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(integrations): filter CCR-dropped sentinel in test iteration
chopratejasb8fc7eee197c
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.jsonindex 79917feb7..14f43182e 100644--- a/.claude-plugin/marketplace.json+++ b/.claude-plugin/marketplace.json@@ -5,14 +5,14 @@},"metadata": {"description": "Headroom marketplace for Claude Code and GitHub Copilot CLI plugins.",- "version": "0.13.2"+ "version": "0.13.4"},"plugins": [{"name": "headroom","source": "./plugins/headroom-agent-hooks","description": "Headroom startup hooks for Claude Code and GitHub Copilot CLI.",- "version": "0.13.2",+ "version": "0.13.4","author": {"name": "Headroom Contributors","url": "https://github.com/chopratejas/headroom"diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.jsonindex 79917feb7..14f43182e 100644--- a/.github/plugin/marketplace.json+++ b/.github/plugin/marketplace.json@@ -5,14 +5,14 @@},"metadata": {"description": "Headroom marketplace for Claude Code and GitHub Copilot CLI plugins.",- "version": "0.13.2"+ "version": "0.13.4"},"plugins": [{"name": "headroom","source": "./plugins/headroom-agent-hooks","description": "Headroom startup hooks for Claude Code and GitHub Copilot CLI.",- "version": "0.13.2",+ "version": "0.13.4","author": {"name": "Headroom Contributors","url": "https://github.com/chopratejas/headroom"diff --git a/headroom/transforms/smart_crusher.py b/headroom/transforms/smart_crusher.pyindex 1d1d3abd4..1ae5ac5f1 100644--- a/headroom/transforms/smart_crusher.py+++ b/headroom/transforms/smart_crusher.py@@ -42,6 +42,39 @@ from .base import Transformlogger = logging.getLogger(__name__)+# ─── CCR sentinel ─────────────────────────────────────────────────────────+#+# When SmartCrusher's lossy path drops rows, it appends a sentinel object+# `{"_ccr_dropped": "<<ccr:HASH N_rows_offloaded>>"}` to the kept-items+# array. The LLM sees this in the prompt and can ask for the original via+# the CCR retrieval tool. Downstream consumers that iterate the array+# expecting a uniform schema (e.g. `for e in entries: e["level"]`) need+# to skip the sentinel — that's what `strip_ccr_sentinels` is for.++CCR_SENTINEL_KEY = "_ccr_dropped"+++def is_ccr_sentinel(item: Any) -> bool:+ """True if `item` is a CCR-dropped sentinel object."""+ return isinstance(item, dict) and CCR_SENTINEL_KEY in item+++def strip_ccr_sentinels(items: Any) -> Any:+ """Return `items` with any CCR-dropped sentinel objects filtered out.++ Pass this through any iteration over a compressed array's contents+ when your code expects a uniform-schema list of records. The sentinel+ carries a `<<ccr:HASH ...>>` marker for the LLM and shouldn't be+ confused for a record — it has only the `_ccr_dropped` key.++ Non-list inputs pass through unchanged so callers can wrap whatever+ `json.loads` returned without first checking the shape.+ """+ if not isinstance(items, list):+ return items+ return [x for x in items if not is_ccr_sentinel(x)]++# ─── Public dataclasses ───────────────────────────────────────────────────diff --git a/plugins/headroom-agent-hooks/.claude-plugin/plugin.json b/plugins/headroom-agent-hooks/.claude-plugin/plugin.jsonindex 569eb4505..fbe47871e 100644--- a/plugins/headroom-agent-hooks/.claude-plugin/plugin.json+++ b/plugins/headroom-agent-hooks/.claude-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "headroom",- "version": "0.13.2",+ "version": "0.13.4","description": "Headroom startup hooks for Claude Code and GitHub Copilot CLI.","author": {"name": "Headroom Contributors",diff --git a/plugins/headroom-agent-hooks/.github/plugin/plugin.json b/plugins/headroom-agent-hooks/.github/plugin/plugin.jsonindex c9a3de90f..1a6db07a5 100644--- a/plugins/headroom-agent-hooks/.github/plugin/plugin.json+++ b/plugins/headroom-agent-hooks/.github/plugin/plugin.json@@ -1,6 +1,6 @@{"name": "headroom",- "version": "0.13.2",+ "version": "0.13.4","description": "Headroom startup hooks for Claude Code and GitHub Copilot CLI.","author": {"name": "Headroom Contributors",diff --git a/tests/test_integrations/langchain/test_evals.py b/tests/test_integrations/langchain/test_evals.pyindex c18b8b9f3..b46160a09 100644--- a/tests/test_integrations/langchain/test_evals.py+++ b/tests/test_integrations/langchain/test_evals.py@@ -18,6 +18,7 @@ import pytestfrom headroom.config import SmartCrusherConfigfrom headroom.providers import OpenAIProviderfrom headroom.transforms import SmartCrusher+from headroom.transforms.smart_crusher import strip_ccr_sentinels# Test fixtures for realistic data@@ -190,8 +191,12 @@ class TestErrorPreservation:json_match = re.search(r"(\{.*\})", compressed_output, re.DOTALL)compressed_data = json.loads(json_match.group(1) if json_match else compressed_output)- # Count preserved errors- compressed_errors = [e for e in compressed_data["entries"] if e["level"] == "ERROR"]+ # Count preserved errors. Strip CCR-dropped sentinel objects+ # before iterating — they carry the retrieval marker for the LLM+ # but don't share the entry schema.+ compressed_errors = [+ e for e in strip_ccr_sentinels(compressed_data["entries"]) if e["level"] == "ERROR"+ ]# CRITICAL: 100% of errors must be preservedassert len(compressed_errors) == len(original_errors), (@@ -226,7 +231,9 @@ class TestErrorPreservation:json_match = re.search(r"(\{.*\})", compressed_output, re.DOTALL)compressed_data = json.loads(json_match.group(1) if json_match else compressed_output)- compressed_errors = [e for e in compressed_data["entries"] if e["level"] == "ERROR"]+ compressed_errors = [+ e for e in strip_ccr_sentinels(compressed_data["entries"]) if e["level"] == "ERROR"+ ]# Even with many errors, ALL must be preservedassert len(compressed_errors) == len(original_errors), (@@ -314,7 +321,7 @@ class TestRelevancePreservation:# At least some high-relevance results should be preserved# (BM25 may not catch all without exact keyword matches)compressed_high_relevance = [- r for r in compressed_data["results"] if r["relevance_score"] > 0.8+ r for r in strip_ccr_sentinels(compressed_data["results"]) if r["relevance_score"] > 0.8]# With BM25, we should preserve at least 1 high-relevance resultdiff --git a/tests/test_integrations/mcp/test_server.py b/tests/test_integrations/mcp/test_server.pyindex b3d85004b..4ff7fbebd 100644--- a/tests/test_integrations/mcp/test_server.py+++ b/tests/test_integrations/mcp/test_server.py@@ -19,6 +19,7 @@ from headroom.integrations.mcp import (compress_tool_result_with_metrics,)from headroom.providers import OpenAIProvider+from headroom.transforms.smart_crusher import strip_ccr_sentinels# ============================================================================# Test Fixtures@@ -280,7 +281,9 @@ class TestMCPErrorPreservation:compressed_data = json.loads(result.compressed_content)compressed_errors = [- e for e in compressed_data["entries"] if e["level"] in ["ERROR", "FATAL"]+ e+ for e in strip_ccr_sentinels(compressed_data["entries"])+ if e["level"] in ["ERROR", "FATAL"]]# CRITICAL: 100% of errors must be preserved@@ -306,7 +309,7 @@ class TestMCPErrorPreservation:# Should preserve some messages with error keywords (SmartCrusher detects these)error_msgs = [m- for m in compressed_data["messages"]+ for m in strip_ccr_sentinels(compressed_data["messages"])if any(kw in m["text"].lower() for kw in ["error", "failed", "exception"])]assert len(error_msgs) > 0, "Should preserve some error messages"@@ -327,7 +330,9 @@ class TestMCPErrorPreservation:compressed_data = json.loads(result.compressed_content)compressed_errors = [- r for r in compressed_data["rows"] if "error" in str(r["status"]).lower()+ r+ for r in strip_ccr_sentinels(compressed_data["rows"])+ if "error" in str(r["status"]).lower()]# Should preserve most error rows@@ -350,7 +355,7 @@ class TestMCPErrorPreservation:# Should preserve at least some bugscompressed_bugs = [i- for i in compressed_data["issues"]+ for i in strip_ccr_sentinels(compressed_data["issues"])if any(label in ["bug", "critical", "urgent", "blocker"] for label in i["labels"])]