@oai404iao/pi-codex-imagegen 0.4.0 → 2.0.0

package/README.md

@@ -2,13 +2,13 @@
 
 See the package guide below for release status; source edits do not publish artifacts.
 
-Peer floor and development target: Pi 0.99.1.
+Peer floor and development target: Pi 1.2.0.
 
-Hosted generation is model-only, including with native codemode in `only` mode.
-Standalone generation remains directly callable and is also available to
-codemode while active. Exposure follows the selected model profile; this does
-not enable codemode itself. A hosted profile with explicit direct fallback
-remains model-only.
+Image generation uses standalone Images endpoints and is directly callable,
+including through codemode while active. This does not enable codemode itself.
+Hosted Responses image generation and `directImageApiFallback` have been removed.
+Legacy hosted profiles are disabled with a diagnostic rather than silently routed
+to a different implementation. Historical image outputs still replay and display.
 
 Codemode scripts receive `{ path, latestPath?, image: { type, data, mimeType } }`.
 The image data is base64; use `image(result.image)` to forward it to the model.
@@ -24,17 +24,19 @@ new image writes. Already-started server generation or disk writes cannot be
 rolled back; cancellation is not a guarantee of avoiding provider charges.
 
 Installs `image_generation`, background image commands, image persistence and
-presentation. Depends only on `pi-codex-runtime`, not core, web-search or the bundle.
+presentation. Its only workspace dependency is `pi-codex-runtime`, not core,
+web-search or the bundle. Photon supplies image decoding and PNG encoding.
 When global `config.json.imageGeneration` is `false`, none of those generation
-surfaces are registered. The gate also blocks late/manual standalone and direct
-fallback execution before authentication or network I/O.
+surfaces are registered. The gate also blocks late/manual standalone execution
+before authentication or network I/O.
 Catalog-supported standalone profiles call Images generation/edit endpoints with
-Pi authentication. Hosted profiles need core unless the existing
-`directImageApiFallback` option was explicitly enabled.
-All image paths, including this explicit fallback and background jobs, use
+Pi authentication. `transparent_background:true` requests transparency;
+omitted or false requests an opaque background. References are sniffed by content,
+including extensionless PNG/JPEG/WebP; GIF/BMP normalize to PNG without resizing.
+All image paths, including background jobs, use
 the selected provider's Pi-resolved credentials, headers and base URL. The
-fallback no longer reads a separate `OPENAI_API_KEY` or forces the public
-OpenAI endpoint. Authentication failure never switches accounts or providers.
+client never reads a separate `OPENAI_API_KEY` or forces the public OpenAI endpoint.
+Authentication failure never switches accounts or providers.
 `endpoint_config.imageGeneration` limits allowed modes at the authenticated
 endpoint. Rejected/denied standalone jobs do not fall through to hosted jobs.
 Explicit protocol rejection temporarily disables that mode for the session,
@@ -53,13 +55,13 @@ providers. Reserved endpoints remain unsupported compatibility surfaces.
 See [the package guide](../../docs/codex-packages.md). From repository root:
 
 ```bash
-npm run check -w @oai404iao/pi-codex-imagegen
-npm run test:codex-composition
-npm run test:codex-packages
+pnpm --filter @oai404iao/pi-codex-imagegen run check
+pnpm run test:codex-composition
+pnpm run test:codex-packages
 ```
 
-Client/capture/display/background-job regressions are in `tests/`; hosted
-transport integration is in root `tests/codex/`. See the
+Client/capture/display/background-job regressions are in `tests/`; cross-package
+integration is in root `tests/codex/`. See the
 [shared configuration guide](../pi-codex-runtime/reference/configuration.md) and
 [image-generation example](assets/image-generation.gif). The example is a
 repository asset, not part of the runtime tarball.

package/THIRD_PARTY_NOTICES.md

@@ -11,8 +11,19 @@ apply-patch compatibility evidence remains pinned to
 The unmodified provenance record preserves upstream source identifiers, not
 claims that every referenced source file is shipped in this package.
 
