pi-codex-image-gen 0.1.12 → 0.1.13

package/skills/imagegen/references/cli.md

@@ -1,6 +1,6 @@
 # CLI reference (`scripts/image_gen.py`)
 
-This file is for the fallback CLI mode only. Read it when the user explicitly asks to use `scripts/image_gen.py` / CLI / API / model controls, or after the user explicitly confirms that a transparent-output request should use the `gpt-image-1.5` true-transparency fallback path.
+This file is for the fallback CLI mode only. Read it when the user requests CLI/API controls or confirms a native transparency API fallback.
 
 `generate-batch` is a CLI subcommand in this fallback path. It is not a top-level mode of the skill.
 The word `batch` in a user request is not CLI opt-in by itself.
@@ -73,12 +73,14 @@ python "$IMAGE_GEN" edit \
 
 `gpt-image-2` is the default model for new CLI fallback work.
 
+For explicit Images 2.5 requests, use `--model gpt-image-2.5-flare` or `--model gpt-image-2.5-sunburst`. Their `2026-09-08` snapshots are also supported. Both accept `--quality xhigh` and `--quality max`, and the flexible size constraints below, including `1536x864`. Sizes above `2560x1440` are experimental. Leave 2.5 `--input-fidelity` unset; support is not verified. These options do not apply to the Pi tool.
+
 - Use `--quality low` for fast drafts, thumbnails, and quick iterations.
 - Use `--quality medium`, `--quality high`, or `--quality auto` for final assets, dense text, diagrams, identity-sensitive edits, and high-resolution outputs.
 - Square images are typically fastest. Use `--size 1024x1024` for quick square drafts.
 - If the user asks for 4K-style output, use `--size 3840x2160` for landscape or `--size 2160x3840` for portrait.
 - Do not pass `--input-fidelity` with `gpt-image-2`; this model always uses high fidelity for image inputs.
-- Do not use `--background transparent` with `gpt-image-2`; the default transparent-image workflow uses Pi `codex_generate_image` on a flat chroma-key background plus local removal. Use `gpt-image-1.5` only after the user explicitly confirms the true-transparent CLI fallback, unless they already requested `gpt-image-1.5`, `scripts/image_gen.py`, or CLI fallback.
+- `gpt-image-2` supports `--background transparent` in preview with PNG or WebP. Confirm the separately billed API fallback before switching from Pi's chroma-key path.
 
 Popular `gpt-image-2` sizes:
 - `1024x1024`
