advisor-pi 1.0.3 → 1.2.0

package/src/index.ts

@@ -7,16 +7,22 @@ import {
 	type ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
+import { loadPreferences, savePreferencesPatch, type AdvisorPreferencesPatch } from "./preferences.js";
+import { buildMenuRows, type MenuKey, rowForLabel } from "./config-ui.js";
 
-const STATE_ENTRY = "advisor-pi-state";
+export { loadPreferences, preferencesPath, savePreferences, savePreferencesPatch } from "./preferences.js";
+export type { AdvisorPreferences, AdvisorPreferencesConfig, AdvisorPreferencesPatch } from "./preferences.js";
+
+export const STATE_ENTRY = "advisor-pi-state";
 const TOOL_NAME = "advisor";
-const DEFAULT_ADVISOR_MODEL = "openai-codex/gpt-5.6-sol";
-const LEGACY_DEFAULT_ADVISOR_MODEL = "openai-codex/gpt-5.5";
+export const DEFAULT_ADVISOR_MODEL = "openai-codex/gpt-5.6-sol";
+export const LEGACY_DEFAULT_ADVISOR_MODEL = "openai-codex/gpt-5.5";
 const DEFAULT_ADVISOR_THINKING_LEVEL: AdvisorThinkingLevel = "high";
 const DEFAULT_MAX_USES = 5;
 const DEFAULT_CACHE_RETENTION: CacheRetention = "short";
 const DEFAULT_TIMEOUT_MS = 600_000;
 const DEFAULT_MAX_TOKENS = 4_000;
+export const DEFAULT_MAX_TRANSCRIPT_CHARS = 20_000;
 
 const advisorToolSchema = Type.Object({
 	question: Type.String({
@@ -40,7 +46,9 @@ const advisorToolSchema = Type.Object({
 type AdvisorToolInput = Static<typeof advisorToolSchema>;
 type AdvisorThinkingLevel = ThinkingLevel | "max";
 
-type AdvisorConfig = {
+type ModeAwareContext = ExtensionContext & { mode?: string };
+
+export type AdvisorConfig = {
 	enabled: boolean;
 	provider: string;
 	modelId: string;
@@ -49,6 +57,7 @@ type AdvisorConfig = {
 	cacheRetention: CacheRetention;
 	maxTokens: number;
 	timeoutMs: number;
+	maxTranscriptChars: number;
 };
 
 type AdvisorStateEntry = {
@@ -74,8 +83,21 @@ type AdvisorToolDetails = {
 	state: AdvisorStateEntry;
 };
 
+export type ModelRegistryLike = {
+	find: (provider: string, modelId: string) => unknown;
+	getAvailable?: () => Array<{ provider?: unknown; id?: unknown }>;
+};
+
+export type NormalizeConfigOptions = {
+	migrateLegacyDefault?: boolean;
+};
+
+function isTuiContext(ctx: ExtensionContext): boolean {
+	return (ctx as ModeAwareContext).mode === "tui" && ctx.hasUI;
+}
+
 export default function advisorPiExtension(pi: ExtensionAPI) {
-	let config = defaultConfig();
+	let config = normalizeConfig(loadPreferences(), defaultConfig(), undefined, { migrateLegacyDefault: false });
 	let useCount = 0;
 
 	pi.registerFlag("advisor-model", {
@@ -94,10 +116,13 @@ export default function advisorPiExtension(pi: ExtensionAPI) {
 		description: "Advisor prompt-cache preference: none, short, or long",
 		type: "string",
 	});
+	pi.registerFlag("advisor-max-transcript-chars", {
+		description: "Maximum conversation transcript characters sent per advisor call (keeps most recent)",
+		type: "string",
+	});
 	pi.registerFlag("advisor-enabled", {
 		description: "Enable the advisor tool on startup",
 		type: "boolean",
-		default: true,
 	});
 
 	pi.registerTool<typeof advisorToolSchema, AdvisorToolDetails>({
@@ -115,8 +140,8 @@ export default function advisorPiExtension(pi: ExtensionAPI) {
 		parameters: advisorToolSchema,
 		executionMode: "sequential",
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
-			refreshStateFromBranch(ctx);
-
+			// Branch state is replayed at session_start/session_tree; refreshing here
+			// would reapply startup flags over explicit in-session command edits.
 			if (!config.enabled) {
 				return advisorDisabledResult(config, useCount, params);
 			}
@@ -146,7 +171,7 @@ export default function advisorPiExtension(pi: ExtensionAPI) {
 			if (!auth.ok) throw new Error(auth.error);
 
 			const startedAt = Date.now();
-			const conversationText = serializeCurrentConversation(ctx);
+			const conversationText = truncateTranscript(serializeCurrentConversation(ctx), config.maxTranscriptChars);
 			const userMessage: Message = {
 				role: "user",
 				content: [
@@ -218,13 +243,16 @@ export default function advisorPiExtension(pi: ExtensionAPI) {
 	});
 
 	pi.registerCommand("advisor-pi", {
-		description: "Configure advisor-pi: status, enable, disable, model, thinking, max-uses, cache, reset",
+		description: "Configure advisor-pi: status, enable, disable, model, thinking, max-uses, max-transcript-chars, cache, reset",
 		handler: async (args, ctx) => {
-			const result = handleCommand(args.trim(), ctx);
-			if (result.persist) persistState(pi, config, useCount);
-			if (result.updateToolState) syncActiveTool(pi);
-			updateStatus(ctx);
-			ctx.ui.notify(result.message, result.level);
+			const trimmed = args.trim();
+			// Bare /advisor-pi is interactive only in the terminal TUI. Other modes
+			// keep the existing status response for scripts and print output.
+			if (!trimmed && isTuiContext(ctx)) {
+				await openConfigPanel(ctx);
+				return;
+			}
+			await applyCommand(trimmed, ctx);
 		},
 	});
 
@@ -248,28 +276,30 @@ export default function advisorPiExtension(pi: ExtensionAPI) {
 	});
 
 	function refreshStateFromBranch(ctx: ExtensionContext): void {
-		config = defaultConfig();
+		config = normalizeConfig(loadPreferences(), defaultConfig(), ctx.modelRegistry, { migrateLegacyDefault: false });
+
 		useCount = 0;
-		const restoredFromBranch = restoreStateFromSession(ctx);
-		if (!restoredFromBranch) applyStartupFlags(pi);
+		restoreStateFromSession(ctx, ctx.modelRegistry);
+		applyStartupFlags(pi, ctx.modelRegistry);
+		ensureAdvisorModelResolves(ctx);
 		syncActiveTool(pi);
 		updateStatus(ctx);
 	}
 
-	function restoreStateFromSession(ctx: ExtensionContext): boolean {
+	function restoreStateFromSession(ctx: ExtensionContext, registry?: ModelRegistryLike): boolean {
 		let restored = false;
 		const branch = ctx.sessionManager.getBranch();
 		for (const entry of branch) {
 			if (entry.type === "custom" && entry.customType === STATE_ENTRY) {
 				restored = true;
 				const data = entry.data as Partial<AdvisorStateEntry> | undefined;
-				if (data?.config) config = normalizeConfig(data.config, config);
+				if (data?.config) config = normalizeConfig(data.config, config, registry);
 				if (typeof data?.useCount === "number") useCount = Math.max(0, data.useCount);
 			}
 			if (entry.type === "message" && entry.message.role === "toolResult" && entry.message.toolName === TOOL_NAME) {
 				restored = true;
 				const details = entry.message.details as Partial<AdvisorToolDetails> | undefined;
-				if (details?.state?.config) config = normalizeConfig(details.state.config, config);
+				if (details?.state?.config) config = normalizeConfig(details.state.config, config, registry);
 				if (typeof details?.state?.useCount === "number") useCount = Math.max(useCount, details.state.useCount);
 				else if (details?.advisor?.useCount) useCount = Math.max(useCount, details.advisor.useCount);
 			}
@@ -277,42 +307,78 @@ export default function advisorPiExtension(pi: ExtensionAPI) {
 		return restored;
 	}
 
-	function applyStartupFlags(api: ExtensionAPI): void {
-		const enabledFlag = api.getFlag("advisor-enabled");
+	function applyStartupFlags(api: ExtensionAPI, registry?: ModelRegistryLike): void {
+		const enabledFlag = flagValue(api, "advisor-enabled");
 		if (typeof enabledFlag === "boolean") config.enabled = enabledFlag;
 
-		const modelFlag = api.getFlag("advisor-model");
+		const modelFlag = flagValue(api, "advisor-model");
 		if (typeof modelFlag === "string" && modelFlag.trim()) {
 			const parsed = parseModelSpec(modelFlag.trim());
-			if (parsed) {
+			if (parsed && (!registry || modelResolves(registry, parsed.provider, parsed.modelId))) {
 				config.provider = parsed.provider;
 				config.modelId = parsed.modelId;
 			}
 		}
 
-		const thinkingFlag = api.getFlag("advisor-thinking");
+		const thinkingFlag = flagValue(api, "advisor-thinking");
 		if (typeof thinkingFlag === "string") {
 			const thinkingLevel = parseThinkingLevel(thinkingFlag);
 			if (thinkingLevel) config.thinkingLevel = thinkingLevel;
 		}
 
-		const maxUsesFlag = api.getFlag("advisor-max-uses");
+		const maxUsesFlag = flagValue(api, "advisor-max-uses");
 		if (typeof maxUsesFlag === "string") {
 			const maxUses = parsePositiveInt(maxUsesFlag);
 			if (maxUses !== undefined) config.maxUses = maxUses;
 		}
 
-		const cacheFlag = api.getFlag("advisor-cache");
+		const cacheFlag = flagValue(api, "advisor-cache");
 		if (typeof cacheFlag === "string") {
 			const cacheRetention = parseCacheRetention(cacheFlag);
 			if (cacheRetention) config.cacheRetention = cacheRetention;
 		}
+
+		const maxTranscriptCharsFlag = flagValue(api, "advisor-max-transcript-chars");
+		if (typeof maxTranscriptCharsFlag === "string") {
+			const maxTranscriptChars = parsePositiveInt(maxTranscriptCharsFlag);
+			if (maxTranscriptChars !== undefined) config.maxTranscriptChars = maxTranscriptChars;
+		}
+	}
+
+	function ensureAdvisorModelResolves(ctx: ExtensionContext): void {
+		const registry = ctx.modelRegistry as ModelRegistryLike | undefined;
+		if (!registry || modelResolves(registry, config.provider, config.modelId)) return;
+		const previous = `${config.provider}/${config.modelId}`;
+		const candidates = [parseModelSpec(DEFAULT_ADVISOR_MODEL), parseModelSpec(LEGACY_DEFAULT_ADVISOR_MODEL)].filter(
+			(candidate): candidate is { provider: string; modelId: string } => candidate !== undefined,
+		);
+		const working = resolveAdvisorModel(registry, candidates);
+		if (!working) return;
+		config.provider = working.provider;
+		config.modelId = working.modelId;
+		persistState(pi, config, useCount);
+		if (ctx.hasUI) {
+			ctx.ui.notify(`Advisor model ${previous} not found. Falling back to ${working.provider}/${working.modelId}.`, "warning");
+		}
+	}
+
+	async function persistPreferencesForEdit(ctx: ExtensionContext, patch: AdvisorPreferencesPatch): Promise<void> {
+		if (await savePreferencesPatch(patch)) return;
+		if (ctx.hasUI) {
+			ctx.ui.notify("Could not save advisor-pi preferences; this change applies to the current session only.", "warning");
+		}
 	}
 
 	function handleCommand(
 		args: string,
 		ctx: ExtensionContext,
-	): { message: string; level: "info" | "warning" | "error"; persist: boolean; updateToolState: boolean } {
+	): {
+		message: string;
+		level: "info" | "warning" | "error";
+		persist: boolean;
+		preferencePatch?: AdvisorPreferencesPatch;
+		updateToolState: boolean;
+	} {
 		if (!args || args === "status") {
 			return {
 				message: formatStatus(ctx),
@@ -328,10 +394,22 @@ export default function advisorPiExtension(pi: ExtensionAPI) {
 		switch (command) {
 			case "enable":
 				config.enabled = true;
-				return { message: "advisor-pi enabled", level: "info", persist: true, updateToolState: true };
+				return {
+					message: "advisor-pi enabled",
+					level: "info",
+					persist: true,
+					preferencePatch: { enabled: true },
+					updateToolState: true,
+				};
 			case "disable":
 				config.enabled = false;
-				return { message: "advisor-pi disabled", level: "info", persist: true, updateToolState: true };
+				return {
+					message: "advisor-pi disabled",
+					level: "info",
+					persist: true,
+					preferencePatch: { enabled: false },
+					updateToolState: true,
+				};
 			case "reset":
 				useCount = 0;
 				return { message: "advisor-pi use count reset", level: "info", persist: true, updateToolState: false };
@@ -360,6 +438,7 @@ export default function advisorPiExtension(pi: ExtensionAPI) {
 					message: `advisor-pi model set to ${config.provider}/${config.modelId}`,
 					level: "info",
 					persist: true,
+					preferencePatch: { provider: config.provider, modelId: config.modelId },
 					updateToolState: false,
 				};
 			}
@@ -378,6 +457,7 @@ export default function advisorPiExtension(pi: ExtensionAPI) {
 					message: `advisor-pi thinking level set to ${thinkingLevel}`,
 					level: "info",
 					persist: true,
+					preferencePatch: { thinkingLevel },
 					updateToolState: false,
 				};
 			}
@@ -396,6 +476,7 @@ export default function advisorPiExtension(pi: ExtensionAPI) {
 					message: `advisor-pi max uses set to ${maxUses}`,
 					level: "info",
 					persist: true,
+					preferencePatch: { maxUses },
 					updateToolState: false,
 				};
 			}
@@ -414,13 +495,33 @@ export default function advisorPiExtension(pi: ExtensionAPI) {
 					message: `advisor-pi cache set to ${cacheRetention}`,
 					level: "info",
 					persist: true,
+					preferencePatch: { cacheRetention },
+					updateToolState: false,
+				};
+			}
+			case "max-transcript-chars": {
+				const maxTranscriptChars = parsePositiveInt(value);
+				if (maxTranscriptChars === undefined) {
+					return {
+						message: "Usage: /advisor-pi max-transcript-chars <positive-number>",
+						level: "error",
+						persist: false,
+						updateToolState: false,
+					};
+				}
+				config.maxTranscriptChars = maxTranscriptChars;
+				return {
+					message: `advisor-pi max transcript chars set to ${maxTranscriptChars}`,
+					level: "info",
+					persist: true,
+					preferencePatch: { maxTranscriptChars },
 					updateToolState: false,
 				};
 			}
 			default:
 				return {
 					message:
-						"Usage: /advisor-pi [status|enable|disable|model <provider>/<model>|thinking <minimal|low|medium|high|xhigh|max>|max-uses <n>|cache <none|short|long>|reset]",
+						"Usage: /advisor-pi [status|enable|disable|model <provider>/<model>|thinking <minimal|low|medium|high|xhigh|max>|max-uses <n>|max-transcript-chars <n>|cache <none|short|long>|reset]",
 					level: "error",
 					persist: false,
 					updateToolState: false,
@@ -428,6 +529,110 @@ export default function advisorPiExtension(pi: ExtensionAPI) {
 		}
 	}
 
+	async function applyCommand(
+		args: string,
+		ctx: ExtensionContext,
+		options: { redactModelErrors?: boolean } = {},
+	): Promise<void> {
+		const result = handleCommand(args, ctx);
+		if (result.persist) {
+			persistState(pi, config, useCount);
+			if (result.preferencePatch) await persistPreferencesForEdit(ctx, result.preferencePatch);
+		}
+		if (result.updateToolState) syncActiveTool(pi);
+		updateStatus(ctx);
+		const message = options.redactModelErrors && result.level === "error" ? "Advisor model not found" : result.message;
+		ctx.ui.notify(message, result.level);
+	}
+
+	async function openConfigPanel(ctx: ExtensionContext): Promise<void> {
+		for (;;) {
+			const rows = buildMenuRows(config, useCount);
+			const choice = await ctx.ui.select("advisor-pi settings", rows.map((row) => row.label));
+			const row = rowForLabel(rows, choice);
+			// Escape returns undefined, which closes the panel without changing state.
+			if (!row || row.key === "close") return;
+			await applyMenuChoice(row.key, ctx);
+		}
+	}
+
+	async function applyMenuChoice(key: MenuKey, ctx: ExtensionContext): Promise<void> {
+		switch (key) {
+			case "enabled": {
+				const choice = await ctx.ui.select("Advisor enabled", ["enabled", "disabled"]);
+				if (choice !== "enabled" && choice !== "disabled") return;
+				const enabled = choice === "enabled";
+				if (enabled === config.enabled) return;
+				const confirmed = await ctx.ui.confirm(
+					enabled ? "Enable advisor-pi?" : "Disable advisor-pi?",
+					enabled
+						? "The advisor tool will be available to the executor."
+						: "The advisor tool will be removed from the active tool list.",
+				);
+				if (!confirmed) return;
+				await applyCommand(enabled ? "enable" : "disable", ctx);
+				return;
+			}
+			case "model": {
+				const typed = await ctx.ui.input("Advisor model", "provider/model");
+				if (typed === undefined) return;
+				const parsed = parseModelSpec(typed);
+				if (!parsed) {
+					ctx.ui.notify("Expected provider/model", "error");
+					return;
+				}
+				let model: unknown;
+				try {
+					model = ctx.modelRegistry.find(parsed.provider, parsed.modelId);
+				} catch {
+					model = undefined;
+				}
+				if (!model) {
+					ctx.ui.notify("Advisor model not found", "error");
+					return;
+				}
+				await applyCommand(`model ${parsed.provider}/${parsed.modelId}`, ctx, { redactModelErrors: true });
+				return;
+			}
+			case "thinking": {
+				const choice = await ctx.ui.select("Advisor thinking", ["minimal", "low", "medium", "high", "xhigh", "max"]);
+				if (!parseThinkingLevel(choice)) return;
+				await applyCommand(`thinking ${choice}`, ctx);
+				return;
+			}
+			case "max-uses": {
+				const value = await ctx.ui.input("Maximum advisor uses", String(config.maxUses));
+				if (value === undefined) return;
+				await applyCommand(`max-uses ${value}`, ctx);
+				return;
+			}
+			case "max-transcript-chars": {
+				const value = await ctx.ui.input("Maximum transcript characters", String(config.maxTranscriptChars));
+				if (value === undefined) return;
+				await applyCommand(`max-transcript-chars ${value}`, ctx);
+				return;
+			}
+			case "cache": {
+				const choice = await ctx.ui.select("Advisor cache retention", ["none", "short", "long"]);
+				if (!parseCacheRetention(choice)) return;
+				await applyCommand(`cache ${choice}`, ctx);
+				return;
+			}
+			case "reset": {
+				if (useCount <= 0) return;
+				const confirmed = await ctx.ui.confirm(
+					"Reset advisor use count?",
+					`This clears ${useCount} advisor use${useCount === 1 ? "" : "s"} for the current session branch.`,
+				);
+				if (!confirmed) return;
+				await applyCommand("reset", ctx);
+				return;
+			}
+			case "close":
+				return;
+		}
+	}
+
 	function syncActiveTool(api: ExtensionAPI): void {
 		const activeTools = api.getActiveTools();
 		const hasAdvisor = activeTools.includes(TOOL_NAME);
@@ -460,6 +665,7 @@ export default function advisorPiExtension(pi: ExtensionAPI) {
 			`model: ${config.provider}/${config.modelId} (${availability})`,
 			`thinking: ${config.thinkingLevel}`,
 			`uses: ${useCount}/${config.maxUses}`,
+			`transcript: max ${config.maxTranscriptChars} chars`,
 			`cache: ${config.cacheRetention}`,
 		].join(" • ");
 	}
@@ -477,7 +683,7 @@ Your role is strategic guidance only. You do not have tools and you do not make
 
 Return guidance in short sections with bullets when useful.`;
 
-function defaultConfig(): AdvisorConfig {
+export function defaultConfig(): AdvisorConfig {
 	const parsed = parseModelSpec(DEFAULT_ADVISOR_MODEL) ?? { provider: "openai-codex", modelId: "gpt-5.6-sol" };
 	return {
 		enabled: true,
@@ -488,6 +694,7 @@ function defaultConfig(): AdvisorConfig {
 		cacheRetention: DEFAULT_CACHE_RETENTION,
 		maxTokens: DEFAULT_MAX_TOKENS,
 		timeoutMs: DEFAULT_TIMEOUT_MS,
+		maxTranscriptChars: DEFAULT_MAX_TRANSCRIPT_CHARS,
 	};
 }
 
@@ -509,6 +716,13 @@ function serializeCurrentConversation(ctx: ExtensionContext): string {
 	return serializeConversation(llmMessages);
 }
 
+export function truncateTranscript(text: string, maxChars: number): string {
+	if (maxChars <= 0) return text;
+	if (text.length <= maxChars) return text;
+	const omitted = text.length - maxChars;
+	return `[... earlier conversation truncated: showing the most recent ${maxChars} of ${text.length} characters (${omitted} omitted)]\n\n${text.slice(text.length - maxChars)}`;
+}
+
 function buildAdvisorUserPrompt(params: AdvisorToolInput, conversationText: string): string {
 	return [
 		"## Executor Question",
@@ -572,7 +786,7 @@ function makeSkippedDetails(config: AdvisorConfig, useCount: number, params: Adv
 	};
 }
 
-function makeStateEntry(config: AdvisorConfig, useCount: number): AdvisorStateEntry {
+export function makeStateEntry(config: AdvisorConfig, useCount: number): AdvisorStateEntry {
 	return {
 		version: 1,
 		config: { ...config },
@@ -581,48 +795,116 @@ function makeStateEntry(config: AdvisorConfig, useCount: number): AdvisorStateEn
 	};
 }
 
-function persistState(pi: ExtensionAPI, config: AdvisorConfig, useCount: number): void {
+export function persistState(pi: ExtensionAPI, config: AdvisorConfig, useCount: number): void {
 	pi.appendEntry(STATE_ENTRY, makeStateEntry(config, useCount));
 }
 
-function normalizeConfig(input: Partial<AdvisorConfig>, fallback: AdvisorConfig): AdvisorConfig {
+export function normalizeConfig(
+	input: Partial<AdvisorConfig>,
+	fallback: AdvisorConfig,
+	registry?: ModelRegistryLike,
+	options: NormalizeConfigOptions = {},
+): AdvisorConfig {
 	const normalized: AdvisorConfig = {
 		enabled: typeof input.enabled === "boolean" ? input.enabled : fallback.enabled,
-		provider: typeof input.provider === "string" && input.provider ? input.provider : fallback.provider,
-		modelId: typeof input.modelId === "string" && input.modelId ? input.modelId : fallback.modelId,
+		provider: typeof input.provider === "string" && input.provider.trim() ? input.provider.trim() : fallback.provider,
+		modelId: typeof input.modelId === "string" && input.modelId.trim() ? input.modelId.trim() : fallback.modelId,
 		thinkingLevel: parseThinkingLevel(input.thinkingLevel) ?? fallback.thinkingLevel,
-		maxUses: typeof input.maxUses === "number" && input.maxUses > 0 ? Math.floor(input.maxUses) : fallback.maxUses,
+		maxUses:
+			typeof input.maxUses === "number" && Number.isFinite(input.maxUses) && Math.floor(input.maxUses) > 0
+				? Math.floor(input.maxUses)
+				: fallback.maxUses,
 		cacheRetention: parseCacheRetention(input.cacheRetention) ?? fallback.cacheRetention,
-		maxTokens: typeof input.maxTokens === "number" && input.maxTokens > 0 ? Math.floor(input.maxTokens) : fallback.maxTokens,
-		timeoutMs: typeof input.timeoutMs === "number" && input.timeoutMs > 0 ? Math.floor(input.timeoutMs) : fallback.timeoutMs,
+		maxTokens:
+			typeof input.maxTokens === "number" && Number.isFinite(input.maxTokens) && Math.floor(input.maxTokens) > 0
+				? Math.floor(input.maxTokens)
+				: fallback.maxTokens,
+		timeoutMs:
+			typeof input.timeoutMs === "number" && Number.isFinite(input.timeoutMs) && Math.floor(input.timeoutMs) > 0
+				? Math.floor(input.timeoutMs)
+				: fallback.timeoutMs,
+		maxTranscriptChars:
+			typeof input.maxTranscriptChars === "number" && Number.isFinite(input.maxTranscriptChars) && Math.floor(input.maxTranscriptChars) > 0
+				? Math.floor(input.maxTranscriptChars)
+				: fallback.maxTranscriptChars,
 	};
 
 	const legacyDefault = parseModelSpec(LEGACY_DEFAULT_ADVISOR_MODEL);
 	if (
+		options.migrateLegacyDefault !== false &&
 		input.thinkingLevel === undefined &&
 		legacyDefault &&
 		normalized.provider === legacyDefault.provider &&
 		normalized.modelId === legacyDefault.modelId
 	) {
-		normalized.provider = fallback.provider;
-		normalized.modelId = fallback.modelId;
+		// Only rewrite the stored legacy default when the migration target resolves.
+		// Otherwise a resolving stored model would be replaced by a non-resolving default.
+		if (!registry || modelResolves(registry, fallback.provider, fallback.modelId)) {
+			normalized.provider = fallback.provider;
+			normalized.modelId = fallback.modelId;
+		}
+	}
+
+	if (registry && typeof input.provider === "string" && input.provider && typeof input.modelId === "string" && input.modelId) {
+		// Never replace a resolving stored model with a non-resolving one.
+		if (modelResolves(registry, input.provider, input.modelId) && !modelResolves(registry, normalized.provider, normalized.modelId)) {
+			normalized.provider = input.provider;
+			normalized.modelId = input.modelId;
+		}
 	}
 
 	return normalized;
 }
 
-function parseModelSpec(value: string): { provider: string; modelId: string } | undefined {
-	const slash = value.indexOf("/");
-	if (slash <= 0 || slash === value.length - 1) return undefined;
-	return {
-		provider: value.slice(0, slash),
-		modelId: value.slice(slash + 1),
-	};
+export function modelResolves(registry: ModelRegistryLike | undefined, provider: string, modelId: string): boolean {
+	if (!registry) return false;
+	try {
+		const found = registry.find(provider, modelId);
+		return found !== undefined && found !== null;
+	} catch {
+		return false;
+	}
+}
+
+export function resolveAdvisorModel(
+	registry: ModelRegistryLike | undefined,
+	candidates: Array<{ provider: string; modelId: string }>,
+): { provider: string; modelId: string } | undefined {
+	if (!registry) return undefined;
+	for (const candidate of candidates) {
+		if (modelResolves(registry, candidate.provider, candidate.modelId)) return candidate;
+	}
+	try {
+		const available = registry.getAvailable?.();
+		const first = Array.isArray(available) ? available[0] : undefined;
+		if (first && typeof first.provider === "string" && typeof first.id === "string" && first.provider && first.id) {
+			return { provider: first.provider, modelId: first.id };
+		}
+	} catch {
+		// Ignore registry listing failures; callers keep the current config.
+	}
+	return undefined;
+}
+
+export function parseModelSpec(value: string): { provider: string; modelId: string } | undefined {
+	const trimmed = value.trim();
+	const slash = trimmed.indexOf("/");
+	if (slash <= 0 || slash === trimmed.length - 1) return undefined;
+	const provider = trimmed.slice(0, slash).trim();
+	const modelId = trimmed.slice(slash + 1).trim();
+	if (!provider || !modelId) return undefined;
+	return { provider, modelId };
+}
+
+function flagValue(api: ExtensionAPI, name: string): boolean | string | undefined {
+	return typeof api.getFlag === "function" ? api.getFlag(name) : undefined;
 }
 
 function parsePositiveInt(value: string): number | undefined {
-	const parsed = Number.parseInt(value, 10);
-	if (!Number.isFinite(parsed) || parsed <= 0) return undefined;
+	const trimmed = value.trim();
+	if (!/^\d+$/.test(trimmed)) return undefined;
+	const parsed = Number(trimmed);
+	if (!Number.isSafeInteger(parsed) || parsed <= 0) return undefined;
 	return parsed;
 }