AGENTS.md files keep working. Your plugins and server integrations do not.OpenCode V1 OpenCode V2 ─────────────────────────── ────────────────────────────────────── opencode.json (permission, agent) ───> same file works, native shape optional .opencode/ agents, skills, commands ─> works unchanged tui.json ───> ~/.config/opencode/cli.json (automatic) plugin: fn returning hooks ───> Plugin.define({ id, setup }) REWRITE @opencode-ai/sdk (and its /v2) ───> @opencode/client REWRITE message.part.* snapshots ───> session.text/tool/* facts REWRITE abort + replay prompt ───> native inbox (steer, queue) REWRITE one server per client ───> one shared background service
@opencode-ai/sdk, @opencode-ai/sdk/v2 and @opencode-ai/plugin. List every plugin hook and every V1 event type you handle (message.updated, message.part.*, question.*, session.idle, session.error).Plugin.define. See plugins, the hook by hook guide and the plugin parity audit.@opencode/client and connect to the shared service. See SDK and the complete example.| Area | OpenCode V1 | OpenCode V2 | Action |
| Plugins | function returning a hooks object | Plugin.define({ id, setup }) | rewrite |
| Server API | @opencode-ai/sdk | @opencode/client | rewrite |
| Terminal config | layered tui.json(c) | one global cli.json | automatic |
| Config, agents, skills | opencode.json, .opencode/ | same files and paths | none |
| Process model | each client starts a server | one shared service for TUI, desktop and web | check integrations |
opencode. They do not run side by side. The V2 installer replaces the V1 binary, so keep a copy of your V1 setup while you test.| Topic | V1 | V2 |
| Client factory | createOpencodeClient({ baseUrl, directory }) | OpenCode.make({ baseUrl, headers }) |
| Results | { data, error } | value, or a rejected promise |
| Event field | event.properties | event.data |
| Event stream | client.global.event() | client.event.subscribe({ signal }) |
| Prompt | session.promptAsync({ parts }) | session.prompt({ sessionID, text, files }) |
| Stop | session.abort | session.interrupt({ sessionID, resume }) |
| System prompt | promptAsync({ system }) | session.instructions.entry.put |
| Questions | question.* | form.* events, session.form.* calls |
| Turn done | session.idle | session.execution.succeeded |
| Errors | session.error | session.execution.failed, step.failed, tool.failed |
| Shell tool | bash | shell |
| Subagent tool | task with subagent_type, task_id | subagent with agent, sessionID |
| File tool input | filePath | path (read, edit, write) |
| Model ref | { providerID, modelID } | { providerID, id, variant? } |
| Permission rule | { permission, pattern, action } | { action, resource, effect } |
| Server password env | OPENCODE_SERVER_PASSWORD | OPENCODE_PASSWORD (ignored in service mode) |
| Health route | GET /api/health | GET /api/info |
123`bash` is now `shell`; `task` is now `subagent`. The `subagent` tool takes `agent` instead of `subagent_type` and `sessionID` instead of `task_id`. `read`, `edit`, `write` take `path` instead of `filePath`.
12curl -fsSL https://opencode.ai/v2/install | bash opencode --version
opencode on PATH can still be V1, which prints help instead of starting a V2 service.opencode --version and require a minimum V2 version (Kimaki requires 2.0.19).PATH: an OPENCODE_PATH override, ~/.opencode/bin/opencode, and the opencode2 alias some installs add.0.0.0-dev-<n>.import { execFile } from 'node:child_process' import os from 'node:os' import path from 'node:path' import { promisify } from 'node:util' const exec = promisify(execFile) const MIN_VERSION = [2, 0, 19] function atLeast(version: string) { if (version.startsWith('0.0.0-dev')) return true const parts = version.split('-')[0].split('.').map(Number) for (let i = 0; i < 3; i++) { if (parts[i] !== MIN_VERSION[i]) return parts[i] > MIN_VERSION[i] } return true } export async function findOpencode() { const candidates = [ process.env.OPENCODE_PATH, 'opencode', path.join(os.homedir(), '.opencode/bin/opencode'), 'opencode2', ].filter((value): value is string => Boolean(value)) for (const binary of candidates) { const result = await exec(binary, ['--version'], { timeout: 5_000 }).catch(() => null) const version = result?.stdout.trim() if (version && atLeast(version)) return { binary, version } } return new Error('OpenCode V2 not found. Run: curl -fsSL https://opencode.ai/v2/install | bash') }
opencode --help before you build your own wrappers. opencode api <operationId> calls any endpoint by its OpenAPI ID:12345opencode api session.switchModel --param sessionID=$OPENCODE_SESSION_ID -d '{"model":{"providerID":"anthropic","id":"claude-opus-4-6"}}' opencode api session.compact --param sessionID=$OPENCODE_SESSION_ID opencode service status opencode plugin list opencode reload
--server <url> with OPENCODE_PASSWORD. A private server you spawned yourself is invisible to plain opencode commands.12Migrate my OpenCode configuration, including file-based definitions, from the V1 format to the native V2 format. Preserve its behavior and all unrelated settings.
permissions array. Actions were renamed too: bash is shell, task is subagent, write and patch are edit.1234567891011121314// V1 { "permission": { "bash": { "git push *": "ask" }, "edit": "allow" }, "tools": { "websearch": false } } // V2 { "permissions": [ { "action": "shell", "resource": "git push *", "effect": "ask" }, { "action": "edit", "resource": "*", "effect": "allow" }, { "action": "websearch", "resource": "*", "effect": "deny" } ] }
bash or task does nothing in V2. See the permission guide.123456// V1 rule in code { permission: 'external_directory', pattern: '/repo/*', action: 'deny' } // V2 rule in code { action: 'external_directory', resource: '/repo/*', effect: 'deny' } { action: 'shell', resource: '*', effect: 'allow' }
skill:<id>) accept only allow and deny, not ask.external_directory is allowed by default in V2. V1 asked before reading paths outside the project. Add { "action": "external_directory", "resource": "*", "effect": "ask" } to keep the old behavior.#:| V1 | V2 |
agent, mode | agents (prompt becomes system, disable becomes disabled) |
model + variant | "anthropic/claude-sonnet-4-5#high" |
command (subtask) | commands (subagent) |
plugin: ["pkg", ["./x.ts", opts]] | plugins: ["pkg", { "package": "./x.ts", "options": opts }] |
mcp.<name> with enabled | mcp.servers.<name> with disabled |
provider with npm, api | providers with package: "aisdk:...", settings.baseURL |
skills.paths, skills.urls | one skills array |
snapshot, attachment, reference | snapshots, media, references |
compaction.preserve_recent_tokens | compaction.keep.tokens |
lsp config but runs no language servers. It also reads only AGENTS.md, not CLAUDE.md. Todos are off by default; enable them with experimental.todo: true.npm. A V2 provider uses a package with the aisdk: prefix, which loads any AI SDK v3 provider module (a create* export) by URL or name:123456789101112131415// V1 { "provider": { "my": { "npm": "@ai-sdk/openai-compatible", "options": { "baseURL": "http://localhost:8080/v1" } } } } // V2 { "providers": { "my": { "name": "My provider", "package": "aisdk:@ai-sdk/openai-compatible", "settings": { "baseURL": "http://localhost:8080/v1" }, "models": { "my-model": { "name": "My model" } } } }, "model": "my/my-model" }
"package": "aisdk:file:///path/to/provider.ts". Kimaki loads its deterministic test provider this way.agent block in opencode.json did not always load the same way in our tests, while file agents in .opencode/agent/*.md did. If an agent is missing after the upgrade, move it to a file.opencode.json and started a private server with it. In V2 you share the user's service, so you cannot own its config.plugins, not single .ts files.opencode.json files load after global config, so project permissions and providers can override your defaults.permissions on session.create, instruction entries) over global config edits.ctx.options, not env vars set when spawning OpenCode. A shared service has none of your env.id and registers everything inside setup(ctx). The full reference is the plugin migration guide.import { Plugin } from '@opencode/plugin' export default Plugin.define({ id: 'company.guard', async setup(ctx) { await ctx.tool.hook('execute.before', (event) => { const input = event.input as { filePath?: string } if (event.tool === 'read' && input.filePath?.includes('.env')) { throw new Error('Do not read .env files') } }) await ctx.shell.hook('create.before', (event) => { event.env.COMPANY_ENV = 'development' }) }, })
default export and checks it has an id plus a setup (Promise API) or effect (Effect API) function.// V1: each export is one plugin import type { Plugin } from '@opencode-ai/plugin' export const contextPlugin: Plugin = async ({ directory, serverUrl }) => { return { 'chat.message': async (input, output) => { /* ... */ }, event: async ({ event }) => { /* ... */ }, } } export { ipcToolsPlugin } from './ipc-tools-plugin.js' // V2: one default export, hooks registered imperatively import { Plugin } from '@opencode/plugin' export default Plugin.define({ id: 'my-plugin', async setup(ctx) { await ctx.session.hook('prompt', async (event) => { /* ... */ }) await ctx.tool.hook('execute.after', async (event) => { /* ... */ }) return () => { // optional cleanup, runs on reload and location shutdown } }, })
Plugin must export a default definition with an id and an effect or setup function.hook() and transform() returns a Promise<Registration> with a dispose() method. Await them in setup so registration finishes before activation. Disposal on unload is automatic.Plugin is now a value, not just a type. import type { Plugin } from V1 code will not work for Plugin.define.effect is a peer dependency. OpenCode rewrites effect and @opencode/plugin imports to the host instances. Declare "effect": "^4" as a peer and dev dependency, never bundle it, and never import effect/internal/*.@opencode/plugin/effect) where effect: (ctx) => Effect replaces setup. Use it where OpenCode's own API is Effect-native, for example OAuth attempts with scoped finalizers.event instead of input and output.| V1 hook | V2 API |
event | ctx.event.subscribe() |
tool map, tool.definition | ctx.tool.transform(...) |
tool.execute.before / after | ctx.tool.hook('execute.before' / 'execute.after', ...) |
shell.env | ctx.shell.hook('create.before', ...) |
chat.message | ctx.session.hook('prompt', ...) |
chat.params, experimental.chat.system.transform | ctx.session.hook('context', ...) |
experimental.chat.messages.transform | ctx.session.hook('context', ...), edit event.messages |
chat.headers | ctx.session.hook('model.request', ...) |
auth loader with a custom fetch | ctx.session.hook('http.request' / 'http.response', ...) |
permission.ask | ctx.permission.hook('evaluate', ...) |
auth | ctx.integration.transform(...) |
experimental.session.compacting | ctx.session.hook('compaction', ...) |
| none | ctx.session.hook('retry', ...) |
dispose | cleanup function returned by setup |
context runs only before agent requests. Register compaction, generate and title hooks too if a change must reach every model request. Kimaki registers the same handler for context, compaction and generate.(input, output) with output.args. V2 passes one mutable event { tool, sessionID, agent, messageID, id, input }. The input is unknown, so narrow it.1234567891011121314// V1 'tool.execute.before': async (input, output) => { if (input.tool !== 'bash') return output.args.command = `export FOO=1; ${output.args.command}` }, // V2 await ctx.tool.hook('execute.before', async (event) => { if (event.tool !== 'shell') return const input = event.input if (!input || typeof input !== 'object' || Array.isArray(input)) return if (!('command' in input) || typeof input.command !== 'string') return input.command = `export FOO=1; ${input.command}` })
bash or task silently never match. Do not keep shell || bash fallbacks; V2 only sends shell.execute.after carries a status plus result or error. The input is read-only.1234567891011// V1 'tool.execute.after': async (input, output) => { await recordEdit({ sessionId: input.sessionID, tool: input.tool, args: input.args, output: output.output }) }, // V2 await ctx.tool.hook('execute.after', async (event) => { if (event.status !== 'completed') return if (!['edit', 'write', 'patch'].includes(event.tool)) return await recordEdit({ sessionId: event.sessionID, tool: event.tool, input: event.input }) })
{ tool, sessionID, agent, messageID, id, input } plus either { status: 'completed', result } or { status: 'error', error }.Tool.Result is { output?, content?, metadata? }, where content is a string or an array of { type: 'text', text } and { type: 'file', uri, mime, name? }. Code that read V1 output.output breaks.execute in a tool transform instead:1234567891011await ctx.tool.transform((tools) => { for (const current of tools.list()) { tools.update(current.id, (tool) => { const execute = tool.execute tool.execute = async (input, context) => { const result = await execute(input, context) return redactSecrets(result) } }) } })
shell.env got the sessionID. V2 ctx.shell.hook('create.before') gets { command, cwd, timeout, shell, env } with no session ID.// V1 'shell.env': async (input, output) => { output.env.MY_SESSION_ID = input.sessionID }, // V2: env that is the same for every session await ctx.shell.hook('create.before', (event) => { event.env.MY_TOOL_HOME = '/opt/my-tool' }) // V2: per-session env, prefix the command in the session-aware tool hook await ctx.tool.hook('execute.before', async (event) => { if (event.tool !== 'shell') return const input = event.input as { command?: unknown } if (typeof input.command !== 'string') return const quote = (value: string) => `'${value.replaceAll("'", "'\\''")}'` input.command = `export MY_TOOL_CALL=${quote(`${event.messageID}:${event.id}`)}; ${input.command}` })
OPENCODE_SESSION_ID.event.tools[name].input in the context hook changes only what the model sees, per request.// V1 'tool.definition': async (input, output) => { if (input.toolID !== 'bash') return output.parameters = myBashSchema }, // V2, per request: extend the JSON schema the model sees await ctx.session.hook('context', async (event) => { if (!(await isMine(event.sessionID))) return const tool = event.tools['shell'] const input = tool?.input if (!tool || !input || typeof input !== 'object' || Array.isArray(input)) return tool.input = { ...input, properties: { ...(input.properties && typeof input.properties === 'object' ? input.properties : {}), description: { type: 'string', description: 'Short 5-10 word summary of the command' }, }, } })
timeout being a non-negative integer.synthetic: true parts into the user message. V2 prompts have no synthetic sub-parts. Save a separate synthetic message before the prompt is admitted.// V1 'chat.message': async (input, output) => { output.parts.push({ id: `prt_${crypto.randomUUID()}`, sessionID: input.sessionID, messageID: output.message.id, type: 'text', text: `[current git branch is ${branch}]`, synthetic: true, }) }, // V2 await ctx.session.hook('prompt', async (event) => { if (!(await isMine(event.sessionID))) return const text = `[current git branch is ${await currentBranch(ctx.location.directory)}]` const history = await ctx.session.context({ sessionID: event.sessionID }).catch(() => null) const last = history?.findLast((m) => m.type === 'synthetic' && m.text.startsWith('[current git branch')) if (last?.type === 'synthetic' && last.text === text) return await ctx.session.synthetic({ sessionID: event.sessionID, text, delivery: event.delivery, resume: false }) })
prompt hook runs before admission, so the synthetic message lands first. Its event is mutable: { sessionID, messageID, prompt, metadata?, delivery }. You can rewrite event.prompt.text or set event.delivery.12345await ctx.session.hook('prompt', (event) => { if (!event.prompt.text.endsWith('. queue')) return event.prompt.text = event.prompt.text.slice(0, -'. queue'.length) event.delivery = 'queue' })
ctx.session.context({ sessionID }) to read the model-facing history. It replaces V1 client.session.messages({ limit }) inside plugins.output.system: string[]. V2 gives event.system as an array of { type: 'text', text }, plus mutable messages, tools, options and read-only model, agent, sessionID.// V1 'experimental.chat.system.transform': async (input, output) => { output.system.push('Always answer in English.') }, 'chat.params': async (input, output) => { output.temperature = 0.2 }, // V2: one handler for every request kind import type { SessionContext } from '@opencode/plugin/promise/session' const shapeRequest = async (event: SessionContext) => { event.system.push({ type: 'text', text: 'Always answer in English.' }) event.options.temperature = 0.2 } await ctx.session.hook('context', shapeRequest) await ctx.session.hook('compaction', shapeRequest) await ctx.session.hook('generate', shapeRequest)
generate also covers OpenCode's warming keep-alive requests. If only context adds your text, compaction and warming requests have a different prefix and the provider prompt cache misses.primary, compaction, title and generate. The title hook is separate: set event.result to skip the title model call.event.messages in the context hook. The entries are OpenCode Message instances, so mutate in place instead of building copies:12345678await ctx.session.hook('context', async (event) => { for (const message of event.messages) { if (message.role !== 'user') continue const extra = renderTurnContext(message.metadata) // TODO: build a new Message once plugins can import OpenCode's Message class. if (extra) Array.prototype.push.call(message.content, { type: 'text', text: extra }) } })
model.request. Scope model hooks with { providerID }.1234567891011// V1 'chat.headers': async (input, output) => { if (input.model.providerID !== 'my-router') return output.headers['x-session-affinity'] = input.sessionID }, // V2 await ctx.session.hook('model.request', async (event) => { event.headers['x-session-affinity'] = event.sessionID event.headers['x-agent'] = event.agent }, { providerID: 'my-router' })
{ sessionID, agent, model, kind, headers, baseURL? }.fetch from auth.loader. V2 hands you the outgoing Request in http.request and the Response in http.response. Replace them to change them.// V1 auth: { provider: 'anthropic', async loader(getAuth, provider) { return { apiKey: '', async fetch(input, init) { const headers = new Headers(init?.headers) headers.set('anthropic-beta', 'my-beta') return fetch(input, { ...init, headers }) }, } }, }, // V2 await ctx.session.hook('http.request', async (event) => { const request = event.request if (!new URL(request.url).pathname.endsWith('/messages')) return const body = rewriteBody(await request.clone().text()) const headers = new Headers(request.headers) headers.set('anthropic-beta', 'my-beta') headers.delete('content-length') // the body length changed event.request = new Request(request, { body, headers }) }, { providerID: 'anthropic' })
request.clone().text().content-length when you change the body.authorization: Bearer. No token injection needed.http.response is the only place to read headers of a failed response, for example rate limit reset times. The retry hook's error carries no headers.12345const lastHeaders = new Map<string, Record<string, string>>() await ctx.session.hook('http.response', (event) => { if (event.response.ok) return lastHeaders.set(event.sessionID, Object.fromEntries(event.response.headers)) })
user-agent: opencode/... on every fetch, including plugin fetches. Some OAuth token endpoints reject it; set your own user agent there.auth.methods with authorize returning { url, instructions, method, callback } becomes an integration method. OpenCode stores and refreshes the credential.// V1 auth: { provider: 'anthropic', methods: [{ label: 'Claude Pro/Max', type: 'oauth', authorize: async () => ({ url, instructions: 'Paste the code', method: 'code', callback: async (code) => ({ type: 'oauth', refresh, access, expires }), }) }], }, // V2 (Promise API) import { Plugin } from '@opencode/plugin' export default Plugin.define({ id: 'my-auth', async setup(ctx) { await ctx.integration.transform((editor) => { editor.method.update({ integrationID: 'anthropic', method: { id: 'my-oauth', type: 'oauth', label: 'My OAuth (browser)' }, authorize: async () => ({ mode: 'code', url: buildAuthorizeUrl(), instructions: 'Paste the code', callback: async (code) => exchangeCode(code), // returns a Credential.OAuth }), refresh: async (credential) => refreshToken(credential), }) }) }, })
auto (callback promise) or code (callback with the pasted code). Register two methods if you need both.{ type: 'failed' } sentinel.oauth, command, key, external and env.ctx.credential.activate({ credentialID }). Account changes are global per integration; model changes are per session.event callback with event.properties. V2 pulls with an async iterator, and payloads are in event.data.// V1 async event({ event }) { if (event.type === 'session.idle') cleanup(event.properties.sessionID) }, // V2 const abort = new AbortController() void (async () => { try { for await (const event of ctx.event.subscribe({ signal: abort.signal })) { if (event.type === 'session.execution.succeeded') cleanup(event.data.sessionID) } } catch { // aborted on plugin unload } })() return () => abort.abort()
sessionID.prompt and context hooks, since a model request means "not idle".compaction gets the full request context plus an optional result. Set it to skip the model call.12345678910// V1 'experimental.session.compacting': async (input, output) => { output.context.push('Keep the list of open TODOs.') }, // V2 await ctx.session.hook('compaction', async (event) => { event.system.push({ type: 'text', text: 'Keep the list of open TODOs.' }) // or: event.result = { summary: '## Objective\n...' } })
ctx.session.compact({ sessionID, delivery: 'queue' }).output.status. V2 evaluate can change effect and message for { sessionID, agent?, action, resources, metadata?, source? }.123456789// V1 'permission.ask': async (input, output) => { if (input.type === 'bash' && isSafe(input)) output.status = 'allow' }, // V2 await ctx.permission.hook('evaluate', (event) => { if (event.action === 'shell' && event.resources.every(isSafe)) event.effect = 'allow' })
ctx.permission.assert(input) asks the user and waits. Rethrow a plain rejection; it ends the current step.retry hook that decides whether and when to retry a failed model call. A fallback plugin can switch model or account and retry the same step, with no abort and no replay:12345await ctx.session.hook('retry', async (event) => { if (!isRateLimit(event.error)) return await ctx.session.switchModel({ sessionID: event.sessionID, model: { providerID: 'openai', id: 'gpt-6' } }) event.decision = { retry: true, delay: 1_000 } })
{ sessionID, agent, model, error, attempt, decision }. Compaction keeps its prepared request across retries, so a model switch here does not apply to it.tool() helper is gone. Tools use plain JSON Schema and return structured content. Transforms are replayed, so keep the callback synchronous and free of side effects.import { Plugin } from '@opencode/plugin' export default Plugin.define({ id: 'greeting', async setup(ctx) { await ctx.tool.transform((editor) => { editor.add({ name: 'greeting', description: 'Create a greeting', input: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'], additionalProperties: false, }, async execute(input) { return { content: `Hello ${(input as { name: string }).name}!` } }, }) }) }, })
1234567891011121314// V1 import { tool } from '@opencode-ai/plugin' return { tool: { greeting: tool({ description: 'Create a greeting', args: { name: z.string() }, async execute({ name }) { return `Hello ${name}!` }, }), }, }
input accepts an Effect Schema, any Standard Schema (zod) or raw JSON Schema. The V1 zod version clash between the plugin package and your app is gone.execute(input, context) gets { sessionID, agent, messageID, id, signal, progress }. Pass context.signal to every wait, so an interrupt stops your tool. progress(metadata) replaces the tool metadata; it does not append.12345async execute(input, context) { await context.progress({ status: 'uploading' }) const files = await waitForUpload({ signal: context.signal }) return { content: `Uploaded ${files.length} files`, metadata: { files: files.length } } }
options: { codemode: false } keeps a tool callable directly instead of only through code mode.null for optional fields. Schema.optional(Schema.String) rejected until: null in our port. Accept null and normalize:1234input: Schema.Struct({ duration: Schema.optional(Schema.NullOr(Schema.String)), until: Schema.optional(Schema.NullOr(Schema.String)), }),
minimum, maximum, maxLength, enum) and check them again in execute. Kimaki, for example, limits upload maxFiles to an integer from 1 to 10, and action buttons to 1 to 3 buttons with labels of 1 to 80 characters and a fixed color set.ctx is a working server client. V1 plugins built their own SDK client from serverUrl, because the plugin-provided V1 client silently did nothing for some REST calls. Delete that workaround.1234567// V1 const client = createOpencodeClient({ baseUrl: serverUrl.toString(), directory, headers: authHeaders() }) const result = await client.session.get({ path: { id: sessionID } }) if (result.data?.directory) { /* ... */ } // V2 const session = await ctx.session.get({ sessionID }) // value or rejection, no .data
ctx shape in @opencode/plugin 2.0.29:| Field | Main members | Notes |
app | name, version, channel | host app info |
location | directory | the loading location, not the session's |
options | plain object | from { package, options } in config |
session | create get remove switchAgent switchModel prompt generate command compact synthetic interrupt update move wait context, hook | no fork, instructions, form: use @opencode/client |
tool | transform, reload, list, hook | hooks: execute.before, execute.after |
shell | hook('create.before') | no sessionID |
event | subscribe | whole server bus |
permission | list get reply, hook('evaluate'), assert | |
skill | skill API, transform, reload | per location, visible in every session |
integration | integration API, transform, reload, connection.* | auth methods live here |
credential | activate | switch the active account |
agent, command, model, provider, mcp, reference, websearch, vcs, worktree | API plus transform and reload | |
rpc | register(definition, handlers) | typed plugin RPC |
storage | get set remove scan | durable JSON scoped to the plugin |
generate | text({ prompt, model }) | one-shot model call |
plugin | list | |
aisdk | AI SDK domain | provider packages |
@opencode/plugin/promise/session: SessionPrompt, SessionContext, SessionCompaction, SessionModelRequest, SessionHttpRequest, SessionRetry and more. Use them to share one handler across hook kinds.ctx.command.transform registers a slash command implemented in code. ctx.worktree.transform registers a worktree provider, replacing V1 workspace adaptor plugins:123456789await ctx.command.transform((editor) => { editor.add({ name: 'standup', description: 'Summarize my commits since yesterday', async execute({ sessionID, prompt, delivery }) { await ctx.session.prompt({ sessionID, text: `Summarize commits since yesterday. ${prompt.text}`, delivery }) }, }) })
ctx.storage is a durable JSON key-value store scoped to your plugin and shared across locations. Values must be JSON.1234567await ctx.storage.set('block/openai', { until: Date.now() + 60_000 }) let after: string | undefined do { const page = await ctx.storage.scan({ prefix: 'block/', after, limit: 1000 }) for (const entry of page.entries) console.log(entry.key, entry.value) after = page.next } while (after)
POST /api/rpc/<id>/<method> with a body { input }; the response is { output }. RPC events reach the bus as rpc.<id>.<event> and are live-only.import { Plugin, Rpc } from '@opencode/plugin' export const StatusRpc = Rpc.define({ id: 'status', methods: { blocks: { input: { type: 'object' }, output: { type: 'object' } } }, events: { switched: { schema: { type: 'object' } } }, }) export default Plugin.define({ id: 'status', async setup(ctx) { const rpc = await ctx.rpc.register(StatusRpc, { blocks: async () => ({ blocks: await readBlocks() }), }) await rpc.events.emit('switched', { sessionID: 'ses_123', to: 'openai/gpt-6' }) }, })
undefined values (omit the key), JSON Schema inputs type as unknown (narrow once), and RPC is one-way (client to plugin). Kimaki tried RPC for CLI to bot calls and dropped it for plain HTTP.tsc build input and load the built directory. Do not exclude it from the build, export a raw .ts entry, or rely on OpenCode to transpile your source.export default Plugin.define(...). Unlike V1, other named exports are harmless: the V2 loader reads only default. Kimaki's auth plugin exports helpers and an error class next to it. Still, keep helpers in separate files so the entry stays small.id. OpenCode keeps one plugin per ID and reports a second one as Duplicate plugin ID. If a user lists your plugin in opencode.json and you also install it, remove one.dist, not src. OpenCode watches plugin files and reloads on change. A src target loads half-edited code on every save; in our port it crashed the service.plugins: ["./probe.ts"] is ignored. In 2.0.19 a standalone file was silently skipped and tools failed with Unknown tool.server entry before index, plus tui and rpc entries. A stray server.js next to your index.js wins.console.*, no stdout or stderr writes; they show up in the TUI. Fail silently and return.12345// V1: key `plugin`, file URLs { "plugin": ["file:///home/me/app/dist/my-plugin.js"] } // V2: key `plugins`, directories, optional options { "plugins": ["./plugins/probe", { "package": "./plugins/discord", "options": { "channel": "general" } }] }
ctx.options holds the options object. Plugins dropped into <config dir>/plugins/<name>/ are auto-discovered and watched, with no config edit. Kimaki writes a one-line shim there on start:12// <config dir>/plugins/kimaki/index.js, generated export { default } from 'file:///path/to/kimaki/dist/plugin/index.js'
plugin.awaitActivation was removed in 2.0.19, so poll plugin.list with a deadline before creating sessions:123456789101112async function waitForPlugin({ client, directory, id }: { client: OpenCodeClient; directory: string; id: string }) { const location = { directory } const deadline = Date.now() + 10_000 while (Date.now() < deadline) { // integration.list waits for activations OpenCode already started; plugin.list does not. await client.integration.list({ location }) const plugins = await client.plugin.list({ location }) if (plugins.data.some((plugin) => plugin.id === id && plugin.state.status === 'active')) return await new Promise((resolve) => setTimeout(resolve, 200)) } return new Error(`plugin ${id} is not active in ${directory}`) }
plugin.list items have state: { status, error? }, not a string state. In tests, assert that no plugin is failed.setup() can run once per location in the same process, while module code and globalThis are process-wide.OpenCode service process ├── module scope / globalThis shared by all locations ├── setup(ctx) for /repo/a ──> ctx.location.directory = /repo/a ├── setup(ctx) for /repo/b ──> ctx.location.directory = /repo/b └── event bus carries events from every location
globalThis as a singleton guard.sessionID, never by "the current session".ctx.location.directory.setup aborts your subscriptions. It must not stop other processes.const KEY = Symbol.for('my-plugin.gateway') type Shared = { refs: number; stop: () => void; starting?: Promise<void> } const g = globalThis as typeof globalThis & { [KEY]?: Shared } export default Plugin.define({ id: 'my-plugin', async setup(ctx) { if (!g[KEY]) { const shared: Shared = { refs: 0, stop: () => {} } g[KEY] = shared shared.starting = startGateway().then((stop) => { shared.stop = stop }) } await g[KEY].starting g[KEY].refs++ return () => { const shared = g[KEY] if (!shared || --shared.refs > 0) return shared.stop() g[KEY] = undefined } }, })
setup ran once per location (duplicate clicks), and a cleanup that reset process-wide state wiped the pending buttons of every project when one location unloaded.ctx.location is the loading directory, not the session's directory. A session moved to a worktree still fires hooks in whatever location handles it. Use ctx.session.get({ sessionID }) for session facts.reload(); reload does not rerun setup. Put anything per session in a hook.opencode reload) runs cleanup and setup again, cancels pending forms and permissions, and lets running sessions continue at the next step. Return a cleanup that stops your timers, and unref() them so they never keep the server alive:1234567891011const timers = new Map<string, NodeJS.Timeout>() function schedule(sessionID: string, ms: number, run: () => Promise<void>) { clearTimeout(timers.get(sessionID)) const timer = setTimeout(() => void run().catch(() => {}), ms) timer.unref?.() timers.set(sessionID, timer) } return () => { for (const timer of timers.values()) clearTimeout(timer) timers.clear() }
metadata at session.create, then return early in every hook when the marker is missing. For subagents, walk the parent chain to find the marker.1234await ctx.session.hook('context', async (event) => { if (!(await isMine(event.sessionID))) return // only change prompts of sessions your integration created })
1234await client.session.create({ location: { directory }, metadata: { myapp: { threadId, channelId, dataDir, port } }, })
const MARKERS = Symbol.for('myapp.markers') const cache: Map<string, Promise<Record<string, unknown> | null>> = (Reflect.get(globalThis, MARKERS) as Map<string, Promise<Record<string, unknown> | null>>) ?? new Map() Reflect.set(globalThis, MARKERS, cache) async function readMarker(ctx: Plugin.Context, sessionID: string): Promise<Record<string, unknown> | null> { const session = await ctx.session.get({ sessionID }).catch(() => null) const value: unknown = session?.metadata?.['myapp'] if (value && typeof value === 'object' && !Array.isArray(value)) return value as Record<string, unknown> if (!session?.parentID) return null return readMarker(ctx, session.parentID) } function isMine(ctx: Plugin.Context, sessionID: string) { const cached = cache.get(sessionID) if (cached) return cached const marker = readMarker(ctx, sessionID) cache.set(sessionID, marker) return marker }
session.update({ metadata }) replaces the whole object. Merge before you write: metadata: { ...info.metadata, myapp: { ...old, port } }.OpenCode session ID system line, and provider auth, which lives in a separate plugin.| Previous behavior | Required result |
| Provider routing plugin | Load the native provider or plugin and test activation |
| Prompt injection guard | Port the scanning hooks, or remove the user option with an error |
| File edit tracking | Record native edit, write, apply_patch success facts |
| Image optimization | Port before file admission, or document the removal |
| Prompt cache drift check | Port to native hooks, or document the removal |
| Worktree adaptation | Replace with native location and worktree behavior |
| Provider auth rotation | Use native integration support, or document the removal |
| Terminal image output | Keep only where the host still supports it |
| V1 plugin | V2 decision |
| interrupt (3s abort and replay) | deleted, native inbox steer |
| memory overview | deleted |
| cache drift check | deleted, instruction entries keep the prefix stable |
| image optimizer | deleted, V2 resizes images |
| task ID sanitizer | deleted |
| context awareness | ported, branch only, prompt hook plus synthetic message |
| bash schema | ported, context hook edits event.tools.shell.input |
| file edit log | ported, execute.after |
| IPC tools | deleted, replaced by CLI commands |
| Anthropic auth | ported, separate plugin with integration and http.request |
| OpenAI and xAI account rotation | replaced by a fallback plugin with the retry hook |
| workspace adaptor | replaced by own git worktrees plus session.move |
| injection guard | removed |
@opencode-ai/sdk/v2 is not the V2 SDK. It is a V1-era transitional client over a mix of legacy and V2 routes. Changing the import from @opencode-ai/sdk to @opencode-ai/sdk/v2 migrates nothing. The upstream internal checklist calls it a legacy client, despite the export name.| Role | OpenCode V1 | OpenCode V2 |
| Network client | @opencode-ai/sdk, including its /v2 export | @opencode/client |
| Embedded host | @opencode-ai/sdk | @opencode/sdk |
| Plugin API | @opencode-ai/plugin | @opencode/plugin |
| Native CLI | opencode-ai | @opencode/cli |
12rg -n "@opencode-ai/(sdk|plugin)" --glob '!**/node_modules/**' --glob '!**/dist/**' rg -n "createOpencodeClient|promptAsync|session\.abort|client\.global\.event|event\.properties" src
@opencode/* packages to the same exact version (no ^). The API changed between V2 releases with no release notes, see the rename table.1pnpm add @opencode/client@2.0.19 @opencode/plugin@2.0.19
node_modules/@opencode/client/dist/promise/generated/types.d.ts of the version you installed.opencode serve. V2 runs one background service per user, shared by the TUI, the desktop app, the web app and your integration. Connect to it instead of starting your own.V1 V2 ───────────────────────────── ─────────────────────────────────────── your bot ──spawn──> opencode serve TUI ──────┐ TUI ──spawn──> opencode serve desktop ──┼──> one OpenCode service ──> many locations (one server per client) your bot ─┘ ~/.local/state/opencode/service.json
Service.discover() reads the registration file. Service.ensure() starts a service when none runs.12345// V1: own child process, own password import { createOpencodeClient } from '@opencode-ai/sdk' const child = spawn(opencodeBin, ['serve', '--port', String(port), '--hostname', '127.0.0.1', '--print-logs', '--log-level', 'WARN'], { env }) const client = createOpencodeClient({ baseUrl: `http://127.0.0.1:${port}`, directory })
123456789101112// V2: the user's shared service import { OpenCode } from '@opencode/client' import { Service } from '@opencode/client/service' const discovered = await Service.discover() const endpoint = discovered ?? (await Service.ensure({ command: [binary, 'serve', '--service', '--hostname', '127.0.0.1'], })) const client = OpenCode.make({ baseUrl: endpoint.url, headers: Service.headers(endpoint) }) const info = await client.server.info({ signal: AbortSignal.timeout(5_000) }) if (!atLeast(info.version)) throw new Error(`OpenCode ${info.version} is too old, upgrade to 2.0.19+`)
ensure():ensure() replaces a running service of another version. That kills the user's live TUI sessions. Check server.info() and tell the user to upgrade instead.command explicitly. The default is opencode from PATH, which can be V1. V1 prints help for serve --service, exits, and ensure fails with a vague error. Use the binary finder.discover() returns no version. Always call server.info().--hostname 127.0.0.1. A V1 server.hostname or mDNS config can otherwise bind 0.0.0.0.opencode. Service.headers(endpoint) builds the header from the registration file. Without the helper:123456const client = OpenCode.make({ baseUrl, headers: { Authorization: `Basic ${Buffer.from(`opencode:${password}`).toString('base64')}`, }, })
| Topic | V1 | V2 |
| Password env | OPENCODE_SERVER_PASSWORD, _USERNAME | OPENCODE_PASSWORD, ignored in service mode |
| Service password | your env var | only in service.json (mode 0600) |
| Health probe | GET /api/health | GET /api/info, authenticated |
| Serve flags | --print-logs --log-level WARN | removed |
401.401 or 403 means "not ready", never "below 500, so fine".123async function ready(client: OpenCodeClient, signal: AbortSignal) { return client.server.info({ signal }).then(() => true, () => false) }
endpoint objects leak it too..data, .error, nested path / query / body and throwOnError.| V1 behavior | V2 replacement |
createOpencodeClient({ baseUrl, directory }) | OpenCode.make({ baseUrl, headers }), location per call |
{ data, error } result | value, or a rejected promise |
session.create({ directory, permission }) | session.create({ location: { directory }, permissions }) |
session.promptAsync({ parts }) | session.prompt({ sessionID, text, files, delivery }) |
promptAsync({ noReply: true }) | session.prompt({ sessionID, text, resume: false }) |
| synthetic context without a reply | session.synthetic({ sessionID, text, resume: false }) |
promptAsync({ system }) | session.instructions.entry.put({ sessionID, key, value }) |
per-prompt agent, model, variant | session.switchAgent / session.switchModel first |
session.abort(...) | session.interrupt({ sessionID, resume? }) |
session.update({ permission }) | session.update({ sessionID, permissions }) |
session.messages | message.list({ sessionID, order, cursor, limit }) |
session.status() polling | session.active() plus execution events |
session.summarize | session.compact |
session.delete | session.remove |
question.reply({ requestID, answers }) | session.form.reply({ sessionID, formID, answer }) |
permission.reply({ requestID, reply }) | permission.reply({ sessionID, requestID, decision }) |
client.global.event() | client.event.subscribe({ signal, onActivity }) |
session.share | none in V2 |
1234// V1 const result = await client.session.create({ directory, permission: rules }) if (result.error || !result.data) throw new Error(String(result.error)) const session = result.data
123456789// V2 const session = await client.session.create({ title: 'Review the current changes', location: { directory }, agent: 'build', model: { providerID: 'anthropic', id: 'claude-opus-4-6' }, permissions: [{ action: 'edit', resource: `${directory}/**`, effect: 'allow' }], metadata: { myapp: { threadId } }, })
session.prompt returns the accepted inbox item, not the reply. The answer only arrives through events. The prompt has no agent, model, system or parts fields; that was the biggest hidden surprise of our port.12345678910111213// V1 await client.session.promptAsync({ sessionID, directory, parts: [ { type: 'text', text }, { type: 'text', text: context, synthetic: true }, ...imageParts, ], system, agent, model: { providerID, modelID }, })
12345678910// V2 await client.session.prompt({ sessionID, id: `msg_chat_${chatMessageId}`, // optional, idempotent, must start with msg_ text, files: [{ uri: 'file:///tmp/screenshot.png', name: 'screenshot.png' }], skills: [{ id: 'playwriter' }], delivery: 'steer', // or 'queue' metadata: { chat: { userId, messageId } }, // shows up in inbox.enqueued payload })
12// V1 await client.session.abort({ sessionID, directory })
123// V2: resume false stops; resume true lets queued input continue const result = await client.session.interrupt({ sessionID, resume: false }) // result.interrupted is false when nothing ran: treat it as success
noReply: true has no direct twin. resume: false admits the item without waking execution. It is delivered with the next turn.12// V1 await client.session.promptAsync({ sessionID, directory, parts, noReply: true })
1234// V2: a user message that should not start a turn await client.session.prompt({ sessionID, text, resume: false }) // V2: model context that is not a user message await client.session.synthetic({ sessionID, text, delivery: 'steer', resume: false })
noReply does not work. If you queue a context-only prompt without resume: false, the inbox delivers it later and the agent starts a turn and replies.12// V1: system string sent with every prompt await client.session.promptAsync({ sessionID, parts, system: buildSystemPrompt() })
12// V2: written once, stored by OpenCode, inherited by forks await client.session.instructions.entry.put({ sessionID, key: 'myapp', value: buildSystemPrompt() })
/experimental/. See instruction entries and the prompt cache.12// V1 await client.question.reply({ requestID, directory, answers: [['Red'], ['Apple', 'Kiwi']] })
123// V2: answers keyed by field, not positional await client.session.form.reply({ sessionID, formID, answer: { q0: 'Red', q1: ['Apple', 'Kiwi'] } }) await client.session.form.cancel({ sessionID, formID })
| Operation | V2 call |
| Create a session | session.create({ location, permissions, agent, model, metadata }) |
| Read one session | session.get({ sessionID }) |
| Admit a user prompt | session.prompt({ sessionID, text, files?, delivery? }) |
| Admit synthetic context | session.synthetic({ sessionID, text, delivery, resume }) |
| Interrupt execution | session.interrupt({ sessionID, resume? }) |
| Store system instructions | session.instructions.entry.put({ sessionID, key, value }) |
| Change agent or model | session.switchAgent(...) / session.switchModel(...) |
| Rename | session.update({ sessionID, title }) |
| Change rules | session.update({ sessionID, permissions }) |
| Busy sessions | session.active(), keys are running session IDs |
| Pending input | session.inbox.list / cancel / update |
| Pending questions | session.form.list / reply / cancel |
| Pending permissions | permission.list / reply |
| User shell command | session.shell({ sessionID, command }) |
| Run a command | session.command({ sessionID, name, text, files, delivery }) |
| Compact | session.compact({ sessionID }) |
| Fork | session.fork({ sessionID, before? }) |
| Move to another directory | session.move({ sessionID, directory, delivery }) |
| Wait until idle (experimental) | session.wait({ sessionID }) |
| Mark read in the sidebar | session.view({ sessionID, idle }) |
| Agents, commands, models | agent.list, command.list, model.list with { location } |
{ data, cursor }. cursor.next is opaque. This covers message.list, session.list, agent.list, command.list, model.list and shell.list.1234567891011121314async function allMessages(client: OpenCodeClient, sessionID: string) { const messages = [] let cursor: string | undefined do { const page = await client.message.list({ sessionID, limit: 200, ...(cursor ? { cursor } : { order: 'asc' }), }) messages.push(...page.data) cursor = page.cursor?.next ?? undefined } while (cursor) return messages }
message.list is newest first by default. Pass order: 'asc' before you render markdown or pick the latest user turn.cursor must not be combined with order. The cursor already carries it.limit is at most 200.12345678// V1: one client per directory const client = createOpencodeClient({ baseUrl, directory }) clientCache.set(directory, client) // V2: one client, location in the call const client = OpenCode.make({ baseUrl: endpoint.url, headers: Service.headers(endpoint) }) await client.agent.list({ location: { directory } }) await client.session.prompt({ sessionID, text }) // session calls resolve the stored location
session.create. Later session calls only need sessionID.location: { directory }, the x-opencode-directory header, or ?location[directory]= in raw HTTP. Not ?directory=.session.list without scope is global across every project. See ordered and scoped reads.V2_HTTP_API_AUDIT.md on the v2 branch. If you ported against an early V2, these renames will hit you:| 2.0.2 | 2.0.19 |
plugin.awaitActivation | removed; prompt, command and shell handlers wait server side |
permission.rules({ sessionID, permissions }) | session.update({ sessionID, permissions }) |
permission.reply({ reply }) | permission.reply({ decision }) |
session.rename({ sessionID, title }) | session.update({ sessionID, title }) |
session.fork({ boundary: { type: 'through' } }) | session.fork({ sessionID }) |
session.fork({ boundary: { type: 'before', messageID } }) | session.fork({ sessionID, before: messageID }) |
session.interrupt({ continue }) | session.interrupt({ resume }) |
session.command({ command }) | session.command({ name }) |
form.list / reply / cancel({ sessionID, ... }) | session.form.list / reply / cancel(...), form.state removed |
worktree.*({ location }) | worktree.*({ projectID }), from location.get().project.id |
project.time.initialized | removed |
GET /api/health | GET /api/info |
session.step.started event | now carries data.started |
session.form.list returns only pending forms. model.list does not wait for plugin activation, so an early read can miss plugin providers.AbortSignal, reconnect, fold text and tools, and stop when the execution ends. Run it with tsx example.ts "list the files in this repo".import { OpenCode, type OpenCodeClient, type V2Event } from '@opencode/client' import { Service } from '@opencode/client/service' import { setTimeout as sleep } from 'node:timers/promises' const STREAM_IDLE_TIMEOUT_MS = 45_000 const MAX_BACKOFF_MS = 30_000 async function connect() { const endpoint = (await Service.discover()) ?? (await Service.ensure({ command: ['opencode', 'serve', '--service', '--hostname', '127.0.0.1'], })) const client = OpenCode.make({ baseUrl: endpoint.url, headers: Service.headers(endpoint) }) const info = await client.server.info({ signal: AbortSignal.timeout(5_000) }) console.error(`connected to OpenCode ${info.version}`) return client } function eventSessionId(event: V2Event): string | null { if (event.type === 'form.created') return event.data.form.sessionID const data: Record<string, unknown> = event.data return typeof data['sessionID'] === 'string' ? data['sessionID'] : null } type View = { toolNames: Map<string, string>; done: boolean } // Pure fold: one event in, printed lines out. function fold(view: View, event: V2Event): string[] { switch (event.type) { case 'session.text.ended': return event.data.text.trim() ? [event.data.text.trim()] : [] case 'session.tool.input.started': view.toolNames.set(`${event.data.assistantMessageID}:${event.data.id}`, event.data.name) return [] case 'session.tool.called': { const name = view.toolNames.get(`${event.data.assistantMessageID}:${event.data.id}`) ?? 'tool' return [` > ${name} ${JSON.stringify(event.data.input).slice(0, 80)}`] } case 'session.tool.failed': if (event.data.error.type === 'aborted') return [] return [` x ${event.data.error.message}`] case 'session.execution.succeeded': view.done = true return ['done'] case 'session.execution.failed': view.done = true return [`failed: ${event.data.error.message}`] case 'session.execution.interrupted': view.done = true return [`interrupted: ${event.data.reason}`] default: return [] } } async function watch({ client, sessionID, signal }: { client: OpenCodeClient; sessionID: string; signal: AbortSignal }) { const view: View = { toolNames: new Map(), done: false } let backoff = 500 while (!signal.aborted && !view.done) { const attempt = new AbortController() const attemptSignal = AbortSignal.any([signal, attempt.signal]) let timer: NodeJS.Timeout | undefined // The server sends a keepalive every 15s; silence means a half-open stream. const touch = () => { clearTimeout(timer) timer = setTimeout(() => attempt.abort(), STREAM_IDLE_TIMEOUT_MS) } touch() try { const stream = client.event.subscribe({ signal: attemptSignal, onActivity: touch }) let first = true for await (const event of stream) { if (first) { if (event.type !== 'server.connected') throw new Error('first event was not server.connected') first = false backoff = 500 // Hydrate: did the run end while we were away? const active = await client.session.active({ signal: attemptSignal }) if (!(sessionID in active)) { view.done = true console.log('session is idle') break } continue } if (eventSessionId(event) !== sessionID) continue for (const line of fold(view, event)) console.log(line) if (view.done) break } } catch (error) { if (signal.aborted) break console.error('stream lost, reconnecting', error instanceof Error ? error.message : error) } finally { clearTimeout(timer) attempt.abort() } if (view.done) break await sleep(backoff, undefined, { signal }).catch(() => {}) backoff = Math.min(backoff * 2, MAX_BACKOFF_MS) } } async function main() { const text = process.argv[2] ?? 'Say hello in one sentence.' const controller = new AbortController() process.on('SIGINT', () => controller.abort()) const client = await connect() const session = await client.session.create({ title: 'example', location: { directory: process.cwd() }, metadata: { example: { createdBy: 'example.ts' } }, }) await client.session.instructions.entry.put({ sessionID: session.id, key: 'example', value: 'Answer briefly. You are driven by a script, not a human.', }) // Subscribe before prompting, so no event of the first turn is missed. const watching = watch({ client, sessionID: session.id, signal: controller.signal }) await sleep(200) await client.session.prompt({ sessionID: session.id, text, delivery: 'steer' }) await watching } await main()
sleep(200) is a shortcut. A real integration keeps one long-lived subscription for the whole process and binds the new session in its routing map before calling session.prompt. Then no wait is needed.session.prompt() │ returns the inbox item ▼ session.inbox.enqueued ──────────> (admitted, pending) session.execution.started ───────> busy period starts, typing on session.inbox.delivered ─────────> prompt becomes visible history │ ├── session.step.started one model call (model, agent) │ ├── session.text.started / delta… / ended │ ├── session.tool.input.started (name) / delta… / ended │ ├── session.tool.called (parsed input) / progress… / success | failed │ └── session.step.ended tokens of this call ├── session.step.started … more steps while tools run │ └── session.execution.succeeded | failed | interrupted
session.prompt call only means the inbox accepted the item. One inbox item can produce many steps while tools and retries run. One execution can also consume several inbox items.| V1 event | V2 replacement |
message.part.updated (with partID, state) | session.text.*, session.reasoning.*, session.tool.*. No partID, no part states |
message.updated (natural completion) | session.step.ended per model call, session.execution.succeeded per busy period |
session.idle | session.execution.succeeded / failed / interrupted |
session.status (busy, idle, retry) | session.execution.started plus terminal events, session.retry.scheduled |
session.error | session.execution.failed, session.step.failed, session.tool.failed |
question.asked / question.replied | form.created with metadata.kind === 'question', form.replied, form.cancelled |
permission.asked / permission.replied | same names, new payload (action, resources, save, source) |
session.updated (title) | session.renamed { title } |
| none | session.inbox.enqueued / delivered / cancelled / delivery.changed |
| none | session.shell.started / ended (user !cmd) |
| none | session.compaction.started / delta / ended / failed |
| none | session.forked, session.moved, session.agent.selected, session.model.selected |
session.status and session.idle still exist in the schema, but V2 core does not publish them. Code waiting for session.idle waits forever.event.properties; V2 uses event.data.123456789type Envelope = { id: string // evt_... type: string created: number // epoch ms; server.connected has none location?: { directory: string } metadata?: Record<string, unknown> data: unknown durable?: { aggregateID: string; seq: number; version: number } // seq counts per session }
data.sessionID. form.created carries it in data.form.sessionID. Global events (shell.created, shell.exited, skill.updated, project.updated) carry none.1{"id":"evt_0f1fe238…","type":"server.connected","data":{}}
1234{"type":"session.created","data":{"sessionID":"ses_f0dfeef7…","slug":"quiet-engine","version":"2.0.19", "projectID":"05de62d3…","location":{"directory":"/repo"},"title":"abort", "model":{"id":"gpt-6-luna","providerID":"openai","variant":"low"}}, "durable":{"aggregateID":"ses_f0dfeef7…","seq":0,"version":1}}
parentID and agent:123{"type":"session.created","data":{"sessionID":"ses_f0dfdb26…","parentID":"ses_f0dfdbc0…", "title":"Find SQLite schema file","agent":"general", "model":{"id":"gpt-6-luna","providerID":"openai","variant":"low"}}}
delivered carries only the ID, so keep the text from enqueued:1234{"type":"session.inbox.enqueued","data":{"inboxID":"msg_0f201109…","sessionID":"ses_f0dfeef7…", "item":{"type":"user","payload":{"text":"Run `sleep 30 && echo never`, then summarize."},"delivery":"steer"}}, "durable":{"aggregateID":"ses_f0dfeef7…","seq":1,"version":1}} {"type":"session.inbox.delivered","data":{"sessionID":"ses_f0dfeef7…","inboxID":"msg_0f201109…"}}
synthetic (shell output, subagent results, plan mode notes) and compaction:12{"type":"session.inbox.enqueued","data":{"inboxID":"msg_0f2017b8…","sessionID":"ses_f0dfe955…", "item":{"type":"compaction","payload":{},"delivery":"steer"}}}
execution.succeeded carries only the session ID: no duration, no tokens.12345678{"type":"session.execution.started","data":{"sessionID":"ses_f0dfeef7…"},"durable":{"seq":2}} {"type":"session.step.started","data":{"sessionID":"ses_…","agent":"build", "model":{"id":"gpt-6-luna","providerID":"openai","variant":"low"}, "assistantMessageID":"msg_0f20110a…","started":1790766551209}} {"type":"session.step.ended","data":{"sessionID":"ses_…","assistantMessageID":"msg_0f201209…", "finish":"stop","cost":0,"tokens":{"input":897,"output":8,"reasoning":0,"cache":{"read":24064,"write":0}}}} {"type":"session.execution.succeeded","data":{"sessionID":"ses_f0dfeef7…"},"durable":{"seq":21}} {"type":"session.execution.interrupted","data":{"sessionID":"ses_…","reason":"user"}}
finish is "tool-calls" or "stop". The interrupt reason is user, shutdown, superseded or inactivity.delta is live only; ended has the full text:1234{"type":"session.text.started","data":{"sessionID":"ses_…","assistantMessageID":"msg_0f201209…","ordinal":0}} {"type":"session.text.delta","data":{"sessionID":"ses_…","assistantMessageID":"msg_0f201209…","ordinal":0,"delta":"resumed after abort"}} {"type":"session.text.ended","data":{"sessionID":"ses_…","assistantMessageID":"msg_0f201209…","ordinal":0, "text":"resumed after abort","state":{"itemId":"msg_0d818140…","phase":"final_answer"}}}
state.phase is provider specific (OpenAI). Do not depend on it.tool.input.started is the only event with the tool name. tool.called has the parsed input but no name:12345678910111213{"type":"session.tool.input.started","data":{"sessionID":"ses_…","assistantMessageID":"msg_0f20110a…", "id":"call_lLObP9GZ…","name":"shell"}} {"type":"session.tool.input.ended","data":{"sessionID":"ses_…","assistantMessageID":"msg_0f20110a…", "id":"call_lLObP9GZ…","text":"{\"command\":\"sleep 30 && echo never\"}"}} {"type":"session.tool.called","data":{"sessionID":"ses_…","assistantMessageID":"msg_0f20110a…", "id":"call_lLObP9GZ…","input":{"command":"sleep 30 && echo never"},"executed":false}} {"type":"session.tool.progress","data":{"sessionID":"ses_…","assistantMessageID":"msg_0f20110a…", "id":"call_lLObP9GZ…","metadata":{"shellID":"sh_0f201178…"}}} {"type":"session.tool.success","data":{"sessionID":"ses_…","assistantMessageID":"msg_0f202ace…", "id":"call_ZXxEebKO…","content":[{"type":"text","text":"first\n"}], "metadata":{"status":"completed","truncated":false,"exit":0},"executed":false}} {"type":"session.tool.failed","data":{"sessionID":"ses_…","assistantMessageID":"msg_0f20110a…","id":"call_lLObP9GZ…", "error":{"type":"aborted","message":"Tool execution interrupted"},"executed":false}}
content is an array of content items, not the V1 state.output string. The shell tool also no longer appends "Command exited with code 0."123456789101112{"type":"form.created","data":{"form":{"id":"frm_0f1ff040…","sessionID":"ses_f0e01095…","title":"Questions", "metadata":{"kind":"question","tool":{"messageID":"msg_0f1fef6c…","id":"call_BavYrlCj…"}}, "fields":[ {"key":"q0","title":"Color","description":"Which color do you prefer?","type":"string", "options":[{"value":"Red","label":"Red","description":"Red"}],"custom":true}, {"key":"q1","title":"Fruits","type":"multiselect", "options":[{"value":"Apple","label":"Apple","description":"Apple"}],"custom":true}]}}} {"type":"form.replied","data":{"id":"frm_0f1ff040…","sessionID":"ses_f0e01095…","answer":{"q0":"green","q1":["apple","kiwi"]}}} {"type":"permission.asked","data":{"id":"per_0f202b5a…","sessionID":"ses_f0dfd533…", "action":"shell","resources":["echo first"],"save":["echo *"], "source":{"type":"tool","messageID":"msg_0f202ace…","id":"call_ZXxEebKO…"}}} {"type":"permission.replied","data":{"sessionID":"ses_f0dfd533…","requestID":"per_0f202b5a…","reply":"once"}}
12345678910// session.retry.scheduled (durable) { sessionID, assistantMessageID, attempt: number, at: number /* epoch ms of next try */, error: SessionError } // session.execution.failed (durable) { sessionID, error: SessionError } // SessionError { type: string, message: string, status?: number, response?: { body: string } } // session.moved { sessionID, location: { directory } } // session.compaction.failed { sessionID, reason: 'auto' | 'manual', error: SessionError, inputID?, cost, tokens }
durable block is part of the session's stored history.| Live event | Live value | Durable boundary |
session.text.delta | data.delta chunk | session.text.ended with full data.text |
session.reasoning.delta | data.delta chunk | session.reasoning.ended with full data.text |
session.tool.input.delta | raw JSON chunk | session.tool.input.ended with full raw input |
session.tool.progress | replacement progress metadata | session.tool.success or session.tool.failed |
session.compaction.delta | text chunk | session.compaction.ended with full text |
session.usage.updated | cumulative tokens | session.step.ended tokens per call |
permission.*, form.*, tui.toast.show, vcs.branch.updated, server.connected and plugin rpc.* events.skill.updated (dozens per turn), project.updated, provider.updated, model.updated, agent.updated, command.updated, plugin.updated, worktree.updated, integration.updated. Drop them before per-session routing. Watch only the catalog ones you need:1const CATALOG_EVENTS = new Set(['model.updated', 'provider.updated', 'integration.updated', 'credential.updated', 'credential.switched'])
partID. Concurrent tool and producer fibers interleave events, so global event order is not a part identity. Key live state like this:| Content | Identity key |
| Text, reasoning | sessionID + assistantMessageID + ordinal |
| Tool call | sessionID + assistantMessageID + id |
| Compaction | inputID of the compaction inbox item |
ended, success or failed event, replace the live buffer with the complete terminal value. If you render append-only (a chat bot, a log), you can skip deltas entirely and render from terminal events:function toolKey(data: { assistantMessageID: string; id: string }) { return `${data.assistantMessageID}:${data.id}` } switch (event.type) { case 'session.text.ended': { const text = event.data.text.trim() if (text) emit({ type: 'markdown', text, blankLineBefore: view.lastKind === 'tool' }) view.lastKind = 'text' return } case 'session.tool.input.started': view.tools[toolKey(event.data)] = { name: event.data.name } return case 'session.tool.called': { // Fallback name when the subscription started after input.started. const name = view.tools[toolKey(event.data)]?.name ?? 'tool' emit({ type: 'send', text: formatToolLine({ name, input: event.data.input }) }) view.lastKind = 'tool' return } case 'session.tool.success': case 'session.tool.failed': delete view.tools[toolKey(event.data)] return }
tool.called, not input.started. input.started has the name but the model is still streaming the JSON arguments:input.started name: shell, id: call_456 input.delta partial JSON {"command":"pnpm input.ended raw input text complete tool.called parsed input { command: "pnpm test" } <── render here
tool.called is tracked in anomalyco/opencode#35638.| Option | Effect |
delivery: 'steer' | admitted at the next safe step boundary of the current run |
delivery: 'queue' | waits until the current execution drains |
resume: false | admitted without waking execution; delivered with the next turn |
session.inbox.list returns only pending items; delivery removes the row in the same transaction that creates the visible user message.12345const inbox = await client.session.inbox.list({ sessionID }) const queued = inbox.filter((item) => item.type === 'user' && item.delivery === 'queue') await client.session.inbox.cancel({ sessionID, inboxID: queued[0].id }) // fires session.inbox.cancelled await client.session.inbox.update({ sessionID, inboxID: queued[1].id, delivery: 'steer' }) // fires delivery.changed
msg_. A repeated ID returns the existing item and starts nothing, so retries are idempotent.12345const promptId = (chatMessageId: string) => `msg_chat_${chatMessageId}` await client.session.prompt({ sessionID, id: promptId(message.id), text, delivery: 'queue' }) // user deleted the chat message await client.session.inbox.cancel({ sessionID, inboxID: promptId(message.id) })
inbox.update changes only delivery. Cancel and enqueue again with a new ID; the item moves to the end of the queue. Feature request: anomalyco/opencode#52275.12await client.session.inbox.cancel({ sessionID, inboxID }) await client.session.prompt({ sessionID, id: `${promptId(message.id)}_e${editedAt}`, text: message.content, delivery: 'queue' })
inbox.enqueued.data.item.payload.metadata. Use it to tell your prompts from prompts typed in the TUI. session.command takes no id and no metadata.1234// V1: a plugin inside OpenCode polled status, aborted, then replayed the prompt await client.session.abort({ sessionID, directory }) // session.abort() cleared the queued prompt, so it had to be sent again await client.session.promptAsync(replayParams)
1234567891011// V2: cancel pending UI ─> interrupt(resume false) ─> prompt(steer) export async function steer({ client, sessionID, text }: { client: OpenCodeClient; sessionID: string; text: string }) { for (const form of await client.session.form.list({ sessionID })) { await client.session.form.cancel({ sessionID, formID: form.id }) } for (const request of await client.permission.list({ sessionID })) { await client.permission.reply({ sessionID, requestID: request.id, decision: 'reject' }) } await client.session.interrupt({ sessionID, resume: false }) return client.session.prompt({ sessionID, text, delivery: 'steer' }) }
execution.interrupted; that caused duplicate runs in our first port.prompt(steer) then interrupt({ resume: true }), parks queued items forever: the resumed drain is steer-scoped and never promotes queue items. We found this only by recording real events. With interrupt first, the new prompt's wake has input scope: the steer runs, then the queue.| Event | Meaning | What to do |
session.execution.started | busy period starts | start duration timer and typing |
session.execution.succeeded | ran to natural completion | flush output, post footer, run analytics |
session.execution.failed | the run failed | show data.error.message, no footer |
session.execution.interrupted | stopped (reason) | no footer, no error line |
succeeded.created - started.created.execution.succeeded after both:inbox.enqueued A (steer) ─> execution.started ─> inbox.delivered A ─> steps… inbox.enqueued Q1 (queue) inbox.enqueued Q2 (queue) inbox.delivered Q1 ─> step.started ─> text.ended ─> step.ended inbox.delivered Q2 ─> step.started ─> text.ended ─> step.ended execution.succeeded <── only one
inbox.delivered of a queued user item as the turn boundary:123456789case 'session.inbox.delivered': { const queued = view.inbox.find((item) => item.inboxID === event.data.inboxID && item.delivery === 'queue') if (queued && view.turn?.model) { emit({ type: 'footer', durationMs: event.created - view.turn.startedAt, model: view.turn.model, notify: false }) view.turn.startedAt = event.created } view.inbox = view.inbox.filter((item) => item.inboxID !== event.data.inboxID) return }
step.started and no model. Skip the footer when you saw no step.session.wait({ sessionID }) (experimental) resolves when the session is idle. Use it before revert or after a move. It is not a "turn finished" check for users:--wait flag must subscribe to events and stop on the first terminal execution event, a pending form or a pending permission. Only session.execution.succeeded counts as success.question.* is gone. The built-in question tool creates a form with metadata.kind = "question". Fields are q0, q1… of type string (single choice) or multiselect, with options[] and custom: true when free text is allowed.123456789case 'form.created': { const form = event.data.form // sessionID is at data.form.sessionID showForm({ id: form.id, sessionID: form.sessionID, fields: form.fields, kind: form.metadata.kind }) return } case 'form.replied': case 'form.cancelled': closeForm(event.data.id) return
1234// answer by field key; arrays for multiselect await client.session.form.reply({ sessionID, formID, answer: { q0: 'Red', q1: ['Apple', 'Kiwi'] } }) // free text or dismiss await client.session.form.cancel({ sessionID, formID })
question. The first websearch call asks for a provider through a form of kind websearch.provider. We rendered only questions; OpenCode cancelled the form after one minute and every search failed with "Web search cancelled". Render generically: boolean as Yes/No, string without options as free text.12const NO_QUESTION_TOOL = { action: 'question', resource: '*', effect: 'deny' } as const await client.session.create({ location: { directory }, permissions: [NO_QUESTION_TOOL] })
permission.asked has action, resources, save and source. Reply with the ask's data.id as requestID.12// V1 await client.permission.reply({ requestID, directory, reply: 'reject', message: 'timed out' })
1234567// V2 case 'permission.asked': showPermission({ id: event.data.id, action: event.data.action, resources: event.data.resources }) return await client.permission.reply({ sessionID, requestID, decision: 'once' }) // 'once' | 'always' | 'reject' const pending = await client.permission.list({ sessionID })
always saves exactly the save patterns from the ask (for example ["echo *"]). A reply cannot widen them.promptAsync({ parts: [] }) to resume after a reject; delete that.{ action, resource, effect } and the last matching rule wins. The bash action is shell.session.form.list and permission.list after every reconnect.session.instructions.updated). That keeps the provider prompt cache hitting.session start ──> instructions (AGENTS.md, skills, entries, env) frozen as system baseline entry changes ──> session.instructions.updated ──> appended to history (delta only) compaction ──> new epoch, new baseline
context hook:12// Good: stored once, cache stays warm await client.session.instructions.entry.put({ sessionID, key: 'myapp', value: systemPrompt })
1234// Breaks the cache: runs on every request and sits before all messages await ctx.session.hook('context', async (event) => { event.system.push(`Current git branch: ${await currentBranch()}`) // any change busts the prefix })
session.synthetic note, written only when the branch changes.compaction and generate requests like context. We edited only context requests; compaction and OpenCode's warming keep-alive requests had a different prefix and rewrote the cache. Register one handler for all three hooks.metadata, rendered by your plugin into the model request only. Stored text stays clean for the TUI, and the same metadata always renders the same text.session.step.ended.tokens, not session.usage.updated. step.ended is durable and per model call. usage.updated is cumulative and live-only, so a delta needs a baseline you do not have after a restart.12345678type Tokens = { input: number; output: number; reasoning: number; cache: { read: number; write: number } } // OpenCode reports output without reasoning but bills both. const total = (t: Tokens) => t.input + t.output + t.reasoning + t.cache.read + t.cache.write case 'session.step.ended': if (view.turn) view.turn.tokens = total(event.data.tokens) // context size = last finished step return
model.list. Omit the percent when the limit is unknown; never print a fake 0%.12345678const models = await client.model.list({ location: { directory } }) const limits = Object.fromEntries(models.data.map((m) => [`${m.providerID}/${m.id}`, m.limit.context])) function contextPercent(tokens: number, model: { providerID: string; id: string }) { const limit = limits[`${model.providerID}/${model.id}`] if (!limit || tokens <= 0) return null return Math.round((tokens / limit) * 100) }
step.ended and step.failed tokens per execution (failed steps are billed), root and subagents, and emit on the terminal execution event. Skip executions you did not observe from their start.123456const CACHE_MISS_SLACK = 1_024 const read = event.data.tokens.cache.read if (view.cached && read + CACHE_MISS_SLACK < view.cached.tokens) { emit({ type: 'send', text: `prompt cache miss: read ${read}, expected ${view.cached.tokens}` }) } view.cached = { tokens: read + event.data.tokens.cache.write, at: event.created }
cached after compaction.session.compacted event.session.inbox.enqueued { item: { type: 'compaction', delivery: 'steer' } } session.compaction.started { reason: 'manual' | 'auto', inputID } session.compaction.delta { text } live only, many session.compaction.ended { reason, text, tokens, cost } session.execution.succeeded no step, no model
1234{"type":"session.compaction.ended","data":{"sessionID":"ses_…","reason":"manual", "text":"## Objective\n- Remember the secret word…", "recent":"[User]: What was the secret word?\n\n[Assistant]: mango", "tokens":{"input":1402,"output":98,"reasoning":0,"cache":{"read":24064,"write":0}},"cost":0}}
step.ended. Set a flag on compaction.ended and report the size then:1234567case 'session.compaction.ended': view.cached = null // new prefix: the first cache miss is expected view.compacted = true // size known when the next step reads it return case 'session.compaction.failed': if (event.data.error.type !== 'aborted') emit({ type: 'send', text: `compaction failed: ${event.data.error.message}` }) return
## Objective, …). A deterministic test provider must answer compaction requests with them.session.retry.scheduled { attempt, at, error } is durable. at is the epoch ms of the next try, so the delay is at - event.created. Always show error.message: a line like "retrying in 3s (attempt 2)" without the cause cannot be debugged later.1234567const RETRY_NOTICE_INTERVAL_MS = 10_000 case 'session.retry.scheduled': if (view.lastRetryAt !== null && event.created - view.lastRetryAt < RETRY_NOTICE_INTERVAL_MS) return view.lastRetryAt = event.created emit({ type: 'send', text: `retrying in ${Math.round((event.data.at - event.created) / 1000)}s (attempt ${event.data.attempt}): ${event.data.error.message}` }) return
session.error is gone. Errors arrive at three levels with one shape:| Event | Scope | Show it? |
session.tool.failed | one tool call | yes, except aborted, the question tool, your own UI tools |
session.step.failed | one model call | count tokens; the error repeats at execution level |
session.execution.failed | the whole run | yes, with a notification; no footer |
tool.failed { error.type: 'aborted' }, step.failed { error.type: 'aborted' }, execution.interrupted { reason: 'user' }, plus global shell.deleted / shell.exited. None of these are user-facing errors. reason: 'shutdown' means the server stopped.task tool is now subagent, with agent instead of subagent_type and sessionID instead of task_id. A child session runs its own executions. Linking it to the exact tool call takes three events:parent tool.input.started { name: 'subagent' } parent tool.called { input: { agent, description, prompt, background?, sessionID? } } child session.created { sessionID, parentID, agent, title } earliest signal parent tool.progress { metadata: { sessionID: child, status: 'running' } } links call child inbox.enqueued { item: { type: 'user', payload: { text: 'You are a subagent…' } } } child execution.started … tool events … execution.succeeded parent tool.success { content: [{ text: '<subagent sessionID="…" state="completed">…' }] }
session.created only registers the child. tool.progress gives the exact call, so it sets the label. Guessing the label from "the earliest open subagent call" broke with parallel subagents created in a different order.123456789101112131415case 'session.created': { const { sessionID, parentID } = event.data if (!parentID || view.children[sessionID]) return if (parentID !== view.sessionId && !view.children[parentID]) return // grandchildren allowed view.children[sessionID] = { agent: event.data.agent ?? 'subagent', description: '', background: false, running: false } return } case 'session.tool.progress': { const childId = event.data.metadata['sessionID'] const tool = view.tools[toolKey(event.data)] if (typeof childId !== 'string' || !tool?.subagent) return view.children[childId] = { ...tool.subagent, running: view.children[childId]?.running ?? false } tool.subagent = null return }
background: true the tool returns at once. The parent can reach execution.succeeded while children still run. Each child completion enqueues a synthetic <subagent … state=completed> item into the parent, which starts a new parent execution.12const isBusy = (view: View) => view.turn !== null || Object.values(view.children).some((child) => child.running) // Post the final footer only when the parent ended and no child runs.
subagent tool accepts sessionID to continue a child. The child gets a new inbox item and no new session.created. Update its label from the new call.form.* and permission.* to the root conversation, labelled by agent, or the child waits on a prompt nobody sees.!cmd) is session.shell, not a prompt. V1 integrations spawned the command themselves and sent the output as a noReply prompt.123// V1 const child = spawn(`exec 2>&1\n${command}`, { shell: true, cwd }) // collect output, then promptAsync({ parts, noReply: true })
12// V2: never awaited, the request returns only when the command ends void client.session.shell({ sessionID, command }).catch((cause) => report(cause))
1234{"type":"session.shell.started","data":{"sessionID":"ses_…","shell":{"id":"sh_0f2012d9…","status":"running", "command":"echo hi && git log --oneline -1","cwd":"/repo","metadata":{"sessionID":"ses_…","background":true},"pid":50334}}} {"type":"session.shell.ended","data":{"sessionID":"ses_…","shell":{"id":"sh_0f2012d9…","status":"exited","exit":0}, "output":{"output":"hi\n05de62d feat: …\n","cursor":91,"size":91,"truncated":false}}}
resume: false item ("The following shell command was executed by the user: …"). The agent sees it on the next turn. While a run is busy it is delivered at the next step boundary, so the model gets another step and may answer it.| Family | Who | Has sessionID |
session.shell.started / ended | user shells | yes, data.sessionID |
shell.created / exited / deleted | every shell, including the tool's | no, only info.metadata.sessionID |
tool.progress.metadata.shellID.session.shell has no delivery, so a shell cannot be queued behind inbox items. session.interrupt does not stop user shells. A full stop has to kill them:1234const shells = await client.shell.list({ location: { directory } }) for (const shell of shells.data.filter((s) => s.status === 'running' && s.metadata['sessionID'] === sessionID)) { await client.shell.remove({ id: shell.id, location: { directory } }) }
client.event.subscribe() is a lazy AsyncIterable over GET /api/event. It does not reconnect and has no replay. You own reconnect, backoff and recovery.123456// V1 const result = await client.global.event({ signal }) for await (const event of result.stream) dispatch(event.payload) // event.properties.sessionID // V2 for await (const event of client.event.subscribe({ signal, onActivity })) dispatch(event) // event.data.sessionID
server.connected. Use it as the "refetch everything" signal after every (re)connect.service.json; never reuse a cached URL.packages/tui/src/mini/stream-v2.transport.ts). It solves the same problem as a chat bot: append-only output from a stream.loop: generation++ stale attempts become no-ops stream = client.event.subscribe() first event must be server.connected else: disconnected hold live events in a list ─────────────┐ hydrate in parallel: │ session.active(), inbox.list, race(hydrate, consume) │ form.list, permission.list apply held events in order <────────────┘ go live on error: backoff 0.5s ─> 30s, re-resolve endpoint, retry
Promise.race with the consumer matters: if the stream dies during hydration, the attempt fails at once instead of waiting for REST calls.AbortController per attempt, so a stale hydration can never publish into a newer connection:const STREAM_IDLE_TIMEOUT_MS = 45_000 async function runAttempt({ endpoint, reconnect }: { endpoint: Endpoint; reconnect: boolean }) { const attempt = new AbortController() const signal = AbortSignal.any([stopController.signal, attempt.signal]) let timer: NodeJS.Timeout | undefined const touch = () => { clearTimeout(timer) timer = setTimeout(() => attempt.abort(), STREAM_IDLE_TIMEOUT_MS) } touch() const iterator = endpoint.client.event.subscribe({ signal, onActivity: touch })[Symbol.asyncIterator]() const result = await (async () => { const first = await iterator.next().catch((cause: unknown) => new StreamClosedError({ cause })) if (first instanceof Error) return first if (first.done || first.value.type !== 'server.connected') { return new StreamClosedError({ reason: 'first event was not server.connected' }) } const held: V2Event[] = [] const phase = { booting: true } const consume = (async (): Promise<Error> => { while (true) { const next = await iterator.next().catch((cause: unknown) => new StreamClosedError({ cause })) if (next instanceof Error) return next if (next.done) return new StreamClosedError({ reason: 'stream ended' }) if (signal.aborted) return new StreamClosedError({ reason: 'stopped' }) if (phase.booting) held.push(next.value) else emit(next.value) } })() const hydrated = await Promise.race([hydrate({ client: endpoint.client, reconnect, signal }), consume]) if (hydrated instanceof Error) return hydrated if (signal.aborted) return new StreamClosedError({ reason: 'stopped' }) state.endpoint = endpoint // switch endpoint before draining held events for (const event of held.splice(0)) emit(event) phase.booting = false return consume })() clearTimeout(timer) attempt.abort() void iterator.return?.(undefined).catch(() => {}) return result } let backoff = 500 while (!stopController.signal.aborted) { const endpoint = await resolveEndpoint() // re-reads service.json every time if (endpoint instanceof Error && state.endpoint === null) return endpoint // fatal only at startup if (!(endpoint instanceof Error)) { await runAttempt({ endpoint, reconnect: state.endpoint !== null }) if (state.endpoint === endpoint) backoff = 500 } await sleep(backoff, undefined, { signal: stopController.signal }).catch(() => {}) backoff = Math.min(backoff * 2, 30_000) }
stop() could still start a new subscription.| State | Source |
| busy sessions | session.active(); keys are running IDs, absent means idle |
| queue | session.inbox.list({ sessionID }) (root only) |
| questions | session.form.list({ sessionID }) (root and children) |
| permissions | permission.list({ sessionID }) (root and children) |
| working directory | session.get({ sessionID }).location.directory |
| subagents started while away | for each unknown active session, walk session.get → parentID |
async function hydrate({ client, signal }: { client: OpenCodeClient; signal: AbortSignal }) { const active = await client.session.active({ signal }) const unknown = Object.keys(active).filter((id) => !routes.has(id) && !ignored.has(id)) await Promise.all(unknown.map((sessionId) => adoptIfChild({ client, sessionId, signal }))) for (const [threadId, root] of roots) { const sessions = [root, ...childrenOf(threadId)] const reads = await Promise.all(sessions.map(async (sessionId) => { const [inbox, forms, permissions] = await Promise.all([ sessionId === root ? client.session.inbox.list({ sessionID: sessionId }, { signal }) : null, client.session.form.list({ sessionID: sessionId }, { signal }), client.permission.list({ sessionID: sessionId }, { signal }), ]) return { sessionId, inbox, forms, permissions } })) // Fed through the same reducer as live events. deliver(threadId, { type: 'myapp.snapshot', at: Date.now(), activeSessionIds: Object.keys(active), sessions: reads }) } }
12345678910111213case 'myapp.snapshot': { const active = new Set(event.activeSessionIds) for (const [id, child] of Object.entries(view.children)) child.running = active.has(id) if (!active.has(view.sessionId)) view.turn = null else view.turn ??= { startedAt: event.at, model: null, agent: null, tokens: 0 } // partial: footer skipped if (!isBusy(view)) view.tools = {} // tool ends missed while away are over for (const session of event.sessions) { if (session.inbox) hydrateQueue(view, session.inbox) hydrateForms(view, session.sessionId, session.forms) // also settle forms that are gone hydratePermissions(view, session.sessionId, session.permissions) } return }
message.list with dedupe keys and dropped it: it doubled the render paths. If you need it, the TUI renders from message.list on reconnect.session.form.list is pending-only. Settle any UI you still show whose form is gone, or a cancelled form keeps a live dropdown forever.active, inbox.list, form.list and permission.list describe different moments. Holding live events avoids lost and duplicated events but not every race.session.log is not a catch-up API yet. GET /api/experimental/session/:id/log?after=<seq>&follow=true returned only { type: 'log.synced', seq } on 2.0.19, even with after=0.sessionID with two maps: every session (including subagents) to its conversation, and each conversation to its root session. A reverse search of the first map returned a subagent as the root after a restart.123456789101112131415function onEvent(event: V2Event) { if (CATALOG_EVENTS.has(event.type)) return reloadCatalog() const sessionId = eventSessionId(event) if (!sessionId) return // global events const threadId = routes.get(sessionId) if (threadId) return deliver(threadId, event) if (ignored.has(sessionId)) return // TUI sessions const parentThread = event.type === 'session.created' && event.data.parentID ? routes.get(event.data.parentID) : undefined if (parentThread) { routes.set(sessionId, parentThread) return deliver(parentThread, event) } hold(sessionId, event) // bounded, arrival order void resolveUnknown(sessionId) // session.get → parentID chain }
ignored, and clear ignored on every reconnect. Cap held events (we use 1000).1234567891011async function findAncestorThread({ client, sessionId, signal }: { client: OpenCodeClient; sessionId: string; signal: AbortSignal }) { let current = sessionId for (let depth = 0; depth < 8; depth++) { const info = await client.session.get({ sessionID: current }, { signal }) if (!info.parentID) return null // an unrelated root session const threadId = routes.get(info.parentID) if (threadId) return threadId current = info.parentID } return null }
session.prompt, so no event of the first turn arrives for an unknown session.| Input | Native operation |
| Normal user turn | session.prompt with delivery: 'steer' |
| Explicit queued turn | session.prompt with delivery: 'queue' |
| Context-only message | session.synthetic with resume: false |
| Command | session.command or the native API for it |
| Shell | session.shell |
123456789export async function submit(input: Submission) { const session = await resolveSession(input) if (session instanceof Error) return session const selected = await applySelection({ sessionID: session.id, agent: input.agent, model: input.model }) if (selected instanceof Error) return selected // never continue with the old model const files = await attach(input.attachments) if (input.kind === 'context') return client.session.synthetic({ sessionID: session.id, text: input.text, resume: false }) return client.session.prompt({ sessionID: session.id, id: input.id, text: input.text, files, delivery: input.delivery, metadata: input.metadata }) }
switchAgent or switchModel must stop submission with a visible error. Until selection can be bound to an inbox item, serialize selection and admission per session.V2Event. Remove handlers for these V1-only events once their behavior has native coverage:message.updatedmessage.part.*question.*session.error as the completion channelsession.idle as a success signal1rg -n "'message\.(updated|part\.)|'question\.|'session\.(idle|error)'" src
Part objects. Our first port did, with fake pending / running states and fake timestamps, so the old formatter kept working. Tool input was lost on success when the part was not seen (input: {}). A small display model is fine; fold its fields directly from native delta and terminal facts.| Meaning | V1 field | V2 field |
| Tool name | task | subagent |
| Selected agent input | subagent_type | agent |
| Continue a child | task_id | sessionID |
| Child session in tool metadata | sessionId | sessionID |
| Parent on session creation | part metadata | session.created.data.parentID |
task, subagent_type and sessionId: subagent output, labels and token accounting failed silently. Cover child text, tool output, labels, completion, interruption and token usage in native event tests.session.execution.succeeded is the successful run boundary. Cleanup and queue logic must run even when your output, including the footer, fails to send.turn_completed from session.execution.succeededsession.step.ended plus session.step.failedsession.idle or message.updated handlers.message.list is newest first. Normalize to chronological order before rendering markdown, picking the latest user turn, or mirroring sessions.session.list to a project unless the feature really wants all projects. Filtering by exact directory hides sessions in linked worktrees; resolve the project ID instead:12const location = await client.location.get({ location: { directory } }) const page = await client.session.list({ project: location.project.id, limit: 200, order: 'desc' })
session.list({ search }) matches titles only (a SQL LIKE). There is no content search.start filter. Never mirror historical sessions just because they are on the first page.session.active, session.get).oauth, key, command, env. Do not coerce command or environment methods into API-key forms; render each method's declared fields.const info = await client.integration.get({ integrationID: 'anthropic', location }) // info.data.methods: [{ id, type: 'oauth' | 'key' | 'command' | 'env', ... }] // API key await client.integration.connect.key({ integrationID: 'anthropic', key, location }) // OAuth: keep the unique attemptID, never the provider ID const attempt = await client.integration.oauth.connect({ integrationID: 'anthropic', methodID: method.id, location }) showLink(attempt.data.url, attempt.data.instructions) const attemptID = attempt.data.attemptID if (attempt.data.mode === 'code') { await client.integration.oauth.complete({ integrationID: 'anthropic', attemptID, code, location }) } else { await client.integration.oauth.status({ integrationID: 'anthropic', attemptID, location }) } // user gave up await client.integration.oauth.cancel({ integrationID: 'anthropic', attemptID, location })
attemptID, and OAuth never completed.credential.*, opencode auth switch). That replaces V1 multi-account rotation plugins.| API | What it is | Identifier |
worktree.* | a local git worktree | its directory |
workspace.* | a provider-backed logical workspace | an OpenCode ID |
worktree.create returns a directory. Do not invent a wrk_<uuid> and pass it to workspace APIs; our first port did, and cleanup failed because OpenCode never created that resource. Remove worktrees with worktree.remove. Use workspace.* only for workspaces OpenCode created.123const location = await client.location.get({ location: { directory: projectDirectory } }) const worktree = await client.worktree.create({ projectID: location.project.id, name: 'fix-login' }) const session = await client.session.create({ location: { directory: worktree.directory } })
experimental_workspace.register) is gone; V2 has no public workspace driver API. Native worktree.create also runs the project's configured start command. If you need your own worktree logic (submodules, lockfiles), create the git worktree yourself and give OpenCode only the directory.12// V1 await client.session.fork({ sessionID, directory, workspace: workspaceId })
123456// V2 const forked = await client.session.fork({ sessionID }) // title becomes "<title> (fork #1)" await client.session.move({ sessionID: forked.id, directory: checkout.directory }) await client.session.wait({ sessionID: forked.id }) const moved = await client.session.get({ sessionID: forked.id }) if (moved.location.directory !== checkout.directory) throw new Error('move did not apply')
session.forked, not session.created. Bind it from the response.session.moved { location } changes the session's directory. Update your view and reload context limits for the new location.1234// V1: status poll, abort, wait for idle, revert at an assistant message const status = await client.session.status({ directory }) if (status.data?.[sessionID]?.type !== 'idle') await client.session.abort({ sessionID, directory }) await client.session.revert({ sessionID, directory, messageID: assistantMessageId })
12345// V2 await client.session.interrupt({ sessionID, resume: false }) await client.session.wait({ sessionID }) await client.session.revert.stage({ sessionID, messageID: userMessageId, files: false }) // files false: skip snapshot restore await client.session.revert.clear({ sessionID }) // redo
--wait flags: only a successful natural completion counts. Errors and tool-call-only intermediate steps are not completion.session.view({ sessionID, idle }) after output is posted, or they stay unread in the TUI sidebar./share has no V2 API: remove it and document the break.agent or model. Switch before prompting, or set them at session.create.12// V1: every promptAsync carried agent, model and variant await client.session.promptAsync({ sessionID, parts, agent: 'plan', model: { providerID, modelID }, variant })
123456// V2: session-wide, stop on failure const switched = await client.session.switchModel({ sessionID, model: { providerID, id: modelId, ...(variant && { variant }) } }) .catch((cause) => new Error(`could not switch model: ${cause}`)) if (switched instanceof Error) return showError(switched) await client.session.switchAgent({ sessionID, agent: 'plan' }) // agent ID, not display name await client.session.prompt({ sessionID, text })
agent.list returns { id: 'plan', name: 'Plan' }. session.create, switchAgent and SessionInfo.agent take the ID.{ providerID, id, variant? }, not { providerID, modelID }. ModelInfo.id matches step.started.data.model.id.switchModel applies at the next step, so it is safe mid-turn.switchAgent('plan') enqueues a synthetic "You are in Plan mode" item. Never render synthetic items as user messages.session.agent.selected and session.model.selected let you see switches made from the TUI.resume: true plus switchModel replaces the V1 "abort and replay with the new model" trick.delivery: 'queue'. Messages waited twice. Delete the local queue; render from session.inbox.*.prompt(steer) then interrupt({ resume: true }) left queued items in the inbox forever. Interrupt with resume: false first, then prompt.execution.interrupted started duplicate runs.noReply that replied. We detected noReply but still called a normal session.prompt, so the agent ran. Use resume: false.tool.called has no name; lines showed tool until we kept a map from tool.input.started.task, subagent_type and sessionId. Subagent output, labels and tokens failed silently.tool.progress metadata.form.created keeps it in data.form.sessionID. Questions were routed nowhere.question forms were shown; websearch.provider forms timed out and every web search failed.session.form.list is pending-only. Forms cancelled while disconnected kept live UI until we settled missing ones on reconnect.Unknown tool. Use a directory with index.js.plugin.list shows it active.model.list and agent.list do not wait for plugin activation; a cold location picked a fallback model and a saved agent failed for ~700ms. integration.list waits, so read it first.model.list and provider.list returned empty on the first call for an unloaded location. Retry a few times..opencode. A data directory inside a project leaked that project's catalog. Read the global catalog from OpenCode's global config dir.service.json.OPENCODE_CONFIG from an agent shell made a test server load the bot's V1 config. Strip OPENCODE_* when you spawn a server from a script.node_modules/.bin/opencode (a shell wrapper) left the server running after SIGTERM. Spawn the native binary.message.list default order reversed markdown exports and fork previews.message.list rendered as empty blocks. Skip non user and assistant messages.session list --active exited early while worktree sessions still ran. List by project.wrk_ ID and workspace.destroy failed.attemptID.context hook changed the prefix of every request. Moved to a synthetic history note.context requests were shaped; compaction and generate had another prefix.null for optional fields; Schema.optional(Schema.String) rejected them. Use Schema.optional(Schema.NullOr(Schema.String)).error.message.session.log was empty on 2.0.19 and message.list drops retry events. Record your own event JSONL per session for bug reports.session.view, every bot session stayed unread in the TUI.message.updated and session.idle that could never fire.OPENCODE_* env, so a test server never touches the user's service:import { spawn } from 'node:child_process' import fs from 'node:fs' import os from 'node:os' import path from 'node:path' // macOS: os.tmpdir() is /var/... but OpenCode resolves /private/var/... const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'oc-test-'))) const env = { ...Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('OPENCODE_') && !key.endsWith('_API_KEY'))), HOME: `${root}/home`, XDG_DATA_HOME: `${root}/data`, XDG_STATE_HOME: `${root}/state`, XDG_CONFIG_HOME: `${root}/config`, XDG_CACHE_HOME: `${root}/cache`, OPENCODE_TEST_HOME: `${root}/home`, OPENCODE_CONFIG_CONTENT: JSON.stringify(testConfig), OPENCODE_DISABLE_PROJECT_CONFIG: '1', OPENCODE_DISABLE_MODELS_FETCH: '1', } const server = spawn(opencodeBinary, ['serve', '--service', '--port', String(port), '--hostname', '127.0.0.1'], { env }) // Same discovery path as production. const endpoint = await Service.discover({ file: `${root}/state/opencode/service.json` })
serve --service needs --port. The default port is fixed, so parallel files collide.*_API_KEY. model.list includes providers from env keys, which breaks snapshots.beforeAll.vi.useFakeTimers() freezes the client and HTTP timeouts. Inject a clock into scheduling code instead.@ai-sdk/provider v3 and returns canned responses. Tool calls are real tool-call stream parts, so OpenCode runs real tools (shell, subagent) and emits real V2 tool events.123456{ "providers": { "det": { "package": "aisdk:file:///abs/path/to/deterministic-provider.js", "models": { "deterministic-v2": {} } } }, "model": "det/deterministic-v2" }
1234// record: subscribe, drive a scenario, write one { at, event } per line for await (const event of client.event.subscribe({ signal })) { fs.appendFileSync(file, JSON.stringify({ at: Date.now(), event }) + '\n') }
123456test('footer after a text-only turn', () => { const events = loadFixture('tools.events.jsonl').filter((event) => !event.type.startsWith('session.tool.')) const { view, effects } = replay({ events }) expect(effectLines(effects)).toMatchInlineSnapshot() expect(view.turn).toBe(null) })
tool.progress.metadata.sessionID and parentID). Never hand-edit fixtures. Recording every production event per conversation (skip deltas, cap the file size) turns user bug reports into fixtures.| Area | Required regression coverage |
| Submission | direct text, queued text, queued image, voice model, context-only synthetic |
| Execution | success footer, failure, interruption without footer, tool continuation |
| Inbox | steer while busy, queue until idle, cancel by inboxID, same msg_ ID idempotent |
| Routing | two active conversations, subagent child output, child usage, background subagents |
| Recovery | SSE loss during output, server restart, pending form recovery, expired forms |
| Ordering | chronological markdown, external synchronization |
| Scope | project session list, all-project deduplication, safe resume |
| Login | OAuth attempt ID, key form, command form, environment form |
| Worktrees | create, move and fork, remove, fresh clone |
| Permissions | V1 alias conversion, native session rules, reject ends the run |
| Plugins | activation, every ported hook, no hook on unmarked sessions |
| Commands | undo, redo, wait success, wait error, wait on tool-only step, form cancel |
12git clone --recurse-submodules https://github.com/you/your-repo /tmp/fresh && cd /tmp/fresh pnpm install && pnpm build && pnpm test
| Limitation | Workaround |
| SSE has no replay; deltas are lost on disconnect | hydrate state, render from terminal events |
session.log returns no history | record your own event log |
tool.called has no tool name | map from tool.input.started (#35638) |
| Queued prompt text cannot be edited | cancel and enqueue again (#52275) |
session.shell has no delivery | run shells at once; no ordered shell queue |
session.interrupt does not stop user shells | shell.list plus shell.remove |
session.command has no id or metadata | dispatch your own marker before the command |
| Hydration reads are not atomic | hold live events while hydrating |
| Forms and permissions are in memory | rebuild from list calls after restart |
usage.recorded is internal | use step.ended tokens |
| Context percent needs the model limit | omit it when unknown |
| Session search is title-only | keep your own index if you need content search |
Plugin SessionDomain lacks some HTTP operations | use @opencode/client there |
| Execution recovery is at-least-once | a crash can repeat a tool side effect |
| No share API | remove share commands |
session.log, instructions.entry, session.wait, session export and import, and fs.write.@opencode-ai/sdk, @opencode-ai/sdk/v2 or @opencode-ai/plugin remains@opencode/* packages pinned to the same exact versionService.discover() / Service.ensure(), never pins a server versionserver.info().version and stops with install instructions on V1.data / .error checks on V2 calls; rejections become typed errorslocation, permissions and a metadata markerpromptAsync replaced by session.prompt; noReply by resume: falseresume: false) first, then prompt(steer)session.inbox.*message.updated, message.part.*, question.*, session.idle, session.errortool.input.started; shell, subagent, path renames appliedsession.execution.*; queued items handled inside one executionparentID and tool.progress, including background childrenserver.connected check, idle watchdog, backoff, endpoint re-resolvestep.ended plus step.failed; context percent omitted when unknownmessage.list and session.list call ordered and scopedattemptID; worktrees use directories, not invented workspace IDsPlugin.define, guarded by the session markeropencode and the V2 installer replaces the V1 binary. Some installs add an opencode2 alias for the same V2 binary. Keep a copy of your V1 setup while you test, and test integrations against an isolated V2 server.@opencode/client, plugins use @opencode/plugin. See the trap.session.execution.succeeded (or failed / interrupted) of the root session. Not session.idle, which V2 core does not publish, and not step.ended, which is one model call. Remember that queued prompts and background subagents can make one execution cover several turns, or a turn span several executions. See execution lifecycle.session.prompt({ delivery: 'steer' }) alone admits the prompt at the next safe step boundary, without stopping the current run. Interrupt first only when the new message should replace the current work. See interrupt, then steer.opencode-ai/opencode, which is an unrelated repo.V2_HTTP_API_AUDIT.md on the v2 branchopencode on your machine, and the other way around.Discord thread ──> Kimaki ──> your OpenCode V2 service <── opencode TUI │ └──> your projects, your models, your plugins