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): preserve byte-faithful Anthropic tool forwarding (#1222)
Rod Boev1f18d5980972
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex cd8af08c0..3f0632809 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -30,6 +30,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0* **proxy:** route Codex OAuth image generation and edit requests through the ChatGPT Codex image backend, while preserving OpenAI API-key image passthrough ([#1215](https://github.com/chopratejas/headroom/pull/1215)).* **proxy:** enable SSO credential resolution in the native Bedrock route via the `aws-config` `sso` feature flag, making the credential chain match what `docs/bedrock.md` already documented ([#999](https://github.com/chopratejas/headroom/pull/999)).* **proxy:** route native Bedrock `/model/{id}/converse` requests to the upstream Converse endpoint instead of the hard-coded `/invoke` action — the non-streaming handler now resolves the action from the inbound path, matching the streaming handler ([#999](https://github.com/chopratejas/headroom/pull/999)).+* **proxy:** preserve byte-faithful `/v1/messages` forwarding when Anthropic tool arrays are already canonical, and only canonicalize-and-mutate tool lists when sorting changes ordering ([#1042](https://github.com/chopratejas/headroom/issues/1042)).* **ccr:** make retrieval store TTL configurable with `HEADROOM_CCR_TTL_SECONDS`, expose the effective TTL in `/v1/retrieve/stats`, and distinguish expired retrievals from missing hashes.* **proxy:** add native Bedrock `/model/{id}/converse-stream` route and forward it through the existing streaming EventStream/SSE pipeline.* **wrap (codex):** fix `headroom wrap codex` producing a `config.toml` with duplicate top-level `model_provider` / `openai_base_url` keys (TOML-spec error) when the user had already configured their own provider. The injector now rewrites pre-existing top-level `model_provider` and `openai_base_url` lines in place — the previous value is kept in a `# was: …` trailing comment — instead of unconditionally prepending a duplicate, so `codex` can start against the proxy. The pre-wrap snapshot mechanism continues to byte-for-byte restore the original file on `headroom unwrap codex`.diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.pyindex e930e96bf..19ac622fa 100644--- a/headroom/proxy/handlers/anthropic.py+++ b/headroom/proxy/handlers/anthropic.py@@ -1671,8 +1671,11 @@ class AnthropicHandlerMixin:# Update bodybody["messages"] = optimized_messagesif tools or _original_tools is not None:- tools = self._sort_tools_deterministically(tools)- body["tools"] = tools+ sorted_tools = self._sort_tools_deterministically(tools)+ if sorted_tools != tools:+ tools = sorted_tools+ if tools != _original_tools:+ body["tools"] = toolspresend_event = self.pipeline_extensions.emit(PipelineStage.PRE_SEND,@@ -1690,8 +1693,14 @@ class AnthropicHandlerMixin:optimized_messages = presend_event.messagesbody["messages"] = optimized_messagesif presend_event.tools is not None:- tools = self._sort_tools_deterministically(presend_event.tools)- body["tools"] = tools+ sorted_tools = self._sort_tools_deterministically(presend_event.tools)+ if sorted_tools != presend_event.tools:+ tools = sorted_tools+ else:+ tools = presend_event.tools+ if tools or body.get("tools") is not None:+ if tools != body.get("tools"):+ body["tools"] = toolsif presend_event.headers is not None:headers = presend_event.headersif presend_event.messages is not previous_presend_messages:@@ -2646,9 +2655,11 @@ class AnthropicHandlerMixin:custom_id = batch_req.get("custom_id", "")params = batch_req.get("params", {})canonical_params = dict(params)- canonical_tools = canonical_params.get("tools")- if canonical_tools is not None:- canonical_params["tools"] = self._sort_tools_deterministically(canonical_tools)+ 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")@@ -2725,7 +2736,12 @@ class AnthropicHandlerMixin:# Create compressed batch requestcompressed_params = {**params, "messages": optimized_messages}if tools is not None:- compressed_params["tools"] = self._sort_tools_deterministically(tools)+ sorted_tools = self._sort_tools_deterministically(tools)+ if sorted_tools != tools:+ tools = sorted_tools+ if tools or original_tools is not None:+ if tools != original_tools:+ compressed_params["tools"] = toolscompressed_requests.append({"custom_id": custom_id,diff --git a/tests/test_issue_728_empty_tools_injection.py b/tests/test_issue_728_empty_tools_injection.pyindex fe08a9ed1..93b2d7f5f 100644--- a/tests/test_issue_728_empty_tools_injection.py+++ b/tests/test_issue_728_empty_tools_injection.py@@ -16,6 +16,7 @@ from __future__ import annotationsimport pytestfrom headroom.ccr.tool_injection import CCR_TOOL_NAME+from headroom.proxy.handlers.anthropic import AnthropicHandlerMixinfrom headroom.proxy.helpers import (_reset_session_ccr_tracker_for_test,apply_session_sticky_ccr_tool,@@ -39,6 +40,29 @@ def _should_set_body_tools(tools: list | None, original_tools: list | None) -> breturn bool(tools or original_tools is not None)+def _sort_tools(tools: list | None) -> list | None:+ return AnthropicHandlerMixin._sort_tools_deterministically(tools)+++def _should_set_body_tools_after_sort(tools: list | None, original_tools: list | None) -> bool:+ """Mirror fixed logic when candidate tools may already be sorted."""+ if not _should_set_body_tools(tools, original_tools):+ return False+ sorted_tools = _sort_tools(tools)+ if sorted_tools != tools:+ tools = sorted_tools+ return tools != original_tools+++def _legacy_should_set_body_tools_after_sort(+ tools: list | None, original_tools: list | None+) -> bool:+ """Older comparator that only wrote when sorting reordered."""+ if not _should_set_body_tools(tools, original_tools):+ return False+ return _sort_tools(tools) != tools++class TestHandlerGuardCondition:"""Verify the guard condition that decides whether to write body['tools']."""@@ -78,6 +102,14 @@ class TestHandlerGuardCondition:assert _should_set_body_tools(tools_after_helpers, original_tools)+ def test_sorted_replacement_reaches_body(self):+ """A sorted replacement that differs from payload still needs to be written."""+ original_tools = [{"name": "zeta"}, {"name": "alpha"}]+ tools_after_helpers = [{"name": "alpha"}, {"name": "zeta"}]++ assert not _legacy_should_set_body_tools_after_sort(tools_after_helpers, original_tools)+ assert _should_set_body_tools_after_sort(tools_after_helpers, original_tools)+# ---------------------------------------------------------------------------# apply_session_sticky_ccr_tool behaviour with no existing toolsdiff --git a/tests/test_proxy_byte_faithful_forwarding.py b/tests/test_proxy_byte_faithful_forwarding.pyindex 3d20e6cc4..d8c0eb87e 100644--- a/tests/test_proxy_byte_faithful_forwarding.py+++ b/tests/test_proxy_byte_faithful_forwarding.py@@ -25,11 +25,9 @@ from unittest.mock import AsyncMockimport httpximport pytest--pytest.importorskip("fastapi")-from fastapi.testclient import TestClient+from headroom.pipeline import PipelineStagefrom headroom.proxy.helpers import (BodyMutationTracker,append_text_to_latest_user_chat_message,@@ -40,6 +38,8 @@ from headroom.proxy.helpers import ()from headroom.proxy.server import ProxyConfig, create_app+pytest.importorskip("fastapi")+# ---------------------------------------------------------------------------# Unit tests for serializer + tracker# ---------------------------------------------------------------------------@@ -301,6 +301,13 @@ class _FakePrefixTracker:return None+class _SortedEmptyToolsPreSendExtension:+ def on_pipeline_event(self, event): # noqa: ANN001+ if event.stage is PipelineStage.PRE_SEND:+ event.tools = []+ return None++def _make_no_optimize_app() -> tuple[TestClient, _CapturingTransport]:"""Boot a proxy with all transforms disabled and a capturing transport."""config = ProxyConfig(@@ -411,6 +418,144 @@ def test_compression_off_numeric_precision_preserved() -> None:assert upstream == inbound_bytes+# Forward coverage only; the PRE_SEND case below is the base-fails proof for this fix.+def test_anthropic_tools_canonical_order_preserves_byte_faithful_request() -> None:+ client, transport = _make_no_optimize_app()+ inbound_dict = {+ "model": "claude-sonnet-4-6",+ "max_tokens": 64,+ "messages": [{"role": "user", "content": "plan test"}],+ "tools": [+ {"name": "alpha"},+ {"name": "zeta", "description": "later"},+ ],+ }+ 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, (+ f"Expected byte-faithful passthrough for canonical tools; upstream={upstream!r}"+ )+++def test_anthropic_tools_unsorted_reordered_and_canonicalized() -> None:+ client, transport = _make_no_optimize_app()+ 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": [+ inbound_dict["tools"][1],+ inbound_dict["tools"][0],+ ],+ }+ inbound_bytes = serialize_body_canonical(inbound_dict)+ expected_bytes = serialize_body_canonical(expected_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 == expected_bytes+ assert upstream != inbound_bytes+++def test_anthropic_presend_sorted_empty_tools_keeps_body_unmutated() -> None:+ inbound_dict = {+ "model": "claude-sonnet-4-6",+ "max_tokens": 64,+ "messages": [{"role": "user", "content": "plan test"}],+ }+ inbound_bytes = serialize_body_canonical(inbound_dict)++ config = ProxyConfig(+ optimize=False,+ cache_enabled=False,+ rate_limit_enabled=False,+ cost_tracking_enabled=False,+ log_requests=False,+ ccr_inject_tool=False,+ ccr_handle_responses=False,+ ccr_context_tracking=False,+ image_optimize=False,+ pipeline_extensions=[_SortedEmptyToolsPreSendExtension()],+ discover_pipeline_extensions=False,+ )+ app = create_app(config)+ client = TestClient(app)++ captured: dict[str, object] = {}++ async def _fake_retry(+ method: str, # noqa: ARG001+ url: str, # noqa: ARG001+ headers: dict[str, str], # noqa: ARG001+ body: dict[str, object], # noqa: ARG001+ body_mutated: bool,+ mutation_reasons: list[str],+ **kwargs: object, # noqa: ANN003+ ) -> httpx.Response: # noqa: ANN201+ captured["body_mutated"] = body_mutated+ captured["mutation_reasons"] = mutation_reasons+ captured["body"] = body+ return httpx.Response(+ 200,+ json={+ "id": "msg_1",+ "type": "message",+ "role": "assistant",+ "content": [{"type": "text", "text": "ok"}],+ "usage": {+ "input_tokens": 10,+ "output_tokens": 3,+ "cache_read_input_tokens": 0,+ "cache_creation_input_tokens": 0,+ },+ },+ )++ app.state.proxy._retry_request = _fake_retry # type: ignore[assignment]+ 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+ assert captured["body_mutated"] is False+ assert captured["mutation_reasons"] == []+ forwarded = captured["body"]+ assert isinstance(forwarded, dict)+ assert "tools" not in forwarded++def test_legacy_json_kwarg_mode_yields_drifted_bytes(monkeypatch: pytest.MonkeyPatch,) -> None: