@cognipeer/agent-sdk 0.16.0 → 0.17.0

package/dist/index.cjs

@@ -2213,7 +2213,7 @@ function recordTraceEvent(session, event) {
   const baseLabel = event.label?.trim().length ? event.label.trim() : defaultEventLabel(event.type);
   const eventLabel = `${baseLabel} #${sequence}`;
   const durationMs = event.durationMs !== void 0 ? Number(event.durationMs) : void 0;
-  if (!Number.isNaN(durationMs ?? NaN) && durationMs !== void 0) {
+  if (!Number.isNaN(durationMs ?? NaN) && durationMs !== void 0 && event.countDuration !== false && !isSubagentTraceScope(session)) {
     session.summary.totalDurationMs += durationMs;
   }
   const inputTokens = event.inputTokens !== void 0 ? Number(event.inputTokens) : void 0;
@@ -2262,10 +2262,13 @@ function recordTraceEvent(session, event) {
       }
     }
   }
+  if (event.alwaysSections?.length) {
+    sections = ensureUniqueSections(id, [...event.alwaysSections, ...sections ?? []]);
+  }
   const resolvedModel = event.model ?? inferModelFromMessages(event.messageList);
   const resolvedProvider = event.provider ?? inferProviderFromMessages(event.messageList);
   const isAiCall = event.type === "ai_call";
