@prometheus-ai/agent 0.5.4 → 0.5.8

package/src/config/model-resolver.ts

@@ -1,27 +1,51 @@
 /**
- * Model resolution, scoping, and initial selection
+ * Model resolution, scoping, and initial selection.
+ *
+ * Layering:
+ * - `matchModel` is the single matching engine. Order: exact `provider/id`
+ *   reference (with variant-alias and OpenRouter routed/date fallbacks) →
+ *   exact canonical id → exact bare id → retired variant alias →
+ *   provider-scoped fuzzy → substring with alias-vs-dated pick.
+ * - `parseModelPatternWithContext`/`parseModelPattern` layer the selector
+ *   grammar on top: trailing `:level` thinking suffixes (`splitThinkingSuffix`)
+ *   and `@upstream` provider routing (`splitUpstreamRouting`).
+ * - Everything else (`resolveModelFromString`, `resolveModelOverride*`,
+ *   `resolveRoleSelection`, `resolveModelScope`, `resolveCliModel`,
+ *   `findSmolModel`/`findSlowModel`) adapts inputs — roles, settings patterns,
+ *   CLI flags, scope globs — onto that pipeline.
  */
 
 import { ThinkingLevel } from "@prometheus-ai/agent-core";
-import {
-	type Api,
-	clampThinkingLevelForModel,
-	DEFAULT_MODEL_PER_PROVIDER,
-	type Effort,
-	type KnownProvider,
-	type Model,
-	modelsAreEqual,
-} from "@prometheus-ai/ai";
+import type { Api, Effort, KnownProvider, Model, ModelSpec } from "@prometheus-ai/ai";
+import { buildModel } from "@prometheus-ai/catalog/build";
+import { modelMatchesHost } from "@prometheus-ai/catalog/hosts";
+import { buildModelProviderPriorityRank } from "@prometheus-ai/catalog/identity";
+import { stripThinkingVariantToken } from "@prometheus-ai/catalog/identity/family";
+import { clampThinkingLevelForModel } from "@prometheus-ai/catalog/model-thinking";
+import { modelsAreEqual } from "@prometheus-ai/catalog/models";
+import { DEFAULT_MODEL_PER_PROVIDER } from "@prometheus-ai/catalog/provider-models";
+import { resolveBareVariantAlias, resolveVariantAlias } from "@prometheus-ai/catalog/variant-collapse";
 import { fuzzyMatch } from "@prometheus-ai/tui";
 import { logger } from "@prometheus-ai/utils";
 import chalk from "chalk";
 import MODEL_PRIO from "../priority.json" with { type: "json" };
 import { parseThinkingLevel, resolveThinkingLevelForModel } from "../thinking";
-import { isAuthenticated, kNoAuth, MODEL_ROLE_IDS, type ModelRegistry, type ModelRole } from "./model-registry";
+import { isAuthenticated, kNoAuth, type ModelRegistry } from "./model-registry";
+import { MODEL_ROLE_IDS, type ModelRole } from "./model-roles";
 import type { Settings } from "./settings";
 
