auto-model-router 0.1.0

package/src/router/features.ts

@@ -0,0 +1,225 @@
+/**
+ * Feature extraction: the cheap signals that drive classification.
+ *
+ * Everything here is a pure function of the normalized request. No tokenizer,
+ * no I/O, no model call — this runs on every agent turn, so the work is a few
+ * linear scans over the message list and at most one pass over the newest
+ * user-authored text.
+ */
+
+import type { NormMessage, NormRequest } from "../wire/types.ts";
+import type { Features } from "./types.ts";
+
+/**
+ * Complexity signals. Deliberately small: each hit pushes the turn toward a
+ * more expensive tier, so precision beats recall. Word-boundary matches,
+ * evaluated only against the newest user-authored content — never history.
+ */
+const COMPLEXITY_KEYWORDS: ReadonlyArray<readonly [string, RegExp]> = [
+	["architecture", /\barchitecture\b/i],
+	["refactor", /\brefactor\w*/i],
+	["debug", /\bdebug\w*/i],
+	// "race" (condition); inflected forms are too rare in agent traffic to matter.
+	["race", /\brace\b/i],
+	["deadlock", /\bdeadlock\w*/i],
+	// Causal "why" questions demand reasoning, not retrieval.
+	["why", /\bwhy\b/i],
+	["root cause", /\broot cause\b/i],
+	["design", /\bdesign\w*/i],
+	["optimize", /\boptimi[sz]\w*/i],
+	["security", /\bsecurity\b/i],
+	["migrate", /\bmigrat\w*/i],
+	["concurrency", /\bconcurren\w*/i],
+	["invariant", /\binvariant\w*/i],
+	["proof", /\bproof\w*/i],
+];
+
+/** Triviality signals: mechanical edits a small model cannot fumble. */
+const TRIVIALITY_KEYWORDS: ReadonlyArray<readonly [string, RegExp]> = [
+	["rename", /\brename\w*/i],
+	["typo", /\btypos?\b/i],
+	["format", /\bformat\w*/i],
+	// Dependency/version bumps.
+	["bump", /\bbump\w*/i],
+	["comment", /\bcomments?\b/i],
+	["changelog", /\bchangelogs?\b/i],
+	["add a test", /\badd (?:a|an|some) tests?\b/i],
+	["lint", /\blint(?:ing|ed)?\b/i],
+];
+
+/**
+ * Error markers scanned in tail tool results. Kept short and literal on
+ * purpose: a false positive escalates a turn that was actually fine, which
+ * costs real money; a false negative merely routes like a clean continuation.
+ */
+const TOOL_FAILURE_MARKERS: ReadonlyArray<RegExp> = [
+	// "error:"/"Error:" at a line start — the near-universal tool error prefix.
+	/(?:^|\n)\s*(?:error|Error):/,
+	// Python crash dump.
+	/Traceback \(most recent call last\)/,
+	// Shell: missing binary.
+	/command not found/,
+	// Non-zero process exit. "exit code 0" is success and never matches.
+	/exit(?:ed with)? code [1-9]\d*/i,
+	// GNU make: "make: *** [target] Error 2". "Error" sits mid-line so the
+	// prefix rule above misses it, and the "*** " literal is distinctive
+	// enough that successful builds never produce it.
+	/(?:^|\n)[^\n]*\*\*\* \[[^\]]*\] Error \d+/,
+];
+
+// Unified-diff headers. Plain "--- "/"+++ " are excluded: markdown rules and
+// lists would false-positive. `diff --git`, hunks, and a/ b/ paths are real diffs.
+const DIFF_RE = /(?:^|\n)(?:diff --git |@@ -\d|\+{3} b\/|-{3} a\/)/;
+
+// A "terse instruction" is one short sentence; longer text carries real requirements.
+const TERSE_MAX_BYTES = 128;
+
+/** Index after the last message of the trailing run matching `pred`. */
+function trailingRunStart(messages: NormMessage[], pred: (m: NormMessage) => boolean): number {
+	let i = messages.length - 1;
+	while (i >= 0) {
+		const m = messages[i];
+		if (m === undefined || !pred(m)) break;
+		i--;
+	}
+	return i + 1;
+}
+
+export function extractFeatures(req: NormRequest, promptTokens: number): Features {
+	const messages = req.messages;
+	const tail = messages[messages.length - 1];
+
+	// The volatile tail: either the newest user-authored content (a trailing
+	// run of user messages — what the human just supplied) or, when the tail is
+	// tool output, a mechanical agent-loop continuation with no new user content.
+	const isToolResultContinuation = tail?.role === "tool";
+	let newContentBytes = 0;
+	let newestUserText = "";
+	if (isToolResultContinuation) {
+		const start = trailingRunStart(messages, (m) => m.role === "tool");
+		for (let i = start; i < messages.length; i++) newContentBytes += messages[i]?.textBytes ?? 0;
+	} else if (tail?.role === "user") {
+		const start = trailingRunStart(messages, (m) => m.role === "user");
+		const parts: string[] = [];
+		for (let i = start; i < messages.length; i++) {
+			const m = messages[i];
+			if (m === undefined) continue;
+			newContentBytes += m.textBytes;
+			parts.push(m.text);
+		}
+		newestUserText = parts.join("\n");
+	}
+	// Proportional share of the caller's prompt estimate, so this inherits
+	// whatever tokenizer calibration the estimate already applied.
+	const newContentTokens =
+		req.promptBytes > 0 && newContentBytes > 0
+			? Math.max(1, Math.round(promptTokens * (newContentBytes / req.promptBytes)))
+			: 0;
+
+	// Depth of the current agent loop: trailing tool results plus the assistant
+	// tool-call turns interleaved with them.
+	let toolLoopDepth = 0;
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const m = messages[i];
+		if (m === undefined) break;
+		if (m.role === "tool" || (m.role === "assistant" && m.toolCalls.length > 0)) toolLoopDepth++;
+		else break;
+	}
+
+	let turnDepth = 0;
+	let toolSchemaBytes = 0;
+	const toolNames = new Set<string>();
+	for (const t of req.tools) toolSchemaBytes += t.schemaBytes;
+	for (const m of messages) {
+		if (m.role === "user" || m.role === "assistant") turnDepth++;
+		if (m.role === "assistant") for (const tc of m.toolCalls) toolNames.add(tc.name);
+		if (m.toolName !== undefined) toolNames.add(m.toolName);
+	}
+
+	// The last two assistant tool calls, in conversation order.
+	let lastName: string | null = null;
+	let lastArgs = "";
+	let prevName: string | null = null;
+	let prevArgs = "";
+	scanCalls: for (let i = messages.length - 1; i >= 0; i--) {
+		const m = messages[i];
+		if (m === undefined || m.role !== "assistant") continue;
+		for (let j = m.toolCalls.length - 1; j >= 0; j--) {
+			const tc = m.toolCalls[j];
+			if (tc === undefined) continue;
+			if (lastName === null) {
+				lastName = tc.name;
+				lastArgs = tc.argsJson;
+			} else {
+				prevName = tc.name;
+				prevArgs = tc.argsJson;
+				break scanCalls;
+			}
+		}
+	}
+	const repeatedToolCall = lastName !== null && lastName === prevName && lastArgs === prevArgs;
+
+	let lastToolFailed = false;
+	if (isToolResultContinuation) {
+		scanResults: for (let i = messages.length - 1; i >= 0; i--) {
+			const m = messages[i];
+			if (m === undefined || m.role !== "tool") break;
+			for (const re of TOOL_FAILURE_MARKERS) {
+				if (re.test(m.text)) {
+					lastToolFailed = true;
+					break scanResults;
+				}
+			}
+		}
+	}
+
+	// Fenced code blocks: odd segments of a ``` split. Byte count includes the
+	// language tag line — close enough for a signal, and allocation-free per block.
+	let codeBlocks = 0;
+	let codeBytes = 0;
+	if (newestUserText.includes("```")) {
+		const parts = newestUserText.split("```");
+		codeBlocks = (parts.length - 1) >> 1;
+		for (let i = 1; i + 1 < parts.length; i += 2) codeBytes += Buffer.byteLength(parts[i] ?? "");
+	}
+
+	let questionCount = 0;
+	for (let i = 0; i < newestUserText.length; i++) {
+		if (newestUserText.charCodeAt(i) === 63) questionCount++;
+	}
+
+	const complexityKeywords: string[] = [];
+	for (const [id, re] of COMPLEXITY_KEYWORDS) if (re.test(newestUserText)) complexityKeywords.push(id);
+	const trivialityKeywords: string[] = [];
+	for (const [id, re] of TRIVIALITY_KEYWORDS) if (re.test(newestUserText)) trivialityKeywords.push(id);
+
+	const trimmed = newestUserText.trim();
+	const terminators = trimmed.match(/[.!?]+(?:\s|$)/g);
+	const isTerseInstruction =
+		trimmed.length > 0 &&
+		Buffer.byteLength(trimmed) <= TERSE_MAX_BYTES &&
+		codeBlocks === 0 &&
+		(terminators === null ? 0 : terminators.length) <= 1;
+
+	return {
+		promptTokens,
+		newContentTokens,
+		turnDepth,
+		toolCount: req.tools.length,
+		toolSchemaBytes,
+		isToolResultContinuation,
+		toolLoopDepth,
+		distinctToolsUsed: toolNames.size,
+		lastToolFailed,
+		repeatedToolCall,
+		hasImages: req.hasImages,
+		codeBlocks,
+		codeBytes,
+		looksLikeDiff: DIFF_RE.test(newestUserText),
+		complexityKeywords,
+		trivialityKeywords,
+		requestedReasoning: req.reasoning,
+		questionCount,
+		isTerseInstruction,
+	};
+}

