@oh-my-pi/pi-coding-agent 15.12.3 → 15.13.0

package/src/cli/setup-cli.ts

@@ -4,12 +4,18 @@
  * Handles `omp setup` for onboarding and `omp setup <component>` for optional dependencies.
  */
 import * as path from "node:path";
-import { $which, APP_NAME, getPythonEnvDir } from "@oh-my-pi/pi-utils";
+import { $which, APP_NAME, getProjectDir, getPythonEnvDir } from "@oh-my-pi/pi-utils";
 import { $ } from "bun";
 import chalk from "chalk";
+import { Settings, settings } from "../config/settings";
 import { theme } from "../modes/theme/theme";
+import { downloadSttModel, isSttModelCached } from "../stt/downloader";
+import { isSttModelKey, STT_MODEL_OPTIONS } from "../stt/models";
+import { detectRecorder, ensureRecorder } from "../stt/recorder";
+import { downloadTtsModel, isTtsLocalModelKey, isTtsModelCached, TTS_LOCAL_MODEL_OPTIONS } from "../tts";
+import { selectSetupModel } from "./setup-model-picker";
 
-export type SetupComponent = "python" | "stt";
+export type SetupComponent = "python" | "speech";
 
 export interface SetupCommandArgs {
 	component: SetupComponent;
@@ -19,7 +25,7 @@ export interface SetupCommandArgs {
 	};
 }
 
-const VALID_COMPONENTS: SetupComponent[] = ["python", "stt"];
+const VALID_COMPONENTS: SetupComponent[] = ["python", "speech"];
 
 const MANAGED_PYTHON_ENV = getPythonEnvDir();
 
@@ -114,8 +120,8 @@ export async function runSetupCommand(cmd: SetupCommandArgs): Promise<void> {
 		case "python":
 			await handlePythonSetup(cmd.flags);
 			break;
-		case "stt":
-			await handleSttSetup(cmd.flags);
+		case "speech":
+			await handleSpeechSetup(cmd.flags);
 			break;
 	}
 }
@@ -149,58 +155,153 @@ async function handlePythonSetup(flags: { json?: boolean; check?: boolean }): Pr
 	process.exit(1);
 }
 
