fix(httpapi): document instance query parameters (#24809)

packages/opencode/src/server/routes/instance/httpapi/pty.ts

@@ -118,7 +118,6 @@ export const PtyConnectApi = HttpApi.make("pty-connect").add(
     .add(
       HttpApiEndpoint.get("connect", PtyPaths.connect, {
         params: Params,
-        query: CursorQuery,
         success: Schema.Boolean,
       }).annotateMerge(
         OpenApi.annotations({

packages/opencode/src/server/routes/instance/httpapi/public.ts

@@ -17,6 +17,56 @@ import { SyncApi } from "./sync"
 import { TuiApi } from "./tui"
 import { WorkspaceApi } from "./workspace"
 
+type OpenApiParameter = {
+  name: string
+  in: string
+  required?: boolean
+  schema?: unknown
+}
+
+type OpenApiOperation = {
+  parameters?: OpenApiParameter[]
+}
+
+type OpenApiPathItem = Partial<Record<"get" | "post" | "put" | "delete" | "patch", OpenApiOperation>>
+
+type OpenApiSpec = {
+  paths?: Record<string, OpenApiPathItem>
+}
+
+const InstanceQueryParameters = [
+  {
+    name: "directory",
+    in: "query",
+    required: false,
+    schema: { type: "string" },
+  },
+  {
+    name: "workspace",
+    in: "query",
+    required: false,
+    schema: { type: "string" },
+  },
+] satisfies OpenApiParameter[]
+
+function documentInstanceQueryParameters(input: Record<string, unknown>) {
+  const spec = input as OpenApiSpec
+  for (const [path, item] of Object.entries(spec.paths ?? {})) {
+    if (path.startsWith("/global/") || path.startsWith("/auth/")) continue
+    for (const method of ["get", "post", "put", "delete", "patch"] as const) {
+      const operation = item[method]
+      if (!operation) continue
+      operation.parameters = [
+        ...InstanceQueryParameters,
+        ...(operation.parameters ?? []).filter(
+          (param) => param.in !== "query" || (param.name !== "directory" && param.name !== "workspace"),
+        ),
+      ]
+    }
+  }
+  return input
+}
+
 export const PublicApi = HttpApi.make("opencode")
   .addHttpApi(ControlApi)
   .addHttpApi(GlobalApi)
@@ -41,5 +91,6 @@ export const PublicApi = HttpApi.make("opencode")
       title: "opencode",
       version: "1.0.0",
       description: "opencode api",
+      transform: documentInstanceQueryParameters,
     }),
   )