agentfootprint 1.1.0 → 1.2.0

package/AGENTS.md

@@ -22,11 +22,11 @@ src/
 ├── tools/       → ToolRegistry + defineTool
 ├── stages/      → Reusable flowchart stages (seedScope, callLLM, parseResponse, etc.)
 ├── scope/       → AgentScope paths + helpers
-├── memory/      → Message utilities (appendMessage, slidingWindow, truncateToCharBudget)
+├── memory/      → Message utilities (appendMessage, lastMessage, lastAssistantMessage)
 ├── executor/    → agentLoop (core ReAct loop)
 ├── compositions/→ withRetry, withFallback, withCircuitBreaker
 ├── streaming/   → StreamEmitter, SSEFormatter, AgentStreamEvent
-├── lib/         → Instructions (agentInstruction, InstructionsToLLM subflow), narrative (grounding helpers), loop (buildAgentLoop), slots, call stages
+├── lib/         → Instructions (agentInstruction, InstructionsToLLM subflow), narrative (agentRenderer), loop (buildAgentLoop), slots, call stages
 └── types/       → All type definitions (messages, llm, tools, content blocks)
 ```
 
@@ -281,7 +281,6 @@ Collects during traversal via recorder hooks — no post-processing of narrative
 ## Anti-Patterns
 
 - Never use the old functional API (`LLMCall({...})`, `Agent({...})`) — always use `LLMCall.create({...})` builder pattern
-- Never use `CostRecorderV2` — use `CostRecorder` (V2 is a deprecated alias)
 - Never pass recorders via constructor options — use `.recorder()` builder method
 - Don't use `name`/`parameters` on `defineTool` — use `id`/`inputSchema`
 - Don't use `tokens.stats()` — use `tokens.getStats()`

package/CLAUDE.md

@@ -22,11 +22,11 @@ src/
 ├── tools/       → ToolRegistry + defineTool
 ├── stages/      → Reusable flowchart stages (seedScope, callLLM, parseResponse, etc.)
 ├── scope/       → AgentScope paths + helpers
-├── memory/      → Message utilities (appendMessage, slidingWindow, truncateToCharBudget)
+├── memory/      → Message utilities (appendMessage, lastMessage, lastAssistantMessage)
 ├── executor/    → agentLoop (core ReAct loop)
 ├── compositions/→ withRetry, withFallback, withCircuitBreaker
 ├── streaming/   → StreamEmitter, SSEFormatter, AgentStreamEvent
-├── lib/         → Instructions (agentInstruction, InstructionsToLLM subflow), narrative (grounding helpers), loop (buildAgentLoop), slots, call stages
+├── lib/         → Instructions (agentInstruction, InstructionsToLLM subflow), narrative (agentRenderer), loop (buildAgentLoop), slots, call stages
 └── types/       → All type definitions (messages, llm, tools, content blocks)
 ```
 
@@ -281,7 +281,6 @@ Collects during traversal via recorder hooks — no post-processing of narrative
 ## Anti-Patterns
 
 - Never use the old functional API (`LLMCall({...})`, `Agent({...})`) — always use `LLMCall.create({...})` builder pattern
-- Never use `CostRecorderV2` — use `CostRecorder` (V2 is a deprecated alias)
 - Never pass recorders via constructor options — use `.recorder()` builder method
 - Don't use `name`/`parameters` on `defineTool` — use `id`/`inputSchema`
 - Don't use `tokens.stats()` — use `tokens.getStats()`

package/ai-instructions/claude-code/SKILL.md

@@ -511,7 +511,7 @@ src/
 ├── models/       → Model configs (anthropic, openai, ollama, bedrock)
 ├── adapters/     → Mock, Anthropic, OpenAI, Bedrock, MCP, A2A, createProvider
 ├── tools/        → ToolRegistry, defineTool
-├── memory/       → Message helpers (appendMessage, slidingWindow, truncate)
+├── memory/       → Message helpers (appendMessage, lastMessage, lastAssistantMessage)
 ├── scope/        → AgentScope (typed paths into footprintjs ScopeFacade)
 ├── stages/       → Reusable stage functions (seedScope, callLLM, parseResponse, etc.)
 ├── core/         → AgentRecorder, PromptProvider, ToolProvider, AgentLoopConfig
