pi-codex-image-gen 0.1.11 → 0.1.12

package/CHANGELOG.md

@@ -1,11 +1,24 @@
 # Changelog
 
+## 0.1.12 - 2026-07-17
+
 All notable changes to this project will be documented in this file.
 
 This project follows the spirit of [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and uses semantic versioning for releases.
 
 ## [Unreleased]
 
+### Added
+
+- Add native edits using up to five local or recent conversation images.
+- Honor bounded `Retry-After` delays and make retry backoff abort-aware.
+
+### Fixed
+
+- Strictly validate base64 data and output-format signatures before returning or saving images.
+- Preserve valid inline images and report a warning when disk persistence fails.
+- Keep original generated artifacts when copying selected outputs elsewhere by default.
+
 ## [0.1.11] - 2026-07-01
 
 ### Changed

package/README.md

@@ -1,6 +1,6 @@
 # pi-codex-image-gen
 
-Image generation for [Pi](https://pi.dev) using the ChatGPT Images 2.0 model via the OpenAI Codex Responses backend.
+Image generation and editing for [Pi](https://pi.dev) using the ChatGPT Images 2.0 model via the OpenAI Codex Responses backend.
 
 ## Install
 
@@ -34,7 +34,7 @@ In a Pi session:
 > Generate a pixel-art sword icon, 32×32, with a blue blade and gold hilt
 ```
 
-The agent will invoke `codex_generate_image` with your prompt, stream the response from the Codex backend, and save the resulting image to disk. The `model` parameter controls the Codex routing model; image generation is always performed by **gpt-image-2** on the backend.
+The agent will invoke `codex_generate_image` with your prompt, optionally include up to five local or recent conversation images for editing, stream the response from the Codex backend, and save the resulting image to disk. The `model` parameter controls the Codex routing model; image generation is always performed by **gpt-image-2** on the backend.
 
 ## Authentication
 
@@ -55,7 +55,7 @@ Create a JSON config file at one (or both) of these locations:
 | Global  | `~/.pi/agent/extensions/codex-image-gen.json`           |
 | Project | `<project-root>/.pi/extensions/codex-image-gen.json`    |
 
-Project config overrides global config. Example:
+Project config overrides global config only when project trust is active. If project trust is declined or otherwise inactive, project config is ignored and global config still applies. Example:
 
 ```json
 {
@@ -89,7 +89,7 @@ Project config overrides global config. Example:
 | `none`    | Image is returned inline but not written to disk.                |
 | `project` | Saves to `<project>/.pi/generated-images/<session-id>/`.         |
 | `global`  | Saves to `~/.pi/agent/generated-images/<session-id>/`.           |
-| `custom`  | Saves to a user-specified directory (requires `saveDir` or env). |
+| `custom`  | Saves to a user-specified directory (requires `saveDir` or env). `~` and `~/...` expand to the current user's home directory. |
 
 ## Tool parameters
 
@@ -100,15 +100,18 @@ Project config overrides global config. Example:
 | `outputFormat` | string | —        | `png` (default), `jpeg`, or `webp`.                                |
 | `save`         | string | —        | Override save mode for this call.                                  |
 | `saveDir`      | string | —        | Directory when `save=custom`. Relative paths resolve under CWD.    |
+| `referencedImagePaths` | string[] | — | Up to five local images to edit. Relative paths resolve under CWD. |
+| `numLastImagesToInclude` | integer | — | Include the most recent one to five conversation images for editing. Mutually exclusive with `referencedImagePaths`. |
 
 ## How it works
 
 1. Resolves auth via Pi's `openai-codex` provider (ChatGPT session token).
 2. Sends a Codex Responses API request to the routing model (default `gpt-5.5`) with the `image_generation` tool enabled.
-3. The backend invokes **gpt-image-2** to generate the image.
-4. Parses the SSE stream for `response.output_item.done` events containing the base64 image.
-5. Saves the image to disk according to the active save mode.
-6. Returns the image data inline plus metadata (model, format, path, revised prompt, usage).
+3. For edits, attaches the selected local or conversation images to the request.
+4. The backend invokes **gpt-image-2** to generate or edit the image.
+5. Parses the SSE stream and strictly validates the returned base64 and image format.
+6. Saves the image according to the active save mode; persistence failures produce a warning without discarding a valid inline image.
+7. Returns the image data inline plus metadata (model, format, path, revised prompt, usage).
 
 ## Troubleshooting
 

package/extensions/index.ts

@@ -7,7 +7,8 @@
  */
 
 import { readFileSync } from "node:fs";
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, readFile, 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";
@@ -23,6 +24,8 @@ const DEFAULT_SAVE_MODE = "global";
 const OPENAI_BETA_HEADER = "responses=experimental";
 const MAX_RETRIES = 3;
 const BASE_DELAY_MS = 1000;
+const MAX_RETRY_DELAY_MS = 30_000;
+const MAX_EDIT_IMAGES = 5;
 
 const SAVE_MODES = ["none", "project", "global", "custom"] as const;
 type SaveMode = (typeof SAVE_MODES)[number];
@@ -37,9 +40,50 @@ function isRetryableStatus(status: number, errorText: string): boolean {
 	return /rate.?limit|overloaded|service.?unavailable|upstream.?connect|connection.?refused/i.test(errorText);
 }
 
-function backoffMs(attempt: number): number {
-	const jitter = 0.9 + Math.random() * 0.2; // matches codex-rs jitter range
-	return BASE_DELAY_MS * 2 ** (attempt - 1) * jitter;
+export function parseRetryAfter(value: string | null, nowMs = Date.now()): number | undefined {
+	if (!value) return undefined;
+	const trimmed = value.trim();
+	if (/^\d+(?:\.\d+)?$/.test(trimmed)) {
+		const milliseconds = Number(trimmed) * 1000;
+		return Number.isFinite(milliseconds) ? Math.min(milliseconds, MAX_RETRY_DELAY_MS) : undefined;
+	}
+	const dateMs = Date.parse(trimmed);
+	if (!Number.isFinite(dateMs) || dateMs <= nowMs) return undefined;
+	return Math.min(dateMs - nowMs, MAX_RETRY_DELAY_MS);
+}
+
+export function retryDelayMs(
+	attempt: number,
+	retryAfter: string | null,
+	random = Math.random,
+	nowMs = Date.now(),
+): number {
+	const serverDelay = parseRetryAfter(retryAfter, nowMs);
+	if (serverDelay !== undefined) {
+		return Math.floor(Math.min(serverDelay * (1 + random() * 0.1), MAX_RETRY_DELAY_MS));
+	}
+	const exponential = Math.min(BASE_DELAY_MS * 2 ** (attempt - 1), MAX_RETRY_DELAY_MS);
+	return Math.floor(exponential * (0.9 + random() * 0.2));
+}
+
+export function abortableDelay(milliseconds: number, signal?: AbortSignal): Promise<void> {
+	if (signal?.aborted) return Promise.reject(new Error("Image generation was aborted."));
+	return new Promise<void>((resolve, reject) => {
+		const timer = setTimeout(finish, milliseconds);
+		function cleanup() {
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", abort);
+		}
+		function finish() {
+			cleanup();
+			resolve();
+		}
+		function abort() {
+			cleanup();
+			reject(new Error("Image generation was aborted."));
+		}
+		signal?.addEventListener("abort", abort, { once: true });
+	});
 }
 
 // --- Tool parameter schema ---
@@ -56,6 +100,19 @@ const TOOL_PARAMS = Type.Object({
 			description: "Directory to save the image when save=custom. Relative paths resolve under the current workspace.",
 		}),
 	),
+	referencedImagePaths: Type.Optional(
+		Type.Array(Type.String(), {
+			maxItems: MAX_EDIT_IMAGES,
+			description: "Up to five local image paths to edit. Relative paths resolve under the current workspace.",
+		}),
+	),
+	numLastImagesToInclude: Type.Optional(
+		Type.Integer({
+			minimum: 1,
+			maximum: MAX_EDIT_IMAGES,
+			description: "Use the most recent one to five images from the current conversation as edit inputs.",
+		}),
+	),
 });
 
 type ToolParams = Static<typeof TOOL_PARAMS>;
@@ -87,6 +144,11 @@ interface ParsedCodexResponse {
 	usage?: unknown;
 }
 
+interface InputImage {
+	data: string;
+	mimeType: string;
+}
+
 // --- #11: Typed SSE event discriminated union ---
 
 type CodexSseEvent =
@@ -143,15 +205,18 @@ function readConfigFile(path: string): ExtensionConfig {
 	}
 }
 
-function loadConfig(cwd: string): ExtensionConfig {
-	const globalConfig = readConfigFile(join(getAgentDir(), "extensions", "codex-image-gen.json"));
+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"));
 	return { ...globalConfig, ...projectConfig };
 }
 
 // --- Path helpers ---
 
-function resolveUnderCwd(cwd: string, path: string): string {
+export function resolveUnderCwd(cwd: string, path: string, homeDir = homedir()): string {
+	if (path === "~") return homeDir;
+	if (path.startsWith("~/")) return resolve(homeDir, path.slice(2));
 	return isAbsolute(path) ? path : resolve(cwd, path);
 }
 
@@ -199,22 +264,115 @@ function mimeForFormat(outputFormat: OutputFormat): string {
 	return outputFormat === "jpeg" ? "image/jpeg" : `image/${outputFormat}`;
 }
 
-async function saveImage(base64Data: string, outputFormat: OutputFormat, outputDir: string, imageCallId: string): Promise<string> {
+function imagePath(outputFormat: OutputFormat, outputDir: string, imageCallId: string): string {
 	const filename = `${sanitizePathPart(imageCallId, "image_generation")}.${extensionForFormat(outputFormat)}`;
-	const filePath = join(outputDir, filename);
+	return join(outputDir, filename);
+}
+
+export function decodeImageData(base64Data: string, outputFormat: OutputFormat): Buffer {
+	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)) {
+		throw new Error("Codex returned invalid base64 image data.");
+	}
+	const bytes = Buffer.from(value, "base64");
+	if (bytes.length === 0 || bytes.toString("base64") !== value) {
+		throw new Error("Codex returned invalid base64 image data.");
+	}
+	const validSignature =
+		(outputFormat === "png" && bytes.length >= 8 && bytes.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) ||
+		(outputFormat === "jpeg" && bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) ||
+		(outputFormat === "webp" && bytes.length >= 12 && bytes.toString("ascii", 0, 4) === "RIFF" && bytes.toString("ascii", 8, 12) === "WEBP");
+	if (!validSignature) throw new Error(`Codex returned image data that does not match ${outputFormat}.`);
+	return bytes;
+}
+
+async function saveImage(
+	bytes: Buffer,
+	outputFormat: OutputFormat,
+	outputDir: string,
+	imageCallId: string,
+): Promise<string> {
+	const filePath = imagePath(outputFormat, outputDir, imageCallId);
 	await withFileMutationQueue(filePath, async () => {
 		await mkdir(outputDir, { recursive: true });
-		await writeFile(filePath, Buffer.from(base64Data, "base64"));
+		await writeFile(filePath, bytes);
 	});
 	return filePath;
 }
 
+export function selectRecentImages(messages: unknown[], count: number): InputImage[] {
+	const images: InputImage[] = [];
+	for (let index = messages.length - 1; index >= 0 && images.length < count; index--) {
+		const message = messages[index] as { content?: unknown };
+		if (!Array.isArray(message?.content)) continue;
+		for (let contentIndex = message.content.length - 1; contentIndex >= 0 && images.length < count; contentIndex--) {
+			const block = message.content[contentIndex] as { type?: unknown; data?: unknown; mimeType?: unknown };
+			if (block?.type === "image" && typeof block.data === "string" && typeof block.mimeType === "string") {
+				images.push({ data: block.data, mimeType: block.mimeType });
+			}
+		}
+	}
+	return images.reverse();
+}
+
+function mimeFromBytes(bytes: Buffer, path: string): string {
+	if (bytes.length >= 8 && bytes.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) return "image/png";
+	if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return "image/jpeg";
+	if (bytes.length >= 12 && bytes.toString("ascii", 0, 4) === "RIFF" && bytes.toString("ascii", 8, 12) === "WEBP") return "image/webp";
+	throw new Error(`Referenced image is unavailable or unsupported: ${path}`);
+}
+
+export async function resolveInputImages(
+	params: ToolParams,
+	cwd: string,
+	messages: unknown[],
+): Promise<InputImage[]> {
+	const paths = params.referencedImagePaths ?? [];
+	if (paths.length > 0 && params.numLastImagesToInclude !== undefined) {
+		throw new Error("Provide only one of referencedImagePaths or numLastImagesToInclude.");
+	}
+	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) };
+			}),
+		);
+	}
+	if (params.numLastImagesToInclude !== undefined) {
+		const count = params.numLastImagesToInclude;
+		if (!Number.isInteger(count) || count < 1 || count > MAX_EDIT_IMAGES) {
+			throw new Error(`numLastImagesToInclude must be between 1 and ${MAX_EDIT_IMAGES}.`);
+		}
+		const images = selectRecentImages(messages, count);
+		if (images.length !== count) {
+			throw new Error(`Requested the last ${count} conversation images, but only ${images.length} were available.`);
+		}
+		return images;
+	}
+	return [];
+}
+
 // --- Request building ---
 // #2: prompt_cache_key set to sessionId
 // #7: parallel_tool_calls: false
 // #14: include removed (not needed without reasoning)
 
