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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-as-api
-Version: 0.6.3
+Version: 0.6.5
 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
@@ -165,7 +165,7 @@ Environment variables (Python, Rust, and TypeScript):
 | `CODEX_AS_API_PORT` | `18080` | Listen port |
 | `CODEX_AS_API_MODEL` | `~/.codex/config.toml` `model`, else `gpt-5.5` | Model identifier passed to Codex backend |
 | `CODEX_AS_API_AUTH_PATH` | `~/.codex/auth.json` | Path to OAuth credentials file |
-| `CODEX_AS_API_CODEX_CLI_VERSION` | latest `@openai/codex` from npm | Override the Codex CLI version used in backend request `User-Agent` headers |
+| `CODEX_AS_API_CODEX_CLI_VERSION` | `0.147.0` | Override the validated Codex compatibility baseline identified in backend request `User-Agent` headers |
 | `CODEX_AS_API_RESPONSES_LITE` | `auto` | Responses Lite mode: `auto`, `on`, or `off` |
 | `CODEX_AS_API_CODEX_METADATA` | `off` | Add Codex-style per-turn `client_metadata` and related backend headers |
 | `CODEX_HOME` | `~/.codex` | Codex home directory used for `auth.json` and `config.toml` discovery |
@@ -177,8 +177,8 @@ model = "gpt-5.6-sol"
 model_reasoning_effort = "high"
 
 # Optional overrides. Without them, known models use the bundled Codex catalog values.
-model_context_window = 372000
-model_auto_compact_token_limit = 334800
+model_context_window = 272000
+model_auto_compact_token_limit = 244800
 ```
 
 `CODEX_AS_API_MODEL` overrides the Codex config model. A request-level `reasoning_effort` overrides `model_reasoning_effort`; when both are omitted, known models use the Codex catalog default. The effective model, reasoning setting, and context settings are exposed from `/health`; context settings are also returned by Anthropic token-count responses.
@@ -198,7 +198,7 @@ model_auto_compact_token_limit = 334800
 | `gpt-5.3-codex-spark` | Ultra-fast coding model |
 | `gpt-5.2` | Previous generation model |
 
-Model capability behavior is driven by `config/model-capabilities.json` across Python, TypeScript, and Rust. The public `gpt-5.6` alias uses Sol's private Codex capability entry. The GPT-5.6 entries use the official Codex Responses Lite contract and a 372,000-token **Codex OAuth** context-window maximum; do not substitute the larger public API context figures for this backend. Larger config overrides are clamped to 372,000. Unknown models use conservative behavior: classic Responses payloads, no assumed parallel tool support, no automatic verbosity, reasoning-effort, or service-tier fields, and, without config overrides, the legacy 200,000-token context / 160,000-token compact thresholds.
+Model capability behavior is driven by `config/model-capabilities.json` across Python, TypeScript, and Rust. The public `gpt-5.6` alias uses Sol's private Codex capability entry. The GPT-5.6 entries use the official Codex Responses Lite contract and a 272,000-token **Codex OAuth** context-window maximum; do not substitute the larger public API context figures for this backend. Larger config overrides are clamped to 272,000. Unknown models use conservative behavior: classic Responses payloads, no assumed parallel tool support, no automatic verbosity, reasoning-effort, or service-tier fields, and, without config overrides, the legacy 200,000-token context / 160,000-token compact thresholds.
 
 To use a different port:
 
@@ -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 \
@@ -388,7 +411,7 @@ Health check. Returns auth availability, configured model and reasoning effort,
 
 ```bash
 curl http://localhost:18080/health
-# {"status":"ok","auth_available":true,"model":"gpt-5.6-sol","reasoning_effort":"high","codex_config_path":"/Users/me/.codex/config.toml","context_window":372000,"auto_compact_token_limit":334800}
+# {"status":"ok","auth_available":true,"model":"gpt-5.6-sol","reasoning_effort":"high","codex_config_path":"/Users/me/.codex/config.toml","context_window":272000,"auto_compact_token_limit":244800}
 ```
 
 ## Codex-Specific Features
@@ -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.147.0 [defaults this field to its Responses metadata session ID](https://github.com/openai/codex/blob/be6e8eac029b183056b7e4402879f15d2c85f61b/codex-rs/core/src/client.rs#L475-L487), and [projects the same value into `client_metadata.session_id`](https://github.com/openai/codex/blob/be6e8eac029b183056b7e4402879f15d2c85f61b/codex-rs/core/src/responses_metadata.rs#L219-L228), 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 Codex 0.147.0 [HTTP/WebSocket request structures](https://github.com/openai/codex/blob/be6e8eac029b183056b7e4402879f15d2c85f61b/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 Codex 0.147.0 SSE parser [takes semantic items from `response.output_item.done`](https://github.com/openai/codex/blob/be6e8eac029b183056b7e4402879f15d2c85f61b/codex-rs/codex-api/src/sse/responses.rs#L330-L341), while its [`response.completed` shape contains the response ID, usage, and `end_turn`](https://github.com/openai/codex/blob/be6e8eac029b183056b7e4402879f15d2c85f61b/codex-rs/codex-api/src/sse/responses.rs#L112-L160), 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.
 
@@ -710,7 +740,7 @@ HTTP Server (FastAPI / Axum / Express)
 ```
 
 The provider handles:
-- Token loading and automatic refresh on 401
+- Token loading, proactive refresh five minutes before expiry, and refresh on 401
 - OpenAI Responses API over SSE
 - `prompt_cache_key` and cache read/write accounting
 - GPT-5.6 reasoning effort/context plus `standard` mode compatibility
@@ -723,20 +753,32 @@ 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.
-- 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`.
+The `Release` GitHub Actions workflow runs on a pushed `v*` tag. It rejects a
+tag that does not exactly match every Python, npm, and Rust version surface,
+runs the complete cross-runtime gate, and then publishes PyPI, npmjs, the
+scoped GitHub npm package, platform Rust binaries, and one GitHub Release.
 
-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:
+The workflow uses registry-supported OIDC for PyPI and npmjs. No `PYPI_TOKEN`,
+`NPM_TOKEN`, personal access token, or repository secret is required. One-time
+registry setup is still required:
 
-```bash
-npm publish ./ts --access public
-```
+- Create GitHub environments named `pypi` and `npm`; add deployment protection
+  rules if desired.
+- On PyPI, add a trusted publisher for project `codex-as-api`, owner `Eunho-J`,
+  repository `codex-as-api`, workflow `release.yml`, environment `pypi`.
+- On npmjs, add a GitHub Actions trusted publisher for package `codex-as-api`,
+  owner `Eunho-J`, repository `codex-as-api`, workflow `release.yml`,
+  environment `npm`, with `npm publish` allowed.
+- GitHub Packages and GitHub Releases use the job-scoped automatic
+  `GITHUB_TOKEN`; repository policy must allow the workflow's declared
+  `packages: write` and `contents: write` permissions.
 
-Publishing to PyPI requires `UV_PUBLISH_TOKEN` and a freshly built distribution:
+After bumping every version and passing the local gate, push the matching tag:
 
 ```bash