package/src/router/index.ts

@@ -0,0 +1,99 @@
+/**
+ * Router assembly: estimate -> features -> classify -> select.
+ *
+ * Deliberately READ-ONLY with respect to conversation state. `server/turn.ts`
+ * owns every write, because only it knows the committed outcome (which model
+ * actually served, what it cost, whether the cache went warm). Routing that
+ * also persisted would race that save and lose the sticky window.
+ *
+ * The read-only property is what makes `auto-model-router explain` safe: it routes a
+ * real request without perturbing the conversation it belongs to.
+ */
+
+import type { CatalogSource } from "../catalog/types.ts";
+import type { ProfileConfig, RouterConfig } from "../config/types.ts";
+import type { Ledger } from "../cost/types.ts";
+import { estimatePromptTokens } from "../tokens/estimate.ts";
+import type { UpstreamClient } from "../upstream/types.ts";
+import type { NormRequest } from "../wire/types.ts";
+import { classify, classifyTask } from "./classify.ts";
+import { extractFeatures } from "./features.ts";
+import { select } from "./select.ts";
+import { TIER_ORDER, type Classification, type ConversationStore, type Decision, type Router, type Tier } from "./types.ts";
+
+export interface RouterDeps {
+	config: RouterConfig;
+	catalog: CatalogSource;
+	ledger: Ledger;
+	conversations: ConversationStore;
+	upstream: UpstreamClient;
+}
+
+/**
+ * Tokenizer used for prompt estimation before a model is chosen.
+ *
+ * Chicken-and-egg: the estimate feeds candidate filtering, so it cannot depend
+ * on the winner. The conversation's previous model is the best available proxy,
+ * and family ratios differ by only a few percent anyway.
+ */
+const NEUTRAL_TOKENIZER = "gpt";
+
+function resolveProfile(cfg: RouterConfig, requestedModel: string): ProfileConfig {
+	const exact = cfg.profiles.find((p) => p.id === requestedModel);
+	if (exact !== undefined) return exact;
+	const fallback = cfg.profiles[0];
+	if (fallback === undefined) throw new Error("no router profiles configured");
+	return fallback;
+}
+
+export function createRouter(deps: RouterDeps): Router {
+	const { config, catalog, ledger, conversations, upstream } = deps;
+
+	return {
+		async route(
+			req: NormRequest,
+			opts: { attempt: number; escalateFrom?: Tier; excludeSlugs?: readonly string[] },
+		): Promise<Decision> {
+			const state = conversations.get(req.conversationKey) ?? conversations.load(req.conversationKey);
+			const snapshot = await catalog.get();
+
+			const priorTokenizer =
+				state.currentSlug === null ? undefined : catalog.find(state.currentSlug)?.tokenizer;
+			const promptTokens = estimatePromptTokens(req, priorTokenizer ?? NEUTRAL_TOKENIZER, ledger);
+			const features = extractFeatures(req, promptTokens);
+
+			let classification: Classification;
+			if (opts.escalateFrom !== undefined) {
+				// An escalation is not a re-judgement: the probe already proved the
+				// cheaper tier failed, so force strictly upward rather than letting
+				// the classifier re-derive the same losing answer.
+				const nextIdx = Math.min(TIER_ORDER.indexOf(opts.escalateFrom) + 1, TIER_ORDER.length - 1);
+				const forced = TIER_ORDER[nextIdx];
+				if (forced === undefined) throw new Error(`unresolvable escalation tier from ${opts.escalateFrom}`);
+				classification = {
+					tier: forced,
+					task: classifyTask(features),
+					confidence: 1,
+					source: "escalation",
+					score: 1,
+					reasons: [`escalated from ${opts.escalateFrom} after attempt ${opts.attempt - 1} was rejected`],
+				};
+			} else {
+				classification = await classify(req, features, config, { upstream, ledger, catalog });
+			}
+
+			return select({
+				req,
+				features,
+				classification,
+				profile: resolveProfile(config, req.requestedModel),
+				state,
+				snapshot,
+				ledger,
+				cfg: config,
+				nowMs: Date.now(),
+				...(opts.excludeSlugs === undefined ? {} : { excludeSlugs: opts.excludeSlugs }),
+			});
+		},
+	};
+}

