ai-runtime-engine 1.1.0

package/dist/core/health/monitor.js

@@ -0,0 +1,82 @@
+/**
+ * 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 { systemClock } from '../../util/clock.js';
+import { redactString } from '../../security/redact.js';
+import { isRoutableState } from './health.js';
+function categoryToState(category) {
+    switch (category) {
+        case 'RATE_LIMIT':
+            return 'RATE_LIMITED';
+        case 'QUOTA':
+            return 'QUOTA_EXCEEDED';
+        case 'AUTHENTICATION':
+        case 'AUTHORIZATION':
+            return 'AUTH_FAILED';
+        case 'NETWORK':
+            return 'NETWORK_ERROR';
+        case 'TIMEOUT':
+        case 'PROVIDER':
+            return 'DEGRADED';
+        case 'MODEL_NOT_FOUND':
+            return 'MODEL_UNAVAILABLE';
+        default:
+            return 'DEGRADED';
+    }
+}
+export class HealthMonitor {
+    telemetry;
+    cooldownMs;
+    state = new Map();
+    clock;
+    constructor(telemetry, clock = systemClock, cooldownMs = 60_000) {
+        this.telemetry = telemetry;
+        this.cooldownMs = cooldownMs;
+        this.clock = clock;
+    }
+    get(providerId) {
+        return this.state.get(providerId);
+    }
+    all() {
+        return [...this.state.values()];
+    }
+    /** Optimistic: an unseen provider is routable; a cooled-down one becomes routable again once elapsed. */
+    routable(providerId) {
+        const s = this.state.get(providerId);
+        if (!s)
+            return true;
+        if (s.cooldownUntil !== undefined)
+            return this.clock.now() >= s.cooldownUntil;
+        return s.routable;
+    }
+    seed(status) {
+        this.transition(status.providerId, status.state, status.detail);
+    }
+    recordOutcome(providerId, ok, category) {
+        if (ok) {
+            this.transition(providerId, 'AVAILABLE');
+            return;
+        }
+        const to = category ? categoryToState(category) : 'DEGRADED';
+        const cooldown = to === 'RATE_LIMITED' || to === 'QUOTA_EXCEEDED' ? this.clock.now() + this.cooldownMs : undefined;
+        this.transition(providerId, to, undefined, cooldown);
+    }
+    transition(providerId, to, detail, cooldownUntil) {
+        const prev = this.state.get(providerId);
+        const status = {
+            providerId,
+            state: to,
+            routable: isRoutableState(to) && cooldownUntil === undefined,
+            checkedAt: this.clock.now(),
+            ...(detail !== undefined ? { detail: redactString(detail) } : {}),
+            ...(cooldownUntil !== undefined ? { cooldownUntil } : {}),
+        };
+        this.state.set(providerId, status);
+        if (this.telemetry && prev?.state !== to) {
+            this.telemetry.emit({ type: 'health.transition', ts: this.clock.now(), providerId, from: prev?.state ?? 'UNKNOWN', to });
+        }
+    }
+}

package/dist/core/policies/budget.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Per-run spend guardrail. Bounds a single run()'s total calls and/or estimated cost across the
+ * primary attempt, fallbacks, and verification. A `maxCalls`/cost ceiling: when the budget is spent,
+ * the run STOPS with a distinct BUDGET category rather than being mistaken for a provider failure and
+ * retried elsewhere.
+ */
+export declare class BudgetTracker {
+    private readonly maxCalls?;
+    private readonly maxCostUsd?;
+    private calls;
+    private costUsd;
+    constructor(maxCalls?: number | undefined, maxCostUsd?: number | undefined);
+    get callsUsed(): number;
+    get costUsed(): number;
+    get active(): boolean;
+    /** Would one more call costing at most `estCostUsd` stay within budget? */
+    canSpend(estCostUsd?: number): boolean;
+    recordCall(costUsd?: number): void;
+}

package/dist/core/policies/budget.js

