@smithers-orchestrator/engine 0.20.0 → 0.20.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithers-orchestrator/engine",
-  "version": "0.20.0",
+  "version": "0.20.3",
   "description": "Concrete Smithers workflow execution engine",
   "type": "module",
   "sideEffects": false,
@@ -33,20 +33,20 @@
     "react": "^19.2.5",
     "react-dom": "^19.2.5",
     "zod": "^4.3.6",
-    "@smithers-orchestrator/agents": "0.20.0",
-    "@smithers-orchestrator/driver": "0.20.0",
-    "@smithers-orchestrator/components": "0.20.0",
-    "@smithers-orchestrator/db": "0.20.0",
-    "@smithers-orchestrator/graph": "0.20.0",
-    "@smithers-orchestrator/memory": "0.20.0",
-    "@smithers-orchestrator/errors": "0.20.0",
-    "@smithers-orchestrator/observability": "0.20.0",
-    "@smithers-orchestrator/react-reconciler": "0.20.0",
-    "@smithers-orchestrator/sandbox": "0.20.0",
-    "@smithers-orchestrator/scheduler": "0.20.0",
-    "@smithers-orchestrator/scorers": "0.20.0",
-    "@smithers-orchestrator/vcs": "0.20.0",
-    "@smithers-orchestrator/time-travel": "0.20.0"
+    "@smithers-orchestrator/agents": "0.20.3",
+    "@smithers-orchestrator/db": "0.20.3",
+    "@smithers-orchestrator/components": "0.20.3",
+    "@smithers-orchestrator/errors": "0.20.3",
+    "@smithers-orchestrator/graph": "0.20.3",
+    "@smithers-orchestrator/memory": "0.20.3",
+    "@smithers-orchestrator/react-reconciler": "0.20.3",
+    "@smithers-orchestrator/sandbox": "0.20.3",
+    "@smithers-orchestrator/scheduler": "0.20.3",
+    "@smithers-orchestrator/scorers": "0.20.3",
+    "@smithers-orchestrator/observability": "0.20.3",
+    "@smithers-orchestrator/time-travel": "0.20.3",
+    "@smithers-orchestrator/vcs": "0.20.3",
+    "@smithers-orchestrator/driver": "0.20.3"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/AgentTraceCollector.js

