@oh-my-pi/pi-coding-agent 16.0.4 → 16.0.5

package/src/session/session-loader.ts

@@ -4,7 +4,7 @@ import { BlobStore, isBlobRef, resolveImageData, resolveImageDataUrl } from "./b
 import { buildSessionContext } from "./session-context";
 import type { FileEntry, SessionEntry, SessionHeader } from "./session-entries";
 import { migrateToCurrentVersion } from "./session-migrations";
-import { isImageBlock } from "./session-persistence";
+import { isImageBlock, isImageDataPayload } from "./session-persistence";
 import { FileSessionStorage, type SessionStorage } from "./session-storage";
 
 /** Exported for compaction.test.ts */
@@ -44,9 +44,19 @@ function hasImageUrl(value: unknown): value is { image_url: string } {
 	return typeof value === "object" && value !== null && "image_url" in value && typeof value.image_url === "string";
 }
 
-async function resolvePersistedImageUrlRefs(value: unknown, blobStore: BlobStore): Promise<void> {
+function shouldResolveImagePayload(value: unknown, key: string | undefined): value is { data: string } {
+	if (!isImageDataPayload(value) || !isBlobRef(value.data)) return false;
+	return (key === "content" && isImageBlock(value)) || key === "images";
+}
+
+async function resolvePersistedBlobRefs(value: unknown, blobStore: BlobStore, key?: string): Promise<void> {
+	if (shouldResolveImagePayload(value, key)) {
+		value.data = await resolveImageData(blobStore, value.data);
+		return;
+	}
+
 	if (Array.isArray(value)) {
-		await Promise.all(value.map(item => resolvePersistedImageUrlRefs(item, blobStore)));
+		await Promise.all(value.map(item => resolvePersistedBlobRefs(item, blobStore, key)));
 		return;
 	}
 
@@ -56,38 +66,15 @@ async function resolvePersistedImageUrlRefs(value: unknown, blobStore: BlobStore
 		value.image_url = await resolveImageDataUrl(blobStore, value.image_url);
 	}
 
-	await Promise.all(Object.values(value).map(item => resolvePersistedImageUrlRefs(item, blobStore)));
+	await Promise.all(
+		Object.entries(value).map(([childKey, item]) => resolvePersistedBlobRefs(item, blobStore, childKey)),
+	);
 }
 
 export async function resolveBlobRefsInEntries(entries: FileEntry[], blobStore: BlobStore): Promise<void> {
-	const promises: Promise<void>[] = [];
-
-	for (const entry of entries) {
-		if (entry.type === "session") continue;
-
-		let contentArray: unknown[] | undefined;
-		if (entry.type === "message" && "content" in entry.message && Array.isArray(entry.message.content)) {
-			contentArray = entry.message.content;
-		} else if (entry.type === "custom_message" && Array.isArray(entry.content)) {
-			contentArray = entry.content;
-		}
-
-		if (contentArray) {
-			for (const block of contentArray) {
-				if (isImageBlock(block) && isBlobRef(block.data)) {
-					promises.push(
-						resolveImageData(blobStore, block.data).then(resolved => {
-							block.data = resolved;
-						}),
-					);
-				}
-			}
-		}
-
-		promises.push(resolvePersistedImageUrlRefs(entry, blobStore));
-	}
-
-	await Promise.all(promises);
+	await Promise.all(
+		entries.filter(entry => entry.type !== "session").map(entry => resolvePersistedBlobRefs(entry, blobStore)),
+	);
 }
 
 /**

package/src/session/session-persistence.ts

@@ -36,10 +36,33 @@ export function isImageBlock(value: unknown): value is { type: "image"; data: st
 	);
 }
 
+function isImageMimeType(value: unknown): value is string {
+	return typeof value === "string" && value.toLowerCase().startsWith("image/");
+}
+
+export function isImageDataPayload(value: unknown): value is { data: string; mimeType?: string } {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		"data" in value &&
+		typeof (value as { data?: string }).data === "string" &&
+		(isImageBlock(value) || ("mimeType" in value && isImageMimeType((value as { mimeType?: unknown }).mimeType)))
+	);
+}
+
+function shouldExternalizeImagePayload(
+	value: unknown,
+	key: string | undefined,
+): value is { data: string; mimeType?: string } {
+	if (!isImageDataPayload(value)) return false;
+	if (isBlobRef(value.data) || value.data.length < BLOB_EXTERNALIZE_THRESHOLD) return false;
+	return (key === TEXT_CONTENT_KEY && isImageBlock(value)) || key === "images";
+}
+
 /**
  * Recursively truncate large strings in an object for session persistence.
  * - Truncates any oversized string fields (key-agnostic)
- * - Replaces oversized image blocks with text notices
+ * - Externalizes oversized image payloads to blob refs
  * - Updates lineCount when content is truncated
  * - Returns original object if no changes needed (structural sharing)
  *
@@ -50,6 +73,9 @@ export function isImageBlock(value: unknown): value is { type: "image"; data: st
  */
 function truncateForPersistence(obj: unknown, blobStore: BlobStore, key?: string): unknown {
 	if (obj === null || obj === undefined) return obj;
+	if (shouldExternalizeImagePayload(obj, key)) {
+		return { ...obj, data: externalizeImageDataSync(blobStore, obj.data, obj.mimeType) };
+	}
 
 	if (typeof obj === "string") {
 		if (key === "image_url" && isImageDataUrl(obj)) {
@@ -72,16 +98,6 @@ function truncateForPersistence(obj: unknown, blobStore: BlobStore, key?: string
 		const result: unknown[] = new Array(obj.length);
 		for (let i = 0; i < obj.length; i++) {
 			const item = obj[i];
-			if (
-				key === TEXT_CONTENT_KEY &&
-				isImageBlock(item) &&
-				!isBlobRef(item.data) &&
-				item.data.length >= BLOB_EXTERNALIZE_THRESHOLD
-			) {
-				changed = true;
-				result[i] = { ...item, data: externalizeImageDataSync(blobStore, item.data, item.mimeType) };
-				continue;
-			}
 			const newItem = truncateForPersistence(item, blobStore, key);
 			if (newItem !== item) changed = true;
 			result[i] = newItem;

package/src/ssh/connection-manager.ts

@@ -65,7 +65,7 @@ async function deleteHostInfoFromDisk(hostName: string): Promise<void> {
 	}
 }
 
-async function validateKeyPermissions(keyPath?: string): Promise<void> {
+async function validateKeyPermissions(keyPath?: string, platform: SshPlatform = process.platform): Promise<void> {
 	if (!keyPath) return;
 	let stats: fs.Stats;
 	try {
@@ -79,6 +79,7 @@ async function validateKeyPermissions(keyPath?: string): Promise<void> {
 	if (!stats.isFile()) {
 		throw new Error(`SSH key is not a file: ${keyPath}`);
 	}
+	if (platform === "win32") return;
 	const mode = stats.mode & 0o777;
 	if ((mode & 0o077) !== 0) {
 		throw new Error(`SSH key permissions must be 600 or stricter: ${keyPath}`);
@@ -402,7 +403,7 @@ export async function buildRemoteCommand(
 	command: string,
 	options?: SSHArgsOptions,
 ): Promise<string[]> {
-	await validateKeyPermissions(host.keyPath);
+	await validateKeyPermissions(host.keyPath, options?.platform);
 	return [...buildCommonArgs(host, options), buildSshTarget(host.username, host.host), command];
 }
 

package/src/task/executor.ts

@@ -2117,8 +2117,8 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 				void session.abort();
 			}
 
+			const pendingExtensionMessages: Array<Promise<unknown>> = [];
 			const extensionRunner = session.extensionRunner;
-			const pendingExtensionMessages: Promise<unknown>[] = [];
 			if (extensionRunner) {
 				extensionRunner.initialize(
 					{

package/src/tools/image-gen.ts

@@ -21,8 +21,8 @@ import {
 } from "@oh-my-pi/pi-utils";
 import { z } from "zod/v4";
 import packageJson from "../../package.json" with { type: "json" };
-
 import { isAuthenticated, type ModelRegistry } from "../config/model-registry";
+import { settings } from "../config/settings";
 import type { CustomTool } from "../extensibility/custom-tools/types";
 import { ohMyPiXAIUserAgent, resolveXAIHttpCredentials } from "../lib/xai-http";
 import imageGenDescription from "../prompts/tools/image-gen.md" with { type: "text" };
@@ -38,7 +38,8 @@ const DEFAULT_OPENAI_BASE_URL = "https://api.openai.com/v1";
 const OPENAI_IMAGE_OUTPUT_FORMAT = "webp";
 const OPENAI_IMAGE_MIME_TYPE = "image/webp";
 
-const ANTIGRAVITY_ENDPOINT = "https://daily-cloudcode-pa.sandbox.googleapis.com";
+const DEFAULT_ANTIGRAVITY_ENDPOINT_PROD = "https://daily-cloudcode-pa.googleapis.com";
+const DEFAULT_ANTIGRAVITY_ENDPOINT_SANDBOX = "https://daily-cloudcode-pa.sandbox.googleapis.com";
 const IMAGE_SYSTEM_INSTRUCTION =
 	"You are an AI image generator. Generate images based on user descriptions. Focus on creating high-quality, visually appealing images that match the user's request.";
 
@@ -1164,33 +1165,74 @@ export const imageGenTool: CustomTool<typeof imageGenSchema, ImageGenToolDetails
 							resolvedImages,
 						);
 
-						const resp = await fetchImpl(`${ANTIGRAVITY_ENDPOINT}/v1internal:streamGenerateContent?alt=sse`, {
-							method: "POST",
-							headers: {
-								Authorization: `Bearer ${bearer}`,
-								"Content-Type": "application/json",
-								Accept: "text/event-stream",
-								"User-Agent": getAntigravityUserAgent(),
-							},
-							body: JSON.stringify(requestBody),
-							signal: requestSignal,
-						});
+						let endpoints = [DEFAULT_ANTIGRAVITY_ENDPOINT_PROD, DEFAULT_ANTIGRAVITY_ENDPOINT_SANDBOX];
+						try {
+							const mode = settings.get("providers.antigravityEndpoint");
+							if (mode === "production") {
+								endpoints = [DEFAULT_ANTIGRAVITY_ENDPOINT_PROD];
+							} else if (mode === "sandbox") {
+								endpoints = [DEFAULT_ANTIGRAVITY_ENDPOINT_SANDBOX];
+							}
+						} catch {
+							// Ignored
+						}
 
-						if (!resp.ok) {
-							const errorText = await resp.text();
-							let message = errorText;
+						let resp: Response | undefined;
+						let lastError: Error | undefined;
+
+						for (let i = 0; i < endpoints.length; i++) {
+							const endpoint = endpoints[i];
+							const isLastEndpoint = i === endpoints.length - 1;
 							try {
-								const parsedErr = JSON.parse(errorText) as { error?: { message?: string } };
-								message = parsedErr.error?.message ?? message;
-							} catch {
-								// Keep raw text.
+								resp = await fetchImpl(`${endpoint}/v1internal:streamGenerateContent?alt=sse`, {
+									method: "POST",
+									headers: {
+										Authorization: `Bearer ${bearer}`,
+										"Content-Type": "application/json",
+										Accept: "text/event-stream",
+										"User-Agent": getAntigravityUserAgent(),
+									},
+									body: JSON.stringify(requestBody),
+									signal: requestSignal,
+								});
+
+								if (resp.ok) {
+									break;
+								}
+
+								const errorText = await resp.text();
+								let message = errorText;
+								try {
+									const parsedErr = JSON.parse(errorText) as { error?: { message?: string } };
+									message = parsedErr.error?.message ?? message;
+								} catch {
+									// Keep raw text.
+								}
+
+								lastError = new ProviderHttpError(
+									`Antigravity image request failed (${resp.status}): ${message}`,
+									resp.status,
+									{ headers: resp.headers },
+								);
+
+								if (resp.status === 429 || (resp.status >= 500 && resp.status < 600)) {
+									if (!isLastEndpoint) {
+										continue;
+									}
+								}
+								break;
+							} catch (error) {
+								lastError = error as Error;
+								if (isLastEndpoint) {
+									break;
+								}
 							}
-							throw new ProviderHttpError(
-								`Antigravity image request failed (${resp.status}): ${message}`,
-								resp.status,
-								{ headers: resp.headers },
-							);
 						}
+
+						if (!resp?.ok) {
+							throw lastError ?? new Error("Antigravity image generation failed");
+						}
+
 						return resp;
 					},
 					{ signal: requestSignal },

package/src/tools/read.ts

@@ -689,7 +689,11 @@ export interface ReadToolDetails {
 	/** Raw text + start line for user-visible TUI rendering, set when content is text-like.
 	 * Mirrors the same lines the model receives but without hashline/line-number prefixes,
 	 * so the TUI can render the file content with its own gutter without re-parsing the formatted text. */
-	displayContent?: { text: string; startLine: number };
+	displayContent?: {
+		text: string;
+		startLine: number;
+		lineNumbers?: Array<number | null>;
+	};
 	summary?: { lines: number; elidedSpans: number; elidedLines: number };
 	/** Number of unresolved git conflicts surfaced by this read (TUI uses for inline `⚠ N` badge). */
 	conflictCount?: number;
@@ -1058,7 +1062,12 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		let emittedHashlineHeader = false;
 		let seenLines: number[] | undefined;
 		const formatText = (content: string, startNum: number): string => {
-			details.displayContent = { text: content, startLine: startNum };
+			const lineCount = countTextLines(content);
+			details.displayContent = {
+				text: content,
+				startLine: startNum,
+				lineNumbers: Array.from({ length: lineCount }, (_, i) => startNum + i),
+			};
 			if (shouldAddHashLines) seenLines = contiguousLineNumbers(startNum, countTextLines(content));
 			const formatted = formatTextWithMode(content, startNum, shouldAddHashLines, shouldAddLineNumbers);
 			if (!hashContext || emittedHashlineHeader) return formatted;
@@ -1070,6 +1079,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			details.displayContent = {
 				text: lineEntriesToPlainText(entries, BRACKET_CONTEXT_ELLIPSIS),
 				startLine: firstLine?.kind === "line" ? firstLine.lineNumber : startNum,
+				lineNumbers: entries.map(entry => (entry.kind === "line" ? entry.lineNumber : null)),
 			};
 			if (shouldAddHashLines) seenLines = lineNumbersFromEntries(entries);
 			const formatted = formatLineEntriesWithMode(entries, shouldAddHashLines, shouldAddLineNumbers);
@@ -1218,6 +1228,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 				details.displayContent = {
 					text: lineEntriesToPlainText(entries, BRACKET_CONTEXT_ELLIPSIS),
 					startLine: firstLine.lineNumber,
+					lineNumbers: entries.map(entry => (entry.kind === "line" ? entry.lineNumber : null)),
 				};
 			}
 			const formatted = formatLineEntriesWithMode(entries, shouldAddHashLines, shouldAddLineNumbers);
@@ -1255,7 +1266,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 	): Promise<{
 		outputText: string;
 		columnTruncated: number;
-		displayContent?: { text: string; startLine: number };
+		displayContent?: { text: string; startLine: number; lineNumbers?: Array<number | null> };
 		bridgeResult?: AgentToolResult<ReadToolDetails>;
 	}> {
 		const rawSelector = isRawSelector(parsed);
@@ -1292,7 +1303,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		const displayLineByNumber = new Map<number, string>();
 		const fullLines = rawSelector ? undefined : await readBracketContextFullLines(absolutePath, fileSize);
 		let columnTruncated = 0;
-		let displayContent: { text: string; startLine: number } | undefined;
+		let displayContent: { text: string; startLine: number; lineNumbers?: Array<number | null> } | undefined;
 
 		for (const range of ranges) {
 			const rangeStart = range.startLine - 1; // 0-indexed
@@ -1375,6 +1386,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			displayContent = {
 				text: lineEntriesToPlainText(entries, BRACKET_CONTEXT_ELLIPSIS),
 				startLine: firstLine?.kind === "line" ? firstLine.lineNumber : (visibleSpans[0]?.startLine ?? 1),
+				lineNumbers: entries.map(entry => (entry.kind === "line" ? entry.lineNumber : null)),
 			};
 			outputText = formatLineEntriesWithMode(entries, shouldAddHashLines, shouldAddLineNumbers);
 		} else {
@@ -2292,10 +2304,17 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 						}
 					}
 
-					let capturedDisplayContent: { text: string; startLine: number } | undefined;
+					let capturedDisplayContent:
+						| { text: string; startLine: number; lineNumbers?: Array<number | null> }
+						| undefined;
 					let emittedHashlineHeader = false;
 					const formatText = (text: string, startNum: number): string => {
-						capturedDisplayContent = { text, startLine: startNum };
+						const lineCount = countTextLines(text);
+						capturedDisplayContent = {
+							text,
+							startLine: startNum,
+							lineNumbers: Array.from({ length: lineCount }, (_, i) => startNum + i),
+						};
 						const formatted = formatTextWithMode(text, startNum, shouldAddHashLines, shouldAddLineNumbers);
 						if (!hashContext || emittedHashlineHeader) return formatted;
 						emittedHashlineHeader = true;
@@ -2322,6 +2341,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 						capturedDisplayContent = {
 							text: lineEntriesToPlainText(entries, BRACKET_CONTEXT_ELLIPSIS),
 							startLine: firstLine?.kind === "line" ? firstLine.lineNumber : startLineDisplay,
+							lineNumbers: entries.map(entry => (entry.kind === "line" ? entry.lineNumber : null)),
 						};
 						const formatted = formatLineEntriesWithMode(entries, shouldAddHashLines, shouldAddLineNumbers);
 						if (!hashContext || emittedHashlineHeader) return formatted;
@@ -2928,6 +2948,8 @@ export const readToolRenderer = {
 								status: "complete",
 								output: warningLines.length > 0 ? warningLines.join("\n") : undefined,
 								expanded,
+								codeStartLine: details?.displayContent?.startLine,
+								codeLineNumbers: details?.displayContent?.lineNumbers,
 								width,
 							},
 							uiTheme,

package/src/tui/code-cell.ts

@@ -33,6 +33,8 @@ export interface CodeCellOptions {
 	codeTail?: boolean;
 	expanded?: boolean;
 	width: number;
+	codeStartLine?: number;
+	codeLineNumbers?: Array<number | null>;
 }
 
 function getState(status?: CodeCellOptions["status"]): State | undefined {
@@ -99,7 +101,17 @@ function collapseCarriageReturns(line: string): string {
 	return idx < 0 ? line : line.slice(idx + 1);
 }
 export function renderCodeCell(options: CodeCellOptions, theme: Theme): string[] {
-	const { code, language, output, expanded = false, outputMaxLines = 6, codeMaxLines = 12, width } = options;
+	const {
+		code,
+		language,
+		output,
+		expanded = false,
+		outputMaxLines = 6,
+		codeMaxLines = 12,
+		width,
+		codeStartLine,
+		codeLineNumbers,
+	} = options;
 	const { title, meta } = formatHeader(options, theme);
 	const state = getState(options.status);
 
@@ -111,16 +123,45 @@ export function renderCodeCell(options: CodeCellOptions, theme: Theme): string[]
 	const startIndex = tail ? rawCodeLines.length - maxCodeLines : 0;
 	const visibleCode = rawCodeLines.slice(startIndex, startIndex + maxCodeLines).join("\n");
 	const codeLines = highlightCode(visibleCode, language);
+
+	let visibleLineNumbers: Array<number | null> | undefined;
+	let lineNumberWidth = 0;
+	if (codeLineNumbers) {
+		visibleLineNumbers = codeLineNumbers.slice(startIndex, startIndex + maxCodeLines);
+	} else if (codeStartLine !== undefined) {
+		visibleLineNumbers = Array.from({ length: maxCodeLines }, (_, i) => codeStartLine + startIndex + i);
+	}
+
+	if (visibleLineNumbers) {
+		const validLineNums = visibleLineNumbers.filter((n): n is number => n !== null && n !== undefined);
+		const maxVal = validLineNums.length > 0 ? Math.max(...validLineNums) : 0;
+		if (maxVal > 0) {
+			lineNumberWidth = Math.max(2, String(maxVal).length);
+		}
+	}
+
+	if (lineNumberWidth > 0 && visibleLineNumbers) {
+		for (let i = 0; i < codeLines.length; i++) {
+			const lineNum = visibleLineNumbers[i];
+			const gutter =
+				lineNum !== null && lineNum !== undefined
+					? String(lineNum).padStart(lineNumberWidth, " ")
+					: " ".repeat(lineNumberWidth);
+			codeLines[i] = theme.fg("dim", `${gutter} `) + codeLines[i];
+		}
+	}
+
 	if (hiddenCodeLines > 0) {
 		const hint = formatExpandHint(theme, expanded, hiddenCodeLines > 0);
+		const gutterPad = lineNumberWidth > 0 ? " ".repeat(lineNumberWidth + 1) : "";
 		if (tail) {
 			// Earlier rows scrolled above the live tail window — mark them on top so
 			// the newest streamed line stays pinned to the bottom of the box.
 			const earlier = `… ${hiddenCodeLines} earlier line${hiddenCodeLines === 1 ? "" : "s"}${hint ? ` ${hint}` : ""}`;
-			codeLines.unshift(theme.fg("dim", earlier));
+			codeLines.unshift(theme.fg("dim", gutterPad + earlier));
 		} else {
 			const moreLine = `${formatMoreItems(hiddenCodeLines, "line")}${hint ? ` ${hint}` : ""}`;
-			codeLines.push(theme.fg("dim", moreLine));
+			codeLines.push(theme.fg("dim", gutterPad + moreLine));
 		}
 	}
 

package/src/utils/image-vision-fallback.ts

@@ -0,0 +1,197 @@
+/**
+ * Vision fallback for text-only models. When a user attaches an image to a model
+ * that cannot accept image input, this:
+ *  1. saves each image under the session `local://` root (for later analysis), and
+ *  2. asks a vision-capable model to describe it and injects that description as
+ *     a text block in place of the image:
+ *
+ *     <image path="local://image-<hash>.png">
+ *     <description>
+ *     </image>
+ *
+ * Without this the provider layer drops the image entirely (NON_VISION_IMAGE_PLACEHOLDER).
+ */
+import * as path from "node:path";
+import {
+	type AgentTelemetry,
+	type AgentTelemetryConfig,
+	instrumentedCompleteSimple,
+	resolveTelemetry,
+} from "@oh-my-pi/pi-agent-core";
+import type { Api, completeSimple, ImageContent, Model, TextContent } from "@oh-my-pi/pi-ai";
+import { logger, prompt, toError } from "@oh-my-pi/pi-utils";
+import { extractTextContent } from "../commit/utils";
+import type { ModelRegistry } from "../config/model-registry";
+import { expandRoleAlias, getModelMatchPreferences, resolveModelFromString } from "../config/model-resolver";
+import type { Settings } from "../config/settings";
+import { type LocalProtocolOptions, resolveLocalRoot } from "../internal-urls";
+import describeUserPrompt from "../prompts/tools/image-attachment-describe.md" with { type: "text" };
+import describeSystemPrompt from "../prompts/tools/image-attachment-describe-system.md" with { type: "text" };
+
+/** Telemetry tag for the oneshot vision-description calls. */
+const ONESHOT_KIND = "image_attachment_describe";
+
+const NO_VISION_MODEL_NOTE =
+	"[No vision-capable model is configured, so this image could not be described automatically. " +
+	"The image was saved; configure a vision model role (modelRoles.vision) and use the inspect_image tool to analyze it.]";
+
+const DESCRIPTION_UNAVAILABLE_NOTE =
+	"[Image description unavailable: the vision model returned no usable text. The image was saved for further analysis.]";
+
+/** Registry surface needed to resolve a vision model and authorize requests. */
+export type VisionFallbackRegistry = Pick<ModelRegistry, "getAvailable" | "getApiKey" | "resolver"> &
+	Partial<Pick<ModelRegistry, "resolveCanonicalModel" | "getCanonicalVariants" | "getCanonicalId">>;
+
+export interface DescribeAttachedImagesDeps {
+	/** Active (text-only) model the prompt is destined for. */
+	activeModel: Model<Api>;
+	modelRegistry: VisionFallbackRegistry;
+	settings: Settings;
+	/** Inputs for resolving the session-scoped `local://` root. */
+	localProtocolOptions: LocalProtocolOptions;
+	/** `provider/id` of the active model; a last-resort vision-model candidate (filtered to image-capable). */
+	activeModelString?: string;
+	telemetryConfig?: AgentTelemetryConfig;
+	sessionId?: string;
+	/** Test seam: overrides the underlying completeSimple call. */
+	completeImpl?: typeof completeSimple;
+}
+
+/** Map an image MIME type to a file extension for the saved artifact. */
+function extensionForMime(mimeType: string): string {
+	const subtype = mimeType.split("/")[1]?.toLowerCase() ?? "";
+	switch (subtype) {
+		case "jpeg":
+		case "jpg":
+			return "jpg";
+		case "png":
+			return "png";
+		case "gif":
+			return "gif";
+		case "webp":
+			return "webp";
+		default: {
+			const sanitized = subtype.replace(/[^a-z0-9]/g, "");
+			return sanitized || "png";
+		}
+	}
+}
+
+/** Content-addressed file name so re-pasting the same image reuses one artifact. */
+function imageFileName(image: ImageContent): string {
+	const hash = Bun.hash(image.data).toString(16);
+	return `image-${hash}.${extensionForMime(image.mimeType)}`;
+}
+
+/** Persist an image under the local root; returns its `local://` URL. */
+async function saveImage(image: ImageContent, localRoot: string): Promise<string> {
+	const fileName = imageFileName(image);
+	const filePath = path.join(localRoot, fileName);
+	// Content-addressed: identical bytes overwrite themselves harmlessly. Bun.write creates parent dirs.
+	await Bun.write(filePath, Buffer.from(image.data, "base64"));
+	return `local://${fileName}`;
+}
+
+function formatImageBlock(localUrl: string, description: string): string {
+	return `<image path="${localUrl}">\n${description}\n</image>`;
+}
+
+/**
+ * Resolve a vision-capable model, mirroring the inspect_image priority
+ * (`pi/vision` → `pi/default` → active → first image-capable available), but
+ * never returning a text-only model.
+ */
+function resolveVisionModel(deps: DescribeAttachedImagesDeps): Model<Api> | undefined {
+	const available = deps.modelRegistry.getAvailable();
+	if (available.length === 0) return undefined;
+	const preferences = getModelMatchPreferences(deps.settings);
+	const resolvePattern = (pattern: string | undefined): Model<Api> | undefined => {
+		if (!pattern) return undefined;
+		const expanded = expandRoleAlias(pattern, deps.settings);
+		const model = resolveModelFromString(expanded, available, preferences, deps.modelRegistry);
+		return model?.input.includes("image") ? model : undefined;
+	};
+	return (
+		resolvePattern("pi/vision") ??
+		resolvePattern("pi/default") ??
+		resolvePattern(deps.activeModelString) ??
+		available.find(model => model.input.includes("image"))
+	);
+}
+
+/** Run one vision-description round-trip; returns trimmed text or `null` on any failure. */
+async function describeImage(
+	image: ImageContent,
+	visionModel: Model<Api>,
+	deps: DescribeAttachedImagesDeps,
+	telemetry: AgentTelemetry | undefined,
+	signal: AbortSignal | undefined,
+): Promise<string | null> {
+	try {
+		const response = await instrumentedCompleteSimple(
+			visionModel,
+			{
+				systemPrompt: [prompt.render(describeSystemPrompt)],
+				messages: [
+					{
+						role: "user",
+						content: [
+							{ type: "image", data: image.data, mimeType: image.mimeType },
+							{ type: "text", text: prompt.render(describeUserPrompt) },
+						],
+						timestamp: Date.now(),
+					},
+				],
+			},
+			{ apiKey: deps.modelRegistry.resolver(visionModel, deps.sessionId), signal },
+			{ telemetry, oneshotKind: ONESHOT_KIND, completeImpl: deps.completeImpl },
+		);
+		if (response.stopReason === "error" || response.stopReason === "aborted") {
+			logger.warn("image attachment description did not complete", {
+				stopReason: response.stopReason,
+				model: `${visionModel.provider}/${visionModel.id}`,
+			});
+			return null;
+		}
+		const text = extractTextContent(response).trim();
+		return text.length > 0 ? text : null;
+	} catch (err) {
+		logger.warn("image attachment description failed", {
+			error: toError(err).message,
+			model: `${visionModel.provider}/${visionModel.id}`,
+		});
+		return null;
+	}
+}
+
+/**
+ * Save each attached image under `local://` and replace it with a descriptive
+ * text block. Returns one {@link TextContent} per input image, in order. Never
+ * throws for an individual image: a failed description falls back to a note while
+ * the saved-path block is still emitted.
+ */
+export async function describeAttachedImagesForTextModel(
+	images: readonly ImageContent[],
+	deps: DescribeAttachedImagesDeps,
+	signal?: AbortSignal,
+): Promise<TextContent[]> {
+	const localRoot = resolveLocalRoot(deps.localProtocolOptions);
+	const visionModel = resolveVisionModel(deps);
+	const apiKey = visionModel ? await deps.modelRegistry.getApiKey(visionModel, deps.sessionId) : undefined;
+	const canDescribe = Boolean(visionModel && apiKey);
+	const telemetry = resolveTelemetry(deps.telemetryConfig, deps.sessionId);
+
+	return Promise.all(
+		images.map(async (image): Promise<TextContent> => {
+			const localUrl = await saveImage(image, localRoot);
+			let description: string;
+			if (canDescribe && visionModel) {
+				description =
+					(await describeImage(image, visionModel, deps, telemetry, signal)) ?? DESCRIPTION_UNAVAILABLE_NOTE;
+			} else {
+				description = NO_VISION_MODEL_NOTE;
+			}
+			return { type: "text", text: formatImageBlock(localUrl, description) };
+		}),
+	);
+}