agentfootprint 1.0.0

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

@@ -0,0 +1,66 @@
+/**
+ * PermissionRecorder — AgentRecorder that captures permission gate events.
+ *
+ * Tracks both layers of gatedTools defense-in-depth:
+ *   1. resolve: tools filtered out (LLM never saw them)
+ *   2. execute: tool calls rejected (hallucinated/injected tool name)
+ *
+ * Integrates with gatedTools via the onBlocked callback — events
+ * are captured DURING traversal (not post-processing).
+ *
+ * Also captures successful tool calls via onToolCall to give a
+ * complete picture: what was allowed, what was blocked, what was denied.
+ *
+ * Usage:
+ *   const permRecorder = new PermissionRecorder();
+ *
+ *   const gated = gatedTools(inner, checker, {
+ *     onBlocked: permRecorder.onBlocked,  // Wire the bridge
+ *   });
+ *
+ *   const agent = Agent.create({ provider })
+ *     .toolProvider(gated)
+ *     .recorder(permRecorder)
+ *     .build();
+ *
+ *   // After execution:
+ *   permRecorder.getEvents();     // all permission events
+ *   permRecorder.getBlocked();    // just blocked tools
+ *   permRecorder.getDenied();     // execute-time rejections
+ *   permRecorder.getSummary();    // { allowed: [...], blocked: [...], denied: [...] }
+ */
+import type { AgentRecorder, ToolCallEvent } from '../../core/recorders';
+import type { ToolContext } from '../../core';
+export interface PermissionEvent {
+    readonly type: 'blocked' | 'denied' | 'allowed';
+    readonly toolId: string;
+    readonly phase: 'resolve' | 'execute';
+    readonly timestamp: number;
+}
+export declare class PermissionRecorder implements AgentRecorder {
+    readonly id = "permission-recorder";
+    private events;
+    /**
+     * Wire this to gatedTools({ onBlocked: recorder.onBlocked }).
+     * Arrow function — safe to pass as callback directly.
+     */
+    readonly onBlocked: (toolId: string, phase: 'resolve' | 'execute', _context?: ToolContext) => void;
+    /** AgentRecorder hook — captures successful tool calls. */
+    onToolCall(event: ToolCallEvent): void;
+    /** All permission events in order. */
+    getEvents(): readonly PermissionEvent[];
+    /** Tools blocked at resolve time (LLM never saw them). */
+    getBlocked(): string[];
+    /** Tool calls denied at execute time (hallucinated/injected). */
+    getDenied(): string[];
+    /** Tools that were allowed and executed successfully. */
+    getAllowed(): string[];
+    /** Summary for audit logging. */
+    getSummary(): {
+        allowed: string[];
+        blocked: string[];
+        denied: string[];
+    };
+    clear(): void;
+}
+//# sourceMappingURL=PermissionRecorder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PermissionRecorder.d.ts","sourceRoot":"","sources":["../../../../src/recorders/v2/PermissionRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;IAChD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,qBAAa,kBAAmB,YAAW,aAAa;IACtD,QAAQ,CAAC,EAAE,yBAAyB;IACpC,OAAO,CAAC,MAAM,CAAyB;IAEvC;;;OAGG;IACH,QAAQ,CAAC,SAAS,WAAY,MAAM,SAAS,SAAS,GAAG,SAAS,aAAa,WAAW,KAAG,IAAI,CAO/F;IAEF,2DAA2D;IAC3D,UAAU,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IAWtC,sCAAsC;IACtC,SAAS,IAAI,SAAS,eAAe,EAAE;IAIvC,0DAA0D;IAC1D,UAAU,IAAI,MAAM,EAAE;IAItB,iEAAiE;IACjE,SAAS,IAAI,MAAM,EAAE;IAIrB,yDAAyD;IACzD,UAAU,IAAI,MAAM,EAAE;IAItB,iCAAiC;IACjC,UAAU,IAAI;QAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE;IAQxE,KAAK,IAAI,IAAI;CAGd"}

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