@@ -140,7 +142,7 @@ python "$IMAGE_GEN" generate \
   --out output/imagegen/product-cutout.png
 ```
 
-When using this path, explain briefly that Pi `codex_generate_image` plus chroma-key removal is the default transparent-image path, but this request needs true model-native transparency. `gpt-image-2` does not support `background=transparent`, so `gpt-image-1.5` is required for this confirmed fallback.
+The older-model example above remains available when explicitly requested. Prefer `--model gpt-image-2` for native transparency preview. Explain that this API fallback requires an API key and separate billing; Pi still uses chroma-key removal.
 
 ## Quality, input fidelity, and masks (CLI fallback only)
 These are explicit CLI controls. They are not Pi `codex_generate_image` tool arguments.
@@ -229,8 +231,8 @@ Notes:
 - For many requested deliverable assets, provide one prompt/job per distinct asset and use semantic filenames when possible.
 
 ## CLI notes
-- Supported sizes depend on the model. `gpt-image-2` supports flexible constrained sizes; older GPT Image models support `1024x1024`, `1536x1024`, `1024x1536`, or `auto`.
-- True transparent CLI outputs require `output_format` to be `png` or `webp` and are not supported by `gpt-image-2`.
+- Supported sizes depend on the model. GPT Image 2 and 2.5 (including the documented snapshots) support flexible constrained sizes; older GPT Image models support `1024x1024`, `1536x1024`, `1024x1536`, or `auto`.
+- Native transparent CLI outputs require `output_format` to be `png` or `webp`. GPT Image 2 support is in preview.
 - `--prompt-file`, `--output-compression`, `--moderation`, `--max-attempts`, `--fail-fast`, `--force`, and `--no-augment` are supported.
 - This CLI is intended for GPT Image models. Do not assume older non-GPT image-model behavior applies here.
 

package/skills/imagegen/references/image-api.md

@@ -1,31 +1,39 @@
 # Image API quick reference
 
-This file is for the fallback CLI mode only. Use it when the user explicitly asks to use `scripts/image_gen.py` / CLI / API / model controls, or after the user explicitly confirms that a transparent-output request should use the `gpt-image-1.5` true-transparency fallback path.
+This file is for the fallback CLI mode only. Use it when the user explicitly requests CLI/API controls or confirms a native transparency API fallback.
 
 These parameters describe the Image API and bundled CLI fallback surface. Do not assume they are normal arguments on the Pi `codex_generate_image` tool.
 
 ## Scope
-- This fallback CLI is intended for GPT Image models (`gpt-image-2`, `gpt-image-1.5`, `gpt-image-1`, and `gpt-image-1-mini`).
+- This fallback CLI supports GPT Image models, including `gpt-image-2.5-flare` and `gpt-image-2.5-sunburst`.
 - The Pi `codex_generate_image` tool and the fallback CLI do not expose the same controls.
 
 ## Model summary
 
 | Model | Quality | Input fidelity | Resolutions | Recommended use |
 | --- | --- | --- | --- | --- |
+| `gpt-image-2.5-flare` | `low`, `medium`, `high`, `xhigh`, `max`, `auto` | Leave unset; not verified | `auto` or flexible sizes below | Optional fast generation |
+| `gpt-image-2.5-sunburst` | `low`, `medium`, `high`, `xhigh`, `max`, `auto` | Leave unset; not verified | `auto` or flexible sizes below | Optional precision editing |
 | `gpt-image-2` | `low`, `medium`, `high`, `auto` | Always high fidelity for image inputs; do not set `input_fidelity` | `auto` or flexible sizes that satisfy the constraints below | Default for new CLI/API workflows: high-quality generation and editing, text-heavy images, photorealism, compositing, identity-sensitive edits, and workflows where fewer retries matter |
 | `gpt-image-1.5` | `low`, `medium`, `high`, `auto` | `low`, `high` | `1024x1024`, `1024x1536`, `1536x1024`, `auto` | True transparent-background fallback and backward-compatible workflows |
 | `gpt-image-1` | `low`, `medium`, `high`, `auto` | `low`, `high` | `1024x1024`, `1024x1536`, `1536x1024`, `auto` | Legacy compatibility |
 | `gpt-image-1-mini` | `low`, `medium`, `high`, `auto` | `low`, `high` | `1024x1024`, `1024x1536`, `1536x1024`, `auto` | Cost-sensitive draft batches and lower-stakes previews |
 
-## gpt-image-2 sizes
+The CLI also recognizes the `2026-09-08` snapshots of both 2.5 models for extended quality settings. Defaults remain unchanged.
 
-`gpt-image-2` accepts `auto` or any `WIDTHxHEIGHT` size that satisfies all constraints:
+Sources: [Flare](https://developers.openai.com/api/docs/models/gpt-image-2.5-flare), [Sunburst](https://developers.openai.com/api/docs/models/gpt-image-2.5-sunburst), [image generation guide](https://developers.openai.com/api/docs/guides/image-generation.md), and [image tool options](https://developers.openai.com/api/docs/guides/tools-image-generation).
+
+## Flexible sizes: GPT Image 2 and 2.5
+
+GPT Image 2 and both 2.5 models accept `auto` or any `WIDTHxHEIGHT` size that satisfies all constraints. The CLI also recognizes their documented dated snapshots.
 
 - Maximum edge length must be less than or equal to `3840px`.
 - Both edges must be multiples of `16px`.
 - Long edge to short edge ratio must not exceed `3:1`.
 - Total pixels must be at least `655,360` and no more than `8,294,400`.
 
+For 2.5, resolutions above `2560x1440` are experimental.
+
 Popular sizes:
 
 | Label | Size | Notes |
@@ -49,8 +57,8 @@ Square images are typically fastest to generate. For 4K-style output, use `3840x
 - `prompt`: text prompt
 - `model`: image model
 - `n`: number of images (1-10)
-- `size`: `auto` by default for `gpt-image-2`; flexible `WIDTHxHEIGHT` sizes are allowed only for `gpt-image-2`; older GPT Image models use `1024x1024`, `1536x1024`, `1024x1536`, or `auto`
-- `quality`: `low`, `medium`, `high`, or `auto`
+- `size`: `auto` by default; GPT Image 2 and 2.5 accept flexible `WIDTHxHEIGHT` sizes under the constraints above; older models use `1024x1024`, `1536x1024`, `1024x1536`, or `auto`
+- `quality`: `low`, `medium`, `high`, or `auto`; the documented 2.5 models also accept `xhigh` and `max`
 - `background`: output transparency behavior (`transparent`, `opaque`, or `auto`) for generated output; this is not the same thing as the prompt's visual scene/backdrop
 - `output_format`: `png` (default), `jpeg`, `webp`
 - `output_compression`: 0-100 (jpeg/webp only)
@@ -68,9 +76,11 @@ Model-specific note for `input_fidelity`:
 
 ## Transparent backgrounds
 
