auto-model-router 0.2.32 → 0.3.0

package/src/router/select.ts

@@ -183,6 +183,8 @@ export function select(args: SelectArgs): Decision {
 	//        Overshooting buys several byte-stable turns per plan change.
 	let compactionPlan: CompactionEdit[] = [];
 	let promptTokensSaved = 0;
+	let compactionSavedBytes = 0;
+	let compactionPlanTokens = state.compactionPlanTokens ?? 0;
 	let effFeatures = features;
 	if (cfg.compaction.enabled && req.promptBytes > 0 && features.promptTokens > 0) {
 		const bytesPerToken = req.promptBytes / features.promptTokens;
@@ -197,8 +199,19 @@ export function select(args: SelectArgs): Decision {
 		const overBudget = compactedTokens > cfg.compaction.budgetTokens;
 		const overWindow =
 			cfg.compaction.fitToWindow && compactedTokens * headroom + EXPECTED_COMPLETION_TOKENS > profile.contextWindow;
+		// Rationing: when the budget is unreachable (the observed case — compacted
+		// prompts of 100-160k against a 40k budget) `overBudget` is true on every
+		// turn, and a plan gains an edit the moment a tool result ages out of the
+		// protected window, so `floorRatio` never gets to hold a plan. Instead,
+		// extend an existing plan only once the compacted prompt has grown by
+		// `replanGrowthRatio` since it was made. Never rations the window fit.
+		const rationed =
+			cfg.compaction.replanGrowthRatio > 1 &&
+			carried.length > 0 &&
+			compactionPlanTokens > 0 &&
+			compactedTokens < compactionPlanTokens * cfg.compaction.replanGrowthRatio;
 		let plan: CompactionResult = { edits: carried, savedBytes: carriedSavedBytes };
-		if (overBudget || overWindow) {
+		if (overWindow || (overBudget && !rationed)) {
 			const targets: number[] = [];
 			// Overshoot the budget so the next re-plan is several turns away.
 			if (overBudget) targets.push(Math.max(1, Math.floor(cfg.compaction.budgetTokens * cfg.compaction.floorRatio)));
@@ -208,12 +221,18 @@ export function select(args: SelectArgs): Decision {
 		}
 		if (plan.edits.length > 0) {
 			compactionPlan = [...plan.edits];
+			compactionSavedBytes = plan.savedBytes;
 			promptTokensSaved = tokensOf(plan.savedBytes);
 			effFeatures = { ...features, promptTokens: features.promptTokens - promptTokensSaved };
 			const added = plan.edits.length - carried.length;
+			// A plan that gained edits was made at THIS compacted size; a carried
+			// plan keeps the size it was made at, so growth accrues against it.
+			if (added > 0 || compactionPlanTokens === 0) compactionPlanTokens = effFeatures.promptTokens;
 			reasons.push(
-				`compaction: ${plan.edits.length} tool result(s) shrunk (${carried.length} carried, ${added} new), ~${promptTokensSaved} tokens saved (prompt ${features.promptTokens}→${effFeatures.promptTokens})`,
+				`compaction: ${plan.edits.length} tool result(s) shrunk (${carried.length} carried, ${added} new), ~${promptTokensSaved} tokens saved (prompt ${features.promptTokens}→${effFeatures.promptTokens})${rationed ? " [re-plan rationed]" : ""}`,
 			);
+		} else {
+			compactionPlanTokens = 0;
 		}
 	}
 
@@ -268,6 +287,19 @@ export function select(args: SelectArgs): Decision {
 	// The task type selects the quality axis and capability filters; the tier
 	// still bounds cost (task selects, tier budgets).
 	const warmSlug = cacheWarm ? state.cacheWarmSlug : null;
+	// Pre-fetch trust/latency signals for all candidate slugs in one batch
+	// query per signal kind, instead of per-model individual lookups.
+	const candidateSignals =
+		ledger !== null && snapshot.models.length > 0
+			? ledger.signals?.(snapshot.models.map((m) => m.slug), cfg.filters.trustScopedByHarness ? req.harnessId : undefined)
+			: undefined;
+	// What an escalated retry has actually been billing per prompt token, for
+	// the escalation-cost term in candidate scoring. Read once per turn; null
+	// (term inert) when the weight is 0 or the ledger has too few samples.
+	const escalationUsdPerPromptToken =
+		cfg.filters.escalationCostWeight > 0
+			? (ledger?.escalationCost?.(cfg.ledger.blendWindowDays)?.usdPerPromptToken ?? null)
+			: null;
 	const build = (t: Tier, relaxLevel = 0): { candidates: Candidate[]; rejected: Rejection[] } =>
 		buildCandidates({
 			req,
@@ -281,12 +313,13 @@ export function select(args: SelectArgs): Decision {
 			warmSlug,
 			relaxLevel,
 			...(args.excludeSlugs === undefined ? {} : { excludeSlugs: args.excludeSlugs }),
+			...(candidateSignals === undefined ? {} : { signals: candidateSignals }),
+			...(escalationUsdPerPromptToken === null ? {} : { escalationUsdPerPromptToken }),
 		});
 	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);
@@ -354,17 +387,26 @@ export function select(args: SelectArgs): Decision {
 		if (warm !== undefined) {
 			const warmPrice = priceAt(warm.model, Math.max(1, state.lastPromptTokens));
 			const newPrice = priceAt(chosen.model, Math.max(1, effFeatures.promptTokens));
-			const stayCost = state.lastPromptTokens * (warmPrice.cacheRead ?? warmPrice.prompt);
-			const switchCost = effFeatures.promptTokens * (newPrice.prompt + (newPrice.cacheWrite ?? 0));
+			const stayWarm = state.lastPromptTokens * (warmPrice.cacheRead ?? warmPrice.prompt);
+			const switchCold = effFeatures.promptTokens * (newPrice.prompt + (newPrice.cacheWrite ?? 0));
+			const newWarm = effFeatures.promptTokens * (newPrice.cacheRead ?? newPrice.prompt);
+			// Amortise over the horizon: H turns of staying warm against one cold
+			// switch plus H−1 turns warm on the new model. H = 1 is the one-turn
+			// comparison, which kept a 25x-priced model warm for a 33-dispatch run
+			// because no single turn could recoup the cold write on its own.
+			const horizon = Math.max(1, cfg.hysteresis.switchHorizonTurns);
+			const stayCost = horizon * stayWarm;
+			const switchCost = switchCold + (horizon - 1) * newWarm;
+			const over = horizon > 1 ? ` over ${horizon} turns` : "";
 			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})`,
+					`cache: switch ${warmSlug} → ${chosen.model.slug} (stay $${stayCost.toFixed(4)} > switch $${switchCost.toFixed(4)} × ${cfg.hysteresis.switchMargin}${over})`,
 				);
 			} else {
 				chosen = warm;
 				sticky = true;
 				reasons.push(
-					`cache: keeping warm ${warmSlug} (stay $${stayCost.toFixed(4)} ≤ switch $${switchCost.toFixed(4)} × ${cfg.hysteresis.switchMargin})`,
+					`cache: keeping warm ${warmSlug} (stay $${stayCost.toFixed(4)} ≤ switch $${switchCost.toFixed(4)} × ${cfg.hysteresis.switchMargin}${over})`,
 				);
 			}
 		}
@@ -377,6 +419,7 @@ export function select(args: SelectArgs): Decision {
 		perDayUsd: profile.budget?.perDayUsd ?? cfg.budget.perDayUsd,
 		onExceeded: profile.budget?.onExceeded ?? cfg.budget.onExceeded,
 	};
+	const daySpend = budget.perDayUsd !== undefined ? (ledger?.spendSince(nowMs - DAY_MS, req.harnessId) ?? 0) : 0;
 	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}`;
@@ -388,7 +431,6 @@ export function select(args: SelectArgs): Decision {
 			// 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}`;
 			}
@@ -425,6 +467,9 @@ export function select(args: SelectArgs): Decision {
 	const fallbacks: string[] = [];
 	for (const c of candidates) {
 		if (c.model.slug === chosen.model.slug) continue;
+		// The cascade is served by ONE upstream: an OpenRouter `models[]` array
+		// cannot name an Ollama model and vice versa.
+		if (c.model.provider !== chosen.model.provider) continue;
 		fallbacks.push(c.model.slug);
 		if (fallbacks.length >= 2) break;
 	}
@@ -475,6 +520,8 @@ export function select(args: SelectArgs): Decision {
 		cacheBreakpointMessageIndices,
 		compactionPlan,
 		promptTokensSaved,
+		compactionSavedBytes,
+		compactionPlanTokens,
 		reasoning,
 		maxTokens,
 		stripAssistantReasoning,

package/src/router/state.ts

@@ -31,6 +31,7 @@ interface Row {
 	context_version: string | null;
 	context_fetched_at_ms: number;
 	compaction_plan: string | null;
+	compaction_plan_tokens: number;
 	updated_at_ms: number;
 }
 
@@ -51,6 +52,7 @@ function toState(row: Row): ConversationState {
 		contextVersion: row.context_version,
 		contextFetchedAtMs: row.context_fetched_at_ms,
 		compactionPlan: row.compaction_plan === null ? null : (JSON.parse(row.compaction_plan) as CompactionEdit[]),
+		compactionPlanTokens: row.compaction_plan_tokens,
 		updatedAtMs: row.updated_at_ms,
 	};
 }
@@ -69,10 +71,10 @@ export function createConversationStore(db: Database): ConversationStore {
 		INSERT INTO conversations (
 			key, session_id, turn, current_slug, current_tier, sticky_until_turn,
 			last_prompt_tokens, cache_warm_slug, cache_warm_at_ms,
-			context_version, context_fetched_at_ms, compaction_plan, updated_at_ms
+			context_version, context_fetched_at_ms, compaction_plan, compaction_plan_tokens, updated_at_ms
 		) VALUES ($key, $sessionId, $turn, $currentSlug, $currentTier, $stickyUntilTurn,
 			$lastPromptTokens, $cacheWarmSlug, $cacheWarmAtMs,
-			$contextVersion, $contextFetchedAtMs, $compactionPlan, $updatedAtMs)
+			$contextVersion, $contextFetchedAtMs, $compactionPlan, $compactionPlanTokens, $updatedAtMs)
 		ON CONFLICT(key) DO UPDATE SET
 			session_id = excluded.session_id,
 			turn = excluded.turn,
@@ -85,6 +87,7 @@ export function createConversationStore(db: Database): ConversationStore {
 			context_version = excluded.context_version,
 			context_fetched_at_ms = excluded.context_fetched_at_ms,
 			compaction_plan = excluded.compaction_plan,
+			compaction_plan_tokens = excluded.compaction_plan_tokens,
 			updated_at_ms = excluded.updated_at_ms
 	`);
 	// Read-modify-write in JS lost money: an aborted or failed dispatch is still
@@ -133,6 +136,7 @@ export function createConversationStore(db: Database): ConversationStore {
 				$stickyUntilTurn: state.stickyUntilTurn,
 				$lastPromptTokens: state.lastPromptTokens,
 				$compactionPlan: state.compactionPlan === null ? null : JSON.stringify(state.compactionPlan),
+				$compactionPlanTokens: state.compactionPlanTokens ?? 0,
 				$cacheWarmSlug: state.cacheWarmSlug,
 				$cacheWarmAtMs: state.cacheWarmAtMs,
 				$contextVersion: state.contextVersion,

package/src/router/tier-plan.ts

@@ -13,17 +13,26 @@
  *
  * The fix is to treat the floors as relative when the absolute ones cannot be
  * met. Rank the available scored models, split them into four quantile bands,
- * and take each band's lower bound as that tier's adaptive floor. The effective
- * floor is then `min(configured, adaptive)`:
+ * and take each band's lower bound as that tier's adaptive floor. The adaptive
+ * floor applies ONLY when the configured one leaves the tier thin:
  *
- *  - A healthy catalog keeps the configured floors verbatim (the adaptive floor
- *    sits above them, so `min` picks the configured value) — no behaviour change.
- *  - A narrowed catalog falls back to the adaptive floor, so `hard` still gets
- *    the best quartile of what is available instead of nothing at all.
+ *  - When at least `MIN_FLOOR_ADMITS` rankable models meet the configured
+ *    floor, the configured floor stands verbatim — no behaviour change.
+ *  - When fewer do (a narrowed catalog), the effective floor is
+ *    `min(configured, adaptive)`, so `hard` still gets the best quartile of
+ *    what is available instead of nothing at all.
  *
- * `min` is deliberate: adaptive floors may only RELAX a floor, never tighten
- * one. Tightening would let a rich catalog silently price us out of a tier the
- * operator explicitly configured.
+ * The thinness gate is load-bearing. An earlier version applied `min` always,
+ * on the assumption that a healthy catalog's bands sit above the configured
+ * floors. They do not: a wide catalog carries a long tail of weak scored models
+ * (measured on 347 key-admitted models: coding p50 = 45.8 against a configured
+ * `moderate` floor of 60, p75 = 59.9 against `hard`'s 72), so `min` silently
+ * relaxed every tier and a coding-50 model won `moderate` — then escalated 14x
+ * more often than the model the configured floor would have picked.
+ *
+ * Adaptive floors may only RELAX a floor, never tighten one. Tightening would
+ * let a rich catalog silently price us out of a tier the operator explicitly
+ * configured.
  *
  * Unscored models are never imputed a score (see `candidates.ts`), so a catalog
  * with no benchmarks at all yields all-zero floors: every tier admits every
@@ -46,10 +55,21 @@ export interface TierPlan {
 	floors: Record<QualityAxis, AxisFloors>;
 	/** How many available models carried a score on each axis. */
 	scoredCount: Record<QualityAxis, number>;
+	/** Rankable models' scores per axis, ascending — what the floors were cut from. */
+	scores: Record<QualityAxis, readonly number[]>;
 	/** Adaptive input-price ceiling ($/Mtok) per tier, from the catalog's price spread. */
 	priceCeilings: Record<Tier, number>;
 }
 
+/**
+ * Rankable models a configured floor must admit for it to stand as written.
+ * Below this the tier is "thin" and the adaptive band may relax the floor.
+ * Three, not one: a lone survivor leaves no same-tier failover and no
+ * meaningful cost ranking, which is the narrowed-catalog situation this whole
+ * module exists to escape.
+ */
+export const MIN_FLOOR_ADMITS = 3;
+
 /**
  * Models that could plausibly serve a turn, for ranking purposes: the built-in
  * denials (floating aliases, batch endpoints, stealth, meta-routers) and free
@@ -121,6 +141,7 @@ function bandCeilings(ascending: readonly number[]): Record<Tier, number> {
 export function computeTierPlan(models: readonly CatalogModel[], cfg: RouterConfig): TierPlan {
 	const floors: Record<string, AxisFloors> = {};
 	const scoredCount: Record<string, number> = {};
+	const axisScores: Record<string, readonly number[]> = {};
 	const includeFree = cfg.filters.includeFree;
 
 	for (const axis of AXES) {
@@ -134,6 +155,7 @@ export function computeTierPlan(models: readonly CatalogModel[], cfg: RouterConf
 		scores.sort((a, b) => a - b);
 		floors[axis] = bandFloors(scores);
 		scoredCount[axis] = scores.length;
+		axisScores[axis] = scores;
 	}
 	// Input prices ($/Mtok) of the rankable models, ascending, for the ceilings.
 	const prices: number[] = [];
@@ -146,10 +168,24 @@ export function computeTierPlan(models: readonly CatalogModel[], cfg: RouterConf
 	return {
 		floors: floors as Record<QualityAxis, AxisFloors>,
 		scoredCount: scoredCount as Record<QualityAxis, number>,
+		scores: axisScores as Record<QualityAxis, readonly number[]>,
 		priceCeilings: bandCeilings(prices),
 	};
 }
 
+/** Rankable models scoring at least `floor` on an axis. `scores` is ascending. */
+export function countAdmitted(scores: readonly number[], floor: number): number {
+	// Binary search for the first score >= floor; everything after it qualifies.
+	let lo = 0;
+	let hi = scores.length;
+	while (lo < hi) {
+		const mid = (lo + hi) >> 1;
+		if ((scores[mid] ?? 0) < floor) lo = mid + 1;
+		else hi = mid;
+	}
+	return scores.length - lo;
+}
+
 /**
  * Memoized per snapshot object AND config object. A catalog refresh installs a
  * fresh `CatalogSnapshot`, which misses the cache and recomputes the plan — so
@@ -173,8 +209,9 @@ export function tierPlanFor(snapshot: CatalogSnapshot, cfg: RouterConfig): TierP
 }
 
 /**
- * The floor to actually enforce for a tier on an axis. Never tightens the
- * configured floor; only relaxes it when the available catalog cannot meet it.
+ * The floor to actually enforce for a tier on an axis. The configured floor
+ * stands whenever at least MIN_FLOOR_ADMITS rankable models meet it; only a
+ * thin tier is relaxed to the adaptive band, and never tightened.
  */
 export function effectiveQualityFloor(
 	configured: number,
@@ -182,6 +219,7 @@ export function effectiveQualityFloor(
 	axis: QualityAxis,
 	plan: TierPlan,
 ): number {
+	if (countAdmitted(plan.scores[axis], configured) >= MIN_FLOOR_ADMITS) return configured;
 	const adaptive = plan.floors[axis][tier];
 	return Math.min(configured, adaptive);
 }

package/src/router/types.ts

@@ -178,6 +178,12 @@ export interface ConversationState {
 	 * the prompt cache and un-saves the tokens. Fresh planning only extends it.
 	 */
 	compactionPlan: CompactionEdit[] | null;
+	/**
+	 * Compacted prompt size (tokens) at which `compactionPlan` was last made.
+	 * Re-planning is rationed against growth from this point
+	 * (`compaction.replanGrowthRatio`). 0 / absent = unknown.
+	 */
+	compactionPlanTokens?: number;
 	/** When that block was fetched, for the staleness TTL. */
 	contextFetchedAtMs: number;
 	updatedAtMs: number;
@@ -247,6 +253,10 @@ export interface Decision {
 	compactionPlan: CompactionEdit[];
 	/** Estimated prompt tokens removed by `compactionPlan`, for the ledger. */
 	promptTokensSaved: number;
+	/** Prompt bytes `compactionPlan` removes; the dispatched size is `req.promptBytes` minus this (plus any context block). */
+	compactionSavedBytes: number;
+	/** Compacted prompt size the plan was (last) made at, persisted for re-plan rationing. */
+	compactionPlanTokens: number;
 	reasoning: ReasoningLevel | undefined;
 	maxTokens: number | undefined;
 	stripAssistantReasoning: boolean;

package/src/server/http.ts

@@ -1,15 +1,15 @@
 import { mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 import type { Server } from "bun";
-import { createCatalog } from "../catalog/openrouter-catalog.ts";
+import { createProviders } from "./providers.ts";
 import { createBridgeFromConfig } from "../context/index.ts";
 import { createLedger } from "../cost/ledger.ts";
+import { buildUsageReport } from "../cost/report.ts";
 import type { Ledger, ModelTrust } from "../cost/types.ts";
 import { createRouter } from "../router/index.ts";
 import { createConversationStore } from "../router/state.ts";
-import { createOpenRouterClient } from "../upstream/openrouter.ts";
 import { UpstreamError } from "../upstream/types.ts";
-import { apiKeySource } from "../config/load.ts";
+import { apiKeySource, ollamaKeySource } from "../config/load.ts";
 import { routerConfigPath } from "../cli/config-cmd.ts";
 import { watchConfig } from "../config/hot-reload.ts";
 import type { RouterConfig } from "../config/types.ts";
@@ -172,8 +172,7 @@ export function startServer(cfg: RouterConfig): StartedServer {
 	if (cfg.ledger.path !== ":memory:") mkdirSync(dirname(cfg.ledger.path), { recursive: true });
 	const db = openDb(cfg.ledger.path);
 	const ledger = createLedger(db, cfg);
-	const upstream = createOpenRouterClient(cfg);
-	const catalog = createCatalog(cfg, upstream, db);
+	const { upstream, catalog, ollama, ollamaUsage } = createProviders(cfg, db, log);
 	const conversations = createConversationStore(db);
 	const router = createRouter({ config: cfg, catalog, ledger, conversations, upstream });
 	const context = createBridgeFromConfig(cfg, db);
@@ -189,7 +188,7 @@ export function startServer(cfg: RouterConfig): StartedServer {
 		routerConfigPath(),
 		cfg,
 		pinned,
-		["server", "openrouter", "context", "ledger"],
+		["server", "openrouter", "ollama", "context", "ledger"],
 		{
 			onReload: ({ changed }) => {
 				log.info("config reloaded", { changed: changed.join(", ") });
@@ -211,6 +210,14 @@ export function startServer(cfg: RouterConfig): StartedServer {
 	if (cfg.openrouter.apiKey === "") {
 		log.warn("OPENROUTER_API_KEY is not set; /v1/chat/completions will fail at dispatch time");
 	}
+	if (ollama !== null) {
+		log.info("ollama cloud upstream enabled", {
+			baseUrl: cfg.ollama.baseUrl,
+			// Provenance only; never the key itself.
+			apiKeySource: ollamaKeySource(cfg).source,
+			costBias: cfg.ollama.costBias,
+		});
+	}
 
 	// Warm the catalog without blocking listen; the first request may race it,
 	// which CatalogSource.get() already serializes.
@@ -281,6 +288,10 @@ export function startServer(cfg: RouterConfig): StartedServer {
 		try {
 			normReq = parseChatRequest(await req.json(), req.headers);
 		} catch (err) {
+			// The slot was acquired before parsing; a rejected body never reaches
+			// runTurn's `finally`, so it must be released here or every malformed
+			// request permanently consumes one of maxConcurrentTurns.
+			releaseTurn();
 			if (err instanceof WireErrorException) return wireErrorResponse(err.wireError);
 			return wireErrorResponse({
 				status: 400,
@@ -358,6 +369,15 @@ export function startServer(cfg: RouterConfig): StartedServer {
 				if (req.method === "GET" && url.pathname === "/v1/router/stats") {
 					return json(computeStats(ledger));
 				}
+				if (req.method === "GET" && url.pathname === "/v1/router/report") {
+					// Usage analytics for `/router report` and the CLI: bounded window,
+					// optional harness scope (the X-Omp-Harness header value).
+					const rawDays = url.searchParams.get("days");
+					const parsedDays = rawDays === null ? 7 : Number.parseInt(rawDays, 10);
+					const windowDays = Number.isInteger(parsedDays) ? Math.min(Math.max(parsedDays, 1), 365) : 7;
+					const harnessId = url.searchParams.get("harness") ?? "";
+					return json(buildUsageReport(db, { windowDays, harnessId }));
+				}
 				if (req.method === "GET" && url.pathname === "/v1/router/decisions") {
 					const rawLimit = url.searchParams.get("limit");
 					const parsed = rawLimit === null ? 50 : Number.parseInt(rawLimit, 10);
@@ -375,6 +395,23 @@ export function startServer(cfg: RouterConfig): StartedServer {
 						agentdox: context.enabled
 							? { url: cfg.context.baseUrl, defaultScope: cfg.context.defaultScope, recordTurns: cfg.context.recordTurns }
 							: null,
+						// Never the key. `available` is the circuit breaker: false while a
+						// 402/429 cooldown routes every turn around Ollama.
+						ollama:
+							ollama === null
+								? null
+								: {
+										baseUrl: cfg.ollama.baseUrl,
+										apiKeySource: ollamaKeySource(cfg).source,
+										models: catalog.ollamaModels?.().length ?? 0,
+										available: ollama.available(),
+										cooldownUntilMs: ollama.cooldownUntilMs(),
+										lastTrip: ollama.lastTrip(),
+										// Plan usage as ollama.com reports it (share of included monthly
+										// credits) and the cost multiplier currently in force.
+										usage: ollamaUsage.peek(),
+										costBias: { configured: cfg.ollama.costBias, effective: catalog.ollamaBias?.() ?? cfg.ollama.costBias, biasUntilUsage: cfg.ollama.biasUntilUsage },
+									},
 						catalog: snap === null
 							? null
 							: {
@@ -382,6 +419,10 @@ export function startServer(cfg: RouterConfig): StartedServer {
 									fetchedAtMs: snap.fetchedAtMs,
 									ageMs: Date.now() - snap.fetchedAtMs,
 									keyScoped: snap.keyScoped === true,
+									// Non-null after a refresh kept < half the previous models;
+									// the one signal that the key narrowed (or upstream blipped)
+									// and routing is now on whatever survived.
+									shrink: catalog.lastShrink?.() ?? null,
 								},
 					});
 				}

package/src/server/providers.ts

@@ -0,0 +1,54 @@
+/**
+ * Upstream + catalog assembly shared by the server and the CLIs, so `models`
+ * and `explain` see exactly the catalog a turn would route over — including
+ * Ollama Cloud when it is enabled.
+ */
+
+import type { Database } from "bun:sqlite";
+import { createCompositeCatalog } from "../catalog/composite.ts";
+import { createOllamaCatalog } from "../catalog/ollama-catalog.ts";
+import { createCatalog } from "../catalog/openrouter-catalog.ts";
+import type { CatalogSource } from "../catalog/types.ts";
+import type { RouterConfig } from "../config/types.ts";
+import { createMultiUpstream } from "../upstream/multi.ts";
+import { createOllamaClient, type OllamaClient } from "../upstream/ollama.ts";
+import { createOllamaUsageSource, NO_USAGE, type OllamaUsageSource } from "../upstream/ollama-usage.ts";
+import { createOpenRouterClient } from "../upstream/openrouter.ts";
+import type { UpstreamClient } from "../upstream/types.ts";
+import { createLogger, type Logger } from "../util/log.ts";
+
+export interface Providers {
+	upstream: UpstreamClient;
+	catalog: CatalogSource & { ollamaModels?(): unknown[]; ollamaBias?(): number };
+	/** Non-null when Ollama Cloud is enabled; carries the circuit breaker. */
+	ollama: OllamaClient | null;
+	/** Plan usage reader; inert without a key. */
+	ollamaUsage: OllamaUsageSource;
+}
+
+export function createProviders(cfg: RouterConfig, db: Database, log: Logger = createLogger(cfg.logLevel)): Providers {
+	const openrouter = createOpenRouterClient(cfg);
+	const openrouterCatalog = createCatalog(cfg, openrouter, db);
+	if (!cfg.ollama.enabled) return { upstream: openrouter, catalog: openrouterCatalog, ollama: null, ollamaUsage: NO_USAGE };
+	// Ollama Cloud is a second upstream ranked in the same catalog: `ollama/…`
+	// slugs dispatch to it, everything else to OpenRouter.
+	const ollama = createOllamaClient(cfg);
+	// Plan usage lives on ollama.com whichever base URL dispatches; it needs the
+	// key, so the daemon path without `/login ollama-cloud` keeps a static bias.
+	const ollamaUsage = createOllamaUsageSource({
+		apiKey: cfg.ollama.apiKey,
+		pollMs: cfg.ollama.usagePollMs,
+		timeoutMs: Math.min(cfg.ollama.timeoutMs, 15_000),
+		log,
+	});
+	return {
+		upstream: createMultiUpstream(openrouter, ollama),
+		catalog: createCompositeCatalog(openrouterCatalog, createOllamaCatalog(cfg.ollama, log), ollama, {
+			costBias: cfg.ollama.costBias,
+			biasUntilUsage: cfg.ollama.biasUntilUsage,
+			usage: ollamaUsage,
+		}),
+		ollama,
+		ollamaUsage,
+	};
+}