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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-as-api
-Version: 0.6.2
+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).
 
@@ -444,7 +467,7 @@ GPT-5.6 requests can instead use the public Responses-shaped object:
 - Responses Lite uses `all_turns` as the Codex wire default. An explicitly different context is rejected instead of silently overwritten; use `responses_lite: false` when the backend route supports classic Responses and another context is required.
 - Remote compact keeps its existing private Codex `reasoning_effort` field but does not accept public `reasoning.mode` or `reasoning.context`.
 
-Anthropic `thinking` values map as `enabled → high`, `adaptive → medium`, and `disabled → none`. Claude Code's `output_config.effort` takes precedence over the adaptive default and supports `low`, `medium`, `high`, `xhigh`, and `max`. The supported reasoning context and verbosity extensions are also available on `/v1/messages`, image generation, and inspection requests; Pro and non-null public cache policy/breakpoints or `safety_identifier` fail explicitly on the private Codex provider.
+Anthropic `thinking` values map as `enabled → high`, `adaptive → medium`, and `disabled → none`. Claude Code's `output_config.effort` takes precedence over adaptive or enabled thinking and supports `low`, `medium`, `high`, `xhigh`, and `max`. Call-level `thinking.disabled` takes precedence over ambient `output_config.effort`, so Claude Code WebSearch/WebFetch auxiliary calls use `none` instead of failing the compatibility check with HTTP 400. The supported reasoning context and verbosity extensions are also available on `/v1/messages`, image generation, and inspection requests; Pro and non-null public cache policy/breakpoints or `safety_identifier` fail explicitly on the private Codex provider.
 
 The pinned official Codex HTTP request has no `stop` field. Omitted, `null`, and empty stop values are omitted from the private request; any non-empty OpenAI `stop` or Anthropic `stop_sequences` value returns HTTP 400 before the private transport starts.
 
@@ -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,14 +665,18 @@ 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:
 
 ```bash
-CODEX_AS_API_MODEL=gpt-5.6-terra codex-as-api
+CODEX_AS_API_MODEL=gpt-5.6-terra \
+CODEX_AS_API_RESPONSES_LITE=off \
+codex-as-api
 ```
 
+`CODEX_AS_API_RESPONSES_LITE=off` is required for Claude Code hosted WebSearch on GPT-5.6. Official Codex Responses Lite uses a client-side standalone `web.run` tool, while this gateway receives Anthropic's hosted `web_search` declaration and has no standalone executor; classic Responses preserves that hosted tool. WebFetch does not use a hosted Responses tool, but still needs the disabled-thinking precedence fix when process-level effort is enabled.
+
 To keep the built-in Fable, Opus, Sonnet, and Haiku rows and append one GPT row, launch the GPT-routed Claude Code process with these variables:
 
 ```bash
@@ -662,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.
 
@@ -720,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.2` 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:
@@ -763,6 +797,27 @@ 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`.
+- Give explicit disabled thinking precedence and send Codex reasoning effort `none` instead of returning HTTP 400.
+- Document and test `CODEX_AS_API_RESPONSES_LITE=off` for Claude Code hosted WebSearch on GPT-5.6; WebFetch needs no Responses Lite override.
+- Preserve fail-loudly validation for invalid effort values and unsupported `output_config` fields.
+- Add Python, TypeScript, and Rust adapter regressions, streamed `/v1/messages` coverage, and a `/count_tokens` regression for the WebSearch/WebFetch request shape.
+
 ### v0.6.2
 
 - Fix `/v1/messages/count_tokens` overcounting that could trigger Claude Code autocompaction on every turn.

{codex_as_api-0.6.2 → 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).
 
@@ -410,7 +433,7 @@ GPT-5.6 requests can instead use the public Responses-shaped object:
 - Responses Lite uses `all_turns` as the Codex wire default. An explicitly different context is rejected instead of silently overwritten; use `responses_lite: false` when the backend route supports classic Responses and another context is required.
 - Remote compact keeps its existing private Codex `reasoning_effort` field but does not accept public `reasoning.mode` or `reasoning.context`.
 
-Anthropic `thinking` values map as `enabled → high`, `adaptive → medium`, and `disabled → none`. Claude Code's `output_config.effort` takes precedence over the adaptive default and supports `low`, `medium`, `high`, `xhigh`, and `max`. The supported reasoning context and verbosity extensions are also available on `/v1/messages`, image generation, and inspection requests; Pro and non-null public cache policy/breakpoints or `safety_identifier` fail explicitly on the private Codex provider.
+Anthropic `thinking` values map as `enabled → high`, `adaptive → medium`, and `disabled → none`. Claude Code's `output_config.effort` takes precedence over adaptive or enabled thinking and supports `low`, `medium`, `high`, `xhigh`, and `max`. Call-level `thinking.disabled` takes precedence over ambient `output_config.effort`, so Claude Code WebSearch/WebFetch auxiliary calls use `none` instead of failing the compatibility check with HTTP 400. The supported reasoning context and verbosity extensions are also available on `/v1/messages`, image generation, and inspection requests; Pro and non-null public cache policy/breakpoints or `safety_identifier` fail explicitly on the private Codex provider.
 
 The pinned official Codex HTTP request has no `stop` field. Omitted, `null`, and empty stop values are omitted from the private request; any non-empty OpenAI `stop` or Anthropic `stop_sequences` value returns HTTP 400 before the private transport starts.
 
@@ -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,14 +631,18 @@ 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:
 
 ```bash
