oira666_pi-image-generation 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 oira666
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1 @@
+pi install npm:oira666_pi-image-generation

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "oira666_pi-image-generation",
+  "version": "0.0.1",
+  "description": "Image generation and reference-image editing for pi.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gee666/pi-image-generation.git"
+  },
+  "keywords": ["pi-package", "pi-extension", "image-generation"],
+  "files": ["src", "resources", "README.md", "LICENSE"],
+  "pi": {
+    "extensions": ["./src/index.ts"],
+    "skills": []
+  },
+  "engines": { "node": ">=22" },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "dependencies": {
+    "pngjs": "^7.0.0"
+  },
+  "devDependencies": {
+    "@types/pngjs": "^6.0.5",
+    "@earendil-works/pi-coding-agent": "0.86.0",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.20.0",
+    "typebox": "^1.0.0",
+    "typescript": "^5.9.0"
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "tsx --test test/*.test.ts",
+    "prepublishOnly": "npm run check && npm test"
+  }
+}

package/resources/imagegen/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: imagegen
+description: Generate and edit raster images with image_gen, including photos, illustrations, textures, sprites, product shots, mockups, and consistent visual variants. Use reference images to preserve identity, style, composition, or objects across edits. Prefer native edits instead when extending existing SVG, vector, HTML, CSS, or canvas assets.
+---
+
+# Image generation
+
+Use `image_gen` for new raster artwork, image edits, and variations. The tool is available to the current pi model regardless of its provider. It uses the configured Codex subscription for the image request; do not launch another Codex agent, request an API key, or fall back to a paid image API.
+
+## Choose the right operation
+
+- New image without references: supply `prompt`.
+- New image guided by existing images: supply `prompt` and reference images. Describe each reference as a style, identity, composition, or mood guide. The tool uses its image-edit endpoint for any request with references, even when the creative intent is a new scene.
+- Edit an existing image: supply references and specify exactly what changes and what stays fixed.
+- Several assets: make one call per asset. For a coherent series, establish an approved reference first and reuse it. Avoid generating every asset independently when consistency matters.
+- Existing vector icon sets, logos, simple diagrams, or code-native visuals: edit their native files when that better fits the task. Do not replace requested raster art with SVG placeholders.
+
+## Tool arguments
+
+- `prompt`: a complete brief, up to 16,000 characters. Include exact text, reference roles, required details, and exclusions.
+- `referenced_image_paths`: one to five local PNG, JPEG, or WebP paths, in the same order used by the prompt. Relative paths use the project directory. These are uploaded to the image service for the requested edit.
+- `num_last_images_to_include`: one to five recent images from the current conversation branch. The selected images are supplied oldest first. This includes user attachments, images read by tools, and generated images. Unrelated recent images can enter this window, so explicit paths are safer for long workflows.
+- `output_path`: an optional new `.png` file path. Otherwise a unique file is saved under `output/imagegen/` in the current project.
+
+Choose either `referenced_image_paths` or `num_last_images_to_include`, never both. Do not pass an empty reference list. References must be at most 32 MiB each and 50 MiB combined. The tool accepts local paths, not arbitrary remote URLs.
+
+There are no separate model, size, quality, seed, mask, or batch arguments. Put framing, proportions, detail, and transparency requirements in the prompt. Do not promise exact dimensions, reproducible seeds, or pixel-perfect preservation. The backend decides the output dimensions and quality.
+
+## Workflow
+
+1. Identify whether this is new artwork, reference-guided generation, or an edit. Determine the intended use and destination.
+2. Collect the brief, literal text, must-keep details, and any references. Ask only when a missing detail blocks the task.
+3. Inspect local references with `read` before composing an edit. Label them by index and role in the prompt, such as `Image 1: edit target; Image 2: character identity reference`.
+4. Preserve detailed user instructions. For a vague brief, add useful framing, materials, or lighting, but do not invent brands, characters, props, slogans, or story requirements.
+5. Make an `image_gen` call. Prefer meaningful output filenames. Never overwrite a source image or an existing deliverable; choose a sibling filename such as `hero-v2.png`.
+6. Inspect the returned preview against the request. If necessary, use `read` to inspect the saved file. Check the subject, composition, text, identity, and constraints. A model without vision must not claim it visually inspected the output; ask the user to assess it instead.
+7. If correction is needed, use the output as an edit reference and request one specific change. Repeat the must-keep constraints. Do not generate excessive variants or retry failed requests automatically; each call can consume image allowance.
+8. Keep the final asset in the project, update consuming code when requested, and report the saved path and final prompt. A failed custom save can fall back to `output/imagegen/`; use the path actually returned by the tool.
+
+## Keeping images consistent
+
+Consistency comes from explicit visual references and a repeated brief, not hidden memory between image requests. The pi model plans the request, inspects outputs, and chooses the next edit. The image service receives only the prompt and selected references, not the whole pi conversation.
+
+For a character, product, or illustration series:
+
+1. Establish an anchor image and retain its saved path.
+2. Write a short visual specification covering the important proportions, features, materials, palette, and drawing style.
+3. Include the anchor in later requests. For a local correction, include the latest version as the edit target and optionally the anchor as the identity/style reference.
+4. Give each image a distinct role. For example, `Image 1: current scene to edit. Image 2: approved robot design; preserve its head shape, eye spacing, ceramic finish, and joint proportions`.
+5. Explicitly separate allowed changes from invariants. For example, `Change only the watering can to blue. Keep the robot, pose, fern, lighting, framing, and watercolor texture unchanged`.
+6. Compare each result with the anchor. If repeated edits drift, return to the anchor and describe the desired scene again.
+
+Full-resolution generated files are reused for recent-image edits, rather than the resized preview. The current branch controls which recent images are eligible, so abandoned forks are not used. Explicit paths are useful after compaction or when the recent-image order is ambiguous.
+
+Reference-guided generation improves continuity but cannot guarantee identical geometry, faces, typography, or individual pixels.
+
+## Prompt structure
+
+Use only the lines that clarify the request:
+
+```text
+Intended use: product photo, website hero, story illustration, sprite, etc.
+Primary request: the user's desired image or edit
+Input images: Image 1 and its role; Image 2 and its role
+Scene and subject: environment, subject, important details
+Style and materials: photo, watercolor, clay render, surface textures
+Composition: viewpoint, framing, proportions, useful negative space
+Lighting and palette: requested light and color constraints
+Text, verbatim: "Exact words"
+Change only: allowed changes for an edit
+Keep unchanged: identity, layout, objects, pose, typography, and other invariants
+Avoid: unwanted elements
+```
+
+For photos, state photorealism and relevant real-world materials or textures. For text, quote the exact wording and describe placement and typography. Verify the result instead of assuming text rendered correctly. For diagrams or educational visuals, provide the actual labels and relationships; do not invent data.
+
+## Transparency
+
+Ask for a genuinely transparent background, not a checkerboard painted into an opaque image. Keep the saved PNG intact so any alpha channel is preserved. Visual appearance alone does not prove transparency; check the file's alpha if transparency is required. Do not switch models or services to obtain it without the user's permission.
+
+## Examples
+
+New image:
+
+```json
+{
+  "prompt": "Website hero illustration of a small ceramic robot tending a fern. Watercolor on warm white paper, soft window light. Wide framing with room for page copy. No lettering or watermark.",
+  "output_path": "public/images/robot-hero.png"
+}
+```
+
+Targeted edit:
+
+```json
+{
+  "prompt": "Image 1 is the edit target. Change only the watering can to blue. Keep the robot design, pose, fern, background, lighting, framing, and watercolor texture unchanged. No new objects or text.",
+  "referenced_image_paths": ["public/images/robot-hero.png"],
+  "output_path": "public/images/robot-hero-v2.png"
+}
+```
+
+Recent-image edit:
+
+```json
+{
+  "prompt": "Change only the background of the supplied image to a plain warm white. Preserve the subject, pose, materials, and framing.",
+  "num_last_images_to_include": 1
+}
+```
+
+## Authentication and failures
+
+The tool and this skill load only when pi has an `openai-codex` OAuth subscription credential in its `auth.json`. Pi manages token refresh. After adding or removing that login, use `/reload` to update extension and skill registration. The active conversation model does not need to be OpenAI.
+
+If authentication fails, tell the user to log in with `/login openai-codex`. For rate limits, wait rather than changing providers. After a timeout or connection failure, the image request may already have consumed allowance. Do not claim a file exists unless the tool returned a saved path.

