@tuan_son.dinh/gsd 2.6.2 → 2.7.0

package/packages/pi-ai/src/utils/overflow.ts

@@ -0,0 +1,123 @@
+import type { AssistantMessage } from "../types.js";
+
+/**
+ * Regex patterns to detect context overflow errors from different providers.
+ *
+ * These patterns match error messages returned when the input exceeds
+ * the model's context window.
+ *
+ * Provider-specific patterns (with example error messages):
+ *
+ * - Anthropic: "prompt is too long: 213462 tokens > 200000 maximum"
+ * - OpenAI: "Your input exceeds the context window of this model"
+ * - Google: "The input token count (1196265) exceeds the maximum number of tokens allowed (1048575)"
+ * - xAI: "This model's maximum prompt length is 131072 but the request contains 537812 tokens"
+ * - Groq: "Please reduce the length of the messages or completion"
+ * - OpenRouter: "This endpoint's maximum context length is X tokens. However, you requested about Y tokens"
+ * - llama.cpp: "the request exceeds the available context size, try increasing it"
+ * - LM Studio: "tokens to keep from the initial prompt is greater than the context length"
+ * - GitHub Copilot: "prompt token count of X exceeds the limit of Y"
+ * - MiniMax: "invalid params, context window exceeds limit"
+ * - Kimi For Coding: "Your request exceeded model token limit: X (requested: Y)"
+ * - Cerebras: Returns "400/413 status code (no body)" - handled separately below
+ * - Mistral: "Prompt contains X tokens ... too large for model with Y maximum context length"
+ * - z.ai: Does NOT error, accepts overflow silently - handled via usage.input > contextWindow
+ * - Ollama: Silently truncates input - not detectable via error message
+ */
+const OVERFLOW_PATTERNS = [
+	/prompt is too long/i, // Anthropic
+	/input is too long for requested model/i, // Amazon Bedrock
+	/exceeds the context window/i, // OpenAI (Completions & Responses API)
+	/input token count.*exceeds the maximum/i, // Google (Gemini)
+	/maximum prompt length is \d+/i, // xAI (Grok)
+	/reduce the length of the messages/i, // Groq
+	/maximum context length is \d+ tokens/i, // OpenRouter (all backends)
+	/exceeds the limit of \d+/i, // GitHub Copilot
+	/exceeds the available context size/i, // llama.cpp server
+	/greater than the context length/i, // LM Studio
+	/context window exceeds limit/i, // MiniMax
+	/exceeded model token limit/i, // Kimi For Coding
+	/too large for model with \d+ maximum context length/i, // Mistral
+	/model_context_window_exceeded/i, // z.ai non-standard finish_reason surfaced as error text
+	/context[_ ]length[_ ]exceeded/i, // Generic fallback
+	/too many tokens/i, // Generic fallback
+	/token limit exceeded/i, // Generic fallback
+];
+
+/**
+ * Check if an assistant message represents a context overflow error.
+ *
+ * This handles two cases:
+ * 1. Error-based overflow: Most providers return stopReason "error" with a
+ *    specific error message pattern.
+ * 2. Silent overflow: Some providers accept overflow requests and return
+ *    successfully. For these, we check if usage.input exceeds the context window.
+ *
+ * ## Reliability by Provider
+ *
+ * **Reliable detection (returns error with detectable message):**
+ * - Anthropic: "prompt is too long: X tokens > Y maximum"
+ * - OpenAI (Completions & Responses): "exceeds the context window"
+ * - Google Gemini: "input token count exceeds the maximum"
+ * - xAI (Grok): "maximum prompt length is X but request contains Y"
+ * - Groq: "reduce the length of the messages"
+ * - Cerebras: 400/413 status code (no body)
+ * - Mistral: "Prompt contains X tokens ... too large for model with Y maximum context length"
+ * - OpenRouter (all backends): "maximum context length is X tokens"
+ * - llama.cpp: "exceeds the available context size"
+ * - LM Studio: "greater than the context length"
+ * - Kimi For Coding: "exceeded model token limit: X (requested: Y)"
+ *
+ * **Unreliable detection:**
+ * - z.ai: Sometimes accepts overflow silently (detectable via usage.input > contextWindow),
+ *   sometimes returns rate limit errors. Pass contextWindow param to detect silent overflow.
+ * - Ollama: Silently truncates input without error. Cannot be detected via this function.
+ *   The response will have usage.input < expected, but we don't know the expected value.
+ *
+ * ## Custom Providers
+ *
+ * If you've added custom models via settings.json, this function may not detect
+ * overflow errors from those providers. To add support:
+ *
+ * 1. Send a request that exceeds the model's context window
+ * 2. Check the errorMessage in the response
+ * 3. Create a regex pattern that matches the error
+ * 4. The pattern should be added to OVERFLOW_PATTERNS in this file, or
+ *    check the errorMessage yourself before calling this function
+ *
+ * @param message - The assistant message to check
+ * @param contextWindow - Optional context window size for detecting silent overflow (z.ai)
+ * @returns true if the message indicates a context overflow
+ */
+export function isContextOverflow(message: AssistantMessage, contextWindow?: number): boolean {
+	// Case 1: Check error message patterns
+	if (message.stopReason === "error" && message.errorMessage) {
+		// Check known patterns
+		if (OVERFLOW_PATTERNS.some((p) => p.test(message.errorMessage!))) {
+			return true;
+		}
+
+		// Cerebras returns 400/413 with no body for context overflow
+		// Note: 429 is rate limiting (requests/tokens per time), NOT context overflow
+		if (/^4(00|13)\s*(status code)?\s*\(no body\)/i.test(message.errorMessage)) {
+			return true;
+		}
+	}
+
+	// Case 2: Silent overflow (z.ai style) - successful but usage exceeds context
+	if (contextWindow && message.stopReason === "stop") {
+		const inputTokens = message.usage.input + message.usage.cacheRead;
+		if (inputTokens > contextWindow) {
+			return true;
+		}
+	}
+
+	return false;
+}
+
+/**
+ * Get the overflow patterns for testing purposes.
+ */
+export function getOverflowPatterns(): RegExp[] {
+	return [...OVERFLOW_PATTERNS];
+}

package/packages/pi-ai/src/utils/sanitize-unicode.ts

@@ -0,0 +1,25 @@
+/**
+ * Removes unpaired Unicode surrogate characters from a string.
+ *
+ * Unpaired surrogates (high surrogates 0xD800-0xDBFF without matching low surrogates 0xDC00-0xDFFF,
+ * or vice versa) cause JSON serialization errors in many API providers.
+ *
+ * Valid emoji and other characters outside the Basic Multilingual Plane use properly paired
+ * surrogates and will NOT be affected by this function.
+ *
+ * @param text - The text to sanitize
+ * @returns The sanitized text with unpaired surrogates removed
+ *
+ * @example
+ * // Valid emoji (properly paired surrogates) are preserved
+ * sanitizeSurrogates("Hello 🙈 World") // => "Hello 🙈 World"
+ *
+ * // Unpaired high surrogate is removed
+ * const unpaired = String.fromCharCode(0xD83D); // high surrogate without low
+ * sanitizeSurrogates(`Text ${unpaired} here`) // => "Text  here"
+ */
+export function sanitizeSurrogates(text: string): string {
+	// Replace unpaired high surrogates (0xD800-0xDBFF not followed by low surrogate)
+	// Replace unpaired low surrogates (0xDC00-0xDFFF not preceded by high surrogate)
+	return text.replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, "");
+}

package/packages/pi-ai/src/utils/typebox-helpers.ts

