@oh-my-pi/pi-coding-agent 17.2.3 → 17.2.5

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "17.2.3",
+	"version": "17.2.5",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -52,17 +52,17 @@
 		"@agentclientprotocol/sdk": "1.2.1",
 		"@babel/parser": "^7.29.7",
 		"@mozilla/readability": "^0.6.0",
-		"@oh-my-pi/hashline": "17.2.3",
-		"@oh-my-pi/omp-stats": "17.2.3",
-		"@oh-my-pi/pi-agent-core": "17.2.3",
-		"@oh-my-pi/pi-ai": "17.2.3",
-		"@oh-my-pi/pi-catalog": "17.2.3",
-		"@oh-my-pi/pi-mnemopi": "17.2.3",
-		"@oh-my-pi/pi-natives": "17.2.3",
-		"@oh-my-pi/pi-tui": "17.2.3",
-		"@oh-my-pi/pi-utils": "17.2.3",
-		"@oh-my-pi/pi-wire": "17.2.3",
-		"@oh-my-pi/snapcompact": "17.2.3",
+		"@oh-my-pi/hashline": "17.2.5",
+		"@oh-my-pi/omp-stats": "17.2.5",
+		"@oh-my-pi/pi-agent-core": "17.2.5",
+		"@oh-my-pi/pi-ai": "17.2.5",
+		"@oh-my-pi/pi-catalog": "17.2.5",
+		"@oh-my-pi/pi-mnemopi": "17.2.5",
+		"@oh-my-pi/pi-natives": "17.2.5",
+		"@oh-my-pi/pi-tui": "17.2.5",
+		"@oh-my-pi/pi-utils": "17.2.5",
+		"@oh-my-pi/pi-wire": "17.2.5",
+		"@oh-my-pi/snapcompact": "17.2.5",
 		"@opentelemetry/api": "^1.9.1",
 		"@opentelemetry/api-logs": "^0.220.0",
 		"@opentelemetry/context-async-hooks": "^2.9.0",

package/scripts/legacy-pi-virtual-module.ts

