@esankhan3/anvil-agent-core 0.1.0

package/dist/router/router.js

@@ -0,0 +1,306 @@
+/**
+ * `LlmRouter` — single source of truth for routing, retries, fallbacks,
+ * rate-limits, spend tracking, and circuit breaking.
+ *
+ * Phase 5: walks the full fallback chain. Per-error gates control which
+ * fallback steps are eligible. content_policy / auth / invalid_request
+ * never trigger cross-provider fallback (security default).
+ */
+import { RouterError, classifyError } from './errors.js';
+import { DEFAULT_RETRY_POLICY, runWithRetry } from './retry.js';
+import { TokenBucketRateLimiter } from './rate-limiter.js';
+import { CircuitBreaker } from './circuit-breaker.js';
+export class LlmRouter {
+    config;
+    resolver;
+    rateLimiter;
+    circuitBreaker;
+    ledger;
+    newId;
+    now;
+    sleep;
+    random;
+    errorClassifiers;
+    constructor(deps) {
+        this.config = deps.config;
+        this.resolver = deps.resolver;
+        this.ledger = deps.ledger;
+        this.newId = deps.newId ?? defaultNewId;
+        this.now = deps.now ?? Date.now;
+        this.sleep = deps.sleep;
+        this.random = deps.random;
+        this.errorClassifiers = deps.errorClassifiers ?? {};
+        this.rateLimiter =
+            deps.rateLimiter ??
+                new TokenBucketRateLimiter({
+                    config: deps.config.rateLimit,
+                    now: deps.now,
+                    sleep: deps.sleep
+                        ? (ms) => deps.sleep(ms)
+                        : undefined,
+                    onRateLimit: deps.config.onRateLimit,
+                });
+        this.circuitBreaker =
+            deps.circuitBreaker ??
+                new CircuitBreaker({
+                    config: deps.config.circuitBreaker,
+                    now: deps.now,
+                });
+    }
+    /** Inspect the active config (immutable snapshot). */
+    getConfig() {
+        return this.config;
+    }
+    /**
+     * Resolve the route for a tag (or pinned model) and walk the chain
+     * primary → fallback[0] → fallback[1] until either success or the
+     * chain is exhausted.
+     *
+     * Per ADR R5:
+     *   - auth / content_policy / invalid_request never trigger fallback
+     *   - rate_limit / server_5xx / timeout default to the full chain;
+     *     RouteFallback.on can restrict per-step
+     *   - All attempts are ledgered (including failed ones with cost)
+     */
+    async invoke(opts) {
+        const startedAt = this.now();
+        if (!this.resolver) {
+            throw new Error('LlmRouter.invoke requires an AdapterResolver (deps.resolver)');
+        }
+        // Pre-flight budget enforcement (Phase 4)
+        this.enforceBudgetPreflight(opts);
+        const chain = this.buildChain(opts);
+        const allAttempts = [];
+        let totalCostUsd = 0;
+        let lastError;
+        let lastErrorClass;
+        let priorAttempted = false; // true once any step has actually run
+        const maxCost = this.config.maxFallbackCostUsd ?? 1.0;
+        for (let step = 0; step < chain.length; step += 1) {
+            const link = chain[step];
+            const adapter = this.resolver.resolve(link.model);
+            // Skip non-primary steps whose `on` gate doesn't match the previous
+            // error. If no step has yet attempted (e.g., circuit breaker skipped
+            // every prior step) we let the fallback run regardless of its gate —
+            // there's no prior error to filter against.
+            if (step > 0 && priorAttempted && !this.shouldTryFallback(link, lastErrorClass)) {
+                continue;
+            }
+            // Circuit-breaker — if open, skip this provider entirely (no adapter
+            // call, no rate-limit consumption, no ledger row).
+            if (!this.circuitBreaker.canAttempt(adapter.provider)) {
+                continue;
+            }
+            this.circuitBreaker.reserveAttempt(adapter.provider);
+            priorAttempted = true;
+            const llmOpts = this.buildInvokeOpts(opts, link.model);
+            const estimatedTokens = this.estimateTokens(llmOpts);
+            const policyFor = (cls) => this.config.retryPolicy[cls] ?? DEFAULT_RETRY_POLICY[cls];
+            const classify = (err) => {
+                const override = this.errorClassifiers[adapter.provider];
+                return override?.(err) ?? classifyError(err);
+            };
+            const retryRun = await runWithRetry(async () => {
+                await this.rateLimiter.acquire(adapter.provider, estimatedTokens);
+                return adapter.invoke(llmOpts);
+            }, {
+                policyFor,
+                classify,
+                sleep: this.sleep,
+                now: this.now,
+                random: this.random,
+                signal: opts.signal,
+            });
+            const stepAttempts = retryRun.attempts.map((a) => ({
+                model: link.model,
+                provider: adapter.provider,
+                attemptIndex: a.index,
+                fallbackIndex: step,
+                errorClass: a.errorClass,
+                durationMs: a.durationMs,
+                costUsd: undefined,
+            }));
+            allAttempts.push(...stepAttempts);
+            if (retryRun.result) {
+                const last = stepAttempts[stepAttempts.length - 1];
+                if (last)
+                    last.costUsd = retryRun.result.costUsd;
+                totalCostUsd += retryRun.result.costUsd;
+                this.recordSpend(opts, adapter.provider, link.model, stepAttempts, retryRun.result, undefined);
+                this.circuitBreaker.recordSuccess(adapter.provider);
+                const outcome = {
+                    result: retryRun.result,
+                    attempts: allAttempts,
+                    totalDurationMs: Math.max(0, this.now() - startedAt),
+                    totalCostUsd,
+                };
+                this.populateBudgetRemaining(outcome, opts);
+                return outcome;
+            }
+            lastError = retryRun.error ?? new Error('LlmRouter: unknown failure');
+            lastErrorClass = stepAttempts[stepAttempts.length - 1]?.errorClass ?? 'unknown';
+            // Record this step's spend regardless (even though no cost was billed).
+            this.recordSpend(opts, adapter.provider, link.model, stepAttempts, undefined, lastError);
+            // Update circuit breaker: only retryable provider faults count
+            // toward tripping the breaker — auth/content_policy/invalid_request
+            // are caller / data issues, not provider health, so they don't open
+            // the circuit.
+            if (!isTerminal(lastErrorClass)) {
+                this.circuitBreaker.recordFailure(adapter.provider);
+            }
+            else {
+                // Terminal classes leave breaker state untouched and short-circuit.
+                break;
+            }
+            // Per-call cost ceiling — abort the chain if we've already exceeded it.
+            if (totalCostUsd > maxCost) {
+                break;
+            }
+        }
+        const finalErr = lastError ?? new Error('LlmRouter: chain produced no error and no result');
+        throw new RouterError(`route '${opts.tag}' failed: ${finalErr.message}`, {
+            attempts: allAttempts,
+            cause: finalErr,
+        });
+    }
+    /** Build the ordered chain of (model, on-gate) steps for a given tag. */
+    buildChain(opts) {
+        if (opts.model) {
+            // Pinned model — no fallbacks (escape hatch).
+            return [{ model: opts.model }];
+        }
+        const route = this.config.routes.find((r) => r.tag === opts.tag);
+        if (!route) {
+            throw new Error(`LlmRouter: no route for tag '${opts.tag}' (and no opts.model pin)`);
+        }
+        const chain = [{ model: route.primary }];
+        for (const fb of route.fallbacks ?? []) {
+            chain.push({ model: fb.model, on: fb.on });
+        }
+        return chain;
+    }
+    /** Decide whether to try this fallback step given the prior error class. */
+    shouldTryFallback(fallback, priorClass) {
+        if (!priorClass)
+            return false;
+        if (isTerminal(priorClass))
+            return false;
+        // No `on` filter means "any retryable error".
+        if (!fallback.on || fallback.on.length === 0)
+            return true;
+        return fallback.on.includes(priorClass);
+    }
+    // ── Budget + ledger helpers ────────────────────────────────────────────
+    enforceBudgetPreflight(opts) {
+        if (!this.ledger || !this.config.budgets)
+            return;
+        const remaining = this.computeRemainingBudget(opts);
+        if (remaining === undefined)
+            return;
+        if (remaining > 0)
+            return;
+        const breach = this.config.budgets.onBreach;
+        if (breach === 'fail') {
+            throw new Error(`LlmRouter: budget exhausted for tag='${opts.tag}' (run='${opts.runId ?? ''}')`);
+        }
+        if (breach === 'queue') {
+            throw new Error(`LlmRouter: budget exhausted; queue mode not yet implemented`);
+        }
+        // 'downgrade' — Phase 5 will pick a cheaper fallback. Phase 4 lets the call
+        // through and trusts the per-call cap.
+    }
+    computeRemainingBudget(opts) {
+        if (!this.ledger || !this.config.budgets)
+            return undefined;
+        const b = this.config.budgets;
+        let remaining;
+        const setMin = (val) => {
+            remaining = remaining === undefined ? val : Math.min(remaining, val);
+        };
+        if (b.dailyUsd !== undefined) {
+            const since = startOfTodayIso();
+            setMin(b.dailyUsd - this.ledger.totalUsd({ since }));
+        }
+        if (b.perRunUsd !== undefined && opts.runId) {
+            setMin(b.perRunUsd - this.ledger.totalUsd({ runId: opts.runId }));
+        }
+        const tagCap = b.perTagUsd?.[opts.tag];
+        if (tagCap !== undefined) {
+            setMin(tagCap - this.ledger.totalUsd({ tag: opts.tag }));
+        }
+        return remaining;
+    }
+    populateBudgetRemaining(outcome, opts) {
+        const r = this.computeRemainingBudget(opts);
+        if (r !== undefined)
+            outcome.budgetRemainingUsd = r;
+    }
+    recordSpend(opts, provider, modelId, attempts, result, err) {
+        if (!this.ledger)
+            return;
+        const last = attempts[attempts.length - 1];
+        this.ledger.record({
+            id: this.newId(),
+            ts: new Date(this.now()).toISOString(),
+            runId: opts.runId,
+            project: opts.project,
+            user: opts.user,
+            tag: opts.tag,
+            provider,
+            model: modelId,
+            inputTokens: result?.usage.inputTokens ?? 0,
+            outputTokens: result?.usage.outputTokens ?? 0,
+            cacheReadTokens: result?.usage.cacheReadTokens ?? 0,
+            cacheWriteTokens: result?.usage.cacheWriteTokens ?? 0,
+            costUsd: result?.costUsd ?? 0,
+            durationMs: attempts.reduce((a, x) => a + x.durationMs, 0),
+            fallbackIndex: last?.fallbackIndex ?? 0,
+            attemptCount: attempts.length,
+            errorClass: err ? (last?.errorClass ?? 'unknown') : undefined,
+        });
+    }
+    /**
+     * Rough token estimate for pre-flight rate-limit checks. Uses the
+     * standard ~4-chars-per-token heuristic over message content. We bias
+     * slightly high (with maxTokens) so the bucket reserves enough room
+     * for the response too.
+     */
+    estimateTokens(opts) {
+        const promptChars = opts.messages.reduce((acc, m) => acc + m.content.length, 0);
+        const promptTokens = Math.ceil(promptChars / 4);
+        const responseTokens = opts.maxTokens ?? 1024;
+        return promptTokens + responseTokens;
+    }
+    // ── Build invoke options for the underlying adapter ───────────────────
+    buildInvokeOpts(opts, modelId) {
+        const messages = typeof opts.prompt === 'string'
+            ? [{ role: 'user', content: opts.prompt }]
+            : opts.prompt.map((m) => ({ role: m.role, content: m.content }));
+        return {
+            model: modelId,
+            messages,
+            tools: opts.tools,
+            maxTokens: opts.maxTokens,
+            temperature: opts.temperature,
+            cacheBreakpoint: opts.cacheBreakpoint,
+            providerOptions: opts.providerOptions,
+            signal: opts.signal,
+        };
+    }
+}
+// ── Helpers ───────────────────────────────────────────────────────────────
+function startOfTodayIso() {
+    const d = new Date();
+    d.setUTCHours(0, 0, 0, 0);
+    return d.toISOString();
+}
+function defaultNewId() {
+    // Cheap monotonic id — Date.now in base36 + a 6-char random suffix.
+    const ts = Date.now().toString(36);
+    const rand = Math.random().toString(36).slice(2, 8);
+    return `s-${ts}-${rand}`;
+}
+function isTerminal(cls) {
+    return cls === 'auth' || cls === 'content_policy' || cls === 'invalid_request';
+}
+//# sourceMappingURL=router.js.map