package/src/auth.ts

@@ -0,0 +1,51 @@
+import { readStoredCredential, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export const PROVIDER = "openai-codex";
+export const OFF_WARNING = "image generation is off, no openai-codex provider configured.";
+
+export function hasSubscription(): boolean {
+  const credential = readStoredCredential(PROVIDER);
+  return credential?.type === "oauth" && typeof credential.access === "string" &&
+    credential.access.length > 0 && typeof credential.refresh === "string" &&
+    credential.refresh.length > 0;
+}
+
+export interface ImageAuth {
+  accessToken: string;
+  accountId: string;
+}
+
+// Only extracts routing metadata. The backend, not this decoder, verifies the JWT.
+export function accountIdFromToken(token: string): string | undefined {
+  try {
+    const claims = JSON.parse(Buffer.from(token.split(".")[1], "base64url").toString("utf8"));
+    const id = claims["https://api.openai.com/auth"]?.chatgpt_account_id;
+    return typeof id === "string" && id.length > 0 ? id : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function resolveImageAuth(
+  registry: Pick<ExtensionContext["modelRegistry"], "getProviderAuth">,
+): Promise<ImageAuth> {
+  if (!hasSubscription()) throw new Error(OFF_WARNING + " Use /login openai-codex, then /reload.");
+
+  // Pi owns token refresh, file locking and persistence. Never refresh or write auth.json here.
+  let resolved;
+  try {
+    resolved = await registry.getProviderAuth(PROVIDER);
+  } catch {
+    throw new Error("Could not refresh the openai-codex login. Use /login openai-codex, then /reload.");
+  }
+  const credential = readStoredCredential(PROVIDER);
+  const accessToken = resolved?.auth.apiKey;
+  // Reject environment/API-key fallbacks and provider overrides that changed the credential.
+  if (credential?.type !== "oauth" || !accessToken || accessToken !== credential.access) {
+    throw new Error("Image generation requires the stored openai-codex subscription login, not an API key or override.");
+  }
+  const accountId = accountIdFromToken(accessToken) ??
+    (typeof credential.accountId === "string" ? credential.accountId : undefined);
+  if (!accountId) throw new Error("The openai-codex login has no account ID. Please log in again.");
+  return { accessToken, accountId };
+}

package/src/backend.ts

@@ -0,0 +1,137 @@
+import { randomUUID } from "node:crypto";
+import { PNG } from "pngjs";
+import type { ImageAuth } from "./auth.ts";
+
+export const IMAGE_MODEL = "gpt-image-2";
+const BASE_URL = "https://chatgpt.com/backend-api/codex";
+export const MAX_IMAGE_BYTES = 32 * 1024 * 1024;
+const MAX_RESPONSE_BYTES = 48 * 1024 * 1024;
+
+export interface ImageRequest {
+  prompt: string;
+  images?: string[];
+}
+
+export interface GeneratedImage {
+  bytes: Buffer;
+  generationId?: string;
+}
+
+async function boundedBody(response: Response, maxBytes: number): Promise<Buffer> {
+  const declared = Number(response.headers.get("content-length"));
+  if (declared > maxBytes) {
+    await response.body?.cancel();
+    throw new Error("Image backend response exceeds the size limit.");
+  }
+  if (!response.body) throw new Error("Image backend returned an empty response.");
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > maxBytes) {
+        await reader.cancel();
+        throw new Error("Image backend response exceeds the size limit.");
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  return Buffer.concat(chunks, total);
+}
+
+export function decodePng(base64: unknown): Buffer {
+  if (typeof base64 !== "string" || base64.length === 0 ||
+    base64.length > Math.ceil(MAX_IMAGE_BYTES / 3) * 4 ||
+    base64.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(base64)) {
+    throw new Error("Image backend returned invalid or oversized image data.");
+  }
+  const bytes = Buffer.from(base64, "base64");
+  if (bytes.length > MAX_IMAGE_BYTES || bytes.length < 24 ||
+    bytes.subarray(0, 8).toString("hex") !== "89504e470d0a1a0a" ||
+    bytes.toString("ascii", 12, 16) !== "IHDR") {
+    throw new Error("Image backend did not return a PNG image.");
+  }
+  const width = bytes.readUInt32BE(16);
+  const height = bytes.readUInt32BE(20);
+  if (!width || !height || width > 8192 || height > 8192 || width * height > 16_777_216) {
+    throw new Error("Image backend returned unsupported PNG dimensions.");
+  }
+  try {
+    // Validate chunks, CRCs and pixel data, but keep the original encoded bytes and alpha.
+    PNG.sync.read(bytes, { checkCRC: true });
+  } catch {
+    throw new Error("Image backend returned a corrupt PNG image.");
+  }
+  return bytes;
+}
+
+export async function requestImage(
+  auth: ImageAuth,
+  request: ImageRequest,
+  signal: AbortSignal,
+  fetcher: typeof fetch = fetch,
+): Promise<GeneratedImage> {
+  signal.throwIfAborted();
+  const editing = !!request.images?.length;
+  let response: Response;
+  try {
+    response = await fetcher(`${BASE_URL}/images/${editing ? "edits" : "generations"}`, {
+      method: "POST",
+      // Never follow a redirect with a subscription credential.
+      redirect: "error",
+      signal,
+      headers: {
+        Authorization: `Bearer ${auth.accessToken}`,
+        "ChatGPT-Account-ID": auth.accountId,
+        "Content-Type": "application/json",
+        originator: "pi-image-generation",
+        "x-codex-image-turn-id": randomUUID(),
+      },
+      body: JSON.stringify({
+        model: IMAGE_MODEL,
+        prompt: request.prompt,
+        background: "auto",
+        quality: "auto",
+        size: "auto",
+        ...(editing ? { images: request.images!.map(image_url => ({ image_url })) } : {}),
+      }),
+    });
+  } catch {
+    signal.throwIfAborted();
+    throw new Error("Image backend connection failed. No automatic retry was made; the request may have been processed.");
+  }
+
+  if (!response.ok) {
+    // Do not echo upstream bodies, prompts, account IDs or auth headers into the session.
+    await response.body?.cancel();
+    const hints: Record<number, string> = {
+      400: "The backend rejected the image request. Check the prompt and reference images.",
+      401: "The subscription login was rejected. Use /login openai-codex, then /reload.",
+      403: "Image generation is not permitted for this account or request.",
+      404: "The subscription image endpoint is unavailable.",
+      429: "The image allowance or rate limit was reached. Wait before trying again.",
+    };
+    throw new Error(`Image generation failed (HTTP ${response.status}). ${hints[response.status] ?? "No automatic retry was made; try again later."}`);
+  }
+
+  let body: unknown;
+  try {
+    body = JSON.parse((await boundedBody(response, MAX_RESPONSE_BYTES)).toString("utf8"));
+  } catch {
+    signal.throwIfAborted();
+    throw new Error("Image backend returned an unreadable or oversized response. No automatic retry was made.");
+  }
+  const data = (body as { data?: { b64_json?: unknown; generation_id?: unknown }[] })?.data;
+  if (!Array.isArray(data) || data.length !== 1) {
+    throw new Error("Image backend did not return exactly one image.");
+  }
+  return {
+    bytes: decodePng(data[0]?.b64_json),
+    generationId: typeof data[0]?.generation_id === "string" ? data[0].generation_id : undefined,
+  };
+}

package/src/images.ts

@@ -0,0 +1,147 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { open, lstat, stat, mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, extname, isAbsolute, join, resolve } from "node:path";
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { MAX_IMAGE_BYTES } from "./backend.ts";
+
+export const MAX_REFERENCES = 5;
+const MAX_TOTAL_INPUT_BYTES = 50 * 1024 * 1024;
+
+export function imagePath(input: string, cwd: string): string {
+  let path = input.startsWith("@") ? input.slice(1) : input;
+  if (path === "~") path = homedir();
+  else if (/^~[/\\]/.test(path)) path = join(homedir(), path.slice(2));
+  return isAbsolute(path) ? path : resolve(cwd, path);
+}
+
+export function mimeForImage(bytes: Buffer): string {
+  if (bytes.subarray(0, 8).toString("hex") === "89504e470d0a1a0a") return "image/png";
+  if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return "image/jpeg";
+  if (bytes.toString("ascii", 0, 4) === "RIFF" && bytes.toString("ascii", 8, 12) === "WEBP") return "image/webp";
+  throw new Error("Reference images must be PNG, JPEG, or WebP files.");
+}
+
+async function fileImage(path: string, signal: AbortSignal): Promise<Buffer> {
+  signal.throwIfAborted();
+  if (!(await stat(path)).isFile()) throw new Error("Reference images must be regular files.");
+  // O_NONBLOCK prevents a FIFO swapped in after stat() from hanging open() on Unix.
+  const flags = constants.O_RDONLY | (process.platform === "win32" ? 0 : constants.O_NONBLOCK);
+  const handle = await open(path, flags);
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.size === 0 || stat.size > MAX_IMAGE_BYTES) {
+      throw new Error("Reference images must be regular files of at most 32 MiB.");
+    }
+    // Bounded even if another process grows the file between stat and read.
+    const bytes = Buffer.alloc(stat.size + 1);
+    let read = 0;
+    while (read < bytes.length) {
+      signal.throwIfAborted();
+      const result = await handle.read(bytes, read, bytes.length - read, null);
+      if (result.bytesRead === 0) break;
+      read += result.bytesRead;
+    }
+    if (read > stat.size) throw new Error("Reference image changed while reading. Try again.");
+    return bytes.subarray(0, read);
+  } finally {
+    await handle.close();
+  }
+}
+
+type Reference = { path: string } | { base64: string };
+const record = (value: unknown): Record<string, unknown> | undefined =>
+  value !== null && typeof value === "object" ? value as Record<string, unknown> : undefined;
+
+// The caller supplies only the active branch. Never use getEntries(), which includes abandoned forks.
+export function recentReferences(entries: readonly unknown[], count: number): Reference[] {
+  const found: Reference[] = [];
+  for (let index = entries.length - 1; index >= 0 && found.length < count; index--) {
+    const entry = record(entries[index]);
+    const message = entry?.type === "message" ? record(entry.message) :
+      entry?.type === "custom_message" ? entry : undefined;
+    if (!message || message.isError === true) continue;
+    if (message.role === "toolResult" && message.toolName === "image_gen") {
+      const details = record(message.details);
+      if (typeof details?.savedPath === "string") {
+        found.push({ path: details.savedPath });
+        continue; // Use the full-resolution artifact, not its inline preview as a second reference.
+      }
+    }
+    if (!Array.isArray(message.content)) continue;
+    for (let i = message.content.length - 1; i >= 0 && found.length < count; i--) {
+      const block = record(message.content[i]);
+      if (block?.type !== "image") continue;
+      if (typeof block.data === "string") found.push({ base64: block.data });
+      else throw new Error("A recent image is not available inline. Use referenced_image_paths instead.");
+    }
+  }
+  if (found.length !== count) {
+    throw new Error(`Requested ${count} recent images, but only ${found.length} are available on this branch. Use referenced_image_paths instead.`);
+  }
+  return found.reverse();
+}
+
+export async function loadReferences(
+  paths: string[] | undefined,
+  recentCount: number | undefined,
+  entries: readonly unknown[],
+  cwd: string,
+  signal: AbortSignal,
+): Promise<string[]> {
+  if (paths !== undefined && recentCount !== undefined) {
+    throw new Error("Use referenced_image_paths or num_last_images_to_include, not both.");
+  }
+  if (paths !== undefined && (paths.length < 1 || paths.length > MAX_REFERENCES)) {
+    throw new Error("Supply between 1 and 5 reference-image paths.");
+  }
+  if (recentCount !== undefined && (!Number.isInteger(recentCount) || recentCount < 1 || recentCount > MAX_REFERENCES)) {
+    throw new Error("num_last_images_to_include must be an integer between 1 and 5.");
+  }
+  const references: Reference[] = paths?.map(path => ({ path: imagePath(path, cwd) })) ??
+    (recentCount === undefined ? [] : recentReferences(entries, recentCount));
+  let total = 0;
+  const images: string[] = [];
+  for (const reference of references) {
+    signal.throwIfAborted();
+    let bytes: Buffer;
+    if ("path" in reference) {
+      bytes = await fileImage(reference.path, signal);
+    } else {
+      if (reference.base64.length > Math.ceil(MAX_IMAGE_BYTES / 3) * 4 ||
+        reference.base64.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(reference.base64)) {
+        throw new Error("Recent image has invalid or oversized data. Use a local image path instead.");
+      }
+      bytes = Buffer.from(reference.base64, "base64");
+    }
+    total += bytes.length;
+    if (bytes.length > MAX_IMAGE_BYTES || total > MAX_TOTAL_INPUT_BYTES) {
+      throw new Error("Reference images exceed the 32 MiB per-image or 50 MiB combined limit.");
+    }
+    images.push(`data:${mimeForImage(bytes)};base64,${bytes.toString("base64")}`);
+  }
+  return images;
+}
+
+export async function prepareOutput(cwd: string, requested?: string): Promise<string> {
+  const path = requested === undefined
+    ? join(cwd, "output", "imagegen", `${Date.now()}-${randomUUID()}.png`)
+    : imagePath(requested, cwd);
+  if (extname(path).toLowerCase() !== ".png") throw new Error("output_path must end in .png.");
+  try {
+    await lstat(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return path;
+    throw error;
+  }
+  throw new Error("The output file already exists. Choose a new filename; images are never overwritten.");
+}
+
+export async function saveImage(path: string, bytes: Buffer): Promise<void> {
+  await withFileMutationQueue(path, async () => {
+    await mkdir(dirname(path), { recursive: true });
+    // Exclusive creation protects against races, hardlinks and an existing symlink at the destination.
+    await writeFile(path, bytes, { flag: "wx", mode: 0o600 });
+  });
+}

package/src/index.ts

@@ -0,0 +1,113 @@
+import { fileURLToPath } from "node:url";
+import { Type } from "typebox";
+import { resizeImage, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { hasSubscription, OFF_WARNING, resolveImageAuth } from "./auth.ts";
+import { IMAGE_MODEL, requestImage } from "./backend.ts";
+import { loadReferences, prepareOutput, saveImage } from "./images.ts";
+
+const parameters = Type.Object({
+  prompt: Type.String({ minLength: 1, maxLength: 16000, description: "Complete image brief, including reference-image roles and details that must not change." }),
+  referenced_image_paths: Type.Optional(Type.Array(Type.String({ minLength: 1 }), {
+    minItems: 1, maxItems: 5, description: "Local PNG/JPEG/WebP references, in prompt order. Relative paths resolve against the project. Do not combine with num_last_images_to_include.",
+  })),
+  num_last_images_to_include: Type.Optional(Type.Integer({
+    minimum: 1, maximum: 5, description: "Use the last 1-5 images on this conversation branch, oldest first. Prefer explicit paths when several unrelated images are present.",
+  })),
+  output_path: Type.Optional(Type.String({ minLength: 1, description: "New .png destination. Defaults to output/imagegen/<unique-name>.png in the project. Never overwrites an existing file." })),
+}, { additionalProperties: false });
+
+// Registry auth resolution does its own locked refresh. Stop waiting on cancellation without
+// interrupting that shared refresh or letting this tool proceed to an image request afterward.
+async function abortable<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+  signal.throwIfAborted();
+  let onAbort: () => void = () => {};
+  const aborted = new Promise<never>((_, reject) => {
+    onAbort = () => reject(signal.reason);
+    signal.addEventListener("abort", onAbort, { once: true });
+    if (signal.aborted) onAbort();
+  });
+  try {
+    return await Promise.race([promise, aborted]);
+  } finally {
+    signal.removeEventListener("abort", onAbort);
+  }
+}
+
+export default function imageGeneration(pi: ExtensionAPI): void {
+  if (!hasSubscription()) {
+    pi.on("session_start", (_event, ctx) => {
+      if (ctx.hasUI) ctx.ui.notify(OFF_WARNING, "warning");
+      else console.error(OFF_WARNING);
+    });
+    return;
+  }
+
+  // Not listed in the package's static skill manifest, so it cannot leak into unauthenticated sessions.
+  pi.on("resources_discover", () => ({
+    skillPaths: hasSubscription() ? [fileURLToPath(new URL("../resources/imagegen/SKILL.md", import.meta.url))] : [],
+  }));
+
+  pi.registerTool({
+    name: "image_gen",
+    label: "Generate image",
+    description: "Generate or edit one raster image using the configured Codex subscription. Accepts up to five local or recent-conversation reference images for consistent edits and variants. Saves a new PNG and returns a preview when possible. No API-key fallback. Reference limits: 32 MiB each, 50 MiB combined; 4-minute request timeout. Load the imagegen skill first.",
+    promptSnippet: "Generate images or edit them using local or recent image references",
+    promptGuidelines: [
+      "Before using image_gen, read the imagegen skill. Reuse reference images and state what must remain unchanged for consistent edits.",
+      "Use image_gen for requested raster artwork, not SVG placeholders. Prefer native code edits for existing vector assets.",
+    ],
+    parameters,
+    async execute(_toolCallId, args, signal, onUpdate, ctx) {
+      const timeout = AbortSignal.timeout(240_000);
+      const requestSignal = signal ? AbortSignal.any([signal, timeout]) : timeout;
+      requestSignal.throwIfAborted();
+      if (!args.prompt.trim()) throw new Error("The image prompt must not be blank.");
+      if (!hasSubscription()) throw new Error(OFF_WARNING + " Use /login openai-codex, then /reload.");
+      const path = await prepareOutput(ctx.cwd, args.output_path);
+      const images = await loadReferences(args.referenced_image_paths, args.num_last_images_to_include,
+        ctx.sessionManager.getBranch(), ctx.cwd, requestSignal);
+      const auth = await abortable(resolveImageAuth(ctx.modelRegistry), requestSignal);
+      onUpdate?.({ content: [{ type: "text", text: images.length ? "Editing image…" : "Generating image…" }], details: {} });
+
+      let result;
+      try {
+        result = await requestImage(auth, { prompt: args.prompt, images }, requestSignal);
+      } catch (error) {
+        if (timeout.aborted && !signal?.aborted) {
+          throw new Error("Image generation timed out after four minutes. It may still have consumed image allowance; no automatic retry was made.");
+        }
+        throw error;
+      }
+      // Persist the original before processing a smaller preview. Never re-encode the saved PNG.
+      let savedPath = path;
+      let saveNote = "";
+      try {
+        await saveImage(savedPath, result.bytes);
+      } catch {
+        savedPath = await prepareOutput(ctx.cwd);
+        try {
+          await saveImage(savedPath, result.bytes);
+        } catch {
+          throw new Error("The image was generated, but could not be saved. Check workspace write permissions before generating again.");
+        }
+        saveNote = " The requested destination could not be written; saved to the default output directory instead.";
+      }
+      const preview = await resizeImage(result.bytes, "image/png").catch(() => null);
+      const content: ({ type: "text"; text: string } | { type: "image"; data: string; mimeType: string })[] = [
+        { type: "text", text: `Saved image: ${savedPath}.${saveNote}\nPrompt: ${args.prompt}` },
+      ];
+      if (preview) content.push({ type: "image", data: preview.data, mimeType: preview.mimeType });
+      else content.push({ type: "text", text: "Preview unavailable. Inspect the saved PNG with the read tool." });
+      return {
+        content,
+        details: {
+          savedPath,
+          prompt: args.prompt,
+          model: IMAGE_MODEL,
+          operation: images.length ? "edit" : "generate",
+          referenceCount: images.length,
+        },
+      };
+    },
+  });
+}