@@ -530,8 +530,7 @@ Single entry point: `import { ... } from 'agentfootprint'`
 
 ## Anti-Patterns to Avoid
 
-1. **Never use `CostRecorderV2`** — it's deprecated. Use `CostRecorder`.
-2. **Never post-process the flowchart** — use recorders to collect data during traversal.
+1. **Never post-process the flowchart** — use recorders to collect data during traversal.
 3. **Never build agents without `mock()`** in tests — no API keys in test suites.
 4. **Don't skip `.recorder(rec)`** — always attach recorders to observe execution.
 5. **Don't use raw footprintjs stages** for agent logic — use concept builders (`Agent.create()`, `LLMCall.create()`, etc.).

package/ai-instructions/clinerules

@@ -78,7 +78,6 @@ runner.toFlowChart()         // for subflow composition
 
 ## Rules
 
-- Use `CostRecorder` (not `CostRecorderV2`)
 - Never post-process — use recorders
 - Use `mock([...])` in tests
 - Use concept builders, not raw stages

package/ai-instructions/copilot-instructions.md

@@ -101,7 +101,6 @@ runner.toFlowChart()            // for subflow composition
 
 ## Rules
 
-- Never use `CostRecorderV2` — use `CostRecorder`
 - Never post-process — use recorders to collect data during traversal
 - Always use `mock([...])` in tests — no API keys in test suites
 - Use concept builders (`Agent.create()`, etc.) not raw stages

package/ai-instructions/cursor/agentfootprint.md

@@ -93,7 +93,6 @@ runner.toFlowChart()            // expose for subflow composition
 
 ## Rules
 
-- Never use `CostRecorderV2` — use `CostRecorder`
 - Never post-process — use recorders
 - Always use `mock([...])` in tests — no API keys
 - Use concept builders, not raw stages

package/ai-instructions/kiro/agentfootprint.md

@@ -93,7 +93,6 @@ runner.toFlowChart()            // expose for subflow composition
 
 ## Rules
 
-- Never use `CostRecorderV2` — use `CostRecorder`
 - Never post-process — use recorders
 - Always use `mock([...])` in tests — no API keys
 - Use concept builders, not raw stages

package/ai-instructions/windsurfrules

@@ -78,7 +78,6 @@ runner.toFlowChart()         // for subflow composition
 
 ## Rules
 
-- Use `CostRecorder` (not `CostRecorderV2`)
 - Never post-process — use recorders
 - Use `mock([...])` in tests
 - Use concept builders, not raw stages

package/dist/esm/recorders/v2/CostRecorder.js.map