@@ -0,0 +1,37 @@
+/**
+ * Per-run spend guardrail. Bounds a single run()'s total calls and/or estimated cost across the
+ * primary attempt, fallbacks, and verification. A `maxCalls`/cost ceiling: when the budget is spent,
+ * the run STOPS with a distinct BUDGET category rather than being mistaken for a provider failure and
+ * retried elsewhere.
+ */
+export class BudgetTracker {
+    maxCalls;
+    maxCostUsd;
+    calls = 0;
+    costUsd = 0;
+    constructor(maxCalls, maxCostUsd) {
+        this.maxCalls = maxCalls;
+        this.maxCostUsd = maxCostUsd;
+    }
+    get callsUsed() {
+        return this.calls;
+    }
+    get costUsed() {
+        return this.costUsd;
+    }
+    get active() {
+        return this.maxCalls !== undefined || this.maxCostUsd !== undefined;
+    }
+    /** Would one more call costing at most `estCostUsd` stay within budget? */
+    canSpend(estCostUsd = 0) {
+        if (this.maxCalls !== undefined && this.calls >= this.maxCalls)
+            return false;
+        if (this.maxCostUsd !== undefined && this.costUsd + estCostUsd > this.maxCostUsd)
+            return false;
+        return true;
+    }
+    recordCall(costUsd = 0) {
+        this.calls += 1;
+        this.costUsd += costUsd;
+    }
+}

package/dist/core/registry/builtinTasks.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Built-in task definitions — the QA Brain integration seam expressed as data. Each named task maps
+ * to the capabilities a model must have to serve it. Grounded in the actual QA Brain skills
+ * (url-to-test, trace analysis, test-healer, framework-converter, feature-analyzer, jira-to-test).
+ * Users extend or override these via `ai.registerTask()`, `new AI({ tasks })`, or YAML `tasks:`.
+ */
+import type { TaskDefinition } from '../../types.js';
+export declare const BUILTIN_TASKS: TaskDefinition[];

package/dist/core/registry/builtinTasks.js

@@ -0,0 +1,54 @@
+/**
+ * Built-in task definitions — the QA Brain integration seam expressed as data. Each named task maps
+ * to the capabilities a model must have to serve it. Grounded in the actual QA Brain skills
+ * (url-to-test, trace analysis, test-healer, framework-converter, feature-analyzer, jira-to-test).
+ * Users extend or override these via `ai.registerTask()`, `new AI({ tasks })`, or YAML `tasks:`.
+ */
+const req = (group, key, minEvidence) => minEvidence ? { group, key, minEvidence } : { group, key };
+export const BUILTIN_TASKS = [
+    {
+        id: 'generate-playwright-tests',
+        aliases: ['url-to-test'],
+        description: 'Generate Playwright tests from a URL, ticket, or spec.',
+        required: [req('intelligence', 'code_generation'), req('intelligence', 'reasoning'), req('output', 'code')],
+        preferred: [req('agent', 'tool_calling')],
+        minContextWindow: 32_000,
+        output: { format: 'code' },
+        defaultStrategy: 'highest-quality',
+    },
+    {
+        id: 'playwright-trace-analysis',
+        aliases: ['trace-analysis', 'analyze-playwright-trace'],
+        description: 'Analyze a Playwright trace and suggest a fix.',
+        required: [req('intelligence', 'code_analysis'), req('intelligence', 'reasoning')],
+        preferred: [req('input', 'image'), req('input', 'file')],
+        minContextWindow: 128_000,
+        defaultStrategy: 'best',
+    },
+    {
+        id: 'test-healer',
+        description: 'Repair a broken test given the failure and the current code.',
+        required: [req('intelligence', 'code_analysis'), req('intelligence', 'code_generation')],
+        minContextWindow: 64_000,
+        output: { format: 'code' },
+    },
+    {
+        id: 'framework-converter',
+        description: 'Convert a test/script from one framework to another.',
+        required: [req('intelligence', 'code_generation'), req('intelligence', 'code_analysis')],
+        minContextWindow: 64_000,
+        output: { format: 'code' },
+    },
+    {
+        id: 'feature-analyzer',
+        description: 'Analyze a feature for test coverage and intent.',
+        required: [req('intelligence', 'reasoning'), req('intelligence', 'summarization'), req('intelligence', 'extraction')],
+        minContextWindow: 32_000,
+    },
+    {
+        id: 'jira-to-test',
+        aliases: ['ticket-router'],
+        description: 'Turn a Jira ticket into test cases / routing intent.',
+        required: [req('intelligence', 'reasoning'), req('intelligence', 'extraction'), req('intelligence', 'classification')],
+    },
+];

