@oh-my-pi/pi-tui 18.9.2 → 18.10.1

package/src/debug-server.ts

@@ -1,5 +1,4 @@
-import { existsSync, unlinkSync } from "node:fs";
-import { createServer, type Server, type Socket } from "node:net";
+import { type IpcConnection, IpcServer } from "@oh-my-pi/pi-natives";
 import { type Component, isFocusable, type OverlayOptions, type TUI } from "./tui";
 import { plainText } from "./native/spans";
 
@@ -209,72 +208,60 @@ function mouseSequence(x: number, y: number, action: string): string {
 export class TuiDebugServer {
 	readonly #tui: TUI;
 	readonly #path: string;
-	#server: Server | undefined;
-	#sockets = new Set<Socket>();
+	#server: IpcServer | undefined;
+	#listening: Promise<boolean> | undefined;
+	#stopped = false;
+	#connections = new Set<IpcConnection>();
 
 	constructor(tui: TUI, path: string) {
 		this.#tui = tui;
 		this.#path = path;
 	}
 
+	/** Resolves true once the socket accepts connections, false if listen failed or the server stopped first. */
+	get ready(): Promise<boolean> {
+		return this.#listening ?? Promise.resolve(false);
+	}
+
 	start(): void {
-		if (this.#server !== undefined) return;
-		try {
-			if (existsSync(this.#path)) unlinkSync(this.#path);
-		} catch {
-			// The listen error below is isolated from the host application.
-		}
-		const server = createServer(socket => this.#accept(socket));
-		this.#server = server;
-		server.on("error", error => {
-			void error;
-		});
-		try {
-			server.listen(this.#path);
-		} catch {
-			this.#server = undefined;
-			server.close();
-		}
+		if (this.#listening !== undefined) return;
+		this.#stopped = false;
+		this.#listening = IpcServer.listen(this.#path, { framing: "lines" }, connection => this.#accept(connection)).then(
+			server => {
+				if (this.#stopped) {
+					void server.close().catch(() => {});
+					return false;
+				}
+				this.#server = server;
+				return true;
+			},
+			() => false, // A live peer or unusable path disables the debug socket; the host application is unaffected.
+		);
 	}
 
 	stop(): void {
+		this.#stopped = true;
 		const server = this.#server;
 		this.#server = undefined;
-		for (const socket of this.#sockets) socket.destroy();
-		this.#sockets.clear();
-		try {
-			server?.close();
-		} catch {
-			// A failed or already-closed listener still needs its stale path removed.
-		}
-		try {
-			if (existsSync(this.#path)) unlinkSync(this.#path);
-		} catch {
-			// Teardown must not affect the host application.
-		}
+		this.#listening = undefined;
+		for (const connection of this.#connections) connection.destroy();
+		this.#connections.clear();
+		void server?.close().catch(() => {});
 	}
 
-	#accept(socket: Socket): void {
-		this.#sockets.add(socket);
-		let buffer = "";
-		socket.setEncoding("utf8");
-		socket.on("data", chunk => {
-			buffer += chunk;
-			let newline = buffer.indexOf("\n");
-			while (newline !== -1) {
-				const line = buffer.slice(0, newline).replace(/\r$/, "");
-				buffer = buffer.slice(newline + 1);
-				if (line.length > 0) this.#handleLine(socket, line);
-				newline = buffer.indexOf("\n");
-			}
-		});
-		socket.on("error", error => {
-			void error;
-		});
-		socket.on("close", () => this.#sockets.delete(socket));
+	#accept(connection: IpcConnection): void {
+		if (this.#stopped) {
+			connection.destroy();
+			return;
+		}
+		this.#connections.add(connection);
+		connection.start(
+			line => void this.#handleLine(connection, line),
+			() => this.#connections.delete(connection),
+		);
 	}
 
-	#handleLine(socket: Socket, line: string): void {
+	async #handleLine(connection: IpcConnection, line: string): Promise<void> {
 		let request: DebugRequest;
 		try {
 			const parsed: unknown = JSON.parse(line);
@@ -282,36 +269,31 @@ export class TuiDebugServer {
 				throw new Error("request must be an object");
 			request = parsed as DebugRequest;
 		} catch (error) {
-			this.#write(socket, { ok: false, error: `malformed JSON: ${errorMessage(error)}` });
+			this.#write(connection, { ok: false, error: `malformed JSON: ${errorMessage(error)}` });
 			return;
 		}
+		let response: DebugResponse;
 		try {
-			const response = this.#dispatch(request);
-			if (request.op === "quit" && response.ok) {
-				this.#write(socket, response, () => {
-					this.#tui.stop();
-					process.exit(0);
-				});
-				return;
-			}
-			this.#write(socket, response);
+			response = this.#dispatch(request);
 		} catch (error) {
-			this.#write(socket, { ok: false, error: errorMessage(error) });
+			response = { ok: false, error: errorMessage(error) };
+		}
+		this.#write(connection, response);
+		if (request.op === "quit" && response.ok) {
+			await connection.drained();
+			this.#tui.stop();
+			process.exit(0);
 		}
 	}
 
-	#write(socket: Socket, response: DebugResponse, flushed?: () => void): void {
+	#write(connection: IpcConnection, response: DebugResponse): void {
 		let line: string;
 		try {
 			line = JSON.stringify(response);
 		} catch (error) {
 			line = JSON.stringify({ ok: false, error: errorMessage(error) });
 		}
-		try {
-			socket.write(`${line}\n`, flushed);
-		} catch {
-			// Broken clients cannot affect the TUI.
-		}
+		connection.send(line);
 	}
 
 	#dispatch(request: DebugRequest): DebugResponse {

package/src/hotkeys-markdown.ts

@@ -135,6 +135,7 @@ function hotkeyGroups(bindings: HotkeysMarkdownBindings): HotkeyGroup[] {
 				{ keys: [act("app.history.search")], action: "Search prompt history" },
 				{ keys: [act("app.tools.expand")], action: "Toggle tool output expansion" },
 				{ keys: [act("app.tools.toggleVisibility")], action: "Toggle tool activity visibility" },
+				{ keys: [act("app.ask.hide")], action: "Hide/show a pending ask question" },
 				{ keys: [act("app.thinking.toggle")], action: "Toggle thinking block visibility" },
 				{ keys: [act("app.editor.external")], action: "Edit message in external editor" },
 				{ keys: [act("app.retry")], action: "Retry last failed assistant turn" },

package/src/native/reconcile.ts

@@ -405,13 +405,31 @@ export class Reconciler {
 		return this.#findEditorIn(node, state.id, "", state.owner, depth);
 	}
 
-	#findEditorIn(node: NativeNode, id: string, keypath: string, owner: Owner, depth: number): string | null {
+	/**
+	 * The first editor under `node`. An `overlay`/`picker` child outside a hoisted
+	 * sheet is hoisted into `layer` under its `^` keypath (see {@link #entries}), so
+	 * a field in a sheet a dock component describes is found under that id.
+	 */
+	#findEditorIn(
+		node: NativeNode,
+		id: string,
+		keypath: string,
+		owner: Owner,
+		depth: number,
+		hoist = true,
+	): string | null {
 		if (node.k === "editor" || node.k === "input") return id;
-		for (const entry of this.#entries(node.c, keypath, owner, true, null)) {
-			const found =
-				entry.comp === undefined
-					? this.#findEditorIn(entry.node, entry.id, entry.keypath, owner, depth)
-					: this.#findEditorOf(entry.comp, depth + 1);
+		for (const entry of this.#entries(node.c, keypath, owner, false, null)) {
+			let found: string | null;
+			if (entry.comp !== undefined) {
+				found = this.#findEditorOf(entry.comp, depth + 1);
+			} else if (hoist && (entry.node.k === "overlay" || entry.node.k === "picker")) {
+				const path = entry.keypath;
+				const portalPath = keypath === "" ? `^${path}` : `${keypath}/^${path.slice(keypath.length + 1)}`;
+				found = this.#findEditorIn(entry.node, nodeId(owner.base, portalPath), portalPath, owner, depth, false);
+			} else {
+				found = this.#findEditorIn(entry.node, entry.id, entry.keypath, owner, depth, hoist);
+			}
 			if (found !== null) return found;
 		}
 		return null;

package/src/overlays/advisor-config.ts

@@ -34,7 +34,16 @@ import { sanitizeDisplayWarnings } from "../render/render-utils";
 import { formatKeyHint } from "../app-keybindings";
 import { editorKey, editorKeys } from "../chrome/keybinding-hints";
 import { HookEditorComponent } from "./hook-editor";
-import { buildBrowserItems, ModelBrowser, type ModelBrowserSource, sortModelItems } from "./model-browser";
+import {
+	buildBrowserItems,
+	MODEL_PICKER_COLUMNS,
+	ModelBrowser,
+	type ModelBrowserItem,
+	type ModelBrowserSource,
+	type ModelPickerCatalogue,
+	type ModelPickerOrder,
+	sortModelItems,
+} from "./model-browser";
 import { bottomBorder, divider, dividerSplit, PanelRows, row, topBorder, topBorderSplit } from "../chrome/overlay-box";
 import { isLayoutMouseRoutable } from "../components/layout/geometry";
 import { SplitPane } from "../components/layout/split-pane";
@@ -42,7 +51,16 @@ import { Stack } from "../components/layout/stack";
 import type { TspPrefsProps, TspPrefsRow, TspSpan } from "@oh-my-pi/pi-wire";
 import { col, node, span, text } from "../native/describe";
 import type { DescribeContext, NativeChild, NativeNode, NativeUiEvent } from "../native/node";
-import { actionHint, hintsRow, type NativeHint, overlayCard } from "../native/overlay";
+import { actionBar, actionButton, actionHint, hintsRow, type NativeHint, overlayCard } from "../native/overlay";
+import {
+	CLOSE_ACTION,
+	pickerAction,
+	pickerEvent,
+	routeSelectListPicker,
+	type SelectPickerOptions,
+	selectListPicker,
+} from "../native/picker";
+import { getThinkingLevelMetadata, parseThinkingLevel } from "../thinking";
 
 export const ADVISOR_REVIEW_MODES = ["turn", "agent-end"] as const;
 export const ADVISOR_SYNC_BACKLOG_MODES = ["off", "1", "3", "5", "strict"] as const;
@@ -205,6 +223,40 @@ function formatAdvisorTools(tools: readonly string[] | undefined, emptyLabel: st
 /** Choice value for "no per-advisor override"; matches no {@link ADVISOR_SYNC_BACKLOG_MODES} entry. */
 const SYNC_BACKLOG_INHERIT = "inherit";
 
+/** The tools list's terminal-only "Done" row; the picker applies with its own action instead. */
+const TOOLS_DONE = "__done";
+
+/**
+ * A picker editor as a component of its own: a component's root picker stays
+ * where it is described, the prefs page's editor slot, where a picker
+ * described inside the page would be hoisted into `layer` under the sheet.
+ */
+class EditorSheet implements Component {
+	node: NativeNode | undefined;
+	readonly #route: (event: NativeUiEvent) => void;
+
+	constructor(route: (event: NativeUiEvent) => void) {
+		this.#route = route;
+	}
+
+	render(): readonly string[] {
+		return [];
+	}
+
+	describe(): NativeNode | null {
+		return this.node ?? null;
+	}
+
+	handleNativeEvent(event: NativeUiEvent): void {
+		this.#route(event);
+	}
+}
+
+/** Whether two memo dependency lists hold the same values by identity. */
+function sameDeps(a: readonly unknown[], b: readonly unknown[]): boolean {
+	return a.length === b.length && a.every((value, i) => value === b[i]);
+}
+
 /** One-line cadence label: mode plus interval. */
 function formatReviewCadence(advisor: AdvisorConfig): string {
 	const reviewInterval = advisor.reviewInterval ?? 1;
@@ -297,7 +349,15 @@ export class AdvisorConfigOverlayComponent implements Component {
 
 	/** The advisor the detail screen (and its editors) edits; -1 on the roster or the shared instructions. */
 	#detailIndex = -1;
-	#nativePrefs: { signature: string; editor: Component | undefined; node: NativeNode } | undefined;
+	#nativePrefs: { signature: string; editor: NativeNode | undefined; node: NativeNode } | undefined;
+	/** The editor over the prefs page, rebuilt only when one of `deps` changes identity. */
+	#nativeEditor: { deps: readonly unknown[]; node: NativeNode } | undefined;
+	/** The model screen's catalogue and the advisor's current model among it (picker `current`). */
+	#modelItems: ModelBrowserItem[] = [];
+	#modelCurrent: string | undefined;
+	/** Picker sheet options of the current list screen (thinking, review mode, sync backlog, tools). */
+	#sheetOptions: SelectPickerOptions | undefined;
+	readonly #editorSheet = new EditorSheet(event => this.#routeEditorPicker(event));
 	#screen: Screen = "list";
 	/** The interactive element for the current screen. */
 	#active: Component = new SelectList([], 1, getSelectListTheme());
@@ -587,7 +647,7 @@ export class AdvisorConfigOverlayComponent implements Component {
 			this.#screen === "sync-backlog" ||
 			this.#screen === "tools" ||
 			this.#screen === "instructions";
-		const editor = overlay ? this.#active : undefined;
+		const editor = overlay ? this.#prefsEditor() : undefined;
 		const focus =
 			this.#screen === "detail" && this.#active instanceof SelectList
 				? (this.#active.getSelectedItem()?.value ?? null)
@@ -606,12 +666,137 @@ export class AdvisorConfigOverlayComponent implements Component {
 		const signature = JSON.stringify(props);
 		const prev = this.#nativePrefs;
 		if (prev && prev.signature === signature && prev.editor === editor) return prev.node;
-		const children: NativeChild[] = editor ? [col([editor], { role: "omp.prefs.editor" })] : [];
+		let children: NativeChild[] = [];
+		if (editor?.k === "picker") {
+			this.#editorSheet.node = editor;
+			children = [this.#editorSheet];
+		} else if (editor) {
+			children = [editor];
+		}
 		const root = node("prefs", props, children);
 		this.#nativePrefs = { signature, editor, node: root };
 		return root;
 	}
 
+	/**
+	 * The editor over the prefs page. Choices are picker sheets on `/model`'s
+	 * anatomy (search, rows, the highlighted model's facts, one primary
+	 * action); the instructions and review-interval editors sit in the page's
+	 * editor card.
+	 */
+	#prefsEditor(): NativeNode {
+		const active = this.#active;
+		const memo = this.#nativeEditor;
+		if (active instanceof ModelBrowser) {
+			const order = active.pickerOrder({ providers: false, rest: active.query.trim() ? "Matches" : "All" });
+			const catalogue = active.pickerItems(this.#modelItems);
+			const preview = active.pickerPreview("compact", this.#modelCurrent);
+			const deps = [active, order, catalogue, preview, active.query, active.cursor, active.pickerSelected];
+			if (memo && sameDeps(memo.deps, deps)) return memo.node;
+			const sheet = this.#modelSheet(active, order, catalogue, preview);
+			this.#nativeEditor = { deps, node: sheet };
+			return sheet;
+		}
+		const options = this.#sheetOptions;
+		if (active instanceof SelectList && options) {
+			const view = active.pickerView();
+			const deps = [active, view.items, view.selected, view.pending, view.query, view.cursor];
+			if (memo && sameDeps(memo.deps, deps)) return memo.node;
+			const props = selectListPicker(active, options);
+			const sheet = node(
+				"picker",
+				this.#screen === "tools"
+					? {
+							...props,
+							items: props.items?.filter(item => item.id !== TOOLS_DONE),
+							actions: [
+								pickerAction("confirm", "Toggle", "enter"),
+								pickerAction("apply", "Apply", "escape", { primary: true, end: true }),
+							],
+						}
+					: props,
+			);
+			this.#nativeEditor = { deps, node: sheet };
+			return sheet;
+		}
+		if (memo && sameDeps(memo.deps, [active])) return memo.node;
+		const content = this.#screen === "review-interval" ? this.#intervalCard(active) : active;
+		const card = col([content], { role: "omp.prefs.editor" });
+		this.#nativeEditor = { deps: [active], node: card };
+		return card;
+	}
+
+	#modelSheet(
+		browser: ModelBrowser,
+		order: ModelPickerOrder,
+		catalogue: ModelPickerCatalogue,
+		preview: readonly NativeChild[],
+	): NativeNode {
+		const name = this.#doc.advisors[this.#detailIndex]?.name || "This advisor";
+		const fallback = this.#defaultModelLabel ?? "the advisor role default";
+		return node(
+			"picker",
+			{
+				title: "Advisor model",
+				subtitle: `${name} reviews with this model. Unset, it uses ${fallback}.`,
+				icon: "model",
+				noun: "models",
+				size: "md",
+				layout: "rows",
+				preview: "below",
+				query: browser.query,
+				cursor: browser.cursor,
+				placeholder: "Search models…",
+				columns: MODEL_PICKER_COLUMNS,
+				...catalogue,
+				order: order.order,
+				...(order.hits ? { hits: order.hits } : {}),
+				selected: browser.pickerSelected,
+				...(this.#modelCurrent ? { current: [this.#modelCurrent] } : {}),
+				total: browser.baseCount,
+				empty: "No models available",
+				actions: [
+					pickerAction("use", "Use for advisor", "enter", { primary: true }),
+					browser.query.length > 0 ? { ...CLOSE_ACTION, label: "Clear search" } : CLOSE_ACTION,
+				],
+			},
+			preview,
+		);
+	}
+
+	/** The review-interval field as a titled card: what the number means, the field, Cancel and Save. */
+	#intervalCard(input: Component): NativeNode {
+		const name = this.#doc.advisors[this.#detailIndex]?.name || "this advisor";
+		return overlayCard("omp.overlay.advisor.interval", `Review interval · ${name}`, [
+			text([span("Review every Nth eligible update; skipped updates join the next review.", "muted")], {
+				wrap: "word",
+			}),
+			input,
+			actionBar([
+				null,
+				actionButton("Cancel", "field-cancel", { keys: "escape" }),
+				actionButton("Save", "field-save", { keys: "enter", tone: "accent" }),
+			]),
+		]);
+	}
+
+	/** A pointer event on the editor's picker sheet, on the path of the key it stands for. */
+	#routeEditorPicker(event: NativeUiEvent): void {
+		const picked = pickerEvent(event);
+		if (!picked) return;
+		const active = this.#active;
+		if (active instanceof ModelBrowser) {
+			if (picked.kind !== "action") active.routePickerItem(picked.item, picked.kind === "activate");
+			else if (picked.act === "close") active.handleCancel();
+			else if (picked.act === "use" && active.pickerSelected) active.routePickerItem(active.pickerSelected, true);
+		} else if (active instanceof SelectList) {
+			// The tools list applies on cancel, like its Esc.
+			if (picked.kind === "action" && picked.act === "apply") active.onCancel?.();
+			else routeSelectListPicker(active, event);
+		}
+		this.#cb.requestRender();
+	}
+
 	/**
 	 * Native page events, each through the roster/detail selections the keys
 	 * make: a page opens that advisor (or the shared instructions), a field
@@ -619,6 +804,14 @@ export class AdvisorConfigOverlayComponent implements Component {
 	 * or the page cancels like Esc.
 	 */
 	handleNativeEvent(event: NativeUiEvent): void {
+		// The review-interval card's buttons, on its Enter and Esc paths.
+		if (event.type === "action" && (event.act === "field-save" || event.act === "field-cancel")) {
+			const input = this.#active;
+			if (!(input instanceof Input)) return;
+			if (event.act === "field-save") input.onSubmit?.(input.getValue());
+			else input.onEscape?.();
+			return;
+		}
 		if (event.key !== "") return;
 		const index = this.#pageIndex();
 		switch (event.type) {
@@ -979,9 +1172,11 @@ export class AdvisorConfigOverlayComponent implements Component {
 
 	// ───────────────────────────── screens ───────────────────────────
 
-	#setScreen(screen: Screen, active: Component, footerHint: string): void {
+	/** `sheet`: how a list screen describes as a picker over the prefs page. */
+	#setScreen(screen: Screen, active: Component, footerHint: string, sheet?: SelectPickerOptions): void {
 		this.#screen = screen;
 		this.#active = active;
+		this.#sheetOptions = sheet;
 		this.#footerHint = footerHint;
 		this.#previewScroll = 0;
 		this.#cb.requestRender();
@@ -1155,6 +1350,8 @@ export class AdvisorConfigOverlayComponent implements Component {
 	}
 
 	#onDetailSelect(index: number, field: string): void {
+		// Editors opened straight from the prefs page edit this advisor too.
+		this.#detailIndex = index;
 		switch (field) {
 			case "toggleEnabled": {
 				const a = this.#doc.advisors[index];
@@ -1232,11 +1429,19 @@ export class AdvisorConfigOverlayComponent implements Component {
 		}
 		const items = buildBrowserItems(models);
 		sortModelItems(items, { mruOrder });
+		// The configured model, whatever thinking suffix it carries, is the picker's current row.
+		const model = this.#doc.advisors[index]?.model?.trim();
+		const current = model
+			? items.find(item => model === item.selector || model.startsWith(`${item.selector}:`))?.selector
+			: undefined;
+		this.#modelItems = items;
+		this.#modelCurrent = current;
 
 		const picker = new ModelBrowser(this.#deps.browserSource, {});
 		picker.setMruOrder(mruOrder);
 		picker.setPerfStats(this.#deps.browserSource.modelPerf);
 		picker.setItems(items);
+		if (current) picker.selectSelector(current);
 		picker.onActivate = item => {
 			const efforts = getSupportedEfforts(item.model);
 			if (efforts.length === 0) {
@@ -1259,6 +1464,11 @@ export class AdvisorConfigOverlayComponent implements Component {
 		const items: SelectItem[] = [{ value: "", label: "(model default thinking)" }];
 		for (const effort of efforts) items.push({ value: effort, label: effort });
 		const list = new SelectList(items, Math.max(1, items.length), getSelectListTheme());
+		// The level the advisor already runs this model at, when it is this model.
+		const model = this.#doc.advisors[index]?.model?.trim();
+		const current =
+			model === selector ? "" : model?.startsWith(`${selector}:`) ? model.slice(selector.length + 1) : undefined;
+		if (current !== undefined) list.setSelectedValue(current);
 		list.onSelect = item => {
 			// Values are supported efforts or the empty model-default choice.
 			this.#doc.advisors[index].model = item.value ? `${selector}:${item.value}` : selector;
@@ -1270,6 +1480,23 @@ export class AdvisorConfigOverlayComponent implements Component {
 			"thinking",
 			list,
 			`Thinking effort for ${selector} · ${editorKey("tui.select.confirm")} / click pick · ${editorKey("tui.select.cancel")} back`,
+			{
+				title: "Thinking level",
+				subtitle: `How hard ${this.#doc.advisors[index]?.name || "the advisor"} reasons on ${selector}.`,
+				icon: "thinking",
+				noun: "levels",
+				current: current === undefined ? [] : [current],
+				confirm: "Use level",
+				decorate: item => {
+					if (!item.value) return { label: "Model default", detail: "No level; the provider decides." };
+					const level = parseThinkingLevel(item.value);
+					const dot = `thinking${item.value.charAt(0).toUpperCase()}${item.value.slice(1)}`;
+					return {
+						detail: level ? getThinkingLevelMetadata(level).description : undefined,
+						chips: [{ text: "", dot }],
+					};
+				},
+			},
 		);
 	}
 	#showReviewModePicker(index: number): void {
@@ -1299,6 +1526,14 @@ export class AdvisorConfigOverlayComponent implements Component {
 			"review-mode",
 			list,
 			`${editorKey("tui.select.confirm")} / click choose review mode · ${editorKey("tui.select.cancel")} back`,
+			{
+				title: "Review mode",
+				subtitle: `When ${advisor.name || "the advisor"} reviews the session.`,
+				icon: "review",
+				noun: "modes",
+				current: [current],
+				decorate: item => ({ label: item.value }),
+			},
 		);
 	}
 
@@ -1361,6 +1596,14 @@ export class AdvisorConfigOverlayComponent implements Component {
 			"sync-backlog",
 			list,
 			`${editorKey("tui.select.confirm")} / click choose catch-up policy · ${editorKey("tui.select.cancel")} back`,
+			{
+				title: "Sync backlog",
+				subtitle: `How long the session waits for ${advisor.name || "the advisor"}'s pending reviews.`,
+				icon: "time",
+				noun: "policies",
+				current: [current ?? SYNC_BACKLOG_INHERIT],
+				decorate: item => ({ label: item.value }),
+			},
 		);
 	}
 
@@ -1370,7 +1613,7 @@ export class AdvisorConfigOverlayComponent implements Component {
 			value: name,
 			label: `${selected.has(name) ? "[x]" : "[ ]"} ${name}`,
 		}));
-		items.push({ value: "__done", label: "Done" });
+		items.push({ value: TOOLS_DONE, label: "Done" });
 		const list = new SelectList(items, Math.max(1, items.length), getSelectListTheme());
 		list.setSelectedIndex(cursor);
 		let cursorIndex = cursor;
@@ -1378,7 +1621,7 @@ export class AdvisorConfigOverlayComponent implements Component {
 			cursorIndex = items.findIndex(i => i.value === item.value);
 		};
 		list.onSelect = item => {
-			if (item.value === "__done") {
+			if (item.value === TOOLS_DONE) {
 				this.#doc.advisors[index].tools = commitTools(selected, all, this.#deps.defaultToolNames);
 				this.#dirty = true;
 				this.#showDetail(index);
@@ -1397,6 +1640,14 @@ export class AdvisorConfigOverlayComponent implements Component {
 			"tools",
 			list,
 			`${editorKey("tui.select.confirm")} / click toggle · select Done or ${editorKey("tui.select.cancel")} to apply (empty = no tools; read/grep/glob = default)`,
+			{
+				title: "Tools",
+				subtitle: `What ${this.#doc.advisors[index]?.name || "the advisor"} may call. None grants no tools; read, grep and glob are the default.`,
+				icon: "tools",
+				noun: "tools",
+				current: [...selected],
+				decorate: item => ({ label: item.value }),
+			},
 		);
 	}