@oai404iao/pi-codex-imagegen 0.1.0-alpha.1

package/src/tools/image-generation/display.ts

@@ -0,0 +1,73 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { makeCachedImagePreview, renderImageGenerationMessage } from "./preview.js";
+import { buildGeneratedImageDisplayText } from "./storage.js";
+import {
+	IMAGE_SAVE_DISPLAY_MESSAGE_TYPE,
+	type CachedImagePreview,
+	type ImageDisplayMessageDetails,
+	type PendingActivity,
+	type SavedGeneratedImage,
+} from "./types.js";
+
+export function createImageDisplay(pi: ExtensionAPI) {
+	const pendingActivities: PendingActivity[] = [];
+	const imagePreviewCache = new Map<string, CachedImagePreview>();
+	let pendingFlushTimer: ReturnType<typeof setTimeout> | undefined;
+	let generation = 0;
+
+	const cancelFlush = () => {
+		if (pendingFlushTimer !== undefined) clearTimeout(pendingFlushTimer);
+		pendingFlushTimer = undefined;
+	};
+
+	const flush = () => {
+		cancelFlush();
+		const activities = pendingActivities.splice(0, pendingActivities.length);
+		for (const activity of activities) {
+			imagePreviewCache.set(activity.savedImage.absolutePath, makeCachedImagePreview(activity.imageData.data, activity.imageData.mimeType));
+			pi.sendMessage(
+				{
+					customType: IMAGE_SAVE_DISPLAY_MESSAGE_TYPE,
+					content: [{ type: "text", text: buildGeneratedImageDisplayText(activity.savedImage, { expanded: false }) }],
+					display: true,
+					details: { savedImages: [activity.savedImage] } satisfies ImageDisplayMessageDetails,
+				},
+				{ triggerTurn: false },
+			);
+		}
+	};
+
+	return {
+		flush,
+		scheduleFlush() {
+			if (pendingFlushTimer !== undefined || pendingActivities.length === 0) return;
+			pendingFlushTimer = setTimeout(flush, 0);
+		},
+		clear() {
+			generation++;
+			cancelFlush();
+			pendingActivities.length = 0;
+			imagePreviewCache.clear();
+		},
+		/** Ignore completion callbacks belonging to a replaced/closed session. */
+		captureSink() {
+			const requestGeneration = generation;
+			return (savedImage: SavedGeneratedImage, imageData: { data: string; mimeType: string }) => {
+				if (requestGeneration !== generation) return;
+				pendingActivities.push({ kind: "image", savedImage, imageData });
+			};
+		},
+		registerRenderer() {
+			pi.registerMessageRenderer<ImageDisplayMessageDetails>(IMAGE_SAVE_DISPLAY_MESSAGE_TYPE, (message, options, theme) => {
+				const savedImage = message.details?.savedImages?.[0];
+				const textContent = typeof message.content === "string"
+					? message.content
+					: message.content
+							.filter((item) => item.type === "text")
+							.map((item) => item.text)
+							.join("\n");
+				return renderImageGenerationMessage(savedImage, textContent, options, theme, imagePreviewCache);
+			});
+		},
+	};
+}

package/src/tools/image-generation/preview.ts

