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: keep file-read tool output byte-exact through the lossless fold
Tejas Chopra59499f73ac49
diff --git a/headroom/config.py b/headroom/config.pyindex b1dc607eb..5bc864f70 100644--- a/headroom/config.py+++ b/headroom/config.py@@ -244,11 +244,15 @@ DEFAULT_EXCLUDE_TOOLS: frozenset[str] = frozenset(# These excluded web-tool results must remain byte-faithful. Even the# excluded-tool lossless fold rewrites formatted JSON.-# Three independent consumers key off this frozenset, all in-# transforms/content_router.py: ContentRouter's two per-block CCR-retrieve-# guards, and _cross_turn_dedup_messages's verbatim_tool_ids -- the latter has-# no dedicated guard of its own, so removing headroom_retrieve from here would-# silently reopen the retrieval loop for that path with cross-turn dedup on.+# Five consumers key off this frozenset, across two modules -- a name added here+# is protected on every wire shape, not just the one you happened to test:+# transforms/content_router.py has ContentRouter's two per-block excluded-tool+# guards (OpenAI chat + Anthropic blocks) and _cross_turn_dedup_messages's+# verbatim_tool_ids; proxy/handlers/openai.py builds verbatim_excluded_call_ids+# for the Responses excluded-tool guard and for the Responses dedup's+# protected_call_ids. The dedup consumers have no dedicated guard of their own,+# so removing headroom_retrieve from here would silently reopen the retrieval+# loop for those paths with cross-turn dedup on.DEFAULT_VERBATIM_EXCLUDE_TOOLS: frozenset[str] = frozenset({"WebSearch",@@ -263,6 +267,45 @@ DEFAULT_VERBATIM_EXCLUDE_TOOLS: frozenset[str] = frozenset(})+# File-READ tools whose output the excluded-tool lossless fold must never+# REWRITE. A strictly weaker protection than DEFAULT_VERBATIM_EXCLUDE_TOOLS+# above, and that gap is the whole reason there are two sets: this one gates only+# the fold, so these tools keep cross-turn dedup and the age-based fall-through.+#+# The failure being fixed: a read tool that returns raw file bytes (Codex-style+# `read`, custom agents, /v1/compress callers naming their own tools) hands+# `_lossless_compact_excluded` a pretty-printed JSON file, which json-min's it.+# That fold is data-lossless and the proxy can invert it -- but the inverse runs+# on OUR side, while the copy that has to match on disk is typed by the MODEL out+# of the bytes it was SHOWN. It builds `Edit(old_string=...)` from minified JSON,+# the file on disk is still pretty-printed, the edit misses, and the retry turn+# costs far more than the fold saved. The log fold (repeats rewritten to+# `... (repeated N times)`) and the search fold (path hoisted into a heading)+# destroy an Edit anchor the same way, so this gates the fold as a whole rather+# than the JSON branch alone. DEFAULT_EXCLUDE_TOOLS has claimed since forever+# that Read "Returns exact file content needed for Edit tool's old_string+# matching"; this is what makes that true instead of aspirational.+#+# Why NOT just add these to DEFAULT_VERBATIM_EXCLUDE_TOOLS, which would have been+# the one-line fix: that set also gates cross-turn dedup and the age-based lossy+# fall-through, and neither shares the failure mode. Dedup replaces a repeat with+# an in-context pointer to an EARLIER copy that is never rewritten (the+# keep-earliest invariant in transforms/cross_turn_dedup.py), so the true bytes+# stay physically in the window for the model to copy from; the fold leaves them+# nowhere at all. Measured on one file read three times, dedup is worth ~66% of+# those tokens -- the largest Read-side saving there is, and the one that still+# fires on Claude Code's `cat -n`-shaped Read output, where the fold never fires+# in the first place. Buying byte-exactness with dedup would be paying the large+# bill to plug the small leak. `view` stays in the stricter set above: that was a+# deliberate, documented call for Copilot and loosening it is not this change's+# business.+DEFAULT_BYTE_EXACT_EXCLUDE_TOOLS: frozenset[str] = frozenset(+ {+ "Read",+ "read",+ }+)+def _tool_name_aliases(name: str) -> tuple[str, ...]:"""Return equivalent spellings for tool exclusion matching."""diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.pyindex 8905f91e7..af42e36ee 100644--- a/headroom/proxy/handlers/openai.py+++ b/headroom/proxy/handlers/openai.py@@ -2110,6 +2110,7 @@ class OpenAIHandlerMixin:# original and lowercased name variants (see _parse_exclude_tools), but# we also test the lowercased name defensively for case-insensitivity.from headroom.config import (+ DEFAULT_BYTE_EXACT_EXCLUDE_TOOLS,DEFAULT_EXCLUDE_TOOLS,DEFAULT_VERBATIM_EXCLUDE_TOOLS,is_tool_excluded,@@ -2129,6 +2130,16 @@ class OpenAIHandlerMixin:for call_id, fn_name in function_name_by_call_id.items()if is_tool_excluded(fn_name, DEFAULT_VERBATIM_EXCLUDE_TOOLS)}+ # A file read is protected from the lossless FOLD only — its bytes come+ # back as the model's `Edit(old_string=…)` anchor, so a rewrite costs a+ # missed edit. Deliberately NOT folded into verbatim_excluded_call_ids:+ # that set also gates the Responses cross-turn dedup below, and dedup+ # leaves the true bytes in context (see DEFAULT_BYTE_EXACT_EXCLUDE_TOOLS).+ byte_exact_call_ids: set[str] = {+ call_id+ for call_id, fn_name in function_name_by_call_id.items()+ if is_tool_excluded(fn_name, DEFAULT_BYTE_EXACT_EXCLUDE_TOOLS)+ }# Read protection (HEADROOM_PROTECT_READS) — parity with the# chat/Anthropic path (ContentRouter.apply). Output of a file-READ@@ -2251,9 +2262,14 @@ class OpenAIHandlerMixin:# Note: when output is a content-part array, fold each text part# individually using ("output_part", index) slots to preserve the# array structure (non-text parts like images are left untouched).+ # A file read skips the fold entirely: this is the Codex wire,+ # where `read` really does return raw file bytes, so a fold here+ # is exactly what breaks the next `Edit(old_string=…)`.excluded_folded = Falseraw_output = item.get("output")- if isinstance(raw_output, list):+ if call_id in byte_exact_call_ids:+ pass # byte-exact: no fold, fall through to the debug record+ elif isinstance(raw_output, list):for pidx, part in enumerate(raw_output):if (isinstance(part, dict)diff --git a/headroom/transforms/content_router.py b/headroom/transforms/content_router.pyindex 71f7f6072..a1c07e10d 100644--- a/headroom/transforms/content_router.py+++ b/headroom/transforms/content_router.py@@ -51,6 +51,7 @@ from enum import Enumfrom typing import Anyfrom ..config import (+ DEFAULT_BYTE_EXACT_EXCLUDE_TOOLS,DEFAULT_EXCLUDE_TOOLS,DEFAULT_VERBATIM_EXCLUDE_TOOLS,ReadLifecycleConfig,@@ -5201,8 +5202,15 @@ class ContentRouter(Transform):continueif messages_from_end <= read_protection_window:# Protected from lossy compression — but grep/log/json- # output can still be losslessly compacted.- compacted = self._lossless_compact_excluded(content)+ # output can still be losslessly compacted, UNLESS this is+ # a file read: every fold rewrites the bytes the model+ # copies into `Edit(old_string=…)`, and a missed edit costs+ # a whole turn (see DEFAULT_BYTE_EXACT_EXCLUDE_TOOLS).+ compacted = (+ None+ if is_tool_excluded(tool_name, DEFAULT_BYTE_EXACT_EXCLUDE_TOOLS)+ else self._lossless_compact_excluded(content)+ )if compacted is not None:folded, kind = compactedresult_slots[i] = {**message, "content": folded}@@ -6174,8 +6182,15 @@ class ContentRouter(Transform):continueif messages_from_end <= read_protection_window:# Protected from lossy compression — but grep/log/json- # output can still be losslessly compacted.- compacted = self._lossless_compact_excluded(block.get("content"))+ # output can still be losslessly compacted, UNLESS this is+ # a file read (see DEFAULT_BYTE_EXACT_EXCLUDE_TOOLS). This+ # is the shape Claude Code's own `Read` arrives in, so it+ # has to carry the same guard as the OpenAI branch above.+ compacted = (+ None+ if is_tool_excluded(tool_name, DEFAULT_BYTE_EXACT_EXCLUDE_TOOLS)+ else self._lossless_compact_excluded(block.get("content"))+ )if compacted is not None:folded, kind = compactednew_blocks.append({**block, "content": folded})diff --git a/tests/test_lossless_excluded_compaction.py b/tests/test_lossless_excluded_compaction.pyindex 5872299fe..20a4fc86d 100644--- a/tests/test_lossless_excluded_compaction.py+++ b/tests/test_lossless_excluded_compaction.py@@ -1,8 +1,8 @@"""Information-preserving compaction for EXCLUDED tool output.-Excluded tools (Read/Grep/Glob/Write/Edit) are protected from *lossy*-compression for accuracy. This feature still compacts them by detected shape,-using only reversible / data-preserving transforms:+Excluded tools (Grep/Glob/Write/Edit) are protected from *lossy* compression for+accuracy. This feature still compacts them by detected shape, using only+reversible / data-preserving transforms:* SEARCH (grep) -> ripgrep --heading fold [byte-lossless]* LOG -> ANSI strip + run-collapse [byte-lossless modulo ANSI color]@@ -10,6 +10,11 @@ using only reversible / data-preserving transforms:Source code and glob path-lists match nothing -> untouched. Always on(information-preserving, so it needs no feature gate) in every path.++File-READ tools (`Read`/`read`, Copilot's `view`) are the exception: they are in+DEFAULT_VERBATIM_EXCLUDE_TOOLS and skip the fold entirely, because their bytes+come back to us as the model's `Edit(old_string=...)` anchor and must therefore+be byte-faithful, not merely recoverable."""from __future__ import annotations@@ -106,14 +111,21 @@ def test_pipeline_folds_grep_and_recovers(tokenizer):assert search_unheading(out) == GREP-def test_pipeline_compacts_log_read(tokenizer):- out, transforms = _run(LOG, "read", tokenizer)+# The two shape tests below drive `grep`, not `read`. A file-read tool is now+# short-circuited before the fold ever runs (see the byte-faithfulness tests+# further down), so `read` would prove nothing about the fold. `grep` is+# excluded-but-foldable: its output is search results the agent greps again,+# never a string it re-emits as an Edit anchor.+++def test_pipeline_compacts_log_from_excluded_tool(tokenizer):+ out, transforms = _run(LOG, "grep", tokenizer)assert "router:excluded:lossless_log" in transformsassert expand_runs(out) == strip_ansi(LOG)-def test_pipeline_minifies_json_read(tokenizer):- out, transforms = _run(JSON, "read", tokenizer)+def test_pipeline_minifies_json_from_excluded_tool(tokenizer):+ out, transforms = _run(JSON, "grep", tokenizer)assert "router:excluded:lossless_json" in transformsassert json.loads(out) == json.loads(JSON) # data-lossless (same object)@@ -123,6 +135,92 @@ def test_pipeline_leaves_source_read_untouched(tokenizer):assert out == CODE+# --- file reads must be BYTE-faithful, not merely recoverable ----------------+#+# Regression for the read-then-Edit miss: `Read`/`read` were excluded from LOSSY+# compression but not from the excluded-tool lossless fold, so a read of a+# pretty-printed JSON file came back json-min'd. That fold is data-lossless and+# the proxy can invert it -- but the inverse runs on OUR side, while the copy+# that has to match on disk is typed by the MODEL from the bytes it was shown.+# It built `Edit(old_string=...)` out of minified JSON, the file on disk was+# still pretty-printed, the edit missed, and the retry turn cost more than the+# ~480 tokens the fold saved. Copilot's equivalent `view` was already protected;+# `Read` was the asymmetry.+++def _run_anthropic(content: str, tool: str, tokenizer):+ """Claude Code's own wire shape: tool_use / tool_result content blocks.++ Gated by a *separate* guard from the OpenAI chat path (`_run`), so the+ byte-exact rule has to be asserted on both or one wire keeps folding.+ """+ router = ContentRouter(ContentRouterConfig())+ messages = [+ {+ "role": "assistant",+ "content": [{"type": "tool_use", "id": "t1", "name": tool, "input": {}}],+ },+ {+ "role": "user",+ "content": [{"type": "tool_result", "tool_use_id": "t1", "content": content}],+ },+ ]+ result = router.apply(messages, tokenizer, compress_user_messages=True)+ return result.messages[1]["content"][0]["content"], result.transforms_applied++[email protected]("shape", [_run, _run_anthropic], ids=["openai_chat", "anthropic_blocks"])[email protected]("tool", ["Read", "read", "view"])[email protected]("body", [JSON, LOG, GREP], ids=["json", "log", "grep"])+def test_file_read_result_is_byte_exact(shape, tool, body, tokenizer):+ out, transforms = shape(body, tool, tokenizer)+ assert out == body, f"{tool} result was rewritten; the model's Edit anchor would miss"+ assert "router:excluded:tool" in transforms+ assert not any(t.startswith("router:excluded:lossless") for t in transforms)+++def test_read_json_edit_anchor_survives(tokenizer):+ """The exact failure this protects: an Edit anchor copied out of a Read.++ `old_string` is a verbatim slice of the pretty-printed file. Before the fix+ the model saw minified JSON, so the anchor it could construct was not a+ substring of the file on disk and `Edit` missed.+ """+ anchor = ' "users": [\n {\n "id": 0,'+ assert anchor in JSON # the anchor is real on disk+ shown, _ = _run(JSON, "Read", tokenizer)+ assert anchor in shown+++def test_read_is_still_cross_turn_deduped(tokenizer):+ """The deliberate line between the two protection sets — hold it.++ Read is byte-exact against the FOLD, not blanket-verbatim. The one-line+ alternative (adding Read to DEFAULT_VERBATIM_EXCLUDE_TOOLS, next to `view`)+ would also switch off cross-turn dedup, which is worth ~66% of the tokens on+ a file read three times — the largest Read-side saving there is, and unlike+ the fold it does not destroy the bytes: keep-earliest guarantees the first,+ unrewritten copy is still in the window for the model to copy its anchor+ from. If someone later "simplifies" the two sets into one, this fails.+ """+ config = ContentRouterConfig()+ config.enable_cross_turn_dedup = True+ router = ContentRouter(config)+ messages = []+ for k in range(3):+ messages.append(+ {+ "role": "assistant",+ "tool_calls": [{"id": f"c{k}", "function": {"name": "Read", "arguments": "{}"}}],+ }+ )+ messages.append({"role": "tool", "tool_call_id": f"c{k}", "content": CODE})+ result = router.apply(messages, tokenizer, compress_user_messages=True)+ outs = [m["content"] for m in result.messages if m.get("role") == "tool"]+ assert outs[0] == CODE # keep-earliest: the anchor copy is never rewritten+ assert len(outs[2]) < len(CODE) # …and the later repeats still fold to pointers++# --- pluggable lossless provider seam ---------------------------------------@@ -150,6 +248,31 @@ def test_registered_provider_is_authoritative():assert _compact(GREP) is None+def test_byte_exact_read_gate_runs_before_the_provider_seam(tokenizer):+ """The read gate is OSS's own guarantee, not something a provider can opt out of.++ An external provider is contractually only "information-preserving" (see+ transforms/lossless_provider.py) — that admits json-min, which is exactly the+ rewrite that misses the Edit. And the seam hands over `content` with no tool+ name, so a provider *cannot* recognise a read and protect it itself. So the+ gate sits in front of the seam: a read is never offered to a provider at all.+ Every other excluded tool still reaches it, unchanged — the seam's reach+ narrows for file reads only.+ """+ seen: list[str] = []+ set_lossless_provider(lambda content: (seen.append(content), None)[1])++ for tool in ("Read", "read"):+ seen.clear()+ _run(GREP, tool, tokenizer)+ assert seen == [], f"{tool} content was handed to the provider"++ for tool in ("Grep", "grep", "Glob", "Write", "Edit"):+ seen.clear()+ _run(GREP, tool, tokenizer)+ assert seen, f"provider lost reach for {tool}"++def test_provider_exception_falls_back_to_builtin():def boom(content):raise RuntimeError("provider blew up")diff --git a/tests/test_openai_responses_compression_units.py b/tests/test_openai_responses_compression_units.pyindex 863e91272..264fdfe68 100644--- a/tests/test_openai_responses_compression_units.py+++ b/tests/test_openai_responses_compression_units.py@@ -1,8 +1,11 @@from __future__ import annotations+import jsonimport threadingfrom types import MethodType, SimpleNamespace+import pytest+from headroom.proxy.handlers import openai as openai_handlerfrom headroom.proxy.handlers.openai import OpenAIHandlerMixinfrom headroom.transforms.compression_units import UnitCompressionResult@@ -824,6 +827,44 @@ def test_openai_responses_adapter_losslessly_folds_excluded_grep_output_content_assert folded_list[2]["refusal"] == "I cannot process this request"[email protected]("tool", ["read", "Read"])[email protected]("as_content_part", [False, True], ids=["plain", "content_part"])+def test_openai_responses_adapter_never_folds_a_file_read(tool, as_content_part):+ """A file read stays byte-exact on the Responses wire too.++ This is the Codex wire, where `read` genuinely returns raw file bytes rather+ than Claude Code's `cat -n` rendering — so it is the shape where folding a+ read really does destroy the `Edit(old_string=…)` anchor the model is about+ to type. See DEFAULT_BYTE_EXACT_EXCLUDE_TOOLS. The grep folds above must keep+ working; only reads opt out.+ """+ router = ContentRouter()+ handler = _handler_with_router(router)+ # Pretty-printed JSON: json-min is the fold that used to eat this.+ file_bytes = json.dumps(+ {"deps": [{"name": f"pkg{i}", "version": "1.0.0"} for i in range(40)]}, indent=2+ )+ output = [{"type": "output_text", "text": file_bytes}] if as_content_part else file_bytes+ payload = {+ "model": "gpt-5",+ "input": [+ {"type": "function_call", "call_id": "call_1", "name": tool, "arguments": "{}"},+ {"type": "function_call_output", "call_id": "call_1", "output": output},+ ],+ }++ new_payload, _modified, _saved, transforms, _units, _chain, _attempted = (+ handler._compress_openai_responses_live_text_units_with_router(+ payload,+ model="gpt-5",+ request_id=f"req_read_verbatim_{tool}_{as_content_part}",+ )+ )++ assert "router:excluded:lossless" not in transforms+ assert new_payload["input"][1]["output"] == output++def test_openai_responses_adapter_excludes_tool_case_insensitively_with_debug(monkeypatch):"""Excluded match is case-insensitive, and the debug path stays exercised.