-`gpt-image-2` does not currently support the Image API `background=transparent` parameter. The skill's default transparent-image path is Pi `codex_generate_image` with a flat chroma-key background, followed by local alpha extraction with `python "scripts/remove_chroma_key.py"`.
+`gpt-image-2` supports `background=transparent` in preview with PNG or WebP. The Pi tool has no background parameter, so its default path remains chroma-key generation followed by local alpha extraction.
+
+Both 2.5 API models also document native transparency with PNG or WebP. This public API capability does not establish that subscription parameters are honored.
 
-Use CLI `gpt-image-1.5` with `background=transparent` and a transparent-capable output format such as `png` or `webp` only after the user explicitly confirms that fallback, unless they already requested `gpt-image-1.5`, `scripts/image_gen.py`, or CLI fallback. If the user asks for true/native transparency, the subject is too complex for clean chroma-key removal, or local background removal fails validation, explain the tradeoff and ask before switching.
+Use CLI `gpt-image-2 --background transparent --output-format png` (or `webp`) only after the user chooses the API path. Explain that it requires an API key and separate billing. Do not silently switch to an older model if preview transparency fails.
 
 ## Output
 - `data[]` list with `b64_json` per image

package/skills/imagegen/references/prompting.md

@@ -79,7 +79,7 @@ Do not add:
 - Ask for crisp edges, generous padding, and no use of the key color inside the subject.
 - After generation, remove the background locally with `python "scripts/remove_chroma_key.py" --input <source> --out <final.png> --auto-key border --soft-matte --transparent-threshold 12 --opaque-threshold 220 --despill` and validate the alpha result before shipping it.
 - Use soft matte and despill for antialiased edges; hard tolerance-only removal is mainly for flat pixel-art or exact-color fixtures.
-- Use CLI `gpt-image-1.5 --background transparent --output-format png` only after the user explicitly confirms the fallback, or when the user already explicitly requested `gpt-image-1.5`, `scripts/image_gen.py`, or CLI fallback. Ask first for true/native transparency requests, failed chroma-key validation, or complex transparent subjects such as hair, fur, glass, smoke, liquids, translucent materials, reflective objects, or soft shadows.
+- Use CLI `gpt-image-2 --background transparent --output-format png` (preview) only after the user chooses the separately billed API fallback. Offer it for native transparency requests, failed chroma-key validation, or complex subjects such as hair, glass, smoke, or soft shadows.
 
 ## Fallback-only execution controls
 - `quality`, `input_fidelity`, explicit masks, output format, and output paths are fallback-only execution controls.
@@ -87,7 +87,7 @@ Do not add:
 - If the user explicitly chooses CLI fallback, see `references/cli.md` and `references/image-api.md` for those controls.
 - In CLI fallback mode, `gpt-image-2` is the default. It supports `quality=low|medium|high|auto`; use `low` for fast drafts and thumbnails, and move to `medium`, `high`, or `auto` for final assets.
 - `gpt-image-2` always uses high fidelity for image inputs, so do not set `input_fidelity` with that model.
-- If a transparent request needs true CLI transparency, ask before using `gpt-image-1.5` unless the user already explicitly chose it. Explain that Pi-tool chroma-key removal is the default path, but `gpt-image-2` does not support `background=transparent`.
+- For native transparency, offer the GPT Image 2 API preview with PNG or WebP. Ask before switching from Pi's chroma-key path to API billing.
 - If the user asks for 4K-style output with `gpt-image-2`, use `3840x2160` for landscape or `2160x3840` for portrait.
 
 ## Use-case tips

package/skills/imagegen/references/sample-prompts.md

@@ -19,7 +19,7 @@ CLI model notes:
 - `gpt-image-2` is the fallback CLI default for new workflows.
 - `gpt-image-2` supports `quality` values `low`, `medium`, `high`, and `auto`.
 - For 4K-style `gpt-image-2` output, use `3840x2160` or `2160x3840`.
-- If transparent output needs true 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 Pi-tool chroma-key removal is the default path, but `gpt-image-2` does not support `background=transparent`.
+- For native transparency, offer CLI `gpt-image-2 --background transparent --output-format png` (preview). Ask before switching from Pi's chroma-key path to separate API billing.
 - Do not set `input_fidelity` with `gpt-image-2`; image inputs already use high fidelity.
 
 For prompting principles (structure, specificity, invariants, iteration), see `references/prompting.md`.
