one-code-extension 0.1.4 → 0.3.0

package/extensions/lib/model-facts.ts

@@ -0,0 +1,162 @@
+/**
+ * Facts about models that pi's catalog strips: release date and tool-calling
+ * support, from models.dev, bundled as `model-facts.generated.json` and refreshed
+ * with each pi bump (`scripts/gen-model-facts.mjs`). Pure: reads one
+ * JSON file lazily, no pi imports.
+ *
+ * Why release dates: the tier price floors are absolute dollars calibrated on US
+ * vendor prices, and nothing else in the classifier knew a model's generation,
+ * so on a ~10x-cheaper vendor a boundary-priced 2025 model (deepseek-r1-0528)
+ * beat a 2026 model priced below the floor (V4 Flash). A model's *generation* is
+ * measured against its vendor family's newest release, never against today, so
+ * a family that ships rarely is not aged by the calendar.
+ * docs/features/tiering/plan.md (Phase 1), docs/decisions/model-tiers.md.
+ *
+ * Lookups resolve OpenRouter's `~vendor/id` redirect aliases and `:variant`
+ * endpoints through their base id, and — since 2026-09-11 — BORROW across
+ * providers: models.dev has no `openai-codex` (or `azure-*`) provider entries,
+ * so `openai-codex/gpt-5.6-terra` had no facts while `openai/gpt-5.6-terra` did,
+ * which left every Codex row unscored by the measured floor and judged by name
+ * anchors alone. A row without its own facts takes the release date of the same
+ * model (same canonical vendor, same normalized id) on any other provider,
+ * provided every such row agrees on the date — a disagreement (OpenRouter's
+ * April `deepseek-v4-flash` vs DeepSeek's July one) borrows nothing. Only the
+ * date is borrowed, never the tool-call flag. A row models.dev does not know
+ * anywhere has no facts and gets the price-and-name behaviour that preceded
+ * this module. docs/decisions/model-tiers.md (2026-09-11).
+ */
+
+import { readFileSync } from "node:fs";
+import type { Api, Model } from "@earendil-works/pi-ai";
+import { baseModelId, DAY_MS, isAliasOrVariantId, modelIdentity } from "./model-policy.ts";
+
+export interface ModelFactsRow {
+	/** ISO date (YYYY-MM-DD) the model was released, per models.dev. */
+	releaseDate: string;
+	/** Present only when models.dev marks the model as NOT supporting tool calls. */
+	toolCall?: false;
+}
+
+interface FactsFile {
+	facts: Record<string, ModelFactsRow>;
+}
+
+/** A model released this many days before its family's newest is one generation behind. */
+export const PRIOR_GENERATION_DAYS = 365;
+/** …and this many days behind is two generations: maximum scaffolding, never auto-selected. */
+export const ANCIENT_GENERATION_DAYS = 730;
+
+let loaded:
+	| {
+			facts: Record<string, ModelFactsRow>;
+			familyNewest: Map<string, number>;
+			/** `vendor|normalizedId` → the agreed release date, or null when providers disagree. */
+			borrowed: Map<string, ModelFactsRow | null>;
+	  }
+	| undefined;
+
+/** Test seam: replace the bundled table (pass `undefined` to restore it). */
+export function setModelFactsForTest(facts: Record<string, ModelFactsRow> | undefined): void {
+	loaded = facts ? index(facts) : undefined;
+}
+
+function load(): NonNullable<typeof loaded> {
+	if (loaded) return loaded;
+	let facts: Record<string, ModelFactsRow> = {};
+	try {
+		const file = JSON.parse(readFileSync(new URL("./model-facts.generated.json", import.meta.url), "utf8")) as FactsFile;
+		if (file && typeof file.facts === "object") facts = file.facts;
+	} catch {
+		// A missing or unreadable table means "no facts": every row degrades to the
+		// pre-facts price-and-name behaviour rather than throwing inside selection.
+	}
+	loaded = index(facts);
+	return loaded;
+}
+
+/**
+ * The vendor family a row's generation is judged within: the canonical vendor
+ * when the identity policy knows it (so `openrouter/deepseek/…` and the direct
+ * `deepseek` provider share one family), else the containment key.
+ */
+export function modelFamily(model: { provider: string; id: string }): string {
+	const identity = modelIdentity(model as Model<Api>);
+	return identity.profile ?? identity.containment;
+}
+
+function index(facts: Record<string, ModelFactsRow>) {
+	const familyNewest = new Map<string, number>();
+	const borrowed = new Map<string, ModelFactsRow | null>();
+	for (const [key, row] of Object.entries(facts)) {
+		const slash = key.indexOf("/");
+		if (slash <= 0) continue;
+		const model = { provider: key.slice(0, slash), id: key.slice(slash + 1) };
+		// Variants and redirect aliases carry no generation of their own.
+		if (isAliasOrVariantId(model.id)) continue;
+		const t = Date.parse(row.releaseDate);
+		if (Number.isNaN(t)) continue;
+		const family = modelFamily(model);
+		if (t > (familyNewest.get(family) ?? -Infinity)) familyNewest.set(family, t);
+		const lend = borrowKey(model);
+		if (!lend) continue;
+		const prior = borrowed.get(lend);
+		if (prior === undefined) borrowed.set(lend, { releaseDate: row.releaseDate });
+		else if (prior !== null && prior.releaseDate !== row.releaseDate) borrowed.set(lend, null);
+	}
+	return { facts, familyNewest, borrowed };
+}
+
+/** The cross-provider identity a row may lend its release date under, or undefined for an unverifiable one. */
+function borrowKey(model: { provider: string; id: string }): string | undefined {
+	const identity = modelIdentity(model as Model<Api>);
+	if (identity.confidence === "opaque" || !identity.profile) return undefined;
+	return `${identity.profile}|${baseModelId(identity.normalizedId)}`;
+}
+
+/**
+ * The models.dev row for a model, resolved through alias and variant spellings,
+ * else borrowed from the same model on another provider (module doc).
+ */
+export function modelFacts(model: { provider: string; id: string }): ModelFactsRow | undefined {
+	const { facts, borrowed } = load();
+	const own = facts[`${model.provider}/${model.id}`] ?? facts[`${model.provider}/${baseModelId(model.id)}`];
+	if (own) return own;
+	const key = borrowKey(model);
+	return (key && borrowed.get(key)) || undefined;
+}
+
+/** Whether models.dev says the model cannot call tools (undefined = unknown or yes). */
+export function lacksToolCalls(model: { provider: string; id: string }): boolean {
+	return modelFacts(model)?.toolCall === false;
+}
+
+/**
+ * How many days behind its family's newest release the model is, or undefined
+ * when either date is unknown. 0 for the newest model itself.
+ */
+export function generationLagDays(model: { provider: string; id: string }): number | undefined {
+	const row = modelFacts(model);
+	if (!row) return undefined;
+	const released = Date.parse(row.releaseDate);
+	if (Number.isNaN(released)) return undefined;
+	const newest = load().familyNewest.get(modelFamily(model));
+	if (newest === undefined) return undefined;
+	return Math.max(0, Math.round((newest - released) / DAY_MS));
+}
+
+export type Generation = "current" | "prior" | "ancient";
+
+/** The model's generation relative to its family, or undefined without facts. */
+export function modelGeneration(model: { provider: string; id: string }): Generation | undefined {
+	const lag = generationLagDays(model);
+	if (lag === undefined) return undefined;
+	if (lag > ANCIENT_GENERATION_DAYS) return "ancient";
+	if (lag > PRIOR_GENERATION_DAYS) return "prior";
+	return "current";
+}
+
+/** Prior or ancient: excluded from every automatic pick (subagent, classifier, reader, presets). */
+export function isPriorGeneration(model: { provider: string; id: string }): boolean {
+	const generation = modelGeneration(model);
+	return generation === "prior" || generation === "ancient";
+}

