@softprobe/opencode-plugin 0.1.1 → 0.1.6

package/dist/session-graph.js

@@ -0,0 +1,204 @@
+/**
+ * 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.
+ */
+/** Window in which an ended task call stays a valid inference candidate. */
+const RECENTLY_ENDED_TASK_MS = 15 * 60 * 1000;
+/** Ended task calls are pruned after a day; active ones are never pruned. */
+const ENDED_TASK_CALL_TTL_MS = 24 * 60 * 60 * 1000;
+/** Safety cap on remembered task calls (active + recently ended). */
+const MAX_TASK_CALLS = 500;
+/** Extract the task-tool args relevant for child-session binding. */
+export function parseTaskCallArgs(args) {
+    if (!args || typeof args !== "object")
+        return {};
+    const record = args;
+    const out = {};
+    if (typeof record.prompt === "string")
+        out.prompt = record.prompt;
+    if (typeof record.subagent_type === "string") {
+        out.subagent_type = record.subagent_type;
+    }
+    if (typeof record.task_id === "string")
+        out.task_id = record.task_id;
+    return out;
+}
+export class SessionGraph {
+    /** child sessionID → parent sessionID (from session events or API lookup). */
+    parents = new Map();
+    /** Sessions known to have no parent. */
+    roots = new Set();
+    /** child sessionID → dispatching task call. */
+    bindings = new Map();
+    /** task callID → child sessionID (reverse of bindings). */
+    childByTaskCall = new Map();
+    /** task callID → call record (args for inference, times for recency). */
+    taskCalls = new Map();
+    registerParent(childSessionID, parentSessionID) {
+        if (childSessionID === parentSessionID)
+            return;
+        this.roots.delete(childSessionID);
+        this.parents.set(childSessionID, parentSessionID);
+    }
+    markRoot(sessionID) {
+        if (this.parents.has(sessionID) || this.bindings.has(sessionID))
+            return;
+        this.roots.add(sessionID);
+    }
+    isRoot(sessionID) {
+        return this.roots.has(sessionID);
+    }
+    parentOf(sessionID) {
+        return this.parents.get(sessionID);
+    }
+    registerTaskCall(callID, sessionID, args) {
+        const existing = this.taskCalls.get(callID);
+        if (existing) {
+            existing.args = { ...existing.args, ...parseTaskCallArgs(args) };
+            return;
+        }
+        this.taskCalls.set(callID, {
+            callID,
+            sessionID,
+            args: parseTaskCallArgs(args),
+            startedAt: Date.now(),
+        });
+        this.pruneTaskCalls();
+    }
+    endTaskCall(callID) {
+        const task = this.taskCalls.get(callID);
+        if (task && task.endedAt === undefined)
+            task.endedAt = Date.now();
+    }
+    bind(binding) {
+        if (binding.childSessionID === binding.parentSessionID)
+            return;
+        const existing = this.bindings.get(binding.childSessionID);
+        if (existing?.source === "metadata" && binding.source === "inferred") {
+            return;
+        }
+        if (existing && existing.taskCallID !== binding.taskCallID) {
+            this.childByTaskCall.delete(existing.taskCallID);
+        }
+        this.roots.delete(binding.childSessionID);
+        this.parents.set(binding.childSessionID, binding.parentSessionID);
+        this.bindings.set(binding.childSessionID, binding);
+        this.childByTaskCall.set(binding.taskCallID, binding.childSessionID);
+    }
+    bindingFor(childSessionID) {
+        return this.bindings.get(childSessionID);
+    }
+    childForTaskCall(callID) {
+        return this.childByTaskCall.get(callID);
+    }
+    /**
+     * Infer which task call in `parentSessionID` dispatched `childSessionID`.
+     * Returns undefined on any ambiguity — never guesses.
+     */
+    resolveTaskCall(childSessionID, parentSessionID, hints = {}) {
+        const now = Date.now();
+        const candidates = [...this.taskCalls.values()].filter((task) => task.sessionID === parentSessionID && this.isCandidate(task, now));
+        if (candidates.length === 0)
+            return undefined;
+        // task_id resume names the child session explicitly — unambiguous even
+        // with several candidates.
+        const resumed = candidates.filter((task) => task.args.task_id === childSessionID);
+        if (resumed.length > 0) {
+            return resumed.reduce((a, b) => (a.startedAt >= b.startedAt ? a : b))
+                .callID;
+        }
+        if (candidates.length === 1) {
+            const only = candidates[0];
+            // A lone candidate that contradicts the hints is not a match — the
+            // child was likely dispatched by a call we never saw.
+            if (hints.agent &&
+                only.args.subagent_type &&
+                only.args.subagent_type !== hints.agent) {
+                return undefined;
+            }
+            if (hints.prompt && only.args.prompt && only.args.prompt !== hints.prompt) {
+                return undefined;
+            }
+            return only.callID;
+        }
+        if (hints.agent) {
+            const byAgent = candidates.filter((task) => task.args.subagent_type === hints.agent);
+            if (byAgent.length === 1)
+                return byAgent[0].callID;
+        }
+        if (hints.prompt) {
+            const byPrompt = candidates.filter((task) => task.args.prompt === hints.prompt);
+            if (byPrompt.length === 1)
+                return byPrompt[0].callID;
+        }
+        return 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) {
+        this.parents.delete(sessionID);
+        this.roots.delete(sessionID);
+        this.dropBinding(sessionID);
+        // Children of the deleted session lose their dispatcher and parent link.
+        for (const [child, parent] of this.parents) {
+            if (parent === sessionID)
+                this.parents.delete(child);
+        }
+        for (const binding of [...this.bindings.values()]) {
+            if (binding.parentSessionID === sessionID) {
+                this.dropBinding(binding.childSessionID);
+            }
+        }
+        for (const [callID, task] of this.taskCalls) {
+            if (task.sessionID === sessionID)
+                this.taskCalls.delete(callID);
+        }
+    }
+    dropBinding(childSessionID) {
+        const binding = this.bindings.get(childSessionID);
+        if (!binding)
+            return;
+        this.bindings.delete(childSessionID);
+        this.childByTaskCall.delete(binding.taskCallID);
+    }
+    isCandidate(task, now) {
+        return (task.endedAt === undefined || now - task.endedAt <= RECENTLY_ENDED_TASK_MS);
+    }
+    pruneTaskCalls() {
+        const now = Date.now();
+        for (const [callID, task] of this.taskCalls) {
+            if (task.endedAt !== undefined && now - task.endedAt > ENDED_TASK_CALL_TTL_MS) {
+                this.taskCalls.delete(callID);
+            }
+        }
+        if (this.taskCalls.size <= MAX_TASK_CALLS)
+            return;
+        const ended = [...this.taskCalls.values()]
+            .filter((task) => task.endedAt !== undefined)
+            .sort((a, b) => a.endedAt - b.endedAt);
+        for (const task of ended) {
+            if (this.taskCalls.size <= MAX_TASK_CALLS)
+                break;
+            this.taskCalls.delete(task.callID);
+        }
+    }
+}