@@ -395,7 +395,7 @@ Scene/backdrop: perfectly flat solid #00ff00 chroma-key background for local bac
 Constraints: background must be one uniform color with no shadows, gradients, texture, reflections, floor plane, or lighting variation; crisp silhouette; generous padding; no halos or fringing; preserve label text exactly; no restyling; do not use #00ff00 anywhere in the subject
 ```
 
-Post-process note: after Pi tool generation, run `python "scripts/remove_chroma_key.py" --input <source> --out <final.png> --auto-key border --soft-matte --transparent-threshold 12 --opaque-threshold 220 --despill`. Ask before using CLI `gpt-image-1.5 --background transparent --output-format png` for true/native transparency, failed chroma-key validation, or complex subjects such as hair, fur, glass, smoke, liquids, translucent materials, reflections, or soft shadows, unless the user already explicitly requested `gpt-image-1.5`, `scripts/image_gen.py`, or CLI fallback.
+Post-process note: after Pi tool generation, run `python "scripts/remove_chroma_key.py" --input <source> --out <final.png> --auto-key border --soft-matte --transparent-threshold 12 --opaque-threshold 220 --despill`. For native transparency, failed validation, or complex subjects, offer CLI `gpt-image-2 --background transparent --output-format png` (preview). Ask before switching to separate API billing.
 
 ### style-transfer
 ```

package/skills/imagegen/scripts/image_gen.py

@@ -1,8 +1,8 @@
 #!/usr/bin/env python3
 """Fallback CLI for explicit image generation or editing with GPT Image models.
 
-Used only when the user explicitly opts into CLI fallback mode, or when explicit
-transparent output requires the `gpt-image-1.5` fallback path.
+Used only when the user explicitly opts into CLI fallback mode, including
+confirmed native transparency requests with separate API billing.
 
 Defaults to gpt-image-2 and a structured prompt augmentation workflow.
 """
@@ -118,7 +118,7 @@ def _parse_size(size: str) -> Optional[Tuple[int, int]]:
     return int(match.group(1)), int(match.group(2))
 
 
-def _validate_gpt_image_2_size(size: str) -> None:
+def _validate_flexible_size(size: str, model: str) -> None:
     if size == "auto":
         return
 
@@ -132,20 +132,20 @@ def _validate_gpt_image_2_size(size: str) -> None:
     total_pixels = width * height
 
     if max_edge > GPT_IMAGE_2_MAX_EDGE:
-        _die("gpt-image-2 size maximum edge length must be less than or equal to 3840px.")
+        _die(f"{model} size maximum edge length must be less than or equal to 3840px.")
     if width % 16 != 0 or height % 16 != 0:
-        _die("gpt-image-2 size width and height must be multiples of 16px.")
+        _die(f"{model} size width and height must be multiples of 16px.")
     if max_edge / min_edge > GPT_IMAGE_2_MAX_RATIO:
-        _die("gpt-image-2 size long edge to short edge ratio must not exceed 3:1.")
+        _die(f"{model} size long edge to short edge ratio must not exceed 3:1.")
     if total_pixels < GPT_IMAGE_2_MIN_PIXELS or total_pixels > GPT_IMAGE_2_MAX_PIXELS:
         _die(
-            "gpt-image-2 size total pixels must be at least 655,360 and no more than 8,294,400."
+            f"{model} size total pixels must be at least 655,360 and no more than 8,294,400."
         )
 
 
 def _validate_size(size: str, model: str) -> None:
-    if model == GPT_IMAGE_2_MODEL:
-        _validate_gpt_image_2_size(size)
+    if _is_gpt_image_2(model) or _is_gpt_image_2_5(model):
+        _validate_flexible_size(size, model)
         return
 
     if size not in ALLOWED_LEGACY_SIZES:
@@ -154,9 +154,23 @@ def _validate_size(size: str, model: str) -> None:
         )
 
 
-def _validate_quality(quality: str) -> None:
-    if quality not in ALLOWED_QUALITIES:
-        _die("quality must be one of low, medium, high, or auto.")
+def _is_gpt_image_2(model: str) -> bool:
+    return model in {GPT_IMAGE_2_MODEL, "gpt-image-2-2026-04-21"}
+
+
+def _is_gpt_image_2_5(model: str) -> bool:
+    return model in {
+        "gpt-image-2.5-flare",
+        "gpt-image-2.5-flare-2026-09-08",
+        "gpt-image-2.5-sunburst",
+        "gpt-image-2.5-sunburst-2026-09-08",
+    }
+
+
+def _validate_quality(quality: str, model: str) -> None:
+    allowed = ALLOWED_QUALITIES | {"xhigh", "max"} if _is_gpt_image_2_5(model) else ALLOWED_QUALITIES
+    if quality not in allowed:
+        _die(f"quality for {model} must be one of {', '.join(sorted(allowed))}.")
 
 
 def _validate_background(background: Optional[str]) -> None:
@@ -187,13 +201,8 @@ def _validate_model_specific_options(
     background: Optional[str],
     input_fidelity: Optional[str] = None,
 ) -> None:
-    if model != GPT_IMAGE_2_MODEL:
+    if not _is_gpt_image_2(model):
         return
-    if background == "transparent":
-        _die(
-            "transparent backgrounds are not supported in gpt-image-2, the latest model. "
-            "Use --model gpt-image-1.5 --background transparent --output-format png instead."
-        )
     if input_fidelity is not None:
         _die(
             "input_fidelity is not supported in gpt-image-2 because image inputs always use high fidelity for this model."
@@ -210,7 +219,7 @@ def _validate_generate_payload(payload: Dict[str, Any]) -> None:
     quality = str(payload.get("quality", DEFAULT_QUALITY))
     background = payload.get("background")
     _validate_size(size, model)
-    _validate_quality(quality)
+    _validate_quality(quality, model)
     _validate_background(background)
     _validate_model_specific_options(model=model, background=background)
     oc = payload.get("output_compression")
@@ -978,7 +987,7 @@ def main() -> int:
 
     _validate_model(args.model)
     _validate_size(args.size, args.model)
-    _validate_quality(args.quality)
+    _validate_quality(args.quality, args.model)
     _validate_background(args.background)
     _validate_model_specific_options(
         model=args.model,

package/src/codex-response.ts

@@ -0,0 +1,286 @@
+// The subscription Responses contract is private. Keep its parser and safety
+// boundaries separate from Pi tool registration and file handling.
+export const REQUEST_TIMEOUT_MS = 5 * 60_000;
+export const MAX_RESPONSE_BYTES = 100 * 1024 * 1024;
+export const MAX_IMAGE_BYTES = 32 * 1024 * 1024;
+const MAX_ERROR_BYTES = 16 * 1024;
+const MAX_TEXT_CHARS = 4000;
+
+export interface ReportedImage {
+	model?: string;
+	size?: string;
+	quality?: string;
+	background?: string;
+	outputFormat?: string;
+}
+
+export interface ParsedCodexResponse {
+	image?: {
+		id: string;
+		status: "completed";
+		result: string;
+		revisedPrompt?: string;
+		reported: ReportedImage;
+	};
+	text: string[];
+	responseId?: string;
+	usage?: unknown;
+}
+
+function object(value: unknown): Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value)
+		? value as Record<string, unknown> : {};
+}
+
+function text(value: unknown, secrets: string[] = []): string {
+	if (typeof value !== "string") return "";
+	let result = value;
+	for (const secret of secrets) {
+		if (secret) result = result.split(secret).join("[redacted]");
+	}
+	// Also hide a JWT cut short by the text bound; exact-token matching alone
+	// cannot redact a credential that arrives across the truncation boundary.
+	return result.replace(/\beyJ[A-Za-z0-9_.-]*/g, "[redacted]")
+		.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").slice(0, MAX_TEXT_CHARS);
+}
+
+function identifier(value: unknown, secrets: string[]): string | undefined {
+	return typeof value === "string" && /^[a-zA-Z0-9_-]{1,128}$/.test(value)
+		&& !secrets.some(secret => secret && value.includes(secret)) ? value : undefined;
+}
+
+export function abortable<T>(work: Promise<T>, signal: AbortSignal): Promise<T> {
+	return new Promise<T>((resolve, reject) => {
+		const abort = () => reject(signal.reason);
+		if (signal.aborted) abort();
+		else signal.addEventListener("abort", abort, { once: true });
+		work.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+	});
+}
+
+export async function withRequestDeadline<T>(
+	signal: AbortSignal | undefined,
+	run: (signal: AbortSignal) => Promise<T>,
+): Promise<T> {
+	const controller = new AbortController();
+	const abort = () => controller.abort(new Error("Image generation was aborted."));
+	if (signal?.aborted) abort();
+	else signal?.addEventListener("abort", abort, { once: true });
+	const timer = setTimeout(() => controller.abort(new Error(
+		"Image generation timed out after 5 minutes. The backend may still finish; no automatic retry was made.",
+	)), REQUEST_TIMEOUT_MS);
+	try {
+		controller.signal.throwIfAborted();
+		return await run(controller.signal);
+	} catch (error) {
+		if (controller.signal.aborted) throw controller.signal.reason;
+		throw error;
+	} finally {
+		clearTimeout(timer);
+		signal?.removeEventListener("abort", abort);
+	}
+}
+
+async function* chunks(response: Response, limit: number, signal: AbortSignal): AsyncGenerator<Uint8Array> {
+	if (!response.body) throw new Error("Codex response did not include a stream body.");
+	const reader = response.body.getReader();
+	let bytes = 0;
+	try {
+		const declared = Number(response.headers.get("content-length"));
+		if (declared > limit) throw new Error("Codex response exceeded the size limit.");
+		while (true) {
+			signal.throwIfAborted();
+			let part: ReadableStreamReadResult<Uint8Array>;
+			try {
+				part = await abortable(reader.read(), signal);
+			} catch {
+				signal.throwIfAborted();
+				throw new Error("Codex response stream was interrupted. The backend may still finish; no automatic retry was made.");
+			}
+			const { done, value } = part;
+			if (done) break;
+			bytes += value.byteLength;
+			if (bytes > limit) throw new Error("Codex response exceeded the size limit.");
+			yield value;
+		}
+	} finally {
+		// Do not let a stalled stream cancellation defeat the request deadline.
+		void reader.cancel().catch(() => undefined);
+		reader.releaseLock();
+	}
+}
+
+const QUOTA_CODES = new Set([
+	"insufficient_quota", "quota_exceeded", "usage_limit_reached", "usage_limit_exceeded",
+	"billing_hard_limit_reached", "billing_not_active", "organization_usage_limit_exceeded",
+	"workspace_member_usage_limit_reached",
+]);
+
+function isQuota(error: Record<string, unknown>): boolean {
+	return [error.code, error.type].some(value => typeof value === "string" && QUOTA_CODES.has(value));
+}
+
+function errorHint(error: unknown): string {
+	const { code, type } = object(error);
+	if (isQuota({ code, type })) {
+		return "Codex subscription quota is unavailable or exhausted. Check your plan or wait for its reset.";
+	}
+	if (code === "moderation_blocked" || type === "image_generation_user_error") {
+		return "Codex could not generate this image. Review the prompt and input images before trying again.";
+	}
+	return "Codex could not complete the image request.";
+}
+
+export async function httpFailure(response: Response, signal: AbortSignal): Promise<{ message: string; retry: boolean }> {
+	if (response.headers.get("cf-mitigated") === "challenge") {
+		void response.body?.cancel().catch(() => undefined);
+		return { message: "Codex connection was challenged by Cloudflare. This does not establish model or subscription availability.", retry: false };
+	}
+	let body = "";
+	try {
+		const decoder = new TextDecoder();
+		for await (const chunk of chunks(response, MAX_ERROR_BYTES, signal)) body += decoder.decode(chunk, { stream: true });
+		body += decoder.decode();
+	} catch {
+		signal.throwIfAborted();
+		// A large or unreadable error body is deliberately not exposed.
+	}
+	let error: Record<string, unknown> = {};
+	try {
+		error = object(object(JSON.parse(body)).error);
+	} catch { /* HTML and other non-JSON error bodies are not diagnostics. */ }
+	const terminal = isQuota(error)
+		|| error.code === "moderation_blocked" || error.type === "image_generation_user_error";
+	const hint = response.status === 401
+		? "Codex login was rejected. Run /login for openai-codex again."
+		: response.status === 403
+			? "Codex access was denied. This can be a connection or account restriction; it does not identify the image model."
+			: errorHint(error);
+	return {
+		message: `Codex image request failed (HTTP ${response.status}). ${hint}`,
+		retry: !terminal && [429, 500, 502, 503, 504].includes(response.status),
+	};
+}
+
+function reportedImage(item: Record<string, unknown>, secrets: string[]): ReportedImage {
+	const reported: ReportedImage = {};
+	const model = item.model;
+	if (typeof model === "string" && /^gpt-image-[a-z0-9.-]{1,80}$/.test(model)
+		&& !secrets.some(secret => secret && model.includes(secret))) reported.model = model;
+	if (typeof item.size === "string" && /^[1-9]\d{0,4}x[1-9]\d{0,4}$/.test(item.size)) reported.size = item.size;
+	if (typeof item.quality === "string" && ["low", "medium", "high", "xhigh", "max", "auto"].includes(item.quality)) reported.quality = item.quality;
+	if (typeof item.background === "string" && ["transparent", "opaque", "auto"].includes(item.background)) reported.background = item.background;
+	if (typeof item.output_format === "string" && ["png", "jpeg", "webp"].includes(item.output_format)) reported.outputFormat = item.output_format;
+	return reported;
+}
+
+export async function parseCodexSse(
+	response: Response,
+	signal: AbortSignal,
+	secrets: string[],
+	onProgress?: (stage: string) => void,
+): Promise<ParsedCodexResponse> {
+	const parsed: ParsedCodexResponse = { text: [] };
+	let completed = false;
+	let textChars = 0;
+	let lastStage: string | undefined;
+	const image = (value: unknown) => {
+		const item = object(value);
+		if (item.type !== "image_generation_call") return;
+		if (parsed.image) throw new Error("Codex returned more than one image. No automatic retry was made.");
+		if (item.status !== "completed") throw new Error("Codex image generation did not complete.");
+		if (typeof item.result !== "string" || !item.result) throw new Error("Codex image_generation_call did not contain image data.");
+		if (item.result.length > Math.ceil(MAX_IMAGE_BYTES / 3) * 4) throw new Error("Codex image exceeded the 32 MiB size limit.");
+		parsed.image = {
+			id: identifier(item.id, secrets) ?? "image_generation",
+			status: "completed",
+			result: item.result,
+			revisedPrompt: text(item.revised_prompt, secrets) || undefined,
+			reported: reportedImage(item, secrets),
+		};
+	};
+	const handle = (frame: string) => {
+		const data = frame.split(/\r?\n/).filter(line => line.startsWith("data:")).map(line => line.slice(5).trim()).join("\n");
+		if (!data || data === "[DONE]") return;
+		let event: Record<string, unknown>;
+		try { event = object(JSON.parse(data)); }
+		catch { throw new Error("Codex returned an invalid stream event. No automatic retry was made."); }
+		switch (event.type) {
+			case "error":
+			case "response.failed":
+				throw new Error(errorHint(object(event.response).error ?? event.error ?? event));
+			case "response.incomplete":
+				throw new Error("Codex response was incomplete. No automatic retry was made.");
+			case "response.created":
+				parsed.responseId = identifier(object(event.response).id, secrets);
+				break;
+			case "response.output_text.delta":
+				if (typeof event.delta === "string" && textChars < MAX_TEXT_CHARS) {
+					const delta = event.delta.slice(0, MAX_TEXT_CHARS - textChars);
+					parsed.text.push(delta);
+					textChars += delta.length;
+				}
+				break;
+			case "response.output_item.done":
+				image(event.item);
+				break;
+			case "response.completed": {
+				const final = object(event.response);
+				parsed.responseId = identifier(final.id, secrets) ?? parsed.responseId;
+				// Usage contains numeric counters only; never persist arbitrary response objects.
+				const usage = object(final.usage);
+				const counters: Record<string, unknown> = Object.fromEntries(
+					["input_tokens", "output_tokens", "total_tokens"].flatMap(key =>
+						typeof usage[key] === "number" && Number.isFinite(usage[key]) && usage[key] >= 0
+							? [[key, usage[key]]] : []),
+				);
+				for (const [key, fields] of [
+					["input_tokens_details", ["cached_tokens"]],
+					["output_tokens_details", ["reasoning_tokens"]],
+				] as const) {
+					const values = object(usage[key]);
+					const details = Object.fromEntries(fields.flatMap(field =>
+						typeof values[field] === "number" && Number.isFinite(values[field]) && values[field] >= 0
+							? [[field, values[field]]] : []));
+					if (Object.keys(details).length) counters[key] = details;
+				}
+				if (Object.keys(counters).length) parsed.usage = counters;
+				if (!parsed.image && Array.isArray(final.output)) final.output.forEach(image);
+				completed = true;
+				break;
+			}
+			case "response.image_generation_call.in_progress":
+			case "response.image_generation_call.generating":
+			case "response.image_generation_call.completed":
+				if (event.type !== lastStage) {
+					lastStage = event.type;
+					onProgress?.(event.type.split(".").at(-1)!);
+				}
+				break;
+		}
+	};
+	const decoder = new TextDecoder();
+	let buffer = "";
+	let scanFrom = 0;
+	for await (const chunk of chunks(response, MAX_RESPONSE_BYTES, signal)) {
+		buffer += decoder.decode(chunk, { stream: true });
+		const separator = /\r?\n\r?\n/g;
+		separator.lastIndex = scanFrom;
+		let match: RegExpExecArray | null;
+		while ((match = separator.exec(buffer))) {
+			handle(buffer.slice(0, match.index));
+			buffer = buffer.slice(match.index + match[0].length);
+			if (completed) break;
+			separator.lastIndex = 0;
+		}
+		if (completed) break;
+		scanFrom = Math.max(0, buffer.length - 3);
+	}
+	if (!completed) {
+		buffer += decoder.decode();
+		if (buffer.trim()) handle(buffer);
+	}
+	if (!completed) throw new Error("Codex stream ended before completion. The backend may still finish; no automatic retry was made.");
+	parsed.text = [text(parsed.text.join(""), secrets)];
+	return parsed;
+}

