agentfootprint 6.11.1 → 6.12.0

package/dist/esm/memory/causal/evidenceRecorder.js

@@ -0,0 +1,213 @@
+/**
+ * causalEvidenceRecorder — the evidence bridge (backlog Phase-1 #5).
+ *
+ * Harvests, DURING the run, everything a causal snapshot needs beyond
+ * (query, finalContent) — from events the engine already fires:
+ *
+ *   stream.tool_start/tool_end  → ToolCallRecord (name, args, resultPreview, errored)
+ *   stream.llm_end              → tokenUsage accumulation + iteration high-water
+ *   agent.turn_start/turn_end   → durationMs (+ authoritative totals when seen)
+ *   FlowRecorder.onDecision     → DecisionRecord with footprintjs decide()/select()
+ *                                 operator-level evidence (rule, conditions, chosen)
+ *   context.evaluated routing   → DecisionRecord per skill the graph routed to
+ *
+ * Pattern: CombinedRecorder (Convention 1 — single purpose: evidence
+ *          accumulation); per-turn reset anchored on `agent.turn_start`
+ *          (Convention 4 — executor `clear()` resets between runs; same-
+ *          executor pause/resume PRESERVES pre-pause evidence by design).
+ * PII note: tool args/results and decide() evidence persist into snapshots.
+ *          footprintjs `RedactionPolicy.emitPatterns` redacts the emit channel
+ *          BEFORE this recorder IF the consumer configures one on the executor
+ *          — the Agent does NOT configure one by default. Values are bounded
+ *          (`maxPreviewChars` for results, `maxFieldChars` for args/evidence);
+ *          treat the snapshot store as PII-bearing and protect it accordingly.
+ *
+ * The Agent attaches this automatically when a CAUSAL memory is mounted and
+ * threads `collect` into the memory write mount (`evidenceSource`) — so
+ * `writeSnapshot` persists real evidence instead of zeros.
+ */
+function preview(value, max) {
+    let s;
+    if (typeof value === 'string')
+        s = value;
+    else {
+        try {
+            s = JSON.stringify(value);
+        }
+        catch {
+            s = String(value);
+        }
+    }
+    return s.length > max ? `${s.slice(0, max)}…` : s;
+}
+/** Bound a record-ish value: oversized serializations become a truncated
+ *  preview marker so snapshots can't grow unbounded (and PII exposure is
+ *  capped). Small values pass through untouched. */
+function bounded(value, max) {
+    if (value === undefined)
+        return undefined;
+    try {
+        const s = JSON.stringify(value);
+        if (s.length <= max)
+            return value;
+        return { __truncated: `${s.slice(0, max)}…` };
+    }
+    catch {
+        return { __truncated: String(value).slice(0, max) };
+    }
+}
+/** Build the evidence-harvesting recorder. Attach via `.recorder(rec)` (the
+ *  Agent does this automatically for CAUSAL memories). */
+export function causalEvidenceRecorder(options = {}) {
+    const maxPreview = options.maxPreviewChars ?? 200;
+    const maxField = options.maxFieldChars ?? 2000;
+    // ── per-turn accumulators (reset on agent.turn_start; executor clear()
+    //    resets between runs; pause/resume keeps pre-pause evidence) ──
+    let decisions = [];
+    let toolCalls = [];
+    let pendingTools = new Map();
+    let tokens = { input: 0, output: 0 };
+    let iterations = 0;
+    let turnStartMs;
+    let authoritative;
+    const reset = () => {
+        decisions = [];
+        toolCalls = [];
+        pendingTools = new Map();
+        tokens = { input: 0, output: 0 };
+        iterations = 0;
+        turnStartMs = undefined;
+        authoritative = undefined;
+    };
+    return {
+        id: options.id ?? 'causal-evidence',
+        onEmit(event) {
+            const { name, payload } = event;
+            switch (name) {
+                case 'agentfootprint.agent.turn_start':
+                    // A new turn on the same executor — start fresh (one snapshot per turn).
+                    reset();
+                    turnStartMs = Date.now();
+                    break;
+                case 'agentfootprint.stream.tool_start': {
+                    const id = String(payload.toolCallId ?? '');
+                    pendingTools.set(id, {
+                        name: String(payload.toolName ?? 'unknown'),
+                        args: bounded((payload.args ?? {}), maxField) ?? {},
+                    });
+                    break;
+                }
+                case 'agentfootprint.stream.tool_end': {
+                    const id = String(payload.toolCallId ?? '');
+                    const started = pendingTools.get(id);
+                    pendingTools.delete(id);
+                    toolCalls.push({
+                        name: started?.name ?? 'unknown',
+                        args: started?.args ?? {},
+                        resultPreview: preview(payload.result, maxPreview),
+                        errored: payload.error === true,
+                    });
+                    break;
+                }
+                case 'agentfootprint.stream.llm_end': {
+                    const usage = payload.usage;
+                    tokens = {
+                        input: tokens.input + (usage?.input ?? 0),
+                        output: tokens.output + (usage?.output ?? 0),
+                    };
+                    const iter = Number(payload.iteration ?? 0);
+                    if (iter > iterations)
+                        iterations = iter;
+                    break;
+                }
+                case 'agentfootprint.context.evaluated': {
+                    // Skill-graph routing provenance → one DecisionRecord per routed skill.
+                    const routing = payload.routing;
+                    if (Array.isArray(routing)) {
+                        for (const r of routing) {
+                            decisions.push({
+                                stageId: 'skill-graph',
+                                chosen: String(r.injectionId ?? r.id ?? 'unknown'),
+                                ...(r.label !== undefined || r.via !== undefined
+                                    ? { rule: r.label ?? `via ${r.via}` }
+                                    : {}),
+                                ...(r.path !== undefined && {
+                                    evidence: { path: r.path },
+                                }),
+                            });
+                        }
+                    }
+                    break;
+                }
+                case 'agentfootprint.agent.turn_end': {
+                    // Authoritative totals when the write runs after turn_end.
+                    authoritative = {
+                        iterations: Number(payload.iterationCount ?? iterations),
+                        input: Number(payload.totalInputTokens ?? tokens.input),
+                        output: Number(payload.totalOutputTokens ?? tokens.output),
+                        durationMs: Number(payload.durationMs ?? 0),
+                    };
+                    break;
+                }
+                default:
+                    break;
+            }
+        },
+        /** footprintjs FlowRecorder channel — decide() decision evidence.
+         *  FlowDecisionEvent carries `decider` (display name), `chosen`, optional
+         *  `evidence` from decide(), and `traversalContext.stageId` (the stable,
+         *  subflow-prefixed stage id — preferred for DecisionRecord.stageId). */
+        onDecision(event) {
+            const stageId = event.traversalContext?.stageId ?? event.decider;
+            // Internal agent plumbing (the cache-gate decider) is not domain
+            // decision evidence. `includes` (not startsWith): in reactMode
+            // 'dynamic-grouped' the names are double-prefixed
+            // ('sf-llm-call/sf-cache/…').
+            if (String(event.chosen ?? '').includes('sf-cache/') || String(stageId).includes('sf-cache'))
+                return;
+            const evidence = event.evidence;
+            decisions.push({
+                stageId: String(stageId),
+                chosen: String(event.chosen ?? 'unknown'),
+                ...(evidence?.label !== undefined || evidence?.rule !== undefined
+                    ? { rule: String(evidence.label ?? evidence.rule) }
+                    : {}),
+                ...(evidence !== undefined && {
+                    evidence: bounded(evidence, maxField),
+                }),
+            });
+        },
+        /** footprintjs FlowRecorder channel — select() selection evidence. */
+        onSelected(event) {
+            const stageId = event.traversalContext?.stageId ?? event.parent;
+            if (String(stageId).includes('sf-cache'))
+                return;
+            // The agent's own Context slot-fork is a selector — plumbing, not domain.
+            if (String(stageId).includes('context') && event.selected.every((s) => s.startsWith('sf-')))
+                return;
+            decisions.push({
+                stageId: String(stageId),
+                chosen: event.selected.join(', '),
+                ...(event.evidence !== undefined && {
+                    evidence: bounded(event.evidence, maxField),
+                }),
+            });
+        },
+        collect() {
+            return {
+                iterations: authoritative?.iterations ?? iterations,
+                decisions: [...decisions],
+                toolCalls: [...toolCalls],
+                durationMs: authoritative?.durationMs ?? (turnStartMs !== undefined ? Date.now() - turnStartMs : 0),
+                tokenUsage: {
+                    input: authoritative?.input ?? tokens.input,
+                    output: authoritative?.output ?? tokens.output,
+                },
+            };
+        },
+        clear() {
+            reset();
+        },
+    };
+}
+//# sourceMappingURL=evidenceRecorder.js.map