@@ -0,0 +1,37 @@
+/**
+ * QualityRecorder — evaluates output quality during execution.
+ *
+ * Calls a judge function on each turn completion and collects scores.
+ * The judge can be LLM-powered, rule-based, or any scoring function.
+ * Scores are collected during traversal (never post-processed).
+ *
+ * Usage:
+ *   const quality = new QualityRecorder(async (event) => {
+ *     const score = await llm.judge(event.content);
+ *     return { score, label: score > 0.8 ? 'good' : 'poor' };
+ *   });
+ *   agent.recorder(quality);
+ *   await agent.run(...);
+ *   console.log(quality.getScores());
+ */
+import type { AgentRecorder, TurnCompleteEvent } from '../../core';
+export interface QualityScore {
+    /** Numeric score (0-1 recommended, but not enforced). */
+    readonly score: number;
+    /** Optional human-readable label. */
+    readonly label?: string;
+    /** Which turn this score belongs to. */
+    readonly turnNumber: number;
+}
+export type QualityJudge = (event: TurnCompleteEvent) => QualityScore | Promise<QualityScore>;
+export declare class QualityRecorder implements AgentRecorder {
+    readonly id: string;
+    private readonly judge;
+    private scores;
+    constructor(judge: QualityJudge, id?: string);
+    onTurnComplete(event: TurnCompleteEvent): void;
+    getScores(): QualityScore[];
+    getAverageScore(): number;
+    clear(): void;
+}
+//# sourceMappingURL=QualityRecorder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"QualityRecorder.d.ts","sourceRoot":"","sources":["../../../../src/recorders/v2/QualityRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAInE,MAAM,WAAW,YAAY;IAC3B,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qCAAqC;IACrC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,wCAAwC;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;AAI9F,qBAAa,eAAgB,YAAW,aAAa;IACnD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,MAAM,CAAsB;gBAExB,KAAK,EAAE,YAAY,EAAE,EAAE,SAAqB;IAKxD,cAAc,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI;IAU9C,SAAS,IAAI,YAAY,EAAE;IAI3B,eAAe,IAAI,MAAM;IAKzB,KAAK,IAAI,IAAI;CAGd"}

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

@@ -0,0 +1,38 @@
+/**
+ * RecorderBridge — dispatches AgentRecorder events from runner execution data.
+ *
+ * Runners call bridge methods at the right points:
+ *   - dispatchTurnStart() before execution
+ *   - dispatchLLMCall() after extracting LLM response from snapshot
+ *   - dispatchTurnComplete() after successful execution
+ *   - dispatchError() on failure
+ */
+import type { AgentRecorder } from '../../core';
+import type { LLMResponse } from '../../types';
+import type { AgentStreamEvent } from '../../streaming';
+export declare class RecorderBridge {
+    private readonly recorders;
+    private turnNumber;
+    private loopIteration;
+    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): void;
+    /** Dispatch turn complete event. */
+    dispatchTurnComplete(content: string, messageCount: number, totalLoopIterations?: number): void;
+    /** Dispatch tool call event from stream events. */
+    dispatchToolCall(toolName: string, args: Record<string, unknown>, result: {
+        content: string;
+        error?: boolean;
+    }, latencyMs: number): void;
+    /**
+     * Create an onStreamEvent handler that bridges tool events to recorders.
+     * Attach this alongside the consumer's onEvent handler in AgentRunner.
+     */
+    createStreamEventBridge(): (event: AgentStreamEvent) => void;
+    /** Dispatch error event. */
+    dispatchError(phase: 'prompt' | 'llm' | 'tool' | 'message', error: unknown): void;
+    private dispatch;
+}
+//# sourceMappingURL=RecorderBridge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RecorderBridge.d.ts","sourceRoot":"","sources":["../../../../src/recorders/v2/RecorderBridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAgB,MAAM,YAAY,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD,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,CAAC,QAAQ,EAAE,WAAW,EAAE,SAAS,SAAI,GAAG,IAAI;IAY3D,oCAAoC;IACpC,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,mBAAmB,SAAI,GAAG,IAAI;IAW1F,mDAAmD;IACnD,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAIxI;;;OAGG;IACH,uBAAuB,IAAI,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI;IAgB5D,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/v2/TokenRecorder.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 } } });
+ */
+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 {
+    readonly totalCalls: number;
+    readonly totalInputTokens: number;
+    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[];
+}
+export interface LLMCallEntry {
+    readonly model: string;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    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;
+}
+export declare class TokenRecorder implements AgentRecorder {
+    readonly id: string;
+    private calls;
+    private readonly pricing;
+    constructor(options?: TokenRecorderOptions | string);
+    onLLMCall(event: LLMCallEvent): void;
+    getStats(): TokenStats;
+    getTotalTokens(): number;
+    clear(): void;
+}
+//# sourceMappingURL=TokenRecorder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TokenRecorder.d.ts","sourceRoot":"","sources":["../../../../src/recorders/v2/TokenRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,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"}

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

