codex-as-api 0.6.3__tar.gz → 0.6.4__tar.gz

{codex_as_api-0.6.3 → codex_as_api-0.6.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-as-api
-Version: 0.6.3
+Version: 0.6.4
 Summary: Use ChatGPT/Codex OAuth as a local OpenAI-compatible API server.
 Project-URL: Homepage, https://github.com/Eunho-J/codex-as-api
 Project-URL: Repository, https://github.com/Eunho-J/codex-as-api
@@ -49,7 +49,7 @@ Use ChatGPT / Codex OAuth as a local OpenAI-compatible API server.
 - **Tool calling** — function calls, tool results, and parallel tool calls
 - **Image support** — generation, inspection, multimodal Chat input, and capability-gated `original` image detail in classic Responses
 - **Reasoning** — configurable effort/context, `standard` mode compatibility, persisted reasoning, and streaming thinking content
-- **Codex features** — `prompt_cache_key`, process-local `response_id` continuation, subagent headers, and remote compaction
+- **Codex features** — session-aware `prompt_cache_key`, process-local Chat `response_id` continuation, subagent headers, and remote compaction
 - **Codex config aware** — reads `CODEX_HOME` / `~/.codex/config.toml` for model, reasoning-effort, and context-window settings
 - **Token estimate & compaction helpers** — Anthropic-compatible `/v1/messages/count_tokens` and `/v1/messages/compact`
 - **Auto auth** — reads `~/.codex/auth.json` and auto-refreshes OAuth tokens
@@ -310,13 +310,36 @@ curl -N http://localhost:18080/v1/messages \
   }'
 ```
 
+### Identifier and cache behavior
+
+The two compatibility facades intentionally use the similarly named fields for
+different jobs:
+
+| Input or output | `/v1/chat/completions` | `/v1/messages` |
+|---|---|---|
+| `client_metadata.session_id` | Forwarded to Codex, used as the default `prompt_cache_key`, and required when Codex metadata mode is enabled | Not used or forwarded |
+| `client_metadata.thread_id` | Codex metadata thread identity; defaults to `session_id` for a root request and preserves an explicit child thread | Not used or synthesized |
+| `prompt_cache_key` | Explicit value wins; otherwise a non-empty `client_metadata.session_id` is used; otherwise omitted | Optional proxy extension; explicit value wins, otherwise the Claude Code session header is hashed |
+| `x-claude-code-session-id` | Not used | SHA-256 of `codex-as-api:claude-code-session:<exact header value>` supplies cache affinity only |
+| `previous_response_id` | Resolves a known entry from the 256-chain process-local history and replays full input/output over HTTP; never forwarded | Non-null values return Anthropic-style HTTP 400 because normal Messages is stateless |
+| `cache_control` | Not an OpenAI Chat control | Validated as an Anthropic compatibility hint, then stripped before Codex transport |
+
+Anthropic `cache_control` is a cache-boundary annotation, not an identifier.
+This proxy accepts only `{"type":"ephemeral"}` with optional `ttl: "5m"` or
+`"1h"` at request, system, message, content-block, and tool locations. The
+private Codex request has no Anthropic breakpoint or TTL fields, so accepted
+hints do not reproduce Anthropic caching semantics. Normal `/v1/messages`
+responses do not expose the Chat-only `response_id`. The custom
+`/v1/messages/compact` endpoint retains its documented local
+`previous_response_id` support.
+
 ### `POST /v1/messages/count_tokens`
 
 Anthropic-compatible token counting helper. Codex OAuth does not expose a count-only endpoint equivalent to Anthropic's native API, so this route counts text locally and returns context-window metadata for the effective backend model. Normalized model-visible messages, tool calls, tool-result metadata, reasoning, and tool schemas are counted once. Request-envelope and generation-control fields are excluded, and image inputs use a separate fixed estimate so inline base64 data is not counted as text.
 
 GPT-5-family text uses a bundled port of official `tiktoken` `o200k_base` `encode_ordinary`: the same Unicode pre-tokenization regex, byte-pair merge algorithm, and merge-rank data are implemented in Python, TypeScript, and Rust. Official `tiktoken` maps `gpt-5` and its `gpt-5-`-prefixed variants to [`o200k_base`](https://github.com/openai/tiktoken/blob/08a5f3b2c987ada4fc5aa1f16c643c203fa8acaa/tiktoken/model.py#L7-L20); this project applies that GPT-5-family encoding to the bundled `gpt-5.*` Codex model IDs. The project does not depend on a `tiktoken` package or download encoding data at runtime. The last upstream synchronization check was **2026-07-14**, against [`tiktoken` 0.13.0 at `08a5f3b`](https://github.com/openai/tiktoken/tree/08a5f3b2c987ada4fc5aa1f16c643c203fa8acaa); the bundled rank file SHA-256 is `446a9538cb6c348e3516120d7c08b09f57c36495e2acfffe59a5bf8b0cfb1a2d`.
 
-Official Codex also has a [`ceil(UTF-8 bytes / 4)` truncation helper](https://github.com/openai/codex/blob/393f64565ab46f09d99ca4d9bd973537e72a114b/codex-rs/utils/string/src/truncate.rs#L4-L84), but Codex documents the history estimate using that helper as [a coarse lower bound rather than a tokenizer-accurate count](https://github.com/openai/codex/blob/393f64565ab46f09d99ca4d9bd973537e72a114b/codex-rs/core/src/context_manager/history.rs#L160-L185). This endpoint therefore uses exact `o200k_base` ordinary text tokenization instead. The complete request count remains an estimate because protocol-wrapper overhead and image cost are local constants, but the former byte-as-token and raw-payload double count that could overstate ordinary Claude Code requests by about 8x is removed.
+Official Codex also has a [`ceil(UTF-8 bytes / 4)` truncation helper](https://github.com/openai/codex/blob/bd2de422aa287b97b06ca6425a10935bcf1b3731/codex-rs/utils/string/src/truncate.rs#L4-L84), but Codex documents the history estimate using that helper as [a coarse lower bound rather than a tokenizer-accurate count](https://github.com/openai/codex/blob/bd2de422aa287b97b06ca6425a10935bcf1b3731/codex-rs/core/src/context_manager/history.rs#L162-L186). This endpoint therefore uses exact `o200k_base` ordinary text tokenization instead. The complete request count remains an estimate because protocol-wrapper overhead and image cost are local constants, but the former byte-as-token and raw-payload double count that could overstate ordinary Claude Code requests by about 8x is removed.
 
 ```bash
 curl http://localhost:18080/v1/messages/count_tokens \
@@ -399,7 +422,7 @@ These features are extensions beyond the standard OpenAI API, designed for Codex
 
 `prompt_cache_key` keeps related prefixes in the same backend cache family. Use one stable, privacy-safe key per conversation or application prefix.
 
