@oh-my-pi/pi-coding-agent 15.10.10 → 15.10.12

package/src/config/model-registry.ts

@@ -1,9 +1,17 @@
+import { execSync } from "node:child_process";
 import * as path from "node:path";
 import { registerCustomApi, unregisterCustomApis } from "@oh-my-pi/pi-ai/api-registry";
-import { readModelCache } from "@oh-my-pi/pi-ai/model-cache";
-import { createModelManager, type ModelManagerOptions, type ModelRefreshStrategy } from "@oh-my-pi/pi-ai/model-manager";
-import { enrichModelThinking } from "@oh-my-pi/pi-ai/model-thinking";
-import { getBundledModels, getBundledProviders } from "@oh-my-pi/pi-ai/models";
+import type { Api, Context, Model, ModelSpec, SimpleStreamOptions, ThinkingConfig } from "@oh-my-pi/pi-ai/types";
+import type { AssistantMessageEventStream } from "@oh-my-pi/pi-ai/utils/event-stream";
+import { buildModel } from "@oh-my-pi/pi-catalog/build";
+import { isVertexExpressOpenAIUrl } from "@oh-my-pi/pi-catalog/hosts";
+import { readModelCache } from "@oh-my-pi/pi-catalog/model-cache";
+import {
+	createModelManager,
+	type ModelManagerOptions,
+	type ModelRefreshStrategy,
+} from "@oh-my-pi/pi-catalog/model-manager";
+import { getBundledModels, getBundledProviders } from "@oh-my-pi/pi-catalog/models";
 import {
 	googleAntigravityModelManagerOptions,
 	googleGeminiCliModelManagerOptions,
@@ -11,79 +19,12 @@ import {
 	PROVIDER_DESCRIPTORS,
 	UNK_CONTEXT_WINDOW,
 	UNK_MAX_TOKENS,
-} from "@oh-my-pi/pi-ai/provider-models";
-import type { Api, Context, Model, SimpleStreamOptions, ThinkingConfig } from "@oh-my-pi/pi-ai/types";
-import type { AssistantMessageEventStream } from "@oh-my-pi/pi-ai/utils/event-stream";
+} from "@oh-my-pi/pi-catalog/provider-models";
 
 // 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.
 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 SPECIAL_MODEL_MANAGER_PROVIDER_IDS: readonly string[] = [
 	"google-antigravity",
 	"google-gemini-cli",
@@ -98,35 +39,37 @@ const STARTUP_MODEL_CACHE_PROVIDER_IDS: readonly string[] = [
 import type { ApiKeyResolver, FetchImpl } from "@oh-my-pi/pi-ai";
 import { registerOAuthProvider, unregisterOAuthProviders } from "@oh-my-pi/pi-ai/oauth";
 import type { OAuthCredentials, OAuthLoginCallbacks } from "@oh-my-pi/pi-ai/oauth/types";
-import { isRecord, logger } from "@oh-my-pi/pi-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 ApiKeyResolverOptions, createApiKeyResolver } from "./api-key-resolver";
-import { type ConfigError, ConfigFile } from "./config-file";
 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";
-import { buildModelProviderPriorityRank } from "./model-provider-priority";
+	resolveCanonicalVariant,
+	resolveModelReference,
+} from "@oh-my-pi/pi-catalog/identity";
+import { isRecord, logger } from "@oh-my-pi/pi-utils";
+import { parseModelString, resolveProviderModelReference } from "../config/model-resolver";
+import type { AuthStorage, OAuthCredential } from "../session/auth-storage";
+import { 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 };
 
@@ -136,196 +79,13 @@ 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;
-}
-
-/**
- * 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"];
 }
 
@@ -351,19 +111,21 @@ 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,
-		};
+			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;
 }
@@ -378,7 +140,7 @@ function isAuthoritativeProjectCatalogModel(model: Model<Api>): boolean {
 	return (
 		model.provider === "google-vertex" &&
 		model.api === "openai-completions" &&
-		model.baseUrl.includes("/endpoints/openapi")
+		isVertexExpressOpenAIUrl(model.baseUrl)
 	);
 }
 
@@ -396,14 +158,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 {
@@ -447,78 +227,50 @@ interface CustomModelsResult {
 	found: boolean;
 }
 
-type OllamaDiscoveredModelMetadata = {
-	reasoning: boolean;
-	input: ("text" | "image")[];
-	contextWindow?: number;
-};
-
-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;
-}
+const commandValueCache = new Map<string, string>();
 
-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 isCommandConfigValue(valueConfig: string | undefined): valueConfig is string {
+	return valueConfig?.startsWith("!") === true;
 }
 
-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 {
@@ -579,73 +331,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,
@@ -653,7 +431,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(
@@ -665,7 +444,7 @@ function mergeAuthHeader(
 	if (!authHeader || !apiKeyConfig) {
 		return nextHeaders;
 	}
-	const resolvedKey = resolveApiKeyConfig(apiKeyConfig);
+	const resolvedKey = resolveConfigValue(apiKeyConfig);
 	return resolvedKey ? { ...nextHeaders, Authorization: `Bearer ${resolvedKey}` } : nextHeaders;
 }
 
@@ -692,7 +471,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 {
@@ -705,8 +484,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,
@@ -719,125 +498,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;
@@ -847,13 +507,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,
@@ -868,11 +530,11 @@ function finalizeCustomModel(model: CustomModelOverlay, options: CustomModelBuil
 		maxTokens: resolvedModel.maxTokens ?? reference?.maxTokens ?? (options.useDefaults ? 16384 : undefined),
 		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 {
@@ -935,6 +597,28 @@ export class ModelRegistry {
 	#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
 	 *
@@ -955,10 +639,8 @@ export class ModelRegistry {
 		// 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();
@@ -1049,7 +731,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();
@@ -1133,84 +815,46 @@ 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 === UNK_CONTEXT_WINDOW
+						? existing.contextWindow
+						: replacementModel.contextWindow,
+				maxTokens: replacementModel.maxTokens === UNK_MAX_TOKENS ? existing.maxTokens : replacementModel.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);
-			}
-		}
-		return merged;
+				},
+				customModel,
+				"replace",
+			);
+		});
 	}
 
 	#loadCachedStandardProviderModels(): { models: Model<Api>[]; authoritativeFreshProviders: Set<string> } {
@@ -1236,8 +880,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 };
@@ -1261,7 +910,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);
@@ -1277,9 +929,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>[] {
@@ -1289,7 +943,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;
 			}
@@ -1372,10 +1033,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 ||
@@ -1385,7 +1047,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),
@@ -1407,7 +1069,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,
@@ -1419,16 +1081,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);
 			}
@@ -1512,17 +1175,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;
@@ -1569,18 +1235,14 @@ 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,
+			getBearerApiKey: async provider => {
+				const apiKey = await this.getApiKeyForProvider(provider);
+				return apiKey && apiKey !== DEFAULT_LOCAL_TOKEN && apiKey !== kNoAuth ? apiKey : undefined;
+			},
+		};
 	}
 
 	#warnProviderDiscoveryFailure(providerConfig: DiscoveryProviderConfig, error: string): void {
@@ -1732,361 +1394,6 @@ 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 this.#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 this.#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 this.#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([
-			this.#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 this.#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 this.#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;
@@ -2164,7 +1471,11 @@ export class ModelRegistry {
 			this.#rebuildPending = true;
 			return;
 		}
-		this.#canonicalIndex = buildCanonicalModelIndex(this.#models, this.#equivalenceConfig);
+		this.#canonicalIndex = buildCanonicalModelIndex(
+			this.#models,
+			getBundledCanonicalReferenceData(),
+			this.#equivalenceConfig,
+		);
 		this.#rebuildPending = false;
 	}
 
@@ -2178,7 +1489,11 @@ export class ModelRegistry {
 		}
 		if (this.#rebuildSuspended === 0 && this.#rebuildPending) {
 			this.#rebuildPending = false;
-			this.#canonicalIndex = buildCanonicalModelIndex(this.#models, this.#equivalenceConfig);
+			this.#canonicalIndex = buildCanonicalModelIndex(
+				this.#models,
+				getBundledCanonicalReferenceData(),
+				this.#equivalenceConfig,
+			);
 		}
 	}
 
@@ -2188,10 +1503,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
@@ -2201,7 +1515,7 @@ export class ModelRegistry {
 					providerName,
 					providerConfig.baseUrl!,
 					providerConfig.api as Api | undefined,
-					providerConfig.headers,
+					resolvedProviderHeaders,
 					providerConfig.apiKey,
 					providerConfig.authHeader,
 					providerCompat,
@@ -2278,53 +1592,11 @@ export class ModelRegistry {
 		});
 	}
 
-	#buildModelOrder(candidates: readonly Model<Api>[]): Map<string, number> {
-		const modelOrder = new Map<string, number>();
-		for (let index = 0; index < candidates.length; index += 1) {
-			modelOrder.set(formatCanonicalVariantSelector(candidates[index]!), index);
-		}
-		return modelOrder;
-	}
-
-	#providerRank(): Map<string, number> {
-		return buildModelProviderPriorityRank(getConfiguredProviderOrderFromSettings());
-	}
-
-	#resolveCanonicalVariant(
-		variants: readonly CanonicalModelVariant[],
-		modelOrder: ReadonlyMap<string, number>,
-		providerRank: ReadonlyMap<string, number>,
-	): CanonicalModelVariant | undefined {
-		if (variants.length === 0) {
-			return undefined;
-		}
-		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[] {
@@ -2354,15 +1626,14 @@ export class ModelRegistry {
 	getCanonicalModelSelections(options?: CanonicalModelQueryOptions): CanonicalModelSelection[] {
 		const { candidateKeys, isAvailable } = this.#canonicalQueryFilters(options);
 		const candidates = options?.candidates ?? (options?.availableOnly ? this.getAvailable() : this.getAll());
-		const modelOrder = this.#buildModelOrder(candidates);
-		const providerRank = this.#providerRank();
+		const preferences = this.#variantPreferences(candidates);
 		const selections: CanonicalModelSelection[] = [];
 		for (const record of this.#canonicalIndex.records) {
 			const variants = this.#filterCanonicalVariants(record, candidateKeys, isAvailable);
 			if (variants.length === 0) {
 				continue;
 			}
-			const resolved = this.#resolveCanonicalVariant(variants, modelOrder, providerRank);
+			const resolved = resolveCanonicalVariant(variants, preferences);
 			if (!resolved) {
 				continue;
 			}
@@ -2389,7 +1660,7 @@ export class ModelRegistry {
 			return undefined;
 		}
 		const candidates = options?.candidates ?? (options?.availableOnly ? this.getAvailable() : this.getAll());
-		return this.#resolveCanonicalVariant(variants, this.#buildModelOrder(candidates), this.#providerRank())?.model;
+		return resolveCanonicalVariant(variants, this.#variantPreferences(candidates))?.model;
 	}
 
 	getCanonicalId(model: Model<Api>): string | undefined {
@@ -2414,7 +1685,10 @@ export class ModelRegistry {
 	 * as providers with stored credentials. See issue #993.
 	 */
 	hasConfiguredAuth(model: Model<Api>): boolean {
-		return this.#keylessProviders.has(model.provider) || this.authStorage.hasAuth(model.provider);
+		const commandKey = this.#resolveCommandBackedApiKey(model.provider);
+		return (
+			commandKey.configured || this.#keylessProviders.has(model.provider) || this.authStorage.hasAuth(model.provider)
+		);
 	}
 
 	getDiscoverableProviders(): string[] {
@@ -2446,6 +1720,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;
 		}
@@ -2462,13 +1738,16 @@ export class ModelRegistry {
 	async getApiKeyForProvider(
 		provider: string,
 		sessionId?: string,
-		options?: { baseUrl?: string; forceRefresh?: boolean; signal?: AbortSignal },
+		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: options?.baseUrl,
+			modelId: options?.modelId,
 			forceRefresh: options?.forceRefresh,
 			signal: options?.signal,
 		});
@@ -2484,6 +1763,8 @@ export class ModelRegistry {
 	}
 
 	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;
 		}
@@ -2607,11 +1888,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) {
@@ -2680,7 +1959,7 @@ export class ModelRegistry {
 				cacheTtlMs: 24 * 60 * 60 * 1000,
 				dynamicModelsAuthoritative: true,
 				fetchDynamicModels: async () => {
-					const apiKey = await this.authStorage.peekApiKey(providerName);
+					const apiKey = await this.#peekApiKeyForProvider(providerName);
 					const resolvedKey = isAuthenticated(apiKey) ? apiKey : undefined;
 					const modelDefs = await fetcher(resolvedKey);
 					const results: Model<Api>[] = [];
@@ -2698,7 +1977,7 @@ export class ModelRegistry {
 						);
 						if (overlay) results.push(finalizeCustomModel(overlay, { useDefaults: true }));
 					}
-					return results;
+					return results.map(toModelSpec);
 				},
 			};
 			this.#runtimeModelManagers.set(providerName, { options: managerOptions, sourceId: sourceId ?? "" });
@@ -2772,7 +2051,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"];
@@ -2804,7 +2083,7 @@ export interface ProviderConfigInput {
 		contextWindow: number;
 		maxTokens: number;
 		headers?: Record<string, string>;
-		compat?: Model<Api>["compat"];
+		compat?: ModelSpec<Api>["compat"];
 		contextPromotionTarget?: string;
 		premiumMultiplier?: number;
 	}>;