package/dist/softprobe.d.ts

@@ -1,6 +1,9 @@
 import { SoftprobeClient, type Generation, type JsonValue, type Observation, type SoftprobeClientOptions } from "@softprobe/tracing";
-import type { AssistantGenerationInput, MessagePart, SessionErrorInfo, UserMessageInput } from "./types.js";
-export type SoftprobeSessionTracerOptions = SoftprobeClientOptions;
+import type { AssistantGenerationInput, MessagePart, SessionErrorInfo, SessionLookup, UserMessageInput } from "./types.js";
+export type SoftprobeSessionTracerOptions = SoftprobeClientOptions & {
+    /** OpenCode client API lookup used to classify unknown sessions lazily. */
+    sessionLookup?: SessionLookup;
+};
 /**
  * Maps OpenCode session hooks to Softprobe Part A observations.
  * Construct with an injected SoftprobeClient (tests) or via {@link createSoftprobeSessionTracer}.
@@ -8,6 +11,18 @@ export type SoftprobeSessionTracerOptions = SoftprobeClientOptions;
 export declare class SoftprobeSessionTracer {
     readonly client: SoftprobeClient;
     private readonly userId?;
+    private readonly sessionLookup?;
+    /** Sub-agent session relationships (parent links + task-call bindings). */
+    private readonly sessionGraph;
+    /** In-flight classification promises, deduped per session. */
+    private readonly classifying;
+    /**
+     * Recently ended task spans, kept so late-starting child sessions can still
+     * be parented under them (OTEL allows ended spans as parents).
+     */
+    private readonly endedTaskSpans;
+    /** messageID → sessionID index enabling per-session state cleanup. */
+    private readonly messageSession;
     private readonly abortedSessions;
     private readonly tracedMessageIds;
     private readonly tracedGenerationIds;
