agentfootprint 6.1.0 → 6.2.0

package/dist/esm/observe.js

@@ -50,6 +50,12 @@ export { permissionRecorder, } from './recorders/core/PermissionRecorder.js';
 export { skillRecorder } from './recorders/core/SkillRecorder.js';
 export { attachLogging, LoggingDomains, } from './recorders/observability/LoggingRecorder.js';
 export { attachStatus, } from './recorders/observability/StatusRecorder.js';
+// Tool→tool DATA-FLOW graph, derived by value provenance from the tool emit
+// stream (see finding 2: causalChain can't see LLM-mediated tool dependencies).
+export { toolLineageRecorder, } from './recorders/observability/ToolLineageRecorder.js';
+// AgentThinkingUI Trace (run → the "watch it think" beat list, collected during
+// traversal). Lets any agentfootprint run drive AgentThinkingUI / domain views.
+export { agentThinkingTrace, } from './recorders/observability/AgentThinkingTraceRecorder.js';
 // Emit primitive — used by every Tier-3 source-domain.
 export { typedEmit } from './recorders/core/typedEmit.js';
 //# sourceMappingURL=observe.js.map

package/dist/esm/observe.js.map

@@ -1 +1 @@
-{"version":3,"file":"observe.js","sourceRoot":"","sources":["../../src/observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,4BAA4B;AAC5B,OAAO,EAAE,eAAe,EAA+B,MAAM,qCAAqC,CAAC;AACnG,OAAO,EAAE,cAAc,EAA8B,MAAM,oCAAoC,CAAC;AAEhG,+BAA+B;AAC/B,OAAO,EACL,mBAAmB,GAEpB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,aAAa,EAA6B,MAAM,mCAAmC,CAAC;AAC7F,OAAO,EACL,gBAAgB,EAChB,gBAAgB,GAgBjB,MAAM,+CAA+C,CAAC;AACvD,OAAO,EACL,aAAa,EACb,eAAe,EACf,eAAe,GAQhB,MAAM,8CAA8C,CAAC;AACtD,OAAO,EACL,eAAe,EACf,cAAc,GAQf,MAAM,gDAAgD,CAAC;AACxD,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,oBAAoB,GAKrB,MAAM,gDAAgD,CAAC;AAExD,6BAA6B;AAC7B,OAAO,EAAE,YAAY,EAA4B,MAAM,kCAAkC,CAAC;AAC1F,OAAO,EAAE,aAAa,EAA6B,MAAM,mCAAmC,CAAC;AAC7F,OAAO,EACL,wBAAwB,GAEzB,MAAM,8CAA8C,CAAC;AACtD,OAAO,EAAE,YAAY,EAA4B,MAAM,kCAAkC,CAAC;AAC1F,OAAO,EAAE,cAAc,EAA8B,MAAM,oCAAoC,CAAC;AAChG,OAAO,EACL,kBAAkB,GAEnB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAAE,aAAa,EAA6B,MAAM,mCAAmC,CAAC;AAC7F,OAAO,EACL,aAAa,EACb,cAAc,GAIf,MAAM,8CAA8C,CAAC;AACtD,OAAO,EACL,YAAY,GAGb,MAAM,6CAA6C,CAAC;AAErD,uDAAuD;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC"}
+{"version":3,"file":"observe.js","sourceRoot":"","sources":["../../src/observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,4BAA4B;AAC5B,OAAO,EAAE,eAAe,EAA+B,MAAM,qCAAqC,CAAC;AACnG,OAAO,EAAE,cAAc,EAA8B,MAAM,oCAAoC,CAAC;AAEhG,+BAA+B;AAC/B,OAAO,EACL,mBAAmB,GAEpB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,aAAa,EAA6B,MAAM,mCAAmC,CAAC;AAC7F,OAAO,EACL,gBAAgB,EAChB,gBAAgB,GAgBjB,MAAM,+CAA+C,CAAC;AACvD,OAAO,EACL,aAAa,EACb,eAAe,EACf,eAAe,GAQhB,MAAM,8CAA8C,CAAC;AACtD,OAAO,EACL,eAAe,EACf,cAAc,GAQf,MAAM,gDAAgD,CAAC;AACxD,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,oBAAoB,GAKrB,MAAM,gDAAgD,CAAC;AAExD,6BAA6B;AAC7B,OAAO,EAAE,YAAY,EAA4B,MAAM,kCAAkC,CAAC;AAC1F,OAAO,EAAE,aAAa,EAA6B,MAAM,mCAAmC,CAAC;AAC7F,OAAO,EACL,wBAAwB,GAEzB,MAAM,8CAA8C,CAAC;AACtD,OAAO,EAAE,YAAY,EAA4B,MAAM,kCAAkC,CAAC;AAC1F,OAAO,EAAE,cAAc,EAA8B,MAAM,oCAAoC,CAAC;AAChG,OAAO,EACL,kBAAkB,GAEnB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAAE,aAAa,EAA6B,MAAM,mCAAmC,CAAC;AAC7F,OAAO,EACL,aAAa,EACb,cAAc,GAIf,MAAM,8CAA8C,CAAC;AACtD,OAAO,EACL,YAAY,GAGb,MAAM,6CAA6C,CAAC;AACrD,4EAA4E;AAC5E,gFAAgF;AAChF,OAAO,EACL,mBAAmB,GAMpB,MAAM,kDAAkD,CAAC;AAC1D,gFAAgF;AAChF,gFAAgF;AAChF,OAAO,EACL,kBAAkB,GAOnB,MAAM,yDAAyD,CAAC;AAEjE,uDAAuD;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/esm/recorders/observability/AgentThinkingTraceRecorder.js

@@ -0,0 +1,190 @@
+/**
+ * AgentThinkingTraceRecorder — produce an AgentThinkingUI `Trace` from a run.
+ *
+ * AgentThinkingUI (the "watch it think" player) consumes a framework-agnostic
+ * `Trace` — a list of beats: `prompt → ask → return → answer`, where a tool
+ * reply is `data` (reason) or an `instruction` (a skill that says how to act).
+ * This recorder builds that `Trace` from agentfootprint's emit stream AS THE RUN
+ * TRAVERSES (no post-processing) — so any agentfootprint agent gets the
+ * domain-expert view for free, and AgentThinkingUI stays vendor-agnostic (it
+ * just renders the `Trace` JSON, exactly as it renders the OTLP adapter's output).
+ *
+ * Mapping (from the events already on the stream):
+ *   stream.llm_end (toolCalls>0)  → the brain reasoned; content + usage become
+ *                                   the upcoming ask's `brain` + `cost`.
+ *   stream.llm_end (toolCalls==0) → the final `answer`.
+ *   stream.tool_start             → `ask`  (read_skill → reaching for a skill).
+ *   stream.tool_end               → `return` (read_skill → replyType:'instruction'
+ *                                   + skill; any other tool → replyType:'data').
+ *
+ * Commentary (each beat's `brain`): filled from agentfootprint's OWN commentary
+ * engine — the SAME `selectCommentaryKey`/`extractCommentaryVars`/`renderCommentary`
+ * the Lens uses — so AgentThinkingUI's Notepad / bottom caption read identically
+ * to the Lens commentary panel (one engine, consumer-overridable via
+ * `commentaryTemplates`). The LLM's own reasoning still wins on the first ask of
+ * an iteration; the engine fills every other beat so no line is ever blank.
+ *
+ * Convention 1 (one purpose) + Convention 4 (run-scoped — resets per run).
+ */
+import { defaultCommentaryTemplates, selectCommentaryKey, extractCommentaryVars, renderCommentary, } from './commentary/commentaryTemplates.js';
+const LLM_END = 'agentfootprint.stream.llm_end';
+const TOOL_START = 'agentfootprint.stream.tool_start';
+const TOOL_END = 'agentfootprint.stream.tool_end';
+function asObject(x) {
+    if (x != null && typeof x === 'object' && !Array.isArray(x))
+        return x;
+    return { value: x };
+}
+function headlineOf(s) {
+    const line = (s ?? '').split('\n').find((l) => l.trim().length > 0) ?? '';
+    return line.length > 140 ? line.slice(0, 140) + '…' : line || 'Done';
+}
+/** `EmitEvent.subflowPath` may arrive as a `/`-joined string or already split;
+ *  normalize to the array shape the commentary engine's `extractAgentName` reads. */
+function splitPath(p) {
+    if (Array.isArray(p))
+        return p;
+    if (typeof p === 'string' && p.length > 0)
+        return p.split('/');
+    return [];
+}
+export function agentThinkingTrace(options = {}) {
+    let lastPipelineId;
+    let task = '';
+    let steps = [];
+    // The most recent reasoning + its cost, awaiting the iteration's ask step(s).
+    let pendingBrain = '';
+    let pendingCost = { ms: 0, tokens: 0 };
+    let pendingCostUsed = false;
+    const byId = new Map();
+    // Commentary engine — the SAME one the Lens uses. Merged once: consumer
+    // overrides spread over the bundled defaults.
+    const templates = options.commentaryTemplates
+        ? { ...defaultCommentaryTemplates, ...options.commentaryTemplates }
+        : defaultCommentaryTemplates;
+    const appName = options.agent ?? 'Agent';
+    /** Narrate one emit event into a prose `brain` line via agentfootprint's
+     *  commentary engine. The raw `EmitEvent` is adapted to the typed
+     *  `AgentfootprintEvent` shape the engine reads (`type`/`payload`/`meta`).
+     *  Returns '' for events the engine deliberately skips. */
+    function narrate(e) {
+        const ev = {
+            type: e.name,
+            payload: e.payload,
+            meta: { subflowPath: splitPath(e.subflowPath) },
+        };
+        const key = selectCommentaryKey(ev);
+        if (!key)
+            return '';
+        const vars = extractCommentaryVars(ev, { appName }, templates);
+        return renderCommentary(templates[key] ?? '', vars);
+    }
+    function reset() {
+        task = '';
+        steps = [];
+        pendingBrain = '';
+        pendingCost = { ms: 0, tokens: 0 };
+        pendingCostUsed = false;
+        byId.clear();
+    }
+    return {
+        id: options.id ?? 'agent-thinking-trace',
+        onEmit(e) {
+            if (lastPipelineId !== undefined && e.pipelineId !== lastPipelineId)
+                reset();
+            lastPipelineId = e.pipelineId;
+            if (e.name === LLM_END) {
+                const p = e.payload;
+                const cost = {
+                    ms: p.durationMs ?? 0,
+                    tokens: (p.usage?.input ?? 0) + (p.usage?.output ?? 0),
+                    tokensIn: p.usage?.input,
+                    tokensOut: p.usage?.output,
+                    tokensCached: p.usage?.cacheRead,
+                };
+                if ((p.toolCallCount ?? 0) === 0) {
+                    // No tool calls → this is the final answer.
+                    const content = p.content ?? '';
+                    steps.push({
+                        kind: 'answer',
+                        to: options.asker ?? 'you',
+                        brain: content,
+                        answer: { headline: headlineOf(content), text: content },
+                        cost,
+                    });
+                }
+                else {
+                    // Reasoning that will drive the upcoming ask step(s) this iteration.
+                    pendingBrain = p.content ?? '';
+                    pendingCost = cost;
+                    pendingCostUsed = false;
+                }
+                return;
+            }
+            if (e.name === TOOL_START) {
+                const p = e.payload;
+                if (!p?.toolCallId)
+                    return;
+                const isSkill = p.toolName === 'read_skill';
+                const skillId = isSkill
+                    ? p.args?.id ?? undefined
+                    : undefined;
+                byId.set(p.toolCallId, { toolName: p.toolName ?? '(tool)', isSkill, skillId });
+                steps.push({
+                    kind: 'ask',
+                    tool: isSkill ? skillId ?? 'skill' : p.toolName ?? '(tool)',
+                    toolName: p.toolName,
+                    input: asObject(p.args),
+                    // First ask of the iteration carries the LLM's own reasoning; later
+                    // asks (and the reasoning-less ones) fall back to engine commentary so
+                    // the Notepad never shows a blank line.
+                    brain: pendingCostUsed ? narrate(e) : pendingBrain || narrate(e),
+                    cost: pendingCostUsed ? { ms: 0, tokens: 0 } : pendingCost, // attribute the LLM cost to the first ask of the iteration
+                });
+                pendingCostUsed = true;
+                return;
+            }
+            if (e.name === TOOL_END) {
+                const p = e.payload;
+                const started = p?.toolCallId ? byId.get(p.toolCallId) : undefined;
+                if (!started)
+                    return;
+                byId.delete(p.toolCallId);
+                steps.push({
+                    kind: 'return',
+                    tool: started.isSkill ? started.skillId ?? 'skill' : started.toolName,
+                    toolName: started.toolName,
+                    replyType: started.isSkill ? 'instruction' : 'data',
+                    output: asObject(p.result),
+                    // The tool-result beat has no LLM reasoning of its own — narrate the
+                    // mechanics via the commentary engine (matches the Lens).
+                    brain: narrate(e),
+                    brainMode: started.isSkill ? 'act' : 'reason',
+                    ...(started.isSkill && started.skillId ? { skill: started.skillId } : {}),
+                    cost: { ms: p.durationMs ?? 0, tokens: 0 },
+                    ...(p.error ? { error: 'tool failed' } : {}),
+                });
+            }
+        },
+        getTrace(overrides = {}) {
+            const prompt = {
+                kind: 'prompt',
+                brain: overrides.task ?? task,
+                cost: { ms: 0, tokens: 0 },
+            };
+            return {
+                task: overrides.task ?? task,
+                ...(overrides.title ? { title: overrides.title } : {}),
+                agent: overrides.agent ?? options.agent ?? 'Agent',
+                model: overrides.model ?? options.model ?? 'model',
+                asker: overrides.asker ?? options.asker ?? 'you',
+                steps: [prompt, ...steps],
+            };
+        },
+        clear() {
+            reset();
+            lastPipelineId = undefined;
+        },
+    };
+}
+//# sourceMappingURL=AgentThinkingTraceRecorder.js.map

package/dist/esm/recorders/observability/AgentThinkingTraceRecorder.js.map

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

package/dist/esm/recorders/observability/ToolLineageRecorder.js.map

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

package/dist/observe.js

@@ -32,7 +32,7 @@
  * directly; Tier 3 dashboards are opt-in.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.typedEmit = exports.attachStatus = exports.LoggingDomains = exports.attachLogging = exports.skillRecorder = exports.permissionRecorder = exports.memoryRecorder = exports.evalRecorder = exports.contextEvaluatedRecorder = exports.toolsRecorder = exports.costRecorder = exports.LiveAgentTurnTracker = exports.LiveToolTracker = exports.LiveLLMTracker = exports.LiveStateRecorder = exports.liveStateRecorder = exports.buildStepGraph = exports.attachFlowchart = exports.runStepRecorder = exports.RunStepRecorder = exports.buildRunSteps = exports.BoundaryRecorder = exports.boundaryRecorder = exports.agentRecorder = exports.compositionRecorder = exports.streamRecorder = exports.ContextRecorder = void 0;
+exports.typedEmit = exports.agentThinkingTrace = exports.toolLineageRecorder = exports.attachStatus = exports.LoggingDomains = exports.attachLogging = exports.skillRecorder = exports.permissionRecorder = exports.memoryRecorder = exports.evalRecorder = exports.contextEvaluatedRecorder = exports.toolsRecorder = exports.costRecorder = exports.LiveAgentTurnTracker = exports.LiveToolTracker = exports.LiveLLMTracker = exports.LiveStateRecorder = exports.liveStateRecorder = exports.buildStepGraph = exports.attachFlowchart = exports.runStepRecorder = exports.RunStepRecorder = exports.buildRunSteps = exports.BoundaryRecorder = exports.boundaryRecorder = exports.agentRecorder = exports.compositionRecorder = exports.streamRecorder = exports.ContextRecorder = void 0;
 // Tier 1 — context + stream
 var ContextRecorder_js_1 = require("./recorders/core/ContextRecorder.js");
 Object.defineProperty(exports, "ContextRecorder", { enumerable: true, get: function () { return ContextRecorder_js_1.ContextRecorder; } });
@@ -79,6 +79,14 @@ Object.defineProperty(exports, "attachLogging", { enumerable: true, get: functio
 Object.defineProperty(exports, "LoggingDomains", { enumerable: true, get: function () { return LoggingRecorder_js_1.LoggingDomains; } });
 var StatusRecorder_js_1 = require("./recorders/observability/StatusRecorder.js");
 Object.defineProperty(exports, "attachStatus", { enumerable: true, get: function () { return StatusRecorder_js_1.attachStatus; } });
+// Tool→tool DATA-FLOW graph, derived by value provenance from the tool emit
+// stream (see finding 2: causalChain can't see LLM-mediated tool dependencies).
+var ToolLineageRecorder_js_1 = require("./recorders/observability/ToolLineageRecorder.js");
+Object.defineProperty(exports, "toolLineageRecorder", { enumerable: true, get: function () { return ToolLineageRecorder_js_1.toolLineageRecorder; } });
+// AgentThinkingUI Trace (run → the "watch it think" beat list, collected during
+// traversal). Lets any agentfootprint run drive AgentThinkingUI / domain views.
+var AgentThinkingTraceRecorder_js_1 = require("./recorders/observability/AgentThinkingTraceRecorder.js");
+Object.defineProperty(exports, "agentThinkingTrace", { enumerable: true, get: function () { return AgentThinkingTraceRecorder_js_1.agentThinkingTrace; } });
 // Emit primitive — used by every Tier-3 source-domain.
 var typedEmit_js_1 = require("./recorders/core/typedEmit.js");
 Object.defineProperty(exports, "typedEmit", { enumerable: true, get: function () { return typedEmit_js_1.typedEmit; } });

package/dist/observe.js.map

@@ -1 +1 @@
-{"version":3,"file":"observe.js","sourceRoot":"","sources":["../src/observe.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;;;AAEH,4BAA4B;AAC5B,0EAAmG;AAA1F,qHAAA,eAAe,OAAA;AACxB,wEAAgG;AAAvF,mHAAA,cAAc,OAAA;AAEvB,+BAA+B;AAC/B,kFAGiD;AAF/C,6HAAA,mBAAmB,OAAA;AAGrB,sEAA6F;AAApF,iHAAA,aAAa,OAAA;AACtB,qFAkBuD;AAjBrD,uHAAA,gBAAgB,OAAA;AAChB,uHAAA,gBAAgB,OAAA;AAiBlB,mFAWsD;AAVpD,mHAAA,aAAa,OAAA;AACb,qHAAA,eAAe,OAAA;AACf,qHAAA,eAAe,OAAA;AASjB,uFAUwD;AATtD,uHAAA,eAAe,OAAA;AACf,sHAAA,cAAc,OAAA;AAShB,uFAUwD;AATtD,yHAAA,iBAAiB,OAAA;AACjB,yHAAA,iBAAiB,OAAA;AACjB,sHAAA,cAAc,OAAA;AACd,uHAAA,eAAe,OAAA;AACf,4HAAA,oBAAoB,OAAA;AAOtB,6BAA6B;AAC7B,oEAA0F;AAAjF,+GAAA,YAAY,OAAA;AACrB,sEAA6F;AAApF,iHAAA,aAAa,OAAA;AACtB,4FAGsD;AAFpD,uIAAA,wBAAwB,OAAA;AAG1B,oEAA0F;AAAjF,+GAAA,YAAY,OAAA;AACrB,wEAAgG;AAAvF,mHAAA,cAAc,OAAA;AACvB,gFAGgD;AAF9C,2HAAA,kBAAkB,OAAA;AAGpB,sEAA6F;AAApF,iHAAA,aAAa,OAAA;AACtB,mFAMsD;AALpD,mHAAA,aAAa,OAAA;AACb,oHAAA,cAAc,OAAA;AAKhB,iFAIqD;AAHnD,iHAAA,YAAY,OAAA;AAKd,uDAAuD;AACvD,8DAA0D;AAAjD,yGAAA,SAAS,OAAA"}
+{"version":3,"file":"observe.js","sourceRoot":"","sources":["../src/observe.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;;;AAEH,4BAA4B;AAC5B,0EAAmG;AAA1F,qHAAA,eAAe,OAAA;AACxB,wEAAgG;AAAvF,mHAAA,cAAc,OAAA;AAEvB,+BAA+B;AAC/B,kFAGiD;AAF/C,6HAAA,mBAAmB,OAAA;AAGrB,sEAA6F;AAApF,iHAAA,aAAa,OAAA;AACtB,qFAkBuD;AAjBrD,uHAAA,gBAAgB,OAAA;AAChB,uHAAA,gBAAgB,OAAA;AAiBlB,mFAWsD;AAVpD,mHAAA,aAAa,OAAA;AACb,qHAAA,eAAe,OAAA;AACf,qHAAA,eAAe,OAAA;AASjB,uFAUwD;AATtD,uHAAA,eAAe,OAAA;AACf,sHAAA,cAAc,OAAA;AAShB,uFAUwD;AATtD,yHAAA,iBAAiB,OAAA;AACjB,yHAAA,iBAAiB,OAAA;AACjB,sHAAA,cAAc,OAAA;AACd,uHAAA,eAAe,OAAA;AACf,4HAAA,oBAAoB,OAAA;AAOtB,6BAA6B;AAC7B,oEAA0F;AAAjF,+GAAA,YAAY,OAAA;AACrB,sEAA6F;AAApF,iHAAA,aAAa,OAAA;AACtB,4FAGsD;AAFpD,uIAAA,wBAAwB,OAAA;AAG1B,oEAA0F;AAAjF,+GAAA,YAAY,OAAA;AACrB,wEAAgG;AAAvF,mHAAA,cAAc,OAAA;AACvB,gFAGgD;AAF9C,2HAAA,kBAAkB,OAAA;AAGpB,sEAA6F;AAApF,iHAAA,aAAa,OAAA;AACtB,mFAMsD;AALpD,mHAAA,aAAa,OAAA;AACb,oHAAA,cAAc,OAAA;AAKhB,iFAIqD;AAHnD,iHAAA,YAAY,OAAA;AAId,4EAA4E;AAC5E,gFAAgF;AAChF,2FAO0D;AANxD,6HAAA,mBAAmB,OAAA;AAOrB,gFAAgF;AAChF,gFAAgF;AAChF,yGAQiE;AAP/D,mIAAA,kBAAkB,OAAA;AASpB,uDAAuD;AACvD,8DAA0D;AAAjD,yGAAA,SAAS,OAAA"}

package/dist/recorders/observability/AgentThinkingTraceRecorder.js

@@ -0,0 +1,194 @@
+"use strict";
+/**
+ * AgentThinkingTraceRecorder — produce an AgentThinkingUI `Trace` from a run.
+ *
+ * AgentThinkingUI (the "watch it think" player) consumes a framework-agnostic
+ * `Trace` — a list of beats: `prompt → ask → return → answer`, where a tool
+ * reply is `data` (reason) or an `instruction` (a skill that says how to act).
+ * This recorder builds that `Trace` from agentfootprint's emit stream AS THE RUN
+ * TRAVERSES (no post-processing) — so any agentfootprint agent gets the
+ * domain-expert view for free, and AgentThinkingUI stays vendor-agnostic (it
+ * just renders the `Trace` JSON, exactly as it renders the OTLP adapter's output).
+ *
+ * Mapping (from the events already on the stream):
+ *   stream.llm_end (toolCalls>0)  → the brain reasoned; content + usage become
+ *                                   the upcoming ask's `brain` + `cost`.
+ *   stream.llm_end (toolCalls==0) → the final `answer`.
+ *   stream.tool_start             → `ask`  (read_skill → reaching for a skill).
+ *   stream.tool_end               → `return` (read_skill → replyType:'instruction'
+ *                                   + skill; any other tool → replyType:'data').
+ *
+ * Commentary (each beat's `brain`): filled from agentfootprint's OWN commentary
+ * engine — the SAME `selectCommentaryKey`/`extractCommentaryVars`/`renderCommentary`
+ * the Lens uses — so AgentThinkingUI's Notepad / bottom caption read identically
+ * to the Lens commentary panel (one engine, consumer-overridable via
+ * `commentaryTemplates`). The LLM's own reasoning still wins on the first ask of
+ * an iteration; the engine fills every other beat so no line is ever blank.
+ *
+ * Convention 1 (one purpose) + Convention 4 (run-scoped — resets per run).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentThinkingTrace = void 0;
+const commentaryTemplates_js_1 = require("./commentary/commentaryTemplates.js");
+const LLM_END = 'agentfootprint.stream.llm_end';
+const TOOL_START = 'agentfootprint.stream.tool_start';
+const TOOL_END = 'agentfootprint.stream.tool_end';
+function asObject(x) {
+    if (x != null && typeof x === 'object' && !Array.isArray(x))
+        return x;
+    return { value: x };
+}
+function headlineOf(s) {
+    const line = (s ?? '').split('\n').find((l) => l.trim().length > 0) ?? '';
+    return line.length > 140 ? line.slice(0, 140) + '…' : line || 'Done';
+}
+/** `EmitEvent.subflowPath` may arrive as a `/`-joined string or already split;
+ *  normalize to the array shape the commentary engine's `extractAgentName` reads. */
+function splitPath(p) {
+    if (Array.isArray(p))
+        return p;
+    if (typeof p === 'string' && p.length > 0)
+        return p.split('/');
+    return [];
+}
+function agentThinkingTrace(options = {}) {
+    let lastPipelineId;
+    let task = '';
+    let steps = [];
+    // The most recent reasoning + its cost, awaiting the iteration's ask step(s).
+    let pendingBrain = '';
+    let pendingCost = { ms: 0, tokens: 0 };
+    let pendingCostUsed = false;
+    const byId = new Map();
+    // Commentary engine — the SAME one the Lens uses. Merged once: consumer
+    // overrides spread over the bundled defaults.
+    const templates = options.commentaryTemplates
+        ? { ...commentaryTemplates_js_1.defaultCommentaryTemplates, ...options.commentaryTemplates }
+        : commentaryTemplates_js_1.defaultCommentaryTemplates;
+    const appName = options.agent ?? 'Agent';
+    /** Narrate one emit event into a prose `brain` line via agentfootprint's
+     *  commentary engine. The raw `EmitEvent` is adapted to the typed
+     *  `AgentfootprintEvent` shape the engine reads (`type`/`payload`/`meta`).
+     *  Returns '' for events the engine deliberately skips. */
+    function narrate(e) {
+        const ev = {
+            type: e.name,
+            payload: e.payload,
+            meta: { subflowPath: splitPath(e.subflowPath) },
+        };
+        const key = (0, commentaryTemplates_js_1.selectCommentaryKey)(ev);
+        if (!key)
+            return '';
+        const vars = (0, commentaryTemplates_js_1.extractCommentaryVars)(ev, { appName }, templates);
+        return (0, commentaryTemplates_js_1.renderCommentary)(templates[key] ?? '', vars);
+    }
+    function reset() {
+        task = '';
+        steps = [];
+        pendingBrain = '';
+        pendingCost = { ms: 0, tokens: 0 };
+        pendingCostUsed = false;
+        byId.clear();
+    }
+    return {
+        id: options.id ?? 'agent-thinking-trace',
+        onEmit(e) {
+            if (lastPipelineId !== undefined && e.pipelineId !== lastPipelineId)
+                reset();
+            lastPipelineId = e.pipelineId;
+            if (e.name === LLM_END) {
+                const p = e.payload;
+                const cost = {
+                    ms: p.durationMs ?? 0,
+                    tokens: (p.usage?.input ?? 0) + (p.usage?.output ?? 0),
+                    tokensIn: p.usage?.input,
+                    tokensOut: p.usage?.output,
+                    tokensCached: p.usage?.cacheRead,
+                };
+                if ((p.toolCallCount ?? 0) === 0) {
+                    // No tool calls → this is the final answer.
+                    const content = p.content ?? '';
+                    steps.push({
+                        kind: 'answer',
+                        to: options.asker ?? 'you',
+                        brain: content,
+                        answer: { headline: headlineOf(content), text: content },
+                        cost,
+                    });
+                }
+                else {
+                    // Reasoning that will drive the upcoming ask step(s) this iteration.
+                    pendingBrain = p.content ?? '';
+                    pendingCost = cost;
+                    pendingCostUsed = false;
+                }
+                return;
+            }
+            if (e.name === TOOL_START) {
+                const p = e.payload;
+                if (!p?.toolCallId)
+                    return;
+                const isSkill = p.toolName === 'read_skill';
+                const skillId = isSkill
+                    ? p.args?.id ?? undefined
+                    : undefined;
+                byId.set(p.toolCallId, { toolName: p.toolName ?? '(tool)', isSkill, skillId });
+                steps.push({
+                    kind: 'ask',
+                    tool: isSkill ? skillId ?? 'skill' : p.toolName ?? '(tool)',
+                    toolName: p.toolName,
+                    input: asObject(p.args),
+                    // First ask of the iteration carries the LLM's own reasoning; later
+                    // asks (and the reasoning-less ones) fall back to engine commentary so
+                    // the Notepad never shows a blank line.
+                    brain: pendingCostUsed ? narrate(e) : pendingBrain || narrate(e),
+                    cost: pendingCostUsed ? { ms: 0, tokens: 0 } : pendingCost, // attribute the LLM cost to the first ask of the iteration
+                });
+                pendingCostUsed = true;
+                return;
+            }
+            if (e.name === TOOL_END) {
+                const p = e.payload;
+                const started = p?.toolCallId ? byId.get(p.toolCallId) : undefined;
+                if (!started)
+                    return;
+                byId.delete(p.toolCallId);
+                steps.push({
+                    kind: 'return',
+                    tool: started.isSkill ? started.skillId ?? 'skill' : started.toolName,
+                    toolName: started.toolName,
+                    replyType: started.isSkill ? 'instruction' : 'data',
+                    output: asObject(p.result),
+                    // The tool-result beat has no LLM reasoning of its own — narrate the
+                    // mechanics via the commentary engine (matches the Lens).
+                    brain: narrate(e),
+                    brainMode: started.isSkill ? 'act' : 'reason',
+                    ...(started.isSkill && started.skillId ? { skill: started.skillId } : {}),
+                    cost: { ms: p.durationMs ?? 0, tokens: 0 },
+                    ...(p.error ? { error: 'tool failed' } : {}),
+                });
+            }
+        },
+        getTrace(overrides = {}) {
+            const prompt = {
+                kind: 'prompt',
+                brain: overrides.task ?? task,
+                cost: { ms: 0, tokens: 0 },
+            };
+            return {
+                task: overrides.task ?? task,
+                ...(overrides.title ? { title: overrides.title } : {}),
+                agent: overrides.agent ?? options.agent ?? 'Agent',
+                model: overrides.model ?? options.model ?? 'model',
+                asker: overrides.asker ?? options.asker ?? 'you',
+                steps: [prompt, ...steps],
+            };
+        },
+        clear() {
+            reset();
+            lastPipelineId = undefined;
+        },
+    };
+}
+exports.agentThinkingTrace = agentThinkingTrace;
+//# sourceMappingURL=AgentThinkingTraceRecorder.js.map

package/dist/recorders/observability/AgentThinkingTraceRecorder.js.map

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

package/dist/recorders/observability/ToolLineageRecorder.js.map

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

package/dist/types/observe.d.ts

@@ -47,5 +47,7 @@ export { permissionRecorder, type PermissionRecorderOptions, } from './recorders
 export { skillRecorder, type SkillRecorderOptions } from './recorders/core/SkillRecorder.js';
 export { attachLogging, LoggingDomains, type LoggingLogger, type LoggingDomain, type LoggingOptions, } from './recorders/observability/LoggingRecorder.js';
 export { attachStatus, type StatusEvent, type StatusOptions, } from './recorders/observability/StatusRecorder.js';
+export { toolLineageRecorder, type ToolLineageRecorderHandle, type ToolLineageOptions, type ToolLineageGraph, type ToolLineageEdge, type ToolCallRef, } from './recorders/observability/ToolLineageRecorder.js';
+export { agentThinkingTrace, type AgentThinkingTraceHandle, type AgentThinkingTraceOptions, type AttTrace, type AttStep, type AttCost, type AttAnswer, } from './recorders/observability/AgentThinkingTraceRecorder.js';
 export { typedEmit } from './recorders/core/typedEmit.js';
 //# sourceMappingURL=observe.d.ts.map

package/dist/types/observe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAGH,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AACnG,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAGhG,OAAO,EACL,mBAAmB,EACnB,KAAK,0BAA0B,GAChC,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAC7F,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,EACvB,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,EAC9B,KAAK,WAAW,EAChB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,GACxB,MAAM,+CAA+C,CAAC;AACvD,OAAO,EACL,aAAa,EACb,eAAe,EACf,eAAe,EACf,KAAK,oBAAoB,EACzB,KAAK,OAAO,EACZ,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,GACvB,MAAM,8CAA8C,CAAC;AACtD,OAAO,EACL,eAAe,EACf,cAAc,EACd,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,gDAAgD,CAAC;AACxD,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,oBAAoB,EACpB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,gDAAgD,CAAC;AAGxD,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAC1F,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAC7F,OAAO,EACL,wBAAwB,EACxB,KAAK,+BAA+B,GACrC,MAAM,8CAA8C,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAC1F,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAChG,OAAO,EACL,kBAAkB,EAClB,KAAK,yBAAyB,GAC/B,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAC7F,OAAO,EACL,aAAa,EACb,cAAc,EACd,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,cAAc,GACpB,MAAM,8CAA8C,CAAC;AACtD,OAAO,EACL,YAAY,EACZ,KAAK,WAAW,EAChB,KAAK,aAAa,GACnB,MAAM,6CAA6C,CAAC;AAGrD,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC"}
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/observe.ts"],"names":[],"mappings":"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"}

package/dist/types/recorders/observability/AgentThinkingTraceRecorder.d.ts

@@ -0,0 +1,101 @@
+/**
+ * AgentThinkingTraceRecorder — produce an AgentThinkingUI `Trace` from a run.
+ *
+ * AgentThinkingUI (the "watch it think" player) consumes a framework-agnostic
+ * `Trace` — a list of beats: `prompt → ask → return → answer`, where a tool
+ * reply is `data` (reason) or an `instruction` (a skill that says how to act).
+ * This recorder builds that `Trace` from agentfootprint's emit stream AS THE RUN
+ * TRAVERSES (no post-processing) — so any agentfootprint agent gets the
+ * domain-expert view for free, and AgentThinkingUI stays vendor-agnostic (it
+ * just renders the `Trace` JSON, exactly as it renders the OTLP adapter's output).
+ *
+ * Mapping (from the events already on the stream):
+ *   stream.llm_end (toolCalls>0)  → the brain reasoned; content + usage become
+ *                                   the upcoming ask's `brain` + `cost`.
+ *   stream.llm_end (toolCalls==0) → the final `answer`.
+ *   stream.tool_start             → `ask`  (read_skill → reaching for a skill).
+ *   stream.tool_end               → `return` (read_skill → replyType:'instruction'
+ *                                   + skill; any other tool → replyType:'data').
+ *
+ * Commentary (each beat's `brain`): filled from agentfootprint's OWN commentary
+ * engine — the SAME `selectCommentaryKey`/`extractCommentaryVars`/`renderCommentary`
+ * the Lens uses — so AgentThinkingUI's Notepad / bottom caption read identically
+ * to the Lens commentary panel (one engine, consumer-overridable via
+ * `commentaryTemplates`). The LLM's own reasoning still wins on the first ask of
+ * an iteration; the engine fills every other beat so no line is ever blank.
+ *
+ * Convention 1 (one purpose) + Convention 4 (run-scoped — resets per run).
+ */
+import type { EmitRecorder } from 'footprintjs';
+import { type CommentaryTemplates } from './commentary/commentaryTemplates.js';
+export interface AttCost {
+    ms: number;
+    tokens: number;
+    tokensIn?: number;
+    tokensOut?: number;
+    tokensCached?: number;
+}
+export interface AttAnswer {
+    headline: string;
+    [key: string]: unknown;
+}
+export type AttStep = {
+    kind: 'prompt';
+    brain: string;
+    cost: AttCost;
+} | {
+    kind: 'ask';
+    tool: string;
+    toolName?: string;
+    input: Record<string, unknown>;
+    brain: string;
+    cost: AttCost;
+} | {
+    kind: 'return';
+    tool: string;
+    toolName?: string;
+    replyType: 'data' | 'instruction' | 'both';
+    output: Record<string, unknown>;
+    brain: string;
+    cost: AttCost;
+    brainMode?: 'reason' | 'act';
+    skill?: string;
+    error?: string;
+} | {
+    kind: 'answer';
+    to: string;
+    brain: string;
+    answer: AttAnswer;
+    cost: AttCost;
+    error?: string;
+};
+export interface AttTrace {
+    task: string;
+    title?: string;
+    agent: string;
+    model: string;
+    asker: string;
+    steps: AttStep[];
+}
+export interface AgentThinkingTraceOptions {
+    readonly id?: string;
+    readonly agent?: string;
+    readonly model?: string;
+    readonly asker?: string;
+    /**
+     * Override agentfootprint's bundled commentary templates — the SAME shape as
+     * the Lens's `commentaryTemplates` prop (partial; spread over the defaults).
+     * Drives each beat's `brain` narration, so AgentThinkingUI's Notepad / bottom
+     * caption read like the Lens commentary panel — one engine, one voice,
+     * consumer-overridable. Omit to use the bundled English defaults.
+     */
+    readonly commentaryTemplates?: Partial<CommentaryTemplates>;
+}
+export interface AgentThinkingTraceHandle extends EmitRecorder {
+    /** The AgentThinkingUI `Trace` for the run so far. `task` (the headline of the
+     *  replay pill) defaults to the captured user message; override any field. */
+    getTrace(overrides?: Partial<Pick<AttTrace, 'task' | 'title' | 'agent' | 'model' | 'asker'>>): AttTrace;
+    clear(): void;
+}
+export declare function agentThinkingTrace(options?: AgentThinkingTraceOptions): AgentThinkingTraceHandle;
+//# sourceMappingURL=AgentThinkingTraceRecorder.d.ts.map

package/dist/types/recorders/observability/AgentThinkingTraceRecorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentThinkingTraceRecorder.d.ts","sourceRoot":"","sources":["../../../../src/recorders/observability/AgentThinkingTraceRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAa,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3D,OAAO,EAKL,KAAK,mBAAmB,EACzB,MAAM,qCAAqC,CAAC;AAI7C,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AACD,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AACD,MAAM,MAAM,OAAO,GACf;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAChD;IACE,IAAI,EAAE,KAAK,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;CACf,GACD;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,aAAa,GAAG,MAAM,CAAC;IAC3C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,CAAC,EAAE,QAAQ,GAAG,KAAK,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GACD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AACpG,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;OAMG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAC7D;AAED,MAAM,WAAW,wBAAyB,SAAQ,YAAY;IAC5D;kFAC8E;IAC9E,QAAQ,CACN,SAAS,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC,CAAC,GAClF,QAAQ,CAAC;IACZ,KAAK,IAAI,IAAI,CAAC;CACf;AAsBD,wBAAgB,kBAAkB,CAChC,OAAO,GAAE,yBAA8B,GACtC,wBAAwB,CAyJ1B"}

package/dist/types/recorders/observability/ToolLineageRecorder.d.ts

@@ -0,0 +1,72 @@
+/**
+ * ToolLineageRecorder — derives the tool→tool DATA-FLOW graph of a run.
+ *
+ * Why this exists: in a ReAct agent a tool's output flows back to the LLM as
+ * text, and the LLM decides the NEXT tool's arguments — so the data dependency
+ * between tools (e.g. FLOGI's FCID reused as io_profile's `initiator_id`) never
+ * touches footprintjs's shared scope, and `causalChain` can't reconstruct it.
+ * This recorder rebuilds that graph from the tool emit stream by VALUE
+ * PROVENANCE: when a tool call's argument value equals a distinctive value
+ * produced by an EARLIER iteration's tool result, it records an edge
+ * (producer → consumer).
+ *
+ * It is a HEURISTIC, not ground truth — it matches by value, so it is accurate
+ * for distinctive identifiers (FCIDs, WWPNs, ids, NAAs, hostnames) and
+ * deliberately conservative:
+ *   - short / common values (below `minValueLength`) are ignored,
+ *   - numbers are ignored by default (coincidental matches are likely),
+ *   - same-iteration (parallel) tool calls never link to each other — the LLM
+ *     chose all their args from the same prior context, before any of them ran.
+ *
+ * No core changes: it consumes the existing `agentfootprint.stream.tool_start`
+ * (args) and `agentfootprint.stream.tool_end` (result) emits. Attach via
+ * `.recorder(toolLineageRecorder())` and read `getLineage()` after the run; the
+ * lens (or any consumer) can render the returned graph.
+ *
+ * Convention 1 — one purpose: it derives ONE artifact (the lineage graph) from
+ * the emit channel. Convention 4 — run-scoped: it resets when a new run starts
+ * (the `pipelineId` changes).
+ */
+import type { EmitRecorder } from 'footprintjs';
+/** A single tool invocation in the run. */
+export interface ToolCallRef {
+    /** The execution-step id this tool call ran under. */
+    readonly runtimeStageId: string;
+    /** The provider tool-call id (stable per call). */
+    readonly toolCallId: string;
+    /** The tool's name. */
+    readonly toolName: string;
+    /** The ReAct iteration the call belongs to (0-based). */
+    readonly iteration: number;
+}
+/** A value-derived data dependency: `from`'s result value reappeared in `to`'s args. */
+export interface ToolLineageEdge {
+    readonly from: ToolCallRef;
+    readonly to: ToolCallRef;
+    /** The distinctive value that links them. */
+    readonly value: string;
+}
+/** The tool→tool data-flow graph for one run. */
+export interface ToolLineageGraph {
+    readonly nodes: readonly ToolCallRef[];
+    readonly edges: readonly ToolLineageEdge[];
+}
+export interface ToolLineageOptions {
+    /** Recorder id (idempotent-by-id when attached). Default `'tool-lineage'`. */
+    readonly id?: string;
+    /** Minimum string length for a value to be matchable. Default 4. */
+    readonly minValueLength?: number;
+    /** Also match numeric values. Default false (coincidental matches likely). */
+    readonly matchNumbers?: boolean;
+    /** Max recursion depth when flattening args/results. Default 6. */
+    readonly maxDepth?: number;
+}
+/** An EmitRecorder that also exposes the derived lineage graph. */
+export interface ToolLineageRecorderHandle extends EmitRecorder {
+    /** The tool→tool data-flow graph derived so far. Safe to call during or after a run. */
+    getLineage(): ToolLineageGraph;
+    /** Reset all accumulated state. */
+    clear(): void;
+}
+export declare function toolLineageRecorder(options?: ToolLineageOptions): ToolLineageRecorderHandle;
+//# sourceMappingURL=ToolLineageRecorder.d.ts.map

package/dist/types/recorders/observability/ToolLineageRecorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolLineageRecorder.d.ts","sourceRoot":"","sources":["../../../../src/recorders/observability/ToolLineageRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAa,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3D,2CAA2C;AAC3C,MAAM,WAAW,WAAW;IAC1B,sDAAsD;IACtD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,mDAAmD;IACnD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,uBAAuB;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,wFAAwF;AACxF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,EAAE,EAAE,WAAW,CAAC;IACzB,6CAA6C;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,iDAAiD;AACjD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC,QAAQ,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;CAC5C;AAED,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,mEAAmE;AACnE,MAAM,WAAW,yBAA0B,SAAQ,YAAY;IAC7D,wFAAwF;IACxF,UAAU,IAAI,gBAAgB,CAAC;IAC/B,mCAAmC;IACnC,KAAK,IAAI,IAAI,CAAC;CACf;AAMD,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,kBAAuB,GAAG,yBAAyB,CAqG/F"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfootprint",
-  "version": "6.1.0",
+  "version": "6.2.0",
   "description": "The explainable agent framework — build AI agents you can explain, audit, and trust. Built on footprintjs.",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",
@@ -178,7 +178,7 @@
     "@aws-sdk/client-xray": "*",
     "@modelcontextprotocol/sdk": "*",
     "@opentelemetry/api": "*",
-    "footprintjs": "^7.0.0",
+    "footprintjs": "^7.0.0 || ^8.0.0",
     "ioredis": "*",
     "openai": "*",
     "zod": "*"
@@ -223,7 +223,7 @@
     "esbuild": "^0.28.0",
     "eslint": "^8.44.0",
     "eslint-config-prettier": "^6.15.0",
-    "footprintjs": "^7.0.0",
+    "footprintjs": "^7.0.0 || ^8.0.0",
     "prettier": "^2.8.1",
     "typedoc": "^0.28.19",
     "typedoc-plugin-markdown": "^4.11.0",