pi-codex-image-gen 0.1.12 → 0.1.13

package/CHANGELOG.md

@@ -1,13 +1,33 @@
 # 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]
 
+## [0.1.13] - 2026-09-11
+
+### Added
+
+- Report backend image metadata, generation stages, byte counts, and elapsed time without guessing the served image model.
+- Support Flare and Sunburst Images 2.5 API model IDs and their September 8 snapshots with `xhigh` and `max` CLI quality settings. Keep existing defaults.
+- Validate documented flexible dimensions for both 2.5 models and the GPT Image 2 dated snapshot in CLI generation, editing, and batch workflows.
+
+### Changed
+
+- Describe the Codex image model as backend-selected. Report its ID only if the backend supplies one; otherwise return `backendImageModel: "unknown"`.
+- Share install telemetry mechanics through `@mocito/install-telemetry` while preserving Pi-specific settings and state paths.
+
+### Fixed
+
+- Identify subscription requests with a Pi User-Agent and distinguish Cloudflare challenges from account/model failures.
+- Bound network time, streamed/error output, prompts, and input images; handle fragmented CRLF streams and incomplete results; avoid quota-error retries and accidental file overwrites.
+- Allow GPT Image 2 native transparency preview with PNG/WebP in the API CLI, and remove outdated older-model fallback requirements from skill guidance.
+- Let `enableInstallTelemetry: false` override an enabled `PI_TELEMETRY` environment flag.
+
+## [0.1.12] - 2026-07-17
+
 ### Added
 
 - Add native edits using up to five local or recent conversation images.

package/CONTRIBUTING.md

@@ -33,10 +33,39 @@ pi -e /path/to/pi-mono/packages/pi-codex-image-gen
 To validate the Python CLI fallback without an API key:
 
 ```bash
-python3 skills/imagegen/scripts/image_gen.py generate --prompt "Test" --out /tmp/test.png --dry-run
-python3 skills/imagegen/scripts/remove_chroma_key.py --help
+uv run --no-project python3 skills/imagegen/scripts/image_gen.py generate --prompt "Test" --model gpt-image-2.5-flare --quality max --dry-run
+uv run --no-project python3 skills/imagegen/scripts/image_gen.py generate --prompt "Test" --background transparent --output-format png --dry-run
+uv run --no-project python3 skills/imagegen/scripts/remove_chroma_key.py --help
 ```
 
