@esankhan3/anvil-agent-core 0.1.0

package/dist/router/rate-limiter.js

@@ -0,0 +1,136 @@
+/**
+ * Token-bucket rate limiter — per-provider RPM (requests/min) + TPM
+ * (tokens/min) buckets.
+ *
+ * Phase 3 ships only the in-process implementation. Cross-process mode
+ * (SQLite advisory file) is a deferred add-on once the router has real
+ * users running multiple parallel cli invocations against shared keys.
+ *
+ * Behavior:
+ *   - One bucket per (provider, scope) where scope is 'rpm' | 'tpm'.
+ *   - Buckets refill linearly at `capacity / 60_000` tokens/ms.
+ *   - `acquire(provider, estimatedTokens)` waits until both buckets have
+ *     enough tokens, then deducts. Behavior on dry bucket follows
+ *     RouterConfig.onRateLimit:
+ *       - 'wait' (default) — sleep until tokens are available
+ *       - 'fail'           — throw immediately
+ *       - 'fallback'       — return false; caller falls back
+ *
+ * Defaults reflect published provider docs as of 2026-04-29; override
+ * via RouterConfig.rateLimit.
+ */
+export const DEFAULT_RATE_LIMITS = {
+    // Anthropic Tier 4 default (Sonnet 4.6); Haiku is much higher.
+    claude: { rpm: 50, tpm: 80_000 },
+    // OpenAI Tier 1 default (gpt-4o RPM 500 / TPM 30k).
+    openai: { rpm: 500, tpm: 30_000 },
+    // Gemini 2.5 Pro default — 1000 RPM, 4M TPM in the AI Studio tier.
+    gemini: { rpm: 1000, tpm: 4_000_000 },
+    // OpenRouter aggregates upstream limits; default is conservative.
+    openrouter: { rpm: 200, tpm: 200_000 },
+    // Local providers — effectively unbounded.
+    ollama: {},
+    'gemini-cli': {},
+    adk: {},
+};
+const realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export class RateLimitedError extends Error {
+    provider;
+    waitMs;
+    constructor(provider, waitMs) {
+        super(`rate limit for provider '${provider}' exhausted; wait ${waitMs}ms`);
+        this.name = 'RateLimitedError';
+        this.provider = provider;
+        this.waitMs = waitMs;
+    }
+}
+export class TokenBucketRateLimiter {
+    config;
+    buckets = new Map();
+    now;
+    sleep;
+    onRateLimit;
+    constructor(deps = {}) {
+        this.config = { ...DEFAULT_RATE_LIMITS, ...deps.config };
+        this.now = deps.now ?? Date.now;
+        this.sleep = deps.sleep ?? realSleep;
+        this.onRateLimit = deps.onRateLimit ?? 'wait';
+    }
+    /**
+     * Reserve 1 RPM token + N TPM tokens for the provider. If the bucket
+     * is dry the behavior depends on the configured `onRateLimit`:
+     *   - 'wait' (default): awaits until available
+     *   - 'fail': throws RateLimitedError
+     *   - 'fallback': returns false; caller falls back
+     */
+    async acquire(provider, estimatedTokens) {
+        const cfg = this.config[provider] ?? {};
+        const rpm = cfg.rpm;
+        const tpm = cfg.tpm;
+        if (rpm === undefined && tpm === undefined)
+            return true; // unbounded
+        while (true) {
+            this.refillAll(provider);
+            const rpmBucket = rpm !== undefined ? this.bucketFor(provider, 'rpm', rpm) : null;
+            const tpmBucket = tpm !== undefined ? this.bucketFor(provider, 'tpm', tpm) : null;
+            const rpmShort = rpmBucket && rpmBucket.tokens < 1;
+            const tpmShort = tpmBucket && tpmBucket.tokens < estimatedTokens;
+            if (!rpmShort && !tpmShort) {
+                if (rpmBucket)
+                    rpmBucket.tokens -= 1;
+                if (tpmBucket)
+                    tpmBucket.tokens -= estimatedTokens;
+                return true;
+            }
+            const waitMs = Math.max(rpmBucket && rpmShort ? this.waitTime(rpmBucket, 1) : 0, tpmBucket && tpmShort ? this.waitTime(tpmBucket, estimatedTokens) : 0);
+            if (this.onRateLimit === 'fail') {
+                throw new RateLimitedError(provider, waitMs);
+            }
+            if (this.onRateLimit === 'fallback') {
+                return false;
+            }
+            await this.sleep(waitMs);
+        }
+    }
+    /** Best-effort introspection — returns current token counts. */
+    snapshot(provider) {
+        this.refillAll(provider);
+        return {
+            rpm: this.buckets.get(`${provider}:rpm`)?.tokens,
+            tpm: this.buckets.get(`${provider}:tpm`)?.tokens,
+        };
+    }
+    bucketFor(provider, scope, capacityPerMin) {
+        const key = `${provider}:${scope}`;
+        let b = this.buckets.get(key);
+        if (!b) {
+            b = { capacityPerMin, tokens: capacityPerMin, lastRefillMs: this.now() };
+            this.buckets.set(key, b);
+        }
+        else if (b.capacityPerMin !== capacityPerMin) {
+            b.capacityPerMin = capacityPerMin;
+        }
+        return b;
+    }
+    refillAll(provider) {
+        for (const scope of ['rpm', 'tpm']) {
+            const b = this.buckets.get(`${provider}:${scope}`);
+            if (!b)
+                continue;
+            const now = this.now();
+            const elapsed = now - b.lastRefillMs;
+            if (elapsed <= 0)
+                continue;
+            const refill = (elapsed / 60_000) * b.capacityPerMin;
+            b.tokens = Math.min(b.capacityPerMin, b.tokens + refill);
+            b.lastRefillMs = now;
+        }
+    }
+    waitTime(bucket, needed) {
+        const deficit = needed - bucket.tokens;
+        if (deficit <= 0)
+            return 0;
+        return Math.ceil((deficit / bucket.capacityPerMin) * 60_000);
+    }
+}
+//# sourceMappingURL=rate-limiter.js.map