-/** Default model IDs for each known provider */
-export const defaultModelPerProvider: Record<KnownProvider, string> = DEFAULT_MODEL_PER_PROVIDER;
+/**
+ * Pick the first available model matching a known provider's default id
+ * (catalog table order), falling back to the first available model.
+ */
+function pickDefaultAvailableModel(availableModels: Model<Api>[]): Model<Api> | undefined {
+	for (const provider of Object.keys(DEFAULT_MODEL_PER_PROVIDER) as KnownProvider[]) {
+		const defaultId = DEFAULT_MODEL_PER_PROVIDER[provider];
+		const match = availableModels.find(m => m.provider === provider && m.id === defaultId);
+		if (match) return match;
+	}
+	return availableModels[0];
+}
 
 export interface ScopedModel {
 	model: Model<Api>;
@@ -29,6 +53,22 @@ export interface ScopedModel {
 	explicitThinkingLevel: boolean;
 }
 
+/**
+ * Split a trailing `:<level>` thinking selector off a model pattern.
+ *
+ * `level` is set only when the suffix parses as a valid thinking level, in
+ * which case `base` has the suffix stripped; otherwise `base` is the input.
+ * `minColonIndex` requires the colon to appear strictly after that index —
+ * role-alias callers pass `LEGACY_MODEL_ROLE_PREFIX.length` so the base is at
+ * least as long as the shortest role prefix.
+ */
+function splitThinkingSuffix(pattern: string, minColonIndex = -1): { base: string; level?: ThinkingLevel } {
+	const colonIdx = pattern.lastIndexOf(":");
+	if (colonIdx <= minColonIndex) return { base: pattern };
+	const level = parseThinkingLevel(pattern.slice(colonIdx + 1));
+	return level ? { base: pattern.slice(0, colonIdx), level } : { base: pattern };
+}
+
 /**
  * Parse a model string in "provider/modelId" format.
  * Returns undefined if the format is invalid.
@@ -41,15 +81,8 @@ export function parseModelString(
 	const id = modelStr.slice(slashIdx + 1);
 	const provider = modelStr.slice(0, slashIdx);
 	// Strip valid thinking level suffix (e.g., "claude-sonnet-4-6:high" -> id "claude-sonnet-4-6", thinkingLevel "high")
-	const colonIdx = id.lastIndexOf(":");
-	if (colonIdx !== -1) {
-		const suffix = id.slice(colonIdx + 1);
-		const thinkingLevel = parseThinkingLevel(suffix);
-		if (thinkingLevel) {
-			return { provider, id: id.slice(0, colonIdx), thinkingLevel };
-		}
-	}
-	return { provider, id };
+	const { base, level } = splitThinkingSuffix(id);
+	return level ? { provider, id: base, thinkingLevel: level } : { provider, id };
 }
 
 /**
@@ -117,6 +150,45 @@ function cloneModelWithRequestedId(model: Model<Api>, requestedId: string): Mode
 	};
 }
 
+const UPSTREAM_ROUTING_SLUG = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/i;
+
+/**
+ * Split a trailing `@<upstream>` provider-routing selector off a model pattern.
+ *
+ * `openrouter/z-ai/glm-4.7@cerebras` -> base `openrouter/z-ai/glm-4.7`, upstream
+ * `cerebras`. A `:thinking` suffix after the slug is kept on the base
+ * (`...@cerebras:high` -> base `...:high`). Returns undefined when there is no
+ * `@` or the suffix is not a bare provider slug, so model ids that legitimately
+ * contain `@` (`claude-opus-4-8@default`, `workers-ai/@cf/...`) are never split.
+ */
+function splitUpstreamRouting(pattern: string): { base: string; upstream: string } | undefined {
+	const at = pattern.lastIndexOf("@");
+	if (at <= 0) return undefined;
+	const rest = pattern.slice(at + 1);
+	const colon = rest.indexOf(":");
+	const upstream = colon === -1 ? rest : rest.slice(0, colon);
+	if (!UPSTREAM_ROUTING_SLUG.test(upstream)) return undefined;
+	const trailing = colon === -1 ? "" : rest.slice(colon);
+	return { base: pattern.slice(0, at) + trailing, upstream };
+}
+
+/** OpenRouter and Vercel AI Gateway are the aggregators that honor per-request upstream routing. */
+function supportsUpstreamRouting(model: Model<Api>): boolean {
+	return modelMatchesHost(model, "openrouter") || modelMatchesHost(model, "vercelAIGateway");
+}
+
+/** Pin a resolved aggregator model to a single upstream provider via its compat routing block. */
+function applyUpstreamRouting(model: Model<Api>, upstream: string): Model<Api> {
+	const aggregatorModel = model as Model<"openai-completions">;
+	const routing = { only: [upstream] };
+	return buildModel({
+		...model,
+		compat: modelMatchesHost(model, "vercelAIGateway")
+			? { ...aggregatorModel.compatConfig, vercelGatewayRouting: routing }
+			: { ...aggregatorModel.compatConfig, openRouterRouting: routing },
+	} as ModelSpec<Api>);
+}
+
 const kProviderModelIndex = Symbol("model-resolver.providerIndex");
 type ModelsWithProviderIndex = readonly Model<Api>[] & {
 	[kProviderModelIndex]?: Map<string, Model<Api> | null>;
@@ -159,6 +231,18 @@ export function resolveProviderModelReference(
 		return exact;
 	}
 
+	// Retired effort-tier variant ids resolve to their collapsed logical
+	// model: hand-table aliases first, then the `X-thinking` → `X` grammar
+	// for auto-derived pairs. Exact lookup above always wins while raw is live.
+	const variantAliasId =
+		resolveVariantAlias(normalizedProvider, normalizedModelId) ?? stripThinkingVariantToken(normalizedModelId);
+	if (variantAliasId) {
+		const aliased = index.get(`${normalizedProvider}\u0000${variantAliasId.toLowerCase()}`);
+		if (aliased) {
+			return aliased;
+		}
+	}
+
 	if (normalizedProvider !== "openrouter") {
 		return undefined;
 	}
@@ -179,7 +263,9 @@ export function resolveProviderModelReference(
 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. */
+	/** Provider precedence used for ambiguous unqualified model patterns. */
+	providerOrder?: readonly string[];
+	/** Providers to deprioritize when no recent usage or provider priority is available. */
 	deprioritizeProviders?: string[];
 }
 
@@ -194,6 +280,7 @@ type RestorableModelRegistry = Pick<ModelRegistry, "getAvailable" | "find" | "ge
 interface ModelPreferenceContext {
 	modelUsageRank: Map<string, number>;
 	providerUsageRank: Map<string, number>;
+	providerPriorityRank: Map<string, number>;
 	deprioritizedProviders: Set<string>;
 	modelOrder: Map<string, number>;
 }
@@ -215,14 +302,35 @@ function buildPreferenceContext(
 			providerUsageRank.set(parsed.provider, i);
 		}
 	}
-
-	const deprioritizedProviders = new Set(preferences?.deprioritizeProviders ?? ["openrouter"]);
+	const providerPriorityRank = buildModelProviderPriorityRank(preferences?.providerOrder);
+	const deprioritizedProviders = new Set(preferences?.deprioritizeProviders ?? []);
 	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 };
