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(transforms/content-router): detect on inner tool-output payload (#1717)

Tejas Chopraa85a04be8754
diff --git a/headroom/transforms/content_router.py b/headroom/transforms/content_router.py
index 163881895..aa6c61a6a 100644
--- a/headroom/transforms/content_router.py
+++ b/headroom/transforms/content_router.py
@@ -45,7 +45,7 @@ import sys
import threading
import time
from concurrent.futures import ThreadPoolExecutor
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, replace
from enum import Enum
from typing import Any
@@ -185,6 +185,40 @@ def _rust_detect_watchdogged(rust_detect: Any, content: str, timeout: float) ->
return box["result"]
+# Coding agents commonly wrap each tool result in an envelope such as
+# ``<returncode>0</returncode>\n<output>...</output>`` (or <stdout>/<stderr>/
+# <tool_result>). Those wrapper tags make the native detector read the whole
+# payload as markup (HTML/XML) even though the inner content is source code, a
+# grep result, or a log. That misroutes to the HTML article-extractor, which
+# blanks or corrupts code (dropping identifiers and route converters). Detect on
+# the inner payload so the real content type wins; compression still runs on the
+# original content.
+_DETECTION_ENVELOPE_RE = re.compile(
+ r"\A\s*(?:<returncode>\s*-?\d+\s*</returncode>\s*)?"
+ r"<(?P<tag>output|stdout|stderr|tool_result|result)>\n?"
+ r"(?P<body>.*?)"
+ r"\n?</(?P=tag)>\s*\Z",
+ re.DOTALL,
+)
+
+
+def _strip_detection_envelope(content: str) -> str:
+ """Return the inner payload of a tool-output envelope, for detection only.
+
+ Only strips when the ENTIRE string is a single wrapper envelope, so content
+ that merely mentions these tags is left untouched. Never returns an empty
+ probe (falls back to the original when the body is blank).
+ """
+ if "<" not in content:
+ return content
+ match = _DETECTION_ENVELOPE_RE.match(content)
+ if match:
+ body = match.group("body")
+ if body.strip():
+ return body
+ return content
+
+
def _detect_content(content: str) -> DetectionResult:
"""Detect content type via the native chain, with a safe Windows default.
@@ -202,6 +236,10 @@ def _detect_content(content: str) -> DetectionResult:
"""
global _detect_backend_warned, _detect_panic_warned, _detect_native_unhealthy
+ # Detect on the unwrapped payload so a tool-output envelope's tags don't get
+ # the whole result misclassified as HTML/XML (#route-converter corruption).
+ content = _strip_detection_envelope(content)
+
backend = _resolve_detect_backend()
if backend == "python":
if not _detect_backend_warned:
@@ -800,6 +838,15 @@ class ContentRouterConfig:
# the crusher themselves.
smart_crusher: Any | None = None
+ # Structural compressor configuration overrides. None preserves each
+ # compressor's dataclass defaults. The proxy wires environment-backed
+ # overrides into these objects, while ccr_inject_marker/search grouping are
+ # still enforced by ContentRouter so global safety flags win consistently.
+ search_compressor: Any | None = None
+ log_compressor: Any | None = None
+ diff_compressor: Any | None = None
+ text_crusher: Any | None = None
+
# Group search-compressor output by file (`rg --heading` style).
# Default False; the proxy enables it in token mode.
search_group_by_file: bool = False
@@ -1995,12 +2042,13 @@ class ContentRouter(Transform):
try:
from .search_compressor import SearchCompressor, SearchCompressorConfig
- self._search_compressor = SearchCompressor(
- SearchCompressorConfig(
- group_by_file=self.config.search_group_by_file,
- enable_ccr=self.config.ccr_inject_marker,
- )
+ cfg = self.config.search_compressor or SearchCompressorConfig()
+ cfg = replace(
+ cfg,
+ group_by_file=self.config.search_group_by_file,
+ enable_ccr=self.config.ccr_inject_marker,
)
+ self._search_compressor = SearchCompressor(cfg)
except ImportError:
logger.debug("SearchCompressor not available")
return self._search_compressor
@@ -2011,9 +2059,9 @@ class ContentRouter(Transform):
try:
from .log_compressor import LogCompressor, LogCompressorConfig
- self._log_compressor = LogCompressor(
- LogCompressorConfig(enable_ccr=self.config.ccr_inject_marker)
- )
+ cfg = self.config.log_compressor or LogCompressorConfig()
+ cfg = replace(cfg, enable_ccr=self.config.ccr_inject_marker)
+ self._log_compressor = LogCompressor(cfg)
except ImportError:
logger.debug("LogCompressor not available")
return self._log_compressor
@@ -2026,9 +2074,10 @@ class ContentRouter(Transform):
return None
if self._text_crusher is None:
try:
- from .text_crusher import TextCrusher
+ from .text_crusher import TextCrusher, TextCrusherConfig
- self._text_crusher = TextCrusher()
+ cfg = self.config.text_crusher or TextCrusherConfig()
+ self._text_crusher = TextCrusher(cfg)
except ImportError:
logger.debug("TextCrusher (headroom._core) unavailable; disabling gate route")
self._text_crusher_enabled = False
@@ -2052,9 +2101,9 @@ class ContentRouter(Transform):
if self._diff_compressor is None:
from .diff_compressor import DiffCompressor, DiffCompressorConfig
- self._diff_compressor = DiffCompressor(
- DiffCompressorConfig(enable_ccr=self.config.ccr_inject_marker)
- )
+ cfg = self.config.diff_compressor or DiffCompressorConfig()
+ cfg = replace(cfg, enable_ccr=self.config.ccr_inject_marker)
+ self._diff_compressor = DiffCompressor(cfg)
return self._diff_compressor
def _get_html_extractor(self) -> Any:
diff --git a/tests/test_transforms_content_router.py b/tests/test_transforms_content_router.py
index d98701616..7a62873d8 100644
--- a/tests/test_transforms_content_router.py
+++ b/tests/test_transforms_content_router.py
@@ -16,6 +16,7 @@ from headroom.transforms.content_router import (
_create_content_signature,
_detect_content,
_extract_json_block,
+ _strip_detection_envelope,
is_mixed_content,
split_into_sections,
)
@@ -989,3 +990,37 @@ def test_detect_content_circuit_breaker_skips_native_after_hang(
assert calls == 1 # breaker tripped: native entered once, 2nd call skipped it
finally:
release.set() # let the lone daemon worker finish
+
+
+def test_strip_detection_envelope_isolates_tool_output_payload() -> None:
+ """Only a whole-string tool-output envelope is unwrapped; content that
+ merely mentions the tags, or has an empty body, is left untouched."""
+ body = "def main():\n return 1"
+ wrapped = f"<returncode>0</returncode>\n<output>\n{body}\n</output>"
+ assert _strip_detection_envelope(wrapped) == body
+ # <output> alias tags and a bare envelope (no returncode) also unwrap.
+ assert _strip_detection_envelope(f"<stdout>\n{body}\n</stdout>") == body
+ # Non-envelope content is returned verbatim (no "<" fast-path + no match).
+ prose = "see the <output> tag docs for details"
+ assert _strip_detection_envelope(prose) == prose
+ # Empty body never yields an empty probe — falls back to the original.
+ empty = "<output>\n\n</output>"
+ assert _strip_detection_envelope(empty) == empty
+
+
+def test_detect_content_sees_through_tool_output_envelope() -> None:
+ """Regression: a tool-result envelope's tags used to make the detector
+ read the whole payload as markup and misroute code to the HTML extractor.
+ Detection now runs on the inner payload, so the real type wins."""
+ code = "\n".join(
+ [
+ "import os",
+ "from pathlib import Path",
+ "",
+ "def main() -> int:",
+ " return len(os.listdir(Path.cwd()))",
+ ]
+ )
+ wrapped = f"<returncode>0</returncode>\n<output>\n{code}\n</output>"
+ assert _detect_content(wrapped).content_type is ContentType.SOURCE_CODE
+ assert _detect_content(wrapped).content_type is _detect_content(code).content_type