@esankhan3/anvil-agent-core 0.1.0

package/dist/router/local-executor.js

@@ -0,0 +1,161 @@
+/**
+ * LocalExecutor — process-local FIFO single-slot queue for exclusive
+ * local models (Ollama big-model slots that can't co-reside on a 16GB
+ * GPU). Embedding + reranker models bypass this entirely.
+ *
+ * Contract:
+ *   • At most ONE exclusive model is loaded at a time.
+ *   • Concurrent callers are serialized in FIFO order — no deadlock,
+ *     no priority inversion.
+ *   • Switching from model A → model B triggers a synchronous eviction
+ *     of A via Ollama's `POST /api/generate {model: A, prompt: '',
+ *     keep_alive: 0}`, then polls `/api/ps` until A is no longer
+ *     resident before letting B's call go through. Confirmed eviction
+ *     prevents the GPU from briefly holding both.
+ *   • Before every load, the executor probes `/api/ps` for OUT-OF-BAND
+ *     resident exclusive models (e.g. an Ollama CLI session on the
+ *     host loaded one independently). Intruders are evicted before B
+ *     loads, so no two exclusive models are ever resident at once.
+ *   • If `fn` throws, the slot is released and the queue keeps moving.
+ *   • Same-id consecutive calls do NOT trigger eviction.
+ */
+export class LocalExecutor {
+    loaded = null;
+    queue = [];
+    busy = false;
+    deps;
+    constructor(deps = {}) {
+        this.deps = {
+            evict: deps.evict ?? defaultEvict,
+            // Default probe is a sync no-op so unit tests don't pay an extra
+            // microtask tick for a network round-trip they don't care about.
+            // Production wires `defaultProbeResident` via the exported
+            // singleton at the bottom of this file.
+            probeResident: deps.probeResident ?? (async () => []),
+            isExclusive: deps.isExclusive ?? (() => true),
+            now: deps.now ?? Date.now,
+        };
+    }
+    withModel(modelId, fn) {
+        return new Promise((resolve, reject) => {
+            this.queue.push({
+                modelId,
+                run: fn,
+                resolve: resolve,
+                reject,
+            });
+            void this.pump();
+        });
+    }
+    inspect() {
+        return { loaded: this.loaded, queueDepth: this.queue.length };
+    }
+    async pump() {
+        if (this.busy)
+            return;
+        this.busy = true;
+        try {
+            while (this.queue.length > 0) {
+                const item = this.queue.shift();
+                try {
+                    // 1. Detect out-of-band intruders — exclusive models loaded
+                    //    by something other than this executor (e.g. an Ollama
+                    //    CLI session on the same host). Evict each before we
+                    //    proceed; no co-residence ever.
+                    let resident = [];
+                    try {
+                        resident = await this.deps.probeResident();
+                    }
+                    catch {
+                        resident = [];
+                    }
+                    for (const r of resident) {
+                        if (r === item.modelId)
+                            continue; // already loaded — nothing to do
+                        if (r === this.loaded)
+                            continue; // tracked below
+                        if (!this.deps.isExclusive(r))
+                            continue; // co-resident utility — exempt
+                        await this.deps.evict(r);
+                    }
+                    // 2. Tracked switch — A → B triggers our own eviction.
+                    if (this.loaded !== null && this.loaded !== item.modelId) {
+                        await this.deps.evict(this.loaded);
+                    }
+                    this.loaded = item.modelId;
+                    const result = await item.run();
+                    item.resolve(result);
+                }
+                catch (err) {
+                    item.reject(err);
+                }
+            }
+        }
+        finally {
+            this.busy = false;
+        }
+    }
+}
+/**
+ * Confirmed eviction. Sends keep_alive:0 to Ollama, then polls /api/ps
+ * until the model is no longer resident or we hit the deadline. Eight
+ * seconds is generous for unloading a 14B model — most unloads complete
+ * sub-second once the daemon receives the signal.
+ */
+async function defaultEvict(modelId) {
+    const baseUrl = (process.env.OLLAMA_HOST ?? 'http://localhost:11434').replace(/\/+$/, '');
+    await fetch(`${baseUrl}/api/generate`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ model: modelId, prompt: '', keep_alive: 0 }),
+    }).catch(() => {
+        // Eviction is best-effort; if Ollama is unreachable, the next /api/chat
+        // will surface the real error. Don't double-fail here.
+    });
+    const deadline = Date.now() + 8000;
+    while (Date.now() < deadline) {
+        let stillLoaded = false;
+        try {
+            const ps = await fetch(`${baseUrl}/api/ps`).then((r) => r.json());
+            stillLoaded = (ps.models ?? []).some((m) => m.name === modelId || m.model === modelId);
+        }
+        catch {
+            return; // probe failed — trust the unload, don't loop forever
+        }
+        if (!stillLoaded)
+            return;
+        await new Promise((r) => setTimeout(r, 200));
+    }
+    // Timed out waiting for unload — not fatal; the next chat call will
+    // either succeed (Ollama swaps fine) or fail with a clear OOM message.
+}
+async function defaultProbeResident() {
+    const baseUrl = (process.env.OLLAMA_HOST ?? 'http://localhost:11434').replace(/\/+$/, '');
+    try {
+        const ps = await fetch(`${baseUrl}/api/ps`).then((r) => r.json());
+        const names = [];
+        for (const m of ps.models ?? []) {
+            const id = m.name ?? m.model;
+            if (id)
+                names.push(id);
+        }
+        return names;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Process-local singleton. Modules that wrap exclusive-slot calls
+ * import this directly; tests construct their own instance to avoid
+ * cross-test pollution.
+ *
+ * The singleton is wired with the real Ollama probe so production
+ * intruder-detection works; per-test instances default to a no-op
+ * probe so they don't pay for a network round-trip they don't care
+ * about.
+ */
+export const localExecutor = new LocalExecutor({
+    probeResident: defaultProbeResident,
+});
+//# sourceMappingURL=local-executor.js.map

package/dist/router/local-executor.js.map

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

package/dist/router/model-registry.d.ts

@@ -0,0 +1,90 @@
+import type { ProviderName } from '../types.js';
+export type ModelCapability = 'embed' | 'rerank' | 'code' | 'reasoning' | 'vision';
+export type ModelComplexity = 'S' | 'M' | 'L';
+export type ModelTier = 'local' | 'cheap' | 'premium';
+export type ModelConsumer = 'agent-core' | 'knowledge-core';
+export interface ModelEntry {
+    id: string;
+    provider: ProviderName;
+    tier: ModelTier;
+    capabilities: ModelCapability[];
+    complexity_max: ModelComplexity;
+    vram_gb: number;
+    exclusive_slot: boolean;
+    context_tokens?: number;
+    /**
+     * Ollama `num_ctx` cap — bounds VRAM cost of context. Set to a value
+     * smaller than the model's max so context tokens don't eat the GPU
+     * headroom needed by weights. Ignored for cloud providers.
+     */
+    context_window?: number;
+    consumed_by?: ModelConsumer;
+    /** Optional non-Ollama HTTP endpoint. Reserved for future providers. */
+    endpoint?: string;
+}
+/**
+ * Walker tunables — controls how the dashboard's chain walker behaves.
+ *
+ * Lives at the top level of `models.yaml` so end users can adjust the
+ * routing/fallback policy in the same place they manage models. All
+ * fields are optional; missing values fall back to compiled-in defaults.
+ *
+ * ```yaml
+ * walker:
+ *   liveness_ttl_ms: 30000   # provider-liveness cache TTL (ms)
+ *   max_attempts: 5          # max chain-fallback attempts per stage
+ * ```
+ */
+export interface WalkerConfig {
+    /**
+     * How long a per-provider liveness verdict is cached. Default 30000.
+     * Lower values catch a recovering provider faster but cost more
+     * probes per run. Set to 0 to disable caching entirely.
+     */
+    liveness_ttl_ms: number;
+    /**
+     * Max chain-fallback attempts per stage entry. Default 5. After this
+     * many UpstreamError(retryable) burns the runner gives up and bubbles
+     * the last error to the user.
+     */
+    max_attempts: number;
+}
+/** Compiled-in defaults — used when models.yaml omits the walker block. */
+export declare const DEFAULT_WALKER_CONFIG: Readonly<WalkerConfig>;
+export interface ModelRegistry {
+    models: ModelEntry[];
+    /** Walker tunables — always populated; defaults applied at load time. */
+    walker: WalkerConfig;
+    /** Live availability annotation; populated by Phase 5 discovery, never by the loader. */
+    availability?: Map<string, ModelAvailability>;
+}
+export interface ModelAvailability {
+    available: boolean;
+    lastChecked: number;
+    error?: string;
+}
+export declare class ModelRegistryParseError extends Error {
+    readonly path: string;
+    readonly cause: unknown;
+    constructor(path: string, cause: unknown);
+}
+export declare class ModelRegistryValidationError extends Error {
+    constructor(message: string);
+}
+export interface LoadModelRegistryOptions {
+    workspaceRoot?: string;
+    env?: NodeJS.ProcessEnv;
+    homeDir?: string;
+}
+export declare function findModelsConfigPath(opts?: LoadModelRegistryOptions): string | undefined;
+/**
+ * Load + validate the models registry. Missing file → empty registry.
+ * Malformed yaml or invalid schema throws.
+ */
+export declare function loadModelRegistry(opts?: LoadModelRegistryOptions): ModelRegistry;
+/**
+ * Parse a previously-deserialized yaml object. Exposed for tests so they
+ * can feed in-memory yaml strings without touching the filesystem.
+ */
+export declare function parseModelRegistry(raw: unknown, sourcePath?: string): ModelRegistry;
+//# sourceMappingURL=model-registry.d.ts.map

package/dist/router/model-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-registry.d.ts","sourceRoot":"","sources":["../../src/router/model-registry.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;AACnF,MAAM,MAAM,eAAe,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAC9C,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;AACtD,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG,gBAAgB,CAAC;AAU5D,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,YAAY,CAAC;IACvB,IAAI,EAAE,SAAS,CAAC;IAChB,YAAY,EAAE,eAAe,EAAE,CAAC;IAChC,cAAc,EAAE,eAAe,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,OAAO,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,aAAa,CAAC;IAC5B,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,2EAA2E;AAC3E,eAAO,MAAM,qBAAqB,EAAE,QAAQ,CAAC,YAAY,CAGvD,CAAC;AAEH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,yEAAyE;IACzE,MAAM,EAAE,YAAY,CAAC;IACrB,yFAAyF;IACzF,YAAY,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC/C;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,uBAAwB,SAAQ,KAAK;aACpB,IAAI,EAAE,MAAM;aAAkB,KAAK,EAAE,OAAO;gBAA5C,IAAI,EAAE,MAAM,EAAkB,KAAK,EAAE,OAAO;CAIzE;AAED,qBAAa,4BAA6B,SAAQ,KAAK;gBACzC,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,wBAAwB;IACvC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,oBAAoB,CAAC,IAAI,GAAE,wBAA6B,GAAG,MAAM,GAAG,SAAS,CAc5F;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,wBAA6B,GAAG,aAAa,CAYpF;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,UAAU,SAAa,GAAG,aAAa,CA6BvF"}

package/dist/router/model-registry.js

@@ -0,0 +1,242 @@
+/**
+ * Model registry — capability/complexity-tagged catalog of models the
+ * resolver picks from. Source-of-truth file is `~/.anvil/models.yaml`.
+ *
+ * The registry holds CURATED facts (capabilities, tier, complexity_max,
+ * VRAM, exclusive_slot) loaded from yaml. Live state (availability,
+ * pricing) is augmented at runtime by the discovery pass — the loader
+ * itself never makes network calls.
+ *
+ * Resolution order for the yaml file:
+ *   1. process.env.ANVIL_MODELS_CONFIG (full path)
+ *   2. <workspaceRoot>/.anvil/models.yaml
+ *   3. ${ANVIL_HOME or $HOME/.anvil}/models.yaml
+ *   4. (no file) → returns { models: [] } and the resolver throws on use.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import * as YAML from 'yaml';
+const PROVIDERS = [
+    'claude', 'openai', 'gemini', 'openrouter', 'ollama', 'gemini-cli', 'adk', 'opencode',
+];
+const CAPABILITIES = ['embed', 'rerank', 'code', 'reasoning', 'vision'];
+const COMPLEXITIES = ['S', 'M', 'L'];
+const TIERS = ['local', 'cheap', 'premium'];
+const CONSUMERS = ['agent-core', 'knowledge-core'];
+/** Compiled-in defaults — used when models.yaml omits the walker block. */
+export const DEFAULT_WALKER_CONFIG = Object.freeze({
+    liveness_ttl_ms: 30_000,
+    max_attempts: 5,
+});
+export class ModelRegistryParseError extends Error {
+    path;
+    cause;
+    constructor(path, cause) {
+        super(`Failed to parse models.yaml at ${path}: ${cause instanceof Error ? cause.message : String(cause)}`);
+        this.path = path;
+        this.cause = cause;
+        this.name = 'ModelRegistryParseError';
+    }
+}
+export class ModelRegistryValidationError extends Error {
+    constructor(message) {
+        super(`models.yaml validation failed: ${message}`);
+        this.name = 'ModelRegistryValidationError';
+    }
+}
+export function findModelsConfigPath(opts = {}) {
+    const env = opts.env ?? process.env;
+    const home = opts.homeDir ?? homedir();
+    const anvilHome = env.ANVIL_HOME ?? join(home, '.anvil');
+    const candidates = [];
+    if (env.ANVIL_MODELS_CONFIG)
+        candidates.push(env.ANVIL_MODELS_CONFIG);
+    if (opts.workspaceRoot)
+        candidates.push(join(opts.workspaceRoot, '.anvil', 'models.yaml'));
+    candidates.push(join(anvilHome, 'models.yaml'));
+    for (const c of candidates) {
+        if (existsSync(c))
+            return c;
+    }
+    return undefined;
+}
+/**
+ * Load + validate the models registry. Missing file → empty registry.
+ * Malformed yaml or invalid schema throws.
+ */
+export function loadModelRegistry(opts = {}) {
+    const path = findModelsConfigPath(opts);
+    if (!path)
+        return { models: [], walker: { ...DEFAULT_WALKER_CONFIG } };
+    let raw;
+    try {
+        raw = YAML.parse(readFileSync(path, 'utf8'));
+    }
+    catch (err) {
+        throw new ModelRegistryParseError(path, err);
+    }
+    return parseModelRegistry(raw, path);
+}
+/**
+ * Parse a previously-deserialized yaml object. Exposed for tests so they
+ * can feed in-memory yaml strings without touching the filesystem.
+ */
+export function parseModelRegistry(raw, sourcePath = '<inline>') {
+    if (raw === null || raw === undefined)
+        return { models: [], walker: { ...DEFAULT_WALKER_CONFIG } };
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new ModelRegistryValidationError(`expected top-level object, got ${describe(raw)} (${sourcePath})`);
+    }
+    const top = raw;
+    const walker = parseWalkerConfig(top.walker);
+    const modelsRaw = top.models;
+    if (modelsRaw === undefined)
+        return { models: [], walker };
+    if (!Array.isArray(modelsRaw)) {
+        throw new ModelRegistryValidationError(`'models' must be an array, got ${describe(modelsRaw)}`);
+    }
+    const models = [];
+    const seenIds = new Set();
+    for (let i = 0; i < modelsRaw.length; i++) {
+        const entry = validateEntry(modelsRaw[i], i);
+        if (seenIds.has(entry.id)) {
+            throw new ModelRegistryValidationError(`duplicate model id "${entry.id}" at index ${i}`);
+        }
+        seenIds.add(entry.id);
+        enforceExclusiveSlotInvariant(entry, i);
+        models.push(entry);
+    }
+    return { models, walker };
+}
+/**
+ * Parse the optional `walker:` block. Missing block → defaults; partial
+ * block → defaults filled in for unspecified keys. Unknown keys throw
+ * (catches typos like `livenessTTL` or `maxRetries` early).
+ */
+function parseWalkerConfig(raw) {
+    if (raw === undefined || raw === null)
+        return { ...DEFAULT_WALKER_CONFIG };
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new ModelRegistryValidationError(`'walker' must be an object, got ${describe(raw)}`);
+    }
+    const w = raw;
+    const allowed = new Set(['liveness_ttl_ms', 'max_attempts']);
+    for (const k of Object.keys(w)) {
+        if (!allowed.has(k)) {
+            throw new ModelRegistryValidationError(`walker.${k}: unknown key. Supported: [${[...allowed].join(', ')}]`);
+        }
+    }
+    const out = { ...DEFAULT_WALKER_CONFIG };
+    if (w.liveness_ttl_ms !== undefined) {
+        out.liveness_ttl_ms = requireNumber(w.liveness_ttl_ms, 'walker.liveness_ttl_ms', { min: 0 });
+    }
+    if (w.max_attempts !== undefined) {
+        const n = requireNumber(w.max_attempts, 'walker.max_attempts', { min: 1 });
+        if (!Number.isInteger(n)) {
+            throw new ModelRegistryValidationError(`walker.max_attempts: expected integer, got ${n}`);
+        }
+        out.max_attempts = n;
+    }
+    return out;
+}
+/**
+ * Big GPU-resident models MUST set `exclusive_slot: true` so the
+ * `LocalExecutor` FIFO can serialize them. Co-resident utility models
+ * (embed, rerank consumed by knowledge-core) are exempt — they share VRAM
+ * with the held big-slot model by design.
+ */
+const EXCLUSIVE_SLOT_VRAM_THRESHOLD_GB = 5;
+function enforceExclusiveSlotInvariant(entry, index) {
+    if (entry.provider !== 'ollama')
+        return; // cloud providers don't use the slot
+    if (entry.consumed_by === 'knowledge-core')
+        return; // co-residents are exempt
+    if (entry.vram_gb < EXCLUSIVE_SLOT_VRAM_THRESHOLD_GB)
+        return;
+    if (entry.exclusive_slot)
+        return;
+    throw new ModelRegistryValidationError(`models[${index}] (${entry.id}): vram_gb=${entry.vram_gb} ≥ ${EXCLUSIVE_SLOT_VRAM_THRESHOLD_GB} requires exclusive_slot:true ` +
+        `to prevent VRAM thrashing. Set exclusive_slot:true, or mark consumed_by:knowledge-core if it is a co-resident utility model.`);
+}
+function validateEntry(rawEntry, index) {
+    const ctx = `models[${index}]`;
+    if (!rawEntry || typeof rawEntry !== 'object' || Array.isArray(rawEntry)) {
+        throw new ModelRegistryValidationError(`${ctx}: expected object, got ${describe(rawEntry)}`);
+    }
+    const e = rawEntry;
+    const id = requireString(e.id, `${ctx}.id`);
+    const provider = requireEnum(e.provider, PROVIDERS, `${ctx}.provider`);
+    const tier = requireEnum(e.tier, TIERS, `${ctx}.tier`);
+    if (!Array.isArray(e.capabilities) || e.capabilities.length === 0) {
+        throw new ModelRegistryValidationError(`${ctx}.capabilities: must be a non-empty array`);
+    }
+    const capabilities = [];
+    for (let j = 0; j < e.capabilities.length; j++) {
+        capabilities.push(requireEnum(e.capabilities[j], CAPABILITIES, `${ctx}.capabilities[${j}]`));
+    }
+    const complexity_max = requireEnum(e.complexity_max, COMPLEXITIES, `${ctx}.complexity_max`);
+    const vram_gb = requireNumber(e.vram_gb, `${ctx}.vram_gb`, { min: 0 });
+    const exclusive_slot = requireBoolean(e.exclusive_slot, `${ctx}.exclusive_slot`);
+    const out = {
+        id,
+        provider,
+        tier,
+        capabilities,
+        complexity_max,
+        vram_gb,
+        exclusive_slot,
+    };
+    if (e.context_tokens !== undefined) {
+        out.context_tokens = requireNumber(e.context_tokens, `${ctx}.context_tokens`, { min: 1, integer: true });
+    }
+    if (e.context_window !== undefined) {
+        out.context_window = requireNumber(e.context_window, `${ctx}.context_window`, { min: 256, integer: true });
+    }
+    if (e.consumed_by !== undefined) {
+        out.consumed_by = requireEnum(e.consumed_by, CONSUMERS, `${ctx}.consumed_by`);
+    }
+    if (e.endpoint !== undefined) {
+        out.endpoint = requireString(e.endpoint, `${ctx}.endpoint`);
+    }
+    return out;
+}
+// — Validation primitives —
+function requireString(v, ctx) {
+    if (typeof v !== 'string' || v.length === 0) {
+        throw new ModelRegistryValidationError(`${ctx}: expected non-empty string, got ${describe(v)}`);
+    }
+    return v;
+}
+function requireEnum(v, allowed, ctx) {
+    if (typeof v !== 'string' || !allowed.includes(v)) {
+        throw new ModelRegistryValidationError(`${ctx}: expected one of [${allowed.join(', ')}], got ${describe(v)}`);
+    }
+    return v;
+}
+function requireNumber(v, ctx, opts = {}) {
+    if (typeof v !== 'number' || !Number.isFinite(v)) {
+        throw new ModelRegistryValidationError(`${ctx}: expected number, got ${describe(v)}`);
+    }
+    if (opts.integer && !Number.isInteger(v)) {
+        throw new ModelRegistryValidationError(`${ctx}: expected integer, got ${v}`);
+    }
+    if (opts.min !== undefined && v < opts.min) {
+        throw new ModelRegistryValidationError(`${ctx}: must be >= ${opts.min}, got ${v}`);
+    }
+    return v;
+}
+function requireBoolean(v, ctx) {
+    if (typeof v !== 'boolean') {
+        throw new ModelRegistryValidationError(`${ctx}: expected boolean, got ${describe(v)}`);
+    }
+    return v;
+}
+function describe(v) {
+    if (v === null)
+        return 'null';
+    if (Array.isArray(v))
+        return 'array';
+    return typeof v;
+}
+//# sourceMappingURL=model-registry.js.map