+Image request behavior and the runtime-owned namespace declaration now follow
+Codex `5a3140176e668a2f72f3c098490eb7f7052d9d85`, including transparent-background
+requests. The runtime package ships the exact source and canonical-JSON hashes
+in `provenance/openai-codex-5a314017-image-generation.json`.
+The earlier provenance record remains historical evidence.
+
 Endpoint clients and presentation code are project implementations. Protocol
 shapes are consumed from pi-codex-runtime rather than copied here.
 
+Reference image normalization uses the separately distributed
+`@silvia-odwyer/photon-node` 0.3.4 dependency (Apache-2.0), retaining original
+dimensions and transparency when encoding GIF/BMP input as PNG. Its package
+includes its own license; no Photon source or WASM binary is vendored here.
+
 See `pi-codex-runtime/reference/source-map.md` in the repository for the pinned
 evidence map and `reference/configuration.md` there for image configuration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oai404iao/pi-codex-imagegen",
-  "version": "0.4.0",
+  "version": "2.0.0",
   "private": false,
   "description": "Unpublished pi-codex-imagegen workspace for the staged Codex split",
   "type": "module",
@@ -28,9 +28,9 @@
     ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.99.1",
-    "@earendil-works/pi-coding-agent": ">=0.99.1",
-    "@earendil-works/pi-tui": ">=0.99.1",
+    "@earendil-works/pi-ai": ">=1.2.0",
+    "@earendil-works/pi-coding-agent": ">=1.2.0",
+    "@earendil-works/pi-tui": ">=1.2.0",
     "typebox": "*"
   },
   "peerDependenciesMeta": {
@@ -45,22 +45,18 @@
     }
   },
   "dependencies": {
-    "@oai404iao/pi-codex-runtime": "0.5.0"
+    "@oai404iao/pi-codex-runtime": "2.0.0",
+    "@silvia-odwyer/photon-node": "0.3.4"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "0.99.1",
-    "@earendil-works/pi-coding-agent": "0.99.1",
-    "@earendil-works/pi-tui": "0.99.1",
+    "@earendil-works/pi-ai": "1.2.0",
+    "@earendil-works/pi-coding-agent": "1.2.0",
+    "@earendil-works/pi-tui": "1.2.0",
     "@types/node": "^26.2.0",
     "tsx": "^4.20.6",
     "typebox": "^1.1.24",
     "typescript": "^7.0.2"
   },
-  "scripts": {
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "tsx --test tests/**/*.test.ts",
-    "check": "npm run typecheck && npm test"
-  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -77,5 +73,10 @@
   "engines": {
     "node": ">=22.19.0"
   },
-  "gitHead": "8c96ca920ee51fe23c5c50d2cb2d8e1b304efe94"
-}
+  "gitHead": "cf3a22fc7855afd0d31e21999b3868da8cf67d5f",
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsx --test tests/**/*.test.ts",
+    "check": "pnpm run typecheck && pnpm run test"
+  }
+}

package/src/background-image-generation.ts

@@ -1,31 +1,17 @@
-import type { Api, Model, ProviderHeaders } from "@earendil-works/pi-ai";
+import type { Api, Model } 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 { relative } from "node:path";
 import { supportsImageInput, type ModelLike } from "@oai404iao/pi-codex-runtime/internal/capabilities";
-import {
-	buildCodexJsonHeaders,
-	hasCodexRequestAuth,
-	resolveResponsesUrl,
-	type ResponsesProtocol,
-	withResolvedAuthBaseUrl,
-} 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 { buildGeneratedImageDisplayText } 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";
-import { checkEndpointResponse, rememberResolvedEndpoint, reportEndpointFailure, requireEndpointCapability } from "@oai404iao/pi-codex-runtime/internal/endpoint-state";
 
