agentfootprint 1.1.0 → 1.1.1

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/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/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.1.1",
   "description": "The explainable agent framework — build AI agents you can explain, audit, and trust. Built on footprintjs.",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",