@@ -24,12 +39,73 @@ export declare class SoftprobeSessionTracer {
     private readonly generationParents;
     constructor(client: SoftprobeClient, options?: {
         userId?: string;
+        sessionLookup?: SessionLookup;
     });
-    clearTraceState(): void;
+    /**
+     * Clear bookkeeping for ended spans. With a sessionID, only that session's
+     * state is cleared (a sub-agent session going idle must not disturb the
+     * parent session's in-flight spans).
+     *
+     * Only payload caches are cleared, in both the scoped and the global path.
+     * Dedup sets are never cleared here — they are capped instead (see
+     * {@link BoundedSet}) — so a late duplicate delivery can never recreate a
+     * span that was already force-ended, on scoped and legacy hosts alike.
+     */
+    clearTraceState(sessionID?: string): void;
     endActiveToolObservations(sessionID?: string, error?: SessionErrorInfo): void;
     endActiveGenerationSteps(sessionID?: string, error?: SessionErrorInfo): void;
-    endActiveTurnObservations(): void;
-    finalizeSessionTracing(): void;
+    endActiveTurnObservations(sessionID?: string): void;
+    /**
+     * End open observations and flush bookkeeping. With a sessionID, only that
+     * session is finalized; without one (dispose/shutdown, or hosts whose idle
+     * event carries no sessionID) everything is finalized.
+     */
+    finalizeSessionTracing(sessionID?: string): void;
+    /**
+     * Register session genealogy reported by OpenCode (`session.created` /
+     * `session.updated` carry `info.parentID` for task-tool child sessions).
+     */
+    registerSessionInfo(sessionID: string, parentID?: string | null): void;
+    /** Drop relationship data for a deleted session (`session.deleted`). */
+    evictSession(sessionID: string): void;
+    /**
+     * Ensure a session is classified (root vs sub-agent child) before its first
+     * spans are created. Resolves the parent from prior events or, failing
+     * that, the OpenCode client API, then tries to bind the session to the
+     * dispatching task call. Idempotent and deduplicated while in flight.
+     */
+    ensureSessionClassified(sessionID: string, hints?: {
+        agent?: string;
+        promptText?: string;
+    }): Promise<void>;
+    private classifySession;
+    /**
+     * Bind a child session to the task call that dispatched it, when the call
+     * can be identified unambiguously. Bindings from task-part metadata are
+     * authoritative and are never replaced by inference.
+     */
+    private tryBindTask;
+    /**
+     * Capture the authoritative child-session link published on the task tool
+     * part (`state.metadata.sessionId`, present while the part is running,
+     * before the child session starts).
+     */
+    private captureTaskBinding;
+    /** Move an ended task span into the archive used for late child attach. */
+    private archiveTaskSpan;
+    /**
+     * Locate the span of the task call that dispatched a child session.
+     *
+     * Direct lookup only. A previous version fell back to "the unique active
+     * task span in the parent session" when the bound call had no span, which
+     * could parent a child under an unrelated sibling task. Its justification —
+     * a path keying the task span by part.id while the binding carries a
+     * different callID — does not exist: `ToolPart.callID` is required in the
+     * SDK, and traceToolPart and captureTaskBinding derive the id from the same
+     * expression, so the two can never diverge. Callers fall back to the parent
+     * session's turn when this returns undefined.
+     */
+    private taskSpanFor;
     forceFlush(): Promise<void>;
     shutdown(): Promise<void>;
     private getTurn;
@@ -89,8 +165,10 @@ export declare class SoftprobeSessionTracer {
      */
     private toolParent;
     /**
-     * Capture tool observations from message.part.updated when tool.execute.*
-     * hooks are missed (or spans from those hooks were dropped on export).
+     * Capture tool observations from message.part.updated.
+     * Also the canonical end path for MCP tools: tool.execute.after often
+     * receives raw CallToolResult without `output`, so we leave the span
+     * open until this completed/error part update arrives.
      */
     traceToolPart(part: MessagePart): void;
     traceToolStart(input: {