-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 {
@@ -33,20 +19,6 @@ export interface ParsedImageGenCommand {
 	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;
@@ -60,12 +32,10 @@ interface ModelRegistryLike {
 	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");
+	if (!value || typeof value !== "object") return false;
+	const record = value as Record<string, unknown>;
+	return typeof record.provider === "string" && (typeof record.id === "string" || typeof record.name === "string");
 }
 
 function registryModels(registry: ModelRegistryLike | undefined): ModelLike[] {
@@ -85,21 +55,21 @@ function registryModels(registry: ModelRegistryLike | undefined): ModelLike[] {
 function isConfiguredImageModel(model: ModelLike | undefined): boolean {
 	if (!model || !supportsImageInput(model)) return false;
 	const settings = loadModelSettings({ ...model, baseUrl: undefined });
-	return Boolean(settings.modelProfile?.effective.enabled && settings.imageGenerationImplementation);
+	return Boolean(settings.modelProfile?.effective.enabled && settings.imageGenerationImplementation === "standalone");
 }
 
 export function selectCodexImageModel(currentModel: ModelLike | undefined, registry: ModelRegistryLike | undefined): ModelLike | undefined {
-	const currentSettings = currentModel && loadModelSettings({ ...currentModel, baseUrl: undefined });
-	if (currentModel && supportsImageInput(currentModel) && currentSettings?.imageGenerationImplementation) return currentModel;
+	const profile = currentModel && loadModelSettings({ ...currentModel, baseUrl: undefined }).modelProfile;
+	if (profile?.removedHostedImageGeneration) {
+		throw new Error(`Hosted image generation was removed for ${profile.id}. Change tools.imageGeneration to standalone or false in models.json; no alternate model was selected.`);
+	}
+	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;
+		if (!profile.effective.enabled || profile.effective.tools.imageGeneration !== "standalone") continue;
 		const slash = profile.id.indexOf("/");
-		const candidate = registry?.find?.(
-			profile.id.slice(0, slash),
-			profile.id.slice(slash + 1),
-		);
+		const candidate = registry?.find?.(profile.id.slice(0, slash), profile.id.slice(slash + 1));
 		if (isModelLike(candidate) && isConfiguredImageModel(candidate)) return candidate;
 	}
 	return undefined;
@@ -143,7 +113,7 @@ function tokenizeArgs(input: string): string[] {
 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);
+	return /\.(?:png|jpe?g|webp|gif|bmp)$/i.test(normalized);
 }
 
 export function parseImageGenCommandArgs(input: string): ParsedImageGenCommand {
@@ -157,140 +127,6 @@ export function parseImageGenCommandArgs(input: string): ParsedImageGenCommand {
 	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 buildHeaders(
-	model: Model<Api>,
-	auth: { apiKey?: string; headers?: ProviderHeaders },
-	endpoint: ResponsesProtocol,
-	codexRequestExtensions: boolean,
-): Headers {
-	const headers = buildCodexJsonHeaders({
-		modelHeaders: model.headers,
-		auth,
-		endpoint,
-		codexRequestExtensions,
-	});
-	if (codexRequestExtensions || endpoint === "codex") 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() {},
@@ -313,117 +149,32 @@ function renderImageGenError(details: ImageGenerationErrorDetails, theme: Theme)
 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.");
+	if (!model) throw new Error("No image-capable model with an enabled standalone model catalog profile is available.");
 	const settings = loadModelSettings({ ...model, baseUrl: undefined }, ctx.cwd);
-	if (!settings.imageGenerationImplementation) throw new Error("Image generation is disabled for the selected model.");
-	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,
-			sessionManager: ctx.sessionManager,
-		}, 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);
-	const requestModel = withResolvedAuthBaseUrl(model, auth);
-	const sessionId = ctx.sessionManager.getSessionId();
-	rememberResolvedEndpoint(model, requestModel, sessionId);
-	requireEndpointCapability(settings.endpoint_config, requestModel, sessionId, "imageGeneration.hosted");
-	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(resolveResponsesUrl(auth.baseUrl ?? model.baseUrl, settings.responsesEndpoint), {
-		signal,
-		method: "POST",
-		headers: buildHeaders(model, {
-			apiKey: auth.apiKey,
-			headers: auth.headers,
-		}, settings.responsesEndpoint, settings.codexRequestExtensions),
-		body: JSON.stringify(body),
-	});
-	signal.throwIfAborted();
-	await checkEndpointResponse(response, requestModel, sessionId, ["imageGeneration.hosted"], signal);
-	const results: CodexImageResult[] = [];
-	let responseId: string | undefined;
-	let lastResponse: Record<string, unknown> | undefined;
-	for await (const event of parseSseEvents(response, signal)) {
-		if (event.type === "error" || event.type === "response.failed") {
-			reportEndpointFailure(requestModel, sessionId, ["imageGeneration.hosted"], event.error ?? (event.response as { error?: unknown } | undefined)?.error);
-		}
-		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,
-		}));
-	}
+	const result = await standaloneImageGeneration({
+		prompt: parsed.prompt, referenced_image_paths: parsed.imagePaths,
+	}, {
+		cwd: ctx.cwd, model, modelRegistry: ctx.modelRegistry, sessionManager: ctx.sessionManager,
+	}, 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: result.details.requestId,
+		callId: "standalone", outputFormat: saved.format, imageModel: settings.imageModel,
+		revisedPrompt: parsed.prompt,
+	};
 	pi.sendMessage({
 		customType: IMAGE_SAVE_DISPLAY_MESSAGE_TYPE,
-		content: [{ type: "text", text: buildGeneratedImageDisplayText(savedImages[0], { expanded: false }) }],
-		display: true,
-		details: { savedImages },
+		content: [{ type: "text", text: buildGeneratedImageDisplayText(savedImage, { expanded: false }) }],
+		display: true, details: { savedImages: [savedImage] },
 	}, { triggerTurn: false });
 }
 
