Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
fix(docker): install the redis extra in every image (#4514)
AlessandroSpallina8d5dde77656c
diff --git a/Dockerfile b/Dockerfileindex ed1fdb2f7..1915e8f35 100644--- a/Dockerfile+++ b/Dockerfile@@ -50,7 +50,9 @@ COPY headroom/ headroom/# The standalone Dockerfile must support every backend advertised by# `headroom proxy --backend`, including Bedrock temporary/SSO credentials.# Those credentials require botocore (GH #1551), supplied by [bedrock].-ARG HEADROOM_EXTRAS=proxy,code,bedrock+# [redis] backs the replica-shared stores: without it HEADROOM_COMPRESS_SESSION_STORE+# stops startup and HEADROOM_CCR_BACKEND=redis falls back to a per-process store.+ARG HEADROOM_EXTRAS=proxy,code,bedrock,redis# `uv pip install` ignores [tool.uv] override-dependencies (uv.lock only), so# pass them explicitly: the image gets the security overrides the lock has# (pillow 13 over fastembed's <13 cap).diff --git a/docker-bake.hcl b/docker-bake.hclindex f7ca8aacd..5b6264847 100644--- a/docker-bake.hcl+++ b/docker-bake.hcl@@ -10,7 +10,7 @@ target "runtime-default" {inherits = ["_common", "docker-metadata-action"]target = "runtime"args = {- HEADROOM_EXTRAS = "proxy,bedrock"+ HEADROOM_EXTRAS = "proxy,bedrock,redis"RUNTIME_USER = "nonroot"}}@@ -19,7 +19,7 @@ target "runtime" {inherits = ["_common", "docker-metadata-action"]target = "runtime"args = {- HEADROOM_EXTRAS = "proxy,bedrock"+ HEADROOM_EXTRAS = "proxy,bedrock,redis"RUNTIME_USER = "root"}}@@ -28,7 +28,7 @@ target "runtime-nonroot" {inherits = ["_common", "docker-metadata-action"]target = "runtime"args = {- HEADROOM_EXTRAS = "proxy,bedrock"+ HEADROOM_EXTRAS = "proxy,bedrock,redis"RUNTIME_USER = "nonroot"}}@@ -37,7 +37,7 @@ target "runtime-code" {inherits = ["_common", "docker-metadata-action"]target = "runtime"args = {- HEADROOM_EXTRAS = "proxy,code,bedrock"+ HEADROOM_EXTRAS = "proxy,code,bedrock,redis"RUNTIME_USER = "root"}}@@ -46,7 +46,7 @@ target "runtime-code-nonroot" {inherits = ["_common", "docker-metadata-action"]target = "runtime"args = {- HEADROOM_EXTRAS = "proxy,code,bedrock"+ HEADROOM_EXTRAS = "proxy,code,bedrock,redis"RUNTIME_USER = "nonroot"}}@@ -55,7 +55,7 @@ target "runtime-slim" {inherits = ["_common", "docker-metadata-action"]target = "runtime-slim"args = {- HEADROOM_EXTRAS = "proxy,bedrock"+ HEADROOM_EXTRAS = "proxy,bedrock,redis"RUNTIME_USER = "root"}}@@ -64,7 +64,7 @@ target "runtime-slim-nonroot" {inherits = ["_common", "docker-metadata-action"]target = "runtime-slim"args = {- HEADROOM_EXTRAS = "proxy,bedrock"+ HEADROOM_EXTRAS = "proxy,bedrock,redis"RUNTIME_USER = "nonroot"}}@@ -73,7 +73,7 @@ target "runtime-code-slim" {inherits = ["_common", "docker-metadata-action"]target = "runtime-slim"args = {- HEADROOM_EXTRAS = "proxy,code,bedrock"+ HEADROOM_EXTRAS = "proxy,code,bedrock,redis"RUNTIME_USER = "root"}}@@ -82,7 +82,7 @@ target "runtime-code-slim-nonroot" {inherits = ["_common", "docker-metadata-action"]target = "runtime-slim"args = {- HEADROOM_EXTRAS = "proxy,code,bedrock"+ HEADROOM_EXTRAS = "proxy,code,bedrock,redis"RUNTIME_USER = "nonroot"}}diff --git a/docs/content/docs/installation.mdx b/docs/content/docs/installation.mdxindex 895763055..4f82b3bdd 100644--- a/docs/content/docs/installation.mdx+++ b/docs/content/docs/installation.mdx@@ -116,6 +116,7 @@ pip install "headroom-ai[all]"| `autogen` | AutoGen AgentChat integration; **not in `[all]`** | `pip install "headroom-ai[autogen]"` || `anyllm` | any-llm multi-provider backend (Python 3.11+); **not in `[all]`** | `pip install "headroom-ai[anyllm]"` || `bedrock` | Native AWS Bedrock credentials/backend support; **not in `[all]`** | `pip install "headroom-ai[bedrock]"` |+| `redis` | Redis client for state shared across replicas (`HEADROOM_CCR_BACKEND=redis`, `HEADROOM_COMPRESS_SESSION_STORE`); **not in `[all]`**, included in every Docker image | `pip install "headroom-ai[redis]"` || `evals` | Evaluation framework (GSM8K, SQuAD, BFCL benchmarks) | `pip install "headroom-ai[evals]"` || `pytorch-mps` | Apple-GPU (MPS) memory-embedder offload — **macOS only**, not in `[all]` (torch + sentence-transformers); opt in with `HEADROOM_EMBEDDER_RUNTIME=pytorch_mps` | `pip install "headroom-ai[pytorch-mps]"` || `html` | HTML main-content extraction with trafilatura | `pip install "headroom-ai[html]"` |@@ -255,15 +256,15 @@ If you want a host `headroom` CLI that keeps Headroom itself inside a container| Tag | Extras | Base image | Description ||---|---|---|---|-| `latest` | `proxy,bedrock` | Debian slim | Default image, runs as non-root |-| `<version>` | `proxy,bedrock` | Debian slim | Pinned release, same default variant |-| `nonroot` | `proxy,bedrock` | Debian slim | Explicit non-root variant |-| `code` | `proxy,code,bedrock` | Debian slim | Includes tree-sitter for code compression |-| `code-nonroot` | `proxy,code,bedrock` | Debian slim | Code compression, non-root |-| `slim` | `proxy,bedrock` | Distroless | Minimal image, no shell |-| `slim-nonroot` | `proxy,bedrock` | Distroless | Minimal, non-root |-| `code-slim` | `proxy,code,bedrock` | Distroless | Code compression, minimal |-| `code-slim-nonroot` | `proxy,code,bedrock` | Distroless | Code compression, minimal, non-root |+| `latest` | `proxy,bedrock,redis` | Debian slim | Default image, runs as non-root |+| `<version>` | `proxy,bedrock,redis` | Debian slim | Pinned release, same default variant |+| `nonroot` | `proxy,bedrock,redis` | Debian slim | Explicit non-root variant |+| `code` | `proxy,code,bedrock,redis` | Debian slim | Includes tree-sitter for code compression |+| `code-nonroot` | `proxy,code,bedrock,redis` | Debian slim | Code compression, non-root |+| `slim` | `proxy,bedrock,redis` | Distroless | Minimal image, no shell |+| `slim-nonroot` | `proxy,bedrock,redis` | Distroless | Minimal, non-root |+| `code-slim` | `proxy,code,bedrock,redis` | Distroless | Code compression, minimal |+| `code-slim-nonroot` | `proxy,code,bedrock,redis` | Distroless | Code compression, minimal, non-root |### Build from sourcediff --git a/docs/content/docs/proxy.mdx b/docs/content/docs/proxy.mdxindex cd1a7ac18..0b3f12b7c 100644--- a/docs/content/docs/proxy.mdx+++ b/docs/content/docs/proxy.mdx@@ -652,7 +652,7 @@ Keep carrying both yourself and send them upstream unchanged. Two consequences w| `transforms_applied` | array | Transform labels that ran. || `transforms_summary` | object | Per-transform counts. || `ccr_hashes` | array | Retrieval hashes for markers inserted (empty unless `mode: "ccr"`). |-| `session` | object | [Session mode](#session-mode) only: `{ "id", "frozen_message_count", "cached_prefix_replayed" }`. |+| `session` | object | [Session mode](#session-mode) only: `{ "id", "frozen_message_count", "cached_prefix_replayed" }`, described there. |```json{@@ -741,15 +741,27 @@ Pass `config.session_id` and Headroom keeps the conversation's replay state itseThe response gains a `session` object:```json-"session": { "id": "conv-8f1c", "frozen_message_count": 12, "cached_prefix_replayed": true }+"session": { "id": "conv-8f1c", "frozen_message_count": 12, "cached_prefix_replayed": false }```+| Field | Type | Description |+| --- | --- | --- |+| `id` | string | The session id this turn ran under: `config.session_id` as sent, or the `x-headroom-session-id` header when `HEADROOM_COMPRESS_SESSION_FROM_HEADER=1` and `config.session_id` is absent. |+| `frozen_message_count` | integer | How many leading messages the pipeline was told not to recompress this turn. Headroom counts the leading run it can replay from the session's compression cache: plain messages always count, a tool result counts only once its content is in that cache, and the last message never counts. An explicit `config.frozen_message_count` wins when larger. It is derived from Headroom's own state, not from the provider, and it can be non-zero on a first turn. |+| `cached_prefix_replayed` | boolean | `true` when the pipeline's output for some leading messages differed from what this endpoint returned for the session last turn, and Headroom overwrote those messages with last turn's bytes. `false` when nothing was overwritten: when the serving process holds no previous turn for the session (a first turn, expired state, or a replica that never served or loaded it), when the pipeline already produced last turn's bytes (the usual case), or when the replay was skipped as unsafe (this turn's messages do not line up with last turn's, or the replay would be larger than the pipeline's output). So `false` does not mean the returned prefix matches last turn's. |++<Callout type="warning" title="cached_prefix_replayed is not a prompt-cache hit">+`cached_prefix_replayed` reports Headroom's own repair step. It says nothing about whether the provider served the prefix from its prompt cache. `false` is the normal value on a healthy session, and it is also what a turn that changed the prefix returns when there was nothing to replay. Read cache hits and misses from the provider's usage (`cache_read_input_tokens`, `prompt_tokens_details.cached_tokens`).+</Callout>+What differs from the stateless contract:- **Forward the returned messages verbatim.** They are what the next turn replays.- **`compress_user_messages` is refused** (`400`). User-message rewrites are not byte-replayable across turns, so they would bust the prefix later.- **Timeouts and busy sessions are a `503`, never fail-open.** Handing back originals would leave the caller forwarding bytes the replay state does not know about, so a compression timeout answers `503` with `error.type = "compression_timeout"`; retry the turn and it lands on consistent state. Turns for one session are serialized under a per-session lock, and a concurrent turn for the same session that waits more than 10 seconds gets the same `503`.-- **State is in-process.** The replay cache lives for `HEADROOM_COMPRESSION_CACHE_TTL_SECONDS` of idle time (3900 by default, floor 600); the tracker's usage state expires after 10 idle minutes. Multi-process deployments (gunicorn workers, replicas) must pin a session to one process — hash the upstream on the session id — or replay silently misses.+- **State is in-process by default.** The replay cache lives for `HEADROOM_COMPRESSION_CACHE_TTL_SECONDS` of idle time (3900 by default, floor 600); the tracker's usage state expires after 10 idle minutes. Without a shared store, multi-process deployments (gunicorn workers, replicas) must pin a session to one process — hash the upstream on the session id — or replay silently misses.+- **`HEADROOM_COMPRESS_SESSION_STORE=redis://...` shares sessions across replicas.** Every replica also keeps each session's tracker in Redis, so any replica can serve the session's next turn and its `POST /v1/usage`. It needs the `redis` extra, which every Docker image includes. It also selects the Redis CCR store unless `HEADROOM_CCR_BACKEND` names another, so CCR markers resolve on any replica. Two limits remain. The per-session lock is per process: two concurrent turns of one session on two replicas both run, the first write wins (compare-and-set), and the next turn continues from the winner. Gateway-mode pending turns stay in-process, so `POST /v1/compress/response` must reach the replica that answered the request half; re-drive therefore still needs real affinity (`gateway.session_affinity`).+- **An unreachable Redis does not fail turns.** A Redis error is a miss: the replica serves from its own memory, logs one `WARNING` when a kind of call (read, write) starts failing and an `INFO` when it works again, and skips Redis for 5 seconds after a connection error (each command times out after 1 second). The cost is the sharing. A replica with no local state for the session recompresses the history, which is slower, and the prefix it returns can differ from last turn's, which is a provider prompt-cache miss. `cached_prefix_replayed` stays `false` on those turns. A Redis that comes back empty is refilled as each session's next turn writes it whole. Run Redis with high availability if prompt-cache hits matter.- `HEADROOM_COMPRESS_SESSION_FROM_HEADER=1` lets the `x-headroom-session-id` header stand in for `config.session_id`. Off by default: gateways commonly stamp that header on all traffic, and a value shared across conversations (Claude Code subagents do this) would blend them into one replay state.**Relaying provider usage: `POST /v1/usage`.** Session mode never sees the provider's response, so cache-hit attribution and savings accounting for the session come from this optional relay (same exposure rules as `/v1/compress`). Post the provider's `usage` block under the session id:@@ -779,7 +791,7 @@ The rule behind it is the proxy's own **no shrink without reload**, moved to the| --- | --- | --- | --- || `can_redrive` | boolean | `false` | The gateway can call the provider again with a request Headroom hands it and post the result back. Unlocks re-driving turn hooks and, with `config.mode: "ccr"`, in-band CCR retrieval. Send `false` for streaming requests. || `can_relay_response` | boolean | `false` | The gateway will post the provider's status and usage to `/v1/compress/response` after every turn. |-| `session_affinity` | boolean | `true` | The gateway pins this session to one Headroom replica. Pending turns are in-process state, so `false` disables re-driving for the turn even when `can_redrive` is set. |+| `session_affinity` | boolean | `true` | The gateway pins this session to one Headroom replica. Pending turns are in-process state, so `false` disables re-driving for the turn even when `can_redrive` is set. `HEADROOM_COMPRESS_SESSION_STORE` shares replay state, not pending turns, so it does not lift this. || `plugin_version` | string | unset | Diagnostics only. || `request_headers` | object | `{}` | The client's request headers the gateway is willing to hand over, as lowercase name → string value. Only `anthropic-beta` is read today: when a turn hook asks for an `anthropic-beta` token, the client's tokens go first in the returned `headers`; every other name is ignored, so a gateway may pass its whole header map. A non-object block or a non-string value is a `400`. Never forwarded anywhere by Headroom. |diff --git a/tests/test_release_workflows.py b/tests/test_release_workflows.pyindex 8f2ed84f5..1f5410ffb 100644--- a/tests/test_release_workflows.py+++ b/tests/test_release_workflows.py@@ -156,6 +156,29 @@ def test_every_published_docker_variant_includes_bedrock_auth_dependencies() ->assert {"boto3", "botocore"} <= bedrock_names+def test_every_docker_variant_includes_the_redis_extra() -> None:+ """Without the client, HEADROOM_COMPRESS_SESSION_STORE=redis:// stops+ startup and HEADROOM_CCR_BACKEND=redis falls back to a per-process store,+ so the 0.42 image could use neither. Keep the Dockerfile default and every+ bake target on [redis]."""+ dockerfile = (ROOT / "Dockerfile").read_text(encoding="utf-8")+ defaults = re.findall(r"^ARG HEADROOM_EXTRAS=(\S+)$", dockerfile, re.MULTILINE)+ assert len(defaults) == 1, defaults+ assert "redis" in defaults[0].split(",")++ bake = (ROOT / "docker-bake.hcl").read_text(encoding="utf-8")+ targets = re.findall(r'^\s*HEADROOM_EXTRAS = "([^"]*)"$', bake, re.MULTILINE)+ assert len(targets) == 9+ assert all("redis" in extras.split(",") for extras in targets), targets++ project = tomllib.loads((ROOT / "pyproject.toml").read_text(encoding="utf-8"))+ redis_names = {+ Requirement(requirement).name+ for requirement in project["project"]["optional-dependencies"]["redis"]+ }+ assert "redis" in redis_names++def test_public_docker_instructions_use_the_current_organization_package() -> None:"""Do not send users back to the personal GHCR package frozen at 0.27.0."""public_docs = (diff --git a/wiki/proxy.md b/wiki/proxy.mdindex 6862ee842..6bc0d3c80 100644--- a/wiki/proxy.md+++ b/wiki/proxy.md@@ -305,7 +305,7 @@ Compression-only endpoint. Compresses messages without ever making a **completio"transforms_applied": ["router:smart_crusher:0.35"],"transforms_summary": {"router:smart_crusher:0.35": 1},"ccr_hashes": [], // non-empty only with mode="ccr"- "session": {"id": "conv-8f1c", "frozen_message_count": 12, "cached_prefix_replayed": true} // session mode only+ "session": {"id": "conv-8f1c", "frozen_message_count": 12, "cached_prefix_replayed": false} // session mode only}```@@ -342,11 +342,13 @@ def next_turn(new_messages):Note `protect_recent` is not a substitute — it guards the newest messages, while `frozen_message_count` guards the oldest, which is the cached end.-**Session mode.** Pass `config.session_id` (non-empty, at most 256 chars) and Headroom keeps the conversation's replay state itself — the same per-session compression cache and prefix tracker the proxy uses — so a gateway that owns routing can resend the raw conversation every turn and get a byte-identical prefix back. Everything previously returned for the session comes back unchanged; only the new tail is compressed; an explicit `frozen_message_count` still wins when larger. Forward the returned messages verbatim. `compress_user_messages` is refused (400). State is in-process (replay cache: `HEADROOM_COMPRESSION_CACHE_TTL_SECONDS`, default 3900; tracker state: 10 idle minutes), so multi-process deployments must pin a session to one process. `HEADROOM_COMPRESS_SESSION_FROM_HEADER=1` lets the `x-headroom-session-id` header stand in for `config.session_id` (off by default).+**Session mode.** Pass `config.session_id` (non-empty, at most 256 chars) and Headroom keeps the conversation's replay state itself — the same per-session compression cache and prefix tracker the proxy uses — so a gateway that owns routing can resend the raw conversation every turn and get a byte-identical prefix back. Everything previously returned for the session comes back unchanged; only the new tail is compressed; an explicit `frozen_message_count` still wins when larger. Forward the returned messages verbatim. `compress_user_messages` is refused (400). State is in-process by default (replay cache: `HEADROOM_COMPRESSION_CACHE_TTL_SECONDS`, default 3900; tracker state: 10 idle minutes), so multi-process deployments must pin a session to one process. With `HEADROOM_COMPRESS_SESSION_STORE=redis://...` (needs the `redis` extra, included in every Docker image) each session's tracker is also kept in Redis and any replica can serve its next turn and its `/v1/usage`; the CCR store follows to Redis unless `HEADROOM_CCR_BACKEND` names another. The per-session lock stays per process: two concurrent turns of one session on two replicas both run and the first write wins (compare-and-set). Gateway-mode pending turns stay in-process, so re-drive still needs real affinity. An unreachable Redis never fails a turn: the replica serves from its own memory (one `WARNING` when calls start failing, `INFO` when they recover, Redis skipped 5 s after a connection error). A replica with no local state then recompresses the history, slower, and can return a different prefix (a provider prompt-cache miss) with `cached_prefix_replayed: false`. Run Redis with high availability. `HEADROOM_COMPRESS_SESSION_FROM_HEADER=1` lets the `x-headroom-session-id` header stand in for `config.session_id` (off by default).++The response's `session` object: `id` is the session id the turn ran under (`config.session_id`, or the header above). `frozen_message_count` is how many leading messages the pipeline was told not to recompress: the leading run Headroom can replay from the session's compression cache (plain messages always count, a tool result only once its content is cached, the last message never), or `config.frozen_message_count` when larger; it comes from Headroom's state, not the provider, and can be non-zero on a first turn. `cached_prefix_replayed` is `true` when the pipeline's output for some leading messages differed from what was returned last turn and Headroom overwrote them with last turn's bytes; `false` when the serving process holds no previous turn for the session (first turn, expired state, a replica that never served or loaded it), when the pipeline already matched (the usual case), or when the replay was skipped as unsafe (messages do not line up with last turn's, or the replay would be larger), so `false` does not mean the prefix matches last turn's. It is **not** a provider prompt-cache hit/miss signal; read that from the provider's usage (`cache_read_input_tokens`, `cached_tokens`).Optionally relay the provider's usage for attribution with `POST /v1/usage` `{"session_id": "...", "usage": {...}}`. Anthropic `cache_read_input_tokens` / `cache_creation_input_tokens` and OpenAI `prompt_tokens_details.cached_tokens` / flat `cached_tokens` are accepted; a block with none of them is a 400. Replies `{"session_id", "frozen_message_count", "applied"}` (`applied: false, reason: "no_cache_signal"` when the only present field is 0), 404 `unknown_session`, or 503 `session_busy` (retry). Telemetry only — it never raises the frozen count.-**Gateway mode (two-half turn contract).** Add a top-level `gateway` object (`{}` is enough) and one model turn becomes two calls, so a gateway that never lets Headroom see the provider response can still run transforms whose reload step needs it — the proxy's "no shrink without reload" rule at the API boundary. `gateway` fields: `can_redrive` (default `false`: the gateway can call the provider again with a request Headroom hands it; send `false` when streaming), `can_relay_response` (default `false`: the gateway will post status/usage after each turn), `session_affinity` (default `true`; `false` disables re-driving because pending turns are in-process), `plugin_version` (diagnostics). Every other top-level field (`system`, `tools`, `temperature`, …) passes through; `tools` is compacted deterministically (`tool_schema_compaction`; `tool_desc_compaction` with `HEADROOM_TOOL_DESC_MAX_CHARS`); extension turn hooks run, stream-safe-only unless `can_redrive` and `session_affinity` both hold. The response adds `body` (the complete provider request — forward it as-is; never contains `config`, `gateway`, `token_budget`), `turn_id`, `route` (`{model, provider, service_tier, reason}`, advisory; a routing extension's model is also written into `body.model`), `obligations` (`redrive` and/or `relay_usage`) and a `gateway` echo. Fail-open answers carry the same keys with originals and `obligations: []`. Savings follow the proxy path: when compaction shortened `tools`, `tokens_before`/`tokens_after` also count the tool definitions, and the answer adds `tool_tokens_saved` (tool-search deferral plus tools a turn hook removed, both net; `tokens_saved + tool_tokens_saved` is the `/stats` headline) and `tool_tokens_deferred` (its deferral share, booked `estimated`); both are absent on fail-open answers. A turn is registered only when `obligations` is non-empty; with `relay_usage` the `/stats` record waits for the response half. Knobs: `HEADROOM_GATEWAY_TURN_TTL_SECONDS` (120), `HEADROOM_GATEWAY_MAX_PENDING_TURNS` (10000), `HEADROOM_GATEWAY_MAX_REDRIVES` (8). With `config.mode: "ccr"` and re-drive allowed, `headroom_retrieve` is injected into `body.tools` (`ccr_tool_injected`) and the response half answers the model's retrieval calls itself.+**Gateway mode (two-half turn contract).** Add a top-level `gateway` object (`{}` is enough) and one model turn becomes two calls, so a gateway that never lets Headroom see the provider response can still run transforms whose reload step needs it — the proxy's "no shrink without reload" rule at the API boundary. `gateway` fields: `can_redrive` (default `false`: the gateway can call the provider again with a request Headroom hands it; send `false` when streaming), `can_relay_response` (default `false`: the gateway will post status/usage after each turn), `session_affinity` (default `true`; `false` disables re-driving because pending turns are in-process, with or without `HEADROOM_COMPRESS_SESSION_STORE`), `plugin_version` (diagnostics). Every other top-level field (`system`, `tools`, `temperature`, …) passes through; `tools` is compacted deterministically (`tool_schema_compaction`; `tool_desc_compaction` with `HEADROOM_TOOL_DESC_MAX_CHARS`); extension turn hooks run, stream-safe-only unless `can_redrive` and `session_affinity` both hold. The response adds `body` (the complete provider request — forward it as-is; never contains `config`, `gateway`, `token_budget`), `turn_id`, `route` (`{model, provider, service_tier, reason}`, advisory; a routing extension's model is also written into `body.model`), `obligations` (`redrive` and/or `relay_usage`) and a `gateway` echo. Fail-open answers carry the same keys with originals and `obligations: []`. Savings follow the proxy path: when compaction shortened `tools`, `tokens_before`/`tokens_after` also count the tool definitions, and the answer adds `tool_tokens_saved` (tool-search deferral plus tools a turn hook removed, both net; `tokens_saved + tool_tokens_saved` is the `/stats` headline) and `tool_tokens_deferred` (its deferral share, booked `estimated`); both are absent on fail-open answers. A turn is registered only when `obligations` is non-empty; with `relay_usage` the `/stats` record waits for the response half. Knobs: `HEADROOM_GATEWAY_TURN_TTL_SECONDS` (120), `HEADROOM_GATEWAY_MAX_PENDING_TURNS` (10000), `HEADROOM_GATEWAY_MAX_REDRIVES` (8). With `config.mode: "ccr"` and re-drive allowed, `headroom_retrieve` is injected into `body.tools` (`ccr_tool_injected`) and the response half answers the model's retrieval calls itself.`POST /v1/compress/response` (same exposure rules as `/v1/compress`) is the response half: `{"turn_id", "status": 200, "latency_ms", "usage": {...}, "response": {...}}`. `usage` accepts Anthropic, OpenAI chat (`prompt_tokens_details.cached_tokens`), OpenAI Responses (`input_tokens_details.cached_tokens`) and Kong's flat `cached_tokens` shapes, or the whole provider body (a nested `usage` key is descended into once); billed counters are summed across re-drive rounds. `response` is required when the turn carries `redrive` and the provider call succeeded; a failed call closes the turn with its `status` alone. Answers: `{"action": "done", "turn_id", "response": <replacement, the latest provider response after a re-drive, or null — forward what you hold>, "frozen_message_count", "usage_applied", "rounds", "billed_usage"}` or `{"action": "redrive", "turn_id", "request": <full provider body to send>, "round"}` — post the provider's JSON back under the same `turn_id`; `billed_usage` sums every counter (cache reads and writes included) across rounds in Anthropic keys, and a re-driven turn's `response` is never null and reports that total as its `usage`; past `HEADROOM_GATEWAY_MAX_REDRIVES` the turn ends with `done` and the latest provider response. Errors: 400 `invalid_request` / `missing_response`, 404 `unknown_turn` (unregistered, finished, or expired), 409 `turn_busy`.