@anthodev/pi-tools-style 0.1.3 → 0.2.0

package/src/render-decorator.ts

@@ -1,215 +1,196 @@
-import {
-	containsTerminalImage,
-	frameContentWidth,
-	frameLines,
-	trimOuterRules,
-	type FrameOptions,
-} from "./frame.js";
-
-interface Renderable {
-	render(width: number): string[];
-}
-
-type RenderableConstructor<T extends Renderable = Renderable> = abstract new (
-	...args: never[]
-) => T;
-
-type RenderFunction = (this: Renderable, width: number) => string[];
-type DecoratedPrototype = Renderable & Record<symbol, unknown>;
-
-export interface RenderDecoratorConfig<T extends Renderable = Renderable>
-	extends Omit<FrameOptions, "title"> {
-	enabled?: boolean;
-	key: symbol;
-	styleBorderFor?: (
-		instance: T,
-	) => NonNullable<FrameOptions["styleBorder"]>;
-	title?: (instance: T) => string | undefined;
-	trimOuterRules?: boolean;
-}
-
-export type InstallStatus = "already-installed" | "installed" | "unsupported";
-
-interface StoredConfig extends Omit<RenderDecoratorConfig, "enabled"> {
-	enabled: boolean;
-}
-
-interface ResolvedFrameOptions {
-	options: FrameOptions;
-	styleSignature: string | undefined;
-	title: string | undefined;
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, keyHint, keyText, truncateTail } from "@earendil-works/pi-coding-agent";
+import type { Theme, TruncationResult } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import type { Component } from "@earendil-works/pi-tui";
+import { getIconMode, isShellEnabledByConfig } from "./settings.js";
+import type { IconMode } from "./tool-icon.js";
+import { getToolTheme } from "./tool-category.js";
+import { getToolRendererRuntimeState, reportShellIncompatibility } from "./tool-renderer.js";
+import type { ToolLayout, ToolRendererImplementation } from "./tool-renderer.js";
+import type { ToolSnapshot, ToolStatus, ToolView, ToolViewFactory } from "./tool-presentation.js";
+
+export type ShellInstallStatus = "already-installed" | "installed" | "unsupported";
+export interface ShellRendererComponentType { readonly prototype: object; }
+type ShellRender = (this: Component, width: number) => string[];
+type ShellStatus = "running" | "complete" | "error" | "cancelled";
+interface ShellAdapterRecord { originalDescriptor: PropertyDescriptor | undefined; wrapper: ShellRender; }
+interface ShellAdapterRegistry { adapters: WeakMap<object, ShellAdapterRecord>; }
+interface ShellCache {
+	command: string; output: string; status: ShellStatus; expanded: boolean; colorKey: string; outputPad: number;
+	exitCode: number | null | undefined; privateTruncated: boolean | undefined; maxBytes: number | undefined; fullOutputPath: string | undefined;
+	width: number; revision: number; tick: number; mode: IconMode; themeColors: Theme["colors"];
+	themeColorMode: string | undefined; themeAppearance: Theme["appearance"]; cancelKey: string; expandHint: string;
+	factory: ToolViewFactory; layout: ToolRendererImplementation["layoutToolView"];
+	truncation: TruncationResult; view: ToolView; snapshot: ToolSnapshot; prepared: ToolLayout; rows: string[];
 }
