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
feat(hooks): add protect_messages, a hard per-message compression veto (#3772)
Tejas Choprad17ac6a174d9
diff --git a/headroom/compress.py b/headroom/compress.pyindex 2d1a786b6..c40e0993c 100644--- a/headroom/compress.py+++ b/headroom/compress.py@@ -230,12 +230,17 @@ def compress(try:# Compute biases from hooks if providedbiases = None+ # Hard per-message veto. Separate from ``biases`` because a bias is a+ # soft multiplier that several strategies clamp or ignore, so it cannot+ # express "leave this one alone".+ protect = Noneif hooks:- from headroom.hooks import CompressContext+ from headroom.hooks import CompressContext, collect_protectedctx = CompressContext(model=model)messages = hooks.pre_compress(messages, ctx)biases = hooks.compute_biases(messages, ctx)+ protect = collect_protected(hooks, messages, ctx)received_event = pipeline_extensions.emit(PipelineStage.INPUT_RECEIVED,@@ -257,6 +262,7 @@ def compress(model_limit=model_limit,context=context,biases=biases,+ protect=protect,# Pass CompressConfig options through to transformscompress_user_messages=cfg.compress_user_messages,compress_system_messages=cfg.compress_system_messages,diff --git a/headroom/hooks.py b/headroom/hooks.pyindex 4f3cf82ce..3ae985e85 100644--- a/headroom/hooks.py+++ b/headroom/hooks.py@@ -1,10 +1,11 @@"""Compression hooks and pipeline lifecycle events.-Three hooks at well-defined pipeline stages:+Four hooks at well-defined pipeline stages:1. pre_compress: modify messages before compression (dedup, filter, inject)2. compute_biases: set per-message compression aggressiveness (position-aware, phase-aware)-3. post_compress: observe results after compression (learning, analytics, logging)+3. protect_messages: veto compression of specific messages outright+4. post_compress: observe results after compression (learning, analytics, logging)The canonical pipeline also emits lifecycle events through ``on_pipeline_event``.That gives extensions one stable contract across SDK, ``compress()``, and proxy@@ -39,7 +40,7 @@ from .pipeline import PipelineEvent@dataclassclass CompressContext:- """Context passed to pre_compress and compute_biases hooks.+ """Context passed to the pre_compress, compute_biases and protect_messages hooks.Provides enough information for hooks to make decisions withoutneeding to understand the proxy's internals.@@ -128,6 +129,32 @@ class CompressionHooks:"""return {}+ def protect_messages(+ self,+ messages: list[dict[str, Any]],+ ctx: CompressContext,+ ) -> set[int]:+ """Return message indices that must not be compressed at all.++ ``compute_biases`` is a *soft* lever: a multiplier on how aggressively+ a compressor prunes. Several strategies clamp it against their own+ floors or ignore it entirely, so no bias — however large — reliably+ means "leave this one alone". A hook that has concluded a specific+ message must survive verbatim needs to say so directly, and this is how.++ The router honours these before any routing decision, so the message is+ passed through untouched whatever its content type or role. Use+ sparingly: a protected message is context the compressor cannot reclaim.++ Args:+ messages: The full message list.+ ctx: Compression context.++ Returns:+ Set of message indices to pass through verbatim. Empty = no vetoes.+ """+ return set()+def post_compress(self, event: CompressEvent) -> None:"""Called after compression completes. Observational only.@@ -149,3 +176,33 @@ class CompressionHooks:the three legacy compression-specific hooks."""return None+++def collect_protected(+ hooks: Any,+ messages: list[dict[str, Any]],+ ctx: CompressContext,+) -> set[int] | None:+ """Ask a hooks object for its per-message vetoes, tolerating older ones.++ ``hooks`` is duck-typed at every call site: nothing requires the object to+ be a :class:`CompressionHooks` subclass, and objects written before+ ``protect_messages`` existed will not have the attribute at all. Calling it+ blind would raise ``AttributeError`` inside the compression block, which the+ proxy catches as a compression failure — so adding this hook would silently+ stop compressing for those callers, turning an additive seam into a+ regression. A missing method means "no vetoes".++ Returns None when the hook cannot be asked, which the router treats the same+ as an empty set.+ """+ fn = getattr(hooks, "protect_messages", None)+ if fn is None:+ return None+ protected = fn(messages, ctx)+ if protected is None:+ return None+ # Normalise here rather than trusting the hook: ``hooks`` is duck-typed, so+ # a set is a convention, not a guarantee, and a list of indices is the+ # obvious thing for an implementer to return.+ return {int(i) for i in protected}diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.pyindex 0a3a4a6a5..33ce52171 100644--- a/headroom/proxy/handlers/anthropic.py+++ b/headroom/proxy/handlers/anthropic.py@@ -1739,6 +1739,16 @@ class AnthropicHandlerMixin:if self.config.hooks and _hook_ctx is not Noneelse None)+ # Hard per-message veto. Separate from ``biases`` because a+ # bias is a soft multiplier that several strategies clamp or+ # ignore, so it cannot express "leave this one alone".+ from headroom.hooks import collect_protected++ protect = (+ collect_protected(self.config.hooks, messages, _hook_ctx)+ if self.config.hooks and _hook_ctx is not None+ else None+ )# F2.1 c5/5: derive the per-request CompressionPolicy# from the auth_mode classified at request entry. The@@ -1807,6 +1817,7 @@ class AnthropicHandlerMixin:prefix_replay_guaranteed=True,idle_seconds=idle_seconds,biases=biases,+ protect=protect,request_id=request_id,compression_policy=compression_policy,cache_ttl_seconds=_cc_ttl,@@ -1853,6 +1864,7 @@ class AnthropicHandlerMixin:prefix_replay_guaranteed=True,idle_seconds=idle_seconds,biases=biases,+ protect=protect,request_id=request_id,compression_policy=compression_policy,cache_ttl_seconds=_cc_ttl,@@ -1905,6 +1917,7 @@ class AnthropicHandlerMixin:prefix_replay_guaranteed=True,idle_seconds=idle_seconds,biases=biases,+ protect=protect,request_id=request_id,compression_policy=compression_policy,cache_ttl_seconds=_cc_ttl,@@ -1948,6 +1961,7 @@ class AnthropicHandlerMixin:frozen_message_count=frozen_message_count,prefix_replay_guaranteed=True,biases=biases,+ protect=protect,request_id=request_id,compression_policy=compression_policy,cache_ttl_seconds=_cc_ttl,@@ -2010,6 +2024,7 @@ class AnthropicHandlerMixin:frozen_message_count=frozen_message_count,prefix_replay_guaranteed=True,biases=biases,+ protect=protect,request_id=request_id,compression_policy=compression_policy,**proxy_pipeline_kwargs(self.config),@@ -2082,6 +2097,7 @@ class AnthropicHandlerMixin:frozen_message_count=prefix_n,idle_seconds=idle_seconds,biases=biases,+ protect=protect,request_id=request_id,compression_policy=compression_policy,cache_ttl_seconds=_cc_ttl,diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.pyindex 85231d543..bdd29b82f 100644--- a/headroom/proxy/handlers/openai.py+++ b/headroom/proxy/handlers/openai.py@@ -3687,13 +3687,18 @@ class OpenAIHandlerMixin:# Hook: pre_compress_hook_biases = None+ # Hard per-message veto. Separate from ``_hook_biases`` because a bias is+ # a soft multiplier that several strategies clamp or ignore, so it cannot+ # express "leave this one alone".+ _hook_protect = Noneif self.config.hooks:- from headroom.hooks import CompressContext+ from headroom.hooks import CompressContext, collect_protected_hook_ctx = CompressContext(model=model, provider="openai")try:messages = self.config.hooks.pre_compress(messages, _hook_ctx)_hook_biases = self.config.hooks.compute_biases(messages, _hook_ctx)+ _hook_protect = collect_protected(self.config.hooks, messages, _hook_ctx)except Exception as e:logger.debug(f"[{request_id}] Hook error: {e}")@@ -3898,6 +3903,7 @@ class OpenAIHandlerMixin:),prefix_replay_guaranteed=True,biases=_hook_biases,+ protect=_hook_protect,compression_policy=compression_policy,cross_turn_dedup_recoverable=_dedup_pointers_recoverable,# Thread the savings-profile knobs (e.g.@@ -3940,6 +3946,7 @@ class OpenAIHandlerMixin:frozen_message_count=apply_frozen_count,prefix_replay_guaranteed=True,biases=_hook_biases,+ protect=_hook_protect,compression_policy=compression_policy,cross_turn_dedup_recoverable=_dedup_pointers_recoverable,# Same savings-profile threading as the token-modediff --git a/headroom/transforms/content_router.py b/headroom/transforms/content_router.pyindex 41fcd749d..395035623 100644--- a/headroom/transforms/content_router.py+++ b/headroom/transforms/content_router.py@@ -5258,6 +5258,15 @@ class ContentRouter(Transform):tokens_before = sum(tokenizer.count_text(str(m.get("content", ""))) for m in messages)context = kwargs.get("context", "")hook_biases: dict[int, float] = kwargs.get("biases") or {}+ # Per-message veto from a compression hook (``CompressionHooks.+ # protect_messages``). Distinct from ``biases``, which is a soft+ # multiplier on how aggressively a compressor prunes: several+ # strategies clamp or ignore it, so a bias — however large — cannot+ # express "leave this one alone". This can. Empty unless a hook is+ # installed, so the default path is unchanged.+ hook_protect: set[int] = {+ int(i) for i in (kwargs.get("protect") or ()) if isinstance(i, (int, bool))+ }# Build tool name map for exclusion checkingtool_name_map = self._build_tool_name_map(messages)@@ -5557,6 +5566,14 @@ class ContentRouter(Transform):content = message.get("content", "")bias = 1.0 # Default bias, may be overridden for tool messages+ # Hook veto, checked before any routing decision so it covers both+ # the content-block path and the string path below.+ if i in hook_protect:+ result_slots[i] = message+ transforms_applied.append("router:protected:hook")+ route_counts["hook_protected"] = route_counts.get("hook_protected", 0) + 1+ continue+messages_from_end = num_messages - i# The caller's own words stay verbatim on a replaying path even# when user messages are compressible for their tool observations:diff --git a/tests/test_hook_protect_messages.py b/tests/test_hook_protect_messages.pynew file mode 100644index 000000000..ff5b5255a--- /dev/null+++ b/tests/test_hook_protect_messages.py@@ -0,0 +1,180 @@+"""``CompressionHooks.protect_messages`` — the hard per-message veto.++``compute_biases`` is a soft multiplier, and several strategies clamp it+against their own floors or ignore it outright: measured against the log and+JSON routes, bias 0.1 and bias 1000 produce byte-identical output. A hook that+has concluded a specific message must survive verbatim therefore cannot say so+with a bias, and this seam is how it says so instead.+"""++from __future__ import annotations++import json++import pytest++from headroom import compress+from headroom.hooks import CompressionHooks+from headroom.tokenizers import get_tokenizer+from headroom.transforms.content_router import ContentRouter++MODEL = "gpt-4o"+LOG = "\n".join(+ f"2026-09-2{i % 9} 10:{i % 60:02d}:00 INFO worker={i} processed batch {i} in {i * 3}ms"+ for i in range(300)+)+BLOB = json.dumps([{"id": i, "name": f"item-{i}", "size": i * 7} for i in range(200)])+++def openai_messages(body: str) -> list[dict]:+ return [+ {"role": "user", "content": "look"},+ {+ "role": "assistant",+ "content": None,+ "tool_calls": [+ {+ "id": "t1",+ "type": "function",+ "function": {"name": "run_terminal_cmd", "arguments": '{"command": "cat x"}'},+ }+ ],+ },+ {"role": "tool", "tool_call_id": "t1", "content": body},+ {"role": "user", "content": "now summarise"},+ ]+++def anthropic_messages(body: str) -> list[dict]:+ return [+ {"role": "user", "content": "look"},+ {+ "role": "assistant",+ "content": [+ {"type": "tool_use", "id": "t1", "name": "Bash", "input": {"command": "cat x"}}+ ],+ },+ {+ "role": "user",+ "content": [{"type": "tool_result", "tool_use_id": "t1", "content": body}],+ },+ {"role": "user", "content": "now summarise"},+ ]+++def _text_at(messages: list[dict], index: int) -> str:+ content = messages[index]["content"]+ if isinstance(content, str):+ return content+ return "".join(+ block.get("content", "") if isinstance(block.get("content"), str) else ""+ for block in content+ )+++ "build", [openai_messages, anthropic_messages], ids=["openai", "anthropic"]+)[email protected]("body", [LOG, BLOB], ids=["log", "json"])+def test_a_protected_message_survives_verbatim(build, body) -> None:+ """Both content shapes, and routes that ignore bias entirely."""+ tokenizer = get_tokenizer(MODEL)++ compressed = ContentRouter().apply(build(body), tokenizer)+ assert _text_at(compressed.messages, 2) != body, "fixture must actually be compressible"++ protected = ContentRouter().apply(build(body), tokenizer, protect={2})+ assert _text_at(protected.messages, 2) == body+ assert "router:protected:hook" in protected.transforms_applied+++ "protect", [None, set(), {99}, frozenset()], ids=["none", "empty", "miss", "frozen"]+)+def test_the_seam_is_inert_unless_used(protect) -> None:+ """The default path must be byte-identical to not passing the kwarg."""+ tokenizer = get_tokenizer(MODEL)+ baseline = ContentRouter().apply(openai_messages(LOG), tokenizer)+ result = ContentRouter().apply(openai_messages(LOG), tokenizer, protect=protect)+ assert _text_at(result.messages, 2) == _text_at(baseline.messages, 2)+ assert "router:protected:hook" not in result.transforms_applied+++def test_protection_beats_every_bias() -> None:+ """The point of the seam: no bias can do this."""+ tokenizer = get_tokenizer(MODEL)+ for bias in (0.1, 1.0, 8.0, 1000.0):+ biased = ContentRouter().apply(openai_messages(LOG), tokenizer, biases={2: bias})+ assert _text_at(biased.messages, 2) != LOG+ protected = ContentRouter().apply(openai_messages(LOG), tokenizer, protect={2})+ assert _text_at(protected.messages, 2) == LOG+++def test_the_default_hook_protects_nothing() -> None:+ assert CompressionHooks().protect_messages(openai_messages(LOG), None) == set()+++def test_the_seam_is_reachable_from_the_sdk() -> None:+ """Wiring check: a hook installed through ``compress(hooks=...)`` reaches+ the router. Without this the seam exists and nobody can use it."""++ class Protecting(CompressionHooks):+ def protect_messages(self, messages, ctx):+ return {2}++ plain = compress(openai_messages(LOG), model=MODEL, hooks=CompressionHooks())+ protecting = compress(openai_messages(LOG), model=MODEL, hooks=Protecting())++ assert _text_at(plain.messages, 2) != LOG+ assert _text_at(protecting.messages, 2) == LOG+ assert protecting.tokens_after > plain.tokens_after+++def test_hooks_that_do_not_implement_it_still_work() -> None:+ """A subclass predating this method inherits the empty default."""++ class Legacy(CompressionHooks):+ def compute_biases(self, messages, ctx):+ return {2: 1.5}++ result = compress(openai_messages(LOG), model=MODEL, hooks=Legacy())+ assert result.tokens_after < result.tokens_before+++def test_a_hooks_object_that_is_not_a_subclass_still_compresses() -> None:+ """The real compatibility case: ``hooks`` is duck-typed, not type-checked.++ Nothing requires the object passed as ``hooks`` to subclass+ CompressionHooks, so one written before ``protect_messages`` existed has no+ such attribute. Calling it blind raises AttributeError inside the+ compression block, which the proxy catches as a *compression failure* — so+ the request would silently stop being compressed. That would make this+ additive seam a regression for those callers.+ """++ class DuckTyped: # deliberately not a CompressionHooks subclass+ def pre_compress(self, messages, ctx):+ return messages++ def compute_biases(self, messages, ctx):+ return {}++ def post_compress(self, event):+ pass++ def on_pipeline_event(self, event):+ return None++ result = compress(openai_messages(LOG), model=MODEL, hooks=DuckTyped())+ assert result.tokens_after < result.tokens_before+++def test_collect_protected_reports_a_missing_method_as_no_vetoes() -> None:+ from headroom.hooks import CompressContext, collect_protected++ class Without:+ pass++ ctx = CompressContext(model=MODEL)+ assert collect_protected(Without(), [], ctx) is None+ assert collect_protected(CompressionHooks(), [], ctx) == set()