@@ -0,0 +1,34 @@
+/**
+ * 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());
+ */
+import type { AgentRecorder, ToolCallEvent } from '../../core';
+export interface ToolUsageStats {
+    readonly totalCalls: number;
+    readonly totalErrors: number;
+    readonly byTool: Record<string, ToolStats>;
+}
+export interface ToolStats {
+    readonly calls: number;
+    readonly errors: number;
+    readonly totalLatencyMs: number;
+    readonly averageLatencyMs: number;
+}
+export declare class ToolUsageRecorder implements AgentRecorder {
+    readonly id: string;
+    private toolCalls;
+    constructor(id?: string);
+    onToolCall(event: ToolCallEvent): void;
+    getStats(): ToolUsageStats;
+    getToolNames(): string[];
+    clear(): void;
+}
+//# sourceMappingURL=ToolUsageRecorder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ToolUsageRecorder.d.ts","sourceRoot":"","sources":["../../../../src/recorders/v2/ToolUsageRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE/D,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"}

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

@@ -0,0 +1,36 @@
+/**
+ * TurnRecorder — tracks turn-level lifecycle events.
+ *
+ * Records when turns start and complete, including message counts and
+ * loop iterations. Useful for debugging multi-turn conversations and
+ * understanding agent behavior over time.
+ *
+ * Usage:
+ *   const turns = new TurnRecorder();
+ *   agent.recorder(turns);
+ *   await agent.run(...);
+ *   console.log(turns.getTurns());
+ */
+import type { AgentRecorder, TurnStartEvent, TurnCompleteEvent, AgentErrorEvent } from '../../core';
+export interface TurnEntry {
+    readonly turnNumber: number;
+    readonly message: string;
+    readonly content?: string;
+    readonly messageCount?: number;
+    readonly totalLoopIterations?: number;
+    readonly error?: unknown;
+    readonly status: 'started' | 'completed' | 'error';
+}
+export declare class TurnRecorder implements AgentRecorder {
+    readonly id: string;
+    private turns;
+    constructor(id?: string);
+    onTurnStart(event: TurnStartEvent): void;
+    onTurnComplete(event: TurnCompleteEvent): void;
+    onError(event: AgentErrorEvent): void;
+    getTurns(): TurnEntry[];
+    getCompletedCount(): number;
+    getErrorCount(): number;
+    clear(): void;
+}
+//# sourceMappingURL=TurnRecorder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TurnRecorder.d.ts","sourceRoot":"","sources":["../../../../src/recorders/v2/TurnRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEpG,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,OAAO,CAAC;CACpD;AAED,qBAAa,YAAa,YAAW,aAAa;IAChD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,KAAK,CAAmB;gBAEpB,EAAE,SAAkB;IAIhC,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IAQxC,cAAc,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI;IAyB9C,OAAO,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAsBrC,QAAQ,IAAI,SAAS,EAAE;IAIvB,iBAAiB,IAAI,MAAM;IAI3B,aAAa,IAAI,MAAM;IAIvB,KAAK,IAAI,IAAI;CAGd"}

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

@@ -0,0 +1,68 @@
+/**
+ * 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.
+ *
+ * Stage-level timing is auto-attached by the runners (MetricRecorder on the
+ * executor) — this preset covers the agent-level concerns only.
+ *
+ * @example
+ * ```typescript
+ * import { Agent, agentObservability } from 'agentfootprint';
+ *
+ * // One call — tokens, tools, and cost tracking
+ * const obs = agentObservability();
+ * const agent = Agent.create({ provider })
+ *   .recorder(obs)
+ *   .build();
+ *
+ * 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 },
+ *   },
+ * });
+ * ```
+ */
+import type { ModelPricing, CostEntry } from './CostRecorder';
+import type { TokenStats } from './TokenRecorder';
+import type { ToolUsageStats } from './ToolUsageRecorder';
+import { CompositeRecorder } from './CompositeRecorder';
+export interface AgentObservabilityOptions {
+    /** Custom ID for the composite recorder. Default: 'agent-observability'. */
+    id?: string;
+    /** Pricing table for cost estimation (per 1M tokens). Models not listed get $0. */
+    pricing?: Record<string, ModelPricing>;
+}
+/** Return type of agentObservability() with convenience accessors. */
+export interface AgentObservabilityRecorder extends CompositeRecorder {
+    /** Token usage stats across all LLM calls. */
+    tokens(): TokenStats;
+    /** Tool usage stats — calls, errors, latency by tool name. */
+    tools(): ToolUsageStats;
+    /** Total estimated USD cost. */
+    cost(): number;
+    /** Per-call cost breakdown. */
+    costEntries(): CostEntry[];
+}
+/**
+ * Create a bundled agent observability recorder.
+ *
+ * Tracks tokens, tool usage, and cost in a single `.recorder()` call.
+ * Stage timing is handled separately by MetricRecorder (auto-attached by runners).
+ */
+export declare function agentObservability(options?: AgentObservabilityOptions): AgentObservabilityRecorder;
+//# sourceMappingURL=agentObservability.d.ts.map

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