@@ -0,0 +1,79 @@
+import { Container, Image, Spacer, Text, getCapabilities, getImageDimensions } from "@earendil-works/pi-tui";
+import { glyphs, treeGlyph } from "@oai404iao/pi-codex-runtime/internal/glyphs";
+import { themeBold, themeFg } from "@oai404iao/pi-codex-runtime/internal/utils/theme";
+import { type CachedImagePreview, type SavedGeneratedImage } from "./types.js";
+
+function getNodeFsSync(): { readFileSync(path: string): Buffer } | null {
+	if (typeof process === "undefined" || !(process.versions?.node || process.versions?.bun)) {
+		return null;
+	}
+	const builtinProcess = process as typeof process & { getBuiltinModule?: (specifier: string) => unknown };
+	if (typeof builtinProcess.getBuiltinModule !== "function") {
+		return null;
+	}
+	try {
+		const module = builtinProcess.getBuiltinModule("node:fs") as { readFileSync?: (path: string) => Buffer } | undefined;
+		return typeof module?.readFileSync === "function" ? { readFileSync: module.readFileSync } : null;
+	} catch {
+		return null;
+	}
+}
+
+export function makeCachedImagePreview(data: string, mimeType: string, bytes?: number): CachedImagePreview {
+	const dimensions = getImageDimensions(data, mimeType) ?? undefined;
+	return { data, mimeType, bytes: bytes ?? Buffer.from(data, "base64").byteLength, widthPx: dimensions?.widthPx, heightPx: dimensions?.heightPx };
+}
+
+function loadCachedImagePreview(savedImage: SavedGeneratedImage, imagePreviewCache: Map<string, CachedImagePreview>): CachedImagePreview | undefined {
+	const cached = imagePreviewCache.get(savedImage.absolutePath);
+	if (cached) return cached;
+	const fs = getNodeFsSync();
+	if (!fs) return undefined;
+	try {
+		const buffer = fs.readFileSync(savedImage.absolutePath);
+		const data = buffer.toString("base64");
+		const mimeType = `image/${savedImage.outputFormat}`;
+		const preview = makeCachedImagePreview(data, mimeType, buffer.byteLength);
+		imagePreviewCache.set(savedImage.absolutePath, preview);
+		return preview;
+	} catch {
+		return undefined;
+	}
+}
+
+function formatImageBytes(bytes: number | undefined): string | undefined {
+	if (!Number.isFinite(bytes) || !bytes) return undefined;
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1024 * 1024) return `${Math.round(bytes / 102.4) / 10}K`;
+	return `${Math.round(bytes / (1024 * 102.4)) / 10}M`;
+}
+
+function shouldRenderInlineImage(): { ok: boolean; reason?: string } {
+	if (process.env.TMUX) return { ok: false, reason: "inline preview disabled in tmux to avoid overlay/stale image artifacts" };
+	const protocol = getCapabilities().images;
+	if (!protocol) return { ok: false, reason: "terminal image protocol unavailable" };
+	return { ok: true };
+}
+
+export function renderImageGenerationMessage(savedImage: SavedGeneratedImage | undefined, messageContent: unknown, options: any, theme: any, imagePreviewCache: Map<string, CachedImagePreview>): Container {
+	const container = new Container();
+	const preview = savedImage ? loadCachedImagePreview(savedImage, imagePreviewCache) : undefined;
+	const type = savedImage?.outputFormat?.toUpperCase() ?? preview?.mimeType?.replace(/^image\//, "").toUpperCase() ?? "IMAGE";
+	const dimensions = preview?.widthPx && preview?.heightPx ? `${preview.widthPx}x${preview.heightPx}` : undefined;
+	const size = formatImageBytes(preview?.bytes);
+	const imageModel = savedImage?.imageModel ? `model ${savedImage.imageModel}` : undefined;
+	const meta = [imageModel, type, dimensions, size].filter(Boolean).join(glyphs().dot);
+	const label = `${themeFg(theme, "accent", glyphs().bullet)}${themeFg(theme, "text", themeBold(theme, "Image Generation "))}`;
+	const pathText = savedImage?.relativePath ?? (typeof messageContent === "string" ? messageContent : "generated image");
+	const lines = [`${label}${themeFg(theme, "accent", pathText)}${meta ? themeFg(theme, "dim", `${glyphs().dot}${meta}`) : ""}`];
+	if (savedImage?.latestRelativePath) lines.push(`${themeFg(theme, "muted", `  ${treeGlyph("├")}`)}${themeFg(theme, "text", "Latest ")}${themeFg(theme, "accent", savedImage.latestRelativePath)}`);
+	if (options?.expanded && savedImage?.revisedPrompt) lines.push(`${themeFg(theme, "muted", `  ${treeGlyph("├")}`)}${themeFg(theme, "text", "Prompt ")}${themeFg(theme, "dim", savedImage.revisedPrompt)}`);
+	const inline = shouldRenderInlineImage();
+	if (!inline.ok) lines.push(`${themeFg(theme, "muted", `  ${treeGlyph("└")}`)}${themeFg(theme, "warning", inline.reason ?? "inline preview unavailable")}`);
+	container.addChild(new Text(lines.join("\n"), 0, 0));
+	if (savedImage && preview && inline.ok) {
+		container.addChild(new Spacer(1));
+		container.addChild(new Image(preview.data, preview.mimeType, { fallbackColor: (text) => themeFg(theme, "dim", text) }, { maxWidthCells: 72, maxHeightCells: options?.expanded ? 24 : 14, filename: savedImage.relativePath }));
+	}
+	return container;
+}

package/src/tools/image-generation/storage.ts

@@ -0,0 +1,185 @@
+import { loadSettings } from "@oai404iao/pi-codex-runtime/internal/settings";
+import { saveBase64Image } from "../../utils/images.js";
+import { type SavedGeneratedImage } from "./types.js";
+
+const OPENAI_CODEX_IMAGE_DIR = ".pi/openai-codex-images";
+
+const OPENAI_CODEX_LATEST_IMAGE_NAME = "latest.png";
+
+let fsPromisesPromise: Promise<typeof import("node:fs/promises")> | undefined;
+
+const workspaceRootCache = new Map<string, Promise<string>>();
+
+const PATH_SEPARATOR = "/";
+
+function sanitizeFilePart(value: string | undefined, fallback: string): string {
+	const trimmed = (value ?? "").trim();
+	if (!trimmed) return fallback;
+	return trimmed.replace(/[^a-zA-Z0-9._-]+/g, "-");
+}
+
+function shortenFilePart(value: string | undefined, fallback: string): string {
+	const safe = sanitizeFilePart(value, fallback);
+	const match = /^([a-zA-Z]+_)(.+)$/.exec(safe);
+	const prefix = match?.[1] ?? "";
+	const body = match?.[2] ?? safe;
+	if (body.length <= 12) return `${prefix}${body}`;
+	return `${prefix}${body.slice(0, 8)}-${body.slice(-4)}`;
+}
+
+export function normalizeImageOutputFormat(value: string | undefined): string {
+	const format = (value ?? "png").toLowerCase();
+	return format === "png" || format === "jpg" || format === "jpeg" || format === "webp" ? format : "png";
+}
+
+function normalizePath(value: string): string {
+	if (!value) return ".";
+	const normalized = value.replace(/\/+/g, PATH_SEPARATOR);
+	if (normalized === PATH_SEPARATOR) return normalized;
+	return normalized.replace(/\/+$/g, "") || PATH_SEPARATOR;
+}
+
+function joinPaths(...parts: string[]): string {
+	if (parts.length === 0) return ".";
+	let result = parts[0] ?? "";
+	for (let i = 1; i < parts.length; i++) {
+		const part = parts[i];
+		if (!part) continue;
+		if (!result || result.endsWith(PATH_SEPARATOR)) {
+			result += part.replace(/^\/+/, "");
+		} else {
+			result += `${PATH_SEPARATOR}${part.replace(/^\/+/, "")}`;
+		}
+	}
+	return normalizePath(result);
+}
+
+function dirnamePath(value: string): string {
+	const normalized = normalizePath(value);
+	if (normalized === PATH_SEPARATOR) return PATH_SEPARATOR;
+	const index = normalized.lastIndexOf(PATH_SEPARATOR);
+	if (index < 0) return ".";
+	if (index === 0) return PATH_SEPARATOR;
+	return normalized.slice(0, index);
+}
+
+function splitPathSegments(value: string): string[] {
+	const normalized = normalizePath(value);
+	if (normalized === PATH_SEPARATOR) return [];
+	return normalized.replace(/^\/+/, "").split(PATH_SEPARATOR).filter(Boolean);
+}
+
+function relativePath(from: string, to: string): string {
+	const normalizedFrom = normalizePath(from);
+	const normalizedTo = normalizePath(to);
+	if (normalizedFrom === normalizedTo) return "";
+	const fromSegments = splitPathSegments(normalizedFrom);
+	const toSegments = splitPathSegments(normalizedTo);
+	let shared = 0;
+	while (shared < fromSegments.length && shared < toSegments.length && fromSegments[shared] === toSegments[shared]) {
+		shared++;
+	}
+	const upSegments = new Array(fromSegments.length - shared).fill("..");
+	const downSegments = toSegments.slice(shared);
+	return [...upSegments, ...downSegments].join(PATH_SEPARATOR);
+}
+
+async function getNodeFsPromises(): Promise<typeof import("node:fs/promises")> {
+	if (!fsPromisesPromise) {
+		fsPromisesPromise = import("node:fs/promises");
+	}
+	return fsPromisesPromise;
+}
+
+async function pathExists(value: string): Promise<boolean> {
+	try {
+		const fs = await getNodeFsPromises();
+		await fs.access(value);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function resolveWorkspaceRoot(cwd: string): Promise<string> {
+	const normalizedCwd = normalizePath(cwd);
+	const cached = workspaceRootCache.get(normalizedCwd);
+	if (cached) return cached;
+
+	const promise = (async () => {
+		let current = normalizedCwd;
+		while (true) {
+			if (await pathExists(joinPaths(current, ".git"))) {
+				return current;
+			}
+			const parent = dirnamePath(current);
+			if (parent === current || parent === ".") {
+				return normalizedCwd;
+			}
+			current = parent;
+		}
+	})();
+
+	workspaceRootCache.set(normalizedCwd, promise);
+	return promise;
+}
+
+export function getOpenAICodexImageDirectory(cwd: string): string {
+	return joinPaths(cwd, OPENAI_CODEX_IMAGE_DIR);
+}
+
+export function getOpenAICodexImagePath(cwd: string, responseId: string | undefined, callId: string, outputFormat?: string): string {
+	const ext = normalizeImageOutputFormat(outputFormat);
+	const safeCallId = shortenFilePart(callId, "image");
+	const safeResponseId = shortenFilePart(responseId, "response");
+	return joinPaths(getOpenAICodexImageDirectory(cwd), `${safeCallId}-${safeResponseId}.${ext}`);
+}
+
+export function getOpenAICodexLatestImagePath(cwd: string): string {
+	return joinPaths(getOpenAICodexImageDirectory(cwd), OPENAI_CODEX_LATEST_IMAGE_NAME);
+}
+
+export function buildGeneratedImageDisplayText(savedImage: SavedGeneratedImage, options?: { expanded?: boolean }): string {
+	const lines: string[] = [];
+	if (options?.expanded && savedImage.revisedPrompt) {
+		lines.push(`Prompt: ${savedImage.revisedPrompt}`);
+	}
+	lines.push(`File: ${savedImage.relativePath}`);
+	return lines.join("\n");
+}
+
+export async function saveOpenAICodexGeneratedImage(
+	cwd: string,
+	image: { responseId?: string; callId: string; result: string; outputFormat?: string; imageModel?: string; revisedPrompt?: string },
+): Promise<SavedGeneratedImage> {
+	const workspaceRoot = await resolveWorkspaceRoot(cwd);
+	const outputFormat = normalizeImageOutputFormat(image.outputFormat);
+	const saved = await saveBase64Image({
+		base64: image.result,
+		callId: image.callId,
+		cwd,
+		format: outputFormat,
+		responseId: image.responseId,
+		settings: loadSettings(cwd),
+	});
+	const absolutePath = saved.path;
+	const latestAbsolutePath = saved.latestPath ?? getOpenAICodexLatestImagePath(workspaceRoot);
+
+	const relativeFilePath = relativePath(workspaceRoot, absolutePath);
+	const latestRelativeFilePath = relativePath(workspaceRoot, latestAbsolutePath);
+	const relativePathValue = relativeFilePath && !relativeFilePath.startsWith("..") ? relativeFilePath : absolutePath;
+	const latestRelativePathValue =
+		latestRelativeFilePath && !latestRelativeFilePath.startsWith("..") ? latestRelativeFilePath : latestAbsolutePath;
+
+	return {
+		absolutePath,
+		relativePath: relativePathValue,
+		latestAbsolutePath,
+		latestRelativePath: latestRelativePathValue,
+		responseId: image.responseId,
+		callId: image.callId,
+		outputFormat,
+		imageModel: image.imageModel,
+		revisedPrompt: image.revisedPrompt,
+	};
+}

package/src/tools/image-generation/types.ts

@@ -0,0 +1,36 @@
+export const IMAGE_SAVE_DISPLAY_MESSAGE_TYPE = "codex-image-generation-display";
+
+export interface SavedGeneratedImage {
+	absolutePath: string;
+	relativePath: string;
+	latestAbsolutePath: string;
+	latestRelativePath: string;
+	responseId: string | undefined;
+	callId: string;
+	outputFormat: string;
+	imageModel?: string;
+	revisedPrompt?: string;
+}
+
+export interface ImageDisplayMessageDetails {
+	savedImages: SavedGeneratedImage[];
+}
+
+interface PendingImageDisplay {
+	savedImage: SavedGeneratedImage;
+	imageData: { data: string; mimeType: string };
+}
+
+interface QueuedImageActivity extends PendingImageDisplay {
+	kind: "image";
+}
+
+export type PendingActivity = QueuedImageActivity;
+
+export interface CachedImagePreview {
+	data: string;
+	mimeType: string;
+	bytes: number;
+	widthPx?: number;
+	heightPx?: number;
+}

package/src/tools/image-generation.ts

@@ -0,0 +1,284 @@
+import { randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { extname, isAbsolute, resolve } from "node:path";
+import { buildSessionContext, type SessionEntry } from "@earendil-works/pi-coding-agent";
+import { saveBase64Image } from "../utils/images.js";
+import type { CodexMinimalToolsSettings } from "@oai404iao/pi-codex-runtime/internal/settings";
+import type { Api, Model, ProviderHeaders } from "@earendil-works/pi-ai";
+import {
+	buildCodexJsonHeaders,
+	hasCodexRequestAuth,
+	resolveCodexApiEndpoint,
+} from "@oai404iao/pi-codex-runtime/internal/codex-http";
+import { loadModelSettings, type ResolvedCodexModelSettings } from "@oai404iao/pi-codex-runtime/internal/model-catalog/runtime";
+
+export interface ImageGenerationInput {
+	prompt?: string;
+	referenced_image_paths?: string[];
+	num_last_images_to_include?: number;
+	size?: "1024x1024" | "1024x1536" | "1536x1024" | "auto";
+	quality?: "low" | "medium" | "high" | "auto";
+	background?: "transparent" | "opaque" | "auto";
+	output_format?: "png" | "webp" | "jpeg";
+}
+
+export const imageGenerationToolSchema = {
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		prompt: { type: "string", description: "Image generation or editing prompt." },
+		referenced_image_paths: {
+			type: "array",
+			maxItems: 5,
+			items: { type: "string", minLength: 1 },
+			description: "Local PNG, JPEG, or WebP paths to edit.",
+		},
+		num_last_images_to_include: {
+			type: "integer",
+			minimum: 1,
+			maximum: 5,
+			description: "Use the newest conversation images when one or more targets have no local path.",
+		},
+	},
+	required: ["prompt"],
+};
+
+async function urlToBase64(url: string, signal?: AbortSignal): Promise<string> {
+	const response = await fetch(url, { signal });
+	if (!response.ok) throw new Error(`Failed to download generated image: ${response.status} ${await response.text()}`);
+	const buffer = Buffer.from(await response.arrayBuffer());
+	return buffer.toString("base64");
+}
+
+export async function directImageGeneration(input: ImageGenerationInput, cwd: string, settings: CodexMinimalToolsSettings, signal?: AbortSignal) {
+	if (!settings.directImageApiFallback) throw new Error("Direct Images API fallback is disabled. Use native openai or openai-codex handling, or enable directImageApiFallback.");
+	const apiKey = process.env.OPENAI_API_KEY;
+	if (!apiKey) throw new Error("OPENAI_API_KEY is required for direct image_generation fallback.");
+	if (!input.prompt?.trim()) throw new Error("A prompt is required for direct image_generation fallback.");
+	const body: Record<string, unknown> = {
+		model: settings.imageModel,
+		prompt: input.prompt,
+	};
+	if (input.size && input.size !== "auto") body.size = input.size;
+	if (input.quality && input.quality !== "auto") body.quality = input.quality;
+	if (input.background && input.background !== "auto") body.background = input.background;
+	if (input.output_format) body.output_format = input.output_format;
+	const response = await fetch("https://api.openai.com/v1/images/generations", {
+		method: "POST",
+		headers: { Authorization: `Bearer ${apiKey}`, "content-type": "application/json" },
+		body: JSON.stringify(body),
+		signal,
+	});
+	if (!response.ok) throw new Error(`OpenAI Images API failed: ${response.status} ${await response.text()}`);
+	const json = await response.json() as { data?: Array<{ b64_json?: string; url?: string; revised_prompt?: string }> };
+	const first = json.data?.[0];
+	const base64 = first?.b64_json ?? (first?.url ? await urlToBase64(first.url, signal) : undefined);
+	if (!base64) throw new Error("OpenAI Images API returned no image data.");
+	const saved = await saveBase64Image({ base64, callId: "direct", cwd, format: input.output_format, responseId: settings.imageModel, settings });
+	return {
+		content: [{ type: "text", text: `Generated image with ${settings.imageModel}; saved to ${saved.path}${saved.latestPath ? ` (latest: ${saved.latestPath})` : ""}.` }],
+		details: { saved, revisedPrompt: first?.revised_prompt, mode: "direct-images-api" },
+	};
+}
+
+interface ImageGenerationToolContext {
+	cwd: string;
+	model?: Model<Api>;
+	modelRegistry?: {
+		getApiKeyAndHeaders(model: Model<Api>): Promise<
+			| { ok: true; apiKey?: string; headers?: ProviderHeaders }
+			| { ok: false; error: string }
+		>;
+	};
+	sessionManager?: {
+		getSessionId?(): string;
+		getBranch(): SessionEntry[];
+	};
+}
+
+export interface StandaloneImageGenerationInvocation {
+	callId?: string;
+	turnId?: string;
+}
+
+async function referencedImageUrls(cwd: string, paths: readonly string[]): Promise<Array<{ image_url: string }>> {
+	if (paths.length > 5) throw new Error("referenced_image_paths must contain at most 5 paths.");
+	return Promise.all(paths.map(async (rawPath) => {
+		const normalized = rawPath.replace(/^@/, "");
+		const path = isAbsolute(normalized) ? normalized : resolve(cwd, normalized);
+		const extension = extname(path).toLowerCase();
+		const mimeType = extension === ".png"
+			? "image/png"
+			: extension === ".jpg" || extension === ".jpeg"
+				? "image/jpeg"
+				: extension === ".webp"
+					? "image/webp"
+					: undefined;
+		if (!mimeType) throw new Error(`Unsupported reference image type: ${rawPath}. Use PNG, JPEG, or WebP.`);
+		const data = await readFile(path);
+		return { image_url: `data:${mimeType};base64,${data.toString("base64")}` };
+	}));
+}
+
+function recentConversationImageUrls(
+	ctx: ImageGenerationToolContext,
+	count: number,
+): Array<{ image_url: string }> {
+	if (!ctx.sessionManager) {
+		throw new Error("Conversation images are unavailable in this tool context; use referenced_image_paths.");
+	}
+	const messages = buildSessionContext(ctx.sessionManager.getBranch()).messages;
+	const images: string[] = [];
+	for (const message of messages) {
+		if (message.role === "user" || message.role === "toolResult") {
+			if (!Array.isArray(message.content)) continue;
+			for (const item of message.content) {
+				if (item.type === "image") {
+					images.push(`data:${item.mimeType};base64,${item.data}`);
+				}
+			}
+			continue;
+		}
+		if (message.role !== "assistant") continue;
+		for (const block of message.content as unknown[]) {
+			if (!block || typeof block !== "object") continue;
+			const candidate = block as {
+				type?: unknown;
+				item?: { result?: unknown };
+			};
+			if (
+				candidate.type === "image_generation_call"
+				&& typeof candidate.item?.result === "string"
+				&& candidate.item.result
+			) {
+				images.push(`data:image/png;base64,${candidate.item.result}`);
+			}
+		}
+	}
+	if (images.length < count) {
+		throw new Error(`Requested the last ${count} conversation images, but only ${images.length} were available.`);
+	}
+	return images.slice(-count).map((image_url) => ({ image_url }));
+}
+
+export async function standaloneImageGeneration(
+	input: ImageGenerationInput,
+	ctx: ImageGenerationToolContext,
+	settings: ResolvedCodexModelSettings,
+	signal?: AbortSignal,
+	invocation: StandaloneImageGenerationInvocation = {},
+) {
+	signal?.throwIfAborted();
+	const callId = invocation.callId ?? "standalone";
+	const turnId = invocation.turnId ?? randomUUID();
+	const model = ctx.model;
+	if (!model || !ctx.modelRegistry) throw new Error("No active model is available for standalone image generation.");
+	if (!settings.enabled) throw new Error("pi-codex-minimal-tools is disabled.");
+	if (!input.prompt?.trim()) throw new Error("A prompt is required for standalone image generation.");
+	if (input.num_last_images_to_include !== undefined && input.referenced_image_paths?.length) {
+		throw new Error("Provide only one of referenced_image_paths or num_last_images_to_include.");
+	}
+	const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+	signal?.throwIfAborted();
+	if (!auth.ok) throw new Error(auth.error);
+	if (!hasCodexRequestAuth({
+		modelHeaders: model.headers,
+		auth: { apiKey: auth.apiKey, headers: auth.headers },
+	})) {
+		throw new Error(`No request authentication for provider: ${model.provider}`);
+	}
+	const images = input.num_last_images_to_include !== undefined
+		? recentConversationImageUrls(ctx, input.num_last_images_to_include)
+		: await referencedImageUrls(ctx.cwd, input.referenced_image_paths ?? []);
+	const edit = images.length > 0;
+	signal?.throwIfAborted();
+	const response = await fetch(
+		resolveCodexApiEndpoint(
+			model.baseUrl,
+			settings.apiKeyMode,
+			edit ? "images/edits" : "images/generations",
+		),
+		{
+			method: "POST",
+			headers: buildCodexJsonHeaders({
+				modelHeaders: model.headers,
+				auth: { apiKey: auth.apiKey, headers: auth.headers },
+				apiKeyMode: settings.apiKeyMode,
+				extraHeaders: {
+					"x-codex-image-turn-id": turnId,
+				},
+			}),
+			body: JSON.stringify({
+				model: settings.imageModel,
+				prompt: input.prompt.trim(),
+				...(edit ? { images } : {}),
+				background: "auto",
+				quality: "auto",
+				size: "auto",
+			}),
+			signal,
+		},
+	);
+	signal?.throwIfAborted();
+	if (!response.ok) {
+		throw new Error(`Standalone image generation failed: HTTP ${response.status}: ${await response.text()}`);
+	}
+	const result = await response.json() as {
+		data?: Array<{ b64_json?: string }>;
+	};
+	signal?.throwIfAborted();
+	const base64 = result.data?.[0]?.b64_json;
+	if (!base64) throw new Error("Standalone image generation returned no image data.");
+	const saved = await saveBase64Image({
+		base64,
+		callId,
+		cwd: ctx.cwd,
+		format: "png",
+		responseId: settings.imageModel,
+		settings,
+	});
+	signal?.throwIfAborted();
+	return {
+		content: [
+			{ type: "image", data: base64, mimeType: "image/png" },
+			{ type: "text", text: `Generated image with ${settings.imageModel}; saved to ${saved.path}${saved.latestPath ? ` (latest: ${saved.latestPath})` : ""}.` },
+		],
+		details: { saved, mode: "standalone-images-api" },
+	};
+}
+
+export function createImageGenerationToolDefinition(options: {
+	loadSettings?: (cwd: string, model?: Model<Api>) => CodexMinimalToolsSettings | ResolvedCodexModelSettings;
+	getCurrentTurnId?: (sessionId: string | undefined) => string | undefined;
+	hasProviderRuntime?: () => boolean;
+} = {}) {
+	return {
+		name: "image_generation",
+		label: "Image Generation",
+		description: "Generate or edit images using the hosted or standalone implementation selected by the current model profile. Results are saved under imageOutputDir and mirrored to latest.<ext>.",
+		promptSnippet: "Generate or edit images with the implementation selected by the current model profile.",
+		parameters: imageGenerationToolSchema,
+		async execute(toolCallId: string, params: ImageGenerationInput, signal: AbortSignal | undefined, _onUpdate: unknown, ctx: ImageGenerationToolContext) {
+			const cwd = ctx?.cwd ?? process.cwd();
+			const settings = options.loadSettings?.(cwd, ctx.model) ?? loadModelSettings(ctx.model, cwd);
+			const resolvedSettings = "modelProfile" in settings
+				? settings as ResolvedCodexModelSettings
+				: loadModelSettings(ctx.model, cwd, settings);
+			if (resolvedSettings.imageGenerationImplementation === "standalone") {
+				const sessionId = ctx.sessionManager?.getSessionId?.();
+				return standaloneImageGeneration(params, ctx, resolvedSettings, signal, {
+					callId: toolCallId,
+					turnId: options.getCurrentTurnId?.(sessionId),
+				});
+			}
+			if (settings?.directImageApiFallback) return directImageGeneration(params, cwd, settings, signal);
+			if (options.hasProviderRuntime?.() === false) {
+				throw new Error("Hosted image_generation requires pi-codex-core. Use a catalog-supported standalone profile or explicitly enable directImageApiFallback.");
+			}
+			return {
+				content: [{ type: "text", text: "image_generation should be handled by the current model profile. If no hosted or standalone implementation is configured, enable directImageApiFallback with OPENAI_API_KEY." }],
+				details: { phase: "native-provider", nativeTool: "image_generation" },
+			};
+		},
+	};
+}