package/dist/router/model-registry.js.map

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

package/dist/router/rate-limiter.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 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.
+ */
+import type { RateLimitProviderConfig } from './types.js';
+export declare const DEFAULT_RATE_LIMITS: Record<string, RateLimitProviderConfig>;
+export interface RateLimiterDeps {
+    /** Per-provider override map. Falls back to DEFAULT_RATE_LIMITS. */
+    config?: Record<string, RateLimitProviderConfig>;
+    /** Time source — injectable for deterministic tests. */
+    now?: () => number;
+    /** Sleep — injectable for deterministic tests. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Behavior when bucket dry. Default 'wait'. */
+    onRateLimit?: 'wait' | 'fail' | 'fallback';
+}
+export declare class RateLimitedError extends Error {
+    readonly provider: string;
+    readonly waitMs: number;
+    constructor(provider: string, waitMs: number);
+}
+export declare class TokenBucketRateLimiter {
+    private readonly config;
+    private readonly buckets;
+    private readonly now;
+    private readonly sleep;
+    private readonly onRateLimit;
+    constructor(deps?: RateLimiterDeps);
+    /**
+     * 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
+     */
+    acquire(provider: string, estimatedTokens: number): Promise<boolean>;
+    /** Best-effort introspection — returns current token counts. */
+    snapshot(provider: string): {
+        rpm?: number;
+        tpm?: number;
+    };
+    private bucketFor;
+    private refillAll;
+    private waitTime;
+}
+//# sourceMappingURL=rate-limiter.d.ts.map

package/dist/router/rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../../src/router/rate-limiter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE1D,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAavE,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;IACjD,wDAAwD;IACxD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,kDAAkD;IAClD,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;CAC5C;AAUD,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBACZ,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAM7C;AAED,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0C;IACjE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IACrD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IACtD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA+B;gBAE/C,IAAI,GAAE,eAAoB;IAOtC;;;;;;OAMG;IACG,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAkC1E,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE;IAQ1D,OAAO,CAAC,SAAS;IAYjB,OAAO,CAAC,SAAS;IAajB,OAAO,CAAC,QAAQ;CAKjB"}