@hheei/omp-optimizer 0.1.0

package/src/edit-guard.ts

@@ -0,0 +1,137 @@
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@oh-my-pi/pi-coding-agent";
+import type { OptimizerHandle, OptimizerStatus } from "./status.ts";
+import { loadOptValue, saveOptValue } from "./persist.ts";
+
+export type EditGuardLevel = "on" | "off";
+export const EDIT_GUARD_LEVELS: readonly EditGuardLevel[] = ["on", "off"];
+
+const EDIT_GUARD_TOOL = "edit-guard" as const;
+const APPLY_PATCH_COMMAND = /(?:^|[\n;&|()])\s*(?:command\s+)?apply_patch\s/;
+const HASHLINE_FILE_HEADER = /^\[[^\]\r\n#]+#[0-9a-f]{4}\]/im;
+const HASHLINE_HUNK_HEADER = /^@@/m;
+const HASHLINE_GUARD_MESSAGE =
+	"Hashline edit was aborted: `@@` is unified-diff syntax, not hashline syntax. Re-read the file, then retry with `[path#HASH]` plus `PUT`, `CUT`, `REM`, or `MV`. Do not retry the same payload.";
+const NO_EDIT_TOOL_GUIDANCE =
+	"`apply_patch` is unavailable; the call was aborted. No supported file-editing tool is active. Enable `edit`, or `write` before retrying.";
+const APPLY_PATCH_RETRY_WARNING = "Do not retry `apply_patch`.";
+
+declare global {
+	var __ompOptimizerEditGuardRegistrations: WeakMap<object, symbol> | undefined;
+}
+
+function currentRegistration(pi: ExtensionAPI): () => boolean {
+	const identity: object = typeof pi.events === "object" && pi.events !== null ? pi.events : pi;
+	let registrations = globalThis.__ompOptimizerEditGuardRegistrations;
+	if (registrations === undefined) {
+		registrations = new WeakMap();
+		globalThis.__ompOptimizerEditGuardRegistrations = registrations;
+	}
+	const token = Symbol("omp-optimizer-edit-guard");
+	registrations.set(identity, token);
+	return () => registrations.get(identity) === token;
+}
+
+/** Detects a streamed shell attempt to invoke apply_patch, excluding plain mentions. */
+export function hasStreamingApplyPatchCommand(command: string): boolean {
+	return APPLY_PATCH_COMMAND.test(command);
+}
+
+/** Detects top-level unified-diff hunk syntax inside a hashline edit payload. */
+export function hasMalformedHashlineInput(input: string): boolean {
+	return HASHLINE_FILE_HEADER.test(input) && HASHLINE_HUNK_HEADER.test(input);
+}
+
+function blockReason(activeTools: readonly string[]): string {
+	const alternatives = ["edit", "write"].filter(name => activeTools.includes(name));
+	if (alternatives.length === 0) return NO_EDIT_TOOL_GUIDANCE;
+	const names = alternatives.map(name => `\`${name}\``);
+	const action = names.length === 1 ? names[0] : `${names[0]} or ${names[1]}`;
+	return `\`apply_patch\` is unavailable; the call was aborted. Continue with ${action}. ${APPLY_PATCH_RETRY_WARNING}`;
+}
+
+/** Aborts malformed hashline edits and unavailable shell apply_patch calls. */
+export function editGuard(pi: ExtensionAPI, status: OptimizerStatus): OptimizerHandle {
+	let level: EditGuardLevel = "on";
+	const isCurrent = currentRegistration(pi);
+	let interrupted = false;
+	let pendingReason: string | undefined;
+
+	function syncStatus(ctx: Pick<ExtensionContext, "ui">): void {
+		status.set(EDIT_GUARD_TOOL, level === "on", ctx);
+	}
+
+	pi.on("before_agent_start", () => {
+		if (!isCurrent()) return;
+		interrupted = false;
+	});
+	pi.on("session_start", (_event, ctx) => {
+		if (!isCurrent()) return;
+		interrupted = false;
+		pendingReason = undefined;
+		for (const entry of ctx.sessionManager.getEntries()) {
+			if (entry.type !== "custom" || entry.customType !== "edit-guard-level") continue;
+			const saved = entry.data && typeof entry.data === "object" && "level" in entry.data ? entry.data.level : undefined;
+			if (saved === "on" || saved === "off") level = saved;
+		}
+		const saved = loadOptValue(EDIT_GUARD_TOOL);
+		if (saved === "on" || saved === "off") level = saved;
+		syncStatus(ctx);
+	});
+	pi.on("agent_start", async (_event, ctx) => syncStatus(ctx));
+	pi.on("agent_end", async (event, ctx) => {
+		if (!isCurrent()) return;
+		syncStatus(ctx);
+		if (event.willContinue || pendingReason === undefined) return;
+		const reason = pendingReason;
+		pendingReason = undefined;
+		pi.sendMessage(
+			{
+				customType: "edit-guard",
+				content: reason,
+				display: true,
+			},
+			{ triggerTurn: true },
+		);
+	});
+	pi.on("session_shutdown", () => {
+		if (!isCurrent()) return;
+		pendingReason = undefined;
+	});
+	pi.on("message_update", (event, context) => {
+		if (level !== "on" || interrupted || !isCurrent() || event.assistantMessageEvent.type !== "toolcall_delta") return;
+		const update = event.assistantMessageEvent;
+		const content = update.partial.content[update.contentIndex];
+		if (content?.type !== "toolCall") return;
+
+		let reason: string | undefined;
+		if (content.name === "edit") {
+			const input = content.arguments.input;
+			if (typeof input === "string" && hasMalformedHashlineInput(input)) reason = HASHLINE_GUARD_MESSAGE;
+		} else if (content.name === "bash") {
+			if (pi.getActiveTools().includes("apply_patch")) return;
+			const command = content.arguments.command;
+			if (typeof command === "string" && hasStreamingApplyPatchCommand(command)) reason = blockReason(pi.getActiveTools());
+		}
+		if (reason === undefined) return;
+		interrupted = true;
+		pendingReason = reason;
+		context.abort();
+	});
+
+	async function run(value: string, ctx: ExtensionCommandContext): Promise<void> {
+		if (value !== "on" && value !== "off") return;
+		level = value;
+		pi.appendEntry("edit-guard-level", { level });
+		saveOptValue(EDIT_GUARD_TOOL, level);
+		syncStatus(ctx);
+		ctx.ui.notify(`Edit Guard ${level === "on" ? "enabled" : "disabled"}`, "info");
+	}
+
+	return {
+		name: EDIT_GUARD_TOOL,
+		help: "Edit Guard — block malformed apply_patch syntax in hashline mode and unavailable shell apply_patch calls",
+		values: EDIT_GUARD_LEVELS,
+		current: () => level,
+		run,
+	};
+}

package/src/index.ts

@@ -0,0 +1,50 @@
+/**
+ * omp-optimizer — token-optimization suite for Oh My Pi.
+ *
+ * Five tools, combined into one extension + one command:
+ *   - caveman: terse-output system prompt
+ *   - rtk:     prefixes shell commands with `rtk` + injects RTK prompt
+ *   - ponytail: lazy-senior-dev system prompt (minimal code, YAGNI)
+ *   - t2s:    converts interactive Traditional Chinese input to Simplified Chinese
+ *   - edit-guard: blocks unified-diff syntax in hashline edits
+ *
+ * They share ONE status-bar cell (all five icons always shown — dimmed when
+ * off, accented when on) and ONE command (/optimizer — an interactive overlay).
+ * index.ts wires lifecycle hooks via each module, then registers the overlay command.
+ */
+
+import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
+import { editGuard } from "./edit-guard.ts";
+import { caveman } from "./caveman.ts";
+import { registerOptCommand } from "./opt.ts";
+import { ponytail } from "./ponytail.ts";
+import { rtk } from "./rtk.ts";
+import { t2s } from "./t2s.ts";
+import { type OptimizerHandle, OptimizerStatus, type OptimizerTool } from "./status.ts";
+import { filterModelWarnings } from "./tool-result-filter.ts";
+
+export default function optimizer(pi: ExtensionAPI) {
+	const status = new OptimizerStatus();
+
+	// Each module registers its own lifecycle hooks and returns a handle the
+	// /optimizer overlay renders + drives.
+	const handles: Record<OptimizerTool, OptimizerHandle> = {
+		caveman: caveman(pi, status),
+		rtk: rtk(pi, status),
+		ponytail: ponytail(pi, status),
+		t2s: t2s(pi, status),
+		"edit-guard": editGuard(pi, status),
+	};
+
+	registerOptCommand(pi, handles, status);
+
+	// Strip model-guidance warnings injected by pi-lens into tool_result content.
+	// These strings (BLIND WRITE, THRASHING) are directives for the LLM, not
+	// information for the user — filtering them here hides them from the TUI
+	// without affecting the model (it already acted on the write/edit result).
+	pi.on("tool_result", async (event) => {
+		const filtered = filterModelWarnings(event.content);
+		if (filtered === event.content) return undefined;
+		return { content: filtered };
+	});
+}

package/src/mode.ts

@@ -0,0 +1,115 @@
+/**
+ * mode.ts — shared plumbing for prompt-injection optimizer modes.
+ *
+ * caveman.ts and ponytail.ts are the same *kind* of tool: a level enum, a
+ * system-prompt fragment injected via before_agent_start, and identical
+ * persistence/status wiring. Only the prompt/help/label *content* differs —
+ * that stays in each module. This file owns the generic level resolution and
+ * the extension factory both call.
+ */
+
+import type {
+	ExtensionAPI,
+	ExtensionCommandContext,
+	ExtensionContext,
+} from "@oh-my-pi/pi-coding-agent";
+import { loadOptValue, saveOptValue } from "./persist.ts";
+import type { OptimizerHandle, OptimizerStatus, OptimizerTool } from "./status.ts";
+
+/**
+ * Resolve a raw command arg to a level, or null if unrecognised.
+ * Handles stop aliases (stop/quit → "off"), numeric shortcuts, and level names.
+ */
+export function resolveLevel<L extends string>(
+	arg: string,
+	levels: readonly L[],
+	levelNumbers: Record<string, L>,
+	stopAliases: ReadonlySet<string>,
+): L | null {
+	const a = arg.trim().toLowerCase();
+	if (stopAliases.has(a)) return "off" as L;
+	if (levelNumbers[a]) return levelNumbers[a];
+	if (levels.includes(a as L)) return a as L;
+	return null;
+}
+
+/** Toggle: off → full, anything else → off. */
+export function toggleLevel<L extends string>(current: L): L {
+	return (current === "off" ? "full" : "off") as L;
+}
+
+export interface ModeConfig<L extends string> {
+	/** Status-registry key + persistence key + `${name}-level` custom entry. */
+	name: OptimizerTool;
+	/** One-line overlay summary. */
+	help: string;
+	/** Cyclable values in display order. */
+	levels: readonly L[];
+	/** Build the system-prompt fragment for a level ("" when off). */
+	buildPrompt(level: L): string;
+	/** Resolve an overlay/command value to a level (each module supplies its enum). */
+	resolve(value: string): L | null;
+	/** Notification shown after a successful change. */
+	notify(level: L): string;
+}
+
+/**
+ * Build the shared extension: prompt injection + session restore + status +
+ * overlay handle. Identical across every prompt-mode tool.
+ */
+export function createMode<L extends string>(
+	pi: ExtensionAPI,
+	status: OptimizerStatus,
+	config: ModeConfig<L>,
+): OptimizerHandle {
+	const { name, levels, buildPrompt } = config;
+	const customType = `${name}-level`;
+	let level = "off" as L;
+
+	function syncStatus(ctx: Pick<ExtensionContext, "ui">) {
+		status.set(name, level !== "off", ctx);
+	}
+
+	pi.on("before_agent_start", async (event, _ctx) => {
+		const prompt = buildPrompt(level);
+		if (!prompt) return undefined;
+		return { systemPrompt: [prompt, ...event.systemPrompt] };
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		// Session log first (survives in-session branch nav), then disk (survives
+		// a full quit/restart). Disk wins when present.
+		for (const entry of ctx.sessionManager.getEntries()) {
+			if (entry.type === "custom" && entry.customType === customType) {
+				level = ((entry.data as { level: L })?.level ?? level) as L;
+			}
+		}
+		const saved = loadOptValue(name);
+		if (saved && levels.includes(saved as L)) level = saved as L;
+		syncStatus(ctx);
+	});
+
+	pi.on("agent_start", async (_event, ctx) => syncStatus(ctx));
+	pi.on("agent_end", async (_event, ctx) => syncStatus(ctx));
+	pi.on("session_shutdown", async () => {});
+
+	async function run(value: string, ctx: ExtensionCommandContext): Promise<void> {
+		const resolved = config.resolve(value);
+		if (resolved === null) return;
+		level = resolved;
+
+		pi.appendEntry(customType, { level });
+		saveOptValue(name, level);
+		syncStatus(ctx);
+
+		ctx.ui.notify(config.notify(level), "info");
+	}
+
+	return {
+		name,
+		help: config.help,
+		values: levels,
+		current: () => level,
+		run,
+	};
+}

package/src/opt-keys.test.ts

@@ -0,0 +1,165 @@
+/** OMP-native SettingsList interaction tests for the /optimizer overlay. */
+
+import { describe, expect, it } from "bun:test";
+import type { ExtensionAPI, ExtensionCommandContext } from "@oh-my-pi/pi-coding-agent";
+import { registerOptCommand } from "./opt.ts";
+import type { OptimizerHandle, OptimizerStatus, OptimizerTool } from "./status.ts";
+
+const KEYS = {
+	up: { legacy: "\u001b[A", kitty: "\u001b[1;1A" },
+	down: { legacy: "\u001b[B", kitty: "\u001b[1;1B" },
+	enter: { legacy: "\r", kitty: "\u001b[13u" },
+	space: { legacy: " ", kitty: "\u001b[32u" },
+	escape: { legacy: "\u001b", kitty: "\u001b[27u" },
+	q: { legacy: "q", kitty: "\u001b[113u" },
+} as const;
+
+const ENCODINGS = ["legacy", "kitty"] as const;
+
+interface Overlay {
+	render(width: number): readonly string[];
+	handleInput(data: string): void;
+}
+
+interface Driver {
+	feed(data: string): void;
+	runs(): Array<{ tool: string; value: string }>;
+	rows(): readonly string[];
+	closed(): boolean;
+}
+
+async function openOverlay(): Promise<Driver> {
+	const runs: Array<{ tool: string; value: string }> = [];
+	const makeHandle = (name: OptimizerTool, current: string, values: string[]): OptimizerHandle => {
+		let value = current;
+		return {
+			name,
+			help: `${name} — help`,
+			values,
+			current: () => value,
+			run: async next => {
+				value = next;
+				runs.push({ tool: name, value: next });
+			},
+		};
+	};
+	const handles: Record<OptimizerTool, OptimizerHandle> = {
+		caveman: makeHandle("caveman", "off", ["off", "lite", "full", "ultra", "micro"]),
+		rtk: makeHandle("rtk", "off", ["off", "on"]),
+		ponytail: makeHandle("ponytail", "off", ["off", "lite", "full", "ultra"]),
+		t2s: makeHandle("t2s", "on", ["on", "off"]),
+		"edit-guard": makeHandle("edit-guard", "on", ["on", "off"]),
+	};
+
+	let overlay: Overlay | undefined;
+	let closed = false;
+	let commandHandler: ((args: string, ctx: ExtensionCommandContext) => Promise<void>) | undefined;
+	const pi = {
+		registerCommand: (_name: string, spec: { handler: typeof commandHandler }) => {
+			commandHandler = spec.handler;
+		},
+	} as unknown as ExtensionAPI;
+
+	registerOptCommand(pi, handles, {} as OptimizerStatus);
+	if (!commandHandler) throw new Error("/optimizer did not register");
+
+	const ctx = {
+		hasUI: true,
+		ui: {
+			notify: () => {},
+			custom: async <T>(
+				factory: (tui: { requestRender(): void }, theme: unknown, keybindings: unknown, done: (value: T) => void) => Overlay,
+			): Promise<T | undefined> => {
+				overlay = factory(
+					{ requestRender: () => {} },
+					{
+						bold: (text: string) => text,
+						fg: (_color: string, text: string) => text,
+						boxRound: {
+							topLeft: "╭",
+							topRight: "╮",
+							bottomLeft: "╰",
+							bottomRight: "╯",
+							horizontal: "─",
+							vertical: "│",
+						},
+					},
+					undefined,
+					() => {
+						closed = true;
+					},
+				);
+				return undefined;
+			},
+		},
+	} as unknown as ExtensionCommandContext;
+
+	await commandHandler("", ctx);
+	if (!overlay) throw new Error("overlay was not constructed");
+	const component = overlay;
+	return {
+		feed: data => component.handleInput(data),
+		runs: () => runs,
+		closed: () => closed,
+		rows: () => component.render(80),
+	};
+}
+
+describe("/optimizer layout", () => {
+	it("uses switch-style titled chrome with aligned rows", async () => {
+		const rows = (await openOverlay()).rows();
+		expect(rows).toHaveLength(11);
+		expect(rows[0]).toMatch(/^╭─ .*Optimizer /);
+		expect(rows[1]).toContain("Caveman");
+		expect(rows[5]).toContain("Edit Guard");
+		expect(rows[6]).toMatch(/^│\s+│$/);
+		expect(rows[7]).toContain("help");
+		expect(rows[8]).toMatch(/^│\s+│$/);
+		expect(rows[9]).toContain("Esc close");
+		expect(rows[10]).toMatch(/^╰─+╯$/);
+	});
+});
+
+for (const encoding of ENCODINGS) {
+	describe(`/optimizer SettingsList keys (${encoding})`, () => {
+		it("moves with the OMP down binding and changes the selected tool", async () => {
+			const driver = await openOverlay();
+			driver.feed(KEYS.down[encoding]);
+			driver.feed(KEYS.space[encoding]);
+			expect(driver.runs()).toEqual([{ tool: "rtk", value: "on" }]);
+		});
+
+		it("wraps upward and changes the last tool", async () => {
+			const driver = await openOverlay();
+			driver.feed(KEYS.up[encoding]);
+			driver.feed(KEYS.space[encoding]);
+			expect(driver.runs()).toEqual([{ tool: "edit-guard", value: "off" }]);
+		});
+
+		it("uses Enter and Space to cycle the selected setting", async () => {
+			const driver = await openOverlay();
+			driver.feed(KEYS.space[encoding]);
+			driver.feed(KEYS.enter[encoding]);
+			expect(driver.runs()).toEqual([
+				{ tool: "caveman", value: "lite" },
+				{ tool: "caveman", value: "full" },
+			]);
+		});
+
+		it("closes on OMP cancel or the optional q shortcut", async () => {
+			const driver = await openOverlay();
+			driver.feed(KEYS.escape[encoding]);
+			expect(driver.closed()).toBe(true);
+
+			const second = await openOverlay();
+			second.feed(KEYS.q[encoding]);
+			expect(second.closed()).toBe(true);
+		});
+
+		it("ignores an unbound key without changing optimizer state", async () => {
+			const driver = await openOverlay();
+			driver.feed("x");
+			expect(driver.runs()).toEqual([]);
+		});
+	});
+}

package/src/opt.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "bun:test";
+import { buildOptHelp } from "./opt.ts";
+import type { OptimizerHandle, OptimizerTool } from "./status.ts";
+
+/** Build a handle set with fixed current values + value lists. */
+function fakeHandles(): Record<OptimizerTool, OptimizerHandle> {
+	const mk = (name: OptimizerTool, current: string, values: string[]): OptimizerHandle => ({
+		name,
+		help: `${name} — ${name} help`,
+		values,
+		current: () => current,
+		run: () => {},
+	});
+	return {
+		caveman: mk("caveman", "full", ["off", "lite", "full", "ultra", "micro"]),
+		rtk: mk("rtk", "on", ["off", "on"]),
+		ponytail: mk("ponytail", "off", ["off", "lite", "full", "ultra"]),
+		t2s: mk("t2s", "on", ["on", "off"]),
+		"edit-guard": mk("edit-guard", "on", ["on", "off"]),
+	};
+}
+
+
+describe("buildOptHelp", () => {
+	it("lists every tool with its current value", () => {
+		const help = buildOptHelp(fakeHandles());
+		expect(help).toContain("caveman: full");
+		expect(help).toContain("rtk: on");
+		expect(help).not.toContain("toon");
+		expect(help).toContain("ponytail: off");
+		expect(help).toContain("edit-guard: on");
+		expect(help).toContain("caveman help");
+	});
+});

package/src/opt.ts

@@ -0,0 +1,161 @@
+/** Interactive `/optimizer` command using OMP's native settings components. */
+
+import { getSettingsListTheme } from "@oh-my-pi/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext, Theme } from "@oh-my-pi/pi-coding-agent";
+import {
+	type Component,
+	matchesKey,
+	padding,
+	SettingsList,
+	truncateToWidth,
+	type SettingItem,
+	type TUI,
+	visibleWidth,
+} from "@oh-my-pi/pi-tui";
+import type { OptimizerHandle, OptimizerStatus, OptimizerTool } from "./status.ts";
+import { OPTIMIZER_ICON, toolIcon } from "./status.ts";
+
+const TOOL_ORDER: readonly OptimizerTool[] = ["caveman", "rtk", "ponytail", "t2s", "edit-guard"];
+
+function helpSummary(help: string): string {
+	const dash = help.indexOf("—");
+	return dash === -1 ? help : help.slice(dash + 1).trim();
+}
+
+export function buildOptHelp(handles: Record<OptimizerTool, OptimizerHandle>): string {
+	const lines = TOOL_ORDER.map(tool => `  ${tool}: ${handles[tool].current()} — ${helpSummary(handles[tool].help)}`);
+	return ["omp-optimizer — token tools", "", ...lines].join("\n");
+}
+
+function displayName(tool: OptimizerTool): string {
+	return tool.split("-").map(part => `${part[0]?.toUpperCase()}${part.slice(1)}`).join(" ");
+}
+
+function buildItems(handles: Record<OptimizerTool, OptimizerHandle>): SettingItem[] {
+	return TOOL_ORDER.map(tool => ({
+		id: tool,
+		label: `${toolIcon(tool)}  ${displayName(tool)}`,
+		description: helpSummary(handles[tool].help),
+		currentValue: handles[tool].current(),
+		values: [...handles[tool].values],
+	}));
+}
+
+function normalizeSettingsKey(data: string): string {
+	if (matchesKey(data, "up")) return "\u001b[A";
+	if (matchesKey(data, "down")) return "\u001b[B";
+	if (matchesKey(data, "escape")) return "\u001b";
+	if (matchesKey(data, "space")) return " ";
+	if (matchesKey(data, "enter")) return "\n";
+	return data;
+}
+
+function trimSettingsListPadding(rows: readonly string[]): string[] {
+	const footerIndex = rows.findLastIndex(row => row !== "");
+	if (footerIndex < 0) return [...rows];
+	const content = rows.slice(0, footerIndex);
+	while (content.at(-1) === "") content.pop();
+	return [...content, "", rows[footerIndex]!];
+}
+
+function fitLine(text: string, width: number): string {
+	const innerWidth = Math.max(0, width - 4);
+	const clipped = truncateToWidth(text, innerWidth);
+	return `${clipped}${padding(Math.max(0, innerWidth - visibleWidth(clipped)))}`;
+}
+
+function frameRow(text: string, width: number, theme: Theme): string {
+	const border = (value: string) => theme.fg("border", value);
+	return `${border(theme.boxRound.vertical)} ${fitLine(text, width)} ${border(theme.boxRound.vertical)}`;
+}
+
+function topBorder(width: number, title: string, theme: Theme): string {
+	const border = (value: string) => theme.fg("border", value);
+	const inner = Math.max(0, width - 2);
+	const shown = truncateToWidth(` ${title} `, Math.max(0, inner - 2));
+	const fillWidth = Math.max(0, inner - 1 - visibleWidth(shown));
+	return `${border(theme.boxRound.topLeft + theme.boxRound.horizontal)}${theme.bold(theme.fg("accent", shown))}${border(theme.boxRound.horizontal.repeat(fillWidth) + theme.boxRound.topRight)}`;
+}
+
+function bottomBorder(width: number, theme: Theme): string {
+	const border = (value: string) => theme.fg("border", value);
+	return border(
+		theme.boxRound.bottomLeft + theme.boxRound.horizontal.repeat(Math.max(0, width - 2)) + theme.boxRound.bottomRight,
+	);
+}
+
+class OptimizerPanel implements Component {
+	#list: SettingsList;
+	#tui: TUI;
+	#done: (result: null) => void;
+	#theme: Theme;
+
+	constructor(
+		tui: TUI,
+		theme: Theme,
+		handles: Record<OptimizerTool, OptimizerHandle>,
+		ctx: ExtensionCommandContext,
+		done: (result: null) => void,
+	) {
+		this.#theme = theme;
+		this.#tui = tui;
+		this.#done = done;
+		this.#list = new SettingsList(
+			buildItems(handles),
+			Math.min(TOOL_ORDER.length, 8),
+			getSettingsListTheme(),
+			(id, value) => {
+				void handles[id as OptimizerTool]?.run(value, ctx);
+			},
+			() => this.#done(null),
+			{ typeToSearch: false, hint: "↑↓ move · Enter/Space change · Esc close" },
+		);
+	}
+
+	render(width: number): readonly string[] {
+		const rows = trimSettingsListPadding(this.#list.render(width));
+		return [
+			topBorder(width, `${OPTIMIZER_ICON}  Optimizer`, this.#theme),
+			...rows.map(row => frameRow(row, width, this.#theme)),
+			bottomBorder(width, this.#theme),
+		];
+	}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, "q")) {
+			this.#done(null);
+			return;
+		}
+		this.#list.handleInput(normalizeSettingsKey(data));
+		this.#tui.requestRender();
+	}
+
+	invalidate(): void {
+		this.#list.invalidate();
+	}
+}
+
+export function registerOptCommand(
+	pi: ExtensionAPI,
+	handles: Record<OptimizerTool, OptimizerHandle>,
+	_status: OptimizerStatus,
+): void {
+	pi.registerCommand("optimizer", {
+		description: "Enable or disable optimizer modes",
+		handler: async (_args, ctx) => {
+			if (!ctx.hasUI) {
+				ctx.ui.notify(buildOptHelp(handles), "info");
+				return;
+			}
+			await ctx.ui.custom<null>(
+				(tui, theme, _keybindings, done) => new OptimizerPanel(tui, theme, handles, ctx, done),
+				{
+					overlay: true,
+					// ponytail: default custom overlays are bottom-centered, leaving the
+					// transcript-sized prompt area blank above this short panel.
+					overlayOptions: { anchor: "top-center", offsetY: 5, width: "100%", maxHeight: "100%", margin: 0 },
+				},
+			);
+		},
+	});
+}