package/dist/router/router.js.map

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

package/dist/router/spend-ledger.d.ts

@@ -0,0 +1,69 @@
+/**
+ * SpendLedger — SQLite-backed per-call spend ledger.
+ *
+ * One row per terminal outcome (success or final failure). Failed calls
+ * that incurred no cost still get a row so retry-driven amplification is
+ * visible in audit. Schema locked in `AGENT-CORE-LLM-ROUTER-ADR.md` §4.
+ *
+ * Default location: `~/.anvil/router/spend.sqlite`. Honors `process.env.
+ * ANVIL_HOME` to relocate the entire `~/.anvil/` tree (memory-core convention).
+ */
+import Database from 'better-sqlite3';
+export declare const SPEND_LEDGER_SCHEMA_SQL = "\nCREATE TABLE IF NOT EXISTS spend (\n  id TEXT PRIMARY KEY,\n  ts TEXT NOT NULL,\n  run_id TEXT,\n  project TEXT,\n  user TEXT,\n  tag TEXT NOT NULL,\n  provider TEXT NOT NULL,\n  model TEXT NOT NULL,\n  input_tokens INTEGER NOT NULL DEFAULT 0,\n  output_tokens INTEGER NOT NULL DEFAULT 0,\n  cache_read_tokens INTEGER NOT NULL DEFAULT 0,\n  cache_write_tokens INTEGER NOT NULL DEFAULT 0,\n  cost_usd REAL NOT NULL DEFAULT 0,\n  duration_ms INTEGER NOT NULL DEFAULT 0,\n  fallback_index INTEGER NOT NULL DEFAULT 0,\n  attempt_count INTEGER NOT NULL DEFAULT 1,\n  error_class TEXT,\n  trace_id TEXT\n);\n\nCREATE INDEX IF NOT EXISTS idx_spend_run ON spend(run_id, ts);\nCREATE INDEX IF NOT EXISTS idx_spend_project ON spend(project, ts);\nCREATE INDEX IF NOT EXISTS idx_spend_tag ON spend(tag, ts);\nCREATE INDEX IF NOT EXISTS idx_spend_provider ON spend(provider, ts);\n";
+export interface SpendRow {
+    id: string;
+    ts: string;
+    runId?: string;
+    project?: string;
+    user?: string;
+    tag: string;
+    provider: string;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    costUsd: number;
+    durationMs: number;
+    fallbackIndex: number;
+    attemptCount: number;
+    errorClass?: string;
+    traceId?: string;
+}
+export interface SpendQueryOpts {
+    runId?: string;
+    project?: string;
+    tag?: string;
+    provider?: string;
+    /** ISO timestamp lower-bound (inclusive). */
+    since?: string;
+    /** ISO timestamp upper-bound (exclusive). */
+    until?: string;
+}
+export declare function defaultSpendLedgerPath(): string;
+export declare class SpendLedger {
+    readonly filePath: string;
+    readonly db: Database.Database;
+    constructor(filePath?: string);
+    /**
+     * Idempotent column adds — for SQLite files created before a column
+     * existed, we ALTER TABLE if missing. Mirrors memory-core's pattern.
+     */
+    private applyAdditiveMigrations;
+    record(row: SpendRow): void;
+    /** Sum of cost_usd across rows matching the query. */
+    totalUsd(opts?: SpendQueryOpts): number;
+    /** Aggregated cost grouped by tag (or runId / project). */
+    groupBy(field: 'tag' | 'run_id' | 'project' | 'provider', opts?: SpendQueryOpts): Array<{
+        key: string;
+        totalUsd: number;
+        count: number;
+    }>;
+    /** Most-recent rows; default 50. */
+    recent(limit?: number): SpendRow[];
+    /** Total count — convenience for tests + sanity checks. */
+    count(opts?: SpendQueryOpts): number;
+    close(): void;
+    private buildWhere;
+}
+//# sourceMappingURL=spend-ledger.d.ts.map

