ai-runtime-engine 3.0.0 → 3.0.1

package/CHANGELOG.md

@@ -5,6 +5,68 @@ All notable changes to `ai-runtime` are documented here. The format follows
 Versioning](https://semver.org/). Development history and rationale live in
 [docs/DECISIONS.md](docs/DECISIONS.md) and [docs/PROGRESS.md](docs/PROGRESS.md).
 
+## [3.0.1] — 2026-09-07
+
+**Hardening pass.** A correctness, security, test, documentation, and release-cleanup pass over a
+full-repo audit of 3.0. The architecture is unchanged — every change extends an existing seam and is
+backward compatible (with one documented downgrade caveat on the encryption format). The test suite grew
+from 892 to 971 and CI now runs a Node 22 + 24 matrix with a tarball-contents audit, a doc-link/anchor
+check, and a fail-closed test-count integrity floor.
+
+### Security
+
+- **Shell tool: eval-capable invocations now require approval, even when allowlisted.** Allowlisting a
+  binary like `npm` or `node` no longer silently permits arbitrary code through its arguments —
+  interpreters run with inline-code/preload flags (`node -e`/`-r`, `python -c/-m`, `perl -M`, the `awk`
+  family, …), package/script runners (`npx`, `npm exec`/`run`/`init`, `deno task`, …), container
+  `run`/`exec`, argv-indirection wrappers (`env`, `xargs`, `nice`, `timeout`, `find -exec`, …), and a
+  non-default `make -f` are escalated to interactive approval (headless runs fail closed). The allowlist
+  matches an absolute path by basename but never a relative or workspace-internal one (realpath-checked).
+  This backstop is best-effort; `docs/security.md` documents its limits and accepted residuals.
+- **Store files are created owner-only** (`0600` files, `0700` directories) on POSIX.
+- **Encryption at rest v2:** the AES-256-GCM key is now derived with **scrypt** over a per-record salt
+  (the `aienc2` envelope) instead of a bare SHA-256, so a passphrase key resists brute force. Legacy
+  `aienc1` and plaintext records still read and upgrade on rewrite. A decryption failure is a typed
+  `StoreDecryptError` — honestly "wrong key OR tampering OR corruption" — and now surfaces instead of
+  reading as a silently empty store. *Downgrade caveat: a pre-3.0.1 runtime cannot read `aienc2` records.*
+- Untrusted-content fencing neutralizes any fence label (not just its own); the verifier's model-authored
+  `reason` is flattened/clamped and its prompt inputs are fenced; the MCP schema sanitizer uses a
+  null-prototype object so a `__proto__` key cannot pollute.
+
+### Fixed
+
+- **Config schema accepted four documented keys it used to reject.** `parseConfig` (the public export) now
+  accepts `learning`, `verification`, `budget`, and `policy` at the root; before this a config using any of
+  them failed to load.
+- **Routing now always enforces context-fit**, not only when a cost/latency constraint is set; and
+  cost/context **estimates account for multimodal input parts** (an image is no longer estimated as zero).
+- **`models: 'auto'`** resolves deterministically offline (defaultModel → kind catalog); a zero-model
+  result is a loud CONFIG error, not a silently unroutable provider.
+- **Streaming fallback no longer garbles output**: a failed streamed attempt is explicitly abandoned via a
+  new `response.stream_abandoned` runtime event, and `response.streamed` is accurate under fallback.
+- **OTLP telemetry is flushed on close**, so short-lived runs no longer drop sub-batch events.
+- **Store lock** stale-steal is atomic (ownership token); **conversation metadata** writes serialize
+  through it; the **HTTP client** no longer sleeps out a backoff after the final retry; a stale provider
+  **cooldown** now reads as routable again; provider `listModels()`/`discover()` return copies.
+- **CLI `--json --yes`** on `cleanup` and `skills --scaffold` now applies the operation and reports the
+  result, instead of printing a preview and ignoring `--yes`. `ai-runtime mcp show <id>` was added.
+
+### Changed
+
+- **The four validated-but-ignored config fields are now enforced:** `ProviderConfig.weightOverrides`
+  (per-provider score weights; keys restricted to the scoring dimensions), `TaskDefinition.qualityFloor`
+  (excludes lower-tier models; a model with no tier is not excluded), `CapabilityRequirement.weight`
+  (weights capability fit and confidence alike), and `constraints.minimumConfidence` (raises the effective
+  confidence floor; it flags, it does not fail the run).
+- **The memory tokenizer is Unicode-aware** — accented Latin, Cyrillic, Arabic, and CJK are now
+  searchable; pure-ASCII tokenization is byte-identical. *Note: learned goal keys for non-ASCII goals
+  re-key (old degenerate records are orphaned, never mixed); session-cached embedding vectors shift.*
+
+### Notes for consumers
+
+- The `RuntimeEvent` union gained a `response.stream_abandoned` arm. New arms are additive at runtime but
+  break an exhaustive `switch` at compile time — carry a default case.
+
 ## [3.0.0] — 2026-09-05
 
 **AI Runtime 3.0.** The 3.x arc set out to make the runtime reason about *what it can do*, talk to tools
@@ -841,6 +903,7 @@ Initial release: the provider-agnostic AI **router** — capability-based routin
 scoring, evidence validation, fallback, health tracking, learning-based scoring, multi-model verification,
 budgets, MCP tools, OpenAPI-based adapter generation, and the `AI` class + CLI.
 
+[3.0.1]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v3.0.1
 [3.0.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v3.0.0
 [2.9.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v2.9.0
 [2.8.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v2.8.0

package/dist/cli/cli.js

@@ -21,7 +21,7 @@ import { mcpCommand, mcpAddCommand, mcpRemoveCommand, mcpEnableCommand, mcpTestC
 import { startRepl } from './interactive/repl.js';
 import { printError } from './render.js';
 const program = new Command();
-program.name('ai-runtime').description('Universal, provider-agnostic AI Runtime & Orchestration Platform').version('3.0.0');
+program.name('ai-runtime').description('Universal, provider-agnostic AI Runtime & Orchestration Platform').version('3.0.1');
 const configOpt = ['-c, --config <path>', 'path to an ai-runtime config file'];
 // Bare `ai-runtime` (no subcommand) opens the interactive terminal. `allowExcessArguments(false)` keeps
 // a mistyped subcommand (e.g. `ai-runtime porviders`) failing fast instead of silently opening the REPL.
@@ -77,6 +77,13 @@ mcp
     .option(...configOpt)
     .option('--json', 'print as JSON')
     .action((id, o) => mcpCommand(id, o));
+mcp
+    .command('show')
+    .argument('<id>', 'server id')
+    .description('Show one server in detail — the unambiguous form for an id that collides with a subcommand name (add/remove/enable/disable/test)')
+    .option(...configOpt)
+    .option('--json', 'print as JSON')
+    .action((id, o) => mcpCommand(id, o));
 mcp
     .command('add')
     .argument('<id>', 'a short id for the server (lowercase, kebab/snake)')

package/dist/cli/commands/cleanup.js

@@ -74,11 +74,19 @@ export async function cleanupCommand(opts) {
             return;
         }
         const plan = planCleanup(rt, Date.now());
-        if (opts.json)
-            return print(JSON.stringify(plan, null, 2));
+        const removable = toRemove(plan);
+        // `--json` changes the OUTPUT FORMAT only; it does not suppress `--yes`. Without `--yes` (or with
+        // `--dry-run`) it emits a plan preview; with `--yes` it applies and reports the result. It never
+        // prompts (machine-facing). The JSON always carries `mode` so a caller can tell plan from applied.
+        if (opts.json) {
+            if (opts.yes && !opts.dryRun && removable > 0) {
+                const applied = applyCleanup(rt, plan);
+                return print(JSON.stringify({ mode: 'applied', plan, applied }, null, 2));
+            }
+            return print(JSON.stringify({ mode: 'plan', plan }, null, 2));
+        }
         for (const line of renderPlan(plan))
             print(line);
-        const removable = toRemove(plan);
         if (removable === 0) {
             print('\nNothing to remove.');
             return;

package/dist/cli/commands/doctor.js

@@ -75,7 +75,7 @@ export function renderDoctor(r) {
     if (!r.providers.length)
         lines.push('  (none configured — run `ai-runtime setup`)');
     for (const p of r.providers)
-        lines.push(`  ${p.authenticated ? '✓' : '✗'} ${p.id.padEnd(14)} ${p.authenticated ? 'authenticated' : 'not configured'}  [${p.state}]  ${p.models} models`);
+        lines.push(`  ${p.authenticated ? '✓' : '✗'} ${p.id.padEnd(14)} ${p.authenticated ? 'authenticated' : 'not configured'}  [${p.state}]  ${p.models} models${p.models === 0 ? '  ⚠ no routable models — list models explicitly or set defaultModel' : ''}`);
     lines.push(`Models:   ${r.models.total} known, ${r.models.usableProviders} provider(s) usable`);
     lines.push('', 'Store:');
     if (!r.store.enabled)

package/dist/cli/commands/run.js

@@ -32,6 +32,12 @@ async function runWith(rt, input, options) {
                 printChunk(e.text);
                 streamedAny = true;
             }
+            else if (e.type === 'response.stream_abandoned') {
+                // Mark a boundary so the discarded partial is not read as part of what follows. Do not promise a
+                // retry — abandonment also fires when the failed attempt was the last candidate.
+                printChunk('\n↩ discarded incomplete response\n');
+                streamedAny = false;
+            }
         });
     }
     if (options.mode) {

package/dist/cli/commands/skills.js

@@ -51,8 +51,15 @@ export async function skillsCommand(opts) {
                     return print(JSON.stringify({ ok: false, error: draft.error }, null, 2));
                 return print(`Could not scaffold a skill: ${draft.error}`);
             }
-            if (opts.json)
-                return print(JSON.stringify({ ok: true, manifest: draft.manifest, yaml: draft.yaml }, null, 2));
+            // `--json` changes the OUTPUT FORMAT only; with `--yes` it SAVES and reports the path, without it
+            // returns the draft. It never prompts (machine-facing). `mode` distinguishes draft from saved.
+            if (opts.json) {
+                if (opts.yes) {
+                    const savedPath = rt.saveScaffoldedSkill(draft.manifest);
+                    return print(JSON.stringify({ ok: true, mode: 'saved', path: savedPath, manifest: draft.manifest }, null, 2));
+                }
+                return print(JSON.stringify({ ok: true, mode: 'draft', manifest: draft.manifest, yaml: draft.yaml }, null, 2));
+            }
             print(`Drafted skill "${draft.manifest.id}":\n`);
             print(draft.yaml);
             const proceed = opts.yes || (await confirm(`Save to .ai-runtime/skills/${draft.manifest.id}.skill.yaml?`));

package/dist/cli/interactive/repl.js

@@ -88,8 +88,10 @@ export async function startRepl(configPath) {
         if (!line.trim())
             return;
         try {
-            mkdirSync(dirname(historyPath), { recursive: true });
-            appendFileSync(historyPath, `${line}\n`);
+            // Owner-only: history holds raw prompt lines under the store home (0700 dir / 0600 file, matching
+            // the store's own record hardening). Mode applies only on creation; POSIX-only, a no-op on Windows.
+            mkdirSync(dirname(historyPath), { recursive: true, mode: 0o700 });
+            appendFileSync(historyPath, `${line}\n`, { mode: 0o600 });
         }
         catch {
             /* history is a convenience; a write failure must never break the REPL */
@@ -121,6 +123,14 @@ export async function startRepl(configPath) {
             streamedThisRun = true;
             return;
         }
+        if (e.type === 'response.stream_abandoned') {
+            // The partial answer just streamed from this provider is being discarded; mark a clear boundary so
+            // whatever follows is not read as a seamless continuation of it. Not necessarily a retry — this also
+            // fires when the failed attempt was the last candidate.
+            printChunk('\n↩ discarded incomplete response\n');
+            streamedThisRun = false;
+            return;
+        }
         const lane = lanes.observe(e);
         if (lane) {
             if (!runInFlight)

package/dist/cli/interactive/session.d.ts

@@ -22,8 +22,10 @@ export declare class ReplSession {
     private conversationId?;
     private dryRunMode;
     private streaming;
+    private readonly env;
     constructor(runtime: Runtime, opts?: {
         streaming?: boolean;
+        env?: NodeJS.ProcessEnv;
     });
     currentMode(): RuntimeMode;
     private views;

package/dist/cli/interactive/session.js

@@ -76,9 +76,13 @@ export class ReplSession {
     conversationId;
     dryRunMode = false;
     streaming;
+    env;
     constructor(runtime, opts = {}) {
         this.runtime = runtime;
         this.streaming = opts.streaming ?? false;
+        // The env the /budget display reads. Injectable so tests need not mutate the real process.env; the
+        // enforcement path already resolves budgets from the runtime's injected env.
+        this.env = opts.env ?? process.env;
     }
     currentMode() {
         return this.mode;
@@ -202,8 +206,8 @@ export class ReplSession {
             case 'budget':
                 return {
                     lines: [
-                        `call budget (AI_MAX_CALLS):    ${process.env.AI_MAX_CALLS ?? '(unset — no limit)'}`,
-                        `cost budget (AI_MAX_COST_USD): ${process.env.AI_MAX_COST_USD ?? '(unset — no limit)'}`,
+                        `call budget (AI_MAX_CALLS):    ${this.env.AI_MAX_CALLS ?? '(unset — no limit)'}`,
+                        `cost budget (AI_MAX_COST_USD): ${this.env.AI_MAX_COST_USD ?? '(unset — no limit)'}`,
                         'over budget: notify-and-wait by default; add --partial (one-shot) to run the phases that fit and pause.',
                     ],
                 };

package/dist/config/schema.js

@@ -11,6 +11,8 @@ const EVIDENCE = ['unsupported', 'unknown', 'inferred', 'documented', 'verified'
 const GROUPS = ['input', 'output', 'intelligence', 'agent'];
 const KINDS = ['openai-compatible', 'gemini', 'groq', 'anthropic', 'ollama', 'custom', 'mock'];
 export const KEY_LIKE = /^(sk-|gsk_|Bearer\s|[A-Za-z0-9_-]{40,}$)/;
+/** The seven scoring-weight dimensions. A `weightOverrides` block may only name these keys. */
+const SCORE_WEIGHT_KEYS = ['capabilityFit', 'quality', 'reliability', 'historicalSuccess', 'latency', 'cost', 'userPreference'];
 const capabilityRequirement = z.object({
     group: z.enum(GROUPS),
     key: z.string().min(1),
@@ -50,10 +52,22 @@ const providerConfig = z
     privacyClass: z.enum(['local', 'cloud']).optional(),
     wireShape: z.enum(['openai', 'anthropic']).optional(),
     headers: z.record(z.string()).optional(),
-    weightOverrides: z.record(z.number()).optional(),
+    weightOverrides: z.record(z.enum(SCORE_WEIGHT_KEYS), z.number()).optional(),
 })
     .strict()
     .refine((p) => !(['openai-compatible', 'custom'].includes(p.kind) && !p.baseUrl), { message: 'openai-compatible/custom providers require a baseUrl' });
+/**
+ * The four router-level blocks that Runtime settings also accept. Defined once here — the single source
+ * of truth used by `routerConfig` below — so `parseConfig` (the public export) accepts them. Before 3.0.1
+ * the root schema rejected them and they were only tolerated via parseRuntimeConfig's fold-back; that
+ * fold-back is gone, and the runtime-config layer now receives them transitively through parseConfig.
+ */
+const learningConfig = z.object({ enabled: z.boolean().optional() }).strict();
+const verificationConfig = z.object({ enabled: z.boolean().optional() }).strict();
+const budgetConfig = z.object({ maxCostUsd: z.number().optional(), maxCalls: z.number().optional() }).strict();
+const policyConfig = z
+    .object({ allowProviders: z.array(z.string()).optional(), denyProviders: z.array(z.string()).optional(), requireLocal: z.boolean().optional(), maxCostUsd: z.number().optional(), strategy: z.enum(STRATEGIES).optional() })
+    .strict();
 const routerConfig = z
     .object({
     providers: z.array(providerConfig),
@@ -65,6 +79,10 @@ const routerConfig = z
         .strict()
         .optional(),
     telemetry: z.object({ enabled: z.boolean().optional(), sink: z.enum(['memory', 'file', 'otlp']).optional(), storePrompts: z.literal(false).optional(), path: z.string().optional(), endpoint: z.string().optional(), headersEnv: z.string().refine((v) => v === undefined || !KEY_LIKE.test(v), { message: 'headersEnv must be an env-var NAME, not a header/token value' }).optional() }).strict().optional(),
+    learning: learningConfig.optional(),
+    verification: verificationConfig.optional(),
+    budget: budgetConfig.optional(),
+    policy: policyConfig.optional(),
     tasks: z.array(taskDefinition).optional(),
 })
     .strict();

package/dist/conversations/conversations.d.ts

@@ -20,11 +20,16 @@ export interface ConversationMeta {
     updatedAt: number;
     turns: number;
 }
+/** Serializes a critical section. Injected from the RuntimeStore's advisory lock; defaults to a no-op. */
+export type WithLock = <T>(fn: () => T) => T;
 export declare class ConversationStore {
     private readonly area;
     private readonly clock;
+    private readonly withLock;
     private counter;
-    constructor(area: Area, clock?: Clock);
+    constructor(area: Area, clock?: Clock, opts?: {
+        withLock?: WithLock;
+    });
     get enabled(): boolean;
     /** Start a conversation; returns its id. */
     start(id?: string): string;

package/dist/conversations/conversations.js

@@ -16,10 +16,13 @@ function deriveTitle(text) {
 export class ConversationStore {
     area;
     clock;
+    withLock;
     counter = 0;
-    constructor(area, clock = systemClock) {
+    constructor(area, clock = systemClock, opts = {}) {
         this.area = area;
         this.clock = clock;
+        // Default is a plain pass-through, so a ConversationStore built without a lock behaves exactly as before.
+        this.withLock = opts.withLock ?? ((fn) => fn());
     }
     get enabled() {
         return this.area.enabled;
@@ -36,13 +39,17 @@ export class ConversationStore {
     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);
+        this.area.appendLine(id, turn); // JSONL append is atomic on its own
+        // Serialize the meta read-modify-write: two concurrent appends must not both read the same turn count
+        // and each write back turns+1 (losing one). The JSONL lines above are safe either way.
+        this.withLock(() => {
+            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);

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

@@ -23,6 +23,13 @@ export interface FallbackInput {
     /** Phase-13 streaming: forwarded to each attempt's `executeOnce`; deltas ride this callback, the final
      *  aggregate rides the return value. Only meaningful when `template.stream` is set. */
     onDelta?: (chunk: string) => void;
+    /** Fired when an attempt that already emitted deltas fails (or is dropped by validation) and fallback
+     *  moves on: the partial stream just sent must be discarded, since the next attempt streams anew. This
+     *  keeps the live stream honest — provider B's answer is never a seamless continuation of provider A's. */
+    onStreamAbandoned?: (info: {
+        providerId: string;
+        model: string;
+    }) => 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. */

package/dist/core/fallback/fallback.js

@@ -34,9 +34,18 @@ export async function runWithFallback(input) {
         tried += 1;
         const started = clock.now();
         const request = buildRequest(input.template, model.id, input.signal);
+        // Wrap onDelta per attempt so we know whether THIS attempt streamed anything. If it did and the
+        // attempt then fails or is dropped, we signal abandonment so the consumer discards the partial.
+        let sawDelta = false;
+        const onDelta = input.onDelta
+            ? (chunk) => {
+                sawDelta = true;
+                input.onDelta(chunk);
+            }
+            : undefined;
         const outcome = input.providerLimiter
-            ? await input.providerLimiter.run(providerId, () => executeOnce(provider, request, input.onDelta))
-            : await executeOnce(provider, request, input.onDelta);
+            ? await input.providerLimiter.run(providerId, () => executeOnce(provider, request, onDelta))
+            : await executeOnce(provider, request, onDelta);
         const latencyMs = clock.now() - started;
         input.budget?.recordCall(estCost);
         if (outcome.ok) {
@@ -47,6 +56,8 @@ export async function runWithFallback(input) {
                 const record = { providerId, model: model.id, outcome: 'non-retryable', category: 'RESPONSE_VALIDATION', latencyMs };
                 attempts.push(record);
                 input.onAttempt?.(record);
+                if (sawDelta)
+                    input.onStreamAbandoned?.({ providerId, model: model.id });
                 lastError = new AIError(`response failed validation: ${why}`, { category: 'RESPONSE_VALIDATION', retryable: false, providerId, model: model.id });
                 continue;
             }
@@ -63,6 +74,8 @@ export async function runWithFallback(input) {
         };
         attempts.push(record);
         input.onAttempt?.(record);
+        if (sawDelta)
+            input.onStreamAbandoned?.({ providerId, model: model.id });
         lastError = outcome.error;
         if (record.outcome === 'non-retryable')
             poisoned.add(providerId);

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

@@ -15,6 +15,12 @@ export declare class HealthMonitor {
     constructor(telemetry?: TelemetrySink | undefined, clock?: Clock, cooldownMs?: number);
     get(providerId: string): HealthStatus | undefined;
     all(): HealthStatus[];
+    /**
+     * Recompute liveness on READ so an inspector (doctor/status) agrees with what `routable()` — and thus
+     * the router — will actually do: once a cooldown has elapsed the provider reads as routable again with
+     * the stale `cooldownUntil` cleared, instead of showing a long-expired cooldown as still down.
+     */
+    private withLiveness;
     /** Optimistic: an unseen provider is routable; a cooled-down one becomes routable again once elapsed. */
     routable(providerId: string): boolean;
     seed(status: HealthStatus): void;

package/dist/core/health/monitor.js

@@ -38,10 +38,23 @@ export class HealthMonitor {
         this.clock = clock;
     }
     get(providerId) {
-        return this.state.get(providerId);
+        const s = this.state.get(providerId);
+        return s ? this.withLiveness(s) : undefined;
     }
     all() {
-        return [...this.state.values()];
+        return [...this.state.values()].map((s) => this.withLiveness(s));
+    }
+    /**
+     * Recompute liveness on READ so an inspector (doctor/status) agrees with what `routable()` — and thus
+     * the router — will actually do: once a cooldown has elapsed the provider reads as routable again with
+     * the stale `cooldownUntil` cleared, instead of showing a long-expired cooldown as still down.
+     */
+    withLiveness(s) {
+        if (s.cooldownUntil !== undefined && this.clock.now() >= s.cooldownUntil) {
+            const { cooldownUntil: _elapsed, ...rest } = s;
+            return { ...rest, routable: true };
+        }
+        return s;
     }
     /** Optimistic: an unseen provider is routable; a cooled-down one becomes routable again once elapsed. */
     routable(providerId) {

package/dist/core/router/confidence.js

@@ -8,13 +8,18 @@ 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) => {
+        // Same per-requirement weighting (weight ?? 1) as capabilityFit, so fit and confidence stay consistent.
+        let wsum = 0;
+        let sum = 0;
+        for (const r of task.required) {
+            const w = r.weight ?? 1;
+            wsum += w;
             if (!capabilitySatisfies(model.capabilities, r))
-                return acc; // pinned/unknown-capability model: penalize
+                continue; // 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;
+            sum += w * (rankOf(cap.evidence) / 4);
+        }
+        evFactor = wsum > 0 ? sum / wsum : 1;
     }
     return clamp01(topScore * (0.5 + 0.5 * evFactor) * task.confidence);
 }

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

@@ -4,8 +4,10 @@
  * 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 { ModelMetadata, NormalizedTask, QualityTier } from '../../types.js';
 import type { ObservedPerf } from '../../learning/performanceStore.js';
+/** Quality-tier ordering, exported so the filter can enforce a task's qualityFloor with the same scale. */
+export declare const TIER_SCORE: Record<QualityTier, number>;
 /** 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;

package/dist/core/router/dimensions.js

@@ -7,17 +7,27 @@
 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 };
+/** Quality-tier ordering, exported so the filter can enforce a task's qualityFloor with the same scale. */
+export 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;
+    // Per-requirement weighting (CapabilityRequirement.weight, default 1): a requirement's contribution to
+    // the mean is proportional to its weight. With all weights defaulting to 1 this is the plain mean.
+    let requiredScore = 1;
+    if (task.required.length > 0) {
+        let wsum = 0;
+        let acc = 0;
+        for (const r of task.required) {
+            const w = r.weight ?? 1;
+            wsum += w;
+            acc += w * (capabilitySatisfies(model.capabilities, r) ? evFactor(r.key, r.group) : 0);
+        }
+        requiredScore = wsum > 0 ? acc / wsum : 1;
+    }
     if (task.preferred.length === 0)
         return clamp01(requiredScore);
     const preferredScore = task.preferred.filter((r) => capabilitySatisfies(model.capabilities, r)).length / task.preferred.length;

package/dist/core/router/filter.js

@@ -8,6 +8,7 @@
  * it, so high-sensitivity input can never reach a cloud provider without an explicit allowance.
  */
 import { capabilitySatisfies } from '../capabilities/evidence.js';
+import { TIER_SCORE } from './dimensions.js';
 import { buildRequest } from './request.js';
 import { isExcluded } from './routingPrefs.js';
 function privacyFloor(task, p) {
@@ -78,6 +79,13 @@ export async function filterCandidates(input) {
             exclude(`context window ${candidate.model.contextWindow} < required ${task.minContextWindow}`);
             continue;
         }
+        // quality floor — exclude a model whose declared tier is below the task's floor. A model with NO
+        // quality tier is NOT excluded (metadata coverage is sparse; a floor is a preference gate, not a
+        // safety gate — excluding unrated models would silently empty a custom provider's pool).
+        if (task.qualityFloor !== undefined && candidate.model.quality?.tier !== undefined && TIER_SCORE[candidate.model.quality.tier] < TIER_SCORE[task.qualityFloor]) {
+            exclude(`model quality tier '${candidate.model.quality.tier}' is below the required floor '${task.qualityFloor}'`);
+            continue;
+        }
         // privacy (unconditional)
         if (requireLocal && provider.privacyClass !== 'local') {
             exclude(`privacy: high/undeclared sensitivity may not use cloud provider (privacyClass=${provider.privacyClass})`);
@@ -91,9 +99,24 @@ export async function filterCandidates(input) {
             exclude(`local providers disabled by policy`);
             continue;
         }
-        // hard cost / latency constraints
+        // estimate — a cheap, local (no-network) computation for built-in providers. Context-fit is ALWAYS
+        // enforced: an input that cannot fit a model's window must never be routed there merely because no
+        // cost/latency constraint was supplied. Cost/latency remain conditional on declared constraints. A
+        // third-party provider's estimate() could still throw; contain it so one bad candidate is excluded
+        // with a reason, not the whole route.
+        let estimate;
+        try {
+            estimate = await provider.estimate(buildRequest(input.template, modelId));
+        }
+        catch {
+            exclude(`estimate failed`);
+            continue;
+        }
+        if (!estimate.contextFits) {
+            exclude(`input does not fit model context window`);
+            continue;
+        }
         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;
@@ -102,10 +125,6 @@ export async function filterCandidates(input) {
                 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);
     }

package/dist/core/router/normalize.js

@@ -113,6 +113,8 @@ export function normalize(req, tasks, config) {
     };
     if (minContextWindow !== undefined)
         task.minContextWindow = minContextWindow;
+    if (def?.qualityFloor !== undefined)
+        task.qualityFloor = def.qualityFloor;
     if (output !== undefined)
         task.output = output;
     return { task, template };

package/dist/core/router/router.js

@@ -80,7 +80,18 @@ export class Router {
         const history = this.deps.performance
             ? (pid, mid) => this.deps.performance.forTask(task.id, pid, mid)
             : undefined;
-        const scored = scoreCandidates(eligible, task, config.weights, task.strategy, { ...(history ? { history } : {}), ...(req.routing ? { prefer: req.routing } : {}) });
+        // Per-provider score-weight overrides (ProviderConfig.weightOverrides), applied to that provider's
+        // candidates only. Built once here; empty ⇒ every provider scores under the base weights.
+        const weightOverridesByProvider = {};
+        for (const p of config.providers)
+            if (p.weightOverrides)
+                weightOverridesByProvider[p.id] = p.weightOverrides;
+        const hasOverrides = Object.keys(weightOverridesByProvider).length > 0;
+        const scored = scoreCandidates(eligible, task, config.weights, task.strategy, {
+            ...(history ? { history } : {}),
+            ...(req.routing ? { prefer: req.routing } : {}),
+            ...(hasOverrides ? { weightOverridesByProvider } : {}),
+        });
         const ranked = scored.map((s) => ({
             providerId: s.candidate.providerId,
             model: s.candidate.model.id,
@@ -142,6 +153,7 @@ export class Router {
             clock: this.clock,
             onAttempt,
             ...(template.stream && req.onDelta ? { onDelta: req.onDelta } : {}),
+            ...(template.stream && req.onStreamAbandoned ? { onStreamAbandoned: req.onStreamAbandoned } : {}),
             validate: (response) => validateResponse({ response, ...(template.output ? { output: template.output } : {}), ...(template.tools ? { tools: template.tools } : {}) }),
             ...(budget ? { budget, costOf } : {}),
             ...(this.deps.providerLimiter ? { providerLimiter: this.deps.providerLimiter } : {}),
@@ -176,7 +188,9 @@ export class Router {
                     confidence = Math.min(1, confidence + 0.05);
             }
         }
-        baseReport.belowConfidenceThreshold = confidence < config.minConfidence;
+        // The effective floor honors BOTH the config default and a stricter per-run constraints.minimumConfidence.
+        const effectiveMinConfidence = Math.max(config.minConfidence, req.constraints?.minimumConfidence ?? 0);
+        baseReport.belowConfidenceThreshold = confidence < effectiveMinConfidence;
         telemetry.emit({ type: 'route.result', ts: this.clock.now(), taskId: task.id, ok: true, confidence, totalLatencyMs: this.clock.now() - runStarted, fallbackCount });
         return { ok: true, response: fb.response, confidence, routing: baseReport };
     }

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

@@ -15,5 +15,8 @@ export interface ScoreOptions {
     /** User prefer routing — a SOFT nudge to the userPreference dimension (never a hard override). */
     prefer?: RoutingPreferences;
     history?: HistoryLookup;
+    /** Per-provider score-weight overrides (ProviderConfig.weightOverrides), merged over the base weights
+     *  for that provider's candidates only. Absent → every provider uses the base weights. */
+    weightOverridesByProvider?: Record<string, Partial<ScoreWeights>>;
 }
 export declare function scoreCandidates(candidates: Candidate[], task: NormalizedTask, baseWeights: ScoreWeights, strategy: Strategy, options?: ScoreOptions): ScoredCandidate[];