+`npm test` requires Python 3 on PATH. CLI regression tests use only its standard library and make dry-run requests. Extension tests mock the backend; neither test path consumes image quota.
+
+The vendored CLI changes for Images 2.5 cover documented quality and flexible size settings plus GPT Image 2 transparency preview. They do not change API endpoints, authentication, or defaults.
+
+Optional live smoke test (requires explicit approval to use image quota): load this checkout with `pi -e`, generate one PNG, and edit it using `referencedImagePaths`. Verify inline display and saved bytes. Confirm that progress and the final summary do not invent an image model, and that `backendImageModel` is `"unknown"` unless the backend explicitly reports one. Verify `reportedImage` size/quality/background against the response, then inspect actual pixels for dimensions and alpha. A successful image does not prove which backend model ran. Never include credentials or raw image payloads in test reports.
+
+## Subscription capability check
+
+Checked on September 11, 2026, with a ChatGPT subscription token and no API-key billing. These observations are account- and date-specific, not a public API guarantee.
+
+- Installed Codex `0.153.4` and upstream commit `4dcce4f0c47e0183e4b05ffcbb38b4fffb8b8042` both use the standalone images client for image generation. Its model is hard-coded to `gpt-image-2`; background, size, and quality are automatic.
+- The request path is determined by subscription authentication: `https://chatgpt.com/backend-api/codex/images/generations` (or `images/edits`).
+- A bounded diagnostic using the direct route generated an image. The existing Responses route also generated an image. All six returned PNG files passed Pillow verification and decoding.
+- Requests naming Flare and Sunburst succeeded, but a deliberately invalid model name also succeeded. None reported a served model. Do not interpret HTTP 200 as proof of selectable models.
+- An explicit `1536x1024`, `high`, `transparent` direct request returned `1254x1254`, `low`, `opaque`. Pixel inspection confirmed RGB output without transparency. Do not add guaranteed controls based on the request schema alone.
+- GET diagnostics with the original Python client header returned a Cloudflare challenge. A package-specific Pi User-Agent reached method validation in the Python diagnostic. Cookie-free Node GET requests with the shipping headers reached the Responses route (405), but the direct route still returned a Cloudflare challenge (403). A User-Agent is not a universal challenge fix.
+- The successful live generation probes used a Codex-compatible diagnostic User-Agent, a model-list warmup, and an in-memory allowlisted infrastructure-cookie jar. These were compatibility probes, not a live run of the modified extension. The shipping extension keeps an honest Pi User-Agent and does not copy that cookie/warmup flow.
+- Model selection through the Responses tool, native transparency by prompting, and live editing were not established by this six-request check. Keep them separate from the proven baseline generation result.
+
+Source references:
+
+- [Installed Codex image tool](https://github.com/openai/codex/blob/rust-v0.153.4/codex-rs/ext/image-generation/src/tool.rs)
+- [Subscription base URL selection](https://github.com/openai/codex/blob/4dcce4f0c47e0183e4b05ffcbb38b4fffb8b8042/codex-rs/model-provider-info/src/lib.rs)
+- [Images endpoint client](https://github.com/openai/codex/blob/4dcce4f0c47e0183e4b05ffcbb38b4fffb8b8042/codex-rs/codex-api/src/endpoint/images.rs)
+- [Codex client headers](https://github.com/openai/codex/blob/4dcce4f0c47e0183e4b05ffcbb38b4fffb8b8042/codex-rs/login/src/auth/default_client.rs)
+
+Future probes should use a known-working control, one changed setting at a time, an invalid-model control for selection claims, and decoded output checks. Obtain a generation budget first, bound time/response sizes, disable automatic retries, and record only sanitized metadata. Do not repeat an ambiguous failed generation automatically.
+
 ## Pull request checklist
 
 Before opening a pull request:
@@ -53,7 +82,7 @@ Before opening a pull request:
 - When changing tool parameters, update both the Typebox `TOOL_PARAMS` schema and the `promptGuidelines` strings — Pi surfaces both to the model.
 - Treat save-mode names, config file keys, and auth flow as public interface; changes to defaults or precedence are breaking changes.
 - Do not modify `skills/imagegen/scripts/image_gen.py` without a documented reason; it is a vendored fallback.
-- The Codex Responses SSE contract is undocumented and may change. If generation breaks, log raw events before assuming a code bug.
+- The Codex Responses SSE contract is private and may change. If generation breaks, inspect sanitized event types, status codes, and allowlisted output metadata. Never log raw response bodies or auth headers.
 - Avoid requiring `OPENAI_API_KEY` for the normal Pi tool path; auth piggybacks on Pi's `openai-codex` login.
 
 ## Code of conduct

package/README.md

@@ -1,6 +1,15 @@
 # pi-codex-image-gen
 
-Image generation and editing for [Pi](https://pi.dev) using the ChatGPT Images 2.0 model via the OpenAI Codex Responses backend.
+Create and edit images without leaving [Pi](https://pi.dev).
+
+`pi-codex-image-gen` turns natural-language requests and reference images into PNG, JPEG, or WebP assets through **Codex image generation**, using your existing ChatGPT Codex login instead of a separate API key.
+
+## Features
+
+- **Generate images in conversation** — describe the asset you need and let Pi create it.
+- **Edit from references** — transform up to five local or recent conversation images.
+- **Save where work happens** — return images inline or organize them by project, session, or custom directory.
+- **No separate API setup** — reuse your existing ChatGPT Plus/Pro Codex authentication.
 
 ## Install
 
@@ -34,7 +43,29 @@ 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, 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.
+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, not the image model. The backend selects the image model; `backendImageModel` is `"unknown"` unless the response explicitly reports an image model.
+
+The tool reports generation stages and the backend's returned size, quality, background, and format in `details.reportedImage`. These are server-reported values, not guarantees inferred from the prompt. `details.byteCount` records decoded bytes; `details.generationDurationMs` records elapsed generation/save time. Check the actual image before using it, especially for exact dimensions or alpha transparency.
+
+### Subscription reliability and limits
+
+- Requests identify this package with a Pi User-Agent. There is no Codex impersonation, browser-cookie import, or paid API fallback.
+- One five-minute network deadline covers the connection, retries, and stream. Escape cancels network work; the remote generation may still finish.
+- Prompts: 32,000 characters. References: five regular PNG/JPEG/WebP files or conversation images, at most 20 MiB each and 50 MiB combined.
+- Responses: 100 MiB total, with at most one 32 MiB decoded output image. Base64 and format signatures are checked; this is not a full image decoder. Backend text and revised prompts are limited to 4,000 characters; HTTP error bodies are read only up to 16 KiB and are not displayed.
+- Transient HTTP failures have bounded retries. Quota exhaustion, moderation errors, failed/incomplete streams, connection errors, and deadlines are not automatically retried. Avoid immediately repeating an ambiguous failure: the first generation may have consumed quota.
+- Local save settings are checked before generation. Existing files are never overwritten; a save failure still returns the inline image and a warning.
+- Cloudflare challenges are reported as connection failures, not as proof that your subscription or image model is unsupported.
+
+### Images 2.5 and API fallback
+
+The optional `skills/imagegen/scripts/image_gen.py` API CLI accepts `--model gpt-image-2.5-flare` or `--model gpt-image-2.5-sunburst`, including their `2026-09-08` snapshots. Both accept `--quality xhigh` and `--quality max` in addition to the existing quality settings. The CLI default remains `gpt-image-2`. Both 2.5 models support `--size auto` and custom dimensions such as `1536x864`, under the [documented size constraints](skills/imagegen/references/image-api.md#flexible-sizes-gpt-image-2-and-25). Resolutions above `2560x1440` are experimental.
+
+GPT Image 2 now supports native transparency in preview: use `--model gpt-image-2 --background transparent --output-format png` (or `webp`) in confirmed CLI mode. This uses `OPENAI_API_KEY` and separate API billing. The Pi tool still uses chroma-key removal because it has no background parameter.
+
+Public API model selection does not establish support for the same options on the private Codex backend. The extension does not expose Flare/Sunburst selection or claim that your account has received the Images 2.5 rollout.
+
+In subscription tests on September 11, 2026, the direct endpoint accepted Flare, Sunburst, and an invalid model name without reporting a served model. It also returned different size, quality, and background values than requested. The Responses route generated an image successfully. These account-specific results do not justify a guaranteed subscription model selector. See [the investigation and test procedure](CONTRIBUTING.md#subscription-capability-check).
 
 ## Authentication
 
@@ -71,7 +102,7 @@ Project config overrides global config only when project trust is active. If pro
 | --------- | ------ | ---------- | ---------------------------------------- |
 | `save`    | string | `"global"` | Default save mode (see below).           |
 | `saveDir` | string | —          | Directory used when `save=custom`.       |
-| `model`   | string | `"gpt-5.5"`| Codex routing model. Image generation is always handled by gpt-image-2. |
+| `model`   | string | `"gpt-5.5"`| Codex routing model, not the backend image model. |
 
 ### Environment variables
 
@@ -108,7 +139,7 @@ Project config overrides global config only when project trust is active. If pro
 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. 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.
+4. The backend selects an image model 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).

package/SECURITY.md

@@ -22,3 +22,11 @@ The maintainer will acknowledge reports as soon as practical and coordinate disc
 `pi-codex-image-gen` is a Pi package. Pi extensions execute with the same permissions as the local user running Pi. Users should review installed Pi packages and only install packages from sources they trust.
 
 The extension uses Pi's existing `openai-codex` login to obtain a short-lived JWT. The token is used only for requests to the Codex Responses API and is never written to disk or logged. Do not commit API keys, tokens, or decoded JWT payloads.
+
+Subscription requests use the fixed HTTPS `chatgpt.com/backend-api/codex/responses` endpoint with normal TLS validation, an honest package User-Agent, and redirects disabled. The extension does not import browser cookies, change authentication, or switch to API-key billing. Only backend-reported image metadata and allowlisted numeric usage counters are retained; raw HTTP error bodies are not shown. Known request credentials are redacted from backend text.
+
+Network work has a five-minute deadline and a 100 MiB response bound. Output images are limited to 32 MiB; input images must be regular files and are limited to 20 MiB each and 50 MiB in total. Image checks validate base64 and format signatures, not all image internals. Treat images as untrusted content when opening them in other software.
+
+Generated files are created exclusively with user-only permissions. A repeated backend ID or existing destination produces a save warning rather than overwriting that file. Cancellation and stream failures do not trigger automatic generation retries because the remote operation may already have consumed quota.
+
+At startup, `@mocito/install-telemetry` sends a best-effort install/update ping to the configured telemetry endpoint once per package version unless CI, Pi offline/telemetry settings, or `enableInstallTelemetry: false` disables it. It contains only the package name/version and parsed platform/runtime/architecture; it does not include prompts, file paths, configuration values, credentials, or provider responses.