-
-interface RenderCacheEntry {
-	config: StoredConfig;
-	output: string[];
-	rendered: readonly string[];
-	styleSignature: string | undefined;
-	title: string | undefined;
-	width: number;
+interface ShellItem { state: Record<string, unknown>; invalidate: () => void; cache?: ShellCache; }
+const SHELL_DECORATOR_KEY = Symbol.for("pi-tools-style:shell-render");
+const OUTPUT_LIMITS = { maxLines: DEFAULT_MAX_LINES, maxBytes: DEFAULT_MAX_BYTES };
+const STATUS: Record<ShellStatus, ToolStatus> = { running: "running", complete: "done", error: "error", cancelled: "cancelled" };
+
+function readRegistry(): ShellAdapterRegistry | undefined {
+	const value: unknown = Reflect.get(globalThis, SHELL_DECORATOR_KEY);
+	return typeof value === "object" && value !== null && Reflect.get(value, "adapters") instanceof WeakMap
+		? value as ShellAdapterRegistry : undefined;
 }
 
-const BORDER_STYLE_PROBE = "╭─╮│╰─╯";
-
-export function installRenderDecorator<T extends Renderable>(
-	component: RenderableConstructor<T>,
-	config: RenderDecoratorConfig<T>,
-): InstallStatus {
-	const prototype = component.prototype as DecoratedPrototype;
-
-	if (prototype[config.key] === true) {
-		storeConfig(config);
-		return "already-installed";
+/** Only BashExecutionComponent.render is adapted; its methods and native child tree stay untouched. */
+export function installShellRenderer(component: ShellRendererComponentType): ShellInstallStatus {
+	try {
+		const prototype = component.prototype;
+		const registry = readRegistry() ?? { adapters: new WeakMap<object, ShellAdapterRecord>() };
+		const installed = registry.adapters.get(prototype);
+		if (installed) return Object.getOwnPropertyDescriptor(prototype, "render")?.value === installed.wrapper ? "already-installed" : "unsupported";
+		const originalDescriptor = Object.getOwnPropertyDescriptor(prototype, "render");
+		const original: unknown = Reflect.get(prototype, "render");
+		if (typeof original !== "function" || typeof Reflect.get(prototype, "getCommand") !== "function" || typeof Reflect.get(prototype, "getOutput") !== "function") return "unsupported";
+		if (originalDescriptor && !("value" in originalDescriptor)) return "unsupported";
+		if (!Reflect.set(globalThis, SHELL_DECORATOR_KEY, registry)) return "unsupported";
+		const wrapper = createShellRenderer(original as ShellRender);
+		Object.defineProperty(prototype, "render", { ...(originalDescriptor ?? { configurable: true, enumerable: false, writable: true }), value: wrapper });
+		registry.adapters.set(prototype, { originalDescriptor, wrapper });
+		return "installed";
+	} catch {
+		return "unsupported";
 	}
-
-	const renderOriginal = resolveOriginalRenderer(prototype);
-	if (!renderOriginal) return "unsupported";
-
-	storeConfig(config);
-
-	Object.defineProperty(prototype, "render", {
-		configurable: true,
-		value: createDecoratedRenderer(config.key, renderOriginal),
-		writable: true,
-	});
-	Object.defineProperty(prototype, config.key, {
-		configurable: false,
-		value: true,
-		writable: false,
-	});
-
-	return "installed";
 }
 
-export function isRenderDecoratorEnabled(key: symbol): boolean {
-	return readConfig(key)?.enabled ?? false;
-}
-
-export function setRenderDecoratorEnabled(key: symbol, enabled: boolean): void {
-	const current = readConfig(key);
-	if (current) Reflect.set(globalThis, key, { ...current, enabled });
-}
-
-function resolveOriginalRenderer(
-	prototype: DecoratedPrototype,
-): RenderFunction | undefined {
-	if (Object.hasOwn(prototype, "render")) {
-		const ownRenderer = prototype.render;
-		return typeof ownRenderer === "function" ? ownRenderer : undefined;
+/** Restore the original own descriptor, or inheritance, only while our wrapper still owns render. */
+export function uninstallShellRenderer(component: ShellRendererComponentType): boolean {
+	try {
+		const registry = readRegistry();
+		const prototype = component.prototype;
+		const installed = registry?.adapters.get(prototype);
+		if (!installed || Object.getOwnPropertyDescriptor(prototype, "render")?.value !== installed.wrapper) return false;
+		if (installed.originalDescriptor) Object.defineProperty(prototype, "render", installed.originalDescriptor);
+		else if (!Reflect.deleteProperty(prototype, "render")) return false;
+		registry!.adapters.delete(prototype);
+		return true;
+	} catch {
+		return false;
 	}
-
-	const parent = Object.getPrototypeOf(prototype) as Renderable | null;
-	if (typeof parent?.render !== "function") return undefined;
-
-	return function renderInherited(width: number): string[] {
-		const currentParent = Object.getPrototypeOf(prototype) as Renderable | null;
-		return typeof currentParent?.render === "function"
-			? currentParent.render.call(this, width)
-			: [];
-	};
 }
 
-function createDecoratedRenderer(
-	key: symbol,
-	renderOriginal: RenderFunction,
-): RenderFunction {
-	const cache = new WeakMap<Renderable, RenderCacheEntry>();
-
-	return function decoratedRender(width: number): string[] {
-		const current = readConfig(key);
-		if (!current?.enabled) return renderOriginal.call(this, width);
-
-		const innerWidth = frameContentWidth(width, current.horizontalPadding);
-		if (innerWidth < 1) return renderOriginal.call(this, width);
-
-		const rendered = renderOriginal.call(this, innerWidth);
-		if (containsTerminalImage(rendered)) {
-			return renderOriginal.call(this, width);
-		}
-
+function createShellRenderer(original: ShellRender): ShellRender {
+	const items = new WeakMap<Component, ShellItem>();
+	return function renderShell(width: number): string[] {
+		const runtime = getToolRendererRuntimeState();
+		if (!runtime.enabled || !isShellEnabledByConfig()) return original.call(this, width);
+		let rows: string[] | undefined;
+		let checkingInternals = false;
 		try {
-			const resolved = resolveFrameOptions(this, current);
-			const cached = cache.get(this);
-			if (
-				cached?.config === current &&
-				cached.width === width &&
-				cached.title === resolved.title &&
-				cached.styleSignature === resolved.styleSignature &&
-				linesEqual(cached.rendered, rendered)
-			) {
-				return cached.output;
+			const implementation = runtime.implementation;
+			const theme = getToolTheme();
+			const outerWidth = Math.floor(width);
+			if (implementation && theme && Number.isFinite(width) && outerWidth >= 5) {
+				checkingInternals = true;
+				const outputPad: unknown = Reflect.get(this, "outputPad");
+				checkingInternals = !(typeof outputPad === "number" && Number.isFinite(outputPad) && outputPad >= 0
+					&& outerWidth < Math.max(5, 3 + 2 * Math.floor(outputPad)));
+				const getCommand: unknown = Reflect.get(this, "getCommand");
+				const getOutput: unknown = Reflect.get(this, "getOutput");
+				const status: unknown = Reflect.get(this, "status");
+				const expanded: unknown = Reflect.get(this, "expanded");
+				const colorKey: unknown = Reflect.get(this, "colorKey");
+				const exitCode: unknown = Reflect.get(this, "exitCode");
+				const fullOutputPath: unknown = Reflect.get(this, "fullOutputPath");
+				const privateTruncation: unknown = Reflect.get(this, "truncationResult");
+				const loader: unknown = Reflect.get(this, "loader");
+				const privateTruncated = typeof privateTruncation === "object" && privateTruncation !== null ? Reflect.get(privateTruncation, "truncated") as unknown : undefined;
+				const maxBytes = typeof privateTruncation === "object" && privateTruncation !== null ? Reflect.get(privateTruncation, "maxBytes") as unknown : undefined;
+				const compatible = typeof getCommand === "function" && typeof getOutput === "function"
+					&& (status === "running" || status === "complete" || status === "error" || status === "cancelled")
+					&& typeof expanded === "boolean" && (colorKey === "dim" || colorKey === "bashMode")
+					&& typeof outputPad === "number" && Number.isFinite(outputPad) && outputPad >= 0
+					&& (exitCode === undefined || exitCode === null || (typeof exitCode === "number" && Number.isFinite(exitCode)))
+					&& (fullOutputPath === undefined || typeof fullOutputPath === "string")
+					&& (privateTruncation === undefined || (typeof privateTruncation === "object" && privateTruncation !== null && !Array.isArray(privateTruncation)))
+					&& (privateTruncated === undefined || typeof privateTruncated === "boolean")
+					&& (maxBytes === undefined || (typeof maxBytes === "number" && Number.isFinite(maxBytes) && maxBytes >= 0))
+					&& (status !== "running" || (typeof loader === "object" && loader !== null && typeof Reflect.get(loader, "render") === "function"));
+				if (!compatible && checkingInternals) {
+					checkingInternals = false;
+					reportShellIncompatibility();
+				}
+				if (compatible && checkingInternals) {
+					const command: unknown = getCommand.call(this);
+					const output: unknown = getOutput.call(this);
+					checkingInternals = false;
+					if (typeof command !== "string" || typeof output !== "string") reportShellIncompatibility();
+					if (typeof command === "string" && typeof output === "string") {
+						const themeColors = theme.colors;
+						const themeColorMode = theme.getColorMode?.();
+						const themeAppearance = theme.appearance;
+						const cancelKey = keyText("tui.select.cancel");
+						const expandHint = keyHint("app.tools.expand", "to expand");
+						let item = items.get(this);
+						if (!item) { item = { state: {}, invalidate: () => this.invalidate() }; items.set(this, item); }
+						const cache = item.cache;
+						const mode = getIconMode();
+						const tick = status === "running" && mode !== "off" ? Math.floor(Date.now() / 80) : 0;
+						if (cache && cache.command === command && cache.output === output && cache.status === status && cache.expanded === expanded
+							&& cache.colorKey === colorKey && cache.outputPad === outputPad && cache.exitCode === exitCode
+							&& cache.privateTruncated === privateTruncated && cache.maxBytes === maxBytes && cache.fullOutputPath === fullOutputPath
+							&& cache.revision === runtime.revision && cache.mode === mode && cache.themeColors === themeColors
+							&& cache.themeColorMode === themeColorMode && cache.themeAppearance === themeAppearance
+							&& cache.cancelKey === cancelKey && cache.expandHint === expandHint
+							&& cache.factory === implementation.createToolView && cache.layout === implementation.layoutToolView) {
+							if (cache.width === outerWidth && cache.tick === tick) return cache.rows;
+							if (cache.width === outerWidth && cache.prepared.refreshHeader) {
+								cache.prepared.refreshHeader(tick);
+								cache.rows[0] = cache.prepared.callRows[0]!;
+								cache.tick = tick;
+								return cache.rows;
+							}
+							// Resize or an implementation without a prepared header still uses the complete layout.
+							const layout = implementation.layoutToolView(cache.view, cache.snapshot, theme, outerWidth, tick);
+							cache.rows = layout.callRows.concat(layout.resultRows);
+							cache.prepared = layout;
+							cache.width = outerWidth;
+							cache.tick = tick;
+							return cache.rows;
+						}
+						const truncation = cache?.output === output ? cache.truncation : truncateTail(output, OUTPUT_LIMITS);
+						const args = { command };
+						const snapshot: ToolSnapshot = {
+							args, presentation: "builtin",
+							result: { content: [{ type: "text", text: truncation.content }], details: {
+								truncation: { truncated: privateTruncated === true || truncation.truncated, maxBytes: truncation.truncated ? truncation.maxBytes : maxBytes ?? truncation.maxBytes },
+								...(fullOutputPath !== undefined ? { fullOutputPath } : {}),
+							} },
+							// Direct !/!! executions have no public tool-call identity or recorded duration.
+							context: { args, toolCallId: "", state: item.state, lastComponent: undefined, invalidate: item.invalidate,
+								cwd: process.cwd(), argsComplete: true, executionStarted: true, isPartial: status === "running",
+								expanded, isError: status === "error", showImages: false, outputPad, durationMs: undefined },
+						};
+						const view = implementation.createToolView("bash", snapshot, theme);
+						let meta = view.head.meta;
+						if (colorKey === "dim" || status === "cancelled" || (status === "error" && typeof exitCode === "number")) {
+							const extra = [...meta];
+							if (colorKey === "dim") extra.push("!! · excluded from context");
+							if (status === "cancelled") extra.push("cancelled");
+							else if (status === "error" && typeof exitCode === "number") extra.push(`exit ${exitCode}`);
+							meta = extra;
+						}
+						const viewForShell: ToolView = { ...view, head: { title: "Shell", target: view.head.target, status: STATUS[status], meta },
+							...(status === "cancelled" ? { tone: "warning" } : {}),
+							sections: status === "running" ? [...view.sections, { slot: "result", preview: false,
+								component: new Text(theme.fg("muted", `Running... (${cancelKey} to cancel)`), 0, 0) }] : view.sections,
+						};
+						const layout = implementation.layoutToolView(viewForShell, snapshot, theme, outerWidth, tick);
+						const renderedRows = layout.callRows.concat(layout.resultRows);
+						rows = renderedRows;
+						item.cache = { command, output, status, expanded, colorKey, outputPad, exitCode, privateTruncated, maxBytes, fullOutputPath,
+							width: outerWidth, revision: runtime.revision, tick, mode, themeColors, factory: implementation.createToolView, layout: implementation.layoutToolView,
+							themeColorMode, themeAppearance, cancelKey, expandHint,
+							truncation, view: viewForShell, snapshot, prepared: layout, rows: renderedRows };
+					}
+				}
 			}
-
-			const output = decorateLines(rendered, width, current, resolved.options);
-			cache.set(this, {
-				config: current,
-				output,
-				rendered: [...rendered],
-				styleSignature: resolved.styleSignature,
-				title: resolved.title,
-				width,
-			});
-			return output;
 		} catch {
-			return renderOriginal.call(this, width);
+			if (checkingInternals) reportShellIncompatibility();
+			// Native rendering is deliberately outside this try: its errors must not trigger a second call.
 		}
+		return rows ?? original.call(this, width);
 	};
 }
-
-function resolveFrameOptions(
-	instance: Renderable,
-	config: StoredConfig,
-): ResolvedFrameOptions {
-	const title = config.title?.(instance);
-	const options: FrameOptions = {};
-
-	if (config.horizontalPadding !== undefined) {
-		options.horizontalPadding = config.horizontalPadding;
-	}
-	const styleBorder = config.styleBorderFor?.(instance) ?? config.styleBorder;
-	if (styleBorder !== undefined) {
-		options.styleBorder = styleBorder;
-	}
-	if (title) options.title = title;
-
-	return {
-		options,
-		// Theme providers can change border output without changing component content.
-		styleSignature: styleBorder?.(BORDER_STYLE_PROBE),
-		title,
-	};
-}
-
-function decorateLines(
-	rendered: readonly string[],
-	width: number,
-	config: StoredConfig,
-	options: FrameOptions,
-): string[] {
-	const lines = config.trimOuterRules
-		? trimOuterRules(rendered)
-		: [...rendered];
-
-	return frameLines(lines, width, options);
-}
-
-function linesEqual(left: readonly string[], right: readonly string[]): boolean {
-	return (
-		left.length === right.length &&
-		left.every((line, index) => line === right[index])
-	);
-}
-
-function storeConfig<T extends Renderable>(
-	config: RenderDecoratorConfig<T>,
-): void {
-	const stored: StoredConfig = {
-		...config,
-		enabled: config.enabled ?? true,
-	} as StoredConfig;
-	Reflect.set(globalThis, config.key, stored);
-}
-
-function readConfig(key: symbol): StoredConfig | undefined {
-	return Reflect.get(globalThis, key) as StoredConfig | undefined;
-}

package/src/settings.ts

@@ -1,65 +1,237 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
 import type { IconMode } from "./tool-icon.js";
 
-interface ToolsStyleSettings {
-	iconMode: IconMode;
+export interface ToolsStyleSettings {
+	readonly enabled: boolean;
+	readonly iconMode: IconMode;
+	readonly webSearchTools: readonly string[];
+	readonly shellEnabled: boolean;
+	readonly tools: Readonly<Record<string, boolean>>;
+}
+
+export interface ToolsStyleSettingsPatch {
+	readonly enabled?: boolean;
+	readonly iconMode?: IconMode;
+	readonly webSearchTools?: readonly string[];
+	readonly shellEnabled?: boolean;
+	readonly tools?: Readonly<Record<string, boolean>>;
+}
+
+interface SettingsStore {
+	value: Readonly<ToolsStyleSettings>;
+	writerTail: Promise<void>;
+	mutationSequence: number;
 }
 
 const SETTINGS_KEY = Symbol.for("pi-tools-style:settings");
-const DEFAULT_SETTINGS: Readonly<ToolsStyleSettings> = {
+const DEFAULT_SETTINGS: Readonly<ToolsStyleSettings> = Object.freeze({
+	enabled: true,
 	iconMode: "ascii",
-};
+	webSearchTools: Object.freeze([] as string[]),
+	shellEnabled: true,
+	tools: Object.freeze(Object.create(null) as Record<string, boolean>),
+});
+let trustedStore: SettingsStore | undefined;
 
 export function getIconMode(): IconMode {
 	return getSettings().iconMode;
 }
 
+export function getWebSearchTools(): readonly string[] {
+	return getSettings().webSearchTools;
+}
+
+export function getSettings(): Readonly<ToolsStyleSettings> {
+	return getStore().value;
+}
+
+export function isToolEnabledByConfig(toolName: string): boolean {
+	const tools = getSettings().tools;
+	return Object.hasOwn(tools, toolName) ? tools[toolName] === true : true;
+}
+
+export function isShellEnabledByConfig(): boolean {
+	return getSettings().shellEnabled;
+}
+
 export function setIconMode(iconMode: IconMode): void {
-	Reflect.set(globalThis, SETTINGS_KEY, {
-		iconMode,
-	} satisfies ToolsStyleSettings);
+	applyPatch(getStore(), { iconMode });
 }
 
-export async function loadSettings(path = getSettingsPath()): Promise<void> {
-	setIconMode(DEFAULT_SETTINGS.iconMode);
+export function loadSettings(path = getSettingsPath()): Promise<void> {
+	const store = getStore();
+	const mutationSequence = store.mutationSequence;
+	return enqueue(store, async () => {
+		let value = DEFAULT_SETTINGS;
+		try {
+			value = normalizeSettings(JSON.parse(await readFile(path, "utf8")));
+		} catch {
+			// Missing or malformed user config intentionally falls back to defaults.
+		}
+		if (store.mutationSequence === mutationSequence) store.value = value;
+	});
+}
 
-	try {
-		const parsed = JSON.parse(await readFile(path, "utf8")) as {
-			iconMode?: unknown;
-		};
-		if (isIconMode(parsed.iconMode)) setIconMode(parsed.iconMode);
-	} catch {
-		// Missing or malformed user config intentionally falls back to ASCII.
-	}
+export function saveSettings(
+	patch: ToolsStyleSettingsPatch,
+	path = getSettingsPath(),
+): Promise<void> {
+	const store = getStore();
+	const snapshot = applyPatch(store, patch);
+	return enqueue(store, () => persistSettings(snapshot, path));
 }
 
-export async function saveIconMode(
+export function saveIconMode(
 	iconMode: IconMode,
 	path = getSettingsPath(),
 ): Promise<void> {
-	await mkdir(dirname(path), { recursive: true });
-	await writeFile(path, `${JSON.stringify({ iconMode }, null, 2)}\n`, "utf8");
-	setIconMode(iconMode);
+	return saveSettings({ iconMode }, path);
+}
+
+export function flushSettingsWrites(): Promise<void> {
+	return getStore().writerTail;
 }
 
 function getSettingsPath(): string {
 	return join(getAgentDir(), "config", "tools-style.json");
 }
 
-function getSettings(): ToolsStyleSettings {
-	const current = Reflect.get(globalThis, SETTINGS_KEY) as
-		| ToolsStyleSettings
-		| undefined;
-	if (current) return current;
+function getStore(): SettingsStore {
+	const current: unknown = Reflect.get(globalThis, SETTINGS_KEY);
+	if (trustedStore && current === trustedStore) return trustedStore;
 
-	const initial = { ...DEFAULT_SETTINGS };
-	Reflect.set(globalThis, SETTINGS_KEY, initial);
-	return initial;
+	const candidate = typeof current === "object" && current !== null
+		? current as Partial<SettingsStore>
+		: undefined;
+	if (
+		candidate &&
+		typeof candidate.value === "object" &&
+		candidate.value !== null &&
+		!Array.isArray(candidate.value) &&
+		candidate.writerTail instanceof Promise &&
+		typeof candidate.mutationSequence === "number" &&
+		Number.isSafeInteger(candidate.mutationSequence) &&
+		candidate.mutationSequence >= 0
+	) {
+		// A reloaded module joins the existing queue, normalizing its value once.
+		trustedStore = candidate as SettingsStore;
+		trustedStore.value = normalizeSettings(trustedStore.value);
+	} else {
+		// Repair an absent, legacy direct settings object or foreign runtime value.
+		trustedStore = {
+			value: normalizeSettings(current),
+			writerTail: Promise.resolve(),
+			mutationSequence: 0,
+		};
+		Reflect.set(globalThis, SETTINGS_KEY, trustedStore);
+	}
+	return trustedStore;
+}
+
+function enqueue(store: SettingsStore, operation: () => Promise<void>): Promise<void> {
+	const pending = store.writerTail.then(operation);
+	// Return this write's rejection, but never poison subsequent queued operations.
+	store.writerTail = pending.catch(() => {});
+	return pending;
+}
+
+function applyPatch(
+	store: SettingsStore,
+	patch: ToolsStyleSettingsPatch,
+): Readonly<ToolsStyleSettings> {
+	const current = store.value;
+	const enabled = ownValue(patch, "enabled");
+	const iconMode = ownValue(patch, "iconMode");
+	const webSearchTools = ownValue(patch, "webSearchTools");
+	const shellEnabled = ownValue(patch, "shellEnabled");
+	const tools = ownValue(patch, "tools");
+	const value: Readonly<ToolsStyleSettings> = Object.freeze({
+		enabled: typeof enabled === "boolean" ? enabled : current.enabled,
+		iconMode: isIconMode(iconMode) ? iconMode : current.iconMode,
+		webSearchTools: Array.isArray(webSearchTools)
+			? normalizeWebSearchTools(webSearchTools)
+			: current.webSearchTools,
+		shellEnabled: typeof shellEnabled === "boolean" ? shellEnabled : current.shellEnabled,
+		tools: typeof tools === "object" && tools !== null && !Array.isArray(tools)
+			? normalizeTools(tools, current.tools)
+			: current.tools,
+	});
+	store.value = value;
+	store.mutationSequence++;
+	return value;
+}
+
+async function persistSettings(settings: Readonly<ToolsStyleSettings>, path: string): Promise<void> {
+	await mkdir(dirname(path), { recursive: true });
+	const temporary = `${path}.${randomUUID()}.tmp`;
+	let writeCompleted = false;
+	try {
+		await writeFile(temporary, `${JSON.stringify(settings, null, 2)}\n`, {
+			encoding: "utf8",
+			flag: "wx",
+		});
+		writeCompleted = true;
+		await rename(temporary, path);
+	} catch (error) {
+		// An exclusive-create collision is not our file; later rename failures are.
+		const occupied = !writeCompleted && typeof error === "object" && error !== null &&
+			"code" in error && error.code === "EEXIST";
+		if (!occupied) {
+			try {
+				await unlink(temporary);
+			} catch {
+				// Cleanup must not replace the original write/rename failure.
+			}
+		}
+		throw error;
+	}
+}
+
+function normalizeSettings(value: unknown): Readonly<ToolsStyleSettings> {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return DEFAULT_SETTINGS;
+	const enabled = ownValue(value, "enabled");
+	const iconMode = ownValue(value, "iconMode");
+	const shellEnabled = ownValue(value, "shellEnabled");
+	return Object.freeze({
+		enabled: typeof enabled === "boolean" ? enabled : DEFAULT_SETTINGS.enabled,
+		iconMode: isIconMode(iconMode) ? iconMode : DEFAULT_SETTINGS.iconMode,
+		webSearchTools: normalizeWebSearchTools(ownValue(value, "webSearchTools")),
+		shellEnabled: typeof shellEnabled === "boolean" ? shellEnabled : DEFAULT_SETTINGS.shellEnabled,
+		tools: normalizeTools(ownValue(value, "tools")),
+	});
+}
+
+function ownValue(value: unknown, key: string): unknown {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+	const record = value as Record<string, unknown>;
+	return Object.hasOwn(record, key) ? record[key] : undefined;
+}
+
+function normalizeTools(
+	value: unknown,
+	base?: Readonly<Record<string, boolean>>,
+): Readonly<Record<string, boolean>> {
+	const tools = Object.assign(Object.create(null) as Record<string, boolean>, base);
+	if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+		for (const [name, enabled] of Object.entries(value)) {
+			if (name.length > 0 && typeof enabled === "boolean") tools[name] = enabled;
+		}
+	}
+	return Object.freeze(tools);
 }
 
 export function isIconMode(value: unknown): value is IconMode {
 	return value === "ascii" || value === "nerd-font" || value === "off";
 }
+
+
+function normalizeWebSearchTools(value: unknown): readonly string[] {
+	if (!Array.isArray(value)) return DEFAULT_SETTINGS.webSearchTools;
+	return Object.freeze(value.filter(
+		(entry): entry is string => typeof entry === "string" && entry.length > 0,
+	));
+}