@@ -0,0 +1,24 @@
+import { type TUnsafe, Type } from "@sinclair/typebox";
+
+/**
+ * Creates a string enum schema compatible with Google's API and other providers
+ * that don't support anyOf/const patterns.
+ *
+ * @example
+ * const OperationSchema = StringEnum(["add", "subtract", "multiply", "divide"], {
+ *   description: "The operation to perform"
+ * });
+ *
+ * type Operation = Static<typeof OperationSchema>; // "add" | "subtract" | "multiply" | "divide"
+ */
+export function StringEnum<T extends readonly string[]>(
+	values: T,
+	options?: { description?: string; default?: T[number] },
+): TUnsafe<T[number]> {
+	return Type.Unsafe<T[number]>({
+		type: "string",
+		enum: values as any,
+		...(options?.description && { description: options.description }),
+		...(options?.default && { default: options.default }),
+	});
+}

package/packages/pi-ai/src/utils/validation.ts

@@ -0,0 +1,84 @@
+import AjvModule from "ajv";
+import addFormatsModule from "ajv-formats";
+
+// Handle both default and named exports
+const Ajv = (AjvModule as any).default || AjvModule;
+const addFormats = (addFormatsModule as any).default || addFormatsModule;
+
+import type { Tool, ToolCall } from "../types.js";
+
+// Detect if we're in a browser extension environment with strict CSP
+// Chrome extensions with Manifest V3 don't allow eval/Function constructor
+const isBrowserExtension = typeof globalThis !== "undefined" && (globalThis as any).chrome?.runtime?.id !== undefined;
+
+// Create a singleton AJV instance with formats (only if not in browser extension)
+// AJV requires 'unsafe-eval' CSP which is not allowed in Manifest V3
+let ajv: any = null;
+if (!isBrowserExtension) {
+	try {
+		ajv = new Ajv({
+			allErrors: true,
+			strict: false,
+			coerceTypes: true,
+		});
+		addFormats(ajv);
+	} catch (_e) {
+		// AJV initialization failed (likely CSP restriction)
+		console.warn("AJV validation disabled due to CSP restrictions");
+	}
+}
+
+/**
+ * Finds a tool by name and validates the tool call arguments against its TypeBox schema
+ * @param tools Array of tool definitions
+ * @param toolCall The tool call from the LLM
+ * @returns The validated arguments
+ * @throws Error if tool is not found or validation fails
+ */
+export function validateToolCall(tools: Tool[], toolCall: ToolCall): any {
+	const tool = tools.find((t) => t.name === toolCall.name);
+	if (!tool) {
+		throw new Error(`Tool "${toolCall.name}" not found`);
+	}
+	return validateToolArguments(tool, toolCall);
+}
+
+/**
+ * Validates tool call arguments against the tool's TypeBox schema
+ * @param tool The tool definition with TypeBox schema
+ * @param toolCall The tool call from the LLM
+ * @returns The validated (and potentially coerced) arguments
+ * @throws Error with formatted message if validation fails
+ */
+export function validateToolArguments(tool: Tool, toolCall: ToolCall): any {
+	// Skip validation in browser extension environment (CSP restrictions prevent AJV from working)
+	if (!ajv || isBrowserExtension) {
+		// Trust the LLM's output without validation
+		// Browser extensions can't use AJV due to Manifest V3 CSP restrictions
+		return toolCall.arguments;
+	}
+
+	// Compile the schema
+	const validate = ajv.compile(tool.parameters);
+
+	// Clone arguments so AJV can safely mutate for type coercion
+	const args = structuredClone(toolCall.arguments);
+
+	// Validate the arguments (AJV mutates args in-place for type coercion)
+	if (validate(args)) {
+		return args;
+	}
+
+	// Format validation errors nicely
+	const errors =
+		validate.errors
+			?.map((err: any) => {
+				const path = err.instancePath ? err.instancePath.substring(1) : err.params.missingProperty || "root";
+				return `  - ${path}: ${err.message}`;
+			})
+			.join("\n") || "Unknown validation error";
+
+	const errorMessage = `Validation failed for tool "${toolCall.name}":\n${errors}\n\nReceived arguments:\n${JSON.stringify(toolCall.arguments, null, 2)}`;
+
+	throw new Error(errorMessage);
+}

