agentfootprint 6.0.0 → 6.2.0

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/dist/types/recorders/observability/commentary/commentaryTemplates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commentaryTemplates.d.ts","sourceRoot":"","sources":["../../../../../src/recorders/observability/commentary/commentaryTemplates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE;;;2EAG2E;AAC3E,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,mBA+ExC,CAAC;AAEF;;6CAE6C;AAC7C,MAAM,WAAW,iBAAiB;IAChC;6EACyE;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;2EAGuE;IACvE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;CACxE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CA6FzF;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,mBAAmB,EAC1B,GAAG,EAAE,iBAAiB,EACtB,SAAS,GAAE,mBAAgD,GAC1D,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmDxB;AAgCD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,mBAAmB,EAAE,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAS3F;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAEvF"}
+{"version":3,"file":"commentaryTemplates.d.ts","sourceRoot":"","sources":["../../../../../src/recorders/observability/commentary/commentaryTemplates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE;;;2EAG2E;AAC3E,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,mBA+ExC,CAAC;AAEF;;6CAE6C;AAC7C,MAAM,WAAW,iBAAiB;IAChC;6EACyE;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;2EAGuE;IACvE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;CACxE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CA6FzF;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,mBAAmB,EAC1B,GAAG,EAAE,iBAAiB,EACtB,SAAS,GAAE,mBAAgD,GAC1D,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA4DxB;AAgCD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,mBAAmB,EAAE,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAS3F;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAEvF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfootprint",
-  "version": "6.0.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",