-Official Codex [defaults this field to its own per-conversation `thread_id`](https://github.com/openai/codex/blob/393f64565ab46f09d99ca4d9bd973537e72a114b/codex-rs/core/src/client.rs#L469-L473). This multi-client facade cannot infer that boundary safely and does not reuse its process-level metadata thread ID as a cache key, which could mix unrelated callers. Set `prompt_cache_key` explicitly when stable cache affinity is required.
+Official Codex 0.145.0 and current `main` [default this field to Responses metadata `session_id`](https://github.com/openai/codex/blob/bd2de422aa287b97b06ca6425a10935bcf1b3731/codex-rs/core/src/client.rs#L483-L486), unless an explicit override is present. This proxy follows the same precedence on Chat requests: explicit `prompt_cache_key`, then a non-empty `client_metadata.session_id`, then omission. It does not generate a process-wide session or reuse `thread_id` as the cache key.
 
 The private Codex OAuth HTTP and WebSocket request structures do not contain public GPT-5.6 `prompt_cache_options` or content-block `prompt_cache_breakpoint` fields. This proxy treats explicit `null` as omitted and rejects non-null controls with HTTP 400 instead of forwarding a request that the private route rejects or silently pretending the requested cache policy was applied. Use a public Responses API client when explicit cache policy or breakpoints are required. See OpenAI's [public prompt caching guide](https://developers.openai.com/api/docs/guides/prompt-caching#prompt-cache-breakpoints).
 
@@ -454,7 +477,7 @@ The mapping is intentionally transport-aware:
 |---|---|
 | `reasoning.mode: "standard"` | Omit mode; send the resolved effort/context |
 | `reasoning.mode: "pro"` | HTTP 400; no official Codex alias |
-| `prompt_cache_key` | Forward unchanged |
+| `prompt_cache_key` | Forward an explicit value; otherwise use non-empty `client_metadata.session_id` |
 | Non-null `prompt_cache_options` / breakpoint | HTTP 400; `null` is omitted and there is no private field |
 | Non-null `safety_identifier` | HTTP 400; `null` is omitted and OAuth account/thread IDs are not semantic aliases |
 | Non-empty `stop` / `stop_sequences` | HTTP 400; no private field |
@@ -462,7 +485,7 @@ The mapping is intentionally transport-aware:
 | `service_tier: "fast"` | Send `service_tier: "priority"` |
 | `service_tier: "default"` | Omit the field |
 
-Authenticated tests on July 10, 2026 verified both official continuation paths with `gpt-5.6-sol`: a direct private Responses WebSocket completed a second delta request using the exact prior `response.id`, and the private HTTP endpoint completed the same continuation when the full prior input/output history was replayed. The proxy implements the HTTP replay strategy. Direct HTTP forwarding of `previous_response_id`, Pro, public cache controls, and `safety_identifier` was rejected and is not used. See OpenAI's [reasoning mode documentation](https://developers.openai.com/api/docs/guides/reasoning#reasoning-mode) and the official Codex [HTTP/WebSocket request structures](https://github.com/openai/codex/blob/393f64565ab46f09d99ca4d9bd973537e72a114b/codex-rs/codex-api/src/common.rs#L215-L293).
+Authenticated tests on July 10, 2026 verified both official continuation paths with `gpt-5.6-sol`: a direct private Responses WebSocket completed a second delta request using the exact prior `response.id`, and the private HTTP endpoint completed the same continuation when the full prior input/output history was replayed. The proxy implements the HTTP replay strategy. Direct HTTP forwarding of `previous_response_id`, Pro, public cache controls, and `safety_identifier` was rejected and is not used. See OpenAI's [reasoning mode documentation](https://developers.openai.com/api/docs/guides/reasoning#reasoning-mode) and the official Codex [HTTP/WebSocket request structures](https://github.com/openai/codex/blob/bd2de422aa287b97b06ca6425a10935bcf1b3731/codex-rs/codex-api/src/common.rs#L251-L307).
 
 ### `responses_lite`
 
@@ -508,15 +531,15 @@ Set `parallel_tool_calls: true` to request parallel tool calls when the selected
 
 ### `client_metadata` and `codex_metadata`
 
-`client_metadata` is forwarded to the Codex backend. Set `codex_metadata: true` or `CODEX_AS_API_CODEX_METADATA=on` to overlay Codex-style turn metadata keys such as `turn_id`, `session_id`, `thread_id`, and `x-codex-turn-metadata`.
+`client_metadata` is forwarded to the Codex backend. Set `codex_metadata: true` or `CODEX_AS_API_CODEX_METADATA=on` to add Codex-style turn metadata. Metadata mode requires a non-empty caller-supplied `client_metadata.session_id`; it preserves that session, defaults a missing root `thread_id` to the session, and preserves an explicit child `thread_id`.
 
-Do not rely on user-supplied values for those reserved Codex metadata keys when metadata mode is enabled; this package regenerates them per turn. Metadata `thread_id` is not a `previous_response_id` alias and is not automatically reused as `prompt_cache_key` by this multi-client proxy.
+The installation ID and process window ID remain stable, while `turn_id` and `x-codex-turn-metadata` are regenerated for each request. Metadata `thread_id` is neither a `previous_response_id` alias nor a cache key. An explicit `prompt_cache_key` wins; otherwise the non-empty session ID supplies cache affinity.
 
 ### `previous_response_id`
 
 Non-streaming responses and the final streaming finish chunk expose the real upstream Responses ID as `response_id`. The provider keeps up to 256 completed chains in a process-local LRU store. Passing a known ID as `previous_response_id` prepends the saved semantic input and exact prior `response.output_item.done` items—including encrypted reasoning and tool items—to the new input, then sends one full private HTTP request. The ID itself is never forwarded and is never converted to `thread_id`.
 
-That event source is intentional: the official Codex SSE parser [takes semantic items from `response.output_item.done`](https://github.com/openai/codex/blob/393f64565ab46f09d99ca4d9bd973537e72a114b/codex-rs/codex-api/src/sse/responses.rs#L326-L337), while its [`response.completed` shape contains the response ID, usage, and `end_turn`](https://github.com/openai/codex/blob/393f64565ab46f09d99ca4d9bd973537e72a114b/codex-rs/codex-api/src/sse/responses.rs#L112-L120), not replay history. The authenticated private HTTP rollout likewise returned an empty `response.completed.output`; the proxy therefore commits the completed output-item events instead of treating that extra field as conversation state.
+That event source is intentional: the official Codex SSE parser [takes semantic items from `response.output_item.done`](https://github.com/openai/codex/blob/bd2de422aa287b97b06ca6425a10935bcf1b3731/codex-rs/codex-api/src/sse/responses.rs#L327-L337), while its [`response.completed` shape contains the response ID, usage, and `end_turn`](https://github.com/openai/codex/blob/bd2de422aa287b97b06ca6425a10935bcf1b3731/codex-rs/codex-api/src/sse/responses.rs#L112-L120), not replay history. The authenticated private HTTP rollout likewise returned an empty `response.completed.output`; the proxy therefore commits the completed output-item events instead of treating that extra field as conversation state.
 
 Only a real `response.completed` event commits a chain. Branches from an older retained ID are supported. Restarting the server or evicting an old entry removes that local state; an unknown ID returns HTTP 400 before any upstream request.
 
@@ -642,7 +665,7 @@ curl -N http://localhost:18080/v1/chat/completions \
 
 ## Using with Claude Code
 
-The `/v1/messages` endpoint implements the Anthropic Messages gateway shape used by Claude Code. Compatibility was validated with Claude Code `2.1.209`, including streaming, real Codex OAuth chat, request-level GPT model routing, adaptive thinking, `--effort max`, and Fast Mode.
+The `/v1/messages` endpoint implements the Anthropic Messages gateway shape used by Claude Code. The current request shape was reproduced with Claude Code `2.1.220`; streaming, real Codex OAuth chat, request-level GPT model routing, adaptive thinking, `--effort max`, and Fast Mode remain covered.
 
 Start the proxy first. `CODEX_AS_API_MODEL` is the fallback used when Claude Code sends a built-in Anthropic model name:
 
@@ -666,7 +689,14 @@ CLAUDE_CODE_ATTRIBUTION_HEADER=0 \
 claude
 ```
 
-Run `/model` and select **GPT-5.6 Sol**. The custom entry is appended to the built-in rows rather than replacing them. Claude Code `2.1.209` recognizes this GPT model ID without a custom capability declaration: `/effort low|medium|high|xhigh|max`, the picker effort control, and `claude --effort ...` are translated from Claude Code's `output_config.effort` to the Codex reasoning effort. Claude Code Fast Mode's `speed: "fast"` is translated to the Codex `priority` service tier.
+Run `/model` and select **GPT-5.6 Sol**. The custom entry is appended to the built-in rows rather than replacing them. Claude Code `2.1.220` recognizes this GPT model ID without a custom capability declaration: `/effort low|medium|high|xhigh|max`, the picker effort control, and `claude --effort ...` are translated from Claude Code's `output_config.effort` to the Codex reasoning effort. Claude Code Fast Mode's `speed: "fast"` is translated to the Codex `priority` service tier.
+
+Claude Code sends `x-claude-code-session-id` for gateway request grouping. This
+proxy hashes the exact header value into a stable `prompt_cache_key`; it does
+not turn the header into Codex `session_id` or `thread_id` metadata. A
+top-level `prompt_cache_key` is supported as a proxy extension and takes
+precedence. Normal Messages requests remain stateless, so callers must send
+full message history.
 
 If managed settings define an `availableModels` allowlist, that list must include the exact `ANTHROPIC_CUSTOM_MODEL_OPTION` value, such as `gpt-5.6-sol`; otherwise Claude Code hides or rejects the custom row.
 
@@ -724,7 +754,7 @@ The provider handles:
 ## Release & package publishing
 
 - Bump versions in `pyproject.toml`, `src/codex_as_api/__init__.py`, `src/codex_as_api/server.py`, `ts/package.json`, `ts/package-lock.json`, `rust/Cargo.toml`, and `rust/Cargo.lock`.
-- Publish a GitHub Release such as `v0.6.3` from the matching commit.
+- Publish a GitHub Release such as `v0.6.4` from the matching commit.
 - The manually-dispatched `Publish npm packages` workflow builds/tests the TypeScript package, runs `npm pack --dry-run`, publishes `codex-as-api` to npmjs when `NPM_TOKEN` is configured, and publishes `@eunho-j/codex-as-api` to GitHub Packages with `GITHUB_TOKEN`.
 
 Publishing to npmjs requires an authenticated npm session (`npm login` beforehand; `npm whoami` should succeed). From the repository root, the publish itself is one command:
@@ -767,6 +797,19 @@ npm test
 
 ## Release Notes
 
+### v0.6.4
+
+- Remove process-global generated Codex session/thread identities and require
+  explicit session identity when Codex metadata mode is enabled.
+- Resolve Chat cache affinity as explicit `prompt_cache_key`, then
+  `client_metadata.session_id`, then omission.
+- Derive Claude Code cache affinity from `x-claude-code-session-id` without
+  fabricating Codex metadata; keep normal Anthropic Messages stateless.
+- Validate and strip Anthropic `cache_control` compatibility hints without
+  claiming unavailable breakpoint or TTL semantics.
+- Update current compatibility evidence to Codex `0.145.0`, Codex `main` at
+  `bd2de422aa287b97b06ca6425a10935bcf1b3731`, and Claude Code `2.1.220`.
+
 ### v0.6.3
 
 - Accept Claude Code auxiliary requests that combine ambient `output_config.effort` with call-level `thinking.disabled`.

{codex_as_api-0.6.3 → codex_as_api-0.6.4}/README.md

@@ -15,7 +15,7 @@ Use ChatGPT / Codex OAuth as a local OpenAI-compatible API server.
 - **Tool calling** — function calls, tool results, and parallel tool calls
 - **Image support** — generation, inspection, multimodal Chat input, and capability-gated `original` image detail in classic Responses
 - **Reasoning** — configurable effort/context, `standard` mode compatibility, persisted reasoning, and streaming thinking content
-- **Codex features** — `prompt_cache_key`, process-local `response_id` continuation, subagent headers, and remote compaction
+- **Codex features** — session-aware `prompt_cache_key`, process-local Chat `response_id` continuation, subagent headers, and remote compaction
 - **Codex config aware** — reads `CODEX_HOME` / `~/.codex/config.toml` for model, reasoning-effort, and context-window settings
 - **Token estimate & compaction helpers** — Anthropic-compatible `/v1/messages/count_tokens` and `/v1/messages/compact`
 - **Auto auth** — reads `~/.codex/auth.json` and auto-refreshes OAuth tokens
@@ -276,13 +276,36 @@ curl -N http://localhost:18080/v1/messages \
   }'
 ```
 
+### Identifier and cache behavior
+
+The two compatibility facades intentionally use the similarly named fields for
+different jobs:
+
+| Input or output | `/v1/chat/completions` | `/v1/messages` |
+|---|---|---|
+| `client_metadata.session_id` | Forwarded to Codex, used as the default `prompt_cache_key`, and required when Codex metadata mode is enabled | Not used or forwarded |
+| `client_metadata.thread_id` | Codex metadata thread identity; defaults to `session_id` for a root request and preserves an explicit child thread | Not used or synthesized |
+| `prompt_cache_key` | Explicit value wins; otherwise a non-empty `client_metadata.session_id` is used; otherwise omitted | Optional proxy extension; explicit value wins, otherwise the Claude Code session header is hashed |
+| `x-claude-code-session-id` | Not used | SHA-256 of `codex-as-api:claude-code-session:<exact header value>` supplies cache affinity only |
+| `previous_response_id` | Resolves a known entry from the 256-chain process-local history and replays full input/output over HTTP; never forwarded | Non-null values return Anthropic-style HTTP 400 because normal Messages is stateless |
+| `cache_control` | Not an OpenAI Chat control | Validated as an Anthropic compatibility hint, then stripped before Codex transport |
+
+Anthropic `cache_control` is a cache-boundary annotation, not an identifier.
+This proxy accepts only `{"type":"ephemeral"}` with optional `ttl: "5m"` or
+`"1h"` at request, system, message, content-block, and tool locations. The
+private Codex request has no Anthropic breakpoint or TTL fields, so accepted
+hints do not reproduce Anthropic caching semantics. Normal `/v1/messages`
+responses do not expose the Chat-only `response_id`. The custom
+`/v1/messages/compact` endpoint retains its documented local
+`previous_response_id` support.
+
 ### `POST /v1/messages/count_tokens`
 
 Anthropic-compatible token counting helper. Codex OAuth does not expose a count-only endpoint equivalent to Anthropic's native API, so this route counts text locally and returns context-window metadata for the effective backend model. Normalized model-visible messages, tool calls, tool-result metadata, reasoning, and tool schemas are counted once. Request-envelope and generation-control fields are excluded, and image inputs use a separate fixed estimate so inline base64 data is not counted as text.
 
 GPT-5-family text uses a bundled port of official `tiktoken` `o200k_base` `encode_ordinary`: the same Unicode pre-tokenization regex, byte-pair merge algorithm, and merge-rank data are implemented in Python, TypeScript, and Rust. Official `tiktoken` maps `gpt-5` and its `gpt-5-`-prefixed variants to [`o200k_base`](https://github.com/openai/tiktoken/blob/08a5f3b2c987ada4fc5aa1f16c643c203fa8acaa/tiktoken/model.py#L7-L20); this project applies that GPT-5-family encoding to the bundled `gpt-5.*` Codex model IDs. The project does not depend on a `tiktoken` package or download encoding data at runtime. The last upstream synchronization check was **2026-07-14**, against [`tiktoken` 0.13.0 at `08a5f3b`](https://github.com/openai/tiktoken/tree/08a5f3b2c987ada4fc5aa1f16c643c203fa8acaa); the bundled rank file SHA-256 is `446a9538cb6c348e3516120d7c08b09f57c36495e2acfffe59a5bf8b0cfb1a2d`.
 
-Official Codex also has a [`ceil(UTF-8 bytes / 4)` truncation helper](https://github.com/openai/codex/blob/393f64565ab46f09d99ca4d9bd973537e72a114b/codex-rs/utils/string/src/truncate.rs#L4-L84), but Codex documents the history estimate using that helper as [a coarse lower bound rather than a tokenizer-accurate count](https://github.com/openai/codex/blob/393f64565ab46f09d99ca4d9bd973537e72a114b/codex-rs/core/src/context_manager/history.rs#L160-L185). This endpoint therefore uses exact `o200k_base` ordinary text tokenization instead. The complete request count remains an estimate because protocol-wrapper overhead and image cost are local constants, but the former byte-as-token and raw-payload double count that could overstate ordinary Claude Code requests by about 8x is removed.
+Official Codex also has a [`ceil(UTF-8 bytes / 4)` truncation helper](https://github.com/openai/codex/blob/bd2de422aa287b97b06ca6425a10935bcf1b3731/codex-rs/utils/string/src/truncate.rs#L4-L84), but Codex documents the history estimate using that helper as [a coarse lower bound rather than a tokenizer-accurate count](https://github.com/openai/codex/blob/bd2de422aa287b97b06ca6425a10935bcf1b3731/codex-rs/core/src/context_manager/history.rs#L162-L186). This endpoint therefore uses exact `o200k_base` ordinary text tokenization instead. The complete request count remains an estimate because protocol-wrapper overhead and image cost are local constants, but the former byte-as-token and raw-payload double count that could overstate ordinary Claude Code requests by about 8x is removed.
 
 ```bash
 curl http://localhost:18080/v1/messages/count_tokens \
@@ -365,7 +388,7 @@ These features are extensions beyond the standard OpenAI API, designed for Codex
 
 `prompt_cache_key` keeps related prefixes in the same backend cache family. Use one stable, privacy-safe key per conversation or application prefix.
 
-Official Codex [defaults this field to its own per-conversation `thread_id`](https://github.com/openai/codex/blob/393f64565ab46f09d99ca4d9bd973537e72a114b/codex-rs/core/src/client.rs#L469-L473). This multi-client facade cannot infer that boundary safely and does not reuse its process-level metadata thread ID as a cache key, which could mix unrelated callers. Set `prompt_cache_key` explicitly when stable cache affinity is required.
+Official Codex 0.145.0 and current `main` [default this field to Responses metadata `session_id`](https://github.com/openai/codex/blob/bd2de422aa287b97b06ca6425a10935bcf1b3731/codex-rs/core/src/client.rs#L483-L486), unless an explicit override is present. This proxy follows the same precedence on Chat requests: explicit `prompt_cache_key`, then a non-empty `client_metadata.session_id`, then omission. It does not generate a process-wide session or reuse `thread_id` as the cache key.
 
 The private Codex OAuth HTTP and WebSocket request structures do not contain public GPT-5.6 `prompt_cache_options` or content-block `prompt_cache_breakpoint` fields. This proxy treats explicit `null` as omitted and rejects non-null controls with HTTP 400 instead of forwarding a request that the private route rejects or silently pretending the requested cache policy was applied. Use a public Responses API client when explicit cache policy or breakpoints are required. See OpenAI's [public prompt caching guide](https://developers.openai.com/api/docs/guides/prompt-caching#prompt-cache-breakpoints).
 
@@ -420,7 +443,7 @@ The mapping is intentionally transport-aware:
 |---|---|
 | `reasoning.mode: "standard"` | Omit mode; send the resolved effort/context |
 | `reasoning.mode: "pro"` | HTTP 400; no official Codex alias |
-| `prompt_cache_key` | Forward unchanged |
+| `prompt_cache_key` | Forward an explicit value; otherwise use non-empty `client_metadata.session_id` |
 | Non-null `prompt_cache_options` / breakpoint | HTTP 400; `null` is omitted and there is no private field |
 | Non-null `safety_identifier` | HTTP 400; `null` is omitted and OAuth account/thread IDs are not semantic aliases |
 | Non-empty `stop` / `stop_sequences` | HTTP 400; no private field |
@@ -428,7 +451,7 @@ The mapping is intentionally transport-aware:
 | `service_tier: "fast"` | Send `service_tier: "priority"` |
 | `service_tier: "default"` | Omit the field |
 
-Authenticated tests on July 10, 2026 verified both official continuation paths with `gpt-5.6-sol`: a direct private Responses WebSocket completed a second delta request using the exact prior `response.id`, and the private HTTP endpoint completed the same continuation when the full prior input/output history was replayed. The proxy implements the HTTP replay strategy. Direct HTTP forwarding of `previous_response_id`, Pro, public cache controls, and `safety_identifier` was rejected and is not used. See OpenAI's [reasoning mode documentation](https://developers.openai.com/api/docs/guides/reasoning#reasoning-mode) and the official Codex [HTTP/WebSocket request structures](https://github.com/openai/codex/blob/393f64565ab46f09d99ca4d9bd973537e72a114b/codex-rs/codex-api/src/common.rs#L215-L293).
+Authenticated tests on July 10, 2026 verified both official continuation paths with `gpt-5.6-sol`: a direct private Responses WebSocket completed a second delta request using the exact prior `response.id`, and the private HTTP endpoint completed the same continuation when the full prior input/output history was replayed. The proxy implements the HTTP replay strategy. Direct HTTP forwarding of `previous_response_id`, Pro, public cache controls, and `safety_identifier` was rejected and is not used. See OpenAI's [reasoning mode documentation](https://developers.openai.com/api/docs/guides/reasoning#reasoning-mode) and the official Codex [HTTP/WebSocket request structures](https://github.com/openai/codex/blob/bd2de422aa287b97b06ca6425a10935bcf1b3731/codex-rs/codex-api/src/common.rs#L251-L307).
 
 ### `responses_lite`
 
@@ -474,15 +497,15 @@ Set `parallel_tool_calls: true` to request parallel tool calls when the selected
 
 ### `client_metadata` and `codex_metadata`
 
-`client_metadata` is forwarded to the Codex backend. Set `codex_metadata: true` or `CODEX_AS_API_CODEX_METADATA=on` to overlay Codex-style turn metadata keys such as `turn_id`, `session_id`, `thread_id`, and `x-codex-turn-metadata`.
+`client_metadata` is forwarded to the Codex backend. Set `codex_metadata: true` or `CODEX_AS_API_CODEX_METADATA=on` to add Codex-style turn metadata. Metadata mode requires a non-empty caller-supplied `client_metadata.session_id`; it preserves that session, defaults a missing root `thread_id` to the session, and preserves an explicit child `thread_id`.
 
-Do not rely on user-supplied values for those reserved Codex metadata keys when metadata mode is enabled; this package regenerates them per turn. Metadata `thread_id` is not a `previous_response_id` alias and is not automatically reused as `prompt_cache_key` by this multi-client proxy.
+The installation ID and process window ID remain stable, while `turn_id` and `x-codex-turn-metadata` are regenerated for each request. Metadata `thread_id` is neither a `previous_response_id` alias nor a cache key. An explicit `prompt_cache_key` wins; otherwise the non-empty session ID supplies cache affinity.
 
 ### `previous_response_id`
 
 Non-streaming responses and the final streaming finish chunk expose the real upstream Responses ID as `response_id`. The provider keeps up to 256 completed chains in a process-local LRU store. Passing a known ID as `previous_response_id` prepends the saved semantic input and exact prior `response.output_item.done` items—including encrypted reasoning and tool items—to the new input, then sends one full private HTTP request. The ID itself is never forwarded and is never converted to `thread_id`.
 
-That event source is intentional: the official Codex SSE parser [takes semantic items from `response.output_item.done`](https://github.com/openai/codex/blob/393f64565ab46f09d99ca4d9bd973537e72a114b/codex-rs/codex-api/src/sse/responses.rs#L326-L337), while its [`response.completed` shape contains the response ID, usage, and `end_turn`](https://github.com/openai/codex/blob/393f64565ab46f09d99ca4d9bd973537e72a114b/codex-rs/codex-api/src/sse/responses.rs#L112-L120), not replay history. The authenticated private HTTP rollout likewise returned an empty `response.completed.output`; the proxy therefore commits the completed output-item events instead of treating that extra field as conversation state.
+That event source is intentional: the official Codex SSE parser [takes semantic items from `response.output_item.done`](https://github.com/openai/codex/blob/bd2de422aa287b97b06ca6425a10935bcf1b3731/codex-rs/codex-api/src/sse/responses.rs#L327-L337), while its [`response.completed` shape contains the response ID, usage, and `end_turn`](https://github.com/openai/codex/blob/bd2de422aa287b97b06ca6425a10935bcf1b3731/codex-rs/codex-api/src/sse/responses.rs#L112-L120), not replay history. The authenticated private HTTP rollout likewise returned an empty `response.completed.output`; the proxy therefore commits the completed output-item events instead of treating that extra field as conversation state.
 
 Only a real `response.completed` event commits a chain. Branches from an older retained ID are supported. Restarting the server or evicting an old entry removes that local state; an unknown ID returns HTTP 400 before any upstream request.
 
@@ -608,7 +631,7 @@ curl -N http://localhost:18080/v1/chat/completions \
 
 ## Using with Claude Code
 
-The `/v1/messages` endpoint implements the Anthropic Messages gateway shape used by Claude Code. Compatibility was validated with Claude Code `2.1.209`, including streaming, real Codex OAuth chat, request-level GPT model routing, adaptive thinking, `--effort max`, and Fast Mode.
+The `/v1/messages` endpoint implements the Anthropic Messages gateway shape used by Claude Code. The current request shape was reproduced with Claude Code `2.1.220`; streaming, real Codex OAuth chat, request-level GPT model routing, adaptive thinking, `--effort max`, and Fast Mode remain covered.
 
 Start the proxy first. `CODEX_AS_API_MODEL` is the fallback used when Claude Code sends a built-in Anthropic model name:
 
@@ -632,7 +655,14 @@ CLAUDE_CODE_ATTRIBUTION_HEADER=0 \
 claude
 ```
 
-Run `/model` and select **GPT-5.6 Sol**. The custom entry is appended to the built-in rows rather than replacing them. Claude Code `2.1.209` recognizes this GPT model ID without a custom capability declaration: `/effort low|medium|high|xhigh|max`, the picker effort control, and `claude --effort ...` are translated from Claude Code's `output_config.effort` to the Codex reasoning effort. Claude Code Fast Mode's `speed: "fast"` is translated to the Codex `priority` service tier.
+Run `/model` and select **GPT-5.6 Sol**. The custom entry is appended to the built-in rows rather than replacing them. Claude Code `2.1.220` recognizes this GPT model ID without a custom capability declaration: `/effort low|medium|high|xhigh|max`, the picker effort control, and `claude --effort ...` are translated from Claude Code's `output_config.effort` to the Codex reasoning effort. Claude Code Fast Mode's `speed: "fast"` is translated to the Codex `priority` service tier.
+
+Claude Code sends `x-claude-code-session-id` for gateway request grouping. This
+proxy hashes the exact header value into a stable `prompt_cache_key`; it does
+not turn the header into Codex `session_id` or `thread_id` metadata. A
+top-level `prompt_cache_key` is supported as a proxy extension and takes
+precedence. Normal Messages requests remain stateless, so callers must send
+full message history.
 
 If managed settings define an `availableModels` allowlist, that list must include the exact `ANTHROPIC_CUSTOM_MODEL_OPTION` value, such as `gpt-5.6-sol`; otherwise Claude Code hides or rejects the custom row.
 
@@ -690,7 +720,7 @@ The provider handles:
 ## Release & package publishing
 
 - Bump versions in `pyproject.toml`, `src/codex_as_api/__init__.py`, `src/codex_as_api/server.py`, `ts/package.json`, `ts/package-lock.json`, `rust/Cargo.toml`, and `rust/Cargo.lock`.
-- Publish a GitHub Release such as `v0.6.3` from the matching commit.
+- Publish a GitHub Release such as `v0.6.4` from the matching commit.
 - The manually-dispatched `Publish npm packages` workflow builds/tests the TypeScript package, runs `npm pack --dry-run`, publishes `codex-as-api` to npmjs when `NPM_TOKEN` is configured, and publishes `@eunho-j/codex-as-api` to GitHub Packages with `GITHUB_TOKEN`.
 
 Publishing to npmjs requires an authenticated npm session (`npm login` beforehand; `npm whoami` should succeed). From the repository root, the publish itself is one command:
@@ -733,6 +763,19 @@ npm test
 
 ## Release Notes
 
+### v0.6.4
+
+- Remove process-global generated Codex session/thread identities and require
+  explicit session identity when Codex metadata mode is enabled.
+- Resolve Chat cache affinity as explicit `prompt_cache_key`, then
+  `client_metadata.session_id`, then omission.
+- Derive Claude Code cache affinity from `x-claude-code-session-id` without
+  fabricating Codex metadata; keep normal Anthropic Messages stateless.
+- Validate and strip Anthropic `cache_control` compatibility hints without
+  claiming unavailable breakpoint or TTL semantics.
+- Update current compatibility evidence to Codex `0.145.0`, Codex `main` at
+  `bd2de422aa287b97b06ca6425a10935bcf1b3731`, and Claude Code `2.1.220`.
+
 ### v0.6.3
 
 - Accept Claude Code auxiliary requests that combine ambient `output_config.effort` with call-level `thinking.disabled`.

{codex_as_api-0.6.3 → codex_as_api-0.6.4}/RELEASES.md

@@ -1,5 +1,43 @@
 # Release Notes
 
+## v0.6.4
+
+### Codex identity and cache affinity
+
+- Remove process-global generated `session_id` and `thread_id` values from
+  Python, TypeScript, and Rust. Codex metadata mode now requires an explicit
+  non-empty `client_metadata.session_id`, defaults a root `thread_id` to that
+  session, preserves an explicit child thread, and refreshes only turn-scoped
+  identity on each request.
+- Resolve Chat `prompt_cache_key` as explicit value, then non-empty
+  `client_metadata.session_id`, then omission. This matches Codex 0.145.0 and
+  current `main`, where the official default is Responses metadata
+  `session_id`, not `thread_id`.
+- Retain bounded process-local Chat `previous_response_id` history replay over
+  private HTTP. The ID remains local and is never forwarded upstream.
+
+### Claude Code session and cache compatibility
+
+- Read `x-claude-code-session-id` on `/v1/messages` and derive a stable,
+  privacy-safe SHA-256 `prompt_cache_key`; an explicit proxy extension
+  `prompt_cache_key` takes precedence.
+- Keep normal Anthropic Messages stateless: reject non-null
+  `previous_response_id`, disable ambient Codex metadata, avoid fabricated
+  Claude thread IDs, and remove Python's nonstandard Anthropic `response_id`.
+- Validate Anthropic `cache_control` hints at request, system, message, content,
+  and tool locations. Accept only `type: "ephemeral"` with optional TTL `5m` or
+  `1h`, then strip the hint because the private Codex transport cannot preserve
+  Anthropic cache breakpoints or TTL behavior.
+
+### Validation
+
+- Python: 515 tests, mypy, and changed-file Ruff checks.
+- TypeScript: 261 tests and production build.
+- Rust: 253 tests and rustfmt.
+- Re-audited `@openai/codex` 0.145.0 plus `main` at
+  `bd2de422aa287b97b06ca6425a10935bcf1b3731`, and reproduced the Claude Code
+  2.1.220 request shape.
+
 ## v0.6.3
 
 ### Claude Code WebSearch/WebFetch auxiliary calls

{codex_as_api-0.6.3 → codex_as_api-0.6.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codex-as-api"
-version = "0.6.3"
+version = "0.6.4"
 description = "Use ChatGPT/Codex OAuth as a local OpenAI-compatible API server."
 readme = "README.md"
 license = { text = "Apache-2.0" }

{codex_as_api-0.6.3 → codex_as_api-0.6.4}/src/codex_as_api/__init__.py

@@ -1,3 +1,3 @@
 """codex-as-api: Use ChatGPT/Codex OAuth as a local OpenAI-compatible API server."""
 
-__version__ = "0.6.3"
+__version__ = "0.6.4"

{codex_as_api-0.6.3 → codex_as_api-0.6.4}/src/codex_as_api/model_capabilities.py

@@ -23,8 +23,6 @@ _PROJECT_ROOT = pathlib.Path(__file__).resolve().parents[2]
 _CAPABILITIES_PATH = _PROJECT_ROOT / "config" / "model-capabilities.json"
 _PACKAGE_CAPABILITIES_PATH = pathlib.Path(__file__).resolve().with_name("model-capabilities.json")
 _INSTALLATION_NAMESPACE = uuid.UUID("d2c81270-8f15-5e8d-a5c4-4cdbf2c21fd0")
-_SESSION_ID = str(uuid.uuid4())
-_THREAD_ID = str(uuid.uuid4())
 _WINDOW_ID = str(uuid.uuid4())
 
 ResponsesLiteMode = Literal["off", "on", "auto"]
@@ -157,14 +155,23 @@ def build_codex_client_metadata(
     existing: Mapping[str, str] | None,
 ) -> dict[str, str]:
     metadata = dict(existing or {})
+    session_id = metadata.get(SESSION_ID_KEY)
+    if not isinstance(session_id, str) or not session_id.strip():
+        raise ValueError("codex_metadata requires a non-empty client_metadata.session_id")
+    thread_id = metadata.get(THREAD_ID_KEY)
+    if thread_id is None:
+        thread_id = session_id
+    elif not isinstance(thread_id, str) or not thread_id.strip():
+        raise ValueError("client_metadata.thread_id must be a non-empty string when provided")
+
     auth_path = pathlib.Path(auth_json_path or "~/.codex/auth.json").expanduser()
     absolute_path = os.path.abspath(os.fspath(auth_path))
     installation_id = str(uuid.uuid5(_INSTALLATION_NAMESPACE, f"codex-as-api:{absolute_path}"))
     turn_id = str(uuid.uuid4())
     turn_metadata = {
         "installation_id": installation_id,
-        "session_id": _SESSION_ID,
-        "thread_id": _THREAD_ID,
+        "session_id": session_id,
+        "thread_id": thread_id,
         "turn_id": turn_id,
         "window_id": _WINDOW_ID,
         "source": "codex-as-api",
@@ -172,8 +179,8 @@ def build_codex_client_metadata(
     metadata.update(
         {
             INSTALLATION_ID_KEY: installation_id,
-            SESSION_ID_KEY: _SESSION_ID,
-            THREAD_ID_KEY: _THREAD_ID,
+            SESSION_ID_KEY: session_id,
+            THREAD_ID_KEY: thread_id,
             TURN_ID_KEY: turn_id,
             WINDOW_ID_KEY: _WINDOW_ID,
             TURN_METADATA_KEY: json.dumps(turn_metadata, separators=(",", ":"), sort_keys=True),

{codex_as_api-0.6.3 → codex_as_api-0.6.4}/src/codex_as_api/provider.py

@@ -27,6 +27,7 @@ from .model_capabilities import (
     LITE_HEADER_NAME,
     LITE_HEADER_VALUE,
     RESPONSES_LITE_ENV,
+    SESSION_ID_KEY,
     apply_model_capability_fields,
     build_codex_client_metadata,
     capability_for_model,
@@ -753,18 +754,27 @@ class ChatGPTOAuthProvider:
         }
         if any(tool.get("type") == "web_search" for tool in payload["tools"]):
             payload["include"] = ["web_search_call.action.sources"]
-        if prompt_cache_key is not None:
+        metadata = dict(client_metadata) if client_metadata is not None else None
+        if resolve_codex_metadata_enabled(codex_metadata):
+            try:
+                metadata = build_codex_client_metadata(
+                    auth_json_path=self.auth_json_path,
+                    existing=metadata,
+                )
+            except ValueError as exc:
+                raise ChatGPTOAuthInvalidRequestError(str(exc)) from exc
+        effective_prompt_cache_key = prompt_cache_key
+        if effective_prompt_cache_key is None and metadata is not None:
+            session_id = metadata.get(SESSION_ID_KEY)
+            if isinstance(session_id, str) and session_id.strip():
+                effective_prompt_cache_key = session_id
+        if effective_prompt_cache_key is not None:
             payload["prompt_cache_key"] = _validate_non_empty_string(
-                prompt_cache_key,
+                effective_prompt_cache_key,
                 "prompt_cache_key",
             )
-        if client_metadata is not None:
-            payload["client_metadata"] = client_metadata
-        if resolve_codex_metadata_enabled(codex_metadata):
-            payload["client_metadata"] = build_codex_client_metadata(
-                auth_json_path=self.auth_json_path,
-                existing=payload.get("client_metadata") if isinstance(payload.get("client_metadata"), dict) else None,
-            )
+        if metadata is not None:
+            payload["client_metadata"] = metadata
         _finalize_responses_payload(
             payload,
             model=request_model,

{codex_as_api-0.6.3 → codex_as_api-0.6.4}/src/codex_as_api/server.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import hashlib
 import json
 import os
 import time
@@ -39,6 +40,9 @@ CODEX_CONFIG = load_codex_config()
 MODEL = _env_str("CODEX_AS_API_MODEL", CODEX_CONFIG.model or "gpt-5.5")
 AUTH_PATH = os.getenv("CODEX_AS_API_AUTH_PATH")
 DEFAULT_CONTEXT_WINDOW = 200_000
+CLAUDE_CODE_SESSION_HEADER = "x-claude-code-session-id"
+_CLAUDE_CACHE_KEY_NAMESPACE = "codex-as-api:claude-code-session:"
+_ANTHROPIC_CACHE_CONTROL_TTLS = frozenset({"5m", "1h"})
 
 _provider: ChatGPTOAuthProvider | None = None
 
@@ -109,6 +113,76 @@ def _anthropic_service_tier(body: dict[str, Any]) -> str | None:
     return speed_tier
 
 
+def _validate_anthropic_cache_control(value: object, location: str) -> None:
+    if not isinstance(value, dict):
+        raise ChatGPTOAuthInvalidRequestError(f"{location}.cache_control must be an object")
+    unknown = sorted(set(value) - {"type", "ttl"})
+    if unknown:
+        raise ChatGPTOAuthInvalidRequestError(
+            f"{location}.cache_control contains unsupported fields: {', '.join(unknown)}"
+        )
+    if value.get("type") != "ephemeral":
+        raise ChatGPTOAuthInvalidRequestError(f"{location}.cache_control.type must be 'ephemeral'")
+    if "ttl" in value and (
+        not isinstance(value["ttl"], str) or value["ttl"] not in _ANTHROPIC_CACHE_CONTROL_TTLS
+    ):
+        raise ChatGPTOAuthInvalidRequestError(f"{location}.cache_control.ttl must be one of: 5m, 1h")
+
+
+def _strip_anthropic_content_cache_controls(value: object, location: str) -> None:
+    if not isinstance(value, list):
+        return
+    for index, block in enumerate(value):
+        if not isinstance(block, dict):
+            continue
+        block_location = f"{location}[{index}]"
+        if "cache_control" in block:
+            _validate_anthropic_cache_control(block["cache_control"], block_location)
+            block.pop("cache_control")
+        _strip_anthropic_content_cache_controls(block.get("content"), f"{block_location}.content")
+
+
+def _strip_anthropic_cache_controls(body: dict[str, Any]) -> None:
+    if "cache_control" in body:
+        _validate_anthropic_cache_control(body["cache_control"], "request")
+        body.pop("cache_control")
+
+    _strip_anthropic_content_cache_controls(body.get("system"), "system")
+    messages = body.get("messages")
+    if isinstance(messages, list):
+        for index, message in enumerate(messages):
+            if not isinstance(message, dict):
+                continue
+            location = f"messages[{index}]"
+            if "cache_control" in message:
+                _validate_anthropic_cache_control(message["cache_control"], location)
+                message.pop("cache_control")
+            _strip_anthropic_content_cache_controls(message.get("content"), f"{location}.content")
+
+    tools = body.get("tools")
+    if isinstance(tools, list):
+        for index, tool in enumerate(tools):
+            if not isinstance(tool, dict) or "cache_control" not in tool:
+                continue
+            location = f"tools[{index}]"
+            _validate_anthropic_cache_control(tool["cache_control"], location)
+            tool.pop("cache_control")
+
+
+def _anthropic_prompt_cache_key(body: dict[str, Any], claude_session_id: str | None) -> str | None:
+    explicit = body.get("prompt_cache_key")
+    if explicit is not None:
+        if not isinstance(explicit, str) or not explicit.strip():
+            raise ChatGPTOAuthInvalidRequestError("prompt_cache_key must be a non-empty string")
+        return explicit
+    if claude_session_id is None:
+        return None
+    if not claude_session_id.strip():
+        raise ChatGPTOAuthInvalidRequestError(f"{CLAUDE_CODE_SESSION_HEADER} must be a non-empty string")
+    value = f"{_CLAUDE_CACHE_KEY_NAMESPACE}{claude_session_id}".encode()
+    return hashlib.sha256(value).hexdigest()
+
+
 def _merge_anthropic_text(
     converted: dict[str, Any] | None,
     direct: object,
@@ -140,7 +214,7 @@ try:
     app = FastAPI(
         title="codex-as-api",
         description="Local OpenAI-compatible API server backed by ChatGPT/Codex OAuth.",
-        version="0.6.3",
+        version="0.6.4",
     )
 
     @app.exception_handler(ChatGPTOAuthError)
@@ -481,6 +555,7 @@ try:
     ) -> tuple[list[Message], list[ToolSchema] | None, str | None, dict[str, Any] | None]:
         messages_value = body.get("messages")
         if anthropic or any(key in body for key in ("system", "thinking", "tool_choice", "stop_sequences")):
+            _strip_anthropic_cache_controls(body)
             _validate_anthropic_context_management(body.get("context_management"))
             anthropic_messages = cast(list[dict[str, Any]], messages_value) if isinstance(messages_value, list) else []
             max_tokens_value = body.get("max_tokens")
@@ -952,6 +1027,7 @@ try:
                     ),
                 )
         try:
+            _strip_anthropic_cache_controls(body)
             _validate_anthropic_context_management(body.get("context_management"))
             messages, tools, _tool_choice, _stop, _reasoning_effort, _text = anthropic_request_to_internal(
                 model=body.get("model"),
@@ -1002,6 +1078,15 @@ try:
             )
 
         try:
+            if body.get("previous_response_id") is not None:
+                raise ChatGPTOAuthInvalidRequestError(
+                    "previous_response_id is not supported by the Anthropic Messages endpoint"
+                )
+            _strip_anthropic_cache_controls(body)
+            prompt_cache_key = _anthropic_prompt_cache_key(
+                body,
+                http_request.headers.get(CLAUDE_CODE_SESSION_HEADER),
+            )
             _validate_anthropic_context_management(body.get("context_management"))
             messages, tools, tool_choice, stop, reasoning_effort, text = anthropic_request_to_internal(
                 model=body.get("model", MODEL),
@@ -1046,7 +1131,9 @@ try:
                     reasoning_mode=reasoning_mode,
                     reasoning_context=reasoning_context,
                     stop=stop,
+                    prompt_cache_key=prompt_cache_key,
                     text=text,
+                    codex_metadata=False,
                     responses_lite=responses_lite,
                     safety_identifier=body.get("safety_identifier"),
                     prompt_cache_options=body.get("prompt_cache_options"),
@@ -1070,7 +1157,9 @@ try:
                             reasoning_mode=reasoning_mode,
                             reasoning_context=reasoning_context,
                             stop=stop,
+                            prompt_cache_key=prompt_cache_key,
                             text=text,
+                            codex_metadata=False,
                             responses_lite=responses_lite,
                             safety_identifier=body.get("safety_identifier"),
                             prompt_cache_options=body.get("prompt_cache_options"),
@@ -1103,7 +1192,9 @@ try:
                 reasoning_mode=reasoning_mode,
                 reasoning_context=reasoning_context,
                 stop=stop,
+                prompt_cache_key=prompt_cache_key,
                 text=text,
+                codex_metadata=False,
                 responses_lite=responses_lite,
                 safety_identifier=body.get("safety_identifier"),
                 prompt_cache_options=body.get("prompt_cache_options"),
@@ -1116,8 +1207,6 @@ try:
 
         request_id = f"msg_{uuid.uuid4().hex[:24]}"
         result = internal_response_to_anthropic(response, client_model, request_id)
-        if response.response_id is not None:
-            result["response_id"] = response.response_id
         return JSONResponse(content=result)
 
     # ------------------------------------------------------------------

{codex_as_api-0.6.3 → codex_as_api-0.6.4}/tests/test_provider.py

@@ -481,15 +481,89 @@ def test_responses_payload_client_metadata_mode_overlays_reserved_keys(auth_json
     payload = provider._responses_payload(  # noqa: SLF001
         _provider_messages(),
         model="gpt-5.5",
-        client_metadata={"app": "kept", "turn_id": "user-value"},
+        client_metadata={"app": "kept", "session_id": "session-root", "turn_id": "user-value"},
         codex_metadata=True,
     )
 
     metadata = payload["client_metadata"]
     assert metadata["app"] == "kept"
+    assert metadata["session_id"] == "session-root"
+    assert metadata["thread_id"] == "session-root"
     assert metadata["turn_id"] != "user-value"
     assert metadata["x-codex-installation-id"]
-    assert json.loads(metadata["x-codex-turn-metadata"])["source"] == "codex-as-api"
+    turn_metadata = json.loads(metadata["x-codex-turn-metadata"])
+    assert turn_metadata["source"] == "codex-as-api"
+    assert turn_metadata["session_id"] == "session-root"
+    assert turn_metadata["thread_id"] == "session-root"
+    assert payload["prompt_cache_key"] == "session-root"
+
+
+def test_responses_payload_codex_metadata_preserves_thread_and_refreshes_only_turn_identity(auth_json_factory):
+    provider = ChatGPTOAuthProvider(auth_json_path=str(auth_json_factory()))
+    options = {
+        "model": "gpt-5.5",
+        "client_metadata": {"session_id": "session-root", "thread_id": "thread-child"},
+        "codex_metadata": True,
+    }
+
+    first = provider._responses_payload(_provider_messages(), **options)  # noqa: SLF001
+    second = provider._responses_payload(_provider_messages(), **options)  # noqa: SLF001
+    first_metadata = first["client_metadata"]
+    second_metadata = second["client_metadata"]
+
+    assert first_metadata["session_id"] == second_metadata["session_id"] == "session-root"
+    assert first_metadata["thread_id"] == second_metadata["thread_id"] == "thread-child"
+    assert first_metadata["x-codex-installation-id"] == second_metadata["x-codex-installation-id"]
+    assert first_metadata["x-codex-window-id"] == second_metadata["x-codex-window-id"]
+    assert first_metadata["turn_id"] != second_metadata["turn_id"]
+
+
+def test_responses_payload_codex_metadata_requires_explicit_session_identity():
+    provider = ChatGPTOAuthProvider()
+
+    with pytest.raises(ChatGPTOAuthInvalidRequestError):
+        provider._responses_payload(  # noqa: SLF001
+            _provider_messages(),
+            model="gpt-5.5",
+            codex_metadata=True,
+        )
+
+
+def test_responses_payload_prompt_cache_key_precedence_and_session_fallback():
+    provider = ChatGPTOAuthProvider()
+
+    fallback = provider._responses_payload(  # noqa: SLF001
+        _provider_messages(),
+        model="gpt-5.5",
+        client_metadata={"session_id": "session-cache"},
+    )
+    explicit = provider._responses_payload(  # noqa: SLF001
+        _provider_messages(),
+        model="gpt-5.5",
+        prompt_cache_key="explicit-cache",
+        client_metadata={"session_id": "session-cache"},
+    )
+    absent = provider._responses_payload(  # noqa: SLF001
+        _provider_messages(),
+        model="gpt-5.5",
+    )
+    blank_session = provider._responses_payload(  # noqa: SLF001
+        _provider_messages(),
+        model="gpt-5.5",
+        client_metadata={"session_id": "   "},
+    )
+    explicit_with_blank_session = provider._responses_payload(  # noqa: SLF001
+        _provider_messages(),
+        model="gpt-5.5",
+        prompt_cache_key="explicit-cache",
+        client_metadata={"session_id": "   "},
+    )
+
+    assert fallback["prompt_cache_key"] == "session-cache"
+    assert explicit["prompt_cache_key"] == "explicit-cache"
+    assert "prompt_cache_key" not in absent
+    assert "prompt_cache_key" not in blank_session
+    assert explicit_with_blank_session["prompt_cache_key"] == "explicit-cache"
 
 
 def test_chat_stream_adds_responses_lite_header(monkeypatch):

{codex_as_api-0.6.3 → codex_as_api-0.6.4}/tests/test_server.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import hashlib
 import json
 import queue
 import threading
@@ -14,6 +15,14 @@ from codex_as_api.model_capabilities import LITE_HEADER_NAME, LITE_HEADER_VALUE,
 from codex_as_api.provider import REMOTE_COMPACTION_MARKER, ChatGPTOAuthProvider
 
 
+def _has_nested_key(value: object, key: str) -> bool:
+    if isinstance(value, dict):
+        return key in value or any(_has_nested_key(child, key) for child in value.values())
+    if isinstance(value, list):
+        return any(_has_nested_key(child, key) for child in value)
+    return False
+
+
 class RecordingBackend(NamedTuple):
     base_url: str
     requests: queue.Queue[dict[str, Any]]
@@ -519,6 +528,27 @@ def test_chat_handler_omits_standard_reasoning_mode_and_preserves_supported_fiel
     ]
 
 
+def test_chat_handler_codex_metadata_requires_client_session_before_upstream(
+    client,
+    recording_backend: RecordingBackend,
+):
+    response = client.post(
+        "/v1/chat/completions",
+        json={
+            "model": "gpt-5.6-sol",
+            "messages": [
+                {"role": "system", "content": "system"},
+                {"role": "user", "content": "hello"},
+            ],
+            "codex_metadata": True,
+        },
+    )
+
+    assert response.status_code == 400
+    assert response.json()["error"]["type"] == "chatgpt_oauth_error"
+    assert recording_backend.requests.empty()
+
+
 def test_chat_handler_rejects_pro_mode_before_upstream(
     client,
     recording_backend: RecordingBackend,
@@ -2076,6 +2106,213 @@ def test_anthropic_messages_uses_codex_model_for_provider_and_client_model_in_re
     assert resp.json()["model"] == "claude-sonnet-4-5"
 
 
+def test_anthropic_messages_uses_session_cache_affinity_without_codex_metadata(
+    client,
+    recording_backend: RecordingBackend,
+    monkeypatch,
+):
+    monkeypatch.setenv("CODEX_AS_API_CODEX_METADATA", "on")
+    payload = {
+        "model": "gpt-5.6-sol",
+        "max_tokens": 1024,
+        "system": "system",
+        "messages": [{"role": "user", "content": "hello"}],
+    }
+    session_id = "claude-session-123"
+    other_session_id = "claude-session-456"
+    expected = hashlib.sha256(f"codex-as-api:claude-code-session:{session_id}".encode()).hexdigest()
+    other_expected = hashlib.sha256(f"codex-as-api:claude-code-session:{other_session_id}".encode()).hexdigest()
+
+    first = client.post(
+        "/v1/messages",
+        headers={"x-claude-code-session-id": session_id},
+        json=payload,
+    )
+    second = client.post(
+        "/v1/messages",
+        headers={"x-claude-code-session-id": session_id},
+        json=payload,
+    )
+    third = client.post(
+        "/v1/messages",
+        headers={"x-claude-code-session-id": other_session_id},
+        json=payload,
+    )
+    explicit = client.post(
+        "/v1/messages",
+        headers={"x-claude-code-session-id": session_id},
+        json={**payload, "prompt_cache_key": "explicit-cache-key"},
+    )
+
+    assert first.status_code == second.status_code == third.status_code == explicit.status_code == 200
+    first_outbound = recording_backend.requests.get(timeout=1)["body"]
+    second_outbound = recording_backend.requests.get(timeout=1)["body"]
+    third_outbound = recording_backend.requests.get(timeout=1)["body"]
+    explicit_outbound = recording_backend.requests.get(timeout=1)["body"]
+    assert first_outbound["prompt_cache_key"] == expected
+    assert second_outbound["prompt_cache_key"] == expected
+    assert third_outbound["prompt_cache_key"] == other_expected
+    assert explicit_outbound["prompt_cache_key"] == "explicit-cache-key"
+    assert "client_metadata" not in first_outbound
+    assert "client_metadata" not in second_outbound
+    assert "client_metadata" not in third_outbound
+    assert "client_metadata" not in explicit_outbound
+    assert "response_id" not in first.json()
+    assert "response_id" not in second.json()
+    assert "response_id" not in third.json()
+    assert "response_id" not in explicit.json()
+
+
+def test_anthropic_messages_without_session_or_explicit_cache_key_omits_cache_key(
+    client,
+    recording_backend: RecordingBackend,
+):
+    response = client.post(
+        "/v1/messages",
+        json={
+            "model": "gpt-5.6-sol",
+            "max_tokens": 1024,
+            "system": "system",
+            "messages": [{"role": "user", "content": "hello"}],
+            "previous_response_id": None,
+        },
+    )
+
+    assert response.status_code == 200
+    assert "prompt_cache_key" not in recording_backend.requests.get(timeout=1)["body"]
+
+
+def test_anthropic_messages_accepts_and_strips_ephemeral_cache_control_hints(
+    client,
+    recording_backend: RecordingBackend,
+):
+    response = client.post(
+        "/v1/messages",
+        json={
+            "model": "gpt-5.6-sol",
+            "max_tokens": 1024,
+            "responses_lite": False,
+            "cache_control": {"type": "ephemeral"},
+            "system": [
+                {
+                    "type": "text",
+                    "text": "system",
+                    "cache_control": {"type": "ephemeral", "ttl": "1h"},
+                }
+            ],
+            "messages": [
+                {
+                    "role": "user",
+                    "cache_control": {"type": "ephemeral", "ttl": "5m"},
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": "hello",
+                            "cache_control": {"type": "ephemeral"},
+                        }
+                    ],
+                }
+            ],
+            "tools": [
+                {
+                    "name": "lookup",
+                    "description": "Lookup",
+                    "input_schema": {"type": "object"},
+                    "cache_control": {"type": "ephemeral", "ttl": "1h"},
+                }
+            ],
+        },
+    )
+
+    assert response.status_code == 200, response.text
+    outbound = recording_backend.requests.get(timeout=1)["body"]
+    assert not _has_nested_key(outbound, "cache_control")
+    assert outbound["instructions"] == "system"
+    assert outbound["input"][0]["content"][0]["text"] == "hello"
+    assert outbound["tools"][0]["name"] == "lookup"
+
+
+@pytest.mark.parametrize(
+    "cache_control_payload",
+    [
+        {"cache_control": "ephemeral"},
+        {"cache_control": {"type": "persistent"}},
+        {"cache_control": {"type": "ephemeral", "ttl": None}},
+        {
+            "system": [
+                {
+                    "type": "text",
+                    "text": "system",
+                    "cache_control": {"type": "ephemeral", "ttl": "24h"},
+                }
+            ]
+        },
+        {
+            "messages": [
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": "hello",
+                            "cache_control": {"type": "ephemeral", "extra": True},
+                        }
+                    ],
+                }
+            ]
+        },
+        {
+            "tools": [
+                {
+                    "name": "lookup",
+                    "input_schema": {"type": "object"},
+                    "cache_control": {"type": "ephemeral", "ttl": []},
+                }
+            ]
+        },
+    ],
+)
+def test_anthropic_messages_rejects_malformed_cache_control_before_upstream(
+    client,
+    recording_backend: RecordingBackend,
+    cache_control_payload,
+):
+    payload = {
+        "model": "gpt-5.6-sol",
+        "max_tokens": 1024,
+        "system": "system",
+        "messages": [{"role": "user", "content": "hello"}],
+        **cache_control_payload,
+    }
+    response = client.post("/v1/messages", json=payload)
+
+    assert response.status_code == 400
+    assert response.json()["type"] == "error"
+    assert response.json()["error"]["type"] == "invalid_request_error"
+    assert recording_backend.requests.empty()
+
+
+def test_anthropic_messages_rejects_non_null_previous_response_id_before_upstream(
+    client,
+    recording_backend: RecordingBackend,
+):
+    response = client.post(
+        "/v1/messages",
+        json={
+            "model": "gpt-5.6-sol",
+            "max_tokens": 1024,
+            "system": "system",
+            "messages": [{"role": "user", "content": "hello"}],
+            "previous_response_id": "resp-prior",
+        },
+    )
+
+    assert response.status_code == 400
+    assert response.json()["type"] == "error"
+    assert response.json()["error"]["type"] == "invalid_request_error"
+    assert recording_backend.requests.empty()
+
+
 def test_anthropic_latest_claude_code_shape_routes_known_gpt_effort_and_fast_mode(
     client,
     recording_backend: RecordingBackend,