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

package/src/autolearn/managed-skills.ts

@@ -0,0 +1,257 @@
+/**
+ * Managed-skills primitives for the experimental auto-learn feature.
+ *
+ * Managed skills are auto-generated/enhanced `SKILL.md` files kept in an
+ * isolated directory (`~/.omp/agent/managed-skills`) separate from
+ * user-authored skills (`~/.omp/agent/skills`). They are discovered and
+ * surfaced like normal skills, but every write here is confined to
+ * `getManagedSkillsDir()` — auto-management can never touch authored skills.
+ */
+import { constants as fsConstants, type Stats } from "node:fs";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { isEnoent } from "@oh-my-pi/pi-utils";
+import { YAML } from "bun";
+import { SOURCE_PATHS } from "../discovery/helpers";
+
+/** Provider id stamped on discovered managed skills (distinguishes them from authored). */
+export const MANAGED_SKILLS_PROVIDER_ID = "omp-managed";
+
+/** Hard cap on a managed SKILL.md body to keep generated skills bounded. */
+export const MAX_MANAGED_SKILL_BYTES = 64_000;
+
+const SKILL_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+/** Resolve the isolated managed-skills directory (`~/.omp/agent/managed-skills`). */
+export function getManagedSkillsDir(home: string = os.homedir()): string {
+	return path.join(home, SOURCE_PATHS.native.userAgent, "managed-skills");
+}
+
+/**
+ * Validate + normalize a managed-skill name. Throws on anything outside the
+ * strict allowlist so a bad name can never escape `getManagedSkillsDir()`
+ * (blocks `..`, slashes, empty, and uppercase).
+ */
+export function sanitizeSkillName(raw: string): string {
+	const name = raw.trim().toLowerCase();
+	if (!SKILL_NAME_PATTERN.test(name)) {
+		throw new Error(
+			`Invalid skill name "${raw}". Use lowercase letters, digits, and hyphens (1-64 chars, starting with a letter or digit).`,
+		);
+	}
+	return name;
+}
+
+/**
+ * Whether `name` is a safe managed-skill name (the exact post-sanitize shape).
+ * Used to validate names read from disk at discovery time — a managed
+ * `SKILL.md` whose `frontmatter.name` was not produced by `sanitizeSkillName`
+ * (e.g. hand-placed) must not render unescaped into the system prompt.
+ */
+export function isValidManagedSkillName(name: string): boolean {
+	return SKILL_NAME_PATTERN.test(name);
+}
+
+/**
+ * Neutralize a machine-generated managed-skill description so it cannot break
+ * out of the system prompt's `<skills>` listing. Managed descriptions are
+ * generated from prior task content and persist across sessions, so this is a
+ * trust boundary: strip control/format chars, angle brackets (`<system-directive>`
+ * / `</skills>`), and Markdown fence delimiters (backticks, `~~~`), then collapse
+ * to a single line. Applied on BOTH write and read so existing files are safe too.
+ */
+export function sanitizeManagedDescription(raw: string): string {
+	return raw
+		.replace(/[\p{Cc}\p{Cf}]/gu, " ")
+		.replace(/[<>`]/g, "")
+		.replace(/~{2,}/g, "~")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+/**
+ * Serialize the minimal `name`/`description` frontmatter block via the repo's
+ * YAML helper (round-trips through `parseFrontmatter`).
+ */
+export function toSkillFrontmatter(name: string, description: string): string {
+	const frontmatter = YAML.stringify(
+		{ name, description: sanitizeManagedDescription(description) },
+		null,
+		2,
+	).trimEnd();
+	return `---\n${frontmatter}\n---\n`;
+}
+
+export interface WriteManagedSkillInput {
+	action: "create" | "update";
+	name: string;
+	description: string;
+	body: string;
+}
+
+/**
+ * Serialize create/update/delete on the same skill name. Both tools are
+ * non-exclusive, so a parallel tool batch in one turn can run two mutations on
+ * the same skill at once (e.g. an update observing the file mid-delete). This
+ * per-name promise chain runs same-skill mutations in submission order while
+ * different names still proceed in parallel. In-process only; cross-process
+ * races are out of scope.
+ */
+const skillMutationChains = new Map<string, Promise<unknown>>();
+function serializeSkillMutation<T>(name: string, op: () => Promise<T>): Promise<T> {
+	const prev = skillMutationChains.get(name) ?? Promise.resolve();
+	const run = prev.then(op, op);
+	const guarded = run.catch(() => {});
+	skillMutationChains.set(name, guarded);
+	void guarded.finally(() => {
+		if (skillMutationChains.get(name) === guarded) skillMutationChains.delete(name);
+	});
+	return run;
+}
+
+/**
+ * Reject when the managed-skills root itself is a symlink. lstat on a child
+ * follows intermediate components, so a symlinked root would let an otherwise
+ * valid name write/delete outside the isolated directory (e.g. onto authored
+ * skills). Checked before composing any child path.
+ */
+async function assertManagedRootSafe(): Promise<void> {
+	const rootStat = await fs.lstat(getManagedSkillsDir()).catch(err => {
+		if (isEnoent(err)) return null;
+		throw err;
+	});
+	if (rootStat?.isSymbolicLink()) {
+		throw new Error("The managed-skills root is a symlink; refusing to operate outside the managed directory.");
+	}
+}
+
+const UPDATE_FILE_OPEN_FLAGS = fsConstants.O_WRONLY | fsConstants.O_NOFOLLOW;
+
+function assertManagedSkillFileSafeForUpdate(name: string, fileStat: Stats): void {
+	if (!fileStat.isFile()) {
+		throw new Error(`Managed skill "${name}" SKILL.md is not a regular file; refusing to overwrite it.`);
+	}
+	if (fileStat.nlink > 1) {
+		throw new Error(
+			`Managed skill "${name}" SKILL.md has ${fileStat.nlink} hard links; refusing to overwrite a file that may be user-authored elsewhere.`,
+		);
+	}
+}
+
+async function openManagedSkillFileForUpdate(name: string, file: string) {
+	try {
+		return await fs.open(file, UPDATE_FILE_OPEN_FLAGS);
+	} catch (err) {
+		if ((err as { code?: string }).code === "ELOOP") {
+			throw new Error(`Managed skill "${name}" SKILL.md is a symlink; refusing to overwrite it.`);
+		}
+		throw err;
+	}
+}
+
+/** Create or update a managed `SKILL.md`. Returns the resolved file path. */
+export async function writeManagedSkill(input: WriteManagedSkillInput): Promise<{ path: string }> {
+	const name = sanitizeSkillName(input.name);
+	const description = sanitizeManagedDescription(input.description);
+	const body = input.body.trim();
+	// Reject empty content: an all-whitespace/control description sanitizes to ""
+	// and the `requireDescription` discovery scan then silently drops the skill,
+	// so the tool would report success for a skill that never appears.
+	if (!description) {
+		throw new Error(`Managed skill "${name}" needs a non-empty description.`);
+	}
+	if (!body) {
+		throw new Error(`Managed skill "${name}" needs a non-empty body.`);
+	}
+	const content = `${toSkillFrontmatter(name, description)}\n${body}\n`;
+	// Cap the UTF-8 byte size of the FINAL file (body + description + frontmatter),
+	// not the UTF-16 code-unit length of the body alone.
+	const bytes = Buffer.byteLength(content, "utf8");
+	if (bytes > MAX_MANAGED_SKILL_BYTES) {
+		throw new Error(
+			`Managed skill is ${bytes} bytes; the limit is ${MAX_MANAGED_SKILL_BYTES}. Trim the body or description.`,
+		);
+	}
+	return serializeSkillMutation(name, async () => {
+		await assertManagedRootSafe();
+		const dir = path.join(getManagedSkillsDir(), name);
+		const file = path.join(dir, "SKILL.md");
+		// Reject a symlinked skill directory: an intermediate symlink would let the
+		// write escape the isolated managed root. lstat does not follow the final
+		// component, so a symlinked `dir` is caught here.
+		const dirStat = await fs.lstat(dir).catch(err => {
+			if (isEnoent(err)) return null;
+			throw err;
+		});
+		if (dirStat?.isSymbolicLink()) {
+			throw new Error(
+				`Managed skill "${name}" resolves through a symlink; refusing to write outside the managed directory.`,
+			);
+		}
+		if (input.action === "create") {
+			await fs.mkdir(dir, { recursive: true });
+			// O_CREAT|O_EXCL ("wx"): atomic create that fails if the file already
+			// exists (closing the check-then-write race) and refuses a symlinked SKILL.md.
+			try {
+				await fs.writeFile(file, content, { flag: "wx" });
+			} catch (err) {
+				if ((err as { code?: string }).code === "EEXIST") {
+					throw new Error(`Managed skill "${name}" already exists. Use action "update" to change it.`);
+				}
+				throw err;
+			}
+			return { path: file };
+		}
+		// update: the file must already exist, be a plain managed file, and must
+		// not share an inode with a user-authored file via hard link. Open the
+		// checked file handle before truncating so a path swap after lstat cannot
+		// redirect the write into a symlink or newly hard-linked target.
+		const fileStat = await fs.lstat(file).catch(err => {
+			if (isEnoent(err)) return null;
+			throw err;
+		});
+		if (fileStat === null) {
+			throw new Error(`Managed skill "${name}" does not exist. Use action "create" to add it.`);
+		}
+		if (fileStat.isSymbolicLink()) {
+			throw new Error(`Managed skill "${name}" SKILL.md is a symlink; refusing to overwrite it.`);
+		}
+		assertManagedSkillFileSafeForUpdate(name, fileStat);
+		const handle = await openManagedSkillFileForUpdate(name, file);
+		try {
+			const openStat = await handle.stat();
+			assertManagedSkillFileSafeForUpdate(name, openStat);
+			await handle.truncate(0);
+			await handle.writeFile(content);
+		} finally {
+			await handle.close();
+		}
+		return { path: file };
+	});
+}
+
+/** Delete a managed skill directory. Throws when it does not exist. */
+export async function deleteManagedSkill(name: string): Promise<void> {
+	const safe = sanitizeSkillName(name);
+	await serializeSkillMutation(safe, async () => {
+		await assertManagedRootSafe();
+		const dir = path.join(getManagedSkillsDir(), safe);
+		// Refuse to follow a symlinked skill directory (rm would delete the target).
+		const dirStat = await fs.lstat(dir).catch(err => {
+			if (isEnoent(err)) return null;
+			throw err;
+		});
+		if (dirStat?.isSymbolicLink()) {
+			throw new Error(`Managed skill "${safe}" is a symlink; refusing to delete outside the managed directory.`);
+		}
+		try {
+			await fs.rm(dir, { recursive: true });
+		} catch (err) {
+			if (isEnoent(err)) {
+				throw new Error(`Managed skill "${safe}" does not exist.`);
+			}
+			throw err;
+		}
+	});
+}

package/src/autoresearch/state.ts

@@ -1,4 +1,4 @@
-import type { SessionEntry } from "../session/session-manager";
+import type { SessionEntry } from "../session/session-entries";
 import { inferMetricUnitFromName, isBetter } from "./helpers";
 import type { RunRow, SessionRow } from "./storage";
 import type {

package/src/autoresearch/types.ts

@@ -1,6 +1,6 @@
 import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
 import type { ExtensionAPI, ExtensionContext } from "../extensibility/extensions";
-import type { SessionEntry } from "../session/session-manager";
+import type { SessionEntry } from "../session/session-entries";
 import type { TruncationResult } from "../session/streaming-output";
 
 export type MetricDirection = "lower" | "higher";

package/src/cli/args.ts

@@ -53,8 +53,19 @@ export interface Args {
 	approvalMode?: "always-ask" | "write" | "yolo";
 	messages: string[];
 	fileArgs: string[];
-	/** Unknown flags (potentially extension flags) - map of flag name to value */
+	/** Extension-registered flags this parse recognized — name to value. */
 	unknownFlags: Map<string, boolean | string>;
+	/**
+	 * `--`/`-` prefixed tokens this parse could not match against any built-in
+	 * or {@link extensionFlags} entry. The startup parse runs *before*
+	 * extensions load, so it always lists every extension-registered flag here;
+	 * the post-extension reparse in {@link applyExtensionFlags} clears those
+	 * once the real flag set is known. Anything still present after that
+	 * reparse is a genuine typo or stale flag and {@link reportUnrecognizedFlags}
+	 * surfaces it as a hard error so the agent does not silently start a
+	 * session with the misparsed positionals as a prompt (issue #2459).
+	 */
+	unrecognizedFlags: string[];
 }
 
 export function parseArgs(inputArgs: string[], extensionFlags?: Map<string, { type: "boolean" | "string" }>): Args {
@@ -67,12 +78,23 @@ export function parseArgs(inputArgs: string[], extensionFlags?: Map<string, { ty
 		messages: [],
 		fileArgs: [],
 		unknownFlags: new Map(),
+		unrecognizedFlags: [],
 	};
 
+	let sawSeparator = false;
 	for (let i = 0; i < args.length; i++) {
 		let arg = args[i];
 		const flagIndex = i;
 
+		// POSIX positional separator: once `--` lands, every remaining token is
+		// a positional regardless of shape. Without this, a flag-looking message
+		// (`omp -p -- --explain-this`) would be re-validated by the loop below
+		// and rejected by the unknown-flag guard (#2461 review).
+		if (sawSeparator) {
+			result.messages.push(arg);
+			continue;
+		}
+
 		// Support --flag=value syntax (e.g. --tools=ask,read). The value is
 		// spliced in as the next token so value-consuming flags pick it up via
 		// `args[++i]`; a non-consuming flag (e.g. a boolean) leaves it behind and
@@ -229,8 +251,22 @@ export function parseArgs(inputArgs: string[], extensionFlags?: Map<string, { ty
 			result.skills = args[++i].split(",").map(s => s.trim());
 		} else if (arg.startsWith("@")) {
 			result.fileArgs.push(arg.slice(1)); // Remove @ prefix
-		} else if (!arg.startsWith("-")) {
+		} else if (!arg.startsWith("-") || arg === "-") {
+			// Plain positional or lone `-` (stdin marker) — pass through as a
+			// message rather than flagging it.
 			result.messages.push(arg);
+		} else if (arg === "--") {
+			// POSIX positional separator: drop the token and switch the loop
+			// into "everything from here is a positional" mode. The guard at
+			// the top of the loop body handles the remaining tokens.
+			sawSeparator = true;
+		} else {
+			// Flag-shaped (`-x`, `--name`) but unrecognized at this parse. Record
+			// it so the post-extension reparse can decide whether to surface it
+			// as a hard error. `--flag=value` already split `value` into the next
+			// slot; the standard "drop unconsumed equals value" guard below
+			// removes it so it does not leak into messages (issue #2459).
+			result.unrecognizedFlags.push(arg);
 		}
 		// Drop an unconsumed `--flag=value` value (e.g. a boolean flag): when no
 		// branch advanced past the spliced token, remove it so it does not fall
@@ -243,6 +279,24 @@ export function parseArgs(inputArgs: string[], extensionFlags?: Map<string, { ty
 	return result;
 }
 
+/**
+ * Emit a stderr error listing the unrecognized flags and return `true` when
+ * there were any. Caller is expected to exit with a non-zero status. Splitting
+ * the print from the exit keeps the helper unit-testable without forking a
+ * process (issue #2459).
+ */
+export function reportUnrecognizedFlags(
+	args: Pick<Args, "unrecognizedFlags">,
+	write: (text: string) => void = text => process.stderr.write(text),
+): boolean {
+	if (args.unrecognizedFlags.length === 0) return false;
+	const flags = args.unrecognizedFlags;
+	const plural = flags.length === 1 ? "" : "s";
+	write(`${chalk.red(`Error: unknown flag${plural}: ${flags.join(", ")}`)}\n`);
+	write(`Run \`${APP_NAME} --help\` for available flags.\n`);
+	return true;
+}
+
 export function getExtraHelpText(): string {
 	return `${chalk.bold("Environment Variables:")}
   ${chalk.dim("# Core Providers")}

package/src/cli/session-picker.ts

@@ -2,7 +2,8 @@ import { ProcessTerminal, TUI } from "@oh-my-pi/pi-tui";
 import { logger } from "@oh-my-pi/pi-utils";
 import { SessionSelectorComponent } from "../modes/components/session-selector";
 import { HistoryStorage } from "../session/history-storage";
-import { type SessionInfo, SessionManager } from "../session/session-manager";
+import type { SessionInfo } from "../session/session-listing";
+import { SessionManager } from "../session/session-manager";
 import { FileSessionStorage } from "../session/session-storage";
 
 /**

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;
+}