package/packages/pi-ai/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2024",
+    "module": "Node16",
+    "lib": ["ES2024"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "inlineSources": true,
+    "inlineSourceMap": false,
+    "moduleResolution": "Node16",
+    "resolveJsonModule": true,
+    "allowImportingTsExtensions": false,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "useDefineForClassFields": false,
+    "types": ["node"],
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist", "**/*.d.ts", "src/**/*.d.ts"]
+}

package/packages/pi-coding-agent/dist/cli/args.d.ts

@@ -0,0 +1,48 @@
+/**
+ * CLI argument parsing and help display
+ */
+import type { ThinkingLevel } from "@gsd/pi-agent-core";
+import { type ToolName } from "../core/tools/index.js";
+export type Mode = "text" | "json" | "rpc";
+export interface Args {
+    provider?: string;
+    model?: string;
+    apiKey?: string;
+    systemPrompt?: string;
+    appendSystemPrompt?: string;
+    thinking?: ThinkingLevel;
+    continue?: boolean;
+    resume?: boolean;
+    help?: boolean;
+    version?: boolean;
+    mode?: Mode;
+    noSession?: boolean;
+    session?: string;
+    sessionDir?: string;
+    models?: string[];
+    tools?: ToolName[];
+    noTools?: boolean;
+    extensions?: string[];
+    noExtensions?: boolean;
+    print?: boolean;
+    export?: string;
+    noSkills?: boolean;
+    skills?: string[];
+    promptTemplates?: string[];
+    noPromptTemplates?: boolean;
+    themes?: string[];
+    noThemes?: boolean;
+    listModels?: string | true;
+    offline?: boolean;
+    verbose?: boolean;
+    messages: string[];
+    fileArgs: string[];
+    /** Unknown flags (potentially extension flags) - map of flag name to value */
+    unknownFlags: Map<string, boolean | string>;
+}
+export declare function isValidThinkingLevel(level: string): level is ThinkingLevel;
+export declare function parseArgs(args: string[], extensionFlags?: Map<string, {
+    type: "boolean" | "string";
+}>): Args;
+export declare function printHelp(): void;
+//# sourceMappingURL=args.d.ts.map

package/packages/pi-coding-agent/dist/cli/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGxD,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAEjE,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;AAE3C,MAAM,WAAW,IAAI;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,8EAA8E;IAC9E,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC,CAAC;CAC5C;AAID,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,aAAa,CAE1E;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,SAAS,GAAG,QAAQ,CAAA;CAAE,CAAC,GAAG,IAAI,CA0H5G;AAED,wBAAgB,SAAS,IAAI,IAAI,CAyIhC"}

package/packages/pi-coding-agent/dist/cli/args.js

