ai-runtime-engine 1.1.0

package/dist/context/tokens.js

@@ -0,0 +1,38 @@
+/**
+ * Token ESTIMATION for context budgeting. These are heuristic estimates (≈ chars / charsPerToken),
+ * deliberately NOT conflated with provider-reported usage (which is authoritative and separate). The
+ * estimator can be calibrated over time from observed (chars, actualTokens) pairs via an EWMA, so the
+ * ratio drifts toward reality per deployment without ever claiming to be exact.
+ */
+const DEFAULT_CHARS_PER_TOKEN = 4;
+const EWMA_ALPHA = 0.2;
+export class TokenEstimator {
+    charsPerToken;
+    constructor(charsPerToken = DEFAULT_CHARS_PER_TOKEN) {
+        this.charsPerToken = charsPerToken > 0 ? charsPerToken : DEFAULT_CHARS_PER_TOKEN;
+    }
+    /** Heuristic token estimate for a string. Always ≥ 0; a non-empty string estimates ≥ 1. */
+    estimate(text) {
+        if (!text)
+            return 0;
+        return Math.max(1, Math.ceil(text.length / this.charsPerToken));
+    }
+    /** The chars→token ratio a token budget maps to (for compression sizing). */
+    charsForTokens(tokens) {
+        return Math.max(0, Math.floor(tokens * this.charsPerToken));
+    }
+    /** Nudge the ratio toward an observed (chars, actualTokens) sample. Ignores degenerate samples. */
+    calibrate(chars, actualTokens) {
+        if (chars <= 0 || actualTokens <= 0)
+            return;
+        const observed = chars / actualTokens;
+        this.charsPerToken = (1 - EWMA_ALPHA) * this.charsPerToken + EWMA_ALPHA * observed;
+    }
+    ratio() {
+        return this.charsPerToken;
+    }
+}
+/** Convenience: a one-off estimate with the default ratio. */
+export function estimateTokens(text) {
+    return new TokenEstimator().estimate(text);
+}

package/dist/conversations/conversations.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Conversation store — full original turns as JSONL, one log + one meta record per conversation. This
+ * is persistent local USER DATA (recoverable originals), deliberately separate from telemetry (which
+ * never stores prompts) and from memory (durable facts). Resolved secret VALUES are still scrubbed so a
+ * pasted key can't be persisted, but user prose is kept intact.
+ */
+import type { Clock } from '../util/clock.js';
+import type { Area } from '../store/area.js';
+export type TurnRole = 'user' | 'assistant' | 'system';
+export interface ConversationTurn {
+    role: TurnRole;
+    text: string;
+    ts: number;
+    runId?: string;
+}
+export interface ConversationMeta {
+    id: string;
+    title: string;
+    createdAt: number;
+    updatedAt: number;
+    turns: number;
+}
+export declare class ConversationStore {
+    private readonly area;
+    private readonly clock;
+    private counter;
+    constructor(area: Area, clock?: Clock);
+    get enabled(): boolean;
+    /** Start a conversation; returns its id. */
+    start(id?: string): string;
+    /** Append a turn (originals preserved; only resolved secrets scrubbed). Titles derive from turn 1. */
+    append(id: string, role: TurnRole, text: string, runId?: string): void;
+    turns(id: string): ConversationTurn[];
+    meta(id: string): ConversationMeta | undefined;
+    /** All conversations, newest first. A corrupt meta file is skipped, not fatal. */
+    list(): ConversationMeta[];
+    delete(id: string): void;
+}

package/dist/conversations/conversations.js

