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(kompress): fail-open wall-clock guard on single-cache-miss compression (#2114)
Rod Boeve9000863fc5e
diff --git a/headroom/transforms/content_router.py b/headroom/transforms/content_router.pyindex 5e7f26b3e..e9e07912c 100644--- a/headroom/transforms/content_router.py+++ b/headroom/transforms/content_router.py@@ -78,6 +78,16 @@ _detect_panic_warned = False_detect_native_unhealthy = False # circuit breaker: native detect hung once (#575)+def _compression_deadline_seconds() -> float:+ try:+ return max(+ 0.0,+ float(os.environ.get("HEADROOM_COMPRESSION_DEADLINE_MS", "20000")) / 1000.0,+ )+ except ValueError:+ return 20.0++def _router_debug_dumps(value: Any) -> str:return json.dumps(value, ensure_ascii=False, default=str, separators=(",", ":"))@@ -3723,8 +3733,48 @@ class ContentRouter(Transform):task_results = []for _, task_content, task_ctx, task_bias, _, _ in pending_tasks:t0 = time.perf_counter()- r = self.compress(task_content, context=task_ctx, bias=task_bias)- task_results.append((r, (time.perf_counter() - t0) * 1000))+ deadline_s = _compression_deadline_seconds() if len(pending_tasks) == 1 else 0.0+ if deadline_s:+ box: dict[str, Any] = {}++ def _run(+ _box: dict[str, Any] = box,+ _content: str = task_content,+ _context: str = task_ctx,+ _bias: float = task_bias,+ ) -> None:+ try:+ _box["result"] = self.compress(+ _content, context=_context, bias=_bias+ )+ except BaseException as exc: # noqa: BLE001+ _box["error"] = exc++ # ponytail: daemon watchdog cannot stop native GIL holds; native layer owns that fix.+ worker = threading.Thread(+ target=_run, name="headroom-single-compress-watchdog", daemon=True+ )+ worker.start()+ worker.join(deadline_s)+ if worker.is_alive():+ logger.warning(+ "ContentRouter single-cache-miss compression exceeded %.1fs; "+ "failing open via PASSTHROUGH",+ deadline_s,+ )+ r = RouterCompressionResult(+ compressed=task_content,+ original=task_content,+ strategy_used=CompressionStrategy.PASSTHROUGH,+ )+ elif "error" in box:+ raise box["error"]+ else:+ r = box["result"]+ else:+ r = self.compress(task_content, context=task_ctx, bias=task_bias)+ compress_ms = (time.perf_counter() - t0) * 1000+ task_results.append((r, compress_ms))else:# Parallel compression via thread poolwith ThreadPoolExecutor(max_workers=max_workers) as executor:diff --git a/pyproject.toml b/pyproject.tomlindex b48a5cdb8..86ef1a514 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -54,7 +54,7 @@ dependencies = [# ImportError-guarded. Marking it 3.14-optional lets headroom install on Python 3.14# (core compression + the Anthropic proxy path never import litellm). See GH #956."litellm>=1.86.2,<2.0; python_version < '3.14'", # model registry, pricing, providers (lazy)- "click>=8.1.0", # CLI framework+ "click>=8.3.3", # CLI framework"rich>=13.0.0", # Rich terminal output"opentelemetry-api>=1.24.0", # Safe no-op OTEL API for instrumentation"ast-grep-cli>=0.30.0", # AST-aware code slicing (CodeCompressor); binary wheel@@ -165,7 +165,7 @@ relevance = [# `headroom/image/compressor.py` adapts both API shapes at runtime via# a try/except cascade. See issue #372 for context.image = [- "pillow>=10.0.0",+ "pillow>=12.3.0","sentencepiece>=0.1.99", # Required by SigLIP tokenizer (SiglipTokenizer)# Python 3.6–3.12: keep the proven ORT-bundled package directly.# ~15 MB ONNX models auto-downloaded on first use.diff --git a/tests/test_content_router_single_item_deadline.py b/tests/test_content_router_single_item_deadline.pynew file mode 100644index 000000000..258468f83--- /dev/null+++ b/tests/test_content_router_single_item_deadline.py@@ -0,0 +1,114 @@+from __future__ import annotations++import time++from headroom.transforms.content_detector import ContentType+from headroom.transforms.content_router import (+ CompressionStrategy,+ ContentRouter,+ ContentRouterConfig,+ RouterCompressionResult,+ RoutingDecision,+)+++class _Tokenizer:+ def count_text(self, content: str) -> int:+ return len(content.split())+++def _compression_result(content: str, compressed: str) -> RouterCompressionResult:+ return RouterCompressionResult(+ compressed=compressed,+ original=content,+ strategy_used=CompressionStrategy.TEXT,+ routing_log=[+ RoutingDecision(+ content_type=ContentType.PLAIN_TEXT,+ strategy=CompressionStrategy.TEXT,+ original_tokens=len(content.split()),+ compressed_tokens=len(compressed.split()),+ )+ ],+ )+++def _router() -> ContentRouter:+ return ContentRouter(+ ContentRouterConfig(+ protect_recent_code=0,+ protect_analysis_context=False,+ skip_user_messages=False,+ )+ )+++def _messages() -> list[dict[str, str]]:+ return [+ {"role": "assistant", "content": "frozen prefix content remains unchanged"},+ {+ "role": "assistant",+ "content": "pending cache miss content takes the inline compression branch",+ },+ ]+++def test_single_cache_miss_fails_open_at_deadline(monkeypatch, caplog):+ router = _router()++ def slow_compress(content, *, context="", bias=1.0):+ time.sleep(0.2)+ return _compression_result(content, "compressed output")++ monkeypatch.setattr(router, "compress", slow_compress)+ monkeypatch.setenv("HEADROOM_COMPRESSION_DEADLINE_MS", "10")++ started = time.perf_counter()+ result = router.apply(+ _messages(),+ _Tokenizer(),+ frozen_message_count=1,+ min_tokens_to_compress=1,+ )++ assert time.perf_counter() - started < 0.12+ assert result.messages[1]["content"] == _messages()[1]["content"]+ assert "failing open via PASSTHROUGH" in caplog.text+++def test_single_cache_miss_preserves_under_deadline_output(monkeypatch):+ router = _router()+ monkeypatch.setattr(+ router,+ "compress",+ lambda content, *, context="", bias=1.0: _compression_result(content, "compressed output"),+ )+ monkeypatch.setenv("HEADROOM_COMPRESSION_DEADLINE_MS", "1000")++ result = router.apply(+ _messages(),+ _Tokenizer(),+ frozen_message_count=1,+ min_tokens_to_compress=1,+ )++ assert result.messages[1]["content"] == "compressed output"+++def test_single_cache_miss_preserves_disabled_deadline(monkeypatch):+ router = _router()+ monkeypatch.setattr(+ router,+ "compress",+ lambda content, *, context="", bias=1.0: _compression_result(content, "compressed output"),+ )+ monkeypatch.setenv("HEADROOM_COMPRESSION_DEADLINE_MS", "0")++ result = router.apply(+ _messages(),+ _Tokenizer(),+ frozen_message_count=1,+ min_tokens_to_compress=1,+ )++ assert result.messages[1]["content"] == "compressed output"diff --git a/uv.lock b/uv.lockindex 6a72283ed..c5fa3fbd3 100644--- a/uv.lock+++ b/uv.lock@@ -1737,7 +1737,7 @@ requires-dist = [{ name = "ast-grep-cli", specifier = ">=0.30.0" },{ name = "boto3", marker = "extra == 'bedrock'", specifier = ">=1.41.0" },{ name = "botocore", extras = ["crt"], marker = "extra == 'bedrock'", specifier = ">=1.41.0" },- { name = "click", specifier = ">=8.1.0" },+ { name = "click", specifier = ">=8.3.3" },{ name = "datasets", marker = "extra == 'evals'", specifier = ">=2.14.0" },{ name = "datasets", marker = "extra == 'voice-train'", specifier = ">=2.14.0" },{ name = "fastapi", marker = "extra == 'dev'", specifier = ">=0.100.0" },@@ -1785,7 +1785,7 @@ requires-dist = [{ name = "opentelemetry-sdk", marker = "extra == 'dev'", specifier = ">=1.24.0" },{ name = "opentelemetry-sdk", marker = "extra == 'otel'", specifier = ">=1.24.0" },{ name = "orjson", marker = "platform_python_implementation != 'PyPy' and extra == 'proxy'", specifier = ">=3.9.14" },- { name = "pillow", marker = "extra == 'image'", specifier = ">=10.0.0" },+ { name = "pillow", marker = "extra == 'image'", specifier = ">=12.3.0" },{ name = "pre-commit", marker = "extra == 'dev'", specifier = ">=3.0.0" },{ name = "pydantic", specifier = ">=2.0.0" },{ name = "pytest", marker = "extra == 'dev'", specifier = ">=7.0.0" },