agentfootprint 1.0.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"CompositeRecorder.js","sourceRoot":"","sources":["../../../src/recorders/v2/CompositeRecorder.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAWH,MAAa,iBAAiB;IACnB,EAAE,CAAS;IACH,SAAS,CAA2B;IAErD,YAAY,SAAmC,EAAE,EAAE,GAAG,oBAAoB;QACxE,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;IACf,CAAC;IAED,WAAW,CAAC,KAAqB;QAC/B,IAAI,CAAC,QAAQ,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;IACtC,CAAC;IAED,SAAS,CAAC,KAAmB;QAC3B,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;IACpC,CAAC;IAED,UAAU,CAAC,KAAoB;QAC7B,IAAI,CAAC,QAAQ,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;IACrC,CAAC;IAED,cAAc,CAAC,KAAwB;QACrC,IAAI,CAAC,QAAQ,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC;IACzC,CAAC;IAED,OAAO,CAAC,KAAsB;QAC5B,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IAClC,CAAC;IAED,KAAK;QACH,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACtC,IAAI,CAAC;gBACH,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC;YACrB,CAAC;YAAC,MAAM,CAAC;gBACP,qBAAqB;YACvB,CAAC;QACH,CAAC;IACH,CAAC;IAED,6CAA6C;IAC7C,YAAY;QACV,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAEO,QAAQ,CAAC,IAAyB,EAAE,KAAc;QACxD,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACtC,IAAI,CAAC;gBACH,MAAM,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;gBAC1B,IAAI,OAAO,EAAE,KAAK,UAAU,EAAE,CAAC;oBAC5B,EAA2B,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;gBACrD,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,gEAAgE;YAClE,CAAC;QACH,CAAC;IACH,CAAC;CACF;AAxDD,8CAwDC"}