@@ -1 +1 @@
-{"version":3,"file":"CostRecorder.js","sourceRoot":"","sources":["../../../../src/recorders/v2/CostRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA0BH,MAAM,OAAO,YAAY;IACd,EAAE,CAAS;IACZ,OAAO,GAAgB,EAAE,CAAC;IAC1B,YAAY,CAA+B;IAEnD,YAAY,UAA+B,EAAE;QAC3C,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,EAAE,IAAI,eAAe,CAAC;QACxC,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,EAAE,CAAC;IACjD,CAAC;IAED,SAAS,CAAC,KAAmB;QAC3B,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,SAAS,CAAC;QACvC,MAAM,WAAW,GAAG,KAAK,CAAC,KAAK,EAAE,WAAW,IAAI,CAAC,CAAC;QAClD,MAAM,YAAY,GAAG,KAAK,CAAC,KAAK,EAAE,YAAY,IAAI,CAAC,CAAC;QAEpD,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QACzC,MAAM,SAAS,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,WAAW,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1E,MAAM,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,YAAY,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QAE7E,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;YAChB,KAAK;YACL,WAAW;YACX,YAAY;YACZ,SAAS;YACT,UAAU;YACV,SAAS,EAAE,SAAS,GAAG,UAAU;SAClC,CAAC,CAAC;IACL,CAAC;IAED,YAAY;QACV,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;IAC3D,CAAC;IAED,UAAU;QACR,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3B,CAAC;IAED,KAAK;QACH,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;IACpB,CAAC;CACF"}
+{"version":3,"file":"CostRecorder.js","sourceRoot":"","sources":["../../../../src/recorders/v2/CostRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAqBH,MAAM,OAAO,YAAY;IACd,EAAE,CAAS;IACZ,OAAO,GAAgB,EAAE,CAAC;IAC1B,YAAY,CAA+B;IAEnD,YAAY,UAA+B,EAAE;QAC3C,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,EAAE,IAAI,eAAe,CAAC;QACxC,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,EAAE,CAAC;IACjD,CAAC;IAED,SAAS,CAAC,KAAmB;QAC3B,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,SAAS,CAAC;QACvC,MAAM,WAAW,GAAG,KAAK,CAAC,KAAK,EAAE,WAAW,IAAI,CAAC,CAAC;QAClD,MAAM,YAAY,GAAG,KAAK,CAAC,KAAK,EAAE,YAAY,IAAI,CAAC,CAAC;QAEpD,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QACzC,MAAM,SAAS,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,WAAW,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1E,MAAM,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,YAAY,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QAE7E,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;YAChB,KAAK;YACL,WAAW;YACX,YAAY;YACZ,SAAS;YACT,UAAU;YACV,SAAS,EAAE,SAAS,GAAG,UAAU;SAClC,CAAC,CAAC;IACL,CAAC;IAED,YAAY;QACV,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;IAC3D,CAAC;IAED,UAAU;QACR,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3B,CAAC;IAED,KAAK;QACH,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;IACpB,CAAC;CACF"}

package/dist/esm/recorders/v2/agentObservability.js

@@ -1,9 +1,9 @@
 /**
  * agentObservability() — one-call preset for full agent observability.
  *
- * Bundles TokenRecorder, ToolUsageRecorder, and CostRecorder into a single
- * CompositeRecorder. The consumer attaches one recorder and gets token tracking,
- * tool usage stats, and cost estimation without knowing the individual types.
+ * Bundles TokenRecorder, ToolUsageRecorder, CostRecorder, and ExplainRecorder
+ * into a single CompositeRecorder. One `.recorder()` call gives you token tracking,
+ * tool usage, cost estimation, and grounding analysis (sources vs claims).
  *
  * Stage-level timing is auto-attached by the runners (MetricRecorder on the
  * executor) — this preset covers the agent-level concerns only.
@@ -12,7 +12,6 @@
  * ```typescript
  * import { Agent, agentObservability } from 'agentfootprint';
  *
- * // One call — tokens, tools, and cost tracking
  * const obs = agentObservability();
  * const agent = Agent.create({ provider })
  *   .recorder(obs)
@@ -20,43 +19,35 @@
  *
  * await agent.run('hello');
  *
- * // Access stats
- * console.log(obs.tokens());     // { totalCalls: 2, totalInputTokens: 150, ... }
- * console.log(obs.tools());      // { totalCalls: 1, byTool: { search: { calls: 1, ... } } }
- * console.log(obs.cost());       // 0.0042
- * ```
- *
- * @example
- * ```typescript
- * // With cost estimation
- * const obs = agentObservability({
- *   pricing: {
- *     'claude-sonnet-4-20250514': { input: 3, output: 15 },
- *     'gpt-4o': { input: 2.5, output: 10 },
- *   },
- * });
+ * obs.tokens();   // { totalCalls: 2, totalInputTokens: 150, ... }
+ * obs.tools();    // { totalCalls: 1, byTool: { search: { calls: 1, ... } } }
+ * obs.cost();     // 0.0042
+ * obs.explain();  // { sources, claims, decisions, summary }
  * ```
  */
 import { CompositeRecorder } from './CompositeRecorder';
 import { CostRecorder } from './CostRecorder';
+import { ExplainRecorder } from './ExplainRecorder';
 import { TokenRecorder } from './TokenRecorder';
 import { ToolUsageRecorder } from './ToolUsageRecorder';
 /**
  * Create a bundled agent observability recorder.
  *
- * Tracks tokens, tool usage, and cost in a single `.recorder()` call.
+ * Tracks tokens, tool usage, cost, and grounding in a single `.recorder()` call.
  * Stage timing is handled separately by MetricRecorder (auto-attached by runners).
  */
 export function agentObservability(options) {
     const tokenRec = new TokenRecorder();
     const toolRec = new ToolUsageRecorder();
     const costRec = new CostRecorder(options?.pricing ? { pricingTable: options.pricing } : undefined);
-    const composite = new CompositeRecorder([tokenRec, toolRec, costRec], options?.id ?? 'agent-observability');
+    const explainRec = new ExplainRecorder();
+    const composite = new CompositeRecorder([tokenRec, toolRec, costRec, explainRec], options?.id ?? 'agent-observability');
     // Convenience accessors — no need to dig into children
     composite.tokens = () => tokenRec.getStats();
     composite.tools = () => toolRec.getStats();
     composite.cost = () => costRec.getTotalCost();
     composite.costEntries = () => costRec.getEntries();
+    composite.explain = () => explainRec.explain();
     return composite;
 }
 //# sourceMappingURL=agentObservability.js.map

package/dist/esm/recorders/v2/agentObservability.js.map

@@ -1 +1 @@
-{"version":3,"file":"agentObservability.js","sourceRoot":"","sources":["../../../../src/recorders/v2/agentObservability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAKH,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAqBxD;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAmC;IAEnC,MAAM,QAAQ,GAAG,IAAI,aAAa,EAAE,CAAC;IACrC,MAAM,OAAO,GAAG,IAAI,iBAAiB,EAAE,CAAC;IACxC,MAAM,OAAO,GAAG,IAAI,YAAY,CAC9B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,SAAS,CACjE,CAAC;IAEF,MAAM,SAAS,GAAG,IAAI,iBAAiB,CACrC,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,EAC5B,OAAO,EAAE,EAAE,IAAI,qBAAqB,CACP,CAAC;IAEhC,uDAAuD;IACvD,SAAS,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC;IAC7C,SAAS,CAAC,KAAK,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;IAC3C,SAAS,CAAC,IAAI,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC;IAC9C,SAAS,CAAC,WAAW,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;IAEnD,OAAO,SAAS,CAAC;AACnB,CAAC"}
+{"version":3,"file":"agentObservability.js","sourceRoot":"","sources":["../../../../src/recorders/v2/agentObservability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAMH,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAuBxD;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAmC;IAEnC,MAAM,QAAQ,GAAG,IAAI,aAAa,EAAE,CAAC;IACrC,MAAM,OAAO,GAAG,IAAI,iBAAiB,EAAE,CAAC;IACxC,MAAM,OAAO,GAAG,IAAI,YAAY,CAC9B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,SAAS,CACjE,CAAC;IACF,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IAEzC,MAAM,SAAS,GAAG,IAAI,iBAAiB,CACrC,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,CAAC,EACxC,OAAO,EAAE,EAAE,IAAI,qBAAqB,CACP,CAAC;IAEhC,uDAAuD;IACvD,SAAS,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC;IAC7C,SAAS,CAAC,KAAK,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;IAC3C,SAAS,CAAC,IAAI,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC;IAC9C,SAAS,CAAC,WAAW,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;IACnD,SAAS,CAAC,OAAO,GAAG,GAAG,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;IAE/C,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/recorders/v2/CostRecorder.js.map

@@ -1 +1 @@
-{"version":3,"file":"CostRecorder.js","sourceRoot":"","sources":["../../../src/recorders/v2/CostRecorder.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AA0BH,MAAa,YAAY;IACd,EAAE,CAAS;IACZ,OAAO,GAAgB,EAAE,CAAC;IAC1B,YAAY,CAA+B;IAEnD,YAAY,UAA+B,EAAE;QAC3C,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,EAAE,IAAI,eAAe,CAAC;QACxC,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,EAAE,CAAC;IACjD,CAAC;IAED,SAAS,CAAC,KAAmB;QAC3B,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,SAAS,CAAC;QACvC,MAAM,WAAW,GAAG,KAAK,CAAC,KAAK,EAAE,WAAW,IAAI,CAAC,CAAC;QAClD,MAAM,YAAY,GAAG,KAAK,CAAC,KAAK,EAAE,YAAY,IAAI,CAAC,CAAC;QAEpD,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QACzC,MAAM,SAAS,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,WAAW,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1E,MAAM,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,YAAY,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QAE7E,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;YAChB,KAAK;YACL,WAAW;YACX,YAAY;YACZ,SAAS;YACT,UAAU;YACV,SAAS,EAAE,SAAS,GAAG,UAAU;SAClC,CAAC,CAAC;IACL,CAAC;IAED,YAAY;QACV,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;IAC3D,CAAC;IAED,UAAU;QACR,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3B,CAAC;IAED,KAAK;QACH,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;IACpB,CAAC;CACF;AAxCD,oCAwCC"}
+{"version":3,"file":"CostRecorder.js","sourceRoot":"","sources":["../../../src/recorders/v2/CostRecorder.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AAqBH,MAAa,YAAY;IACd,EAAE,CAAS;IACZ,OAAO,GAAgB,EAAE,CAAC;IAC1B,YAAY,CAA+B;IAEnD,YAAY,UAA+B,EAAE;QAC3C,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,EAAE,IAAI,eAAe,CAAC;QACxC,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,EAAE,CAAC;IACjD,CAAC;IAED,SAAS,CAAC,KAAmB;QAC3B,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,SAAS,CAAC;QACvC,MAAM,WAAW,GAAG,KAAK,CAAC,KAAK,EAAE,WAAW,IAAI,CAAC,CAAC;QAClD,MAAM,YAAY,GAAG,KAAK,CAAC,KAAK,EAAE,YAAY,IAAI,CAAC,CAAC;QAEpD,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QACzC,MAAM,SAAS,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,WAAW,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1E,MAAM,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,YAAY,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QAE7E,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;YAChB,KAAK;YACL,WAAW;YACX,YAAY;YACZ,SAAS;YACT,UAAU;YACV,SAAS,EAAE,SAAS,GAAG,UAAU;SAClC,CAAC,CAAC;IACL,CAAC;IAED,YAAY;QACV,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;IAC3D,CAAC;IAED,UAAU;QACR,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3B,CAAC;IAED,KAAK;QACH,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;IACpB,CAAC;CACF;AAxCD,oCAwCC"}

package/dist/recorders/v2/agentObservability.js

@@ -2,9 +2,9 @@
 /**
  * agentObservability() — one-call preset for full agent observability.
  *
- * Bundles TokenRecorder, ToolUsageRecorder, and CostRecorder into a single
- * CompositeRecorder. The consumer attaches one recorder and gets token tracking,
- * tool usage stats, and cost estimation without knowing the individual types.
+ * Bundles TokenRecorder, ToolUsageRecorder, CostRecorder, and ExplainRecorder
+ * into a single CompositeRecorder. One `.recorder()` call gives you token tracking,
+ * tool usage, cost estimation, and grounding analysis (sources vs claims).
  *
  * Stage-level timing is auto-attached by the runners (MetricRecorder on the
  * executor) — this preset covers the agent-level concerns only.
@@ -13,7 +13,6 @@
  * ```typescript
  * import { Agent, agentObservability } from 'agentfootprint';
  *
- * // One call — tokens, tools, and cost tracking
  * const obs = agentObservability();
  * const agent = Agent.create({ provider })
  *   .recorder(obs)
@@ -21,45 +20,37 @@
  *
  * await agent.run('hello');
  *
- * // Access stats
- * console.log(obs.tokens());     // { totalCalls: 2, totalInputTokens: 150, ... }
- * console.log(obs.tools());      // { totalCalls: 1, byTool: { search: { calls: 1, ... } } }
- * console.log(obs.cost());       // 0.0042
- * ```
- *
- * @example
- * ```typescript
- * // With cost estimation
- * const obs = agentObservability({
- *   pricing: {
- *     'claude-sonnet-4-20250514': { input: 3, output: 15 },
- *     'gpt-4o': { input: 2.5, output: 10 },
- *   },
- * });
+ * obs.tokens();   // { totalCalls: 2, totalInputTokens: 150, ... }
+ * obs.tools();    // { totalCalls: 1, byTool: { search: { calls: 1, ... } } }
+ * obs.cost();     // 0.0042
+ * obs.explain();  // { sources, claims, decisions, summary }
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.agentObservability = void 0;
 const CompositeRecorder_1 = require("./CompositeRecorder");
 const CostRecorder_1 = require("./CostRecorder");
+const ExplainRecorder_1 = require("./ExplainRecorder");
 const TokenRecorder_1 = require("./TokenRecorder");
 const ToolUsageRecorder_1 = require("./ToolUsageRecorder");
 /**
  * Create a bundled agent observability recorder.
  *
- * Tracks tokens, tool usage, and cost in a single `.recorder()` call.
+ * Tracks tokens, tool usage, cost, and grounding in a single `.recorder()` call.
  * Stage timing is handled separately by MetricRecorder (auto-attached by runners).
  */
 function agentObservability(options) {
     const tokenRec = new TokenRecorder_1.TokenRecorder();
     const toolRec = new ToolUsageRecorder_1.ToolUsageRecorder();
     const costRec = new CostRecorder_1.CostRecorder(options?.pricing ? { pricingTable: options.pricing } : undefined);
-    const composite = new CompositeRecorder_1.CompositeRecorder([tokenRec, toolRec, costRec], options?.id ?? 'agent-observability');
+    const explainRec = new ExplainRecorder_1.ExplainRecorder();
+    const composite = new CompositeRecorder_1.CompositeRecorder([tokenRec, toolRec, costRec, explainRec], options?.id ?? 'agent-observability');
     // Convenience accessors — no need to dig into children
     composite.tokens = () => tokenRec.getStats();
     composite.tools = () => toolRec.getStats();
     composite.cost = () => costRec.getTotalCost();
     composite.costEntries = () => costRec.getEntries();
+    composite.explain = () => explainRec.explain();
     return composite;
 }
 exports.agentObservability = agentObservability;

package/dist/recorders/v2/agentObservability.js.map

@@ -1 +1 @@
-{"version":3,"file":"agentObservability.js","sourceRoot":"","sources":["../../../src/recorders/v2/agentObservability.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;;;AAKH,2DAAwD;AACxD,iDAA8C;AAC9C,mDAAgD;AAChD,2DAAwD;AAqBxD;;;;;GAKG;AACH,SAAgB,kBAAkB,CAChC,OAAmC;IAEnC,MAAM,QAAQ,GAAG,IAAI,6BAAa,EAAE,CAAC;IACrC,MAAM,OAAO,GAAG,IAAI,qCAAiB,EAAE,CAAC;IACxC,MAAM,OAAO,GAAG,IAAI,2BAAY,CAC9B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,SAAS,CACjE,CAAC;IAEF,MAAM,SAAS,GAAG,IAAI,qCAAiB,CACrC,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,EAC5B,OAAO,EAAE,EAAE,IAAI,qBAAqB,CACP,CAAC;IAEhC,uDAAuD;IACvD,SAAS,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC;IAC7C,SAAS,CAAC,KAAK,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;IAC3C,SAAS,CAAC,IAAI,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC;IAC9C,SAAS,CAAC,WAAW,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;IAEnD,OAAO,SAAS,CAAC;AACnB,CAAC;AArBD,gDAqBC"}
+{"version":3,"file":"agentObservability.js","sourceRoot":"","sources":["../../../src/recorders/v2/agentObservability.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;;;AAMH,2DAAwD;AACxD,iDAA8C;AAC9C,uDAAoD;AACpD,mDAAgD;AAChD,2DAAwD;AAuBxD;;;;;GAKG;AACH,SAAgB,kBAAkB,CAChC,OAAmC;IAEnC,MAAM,QAAQ,GAAG,IAAI,6BAAa,EAAE,CAAC;IACrC,MAAM,OAAO,GAAG,IAAI,qCAAiB,EAAE,CAAC;IACxC,MAAM,OAAO,GAAG,IAAI,2BAAY,CAC9B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,SAAS,CACjE,CAAC;IACF,MAAM,UAAU,GAAG,IAAI,iCAAe,EAAE,CAAC;IAEzC,MAAM,SAAS,GAAG,IAAI,qCAAiB,CACrC,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,CAAC,EACxC,OAAO,EAAE,EAAE,IAAI,qBAAqB,CACP,CAAC;IAEhC,uDAAuD;IACvD,SAAS,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC;IAC7C,SAAS,CAAC,KAAK,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;IAC3C,SAAS,CAAC,IAAI,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC;IAC9C,SAAS,CAAC,WAAW,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;IACnD,SAAS,CAAC,OAAO,GAAG,GAAG,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;IAE/C,OAAO,SAAS,CAAC;AACnB,CAAC;AAvBD,gDAuBC"}

package/dist/types/recorders/v2/CostRecorder.d.ts

@@ -11,12 +11,8 @@
  *   console.log(`$${cost.getTotalCost().toFixed(4)}`);
  */
 import type { AgentRecorder, LLMCallEvent } from '../../core';
-export interface ModelPricing {
-    /** Cost per 1M input tokens in USD. */
-    readonly input: number;
-    /** Cost per 1M output tokens in USD. */
-    readonly output: number;
-}
+import type { ModelPricing } from '../../models/types';
+export type { ModelPricing } from '../../models/types';
 export interface CostEntry {
     readonly model: string;
     readonly inputTokens: number;

package/dist/types/recorders/v2/CostRecorder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CostRecorder.d.ts","sourceRoot":"","sources":["../../../../src/recorders/v2/CostRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE9D,MAAM,WAAW,YAAY;IAC3B,uCAAuC;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CACtD;AAED,qBAAa,YAAa,YAAW,aAAa;IAChD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,OAAO,CAAmB;IAClC,OAAO,CAAC,YAAY,CAA+B;gBAEvC,OAAO,GAAE,mBAAwB;IAK7C,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAmBpC,YAAY,IAAI,MAAM;IAItB,UAAU,IAAI,SAAS,EAAE;IAIzB,KAAK,IAAI,IAAI;CAGd"}
+{"version":3,"file":"CostRecorder.d.ts","sourceRoot":"","sources":["../../../../src/recorders/v2/CostRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CACtD;AAED,qBAAa,YAAa,YAAW,aAAa;IAChD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,OAAO,CAAmB;IAClC,OAAO,CAAC,YAAY,CAA+B;gBAEvC,OAAO,GAAE,mBAAwB;IAK7C,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAmBpC,YAAY,IAAI,MAAM;IAItB,UAAU,IAAI,SAAS,EAAE;IAIzB,KAAK,IAAI,IAAI;CAGd"}

package/dist/types/recorders/v2/agentObservability.d.ts

@@ -1,9 +1,9 @@
 /**
  * agentObservability() — one-call preset for full agent observability.
  *
- * Bundles TokenRecorder, ToolUsageRecorder, and CostRecorder into a single
- * CompositeRecorder. The consumer attaches one recorder and gets token tracking,
- * tool usage stats, and cost estimation without knowing the individual types.
+ * Bundles TokenRecorder, ToolUsageRecorder, CostRecorder, and ExplainRecorder
+ * into a single CompositeRecorder. One `.recorder()` call gives you token tracking,
+ * tool usage, cost estimation, and grounding analysis (sources vs claims).
  *
  * Stage-level timing is auto-attached by the runners (MetricRecorder on the
  * executor) — this preset covers the agent-level concerns only.
@@ -12,7 +12,6 @@
  * ```typescript
  * import { Agent, agentObservability } from 'agentfootprint';
  *
- * // One call — tokens, tools, and cost tracking
  * const obs = agentObservability();
  * const agent = Agent.create({ provider })
  *   .recorder(obs)
@@ -20,26 +19,16 @@
  *
  * await agent.run('hello');
  *
- * // Access stats
- * console.log(obs.tokens());     // { totalCalls: 2, totalInputTokens: 150, ... }
- * console.log(obs.tools());      // { totalCalls: 1, byTool: { search: { calls: 1, ... } } }
- * console.log(obs.cost());       // 0.0042
- * ```
- *
- * @example
- * ```typescript
- * // With cost estimation
- * const obs = agentObservability({
- *   pricing: {
- *     'claude-sonnet-4-20250514': { input: 3, output: 15 },
- *     'gpt-4o': { input: 2.5, output: 10 },
- *   },
- * });
+ * obs.tokens();   // { totalCalls: 2, totalInputTokens: 150, ... }
+ * obs.tools();    // { totalCalls: 1, byTool: { search: { calls: 1, ... } } }
+ * obs.cost();     // 0.0042
+ * obs.explain();  // { sources, claims, decisions, summary }
  * ```
  */
 import type { ModelPricing, CostEntry } from './CostRecorder';
 import type { TokenStats } from './TokenRecorder';
 import type { ToolUsageStats } from './ToolUsageRecorder';
+import type { Explanation } from './ExplainRecorder';
 import { CompositeRecorder } from './CompositeRecorder';
 export interface AgentObservabilityOptions {
     /** Custom ID for the composite recorder. Default: 'agent-observability'. */
@@ -57,11 +46,13 @@ export interface AgentObservabilityRecorder extends CompositeRecorder {
     cost(): number;
     /** Per-call cost breakdown. */
     costEntries(): CostEntry[];
+    /** Grounding analysis — sources (tool results) vs claims (LLM output). */
+    explain(): Explanation;
 }
 /**
  * Create a bundled agent observability recorder.
  *
- * Tracks tokens, tool usage, and cost in a single `.recorder()` call.
+ * Tracks tokens, tool usage, cost, and grounding in a single `.recorder()` call.
  * Stage timing is handled separately by MetricRecorder (auto-attached by runners).
  */
 export declare function agentObservability(options?: AgentObservabilityOptions): AgentObservabilityRecorder;

package/dist/types/recorders/v2/agentObservability.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agentObservability.d.ts","sourceRoot":"","sources":["../../../../src/recorders/v2/agentObservability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAKxD,MAAM,WAAW,yBAAyB;IACxC,4EAA4E;IAC5E,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CACxC;AAED,sEAAsE;AACtE,MAAM,WAAW,0BAA2B,SAAQ,iBAAiB;IACnE,8CAA8C;IAC9C,MAAM,IAAI,UAAU,CAAC;IACrB,8DAA8D;IAC9D,KAAK,IAAI,cAAc,CAAC;IACxB,gCAAgC;IAChC,IAAI,IAAI,MAAM,CAAC;IACf,+BAA+B;IAC/B,WAAW,IAAI,SAAS,EAAE,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,CAAC,EAAE,yBAAyB,GAClC,0BAA0B,CAmB5B"}
+{"version":3,"file":"agentObservability.d.ts","sourceRoot":"","sources":["../../../../src/recorders/v2/agentObservability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAMxD,MAAM,WAAW,yBAAyB;IACxC,4EAA4E;IAC5E,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CACxC;AAED,sEAAsE;AACtE,MAAM,WAAW,0BAA2B,SAAQ,iBAAiB;IACnE,8CAA8C;IAC9C,MAAM,IAAI,UAAU,CAAC;IACrB,8DAA8D;IAC9D,KAAK,IAAI,cAAc,CAAC;IACxB,gCAAgC;IAChC,IAAI,IAAI,MAAM,CAAC;IACf,+BAA+B;IAC/B,WAAW,IAAI,SAAS,EAAE,CAAC;IAC3B,0EAA0E;IAC1E,OAAO,IAAI,WAAW,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,CAAC,EAAE,yBAAyB,GAClC,0BAA0B,CAqB5B"}

package/package.json

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