fix(opencode): stabilize production OpenAPI docs

[Astro-Han]

Summary

• Share the production Effect ProductionApi between dispatch and OpenAPI documentation.
• Generate the production /doc document from that Effect HttpApi source while retaining the special /event, /global/event, /global/sync-event, and /pty/{ptyID}/connect surfaces.
• Stabilize SSE event schema generation and record the exact checked-in SDK OpenAPI drift that remains against the production source.

Why

The OpenAPI/SDK drift should not be closed from the old Hono documentation tree. This narrows the migration step to the source that production /doc already serves: make that Effect HttpApi source stable and verifiable first, then leave the SDK generator switch for the follow-up that can make the generated SDK types compile.

Related Issue

Related to #936.

Human Review Status

Pending

Review Focus

• ProductionApi is now the single Effect HttpApi declaration shared by production routing and /doc generation.
• Special adapter surfaces stay documented even though they are not ordinary local HttpApi JSON routes.
• AgentConfig zod override schemas and /question removal stay guarded.
• The production event schema no longer depends on incidental handler import order.

Risk Notes

The CLI/SDK generator is intentionally not switched in this PR. Switching it to this production source still needs the session/acp and related Schema.Any route schemas made SDK-ready first; otherwise packages/opencode typecheck goes red. The checked-in SDK spec therefore still trails the production source by the 24 paths asserted in openapi-generation-source.test.ts.

No visible UI or copy changed, so no screenshot was taken. No platform, packaging, updater, signing, path, shell, or permission surface was touched. No generated SDK artifacts were updated.

How To Verify

OpenAPI/control/route tests: 45 passed via bun test test/server/openapi-generation-source.test.ts test/server/control-routes.test.ts test/server/production-boundary.test.ts test/server/route-inventory-harness.test.ts
OpenAPI event regression: 5 passed via bun test test/server/openapi-generation-source.test.ts after the final comment-only touch
opencode typecheck: passed via GOMAXPROCS=2 bun run typecheck from packages/opencode
SDK JS typecheck: passed via bun run typecheck from packages/sdk/js
Diff check: passed via git diff --check from the repository root

Screenshots or Recordings

Not applicable; no visible UI changes.

Checklist

How to use this checklist:

• Tick a box by replacing [ ] with [x]. Do not edit, add, or remove items.
• The bot-applied label items can only be honestly ticked AFTER the PR is opened and the labeler / priority-triage bots have run — return to the PR description and tick them then.
• Most items are required. The few that are conditional are explicitly marked (conditional); for those, leave unticked if they truly do not apply and explain why in Risk Notes. All other items must be ticked before requesting human review.

• Type label — this PR carries exactly one of bug, enhancement, task, documentation. Type labels are author-added; the labeler bot does NOT assign them. Add the label in the GitHub UI, then tick this.
• Routing labels — this PR carries at least one of app, ui, platform, harness, ci. The labeler bot assigns these on PR open based on changed paths. Confirm the bot's choice (or override if wrong), then tick this.
• Priority label — this PR carries exactly one of P0, P1, P2, P3. The priority-triage bot suggests one on PR open. Confirm or override, then tick this.
• Human Review Status above is set to Pending, Approved by @<reviewer>, or Not required: <reason> (default is Pending; "not required" is restricted to bot-authored low-risk PRs).
• I linked the related issue, or stated in Summary why there is no issue.
• I described the review focus and any meaningful risks.
• I replaced the example block in How To Verify with the real verification steps and the key result for each.
• I did not introduce unrelated refactors, dependencies, generated files, or file changes beyond the stated scope.
• (conditional) I manually checked visible UI or copy changes when needed, with screenshots or recordings. Leave unticked only if no visible UI or copy changed.
• (conditional) I considered macOS and Windows impact for platform, packaging, updater, signing, paths, shell, or permissions changes. Leave unticked only if no platform/packaging surface was touched.
• (conditional) I called out docs, release notes, dependencies, permissions, credentials, deletion behavior, generated content, or local file changes when relevant. Leave unticked only if none of those surfaces was touched.
• I reviewed the final diff for unrelated changes and suspicious dependency changes.
• I am targeting dev, and my PR title and commit messages use Conventional Commits in English.

Summary by CodeRabbit

• New Features

  • OpenAPI documentation now includes instance event subscriptions and PTY session connection endpoints.
  • Event schema generation supports selective event type filtering.

• Tests

  • Added test coverage for OpenAPI documentation generation and stability.

[github-actions]

Suggested priority: P2 (includes non-doc, non-test paths outside the low-risk bucket).

P1/P0 are reserved for maintainer confirmation. Please relabel manually if this is a release blocker, security issue, data-loss risk, or updater/runtime failure.

[coderabbitai]

Warning

Review limit reached

@Astro-Han, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 43 minutes and 1 second. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 35551bb1-99d5-464f-be8b-f63924d7d761

📥 Commits

Reviewing files that changed from the base of the PR and between fea6bd5 and c1a4f7b.

📒 Files selected for processing (8)

