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(router): fall back to built-ins when an external compressor passes through (#3893)
Recep Kurtulus2c4b20fcba6d
diff --git a/headroom/transforms/content_router.py b/headroom/transforms/content_router.pyindex 6fe26eec6..667dfc54c 100644--- a/headroom/transforms/content_router.py+++ b/headroom/transforms/content_router.py@@ -3494,6 +3494,12 @@ class ContentRouter(Transform):type(out).__name__,)return None+ # A passthrough (``compressed=False``) is the compressor declining this+ # block, not a result; fall back so the built-in path still gets its+ # turn instead of the block going out uncompressed.+ if not out.compressed:+ logger.debug("external compressor %r passed through; falling back to built-in", name)+ return Nonecompressed = out.content# Never blank out a non-empty block (an empty user/tool block makes# providers reject the request); fall back so the built-in path runs.diff --git a/tests/test_router_external_passthrough.py b/tests/test_router_external_passthrough.pynew file mode 100644index 000000000..975190cff--- /dev/null+++ b/tests/test_router_external_passthrough.py@@ -0,0 +1,111 @@+"""A selected external compressor that passes a block through must not swallow it.++``CompressOutput.compressed=False`` is the contract's passthrough signal: the+compressor declined this block and returned it unchanged. The router has to+treat that like any other fail-open case and run its built-in dispatch, exactly+as if no external compressor were selected. Before the fix the router adopted+the unchanged block as the external result (chain ``["external:<name>"]``), so+every declined block skipped Headroom's own compressors.+"""++from __future__ import annotations++import pytest++from headroom.cache.compression_store import reset_compression_store+from headroom.transforms.compressor_registry import (+ CompressInput,+ CompressorDescriptor,+ CompressOutput,+)+from headroom.transforms.content_router import (+ CompressionStrategy,+ ContentRouter,+ ContentRouterConfig,+)++# Routes to SMART_CRUSHER (application/json) and is not touched by the STAGE-0+# lossless fold, so it reaches the external dispatch branch.+_JSON_ARRAY = (+ "["+ + ",".join(+ f'{{"id":{i},"name":"item-{i}","status":"active","value":{i * 7},'+ f'"note":"a fairly long descriptive field number {i} to add bulk"}}'+ for i in range(40)+ )+ + "]"+)+++def _memory_ccr(monkeypatch):+ monkeypatch.setenv("HEADROOM_CCR_BACKEND", "memory")+ monkeypatch.setenv("HEADROOM_DETECT_BACKEND", "python")+ reset_compression_store()+ yield+ reset_compression_store()+++class _DecliningExternal:+ """External compressor that always declines with ``compressed=False``."""++ def __init__(self) -> None:+ self.calls: list[CompressInput] = []++ @property+ def descriptor(self) -> CompressorDescriptor:+ return CompressorDescriptor(+ name="ext_decline",+ content_types=["application/json"],+ lossless=False,+ cost_tier="ml",+ recoverable=True,+ )++ def compress(self, inp: CompressInput) -> CompressOutput:+ self.calls.append(inp)+ return CompressOutput(+ content=inp.content,+ tokens_before=len(inp.content.split()),+ tokens_after=len(inp.content.split()),+ lossless=True,+ compressed=False,+ )+++def _router(selection: list[str] | None, comp: _DecliningExternal | None = None) -> ContentRouter:+ router = ContentRouter(+ ContentRouterConfig(enable_kompress=False, active_external_compressors=selection)+ )+ if comp is not None:+ router.compressor_registry.register(comp, replace=True)+ router._active_external_compressors = router._resolve_active_external_compressors()+ return router+++def test_passthrough_falls_back_to_builtin_dispatch(_memory_ccr):+ comp = _DecliningExternal()+ with_external = _router(["ext_decline"], comp)+ without_external = _router(None)++ got = with_external._apply_strategy_to_content(+ _JSON_ARRAY, CompressionStrategy.SMART_CRUSHER, ""+ )+ expected = without_external._apply_strategy_to_content(+ _JSON_ARRAY, CompressionStrategy.SMART_CRUSHER, ""+ )++ assert comp.calls, "the external compressor should have been consulted"+ assert "external:ext_decline" not in got[2]+ # Byte-identical to the path with no external compressor selected.+ assert got == expected+++def test_passthrough_does_not_short_circuit_compress(_memory_ccr):+ comp = _DecliningExternal()+ router = _router(["ext_decline"], comp)++ result = router.compress(_JSON_ARRAY)++ assert comp.calls+ assert "external:ext_decline" not in result.strategy_chain