-uv build --clear && uv publish dist/*
+python scripts/check_package_versions.py --tag v0.6.5
+git tag v0.6.5
+git push origin v0.6.5
 ```
 
 ## Tests
@@ -767,6 +809,35 @@ npm test
 
 ## Release Notes
 
+### v0.6.5
+
+- Align GPT-5.6 alias, Sol, Terra, and Luna context limits with Codex `0.147.0`
+  at 272,000 tokens and derive the 244,800-token automatic compact threshold.
+- Pin the verified upstream request, Responses Lite, header, and model contract
+  to `openai/codex` commit
+  `be6e8eac029b183056b7e4402879f15d2c85f61b`; track its new fractional SSE
+  rollout-budget field without claiming an unapproved facade mapping.
+- Refresh OAuth credentials five minutes before expiry, coalesce concurrent
+  refreshes, reload changed credentials after 401, and preserve upstream HTTP
+  status codes across all three servers.
+- Replace startup npm version discovery with deterministic compatibility and
+  package-version identity in the Codex-style `User-Agent`.
+- Add full cross-runtime CI plus tag-gated OIDC publishing to PyPI and npmjs,
+  `GITHUB_TOKEN` publishing to GitHub Packages, and GitHub Release assets.
+
+### 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.5}/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
@@ -131,7 +131,7 @@ Environment variables (Python, Rust, and TypeScript):
 | `CODEX_AS_API_PORT` | `18080` | Listen port |
 | `CODEX_AS_API_MODEL` | `~/.codex/config.toml` `model`, else `gpt-5.5` | Model identifier passed to Codex backend |
 | `CODEX_AS_API_AUTH_PATH` | `~/.codex/auth.json` | Path to OAuth credentials file |
-| `CODEX_AS_API_CODEX_CLI_VERSION` | latest `@openai/codex` from npm | Override the Codex CLI version used in backend request `User-Agent` headers |
+| `CODEX_AS_API_CODEX_CLI_VERSION` | `0.147.0` | Override the validated Codex compatibility baseline identified in backend request `User-Agent` headers |
 | `CODEX_AS_API_RESPONSES_LITE` | `auto` | Responses Lite mode: `auto`, `on`, or `off` |
 | `CODEX_AS_API_CODEX_METADATA` | `off` | Add Codex-style per-turn `client_metadata` and related backend headers |
 | `CODEX_HOME` | `~/.codex` | Codex home directory used for `auth.json` and `config.toml` discovery |
@@ -143,8 +143,8 @@ model = "gpt-5.6-sol"
 model_reasoning_effort = "high"
 
 # Optional overrides. Without them, known models use the bundled Codex catalog values.
-model_context_window = 372000
-model_auto_compact_token_limit = 334800
+model_context_window = 272000
+model_auto_compact_token_limit = 244800
 ```
 
 `CODEX_AS_API_MODEL` overrides the Codex config model. A request-level `reasoning_effort` overrides `model_reasoning_effort`; when both are omitted, known models use the Codex catalog default. The effective model, reasoning setting, and context settings are exposed from `/health`; context settings are also returned by Anthropic token-count responses.
@@ -164,7 +164,7 @@ model_auto_compact_token_limit = 334800
 | `gpt-5.3-codex-spark` | Ultra-fast coding model |
 | `gpt-5.2` | Previous generation model |
 
-Model capability behavior is driven by `config/model-capabilities.json` across Python, TypeScript, and Rust. The public `gpt-5.6` alias uses Sol's private Codex capability entry. The GPT-5.6 entries use the official Codex Responses Lite contract and a 372,000-token **Codex OAuth** context-window maximum; do not substitute the larger public API context figures for this backend. Larger config overrides are clamped to 372,000. Unknown models use conservative behavior: classic Responses payloads, no assumed parallel tool support, no automatic verbosity, reasoning-effort, or service-tier fields, and, without config overrides, the legacy 200,000-token context / 160,000-token compact thresholds.
+Model capability behavior is driven by `config/model-capabilities.json` across Python, TypeScript, and Rust. The public `gpt-5.6` alias uses Sol's private Codex capability entry. The GPT-5.6 entries use the official Codex Responses Lite contract and a 272,000-token **Codex OAuth** context-window maximum; do not substitute the larger public API context figures for this backend. Larger config overrides are clamped to 272,000. Unknown models use conservative behavior: classic Responses payloads, no assumed parallel tool support, no automatic verbosity, reasoning-effort, or service-tier fields, and, without config overrides, the legacy 200,000-token context / 160,000-token compact thresholds.
 
 To use a different port:
 
@@ -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 \
@@ -354,7 +377,7 @@ Health check. Returns auth availability, configured model and reasoning effort,
 
 ```bash
 curl http://localhost:18080/health
-# {"status":"ok","auth_available":true,"model":"gpt-5.6-sol","reasoning_effort":"high","codex_config_path":"/Users/me/.codex/config.toml","context_window":372000,"auto_compact_token_limit":334800}
+# {"status":"ok","auth_available":true,"model":"gpt-5.6-sol","reasoning_effort":"high","codex_config_path":"/Users/me/.codex/config.toml","context_window":272000,"auto_compact_token_limit":244800}
 ```
 
 ## Codex-Specific Features
@@ -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.147.0 [defaults this field to its Responses metadata session ID](https://github.com/openai/codex/blob/be6e8eac029b183056b7e4402879f15d2c85f61b/codex-rs/core/src/client.rs#L475-L487), and [projects the same value into `client_metadata.session_id`](https://github.com/openai/codex/blob/be6e8eac029b183056b7e4402879f15d2c85f61b/codex-rs/core/src/responses_metadata.rs#L219-L228), 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 Codex 0.147.0 [HTTP/WebSocket request structures](https://github.com/openai/codex/blob/be6e8eac029b183056b7e4402879f15d2c85f61b/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 Codex 0.147.0 SSE parser [takes semantic items from `response.output_item.done`](https://github.com/openai/codex/blob/be6e8eac029b183056b7e4402879f15d2c85f61b/codex-rs/codex-api/src/sse/responses.rs#L330-L341), while its [`response.completed` shape contains the response ID, usage, and `end_turn`](https://github.com/openai/codex/blob/be6e8eac029b183056b7e4402879f15d2c85f61b/codex-rs/codex-api/src/sse/responses.rs#L112-L160), 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.
 
@@ -676,7 +706,7 @@ HTTP Server (FastAPI / Axum / Express)
 ```
 
 The provider handles:
-- Token loading and automatic refresh on 401
+- Token loading, proactive refresh five minutes before expiry, and refresh on 401
 - OpenAI Responses API over SSE
 - `prompt_cache_key` and cache read/write accounting
 - GPT-5.6 reasoning effort/context plus `standard` mode compatibility
@@ -689,20 +719,32 @@ 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.
-- 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`.
+The `Release` GitHub Actions workflow runs on a pushed `v*` tag. It rejects a
+tag that does not exactly match every Python, npm, and Rust version surface,
+runs the complete cross-runtime gate, and then publishes PyPI, npmjs, the
+scoped GitHub npm package, platform Rust binaries, and one GitHub Release.
 
-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:
+The workflow uses registry-supported OIDC for PyPI and npmjs. No `PYPI_TOKEN`,
+`NPM_TOKEN`, personal access token, or repository secret is required. One-time
+registry setup is still required:
 
-```bash
-npm publish ./ts --access public
-```
+- Create GitHub environments named `pypi` and `npm`; add deployment protection
+  rules if desired.
+- On PyPI, add a trusted publisher for project `codex-as-api`, owner `Eunho-J`,
+  repository `codex-as-api`, workflow `release.yml`, environment `pypi`.
+- On npmjs, add a GitHub Actions trusted publisher for package `codex-as-api`,
+  owner `Eunho-J`, repository `codex-as-api`, workflow `release.yml`,
+  environment `npm`, with `npm publish` allowed.
+- GitHub Packages and GitHub Releases use the job-scoped automatic
+  `GITHUB_TOKEN`; repository policy must allow the workflow's declared
+  `packages: write` and `contents: write` permissions.
 
-Publishing to PyPI requires `UV_PUBLISH_TOKEN` and a freshly built distribution:
+After bumping every version and passing the local gate, push the matching tag:
 
 ```bash
-uv build --clear && uv publish dist/*
+python scripts/check_package_versions.py --tag v0.6.5
+git tag v0.6.5
+git push origin v0.6.5
 ```
 
 ## Tests
@@ -733,6 +775,35 @@ npm test
 
 ## Release Notes
 
+### v0.6.5
+
+- Align GPT-5.6 alias, Sol, Terra, and Luna context limits with Codex `0.147.0`
+  at 272,000 tokens and derive the 244,800-token automatic compact threshold.
+- Pin the verified upstream request, Responses Lite, header, and model contract
+  to `openai/codex` commit
+  `be6e8eac029b183056b7e4402879f15d2c85f61b`; track its new fractional SSE
+  rollout-budget field without claiming an unapproved facade mapping.
+- Refresh OAuth credentials five minutes before expiry, coalesce concurrent
+  refreshes, reload changed credentials after 401, and preserve upstream HTTP
+  status codes across all three servers.
+- Replace startup npm version discovery with deterministic compatibility and
+  package-version identity in the Codex-style `User-Agent`.
+- Add full cross-runtime CI plus tag-gated OIDC publishing to PyPI and npmjs,
+  `GITHUB_TOKEN` publishing to GitHub Packages, and GitHub Release assets.
+
+### 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.5}/RELEASES.md

@@ -1,5 +1,83 @@
 # Release Notes
 
+## v0.6.5
+
+### Codex 0.147 compatibility
+
+- Align GPT-5.6 alias, Sol, Terra, and Luna context limits with the stable
+  Codex 0.147 catalog at 272,000 tokens. Automatic compact defaults now derive
+  to 244,800 tokens.
+- Pin a structured compatibility fixture to `openai/codex` 0.147.0 commit
+  `be6e8eac029b183056b7e4402879f15d2c85f61b`, covering the model fields,
+  Responses request path, Lite behavior, and originator header. The fractional
+  `codex_rollout_budget_units` usage field is tracked as upstream-only because
+  this facade has no approved public mapping for it.
+- Replace the moving startup `npm view @openai/codex version` lookup with a
+  deterministic Codex compatibility baseline and `codex-as-api` package
+  version in the request `User-Agent`.
+
+### Authentication and errors
+
+- Refresh OAuth access tokens five minutes before expiry, coalesce concurrent
+  refresh work, and reload credentials changed by another request before
+  rotating a refresh token after HTTP 401.
+- Preserve the existing root or nested auth-file layout, reject account
+  switches and conflicting token claims, and compare the credential snapshot
+  again before persisting a refresh response.
+- Preserve upstream HTTP statuses, including rate-limit and overload responses,
+  in Python and TypeScript to match Rust.
+
+### CI and publishing
+
+- Add pull-request and push CI for Python tests, Ruff, mypy, package builds,
+  TypeScript tests/build/package checks, and Rust format, Clippy, tests, and
+  release builds.
+- Add a tag-triggered release workflow that requires exact tag/package version
+  agreement and the full cross-runtime gate before publishing.
+- Publish PyPI and npmjs through trusted-publisher OIDC, GitHub Packages and
+  GitHub Releases through the automatic repository `GITHUB_TOKEN`, and attach
+  Python/npm distributions plus Linux, macOS, and Windows Rust binaries.
+- Remove the manual npm workflow that could report success after silently
+  skipping npmjs publication when `NPM_TOKEN` was absent.
+
+## 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