package/dist/core/registry/registry.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The provider registry. Holds provider instances and their enabled state. The router only ever
+ * reaches providers through here, and only through the `AIProvider` contract — so a new vendor is
+ * just another registered instance, never a special case.
+ */
+import type { AIProvider } from '../../providers/provider.js';
+export declare class ProviderRegistry {
+    private readonly entries;
+    register(provider: AIProvider, enabled?: boolean): void;
+    setEnabled(id: string, enabled: boolean): void;
+    has(id: string): boolean;
+    get(id: string): AIProvider | undefined;
+    /** Every registered provider, regardless of enabled state. */
+    all(): AIProvider[];
+    /** Only the providers eligible to serve traffic. */
+    enabled(): AIProvider[];
+    isEnabled(id: string): boolean;
+}

package/dist/core/registry/registry.js

@@ -0,0 +1,33 @@
+/**
+ * The provider registry. Holds provider instances and their enabled state. The router only ever
+ * reaches providers through here, and only through the `AIProvider` contract — so a new vendor is
+ * just another registered instance, never a special case.
+ */
+export class ProviderRegistry {
+    entries = new Map();
+    register(provider, enabled = true) {
+        this.entries.set(provider.id, { provider, enabled });
+    }
+    setEnabled(id, enabled) {
+        const entry = this.entries.get(id);
+        if (entry)
+            entry.enabled = enabled;
+    }
+    has(id) {
+        return this.entries.has(id);
+    }
+    get(id) {
+        return this.entries.get(id)?.provider;
+    }
+    /** Every registered provider, regardless of enabled state. */
+    all() {
+        return [...this.entries.values()].map((e) => e.provider);
+    }
+    /** Only the providers eligible to serve traffic. */
+    enabled() {
+        return [...this.entries.values()].filter((e) => e.enabled).map((e) => e.provider);
+    }
+    isEnabled(id) {
+        return this.entries.get(id)?.enabled ?? false;
+    }
+}

package/dist/core/registry/taskRegistry.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The task registry: named task -> TaskDefinition, resolving aliases and merging sources by
+ * precedence. Built-ins are the floor; config tasks and `registerTask()` override by id.
+ */
+import type { TaskDefinition } from '../../types.js';
+export declare class TaskRegistry {
+    private readonly byId;
+    private readonly aliasToId;
+    constructor(extra?: TaskDefinition[]);
+    /** Register (or override by id) a task definition and index its aliases. */
+    register(def: TaskDefinition): void;
+    /** Look up a task by id or alias. Returns undefined for an unknown task (caller infers). */
+    lookup(nameOrAlias: string): TaskDefinition | undefined;
+    list(): TaskDefinition[];
+}

package/dist/core/registry/taskRegistry.js

@@ -0,0 +1,30 @@
+/**
+ * The task registry: named task -> TaskDefinition, resolving aliases and merging sources by
+ * precedence. Built-ins are the floor; config tasks and `registerTask()` override by id.
+ */
+import { BUILTIN_TASKS } from './builtinTasks.js';
+export class TaskRegistry {
+    byId = new Map();
+    aliasToId = new Map();
+    constructor(extra = []) {
+        for (const def of BUILTIN_TASKS)
+            this.register(def);
+        for (const def of extra)
+            this.register(def);
+    }
+    /** Register (or override by id) a task definition and index its aliases. */
+    register(def) {
+        this.byId.set(def.id, def);
+        this.aliasToId.set(def.id, def.id);
+        for (const alias of def.aliases ?? [])
+            this.aliasToId.set(alias, def.id);
+    }
+    /** Look up a task by id or alias. Returns undefined for an unknown task (caller infers). */
+    lookup(nameOrAlias) {
+        const id = this.aliasToId.get(nameOrAlias);
+        return id ? this.byId.get(id) : undefined;
+    }
+    list() {
+        return [...this.byId.values()];
+    }
+}