@@ -432,23 +183,15 @@ export function registerBackgroundImageGenerationCommand(pi: ExtensionAPI): void
 	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 = {
+		const rawContent = typeof message.content === "string" ? message.content
+			: message.content.filter((item) => item.type === "text").map((item) => item.text).join("\n");
+		return renderImageGenError({
 			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);
+			prompt: message.details?.prompt, imageModel: message.details?.imageModel, referenceCount: message.details?.referenceCount,
+		}, 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]",
+		description: "Generate or edit an image in the background with the standalone Images API. Usage: /image-gen prompt text [@reference.png]",
 		handler: async (args, ctx) => {
 			const parsed = parseImageGenCommandArgs(args);
 			if (!parsed.prompt) {
@@ -464,8 +207,7 @@ export function registerBackgroundImageGenerationCommand(pi: ExtensionAPI): void
 					const message = error instanceof Error ? error.message : String(error);
 					pi.sendMessage({
 						customType: IMAGE_GEN_ERROR_MESSAGE_TYPE,
-						content: `Image generation failed: ${message}`,
-						display: true,
+						content: `Image generation failed: ${message}`, display: true,
 						details: { message, prompt: parsed.prompt, imageModel: settings.imageModel, referenceCount: parsed.imagePaths.length } satisfies ImageGenerationErrorDetails,
 					}, { triggerTurn: false });
 				})

package/src/index.ts

