@gajae-code/coding-agent 0.17.1 → 0.17.4

package/src/config/model-profile-activation.ts

@@ -1,5 +1,5 @@
 import { ThinkingLevel } from "@gajae-code/agent-core";
-import type { Api, Model } from "@gajae-code/ai/core";
+import { type Api, isKnownProvider, type Model } from "@gajae-code/ai/core";
 import { logger } from "@gajae-code/utils";
 import type { AgentSession, DefaultFallbackRuntimeState } from "../session/agent-session";
 import { clampExplicitThinkingLevelForModel, formatClampedModelSelector } from "../thinking";
@@ -10,6 +10,7 @@ import {
 	formatModelProfileDisplayLabel,
 	type ModelProfileDefinition,
 	PROXY_ROUTABLE_PROVIDER_IDS,
+	type ResolvedProfileBinding,
 	resolveProfileBindings,
 } from "./model-profiles";
 
@@ -21,11 +22,13 @@ import {
 	isAuthenticated,
 	kNoAuth,
 	type ModelRegistry,
+	registrySelectorResolvesToModel,
 } from "./model-registry";
 import {
 	formatModelSelectorValue,
 	formatModelString,
 	parseModelString,
+	resolveConfiguredModelPatterns,
 	resolveModelChainWithAuth,
 	resolveModelRoleValue,
 	splitSelectorThinkingSuffix,
@@ -69,7 +72,8 @@ type ModelProfileActivationSession = Pick<
 		| "resolveModelByLookupAlias"
 		| "authStorage"
 		| "isCredentiallessProvider"
-	>;
+	> &
+		Partial<Pick<ModelRegistry, "getAvailableForProfileActivation">>;
 	getConfiguredModelChainState?: (role: string) => ConfiguredModelChainState | undefined;
 };
 
