pi-codex-image-gen 0.1.12 → 0.1.14

package/CHANGELOG.md

@@ -1,13 +1,45 @@
 # 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.14] - 2026-10-02
+
+### Added
+
+- Add package-owned ChatGPT image OAuth through `/login codex-images`, with Pi-managed credential storage and refresh. Keep chat on any provider, including `openai`, without installing Codex or importing Pi's legacy OAuth helpers.
+
+### Fixed
+
+- Keep image authentication separate from the unsupported `openai` plan-sharing image route. Preserve available legacy Pi `openai-codex` credentials as a fallback when package-owned image credentials are absent.
+- Keep OAuth refresh errors private and avoid switching accounts after a selected OAuth failure.
+- Keep manual-login guidance visible when the local callback port is occupied.
+
+## [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

@@ -22,7 +22,7 @@ pi install -l /path/to/pi-mono/packages/pi-codex-image-gen
 pi
 ```
 
-Then run `/login` for `openai-codex` and ask Pi to generate an image.
+With Pi 0.85.1 or later, run `/login codex-images`, complete the ChatGPT browser login, and ask Pi to generate an image. Chat can stay on `openai` OAuth. Neither the Codex app nor Pi's legacy OAuth helpers are required.
 
 For a one-off run without changing settings:
 
@@ -33,10 +33,47 @@ 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.
+
+For auth compatibility, run the smoke test with `/login codex-images` while chat uses `openai` OAuth. Verify the provider appears in `/login`, not `/model`, and that Pi persists the image credential under its own ID. Check `details.provider: "codex-images"` and `details.transport: "codex-responses"`. If legacy Pi `openai-codex` is available, test it separately without owned image credentials; it should report `openai-codex` / `codex-responses`. With both logins, owned image OAuth wins. A selected auth failure must not switch accounts. With only chat OAuth or an API key, the tool must ask for `/login codex-images` before any image request.
+
+Test `/logout codex-images` without changing the chat login. On a remote/headless machine, test the full-redirect-URL fallback and callback-port conflicts. Never paste a callback into chat. Automated tests exercise actual provider registration, Pi login/storage/logout, PKCE/state, loopback/manual callbacks, cancellation, concurrent refresh, and image tool wiring using mocked token/image responses. They do not prove that a fresh live browser grant or a particular account supports the image endpoint.
+
+On October 2, 2026, the maintainer reported that the package-owned flow worked in a live smoke test. This is a user-confirmed result, not automated verification of every account or of the served image model.
+
+On October 2, 2026, live diagnostics with new `openai` plan-sharing OAuth rejected Responses image tools with `subscription_sharing_unsupported_capability`, and direct Images calls with `hardened_oauth_rule_missing`. OpenAI's [preview limitations](https://developers.openai.com/siwc/token-sharing-open-source/preview-limitations) list image generation as unsupported. The same chat grant could call a local image function; separate image-capable Codex OAuth produced verified PNGs through both native Images and Codex Responses endpoints. These probes established the grant distinction, not a live test of this package-owned browser login.
+
+## 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,8 +90,8 @@ 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.
-- Avoid requiring `OPENAI_API_KEY` for the normal Pi tool path; auth piggybacks on Pi's `openai-codex` login.
+- 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.
+- Keep the Pi tool subscription-only: prefer package-owned `codex-images` OAuth, preserve available legacy Pi `openai-codex` support, and never use the `openai` chat token, Codex app credentials, or `OPENAI_API_KEY` for tool requests.
 
 ## 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 **ChatGPT subscription image generation**. Sign in from Pi; no Codex app or separate API key is required.
+
+## 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.
+- **Separate image login** — keep Pi chat on `openai` OAuth while the extension handles image authentication.
 
 ## Install
 
@@ -34,17 +43,47 @@ 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. The image login uses the Codex-compatible public OAuth client; it does not launch the Codex app, read its credentials, import browser cookies, or fall back to paid API calls.
+- 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
 
-Uses your existing **openai-codex** login — no `OPENAI_API_KEY` required. If you haven't logged in yet:
+The extension owns an image-capable ChatGPT OAuth flow, registered as **Codex Images** (`codex-images`). Pi stores its credentials and handles refresh. Your chat provider can remain `openai`; image authentication is independent.
 
 ```