package/dist/core/router/confidence.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Confidence derivation. Blends the winning score with how well-evidenced the selected model's
+ * required capabilities are and how confident normalization was about the task. Monotonic: a higher
+ * score, better evidence, or a known (vs inferred) task each raises confidence.
+ */
+import type { ModelMetadata, NormalizedTask } from '../../types.js';
+export declare function deriveConfidence(topScore: number, model: ModelMetadata, task: NormalizedTask): number;

package/dist/core/router/confidence.js

@@ -0,0 +1,20 @@
+/**
+ * Confidence derivation. Blends the winning score with how well-evidenced the selected model's
+ * required capabilities are and how confident normalization was about the task. Monotonic: a higher
+ * score, better evidence, or a known (vs inferred) task each raises confidence.
+ */
+import { capabilitySatisfies, getCapability, rankOf } from '../capabilities/evidence.js';
+const clamp01 = (n) => (n < 0 ? 0 : n > 1 ? 1 : n);
+export function deriveConfidence(topScore, model, task) {
+    let evFactor = 1;
+    if (task.required.length > 0) {
+        const sum = task.required.reduce((acc, r) => {
+            if (!capabilitySatisfies(model.capabilities, r))
+                return acc; // pinned/unknown-capability model: penalize
+            const cap = getCapability(model.capabilities, r.group, r.key);
+            return acc + rankOf(cap.evidence) / 4;
+        }, 0);
+        evFactor = sum / task.required.length;
+    }
+    return clamp01(topScore * (0.5 + 0.5 * evFactor) * task.confidence);
+}

package/dist/core/router/dimensions.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Per-dimension scoring functions, each returning 0..1. They read ONLY normalized ModelMetadata
+ * (capabilities resolved by the provider, quality/reliability/latency/pricing threaded on upstream),
+ * so `core/scoring` never imports vendor data. `historicalSuccess` is a static placeholder here and
+ * is wired to telemetry in a later stage.
+ */
+import type { ModelMetadata, NormalizedTask } from '../../types.js';
+import type { ObservedPerf } from '../../learning/performanceStore.js';
+/** How well the model meets required capabilities (evidence-weighted) plus a preferred-coverage bonus. */
+export declare function capabilityFit(model: ModelMetadata, task: NormalizedTask): number;
+export declare function quality(model: ModelMetadata): number;
+export declare function reliability(model: ModelMetadata): number;
+export declare function historicalSuccess(model: ModelMetadata, observed?: ObservedPerf): number;
+export declare function latency(model: ModelMetadata, observed?: ObservedPerf): number;
+export declare function cost(model: ModelMetadata): number;
+export declare function userPreference(_model: ModelMetadata, preference?: number): number;

package/dist/core/router/dimensions.js