@@ -27,7 +27,6 @@ export default function codexImagegen(pi: ExtensionAPI): void {
 	const definition = createImageGenerationToolDefinition({
 		loadSettings: (cwd, model) => loadModelSettings(model, cwd),
 		getCurrentTurnId: sessionId => currentCodexTurn(sessionId)?.turnId,
-		hasProviderRuntime: () => broker.coreEnabled,
 	});
 	const parameters = { ...definition.parameters };
 	broker.ownedTools.set("image_generation", { parameters, description: definition.description });

package/src/tools/image-generation.ts

@@ -1,28 +1,21 @@
-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 { isAbsolute, resolve } from "node:path";
+import { buildSessionContext, detectSupportedImageMimeTypeFromFile, type SessionEntry } from "@earendil-works/pi-coding-agent";
 import { saveBase64Image } from "../utils/images.js";
 import { imageGenerationOutput, imageGenerationOutputSchema } from "./image-generation/output.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,
-	withResolvedAuthBaseUrl,
-} from "@oai404iao/pi-codex-runtime/internal/codex-http";
+import { buildCodexJsonHeaders, hasCodexRequestAuth, resolveCodexApiEndpoint, withResolvedAuthBaseUrl } from "@oai404iao/pi-codex-runtime/internal/codex-http";
 import { loadModelSettings, type ResolvedCodexModelSettings } from "@oai404iao/pi-codex-runtime/internal/model-catalog/runtime";
 import { checkEndpointResponse, rememberResolvedEndpoint, requireEndpointCapability } from "@oai404iao/pi-codex-runtime/internal/endpoint-state";
+import { currentCodexTurn, uuidV7 } from "@oai404iao/pi-codex-runtime/internal/codex-wire-identity";
+import { fetchCodexJson } from "@oai404iao/pi-codex-runtime/internal/json-request";
 
 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";
+	referenced_image_paths?: string[] | null;
+	num_last_images_to_include?: number | null;
+	transparent_background?: boolean;
 }
 
 export const imageGenerationToolSchema = {
@@ -31,74 +24,22 @@ export const imageGenerationToolSchema = {
 	properties: {
 		prompt: { type: "string", description: "Image generation or editing prompt." },
 		referenced_image_paths: {
-			type: "array",
-			maxItems: 5,
+			type: ["array", "null"], maxItems: 5,
 			items: { type: "string", minLength: 1 },
-			description: "Local PNG, JPEG, or WebP paths to edit.",
+			description: "Local image paths to edit. PNG, JPEG, WebP, GIF and BMP are supported.",
 		},
 		num_last_images_to_include: {
-			type: "integer",
-			minimum: 1,
-			maximum: 5,
+			type: ["integer", "null"], minimum: 1, maximum: 5,
 			description: "Use the newest conversation images when one or more targets have no local path.",
 		},
+		transparent_background: {
+			type: "boolean",
+			description: "Whether the output should have a transparent background. Defaults to false.",
+		},
 	},
 	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, ctx: ImageGenerationToolContext, settings: CodexMinimalToolsSettings, signal?: AbortSignal) {
-	if (!settings.imageGeneration) throw new Error("Image generation is disabled by the global imageGeneration setting.");
-	if (!settings.directImageApiFallback) throw new Error("Direct Images API fallback is disabled. Use the configured image implementation, or enable directImageApiFallback.");
-	if (!input.prompt?.trim()) throw new Error("A prompt is required for direct image_generation fallback.");
-	signal?.throwIfAborted();
-	const model = ctx.model;
-	if (!model || !ctx.modelRegistry) throw new Error("No active model is available for direct image generation.");
-	const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
-	signal?.throwIfAborted();
-	if (!auth.ok) throw new Error(auth.error);
-	const requestModel = withResolvedAuthBaseUrl(model, auth);
-	const sessionId = ctx.sessionManager?.getSessionId?.();
-	rememberResolvedEndpoint(model, requestModel, sessionId);
-	requireEndpointCapability(settings.endpoint_config, requestModel, sessionId, "imageGeneration.standalone");
-	if (!hasCodexRequestAuth({ modelHeaders: model.headers, auth })) {
-		throw new Error(`No request authentication for provider: ${model.provider}`);
-	}
-	const endpoint = loadModelSettings(model, ctx.cwd, settings).responsesEndpoint;
-	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(resolveCodexApiEndpoint(auth.baseUrl ?? model.baseUrl, endpoint, "images/generations"), {
-		method: "POST",
-		headers: buildCodexJsonHeaders({ modelHeaders: model.headers, auth, endpoint, codexRequestExtensions: settings.codexRequestExtensions }),
-		body: JSON.stringify(body),
-		signal,
-	});
-	await checkEndpointResponse(response, requestModel, sessionId, ["imageGeneration.standalone"], signal);
-	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.");
-	signal?.throwIfAborted();
-	const saved = await saveBase64Image({ base64, callId: "direct", cwd: ctx.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" },
-		structuredContent: imageGenerationOutput(saved, base64),
-	};
-}
-
 interface ImageGenerationToolContext {
 	cwd: string;
 	model?: Model<Api>;
@@ -124,26 +65,27 @@ async function referencedImageUrls(cwd: string, paths: readonly string[]): Promi
 	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 mimeType = await detectSupportedImageMimeTypeFromFile(path);
+		if (!mimeType) throw new Error(`Unsupported reference image type: ${rawPath}. Use PNG, JPEG, WebP, GIF, or BMP.`);
 		const data = await readFile(path);
+		if (mimeType === "image/gif" || mimeType === "image/bmp") {
+			// Codex Original mode normalizes unsupported source formats to PNG without resizing.
+			const { PhotonImage } = await import("@silvia-odwyer/photon-node");
+			const decoded = PhotonImage.new_from_byteslice(data);
+			try {
+				return { image_url: `data:image/png;base64,${Buffer.from(decoded.get_bytes()).toString("base64")}` };
+			} finally {
+				decoded.free();
+			}
+		}
 		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.");
+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.");
+	if (!Number.isSafeInteger(count) || count < 1 || count > 5) {
+		throw new Error("num_last_images_to_include must be an integer between 1 and 5.");
 	}
 	const messages = buildSessionContext(ctx.sessionManager.getBranch()).messages;
 	const images: string[] = [];
@@ -151,31 +93,20 @@ function recentConversationImageUrls(
 		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}`);
-				}
+				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
-			) {
+			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.`);
-	}
+	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 }));
 }
 
