openapi.json is incomplete: query parameter directory present, session missing

Description

http://127.0.0.1:4096/doc returns openapi.json

Here is (yaml version) snippet:

  /event:
    get:
      operationId: event.subscribe
      parameters:
        - in: query
          name: directory
          schema:
            type: string
      summary: Subscribe to events
      description: Get events
      responses:
        "200":
          description: Event stream
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/Event'

For event endpoint it declares query parameter directory, no more parameters specified. But it apparently works with session query parameter as follows:

http://127.0.0.1:4096/event?session=ses_480e6a355ffen1k9EXzZLX4Ofk

It would be great to have the openapi.json complete

OpenCode version

v1.0.220

Steps to reproduce

check the openapi.json spec: http://127.0.0.1:4096/doc
read the spec for event endpoint, see only directory is mentioned as query parameter
list sessions http://127.0.0.1:4096/session , pick session id of one of them
use the session id in http://127.0.0.1:4096/event?session=ses_480e6a355ffen1k9EXzZLX4Ofk
do something in opencode terminal in given session
you shall notice, the query to http://127.0.0.1:4096/event?session=ses_480e6a355ffen1k9EXzZLX4Ofk provides new event

$ http GET http://127.0.0.1:4096/doc | yq -P -oy '.paths["/event"].get'

operationId: event.subscribe
parameters:
  - in: query
    name: directory
    schema:
      type: string
summary: Subscribe to events
description: Get events
responses:
  "200":
    description: Event stream
    content:
      text/event-stream:
        schema:
          $ref: '#/components/schemas/Event'

$ http GET http://127.0.0.1:4096/session | jq '.'
[
  {
    "id": "ses_47faebea1ffebgG5b21vgx0Fw1",
    "version": "1.0.220",
    "projectID": "7f065c289c7ea2c062b0cc377bbb7c714d2e8e14",
    "directory": "/Users/javl/devel/ttr/gitlab/personal/honza/try-bmad-v6/sse",
    "parentID": "ses_47fc1b5c1ffeznq1dcr9fJHUY2",
    "title": "Research practical Neovim workflow examples (@explore subagent)",
    "time": {
      "created": 1767384367454,
      "updated": 1767384452040
    },
    "summary": {
      "additions": 0,
      "deletions": 0,
      "files": 0
    }
  },
  {
    "id": "ses_47fb1c28effeF3wIAMEiMuRF3B",
    "version": "1.0.220",
    "projectID": "7f065c289c7ea2c062b0cc377bbb7c714d2e8e14",
    "directory": "/Users/javl/devel/ttr/gitlab/personal/honza/try-bmad-v6/sse",
    "parentID": "ses_47fc1b5c1ffeznq1dcr9fJHUY2",
    "title": "Research workflow automation patterns (@explore subagent)",
    "time": {
      "created": 1767384169841,
      "updated": 1767384183703
    },
    "summary": {
      "additions": 0,
      "deletions": 0,
      "files": 0
    }
  },
  {
    "id": "ses_47fb1d036ffe7CH1EQvqftCn3Z",
    "version": "1.0.220",
    "projectID": "7f065c289c7ea2c062b0cc377bbb7c714d2e8e14",
    "directory": "/Users/javl/devel/ttr/gitlab/personal/honza/try-bmad-v6/sse",
    "parentID": "ses_47fc1b5c1ffeznq1dcr9fJHUY2",
    "title": "Research terminal UI architecture patterns (@explore subagent)",
    "time": {
      "created": 1767384166345,
      "updated": 1767384193412
    },
    "summary": {
      "additions": 0,
      "deletions": 0,
      "files": 0
    }
  },
  {
    "id": "ses_47fb63573ffeMMB1rt3ow1F8y7",
    "version": "1.0.220",
    "projectID": "7f065c289c7ea2c062b0cc377bbb7c714d2e8e14",
    "directory": "/Users/javl/devel/ttr/gitlab/personal/honza/try-bmad-v6/sse",
    "parentID": "ses_47fc1b5c1ffeznq1dcr9fJHUY2",
    "title": "Research Neovim RPC and automation patterns (@explore subagent)",
    "time": {
      "created": 1767383878284,
      "updated": 1767383900029
    },
    "summary": {
      "additions": 0,
      "deletions": 0,
      "files": 0
    }
  },
  {
    "id": "ses_47fb64448ffe00OM69KiqcDltt",
    "version": "1.0.220",
    "projectID": "7f065c289c7ea2c062b0cc377bbb7c714d2e8e14",
    "directory": "/Users/javl/devel/ttr/gitlab/personal/honza/try-bmad-v6/sse",
    "parentID": "ses_47fc1b5c1ffeznq1dcr9fJHUY2",
    "title": "Research file-based IPC patterns (@explore subagent)",
    "time": {
      "created": 1767383874487,
      "updated": 1767383970104
    },
    "summary": {
      "additions": 0,
      "deletions": 0,
      "files": 0
    }
  },
  {
    "id": "ses_47fb65083ffey9jup7R6Pezhk7",
    "version": "1.0.220",
    "projectID": "7f065c289c7ea2c062b0cc377bbb7c714d2e8e14",
    "directory": "/Users/javl/devel/ttr/gitlab/personal/honza/try-bmad-v6/sse",
    "parentID": "ses_47fc1b5c1ffeznq1dcr9fJHUY2",
    "title": "Research OpenCode API patterns (@explore subagent)",
    "time": {
      "created": 1767383871356,
      "updated": 1767383971786
    },
    "summary": {
      "additions": 0,
      "deletions": 0,
      "files": 0
    }
  },
  {
    "id": "ses_47fba14a2ffeFJ6pTr2UYbDXii",
    "version": "1.0.220",
    "projectID": "7f065c289c7ea2c062b0cc377bbb7c714d2e8e14",
    "directory": "/Users/javl/devel/ttr/gitlab/personal/honza/try-bmad-v6/sse",
    "parentID": "ses_47fc1b5c1ffeznq1dcr9fJHUY2",
    "title": "Research terminal multiplexers and file watchers (@explore subagent)",
    "time": {
      "created": 1767383624541,
      "updated": 1767383699911
    },
    "summary": {
      "additions": 0,
      "deletions": 0,
      "files": 0
    }
  },
  {
    "id": "ses_47fba1ffdffeuiVo77eeIK1zIZ",
    "version": "1.0.220",
    "projectID": "7f065c289c7ea2c062b0cc377bbb7c714d2e8e14",
    "directory": "/Users/javl/devel/ttr/gitlab/personal/honza/try-bmad-v6/sse",
    "parentID": "ses_47fc1b5c1ffeznq1dcr9fJHUY2",
    "title": "Research Neovim plugin ecosystem (@explore subagent)",
    "time": {
      "created": 1767383621634,
      "updated": 1767383691290
    },
    "summary": {
      "additions": 0,
      "deletions": 0,
      "files": 0
    }
  },
  {
    "id": "ses_47fc1b5c1ffeznq1dcr9fJHUY2",
    "version": "1.0.220",
    "projectID": "7f065c289c7ea2c062b0cc377bbb7c714d2e8e14",
    "directory": "/Users/javl/devel/ttr/gitlab/personal/honza/try-bmad-v6/sse",
    "title": "Research workflow setup guide",
    "time": {
      "created": 1767383124542,
      "updated": 1767385202245
    },
    "summary": {
      "additions": 2151,
      "deletions": 0,
      "files": 1
    }
  },
  {
    "id": "ses_480dc889effeOMPLge4iiKR3qL",
    "version": "1.0.220",
    "projectID": "7f065c289c7ea2c062b0cc377bbb7c714d2e8e14",
    "directory": "/Users/javl/devel/ttr/gitlab/personal/honza/try-bmad-v6/sse",
    "title": "Workflow-init setup",
    "time": {
      "created": 1767364589409,
      "updated": 1767365852250
    },
    "summary": {
      "additions": 0,
      "deletions": 0,
      "files": 0
    }
  },
  {
    "id": "ses_480e6a355ffen1k9EXzZLX4Ofk",
    "version": "1.0.220",
    "projectID": "7f065c289c7ea2c062b0cc377bbb7c714d2e8e14",
    "directory": "/Users/javl/devel/ttr/gitlab/personal/honza/try-bmad-v6/sse",
    "title": "OpenCode Server-Sent Events API",
    "time": {
      "created": 1767363927210,
      "updated": 1767382518526
    },
    "summary": {
      "additions": 0,
      "deletions": 0,
      "files": 0
    }
  }
]