@@ -0,0 +1,60 @@
+/**
+ * Per-dimension scoring functions, each returning 0..1. They read ONLY normalized ModelMetadata
+ * (capabilities resolved by the provider, quality/reliability/latency/pricing threaded on upstream),
+ * so `core/scoring` never imports vendor data. `historicalSuccess` is a static placeholder here and
+ * is wired to telemetry in a later stage.
+ */
+import { rankOf } from '../capabilities/evidence.js';
+import { capabilitySatisfies, getCapability } from '../capabilities/evidence.js';
+const clamp01 = (n) => (n < 0 ? 0 : n > 1 ? 1 : n);
+const TIER_SCORE = { frontier: 1, strong: 0.8, mid: 0.6, small: 0.4 };
+/** How well the model meets required capabilities (evidence-weighted) plus a preferred-coverage bonus. */
+export function capabilityFit(model, task) {
+    const evFactor = (key, group) => {
+        const cap = getCapability(model.capabilities, group, key);
+        return cap.value ? rankOf(cap.evidence) / 4 : 0;
+    };
+    const requiredScore = task.required.length === 0
+        ? 1
+        : task.required.reduce((acc, r) => acc + (capabilitySatisfies(model.capabilities, r) ? evFactor(r.key, r.group) : 0), 0) /
+            task.required.length;
+    if (task.preferred.length === 0)
+        return clamp01(requiredScore);
+    const preferredScore = task.preferred.filter((r) => capabilitySatisfies(model.capabilities, r)).length / task.preferred.length;
+    return clamp01(0.8 * requiredScore + 0.2 * preferredScore);
+}
+export function quality(model) {
+    if (model.quality?.score !== undefined)
+        return clamp01(model.quality.score);
+    if (model.quality?.tier)
+        return TIER_SCORE[model.quality.tier];
+    return 0.5;
+}
+export function reliability(model) {
+    return clamp01(model.reliability?.successRate ?? 0.85);
+}
+export function historicalSuccess(model, observed) {
+    // Prefer OBSERVED success rate once we have enough samples; else declared reliability.
+    if (observed)
+        return clamp01(observed.successRate);
+    return clamp01(model.reliability?.successRate ?? 0.8);
+}
+export function latency(model, observed) {
+    // Prefer OBSERVED latency once learned; else the catalog's p50.
+    const p50 = observed?.avgLatencyMs ?? model.latency?.p50Ms;
+    if (p50 === undefined)
+        return 0.5;
+    return clamp01(1 / (1 + p50 / 2000));
+}
+export function cost(model) {
+    const p = model.pricing;
+    if (!p)
+        return 1; // local / unpriced treated as cheapest
+    const sum = (p.inputPerMTok ?? 0) + (p.outputPerMTok ?? 0);
+    if (sum === 0)
+        return 1;
+    return clamp01(1 / (1 + sum));
+}
+export function userPreference(_model, preference) {
+    return clamp01(preference ?? 0.5);
+}

package/dist/core/router/executor.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Phase 5 — single-attempt execution. Calls the provider through the contract and normalizes ANY
+ * thrown value into an AIError carrying the provider/model, so the fallback controller never sees a
+ * raw vendor error.
+ */
+import type { AIProvider } from '../../providers/provider.js';
+import type { AIRequest, AIResponse } from '../../types.js';
+import { AIError } from '../fallback/errors.js';
+export type ExecOutcome = {
+    ok: true;
+    response: AIResponse;
+} | {
+    ok: false;
+    error: AIError;
+};
+export declare function executeOnce(provider: AIProvider, request: AIRequest): Promise<ExecOutcome>;

package/dist/core/router/executor.js

@@ -0,0 +1,25 @@
+/**
+ * Phase 5 — single-attempt execution. Calls the provider through the contract and normalizes ANY
+ * thrown value into an AIError carrying the provider/model, so the fallback controller never sees a
+ * raw vendor error.
+ */
+import { AIError, toAIError } from '../fallback/errors.js';
+export async function executeOnce(provider, request) {
+    try {
+        const response = await provider.execute(request);
+        return { ok: true, response };
+    }
+    catch (e) {
+        const base = toAIError(e);
+        const error = base.providerId
+            ? base
+            : new AIError(base.message, {
+                category: base.category,
+                status: base.status,
+                retryable: base.retryable,
+                providerId: provider.id,
+                model: request.model,
+            });
+        return { ok: false, error };
+    }
+}