package/dist/router/rate-limiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.js","sourceRoot":"","sources":["../../src/router/rate-limiter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,MAAM,CAAC,MAAM,mBAAmB,GAA4C;IAC1E,+DAA+D;IAC/D,MAAM,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE;IAChC,oDAAoD;IACpD,MAAM,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE;IACjC,mEAAmE;IACnE,MAAM,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,SAAS,EAAE;IACrC,kEAAkE;IAClE,UAAU,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE;IACtC,2CAA2C;IAC3C,MAAM,EAAE,EAAE;IACV,YAAY,EAAE,EAAE;IAChB,GAAG,EAAE,EAAE;CACR,CAAC;AAmBF,MAAM,SAAS,GAAG,CAAC,EAAU,EAAE,EAAE,CAAC,IAAI,OAAO,CAAO,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;AAE9E,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAChC,QAAQ,CAAS;IACjB,MAAM,CAAS;IACxB,YAAY,QAAgB,EAAE,MAAc;QAC1C,KAAK,CAAC,4BAA4B,QAAQ,qBAAqB,MAAM,IAAI,CAAC,CAAC;QAC3E,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED,MAAM,OAAO,sBAAsB;IAChB,MAAM,CAA0C;IAChD,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IACpC,GAAG,CAAe;IAClB,KAAK,CAAgC;IACrC,WAAW,CAA+B;IAE3D,YAAY,OAAwB,EAAE;QACpC,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,mBAAmB,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QACzD,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;QAChC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,SAAS,CAAC;QACrC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,MAAM,CAAC;IAChD,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,CAAC,QAAgB,EAAE,eAAuB;QACrD,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QACxC,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC;QACpB,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC;QACpB,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC,CAAC,YAAY;QAErE,OAAO,IAAI,EAAE,CAAC;YACZ,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;YACzB,MAAM,SAAS,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YAClF,MAAM,SAAS,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YAElF,MAAM,QAAQ,GAAG,SAAS,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;YACnD,MAAM,QAAQ,GAAG,SAAS,IAAI,SAAS,CAAC,MAAM,GAAG,eAAe,CAAC;YACjE,IAAI,CAAC,QAAQ,IAAI,CAAC,QAAQ,EAAE,CAAC;gBAC3B,IAAI,SAAS;oBAAE,SAAS,CAAC,MAAM,IAAI,CAAC,CAAC;gBACrC,IAAI,SAAS;oBAAE,SAAS,CAAC,MAAM,IAAI,eAAe,CAAC;gBACnD,OAAO,IAAI,CAAC;YACd,CAAC;YAED,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CACrB,SAAS,IAAI,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EACvD,SAAS,IAAI,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CACtE,CAAC;YAEF,IAAI,IAAI,CAAC,WAAW,KAAK,MAAM,EAAE,CAAC;gBAChC,MAAM,IAAI,gBAAgB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YAC/C,CAAC;YACD,IAAI,IAAI,CAAC,WAAW,KAAK,UAAU,EAAE,CAAC;gBACpC,OAAO,KAAK,CAAC;YACf,CAAC;YACD,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,gEAAgE;IAChE,QAAQ,CAAC,QAAgB;QACvB,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QACzB,OAAO;YACL,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,QAAQ,MAAM,CAAC,EAAE,MAAM;YAChD,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,QAAQ,MAAM,CAAC,EAAE,MAAM;SACjD,CAAC;IACJ,CAAC;IAEO,SAAS,CAAC,QAAgB,EAAE,KAAoB,EAAE,cAAsB;QAC9E,MAAM,GAAG,GAAG,GAAG,QAAQ,IAAI,KAAK,EAAE,CAAC;QACnC,IAAI,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,CAAC,CAAC,EAAE,CAAC;YACP,CAAC,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,cAAc,EAAE,YAAY,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;YACzE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QAC3B,CAAC;aAAM,IAAI,CAAC,CAAC,cAAc,KAAK,cAAc,EAAE,CAAC;YAC/C,CAAC,CAAC,cAAc,GAAG,cAAc,CAAC;QACpC,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC;IAEO,SAAS,CAAC,QAAgB;QAChC,KAAK,MAAM,KAAK,IAAI,CAAC,KAAK,EAAE,KAAK,CAAU,EAAE,CAAC;YAC5C,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,QAAQ,IAAI,KAAK,EAAE,CAAC,CAAC;YACnD,IAAI,CAAC,CAAC;gBAAE,SAAS;YACjB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACvB,MAAM,OAAO,GAAG,GAAG,GAAG,CAAC,CAAC,YAAY,CAAC;YACrC,IAAI,OAAO,IAAI,CAAC;gBAAE,SAAS;YAC3B,MAAM,MAAM,GAAG,CAAC,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,cAAc,CAAC;YACrD,CAAC,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;YACzD,CAAC,CAAC,YAAY,GAAG,GAAG,CAAC;QACvB,CAAC;IACH,CAAC;IAEO,QAAQ,CAAC,MAAc,EAAE,MAAc;QAC7C,MAAM,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QACvC,IAAI,OAAO,IAAI,CAAC;YAAE,OAAO,CAAC,CAAC;QAC3B,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,GAAG,MAAM,CAAC,cAAc,CAAC,GAAG,MAAM,CAAC,CAAC;IAC/D,CAAC;CACF"}

