Skip to content

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.

docs(transforms): correct stale unit-result-cache placeholder comments (#2506)

gglucassf326fe26c561
diff --git a/headroom/transforms/compression_units.py b/headroom/transforms/compression_units.py
index c499446c1..063b55b7f 100644
--- a/headroom/transforms/compression_units.py
+++ b/headroom/transforms/compression_units.py
@@ -52,8 +52,10 @@ class CompressionUnit:
# - compressor_noop: router returned identical bytes (no compression possible)
# - already_compressed: input already carried a CCR retrieval marker
# - rejected_not_smaller: compressor produced output >= input tokens
-# - cache_hit: result returned from result_cache (placeholder; not
-# currently wired into the unit path — see follow-up)
+# - cache_hit: reserved; cached unit reuse is caller-level (the OpenAI
+# Responses handler's unit-result cache) and is surfaced
+# via RouterCompressionResult.cache_hit, not as a reason
+# here — no code path produces this category today
UNIT_REASON_CATEGORIES = {
None: "applied",
"protected_user_message": "protected_role",
diff --git a/headroom/transforms/content_router.py b/headroom/transforms/content_router.py
index 4a862f7c1..a2a0f68ea 100644
--- a/headroom/transforms/content_router.py
+++ b/headroom/transforms/content_router.py
@@ -1394,11 +1394,12 @@ class RouterCompressionResult:
LOG fallback chain it's three. Lets log readers see *how*
we got to the final compressor without parsing the
decision_reason string.
- cache_hit: True when this result came from the router's
- result_cache (no fresh compression ran). Currently the
- single-content compress() path doesn't populate the cache,
- so this is False in practice — placeholder for the
- cache-wire-up follow-up.
+ cache_hit: True when this result was reused from a cache
+ instead of a fresh compression run. compress() itself
+ never sets this (only apply() has the router-internal
+ two-tier cache); it is set by callers that cache unit
+ results — e.g. the OpenAI Responses handler marks reused
+ units via ``replace(router_result, cache_hit=True)``.
"""
compressed: str