package/dist/esm/memory/causal/evidenceRecorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidenceRecorder.js","sourceRoot":"","sources":["../../../../src/memory/causal/evidenceRecorder.ts"],"names":[],"mappings":"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"}

package/dist/esm/memory/causal/index.js

@@ -1,4 +1,5 @@
 export { DEFAULT_TOOL_RESULT_PREVIEW_LEN } from './types.js';
+export { causalEvidenceRecorder, } from './evidenceRecorder.js';
 export { writeSnapshot } from './writeSnapshot.js';
 export { loadSnapshot } from './loadSnapshot.js';
 export { snapshotPipeline } from './snapshotPipeline.js';

package/dist/esm/memory/causal/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/memory/causal/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,+BAA+B,EAAE,MAAM,YAAY,CAAC;AAE7D,OAAO,EAAE,aAAa,EAA4B,MAAM,oBAAoB,CAAC;AAC7E,OAAO,EAAE,YAAY,EAA2B,MAAM,mBAAmB,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAA+B,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/memory/causal/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,+BAA+B,EAAE,MAAM,YAAY,CAAC;AAE7D,OAAO,EACL,sBAAsB,GAIvB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,aAAa,EAA4B,MAAM,oBAAoB,CAAC;AAC7E,OAAO,EAAE,YAAY,EAA2B,MAAM,mBAAmB,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAA+B,MAAM,uBAAuB,CAAC"}