@@ -0,0 +1,716 @@
+import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { nowMs } from "@smithers-orchestrator/scheduler/nowMs";
+import { normalizeTokenUsage } from "@smithers-orchestrator/agents/BaseCliAgent";
+import { detectAgentFamily } from "@smithers-orchestrator/observability/detectAgentFamily";
+import { detectCaptureMode } from "@smithers-orchestrator/observability/detectCaptureMode";
+import { resolveAgentTraceCapabilities } from "@smithers-orchestrator/observability/resolveAgentTraceCapabilities";
+import { unsupportedKindsForCapabilities } from "@smithers-orchestrator/observability/unsupportedKindsForCapabilities";
+import { kindPhase } from "@smithers-orchestrator/observability/kindPhase";
+import { normalizeStructuredEvent } from "@smithers-orchestrator/observability/normalizeStructuredEvent";
+import { extractProviderSessionCorrelation } from "@smithers-orchestrator/observability/_traceEventNormalizers";
+import { redactValue } from "@smithers-orchestrator/observability/_traceRedaction";
+import { canonicalTraceEventToOtelLogRecord } from "@smithers-orchestrator/observability/canonicalTraceEventToOtelLogRecord";
+import { agentSessionEventToOtelLogRecord } from "@smithers-orchestrator/observability/agentSessionEventToOtelLogRecord";
+import { emitOtelLogRecord } from "@smithers-orchestrator/observability/emitOtelLogRecord";
+import { shouldExportTraceEventToOtel } from "@smithers-orchestrator/observability/_otelLogBuilders";
+import {
+    resolveClaudeSessionFile,
+    resolveCodexSessionFile,
+    resolvePiSessionFile,
+} from "@smithers-orchestrator/observability/_sessionFileResolvers";
+
+/**
+ * @typedef {import("@smithers-orchestrator/observability/SmithersEvent").SmithersEvent} SmithersEvent
+ * @typedef {import("@smithers-orchestrator/observability/agentTrace").AgentCaptureMode} AgentCaptureMode
+ * @typedef {import("@smithers-orchestrator/observability/agentTrace").AgentFamily} AgentFamily
+ * @typedef {import("@smithers-orchestrator/observability/agentTrace").AgentSessionTranscriptEvent} AgentSessionTranscriptEvent
+ * @typedef {import("@smithers-orchestrator/observability/agentTrace").AgentTraceCapabilityProfile} AgentTraceCapabilityProfile
+ * @typedef {import("@smithers-orchestrator/observability/agentTrace").AgentTraceSummary} AgentTraceSummary
+ * @typedef {import("@smithers-orchestrator/observability/agentTrace").CanonicalAgentTraceEvent} CanonicalAgentTraceEvent
+ * @typedef {import("@smithers-orchestrator/observability/agentTrace").CanonicalAgentTraceEventKind} CanonicalAgentTraceEventKind
+ * @typedef {import("@smithers-orchestrator/observability/agentTrace").TraceCompleteness} TraceCompleteness
+ * @typedef {import("./AgentTraceCollectorOptions.ts").AgentTraceCollectorOptions} AgentTraceCollectorOptions
+ * @typedef {import("./events.js").EventBus} EventBus
+ *
+ * @typedef {import("@smithers-orchestrator/observability/_traceEventNormalizers").NormalizedTraceBatch} NormalizedTraceBatch
+ * @typedef {import("@smithers-orchestrator/observability/_traceEventNormalizers").NormalizedTraceEvent} NormalizedTraceEvent
+ */
+
+/**
+ * @param {Record<string, string | number | boolean> | undefined} annotations
+ * @returns {Record<string, string | number | boolean>}
+ */
+function normalizeAnnotations(annotations) {
+    /** @type {Record<string, string | number | boolean>} */
+    const normalized = {};
+    for (const [key, value] of Object.entries(annotations ?? {})) {
+        if (["string", "number", "boolean"].includes(typeof value)) {
+            normalized[key] = /** @type {string | number | boolean} */ (value);
+        }
+    }
+    return normalized;
+}
+
+export class AgentTraceCollector {
+    /** @type {EventBus} */
+    eventBus;
+    /** @type {string} */
+    runId;
+    /** @type {string | undefined} */
+    workflowPath;
+    /** @type {string | undefined} */
+    workflowHash;
+    /** @type {string} */
+    cwd;
+    /** @type {string} */
+    nodeId;
+    /** @type {number} */
+    iteration;
+    /** @type {number} */
+    attempt;
+    /** @type {any} */
+    agent;
+    /** @type {AgentFamily} */
+    agentFamily;
+    /** @type {AgentCaptureMode} */
+    captureMode;
+    /** @type {string | undefined} */
+    agentId;
+    /** @type {string | undefined} */
+    model;
+    /** @type {Record<string, string | number | boolean>} */
+    annotations;
+    /** @type {string | undefined} */
+    logDir;
+    /** @type {AgentTraceCapabilityProfile} */
+    capabilities;
+    /** @type {number} */
+    startedAtMs = nowMs();
+    /** @type {CanonicalAgentTraceEvent[]} */
+    events = [];
+    /** @type {AgentSessionTranscriptEvent[]} */
+    sessionEvents = [];
+    /** @type {string[]} */
+    rawArtifactRefs = [];
+    /** @type {Set<CanonicalAgentTraceEventKind>} */
+    seenKinds = new Set();
+    /** @type {Set<string>} */
+    seenSessionRows = new Set();
+    /** @type {Set<CanonicalAgentTraceEventKind>} */
+    directKinds = new Set();
+    /** @type {Set<CanonicalAgentTraceEventKind>} */
+    expectedKinds = new Set();
+    /** @type {string[]} */
+    failures = [];
+    /** @type {string[]} */
+    warnings = [];
+    sequence = 0;
+    sessionSequence = 0;
+    rawEventSequence = 0;
+    stdoutBuffer = "";
+    stderrBuffer = "";
+    assistantTextBuffer = "";
+    /** @type {string | null} */
+    finalText = null;
+    /** @type {string | undefined} */
+    providerSessionId;
+    /** @type {string | undefined} */
+    providerThreadId;
+    /** @type {string | undefined} */
+    currentRawEventId;
+    /** @type {((event: SmithersEvent) => void) | undefined} */
+    listener;
+
+    /** @param {AgentTraceCollectorOptions} opts */
+    constructor(opts) {
+        this.eventBus = opts.eventBus;
+        this.runId = opts.runId;
+        this.workflowPath = opts.workflowPath ?? undefined;
+        this.workflowHash = opts.workflowHash ?? undefined;
+        this.cwd = opts.cwd;
+        this.nodeId = opts.nodeId;
+        this.iteration = opts.iteration;
+        this.attempt = opts.attempt;
+        this.agent = opts.agent;
+        this.agentFamily = detectAgentFamily(opts.agent);
+        this.captureMode = detectCaptureMode(opts.agent);
+        this.capabilities = resolveAgentTraceCapabilities(this.agentFamily, this.captureMode);
+        this.agentId = opts.agentId;
+        this.model = opts.model;
+        this.annotations = normalizeAnnotations(opts.annotations);
+        this.logDir = opts.logDir;
+
+        const profile = this.capabilities;
+        if (profile.sessionMetadata && this.agentFamily === "pi") {
+            this.expectedKinds.add("session.start");
+            this.expectedKinds.add("session.end");
+            this.expectedKinds.add("turn.start");
+            this.expectedKinds.add("turn.end");
+        }
+        if (profile.finalAssistantMessage) {
+            this.expectedKinds.add("assistant.message.final");
+        }
+    }
+
+    begin() {
+        this.listener = (event) => this.observeSmithersEvent(event);
+        this.eventBus.on("event", this.listener);
+    }
+
+    endListener() {
+        if (this.listener) this.eventBus.off("event", this.listener);
+        this.listener = undefined;
+    }
+
+    /** @param {string} text */
+    onStdout(text) {
+        this.processChunk("stdout", text);
+    }
+
+    /** @param {string} text */
+    onStderr(text) {
+        this.processChunk("stderr", text);
+    }
+
+    /** @param {any} result */
+    observeResult(result) {
+        const text = String(result?.text ?? "").trim();
+        const rawEventId = this.nextRawEventId("result");
+        if (text &&
+            (!this.finalText ||
+                (!this.seenKinds.has("assistant.text.delta") &&
+                    !this.seenKinds.has("assistant.message.final")))) {
+            this.finalText = text;
+        }
+        if (this.captureMode === "sdk-events" && text) {
+            this.pushDerived("assistant.message.final", { text }, text, undefined, true, rawEventId);
+        }
+        const usage = normalizeTokenUsage(result?.usage ?? result?.totalUsage);
+        if (usage) {
+            this.pushDerived("usage", usage, usage, "usage", true, rawEventId);
+        }
+    }
+
+    /** @param {unknown} error */
+    observeError(error) {
+        this.failures.push(error instanceof Error ? error.message : String(error));
+        const rawEventId = this.nextRawEventId("error");
+        this.pushDerived("capture.error", { error: this.failures.at(-1) }, { error: this.failures.at(-1) }, "error", true, rawEventId);
+    }
+
+    async flush() {
+        this.endListener();
+        const finishedAtMs = nowMs();
+        this.flushStructuredBuffers();
+        await this.importProviderSessionTranscript();
+        if (this.captureMode !== "sdk-events" &&
+            !this.seenKinds.has("assistant.message.final") &&
+            this.finalText &&
+            this.failures.length === 0) {
+            this.pushDerived("assistant.message.final", { text: this.finalText }, this.finalText, undefined, false);
+        }
+        if ((this.captureMode === "cli-json-stream" || this.captureMode === "rpc-events") &&
+            this.events.length > 0 &&
+            !this.seenKinds.has("assistant.message.final") &&
+            this.failures.length === 0) {
+            this.warnings.push("structured stream ended without a terminal assistant message");
+            this.pushDerived("capture.warning", { reason: "missing-terminal-event" }, { reason: "missing-terminal-event" }, "capture");
+        }
+
+        let traceCompleteness = this.resolveCompleteness();
+        let missingExpectedEventKinds = [...this.expectedKinds].filter((kind) => !this.directKinds.has(kind));
+        this.applyTraceCompleteness(traceCompleteness);
+        /** @type {AgentTraceSummary} */
+        let summary = {
+            traceVersion: "1",
+            runId: this.runId,
+            workflowPath: this.workflowPath,
+            workflowHash: this.workflowHash,
+            nodeId: this.nodeId,
+            iteration: this.iteration,
+            attempt: this.attempt,
+            traceStartedAtMs: this.startedAtMs,
+            traceFinishedAtMs: finishedAtMs,
+            agentFamily: this.agentFamily,
+            agentId: this.agentId,
+            model: this.model,
+            captureMode: this.captureMode,
+            traceCompleteness,
+            unsupportedEventKinds: unsupportedKindsForCapabilities(this.capabilities).filter((kind) => !this.seenKinds.has(kind)),
+            missingExpectedEventKinds,
+            rawArtifactRefs: this.rawArtifactRefs,
+        };
+
+        const persistedArtifact = await this.persistNdjson(summary);
+        if (persistedArtifact.ok && persistedArtifact.file) {
+            const artifactPath = persistedArtifact.file;
+            this.rawArtifactRefs.push(artifactPath);
+            this.pushDerived("artifact.created", {
+                artifactKind: "agent-trace.ndjson",
+                artifactPath,
+                contentType: "application/x-ndjson",
+            }, {
+                artifactKind: "agent-trace.ndjson",
+                artifactPath,
+                contentType: "application/x-ndjson",
+            }, "artifact");
+            this.applyTraceCompleteness(traceCompleteness);
+            summary = { ...summary, rawArtifactRefs: [...this.rawArtifactRefs] };
+            try {
+                await this.rewriteNdjson(artifactPath, summary);
+            } catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                this.warnings.push(message);
+                this.pushDerived("capture.warning", { reason: "artifact-rewrite-failed", error: message }, { reason: "artifact-rewrite-failed", error: message }, "artifact");
+                traceCompleteness = this.resolveCompleteness();
+                missingExpectedEventKinds = [...this.expectedKinds].filter((kind) => !this.directKinds.has(kind));
+                this.applyTraceCompleteness(traceCompleteness);
+                summary = {
+                    ...summary,
+                    traceCompleteness,
+                    missingExpectedEventKinds,
+                    rawArtifactRefs: [...this.rawArtifactRefs],
+                };
+            }
+        } else if (!persistedArtifact.ok) {
+            this.warnings.push(persistedArtifact.error);
+            this.pushDerived("capture.warning", { reason: "artifact-write-failed", error: persistedArtifact.error }, { reason: "artifact-write-failed", error: persistedArtifact.error }, "artifact");
+            traceCompleteness = this.resolveCompleteness();
+            missingExpectedEventKinds = [...this.expectedKinds].filter((kind) => !this.directKinds.has(kind));
+            this.applyTraceCompleteness(traceCompleteness);
+            summary = {
+                ...summary,
+                traceCompleteness,
+                missingExpectedEventKinds,
+                rawArtifactRefs: [...this.rawArtifactRefs],
+            };
+        }
+
+        this.applyTraceCompleteness(traceCompleteness);
+        for (const event of this.events) {
+            /** @type {SmithersEvent} */
+            const smithersEvent = /** @type {any} */ ({
+                type: "AgentTraceEvent",
+                runId: this.runId,
+                nodeId: this.nodeId,
+                iteration: this.iteration,
+                attempt: this.attempt,
+                trace: event,
+                timestampMs: event.timestampMs,
+            });
+            await this.eventBus.emitEventQueued(smithersEvent);
+            if (!shouldExportTraceEventToOtel(event)) continue;
+            const record = canonicalTraceEventToOtelLogRecord(event, {
+                agentId: this.agentId,
+                model: this.model,
+            });
+            await emitOtelLogRecord("agent-trace", record);
+        }
+        for (const event of this.sessionEvents) {
+            /** @type {SmithersEvent} */
+            const smithersEvent = /** @type {any} */ ({
+                type: "AgentSessionEvent",
+                runId: this.runId,
+                nodeId: this.nodeId,
+                iteration: this.iteration,
+                attempt: this.attempt,
+                transcript: event,
+                timestampMs: event.timestampMs,
+            });
+            await this.eventBus.emitEventQueued(smithersEvent);
+            const record = agentSessionEventToOtelLogRecord(event, {
+                agentId: this.agentId,
+                model: this.model,
+            });
+            await emitOtelLogRecord("agent-session", record);
+        }
+
+        await this.eventBus.emitEventQueued(/** @type {any} */ ({
+            type: "AgentTraceSummary",
+            runId: this.runId,
+            nodeId: this.nodeId,
+            iteration: this.iteration,
+            attempt: this.attempt,
+            summary,
+            timestampMs: finishedAtMs,
+        }));
+    }
+
+    /**
+     * @param {"stdout" | "stderr"} stream
+     * @param {string} text
+     */
+    processChunk(stream, text) {
+        if (stream === "stderr") {
+            this.stderrBuffer += text;
+            this.pushObserved("stderr", { text }, text, stream);
+            return;
+        }
+        this.stdoutBuffer += text;
+        if (this.captureMode === "cli-text" || this.captureMode === "sdk-events") {
+            this.pushObserved("stdout", { text }, text, stream);
+            return;
+        }
+        const lines = this.stdoutBuffer.split(/\r?\n/);
+        this.stdoutBuffer = lines.pop() ?? "";
+        for (const line of lines) {
+            if (!line.trim()) continue;
+            this.processStructuredStdoutLine(line);
+        }
+    }
+
+    flushStructuredBuffers() {
+        if (this.captureMode === "cli-text" || this.captureMode === "sdk-events") {
+            this.stdoutBuffer = "";
+            this.stderrBuffer = "";
+            return;
+        }
+        const line = this.stdoutBuffer.trim();
+        this.stdoutBuffer = "";
+        this.stderrBuffer = "";
+        if (!line) return;
+        this.failures.push(`truncated structured stream: ${line.slice(0, 200)}`);
+        this.pushObserved("capture.error", { reason: "truncated-json-stream", linePreview: line.slice(0, 200) }, line, "stdout");
+    }
+
+    /** @param {string} line */
+    processStructuredStdoutLine(line) {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        } catch {
+            this.failures.push(`malformed upstream JSON: ${line.slice(0, 200)}`);
+            this.pushObserved("capture.error", { linePreview: line.slice(0, 200), reason: "malformed-json" }, line, "stdout");
+            return;
+        }
+        const rawType = typeof parsed?.type === "string" ? parsed.type : "structured";
+        const previousRawEventId = this.currentRawEventId;
+        this.currentRawEventId = this.nextRawEventId(rawType);
+        try {
+            this.observeProviderSessionRow(parsed, "live");
+            this.emitObservedBatch(normalizeStructuredEvent(this.agentFamily, parsed, rawType));
+        } finally {
+            this.currentRawEventId = previousRawEventId;
+        }
+    }
+
+    /** @param {string} text */
+    appendAssistantText(text) {
+        this.assistantTextBuffer += text;
+        this.finalText = this.assistantTextBuffer;
+    }
+
+    /** @param {string} text */
+    setFinalAssistantText(text) {
+        this.assistantTextBuffer = text;
+        this.finalText = text;
+    }
+
+    /** @param {SmithersEvent} event */
+    observeSmithersEvent(event) {
+        const anyEvent = /** @type {any} */ (event);
+        const sameAttempt = anyEvent.runId === this.runId &&
+            anyEvent.nodeId === this.nodeId &&
+            anyEvent.iteration === this.iteration &&
+            anyEvent.attempt === this.attempt;
+        if (!sameAttempt) return;
+        if (this.agentFamily === "pi") return;
+        if (event.type === "ToolCallStarted") {
+            const rawEventId = this.nextRawEventId(event.type);
+            this.pushDerived("tool.execution.start", {
+                toolCallId: event.toolCallId,
+                toolName: event.toolName,
+            }, event, event.type, true, rawEventId);
+            this.expectedKinds.add("tool.execution.end");
+        }
+        if (event.type === "ToolCallFinished") {
+            const rawEventId = this.nextRawEventId(event.type);
+            this.pushDerived("tool.execution.end", {
+                toolCallId: event.toolCallId,
+                toolName: event.toolName,
+                isError: event.status === "error",
+            }, event, event.type, true, rawEventId);
+        }
+        if (event.type === "TokenUsageReported") {
+            const rawEventId = this.nextRawEventId(event.type);
+            this.pushDerived("usage", {
+                model: event.model,
+                agent: event.agent,
+                inputTokens: event.inputTokens,
+                outputTokens: event.outputTokens,
+                cacheReadTokens: event.cacheReadTokens,
+                cacheWriteTokens: event.cacheWriteTokens,
+                reasoningTokens: event.reasoningTokens,
+            }, event, event.type, true, rawEventId);
+        }
+    }
+
+    /** @returns {TraceCompleteness} */
+    resolveCompleteness() {
+        if (this.failures.length > 0) return "capture-failed";
+        /** @type {Set<CanonicalAgentTraceEventKind>} */
+        const richKinds = new Set([
+            "session.start",
+            "session.end",
+            "turn.start",
+            "turn.end",
+            "message.start",
+            "message.update",
+            "message.end",
+            "assistant.text.delta",
+            "assistant.thinking.delta",
+            "tool.execution.start",
+            "tool.execution.update",
+            "tool.execution.end",
+            "tool.result",
+            "retry.start",
+            "retry.end",
+            "compaction.start",
+            "compaction.end",
+        ]);
+        const sawRichStructure = [...this.directKinds].some((kind) => richKinds.has(kind));
+        const coarseCaptureMode = this.captureMode === "sdk-events" ||
+            this.captureMode === "cli-text" ||
+            this.captureMode === "cli-json";
+        if (!sawRichStructure && this.warnings.length === 0 && coarseCaptureMode) {
+            return "final-only";
+        }
+        const missing = [...this.expectedKinds].filter((kind) => !this.directKinds.has(kind));
+        if (missing.length > 0 || this.warnings.length > 0) return "partial-observed";
+        if (coarseCaptureMode) {
+            return sawRichStructure ? "partial-observed" : "final-only";
+        }
+        if (!sawRichStructure) return "final-only";
+        return "full-observed";
+    }
+
+    /**
+     * @param {CanonicalAgentTraceEventKind} kind
+     * @param {Record<string, unknown> | null} payload
+     * @param {unknown} raw
+     * @param {boolean} observed
+     * @param {string} [rawType]
+     * @param {boolean} [direct]
+     * @param {string} [rawEventId]
+     */
+    push(kind, payload, raw, observed, rawType, direct = true, rawEventId) {
+        const redactedPayload = redactValue(payload);
+        const redactedRaw = redactValue(raw);
+        /** @type {CanonicalAgentTraceEvent} */
+        const event = {
+            traceVersion: "1",
+            runId: this.runId,
+            workflowPath: this.workflowPath,
+            workflowHash: this.workflowHash,
+            nodeId: this.nodeId,
+            iteration: this.iteration,
+            attempt: this.attempt,
+            timestampMs: nowMs(),
+            event: {
+                sequence: this.sequence++,
+                kind,
+                phase: kindPhase(kind),
+            },
+            source: {
+                agentFamily: this.agentFamily,
+                captureMode: this.captureMode,
+                rawType,
+                rawEventId: rawEventId ??
+                    (observed
+                        ? (this.currentRawEventId ?? this.nextRawEventId(rawType ?? kind))
+                        : undefined),
+                observed,
+            },
+            traceCompleteness: "partial-observed",
+            payload: /** @type {Record<string, unknown> | null} */ (redactedPayload.value),
+            raw: redactedRaw.value,
+            redaction: {
+                applied: redactedPayload.applied || redactedRaw.applied,
+                ruleIds: [...new Set([...redactedPayload.ruleIds, ...redactedRaw.ruleIds])],
+            },
+            annotations: this.annotations,
+        };
+        this.events.push(event);
+        this.seenKinds.add(kind);
+        if (direct) this.directKinds.add(kind);
+    }
+
+    /**
+     * @param {CanonicalAgentTraceEventKind} kind
+     * @param {Record<string, unknown> | null} payload
+     * @param {unknown} raw
+     * @param {string} [rawType]
+     * @param {string} [rawEventId]
+     */
+    pushObserved(kind, payload, raw, rawType, rawEventId) {
+        this.push(kind, payload, raw, true, rawType, true, rawEventId);
+    }
+
+    /**
+     * @param {CanonicalAgentTraceEventKind} kind
+     * @param {Record<string, unknown> | null} payload
+     * @param {unknown} raw
+     * @param {string} [rawType]
+     * @param {boolean} [direct]
+     * @param {string} [rawEventId]
+     */
+    pushDerived(kind, payload, raw, rawType, direct = true, rawEventId) {
+        this.push(kind, payload, raw, false, rawType, direct, rawEventId);
+    }
+
+    /** @param {TraceCompleteness} traceCompleteness */
+    applyTraceCompleteness(traceCompleteness) {
+        for (const event of this.events) {
+            event.traceCompleteness = traceCompleteness;
+        }
+    }
+
+    /**
+     * @param {NormalizedTraceBatch} batch
+     * @param {string} [rawEventId]
+     */
+    emitObservedBatch(batch, rawEventId = this.currentRawEventId) {
+        for (const kind of batch.expectedKinds ?? []) {
+            this.expectedKinds.add(kind);
+        }
+        for (const event of batch.events) {
+            this.observeNormalizedEvent(event);
+            if (event.observed) {
+                this.pushObserved(event.kind, event.payload, event.raw, event.rawType, rawEventId);
+                continue;
+            }
+            this.pushDerived(event.kind, event.payload, event.raw, event.rawType, true, rawEventId);
+        }
+    }
+
+    /** @param {NormalizedTraceEvent} event */
+    observeNormalizedEvent(event) {
+        if (event.kind === "assistant.text.delta" &&
+            typeof event.payload?.text === "string") {
+            this.appendAssistantText(event.payload.text);
+            return;
+        }
+        if (event.kind === "assistant.message.final" &&
+            typeof event.payload?.text === "string") {
+            this.setFinalAssistantText(event.payload.text);
+        }
+    }
+
+    /** @param {string} rawType */
+    nextRawEventId(rawType) {
+        return `${rawType}:${this.rawEventSequence++}`;
+    }
+
+    /**
+     * @param {unknown} row
+     * @param {"live" | "artifact"} ingestSource
+     */
+    observeProviderSessionRow(row, ingestSource) {
+        if (this.captureMode !== "cli-json-stream" && this.captureMode !== "rpc-events") return;
+        const fingerprint = JSON.stringify(row);
+        if (this.seenSessionRows.has(fingerprint)) return;
+        this.seenSessionRows.add(fingerprint);
+        const correlation = extractProviderSessionCorrelation(this.agentFamily, row);
+        if (correlation.sessionId) this.providerSessionId = correlation.sessionId;
+        if (correlation.threadId) this.providerThreadId = correlation.threadId;
+        const redacted = redactValue(row);
+        const parsed = /** @type {any} */ (row);
+        this.sessionEvents.push({
+            transcriptVersion: "1",
+            runId: this.runId,
+            workflowPath: this.workflowPath,
+            workflowHash: this.workflowHash,
+            nodeId: this.nodeId,
+            iteration: this.iteration,
+            attempt: this.attempt,
+            timestampMs: nowMs(),
+            event: {
+                sequence: this.sessionSequence++,
+                rowType: typeof parsed?.type === "string" && parsed.type ? parsed.type : "structured",
+            },
+            source: {
+                agentFamily: this.agentFamily,
+                captureMode: this.captureMode,
+                ingestSource,
+                observedLive: ingestSource === "live",
+                providerSessionId: this.providerSessionId,
+                providerThreadId: this.providerThreadId,
+            },
+            raw: redacted.value,
+            redaction: {
+                applied: redacted.applied,
+                ruleIds: redacted.ruleIds,
+            },
+            annotations: this.annotations,
+        });
+    }
+
+    async importProviderSessionTranscript() {
+        const file = await this.resolveProviderSessionFile();
+        if (!file) return;
+        let text;
+        try {
+            text = await readFile(file, "utf8");
+        } catch (error) {
+            this.warnings.push(error instanceof Error ? error.message : String(error));
+            return;
+        }
+        for (const line of text.split(/\r?\n/)) {
+            if (!line.trim()) continue;
+            try {
+                this.observeProviderSessionRow(JSON.parse(line), "artifact");
+            } catch {
+                // Keep canonical capture strict; transcript backfill is best effort only.
+            }
+        }
+    }
+
+    /** @returns {Promise<string | null>} */
+    async resolveProviderSessionFile() {
+        if (this.agentFamily === "pi") {
+            return resolvePiSessionFile(this.agent, this.providerSessionId);
+        }
+        if (this.agentFamily === "claude-code") {
+            return resolveClaudeSessionFile(this.agent, this.cwd, this.providerSessionId);
+        }
+        if (this.agentFamily === "codex") {
+            return resolveCodexSessionFile(this.agent, this.cwd, this.startedAtMs);
+        }
+        return null;
+    }
+
+    /**
+     * @param {AgentTraceSummary} summary
+     * @returns {Promise<{ ok: true; file?: string } | { ok: false; error: string }>}
+     */
+    async persistNdjson(summary) {
+        if (!this.logDir) return { ok: true };
+        const dir = join(this.logDir, "agent-trace");
+        const file = join(dir, `${this.nodeId}-${this.iteration}-${this.attempt}.ndjson`);
+        const lines = this.events
+            .map((event) => JSON.stringify(event))
+            .concat(JSON.stringify({ summary }));
+        try {
+            await mkdir(dir, { recursive: true });
+            await appendFile(file, `${lines.join("\n")}\n`, "utf8");
+            return { ok: true, file };
+        } catch (error) {
+            return {
+                ok: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+
+    /**
+     * @param {string} file
+     * @param {AgentTraceSummary} summary
+     */
+    async rewriteNdjson(file, summary) {
+        const lines = this.events
+            .map((event) => JSON.stringify(event))
+            .concat(JSON.stringify({ summary }));
+        await writeFile(file, `${lines.join("\n")}\n`, "utf8");
+    }
+}

package/src/AgentTraceCollectorOptions.ts

@@ -0,0 +1,17 @@
+import type { EventBus } from "./events.js";
+
+export type AgentTraceCollectorOptions = {
+  eventBus: EventBus;
+  runId: string;
+  workflowPath?: string | null;
+  workflowHash?: string | null;
+  cwd: string;
+  nodeId: string;
+  iteration: number;
+  attempt: number;
+  agent: unknown;
+  agentId?: string;
+  model?: string;
+  logDir?: string;
+  annotations?: Record<string, string | number | boolean>;
+};

package/src/engine.js

@@ -20,6 +20,7 @@ import { buildPlanTree, scheduleTasks, buildStateKey, } from "./scheduler.js";
 import { getDefinedToolMetadata } from "./getDefinedToolMetadata.js";
 import { captureSnapshotEffect, loadLatestSnapshot, parseSnapshot, } from "@smithers-orchestrator/time-travel/snapshot";
 import { EventBus } from "./events.js";
+import { AgentTraceCollector } from "./AgentTraceCollector.js";
 import { getJjPointer, runJj, workspaceAdd } from "@smithers-orchestrator/vcs/jj";
 import { findVcsRoot } from "@smithers-orchestrator/vcs/find-root";
 import * as BunContext from "@effect/platform-bun/BunContext";
@@ -117,6 +118,78 @@ function isAbortError(err) {
     }
     return false;
 }
+/**
+ * @param {unknown} err
+ * @returns {string[]}
+ */
+function collectErrorMessages(err) {
+    const messages = [];
+    let current = err;
+    const seen = new Set();
+    while (current && typeof current === "object" && !seen.has(current)) {
+        seen.add(current);
+        const record = /** @type {Record<string, unknown>} */ (current);
+        if (typeof record.name === "string")
+            messages.push(record.name);
+        if (typeof record.message === "string")
+            messages.push(record.message);
+        current = record.cause;
+    }
+    if (typeof err === "string") {
+        messages.push(err);
+    }
+    return messages;
+}
+/**
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+function isStructuredOutputParseFailure(err) {
+    // AI SDK 6.x names structured-output parse/validation failures with these
+    // stable error names. The message fallback catches errors after wrapping.
+    const aiSdkErrorName = /^AI_(NoObjectGeneratedError|NoOutputGeneratedError|JSONParseError|TypeValidationError)$/;
+    const aiSdkErrorMessage = /No output generated|No object generated|could not parse the response|structured output parse|response did not match schema/i;
+    return collectErrorMessages(err).some((message) => aiSdkErrorName.test(message) || aiSdkErrorMessage.test(message));
+}
+/**
+ * @param {string} nodeId
+ * @returns {string}
+ */
+function depsTextAccessHint(nodeId) {
+    return /^[A-Za-z_$][\w$]*$/.test(nodeId)
+        ? `deps.${nodeId}.text`
+        : `deps[${JSON.stringify(nodeId)}].text`;
+}
+/**
+ * @param {Pick<TaskDescriptor, "nodeId" | "outputTableName">} desc
+ * @param {unknown} cause
+ * @param {Record<string, unknown>} [details]
+ * @returns {SmithersError}
+ */
+function makeStructuredOutputCompatibilityError(desc, cause, details = {}) {
+    return new SmithersError("INVALID_OUTPUT", `Task "${desc.nodeId}" expected structured JSON output, but the agent/model did not return valid JSON for the declared output schema. This commonly happens with OpenAI-compatible local model servers such as llama.cpp that do not fully support JSON schema structured output. Use a model that supports structured output, or opt out with OpenAIAgent({ nativeStructuredOutput: false }) so Smithers can use prompt-based JSON extraction.`, {
+        nodeId: desc.nodeId,
+        outputTable: desc.outputTableName,
+        ...details,
+        hint: "For plain text, use an object-shaped schema such as z.object({ text: z.string() }) and read it downstream as deps.<task>.text.",
+    }, { cause });
+}
+/**
+ * @param {Pick<TaskDescriptor, "nodeId" | "outputTableName">} desc
+ * @param {string} text
+ * @param {unknown} [cause]
+ * @param {Record<string, unknown>} [details]
+ * @returns {SmithersError}
+ */
+function makePlainTextOutputError(desc, text, cause, details = {}) {
+    const preview = text.slice(0, 120).replace(/\s+/g, " ").trim();
+    return new SmithersError("INVALID_OUTPUT", `Task "${desc.nodeId}" returned plain text, but Smithers task outputs must be JSON objects matching the declared output schema. Plain text cannot be passed through deps directly. Use z.object({ text: z.string() }), return {"text":"..."}, and read it downstream as ${depsTextAccessHint(desc.nodeId)}.`, {
+        nodeId: desc.nodeId,
+        outputTable: desc.outputTableName,
+        ...details,
+        textPreview: preview || undefined,
+    }, cause === undefined ? undefined : { cause });
+}
 /**
  * @param {AbortSignal} [signal]
  * @returns {Promise<never> | null}
@@ -2582,6 +2655,7 @@ async function legacyExecuteTask(adapter, db, runId, desc, descriptorMap, inputT
     let responseText = null;
     let effectiveAgent = null;
     let supportsNativeStructuredOutput = false;
+    let structuredOutputAccessError;
     // Resolve effective root once so both caching and execution share it.
     const taskRoot = desc.worktreePath ?? toolConfig.rootDir;
     const stepCacheEnabled = cacheEnabled || Boolean(desc.cachePolicy);
@@ -3053,54 +3127,95 @@ async function legacyExecuteTask(adapter, db, runId, desc, descriptorMap, inputT
                     }, 100)
                     : undefined;
                 // Use fallback agent on retry attempts when available
+                const traceCollector = toolConfig.traceContext && effectiveAgent
+                    ? new AgentTraceCollector({
+                        eventBus,
+                        runId,
+                        workflowPath: toolConfig.traceContext.workflowPath,
+                        workflowHash: toolConfig.traceContext.workflowHash,
+                        cwd: taskRoot,
+                        nodeId: desc.nodeId,
+                        iteration: desc.iteration,
+                        attempt: attemptNo,
+                        agent: effectiveAgent,
+                        agentId: attemptMeta.agentId ?? undefined,
+                        model: attemptMeta.agentModel ?? undefined,
+                        logDir: toolConfig.traceContext.logDir,
+                        annotations: toolConfig.traceContext.annotations,
+                    })
+                    : null;
+                if (traceCollector) traceCollector.begin();
                 let result;
                 try {
-                    result = await runPromisePreservingFailure(withSmithersSpan(smithersSpanNames.agent, Effect.tryPromise({
-                        try: () => {
-                            const agentCall = guidedResumeMessages?.length
-                                ? {
-                                    messages: guidedResumeMessages,
-                                }
-                                : {
-                                    prompt: effectivePrompt,
-                                };
-                            return effectiveAgent.generate({
-                                options: undefined,
-                                abortSignal: taskSignal,
-                                ...agentCall,
-                                resumeSession,
-                                lastHeartbeat: previousHeartbeat,
-                                rootDir: taskRoot,
-                                maxOutputBytes: toolConfig.maxOutputBytes,
-                                timeout: desc.timeoutMs
-                                    ? { totalMs: desc.timeoutMs }
-                                    : undefined,
-                                onStdout: (text) => {
-                                    recordInternalHeartbeat();
-                                    emitOutput(text, "stdout");
-                                },
-                                onStderr: (text) => {
-                                    recordInternalHeartbeat();
-                                    emitOutput(text, "stderr");
-                                },
-                                onEvent: handleAgentEvent,
-                                onStepFinish: handleSdkStepFinish,
-                                outputSchema: desc.outputSchema,
-                            });
-                        },
-                        catch: (error) => error,
-                    }), {
-                        ...taskSpanContext,
-                        agent: attemptMeta.agentId ??
-                            attemptMeta.agentEngine ??
-                            "unknown",
-                        model: attemptMeta.agentModel,
-                    }));
+                    try {
+                        result = await runPromisePreservingFailure(withSmithersSpan(smithersSpanNames.agent, Effect.tryPromise({
+                            try: () => {
+                                const agentCall = guidedResumeMessages?.length
+                                    ? {
+                                        messages: guidedResumeMessages,
+                                    }
+                                    : {
+                                        prompt: effectivePrompt,
+                                    };
+                                return effectiveAgent.generate({
+                                    options: undefined,
+                                    abortSignal: taskSignal,
+                                    ...agentCall,
+                                    resumeSession,
+                                    lastHeartbeat: previousHeartbeat,
+                                    rootDir: taskRoot,
+                                    maxOutputBytes: toolConfig.maxOutputBytes,
+                                    timeout: desc.timeoutMs
+                                        ? { totalMs: desc.timeoutMs }
+                                        : undefined,
+                                    onStdout: (text) => {
+                                        recordInternalHeartbeat();
+                                        emitOutput(text, "stdout");
+                                        traceCollector?.onStdout(text);
+                                    },
+                                    onStderr: (text) => {
+                                        recordInternalHeartbeat();
+                                        emitOutput(text, "stderr");
+                                        traceCollector?.onStderr(text);
+                                    },
+                                    onEvent: handleAgentEvent,
+                                    onStepFinish: handleSdkStepFinish,
+                                    outputSchema: desc.outputSchema,
+                                });
+                            },
+                            catch: (error) => error,
+                        }), {
+                            ...taskSpanContext,
+                            agent: attemptMeta.agentId ??
+                                attemptMeta.agentEngine ??
+                                "unknown",
+                            model: attemptMeta.agentModel,
+                        }));
+                    }
+                    finally {
+                        if (hijackPollingInterval) {
+                            clearInterval(hijackPollingInterval);
+                        }
+                    }
                 }
-                finally {
-                    if (hijackPollingInterval) {
-                        clearInterval(hijackPollingInterval);
+                catch (error) {
+                    const errorDetails = {
+                        attempt: attemptNo,
+                        iteration: desc.iteration,
+                    };
+                    const effectiveError = supportsNativeStructuredOutput && desc.outputSchema && isStructuredOutputParseFailure(error)
+                        ? makeStructuredOutputCompatibilityError(desc, error, errorDetails)
+                        : error;
+                    if (traceCollector) {
+                        traceCollector.observeError(effectiveError);
+                        try { await traceCollector.flush(); }
+                        catch { /* trace flush failures must not mask the original error */ }
                     }