package/dist/router/resolver.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Resolver — given a capability + complexity + tier preference list, walks
+ * the model registry and returns a routing chain `{ primary, fallbacks }`
+ * suitable for `LlmRouter.invoke`.
+ *
+ * Pure function. No I/O. No mutation of the registry.
+ *
+ * Algorithm:
+ *   1. Filter: model.capabilities ⊇ {capability}
+ *              ∧ rank(complexity) ≤ rank(model.complexity_max)
+ *              ∧ availability[model.id]?.available !== false
+ *              ∧ context_tokens, if requested, ≤ model.context_tokens
+ *   2. Group by tier
+ *   3. Walk tiers in `prefer` order; within tier, yaml-declared order
+ *   4. Concatenate → [primary, ...fallbacks]
+ *   5. If empty → ModelResolutionError with per-step diagnostic counts
+ */
+import type { ModelRegistry, ModelCapability, ModelComplexity, ModelTier } from './model-registry.js';
+import type { RouteFallback } from './types.js';
+export interface ResolveModelOptions {
+    capability: ModelCapability;
+    complexity: ModelComplexity;
+    /** Tier preference order. Walked left-to-right; first non-empty tier wins. */
+    prefer: ModelTier[];
+    /** Optional minimum context window required by the call. */
+    minContextTokens?: number;
+}
+export interface ResolvedChain {
+    primary: string;
+    fallbacks: RouteFallback[];
+}
+export declare class ModelResolutionError extends Error {
+    readonly opts: ResolveModelOptions;
+    readonly diagnostic: ResolutionDiagnostic;
+    constructor(opts: ResolveModelOptions, diagnostic: ResolutionDiagnostic);
+}
+export interface ResolutionDiagnostic {
+    totalInRegistry: number;
+    matchedCapability: number;
+    matchedComplexity: number;
+    matchedContext: number;
+    matchedAvailability: number;
+}
+export declare function resolveModel(opts: ResolveModelOptions, registry: ModelRegistry): ResolvedChain;
+//# sourceMappingURL=resolver.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../src/router/resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EACf,eAAe,EACf,SAAS,EAEV,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,eAAe,CAAC;IAC5B,UAAU,EAAE,eAAe,CAAC;IAC5B,8EAA8E;IAC9E,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,4DAA4D;IAC5D,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,aAAa,EAAE,CAAC;CAC5B;AAED,qBAAa,oBAAqB,SAAQ,KAAK;aAE3B,IAAI,EAAE,mBAAmB;aACzB,UAAU,EAAE,oBAAoB;gBADhC,IAAI,EAAE,mBAAmB,EACzB,UAAU,EAAE,oBAAoB;CAKnD;AAED,MAAM,WAAW,oBAAoB;IACnC,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAID,wBAAgB,YAAY,CAAC,IAAI,EAAE,mBAAmB,EAAE,QAAQ,EAAE,aAAa,GAAG,aAAa,CAmD9F"}

