@softprobe/opencode-plugin 0.1.1 → 0.1.5

package/README.md

@@ -67,4 +67,20 @@ credentials when `SPCODE_MODE` is on (see softprobe-code
 - Retries, reasoning, compaction events
 - Failed steps and session errors / aborts
 
+### Sub-agent sessions
+
+OpenCode runs sub-agents (the `task` tool) in child sessions. The plugin nests
+each child session's turn under the dispatching task span, so a whole agent
+run — root session plus any sub-agents, recursively — forms a single trace
+instead of several disconnected ones. The link comes from the task part's
+`state.metadata.sessionId` (authoritative), with `task_id` resume and
+parentID + task-call inference as fallbacks; ambiguous dispatches (e.g.
+parallel identical task calls) are left unnested rather than guessed. Each
+span keeps its own `sp.session.id`; the parent side is recorded as
+`sp.metadata.opencode.parentSessionID` / `sp.metadata.opencode.parentTaskCallID`
+on the child turn and `sp.child.session.id` on the task span.
+
+Session lifecycle is isolated per session: a sub-agent session going idle
+finalizes only its own spans, never the parent session's in-flight work.
+
 See [Coding agents](../../docs/integrations/coding-agents.md).

package/dist/bounded.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Insertion-ordered collections with a hard cap.
+ *
+ * Used for bookkeeping that has to outlive a single session: dedup keys must
+ * survive a scoped `session.idle` (otherwise a late duplicate delivery
+ * recreates a span that was already force-ended), but nothing clears them
+ * afterwards except process shutdown. A cap keeps them from growing without
+ * bound on a long-lived `opencode serve` while preserving the property that
+ * matters — recent ids are always remembered.
+ */
+export declare class BoundedSet {
+    private readonly cap;
+    private readonly items;
+    constructor(cap: number);
+    get size(): number;
+    has(key: string): boolean;
+    /** Insertion order is kept: re-adding a known key does not refresh it. */
+    add(key: string): void;
+}
+export declare class BoundedMap<V> {
+    private readonly cap;
+    private readonly items;
+    constructor(cap: number);
+    get size(): number;
+    get(key: string): V | undefined;
+    /** Writing a key refreshes its position, so active entries are not evicted. */
+    set(key: string, value: V): void;
+    delete(key: string): void;
+}

package/dist/bounded.js

@@ -0,0 +1,62 @@
+/**
+ * Insertion-ordered collections with a hard cap.
+ *
+ * Used for bookkeeping that has to outlive a single session: dedup keys must
+ * survive a scoped `session.idle` (otherwise a late duplicate delivery
+ * recreates a span that was already force-ended), but nothing clears them
+ * afterwards except process shutdown. A cap keeps them from growing without
+ * bound on a long-lived `opencode serve` while preserving the property that
+ * matters — recent ids are always remembered.
+ */
+export class BoundedSet {
+    cap;
+    items = new Set();
+    constructor(cap) {
+        this.cap = cap;
+    }
+    get size() {
+        return this.items.size;
+    }
+    has(key) {
+        return this.items.has(key);
+    }
+    /** Insertion order is kept: re-adding a known key does not refresh it. */
+    add(key) {
+        if (this.items.has(key))
+            return;
+        this.items.add(key);
+        while (this.items.size > this.cap) {
+            const oldest = this.items.values().next().value;
+            if (oldest === undefined)
+                return;
+            this.items.delete(oldest);
+        }
+    }
+}
+export class BoundedMap {
+    cap;
+    items = new Map();
+    constructor(cap) {
+        this.cap = cap;
+    }
+    get size() {
+        return this.items.size;
+    }
+    get(key) {
+        return this.items.get(key);
+    }
+    /** Writing a key refreshes its position, so active entries are not evicted. */
+    set(key, value) {
+        this.items.delete(key);
+        this.items.set(key, value);
+        while (this.items.size > this.cap) {
+            const oldest = this.items.keys().next().value;
+            if (oldest === undefined)
+                return;
+            this.items.delete(oldest);
+        }
+    }
+    delete(key) {
+        this.items.delete(key);
+    }
+}

package/dist/index.d.ts

@@ -14,5 +14,8 @@ declare const _default: {
 };
 export default _default;
 export { SoftprobeSessionTracer, createSoftprobeSessionTracer, } from "./softprobe.js";
+export { SessionGraph, parseTaskCallArgs } from "./session-graph.js";
+export type { TaskBinding, TaskCallArgs } from "./session-graph.js";
+export type { SessionLookup } from "./types.js";
 export { loadSoftprobeCredentials, MissingSoftprobeCredentialsError, defaultConfigDir, defaultConfigPath, type SoftprobePluginCredentials, } from "./config.js";
 export { inferToolKind } from "./tool-kind.js";

package/dist/index.js

@@ -1,5 +1,6 @@
 import { loadSoftprobeCredentials, MissingSoftprobeCredentialsError, } from "./config.js";
 import { createSoftprobeSessionTracer, } from "./softprobe.js";
+import { BoundedMap } from "./bounded.js";
 function log(level, message) {
     const line = `[softprobe-opencode] ${message}`;
     if (level === "error")
@@ -36,102 +37,50 @@ function createShutdownOnce(tracer) {
         return shutdownPromise;
     };
 }
-async function handleEvent(tracer, event, shutdown) {
-    if (event.type === "session.idle") {
-        log("info", "Flushing spans");
-        tracer.finalizeSessionTracing();
-        await tracer.forceFlush();
-    }
-    if (event.type === "server.instance.disposed") {
-        tracer.finalizeSessionTracing();
-        if (shutdown)
-            await shutdown();
-    }
-    if (event.type === "session.error" && "properties" in event) {
-        const props = event.properties;
-        if (props.sessionID) {
-            tracer.traceSessionError({
-                sessionID: props.sessionID,
-                error: props.error,
-            });
-        }
-    }
-    if (event.type === "message.part.updated" && "properties" in event) {
-        const part = event.properties.part;
-        tracer.rememberAssistantPart(part);
-        tracer.traceReasoningPart(part);
-        tracer.traceToolPart(part);
-    }
-    if (event.type === "session.next.step.started") {
-        tracer.startActiveGenerationStep({
-            sessionID: event.properties.sessionID,
-            agent: event.properties.agent,
-            model: event.properties.model,
-            started: event.properties.timestamp,
-            snapshot: event.properties.snapshot,
-        });
-    }
-    if (event.type === "session.next.step.failed") {
-        tracer.traceFailedGenerationStep({
-            id: event.id,
-            sessionID: event.properties.sessionID,
-            completed: event.properties.timestamp,
-            error: event.properties.error,
-        });
-    }
-    if (event.type === "session.next.retried") {
-        tracer.traceEvent({
-            id: event.id,
-            sessionID: event.properties.sessionID,
-            name: "opencode.generation.retry",
-            timestamp: event.properties.timestamp,
-            output: event.properties.error,
-            metadata: { attempt: event.properties.attempt },
-        });
-    }
-    if (event.type === "session.next.reasoning.ended") {
-        tracer.traceReasoning({
-            reasoningID: event.properties.reasoningID,
-            sessionID: event.properties.sessionID,
-            timestamp: event.properties.timestamp,
-            text: event.properties.text,
-            messageID: event.properties.assistantMessageID,
-            source: "session.next.reasoning.ended",
-        });
+const SESSION_LOOKUP_TIMEOUT_MS = 1500;
+async function withTimeout(promise, ms) {
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(undefined), ms);
+            }),
+        ]);
     }
