chore: rework openapi spec and use stainless sdk

packages/opencode/AGENTS.md

@@ -7,7 +7,6 @@
 - **Typecheck**: `bun run typecheck` (npm run typecheck)
 - **Test**: `bun test` (runs all tests)
 - **Single test**: `bun test test/tool/tool.test.ts` (specific test file)
-- **API Client Generation**: `cd packages/tui && go generate ./pkg/client/` (after changes to server endpoints)
 
 ## Code Style
 
@@ -38,4 +37,4 @@
 - **Validation**: All inputs validated with Zod schemas
 - **Logging**: Use `Log.create({ service: "name" })` pattern
 - **Storage**: Use `Storage` namespace for persistence
-- **API Client**: Go TUI communicates with TypeScript server via generated client. When adding/modifying server endpoints in `packages/opencode/src/server/server.ts`, run `cd packages/tui && go generate ./pkg/client/` to update the Go client code and OpenAPI spec.
+- **API Client**: Go TUI communicates with TypeScript server via stainless SDK. When adding/modifying server endpoints in `packages/opencode/src/server/server.ts`, ask the user to generate a new client SDK to proceed with client-side changes.

packages/opencode/src/app/app.ts

@@ -27,7 +27,7 @@ export namespace App {
       }),
     })
     .openapi({
-      ref: "App.Info",
+      ref: "App",
     })
   export type Info = z.infer<typeof Info>
 

packages/opencode/src/config/config.ts

@@ -40,7 +40,7 @@ export namespace Config {
     })
     .strict()
     .openapi({
-      ref: "Config.McpLocal",
+      ref: "McpLocalConfig",
     })
 
   export const McpRemote = z
@@ -50,7 +50,7 @@ export namespace Config {
     })
     .strict()
     .openapi({
-      ref: "Config.McpRemote",
+      ref: "McpRemoteConfig",
     })
 
   export const Mcp = z.discriminatedUnion("type", [McpLocal, McpRemote])
@@ -124,7 +124,7 @@ export namespace Config {
     })
     .strict()
     .openapi({
-      ref: "Config.Keybinds",
+      ref: "KeybindsConfig",
     })
   export const Info = z
     .object({
@@ -197,7 +197,7 @@ export namespace Config {
     })
     .strict()
     .openapi({
-      ref: "Config.Info",
+      ref: "Config",
     })
 
   export type Info = z.output<typeof Info>

packages/opencode/src/provider/models.ts

@@ -29,7 +29,7 @@ export namespace ModelsDev {
       options: z.record(z.any()),
     })
     .openapi({
-      ref: "Model.Info",
+      ref: "Model",
     })
   export type Model = z.infer<typeof Model>
 
@@ -43,7 +43,7 @@ export namespace ModelsDev {
       models: z.record(Model),
     })
     .openapi({
-      ref: "Provider.Info",
+      ref: "Provider",
     })
 
   export type Provider = z.infer<typeof Provider>

packages/opencode/src/server/server.ts

@@ -9,12 +9,10 @@ import { z } from "zod"
 import { Message } from "../session/message"
 import { Provider } from "../provider/provider"
 import { App } from "../app/app"
-import { Global } from "../global"
 import { mapValues } from "remeda"
 import { NamedError } from "../util/error"
 import { ModelsDev } from "../provider/models"
 import { Ripgrep } from "../external/ripgrep"
