mirror of
https://github.com/anomalyco/opencode.git
synced 2026-11-21 04:12:08 +03:00
docs: split client and sdk guides
This commit is contained in:
@@ -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"],
|
||||
|
||||
@@ -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
-66
@@ -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)),
|
||||
)
|
||||
```
|
||||
@@ -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.
|
||||
@@ -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" },
|
||||
],
|
||||
},
|
||||
],
|
||||
|
||||
Reference in New Issue
Block a user