@@ -105,6 +109,7 @@ export interface PrepareModelProfileActivationOptions {
 				| "getSessionCanonicalVariant"
 				| "restoreSessionCanonicalVariant"
 				| "getConfiguredProviderIds"
+				| "isKnownProvider"
 			>
 		> & {
 			getError?: ModelRegistry["getError"];
@@ -248,7 +253,12 @@ function concretizeMaterializedAssignmentValues(
 	const sessionId = (options.session as { sessionId?: string }).sessionId;
 	const credentialSessionId = options.session.credentialSessionId ?? sessionId;
 	if (!modelRegistry || !sessionId) return assignments;
-	const availableModels = modelRegistry.getAvailable();
+	// Materialized assignments are persisted into `modelRoles` and
+	// `task.agentModelOverrides` and later consumed by profile execution, so they
+	// must resolve against the descriptor-backed profile-activation catalog, not
+	// the broadened general one: otherwise a bare assignment can persist a
+	// bundled model that fresh live profile evidence excludes.
+	const availableModels = modelRegistry.getAvailableForProfileActivation?.() ?? modelRegistry.getAvailable();
 	const authenticatedModels = availableModels.filter(model => {
 		const isCredentiallessProvider = modelRegistry.isCredentiallessProvider?.bind(modelRegistry);
 		const hasUsableAuth = modelRegistry.authStorage?.hasUsableAuth?.bind(modelRegistry.authStorage);
@@ -449,7 +459,7 @@ export function materializeActiveModelProfileAssignments(options: MaterializeMod
 }
 
 export class ModelProfileCredentialError extends Error {
-	readonly code = "authentication_failed";
+	readonly code: string = "authentication_failed";
 	readonly profileLabel: string;
 	readonly providers: readonly string[];
 	readonly role: string | undefined;
@@ -466,6 +476,28 @@ export class ModelProfileCredentialError extends Error {
 export function formatModelProfileCredentialError(profileLabel: string, providers: readonly string[]): string {
 	return `Model profile "${profileLabel}" requires credentials for: ${providers.join(", ")}. Run /login and configure the missing provider(s), then retry.`;
 }
+export function formatModelProfileUnknownProviderError(profileLabel: string, providers: readonly string[]): string {
+	return `Model profile "${profileLabel}" requires provider(s) this build does not know: ${providers.join(", ")}. The profile likely targets a newer or custom build; declare the provider(s) in models.yml or use a build that ships them.`;
+}
+
+/**
+ * A required profile provider that this build cannot know: it is neither a
+ * built-in provider id nor declared in models.yml. That is a build/config
+ * mismatch (for example a profile authored on a newer or custom build), not a
+ * credential gap, so the diagnosis must not send the user to /login.
+ *
+ * Extends {@link ModelProfileCredentialError} so existing startup recovery
+ * (interactive toast-and-continue) keeps working with the sharper message.
+ */
+export class ModelProfileUnknownProviderError extends ModelProfileCredentialError {
+	readonly code = "unknown_provider";
+
+	constructor(profileLabel: string, providers: readonly string[], role?: string) {
+		super(profileLabel, providers, role);
+		this.name = "ModelProfileUnknownProviderError";
+		this.message = formatModelProfileUnknownProviderError(profileLabel, providers);
+	}
+}
 
 /**
  * Rewrite a selector only within the selector provider's own alternative group.
@@ -534,6 +566,14 @@ function rewriteBindingsProviders(
 		),
 	};
 }
+export function isModelProfileProxyConfigured(
+	provider: string,
+	configuredProviders: readonly string[] | undefined,
+	credentialless: boolean,
+): boolean {
+	return configuredProviders?.includes(provider) === true || (provider === "opencodex" && credentialless);
+}
+
 /**
  * Resolve the explicitly configured OpenAI-compatible proxy provider id for a
  * preset. Returns undefined when unset or empty. Passwords/labels are never
@@ -608,6 +648,245 @@ export function requiresQualifiedModelProfileRoleResolution(profile: Pick<ModelP
 	return profile.source === "user" || profile.source === "registry";
 }
 
+/** Resolve a removed saved-session default through the durable profile without mutating persistent state. */
+export async function resolveMissingSessionModelRecovery(options: {
+	modelRegistry: PrepareModelProfileActivationOptions["modelRegistry"];
+	settings: Pick<Settings, "get" | "getModelRole">;
+	defaultEntries: readonly string[];
+	skips: Array<{ selector: string; reason: string }>;
+	savedDefault: string | undefined;
+	credentialSessionId: string;
+	aliasIntent?: "preset-equivalent";
+}): Promise<
+	| {
+			profileName: string;
+			entries: string[];
+			model?: Model<Api>;
+			thinkingLevel?: ThinkingLevel;
+			explicitThinkingLevel: boolean;
+			activeIndex: number;
+			skips: Array<{ selector: string; reason: string }>;
+	  }
+	| undefined
+> {
+	const allSelectorsUnknown =
+		options.skips.length === options.defaultEntries.length &&
+		options.skips.every(skip => skip.reason === "unknown_model");
+	if (!allSelectorsUnknown) return undefined;
+	const fullCatalog = options.modelRegistry.getAll();
+	const savedSelectorsMissingFromCatalog = resolveConfiguredModelPatterns(
+		options.defaultEntries,
+		options.settings,
+	).every(selector => {
+		if (
+			resolveModelRoleValue(selector, fullCatalog, {
+				settings: options.settings,
+				modelRegistry: options.modelRegistry,
+				credentialSessionId: options.credentialSessionId,
+				...(options.aliasIntent ? { aliasIntent: options.aliasIntent } : {}),
+			}).model
+		)
+			return false;
+		return !registrySelectorResolvesToModel(selector, fullCatalog);
+	});
+	const savedConcreteDefault = options.savedDefault ? parseModelString(options.savedDefault) : undefined;
+	const savedConcreteDefaultMissingFromCatalog =
+		savedConcreteDefault === undefined ||
+		!fullCatalog.some(
+			model =>
+				model.provider.toLowerCase() === savedConcreteDefault.provider.toLowerCase() &&
+				model.id.toLowerCase() === savedConcreteDefault.id.toLowerCase(),
+		);
+	const durableProfile = options.settings.get("modelProfile.default");
+	if (!savedSelectorsMissingFromCatalog || !savedConcreteDefaultMissingFromCatalog || !durableProfile)
+		return undefined;
+	return resolveModelProfileDefaultChain({
+		modelRegistry: options.modelRegistry,
+		settings: options.settings,
+		profileName: durableProfile,
+		credentialSessionId: options.credentialSessionId,
+	});
+}
+
+/** Resolve a durable profile's effective default chain without mutating session or settings state. */
+export async function resolveModelProfileDefaultChain(options: {
+	modelRegistry: PrepareModelProfileActivationOptions["modelRegistry"];
+	settings: Pick<Settings, "get">;
+	profileName: string;
+	credentialSessionId: string;
+}): Promise<{
+	profileName: string;
+	entries: string[];
+	model?: Model<Api>;
+	thinkingLevel?: ThinkingLevel;
+	explicitThinkingLevel: boolean;
+	activeIndex: number;
+	skips: Array<{ selector: string; reason: string }>;
+}> {
+	const profiles = options.modelRegistry.getModelProfiles();
+	const profileName = validateModelProfileName(options.profileName, profiles, options.modelRegistry.getError?.());
+	const profile = profiles.get(profileName) ?? options.modelRegistry.getModelProfile(profileName)!;
+	const profileLabel = formatModelProfileDisplayLabel(profile);
+	const requiredProviders = aggregateModelProfileRequiredProviders(profile.requiredProviders, profile);
+	const alternativeGroups = profile.alternativeProviderGroups ?? [];
+	const alternativeSet = new Set(alternativeGroups.flat());
+	const requiredProviderSet = new Set(requiredProviders);
+	const authenticatedProviders = new Set<string>();
+	const missingProviders: string[] = [];
+	const configuredProviderIds = options.modelRegistry.getConfiguredProviderIds?.();
+	if (configuredProviderIds !== undefined || options.modelRegistry.isKnownProvider !== undefined) {
+		const isProviderKnown = (provider: string): boolean =>
+			(options.modelRegistry.isKnownProvider?.(provider) ?? false) ||
+			isKnownProvider(provider) ||
+			configuredProviderIds?.includes(provider) === true;
+		const unknownProviderIds = new Set<string>();
+		for (const provider of requiredProviders) {
+			if (!alternativeSet.has(provider) && !isProviderKnown(provider)) unknownProviderIds.add(provider);
+		}
+		for (const group of alternativeGroups) {
+			if (group.some(isProviderKnown)) continue;
+			for (const provider of group) {
+				if (!isProviderKnown(provider)) unknownProviderIds.add(provider);
+			}
+		}
+		const unknownProviders = [...unknownProviderIds].sort();
+		if (unknownProviders.length > 0) throw new ModelProfileUnknownProviderError(profileLabel, unknownProviders);
+	}
+	for (const provider of new Set([
+		...requiredProviders,
+		...alternativeSet,
+		...deriveModelProfileMappedProviders(profile),
+	])) {
+		let apiKey: string | undefined;
+		try {
+			apiKey = await options.modelRegistry.getApiKeyForProvider(provider, options.credentialSessionId);
+		} catch (error) {
+			if (requiredProviderSet.has(provider) && !alternativeSet.has(provider)) throw error;
+			continue;
+		}
+		if (apiKey === kNoAuth || isAuthenticated(apiKey)) authenticatedProviders.add(provider);
+		else if (requiredProviderSet.has(provider)) missingProviders.push(provider);
+	}
+	const proxyProvider = profile.source !== "user" ? resolveProxyProviderId(options.settings) : undefined;
+	const proxyMode = profile.source !== "user" ? resolveProxyMode(options.settings) : "fallback";
+	const proxyRoutableProviders =
+		profile.source === "user"
+			? new Set<string>()
+			: profile.source === "registry"
+				? new Set([
+						...PROXY_ROUTABLE_PROVIDER_IDS,
+						...profile.requiredProviders,
+						...deriveModelProfileMappedProviders(profile),
+					])
+				: PROXY_ROUTABLE_PROVIDER_IDS;
+	if (proxyMode === "always" && proxyProvider === undefined)
+		throw new Error('modelProfile.proxyMode "always" requires modelProfile.proxyProvider');
+	const proxyApiKey =
+		proxyProvider === undefined
+			? undefined
+			: await options.modelRegistry.getApiKeyForProvider(proxyProvider, options.credentialSessionId);
+	if (
+		proxyProvider !== undefined &&
+		!isModelProfileProxyConfigured(proxyProvider, configuredProviderIds, proxyApiKey === kNoAuth)
+	) {
+		throw new Error(
+			`modelProfile.proxyProvider "${proxyProvider}" is not configured. Configure it with \`gjc setup provider\` before activating a preset.`,
+		);
+	}
+	const proxyAuthenticated = proxyApiKey !== undefined && (proxyApiKey === kNoAuth || isAuthenticated(proxyApiKey));
+	if (proxyMode === "always" && !proxyAuthenticated)
+		throw new ModelProfileCredentialError(profileLabel, [proxyProvider!]);
+	const strictMissing = missingProviders.filter(
+		provider => !proxyRoutableProviders.has(provider) && !alternativeSet.has(provider),
+	);
+	if (strictMissing.length > 0) throw new ModelProfileCredentialError(profileLabel, strictMissing);
+	const strictRoutableMissing = missingProviders.filter(
+		provider => proxyRoutableProviders.has(provider) && !alternativeSet.has(provider),
+	);
+	if (strictRoutableMissing.length > 0 && !proxyAuthenticated) {
+		throw new ModelProfileCredentialError(
+			profileLabel,
+			proxyProvider === undefined ? strictRoutableMissing : [proxyProvider],
+		);
+	}
+	for (const group of alternativeGroups) {
+		if (group.some(provider => authenticatedProviders.has(provider))) continue;
+		const allRoutable = group.every(provider => proxyRoutableProviders.has(provider));
+		if (allRoutable && proxyAuthenticated) continue;
+		throw new ModelProfileCredentialError(
+			profileLabel,
+			allRoutable && proxyProvider !== undefined ? [proxyProvider] : [...group],
+		);
+	}
+	const availableModels =
+		options.modelRegistry.getAvailableForProfileActivation?.() ??
+		options.modelRegistry.getAvailable?.() ??
+		options.modelRegistry.getAll();
+	let bindings = resolveProfileBindings(profile);
+	if (alternativeGroups.length > 0)
+		bindings = rewriteBindingsProviders(bindings, authenticatedProviders, alternativeGroups);
+	if (proxyProvider !== undefined && proxyAuthenticated && profile.source !== "user") {
+		bindings = rewriteBindingsForProxy(
+			bindings,
+			proxyProvider,
+			proxyMode,
+			availableModels,
+			authenticatedProviders,
+			proxyRoutableProviders,
+		);
+	}
+	await preflightModelProfileRoleBindings({
+		profile,
+		bindings,
+		roleCatalogModels: options.modelRegistry.getAll(),
+		settings: options.settings as Settings,
+		modelRegistry: options.modelRegistry as ModelRegistry,
+		sessionId: "",
+		credentialSessionId: options.credentialSessionId,
+		profileLabel,
+	});
+	if (!bindings.defaultSelector)
+		return { profileName, entries: [], explicitThinkingLevel: false, activeIndex: 0, skips: [] };
+	const defaultChain = normalizeModelSelectorValue(
+		await resolveAndClampSelectorValue(
+			bindings.defaultSelector,
+			availableModels,
+			{
+				settings: options.settings as Settings,
+				modelRegistry: options.modelRegistry as ModelRegistry,
+				sessionId: "",
+				credentialSessionId: options.credentialSessionId,
+				aliasIntent: "preset-equivalent",
+			},
+			profileLabel,
+			"default",
+		),
+	);
+	const resolution = await resolveModelChainWithAuth(
+		defaultChain,
+		{
+			getAvailable: () => availableModels,
+			getApiKey: (model, sessionId) =>
+				options.modelRegistry.getApiKeyForProvider(model.provider, sessionId, model.baseUrl),
+			resolveCanonicalModel: options.modelRegistry.resolveCanonicalModel?.bind(options.modelRegistry),
+			getCanonicalVariants: options.modelRegistry.getCanonicalVariants?.bind(options.modelRegistry),
+			getCanonicalId: options.modelRegistry.getCanonicalId?.bind(options.modelRegistry),
+			resolveModelByLookupAlias: options.modelRegistry.resolveModelByLookupAlias?.bind(options.modelRegistry),
+			lookupAliasExists: options.modelRegistry.lookupAliasExists?.bind(options.modelRegistry),
+			clearCanonicalVariant: options.modelRegistry.clearCanonicalVariant?.bind(options.modelRegistry),
+		} as ModelRegistry,
+		options.settings as Settings,
+		options.credentialSessionId,
+		{
+			managedFallback: true,
+			aliasIntent: "preset-equivalent",
+			canonicalSessionId: null,
+			credentialSessionId: options.credentialSessionId,
+		},
+	);
+	return { profileName, entries: defaultChain, ...resolution };
+}
+
 export function rewriteSelectorForProxy(
 	selector: string,
 	proxyProvider: string,
@@ -620,9 +899,13 @@ export function rewriteSelectorForProxy(
 	const baseSelector = suffix.selector;
 	const slash = baseSelector.indexOf("/");
 	const proxyModels = allModels.filter(model => model.provider === proxyProvider);
+	const matchingProxyModels = (id: string): Model<Api>[] => {
+		const publicMatches = proxyModels.filter(model => model.id === id);
+		return publicMatches.length > 0 ? publicMatches : proxyModels.filter(model => model.wireModelId === id);
+	};
 	if (slash < 0) {
 		if (proxyMode === "fallback") return selector;
-		const exactMatches = proxyModels.filter(model => model.id === baseSelector);
+		const exactMatches = matchingProxyModels(baseSelector);
 		const finalSegmentMatches = proxyModels.filter(model => model.id.split("/").at(-1) === baseSelector);
 		const matches = exactMatches.length > 0 ? exactMatches : finalSegmentMatches;
 		if (matches.length !== 1) {
@@ -640,8 +923,8 @@ export function rewriteSelectorForProxy(
 		throw new Error(`Configured proxy "${proxyProvider}" cannot route its own direct selector "${baseSelector}"`);
 	}
 	const directModelId = baseSelector.substring(slash + 1);
-	const exactMatches = proxyModels.filter(model => model.id === `${directProvider}/${directModelId}`);
-	const flatMatches = proxyModels.filter(model => model.id === directModelId);
+	const exactMatches = matchingProxyModels(`${directProvider}/${directModelId}`);
+	const flatMatches = matchingProxyModels(directModelId);
 	const matches = exactMatches.length > 0 ? exactMatches : flatMatches;
 	if (matches.length === 0) {
 		throw new Error(`Configured proxy "${proxyProvider}" does not expose a model for "${baseSelector}"`);
@@ -851,6 +1134,49 @@ async function resolveAndClampSelectorValue(
 	return clamped.length === 1 && typeof selectorValue === "string" ? clamped[0] : clamped;
 }
 
+/** Resolve every non-default binding under the profile activation contract without installing it. */
+async function preflightModelProfileRoleBindings(options: {
+	profile: ModelProfileDefinition;
+	bindings: ResolvedProfileBinding;
+	roleCatalogModels: Model<Api>[];
+	settings: Settings;
+	modelRegistry: ModelRegistry;
+	sessionId: string;
+	credentialSessionId: string;
+	profileLabel: string;
+}): Promise<{
+	modelRoles: Record<string, ModelSelectorValue>;
+	agentModelOverrides: Record<string, ModelSelectorValue>;
+}> {
+	const resolveBindings = async (bindings: Record<string, ModelSelectorValue>) => {
+		const resolved: Record<string, ModelSelectorValue> = {};
+		for (const [role, selectorValue] of Object.entries(bindings) as [
+			GjcModelAssignmentTargetId,
+			ModelSelectorValue,
+		][]) {
+			resolved[role] = await resolveAndClampSelectorValue(
+				selectorValue,
+				options.roleCatalogModels,
+				{
+					settings: options.settings,
+					modelRegistry: options.modelRegistry,
+					sessionId: options.sessionId,
+					credentialSessionId: options.credentialSessionId,
+					aliasIntent: "preset-equivalent",
+					requireQualifiedResolution: requiresQualifiedModelProfileRoleResolution(options.profile),
+				},
+				options.profileLabel,
+				role,
+			);
+		}
+		return resolved;
+	};
+	return {
+		modelRoles: await resolveBindings(options.bindings.modelRoles),
+		agentModelOverrides: await resolveBindings(options.bindings.agentModelOverrides),
+	};
+}
+
 async function concretizeProfileSelectorValue(
 	selectorValue: ModelSelectorValue,
 	prepared: PreparedModelProfileActivation,
@@ -957,6 +1283,33 @@ export async function prepareModelProfileActivation(
 			...alternativeSet,
 			...deriveModelProfileMappedProviders(profile),
 		]);
+		// A required provider this build cannot know is a build/config mismatch,
+		// not a credential gap: diagnose it before any auth probing so the user
+		// is never sent to /login for a provider this binary cannot serve (for
+		// example a models.yml profile authored on a newer or custom build). A
+		// registry without provider visibility keeps the legacy
+		// credential diagnosis.
+		const configuredProviderIds = options.modelRegistry.getConfiguredProviderIds?.();
+		if (configuredProviderIds !== undefined || options.modelRegistry.isKnownProvider !== undefined) {
+			const isProviderKnown = (provider: string): boolean =>
+				(options.modelRegistry.isKnownProvider?.(provider) ?? false) ||
+				isKnownProvider(provider) ||
+				configuredProviderIds?.includes(provider) === true;
+			const unknownRequiredProviders = new Set<string>();
+			for (const provider of requiredProviders) {
+				if (!alternativeSet.has(provider) && !isProviderKnown(provider)) unknownRequiredProviders.add(provider);
+			}
+			for (const group of alternativeGroups) {
+				if (group.some(isProviderKnown)) continue;
+				for (const provider of group) {
+					if (!isProviderKnown(provider)) unknownRequiredProviders.add(provider);
+				}
+			}
+			const unknownProviderIds = [...unknownRequiredProviders].sort();
+			if (unknownProviderIds.length > 0) {
+				throw new ModelProfileUnknownProviderError(profileLabel, unknownProviderIds);
+			}
+		}
 
 		const missingProviders: string[] = [];
 		const authenticatedProviders: string[] = [];
@@ -995,18 +1348,18 @@ export async function prepareModelProfileActivation(
 		if (proxyMode === "always" && proxyProvider === undefined) {
 			throw new Error('modelProfile.proxyMode "always" requires modelProfile.proxyProvider');
 		}
+		const proxyApiKey =
+			proxyProvider === undefined
+				? undefined
+				: await options.modelRegistry.getApiKeyForProvider(proxyProvider, credentialSessionId);
 		if (proxyProvider !== undefined) {
 			const configuredProxyProviders = options.modelRegistry.getConfiguredProviderIds?.();
-			if (!configuredProxyProviders?.includes(proxyProvider)) {
+			if (!isModelProfileProxyConfigured(proxyProvider, configuredProxyProviders, proxyApiKey === kNoAuth)) {
 				throw new Error(
 					`modelProfile.proxyProvider "${proxyProvider}" is not configured. Configure it with \`gjc setup provider\` before activating a preset.`,
 				);
 			}
 		}
-		const proxyApiKey =
-			proxyProvider === undefined
-				? undefined
-				: await options.modelRegistry.getApiKeyForProvider(proxyProvider, credentialSessionId);
 		const proxyAuthenticated =
 			proxyProvider !== undefined &&
 			proxyApiKey !== undefined &&
@@ -1118,47 +1471,16 @@ export async function prepareModelProfileActivation(
 			throw new Error(`Model profile "${profileLabel}" default selectors did not resolve to an authenticated model`);
 		}
 
-		const modelRoles: Record<string, ModelSelectorValue> = {};
-		for (const [role, selectorValue] of Object.entries(bindings.modelRoles) as [
-			GjcModelAssignmentTargetId,
-			ModelSelectorValue,
-		][]) {
-			modelRoles[role] = await resolveAndClampSelectorValue(
-				selectorValue,
-				roleCatalogModels,
-				{
-					settings: options.settings as Settings,
-					modelRegistry: options.modelRegistry as ModelRegistry,
-					sessionId: options.session.sessionId,
-					credentialSessionId,
-					aliasIntent: "preset-equivalent",
-					requireQualifiedResolution: requiresQualifiedModelProfileRoleResolution(profile),
-				},
-				profileLabel,
-				role,
-			);
-		}
-
-		const agentModelOverrides: Record<string, ModelSelectorValue> = {};
-		for (const [role, selectorValue] of Object.entries(bindings.agentModelOverrides) as [
-			GjcModelAssignmentTargetId,
-			ModelSelectorValue,
-		][]) {
-			agentModelOverrides[role] = await resolveAndClampSelectorValue(
-				selectorValue,
-				roleCatalogModels,
-				{
-					settings: options.settings as Settings,
-					modelRegistry: options.modelRegistry as ModelRegistry,
-					sessionId: options.session.sessionId,
-					credentialSessionId,
-					aliasIntent: "preset-equivalent",
-					requireQualifiedResolution: requiresQualifiedModelProfileRoleResolution(profile),
-				},
-				profileLabel,
-				role,
-			);
-		}
+		const { modelRoles, agentModelOverrides } = await preflightModelProfileRoleBindings({
+			profile,
+			bindings,
+			roleCatalogModels,
+			settings: options.settings as Settings,
+			modelRegistry: options.modelRegistry as ModelRegistry,
+			sessionId: options.session.sessionId,
+			credentialSessionId,
+			profileLabel,
+		});
 
 		return {
 			profileName,
@@ -1660,3 +1982,34 @@ export async function activateModelProfile(
 	const prepared = await prepareModelProfileActivation(options);
 	await applyPreparedModelProfileActivation(prepared, applyOptions);
 }
+
+/** Install only a profile's runtime role layer, preserving session model and configured-chain intent. */
+export async function applyModelProfileRuntimeBindings(options: PrepareModelProfileActivationOptions): Promise<void> {
+	const prepared = await prepareModelProfileActivation(options);
+	try {
+		prepared.settings.override("modelRoles", {
+			...prepared.baseModelRoles,
+			...prepared.modelRoles,
+		});
+		prepared.settings.override("task.agentModelOverrides", {
+			...prepared.baseAgentModelOverrides,
+			...prepared.agentModelOverrides,
+		});
+		prepared.session.setActiveModelProfile?.(prepared.profileName);
+		prepared.session.noteProfileInstalledOverrides?.(
+			Object.keys(prepared.modelRoles),
+			Object.keys(prepared.agentModelOverrides),
+			prepared.previousModel,
+		);
+		try {
+			await prepared.session.syncEagerDelegation?.();
+		} catch (error) {
+			logger.warn("Failed to sync eager delegation after recovered profile runtime bindings", {
+				profile: prepared.profileName,
+				error: error instanceof Error ? error.message : String(error),
+			});
+		}
+	} finally {
+		restoreCanonicalVariant(prepared.modelRegistry, prepared.session.sessionId, prepared.previousCanonicalVariant);
+	}
+}