--- id: PX-SPEC-CX7Q4N2V type: spec title: Codex Subscription Capabilities --- ## Intent Expose Codex subscription capabilities inside Pi without requiring separately billed API access. Image generation and editing are the first required capabilities, not the limit of the extension's purpose. Preserve normal Pi workflows instead of requiring a switch to the Codex application. ## Scope - Discover capability support, account access, and actionable blockers without claiming that authentication proves entitlement. - Generate images from text; edit images using supplied references and instructions. - Make supported operations callable by Pi's agent, codemode workflows, and configured PiPi children. - Return usable image artifacts and truthful operation status in the requesting session. - Admit additional subscription capabilities only when their behavior and access route are verified and explicitly scoped. Out: general Codex client replacement, speculative feature parity, unrelated chat-provider changes, classifier access inferred from a Codex subscription, automatic paid fallback. No new dashboard or custom visual interface is required. ## Behavior Capability discovery distinguishes known support from account access and successful execution. ```mermaid flowchart TB discover["Discover subscription capabilities"] --> support{"Supported integration route?"} support -->|no| unsupported["Report unsupported capability"] support -->|unknown| unknown["Report access or compatibility unverified"] support -->|yes| auth{"Subscription authentication available?"} auth -->|no| login["Explain authentication requirement"] auth -->|yes| access{"Account access known?"} access -->|blocked| blocked["Explain entitlement or quota blocker"] access -->|"allowed or unverified"| request["Explicit operation request"] request --> run["Execute through subscription route"] run -->|success| artifact["Return image artifacts and provenance"] run -->|failure| failure["Return actionable failure without paid fallback"] run -->|cancelled| cancelled["Report cancellation and any known upstream outcome"] ``` ### Access and billing Reuse the user's existing Pi Codex sign-in where supported; explain any additional required authentication before execution. Do not extract browser cookies, expose credentials, bypass account restrictions, or represent unsupported access as supported. Distinguish subscription usage from API billing, free generation, and unknown usage. Explain before execution that image operations consume subscription allowance; show remaining limits or usage only when upstream supplies them reliably. Never silently use OpenRouter, API-key billing, purchased credits beyond an approved spending boundary, or another provider. If upstream can automatically consume purchased credits and that boundary cannot be enforced, disclose the limitation and require explicit approval before execution. Capability discovery must not generate images or otherwise spend generation allowance merely to test access. ### Image operations Accept text prompts and reference images for generation or editing, subject to verified upstream limits. Report unsupported options before execution when locally knowable; otherwise preserve the upstream rejection. Return generated images in a form Pi and the requesting agent can inspect and reuse, with format and artifact references. Persist artifacts only within the caller-authorized output destination; avoid overwriting existing files without approval. Associate results with their originating request and session, including concurrent PiPi requests. Do not claim successful editing merely because an image was returned; preserve requested constraints for subsequent inspection. ### Lifecycle and failure Expose pending, completed, failed, and cancelled outcomes without presenting acknowledgment as completion. Keep Pi responsive while operations run and support cancellation. Cancellation must distinguish local cancellation from confirmed upstream cancellation; never promise refunded allowance. Authentication expiry, unavailable entitlement, exhausted quota, rate limiting, incompatible upstream behavior, and network failure produce actionable errors. Do not automatically retry a generation whose upstream completion is unknown, because a retry may duplicate consumption. Keep partial results distinguishable from complete results. Diagnostic failures remain nonfatal and never leak prompts, reference images, or credentials through default logging. ## Constraints Follow the repository's root installation unit, isolated-extension, settings, and diagnostics contracts. Do not require modifications to Pi core or other installed extensions to provide the declared behavior. Prefer existing Pi interaction and artifact conventions; no parallel credential store or silent user-config edits. A published Codex feature is evidence of product support, not proof that Pi can invoke it through subscription authentication. Unsupported capabilities remain explicitly unsupported rather than being emulated through separately billed services. ## Acceptance criteria - [ ] A user with eligible Codex subscription access can generate an image from Pi without an OpenRouter key or separately billed OpenAI API key. - [ ] The same user can supply a reference image and request an edit; resulting artifacts are inspectable and reusable inside Pi. - [ ] Agent invocation, codemode orchestration, and a configured PiPi child can each request the supported image operation and receive its own result. - [ ] Concurrent requests retain correct session/result ownership; cancellation of one request does not cancel unrelated work. - [ ] Missing authentication, unknown account access, confirmed entitlement failure, quota exhaustion, and unsupported capabilities remain distinguishable. - [ ] Discovery performs no generation; catalog presence or sign-in alone never appears as confirmed operation access. - [ ] Subscription consumption is disclosed; unavailable usage figures are labeled unknown, never reported as zero. - [ ] No rejected, cancelled, timed-out, or unsupported request silently falls back to paid API access or an unapproved credit charge. - [ ] Cancellation and ambiguous upstream completion remain truthful, with no automatic duplicate generation. - [ ] Existing output files and unrelated user configuration remain unchanged without explicit approval. - [ ] Additional capabilities are advertised only after verified subscription-backed operation, with declared inputs, outputs, limits, and failure behavior. - [ ] Unsupported upstream integration blocks acceptance of the affected capability rather than weakening the subscription-backed requirement. ## Evidence and unresolved questions [Codex image generation documentation](https://developers.openai.com/codex/image-generation) describes built-in generation/editing, reference images, and subscription-limit consumption. [Codex pricing](https://developers.openai.com/codex/pricing) excludes image generation from the Free plan and distinguishes subscription limits from API-key billing. Installed Pi documentation currently exposes image generation through OpenRouter; this session's image catalog contains no Codex subscription-backed generator. These observations establish the user-facing gap, not implementation feasibility. Before implementation commitments, establish the permitted subscription integration route, supported account plans, authentication reuse, artifact handling, cancellation semantics, and purchased-credit boundaries. The inventory of subscription capabilities beyond image generation/editing remains open; no additional capability is promised by this spec.