pi-usereq 0.7.0 → 0.11.0

package/pi.dev-src/pi-mono/coding-agent/scripts/migrate-sessions.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+#
+# Migrate sessions from ~/.pi/agent/*.jsonl to proper session directories.
+# This fixes sessions created by the bug in v0.30.0 where sessions were
+# saved to ~/.pi/agent/ instead of ~/.pi/agent/sessions/<encoded-cwd>/.
+#
+# Usage: ./migrate-sessions.sh [--dry-run]
+#
+
+set -e
+
+AGENT_DIR="${PI_AGENT_DIR:-$HOME/.pi/agent}"
+DRY_RUN=false
+
+if [[ "$1" == "--dry-run" ]]; then
+    DRY_RUN=true
+    echo "Dry run mode - no files will be moved"
+    echo
+fi
+
+# Find all .jsonl files directly in agent dir (not in subdirectories)
+shopt -s nullglob
+files=("$AGENT_DIR"/*.jsonl)
+shopt -u nullglob
+
+if [[ ${#files[@]} -eq 0 ]]; then
+    echo "No session files found in $AGENT_DIR"
+    exit 0
+fi
+
+echo "Found ${#files[@]} session file(s) to migrate"
+echo
+
+migrated=0
+failed=0
+
+for file in "${files[@]}"; do
+    filename=$(basename "$file")
+    
+    # Read first line and extract cwd using jq
+    if ! first_line=$(head -1 "$file" 2>/dev/null); then
+        echo "SKIP: $filename - cannot read file"
+        ((failed++))
+        continue
+    fi
+    
+    # Parse JSON and extract cwd
+    if ! cwd=$(echo "$first_line" | jq -r '.cwd // empty' 2>/dev/null); then
+        echo "SKIP: $filename - invalid JSON"
+        ((failed++))
+        continue
+    fi
+    
+    if [[ -z "$cwd" ]]; then
+        echo "SKIP: $filename - no cwd in session header"
+        ((failed++))
+        continue
+    fi
+    
+    # Encode cwd: remove leading slash, replace slashes with dashes, wrap with --
+    encoded=$(echo "$cwd" | sed 's|^/||' | sed 's|[/:\\]|-|g')
+    encoded="--${encoded}--"
+    
+    target_dir="$AGENT_DIR/sessions/$encoded"
+    target_file="$target_dir/$filename"
+    
+    if [[ -e "$target_file" ]]; then
+        echo "SKIP: $filename - target already exists"
+        ((failed++))
+        continue
+    fi
+    
+    echo "MIGRATE: $filename"
+    echo "    cwd: $cwd"
+    echo "    to:  $target_dir/"
+    
+    if [[ "$DRY_RUN" == false ]]; then
+        mkdir -p "$target_dir"
+        mv "$file" "$target_file"
+    fi
+    
+    ((migrated++))
+    echo
+done
+
+echo "---"
+echo "Migrated: $migrated"
+echo "Skipped:  $failed"
+
+if [[ "$DRY_RUN" == true && $migrated -gt 0 ]]; then
+    echo
+    echo "Run without --dry-run to perform the migration"
+fi

package/pi.dev-src/pi-mono/coding-agent/src/bun/cli.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+process.title = "pi";
+process.emitWarning = (() => {}) as typeof process.emitWarning;
+
+await import("./register-bedrock.js");
+await import("../cli.js");

package/pi.dev-src/pi-mono/coding-agent/src/bun/register-bedrock.ts

@@ -0,0 +1,4 @@
+import { setBedrockProviderModule } from "@mariozechner/pi-ai";
+import { bedrockProviderModule } from "@mariozechner/pi-ai/bedrock-provider";
+
+setBedrockProviderModule(bedrockProviderModule);

package/pi.dev-src/pi-mono/coding-agent/src/cli/args.ts

@@ -0,0 +1,335 @@
+/**
+ * CLI argument parsing and help display
+ */
+
+import type { ThinkingLevel } from "@mariozechner/pi-agent-core";
+import chalk from "chalk";
+import { APP_NAME, CONFIG_DIR_NAME, ENV_AGENT_DIR } from "../config.js";
+import type { ExtensionFlag } from "../core/extensions/types.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;
+	fork?: string;
+	sessionDir?: string;
+	models?: string[];
+	tools?: string[];
+	noTools?: boolean;
+	extensions?: string[];
+	noExtensions?: boolean;
+	print?: boolean;
+	export?: string;
+	noSkills?: boolean;
+	skills?: string[];
+	promptTemplates?: string[];
+	noPromptTemplates?: boolean;
+	themes?: string[];
+	noThemes?: boolean;
+	noContextFiles?: 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>;
+	diagnostics: Array<{ type: "warning" | "error"; message: string }>;
+}
+
+const VALID_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
+
+export function isValidThinkingLevel(level: string): level is ThinkingLevel {
+	return VALID_THINKING_LEVELS.includes(level as ThinkingLevel);
+}
+
+export function parseArgs(args: string[]): Args {
+	const result: Args = {
+		messages: [],
+		fileArgs: [],
+		unknownFlags: new Map(),
+		diagnostics: [],
+	};
+
+	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 = result.appendSystemPrompt ?? [];
+			result.appendSystemPrompt.push(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 === "--fork" && i + 1 < args.length) {
+			result.fork = 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) {
+			result.tools = args[++i]
+				.split(",")
+				.map((s) => s.trim())
+				.filter((name) => name.length > 0);
+		} else if (arg === "--thinking" && i + 1 < args.length) {
+			const level = args[++i];
+			if (isValidThinkingLevel(level)) {
+				result.thinking = level;
+			} else {
+				result.diagnostics.push({
+					type: "warning",
+					message: `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 === "--no-context-files" || arg === "-nc") {
+			result.noContextFiles = 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("--")) {
+			const eqIndex = arg.indexOf("=");
+			if (eqIndex !== -1) {
+				result.unknownFlags.set(arg.slice(2, eqIndex), arg.slice(eqIndex + 1));
+			} else {
+				const flagName = arg.slice(2);
+				const next = args[i + 1];
+				if (next !== undefined && !next.startsWith("-") && !next.startsWith("@")) {
+					result.unknownFlags.set(flagName, next);
+					i++;
+				} else {
+					result.unknownFlags.set(flagName, true);
+				}
+			}
+		} else if (arg.startsWith("-") && !arg.startsWith("--")) {
+			result.diagnostics.push({ type: "error", message: `Unknown option: ${arg}` });
+		} else if (!arg.startsWith("-")) {
+			result.messages.push(arg);
+		}
+	}
+
+	return result;
+}
+
+export function printHelp(extensionFlags?: ExtensionFlag[]): void {
+	const extensionFlagsText =
+		extensionFlags && extensionFlags.length > 0
+			? `\n${chalk.bold("Extension CLI Flags:")}\n${extensionFlags
+					.map((flag) => {
+						const value = flag.type === "string" ? " <value>" : "";
+						const description = flag.description ?? `Registered by ${flag.extensionPath}`;
+						return `  --${flag.name}${value}`.padEnd(30) + description;
+					})
+					.join("\n")}\n`
+			: "";
+	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} uninstall <source> [-l]   Alias for remove
+  ${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/uninstall/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 (can be used multiple times)
+  --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|id>            Use specific session file or partial UUID
+  --fork <path|id>               Fork specific session file or partial UUID into a new session
+  --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 tools by default (built-in and extension)
+  --tools <tools>                Comma-separated allowlist of tool names to enable
+                                 Applies to built-in and extension tools
+  --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
+  --no-context-files, -nc        Disable AGENTS.md and CLAUDE.md 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).${extensionFlagsText}
+
+${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
+  FIREWORKS_API_KEY                - Fireworks 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_TELEMETRY                     - Override install telemetry when set to 1/true/yes or 0/false/no
+  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("Built-in Tool Names:")}
+  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)
+`);
+}

package/pi.dev-src/pi-mono/coding-agent/src/cli/config-selector.ts

@@ -0,0 +1,52 @@
+/**
+ * TUI config selector for `pi config` command
+ */
+
+import { ProcessTerminal, TUI } from "@mariozechner/pi-tui";
+import type { ResolvedPaths } from "../core/package-manager.js";
+import type { SettingsManager } from "../core/settings-manager.js";
+import { ConfigSelectorComponent } from "../modes/interactive/components/config-selector.js";
+import { initTheme, stopThemeWatcher } from "../modes/interactive/theme/theme.js";
+
+export interface ConfigSelectorOptions {
+	resolvedPaths: ResolvedPaths;
+	settingsManager: SettingsManager;
+	cwd: string;
+	agentDir: string;
+}
+
+/** Show TUI config selector and return when closed */
+export async function selectConfig(options: ConfigSelectorOptions): Promise<void> {
+	// Initialize theme before showing TUI
+	initTheme(options.settingsManager.getTheme(), true);
+
+	return new Promise((resolve) => {
+		const ui = new TUI(new ProcessTerminal());
+		let resolved = false;
+
+		const selector = new ConfigSelectorComponent(
+			options.resolvedPaths,
+			options.settingsManager,
+			options.cwd,
+			options.agentDir,
+			() => {
+				if (!resolved) {
+					resolved = true;
+					ui.stop();
+					stopThemeWatcher();
+					resolve();
+				}
+			},
+			() => {
+				ui.stop();
+				stopThemeWatcher();
+				process.exit(0);
+			},
+			() => ui.requestRender(),
+		);
+
+		ui.addChild(selector);
+		ui.setFocus(selector.getResourceList());
+		ui.start();
+	});
+}

package/pi.dev-src/pi-mono/coding-agent/src/cli/file-processor.ts

@@ -0,0 +1,100 @@
+/**
+ * Process @file CLI arguments into text content and image attachments
+ */
+
+import { access, readFile, stat } from "node:fs/promises";
+import type { ImageContent } from "@mariozechner/pi-ai";
+import chalk from "chalk";
+import { resolve } from "path";
+import { resolveReadPath } from "../core/tools/path-utils.js";
+import { formatDimensionNote, resizeImage } from "../utils/image-resize.js";
+import { detectSupportedImageMimeTypeFromFile } from "../utils/mime.js";
+
+export interface ProcessedFiles {
+	text: string;
+	images: ImageContent[];
+}
+
+export interface ProcessFileOptions {
+	/** Whether to auto-resize images to 2000x2000 max. Default: true */
+	autoResizeImages?: boolean;
+}
+
+/** Process @file arguments into text content and image attachments */
+export async function processFileArguments(fileArgs: string[], options?: ProcessFileOptions): Promise<ProcessedFiles> {
+	const autoResizeImages = options?.autoResizeImages ?? true;
+	let text = "";
+	const images: ImageContent[] = [];
+
+	for (const fileArg of fileArgs) {
+		// Expand and resolve path (handles ~ expansion and macOS screenshot Unicode spaces)
+		const absolutePath = resolve(resolveReadPath(fileArg, process.cwd()));
+
+		// Check if file exists
+		try {
+			await access(absolutePath);
+		} catch {
+			console.error(chalk.red(`Error: File not found: ${absolutePath}`));
+			process.exit(1);
+		}
+
+		// Check if file is empty
+		const stats = await stat(absolutePath);
+		if (stats.size === 0) {
+			// Skip empty files
+			continue;
+		}
+
+		const mimeType = await detectSupportedImageMimeTypeFromFile(absolutePath);
+
+		if (mimeType) {
+			// Handle image file
+			const content = await readFile(absolutePath);
+			const base64Content = content.toString("base64");
+
+			let attachment: ImageContent;
+			let dimensionNote: string | undefined;
+
+			if (autoResizeImages) {
+				const resized = await resizeImage({ type: "image", data: base64Content, mimeType });
+				if (!resized) {
+					text += `<file name="${absolutePath}">[Image omitted: could not be resized below the inline image size limit.]</file>\n`;
+					continue;
+				}
+				dimensionNote = formatDimensionNote(resized);
+				attachment = {
+					type: "image",
+					mimeType: resized.mimeType,
+					data: resized.data,
+				};
+			} else {
+				attachment = {
+					type: "image",
+					mimeType,
+					data: base64Content,
+				};
+			}
+
+			images.push(attachment);
+
+			// Add text reference to image with optional dimension note
+			if (dimensionNote) {
+				text += `<file name="${absolutePath}">${dimensionNote}</file>\n`;
+			} else {
+				text += `<file name="${absolutePath}"></file>\n`;
+			}
+		} else {
+			// Handle text file
+			try {
+				const content = await readFile(absolutePath, "utf-8");
+				text += `<file name="${absolutePath}">\n${content}\n</file>\n`;
+			} catch (error: unknown) {
+				const message = error instanceof Error ? error.message : String(error);
+				console.error(chalk.red(`Error: Could not read file ${absolutePath}: ${message}`));
+				process.exit(1);
+			}
+		}
+	}
+
+	return { text, images };
+}

package/pi.dev-src/pi-mono/coding-agent/src/cli/initial-message.ts

@@ -0,0 +1,43 @@
+import type { ImageContent } from "@mariozechner/pi-ai";
+import type { Args } from "./args.js";
+
+export interface InitialMessageInput {
+	parsed: Args;
+	fileText?: string;
+	fileImages?: ImageContent[];
+	stdinContent?: string;
+}
+
+export interface InitialMessageResult {
+	initialMessage?: string;
+	initialImages?: ImageContent[];
+}
+
+/**
+ * Combine stdin content, @file text, and the first CLI message into a single
+ * initial prompt for non-interactive mode.
+ */
+export function buildInitialMessage({
+	parsed,
+	fileText,
+	fileImages,
+	stdinContent,
+}: InitialMessageInput): InitialMessageResult {
+	const parts: string[] = [];
+	if (stdinContent !== undefined) {
+		parts.push(stdinContent);
+	}
+	if (fileText) {
+		parts.push(fileText);
+	}
+
+	if (parsed.messages.length > 0) {
+		parts.push(parsed.messages[0]);
+		parsed.messages.shift();
+	}
+
+	return {
+		initialMessage: parts.length > 0 ? parts.join("") : undefined,
+		initialImages: fileImages && fileImages.length > 0 ? fileImages : undefined,
+	};
+}