pi-codex-image-gen 0.1.12 → 0.1.13

package/extensions/index.ts

@@ -3,17 +3,19 @@
  *
  * Registers `codex_generate_image`, a tool that uses Pi's existing
  * openai-codex ChatGPT/Codex auth to call the Codex Responses backend with the
- * native `image_generation` tool. The backend maps that tool to gpt-image-2.
+ * native `image_generation` tool. The backend selects the image model.
  */
 
 import { readFileSync } from "node:fs";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { mkdir, open, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
 import { StringEnum } from "@earendil-works/pi-ai";
-import { type ExtensionAPI, getAgentDir, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { CONFIG_DIR_NAME, type ExtensionAPI, getAgentDir, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
 import { reportInstallTelemetry } from "../src/install-telemetry.js";
+import { abortable, httpFailure, MAX_IMAGE_BYTES, parseCodexSse, withRequestDeadline, type ParsedCodexResponse } from "../src/codex-response.js";
 
 const PACKAGE_NAME = "pi-codex-image-gen";
 const PROVIDER = "openai-codex";
@@ -26,6 +28,9 @@ const MAX_RETRIES = 3;
 const BASE_DELAY_MS = 1000;
 const MAX_RETRY_DELAY_MS = 30_000;
 const MAX_EDIT_IMAGES = 5;
+const MAX_INPUT_IMAGE_BYTES = 20 * 1024 * 1024;
+const MAX_TOTAL_INPUT_BYTES = 50 * 1024 * 1024;
+const MAX_PROMPT_CHARS = 32_000;
 
 const SAVE_MODES = ["none", "project", "global", "custom"] as const;
 type SaveMode = (typeof SAVE_MODES)[number];
@@ -35,11 +40,6 @@ type OutputFormat = (typeof OUTPUT_FORMATS)[number];
 
 // --- #1: Retry helpers with exponential backoff + jitter ---
 
-function isRetryableStatus(status: number, errorText: string): boolean {
-	if ([429, 500, 502, 503, 504].includes(status)) return true;
-	return /rate.?limit|overloaded|service.?unavailable|upstream.?connect|connection.?refused/i.test(errorText);
-}
-
 export function parseRetryAfter(value: string | null, nowMs = Date.now()): number | undefined {
 	if (!value) return undefined;
 	const trimmed = value.trim();
@@ -89,9 +89,9 @@ export function abortableDelay(milliseconds: number, signal?: AbortSignal): Prom
 // --- Tool parameter schema ---
 
 const TOOL_PARAMS = Type.Object({
-	prompt: Type.String({ description: "The image prompt. Be specific about subject, composition, style, text, and constraints." }),
+	prompt: Type.String({ minLength: 1, maxLength: MAX_PROMPT_CHARS, description: "The image prompt. Be specific about subject, composition, style, text, and constraints." }),
 	model: Type.Optional(
-		Type.String({ description: `Codex model that should invoke image generation. Defaults to ${DEFAULT_MODEL}.` }),
+		Type.String({ minLength: 1, maxLength: 200, description: `Codex routing model, not an image model selector. Defaults to ${DEFAULT_MODEL}.` }),
 	),
 	outputFormat: Type.Optional(StringEnum(OUTPUT_FORMATS)),
 	save: Type.Optional(StringEnum(SAVE_MODES)),
@@ -130,44 +130,11 @@ interface SaveConfig {
 	outputDir?: string;
 }
 
-interface GeneratedImage {
-	id: string;
-	status: string;
-	result: string;
-	revisedPrompt?: string;
-}
-
-interface ParsedCodexResponse {
-	image?: GeneratedImage;
-	text: string[];
-	responseId?: string;
-	usage?: unknown;
-}
-
 interface InputImage {
 	data: string;
 	mimeType: string;
 }
 
-// --- #11: Typed SSE event discriminated union ---
-
-type CodexSseEvent =
-	| { type: "error"; message?: string; code?: string }
-	| { type: "response.failed"; response?: { error?: { message?: string } } }
-	| { type: "response.created"; response?: { id?: string } }
-	| { type: "response.output_text.delta"; delta?: string }
-	| {
-			type: "response.output_item.done";
-			item?: {
-				type?: string;
-				id?: string | number;
-				status?: string;
-				result?: string;
-				revised_prompt?: string;
-			};
-	  }
-	| { type: "response.completed"; response?: { id?: string; usage?: unknown } };
-
 // --- JWT helpers ---
 
 function decodeJwtPayload(token: string): Record<string, unknown> {
@@ -177,8 +144,8 @@ function decodeJwtPayload(token: string): Record<string, unknown> {
 	}
 	try {
 		return JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8")) as Record<string, unknown>;
-	} catch (error) {
-		throw new Error(`Failed to decode OpenAI Codex auth token: ${error instanceof Error ? error.message : String(error)}`);
+	} catch {
+		throw new Error("Failed to decode OpenAI Codex auth token. Run /login for openai-codex again.");
 	}
 }
 
@@ -208,7 +175,7 @@ function readConfigFile(path: string): ExtensionConfig {
 export function loadConfig(cwd: string, projectTrusted: boolean, agentDir = getAgentDir()): ExtensionConfig {
 	const globalConfig = readConfigFile(join(agentDir, "extensions", "codex-image-gen.json"));
 	if (!projectTrusted) return globalConfig;
-	const projectConfig = readConfigFile(join(cwd, ".pi", "extensions", "codex-image-gen.json"));
+	const projectConfig = readConfigFile(join(cwd, CONFIG_DIR_NAME, "extensions", "codex-image-gen.json"));
 	return { ...globalConfig, ...projectConfig };
 }
 
@@ -221,7 +188,7 @@ export function resolveUnderCwd(cwd: string, path: string, homeDir = homedir()):
 }
 
 function sanitizePathPart(value: string, fallback: string): string {
-	const sanitized = value
+	const sanitized = value.slice(0, 128)
 		.split("")
 		.map((ch) => (/[a-zA-Z0-9_-]/.test(ch) ? ch : "_"))
 		.join("")
@@ -239,7 +206,7 @@ function resolveSaveConfig(params: ToolParams, cwd: string, sessionId: string, c
 		throw new Error(`Invalid save mode: ${mode}. Expected one of ${SAVE_MODES.join(", ")}.`);
 	}
 	if (mode === "project") {
-		return { mode, outputDir: join(cwd, ".pi", "generated-images", safeSessionId) };
+		return { mode, outputDir: join(cwd, CONFIG_DIR_NAME, "generated-images", safeSessionId) };
 	}
 	if (mode === "global") {
 		return { mode, outputDir: join(getAgentDir(), "generated-images", safeSessionId) };
@@ -270,12 +237,13 @@ function imagePath(outputFormat: OutputFormat, outputDir: string, imageCallId: s
 }
 
 export function decodeImageData(base64Data: string, outputFormat: OutputFormat): Buffer {
+	if (base64Data.length > Math.ceil(MAX_IMAGE_BYTES / 3) * 4) throw new Error("Codex image exceeded the 32 MiB size limit.");
 	const value = base64Data.trim();
-	if (!value || value.length % 4 !== 0 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) {
+	if (!value || value.length % 4 !== 0 || /[^A-Za-z0-9+/=]/.test(value)) {
 		throw new Error("Codex returned invalid base64 image data.");
 	}
 	const bytes = Buffer.from(value, "base64");
-	if (bytes.length === 0 || bytes.toString("base64") !== value) {
+	if (bytes.length === 0 || bytes.length > MAX_IMAGE_BYTES || bytes.toString("base64") !== value) {
 		throw new Error("Codex returned invalid base64 image data.");
 	}
 	const validSignature =
@@ -294,8 +262,8 @@ async function saveImage(
 ): Promise<string> {
 	const filePath = imagePath(outputFormat, outputDir, imageCallId);
 	await withFileMutationQueue(filePath, async () => {
-		await mkdir(outputDir, { recursive: true });
-		await writeFile(filePath, bytes);
+		await mkdir(outputDir, { recursive: true, mode: 0o700 });
+		await writeFile(filePath, bytes, { flag: "wx", mode: 0o600 });
 	});
 	return filePath;
 }
@@ -322,6 +290,29 @@ function mimeFromBytes(bytes: Buffer, path: string): string {
 	throw new Error(`Referenced image is unavailable or unsupported: ${path}`);
 }
 
+async function readInputImage(path: string): Promise<Buffer> {
+	// O_NONBLOCK prevents named pipes from blocking before the regular-file check.
+	const file = await open(path, constants.O_RDONLY | (constants.O_NONBLOCK ?? 0));
+	try {
+		const info = await file.stat();
+		if (!info.isFile()) throw new Error("Referenced images must be regular files.");
+		if (info.size > MAX_INPUT_IMAGE_BYTES) throw new Error("Referenced image exceeds 20 MiB.");
+		const blocks: Buffer[] = [];
+		let total = 0;
+		while (true) {
+			const block = Buffer.alloc(Math.min(64 * 1024, MAX_INPUT_IMAGE_BYTES + 1 - total));
+			const { bytesRead } = await file.read(block, 0, block.length, null);
+			if (!bytesRead) break;
+			total += bytesRead;
+			if (total > MAX_INPUT_IMAGE_BYTES) throw new Error("Referenced image exceeds 20 MiB.");
+			blocks.push(block.subarray(0, bytesRead));
+		}
+		return Buffer.concat(blocks, total);
+	} finally {
+		await file.close();
+	}
+}
+
 export async function resolveInputImages(
 	params: ToolParams,
 	cwd: string,
@@ -333,19 +324,22 @@ export async function resolveInputImages(
 	}
 	if (paths.length > MAX_EDIT_IMAGES) throw new Error(`referencedImagePaths accepts at most ${MAX_EDIT_IMAGES} paths.`);
 	if (paths.length > 0) {
-		return Promise.all(
-			paths.map(async (path) => {
-				const normalized = path.startsWith("@") ? path.slice(1) : path;
-				const absolutePath = resolveUnderCwd(cwd, normalized);
-				let bytes: Buffer;
-				try {
-					bytes = await readFile(absolutePath);
-				} catch (error) {
-					throw new Error(`Unable to read referenced image at ${absolutePath}: ${error instanceof Error ? error.message : String(error)}`);
-				}
-				return { data: bytes.toString("base64"), mimeType: mimeFromBytes(bytes, absolutePath) };
-			}),
-		);
+		const images: InputImage[] = [];
+		let total = 0;
+		for (const path of paths) {
+			const normalized = path.startsWith("@") ? path.slice(1) : path;
+			const absolutePath = resolveUnderCwd(cwd, normalized);
+			let bytes: Buffer;
+			try {
+				bytes = await readInputImage(absolutePath);
+			} catch (error) {
+				throw new Error(`Unable to read referenced image at ${absolutePath}: ${error instanceof Error ? error.message : String(error)}`);
+			}
+			total += bytes.length;
+			if (total > MAX_TOTAL_INPUT_BYTES) throw new Error("Referenced images exceed 50 MiB in total.");
+			images.push({ data: bytes.toString("base64"), mimeType: mimeFromBytes(bytes, absolutePath) });
+		}
+		return images;
 	}
 	if (params.numLastImagesToInclude !== undefined) {
 		const count = params.numLastImagesToInclude;
@@ -356,6 +350,16 @@ export async function resolveInputImages(
 		if (images.length !== count) {
 			throw new Error(`Requested the last ${count} conversation images, but only ${images.length} were available.`);
 		}
+		let total = 0;
+		for (const image of images) {
+			if (image.data.length > Math.ceil(MAX_INPUT_IMAGE_BYTES / 3) * 4) throw new Error("Conversation image exceeds 20 MiB.");
+			const format = OUTPUT_FORMATS.find(format => mimeForFormat(format) === image.mimeType);
+			if (!format) throw new Error("Conversation image has an unsupported format.");
+			const bytes = decodeImageData(image.data, format);
+			if (bytes.length > MAX_INPUT_IMAGE_BYTES) throw new Error("Conversation image exceeds 20 MiB.");
+			total += bytes.length;
+			if (total > MAX_TOTAL_INPUT_BYTES) throw new Error("Conversation images exceed 50 MiB in total.");
+		}
 		return images;
 	}
 	return [];
@@ -399,108 +403,6 @@ export function buildRequestBody(
 	};
 }
 
-// --- SSE parsing ---
-
-function parseSseDataLines(chunk: string): string | undefined {
-	const data = chunk
-		.split("\n")
-		.filter((line) => line.startsWith("data:"))
-		.map((line) => line.slice(5).trim())
-		.join("\n")
-		.trim();
-	return data && data !== "[DONE]" ? data : undefined;
-}
-
-async function parseCodexSse(response: Response, signal?: AbortSignal): Promise<ParsedCodexResponse> {
-	if (!response.body) throw new Error("Codex response did not include a stream body.");
-	const reader = response.body.getReader();
-	const decoder = new TextDecoder();
-	let buffer = "";
-	const parsed: ParsedCodexResponse = { text: [] };
-
-	try {
-		while (true) {
-			if (signal?.aborted) throw new Error("Image generation was aborted.");
-			const { done, value } = await reader.read();
-			if (done) break;
-			buffer += decoder.decode(value, { stream: true });
-
-			let separator = buffer.indexOf("\n\n");
-			while (separator !== -1) {
-				const chunk = buffer.slice(0, separator);
-				buffer = buffer.slice(separator + 2);
-				const data = parseSseDataLines(chunk);
-				if (data) handleCodexEvent(JSON.parse(data) as CodexSseEvent, parsed);
-				separator = buffer.indexOf("\n\n");
-			}
-		}
-		const remaining = parseSseDataLines(buffer);
-		if (remaining) handleCodexEvent(JSON.parse(remaining) as CodexSseEvent, parsed);
-	} finally {
-		try {
-			await reader.cancel();
-		} catch {
-			// ignored: stream may already be closed
-		}
-		reader.releaseLock();
-	}
-
-	return parsed;
-}
-
-// --- #11: Typed event handler via discriminated union ---
-
-function handleCodexEvent(event: CodexSseEvent, parsed: ParsedCodexResponse): void {
-	if (!event || typeof event !== "object") return;
-
-	switch (event.type) {
-		case "error": {
-			const e = event as Extract<CodexSseEvent, { type: "error" }>;
-			throw new Error(`Codex error: ${e.message || e.code || JSON.stringify(event)}`);
-		}
-		case "response.failed": {
-			const e = event as Extract<CodexSseEvent, { type: "response.failed" }>;
-			throw new Error(e.response?.error?.message || "Codex response failed.");
-		}
-		case "response.created": {
-			const e = event as Extract<CodexSseEvent, { type: "response.created" }>;
-			if (typeof e.response?.id === "string") {
-				parsed.responseId = e.response.id;
-			}
-			break;
-		}
-		case "response.output_text.delta": {
-			const e = event as Extract<CodexSseEvent, { type: "response.output_text.delta" }>;
-			if (typeof e.delta === "string") {
-				parsed.text.push(e.delta);
-			}
-			break;
-		}
-		case "response.output_item.done": {
-			const e = event as Extract<CodexSseEvent, { type: "response.output_item.done" }>;
-			const item = e.item;
-			if (item?.type === "image_generation_call") {
-				if (typeof item.result !== "string" || item.result.length === 0) {
-					throw new Error("Codex image_generation_call did not contain image data.");
-				}
-				parsed.image = {
-					id: String(item.id || "image_generation"),
-					status: String(item.status || "completed"),
-					result: item.result,
-					revisedPrompt: typeof item.revised_prompt === "string" ? item.revised_prompt : undefined,
-				};
-			}
-			break;
-		}
-		case "response.completed": {
-			const e = event as Extract<CodexSseEvent, { type: "response.completed" }>;
-			if (typeof e.response?.id === "string") parsed.responseId = e.response.id;
-			if (e.response?.usage) parsed.usage = e.response.usage;
-			break;
-		}
-	}
-}
-
 // --- #1: requestImage with retry + backoff + jitter ---
 
 async function requestImage(
@@ -512,41 +414,46 @@ async function requestImage(
 	sessionId: string,
 	inputImages: InputImage[],
 	signal?: AbortSignal,
+	onProgress?: (stage: string) => void,
 ): Promise<ParsedCodexResponse> {
 	const body = JSON.stringify(buildRequestBody(params, model, outputFormat, sessionId, inputImages));
 	const headers: Record<string, string> = {
 		Authorization: `Bearer ${token}`,
 		"chatgpt-account-id": accountId,
 		originator: "pi",
+		"User-Agent": PACKAGE_NAME,
 		"OpenAI-Beta": OPENAI_BETA_HEADER,
 		accept: "text/event-stream",
 		"content-type": "application/json",
 	};
 
-	for (let attempt = 1; attempt <= MAX_RETRIES + 1; attempt++) {
-		if (signal?.aborted) throw new Error("Image generation was aborted.");
-
-		const response = await fetch(CODEX_RESPONSES_URL, {
-			method: "POST",
-			headers,
-			body,
-			signal,
-		});
-
-		if (!response.ok) {
-			const errorText = await response.text();
-			if (attempt <= MAX_RETRIES && isRetryableStatus(response.status, errorText)) {
-				const delay = retryDelayMs(attempt, response.headers.get("retry-after"));
-				await abortableDelay(delay, signal);
-				continue;
+	return withRequestDeadline(signal, async (signal) => {
+		for (let attempt = 1; attempt <= MAX_RETRIES + 1; attempt++) {
+			signal.throwIfAborted();
+			let response: Response;
+			try {
+				response = await abortable(fetch(CODEX_RESPONSES_URL, {
+					method: "POST", headers, body, signal, redirect: "error",
+				}), signal);
+			} catch {
+				signal.throwIfAborted();
+				throw new Error("Codex connection failed. No automatic retry was made; check connectivity before trying again.");
 			}
-			throw new Error(`Codex image generation request failed (${response.status}): ${errorText}`);
-		}
 
-		return parseCodexSse(response, signal);
-	}
+			if (!response.ok) {
+				const failure = await httpFailure(response, signal);
+				if (attempt <= MAX_RETRIES && failure.retry) {
+					const delay = retryDelayMs(attempt, response.headers.get("retry-after"));
+					await abortableDelay(delay, signal);
+					continue;
+				}
+				throw new Error(failure.message);
+			}
 
-	throw new Error("Codex image generation request failed after all retries.");
+			return parseCodexSse(response, signal, [token, accountId], onProgress);
+		}
+		throw new Error("Codex image generation request failed after all retries.");
+	});
 }
 
 // --- Extension entry point ---
@@ -558,26 +465,40 @@ export default function codexImageGen(pi: ExtensionAPI) {
 		name: "codex_generate_image",
 		label: "Codex Image",
 		description:
-			"Generate or edit an image with the OpenAI Codex ChatGPT backend built-in image_generation tool (gpt-image-2). Accepts up to five local or recent conversation images. Uses the existing openai-codex login; does not require OPENAI_API_KEY.",
-		promptSnippet: "Generate or edit bitmap images via the OpenAI Codex ChatGPT backend gpt-image-2 image_generation tool.",
+			"Generate or edit an image with the OpenAI Codex ChatGPT backend built-in image_generation tool. The backend selects the image model. Accepts up to five local or recent conversation images (20 MiB each, 50 MiB total). Uses the existing openai-codex login; does not require OPENAI_API_KEY. Network deadline: 5 minutes; output image limit: 32 MiB; backend text is limited to 4,000 characters.",
+		promptSnippet: "Generate or edit bitmap images via the OpenAI Codex ChatGPT backend image_generation tool.",
 		promptGuidelines: [
 			"Use codex_generate_image when the user asks to generate or edit a raster image with OpenAI/Codex image generation.",
 			"Do not use codex_generate_image without a clear image-generation request, because it consumes the user's Codex image quota.",
+			"The model parameter selects a Codex routing model, not an image model. Do not pass gpt-image-* IDs.",
+			"Output metadata is backend-reported, not independently verified. Check pixels for dimensions and transparency; do not infer a served model from appearance or a successful request.",
+			"Do not automatically repeat quota, connection, deadline, or incomplete-stream failures. The backend may already have consumed image quota.",
 		],
 		parameters: TOOL_PARAMS,
 		executionMode: "parallel", // #4: safe to run concurrently — no shared state, saves serialized per-path
 		async execute(toolCallId, params: ToolParams, signal, onUpdate, ctx) {
+			if (typeof params.prompt !== "string" || !params.prompt.trim() || params.prompt.length > MAX_PROMPT_CHARS) {
+				throw new Error("Image prompt must contain 1 to 32,000 characters.");
+			}
 			const outputFormat = params.outputFormat || "png";
+			if (!OUTPUT_FORMATS.includes(outputFormat)) throw new Error("Unsupported image output format.");
 			const projectTrusted = typeof ctx.isProjectTrusted === "function" && ctx.isProjectTrusted();
 			const config = loadConfig(ctx.cwd, projectTrusted); // #5: load once, pass to resolveSaveConfig
 			const requestedModel = params.model || config.model || DEFAULT_MODEL;
+			if (typeof requestedModel !== "string" || !requestedModel.trim() || requestedModel.length > 200) {
+				throw new Error("Codex routing model must contain 1 to 200 characters.");
+			}
+			if (requestedModel.startsWith("gpt-image-")) {
+				throw new Error("The model parameter selects a Codex routing model, not an image model. Subscription image-model selection is not verified.");
+			}
 			const model = ctx.modelRegistry.find(PROVIDER, requestedModel)?.id || requestedModel; // #6: removed dead FALLBACK_MODEL
+			const sessionId = ctx.sessionManager.getSessionId();
+			const saveConfig = resolveSaveConfig(params, ctx.cwd, sessionId, config);
 			const token = await ctx.modelRegistry.getApiKeyForProvider(PROVIDER);
 			if (!token) {
 				throw new Error(`Missing ${PROVIDER} credentials. Run /login and select ChatGPT Plus/Pro (Codex).`);
 			}
 			const accountId = extractChatGptAccountId(token);
-			const sessionId = ctx.sessionManager.getSessionId();
 			const messages: unknown[] = [];
 			for (const entry of ctx.sessionManager.getBranch()) {
 				if (entry.type === "message") messages.push(entry.message);
@@ -586,18 +507,24 @@ export default function codexImageGen(pi: ExtensionAPI) {
 			const inputImages = await resolveInputImages(params, ctx.cwd, messages);
 
 			onUpdate?.({
-				content: [{ type: "text", text: `Requesting gpt-image-2 ${inputImages.length > 0 ? "edit" : "generation"} through ${PROVIDER}/${model}...` }],
+				content: [{ type: "text", text: `Requesting image ${inputImages.length > 0 ? "edit" : "generation"} through ${PROVIDER}/${model}...` }],
 				details: { provider: PROVIDER, model, outputFormat, inputImageCount: inputImages.length },
 			});
 
-			const parsed = await requestImage(params, token, accountId, model, outputFormat, sessionId, inputImages, signal);
+			const started = Date.now();
+			const parsed = await requestImage(params, token, accountId, model, outputFormat, sessionId, inputImages, signal, (stage) => {
+				onUpdate?.({
+					content: [{ type: "text", text: `Codex image stage: ${stage}.` }],
+					details: { provider: PROVIDER, model, stage },
+				});
+			});
 			if (!parsed.image) {
 				const text = parsed.text.join("").trim();
 				throw new Error(text ? `Codex did not return an image. Response text: ${text}` : "Codex did not return an image.");
 			}
 
 			const imageBytes = decodeImageData(parsed.image.result, outputFormat);
-			const saveConfig = resolveSaveConfig(params, ctx.cwd, sessionId, config);
+			const reportedImage = parsed.image.reported;
 			let savedPath: string | undefined;
 			let attemptedPath: string | undefined;
 			let saveWarning: string | undefined;
@@ -615,8 +542,11 @@ export default function codexImageGen(pi: ExtensionAPI) {
 			}
 
 			const summary = [
-				`Generated image via ${PROVIDER}/${model} using backend gpt-image-2.`,
+				`Generated image via ${PROVIDER}/${model} using the backend-selected image model.`,
 				`Status: ${parsed.image.status}.`,
+				reportedImage.size ? `Backend-reported size: ${reportedImage.size}.` : undefined,
+				reportedImage.quality ? `Backend-reported quality: ${reportedImage.quality}.` : undefined,
+				reportedImage.background ? `Backend-reported background: ${reportedImage.background}.` : undefined,
 				parsed.image.revisedPrompt ? `Revised prompt: ${parsed.image.revisedPrompt}` : undefined,
 				savedPath ? `Saved image to: ${savedPath}` : "Image was not saved to disk.",
 				saveWarning ? `Warning: ${saveWarning}` : undefined,
@@ -632,7 +562,11 @@ export default function codexImageGen(pi: ExtensionAPI) {
 				details: {
 					provider: PROVIDER,
 					model,
-					backendImageModel: "gpt-image-2",
+					backendImageModel: reportedImage.model ?? "unknown",
+					reportedImage,
+					transport: "codex-responses",
+					generationDurationMs: Date.now() - started,
+					byteCount: imageBytes.length,
 					outputFormat,
 					saveMode: saveConfig.mode,
 					savedPath,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-codex-image-gen",
-  "version": "0.1.12",
-  "description": "Image generation for Pi using the ChatGPT Images 2.0 model.",
+  "version": "0.1.13",
+  "description": "Image generation and editing for Pi using your ChatGPT Codex login.",
   "type": "module",
   "license": "Apache-2.0",
   "author": "Jose Mocito",
@@ -58,16 +58,19 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.80.0",
-    "@earendil-works/pi-coding-agent": "^0.80.0",
-    "typebox": "^1.3.4",
-    "@types/node": "^26.1.0",
-    "typescript": "^6.0.3"
+    "@earendil-works/pi-ai": "^0.85.1",
+    "@earendil-works/pi-coding-agent": "^0.85.1",
+    "@types/node": "^26.2.0",
+    "typebox": "^1.3.10",
+    "typescript": "^7.0.2"
   },
   "publishConfig": {
     "access": "public"
   },
   "engines": {
     "node": ">=20.6.0"
+  },
+  "dependencies": {
+    "@mocito/install-telemetry": "0.1.1"
   }
 }

package/skills/imagegen/SKILL.md

@@ -16,7 +16,7 @@ Generates or edits images for the current project (for example website assets, g
 This skill has exactly two top-level modes:
 
 - **Default Pi tool mode (preferred):** Pi `codex_generate_image` tool for new image generation, edits using up to five local or recent conversation images, reference variants, and simple transparent-image requests. Does not require `OPENAI_API_KEY`.
-- **Fallback CLI mode:** `scripts/image_gen.py` CLI. Use when the user explicitly asks for the CLI/API/model path, or after the user explicitly confirms a true model-native transparency fallback with `gpt-image-1.5`. Requires `OPENAI_API_KEY`.
+- **Fallback CLI mode:** `scripts/image_gen.py` CLI. Use when the user explicitly asks for the CLI/API/model path, or after the user explicitly confirms a native transparency API fallback. Requires `OPENAI_API_KEY` and separate API billing.
 
 Within CLI fallback, the CLI exposes three subcommands:
 
@@ -26,11 +26,13 @@ Within CLI fallback, the CLI exposes three subcommands:
 
 Rules:
 - Use the Pi `codex_generate_image` tool by default for new image generation requests.
+- The tool's `model` parameter selects a Codex routing model, not Flare or Sunburst. Do not claim a specific served image model unless the response reports it. Read `details.reportedImage` for backend-reported output settings, then inspect the actual image; prompt requests for quality, dimensions, or transparency are not guarantees.
+- Do not automatically repeat quota, connection, timeout, or incomplete-stream failures. The remote generation may already have consumed quota.
 - Use `referencedImagePaths` for edits when every target has a local path. Use `numLastImagesToInclude` only when a target is available solely in recent conversation history. Never provide both selectors. Masks and advanced CLI-only controls still require confirmed CLI fallback.
 - Do not switch to CLI fallback for ordinary generation quality, size, or output file-path control.
 - If the user explicitly asks for a transparent image/background, stay on Pi `codex_generate_image` first: prompt for a flat removable chroma-key background, then remove it locally with the installed helper at `scripts/remove_chroma_key.py`.
 - Never silently switch from Pi `codex_generate_image` or CLI `gpt-image-2` to CLI `gpt-image-1.5`. Treat this as a model/path downgrade and ask the user before doing it, unless the user has already explicitly requested `gpt-image-1.5`, `scripts/image_gen.py`, or CLI fallback.
-- If a transparent request appears too complex for clean chroma-key removal, asks for true/native transparency, or local removal fails validation, explain that true transparency requires CLI `gpt-image-1.5 --background transparent --output-format png` because `gpt-image-2` does not support `background=transparent`, then ask whether to proceed. Run the CLI fallback only after the user confirms.
+- If a transparent request appears too complex for clean chroma-key removal, asks for true/native transparency, or local removal fails validation, offer CLI `gpt-image-2 --background transparent --output-format png` (native transparency preview). Run the CLI fallback only after the user confirms.
 - The word `batch` by itself does not mean CLI fallback. If the user asks for many assets or says to batch-generate assets without explicitly asking for CLI/API/model controls, stay on the Pi tool path and issue one Pi tool call per requested asset or variant.
 - If the Pi tool fails or is unavailable, tell the user the CLI fallback exists and that it requires `OPENAI_API_KEY`. Proceed only if the user explicitly asks for that fallback.
 - If the user explicitly asks for CLI mode, use the bundled `scripts/image_gen.py` workflow. Do not create one-off SDK runners.
@@ -39,7 +41,7 @@ Rules:
 Pi tool save-path policy:
 - In Pi tool mode, generated images are saved under Pi's agent directory by default: `<pi-agent-dir>/generated-images/<pi-session-id>/<image-call-id>.*`. The default Pi agent directory is `~/.pi/agent`, but it can be overridden with `PI_CODING_AGENT_DIR`; use Pi's configured agent directory, not a hardcoded home path.
 - Do not describe or rely on OS temp as the default Pi tool destination.
-- Do not describe or rely on a destination-path argument (if any) on the Pi `codex_generate_image` tool. If a specific location is needed, generate first and then copy the selected output from `<pi-agent-dir>/generated-images/<pi-session-id>/<image-call-id>.*`.
+- Use the tool's `save` and `saveDir` controls to choose a save directory. Custom mode appends a session directory; it does not accept an exact output filename. If an exact asset path is needed, copy the generated image there and leave the original in place.
 - Save-path precedence in Pi tool mode:
   1. If the user names a destination, copy the selected output there and leave the original in place.
   2. If the image is meant for the current project, copy the final selected image into the workspace before finishing and leave the original in place.
@@ -113,7 +115,7 @@ Assume the user wants a new image unless they clearly ask to change an existing
    - If the user's prompt is already specific and detailed, normalize it into a clear spec without adding creative requirements.
    - If the user's prompt is generic, add tasteful augmentation only when it materially improves output quality.
 10. Use the Pi `codex_generate_image` tool by default for generation and supported existing-image edits. Ask for CLI fallback confirmation only when the request requires unsupported controls such as masks.
-11. For transparent-output requests, follow the transparent image guidance below: generate with Pi `codex_generate_image` on a flat chroma-key background, copy the selected output into the workspace or `tmp/imagegen/`, run the installed `scripts/remove_chroma_key.py` helper, and validate the alpha result before using it. If this path looks unsuitable or fails, ask before switching to CLI `gpt-image-1.5`.
+11. For transparent-output requests, follow the transparent image guidance below: generate with Pi `codex_generate_image` on a flat chroma-key background, copy the selected output into the workspace or `tmp/imagegen/`, run the installed `scripts/remove_chroma_key.py` helper, and validate the alpha result before using it. If this path looks unsuitable or fails, ask before switching to the API CLI.
 12. Inspect outputs and validate: subject, style, composition, text accuracy, and invariants/avoid items.
 13. Iterate with a single targeted change, then re-check.
 14. For preview-only work, render the image inline; the underlying file may remain at the default `<pi-agent-dir>/generated-images/<pi-session-id>/<image-call-id>.*` path.
@@ -154,12 +156,12 @@ Do not use #00ff00 anywhere in the subject.
 No cast shadow, no contact shadow, no reflection, no watermark, and no text unless explicitly requested.
 ```
 
-Do not automatically use CLI `gpt-image-1.5 --background transparent --output-format png` instead of chroma keying. Ask the user first when the user asks for true/native transparency, when local removal fails validation, or when the requested image is complex: hair, fur, feathers, smoke, glass, liquids, translucent materials, reflective objects, soft shadows, realistic product grounding, or subject colors that conflict with all practical key colors.
+Do not automatically use CLI `gpt-image-2 --background transparent --output-format png` instead of chroma keying. Ask the user first when the user asks for true/native transparency, when local removal fails validation, or when the requested image is complex: hair, fur, feathers, smoke, glass, liquids, translucent materials, reflective objects, soft shadows, realistic product grounding, or subject colors that conflict with all practical key colors.
 
 Use a concise confirmation like:
 
 ```text
-This likely needs true native transparency. The default Pi tool path uses a chroma-key background plus local removal, but true transparency requires the CLI fallback with gpt-image-1.5 because gpt-image-2 does not support background=transparent. It also requires OPENAI_API_KEY. Should I proceed with that CLI fallback?
+This likely needs native transparency. The Pi tool uses chroma-key removal. The API CLI supports native transparency in preview with gpt-image-2. It requires OPENAI_API_KEY and separate API billing. Should I use that fallback?
 ```
 
 ## Prompt augmentation
@@ -279,7 +281,7 @@ Constraints: change only the background; keep the product and its edges unchange
 - If the prompt is generic, add only the extra detail that will materially help.
 - If the prompt is already detailed, normalize it instead of expanding it.
 - For CLI fallback only, see `references/cli.md` and `references/image-api.md` for model, `quality`, `input_fidelity`, masks, output format, and output-path guidance.
-- For transparent images, use the built-in-first chroma-key workflow unless the request is complex enough to need true CLI transparency; ask before switching to CLI `gpt-image-1.5`.
+- For transparent images, use the built-in-first chroma-key workflow unless the request needs native CLI transparency; ask before switching to the API CLI.
 
 More principles shared by both modes: `references/prompting.md`.
 Copy/paste specs shared by both modes: `references/sample-prompts.md`.
@@ -291,14 +293,14 @@ Asset-type templates (website assets, game assets, wireframes, logo) are consoli
 
 The fallback CLI defaults to `gpt-image-2`.
 
-- Use `gpt-image-2` for new CLI/API workflows unless the request needs true model-native transparent output.
-- If a transparent request may need CLI fallback, ask before using `gpt-image-1.5` unless the user already explicitly requested `gpt-image-1.5`, `scripts/image_gen.py`, or CLI fallback. Explain that the built-in chroma-key path is the default, but true transparency requires `gpt-image-1.5` because `gpt-image-2` does not support `background=transparent`.
+- Keep `gpt-image-2` as the CLI default. For explicit 2.5 requests, use `gpt-image-2.5-flare` for fast generation or `gpt-image-2.5-sunburst` for editing precision. Both also accept `xhigh` and `max` quality and their `2026-09-08` snapshots. Both support the flexible size constraints below; sizes above `2560x1440` are experimental. Leave 2.5 `input_fidelity` unset; support for that control is not verified.
+- Native transparency is available in preview with CLI `gpt-image-2 --background transparent --output-format png` (or `webp`). Ask before switching from Pi to this separately billed API path.
 - `gpt-image-2` always uses high fidelity for image inputs; do not set `input_fidelity` with this model.
 - `gpt-image-2` supports `quality` values `low`, `medium`, `high`, and `auto`.
 - Use `quality low` for fast drafts, thumbnails, and quick iterations. Use `medium`, `high`, or `auto` for final assets, dense text, diagrams, identity-sensitive edits, or high-resolution outputs.
 - Square images are typically fastest to generate. Use `1024x1024` for fast square drafts.
 - If the user asks for 4K-style output, use `3840x2160` for landscape or `2160x3840` for portrait.
-- `gpt-image-2` size may be `auto` or `WIDTHxHEIGHT` if all constraints hold: max edge `<= 3840px`, both edges multiples of `16px`, long-to-short ratio `<= 3:1`, total pixels between `655,360` and `8,294,400`.
+- GPT Image 2 and 2.5 API size may be `auto` or `WIDTHxHEIGHT` if all constraints hold: max edge `<= 3840px`, both edges multiples of `16px`, long-to-short ratio `<= 3:1`, total pixels between `655,360` and `8,294,400`.
 
 Popular `gpt-image-2` sizes:
 - `1024x1024` square