package/src/install-telemetry.ts

@@ -1,12 +1,11 @@
 import { readFileSync } from "node:fs";
-import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { reportInstallTelemetry as report } from "@mocito/install-telemetry";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
 const PACKAGE_NAME = "pi-codex-image-gen";
-const INSTALL_TELEMETRY_URL = "https://mocito.dev/api/report-install";
-const INSTALL_TELEMETRY_TIMEOUT_MS = 5000;
+const INSTALL_TELEMETRY_ENDPOINT = "https://mocito.dev/api/report-install";
 const CI_ENVIRONMENT_VARIABLES = [
   "APPVEYOR",
   "BITBUCKET_BUILD_NUMBER",
@@ -24,10 +23,6 @@ const CI_ENVIRONMENT_VARIABLES = [
   "VERCEL",
 ];
 
-interface InstallTelemetryState {
-  lastReportedVersion?: string;
-}
-
 interface PiSettingsDocument {
   enableInstallTelemetry?: unknown;
 }
@@ -51,18 +46,15 @@ function isPresentEnvFlag(value: string | undefined): boolean {
   return normalized !== "0" && normalized !== "false" && normalized !== "no";
 }
 
-function isCiEnvironment(): boolean {
-  if (isTruthyEnvFlag(process.env.CI)) return true;
-  return CI_ENVIRONMENT_VARIABLES.some((name) => isPresentEnvFlag(process.env[name]));
-}
-
-function isInstallTelemetryEnabled(): boolean {
-  if (isCiEnvironment()) return false;
-  if (isTruthyEnvFlag(process.env.PI_OFFLINE)) return false;
-  if (process.env.PI_TELEMETRY !== undefined) return isTruthyEnvFlag(process.env.PI_TELEMETRY);
+export function isInstallTelemetryEnabled(env: NodeJS.ProcessEnv = process.env, settingsPath = join(getAgentDir(), "settings.json")): boolean {
+  if (isTruthyEnvFlag(env.CI)) return false;
+  if (CI_ENVIRONMENT_VARIABLES.some((name) => isPresentEnvFlag(env[name]))) return false;
+  if (isTruthyEnvFlag(env.PI_OFFLINE)) return false;
 
-  const settings = readJsonFile(join(getAgentDir(), "settings.json")) as PiSettingsDocument;
-  return settings.enableInstallTelemetry !== false;
+  const settings = readJsonFile(settingsPath) as PiSettingsDocument;
+  if (settings.enableInstallTelemetry === false) return false;
+  if (env.PI_TELEMETRY !== undefined) return isTruthyEnvFlag(env.PI_TELEMETRY);
+  return true;
 }
 
 function getPackageVersion(): string {
@@ -70,35 +62,16 @@ function getPackageVersion(): string {
   return typeof packageJson.version === "string" && packageJson.version.length > 0 ? packageJson.version : "0.0.0";
 }
 
-function getInstallTelemetryUserAgent(version: string): string {
-  const runtimeVersions = process.versions as NodeJS.ProcessVersions & { bun?: string };
-  const runtime = runtimeVersions.bun ? `bun/${runtimeVersions.bun}` : `node/${process.version}`;
-  return `${PACKAGE_NAME}/${version} (${process.platform}; ${runtime}; ${process.arch})`;
-}
-
-async function reportInstallTelemetryAsync(): Promise<void> {
+export function reportInstallTelemetry(): void {
   try {
-    if (!isInstallTelemetryEnabled()) return;
-
-    const version = getPackageVersion();
-    const extensionsDir = join(getAgentDir(), "extensions");
-    const statePath = join(extensionsDir, "pi-codex-image-gen-install.json");
-    const state = readJsonFile(statePath) as InstallTelemetryState;
-    if (state.lastReportedVersion === version) return;
-
-    await mkdir(extensionsDir, { recursive: true });
-    await writeFile(statePath, `${JSON.stringify({ lastReportedVersion: version }, null, 2)}\n`, "utf8");
-
-    const params = new URLSearchParams({ tool: PACKAGE_NAME, version });
-    await fetch(`${INSTALL_TELEMETRY_URL}?${params.toString()}`, {
-      headers: { "User-Agent": getInstallTelemetryUserAgent(version) },
-      signal: AbortSignal.timeout(INSTALL_TELEMETRY_TIMEOUT_MS),
-    });
+    void report({
+      endpoint: INSTALL_TELEMETRY_ENDPOINT,
+      tool: PACKAGE_NAME,
+      version: getPackageVersion(),
+      statePath: join(getAgentDir(), "extensions", "pi-codex-image-gen-install.json"),
+      enabled: isInstallTelemetryEnabled(),
+    }).catch(() => undefined);
   } catch {
-    // Best-effort telemetry: ignore settings, filesystem, and network failures.
+    // Best-effort telemetry: ignore local policy and filesystem failures.
   }
 }
-
-export function reportInstallTelemetry(): void {
-  void reportInstallTelemetryAsync();
-}