package/dist/router/resolver.js

@@ -0,0 +1,71 @@
+export class ModelResolutionError extends Error {
+    opts;
+    diagnostic;
+    constructor(opts, diagnostic) {
+        super(formatDiagnostic(opts, diagnostic));
+        this.opts = opts;
+        this.diagnostic = diagnostic;
+        this.name = 'ModelResolutionError';
+    }
+}
+const COMPLEXITY_RANK = { S: 1, M: 2, L: 3 };
+export function resolveModel(opts, registry) {
+    const requested = COMPLEXITY_RANK[opts.complexity];
+    const diag = {
+        totalInRegistry: registry.models.length,
+        matchedCapability: 0,
+        matchedComplexity: 0,
+        matchedContext: 0,
+        matchedAvailability: 0,
+    };
+    const passed = [];
+    for (const m of registry.models) {
+        if (!m.capabilities.includes(opts.capability))
+            continue;
+        diag.matchedCapability += 1;
+        if (COMPLEXITY_RANK[m.complexity_max] < requested)
+            continue;
+        diag.matchedComplexity += 1;
+        if (opts.minContextTokens !== undefined &&
+            m.context_tokens !== undefined &&
+            m.context_tokens < opts.minContextTokens) {
+            continue;
+        }
+        diag.matchedContext += 1;
+        if (registry.availability?.get(m.id)?.available === false)
+            continue;
+        diag.matchedAvailability += 1;
+        passed.push(m);
+    }
+    // Walk tier preference. Within a tier, preserve yaml-declared order
+    // (which is the order they appear in registry.models, since `passed`
+    // is built by iterating registry.models in order and we keep that).
+    const ordered = [];
+    for (const tier of opts.prefer) {
+        for (const m of passed) {
+            if (m.tier === tier)
+                ordered.push(m);
+        }
+    }
+    if (ordered.length === 0) {
+        throw new ModelResolutionError(opts, diag);
+    }
+    return {
+        primary: ordered[0].id,
+        fallbacks: ordered.slice(1).map((m) => ({ model: m.id })),
+    };
+}
+function formatDiagnostic(opts, d) {
+    const lines = [
+        `no model matches {capability: ${opts.capability}, complexity: ${opts.complexity}, prefer: [${opts.prefer.join(', ')}]}`,
+        `  registry has ${d.totalInRegistry} model(s);`,
+        `  ${d.matchedCapability} satisfied capability,`,
+        `  ${d.matchedComplexity} also satisfied complexity_max,`,
+        `  ${d.matchedContext} also satisfied context_tokens,`,
+        `  ${d.matchedAvailability} were available.`,
+        `  hint: add a matching model to ~/.anvil/models.yaml,`,
+        `        or relax stage policy to a less strict capability/complexity.`,
+    ];
+    return lines.join('\n');
+}
+//# sourceMappingURL=resolver.js.map

