fix(openai-codex): support GPT-5.6 Luna Responses Lite

[taltas]

Summary and root cause

Zoo Code already catalogs the exact model ID gpt-5.6-luna, but ChatGPT OAuth requests to that model failed because Luna expects the Responses Lite request contract rather than the normal Responses request used by the OpenAI Codex provider. The standard request body and headers were therefore incompatible with Luna.

This change detects only the exact gpt-5.6-luna model on the ChatGPT OAuth Codex path, transforms the outgoing body into the Responses Lite-compatible shape, and adds the Luna-only headers required for routing, affinity, and prompt caching. Non-Luna requests continue using the existing standard Responses contract.

The initial request referred to “5.5 Luna.” However, upstream anomalyco/opencode#36685, its corresponding commit, and Zoo Code's existing model catalog identify the model as gpt-5.6-luna. Exact equality is intentional: this does not change GPT-5.5, Sol, Terra, model aliases, API-key providers, or any other transport.

Request handling

For exact-model Luna requests, the provider now:

• transforms the normal Responses request body into the Responses Lite-compatible body before sending it;
• preserves the existing conversation input, instructions, tools, tool choice, reasoning configuration, and streaming intent while applying the Luna-specific request contract;
• supplies the Luna-only session-id and x-session-affinity headers in addition to the existing Codex session_id header;
• reuses the same provider-local session value as prompt_cache_key so request affinity and prompt caching remain stable;
• applies the same transformation and headers to SDK streaming and the direct SSE fallback;
• retains the transformed body and Luna headers when the provider refreshes authentication and retries after an auth failure; and
• applies the same Luna contract to completePrompt, keeping one-shot completion behavior aligned with streaming behavior.

flowchart LR
    subgraph Before[Before]
        B1[ChatGPT OAuth request] --> B2{Exact model gpt-5.6-luna?}
        B2 --> B3[Normal Responses body and headers]
        B3 --> B4[Luna rejects incompatible contract]
    end

    subgraph After[After]
        A1[ChatGPT OAuth request] --> A2{Exact model gpt-5.6-luna?}
        A2 -- No --> A3[Existing normal Responses path]
        A2 -- Yes --> A4[Transform to Responses Lite body]
        A4 --> A5[Add Luna-only session and affinity headers]
        A5 --> A6[SDK streaming, SSE fallback, auth retry, or completePrompt]
        A6 --> A7[Luna request succeeds]
    end

Loading

taskId and provider session boundary

No core task ID was removed, replaced, regenerated, or mutated.

Before this change, request metadata taskId was already used only inside this provider as the Codex session_id header. The provider now resolves that value once into a provider-local effectiveSessionId, using the handler UUID only as a fallback when request metadata does not supply a taskId. That single provider-local value is then reused consistently for:

• session_id;
• session-id;
• x-session-affinity; and
• prompt_cache_key.

Core task execution, tool dispatch, subtask routing, persistence, and task lookup remain unchanged. The provider consumes core metadata to derive transport metadata; it does not write a provider session value back into core task state.

flowchart LR
    subgraph Core[Core task domain]
        T[Existing taskId]
        E[Task execution]
        D[Tool and subtask dispatch]
        P[Persistence and lookup]
        T --> E
        T --> D
        T --> P
    end

    subgraph Provider[OpenAI Codex provider boundary]
        M[Read request metadata taskId]
        F[Fallback: handler UUID]
        S[Resolve effectiveSessionId once]
        H[session_id / session-id / x-session-affinity]
        C[prompt_cache_key]
        M --> S
        F --> S
        S --> H
        S --> C
    end

    T -- read-only metadata --> M
    S -. no mutation or write-back .-> T

Loading

Scope and non-goals

• Limited to exact gpt-5.6-luna requests through the ChatGPT OAuth OpenAI Codex provider.
• No behavior changes for GPT-5.5, Sol, Terra, aliases, API-key providers, or other transports.
• No changes to core task identity or lifecycle behavior.
• No WebSocket implementation is included because Zoo Code has no Codex WebSocket path; this change covers the provider's existing SDK streaming, SSE fallback, retry, and completion paths.

Tests and verification

• Focused Vitest: 35 tests across 2 files passed.
• src type check passed.
• src lint passed.
• Repository lint passed: 11 tasks.
• Diff check passed.
• The only reported environment issue was a Node version warning; it did not affect the successful checks above.

References

