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

package/src/background-image-generation.ts

@@ -0,0 +1,476 @@
+import type { Api, Model, ProviderHeaders } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionCommandContext, Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, type Component } from "@earendil-works/pi-tui";
+import { readFile } from "node:fs/promises";
+import { extname, isAbsolute, relative, resolve } from "node:path";
+import { supportsImageInput, type ModelLike } from "@oai404iao/pi-codex-runtime/internal/capabilities";
+import {
+	buildCodexJsonHeaders,
+	hasCodexRequestAuth,
+} from "@oai404iao/pi-codex-runtime/internal/codex-http";
+import { createBackgroundImageJobs, panelBranch } from "./background-image-jobs.js";
+import { listResolvedModelProfiles } from "@oai404iao/pi-codex-runtime/internal/model-catalog/catalog";
+import { loadModelSettings } from "@oai404iao/pi-codex-runtime/internal/model-catalog/runtime";
+import { setProviderGeneratedHeader } from "@oai404iao/pi-codex-runtime/internal/provider-headers";
+import { loadSettings } from "@oai404iao/pi-codex-runtime/internal/settings";
+import { standaloneImageGeneration } from "./tools/image-generation.js";
+import {
+	buildGeneratedImageDisplayText,
+	saveOpenAICodexGeneratedImage,
+} from "./tools/image-generation/storage.js";
+import { IMAGE_SAVE_DISPLAY_MESSAGE_TYPE, type SavedGeneratedImage } from "./tools/image-generation/types.js";
+import { projectRoot } from "./utils/images.js";
+
+const DEFAULT_CODEX_BASE_URL = "https://chatgpt.com/backend-api";
+const BACKGROUND_IMAGE_INSTRUCTIONS = "Generate or edit images with the hosted image_generation tool. Use the user's prompt and any provided reference images. Return the image_generation_call result.";
+const IMAGE_GEN_ERROR_MESSAGE_TYPE = "codex-image-generation-error";
+
+export interface ParsedImageGenCommand {
+	prompt: string;
+	imagePaths: string[];
+}
+
+interface ReferenceImage {
+	path: string;
+	mimeType: string;
+	base64: string;
+}
+
+interface CodexImageResult {
+	id: string;
+	result: string;
+	outputFormat?: string;
+	revisedPrompt?: string;
+	imageModel?: string;
+}
+
+interface ImageGenerationErrorDetails {
+	message: string;
+	prompt?: string;
+	imageModel?: string;
+	referenceCount?: number;
+}
+
+interface ModelRegistryLike {
+	getAll?: () => unknown;
+	getAvailable?: () => unknown;
+	find?: (provider: string, id: string) => unknown;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function isModelLike(value: unknown): value is ModelLike {
+	return isRecord(value) && typeof value.provider === "string" && (typeof value.id === "string" || typeof value.name === "string");
+}
+
+function registryModels(registry: ModelRegistryLike | undefined): ModelLike[] {
+	if (!registry) return [];
+	for (const method of [registry.getAll, registry.getAvailable]) {
+		if (typeof method !== "function") continue;
+		try {
+			const value = method.call(registry);
+			if (Array.isArray(value)) return value.filter(isModelLike);
+		} catch {
+			// Try the next registry shape.
+		}
+	}
+	return [];
+}
+
+function isConfiguredImageModel(model: ModelLike | undefined): boolean {
+	if (!model || !supportsImageInput(model)) return false;
+	const settings = loadModelSettings(model);
+	return Boolean(
+		settings.modelProfile?.effective.enabled
+		&& settings.imageGenerationImplementation,
+	);
+}
+
+export function selectCodexImageModel(currentModel: ModelLike | undefined, registry: ModelRegistryLike | undefined): ModelLike | undefined {
+	if (isConfiguredImageModel(currentModel)) return currentModel;
+	const discovered = registryModels(registry).find(isConfiguredImageModel);
+	if (discovered) return discovered;
+	for (const profile of listResolvedModelProfiles()) {
+		if (!profile.effective.enabled || !profile.effective.tools.imageGeneration) continue;
+		const slash = profile.id.indexOf("/");
+		const candidate = registry?.find?.(
+			profile.id.slice(0, slash),
+			profile.id.slice(slash + 1),
+		);
+		if (isModelLike(candidate) && isConfiguredImageModel(candidate)) return candidate;
+	}
+	return undefined;
+}
+
+function tokenizeArgs(input: string): string[] {
+	const tokens: string[] = [];
+	let current = "";
+	let quote: '"' | "'" | undefined;
+	let escaped = false;
+	for (const ch of input) {
+		if (escaped) {
+			current += ch;
+			escaped = false;
+			continue;
+		}
+		if (ch === "\\") {
+			escaped = true;
+			continue;
+		}
+		if (quote) {
+			if (ch === quote) quote = undefined;
+			else current += ch;
+			continue;
+		}
+		if (ch === '"' || ch === "'") {
+			quote = ch;
+			continue;
+		}
+		if (/\s/.test(ch)) {
+			if (current) tokens.push(current);
+			current = "";
+			continue;
+		}
+		current += ch;
+	}
+	if (current) tokens.push(current);
+	return tokens;
+}
+
+function isSupportedImagePathToken(token: string): boolean {
+	const normalized = token.replace(/^file:\/\//, "").replace(/[),.;:]+$/, "");
+	if (/^https?:\/\//i.test(normalized) || normalized.startsWith("data:")) return false;
+	return /\.(?:png|jpe?g|webp)$/i.test(normalized);
+}
+
+export function parseImageGenCommandArgs(input: string): ParsedImageGenCommand {
+	const imagePaths: string[] = [];
+	const promptParts: string[] = [];
+	for (const token of tokenizeArgs(input.trim())) {
+		if (token.startsWith("@") && token.length > 1) imagePaths.push(token.slice(1));
+		else if (isSupportedImagePathToken(token)) imagePaths.push(token.replace(/^file:\/\//, "").replace(/[),.;:]+$/, ""));
+		else promptParts.push(token);
+	}
+	return { prompt: promptParts.join(" ").trim(), imagePaths };
+}
+
+function mimeTypeForPath(path: string): string {
+	const ext = extname(path).toLowerCase();
+	if (ext === ".jpg" || ext === ".jpeg") return "image/jpeg";
+	if (ext === ".webp") return "image/webp";
+	if (ext === ".png") return "image/png";
+	throw new Error(`Unsupported reference image type: ${path}. Use PNG, JPEG, or WebP.`);
+}
+
+async function loadReferenceImage(cwd: string, rawPath: string): Promise<ReferenceImage> {
+	const path = isAbsolute(rawPath) ? rawPath : resolve(cwd, rawPath);
+	const buffer = await readFile(path);
+	return { path, mimeType: mimeTypeForPath(path), base64: buffer.toString("base64") };
+}
+
+function resolveCodexUrl(baseUrl: string | undefined, options?: { apiKeyMode?: boolean }): string {
+	const raw = baseUrl && baseUrl.trim().length > 0 ? baseUrl : DEFAULT_CODEX_BASE_URL;
+	const normalized = raw.replace(/\/+$/, "");
+	if (options?.apiKeyMode) {
+		if (normalized.endsWith("/responses")) return normalized;
+		return `${normalized}/responses`;
+	}
+	if (normalized.endsWith("/codex/responses")) return normalized;
+	if (normalized.endsWith("/codex")) return `${normalized}/responses`;
+	return `${normalized}/codex/responses`;
+}
+
+function buildHeaders(
+	model: Model<Api>,
+	auth: { apiKey?: string; headers?: ProviderHeaders },
+	options?: { apiKeyMode?: boolean },
+): Headers {
+	const headers = buildCodexJsonHeaders({
+		modelHeaders: model.headers,
+		auth,
+		apiKeyMode: options?.apiKeyMode ?? false,
+	});
+	setProviderGeneratedHeader(headers, "OpenAI-Beta", "responses=experimental");
+	setProviderGeneratedHeader(headers, "accept", "text/event-stream");
+	return headers;
+}
+
+export function buildBackgroundImageRequest(options: {
+	prompt: string;
+	referenceImages: ReferenceImage[];
+	responsesModel: string;
+	imageModel: string;
+}): Record<string, unknown> {
+	const content: Array<Record<string, unknown>> = [
+		{ type: "input_text", text: options.referenceImages.length > 0 ? `Edit the provided image(s): ${options.prompt}` : options.prompt },
+		...options.referenceImages.map((image) => ({
+			type: "input_image",
+			detail: "auto",
+			image_url: `data:${image.mimeType};base64,${image.base64}`,
+		})),
+	];
+	return {
+		model: options.responsesModel,
+		store: false,
+		stream: true,
+		instructions: BACKGROUND_IMAGE_INSTRUCTIONS,
+		input: [{ role: "user", content }],
+		tools: [{
+			type: "image_generation",
+			model: options.imageModel,
+			output_format: "png",
+			action: options.referenceImages.length > 0 ? "edit" : "generate",
+		}],
+		tool_choice: { type: "image_generation" },
+	};
+}
+
+async function* parseSseEvents(response: Response, signal: AbortSignal): AsyncIterable<Record<string, unknown>> {
+	if (!response.body) return;
+	const reader = response.body.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+	const cancel = () => { void reader.cancel(signal.reason).catch(() => {}); };
+	signal.addEventListener("abort", cancel, { once: true });
+	if (signal.aborted) cancel();
+	try {
+		while (true) {
+			signal.throwIfAborted();
+			const { done, value } = await reader.read();
+			signal.throwIfAborted();
+			if (done) break;
+			buffer += decoder.decode(value, { stream: true });
+			let boundary: number;
+			while ((boundary = buffer.indexOf("\n\n")) >= 0) {
+				const raw = buffer.slice(0, boundary);
+				buffer = buffer.slice(boundary + 2);
+				for (const line of raw.split(/\r?\n/)) {
+					if (!line.startsWith("data:")) continue;
+					const data = line.slice(5).trim();
+					if (!data || data === "[DONE]") continue;
+					yield JSON.parse(data) as Record<string, unknown>;
+				}
+			}
+		}
+	} finally {
+		signal.removeEventListener("abort", cancel);
+		reader.releaseLock();
+	}
+}
+
+function collectImageResult(results: CodexImageResult[], item: unknown, fallbackImageModel: string): void {
+	if (!item || typeof item !== "object") return;
+	const candidate = item as Record<string, unknown>;
+	if (candidate.type !== "image_generation_call" || typeof candidate.result !== "string") return;
+	const id = typeof candidate.id === "string" ? candidate.id : `ig_${results.length}`;
+	if (results.some((result) => result.id === id)) return;
+	results.push({
+		id,
+		result: candidate.result,
+		outputFormat: typeof candidate.output_format === "string" ? candidate.output_format : "png",
+		revisedPrompt: typeof candidate.revised_prompt === "string" ? candidate.revised_prompt : undefined,
+		imageModel: typeof candidate.model === "string" ? candidate.model : fallbackImageModel,
+	});
+}
+
+function collectResponseText(value: unknown, out: string[]): void {
+	if (!value || typeof value !== "object") return;
+	const item = value as Record<string, unknown>;
+	for (const key of ["text", "refusal", "summary_text", "message"] as const) {
+		const text = item[key];
+		if (typeof text === "string" && text.trim()) out.push(text.trim());
+	}
+	for (const key of ["content", "output", "summary"] as const) {
+		const child = item[key];
+		if (Array.isArray(child)) for (const part of child) collectResponseText(part, out);
+	}
+}
+
+export function summarizeNonImageResponse(response: Record<string, unknown> | undefined): string {
+	if (!response) return "No image was returned by Codex.";
+	const status = typeof response.status === "string" ? response.status : undefined;
+	const error = response.error && typeof response.error === "object" ? response.error as Record<string, unknown> : undefined;
+	const errorMessage = typeof error?.message === "string" ? error.message : undefined;
+	const texts: string[] = [];
+	collectResponseText(response, texts);
+	const text = [...new Set(texts)].join(" ").replace(/\s+/g, " ").trim();
+	const details = [status && status !== "completed" ? `status ${status}` : undefined, errorMessage, text].filter(Boolean).join(" · ");
+	return details ? `No image was returned by Codex: ${details}` : "No image was returned by Codex.";
+}
+
+function renderImageGenError(details: ImageGenerationErrorDetails, theme: Theme): Component {
+	return {
+		invalidate() {},
+		render(width: number): string[] {
+			const safeWidth = Math.max(1, width);
+			const message = details.message || "Image generation failed.";
+			const promptWidth = Math.max(16, safeWidth - 28);
+			const lines = [
+				`${theme.fg("error", "● ")}${theme.fg("text", theme.bold("Image Generation "))}${theme.fg("error", "failed")}`,
+			];
+			if (details.imageModel) lines.push(`${panelBranch(theme, "├")}${theme.fg("text", "Model ")}${theme.fg("muted", details.imageModel)}`);
+			if (details.referenceCount && details.referenceCount > 0) lines.push(`${panelBranch(theme, "├")}${theme.fg("text", "Refs ")}${theme.fg("muted", `${details.referenceCount}`)}`);
+			if (details.prompt) lines.push(`${panelBranch(theme, "├")}${theme.fg("text", "Prompt ")}${theme.fg("muted", truncateToWidth(details.prompt, promptWidth, "…"))}`);
+			lines.push(`${panelBranch(theme, "└")}${theme.fg("error", truncateToWidth(message, Math.max(16, safeWidth - 5), "…"))}`);
+			return lines.map((line) => truncateToWidth(line, safeWidth, ""));
+		},
+	};
+}
+
+async function runBackgroundImageGeneration(pi: ExtensionAPI, ctx: ExtensionCommandContext, parsed: ParsedImageGenCommand, signal: AbortSignal): Promise<void> {
+	signal.throwIfAborted();
+	const model = selectCodexImageModel(ctx.model as ModelLike | undefined, ctx.modelRegistry as ModelRegistryLike | undefined) as Model<Api> | undefined;
+	if (!model) throw new Error("No image-capable model with an enabled model catalog profile is available.");
+	const settings = loadModelSettings(model as ModelLike, ctx.cwd);
+	if (!settings.enabled) throw new Error("pi-codex-minimal-tools is disabled.");
+	if (settings.imageGenerationImplementation === "standalone") {
+		const result = await standaloneImageGeneration({
+			prompt: parsed.prompt,
+			referenced_image_paths: parsed.imagePaths,
+		}, {
+			cwd: ctx.cwd,
+			model,
+			modelRegistry: ctx.modelRegistry,
+		}, settings, signal, { callId: "standalone" });
+		signal.throwIfAborted();
+		const saved = result.details.saved;
+		const workspaceRoot = projectRoot(ctx.cwd);
+		const relativePath = relative(workspaceRoot, saved.path);
+		const latestAbsolutePath = saved.latestPath ?? saved.path;
+		const latestRelativePath = relative(workspaceRoot, latestAbsolutePath);
+		const savedImage: SavedGeneratedImage = {
+			absolutePath: saved.path,
+			relativePath: relativePath && !relativePath.startsWith("..") ? relativePath : saved.path,
+			latestAbsolutePath,
+			latestRelativePath: latestRelativePath && !latestRelativePath.startsWith("..")
+				? latestRelativePath
+				: latestAbsolutePath,
+			responseId: undefined,
+			callId: "standalone",
+			outputFormat: saved.format,
+			imageModel: settings.imageModel,
+			revisedPrompt: parsed.prompt,
+		};
+		pi.sendMessage({
+			customType: IMAGE_SAVE_DISPLAY_MESSAGE_TYPE,
+			content: [{ type: "text", text: buildGeneratedImageDisplayText(savedImage, { expanded: false }) }],
+			display: true,
+			details: { savedImages: [savedImage] },
+		}, { triggerTurn: false });
+		return;
+	}
+	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 is configured for ${model.provider}.`);
+	}
+	const referenceImages = await Promise.all(parsed.imagePaths.map((path) => loadReferenceImage(ctx.cwd, path)));
+	signal.throwIfAborted();
+	const body = buildBackgroundImageRequest({
+		prompt: parsed.prompt,
+		referenceImages,
+		responsesModel: model.id,
+		imageModel: settings.imageModel,
+	});
+	const response = await fetch(resolveCodexUrl(model.baseUrl, { apiKeyMode: settings.apiKeyMode }), {
+		signal,
+		method: "POST",
+		headers: buildHeaders(model, {
+			apiKey: auth.apiKey,
+			headers: auth.headers,
+		}, { apiKeyMode: settings.apiKeyMode }),
+		body: JSON.stringify(body),
+	});
+	signal.throwIfAborted();
+	if (!response.ok) throw new Error(`Codex image generation failed: ${response.status} ${await response.text()}`);
+	const results: CodexImageResult[] = [];
+	let responseId: string | undefined;
+	let lastResponse: Record<string, unknown> | undefined;
+	for await (const event of parseSseEvents(response, signal)) {
+		if (event.type === "response.created" && event.response && typeof event.response === "object") {
+			lastResponse = event.response as Record<string, unknown>;
+			const id = (event.response as { id?: unknown }).id;
+			if (typeof id === "string") responseId = id;
+		}
+		if (event.type === "response.output_item.done") collectImageResult(results, event.item, settings.imageModel);
+		if ((event.type === "response.completed" || event.type === "response.done") && event.response && typeof event.response === "object") {
+			lastResponse = event.response as Record<string, unknown>;
+			const responseOutput = (event.response as { output?: unknown }).output;
+			if (Array.isArray(responseOutput)) for (const item of responseOutput) collectImageResult(results, item, settings.imageModel);
+		}
+	}
+	if (results.length === 0) throw new Error(summarizeNonImageResponse(lastResponse));
+	const savedImages = [];
+	for (const result of results) {
+		signal.throwIfAborted();
+		savedImages.push(await saveOpenAICodexGeneratedImage(ctx.cwd, {
+			responseId,
+			callId: result.id,
+			result: result.result,
+			outputFormat: result.outputFormat,
+			imageModel: result.imageModel,
+			revisedPrompt: result.revisedPrompt ?? parsed.prompt,
+		}));
+	}
+	signal.throwIfAborted();
+	pi.sendMessage({
+		customType: IMAGE_SAVE_DISPLAY_MESSAGE_TYPE,
+		content: [{ type: "text", text: buildGeneratedImageDisplayText(savedImages[0], { expanded: false }) }],
+		display: true,
+		details: { savedImages },
+	}, { triggerTurn: false });
+}
+
+export function registerBackgroundImageGenerationCommand(pi: ExtensionAPI): void {
+	const jobs = createBackgroundImageJobs();
+	pi.on("session_start", (_event, ctx) => jobs.reset(ctx));
+	pi.on("session_shutdown", (_event, ctx) => jobs.reset(ctx));
+	pi.registerMessageRenderer<ImageGenerationErrorDetails>(IMAGE_GEN_ERROR_MESSAGE_TYPE, (message, _options, theme) => {
+		const rawContent = typeof message.content === "string"
+			? message.content
+			: message.content
+					.filter((item) => item.type === "text")
+					.map((item) => item.text)
+					.join("\n");
+		const details: ImageGenerationErrorDetails = {
+			message: message.details?.message ?? rawContent.replace(/^Image generation failed:\s*/i, "") ?? "Image generation failed.",
+			prompt: message.details?.prompt,
+			imageModel: message.details?.imageModel,
+			referenceCount: message.details?.referenceCount,
+		};
+		return renderImageGenError(details, theme);
+	});
+
+	pi.registerCommand("image-gen", {
+		description: "Generate or edit an image in the background with the current model catalog. Usage: /image-gen prompt text [@reference.png]",
+		handler: async (args, ctx) => {
+			const parsed = parseImageGenCommandArgs(args);
+			if (!parsed.prompt) {
+				ctx.ui.notify("Usage: /image-gen prompt text [@reference.png]", "warning");
+				return;
+			}
+			const settings = loadSettings(ctx.cwd);
+			const job = jobs.start(ctx, parsed, settings.imageModel);
+			ctx.ui.notify(`Queued image generation with ${settings.imageModel}${parsed.imagePaths.length ? ` (${parsed.imagePaths.length} reference image${parsed.imagePaths.length === 1 ? "" : "s"})` : ""}.`, "info");
+			void runBackgroundImageGeneration(pi, ctx, parsed, job.signal)
+				.catch((error) => {
+					if (!job.isCurrent()) return;
+					const message = error instanceof Error ? error.message : String(error);
+					pi.sendMessage({
+						customType: IMAGE_GEN_ERROR_MESSAGE_TYPE,
+						content: `Image generation failed: ${message}`,
+						display: true,
+						details: { message, prompt: parsed.prompt, imageModel: settings.imageModel, referenceCount: parsed.imagePaths.length } satisfies ImageGenerationErrorDetails,
+					}, { triggerTurn: false });
+				})
+				.finally(() => job.finish())
+				.catch(() => {}); // Closed UI/API failures must not escape a detached job.
+		},
+	});
+}

package/src/background-image-jobs.ts

@@ -0,0 +1,116 @@
+import type { ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth, type Component } from "@earendil-works/pi-tui";
+import { frameGlyphs, glyphs, treeGlyph } from "@oai404iao/pi-codex-runtime/internal/glyphs";
+
+const STATUS_KEY = "codex-image-gen";
+const PADDING = 1;
+
+interface Job {
+	id: string;
+	startedAt: number;
+	prompt: string;
+	referenceCount: number;
+	imageModel: string;
+	controller: AbortController;
+}
+
+function padAnsi(text: string, width: number): string {
+	const truncated = truncateToWidth(text, width, "");
+	return `${truncated}${" ".repeat(Math.max(0, width - visibleWidth(truncated)))}`;
+}
+
+function panelFrame(lines: string[], width: number, theme: Theme): string[] {
+	const safeWidth = Math.max(1, width);
+	if (safeWidth < 8) return lines.map(line => truncateToWidth(line, safeWidth, ""));
+	const inner = Math.max(1, width - 2);
+	const contentWidth = Math.max(1, width - 2 - PADDING * 2);
+	const border = (text: string) => theme.fg("borderAccent", text);
+	const frame = frameGlyphs();
+	return [
+		`${border(frame.tl)}${border(frame.h.repeat(inner))}${border(frame.tr)}`,
+		...lines.map(line => `${border(frame.v)}${" ".repeat(PADDING)}${padAnsi(line, contentWidth)}${" ".repeat(PADDING)}${border(frame.v)}`),
+		`${border(frame.bl)}${border(frame.h.repeat(inner))}${border(frame.br)}`,
+	].map(line => truncateToWidth(line, safeWidth, ""));
+}
+
+export function panelBranch(theme: Theme, branch: "├" | "└" | "│"): string {
+	return theme.fg("muted", treeGlyph(branch));
+}
+
+function renderJobs(active: Map<string, Job>, theme: Theme, width: number): string[] {
+	const jobs = [...active.values()].sort((a, b) => a.startedAt - b.startedAt);
+	if (!jobs.length) return [];
+	const elapsed = Math.max(0, Math.round((Date.now() - jobs[0]!.startedAt) / 1000));
+	const imageModels = [...new Set(jobs.map(job => job.imageModel))];
+	const modelText = imageModels.length === 1 ? imageModels[0] : `${imageModels.length} models`;
+	const refs = jobs.reduce((total, job) => total + job.referenceCount, 0);
+	const refText = refs > 0 ? ` · ${refs} ref${refs === 1 ? "" : "s"}` : "";
+	const lines = [`${theme.fg("customMessageLabel", theme.bold("Image Generation"))} ${theme.fg("muted", `${jobs.length} running · ${modelText}${refText} · ${elapsed}s`)}`];
+	const dot = theme.fg("dim", glyphs().dot);
+	const shown = jobs.slice(0, 4);
+	for (const [index, job] of shown.entries()) {
+		const age = Math.max(0, Math.round((Date.now() - job.startedAt) / 1000));
+		const isLast = index === shown.length - 1 && jobs.length <= shown.length;
+		const references = job.referenceCount > 0 ? `${dot}${theme.fg("dim", `${job.referenceCount} ref${job.referenceCount === 1 ? "" : "s"}`)}` : "";
+		const promptWidth = Math.max(16, width - 36);
+		lines.push(`${panelBranch(theme, isLast ? "└" : "├")}${theme.fg("accent", glyphs().bullet.trim())} ${theme.fg("accent", truncateToWidth(job.prompt, promptWidth, glyphs().ellipsis))}${dot}${theme.fg("muted", job.imageModel)}${references}${dot}${theme.fg("dim", `${age}s`)}`);
+	}
+	if (jobs.length > shown.length) lines.push(`${panelBranch(theme, "└")}${theme.fg("muted", `${glyphs().ellipsis} ${jobs.length - shown.length} more`)}`);
+	return panelFrame(lines, width, theme);
+}
+
+export function createBackgroundImageJobs() {
+	const jobs = new Map<string, Job>();
+	let generation = 0;
+	let timer: ReturnType<typeof setInterval> | undefined;
+	let statusContext: ExtensionContext | undefined;
+	const stopTimer = () => {
+		if (timer !== undefined) clearInterval(timer);
+		timer = undefined;
+	};
+	const update = (ctx: ExtensionContext) => {
+		statusContext = ctx;
+		ctx.ui?.setStatus(STATUS_KEY, jobs.size ? `image-gen ${jobs.size}` : undefined);
+		ctx.ui?.setWidget(STATUS_KEY, jobs.size ? (_tui: unknown, theme: Theme): Component => ({
+			invalidate() {},
+			render: width => renderJobs(jobs, theme, width),
+		}) : undefined, { placement: "aboveEditor" });
+		if (!jobs.size) stopTimer();
+		else if (timer === undefined) {
+			timer = setInterval(() => { if (statusContext) update(statusContext); }, 1000);
+			timer.unref?.();
+		}
+	};
+	return {
+		start(ctx: ExtensionContext, parsed: { prompt: string; imagePaths: string[] }, imageModel: string) {
+			const epoch = generation;
+			const job: Job = {
+				id: `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`,
+				startedAt: Date.now(), prompt: parsed.prompt, referenceCount: parsed.imagePaths.length,
+				imageModel, controller: new AbortController(),
+			};
+			jobs.set(job.id, job);
+			update(ctx);
+			const isCurrent = () => epoch === generation && !job.controller.signal.aborted;
+			return {
+				signal: job.controller.signal,
+				isCurrent,
+				finish() {
+					if (!isCurrent()) return;
+					jobs.delete(job.id);
+					update(ctx);
+				},
+			};
+		},
+		reset(ctx?: ExtensionContext) {
+			generation++;
+			for (const job of jobs.values()) job.controller.abort(new Error("Image generation session ended"));
+			jobs.clear();
+			stopTimer();
+			const current = ctx ?? statusContext;
+			statusContext = undefined;
+			current?.ui?.setStatus(STATUS_KEY, undefined);
+			current?.ui?.setWidget(STATUS_KEY, undefined);
+		},
+	};
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { addPackageTool, ensureCodexServices } from "@oai404iao/pi-codex-runtime";
+import { currentCodexTurn } from "@oai404iao/pi-codex-runtime/internal/codex-wire-identity";
+import { loadModelSettings } from "@oai404iao/pi-codex-runtime/internal/model-catalog/runtime";
+import { loadSettings } from "@oai404iao/pi-codex-runtime/internal/settings";
+import { registerBackgroundImageGenerationCommand } from "./background-image-generation.js";
+import { createImageGenerationToolDefinition } from "./tools/image-generation.js";
+import { createImageCapture } from "./tools/image-generation/capture.js";
+import { createImageDisplay } from "./tools/image-generation/display.js";
+
+export default function codexImagegen(pi: ExtensionAPI): void {
+	const broker = ensureCodexServices(pi);
+	if (!broker.claim("package:imagegen")) return;
+	const display = createImageDisplay(pi);
+	broker.addPresentation("image_generation", {
+		clear: display.clear,
+		flush: display.flush,
+		scheduleFlush: display.scheduleFlush,
+		registerRenderers: display.registerRenderer,
+		streamEffects() {
+			const sink = display.captureSink();
+			return { createEventObserver: context => createImageCapture(context, sink) };
+		},
+	});
+	addPackageTool(broker, "image_generation", () => {
+		pi.registerTool(createImageGenerationToolDefinition({
+			loadSettings: (cwd, model) => loadModelSettings(model, cwd),
+			getCurrentTurnId: sessionId => currentCodexTurn(sessionId)?.turnId,
+			hasProviderRuntime: () => broker.coreEnabled,
+		}) as never);
+	});
+	if (loadSettings().enabled) registerBackgroundImageGenerationCommand(pi);
+}

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

@@ -0,0 +1,42 @@
+import type { ProviderEventContext } from "@oai404iao/pi-codex-runtime/internal/providers/openai-codex/stream-effects";
+import type { StreamEventShape } from "@oai404iao/pi-codex-runtime/internal/providers/openai-codex/types";
+import { loadSettings } from "@oai404iao/pi-codex-runtime/internal/settings";
+import { normalizeImageOutputFormat, saveOpenAICodexGeneratedImage } from "./storage.js";
+import type { SavedGeneratedImage } from "./types.js";
+
+export function createImageCapture(
+	context: ProviderEventContext,
+	onImageSaved: (image: SavedGeneratedImage, data: { data: string; mimeType: string }) => void,
+	saveImage = saveOpenAICodexGeneratedImage,
+) {
+	let responseId: string | undefined;
+	return async (event: StreamEventShape): Promise<void> => {
+		if (event.type === "response.created" && event.response?.id) responseId = event.response.id;
+		if (context.signal?.aborted) return;
+		if (event.type !== "response.output_item.done" || event.item?.type !== "image_generation_call") return;
+		const callId = typeof event.item.id === "string" ? event.item.id : undefined;
+		const result = typeof event.item.result === "string" ? event.item.result : undefined;
+		if (!callId || !result) return;
+		try {
+			const outputFormat = typeof event.item.output_format === "string" ? event.item.output_format : undefined;
+			const normalizedOutputFormat = normalizeImageOutputFormat(outputFormat);
+			const settings = loadSettings(context.cwd);
+			const imageModel = typeof event.item.model === "string" ? event.item.model : settings.imageModel;
+			const saved = await saveImage(context.cwd, {
+				responseId,
+				callId,
+				result,
+				outputFormat: normalizedOutputFormat,
+				imageModel,
+				revisedPrompt:
+					typeof event.item.revised_prompt === "string" ? event.item.revised_prompt : context.requestPrompt,
+			});
+			if (!context.signal?.aborted) {
+				onImageSaved(saved, { data: result, mimeType: `image/${normalizedOutputFormat}` });
+			}
+		} catch {
+			// Persistence is best-effort. Raw diagnostics here would corrupt the
+			// active TUI; failures must not discard the provider response/replay.
+		}
+	};
+}