package/dist/router/resolver.js.map

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

package/dist/router/retry.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Per-error retry engine.
+ *
+ * Drives a single attempt-loop against one adapter using `RetryPolicy`
+ * resolved from the active `ErrorClass`. The fallback walk (Phase 5)
+ * sits a layer up and consumes this primitive for each step.
+ *
+ * Default policy table per ADR R2:
+ *   - rate_limit:    5 attempts, exponential, base 1000ms, max 30000ms
+ *   - timeout:       3 attempts, linear,      base 500ms,  max 5000ms
+ *   - server_5xx:    4 attempts, exponential, base 200ms,  max 5000ms
+ *   - auth:          0 attempts, constant     (terminal — surface immediately)
+ *   - content_policy: 0 attempts, constant    (terminal)
+ *   - invalid_request: 0 attempts, constant   (terminal)
+ *   - unknown:       1 attempt,  constant,    base 1000ms
+ *
+ * `Retry-After` headers — when present on the thrown error — override
+ * the computed backoff for that single delay.
+ */
+import type { ErrorClass, RetryPolicy } from './types.js';
+export declare const DEFAULT_RETRY_POLICY: Record<ErrorClass, RetryPolicy>;
+export interface RetryAttempt {
+    index: number;
+    errorClass?: ErrorClass;
+    error?: Error;
+    delayMs: number;
+    durationMs: number;
+}
+export interface RunWithRetryResult<T> {
+    result?: T;
+    error?: Error;
+    attempts: RetryAttempt[];
+}
+export interface RunWithRetryDeps {
+    /** Resolve the retry policy for a given error class. */
+    policyFor: (cls: ErrorClass) => RetryPolicy;
+    /**
+     * Adapter-specific overrides for `classifyError`. Returning `undefined`
+     * falls back to the generic heuristic.
+     */
+    classify?: (err: unknown) => ErrorClass | undefined;
+    /** Sleep — injectable so tests can drive a fake clock. */
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /** Time source — injectable for deterministic durations. */
+    now?: () => number;
+    /** Random source for jitter — injectable for deterministic tests. */
+    random?: () => number;
+    signal?: AbortSignal;
+}
+/**
+ * Run `fn` under the active retry policy. Returns the success result
+ * once produced, or the final error after the policy budget is exhausted.
+ *
+ * Each invocation is recorded in `attempts[]` with its classification,
+ * pre-attempt delay, and wall-clock duration.
+ */
+export declare function runWithRetry<T>(fn: () => Promise<T>, deps: RunWithRetryDeps): Promise<RunWithRetryResult<T>>;
+//# sourceMappingURL=retry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/router/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG1D,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,UAAU,EAAE,WAAW,CAQhE,CAAC;AAEF,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC,MAAM,CAAC,EAAE,CAAC,CAAC;IACX,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,SAAS,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,WAAW,CAAC;IAC5C;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,UAAU,GAAG,SAAS,CAAC;IACpD,0DAA0D;IAC1D,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,4DAA4D;IAC5D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAgBD;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAwDhC"}

package/dist/router/retry.js

