@liontree/opencode-agent-sdk 0.1.0 → 0.1.2

package/README.md

@@ -6,7 +6,7 @@ This package wraps OpenCode's lower-level session and SSE APIs with a more agent
 
 - declare agents once
 - create reusable sessions
-- call `query()` / `receiveResponse()` or `run()`
+- call `query()` / `receiveResponse()` or `runAgent()`
 - 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.
@@ -58,15 +58,14 @@ 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, and `examples/attach.ts` for attaching to an existing OpenCode server.
+
 ```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",
@@ -139,34 +138,113 @@ const runtime = await createAgentRuntime({
 })
 ```
 
-If you only need the final answer instead of a streamed event loop, use `run()`:
+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
-const result = await session.run("Summarize the current repository")
+const result = await session.runAgent("Summarize the current repository")
 
 console.log(result.text)
 ```
 
+To stream descendant subagent activity in the same turn, pass `includeSubagents: true` and read `event.source.chainText`:
+
+```ts
+await session.query("Investigate the auth flow", { includeSubagents: true })
+
+for await (const event of session.receiveResponse()) {
+  if (event.type === "tool_call") {
+    console.log(`[${event.source.chainText}]`, event.toolName, event.status)
+  }
+}
+```
+
+You can also reopen an existing session and optionally continue it with another turn:
+
+```ts
+const reopened = await runtime.resumeAgent({
+  sessionID: "sess_123",
+  prompt: "Continue from the last auth findings.",
+})
+
+for await (const event of reopened.receiveResponse()) {
+  if (event.type === "text") {
+    process.stdout.write(event.text)
+  }
+}
+```
+
+If you want a subagent to be able to launch another subagent via the `task` tool, you must allow it in that agent's permissions. OpenCode controls `task` separately from normal read/edit/bash permissions.
+
+```ts
+const runtime = await createAgentRuntime({
+  directory: "/app",
+  model: "openai/gpt-5.4",
+  config: {
+    agent: {
+      general: {
+        permission: {
+          task: {
+            "*": "allow",
+          },
+        },
+      },
+    },
+  },
+})
+```
+
+Use `config.agent.<name>.permission.task` when you want to override a built-in agent such as `general`. For custom agents declared in `options.agents`, you can also set `permission` directly on the agent definition.
+
 ## Main API
 
 ### `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 })`
 
 Creates a reusable OpenCode session and returns an `OpencodeAgentSession`.
 
+### `runtime.openSession(sessionID, { agent, model })`
+
+Opens an existing OpenCode session and returns an `OpencodeAgentSession` handle.
+
+### `runtime.listAgents()`
+
+Lists the agents currently available from the OpenCode runtime, including built-in subagents such as `general` and `explore`.
+
+### `runtime.runAgent({ agent, prompt, model })`
+
+Creates a fresh session, runs one turn, and resolves the final result.
+
+### `runtime.resumeAgent({ sessionID, prompt?, agent?, model?, includeSubagents? })`
+
+Reopens an existing session and optionally starts another turn on it.
+
 ### `session.query(prompt, options)`
 
 Starts one turn on the session.
 
+- pass `includeSubagents: true` to receive descendant subagent-session events in the same stream
+- to let a subagent launch more subagents, configure that agent's `permission.task`
+
 ### `session.receiveResponse()`
 
 Consumes the active turn as an async stream of normalized events:
@@ -179,7 +257,7 @@ Consumes the active turn as an async stream of normalized events:
 
 `receiveResponse()` is single-consumer per turn.
 
-### `session.run(prompt, options)`
+### `session.runAgent(prompt, options)`
 
 Convenience helper that internally calls `query()` and consumes the response stream until a final result is available.
 
@@ -212,9 +290,24 @@ Emitted for prompt failures, session errors, SSE errors, or shutdown problems.
 
 Emitted exactly once when the final assistant message can be resolved.
 
+## Source Metadata
+
+Every normalized event now includes a `source` object describing where it came from.
+
+- `source.agentType`: raw agent name such as `build`, `general`, or `explore`
+- `source.agentLabel`: display label with sibling ordinal when needed, such as `general#2`
+- `source.chainText`: readable lineage such as `build -> general#2 -> explore#1`
+- `source.sessionID`: the session that produced the event
+- `source.parentSessionID`: parent session ID when the event came from a descendant session
+- `source.rootSessionID`: root session for the current lineage
+- `source.taskID`: session ID when the event came from a subagent task, otherwise `null`
+- `source.sourceToolCallID`: originating `task` tool call when known
+
+`event.agent` and `result.agent` are preserved for compatibility and match `source.agentType`.
+
 ## Notes
 
 - This SDK is higher-level than raw OpenCode, not a workflow engine.