@@ -0,0 +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,CAAC,OAAO,CAAC,EAAE,yBAAyB,GAAG,0BAA0B,CAmBlG"}

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

@@ -0,0 +1,21 @@
+/**
+ * recorders/ — AgentRecorder implementations.
+ */
+export { TokenRecorder } from './TokenRecorder';
+export type { TokenStats, LLMCallEntry } from './TokenRecorder';
+export { CostRecorder } from './CostRecorder';
+export type { CostEntry, CostRecorderOptions, ModelPricing, } from './CostRecorder';
+export { ToolUsageRecorder } from './ToolUsageRecorder';
+export type { ToolUsageStats, ToolStats } from './ToolUsageRecorder';
+export { TurnRecorder } from './TurnRecorder';
+export type { TurnEntry } from './TurnRecorder';
+export { QualityRecorder } from './QualityRecorder';
+export type { QualityScore, QualityJudge } from './QualityRecorder';
+export { GuardrailRecorder } from './GuardrailRecorder';
+export type { Violation, GuardrailCheck } from './GuardrailRecorder';
+export { CompositeRecorder } from './CompositeRecorder';
+export { PermissionRecorder } from './PermissionRecorder';
+export type { PermissionEvent } from './PermissionRecorder';
+export { agentObservability } from './agentObservability';
+export type { AgentObservabilityOptions, AgentObservabilityRecorder } from './agentObservability';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/recorders/v2/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EACV,SAAS,EACT,mBAAmB,EACnB,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,YAAY,EAAE,yBAAyB,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC"}

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

@@ -0,0 +1,18 @@
+/**
+ * agentfootprint/resilience — Make agents reliable.
+ *
+ * Retry, fallback, circuit breaker, cross-family provider failover.
+ *
+ * @example
+ * ```typescript
+ * import { withRetry, resilientProvider } from 'agentfootprint/resilience';
+ *
+ * const reliable = withRetry(agent, { maxRetries: 3 });
+ * const provider = resilientProvider([anthropicAdapter, openaiAdapter]);
+ * ```
+ */
+export { withRetry, withFallback, withCircuitBreaker, CircuitBreaker } from './compositions';
+export type { RetryOptions, FallbackOptions, CircuitBreakerOptions, CircuitState } from './compositions';
+export { resilientProvider, fallbackProvider } from './adapters';
+export type { ResilientProviderOptions, FallbackProviderOptions } from './adapters';
+//# sourceMappingURL=resilience.barrel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resilience.barrel.d.ts","sourceRoot":"","sources":["../../src/resilience.barrel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC7F,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACzG,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACjE,YAAY,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC"}

package/dist/types/retriever.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Retriever types — the contract for retrieval providers.
+ * Users implement RetrieverProvider for their vector store (Pinecone, Chroma, pg_vector, etc.).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=retriever.js.map

package/dist/types/retriever.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retriever.js","sourceRoot":"","sources":["../../src/types/retriever.ts"],"names":[],"mappings":";AAAA;;;GAGG"}

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

