From b3c8bec019ba813ca1a4af97dde79096a11fa54e Mon Sep 17 00:00:00 2001 From: Jay V Date: Tue, 19 Aug 2025 17:21:43 -0400 Subject: [PATCH] docs: edit server --- packages/web/astro.config.mjs | 21 +- packages/web/src/content/docs/docs/server.mdx | 189 ++++++++++-------- 2 files changed, 123 insertions(+), 87 deletions(-) diff --git a/packages/web/astro.config.mjs b/packages/web/astro.config.mjs index da426e44..fb905c72 100644 --- a/packages/web/astro.config.mjs +++ b/packages/web/astro.config.mjs @@ -9,8 +9,6 @@ import { rehypeHeadingIds } from "@astrojs/markdown-remark" import rehypeAutolinkHeadings from "rehype-autolink-headings" import { spawnSync } from "child_process" -const github = "https://github.com/sst/opencode" - // https://astro.build/config export default defineConfig({ site: config.url, @@ -49,7 +47,7 @@ export default defineConfig({ }, ], editLink: { - baseUrl: `${github}/edit/dev/packages/web/`, + baseUrl: `${config.github}/edit/dev/packages/web/`, }, markdown: { headingLinks: false, @@ -69,7 +67,13 @@ export default defineConfig({ { label: "Usage", - items: ["docs/tui", "docs/cli", "docs/ide", "docs/share", "docs/server", "docs/github"], + items: [ + "docs/tui", + "docs/cli", + "docs/ide", + "docs/share", + "docs/github" + ], }, { @@ -79,7 +83,6 @@ export default defineConfig({ "docs/agents", "docs/models", "docs/themes", - "docs/plugins", "docs/keybinds", "docs/formatters", "docs/permissions", @@ -87,6 +90,14 @@ export default defineConfig({ "docs/mcp-servers", ], }, + + { + label: "Develop", + items: [ + "docs/server", + "docs/plugins", + ], + }, ], components: { Hero: "./src/components/Hero.astro", diff --git a/packages/web/src/content/docs/docs/server.mdx b/packages/web/src/content/docs/docs/server.mdx index 90a67e6f..894c30fd 100644 --- a/packages/web/src/content/docs/docs/server.mdx +++ b/packages/web/src/content/docs/docs/server.mdx @@ -1,130 +1,155 @@ --- -title: Server API -description: Interact with opencode over HTTP using `opencode serve`. +title: Server +description: Interact with opencode server over HTTP. --- -## Overview +import config from "../../../../config.mjs" +export const typesUrl = `${config.github}/blob/dev/packages/sdk/js/src/gen/types.gen.ts` -`opencode serve` runs a headless HTTP server that exposes the same features as the TUI. The server is intended for automation and remote control. +The `opencode serve` command runs a headless HTTP server that exposes an API that an opencode client, like the TUI, uses. You can use this to create your own opencode client and even control a currently running TUI. -## Starting the server +--- + +## Usage ```bash opencode serve [--port ] [--hostname ] ``` -### Options +#### Options | Flag | Short | Description | Default | | ------------ | ----- | --------------------- | ----------- | | `--port` | `-p` | Port to listen on | `4096` | | `--hostname` | `-h` | Hostname to listen on | `127.0.0.1` | -## Documentation +--- -The server publishes an OpenAPI 3.1 spec and an interactive explorer at: +## Docs + +The server publishes an OpenAPI 3.1 spec that can be viewed at: ``` http://:/doc ``` -Use the spec to generate clients or inspect request and response types. All examples below use `curl` with the default `localhost:4096`. +For example, `http://localhost:4096/doc`. Use the spec to generate clients or inspect request and response types. Or view it in a Swagger explorer. -## API Endpoints +--- -### App & Config +## APIs -| Method | Path | Description | Response | -| ------ | ------------------- | --------------------------------- | -------- | -| `GET` | `/app` | Get app info | [`App`](packages/sdk/js/src/gen/types.gen.ts) | -| `POST` | `/app/init` | Initialize the app | `boolean` | -| `GET` | `/config` | Get config info | [`Config`](packages/sdk/js/src/gen/types.gen.ts) | -| `GET` | `/config/providers` | List providers and default models | `{ providers: `[`Provider[]`](packages/sdk/js/src/gen/types.gen.ts)`, default: { [key: string]: string } }` | +The opencode server exposes the following APIs. + +--- + +### App + +| Method | Path | Description | Response | +| ------ | ----------- | ------------------ | --------------------------------------- | +| `GET` | `/app` | Get app info | App | +| `POST` | `/app/init` | Initialize the app | `boolean` | + +--- + +### Config + +| Method | Path | Description | Response | +| ------ | ------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------- | +| `GET` | `/config` | Get config info | Config | +| `GET` | `/config/providers` | List providers and default models | `{ providers: `Provider[]`, default: { [key: string]: string } }` | + +--- ### Sessions -| Method | Path | Description | Notes | -| -------- | ---------------------------------------- | ---------------------------------- | ------------------------------------------ | -| `GET` | `/session` | List sessions | Returns [`Session[]`](packages/sdk/js/src/gen/types.gen.ts) | -| `GET` | `/session/:id` | Get session | Returns [`Session`](packages/sdk/js/src/gen/types.gen.ts) | -| `GET` | `/session/:id/children` | List child sessions | Returns [`Session[]`](packages/sdk/js/src/gen/types.gen.ts) | -| `POST` | `/session` | Create session | body: `{ parentID?, title? }`, returns [`Session`](packages/sdk/js/src/gen/types.gen.ts) | -| `DELETE` | `/session/:id` | Delete session | | -| `PATCH` | `/session/:id` | Update session properties | body: `{ title? }`, returns [`Session`](packages/sdk/js/src/gen/types.gen.ts) | -| `POST` | `/session/:id/init` | Analyze app and create `AGENTS.md` | body: `{ messageID, providerID, modelID }` | -| `POST` | `/session/:id/abort` | Abort a running session | | -| `POST` | `/session/:id/share` | Share session | Returns [`Session`](packages/sdk/js/src/gen/types.gen.ts) | -| `DELETE` | `/session/:id/share` | Unshare session | Returns [`Session`](packages/sdk/js/src/gen/types.gen.ts) | -| `POST` | `/session/:id/summarize` | Summarize session | | -| `GET` | `/session/:id/message` | List messages in a session | Returns `{ info: `[`Message`](packages/sdk/js/src/gen/types.gen.ts)`, parts: `[`Part[]`](packages/sdk/js/src/gen/types.gen.ts)`}[]` | -| `GET` | `/session/:id/message/:messageID` | Get message details | Returns `{ info: `[`Message`](packages/sdk/js/src/gen/types.gen.ts)`, parts: `[`Part[]`](packages/sdk/js/src/gen/types.gen.ts)`}` | -| `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 [`Message`](packages/sdk/js/src/gen/types.gen.ts) | -| `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 [`Message`](packages/sdk/js/src/gen/types.gen.ts) | -| `POST` | `/session/:id/revert` | Revert a message | body: `{ messageID }` | -| `POST` | `/session/:id/unrevert` | Restore reverted messages | | -| `POST` | `/session/:id/permissions/:permissionID` | Respond to a permission request | body: `{ response }` | +| Method | Path | Description | Notes | +| -------- | ---------------------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `GET` | `/session` | List sessions | Returns Session[] | +| `GET` | `/session/:id` | Get session | Returns Session | +| `GET` | `/session/:id/children` | List child sessions | Returns Session[] | +| `POST` | `/session` | Create session | body: `{ parentID?, title? }`, returns Session | +| `DELETE` | `/session/:id` | Delete session | | +| `PATCH` | `/session/:id` | Update session properties | body: `{ title? }`, returns Session | +| `POST` | `/session/:id/init` | Analyze app and create `AGENTS.md` | body: `{ messageID, providerID, modelID }` | +| `POST` | `/session/:id/abort` | Abort a running session | | +| `POST` | `/session/:id/share` | Share session | Returns Session | +| `DELETE` | `/session/:id/share` | Unshare session | Returns Session | +| `POST` | `/session/:id/summarize` | Summarize session | | +| `GET` | `/session/:id/message` | List messages in a session | Returns `{ info: `Message`, parts: `Part[]`}[]` | +| `GET` | `/session/:id/message/:messageID` | Get message details | Returns `{ info: `Message`, parts: `Part[]`}` | +| `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 Message | +| `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 Message | +| `POST` | `/session/:id/revert` | Revert a message | body: `{ messageID }` | +| `POST` | `/session/:id/unrevert` | Restore reverted messages | | +| `POST` | `/session/:id/permissions/:permissionID` | Respond to a permission request | body: `{ response }` | -### Search & Files +--- -| Method | Path | Description | Response | -| ------ | ------------------------ | ---------------------------- | -------- | +### Files + +| Method | Path | Description | Response | +| ------ | ------------------------ | ---------------------------- | ------------------------------------------------------------------------------------------- | | `GET` | `/find?pattern=` | Search for text in files | Array of match objects with `path`, `lines`, `line_number`, `absolute_offset`, `submatches` | -| `GET` | `/find/file?query=` | Find files by name | `string[]` (file paths) | -| `GET` | `/find/symbol?query=` | Find workspace symbols | [`Symbol[]`](packages/sdk/js/src/gen/types.gen.ts) | -| `GET` | `/file?path=` | Read a file | `{ type: "raw" \| "patch", content: string }` | -| `GET` | `/file/status` | Get status for tracked files | [`File[]`](packages/sdk/js/src/gen/types.gen.ts) | +| `GET` | `/find/file?query=` | Find files by name | `string[]` (file paths) | +| `GET` | `/find/symbol?query=` | Find workspace symbols | Symbol[] | +| `GET` | `/file?path=` | Read a file | `{ type: "raw" \| "patch", content: string }` | +| `GET` | `/file/status` | Get status for tracked files | File[] | + +--- ### Logging -| Method | Path | Description | Response | -| ------ | ------ | ---------------------------------------------------------------- | -------- | -| `POST` | `/log` | Write log entry. Body: `{ service, level, message, extra? }` | `boolean` | +| Method | Path | Description | Response | +| ------ | ------ | ------------------------------------------------------------ | --------- | +| `POST` | `/log` | Write log entry. Body: `{ service, level, message, extra? }` | `boolean` | + +--- ### Agents -| Method | Path | Description | Response | -| ------ | -------- | ------------------------ | -------- | -| `GET` | `/agent` | List all available agents | [`Agent[]`](packages/sdk/js/src/gen/types.gen.ts) | +| Method | Path | Description | Response | +| ------ | -------- | ------------------------- | ------------------------------------------- | +| `GET` | `/agent` | List all available agents | Agent[] | -### TUI Control +--- -| Method | Path | Description | Response | -| ------------ | ---------------------- | ------------------------------------------- | -------- | -| `POST` | `/tui/append-prompt` | Append text to the prompt | `boolean` | -| `POST` | `/tui/open-help` | Open the help dialog | `boolean` | -| `POST` | `/tui/open-sessions` | Open the session selector | `boolean` | -| `POST` | `/tui/open-themes` | Open the theme selector | `boolean` | -| `POST` | `/tui/open-models` | Open the model selector | `boolean` | -| `POST` | `/tui/submit-prompt` | Submit the current prompt | `boolean` | -| `POST` | `/tui/clear-prompt` | Clear the prompt | `boolean` | -| `POST` | `/tui/execute-command` | Execute a command (`{ command }`) | `boolean` | -| `POST` | `/tui/show-toast` | Show toast (`{ title?, message, variant }`) | `boolean` | -| `GET` | `/tui/control/next` | Wait for the next control request | Control request object | -| `POST` | `/tui/control/response` | Respond to a control request (`{ body }`) | `boolean` | +### TUI -### Authentication +| Method | Path | Description | Response | +| ------ | ----------------------- | ------------------------------------------- | ---------------------- | +| `POST` | `/tui/append-prompt` | Append text to the prompt | `boolean` | +| `POST` | `/tui/open-help` | Open the help dialog | `boolean` | +| `POST` | `/tui/open-sessions` | Open the session selector | `boolean` | +| `POST` | `/tui/open-themes` | Open the theme selector | `boolean` | +| `POST` | `/tui/open-models` | Open the model selector | `boolean` | +| `POST` | `/tui/submit-prompt` | Submit the current prompt | `boolean` | +| `POST` | `/tui/clear-prompt` | Clear the prompt | `boolean` | +| `POST` | `/tui/execute-command` | Execute a command (`{ command }`) | `boolean` | +| `POST` | `/tui/show-toast` | Show toast (`{ title?, message, variant }`) | `boolean` | +| `GET` | `/tui/control/next` | Wait for the next control request | Control request object | +| `POST` | `/tui/control/response` | Respond to a control request (`{ body }`) | `boolean` | -| Method | Path | Description | Response | -| ------ | ----------- | ---------------------------------------------------------------- | -------- | -| `PUT` | `/auth/:id` | Set authentication credentials. Body must match provider schema | `boolean` | +--- + +### Auth + +| Method | Path | Description | Response | +| ------ | ----------- | --------------------------------------------------------------- | --------- | +| `PUT` | `/auth/:id` | Set authentication credentials. Body must match provider schema | `boolean` | + +--- ### Events -| Method | Path | Description | Response | -| ------ | -------- | ------------------------------------------------------------------------------ | -------- | +| Method | Path | Description | Response | +| ------ | -------- | ----------------------------------------------------------------------------- | ------------------------- | | `GET` | `/event` | Server-sent events stream. First event is `server.connected`, then bus events | Server-sent events stream | -### Documentation +--- -| Method | Path | Description | Response | -| ------ | ------ | ------------------------------------- | -------- | -| `GET` | `/doc` | OpenAPI 3.1 specification and explorer | HTML page with OpenAPI spec and Swagger UI | +### Docs -## Example - -```bash -# fetch current app info -curl http://localhost:4096/app -``` - -Use the OpenAPI spec for complete schemas and additional endpoints. +| Method | Path | Description | Response | +| ------ | ------ | -------------------------------------- | ------------------------------------------ | +| `GET` | `/doc` | OpenAPI 3.1 specification | HTML page with OpenAPI spec |