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: preserve anthropic passthrough tool order (#1427)
Vinay Guptaa9322477e33e
diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.pyindex a01c9a5a1..e10d1b171 100644--- a/headroom/proxy/handlers/anthropic.py+++ b/headroom/proxy/handlers/anthropic.py@@ -149,6 +149,18 @@ class AnthropicHandlerMixin:return toolsreturn sorted(tools, key=cls._tool_sort_key)+ @classmethod+ def _tools_for_forwarding(+ cls,+ tools: list[dict[str, Any]] | None,+ *,+ preserve_order: bool,+ ) -> list[dict[str, Any]] | None:+ """Return upstream tools, preserving client order for passthrough requests."""+ if preserve_order:+ return tools+ return cls._sort_tools_deterministically(tools)+@staticmethoddef _compress_latest_user_turn_images_cache_safe(messages: list[dict[str, Any]],@@ -663,6 +675,7 @@ class AnthropicHandlerMixin:request.headers.get("x-headroom-bypass", "").lower() == "true"or request.headers.get("x-headroom-mode", "").lower() == "passthrough")+ preserve_tool_order = _bypass or not self.config.optimizeif _bypass:logger.info(f"[{request_id}] Bypass: skipping compression (header)")@@ -1843,9 +1856,12 @@ class AnthropicHandlerMixin:# Update bodybody["messages"] = optimized_messagesif tools or _original_tools is not None:- sorted_tools = self._sort_tools_deterministically(tools)- if sorted_tools != tools:- tools = sorted_tools+ forwarded_tools = self._tools_for_forwarding(+ tools,+ preserve_order=preserve_tool_order,+ )+ if forwarded_tools != tools:+ tools = forwarded_toolsif tools != _original_tools:body["tools"] = tools@@ -1865,11 +1881,10 @@ class AnthropicHandlerMixin:optimized_messages = presend_event.messagesbody["messages"] = optimized_messagesif presend_event.tools is not None:- sorted_tools = self._sort_tools_deterministically(presend_event.tools)- if sorted_tools != presend_event.tools:- tools = sorted_tools- else:- tools = presend_event.tools+ tools = self._tools_for_forwarding(+ presend_event.tools,+ preserve_order=preserve_tool_order,+ )if tools or body.get("tools") is not None:if tools != body.get("tools"):body["tools"] = tools@@ -2897,10 +2912,6 @@ class AnthropicHandlerMixin:params = batch_req.get("params", {})canonical_params = dict(params)original_tools = canonical_params.get("tools")- if original_tools is not None:- sorted_tools = self._sort_tools_deterministically(original_tools)- if sorted_tools != original_tools:- canonical_params["tools"] = sorted_toolsmessages = params.get("messages", [])original_messages = copy.deepcopy(messages)model = params.get("model", "unknown")@@ -2915,6 +2926,11 @@ class AnthropicHandlerMixin:)continue+ if original_tools is not None:+ sorted_tools = self._sort_tools_deterministically(original_tools)+ if sorted_tools != original_tools:+ canonical_params["tools"] = sorted_tools+# Apply optimizationoriginal_tokens = 0 # Initialize before try to prevent UnboundLocalErrortry:diff --git a/tests/test_anthropic_stage_timings.py b/tests/test_anthropic_stage_timings.pyindex 5a4ea86ef..cd4177310 100644--- a/tests/test_anthropic_stage_timings.py+++ b/tests/test_anthropic_stage_timings.py@@ -245,6 +245,42 @@ def test_anthropic_http_happy_path_emits_stage_timings(stage_log_capture):assert "total_pre_upstream" in emitted+def test_anthropic_no_optimize_preserves_client_tool_order():+ tools = [+ {+ "name": "Read",+ "description": "Read a file",+ "input_schema": {"type": "object", "properties": {}},+ },+ {+ "name": "Bash",+ "description": "Run a shell command",+ "input_schema": {"type": "object", "properties": {}},+ },+ ]+ request = _build_request(+ {+ "model": "claude-3-5-sonnet-latest",+ "messages": [{"role": "user", "content": "use a tool"}],+ "tools": tools,+ },+ {"authorization": "Bearer sk-ant-api-test"},+ )+ handler = _DummyAnthropicHandler()++ import headroom.tokenizers as _tk++ orig_get = _tk.get_tokenizer+ _tk.get_tokenizer = lambda model: _DummyTokenizer()+ try:+ anyio.run(handler.handle_anthropic_messages, request)+ finally:+ _tk.get_tokenizer = orig_get++ _, _, _, forwarded_body = handler.captured+ assert [tool["name"] for tool in forwarded_body["tools"]] == ["Read", "Bash"]++def test_anthropic_http_invalid_body_still_emits_stage_timings(stage_log_capture):async def receive():# Invalid JSON — produces ``ValueError`` from ``_read_request_json``.diff --git a/tests/test_proxy_anthropic_cache_stability.py b/tests/test_proxy_anthropic_cache_stability.pyindex fb5d92187..086ba83ad 100644--- a/tests/test_proxy_anthropic_cache_stability.py+++ b/tests/test_proxy_anthropic_cache_stability.py@@ -86,10 +86,32 @@ def _make_proxy_client() -> TestClient:return TestClient(app)-def test_anthropic_tools_sorted_deterministically_before_forward() -> None:+ ("optimize", "expected_names"),+ [+ (False, ["zeta", "alpha", "mu"]),+ (True, ["alpha", "mu", "zeta"]),+ ],+)+def test_anthropic_tools_forwarding_order_matches_optimization_mode(+ optimize: bool,+ expected_names: list[str],+) -> None:captured = {}with _make_proxy_client() as client:proxy = client.app.state.proxy+ proxy.config.optimize = optimize+ proxy.config.mode = "token"++ if optimize:+ proxy.anthropic_pipeline.apply = lambda **kwargs: SimpleNamespace(+ messages=kwargs["messages"],+ transforms_applied=[],+ timing={},+ tokens_before=100,+ tokens_after=100,+ waste_signals=None,+ )async def _fake_retry(method, url, headers, body, stream=False, **kwargs): # noqa: ANN001captured["body"] = body@@ -128,7 +150,7 @@ def test_anthropic_tools_sorted_deterministically_before_forward() -> None:assert response.status_code == 200sent_tools = captured["body"]["tools"]- assert [t["name"] for t in sent_tools] == ["alpha", "mu", "zeta"]+ assert [t["name"] for t in sent_tools] == expected_namesdef test_image_compression_only_applies_to_latest_non_frozen_user_turn() -> None:@@ -186,10 +208,20 @@ def test_image_compression_does_not_touch_previous_turns_if_last_message_not_useassert result[0]["content"][0]["source"]["data"] == "OLD_IMAGE_BYTES"-def test_anthropic_batch_tools_sorted_deterministically_before_forward() -> None:+ ("optimize", "expected_names"),+ [+ (False, ["zeta", "alpha", "mu"]),+ (True, ["alpha", "mu", "zeta"]),+ ],+)+def test_anthropic_batch_tools_forwarding_order_matches_optimization_mode(+ optimize: bool,+ expected_names: list[str],+) -> None:captured = {}config = ProxyConfig(- optimize=False,+ optimize=optimize,cache_enabled=False,rate_limit_enabled=False,cost_tracking_enabled=False,@@ -203,6 +235,17 @@ def test_anthropic_batch_tools_sorted_deterministically_before_forward() -> Nonewith TestClient(app) as client:proxy = client.app.state.proxy+ proxy.config.mode = "token"++ if optimize:+ proxy.anthropic_pipeline.apply = lambda **kwargs: SimpleNamespace(+ messages=kwargs["messages"],+ transforms_applied=[],+ timing={},+ tokens_before=100,+ tokens_after=100,+ waste_signals=None,+ )async def _fake_retry(method, url, headers, body, stream=False, **kwargs): # noqa: ANN001captured["body"] = body@@ -259,7 +302,7 @@ def test_anthropic_batch_tools_sorted_deterministically_before_forward() -> Noneassert response.status_code == 200sent_tools = captured["body"]["requests"][0]["params"]["tools"]- assert [t["name"] for t in sent_tools] == ["alpha", "mu", "zeta"]+ assert [t["name"] for t in sent_tools] == expected_namesdef test_append_context_targets_latest_non_frozen_user_turn() -> None:diff --git a/tests/test_proxy_byte_faithful_forwarding.py b/tests/test_proxy_byte_faithful_forwarding.pyindex d8c0eb87e..027956c5b 100644--- a/tests/test_proxy_byte_faithful_forwarding.py+++ b/tests/test_proxy_byte_faithful_forwarding.py@@ -308,10 +308,10 @@ class _SortedEmptyToolsPreSendExtension:return None-def _make_no_optimize_app() -> tuple[TestClient, _CapturingTransport]:- """Boot a proxy with all transforms disabled and a capturing transport."""+def _make_anthropic_app(*, optimize: bool) -> tuple[TestClient, _CapturingTransport]:+ """Boot an Anthropic proxy with a capturing transport."""config = ProxyConfig(- optimize=False,+ optimize=optimize,cache_enabled=False,rate_limit_enabled=False,cost_tracking_enabled=False,@@ -335,6 +335,11 @@ def _make_no_optimize_app() -> tuple[TestClient, _CapturingTransport]:return TestClient(app), transport+def _make_no_optimize_app() -> tuple[TestClient, _CapturingTransport]:+ """Boot a proxy with all transforms disabled and a capturing transport."""+ return _make_anthropic_app(optimize=False)++def test_passthrough_no_mutation_byte_equal_sha256() -> None:"""No transform → upstream SHA-256 equals client-sent SHA-256."""client, transport = _make_no_optimize_app()@@ -448,7 +453,7 @@ def test_anthropic_tools_canonical_order_preserves_byte_faithful_request() -> No)-def test_anthropic_tools_unsorted_reordered_and_canonicalized() -> None:+def test_anthropic_tools_unsorted_order_preserves_byte_faithful_request() -> None:client, transport = _make_no_optimize_app()inbound_dict = {"model": "claude-sonnet-4-6",@@ -459,6 +464,49 @@ def test_anthropic_tools_unsorted_reordered_and_canonicalized() -> None:{"name": "alpha"},],}+ inbound_bytes = serialize_body_canonical(inbound_dict)++ response = client.post(+ "/v1/messages",+ headers={+ "x-api-key": "test-key",+ "anthropic-version": "2023-06-01",+ "content-type": "application/json",+ },+ content=inbound_bytes,+ )+ assert response.status_code == 200, response.text+ upstream = transport.captured_body or b""+ assert upstream == inbound_bytes+ forwarded = json.loads(upstream.decode("utf-8"))+ assert [tool["name"] for tool in forwarded["tools"]] == ["zeta", "alpha"]+++def test_anthropic_tools_unsorted_reordered_and_canonicalized_when_optimized() -> None:+ client, transport = _make_anthropic_app(optimize=True)+ proxy = client.app.state.proxy+ proxy.config.mode = "token"++ def _fake_apply(**kwargs):+ return SimpleNamespace(+ messages=kwargs["messages"],+ transforms_applied=[],+ timing={},+ tokens_before=100,+ tokens_after=100,+ waste_signals=None,+ )++ proxy.anthropic_pipeline.apply = _fake_apply+ inbound_dict = {+ "model": "claude-sonnet-4-6",+ "max_tokens": 64,+ "messages": [{"role": "user", "content": "plan test"}],+ "tools": [+ {"name": "zeta", "description": "later"},+ {"name": "alpha"},+ ],+ }expected_dict = {**inbound_dict,"tools": [diff --git a/tests/test_proxy_handler_helpers.py b/tests/test_proxy_handler_helpers.pyindex daa0c42f7..fe2b48f6b 100644--- a/tests/test_proxy_handler_helpers.py+++ b/tests/test_proxy_handler_helpers.py@@ -570,6 +570,15 @@ def test_anthropic_tool_sort_and_context_append_helpers() -> None:"tool",]assert AnthropicHandlerMixin._sort_tools_deterministically(None) is None+ assert AnthropicHandlerMixin._tools_for_forwarding(tools, preserve_order=True) == tools+ assert [+ AnthropicHandlerMixin._tool_sort_key(tool)[0]+ for tool in AnthropicHandlerMixin._tools_for_forwarding(tools, preserve_order=False) or []+ ] == [+ "alpha",+ "beta",+ "tool",+ ]assert (AnthropicHandlerMixin._append_context_to_latest_non_frozen_user_turn([], "ctx", frozen_message_count=0