+                    throw effectiveError;
+                }
+                if (traceCollector) {
+                    traceCollector.observeResult(result);
+                    await traceCollector.flush();
                 }
                 agentResult = result;
                 if (!conversationMessages) {
@@ -3163,8 +3278,9 @@ async function legacyExecuteTask(adapter, db, runId, desc, descriptorMap, inputT
                         output = result.output;
                     }
                 }
-                catch {
-                    // Structured output access threw
+                catch (error) {
+                    structuredOutputAccessError = error;
+                    // Structured output access threw; text parsing below may still recover.
                 }
                 // Fall back to parsing text/steps for JSON
                 if (output === undefined) {
@@ -3389,6 +3505,7 @@ async function legacyExecuteTask(adapter, db, runId, desc, descriptorMap, inputT
                     if (output === undefined) {
                         // Debug: log what we have
                         const finishReason = result.finishReason ?? "unknown";
+                        const debugSteps = result.steps ?? [];
                         logDebug("agent response did not contain valid JSON output", {
                             runId,
                             nodeId: desc.nodeId,
@@ -3406,6 +3523,16 @@ async function legacyExecuteTask(adapter, db, runId, desc, descriptorMap, inputT
                         const tailHint = tail
                             ? ` Last 200 chars of response: ${JSON.stringify(tail)}`
                             : " Agent returned an empty response.";
+                        const errorDetails = {
+                            attempt: attemptNo,
+                            iteration: desc.iteration,
+                        };
+                        if (supportsNativeStructuredOutput && structuredOutputAccessError) {
+                            throw makeStructuredOutputCompatibilityError(desc, structuredOutputAccessError, errorDetails);
+                        }
+                        if (text.trim()) {
+                            throw makePlainTextOutputError(desc, text, undefined, errorDetails);
+                        }
                         throw new SmithersError("INVALID_OUTPUT", `No valid JSON output found in agent response (finishReason=${finishReason}, textLength=${text.length}).${tailHint}`);
                     }
                 }
@@ -3414,8 +3541,11 @@ async function legacyExecuteTask(adapter, db, runId, desc, descriptorMap, inputT
                     try {
                         payload = JSON.parse(output);
                     }
-                    catch  {
-                        throw new SmithersError("INVALID_OUTPUT", `Failed to parse agent output as JSON. Output starts with: "${output.slice(0, 100)}"`);
+                    catch (error) {
+                        throw makePlainTextOutputError(desc, output, error, {
+                            attempt: attemptNo,
+                            iteration: desc.iteration,
+                        });
                     }
                 }
                 else {
@@ -3469,16 +3599,32 @@ async function legacyExecuteTask(adapter, db, runId, desc, descriptorMap, inputT
      * @param {unknown} cause
      * @param {number} schemaRetryAttempts
      */
-        const toInvalidOutputError = (cause, schemaRetryAttempts) => new SmithersError("INVALID_OUTPUT", `Task output failed validation for ${desc.outputTableName}`, {
-            attempt: attemptNo,
-            nodeId: desc.nodeId,
-            iteration: desc.iteration,
-            outputTable: desc.outputTableName,
-            schemaRetryAttempts,
-            issues: cause && typeof cause === "object" && "issues" in cause
-                ? cause.issues
-                : undefined,
-        }, { cause });
+        const toInvalidOutputError = (cause, schemaRetryAttempts) => {
+            if (supportsNativeStructuredOutput && structuredOutputAccessError) {
+                return makeStructuredOutputCompatibilityError(desc, structuredOutputAccessError, {
+                    attempt: attemptNo,
+                    iteration: desc.iteration,
+                    schemaRetryAttempts,
+                });
+            }
+            if (typeof payload === "string") {
+                return makePlainTextOutputError(desc, payload, cause, {
+                    attempt: attemptNo,
+                    iteration: desc.iteration,
+                    schemaRetryAttempts,
+                });
+            }
+            return new SmithersError("INVALID_OUTPUT", `Task output failed validation for ${desc.outputTableName}`, {
+                attempt: attemptNo,
+                nodeId: desc.nodeId,
+                iteration: desc.iteration,
+                outputTable: desc.outputTableName,
+                schemaRetryAttempts,
+                issues: cause && typeof cause === "object" && "issues" in cause
+                    ? cause.issues
+                    : undefined,
+            }, { cause });
+        };
         // Schema-validation retry: if the agent returned parseable JSON but it
         // doesn't match the Zod schema, resume the SAME agent conversation with
         // the validation error up to 3 times before giving up. These attempts
@@ -3511,6 +3657,7 @@ async function legacyExecuteTask(adapter, db, runId, desc, descriptorMap, inputT
         }
         while (!validation.ok && desc.agent && schemaRetry < MAX_SCHEMA_RETRIES) {
             schemaRetry++;
+            structuredOutputAccessError = undefined;
             const schemaDesc = describeSchemaShape(desc.outputTable, desc.outputSchema);
             const zodIssues = validation.error?.issues
                 ?.map((iss) => `  - ${(iss.path ?? []).join(".")}: ${iss.message}`)
@@ -3598,7 +3745,8 @@ async function legacyExecuteTask(adapter, db, runId, desc, descriptorMap, inputT
                         retryOutput = schemaRetryResult.output;
                     }
                 }
-                catch {
+                catch (error) {
+                    structuredOutputAccessError = error;
                     // Structured output access threw; fall back to text parsing.
                 }
             }
@@ -4280,6 +4428,12 @@ async function runWorkflowBodyDriver(workflow, opts) {
         allowNetwork,
         maxOutputBytes,
         toolTimeoutMs,
+        traceContext: {
+            workflowPath: resolvedWorkflowPath ?? opts.workflowPath ?? null,
+            workflowHash: runMetadata.workflowHash ?? null,
+            logDir: logDir ?? undefined,
+            annotations: opts.annotations,
+        },
     };
     let frameNo = ((await adapter.getLastFrame(runId))?.frameNo ?? 0);
     let defaultIteration = 0;
@@ -5665,6 +5819,12 @@ async function runWorkflowBodyLegacy(workflow, opts) {
             allowNetwork,
             maxOutputBytes,
             toolTimeoutMs,
+            traceContext: {
+                workflowPath: resolvedWorkflowPath ?? opts.workflowPath ?? null,
+                workflowHash: runMetadata.workflowHash ?? null,
+                logDir: logDir ?? undefined,
+                annotations: opts.annotations,
+            },
         };
         const schedulerExecutionConcurrency = Math.max(1, maxConcurrency);
         /**