@liontree/opencode-agent-sdk 0.1.1 → 0.1.2

package/README.md

@@ -58,7 +58,7 @@ This package declares `@opencode-ai/sdk` and `opencode-ai` as dependencies, so y
 npm install @liontree/opencode-agent-sdk
 ```
 
-See `examples/subagents.ts` for a complete subagent lineage and `resumeAgent()` example.
+See `examples/subagents.ts` for a complete subagent lineage and `resumeAgent()` example, and `examples/attach.ts` for attaching to an existing OpenCode server.
 
 ```ts
 import { createAgentRuntime } from "@liontree/opencode-agent-sdk"
@@ -138,6 +138,18 @@ const runtime = await createAgentRuntime({
 })
 ```
 
+If you already have an OpenCode server running, attach to it with `serverUrl`:
+
+```ts
+const runtime = await createAgentRuntime({
+  directory: "/app",
+  serverUrl: "http://127.0.0.1:40937",
+  model: "openai/gpt-5.4",
+})
+```
+
+In attach mode, `model` still works as a local default and is sent with each prompt. Other runtime config such as `config`, `mcp`, `permission`, and `rawConfigContent` is not pushed into the existing server.
+
 If you only need the final answer instead of a streamed event loop, use `runAgent()`:
 
 ```ts
@@ -199,13 +211,12 @@ Use `config.agent.<name>.permission.task` when you want to override a built-in a
 
 ### `createAgentRuntime(options)`
 
-Creates a managed OpenCode runtime and injects:
+Creates an OpenCode runtime in one of two modes:
+
+- managed mode: starts and manages an OpenCode server, then injects agent prompts, optional default model, optional MCP config, optional permission config, and optional extra config merged with inherited inline config
+- attach mode: connects to an existing OpenCode server with `serverUrl`
 
-- agent prompts
-- optional default model
-- optional MCP config
-- optional permission config
-- optional extra config merged with inherited inline config
+Attach mode does not push `config`, `mcp`, `permission`, or `rawConfigContent` into the existing server. `model` still works as a local default and is sent with each prompt. `serverUrl` cannot be combined with `hostname`, `port`, or `timeoutMs`.
 
 ### `runtime.createSession({ agent, model })`
 

package/dist/runtime.js

@@ -1,4 +1,4 @@
-import { createOpencode, } from "@opencode-ai/sdk/v2";
+import { createOpencode, createOpencodeClient, } 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;
@@ -928,6 +928,16 @@ export class OpencodeAgentRuntime {
 }
 export async function createAgentRuntime(options) {
     const agents = options.agents ?? {};
+    if (options.serverUrl) {
+        if (typeof options.hostname === "string" || typeof options.port === "number" || typeof options.timeoutMs === "number") {
+            throw new Error("serverUrl cannot be combined with hostname, port, or timeoutMs");
+        }
+        const client = createOpencodeClient({
+            baseUrl: options.serverUrl,
+            directory: options.directory,
+        });
+        return new OpencodeAgentRuntime(client, options.directory, agents, undefined, options.model);
+    }
     const runtimeConfig = buildRuntimeConfig({
         agents,
         ...(options.config ? { config: options.config } : {}),

package/dist/types.d.ts

@@ -28,6 +28,7 @@ export type AgentRuntimeOptions = {
     permission?: JsonObject;
     port?: number;
     rawConfigContent?: string;
+    serverUrl?: string;
     timeoutMs?: number;
 };
 export type AgentSessionOptions = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liontree/opencode-agent-sdk",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "High-level agent runtime built on top of @opencode-ai/sdk",
   "type": "module",
   "main": "./dist/index.js",