@cognipeer/agent-sdk 0.13.0 → 0.14.0

package/dist/index.cjs

@@ -2026,27 +2026,71 @@ function convertMessageListToSections(messageList) {
   }
   return sections.length > 0 ? sections : void 0;
 }
-function createTraceSession(opts) {
+function readTraceContinuation(value) {
+  if (!value || typeof value !== "object") return void 0;
+  const raw = value;
+  if (raw.v !== 1 || typeof raw.sessionId !== "string" || raw.sessionId.length === 0) return void 0;
+  const nextSequence = Number(raw.nextSequence);
+  const startedAt = Number(raw.startedAt);
+  const part = Number(raw.part);
+  if (!Number.isInteger(nextSequence) || nextSequence < 1) return void 0;
+  if (!Number.isFinite(startedAt) || !Number.isInteger(part) || part < 1) return void 0;
+  const summary = raw.summary && typeof raw.summary === "object" ? { ...createEmptySummary(), ...raw.summary } : createEmptySummary();
+  summary.eventCounts = { ...raw.summary?.eventCounts ?? {} };
+  return {
+    v: 1,
+    sessionId: raw.sessionId,
+    traceId: typeof raw.traceId === "string" ? raw.traceId : void 0,
+    rootSpanId: typeof raw.rootSpanId === "string" ? raw.rootSpanId : void 0,
+    threadId: typeof raw.threadId === "string" ? raw.threadId : void 0,
+    startedAt,
+    nextSequence,
+    part,
+    summary,
+    errors: Array.isArray(raw.errors) ? raw.errors : []
+  };
+}
+function traceContinuationOf(session) {
+  return {
+    v: 1,
+    sessionId: session.sessionId,
+    traceId: session.traceId,
+    rootSpanId: session.rootSpanId,
+    threadId: session.threadId,
+    startedAt: session.startedAt,
+    nextSequence: (session.sequenceOffset ?? 0) + session.events.length + 1,
+    part: session.part ?? 1,
+    summary: JSON.parse(JSON.stringify(session.summary)),
+    // Sink failures belong to the part that hit them; carrying them on would
+    // mark every later part `partial`.
+    errors: session.errors.filter((error) => error.type !== "sink")
+  };
+}
+function createTraceSession(opts, continuation) {
   const cfg = withDefaults(opts.tracing);
   if (!cfg.enabled) return void 0;
   const providedSessionId = opts.tracing?.sessionId?.trim();
-  const sessionId = providedSessionId || generateSessionId();
-  const traceId = generateTraceId();
-  const rootSpanId = generateSpanId();
+  const sessionId = continuation?.sessionId || providedSessionId || generateSessionId();
+  const traceId = continuation?.traceId || generateTraceId();
+  const rootSpanId = continuation?.rootSpanId || generateSpanId();
   const runtime = {
     sessionId,
     traceId,
     rootSpanId,
-    threadId: opts.tracing?.threadId,
+    threadId: continuation?.threadId ?? opts.tracing?.threadId,
     configAgentName: opts.tracing?.agentName?.trim() || void 0,
     configMetadata: opts.tracing?.metadata && Object.keys(opts.tracing.metadata).length > 0 ? opts.tracing.metadata : void 0,
-    startedAt: Date.now(),
+    startedAt: continuation?.startedAt ?? Date.now(),
     resolvedConfig: cfg,
     events: [],
-    summary: createEmptySummary(),
+    summary: continuation ? continuation.summary : createEmptySummary(),
     status: "in_progress",
-    errors: [],
-    sessionStarted: false
+    errors: continuation ? [...continuation.errors] : [],
+    // A continued session was announced by its first part; announcing it
+    // again would reset a streaming receiver's copy.
+    sessionStarted: Boolean(continuation),
+    sequenceOffset: continuation ? continuation.nextSequence - 1 : 0,
+    part: continuation ? continuation.part + 1 : 1
   };
   if (cfg.sink.type === "file") {
     const baseDir = cfg.sink.baseDir;
@@ -2106,7 +2150,7 @@ async function startStreamingSession(session, agentRuntime) {
 }
 function recordTraceEvent(session, event) {
   if (!session) return void 0;
-  const sequence = session.events.length + 1;
+  const sequence = (session.sequenceOffset ?? 0) + session.events.length + 1;
   const id = generateEventId(sequence);
   const timestampIso = event.timestamp || (/* @__PURE__ */ new Date()).toISOString();
   const status = event.status ?? "success";
@@ -2296,7 +2340,8 @@ async function finalizeTraceSession(session, params = {}) {
     summary: session.summary,
     events: session.events,
     status: status2,
-    errors: session.errors
+    errors: session.errors,
+    ...(session.part ?? 1) > 1 ? { continuation: { part: session.part, firstSequence: (session.sequenceOffset ?? 0) + 1 } } : {}
   });
   const payloadForSink = buildPayload(initialStatus);
   let sinkFailed = false;
@@ -2353,7 +2398,17 @@ async function finalizeTraceSession(session, params = {}) {
   if (sink.type === "file" && session.fileSessionDir) {
     try {
       const filePath = path__default.default.join(session.fileSessionDir, "trace.session.json");
-      await fs__default.default.promises.writeFile(filePath, JSON.stringify(finalPayload, null, 2), "utf8");
+      let filePayload = finalPayload;
+      if (finalPayload.continuation) {
+        try {
+          const previous = JSON.parse(await fs__default.default.promises.readFile(filePath, "utf8"));
+          const earlier = (previous.events ?? []).filter((event) => event.sequence < finalPayload.continuation.firstSequence);
+          filePayload = { ...finalPayload, events: [...earlier, ...finalPayload.events] };
+          delete filePayload.continuation;
+        } catch {
+        }
+      }
+      await fs__default.default.promises.writeFile(filePath, JSON.stringify(filePayload, null, 2), "utf8");
     } catch (err) {
       sinkFailed = true;
       const message = err instanceof Error ? err.message : String(err);
@@ -4792,6 +4847,207 @@ ${append}`;
   };
 }
 
+// src/utils/traceDecisions.ts
+var TRACED_KEY = "__outcomeTraced";
+function waitedMs(from, to) {
+  if (!from || !to) return void 0;
+  const ms = Date.parse(to) - Date.parse(from);
+  return Number.isFinite(ms) && ms >= 0 ? ms : void 0;
+}
+function sameJson(a, b) {
+  try {
+    return JSON.stringify(a) === JSON.stringify(b);
+  } catch {
+    return false;
+  }
+}
+function recordApprovalRequested(session, entry) {
+  if (!session) return;
+  const logData = session.resolvedConfig.logData;
+  const sections = [
+    {
+      kind: "metadata",
+      label: "Approval",
+      data: {
+        approvalId: entry.id,
+        toolCallId: entry.toolCallId,
+        status: "pending",
+        requestedAt: entry.requestedAt,
+        ...entry.metadata?.prompt !== void 0 ? { prompt: entry.metadata.prompt } : {}
+      }
+    }
+  ];
+  if (logData) {
+    sections.push({ kind: "tool_call", label: "Arguments to approve", tool: entry.toolName, arguments: sanitizeTracePayload(entry.args) });
+  }
+  recordTraceEvent(session, {
+    type: "tool_approval",
+    label: `Approval requested \xB7 ${entry.toolName}`,
+    timestamp: entry.requestedAt,
+    status: "pending",
+    actor: { scope: "agent", name: entry.toolName, role: "approval_request" },
+    sections
+  });
+}
+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.status !== "approved" && entry.status !== "rejected") continue;
+    const approved = entry.status === "approved";
+    const edited = approved && entry.approvedArgs !== void 0 && !sameJson(entry.approvedArgs, entry.args);
+    const sections = [
+      {
+        kind: "metadata",
+        label: "Decision",
+        data: {
+          approvalId: entry.id,
+          toolCallId: entry.toolCallId,
+          decision: entry.status,
+          ...entry.decidedBy ? { decidedBy: entry.decidedBy } : {},
+          ...entry.comment ? { comment: entry.comment } : {},
+          requestedAt: entry.requestedAt,
+          decidedAt: entry.decidedAt,
+          ...waitedMs(entry.requestedAt, entry.decidedAt) !== void 0 ? { waitedMs: waitedMs(entry.requestedAt, entry.decidedAt) } : {},
+          ...edited ? { argumentsEdited: true } : {}
+        }
+      }
+    ];
+    if (logData) {
+      sections.push({ kind: "tool_call", label: "Requested arguments", tool: entry.toolName, arguments: sanitizeTracePayload(entry.args) });
+      if (edited) {
+        sections.push({ kind: "tool_call", label: "Approved arguments", tool: entry.toolName, arguments: sanitizeTracePayload(entry.approvedArgs) });
+      }
+    }
+    recordTraceEvent(session, {
+      type: "tool_approval",
+      label: `${approved ? "Approved" : "Rejected"} \xB7 ${entry.toolName}`,
+      timestamp: entry.decidedAt,
+      durationMs: waitedMs(entry.requestedAt, entry.decidedAt),
+      status: "success",
+      actor: { scope: "human", name: entry.decidedBy || "reviewer", role: "approver" },
+      sections
+    });
+    entry.metadata = { ...entry.metadata || {}, [TRACED_KEY]: true };
+  }
+  for (const entry of state.pendingUserQuestions ?? []) {
+    if (!entry.answeredAt || entry.metadata?.[TRACED_KEY]) continue;
+    if (entry.status !== "answered" && entry.status !== "cancelled") continue;
+    const clientTool = readClientTool(entry);
+    if (clientTool) {
+      recordClientToolResult(session, entry, clientTool, state.toolHistory);
+      entry.metadata = { ...entry.metadata || {}, [TRACED_KEY]: true };
+      continue;
+    }
+    const cancelled = entry.status === "cancelled";
+    const data = {
+      questionId: entry.id,
+      toolCallId: entry.toolCallId,
+      status: entry.status,
+      ...entry.answeredBy ? { answeredBy: entry.answeredBy } : {},
+      ...entry.notes ? { notes: entry.notes } : {},
+      requestedAt: entry.requestedAt,
+      answeredAt: entry.answeredAt,
+      ...waitedMs(entry.requestedAt, entry.answeredAt) !== void 0 ? { waitedMs: waitedMs(entry.requestedAt, entry.answeredAt) } : {}
+    };
+    const sections = [{ kind: "metadata", label: "Answer", data }];
+    if (logData) {
+      sections.push({
+        kind: "metadata",
+        label: "Questions and answers",
+        data: {
+          items: (entry.questions ?? []).map((item) => ({
+            question: item.question,
+            ...item.header ? { header: item.header } : {},
+            answer: sanitizeTracePayload(entry.answers?.[item.question] ?? (item.header ? entry.answers?.[item.header] : void 0) ?? null)
+          }))
+        }
+      });
+    }
+    recordTraceEvent(session, {
+      type: "user_question",
+      label: cancelled ? "Question cancelled" : "Answer from user",
+      timestamp: entry.answeredAt,
+      durationMs: waitedMs(entry.requestedAt, entry.answeredAt),
+      status: cancelled ? "skipped" : "success",
+      actor: { scope: "human", name: entry.answeredBy || "user", role: "user" },
+      sections
+    });
+    entry.metadata = { ...entry.metadata || {}, [TRACED_KEY]: true };
+  }
+}
+function recordClientToolRequested(session, entry) {
+  if (!session) return;
+  const clientTool = readClientTool(entry);
+  if (!clientTool) return;
+  const sections = [
+    {
+      kind: "metadata",
+      label: "Client tool",
+      data: { questionId: entry.id, toolCallId: entry.toolCallId, status: "pending", requestedAt: entry.requestedAt }
+    }
+  ];
+  if (session.resolvedConfig.logData) {
+    sections.push({ kind: "tool_call", label: "Arguments", tool: clientTool.name, arguments: sanitizeTracePayload(clientTool.args) });
+  }
+  recordTraceEvent(session, {
+    type: "tool_call",
+    label: `Tool Execution - ${clientTool.name} (client)`,
+    timestamp: entry.requestedAt,
+    status: "pending",
+    actor: { scope: "client", name: clientTool.name, role: "tool" },
+    sections
+  });
+}
+function readClientTool(entry) {
+  const meta = entry.metadata?.clientTool;
+  if (!meta || typeof meta !== "object" || typeof meta.name !== "string") return void 0;
+  return { name: meta.name, args: meta.args };
+}
+function recordClientToolResult(session, entry, clientTool, toolHistory) {
+  const step = [...toolHistory ?? []].reverse().find((item) => item?.tool_call_id === entry.toolCallId);
+  const failed = step?.status === "error" || entry.status === "cancelled";
+  const sections = [
+    {
+      kind: "metadata",
+      label: "Client tool",
+      data: {
+        questionId: entry.id,
+        toolCallId: entry.toolCallId,
+        status: failed ? "error" : "answered",
+        ...entry.answeredBy ? { answeredBy: entry.answeredBy } : {},
+        requestedAt: entry.requestedAt,
+        answeredAt: entry.answeredAt,
+        ...waitedMs(entry.requestedAt, entry.answeredAt) !== void 0 ? { waitedMs: waitedMs(entry.requestedAt, entry.answeredAt) } : {}
+      }
+    }
+  ];
+  if (session.resolvedConfig.logData) {
+    sections.push({ kind: "tool_call", label: "Arguments", tool: clientTool.name, arguments: sanitizeTracePayload(clientTool.args) });
+    if (step) {
+      const output = step.rawOutput ?? step.output;
+      sections.push({
+        kind: "tool_result",
+        label: "Result from client",
+        tool: clientTool.name,
+        output: sanitizeTracePayload(output),
+        summary: typeof step.output === "string" ? step.output.slice(0, 2e3) : void 0
+      });
+    }
+  }
+  const ranMs = typeof step?.durationMs === "number" ? step.durationMs : void 0;
+  recordTraceEvent(session, {
+    type: "tool_call",
+    label: `Tool Execution - ${clientTool.name} (client)`,
+    timestamp: entry.answeredAt,
+    durationMs: waitedMs(entry.requestedAt, entry.answeredAt) ?? ranMs,
+    status: failed ? "error" : "success",
+    actor: { scope: "client", name: clientTool.name, role: "tool" },
+    sections
+  });
+}
+
 // src/utils/traceSections.ts
 init_content();
 function truncate(text, max = 500) {
@@ -5260,6 +5516,7 @@ function createToolsNode(initialTools, opts) {
           };
           pendingApprovals.push(approvalEntry);
           pendingByCallId.set(toolCallId, approvalEntry);
+          recordApprovalRequested(traceSession, approvalEntry);
           onEvent?.({ type: "tool_approval", status: "pending", id: approvalEntry.id, toolName: approvalEntry.toolName, toolCallId: approvalEntry.toolCallId, args });
           if (host?.has("notification")) {
             await host.runObservers("notification", {
@@ -5523,6 +5780,7 @@ function createToolsNode(initialTools, opts) {
           if (!pendingApproval) {
             throw new Error(`Tool ${toolName} requested approval but no pending approval entry was recorded.`);
           }
+          recordApprovalRequested(traceSession, pendingApproval);
           awaitingApproval = true;
           return {
             status: "awaiting_approval",
@@ -5539,6 +5797,7 @@ function createToolsNode(initialTools, opts) {
           if (!pendingQuestion) {
             throw new Error(`Tool ${toolName} requested a user question but no pending question entry was recorded.`);
           }
+          recordClientToolRequested(traceSession, pendingQuestion);
           awaitingUserQuestion = true;
           if (host?.has("notification")) {
             await host.runObservers("notification", {
@@ -6635,16 +6894,20 @@ function createAskUserQuestionTool(stateRef, config) {
       });
       recordTraceEvent(ctx.__traceSession, {
         type: "user_question",
-        label: "Ask User",
+        label: "Question to user",
+        timestamp: entry.requestedAt,
         actor: { scope: "agent", name: "ask_user_question", role: "user_interaction" },
-        status: "success",
+        status: "pending",
         sections: [
           {
             kind: "metadata",
             label: "Pending Question",
             data: {
               id: entry.id,
+              questionId: entry.id,
               toolCallId: entry.toolCallId,
+              status: "pending",
+              requestedAt: entry.requestedAt,
               questions: entry.questions,
               allowFreeText
             }
@@ -7863,15 +8126,17 @@ function createAgent(opts) {
       }
       const traceSession = state.ctx?.__traceSession;
       if (traceSession) {
+        const iterationNumber = (traceSession.summary.eventCounts.agent_iteration ?? 0) + 1;
         const iterEvent = recordTraceEvent(traceSession, {
           type: "agent_iteration",
-          label: `Iteration ${iterations}`,
+          label: `Iteration ${iterationNumber}`,
           actor: { scope: "agent", name: opts.name || "agent", role: "orchestrator" },
           parentSpanId: traceSession.rootSpanId
         });
         if (iterEvent) {
           traceSession.currentIterationSpanId = iterEvent.spanId;
         }
+        recordHumanDecisions(traceSession, state);
       }
       if (cancelIfRequested("loop")) break;
       const skippingAgent = resumeStage === "tools";
@@ -8152,7 +8417,7 @@ function createAgent(opts) {
       }
       emit({ type: "progress", ...progress });
     };
-    const traceSession = createTraceSession(opts);
+    const traceSession = createTraceSession(opts, readTraceContinuation(input.ctx?.__traceContinuation));
     const ctx = {
       ...input.ctx || {},
       __onEvent: onEvent,
@@ -8160,6 +8425,7 @@ function createAgent(opts) {
       __onStream: onStream,
       __streaming: streamEnabled
     };
+    delete ctx.__traceContinuation;
     if (traceSession) ctx.__traceSession = traceSession;
     delete ctx.__plugins;
     delete ctx.__applySystemPromptContribution;
@@ -8308,10 +8574,17 @@ function createAgent(opts) {
         }
       }
     }
+    const pausedForHuman = statusFor(res) === "paused";
+    const midTurn = pausedForHuman || Boolean(res.ctx?.__needsSummarization);
     await finalizeTraceSession(traceSession, {
       agentRuntime: res.agent || runtime,
-      status: "success"
+      status: pausedForHuman ? "paused" : midTurn ? "in_progress" : "success"
     });
+    if (traceSession && midTurn) {
+      res.ctx = { ...res.ctx || {}, __traceContinuation: traceContinuationOf(traceSession) };
+    } else if (res.ctx && "__traceContinuation" in res.ctx) {
+      delete res.ctx.__traceContinuation;
+    }
     const isTransientSummarizationExit = !!res.ctx?.__needsSummarization;
     const finalAssistantMsg = isTransientSummarizationExit ? void 0 : getLastAssistantMessage(res.messages);
     const finalIsSyntheticSummary = !isTransientSummarizationExit && finalAssistantMsg && isSyntheticSummaryMessage(finalAssistantMsg);
@@ -11215,6 +11488,14 @@ ${pluginAppend}`;
         } else if (lastResult.state) {
           lastResult = { ...lastResult, state: { ...lastResult.state, memoryFacts: state.memoryFacts, plan: state.plan, planVersion: state.planVersion, messages: rawMessages } };
         }
+        if (lastResult.state) {
+          const endCtx = lastResult.state.ctx;
+          if (endCtx?.__traceContinuation && !(endCtx.__awaitingApproval || endCtx.__awaitingUserQuestion || endCtx.__paused)) {
+            const strippedCtx = { ...endCtx };
+            delete strippedCtx.__traceContinuation;
+            lastResult = { ...lastResult, state: { ...lastResult.state, ctx: strippedCtx } };
+          }
+        }
         if (skillsEnabled && lastResult.state) {
           const persisted = skillStateFromRegistry(toolSet.skillRegistryRef);
           if (persisted) {
@@ -19539,6 +19820,7 @@ exports.prepareStrictToolMenu = prepareStrictToolMenu;
 exports.promptInjectionGuard = promptInjectionGuard;
 exports.rateLimit = rateLimit;
 exports.readMemoryFacts = readMemoryFacts;
+exports.readTraceContinuation = readTraceContinuation;
 exports.redactText = redactText;
 exports.regexGuardrail = regexGuardrail;
 exports.regexRule = regexRule;
@@ -19575,6 +19857,7 @@ exports.toStrictCompatible = toStrictCompatible;
 exports.toStrictToolSchema = toStrictToolSchema;
 exports.tokenize = tokenize;
 exports.toolPolicy = toolPolicy;
+exports.traceContinuationOf = traceContinuationOf;
 exports.traceSessionToOtlp = traceSessionToOtlp;
 exports.validateReasoningConfig = validateReasoningConfig;
 exports.validateToolArgs = validateToolArgs;