fix(opencode): generate SDK OpenAPI from production source

[Astro-Han]

Summary

Switch SDK/OpenAPI generation to the production Effect ProductionApi source and refresh the checked-in OpenAPI plus v2 SDK artifacts.

Why

The SDK generation chain still depended on the legacy Hono documentation tree, leaving checked-in OpenAPI and generated SDK coverage behind the production HTTP boundary. Related to #936.

Related Issue

Related to #936.

Human Review Status

Pending

Review Focus

• Confirm Server.openapi() and bun dev generate now use controlOpenApi() from the production ProductionApi source.
• Review the narrow OpenAPI schema patches for session, automation, memory, artifacts, symbols, VCS failure responses, and special SSE/WebSocket surfaces.
• Confirm generated packages/sdk/openapi.json and v2 SDK artifacts are expected and do not hide drift.

Risk Notes

Residual risk: session.export remains a debug export snapshot without a hand-authored zod schema, so its generated response type is still broad. I did not hand-write that large schema in this PR because it would broaden the migration beyond the SDK generation source closeout. No visible UI changed, and no platform/packaging surface changed.

How To Verify

packages/opencode: bun test test/server/vcs-routes.test.ts test/server/openapi-generation-source.test.ts -> 28 passed
packages/opencode: bun test test/server/openapi-generation-source.test.ts test/server/production-boundary.test.ts test/server/route-inventory-harness.test.ts -> passed before the VCS CI fix
packages/opencode: bun test test/server/production-boundary.test.ts test/server/route-inventory-harness.test.ts -> 34 passed after the VCS CI fix
packages/opencode: bun run route:inventory -> passed; Hono 128, checked-in OpenAPI 125, v2 SDK 124, local HttpApi 122; special surfaces remain classified honestly
packages/sdk/js: bun run build -> passed and regenerated packages/sdk/openapi.json plus v2 SDK artifacts
packages/sdk/js: bun test test/v2-generated-core.test.ts test/v2-client-error-interceptor.test.ts -> 16 passed
packages/opencode: GOMAXPROCS=2 bun run typecheck -> passed
root: bun turbo typecheck -> passed before the VCS CI fix
root: git diff --check -> passed
fresh-eye review: final pre-PR round reported No P0/P1 findings; post-CI-fix VCS round reported No P0-P3 findings and no P0/P1 blockers

Screenshots or Recordings

Not applicable; no visible UI changes.

Checklist

• 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

  • Expanded OpenAPI API documentation generation to include additional routes and comprehensive schema definitions.

• Documentation

  • Enhanced TypeScript type exports in JavaScript SDK for improved type support and better IDE autocompletion.

[coderabbitai]

📝 Walkthrough

Walkthrough

serverOpenApi is renamed to legacyServerOpenApi and controlOpenApi becomes the active production OpenAPI generator. control-openapi.ts gains extensive schema helper utilities and route-patch functions covering session, automation, memory, and additional routes. The SDK build pipeline updates the openapi.json output path, and the JS SDK client exports new public type aliases.

Changes

OpenAPI Schema Expansion and SDK Wiring

Layer / File(s)	Summary
Legacy rename and server wiring to controlOpenApi packages/opencode/src/server/openapi.ts, packages/opencode/src/server/routes/instance/httpapi/groups/session.ts, packages/opencode/src/server/server.ts	serverOpenApi is renamed to legacyServerOpenApi; POST /session gains WorkspaceRoutingQuery; server.ts switches openapi() to dynamically import and return controlOpenApi.
Schema helper utilities and mergeSchemas override packages/opencode/src/server/control-openapi.ts (lines 3–66)	Imports expanded for all source modules; OpenApiDocument.paths loosened to any; mergeSchemas gains an override option; sortRefUnions added for deterministic anyOf ordering.
Schema construction and route-patch helpers packages/opencode/src/server/control-openapi.ts (lines 68–395)	Adds schemaRef, arrayOf, message/JSON wrappers, and mutators for request/response/parameter schemas. Implements patchSessionSchemas, patchAutomationSchemas, memory schema builders with patchMemorySchemas, and patchAdditionalRouteSchemas with custom component builders for project/experimental/file/permission routes.
controlOpenApi Promise.all resolver expansion and schema merging packages/opencode/src/server/control-openapi.ts (lines 415–658)	Pre-built inline schema bodies defined; Promise.all expanded to generate schemas for providers, session info, messages, LSP, automation, todo, and turn-change. All resolved schemas merged with override: true; custom component schemas injected; all patch functions called to wire refs into route operations.
CLI generate command null-safe path iteration packages/opencode/src/cli/cmd/generate.ts	specs.paths ?? {} replaces the unsafe access and removes the ts-expect-error suppression.
SDK build pipeline path update and type exports packages/sdk/js/script/build.ts, packages/sdk/js/src/v2/client.ts	openApiPath resolved to ../openapi.json; post-build openapi.json cleanup removed; FileNode, FileContent, McpStatus, Path, VcsInfo, VcsFileDiff, Command, Agent, LspStatus type aliases added to the JS SDK client.
Test suite updates packages/opencode/test/server/openapi-generation-source.test.ts, packages/opencode/test/server/production-boundary.test.ts, packages/opencode/test/server/pty-routes.test.ts, packages/opencode/test/server/route-inventory-harness.test.ts	Schema-compatibility and path-parity tests replace the drift-documentation test; production boundary assertions updated for legacyServerOpenApi and control-openapi import; pty-routes parameter extraction simplified; route-inventory expectations for /external-result updated to openapi: true and classification: pawwork-owned.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• Astro-Han/pawwork#1398: Directly overlaps control-openapi.ts and server.ts OpenAPI import wiring, including the same /doc production boundary.
• Astro-Han/pawwork#1402: Modifies controlOpenApi() schema generation and path/operation wiring in control-openapi.ts.
• Astro-Han/pawwork#1382: Introduces the experimental worktree routes that this PR adds OpenAPI schema patches for.

Suggested labels

tech-debt

🐇 A hop through schemas wide and deep,
Where anyOf refs now sort in sleep,
controlOpenApi takes the stage,
Each route now typed upon the page—
The legacy path quietly renamed,
And SDK types at last proclaimed! 🎉

🚥 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): generate SDK OpenAPI from production source' clearly and concisely describes the main change—switching SDK/OpenAPI generation to use the production source instead of the legacy Hono tree.
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.
Description check	✅ Passed	The pull request description is comprehensive and follows the required template with all major sections completed.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

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

---

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.}

[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.