From 778d5b675c38a2225370f89483930334626ed04d Mon Sep 17 00:00:00 2001 From: Dax Raad Date: Mon, 24 Aug 2026 19:03:26 -0400 Subject: [PATCH] docs: split client and sdk guides --- packages/www/openapi.json | 98 ++++++++++++ packages/www/public/openapi.json | 98 ++++++++++++ .../src/docs/content/build/client/effect.mdx | 101 ++++++++++++ .../build/{client.mdx => client/index.mdx} | 67 +------- packages/www/src/docs/content/build/sdk.mdx | 148 ------------------ .../src/docs/content/build/sdk/cloudflare.mdx | 81 ++++++++++ .../www/src/docs/content/build/sdk/effect.mdx | 99 ++++++++++++ .../www/src/docs/content/build/sdk/index.mdx | 74 +++++++++ packages/www/src/docs/lib/navigation.ts | 13 +- 9 files changed, 563 insertions(+), 216 deletions(-) create mode 100644 packages/www/src/docs/content/build/client/effect.mdx rename packages/www/src/docs/content/build/{client.mdx => client/index.mdx} (60%) delete mode 100644 packages/www/src/docs/content/build/sdk.mdx create mode 100644 packages/www/src/docs/content/build/sdk/cloudflare.mdx create mode 100644 packages/www/src/docs/content/build/sdk/effect.mdx create mode 100644 packages/www/src/docs/content/build/sdk/index.mdx diff --git a/packages/www/openapi.json b/packages/www/openapi.json index faaeb1a9bca..5ad90dab6b3 100644 --- a/packages/www/openapi.json +++ b/packages/www/openapi.json @@ -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"], diff --git a/packages/www/public/openapi.json b/packages/www/public/openapi.json index faaeb1a9bca..5ad90dab6b3 100644 --- a/packages/www/public/openapi.json +++ b/packages/www/public/openapi.json @@ -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"], diff --git a/packages/www/src/docs/content/build/client/effect.mdx b/packages/www/src/docs/content/build/client/effect.mdx new file mode 100644 index 00000000000..1d6d96b785e --- /dev/null +++ b/packages/www/src/docs/content/build/client/effect.mdx @@ -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() +``` diff --git a/packages/www/src/docs/content/build/client.mdx b/packages/www/src/docs/content/build/client/index.mdx similarity index 60% rename from packages/www/src/docs/content/build/client.mdx rename to packages/www/src/docs/content/build/client/index.mdx index b741b5692a5..233c9ff07e4 100644 --- a/packages/www/src/docs/content/build/client.mdx +++ b/packages/www/src/docs/content/build/client/index.mdx @@ -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)), -) -``` diff --git a/packages/www/src/docs/content/build/sdk.mdx b/packages/www/src/docs/content/build/sdk.mdx deleted file mode 100644 index 8d4f605057b..00000000000 --- a/packages/www/src/docs/content/build/sdk.mdx +++ /dev/null @@ -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. - - - The V2 SDK is beta. Install the current preview with `bun add @opencode-ai/sdk@dev`; its API may change before a - stable release. - - -## 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 - - 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`. diff --git a/packages/www/src/docs/content/build/sdk/cloudflare.mdx b/packages/www/src/docs/content/build/sdk/cloudflare.mdx new file mode 100644 index 00000000000..61085ab9a9f --- /dev/null +++ b/packages/www/src/docs/content/build/sdk/cloudflare.mdx @@ -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 + + 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 }) + }), +) +``` diff --git a/packages/www/src/docs/content/build/sdk/effect.mdx b/packages/www/src/docs/content/build/sdk/effect.mdx new file mode 100644 index 00000000000..56377722ee0 --- /dev/null +++ b/packages/www/src/docs/content/build/sdk/effect.mdx @@ -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()))) +``` diff --git a/packages/www/src/docs/content/build/sdk/index.mdx b/packages/www/src/docs/content/build/sdk/index.mdx new file mode 100644 index 00000000000..d27e72b28ea --- /dev/null +++ b/packages/www/src/docs/content/build/sdk/index.mdx @@ -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. + + + The V2 SDK is beta. Install the current preview with `bun add @opencode-ai/sdk@dev`; its API may change before a + stable release. + + +## 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. diff --git a/packages/www/src/docs/lib/navigation.ts b/packages/www/src/docs/lib/navigation.ts index 2c5587c4ee8..5e42664d587 100644 --- a/packages/www/src/docs/lib/navigation.ts +++ b/packages/www/src/docs/lib/navigation.ts @@ -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" }, ], }, ],