@nghyane/arcane 0.1.0

package/src/config/model-registry.ts

@@ -0,0 +1,1140 @@
+import {
+	type Api,
+	type AssistantMessageEventStream,
+	type Context,
+	createModelManager,
+	getBundledModels,
+	getBundledProviders,
+	getGitHubCopilotBaseUrl,
+	googleAntigravityModelManagerOptions,
+	googleGeminiCliModelManagerOptions,
+	type Model,
+	type ModelManagerOptions,
+	type ModelRefreshStrategy,
+	normalizeDomain,
+	type OAuthCredentials,
+	type OAuthLoginCallbacks,
+	openaiCodexModelManagerOptions,
+	PROVIDER_DESCRIPTORS,
+	registerCustomApi,
+	registerOAuthProvider,
+	type SimpleStreamOptions,
+	unregisterCustomApis,
+	unregisterOAuthProviders,
+} from "@nghyane/arcane-ai";
+import { logger } from "@nghyane/arcane-utils";
+import { type Static, Type } from "@sinclair/typebox";
+import { type ConfigError, ConfigFile } from "../config";
+import type { ThemeColor } from "../modes/theme/theme";
+import type { AuthStorage, OAuthCredential } from "../session/auth-storage";
+
+export const kNoAuth = "N/A";
+
+export function isAuthenticated(apiKey: string | undefined | null): apiKey is string {
+	return Boolean(apiKey) && apiKey !== kNoAuth;
+}
+
+export type ModelRole = "default" | "fast" | "reviewer" | "oracle" | "commit";
+
+export interface ModelRoleInfo {
+	tag?: string;
+	name: string;
+	color?: ThemeColor;
+}
+
+export const MODEL_ROLES: Record<ModelRole, ModelRoleInfo> = {
+	default: { tag: "DEFAULT", name: "Default", color: "success" },
+	fast: { tag: "FAST", name: "Fast", color: "warning" },
+	reviewer: { tag: "REVIEW", name: "Reviewer", color: "accent" },
+	oracle: { tag: "ORACLE", name: "Oracle", color: "accent" },
+	commit: { name: "Commit" },
+};
+
+export const MODEL_ROLE_IDS: ModelRole[] = ["default", "fast", "reviewer", "oracle", "commit"];
+
+const OpenRouterRoutingSchema = Type.Object({
+	only: Type.Optional(Type.Array(Type.String())),
+	order: Type.Optional(Type.Array(Type.String())),
+});
+
+// Schema for Vercel AI Gateway routing preferences
+const VercelGatewayRoutingSchema = Type.Object({
+	only: Type.Optional(Type.Array(Type.String())),
+	order: Type.Optional(Type.Array(Type.String())),
+});
+
+// Schema for OpenAI compatibility settings
+const OpenAICompatSchema = Type.Object({
+	supportsStore: Type.Optional(Type.Boolean()),
+	supportsDeveloperRole: Type.Optional(Type.Boolean()),
+	supportsReasoningEffort: Type.Optional(Type.Boolean()),
+	maxTokensField: Type.Optional(Type.Union([Type.Literal("max_completion_tokens"), Type.Literal("max_tokens")])),
+	openRouterRouting: Type.Optional(OpenRouterRoutingSchema),
+	vercelGatewayRouting: Type.Optional(VercelGatewayRoutingSchema),
+});
+
+// Schema for custom model definition
+// Most fields are optional with sensible defaults for local models (Ollama, LM Studio, etc.)
+const ModelDefinitionSchema = Type.Object({
+	id: Type.String({ minLength: 1 }),
+	name: Type.Optional(Type.String({ minLength: 1 })),
+	api: Type.Optional(
+		Type.Union([
+			Type.Literal("openai-completions"),
+			Type.Literal("openai-responses"),
+			Type.Literal("openai-codex-responses"),
+			Type.Literal("azure-openai-responses"),
+			Type.Literal("anthropic-messages"),
+			Type.Literal("google-generative-ai"),
+			Type.Literal("google-vertex"),
+		]),
+	),
+	reasoning: Type.Optional(Type.Boolean()),
+	input: Type.Optional(Type.Array(Type.Union([Type.Literal("text"), Type.Literal("image")]))),
+	cost: Type.Optional(
+		Type.Object({
+			input: Type.Number(),
+			output: Type.Number(),
+			cacheRead: Type.Number(),
+			cacheWrite: Type.Number(),
+		}),
+	),
+	contextWindow: Type.Optional(Type.Number()),
+	maxTokens: Type.Optional(Type.Number()),
+	headers: Type.Optional(Type.Record(Type.String(), Type.String())),
+	compat: Type.Optional(OpenAICompatSchema),
+	contextPromotionTarget: Type.Optional(Type.String({ minLength: 1 })),
+});
+
+// Schema for per-model overrides (all fields optional, merged with built-in model)
+const ModelOverrideSchema = Type.Object({
+	name: Type.Optional(Type.String({ minLength: 1 })),
+	reasoning: Type.Optional(Type.Boolean()),
+	input: Type.Optional(Type.Array(Type.Union([Type.Literal("text"), Type.Literal("image")]))),
+	cost: Type.Optional(
+		Type.Object({
+			input: Type.Optional(Type.Number()),
+			output: Type.Optional(Type.Number()),
+			cacheRead: Type.Optional(Type.Number()),
+			cacheWrite: Type.Optional(Type.Number()),
+		}),
+	),
+	contextWindow: Type.Optional(Type.Number()),
+	maxTokens: Type.Optional(Type.Number()),
+	headers: Type.Optional(Type.Record(Type.String(), Type.String())),
+	compat: Type.Optional(OpenAICompatSchema),
+	contextPromotionTarget: Type.Optional(Type.String({ minLength: 1 })),
+});
+
+type ModelOverride = Static<typeof ModelOverrideSchema>;
+
+const ProviderDiscoverySchema = Type.Object({
+	type: Type.Union([Type.Literal("ollama")]),
+});
+
+const ProviderAuthSchema = Type.Union([Type.Literal("apiKey"), Type.Literal("none")]);
+
+const ProviderConfigSchema = Type.Object({
+	baseUrl: Type.Optional(Type.String({ minLength: 1 })),
+	apiKey: Type.Optional(Type.String({ minLength: 1 })),
+	api: Type.Optional(
+		Type.Union([
+			Type.Literal("openai-completions"),
+			Type.Literal("openai-responses"),
+			Type.Literal("openai-codex-responses"),
+			Type.Literal("azure-openai-responses"),
+			Type.Literal("anthropic-messages"),
+			Type.Literal("google-generative-ai"),
+			Type.Literal("google-vertex"),
+		]),
+	),
+	headers: Type.Optional(Type.Record(Type.String(), Type.String())),
+	authHeader: Type.Optional(Type.Boolean()),
+	auth: Type.Optional(ProviderAuthSchema),
+	discovery: Type.Optional(ProviderDiscoverySchema),
+	models: Type.Optional(Type.Array(ModelDefinitionSchema)),
+	modelOverrides: Type.Optional(Type.Record(Type.String(), ModelOverrideSchema)),
+});
+
+const ModelsConfigSchema = Type.Object({
+	providers: Type.Record(Type.String(), ProviderConfigSchema),
+});
+
+type ModelsConfig = Static<typeof ModelsConfigSchema>;
+
+type ProviderAuthMode = Static<typeof ProviderAuthSchema>;
+type ProviderDiscovery = Static<typeof ProviderDiscoverySchema>;
+
+type ProviderValidationMode = "models-config" | "runtime-register";
+
+interface ProviderValidationModel {
+	id: string;
+	api?: Api;
+	contextWindow?: number;
+	maxTokens?: number;
+}
+
+interface ProviderValidationConfig {
+	baseUrl?: string;
+	apiKey?: string;
+	api?: Api;
+	auth?: ProviderAuthMode;
+	oauthConfigured?: boolean;
+	discovery?: ProviderDiscovery;
+	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 && !hasModelOverrides && !config.discovery) {
+				throw new Error(
+					`Provider ${providerName}: must specify "baseUrl", "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) {
+		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,
+					apiKey: providerConfig.apiKey,
+					api: providerConfig.api as Api | undefined,
+					auth: (providerConfig.auth ?? "apiKey") as ProviderAuthMode,
+					discovery: providerConfig.discovery as ProviderDiscovery | undefined,
+					modelOverrides: providerConfig.modelOverrides,
+					models: (providerConfig.models ?? []) as ProviderValidationModel[],
+				},
+				"models-config",
+			);
+		}
+	},
+);
+
+/** Provider override config (baseUrl, headers, apiKey) without custom models */
+interface ProviderOverride {
+	baseUrl?: string;
+	headers?: Record<string, string>;
+	apiKey?: string;
+}
+
+interface DiscoveryProviderConfig {
+	provider: string;
+	api: Api;
+	baseUrl?: string;
+	headers?: Record<string, string>;
+	discovery: ProviderDiscovery;
+}
+
+/**
+ * Serialized representation of ModelRegistry for passing to subagent workers.
+ */
+export interface SerializedModelRegistry {
+	models: Model<Api>[];
+	customProviderApiKeys?: Record<string, string>;
+}
+
+/** Result of loading custom models from models.json */
+interface CustomModelsResult {
+	models?: Model<Api>[];
+	overrides?: Map<string, ProviderOverride>;
+	modelOverrides?: Map<string, Map<string, ModelOverride>>;
+	keylessProviders?: Set<string>;
+	discoverableProviders?: DiscoveryProviderConfig[];
+	configuredProviders?: Set<string>;
+	error?: ConfigError;
+	found: boolean;
+}
+
+/**
+ * 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 extractGoogleOAuthToken(value: string | undefined): string | undefined {
+	if (!isAuthenticated(value)) return undefined;
+	try {
+		const parsed = JSON.parse(value) as { token?: unknown };
+		if (Object.hasOwn(parsed, "token")) {
+			if (typeof parsed.token !== "string") {
+				return undefined;
+			}
+			const token = parsed.token.trim();
+			return token.length > 0 ? token : undefined;
+		}
+	} catch {
+		// OAuth values for Google providers are expected to be JSON, but custom setups may already provide raw token.
+	}
+	return value;
+}
+
+function getOAuthCredentialsForProvider(authStorage: AuthStorage, provider: string): OAuthCredential[] {
+	const providerEntry = authStorage.getAll()[provider];
+	if (!providerEntry) {
+		return [];
+	}
+	const entries = Array.isArray(providerEntry) ? providerEntry : [providerEntry];
+	return entries.filter((entry): entry is OAuthCredential => entry.type === "oauth");
+}
+
+function resolveOAuthAccountIdForAccessToken(
+	authStorage: AuthStorage,
+	provider: string,
+	accessToken: string,
+): string | undefined {
+	const oauthCredentials = getOAuthCredentialsForProvider(authStorage, provider);
+	const matchingCredential = oauthCredentials.find(credential => credential.access === accessToken);
+	if (matchingCredential) {
+		return matchingCredential.accountId;
+	}
+	if (oauthCredentials.length === 1) {
+		return oauthCredentials[0].accountId;
+	}
+	return undefined;
+}
+
+function mergeCompat(
+	baseCompat: Model<Api>["compat"],
+	overrideCompat: ModelOverride["compat"],
+): Model<Api>["compat"] | undefined {
+	if (!overrideCompat) return baseCompat;
+	const base = baseCompat ?? {};
+	const override = overrideCompat;
+	const merged: NonNullable<Model<Api>["compat"]> = { ...base, ...override };
+	if (baseCompat?.openRouterRouting || overrideCompat.openRouterRouting) {
+		merged.openRouterRouting = { ...baseCompat?.openRouterRouting, ...overrideCompat.openRouterRouting };
+	}
+	if (baseCompat?.vercelGatewayRouting || overrideCompat.vercelGatewayRouting) {
+		merged.vercelGatewayRouting = { ...baseCompat?.vercelGatewayRouting, ...overrideCompat.vercelGatewayRouting };
+	}
+	return merged;
+}
+
+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.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.contextPromotionTarget !== undefined) result.contextPromotionTarget = override.contextPromotionTarget;
+	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 result;
+}
+
+interface CustomModelDefinitionLike {
+	id: string;
+	name?: string;
+	api?: Api;
+	reasoning?: boolean;
+	input?: ("text" | "image")[];
+	cost?: { input: number; output: number; cacheRead: number; cacheWrite: number };
+	contextWindow?: number;
+	maxTokens?: number;
+	headers?: Record<string, string>;
+	compat?: Model<Api>["compat"];
+	contextPromotionTarget?: string;
+}
+
+interface CustomModelBuildOptions {
+	useDefaults: boolean;
+}
+
+function mergeCustomModelHeaders(
+	providerHeaders: Record<string, string> | undefined,
+	modelHeaders: Record<string, string> | undefined,
+	authHeader: boolean | undefined,
+	apiKeyConfig: string | undefined,
+): Record<string, string> | undefined {
+	let headers = providerHeaders || modelHeaders ? { ...providerHeaders, ...modelHeaders } : undefined;
+	if (authHeader && apiKeyConfig) {
+		const resolvedKey = resolveApiKeyConfig(apiKeyConfig);
+		if (resolvedKey) {
+			headers = { ...headers, Authorization: `Bearer ${resolvedKey}` };
+		}
+	}
+	return headers;
+}
+
+function buildCustomModel(
+	providerName: string,
+	providerBaseUrl: string,
+	providerApi: Api | undefined,
+	providerHeaders: Record<string, string> | undefined,
+	providerApiKey: string | undefined,
+	authHeader: boolean | undefined,
+	modelDef: CustomModelDefinitionLike,
+	options: CustomModelBuildOptions,
+): Model<Api> | undefined {
+	const api = modelDef.api ?? providerApi;
+	if (!api) return undefined;
+	const withDefaults = options.useDefaults;
+	const cost = modelDef.cost ?? (withDefaults ? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 } : undefined);
+	const input = modelDef.input ?? (withDefaults ? ["text"] : undefined);
+	return {
+		id: modelDef.id,
+		name: modelDef.name ?? (withDefaults ? modelDef.id : undefined),
+		api,
+		provider: providerName,
+		baseUrl: providerBaseUrl,
+		reasoning: modelDef.reasoning ?? (withDefaults ? false : undefined),
+		input: input as ("text" | "image")[],
+		cost,
+		contextWindow: modelDef.contextWindow ?? (withDefaults ? 128000 : undefined),
+		maxTokens: modelDef.maxTokens ?? (withDefaults ? 16384 : undefined),
+		headers: mergeCustomModelHeaders(providerHeaders, modelDef.headers, authHeader, providerApiKey),
+		compat: modelDef.compat,
+		contextPromotionTarget: modelDef.contextPromotionTarget,
+	} as Model<Api>;
+}
+
+/**
+ * Model registry - loads and manages models, resolves API keys via AuthStorage.
+ */
+export class ModelRegistry {
+	#models: Model<Api>[] = [];
+	#customProviderApiKeys: Map<string, string> = new Map();
+	#keylessProviders: Set<string> = new Set();
+	#discoverableProviders: DiscoveryProviderConfig[] = [];
+	#modelOverrides: Map<string, Map<string, ModelOverride>> = new Map();
+	#configError: ConfigError | undefined = undefined;
+	#modelsConfigFile: ConfigFile<ModelsConfig>;
+	#registeredProviderSources: Set<string> = new Set();
+
+	/**
+	 * @param authStorage - Auth storage for API key resolution
+	 */
+	constructor(
+		readonly authStorage: AuthStorage,
+		modelsPath?: string,
+	) {
+		this.#modelsConfigFile = ModelsConfigFile.relocate(modelsPath);
+		// 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;
+		});
+		// Load models synchronously in constructor
+		this.#loadModels();
+	}
+
+	/**
+	 * Reload models from disk (built-in + custom from models.json).
+	 */
+	async refresh(strategy: ModelRefreshStrategy = "online-if-uncached"): Promise<void> {
+		this.#modelsConfigFile.invalidate();
+		this.#customProviderApiKeys.clear();
+		this.#keylessProviders.clear();
+		this.#discoverableProviders = [];
+		this.#modelOverrides.clear();
+		this.#configError = undefined;
+		this.#loadModels();
+		await this.#refreshRuntimeDiscoveries(strategy);
+	}
+
+	/**
+	 * Get any error from loading models.json (undefined if no error).
+	 */
+	getError(): ConfigError | undefined {
+		return this.#configError;
+	}
+
+	#loadModels() {
+		// Load custom models from models.json first (to know which providers to override)
+		const {
+			models: customModels = [],
+			overrides = new Map(),
+			modelOverrides = new Map(),
+			keylessProviders = new Set(),
+			discoverableProviders = [],
+			configuredProviders = new Set(),
+			error: configError,
+		} = this.#loadCustomModels();
+		this.#configError = configError;
+		this.#keylessProviders = keylessProviders;
+		this.#discoverableProviders = discoverableProviders;
+		this.#modelOverrides = modelOverrides;
+
+		this.#addImplicitDiscoverableProviders(configuredProviders);
+		const builtInModels = this.#loadBuiltInModels(overrides, modelOverrides);
+		const combined = this.#mergeCustomModels(builtInModels, customModels);
+
+		// Update github-copilot base URL based on OAuth credentials
+		const copilotCred = this.authStorage.getOAuthCredential("github-copilot");
+		if (copilotCred) {
+			const domain = copilotCred.enterpriseUrl
+				? (normalizeDomain(copilotCred.enterpriseUrl) ?? undefined)
+				: undefined;
+			const baseUrl = getGitHubCopilotBaseUrl(copilotCred.access, domain);
+			this.#models = combined.map(m => (m.provider === "github-copilot" ? { ...m, baseUrl } : m));
+		} else {
+			this.#models = combined;
+		}
+	}
+
+	/** Load built-in models, applying provider and per-model overrides */
+	#loadBuiltInModels(
+		overrides: Map<string, ProviderOverride>,
+		modelOverrides: Map<string, Map<string, ModelOverride>>,
+	): Model<Api>[] {
+		return getBundledProviders().flatMap(provider => {
+			const models = getBundledModels(provider as Parameters<typeof getBundledModels>[0]) as Model<Api>[];
+			const providerOverride = overrides.get(provider);
+			const perModelOverrides = modelOverrides.get(provider);
+
+			return models.map(m => {
+				let model = m;
+				if (providerOverride) {
+					model = {
+						...model,
+						baseUrl: providerOverride.baseUrl ?? model.baseUrl,
+						headers: providerOverride.headers ? { ...model.headers, ...providerOverride.headers } : model.headers,
+					};
+				}
+				const modelOverride = perModelOverrides?.get(m.id);
+				if (modelOverride) {
+					model = applyModelOverride(model, modelOverride);
+				}
+				return model;
+			});
+		});
+	}
+
+	/** Merge custom models with built-in, replacing by provider+id match */
+	#mergeCustomModels(builtInModels: Model<Api>[], customModels: Model<Api>[]): Model<Api>[] {
+		const merged = [...builtInModels];
+		for (const customModel of customModels) {
+			const existingIndex = merged.findIndex(m => m.provider === customModel.provider && m.id === customModel.id);
+			if (existingIndex >= 0) {
+				merged[existingIndex] = customModel;
+			} else {
+				merged.push(customModel);
+			}
+		}
+		return merged;
+	}
+
+	#addImplicitDiscoverableProviders(configuredProviders: Set<string>): void {
+		if (configuredProviders.has("ollama")) return;
+		this.#discoverableProviders.push({
+			provider: "ollama",
+			api: "openai-completions",
+			baseUrl: Bun.env.OLLAMA_BASE_URL || "http://127.0.0.1:11434",
+			discovery: { type: "ollama" },
+		});
+		this.#keylessProviders.add("ollama");
+	}
+
+	#loadCustomModels(): CustomModelsResult {
+		const { value, error, status } = this.#modelsConfigFile.tryLoad();
+
+		if (status === "error") {
+			return {
+				models: [],
+				overrides: new Map(),
+				modelOverrides: new Map(),
+				keylessProviders: new Set(),
+				discoverableProviders: [],
+				configuredProviders: new Set(),
+				error,
+				found: true,
+			};
+		} else if (status === "not-found") {
+			return {
+				models: [],
+				overrides: new Map(),
+				modelOverrides: new Map(),
+				keylessProviders: new Set(),
+				discoverableProviders: [],
+				configuredProviders: new Set(),
+				found: false,
+			};
+		}
+
+		const overrides = new Map<string, ProviderOverride>();
+		const allModelOverrides = new Map<string, Map<string, ModelOverride>>();
+		const keylessProviders = new Set<string>();
+		const discoverableProviders: DiscoveryProviderConfig[] = [];
+		const configuredProviders = new Set(Object.keys(value.providers));
+
+		for (const [providerName, providerConfig] of Object.entries(value.providers)) {
+			// Always set overrides when baseUrl/headers present
+			if (providerConfig.baseUrl || providerConfig.headers || providerConfig.apiKey) {
+				overrides.set(providerName, {
+					baseUrl: providerConfig.baseUrl,
+					headers: providerConfig.headers,
+					apiKey: providerConfig.apiKey,
+				});
+			}
+
+			const authMode = (providerConfig.auth ?? "apiKey") as ProviderAuthMode;
+			if (authMode === "none") {
+				keylessProviders.add(providerName);
+			}
+
+			if (providerConfig.discovery && providerConfig.api) {
+				discoverableProviders.push({
+					provider: providerName,
+					api: providerConfig.api as Api,
+					baseUrl: providerConfig.baseUrl,
+					headers: providerConfig.headers,
+					discovery: providerConfig.discovery,
+				});
+			}
+
+			// Always store API key for fallback resolver
+			if (providerConfig.apiKey) {
+				this.#customProviderApiKeys.set(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);
+				}
+				allModelOverrides.set(providerName, perModel);
+			}
+		}
+
+		return {
+			models: this.#parseModels(value),
+			overrides,
+			modelOverrides: allModelOverrides,
+			keylessProviders,
+			discoverableProviders,
+			configuredProviders,
+			found: true,
+		};
+	}
+
+	async #refreshRuntimeDiscoveries(strategy: ModelRefreshStrategy): Promise<void> {
+		const configuredDiscoveriesPromise =
+			this.#discoverableProviders.length === 0
+				? Promise.resolve<Model<Api>[]>([])
+				: Promise.all(this.#discoverableProviders.map(provider => this.#discoverProviderModels(provider))).then(
+						results => results.flat(),
+					);
+		const [configuredDiscovered, builtInDiscovered] = await Promise.all([
+			configuredDiscoveriesPromise,
+			this.#discoverBuiltInProviderModels(strategy),
+		]);
+		const discovered = [...configuredDiscovered, ...builtInDiscovered];
+		if (discovered.length === 0) {
+			return;
+		}
+		const merged = this.#mergeCustomModels(
+			this.#models,
+			discovered.map(model => {
+				const existing =
+					this.find(model.provider, model.id) ??
+					this.#models.find(candidate => candidate.provider === model.provider);
+				return existing
+					? {
+							...model,
+							baseUrl: existing.baseUrl,
+							headers: existing.headers ? { ...existing.headers, ...model.headers } : model.headers,
+						}
+					: model;
+			}),
+		);
+		this.#models = this.#applyModelOverrides(merged, this.#modelOverrides);
+	}
+
+	async #discoverProviderModels(providerConfig: DiscoveryProviderConfig): Promise<Model<Api>[]> {
+		switch (providerConfig.discovery.type) {
+			case "ollama":
+				return this.#discoverOllamaModels(providerConfig);
+		}
+	}
+
+	async #discoverBuiltInProviderModels(strategy: ModelRefreshStrategy): Promise<Model<Api>[]> {
+		// Skip providers already handled by configured discovery (e.g. user-configured ollama with discovery.type)
+		const configuredDiscoveryProviders = new Set(this.#discoverableProviders.map(p => p.provider));
+		const managerOptions = (await this.#collectBuiltInModelManagerOptions()).filter(
+			opts => !configuredDiscoveryProviders.has(opts.providerId),
+		);
+		if (managerOptions.length === 0) {
+			return [];
+		}
+		const discoveries = await Promise.all(
+			managerOptions.map(options => this.#discoverWithModelManager(options, strategy)),
+		);
+		return discoveries.flat();
+	}
+
+	async #collectBuiltInModelManagerOptions(): Promise<ModelManagerOptions<Api>[]> {
+		const specialProviderDescriptors: Array<{
+			providerId: string;
+			resolveKey: (value: string | undefined) => string | undefined;
+			createOptions: (key: string) => ModelManagerOptions<Api>;
+		}> = [
+			{
+				providerId: "google-antigravity",
+				resolveKey: extractGoogleOAuthToken,
+				createOptions: oauthToken =>
+					googleAntigravityModelManagerOptions({
+						oauthToken,
+						endpoint: this.getProviderBaseUrl("google-antigravity"),
+					}),
+			},
+			{
+				providerId: "google-gemini-cli",
+				resolveKey: extractGoogleOAuthToken,
+				createOptions: oauthToken =>
+					googleGeminiCliModelManagerOptions({
+						oauthToken,
+						endpoint: this.getProviderBaseUrl("google-gemini-cli"),
+					}),
+			},
+			{
+				providerId: "openai-codex",
+				resolveKey: value => value,
+				createOptions: accessToken => {
+					const accountId = resolveOAuthAccountIdForAccessToken(this.authStorage, "openai-codex", accessToken);
+					return openaiCodexModelManagerOptions({
+						accessToken,
+						accountId,
+					});
+				},
+			},
+		];
+		// Use peekApiKey to avoid OAuth token refresh during discovery.
+		// The token is only needed if the dynamic fetch fires (cache miss),
+		// and failures there are handled gracefully.
+		const peekKey = (descriptor: { providerId: string }) => this.#peekApiKeyForProvider(descriptor.providerId);
+		const [standardProviderKeys, specialKeys] = await Promise.all([
+			Promise.all(PROVIDER_DESCRIPTORS.map(peekKey)),
+			Promise.all(specialProviderDescriptors.map(peekKey)),
+		]);
+		const options: ModelManagerOptions<Api>[] = [];
+		for (let i = 0; i < PROVIDER_DESCRIPTORS.length; i++) {
+			const descriptor = PROVIDER_DESCRIPTORS[i];
+			const apiKey = standardProviderKeys[i];
+			if (isAuthenticated(apiKey) || descriptor.allowUnauthenticated) {
+				options.push(
+					descriptor.createModelManagerOptions({
+						apiKey: isAuthenticated(apiKey) ? apiKey : undefined,
+						baseUrl: this.getProviderBaseUrl(descriptor.providerId),
+					}),
+				);
+			}
+		}
+
+		for (let i = 0; i < specialProviderDescriptors.length; i++) {
+			const descriptor = specialProviderDescriptors[i];
+			const key = descriptor.resolveKey(specialKeys[i]);
+			if (!isAuthenticated(key)) {
+				continue;
+			}
+			options.push(descriptor.createOptions(key));
+		}
+		return options;
+	}
+
+	async #discoverWithModelManager(
+		options: ModelManagerOptions<Api>,
+		strategy: ModelRefreshStrategy,
+	): Promise<Model<Api>[]> {
+		try {
+			const manager = createModelManager(options);
+			const result = await manager.refresh(strategy);
+			return result.models.map(model =>
+				model.provider === options.providerId ? model : { ...model, provider: options.providerId },
+			);
+		} catch (error) {
+			logger.warn("model discovery failed for provider", {
+				provider: options.providerId,
+				error: error instanceof Error ? error.message : String(error),
+			});
+			return [];
+		}
+	}
+
+	async #discoverOllamaModels(providerConfig: DiscoveryProviderConfig): Promise<Model<Api>[]> {
+		const endpoint = this.#normalizeOllamaBaseUrl(providerConfig.baseUrl);
+		const tagsUrl = `${endpoint}/api/tags`;
+		try {
+			const response = await fetch(tagsUrl, {
+				headers: { ...(providerConfig.headers ?? {}) },
+				signal: AbortSignal.timeout(3000),
+			});
+			if (!response.ok) {
+				logger.warn("model discovery failed for provider", {
+					provider: providerConfig.provider,
+					status: response.status,
+					url: tagsUrl,
+				});
+				return [];
+			}
+			const payload = (await response.json()) as { models?: Array<{ name?: string; model?: string }> };
+			const models = payload.models ?? [];
+			const discovered: Model<Api>[] = [];
+			for (const item of models) {
+				const id = item.model || item.name;
+				if (!id) continue;
+				discovered.push({
+					id,
+					name: item.name || id,
+					api: providerConfig.api,
+					provider: providerConfig.provider,
+					baseUrl: `${endpoint}/v1`,
+					reasoning: false,
+					input: ["text"],
+					cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+					contextWindow: 128000,
+					maxTokens: 8192,
+					headers: providerConfig.headers,
+				});
+			}
+			return this.#applyProviderModelOverrides(providerConfig.provider, discovered);
+		} catch (error) {
+			logger.warn("model discovery failed for provider", {
+				provider: providerConfig.provider,
+				url: tagsUrl,
+				error: error instanceof Error ? error.message : String(error),
+			});
+			return [];
+		}
+	}
+
+	#normalizeOllamaBaseUrl(baseUrl?: string): string {
+		const raw = baseUrl || "http://127.0.0.1:11434";
+		try {
+			const parsed = new URL(raw);
+			return `${parsed.protocol}//${parsed.host}`;
+		} catch {
+			return "http://127.0.0.1:11434";
+		}
+	}
+
+	#applyProviderModelOverrides(provider: string, models: Model<Api>[]): Model<Api>[] {
+		const overrides = this.#modelOverrides.get(provider);
+		if (!overrides || overrides.size === 0) return models;
+		return models.map(model => {
+			const override = overrides.get(model.id);
+			if (!override) return model;
+			return applyModelOverride(model, override);
+		});
+	}
+
+	#applyModelOverrides(models: Model<Api>[], overrides: Map<string, Map<string, ModelOverride>>): Model<Api>[] {
+		if (overrides.size === 0) return models;
+		return models.map(model => {
+			const providerOverrides = overrides.get(model.provider);
+			if (!providerOverrides) return model;
+			const override = providerOverrides.get(model.id);
+			if (!override) return model;
+			return applyModelOverride(model, override);
+		});
+	}
+
+	#parseModels(config: ModelsConfig): Model<Api>[] {
+		const models: Model<Api>[] = [];
+
+		for (const [providerName, providerConfig] of Object.entries(config.providers)) {
+			const modelDefs = providerConfig.models ?? [];
+			if (modelDefs.length === 0) continue; // Override-only, no custom models
+			if (providerConfig.apiKey) {
+				this.#customProviderApiKeys.set(providerName, providerConfig.apiKey);
+			}
+			for (const modelDef of modelDefs) {
+				const model = buildCustomModel(
+					providerName,
+					providerConfig.baseUrl!,
+					providerConfig.api as Api | undefined,
+					providerConfig.headers,
+					providerConfig.apiKey,
+					providerConfig.authHeader,
+					modelDef,
+					{ useDefaults: true },
+				);
+				if (!model) continue;
+				models.push(model);
+			}
+		}
+		return models;
+	}
+
+	/**
+	 * Get all models (built-in + custom).
+	 * If models.json had errors, returns only built-in models.
+	 */
+	getAll(): Model<Api>[] {
+		return this.#models;
+	}
+
+	/**
+	 * Get only models that have auth configured.
+	 * This is a fast check that doesn't refresh OAuth tokens.
+	 */
+	getAvailable(): Model<Api>[] {
+		return this.#models.filter(m => this.#keylessProviders.has(m.provider) || this.authStorage.hasAuth(m.provider));
+	}
+
+	/**
+	 * Find a model by provider and ID.
+	 */
+	find(provider: string, modelId: string): Model<Api> | undefined {
+		return this.#models.find(m => m.provider === provider && m.id === modelId);
+	}
+
+	/**
+	 * Get the base URL associated with a provider, if any model defines one.
+	 */
+	getProviderBaseUrl(provider: string): string | undefined {
+		return this.#models.find(m => m.provider === provider && m.baseUrl)?.baseUrl;
+	}
+
+	/**
+	 * Get API key for a model.
+	 */
+	async getApiKey(model: Model<Api>, sessionId?: string): Promise<string | undefined> {
+		if (this.#keylessProviders.has(model.provider)) {
+			return kNoAuth;
+		}
+		return this.authStorage.getApiKey(model.provider, sessionId, { baseUrl: model.baseUrl });
+	}
+
+	/**
+	 * Get API key for a provider (e.g., "openai").
+	 */
+	async getApiKeyForProvider(provider: string, sessionId?: string, baseUrl?: string): Promise<string | undefined> {
+		if (this.#keylessProviders.has(provider)) {
+			return kNoAuth;
+		}
+		return this.authStorage.getApiKey(provider, sessionId, { baseUrl });
+	}
+
+	async #peekApiKeyForProvider(provider: string): Promise<string | undefined> {
+		if (this.#keylessProviders.has(provider)) {
+			return kNoAuth;
+		}
+		return this.authStorage.peekApiKey(provider);
+	}
+
+	/**
+	 * Check if a model is using OAuth credentials (subscription).
+	 */
+	isUsingOAuth(model: Model<Api>): boolean {
+		return this.authStorage.hasOAuth(model.provider);
+	}
+
+	/**
+	 * Remove custom API/OAuth registrations for a specific extension source.
+	 */
+	clearSourceRegistrations(sourceId: string): void {
+		unregisterCustomApis(sourceId);
+		unregisterOAuthProviders(sourceId);
+	}
+
+	/**
+	 * Remove registrations for extension sources that are no longer active.
+	 */
+	syncExtensionSources(activeSourceIds: string[]): void {
+		const activeSources = new Set(activeSourceIds);
+		for (const sourceId of this.#registeredProviderSources) {
+			if (activeSources.has(sourceId)) {
+				continue;
+			}
+			this.clearSourceRegistrations(sourceId);
+			this.#registeredProviderSources.delete(sourceId);
+		}
+	}
+
+	/**
+	 * Register a provider dynamically (from extensions).
+	 *
+	 * If provider has models: replaces all existing models for this provider.
+	 * If provider has only baseUrl/headers: overrides existing models' URLs.
+	 * If provider has streamSimple: registers a custom API streaming function.
+	 * If provider has oauth: registers OAuth provider for /login support.
+	 */
+	registerProvider(providerName: string, config: ProviderConfigInput, sourceId?: string): void {
+		if (config.streamSimple && !config.api) {
+			throw new Error(`Provider ${providerName}: "api" is required when registering streamSimple.`);
+		}
+
+		validateProviderConfiguration(
+			providerName,
+			{
+				baseUrl: config.baseUrl,
+				apiKey: config.apiKey,
+				api: config.api,
+				oauthConfigured: Boolean(config.oauth),
+				models: (config.models ?? []) as ProviderValidationModel[],
+			},
+			"runtime-register",
+		);
+
+		if (config.streamSimple && config.api) {
+			const streamSimple = config.streamSimple;
+			registerCustomApi(config.api, streamSimple, sourceId, (model, context, options) =>
+				streamSimple(model, context, options as SimpleStreamOptions),
+			);
+		}
+
+		if (config.oauth) {
+			registerOAuthProvider({
+				...config.oauth,
+				id: providerName,
+				sourceId,
+			});
+		}
+
+		if (sourceId) {
+			this.#registeredProviderSources.add(sourceId);
+		}
+		if (config.apiKey) {
+			this.#customProviderApiKeys.set(providerName, config.apiKey);
+		}
+
+		if (config.models && config.models.length > 0) {
+			const nextModels = this.#models.filter(m => m.provider !== providerName);
+			for (const modelDef of config.models) {
+				const model = buildCustomModel(
+					providerName,
+					config.baseUrl!,
+					config.api,
+					config.headers,
+					config.apiKey,
+					config.authHeader,
+					modelDef,
+					{ useDefaults: false },
+				);
+				if (!model) {
+					throw new Error(`Provider ${providerName}, model ${modelDef.id}: no "api" specified.`);
+				}
+				nextModels.push(model);
+			}
+
+			if (config.oauth?.modifyModels) {
+				const credential = this.authStorage.getOAuthCredential(providerName);
+				if (credential) {
+					this.#models = config.oauth.modifyModels(nextModels, credential);
+					return;
+				}
+			}
+
+			this.#models = nextModels;
+			return;
+		}
+
+		if (config.baseUrl) {
+			this.#models = this.#models.map(m => {
+				if (m.provider !== providerName) return m;
+				return {
+					...m,
+					baseUrl: config.baseUrl ?? m.baseUrl,
+					headers: config.headers ? { ...m.headers, ...config.headers } : m.headers,
+				};
+			});
+		}
+	}
+}
+
+/**
+ * Input type for registerProvider API (from extensions).
+ */
+export interface ProviderConfigInput {
+	baseUrl?: string;
+	apiKey?: string;
+	api?: Api;
+	streamSimple?: (model: Model<Api>, context: Context, options?: SimpleStreamOptions) => AssistantMessageEventStream;
+	headers?: Record<string, string>;
+	authHeader?: boolean;
+	oauth?: {
+		name: string;
+		login(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials | string>;
+		refreshToken?(credentials: OAuthCredentials): Promise<OAuthCredentials>;
+		getApiKey?(credentials: OAuthCredentials): string;
+		modifyModels?(models: Model<Api>[], credentials: OAuthCredentials): Model<Api>[];
+	};
+	models?: Array<{
+		id: string;
+		name: string;
+		api?: Api;
+		reasoning: boolean;
+		input: ("text" | "image")[];
+		cost: { input: number; output: number; cacheRead: number; cacheWrite: number };
+		contextWindow: number;
+		maxTokens: number;
+		headers?: Record<string, string>;
+		compat?: Model<Api>["compat"];
+		contextPromotionTarget?: string;
+	}>;
+}