• Upstream PR: fix(opencode): support Luna Responses Lite over OAuth anomalyco/opencode#36685
• Upstream commit: anomalyco/opencode@67aa9ce
• Detailed analysis: docs/luna-responses-lite-analysis.md

Summary by CodeRabbit

• New Features

  • Added support for the gpt-5.6-luna model through Responses Lite request handling.
  • Preserved consistent session and authentication behavior across streaming, fallback, retry, and non-streaming requests.
  • Maintained existing behavior for other models.

• Documentation

  • Added compatibility guidance, request requirements, verification steps, and acceptance criteria for Luna support.

• Tests

  • Expanded coverage for request formatting, headers, session handling, retries, fallback requests, and non-Luna behavior.

[coderabbitai]

📝 Walkthrough

Walkthrough

The Codex provider now supports GPT-5.6 Luna Responses Lite requests through exact model gating, body transformation, session-aware headers, consistent streaming/fallback handling, and completePrompt() integration. Tests cover transformation rules, retries, non-Luna behavior, and request invariants.

Changes

Luna Responses Lite support

Layer / File(s)	Summary
Compatibility contract and implementation scope docs/luna-responses-lite-analysis.md	Documents Luna request transformation, session resolution, headers, transport behavior, validation, tests, and acceptance criteria.
Luna request-body transformation src/api/providers/openai-codex.ts	Adds transformLunaResponsesLiteBody with validation, developer messages, image-detail removal, tool settings, reasoning context, and session-based cache keys.
Session-aware request flow and headers src/api/providers/openai-codex.ts	Propagates the effective session ID through streaming, SDK fallback, and completion requests, while centralizing Luna-specific headers.
Provider behavior coverage src/api/providers/__tests__/openai-codex.spec.ts, src/api/providers/__tests__/openai-codex-native-tool-calls.spec.ts	Adds coverage for transformation, fallback reuse, authentication retries, non-Luna isolation, disabled reasoning, and request/header invariants.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant OpenAiCodexHandler
  participant CodexSDK
  participant SSEEndpoint
  OpenAiCodexHandler->>OpenAiCodexHandler: Resolve session and transform Luna body
  OpenAiCodexHandler->>CodexSDK: Send transformed body and headers
  CodexSDK-->>OpenAiCodexHandler: Return stream or fail
  OpenAiCodexHandler->>SSEEndpoint: Retry with the same body and headers
  SSEEndpoint-->>OpenAiCodexHandler: Return SSE stream

Loading

Suggested labels: awaiting-review

Suggested reviewers: hannesrudolph, jamesrobert20, navedmerchant, p12tic, edelauna

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The PR is detailed and well structured, but it omits the required linked GitHub issue section.	Add a "Related GitHub Issue" section with a valid "Closes: #" link, then keep the summary, testing, and scope details.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and clearly describes the main change: adding GPT-5.6 Luna Responses Lite support.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/openai-codex-luna-responses-lite

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

❌ Patch coverage is 96.96970% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/api/providers/openai-codex.ts	96.96%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[coderabbitai]

🧹 Nitpick comments (1)

src/api/providers/__tests__/openai-codex.spec.ts (1)

339-339: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Hoist the Luna version string into a shared test constant. "0.144.0" is repeated in three assertions; centralizing it avoids updating multiple spots when the header version changes.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/api/providers/__tests__/openai-codex.spec.ts` at line 339, Define a
shared test constant for the Luna version near the other test fixtures in
openai-codex.spec.ts, then replace all three hardcoded "0.144.0" assertion
values with that constant. Keep the existing assertions and expected version
unchanged.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/api/providers/__tests__/openai-codex.spec.ts`:
- Line 339: Define a shared test constant for the Luna version near the other
test fixtures in openai-codex.spec.ts, then replace all three hardcoded
"0.144.0" assertion values with that constant. Keep the existing assertions and
expected version unchanged.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: c2922768-3277-4e17-9d7b-91f33bc97186

📥 Commits

Reviewing files that changed from the base of the PR and between 9e218a5 and ccdc706.

📒 Files selected for processing (4)

• docs/luna-responses-lite-analysis.md
• src/api/providers/__tests__/openai-codex-native-tool-calls.spec.ts
• src/api/providers/__tests__/openai-codex.spec.ts
• src/api/providers/openai-codex.ts

[taltas]

@zoomote please review this PR

[taltas]

@roomote please review