@@ -0,0 +1,64 @@
+/**
+ * Conversation store — full original turns as JSONL, one log + one meta record per conversation. This
+ * is persistent local USER DATA (recoverable originals), deliberately separate from telemetry (which
+ * never stores prompts) and from memory (durable facts). Resolved secret VALUES are still scrubbed so a
+ * pasted key can't be persisted, but user prose is kept intact.
+ */
+import { systemClock } from '../util/clock.js';
+import { redactString } from '../security/redact.js';
+function deriveTitle(text) {
+    const clean = text.replace(/\s+/g, ' ').trim();
+    if (!clean)
+        return 'Untitled';
+    const words = clean.split(' ').slice(0, 8).join(' ');
+    return words.length > 60 ? words.slice(0, 57) + '…' : words;
+}
+export class ConversationStore {
+    area;
+    clock;
+    counter = 0;
+    constructor(area, clock = systemClock) {
+        this.area = area;
+        this.clock = clock;
+    }
+    get enabled() {
+        return this.area.enabled;
+    }
+    /** Start a conversation; returns its id. */
+    start(id) {
+        const cid = id ?? `conv_${this.clock.now().toString(36)}_${process.pid.toString(36)}_${(this.counter += 1).toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
+        const now = this.clock.now();
+        const meta = { id: cid, title: 'Untitled', createdAt: now, updatedAt: now, turns: 0 };
+        this.area.writeJson(cid, meta);
+        return cid;
+    }
+    /** Append a turn (originals preserved; only resolved secrets scrubbed). Titles derive from turn 1. */
+    append(id, role, text, runId) {
+        const safe = redactString(text);
+        const turn = { role, text: safe, ts: this.clock.now(), ...(runId ? { runId } : {}) };
+        this.area.appendLine(id, turn);
+        const meta = this.area.tryReadJson(id) ?? { id, title: 'Untitled', createdAt: turn.ts, updatedAt: turn.ts, turns: 0 };
+        meta.turns += 1;
+        meta.updatedAt = turn.ts;
+        if (meta.title === 'Untitled' && role === 'user')
+            meta.title = deriveTitle(safe);
+        this.area.writeJson(id, meta);
+    }
+    turns(id) {
+        return this.area.readLines(id);
+    }
+    meta(id) {
+        return this.area.tryReadJson(id);
+    }
+    /** All conversations, newest first. A corrupt meta file is skipped, not fatal. */
+    list() {
+        return this.area
+            .listIds()
+            .map((id) => this.area.tryReadJson(id))
+            .filter((m) => m !== undefined)
+            .sort((a, b) => b.updatedAt - a.updatedAt);
+    }
+    delete(id) {
+        this.area.remove(id);
+    }
+}

package/dist/core/capabilities/evidence.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The evidence engine — the heart of the "never claim a capability with false certainty" rule.
+ *
+ * Two invariants enforced here and covered by tests:
+ *   1. `unknown` and `unsupported` NEVER satisfy a requirement.
+ *   2. Merging capability facts never PROMOTES evidence beyond what a source actually asserted;
+ *      the higher-ranked source wins, ties keep the first, and a positive claim can only be
+ *      overridden by an equally- or higher-ranked source.
+ */
+import type { Capability, CapabilityProfile, CapabilityRequirement, Evidence } from '../../types.js';
+import type { BooleanCapabilityGroup } from './taxonomy.js';
+export declare function rankOf(evidence: Evidence): number;
+/** The capability returned for anything we have no fact about: false @ unknown. Never satisfies. */
+export declare function unknownCapability(): Capability;
+/** An empty profile — every lookup falls back to `unknown`. */
+export declare function emptyProfile(contextWindow?: number): CapabilityProfile;
+/** Look up one boolean capability, returning the `unknown` default when absent. */
+export declare function getCapability(profile: CapabilityProfile, group: BooleanCapabilityGroup, key: string): Capability;
+/**
+ * Does `profile` satisfy `req`? True only when the capability is positively present AND its evidence
+ * rank meets the requirement's floor (default `documented`). `unknown`/`unsupported` can never pass
+ * because their rank (1/0) is below any real floor and their value is false.
+ */
+export declare function capabilitySatisfies(profile: CapabilityProfile, req: CapabilityRequirement): boolean;
+/**
+ * Merge two capability facts without ever inventing certainty. The source with the higher evidence
+ * rank wins outright. On a tie, `a` is kept. This means a `documented:true` is never silently
+ * upgraded to `verified:true` by a second `documented` source — evidence only moves when a
+ * genuinely higher-ranked source says so.
+ */
+export declare function mergeCapability<V>(a: Capability<V>, b: Capability<V>): Capability<V>;
+/** Merge two full profiles fact-by-fact under the never-promote rule. */
+export declare function mergeProfiles(a: CapabilityProfile, b: CapabilityProfile): CapabilityProfile;
+/**
+ * Build a profile from a plain list of supported keys, all tagged at one evidence level. Used by
+ * providers/config that self-declare capabilities. Anything not listed stays `unknown` (absent).
+ */
+export declare function profileFromDeclared(declared: Partial<Record<BooleanCapabilityGroup, string[]>> & {
+    contextWindow?: number;
+}, evidence: Evidence): CapabilityProfile;

package/dist/core/capabilities/evidence.js

@@ -0,0 +1,102 @@
+/**
+ * The evidence engine — the heart of the "never claim a capability with false certainty" rule.
+ *
+ * Two invariants enforced here and covered by tests:
+ *   1. `unknown` and `unsupported` NEVER satisfy a requirement.
+ *   2. Merging capability facts never PROMOTES evidence beyond what a source actually asserted;
+ *      the higher-ranked source wins, ties keep the first, and a positive claim can only be
+ *      overridden by an equally- or higher-ranked source.
+ */
+import { EVIDENCE_RANK } from '../../types.js';
+export function rankOf(evidence) {
+    return EVIDENCE_RANK[evidence];
+}
+/** The capability returned for anything we have no fact about: false @ unknown. Never satisfies. */
+export function unknownCapability() {
+    return { value: false, evidence: 'unknown' };
+}
+/** An empty profile — every lookup falls back to `unknown`. */
+export function emptyProfile(contextWindow = 0) {
+    return {
+        input: {},
+        output: {},
+        intelligence: {},
+        agent: {},
+        context: { contextWindow: { value: contextWindow, evidence: contextWindow > 0 ? 'documented' : 'unknown' } },
+    };
+}
+/** Look up one boolean capability, returning the `unknown` default when absent. */
+export function getCapability(profile, group, key) {
+    const bucket = profile[group];
+    return bucket[key] ?? unknownCapability();
+}
+/**
+ * Does `profile` satisfy `req`? True only when the capability is positively present AND its evidence
+ * rank meets the requirement's floor (default `documented`). `unknown`/`unsupported` can never pass
+ * because their rank (1/0) is below any real floor and their value is false.
+ */
+export function capabilitySatisfies(profile, req) {
+    const cap = getCapability(profile, req.group, req.key);
+    if (!cap.value)
+        return false;
+    const floor = rankOf(req.minEvidence ?? 'documented');
+    return rankOf(cap.evidence) >= floor;
+}
+/**
+ * Merge two capability facts without ever inventing certainty. The source with the higher evidence
+ * rank wins outright. On a tie, `a` is kept. This means a `documented:true` is never silently
+ * upgraded to `verified:true` by a second `documented` source — evidence only moves when a
+ * genuinely higher-ranked source says so.
+ */
+export function mergeCapability(a, b) {
+    return rankOf(b.evidence) > rankOf(a.evidence) ? b : a;
+}
+function mergeBucket(a, b) {
+    const out = {};
+    for (const key of new Set([...Object.keys(a), ...Object.keys(b)])) {
+        const av = a[key];
+        const bv = b[key];
+        if (av && bv)
+            out[key] = mergeCapability(av, bv);
+        else if (av)
+            out[key] = av;
+        else if (bv)
+            out[key] = bv;
+    }
+    return out;
+}
+/** Merge two full profiles fact-by-fact under the never-promote rule. */
+export function mergeProfiles(a, b) {
+    return {
+        input: mergeBucket(a.input, b.input),
+        output: mergeBucket(a.output, b.output),
+        intelligence: mergeBucket(a.intelligence, b.intelligence),
+        agent: mergeBucket(a.agent, b.agent),
+        context: {
+            contextWindow: mergeCapability(a.context.contextWindow, b.context.contextWindow),
+            maxOutputTokens: a.context.maxOutputTokens && b.context.maxOutputTokens
+                ? mergeCapability(a.context.maxOutputTokens, b.context.maxOutputTokens)
+                : (a.context.maxOutputTokens ?? b.context.maxOutputTokens),
+        },
+    };
+}
+/**
+ * Build a profile from a plain list of supported keys, all tagged at one evidence level. Used by
+ * providers/config that self-declare capabilities. Anything not listed stays `unknown` (absent).
+ */
+export function profileFromDeclared(declared, evidence) {
+    const profile = emptyProfile(declared.contextWindow ?? 0);
+    const groups = ['input', 'output', 'intelligence', 'agent'];
+    for (const group of groups) {
+        const keys = declared[group];
+        if (!keys)
+            continue;
+        const bucket = profile[group];
+        for (const key of keys)
+            bucket[key] = { value: true, evidence };
+    }
+    if (declared.contextWindow && declared.contextWindow > 0) {
+        profile.context.contextWindow = { value: declared.contextWindow, evidence };
+    }
+    return profile;
+}

package/dist/core/capabilities/overlay.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A runtime capability overlay. Verified probe results (and the one sanctioned runtime DEMOTION —
+ * a gateway that rejects response_format) live here, keyed by (provider, model), and are merged over
+ * the catalog/declared profile at routing time under the same never-promote merge rule. This keeps the
+ * static catalog deterministic while letting evidence improve as the system actually exercises models.
+ */
+import type { CapabilityProfile } from '../../types.js';
+export declare class CapabilityOverlay {
+    private readonly map;
+    private key;
+    get(providerId: string, model: string): CapabilityProfile | undefined;
+    /** Merge a probed profile into the overlay for a model (never-promote merge). */
+    set(providerId: string, model: string, profile: CapabilityProfile): void;
+    size(): number;
+}

package/dist/core/capabilities/taxonomy.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The normalized capability taxonomy. This is the vocabulary the whole router speaks;
+ * provider adapters map their vendor-specific truth INTO these terms so that `core/` never
+ * has to know a vendor name. Adding a term here is the only sanctioned way to grow the taxonomy.
+ */
+export declare const INPUT_MODALITIES: readonly ["text", "image", "audio", "video", "file", "pdf"];
+export type InputModality = (typeof INPUT_MODALITIES)[number];
+export declare const OUTPUT_MODALITIES: readonly ["text", "json", "structured_output", "code", "image", "audio"];
+export type OutputModality = (typeof OUTPUT_MODALITIES)[number];
+export declare const INTELLIGENCE_SKILLS: readonly ["reasoning", "classification", "summarization", "code_generation", "code_analysis", "planning", "translation", "extraction"];
+export type IntelligenceSkill = (typeof INTELLIGENCE_SKILLS)[number];
+export declare const AGENT_CAPABILITIES: readonly ["tool_calling", "function_calling", "mcp", "agentic_loop"];
+export type AgentCapability = (typeof AGENT_CAPABILITIES)[number];
+/** The five groups a capability requirement can address. `context` is numeric, handled separately. */
+export type CapabilityGroup = 'input' | 'output' | 'intelligence' | 'agent' | 'context';
+/** Groups whose keys are booleans (everything but the numeric `context`). */
+export type BooleanCapabilityGroup = 'input' | 'output' | 'intelligence' | 'agent';
+/** All valid keys for a boolean group, as a runtime lookup used by config validation. */
+export declare const CAPABILITY_KEYS: Record<BooleanCapabilityGroup, readonly string[]>;

package/dist/core/capabilities/taxonomy.js

@@ -0,0 +1,25 @@
+/**
+ * The normalized capability taxonomy. This is the vocabulary the whole router speaks;
+ * provider adapters map their vendor-specific truth INTO these terms so that `core/` never
+ * has to know a vendor name. Adding a term here is the only sanctioned way to grow the taxonomy.
+ */
+export const INPUT_MODALITIES = ['text', 'image', 'audio', 'video', 'file', 'pdf'];
+export const OUTPUT_MODALITIES = ['text', 'json', 'structured_output', 'code', 'image', 'audio'];
+export const INTELLIGENCE_SKILLS = [
+    'reasoning',
+    'classification',
+    'summarization',
+    'code_generation',
+    'code_analysis',
+    'planning',
+    'translation',
+    'extraction',
+];
+export const AGENT_CAPABILITIES = ['tool_calling', 'function_calling', 'mcp', 'agentic_loop'];
+/** All valid keys for a boolean group, as a runtime lookup used by config validation. */
+export const CAPABILITY_KEYS = {
+    input: INPUT_MODALITIES,
+    output: OUTPUT_MODALITIES,
+    intelligence: INTELLIGENCE_SKILLS,
+    agent: AGENT_CAPABILITIES,
+};

package/dist/core/fallback/errors.d.ts

@@ -0,0 +1,30 @@
+/**
+ * One authoritative error taxonomy for the whole router. A compact {status, retryable, category}
+ * shape is exactly what fallback needs: `category` spans the full ErrorCategory set and the error
+ * carries provider/model.
+ *
+ * SECURITY: an AIError stores only a category, a status, and a provider/model — never a key, never
+ * a request URL. Messages are assumed to reach a sink, so callers pass already-redacted text.
+ */
+import type { ErrorCategory, RouterErrorInfo } from '../../types.js';
+export interface AIErrorOptions {
+    category?: ErrorCategory;
+    status?: number | null;
+    retryable?: boolean;
+    providerId?: string;
+    model?: string;
+}
+export declare class AIError extends Error {
+    readonly category: ErrorCategory;
+    readonly status: number | null;
+    readonly retryable: boolean;
+    readonly providerId?: string;
+    readonly model?: string;
+    constructor(message: string, opts?: AIErrorOptions);
+    toInfo(): RouterErrorInfo;
+}
+export declare function isRetryable(category: ErrorCategory): boolean;
+/** Map an HTTP status to a category. Provider adapters may refine this with body inspection. */
+export declare function statusToCategory(status: number): ErrorCategory;
+/** Coerce any thrown value into an AIError without losing an existing category. */
+export declare function toAIError(err: unknown, fallback?: AIErrorOptions): AIError;

package/dist/core/fallback/errors.js

@@ -0,0 +1,80 @@
+/**
+ * One authoritative error taxonomy for the whole router. A compact {status, retryable, category}
+ * shape is exactly what fallback needs: `category` spans the full ErrorCategory set and the error
+ * carries provider/model.
+ *
+ * SECURITY: an AIError stores only a category, a status, and a provider/model — never a key, never
+ * a request URL. Messages are assumed to reach a sink, so callers pass already-redacted text.
+ */
+export class AIError extends Error {
+    category;
+    status;
+    retryable;
+    providerId;
+    model;
+    constructor(message, opts = {}) {
+        super(message);
+        this.name = 'AIError';
+        this.category = opts.category ?? 'UNKNOWN';
+        this.status = opts.status ?? null;
+        this.retryable = opts.retryable ?? isRetryable(this.category);
+        if (opts.providerId !== undefined)
+            this.providerId = opts.providerId;
+        if (opts.model !== undefined)
+            this.model = opts.model;
+    }
+    toInfo() {
+        const info = {
+            category: this.category,
+            message: this.message,
+            retryable: this.retryable,
+        };
+        if (this.providerId !== undefined)
+            info.providerId = this.providerId;
+        if (this.model !== undefined)
+            info.model = this.model;
+        return info;
+    }
+}
+/**
+ * Retryable-vs-terminal by category. Retryable failures are the transient wire/limit ones;
+ * everything caused by a bad request, bad key, or missing capability is terminal — retrying
+ * it against the same provider only wastes calls (the never-re-hammer rule).
+ */
+const RETRYABLE = new Set([
+    'RATE_LIMIT',
+    'QUOTA',
+    'TIMEOUT',
+    'NETWORK',
+    'PROVIDER',
+]);
+export function isRetryable(category) {
+    return RETRYABLE.has(category);
+}
+/** Map an HTTP status to a category. Provider adapters may refine this with body inspection. */
+export function statusToCategory(status) {
+    if (status === 401)
+        return 'AUTHENTICATION';
+    if (status === 403)
+        return 'AUTHORIZATION';
+    if (status === 404)
+        return 'MODEL_NOT_FOUND';
+    if (status === 408)
+        return 'TIMEOUT';
+    if (status === 422)
+        return 'INVALID_REQUEST';
+    if (status === 429)
+        return 'RATE_LIMIT';
+    if (status >= 500)
+        return 'PROVIDER';
+    if (status >= 400)
+        return 'INVALID_REQUEST';
+    return 'UNKNOWN';
+}
+/** Coerce any thrown value into an AIError without losing an existing category. */
+export function toAIError(err, fallback = {}) {
+    if (err instanceof AIError)
+        return err;
+    const message = err instanceof Error ? err.message : String(err);
+    return new AIError(message, fallback);
+}

package/dist/core/fallback/fallback.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Cross-provider fallback. Walks the ranked candidates; on failure it moves to the next candidate,
+ * but never re-hammers a provider that already returned a NON-retryable error (that provider's later
+ * candidates are skipped). A STOP-category error aborts the whole run. If nothing succeeds the result
+ * is ALL_PROVIDERS_FAILED, carrying the full attempt trace and the last underlying error.
+ */
+import type { AIProvider } from '../../providers/provider.js';
+import type { AIResponse, AttemptRecord, ValidationReport } from '../../types.js';
+import type { ScoredCandidate } from '../router/scorer.js';
+import type { RequestTemplate } from '../router/normalize.js';
+import { AIError } from './errors.js';
+import type { BudgetTracker } from '../policies/budget.js';
+import type { Clock } from '../../util/clock.js';
+export interface FallbackInput {
+    ranked: ScoredCandidate[];
+    template: RequestTemplate;
+    getProvider: (id: string) => AIProvider | undefined;
+    maxFallbacks: number;
+    signal?: AbortSignal;
+    clock?: Clock;
+    onAttempt?: (record: AttemptRecord) => void;
+    /** Optional Phase-6 validation. A failing report drops this candidate and continues (no poisoning). */
+    validate?: (response: AIResponse, model: string) => ValidationReport;
+    /** Optional spend guardrail. When it cannot afford the next call, the run STOPS with BUDGET. */
+    budget?: BudgetTracker;
+    /** Estimated USD cost of a candidate call, consulted before spending (used with `budget`). */
+    costOf?: (providerId: string, model: string) => Promise<number>;
+}
+export type FallbackResult = {
+    ok: true;
+    response: AIResponse;
+    used: ScoredCandidate;
+    attempts: AttemptRecord[];
+    validation?: ValidationReport;
+} | {
+    ok: false;
+    error: AIError;
+    attempts: AttemptRecord[];
+};
+export declare function runWithFallback(input: FallbackInput): Promise<FallbackResult>;

package/dist/core/fallback/fallback.js

@@ -0,0 +1,82 @@
+/**
+ * Cross-provider fallback. Walks the ranked candidates; on failure it moves to the next candidate,
+ * but never re-hammers a provider that already returned a NON-retryable error (that provider's later
+ * candidates are skipped). A STOP-category error aborts the whole run. If nothing succeeds the result
+ * is ALL_PROVIDERS_FAILED, carrying the full attempt trace and the last underlying error.
+ */
+import { buildRequest } from '../router/request.js';
+import { executeOnce } from '../router/executor.js';
+import { AIError } from './errors.js';
+import { attemptOutcome, isStop } from './retryPolicy.js';
+import { systemClock } from '../../util/clock.js';
+export async function runWithFallback(input) {
+    const clock = input.clock ?? systemClock;
+    const attempts = [];
+    const poisoned = new Set(); // providers that returned a non-retryable error
+    let lastError;
+    let tried = 0;
+    const limit = input.maxFallbacks + 1;
+    for (const scored of input.ranked) {
+        if (tried >= limit)
+            break;
+        const { providerId, model } = scored.candidate;
+        if (poisoned.has(providerId))
+            continue;
+        const provider = input.getProvider(providerId);
+        if (!provider)
+            continue;
+        // Budget gate: if we cannot afford this call, stop the whole run with BUDGET (not a fallback).
+        const estCost = input.budget?.active && input.costOf ? await input.costOf(providerId, model.id) : 0;
+        if (input.budget && !input.budget.canSpend(estCost)) {
+            lastError = new AIError(`run budget exhausted (calls=${input.budget.callsUsed}, cost=${input.budget.costUsed.toFixed(4)})`, { category: 'BUDGET', retryable: false });
+            break;
+        }
+        tried += 1;
+        const started = clock.now();
+        const request = buildRequest(input.template, model.id, input.signal);
+        const outcome = await executeOnce(provider, request);
+        const latencyMs = clock.now() - started;
+        input.budget?.recordCall(estCost);
+        if (outcome.ok) {
+            const validation = input.validate?.(outcome.response, model.id);
+            if (validation && !validation.ok) {
+                // Response-specific failure: drop this candidate but do NOT poison the provider.
+                const why = validation.checks.filter((c) => !c.ok).map((c) => c.why).filter(Boolean).join('; ');
+                const record = { providerId, model: model.id, outcome: 'non-retryable', category: 'RESPONSE_VALIDATION', latencyMs };
+                attempts.push(record);
+                input.onAttempt?.(record);
+                lastError = new AIError(`response failed validation: ${why}`, { category: 'RESPONSE_VALIDATION', retryable: false, providerId, model: model.id });
+                continue;
+            }
+            attempts.push({ providerId, model: model.id, outcome: 'success', latencyMs });
+            input.onAttempt?.(attempts[attempts.length - 1]);
+            return { ok: true, response: outcome.response, used: scored, attempts, ...(validation ? { validation } : {}) };
+        }
+        const record = {
+            providerId,
+            model: model.id,
+            outcome: attemptOutcome(outcome.error),
+            category: outcome.error.category,
+            latencyMs,
+        };
+        attempts.push(record);
+        input.onAttempt?.(record);
+        lastError = outcome.error;
+        if (record.outcome === 'non-retryable')
+            poisoned.add(providerId);
+        if (isStop(outcome.error.category))
+            break;
+    }
+    // A stop-category error (budget/config/privacy) surfaces as-is; otherwise aggregate as ALL_PROVIDERS_FAILED.
+    const error = lastError !== undefined && isStop(lastError.category)
+        ? lastError
+        : lastError !== undefined
+            ? new AIError(`all providers failed — last: ${lastError.message}`, {
+                category: 'ALL_PROVIDERS_FAILED',
+                retryable: false,
+                ...(lastError.providerId !== undefined ? { providerId: lastError.providerId } : {}),
+                ...(lastError.model !== undefined ? { model: lastError.model } : {}),
+            })
+            : new AIError('no candidate could be executed', { category: 'ALL_PROVIDERS_FAILED', retryable: false });
+    return { ok: false, error, attempts };
+}

package/dist/core/fallback/retryPolicy.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Fallback classification. Distinct from the SAME-provider retry (which lives in the HTTP layer):
+ * this governs CROSS-provider traversal. A failure means "try the next candidate",
+ * except for a few categories that make trying anything else pointless (budget spent, config broken,
+ * a privacy policy that forbade the route) — those stop the whole run.
+ */
+import type { AttemptRecord, ErrorCategory } from '../../types.js';
+import type { AIError } from './errors.js';
+/** Should this error abort the entire run rather than fall through to the next provider? */
+export declare function isStop(category: ErrorCategory): boolean;
+export declare function attemptOutcome(err: AIError): AttemptRecord['outcome'];

package/dist/core/fallback/retryPolicy.js

@@ -0,0 +1,14 @@
+/**
+ * Fallback classification. Distinct from the SAME-provider retry (which lives in the HTTP layer):
+ * this governs CROSS-provider traversal. A failure means "try the next candidate",
+ * except for a few categories that make trying anything else pointless (budget spent, config broken,
+ * a privacy policy that forbade the route) — those stop the whole run.
+ */
+const STOP = new Set(['BUDGET', 'CONFIG', 'PRIVACY_VIOLATION']);
+/** Should this error abort the entire run rather than fall through to the next provider? */
+export function isStop(category) {
+    return STOP.has(category);
+}
+export function attemptOutcome(err) {
+    return err.retryable ? 'retryable' : 'non-retryable';
+}

package/dist/core/health/health.d.ts

@@ -0,0 +1,3 @@
+/** Health-state predicate: which states may still receive traffic. Unknown/unchecked is optimistic. */
+import type { HealthState } from '../../types.js';
+export declare function isRoutableState(state: HealthState): boolean;

package/dist/core/health/health.js

@@ -0,0 +1,5 @@
+/** Health-state predicate: which states may still receive traffic. Unknown/unchecked is optimistic. */
+const ROUTABLE = new Set(['AVAILABLE', 'CONFIGURED', 'DEGRADED', 'UNKNOWN']);
+export function isRoutableState(state) {
+    return ROUTABLE.has(state);
+}

package/dist/core/health/monitor.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Per-provider health tracker. Seeded from healthCheck() and updated by execution outcomes: a
+ * rate-limit or quota error puts the provider in a timed cooldown so subsequent routing skips it;
+ * a success restores it. State transitions emit `health.transition` telemetry. Cooldowns persist on
+ * the AI instance across run() calls, which is what makes "back off a throttled provider" real.
+ */
+import type { ErrorCategory, HealthStatus } from '../../types.js';
+import type { Clock } from '../../util/clock.js';
+import type { TelemetrySink } from '../../telemetry/telemetry.js';
+export declare class HealthMonitor {
+    private readonly telemetry?;
+    private readonly cooldownMs;
+    private readonly state;
+    private readonly clock;
+    constructor(telemetry?: TelemetrySink | undefined, clock?: Clock, cooldownMs?: number);
+    get(providerId: string): HealthStatus | undefined;
+    all(): HealthStatus[];
+    /** Optimistic: an unseen provider is routable; a cooled-down one becomes routable again once elapsed. */
+    routable(providerId: string): boolean;
+    seed(status: HealthStatus): void;
+    recordOutcome(providerId: string, ok: boolean, category?: ErrorCategory): void;
+    private transition;
+}