• packages/opencode/src/bus/bus-event.ts
• packages/opencode/src/server/control-openapi.ts
• packages/opencode/src/server/global-openapi-schema.ts
• packages/opencode/src/server/production-api.ts
• packages/opencode/src/server/production-event-sources.ts
• packages/opencode/src/server/production-httpapi.ts
• packages/opencode/src/sync/index.ts
• packages/opencode/test/server/openapi-generation-source.test.ts

📝 Walkthrough

Walkthrough

BusEvent.payloads and SyncEvent.payloads gain an optional include filter to build discriminated unions from a subset of registered event types. ProductionApi is extracted into its own module. controlOpenApi is rebuilt to source from ProductionApi and adds GET /event (SSE) and GET /pty/{ptyID}/connect path operations with extended schema component merging. A new production-event-sources.ts enumerates the SSE event types used, and a new test suite validates the generation.

Changes

Filtered OpenAPI event schema generation

Layer / File(s)	Summary
Filtered payload schema builders packages/opencode/src/bus/bus-event.ts, packages/opencode/src/sync/index.ts	BusEvent.payloads and SyncEvent.payloads each gain a PayloadOptions type with an optional include iterable; a helper resolves and filters the registry, throwing on unregistered types, before building the Zod discriminated union.
globalEventOpenApiSchema / globalSyncEventOpenApiSchema filtering packages/opencode/src/server/global-openapi-schema.ts	Both schema functions forward optional busEventTypes/syncEventTypes options to the filtered payload builders instead of calling unfiltered payloads().
ProductionApi module extraction and production-httpapi rewiring packages/opencode/src/server/production-api.ts, packages/opencode/src/server/production-httpapi.ts	The HttpApi.make("production").addHttpApi(...) chain is extracted into a new production-api.ts; production-httpapi.ts drops its inline construction and imports ProductionApi from the new module.
Production SSE event type constants packages/opencode/src/server/production-event-sources.ts	New file exports productionBusEventTypes and productionSyncEventTypes as as const arrays enumerating all SSE event type strings for the production server.
controlOpenApi rebuilt around ProductionApi with /event and /pty paths packages/opencode/src/server/control-openapi.ts	Imports updated to use ProductionApi; sortRefUnions helper and workspaceRoutingParameters added; controlOpenApi now clones from ProductionApi, adds GET /event (SSE subscribe) and GET /pty/{ptyID}/connect path operations, and extends component schema merging for instance events, PTY, config, and bad-request schemas.
OpenAPI generation source tests packages/opencode/test/server/openapi-generation-source.test.ts	New Bun test suite asserts ProductionApi reuse, expected and absent route paths, deterministic import-order-independent event schema completeness, Zod config override preservation, and controlled SDK OpenAPI drift.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related PRs

• Astro-Han/pawwork#1398: Modifies the same controlOpenApi() implementation and globalEventOpenApiSchema/globalSyncEventOpenApiSchema functions that this PR extends with filtered payload support.

Suggested labels

upstream, tech-debt

Poem

🐇 Hop hop, the schemas align,
Filtered payloads now combine,
ProductionApi found its home,
SSE paths no longer roam.
/event and /pty appear—
The OpenAPI doc is clear! 🎉

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title "fix(opencode): stabilize production OpenAPI docs" directly describes the main objective of the PR—stabilizing production OpenAPI documentation generation.
Description check	✅ Passed	The PR description follows the template with all required sections completed: Summary, Why, Related Issue, Human Review Status, Review Focus, Risk Notes, How To Verify, and all checklist items properly addressed.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/i936-openapi-sdk-generation

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/opencode/src/server/control-openapi.ts`:
- Around line 145-183: The OpenAPI specification for the "/pty/{ptyID}/connect"
endpoint's GET operation incorrectly documents a 200 response with
application/json content type, but the actual implementation uses WebSocket
upgrade which returns HTTP 101 Switching Protocols instead. Update the responses
section in the get operation to use a 101 response code that reflects the
WebSocket protocol upgrade, removing the application/json schema and replacing
it with appropriate WebSocket upgrade documentation (or an empty/null response
schema since WebSocket connections don't return JSON).

In `@packages/opencode/test/server/openapi-generation-source.test.ts`:
- Around line 107-113: The test function "generates the full production event
schema without import-order dependence" mutates the global BusEvent registry by
calling BusEvent.define() with "test.openapi.leak", and since there is no
teardown mechanism to remove this registration, it contaminates the shared test
runtime and causes order-dependencies for subsequent tests that call
BusEvent.payloads() without filters. To fix this, either add a cleanup/teardown
step that unregisters the event after the test completes, or isolate the
BusEvent.define() mutation by running it in a separate module or process context
so the registration does not leak into other tests in the same test suite
execution.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: cbc3d984-dea0-43e2-a683-0e72261261c0

📥 Commits

Reviewing files that changed from the base of the PR and between e0a6db0 and fea6bd5.

📒 Files selected for processing (8)

• packages/opencode/src/bus/bus-event.ts
• packages/opencode/src/server/control-openapi.ts
• packages/opencode/src/server/global-openapi-schema.ts
• packages/opencode/src/server/production-api.ts
• packages/opencode/src/server/production-event-sources.ts
• packages/opencode/src/server/production-httpapi.ts
• packages/opencode/src/sync/index.ts
• packages/opencode/test/server/openapi-generation-source.test.ts