package/src/router/select.ts

@@ -0,0 +1,365 @@
+/**
+ * Selection: turn a classification into a concrete model decision.
+ *
+ * This is the economic core of the router: profile clamping, hysteresis,
+ * candidate widening, the cache-aware stay/switch arithmetic, the budget
+ * guard, fallbacks, cache breakpoints, probe planning, and capability clamps.
+ */
+
+import type { CatalogSnapshot } from "../catalog/types.ts";
+import type { ProfileConfig, RouterConfig } from "../config/types.ts";
+import { priceAt } from "../cost/forecast.ts";
+import type { Ledger } from "../cost/types.ts";
+import type { NormRequest, ReasoningLevel } from "../wire/types.ts";
+import { planCacheBreakpoints } from "./cache-control.ts";
+import { buildCandidates } from "./candidates.ts";
+import {
+	TIER_ORDER,
+	type Candidate,
+	type Classification,
+	type ConversationState,
+	type Decision,
+	type Features,
+	type ProbePlan,
+	type Rejection,
+	type Tier,
+} from "./types.ts";
+
+export interface SelectArgs {
+	req: NormRequest;
+	features: Features;
+	classification: Classification;
+	profile: ProfileConfig;
+	state: ConversationState;
+	snapshot: CatalogSnapshot;
+	ledger: Ledger | null;
+	cfg: RouterConfig;
+	nowMs: number;
+	/**
+	 * Slugs that already failed on this turn. Passed straight to
+	 * `buildCandidates` so a failover retry lands on a different model.
+	 */
+	excludeSlugs?: readonly string[];
+}
+
+/**
+ * Thrown when the budget guard rejects a turn. `status`/`code` mirror the
+ * WireError shape so the server can render it as a 402-class response.
+ */
+export class BudgetExceededError extends Error {
+	readonly status = 402;
+	readonly code = "budget_exceeded";
+	constructor(message: string) {
+		super(message);
+		this.name = "BudgetExceededError";
+	}
+}
+
+// Mid-range completion assumption for forecasts. Long generations amortize
+// into prompt-dominated cost anyway; precision here does not move rankings.
+const EXPECTED_COMPLETION_TOKENS = 1024;
+const DAY_MS = 86_400_000;
+
+/**
+ * Authors known to accept replayed assistant reasoning over chat completions:
+ * Anthropic requires thinking-block replay for tool-use continuity, and Google
+ * requires thought signatures. Everything else gets reasoning stripped — a
+ * rejected replay costs a whole turn.
+ */
+const REASONING_REPLAY_AUTHORS: Record<string, true> = {
+	anthropic: true,
+	google: true,
+};
+
+function tierIdx(t: Tier): number {
+	return TIER_ORDER.indexOf(t);
+}
+
+function tierAt(i: number): Tier | null {
+	const t = TIER_ORDER[i];
+	return t === undefined ? null : t;
+}
+
+/** Tier search order: the tier itself, then one up, one down, two up, ... within [minTier, maxTier]. */
+function wideningOrder(tier: Tier, minTier: Tier, maxTier: Tier): Tier[] {
+	const lo = tierIdx(minTier);
+	const hi = tierIdx(maxTier);
+	const c = tierIdx(tier);
+	const out: Tier[] = [];
+	for (let d = 0; d <= Math.max(hi - c, c - lo); d++) {
+		const up = tierAt(c + d);
+		const down = tierAt(c - d);
+		if (d === 0) {
+			if (up !== null) out.push(up);
+			continue;
+		}
+		if (up !== null && c + d <= hi) out.push(up);
+		if (down !== null && c - d >= lo) out.push(down);
+	}
+	return out;
+}
+
+export function select(args: SelectArgs): Decision {
+	const { req, features, classification, profile, state, snapshot, ledger, cfg, nowMs } = args;
+	const reasons: string[] = [];
+	const minI = tierIdx(profile.minTier);
+	const maxI = tierIdx(profile.maxTier);
+	const clampTier = (t: Tier): Tier => tierAt(Math.min(Math.max(tierIdx(t), minI), maxI)) ?? t;
+
+	// 1. Clamp the classified tier to the requesting profile's envelope.
+	let effective = clampTier(classification.tier);
+	if (effective !== classification.tier) {
+		reasons.push(`classified ${classification.tier}, clamped to profile ${profile.id} [${profile.minTier}..${profile.maxTier}] → ${effective}`);
+	}
+
+	// 2. Hysteresis: while the sticky window is open, never route below the
+	//    held tier — per-turn flapping would repeatedly cold-start prompt caches.
+	let cls = classification;
+	if (state.stickyUntilTurn > state.turn && state.currentTier !== null && tierIdx(state.currentTier) >= tierIdx(effective)) {
+		const held = clampTier(state.currentTier);
+		if (held !== effective) {
+			reasons.push(`hysteresis: holding ${held} until turn ${state.stickyUntilTurn} (classified ${effective})`);
+			cls = {
+				...classification,
+				tier: held,
+				source: "sticky",
+				reasons: [`hysteresis hold ${held} until turn ${state.stickyUntilTurn}`, ...classification.reasons],
+			};
+			effective = held;
+		}
+	}
+	// Never downgrade more than maxDowngradePerTurn tiers in one turn, so
+	// quality never falls off a cliff on a single odd classification.
+	if (state.currentTier !== null) {
+		const floor = Math.max(tierIdx(state.currentTier) - cfg.hysteresis.maxDowngradePerTurn, minI);
+		if (tierIdx(effective) < floor) {
+			const clamped = tierAt(floor);
+			if (clamped !== null) {
+				reasons.push(`downgrade limited to ${cfg.hysteresis.maxDowngradePerTurn} tier(s)/turn: ${effective} → ${clamped}`);
+				effective = clamped;
+			}
+		}
+	}
+
+	// 3. Candidates for the effective tier; widen one tier upward, then
+	//    downward, and only fail when the whole profile envelope is exhausted.
+	// The task type selects the quality axis and capability filters; the tier
+	// still bounds cost (task selects, tier budgets).
+	const warmSlug =
+		state.cacheWarmSlug !== null && nowMs - state.cacheWarmAtMs <= cfg.hysteresis.cacheWarmTtlMs
+			? state.cacheWarmSlug
+			: null;
+	const build = (t: Tier, relaxLevel = 0): { candidates: Candidate[]; rejected: Rejection[] } =>
+		buildCandidates({
+			req,
+			features,
+			tier: t,
+			task: classification.task,
+			snapshot,
+			ledger,
+			cfg,
+			expectedCompletionTokens: EXPECTED_COMPLETION_TOKENS,
+			warmSlug,
+			relaxLevel,
+			...(args.excludeSlugs === undefined ? {} : { excludeSlugs: args.excludeSlugs }),
+		});
+	let chosenTier = effective;
+	let built: { candidates: Candidate[]; rejected: Rejection[] } | null = null;
+	// Relax level the tier rescue used (0 = no rescue). The budget downgrade
+	// search must rebuild at the same level, or it re-applies the strict config
+	// that excluded every model and throws instead of downgrading.
+	let rescuedRelax = 0;
+	for (const t of wideningOrder(effective, profile.minTier, profile.maxTier)) {
+		const b = build(t);
+		if (b.candidates.length > 0) {
+			built = b;
+			chosenTier = t;
+			break;
+		}
+		reasons.push(`no candidates in ${t} (${b.rejected.length} rejected)`);
+		built ??= b;
+	}
+	// Tier rescue: the configured envelopes (price ceilings, quality floors,
+	// trust bar) were tuned against the full catalog, and a guardrail can shrink
+	// availability so no configured tier admits anything. Rather than 500, relax
+	// the tier's economic constraints — in order, price → quality → trust — until
+	// some AVAILABLE model qualifies. Hard capability filters (tools/images/
+	// context) and the key-scoped allowlist are never lifted.
+	if (built === null || built.candidates.length === 0) {
+		const envelope = wideningOrder(effective, profile.minTier, profile.maxTier);
+		let rescued = false;
+		for (let relax = 1; relax <= 3 && !rescued; relax++) {
+			for (const t of envelope) {
+				const b = build(t, relax);
+				if (b.candidates.length > 0) {
+					built = b;
+					chosenTier = t;
+					rescued = true;
+					rescuedRelax = relax;
+					break;
+				}
+			}
+		}
+		if (rescued) {
+			const first = built!.candidates[0];
+			const label =
+				rescuedRelax === 1
+					? "price ceilings"
+					: rescuedRelax === 2
+						? "price ceilings + quality floors"
+						: "price ceilings + quality floors + trust bar";
+			reasons.push(
+				`tier rescue: strict config excluded all available models; relaxed ${label} to pick ${first!.model.slug} (${chosenTier})`,
+			);
+		} else if (built === null || built.candidates.length === 0) {
+			throw new Error(`no viable model: catalog exhausted across profile ${profile.id}`);
+		}
+	}
+	if (chosenTier !== effective) reasons.push(`widened ${effective} → ${chosenTier}`);
+	// After the rescue block, `built` is guaranteed non-null: the branch either
+	// rescued a non-empty candidate set, or threw the `catalog exhausted` error.
+	const resolved = built as { candidates: Candidate[]; rejected: Rejection[] };
+	let candidates = resolved.candidates;
+	const first = candidates[0];
+	if (first === undefined) throw new Error(`no viable model: catalog exhausted across profile ${profile.id}`);
+	let chosen = first;
+
+	// 4. Cache-aware switch decision. Staying prices the previous turn's prompt
+	//    at the warm model's cache-read rate; switching prices the full current
+	//    prompt at the new model's cold rate plus its cache-write premium (we
+	//    assume the whole prompt is written). Switch only when the saving
+	//    clears switchMargin.
+	let sticky = false;
+	if (warmSlug !== null && chosen.model.slug !== warmSlug) {
+		const warm = candidates.find((c) => c.model.slug === warmSlug);
+		if (warm !== undefined) {
+			const warmPrice = priceAt(warm.model, Math.max(1, state.lastPromptTokens));
+			const newPrice = priceAt(chosen.model, Math.max(1, features.promptTokens));
+			const stayCost = state.lastPromptTokens * (warmPrice.cacheRead ?? warmPrice.prompt);
+			const switchCost = features.promptTokens * (newPrice.prompt + (newPrice.cacheWrite ?? 0));
+			if (stayCost > switchCost * cfg.hysteresis.switchMargin) {
+				reasons.push(
+					`cache: switch ${warmSlug} → ${chosen.model.slug} (stay $${stayCost.toFixed(4)} > switch $${switchCost.toFixed(4)} × ${cfg.hysteresis.switchMargin})`,
+				);
+			} else {
+				chosen = warm;
+				sticky = true;
+				reasons.push(
+					`cache: keeping warm ${warmSlug} (stay $${stayCost.toFixed(4)} ≤ switch $${switchCost.toFixed(4)} × ${cfg.hysteresis.switchMargin})`,
+				);
+			}
+		}
+	}
+
+	// 5. Budget guard, against the COLD forecast: a budget must survive a cache miss.
+	const budget = {
+		perTurnUsd: profile.budget?.perTurnUsd ?? cfg.budget.perTurnUsd,
+		perConversationUsd: profile.budget?.perConversationUsd ?? cfg.budget.perConversationUsd,
+		perDayUsd: profile.budget?.perDayUsd ?? cfg.budget.perDayUsd,
+		onExceeded: profile.budget?.onExceeded ?? cfg.budget.onExceeded,
+	};
+	const breach = (c: Candidate): string | null => {
+		if (budget.perTurnUsd !== undefined && c.forecast.coldUsd > budget.perTurnUsd) {
+			return `cold forecast $${c.forecast.coldUsd.toFixed(4)} > per-turn budget $${budget.perTurnUsd}`;
+		}
+		if (budget.perConversationUsd !== undefined && state.spentUsd + c.forecast.coldUsd > budget.perConversationUsd) {
+			return `conversation spend $${state.spentUsd.toFixed(4)} + cold forecast > per-conversation budget $${budget.perConversationUsd}`;
+		}
+		if (budget.perDayUsd !== undefined) {
+			// Scope the rolling 24h ceiling to the requesting harness when it
+			// identifies itself, so multiple harnesses sharing one router each get
+			// their own daily budget instead of one exhausting it for the others.
+			const daySpend = ledger?.spendSince(nowMs - DAY_MS, req.harnessId) ?? 0;
+			if (daySpend + c.forecast.coldUsd > budget.perDayUsd) {
+				return `24h spend $${daySpend.toFixed(4)} + cold forecast > per-day budget $${budget.perDayUsd}`;
+			}
+		}
+		return null;
+	};
+	let budgetDowngraded = false;
+	const why = breach(chosen);
+	if (why !== null) {
+		if (budget.onExceeded === "reject") throw new BudgetExceededError(why);
+		// Downgrade: the cheapest candidate in the cheapest tier that fits.
+		let rescue: { tier: Tier; candidate: Candidate; candidates: Candidate[] } | null = null;
+		for (const t of wideningOrder(profile.minTier, profile.minTier, profile.maxTier)) {
+			const b = build(t, rescuedRelax);
+			let cheapest: Candidate | null = null;
+			for (const c of b.candidates) {
+				if (cheapest === null || c.forecast.coldUsd < cheapest.forecast.coldUsd) cheapest = c;
+			}
+			if (cheapest !== null && breach(cheapest) === null) {
+				rescue = { tier: t, candidate: cheapest, candidates: b.candidates };
+				break;
+			}
+		}
+		if (rescue === null) throw new BudgetExceededError(`${why}; no cheaper candidate fits the budget`);
+		reasons.push(`budget: ${why}; downgraded ${chosenTier} → ${rescue.tier} (${rescue.candidate.model.slug})`);
+		chosen = rescue.candidate;
+		chosenTier = rescue.tier;
+		candidates = rescue.candidates;
+		budgetDowngraded = true;
+		sticky = false;
+	}
+
+	// 6. Same-tier fallbacks for OpenRouter's transient-error `models[]` cascade.
+	const fallbacks: string[] = [];
+	for (const c of candidates) {
+		if (c.model.slug === chosen.model.slug) continue;
+		fallbacks.push(c.model.slug);
+		if (fallbacks.length >= 2) break;
+	}
+
+	// 7. Cache breakpoints.
+	const cacheBreakpointMessageIndices = planCacheBreakpoints(req, chosen.model, cfg);
+
+	// 8. Guarded probe: only tiers configured for probing, and only when a
+	//    strictly higher tier exists inside the profile envelope to escalate into.
+	const nextTier = tierAt(tierIdx(chosenTier) + 1);
+	const escalateTo = nextTier !== null && tierIdx(nextTier) <= maxI ? nextTier : null;
+	const probeEnabled = cfg.escalation.enabled && escalateTo !== null && cfg.escalation.probeTiers.includes(chosenTier);
+	const probe: ProbePlan = {
+		enabled: probeEnabled,
+		maxTokens: cfg.escalation.probeTokens,
+		maxHoldMs: cfg.escalation.maxHoldMs,
+		escalateTo: probeEnabled ? escalateTo : null,
+	};
+
+	// 9. Clamp reasoning and output budget to what the target supports.
+	let reasoning: ReasoningLevel | undefined = req.reasoning;
+	if (reasoning !== undefined && !chosen.model.supportsReasoning) {
+		if (reasoning !== "off") reasons.push(`dropped reasoning=${reasoning}: ${chosen.model.slug} does not support it`);
+		reasoning = undefined;
+	}
+	if (chosen.model.reasoningMandatory && (reasoning === undefined || reasoning === "off")) {
+		reasoning = "minimal";
+		reasons.push(`reasoning forced to minimal: ${chosen.model.slug} has mandatory reasoning`);
+	}
+	let maxTokens: number | undefined = req.maxTokens;
+	const ceiling = chosen.model.maxCompletionTokens;
+	if (ceiling !== undefined) {
+		// The ceiling is a hard limit anyway; passing it explicitly also caps runaway completions.
+		maxTokens = maxTokens === undefined ? ceiling : Math.min(maxTokens, ceiling);
+	}
+	const stripAssistantReasoning = !(chosen.model.supportsReasoning && REASONING_REPLAY_AUTHORS[chosen.model.author] === true);
+
+	return {
+		slug: chosen.model.slug,
+		fallbacks,
+		tier: chosenTier,
+		classification: cls,
+		features,
+		forecast: chosen.forecast,
+		sessionId: state.sessionId,
+		sticky,
+		cacheBreakpointMessageIndices,
+		reasoning,
+		maxTokens,
+		stripAssistantReasoning,
+		probe,
+		considered: candidates,
+		rejected: resolved.rejected,
+		reasons,
+		budgetDowngraded,
+	};
+}