docs: split client and sdk guides

This commit is contained in:
Dax Raad
2026-08-24 19:03:26 -04:00
Unverified
parent 127113188e
commit 778d5b675c
9 changed files with 563 additions and 216 deletions
+98
View File
@@ -10614,6 +10614,104 @@
"summary": "Refresh worktrees"
}
},
"/api/workspace": {
"post": {
"tags": ["workspace"],
"operationId": "v2.workspace.create",
"parameters": [],
"security": [],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "string",
"pattern": "^wrk"
}
},
"required": ["data"],
"additionalProperties": false
}
}
}
},
"400": {
"description": "InvalidRequestError",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InvalidRequestErrorEncoded"
}
}
}
},
"401": {
"description": "UnauthorizedError",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnauthorizedErrorEncoded"
}
}
}
},
"404": {
"description": "ProviderNotFoundError",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProviderNotFoundErrorEncoded"
}
}
}
},
"409": {
"description": "ConflictError",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConflictErrorEncoded"
}
}
}
}
},
"description": "Create a logical workspace. A caller-supplied ID is idempotent when retried with the same provider; reusing it with another provider returns a conflict.",
"summary": "Create workspace",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"anyOf": [
{
"type": "string",
"pattern": "^wrk"
},
{
"type": "null"
}
]
},
"provider": {
"type": "string"
}
},
"required": ["provider"],
"additionalProperties": false
}
}
},
"required": true
}
}
},
"/api/workspace/{workspaceID}": {
"delete": {
"tags": ["workspace"],
+98
View File
@@ -10614,6 +10614,104 @@
"summary": "Refresh worktrees"
}
},
"/api/workspace": {
"post": {
"tags": ["workspace"],
"operationId": "v2.workspace.create",
"parameters": [],
"security": [],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "string",
"pattern": "^wrk"
}
},
"required": ["data"],
"additionalProperties": false
}
}
}
},
"400": {
"description": "InvalidRequestError",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InvalidRequestErrorEncoded"
}
}
}
},
"401": {
"description": "UnauthorizedError",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnauthorizedErrorEncoded"
}
}
}
},
"404": {
"description": "ProviderNotFoundError",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProviderNotFoundErrorEncoded"
}
}
}
},
"409": {
"description": "ConflictError",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConflictErrorEncoded"
}
}
}
}
},
"description": "Create a logical workspace. A caller-supplied ID is idempotent when retried with the same provider; reusing it with another provider returns a conflict.",
"summary": "Create workspace",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"anyOf": [
{
"type": "string",
"pattern": "^wrk"
},
{
"type": "null"
}
]
},
"provider": {
"type": "string"
}
},
"required": ["provider"],
"additionalProperties": false
}
}
},
"required": true
}
}
},
"/api/workspace/{workspaceID}": {
"delete": {
"tags": ["workspace"],
@@ -0,0 +1,101 @@
---
title: "Effect"
---
`@opencode-ai/client/effect` is the Effect-native client for the OpenCode HTTP API. It returns typed Effects and Streams
and decodes responses into OpenCode schema values.
```sh
bun add @opencode-ai/client@beta effect
```
## Create a client
Create a client with the server URL, then call methods grouped by API resource.
```ts
import { AbsolutePath, Location, OpenCode } from "@opencode-ai/client/effect"
import { Effect } from "effect"
import { FetchHttpClient } from "effect/unstable/http"
const program = Effect.gen(function* () {
const client = yield* OpenCode.make({ baseUrl: "http://localhost:4096" })
const session = yield* client.session.create({
location: Location.Ref.make({ directory: AbsolutePath.make("/workspace") }),
})
yield* client.session.prompt({
sessionID: session.id,
text: "Review the current changes",
})
return session
})
const session = await Effect.runPromise(program.pipe(Effect.provide(FetchHttpClient.layer)))
```
## Headers and requests
Pass default headers to `OpenCode.make`. Each operation also accepts request options for cancellation or per-request
headers.
```ts
const client = yield* OpenCode.make({
baseUrl: "https://opencode.example.com",
headers: { authorization: `Bearer ${process.env.OPENCODE_TOKEN}` },
})
const sessions = yield* client.session.list(undefined, {
signal: AbortSignal.timeout(10_000),
})
```
## Stream events
Streaming operations such as `event.subscribe()` and `session.log()` return Effect Streams.
```ts
import { Effect, Stream } from "effect"
yield* client.event.subscribe().pipe(
Stream.runForEach((event) => Effect.logInfo("OpenCode event", { type: event.type })),
)
```
## Local background service
The Node-only `@opencode-ai/client/effect/service` entrypoint discovers, starts, authenticates, and stops the local
background service as Effects.
```sh
bun add @effect/platform-node
```
Create an authenticated client for the ensured service.
```ts
import { NodeFileSystem } from "@effect/platform-node"
import { OpenCode } from "@opencode-ai/client/effect"
import { Service } from "@opencode-ai/client/effect/service"
import { Effect } from "effect"
import { FetchHttpClient } from "effect/unstable/http"
const program = Effect.gen(function* () {
const endpoint = yield* Service.ensure()
const client = yield* OpenCode.make({
baseUrl: endpoint.url,
headers: Service.headers(endpoint),
})
return yield* client.health.get()
})
const health = await Effect.runPromise(
program.pipe(Effect.provide(FetchHttpClient.layer), Effect.provide(NodeFileSystem.layer)),
)
```
Discover without starting, or stop the exact registered service.
```ts
const endpoint = yield* Service.discover()
yield* Service.stop()
```
@@ -1,5 +1,5 @@
---
title: "Client"
title: "JavaScript"
---
`@opencode-ai/client` is the generated TypeScript client for the OpenCode HTTP
@@ -110,68 +110,3 @@ const endpoint = await Service.ensure({
Omit these options to use the standard registration path and
`opencode serve --service` command.
## Effect
OpenCode provides a first-class Effect client through the
`@opencode-ai/client/effect` entrypoint. It returns typed Effects and Streams
and decodes responses into OpenCode schema values.
```sh
bun add @opencode-ai/client@beta effect
```
### Create a client
```ts
import { AbsolutePath, Location, OpenCode } from "@opencode-ai/client/effect"
import { Effect } from "effect"
import { FetchHttpClient } from "effect/unstable/http"
const program = Effect.gen(function* () {
const client = yield* OpenCode.make({ baseUrl: "http://localhost:4096" })
const session = yield* client.session.create({
location: Location.Ref.make({
directory: AbsolutePath.make("/workspace"),
}),
})
return yield* client.session.get({ sessionID: session.id })
})
const session = await Effect.runPromise(program.pipe(Effect.provide(FetchHttpClient.layer)))
```
Streaming operations, including `client.event.subscribe()` and
`client.session.log(...)`, return Effect `Stream` values.
### Local background service
The Node-only `@opencode-ai/client/effect/service` entrypoint exposes the same
operations as Effect values. Add `@effect/platform-node` and provide its
filesystem layer when running them.
```sh
bun add @effect/platform-node
```
```ts
import { NodeFileSystem } from "@effect/platform-node"
import { OpenCode } from "@opencode-ai/client/effect"
import { Service } from "@opencode-ai/client/effect/service"
import { Effect } from "effect"
import { FetchHttpClient } from "effect/unstable/http"
const program = Effect.gen(function* () {
const endpoint = yield* Service.ensure()
const client = yield* OpenCode.make({
baseUrl: endpoint.url,
headers: Service.headers(endpoint),
})
return yield* client.health.get()
})
const health = await Effect.runPromise(
program.pipe(Effect.provide(FetchHttpClient.layer), Effect.provide(NodeFileSystem.layer)),
)
```
-148
View File
@@ -1,148 +0,0 @@
---
title: "SDK"
---
`@opencode-ai/sdk` hosts OpenCode directly inside your application. Unlike the
[network client](/build/client), it assembles the OpenCode server and routes API
calls through its HTTP router in memory. It opens no HTTP listener and adds no
network hop between the client and server.
<Callout type="warning">
The V2 SDK is beta. Install the current preview with `bun add @opencode-ai/sdk@dev`; its API may change before a
stable release.
</Callout>
## Create a host
`OpenCode.create()` returns an explicitly owned host. Use `await using` to
release its router, Location services, fibers, and scoped plugin registrations:
```ts
import { OpenCode } from "@opencode-ai/sdk"
await using opencode = await OpenCode.create()
const session = await opencode.sessions.create({
location: { directory: "/workspace" },
})
await opencode.sessions.prompt({
sessionID: session.id,
text: "Review the current changes",
})
```
Call `await opencode.close()` explicitly when explicit resource management is
not available.
The embedded host uses the same Promise values, declared errors, request
options, and `AsyncIterable` streams as `@opencode-ai/client`. It exposes the
full generated client and adds the convenience aliases `sessions` and `events`
for the session and event groups.
## Stream events
```ts
for await (const event of opencode.events.subscribe()) {
console.log(event.type)
}
```
Pass an `AbortSignal` through the generated request options, or leave an
iteration to cancel its response body.
## Register plugins
Pass initial Promise plugins to `OpenCode.create()`. Embedded plugins use the
same discovery and Location-scoped activation path as configured plugins.
```ts
const plugin = {
id: "example",
async setup(ctx) {
await ctx.agent.transform((agents) => {
// Modify the Location's agent catalog.
})
},
}
await using opencode = await OpenCode.create({ plugins: [plugin] })
```
Call `await opencode.plugin(plugin)` to register another plugin after startup.
See the [Plugins guide](/build/plugins) for the plugin context and available
hooks.
## Workerd
Use `@opencode-ai/sdk/workerd` inside a Cloudflare Durable Object. This profile
uses the object's SQLite storage, persists durable events for eviction recovery,
and replaces unavailable local filesystem and process services.
Hold one host for the lifetime of the Durable Object instance instead of
creating one for every request:
```ts
import { OpenCodeWorkerd } from "@opencode-ai/sdk/workerd"
import myPlugin from "./my-plugin"
export class OpenCodeDO {
private readonly opencode: Promise<OpenCodeWorkerd.Interface>
constructor(state: DurableObjectState) {
this.opencode = state.blockConcurrencyWhile(() =>
OpenCodeWorkerd.create({
storage: state.storage,
config: { default_agent: "build" },
plugins: [myPlugin],
}),
)
}
async fetch() {
const opencode = await this.opencode
return Response.json(await opencode.health.get())
}
}
```
`blockConcurrencyWhile` keeps every Durable Object event out until the host is
ready and resets the object if initialization fails. The retained Promise gives
request handlers direct access to the same host after startup. Configuration is
a typed JavaScript object, and plugins are imported values bundled with the
Worker.
Wrangler selects OpenCode's Workerd-safe low-level implementations through the
`workerd` package condition. Cloudflare may evict a Durable Object without
running cleanup, so correctness does not depend on `close()` being called.
## Effect
Import the Effect-native API from `@opencode-ai/sdk/effect`. Closing its Effect
Scope releases the embedded host:
```ts
import { AbsolutePath, Location, OpenCode } from "@opencode-ai/sdk/effect"
import { Effect } from "effect"
const program = Effect.scoped(
Effect.gen(function* () {
const opencode = yield* OpenCode.create()
return yield* opencode.sessions.create({
location: Location.Ref.make({
directory: AbsolutePath.make("/workspace"),
}),
})
}),
)
const session = await Effect.runPromise(program)
```
Effect applications can contribute plugins from ordinary registration layers.
The registration layer may depend on `OpenCode.Service` and any other services
needed to construct the plugin; `OpenCode.layer()` remains unaware of those
features.
Use `OpenCode.layer()` for dependency injection. The Effect-native Workerd
entrypoint is `@opencode-ai/sdk/workerd/effect`.
@@ -0,0 +1,81 @@
---
title: "Cloudflare"
---
Use `@opencode-ai/sdk/workerd` inside a Cloudflare Durable Object. This profile uses the object's SQLite storage,
persists durable events for eviction recovery, and replaces unavailable local filesystem and process services.
```sh
bun add @opencode-ai/sdk@dev
```
Hold one host for the lifetime of the Durable Object instance instead of creating one for every request.
```ts
import { OpenCodeWorkerd } from "@opencode-ai/sdk/workerd"
import myPlugin from "./my-plugin"
export class OpenCodeDO {
private readonly opencode: Promise<OpenCodeWorkerd.Interface>
constructor(state: DurableObjectState) {
this.opencode = state.blockConcurrencyWhile(() =>
OpenCodeWorkerd.create({
storage: state.storage,
config: { default_agent: "build" },
plugins: [myPlugin],
}),
)
}
async fetch() {
const opencode = await this.opencode
return Response.json(await opencode.health.get())
}
}
```
`blockConcurrencyWhile` keeps every Durable Object event out until the host is ready and resets the object if
initialization fails. The retained Promise gives request handlers direct access to the same host after startup.
```ts
constructor(state: DurableObjectState) {
this.opencode = state.blockConcurrencyWhile(() =>
OpenCodeWorkerd.create({ storage: state.storage }),
)
}
```
Configuration is a typed JavaScript object, and plugins are imported values bundled with the Worker.
```ts
await OpenCodeWorkerd.create({
storage: state.storage,
config: { default_agent: "build" },
plugins: [myPlugin],
})
```
Wrangler selects OpenCode's Workerd-safe implementations through the `workerd` package condition. Cloudflare may evict
a Durable Object without running cleanup, so correctness does not depend on `close()` being called.
```jsonc title="wrangler.jsonc"
{
"compatibility_flags": ["nodejs_compat"]
}
```
## Effect
Use the Effect-native entrypoint from `@opencode-ai/sdk/workerd/effect`.
```ts
import { OpenCodeWorkerd } from "@opencode-ai/sdk/workerd/effect"
import { Effect } from "effect"
const program = Effect.scoped(
Effect.gen(function* () {
return yield* OpenCodeWorkerd.create({ storage: state.storage })
}),
)
```
@@ -0,0 +1,99 @@
---
title: "Effect"
---
`@opencode-ai/sdk/effect` is the Effect-native embedded SDK. Operations return typed Effects and Streams, and closing
the owning Scope releases the router, Location services, fibers, and plugin registrations.
```sh
bun add @opencode-ai/sdk@dev effect
```
## Create a host
Create the host inside `Effect.scoped`, then use its generated API groups or the `sessions` alias.
```ts
import { AbsolutePath, Location, OpenCode } from "@opencode-ai/sdk/effect"
import { Effect } from "effect"
const program = Effect.scoped(
Effect.gen(function* () {
const opencode = yield* OpenCode.create()
const session = yield* opencode.sessions.create({
location: Location.Ref.make({ directory: AbsolutePath.make("/workspace") }),
})
yield* opencode.sessions.prompt({
sessionID: session.id,
text: "Review the current changes",
})
return session
}),
)
const session = await Effect.runPromise(program)
```
The embedded host uses the same schema values, declared errors, request options, and Streams as
`@opencode-ai/client/effect`.
```ts
const health = yield* opencode.health.get()
const sessions = yield* opencode.sessions.list()
```
## Stream events
Streaming endpoints return Effect `Stream` values. Fork consumers in the host Scope when they should run in the
background.
```ts
import { Effect, Stream } from "effect"
yield* opencode.events.subscribe().pipe(
Stream.runForEach((event) => Effect.logInfo("OpenCode event", { type: event.type })),
Effect.forkScoped,
)
```
## Register plugins
Register Effect plugins through the embedded host. Their registrations remain scoped to the host.
```ts
import { Plugin } from "@opencode-ai/plugin/effect"
import { Effect } from "effect"
const plugin = Plugin.define({
id: "example",
effect: (ctx) =>
Effect.gen(function* () {
const storage = ctx.storage
yield* storage.set("embedded", true)
}),
})
yield* opencode.plugin(plugin)
```
See the [Effect plugins guide](/build/plugins/effect) for the complete plugin context.
```ts
yield* opencode.plugin.list()
```
## Layer
Use `OpenCode.layer()` when the embedded host should be an application service.
```ts
import { OpenCode } from "@opencode-ai/sdk/effect"
import { Effect } from "effect"
const program = Effect.gen(function* () {
const opencode = yield* OpenCode.Service
return yield* opencode.health.get()
})
const health = await Effect.runPromise(program.pipe(Effect.provide(OpenCode.layer())))
```
@@ -0,0 +1,74 @@
---
title: "Overview"
---
`@opencode-ai/sdk` hosts OpenCode directly inside your application. Unlike the
[network client](/build/client), it assembles the OpenCode server and routes API
calls through its HTTP router in memory. It opens no HTTP listener and adds no
network hop between the client and server.
<Callout type="warning">
The V2 SDK is beta. Install the current preview with `bun add @opencode-ai/sdk@dev`; its API may change before a
stable release.
</Callout>
## Create a host
`OpenCode.create()` returns an explicitly owned host. Use `await using` to
release its router, Location services, fibers, and scoped plugin registrations:
```ts
import { OpenCode } from "@opencode-ai/sdk"
await using opencode = await OpenCode.create()
const session = await opencode.sessions.create({
location: { directory: "/workspace" },
})
await opencode.sessions.prompt({
sessionID: session.id,
text: "Review the current changes",
})
```
Call `await opencode.close()` explicitly when explicit resource management is
not available.
The embedded host uses the same Promise values, declared errors, request
options, and `AsyncIterable` streams as `@opencode-ai/client`. It exposes the
full generated client and adds the convenience aliases `sessions` and `events`
for the session and event groups.
## Stream events
```ts
for await (const event of opencode.events.subscribe()) {
console.log(event.type)
}
```
Pass an `AbortSignal` through the generated request options, or leave an
iteration to cancel its response body.
## Register plugins
Pass initial Promise plugins to `OpenCode.create()`. Embedded plugins use the
same discovery and Location-scoped activation path as configured plugins.
```ts
const plugin = {
id: "example",
async setup(ctx) {
await ctx.agent.transform((agents) => {
// Modify the Location's agent catalog.
})
},
}
await using opencode = await OpenCode.create({ plugins: [plugin] })
```
Call `await opencode.plugin(plugin)` to register another plugin after startup.
See the [Plugins guide](/build/plugins) for the plugin context and available
hooks.
+11 -2
View File
@@ -99,9 +99,18 @@ export const docsSections: DocsSection[] = [
],
},
{
title: "Client",
items: [
{ title: "Client", slug: "build/client" },
{ title: "SDK", slug: "build/sdk" },
{ title: "JavaScript", slug: "build/client" },
{ title: "Effect", slug: "build/client/effect" },
],
},
{
title: "SDK",
items: [
{ title: "Overview", slug: "build/sdk" },
{ title: "Effect", slug: "build/sdk/effect" },
{ title: "Cloudflare", slug: "build/sdk/cloudflare" },
],
},
],