-CODEX_AS_API_MODEL=gpt-5.6-terra codex-as-api
+CODEX_AS_API_MODEL=gpt-5.6-terra \
+CODEX_AS_API_RESPONSES_LITE=off \
+codex-as-api
 ```
 
+`CODEX_AS_API_RESPONSES_LITE=off` is required for Claude Code hosted WebSearch on GPT-5.6. Official Codex Responses Lite uses a client-side standalone `web.run` tool, while this gateway receives Anthropic's hosted `web_search` declaration and has no standalone executor; classic Responses preserves that hosted tool. WebFetch does not use a hosted Responses tool, but still needs the disabled-thinking precedence fix when process-level effort is enabled.
+
 To keep the built-in Fable, Opus, Sonnet, and Haiku rows and append one GPT row, launch the GPT-routed Claude Code process with these variables:
 
 ```bash
@@ -628,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.
 
@@ -686,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.2` 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:
@@ -729,6 +763,27 @@ 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`.
+- Give explicit disabled thinking precedence and send Codex reasoning effort `none` instead of returning HTTP 400.
+- Document and test `CODEX_AS_API_RESPONSES_LITE=off` for Claude Code hosted WebSearch on GPT-5.6; WebFetch needs no Responses Lite override.
+- Preserve fail-loudly validation for invalid effort values and unsupported `output_config` fields.
+- Add Python, TypeScript, and Rust adapter regressions, streamed `/v1/messages` coverage, and a `/count_tokens` regression for the WebSearch/WebFetch request shape.
+
 ### v0.6.2
 
 - Fix `/v1/messages/count_tokens` overcounting that could trigger Claude Code autocompaction on every turn.

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

@@ -1,5 +1,58 @@
 # 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
+
+- Fix HTTP 400 responses when a Claude Code session with ambient effort sends a WebSearch/WebFetch auxiliary request containing both `output_config.effort` and call-level `thinking: {"type":"disabled"}`.
+- Give explicit disabled thinking precedence over valid ambient effort and forward Codex reasoning effort `none` across Python, TypeScript, and Rust.
+- Require and document `CODEX_AS_API_RESPONSES_LITE=off` for Claude Code hosted WebSearch on GPT-5.6 because official Responses Lite relies on a standalone `web.run` executor; WebFetch does not require this override.
+- Continue rejecting empty, non-string, or unsupported effort values and unsupported `output_config` fields rather than silently discarding malformed requests.
+
+### Validation
+
+- Adapter tests cover every valid Claude Code effort value paired with disabled thinking while retaining invalid-value failures.
+- Streamed `/v1/messages` tests across all three runtimes and a local `/count_tokens` test reproduce the Claude Code 2.1.209 request shape and prove provider-backed requests reach the classic Codex wire with reasoning effort `none`.
+- A real GPT-5.6 Sol Codex OAuth WebSearch completed with HTTP 200 and structured `server_tool_use`, `web_search_tool_result`, and terminal SSE events.
+
 ## v0.6.2
 
 ### Claude Code count_tokens autocompact fix
@@ -9,7 +62,7 @@
 - Count tool calls, tool-result identifiers, reasoning content, and normalized tool schemas once while excluding model IDs, output limits, stream flags, metadata, and other non-model request controls.
 - Keep the existing image estimate separate so URL and inline base64 images are counted once without tokenizing the base64 payload as text.
 - Keep token counting local and OAuth-free. No `tiktoken` package dependency or first-run encoding download is introduced.
-- Record the upstream synchronization point as `tiktoken` 0.13.0 commit `08a5f3b2c987ada4fc5aa1f16c643c203fa8acaa`, checked on 2026-07-14, with the official rank-file SHA-256 verified in packaged builds.
+- Record the upstream synchronization point as `tiktoken` 0.13.0 commit `08a5f3b2c987ada4fc5aa1f16c643c203fa8acaa`, checked on 2026-07-14, with the official rank-file SHA-256 verified during release validation.
 
 ### Validation
 

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codex-as-api"
-version = "0.6.2"
+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.2 → 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.2"
+__version__ = "0.6.4"

{codex_as_api-0.6.2 → codex_as_api-0.6.4}/src/codex_as_api/anthropic_adapter.py

@@ -341,13 +341,19 @@ def _convert_reasoning_effort(thinking: dict[str, Any] | None, output_config: ob
             raise ValueError("output_config.task_budget is not supported by the Codex OAuth backend")
         raw_effort = output_config.get("effort")
         if raw_effort is not None:
-            if raw_effort not in {"low", "medium", "high", "xhigh", "max"}:
+            if not isinstance(raw_effort, str) or raw_effort not in {
+                "low",
+                "medium",
+                "high",
+                "xhigh",
+                "max",
+            }:
                 raise ValueError("output_config.effort must be one of: low, medium, high, xhigh, max")
             output_effort = raw_effort
 
     thinking_effort = _convert_thinking(thinking)
-    if thinking_effort == "none" and output_effort is not None:
-        raise ValueError("output_config.effort cannot be represented together with thinking.disabled")
+    if thinking_effort == "none":
+        return "none"
     return output_effort or thinking_effort
 
 

{codex_as_api-0.6.2 → 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.2 → 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,