@liontree/opencode-agent-sdk 0.1.0

package/README.md

@@ -0,0 +1,220 @@
+# opencode-agent-sdk
+
+High-level agent runtime for `@opencode-ai/sdk/v2`.
+
+This package wraps OpenCode's lower-level session and SSE APIs with a more agent-oriented model:
+
+- declare agents once
+- create reusable sessions
+- call `query()` / `receiveResponse()` or `run()`
+- consume normalized text, tool-call, status, error, and final-result events
+
+It is inspired by the usability level of Claude's agent SDK, but it does not try to be API-compatible 1:1.
+
+## Config behavior
+
+This SDK follows OpenCode's normal config resolution and adds programmatic overrides on top.
+
+- OpenCode still loads its normal config chain such as global config, project config, `.opencode/`, and managed config
+- if `OPENCODE_CONFIG_CONTENT` is already present in the parent process, this SDK inherits and merges it by default
+- options passed to `createAgentRuntime()` are applied as inline runtime overrides on top of the inherited config
+
+In practice, the resolved precedence for config passed through this SDK is:
+
+1. existing `OPENCODE_CONFIG_CONTENT` from the parent environment
+2. `options.config`
+3. SDK-managed overrides such as `agents`, `mcp`, `permission`, and `model`
+
+Pass `rawConfigContent` if you want to override the inherited inline config content explicitly.
+
+## Why
+
+`@opencode-ai/sdk` is a solid transport/client layer, but most applications still need to rebuild the same higher-level pieces:
+
+- session lifecycle helpers
+- per-turn completion handling
+- stream filtering by session
+- message delta vs snapshot reconciliation
+- tool call lifecycle normalization
+- final assistant message lookup
+
+`@liontree/opencode-agent-sdk` packages those concerns into a reusable runtime.
+
+## Installation
+
+```bash
+npm install @liontree/opencode-agent-sdk
+```
+
+This package declares `@opencode-ai/sdk` and `opencode-ai` as dependencies, so you do not need to install them separately.
+
+## Requirements
+
+- a working OpenCode provider/auth setup available through normal OpenCode config resolution or inline config passed to this SDK
+
+## Quick Start
+
+```bash
+npm install @liontree/opencode-agent-sdk
+```
+
+```ts
+import { createAgentRuntime } from "@liontree/opencode-agent-sdk"
+
+const runtime = await createAgentRuntime({
+  directory: "/app",
+  model: "openai/gpt-5.4",
+  permission: {
+    "*": "allow",
+  },
+  mcp: {
+    terminal: {
+      type: "remote",
+      url: "http://127.0.0.1:8000/mcp",
+      oauth: false,
+      timeout: 3600000,
+    },
+  },
+  agents: {
+    fuzzer: {
+      description: "Expert in AFL++ fuzzing workflows.",
+      prompt: "You are the fuzzing agent...",
+    },
+  },
+})
+
+const session = await runtime.createSession({ agent: "fuzzer" })
+
+await session.query("Start fuzzing target libpng")
+
+for await (const event of session.receiveResponse()) {
+  switch (event.type) {
+    case "status":
+      console.log("status:", event.status)
+      break
+    case "text":
+      process.stdout.write(event.text)
+      break
+    case "tool_call":
+      console.log("tool:", event.toolName, event.status)
+      break
+    case "error":
+      console.error("error:", event.error)
+      break
+    case "result":
+      console.log("final text:\n", event.result.text)
+      break
+  }
+}
+
+await runtime.dispose()
+```
+
+This example assumes your OpenCode provider/auth configuration is already available through OpenCode's normal config resolution, for example:
+
+- `~/.config/opencode/opencode.json`
+- `opencode.json` in the project
+- environment variables consumed by your provider config
+- existing `OPENCODE_CONFIG_CONTENT`
+
+If you want to provide inline config explicitly, pass `rawConfigContent` or `config`.
+
+```ts
+const runtime = await createAgentRuntime({
+  directory: "/app",
+  rawConfigContent: JSON.stringify({
+    provider: {
+      openai: {
+        options: {
+          apiKey: "{env:OPENAI_API_KEY}",
+        },
+      },
+    },
+  }),
+  agents: {
+    researcher: {
+      prompt: "You are a focused research agent.",
+    },
+  },
+})
+```
+
+If you only need the final answer instead of a streamed event loop, use `run()`:
+
+```ts
+const result = await session.run("Summarize the current repository")
+
+console.log(result.text)
+```
+
+## Main API
+
+### `createAgentRuntime(options)`
+
+Creates a managed OpenCode runtime and injects:
+
+- agent prompts
+- optional default model
+- optional MCP config
+- optional permission config
+- optional extra config merged with inherited inline config
+
+### `runtime.createSession({ agent, model })`
+
+Creates a reusable OpenCode session and returns an `OpencodeAgentSession`.
+
+### `session.query(prompt, options)`
+
+Starts one turn on the session.
+
+### `session.receiveResponse()`
+
+Consumes the active turn as an async stream of normalized events:
+
+- `status`
+- `text`
+- `tool_call`
+- `error`
+- `result`
+
+`receiveResponse()` is single-consumer per turn.
+
+### `session.run(prompt, options)`
+
+Convenience helper that internally calls `query()` and consumes the response stream until a final result is available.
+
+### `session.abort()` / `session.interrupt()`
+
+Both currently map to OpenCode's session abort behavior.
+
+## Event Model
+
+### `status`
+
+Emitted on deduplicated session status transitions such as `busy` and `idle`.
+
+### `text`
+
+Emitted for assistant text updates.
+
+- `format: "delta"` means incremental text
+- `format: "snapshot"` means the full part text was emitted to recover from a missing delta or stream correction
+
+### `tool_call`
+
+Emitted when a tool part changes lifecycle state.
+
+### `error`
+
+Emitted for prompt failures, session errors, SSE errors, or shutdown problems.
+
+### `result`
+
+Emitted exactly once when the final assistant message can be resolved.
+
+## Notes
+
+- This SDK is higher-level than raw OpenCode, not a workflow engine.
+- It does not implement multi-agent orchestration for you.
+- It does not aim for complete Claude SDK compatibility.
+- Model resolution order is: per-call override -> session default -> agent default -> runtime default -> OpenCode config.