package/extensions/lib/model-policy.ts

@@ -1,112 +1,15 @@
-import type { Api, Model } from "@earendil-works/pi-ai";
-
-/** The two automatic model-selection jobs have different capability floors. */
-export type ModelRole = "classifier" | "subagent";
-
-export interface RoleProfile {
-	/** Vetted, small-but-capable models. Price alone never adds to this list. */
-	classifier: readonly string[];
-	/** Economical models suitable for delegated coding/reasoning work. */
-	subagent: readonly string[];
-}
+import { type Api, clampThinkingLevel, type Model, type ThinkingLevel } from "@earendil-works/pi-ai";
 
 /**
- * Short family lists, not catalogs. Broad gateways apply these to their live
- * authenticated catalog after containment; they never get an OpenRouter-sized
- * hardcoded list. Reviewed against official provider docs on 2026-08-06.
+ * Whether a session runs on a Claude-family model. Claude Code's own subagent
+ * conventions (`CLAUDE_CODE_SUBAGENT_MODEL`, `.claude/agents` model fields) are
+ * honored across providers only on such sessions; elsewhere subagents stay on
+ * the session's provider. Only provider/id are consulted, so a minimal model
+ * shape suffices.
  */
-export const ROLE_PROFILES: Readonly<Record<string, RoleProfile>> = {
-	anthropic: {
-		classifier: ["claude-haiku-4-5", "claude-sonnet-5", "claude-sonnet-4-6"],
-		subagent: ["claude-sonnet-5", "claude-haiku-4-5", "claude-sonnet-4-6"],
-	},
-	openai: {
-		classifier: ["gpt-5.6-luna", "gpt-5.4-mini", "gpt-5-mini", "gpt-4.1-mini", "gpt-4o-mini"],
-		subagent: ["gpt-5.6-luna", "gpt-5.4-mini", "gpt-5.3-codex-spark", "gpt-5.6-terra"],
-	},
-	google: {
-		classifier: ["gemini-3.6-flash", "gemini-3.5-flash", "gemini-3-flash-preview", "gemini-2.5-flash"],
-		subagent: ["gemini-3.6-flash", "gemini-3.5-flash", "gemini-3-flash-preview", "gemini-2.5-flash"],
-	},
-	xai: {
-		classifier: ["grok-4.3", "grok-4.5"],
-		subagent: ["grok-build-0.1", "grok-4.3", "grok-4.5"],
-	},
-	mistral: {
-		classifier: ["mistral-small-2603", "mistral-small-latest", "mistral-medium-3.5"],
-		subagent: ["mistral-small-2603", "mistral-medium-3.5", "codestral-latest"],
-	},
-	deepseek: {
-		classifier: ["deepseek-v4-flash", "deepseek-v4-pro"],
-		subagent: ["deepseek-v4-flash", "deepseek-v4-pro"],
-	},
-	zai: {
-		classifier: ["glm-5-turbo", "glm-4.7", "glm-5.2", "glm-4.5-air", "glm-4-flash"],
-		subagent: ["glm-5-turbo", "glm-4.7", "glm-5.2", "glm-4.5-air"],
-	},
-	moonshot: {
-		classifier: ["kimi-k2.6", "kimi-k2.5"],
-		subagent: ["kimi-k2.7-code", "kimi-k2.6", "kimi-k3"],
-	},
-	minimax: {
-		classifier: ["MiniMax-M2.7", "MiniMax-M3"],
-		subagent: ["MiniMax-M2.7", "MiniMax-M3"],
-	},
-	xiaomi: {
-		classifier: ["mimo-v2.5", "mimo-v2-pro"],
-		subagent: ["mimo-v2.5", "mimo-v2.5-pro", "mimo-v2-pro"],
-	},
-	"ant-ling": {
-		// The current pi catalog predates Ling 3.0. Flash remains opt-in: it has
-		// not been calibrated as the approval boundary.
-		classifier: ["Ling-2.6-1T", "Ring-2.6-1T"],
-		subagent: ["Ling-2.6-1T", "Ring-2.6-1T", "Ling-2.6-flash"],
-	},
-	meta: {
-		classifier: ["llama-3.3-70b", "llama-4-scout"],
-		subagent: ["llama-4-scout", "llama-3.3-70b"],
-	},
-	amazon: {
-		classifier: ["nova-2-lite", "nova-lite"],
-		subagent: ["nova-2-lite", "nova-lite", "nova-pro"],
-	},
-	"host:nvidia": {
-		classifier: ["nvidia/nvidia-nemotron-nano-9b-v2", "openai/gpt-oss-20b", "meta/llama-3.3-70b-instruct"],
-		subagent: ["poolside/laguna-xs-2.1", "nvidia/nemotron-3-super-120b-a12b", "openai/gpt-oss-20b"],
-	},
-	"host:groq": {
-		classifier: ["openai/gpt-oss-20b", "llama-3.3-70b-versatile"],
-		subagent: ["openai/gpt-oss-20b", "openai/gpt-oss-120b", "llama-3.3-70b-versatile"],
-	},
-	"host:cerebras": {
-		classifier: ["gpt-oss-120b", "zai-glm-4.7"],
-		subagent: ["gpt-oss-120b", "zai-glm-4.7"],
-	},
-	"host:fireworks": {
-		classifier: ["accounts/fireworks/models/deepseek-v4-flash", "accounts/fireworks/models/gpt-oss-20b"],
-		subagent: ["accounts/fireworks/models/kimi-k2p7-code", "accounts/fireworks/models/gpt-oss-20b"],
-	},
-	"host:together": {
-		classifier: ["Qwen/Qwen3.5-9B", "openai/gpt-oss-20b"],
-		subagent: ["openai/gpt-oss-20b", "moonshotai/Kimi-K2.7-Code", "Qwen/Qwen3.5-9B"],
-	},
-	"host:baseten": {
-		classifier: ["openai/gpt-oss-120b", "deepseek-ai/DeepSeek-V4-Flash"],
-		subagent: ["openai/gpt-oss-120b", "zai-org/GLM-5.2", "moonshotai/Kimi-K2.7-Code"],
-	},
-	"host:cloudflare-workers": {
-		classifier: ["@cf/openai/gpt-oss-20b", "@cf/zai-org/glm-4.7-flash"],
-		subagent: ["@cf/moonshotai/kimi-k2.7-code", "@cf/openai/gpt-oss-20b"],
-	},
-	"host:qwen-plan": {
-		classifier: ["qwen3.6-flash", "deepseek-v4-flash", "qwen3.6-plus"],
-		subagent: ["kimi-k2.7-code", "deepseek-v4-flash", "qwen3.7-plus", "qwen3.6-plus"],
-	},
-	"host:kimi-coding": {
-		classifier: ["kimi-for-coding", "k3"],
-		subagent: ["kimi-for-coding", "k3"],
-	},
-};
+export function isClaudeFamilyModel(model: { provider: string; id: string }): boolean {
+	return model.provider === "anthropic" || /claude/i.test(model.id);
+}
 
 export type ProviderPolicyKind = "direct" | "hosted" | "gateway" | "opaque";
 
@@ -114,14 +17,12 @@ export interface ProviderPolicy {
 	kind: ProviderPolicyKind;
 	/** Fixed profile for direct vendors and stable hosted catalogs. */
 	profile?: string;
-	/** Whether a price-ranked subagent may follow the vetted profile. */
-	dynamicSubagents: boolean;
 }
 
-const direct = (profile: string): ProviderPolicy => ({ kind: "direct", profile, dynamicSubagents: true });
-const hosted = (profile?: string): ProviderPolicy => ({ kind: "hosted", profile, dynamicSubagents: true });
-const gateway = (): ProviderPolicy => ({ kind: "gateway", dynamicSubagents: true });
-const opaque = (): ProviderPolicy => ({ kind: "opaque", dynamicSubagents: false });
+const direct = (profile: string): ProviderPolicy => ({ kind: "direct", profile });
+const hosted = (profile?: string): ProviderPolicy => ({ kind: "hosted", profile });
+const gateway = (): ProviderPolicy => ({ kind: "gateway" });
+const opaque = (): ProviderPolicy => ({ kind: "opaque" });
 
 /**
  * Every built-in language-model provider in pi 0.84.0. Unknown/custom providers
@@ -301,38 +202,96 @@ export function modelIdentity(model: Model<Api>): ModelIdentity {
 	};
 }
 
+const UNSUITABLE_VARIANT = /:(batch|free|online|thinking)$/i;
+
 /**
- * Names of the known small-but-capable model families, best tier first. Too weak
- * to *choose* by — Groq and xAI carry none of them — but strong enough to
- * corroborate a choice price alone suggested, and to order tiers when several
- * cheap models qualify (mini-class ahead of nano/lite-class).
+ * The id without OpenRouter's `~` redirect-alias marker and without a
+ * `:batch`-style endpoint variant — the spelling the name rules, the facts
+ * table and the capability index all key on (`~deepseek/deepseek-v4-flash-latest`
+ * → `deepseek/deepseek-v4-flash-latest`, `gpt-5-mini:batch` → `gpt-5-mini`).
  */
-const NAME_HINTS = [/haiku/i, /flash/i, /mini/i, /nano/i, /small/i, /lite/i, /instant/i, /sonnet/i];
-
-/** Index into NAME_HINTS; NAME_HINTS.length means "no known small-model name". */
-export function hintRank(model: Model<Api>): number {
-	const index = NAME_HINTS.findIndex((pattern) => pattern.test(model.id));
-	return index === -1 ? NAME_HINTS.length : index;
+export function baseModelId(id: string): string {
+	return (id.startsWith("~") ? id.slice(1) : id).replace(/:[a-z]+$/i, "");
 }
 
-/** Whether the model's name carries one of the known small-model family words. */
-export function hasSmallModelName(model: Model<Api>): boolean {
-	return hintRank(model) < NAME_HINTS.length;
+/** Whether the id carries a redirect marker or endpoint variant (`baseModelId` would change it). */
+export function isAliasOrVariantId(id: string): boolean {
+	return baseModelId(id) !== id;
 }
 
-const UNSUITABLE_VARIANT = /:(batch|free|online|thinking)$/i;
-
-/** Automatic selection excludes endpoint variants with the wrong execution shape. */
+/**
+ * Automatic selection excludes endpoint variants with the wrong execution shape,
+ * and OpenRouter's `~vendor/family-latest` redirect aliases ("always redirects to
+ * the latest model in the family"): the model behind one moves without notice,
+ * so it has no stable identity to tier, date or price — and the classifier is a
+ * permission boundary. The alias stays available by hand (/model, an explicit
+ * `subagentModel` / `classifierModel` setting).
+ */
 export function isSelectableVariant(model: Model<Api>): boolean {
-	return !UNSUITABLE_VARIANT.test(model.id);
+	return !UNSUITABLE_VARIANT.test(model.id) && !model.id.startsWith("~");
 }
 
+/** One day in milliseconds, for the release-date arithmetic in model-facts.ts and capability-index.ts. */
+export const DAY_MS = 86_400_000;
+
 /** Non-positive values are catalog sentinels/unpriced, not evidence of being free. */
 export function pricedInput(model: Model<Api>): number | undefined {
 	const input = model.cost?.input;
 	return typeof input === "number" && input > 0 ? input : undefined;
 }
 
+/** A dated snapshot id (`claude-haiku-4-5-20251001`): the trailing `-YYYYMMDD` marks a pinned alias of an undated model. */
+export function isDatedModelId(id: string): boolean {
+	return /-20\d{6}$/.test(id);
+}
+
+/**
+ * The id with a trailing snapshot date removed: `-YYYYMMDD` (Anthropic, OpenAI)
+ * or `-MMDD` (DeepSeek's `deepseek-v4-flash-0731`, `deepseek-v4-pro-0813`; the
+ * four digits must be a real month and day, so a `-2411`-style version tag is
+ * left alone). The id itself when it carries no such suffix.
+ */
+export function stripSnapshotDate(id: string): string {
+	if (isDatedModelId(id)) return id.slice(0, -9);
+	const short = id.match(/-(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])$/);
+	return short ? id.slice(0, -5) : id;
+}
+
+/** Whether the id ends in a snapshot date of either shape (`stripSnapshotDate` would change it). */
+export function isSnapshotDatedId(id: string): boolean {
+	return stripSnapshotDate(id) !== id;
+}
+
+/**
+ * Whether `model` is a dated snapshot whose undated alias is also present in
+ * `pool` — the row a listing collapses so the same model is not offered twice.
+ * Exact: the alias must be the id minus its date, so `deepseek-v4-flash-vision-exp`
+ * is never read as a snapshot of `deepseek-v4-flash`.
+ */
+export function isDatedDuplicate(model: { id: string }, pool: ReadonlyArray<{ id: string }>): boolean {
+	const alias = stripSnapshotDate(model.id);
+	return alias !== model.id && pool.some((other) => other.id === alias);
+}
+
+/** The canonical `provider/id` spec — one source of truth for the string form. */
+export function modelSpec(model: { provider: string; id: string }): string {
+	return `${model.provider}/${model.id}`;
+}
+
+/** Whether a stamped-default setting was set for a provider this session has since left. */
+export function isStaleContainmentStamp(
+	setForContainment: string | undefined,
+	sessionModel: { provider: string; id: string } | undefined,
+): boolean {
+	return setForContainment !== (sessionModel ? modelIdentity(sessionModel as Model<Api>).containment : undefined);
+}
+
+/** Whether an explicit model leaves the session's provider/route/family boundary. */
+export function crossesProvider(model: Model<Api>, sessionModel: Model<Api>): boolean {
+	if (model.provider !== sessionModel.provider) return true;
+	return modelIdentity(model).containment !== modelIdentity(sessionModel).containment;
+}
+
 /** Models that automatic selection may consider without changing containment. */
 export function modelsContainedToSession(available: Model<Api>[], sessionModel: Model<Api>): Model<Api>[] {
 	const sessionIdentity = modelIdentity(sessionModel);
@@ -344,74 +303,71 @@ export function modelsContainedToSession(available: Model<Api>[], sessionModel:
 	);
 }
 
-function comparableId(value: string): string {
-	return value.toLowerCase().replaceAll(".", "-").replaceAll("_", "-");
-}
-
-function matchesPrefix(model: Model<Api>, prefix: string): boolean {
-	const id = comparableId(modelIdentity(model).normalizedId);
-	const wanted = comparableId(prefix);
-	return id === wanted || id.startsWith(wanted);
+/**
+ * The thinking level to send on a one-shot `completeSimple` call that would
+ * rather run with thinking OFF (classifier, setup drafting, recap, readers).
+ *
+ * `undefined` = the model supports off — omit `reasoning`, pi disables thinking
+ * explicitly, the request stays exactly as before. A level = the model cannot
+ * disable thinking (catalog `thinkingLevelMap.off: null`, e.g. Gemini 3.6+
+ * Flash); omitting `reasoning` makes the provider 400 ("Reasoning is mandatory
+ * for this endpoint and cannot be disabled"), so send the lowest level the
+ * model supports instead.
+ */
+export function forcedReasoningLevel(model: Model<Api>): ThinkingLevel | undefined {
+	const clamped = clampThinkingLevel(model, "off");
+	return clamped === "off" ? undefined : (clamped as ThinkingLevel);
 }
 
-/** First live model matching a role's reviewed family order. */
-export function findRoleProfileModel(
-	available: Model<Api>[],
-	sessionModel: Model<Api>,
-	role: ModelRole,
-	accept: (model: Model<Api>) => boolean = () => true,
-	// A caller that already computed the containment set can pass it to avoid the
-	// O(catalog) recompute (classifierCandidates does, on a per-tool-call hot path).
-	precomputedContained?: Model<Api>[],
-): Model<Api> | undefined {
-	const identity = modelIdentity(sessionModel);
-	if (!identity.profile) return undefined;
-	const prefixes = ROLE_PROFILES[identity.profile]?.[role] ?? [];
-	const contained = precomputedContained ?? modelsContainedToSession(available, sessionModel);
-	for (const prefix of prefixes) {
-		const wanted = comparableId(prefix);
-		const exact = contained.find(
-			(model) => comparableId(modelIdentity(model).normalizedId) === wanted && accept(model),
-		);
-		if (exact) return exact;
-		const prefixed = contained.find((model) => matchesPrefix(model, prefix) && accept(model));
-		if (prefixed) return prefixed;
-	}
-	return undefined;
+/**
+ * Provider error saying thinking cannot be disabled — the reactive net for a
+ * model whose catalog entry LACKS the `thinkingLevelMap.off: null` marker
+ * (OpenRouter entries, hand-added models newer than the bundled catalog).
+ * A false positive only costs one retry with minimal thinking.
+ */
+export function isReasoningMandatoryError(message: string): boolean {
+	return /(reasoning|thinking)[^.]*\b(mandatory|cannot be disabled|can't be disabled|must be enabled|is required)\b/i.test(message);
 }
 
-export interface EconomicalModelChoice {
-	model: Model<Api>;
-	via: "profile" | "session";
+/** The level to retry with after isReasoningMandatoryError: the lowest real level the model supports. */
+export function reasoningRetryLevel(model: Model<Api>): ThinkingLevel {
+	const clamped = clampThinkingLevel(model, "minimal");
+	return clamped === "off" ? "minimal" : (clamped as ThinkingLevel);
 }
 
 /**
- * A vetted small-but-capable same-containment model within the session's
- * price ceiling, else the session model itself. Used for low-stakes one-shot
- * jobs over untrusted content (the web_fetch reader) — the content goes to
- * the model, so containment applies. Not used for compaction, which runs on
- * the session model to reuse the provider prompt cache.
+ * Run a one-shot `completeSimple`-style call that wants thinking OFF, handling
+ * the models that can't. The proactive path ({@link forcedReasoningLevel}) sends
+ * a level up front for catalog-marked models; the reactive path catches a
+ * provider's mandatory-thinking 400 ({@link isReasoningMandatoryError}) for the
+ * metadata gaps and retries ONCE at the model's floor. `call` receives the level
+ * to send (undefined = omit `reasoning`) and is invoked at most twice.
+ *
+ * `learned` optionally memoizes the reactive result per `provider/id` across
+ * calls, so a repeatedly-called site (the web-fetch reader) pays the failed
+ * round-trip once, not every call. Omit it for one-off callers.
+ *
+ * `onUsage` receives the final reply's `usage` once per invocation — this is the
+ * single choke point for the reader-style one-shots (web-fetch, recap, setup),
+ * so instrumenting it here reports their cost to the footer without each call
+ * site having to remember to.
  */
-export function pickEconomicalContainedModel(
-	available: Model<Api>[],
-	sessionModel: Model<Api> | undefined,
-): EconomicalModelChoice | undefined {
-	if (!sessionModel) return undefined;
-	const sessionPrice = pricedInput(sessionModel);
-	const withinBudget = (model: Model<Api>) => {
-		if (sessionPrice === undefined) return true;
-		const price = pricedInput(model);
-		return price === undefined || price <= sessionPrice;
-	};
-	const profiled = findRoleProfileModel(available, sessionModel, "classifier", withinBudget);
-	return profiled ? { model: profiled, via: "profile" } : { model: sessionModel, via: "session" };
-}
-
-/** Whether price ranking is an acceptable subagent fallback for this session. */
-export function allowsDynamicSubagentSelection(sessionModel: Model<Api>): boolean {
-	const policy = providerPolicy(sessionModel.provider);
-	if (!policy.dynamicSubagents) return false;
-	return modelIdentity(sessionModel).confidence !== "opaque";
+export async function withReasoningFallback<R extends { stopReason: string; errorMessage?: string; usage?: unknown }>(
+	model: Model<Api>,
+	call: (reasoning: ThinkingLevel | undefined) => Promise<R>,
+	learned?: Map<string, ThinkingLevel>,
+	onUsage?: (usage: unknown) => void,
+): Promise<R> {
+	const key = `${model.provider}/${model.id}`;
+	const reasoning = learned?.get(key) ?? forcedReasoningLevel(model);
+	let result = await call(reasoning);
+	if (result.stopReason === "error" && !reasoning && isReasoningMandatoryError(result.errorMessage ?? "")) {
+		const level = reasoningRetryLevel(model);
+		learned?.set(key, level);
+		result = await call(level);
+	}
+	onUsage?.(result.usage);
+	return result;
 }
 
 /** Resolve an explicit provider/id, bare id, or prefix. Explicit choices are not contained. */