package/dist/recorders/v2/CostRecorder.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * CostRecorder (v2) — 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)}`);
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CostRecorder = void 0;
+class CostRecorder {
+    id;
+    entries = [];
+    pricingTable;
+    constructor(options = {}) {
+        this.id = options.id ?? 'cost-recorder';
+        this.pricingTable = options.pricingTable ?? {};
+    }
+    onLLMCall(event) {
+        const model = event.model ?? 'unknown';
+        const inputTokens = event.usage?.inputTokens ?? 0;
+        const outputTokens = event.usage?.outputTokens ?? 0;
+        const pricing = this.pricingTable[model];
+        const inputCost = pricing ? (inputTokens / 1_000_000) * pricing.input : 0;
+        const outputCost = pricing ? (outputTokens / 1_000_000) * pricing.output : 0;
+        this.entries.push({
+            model,
+            inputTokens,
+            outputTokens,
+            inputCost,
+            outputCost,
+            totalCost: inputCost + outputCost,
+        });
+    }
+    getTotalCost() {
+        return this.entries.reduce((s, e) => s + e.totalCost, 0);
+    }
+    getEntries() {
+        return [...this.entries];
+    }
+    clear() {
+        this.entries = [];
+    }
+}
+exports.CostRecorder = CostRecorder;
+//# sourceMappingURL=CostRecorder.js.map

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

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

package/dist/recorders/v2/ExplainRecorder.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * ExplainRecorder — collects grounding evidence during traversal.
+ *
+ * Captures sources (tool results), claims (LLM output), and decisions
+ * as they happen — no post-processing of narrative entries.
+ *
+ * Usage:
+ *   const explain = new ExplainRecorder();
+ *   agent.recorder(explain);
+ *   await agent.run('Check order');
+ *
+ *   explain.getSources();    // tool results (ground truth)
+ *   explain.getClaims();     // LLM responses (to verify)
+ *   explain.getDecisions();  // tool call decisions (what the LLM chose to do)
+ *   explain.explain();       // structured summary
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExplainRecorder = void 0;
+class ExplainRecorder {
+    id;
+    sources = [];
+    claims = [];
+    decisions = [];
+    currentTurn = 0;
+    constructor(id = 'explain-recorder') {
+        this.id = id;
+    }
+    onTurnStart(event) {
+        this.currentTurn = event.turnNumber;
+    }
+    lastModel;
+    lastIteration = 0;
+    onLLMCall(event) {
+        // Track model/iteration for claim attribution
+        this.lastModel = event.model;
+        this.lastIteration = event.loopIteration;
+    }
+    onToolCall(event) {
+        // Tool result = source of truth (shallow clone args to prevent mutation)
+        this.sources.push({
+            toolName: event.toolName,
+            args: { ...event.args },
+            result: String(event.result.content),
+            turnNumber: this.currentTurn,
+        });
+        // Tool call = decision the LLM made
+        this.decisions.push({
+            toolName: event.toolName,
+            args: { ...event.args },
+            latencyMs: event.latencyMs,
+        });
+    }
+    onTurnComplete(event) {
+        // Capture the final LLM response as a claim — always, regardless of prior events
+        this.claims.push({
+            content: event.content,
+            model: this.lastModel,
+            iteration: this.lastIteration,
+        });
+    }
+    /** Tool results — the ground truth data. */
+    getSources() {
+        return [...this.sources];
+    }
+    /** LLM responses — what it claimed. */
+    getClaims() {
+        return [...this.claims];
+    }
+    /** Tool call decisions — what the LLM chose to do. Returns snapshot-safe copies. */
+    getDecisions() {
+        return this.decisions.map(d => ({ ...d, args: { ...d.args } }));
+    }
+    /** Structured explanation of the agent's execution. */
+    explain() {
+        const toolNames = [...new Set(this.decisions.map(d => d.toolName))];
+        const summary = this.sources.length === 0
+            ? `Agent responded directly without calling tools.`
+            : `Agent called ${toolNames.join(', ')} (${this.sources.length} call${this.sources.length > 1 ? 's' : ''}), then responded based on the results.`;
+        return {
+            sources: this.getSources(),
+            claims: this.getClaims(),
+            decisions: this.getDecisions(),
+            summary,
+        };
+    }
+    clear() {
+        this.sources = [];
+        this.claims = [];
+        this.decisions = [];
+        this.currentTurn = 0;
+        this.lastModel = undefined;
+        this.lastIteration = 0;
+    }
+}
+exports.ExplainRecorder = ExplainRecorder;
+//# sourceMappingURL=ExplainRecorder.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ExplainRecorder.js","sourceRoot":"","sources":["../../../src/recorders/v2/ExplainRecorder.ts"],"names":[],"mappings":"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"}

package/dist/recorders/v2/GuardrailRecorder.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * GuardrailRecorder — checks safety/policy constraints during execution.
+ *
+ * Calls a check function on each turn completion. If the check returns
+ * a violation, it is recorded. Violations can be reviewed after execution
+ * or used to trigger alerts.
+ *
+ * The check function receives the turn completion event and returns
+ * either null (no violation) or a Violation object.
+ *
+ * Usage:
+ *   const guardrail = new GuardrailRecorder(async (event) => {
+ *     if (event.content.includes('CONFIDENTIAL')) {
+ *       return { rule: 'pii-leak', message: 'Output contains confidential data' };
+ *     }
+ *     return null;
+ *   });
+ *   agent.recorder(guardrail);
+ *   await agent.run(...);
+ *   if (guardrail.hasViolations()) { ... }
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GuardrailRecorder = void 0;
+// ── Recorder ─────────────────────────────────────────────────
+class GuardrailRecorder {
+    id;
+    check;
+    violations = [];
+    constructor(check, id = 'guardrail-recorder') {
+        this.check = check;
+        this.id = id;
+    }
+    onTurnComplete(event) {
+        const result = this.check(event);
+        if (result instanceof Promise) {
+            result
+                .then((v) => {
+                if (v)
+                    this.violations.push(v);
+            })
+                .catch(() => { });
+        }
+        else if (result) {
+            this.violations.push(result);
+        }
+    }
+    getViolations() {
+        return [...this.violations];
+    }
+    hasViolations() {
+        return this.violations.length > 0;
+    }
+    getViolationsByRule(rule) {
+        return this.violations.filter((v) => v.rule === rule);
+    }
+    clear() {
+        this.violations = [];
+    }
+}
+exports.GuardrailRecorder = GuardrailRecorder;
+//# sourceMappingURL=GuardrailRecorder.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GuardrailRecorder.js","sourceRoot":"","sources":["../../../src/recorders/v2/GuardrailRecorder.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAqBH,gEAAgE;AAEhE,MAAa,iBAAiB;IACnB,EAAE,CAAS;IACH,KAAK,CAAiB;IAC/B,UAAU,GAAgB,EAAE,CAAC;IAErC,YAAY,KAAqB,EAAE,EAAE,GAAG,oBAAoB;QAC1D,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;IACf,CAAC;IAED,cAAc,CAAC,KAAwB;QACrC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACjC,IAAI,MAAM,YAAY,OAAO,EAAE,CAAC;YAC9B,MAAM;iBACH,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE;gBACV,IAAI,CAAC;oBAAE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACjC,CAAC,CAAC;iBACD,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACrB,CAAC;aAAM,IAAI,MAAM,EAAE,CAAC;YAClB,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IAED,aAAa;QACX,OAAO,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;IAC9B,CAAC;IAED,aAAa;QACX,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC;IACpC,CAAC;IAED,mBAAmB,CAAC,IAAY;QAC9B,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IACxD,CAAC;IAED,KAAK;QACH,IAAI,CAAC,UAAU,GAAG,EAAE,CAAC;IACvB,CAAC;CACF;AAtCD,8CAsCC"}

package/dist/recorders/v2/OTelRecorder.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * OTelRecorder — exports agent events as OpenTelemetry spans.
+ *
+ * Takes a duck-typed Tracer from the consumer — zero @opentelemetry dependency in core.
+ * Follows OpenTelemetry Semantic Conventions for GenAI where applicable.
+ *
+ * Usage:
+ *   import { trace } from '@opentelemetry/api';
+ *   import { OTelRecorder } from 'agentfootprint/observe';
+ *
+ *   const recorder = new OTelRecorder(trace.getTracer('agentfootprint'));
+ *   agent.recorder(recorder);
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OTelRecorder = void 0;
+class OTelRecorder {
+    id;
+    tracer;
+    serviceName;
+    turnSpan;
+    constructor(tracer, options) {
+        this.tracer = tracer;
+        this.id = options?.id ?? 'otel-recorder';
+        this.serviceName = options?.serviceName ?? 'agentfootprint';
+    }
+    onTurnStart(event) {
+        this.turnSpan = this.tracer.startSpan('agent.turn', {
+            attributes: {
+                'gen_ai.system': this.serviceName,
+                'agent.turn_number': event.turnNumber,
+            },
+        });
+    }
+    onLLMCall(event) {
+        const span = this.tracer.startSpan('gen_ai.chat', {
+            attributes: {
+                'gen_ai.system': this.serviceName,
+                'gen_ai.request.model': event.model ?? 'unknown',
+                'gen_ai.response.finish_reason': event.finishReason ?? 'unknown',
+                'gen_ai.usage.input_tokens': event.usage?.inputTokens ?? 0,
+                'gen_ai.usage.output_tokens': event.usage?.outputTokens ?? 0,
+                'gen_ai.response.latency_ms': event.latencyMs,
+                'agent.loop_iteration': event.loopIteration,
+            },
+        });
+        span.end();
+    }
+    onToolCall(event) {
+        const span = this.tracer.startSpan(`tool.${event.toolName}`, {
+            attributes: {
+                'tool.name': event.toolName,
+                'tool.latency_ms': event.latencyMs,
+                'tool.error': Boolean(event.result.error),
+            },
+        });
+        span.end();
+    }
+    onTurnComplete(event) {
+        if (this.turnSpan) {
+            this.turnSpan.setAttribute('agent.iterations', event.totalLoopIterations);
+            this.turnSpan.setAttribute('agent.message_count', event.messageCount);
+            this.turnSpan.end();
+            this.turnSpan = undefined;
+        }
+    }
+    onError(event) {
+        const span = this.tracer.startSpan('agent.error', {
+            attributes: {
+                'error.phase': event.phase,
+                'error.type': event.error instanceof Error ? event.error.name : 'unknown',
+            },
+        });
+        // OTel StatusCode.ERROR = 2
+        span.setStatus?.({ code: 2, message: event.error instanceof Error ? event.error.message : String(event.error) });
+        span.end();
+    }
+    clear() {
+        this.turnSpan = undefined;
+    }
+}
+exports.OTelRecorder = OTelRecorder;
+//# sourceMappingURL=OTelRecorder.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"OTelRecorder.js","sourceRoot":"","sources":["../../../src/recorders/v2/OTelRecorder.ts"],"names":[],"mappings":"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"}

package/dist/recorders/v2/PermissionRecorder.js

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * 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: [...] }
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PermissionRecorder = void 0;
+class PermissionRecorder {
+    id = 'permission-recorder';
+    events = [];
+    /**
+     * Wire this to gatedTools({ onBlocked: recorder.onBlocked }).
+     * Arrow function — safe to pass as callback directly.
+     */
+    onBlocked = (toolId, phase, _context) => {
+        this.events.push({
+            type: phase === 'resolve' ? 'blocked' : 'denied',
+            toolId,
+            phase,
+            timestamp: Date.now(),
+        });
+    };
+    /** AgentRecorder hook — captures successful tool calls. */
+    onToolCall(event) {
+        if (!event.result.error) {
+            this.events.push({
+                type: 'allowed',
+                toolId: event.toolName,
+                phase: 'execute',
+                timestamp: Date.now(),
+            });
+        }
+    }
+    /** All permission events in order. */
+    getEvents() {
+        return this.events;
+    }
+    /** Tools blocked at resolve time (LLM never saw them). */
+    getBlocked() {
+        return [...new Set(this.events.filter((e) => e.type === 'blocked').map((e) => e.toolId))];
+    }
+    /** Tool calls denied at execute time (hallucinated/injected). */
+    getDenied() {
+        return [...new Set(this.events.filter((e) => e.type === 'denied').map((e) => e.toolId))];
+    }
+    /** Tools that were allowed and executed successfully. */
+    getAllowed() {
+        return [...new Set(this.events.filter((e) => e.type === 'allowed').map((e) => e.toolId))];
+    }
+    /** Summary for audit logging. */
+    getSummary() {
+        return {
+            allowed: this.getAllowed(),
+            blocked: this.getBlocked(),
+            denied: this.getDenied(),
+        };
+    }
+    clear() {
+        this.events = [];
+    }
+}
+exports.PermissionRecorder = PermissionRecorder;
+//# sourceMappingURL=PermissionRecorder.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PermissionRecorder.js","sourceRoot":"","sources":["../../../src/recorders/v2/PermissionRecorder.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;;;AAYH,MAAa,kBAAkB;IACpB,EAAE,GAAG,qBAAqB,CAAC;IAC5B,MAAM,GAAsB,EAAE,CAAC;IAEvC;;;OAGG;IACM,SAAS,GAAG,CAAC,MAAc,EAAE,KAA4B,EAAE,QAAsB,EAAQ,EAAE;QAClG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ;YAChD,MAAM;YACN,KAAK;YACL,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;SACtB,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,2DAA2D;IAC3D,UAAU,CAAC,KAAoB;QAC7B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YACxB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;gBACf,IAAI,EAAE,SAAS;gBACf,MAAM,EAAE,KAAK,CAAC,QAAQ;gBACtB,KAAK,EAAE,SAAS;gBAChB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;aACtB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,sCAAsC;IACtC,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,0DAA0D;IAC1D,UAAU;QACR,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAC5F,CAAC;IAED,iEAAiE;IACjE,SAAS;QACP,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAC3F,CAAC;IAED,yDAAyD;IACzD,UAAU;QACR,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAC5F,CAAC;IAED,iCAAiC;IACjC,UAAU;QACR,OAAO;YACL,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE;YAC1B,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE;YAC1B,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE;SACzB,CAAC;IACJ,CAAC;IAED,KAAK;QACH,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC;IACnB,CAAC;CACF;AA7DD,gDA6DC"}

package/dist/recorders/v2/QualityRecorder.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * 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());
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QualityRecorder = void 0;
+// ── Recorder ─────────────────────────────────────────────────
+class QualityRecorder {
+    id;
+    judge;
+    scores = [];
+    constructor(judge, id = 'quality-recorder') {
+        this.judge = judge;
+        this.id = id;
+    }
+    onTurnComplete(event) {
+        // Fire-and-forget — eval must not block execution
+        const result = this.judge(event);
+        if (result instanceof Promise) {
+            result.then((s) => this.scores.push(s)).catch(() => { });
+        }
+        else {
+            this.scores.push(result);
+        }
+    }
+    getScores() {
+        return [...this.scores];
+    }
+    getAverageScore() {
+        if (this.scores.length === 0)
+            return 0;
+        return this.scores.reduce((sum, s) => sum + s.score, 0) / this.scores.length;
+    }
+    clear() {
+        this.scores = [];
+    }
+}
+exports.QualityRecorder = QualityRecorder;
+//# sourceMappingURL=QualityRecorder.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"QualityRecorder.js","sourceRoot":"","sources":["../../../src/recorders/v2/QualityRecorder.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;;AAiBH,gEAAgE;AAEhE,MAAa,eAAe;IACjB,EAAE,CAAS;IACH,KAAK,CAAe;IAC7B,MAAM,GAAmB,EAAE,CAAC;IAEpC,YAAY,KAAmB,EAAE,EAAE,GAAG,kBAAkB;QACtD,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;IACf,CAAC;IAED,cAAc,CAAC,KAAwB;QACrC,kDAAkD;QAClD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACjC,IAAI,MAAM,YAAY,OAAO,EAAE,CAAC;YAC9B,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAC1D,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,SAAS;QACP,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IAC1B,CAAC;IAED,eAAe;QACb,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,CAAC,CAAC;QACvC,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;IAC/E,CAAC;IAED,KAAK;QACH,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC;IACnB,CAAC;CACF;AAhCD,0CAgCC"}

package/dist/recorders/v2/RecorderBridge.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RecorderBridge = void 0;
+class RecorderBridge {
+    recorders;
+    turnNumber = 1;
+    loopIteration = 0;
+    constructor(recorders) {
+        this.recorders = recorders;
+    }
+    /** Dispatch turn start event. */
+    dispatchTurnStart(message) {
+        this.dispatch('onTurnStart', { turnNumber: this.turnNumber, message });
+    }
+    /** Dispatch LLM call event from the adapter response stored in scope. */
+    dispatchLLMCall(response, latencyMs = 0) {
+        const event = {
+            model: response.model,
+            usage: response.usage,
+            latencyMs,
+            turnNumber: this.turnNumber,
+            loopIteration: this.loopIteration,
+            finishReason: response.finishReason,
+        };
+        this.dispatch('onLLMCall', event);
+    }
+    /** Dispatch turn complete event. */
+    dispatchTurnComplete(content, messageCount, totalLoopIterations = 0) {
+        this.dispatch('onTurnComplete', {
+            turnNumber: this.turnNumber,
+            messageCount,
+            totalLoopIterations,
+            content,
+        });
+        this.turnNumber++;
+        this.loopIteration = 0;
+    }
+    /** Dispatch tool call event from stream events. */
+    dispatchToolCall(toolName, args, result, latencyMs) {
+        this.dispatch('onToolCall', { toolName, args, result, latencyMs });
+    }
+    /**
+     * Create an onStreamEvent handler that bridges tool events to recorders.
+     * Attach this alongside the consumer's onEvent handler in AgentRunner.
+     */
+    createStreamEventBridge() {
+        const pendingTools = new Map();
+        return (event) => {
+            if (event.type === 'tool_start') {
+                pendingTools.set(event.toolCallId, { name: event.toolName, args: event.args, startMs: Date.now() });
+            }
+            else if (event.type === 'tool_end') {
+                const pending = pendingTools.get(event.toolCallId);
+                if (pending) {
+                    this.dispatchToolCall(pending.name, pending.args, { content: event.result, error: event.error }, event.latencyMs);
+                    pendingTools.delete(event.toolCallId);
+                }
+            }
+        };
+    }
+    /** Dispatch error event. */
+    dispatchError(phase, error) {
+        this.dispatch('onError', { phase, error, turnNumber: this.turnNumber });
+    }
+    dispatch(hook, event) {
+        for (const recorder of this.recorders) {
+            try {
+                const fn = recorder[hook];
+                if (typeof fn === 'function') {
+                    fn.call(recorder, event);
+                }
+            }
+            catch {
+                // Error isolation
+            }
+        }
+    }
+}
+exports.RecorderBridge = RecorderBridge;
+//# sourceMappingURL=RecorderBridge.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RecorderBridge.js","sourceRoot":"","sources":["../../../src/recorders/v2/RecorderBridge.ts"],"names":[],"mappings":"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"}

package/dist/recorders/v2/TokenRecorder.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * 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 } } });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenRecorder = void 0;
+class TokenRecorder {
+    id;
+    calls = [];
+    pricing;
+    constructor(options) {
+        if (typeof options === 'string') {
+            // Backward compat: new TokenRecorder('my-id')
+            this.id = options;
+            this.pricing = {};
+        }
+        else {
+            this.id = options?.id ?? 'token-recorder';
+            this.pricing = options?.pricing ?? {};
+        }
+    }
+    onLLMCall(event) {
+        const model = event.model ?? 'unknown';
+        const inputTokens = event.usage?.inputTokens ?? 0;
+        const outputTokens = event.usage?.outputTokens ?? 0;
+        const p = this.pricing[model];
+        const cost = p
+            ? (inputTokens / 1_000_000) * p.input + (outputTokens / 1_000_000) * p.output
+            : 0;
+        this.calls.push({
+            model,
+            inputTokens,
+            outputTokens,
+            latencyMs: event.latencyMs,
+            turnNumber: event.turnNumber,
+            loopIteration: event.loopIteration,
+            cost,
+        });
+    }
+    getStats() {
+        const totalCalls = this.calls.length;
+        const totalInputTokens = this.calls.reduce((s, c) => s + c.inputTokens, 0);
+        const totalOutputTokens = this.calls.reduce((s, c) => s + c.outputTokens, 0);
+        const totalLatencyMs = this.calls.reduce((s, c) => s + c.latencyMs, 0);
+        const totalCost = this.calls.reduce((s, c) => s + c.cost, 0);
+        return {
+            totalCalls,
+            totalInputTokens,
+            totalOutputTokens,
+            totalLatencyMs,
+            averageLatencyMs: totalCalls > 0 ? Math.round(totalLatencyMs / totalCalls) : 0,
+            totalCost,
+            calls: [...this.calls],
+        };
+    }
+    getTotalTokens() {
+        return this.calls.reduce((s, c) => s + c.inputTokens + c.outputTokens, 0);
+    }
+    clear() {
+        this.calls = [];
+    }
+}
+exports.TokenRecorder = TokenRecorder;
+//# sourceMappingURL=TokenRecorder.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TokenRecorder.js","sourceRoot":"","sources":["../../../src/recorders/v2/TokenRecorder.ts"],"names":[],"mappings":"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"}