@@ -0,0 +1,87 @@
+/**
+ * AgentScope — typed wrapper over ScopeFacade for agent state.
+ *
+ * Instead of raw scope.getValue('messages'), use scope.getMessages().
+ * All paths come from AGENT_PATHS constants (single source of truth).
+ */
+import type { ScopeFacade } from 'footprintjs/advanced';
+import type { Message, AdapterResult, LLMToolDescription, RetrievalResult, AgentResultEntry } from '../types';
+import type { ParsedResponse } from './types';
+/**
+ * Well-known scope paths for memory subflow state.
+ * These keys are internal to PrepareMemory/CommitMemory and are prefixed
+ * with `memory_` to avoid collision with agent state keys.
+ */
+export declare const MEMORY_PATHS: {
+    /** Raw history loaded from ConversationStore (PrepareMemory internal). */
+    readonly STORED_HISTORY: "memory_storedHistory";
+    /** Prepared messages after strategy applied (PrepareMemory output). */
+    readonly PREPARED_MESSAGES: "memory_preparedMessages";
+    /**
+     * Set to `true` by HandleResponse when the turn is finalizing (no more tool calls).
+     * CommitMemory reads this to know when to save + break the pipeline.
+     */
+    readonly SHOULD_COMMIT: "memory_shouldCommit";
+};
+/** Well-known scope paths for agent state. */
+export declare const AGENT_PATHS: {
+    readonly MESSAGES: "messages";
+    readonly SYSTEM_PROMPT: "systemPrompt";
+    readonly TOOL_DESCRIPTIONS: "toolDescriptions";
+    readonly ADAPTER_RESULT: "adapterResult";
+    readonly PARSED_RESPONSE: "parsedResponse";
+    readonly LOOP_COUNT: "loopCount";
+    readonly MAX_ITERATIONS: "maxIterations";
+    readonly RESULT: "result";
+};
+/** Well-known scope paths for multi-agent pipeline state. */
+export declare const MULTI_AGENT_PATHS: {
+    readonly PIPELINE_INPUT: "pipelineInput";
+    readonly AGENT_RESULTS: "agentResults";
+    readonly RESULT: "result";
+    readonly SIGNAL: "_signal";
+    readonly TIMEOUT_MS: "_timeoutMs";
+};
+/** Well-known scope paths for RAG state. */
+export declare const RAG_PATHS: {
+    readonly RETRIEVAL_QUERY: "retrievalQuery";
+    readonly RETRIEVAL_RESULT: "retrievalResult";
+    readonly CONTEXT_WINDOW: "contextWindow";
+};
+/**
+ * Typed accessors for agent state in scope.
+ * These are pure functions — no class inheritance needed.
+ */
+export declare const AgentScope: {
+    readonly getMessages: (scope: ScopeFacade) => Message[];
+    readonly getSystemPrompt: (scope: ScopeFacade) => string | undefined;
+    readonly getToolDescriptions: (scope: ScopeFacade) => LLMToolDescription[];
+    readonly getAdapterResult: (scope: ScopeFacade) => AdapterResult | undefined;
+    readonly getParsedResponse: (scope: ScopeFacade) => ParsedResponse | undefined;
+    readonly getLoopCount: (scope: ScopeFacade) => number;
+    readonly getMaxIterations: (scope: ScopeFacade) => number;
+    readonly getResult: (scope: ScopeFacade) => string | undefined;
+    readonly setMessages: (scope: ScopeFacade, messages: Message[]) => void;
+    readonly setSystemPrompt: (scope: ScopeFacade, prompt: string) => void;
+    readonly setToolDescriptions: (scope: ScopeFacade, tools: LLMToolDescription[]) => void;
+    readonly setAdapterResult: (scope: ScopeFacade, result: AdapterResult) => void;
+    readonly setParsedResponse: (scope: ScopeFacade, parsed: ParsedResponse) => void;
+    readonly setLoopCount: (scope: ScopeFacade, count: number) => void;
+    readonly setMaxIterations: (scope: ScopeFacade, max: number) => void;
+    readonly setResult: (scope: ScopeFacade, result: string) => void;
+    readonly getRetrievalQuery: (scope: ScopeFacade) => string | undefined;
+    readonly getRetrievalResult: (scope: ScopeFacade) => RetrievalResult | undefined;
+    readonly getContextWindow: (scope: ScopeFacade) => string | undefined;
+    readonly setRetrievalQuery: (scope: ScopeFacade, query: string) => void;
+    readonly setRetrievalResult: (scope: ScopeFacade, result: RetrievalResult) => void;
+    readonly setContextWindow: (scope: ScopeFacade, context: string) => void;
+    readonly getPipelineInput: (scope: ScopeFacade) => string | undefined;
+    readonly getAgentResults: (scope: ScopeFacade) => AgentResultEntry[];
+    readonly setPipelineInput: (scope: ScopeFacade, input: string) => void;
+    readonly setAgentResults: (scope: ScopeFacade, results: AgentResultEntry[]) => void;
+    readonly getShouldCommit: (scope: ScopeFacade) => boolean;
+    readonly getStoredHistory: (scope: ScopeFacade) => Message[];
+    readonly getPreparedMessages: (scope: ScopeFacade) => Message[];
+    readonly setShouldCommit: (scope: ScopeFacade, value: boolean) => void;
+};
+//# sourceMappingURL=AgentScope.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AgentScope.d.ts","sourceRoot":"","sources":["../../../src/scope/AgentScope.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EACV,OAAO,EACP,aAAa,EACb,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EACjB,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,YAAY;IACvB,0EAA0E;;IAE1E,uEAAuE;;IAEvE;;;OAGG;;CAEK,CAAC;AAEX,8CAA8C;AAC9C,eAAO,MAAM,WAAW;;;;;;;;;CASd,CAAC;AAEX,6DAA6D;AAC7D,eAAO,MAAM,iBAAiB;;;;;;CAMpB,CAAC;AAEX,4CAA4C;AAC5C,eAAO,MAAM,SAAS;;;;CAIZ,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,UAAU;kCAGF,WAAW,KAAG,OAAO,EAAE;sCAKnB,WAAW,KAAG,MAAM,GAAG,SAAS;0CAI5B,WAAW,KAAG,kBAAkB,EAAE;uCAIrC,WAAW,KAAG,aAAa,GAAG,SAAS;wCAItC,WAAW,KAAG,cAAc,GAAG,SAAS;mCAI7C,WAAW,KAAG,MAAM;uCAIhB,WAAW,KAAG,MAAM;gCAI3B,WAAW,KAAG,MAAM,GAAG,SAAS;kCAM9B,WAAW,YAAY,OAAO,EAAE,KAAG,IAAI;sCAInC,WAAW,UAAU,MAAM,KAAG,IAAI;0CAI9B,WAAW,SAAS,kBAAkB,EAAE,KAAG,IAAI;uCAIlD,WAAW,UAAU,aAAa,KAAG,IAAI;wCAIxC,WAAW,UAAU,cAAc,KAAG,IAAI;mCAI/C,WAAW,SAAS,MAAM,KAAG,IAAI;uCAI7B,WAAW,OAAO,MAAM,KAAG,IAAI;gCAItC,WAAW,UAAU,MAAM,KAAG,IAAI;wCAM1B,WAAW,KAAG,MAAM,GAAG,SAAS;yCAI/B,WAAW,KAAG,eAAe,GAAG,SAAS;uCAI3C,WAAW,KAAG,MAAM,GAAG,SAAS;wCAM/B,WAAW,SAAS,MAAM,KAAG,IAAI;yCAIhC,WAAW,UAAU,eAAe,KAAG,IAAI;uCAI7C,WAAW,WAAW,MAAM,KAAG,IAAI;uCAMnC,WAAW,KAAG,MAAM,GAAG,SAAS;sCAIjC,WAAW,KAAG,gBAAgB,EAAE;uCAM/B,WAAW,SAAS,MAAM,KAAG,IAAI;sCAIlC,WAAW,WAAW,gBAAgB,EAAE,KAAG,IAAI;sCAM/C,WAAW,KAAG,OAAO;uCAIpB,WAAW,KAAG,OAAO,EAAE;0CAIpB,WAAW,KAAG,OAAO,EAAE;sCAM3B,WAAW,SAAS,OAAO,KAAG,IAAI;CAGjD,CAAC"}

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

@@ -0,0 +1,3 @@
+export { AgentScope, AGENT_PATHS, RAG_PATHS, MULTI_AGENT_PATHS, MEMORY_PATHS } from './AgentScope';
+export type { ParsedResponse, AgentLoopState, SystemPromptSubflowState, ToolsSubflowState, MessagesSubflowState, RAGState, MultiAgentState, } from './types';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/scope/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,SAAS,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACnG,YAAY,EACV,cAAc,EACd,cAAc,EACd,wBAAwB,EACxB,iBAAiB,EACjB,oBAAoB,EACpB,QAAQ,EACR,eAAe,GAChB,MAAM,SAAS,CAAC"}