package/dist/config.d.ts

@@ -0,0 +1,18 @@
+import type { AgentDefinition, JsonObject, JsonValue, ModelReference, ModelSpec } from "./types.js";
+export type PlainObject = JsonObject;
+type BuildRuntimeConfigOptions = {
+    agents: Record<string, AgentDefinition>;
+    config?: PlainObject;
+    mcp?: PlainObject;
+    model?: ModelReference;
+    permission?: PlainObject;
+    rawConfigContent?: string;
+};
+export declare function isPlainObject(value: JsonValue | object): value is PlainObject;
+export declare function deepMergeConfig(base: PlainObject, overlay: PlainObject): PlainObject;
+export declare function parseRuntimeConfigContent(raw?: string): PlainObject;
+export declare function resolveInlineConfigContent(raw?: string): string | undefined;
+export declare function normalizeModelReference(model: ModelReference): ModelSpec;
+export declare function parseModelSpec(raw?: string): ModelSpec | undefined;
+export declare function buildRuntimeConfig({ agents, config, mcp, model, permission, rawConfigContent, }: BuildRuntimeConfigOptions): PlainObject;
+export {};

package/dist/config.js

@@ -0,0 +1,88 @@
+const INLINE_CONFIG_ENV_VAR = "OPENCODE_CONFIG_CONTENT";
+export function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function deepMergeConfig(base, overlay) {
+    const result = { ...base };
+    for (const [key, value] of Object.entries(overlay)) {
+        const existing = result[key];
+        if (existing && isPlainObject(existing) && isPlainObject(value)) {
+            result[key] = deepMergeConfig(existing, value);
+            continue;
+        }
+        result[key] = value;
+    }
+    return result;
+}
+export function parseRuntimeConfigContent(raw) {
+    if (!raw || !raw.trim()) {
+        return {};
+    }
+    const parsed = JSON.parse(raw);
+    if (!isPlainObject(parsed)) {
+        throw new Error("rawConfigContent must be a JSON object");
+    }
+    return parsed;
+}
+export function resolveInlineConfigContent(raw) {
+    if (typeof raw === "string") {
+        return raw;
+    }
+    return process.env[INLINE_CONFIG_ENV_VAR];
+}
+export function normalizeModelReference(model) {
+    if (typeof model !== "string") {
+        return model;
+    }
+    const splitIndex = model.indexOf("/");
+    if (splitIndex <= 0 || splitIndex === model.length - 1) {
+        throw new Error(`Invalid model reference: ${model}`);
+    }
+    return {
+        providerID: model.slice(0, splitIndex).trim(),
+        modelID: model.slice(splitIndex + 1).trim(),
+    };
+}
+export function parseModelSpec(raw) {
+    if (!raw || !raw.includes("/")) {
+        return undefined;
+    }
+    const splitIndex = raw.indexOf("/");
+    const providerID = raw.slice(0, splitIndex).trim();
+    const modelID = raw.slice(splitIndex + 1).trim();
+    if (!providerID || !modelID) {
+        return undefined;
+    }
+    return { providerID, modelID };
+}
+function toModelString(model) {
+    const normalized = normalizeModelReference(model);
+    return `${normalized.providerID}/${normalized.modelID}`;
+}
+function buildAgentConfig(agents) {
+    const entries = Object.entries(agents).map(([name, definition]) => {
+        const config = {
+            mode: definition.mode ?? "primary",
+            prompt: definition.prompt,
+        };
+        return [name, config];
+    });
+    return Object.fromEntries(entries);
+}
+export function buildRuntimeConfig({ agents, config, mcp, model, permission, rawConfigContent, }) {
+    const inheritedInlineConfig = parseRuntimeConfigContent(resolveInlineConfigContent(rawConfigContent));
+    const optionConfig = config ?? {};
+    const managedConfig = {
+        agent: buildAgentConfig(agents),
+    };
+    if (mcp) {
+        managedConfig.mcp = mcp;
+    }
+    if (permission) {
+        managedConfig.permission = permission;
+    }
+    if (model) {
+        managedConfig.model = toModelString(model);
+    }
+    return deepMergeConfig(deepMergeConfig(inheritedInlineConfig, optionConfig), managedConfig);
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { buildRuntimeConfig, deepMergeConfig, normalizeModelReference, parseModelSpec, parseRuntimeConfigContent, resolveInlineConfigContent, } from "./config.js";
+export { createAgentRuntime, OpencodeAgentRuntime, OpencodeAgentSession, type Session } from "./runtime.js";
+export type { AgentDefinition, AgentErrorEvent, AgentErrorInfo, AgentQueryOptions, AgentResponseEvent, AgentResultEvent, AgentRunOptions, AgentRuntimeOptions, AgentRuntimeRunOptions, AgentSessionOptions, AgentStatusEvent, AgentTextEvent, AgentToolCallEvent, AgentTurnResult, JsonArray, JsonObject, JsonPrimitive, JsonValue, ModelReference, ModelSpec, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { buildRuntimeConfig, deepMergeConfig, normalizeModelReference, parseModelSpec, parseRuntimeConfigContent, resolveInlineConfigContent, } from "./config.js";
+export { createAgentRuntime, OpencodeAgentRuntime, OpencodeAgentSession } from "./runtime.js";

package/dist/runtime.d.ts

@@ -0,0 +1,36 @@
+import { type OpencodeClient, type Session } from "@opencode-ai/sdk/v2";
+import type { AgentDefinition, AgentQueryOptions, AgentResponseEvent, AgentRunOptions, AgentRuntimeOptions, AgentRuntimeRunOptions, AgentSessionOptions, AgentTurnResult, ModelReference, ModelSpec } from "./types.js";
+type ManagedServer = {
+    close: () => void;
+};
+export declare class OpencodeAgentSession {
+    private readonly runtime;
+    readonly id: string;
+    private readonly defaultAgent?;
+    private readonly defaultModel?;
+    private activeTurn;
+    private startingTurn;
+    constructor(runtime: OpencodeAgentRuntime, id: string, defaultAgent?: string | undefined, defaultModel?: ModelReference | undefined);
+    private assertAvailable;
+    query(prompt: string, options?: AgentQueryOptions): Promise<void>;
+    receiveResponse(): AsyncGenerator<AgentResponseEvent, void, unknown>;
+    run(prompt: string, options?: AgentRunOptions): Promise<AgentTurnResult>;
+    abort(): Promise<void>;
+    interrupt(): Promise<void>;
+}
+export declare class OpencodeAgentRuntime {
+    readonly client: OpencodeClient;
+    readonly directory: string;
+    private readonly managedServer?;
+    private readonly defaultModel?;
+    private disposed;
+    private readonly agentDefinitions;
+    constructor(client: OpencodeClient, directory: string, agents: Record<string, AgentDefinition>, managedServer?: ManagedServer | undefined, defaultModel?: ModelReference | undefined);
+    dispose(): Promise<void>;
+    getAgent(name: string): AgentDefinition;
+    resolveModel(agentName: string, override?: ModelReference): Promise<ModelSpec>;
+    createSession(options?: AgentSessionOptions): Promise<OpencodeAgentSession>;
+    run(options: AgentRuntimeRunOptions): Promise<AgentTurnResult>;
+}
+export declare function createAgentRuntime(options: AgentRuntimeOptions): Promise<OpencodeAgentRuntime>;
+export type { Session };

package/dist/runtime.js

@@ -0,0 +1,618 @@
+import { createOpencode, } from "@opencode-ai/sdk/v2";
+import { buildRuntimeConfig, normalizeModelReference, parseModelSpec } from "./config.js";
+import { delay, extractTextFromParts, formatErrorInfo, requireData, toErrorInfo } from "./utils.js";
+const POST_IDLE_EVENT_DRAIN_MS = 300;
+const EVENT_STREAM_SHUTDOWN_TIMEOUT_MS = 2000;
+function isSessionEvent(event) {
+    return (event.type === "message.part.updated" ||
+        event.type === "message.part.delta" ||
+        event.type === "message.updated" ||
+        event.type === "session.status" ||
+        event.type === "session.idle" ||
+        event.type === "session.error");
+}
+function getEventSessionID(event) {
+    switch (event.type) {
+        case "message.part.updated":
+            return event.properties.part.sessionID;
+        case "message.part.delta":
+            return event.properties.sessionID;
+        case "message.updated":
+            return event.properties.info.sessionID;
+        case "session.status":
+            return event.properties.sessionID;
+        case "session.idle":
+            return event.properties.sessionID;
+        case "session.error":
+            return event.properties.sessionID;
+    }
+}
+function createIdleGate() {
+    let resolved = false;
+    let resolveSignal = () => { };
+    const signal = new Promise((resolve) => {
+        resolveSignal = resolve;
+    });
+    return {
+        signal,
+        mark() {
+            if (!resolved) {
+                resolved = true;
+                resolveSignal();
+            }
+        },
+    };
+}
+function createTurnContext() {
+    return {
+        assistantMessageIDs: new Set(),
+        idleGate: createIdleGate(),
+        lastStatus: "",
+        latestAssistantMessageID: null,
+        sawBusy: false,
+        textByPartID: new Map(),
+        toolStatusByPartID: new Map(),
+    };
+}
+function getAssistantMessageError(info) {
+    if (!info || info.role !== "assistant" || !info.error) {
+        return null;
+    }
+    return toErrorInfo(info.error);
+}
+class AsyncEventQueue {
+    closed = false;
+    failure = null;
+    values = [];
+    waiters = [];
+    push(value) {
+        if (this.closed || this.failure) {
+            return;
+        }
+        const waiter = this.waiters.shift();
+        if (waiter) {
+            waiter.resolve({ value, done: false });
+            return;
+        }
+        this.values.push(value);
+    }
+    close() {
+        if (this.closed || this.failure) {
+            return;
+        }
+        this.closed = true;
+        for (const waiter of this.waiters.splice(0)) {
+            waiter.resolve({ value: undefined, done: true });
+        }
+    }
+    fail(error) {
+        if (this.closed || this.failure) {
+            return;
+        }
+        this.failure = error;
+        for (const waiter of this.waiters.splice(0)) {
+            waiter.reject(error);
+        }
+    }
+    next() {
+        if (this.values.length > 0) {
+            const value = this.values.shift();
+            return Promise.resolve({ value: value, done: false });
+        }
+        if (this.failure) {
+            return Promise.reject(this.failure);
+        }
+        if (this.closed) {
+            return Promise.resolve({ value: undefined, done: true });
+        }
+        return new Promise((resolve, reject) => {
+            this.waiters.push({ resolve, reject });
+        });
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => this.next(),
+        };
+    }
+}
+class ActiveTurn {
+    args;
+    claimed = false;
+    finalResult = null;
+    queue = new AsyncEventQueue();
+    worker;
+    constructor(args) {
+        this.args = args;
+        this.worker = this.run();
+    }
+    async *consume() {
+        if (this.claimed) {
+            throw new Error("receiveResponse() can only be consumed once per query()");
+        }
+        this.claimed = true;
+        for await (const event of this.queue) {
+            yield event;
+        }
+    }
+    getResult() {
+        return this.finalResult;
+    }
+    emit(event) {
+        this.queue.push(event);
+    }
+    emitError(error) {
+        this.emit({
+            type: "error",
+            agent: this.args.agent,
+            sessionID: this.args.sessionID,
+            error: toErrorInfo(error),
+        });
+    }
+    markIdleIfReady(context) {
+        if (context.sawBusy || context.latestAssistantMessageID !== null) {
+            context.idleGate.mark();
+        }
+    }
+    emitStatus(context, status) {
+        if (!status || status === context.lastStatus) {
+            return;
+        }
+        context.lastStatus = status;
+        this.emit({
+            type: "status",
+            agent: this.args.agent,
+            sessionID: this.args.sessionID,
+            status,
+        });
+    }
+    emitTextEvent(event) {
+        this.emit({
+            type: "text",
+            agent: this.args.agent,
+            sessionID: this.args.sessionID,
+            ...event,
+        });
+    }
+    emitToolCallEvent(event) {
+        this.emit({
+            type: "tool_call",
+            agent: this.args.agent,
+            sessionID: this.args.sessionID,
+            ...event,
+        });
+    }
+    handleMessagePartDelta(event, context) {
+        if (event.properties.field !== "text" || !event.properties.delta) {
+            return;
+        }
+        const previous = context.textByPartID.get(event.properties.partID) ?? "";
+        context.textByPartID.set(event.properties.partID, `${previous}${event.properties.delta}`);
+        this.emitTextEvent({
+            format: "delta",
+            messageID: event.properties.messageID,
+            partID: event.properties.partID,
+            text: event.properties.delta,
+        });
+    }
+    handleTextPartUpdated(part, context) {
+        const previous = context.textByPartID.get(part.id) ?? "";
+        let format = null;
+        let text = "";
+        if (part.text.length > previous.length && part.text.startsWith(previous)) {
+            text = part.text.slice(previous.length);
+            format = text ? "delta" : null;
+        }
+        else if (part.text !== previous) {
+            text = part.text;
+            format = "snapshot";
+        }
+        context.textByPartID.set(part.id, part.text);
+        if (!format || !text) {
+            return;
+        }
+        this.emitTextEvent({
+            format,
+            messageID: part.messageID,
+            partID: part.id,
+            text,
+        });
+    }
+    handleToolPartUpdated(part, context) {
+        const status = part.state.status;
+        if (context.toolStatusByPartID.get(part.id) === status) {
+            return;
+        }
+        context.toolStatusByPartID.set(part.id, status);
+        const event = {
+            attachments: 0,
+            callID: part.callID,
+            input: part.state.input,
+            messageID: part.messageID,
+            partID: part.id,
+            status,
+            toolName: part.tool,
+        };
+        if (part.state.status === "running" && part.state.title) {
+            event.title = part.state.title;
+        }
+        if (part.state.status === "completed") {
+            event.attachments = part.state.attachments?.length ?? 0;
+            event.output = part.state.output;
+            event.title = part.state.title;
+        }
+        if (part.state.status === "error") {
+            event.error = part.state.error;
+        }
+        this.emitToolCallEvent({
+            ...event,
+        });
+    }
+    handleSessionEvent(event, context) {
+        switch (event.type) {
+            case "session.status":
+                if (event.properties.status.type === "busy") {
+                    context.sawBusy = true;
+                }
+                if (event.properties.status.type === "idle") {
+                    this.markIdleIfReady(context);
+                }
+                this.emitStatus(context, event.properties.status.type);
+                return;
+            case "session.idle":
+                this.markIdleIfReady(context);
+                this.emitStatus(context, "idle");
+                return;
+            case "session.error":
+                this.emitError(event.properties.error);
+                return;
+            case "message.updated":
+                if (event.properties.info.role === "assistant") {
+                    context.assistantMessageIDs.add(event.properties.info.id);
+                    context.latestAssistantMessageID = event.properties.info.id;
+                }
+                return;
+            case "message.part.delta":
+                if (context.assistantMessageIDs.has(event.properties.messageID)) {
+                    this.handleMessagePartDelta(event, context);
+                }
+                return;
+            case "message.part.updated":
+                if (!context.assistantMessageIDs.has(event.properties.part.messageID)) {
+                    return;
+                }
+                if (event.properties.part.type === "text") {
+                    this.handleTextPartUpdated(event.properties.part, context);
+                    return;
+                }
+                if (event.properties.part.type === "tool") {
+                    this.handleToolPartUpdated(event.properties.part, context);
+                }
+                return;
+        }
+    }
+    async subscribeToEvents() {
+        const controller = new AbortController();
+        const subscription = (await this.args.client.event.subscribe({ directory: this.args.directory }, {
+            signal: controller.signal,
+            onSseError: (error) => {
+                if (!controller.signal.aborted) {
+                    this.emitError(error);
+                }
+            },
+        }));
+        const stream = (async function* () {
+            for await (const event of subscription.stream) {
+                if (isSessionEvent(event)) {
+                    yield event;
+                }
+            }
+        })();
+        return {
+            abort: () => {
+                controller.abort();
+            },
+            signal: controller.signal,
+            stream,
+        };
+    }
+    async resolveLatestAssistantMessage(sessionID, preferredMessageID) {
+        if (preferredMessageID) {
+            const message = await requireData("session.message", this.args.client.session.message({
+                sessionID,
+                messageID: preferredMessageID,
+                directory: this.args.directory,
+            }));
+            return {
+                info: message.info ?? null,
+                parts: message.parts ?? [],
+            };
+        }
+        const messages = await requireData("session.messages", this.args.client.session.messages({
+            sessionID,
+            directory: this.args.directory,
+        }));
+        const latestAssistant = [...messages].reverse().find((entry) => entry.info.role === "assistant");
+        if (!latestAssistant) {
+            return {
+                info: null,
+                parts: [],
+            };
+        }
+        return {
+            info: latestAssistant.info ?? null,
+            parts: latestAssistant.parts ?? [],
+        };
+    }
+    async run() {
+        const context = createTurnContext();
+        const events = await this.subscribeToEvents();
+        const consumeTask = (async () => {
+            try {
+                for await (const event of events.stream) {
+                    if (getEventSessionID(event) !== this.args.sessionID) {
+                        continue;
+                    }
+                    this.handleSessionEvent(event, context);
+                }
+            }
+            catch (error) {
+                if (!events.signal.aborted) {
+                    this.emitError(error);
+                }
+            }
+        })();
+        let turnError = null;
+        try {
+            const response = await this.args.client.session.promptAsync({
+                sessionID: this.args.sessionID,
+                directory: this.args.directory,
+                agent: this.args.agent,
+                model: {
+                    providerID: this.args.model.providerID,
+                    modelID: this.args.model.modelID,
+                },
+                parts: [{ type: "text", text: this.args.prompt }],
+            });
+            if (response.error) {
+                throw new Error(`session.promptAsync failed: ${JSON.stringify(response.error)}`);
+            }
+            await context.idleGate.signal;
+        }
+        catch (error) {
+            turnError = toErrorInfo(error);
+            this.emit({
+                type: "error",
+                agent: this.args.agent,
+                sessionID: this.args.sessionID,
+                error: turnError,
+            });
+        }
+        finally {
+            await delay(POST_IDLE_EVENT_DRAIN_MS);
+            events.abort();
+            let shutdownTimer;
+            try {
+                await Promise.race([
+                    consumeTask,
+                    new Promise((_, reject) => {
+                        shutdownTimer = setTimeout(() => {
+                            reject(new Error("Timed out shutting down session event stream after abort"));
+                        }, EVENT_STREAM_SHUTDOWN_TIMEOUT_MS);
+                    }),
+                ]);
+            }
+            catch (error) {
+                const shutdownError = toErrorInfo(error);
+                turnError ??= shutdownError;
+                this.emit({
+                    type: "error",
+                    agent: this.args.agent,
+                    sessionID: this.args.sessionID,
+                    error: shutdownError,
+                });
+            }
+            finally {
+                if (shutdownTimer) {
+                    clearTimeout(shutdownTimer);
+                }
+            }
+        }
+        try {
+            const resolved = await this.resolveLatestAssistantMessage(this.args.sessionID, context.latestAssistantMessageID);
+            const result = {
+                agent: this.args.agent,
+                error: turnError ?? getAssistantMessageError(resolved.info),
+                info: resolved.info,
+                messageID: resolved.info?.id ?? context.latestAssistantMessageID,
+                parts: resolved.parts,
+                sessionID: this.args.sessionID,
+                text: extractTextFromParts(resolved.parts),
+            };
+            if (result.info || result.parts.length > 0 || result.error) {
+                this.finalResult = result;
+                this.emit({
+                    type: "result",
+                    agent: this.args.agent,
+                    sessionID: this.args.sessionID,
+                    result,
+                });
+            }
+        }
+        catch (error) {
+            const resolveError = toErrorInfo(error);
+            this.emit({
+                type: "error",
+                agent: this.args.agent,
+                sessionID: this.args.sessionID,
+                error: resolveError,
+            });
+        }
+        finally {
+            this.queue.close();
+        }
+    }
+}
+export class OpencodeAgentSession {
+    runtime;
+    id;
+    defaultAgent;
+    defaultModel;
+    activeTurn = null;
+    startingTurn = false;
+    constructor(runtime, id, defaultAgent, defaultModel) {
+        this.runtime = runtime;
+        this.id = id;
+        this.defaultAgent = defaultAgent;
+        this.defaultModel = defaultModel;
+    }
+    assertAvailable() {
+        if (this.startingTurn || this.activeTurn) {
+            throw new Error("A turn is already active for this session");
+        }
+    }
+    async query(prompt, options = {}) {
+        this.assertAvailable();
+        this.startingTurn = true;
+        try {
+            const agent = options.agent ?? this.defaultAgent;
+            if (!agent) {
+                throw new Error("No agent selected. Pass agent to createSession(), query(), or run().");
+            }
+            const model = await this.runtime.resolveModel(agent, options.model ?? this.defaultModel);
+            this.activeTurn = new ActiveTurn({
+                agent,
+                client: this.runtime.client,
+                directory: this.runtime.directory,
+                model,
+                prompt,
+                sessionID: this.id,
+            });
+        }
+        finally {
+            this.startingTurn = false;
+        }
+    }
+    async *receiveResponse() {
+        const turn = this.activeTurn;
+        if (!turn) {
+            throw new Error("No active turn. Call query() first.");
+        }
+        try {
+            for await (const event of turn.consume()) {
+                yield event;
+            }
+        }
+        finally {
+            if (this.activeTurn === turn) {
+                this.activeTurn = null;
+            }
+        }
+    }
+    async run(prompt, options = {}) {
+        await this.query(prompt, options);
+        let lastError = null;
+        let result = null;
+        for await (const event of this.receiveResponse()) {
+            if (event.type === "error") {
+                lastError = event.error;
+            }
+            if (event.type === "result") {
+                result = event.result;
+            }
+        }
+        if (result) {
+            return result;
+        }
+        if (lastError) {
+            throw new Error(formatErrorInfo(lastError));
+        }
+        throw new Error("Agent turn completed without a final result");
+    }
+    async abort() {
+        await requireData("session.abort", this.runtime.client.session.abort({
+            sessionID: this.id,
+            directory: this.runtime.directory,
+        }));
+    }
+    async interrupt() {
+        await this.abort();
+    }
+}
+export class OpencodeAgentRuntime {
+    client;
+    directory;
+    managedServer;
+    defaultModel;
+    disposed = false;
+    agentDefinitions;
+    constructor(client, directory, agents, managedServer, defaultModel) {
+        this.client = client;
+        this.directory = directory;
+        this.managedServer = managedServer;
+        this.defaultModel = defaultModel;
+        this.agentDefinitions = new Map(Object.entries(agents));
+    }
+    async dispose() {
+        if (this.disposed) {
+            return;
+        }
+        this.disposed = true;
+        this.managedServer?.close();
+    }
+    getAgent(name) {
+        const agent = this.agentDefinitions.get(name);
+        if (!agent) {
+            throw new Error(`Unknown agent '${name}'`);
+        }
+        return agent;
+    }
+    async resolveModel(agentName, override) {
+        const agentModel = this.getAgent(agentName).model;
+        const selected = override ?? agentModel ?? this.defaultModel;
+        if (selected) {
+            return normalizeModelReference(selected);
+        }
+        const config = await requireData("config.get", this.client.config.get({
+            directory: this.directory,
+        }));
+        const resolved = parseModelSpec(config.model);
+        if (!resolved) {
+            throw new Error("Unable to resolve model from OpenCode config. Set runtime.model or configure a default model in OpenCode.");
+        }
+        return resolved;
+    }
+    async createSession(options = {}) {
+        if (this.disposed) {
+            throw new Error("Runtime has been disposed");
+        }
+        const session = await requireData("session.create", this.client.session.create({
+            directory: this.directory,
+        }));
+        return new OpencodeAgentSession(this, session.id, options.agent, options.model);
+    }
+    async run(options) {
+        const sessionOptions = {
+            agent: options.agent,
+            ...(options.model ? { model: options.model } : {}),
+        };
+        const session = await this.createSession(sessionOptions);
+        return session.run(options.prompt);
+    }
+}
+export async function createAgentRuntime(options) {
+    const runtimeConfig = buildRuntimeConfig({
+        agents: options.agents,
+        ...(options.config ? { config: options.config } : {}),
+        ...(options.mcp ? { mcp: options.mcp } : {}),
+        ...(options.model ? { model: options.model } : {}),
+        ...(options.permission ? { permission: options.permission } : {}),
+        ...(options.rawConfigContent ? { rawConfigContent: options.rawConfigContent } : {}),
+    });
+    const { client, server } = await createOpencode({
+        hostname: options.hostname ?? "127.0.0.1",
+        port: options.port ?? 0,
+        timeout: options.timeoutMs ?? 15000,
+        config: runtimeConfig,
+    });
+    return new OpencodeAgentRuntime(client, options.directory, options.agents, server, options.model);
+}

package/dist/types.d.ts

@@ -0,0 +1,100 @@
+import type { Message, Part, ToolState } from "@opencode-ai/sdk/v2";
+export type JsonPrimitive = boolean | null | number | string;
+export type JsonValue = JsonArray | JsonObject | JsonPrimitive;
+export type JsonArray = JsonValue[];
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+export type ModelSpec = {
+    modelID: string;
+    providerID: string;
+};
+export type ModelReference = ModelSpec | `${string}/${string}`;
+export type AgentDefinition = {
+    description?: string;
+    model?: ModelReference;
+    mode?: string;
+    prompt: string;
+};
+export type AgentRuntimeOptions = {
+    agents: Record<string, AgentDefinition>;
+    config?: JsonObject;
+    directory: string;
+    hostname?: string;
+    mcp?: JsonObject;
+    model?: ModelReference;
+    permission?: JsonObject;
+    port?: number;
+    rawConfigContent?: string;
+    timeoutMs?: number;
+};
+export type AgentSessionOptions = {
+    agent?: string;
+    model?: ModelReference;
+};
+export type AgentQueryOptions = AgentSessionOptions;
+export type AgentRunOptions = AgentSessionOptions;
+export type AgentRuntimeRunOptions = {
+    agent: string;
+    model?: ModelReference;
+    prompt: string;
+};
+export type AgentErrorInfo = {
+    code?: string;
+    message: string;
+    name: string;
+    status?: number;
+    statusCode?: number;
+};
+export type AgentStatusEvent = {
+    agent: string;
+    sessionID: string;
+    status: string;
+    type: "status";
+};
+export type AgentTextEvent = {
+    agent: string;
+    format: "delta" | "snapshot";
+    messageID: string;
+    partID: string;
+    sessionID: string;
+    text: string;
+    type: "text";
+};
+export type AgentToolCallEvent = {
+    agent: string;
+    attachments: number;
+    callID: string;
+    error?: string;
+    input?: unknown;
+    messageID: string;
+    output?: string;
+    partID: string;
+    sessionID: string;
+    status: ToolState["status"];
+    title?: string;
+    toolName: string;
+    type: "tool_call";
+};
+export type AgentErrorEvent = {
+    agent: string;
+    error: AgentErrorInfo;
+    sessionID: string;
+    type: "error";
+};
+export type AgentTurnResult = {
+    agent: string;
+    error: AgentErrorInfo | null;
+    info: Message | null;
+    messageID: string | null;
+    parts: Part[];
+    sessionID: string;
+    text: string;
+};
+export type AgentResultEvent = {
+    agent: string;
+    result: AgentTurnResult;
+    sessionID: string;
+    type: "result";
+};
+export type AgentResponseEvent = AgentErrorEvent | AgentResultEvent | AgentStatusEvent | AgentTextEvent | AgentToolCallEvent;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,13 @@
+import type { Part } from "@opencode-ai/sdk/v2";
+import type { AgentErrorInfo } from "./types.js";
+type ResponseEnvelope<TData, TError> = {
+    data?: TData | null | undefined;
+    error?: TError | undefined;
+};
+export declare function requireData<TData, TError>(label: string, promise: Promise<ResponseEnvelope<TData, TError>>): Promise<Exclude<TData, null | undefined>>;
+export declare function delay(ms: number): Promise<void>;
+export declare function formatError(error: Error | object | string | number | boolean | null | undefined): string;
+export declare function extractTextFromParts(parts: Part[]): string;
+export declare function toErrorInfo(error: unknown): AgentErrorInfo;
+export declare function formatErrorInfo(error: AgentErrorInfo): string;
+export {};

package/dist/utils.js

@@ -0,0 +1,90 @@
+export async function requireData(label, promise) {
+    const response = await promise;
+    if (response.error) {
+        throw new Error(`${label} failed: ${JSON.stringify(response.error)}`);
+    }
+    if (response.data == null) {
+        throw new Error(`${label} failed: empty response data`);
+    }
+    return response.data;
+}
+export function delay(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+export function formatError(error) {
+    if (!(error instanceof Error)) {
+        return String(error);
+    }
+    const errorWithMetadata = error;
+    const details = [
+        typeof errorWithMetadata.code === "string" && `code=${JSON.stringify(errorWithMetadata.code)}`,
+        typeof errorWithMetadata.status === "number" && `status=${errorWithMetadata.status}`,
+        typeof errorWithMetadata.statusCode === "number" && `statusCode=${errorWithMetadata.statusCode}`,
+        errorWithMetadata.cause instanceof Error &&
+            errorWithMetadata.cause.message &&
+            `cause=${JSON.stringify(errorWithMetadata.cause.message)}`,
+    ].filter((detail) => Boolean(detail));
+    if (details.length === 0) {
+        return `${error.name}: ${error.message}`;
+    }
+    return `${error.name}: ${error.message} | ${details.join(", ")}`;
+}
+export function extractTextFromParts(parts) {
+    return parts
+        .filter((part) => part.type === "text")
+        .map((part) => part.text)
+        .join("");
+}
+export function toErrorInfo(error) {
+    if (error instanceof Error) {
+        const errorWithMetadata = error;
+        const result = {
+            name: error.name,
+            message: error.message,
+        };
+        if (typeof errorWithMetadata.code === "string") {
+            result.code = errorWithMetadata.code;
+        }
+        if (typeof errorWithMetadata.status === "number") {
+            result.status = errorWithMetadata.status;
+        }
+        if (typeof errorWithMetadata.statusCode === "number") {
+            result.statusCode = errorWithMetadata.statusCode;
+        }
+        return result;
+    }
+    if (typeof error === "object" && error !== null) {
+        const candidate = error;
+        const result = {
+            name: typeof candidate.name === "string" ? candidate.name : "Error",
+            message: typeof candidate.message === "string" ? candidate.message : JSON.stringify(error),
+        };
+        if (typeof candidate.code === "string") {
+            result.code = candidate.code;
+        }
+        if (typeof candidate.status === "number") {
+            result.status = candidate.status;
+        }
+        if (typeof candidate.statusCode === "number") {
+            result.statusCode = candidate.statusCode;
+        }
+        return result;
+    }
+    return {
+        name: "Error",
+        message: String(error),
+    };
+}
+export function formatErrorInfo(error) {
+    const details = [
+        typeof error.code === "string" && `code=${JSON.stringify(error.code)}`,
+        typeof error.status === "number" && `status=${error.status}`,
+        typeof error.statusCode === "number" && `statusCode=${error.statusCode}`,
+    ].filter((detail) => Boolean(detail));
+    if (details.length === 0) {
+        return `${error.name}: ${error.message}`;
+    }
+    return `${error.name}: ${error.message} | ${details.join(", ")}`;
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@liontree/opencode-agent-sdk",
+  "version": "0.1.0",
+  "description": "High-level agent runtime built on top of @opencode-ai/sdk",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@opencode-ai/sdk": "^1.2.15",
+    "opencode-ai": "^1.2.15"
+  },
+  "devDependencies": {
+    "@types/node": "^24.5.2",
+    "typescript": "^5.9.2"
+  },
+  "keywords": [
+    "opencode",
+    "agent",
+    "sdk"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LioTree/opencode-agent-sdk.git"
+  },
+  "homepage": "https://github.com/LioTree/opencode-agent-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/LioTree/opencode-agent-sdk/issues"
+  },
+  "license": "MIT"
+}