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

package/dist/types/web/search/providers/searxng.d.ts

@@ -44,6 +44,7 @@ export declare function searchSearXNG(params: {
     num_results?: number;
     recency?: "day" | "week" | "month" | "year";
     signal?: AbortSignal;
+    timeoutMs?: number;
     fetch?: FetchImpl;
 }): Promise<SearchResponse>;
 /** Search provider for SearXNG web search. */

package/dist/types/web/search/providers/tavily.d.ts

@@ -21,6 +21,7 @@ export interface TavilySearchParams {
     /** `before:` upper bound, ISO `YYYY-MM-DD`, mapped to `end_date`. */
     end_date?: string;
     signal?: AbortSignal;
+    timeoutMs?: number;
     fetch?: FetchImpl;
 }
 /** Find Tavily API key through AuthStorage's unified refresh pipeline. */

package/dist/types/web/search/providers/tinyfish.d.ts

@@ -14,6 +14,7 @@ export interface TinyFishSearchParams {
     recency?: SearchParams["recency"];
     page?: number;
     signal?: AbortSignal;
+    timeoutMs?: number;
     fetch?: FetchImpl;
 }
 /** Resolve TinyFish API key through the shared auth storage pipeline. */

package/dist/types/web/search/providers/utils.d.ts

@@ -15,16 +15,13 @@ import { SearchProviderError, type SearchProviderId, type SearchSource } from ".
  */
 export declare function findCredential(storage: AgentStorage | null | undefined, envKey: string | null | undefined, ...storageProviders: string[]): string | null;
 /**
- * Default hard ceiling for a single web-search round-trip. 60s tolerates
- * legitimate slow LLM-mediated responses (anthropic web_search_20250305,
- * perplexity, gemini, codex) while still guaranteeing the session unfreezes
- * within a minute if Bun's `AbortSignal` fails to propagate on Windows.
- *
- * Pure search APIs (brave, exa, jina, tavily, searxng, synthetic, zai)
- * settle far faster in practice; reusing the same ceiling keeps the wiring
- * uniform without compromising correctness.
+ * The 60-second default tolerates legitimate slow LLM-mediated responses
+ * (Anthropic web_search_20250305, Perplexity, Gemini, Codex) while bounding
+ * Windows stalls when Bun's `AbortSignal` fails to propagate. Callers may
+ * configure a longer provider deadline, capped at five minutes by the
+ * dispatcher; pure search APIs typically settle far faster.
  */
-export declare const SEARCH_HARD_TIMEOUT_MS = 60000;
+export declare const SEARCH_HARD_TIMEOUT_MS: number;
 /**
  * Compose a caller-supplied {@link AbortSignal} with a hard timeout so an
  * outbound `fetch()` is guaranteed to settle within `ms` even when the

package/dist/types/web/search/providers/zai.d.ts

@@ -12,6 +12,7 @@ export interface ZaiSearchParams {
     query: string;
     num_results?: number;
     signal?: AbortSignal;
+    timeoutMs?: number;
     fetch?: FetchImpl;
     authStorage: AuthStorage;
     sessionId?: string;

package/dist/types/web/search/types.d.ts

@@ -100,6 +100,10 @@ export declare const SEARCH_PROVIDER_OPTIONS: readonly [{
     readonly label: "Public Web";
     readonly description: "Queries every credential-free engine in parallel and consolidates deduplicated results";
 }];
+/** Default hard timeout for each web-search provider transport. */
+export declare const DEFAULT_WEB_SEARCH_TIMEOUT_SECONDS = 60;
+/** Maximum configurable hard timeout for each web-search provider transport. */
+export declare const MAX_WEB_SEARCH_TIMEOUT_SECONDS = 300;
 /** Supported web search providers (every option except `auto`). */
 export type SearchProviderId = Exclude<(typeof SEARCH_PROVIDER_OPTIONS)[number]["value"], "auto">;
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "17.2.4",
+	"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.4",
-		"@oh-my-pi/omp-stats": "17.2.4",
-		"@oh-my-pi/pi-agent-core": "17.2.4",
-		"@oh-my-pi/pi-ai": "17.2.4",
-		"@oh-my-pi/pi-catalog": "17.2.4",
-		"@oh-my-pi/pi-mnemopi": "17.2.4",
-		"@oh-my-pi/pi-natives": "17.2.4",
-		"@oh-my-pi/pi-tui": "17.2.4",
-		"@oh-my-pi/pi-utils": "17.2.4",
-		"@oh-my-pi/pi-wire": "17.2.4",
-		"@oh-my-pi/snapcompact": "17.2.4",
+		"@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/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`;
+}