Codex request parity checklist (CL-5168)

docs/plans/codex-request-parity-checklist.md

@@ -0,0 +1,90 @@
+# Codex request parity checklist (CL-5168)
+
+**Status:** spike artifact — docs only; no production change in this issue  
+**Sources:** Corbits `src/provider/codex-responses-adapter.ts` `buildRequest`; openai/codex public Responses usage; nanocodex (gakonst) as lean-client reference; plan notes in Linear project *Codex / GPT adapter efficiency* (companion plan may live as untracked `docs/plans/codex-adapter-enhancements.md` on a local tree — not required to read this checklist)  
+**Statuses (exactly one per row):** `already_match` · `safe_to_add` · `backend_rejected` · `unknown` · `intentionally_different`
+
+Corbits target: ChatGPT Codex backend (`chatgpt.com/backend-api/codex/responses`), **not** platform `api.openai.com`. Reference clients may target either surface; mark carefully. Peer-client columns are coarse spike sketches (`yes` / `varies` / `may use`) unless a path is cited — Corbits column is authoritative against `buildRequest`.
+
+---
+
+## Body fields
+
+| Field | Corbits today | openai/codex (ref) | nanocodex (ref) | Status | Notes |
+|---|---|---|---|---|---|
+| `model` | yes | yes | yes | already_match | Required |
+| `input` | full history each turn | full or chained | full or chained | already_match | Continuity via full replay + encrypted reasoning; no delta input yet |
+| `instructions` | pinned via `codexInstructions()` | official Codex prompt | often official or close | already_match | Corbits disk/bundled pin; product prompt is **not** here |
+| `store` | `false` | typically false for CLI | false | already_match | Backend requires off for encrypted reasoning path |
+| `stream` | `true` | true for interactive | true | already_match | |
+| `include` | `["reasoning.encrypted_content"]` | encrypted reasoning include | similar when supported | already_match | Round-trip signatures on thinking blocks |
+| `parallel_tool_calls` | `false` | varies | varies | intentionally_different | Spike later whether `true` is safe with Corbits tool runtime |
+| `tools` | flat Responses tools when present | yes | yes | already_match | |
+| `tool_choice` | `"auto"` when tools present | auto / none | auto | already_match | |
+| `reasoning.effort` | from `providerOptions.reasoning_effort` when string ≠ `"none"` | yes | yes | already_match | Mapping only; role defaults are product (CL-5162) |
+| `reasoning.summary` | `"auto"` when effort set | often auto | often auto | already_match | |
+| `prompt_cache_key` | Codex session id when present | session/cache key patterns | session-ish keys | already_match | Confirm vs best clients under load (measure later) |
+| `previous_response_id` | **omitted** | may use for continuity | may use | safe_to_add | **Only after PerfTrace attribution (CL-5167)** says payload/transport material; implement as CL-5161 |
+| `max_output_tokens` | **omitted** | often omitted on Codex backend | often omitted | backend_rejected | Corbits intentionally omits; backend rejects |
+| `generate` / warmup | **omitted** | some clients warmup | unknown | unknown | Spike only after attribution (CL-5172) |
+| Chat Completions fields (`messages`, `max_tokens`, …) | never | N/A | N/A | intentionally_different | Wrong protocol; must stay absent |
+| Free-form body extras | none | varies | varies | unknown | Backend rejects unknown fields aggressively — add only with live probe |
+
+---
+
+## Headers
+
+| Header | Corbits today | openai/codex (ref) | nanocodex (ref) | Status | Notes |
+|---|---|---|---|---|---|
+| `content-type` | `application/json` | yes | yes | already_match | |
+| `accept` | `text/event-stream` | SSE | SSE or WS | already_match | HTTP SSE path only today |
+| `authorization` | bearer sentinel → harness injects token | bearer | bearer | already_match | |
+| `openai-beta` | `responses=experimental` | responses experimental | similar | already_match | |
+| `originator` | `codex_cli_rs` (from authorize extras) | codex_cli_rs | may differ | already_match | Match official CLI identity |
+| `chatgpt-account-id` | when account present | required for subscription | when available | already_match | From tokens / providerOptions |
+| `session_id` | when session id present | session headers | session-ish | already_match | Paired with `prompt_cache_key` |
+| WebSocket upgrade / WS protocol headers | none | if WS client | if WS client | unknown | No WS in Corbits; spike is CL-5164, gated by CL-5167 attribution |
+| Extra product headers | none | product-specific | lean | unknown | Do not invent without backend proof |
+
+---
+
+## Input item types (Corbits)
+
+| Item type | Corbits | Status | Notes |
+|---|---|---|---|
+| `message` (user/assistant/system/developer) | yes; product system → leading `developer` bridge | intentionally_different | Bridge is product-correct, not a parity bug |
+| `function_call` | yes | already_match | |
+| `function_call_output` | yes | already_match | |
+| `reasoning` + `encrypted_content` | yes (signature round-trip) | already_match | Thinking without signature is not re-sent |
+| Image parts | yes (`input_image`) | already_match | |
+
+---
+
+## Transport
+
+| Capability | Corbits | Status | Notes |
+|---|---|---|---|
+| HTTP POST + SSE | yes | already_match | |
+| WebSocket | no | unknown | Gated by CL-5167; spike CL-5164 |
+| `previous_response_id` chaining | no | safe_to_add | Gated by CL-5167; implement CL-5161 |
+| Connection warmup | no | unknown | Gated by CL-5167; spike CL-5172 |
+
+---
+
+## Recommended follow-ups (do not implement in CL-5168)
+
+1. **Measure first** — PerfTrace attribution (CL-5167) before transport bets  
+2. **Body key snapshot tests** — lock allowlist so Chat Completions fields cannot leak  
+3. **`parallel_tool_calls: true` live spike** — only with tool-runtime safety review  
+4. **`previous_response_id` / WS / warmup** — only if CL-5167 shows transport share is material  
+
+---
+
+## Field count
+
+- Body rows: 17  
+- Header rows: 9  
+- Input item rows: 5  
+- Transport rows: 4  
+
+**Production code changed in this issue:** none.