-  const spanId = generateSpanId();
+  const spanId = event.spanId || generateSpanId();
   const parentSpanId = event.parentSpanId || session.currentIterationSpanId || session.rootSpanId;
   const record = {
     sessionId: session.sessionId,
@@ -2359,6 +2362,58 @@ var DEFERRED_TRACE_EVENTS_KEY = "__deferredTraceEvents";
 function isTraceSessionOpen(session) {
   return Boolean(session) && !session.closed;
 }
+var SUBAGENT_TRACE_SCOPE = Symbol("subagentTraceScope");
+function createSubagentTraceScope(parent, info) {
+  const scope = { ...info, iterations: info.iterations ?? 0 };
+  let currentIterationSpanId;
+  return new Proxy(parent, {
+    get(target, prop) {
+      if (prop === SUBAGENT_TRACE_SCOPE) return scope;
+      if (prop === "rootSpanId") return scope.agentSpanId;
+      if (prop === "currentIterationSpanId") return currentIterationSpanId;
+      return Reflect.get(target, prop);
+    },
+    set(target, prop, value) {
+      if (prop === "currentIterationSpanId") {
+        currentIterationSpanId = value;
+        return true;
+      }
+      return Reflect.set(target, prop, value);
+    }
+  });
+}
+function subagentTraceScopeOf(session) {
+  if (!session) return void 0;
+  return session[SUBAGENT_TRACE_SCOPE];
+}
+function canPauseForHuman(session) {
+  return subagentTraceScopeOf(session)?.hitl !== false;
+}
+function isSubagentTraceScope(session) {
+  return subagentTraceScopeOf(session) !== void 0;
+}
+function recordSubagentSpan(session, span) {
+  const sections = [];
+  if (session.resolvedConfig.logData) {
+    if (span.task !== void 0) sections.push({ kind: "message", label: "Task", role: "user", content: span.task });
+    if (span.result) sections.push({ kind: "message", label: "Result", role: "assistant", content: span.result });
+  }
+  recordTraceEvent(session, {
+    type: "span",
+    spanId: span.spanId,
+    parentSpanId: span.parentSpanId,
+    label: `Sub-agent ${span.name}`,
+    actor: { scope: "agent", name: span.name, role: "subagent" },
+    status: span.status,
+    durationMs: span.durationMs,
+    // The child's own calls and the delegating tool_call already hold this time.
+    countDuration: false,
+    ...span.error ? { error: { message: span.error } } : {},
+    // The Console reads which sub-agent ran from here, so it survives logData off.
+    alwaysSections: [{ kind: "metadata", label: "Sub-agent", data: sanitizeTracePayload(span.info) }],
+    sections
+  });
+}
 function recordOrDeferTraceEvent(ctx, event, options) {
   const session = ctx?.__traceSession;
   if (isTraceSessionOpen(session)) {
@@ -4936,6 +4991,9 @@ ${append}`;
 
 // src/utils/traceDecisions.ts
 var TRACED_KEY = "__outcomeTraced";
+function surfacedFromSubagent(entry) {
+  return Boolean(entry.metadata?.__subagent);
+}
 function waitedMs(from, to) {
   if (!from || !to) return void 0;
   const ms = Date.parse(to) - Date.parse(from);
@@ -4949,7 +5007,7 @@ function sameJson(a, b) {
   }
 }
 function recordApprovalRequested(session, entry) {
-  if (!session) return;
+  if (!session || surfacedFromSubagent(entry) || !canPauseForHuman(session)) return;
   const logData = session.resolvedConfig.logData;
   const sections = [
     {
@@ -4980,7 +5038,7 @@ function recordHumanDecisions(session, state) {
   if (!session) return;
   const logData = session.resolvedConfig.logData;
   for (const entry of state.pendingApprovals ?? []) {
-    if (!entry.decidedAt || entry.metadata?.[TRACED_KEY]) continue;
+    if (!entry.decidedAt || entry.metadata?.[TRACED_KEY] || surfacedFromSubagent(entry)) continue;
     if (entry.status !== "approved" && entry.status !== "rejected") continue;
     const approved = entry.status === "approved";
     const edited = approved && entry.approvedArgs !== void 0 && !sameJson(entry.approvedArgs, entry.args);
@@ -5019,7 +5077,7 @@ function recordHumanDecisions(session, state) {
     entry.metadata = { ...entry.metadata || {}, [TRACED_KEY]: true };
   }
   for (const entry of state.pendingUserQuestions ?? []) {
-    if (!entry.answeredAt || entry.metadata?.[TRACED_KEY]) continue;
+    if (!entry.answeredAt || entry.metadata?.[TRACED_KEY] || surfacedFromSubagent(entry)) continue;
     if (entry.status !== "answered" && entry.status !== "cancelled") continue;
     const clientTool = readClientTool(entry);
     if (clientTool) {
@@ -5065,7 +5123,7 @@ function recordHumanDecisions(session, state) {
   }
 }
 function recordClientToolRequested(session, entry) {
-  if (!session) return;
+  if (!session || surfacedFromSubagent(entry) || !canPauseForHuman(session)) return;
   const clientTool = readClientTool(entry);
   if (!clientTool) return;
   const sections = [
@@ -5721,6 +5779,7 @@ function createToolsNode(initialTools, opts) {
         toolCount += 1;
         return { status: "error" };
       }
+      let traceSpanId;
       try {
         if (cachedHit !== void 0) {
           const executionId2 = nanoid.nanoid();
@@ -5800,7 +5859,8 @@ function createToolsNode(initialTools, opts) {
         onEvent?.({ type: "tool_call", phase: "start", name: toolName, id: tc.id, args });
         onProgress?.({ stage: "tools", message: `Running tool ${tc.name}` });
         const anyTool = tool;
-        const callOptions = { cancellationToken, signal: abortSignal, toolCallId };
+        traceSpanId = traceSession ? generateSpanId() : void 0;
+        const callOptions = { cancellationToken, signal: abortSignal, toolCallId, ...traceSpanId ? { traceSpanId } : {} };
         const invokeOnce = async () => {
           if (typeof anyTool.func === "function") return anyTool.func(args, callOptions);
           if (typeof anyTool.invoke === "function") return anyTool.invoke(args, callOptions);
@@ -5983,6 +6043,7 @@ function createToolsNode(initialTools, opts) {
         const outputBytes = traceSession?.resolvedConfig.logData ? estimatePayloadBytes(sanitizedOutput) : void 0;
         recordTraceEvent(traceSession, {
           type: "tool_call",
+          spanId: traceSpanId,
           label: `Tool Execution - ${toolName}`,
           actor: { scope: "tool", name: toolName, role: "tool" },
           ...reportedFailure ? { status: "error", error: { message: reportedFailure } } : {},
@@ -6045,6 +6106,7 @@ function createToolsNode(initialTools, opts) {
         const errorOutput = { message, stack: host?.has("postToolUse") ? void 0 : error?.stack };
         recordTraceEvent(traceSession, {
           type: "tool_call",
+          spanId: traceSpanId,
           label: `Tool Error - ${toolName}`,
           actor: { scope: "tool", name: toolName, role: "tool" },
           status: "error",
@@ -7005,7 +7067,7 @@ function createAskUserQuestionTool(stateRef, config) {
         questions: entry.questions,
         allowFreeText
       });
-      recordTraceEvent(ctx.__traceSession, {
+      if (canPauseForHuman(ctx.__traceSession)) recordTraceEvent(ctx.__traceSession, {
         type: "user_question",
         label: "Question to user",
         timestamp: entry.requestedAt,
@@ -8288,19 +8350,22 @@ function createAgent(opts) {
             detail: { reason: budget.reason, iteration: iterations }
           });
         }
+        recordHumanDecisions(state.ctx?.__traceSession, state);
         const ctx = { ...state.ctx || {}, __limitBreached: budget.reason };
         state = { ...state, ctx };
         break;
       }
       const traceSession = state.ctx?.__traceSession;
       if (traceSession) {
-        const iterationNumber = (traceSession.summary.eventCounts.agent_iteration ?? 0) + 1;
+        const subagentScope = subagentTraceScopeOf(traceSession);
+        const iterationNumber = subagentScope ? ++subagentScope.iterations : (traceSession.summary.eventCounts.agent_iteration ?? 0) - (traceSession.summary.subagentIterations ?? 0) + 1;
         const iterEvent = recordTraceEvent(traceSession, {
           type: "agent_iteration",
           label: `Iteration ${iterationNumber}`,
           actor: { scope: "agent", name: opts.name || "agent", role: "orchestrator" },
           parentSpanId: traceSession.rootSpanId
         });
+        if (subagentScope) traceSession.summary.subagentIterations = (traceSession.summary.subagentIterations ?? 0) + 1;
         if (iterEvent) {
           traceSession.currentIterationSpanId = iterEvent.spanId;
         }
@@ -8610,7 +8675,9 @@ function createAgent(opts) {
     const inheritedSession = config?.__pluginSession;
     ctx.__runId = inheritedSession?.runId ?? traceSession?.sessionId ?? `run_${nanoid.nanoid(10)}`;
     const stateHolder = inheritedSession?.stateHolder ?? { value: void 0 };
-    const traceRecorder = createPluginTraceRecorder(() => traceSession);
+    const traceRecorder = createPluginTraceRecorder(
+      () => traceSession ?? (subagentTraceScopeOf(ctx.__traceSession) ? ctx.__traceSession : void 0)
+    );
     const runHost = inheritedSession?.host ?? (pluginHost.hasAny() ? pluginHost.beginRun({
       runId: ctx.__runId,
       agentName: opts.name,
@@ -8853,7 +8920,7 @@ function createAgent(opts) {
         name: toolName,
         description: description || `Delegate task to agent ${opts.name || "Agent"}`,
         schema,
-        func: async ({ input }) => {
+        func: async ({ input }, context) => {
           const ref = delegatedTool._stateRef;
           const parentCtx = ref.ctx || {};
           const parentMessages = Array.isArray(ref.messages) ? ref.messages : [];
@@ -8886,6 +8953,33 @@ function createAgent(opts) {
             input
           );
           const childCtx = { __delegationDepth: currentDepth + 1 };
+          const parentSession = parentCtx.__traceSession;
+          const traced = isTraceSessionOpen(parentSession);
+          const agentSpanId = generateSpanId();
+          const parentIterationSpanId = traced ? parentSession.currentIterationSpanId : void 0;
+          if (traced && !withDefaults(opts.tracing).enabled) {
+            childCtx.__traceSession = createSubagentTraceScope(parentSession, {
+              agentSpanId,
+              name: opts.name || "agent",
+              mode: "asTool",
+              hitl: false
+            });
+          }
+          const startedAt = Date.now();
+          const recordSpan = (status, extra) => {
+            if (!traced || !isTraceSessionOpen(parentSession)) return;
+            recordSubagentSpan(parentSession, {
+              spanId: agentSpanId,
+              parentSpanId: context?.traceSpanId ?? parentIterationSpanId,
+              name: opts.name || "agent",
+              status,
+              durationMs: Date.now() - startedAt,
+              error: extra.error,
+              info: { name: opts.name || "agent", mode: "asTool", depth: currentDepth + 1, parentToolCallId: context?.toolCallId, status: status === "success" ? "ok" : "error" },
+              task: input,
+              result: extra.result
+            });
+          };
           const childConfig = {
             onEvent: parentCtx.__onEvent ? (e) => {
               if (e?.type === "finalAnswer" || e?.type === "metadata") return;
@@ -8901,7 +8995,14 @@ function createAgent(opts) {
             stream: Boolean(parentCtx.__streaming),
             cancellationToken: parentCtx.__cancellationToken ?? parentCtx.__abortSignal
           };
-          const res = await instance.invoke({ messages: childMessages, ctx: childCtx }, childConfig);
+          let res;
+          try {
+            res = await instance.invoke({ messages: childMessages, ctx: childCtx }, childConfig);
+          } catch (err) {
+            recordSpan("error", { error: err?.message || String(err) });
+            throw err;
+          }
+          recordSpan("success", { result: res.content });
           return {
             content: res.content,
             output: res.output,
@@ -11064,11 +11165,42 @@ function mergeChildUsage(ref, childState, baseline, tag) {
 async function runChild(spec, input, deps, ref, opts) {
   const parentCtx = ref.ctx || {};
   const parentOnEvent = parentCtx.__onEvent;
-  const spawnId = `sa_${nanoid.nanoid(6)}`;
+  const spawnId = opts.record?.spawnId ?? `sa_${nanoid.nanoid(6)}`;
   const start = Date.now();
   const usageTag = { name: spec.name, id: spawnId, mode: spec.mode };
   const parentHost = parentCtx.__plugins;
   const childDepth = (Number(parentCtx.__delegationDepth) || 0) + 1;
+  const parentSession = parentCtx.__traceSession;
+  const traced = isTraceSessionOpen(parentSession);
+  const agentSpanId = generateSpanId();
+  const parentIterationSpanId = traced ? parentSession.currentIterationSpanId : void 0;
+  const traceScope = traced ? createSubagentTraceScope(parentSession, { agentSpanId, name: spec.name, spawnId, mode: spec.mode, hitl: opts.allowHITL, iterations: opts.record?.iterations }) : void 0;
+  const recordSegment = (status, info) => {
+    if (!traced || !isTraceSessionOpen(parentSession)) return;
+    recordSubagentSpan(parentSession, {
+      spanId: agentSpanId,
+      // The tool_call span only exists once the tool returns; a paused child
+      // has not returned, so its span hangs off the iteration.
+      parentSpanId: status === "pending" ? parentIterationSpanId : opts.parentSpanId ?? parentIterationSpanId,
+      name: spec.name,
+      status,
+      durationMs: Date.now() - start,
+      error: info.error,
+      info: {
+        id: spawnId,
+        name: spec.name,
+        mode: spec.mode,
+        parallel: opts.parallel,
+        depth: childDepth,
+        parentToolCallId: opts.parentToolCallId,
+        status: info.subagentStatus,
+        ...info.note ? { note: info.note } : {},
+        ...spec.metadata ? { metadata: spec.metadata } : {}
+      },
+      task: info.input,
+      result: info.content
+    });
+  };
   const emitStart = (task) => {
     parentOnEvent?.({ type: "subagent", phase: "start", name: spec.name, id: spawnId, mode: spec.mode, parallel: opts.parallel, parentToolCallId: opts.parentToolCallId, input: task });
   };
@@ -11076,6 +11208,15 @@ async function runChild(spec, input, deps, ref, opts) {
     result2.durationMs ?? (result2.durationMs = Date.now() - start);
     deps.registryRef.results.push(result2);
     const message = result2.error || result2.note || result2.status;
+    const traceStatus = result2.status === "ok" || result2.status === "incomplete" ? "success" : result2.status === "blocked" ? "skipped" : "error";
+    recordSegment(traceStatus, {
+      subagentStatus: result2.status,
+      input,
+      // `message` falls back to the status itself ("ok"): only a failed or refused run has an error to show.
+      error: traceStatus === "success" ? void 0 : message,
+      note: result2.note,
+      content: result2.content
+    });
     parentOnEvent?.({
       type: "subagent",
       phase: FAILED_STATUSES.has(result2.status) ? "error" : "result",
@@ -11174,6 +11315,7 @@ async function runChild(spec, input, deps, ref, opts) {
       ctx: { __delegationDepth: currentDepth + 1 }
     };
   }
+  if (traceScope) childInput = { ...childInput, ctx: { ...childInput.ctx || {}, __traceSession: traceScope } };
   const usageBaseline = childInput.usage?.perRequest?.length ?? 0;
   let res;
   try {
@@ -11214,8 +11356,11 @@ async function runChild(spec, input, deps, ref, opts) {
           input,
           childState: cleanChildState(childState),
           pendingKind: "approval",
-          pendingId: childEntry.id
+          pendingId: childEntry.id,
+          spawnId,
+          iterations: traceScope ? subagentTraceScopeOf(traceScope)?.iterations : void 0
         };
+        recordSegment("pending", { subagentStatus: "paused", input });
         parentOnEvent?.({ type: "subagent", phase: "paused", name: spec.name, id: spawnId, mode: spec.mode, parentToolCallId: opts.parentToolCallId });
         return { kind: "approval", toolCallId: surfaced.toolCallId, approvalId: surfaced.id };
       }
@@ -11237,8 +11382,11 @@ async function runChild(spec, input, deps, ref, opts) {
           input,
           childState: cleanChildState(childState),
           pendingKind: "user_question",
-          pendingId: childEntry.id
+          pendingId: childEntry.id,
+          spawnId,
+          iterations: traceScope ? subagentTraceScopeOf(traceScope)?.iterations : void 0
         };
+        recordSegment("pending", { subagentStatus: "paused", input });
         parentOnEvent?.({ type: "subagent", phase: "paused", name: spec.name, id: spawnId, mode: spec.mode, parentToolCallId: opts.parentToolCallId });
         return { kind: "user_question", toolCallId: surfaced.toolCallId, id: surfaced.id };
       }
@@ -11342,7 +11490,7 @@ function createDelegateTool(deps) {
         if (!budget.ok) return refusal(budget.reason);
         d.registryRef.spawnedCount += 1;
       }
-      return toToolReturn(await runChild(spec, record?.input ?? input, d, ref, { allowHITL: true, parentToolCallId, isResume: !!record, record, reserved: !record }));
+      return toToolReturn(await runChild(spec, record?.input ?? input, d, ref, { allowHITL: true, parentToolCallId, isResume: !!record, record, reserved: !record, parentSpanId: context?.traceSpanId }));
     }
   });
   tool._deps = deps;
@@ -11387,7 +11535,7 @@ function createSpawnTool(deps) {
         if (!budget.ok) return refusal(budget.reason);
         d.registryRef.spawnedCount += 1;
       }
-      return toToolReturn(await runChild(spec, record?.input ?? args.input, d, ref, { allowHITL: true, parentToolCallId, isResume: !!record, record, reserved: !record }));
+      return toToolReturn(await runChild(spec, record?.input ?? args.input, d, ref, { allowHITL: true, parentToolCallId, isResume: !!record, record, reserved: !record, parentSpanId: context?.traceSpanId }));
     }
   });
   tool._deps = deps;
@@ -11470,7 +11618,8 @@ function createParallelTool(deps) {
             allowHITL: false,
             parentToolCallId: `${parentToolCallId}#${i}`,
             parallel: true,
-            reserved: true
+            reserved: true,
+            parentSpanId: context?.traceSpanId
           });
           results[i] = outcome.kind === "result" ? outcome.result : { name: entry.spec.name, mode: entry.spec.mode, status: "error", input: entry.input, error: "Unexpected pause in parallel child." };
         }
@@ -15765,6 +15914,7 @@ function otelTracing(config) {
       sessionEnd: async ({ status, durationMs, error }, ctx) => {
         const state = ctx.state;
         const session = state.ctx?.__traceSession;
+        if (isSubagentTraceScope(session)) return;
         if (!session) {
           const message = "otelTracing exported nothing: the agent has no trace session. Enable the SDK's tracing runtime with `tracing: { enabled: true }` \u2014 the plugin exports the session the runtime records, it does not record one itself.";
           ctx.logger.warn(message);