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(compression): honor qualified CCR names across integrations (#2698)
Rod Boevdcb674b5e4e0
diff --git a/headroom/integrations/langchain/langgraph.py b/headroom/integrations/langchain/langgraph.pyindex 6fcdeff62..2e6734795 100644--- a/headroom/integrations/langchain/langgraph.py+++ b/headroom/integrations/langchain/langgraph.py@@ -47,6 +47,8 @@ except ImportError:BaseMessage = object # type: ignore[misc,assignment]ToolMessage = object # type: ignore[misc,assignment]+from headroom.ccr.tool_injection import CCR_TOOL_NAME+from headroom.config import is_tool_excludedfrom headroom.transforms.smart_crusher import SmartCrusher, SmartCrusherConfiglogger = logging.getLogger(__name__)@@ -156,6 +158,7 @@ def _get_crusher(min_tokens: int) -> SmartCrusher:def _should_skip(content: str,config: CompressToolMessagesConfig,+ tool_name: str | None = None,) -> str | None:"""Check if a ToolMessage should skip compression.@@ -164,6 +167,9 @@ def _should_skip(if not content:return "empty_content"+ if tool_name and is_tool_excluded(tool_name, (CCR_TOOL_NAME,)):+ return "tool_excluded"+tokens = _estimate_tokens(content)if tokens < config.min_tokens_to_compress:return f"below_threshold:{tokens}<{config.min_tokens_to_compress}"@@ -176,6 +182,18 @@ def _should_skip(return None+def _tool_names_by_id(messages: list[BaseMessage]) -> dict[str, str]: # type: ignore[type-arg]+ """Index tool-call names so results without a copied name remain classifiable."""+ names: dict[str, str] = {}+ for message in messages:+ for tool_call in getattr(message, "tool_calls", ()) or ():+ tool_call_id = tool_call.get("id")+ tool_name = tool_call.get("name")+ if tool_call_id and tool_name:+ names[tool_call_id] = tool_name+ return names++def compress_tool_messages(messages: list[BaseMessage], # type: ignore[type-arg]*,@@ -223,6 +241,7 @@ def compress_tool_messages(crusher = _get_crusher(config.min_tokens_to_compress)result_messages: list[BaseMessage] = []metrics: list[ToolMessageCompressionMetrics] = []+ tool_names = _tool_names_by_id(messages)for msg in messages:if not isinstance(msg, ToolMessage):@@ -233,7 +252,8 @@ def compress_tool_messages(request_id = str(uuid4())# Check if we should skip- skip_reason = _should_skip(content, config)+ tool_name = getattr(msg, "name", None) or tool_names.get(getattr(msg, "tool_call_id", ""))+ skip_reason = _should_skip(content, config, tool_name)if skip_reason:result_messages.append(msg)tokens = _estimate_tokens(content)diff --git a/headroom/integrations/strands/hooks.py b/headroom/integrations/strands/hooks.pyindex 29dc32a03..275b6f64d 100644--- a/headroom/integrations/strands/hooks.py+++ b/headroom/integrations/strands/hooks.py@@ -48,6 +48,8 @@ except ImportError:ToolResult = dict # type: ignore[misc,assignment]from headroom import HeadroomConfig+from headroom.ccr.tool_injection import CCR_TOOL_NAME+from headroom.config import is_tool_excludedfrom headroom.transforms.smart_crusher import SmartCrusher, SmartCrusherConfiglogger = logging.getLogger(__name__)@@ -314,7 +316,7 @@ class HeadroomHookProvider(HookProvider): # type: ignore[misc]tool_use_id = event.tool_use.get("toolUseId", "unknown")# Check if compression should be skipped- skip_reason = self._should_skip_compression(result)+ skip_reason = self._should_skip_compression(result, tool_name)if skip_reason:self._record_metrics(request_id=request_id,@@ -421,11 +423,15 @@ class HeadroomHookProvider(HookProvider): # type: ignore[misc]tokens_before,)- def _should_skip_compression(self, result: ToolResult) -> str | None:+ def _should_skip_compression(+ self, result: ToolResult, tool_name: str | None = None+ ) -> str | None:"""Check if compression should be skipped for this result.Args:result: The tool result to check.+ tool_name: The name of the tool that produced the result, used to+ honor the shared tool-exclusion set.Returns:Skip reason string if should skip, None if should compress.@@ -434,6 +440,9 @@ class HeadroomHookProvider(HookProvider): # type: ignore[misc]if not self.compress_tool_outputs:return "compression_disabled"+ if tool_name and is_tool_excluded(tool_name, (CCR_TOOL_NAME,)):+ return "tool_excluded"+# Skip error results if preserve_errors is Trueif self.preserve_errors and result.get("status") == "error":return "error_result_preserved"diff --git a/headroom/transforms/smart_crusher.py b/headroom/transforms/smart_crusher.pyindex 6e4ae6d1c..4dde88736 100644--- a/headroom/transforms/smart_crusher.py+++ b/headroom/transforms/smart_crusher.py@@ -52,7 +52,7 @@ from dataclasses import dataclassfrom typing import Anyfrom ..ccr.tool_injection import CCR_TOOL_NAME-from ..config import CCRConfig, TransformResult+from ..config import CCRConfig, TransformResult, is_tool_excludedfrom ..tokenizer import Tokenizerfrom ..utils import compute_short_hash, create_tool_digest_marker, deep_copy_messagesfrom .base import Transform@@ -1280,7 +1280,10 @@ class SmartCrusher(Transform):# unresolvable retrieval loop.# ponytail: ceiling is tool_call_id lookup; if the id is missing we# compress (conservative: unknown tool names don't get a free pass).- if tool_names_by_id.get(msg.get("tool_call_id") or "") == CCR_TOOL_NAME:+ if is_tool_excluded(+ tool_names_by_id.get(msg.get("tool_call_id") or "") or "",+ (CCR_TOOL_NAME,),+ ):continuecontent = msg.get("content", "")if isinstance(content, str):@@ -1310,7 +1313,10 @@ class SmartCrusher(Transform):# would produce a new <<ccr:hash>> marker the agent cannot# redeem (infinite retrieval loop).# ponytail: ceiling is tool_use_id lookup; unknown ids pass through.- if tool_names_by_id.get(block.get("tool_use_id") or "") == CCR_TOOL_NAME:+ if is_tool_excluded(+ tool_names_by_id.get(block.get("tool_use_id") or "") or "",+ (CCR_TOOL_NAME,),+ ):continuetool_content = block.get("content", "")if not isinstance(tool_content, str):diff --git a/tests/integrations/test_langgraph.py b/tests/integrations/test_langgraph.pynew file mode 100644index 000000000..6f648a247--- /dev/null+++ b/tests/integrations/test_langgraph.py@@ -0,0 +1,90 @@+"""Regression tests for qualified CCR retrieval tool names in LangGraph."""++from __future__ import annotations++import json++import pytest++pytest.importorskip("headroom._core")++try:+ from langchain_core.messages import AIMessage, ToolMessage+except ImportError:+ pytest.skip("LangChain not installed", allow_module_level=True)++from headroom.integrations.langchain.langgraph import compress_tool_messages+++def _large_output() -> str:+ return json.dumps([{"id": i, "name": f"item_{i}", "value": "x" * 30} for i in range(200)])+++def _messages(tool_name: str) -> list:+ return [+ AIMessage(content="", tool_calls=[{"id": "call_1", "name": tool_name, "args": {}}]),+ ToolMessage(content=_large_output(), tool_call_id="call_1"),+ ]+++ "tool_name",+ ["mcp__Headroom__headroom_retrieve", "mcp_Headroom_headroom_retrieve"],+)+def test_qualified_ccr_retrieval_message_is_preserved(tool_name: str) -> None:+ messages = _messages(tool_name)+ original = messages[1].content++ result = compress_tool_messages(messages)++ assert result.messages[1].content == original+ assert result.metrics[0].skip_reason == "tool_excluded"+++def test_incomplete_tool_calls_do_not_hide_later_qualified_name() -> None:+ messages = [+ AIMessage(+ content="",+ tool_calls=[+ {"id": None, "name": "incomplete", "args": {}},+ {"id": "ignored", "name": "", "args": {}},+ {+ "id": "call_1",+ "name": "mcp__Headroom__headroom_retrieve",+ "args": {},+ },+ ],+ ),+ ToolMessage(content=_large_output(), tool_call_id="call_1"),+ ]+ original = messages[1].content++ result = compress_tool_messages(messages)++ assert result.messages[1].content == original+ assert result.metrics[0].skip_reason == "tool_excluded"+++def test_near_match_ccr_tool_name_is_not_excluded() -> None:+ messages = _messages("mcp__Headroom__headroom_retrieve_extra")+ original = messages[1].content++ result = compress_tool_messages(messages)++ assert result.metrics[0].skip_reason != "tool_excluded"+ assert result.messages[1].content != original+++ "tool_name",+ ["mcp__Headroom__headroom_retrieve", "mcp_Headroom_headroom_retrieve"],+)+def test_qualified_name_on_the_tool_message_is_enough(tool_name: str) -> None:+ """`ToolNode` populates `ToolMessage.name`, so the id index is only a fallback."""+ messages = [ToolMessage(content=_large_output(), tool_call_id="call_1", name=tool_name)]+ original = messages[0].content++ result = compress_tool_messages(messages)++ assert result.messages[0].content == original+ assert result.metrics[0].skip_reason == "tool_excluded"diff --git a/tests/integrations/test_strands/test_ccr_exclusion.py b/tests/integrations/test_strands/test_ccr_exclusion.pynew file mode 100644index 000000000..56c1d05d7--- /dev/null+++ b/tests/integrations/test_strands/test_ccr_exclusion.py@@ -0,0 +1,91 @@+"""Regression tests for qualified CCR names in Strands compression."""++from __future__ import annotations++from types import SimpleNamespace+from unittest.mock import Mock++import pytest++pytest.importorskip("headroom._core")++from headroom.integrations.strands import hooks+++def hook(monkeypatch: pytest.MonkeyPatch) -> hooks.HeadroomHookProvider:+ monkeypatch.setattr(hooks, "STRANDS_AVAILABLE", True)+ provider = hooks.HeadroomHookProvider(min_tokens_to_compress=0)+ provider._crusher = Mock()+ provider._crusher.crush.return_value = SimpleNamespace(+ compressed="compressed", was_modified=True+ )+ return provider+++class _Registry:+ """Stand-in for Strands' HookRegistry that dispatches like the real one."""++ def __init__(self) -> None:+ self._callbacks: dict[object, list] = {}++ def add_callback(self, event_type: object, callback) -> None: # noqa: ANN001+ self._callbacks.setdefault(event_type, []).append(callback)++ def dispatch(self, event_type: object, event: object) -> None:+ for callback in self._callbacks[event_type]:+ callback(event)+++def _event(tool_name: str, content: str) -> SimpleNamespace:+ return SimpleNamespace(+ tool_use={"name": tool_name, "toolUseId": "tool_1"},+ result={"content": [{"text": content}]},+ )+++def test_qualified_ccr_result_is_preserved_through_the_registered_hook(+ hook: hooks.HeadroomHookProvider,+) -> None:+ """Drive the seam Strands actually drives: register_hooks, then dispatch."""+ registry = _Registry()+ hook.register_hooks(registry)++ content = "x" * 400+ event = _event("mcp__headroom__headroom_retrieve", content)+ registry.dispatch(hooks.AfterToolCallEvent, event)++ assert event.result["content"][0]["text"] == content+ assert hook.metrics_history[0].skip_reason == "tool_excluded"+ hook._crusher.crush.assert_not_called()+++ "tool_name",+ [+ "mcp__headroom__headroom_retrieve",+ "mcp_headroom_headroom_retrieve",+ "headroom_retrieve",+ ],+)+def test_qualified_ccr_tool_result_is_preserved(+ hook: hooks.HeadroomHookProvider, tool_name: str+) -> None:+ content = "x" * 400+ event = _event(tool_name, content)++ hook._compress_tool_result(event)++ assert event.result["content"][0]["text"] == content+ assert hook.metrics_history[0].skip_reason == "tool_excluded"+ hook._crusher.crush.assert_not_called()+++def test_near_match_tool_name_still_compresses(hook: hooks.HeadroomHookProvider) -> None:+ event = _event("mcp__headroom__headroom_retrieve_extra", "x" * 400)++ hook._compress_tool_result(event)++ assert event.result["content"][0]["text"] == "compressed"+ assert hook.metrics_history[0].was_compressed is True+ hook._crusher.crush.assert_called_once()diff --git a/tests/integrations/test_strands/test_hooks_unit.py b/tests/integrations/test_strands/test_hooks_unit.pyindex b059b93c5..8a18a1c90 100644--- a/tests/integrations/test_strands/test_hooks_unit.py+++ b/tests/integrations/test_strands/test_hooks_unit.py@@ -254,6 +254,30 @@ class TestShouldSkipCompression:skip_reason = hook._should_skip_compression(result)assert skip_reason is None+ @pytest.mark.parametrize(+ "tool_name",+ ["mcp__Headroom__headroom_retrieve", "mcp_Headroom_headroom_retrieve"],+ )+ def test_skip_qualified_ccr_retrieval_results(self, tool_name):+ """Qualified CCR retrieval names use the shared exclusion authority."""+ from headroom.integrations.strands import HeadroomHookProvider++ hook = HeadroomHookProvider()+ result = {"content": [{"text": "retrieved content"}]}++ assert hook._should_skip_compression(result, tool_name) == "tool_excluded"++ def test_near_match_ccr_tool_name_is_not_excluded(self):+ """A similar qualified name remains eligible for compression."""+ from headroom.integrations.strands import HeadroomHookProvider++ hook = HeadroomHookProvider()+ result = {"content": [{"text": "retrieved content"}]}++ assert (+ hook._should_skip_compression(result, "mcp__Headroom__headroom_retrieve_extra") is None+ )+class TestCompressToolResult:"""Tests for _compress_tool_result hook handler."""@@ -323,6 +347,24 @@ class TestCompressToolResult:assert metrics.was_compressed is Falseassert metrics.skip_reason == "compression_disabled"+ def test_qualified_ccr_retrieval_result_is_preserved(self):+ """The production hook skips qualified CCR retrieval results."""+ from headroom.integrations.strands import HeadroomHookProvider++ hook = HeadroomHookProvider(min_tokens_to_compress=1)+ original = json.dumps([{"id": i, "data": "x" * 50} for i in range(50)])+ mock_event = MagicMock()+ mock_event.tool_use = {+ "name": "mcp__Headroom__headroom_retrieve",+ "toolUseId": "tool-ccr",+ }+ mock_event.result = {"content": [{"text": original}]}++ hook._compress_tool_result(mock_event)++ assert mock_event.result["content"][0]["text"] == original+ assert hook.metrics_history[-1].skip_reason == "tool_excluded"+class TestMetricsTracking:"""Tests for metrics tracking and aggregation."""diff --git a/tests/test_smart_crusher.py b/tests/test_smart_crusher.pynew file mode 100644index 000000000..0ba6d13cb--- /dev/null+++ b/tests/test_smart_crusher.py@@ -0,0 +1,141 @@+"""Regression tests for qualified CCR retrieval tool names."""++from __future__ import annotations++import json++import pytest++from headroom import OpenAIProvider, Tokenizer+from headroom.ccr.tool_injection import CCR_TOOL_NAME+from headroom.config import SmartCrusherConfig++try:+ from headroom._core import SmartCrusher as _RustSmartCrusher # noqa: F401+except ImportError:+ pytest.skip("headroom._core not built", allow_module_level=True)++from headroom.transforms.smart_crusher import SmartCrusher+++def _big_content() -> str:+ return json.dumps([{"id": i, "value": "x" * 20} for i in range(60)])+++def _apply_for_tool(tool_name: str):+ messages = [+ {+ "role": "assistant",+ "tool_calls": [+ {+ "id": "call_1",+ "function": {"name": tool_name, "arguments": "{}"},+ }+ ],+ },+ {"role": "tool", "tool_call_id": "call_1", "content": _big_content()},+ ]+ tokenizer = Tokenizer(OpenAIProvider().get_token_counter("gpt-4o"), "gpt-4o")+ result = SmartCrusher(config=SmartCrusherConfig(min_tokens_to_crush=0)).apply(+ messages, tokenizer+ )+ return messages[1]["content"], result+++ "tool_name",+ ["mcp__Headroom__headroom_retrieve", "mcp_Headroom_headroom_retrieve"],+)+def test_qualified_ccr_retrieval_result_is_preserved(tool_name: str) -> None:+ original, result = _apply_for_tool(tool_name)++ assert result.messages[1]["content"] == original+ assert not any("smart_crush" in transform for transform in result.transforms_applied)+++def test_near_match_ccr_tool_name_still_compresses() -> None:+ original, result = _apply_for_tool("mcp__Headroom__headroom_retrieve_extra")++ assert result.messages[1]["content"] != original or result.tokens_after < result.tokens_before+++def test_bare_ccr_tool_name_remains_preserved() -> None:+ original, result = _apply_for_tool(CCR_TOOL_NAME)++ assert result.messages[1]["content"] == original+++def _apply_anthropic_for_tool(tool_name: str):+ """Anthropic block shape: tool_use in the assistant turn, tool_result in the user turn."""+ messages = [+ {+ "role": "assistant",+ "content": [+ {"type": "tool_use", "id": "tu_1", "name": tool_name, "input": {}},+ ],+ },+ {+ "role": "user",+ "content": [+ {"type": "tool_result", "tool_use_id": "tu_1", "content": _big_content()},+ ],+ },+ ]+ tokenizer = Tokenizer(OpenAIProvider().get_token_counter("gpt-4o"), "gpt-4o")+ result = SmartCrusher(config=SmartCrusherConfig(min_tokens_to_crush=0)).apply(+ messages, tokenizer+ )+ return messages[1]["content"][0]["content"], result+++ "tool_name",+ [+ "mcp__Headroom__headroom_retrieve",+ "mcp_Headroom_headroom_retrieve",+ CCR_TOOL_NAME,+ ],+)+def test_qualified_ccr_tool_result_block_is_preserved(tool_name: str) -> None:+ original, result = _apply_anthropic_for_tool(tool_name)++ assert result.messages[1]["content"][0]["content"] == original+ assert not any("smart" in transform for transform in result.transforms_applied)+++ "tool_name",+ ["mcp__Headroom__headroom_retrieve", "mcp_Headroom_headroom_retrieve", CCR_TOOL_NAME],+)+def test_mcp_compressor_preserves_qualified_ccr_output(tool_name: str) -> None:+ """`HeadroomMCPCompressor.compress` is the production entry point issue #2656 names.++ It drives `SmartCrusher.apply` with a `role=tool` message, so the guard has to+ hold through that wrapper and not only on a directly built message list.+ """+ from headroom.integrations.mcp.server import HeadroomMCPCompressor++ content = json.dumps({"results": [{"id": i, "value": "x" * 40} for i in range(80)]})+ result = HeadroomMCPCompressor().compress(content, tool_name=tool_name)++ assert result.compressed_content == content+++def test_mcp_compressor_still_compresses_a_near_match_name() -> None:+ from headroom.integrations.mcp.server import HeadroomMCPCompressor++ content = json.dumps({"results": [{"id": i, "value": "x" * 40} for i in range(80)]})+ result = HeadroomMCPCompressor().compress(+ content, tool_name="mcp__Headroom__headroom_retrieve_extra"+ )++ assert result.compressed_content != content+++def test_near_match_ccr_tool_result_block_still_compresses() -> None:+ original, result = _apply_anthropic_for_tool("mcp__Headroom__headroom_retrieve_extra")++ assert (+ result.messages[1]["content"][0]["content"] != original+ or result.tokens_after < result.tokens_before+ )