@nghyane/arcane 0.1.0

package/src/config/model-resolver.ts

@@ -0,0 +1,812 @@
+/**
+ * Model resolution, scoping, and initial selection
+ */
+import type { ThinkingLevel } from "@nghyane/arcane-agent";
+import {
+	type Api,
+	DEFAULT_MODEL_PER_PROVIDER,
+	type KnownProvider,
+	type Model,
+	modelsAreEqual,
+} from "@nghyane/arcane-ai";
+import chalk from "chalk";
+import { isValidThinkingLevel } from "../cli/args";
+import MODEL_PRIO from "../priority.json" with { type: "json" };
+import { fuzzyMatch } from "../utils/fuzzy";
+import { MODEL_ROLE_IDS, type ModelRegistry, type ModelRole } from "./model-registry";
+import type { Settings } from "./settings";
+
+/** Default model IDs for each known provider */
+export const defaultModelPerProvider: Record<KnownProvider, string> = DEFAULT_MODEL_PER_PROVIDER;
+
+export interface ScopedModel {
+	model: Model<Api>;
+	thinkingLevel?: ThinkingLevel;
+	explicitThinkingLevel: boolean;
+}
+
+/**
+ * Parse a model string in "provider/modelId" format.
+ * Returns undefined if the format is invalid.
+ */
+export function parseModelString(modelStr: string): { provider: string; id: string } | undefined {
+	const slashIdx = modelStr.indexOf("/");
+	if (slashIdx <= 0) return undefined;
+	return { provider: modelStr.slice(0, slashIdx), id: modelStr.slice(slashIdx + 1) };
+}
+
+/**
+ * Format a model as "provider/modelId" string.
+ */
+export function formatModelString(model: Model<Api>): string {
+	return `${model.provider}/${model.id}`;
+}
+
+export interface ModelMatchPreferences {
+	/** Most-recently-used model keys (provider/modelId) to prefer when ambiguous. */
+	usageOrder?: string[];
+	/** Providers to deprioritize when no recent usage is available. */
+	deprioritizeProviders?: string[];
+}
+
+interface ModelPreferenceContext {
+	modelUsageRank: Map<string, number>;
+	providerUsageRank: Map<string, number>;
+	deprioritizedProviders: Set<string>;
+	modelOrder: Map<string, number>;
+}
+
+function buildPreferenceContext(
+	availableModels: Model<Api>[],
+	preferences: ModelMatchPreferences | undefined,
+): ModelPreferenceContext {
+	const modelUsageRank = new Map<string, number>();
+	const providerUsageRank = new Map<string, number>();
+	const usageOrder = preferences?.usageOrder ?? [];
+	for (let i = 0; i < usageOrder.length; i += 1) {
+		const key = usageOrder[i];
+		if (!modelUsageRank.has(key)) {
+			modelUsageRank.set(key, i);
+		}
+		const parsed = parseModelString(key);
+		if (parsed && !providerUsageRank.has(parsed.provider)) {
+			providerUsageRank.set(parsed.provider, i);
+		}
+	}
+
+	const deprioritizedProviders = new Set(preferences?.deprioritizeProviders ?? ["openrouter"]);
+	const modelOrder = new Map<string, number>();
+	for (let i = 0; i < availableModels.length; i += 1) {
+		modelOrder.set(formatModelString(availableModels[i]), i);
+	}
+
+	return { modelUsageRank, providerUsageRank, deprioritizedProviders, modelOrder };
+}
+
+function pickPreferredModel(candidates: Model<Api>[], context: ModelPreferenceContext): Model<Api> {
+	if (candidates.length <= 1) return candidates[0];
+	return [...candidates].sort((a, b) => {
+		const aKey = formatModelString(a);
+		const bKey = formatModelString(b);
+		const aUsage = context.modelUsageRank.get(aKey);
+		const bUsage = context.modelUsageRank.get(bKey);
+		if (aUsage !== undefined || bUsage !== undefined) {
+			return (aUsage ?? Number.POSITIVE_INFINITY) - (bUsage ?? Number.POSITIVE_INFINITY);
+		}
+
+		const aProviderUsage = context.providerUsageRank.get(a.provider);
+		const bProviderUsage = context.providerUsageRank.get(b.provider);
+		if (aProviderUsage !== undefined || bProviderUsage !== undefined) {
+			return (aProviderUsage ?? Number.POSITIVE_INFINITY) - (bProviderUsage ?? Number.POSITIVE_INFINITY);
+		}
+
+		const aDeprioritized = context.deprioritizedProviders.has(a.provider);
+		const bDeprioritized = context.deprioritizedProviders.has(b.provider);
+		if (aDeprioritized !== bDeprioritized) {
+			return aDeprioritized ? 1 : -1;
+		}
+
+		const aOrder = context.modelOrder.get(aKey) ?? 0;
+		const bOrder = context.modelOrder.get(bKey) ?? 0;
+		return aOrder - bOrder;
+	})[0];
+}
+
+/**
+ * Helper to check if a model ID looks like an alias (no date suffix)
+ * Dates are typically in format: -20241022 or -20250929
+ */
+function isAlias(id: string): boolean {
+	// Check if ID ends with -latest
+	if (id.endsWith("-latest")) return true;
+
+	// Check if ID ends with a date pattern (-YYYYMMDD)
+	const datePattern = /-\d{8}$/;
+	return !datePattern.test(id);
+}
+
+/**
+ * Try to match a pattern to a model from the available models list.
+ * Returns the matched model or undefined if no match found.
+ */
+function tryMatchModel(
+	modelPattern: string,
+	availableModels: Model<Api>[],
+	context: ModelPreferenceContext,
+): Model<Api> | undefined {
+	// Check for provider/modelId format (provider is everything before the first /)
+	const slashIndex = modelPattern.indexOf("/");
+	if (slashIndex !== -1) {
+		const provider = modelPattern.substring(0, slashIndex);
+		const modelId = modelPattern.substring(slashIndex + 1);
+		const providerMatch = availableModels.find(
+			m => m.provider.toLowerCase() === provider.toLowerCase() && m.id.toLowerCase() === modelId.toLowerCase(),
+		);
+		if (providerMatch) {
+			return providerMatch;
+		}
+
+		const providerModels = availableModels.filter(m => m.provider.toLowerCase() === provider.toLowerCase());
+		if (providerModels.length > 0) {
+			const scored = providerModels
+				.map(model => ({ model, match: fuzzyMatch(modelId, model.id) }))
+				.filter(entry => entry.match.matches);
+			if (scored.length > 0) {
+				scored.sort((a, b) => {
+					if (a.match.score !== b.match.score) return a.match.score - b.match.score;
+					const aKey = formatModelString(a.model);
+					const bKey = formatModelString(b.model);
+					const aUsage = context.modelUsageRank.get(aKey) ?? Number.POSITIVE_INFINITY;
+					const bUsage = context.modelUsageRank.get(bKey) ?? Number.POSITIVE_INFINITY;
+					if (aUsage !== bUsage) return aUsage - bUsage;
+
+					const aProviderUsage = context.providerUsageRank.get(a.model.provider) ?? Number.POSITIVE_INFINITY;
+					const bProviderUsage = context.providerUsageRank.get(b.model.provider) ?? Number.POSITIVE_INFINITY;
+					if (aProviderUsage !== bProviderUsage) return aProviderUsage - bProviderUsage;
+
+					const aOrder = context.modelOrder.get(aKey) ?? 0;
+					const bOrder = context.modelOrder.get(bKey) ?? 0;
+					return aOrder - bOrder;
+				});
+				return scored[0]?.model;
+			}
+		}
+		// No exact provider/model match - fall through to other matching
+	}
+
+	// Check for exact ID match (case-insensitive)
+	const exactMatches = availableModels.filter(m => m.id.toLowerCase() === modelPattern.toLowerCase());
+	if (exactMatches.length > 0) {
+		return pickPreferredModel(exactMatches, context);
+	}
+
+	// No exact match - fall back to partial matching
+	const matches = availableModels.filter(
+		m =>
+			m.id.toLowerCase().includes(modelPattern.toLowerCase()) ||
+			m.name?.toLowerCase().includes(modelPattern.toLowerCase()),
+	);
+
+	if (matches.length === 0) {
+		return undefined;
+	}
+
+	// Separate into aliases and dated versions
+	const aliases = matches.filter(m => isAlias(m.id));
+	const datedVersions = matches.filter(m => !isAlias(m.id));
+
+	if (aliases.length > 0) {
+		return pickPreferredModel(aliases, context);
+	}
+	if (datedVersions.length === 0) return undefined;
+
+	if (datedVersions.length === 1) {
+		return datedVersions[0];
+	}
+
+	const sortedById = [...datedVersions].sort((a, b) => b.id.localeCompare(a.id));
+	const topId = sortedById[0]?.id;
+	if (!topId) return undefined;
+	const topCandidates = sortedById.filter(model => model.id === topId);
+	return pickPreferredModel(topCandidates, context);
+}
+
+export interface ParsedModelResult {
+	model: Model<Api> | undefined;
+	/** Thinking level if explicitly specified in pattern, undefined otherwise */
+	thinkingLevel?: ThinkingLevel;
+	warning: string | undefined;
+	explicitThinkingLevel: boolean;
+}
+
+/**
+ * Parse a pattern to extract model and thinking level.
+ * Handles models with colons in their IDs (e.g., OpenRouter's :exacto suffix).
+ *
+ * Algorithm:
+ * 1. Try to match full pattern as a model
+ * 2. If found, return it with undefined thinking level
+ * 3. If not found and has colons, split on last colon:
+ *    - If suffix is valid thinking level, use it and recurse on prefix
+ *    - If suffix is invalid, warn and recurse on prefix
+ *
+ * @internal Exported for testing
+ */
+function parseModelPatternWithContext(
+	pattern: string,
+	availableModels: Model<Api>[],
+	context: ModelPreferenceContext,
+	options?: { allowInvalidThinkingLevelFallback?: boolean },
+): ParsedModelResult {
+	// Try exact match first
+	const exactMatch = tryMatchModel(pattern, availableModels, context);
+	if (exactMatch) {
+		return { model: exactMatch, thinkingLevel: undefined, warning: undefined, explicitThinkingLevel: false };
+	}
+
+	// No match - try splitting on last colon if present
+	const lastColonIndex = pattern.lastIndexOf(":");
+	if (lastColonIndex === -1) {
+		// No colons, pattern simply doesn't match any model
+		return { model: undefined, thinkingLevel: undefined, warning: undefined, explicitThinkingLevel: false };
+	}
+
+	const prefix = pattern.substring(0, lastColonIndex);
+	const suffix = pattern.substring(lastColonIndex + 1);
+
+	if (isValidThinkingLevel(suffix)) {
+		// Valid thinking level - recurse on prefix and use this level
+		const result = parseModelPatternWithContext(prefix, availableModels, context, options);
+		if (result.model) {
+			// Only use this thinking level if no warning from inner recursion
+			const explicitThinkingLevel = !result.warning;
+			return {
+				model: result.model,
+				thinkingLevel: explicitThinkingLevel ? suffix : undefined,
+				warning: result.warning,
+				explicitThinkingLevel,
+			};
+		}
+		return result;
+	}
+
+	const allowFallback = options?.allowInvalidThinkingLevelFallback ?? true;
+	if (!allowFallback) {
+		return { model: undefined, thinkingLevel: undefined, warning: undefined, explicitThinkingLevel: false };
+	}
+
+	// Invalid suffix - recurse on prefix and warn
+	const result = parseModelPatternWithContext(prefix, availableModels, context, options);
+	if (result.model) {
+		return {
+			model: result.model,
+			thinkingLevel: undefined,
+			warning: `Invalid thinking level "${suffix}" in pattern "${pattern}". Using default instead.`,
+			explicitThinkingLevel: false,
+		};
+	}
+	return result;
+}
+
+export function parseModelPattern(
+	pattern: string,
+	availableModels: Model<Api>[],
+	preferences?: ModelMatchPreferences,
+	options?: { allowInvalidThinkingLevelFallback?: boolean },
+): ParsedModelResult {
+	const context = buildPreferenceContext(availableModels, preferences);
+	return parseModelPatternWithContext(pattern, availableModels, context, options);
+}
+
+const PREFIX_MODEL_ROLE = "arcane/";
+const DEFAULT_MODEL_ROLE = "default";
+
+/**
+ * Check if a model override value is effectively the default role.
+ */
+export function isDefaultModelAlias(value: string | string[] | undefined): boolean {
+	if (!value) return true;
+	if (Array.isArray(value)) return value.every(entry => isDefaultModelAlias(entry));
+	if (value.startsWith(PREFIX_MODEL_ROLE)) {
+		value = value.slice(PREFIX_MODEL_ROLE.length);
+	}
+	return value === DEFAULT_MODEL_ROLE;
+}
+
+/**
+ * Expand a role alias like "arcane/fast" to the configured model string.
+ */
+export function expandRoleAlias(value: string, settings?: Settings): string {
+	const normalized = value.trim();
+	if (normalized === "default") return settings?.getModelRole("default") ?? value;
+	if (!normalized.startsWith(PREFIX_MODEL_ROLE)) return value;
+	const role = normalized.slice(PREFIX_MODEL_ROLE.length) as ModelRole;
+	if (!MODEL_ROLE_IDS.includes(role)) return value;
+	return settings?.getModelRole(role) ?? value;
+}
+
+/**
+ * Resolve a model identifier or pattern to a Model instance.
+ */
+export function resolveModelFromString(
+	value: string,
+	available: Model<Api>[],
+	matchPreferences?: ModelMatchPreferences,
+): Model<Api> | undefined {
+	const parsed = parseModelString(value);
+	if (parsed) {
+		return available.find(model => model.provider === parsed.provider && model.id === parsed.id);
+	}
+	return parseModelPattern(value, available, matchPreferences).model;
+}
+
+/**
+ * Resolve a model from configured roles, honoring order and overrides.
+ */
+export function resolveModelFromSettings(options: {
+	settings: Settings;
+	availableModels: Model<Api>[];
+	matchPreferences?: ModelMatchPreferences;
+	roleOrder?: readonly ModelRole[];
+}): Model<Api> | undefined {
+	const { settings, availableModels, matchPreferences, roleOrder } = options;
+	const roles = roleOrder ?? MODEL_ROLE_IDS;
+	for (const role of roles) {
+		const configured = settings.getModelRole(role);
+		if (!configured) continue;
+		const resolved = resolveModelFromString(expandRoleAlias(configured, settings), availableModels, matchPreferences);
+		if (resolved) return resolved;
+	}
+	return availableModels[0];
+}
+
+/**
+ * Resolve a list of override patterns to the first matching model.
+ */
+export function resolveModelOverride(
+	modelPatterns: string[],
+	modelRegistry: ModelRegistry,
+	settings?: Settings,
+): { model?: Model<Api>; thinkingLevel?: ThinkingLevel } {
+	if (modelPatterns.length === 0) return {};
+	const matchPreferences = { usageOrder: settings?.getStorage()?.getModelUsageOrder() };
+	for (const pattern of modelPatterns) {
+		const normalized = pattern.trim();
+		if (!normalized || isDefaultModelAlias(normalized)) {
+			continue;
+		}
+		const effectivePattern = expandRoleAlias(pattern, settings);
+		const { model, thinkingLevel } = parseModelPattern(
+			effectivePattern,
+			modelRegistry.getAvailable(),
+			matchPreferences,
+		);
+		if (model) {
+			return { model, thinkingLevel: thinkingLevel !== "off" ? thinkingLevel : undefined };
+		}
+	}
+	return {};
+}
+
+/**
+ * Resolve model patterns to actual Model objects with optional thinking levels
+ * Format: "pattern:level" where :level is optional
+ * For each pattern, finds all matching models and picks the best version:
+ * 1. Prefer alias (e.g., claude-sonnet-4-5) over dated versions (claude-sonnet-4-5-20250929)
+ * 2. If no alias, pick the latest dated version
+ *
+ * Supports models with colons in their IDs (e.g., OpenRouter's model:exacto).
+ * The algorithm tries to match the full pattern first, then progressively
+ * strips colon-suffixes to find a match.
+ */
+export async function resolveModelScope(
+	patterns: string[],
+	modelRegistry: ModelRegistry,
+	preferences?: ModelMatchPreferences,
+): Promise<ScopedModel[]> {
+	const availableModels = modelRegistry.getAvailable();
+	const context = buildPreferenceContext(availableModels, preferences);
+	const scopedModels: ScopedModel[] = [];
+
+	for (const pattern of patterns) {
+		// Check if pattern contains glob characters
+		if (pattern.includes("*") || pattern.includes("?") || pattern.includes("[")) {
+			// Extract optional thinking level suffix (e.g., "provider/*:high")
+			const colonIdx = pattern.lastIndexOf(":");
+			let globPattern = pattern;
+			let thinkingLevel: ThinkingLevel | undefined;
+			let explicitThinkingLevel = false;
+
+			if (colonIdx !== -1) {
+				const suffix = pattern.substring(colonIdx + 1);
+				if (isValidThinkingLevel(suffix)) {
+					thinkingLevel = suffix;
+					explicitThinkingLevel = true;
+					globPattern = pattern.substring(0, colonIdx);
+				}
+			}
+
+			// Match against "provider/modelId" format OR just model ID
+			// This allows "*sonnet*" to match without requiring "anthropic/*sonnet*"
+			const matchingModels = availableModels.filter(m => {
+				const fullId = `${m.provider}/${m.id}`;
+				const glob = new Bun.Glob(globPattern.toLowerCase());
+				return glob.match(fullId.toLowerCase()) || glob.match(m.id.toLowerCase());
+			});
+
+			if (matchingModels.length === 0) {
+				console.warn(chalk.yellow(`Warning: No models match pattern "${pattern}"`));
+				continue;
+			}
+
+			for (const model of matchingModels) {
+				if (!scopedModels.find(sm => modelsAreEqual(sm.model, model))) {
+					scopedModels.push({ model, thinkingLevel, explicitThinkingLevel });
+				}
+			}
+			continue;
+		}
+
+		const { model, thinkingLevel, warning, explicitThinkingLevel } = parseModelPatternWithContext(
+			pattern,
+			availableModels,
+			context,
+		);
+
+		if (warning) {
+			console.warn(chalk.yellow(`Warning: ${warning}`));
+		}
+
+		if (!model) {
+			console.warn(chalk.yellow(`Warning: No models match pattern "${pattern}"`));
+			continue;
+		}
+
+		// Avoid duplicates
+		if (!scopedModels.find(sm => modelsAreEqual(sm.model, model))) {
+			scopedModels.push({ model, thinkingLevel, explicitThinkingLevel });
+		}
+	}
+
+	return scopedModels;
+}
+
+export interface ResolveCliModelResult {
+	model: Model<Api> | undefined;
+	thinkingLevel?: ThinkingLevel;
+	warning: string | undefined;
+	error: string | undefined;
+}
+
+/**
+ * Resolve a single model from CLI flags.
+ */
+export function resolveCliModel(options: {
+	cliProvider?: string;
+	cliModel?: string;
+	modelRegistry: ModelRegistry;
+	preferences?: ModelMatchPreferences;
+}): ResolveCliModelResult {
+	const { cliProvider, cliModel, modelRegistry, preferences } = options;
+
+	if (!cliModel) {
+		return { model: undefined, warning: undefined, error: undefined };
+	}
+
+	const availableModels = modelRegistry.getAll();
+	if (availableModels.length === 0) {
+		return {
+			model: undefined,
+			warning: undefined,
+			error: "No models available. Check your installation or add models to models.json.",
+		};
+	}
+
+	const providerMap = new Map<string, string>();
+	for (const model of availableModels) {
+		providerMap.set(model.provider.toLowerCase(), model.provider);
+	}
+
+	let provider = cliProvider ? providerMap.get(cliProvider.toLowerCase()) : undefined;
+	if (cliProvider && !provider) {
+		return {
+			model: undefined,
+			warning: undefined,
+			error: `Unknown provider "${cliProvider}". Use --list-models to see available providers/models.`,
+		};
+	}
+
+	if (!provider) {
+		const lower = cliModel.toLowerCase();
+		const exact = availableModels.find(
+			model => model.id.toLowerCase() === lower || `${model.provider}/${model.id}`.toLowerCase() === lower,
+		);
+		if (exact) {
+			return { model: exact, warning: undefined, thinkingLevel: undefined, error: undefined };
+		}
+	}
+
+	let pattern = cliModel;
+
+	if (!provider) {
+		const slashIndex = cliModel.indexOf("/");
+		if (slashIndex !== -1) {
+			const maybeProvider = cliModel.substring(0, slashIndex);
+			const canonical = providerMap.get(maybeProvider.toLowerCase());
+			if (canonical) {
+				provider = canonical;
+				pattern = cliModel.substring(slashIndex + 1);
+			}
+		}
+	} else {
+		const prefix = `${provider}/`;
+		if (cliModel.toLowerCase().startsWith(prefix.toLowerCase())) {
+			pattern = cliModel.substring(prefix.length);
+		}
+	}
+
+	const candidates = provider ? availableModels.filter(model => model.provider === provider) : availableModels;
+	const { model, thinkingLevel, warning } = parseModelPattern(pattern, candidates, preferences, {
+		allowInvalidThinkingLevelFallback: false,
+	});
+
+	if (!model) {
+		const display = provider ? `${provider}/${pattern}` : cliModel;
+		return {
+			model: undefined,
+			thinkingLevel: undefined,
+			warning,
+			error: `Model "${display}" not found. Use --list-models to see available models.`,
+		};
+	}
+
+	return { model, thinkingLevel, warning, error: undefined };
+}
+
+export interface InitialModelResult {
+	model: Model<Api> | undefined;
+	thinkingLevel: ThinkingLevel;
+	fallbackMessage: string | undefined;
+}
+
+/**
+ * Find the initial model to use based on priority:
+ * 1. CLI args (provider + model)
+ * 2. First model from scoped models (if not continuing/resuming)
+ * 3. Restored from session (if continuing/resuming)
+ * 4. Saved default from settings
+ * 5. First available model with valid API key
+ */
+export async function findInitialModel(options: {
+	cliProvider?: string;
+	cliModel?: string;
+	scopedModels: ScopedModel[];
+	isContinuing: boolean;
+	defaultProvider?: string;
+	defaultModelId?: string;
+	defaultThinkingLevel?: ThinkingLevel;
+	modelRegistry: ModelRegistry;
+}): Promise<InitialModelResult> {
+	const {
+		cliProvider,
+		cliModel,
+		scopedModels,
+		isContinuing,
+		defaultProvider,
+		defaultModelId,
+		defaultThinkingLevel,
+		modelRegistry,
+	} = options;
+
+	let model: Model<Api> | undefined;
+	let thinkingLevel: ThinkingLevel = "off";
+
+	// 1. CLI args take priority
+	if (cliProvider && cliModel) {
+		const found = modelRegistry.find(cliProvider, cliModel);
+		if (!found) {
+			console.error(chalk.red(`Model ${cliProvider}/${cliModel} not found`));
+			process.exit(1);
+		}
+		return { model: found, thinkingLevel: "off", fallbackMessage: undefined };
+	}
+
+	// 2. Use first model from scoped models (skip if continuing/resuming)
+	if (scopedModels.length > 0 && !isContinuing) {
+		const scoped = scopedModels[0];
+		const scopedThinkingLevel = scoped.thinkingLevel ?? defaultThinkingLevel ?? "off";
+		return {
+			model: scoped.model,
+			thinkingLevel: scopedThinkingLevel,
+			fallbackMessage: undefined,
+		};
+	}
+
+	// 3. Try saved default from settings
+	if (defaultProvider && defaultModelId) {
+		const found = modelRegistry.find(defaultProvider, defaultModelId);
+		if (found) {
+			model = found;
+			if (defaultThinkingLevel) {
+				thinkingLevel = defaultThinkingLevel;
+			}
+			return { model, thinkingLevel, fallbackMessage: undefined };
+		}
+	}
+
+	// 4. Try first available model with valid API key
+	const availableModels = modelRegistry.getAvailable();
+
+	if (availableModels.length > 0) {
+		// Try to find a default model from known providers
+		for (const provider of Object.keys(defaultModelPerProvider) as KnownProvider[]) {
+			const defaultId = defaultModelPerProvider[provider];
+			const match = availableModels.find(m => m.provider === provider && m.id === defaultId);
+			if (match) {
+				return { model: match, thinkingLevel: "off", fallbackMessage: undefined };
+			}
+		}
+
+		// If no default found, use first available
+		return { model: availableModels[0], thinkingLevel: "off", fallbackMessage: undefined };
+	}
+
+	// 5. No model found
+	return { model: undefined, thinkingLevel: "off", fallbackMessage: undefined };
+}
+
+/**
+ * Restore model from session, with fallback to available models
+ */
+export async function restoreModelFromSession(
+	savedProvider: string,
+	savedModelId: string,
+	currentModel: Model<Api> | undefined,
+	shouldPrintMessages: boolean,
+	modelRegistry: ModelRegistry,
+): Promise<{ model: Model<Api> | undefined; fallbackMessage: string | undefined }> {
+	const restoredModel = modelRegistry.find(savedProvider, savedModelId);
+
+	// Check if restored model exists and has a valid API key
+	const hasApiKey = restoredModel ? !!(await modelRegistry.getApiKey(restoredModel)) : false;
+
+	if (restoredModel && hasApiKey) {
+		if (shouldPrintMessages) {
+			console.log(chalk.dim(`Restored model: ${savedProvider}/${savedModelId}`));
+		}
+		return { model: restoredModel, fallbackMessage: undefined };
+	}
+
+	// Model not found or no API key - fall back
+	const reason = !restoredModel ? "model no longer exists" : "no API key available";
+
+	if (shouldPrintMessages) {
+		console.error(chalk.yellow(`Warning: Could not restore model ${savedProvider}/${savedModelId} (${reason}).`));
+	}
+
+	// If we already have a model, use it as fallback
+	if (currentModel) {
+		if (shouldPrintMessages) {
+			console.log(chalk.dim(`Falling back to: ${currentModel.provider}/${currentModel.id}`));
+		}
+		return {
+			model: currentModel,
+			fallbackMessage: `Could not restore model ${savedProvider}/${savedModelId} (${reason}). Using ${currentModel.provider}/${currentModel.id}.`,
+		};
+	}
+
+	// Try to find any available model
+	const availableModels = modelRegistry.getAvailable();
+
+	if (availableModels.length > 0) {
+		// Try to find a default model from known providers
+		let fallbackModel: Model<Api> | undefined;
+		for (const provider of Object.keys(defaultModelPerProvider) as KnownProvider[]) {
+			const defaultId = defaultModelPerProvider[provider];
+			const match = availableModels.find(m => m.provider === provider && m.id === defaultId);
+			if (match) {
+				fallbackModel = match;
+				break;
+			}
+		}
+
+		// If no default found, use first available
+		if (!fallbackModel) {
+			fallbackModel = availableModels[0];
+		}
+
+		if (shouldPrintMessages) {
+			console.log(chalk.dim(`Falling back to: ${fallbackModel.provider}/${fallbackModel.id}`));
+		}
+
+		return {
+			model: fallbackModel,
+			fallbackMessage: `Could not restore model ${savedProvider}/${savedModelId} (${reason}). Using ${fallbackModel.provider}/${fallbackModel.id}.`,
+		};
+	}
+
+	// No models available
+	return { model: undefined, fallbackMessage: undefined };
+}
+
+/**
+ * Find a fast model using the priority chain.
+ * Tries exact matches first, then fuzzy matches.
+ *
+ * @param modelRegistry The model registry to search
+ * @param savedModel Optional saved model string from settings (provider/modelId)
+ * @returns The best available fast model, or undefined if none found
+ */
+export async function findSmolModel(
+	modelRegistry: ModelRegistry,
+	savedModel?: string,
+): Promise<Model<Api> | undefined> {
+	const availableModels = modelRegistry.getAvailable();
+	if (availableModels.length === 0) return undefined;
+
+	// 1. Try saved model from settings
+	if (savedModel) {
+		const parsed = parseModelString(savedModel);
+		if (parsed) {
+			const match = availableModels.find(m => m.provider === parsed.provider && m.id === parsed.id);
+			if (match) return match;
+		}
+	}
+
+	// 2. Try priority chain
+	for (const pattern of MODEL_PRIO.fast) {
+		// Try exact match with provider prefix
+		const providerMatch = availableModels.find(m => `${m.provider}/${m.id}`.toLowerCase() === pattern);
+		if (providerMatch) return providerMatch;
+
+		// Try exact match first
+		const exactMatch = availableModels.find(m => m.id.toLowerCase() === pattern);
+		if (exactMatch) return exactMatch;
+
+		// Try fuzzy match (substring)
+		const fuzzyMatch = availableModels.find(m => m.id.toLowerCase().includes(pattern));
+		if (fuzzyMatch) return fuzzyMatch;
+	}
+
+	// 3. Fallback to first available (same as default)
+	return availableModels[0];
+}
+
+/**
+ * Find a oracle/comprehensive model using the priority chain.
+ * Prioritizes reasoning and codex models for thorough analysis.
+ *
+ * @param modelRegistry The model registry to search
+ * @param savedModel Optional saved model string from settings (provider/modelId)
+ * @returns The best available oracle model, or undefined if none found
+ */
+export async function findSlowModel(
+	modelRegistry: ModelRegistry,
+	savedModel?: string,
+): Promise<Model<Api> | undefined> {
+	const availableModels = modelRegistry.getAvailable();
+	if (availableModels.length === 0) return undefined;
+
+	// 1. Try saved model from settings
+	if (savedModel) {
+		const parsed = parseModelString(savedModel);
+		if (parsed) {
+			const match = availableModels.find(m => m.provider === parsed.provider && m.id === parsed.id);
+			if (match) return match;
+		}
+	}
+
+	// 2. Try priority chain
+	for (const pattern of MODEL_PRIO.oracle) {
+		// Try exact match first
+		const exactMatch = availableModels.find(m => m.id.toLowerCase() === pattern.toLowerCase());
+		if (exactMatch) return exactMatch;
+
+		// Try fuzzy match (substring)
+		const fuzzyMatch = availableModels.find(m => m.id.toLowerCase().includes(pattern.toLowerCase()));
+		if (fuzzyMatch) return fuzzyMatch;
+	}
+
+	// 3. Fallback to first available (same as default)
+	return availableModels[0];
+}