mirror of
https://github.com/sst/opencode.git
synced 2025-08-23 14:34:08 +00:00
This commit is contained in:
Jay V
parent
b3c8bec019
commit
8d8045ff95
5 changed files with 309 additions and 15 deletions
|
|
@ -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.
|
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.
|
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.
|
||||||
|
|
|
||||||
|
|
@ -67,13 +67,7 @@ export default defineConfig({
|
||||||
|
|
||||||
{
|
{
|
||||||
label: "Usage",
|
label: "Usage",
|
||||||
items: [
|
items: ["docs/tui", "docs/cli", "docs/ide", "docs/share", "docs/github"],
|
||||||
"docs/tui",
|
|
||||||
"docs/cli",
|
|
||||||
"docs/ide",
|
|
||||||
"docs/share",
|
|
||||||
"docs/github"
|
|
||||||
],
|
|
||||||
},
|
},
|
||||||
|
|
||||||
{
|
{
|
||||||
|
|
@ -93,10 +87,7 @@ export default defineConfig({
|
||||||
|
|
||||||
{
|
{
|
||||||
label: "Develop",
|
label: "Develop",
|
||||||
items: [
|
items: ["docs/sdk", "docs/server", "docs/plugins"],
|
||||||
"docs/server",
|
|
||||||
"docs/plugins",
|
|
||||||
],
|
|
||||||
},
|
},
|
||||||
],
|
],
|
||||||
components: {
|
components: {
|
||||||
|
|
|
||||||
|
|
@ -176,7 +176,7 @@ opencode run Explain the use of context in Go
|
||||||
|
|
||||||
### serve
|
### 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
|
```bash
|
||||||
opencode serve
|
opencode serve
|
||||||
|
|
|
||||||
300
packages/web/src/content/docs/docs/sdk.mdx
Normal file
300
packages/web/src/content/docs/docs/sdk.mdx
Normal file
|
|
@ -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)
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
@ -57,7 +57,7 @@ The opencode server exposes the following APIs.
|
||||||
| Method | Path | Description | Response |
|
| Method | Path | Description | Response |
|
||||||
| ------ | ------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------- |
|
| ------ | ------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------- |
|
||||||
| `GET` | `/config` | Get config info | <a href={typesUrl}><code>Config</code></a> |
|
| `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> |
|
| `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> |
|
| `DELETE` | `/session/:id/share` | Unshare session | Returns <a href={typesUrl}><code>Session</code></a> |
|
||||||
| `POST` | `/session/:id/summarize` | Summarize session | |
|
| `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` | 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}><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}>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/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/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 }` |
|
| `POST` | `/session/:id/revert` | Revert a message | body: `{ messageID }` |
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue