advisor-pi 1.1.0 → 1.2.0

package/src/index.ts

@@ -7,6 +7,11 @@ 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";
+
+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";
@@ -41,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;
@@ -81,8 +88,16 @@ export type ModelRegistryLike = {
 	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", {
@@ -108,7 +123,6 @@ export default function advisorPiExtension(pi: ExtensionAPI) {
 	pi.registerFlag("advisor-enabled", {
 		description: "Enable the advisor tool on startup",
 		type: "boolean",
-		default: true,
 	});
 
 	pi.registerTool<typeof advisorToolSchema, AdvisorToolDetails>({
@@ -126,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);
 			}
@@ -231,11 +245,14 @@ export default function advisorPiExtension(pi: ExtensionAPI) {
 	pi.registerCommand("advisor-pi", {
 		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);
 		},
 	});
 
@@ -259,10 +276,11 @@ 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, ctx.modelRegistry);
-		if (!restoredFromBranch) applyStartupFlags(pi, ctx.modelRegistry);
+		restoreStateFromSession(ctx, ctx.modelRegistry);
+		applyStartupFlags(pi, ctx.modelRegistry);
 		ensureAdvisorModelResolves(ctx);
 		syncActiveTool(pi);
 		updateStatus(ctx);
@@ -290,10 +308,10 @@ export default function advisorPiExtension(pi: ExtensionAPI) {
 	}
 
 	function applyStartupFlags(api: ExtensionAPI, registry?: ModelRegistryLike): void {
-		const enabledFlag = api.getFlag("advisor-enabled");
+		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 && (!registry || modelResolves(registry, parsed.provider, parsed.modelId))) {
@@ -302,25 +320,25 @@ export default function advisorPiExtension(pi: ExtensionAPI) {
 			}
 		}
 
-		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 = api.getFlag("advisor-max-transcript-chars");
+		const maxTranscriptCharsFlag = flagValue(api, "advisor-max-transcript-chars");
 		if (typeof maxTranscriptCharsFlag === "string") {
 			const maxTranscriptChars = parsePositiveInt(maxTranscriptCharsFlag);
 			if (maxTranscriptChars !== undefined) config.maxTranscriptChars = maxTranscriptChars;
@@ -344,10 +362,23 @@ export default function advisorPiExtension(pi: ExtensionAPI) {
 		}
 	}
 
+	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),
@@ -363,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 };
@@ -395,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,
 				};
 			}
@@ -413,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,
 				};
 			}
@@ -431,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,
 				};
 			}
@@ -449,6 +495,7 @@ export default function advisorPiExtension(pi: ExtensionAPI) {
 					message: `advisor-pi cache set to ${cacheRetention}`,
 					level: "info",
 					persist: true,
+					preferencePatch: { cacheRetention },
 					updateToolState: false,
 				};
 			}
@@ -467,6 +514,7 @@ export default function advisorPiExtension(pi: ExtensionAPI) {
 					message: `advisor-pi max transcript chars set to ${maxTranscriptChars}`,
 					level: "info",
 					persist: true,
+					preferencePatch: { maxTranscriptChars },
 					updateToolState: false,
 				};
 			}
@@ -481,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);
@@ -651,24 +803,35 @@ 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" && input.maxTranscriptChars > 0
+			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 &&
@@ -724,17 +887,24 @@ export function resolveAdvisorModel(
 }
 
 export 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),
-	};
+	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;
 }
 

package/src/preferences.ts

@@ -0,0 +1,228 @@
+import { randomUUID } from "node:crypto";
+import {
+	closeSync,
+	fsyncSync,
+	mkdirSync,
+	openSync,
+	readFileSync,
+	renameSync,
+	unlinkSync,
+	writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export const PREFERENCES_VERSION = 1;
+
+/** Fixed allow-listed names within the extension-specific preferences directory. */
+export const PREFERENCE_FILE_NAMES = Object.freeze({
+	enabled: "enabled.json",
+	model: "model.json",
+	thinkingLevel: "thinkingLevel.json",
+	maxUses: "maxUses.json",
+	cacheRetention: "cacheRetention.json",
+	maxTranscriptChars: "maxTranscriptChars.json",
+});
+
+export type AdvisorPreferencesPatch = {
+	enabled?: boolean;
+	provider?: string;
+	modelId?: string;
+	thinkingLevel?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+	maxUses?: number;
+	cacheRetention?: "none" | "short" | "long";
+	maxTranscriptChars?: number;
+};
+
+export type AdvisorPreferences = AdvisorPreferencesPatch & { version: typeof PREFERENCES_VERSION };
+
+/** Return the directory containing advisor-pi's per-setting files. */
+export function preferencesPath(agentDir: string = getAgentDir()): string {
+	return join(agentDir, "advisor-pi-preferences");
+}
+
+/** Read and independently validate the durable advisor settings. */
+export function loadPreferences(agentDir: string = getAgentDir()): AdvisorPreferencesPatch {
+	const patch: AdvisorPreferencesPatch = {};
+	const enabled = readPreference(agentDir, PREFERENCE_FILE_NAMES.enabled);
+	if (enabled && typeof enabled.enabled === "boolean") patch.enabled = enabled.enabled;
+
+	const model = readPreference(agentDir, PREFERENCE_FILE_NAMES.model);
+	if (model && typeof model.provider === "string" && model.provider.trim() && typeof model.modelId === "string" && model.modelId.trim()) {
+		patch.provider = model.provider.trim();
+		patch.modelId = model.modelId.trim();
+	}
+
+	const thinkingLevel = parseThinkingLevel(readPreference(agentDir, PREFERENCE_FILE_NAMES.thinkingLevel)?.thinkingLevel);
+	if (thinkingLevel) patch.thinkingLevel = thinkingLevel;
+
+	const maxUses = readPreference(agentDir, PREFERENCE_FILE_NAMES.maxUses)?.maxUses;
+	if (isPositiveSafeInteger(maxUses)) patch.maxUses = maxUses;
+
+	const cacheRetention = parseCacheRetention(readPreference(agentDir, PREFERENCE_FILE_NAMES.cacheRetention)?.cacheRetention);
+	if (cacheRetention) patch.cacheRetention = cacheRetention;
+
+	const maxTranscriptChars = readPreference(agentDir, PREFERENCE_FILE_NAMES.maxTranscriptChars)?.maxTranscriptChars;
+	if (isPositiveSafeInteger(maxTranscriptChars)) patch.maxTranscriptChars = maxTranscriptChars;
+
+	return patch;
+}
+
+/** Validate and persist supplied logical settings without any aggregate snapshot. */
+export async function savePreferences(config: AdvisorPreferencesPatch, agentDir: string = getAgentDir()): Promise<boolean> {
+	return saveValidatedPreferences(config, agentDir);
+}
+
+/** Validate and persist one or more deliberate logical setting edits. */
+export async function savePreferencesPatch(patch: AdvisorPreferencesPatch, agentDir: string = getAgentDir()): Promise<boolean> {
+	return saveValidatedPreferences(patch, agentDir);
+}
+
+type PreferenceWrite = { fileName: string; payload: Record<string, unknown> };
+
+async function saveValidatedPreferences(input: unknown, agentDir: string): Promise<boolean> {
+	const writes = prepareWrites(input);
+	if (!writes) return false;
+	try {
+		mkdirSync(preferencesPath(agentDir), { recursive: true, mode: 0o700 });
+	} catch {
+		return false;
+	}
+	for (const write of writes) {
+		if (!writePreference(agentDir, write)) return false;
+	}
+	return true;
+}
+
+function prepareWrites(input: unknown): PreferenceWrite[] | undefined {
+	if (!isRecord(input)) return undefined;
+	if (input.version !== undefined && input.version !== PREFERENCES_VERSION) return undefined;
+
+	const keys = Object.keys(input).filter((key) => key !== "version");
+	if (keys.length === 0) return undefined;
+	const writes: PreferenceWrite[] = [];
+	const hasProvider = keys.includes("provider");
+	const hasModelId = keys.includes("modelId");
+	if (hasProvider || hasModelId) {
+		if (!hasProvider || !hasModelId || typeof input.provider !== "string" || !input.provider.trim() || typeof input.modelId !== "string" || !input.modelId.trim()) {
+			return undefined;
+		}
+		writes.push({
+			fileName: PREFERENCE_FILE_NAMES.model,
+			payload: {
+				version: PREFERENCES_VERSION,
+				provider: input.provider.trim(),
+				modelId: input.modelId.trim(),
+			},
+		});
+	}
+
+	for (const key of keys) {
+		switch (key) {
+			case "provider":
+			case "modelId":
+				break;
+			case "enabled":
+				if (typeof input.enabled !== "boolean") return undefined;
+				writes.push({ fileName: PREFERENCE_FILE_NAMES.enabled, payload: { version: PREFERENCES_VERSION, enabled: input.enabled } });
+				break;
+			case "thinkingLevel": {
+				const thinkingLevel = parseThinkingLevel(input.thinkingLevel);
+				if (!thinkingLevel) return undefined;
+				writes.push({ fileName: PREFERENCE_FILE_NAMES.thinkingLevel, payload: { version: PREFERENCES_VERSION, thinkingLevel } });
+				break;
+			}
+			case "maxUses":
+				if (!isPositiveSafeInteger(input.maxUses)) return undefined;
+				writes.push({ fileName: PREFERENCE_FILE_NAMES.maxUses, payload: { version: PREFERENCES_VERSION, maxUses: input.maxUses } });
+				break;
+			case "cacheRetention": {
+				const cacheRetention = parseCacheRetention(input.cacheRetention);
+				if (!cacheRetention) return undefined;
+				writes.push({ fileName: PREFERENCE_FILE_NAMES.cacheRetention, payload: { version: PREFERENCES_VERSION, cacheRetention } });
+				break;
+			}
+			case "maxTranscriptChars":
+				if (!isPositiveSafeInteger(input.maxTranscriptChars)) return undefined;
+				writes.push({
+					fileName: PREFERENCE_FILE_NAMES.maxTranscriptChars,
+					payload: { version: PREFERENCES_VERSION, maxTranscriptChars: input.maxTranscriptChars },
+				});
+				break;
+			default:
+				return undefined;
+		}
+	}
+	return writes;
+}
+
+function readPreference(agentDir: string, fileName: string): Record<string, unknown> | undefined {
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(join(preferencesPath(agentDir), fileName), "utf8"));
+		if (!isRecord(parsed)) return undefined;
+		if (parsed.version !== undefined && parsed.version !== PREFERENCES_VERSION) return undefined;
+		return parsed;
+	} catch {
+		return undefined;
+	}
+}
+
+function writePreference(agentDir: string, write: PreferenceWrite): boolean {
+	const directory = preferencesPath(agentDir);
+	const temporaryPath = join(directory, `.${write.fileName}.${process.pid}.${randomUUID()}.tmp`);
+	let fileDescriptor: number | undefined;
+	try {
+		fileDescriptor = openSync(temporaryPath, "wx", 0o600);
+		writeFileSync(fileDescriptor, `${JSON.stringify(write.payload, null, 2)}\n`, "utf8");
+		fsyncSync(fileDescriptor);
+		closeSync(fileDescriptor);
+		fileDescriptor = undefined;
+		renameSync(temporaryPath, join(directory, write.fileName));
+		return true;
+	} catch {
+		return false;
+	} finally {
+		if (fileDescriptor !== undefined) {
+			try {
+				closeSync(fileDescriptor);
+			} catch {
+				// Best-effort cleanup after a failed write.
+			}
+		}
+		try {
+			unlinkSync(temporaryPath);
+		} catch {
+			// The rename succeeded, or the temporary file was never created.
+		}
+	}
+}
+
+export type AdvisorPreferencesConfig = {
+	enabled: boolean;
+	provider: string;
+	modelId: string;
+	thinkingLevel: NonNullable<AdvisorPreferencesPatch["thinkingLevel"]>;
+	maxUses: number;
+	cacheRetention: NonNullable<AdvisorPreferencesPatch["cacheRetention"]>;
+	maxTranscriptChars: number;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isPositiveSafeInteger(value: unknown): value is number {
+	return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+
+function parseCacheRetention(value: unknown): AdvisorPreferencesPatch["cacheRetention"] {
+	if (value === "none" || value === "short" || value === "long") return value;
+	return undefined;
+}
+
+function parseThinkingLevel(value: unknown): AdvisorPreferencesPatch["thinkingLevel"] {
+	if (value === "minimal" || value === "low" || value === "medium" || value === "high" || value === "xhigh" || value === "max") {
+		return value;
+	}
+	return undefined;
+}