feat(server): Server.openapi() backed by HttpApi spec, parity-checked against Hono output (#25545)

packages/opencode/src/cli/cmd/generate.ts

@@ -1,22 +1,28 @@
 import { Server } from "../../server/server"
-import { PublicApi } from "../../server/routes/instance/httpapi/public"
 import type { CommandModule } from "yargs"
-import { OpenApi } from "effect/unstable/httpapi"
 
 type Args = {
   httpapi: boolean
+  hono: boolean
 }
 
 export const GenerateCommand = {
   command: "generate",
   builder: (yargs) =>
-    yargs.option("httpapi", {
-      type: "boolean",
-      default: false,
-      description: "Generate OpenAPI from the experimental Effect HttpApi contract",
-    }),
+    yargs
+      .option("httpapi", {
+        type: "boolean",
+        default: false,
+        description:
+          "Generate OpenAPI from the Effect HttpApi contract (default; flag retained for backwards compatibility)",
+      })
+      .option("hono", {
+        type: "boolean",
+        default: false,
+        description: "Generate OpenAPI from the legacy Hono backend (parity-diff only; will be removed)",
+      }),
   handler: async (args) => {
-    const specs = args.httpapi ? OpenApi.fromApi(PublicApi) : await Server.openapi()
+    const specs = args.hono ? await Server.openapiHono() : await Server.openapi()
     for (const item of Object.values(specs.paths)) {
       for (const method of ["get", "post", "put", "delete", "patch"] as const) {
         const operation = item[method]

packages/opencode/src/server/server.ts

@@ -5,6 +5,7 @@ import { lazy } from "@/util/lazy"
 import * as Log from "@opencode-ai/core/util/log"
 import { Flag } from "@opencode-ai/core/flag/flag"
 import { WorkspaceID } from "@/control-plane/schema"
+import { OpenApi } from "effect/unstable/httpapi"
 import { MDNS } from "./mdns"
 import { AuthMiddleware, CompressionMiddleware, CorsMiddleware, ErrorMiddleware, LoggerMiddleware } from "./middleware"
 import { FenceMiddleware } from "./fence"
@@ -17,6 +18,7 @@ import { WorkspaceRouterMiddleware } from "./workspace"
 import { InstanceMiddleware } from "./routes/instance/middleware"
 import { WorkspaceRoutes } from "./routes/control/workspace"
 import { ExperimentalHttpApiServer } from "./routes/instance/httpapi/server"
+import { PublicApi } from "./routes/instance/httpapi/public"
 import * as ServerBackend from "./backend"
 import type { CorsOptions } from "./cors"
 
@@ -135,7 +137,30 @@ function createHono(opts: CorsOptions, selection: ServerBackend.Selection = Serv
   }
 }
 
+/**
+ * Generate the OpenAPI document used by the SDK build.
+ *
+ * Since the Effect HttpApi backend now covers every Hono route (plus the new
+ * `/api/session/*` v2 routes — see `httpapi-bridge.test.ts` for the parity
+ * audit), `Server.openapi()` derives the spec from `OpenApi.fromApi(PublicApi)`.
+ * `PublicApi` is `OpenCodeHttpApi` annotated with the `matchLegacyOpenApi`
+ * transform that injects instance query parameters, strips Effect's optional
+ * null arms, normalizes component names, and patches SSE response schemas so
+ * the generated SDK keeps the legacy Hono shape.
+ *
+ * The Hono-derived spec is still reachable via `openapiHono()` so reviewers
+ * can diff the two outputs while the Hono backend lingers; once the Hono
+ * backend is deleted that helper goes with it.
+ */
 export async function openapi() {
+  return OpenApi.fromApi(PublicApi)
+}
+
+/**
+ * Hono-derived OpenAPI spec, retained for parity diffing only. Delete once
+ * the Hono backend is removed.
+ */
+export async function openapiHono() {
   // Build a fresh app with all routes registered directly so
   // hono-openapi can see describeRoute metadata (`.route()` wraps
   // handlers when the sub-app has a custom errorHandler, which