@@ -142,7 +142,13 @@ export async function collectBundledPiEntries(): Promise<BundledPiEntry[]> {
 
 			const sourceDir = path.join(packageRoot, pattern.sourcePrefix);
 			try {
-				const glob = new Bun.Glob(`*${pattern.sourceSuffix}`);
+				// Recursive on purpose: Node matches `*` in an `exports` pattern across
+				// `/`, so `./slash-commands/*` genuinely serves
+				// `slash-commands/helpers/active-oauth-account`. Enumerating only the
+				// top level left every nested key out of the compiled registry, where
+				// it fell through to `Bun.resolveSync` and died under bunfs — so such
+				// an import worked from source and failed inside a binary.
+				const glob = new Bun.Glob(`**/*${pattern.sourceSuffix}`);
 				const matches: string[] = [];
 				for await (const match of glob.scan({ cwd: sourceDir, onlyFiles: true })) {
 					matches.push(match);
@@ -151,7 +157,11 @@ export async function collectBundledPiEntries(): Promise<BundledPiEntry[]> {
 				for (const match of matches) {
 					if (!match.endsWith(pattern.sourceSuffix)) continue;
 					const basename = match.slice(0, match.length - pattern.sourceSuffix.length);
-					if (!isSafeWildcardBasename(basename) || basename.includes("/")) continue;
+					const segments = basename.split("/");
+					// Every directory on the way has to be importable too: a private or
+					// hidden folder is no more exported than a private file.
+					if (segments.some(segment => segment.startsWith(".") || segment.startsWith("_"))) continue;
+					if (!isSafeWildcardBasename(segments.at(-1) ?? "")) continue;
 					const subpath = `${pattern.exportPrefix}${basename}${pattern.exportSuffix}`;
 					const key = `${manifest.name}/${subpath}`;
 					addEntry(key, bindingForSubpath(pkg.identifier, subpath), key);

package/src/advisor/advise-tool.ts

@@ -180,12 +180,23 @@ export class AdviseTool implements AgentTool<typeof adviseSchema, AdviseDetails>
 	 *  escalation: nit → concern → blocker), so an advisor cannot bypass dedupe
 	 *  by retagging the same text at a lower or equal severity. */
 	#deliveredNoteSeverities = new Map<string, number>();
+	#inProgressUpdate = false;
 
 	constructor(private readonly onAdvice: (note: string, severity?: AdviseDetails["severity"]) => void) {}
 
+	/**
+	 * Mark whether the next advisor prompt reviews an in-progress primary turn.
+	 * Non-blockers are withheld until a completed update so partial work does
+	 * not interrupt the primary before it can finish its planned steps.
+	 */
+	beginUpdate(inProgress: boolean): void {
+		this.#inProgressUpdate = inProgress;
+	}
+
 	/** Clear delivered-note memory when the advisor starts a fresh conversation. */
 	resetDeliveredNotes(): void {
 		this.#deliveredNoteSeverities.clear();
+		this.#inProgressUpdate = false;
 	}
 
 	async execute(
@@ -195,6 +206,13 @@ export class AdviseTool implements AgentTool<typeof adviseSchema, AdviseDetails>
 		_onUpdate?: AgentToolUpdateCallback<AdviseDetails>,
 		_context?: AgentToolContext,
 	): Promise<AgentToolResult<AdviseDetails>> {
+		if (this.#inProgressUpdate && args.severity !== "blocker") {
+			return {
+				content: [{ type: "text", text: "Recorded." }],
+				details: { note: args.note, severity: args.severity },
+				useless: true,
+			};
+		}
 		const key = advisorNoteDedupeKey(args.note);
 		const rank = advisorSeverityRank(args.severity);
 		const previousRank = this.#deliveredNoteSeverities.get(key) ?? 0;

package/src/advisor/runtime.ts

@@ -51,11 +51,11 @@ export interface AdvisorRuntimeHost {
 	maintainContext?(incomingTokens: number, signal: AbortSignal): Promise<boolean>;
 	/**
 	 * Called immediately before each `agent.prompt(batch)` cycle. Lets the host
-	 * clear per-update advisor state — currently the one-advise-per-update gate
-	 * in {@link AdvisorEmissionGuard}, which the host owns because it is the
-	 * one that routes `advise()` results back to the primary.
+	 * clear per-update advisor state and apply the in-progress delivery policy.
+	 * The host owns these gates because it routes `advise()` results back to the
+	 * primary.
 	 */
-	beginAdvisorUpdate?(): void;
+	beginAdvisorUpdate?(inProgress: boolean): void;
 	/**
 	 * Called with the error of every failed advisor turn, before the retry sleep
 	 * or the dropped-after-3 path. Lets the host apply credential-level remedies
@@ -909,8 +909,8 @@ export class AdvisorRuntime {
 				const contextWasFresh = resetContext || recoveringOverflow || messageSnapshot === 0;
 				try {
 					// Reset the host's per-update advisor state (one-advise-per-update
-					// gate) before each model cycle so the new batch starts fresh.
-					this.host.beginAdvisorUpdate?.();
+					// gate) and pass through whether this batch reviews partial work.
+					this.host.beginAdvisorUpdate?.(wip);
 					const prompt = this.agent.prompt(batch);
 					this.#promptInFlight = prompt;
 					try {

package/src/capability/mcp.ts

@@ -4,6 +4,8 @@
  * Canonical shape for MCP server configurations, regardless of source format.
  * All providers translate their native format to this shape.
  */
+
+import type { MCPRequestIdFormat } from "../mcp/types";
 import { defineCapability } from ".";
 import type { SourceMeta } from "./types";
 
@@ -17,6 +19,8 @@ export interface MCPServer {
 	enabled?: boolean;
 	/** Connection timeout in milliseconds */
 	timeout?: number;
+	/** Encoding for outgoing JSON-RPC request ids (default: `"number"`) */
+	requestIdFormat?: MCPRequestIdFormat;
 	/** Command to run (for stdio transport) */
 	command?: string;
 	/** Command arguments */
@@ -56,6 +60,9 @@ export interface MCPServer {
 /** Compare the transport inputs that determine which MCP endpoint gets connected. */
 function isSameMCPConnection(left: MCPServer, right: MCPServer): boolean {
 	if (!Bun.deepEquals(left.auth, right.auth) || !Bun.deepEquals(left.oauth, right.oauth)) return false;
+	// Normalize against the allocator's own default so an explicit "number" is
+	// equivalent to leaving the option unset, not a distinct connection.
+	if ((left.requestIdFormat ?? "number") !== (right.requestIdFormat ?? "number")) return false;
 
 	const leftTransport = left.transport ?? (left.command ? "stdio" : left.url ? "http" : "stdio");
 	const rightTransport = right.transport ?? (right.command ? "stdio" : right.url ? "http" : "stdio");

package/src/cli/args.ts

@@ -1,8 +1,9 @@
 /**
  * CLI argument parsing and help display
  */
-import { APP_NAME, CONFIG_DIR_NAME, logger } from "@oh-my-pi/pi-utils";
+import { $env, APP_NAME, logger } from "@oh-my-pi/pi-utils";
 import chalk from "chalk";
+import type { ServiceTierOpenAISettingValue } from "../config/service-tier";
 import { CLI_THINKING_LEVELS, type ConfiguredThinkingLevel, parseCliThinkingLevel } from "../thinking";
 import { BUILTIN_TOOL_NAMES, HIDDEN_TOOL_NAMES, normalizeToolNames } from "../tools/builtin-names";
 import {
@@ -13,8 +14,11 @@ import {
 	STRING_SETTERS,
 	STRING_VALUE_FLAGS,
 } from "./flag-tables";
+import { getExtraHelpText } from "./help-extra";
 import { CliUsageError } from "./usage-error";
 
+export { getExtraHelpText };
+
 export type Mode = "text" | "json" | "rpc" | "acp" | "rpc-ui";
 
 export interface Args {
@@ -40,6 +44,7 @@ export interface Args {
 	systemPrompt?: string;
 	appendSystemPrompt?: string;
 	thinking?: ConfiguredThinkingLevel;
+	serviceTier?: ServiceTierOpenAISettingValue;
 	hideThinking?: boolean;
 	advisor?: boolean;
 	continue?: boolean;
@@ -145,6 +150,7 @@ export function parseArgs(inputArgs: string[], extensionFlags?: Map<string, { ty
 		fileArgs: [],
 		unknownFlags: new Map(),
 		unrecognizedFlags: [],
+		sessionDir: $env.PI_CODING_AGENT_SESSION_DIR || undefined,
 	};
 
 	// `--` ends option parsing (POSIX end-of-options). Everything after it is
@@ -330,92 +336,6 @@ export function reportCliUsageError(
 	return true;
 }
 
-export function getExtraHelpText(): string {
-	return `${chalk.bold("Environment Variables:")}
-  ${chalk.dim("# Core Providers")}
-  ANTHROPIC_API_KEY          - Anthropic Claude models
-  ANTHROPIC_OAUTH_TOKEN      - Anthropic OAuth (takes precedence over API key)
-  CLAUDE_CODE_USE_FOUNDRY    - Enable Anthropic Foundry mode (uses Foundry endpoint + mTLS)
-  FOUNDRY_BASE_URL           - Anthropic Foundry base URL (e.g., https://<foundry-host>)
-  ANTHROPIC_FOUNDRY_API_KEY  - Anthropic token used as Authorization: Bearer <token> in Foundry mode
-  ANTHROPIC_CUSTOM_HEADERS   - Extra headers for Foundry or any custom ANTHROPIC_BASE_URL gateway (e.g., "user-id: USERNAME")
-  CLAUDE_CODE_CLIENT_CERT    - Client certificate (PEM path or inline PEM) for mTLS
-  CLAUDE_CODE_CLIENT_KEY     - Client private key (PEM path or inline PEM) for mTLS
-  NODE_EXTRA_CA_CERTS        - CA bundle path (or inline PEM) for server certificate validation
-  OPENAI_API_KEY             - OpenAI GPT models
-  GEMINI_API_KEY             - Google Gemini models
-  COPILOT_GITHUB_TOKEN      - GitHub Copilot
-
-  ${chalk.dim("# Additional LLM Providers")}
-  AZURE_OPENAI_API_KEY       - Azure OpenAI models
-  GROQ_API_KEY               - Groq models
-  CEREBRAS_API_KEY           - Cerebras models
-  XAI_API_KEY                - xAI Grok models
-  OPENROUTER_API_KEY         - OpenRouter aggregated models
-  KILO_API_KEY               - Kilo Gateway models
-  MISTRAL_API_KEY            - Mistral models
-  ZAI_API_KEY                - z.ai models (ZhipuAI/GLM)
-  UMANS_AI_CODING_PLAN_API_KEY - Umans AI Coding Plan models
-  UMANS_WEBSEARCH_PROVIDER    - Umans gateway web search backend (native or exa)
-  MINIMAX_API_KEY            - MiniMax models
-  OPENCODE_API_KEY           - OpenCode Zen/OpenCode Go models
-  CURSOR_ACCESS_TOKEN        - Cursor AI models
-  AI_GATEWAY_API_KEY         - Vercel AI Gateway
-  WAFER_SERVERLESS_API_KEY   - Wafer Serverless (pay-as-you-go)
-
-  ${chalk.dim("# Cloud Providers")}
-  AWS_PROFILE                - AWS Bedrock (or AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY)
-  GOOGLE_CLOUD_PROJECT       - Google Vertex AI (requires GOOGLE_CLOUD_LOCATION)
-  GOOGLE_APPLICATION_CREDENTIALS - Service account for Vertex AI
-
-  ${chalk.dim("# Search & Tools")}
-  EXA_API_KEY                - Exa web search
-  BRAVE_API_KEY              - Brave web search
-  PERPLEXITY_API_KEY         - Perplexity web search API key (optional; anonymous fallback)
-  PERPLEXITY_COOKIES         - Perplexity web search (session cookie)
-  TAVILY_API_KEY             - Tavily web search
-  TINYFISH_API_KEY           - TinyFish web search
-  FIRECRAWL_API_KEY          - Firecrawl web search
-  ANTHROPIC_SEARCH_API_KEY   - Anthropic web search (override; isolates search from main ANTHROPIC_API_KEY)
-  ANTHROPIC_SEARCH_BASE_URL  - Anthropic web search base URL (override; pairs with ANTHROPIC_SEARCH_API_KEY)
-
-  ${chalk.dim("# Configuration")}
-  OMP_PROFILE                 - Named profile for isolated agent state (same as --profile)
-  Use \`omp --profile <name> --alias <command>\` to create a shell shortcut for a profile
-  PI_CODING_AGENT_DIR        - Session storage directory (default: ~/${CONFIG_DIR_NAME}/agent)
-  PI_PACKAGE_DIR             - Override package directory (for Nix/Guix store paths)
-  PI_SMOL_MODEL              - Override smol/fast model (see --smol)
-  PI_SLOW_MODEL              - Override slow/reasoning model (see --slow)
-  PI_PLAN_MODEL              - Override planning model (see --plan)
-  PI_NO_PTY                  - Disable PTY-based interactive bash execution
-  For complete environment variable reference, see:
-  ${chalk.dim("docs/environment-variables.md")}
-${chalk.bold("Available Tools (default-enabled unless noted):")}
-  read          - Read file contents
-  bash          - Execute bash commands
-  edit          - Edit files with find/replace
-  write         - Write files (creates/overwrites)
-  grep          - Search file contents
-  glob          - Find files by glob pattern
-  lsp           - Language server protocol (code intelligence)
-  python        - Execute Python code (requires: ${APP_NAME} setup python)
-  notebook      - Edit Jupyter notebooks
-  inspect_image - Analyze images with a vision model
-  browser       - Browser automation (Puppeteer)
-  computer      - Native host desktop capture and input (disabled by default)
-  task          - Launch sub-agents for parallel tasks
-  todo          - Manage todo/task lists
-  web_search    - Search the web
-  ask           - Ask user questions (interactive mode only)
-
-${chalk.bold("Plugin Options:")}
-  --plugin-dir <path>        Load plugin from directory (repeatable)
-
-${chalk.bold("Useful Commands:")}
-  omp agents unpack           - Export bundled subagents to ~/.omp/agent/agents (default)
-  omp agents unpack --project - Export bundled subagents to ./.omp/agents`;
-}
-
 export function printHelp(): void {
 	process.stdout.write(
 		`${chalk.bold(APP_NAME)} - AI coding assistant\n\n` +

package/src/cli/browser-relay-cli.ts

@@ -0,0 +1,119 @@
+/**
+ * `omp browser-relay` implementation: serve the local CDP relay and install
+ * its Chrome extension. Standalone CLI command — console output here is
+ * intentional user-facing output.
+ */
+import * as path from "node:path";
+import { getBrowserRelayDir } from "@oh-my-pi/pi-utils";
+import { probeRelayServer } from "../tools/browser/relay/daemon";
+import backgroundJs from "../tools/browser/relay/extension-assets/background.js.txt" with { type: "text" };
+import manifestJson from "../tools/browser/relay/extension-assets/manifest.json.txt" with { type: "text" };
+import optionsHtml from "../tools/browser/relay/extension-assets/options.html.txt" with { type: "text" };
+import optionsJs from "../tools/browser/relay/extension-assets/options.js.txt" with { type: "text" };
+import { DEFAULT_RELAY_URL } from "../tools/browser/relay/kind";
+import { type RelayServer, startRelayServer } from "../tools/browser/relay/server";
+
+export const BROWSER_RELAY_ACTIONS = ["serve", "install"] as const;
+export type BrowserRelayAction = (typeof BROWSER_RELAY_ACTIONS)[number];
+
+export interface BrowserRelayCommandArgs {
+	action: BrowserRelayAction;
+	port: number;
+	token?: string;
+	/** Install target directory; defaults to ~/.omp/browser-relay/extension. */
+	dir?: string;
+	/** Gather tabs the agent actively drives into an 'omp' Chrome tab group (default true). */
+	group?: boolean;
+	verbose?: boolean;
+}
+
+const EXTENSION_FILES: Record<string, string> = {
+	"background.js": backgroundJs,
+	"manifest.json": manifestJson,
+	"options.html": optionsHtml,
+	"options.js": optionsJs,
+};
+
+/** Default port of the relay endpoint (kept in sync with DEFAULT_RELAY_URL). */
+export const DEFAULT_RELAY_PORT = Number(new URL(DEFAULT_RELAY_URL).port);
+
+export async function runBrowserRelayCommand(args: BrowserRelayCommandArgs): Promise<void> {
+	if (args.action === "install") {
+		await runInstall(args.dir);
+		return;
+	}
+	await runServe(args);
+}
+
+async function runInstall(dirOverride: string | undefined): Promise<void> {
+	const dir = dirOverride ? path.resolve(dirOverride) : path.join(getBrowserRelayDir(), "extension");
+	for (const name in EXTENSION_FILES) {
+		await Bun.write(path.join(dir, name), EXTENSION_FILES[name]!);
+	}
+	console.log(`Installed the OMP Browser Relay extension to ${dir}`);
+	console.log("");
+	console.log("Finish setup in Chrome:");
+	console.log("  1. Open chrome://extensions and enable Developer mode.");
+	console.log(`  2. Click "Load unpacked" and select: ${dir}`);
+	console.log("  3. Enable the mode:  omp config set browser.relay true");
+	console.log("");
+	console.log("omp starts the relay automatically when the browser tool needs it;");
+	console.log("run `omp browser-relay` yourself only for --token or --no-group.");
+	console.log("The extension badge shows 'on' once it reaches a relay.");
+}
+
+async function runServe(args: BrowserRelayCommandArgs): Promise<void> {
+	const log = args.verbose
+		? (message: string, data?: Record<string, unknown>) => {
+				console.error(`[relay] ${message}${data ? ` ${JSON.stringify(data)}` : ""}`);
+			}
+		: undefined;
+	let relay: RelayServer;
+	try {
+		relay = startRelayServer({ port: args.port, token: args.token, group: args.group !== false, log });
+	} catch (err) {
+		// The port is machine-global while relays can be started by any project's
+		// broker (or by hand): losing the bind to a live relay is success.
+		if (err instanceof Error && "code" in err && err.code === "EADDRINUSE") {
+			if (await probeRelayServer(`http://127.0.0.1:${args.port}`)) {
+				console.log(`omp browser relay already running on http://127.0.0.1:${args.port}; nothing to do.`);
+				return;
+			}
+			console.error(`Port ${args.port} is in use by something that is not an omp browser relay.`);
+			process.exit(1);
+		}
+		throw err;
+	}
+
+	console.log(`omp browser relay listening on http://127.0.0.1:${args.port}`);
+	console.log(`  extension endpoint  ws://127.0.0.1:${args.port}/ext${args.token ? "?token=***" : ""}`);
+	if (args.port === DEFAULT_RELAY_PORT) {
+		console.log("  enable with         omp config set browser.relay true");
+	} else {
+		console.log(
+			`  enable with         omp config set browser.relay true && omp config set browser.relayUrl http://127.0.0.1:${args.port}`,
+		);
+	}
+	console.log("Waiting for the OMP Browser Relay extension to connect (omp browser-relay install)...");
+
+	let announced = false;
+	const readiness = setInterval(() => {
+		if (relay.bridge.ready && !announced) {
+			announced = true;
+			console.log("Extension connected. The omp browser tool can now drive your tabs.");
+		} else if (!relay.bridge.ready && announced) {
+			announced = false;
+			console.log("Extension disconnected; waiting for it to reconnect...");
+		}
+	}, 500);
+
+	const shutdown = () => {
+		clearInterval(readiness);
+		relay.stop();
+		process.exit(0);
+	};
+	process.on("SIGINT", shutdown);
+	process.on("SIGTERM", shutdown);
+	// Serve runs until SIGINT/SIGTERM; keep the process alive.
+	await new Promise<never>(() => {});
+}

package/src/cli/command-help.ts

@@ -0,0 +1,103 @@
+import type { CommandMetadata } from "@oh-my-pi/pi-utils/cli";
+
+export const acpHelp = {
+	description: "Run Oh My Pi as an ACP (Agent Client Protocol) server over stdio",
+} satisfies CommandMetadata;
+
+export const agentsHelp = { description: "Manage bundled task agents" } satisfies CommandMetadata;
+
+export const authBrokerHelp = {
+	description: "Manage the omp auth-broker (credential vault)",
+} satisfies CommandMetadata;
+
+export const authGatewayHelp = {
+	description: "Run an auth-gateway forward proxy backed by the configured broker",
+} satisfies CommandMetadata;
+
+export const benchHelp = {
+	description: "Benchmark models with the same prompt: time-to-first-token and generation throughput (tokens/s)",
+} satisfies CommandMetadata;
+
+export const browserRelayHelp = {
+	description: "Run the local CDP relay that lets the browser tool drive your own Chrome tabs",
+} satisfies CommandMetadata;
+
+export const cleanseHelp = {
+	description: "Detect and fix project diagnostics with weighted parallel subagents",
+} satisfies CommandMetadata;
+
+export const commitHelp = { description: "Generate a commit message and update changelogs" } satisfies CommandMetadata;
+
+export const completionsHelp = {
+	description: "Print a shell completion script (bash, zsh, or fish)",
+} satisfies CommandMetadata;
+
+export const completeHelp = { hidden: true } satisfies CommandMetadata;
+
+export const configHelp = { description: "Manage configuration settings" } satisfies CommandMetadata;
+
+export const dryBalanceHelp = {
+	description: "Dry-run OAuth account balancing across random session ids",
+} satisfies CommandMetadata;
+
+export const galleryHelp = {
+	description: "Preview tool renderers across streaming, in-progress, success, and failure states",
+} satisfies CommandMetadata;
+
+export const gcHelp = { description: "Run storage garbage collection" } satisfies CommandMetadata;
+
+export const grepHelp = { description: "Test grep tool" } satisfies CommandMetadata;
+
+export const grievancesHelp = {
+	description: "View, clean, or push reported tool issues (auto-QA grievances)",
+} satisfies CommandMetadata;
+
+export const installHelp = {
+	description: "Install or link an extension package (alias of `plugin install`/`plugin link`)",
+} satisfies CommandMetadata;
+
+export const joinHelp = { description: "Join a shared collab session (same as /join)" } satisfies CommandMetadata;
+
+export const modelsHelp = { description: "List, search, and refresh available models" } satisfies CommandMetadata;
+
+export const pluginHelp = { description: "Manage plugins (install, uninstall, list, etc.)" } satisfies CommandMetadata;
+
+export const readHelp = {
+	description: "Show what the read tool will return for a path, URL, or internal URI",
+} satisfies CommandMetadata;
+
+export const sayHelp = {
+	description: "Synthesize text with the local TTS engine and play it through the speakers",
+} satisfies CommandMetadata;
+
+export const searchHelp = { description: "Test web search providers" } satisfies CommandMetadata;
+
+export const setupHelp = {
+	description: "Run onboarding setup or install dependencies for optional features",
+} satisfies CommandMetadata;
+
+export const shellHelp = { description: "Interactive shell console" } satisfies CommandMetadata;
+
+export const sshHelp = { description: "Manage SSH host configurations" } satisfies CommandMetadata;
+
+export const statsHelp = { description: "View usage statistics" } satisfies CommandMetadata;
+
+export const tinyModelsHelp = {
+	description: "Download tiny local models (session titles + memory)",
+} satisfies CommandMetadata;
+
+export const tokenHelp = { description: "Get the API key or OAuth token for a provider" } satisfies CommandMetadata;
+
+export const ttsrHelp = {
+	description: "Inspect and test Time-Traveling Stream Rules (TTSR)",
+} satisfies CommandMetadata;
+
+export const updateHelp = { description: "Check for and install updates" } satisfies CommandMetadata;
+
+export const usageHelp = {
+	description: "Show provider usage limits for every authenticated account",
+} satisfies CommandMetadata;
+
+export const worktreeHelp = {
+	description: "List or clear agent-managed git worktrees (~/.omp/wt)",
+} satisfies CommandMetadata;

package/src/cli/completion-gen.ts

@@ -14,7 +14,7 @@
  * — see `commands/complete.ts`. The flag→source mapping below is the only manual
  * knob and is keyed by flag name so it stays stable as flags are added.
  */
-import type { ArgDescriptor, CliConfig, CommandCtor, FlagDescriptor } from "@oh-my-pi/pi-utils/cli";
+import type { ArgDescriptor, CliConfig, CommandMetadata, FlagDescriptor } from "@oh-my-pi/pi-utils/cli";
 import { BUILTIN_TOOL_NAMES } from "../tools/builtin-names";
 
 export type Shell = "bash" | "zsh" | "fish";
@@ -88,9 +88,9 @@ function argValue(desc: ArgDescriptor): ValueSource {
 	return { kind: "file" };
 }
 
-function buildFlags(Cmd: CommandCtor): CompletionFlag[] {
+function buildFlags(command: CommandMetadata): CompletionFlag[] {
 	const out: CompletionFlag[] = [];
-	const flags = Cmd.flags ?? {};
+	const flags = command.flags ?? {};
 	for (const name in flags) {
 		const desc = flags[name];
 		out.push({
@@ -104,9 +104,9 @@ function buildFlags(Cmd: CommandCtor): CompletionFlag[] {
 	return out;
 }
 
-function buildArgs(Cmd: CommandCtor): CompletionArg[] {
+function buildArgs(command: CommandMetadata): CompletionArg[] {
 	const out: CompletionArg[] = [];
-	const args = Cmd.args ?? {};
+	const args = command.args ?? {};
 	for (const name in args) {
 		const desc = args[name];
 		out.push({ name, description: desc.description ?? "", value: argValue(desc) });

package/src/cli/flag-tables.ts

@@ -30,6 +30,7 @@
  * real implementations at the dispatch site.
  */
 
+import { isServiceTierOpenAISettingValue, SERVICE_TIER_OPENAI_VALUES } from "../config/service-tier";
 import type { ConfiguredThinkingLevel } from "../thinking";
 import type { Args } from "./args";
 import { CliUsageError } from "./usage-error";
@@ -152,6 +153,14 @@ export const STRING_SETTERS: Record<string, StringSetter> = {
 	"--max-time": (result, value) => {
 		result.maxTime = parseMaxTimeSeconds(value);
 	},
+	"--service-tier": (result, value) => {
+		if (!isServiceTierOpenAISettingValue(value)) {
+			throw new CliUsageError(
+				`Invalid --service-tier value: ${JSON.stringify(value)}. Expected one of: ${SERVICE_TIER_OPENAI_VALUES.join(", ")}.`,
+			);
+		}
+		result.serviceTier = value;
+	},
 	"--api-key": (result, value) => {
 		result.apiKey = value;
 	},

package/src/cli/help-extra.ts

@@ -0,0 +1,89 @@
+import "@oh-my-pi/pi-utils/env";
+import { APP_NAME, CONFIG_DIR_NAME } from "@oh-my-pi/pi-utils/dirs";
+import chalk from "chalk";
+
+export function getExtraHelpText(): string {
+	return `${chalk.bold("Environment Variables:")}
+  ${chalk.dim("# Core Providers")}
+  ANTHROPIC_API_KEY          - Anthropic Claude models
+  ANTHROPIC_OAUTH_TOKEN      - Anthropic OAuth (takes precedence over API key)
+  CLAUDE_CODE_USE_FOUNDRY    - Enable Anthropic Foundry mode (uses Foundry endpoint + mTLS)
+  FOUNDRY_BASE_URL           - Anthropic Foundry base URL (e.g., https://<foundry-host>)
+  ANTHROPIC_FOUNDRY_API_KEY  - Anthropic token used as Authorization: Bearer <token> in Foundry mode
+  ANTHROPIC_CUSTOM_HEADERS   - Extra headers for Foundry or any custom ANTHROPIC_BASE_URL gateway (e.g., "user-id: USERNAME")
+  CLAUDE_CODE_CLIENT_CERT    - Client certificate (PEM path or inline PEM) for mTLS
+  CLAUDE_CODE_CLIENT_KEY     - Client private key (PEM path or inline PEM) for mTLS
+  NODE_EXTRA_CA_CERTS        - CA bundle path (or inline PEM) for server certificate validation
+  OPENAI_API_KEY             - OpenAI GPT models
+  GEMINI_API_KEY             - Google Gemini models
+  COPILOT_GITHUB_TOKEN      - GitHub Copilot
+
+  ${chalk.dim("# Additional LLM Providers")}
+  AZURE_OPENAI_API_KEY       - Azure OpenAI models
+  GROQ_API_KEY               - Groq models
+  CEREBRAS_API_KEY           - Cerebras models
+  XAI_API_KEY                - xAI Grok models
+  OPENROUTER_API_KEY         - OpenRouter aggregated models
+  KILO_API_KEY               - Kilo Gateway models
+  MISTRAL_API_KEY            - Mistral models
+  ZAI_API_KEY                - z.ai models (ZhipuAI/GLM)
+  UMANS_AI_CODING_PLAN_API_KEY - Umans AI Coding Plan models
+  UMANS_WEBSEARCH_PROVIDER    - Umans gateway web search backend (native or exa)
+  MINIMAX_API_KEY            - MiniMax models
+  OPENCODE_API_KEY           - OpenCode Zen/OpenCode Go models
+  CURSOR_ACCESS_TOKEN        - Cursor AI models
+  AI_GATEWAY_API_KEY         - Vercel AI Gateway
+  WAFER_SERVERLESS_API_KEY   - Wafer Serverless (pay-as-you-go)
+
+  ${chalk.dim("# Cloud Providers")}
+  AWS_PROFILE                - AWS Bedrock (or AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY)
+  GOOGLE_CLOUD_PROJECT       - Google Vertex AI (requires GOOGLE_CLOUD_LOCATION)
+  GOOGLE_APPLICATION_CREDENTIALS - Service account for Vertex AI
+
+  ${chalk.dim("# Search & Tools")}
+  EXA_API_KEY                - Exa web search
+  BRAVE_API_KEY              - Brave web search
+  PERPLEXITY_API_KEY         - Perplexity web search API key (optional; anonymous fallback)
+  PERPLEXITY_COOKIES         - Perplexity web search (session cookie)
+  TAVILY_API_KEY             - Tavily web search
+  TINYFISH_API_KEY           - TinyFish web search
+  FIRECRAWL_API_KEY          - Firecrawl web search
+  ANTHROPIC_SEARCH_API_KEY   - Anthropic web search (override; isolates search from main ANTHROPIC_API_KEY)
+  ANTHROPIC_SEARCH_BASE_URL  - Anthropic web search base URL (override; pairs with ANTHROPIC_SEARCH_API_KEY)
+
+  ${chalk.dim("# Configuration")}
+  OMP_PROFILE                 - Named profile for isolated agent state (same as --profile)
+  Use \`omp --profile <name> --alias <command>\` to create a shell shortcut for a profile
+  PI_CODING_AGENT_DIR        - Session storage directory (default: ~/${CONFIG_DIR_NAME}/agent)
+  PI_PACKAGE_DIR             - Override package directory (for Nix/Guix store paths)
+  PI_SMOL_MODEL              - Override smol/fast model (see --smol)
+  PI_SLOW_MODEL              - Override slow/reasoning model (see --slow)
+  PI_PLAN_MODEL              - Override planning model (see --plan)
+  PI_NO_PTY                  - Disable PTY-based interactive bash execution
+  For complete environment variable reference, see:
+  ${chalk.dim("docs/environment-variables.md")}
+${chalk.bold("Available Tools (default-enabled unless noted):")}
+  read          - Read file contents
+  bash          - Execute bash commands
+  edit          - Edit files with find/replace
+  write         - Write files (creates/overwrites)
+  grep          - Search file contents
+  glob          - Find files by glob pattern
+  lsp           - Language server protocol (code intelligence)
+  python        - Execute Python code (requires: ${APP_NAME} setup python)
+  notebook      - Edit Jupyter notebooks
+  inspect_image - Analyze images with a vision model
+  browser       - Browser automation (Puppeteer)
+  computer      - Native host desktop capture and input (disabled by default)
+  task          - Launch sub-agents for parallel tasks
+  todo          - Manage todo/task lists
+  web_search    - Search the web
+  ask           - Ask user questions (interactive mode only)
+
+${chalk.bold("Plugin Options:")}
+  --plugin-dir <path>        Load plugin from directory (repeatable)
+
+${chalk.bold("Useful Commands:")}
+  omp agents unpack           - Export bundled subagents to ~/.omp/agent/agents (default)
+  omp agents unpack --project - Export bundled subagents to ./.omp/agents`;
+}