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(proxy): snapshot the original messages when a turn hook can edit them (#4241)
Tejas Chopradf11f2749862
diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.pyindex 3344e9fef..3de6f8295 100644--- a/headroom/proxy/handlers/anthropic.py+++ b/headroom/proxy/handlers/anthropic.py@@ -1248,9 +1248,10 @@ class AnthropicHandlerMixin:pipeline_path = request.url.path if upstream_base_url else "/v1/messages"pipeline_stream = bool(body.get("stream", False) or force_stream)# O1 (2026-09-27 perf audit): the snapshot of the original- # conversation aliases the live list unless hooks or pipeline- # extensions are configured - those can mutate `messages` in place- # (pre_compress receives the live list), so then the snapshot is an+ # conversation aliases the live list unless hooks, pipeline+ # extensions or turn hooks are configured - those can mutate+ # `messages` in place (pre_compress receives the live list, skill+ # search folds text in place), so then the snapshot is an# independently owned copy (snapshot_original_messages). The# deep_copy stage is always measured so the timing summary keeps# its key.@@ -5779,7 +5780,7 @@ class AnthropicHandlerMixin:pipeline_timing: dict[str, float] = {}# O1 (2026-09-27 perf audit): the per-request snapshot aliases unless- # hooks or extensions are configured (see the main handler).+ # hooks, extensions or turn hooks are configured (see the main handler).from headroom.proxy.helpers import snapshot_original_messagesfrom headroom.transforms.cold_prefix import anthropic_cache_ttl_secondsdiff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.pyindex 80f0657a4..f649553d5 100644--- a/headroom/proxy/handlers/openai.py+++ b/headroom/proxy/handlers/openai.py@@ -3135,8 +3135,8 @@ class OpenAIHandlerMixin:model = body.get("model", "unknown")messages = body.get("messages", [])# O1 (2026-09-27 perf audit): the snapshot of the original- # conversation aliases the live list unless hooks or pipeline- # extensions are configured; those can mutate `messages` in place+ # conversation aliases the live list unless hooks, pipeline extensions+ # or turn hooks are configured; those can mutate `messages` in place# (pre_compress receives the live list), so then it is an# independently owned copy (see snapshot_original_messages).from headroom.proxy.helpers import snapshot_original_messagesdiff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.pyindex e28c786ec..e3675ca3a 100644--- a/headroom/proxy/helpers.py+++ b/headroom/proxy/helpers.py@@ -112,6 +112,7 @@ from headroom.proxy.tool_injection_logging import ()from headroom.proxy.tool_injection_tracker import SessionToolTracker as _SessionToolTrackerfrom headroom.proxy.tool_name_policy import extract_tool_name+from headroom.proxy.turn_hooks import registered_turn_hooksif TYPE_CHECKING:import httpx@@ -4793,11 +4794,12 @@ def snapshot_original_messages(Aliasing the live list is safe only while nothing between ingress and thepipeline's own deepcopy can mutate it in place. A configured- ``config.hooks`` (``pre_compress`` and friends receive the live list) or an- enabled pipeline extension can, so in that case the snapshot is an- independently owned deep copy; with neither configured the alias is kept- and costs nothing.+ ``config.hooks`` (``pre_compress`` and friends receive the live list), an+ enabled pipeline extension or a registered turn hook (skill search folds+ message text in place) can, so in that case the snapshot is an+ independently owned deep copy; with none of them the alias is kept and+ costs nothing."""- if hooks is not None or bool(getattr(extensions, "enabled", False)):+ if hooks is not None or bool(getattr(extensions, "enabled", False)) or registered_turn_hooks():return copy.deepcopy(messages)return messagesdiff --git a/tests/test_original_snapshot_in_place_hook.py b/tests/test_original_snapshot_in_place_hook.pyindex 3b75a87e2..b08c0a321 100644--- a/tests/test_original_snapshot_in_place_hook.py+++ b/tests/test_original_snapshot_in_place_hook.py@@ -4,8 +4,10 @@ O1 aliases ``original_client_messages`` to the live ``messages`` list to skip adeepcopy per request. That is only safe while nothing mutates the list beforethe pipeline's own copy; ``config.hooks.pre_compress`` receives the live list,so a hook that edits it in place (and returns the same list) used to rewrite the-recorded original too. With hooks or extensions configured the snapshot is an-independently owned copy; with neither, the alias stays (no env switch).+recorded original too. Registered turn hooks (skill search) fold message text+in place the same way. With hooks, extensions or turn hooks configured the+snapshot is an independently owned copy; with none, the alias stays (no env+switch).Observed at the handlers' own consumers: ``compute_session_id`` derives thesession from the ORIGINAL client messages after the hook has run, and the@@ -27,8 +29,18 @@ from fastapi.testclient import TestClient # noqa: E402from headroom.hooks import CompressionHooks # noqa: E402from headroom.proxy.helpers import snapshot_original_messages # noqa: E402from headroom.proxy.server import ProxyConfig, create_app # noqa: E402+from headroom.proxy.turn_hooks import clear_turn_hooks, register_turn_hook # noqa: E402ORIGINAL = "the original user text"++[email protected](autouse=True)+def _clean_turn_hooks():+ clear_turn_hooks()+ yield+ clear_turn_hooks()++HOOKED = "HOOKED IN PLACE"@@ -175,3 +187,66 @@ def test_the_snapshot_aliases_only_when_nothing_can_mutate() -> None:for kw in ({"hooks": _InPlaceHooks()}, {"extensions": _Ext()}):snap = snapshot_original_messages(msgs, **kw)assert snap == msgs and snap is not msgs and snap[0] is not msgs[0]+++def test_the_snapshot_is_a_copy_while_a_turn_hook_is_registered() -> None:+ msgs = [{"role": "user", "content": ORIGINAL}]+ register_turn_hook(_InPlaceTurnHook())+ snap = snapshot_original_messages(msgs)+ assert snap == msgs and snap is not msgs and snap[0] is not msgs[0]+++class _InPlaceTurnHook:+ """Shaped like skill search: rewrites a message's text in place, adds a tool."""++ name = "in_place_fold"+ stream_safe = False++ def on_request(self, ctx) -> None:+ for m in ctx.messages:+ if m.get("role") == "user":+ m["content"] = "short"+ ctx.tools = [+ *(ctx.tools or []),+ {"name": "search", "description": "find", "input_schema": {"type": "object"}},+ ]+++def test_anthropic_headline_counts_a_turn_hook_fold_made_in_place() -> None:+ register_turn_hook(_InPlaceTurnHook())+ with TestClient(create_app(_config(hooks=None))) as client:+ proxy = client.app.state.proxy++ async def _fake_retry(method, url, headers, body, stream=False, **kwargs): # noqa: ANN001+ return httpx.Response(+ 200,+ content=json.dumps(+ {+ "id": "msg_1",+ "type": "message",+ "role": "assistant",+ "model": "claude-sonnet-4-5",+ "content": [{"type": "text", "text": "ok"}],+ "stop_reason": "end_turn",+ "usage": {"input_tokens": 5, "output_tokens": 1},+ }+ ).encode(),+ headers={"content-type": "application/json"},+ )++ proxy._retry_request = _fake_retry+ r = client.post(+ "/v1/messages",+ headers={"x-api-key": "sk-ant-test", "anthropic-version": "2023-06-01"},+ json={+ "model": "claude-sonnet-4-5",+ "max_tokens": 16,+ "messages": [{"role": "user", "content": ORIGINAL + " word" * 400}],+ },+ )+ assert r.status_code == 200, r.text++ before = int(r.headers["x-headroom-tokens-before"])+ after = int(r.headers["x-headroom-tokens-after"])+ assert before > after+ assert int(r.headers["x-headroom-tokens-saved"]) == before - after > 0