docs: add sdk doc

.opencode/agent/docs.md

@@ -24,3 +24,6 @@ example, if the page title is "Models", avoid using a section title like "Add
 new models". This might be unavoidable in some cases, but try to avoid it.
 
 Check out the /packages/web/src/content/docs/docs/index.mdx as an example.
+
+For JS or TS code snippets remove trailing semicolons and any trailing commas
+that might not be needed.

packages/web/astro.config.mjs

@@ -67,13 +67,7 @@ export default defineConfig({
 
         {
           label: "Usage",
-          items: [
-            "docs/tui",
-            "docs/cli",
-            "docs/ide",
-            "docs/share",
-            "docs/github"
-          ],
+          items: ["docs/tui", "docs/cli", "docs/ide", "docs/share", "docs/github"],
         },
 
         {
@@ -93,10 +87,7 @@ export default defineConfig({
 
         {
           label: "Develop",
-          items: [
-            "docs/server",
-            "docs/plugins",
-          ],
+          items: ["docs/sdk", "docs/server", "docs/plugins"],
         },
       ],
       components: {

packages/web/src/content/docs/docs/cli.mdx

@@ -176,7 +176,7 @@ opencode run Explain the use of context in Go
 
 ### serve
 
-Start a headless opencode server for API access. See [Server API](/docs/server) for the full HTTP interface.
+Start a headless opencode server for API access. Check out the [server docs](/docs/server) for the full HTTP interface.
 
 ```bash
 opencode serve

packages/web/src/content/docs/docs/sdk.mdx

@@ -0,0 +1,300 @@
+---
+title: SDK
+description: JS SDK for the opencode server.
+---
+
+import config from "../../../../config.mjs"
+export const typesUrl = `${config.github}/blob/dev/packages/sdk/js/src/gen/types.gen.ts`
+
+The opencode [JS/TS SDK](https://www.npmjs.com/package/@opencode-ai/sdk) provides a type-safe client for interacting with the opencode server. You can use it to build custom integrations and control opencode programmatically.
+
+---
+
+## Install
+
+Install the SDK from npm:
+
+```bash
+npm install @opencode-ai/sdk
+```
+
+---
+
+## Create client
+
+Create a client instance to connect to your opencode server:
+
+```javascript
+import { createOpencodeClient } from "@opencode-ai/sdk"
+
+const client = createOpencodeClient({
+  baseUrl: "http://localhost:4096",
+})
+```
+
+#### Options
+
+| Option    | Type       | Description                 | Default                 |
+| --------- | ---------- | --------------------------- | ----------------------- |
+| `baseUrl` | `string`   | URL of the opencode server  | `http://localhost:4096` |
+| `fetch`   | `function` | Custom fetch implementation | `globalThis.fetch`      |
+
+---
+
+## Start server
+
+You can also programmatically start an opencode server:
+
+```javascript
+import { createOpencodeServer } from "@opencode-ai/sdk"
+
+const server = await createOpencodeServer({
+  host: "127.0.0.1",
+  port: 4096,
+})
+
+console.log(`Server running at ${server.url}`)
+
+server.close()
+```
+
+---
+
+## Types
+
+The SDK includes TypeScript definitions for all API types. Import them directly:
+
+```typescript
+import type { Session, Message, Part } from "@opencode-ai/sdk"
+```
+
+All types are generated from the server's OpenAPI specification and available in the <a href={typesUrl}>types file</a>.
+
+---
+
+## APIs
+
+The SDK exposes all server APIs through a type-safe client interface.
+
+---
+
+### App
+
+| Method       | Description        | Response                                |
+| ------------ | ------------------ | --------------------------------------- |
+| `app.get()`  | Get app info       | <a href={typesUrl}><code>App</code></a> |
+| `app.init()` | Initialize the app | `boolean`                               |
+
+---
+
+#### Examples
+
+```javascript
+const app = await client.app.get()
+await client.app.init()
+```
+
+---
+
+### Config
+
+| Method               | Description                       | Response                                                                                              |
+| -------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `config.get()`       | Get config info                   | <a href={typesUrl}><code>Config</code></a>                                                            |
+| `config.providers()` | List providers and default models | `{ providers: `<a href={typesUrl}><code>Provider[]</code></a>`, default: { [key: string]: string } }` |
+
+---
+
+#### Examples
+
+```javascript
+const config = await client.config.get()
+const { providers, default: defaults } = await client.config.providers()
+```
+
+---
+
+### Sessions
+
+| Method                                                        | Description                        | Notes                                                                                                                   |
+| ------------------------------------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `session.list()`                                              | List sessions                      | Returns <a href={typesUrl}><code>Session[]</code></a>                                                                   |
+| `session.get({ id })`                                         | Get session                        | Returns <a href={typesUrl}><code>Session</code></a>                                                                     |
+| `session.children({ id })`                                    | List child sessions                | Returns <a href={typesUrl}><code>Session[]</code></a>                                                                   |
+| `session.create({ parentID?, title? })`                       | Create session                     | Returns <a href={typesUrl}><code>Session</code></a>                                                                     |
+| `session.delete({ id })`                                      | Delete session                     | Returns `boolean`                                                                                                       |
+| `session.update({ id, title? })`                              | Update session properties          | Returns <a href={typesUrl}><code>Session</code></a>                                                                     |
+| `session.init({ id, messageID, providerID, modelID })`        | Analyze app and create `AGENTS.md` | Returns `boolean`                                                                                                       |
+| `session.abort({ id })`                                       | Abort a running session            | Returns `boolean`                                                                                                       |
+| `session.share({ id })`                                       | Share session                      | Returns <a href={typesUrl}><code>Session</code></a>                                                                     |
+| `session.unshare({ id })`                                     | Unshare session                    | Returns <a href={typesUrl}><code>Session</code></a>                                                                     |
+| `session.summarize({ id, providerID, modelID })`              | Summarize session                  | Returns `boolean`                                                                                                       |
+| `session.messages({ id })`                                    | List messages in a session         | Returns `{ info: `<a href={typesUrl}><code>Message</code></a>`, parts: `<a href={typesUrl}><code>Part[]</code></a>`}[]` |
+| `session.message({ id, messageID })`                          | Get message details                | Returns `{ info: `<a href={typesUrl}><code>Message</code></a>`, parts: `<a href={typesUrl}><code>Part[]</code></a>`}`   |
+| `session.chat({ id, ...chatInput })`                          | Send chat message                  | Returns <a href={typesUrl}><code>Message</code></a>                                                                     |
+| `session.shell({ id, agent, command })`                       | Run a shell command                | Returns <a href={typesUrl}><code>Message</code></a>                                                                     |
+| `session.revert({ id, messageID, partID? })`                  | Revert a message                   | Returns <a href={typesUrl}><code>Session</code></a>                                                                     |
+| `session.unrevert({ id })`                                    | Restore reverted messages          | Returns <a href={typesUrl}><code>Session</code></a>                                                                     |
+| `session.permissions.respond({ id, permissionID, response })` | Respond to a permission request    | Returns `boolean`                                                                                                       |
+
+---
+
+#### Examples
+
+```javascript
+// Create and manage sessions
+const session = await client.session.create({ title: "My session" })
+const sessions = await client.session.list()
+
+// Send messages
+const message = await client.session.chat({
+  id: session.id,
+  providerID: "anthropic",
+  modelID: "claude-3-5-sonnet-20241022",
+  parts: [{ type: "text", text: "Hello!" }],
+})
+```
+
+---
+
+### Files
+
+| Method                    | Description                  | Response                                                                                    |
+| ------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------- |
+| `find.text({ pattern })`  | Search for text in files     | Array of match objects with `path`, `lines`, `line_number`, `absolute_offset`, `submatches` |
+| `find.files({ query })`   | Find files by name           | `string[]` (file paths)                                                                     |
+| `find.symbols({ query })` | Find workspace symbols       | <a href={typesUrl}><code>Symbol[]</code></a>                                                |
+| `file.read({ path })`     | Read a file                  | `{ type: "raw" \| "patch", content: string }`                                               |
+| `file.status()`           | Get status for tracked files | <a href={typesUrl}><code>File[]</code></a>                                                  |
+
+---
+
+#### Examples
+
+```javascript
+// Search and read files
+const textResults = await client.find.text({ pattern: "function.*opencode" })
+const files = await client.find.files({ query: "*.ts" })
+const content = await client.file.read({ path: "src/index.ts" })
+```
+
+---
+
+### Logging
+
+| Method                                           | Description     | Response  |
+| ------------------------------------------------ | --------------- | --------- |
+| `log.write({ service, level, message, extra? })` | Write log entry | `boolean` |
+
+---
+
+#### Examples
+
+```javascript
+await client.log.write({
+  service: "my-app",
+  level: "info",
+  message: "Operation completed",
+})
+```
+
+---
+
+### Agents
+
+| Method         | Description               | Response                                    |
+| -------------- | ------------------------- | ------------------------------------------- |
+| `agent.list()` | List all available agents | <a href={typesUrl}><code>Agent[]</code></a> |
+
+---
+
+#### Examples
+
+```javascript
+const agents = await client.agent.list()
+```
+
+---
+
+### TUI
+
+| Method                                        | Description                       | Response               |
+| --------------------------------------------- | --------------------------------- | ---------------------- |
+| `tui.appendPrompt({ text })`                  | Append text to the prompt         | `boolean`              |
+| `tui.openHelp()`                              | Open the help dialog              | `boolean`              |
+| `tui.openSessions()`                          | Open the session selector         | `boolean`              |
+| `tui.openThemes()`                            | Open the theme selector           | `boolean`              |
+| `tui.openModels()`                            | Open the model selector           | `boolean`              |
+| `tui.submitPrompt()`                          | Submit the current prompt         | `boolean`              |
+| `tui.clearPrompt()`                           | Clear the prompt                  | `boolean`              |
+| `tui.executeCommand({ command })`             | Execute a command                 | `boolean`              |
+| `tui.showToast({ title?, message, variant })` | Show toast notification           | `boolean`              |
+| `tui.control.next()`                          | Wait for the next control request | Control request object |
+| `tui.control.response({ body })`              | Respond to a control request      | `boolean`              |
+
+---
+
+#### Examples
+
+```javascript
+// Control TUI interface
+await client.tui.appendPrompt({ text: "Add this to prompt" })
+await client.tui.showToast({
+  message: "Task completed",
+  variant: "success",
+})
+```
+
+---
+
+### Auth
+
+| Method                          | Description                    | Response  |
+| ------------------------------- | ------------------------------ | --------- |
+| `auth.set({ id, ...authData })` | Set authentication credentials | `boolean` |
+
+---
+
+#### Examples
+
+```javascript
+await client.auth.set({
+  id: "anthropic",
+  type: "api",
+  key: "your-api-key",
+})
+```
+
+---
+
+### Events
+
+| Method              | Description               | Response                  |
+| ------------------- | ------------------------- | ------------------------- |
+| `event.subscribe()` | Server-sent events stream | Server-sent events stream |
+
+---
+
+#### Examples
+
+```javascript
+// Listen to real-time events
+const eventStream = await client.event.subscribe()
+for await (const event of eventStream) {
+  console.log("Event:", event.type, event.properties)
+}
+```
+
+---
+
+## Error handling
+
+The SDK throws typed errors that you can catch and handle:
+
+```typescript
+try {
+  const session = await client.session.get({ id: "invalid-id" })
+} catch (error) {
+  console.error("Failed to get session:", error.message)
+}
+```

packages/web/src/content/docs/docs/server.mdx

@@ -57,7 +57,7 @@ The opencode server exposes the following APIs.
 | Method | Path                | Description                       | Response                                                                                              |
 | ------ | ------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------- |
 | `GET`  | `/config`           | Get config info                   | <a href={typesUrl}><code>Config</code></a>                                                            |
-| `GET`  | `/config/providers` | List providers and default models | `{ providers: `<a href={typesUrl}><code>Provider[]</code></a>`, default: { [key: string]: string } }` |
+| `GET`  | `/config/providers` | List providers and default models | `{ providers: `<a href={typesUrl}>Provider[]</a>`, default: { [key: string]: string } }` |
 
 ---
 
@@ -76,8 +76,8 @@ The opencode server exposes the following APIs.
 | `POST`   | `/session/:id/share`                     | Share session                      | Returns <a href={typesUrl}><code>Session</code></a>                                                                                                                        |
 | `DELETE` | `/session/:id/share`                     | Unshare session                    | Returns <a href={typesUrl}><code>Session</code></a>                                                                                                                        |
 | `POST`   | `/session/:id/summarize`                 | Summarize session                  |                                                                                                                                                                            |
-| `GET`    | `/session/:id/message`                   | List messages in a session         | Returns `{ info: `<a href={typesUrl}><code>Message</code></a>`, parts: `<a href={typesUrl}><code>Part[]</code></a>`}[]`                                                    |
-| `GET`    | `/session/:id/message/:messageID`        | Get message details                | Returns `{ info: `<a href={typesUrl}><code>Message</code></a>`, parts: `<a href={typesUrl}><code>Part[]</code></a>`}`                                                      |
+| `GET`    | `/session/:id/message`                   | List messages in a session         | Returns `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}[]`                                                    |
+| `GET`    | `/session/:id/message/:messageID`        | Get message details                | Returns `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}`                                                      |
 | `POST`   | `/session/:id/message`                   | Send chat message                  | body matches [`ChatInput`](https://github.com/sst/opencode/blob/main/packages/opencode/src/session/index.ts#L358), returns <a href={typesUrl}><code>Message</code></a>     |
 | `POST`   | `/session/:id/shell`                     | Run a shell command                | body matches [`CommandInput`](https://github.com/sst/opencode/blob/main/packages/opencode/src/session/index.ts#L1007), returns <a href={typesUrl}><code>Message</code></a> |
 | `POST`   | `/session/:id/revert`                    | Revert a message                   | body: `{ messageID }`                                                                                                                                                      |