package/dist/core/router/filter.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Phase 2 — filter. Excludes candidates that cannot or must not serve the task, recording a concrete
+ * reason for each so a zero-eligible outcome yields an actionable NO_CAPABLE_PROVIDER. Order matters
+ * only for which reason is reported first; every exclusion is a hard gate:
+ *   deny/allow → pin → capability (relaxed when pinned) → context window → privacy → hard cost/latency.
+ *
+ * PRIVACY is enforced here UNCONDITIONALLY — even a pinned/provider-specific request passes through
+ * it, so high-sensitivity input can never reach a cloud provider without an explicit allowance.
+ */
+import type { AIProvider } from '../../providers/provider.js';
+import type { Candidate, ExclusionReason, NormalizedTask, RunRequest } from '../../types.js';
+import type { ResolvedConfig } from '../../config/defaults.js';
+import type { HealthMonitor } from '../health/monitor.js';
+import type { RequestTemplate } from './normalize.js';
+export interface FilterInput {
+    candidates: Candidate[];
+    task: NormalizedTask;
+    config: ResolvedConfig;
+    template: RequestTemplate;
+    getProvider: (id: string) => AIProvider | undefined;
+    pin: {
+        provider?: string;
+        model?: string;
+    };
+    constraints?: RunRequest['constraints'];
+    /** User exclude routing (a hard filter, recorded in the trace — never overridden by learning). */
+    routing?: RunRequest['routing'];
+    health?: HealthMonitor;
+}
+export interface FilterResult {
+    eligible: Candidate[];
+    filteredOut: ExclusionReason[];
+}
+export declare function filterCandidates(input: FilterInput): Promise<FilterResult>;

package/dist/core/router/filter.js

@@ -0,0 +1,113 @@
+/**
+ * Phase 2 — filter. Excludes candidates that cannot or must not serve the task, recording a concrete
+ * reason for each so a zero-eligible outcome yields an actionable NO_CAPABLE_PROVIDER. Order matters
+ * only for which reason is reported first; every exclusion is a hard gate:
+ *   deny/allow → pin → capability (relaxed when pinned) → context window → privacy → hard cost/latency.
+ *
+ * PRIVACY is enforced here UNCONDITIONALLY — even a pinned/provider-specific request passes through
+ * it, so high-sensitivity input can never reach a cloud provider without an explicit allowance.
+ */
+import { capabilitySatisfies } from '../capabilities/evidence.js';
+import { buildRequest } from './request.js';
+import { isExcluded } from './routingPrefs.js';
+function privacyFloor(task, p) {
+    let floor = task.requireLocal || task.strategy === 'local-only' || !p.allowCloud;
+    if (task.sensitivity === 'high' && !p.sensitiveDataAllowedOnCloud)
+        floor = true;
+    if (task.sensitivity === 'unknown' && p.treatUnknownAsSensitive && !p.sensitiveDataAllowedOnCloud)
+        floor = true;
+    return floor;
+}
+export async function filterCandidates(input) {
+    const { candidates, task, config, pin, constraints } = input;
+    const eligible = [];
+    const filteredOut = [];
+    const pinned = Boolean(pin.provider);
+    const requireLocal = privacyFloor(task, config.privacy);
+    const wantCostLatency = constraints?.maxCostUsd !== undefined || constraints?.maxLatencyMs !== undefined;
+    for (const candidate of candidates) {
+        const provider = input.getProvider(candidate.providerId);
+        const modelId = candidate.model.id;
+        const exclude = (reason) => {
+            filteredOut.push({ providerId: candidate.providerId, model: modelId, reason });
+        };
+        if (!provider) {
+            exclude('provider not registered');
+            continue;
+        }
+        // health / cooldown
+        if (input.health && !input.health.routable(candidate.providerId)) {
+            const state = input.health.get(candidate.providerId)?.state ?? 'UNKNOWN';
+            exclude(`provider not routable (health=${state})`);
+            continue;
+        }
+        // user exclude routing (a HARD filter — but the candidate stays visible in the trace, and learning
+        // can never re-admit it). Checked before pin so it applies even to a pinned provider.
+        if (isExcluded(input.routing, candidate.providerId, modelId)) {
+            exclude(`⊘ excluded by user configuration`);
+            continue;
+        }
+        // deny / allow lists
+        if (constraints?.denyProviders?.includes(candidate.providerId)) {
+            exclude(`excluded by denyProviders`);
+            continue;
+        }
+        if (constraints?.allowProviders && !constraints.allowProviders.includes(candidate.providerId)) {
+            exclude(`not in allowProviders`);
+            continue;
+        }
+        // pin
+        if (pin.provider && candidate.providerId !== pin.provider) {
+            exclude(`not the pinned provider '${pin.provider}'`);
+            continue;
+        }
+        if (pin.model && modelId !== pin.model) {
+            exclude(`not the pinned model '${pin.model}'`);
+            continue;
+        }
+        // capability — relaxed when the caller pinned a provider (route on their assertion)
+        if (!pinned) {
+            const unmet = task.required.find((r) => !capabilitySatisfies(candidate.model.capabilities, r));
+            if (unmet) {
+                exclude(`missing required capability ${unmet.group}.${unmet.key}`);
+                continue;
+            }
+        }
+        // context window
+        if (task.minContextWindow !== undefined && candidate.model.contextWindow !== undefined && candidate.model.contextWindow < task.minContextWindow) {
+            exclude(`context window ${candidate.model.contextWindow} < required ${task.minContextWindow}`);
+            continue;
+        }
+        // privacy (unconditional)
+        if (requireLocal && provider.privacyClass !== 'local') {
+            exclude(`privacy: high/undeclared sensitivity may not use cloud provider (privacyClass=${provider.privacyClass})`);
+            continue;
+        }
+        if (task.strategy === 'cloud-only' && provider.privacyClass !== 'cloud') {
+            exclude(`strategy cloud-only excludes local provider`);
+            continue;
+        }
+        if (!config.privacy.allowLocal && provider.privacyClass === 'local') {
+            exclude(`local providers disabled by policy`);
+            continue;
+        }
+        // hard cost / latency constraints
+        if (wantCostLatency) {
+            const estimate = await provider.estimate(buildRequest(input.template, modelId));
+            if (constraints?.maxCostUsd !== undefined && estimate.estCost && estimate.estCost.amount > constraints.maxCostUsd) {
+                exclude(`estimated cost ${estimate.estCost.amount} > maxCostUsd ${constraints.maxCostUsd}`);
+                continue;
+            }
+            if (constraints?.maxLatencyMs !== undefined && estimate.estLatencyMs?.p50 !== undefined && estimate.estLatencyMs.p50 > constraints.maxLatencyMs) {
+                exclude(`estimated latency ${estimate.estLatencyMs.p50}ms > maxLatencyMs ${constraints.maxLatencyMs}`);
+                continue;
+            }
+            if (!estimate.contextFits) {
+                exclude(`input does not fit model context window`);
+                continue;
+            }
+        }
+        eligible.push(candidate);
+    }
+    return { eligible, filteredOut };
+}

