auto-model-router 0.3.3 → 0.4.0

package/src/config/types.ts

@@ -264,6 +264,14 @@ export interface FilterConfig {
 	latencyReferenceTokensPerSec: number;
 	/** Streamed samples required before latency is scored against a model. */
 	latencyMinSamples: number;
+	/**
+	 * Warm-expected samples a model needs before its observed cache hit rate
+	 * (ledger `cacheReliability`) discounts the "stay warm" price in the
+	 * stay/switch comparison. Below it, and when 0, a cache is assumed fully
+	 * reliable. Measured 2026-09-06: same-model short-gap turns still ran cold
+	 * 5-6% on glm/gemini, 11% on ling and 50% on nex.
+	 */
+	cacheReliabilityMinSamples: number;
 	/**
 	 * Absolute expected-wait ceiling (ms). A hard drop, mirroring the price
 	 * ceiling: any model whose expected total wait (TTFT + streaming the expected
@@ -277,6 +285,13 @@ export interface FilterConfig {
 	 * Undefined ⇒ off (the default).
 	 */
 	maxExpectedWaitMs?: number;
+	/**
+	 * Latency weight for tool-result continuations (the agent loop's own
+	 * follow-ups, where no person is waiting on first token). Unset ⇒
+	 * `latencyWeight` applies to every turn. Lower it to spend speed only on
+	 * user-facing turns.
+	 */
+	latencyWeightContinuation?: number;
 	/**
 	 * How much of a model's measured escalation risk to price into its effective
 	 * cost, 0-1. 0 (the default) disables the term.
@@ -305,6 +320,13 @@ export interface ClassifierConfig {
 	ambiguityThreshold: number;
 	/** Slug used for adjudication. Must be cheap and fast. */
 	model: string;
+	/**
+	 * Path of a model written by `tools/train-classifier.ts`. When set, every
+	 * heuristic classification also carries the learned P(escalate) in its
+	 * reasons (`learned: p(escalate)=…`) and `Classification.learnedRisk`.
+	 * Advisory: it never moves a tier. Empty ⇒ off.
+	 */
+	learnedModelPath: string;
 	/** Skip adjudication when it would exceed this fraction of the forecast turn cost. */
 	maxCostFraction: number;
 	/** Absolute per-call ceiling, USD. */
@@ -392,6 +414,19 @@ export interface HysteresisConfig {
 	 * dispatches per user-visible turn, so single digits are conservative.
 	 */
 	switchHorizonTurns: number;
+	/**
+	 * A heuristic tier UPGRADE whose classification confidence is below this
+	 * waits one turn when the current model's cache is warm; a second
+	 * consecutive upgrade classification confirms it. 0 disables. Escalations,
+	 * explicit high reasoning and failing tool loops bypass the wait.
+	 *
+	 * Measured on 7 days of live traffic: 65 of 67 moderate→hard upgrades
+	 * bounced back within 3 turns, 50 of them below 0.6 confidence, costing
+	 * $17.90 in cold hard-tier prompt reads against $0.23 for staying warm.
+	 * The stay/switch comparison never sees these because the warm cheap
+	 * model is below the new tier's floor.
+	 */
+	confirmUpgradesBelowConfidence: number;
 	/** Assume a warm cache expires after this long. OpenRouter sticky sessions: 5-10 min. */
 	cacheWarmTtlMs: number;
 	/** Downgrade at most this many tiers per turn, so quality never falls off a cliff. */
@@ -495,6 +530,17 @@ export interface CacheConfig {
 	milestoneTokens: number;
 }
 
+/** Usage-report options. */
+export interface ReportConfig {
+	/**
+	 * Models to price the window's traffic on as if every turn had used that
+	 * one model, at its list price with the window's own cache hit rate: the
+	 * "what the router saved" counterfactual. Slugs missing from the catalog
+	 * are skipped.
+	 */
+	baselines: string[];
+}
+
 export interface BudgetConfig {
 	/** Reject or downgrade when a turn's cold forecast exceeds this, USD. */
 	perTurnUsd?: number;
@@ -502,6 +548,13 @@ export interface BudgetConfig {
 	perConversationUsd?: number;
 	/** Rolling 24h ceiling, USD. */
 	perDayUsd?: number;
+	/**
+	 * Calendar-month (UTC) target, USD. Paced: the per-day ceiling becomes
+	 * min(perDayUsd, remaining ÷ days left in the month), so a month that runs
+	 * ahead of pace tightens automatically instead of failing on its last day.
+	 * Scoped per harness like perDayUsd.
+	 */
+	perMonthUsd?: number;
 	/** At the ceiling: drop to the cheapest viable model, or fail the request outright. */
 	onExceeded: "downgrade" | "reject";
 }
@@ -663,6 +716,7 @@ export interface RouterConfig {
 	context: ContextConfig;
 	compaction: CompactionConfig;
 	budget: BudgetConfig;
+	report: ReportConfig;
 	profiles: ProfileConfig[];
 	ledger: LedgerConfig;
 	/**

package/src/cost/feedback.ts

@@ -0,0 +1,81 @@
+/**
+ * User verdicts on routed turns, from omp (`/router feedback good|bad`).
+ *
+ * The router otherwise learns only from escalation signals. A person saying
+ * a cheap model's answer was wrong — or that it was fine — is the label the
+ * de-escalation question needs. Each verdict is tied to the ledger row it
+ * judged, so it aggregates by served model, tier and task.
+ */
+
+import type { Database } from "bun:sqlite";
+
+export type Verdict = "good" | "bad";
+
+export interface FeedbackRecord {
+	ledgerId: string;
+	ompSessionId: string;
+	slug: string;
+	tier: string;
+	verdict: Verdict;
+	note: string;
+}
+
+export interface FeedbackCounts {
+	good: number;
+	bad: number;
+}
+
+export interface FeedbackStore {
+	record(rec: FeedbackRecord, nowMs?: number): string;
+	/** Verdict counts per served slug since `sinceMs`. */
+	countsBySlug(sinceMs: number, harnessId?: string): Map<string, FeedbackCounts>;
+	/** Verdicts for one ledger row (a user may re-judge). */
+	forLedgerId(ledgerId: string): Array<{ verdict: Verdict; note: string; createdAtMs: number }>;
+}
+
+export function createFeedbackStore(db: Database): FeedbackStore {
+	const insert = db.query(
+		`INSERT INTO feedback (id, ledger_id, omp_session_id, slug, tier, verdict, note, created_at_ms)
+		 VALUES ($id, $ledgerId, $ompSessionId, $slug, $tier, $verdict, $note, $createdAtMs)`,
+	);
+	const bySlug = db.query(
+		`SELECT f.slug, f.verdict, COUNT(*) AS n FROM feedback f
+		 LEFT JOIN ledger l ON l.id = f.ledger_id
+		 WHERE f.created_at_ms >= $since AND ($harness = '' OR l.harness_id = $harness)
+		 GROUP BY f.slug, f.verdict`,
+	);
+	const forRow = db.query("SELECT verdict, note, created_at_ms FROM feedback WHERE ledger_id = ? ORDER BY created_at_ms DESC");
+	return {
+		record(rec, nowMs = Date.now()) {
+			const id = crypto.randomUUID();
+			insert.run({
+				$id: id,
+				$ledgerId: rec.ledgerId,
+				$ompSessionId: rec.ompSessionId,
+				$slug: rec.slug,
+				$tier: rec.tier,
+				$verdict: rec.verdict,
+				$note: rec.note.slice(0, 500),
+				$createdAtMs: nowMs,
+			});
+			return id;
+		},
+		countsBySlug(sinceMs, harnessId = "") {
+			const out = new Map<string, FeedbackCounts>();
+			for (const r of bySlug.all({ $since: sinceMs, $harness: harnessId }) as { slug: string; verdict: string; n: number }[]) {
+				const c = out.get(r.slug) ?? { good: 0, bad: 0 };
+				if (r.verdict === "good") c.good += r.n;
+				else c.bad += r.n;
+				out.set(r.slug, c);
+			}
+			return out;
+		},
+		forLedgerId(ledgerId) {
+			return (forRow.all(ledgerId) as { verdict: Verdict; note: string; created_at_ms: number }[]).map((r) => ({
+				verdict: r.verdict,
+				note: r.note,
+				createdAtMs: r.created_at_ms,
+			}));
+		},
+	};
+}

package/src/cost/ledger.ts

@@ -24,6 +24,7 @@ import type {
 	Ledger,
 	LedgerEntry,
 	LedgerSignals,
+	ModelCacheReliability,
 	ModelLatency,
 	ModelTrust,
 	UsageCounts,
@@ -38,6 +39,14 @@ const MAX_SANE_BYTES_PER_TOKEN = 8;
 const MIN_ESCALATION_SAMPLES = 10;
 /** The escalation-cost aggregate scans a window of rows; memoised for this long. */
 const ESCALATION_COST_MEMO_MS = 60_000;
+
+/**
+ * Cache reliability is one window-function pass over the newest rows, memoised
+ * for a minute: the previous kept turn of each conversation is found with LAG,
+ * and a row counts when that turn was on the same model within the warm TTL.
+ */
+const CACHE_RELIABILITY_ROWS = 6_000;
+const CACHE_RELIABILITY_MEMO_MS = 60_000;
 const DAY_MS = 86_400_000;
 
 // Row shapes below are fixed by our own schema in util/sqlite.ts.
@@ -236,7 +245,42 @@ function toEntry(row: LedgerRow): LedgerEntry {
 	};
 }
 
+export interface CacheReliabilityRow {
+	slug: string;
+	samples: number;
+	hit: number;
+}
+
+/**
+ * Observed cache hit rates when a warm cache was expected, per served slug.
+ * `sinceMs` bounds the rows scanned (0 ⇒ the newest `limitRows`). Rows whose
+ * cache count the router estimated (`usage.cachedEstimated`) are excluded.
+ */
+export function queryCacheReliability(db: Database, opts: { warmTtlMs: number; sinceMs?: number; limitRows?: number }): CacheReliabilityRow[] {
+	const sinceMs = opts.sinceMs ?? 0;
+	const limitRows = opts.limitRows ?? CACHE_RELIABILITY_ROWS;
+	return db
+		.query(
+			`WITH recent AS (
+				SELECT conversation_key AS ck, created_at_ms AS t, COALESCE(served_slug, slug) AS s,
+					json_extract(usage, '$.promptTokens') AS p, json_extract(usage, '$.cachedTokens') AS c,
+					COALESCE(json_extract(usage, '$.cachedEstimated'), 0) AS est
+				FROM ledger WHERE wasted = 0 AND error IS NULL AND created_at_ms >= $since
+				ORDER BY created_at_ms DESC LIMIT $limit),
+			seq AS (
+				SELECT s, p, c, est, t,
+					LAG(s) OVER w AS prev_s, LAG(p) OVER w AS prev_p, LAG(t) OVER w AS prev_t
+				FROM recent WINDOW w AS (PARTITION BY ck ORDER BY t))
+			SELECT s AS slug, COUNT(*) AS samples, AVG(MIN(1.0, c * 1.0 / MIN(prev_p, p))) AS hit
+			FROM seq
+			WHERE prev_s = s AND p > 1000 AND prev_p > 1000 AND t - prev_t <= $ttl AND est = 0
+			GROUP BY s`,
+		)
+		.all({ $since: sinceMs, $limit: limitRows, $ttl: opts.warmTtlMs }) as CacheReliabilityRow[];
+}
+
 export function createLedger(db: Database, cfg: RouterConfig): Ledger {
+	let cacheMemo: { atMs: number; map: Map<string, ModelCacheReliability> } | null = null;
 	// Prepared once: record() runs on every turn.
 	const insertStmt = db.query(
 		`INSERT INTO ledger (
@@ -276,6 +320,10 @@ export function createLedger(db: Database, cfg: RouterConfig): Ledger {
 	);
 	const ratioStmt = db.query("SELECT est_bytes, actual_tokens, samples FROM token_calibration WHERE tokenizer = ?");
 	const recentStmt = db.query("SELECT * FROM ledger ORDER BY created_at_ms DESC LIMIT ?");
+	const providerSpendStmt = db.query(
+		"SELECT COALESCE(SUM(COALESCE(reported_usd, predicted_usd)), 0) AS total FROM ledger WHERE created_at_ms >= ? AND COALESCE(served_slug, slug) LIKE ?",
+	);
+	const sessionStmt = db.query("SELECT * FROM ledger WHERE omp_session_id = ? AND wasted = 0 ORDER BY created_at_ms DESC LIMIT ?");
 	// What an escalated retry actually bills, per prompt token, over a window.
 	// attempt > 0 rows are the re-dispatches that followed a rejected attempt;
 	// errored ones carry no usage and are excluded.
@@ -435,6 +483,18 @@ export function createLedger(db: Database, cfg: RouterConfig): Ledger {
 			return out;
 		},
 
+		cacheReliability(slug: string): ModelCacheReliability | null {
+			const now = Date.now();
+			if (cacheMemo === null || now - cacheMemo.atMs > CACHE_RELIABILITY_MEMO_MS) {
+				const map = new Map<string, ModelCacheReliability>();
+				for (const r of queryCacheReliability(db, { warmTtlMs: cfg.hysteresis.cacheWarmTtlMs })) {
+					map.set(r.slug, { slug: r.slug, samples: r.samples, hitRate: Math.min(1, Math.max(0, r.hit)) });
+				}
+				cacheMemo = { atMs: now, map };
+			}
+			return cacheMemo.map.get(slug) ?? null;
+		},
+
 		escalationCost(windowDays: number): EscalationCost | null {
 			const now = Date.now();
 			if (escalationMemo !== null && escalationMemo.windowDays === windowDays && now - escalationMemo.atMs < ESCALATION_COST_MEMO_MS) {
@@ -459,5 +519,18 @@ export function createLedger(db: Database, cfg: RouterConfig): Ledger {
 			const rows = recentStmt.all(limit) as LedgerRow[];
 			return rows.map(toEntry);
 		},
+		providerSpendSince(slugPrefix: string, sinceMs: number): number {
+			const row = providerSpendStmt.get(sinceMs, `${slugPrefix}%`) as { total: number } | null;
+			return row?.total ?? 0;
+		},
+		latestForSession(ompSessionId: string): LedgerEntry | null {
+			if (ompSessionId === "") return null;
+			const row = sessionStmt.get(ompSessionId, 1) as LedgerRow | null;
+			return row === null ? null : toEntry(row);
+		},
+		entriesForSession(ompSessionId: string, limit: number): LedgerEntry[] {
+			if (ompSessionId === "") return [];
+			return (sessionStmt.all(ompSessionId, Math.max(1, limit)) as LedgerRow[]).map(toEntry);
+		},
 	};
 }

package/src/cost/report.ts

@@ -9,6 +9,7 @@
  */
 
 import type { Database } from "bun:sqlite";
+import { createFeedbackStore, type FeedbackCounts } from "./feedback.ts";
 
 export interface ReportTotals {
 	dispatches: number;
@@ -50,6 +51,8 @@ export interface ModelRow extends ReportRow {
 	provider: string;
 	/** Dispatch counts per tier, e.g. `{ trivial: 12, moderate: 3 }`. */
 	tiers: Record<string, number>;
+	/** User verdicts from /router good|bad on turns this model served, in the window. */
+	feedback: FeedbackCounts;
 }
 
 export interface DayRow {
@@ -71,6 +74,50 @@ export interface UsageReport {
 	models: ModelRow[];
 	tiers: ReportRow[];
 	days: DayRow[];
+	/** Mean prompt composition over rows that recorded it; null when none did. */
+	anatomy: AnatomyShare | null;
+	/** What the window would have cost on one model throughout, per configured baseline. */
+	baselines: BaselineRow[];
+}
+
+export interface BaselineRow {
+	slug: string;
+	usd: number;
+	/** 1 − routed spend ÷ baseline spend; negative when the router cost more. */
+	savedShare: number;
+}
+
+/** Resolves configured baseline slugs against a catalog lookup; unknown slugs are skipped. */
+export function baselinePrices(slugs: readonly string[], find: (slug: string) => { price: { prompt: number; completion: number; cacheRead?: number } } | undefined): BaselinePrice[] {
+	const out: BaselinePrice[] = [];
+	for (const slug of slugs) {
+		const m = find(slug);
+		if (m === undefined) continue;
+		out.push({ slug, prompt: m.price.prompt, completion: m.price.completion, ...(m.price.cacheRead === undefined ? {} : { cacheRead: m.price.cacheRead }) });
+	}
+	return out;
+}
+
+/** A baseline's prices per token (the catalog's `Price`, or a subset of it). */
+export interface BaselinePrice {
+	slug: string;
+	prompt: number;
+	completion: number;
+	cacheRead?: number;
+}
+
+/** Shares of prompt bytes, 0-1, averaged over the window's dispatches. */
+export interface AnatomyShare {
+	rows: number;
+	avgMessages: number;
+	system: number;
+	user: number;
+	assistant: number;
+	tool: number;
+	/** Tool schemas relative to prompt bytes (they ride in the tools param, not the messages). */
+	schemas: number;
+	olderHalf: number;
+	staleTool: number;
 }
 
 const USD = "COALESCE(reported_usd, predicted_usd)";
@@ -129,7 +176,10 @@ function toRow(r: RawRow, windowSpend: number): ReportRow {
  * Builds the report for the last `windowDays`. `harnessId` narrows to one
  * harness (the `X-Omp-Harness` header); empty means everything.
  */
-export function buildUsageReport(db: Database, opts: { windowDays: number; harnessId?: string; nowMs?: number }): UsageReport {
+export function buildUsageReport(
+	db: Database,
+	opts: { windowDays: number; harnessId?: string; nowMs?: number; baselines?: readonly BaselinePrice[] },
+): UsageReport {
 	const nowMs = opts.nowMs ?? Date.now();
 	const windowDays = Math.max(1, opts.windowDays);
 	const sinceMs = nowMs - windowDays * 86_400_000;
@@ -196,10 +246,12 @@ export function buildUsageReport(db: Database, opts: { windowDays: number; harne
 		rec[m.tier] = m.n;
 		mixByModel.set(m.key, rec);
 	}
+	const feedbackBySlug = createFeedbackStore(db).countsBySlug(sinceMs, harnessId);
 	const models: ModelRow[] = modelRows.map((r) => ({
 		...toRow(r, windowSpend),
 		provider: r.key.startsWith("ollama/") ? "ollama" : "openrouter",
 		tiers: mixByModel.get(r.key) ?? {},
+		feedback: feedbackBySlug.get(r.key) ?? { good: 0, bad: 0 },
 	}));
 
 	const tiers = (
@@ -221,6 +273,42 @@ export function buildUsageReport(db: Database, opts: { windowDays: number; harne
 		cacheHitRate: d.prompt_tokens > 0 ? d.cached_tokens / d.prompt_tokens : 0,
 	}));
 
+	const an = db
+		.query(
+			`SELECT COUNT(*) AS rows, AVG(json_extract(features, '$.anatomy.messages')) AS msgs,
+				AVG(json_extract(features, '$.anatomy.systemBytes')) AS sys, AVG(json_extract(features, '$.anatomy.userBytes')) AS usr,
+				AVG(json_extract(features, '$.anatomy.assistantBytes')) AS asst, AVG(json_extract(features, '$.anatomy.toolBytes')) AS tool,
+				AVG(json_extract(features, '$.toolSchemaBytes')) AS schemas,
+				AVG(json_extract(features, '$.anatomy.olderHalfBytes')) AS older, AVG(json_extract(features, '$.anatomy.staleToolBytes')) AS stale
+			 FROM ledger WHERE ${where} AND json_extract(features, '$.anatomy.messages') IS NOT NULL`,
+		)
+		.get(bind) as { rows: number; msgs: number | null; sys: number | null; usr: number | null; asst: number | null; tool: number | null; schemas: number | null; older: number | null; stale: number | null };
+	let anatomy: AnatomyShare | null = null;
+	if (an.rows > 0) {
+		const total = (an.sys ?? 0) + (an.usr ?? 0) + (an.asst ?? 0) + (an.tool ?? 0);
+		const share = (v: number | null): number => (total > 0 ? (v ?? 0) / total : 0);
+		anatomy = {
+			rows: an.rows,
+			avgMessages: Math.round(an.msgs ?? 0),
+			system: share(an.sys),
+			user: share(an.usr),
+			assistant: share(an.asst),
+			tool: share(an.tool),
+			schemas: share(an.schemas),
+			olderHalf: share(an.older),
+			staleTool: share(an.stale),
+		};
+	}
+
+	// Counterfactual: the window's tokens on one model throughout, at list
+	// price with the window's own cache hit rate (cached tokens read at the
+	// baseline's cache rate, or full price when it publishes none).
+	const baselines: BaselineRow[] = (opts.baselines ?? []).map((b) => {
+		const fresh = Math.max(0, t.prompt_tokens - t.cached_tokens);
+		const usd = fresh * b.prompt + t.cached_tokens * (b.cacheRead ?? b.prompt) + t.completion_tokens * b.completion;
+		return { slug: b.slug, usd, savedShare: usd > 0 ? 1 - t.spend / usd : 0 };
+	});
+
 	return {
 		generatedAtMs: nowMs,
 		windowDays,
@@ -244,6 +332,8 @@ export function buildUsageReport(db: Database, opts: { windowDays: number; harne
 		models,
 		tiers,
 		days,
+		anatomy,
+		baselines,
 	};
 }
 
@@ -294,6 +384,19 @@ export function reportView(r: UsageReport, opts: { maxModels?: number } = {}): R
 		`spend ${usd(t.spendUsd)} over ${num(t.dispatches)} dispatches in ${num(t.conversations)} conversations · ${usd(t.dispatches > 0 ? t.spendUsd / t.dispatches : 0)}/dispatch`,
 		`prompt ${num(t.promptTokens)} tok (cache hit ${pct(t.cacheHitRate, t.cacheEstimated)}) · completion ${num(t.completionTokens)} tok · switches ${num(t.modelSwitches)} · escalations ${num(t.escalations)} · failovers ${num(t.failovers)} · errors ${num(t.errors)} (${num(t.aborted)} aborted)`,
 	];
+	if (r.baselines.length > 0 && t.dispatches > 0) {
+		summary.push(
+			`same traffic on one model: ${r.baselines
+				.map((b) => `${b.slug} ${usd(b.usd)} (router ${b.savedShare >= 0 ? "saved" : "cost extra"} ${pct(Math.abs(b.savedShare))})`)
+				.join(" · ")}`,
+		);
+	}
+	const a = r.anatomy;
+	if (a !== null) {
+		summary.push(
+			`prompt anatomy (mean of ${num(a.rows)}): tool results ${pct(a.tool)} · assistant ${pct(a.assistant)} · user ${pct(a.user)} · system ${pct(a.system)} · tool schemas +${pct(a.schemas)} · older half ${pct(a.olderHalf)} · stale tool results ${pct(a.staleTool)} · ${num(a.avgMessages)} messages`,
+		);
+	}
 	const tables: ReportTable[] = [];
 	if (r.providers.length > 0) {
 		tables.push({
@@ -307,7 +410,7 @@ export function reportView(r: UsageReport, opts: { maxModels?: number } = {}): R
 		tables.push({
 			id: "models",
 			title: `models (top ${Math.min(maxModels, r.models.length)} of ${r.models.length} by spend)`,
-			headers: ["model", "dispatches", "spend", "share", "cache", "ttft", "speed", "tiers"],
+			headers: ["model", "dispatches", "spend", "share", "cache", "ttft", "speed", "feedback", "tiers"],
 			rows: r.models.slice(0, maxModels).map((m) => [
 				m.key,
 				num(m.dispatches),
@@ -316,6 +419,7 @@ export function reportView(r: UsageReport, opts: { maxModels?: number } = {}): R
 				pct(m.cacheHitRate, m.cacheEstimated),
 				ms(m.avgTtftMs),
 				tps(m.tokensPerSec),
+				m.feedback.good + m.feedback.bad === 0 ? "" : `+${m.feedback.good}/-${m.feedback.bad}`,
 				Object.entries(m.tiers)
 					.sort((a, b) => b[1] - a[1])
 					.map(([k, v]) => `${k}:${v}`)

package/src/cost/types.ts

@@ -200,9 +200,24 @@ export interface ModelLatency {
 	tokensPerSec: number;
 }
 
+/**
+ * How often a model's prompt cache actually hit when the router expected it
+ * warm: the previous kept turn of the conversation was on the same model
+ * within `hysteresis.cacheWarmTtlMs`. Provider-side misses (a model whose
+ * cache is flaky, or absent) show up here as a low rate. Router-estimated
+ * cache counts (Ollama) are excluded: they are constructed, not observed.
+ */
+export interface ModelCacheReliability {
+	slug: string;
+	samples: number;
+	/** Mean cached / expected-cached over those samples, 0-1. */
+	hitRate: number;
+}
+
 export interface LedgerSignals {
 	trust: ModelTrust | null;
 	latency: ModelLatency | null;
+	cache?: ModelCacheReliability | null;
 }
 
 /** Measured price of a probe escalation: what the retry billed per prompt token of the failed turn. */
@@ -241,7 +256,20 @@ export interface Ledger {
 	 * escalation-cost term in candidate scoring is inert without it.
 	 */
 	escalationCost?(windowDays: number): EscalationCost | null;
+	/**
+	 * Observed cache hit rate when a warm cache was expected (see
+	 * ModelCacheReliability). Null until any sample exists. Optional so fakes
+	 * need not implement it; the stay/switch comparison assumes a reliable
+	 * cache without it.
+	 */
+	cacheReliability?(slug: string): ModelCacheReliability | null;
 	/** Observed chars-per-token ratio for a tokenizer family; null until calibrated. */
 	tokenRatio(tokenizer: string): number | null;
 	recentEntries(limit: number): LedgerEntry[];
+	/** Spend since an instant on slugs with a prefix (`ollama/`), for provider-level reconciliation. Optional. */
+	providerSpendSince?(slugPrefix: string, sinceMs: number): number;
+	/** Newest kept (non-wasted) entry for an omp session, for /router why and feedback. Optional so fakes need not implement it. */
+	latestForSession?(ompSessionId: string): LedgerEntry | null;
+	/** Newest entries for an omp session, newest first. Optional. */
+	entriesForSession?(ompSessionId: string, limit: number): LedgerEntry[];
 }

package/src/router/candidates.ts

@@ -111,12 +111,21 @@ function expectedWaitMs(latency: ModelLatency, expectedCompletionTokens: number)
  * tiny cost and capped at LATENCY_EXCESS_CAP, so the model stays cheapest. That is
  * `filters.maxExpectedWaitMs`'s job — a hard drop, applied in buildCandidates.
  */
-function latencyMultiplier(latency: ModelLatency | null, filters: FilterConfig, expectedCompletionTokens: number): number {
-	if (latency === null || filters.latencyWeight <= 0 || latency.samples < filters.latencyMinSamples) return 1;
+/**
+ * The latency weight in force for a turn: the continuation weight on a
+ * tool-result continuation when one is configured, else the general one.
+ * A person waits on first token only when the turn is theirs.
+ */
+export function latencyWeightFor(filters: FilterConfig, isToolResultContinuation: boolean): number {
+	return isToolResultContinuation && filters.latencyWeightContinuation !== undefined ? filters.latencyWeightContinuation : filters.latencyWeight;
+}
+
+function latencyMultiplier(latency: ModelLatency | null, filters: FilterConfig, expectedCompletionTokens: number, weight = filters.latencyWeight): number {
+	if (latency === null || weight <= 0 || latency.samples < filters.latencyMinSamples) return 1;
 	const waitMs = expectedWaitMs(latency, expectedCompletionTokens);
 	const refWaitMs = filters.latencyReferenceMs + (expectedCompletionTokens / filters.latencyReferenceTokensPerSec) * 1000;
 	const excess = refWaitMs > 0 ? Math.max(0, (waitMs - refWaitMs) / refWaitMs) : 0;
-	return 1 + filters.latencyWeight * Math.min(excess, LATENCY_EXCESS_CAP);
+	return 1 + weight * Math.min(excess, LATENCY_EXCESS_CAP);
 }
 
 export function buildCandidates(args: BuildCandidatesArgs): { candidates: Candidate[]; rejected: Rejection[] } {
@@ -320,7 +329,7 @@ export function buildCandidates(args: BuildCandidatesArgs): { candidates: Candid
 		// 20% of the time really costs ~25% more in retries. Latency does the same
 		// for slowness (TTFT over the reference). qualityExponent 0 makes this
 		// "cheapest above the floor"; the floor does the quality work.
-		const latencyMult = latencyMultiplier(latency, filters, expectedCompletionTokens);
+		const latencyMult = latencyMultiplier(latency, filters, expectedCompletionTokens, latencyWeightFor(filters, features.isToolResultContinuation));
 		// Escalation-cost term: the trust divisor prices a failure as a retry of
 		// THIS model, but a probe escalation re-dispatches the whole prompt on
 		// the next tier's model — measured at ~700x a cheap model's own turn cost.

package/src/router/classify.ts

@@ -10,6 +10,7 @@ import type { Ledger } from "../cost/types.ts";
 import { estimateTokens } from "../tokens/estimate.ts";
 import type { UpstreamClient } from "../upstream/types.ts";
 import { sha256Hex } from "../util/hash.ts";
+import { loadLearnedModel, predictRisk } from "./learned.ts";
 import type { NormRequest, ReasoningLevel } from "../wire/types.ts";
 import type { Classification, Features, TaskType, Tier } from "./types.ts";
 
@@ -303,6 +304,15 @@ export async function classify(
 ): Promise<Classification> {
 	const heuristic = scoreHeuristic(f, cfg);
 	const cc = cfg.classifier;
+	// Advisory learned risk: recorded beside the decision, never acted on here.
+	if (cc.learnedModelPath !== "") {
+		const model = await loadLearnedModel(cc.learnedModelPath);
+		if (model !== null) {
+			const risk = predictRisk(model, f);
+			heuristic.learnedRisk = risk;
+			heuristic.reasons.push(`learned: p(escalate)=${risk.toFixed(3)}`);
+		}
+	}
 	if (cc.ambiguityThreshold <= 0 || heuristic.confidence >= cc.ambiguityThreshold) return heuristic;
 
 	const digest = buildDigest(req, f);

package/src/router/features.ts

@@ -8,7 +8,7 @@
  */
 
 import type { NormMessage, NormRequest } from "../wire/types.ts";
-import type { Features } from "./types.ts";
+import type { Features, PromptAnatomy } from "./types.ts";
 
 /**
  * Complexity signals. Deliberately small: each hit pushes the turn toward a
@@ -224,6 +224,24 @@ export function extractFeatures(req: NormRequest, promptTokens: number): Feature
 		codeBlocks === 0 &&
 		(terminators === null ? 0 : terminators.length) <= 1;
 
+	// Prompt anatomy: where the bytes sit. Cheap (one pass over textBytes) and
+	// content-free, so it is safe to record on every row.
+	const anatomy: PromptAnatomy = { messages: 0, systemBytes: 0, userBytes: 0, assistantBytes: 0, toolBytes: 0, olderHalfBytes: 0, staleToolBytes: 0 };
+	const nonSystem = messages.filter((m) => m.role !== "system");
+	const olderHalfEnd = Math.floor(nonSystem.length / 2);
+	const staleEnd = Math.max(0, nonSystem.length - 20);
+	nonSystem.forEach((m, i) => {
+		if (i < olderHalfEnd) anatomy.olderHalfBytes += m.textBytes;
+		if (m.role === "tool" && i < staleEnd) anatomy.staleToolBytes += m.textBytes;
+	});
+	for (const m of messages) {
+		anatomy.messages++;
+		if (m.role === "system") anatomy.systemBytes += m.textBytes;
+		else if (m.role === "user") anatomy.userBytes += m.textBytes;
+		else if (m.role === "assistant") anatomy.assistantBytes += m.textBytes;
+		else anatomy.toolBytes += m.textBytes;
+	}
+
 	return {
 		promptTokens,
 		newContentTokens,
@@ -246,5 +264,6 @@ export function extractFeatures(req: NormRequest, promptTokens: number): Feature
 		requestedReasoning: req.reasoning,
 		questionCount,
 		isTerseInstruction,
+		anatomy,
 	};
 }

package/src/router/index.ts

@@ -52,7 +52,7 @@ export function createRouter(deps: RouterDeps): Router {
 	return {
 		async route(
 			req: NormRequest,
-			opts: { attempt: number; escalateFrom?: Tier; excludeSlugs?: readonly string[] },
+			opts: { attempt: number; escalateFrom?: Tier; excludeSlugs?: readonly string[]; forceTier?: Tier; forceSlug?: string },
 		): Promise<Decision> {
 			const state = conversations.get(req.conversationKey) ?? conversations.load(req.conversationKey);
 			const snapshot = await catalog.get();
@@ -78,6 +78,16 @@ export function createRouter(deps: RouterDeps): Router {
 					score: 1,
 					reasons: [`escalated from ${opts.escalateFrom} after attempt ${opts.attempt - 1} was rejected`],
 				};
+			} else if (opts.forceTier !== undefined) {
+				// A session override from omp: the user chose the tier for a while.
+				classification = {
+					tier: opts.forceTier,
+					task: classifyTask(features),
+					confidence: 1,
+					source: "forced",
+					score: 1,
+					reasons: [`tier ${opts.forceTier} forced by session override (/router tier)`],
+				};
 			} else {
 				classification = await classify(req, features, config, { upstream, ledger, catalog });
 			}
@@ -93,6 +103,7 @@ export function createRouter(deps: RouterDeps): Router {
 				cfg: config,
 				nowMs: Date.now(),
 				...(opts.excludeSlugs === undefined ? {} : { excludeSlugs: opts.excludeSlugs }),
+				...(opts.forceSlug === undefined ? {} : { forceSlug: opts.forceSlug }),
 			});
 		},
 	};