+	return { modelUsageRank, providerUsageRank, providerPriorityRank, deprioritizedProviders, modelOrder };
+}
+
+export function getModelMatchPreferences(
+	settings?: Partial<Pick<Settings, "get" | "getStorage">>,
+): ModelMatchPreferences {
+	return {
+		usageOrder: settings?.getStorage?.()?.getModelUsageOrder(),
+		providerOrder: settings?.get?.("modelProviderOrder"),
+	};
+}
+
+function mergeModelMatchPreferences(
+	settings: Settings | undefined,
+	preferences: ModelMatchPreferences | undefined,
+): ModelMatchPreferences {
+	const settingsPreferences = getModelMatchPreferences(settings);
+	return {
+		usageOrder: preferences?.usageOrder ?? settingsPreferences.usageOrder,
+		providerOrder: preferences?.providerOrder ?? settingsPreferences.providerOrder,
+		deprioritizeProviders: preferences?.deprioritizeProviders,
+	};
 }
 
 function pickPreferredModel(candidates: Model<Api>[], context: ModelPreferenceContext): Model<Api> {
@@ -236,6 +344,12 @@ function pickPreferredModel(candidates: Model<Api>[], context: ModelPreferenceCo
 			return (aUsage ?? Number.POSITIVE_INFINITY) - (bUsage ?? Number.POSITIVE_INFINITY);
 		}
 
+		const aProviderPriority = context.providerPriorityRank.get(a.provider.toLowerCase());
+		const bProviderPriority = context.providerPriorityRank.get(b.provider.toLowerCase());
+		if (aProviderPriority !== undefined || bProviderPriority !== undefined) {
+			return (aProviderPriority ?? Number.POSITIVE_INFINITY) - (bProviderPriority ?? Number.POSITIVE_INFINITY);
+		}
+
 		const aProviderUsage = context.providerUsageRank.get(a.provider);
 		const bProviderUsage = context.providerUsageRank.get(b.provider);
 		if (aProviderUsage !== undefined || bProviderUsage !== undefined) {
@@ -271,10 +385,7 @@ function isAlias(id: string): boolean {
  * Find an exact explicit provider/model match.
  * Bare model ids are handled separately so canonical ids can coalesce variants.
  */
-export function findExactModelReferenceMatch(
-	modelReference: string,
-	availableModels: Model<Api>[],
-): Model<Api> | undefined {
+function findExactModelReferenceMatch(modelReference: string, availableModels: Model<Api>[]): Model<Api> | undefined {
 	const trimmedReference = modelReference.trim();
 	if (!trimmedReference) {
 		return undefined;
@@ -310,10 +421,17 @@ function findExactCanonicalModelMatch(
 }
 
 /**
- * Try to match a pattern to a model from the available models list.
+ * The single model-matching engine. Tries, in order:
+ * 1. exact `provider/id` reference (variant-alias and OpenRouter routed/date
+ *    fallbacks included),
+ * 2. exact canonical id (coalesces provider variants),
+ * 3. exact bare id (preference-ranked),
+ * 4. retired effort-tier variant alias (collapsed catalog entries),
+ * 5. provider-scoped fuzzy match,
+ * 6. substring match with the alias-vs-dated pick.
  * Returns the matched model or undefined if no match found.
  */
-function tryMatchModel(
+function matchModel(
 	modelPattern: string,
 	availableModels: Model<Api>[],
 	context: ModelPreferenceContext,
@@ -339,6 +457,20 @@ function tryMatchModel(
 	if (exactMatches.length > 0) {
 		return pickPreferredModel(exactMatches, context);
 	}
+
+	// Retired effort-tier variant ids (bare, no provider prefix) resolve to
+	// their collapsed logical model; models from the providers whose table
+	// declared the alias win ties. Auto-derived `X-thinking` pairs resolve
+	// through the grammar fallback.
+	const bareAlias = resolveBareVariantAlias(modelPattern);
+	const bareAliasTargetId = bareAlias?.id ?? stripThinkingVariantToken(modelPattern);
+	if (bareAliasTargetId) {
+		const aliasMatches = availableModels.filter(m => m.id.toLowerCase() === bareAliasTargetId.toLowerCase());
+		if (aliasMatches.length > 0) {
+			const preferred = bareAlias ? aliasMatches.filter(m => bareAlias.providers.includes(m.provider)) : [];
+			return pickPreferredModel(preferred.length > 0 ? preferred : aliasMatches, context);
+		}
+	}
 	// Check for provider/modelId format — fuzzy match within provider only.
 	const slashIndex = modelPattern.indexOf("/");
 	if (slashIndex !== -1) {
@@ -411,6 +543,8 @@ export interface ParsedModelResult {
 	model: Model<Api> | undefined;
 	/** Thinking level if explicitly specified in pattern, undefined otherwise */
 	thinkingLevel?: ThinkingLevel;
+	/** Upstream provider slug from an `@upstream` routing selector, if present. */
+	upstream?: string;
 	warning: string | undefined;
 	explicitThinkingLevel: boolean;
 }
@@ -435,31 +569,21 @@ function parseModelPatternWithContext(
 	options?: { allowInvalidThinkingSelectorFallback?: boolean; modelRegistry?: CanonicalModelRegistry },
 ): ParsedModelResult {
 	// Try exact match first
-	const exactMatch = tryMatchModel(pattern, availableModels, context, options);
+	const exactMatch = matchModel(pattern, availableModels, context, options);
 	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);
-
-	const parsedThinkingLevel = parseThinkingLevel(suffix);
-	if (parsedThinkingLevel) {
-		// Valid thinking level - recurse on prefix and use this level
-		const result = parseModelPatternWithContext(prefix, availableModels, context, options);
+	// No match - try stripping a valid thinking suffix and recursing
+	const { base, level } = splitThinkingSuffix(pattern);
+	if (level) {
+		const result = parseModelPatternWithContext(base, 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 ? parsedThinkingLevel : undefined,
+				thinkingLevel: explicitThinkingLevel ? level : undefined,
 				warning: result.warning,
 				explicitThinkingLevel,
 			};
@@ -467,6 +591,14 @@ function parseModelPatternWithContext(
 		return result;
 	}
 
+	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);
+
 	const allowFallback = options?.allowInvalidThinkingSelectorFallback ?? true;
 	if (!allowFallback) {
 		return { model: undefined, thinkingLevel: undefined, warning: undefined, explicitThinkingLevel: false };
@@ -492,19 +624,35 @@ export function parseModelPattern(
 	options?: { allowInvalidThinkingSelectorFallback?: boolean; modelRegistry?: CanonicalModelRegistry },
 ): ParsedModelResult {
 	const context = buildPreferenceContext(availableModels, preferences);
-	return parseModelPatternWithContext(pattern, availableModels, context, options);
+	const direct = parseModelPatternWithContext(pattern, availableModels, context, options);
+	if (direct.model) return direct;
+
+	// No direct match: a trailing `@upstream` may be a provider-routing selector.
+	// Only honor it when the base resolves to an aggregator model (OpenRouter /
+	// Vercel Gateway); otherwise `@` stays part of the id and `direct` stands.
+	const routing = splitUpstreamRouting(pattern);
+	if (routing) {
+		const routed = parseModelPatternWithContext(routing.base, availableModels, context, options);
+		if (routed.model && supportsUpstreamRouting(routed.model)) {
+			return { ...routed, model: applyUpstreamRouting(routed.model, routing.upstream), upstream: routing.upstream };
+		}
+	}
+	return direct;
 }
 
-const PREFIX_MODEL_ROLE = "prometheus/";
+const LEGACY_MODEL_ROLE_PREFIX = "pi/";
+const PROMETHEUS_MODEL_ROLE_PREFIX = "prometheus/";
+const MODEL_ROLE_PREFIXES = [LEGACY_MODEL_ROLE_PREFIX, PROMETHEUS_MODEL_ROLE_PREFIX] as const;
 const DEFAULT_MODEL_ROLE = "default";
 
 function getModelRoleAlias(value: string): ModelRole | undefined {
 	const normalized = value.trim();
-	if (!normalized.startsWith(PREFIX_MODEL_ROLE)) return undefined;
-
-	const candidate = normalized.slice(PREFIX_MODEL_ROLE.length);
-	for (const role of MODEL_ROLE_IDS) {
-		if (candidate === role) return role;
+	for (const prefix of MODEL_ROLE_PREFIXES) {
+		if (!normalized.startsWith(prefix)) continue;
+		const candidate = normalized.slice(prefix.length);
+		for (const role of MODEL_ROLE_IDS) {
+			if (candidate === role) return role;
+		}
 	}
 	return undefined;
 }
@@ -518,26 +666,84 @@ function normalizeModelPatternList(value: string | string[] | undefined): string
 function isSessionInheritedAgentPattern(value: string): boolean {
 	return (
 		value === DEFAULT_MODEL_ROLE ||
-		value === `${PREFIX_MODEL_ROLE}${DEFAULT_MODEL_ROLE}` ||
-		value === `${PREFIX_MODEL_ROLE}task`
+		MODEL_ROLE_PREFIXES.some(prefix => value === `${prefix}${DEFAULT_MODEL_ROLE}` || value === `${prefix}task`)
 	);
 }
 
-function resolveConfiguredRolePattern(value: string, settings?: Settings): string[] | undefined {
+function shouldInheritDefaultBeforePriority(role: ModelRole): boolean {
+	return role === "smol" || role === "slow" || role === "designer";
+}
+
+function resolveDefaultInheritedPatterns(
+	role: ModelRole,
+	configuredDefault: string | undefined,
+	roleDefaults: string[],
+	settings: Settings | undefined,
+	visited: Set<ModelRole>,
+): string[] {
+	if (!shouldInheritDefaultBeforePriority(role) || !configuredDefault) return [];
+
+	const resolved: string[] = [];
+	for (const pattern of normalizeModelPatternList(configuredDefault)) {
+		const { base: aliasCandidate, level: thinkingLevel } = splitThinkingSuffix(
+			pattern,
+			LEGACY_MODEL_ROLE_PREFIX.length,
+		);
+		const aliasRole = getModelRoleAlias(aliasCandidate);
+		if (aliasRole === role) {
+			// Self-alias (e.g. modelRoles.default = "pi/smol" or "prometheus/smol")
+			// would loop back to the same unset role; collapse straight to the
+			// built-in priority chain.
+			resolved.push(
+				...(thinkingLevel
+					? roleDefaults.map(defaultPattern => `${defaultPattern}:${thinkingLevel}`)
+					: roleDefaults),
+			);
+			continue;
+		}
+		if (aliasRole && !visited.has(aliasRole)) {
+			// Cross-role alias (e.g. modelRoles.default = "pi/slow" or
+			// "prometheus/slow"): resolve the target role's patterns now so
+			// downstream one-layer expanders see concrete model patterns instead of
+			// another role alias.
+			const recursed = resolveConfiguredRolePattern(pattern, settings, new Set(visited));
+			if (recursed && recursed.length > 0) {
+				resolved.push(...recursed);
+				continue;
+			}
+		}
+		resolved.push(pattern);
+	}
+	return resolved;
+}
+
+function resolveConfiguredRolePattern(
+	value: string,
+	settings?: Settings,
+	visited: Set<ModelRole> = new Set(),
+): string[] | undefined {
 	const normalized = value.trim();
 	if (!normalized) return undefined;
 
-	const lastColonIndex = normalized.lastIndexOf(":");
-	const thinkingLevel =
-		lastColonIndex > PREFIX_MODEL_ROLE.length ? parseThinkingLevel(normalized.slice(lastColonIndex + 1)) : undefined;
-	const aliasCandidate = thinkingLevel ? normalized.slice(0, lastColonIndex) : normalized;
+	const { base: aliasCandidate, level: thinkingLevel } = splitThinkingSuffix(
+		normalized,
+		LEGACY_MODEL_ROLE_PREFIX.length,
+	);
 	const role = getModelRoleAlias(aliasCandidate);
 	if (!role) return [normalized];
+	if (visited.has(role)) return undefined;
+	visited.add(role);
 
 	const configured = settings?.getModelRole(role)?.trim();
+	const configuredDefault = settings?.getModelRole(DEFAULT_MODEL_ROLE)?.trim();
 	const roleDefaults = normalizeModelPatternList(MODEL_PRIO[role as keyof typeof MODEL_PRIO]);
-	const resolved = configured ? normalizeModelPatternList(configured) : roleDefaults;
-	if (!resolved || resolved.length === 0) {
+	const resolved = configured
+		? normalizeModelPatternList(configured)
+		: resolveDefaultInheritedPatterns(role, configuredDefault, roleDefaults, settings, visited);
+	if (resolved.length === 0) {
+		resolved.push(...roleDefaults);
+	}
+	if (resolved.length === 0) {
 		return undefined;
 	}
 
@@ -545,7 +751,8 @@ function resolveConfiguredRolePattern(value: string, settings?: Settings): strin
 }
 
 /**
- * Expand a role alias like "prometheus/smol" to the configured model string.
+ * Expand a role alias like "pi/smol" or "prometheus/smol" to the configured
+ * model string.
  */
 export function expandRoleAlias(value: string, settings?: Settings): string {
 	const normalized = value.trim();
@@ -584,7 +791,7 @@ export function resolveAgentModelPatterns(options: AgentModelPatternResolutionOp
 	const agentInheritsSessionModel = singleAgentPattern ? isSessionInheritedAgentPattern(singleAgentPattern) : false;
 	if (configuredAgentPatterns.length > 0) {
 		if (!agentInheritsSessionModel) return configuredAgentPatterns;
-		if (singleAgentPattern === `${PREFIX_MODEL_ROLE}task`) return configuredAgentPatterns;
+		if (singleAgentPattern === "pi/task") return configuredAgentPatterns;
 	}
 
 	const fallback =
@@ -616,14 +823,15 @@ export function resolveModelRoleValue(
 		return { model: undefined, thinkingLevel: undefined, explicitThinkingLevel: false, warning: undefined };
 	}
 
-	const effectivePatterns = resolveConfiguredRolePattern(normalized, options?.settings);
+	const effectivePatterns = resolveConfiguredModelPatterns(normalized, options?.settings);
 	if (!effectivePatterns || effectivePatterns.length === 0) {
 		return { model: undefined, thinkingLevel: undefined, explicitThinkingLevel: false, warning: undefined };
 	}
 
 	let warning: string | undefined;
+	const matchPreferences = mergeModelMatchPreferences(options?.settings, options?.matchPreferences);
 	for (const effectivePattern of effectivePatterns) {
-		const resolved = parseModelPattern(effectivePattern, availableModels, options?.matchPreferences, {
+		const resolved = parseModelPattern(effectivePattern, availableModels, matchPreferences, {
 			modelRegistry: options?.modelRegistry,
 		});
 		if (resolved.model) {
@@ -656,9 +864,7 @@ export function extractExplicitThinkingSelector(
 	let current = normalized;
 	while (!visited.has(current)) {
 		visited.add(current);
-		const lastColonIndex = current.lastIndexOf(":");
-		const thinkingSelector =
-			lastColonIndex > PREFIX_MODEL_ROLE.length ? parseThinkingLevel(current.slice(lastColonIndex + 1)) : undefined;
+		const thinkingSelector = splitThinkingSuffix(current, LEGACY_MODEL_ROLE_PREFIX.length).level;
 		if (thinkingSelector) {
 			return thinkingSelector;
 		}
@@ -724,7 +930,7 @@ export function resolveModelOverride(
 ): { model?: Model<Api>; thinkingLevel?: ThinkingLevel; explicitThinkingLevel: boolean } {
 	if (modelPatterns.length === 0) return { explicitThinkingLevel: false };
 	const availableModels = modelRegistry.getAvailable();
-	const matchPreferences = { usageOrder: settings?.getStorage()?.getModelUsageOrder() };
+	const matchPreferences = getModelMatchPreferences(settings);
 	for (const pattern of modelPatterns) {
 		const { model, thinkingLevel, explicitThinkingLevel } = resolveModelRoleValue(pattern, availableModels, {
 			settings,
@@ -804,7 +1010,7 @@ export function resolveRoleSelection(
 	availableModels: Model<Api>[],
 	modelRegistry?: CanonicalModelRegistry,
 ): { model: Model<Api>; thinkingLevel?: ThinkingLevel } | undefined {
-	const matchPreferences = { usageOrder: settings.getStorage()?.getModelUsageOrder() };
+	const matchPreferences = getModelMatchPreferences(settings);
 	for (const role of roles) {
 		const resolved = resolveModelRoleValue(settings.getModelRole(role), availableModels, {
 			settings,
@@ -823,20 +1029,8 @@ function resolveExactCanonicalScopePattern(
 	modelRegistry: Pick<ModelRegistry, "getCanonicalVariants">,
 	availableModels: Model<Api>[],
 ): { models: Model<Api>[]; thinkingLevel?: ThinkingLevel; explicitThinkingLevel: boolean } | undefined {
-	const lastColonIndex = pattern.lastIndexOf(":");
-	let canonicalId = pattern;
-	let thinkingLevel: ThinkingLevel | undefined;
-	let explicitThinkingLevel = false;
-
-	if (lastColonIndex !== -1) {
-		const suffix = pattern.substring(lastColonIndex + 1);
-		const parsedThinkingLevel = parseThinkingLevel(suffix);
-		if (parsedThinkingLevel) {
-			canonicalId = pattern.substring(0, lastColonIndex);
-			thinkingLevel = parsedThinkingLevel;
-			explicitThinkingLevel = true;
-		}
-	}
+	const { base: canonicalId, level: thinkingLevel } = splitThinkingSuffix(pattern);
+	const explicitThinkingLevel = thinkingLevel !== undefined;
 
 	const variants = modelRegistry
 		.getCanonicalVariants(canonicalId, { availableOnly: true, candidates: availableModels })
@@ -867,25 +1061,23 @@ export async function resolveModelScope(
 	const availableModels = modelRegistry.getAvailable();
 	const context = buildPreferenceContext(availableModels, preferences);
 	const scopedModels: ScopedModel[] = [];
+	const addScopedModel = (model: Model<Api>, thinkingLevel: ThinkingLevel | undefined, explicit: boolean) => {
+		if (scopedModels.some(sm => modelsAreEqual(sm.model, model))) return;
+		scopedModels.push({
+			model,
+			thinkingLevel: explicit
+				? (resolveThinkingLevelForModel(model, thinkingLevel) ?? thinkingLevel)
+				: thinkingLevel,
+			explicitThinkingLevel: explicit,
+		});
+	};
 
 	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);
-				const parsedThinkingLevel = parseThinkingLevel(suffix);
-				if (parsedThinkingLevel) {
-					thinkingLevel = parsedThinkingLevel;
-					explicitThinkingLevel = true;
-					globPattern = pattern.substring(0, colonIdx);
-				}
-			}
+			const { base: globPattern, level: thinkingLevel } = splitThinkingSuffix(pattern);
+			const explicitThinkingLevel = thinkingLevel !== undefined;
 
 			// Match against "provider/modelId" format OR just model ID
 			// This allows "*sonnet*" to match without requiring "anthropic/*sonnet*"
@@ -901,15 +1093,7 @@ export async function resolveModelScope(
 			}
 
 			for (const model of matchingModels) {
-				if (!scopedModels.find(sm => modelsAreEqual(sm.model, model))) {
-					scopedModels.push({
-						model,
-						thinkingLevel: explicitThinkingLevel
-							? (resolveThinkingLevelForModel(model, thinkingLevel) ?? thinkingLevel)
-							: thinkingLevel,
-						explicitThinkingLevel,
-					});
-				}
+				addScopedModel(model, thinkingLevel, explicitThinkingLevel);
 			}
 			continue;
 		}
@@ -917,16 +1101,7 @@ export async function resolveModelScope(
 		const exactCanonical = resolveExactCanonicalScopePattern(pattern, modelRegistry, availableModels);
 		if (exactCanonical) {
 			for (const model of exactCanonical.models) {
-				if (!scopedModels.find(sm => modelsAreEqual(sm.model, model))) {
-					scopedModels.push({
-						model,
-						thinkingLevel: exactCanonical.explicitThinkingLevel
-							? (resolveThinkingLevelForModel(model, exactCanonical.thinkingLevel) ??
-								exactCanonical.thinkingLevel)
-							: exactCanonical.thinkingLevel,
-						explicitThinkingLevel: exactCanonical.explicitThinkingLevel,
-					});
-				}
+				addScopedModel(model, exactCanonical.thinkingLevel, exactCanonical.explicitThinkingLevel);
 			}
 			continue;
 		}
@@ -947,16 +1122,7 @@ export async function resolveModelScope(
 			continue;
 		}
 
-		// Avoid duplicates
-		if (!scopedModels.find(sm => modelsAreEqual(sm.model, model))) {
-			scopedModels.push({
-				model,
-				thinkingLevel: explicitThinkingLevel
-					? (resolveThinkingLevelForModel(model, thinkingLevel) ?? thinkingLevel)
-					: thinkingLevel,
-				explicitThinkingLevel,
-			});
-		}
+		addScopedModel(model, thinkingLevel, explicitThinkingLevel);
 	}
 
 	return scopedModels;
@@ -992,6 +1158,66 @@ export async function resolveAllowedModels(
 	return available.filter(model => allowed.has(`${model.provider}/${model.id}`));
 }
 
+/**
+ * Synchronous subset of {@link resolveAllowedModels} for contexts where async is unavailable
+ * (e.g. `getAvailableModels()` which is called from the ACP model-list advertisement, RPC
+ * `get_available_models`, and the `/model` slash command). Uses the same effective
+ * `enabledModels` scope semantics as startup resolution:
+ *
+ * - Glob selectors match `provider/modelId` and bare model id
+ * - Exact canonical ids expand to all available concrete variants
+ * - Exact `provider/modelId`, bare ids, provider-scoped fuzzy, and substring selectors
+ *   resolve through the shared model-pattern matcher
+ * - Optional `:thinkingLevel` suffixes are stripped only when valid
+ *
+ * When no pattern resolves to any model (misconfiguration / typo) an empty list is returned,
+ * consistent with the empty-list contract of {@link resolveAllowedModels}. Callers that render
+ * a UI picker should treat an empty list as "hide the picker entry", matching how the SDK
+ * surfaces the same misconfiguration during session initialization.
+ */
+export function filterAvailableModelsByEnabledPatterns(
+	available: Model<Api>[],
+	patterns: readonly string[],
+	registry: Pick<ModelRegistry, "getCanonicalVariants">,
+): Model<Api>[] {
+	if (patterns.length === 0) return available;
+
+	const context = buildPreferenceContext(available, undefined);
+	const allowed = new Set<string>();
+	const addAllowed = (model: Model<Api>) => {
+		allowed.add(`${model.provider}/${model.id}`);
+	};
+
+	for (const pattern of patterns) {
+		if (pattern.includes("*") || pattern.includes("?") || pattern.includes("[")) {
+			const { base: globPattern } = splitThinkingSuffix(pattern);
+			const glob = new Bun.Glob(globPattern.toLowerCase());
+			for (const model of available) {
+				const fullId = `${model.provider}/${model.id}`.toLowerCase();
+				if (glob.match(fullId) || glob.match(model.id.toLowerCase())) {
+					addAllowed(model);
+				}
+			}
+			continue;
+		}
+
+		const exactCanonical = resolveExactCanonicalScopePattern(pattern, registry, available);
+		if (exactCanonical) {
+			for (const model of exactCanonical.models) {
+				addAllowed(model);
+			}
+			continue;
+		}
+
+		const { model } = parseModelPatternWithContext(pattern, available, context, { modelRegistry: registry });
+		if (model) {
+			addAllowed(model);
+		}
+	}
+
+	return allowed.size === 0 ? [] : available.filter(model => allowed.has(`${model.provider}/${model.id}`));
+}
+
 export interface ResolveCliModelResult {
 	model: Model<Api> | undefined;
 	selector?: string;
@@ -1036,7 +1262,7 @@ export function resolveCliModel(options: {
 			model: undefined,
 			selector: undefined,
 			warning: undefined,
-			error: `Unknown provider "${cliProvider}". Use --list-models to see available providers/models.`,
+			error: `Unknown provider "${cliProvider}". Run "prometheus models" to see available providers/models.`,
 		};
 	}
 
@@ -1047,14 +1273,11 @@ export function resolveCliModel(options: {
 		// provider+id match over flat id match. Without this, a model with id
 		// "zai/glm-5" on provider "vercel-ai-gateway" wins over provider "zai"
 		// with id "glm-5", because Array.find returns the first catalog hit.
-		const slashIdx = lower.indexOf("/");
-		let exact: (typeof availableModels)[number] | undefined;
-		if (slashIdx !== -1) {
-			const prefix = lower.substring(0, slashIdx);
-			const suffix = trimmedModel.substring(slashIdx + 1);
-			exact = resolveProviderModelReference(prefix, suffix, availableModels);
-		}
+		let exact = findExactModelReferenceMatch(trimmedModel, availableModels);
 		if (!exact && !trimmedModel.includes(":")) {
+			// CLI flags address the full catalog, so unlike the engine's canonical
+			// step this lookup is unrestricted; the `:`-guard defers suffixed
+			// selectors (thinking levels, ollama-style ids) to the grammar below.
 			const canonicalMatch = modelRegistry.resolveCanonicalModel?.(trimmedModel, { availableOnly: false });
 			if (canonicalMatch) {
 				return {
@@ -1067,6 +1290,8 @@ export function resolveCliModel(options: {
 			}
 		}
 		if (!exact) {
+			// Flat exact id (or full selector) by catalog order: CLI resolution
+			// stays deterministic across runs regardless of usage-based ranking.
 			exact = availableModels.find(
 				model => model.id.toLowerCase() === lower || `${model.provider}/${model.id}`.toLowerCase() === lower,
 			);
@@ -1115,7 +1340,7 @@ export function resolveCliModel(options: {
 	}
 
 	const candidates = provider ? availableModels.filter(model => model.provider === provider) : availableModels;
-	const { model, thinkingLevel, warning } = parseModelPattern(pattern, candidates, preferences, {
+	const { model, thinkingLevel, warning, upstream } = parseModelPattern(pattern, candidates, preferences, {
 		allowInvalidThinkingSelectorFallback: false,
 		modelRegistry,
 	});
@@ -1127,17 +1352,13 @@ export function resolveCliModel(options: {
 			selector: undefined,
 			thinkingLevel: undefined,
 			warning,
-			error: `Model "${display}" not found. Use --list-models to see available models.`,
+			error: `Model "${display}" not found. Run "prometheus models" to see available models.`,
 		};
 	}
 
 	let selector = provider ? formatModelString(model) : undefined;
 	if (!provider) {
-		const lastColonIndex = pattern.lastIndexOf(":");
-		const canonicalCandidate =
-			lastColonIndex !== -1 && parseThinkingLevel(pattern.substring(lastColonIndex + 1))
-				? pattern.substring(0, lastColonIndex)
-				: pattern;
+		const canonicalCandidate = splitThinkingSuffix(pattern).base;
 		if (!canonicalCandidate.includes("/")) {
 			const canonicalResolved = modelRegistry.resolveCanonicalModel?.(canonicalCandidate, { availableOnly: false });
 			if (canonicalResolved && canonicalResolved.provider === model.provider && canonicalResolved.id === model.id) {
@@ -1145,6 +1366,9 @@ export function resolveCliModel(options: {
 			}
 		}
 	}
+	if (selector !== undefined && upstream) {
+		selector = `${selector}@${upstream}`;
+	}
 
 	return {
 		model,
@@ -1233,18 +1457,9 @@ export async function findInitialModel(options: {
 	// 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: undefined, fallbackMessage: undefined };
-			}
-		}
-
-		// If no default found, use first available
-		return { model: availableModels[0], thinkingLevel: undefined, fallbackMessage: undefined };
+	const fallback = pickDefaultAvailableModel(availableModels);
+	if (fallback) {
+		return { model: fallback, thinkingLevel: undefined, fallbackMessage: undefined };
 	}
 
 	// 5. No model found
@@ -1294,23 +1509,8 @@ export async function restoreModelFromSession(
 	// 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];
-		}
-
+	const fallbackModel = pickDefaultAvailableModel(availableModels);
+	if (fallbackModel) {
 		if (shouldPrintMessages) {
 			console.log(chalk.dim(`Falling back to: ${fallbackModel.provider}/${fallbackModel.id}`));
 		}