package/dist/core/router/normalize.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Phase 1 — task normalization. Turns a public `RunRequest` + the task registry into a
+ * `NormalizedTask` (required/preferred capabilities, strategy, sensitivity) plus a provider-agnostic
+ * request template that the executor completes with a chosen model. An UNKNOWN task never fails: its
+ * requirements are inferred from the request's own hints and its confidence is stamped low.
+ */
+import type { AIRequest, InputPart, NormalizedTask, OutputFormat, RunRequest, Sensitivity, ToolSpec } from '../../types.js';
+import type { ResolvedConfig } from '../../config/defaults.js';
+import type { TaskRegistry } from '../registry/taskRegistry.js';
+export interface RequestTemplate {
+    taskId: string;
+    input: {
+        text?: string;
+        parts?: InputPart[];
+    };
+    system?: string;
+    output?: {
+        format: OutputFormat;
+        schema?: unknown;
+    };
+    tools?: ToolSpec[];
+    params?: AIRequest['params'];
+    timeoutMs: number;
+    sensitivity: Sensitivity;
+}
+export interface NormalizeResult {
+    task: NormalizedTask;
+    template: RequestTemplate;
+}
+export declare function normalize(req: RunRequest, tasks: TaskRegistry, config: ResolvedConfig): NormalizeResult;