package/dist/router/spend-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spend-ledger.d.ts","sourceRoot":"","sources":["../../src/router/spend-ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAKtC,eAAO,MAAM,uBAAuB,42BA0BnC,CAAC;AAEF,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,sBAAsB,IAAI,MAAM,CAG/C;AAED,qBAAa,WAAW;aAGM,QAAQ,EAAE,MAAM;IAF5C,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,CAAC;gBAEH,QAAQ,GAAE,MAAiC;IAQvE;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAW/B,MAAM,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI;IAkC3B,sDAAsD;IACtD,QAAQ,CAAC,IAAI,GAAE,cAAmB,GAAG,MAAM;IAQ3C,2DAA2D;IAC3D,OAAO,CACL,KAAK,EAAE,KAAK,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,EAChD,IAAI,GAAE,cAAmB,GACxB,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAY1D,oCAAoC;IACpC,MAAM,CAAC,KAAK,SAAK,GAAG,QAAQ,EAAE;IAO9B,2DAA2D;IAC3D,KAAK,CAAC,IAAI,GAAE,cAAmB,GAAG,MAAM;IAMxC,KAAK,IAAI,IAAI;IAIb,OAAO,CAAC,UAAU;CAgCnB"}

package/dist/router/spend-ledger.js

@@ -0,0 +1,191 @@
+/**
+ * SpendLedger — SQLite-backed per-call spend ledger.
+ *
+ * One row per terminal outcome (success or final failure). Failed calls
+ * that incurred no cost still get a row so retry-driven amplification is
+ * visible in audit. Schema locked in `AGENT-CORE-LLM-ROUTER-ADR.md` §4.
+ *
+ * Default location: `~/.anvil/router/spend.sqlite`. Honors `process.env.
+ * ANVIL_HOME` to relocate the entire `~/.anvil/` tree (memory-core convention).
+ */
+import Database from 'better-sqlite3';
+import { mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+export const SPEND_LEDGER_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS spend (
+  id TEXT PRIMARY KEY,
+  ts TEXT NOT NULL,
+  run_id TEXT,
+  project TEXT,
+  user TEXT,
+  tag TEXT NOT NULL,
+  provider TEXT NOT NULL,
+  model TEXT NOT NULL,
+  input_tokens INTEGER NOT NULL DEFAULT 0,
+  output_tokens INTEGER NOT NULL DEFAULT 0,
+  cache_read_tokens INTEGER NOT NULL DEFAULT 0,
+  cache_write_tokens INTEGER NOT NULL DEFAULT 0,
+  cost_usd REAL NOT NULL DEFAULT 0,
+  duration_ms INTEGER NOT NULL DEFAULT 0,
+  fallback_index INTEGER NOT NULL DEFAULT 0,
+  attempt_count INTEGER NOT NULL DEFAULT 1,
+  error_class TEXT,
+  trace_id TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_spend_run ON spend(run_id, ts);
+CREATE INDEX IF NOT EXISTS idx_spend_project ON spend(project, ts);
+CREATE INDEX IF NOT EXISTS idx_spend_tag ON spend(tag, ts);
+CREATE INDEX IF NOT EXISTS idx_spend_provider ON spend(provider, ts);
+`;
+export function defaultSpendLedgerPath() {
+    const root = process.env.ANVIL_HOME ?? join(homedir(), '.anvil');
+    return join(root, 'router', 'spend.sqlite');
+}
+export class SpendLedger {
+    filePath;
+    db;
+    constructor(filePath = defaultSpendLedgerPath()) {
+        this.filePath = filePath;
+        mkdirSync(dirname(filePath), { recursive: true });
+        this.db = new Database(filePath);
+        this.db.pragma('journal_mode = WAL');
+        this.db.exec(SPEND_LEDGER_SCHEMA_SQL);
+        this.applyAdditiveMigrations();
+    }
+    /**
+     * Idempotent column adds — for SQLite files created before a column
+     * existed, we ALTER TABLE if missing. Mirrors memory-core's pattern.
+     */
+    applyAdditiveMigrations() {
+        const cols = this.db.pragma('table_info(spend)').map((c) => c.name);
+        const ensure = (name, ddl) => {
+            if (!cols.includes(name)) {
+                this.db.exec(`ALTER TABLE spend ADD COLUMN ${ddl}`);
+            }
+        };
+        ensure('error_class', 'error_class TEXT');
+        ensure('trace_id', 'trace_id TEXT');
+    }
+    record(row) {
+        const stmt = this.db.prepare(`INSERT OR REPLACE INTO spend(
+        id, ts, run_id, project, user, tag, provider, model,
+        input_tokens, output_tokens, cache_read_tokens, cache_write_tokens,
+        cost_usd, duration_ms, fallback_index, attempt_count, error_class, trace_id
+      ) VALUES (
+        @id, @ts, @runId, @project, @user, @tag, @provider, @model,
+        @inputTokens, @outputTokens, @cacheReadTokens, @cacheWriteTokens,
+        @costUsd, @durationMs, @fallbackIndex, @attemptCount, @errorClass, @traceId
+      )`);
+        stmt.run({
+            id: row.id,
+            ts: row.ts,
+            runId: row.runId ?? null,
+            project: row.project ?? null,
+            user: row.user ?? null,
+            tag: row.tag,
+            provider: row.provider,
+            model: row.model,
+            inputTokens: row.inputTokens,
+            outputTokens: row.outputTokens,
+            cacheReadTokens: row.cacheReadTokens ?? 0,
+            cacheWriteTokens: row.cacheWriteTokens ?? 0,
+            costUsd: row.costUsd,
+            durationMs: row.durationMs,
+            fallbackIndex: row.fallbackIndex,
+            attemptCount: row.attemptCount,
+            errorClass: row.errorClass ?? null,
+            traceId: row.traceId ?? null,
+        });
+    }
+    /** Sum of cost_usd across rows matching the query. */
+    totalUsd(opts = {}) {
+        const { sql, params } = this.buildWhere(opts);
+        const row = this.db
+            .prepare(`SELECT COALESCE(SUM(cost_usd), 0) AS total FROM spend ${sql}`)
+            .get(...params);
+        return row.total;
+    }
+    /** Aggregated cost grouped by tag (or runId / project). */
+    groupBy(field, opts = {}) {
+        const { sql, params } = this.buildWhere(opts);
+        return this.db
+            .prepare(`SELECT ${field} AS key, COALESCE(SUM(cost_usd), 0) AS totalUsd, COUNT(*) AS count
+         FROM spend ${sql}
+         GROUP BY ${field}
+         ORDER BY totalUsd DESC`)
+            .all(...params);
+    }
+    /** Most-recent rows; default 50. */
+    recent(limit = 50) {
+        const rows = this.db
+            .prepare(`SELECT * FROM spend ORDER BY ts DESC LIMIT ?`)
+            .all(limit);
+        return rows.map(rowToSpend);
+    }
+    /** Total count — convenience for tests + sanity checks. */
+    count(opts = {}) {
+        const { sql, params } = this.buildWhere(opts);
+        const row = this.db.prepare(`SELECT COUNT(*) AS c FROM spend ${sql}`).get(...params);
+        return row.c;
+    }
+    close() {
+        this.db.close();
+    }
+    buildWhere(opts) {
+        const where = [];
+        const params = [];
+        if (opts.runId !== undefined) {
+            where.push('run_id = ?');
+            params.push(opts.runId);
+        }
+        if (opts.project !== undefined) {
+            where.push('project = ?');
+            params.push(opts.project);
+        }
+        if (opts.tag !== undefined) {
+            where.push('tag = ?');
+            params.push(opts.tag);
+        }
+        if (opts.provider !== undefined) {
+            where.push('provider = ?');
+            params.push(opts.provider);
+        }
+        if (opts.since !== undefined) {
+            where.push('ts >= ?');
+            params.push(opts.since);
+        }
+        if (opts.until !== undefined) {
+            where.push('ts < ?');
+            params.push(opts.until);
+        }
+        return {
+            sql: where.length ? `WHERE ${where.join(' AND ')}` : '',
+            params,
+        };
+    }
+}
+function rowToSpend(row) {
+    return {
+        id: row.id,
+        ts: row.ts,
+        runId: row.run_id ?? undefined,
+        project: row.project ?? undefined,
+        user: row.user ?? undefined,
+        tag: row.tag,
+        provider: row.provider,
+        model: row.model,
+        inputTokens: row.input_tokens,
+        outputTokens: row.output_tokens,
+        cacheReadTokens: row.cache_read_tokens ?? 0,
+        cacheWriteTokens: row.cache_write_tokens ?? 0,
+        costUsd: row.cost_usd,
+        durationMs: row.duration_ms,
+        fallbackIndex: row.fallback_index,
+        attemptCount: row.attempt_count,
+        errorClass: row.error_class ?? undefined,
+        traceId: row.trace_id ?? undefined,
+    };
+}
+//# sourceMappingURL=spend-ledger.js.map

package/dist/router/spend-ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spend-ledger.js","sourceRoot":"","sources":["../../src/router/spend-ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAElC,MAAM,CAAC,MAAM,uBAAuB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;CA0BtC,CAAC;AAkCF,MAAM,UAAU,sBAAsB;IACpC,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,CAAC,CAAC;IACjE,OAAO,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,cAAc,CAAC,CAAC;AAC9C,CAAC;AAED,MAAM,OAAO,WAAW;IAGM;IAFnB,EAAE,CAAoB;IAE/B,YAA4B,WAAmB,sBAAsB,EAAE;QAA3C,aAAQ,GAAR,QAAQ,CAAmC;QACrE,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAClD,IAAI,CAAC,EAAE,GAAG,IAAI,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACjC,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;QACrC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;QACtC,IAAI,CAAC,uBAAuB,EAAE,CAAC;IACjC,CAAC;IAED;;;OAGG;IACK,uBAAuB;QAC7B,MAAM,IAAI,GAAI,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAwB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC5F,MAAM,MAAM,GAAG,CAAC,IAAY,EAAE,GAAW,EAAE,EAAE;YAC3C,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;gBACzB,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,gCAAgC,GAAG,EAAE,CAAC,CAAC;YACtD,CAAC;QACH,CAAC,CAAC;QACF,MAAM,CAAC,aAAa,EAAE,kBAAkB,CAAC,CAAC;QAC1C,MAAM,CAAC,UAAU,EAAE,eAAe,CAAC,CAAC;IACtC,CAAC;IAED,MAAM,CAAC,GAAa;QAClB,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAC1B;;;;;;;;QAQE,CACH,CAAC;QACF,IAAI,CAAC,GAAG,CAAC;YACP,EAAE,EAAE,GAAG,CAAC,EAAE;YACV,EAAE,EAAE,GAAG,CAAC,EAAE;YACV,KAAK,EAAE,GAAG,CAAC,KAAK,IAAI,IAAI;YACxB,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,IAAI;YAC5B,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,IAAI;YACtB,GAAG,EAAE,GAAG,CAAC,GAAG;YACZ,QAAQ,EAAE,GAAG,CAAC,QAAQ;YACtB,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,WAAW,EAAE,GAAG,CAAC,WAAW;YAC5B,YAAY,EAAE,GAAG,CAAC,YAAY;YAC9B,eAAe,EAAE,GAAG,CAAC,eAAe,IAAI,CAAC;YACzC,gBAAgB,EAAE,GAAG,CAAC,gBAAgB,IAAI,CAAC;YAC3C,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,UAAU,EAAE,GAAG,CAAC,UAAU;YAC1B,aAAa,EAAE,GAAG,CAAC,aAAa;YAChC,YAAY,EAAE,GAAG,CAAC,YAAY;YAC9B,UAAU,EAAE,GAAG,CAAC,UAAU,IAAI,IAAI;YAClC,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,IAAI;SAC7B,CAAC,CAAC;IACL,CAAC;IAED,sDAAsD;IACtD,QAAQ,CAAC,OAAuB,EAAE;QAChC,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QAC9C,MAAM,GAAG,GAAG,IAAI,CAAC,EAAE;aAChB,OAAO,CAAC,yDAAyD,GAAG,EAAE,CAAC;aACvE,GAAG,CAAC,GAAG,MAAM,CAAsB,CAAC;QACvC,OAAO,GAAG,CAAC,KAAK,CAAC;IACnB,CAAC;IAED,2DAA2D;IAC3D,OAAO,CACL,KAAgD,EAChD,OAAuB,EAAE;QAEzB,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QAC9C,OAAO,IAAI,CAAC,EAAE;aACX,OAAO,CACN,UAAU,KAAK;sBACD,GAAG;oBACL,KAAK;gCACO,CACzB;aACA,GAAG,CAAC,GAAG,MAAM,CAA4D,CAAC;IAC/E,CAAC;IAED,oCAAoC;IACpC,MAAM,CAAC,KAAK,GAAG,EAAE;QACf,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE;aACjB,OAAO,CAAC,8CAA8C,CAAC;aACvD,GAAG,CAAC,KAAK,CAA8B,CAAC;QAC3C,OAAO,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAC9B,CAAC;IAED,2DAA2D;IAC3D,KAAK,CAAC,OAAuB,EAAE;QAC7B,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QAC9C,MAAM,GAAG,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,mCAAmC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,MAAM,CAAkB,CAAC;QACtG,OAAO,GAAG,CAAC,CAAC,CAAC;IACf,CAAC;IAED,KAAK;QACH,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;IAClB,CAAC;IAEO,UAAU,CAAC,IAAoB;QACrC,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAc,EAAE,CAAC;QAC7B,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC7B,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YACzB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1B,CAAC;QACD,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAC/B,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;YAC1B,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC5B,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;YAC3B,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACtB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACxB,CAAC;QACD,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YAChC,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;YAC3B,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC7B,CAAC;QACD,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC7B,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACtB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1B,CAAC;QACD,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC7B,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACrB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1B,CAAC;QACD,OAAO;YACL,GAAG,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE;YACvD,MAAM;SACP,CAAC;IACJ,CAAC;CACF;AAED,SAAS,UAAU,CAAC,GAA4B;IAC9C,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAY;QACpB,EAAE,EAAE,GAAG,CAAC,EAAY;QACpB,KAAK,EAAG,GAAG,CAAC,MAAiB,IAAI,SAAS;QAC1C,OAAO,EAAG,GAAG,CAAC,OAAkB,IAAI,SAAS;QAC7C,IAAI,EAAG,GAAG,CAAC,IAAe,IAAI,SAAS;QACvC,GAAG,EAAE,GAAG,CAAC,GAAa;QACtB,QAAQ,EAAE,GAAG,CAAC,QAAkB;QAChC,KAAK,EAAE,GAAG,CAAC,KAAe;QAC1B,WAAW,EAAE,GAAG,CAAC,YAAsB;QACvC,YAAY,EAAE,GAAG,CAAC,aAAuB;QACzC,eAAe,EAAG,GAAG,CAAC,iBAA4B,IAAI,CAAC;QACvD,gBAAgB,EAAG,GAAG,CAAC,kBAA6B,IAAI,CAAC;QACzD,OAAO,EAAE,GAAG,CAAC,QAAkB;QAC/B,UAAU,EAAE,GAAG,CAAC,WAAqB;QACrC,aAAa,EAAE,GAAG,CAAC,cAAwB;QAC3C,YAAY,EAAE,GAAG,CAAC,aAAuB;QACzC,UAAU,EAAG,GAAG,CAAC,WAAsB,IAAI,SAAS;QACpD,OAAO,EAAG,GAAG,CAAC,QAAmB,IAAI,SAAS;KAC/C,CAAC;AACJ,CAAC"}

package/dist/router/telemetry.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Router telemetry — OTel parent + child spans for `LlmRouter.invoke`.
+ *
+ * Span hierarchy (per ADR R10):
+ *   anvil.router.invoke         — one per invoke() call
+ *     anvil.router.attempt      — one per RouteAttempt (success or failure)
+ *       gen_ai.invoke           — emitted by instrumentModelAdapter (legacy
+ *                                  adapters) or LanguageModel callers
+ *
+ * Attributes:
+ *   anvil.router.route_id, anvil.router.tag, anvil.router.run_id,
+ *   anvil.router.attempt, anvil.router.error_class,
+ *   anvil.router.fallback_index, anvil.router.budget_remaining_usd,
+ *   anvil.router.circuit_breaker_state, anvil.router.total_cost_usd,
+ *   anvil.router.attempt_count
+ *
+ * Wrapper-style — call `withRouterSpans(router, opts)` to capture spans
+ * around a single invoke. The wrapper is a no-op when `recordContent` is
+ * false; it never throws on tracer absence.
+ */
+import type { LlmRouter } from './router.js';
+import type { InvokeOpts, RouteOutcome } from './types.js';
+export declare const ROUTER_INVOKE_SPAN = "anvil.router.invoke";
+export declare const ROUTER_ATTEMPT_SPAN = "anvil.router.attempt";
+export declare const RouterAttr: {
+    readonly ROUTE_ID: "anvil.router.route_id";
+    readonly TAG: "anvil.router.tag";
+    readonly RUN_ID: "anvil.router.run_id";
+    readonly PROJECT: "anvil.router.project";
+    readonly USER: "anvil.router.user";
+    readonly ATTEMPT: "anvil.router.attempt";
+    readonly ATTEMPT_COUNT: "anvil.router.attempt_count";
+    readonly ERROR_CLASS: "anvil.router.error_class";
+    readonly FALLBACK_INDEX: "anvil.router.fallback_index";
+    readonly BUDGET_REMAINING_USD: "anvil.router.budget_remaining_usd";
+    readonly CIRCUIT_BREAKER_STATE: "anvil.router.circuit_breaker_state";
+    readonly TOTAL_COST_USD: "anvil.router.total_cost_usd";
+    readonly PROVIDER: "anvil.router.provider";
+    readonly MODEL: "anvil.router.model";
+    readonly COST_USD: "anvil.router.cost_usd";
+};
+/**
+ * Wrap a single `LlmRouter.invoke()` call with a parent span and one
+ * child span per RouteAttempt. The wrapper post-walks `outcome.attempts`
+ * to emit children — this keeps the router code itself untouched.
+ */
+export declare function invokeWithSpans(router: LlmRouter, opts: InvokeOpts): Promise<RouteOutcome>;
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/router/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/router/telemetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAgB,MAAM,YAAY,CAAC;AAGzE,eAAO,MAAM,kBAAkB,wBAAwB,CAAC;AACxD,eAAO,MAAM,mBAAmB,yBAAyB,CAAC;AAE1D,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;CAgBb,CAAC;AAEX;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,YAAY,CAAC,CAsCvB"}