-import { Installation } from "../installation"
 import { Config } from "../config/config"
 
 const ERRORS = {
@@ -70,12 +68,12 @@ export namespace Server {
         })
       })
       .get(
-        "/openapi",
+        "/doc",
         openAPISpecs(app, {
           documentation: {
             info: {
               title: "opencode",
-              version: "1.0.0",
+              version: "0.0.2",
               description: "opencode api",
             },
             openapi: "3.0.0",
@@ -122,8 +120,8 @@ export namespace Server {
           })
         },
       )
-      .post(
-        "/app_info",
+      .get(
+        "/app",
         describeRoute({
           description: "Get app info",
           responses: {
@@ -142,26 +140,7 @@ export namespace Server {
         },
       )
       .post(
-        "/config_get",
-        describeRoute({
-          description: "Get config info",
-          responses: {
-            200: {
-              description: "Get config info",
-              content: {
-                "application/json": {
-                  schema: resolver(Config.Info),
-                },
-              },
-            },
-          },
-        }),
-        async (c) => {
-          return c.json(await Config.get())
-        },
-      )
-      .post(
-        "/app_initialize",
+        "/app/init",
         describeRoute({
           description: "Initialize the app",
           responses: {
@@ -180,172 +159,27 @@ export namespace Server {
           return c.json(true)
         },
       )
-      .post(
-        "/session_initialize",
+      .get(
+        "/config",
         describeRoute({
-          description: "Analyze the app and create an AGENTS.md file",
+          description: "Get config info",
           responses: {
             200: {
-              description: "200",
+              description: "Get config info",
               content: {
                 "application/json": {
-                  schema: resolver(z.boolean()),
-                },
-              },
-            },
-          },
-        }),
-        zValidator(
-          "json",
-          z.object({
-            sessionID: z.string(),
-            providerID: z.string(),
-            modelID: z.string(),
-          }),
-        ),
-        async (c) => {
-          const body = c.req.valid("json")
-          await Session.initialize(body)
-          return c.json(true)
-        },
-      )
-      .post(
-        "/path_get",
-        describeRoute({
-          description: "Get paths",
-          responses: {
-            200: {
-              description: "200",
-              content: {
-                "application/json": {
-                  schema: resolver(
-                    z.object({
-                      root: z.string(),
-                      data: z.string(),
-                      cwd: z.string(),
-                      config: z.string(),
-                    }),
-                  ),
+                  schema: resolver(Config.Info),
                 },
               },
             },
           },
         }),
         async (c) => {
-          const app = App.info()
-          return c.json({
-            root: app.path.root,
-            data: app.path.data,
-            cwd: app.path.cwd,
-            config: Global.Path.data,
-          })
+          return c.json(await Config.get())
         },
       )
-      .post(
-        "/session_create",
-        describeRoute({
-          description: "Create a new session",
-          responses: {
-            ...ERRORS,
-            200: {
-              description: "Successfully created session",
-              content: {
-                "application/json": {
-                  schema: resolver(Session.Info),
-                },
-              },
-            },
-          },
-        }),
-        async (c) => {
-          const session = await Session.create()
-          return c.json(session)
-        },
-      )
-      .post(
-        "/session_share",
-        describeRoute({
-          description: "Share the session",
-          responses: {
-            200: {
-              description: "Successfully shared session",
-              content: {
-                "application/json": {
-                  schema: resolver(Session.Info),
-                },
-              },
-            },
-          },
-        }),
-        zValidator(
-          "json",
-          z.object({
-            sessionID: z.string(),
-          }),
-        ),
-        async (c) => {
-          const body = c.req.valid("json")
-          await Session.share(body.sessionID)
-          const session = await Session.get(body.sessionID)
-          return c.json(session)
-        },
-      )
-      .post(
-        "/session_unshare",
-        describeRoute({
-          description: "Unshare the session",
-          responses: {
-            200: {
-              description: "Successfully unshared session",
-              content: {
-                "application/json": {
-                  schema: resolver(Session.Info),
-                },
-              },
-            },
-          },
-        }),
-        zValidator(
-          "json",
-          z.object({
-            sessionID: z.string(),
-          }),
-        ),
-        async (c) => {
-          const body = c.req.valid("json")
-          await Session.unshare(body.sessionID)
-          const session = await Session.get(body.sessionID)
-          return c.json(session)
-        },
-      )
-      .post(
-        "/session_messages",
-        describeRoute({
-          description: "Get messages for a session",
-          responses: {
-            200: {
-              description: "Successfully created session",
-              content: {
-                "application/json": {
-                  schema: resolver(Message.Info.array()),
-                },
-              },
-            },
-          },
-        }),
-        zValidator(
-          "json",
-          z.object({
-            sessionID: z.string(),
-          }),
-        ),
-        async (c) => {
-          const messages = await Session.messages(c.req.valid("json").sessionID)
-          return c.json(messages)
-        },
-      )
-      .post(
-        "/session_list",
+      .get(
+        "/session",
         describeRoute({
           description: "List all sessions",
           responses: {
@@ -365,33 +199,28 @@ export namespace Server {
         },
       )
       .post(
-        "/session_abort",
+        "/session",
         describeRoute({
-          description: "Abort a session",
+          description: "Create a new session",
           responses: {
+            ...ERRORS,
             200: {
-              description: "Aborted session",
+              description: "Successfully created session",
               content: {
                 "application/json": {
-                  schema: resolver(z.boolean()),
+                  schema: resolver(Session.Info),
                 },
               },
             },
           },
         }),
-        zValidator(
-          "json",
-          z.object({
-            sessionID: z.string(),
-          }),
-        ),
         async (c) => {
-          const body = c.req.valid("json")
-          return c.json(Session.abort(body.sessionID))
+          const session = await Session.create()
+          return c.json(session)
         },
       )
-      .post(
-        "/session_delete",
+      .delete(
+        "/session/:id",
         describeRoute({
           description: "Delete a session and all its data",
           responses: {
@@ -406,24 +235,23 @@ export namespace Server {
           },
         }),
         zValidator(
-          "json",
+          "param",
           z.object({
-            sessionID: z.string(),
+            id: z.string(),
           }),
         ),
         async (c) => {
-          const body = c.req.valid("json")
-          await Session.remove(body.sessionID)
+          await Session.remove(c.req.valid("param").id)
           return c.json(true)
         },
       )
       .post(
-        "/session_summarize",
+        "/session/:id/init",
         describeRoute({
-          description: "Summarize the session",
+          description: "Analyze the app and create an AGENTS.md file",
           responses: {
             200: {
-              description: "Summarize the session",
+              description: "200",
               content: {
                 "application/json": {
                   schema: resolver(z.boolean()),
@@ -432,27 +260,175 @@ export namespace Server {
             },
           },
         }),
+        zValidator(
+          "param",
+          z.object({
+            id: z.string().openapi({ description: "Session ID" }),
+          }),
+        ),
         zValidator(
           "json",
           z.object({
-            sessionID: z.string(),
             providerID: z.string(),
             modelID: z.string(),
           }),
         ),
         async (c) => {
+          const sessionID = c.req.valid("param").id
           const body = c.req.valid("json")
-          await Session.summarize(body)
+          await Session.initialize({ ...body, sessionID })
           return c.json(true)
         },
       )
       .post(
-        "/session_chat",
+        "/session/:id/abort",
         describeRoute({
-          description: "Chat with a model",
+          description: "Abort a session",
           responses: {
             200: {
-              description: "Chat with a model",
+              description: "Aborted session",
+              content: {
+                "application/json": {
+                  schema: resolver(z.boolean()),
+                },
+              },
+            },
+          },
+        }),
+        zValidator(
+          "param",
+          z.object({
+            id: z.string(),
+          }),
+        ),
+        async (c) => {
+          return c.json(Session.abort(c.req.valid("param").id))
+        },
+      )
+      .post(
+        "/session/:id/share",
+        describeRoute({
+          description: "Share a session",
+          responses: {
+            200: {
+              description: "Successfully shared session",
+              content: {
+                "application/json": {
+                  schema: resolver(Session.Info),
+                },
+              },
+            },
+          },
+        }),
+        zValidator(
+          "param",
+          z.object({
+            id: z.string(),
+          }),
+        ),
+        async (c) => {
+          const id = c.req.valid("param").id
+          await Session.share(id)
+          const session = await Session.get(id)
+          return c.json(session)
+        },
+      )
+      .delete(
+        "/session/:id/share",
+        describeRoute({
+          description: "Unshare the session",
+          responses: {
+            200: {
+              description: "Successfully unshared session",
+              content: {
+                "application/json": {
+                  schema: resolver(Session.Info),
+                },
+              },
+            },
+          },
+        }),
+        zValidator(
+          "param",
+          z.object({
+            id: z.string(),
+          }),
+        ),
+        async (c) => {
+          const id = c.req.valid("param").id
+          await Session.unshare(id)
+          const session = await Session.get(id)
+          return c.json(session)
+        },
+      )
+      .post(
+        "/session/:id/summarize",
+        describeRoute({
+          description: "Summarize the session",
+          responses: {
+            200: {
+              description: "Summarized session",
+              content: {
+                "application/json": {
+                  schema: resolver(z.boolean()),
+                },
+              },
+            },
+          },
+        }),
+        zValidator(
+          "param",
+          z.object({
+            id: z.string().openapi({ description: "Session ID" }),
+          }),
+        ),
+        zValidator(
+          "json",
+          z.object({
+            providerID: z.string(),
+            modelID: z.string(),
+          }),
+        ),
+        async (c) => {
+          const id = c.req.valid("param").id
+          const body = c.req.valid("json")
+          await Session.summarize({ ...body, sessionID: id })
+          return c.json(true)
+        },
+      )
+      .get(
+        "/session/:id/message",
+        describeRoute({
+          description: "List messages for a session",
+          responses: {
+            200: {
+              description: "List of messages",
+              content: {
+                "application/json": {
+                  schema: resolver(Message.Info.array()),
+                },
+              },
+            },
+          },
+        }),
+        zValidator(
+          "param",
+          z.object({
+            id: z.string().openapi({ description: "Session ID" }),
+          }),
+        ),
+        async (c) => {
+          const messages = await Session.messages(c.req.valid("param").id)
+          return c.json(messages)
+        },
+      )
+      .post(
+        "/session/:id/message",
+        describeRoute({
+          description: "Create and send a new message to a session",
+          responses: {
+            200: {
+              description: "Created message",
               content: {
                 "application/json": {
                   schema: resolver(Message.Info),
@@ -461,23 +437,29 @@ export namespace Server {
             },
           },
         }),
+        zValidator(
+          "param",
+          z.object({
+            id: z.string().openapi({ description: "Session ID" }),
+          }),
+        ),
         zValidator(
           "json",
           z.object({
-            sessionID: z.string(),
             providerID: z.string(),
             modelID: z.string(),
-            parts: Message.Part.array(),
+            parts: Message.MessagePart.array(),
           }),
         ),
         async (c) => {
+          const sessionID = c.req.valid("param").id
           const body = c.req.valid("json")
-          const msg = await Session.chat(body)
+          const msg = await Session.chat({ ...body, sessionID })
           return c.json(msg)
         },
       )
-      .post(
-        "/provider_list",
+      .get(
+        "/config/providers",
         describeRoute({
           description: "List all providers",
           responses: {
@@ -509,8 +491,8 @@ export namespace Server {
           })
         },
       )
-      .post(
-        "/file_search",
+      .get(
+        "/file",
         describeRoute({
           description: "Search for files",
           responses: {
@@ -525,41 +507,22 @@ export namespace Server {
           },
         }),
         zValidator(
-          "json",
+          "query",
           z.object({
             query: z.string(),
           }),
         ),
         async (c) => {
-          const body = c.req.valid("json")
+          const query = c.req.valid("query").query
           const app = App.info()
           const result = await Ripgrep.files({
             cwd: app.path.cwd,
-            query: body.query,
+            query,
             limit: 10,
           })
           return c.json(result)
         },
       )
-      .post(
-        "installation_info",
-        describeRoute({
-          description: "Get installation info",
-          responses: {
-            200: {
-              description: "Get installation info",
-              content: {
-                "application/json": {
-                  schema: resolver(Installation.Info),
-                },
-              },
-            },
-          },
-        }),
-        async (c) => {
-          return c.json(Installation.info())
-        },
-      )
 
     return result
   }

packages/opencode/src/session/index.ts

@@ -55,14 +55,18 @@ export namespace Session {
       }),
     })
     .openapi({
-      ref: "session.info",
+      ref: "Session",
     })
   export type Info = z.output<typeof Info>
 
-  export const ShareInfo = z.object({
-    secret: z.string(),
-    url: z.string(),
-  })
+  export const ShareInfo = z
+    .object({
+      secret: z.string(),
+      url: z.string(),
+    })
+    .openapi({
+      ref: "SessionShare",
+    })
   export type ShareInfo = z.output<typeof ShareInfo>
 
   export const Event = {
@@ -273,7 +277,7 @@ export namespace Session {
     sessionID: string
     providerID: string
     modelID: string
-    parts: Message.Part[]
+    parts: Message.MessagePart[]
     system?: string[]
     tools?: Tool.Info[]
   }) {
@@ -951,7 +955,7 @@ function toUIMessage(msg: Message.Info): UIMessage {
   throw new Error("not implemented")
 }
 
-function toParts(parts: Message.Part[]): UIMessage["parts"] {
+function toParts(parts: Message.MessagePart[]): UIMessage["parts"] {
   const result: UIMessage["parts"] = []
   for (const part of parts) {
     switch (part.type) {

packages/opencode/src/session/message.ts

@@ -18,7 +18,7 @@ export namespace Message {
       args: z.custom<Required<unknown>>(),
     })
     .openapi({
-      ref: "Message.ToolInvocation.ToolCall",
+      ref: "ToolCall",
     })
   export type ToolCall = z.infer<typeof ToolCall>
 
@@ -31,7 +31,7 @@ export namespace Message {
       args: z.custom<Required<unknown>>(),
     })
     .openapi({
-      ref: "Message.ToolInvocation.ToolPartialCall",
+      ref: "ToolPartialCall",
     })
   export type ToolPartialCall = z.infer<typeof ToolPartialCall>
 
@@ -45,14 +45,14 @@ export namespace Message {
       result: z.string(),
     })
     .openapi({
-      ref: "Message.ToolInvocation.ToolResult",
+      ref: "ToolResult",
     })
   export type ToolResult = z.infer<typeof ToolResult>
 
   export const ToolInvocation = z
     .discriminatedUnion("state", [ToolCall, ToolPartialCall, ToolResult])
     .openapi({
-      ref: "Message.ToolInvocation",
+      ref: "ToolInvocation",
     })
   export type ToolInvocation = z.infer<typeof ToolInvocation>
 
@@ -62,7 +62,7 @@ export namespace Message {
       text: z.string(),
     })
     .openapi({
-      ref: "Message.Part.Text",
+      ref: "TextPart",
     })
   export type TextPart = z.infer<typeof TextPart>
 
@@ -73,7 +73,7 @@ export namespace Message {
       providerMetadata: z.record(z.any()).optional(),
     })
     .openapi({
-      ref: "Message.Part.Reasoning",
+      ref: "ReasoningPart",
     })
   export type ReasoningPart = z.infer<typeof ReasoningPart>
 
@@ -83,7 +83,7 @@ export namespace Message {
       toolInvocation: ToolInvocation,
     })
     .openapi({
-      ref: "Message.Part.ToolInvocation",
+      ref: "ToolInvocationPart",
     })
   export type ToolInvocationPart = z.infer<typeof ToolInvocationPart>
 
@@ -96,7 +96,7 @@ export namespace Message {
       providerMetadata: z.record(z.any()).optional(),
     })
     .openapi({
-      ref: "Message.Part.SourceUrl",
+      ref: "SourceUrlPart",
     })
   export type SourceUrlPart = z.infer<typeof SourceUrlPart>
 
@@ -108,7 +108,7 @@ export namespace Message {
       url: z.string(),
     })
     .openapi({
-      ref: "Message.Part.File",
+      ref: "FilePart",
     })
   export type FilePart = z.infer<typeof FilePart>
 
@@ -117,11 +117,11 @@ export namespace Message {
       type: z.literal("step-start"),
     })
     .openapi({
-      ref: "Message.Part.StepStart",
+      ref: "StepStartPart",
     })
   export type StepStartPart = z.infer<typeof StepStartPart>
 
-  export const Part = z
+  export const MessagePart = z
     .discriminatedUnion("type", [
       TextPart,
       ReasoningPart,
@@ -131,15 +131,15 @@ export namespace Message {
       StepStartPart,
     ])
     .openapi({
-      ref: "Message.Part",
+      ref: "MessagePart",
     })
-  export type Part = z.infer<typeof Part>
+  export type MessagePart = z.infer<typeof MessagePart>
 
   export const Info = z
     .object({
       id: z.string(),
       role: z.enum(["user", "assistant"]),
-      parts: z.array(Part),
+      parts: z.array(MessagePart),
       metadata: z
         .object({
           time: z.object({
@@ -189,10 +189,10 @@ export namespace Message {
             })
             .optional(),
         })
-        .openapi({ ref: "Message.Metadata" }),
+        .openapi({ ref: "MessageMetadata" }),
     })
     .openapi({
-      ref: "Message.Info",
+      ref: "Message",
     })
   export type Info = z.infer<typeof Info>
 
@@ -205,7 +205,11 @@ export namespace Message {
     ),
     PartUpdated: Bus.event(
       "message.part.updated",
-      z.object({ part: Part, sessionID: z.string(), messageID: z.string() }),
+      z.object({
+        part: MessagePart,
+        sessionID: z.string(),
+        messageID: z.string(),
+      }),
     ),
   }
 }