@@ -0,0 +1,119 @@
+/**
+ * Per-error retry engine.
+ *
+ * Drives a single attempt-loop against one adapter using `RetryPolicy`
+ * resolved from the active `ErrorClass`. The fallback walk (Phase 5)
+ * sits a layer up and consumes this primitive for each step.
+ *
+ * Default policy table per ADR R2:
+ *   - rate_limit:    5 attempts, exponential, base 1000ms, max 30000ms
+ *   - timeout:       3 attempts, linear,      base 500ms,  max 5000ms
+ *   - server_5xx:    4 attempts, exponential, base 200ms,  max 5000ms
+ *   - auth:          0 attempts, constant     (terminal — surface immediately)
+ *   - content_policy: 0 attempts, constant    (terminal)
+ *   - invalid_request: 0 attempts, constant   (terminal)
+ *   - unknown:       1 attempt,  constant,    base 1000ms
+ *
+ * `Retry-After` headers — when present on the thrown error — override
+ * the computed backoff for that single delay.
+ */
+import { classifyError, parseRetryAfterMs } from './errors.js';
+export const DEFAULT_RETRY_POLICY = {
+    rate_limit: { attempts: 5, backoff: 'exponential', baseMs: 1000, maxMs: 30000 },
+    timeout: { attempts: 3, backoff: 'linear', baseMs: 500, maxMs: 5000 },
+    server_5xx: { attempts: 4, backoff: 'exponential', baseMs: 200, maxMs: 5000 },
+    auth: { attempts: 0, backoff: 'constant', baseMs: 0 },
+    content_policy: { attempts: 0, backoff: 'constant', baseMs: 0 },
+    invalid_request: { attempts: 0, backoff: 'constant', baseMs: 0 },
+    unknown: { attempts: 1, backoff: 'constant', baseMs: 1000 },
+};
+const realSleep = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted)
+        return reject(signal.reason);
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener('abort', () => {
+        clearTimeout(timer);
+        reject(signal.reason);
+    }, { once: true });
+});
+/**
+ * Run `fn` under the active retry policy. Returns the success result
+ * once produced, or the final error after the policy budget is exhausted.
+ *
+ * Each invocation is recorded in `attempts[]` with its classification,
+ * pre-attempt delay, and wall-clock duration.
+ */
+export async function runWithRetry(fn, deps) {
+    const sleep = deps.sleep ?? realSleep;
+    const now = deps.now ?? Date.now;
+    const random = deps.random ?? Math.random;
+    const attempts = [];
+    let attemptIndex = 0;
+    while (true) {
+        const startedAt = now();
+        let outcome;
+        try {
+            const value = await fn();
+            outcome = { ok: true, value };
+        }
+        catch (raw) {
+            outcome = { ok: false, err: raw instanceof Error ? raw : new Error(String(raw)) };
+        }
+        const durationMs = Math.max(0, now() - startedAt);
+        if (outcome.ok) {
+            attempts.push({ index: attemptIndex, delayMs: 0, durationMs });
+            return { result: outcome.value, attempts };
+        }
+        const cls = deps.classify?.(outcome.err) ?? classifyError(outcome.err);
+        const policy = deps.policyFor(cls);
+        attempts.push({
+            index: attemptIndex,
+            errorClass: cls,
+            error: outcome.err,
+            delayMs: 0,
+            durationMs,
+        });
+        // Budget exhausted (or terminal class with attempts: 0).
+        if (attemptIndex >= policy.attempts) {
+            return { error: outcome.err, attempts };
+        }
+        // Compute the next delay. `Retry-After` overrides if present.
+        const headerDelay = parseRetryAfterMs(outcome.err.headers);
+        const computed = headerDelay ?? computeDelay(policy, attemptIndex, random);
+        attempts[attempts.length - 1].delayMs = computed;
+        if (computed > 0) {
+            try {
+                await sleep(computed, deps.signal);
+            }
+            catch (e) {
+                return { error: e instanceof Error ? e : new Error(String(e)), attempts };
+            }
+        }
+        attemptIndex += 1;
+    }
+}
+function computeDelay(policy, attemptIndex, random) {
+    const useJitter = policy.jitter ?? true;
+    let base;
+    switch (policy.backoff) {
+        case 'constant':
+            base = policy.baseMs;
+            break;
+        case 'linear':
+            base = policy.baseMs * (attemptIndex + 1);
+            break;
+        case 'exponential':
+            base = policy.baseMs * Math.pow(2, attemptIndex);
+            break;
+    }
+    if (policy.maxMs !== undefined) {
+        base = Math.min(base, policy.maxMs);
+    }
+    if (!useJitter)
+        return Math.max(0, Math.round(base));
+    // ±25% jitter
+    const jitter = base * 0.25;
+    const value = base + (random() * 2 - 1) * jitter;
+    return Math.max(0, Math.round(value));
+}
+//# sourceMappingURL=retry.js.map