-- It does not implement multi-agent orchestration for you.
+- It exposes OpenCode subagent lineage metadata, but it does not implement orchestration policy 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

@@ -1,7 +1,7 @@
 import type { AgentDefinition, JsonObject, JsonValue, ModelReference, ModelSpec } from "./types.js";
 export type PlainObject = JsonObject;
 type BuildRuntimeConfigOptions = {
-    agents: Record<string, AgentDefinition>;
+    agents?: Record<string, AgentDefinition>;
     config?: PlainObject;
     mcp?: PlainObject;
     model?: ModelReference;

package/dist/config.js

@@ -65,15 +65,25 @@ function buildAgentConfig(agents) {
             mode: definition.mode ?? "primary",
             prompt: definition.prompt,
         };
+        if (definition.description) {
+            config.description = definition.description;
+        }
+        if (definition.model) {
+            config.model = toModelString(definition.model);
+        }
+        if (definition.permission) {
+            config.permission = definition.permission;
+        }
         return [name, config];
     });
     return Object.fromEntries(entries);
 }
 export function buildRuntimeConfig({ agents, config, mcp, model, permission, rawConfigContent, }) {
+    const resolvedAgents = agents ?? {};
     const inheritedInlineConfig = parseRuntimeConfigContent(resolveInlineConfigContent(rawConfigContent));
     const optionConfig = config ?? {};
     const managedConfig = {
-        agent: buildAgentConfig(agents),
+        agent: buildAgentConfig(resolvedAgents),
     };
     if (mcp) {
         managedConfig.mcp = mcp;

package/dist/index.d.ts

@@ -1,3 +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";
+export type { AgentDefinition, AgentErrorEvent, AgentErrorInfo, AgentEventSource, AgentMode, AgentQueryOptions, AgentResponseEvent, AgentResultEvent, AgentRunOptions, AgentRuntimeOptions, AgentRuntimeRunOptions, AgentSessionOptions, AgentStatusEvent, AgentTextEvent, AgentToolCallEvent, AgentTurnResult, JsonArray, JsonObject, JsonPrimitive, JsonValue, ModelReference, ModelSpec, ResumeAgentOptions, RuntimeAgentInfo, } from "./types.js";

package/dist/runtime.d.ts

@@ -1,5 +1,5 @@
 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";
+import type { AgentDefinition, AgentEventSource, AgentQueryOptions, AgentResponseEvent, AgentRunOptions, AgentRuntimeOptions, AgentRuntimeRunOptions, AgentSessionOptions, AgentTurnResult, ModelReference, ModelSpec, ResumeAgentOptions, RuntimeAgentInfo } from "./types.js";
 type ManagedServer = {
     close: () => void;
 };
@@ -15,6 +15,7 @@ export declare class OpencodeAgentSession {
     query(prompt: string, options?: AgentQueryOptions): Promise<void>;
     receiveResponse(): AsyncGenerator<AgentResponseEvent, void, unknown>;
     run(prompt: string, options?: AgentRunOptions): Promise<AgentTurnResult>;
+    runAgent(prompt: string, options?: AgentRunOptions): Promise<AgentTurnResult>;
     abort(): Promise<void>;
     interrupt(): Promise<void>;
 }
@@ -25,12 +26,34 @@ export declare class OpencodeAgentRuntime {
     private readonly defaultModel?;
     private disposed;
     private readonly agentDefinitions;
+    private runtimeAgentsPromise;
+    private readonly sessionInfoCache;
+    private readonly sessionNodeCache;
     constructor(client: OpencodeClient, directory: string, agents: Record<string, AgentDefinition>, managedServer?: ManagedServer | undefined, defaultModel?: ModelReference | undefined);
+    private getSessionNode;
+    private getSiblingOrdinal;
+    trackSessionInfo(session: Session): void;
+    trackSessionAgentType(sessionID: string, agentType: string, force?: boolean): void;
+    trackTaskSessionLink(input: {
+        agentType: string | null;
+        childSessionID: string;
+        parentSessionID: string;
+        sourceToolCallID: string | null;
+    }): void;
+    getSessionInfo(sessionID: string): Promise<Session>;
+    ensureSessionAgentType(sessionID: string, fallbackAgentType?: string): Promise<string | null>;
+    primeSessionLineage(sessionID: string, fallbackAgentType?: string): Promise<void>;
+    getKnownEventSource(sessionID: string, fallbackAgentType?: string): AgentEventSource;
     dispose(): Promise<void>;
     getAgent(name: string): AgentDefinition;
+    listAgents(): Promise<RuntimeAgentInfo[]>;
+    private getRuntimeAgentInfo;
     resolveModel(agentName: string, override?: ModelReference): Promise<ModelSpec>;
+    openSession(sessionID: string, options?: AgentSessionOptions): Promise<OpencodeAgentSession>;
     createSession(options?: AgentSessionOptions): Promise<OpencodeAgentSession>;
     run(options: AgentRuntimeRunOptions): Promise<AgentTurnResult>;
+    runAgent(options: AgentRuntimeRunOptions): Promise<AgentTurnResult>;
+    resumeAgent(options: ResumeAgentOptions): Promise<OpencodeAgentSession>;
 }
 export declare function createAgentRuntime(options: AgentRuntimeOptions): Promise<OpencodeAgentRuntime>;
 export type { Session };

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;
@@ -7,9 +7,11 @@ function isSessionEvent(event) {
     return (event.type === "message.part.updated" ||
         event.type === "message.part.delta" ||
         event.type === "message.updated" ||
+        event.type === "session.created" ||
         event.type === "session.status" ||
         event.type === "session.idle" ||
-        event.type === "session.error");
+        event.type === "session.error" ||
+        event.type === "session.updated");
 }
 function getEventSessionID(event) {
     switch (event.type) {
@@ -19,14 +21,43 @@ function getEventSessionID(event) {
             return event.properties.sessionID;
         case "message.updated":
             return event.properties.info.sessionID;
+        case "session.created":
+            return event.properties.info.id;
         case "session.status":
             return event.properties.sessionID;
         case "session.idle":
             return event.properties.sessionID;
         case "session.error":
             return event.properties.sessionID;
+        case "session.updated":
+            return event.properties.info.id;
     }
 }
+function isRecord(value) {
+    return value !== null && typeof value === "object";
+}
+function getRecordString(value, key) {
+    if (!isRecord(value)) {
+        return null;
+    }
+    const candidate = value[key];
+    return typeof candidate === "string" && candidate.length > 0 ? candidate : null;
+}
+function parseSubagentFromTitle(title) {
+    if (!title) {
+        return null;
+    }
+    const match = /\(@([^()]+) subagent\)$/.exec(title.trim());
+    return match?.[1] ?? null;
+}
+function compareSessionNodes(a, b, sessionInfoCache) {
+    const aCreated = sessionInfoCache.get(a.sessionID)?.time.created ?? Number.MAX_SAFE_INTEGER;
+    const bCreated = sessionInfoCache.get(b.sessionID)?.time.created ?? Number.MAX_SAFE_INTEGER;
+    if (aCreated !== bCreated) {
+        return aCreated - bCreated;
+    }
+    return a.sessionID.localeCompare(b.sessionID);
+}
 function createIdleGate() {
     let resolved = false;
     let resolveSignal = () => { };
@@ -43,14 +74,16 @@ function createIdleGate() {
         },
     };
 }
-function createTurnContext() {
+function createTurnContext(rootSessionID) {
     return {
         assistantMessageIDs: new Set(),
+        hasAssistantMessage: false,
         idleGate: createIdleGate(),
-        lastStatus: "",
-        latestAssistantMessageID: null,
+        lastStatusBySessionID: new Map([[rootSessionID, "pending"]]),
+        latestRootAssistantMessageID: null,
         sawBusy: false,
         textByPartID: new Map(),
+        trackedSessionIDs: new Set([rootSessionID]),
         toolStatusByPartID: new Map(),
     };
 }
@@ -140,44 +173,64 @@ class ActiveTurn {
     emit(event) {
         this.queue.push(event);
     }
-    emitError(error) {
+    getEventSource(sessionID, fallbackAgentType) {
+        const rootFallback = sessionID === this.args.sessionID ? this.args.agent : undefined;
+        return this.args.runtime.getKnownEventSource(sessionID, fallbackAgentType ?? rootFallback);
+    }
+    emitError(error, sessionID = this.args.sessionID, fallbackAgentType) {
+        const source = this.getEventSource(sessionID, fallbackAgentType);
         this.emit({
             type: "error",
-            agent: this.args.agent,
-            sessionID: this.args.sessionID,
+            agent: source.agentType,
+            sessionID,
+            source,
             error: toErrorInfo(error),
         });
     }
     markIdleIfReady(context) {
-        if (context.sawBusy || context.latestAssistantMessageID !== null) {
+        if (context.sawBusy || context.hasAssistantMessage) {
+            if (this.args.includeSubagents) {
+                for (const sessionID of context.trackedSessionIDs) {
+                    if (context.lastStatusBySessionID.get(sessionID) !== "idle") {
+                        return;
+                    }
+                }
+            }
             context.idleGate.mark();
         }
     }
-    emitStatus(context, status) {
-        if (!status || status === context.lastStatus) {
+    emitStatus(sessionID, context, status, fallbackAgentType) {
+        const previous = context.lastStatusBySessionID.get(sessionID) ?? "";
+        if (!status || status === previous) {
             return;
         }
-        context.lastStatus = status;
+        context.lastStatusBySessionID.set(sessionID, status);
+        const source = this.getEventSource(sessionID, fallbackAgentType);
         this.emit({
             type: "status",
-            agent: this.args.agent,
-            sessionID: this.args.sessionID,
+            agent: source.agentType,
+            sessionID,
+            source,
             status,
         });
     }
-    emitTextEvent(event) {
+    emitTextEvent(sessionID, event) {
+        const source = this.getEventSource(sessionID);
         this.emit({
             type: "text",
-            agent: this.args.agent,
-            sessionID: this.args.sessionID,
+            agent: source.agentType,
+            sessionID,
+            source,
             ...event,
         });
     }
-    emitToolCallEvent(event) {
+    emitToolCallEvent(sessionID, event) {
+        const source = this.getEventSource(sessionID);
         this.emit({
             type: "tool_call",
-            agent: this.args.agent,
-            sessionID: this.args.sessionID,
+            agent: source.agentType,
+            sessionID,
+            source,
             ...event,
         });
     }
@@ -187,7 +240,7 @@ class ActiveTurn {
         }
         const previous = context.textByPartID.get(event.properties.partID) ?? "";
         context.textByPartID.set(event.properties.partID, `${previous}${event.properties.delta}`);
-        this.emitTextEvent({
+        this.emitTextEvent(event.properties.sessionID, {
             format: "delta",
             messageID: event.properties.messageID,
             partID: event.properties.partID,
@@ -210,7 +263,7 @@ class ActiveTurn {
         if (!format || !text) {
             return;
         }
-        this.emitTextEvent({
+        this.emitTextEvent(part.sessionID, {
             format,
             messageID: part.messageID,
             partID: part.id,
@@ -243,32 +296,97 @@ class ActiveTurn {
         if (part.state.status === "error") {
             event.error = part.state.error;
         }
-        this.emitToolCallEvent({
+        this.emitToolCallEvent(part.sessionID, {
             ...event,
         });
     }
+    extractTaskChildSessionID(part) {
+        if (part.tool !== "task") {
+            return null;
+        }
+        const metadata = "metadata" in part.state ? part.state.metadata : undefined;
+        return getRecordString(metadata, "sessionId") ?? getRecordString(part.state.input, "task_id");
+    }
+    extractTaskAgentType(part) {
+        if (part.tool !== "task") {
+            return null;
+        }
+        return getRecordString(part.state.input, "subagent_type");
+    }
+    trackDiscoveredSessions(event, context) {
+        switch (event.type) {
+            case "session.created":
+            case "session.updated": {
+                this.args.runtime.trackSessionInfo(event.properties.info);
+                if (this.args.includeSubagents &&
+                    event.properties.info.parentID &&
+                    context.trackedSessionIDs.has(event.properties.info.parentID)) {
+                    context.trackedSessionIDs.add(event.properties.info.id);
+                    if (!context.lastStatusBySessionID.has(event.properties.info.id)) {
+                        context.lastStatusBySessionID.set(event.properties.info.id, "pending");
+                    }
+                }
+                return;
+            }
+            case "message.updated":
+                this.args.runtime.trackSessionAgentType(event.properties.info.sessionID, event.properties.info.agent);
+                return;
+            case "message.part.updated": {
+                if (!this.args.includeSubagents || event.properties.part.type !== "tool") {
+                    return;
+                }
+                const part = event.properties.part;
+                if (!context.trackedSessionIDs.has(part.sessionID)) {
+                    return;
+                }
+                const childSessionID = this.extractTaskChildSessionID(part);
+                if (!childSessionID) {
+                    return;
+                }
+                this.args.runtime.trackTaskSessionLink({
+                    agentType: this.extractTaskAgentType(part),
+                    childSessionID,
+                    parentSessionID: part.sessionID,
+                    sourceToolCallID: part.callID,
+                });
+                context.trackedSessionIDs.add(childSessionID);
+                if (!context.lastStatusBySessionID.has(childSessionID)) {
+                    context.lastStatusBySessionID.set(childSessionID, "pending");
+                }
+                return;
+            }
+            default:
+                return;
+        }
+    }
     handleSessionEvent(event, context) {
         switch (event.type) {
+            case "session.created":
+            case "session.updated":
+                return;
             case "session.status":
                 if (event.properties.status.type === "busy") {
                     context.sawBusy = true;
                 }
+                this.emitStatus(event.properties.sessionID, context, event.properties.status.type);
                 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");
+                this.emitStatus(event.properties.sessionID, context, "idle");
                 return;
             case "session.error":
-                this.emitError(event.properties.error);
+                this.emitError(event.properties.error, event.properties.sessionID);
                 return;
             case "message.updated":
                 if (event.properties.info.role === "assistant") {
                     context.assistantMessageIDs.add(event.properties.info.id);
-                    context.latestAssistantMessageID = event.properties.info.id;
+                    context.hasAssistantMessage = true;
+                    if (event.properties.info.sessionID === this.args.sessionID) {
+                        context.latestRootAssistantMessageID = event.properties.info.id;
+                    }
                 }
                 return;
             case "message.part.delta":
@@ -344,12 +462,15 @@ class ActiveTurn {
         };
     }
     async run() {
-        const context = createTurnContext();
+        await this.args.runtime.primeSessionLineage(this.args.sessionID, this.args.agent);
+        const context = createTurnContext(this.args.sessionID);
         const events = await this.subscribeToEvents();
         const consumeTask = (async () => {
             try {
                 for await (const event of events.stream) {
-                    if (getEventSessionID(event) !== this.args.sessionID) {
+                    this.trackDiscoveredSessions(event, context);
+                    const sessionID = getEventSessionID(event);
+                    if (!sessionID || !context.trackedSessionIDs.has(sessionID)) {
                         continue;
                     }
                     this.handleSessionEvent(event, context);
@@ -380,12 +501,7 @@ class ActiveTurn {
         }
         catch (error) {
             turnError = toErrorInfo(error);
-            this.emit({
-                type: "error",
-                agent: this.args.agent,
-                sessionID: this.args.sessionID,
-                error: turnError,
-            });
+            this.emitError(turnError);
         }
         finally {
             await delay(POST_IDLE_EVENT_DRAIN_MS);
@@ -404,12 +520,7 @@ class ActiveTurn {
             catch (error) {
                 const shutdownError = toErrorInfo(error);
                 turnError ??= shutdownError;
-                this.emit({
-                    type: "error",
-                    agent: this.args.agent,
-                    sessionID: this.args.sessionID,
-                    error: shutdownError,
-                });
+                this.emitError(shutdownError);
             }
             finally {
                 if (shutdownTimer) {
@@ -418,34 +529,31 @@ class ActiveTurn {
             }
         }
         try {
-            const resolved = await this.resolveLatestAssistantMessage(this.args.sessionID, context.latestAssistantMessageID);
+            const resolved = await this.resolveLatestAssistantMessage(this.args.sessionID, context.latestRootAssistantMessageID);
+            const source = this.getEventSource(this.args.sessionID, this.args.agent);
             const result = {
-                agent: this.args.agent,
+                agent: source.agentType,
                 error: turnError ?? getAssistantMessageError(resolved.info),
                 info: resolved.info,
-                messageID: resolved.info?.id ?? context.latestAssistantMessageID,
+                messageID: resolved.info?.id ?? context.latestRootAssistantMessageID,
                 parts: resolved.parts,
                 sessionID: this.args.sessionID,
+                source,
                 text: extractTextFromParts(resolved.parts),
             };
             if (result.info || result.parts.length > 0 || result.error) {
                 this.finalResult = result;
                 this.emit({
                     type: "result",
-                    agent: this.args.agent,
+                    agent: source.agentType,
                     sessionID: this.args.sessionID,
+                    source,
                     result,
                 });
             }
         }
         catch (error) {
-            const resolveError = toErrorInfo(error);
-            this.emit({
-                type: "error",
-                agent: this.args.agent,
-                sessionID: this.args.sessionID,
-                error: resolveError,
-            });
+            this.emitError(toErrorInfo(error));
         }
         finally {
             this.queue.close();
@@ -478,13 +586,16 @@ export class OpencodeAgentSession {
             if (!agent) {
                 throw new Error("No agent selected. Pass agent to createSession(), query(), or run().");
             }
+            this.runtime.trackSessionAgentType(this.id, agent, true);
             const model = await this.runtime.resolveModel(agent, options.model ?? this.defaultModel);
             this.activeTurn = new ActiveTurn({
                 agent,
                 client: this.runtime.client,
                 directory: this.runtime.directory,
+                includeSubagents: options.includeSubagents ?? false,
                 model,
                 prompt,
+                runtime: this.runtime,
                 sessionID: this.id,
             });
         }
@@ -528,6 +639,9 @@ export class OpencodeAgentSession {
         }
         throw new Error("Agent turn completed without a final result");
     }
+    async runAgent(prompt, options = {}) {
+        return this.run(prompt, options);
+    }
     async abort() {
         await requireData("session.abort", this.runtime.client.session.abort({
             sessionID: this.id,
@@ -545,6 +659,9 @@ export class OpencodeAgentRuntime {
     defaultModel;
     disposed = false;
     agentDefinitions;
+    runtimeAgentsPromise = null;
+    sessionInfoCache = new Map();
+    sessionNodeCache = new Map();
     constructor(client, directory, agents, managedServer, defaultModel) {
         this.client = client;
         this.directory = directory;
@@ -552,6 +669,149 @@ export class OpencodeAgentRuntime {
         this.defaultModel = defaultModel;
         this.agentDefinitions = new Map(Object.entries(agents));
     }
+    getSessionNode(sessionID) {
+        let node = this.sessionNodeCache.get(sessionID);
+        if (!node) {
+            node = {
+                agentType: null,
+                parentSessionID: null,
+                sessionID,
+                sourceToolCallID: null,
+                title: null,
+            };
+            this.sessionNodeCache.set(sessionID, node);
+        }
+        return node;
+    }
+    getSiblingOrdinal(node) {
+        if (!node.parentSessionID || !node.agentType) {
+            return null;
+        }
+        const siblings = [...this.sessionNodeCache.values()]
+            .filter((candidate) => candidate.parentSessionID === node.parentSessionID && candidate.agentType === node.agentType)
+            .sort((left, right) => compareSessionNodes(left, right, this.sessionInfoCache));
+        const index = siblings.findIndex((candidate) => candidate.sessionID === node.sessionID);
+        return index >= 0 ? index + 1 : null;
+    }
+    trackSessionInfo(session) {
+        this.sessionInfoCache.set(session.id, session);
+        const node = this.getSessionNode(session.id);
+        node.parentSessionID = session.parentID ?? null;
+        node.title = session.title;
+        const titleAgent = parseSubagentFromTitle(session.title);
+        if (titleAgent && !node.agentType) {
+            node.agentType = titleAgent;
+        }
+    }
+    trackSessionAgentType(sessionID, agentType, force = false) {
+        if (!agentType) {
+            return;
+        }
+        const node = this.getSessionNode(sessionID);
+        if (force || !node.agentType) {
+            node.agentType = agentType;
+        }
+    }
+    trackTaskSessionLink(input) {
+        const node = this.getSessionNode(input.childSessionID);
+        if (!node.parentSessionID) {
+            node.parentSessionID = input.parentSessionID;
+        }
+        if (!node.sourceToolCallID && input.sourceToolCallID) {
+            node.sourceToolCallID = input.sourceToolCallID;
+        }
+        if (!node.agentType && input.agentType) {
+            node.agentType = input.agentType;
+        }
+    }
+    async getSessionInfo(sessionID) {
+        const cached = this.sessionInfoCache.get(sessionID);
+        if (cached) {
+            return cached;
+        }
+        const session = await requireData("session.get", this.client.session.get({
+            sessionID,
+            directory: this.directory,
+        }));
+        this.trackSessionInfo(session);
+        return session;
+    }
+    async ensureSessionAgentType(sessionID, fallbackAgentType) {
+        const node = this.getSessionNode(sessionID);
+        if (node.agentType) {
+            return node.agentType;
+        }
+        const titleAgent = parseSubagentFromTitle(node.title);
+        if (titleAgent) {
+            node.agentType = titleAgent;
+            return node.agentType;
+        }
+        try {
+            const messages = await requireData("session.messages", this.client.session.messages({
+                sessionID,
+                directory: this.directory,
+            }));
+            const messageWithAgent = [...messages]
+                .reverse()
+                .find((entry) => typeof entry.info.agent === "string" && entry.info.agent.length > 0);
+            if (messageWithAgent?.info.agent) {
+                node.agentType = messageWithAgent.info.agent;
+                return node.agentType;
+            }
+        }
+        catch {
+            // Ignore cache warm-up failures and fall back below.
+        }
+        if (fallbackAgentType) {
+            node.agentType = fallbackAgentType;
+            return node.agentType;
+        }
+        return null;
+    }
+    async primeSessionLineage(sessionID, fallbackAgentType) {
+        let currentSessionID = sessionID;
+        while (currentSessionID) {
+            const session = await this.getSessionInfo(currentSessionID);
+            await this.ensureSessionAgentType(currentSessionID, currentSessionID === sessionID ? fallbackAgentType : undefined);
+            currentSessionID = session.parentID ?? null;
+        }
+    }
+    getKnownEventSource(sessionID, fallbackAgentType) {
+        const leaf = this.getSessionNode(sessionID);
+        if (!leaf.agentType && fallbackAgentType) {
+            leaf.agentType = fallbackAgentType;
+        }
+        const lineage = [];
+        const seen = new Set();
+        let cursor = leaf;
+        while (cursor && !seen.has(cursor.sessionID)) {
+            lineage.push(cursor);
+            seen.add(cursor.sessionID);
+            cursor = cursor.parentSessionID ? this.sessionNodeCache.get(cursor.parentSessionID) : undefined;
+        }
+        const ordered = lineage.reverse();
+        const chain = ordered.map((node, index) => {
+            const agentType = node.agentType ?? (node.sessionID === sessionID ? fallbackAgentType : undefined) ?? "unknown";
+            if (index === 0) {
+                return agentType;
+            }
+            const ordinal = this.getSiblingOrdinal(node);
+            return ordinal ? `${agentType}#${ordinal}` : agentType;
+        });
+        const agentType = leaf.agentType ?? fallbackAgentType ?? "unknown";
+        return {
+            agentLabel: chain[chain.length - 1] ?? agentType,
+            agentType,
+            chain,
+            chainText: chain.join(" -> "),
+            depth: Math.max(chain.length - 1, 0),
+            parentSessionID: leaf.parentSessionID,
+            rootSessionID: ordered[0]?.sessionID ?? sessionID,
+            sessionID,
+            sourceToolCallID: leaf.sourceToolCallID,
+            taskID: leaf.parentSessionID ? sessionID : null,
+        };
+    }
     async dispose() {
         if (this.disposed) {
             return;
@@ -566,9 +826,49 @@ export class OpencodeAgentRuntime {
         }
         return agent;
     }
+    async listAgents() {
+        if (!this.runtimeAgentsPromise) {
+            this.runtimeAgentsPromise = requireData("app.agents", this.client.app.agents({
+                directory: this.directory,
+            })).then((agents) => agents.map((agent) => {
+                const info = {
+                    mode: agent.mode,
+                    name: agent.name,
+                };
+                if (agent.color) {
+                    info.color = agent.color;
+                }
+                if (agent.description) {
+                    info.description = agent.description;
+                }
+                if (typeof agent.hidden === "boolean") {
+                    info.hidden = agent.hidden;
+                }
+                if (agent.model) {
+                    info.model = {
+                        modelID: agent.model.modelID,
+                        providerID: agent.model.providerID,
+                    };
+                }
+                if (typeof agent.native === "boolean") {
+                    info.native = agent.native;
+                }
+                if (typeof agent.steps === "number") {
+                    info.steps = agent.steps;
+                }
+                return info;
+            }));
+        }
+        return this.runtimeAgentsPromise;
+    }
+    async getRuntimeAgentInfo(name) {
+        const agents = await this.listAgents();
+        return agents.find((agent) => agent.name === name) ?? null;
+    }
     async resolveModel(agentName, override) {
-        const agentModel = this.getAgent(agentName).model;
-        const selected = override ?? agentModel ?? this.defaultModel;
+        const configuredModel = this.agentDefinitions.get(agentName)?.model;
+        const runtimeModel = (await this.getRuntimeAgentInfo(agentName))?.model;
+        const selected = override ?? configuredModel ?? runtimeModel ?? this.defaultModel;
         if (selected) {
             return normalizeModelReference(selected);
         }
@@ -581,6 +881,12 @@ export class OpencodeAgentRuntime {
         }
         return resolved;
     }
+    async openSession(sessionID, options = {}) {
+        const session = await this.getSessionInfo(sessionID);
+        await this.primeSessionLineage(sessionID, options.agent);
+        const defaultAgent = (await this.ensureSessionAgentType(sessionID, options.agent ?? parseSubagentFromTitle(session.title) ?? undefined)) ?? undefined;
+        return new OpencodeAgentSession(this, sessionID, defaultAgent, options.model);
+    }
     async createSession(options = {}) {
         if (this.disposed) {
             throw new Error("Runtime has been disposed");
@@ -588,6 +894,10 @@ export class OpencodeAgentRuntime {
         const session = await requireData("session.create", this.client.session.create({
             directory: this.directory,
         }));
+        this.trackSessionInfo(session);
+        if (options.agent) {
+            this.trackSessionAgentType(session.id, options.agent);
+        }
         return new OpencodeAgentSession(this, session.id, options.agent, options.model);
     }
     async run(options) {
@@ -598,10 +908,38 @@ export class OpencodeAgentRuntime {
         const session = await this.createSession(sessionOptions);
         return session.run(options.prompt);
     }
+    async runAgent(options) {
+        return this.run(options);
+    }
+    async resumeAgent(options) {
+        const session = await this.openSession(options.sessionID, {
+            ...(options.agent ? { agent: options.agent } : {}),
+            ...(options.model ? { model: options.model } : {}),
+        });
+        if (options.prompt) {
+            await session.query(options.prompt, {
+                ...(options.agent ? { agent: options.agent } : {}),
+                ...(typeof options.includeSubagents === "boolean" ? { includeSubagents: options.includeSubagents } : {}),
+                ...(options.model ? { model: options.model } : {}),
+            });
+        }
+        return session;
+    }
 }
 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.agents,
+        agents,
         ...(options.config ? { config: options.config } : {}),
         ...(options.mcp ? { mcp: options.mcp } : {}),
         ...(options.model ? { model: options.model } : {}),
@@ -614,5 +952,5 @@ export async function createAgentRuntime(options) {
         timeout: options.timeoutMs ?? 15000,
         config: runtimeConfig,
     });
-    return new OpencodeAgentRuntime(client, options.directory, options.agents, server, options.model);
+    return new OpencodeAgentRuntime(client, options.directory, agents, server, options.model);
 }

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { Message, Part, ToolState } from "@opencode-ai/sdk/v2";
+import type { Agent as OpencodeAgent, 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[];
@@ -10,14 +10,16 @@ export type ModelSpec = {
     providerID: string;
 };
 export type ModelReference = ModelSpec | `${string}/${string}`;
+export type AgentMode = "all" | "primary" | "subagent";
 export type AgentDefinition = {
     description?: string;
     model?: ModelReference;
-    mode?: string;
+    mode?: AgentMode;
+    permission?: JsonObject;
     prompt: string;
 };
 export type AgentRuntimeOptions = {
-    agents: Record<string, AgentDefinition>;
+    agents?: Record<string, AgentDefinition>;
     config?: JsonObject;
     directory: string;
     hostname?: string;
@@ -26,19 +28,27 @@ export type AgentRuntimeOptions = {
     permission?: JsonObject;
     port?: number;
     rawConfigContent?: string;
+    serverUrl?: string;
     timeoutMs?: number;
 };
 export type AgentSessionOptions = {
     agent?: string;
     model?: ModelReference;
 };
-export type AgentQueryOptions = AgentSessionOptions;
-export type AgentRunOptions = AgentSessionOptions;
+export type AgentQueryOptions = AgentSessionOptions & {
+    includeSubagents?: boolean;
+};
+export type AgentRunOptions = AgentQueryOptions;
 export type AgentRuntimeRunOptions = {
     agent: string;
     model?: ModelReference;
     prompt: string;
 };
+export type ResumeAgentOptions = AgentSessionOptions & {
+    includeSubagents?: boolean;
+    prompt?: string;
+    sessionID: string;
+};
 export type AgentErrorInfo = {
     code?: string;
     message: string;
@@ -46,10 +56,26 @@ export type AgentErrorInfo = {
     status?: number;
     statusCode?: number;
 };
+export type AgentEventSource = {
+    agentLabel: string;
+    agentType: string;
+    chain: string[];
+    chainText: string;
+    depth: number;
+    parentSessionID: string | null;
+    rootSessionID: string;
+    sessionID: string;
+    sourceToolCallID: string | null;
+    taskID: string | null;
+};
+export type RuntimeAgentInfo = Pick<OpencodeAgent, "color" | "description" | "hidden" | "mode" | "name" | "native" | "steps"> & {
+    model?: ModelSpec;
+};
 export type AgentStatusEvent = {
     agent: string;
     sessionID: string;
     status: string;
+    source: AgentEventSource;
     type: "status";
 };
 export type AgentTextEvent = {
@@ -58,6 +84,7 @@ export type AgentTextEvent = {
     messageID: string;
     partID: string;
     sessionID: string;
+    source: AgentEventSource;
     text: string;
     type: "text";
 };
@@ -71,6 +98,7 @@ export type AgentToolCallEvent = {
     output?: string;
     partID: string;
     sessionID: string;
+    source: AgentEventSource;
     status: ToolState["status"];
     title?: string;
     toolName: string;
@@ -80,6 +108,7 @@ export type AgentErrorEvent = {
     agent: string;
     error: AgentErrorInfo;
     sessionID: string;
+    source: AgentEventSource;
     type: "error";
 };
 export type AgentTurnResult = {
@@ -89,12 +118,14 @@ export type AgentTurnResult = {
     messageID: string | null;
     parts: Part[];
     sessionID: string;
+    source: AgentEventSource;
     text: string;
 };
 export type AgentResultEvent = {
     agent: string;
     result: AgentTurnResult;
     sessionID: string;
+    source: AgentEventSource;
     type: "result";
 };
 export type AgentResponseEvent = AgentErrorEvent | AgentResultEvent | AgentStatusEvent | AgentTextEvent | AgentToolCallEvent;

package/package.json

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