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.

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.py
index 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 None
compressed = 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.py
new file mode 100644
index 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