package/dist/router/retry.js.map

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

package/dist/router/router.d.ts

@@ -0,0 +1,100 @@
+/**
+ * `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 type { ErrorClass, InvokeOpts, RouteAttempt, RouteOutcome, RouterConfig } from './types.js';
+import type { LanguageModel, LanguageModelInvokeOptions, InvokeResult } from '../types.js';
+import { TokenBucketRateLimiter } from './rate-limiter.js';
+import { SpendLedger } from './spend-ledger.js';
+import { CircuitBreaker } from './circuit-breaker.js';
+export interface AdapterResolver {
+    /** Resolve a model id to an executor. */
+    resolve(modelId: string): LanguageModel;
+}
+export interface LlmRouterDeps {
+    config: RouterConfig;
+    /**
+     * Resolves a model id → executor. Phase 5 wires this to ProviderRegistry.
+     * Tests inject fakes directly.
+     */
+    resolver?: AdapterResolver;
+    /**
+     * Pre-flight rate limiter. If omitted, the router constructs an internal
+     * TokenBucketRateLimiter from `config.rateLimit`.
+     */
+    rateLimiter?: TokenBucketRateLimiter;
+    /**
+     * Spend ledger. If omitted, no rows are recorded (useful for tests or
+     * embedded scenarios). Pass `new SpendLedger()` to use the default
+     * `~/.anvil/router/spend.sqlite` file.
+     */
+    ledger?: SpendLedger;
+    /**
+     * Per-provider circuit breaker. If omitted, the router constructs one
+     * from `config.circuitBreaker` (or defaults).
+     */
+    circuitBreaker?: CircuitBreaker;
+    /** Generate ledger row ids — injectable for deterministic tests. */
+    newId?: () => string;
+    /** Time source for deterministic tests. */
+    now?: () => number;
+    /** Sleep — injectable for deterministic tests. */
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /** Random source for jitter. */
+    random?: () => number;
+    /** Adapter-specific error classifiers (per-provider override). */
+    errorClassifiers?: Record<string, (err: unknown) => ErrorClass | undefined>;
+}
+export declare class LlmRouter {
+    protected readonly config: RouterConfig;
+    protected readonly resolver?: AdapterResolver;
+    protected readonly rateLimiter: TokenBucketRateLimiter;
+    protected readonly circuitBreaker: CircuitBreaker;
+    protected readonly ledger?: SpendLedger;
+    protected readonly newId: () => string;
+    protected readonly now: () => number;
+    protected readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    protected readonly random?: () => number;
+    protected readonly errorClassifiers: Record<string, (err: unknown) => ErrorClass | undefined>;
+    constructor(deps: LlmRouterDeps);
+    /** Inspect the active config (immutable snapshot). */
+    getConfig(): Readonly<RouterConfig>;
+    /**
+     * 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)
+     */
+    invoke(opts: InvokeOpts): Promise<RouteOutcome>;
+    /** Build the ordered chain of (model, on-gate) steps for a given tag. */
+    protected buildChain(opts: InvokeOpts): Array<{
+        model: string;
+        on?: ErrorClass[];
+    }>;
+    /** Decide whether to try this fallback step given the prior error class. */
+    protected shouldTryFallback(fallback: {
+        on?: ErrorClass[];
+    }, priorClass: ErrorClass | undefined): boolean;
+    protected enforceBudgetPreflight(opts: InvokeOpts): void;
+    protected computeRemainingBudget(opts: InvokeOpts): number | undefined;
+    protected populateBudgetRemaining(outcome: RouteOutcome, opts: InvokeOpts): void;
+    protected recordSpend(opts: InvokeOpts, provider: string, modelId: string, attempts: ReadonlyArray<RouteAttempt>, result: InvokeResult | undefined, err: Error | undefined): void;
+    /**
+     * 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.
+     */
+    protected estimateTokens(opts: LanguageModelInvokeOptions): number;
+    protected buildInvokeOpts(opts: InvokeOpts, modelId: string): LanguageModelInvokeOptions;
+}
+//# sourceMappingURL=router.d.ts.map

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

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