package/dist/esm/memory/causal/loadSnapshot.js

@@ -78,15 +78,29 @@ function formatProjection(entry, projection, score) {
     const header = `[Past run · query: "${truncate(snap.query, 80)}" · score: ${score.toFixed(2)}]`;
     let body;
     switch (projection) {
-        case SNAPSHOT_PROJECTIONS.DECISIONS:
+        case SNAPSHOT_PROJECTIONS.DECISIONS: {
+            // Tool evidence is part of the "why": in LLM-decided flows the
+            // operator-level facts (creditScore=580, dti=0.45) arrive as tool
+            // results, so the decisions projection includes them.
+            // SECURITY: this replays STORED TOOL OUTPUT into a future prompt — a
+            // persisted prompt-injection surface if tools ingest untrusted content.
+            // Treat snapshot stores as prompt-trusted; sanitize tool output at the
+            // tool boundary when it carries third-party text.
+            const toolLines = snap.toolCalls.length === 0
+                ? ''
+                : `\nTool evidence:\n${snap.toolCalls
+                    .map((t) => `- ${t.name}(${JSON.stringify(t.args)}) → ${t.resultPreview}` +
+                    (t.errored ? ' [ERROR]' : ''))
+                    .join('\n')}`;
             body =
-                snap.decisions.length === 0
+                snap.decisions.length === 0 && snap.toolCalls.length === 0
                     ? `(no decision evidence captured)\nFinal answer: ${snap.finalContent}`
-                    : snap.decisions
+                    : `${snap.decisions
                         .map((d) => `- ${d.stageId} → "${d.chosen}"${d.rule ? ` (rule: ${d.rule})` : ''}` +
                         (d.evidence ? `; evidence: ${JSON.stringify(d.evidence)}` : ''))
-                        .join('\n');
+                        .join('\n')}${toolLines}\nFinal answer: ${snap.finalContent}`;
             break;
+        }
         case SNAPSHOT_PROJECTIONS.NARRATIVE:
             body = snap.narrative ?? `(no narrative captured)\nFinal answer: ${snap.finalContent}`;
             break;

package/dist/esm/memory/causal/loadSnapshot.js.map

@@ -1 +1 @@
-{"version":3,"file":"loadSnapshot.js","sourceRoot":"","sources":["../../../../src/memory/causal/loadSnapshot.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"loadSnapshot.js","sourceRoot":"","sources":["../../../../src/memory/causal/loadSnapshot.ts"],"names":[],"mappings":"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"}

package/dist/esm/memory/causal/writeSnapshot.js

@@ -46,14 +46,18 @@ export function writeSnapshot(config) {
         }));
         const now = Date.now();
         const ttl = config.ttlMs ? now + config.ttlMs : undefined;
+        // Evidence bridge (#5): the wire layer delivers run evidence harvested by
+        // `causalEvidenceRecorder` via the write mount's `evidenceSource`. Absent
+        // (non-agent hosts, no recorder attached) → zeros, as before.
+        const evidence = scope.runEvidence;
         const snapshot = {
             query,
             finalContent,
-            iterations: 0, // TODO: capture from scope when wire helper exposes it
-            decisions: [], // Populated by a follow-up FlowRecorder integration
-            toolCalls: [], // Populated by a follow-up FlowRecorder integration
-            durationMs: 0,
-            tokenUsage: { input: 0, output: 0 },
+            iterations: evidence?.iterations ?? 0,
+            decisions: evidence?.decisions ?? [],
+            toolCalls: evidence?.toolCalls ?? [],
+            durationMs: evidence?.durationMs ?? 0,
+            tokenUsage: evidence?.tokenUsage ?? { input: 0, output: 0 },
         };
         const entry = {
             id: `snap-${turn}`,

package/dist/esm/memory/causal/writeSnapshot.js.map

@@ -1 +1 @@
-{"version":3,"file":"writeSnapshot.js","sourceRoot":"","sources":["../../../../src/memory/causal/writeSnapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AA0CH,MAAM,UAAU,aAAa,CAAC,MAA2B;IACvD,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC;IACnC,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,IAAI,kBAAkB,CAAC;IAE3D,OAAO,KAAK,EAAE,KAA8B,EAAiB,EAAE;QAC7D,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;QAChC,MAAM,IAAI,GAAG,KAAK,CAAC,UAAU,CAAC;QAC9B,MAAM,WAAW,GAAG,CAAC,KAAK,CAAC,WAAW,IAAI,EAAE,CAA0B,CAAC;QACvE,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAErC,4DAA4D;QAC5D,gEAAgE;QAChE,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC;QAC3D,MAAM,YAAY,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC;QACrE,MAAM,KAAK,GAAI,OAAO,EAAE,OAA8B,IAAI,EAAE,CAAC;QAC7D,MAAM,YAAY,GAAI,YAAY,EAAE,OAA8B,IAAI,EAAE,CAAC;QAEzE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,CAAC,iCAAiC;QAEjE,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC;QACzC,MAAM,QAAQ,GAAG,CAAC,MAAM,QAAQ,CAAC,KAAK,CAAC;YACrC,IAAI,EAAE,KAAK;YACX,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC9B,CAAC,CAAa,CAAC;QAEhB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;QAE1D,MAAM,QAAQ,GAAkB;YAC9B,KAAK;YACL,YAAY;YACZ,UAAU,EAAE,CAAC,EAAE,uDAAuD;YACtE,SAAS,EAAE,EAAE,EAAE,oDAAoD;YACnE,SAAS,EAAE,EAAE,EAAE,oDAAoD;YACnE,UAAU,EAAE,CAAC;YACb,UAAU,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE;SACpC,CAAC;QAEF,MAAM,KAAK,GAA+B;YACxC,EAAE,EAAE,QAAQ,IAAI,EAAE;YAClB,KAAK,EAAE,QAAQ;YACf,OAAO,EAAE,CAAC;YACV,SAAS,EAAE,GAAG;YACd,SAAS,EAAE,GAAG;YACd,cAAc,EAAE,GAAG;YACnB,WAAW,EAAE,CAAC;YACd,SAAS,EAAE,CAAC,GAAG,QAAQ,CAAC;YACxB,cAAc,EAAE,UAAU;YAC1B,GAAG,CAAC,GAAG,KAAK,SAAS,IAAI,EAAE,GAAG,EAAE,CAAC;YACjC,GAAG,CAAC,MAAM,CAAC,IAAI,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;YACzC,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;SAC3B,CAAC;QAEF,MAAM,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IACnC,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"writeSnapshot.js","sourceRoot":"","sources":["../../../../src/memory/causal/writeSnapshot.ts"],"names":[],"mappings":"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"}

package/dist/esm/memory/define.types.js

@@ -44,8 +44,8 @@
  * - `SEMANTIC`  — extracted structured facts, deduped on key
  * - `NARRATIVE` — beats / summaries of prior runs (append-only)
  * - `CAUSAL`    — footprintjs execution snapshots, the differentiator
- *                 (replays stored run outcomes for "why?" follow-ups;
- *                 operator-level decision-evidence wiring in progress)
+ *                 (replays stored decisions + tool evidence for "why?"
+ *                 follow-ups — harvested automatically per run)
  */
 export const MEMORY_TYPES = {
     EPISODIC: 'episodic',

package/dist/esm/memory/wire/mountMemoryPipeline.js

@@ -40,7 +40,11 @@ export function mountMemoryRead(builder, config) {
             // like `loadRelevant` derive the query from the last user
             // message here. The write-side `newMessages` field is empty
             // during read; these are two different concerns.
-            messages: parentState.messages ?? [],
+            // Agents carry the conversation as `history`; bare hosts may use
+            // `messages`. Without this fallback, read stages that derive the query
+            // from the last user message (loadSnapshot/loadRelevant) saw [] inside
+            // an Agent and silently injected nothing — the causal READ never fired.
+            messages: parentState.messages ?? parentState.history ?? [],
             newMessages: [], // write side unused in read subflow
         }),
         outputMapper: (subflowState) => ({
@@ -66,6 +70,11 @@ export function mountMemoryWrite(builder, config) {
             turnNumber: parentState[turnNumberKey],
             contextTokensRemaining: parentState[contextTokensKey] ?? 0,
             newMessages: parentState[newMessagesKey] ?? [],
+            // Evidence bridge (#5): harvested run evidence for causal writeSnapshot.
+            // Closure-delivered (no PARENT-scope write) — note it DOES land in the
+            // write subflow's own tracked scope/commit log, like newMessages; the
+            // values are already observable as events, so no new exposure class.
+            ...(config.evidenceSource && { runEvidence: config.evidenceSource() }),
         }),
         // No outputMapper — write has no parent-visible output.
     });

package/dist/esm/memory/wire/mountMemoryPipeline.js.map

@@ -1 +1 @@
-{"version":3,"file":"mountMemoryPipeline.js","sourceRoot":"","sources":["../../../../src/memory/wire/mountMemoryPipeline.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mountMemoryPipeline.js","sourceRoot":"","sources":["../../../../src/memory/wire/mountMemoryPipeline.ts"],"names":[],"mappings":"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"}

package/dist/memory/causal/evidenceRecorder.js

@@ -0,0 +1,217 @@
+"use strict";
+/**
+ * causalEvidenceRecorder — the evidence bridge (backlog Phase-1 #5).
+ *
+ * Harvests, DURING the run, everything a causal snapshot needs beyond
+ * (query, finalContent) — from events the engine already fires:
+ *
+ *   stream.tool_start/tool_end  → ToolCallRecord (name, args, resultPreview, errored)
+ *   stream.llm_end              → tokenUsage accumulation + iteration high-water
+ *   agent.turn_start/turn_end   → durationMs (+ authoritative totals when seen)
+ *   FlowRecorder.onDecision     → DecisionRecord with footprintjs decide()/select()
+ *                                 operator-level evidence (rule, conditions, chosen)
+ *   context.evaluated routing   → DecisionRecord per skill the graph routed to
+ *
+ * Pattern: CombinedRecorder (Convention 1 — single purpose: evidence
+ *          accumulation); per-turn reset anchored on `agent.turn_start`
+ *          (Convention 4 — executor `clear()` resets between runs; same-
+ *          executor pause/resume PRESERVES pre-pause evidence by design).
+ * PII note: tool args/results and decide() evidence persist into snapshots.
+ *          footprintjs `RedactionPolicy.emitPatterns` redacts the emit channel
+ *          BEFORE this recorder IF the consumer configures one on the executor
+ *          — the Agent does NOT configure one by default. Values are bounded
+ *          (`maxPreviewChars` for results, `maxFieldChars` for args/evidence);
+ *          treat the snapshot store as PII-bearing and protect it accordingly.
+ *
+ * The Agent attaches this automatically when a CAUSAL memory is mounted and
+ * threads `collect` into the memory write mount (`evidenceSource`) — so
+ * `writeSnapshot` persists real evidence instead of zeros.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.causalEvidenceRecorder = void 0;
+function preview(value, max) {
+    let s;
+    if (typeof value === 'string')
+        s = value;
+    else {
+        try {
+            s = JSON.stringify(value);
+        }
+        catch {
+            s = String(value);
+        }
+    }
+    return s.length > max ? `${s.slice(0, max)}…` : s;
+}
+/** Bound a record-ish value: oversized serializations become a truncated
+ *  preview marker so snapshots can't grow unbounded (and PII exposure is
+ *  capped). Small values pass through untouched. */
+function bounded(value, max) {
+    if (value === undefined)
+        return undefined;
+    try {
+        const s = JSON.stringify(value);
+        if (s.length <= max)
+            return value;
+        return { __truncated: `${s.slice(0, max)}…` };
+    }
+    catch {
+        return { __truncated: String(value).slice(0, max) };
+    }
+}
+/** Build the evidence-harvesting recorder. Attach via `.recorder(rec)` (the
+ *  Agent does this automatically for CAUSAL memories). */
+function causalEvidenceRecorder(options = {}) {
+    const maxPreview = options.maxPreviewChars ?? 200;
+    const maxField = options.maxFieldChars ?? 2000;
+    // ── per-turn accumulators (reset on agent.turn_start; executor clear()
+    //    resets between runs; pause/resume keeps pre-pause evidence) ──
+    let decisions = [];
+    let toolCalls = [];
+    let pendingTools = new Map();
+    let tokens = { input: 0, output: 0 };
+    let iterations = 0;
+    let turnStartMs;
+    let authoritative;
+    const reset = () => {
+        decisions = [];
+        toolCalls = [];
+        pendingTools = new Map();
+        tokens = { input: 0, output: 0 };
+        iterations = 0;
+        turnStartMs = undefined;
+        authoritative = undefined;
+    };
+    return {
+        id: options.id ?? 'causal-evidence',
+        onEmit(event) {
+            const { name, payload } = event;
+            switch (name) {
+                case 'agentfootprint.agent.turn_start':
+                    // A new turn on the same executor — start fresh (one snapshot per turn).
+                    reset();
+                    turnStartMs = Date.now();
+                    break;
+                case 'agentfootprint.stream.tool_start': {
+                    const id = String(payload.toolCallId ?? '');
+                    pendingTools.set(id, {
+                        name: String(payload.toolName ?? 'unknown'),
+                        args: bounded((payload.args ?? {}), maxField) ?? {},
+                    });
+                    break;
+                }
+                case 'agentfootprint.stream.tool_end': {
+                    const id = String(payload.toolCallId ?? '');
+                    const started = pendingTools.get(id);
+                    pendingTools.delete(id);
+                    toolCalls.push({
+                        name: started?.name ?? 'unknown',
+                        args: started?.args ?? {},
+                        resultPreview: preview(payload.result, maxPreview),
+                        errored: payload.error === true,
+                    });
+                    break;
+                }
+                case 'agentfootprint.stream.llm_end': {
+                    const usage = payload.usage;
+                    tokens = {
+                        input: tokens.input + (usage?.input ?? 0),
+                        output: tokens.output + (usage?.output ?? 0),
+                    };
+                    const iter = Number(payload.iteration ?? 0);
+                    if (iter > iterations)
+                        iterations = iter;
+                    break;
+                }
+                case 'agentfootprint.context.evaluated': {
+                    // Skill-graph routing provenance → one DecisionRecord per routed skill.
+                    const routing = payload.routing;
+                    if (Array.isArray(routing)) {
+                        for (const r of routing) {
+                            decisions.push({
+                                stageId: 'skill-graph',
+                                chosen: String(r.injectionId ?? r.id ?? 'unknown'),
+                                ...(r.label !== undefined || r.via !== undefined
+                                    ? { rule: r.label ?? `via ${r.via}` }
+                                    : {}),
+                                ...(r.path !== undefined && {
+                                    evidence: { path: r.path },
+                                }),
+                            });
+                        }
+                    }
+                    break;
+                }
+                case 'agentfootprint.agent.turn_end': {
+                    // Authoritative totals when the write runs after turn_end.
+                    authoritative = {
+                        iterations: Number(payload.iterationCount ?? iterations),
+                        input: Number(payload.totalInputTokens ?? tokens.input),
+                        output: Number(payload.totalOutputTokens ?? tokens.output),
+                        durationMs: Number(payload.durationMs ?? 0),
+                    };
+                    break;
+                }
+                default:
+                    break;
+            }
+        },
+        /** footprintjs FlowRecorder channel — decide() decision evidence.
+         *  FlowDecisionEvent carries `decider` (display name), `chosen`, optional
+         *  `evidence` from decide(), and `traversalContext.stageId` (the stable,
+         *  subflow-prefixed stage id — preferred for DecisionRecord.stageId). */
+        onDecision(event) {
+            const stageId = event.traversalContext?.stageId ?? event.decider;
+            // Internal agent plumbing (the cache-gate decider) is not domain
+            // decision evidence. `includes` (not startsWith): in reactMode
+            // 'dynamic-grouped' the names are double-prefixed
+            // ('sf-llm-call/sf-cache/…').
+            if (String(event.chosen ?? '').includes('sf-cache/') || String(stageId).includes('sf-cache'))
+                return;
+            const evidence = event.evidence;
+            decisions.push({
+                stageId: String(stageId),
+                chosen: String(event.chosen ?? 'unknown'),
+                ...(evidence?.label !== undefined || evidence?.rule !== undefined
+                    ? { rule: String(evidence.label ?? evidence.rule) }
+                    : {}),
+                ...(evidence !== undefined && {
+                    evidence: bounded(evidence, maxField),
+                }),
+            });
+        },
+        /** footprintjs FlowRecorder channel — select() selection evidence. */
+        onSelected(event) {
+            const stageId = event.traversalContext?.stageId ?? event.parent;
+            if (String(stageId).includes('sf-cache'))
+                return;
+            // The agent's own Context slot-fork is a selector — plumbing, not domain.
+            if (String(stageId).includes('context') && event.selected.every((s) => s.startsWith('sf-')))
+                return;
+            decisions.push({
+                stageId: String(stageId),
+                chosen: event.selected.join(', '),
+                ...(event.evidence !== undefined && {
+                    evidence: bounded(event.evidence, maxField),
+                }),
+            });
+        },
+        collect() {
+            return {
+                iterations: authoritative?.iterations ?? iterations,
+                decisions: [...decisions],
+                toolCalls: [...toolCalls],
+                durationMs: authoritative?.durationMs ?? (turnStartMs !== undefined ? Date.now() - turnStartMs : 0),
+                tokenUsage: {
+                    input: authoritative?.input ?? tokens.input,
+                    output: authoritative?.output ?? tokens.output,
+                },
+            };
+        },
+        clear() {
+            reset();
+        },
+    };
+}
+exports.causalEvidenceRecorder = causalEvidenceRecorder;
+//# sourceMappingURL=evidenceRecorder.js.map

package/dist/memory/causal/evidenceRecorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidenceRecorder.js","sourceRoot":"","sources":["../../../src/memory/causal/evidenceRecorder.ts"],"names":[],"mappings":"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"}

package/dist/memory/causal/index.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.snapshotPipeline = exports.loadSnapshot = exports.writeSnapshot = exports.DEFAULT_TOOL_RESULT_PREVIEW_LEN = void 0;
+exports.snapshotPipeline = exports.loadSnapshot = exports.writeSnapshot = exports.causalEvidenceRecorder = exports.DEFAULT_TOOL_RESULT_PREVIEW_LEN = void 0;
 var types_js_1 = require("./types.js");
 Object.defineProperty(exports, "DEFAULT_TOOL_RESULT_PREVIEW_LEN", { enumerable: true, get: function () { return types_js_1.DEFAULT_TOOL_RESULT_PREVIEW_LEN; } });
+var evidenceRecorder_js_1 = require("./evidenceRecorder.js");
+Object.defineProperty(exports, "causalEvidenceRecorder", { enumerable: true, get: function () { return evidenceRecorder_js_1.causalEvidenceRecorder; } });
 var writeSnapshot_js_1 = require("./writeSnapshot.js");
 Object.defineProperty(exports, "writeSnapshot", { enumerable: true, get: function () { return writeSnapshot_js_1.writeSnapshot; } });
 var loadSnapshot_js_1 = require("./loadSnapshot.js");

package/dist/memory/causal/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/memory/causal/index.ts"],"names":[],"mappings":";;;AAOA,uCAA6D;AAApD,2HAAA,+BAA+B,OAAA;AAExC,uDAA6E;AAApE,iHAAA,aAAa,OAAA;AACtB,qDAA0E;AAAjE,+GAAA,YAAY,OAAA;AACrB,6DAAsF;AAA7E,uHAAA,gBAAgB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/memory/causal/index.ts"],"names":[],"mappings":";;;AAOA,uCAA6D;AAApD,2HAAA,+BAA+B,OAAA;AAExC,6DAK+B;AAJ7B,6HAAA,sBAAsB,OAAA;AAKxB,uDAA6E;AAApE,iHAAA,aAAa,OAAA;AACtB,qDAA0E;AAAjE,+GAAA,YAAY,OAAA;AACrB,6DAAsF;AAA7E,uHAAA,gBAAgB,OAAA"}