$ http --stream GET 'http://127.0.0.1:4096/event?session=ses_480e6a355ffen1k9EXzZLX4Ofk'
HTTP/1.1 200 OK
Cache-Control: no-cache
Connection: keep-alive
Content-Type: text/event-stream
Date: Fri, 02 Jan 2026 20:44:15 GMT
Transfer-Encoding: chunked
Vary: Origin

data: {
    "properties": {},
    "type": "server.connected"
}

^C

$ http GET http://127.0.0.1:4096/doc | yq -P -oy '.paths["/event"].get.parameters'
- in: query
  name: directory
  schema:
    type: string

Screenshot and/or share link

No response

Operating System

macOS 25.1.0

Terminal

Ghostty

I’d like to work on this issue. I’ll investigate and open a PR.

Quick research update after digging in locally:

I can reproduce this on current dev. /doc shows GET /event with only directory, while GET /event?session=<id> still returns 200 and opens SSE.

Root cause appears to be in packages/opencode/src/server/server.ts:

query validation is defined as z.object({ directory: z.string().optional() })
/event OpenAPI route metadata does not define a session parameter
the handler uses Bus.subscribeAll(...) and does not read session from query

So session is effectively accepted/ignored at runtime, but not represented in the OpenAPI contract.

Plan:

add session to the /event OpenAPI query params,
align route query schema/behavior with intended session semantics,
add regression coverage for /doc and regenerate SDK artifacts if needed.

If this direction looks good, I’ll open a PR.

Implemented in #15028.

What I changed:

Added /event query validation for both optional params: directory and session.
Added regression tests in packages/opencode/test/server/event-openapi.test.ts to verify:
- OpenAPI documents /event query params as directory + session
- SSE still returns 200 + text/event-stream with ?session=...
- SSE still returns 200 + text/event-stream without session
Regenerated SDK artifacts so session?: string is reflected in generated client types (v2 + root SDK typing).

Why this change:

Runtime already accepted ?session=<id> and opened SSE, but the OpenAPI contract and SDK typing did not expose session.
This creates contract drift and missing client typing.
This fix aligns contract + generated SDK with existing behavior, without changing stream filtering semantics in this issue.

To stay organized issues are automatically closed after 60 days of no activity. If the issue is still relevant please open a new one.

Navigation Menu

Repository navigation

openapi.json is incomplete: query parameter directory present, session missing #6686

Description

OpenCode version

Steps to reproduce

Screenshot and/or share link

Operating System

Terminal

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

openapi.json is incomplete: query parameter directory present, session missing #6686

Description

Description

OpenCode version

Steps to reproduce

Screenshot and/or share link

Operating System

Terminal

Activity

phongndo commented on Feb 23, 2026

phongndo commented on Feb 23, 2026

phongndo commented on Feb 25, 2026

github-actions commented on Apr 27, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions