@prometheus-ai/agent 0.5.4 → 0.5.8

package/src/config/model-registry.ts

@@ -1,96 +1,34 @@
+import { execSync } from "node:child_process";
 import * as path from "node:path";
+import { registerCustomApi, unregisterCustomApis } from "@prometheus-ai/ai/api-registry";
+import type { Api, Context, Model, ModelSpec, SimpleStreamOptions, ThinkingConfig } from "@prometheus-ai/ai/types";
+import type { AssistantMessageEventStream } from "@prometheus-ai/ai/utils/event-stream";
+import { buildModel } from "@prometheus-ai/catalog/build";
+import { isVertexExpressOpenAIUrl } from "@prometheus-ai/catalog/hosts";
+import { readModelCache } from "@prometheus-ai/catalog/model-cache";
 import {
-	type Api,
-	type AssistantMessageEventStream,
-	type Context,
 	createModelManager,
-	enrichModelThinking,
-	getBundledModels,
-	getBundledProviders,
-	googleAntigravityModelManagerOptions,
-	googleGeminiCliModelManagerOptions,
-	type Model,
 	type ModelManagerOptions,
 	type ModelRefreshStrategy,
+} from "@prometheus-ai/catalog/model-manager";
+import { getBundledModels, getBundledProviders } from "@prometheus-ai/catalog/models";
+import {
+	googleAntigravityModelManagerOptions,
+	googleGeminiCliModelManagerOptions,
 	openaiCodexModelManagerOptions,
 	PROVIDER_DESCRIPTORS,
-	readModelCache,
-	registerCustomApi,
-	type SimpleStreamOptions,
-	type ThinkingConfig,
-	UNK_CONTEXT_WINDOW,
-	UNK_MAX_TOKENS,
-	unregisterCustomApis,
-} from "@prometheus-ai/ai";
-
-// Sentinel for local-only OAuth token (LM Studio, vLLM) — declared inline to avoid loading
-// any provider module at startup. Must match `DEFAULT_LOCAL_TOKEN` in oauth/lm-studio.ts.
+} from "@prometheus-ai/catalog/provider-models";
+import {
+	collapseBuiltModelVariants,
+	getVariantAliasSources,
+	resolveVariantAlias,
+} from "@prometheus-ai/catalog/variant-collapse";
+
+// Sentinels for local-only OAuth tokens — declared inline to avoid loading
+// provider modules at startup. Must match packages/ai/src/registry/lm-studio.ts
+// and packages/ai/src/registry/vllm.ts.
 const DEFAULT_LOCAL_TOKEN = "lm-studio-local";
-
-// Default cap on `max_tokens` for auto-discovered models that do not advertise
-// their own output limit (OpenAI-models-list, Ollama, llama.cpp, new-api/
-// one-api proxies). 32K matches the upper end of what mainstream
-// OpenAI-compatible providers (DeepSeek, MiMo, OpenRouter, etc.) actually
-// accept and keeps `min(contextWindow, …)` honoring smaller local windows.
-// Conservative caps below this caused providers to drop the connection
-// mid-stream when models hit the cap on legitimate large tool calls (see
-// issue #1528: `write` payloads >~5KB on deepseek-v4-pro surfaced as
-// "socket connection was closed unexpectedly").
-const DISCOVERY_DEFAULT_MAX_TOKENS = 32_768;
-
-const DEFAULT_OLLAMA_BASE_URL = "http://127.0.0.1:11434";
-const OLLAMA_HOST_DEFAULT_PORT = "11434";
-
-function normalizeOllamaHostEnv(value: string | undefined): string | undefined {
-	const trimmed = value?.trim();
-	if (!trimmed) return undefined;
-	const candidate = trimmed.includes("://")
-		? trimmed
-		: trimmed.startsWith("//")
-			? `http:${trimmed}`
-			: trimmed.startsWith(":")
-				? `http://127.0.0.1${trimmed}`
-				: `http://${trimmed}`;
-	try {
-		const parsed = new URL(candidate);
-		if (!parsed.hostname || (parsed.protocol !== "http:" && parsed.protocol !== "https:")) {
-			return undefined;
-		}
-		if (!parsed.port && parsed.protocol === "http:") {
-			parsed.port = OLLAMA_HOST_DEFAULT_PORT;
-		}
-		return `${parsed.protocol}//${parsed.host}`;
-	} catch {
-		return undefined;
-	}
-}
-
-function getImplicitOllamaBaseUrl(): string {
-	const baseUrl = Bun.env.OLLAMA_BASE_URL?.trim();
-	return baseUrl || normalizeOllamaHostEnv(Bun.env.OLLAMA_HOST) || DEFAULT_OLLAMA_BASE_URL;
-}
-
-function getOllamaContextLengthOverride(): number | undefined {
-	const value = Bun.env.OLLAMA_CONTEXT_LENGTH?.trim();
-	if (!value) return undefined;
-	const parsed = Number(value);
-	return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
-}
-
-// Anthropic-safe variant of the discovery cap. The Anthropic stream converter
-// in `packages/ai/src/providers/anthropic.ts` derives the request limit as
-// `(model.maxTokens / 3) | 0`, so the 32K default would surface as 10,922
-// requested output tokens — above the 8,192 hard cap on classic Claude 3.x
-// Sonnet/Haiku/Opus endpoints. Discovered models routed through
-// `anthropic-messages` (proxy `supported_endpoint_types: ["anthropic"]` or a
-// custom provider with `api: anthropic-messages` + openai-models-list
-// discovery) fall back to this conservative value.
-const DISCOVERY_DEFAULT_MAX_TOKENS_ANTHROPIC = 8_192;
-
-/** Routes discovered-model `maxTokens` defaults around Anthropic's 3× output divisor. */
-function discoveryDefaultMaxTokens(api: Api | undefined): number {
-	return api === "anthropic-messages" ? DISCOVERY_DEFAULT_MAX_TOKENS_ANTHROPIC : DISCOVERY_DEFAULT_MAX_TOKENS;
-}
+const DEFAULT_VLLM_LOCAL_TOKEN = "vllm-local";
 
 const SPECIAL_MODEL_MANAGER_PROVIDER_IDS: readonly string[] = [
 	"google-antigravity",
@@ -103,35 +41,40 @@ const STARTUP_MODEL_CACHE_PROVIDER_IDS: readonly string[] = [
 	...SPECIAL_MODEL_MANAGER_PROVIDER_IDS,
 ];
 
-import { registerOAuthProvider, unregisterOAuthProviders } from "@prometheus-ai/ai/utils/oauth";
-import type { OAuthCredentials, OAuthLoginCallbacks } from "@prometheus-ai/ai/utils/oauth/types";
-import { isRecord, logger } from "@prometheus-ai/utils";
-import { parseModelString, resolveProviderModelReference } from "../config/model-resolver";
-import { isValidThemeColor, type ThemeColor } from "../modes/theme/theme";
-import type { AuthStorage, OAuthCredential } from "../session/auth-storage";
-import { type ConfigError, ConfigFile } from "./config-file";
+import type { ApiKeyResolver, FetchImpl } from "@prometheus-ai/ai";
+import { registerOAuthProvider, unregisterOAuthProviders } from "@prometheus-ai/ai/oauth";
+import type { OAuthCredentials, OAuthLoginCallbacks } from "@prometheus-ai/ai/oauth/types";
 import {
 	buildCanonicalModelIndex,
+	buildCanonicalModelOrder,
+	buildModelProviderPriorityRank,
 	type CanonicalModelIndex,
 	type CanonicalModelRecord,
 	type CanonicalModelVariant,
+	type CanonicalVariantPreferences,
 	formatCanonicalVariantSelector,
+	getBundledCanonicalReferenceData,
+	getBundledModelReferenceIndex,
 	type ModelEquivalenceConfig,
-} from "./model-equivalence";
-import {
-	getBracketStrippedModelIdCandidates,
-	getLongestModelLikeIdSegment,
-	getModelLikeIdSegments,
-	stripBracketedModelIdAffixes,
-} from "./model-id-affixes";
+	resolveCanonicalVariant,
+	resolveModelReference,
+} from "@prometheus-ai/catalog/identity";
+import { isRecord, logger } from "@prometheus-ai/utils";
+import { parseModelString, resolveProviderModelReference } from "../config/model-resolver";
+import type { AuthStorage, OAuthCredential } from "../session/auth-storage";
+import { type ApiKeyResolverModel, type ApiKeyResolverOptions, createApiKeyResolver } from "./api-key-resolver";
+import type { ConfigError, ConfigFile } from "./config-file";
 import {
-	type ModelOverride,
-	type ModelsConfig,
-	ModelsConfigSchema,
-	type ProviderAuthMode,
-	type ProviderDiscovery,
-} from "./models-config-schema";
-import { type Settings, settings } from "./settings";
+	DISCOVERY_DEFAULT_MAX_TOKENS,
+	type DiscoveryContext,
+	type DiscoveryProviderConfig,
+	discoverModelsByProviderType,
+	getImplicitOllamaBaseUrl,
+	getOllamaContextLengthOverride,
+} from "./model-discovery";
+import { ModelsConfigFile, type ProviderValidationModel, validateProviderConfiguration } from "./models-config";
+import type { ModelOverride, ModelsConfig, ProviderAuthMode } from "./models-config-schema";
+import { settings } from "./settings";
 
 export type { CanonicalModelIndex, CanonicalModelRecord, CanonicalModelVariant, ModelEquivalenceConfig };
 
@@ -141,196 +84,17 @@ export function isAuthenticated(apiKey: string | undefined | null): apiKey is st
 	return Boolean(apiKey) && apiKey !== kNoAuth;
 }
 
-export type ModelRole = "default" | "smol" | "slow" | "vision" | "plan" | "designer" | "commit" | "task";
-
-export interface ModelRoleInfo {
-	tag?: string;
-	name: string;
-	color?: ThemeColor;
-}
-
-export const MODEL_ROLES: Record<ModelRole, ModelRoleInfo> = {
-	default: { tag: "DEFAULT", name: "Default", color: "success" },
-	smol: { tag: "SMOL", name: "Fast", color: "warning" },
-	slow: { tag: "SLOW", name: "Thinking", color: "accent" },
-	vision: { tag: "VISION", name: "Vision", color: "error" },
-	plan: { tag: "PLAN", name: "Architect", color: "muted" },
-	designer: { tag: "DESIGNER", name: "Designer", color: "muted" },
-	commit: { tag: "COMMIT", name: "Commit", color: "dim" },
-	task: { tag: "TASK", name: "Subtask", color: "muted" },
-};
-
-export const MODEL_ROLE_IDS: ModelRole[] = ["default", "smol", "slow", "vision", "plan", "designer", "commit", "task"];
-
-/** Alias for ModelRoleInfo - used for both built-in and custom roles */
-export type RoleInfo = ModelRoleInfo;
-
-/**
- * Return the canonical set of known roles for selector/carousel UI.
- *
- * Built-ins always come first. Configured cycle order, model assignments, and
- * tag metadata can introduce additional custom roles without requiring duplicate
- * entries across settings.
- */
-export function getKnownRoleIds(settings: Settings): string[] {
-	const roles = [...MODEL_ROLE_IDS] as string[];
-	const seen = new Set<string>(roles);
-	const addRole = (role: string) => {
-		if (seen.has(role)) return;
-		seen.add(role);
-		roles.push(role);
-	};
-
-	for (const role of settings.get("cycleOrder")) addRole(role);
-	for (const role of Object.keys(settings.getModelRoles())) addRole(role);
-	for (const role of Object.keys(settings.get("modelTags"))) addRole(role);
-
-	return roles;
+function isDiscoveryBearerApiKey(apiKey: string | undefined | null): apiKey is string {
+	return isAuthenticated(apiKey) && apiKey !== DEFAULT_LOCAL_TOKEN && apiKey !== DEFAULT_VLLM_LOCAL_TOKEN;
 }
 
-/**
- * Get role info for a role name (built-in or custom).
- * Configured metadata overrides built-in defaults when present.
- */
-export function getRoleInfo(role: string, settings: Settings): RoleInfo {
-	const builtIn = role in MODEL_ROLES ? MODEL_ROLES[role as ModelRole] : undefined;
-	const configured = settings.get("modelTags")[role];
-
-	if (configured) {
-		return {
-			tag: builtIn?.tag,
-			name: configured.name || builtIn?.name || role,
-			color: configured.color && isValidThemeColor(configured.color) ? configured.color : builtIn?.color,
-		};
-	}
-
-	if (builtIn) return builtIn;
-
-	return { name: role, color: "muted" };
-}
-
-type ProviderValidationMode = "models-config" | "runtime-register";
-
-interface ProviderValidationModel {
-	id: string;
-	api?: Api;
-	contextWindow?: number;
-	maxTokens?: number;
-}
-
-interface ProviderValidationConfig {
-	baseUrl?: string;
-	headers?: Record<string, string>;
-	apiKey?: string;
-	api?: Api;
-	auth?: ProviderAuthMode;
-	oauthConfigured?: boolean;
-	discovery?: ProviderDiscovery;
-	compat?: Model<Api>["compat"];
-	disableStrictTools?: boolean;
-	modelOverrides?: Record<string, unknown>;
-	models: ProviderValidationModel[];
-}
-
-function validateProviderConfiguration(
-	providerName: string,
-	config: ProviderValidationConfig,
-	mode: ProviderValidationMode,
-): void {
-	const hasProviderApi = !!config.api;
-	const models = config.models;
-
-	if (models.length === 0) {
-		if (mode === "models-config") {
-			const hasModelOverrides = config.modelOverrides && Object.keys(config.modelOverrides).length > 0;
-			if (
-				!config.baseUrl &&
-				!config.headers &&
-				!config.compat &&
-				!config.apiKey &&
-				!config.disableStrictTools &&
-				!hasModelOverrides &&
-				!config.discovery
-			) {
-				throw new Error(
-					`Provider ${providerName}: must specify "baseUrl", "headers", "apiKey", "compat", "disableStrictTools", "modelOverrides", "discovery", or "models"`,
-				);
-			}
-		}
-	} else {
-		if (!config.baseUrl) {
-			throw new Error(`Provider ${providerName}: "baseUrl" is required when defining custom models.`);
-		}
-		const requiresAuth =
-			mode === "runtime-register"
-				? !config.apiKey && !config.oauthConfigured
-				: !config.apiKey && (config.auth ?? "apiKey") !== "none";
-		if (requiresAuth) {
-			throw new Error(
-				mode === "runtime-register"
-					? `Provider ${providerName}: "apiKey" or "oauth" is required when defining models.`
-					: `Provider ${providerName}: "apiKey" is required when defining custom models unless auth is "none".`,
-			);
-		}
-	}
-
-	if (mode === "models-config" && config.discovery && !config.api && config.discovery.type !== "proxy") {
-		throw new Error(`Provider ${providerName}: "api" is required when discovery is enabled at provider level.`);
-	}
-
-	for (const modelDef of models) {
-		if (!hasProviderApi && !modelDef.api) {
-			throw new Error(
-				mode === "runtime-register"
-					? `Provider ${providerName}, model ${modelDef.id}: no "api" specified.`
-					: `Provider ${providerName}, model ${modelDef.id}: no "api" specified. Set at provider or model level.`,
-			);
-		}
-		if (!modelDef.id) {
-			throw new Error(`Provider ${providerName}: model missing "id"`);
-		}
-		if (mode === "models-config") {
-			if (modelDef.contextWindow !== undefined && modelDef.contextWindow <= 0) {
-				throw new Error(`Provider ${providerName}, model ${modelDef.id}: invalid contextWindow`);
-			}
-			if (modelDef.maxTokens !== undefined && modelDef.maxTokens <= 0) {
-				throw new Error(`Provider ${providerName}, model ${modelDef.id}: invalid maxTokens`);
-			}
-		}
-	}
-}
-
-export const ModelsConfigFile = new ConfigFile<ModelsConfig>("models", ModelsConfigSchema).withValidation(
-	"models",
-	config => {
-		for (const [providerName, providerConfig] of Object.entries(config.providers ?? {})) {
-			validateProviderConfiguration(
-				providerName,
-				{
-					baseUrl: providerConfig.baseUrl,
-					headers: providerConfig.headers,
-					apiKey: providerConfig.apiKey,
-					api: providerConfig.api as Api | undefined,
-					auth: (providerConfig.auth ?? "apiKey") as ProviderAuthMode,
-					discovery: providerConfig.discovery as ProviderDiscovery | undefined,
-					compat: providerConfig.compat,
-					disableStrictTools: providerConfig.disableStrictTools,
-					modelOverrides: providerConfig.modelOverrides,
-					models: (providerConfig.models ?? []) as ProviderValidationModel[],
-				},
-				"models-config",
-			);
-		}
-	},
-);
-
 /** Provider override config (baseUrl, headers, apiKey, compat, transport) without custom models */
 interface ProviderOverride {
 	baseUrl?: string;
 	headers?: Record<string, string>;
 	apiKey?: string;
 	authHeader?: boolean;
-	compat?: Model<Api>["compat"];
+	compat?: ModelSpec<Api>["compat"];
 	transport?: Model<Api>["transport"];
 }
 
@@ -344,9 +108,19 @@ interface ProviderOverride {
  *      `token-plan-sgp.xiaomimimo.com` at discovery time)
  *   3. Existing bundled baseUrl (the host baked into `models.json`)
  *
+ * `transport` resolution priority:
+ *   1. `providerOverride.transport` (e.g. `prometheus-native` for auth-gateway users)
+ *   2. `existing.transport` (carried over from boot-time override application)
+ *   3. `model.transport` (rarely set — discovery defaults omit it)
+ *
  * Without (1), the user's override would lose to discovery; without (2)
  * preferred over (3), the bundled `api.xiaomimimo.com` would shadow the
  * tp- token-plan host and produce 401s on the first stream call.
+ * Without explicit transport propagation, an openrouter (or any) entry
+ * marked `transport: prometheus-native` in models.yml silently reverts to the
+ * default openai-completions transport after the background catalog
+ * refresh — so the first `/model` switch after boot hits the raw OpenAI
+ * chat-completions URL instead of the gateway's `/v1/pi/stream` (#2555).
  * See `xiaomi-tp-discovery-merge.test.ts` and the `refresh()` baseUrl-override
  * regression in `model-registry.test.ts`.
  */
@@ -356,19 +130,22 @@ export function mergeDiscoveredModel<TApi extends Api>(
 	providerOverride?: Pick<ProviderOverride, "baseUrl" | "headers" | "transport">,
 ): Model<TApi> {
 	if (existing) {
-		return {
+		return buildModel({
 			...model,
 			baseUrl: providerOverride?.baseUrl ?? model.baseUrl ?? existing.baseUrl,
 			headers: existing.headers ? { ...existing.headers, ...model.headers } : model.headers,
-		};
+			transport: providerOverride?.transport ?? existing.transport ?? model.transport,
+			compat: model.compatConfig,
+		} as ModelSpec<TApi>);
 	}
 	if (providerOverride) {
-		return {
+		return buildModel({
 			...model,
 			baseUrl: providerOverride.baseUrl ?? model.baseUrl,
 			headers: providerOverride.headers ? { ...model.headers, ...providerOverride.headers } : model.headers,
 			...(providerOverride.transport !== undefined ? { transport: providerOverride.transport } : {}),
-		};
+			compat: model.compatConfig,
+		} as ModelSpec<TApi>);
 	}
 	return model;
 }
@@ -383,7 +160,7 @@ function isAuthoritativeProjectCatalogModel(model: Model<Api>): boolean {
 	return (
 		model.provider === "google-vertex" &&
 		model.api === "openai-completions" &&
-		model.baseUrl.includes("/endpoints/openapi")
+		isVertexExpressOpenAIUrl(model.baseUrl)
 	);
 }
 
@@ -401,14 +178,32 @@ function dropProviderModels(models: readonly Model<Api>[], providers: ReadonlySe
 	return models.filter(model => !providers.has(model.provider));
 }
 
-interface DiscoveryProviderConfig {
-	provider: string;
-	api: Api;
-	baseUrl?: string;
-	headers?: Record<string, string>;
-	compat?: Model<Api>["compat"];
-	discovery: ProviderDiscovery;
-	optional?: boolean;
+/**
+ * Merge `incoming` entries into a copy of `base`, keyed by `provider`+`id`.
+ * Matches are replaced with `combine(existing, entry)`; new entries are
+ * appended as `combine(undefined, entry)`.
+ */
+function mergeByModelKey<T extends { provider: string; id: string }>(
+	base: readonly Model<Api>[],
+	incoming: readonly T[],
+	combine: (existing: Model<Api> | undefined, entry: T) => Model<Api>,
+): Model<Api>[] {
+	const merged = [...base];
+	const indexByKey = new Map<string, number>();
+	for (let i = 0; i < merged.length; i += 1) {
+		indexByKey.set(`${merged[i].provider}\u0000${merged[i].id}`, i);
+	}
+	for (const entry of incoming) {
+		const key = `${entry.provider}\u0000${entry.id}`;
+		const existingIndex = indexByKey.get(key);
+		if (existingIndex !== undefined) {
+			merged[existingIndex] = combine(merged[existingIndex], entry);
+		} else {
+			merged.push(combine(undefined, entry));
+			indexByKey.set(key, merged.length - 1);
+		}
+	}
+	return merged;
 }
 
 interface BuiltInDiscoveryResult {
@@ -433,6 +228,12 @@ export interface CanonicalModelQueryOptions {
 	candidates?: readonly Model<Api>[];
 }
 
+/** A canonical record (with query-filtered variants) plus the variant model selected for it. */
+export interface CanonicalModelSelection {
+	record: CanonicalModelRecord;
+	model: Model<Api>;
+}
+
 /** Result of loading custom models from models.json */
 interface CustomModelsResult {
 	models?: CustomModelOverlay[];
@@ -446,78 +247,50 @@ interface CustomModelsResult {
 	found: boolean;
 }
 
-type OllamaDiscoveredModelMetadata = {
-	reasoning: boolean;
-	input: ("text" | "image")[];
-	contextWindow?: number;
-};
+const commandValueCache = new Map<string, string>();
 
-type LlamaCppDiscoveredServerMetadata = {
-	contextWindow?: number;
-	input?: ("text" | "image")[];
-};
-
-/**
- * Resolve an API key config value to an actual key.
- * Checks environment variable first, then treats as literal.
- */
-function resolveApiKeyConfig(keyConfig: string): string | undefined {
-	const envValue = Bun.env[keyConfig];
-	if (envValue) return envValue;
-	return keyConfig;
+function isCommandConfigValue(valueConfig: string | undefined): valueConfig is string {
+	return valueConfig?.startsWith("!") === true;
 }
 
-function toPositiveNumberOrUndefined(value: unknown): number | undefined {
-	if (typeof value === "number" && Number.isFinite(value) && value > 0) {
-		return value;
-	}
-	if (typeof value === "string" && value.trim()) {
-		const parsed = Number(value);
-		if (Number.isFinite(parsed) && parsed > 0) {
-			return parsed;
-		}
-	}
-	return undefined;
-}
-
-function extractOllamaContextWindow(payload: Record<string, unknown>): number | undefined {
-	const modelInfo = payload.model_info;
-	if (isRecord(modelInfo)) {
-		for (const [key, value] of Object.entries(modelInfo)) {
-			if (key === "context_length" || key.endsWith(".context_length")) {
-				const contextWindow = toPositiveNumberOrUndefined(value);
-				if (contextWindow !== undefined) {
-					return contextWindow;
-				}
-			}
-		}
-	}
-
-	const parameters = payload.parameters;
-	if (typeof parameters !== "string") {
+function resolveCommandConfig(command: string): string | undefined {
+	const cached = commandValueCache.get(command);
+	if (cached !== undefined) return cached;
+	try {
+		const stdout = execSync(command, { encoding: "utf8", timeout: 10_000, windowsHide: true });
+		const trimmed = stdout.trim();
+		if (trimmed.length === 0) return undefined;
+		commandValueCache.set(command, trimmed);
+		return trimmed;
+	} catch {
 		return undefined;
 	}
-	const match = parameters.match(/(?:^|\n)\s*num_ctx\s+(\d+)\s*(?:$|\n)/m);
-	return match ? toPositiveNumberOrUndefined(match[1]) : undefined;
 }
 
-function extractLlamaCppContextWindow(payload: Record<string, unknown>): number | undefined {
-	const generationSettings = payload.default_generation_settings;
-	if (isRecord(generationSettings)) {
-		const contextWindow = toPositiveNumberOrUndefined(generationSettings.n_ctx);
-		if (contextWindow !== undefined) {
-			return contextWindow;
-		}
-	}
-	return toPositiveNumberOrUndefined(payload.n_ctx);
+interface CommandApiKeyResolution {
+	configured: boolean;
+	value?: string;
+}
+/**
+ * Resolve a models.yml secret/config value to an actual value.
+ * `!cmd` runs a shell command and returns trimmed stdout, otherwise env vars are
+ * checked first and the input falls back to a literal value.
+ */
+function resolveConfigValue(valueConfig: string): string | undefined {
+	if (valueConfig.startsWith("!")) return resolveCommandConfig(valueConfig.slice(1).trim());
+	const envValue = Bun.env[valueConfig];
+	if (envValue) return envValue;
+	return valueConfig;
 }
 
-function extractLlamaCppInputCapabilities(payload: Record<string, unknown>): ("text" | "image")[] | undefined {
-	const modalities = payload.modalities;
-	if (!isRecord(modalities)) {
-		return undefined;
+function resolveConfigHeaders(headers: Record<string, string> | undefined): Record<string, string> | undefined {
+	if (!headers) return undefined;
+	const resolved: Record<string, string> = {};
+	for (const [key, value] of Object.entries(headers)) {
+		const next = resolveConfigValue(value);
+		if (next) resolved[key] = next;
 	}
-	return modalities.vision === true ? ["text", "image"] : ["text"];
+	return Object.keys(resolved).length > 0 ? resolved : undefined;
 }
 
 function extractGoogleOAuthToken(value: string | undefined): string | undefined {
@@ -578,73 +351,99 @@ function mergeCompat<TBase extends object, TOverride extends object>(
 	return merged as TBase & TOverride;
 }
 
-function applyModelOverride(model: Model<Api>, override: ModelOverride): Model<Api> {
-	const result = { ...model };
-	if (override.name !== undefined) result.name = override.name;
-	if (override.reasoning !== undefined) result.reasoning = override.reasoning;
-	if (override.thinking !== undefined) result.thinking = override.thinking as ThinkingConfig;
-	if (override.input !== undefined) result.input = override.input as ("text" | "image")[];
-	if (override.contextWindow !== undefined) result.contextWindow = override.contextWindow;
-	if (override.maxTokens !== undefined) result.maxTokens = override.maxTokens;
-	if (override.omitMaxOutputTokens !== undefined) result.omitMaxOutputTokens = override.omitMaxOutputTokens;
-	if (override.contextPromotionTarget !== undefined) result.contextPromotionTarget = override.contextPromotionTarget;
-	if (override.premiumMultiplier !== undefined) result.premiumMultiplier = override.premiumMultiplier;
-	if (override.cost) {
-		result.cost = {
-			input: override.cost.input ?? model.cost.input,
-			output: override.cost.output ?? model.cost.output,
-			cacheRead: override.cost.cacheRead ?? model.cost.cacheRead,
-			cacheWrite: override.cost.cacheWrite ?? model.cost.cacheWrite,
-		};
-	}
-	if (override.headers) {
-		result.headers = { ...model.headers, ...override.headers };
-	}
-	result.compat = mergeCompat(model.compat, override.compat);
-	return enrichModelThinking(result);
+/**
+ * Project a built model back to spec shape for the model-manager/cache
+ * boundary: sparse compat comes from `compatConfig`, never from the resolved
+ * record.
+ */
+function toModelSpec<TApi extends Api>(model: Model<TApi>): ModelSpec<TApi> {
+	return { ...model, compat: model.compatConfig } as ModelSpec<TApi>;
 }
 
-interface CustomModelDefinitionLike {
-	id: string;
+/**
+ * The patchable subset of `Model` fields shared by `modelOverrides` entries,
+ * custom model definitions, and parsed custom-model overlays. `undefined`
+ * always means "leave the base value alone".
+ */
+interface ModelPatch {
 	name?: string;
-	api?: Api;
-	baseUrl?: string;
 	reasoning?: boolean;
 	thinking?: ThinkingConfig;
 	input?: ("text" | "image")[];
-	cost?: { input: number; output: number; cacheRead: number; cacheWrite: number };
+	cost?: Partial<Model<Api>["cost"]>;
 	contextWindow?: number;
 	maxTokens?: number;
 	omitMaxOutputTokens?: boolean;
 	headers?: Record<string, string>;
-	compat?: Model<Api>["compat"];
+	compat?: ModelSpec<Api>["compat"];
 	contextPromotionTarget?: string;
 	premiumMultiplier?: number;
 }
 
+/**
+ * How a patch treats the base model's transport metadata (headers/compat):
+ * - `merge`: fold the patch into the base's (modelOverrides semantics).
+ * - `replace`: the patch owns transport wholesale — same-id custom definitions
+ *   already folded provider-level headers/compat in during parsing, so bundled
+ *   transport metadata must not be re-merged (see `#mergeCustomModels`).
+ */
+type ModelTransportPolicy = "merge" | "replace";
+
+function applyModelPatch(base: Model<Api>, patch: ModelPatch, transport: ModelTransportPolicy): Model<Api> {
+	const result = { ...base };
+	if (patch.name !== undefined) result.name = patch.name;
+	if (patch.reasoning !== undefined) result.reasoning = patch.reasoning;
+	if (patch.thinking !== undefined) result.thinking = patch.thinking;
+	if (patch.input !== undefined) result.input = patch.input;
+	if (patch.contextWindow !== undefined) result.contextWindow = patch.contextWindow;
+	if (patch.maxTokens !== undefined) result.maxTokens = patch.maxTokens;
+	if (patch.omitMaxOutputTokens !== undefined) result.omitMaxOutputTokens = patch.omitMaxOutputTokens;
+	if (patch.contextPromotionTarget !== undefined) result.contextPromotionTarget = patch.contextPromotionTarget;
+	if (patch.premiumMultiplier !== undefined) result.premiumMultiplier = patch.premiumMultiplier;
+	if (patch.cost) {
+		result.cost = {
+			input: patch.cost.input ?? base.cost.input,
+			output: patch.cost.output ?? base.cost.output,
+			cacheRead: patch.cost.cacheRead ?? base.cost.cacheRead,
+			cacheWrite: patch.cost.cacheWrite ?? base.cost.cacheWrite,
+		};
+	}
+	let compat: ModelSpec<Api>["compat"];
+	if (transport === "merge") {
+		if (patch.headers) {
+			result.headers = { ...base.headers, ...patch.headers };
+		}
+		compat = mergeCompat(base.compatConfig, patch.compat);
+	} else {
+		result.headers = patch.headers;
+		compat = patch.compat;
+	}
+	return buildModel({ ...result, compat } as ModelSpec<Api>);
+}
+
+function applyModelOverride(model: Model<Api>, override: ModelOverride): Model<Api> {
+	return applyModelPatch(model, override as ModelPatch, "merge");
+}
+
+interface CustomModelDefinitionLike extends ModelPatch {
+	id: string;
+	api?: Api;
+	baseUrl?: string;
+	cost?: Model<Api>["cost"];
+}
+
 interface CustomModelBuildOptions {
 	useDefaults: boolean;
 }
 
-type CustomModelOverlay = {
+interface CustomModelOverlay extends ModelPatch {
 	id: string;
 	provider: string;
 	api: Api;
 	baseUrl: string;
-	name?: string;
-	reasoning?: boolean;
-	thinking?: ThinkingConfig;
-	input?: ("text" | "image")[];
-	cost?: { input: number; output: number; cacheRead: number; cacheWrite: number };
-	contextWindow?: number;
-	maxTokens?: number;
-	omitMaxOutputTokens?: boolean;
-	headers?: Record<string, string>;
-	compat?: Model<Api>["compat"];
-	contextPromotionTarget?: string;
-	premiumMultiplier?: number;
+	cost?: Model<Api>["cost"];
 	isOAuth?: boolean;
-};
+}
 
 function mergeCustomModelHeaders(
 	providerHeaders: Record<string, string> | undefined,
@@ -652,7 +451,8 @@ function mergeCustomModelHeaders(
 	authHeader: boolean | undefined,
 	apiKeyConfig: string | undefined,
 ): Record<string, string> | undefined {
-	return mergeAuthHeader({ ...providerHeaders, ...modelHeaders }, authHeader, apiKeyConfig);
+	const resolvedModelHeaders = resolveConfigHeaders(modelHeaders);
+	return mergeAuthHeader({ ...providerHeaders, ...resolvedModelHeaders }, authHeader, apiKeyConfig);
 }
 
 function mergeAuthHeader(
@@ -664,7 +464,7 @@ function mergeAuthHeader(
 	if (!authHeader || !apiKeyConfig) {
 		return nextHeaders;
 	}
-	const resolvedKey = resolveApiKeyConfig(apiKeyConfig);
+	const resolvedKey = resolveConfigValue(apiKeyConfig);
 	return resolvedKey ? { ...nextHeaders, Authorization: `Bearer ${resolvedKey}` } : nextHeaders;
 }
 
@@ -691,7 +491,7 @@ function buildCustomModelOverlay(
 	providerHeaders: Record<string, string> | undefined,
 	providerApiKey: string | undefined,
 	authHeader: boolean | undefined,
-	providerCompat: Model<Api>["compat"] | undefined,
+	providerCompat: ModelSpec<Api>["compat"] | undefined,
 	providerAuth: ProviderAuthMode | undefined,
 	modelDef: CustomModelDefinitionLike,
 ): CustomModelOverlay | undefined {
@@ -704,8 +504,8 @@ function buildCustomModelOverlay(
 		baseUrl: modelDef.baseUrl ?? providerBaseUrl,
 		name: modelDef.name,
 		reasoning: modelDef.reasoning,
-		thinking: modelDef.thinking as ThinkingConfig | undefined,
-		input: modelDef.input as ("text" | "image")[] | undefined,
+		thinking: modelDef.thinking,
+		input: modelDef.input,
 		cost: modelDef.cost,
 		contextWindow: modelDef.contextWindow,
 		maxTokens: modelDef.maxTokens,
@@ -718,125 +518,6 @@ function buildCustomModelOverlay(
 	};
 }
 
-// Custom provider entries often front a known upstream model through a local proxy.
-// Use bundled metadata for missing pricing/capability fields, but keep the custom transport.
-function shouldReplaceCustomReference(existing: Model<Api> | undefined, candidate: Model<Api>): boolean {
-	if (!existing) return true;
-	if (candidate.contextWindow !== existing.contextWindow) {
-		return candidate.contextWindow > existing.contextWindow;
-	}
-	if (candidate.maxTokens !== existing.maxTokens) {
-		return candidate.maxTokens > existing.maxTokens;
-	}
-	const existingHasCachePricing = existing.cost.cacheRead > 0 || existing.cost.cacheWrite > 0;
-	const candidateHasCachePricing = candidate.cost.cacheRead > 0 || candidate.cost.cacheWrite > 0;
-	if (candidateHasCachePricing !== existingHasCachePricing) {
-		return candidateHasCachePricing;
-	}
-	return existing.provider !== "openai" && candidate.provider === "openai";
-}
-
-function normalizeCustomReferenceKey(value: string): string {
-	return value.trim().toLowerCase();
-}
-
-function buildCustomReferenceMap(): Map<string, Model<Api>> {
-	const references = new Map<string, Model<Api>>();
-	for (const provider of getBundledProviders()) {
-		for (const model of getBundledModels(provider as Parameters<typeof getBundledModels>[0])) {
-			const candidate = model as Model<Api>;
-			const key = normalizeCustomReferenceKey(candidate.id);
-			if (shouldReplaceCustomReference(references.get(key), candidate)) {
-				references.set(key, candidate);
-			}
-		}
-	}
-	return references;
-}
-
-function buildCustomReferenceSuffixAliasMap(exactReferences: ReadonlyMap<string, Model<Api>>): Map<string, Model<Api>> {
-	const aliases = new Map<string, Model<Api>>();
-	for (const reference of exactReferences.values()) {
-		const slashIndex = reference.id.lastIndexOf("/");
-		if (slashIndex === -1) {
-			continue;
-		}
-		const suffix = reference.id.slice(slashIndex + 1);
-		const alias = getLongestModelLikeIdSegment(suffix);
-		if (!alias) {
-			continue;
-		}
-		if (shouldReplaceCustomReference(aliases.get(alias), reference)) {
-			aliases.set(alias, reference);
-		}
-	}
-	return aliases;
-}
-
-const customReferenceMap = buildCustomReferenceMap();
-const customReferenceSuffixAliasMap = buildCustomReferenceSuffixAliasMap(customReferenceMap);
-
-const CUSTOM_REFERENCE_TRAILING_MARKER_PATTERN =
-	/[-:](?:thinking|customtools|high|low|medium|minimal|xhigh|free|cloud|exacto|nitro|original|optimized|nvfp4|fp8|fp4|bf16|int8|int4|search)$/i;
-
-function stripCustomReferenceTrailingMarker(candidate: string): string | undefined {
-	const match = CUSTOM_REFERENCE_TRAILING_MARKER_PATTERN.exec(candidate);
-	return match ? candidate.slice(0, match.index) : undefined;
-}
-
-function getCustomReferenceCandidateIds(modelId: string): string[] {
-	const candidates = new Set<string>();
-	const queue = [modelId];
-	for (let index = 0; index < queue.length; index += 1) {
-		const candidate = queue[index]?.trim();
-		if (!candidate || candidates.has(candidate)) continue;
-		candidates.add(candidate);
-
-		for (const stripped of getBracketStrippedModelIdCandidates(candidate)) {
-			queue.push(stripped);
-		}
-		for (const segment of getModelLikeIdSegments(candidate)) {
-			queue.push(segment);
-		}
-
-		for (const suffix of [":cloud", "-cloud"] as const) {
-			if (candidate.toLowerCase().endsWith(suffix)) {
-				queue.push(candidate.slice(0, -suffix.length));
-			}
-		}
-
-		const slashIndex = candidate.lastIndexOf("/");
-		if (slashIndex !== -1) {
-			queue.push(candidate.slice(slashIndex + 1));
-		}
-
-		const colonToDash = candidate.replace(/:/g, "-");
-		if (colonToDash !== candidate) {
-			queue.push(colonToDash);
-		}
-
-		const lowercased = candidate.toLowerCase();
-		if (lowercased !== candidate) {
-			queue.push(lowercased);
-		}
-
-		const strippedMarker = stripCustomReferenceTrailingMarker(candidate);
-		if (strippedMarker) {
-			queue.push(strippedMarker);
-		}
-	}
-	return [...candidates];
-}
-
-function resolveCustomModelReference(modelId: string): Model<Api> | undefined {
-	for (const candidate of getCustomReferenceCandidateIds(modelId)) {
-		const key = normalizeCustomReferenceKey(candidate);
-		const reference = customReferenceMap.get(key) ?? customReferenceSuffixAliasMap.get(key);
-		if (reference) return reference;
-	}
-	return undefined;
-}
-
 function applyStandaloneCustomModelPolicies(model: CustomModelOverlay): CustomModelOverlay {
 	if (model.id !== "gpt-5.4" || model.provider === "github-copilot" || model.contextWindow !== undefined) {
 		return model;
@@ -846,13 +527,15 @@ function applyStandaloneCustomModelPolicies(model: CustomModelOverlay): CustomMo
 
 function finalizeCustomModel(model: CustomModelOverlay, options: CustomModelBuildOptions): Model<Api> {
 	const resolvedModel = options.useDefaults ? applyStandaloneCustomModelPolicies(model) : model;
-	const reference = options.useDefaults ? resolveCustomModelReference(resolvedModel.id) : undefined;
+	const reference = options.useDefaults
+		? resolveModelReference(resolvedModel.id, getBundledModelReferenceIndex())
+		: undefined;
 	const cost =
 		resolvedModel.cost ??
 		reference?.cost ??
 		(options.useDefaults ? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 } : undefined);
 	const input = resolvedModel.input ?? reference?.input ?? (options.useDefaults ? ["text"] : undefined);
-	return enrichModelThinking({
+	return buildModel({
 		id: resolvedModel.id,
 		name: resolvedModel.name ?? (options.useDefaults ? resolvedModel.id : undefined),
 		api: resolvedModel.api,
@@ -862,16 +545,15 @@ function finalizeCustomModel(model: CustomModelOverlay, options: CustomModelBuil
 		thinking: resolvedModel.thinking ?? reference?.thinking,
 		input: input as ("text" | "image")[],
 		cost,
-		contextWindow:
-			resolvedModel.contextWindow ?? reference?.contextWindow ?? (options.useDefaults ? 128000 : undefined),
-		maxTokens: resolvedModel.maxTokens ?? reference?.maxTokens ?? (options.useDefaults ? 16384 : undefined),
+		contextWindow: resolvedModel.contextWindow ?? reference?.contextWindow ?? (options.useDefaults ? 128000 : null),
+		maxTokens: resolvedModel.maxTokens ?? reference?.maxTokens ?? (options.useDefaults ? 16384 : null),
 		headers: resolvedModel.headers,
 		omitMaxOutputTokens: resolvedModel.omitMaxOutputTokens ?? reference?.omitMaxOutputTokens,
-		compat: mergeCompat(reference?.compat, resolvedModel.compat),
+		compat: mergeCompat(reference?.compatConfig, resolvedModel.compat),
 		contextPromotionTarget: resolvedModel.contextPromotionTarget,
 		premiumMultiplier: resolvedModel.premiumMultiplier,
 		isOAuth: resolvedModel.isOAuth,
-	} as Model<Api>);
+	} as ModelSpec<Api>);
 }
 
 function normalizeSuppressedSelector(selector: string): string {
@@ -879,7 +561,37 @@ function normalizeSuppressedSelector(selector: string): string {
 	if (!trimmed) return trimmed;
 	const parsed = parseModelString(trimmed);
 	if (!parsed) return trimmed;
-	return `${parsed.provider}/${parsed.id}`;
+	// Retired effort-tier variant ids normalize to their collapsed logical id
+	// so persisted suppressions keyed by raw member ids still bind.
+	const aliasId = resolveVariantAlias(parsed.provider, parsed.id);
+	return `${parsed.provider}/${aliasId ?? parsed.id}`;
+}
+
+/**
+ * Look up a model's override, falling back to entries keyed by retired
+ * effort-tier variant ids (models.yml authored before collapsing). A raw key
+ * only re-binds when no live model holds that id.
+ */
+function resolveModelOverrideWithAliases(
+	overrides: Map<string, ModelOverride>,
+	model: Model<Api>,
+	hasLiveModel: (provider: string, id: string) => boolean,
+): ModelOverride | undefined {
+	const direct = overrides.get(model.id);
+	if (direct) return direct;
+	for (const rawId of getVariantAliasSources(model.provider, model.id)) {
+		if (hasLiveModel(model.provider, rawId)) continue;
+		const remapped = overrides.get(rawId);
+		if (remapped) {
+			logger.debug("model override re-keyed through variant alias", {
+				provider: model.provider,
+				from: rawId,
+				to: model.id,
+			});
+			return remapped;
+		}
+	}
+	return undefined;
 }
 
 function getDisabledProviderIdsFromSettings(): Set<string> {
@@ -904,6 +616,7 @@ function getConfiguredProviderOrderFromSettings(): string[] {
 export class ModelRegistry {
 	#models: Model<Api>[] = [];
 	#canonicalIndex: CanonicalModelIndex = { records: [], byId: new Map(), bySelector: new Map() };
+	#canonicalIndexDirty: boolean = true;
 	#customProviderApiKeys: Map<string, string> = new Map();
 	#keylessProviders: Set<string> = new Set();
 	#discoverableProviders: DiscoveryProviderConfig[] = [];
@@ -927,8 +640,34 @@ export class ModelRegistry {
 	#runtimeProviderOverrides: Map<string, ProviderOverride> = new Map();
 	#runtimeProvidersBySource: Map<string, Set<string>> = new Map();
 	#runtimeProviderSourceByName: Map<string, string> = new Map();
+	// Runtime model managers registered by extensions via fetchDynamicModels.
+	// Keyed by provider name; use the same SQLite cache path as builtins.
+	#runtimeModelManagers: Map<string, { options: ModelManagerOptions<Api>; sourceId: string }> = new Map();
 	#rebuildPending: boolean = false;
 	#rebuildSuspended: number = 0;
+	#fetch: FetchImpl;
+
+	#resolveCommandBackedApiKey(provider: string): CommandApiKeyResolution {
+		const keyConfig = this.#customProviderApiKeys.get(provider);
+		if (!isCommandConfigValue(keyConfig)) return { configured: false };
+		const value = resolveConfigValue(keyConfig);
+		if (value) {
+			this.authStorage.setConfigApiKey(provider, value);
+			return { configured: true, value };
+		}
+		this.authStorage.removeConfigApiKey(provider);
+		return { configured: true };
+	}
+
+	#installProviderApiKey(provider: string, keyConfig: string): void {
+		this.#customProviderApiKeys.set(provider, keyConfig);
+		const resolved = resolveConfigValue(keyConfig);
+		if (resolved) {
+			this.authStorage.setConfigApiKey(provider, resolved);
+		} else if (isCommandConfigValue(keyConfig)) {
+			this.authStorage.removeConfigApiKey(provider);
+		}
+	}
 
 	/**
 	 * @param authStorage - Auth storage for API key resolution
@@ -942,16 +681,16 @@ export class ModelRegistry {
 	constructor(
 		readonly authStorage: AuthStorage,
 		modelsPath?: string,
+		options?: { fetch?: FetchImpl },
 	) {
+		this.#fetch = options?.fetch ?? fetch;
 		this.#modelsConfigFile = ModelsConfigFile.relocate(modelsPath);
 		this.#cacheDbPath = modelsPath ? path.join(path.dirname(modelsPath), "models.db") : undefined;
 		// Set up fallback resolver for custom provider API keys
 		this.authStorage.setFallbackResolver(provider => {
 			const keyConfig = this.#customProviderApiKeys.get(provider);
-			if (keyConfig) {
-				return resolveApiKeyConfig(keyConfig);
-			}
-			return undefined;
+			if (!keyConfig) return undefined;
+			return resolveConfigValue(keyConfig);
 		});
 		// Load models synchronously in constructor.
 		this.#loadModels();
@@ -1004,6 +743,27 @@ export class ModelRegistry {
 		}
 	}
 
+	/**
+	 * Discover models for providers registered at runtime via `fetchDynamicModels`
+	 * (extension providers). Merges the discovered catalog into the existing model
+	 * set without reloading static models, so dynamically-discovered models from
+	 * other providers are preserved. No-op when no runtime providers are registered.
+	 *
+	 * Drives the same SQLite model cache as built-in providers, so the default
+	 * `online-if-uncached` strategy fetches at most once per cache TTL (24 h).
+	 */
+	async refreshRuntimeProviders(strategy: ModelRefreshStrategy = "online-if-uncached"): Promise<void> {
+		if (this.#runtimeModelManagers.size === 0) {
+			return;
+		}
+		this.#suspendRebuild();
+		try {
+			await this.#refreshRuntimeDiscoveries(strategy, new Set(this.#runtimeModelManagers.keys()));
+		} finally {
+			this.#resumeRebuild();
+		}
+	}
+
 	#reloadStaticModels(): void {
 		const currentMtime = this.#modelsConfigFile.getMtimeMs();
 		if (currentMtime !== null && currentMtime === this.#lastStaticLoadMtime) {
@@ -1021,7 +781,7 @@ export class ModelRegistry {
 		// Restore runtime API keys before #loadModels — survives because
 		// #loadModels only calls .set() on #customProviderApiKeys, never reassigns it.
 		for (const [k, v] of this.#runtimeProviderApiKeys) {
-			this.#customProviderApiKeys.set(k, v);
+			this.#installProviderApiKey(k, v);
 		}
 		this.#providerOverrides.clear();
 		this.#modelOverrides.clear();
@@ -1089,7 +849,9 @@ export class ModelRegistry {
 		const withConfigModels = this.#mergeCustomModels(resolvedDefaults, this.#customModelOverlays);
 		// Merge runtime extension models so they survive refresh() cycles
 		const combined = this.#mergeCustomModels(withConfigModels, this.#runtimeModelOverlays);
-		const withModelOverrides = this.#applyModelOverrides(combined, this.#modelOverrides);
+		// Custom/config providers bypass the model-manager merge point —
+		// collapse effort-tier variants here so X/X-thinking twins fold.
+		const withModelOverrides = this.#applyModelOverrides(collapseBuiltModelVariants(combined), this.#modelOverrides);
 		this.#models = this.#applyRuntimeProviderOverrides(withModelOverrides);
 		this.#rebuildCanonicalIndex();
 		this.#lastStaticLoadMtime = this.#modelsConfigFile.getMtimeMs();
@@ -1105,84 +867,55 @@ export class ModelRegistry {
 			return models.map(m => {
 				if (!providerOverride) return m;
 				const withTransportOverride = this.#applyProviderTransportOverride(m, providerOverride);
-				return {
+				return buildModel({
 					...withTransportOverride,
-					compat: mergeCompat(m.compat, providerOverride.compat),
-				};
+					compat: mergeCompat(m.compatConfig, providerOverride.compat),
+				} as ModelSpec<Api>);
 			});
 		});
 	}
 
 	#mergeResolvedModels(baseModels: Model<Api>[], replacementModels: Model<Api>[]): Model<Api>[] {
-		const merged = [...baseModels];
-		const indexByKey = new Map<string, number>();
-		for (let i = 0; i < merged.length; i += 1) {
-			const m = merged[i];
-			indexByKey.set(`${m.provider}\u0000${m.id}`, i);
-		}
-		for (const replacementModel of replacementModels) {
-			const key = `${replacementModel.provider}\u0000${replacementModel.id}`;
-			const existingIndex = indexByKey.get(key);
-			if (existingIndex !== undefined) {
-				const existing = merged[existingIndex];
-				merged[existingIndex] = {
-					...replacementModel,
-					contextWindow:
-						replacementModel.contextWindow === UNK_CONTEXT_WINDOW
-							? existing.contextWindow
-							: replacementModel.contextWindow,
-					maxTokens:
-						replacementModel.maxTokens === UNK_MAX_TOKENS ? existing.maxTokens : replacementModel.maxTokens,
-				};
-			} else {
-				merged.push(replacementModel);
-				indexByKey.set(key, merged.length - 1);
-			}
-		}
-		return merged;
+		return mergeByModelKey(baseModels, replacementModels, (existing, replacementModel) => {
+			if (!existing) return replacementModel;
+			return {
+				...replacementModel,
+				contextWindow: replacementModel.contextWindow ?? existing.contextWindow,
+				maxTokens: replacementModel.maxTokens ?? existing.maxTokens,
+			};
+		});
 	}
 
 	/** Merge custom models with built-in, replacing by provider+id match */
 	#mergeCustomModels(builtInModels: Model<Api>[], customModels: CustomModelOverlay[]): Model<Api>[] {
-		const merged = [...builtInModels];
-		const indexByKey = new Map<string, number>();
-		for (let i = 0; i < merged.length; i += 1) {
-			const m = merged[i];
-			indexByKey.set(`${m.provider}\u0000${m.id}`, i);
-		}
-		for (const customModel of customModels) {
-			const key = `${customModel.provider}\u0000${customModel.id}`;
-			const existingIndex = indexByKey.get(key);
-			if (existingIndex !== undefined) {
-				const existingModel = merged[existingIndex];
-				merged[existingIndex] = enrichModelThinking({
+		return mergeByModelKey(builtInModels, customModels, (existingModel, customModel) => {
+			if (!existingModel) return finalizeCustomModel(customModel, { useDefaults: true });
+			// Same-id custom definitions replace bundled transport behavior, so the
+			// patch is applied with the `replace` transport policy.
+			return applyModelPatch(
+				{
 					...existingModel,
 					id: customModel.id,
 					provider: customModel.provider,
 					api: customModel.api,
 					baseUrl: customModel.baseUrl,
-					name: customModel.name ?? existingModel.name,
-					reasoning: customModel.reasoning ?? existingModel.reasoning,
-					thinking: customModel.thinking ?? existingModel.thinking,
-					input: customModel.input ?? existingModel.input,
-					cost: customModel.cost ?? existingModel.cost,
-					contextWindow: customModel.contextWindow ?? existingModel.contextWindow,
-					maxTokens: customModel.maxTokens ?? existingModel.maxTokens,
-					omitMaxOutputTokens: customModel.omitMaxOutputTokens ?? existingModel.omitMaxOutputTokens,
-					// Same-id custom definitions replace bundled transport behavior. Provider-level
-					// headers/compat were already folded into customModel during parsing; do not
-					// re-merge bundled transport metadata here.
-					headers: customModel.headers,
-					compat: customModel.compat,
-					contextPromotionTarget: customModel.contextPromotionTarget ?? existingModel.contextPromotionTarget,
-					premiumMultiplier: customModel.premiumMultiplier ?? existingModel.premiumMultiplier,
-				} as Model<Api>);
-			} else {
-				merged.push(finalizeCustomModel(customModel, { useDefaults: true }));
-				indexByKey.set(key, merged.length - 1);
-			}
+				},
+				customModel,
+				"replace",
+			);
+		});
+	}
+
+	#resolveStartupModelCacheProviderId(providerId: string): string {
+		const descriptor = PROVIDER_DESCRIPTORS.find(candidate => candidate.providerId === providerId);
+		if (!descriptor) {
+			return providerId;
 		}
-		return merged;
+		const baseUrl =
+			this.#runtimeProviderOverrides.get(providerId)?.baseUrl ??
+			this.#providerOverrides.get(providerId)?.baseUrl ??
+			this.getProviderBaseUrl(providerId);
+		return descriptor.createModelManagerOptions({ baseUrl, fetch: this.#fetch }).cacheProviderId ?? providerId;
 	}
 
 	#loadCachedStandardProviderModels(): { models: Model<Api>[]; authoritativeFreshProviders: Set<string> } {
@@ -1193,7 +926,8 @@ export class ModelRegistry {
 			if (configuredDiscoveryProviders.has(providerId)) {
 				continue;
 			}
-			const cache = readModelCache<Api>(providerId, 24 * 60 * 60 * 1000, Date.now, this.#cacheDbPath);
+			const cacheProviderId = this.#resolveStartupModelCacheProviderId(providerId);
+			const cache = readModelCache<Api>(cacheProviderId, 24 * 60 * 60 * 1000, Date.now, this.#cacheDbPath);
 			if (!cache) {
 				continue;
 			}
@@ -1208,8 +942,13 @@ export class ModelRegistry {
 				? models.map(model => this.#applyProviderTransportOverride(model, providerOverride))
 				: models;
 			const withCompat = providerOverride?.compat
-				? withTransport.map(model => ({ ...model, compat: mergeCompat(model.compat, providerOverride.compat) }))
-				: withTransport;
+				? withTransport.map(model =>
+						buildModel({
+							...model,
+							compat: mergeCompat(model.compat, providerOverride.compat),
+						} as ModelSpec<Api>),
+					)
+				: withTransport.map(model => buildModel(model));
 			cachedModels.push(...this.#applyProviderModelOverrides(providerId, withCompat));
 		}
 		return { models: cachedModels, authoritativeFreshProviders };
@@ -1218,7 +957,12 @@ export class ModelRegistry {
 	#loadCachedDiscoverableModels(): Model<Api>[] {
 		const cachedModels: Model<Api>[] = [];
 		for (const providerConfig of this.#discoverableProviders) {
-			const cache = readModelCache<Api>(providerConfig.provider, 24 * 60 * 60 * 1000, Date.now, this.#cacheDbPath);
+			const cache = readModelCache<Api>(
+				this.#configuredDiscoveryCacheProviderId(providerConfig),
+				24 * 60 * 60 * 1000,
+				Date.now,
+				this.#cacheDbPath,
+			);
 			if (!cache) {
 				this.#providerDiscoveryStates.set(providerConfig.provider, {
 					provider: providerConfig.provider,
@@ -1233,7 +977,10 @@ export class ModelRegistry {
 				providerConfig.provider,
 				this.#normalizeDiscoverableModels(
 					providerConfig,
-					this.#applyProviderCompat(providerConfig.compat, cache.models),
+					this.#applyProviderCompat(
+						providerConfig.compat,
+						cache.models.map(model => buildModel(model)),
+					),
 				),
 			);
 			cachedModels.push(...models);
@@ -1249,9 +996,11 @@ export class ModelRegistry {
 		return cachedModels;
 	}
 
-	#applyProviderCompat(compat: Model<Api>["compat"] | undefined, models: Model<Api>[]): Model<Api>[] {
+	#applyProviderCompat(compat: ModelSpec<Api>["compat"] | undefined, models: Model<Api>[]): Model<Api>[] {
 		if (!compat) return models;
-		return models.map(model => ({ ...model, compat: mergeCompat(model.compat, compat) }));
+		return models.map(model =>
+			buildModel({ ...model, compat: mergeCompat(model.compatConfig, compat) } as ModelSpec<Api>),
+		);
 	}
 
 	#normalizeDiscoverableModels(providerConfig: DiscoveryProviderConfig, models: Model<Api>[]): Model<Api>[] {
@@ -1261,7 +1010,14 @@ export class ModelRegistry {
 
 		const contextLengthOverride = getOllamaContextLengthOverride();
 		return models.map(model => {
-			const normalized = model.api === "openai-completions" ? { ...model, api: "openai-responses" as const } : model;
+			const normalized =
+				model.api === "openai-completions"
+					? buildModel({
+							...model,
+							api: "openai-responses" as const,
+							compat: model.compatConfig,
+						} as ModelSpec<Api>)
+					: model;
 			if (contextLengthOverride === undefined) {
 				return normalized;
 			}
@@ -1344,10 +1100,11 @@ export class ModelRegistry {
 		const configuredProviders = new Set(Object.keys(value.providers ?? {}));
 
 		for (const [providerName, providerConfig] of providerEntries) {
+			const resolvedProviderHeaders = resolveConfigHeaders(providerConfig.headers);
 			// Always set overrides when baseUrl/headers/apiKey/authHeader/compat/disableStrictTools/transport are present
 			if (
 				providerConfig.baseUrl ||
-				providerConfig.headers ||
+				resolvedProviderHeaders ||
 				providerConfig.apiKey ||
 				providerConfig.authHeader !== undefined ||
 				providerConfig.compat ||
@@ -1357,7 +1114,7 @@ export class ModelRegistry {
 				const disableStrictCompat = providerConfig.disableStrictTools ? { disableStrictTools: true } : undefined;
 				overrides.set(providerName, {
 					baseUrl: providerConfig.baseUrl,
-					headers: providerConfig.headers,
+					headers: resolvedProviderHeaders,
 					apiKey: providerConfig.apiKey,
 					authHeader: providerConfig.authHeader,
 					compat: mergeCompat(providerConfig.compat, disableStrictCompat),
@@ -1379,7 +1136,7 @@ export class ModelRegistry {
 					// fallback for entries that don't advertise one.
 					api: (providerConfig.api ?? "openai-completions") as Api,
 					baseUrl: providerConfig.baseUrl,
-					headers: providerConfig.headers,
+					headers: resolvedProviderHeaders,
 					compat: mergeCompat(providerConfig.compat, disableStrictCompat),
 					discovery: providerConfig.discovery,
 					optional: false,
@@ -1391,16 +1148,17 @@ export class ModelRegistry {
 			// bearer in models.yml (e.g. for an auth-gateway baseUrl), that bearer
 			// must authenticate the outbound request.
 			if (providerConfig.apiKey) {
-				this.#customProviderApiKeys.set(providerName, providerConfig.apiKey);
-				const resolved = resolveApiKeyConfig(providerConfig.apiKey);
-				if (resolved) this.authStorage.setConfigApiKey(providerName, resolved);
+				this.#installProviderApiKey(providerName, providerConfig.apiKey);
 			}
 
 			// Parse per-model overrides
 			if (providerConfig.modelOverrides) {
 				const perModel = new Map<string, ModelOverride>();
 				for (const [modelId, override] of Object.entries(providerConfig.modelOverrides)) {
-					perModel.set(modelId, override);
+					perModel.set(
+						modelId,
+						override.headers ? { ...override, headers: resolveConfigHeaders(override.headers) } : override,
+					);
 				}
 				allModelOverrides.set(providerName, perModel);
 			}
@@ -1461,16 +1219,24 @@ export class ModelRegistry {
 		const withConfigModels = this.#mergeCustomModels(resolved, this.#customModelOverlays);
 		// Merge runtime extension models so they survive online discovery completion
 		const combined = this.#mergeCustomModels(withConfigModels, this.#runtimeModelOverlays);
-		const withModelOverrides = this.#applyModelOverrides(combined, this.#modelOverrides);
+		const withModelOverrides = this.#applyModelOverrides(collapseBuiltModelVariants(combined), this.#modelOverrides);
 		this.#models = this.#applyRuntimeProviderOverrides(withModelOverrides);
 		this.#rebuildCanonicalIndex();
 	}
 
+	#configuredDiscoveryCacheProviderId(providerConfig: DiscoveryProviderConfig): string {
+		if (providerConfig.discovery.type === "openai-models-list") {
+			return `${providerConfig.provider}:openai-models-list-context-v2`;
+		}
+		return providerConfig.provider;
+	}
+
 	async #discoverProviderModels(
 		providerConfig: DiscoveryProviderConfig,
 		strategy: ModelRefreshStrategy,
 	): Promise<Model<Api>[]> {
-		const cached = readModelCache<Api>(providerConfig.provider, 24 * 60 * 60 * 1000, Date.now, this.#cacheDbPath);
+		const cacheProviderId = this.#configuredDiscoveryCacheProviderId(providerConfig);
+		const cached = readModelCache<Api>(cacheProviderId, 24 * 60 * 60 * 1000, Date.now, this.#cacheDbPath);
 		const requiresAuth = !this.#keylessProviders.has(providerConfig.provider);
 		if (requiresAuth) {
 			const apiKey = await this.#peekApiKeyForProvider(providerConfig.provider);
@@ -1484,17 +1250,20 @@ export class ModelRegistry {
 					models: cached?.models.map(model => model.id) ?? [],
 				});
 				this.#lastDiscoveryWarnings.delete(providerConfig.provider);
-				return cached?.models ?? [];
+				return cached ? cached.models.map(model => buildModel(model)) : [];
 			}
 		}
 
 		const providerId = providerConfig.provider;
 		let discoveryError: string | undefined;
-		const fetchDynamicModels = async (): Promise<readonly Model<Api>[] | null> => {
+		const fetchDynamicModels = async (): Promise<readonly ModelSpec<Api>[] | null> => {
 			try {
-				const models = await this.#discoverModelsByProviderType(providerConfig);
+				const models = this.#applyProviderModelOverrides(
+					providerId,
+					await discoverModelsByProviderType(providerConfig, this.#discoveryContext()),
+				);
 				this.#lastDiscoveryWarnings.delete(providerId);
-				return models;
+				return models.map(toModelSpec);
 			} catch (error) {
 				discoveryError = error instanceof Error ? error.message : String(error);
 				return null;
@@ -1505,6 +1274,7 @@ export class ModelRegistry {
 			providerId,
 			staticModels: [],
 			cacheDbPath: this.#cacheDbPath,
+			cacheProviderId,
 			cacheTtlMs: 24 * 60 * 60 * 1000,
 			fetchDynamicModels,
 		});
@@ -1541,18 +1311,17 @@ export class ModelRegistry {
 		);
 	}
 
-	#discoverModelsByProviderType(providerConfig: DiscoveryProviderConfig): Promise<Model<Api>[]> {
-		switch (providerConfig.discovery.type) {
-			case "ollama":
-				return this.#discoverOllamaModels(providerConfig);
-			case "llama.cpp":
-				return this.#discoverLlamaCppModels(providerConfig);
-			case "lm-studio":
-			case "openai-models-list":
-				return this.#discoverOpenAIModelsList(providerConfig);
-			case "proxy":
-				return this.#discoverProxyModels(providerConfig);
-		}
+	#discoveryContext(): DiscoveryContext {
+		return {
+			fetch: this.#fetch,
+			getBearerApiKeyResolver: async provider => {
+				const apiKey = await this.getApiKeyForProvider(provider);
+				if (!isDiscoveryBearerApiKey(apiKey)) {
+					return undefined;
+				}
+				return this.resolver(provider);
+			},
+		};
 	}
 
 	#warnProviderDiscoveryFailure(providerConfig: DiscoveryProviderConfig, error: string): void {
@@ -1610,6 +1379,7 @@ export class ModelRegistry {
 					googleAntigravityModelManagerOptions({
 						oauthToken,
 						endpoint: this.getProviderBaseUrl("google-antigravity"),
+						fetch: this.#fetch,
 					}),
 			},
 			{
@@ -1619,6 +1389,7 @@ export class ModelRegistry {
 					googleGeminiCliModelManagerOptions({
 						oauthToken,
 						endpoint: this.getProviderBaseUrl("google-gemini-cli"),
+						fetch: this.#fetch,
 					}),
 			},
 			{
@@ -1652,11 +1423,21 @@ export class ModelRegistry {
 		for (let i = 0; i < standardProviderDescriptors.length; i++) {
 			const descriptor = standardProviderDescriptors[i];
 			const apiKey = standardProviderKeys[i];
-			if (isAuthenticated(apiKey) || descriptor.allowUnauthenticated) {
+			const hasExplicitVllmConfig =
+				descriptor.providerId === "vllm" &&
+				(this.#runtimeProviderOverrides.has(descriptor.providerId) ||
+					this.#providerOverrides.has(descriptor.providerId) ||
+					this.#keylessProviders.has(descriptor.providerId));
+			if (isAuthenticated(apiKey) || descriptor.allowUnauthenticated || hasExplicitVllmConfig) {
+				const discoveryBaseUrl =
+					this.#runtimeProviderOverrides.get(descriptor.providerId)?.baseUrl ??
+					this.#providerOverrides.get(descriptor.providerId)?.baseUrl ??
+					this.getProviderBaseUrl(descriptor.providerId);
 				options.push(
 					descriptor.createModelManagerOptions({
-						apiKey: isAuthenticated(apiKey) ? apiKey : undefined,
-						baseUrl: this.getProviderBaseUrl(descriptor.providerId),
+						apiKey: isDiscoveryBearerApiKey(apiKey) ? apiKey : undefined,
+						baseUrl: discoveryBaseUrl,
+						fetch: this.#fetch,
 					}),
 				);
 			}
@@ -1670,6 +1451,10 @@ export class ModelRegistry {
 			}
 			options.push(descriptor.createOptions(key));
 		}
+		// Append runtime model managers registered by extensions via fetchDynamicModels.
+		for (const { options: managerOpts } of this.#runtimeModelManagers.values()) {
+			options.push(managerOpts);
+		}
 		return options;
 	}
 
@@ -1697,366 +1482,16 @@ export class ModelRegistry {
 		}
 	}
 
-	async #discoverOllamaModelMetadata(
-		endpoint: string,
-		modelId: string,
-		headers: Record<string, string> | undefined,
-	): Promise<OllamaDiscoveredModelMetadata | null> {
-		const showUrl = `${endpoint}/api/show`;
-		try {
-			const response = await fetch(showUrl, {
-				method: "POST",
-				headers: { ...(headers ?? {}), "Content-Type": "application/json" },
-				body: JSON.stringify({ model: modelId }),
-				signal: AbortSignal.timeout(150),
-			});
-			if (!response.ok) {
-				return null;
-			}
-			const payload = (await response.json()) as unknown;
-			if (!isRecord(payload)) {
-				return null;
-			}
-			const contextWindow = extractOllamaContextWindow(payload);
-			const capabilities = payload.capabilities;
-			if (Array.isArray(capabilities)) {
-				const normalized = new Set(
-					capabilities.flatMap(capability => (typeof capability === "string" ? [capability.toLowerCase()] : [])),
-				);
-				const supportsVision = normalized.has("vision") || normalized.has("image");
-				return {
-					reasoning: normalized.has("thinking"),
-					input: supportsVision ? ["text", "image"] : ["text"],
-					contextWindow,
-				};
-			}
-			if (!isRecord(capabilities)) {
-				return {
-					reasoning: false,
-					input: ["text"],
-					contextWindow,
-				};
-			}
-			const supportsVision = capabilities.vision === true || capabilities.image === true;
-			return {
-				reasoning: capabilities.thinking === true,
-				input: supportsVision ? ["text", "image"] : ["text"],
-				contextWindow,
-			};
-		} catch {
-			return null;
-		}
-	}
-
-	async #discoverOllamaModels(providerConfig: DiscoveryProviderConfig): Promise<Model<Api>[]> {
-		const endpoint = this.#normalizeOllamaBaseUrl(providerConfig.baseUrl);
-		const tagsUrl = `${endpoint}/api/tags`;
-		const headers = { ...(providerConfig.headers ?? {}) };
-		const response = await fetch(tagsUrl, {
-			headers,
-			signal: AbortSignal.timeout(250),
-		});
-		if (!response.ok) {
-			throw new Error(`HTTP ${response.status} from ${tagsUrl}`);
-		}
-		const payload = (await response.json()) as { models?: Array<{ name?: string; model?: string }> };
-		const entries = (payload.models ?? []).flatMap(item => {
-			const id = item.model || item.name;
-			return id ? [{ id, name: item.name || id }] : [];
-		});
-		const metadataById = new Map(
-			await Promise.all(
-				entries.map(
-					async entry => [entry.id, await this.#discoverOllamaModelMetadata(endpoint, entry.id, headers)] as const,
-				),
-			),
-		);
-		const discovered = entries.map(entry => {
-			const metadata = metadataById.get(entry.id);
-			return enrichModelThinking({
-				id: entry.id,
-				name: entry.name,
-				api: providerConfig.api,
-				provider: providerConfig.provider,
-				baseUrl: `${endpoint}/v1`,
-				reasoning: metadata?.reasoning ?? false,
-				input: metadata?.input ?? ["text"],
-				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-				contextWindow: metadata?.contextWindow ?? 128000,
-				maxTokens: Math.min(metadata?.contextWindow ?? Number.POSITIVE_INFINITY, DISCOVERY_DEFAULT_MAX_TOKENS),
-				headers: providerConfig.headers,
-			});
-		});
-		return this.#applyProviderModelOverrides(providerConfig.provider, discovered);
-	}
-
-	async #discoverLlamaCppServerMetadata(
-		baseUrl: string,
-		headers: Record<string, string> | undefined,
-	): Promise<LlamaCppDiscoveredServerMetadata | null> {
-		const propsUrl = `${this.#toLlamaCppNativeBaseUrl(baseUrl)}/props`;
-		try {
-			const response = await fetch(propsUrl, {
-				headers,
-				signal: AbortSignal.timeout(150),
-			});
-			if (!response.ok) {
-				return null;
-			}
-			const payload = (await response.json()) as unknown;
-			if (!isRecord(payload)) {
-				return null;
-			}
-			return {
-				contextWindow: extractLlamaCppContextWindow(payload),
-				input: extractLlamaCppInputCapabilities(payload),
-			};
-		} catch {
-			return null;
-		}
-	}
-
-	async #discoverLlamaCppModels(providerConfig: DiscoveryProviderConfig): Promise<Model<Api>[]> {
-		const baseUrl = this.#normalizeLlamaCppBaseUrl(providerConfig.baseUrl);
-		const modelsUrl = `${baseUrl}/models`;
-
-		const headers: Record<string, string> = { ...(providerConfig.headers ?? {}) };
-		const apiKey = await this.authStorage.getApiKey(providerConfig.provider);
-		if (apiKey && apiKey !== DEFAULT_LOCAL_TOKEN && apiKey !== kNoAuth) {
-			headers.Authorization = `Bearer ${apiKey}`;
-		}
-
-		const [response, serverMetadata] = await Promise.all([
-			fetch(modelsUrl, {
-				headers,
-				signal: AbortSignal.timeout(250),
-			}),
-			this.#discoverLlamaCppServerMetadata(baseUrl, headers),
-		]);
-		if (!response.ok) {
-			throw new Error(`HTTP ${response.status} from ${modelsUrl}`);
-		}
-		const payload = (await response.json()) as { data?: Array<{ id: string }> };
-		const models = payload.data ?? [];
-		const discovered: Model<Api>[] = [];
-		for (const item of models) {
-			const id = item.id;
-			if (!id) continue;
-			discovered.push(
-				enrichModelThinking({
-					id,
-					name: id,
-					api: providerConfig.api,
-					provider: providerConfig.provider,
-					baseUrl,
-					reasoning: false,
-					input: serverMetadata?.input ?? ["text"],
-					cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-					contextWindow: serverMetadata?.contextWindow ?? 128000,
-					maxTokens: Math.min(
-						serverMetadata?.contextWindow ?? Number.POSITIVE_INFINITY,
-						DISCOVERY_DEFAULT_MAX_TOKENS,
-					),
-					headers,
-					compat: {
-						supportsStore: false,
-						supportsDeveloperRole: false,
-						supportsReasoningEffort: false,
-					},
-				}),
-			);
-		}
-		return this.#applyProviderModelOverrides(providerConfig.provider, discovered);
-	}
-
-	async #discoverOpenAIModelsList(providerConfig: DiscoveryProviderConfig): Promise<Model<Api>[]> {
-		const baseUrl = this.#normalizeOpenAIModelsListBaseUrl(providerConfig.baseUrl);
-		const modelsUrl = `${baseUrl}/models`;
-
-		const headers: Record<string, string> = { ...(providerConfig.headers ?? {}) };
-		const apiKey = await this.authStorage.getApiKey(providerConfig.provider);
-		if (apiKey && apiKey !== DEFAULT_LOCAL_TOKEN && apiKey !== kNoAuth) {
-			headers.Authorization = `Bearer ${apiKey}`;
-		}
-
-		const response = await fetch(modelsUrl, {
-			headers,
-			signal: AbortSignal.timeout(10_000),
-		});
-		if (!response.ok) {
-			throw new Error(`HTTP ${response.status} from ${modelsUrl}`);
-		}
-		const payload = (await response.json()) as { data?: Array<{ id: string }> };
-		const models = payload.data ?? [];
-		const discovered: Model<Api>[] = [];
-		for (const item of models) {
-			const id = item.id;
-			if (!id) continue;
-			discovered.push(
-				enrichModelThinking({
-					id,
-					name: id,
-					api: providerConfig.api,
-					provider: providerConfig.provider,
-					baseUrl,
-					reasoning: false,
-					input: ["text"],
-					cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-					contextWindow: 128000,
-					maxTokens: discoveryDefaultMaxTokens(providerConfig.api),
-					headers,
-					compat: {
-						supportsStore: false,
-						supportsDeveloperRole: false,
-						supportsReasoningEffort: false,
-					},
-				}),
-			);
-		}
-		return this.#applyProviderModelOverrides(providerConfig.provider, discovered);
-	}
-
-	/**
-	 * Discover models from an Anthropic+OpenAI-compatible reseller proxy that
-	 * exposes both `/v1/messages` and `/v1/chat/completions`, advertising each
-	 * model's wire capabilities through `supported_endpoint_types` on
-	 * `GET /v1/models` (new-api / one-api-style proxies).
-	 *
-	 * Routing per model:
-	 *   supported_endpoint_types: ["anthropic", ...] -> api: "anthropic-messages"
-	 *   supported_endpoint_types: ["openai"]         -> api: "openai-completions"
-	 *   missing / neither                            -> provider-level api fallback
-	 *
-	 * Anthropic models share the same baseUrl; the Anthropic SDK strips a
-	 * trailing `/v1` itself before appending `/v1/messages`, so the discovery
-	 * URL (which ends in `/v1`) round-trips correctly.
-	 */
-	async #discoverProxyModels(providerConfig: DiscoveryProviderConfig): Promise<Model<Api>[]> {
-		const baseUrl = this.#normalizeOpenAIModelsListBaseUrl(providerConfig.baseUrl);
-		const modelsUrl = `${baseUrl}/models`;
-
-		const headers: Record<string, string> = { ...(providerConfig.headers ?? {}) };
-		const apiKey = await this.authStorage.getApiKey(providerConfig.provider);
-		if (apiKey && apiKey !== DEFAULT_LOCAL_TOKEN && apiKey !== kNoAuth) {
-			headers.Authorization = `Bearer ${apiKey}`;
-		}
-
-		const response = await fetch(modelsUrl, {
-			headers,
-			signal: AbortSignal.timeout(10_000),
-		});
-		if (!response.ok) {
-			throw new Error(`HTTP ${response.status} from ${modelsUrl}`);
-		}
-		const payload = (await response.json()) as {
-			data?: Array<{ id?: string; name?: string; supported_endpoint_types?: string[] }>;
-		};
-		const items = payload.data ?? [];
-		const discovered: Model<Api>[] = [];
-		for (const item of items) {
-			const id = item.id;
-			if (!id) continue;
-			const endpoints = item.supported_endpoint_types ?? [];
-			const api: Api | undefined = endpoints.includes("anthropic")
-				? "anthropic-messages"
-				: endpoints.includes("openai")
-					? "openai-completions"
-					: providerConfig.api;
-			if (!api) continue;
-			const isAnthropic = api === "anthropic-messages";
-			const reference = resolveCustomModelReference(id);
-			const discoveryName = typeof item.name === "string" ? item.name.trim() : "";
-			const displayName =
-				reference?.name ??
-				(discoveryName && discoveryName !== id ? discoveryName : undefined) ??
-				stripBracketedModelIdAffixes(id) ??
-				id;
-			discovered.push(
-				enrichModelThinking({
-					id,
-					name: displayName,
-					api,
-					provider: providerConfig.provider,
-					baseUrl,
-					reasoning: reference?.reasoning ?? false,
-					thinking: reference?.thinking,
-					input: reference?.input ?? ["text"],
-					// Proxy pricing is provider-specific and usually does not match
-					// upstream bundled catalogs, so keep costs local-unknown even when
-					// we successfully recover the upstream model identity.
-					cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-					contextWindow: reference?.contextWindow ?? 128000,
-					maxTokens: reference?.maxTokens ?? discoveryDefaultMaxTokens(api),
-					headers,
-					// OpenAI-compat fields are no-ops on anthropic models; the
-					// Anthropic SDK ignores them. Provider-level disableStrictTools
-					// flows in via #applyProviderCompat for the third-party-Anthropic
-					// path. Cross-wire bundled compat is intentionally not copied:
-					// request-shaping fields are provider-wire specific.
-					compat: isAnthropic
-						? undefined
-						: {
-								supportsStore: false,
-								supportsDeveloperRole: false,
-								supportsReasoningEffort: false,
-							},
-				}),
-			);
-		}
-		return this.#applyProviderModelOverrides(providerConfig.provider, discovered);
-	}
-
-	#normalizeLlamaCppBaseUrl(baseUrl?: string): string {
-		const defaultBaseUrl = "http://127.0.0.1:8080";
-		const raw = baseUrl || defaultBaseUrl;
-		try {
-			const parsed = new URL(raw);
-			const trimmedPath = parsed.pathname.replace(/\/+$/g, "");
-			return `${parsed.protocol}//${parsed.host}${trimmedPath}`;
-		} catch {
-			return raw;
-		}
-	}
-
-	#toLlamaCppNativeBaseUrl(baseUrl: string): string {
-		try {
-			const parsed = new URL(baseUrl);
-			const trimmedPath = parsed.pathname.replace(/\/+$/g, "");
-			parsed.pathname = trimmedPath.endsWith("/v1") ? trimmedPath.slice(0, -3) || "/" : trimmedPath || "/";
-			const normalized = `${parsed.protocol}//${parsed.host}${parsed.pathname}`;
-			return normalized.endsWith("/") ? normalized.slice(0, -1) : normalized;
-		} catch {
-			return baseUrl.endsWith("/v1") ? baseUrl.slice(0, -3) : baseUrl;
-		}
-	}
-
-	#normalizeOpenAIModelsListBaseUrl(baseUrl?: string): string {
-		const defaultBaseUrl = "http://127.0.0.1:1234/v1";
-		const raw = baseUrl || defaultBaseUrl;
-		try {
-			const parsed = new URL(raw);
-			const trimmedPath = parsed.pathname.replace(/\/+$/g, "");
-			parsed.pathname = trimmedPath.endsWith("/v1") ? trimmedPath || "/v1" : `${trimmedPath}/v1`;
-			return `${parsed.protocol}//${parsed.host}${parsed.pathname}`;
-		} catch {
-			return raw;
-		}
-	}
-	#normalizeOllamaBaseUrl(baseUrl?: string): string {
-		const raw = baseUrl || DEFAULT_OLLAMA_BASE_URL;
-		try {
-			const parsed = new URL(raw);
-			return `${parsed.protocol}//${parsed.host}`;
-		} catch {
-			return DEFAULT_OLLAMA_BASE_URL;
-		}
-	}
-
 	#applyProviderModelOverrides(provider: string, models: Model<Api>[]): Model<Api>[] {
 		const overrides = this.#modelOverrides.get(provider);
 		if (!overrides || overrides.size === 0) return models;
+		let liveIds: Set<string> | null = null;
+		const hasLiveModel = (_provider: string, id: string) => {
+			liveIds ??= new Set(models.map(m => m.id));
+			return liveIds.has(id);
+		};
 		return models.map(model => {
-			const override = overrides.get(model.id);
+			const override = resolveModelOverrideWithAliases(overrides, model, hasLiveModel);
 			if (!override) return model;
 			return applyModelOverride(model, override);
 		});
@@ -2100,10 +1535,15 @@ export class ModelRegistry {
 	}
 	#applyModelOverrides(models: Model<Api>[], overrides: Map<string, Map<string, ModelOverride>>): Model<Api>[] {
 		if (overrides.size === 0) return models;
+		let liveKeys: Set<string> | null = null;
+		const hasLiveModel = (provider: string, id: string) => {
+			liveKeys ??= new Set(models.map(m => `${m.provider}\u0000${m.id}`));
+			return liveKeys.has(`${provider}\u0000${id}`);
+		};
 		return models.map(model => {
 			const providerOverrides = overrides.get(model.provider);
 			if (!providerOverrides) return model;
-			const override = providerOverrides.get(model.id);
+			const override = resolveModelOverrideWithAliases(providerOverrides, model, hasLiveModel);
 			if (!override) return model;
 			return applyModelOverride(model, override);
 		});
@@ -2129,10 +1569,25 @@ export class ModelRegistry {
 			this.#rebuildPending = true;
 			return;
 		}
-		this.#canonicalIndex = buildCanonicalModelIndex(this.#models, this.#equivalenceConfig);
+		// Defer the catalog-wide index build to first read. Boot model
+		// resolution reads it only when enabledModels or a default-role pattern
+		// is configured; the empty interactive launch never reads it pre-paint,
+		// so the ~200ms build over the full catalog moves off the first-paint
+		// critical path.
+		this.#canonicalIndexDirty = true;
 		this.#rebuildPending = false;
 	}
 
+	#ensureCanonicalIndex(): CanonicalModelIndex {
+		if (this.#canonicalIndexDirty) {
+			this.#canonicalIndex = logger.time("buildCanonicalModelIndex", () =>
+				buildCanonicalModelIndex(this.#models, getBundledCanonicalReferenceData(), this.#equivalenceConfig),
+			);
+			this.#canonicalIndexDirty = false;
+		}
+		return this.#canonicalIndex;
+	}
+
 	#suspendRebuild(): void {
 		this.#rebuildSuspended += 1;
 	}
@@ -2143,7 +1598,7 @@ export class ModelRegistry {
 		}
 		if (this.#rebuildSuspended === 0 && this.#rebuildPending) {
 			this.#rebuildPending = false;
-			this.#canonicalIndex = buildCanonicalModelIndex(this.#models, this.#equivalenceConfig);
+			this.#canonicalIndexDirty = true;
 		}
 	}
 
@@ -2153,10 +1608,9 @@ export class ModelRegistry {
 		for (const [providerName, providerConfig] of Object.entries(config.providers ?? {})) {
 			const modelDefs = providerConfig.models ?? [];
 			if (modelDefs.length === 0) continue; // Override-only, no custom models
+			const resolvedProviderHeaders = resolveConfigHeaders(providerConfig.headers);
 			if (providerConfig.apiKey) {
-				this.#customProviderApiKeys.set(providerName, providerConfig.apiKey);
-				const resolved = resolveApiKeyConfig(providerConfig.apiKey);
-				if (resolved) this.authStorage.setConfigApiKey(providerName, resolved);
+				this.#installProviderApiKey(providerName, providerConfig.apiKey);
 			}
 			for (const modelDef of modelDefs) {
 				const providerCompat = providerConfig.disableStrictTools
@@ -2166,7 +1620,7 @@ export class ModelRegistry {
 					providerName,
 					providerConfig.baseUrl!,
 					providerConfig.api as Api | undefined,
-					providerConfig.headers,
+					resolvedProviderHeaders,
 					providerConfig.apiKey,
 					providerConfig.authHeader,
 					providerCompat,
@@ -2188,100 +1642,73 @@ export class ModelRegistry {
 		return this.#models;
 	}
 
-	#isModelAvailable(model: Model<Api>): boolean {
+	/**
+	 * Availability predicate with per-provider memoization. Auth lookups
+	 * (`authStorage.hasAuth`) and the disabled-provider set are resolved once
+	 * per provider instead of once per model, which matters when filtering the
+	 * full bundled catalog (thousands of models, ~50 providers).
+	 */
+	#createAvailabilityCheck(): (model: Model<Api>) => boolean {
 		const disabledProviders = getDisabledProviderIdsFromSettings();
-		return (
-			!disabledProviders.has(model.provider) &&
-			(this.#keylessProviders.has(model.provider) || this.authStorage.hasAuth(model.provider))
-		);
+		const byProvider = new Map<string, boolean>();
+		return model => {
+			let available = byProvider.get(model.provider);
+			if (available === undefined) {
+				available =
+					!disabledProviders.has(model.provider) &&
+					(this.#keylessProviders.has(model.provider) || this.authStorage.hasAuth(model.provider));
+				byProvider.set(model.provider, available);
+			}
+			return available;
+		};
+	}
+
+	/**
+	 * Build the shared per-query filter state for canonical model queries.
+	 * Hoisted out of the per-record loop: building the candidate-selector set
+	 * and availability memo once per query instead of once per record is what
+	 * keeps `getCanonicalModelSelections` linear instead of O(records × candidates).
+	 */
+	#canonicalQueryFilters(options: CanonicalModelQueryOptions | undefined): {
+		candidateKeys: Set<string> | undefined;
+		isAvailable: ((model: Model<Api>) => boolean) | undefined;
+	} {
+		return {
+			candidateKeys: options?.candidates
+				? new Set(options.candidates.map(candidate => formatCanonicalVariantSelector(candidate)))
+				: undefined,
+			isAvailable: options?.availableOnly ? this.#createAvailabilityCheck() : undefined,
+		};
 	}
 
 	#filterCanonicalVariants(
 		record: CanonicalModelRecord,
-		options: CanonicalModelQueryOptions | undefined,
+		candidateKeys: ReadonlySet<string> | undefined,
+		isAvailable: ((model: Model<Api>) => boolean) | undefined,
 	): CanonicalModelVariant[] {
-		const candidateKeys = options?.candidates
-			? new Set(options.candidates.map(candidate => formatCanonicalVariantSelector(candidate)))
-			: undefined;
 		return record.variants.filter(variant => {
 			if (candidateKeys && !candidateKeys.has(variant.selector)) {
 				return false;
 			}
-			if (options?.availableOnly && !this.#isModelAvailable(variant.model)) {
+			if (isAvailable && !isAvailable(variant.model)) {
 				return false;
 			}
 			return true;
 		});
 	}
 
-	#providerRank(models: readonly Model<Api>[]): Map<string, number> {
-		const configuredProviders = getConfiguredProviderOrderFromSettings();
-		const result = new Map<string, number>();
-		let nextRank = 0;
-		for (const provider of configuredProviders) {
-			const normalized = provider.trim().toLowerCase();
-			if (!normalized || result.has(normalized)) {
-				continue;
-			}
-			result.set(normalized, nextRank);
-			nextRank += 1;
-		}
-		for (const model of models) {
-			const normalized = model.provider.toLowerCase();
-			if (result.has(normalized)) {
-				continue;
-			}
-			result.set(normalized, nextRank);
-			nextRank += 1;
-		}
-		return result;
-	}
-
-	#resolveCanonicalVariant(
-		variants: readonly CanonicalModelVariant[],
-		allCandidates: readonly Model<Api>[],
-	): CanonicalModelVariant | undefined {
-		if (variants.length === 0) {
-			return undefined;
-		}
-		const providerRank = this.#providerRank(allCandidates);
-		const modelOrder = new Map<string, number>();
-		for (let index = 0; index < allCandidates.length; index += 1) {
-			modelOrder.set(formatCanonicalVariantSelector(allCandidates[index]!), index);
-		}
-		const sourceRank: Record<CanonicalModelVariant["source"], number> = {
-			override: 1,
-			bundled: 1,
-			heuristic: 2,
-			fallback: 3,
+	#variantPreferences(candidates: readonly Model<Api>[]): CanonicalVariantPreferences {
+		return {
+			modelOrder: buildCanonicalModelOrder(candidates),
+			providerRank: buildModelProviderPriorityRank(getConfiguredProviderOrderFromSettings()),
 		};
-		return [...variants].sort((left, right) => {
-			const leftProviderRank = providerRank.get(left.model.provider.toLowerCase()) ?? Number.MAX_SAFE_INTEGER;
-			const rightProviderRank = providerRank.get(right.model.provider.toLowerCase()) ?? Number.MAX_SAFE_INTEGER;
-			if (leftProviderRank !== rightProviderRank) {
-				return leftProviderRank - rightProviderRank;
-			}
-			const leftExact = left.model.id === left.canonicalId ? 0 : 1;
-			const rightExact = right.model.id === right.canonicalId ? 0 : 1;
-			if (leftExact !== rightExact) {
-				return leftExact - rightExact;
-			}
-			if (sourceRank[left.source] !== sourceRank[right.source]) {
-				return sourceRank[left.source] - sourceRank[right.source];
-			}
-			if (left.model.id.length !== right.model.id.length) {
-				return left.model.id.length - right.model.id.length;
-			}
-			const leftOrder = modelOrder.get(left.selector) ?? Number.MAX_SAFE_INTEGER;
-			const rightOrder = modelOrder.get(right.selector) ?? Number.MAX_SAFE_INTEGER;
-			return leftOrder - rightOrder;
-		})[0];
 	}
 
 	getCanonicalModels(options?: CanonicalModelQueryOptions): CanonicalModelRecord[] {
+		const { candidateKeys, isAvailable } = this.#canonicalQueryFilters(options);
 		const records: CanonicalModelRecord[] = [];
-		for (const record of this.#canonicalIndex.records) {
-			const variants = this.#filterCanonicalVariants(record, options);
+		for (const record of this.#ensureCanonicalIndex().records) {
+			const variants = this.#filterCanonicalVariants(record, candidateKeys, isAvailable);
 			if (variants.length === 0) {
 				continue;
 			}
@@ -2294,12 +1721,42 @@ export class ModelRegistry {
 		return records;
 	}
 
+	/**
+	 * One-pass equivalent of `getCanonicalModels` + `resolveCanonicalModel` per
+	 * record. The per-query state (candidate-selector set, availability memo,
+	 * provider rank, candidate order) is built once, so the whole catalog
+	 * resolves in O(records + candidates) instead of O(records × candidates).
+	 * This is the path the model selector hydrates from synchronously on open.
+	 */
+	getCanonicalModelSelections(options?: CanonicalModelQueryOptions): CanonicalModelSelection[] {
+		const { candidateKeys, isAvailable } = this.#canonicalQueryFilters(options);
+		const candidates = options?.candidates ?? (options?.availableOnly ? this.getAvailable() : this.getAll());
+		const preferences = this.#variantPreferences(candidates);
+		const selections: CanonicalModelSelection[] = [];
+		for (const record of this.#ensureCanonicalIndex().records) {
+			const variants = this.#filterCanonicalVariants(record, candidateKeys, isAvailable);
+			if (variants.length === 0) {
+				continue;
+			}
+			const resolved = resolveCanonicalVariant(variants, preferences);
+			if (!resolved) {
+				continue;
+			}
+			selections.push({
+				record: { id: record.id, name: record.name, variants },
+				model: resolved.model,
+			});
+		}
+		return selections;
+	}
+
 	getCanonicalVariants(canonicalId: string, options?: CanonicalModelQueryOptions): CanonicalModelVariant[] {
-		const record = this.#canonicalIndex.byId.get(canonicalId.trim().toLowerCase());
+		const record = this.#ensureCanonicalIndex().byId.get(canonicalId.trim().toLowerCase());
 		if (!record) {
 			return [];
 		}
-		return this.#filterCanonicalVariants(record, options);
+		const { candidateKeys, isAvailable } = this.#canonicalQueryFilters(options);
+		return this.#filterCanonicalVariants(record, candidateKeys, isAvailable);
 	}
 
 	resolveCanonicalModel(canonicalId: string, options?: CanonicalModelQueryOptions): Model<Api> | undefined {
@@ -2308,11 +1765,11 @@ export class ModelRegistry {
 			return undefined;
 		}
 		const candidates = options?.candidates ?? (options?.availableOnly ? this.getAvailable() : this.getAll());
-		return this.#resolveCanonicalVariant(variants, candidates)?.model;
+		return resolveCanonicalVariant(variants, this.#variantPreferences(candidates))?.model;
 	}
 
 	getCanonicalId(model: Model<Api>): string | undefined {
-		return this.#canonicalIndex.bySelector.get(formatCanonicalVariantSelector(model).toLowerCase());
+		return this.#ensureCanonicalIndex().bySelector.get(formatCanonicalVariantSelector(model).toLowerCase());
 	}
 
 	/**
@@ -2320,20 +1777,32 @@ export class ModelRegistry {
 	 * This is a fast check that doesn't refresh OAuth tokens.
 	 */
 	getAvailable(): Model<Api>[] {
-		return this.#models.filter(model => this.#isModelAvailable(model));
+		return this.#models.filter(this.#createAvailabilityCheck());
 	}
 
 	/**
 	 * Check whether auth is configured for a model's provider.
 	 *
-	 * Mirrors the upstream `@mariozechner/pi-coding-agent` API surface so that
+	 * Mirrors the upstream `@mariozechner/agent` API surface so that
 	 * external plugins/extensions and downstream wrappers (e.g. subagent launch
 	 * paths that pre-flight auth before model resolution) can probe a model
 	 * without resolving an API key. Returns true for keyless providers as well
 	 * as providers with stored credentials. See issue #993.
+	 *
+	 * Side-effect-free and synchronous: a command-backed key (`!cmd`) counts as
+	 * configured by its presence alone — the program is NOT executed — and OAuth
+	 * tokens are NOT refreshed (`authStorage.hasAuth`). This is what keeps the
+	 * model-switch pre-flight off the event loop's hot path; the real key
+	 * (command execution + OAuth refresh) is resolved lazily per request via
+	 * {@link ModelRegistry.resolver}.
 	 */
 	hasConfiguredAuth(model: Model<Api>): boolean {
-		return this.#keylessProviders.has(model.provider) || this.authStorage.hasAuth(model.provider);
+		const keyConfig = this.#customProviderApiKeys.get(model.provider);
+		return (
+			isCommandConfigValue(keyConfig) ||
+			this.#keylessProviders.has(model.provider) ||
+			this.authStorage.hasAuth(model.provider)
+		);
 	}
 
 	getDiscoverableProviders(): string[] {
@@ -2365,6 +1834,8 @@ export class ModelRegistry {
 	 * Get API key for a model.
 	 */
 	async getApiKey(model: Model<Api>, sessionId?: string): Promise<string | undefined> {
+		const commandKey = this.#resolveCommandBackedApiKey(model.provider);
+		if (commandKey.configured) return commandKey.value;
 		if (this.#keylessProviders.has(model.provider) && !this.authStorage.hasAuth(model.provider)) {
 			return kNoAuth;
 		}
@@ -2373,15 +1844,53 @@ export class ModelRegistry {
 
 	/**
 	 * Get API key for a provider (e.g., "openai").
+	 *
+	 * `options.forceRefresh` powers step (b) of the auth-retry policy — it
+	 * re-mints the session-sticky OAuth token even when the cached copy still
+	 * looks valid. `options.signal` is threaded into any broker-bound refresh.
 	 */
-	async getApiKeyForProvider(provider: string, sessionId?: string, baseUrl?: string): Promise<string | undefined> {
+	async getApiKeyForProvider(
+		provider: string,
+		sessionId?: string,
+		options?: { baseUrl?: string; modelId?: string; forceRefresh?: boolean; signal?: AbortSignal },
+	): Promise<string | undefined> {
+		const commandKey = this.#resolveCommandBackedApiKey(provider);
+		if (commandKey.configured) return commandKey.value;
 		if (this.#keylessProviders.has(provider) && !this.authStorage.hasAuth(provider)) {
 			return kNoAuth;
 		}
-		return this.authStorage.getApiKey(provider, sessionId, { baseUrl });
+		return this.authStorage.getApiKey(provider, sessionId, {
+			baseUrl: options?.baseUrl,
+			modelId: options?.modelId,
+			forceRefresh: options?.forceRefresh,
+			signal: options?.signal,
+		});
+	}
+
+	/**
+	 * Build an {@link ApiKeyResolver} implementing the central a/b/c auth-retry
+	 * policy. Accepts a provider id with options, or a model with an optional
+	 * session id (`resolver(model, sessionId)`) which derives `baseUrl`/`modelId`
+	 * from the model. Callers that need the initial key for a guard can call
+	 * `resolveApiKeyOnce(resolver)`.
+	 */
+	resolver(provider: string, options?: ApiKeyResolverOptions): ApiKeyResolver;
+	resolver(model: ApiKeyResolverModel, sessionId?: string): ApiKeyResolver;
+	resolver(target: string | ApiKeyResolverModel, optionsOrSessionId?: ApiKeyResolverOptions | string): ApiKeyResolver {
+		const options = typeof optionsOrSessionId === "string" ? { sessionId: optionsOrSessionId } : optionsOrSessionId;
+		if (typeof target === "string") {
+			return createApiKeyResolver(this, target, options);
+		}
+		return createApiKeyResolver(this, target.provider, {
+			...options,
+			baseUrl: target.baseUrl,
+			modelId: target.id,
+		});
 	}
 
 	async #peekApiKeyForProvider(provider: string): Promise<string | undefined> {
+		const commandKey = this.#resolveCommandBackedApiKey(provider);
+		if (commandKey.configured) return commandKey.value;
 		if (this.#keylessProviders.has(provider) && !this.authStorage.hasAuth(provider)) {
 			return kNoAuth;
 		}
@@ -2399,6 +1908,7 @@ export class ModelRegistry {
 		this.#runtimeProviderApiKeys.delete(providerName);
 		this.#runtimeProviderOverrides.delete(providerName);
 		this.#runtimeModelOverlays = this.#runtimeModelOverlays.filter(overlay => overlay.provider !== providerName);
+		this.#runtimeModelManagers.delete(providerName);
 		this.authStorage.removeConfigApiKey(providerName);
 	}
 
@@ -2504,11 +2014,9 @@ export class ModelRegistry {
 		}
 
 		if (config.apiKey) {
-			this.#customProviderApiKeys.set(providerName, config.apiKey);
+			this.#installProviderApiKey(providerName, config.apiKey);
 			// Persist runtime API keys so they survive #reloadStaticModels() cycles
 			this.#runtimeProviderApiKeys.set(providerName, config.apiKey);
-			const resolved = resolveApiKeyConfig(config.apiKey);
-			if (resolved) this.authStorage.setConfigApiKey(providerName, resolved);
 		}
 
 		if (config.models && config.models.length > 0) {
@@ -2562,6 +2070,47 @@ export class ModelRegistry {
 			return;
 		}
 
+		if (config.fetchDynamicModels) {
+			const fetcher = config.fetchDynamicModels;
+			const providerBaseUrl = config.baseUrl ?? "";
+			const providerApi = config.api;
+			const providerHeaders = config.headers;
+			const providerApiKey = config.apiKey;
+			const providerAuthHeader = config.authHeader;
+			const providerCompat = config.compat;
+			const managerOptions: ModelManagerOptions<Api> = {
+				providerId: providerName as Parameters<typeof createModelManager>[0]["providerId"],
+				staticModels: [],
+				cacheDbPath: this.#cacheDbPath,
+				cacheTtlMs: 24 * 60 * 60 * 1000,
+				dynamicModelsAuthoritative: true,
+				fetchDynamicModels: async () => {
+					const apiKey = await this.#peekApiKeyForProvider(providerName);
+					const resolvedKey = isAuthenticated(apiKey) ? apiKey : undefined;
+					const modelDefs = await fetcher(resolvedKey);
+					const results: Model<Api>[] = [];
+					for (const modelDef of modelDefs) {
+						const overlay = buildCustomModelOverlay(
+							providerName,
+							modelDef.baseUrl ?? providerBaseUrl,
+							modelDef.api ?? providerApi,
+							providerHeaders,
+							providerApiKey,
+							providerAuthHeader,
+							providerCompat,
+							undefined,
+							modelDef as CustomModelDefinitionLike,
+						);
+						if (overlay) results.push(finalizeCustomModel(overlay, { useDefaults: true }));
+					}
+					return results.map(toModelSpec);
+				},
+			};
+			this.#runtimeModelManagers.set(providerName, { options: managerOptions, sourceId: sourceId ?? "" });
+			// Discovery is driven by refreshRuntimeProviders() after the drain — not
+			// here, so registration has no network side effect and callers can await.
+		}
+
 		if (
 			config.baseUrl ||
 			config.headers ||
@@ -2609,6 +2158,14 @@ export class ModelRegistry {
 		}
 		return true;
 	}
+
+	/**
+	 * Clear all cooldown suppressions recorded via {@link suppressSelector}.
+	 * Used to reset retry-fallback cooldown state without a full {@link refresh}.
+	 */
+	clearSuppressedSelectors(): void {
+		this.#suppressedSelectors.clear();
+	}
 }
 
 /**
@@ -2620,7 +2177,7 @@ export interface ProviderConfigInput {
 	api?: Api;
 	streamSimple?: (model: Model<Api>, context: Context, options?: SimpleStreamOptions) => AssistantMessageEventStream;
 	headers?: Record<string, string>;
-	compat?: Model<Api>["compat"];
+	compat?: ModelSpec<Api>["compat"];
 	authHeader?: boolean;
 	/** Streaming transport override — see {@link Model.transport}. */
 	transport?: Model<Api>["transport"];
@@ -2631,6 +2188,15 @@ export interface ProviderConfigInput {
 		getApiKey?(credentials: OAuthCredentials): string;
 		modifyModels?(models: Model<Api>[], credentials: OAuthCredentials): Model<Api>[];
 	};
+	/**
+	 * Async factory that fetches the live model list from the provider endpoint.
+	 * When present, the result is run through the same SQLite model-cache as
+	 * built-in providers (keyed by provider name, default 24 h TTL).
+	 * The factory receives the resolved API key (undefined when unauthenticated).
+	 */
+	fetchDynamicModels?: (
+		apiKey: string | undefined,
+	) => Promise<readonly NonNullable<ProviderConfigInput["models"]>[number][]>;
 	models?: Array<{
 		id: string;
 		name: string;
@@ -2643,7 +2209,7 @@ export interface ProviderConfigInput {
 		contextWindow: number;
 		maxTokens: number;
 		headers?: Record<string, string>;
-		compat?: Model<Api>["compat"];
+		compat?: ModelSpec<Api>["compat"];
 		contextPromotionTarget?: string;
 		premiumMultiplier?: number;
 	}>;