-function buildRequestBody(params: ToolParams, model: string, outputFormat: OutputFormat, sessionId: string) {
+export function buildRequestBody(
+	params: ToolParams,
+	model: string,
+	outputFormat: OutputFormat,
+	sessionId: string,
+	inputImages: InputImage[] = [],
+) {
 	return {
 		model,
 		store: false,
@@ -225,7 +383,13 @@ function buildRequestBody(params: ToolParams, model: string, outputFormat: Outpu
 		input: [
 			{
 				role: "user",
-				content: [{ type: "input_text", text: params.prompt }],
+				content: [
+					{ type: "input_text", text: params.prompt },
+					...inputImages.map((image) => ({
+						type: "input_image",
+						image_url: `data:${image.mimeType};base64,${image.data}`,
+					})),
+				],
 			},
 		],
 		tools: [{ type: "image_generation", output_format: outputFormat }],
@@ -346,9 +510,10 @@ async function requestImage(
 	model: string,
 	outputFormat: OutputFormat,
 	sessionId: string,
+	inputImages: InputImage[],
 	signal?: AbortSignal,
 ): Promise<ParsedCodexResponse> {
-	const body = JSON.stringify(buildRequestBody(params, model, outputFormat, sessionId));
+	const body = JSON.stringify(buildRequestBody(params, model, outputFormat, sessionId, inputImages));
 	const headers: Record<string, string> = {
 		Authorization: `Bearer ${token}`,
 		"chatgpt-account-id": accountId,
@@ -371,8 +536,8 @@ async function requestImage(
 		if (!response.ok) {
 			const errorText = await response.text();
 			if (attempt <= MAX_RETRIES && isRetryableStatus(response.status, errorText)) {
-				const delay = backoffMs(attempt);
-				await new Promise<void>((resolve) => setTimeout(resolve, delay));
+				const delay = retryDelayMs(attempt, response.headers.get("retry-after"));
+				await abortableDelay(delay, signal);
 				continue;
 			}
 			throw new Error(`Codex image generation request failed (${response.status}): ${errorText}`);
@@ -393,17 +558,18 @@ export default function codexImageGen(pi: ExtensionAPI) {
 		name: "codex_generate_image",
 		label: "Codex Image",
 		description:
-			"Generate an image with the OpenAI Codex ChatGPT backend built-in image_generation tool (gpt-image-2). Uses the existing openai-codex login; does not require OPENAI_API_KEY.",
-		promptSnippet: "Generate 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 (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.",
 		promptGuidelines: [
-			"Use codex_generate_image when the user asks to generate a raster image, illustration, photo, sprite, icon draft, banner, or other bitmap asset with OpenAI/Codex image generation.",
+			"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.",
 		],
 		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) {
 			const outputFormat = params.outputFormat || "png";
-			const config = loadConfig(ctx.cwd); // #5: load once, pass to resolveSaveConfig
+			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;
 			const model = ctx.modelRegistry.find(PROVIDER, requestedModel)?.id || requestedModel; // #6: removed dead FALLBACK_MODEL
 			const token = await ctx.modelRegistry.getApiKeyForProvider(PROVIDER);
@@ -412,32 +578,40 @@ export default function codexImageGen(pi: ExtensionAPI) {
 			}
 			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);
+				if (entry.type === "custom_message") messages.push(entry);
+			}
+			const inputImages = await resolveInputImages(params, ctx.cwd, messages);
 
 			onUpdate?.({
-				content: [{ type: "text", text: `Requesting gpt-image-2 generation through ${PROVIDER}/${model}...` }],
-				details: { provider: PROVIDER, model, outputFormat },
+				content: [{ type: "text", text: `Requesting gpt-image-2 ${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, signal);
+			const parsed = await requestImage(params, token, accountId, model, outputFormat, sessionId, inputImages, signal);
 			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);
 			let savedPath: string | undefined;
+			let attemptedPath: string | undefined;
+			let saveWarning: string | undefined;
 			if (saveConfig.mode !== "none" && saveConfig.outputDir) {
-				savedPath = await saveImage(parsed.image.result, outputFormat, saveConfig.outputDir, parsed.image.id || toolCallId);
-				// #12: second onUpdate after save with path + byte count
-				onUpdate?.({
-					content: [{ type: "text", text: `Image saved to ${savedPath}.` }],
-					details: {
-						provider: PROVIDER,
-						model,
-						savedPath,
-						byteCount: Buffer.byteLength(parsed.image.result, "base64"),
-					},
-				});
+				attemptedPath = imagePath(outputFormat, saveConfig.outputDir, parsed.image.id || toolCallId);
+				try {
+					savedPath = await saveImage(imageBytes, outputFormat, saveConfig.outputDir, parsed.image.id || toolCallId);
+					onUpdate?.({
+						content: [{ type: "text", text: `Image saved to ${savedPath}.` }],
+						details: { provider: PROVIDER, model, savedPath, byteCount: imageBytes.length },
+					});
+				} catch (error) {
+					saveWarning = `Image generation succeeded, but the image could not be saved to disk: ${error instanceof Error ? error.message : String(error)}`;
+				}
 			}
 
 			const summary = [
@@ -445,6 +619,7 @@ export default function codexImageGen(pi: ExtensionAPI) {
 				`Status: ${parsed.image.status}.`,
 				parsed.image.revisedPrompt ? `Revised prompt: ${parsed.image.revisedPrompt}` : undefined,
 				savedPath ? `Saved image to: ${savedPath}` : "Image was not saved to disk.",
+				saveWarning ? `Warning: ${saveWarning}` : undefined,
 			]
 				.filter(Boolean)
 				.join(" ");
@@ -461,6 +636,9 @@ export default function codexImageGen(pi: ExtensionAPI) {
 					outputFormat,
 					saveMode: saveConfig.mode,
 					savedPath,
+					attemptedPath,
+					saveWarning,
+					inputImageCount: inputImages.length,
 					responseId: parsed.responseId,
 					imageGenerationId: parsed.image.id,
 					revisedPrompt: parsed.image.revisedPrompt,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-codex-image-gen",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "Image generation for Pi using the ChatGPT Images 2.0 model.",
   "type": "module",
   "license": "Apache-2.0",
@@ -41,6 +41,7 @@
   "scripts": {
     "check": "tsc --noEmit",
     "typecheck": "tsc --noEmit",
+    "test": "rm -rf .test-dist && tsc --noEmit false --outDir .test-dist && node --test tests/*.test.mjs; status=$?; rm -rf .test-dist; exit $status",
     "pack:dry-run": "npm pack --dry-run"
   },
   "pi": {
@@ -59,8 +60,8 @@
   "devDependencies": {
     "@earendil-works/pi-ai": "^0.80.0",
     "@earendil-works/pi-coding-agent": "^0.80.0",
-    "typebox": "^1.2.10",
-    "@types/node": "^25.9.3",
+    "typebox": "^1.3.4",
+    "@types/node": "^26.1.0",
     "typescript": "^6.0.3"
   },
   "publishConfig": {

package/skills/imagegen/SKILL.md

@@ -7,7 +7,7 @@ description: "Generate or edit raster images when the task benefits from AI-crea
 
 > Adapted from OpenAI Codex's `imagegen` skill for Pi.
 > Original source: https://github.com/openai/codex/tree/main/codex-rs/skills/src/assets/samples/imagegen
-> Required Pi modifications: use Pi's `codex_generate_image` tool name, Pi artifact paths, and the bundled helper path; direct image editing remains CLI fallback unless the Pi tool grows edit support.
+> Required Pi modifications: use Pi's `codex_generate_image` tool name, Pi artifact paths, and the bundled helper path.
 
 Generates or edits images for the current project (for example website assets, game assets, UI mockups, product mockups, wireframes, logo design, photorealistic images, or infographics).
 
@@ -15,7 +15,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 normal image generation, editing, and simple transparent-image requests. Does not require `OPENAI_API_KEY`.
+- **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`.
 
 Within CLI fallback, the CLI exposes three subcommands:
@@ -25,8 +25,9 @@ Within CLI fallback, the CLI exposes three subcommands:
 - `generate-batch`
 
 Rules:
-- Use the Pi `codex_generate_image` tool by default for normal image generation and editing requests.
-- Do not switch to CLI fallback for ordinary quality, size, or file-path control.
+- Use the Pi `codex_generate_image` tool by default for new image generation requests.
+- 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.
@@ -38,12 +39,13 @@ 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 move or copy the selected output from `<pi-agent-dir>/generated-images/<pi-session-id>/<image-call-id>.*`.
+- 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>.*`.
 - Save-path precedence in Pi tool mode:
-  1. If the user names a destination, move or copy the selected output there.
-  2. If the image is meant for the current project, move or copy the final selected image into the workspace before finishing.
+  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.
   3. If the image is only for preview or brainstorming, render it inline; the underlying file can remain at the default `<pi-agent-dir>/generated-images/<pi-session-id>/*` path.
 - Never leave a project-referenced asset only at the default `<pi-agent-dir>/generated-images/<pi-session-id>/*` path.
+- Move or delete a Pi-generated original only when the user explicitly requests it.
 - Do not overwrite an existing asset unless the user explicitly asked for replacement; otherwise create a sibling versioned filename such as `hero-v2.png` or `item-icon-edited.png`.
 
 Shared prompt guidance for both modes lives in `references/prompting.md` and `references/sample-prompts.md`.
@@ -82,9 +84,10 @@ Intent:
 - If the user provides no images, treat the request as **generate**.
 
 Pi edit semantics:
-- The current Pi `codex_generate_image` tool is for new image generation. Do not promise arbitrary filesystem-path editing through the Pi tool.
-- If the user wants to edit an existing image, use the explicit CLI fallback only when the user asks for it or confirms it.
-- If a local file needs direct file-path control, masks, or other explicit CLI-only parameters, use the explicit CLI fallback only after confirmation.
+- Use `referencedImagePaths` when all edit targets have readable local paths, with at most five paths.
+- Use `numLastImagesToInclude` for the smallest recent-conversation window containing all targets, from one to five images.
+- Never provide both image selectors. If neither can include every target, ask the user to attach or provide the missing image.
+- Use confirmed CLI fallback only for masks or other explicit CLI-only parameters.
 - For edits, preserve invariants aggressively and save non-destructively by default.
 
 Execution strategy:
@@ -95,7 +98,7 @@ Execution strategy:
 Assume the user wants a new image unless they clearly ask to change an existing one.
 
 ## Workflow
-1. Decide the top-level mode: Pi tool by default, including simple transparent-output requests; fallback CLI only if explicitly requested or after the user explicitly confirms a transparent-output fallback.
+1. Decide the top-level mode: Pi tool by default for generation, supported edits, and simple transparent-output requests; fallback CLI only if explicitly requested or after the user confirms an unsupported edit control or transparent-output fallback.
 2. Decide the intent: `generate` or `edit`.
 3. Decide whether the output is preview-only or meant to be consumed by the current project.
 4. Decide the execution strategy: single asset vs repeated Pi tool calls vs CLI `generate-batch`.
@@ -104,17 +107,17 @@ Assume the user wants a new image unless they clearly ask to change an existing
    - reference image
    - edit target
    - supporting insert/style/compositing input
-7. If the edit target is only on the local filesystem, use CLI fallback for direct edits only after the user asks for or confirms fallback mode.
+7. For local edit targets, pass up to five paths through `referencedImagePaths`. For pathless conversation images, use the smallest valid `numLastImagesToInclude`.
 8. If the user asked for a photo, illustration, sprite, product image, banner, or other explicitly raster-style asset, use `codex_generate_image` rather than substituting SVG/HTML/CSS placeholders. If the request is for an icon, logo, or UI graphic that should match existing repo-native SVG/vector/code assets, prefer editing those directly instead.
 9. Augment the prompt based on specificity:
    - 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.
+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`.
 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.
-15. For project-bound work, move or copy the selected artifact into the workspace and update any consuming code or references. Never leave a project-referenced asset only at the default `<pi-agent-dir>/generated-images/<pi-session-id>/<image-call-id>.*` path.
+15. For project-bound work, copy the selected artifact into the workspace, leave the original in place, and update any consuming code or references. Never leave a project-referenced asset only at the default `<pi-agent-dir>/generated-images/<pi-session-id>/<image-call-id>.*` path.
 16. For batches or multi-asset requests, persist every requested deliverable final in the workspace unless the user explicitly asked to keep outputs preview-only. Discarded variants do not need to be kept unless requested.
 17. If the user explicitly chooses or confirms the CLI fallback, then use the fallback-only docs for model, quality, size, `input_fidelity`, masks, output format, output paths, and network setup.
 18. Always report the final saved path(s) for any workspace-bound asset(s), plus the final prompt or prompt set and whether the Pi tool or fallback CLI mode was used.
@@ -126,7 +129,7 @@ Transparent-image requests still use Pi `codex_generate_image` first. Because th
 Default sequence:
 1. Use Pi `codex_generate_image` to generate the requested subject on a perfectly flat solid chroma-key background.
 2. Choose a key color that is unlikely to appear in the subject: default `#00ff00`, use `#ff00ff` for green subjects, and avoid `#0000ff` for blue subjects.
-3. After generation, move or copy the selected source image from `<pi-agent-dir>/generated-images/<pi-session-id>/<image-call-id>.*` into the workspace or `tmp/imagegen/`.
+3. After generation, copy the selected source image from `<pi-agent-dir>/generated-images/<pi-session-id>/<image-call-id>.*` into the workspace or `tmp/imagegen/` and leave the original in place.
 4. Run the bundled helper from this skill directory:
    ```bash
    python "scripts/remove_chroma_key.py" \