@@ -0,0 +1,299 @@
+/**
+ * CLI argument parsing and help display
+ */
+import chalk from "chalk";
+import { APP_NAME, CONFIG_DIR_NAME, ENV_AGENT_DIR } from "../config.js";
+import { allTools } from "../core/tools/index.js";
+const VALID_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"];
+export function isValidThinkingLevel(level) {
+    return VALID_THINKING_LEVELS.includes(level);
+}
+export function parseArgs(args, extensionFlags) {
+    const result = {
+        messages: [],
+        fileArgs: [],
+        unknownFlags: new Map(),
+    };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h") {
+            result.help = true;
+        }
+        else if (arg === "--version" || arg === "-v") {
+            result.version = true;
+        }
+        else if (arg === "--mode" && i + 1 < args.length) {
+            const mode = args[++i];
+            if (mode === "text" || mode === "json" || mode === "rpc") {
+                result.mode = mode;
+            }
+        }
+        else if (arg === "--continue" || arg === "-c") {
+            result.continue = true;
+        }
+        else if (arg === "--resume" || arg === "-r") {
+            result.resume = true;
+        }
+        else if (arg === "--provider" && i + 1 < args.length) {
+            result.provider = args[++i];
+        }
+        else if (arg === "--model" && i + 1 < args.length) {
+            result.model = args[++i];
+        }
+        else if (arg === "--api-key" && i + 1 < args.length) {
+            result.apiKey = args[++i];
+        }
+        else if (arg === "--system-prompt" && i + 1 < args.length) {
+            result.systemPrompt = args[++i];
+        }
+        else if (arg === "--append-system-prompt" && i + 1 < args.length) {
+            result.appendSystemPrompt = args[++i];
+        }
+        else if (arg === "--no-session") {
+            result.noSession = true;
+        }
+        else if (arg === "--session" && i + 1 < args.length) {
+            result.session = args[++i];
+        }
+        else if (arg === "--session-dir" && i + 1 < args.length) {
+            result.sessionDir = args[++i];
+        }
+        else if (arg === "--models" && i + 1 < args.length) {
+            result.models = args[++i].split(",").map((s) => s.trim());
+        }
+        else if (arg === "--no-tools") {
+            result.noTools = true;
+        }
+        else if (arg === "--tools" && i + 1 < args.length) {
+            const toolNames = args[++i].split(",").map((s) => s.trim());
+            const validTools = [];
+            for (const name of toolNames) {
+                if (name in allTools) {
+                    validTools.push(name);
+                }
+                else {
+                    console.error(chalk.yellow(`Warning: Unknown tool "${name}". Valid tools: ${Object.keys(allTools).join(", ")}`));
+                }
+            }
+            result.tools = validTools;
+        }
+        else if (arg === "--thinking" && i + 1 < args.length) {
+            const level = args[++i];
+            if (isValidThinkingLevel(level)) {
+                result.thinking = level;
+            }
+            else {
+                console.error(chalk.yellow(`Warning: Invalid thinking level "${level}". Valid values: ${VALID_THINKING_LEVELS.join(", ")}`));
+            }
+        }
+        else if (arg === "--print" || arg === "-p") {
+            result.print = true;
+        }
+        else if (arg === "--export" && i + 1 < args.length) {
+            result.export = args[++i];
+        }
+        else if ((arg === "--extension" || arg === "-e") && i + 1 < args.length) {
+            result.extensions = result.extensions ?? [];
+            result.extensions.push(args[++i]);
+        }
+        else if (arg === "--no-extensions" || arg === "-ne") {
+            result.noExtensions = true;
+        }
+        else if (arg === "--skill" && i + 1 < args.length) {
+            result.skills = result.skills ?? [];
+            result.skills.push(args[++i]);
+        }
+        else if (arg === "--prompt-template" && i + 1 < args.length) {
+            result.promptTemplates = result.promptTemplates ?? [];
+            result.promptTemplates.push(args[++i]);
+        }
+        else if (arg === "--theme" && i + 1 < args.length) {
+            result.themes = result.themes ?? [];
+            result.themes.push(args[++i]);
+        }
+        else if (arg === "--no-skills" || arg === "-ns") {
+            result.noSkills = true;
+        }
+        else if (arg === "--no-prompt-templates" || arg === "-np") {
+            result.noPromptTemplates = true;
+        }
+        else if (arg === "--no-themes") {
+            result.noThemes = true;
+        }
+        else if (arg === "--list-models") {
+            // Check if next arg is a search pattern (not a flag or file arg)
+            if (i + 1 < args.length && !args[i + 1].startsWith("-") && !args[i + 1].startsWith("@")) {
+                result.listModels = args[++i];
+            }
+            else {
+                result.listModels = true;
+            }
+        }
+        else if (arg === "--verbose") {
+            result.verbose = true;
+        }
+        else if (arg === "--offline") {
+            result.offline = true;
+        }
+        else if (arg.startsWith("@")) {
+            result.fileArgs.push(arg.slice(1)); // Remove @ prefix
+        }
+        else if (arg.startsWith("--") && extensionFlags) {
+            // Check if it's an extension-registered flag
+            const flagName = arg.slice(2);
+            const extFlag = extensionFlags.get(flagName);
+            if (extFlag) {
+                if (extFlag.type === "boolean") {
+                    result.unknownFlags.set(flagName, true);
+                }
+                else if (extFlag.type === "string" && i + 1 < args.length) {
+                    result.unknownFlags.set(flagName, args[++i]);
+                }
+            }
+            // Unknown flags without extensionFlags are silently ignored (first pass)
+        }
+        else if (!arg.startsWith("-")) {
+            result.messages.push(arg);
+        }
+    }
+    return result;
+}
+export function printHelp() {
+    console.log(`${chalk.bold(APP_NAME)} - AI coding assistant with read, bash, edit, write tools
+
+${chalk.bold("Usage:")}
+  ${APP_NAME} [options] [@files...] [messages...]
+
+${chalk.bold("Commands:")}
+  ${APP_NAME} install <source> [-l]    Install extension source and add to settings
+  ${APP_NAME} remove <source> [-l]     Remove extension source from settings
+  ${APP_NAME} update [source]          Update installed extensions (skips pinned sources)
+  ${APP_NAME} list                     List installed extensions from settings
+  ${APP_NAME} config                   Open TUI to enable/disable package resources
+  ${APP_NAME} <command> --help         Show help for install/remove/update/list
+
+${chalk.bold("Options:")}
+  --provider <name>              Provider name (default: google)
+  --model <pattern>              Model pattern or ID (supports "provider/id" and optional ":<thinking>")
+  --api-key <key>                API key (defaults to env vars)
+  --system-prompt <text>         System prompt (default: coding assistant prompt)
+  --append-system-prompt <text>  Append text or file contents to the system prompt
+  --mode <mode>                  Output mode: text (default), json, or rpc
+  --print, -p                    Non-interactive mode: process prompt and exit
+  --continue, -c                 Continue previous session
+  --resume, -r                   Select a session to resume
+  --session <path>               Use specific session file
+  --session-dir <dir>            Directory for session storage and lookup
+  --no-session                   Don't save session (ephemeral)
+  --models <patterns>            Comma-separated model patterns for Ctrl+P cycling
+                                 Supports globs (anthropic/*, *sonnet*) and fuzzy matching
+  --no-tools                     Disable all built-in tools
+  --tools <tools>                Comma-separated list of tools to enable (default: read,bash,edit,write)
+                                 Available: read, bash, edit, write, grep, find, ls
+  --thinking <level>             Set thinking level: off, minimal, low, medium, high, xhigh
+  --extension, -e <path>         Load an extension file (can be used multiple times)
+  --no-extensions, -ne           Disable extension discovery (explicit -e paths still work)
+  --skill <path>                 Load a skill file or directory (can be used multiple times)
+  --no-skills, -ns               Disable skills discovery and loading
+  --prompt-template <path>       Load a prompt template file or directory (can be used multiple times)
+  --no-prompt-templates, -np     Disable prompt template discovery and loading
+  --theme <path>                 Load a theme file or directory (can be used multiple times)
+  --no-themes                    Disable theme discovery and loading
+  --export <file>                Export session file to HTML and exit
+  --list-models [search]         List available models (with optional fuzzy search)
+  --verbose                      Force verbose startup (overrides quietStartup setting)
+  --offline                      Disable startup network operations (same as PI_OFFLINE=1)
+  --help, -h                     Show this help
+  --version, -v                  Show version number
+
+Extensions can register additional flags (e.g., --plan from plan-mode extension).
+
+${chalk.bold("Examples:")}
+  # Interactive mode
+  ${APP_NAME}
+
+  # Interactive mode with initial prompt
+  ${APP_NAME} "List all .ts files in src/"
+
+  # Include files in initial message
+  ${APP_NAME} @prompt.md @image.png "What color is the sky?"
+
+  # Non-interactive mode (process and exit)
+  ${APP_NAME} -p "List all .ts files in src/"
+
+  # Multiple messages (interactive)
+  ${APP_NAME} "Read package.json" "What dependencies do we have?"
+
+  # Continue previous session
+  ${APP_NAME} --continue "What did we discuss?"
+
+  # Use different model
+  ${APP_NAME} --provider openai --model gpt-4o-mini "Help me refactor this code"
+
+  # Use model with provider prefix (no --provider needed)
+  ${APP_NAME} --model openai/gpt-4o "Help me refactor this code"
+
+  # Use model with thinking level shorthand
+  ${APP_NAME} --model sonnet:high "Solve this complex problem"
+
+  # Limit model cycling to specific models
+  ${APP_NAME} --models claude-sonnet,claude-haiku,gpt-4o
+
+  # Limit to a specific provider with glob pattern
+  ${APP_NAME} --models "github-copilot/*"
+
+  # Cycle models with fixed thinking levels
+  ${APP_NAME} --models sonnet:high,haiku:low
+
+  # Start with a specific thinking level
+  ${APP_NAME} --thinking high "Solve this complex problem"
+
+  # Read-only mode (no file modifications possible)
+  ${APP_NAME} --tools read,grep,find,ls -p "Review the code in src/"
+
+  # Export a session file to HTML
+  ${APP_NAME} --export ~/${CONFIG_DIR_NAME}/agent/sessions/--path--/session.jsonl
+  ${APP_NAME} --export session.jsonl output.html
+
+${chalk.bold("Environment Variables:")}
+  ANTHROPIC_API_KEY                - Anthropic Claude API key
+  ANTHROPIC_OAUTH_TOKEN            - Anthropic OAuth token (alternative to API key)
+  OPENAI_API_KEY                   - OpenAI GPT API key
+  AZURE_OPENAI_API_KEY             - Azure OpenAI API key
+  AZURE_OPENAI_BASE_URL            - Azure OpenAI base URL (https://{resource}.openai.azure.com/openai/v1)
+  AZURE_OPENAI_RESOURCE_NAME       - Azure OpenAI resource name (alternative to base URL)
+  AZURE_OPENAI_API_VERSION         - Azure OpenAI API version (default: v1)
+  AZURE_OPENAI_DEPLOYMENT_NAME_MAP - Azure OpenAI model=deployment map (comma-separated)
+  GEMINI_API_KEY                   - Google Gemini API key
+  GROQ_API_KEY                     - Groq API key
+  CEREBRAS_API_KEY                 - Cerebras API key
+  XAI_API_KEY                      - xAI Grok API key
+  OPENROUTER_API_KEY               - OpenRouter API key
+  AI_GATEWAY_API_KEY               - Vercel AI Gateway API key
+  ZAI_API_KEY                      - ZAI API key
+  MISTRAL_API_KEY                  - Mistral API key
+  MINIMAX_API_KEY                  - MiniMax API key
+  OPENCODE_API_KEY                 - OpenCode Zen/OpenCode Go API key
+  KIMI_API_KEY                     - Kimi For Coding API key
+  AWS_PROFILE                      - AWS profile for Amazon Bedrock
+  AWS_ACCESS_KEY_ID                - AWS access key for Amazon Bedrock
+  AWS_SECRET_ACCESS_KEY            - AWS secret key for Amazon Bedrock
+  AWS_BEARER_TOKEN_BEDROCK         - Bedrock API key (bearer token)
+  AWS_REGION                       - AWS region for Amazon Bedrock (e.g., us-east-1)
+  ${ENV_AGENT_DIR.padEnd(32)} - Session storage directory (default: ~/${CONFIG_DIR_NAME}/agent)
+  PI_PACKAGE_DIR                   - Override package directory (for Nix/Guix store paths)
+  PI_OFFLINE                       - Disable startup network operations when set to 1/true/yes
+  PI_SHARE_VIEWER_URL              - Base URL for /share command (default: https://pi.dev/session/)
+  PI_AI_ANTIGRAVITY_VERSION        - Override Antigravity User-Agent version (e.g., 1.23.0)
+
+${chalk.bold("Available Tools (default: read, bash, edit, write):")}
+  read   - Read file contents
+  bash   - Execute bash commands
+  edit   - Edit files with find/replace
+  write  - Write files (creates/overwrites)
+  grep   - Search file contents (read-only, off by default)
+  find   - Find files by glob pattern (read-only, off by default)
+  ls     - List directory contents (read-only, off by default)
+`);
+}
+//# sourceMappingURL=args.js.map