@@ -188,84 +119,69 @@ export async function standaloneImageGeneration(
 ) {
 	signal?.throwIfAborted();
 	const callId = invocation.callId ?? "standalone";
-	const turnId = invocation.turnId ?? randomUUID();
+	const sessionId = ctx.sessionManager?.getSessionId?.();
+	const turnId = invocation.turnId ?? currentCodexTurn(sessionId)?.turnId ?? uuidV7();
 	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 (!settings.imageGeneration) throw new Error("Image generation is disabled by the global setting or current model profile.");
+	if (settings.imageGenerationImplementation !== "standalone") throw new Error("Image generation requires a standalone model profile.");
 	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) {
+	if (input.transparent_background !== undefined && typeof input.transparent_background !== "boolean") {
+		throw new Error("transparent_background must be a boolean.");
+	}
+	if (input.num_last_images_to_include != null && input.referenced_image_paths?.length) {
 		throw new Error("Provide only one of referenced_image_paths or num_last_images_to_include.");
 	}
+	// Capture the invocation's images and turn before auth can yield to another turn.
+	const images = input.num_last_images_to_include != null
+		? recentConversationImageUrls(ctx, input.num_last_images_to_include)
+		: await referencedImageUrls(ctx.cwd, input.referenced_image_paths ?? []);
 	const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
 	signal?.throwIfAborted();
 	if (!auth.ok) throw new Error(auth.error);
 	const requestModel = withResolvedAuthBaseUrl(model, auth);
-	const sessionId = ctx.sessionManager?.getSessionId?.();
 	rememberResolvedEndpoint(model, requestModel, sessionId);
 	requireEndpointCapability(settings.endpoint_config, requestModel, sessionId, "imageGeneration.standalone");
-	if (!hasCodexRequestAuth({
-		modelHeaders: model.headers,
-		auth: { apiKey: auth.apiKey, headers: auth.headers },
-	})) {
+	if (!hasCodexRequestAuth({ modelHeaders: model.headers, auth })) {
 		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(
-			auth.baseUrl ?? model.baseUrl,
-			settings.responsesEndpoint,
-			edit ? "images/edits" : "images/generations",
-		),
+	const response = await fetchCodexJson(
+		resolveCodexApiEndpoint(auth.baseUrl ?? model.baseUrl, settings.responsesEndpoint, images.length ? "images/edits" : "images/generations"),
 		{
-			method: "POST",
 			headers: buildCodexJsonHeaders({
 				codexRequestExtensions: settings.codexRequestExtensions,
-				modelHeaders: model.headers,
-				auth: { apiKey: auth.apiKey, headers: auth.headers },
-				endpoint: settings.responsesEndpoint,
-				extraHeaders: settings.codexRequestExtensions ? {
-					"x-codex-image-turn-id": turnId,
-				} : undefined,
+				modelHeaders: model.headers, auth, endpoint: settings.responsesEndpoint,
+				extraHeaders: settings.codexRequestExtensions ? { "x-codex-image-turn-id": turnId } : undefined,
 			}),
 			body: JSON.stringify({
-				model: settings.imageModel,
-				prompt: input.prompt.trim(),
-				...(edit ? { images } : {}),
-				background: "auto",
-				quality: "auto",
-				size: "auto",
+				model: settings.imageModel, prompt: input.prompt,
+				...(images.length ? { images } : {}),
+				background: input.transparent_background === true ? "transparent" : "opaque",
+				quality: "auto", size: "auto",
 			}),
 			signal,
 		},
+		["imageGeneration.standalone"],
 	);
 	signal?.throwIfAborted();
 	await checkEndpointResponse(response, requestModel, sessionId, ["imageGeneration.standalone"], signal);
-	const result = await response.json() as {
-		data?: Array<{ b64_json?: string }>;
-	};
+	const result = await response.json() as { data?: Array<{ b64_json?: string; generation_id?: 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,
-	});
+	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" },
+		details: {
+			saved, mode: "standalone-images-api",
+			requestId: response.headers.get("x-codex-imagegen-request-id") ?? undefined,
+			generationId: result.data?.[0]?.generation_id,
+		},
 		structuredContent: imageGenerationOutput(saved, base64),
 	};
 }
@@ -273,12 +189,11 @@ export async function standaloneImageGeneration(
 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>.",
+		description: "Generate or edit images using the standalone Images API selected by the current model profile. Results are saved under imageOutputDir and mirrored to latest.png.",
 		promptSnippet: "Generate or edit images with the implementation selected by the current model profile.",
 		parameters: imageGenerationToolSchema,
 		outputSchema: imageGenerationOutputSchema,
@@ -286,28 +201,10 @@ export function createImageGenerationToolDefinition(options: {
 			const cwd = ctx?.cwd ?? process.cwd();
 			const profileModel = ctx.model ? { ...ctx.model, baseUrl: "" } : undefined;
 			const settings = options.loadSettings?.(cwd, profileModel) ?? loadModelSettings(profileModel, cwd);
-			const resolvedSettings = "modelProfile" in settings
-				? settings as ResolvedCodexModelSettings
-				: loadModelSettings(profileModel, cwd, settings);
-			if (!resolvedSettings.imageGeneration) {
-				throw new Error("Image generation is disabled by the global setting or current model profile.");
-			}
-			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, { ...ctx, 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 {
-				isError: true,
-				content: [{ type: "text", text: "image_generation should be handled by the current model profile. If no hosted or standalone implementation is configured, explicitly enable directImageApiFallback using the current provider's Pi authentication." }],
-				details: { phase: "native-provider", nativeTool: "image_generation" },
-			};
+			const resolved = "modelProfile" in settings ? settings as ResolvedCodexModelSettings : loadModelSettings(profileModel, cwd, settings);
+			return standaloneImageGeneration(params, { ...ctx, cwd }, resolved, signal, {
+				callId: toolCallId, turnId: options.getCurrentTurnId?.(ctx.sessionManager?.getSessionId?.()),
+			});
 		},
 	};
 }