-async function handleSttSetup(flags: { json?: boolean; check?: boolean }): Promise<void> {
-	const { checkDependencies, formatDependencyStatus } = await import("../stt/setup");
-	const status = await checkDependencies();
+/**
+ * One installable speech dependency. `isReady`/`status` are read-only probes;
+ * `pick` (optional) lets an interactive user choose + persist a model; `ensure`
+ * performs the download, streaming a normalized progress event.
+ */
+interface SpeechComponent {
+	name: string;
+	isReady(): Promise<boolean>;
+	status(): Promise<string>;
+	pick?(): Promise<boolean>;
+	ensure(onProgress: (progress: { stage: string; percent?: number }) => void): Promise<void>;
+}
 
-	if (flags.json) {
-		console.log(JSON.stringify(status, null, 2));
-		if (!status.recorder.available || !status.python.available || !status.whisper.available) process.exit(1);
-		return;
-	}
+function buildSpeechComponents(): SpeechComponent[] {
+	return [
+		{
+			name: "Recorder",
+			isReady: async () => detectRecorder() !== null,
+			status: async () => {
+				const recorder = detectRecorder();
+				return recorder ? `${recorder.tool} (${recorder.bin})` : "none — ffmpeg will be downloaded";
+			},
+			ensure: async onProgress => {
+				await ensureRecorder(onProgress);
+			},
+		},
+		{
+			name: "Speech-to-Text model",
+			isReady: () => isSttModelCached(settings.get("stt.modelName")),
+			status: async () => {
+				const key = settings.get("stt.modelName");
+				return (await isSttModelCached(key)) ? key : `${key} — not downloaded`;
+			},
+			pick: async () => {
+				const chosen = await selectSetupModel(
+					"Speech-to-Text model",
+					[...STT_MODEL_OPTIONS],
+					settings.get("stt.modelName"),
+				);
+				if (chosen === null) return false;
+				if (isSttModelKey(chosen)) {
+					settings.set("stt.modelName", chosen);
+					await settings.flush();
+				}
+				return true;
+			},
+			ensure: onProgress =>
+				downloadSttModel(settings.get("stt.modelName"), progress =>
+					onProgress({ stage: `Downloading ${progress.label} model`, percent: progress.percent }),
+				),
+		},
+		{
+			name: "Text-to-Speech model",
+			isReady: () => isTtsModelCached(settings.get("tts.localModel")),
+			status: async () => {
+				const key = settings.get("tts.localModel");
+				return (await isTtsModelCached(key)) ? key : `${key} — model/runtime not installed`;
+			},
+			pick: async () => {
+				const chosen = await selectSetupModel(
+					"Text-to-Speech model",
+					[...TTS_LOCAL_MODEL_OPTIONS],
+					settings.get("tts.localModel"),
+				);
+				if (chosen === null) return false;
+				if (isTtsLocalModelKey(chosen)) {
+					settings.set("tts.localModel", chosen);
+					await settings.flush();
+				}
+				return true;
+			},
+			ensure: async onProgress => {
+				const ok = await downloadTtsModel(settings.get("tts.localModel"), progress =>
+					onProgress({ stage: progress.stage, percent: progress.percent }),
+				);
+				if (!ok) throw new Error("Failed to download the local text-to-speech model.");
+			},
+		},
+	];
+}
 
-	console.log(formatDependencyStatus(status));
+/**
+ * Unified `omp setup speech` flow. Drives every {@link SpeechComponent} through
+ * one path: report (`--json`/`--check`) or install (interactive pick + ensure
+ * with single-line progress; non-TTY skips pickers and installs configured
+ * values).
+ */
+async function handleSpeechSetup(flags: { json?: boolean; check?: boolean }): Promise<void> {
+	await Settings.init({ cwd: getProjectDir() });
+	const components = buildSpeechComponents();
 
-	if (status.recorder.available && status.python.available && status.whisper.available) {
-		console.log(chalk.green(`\n${theme.status.success} Speech-to-text is ready`));
+	if (flags.json) {
+		const report: Record<string, { ready: boolean; status: string }> = {};
+		let allReady = true;
+		for (const component of components) {
+			const ready = await component.isReady();
+			if (!ready) allReady = false;
+			report[component.name] = { ready, status: await component.status() };
+		}
+		console.log(JSON.stringify(report, null, 2));
+		if (!allReady) process.exit(1);
 		return;
 	}
 
 	if (flags.check) {
-		process.exit(1);
-	}
-
-	if (!status.python.available) {
-		console.error(chalk.red(`\n${theme.status.error} Python not found`));
-		console.error(chalk.dim("Install Python 3.8+ and ensure it's in your PATH"));
-		process.exit(1);
-	}
-
-	if (!status.recorder.available) {
-		console.error(chalk.yellow(`\n${theme.status.warning} No recording tool found`));
-		console.error(chalk.dim(status.recorder.installHint));
+		console.log(chalk.bold("Speech dependencies:"));
+		let allReady = true;
+		for (const component of components) {
+			const ready = await component.isReady();
+			if (!ready) allReady = false;
+			const mark = ready ? chalk.green("[ok]") : chalk.yellow("[missing]");
+			console.log(`  ${mark} ${component.name}: ${await component.status()}`);
+		}
+		if (!allReady) process.exit(1);
+		return;
 	}
 
-	if (!status.whisper.available) {
-		console.log(chalk.dim(`\nInstalling openai-whisper...`));
-		const { resolvePython } = await import("../stt/transcriber");
-		const pythonCmd = resolvePython()!;
-		const result = await $`${pythonCmd} -m pip install -q openai-whisper`.nothrow();
-		if (result.exitCode !== 0) {
-			console.error(chalk.red(`\n${theme.status.error} Failed to install openai-whisper`));
-			console.error(chalk.dim("Try manually: pip install openai-whisper"));
+	const interactive = Boolean(process.stdout.isTTY);
+	for (const component of components) {
+		if (interactive && component.pick) {
+			await component.pick();
+		}
+		if (await component.isReady()) {
+			console.log(chalk.green(`${theme.status.success} ${component.name} ready`));
+			continue;
+		}
+		console.log(chalk.dim(`Preparing ${component.name}...`));
+		try {
+			await component.ensure(progress => {
+				const percent = typeof progress.percent === "number" ? ` (${progress.percent}%)` : "";
+				process.stdout.write(`\r${chalk.dim(`${progress.stage}${percent}`)}\x1b[K`);
+			});
+			process.stdout.write("\n");
+		} catch (err) {
+			process.stdout.write("\n");
+			const msg = err instanceof Error ? err.message : `Failed to set up ${component.name}`;
+			console.error(chalk.red(`${theme.status.error} ${msg}`));
 			process.exit(1);
 		}
 	}
 
-	const recheck = await checkDependencies();
-	if (recheck.recorder.available && recheck.python.available && recheck.whisper.available) {
-		console.log(chalk.green(`\n${theme.status.success} Speech-to-text is ready`));
-	} else {
-		console.error(chalk.red(`\n${theme.status.error} Setup incomplete`));
-		console.log(formatDependencyStatus(recheck));
-		process.exit(1);
-	}
+	console.log(chalk.green(`\n${theme.status.success} Speech is ready`));
+	console.log(
+		chalk.dim(
+			"Enable speech-to-text via stt.enabled, then hold Space to talk (or bind app.stt.toggle); enable the speech-generation tool via speechgen.enabled; speak replies aloud via speech.enabled.",
+		),
+	);
 }
 
 /**
@@ -215,7 +316,7 @@ ${chalk.bold("Usage:")}
 
 ${chalk.bold("Components:")}
   python    Verify a Python 3 interpreter is reachable for code execution
-  stt       Install speech-to-text dependencies (openai-whisper, recording tools)
+  speech    Pick + download the speech-to-text and text-to-speech models and an audio recorder
 
 ${chalk.bold("Options:")}
   -c, --check   Check if dependencies are installed without installing
@@ -224,8 +325,8 @@ ${chalk.bold("Options:")}
 ${chalk.bold("Examples:")}
   ${APP_NAME} setup                  Run the onboarding wizard
   ${APP_NAME} setup python           Check Python execution dependencies
-  ${APP_NAME} setup stt              Install speech-to-text dependencies
-  ${APP_NAME} setup stt --check      Check if STT dependencies are available
+  ${APP_NAME} setup speech           Set up speech (pick STT + TTS models, install a recorder)
+  ${APP_NAME} setup speech --check   Check if speech dependencies are available
   ${APP_NAME} setup python --check   Check if Python execution is available
 `);
 }

package/src/cli/setup-model-picker.ts

@@ -0,0 +1,43 @@
+/**
+ * Standalone TUI model picker used by `omp setup speech`.
+ *
+ * Mirrors {@link ./session-picker.ts} for the standalone-TUI lifecycle: spin up
+ * a one-shot {@link TUI} over a {@link SelectList}, resolve on select/cancel, and
+ * tear the UI down. The standalone TUI auto-renders on input, so no manual
+ * render wiring is needed beyond `addChild`/`setFocus`/`start`.
+ */
+import { ProcessTerminal, type SelectItem, SelectList, TUI } from "@oh-my-pi/pi-tui";
+import { getSelectListTheme } from "../modes/theme/theme";
+
+/**
+ * Show a single-column model picker and resolve with the chosen item's value,
+ * or `null` if the user cancelled. `currentValue` pre-selects the matching row.
+ */
+export async function selectSetupModel(
+	title: string,
+	items: SelectItem[],
+	currentValue: string,
+): Promise<string | null> {
+	const { promise, resolve } = Promise.withResolvers<string | null>();
+	const ui = new TUI(new ProcessTerminal());
+	let resolved = false;
+
+	const finish = (value: string | null): void => {
+		if (resolved) return;
+		resolved = true;
+		ui.stop();
+		resolve(value);
+	};
+
+	const list = new SelectList(items, Math.min(items.length, 10), getSelectListTheme());
+	const currentIndex = items.findIndex(item => item.value === currentValue);
+	if (currentIndex >= 0) list.setSelectedIndex(currentIndex);
+	list.onSelect = item => finish(item.value);
+	list.onCancel = () => finish(null);
+
+	process.stdout.write(`${title}\n`);
+	ui.addChild(list);
+	ui.setFocus(list);
+	ui.start();
+	return promise;
+}

package/src/cli-commands.ts

@@ -27,7 +27,9 @@ export const commands: CommandEntry[] = [
 	{ name: "grievances", load: () => import("./commands/grievances").then(m => m.default) },
 	{ name: "install", load: () => import("./commands/install").then(m => m.default) },
 	{ name: "join", load: () => import("./commands/join").then(m => m.default) },
+	{ name: "models", load: () => import("./commands/models").then(m => m.default) },
 	{ name: "plugin", load: () => import("./commands/plugin").then(m => m.default) },
+	{ name: "say", load: () => import("./commands/say").then(m => m.default) },
 	{ name: "setup", load: () => import("./commands/setup").then(m => m.default) },
 	{ name: "shell", load: () => import("./commands/shell").then(m => m.default) },
 	{ name: "read", load: () => import("./commands/read").then(m => m.default) },
@@ -36,6 +38,7 @@ export const commands: CommandEntry[] = [
 	{ name: "update", load: () => import("./commands/update").then(m => m.default) },
 	{ name: "usage", load: () => import("./commands/usage").then(m => m.default) },
 	{ name: "tiny-models", load: () => import("./commands/tiny-models").then(m => m.default) },
+	{ name: "token", load: () => import("./commands/token").then(m => m.default) },
 	{ name: "worktree", load: () => import("./commands/worktree").then(m => m.default), aliases: ["wt"] },
 	{ name: "search", load: () => import("./commands/web-search").then(m => m.default), aliases: ["q"] },
 ];

package/src/cli.ts

@@ -56,6 +56,8 @@ async function showHelp(config: CliConfig): Promise<void> {
 async function runSmokeTest(): Promise<void> {
 	const { smokeTestSyncWorker, startServer } = await import("@oh-my-pi/omp-stats");
 	const { smokeTestTinyTitleWorker } = await import("./tiny/title-client");
+	const { smokeTestSttWorker } = await import("./stt/asr-client");
+	const { smokeTestTtsWorker } = await import("./tts/tts-client");
 	await smokeTestSyncWorker();
 
 	const statsServer = await startServer(0);
@@ -71,6 +73,8 @@ async function runSmokeTest(): Promise<void> {
 	}
 
 	await smokeTestTinyTitleWorker();
+	await smokeTestSttWorker();
+	await smokeTestTtsWorker();
 	process.stdout.write("smoke-test: ok\n");
 }
 
@@ -78,6 +82,8 @@ const TINY_WORKER_ARGS = new Set(["--tiny-worker", "__tiny_worker"]);
 const STATS_SYNC_WORKER_ARG = "__omp_stats_sync_worker";
 const TAB_WORKER_ARG = "__omp_tab_worker";
 const JS_EVAL_WORKER_ARG = "__omp_js_eval_worker";
+const STT_WORKER_ARG = "__omp_stt_worker";
+const TTS_WORKER_ARG = "__omp_tts_worker";
 
 async function runWorkerEntrypoint(arg: string | undefined): Promise<boolean> {
 	if (arg === STATS_SYNC_WORKER_ARG) {
@@ -110,21 +116,34 @@ async function runWorkerEntrypoint(arg: string | undefined): Promise<boolean> {
 		await import("./eval/js/worker-entry");
 		return true;
 	}
+	if (arg === STT_WORKER_ARG) {
+		const { startSttWorker } = await import("./stt/asr-worker");
+		await runIpcSubprocessWorker(startSttWorker);
+		return true;
+	}
+	if (arg === TTS_WORKER_ARG) {
+		const { startTtsWorker } = await import("./tts/tts-worker");
+		await runIpcSubprocessWorker(startTtsWorker);
+		return true;
+	}
 	return false;
 }
 
 /**
- * Hidden subcommand that boots the tiny-model worker inside this process
- * over the parent's IPC channel. The agent's main process spawns the same
- * binary with this flag so `onnxruntime-node` (loaded transitively by
- * `@huggingface/transformers`) lives in a child address space. The parent
- * `SIGKILL`s the child on shutdown so the NAPI finalizer never runs in
- * either process — that finalizer segfaults Bun on Windows (issue #1606).
+ * Boot a subprocess-isolated transformers.js worker over the parent's IPC
+ * channel and block until the parent disconnects. The tiny-model, STT, and TTS
+ * workers each run `onnxruntime-node` (loaded transitively by
+ * `@huggingface/transformers`) in a child address space because its NAPI
+ * finalizer segfaults Bun on shutdown (issue #1606); the parent `SIGKILL`s the
+ * child so that finalizer never runs in either process. This wires `process`
+ * IPC to the worker's typed transport, keeps the event loop alive while the
+ * worker is idle, and hard-kills the process on parent `disconnect`.
  */
-async function runTinyWorker(): Promise<void> {
-	const { startTinyTitleWorker } = await import("./tiny/worker");
+async function runIpcSubprocessWorker<In, Out>(
+	start: (transport: { send(message: Out): void; onMessage(handler: (message: In) => void): () => void }) => void,
+): Promise<void> {
 	const { promise: shuttingDown, resolve: shutdown } = Promise.withResolvers<void>();
-	const send = (message: unknown): void => {
+	const send = (message: Out): void => {
 		// `process.send` only exists when spawned with an IPC channel; the
 		// parent always spawns us that way. If it's missing, the parent
 		// vanished and there's no one to talk to.
@@ -139,10 +158,10 @@ async function runTinyWorker(): Promise<void> {
 			shutdown();
 		}
 	};
-	startTinyTitleWorker({
+	start({
 		send,
 		onMessage(handler) {
-			const wrap = (data: unknown): void => handler(data as never);
+			const wrap = (data: unknown): void => handler(data as In);
 			process.on("message", wrap);
 			return () => {
 				process.off("message", wrap);
@@ -151,8 +170,8 @@ async function runTinyWorker(): Promise<void> {
 	});
 	const keepalive = setInterval(() => {}, 2 ** 30);
 	// Parent went away (crashed, SIGKILL, etc.) — commit suicide so we don't
-	// linger as an orphan. SIGKILL via `process.kill` keeps us symmetrical
-	// with the parent's hard-kill on shutdown: skip every JS/native finalizer.
+	// linger as an orphan. SIGKILL via `process.kill` keeps us symmetrical with
+	// the parent's hard-kill on shutdown: skip every JS/native finalizer.
 	process.on("disconnect", () => shutdown());
 	try {
 		await shuttingDown;
@@ -162,6 +181,19 @@ async function runTinyWorker(): Promise<void> {
 	process.kill(process.pid, "SIGKILL");
 }
 
+/**
+ * Hidden subcommand that boots the tiny-model worker inside this process over
+ * the parent's IPC channel. The agent's main process spawns the same binary
+ * with this flag so `onnxruntime-node` (loaded transitively by
+ * `@huggingface/transformers`) lives in a child address space. The parent
+ * `SIGKILL`s the child on shutdown so the NAPI finalizer never runs in either
+ * process — that finalizer segfaults Bun on Windows (issue #1606).
+ */
+async function runTinyWorker(): Promise<void> {
+	const { startTinyTitleWorker } = await import("./tiny/worker");
+	await runIpcSubprocessWorker(startTinyTitleWorker);
+}
+
 /** Run the CLI with the given argv (no `process.argv` prefix). */
 export async function runCli(argv: string[]): Promise<void> {
 	if (argv[0] === "--smoke-test") {

package/src/collab/host.ts

@@ -20,7 +20,7 @@ import { AgentLifecycleManager } from "../registry/agent-lifecycle";
 import { AgentRegistry } from "../registry/agent-registry";
 import type { AgentSessionEvent } from "../session/agent-session";
 import { stripImagesFromMessage, USER_INTERRUPT_LABEL } from "../session/messages";
-import type { SessionEntry as StoredSessionEntry } from "../session/session-manager";
+import type { SessionEntry as StoredSessionEntry } from "../session/session-entries";
 import { TASK_SUBAGENT_LIFECYCLE_CHANNEL, TASK_SUBAGENT_PROGRESS_CHANNEL } from "../task";
 import { generateRoomKey, generateWriteToken, importRoomKey } from "./crypto";
 import {
@@ -365,13 +365,8 @@ export class CollabHost {
 		const name = peer.name;
 		const content: string | (TextContent | ImageContent)[] =
 			images && images.length > 0 ? [{ type: "text", text }, ...images] : text;
-		const details: CollabPromptDetails & { __pendingDisplayTag?: string } = { from: name };
+		const details: CollabPromptDetails = { from: name };
 		if (this.#ctx.session.isStreaming) {
-			// Mid-turn guest prompts are steered: register the pending-display twin
-			// so queuedMessageCount reflects the queued steer (host pending bar +
-			// guests' "queued ×N" badge). The tag dequeues the entry when the agent
-			// consumes the message (mirrors the skill-prompt path).
-			details.__pendingDisplayTag = this.#ctx.session.enqueueCustomMessageDisplay(text, "steer");
 			this.#ctx.updatePendingMessagesDisplay();
 			this.#ctx.ui.requestRender();
 			this.#scheduleStateBroadcast();
@@ -385,7 +380,7 @@ export class CollabHost {
 					details,
 					attribution: "user",
 				},
-				{ streamingBehavior: "steer" },
+				{ streamingBehavior: "steer", queueChipText: text },
 			)
 			.catch(err => {
 				logger.warn("collab guest prompt failed", { error: String(err) });
@@ -416,21 +411,23 @@ export class CollabHost {
 
 	#buildState(): CollabSessionState {
 		const session = this.#ctx.session;
-		// Context numbers come from the status line's breakdown — not
-		// session.getContextUsage() — so guests render exactly what the host's
-		// own footer shows.
+		// Context numbers come from the status line's memoized breakdown so guests
+		// render exactly the same anchored, provider-real count the host's own
+		// status line shows.
 		const breakdown = this.#ctx.statusLine.getCachedContextBreakdown();
+		const tokens = breakdown.usedTokens;
 		return {
 			isStreaming: session.isStreaming,
+			isAborting: session.isAborting,
 			queuedMessageCount: session.queuedMessageCount,
 			sessionName: session.sessionName,
 			cwd: this.#ctx.sessionManager.getCwd(),
 			model: session.model,
 			thinkingLevel: session.thinkingLevel,
 			contextUsage: {
-				tokens: breakdown.usedTokens,
+				tokens,
 				contextWindow: breakdown.contextWindow,
-				percent: breakdown.contextWindow > 0 ? (breakdown.usedTokens / breakdown.contextWindow) * 100 : null,
+				percent: tokens !== null && breakdown.contextWindow > 0 ? (tokens / breakdown.contextWindow) * 100 : null,
 			},
 			participants: this.participants,
 		};

package/src/collab/protocol.ts

@@ -25,7 +25,7 @@ import {
 } from "@oh-my-pi/pi-wire";
 import type { ContextUsage } from "../extensibility/extensions/types";
 import type { AgentSessionEvent } from "../session/agent-session";
-import type { SessionEntry, SessionHeader } from "../session/session-manager";
+import type { SessionEntry, SessionHeader } from "../session/session-entries";
 
 export type {
 	CollabPromptDetails,

package/src/commands/launch.ts

@@ -124,9 +124,6 @@ export default class Index extends Command {
 		export: Flags.string({
 			description: "Export session file to HTML and exit",
 		}),
-		"list-models": Flags.string({
-			description: "List available models (with optional fuzzy search)",
-		}),
 		"no-title": Flags.boolean({
 			description: "Disable title auto-generation",
 		}),

package/src/commands/models.ts

@@ -0,0 +1,61 @@
+/**
+ * List, search, and refresh available models.
+ */
+import { APP_NAME } from "@oh-my-pi/pi-utils";
+import { Args, Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { resolveModelsArgs, runModelsCommand } from "../cli/models-cli";
+
+export default class Models extends Command {
+	static description = "List, search, and refresh available models";
+
+	static args = {
+		action: Args.string({
+			description: "ls (default) | find | refresh | canonical | <provider>",
+			required: false,
+		}),
+		pattern: Args.string({
+			description: "Filter/search substring, or provider name (required for find)",
+			required: false,
+		}),
+	};
+
+	static flags = {
+		json: Flags.boolean({ description: "Output JSON" }),
+		extension: Flags.string({
+			char: "e",
+			description: "Load an extension file before listing (repeatable)",
+			multiple: true,
+		}),
+		"no-extensions": Flags.boolean({
+			description: "Disable extension discovery (explicit -e paths still work)",
+		}),
+		config: Flags.string({
+			description: "Load an extra config.yml-style overlay for this run (repeatable)",
+			multiple: true,
+		}),
+	};
+
+	static examples = [
+		`# List every available model, grouped by provider\n  ${APP_NAME} models`,
+		`# List one provider's models (any provider name works)\n  ${APP_NAME} models openai-codex`,
+		`# Find models by substring\n  ${APP_NAME} models find minimax`,
+		`# Force a fresh catalog fetch (replaces rm -rf ~/.omp/models.db)\n  ${APP_NAME} models refresh`,
+		`# Show the coalesced canonical model view\n  ${APP_NAME} models canonical`,
+		`# Machine-readable output\n  ${APP_NAME} models --json`,
+	];
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(Models);
+		const { action, pattern } = resolveModelsArgs(args.action, args.pattern);
+		await runModelsCommand({
+			action,
+			pattern,
+			flags: {
+				json: flags.json,
+				extensions: flags.extension,
+				noExtensions: flags["no-extensions"],
+				config: flags.config,
+			},
+		});
+	}
+}