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(review): address PR #210 feedback — race, query-params, SHA logging, frozen prefix, etc
chopratejase165a579f8dd
diff --git a/headroom/binaries.py b/headroom/binaries.pyindex 659d1e540..467ec84ee 100644--- a/headroom/binaries.py+++ b/headroom/binaries.py@@ -18,8 +18,10 @@ Env vars:from __future__ import annotationsimport functools+import globimport hashlibimport json+import loggingimport osimport platformimport shutil@@ -28,12 +30,15 @@ import sysimport tarfileimport tempfileimport urllib.error+import urllib.parseimport urllib.requestimport zipfilefrom dataclasses import dataclassfrom pathlib import Pathfrom typing import Any+logger = logging.getLogger(__name__)+__all__ = ["BinaryError","BinaryFetchError",@@ -99,7 +104,12 @@ def _machine_to_arch(machine: str) -> str:def _is_musl() -> bool:- # Best-effort musl detection on Linux. Never raises.+ """Best-effort musl detection on Linux. Never raises.++ First: ask `ldd --version` (returns 'musl' on Alpine/Void).+ Fallback: check for the musl dynamic loader at /lib/ld-musl-*.so.1,+ which is present on Alpine even when `ldd` is absent.+ """try:out = subprocess.run(["ldd", "--version"],@@ -108,9 +118,14 @@ def _is_musl() -> bool:timeout=2,check=False,)- return "musl" in (out.stdout + out.stderr).lower()+ if "musl" in (out.stdout + out.stderr).lower():+ return Trueexcept (FileNotFoundError, subprocess.TimeoutExpired, OSError):- return False+ pass+ # Fallback: musl ships a distinctive dynamic loader.+ if glob.glob("/lib/ld-musl-*.so.1") or glob.glob("/lib64/ld-musl-*.so.1"):+ return True+ return False@functools.lru_cache(maxsize=1)@@ -256,8 +271,10 @@ def _sha256_file(path: Path) -> str:def _verify_sha256(path: Path, expected: str | None) -> None:if not expected:- # Upstream release not SHA-pinned in registry. We trusted HTTPS + the- # GitHub CDN for the download; log nothing here — `doctor` surfaces.+ # Upstream release not SHA-pinned in registry. HTTPS + the GitHub CDN+ # is the only integrity check. Log at INFO so verbose runs can see+ # this state; `doctor` surfaces the same fact via `sha_pinned=False`.+ logger.info("binary %s downloaded without sha256 pin (HTTPS trust only)", path.name)returngot = _sha256_file(path)if got.lower() != expected.lower():@@ -279,8 +296,8 @@ def _extract(archive: Path, member: str, dest: Path) -> None:elif name.endswith(".zip"):with zipfile.ZipFile(archive) as zf:_extract_member_from_zip(zf, member, dest)- elif name.endswith(".gz") and "." not in name[:-3]:- # bare .gz of a single binary+ elif name.endswith(".gz") and not (name.endswith(".tar.gz") or name.endswith(".tgz")):+ # bare .gz of a single binary (e.g. `scc-linux-x86_64.gz`)import gzipwith gzip.open(archive, "rb") as gz, dest.open("wb") as out:@@ -411,19 +428,25 @@ def resolve(tool: str) -> Path:with tempfile.TemporaryDirectory(prefix="headroom-fetch-") as tmp:tmp_dir = Path(tmp)- download_path = tmp_dir / Path(url).name+ # Strip query params so mirror URLs like `.../difft.tar.gz?token=...`+ # don't produce filenames that break archive-type detection.+ url_path = urllib.parse.urlparse(url).path+ download_path = tmp_dir / (Path(url_path).name or "download")_download(url, download_path)_verify_sha256(download_path, sha256)staging = tmp_dir / "out"_extract(download_path, member, staging)binary_path.parent.mkdir(parents=True, exist_ok=True)- # Atomic-ish move: write to sibling then rename.- tmp_final = binary_path.with_suffix(binary_path.suffix + ".partial")+ # Atomic move with a PID-scoped partial name so two concurrent+ # `headroom proxy` starts don't race on the same .partial path.+ tmp_final = binary_path.with_name(f"{binary_path.name}.{os.getpid()}.partial")shutil.move(str(staging), tmp_final)try:tmp_final.chmod(0o755)- except OSError:- pass # Windows or restricted FS — .exe is already executable+ except OSError as e:+ if not sys.platform.startswith("win"):+ logger.warning("chmod +x failed for %s: %s", tmp_final, e)+ # On Windows the .exe is already executable; elsewhere we logged.os.replace(tmp_final, binary_path)return binary_path@@ -480,12 +503,13 @@ def status() -> list[dict[str, Any]]:out.append(row)continuetry:- _asset_for_platform(name, plat)+ asset = _asset_for_platform(name, plat)except PlatformNotSupported as e:row["state"] = "unsupported-platform"row["detail"] = str(e)out.append(row)continue+ row["sha_pinned"] = bool(asset.get("sha256"))cached = _cached_path(name, entry["version"], plat)if cached.exists():row["path"] = str(cached)diff --git a/headroom/cli/proxy.py b/headroom/cli/proxy.pyindex c5ad3e5fa..dc282fb99 100644--- a/headroom/cli/proxy.py+++ b/headroom/cli/proxy.py@@ -281,11 +281,24 @@ def proxy(# tools are downloaded once at startup if missing, then cached per-user.from headroom.binaries import ensure_tools- ensure_tools()+ resolved_tools = ensure_tools()# Opt-in: turn on tool_result interceptors (ast-grep Read outline, etc.).# The TransformPipeline reads this env var at construction time.if intercept_tool_results:+ # Validate each interceptor's critical tool actually installed. Today+ # only the ast-grep Read outliner is wired; add entries here as+ # interceptors gain dependencies.+ critical_tools = ["ast-grep"]+ missing = [t for t in critical_tools if not resolved_tools.get(t)]+ if missing:+ click.secho(+ f"warning: --intercept-tool-results set but tool(s) unavailable: {missing}. "+ "Interceptors depending on them will silently pass through. "+ "Run `headroom tools doctor` to diagnose.",+ fg="yellow",+ err=True,+ )os.environ["HEADROOM_INTERCEPT_ENABLED"] = "1"# Resolve API URL overrides: CLI flag > env var > Nonediff --git a/headroom/cli/tools.py b/headroom/cli/tools.pyindex 83ca8e081..39e767b8c 100644--- a/headroom/cli/tools.py+++ b/headroom/cli/tools.py@@ -52,8 +52,11 @@ def _exec_tool(tool: str, argv: Sequence[str]) -> None:click.secho(f"error: {e}", fg="red", err=True)sys.exit(2)- # Replace the current process on POSIX for correct signal handling;- # fall back to subprocess on Windows where os.execv is awkward.+ # Replace the current process on POSIX for correct signal handling and+ # fd/pty passthrough. NOTE: os.execv replaces the process image — atexit+ # handlers, context managers, and Python finalizers do NOT run. Anything+ # that needs to clean up on shell exit must be handled elsewhere (e.g.+ # the parent `headroom` process, not these thin passthroughs).cmd = [str(path), *argv]if os.name == "posix":os.execv(cmd[0], cmd) # never returns@@ -212,8 +215,13 @@ def tools_install_cmd(tools: tuple[str, ...], force: bool) -> None:)if cached.exists():cached.unlink()- except Exception: # noqa: BLE001- pass+ except OSError as e:+ click.secho(+ f"{name}: failed to remove cached binary: {e}",+ fg="yellow",+ err=True,+ )+ exit_code = 1try:path = binaries.resolve(name)click.secho(f"{name}: installed → {path}", fg="green")diff --git a/headroom/proxy/interceptors/__init__.py b/headroom/proxy/interceptors/__init__.pyindex e57a7af15..f2fbdfcba 100644--- a/headroom/proxy/interceptors/__init__.py+++ b/headroom/proxy/interceptors/__init__.py@@ -18,6 +18,7 @@ from .base import (ToolResultInterceptorTransform,TransformSpan,apply_to_messages,+ interceptor_failure_counts,register,)@@ -28,5 +29,6 @@ __all__ = ["ToolResultInterceptorTransform","TransformSpan","apply_to_messages",+ "interceptor_failure_counts","register",]diff --git a/headroom/proxy/interceptors/astgrep.py b/headroom/proxy/interceptors/astgrep.pyindex a6da3407e..ed0874bb6 100644--- a/headroom/proxy/interceptors/astgrep.py+++ b/headroom/proxy/interceptors/astgrep.py@@ -13,6 +13,7 @@ from __future__ import annotationsimport jsonimport loggingimport os+import shutilimport subprocessimport tempfilefrom pathlib import Path@@ -33,6 +34,11 @@ MIN_CHARS_TO_REWRITE = int(os.environ.get("HEADROOM_INTERCEPT_READ_MIN_CHARS", "# Tool_input keys that indicate the model targeted a specific line range;# outlining would frustrate that intent and likely cause a re-read.+# Provenance of the keys we recognize:+# offset / limit — Claude Code's Read tool (pagination by line).+# line_range — Cursor / VS Code Copilot read_file with explicit range.+# start_line / end_line — Aider, Continue, some MCP filesystem servers.+# ranges — OpenAI Codex file tools (list of [start,end] pairs)._RANGE_KEYS = ("offset", "limit", "line_range", "start_line", "end_line", "ranges")# ast-grep --lang is passed these values; only extensions with a stable@@ -121,7 +127,17 @@ class AstGrepReadOutline:tool_input: dict[str, Any],) -> str | None:"""Key by file_path so a second Read of the same file passes through."""- return _path_from_input(tool_input)+ path = _path_from_input(tool_input)+ if path is None:+ # matches() returned True but no recognized path key — the tool+ # may use an unknown key (e.g. some MCP servers use `file`).+ # Without a key, progressive disclosure can't protect against+ # re-outlining; log once for observability.+ logger.debug(+ "ast-grep: no path key in tool_input (keys=%s); progressive disclosure disabled",+ sorted(tool_input.keys()),+ )+ return pathdef _detect_lang_from_input(tool_input: dict[str, Any]) -> str | None:@@ -155,10 +171,16 @@ def _run_ast_grep(return []# Use the canonical extension so ast-grep can pick the right grammar.+ # Write into a private mode-0700 temp dir — /tmp is shared on multi-tenant+ # systems and tool_output is untrusted content.ext = next((e for e, L in _EXT_TO_LANG.items() if L == lang), ".txt")- with tempfile.NamedTemporaryFile(mode="w", suffix=ext, delete=False, encoding="utf-8") as tmp:- tmp.write(source)- tmp_path = tmp.name+ tmp_dir = Path(tempfile.mkdtemp(prefix="headroom-sg-"))+ try:+ os.chmod(tmp_dir, 0o700)+ except OSError:+ pass # best-effort on Windows / restricted FS+ tmp_path = tmp_dir / f"src{ext}"+ tmp_path.write_text(source, encoding="utf-8")try:for pattern in patterns:@@ -172,7 +194,7 @@ def _run_ast_grep("--lang",lang,"--json=stream",- tmp_path,+ str(tmp_path),],capture_output=True,text=True,@@ -182,21 +204,36 @@ def _run_ast_grep(except (subprocess.TimeoutExpired, OSError) as e:logger.debug("ast-grep timed out or failed: %s", e)continue- if completed.returncode != 0:+ # rc=0: matches. rc=1: no matches (expected). rc>=2: real error+ # (bad syntax, grammar missing, corrupt binary) — log it so+ # users can diagnose.+ if completed.returncode == 1:+ continue+ if completed.returncode >= 2:+ logger.debug(+ "ast-grep error (rc=%d, lang=%s, pattern=%r): %s",+ completed.returncode,+ lang,+ pattern,+ (completed.stderr or "")[:200],+ )continue- for line in completed.stdout.splitlines():- line = line.strip()- if not line:- continue+ lines = [ln.strip() for ln in completed.stdout.splitlines() if ln.strip()]+ parse_failures = 0+ for line in lines:try:all_matches.append(json.loads(line))except json.JSONDecodeError:- continue+ parse_failures += 1+ if lines and parse_failures == len(lines):+ logger.warning(+ "ast-grep produced output but every line failed to parse as JSON "+ "(rc=0, lang=%s, pattern=%r) — likely version mismatch or corrupt binary",+ lang,+ pattern,+ )finally:- try:- Path(tmp_path).unlink()- except OSError:- pass+ shutil.rmtree(tmp_dir, ignore_errors=True)return all_matchesdiff --git a/headroom/proxy/interceptors/base.py b/headroom/proxy/interceptors/base.pyindex 5a6f146f9..996d8c938 100644--- a/headroom/proxy/interceptors/base.py+++ b/headroom/proxy/interceptors/base.py@@ -2,7 +2,9 @@from __future__ import annotations+import jsonimport logging+import threadingfrom dataclasses import dataclassfrom typing import Any, Protocol, runtime_checkable@@ -17,6 +19,30 @@ from headroom.transforms.base import Transformlogger = logging.getLogger(__name__)+# Interceptor failure counters exposed via `interceptor_failure_counts()`.+# Incremented whenever `matches()`, `transform()`, or `progressive_disclosure_key()`+# raises an exception. Dashboards / stats endpoints can surface these to+# distinguish "nothing eligible to intercept" from "everything is crashing."+_FAILURES: dict[str, int] = {}+_FAILURES_LOCK = threading.Lock()+++def _record_failure(interceptor_name: str) -> None:+ with _FAILURES_LOCK:+ _FAILURES[interceptor_name] = _FAILURES.get(interceptor_name, 0) + 1+++def interceptor_failure_counts() -> dict[str, int]:+ """Return a snapshot of interceptor failure counters."""+ with _FAILURES_LOCK:+ return dict(_FAILURES)+++def reset_interceptor_failure_counts() -> None:+ """Reset failure counters (used by tests)."""+ with _FAILURES_LOCK:+ _FAILURES.clear()+@runtime_checkableclass ToolResultInterceptor(Protocol):@@ -76,7 +102,7 @@ class TransformSpan:return max(self.tokens_before - self.tokens_after, 0)-@dataclass+@dataclass(frozen=True)class InterceptionResult:messages: list[dict[str, Any]]spans: list[TransformSpan]@@ -93,14 +119,15 @@ def register(interceptor: ToolResultInterceptor) -> None:INTERCEPTORS.append(interceptor)-def _find_tool_use(+def _build_tool_use_index(messages: list[dict[str, Any]],- tool_use_id: str,-) -> tuple[str | None, dict[str, Any]]:- """Walk prior messages to find the tool_use block that produced a given id.+) -> dict[str, tuple[str | None, dict[str, Any]]]:+ """Scan once and build a dict of {tool_use_id: (tool_name, tool_input)}.- Returns (tool_name, tool_input) or (None, {}) if not found.+ O(total_blocks) to build, O(1) to look up — used instead of a per-message+ linear scan so `apply_to_messages()` stays linear in message count."""+ index: dict[str, tuple[str | None, dict[str, Any]]] = {}for msg in messages:content = msg.get("content")if isinstance(content, list):@@ -108,30 +135,31 @@ def _find_tool_use(if not isinstance(block, dict):continue# Anthropic: {"type": "tool_use", "id": ..., "name": ..., "input": {...}}- if block.get("type") == "tool_use" and block.get("id") == tool_use_id:- return (- block.get("name"),- block.get("input") or {},- )+ if block.get("type") == "tool_use":+ bid = block.get("id")+ if isinstance(bid, str):+ index[bid] = (block.get("name"), block.get("input") or {})# OpenAI: assistant message with `tool_calls` listtool_calls = msg.get("tool_calls")if isinstance(tool_calls, list):for call in tool_calls:- if isinstance(call, dict) and call.get("id") == tool_use_id:- fn = call.get("function") or {}- # arguments is a JSON string in OpenAI; decode best-effort- import json as _json-- args: dict[str, Any] = {}- if isinstance(fn.get("arguments"), str):- try:- args = _json.loads(fn["arguments"])- except Exception: # noqa: BLE001- args = {}- elif isinstance(fn.get("arguments"), dict):- args = fn["arguments"]- return fn.get("name"), args- return None, {}+ if not isinstance(call, dict):+ continue+ cid = call.get("id")+ if not isinstance(cid, str):+ continue+ fn = call.get("function") or {}+ args: dict[str, Any] = {}+ raw_args = fn.get("arguments")+ if isinstance(raw_args, str):+ try:+ args = json.loads(raw_args)+ except json.JSONDecodeError:+ args = {}+ elif isinstance(raw_args, dict):+ args = raw_args+ index[cid] = (fn.get("name"), args)+ return indexdef _tool_use_id_for_message(msg: dict[str, Any]) -> str | None:@@ -171,6 +199,9 @@ def apply_to_messages(# file from being outlined again — the model evidently came back for# more, so give it the raw content.fired: dict[str, set[str]] = {}+ # Build O(1) tool_use lookup index once per request — prior implementation+ # was O(n²) on long conversations.+ tool_use_index = _build_tool_use_index(messages)for msg in messages:if not _is_tool_result_message(msg):@@ -186,7 +217,10 @@ def apply_to_messages(tool_name: str | None = Nonetool_input: dict[str, Any] = {}if tuid:- tool_name, tool_input = _find_tool_use(messages, tuid)+ tool_name, tool_input = tool_use_index.get(tuid, (None, {}))+ if tuid not in tool_use_index:+ # Orphaned tool_result — interceptors run without tool context.+ logger.debug("tool_result %s has no matching tool_use", tuid)current = originalfor interceptor in INTERCEPTORS:@@ -198,7 +232,11 @@ def apply_to_messages(key = key_fn(tool_name, tool_input)except Exception as e: # noqa: BLE001logger.warning("interceptor %s key() failed: %s", interceptor.name, e)- key = None+ _record_failure(interceptor.name)+ # Skip this interceptor entirely rather than firing+ # without progressive-disclosure protection — a broken+ # key would otherwise fire on every Read of the same file.+ continueif key and key in fired.get(interceptor.name, set()):continue@@ -208,6 +246,7 @@ def apply_to_messages(rewritten = interceptor.transform(tool_name, tool_input, current)except Exception as e: # noqa: BLE001 — never crash a requestlogger.warning("interceptor %s failed: %s", interceptor.name, e)+ _record_failure(interceptor.name)continueif not rewritten or rewritten == current:continue@@ -239,6 +278,9 @@ class ToolResultInterceptorTransform(Transform):Placed at transforms[0] so downstream compressors operate on the already-shrunk content. Transform names of firing interceptors are added to`transforms_applied` so they appear in existing dashboards/metrics.++ Honors the standard `frozen_message_count` contract: leading messages in+ the provider's prefix cache are not modified, preserving cache hits."""name = "tool_result_interceptors"@@ -249,12 +291,24 @@ class ToolResultInterceptorTransform(Transform):tokenizer: Tokenizer,**kwargs: Any,) -> TransformResult:- result = apply_to_messages(messages, tokenizer)- tokens_after = tokenizer.count_messages(result.messages)- tokens_before = tokens_after + sum(s.tokens_saved for s in result.spans)+ # Measure the true baseline on the original messages — back-calculating+ # from `tokens_after + sum(saved)` would double-count per-message+ # overhead that spans don't track.+ tokens_before = tokenizer.count_messages(messages)++ # Honor the frozen prefix: never touch cached messages.+ frozen = int(kwargs.get("frozen_message_count") or 0)+ if frozen > 0:+ frozen_msgs, mutable_msgs = messages[:frozen], messages[frozen:]+ else:+ frozen_msgs, mutable_msgs = [], messages++ result = apply_to_messages(mutable_msgs, tokenizer)+ out_messages = frozen_msgs + result.messages+ tokens_after = tokenizer.count_messages(out_messages)transforms_applied = [f"interceptor:{s.tool}" for s in result.spans] if result.spans else []return TransformResult(- messages=result.messages,+ messages=out_messages,tokens_before=tokens_before,tokens_after=tokens_after,transforms_applied=transforms_applied,diff --git a/headroom/tools.json b/headroom/tools.jsonindex 972424044..1c7c0e90c 100644--- a/headroom/tools.json+++ b/headroom/tools.json@@ -6,17 +6,30 @@"binary": "difft","source": "Wilfred/difftastic","homepage": "https://difftastic.wilfred.me.uk/",+ "_comment": "Upstream publishes glibc Linux builds only. The glibc binaries run on musl hosts (Alpine) via compatibility shims, so we point both gnu and musl keys at the same asset and document it here for auditors.","assets": {"linux-x86_64-gnu": {"url": "https://github.com/Wilfred/difftastic/releases/download/0.64.0/difft-x86_64-unknown-linux-gnu.tar.gz","member": "difft","sha256": null},+ "linux-x86_64-musl": {+ "url": "https://github.com/Wilfred/difftastic/releases/download/0.64.0/difft-x86_64-unknown-linux-gnu.tar.gz",+ "member": "difft",+ "sha256": null,+ "_comment": "same asset as linux-x86_64-gnu; upstream has no dedicated musl build"+ },"linux-aarch64-gnu": {"url": "https://github.com/Wilfred/difftastic/releases/download/0.64.0/difft-aarch64-unknown-linux-gnu.tar.gz","member": "difft","sha256": null},+ "linux-aarch64-musl": {+ "url": "https://github.com/Wilfred/difftastic/releases/download/0.64.0/difft-aarch64-unknown-linux-gnu.tar.gz",+ "member": "difft",+ "sha256": null,+ "_comment": "same asset as linux-aarch64-gnu"+ },"darwin-x86_64": {"url": "https://github.com/Wilfred/difftastic/releases/download/0.64.0/difft-x86_64-apple-darwin.tar.gz","member": "difft",@@ -39,6 +52,7 @@"binary": "scc","source": "boyter/scc","homepage": "https://github.com/boyter/scc",+ "_comment": "scc is a statically-linked Go binary, so the same asset is used for both libc variants. The duplicated gnu/musl entries are intentional — they document musl support for `headroom tools doctor`.","assets": {"linux-x86_64-gnu": {"url": "https://github.com/boyter/scc/releases/download/v3.5.0/scc_Linux_x86_64.tar.gz",diff --git a/tests/test_binaries.py b/tests/test_binaries.pyindex 9d467bef2..73aa6e885 100644--- a/tests/test_binaries.py+++ b/tests/test_binaries.py@@ -7,7 +7,6 @@ from __future__ import annotationsimport hashlibimport io-import osimport sysimport tarfileimport zipfile@@ -186,20 +185,44 @@ def test_offline_error_when_fetch_required(monkeypatch):binaries.resolve("difft")-def test_mirror_substitution():- os.environ["HEADROOM_BINARIES_MIRROR"] = "https://mirror.example.com/gh"+def test_mirror_substitution(monkeypatch):+ monkeypatch.setenv("HEADROOM_BINARIES_MIRROR", "https://mirror.example.com/gh")+ out = binaries._mirror_url(+ "https://github.com/Wilfred/difftastic/releases/download/0.64.0/x.tar.gz"+ )+ assert (+ out == "https://mirror.example.com/gh/Wilfred/difftastic/releases/download/0.64.0/x.tar.gz"+ )+ # Non-matching URLs are left alone.+ assert binaries._mirror_url("https://example.com/x") == "https://example.com/x"+++def test_mirror_url_with_query_params_strips_them_from_download_filename(monkeypatch, fake_urlopen):+ """Mirror URLs with `?token=...` must not leak into the download filename.++ Regression test for the case where `Path(url).name` gave+ `difft.tar.gz?token=abc`, which broke `.endswith(".tar.gz")` detection+ and resulted in a raw archive being copied as an "executable."+ """+ _set_platform(monkeypatch, sys_plat="darwin", machine="arm64")+ monkeypatch.setattr(binaries.shutil, "which", lambda _name: None)+ archive = _make_tar_gz({"difft": b"ok"})+ tokened_url = (+ "https://github.com/Wilfred/difftastic/releases/download/0.64.0/"+ "difft-aarch64-apple-darwin.tar.gz?token=abc&sig=xyz"+ )+ # Override the registry URL for this test.+ reg = binaries._registry()+ asset = reg["tools"]["difft"]["assets"]["darwin-aarch64"]+ original_url = asset["url"]+ asset["url"] = tokened_url+ fake_urlopen[tokened_url] = archivetry:- out = binaries._mirror_url(- "https://github.com/Wilfred/difftastic/releases/download/0.64.0/x.tar.gz"- )- assert (- out- == "https://mirror.example.com/gh/Wilfred/difftastic/releases/download/0.64.0/x.tar.gz"- )- # Non-matching URLs are left alone.- assert binaries._mirror_url("https://example.com/x") == "https://example.com/x"+ path = binaries.resolve("difft")+ assert path.exists()+ assert path.read_bytes() == b"ok"finally:- del os.environ["HEADROOM_BINARIES_MIRROR"]+ asset["url"] = original_urldef test_fetch_extract_and_cache_tar_gz(monkeypatch, fake_urlopen, tmp_path):@@ -271,6 +294,31 @@ def test_sha256_match_passes(monkeypatch, fake_urlopen):# -------- status() ------------------------------------------------------- #+def test_ensure_tools_partial_failure_proxy_still_starts(monkeypatch):+ """If one tool fails to fetch, others still install and ensure_tools returns."""+ _set_platform(monkeypatch, sys_plat="darwin", machine="arm64")+ monkeypatch.setattr(binaries.shutil, "which", lambda _name: None)++ scc_asset = binaries._registry()["tools"]["scc"]["assets"]["darwin-aarch64"]+ scc_tar = _make_tar_gz({"scc": b"ok"})++ def selective_urlopen(req, timeout=None): # noqa: ARG001+ url = req.full_url if hasattr(req, "full_url") else req+ if url == scc_asset["url"]:+ return _FakeResponse(scc_tar)+ # difft fails with a real network-style error.+ import urllib.error++ raise urllib.error.URLError("simulated network failure")++ monkeypatch.setattr(binaries.urllib.request, "urlopen", selective_urlopen)++ result = binaries.ensure_tools(quiet=True)+ # scc succeeded; difft failed but ensure_tools() did not crash.+ assert result["scc"] is not None+ assert result["difft"] is None++def test_status_reports_every_registered_tool(monkeypatch):_set_platform(monkeypatch, sys_plat="darwin", machine="arm64")monkeypatch.setattr(binaries.shutil, "which", lambda _name: None)diff --git a/tests/test_tool_result_interceptors.py b/tests/test_tool_result_interceptors.pyindex 30e97df0e..f5d9d6f98 100644--- a/tests/test_tool_result_interceptors.py+++ b/tests/test_tool_result_interceptors.py@@ -9,10 +9,13 @@ import pytestfrom headroom.proxy.interceptors import (INTERCEPTORS,ToolResultInterceptor,+ ToolResultInterceptorTransform,apply_to_messages,+ interceptor_failure_counts,register,)from headroom.proxy.interceptors.astgrep import AstGrepReadOutline+from headroom.proxy.interceptors.base import reset_interceptor_failure_countsfrom headroom.tokenizer import Tokenizer@@ -398,3 +401,240 @@ def test_openai_format_tool_result_is_rewritten(tokenizer):assert len(result.spans) == 1new_content = result.messages[1]["content"]assert "outlined by ast-grep" in new_content+++# -------- Failure isolation & safety guarantees -------------------------- #+++def test_failing_interceptor_does_not_crash_request(tokenizer):+ """If transform() raises, the request still succeeds unchanged."""+ reset_interceptor_failure_counts()++ class BoomInterceptor:+ name = "boom"++ def matches(self, tool_name, tool_input, tool_output):+ return tool_name == "Read"++ def transform(self, tool_name, tool_input, tool_output):+ raise RuntimeError("simulated interceptor bug")++ register(BoomInterceptor())+ try:+ messages = [+ {+ "role": "assistant",+ "content": [+ {+ "type": "tool_use",+ "id": "b",+ "name": "Read",+ "input": {"file_path": "/repo/payments.py"},+ }+ ],+ },+ {+ "role": "user",+ "content": [{"type": "tool_result", "tool_use_id": "b", "content": _PY_FIXTURE}],+ },+ ]+ result = apply_to_messages(messages, tokenizer)+ # No span recorded for boom; request survives.+ assert not any(s.tool == "boom" for s in result.spans)+ # The failure counter incremented.+ assert interceptor_failure_counts().get("boom") == 1+ finally:+ INTERCEPTORS[:] = [i for i in INTERCEPTORS if i.name != "boom"]+++def test_failing_key_skips_interceptor_entirely(tokenizer):+ """Broken progressive_disclosure_key() must skip, not fire without a key."""+ reset_interceptor_failure_counts()+ fire_count = {"n": 0}++ class BadKey:+ name = "bad-key"++ def matches(self, tool_name, tool_input, tool_output):+ return tool_name == "Read"++ def transform(self, tool_name, tool_input, tool_output):+ fire_count["n"] += 1+ return "X" # reduces tokens++ def progressive_disclosure_key(self, tool_name, tool_input):+ raise RuntimeError("cannot compute key")++ register(BadKey())+ try:+ messages = [+ {+ "role": "assistant",+ "content": [+ {+ "type": "tool_use",+ "id": "k",+ "name": "Read",+ "input": {"file_path": "/repo/payments.py"},+ }+ ],+ },+ {+ "role": "user",+ "content": [{"type": "tool_result", "tool_use_id": "k", "content": _PY_FIXTURE}],+ },+ ]+ apply_to_messages(messages, tokenizer)+ assert fire_count["n"] == 0 # transform never ran+ assert interceptor_failure_counts().get("bad-key") == 1+ finally:+ INTERCEPTORS[:] = [i for i in INTERCEPTORS if i.name != "bad-key"]+++def test_refuses_to_enlarge(tokenizer):+ """If rewrite has MORE tokens than original, pass through unchanged.++ Uses a non-code tool path so only the Inflater runs (ast-grep passes+ through on non-Read tools).+ """+ original_content = "some data " * 200++ class Inflater:+ name = "inflater"++ def matches(self, tool_name, tool_input, tool_output):+ return tool_name == "FetchPage"++ def transform(self, tool_name, tool_input, tool_output):+ return tool_output + (" padding" * 200)++ register(Inflater())+ try:+ messages = [+ {+ "role": "assistant",+ "content": [+ {+ "type": "tool_use",+ "id": "i",+ "name": "FetchPage",+ "input": {"url": "https://example.com"},+ }+ ],+ },+ {+ "role": "user",+ "content": [+ {"type": "tool_result", "tool_use_id": "i", "content": original_content}+ ],+ },+ ]+ result = apply_to_messages(messages, tokenizer)+ assert not any(s.tool == "inflater" for s in result.spans)+ # Original content preserved.+ assert result.messages[1]["content"][0]["content"] == original_content+ finally:+ INTERCEPTORS[:] = [i for i in INTERCEPTORS if i.name != "inflater"]+++def test_orphaned_tool_result_does_not_crash(tokenizer):+ """A tool_result with no matching tool_use still runs safely (no tool_name)."""+ messages = [+ # No tool_use block — the model's prior turn is missing.+ {+ "role": "user",+ "content": [+ {"type": "tool_result", "tool_use_id": "orphan-id", "content": _PY_FIXTURE}+ ],+ },+ ]+ result = apply_to_messages(messages, tokenizer)+ # ast-grep.matches() returns False when tool_name is None, so no span.+ assert result.spans == []+ # The orphan message is preserved.+ assert result.messages[0]["content"][0]["content"] == _PY_FIXTURE+++# -------- Transform adapter tests ---------------------------------------- #+++def test_transform_adapter_applies_interceptors(tokenizer):+ """ToolResultInterceptorTransform.apply() runs interceptors + records tokens."""+ transform = ToolResultInterceptorTransform()+ messages = [+ {+ "role": "assistant",+ "content": [+ {+ "type": "tool_use",+ "id": "a",+ "name": "Read",+ "input": {"file_path": "/repo/payments.py"},+ }+ ],+ },+ {+ "role": "user",+ "content": [{"type": "tool_result", "tool_use_id": "a", "content": _PY_FIXTURE}],+ },+ ]+ result = transform.apply(messages, tokenizer)+ assert result.tokens_after < result.tokens_before+ assert "interceptor:ast-grep" in result.transforms_applied+++def test_transform_adapter_respects_frozen_message_count(tokenizer):+ """Messages in the frozen prefix must be untouched to preserve prefix caches."""+ transform = ToolResultInterceptorTransform()+ messages = [+ # Frozen prefix (first tool_result) — MUST pass through unchanged.+ {+ "role": "assistant",+ "content": [+ {+ "type": "tool_use",+ "id": "t1",+ "name": "Read",+ "input": {"file_path": "/repo/a.py"},+ }+ ],+ },+ {+ "role": "user",+ "content": [{"type": "tool_result", "tool_use_id": "t1", "content": _PY_FIXTURE}],+ },+ # Mutable tail (second Read of a different file) — free to outline.+ {+ "role": "assistant",+ "content": [+ {+ "type": "tool_use",+ "id": "t2",+ "name": "Read",+ "input": {"file_path": "/repo/b.py"},+ }+ ],+ },+ {+ "role": "user",+ "content": [{"type": "tool_result", "tool_use_id": "t2", "content": _PY_FIXTURE}],+ },+ ]+ result = transform.apply(messages, tokenizer, frozen_message_count=2)+ # Frozen prefix identity preserved (exact same list refs).+ assert result.messages[0] is messages[0]+ assert result.messages[1] is messages[1]+ # Tail got outlined.+ assert "outlined by ast-grep" in result.messages[3]["content"][0]["content"]+++def test_transform_adapter_tokens_before_is_baseline_not_reconstruction(tokenizer):+ """tokens_before must reflect the real original messages, not back-calc."""+ transform = ToolResultInterceptorTransform()+ messages = [+ {"role": "user", "content": [{"type": "text", "text": "plain non-tool message"}]},+ ]+ result = transform.apply(messages, tokenizer)+ # No spans, no change.+ assert result.tokens_before == result.tokens_after+ assert result.transforms_applied == []