agentfootprint 1.4.2 → 1.7.1

package/dist/types/lib/loop/types.d.ts

@@ -217,6 +217,22 @@ export interface AgentLoopConfig {
     readonly streaming?: boolean;
     /** Structured output format — passed to LLM provider as responseFormat option. */
     readonly responseFormat?: ResponseFormat;
+    /**
+     * Run multiple tool calls within a single turn concurrently via Promise.all.
+     * Results are appended in the order the LLM requested them. Default: false.
+     * Only beneficial when the LLM requests 2+ independent tool calls in a turn.
+     */
+    readonly parallelTools?: boolean;
+    /**
+     * After this many consecutive identical (name, args) tool-call failures, the
+     * library injects a one-shot `escalation` field into the tool result content
+     * telling the LLM to change arguments, switch tools, or finalize. Fires
+     * exactly once per (name, args) key per conversation.
+     *
+     * Defaults to `REPEATED_FAILURE_ESCALATION_THRESHOLD` (3). Pass `0` (or any
+     * non-positive number) to disable.
+     */
+    readonly maxIdenticalFailures?: number;
     /**
      * Custom routing strategy — replaces the default RouteResponse decider.
      *
@@ -229,6 +245,28 @@ export interface AgentLoopConfig {
      * @internal Consumers use Agent/Swarm builders, not this field directly.
      */
     readonly routing?: RoutingConfig;
+    /**
+     * User-defined routing branches prepended to the default `tool-calls | final` routing.
+     *
+     * Each extension's `when` predicate is evaluated (in order) before the default
+     * decider logic. If none match, the default routing applies. If the runner
+     * exposes `.toFlowChart()`, the branch is mounted as a subflow; otherwise the
+     * runner is wrapped as a stage function.
+     *
+     * Ignored when `routing` is also set (Swarm path).
+     *
+     * @example
+     * ```ts
+     * routeExtensions: [
+     *   { id: 'escalate', when: (s) => s.parsedResponse.content.includes('[ESCALATE]'), runner: humanAgent },
+     * ]
+     * ```
+     */
+    readonly routeExtensions?: readonly {
+        readonly id?: string;
+        readonly when: (scope: any) => boolean;
+        readonly runner: import('../../types/multiAgent').RunnerLike;
+    }[];
 }
 /**
  * Options for seeding the loop with initial state.

package/dist/types/lib/loop/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/lib/loop/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/lib/loop/types.ts"],"names":[],"mappings":"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"}

package/dist/types/lib/narrative/agentRenderer.d.ts

@@ -1,5 +1,5 @@
 /**
- * Agent NarrativeRenderer — LLM-optimized narrative for agent loop execution.
+ * Agent NarrativeFormatter — LLM-optimized narrative for agent loop execution.
  *
  * Designed for LLM follow-up reasoning: the narrative answers "what happened?"
  * so a downstream LLM can ask informed questions about the agent's execution.
@@ -30,7 +30,12 @@ export interface AgentRendererOptions {
     verbose?: boolean;
 }
 /**
- * Create an agent-optimized NarrativeRenderer.
+ * Create an agent-optimized narrative formatter.
+ *
+ * Returns the `NarrativeRenderer` type (structurally identical to
+ * footprintjs's new `NarrativeFormatter`). Once a newer footprintjs
+ * release is consumed here, migrate the return type to
+ * `NarrativeFormatter` — no behavioural change.
  *
  * Usage:
  * ```typescript

package/dist/types/lib/narrative/agentRenderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agentRenderer.d.ts","sourceRoot":"","sources":["../../../../src/lib/narrative/agentRenderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EACV,iBAAiB,EAUlB,MAAM,uBAAuB,CAAC;AA6E/B,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AA4ID;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,iBAAiB,CAsFrF"}
+{"version":3,"file":"agentRenderer.d.ts","sourceRoot":"","sources":["../../../../src/lib/narrative/agentRenderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAQH,OAAO,KAAK,EACV,iBAAiB,EAWlB,MAAM,uBAAuB,CAAC;AA6E/B,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAmKD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,iBAAiB,CAwJrF"}

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

@@ -18,4 +18,5 @@ export { OTelRecorder } from './recorders/OTelRecorder';
 export type { OTelTracer, OTelRecorderOptions } from './recorders/OTelRecorder';
 export type { TokenStats, LLMCallEntry, CostEntry, CostRecorderOptions, TurnEntry, ToolUsageStats, ToolStats, QualityScore, QualityJudge, Violation, GuardrailCheck, PermissionEvent, AgentObservabilityOptions, AgentObservabilityRecorder, } from './recorders';
 export type { AgentRecorder } from './core';
+export { ExplainRecorder } from './recorders/ExplainRecorder';
 //# sourceMappingURL=observe.barrel.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"observe.barrel.d.ts","sourceRoot":"","sources":["../../src/observe.barrel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACL,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,YAAY,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEhF,YAAY,EACV,UAAU,EACV,YAAY,EACZ,SAAS,EACT,mBAAmB,EACnB,SAAS,EACT,cAAc,EACd,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,cAAc,EACd,eAAe,EACf,yBAAyB,EACzB,0BAA0B,GAC3B,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC"}
+{"version":3,"file":"observe.barrel.d.ts","sourceRoot":"","sources":["../../src/observe.barrel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACL,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,YAAY,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEhF,YAAY,EACV,UAAU,EACV,YAAY,EACZ,SAAS,EACT,mBAAmB,EACnB,SAAS,EACT,cAAc,EACd,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,cAAc,EACd,eAAe,EACf,yBAAyB,EACzB,0BAA0B,GAC3B,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAG5C,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/types/providers.barrel.d.ts

@@ -25,7 +25,7 @@ export { mcpToolProvider, a2aRunner } from './adapters';
 export type { MCPClient, MCPToolProviderOptions, A2AClient, A2ARunnerOptions } from './adapters';
 export type { LLMProvider, LLMCallOptions, LLMResponse, LLMStreamChunk, TokenUsage } from './types';
 export type { PromptProvider, PromptContext, ToolProvider, ToolContext, ToolExecutionResult, } from './core';
-export { agentAsTool, compositeTools, gatedTools } from './providers';
+export { agentAsTool, compositeTools, gatedTools, staticTools, noTools } from './providers';
 export type { AgentAsToolConfig } from './providers';
 export { staticPrompt, templatePrompt, skillBasedPrompt, compositePrompt } from './providers';
 export type { Skill, SkillBasedPromptOptions, CompositePromptOptions } from './providers';

package/dist/types/providers.barrel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"providers.barrel.d.ts","sourceRoot":"","sources":["../../src/providers.barrel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAC9D,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxE,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAG1D,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7F,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC3E,YAAY,EACV,YAAY,EACZ,qBAAqB,EACrB,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB,EACrB,8BAA8B,EAC9B,2BAA2B,GAC5B,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACxD,YAAY,EAAE,SAAS,EAAE,sBAAsB,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGjG,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,WAAW,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACpG,YAAY,EACV,cAAc,EACd,aAAa,EACb,YAAY,EACZ,WAAW,EACX,mBAAmB,GACpB,MAAM,QAAQ,CAAC;AAGhB,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACtE,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAGrD,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9F,YAAY,EAAE,KAAK,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAG1F,OAAO,EACL,WAAW,EACX,aAAa,EACb,UAAU,EACV,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,oBAAoB,EACpB,iBAAiB,EACjB,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"providers.barrel.d.ts","sourceRoot":"","sources":["../../src/providers.barrel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAC9D,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxE,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAG1D,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7F,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC3E,YAAY,EACV,YAAY,EACZ,qBAAqB,EACrB,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB,EACrB,8BAA8B,EAC9B,2BAA2B,GAC5B,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACxD,YAAY,EAAE,SAAS,EAAE,sBAAsB,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGjG,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,WAAW,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACpG,YAAY,EACV,cAAc,EACd,aAAa,EACb,YAAY,EACZ,WAAW,EACX,mBAAmB,GACpB,MAAM,QAAQ,CAAC;AAGhB,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,UAAU,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC5F,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAGrD,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9F,YAAY,EAAE,KAAK,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAG1F,OAAO,EACL,WAAW,EACX,aAAa,EACb,UAAU,EACV,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,oBAAoB,EACpB,iBAAiB,EACjB,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC"}

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

@@ -1,15 +1,9 @@
 /**
- * CostRecorder (v2) — calculates USD cost from AgentRecorder LLM call events.
+ * CostRecorder — calculates USD cost from AgentRecorder LLM call events.
  *
- * Unlike the v1 CostRecorder (which observes scope writes), this one
- * receives structured LLMCallEvent objects from the core loop.
- *
- * Usage:
- *   const cost = new CostRecorder({ pricingTable: { 'claude-sonnet': { input: 3, output: 15 } } });
- *   agent.recorder(cost);
- *   await agent.run(...);
- *   console.log(`$${cost.getTotalCost().toFixed(4)}`);
+ * Extends KeyedRecorder<CostEntry> — Map keyed by runtimeStageId.
  */