-> /login
+> /login codex-images
 ```
 
-Select **ChatGPT Plus/Pro (Codex)** and complete the OAuth flow.
+Complete the browser login with your ChatGPT account. You can also run `/login` and select **Codex Images (ChatGPT subscription)**. The browser redirects to `http://localhost:1455/auth/callback`. If the callback cannot reach Pi, paste the **full redirect URL** into Pi's login prompt, not into chat. Login expires after ten minutes.
+
+Use Pi 0.85.1 or later. Pi stores the `codex-images` credential in its agent auth store (normally `~/.pi/agent/auth.json`). `/logout codex-images` removes that credential without changing your chat login. No credential files are created by the extension itself.
+
+The package implements the Codex-compatible OAuth protocol itself. It neither imports Pi's `openai-codex` OAuth helpers nor requires the Codex app or its credential store. It still depends on OpenAI continuing to accept that public OAuth client and private image endpoint; this is not a new OAuth application registered with OpenAI.
+
+Existing Pi `openai-codex` credentials remain a compatibility fallback when `codex-images` credentials are absent and the legacy provider is available. With both image logins, `codex-images` wins. A selected login that fails to refresh or generate does not switch to another account.
+
+Both image logins use `https://chatgpt.com/backend-api/codex/responses`. Pi's new `openai` plan-sharing OAuth grant is different and [does not support image generation](https://developers.openai.com/siwc/token-sharing-open-source/preview-limitations). The extension never sends that chat token to the Codex backend. API keys do **not** enable this tool or API-key billing.
 
 ## Configuration
 
@@ -71,7 +110,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
 
@@ -105,10 +144,10 @@ Project config overrides global config only when project trust is active. If pro
 
 ## 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.
+1. Resolves package-owned `codex-images` OAuth via Pi, or falls back to available legacy Pi `openai-codex` OAuth.
+2. Sends a request to the Codex Responses endpoint and 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).
@@ -117,8 +156,8 @@ Project config overrides global config only when project trust is active. If pro
 
 | Symptom | Cause | Fix |
 | --- | --- | --- |
-| "Missing openai-codex credentials" | Not logged in | Run `/login` and select **ChatGPT Plus/Pro (Codex)** |
-| 401 / 403 response | Token expired | Re-run `/login` for openai-codex |
+| "Missing image OAuth credentials" | No image-capable subscription login; chat OAuth and API keys are not sufficient | Run `/login codex-images` |
+| 401 / 403 response | Image login rejected or token expired | Re-run `/login codex-images` |
 | 429 response | Rate limited | Wait and retry; the extension retries automatically with backoff |
 | "Codex did not return an image" | Backend refused the prompt | Rephrase the prompt and try again |
 | "save=custom requires saveDir" | Missing config | Set `saveDir` in config or `PI_CODEX_IMAGE_SAVE_DIR` env var |

package/SECURITY.md

@@ -21,4 +21,14 @@ 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.
+The extension implements image-capable ChatGPT OAuth under the provider ID `codex-images`, using the Codex-compatible public OAuth client ID (not a client secret). Pi stores access/refresh tokens in its agent credential store, normally `~/.pi/agent/auth.json`, and coordinates refresh. This is local credential persistence, not encrypted secret storage; protect the agent directory and do not commit it. The extension does not write its own credential files or access the Codex app's credential store. `/logout codex-images` removes only the image login. Existing legacy Pi `openai-codex` OAuth remains a fallback when package-owned credentials are absent; refresh or request failure does not switch accounts.
+
+Browser login uses random OAuth state and S256 PKCE. Its callback listener binds only to `127.0.0.1:1455`; the registered redirect URI is `http://localhost:1455/auth/callback`. Loopback HTTP is limited to this local callback. Automatic and pasted callbacks must have the expected origin, path, and state. Pasted input must be the full redirect URL, never a bare authorization code. Invalid callbacks cannot finish login. Listener cleanup runs on success, failure, and cancellation. Login has a ten-minute limit; token requests have a 30-second limit and 64 KiB response bound, with no retries or redirects. Do not paste login URLs into chat or log them.
+
+Authorization/token exchange uses fixed `auth.openai.com` HTTPS endpoints with normal TLS validation. Image requests use only `https://chatgpt.com/backend-api/codex/responses`, an honest package User-Agent, and disabled redirects. JWT account claims supply a validated routing header only; OpenAI authenticates the token. The extension does not import browser cookies, use the `openai` plan-sharing chat grant, or switch to API-key billing. Only backend-reported image metadata and allowlisted numeric usage counters are retained; token response bodies, HTTP error bodies, and raw auth-resolution errors are not shown. Known image 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.