@oh-my-pi/pi-tui 18.4.2 → 18.4.4

package/src/overlays/advisor-config.ts

@@ -39,6 +39,10 @@ import { bottomBorder, divider, dividerSplit, PanelRows, row, topBorder, topBord
 import { isLayoutMouseRoutable } from "../components/layout/geometry";
 import { SplitPane } from "../components/layout/split-pane";
 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";
 
 /** One advisor declared in `WATCHDOG.yml`; its instructions specialize the shared baseline. */
 export interface AdvisorConfig {
@@ -196,6 +200,38 @@ function wrap(text: string, width: number): string[] {
 
 type Screen = "list" | "detail" | "name" | "model" | "tools" | "thinking" | "instructions";
 
+/** Footer key hints per screen for the described overlay (the ANSI footer strings carry the same keys). */
+function screenHints(screen: Screen): (NativeHint | undefined)[] {
+	switch (screen) {
+		case "list":
+			return [
+				actionHint(["tui.select.up", "tui.select.down"], "move"),
+				actionHint("tui.select.confirm", "select"),
+				actionHint("tui.select.cancel", "close"),
+			];
+		case "detail":
+			return [actionHint("tui.select.confirm", "edit field"), actionHint("tui.select.cancel", "back")];
+		case "name":
+			return [actionHint("tui.input.submit", "save"), actionHint("tui.select.cancel", "cancel")];
+		case "model":
+			return [
+				{ keys: [], label: "type to search" },
+				{ keys: ["enter"], label: "pick" },
+				actionHint("tui.select.cancel", "back"),
+			];
+		case "thinking":
+			return [actionHint("tui.select.confirm", "pick"), actionHint("tui.select.cancel", "back")];
+		case "tools":
+			return [
+				actionHint("tui.select.confirm", "toggle"),
+				{ keys: [], label: "Done applies (empty = no tools; read/grep/glob = default)" },
+				actionHint("tui.select.cancel", "apply"),
+			];
+		case "instructions":
+			return [];
+	}
+}
+
 /**
  * Fullscreen advisor-configuration overlay. Implements {@link Component} directly
  * (rather than extending Container) so it owns the whole frame and the mouse
@@ -214,11 +250,26 @@ export class AdvisorConfigOverlayComponent implements Component {
 	#cachedReports: UsageReport[] | null = null;
 	#dirty = false;
 
+	/** 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;
 	#screen: Screen = "list";
 	/** The interactive element for the current screen. */
 	#active: Component = new SelectList([], 1, getSelectListTheme());
 	#footerHint = "";
 	#previewScroll = 0;
+	#nativeHints: { screen: Screen; node: NativeNode | undefined } | undefined;
+	#nativePreview: { json: string; node: NativeNode } | undefined;
+	#nativeRoot:
+		| {
+				screen: Screen;
+				active: Component;
+				title: string;
+				preview: NativeNode | undefined;
+				hints: NativeNode | undefined;
+				node: NativeNode;
+		  }
+		| undefined;
 
 	// Persistent frame: top, growing two-pane body, divider, footer, bottom.
 	// The frame paints from screen row 0, so SGR `event.row`/`event.col` —
@@ -309,6 +360,372 @@ export class AdvisorConfigOverlayComponent implements Component {
 		return this.#frame.render(width);
 	}
 
+	/** Docks as a side sheet beside the transcript, like `/settings`, when the terminal draws `prefs` with `aside`. */
+	nativeSheet(cx: DescribeContext): boolean {
+		return cx.supports("prefs") && cx.feature("aside");
+	}
+
+	/**
+	 * The native settings page (`prefs`) when the terminal draws it: a page per
+	 * advisor plus the shared instructions, the advisor's fields as typed rows,
+	 * the file actions, and the model/tools/instructions editors over the page.
+	 * Otherwise the root card `omp.overlay.advisor`: on the roster screen a
+	 * sidebar (the active `SelectList`) beside the highlighted entry's preview;
+	 * every other screen shows its editor component alone. Key hints close the
+	 * card.
+	 */
+	describe(cx: DescribeContext): NativeNode {
+		if (cx.supports("prefs")) return this.#describePrefs();
+		return this.#describeCard();
+	}
+
+	/** The advisor index a page shows: the detail's, else the roster's highlighted advisor, else the first. */
+	#pageIndex(): number {
+		if (this.#detailIndex >= 0) return this.#detailIndex;
+		const value = this.#active instanceof SelectList ? (this.#active.getSelectedItem()?.value ?? "") : "";
+		const match = /^advisor:(\d+)$/.exec(value);
+		return match ? Number(match[1]) : value === "shared" ? -1 : 0;
+	}
+
+	#describePrefs(): NativeNode {
+		const doc = this.#doc;
+		const index = this.#pageIndex();
+		const shared = index < 0;
+		const advisor = shared ? undefined : doc.advisors[index];
+		const pages: TspPrefsProps["pages"][number][] = doc.advisors.map((a, i) => ({
+			id: `advisor:${i}`,
+			label: a.name || "(unnamed)",
+			icon: "advisor",
+			group: "Advisors",
+		}));
+		pages.push({ id: "shared", label: "Shared instructions", icon: "doc", group: "All advisors" });
+
+		const sections: TspPrefsProps["sections"][number][] = [];
+		if (doc.warnings?.length) {
+			sections.push({
+				id: "warnings",
+				title: "Config problems",
+				rows: sanitizeDisplayWarnings(doc.warnings).map((warning, i) => ({
+					id: `warning:${i}`,
+					label: "Dropped while loading",
+					warning,
+					control: { k: "action", label: "Save to rewrite", act: "save" },
+				})),
+			});
+		}
+		if (advisor) {
+			const model = advisor.model?.trim();
+			const tools = advisor.tools ?? [...this.#deps.defaultToolNames];
+			const rows: TspPrefsRow[] = [
+				{
+					id: "toggleEnabled",
+					label: "Enabled",
+					hint: "Run this advisor alongside the session.",
+					control: { k: "switch", on: advisor.enabled !== false },
+				},
+				{ id: "name", label: "Name", control: { k: "text", value: advisor.name } },
+				{
+					id: "model",
+					label: "Model",
+					hint: model ? undefined : `Uses the advisor role default (${this.#defaultModelLabel ?? "unset"}).`,
+					changed: model ? true : undefined,
+					defaultLabel: model ? (this.#defaultModelLabel ?? "advisor role default") : undefined,
+					control: { k: "action", label: model || this.#defaultModelLabel || "advisor role default", act: "edit" },
+				},
+				{
+					id: "tools",
+					label: "Tools",
+					hint: "None means no tools; read, grep and glob are the default.",
+					control: {
+						k: "multi",
+						values: tools,
+						options: this.#availableToolNames.map(name => ({ value: name, label: name })),
+					},
+				},
+				{
+					id: "instructions",
+					label: "Instructions",
+					hint: previewLineOrNone(advisor.instructions),
+					control: { k: "action", label: "Edit…", act: "edit" },
+				},
+				{ id: "delete", label: "Delete this advisor", control: { k: "action", label: "Delete", act: "delete" } },
+			];
+			sections.push({ id: "advisor", title: advisor.name || "Advisor", rows });
+		} else {
+			sections.push({
+				id: "shared",
+				title: "Shared instructions",
+				rows: [
+					{
+						id: "shared",
+						label: "Instructions",
+						hint: previewLineOrNone(doc.instructions),
+						control: { k: "action", label: "Edit…", act: "edit" },
+					},
+				],
+			});
+		}
+		sections.push({
+			id: "file",
+			title: `WATCHDOG.yml · ${this.#scope}`,
+			rows: [
+				{
+					id: "save",
+					label: "Save & apply",
+					hint: "Write this file and reload the live advisors without a restart.",
+					warning: this.#dirty ? "Unsaved changes" : undefined,
+					control: { k: "action", label: "Save", act: "save" },
+				},
+				{
+					id: "add",
+					label: "Add advisor",
+					hint: "Create a new advisor entry, then set its model, tools and instructions.",
+					control: { k: "action", label: "Add", act: "add" },
+				},
+				{
+					id: "scope",
+					label: "Scope",
+					hint: `Editing the ${this.#scope} file. Switch to the ${this.#otherScope()} file.`,
+					control: { k: "action", label: `Open ${this.#otherScope()}`, act: "scope" },
+				},
+			],
+		});
+
+		// Name editing shows its draft in the row; the other editors sit over the page.
+		const input = this.#screen === "name" && this.#active instanceof Input ? this.#active : undefined;
+		const editing = input
+			? { row: "name", draft: input.getValue(), cursor: Number(input.debugState().cursor) }
+			: null;
+		const overlay =
+			this.#screen === "model" ||
+			this.#screen === "thinking" ||
+			this.#screen === "tools" ||
+			this.#screen === "instructions";
+		const editor = overlay ? this.#active : undefined;
+		const focus =
+			this.#screen === "detail" && this.#active instanceof SelectList
+				? (this.#active.getSelectedItem()?.value ?? null)
+				: null;
+		const props: TspPrefsProps = {
+			title: this.#dirty ? "Advisors · unsaved" : "Advisors",
+			pages,
+			page: shared ? "shared" : `advisor:${index}`,
+			lead: shared
+				? "Instructions every advisor gets before its own."
+				: "An advisor watches the session and leaves notes; set its model, tools and instructions here.",
+			sections,
+			focus,
+			editing,
+		};
+		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" })] : [];
+		const root = node("prefs", props, children);
+		this.#nativePrefs = { signature, editor, node: root };
+		return root;
+	}
+
+	/**
+	 * Native page events, each through the roster/detail selections the keys
+	 * make: a page opens that advisor (or the shared instructions), a field
+	 * change or button runs the field's detail action, and closing an editor
+	 * or the page cancels like Esc.
+	 */
+	handleNativeEvent(event: NativeUiEvent): void {
+		if (event.key !== "") return;
+		const index = this.#pageIndex();
+		switch (event.type) {
+			case "action": {
+				if (event.act === "page" && event.value) {
+					const match = /^advisor:(\d+)$/.exec(event.value);
+					if (match) this.#showDetail(Number(match[1]));
+					else if (event.value === "shared") this.#showInstructionsEditor(-1);
+					return;
+				}
+				if (event.act === "close") {
+					if (event.value !== undefined) this.#active.handleInput?.("\x1b");
+					else this.#cb.close();
+					return;
+				}
+				if (event.act === "save" || event.act === "add" || event.act === "scope") {
+					void this.#onListSelect(event.act).catch(err => {
+						this.#cb.notify(`Advisor config: ${err instanceof Error ? err.message : String(err)}`);
+					});
+					return;
+				}
+				if (event.value === "shared") this.#showInstructionsEditor(-1);
+				else if (index >= 0 && event.value)
+					this.#onDetailSelect(index, event.act === "delete" ? "delete" : event.value);
+				return;
+			}
+			case "change": {
+				if (index < 0) return;
+				const advisor = this.#doc.advisors[index];
+				if (!advisor) return;
+				if (event.item === "toggleEnabled" && typeof event.value === "boolean") {
+					if (event.value !== (advisor.enabled !== false)) this.#onDetailSelect(index, "toggleEnabled");
+				} else if (event.item === "tools" && Array.isArray(event.value)) {
+					advisor.tools = commitTools(new Set(event.value), this.#availableToolNames, this.#deps.defaultToolNames);
+					this.#dirty = true;
+					this.#showDetail(index);
+				} else if (event.item === "name" && typeof event.value === "string" && event.value.trim()) {
+					advisor.name = event.value.trim();
+					this.#dirty = true;
+					this.#showDetail(index);
+				}
+				return;
+			}
+			case "activate":
+				if (event.item === "shared") this.#showInstructionsEditor(-1);
+				else if (index >= 0) this.#onDetailSelect(index, event.item);
+				return;
+			case "select":
+				if (this.#screen === "detail" && this.#active instanceof SelectList) {
+					this.#active.setSelectedValue(event.item);
+					this.#cb.requestRender();
+				}
+				return;
+			case "toggle":
+				return;
+		}
+	}
+
+	#describeCard(): NativeNode {
+		const title = `Advisor configuration · ${this.#scope}${this.#dirty ? "  ● unsaved" : ""}`;
+		const preview = this.#screen === "list" ? this.#describePreview() : undefined;
+		if (this.#nativeHints?.screen !== this.#screen) {
+			const hints = screenHints(this.#screen);
+			this.#nativeHints = { screen: this.#screen, node: hints.length > 0 ? hintsRow(hints) : undefined };
+		}
+		const hints = this.#nativeHints.node;
+		const prev = this.#nativeRoot;
+		if (
+			prev?.screen === this.#screen &&
+			prev.active === this.#active &&
+			prev.title === title &&
+			prev.preview === preview &&
+			prev.hints === hints
+		) {
+			return prev.node;
+		}
+		const head: TspSpan[] = [span(`Advisor configuration · ${this.#scope}`)];
+		if (this.#dirty) head.push(span("  ● unsaved", "warning"));
+		const body: NativeNode = preview
+			? node(
+					"row",
+					{ gap: "md", align: "start", grow: 1 },
+					[
+						node("col", { min: { w: "22ch" }, max: { w: "42ch" }, basis: 0.34 }, [this.#active], "sidebar"),
+						preview,
+					],
+					"split",
+				)
+			: node("col", { grow: 1 }, [this.#active], "body");
+		const children: NativeChild[] = [body];
+		if (hints) children.push(node("rule", undefined, undefined, "divider"), hints);
+		const card = overlayCard("omp.overlay.advisor", head, children);
+		this.#nativeRoot = { screen: this.#screen, active: this.#active, title, preview, hints, node: card };
+		return card;
+	}
+
+	/** The highlighted roster entry's preview; rebuilt only when its content changes (live stats, quota). */
+	#describePreview(): NativeNode {
+		const children: NativeNode[] = [];
+		if (this.#doc.warnings?.length) {
+			children.push(
+				node(
+					"col",
+					{ tone: "warning" },
+					[
+						text([span("⚠ Config problems — dropped while loading:", "warning")]),
+						...sanitizeDisplayWarnings(this.#doc.warnings).map(warning =>
+							text([span(warning, "warning")], { wrap: "word" }),
+						),
+					],
+					"warnings",
+				),
+			);
+		}
+		const list = this.#active;
+		const value = list instanceof SelectList ? (list.getSelectedItem()?.value ?? "") : "";
+		const match = /^advisor:(\d+)$/.exec(value);
+		const advisor = match ? this.#doc.advisors[Number(match[1])] : undefined;
+		if (advisor) {
+			children.push(...this.#describeAdvisorPreview(advisor));
+		} else if (value === "shared") {
+			const instructions = this.#doc.instructions?.trim();
+			children.push(
+				text([span("Shared instructions", "strong")]),
+				instructions ? text(instructions, { wrap: "word" }) : text([span("(none)", "muted")]),
+			);
+		} else {
+			const help =
+				value === "add"
+					? "Create a new advisor entry, then edit its model, tools, and instructions."
+					: value === "scope"
+						? `Switch between the project and user WATCHDOG.yml. Currently editing the ${this.#scope}-level file.`
+						: value === "save"
+							? "Write this scope's WATCHDOG.yml and reload the live advisors without a restart."
+							: value === "close"
+								? "Close the editor. Unsaved changes are discarded."
+								: "";
+			if (help) children.push(text([span(help, "muted")], { wrap: "word" }));
+		}
+		const candidate = node("col", { gap: "sm", grow: 1 }, children, "preview");
+		const json = JSON.stringify(candidate);
+		if (this.#nativePreview?.json === json) return this.#nativePreview.node;
+		this.#nativePreview = { json, node: candidate };
+		return candidate;
+	}
+
+	#describeAdvisorPreview(advisor: AdvisorConfig): NativeNode[] {
+		const model = advisor.model?.trim() || this.#defaultModelLabel || "advisor role default";
+		const instructions = advisor.instructions?.trim();
+		const out: NativeNode[] = [
+			text([span(advisor.name || "(unnamed)", "strong")]),
+			node("kv", {
+				items: [
+					{ k: "Enabled", v: advisor.enabled === false ? "○ off" : "● on" },
+					{ k: "Model", v: model },
+					{ k: "Tools", v: formatAdvisorTools(advisor.tools, "no tools") },
+				],
+			}),
+			text([span("Instructions:", "dim")]),
+			instructions ? text(instructions, { wrap: "word" }) : text([span("(none)", "muted")]),
+		];
+		const liveStat = this.#cb.getAdvisorStats?.()?.find(s => s.name === (advisor.name || "default"));
+		if (liveStat && (liveStat.status === "running" || liveStat.status === "quota_exhausted")) {
+			const spendParts = [
+				`${liveStat.tokens.input.toLocaleString()} in`,
+				`${liveStat.tokens.output.toLocaleString()} out`,
+			];
+			if (liveStat.tokens.cacheRead > 0) spendParts.push(`${liveStat.tokens.cacheRead.toLocaleString()} cache`);
+			const usage: { k: string; v: string }[] = [{ k: "Tokens", v: spendParts.join(", ") }];
+			if (liveStat.cost > 0) usage.push({ k: "Cost", v: `$${liveStat.cost.toFixed(4)}` });
+			if (liveStat.contextWindow > 0) {
+				const pct = Math.round((liveStat.contextTokens / liveStat.contextWindow) * 100);
+				usage.push({
+					k: "Context",
+					v: `${liveStat.contextTokens.toLocaleString()}/${liveStat.contextWindow.toLocaleString()} (${pct}%)`,
+				});
+			}
+			out.push(text([span("Usage:", "dim")]), node("kv", { items: usage }));
+		}
+		const quotaProvider =
+			(advisor.model?.includes("/") ? advisor.model.split("/")[0] : null) ?? liveStat?.model?.provider;
+		if (this.#cachedReports && quotaProvider) {
+			const quota = formatCompactQuota(
+				quotaProvider,
+				this.#cachedReports,
+				Date.now(),
+				this.#cb.getQuotaLimitFilter?.(quotaProvider, liveStat?.sessionId),
+			);
+			if (quota) out.push(text([span(quota, "dim")], { wrap: "word" }));
+		}
+		return out;
+	}
+
 	// ───────────────────────────── input ─────────────────────────────
 
 	handleInput(data: string): void {
@@ -489,6 +906,7 @@ export class AdvisorConfigOverlayComponent implements Component {
 	}
 
 	#showList(): void {
+		this.#detailIndex = -1;
 		this.#ensureRosterVisible();
 		const items: SelectItem[] = this.#doc.advisors.map((advisor, index) => ({
 			value: `advisor:${index}`,
@@ -579,6 +997,7 @@ export class AdvisorConfigOverlayComponent implements Component {
 			this.#showList();
 			return;
 		}
+		this.#detailIndex = index;
 		const modelDescription = advisor.model?.trim() || this.#defaultModelLabel || "advisor role default";
 		const toolsDescription = formatAdvisorTools(advisor.tools, "no tools");
 		const items: SelectItem[] = [
@@ -758,6 +1177,7 @@ export class AdvisorConfigOverlayComponent implements Component {
 	/** `index === -1` edits the shared top-level instructions; otherwise advisor[index]. */
 	#showInstructionsEditor(index: number): void {
 		const shared = index < 0;
+		this.#detailIndex = index;
 		const current = shared ? this.#doc.instructions : this.#doc.advisors[index].instructions;
 		const title = shared ? "Shared advisor instructions" : `Instructions — ${this.#doc.advisors[index].name}`;
 		const editor = new HookEditorComponent(