+import { KeyedRecorder } from 'footprintjs/trace';
 import type { AgentRecorder, LLMCallEvent } from '../core';
 import type { ModelPricing } from '../models/types';
 export type { ModelPricing } from '../models/types';
@@ -20,20 +14,30 @@ export interface CostEntry {
     readonly inputCost: number;
     readonly outputCost: number;
     readonly totalCost: number;
+    readonly runtimeStageId: string;
 }
 export interface CostRecorderOptions {
     readonly id?: string;
-    /** Pricing per model (per 1M tokens). Models not in this table get $0 cost. */
     readonly pricingTable?: Record<string, ModelPricing>;
 }
-export declare class CostRecorder implements AgentRecorder {
+export declare class CostRecorder extends KeyedRecorder<CostEntry> implements AgentRecorder {
     readonly id: string;
-    private entries;
     private pricingTable;
     constructor(options?: CostRecorderOptions);
     onLLMCall(event: LLMCallEvent): void;
     getTotalCost(): number;
     getEntries(): CostEntry[];
-    clear(): void;
+    toSnapshot(): {
+        name: string;
+        description: string;
+        preferredOperation: "accumulate";
+        data: {
+            numericField: string;
+            grandTotal: number;
+            steps: {
+                [k: string]: CostEntry;
+            };
+        };
+    };
 }
 //# sourceMappingURL=CostRecorder.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"CostRecorder.d.ts","sourceRoot":"","sources":["../../../src/recorders/CostRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD,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/CostRecorder.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD,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;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CACtD;AAED,qBAAa,YAAa,SAAQ,aAAa,CAAC,SAAS,CAAE,YAAW,aAAa;IACjF,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,YAAY,CAA+B;gBAEvC,OAAO,GAAE,mBAAwB;IAM7C,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAoBpC,YAAY,IAAI,MAAM;IAItB,UAAU,IAAI,SAAS,EAAE;IAIzB,UAAU;;;;;;;;;;;;CAYX"}

package/dist/types/recorders/ExplainRecorder.d.ts

@@ -62,6 +62,8 @@ export interface LLMContext {
 export interface EvalIteration {
     /** Loop iteration number (0-based). */
     readonly iteration: number;
+    /** Unique execution step identifier for this LLM call. */
+    readonly runtimeStageId?: string;
     /** What the LLM had THIS iteration (context changes each loop — messages grow). */
     readonly context: LLMContext;
     /** Tool calls the LLM chose to make (empty if final response). */
@@ -93,6 +95,7 @@ export declare class ExplainRecorder implements AgentRecorder {
     private currentTurn;
     private input?;
     private currentIteration;
+    private currentRuntimeStageId?;
     private currentContext;
     constructor(id?: string);
     onTurnStart(event: TurnStartEvent): void;

package/dist/types/recorders/ExplainRecorder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ExplainRecorder.d.ts","sourceRoot":"","sources":["../../../src/recorders/ExplainRecorder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ExplainRecorder.d.ts","sourceRoot":"","sources":["../../../src/recorders/ExplainRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,aAAa,EACb,cAAc,EACd,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAEjB,mDAAmD;AACnD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,+CAA+C;AAC/C,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,2CAA2C;AAC3C,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,sEAAsE;AACtE,MAAM,WAAW,UAAU;IACzB,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,sCAAsC;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,qEAAqE;IACrE,QAAQ,CAAC,cAAc,CAAC,EAAE,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/E,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACtE,kBAAkB;IAClB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,uCAAuC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,0DAA0D;IAC1D,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,mFAAmF;IACnF,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,SAAS,aAAa,EAAE,CAAC;IAC7C,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IACxC,kFAAkF;IAClF,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAC;CACjC;AAED,iEAAiE;AACjE,MAAM,WAAW,WAAW;IAC1B,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,SAAS,aAAa,EAAE,CAAC;IAC9C,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IACxC,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,SAAS,QAAQ,EAAE,CAAC;IACrC,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,EAAE,SAAS,aAAa,EAAE,CAAC;IAC7C,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,eAAgB,YAAW,aAAa;IACnD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAGpB,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,yBAAyB,CAAuB;IACxD,OAAO,CAAC,uBAAuB,CAAoB;IAGnD,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,KAAK,CAAC,CAAS;IACvB,OAAO,CAAC,gBAAgB,CAAM;IAC9B,OAAO,CAAC,qBAAqB,CAAC,CAAS;IACvC,OAAO,CAAC,cAAc,CAAkB;gBAE5B,EAAE,SAAqB;IAInC,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IAKxC,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAqBpC,UAAU,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IAiBtC,cAAc,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI;IAW9C,8DAA8D;IAC9D,OAAO,CAAC,cAAc;IAetB,UAAU,IAAI,SAAS,UAAU,EAAE;IAInC,SAAS,IAAI,SAAS,QAAQ,EAAE;IAIhC,YAAY,IAAI,SAAS,aAAa,EAAE;IAMxC,UAAU,IAAI,UAAU;IAIxB,sCAAsC;IACtC,aAAa,IAAI,SAAS,aAAa,EAAE;IASzC,gFAAgF;IAChF,OAAO,IAAI,WAAW;IAqBtB,KAAK,IAAI,IAAI;CAUd"}

package/dist/types/recorders/RecorderBridge.d.ts

@@ -14,11 +14,15 @@ export declare class RecorderBridge {
     private readonly recorders;
     private turnNumber;
     private loopIteration;
+    private _toolRuntimeStageId;
+    /** Set by the LLM capture recorder's onStageStart — tracks current stage's runtimeStageId. */
+    setToolRuntimeStageId(id: string): void;
     constructor(recorders: AgentRecorder[]);
     /** Dispatch turn start event. */
     dispatchTurnStart(message: string): void;
     /** Dispatch LLM call event from the adapter response stored in scope. */
-    dispatchLLMCall(response: LLMResponse, latencyMs?: number, context?: {
+    dispatchLLMCall(response: LLMResponse, latencyMs: number, context: {
+        runtimeStageId: string;
         systemPrompt?: string;
         toolDescriptions?: Array<{
             name: string;
@@ -31,11 +35,11 @@ export declare class RecorderBridge {
     }): void;
     /** Dispatch turn complete event. */
     dispatchTurnComplete(content: string, messageCount: number, totalLoopIterations?: number): void;
-    /** Dispatch tool call event from stream events. */
+    /** Dispatch tool call event. */
     dispatchToolCall(toolName: string, args: Record<string, unknown>, result: {
         content: string;
         error?: boolean;
-    }, latencyMs: number): void;
+    }, latencyMs: number, runtimeStageId: string): void;
     /**
      * Create an onStreamEvent handler that bridges tool events to recorders.
      * Attach this alongside the consumer's onEvent handler in AgentRunner.

package/dist/types/recorders/RecorderBridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RecorderBridge.d.ts","sourceRoot":"","sources":["../../../src/recorders/RecorderBridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAgB,MAAM,SAAS,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkB;IAC5C,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,aAAa,CAAK;gBAEd,SAAS,EAAE,aAAa,EAAE;IAItC,iCAAiC;IACjC,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIxC,yEAAyE;IACzE,eAAe,CACb,QAAQ,EAAE,WAAW,EACrB,SAAS,SAAI,EACb,OAAO,CAAC,EAAE;QACR,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,gBAAgB,CAAC,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,WAAW,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAChE,QAAQ,CAAC,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,OAAO,CAAA;SAAE,CAAC,CAAC;KACtD,GACA,IAAI;IAgBP,oCAAoC;IACpC,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,mBAAmB,SAAI,GAAG,IAAI;IAW1F,mDAAmD;IACnD,gBAAgB,CACd,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAC5C,SAAS,EAAE,MAAM,GAChB,IAAI;IAIP;;;OAGG;IACH,uBAAuB,IAAI,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI;IA4B5D,4BAA4B;IAC5B,aAAa,CAAC,KAAK,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAIjF,OAAO,CAAC,QAAQ;CAYjB"}
+{"version":3,"file":"RecorderBridge.d.ts","sourceRoot":"","sources":["../../../src/recorders/RecorderBridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAgB,MAAM,SAAS,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkB;IAC5C,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,mBAAmB,CAAM;IAEjC,8FAA8F;IAC9F,qBAAqB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;gBAI3B,SAAS,EAAE,aAAa,EAAE;IAItC,iCAAiC;IACjC,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIxC,yEAAyE;IACzE,eAAe,CACb,QAAQ,EAAE,WAAW,EACrB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE;QACP,cAAc,EAAE,MAAM,CAAC;QACvB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,gBAAgB,CAAC,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,WAAW,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAChE,QAAQ,CAAC,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,OAAO,CAAA;SAAE,CAAC,CAAC;KACtD,GACA,IAAI;IAiBP,oCAAoC;IACpC,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,mBAAmB,SAAI,GAAG,IAAI;IAW1F,gCAAgC;IAChC,gBAAgB,CACd,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAC5C,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,GACrB,IAAI;IAIP;;;OAGG;IACH,uBAAuB,IAAI,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI;IA6B5D,4BAA4B;IAC5B,aAAa,CAAC,KAAK,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAIjF,OAAO,CAAC,QAAQ;CAYjB"}

package/dist/types/recorders/TokenRecorder.d.ts

@@ -1,24 +1,14 @@
 /**
  * TokenRecorder — tracks token usage and cost across LLM calls.
  *
- * Implements AgentRecorder. Observes onLLMCall events and accumulates
- * input/output token counts, call count, latency stats, and per-call cost.
- *
- * Usage:
- *   const tokens = new TokenRecorder();
- *   agent.recorder(tokens);
- *   await agent.run(...);
- *   console.log(tokens.getStats());
- *
- * With pricing:
- *   const tokens = new TokenRecorder({ pricing: { 'claude-sonnet-4-20250514': { input: 3, output: 15 } } });
+ * Extends KeyedRecorder<LLMCallEntry> — Map keyed by runtimeStageId.
+ * No fallbacks. runtimeStageId is always provided by footprintjs.
  */
+import { KeyedRecorder } from 'footprintjs/trace';
 import type { AgentRecorder, LLMCallEvent } from '../core';
 import type { ModelPricing } from '../models/types';
 export interface TokenRecorderOptions {
-    /** Recorder ID. Default: 'token-recorder'. */
     id?: string;
-    /** Pricing table (per 1M tokens, USD). Models not listed get $0. */
     pricing?: Record<string, ModelPricing>;
 }
 export interface TokenStats {
@@ -27,7 +17,6 @@ export interface TokenStats {
     readonly totalOutputTokens: number;
     readonly totalLatencyMs: number;
     readonly averageLatencyMs: number;
-    /** Total estimated cost in USD. 0 if no pricing table provided. */
     readonly totalCost: number;
     readonly calls: LLMCallEntry[];
 }
@@ -38,17 +27,27 @@ export interface LLMCallEntry {
     readonly latencyMs: number;
     readonly turnNumber: number;
     readonly loopIteration: number;
-    /** Estimated cost in USD for this call. 0 if model not in pricing table. */
     readonly cost: number;
+    readonly runtimeStageId: string;
 }
-export declare class TokenRecorder implements AgentRecorder {
+export declare class TokenRecorder extends KeyedRecorder<LLMCallEntry> implements AgentRecorder {
     readonly id: string;
-    private calls;
     private readonly pricing;
     constructor(options?: TokenRecorderOptions | string);
     onLLMCall(event: LLMCallEvent): void;
     getStats(): TokenStats;
     getTotalTokens(): number;
-    clear(): void;
+    toSnapshot(): {
+        name: string;
+        description: string;
+        preferredOperation: "aggregate";
+        data: {
+            numericField: string;
+            grandTotal: number;
+            steps: {
+                [k: string]: LLMCallEntry;
+            };
+        };
+    };
 }
 //# sourceMappingURL=TokenRecorder.d.ts.map

package/dist/types/recorders/TokenRecorder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TokenRecorder.d.ts","sourceRoot":"","sources":["../../../src/recorders/TokenRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD,MAAM,WAAW,oBAAoB;IACnC,8CAA8C;IAC9C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,YAAY,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,YAAY;IAC3B,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,aAAa,EAAE,MAAM,CAAC;IAC/B,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,aAAc,YAAW,aAAa;IACjD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+B;gBAE3C,OAAO,CAAC,EAAE,oBAAoB,GAAG,MAAM;IAWnD,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAoBpC,QAAQ,IAAI,UAAU;IAkBtB,cAAc,IAAI,MAAM;IAIxB,KAAK,IAAI,IAAI;CAGd"}
+{"version":3,"file":"TokenRecorder.d.ts","sourceRoot":"","sources":["../../../src/recorders/TokenRecorder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD,MAAM,WAAW,oBAAoB;IACnC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,YAAY,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,YAAY;IAC3B,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,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,qBAAa,aAAc,SAAQ,aAAa,CAAC,YAAY,CAAE,YAAW,aAAa;IACrF,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+B;gBAE3C,OAAO,CAAC,EAAE,oBAAoB,GAAG,MAAM;IAWnD,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAqBpC,QAAQ,IAAI,UAAU;IAmBtB,cAAc,IAAI,MAAM;IAIxB,UAAU;;;;;;;;;;;;CAYX"}

package/dist/types/recorders/ToolUsageRecorder.d.ts

@@ -1,15 +1,9 @@
 /**
  * ToolUsageRecorder — tracks which tools are called, how often, and latency.
  *
- * Useful for understanding agent behavior: which tools are hot,
- * which are slow, and which are erroring.
- *
- * Usage:
- *   const toolUsage = new ToolUsageRecorder();
- *   agent.recorder(toolUsage);
- *   await agent.run(...);
- *   console.log(toolUsage.getStats());
+ * Extends KeyedRecorder<ToolCallEvent> — Map keyed by runtimeStageId.
  */
+import { KeyedRecorder } from 'footprintjs/trace';
 import type { AgentRecorder, ToolCallEvent } from '../core';
 export interface ToolUsageStats {
     readonly totalCalls: number;
@@ -22,13 +16,23 @@ export interface ToolStats {
     readonly totalLatencyMs: number;
     readonly averageLatencyMs: number;
 }
-export declare class ToolUsageRecorder implements AgentRecorder {
+export declare class ToolUsageRecorder extends KeyedRecorder<ToolCallEvent> implements AgentRecorder {
     readonly id: string;
-    private toolCalls;
     constructor(id?: string);
     onToolCall(event: ToolCallEvent): void;
     getStats(): ToolUsageStats;
     getToolNames(): string[];
-    clear(): void;
+    toSnapshot(): {
+        name: string;
+        description: string;
+        preferredOperation: "translate";
+        data: {
+            numericField: string;
+            grandTotal: number;
+            steps: {
+                [k: string]: ToolCallEvent;
+            };
+        };
+    };
 }
 //# sourceMappingURL=ToolUsageRecorder.d.ts.map

package/dist/types/recorders/ToolUsageRecorder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ToolUsageRecorder.d.ts","sourceRoot":"","sources":["../../../src/recorders/ToolUsageRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE5D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAED,qBAAa,iBAAkB,YAAW,aAAa;IACrD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,SAAS,CAAuB;gBAE5B,EAAE,SAAwB;IAItC,UAAU,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IAItC,QAAQ,IAAI,cAAc;IA6B1B,YAAY,IAAI,MAAM,EAAE;IAIxB,KAAK,IAAI,IAAI;CAGd"}
+{"version":3,"file":"ToolUsageRecorder.d.ts","sourceRoot":"","sources":["../../../src/recorders/ToolUsageRecorder.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE5D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAED,qBAAa,iBAAkB,SAAQ,aAAa,CAAC,aAAa,CAAE,YAAW,aAAa;IAC1F,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;gBAER,EAAE,SAAwB;IAKtC,UAAU,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IAItC,QAAQ,IAAI,cAAc;IA8B1B,YAAY,IAAI,MAAM,EAAE;IAIxB,UAAU;;;;;;;;;;;;CAYX"}

package/dist/types/scope/types.d.ts

@@ -66,6 +66,13 @@ export interface AgentLoopState {
     maxIterations: number;
     /** Final answer text (set when turn finalizes). */
     result: string;
+    /**
+     * Set by Finalize when the turn ended because `loopCount >= maxIterations`
+     * (safeDecider force-routed to the default branch), rather than because the
+     * LLM chose to stop. Consumers use it to render a distinct "agent gave up"
+     * state instead of an ambiguous empty response.
+     */
+    maxIterationsReached?: boolean;
     /** Prepared messages after strategy applied (Messages slot output). */
     memory_preparedMessages: Message[];
     /** Raw history loaded from ConversationStore. */

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

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

package/dist/types/streaming/StreamEmitter.d.ts

@@ -56,6 +56,15 @@ export type AgentStreamEvent = {
     content: string;
     iterations: number;
     paused?: boolean;
+    /**
+     * Why the turn ended. Absent when the LLM chose to stop normally.
+     *   - 'maxIterations': safeDecider force-finalized at the iteration cap.
+     *   - 'paused':        the agent paused for human input (ask_human). Paired
+     *                      with `paused: true`; the `reason` variant lets
+     *                      consumers switch on a single field instead of two.
+     * Future reasons can be added without breaking consumers (optional field).
+     */
+    reason?: 'maxIterations' | 'paused';
 } | {
     type: 'error';
     phase: AgentPhase;

package/dist/types/streaming/StreamEmitter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StreamEmitter.d.ts","sourceRoot":"","sources":["../../../src/streaming/StreamEmitter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAClC;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB,GACD;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAC3F;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,6FAA6F;IAC7F,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB,GACD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAC3E;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D,MAAM,MAAM,uBAAuB,GAAG,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;AAExE;;;;;GAKG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAiC;IAEjD,EAAE,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,IAAI;IAOhD,IAAI,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI;CASpC;AAED;;;;;;;;GAQG;AACH,qBAAa,YAAY;IACvB,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM;IAI9C,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,gBAAgB,EAAE,GAAG,MAAM;CAGrD;AAGD,gDAAgD;AAChD,MAAM,MAAM,WAAW,GAAG,gBAAgB,CAAC;AAC3C,uDAAuD;AACvD,MAAM,MAAM,kBAAkB,GAAG,uBAAuB,CAAC"}
+{"version":3,"file":"StreamEmitter.d.ts","sourceRoot":"","sources":["../../../src/streaming/StreamEmitter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAClC;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB,GACD;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAC3F;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,6FAA6F;IAC7F,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB,GACD;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,eAAe,GAAG,QAAQ,CAAC;CACrC,GACD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D,MAAM,MAAM,uBAAuB,GAAG,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;AAExE;;;;;GAKG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAiC;IAEjD,EAAE,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,IAAI;IAOhD,IAAI,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI;CASpC;AAED;;;;;;;;GAQG;AACH,qBAAa,YAAY;IACvB,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM;IAI9C,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,gBAAgB,EAAE,GAAG,MAAM;CAGrD;AAGD,gDAAgD;AAChD,MAAM,MAAM,WAAW,GAAG,gBAAgB,CAAC;AAC3C,uDAAuD;AACvD,MAAM,MAAM,kBAAkB,GAAG,uBAAuB,CAAC"}

package/dist/types/types/agent.d.ts

@@ -25,6 +25,13 @@ export interface AgentResult {
         question: string;
         toolCallId: string;
     };
+    /**
+     * True when the turn ended because the agent hit its iteration cap
+     * (safeDecider force-routed to Finalize). The LLM did not choose to stop —
+     * it was cut off. Render a distinct state so users understand the loop
+     * didn't complete normally.
+     */
+    readonly maxIterationsReached?: boolean;
 }
 export interface AgentRunOptions {
     /** User message to send. */

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

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/types/agent.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,oFAAoF;IACpF,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/D;AAED,MAAM,WAAW,eAAe;IAC9B,4BAA4B;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qCAAqC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,+BAA+B;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/types/agent.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,oFAAoF;IACpF,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9D;;;;;OAKG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;CACzC;AAED,MAAM,WAAW,eAAe;IAC9B,4BAA4B;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qCAAqC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,+BAA+B;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B"}

package/dist/types/types/multiAgent.d.ts

@@ -53,5 +53,12 @@ export interface TraversalResult {
     readonly agents: AgentResultEntry[];
     /** Total traversal execution time. */
     readonly totalLatencyMs: number;
+    /**
+     * True when the traversal ended because `loopCount >= maxIterations` in the
+     * underlying agent loop (set by `safeDecider`), rather than because the LLM
+     * chose to stop. Surfaced uniformly across Swarm / Pipeline / custom runners
+     * so consumers can render a distinct "agent gave up" state.
+     */
+    readonly maxIterationsReached?: boolean;
 }
 //# sourceMappingURL=multiAgent.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"multiAgent.d.ts","sourceRoot":"","sources":["../../../src/types/multiAgent.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,GAAG,CACD,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GACrD,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChC,YAAY,CAAC,IAAI,MAAM,EAAE,CAAC;IAC1B,WAAW,CAAC,IAAI,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6BAA6B;IAC7B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,kGAAkG;IAClG,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC;IAClE,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,CAAC,EAAE,CACtB,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,EAC3B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC3B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,4BAA4B;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mDAAmD;IACnD,QAAQ,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC;IACpC,sCAAsC;IACtC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC"}
+{"version":3,"file":"multiAgent.d.ts","sourceRoot":"","sources":["../../../src/types/multiAgent.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,GAAG,CACD,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GACrD,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChC,YAAY,CAAC,IAAI,MAAM,EAAE,CAAC;IAC1B,WAAW,CAAC,IAAI,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6BAA6B;IAC7B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,kGAAkG;IAClG,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC;IAClE,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,CAAC,EAAE,CACtB,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,EAC3B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC3B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,4BAA4B;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mDAAmD;IACnD,QAAQ,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC;IACpC,sCAAsC;IACtC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;CACzC"}

package/dist/types/types/tools.d.ts

@@ -6,12 +6,28 @@ export interface ToolDefinition {
     readonly id: string;
     /** Human-readable description (sent to LLM). */
     readonly description: string;
-    /** JSON Schema for tool input. */
+    /** JSON Schema for tool input (plain object or Zod schema). */
     readonly inputSchema: Record<string, unknown>;
-    /** Handler function. Returns string result. */
+    /** Handler function. Receives parsed LLM arguments. */
     readonly handler: ToolHandler;
 }
-export type ToolHandler = (input: Record<string, unknown>) => Promise<ToolResult> | ToolResult;
+/**
+ * Tool handler function.
+ *
+ * Input is typed as `any` to allow destructured typed parameters
+ * in tool definitions. The runtime input is always a parsed JSON object
+ * from the LLM's tool call arguments.
+ *
+ * @example
+ * ```typescript
+ * // Destructure directly — the common pattern:
+ * handler: async ({ query }: { query: string }) => ({ content: `Results for: ${query}` })
+ *
+ * // Or use the raw input:
+ * handler: async (input) => ({ content: `${input.query}` })
+ * ```
+ */
+export type ToolHandler = (input: any) => Promise<ToolResult> | ToolResult;
 export interface ToolResult {
     readonly content: string;
     readonly error?: boolean;

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

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/types/tools.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,cAAc;IAC7B,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,kCAAkC;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9C,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,MAAM,WAAW,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,UAAU,CAAC,GAAG,UAAU,CAAC;AAE/F,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/types/tools.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,cAAc;IAC7B,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9C,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,KAAK,EAAE,GAAG,KAAK,OAAO,CAAC,UAAU,CAAC,GAAG,UAAU,CAAC;AAE3E,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfootprint",
-  "version": "1.4.2",
+  "version": "1.7.1",
   "description": "The explainable agent framework — build AI agents you can explain, audit, and trust. Built on footprintjs.",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",
@@ -52,6 +52,7 @@
     "build": "tsc && tsc -p tsconfig.esm.json",
     "watch": "tsc -w",
     "test": "vitest run",
+    "test:examples": "tsc -p examples/tsconfig.json",
     "test:watch": "vitest --watch",
     "lint": "eslint 'src/**/*.ts' 'test/**/*.ts' --ext .ts",
     "lint:fix": "eslint 'src/**/*.ts' 'test/**/*.ts' --ext .ts --fix",
@@ -144,10 +145,8 @@
     }
   },
   "sideEffects": false,
-  "dependencies": {
-    "footprintjs": ">=4.4.1"
-  },
   "peerDependencies": {
+    "footprintjs": ">=4.13.0",
     "@anthropic-ai/sdk": ">=0.30.0",
     "@aws-sdk/client-bedrock-runtime": ">=3.0.0",
     "openai": ">=4.0.0"
@@ -169,7 +168,7 @@
     "@typescript-eslint/parser": "^5.61.0",
     "eslint": "^8.44.0",
     "eslint-config-prettier": "^6.15.0",
-    "footprintjs": "^4.4.1",
+    "footprintjs": "^4.13.0",
     "prettier": "^2.8.1",
     "typescript": "~5.4.5",
     "vitest": "^4.0.18",