-    if (event.type === "session.next.compaction.ended") {
-        tracer.traceEvent({
-            id: event.id,
-            sessionID: event.properties.sessionID,
-            name: "opencode.generation.compaction",
-            timestamp: event.properties.timestamp,
-            output: { text: event.properties.text },
-            metadata: {
-                include: event.properties.include ?? null,
-            },
-        });
+    catch {
+        return undefined;
     }
-    if (event.type === "message.updated" && "properties" in event) {
-        const message = event.properties.info;
-        if (message.role !== "assistant" || !message.time.completed) {
-            return;
-        }
-        tracer.traceGeneration({
-            sessionID: message.sessionID,
-            messageID: message.id,
-            parentID: message.parentID,
-            modelID: message.modelID,
-            providerID: message.providerID,
-            agent: message.mode,
-            mode: message.mode,
-            created: message.time.created,
-            completed: message.time.completed,
-            finish: message.finish,
-            cost: message.cost,
-            tokens: message.tokens,
-        });
+    finally {
+        if (timer)
+            clearTimeout(timer);
     }
 }
+/**
+ * Build a lazy parent-session lookup from the OpenCode plugin client.
+ * Returns undefined when the client or its session API is unavailable.
+ */
+function createSessionLookup(client) {
+    const sessionApi = client?.session;
+    if (typeof sessionApi?.get !== "function")
+        return undefined;
+    const get = sessionApi.get;
+    return async (sessionID) => {
+        const response = await withTimeout(get.call(sessionApi, { path: { id: sessionID } }), SESSION_LOOKUP_TIMEOUT_MS);
+        if (!response || typeof response !== "object")
+            return undefined;
+        // hey-api clients wrap payloads in { data }; older shapes vary.
+        const record = response;
+        const data = (record.data ?? record);
+        const info = (data.info ?? data);
+        return typeof info.parentID === "string" ? info.parentID : undefined;
+    };
+}
+/** The first text part holds the raw prompt (OpenCode appends parts for @-mentions). */
+function firstTextPart(parts) {
+    const first = parts?.find((part) => part.type === "text");
+    return typeof first?.text === "string" ? first.text : undefined;
+}
 function safeRun(hookName, fn) {
     return Promise.resolve()
         .then(fn)
@@ -142,6 +91,159 @@ function safeRun(hookName, fn) {
 /** Build OpenCode hooks from an existing tracer (used by the plugin and tests). */
 export function createHooksFromTracer(tracer) {
     const shutdownOnce = createShutdownOnce(tracer);
+    // session.status {type:"idle"} and the deprecated session.idle fire
+    // back-to-back for the same transition — coalesce per session. The mark is
+    // reset on any new activity (busy status, a new user message, a new
+    // generation step) so a genuinely new idle is never swallowed.
+    const IDLE_COALESCE_MS = 2000;
+    const IDLE_MARK_CAP = 500;
+    const idleHandledAt = new BoundedMap(IDLE_MARK_CAP);
+    const handleSessionIdle = async (sessionID) => {
+        if (sessionID) {
+            const now = Date.now();
+            const last = idleHandledAt.get(sessionID);
+            if (last !== undefined && now - last < IDLE_COALESCE_MS)
+                return;
+            idleHandledAt.set(sessionID, now);
+        }
+        log("info", "Flushing spans");
+        // Scoped finalize: a sub-agent session going idle must not end the
+        // parent session's in-flight spans. Without a sessionID (old hosts),
+        // fall back to finalizing everything.
+        tracer.finalizeSessionTracing(sessionID);
+        await tracer.forceFlush();
+    };
+    const handleEvent = async (event) => {
+        if (event.type === "session.idle") {
+            const props = ("properties" in event
+                ? event.properties
+                : undefined);
+            await handleSessionIdle(props?.sessionID);
+        }
+        if (event.type === "session.status" && "properties" in event) {
+            const props = event.properties;
+            if (props?.status?.type === "idle") {
+                await handleSessionIdle(props.sessionID);
+            }
+            else if (props?.sessionID && props.status?.type) {
+                // New activity: the next idle is a fresh transition, not a duplicate.
+                idleHandledAt.delete(props.sessionID);
+            }
+        }
+        if ((event.type === "session.created" || event.type === "session.updated") &&
+            "properties" in event) {
+            const info = event.properties
+                ?.info;
+            // Session genealogy: task-tool child sessions carry parentID here.
+            if (info?.id)
+                tracer.registerSessionInfo(info.id, info.parentID);
+        }
+        if (event.type === "session.deleted" && "properties" in event) {
+            const info = event.properties
+                ?.info;
+            if (info?.id) {
+                // End the deleted session's in-flight spans before dropping its
+                // relationship data, so nothing leaks open until dispose.
+                tracer.finalizeSessionTracing(info.id);
+                tracer.evictSession(info.id);
+                idleHandledAt.delete(info.id);
+            }
+        }
+        if (event.type === "server.instance.disposed") {
+            tracer.finalizeSessionTracing();
+            await shutdownOnce();
+        }
+        if (event.type === "session.error" && "properties" in event) {
+            const props = event.properties;
+            if (props?.sessionID) {
+                tracer.traceSessionError({
+                    sessionID: props.sessionID,
+                    error: props.error,
+                });
+            }
+        }
+        if (event.type === "message.part.updated" && "properties" in event) {
+            const part = event.properties.part;
+            tracer.rememberAssistantPart(part);
+            tracer.traceReasoningPart(part);
+            tracer.traceToolPart(part);
+        }
+        if (event.type === "session.next.step.started") {
+            // Activity without a chat.message (queued work, sub-agent turns): the
+            // next idle is a fresh transition, not a duplicate of the last one.
+            // If a step.started were ever delivered *between* the paired idle
+            // events, this defeats their coalescing — costing one extra forceFlush,
+            // not a span, since the first finalize already cleared the turn.
+            idleHandledAt.delete(event.properties.sessionID);
+            tracer.startActiveGenerationStep({
+                sessionID: event.properties.sessionID,
+                agent: event.properties.agent,
+                model: event.properties.model,
+                started: event.properties.timestamp,
+                snapshot: event.properties.snapshot,
+            });
+        }
+        if (event.type === "session.next.step.failed") {
+            tracer.traceFailedGenerationStep({
+                id: event.id,
+                sessionID: event.properties.sessionID,
+                completed: event.properties.timestamp,
+                error: event.properties.error,
+            });
+        }
+        if (event.type === "session.next.retried") {
+            tracer.traceEvent({
+                id: event.id,
+                sessionID: event.properties.sessionID,
+                name: "opencode.generation.retry",
+                timestamp: event.properties.timestamp,
+                output: event.properties.error,
+                metadata: { attempt: event.properties.attempt },
+            });
+        }
+        if (event.type === "session.next.reasoning.ended") {
+            tracer.traceReasoning({
+                reasoningID: event.properties.reasoningID,
+                sessionID: event.properties.sessionID,
+                timestamp: event.properties.timestamp,
+                text: event.properties.text,
+                messageID: event.properties.assistantMessageID,
+                source: "session.next.reasoning.ended",
+            });
+        }
+        if (event.type === "session.next.compaction.ended") {
+            tracer.traceEvent({
+                id: event.id,
+                sessionID: event.properties.sessionID,
+                name: "opencode.generation.compaction",
+                timestamp: event.properties.timestamp,
+                output: { text: event.properties.text },
+                metadata: {
+                    include: event.properties.include ?? null,
+                },
+            });
+        }
+        if (event.type === "message.updated" && "properties" in event) {
+            const message = event.properties.info;
+            if (message.role !== "assistant" || !message.time.completed) {
+                return;
+            }
+            tracer.traceGeneration({
+                sessionID: message.sessionID,
+                messageID: message.id,
+                parentID: message.parentID,
+                modelID: message.modelID,
+                providerID: message.providerID,
+                agent: message.mode,
+                mode: message.mode,
+                created: message.time.created,
+                completed: message.time.completed,
+                finish: message.finish,
+                cost: message.cost,
+                tokens: message.tokens,
+            });
+        }
+    };
     return {
         dispose: () => safeRun("dispose", async () => {
             tracer.finalizeSessionTracing();
@@ -154,13 +256,13 @@ export function createHooksFromTracer(tracer) {
         }),
         event: ({ event }) => safeRun("event", async () => {
             try {
-                await handleEvent(tracer, event, shutdownOnce);
+                await handleEvent(event);
             }
             catch (error) {
                 // forceFlush often rejects with [Error] when thelake is slow;
                 // spans may already have been accepted via BatchSpanProcessor.
                 // Log and continue so session lifecycle is not blocked on OTLP.
-                if (event.type === "session.idle" &&
+                if ((event.type === "session.idle" || event.type === "session.status") &&
                     (Array.isArray(error) ||
                         (error instanceof Error && /timed out/i.test(error.message)))) {
                     log("warn", `flush after session.idle: ${formatHookError(error)}`);
@@ -169,13 +271,28 @@ export function createHooksFromTracer(tracer) {
                 throw error;
             }
         }),
-        "chat.message": (input, output) => safeRun("chat.message", () => {
+        "chat.message": (input, output) => safeRun("chat.message", async () => {
+            const parts = output.parts;
+            // A new turn is fresh activity — the next idle is not a duplicate.
+            idleHandledAt.delete(input.sessionID);
+            // Classify (root vs sub-agent child) before the turn span is created;
+            // spans cannot be re-parented afterwards. Classification is a pure
+            // enhancement: its failure must never cost the turn itself.
+            try {
+                await tracer.ensureSessionClassified(input.sessionID, {
+                    agent: input.agent,
+                    promptText: firstTextPart(parts),
+                });
+            }
+            catch (error) {
+                log("warn", `session classification failed: ${formatHookError(error)}`);
+            }
             tracer.traceUserMessage({
                 sessionID: input.sessionID,
                 messageID: input.messageID,
                 agent: input.agent,
                 model: input.model,
-                parts: output.parts,
+                parts,
             });
         }),
         "tool.execute.before": (input, output) => safeRun("tool.execute.before", () => {
@@ -187,18 +304,26 @@ export function createHooksFromTracer(tracer) {
             });
         }),
         "tool.execute.after": (input, output) => safeRun("tool.execute.after", () => {
+            // Registry tools pass `{ title, output }`. MCP tools currently fire
+            // this hook with raw CallToolResult (`{ content }`) *before*
+            // OpenCode normalizes/truncates — ending here would record
+            // `sp.output: "{}"` and block message.part.updated (canonical
+            // truncated `part.state.output`) via tracedToolCallIds. Defer when
+            // `output` is not a string so traceToolPart owns the end.
+            if (typeof output?.output !== "string")
+                return;
             tracer.traceToolEnd({
                 sessionID: input.sessionID,
                 callID: input.callID,
                 tool: input.tool,
                 args: input.args,
-                title: output.title,
+                title: output.title || input.tool,
                 output: output.output,
             });
         }),
     };
 }
-export const SoftprobePlugin = async () => {
+export const SoftprobePlugin = async (input) => {
     let tracer;
     try {
         const credentials = await loadSoftprobeCredentials();
@@ -209,6 +334,7 @@ export const SoftprobePlugin = async () => {
             environment: credentials.environment,
             userId: credentials.userId,
             serviceName: credentials.serviceName ?? "opencode",
+            sessionLookup: createSessionLookup(input?.client),
         });
         log("info", `OTLP tracing initialized → ${credentials.otlpEndpoint}`);
     }
@@ -231,5 +357,6 @@ export default {
     server: SoftprobePlugin,
 };
 export { SoftprobeSessionTracer, createSoftprobeSessionTracer, } from "./softprobe.js";
+export { SessionGraph, parseTaskCallArgs } from "./session-graph.js";
 export { loadSoftprobeCredentials, MissingSoftprobeCredentialsError, defaultConfigDir, defaultConfigPath, } from "./config.js";
 export { inferToolKind } from "./tool-kind.js";

package/dist/session-graph.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Session relationship data for OpenCode sub-agent nesting.
+ *
+ * Pure bookkeeping — no spans, no I/O, no timers. The tracer consults this
+ * graph to decide whether a session is a sub-agent child and, if so, which
+ * task tool call in the parent session dispatched it.
+ *
+ * Binding sources, in order of authority:
+ *  1. `bind(source: "metadata")` from the task tool part's
+ *     `state.metadata.sessionId`. OpenCode publishes this while the part is
+ *     still running, before the child session starts — exact and safe under
+ *     concurrent task calls.
+ *  2. Task args `task_id` (session resume) — the child session is named
+ *     explicitly, matched in {@link resolveTaskCall}.
+ *  3. Heuristic inference from parentID + task call candidates (unique
+ *     candidate → agent name → prompt text), for OpenCode versions that do
+ *     not publish part metadata. Never resolves on ambiguity: a wrong
+ *     nesting is silent data corruption, a missing one is only a missing
+ *     edge.
+ */
+export type TaskCallArgs = {
+    prompt?: string;
+    subagent_type?: string;
+    task_id?: string;
+};
+export type TaskBinding = {
+    childSessionID: string;
+    parentSessionID: string;
+    taskCallID: string;
+    /** "metadata" is authoritative and never overwritten by "inferred". */
+    source: "metadata" | "inferred";
+};
+/** Extract the task-tool args relevant for child-session binding. */
+export declare function parseTaskCallArgs(args: unknown): TaskCallArgs;
+export declare class SessionGraph {
+    /** child sessionID → parent sessionID (from session events or API lookup). */
+    private readonly parents;
+    /** Sessions known to have no parent. */
+    private readonly roots;
+    /** child sessionID → dispatching task call. */
+    private readonly bindings;
+    /** task callID → child sessionID (reverse of bindings). */
+    private readonly childByTaskCall;
+    /** task callID → call record (args for inference, times for recency). */
+    private readonly taskCalls;
+    registerParent(childSessionID: string, parentSessionID: string): void;
+    markRoot(sessionID: string): void;
+    isRoot(sessionID: string): boolean;
+    parentOf(sessionID: string): string | undefined;
+    registerTaskCall(callID: string, sessionID: string, args: TaskCallArgs): void;
+    endTaskCall(callID: string): void;
+    bind(binding: TaskBinding): void;
+    bindingFor(childSessionID: string): TaskBinding | undefined;
+    childForTaskCall(callID: string): string | undefined;
+    /**
+     * Infer which task call in `parentSessionID` dispatched `childSessionID`.
+     * Returns undefined on any ambiguity — never guesses.
+     */
+    resolveTaskCall(childSessionID: string, parentSessionID: string, hints?: {
+        agent?: string;
+        prompt?: string;
+    }): string | undefined;
+    /**
+     * Drop relationship data owned by a deleted session: its own parent link,
+     * root mark, task calls, and bindings dispatched by it (its children lose
+     * their dispatcher).
+     */
+    evictSession(sessionID: string): void;
+    private dropBinding;
+    private isCandidate;
+    private pruneTaskCalls;
+}