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(memory): avoid injecting tools into tool-free requests (#3677)
AxelRay46755b5f7280
diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.pyindex 584bcfafd..9ca8199f2 100644--- a/headroom/proxy/handlers/anthropic.py+++ b/headroom/proxy/handlers/anthropic.py@@ -2797,6 +2797,7 @@ class AnthropicHandlerMixin:existing_tools=tools,memory_tools_to_inject=memory_tool_defs,inject_this_turn=bool(self.memory_handler.config.inject_tools),+ client_declared_tools=bool(_original_tools),)if mem_tools_injected:memory_tools_injected = Truediff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.pyindex 4bccb8779..77c659b68 100644--- a/headroom/proxy/handlers/openai.py+++ b/headroom/proxy/handlers/openai.py@@ -192,6 +192,17 @@ def _codex_ws_compression_timeout_seconds() -> float:_WS_ALLOWED_ORIGINS_ENV = "HEADROOM_WS_ORIGINS"_CORS_ALLOWED_ORIGINS_ENV = "HEADROOM_CORS_ORIGINS"_CODEX_RESPONSES_LITE_HEADER = "x-openai-internal-codex-responses-lite"+# Memory-tool injection needs affirmative protocol evidence. A caller that+# explicitly supplies tools is handled separately at each endpoint; when the+# caller omits them, only a real client known to support Headroom's memory+# tools may opt in.+_KNOWN_TOOL_CAPABLE_CLIENTS = frozenset({"codex"})+++def _client_can_receive_memory_tools(client: str | None) -> bool:+ return client in _KNOWN_TOOL_CAPABLE_CLIENTS++# Codex mirrors the responses-lite request header into the response.create# frame body under client_metadata; upstream rejects gpt-5.x when it is# truthy. Stripping the WS handshake header alone is insufficient@@ -4352,6 +4363,7 @@ class OpenAIHandlerMixin:existing_tools=tools,memory_tools_to_inject=memory_tool_defs,inject_this_turn=bool(self.memory_handler.config.inject_tools),+ client_declared_tools=bool(_original_tools),)if mem_tools_injected:memory_tools_injected = True@@ -5842,6 +5854,14 @@ class OpenAIHandlerMixin:headers, is_chatgpt_auth = _resolve_codex_routing_headers(headers)if is_chatgpt_auth:client = "codex"+ memory_client = (+ "codex"+ if is_chatgpt_auth+ else (None if request.scope.get("headroom_codex_client_stamped") else client)+ )+ client_declared_response_tools = bool(+ body.get("tools")+ ) or _client_can_receive_memory_tools(memory_client)if _ensure_chatgpt_responses_store_false(body, is_chatgpt_auth=is_chatgpt_auth):logger.info(f"[{request_id}] Responses: forced store=false for ChatGPT auth")responses_memory_tools_allowed = _allow_responses_memory_tools(is_chatgpt_auth)@@ -6112,6 +6132,7 @@ class OpenAIHandlerMixin:existing_tools=resp_tools,memory_tools_to_inject=memory_tool_defs_responses,inject_this_turn=bool(self.memory_handler.config.inject_tools),+ client_declared_tools=client_declared_response_tools,)if mem_tools_injected:body["tools"] = resp_tools@@ -7101,7 +7122,9 @@ class OpenAIHandlerMixin:# WS sessions bypass the HTTP middleware that stamps X-Client: codex on# the Responses endpoint, so apply the same path-based stamp here before# classify_client runs (parallels server.py / should_stamp_codex_client).- if should_stamp_codex_client(_ws_path, ws_headers):+ codex_client_was_stamped = should_stamp_codex_client(_ws_path, ws_headers)+ raw_client = classify_client(ws_headers)+ if codex_client_was_stamped:ws_headers["x-client"] = "codex"# Identify the WS harness before downstream auth/header rewrites.# Captured in closure so per-turn RequestOutcome can stamp it.@@ -7186,6 +7209,9 @@ class OpenAIHandlerMixin:)upstream_headers, is_chatgpt_auth = _resolve_codex_routing_headers(upstream_headers)+ memory_client = (+ "codex" if is_chatgpt_auth else (None if codex_client_was_stamped else raw_client)+ )# OpenAI rejects newer Codex models when this client-only lite header leaks upstream.upstream_headers = {key: value@@ -7807,6 +7833,9 @@ class OpenAIHandlerMixin:t.get("name") or t.get("function", {}).get("name", "?")for t in (ws_response_body.get("tools") or [])]+ client_declared_ws_tools = bool(+ ws_response_body.get("tools")+ ) or _client_can_receive_memory_tools(memory_client)instr_preview = (ws_response_body.get("instructions") or "")[:200]logger.info(f"[{request_id}] WS Memory: Codex tools={existing_tool_names}, "@@ -7927,6 +7956,7 @@ class OpenAIHandlerMixin:inject_this_turn=bool(self.memory_handler.config.inject_tools and ws_memory_tools_allowed),+ client_declared_tools=client_declared_ws_tools,)if mem_injected:ws_response_body["tools"] = ws_toolsdiff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.pyindex b7f502759..c1d0cb58d 100644--- a/headroom/proxy/helpers.py+++ b/headroom/proxy/helpers.py@@ -2403,6 +2403,7 @@ def apply_session_sticky_memory_tools(existing_tools: list[dict[str, Any]] | None,memory_tools_to_inject: list[dict[str, Any]],inject_this_turn: bool,+ client_declared_tools: bool = True,) -> tuple[list[dict[str, Any]], bool]:"""Apply sticky-on memory tool injection per `SessionToolTracker`.@@ -2431,6 +2432,11 @@ def apply_session_sticky_memory_tools(``inject_this_turn`` flag drives the decision verbatim. We log thebypass once so operators can see it.+ ``client_declared_tools`` is False when the inbound request omitted+ tools or explicitly sent an empty list. In that case memory tools are+ never added, including sticky replay, because the client cannot service+ them.+Returns ``(updated_tools, was_injected)``. The returned list is afresh list (caller-safe). ``was_injected`` is True iff at least onememory tool was added to the list.@@ -2439,6 +2445,16 @@ def apply_session_sticky_memory_tools(raise ValueError(f"unsupported provider: {provider!r}")tools_out: list[dict[str, Any]] = list(existing_tools) if existing_tools else []+ if not client_declared_tools:+ log_tool_injection_decision(+ provider=provider,+ session_id=session_id,+ decision="skip_no_client_tools",+ tool_definition_bytes_count=0,+ request_id=request_id,+ )+ return tools_out, False+existing_names: set[str] = set()for t in tools_out:n = _extract_tool_name(t)diff --git a/headroom/proxy/server.py b/headroom/proxy/server.pyindex 9a0ddf14c..11ca2f9fc 100644--- a/headroom/proxy/server.py+++ b/headroom/proxy/server.py@@ -3728,6 +3728,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:# hard connection failure. Mutating scope["headers"] before call_next# makes every downstream classify_client(headers) read "codex".if should_stamp_codex_client(path, headers):+ request.scope["headroom_codex_client_stamped"] = Truerequest.scope["headers"].append((b"x-client", b"codex"))client = getattr(request, "client", None)client_addr = ""diff --git a/headroom/proxy/tool_injection_logging.py b/headroom/proxy/tool_injection_logging.pyindex ad05554eb..a05b0b0b6 100644--- a/headroom/proxy/tool_injection_logging.py+++ b/headroom/proxy/tool_injection_logging.py@@ -18,6 +18,7 @@ ToolInjectionDecision = Literal[# tool definition is re-injected even without fresh compression (#2440)."inject_history_reference","skip",+ "skip_no_client_tools","skip_disabled_via_env",]diff --git a/tests/test_codex_ws_per_frame_memory.py b/tests/test_codex_ws_per_frame_memory.pyindex 278b00ec3..8949c4672 100644--- a/tests/test_codex_ws_per_frame_memory.py+++ b/tests/test_codex_ws_per_frame_memory.py@@ -72,6 +72,24 @@ def _turn(text: str) -> str:return json.dumps({"type": "response.create", "response": {"input": text}})+def _turn_with_tools(text: str, tools: list[dict[str, object]] | None) -> str:+ response: dict[str, object] = {"input": text}+ if tools is not None:+ response["tools"] = tools+ return json.dumps({"type": "response.create", "response": response})+++def _client_response_tools() -> list[dict[str, object]]:+ return [+ {+ "type": "function",+ "name": "client_tool",+ "description": "client tool",+ "parameters": {"type": "object", "properties": {}},+ }+ ]++def _direct_turn(text: str) -> str:return json.dumps({"input": text})@@ -152,9 +170,9 @@ async def test_memory_lookup_runs_for_each_issue_artifact_frame_and_preserves_nofirst_turn, later_turn = _issue_2059_turns()first_input, later_input = _issue_2059_inputs()client_frames = [- first_turn,+ _turn_with_tools(json.loads(first_turn)["response"]["input"], _client_response_tools()),json.dumps({"type": "response.cancel"}),- later_turn,+ _turn_with_tools(json.loads(later_turn)["response"]["input"], _client_response_tools()),]client_ws = _FakeWebSocket(frames=client_frames)handler = _DummyOpenAIHandler()@@ -171,12 +189,36 @@ async def test_memory_lookup_runs_for_each_issue_artifact_frame_and_preserves_no]assert f"current memory: {first_input}" in forwarded_turns[0]["response"]["input"]assert f"current memory: {later_input}" in forwarded_turns[1]["response"]["input"]- expected_tools = _expected_memory_response_tools()+ expected_tools = [*_client_response_tools(), *_expected_memory_response_tools()]for frame in forwarded_turns:assert frame["response"]["tools"] == expected_toolsassert forwarded_turns[0]["response"]["tools"] == forwarded_turns[1]["response"]["tools"][email protected]("tools", [None, []], ids=["omitted", "empty"])+async def test_ws_responses_do_not_inject_memory_tools_without_client_tools(tools):+ upstream = _FakeUpstream(+ [+ json.dumps({"type": "response.created", "response": {"id": "r_no_tools"}}),+ json.dumps({"type": "response.completed", "response": {"id": "r_no_tools"}}),+ ]+ )+ client_ws = _FakeWebSocket(+ frames=[_turn_with_tools("no tools requested", tools)],+ headers={"authorization": "Bearer test", "x-client": "unknown-client"},+ )+ handler = _DummyOpenAIHandler()+ handler.memory_handler = _MemoryHandler()++ with patch.dict(sys.modules, {"websockets": _make_fake_websockets_module(upstream)}):+ await handler.handle_openai_responses_ws(client_ws)++ forwarded = [json.loads(frame) for frame in upstream.sent if "response" in json.loads(frame)]+ assert forwarded+ assert forwarded[0]["response"].get("tools", []) == []++@pytest.mark.asyncioasync def test_memory_lookup_skips_input_bearing_non_create_first_frame():upstream = _FakeUpstream(diff --git a/tests/test_memory_tool_session_sticky.py b/tests/test_memory_tool_session_sticky.pyindex dd3b761f5..c20931019 100644--- a/tests/test_memory_tool_session_sticky.py+++ b/tests/test_memory_tool_session_sticky.py@@ -500,6 +500,51 @@ def test_memory_disabled_after_inject_still_injects() -> None:assert bytes1 == bytes2+def test_no_client_tools_suppresses_fresh_and_sticky_injection() -> None:+ """Requests without client-declared tools must not receive memory tools."""+ defs = _anthropic_memory_defs()+ client_tools = [{"name": "client_tool", "description": "client-owned", "input_schema": {}}]++ fresh_tools, fresh_was = apply_session_sticky_memory_tools(+ provider="anthropic",+ session_id="s-fresh-no-client-tools",+ request_id="r-fresh",+ existing_tools=None,+ memory_tools_to_inject=defs,+ inject_this_turn=True,+ client_declared_tools=False,+ )+ assert fresh_was is False+ assert fresh_tools == []++ # Establish sticky memory tools while the client has declared tools.+ tools1, was1 = apply_session_sticky_memory_tools(+ provider="anthropic",+ session_id="s-no-client-tools",+ request_id="r-1",+ existing_tools=client_tools,+ memory_tools_to_inject=defs,+ inject_this_turn=True,+ client_declared_tools=True,+ )+ assert was1 is True+ assert "memory_search" in _names_in(tools1)++ # A later request omits tools entirely. Sticky replay must not turn it into+ # a tool-capable request that the client cannot service.+ tools2, was2 = apply_session_sticky_memory_tools(+ provider="anthropic",+ session_id="s-no-client-tools",+ request_id="r-2",+ existing_tools=[],+ memory_tools_to_inject=defs,+ inject_this_turn=True,+ client_declared_tools=False,+ )+ assert was2 is False+ assert tools2 == []++def test_different_sessions_independent() -> None:"""Session A injects; session B doesn't; verify isolation."""defs = _anthropic_memory_defs()diff --git a/tests/test_openai_codex_routing.py b/tests/test_openai_codex_routing.pyindex 5b7d4b0d2..447a10196 100644--- a/tests/test_openai_codex_routing.py+++ b/tests/test_openai_codex_routing.py@@ -553,7 +553,11 @@ def test_handle_openai_responses_chatgpt_codex_timeout_fails_open(monkeypatch):def test_handle_openai_responses_api_auth_store_false_injects_stateless_memory_tools(monkeypatch):request = _build_request({"model": "gpt-4o-mini", "input": "hello", "store": False},- {"Authorization": "Bearer sk-test", "x-headroom-user-id": "user-1"},+ {+ "Authorization": "Bearer sk-test",+ "User-Agent": "codex-cli/0.5",+ "x-headroom-user-id": "user-1",+ },)handler = _DummyOpenAIHandler()memory_handler = _MemoryToolsOnlyHandler()@@ -618,7 +622,11 @@ def test_openai_responses_memory_continuation_is_zdr_safe(store, include, monkeybody["store"] = storerequest = _build_request(body,- {"Authorization": "Bearer sk-test", "x-headroom-user-id": "user-1"},+ {+ "Authorization": "Bearer sk-test",+ "User-Agent": "codex-cli/0.5",+ "x-headroom-user-id": "user-1",+ },)handler = _ZdrResponsesHandler()diff --git a/tests/test_openai_codex_ws_lifecycle.py b/tests/test_openai_codex_ws_lifecycle.pyindex 37331607d..054cd921a 100644--- a/tests/test_openai_codex_ws_lifecycle.py+++ b/tests/test_openai_codex_ws_lifecycle.py@@ -195,7 +195,13 @@ class _FakeWebSocket:hold_after_initial: bool = False,call_log: list[str] | None = None,) -> None:- self.headers = dict(headers or {"authorization": "Bearer test"})+ self.headers = dict(+ headers+ or {+ "authorization": "Bearer test",+ "user-agent": "codex-cli/0.5",+ }+ )self._frames = list(frames or [])self._hold_after_initial = hold_after_initialself._disconnect_after_n_sends = disconnect_after_n_sendsdiff --git a/tests/test_proxy_openai_responses_bypass.py b/tests/test_proxy_openai_responses_bypass.pyindex f119d435b..864f188eb 100644--- a/tests/test_proxy_openai_responses_bypass.py+++ b/tests/test_proxy_openai_responses_bypass.py@@ -112,3 +112,58 @@ def test_responses_bypass_skips_memory_and_compression_mutation() -> None:assert "tools" not in captured["body"]assert memory_handler.search_calls == 0assert memory_handler.tool_calls == 0++[email protected]("tools", [None, []], ids=["omitted", "empty"])+def test_responses_do_not_inject_memory_tools_without_client_tools(tools) -> None:+ app = create_app(+ ProxyConfig(+ optimize=False,+ cache_enabled=False,+ rate_limit_enabled=False,+ cost_tracking_enabled=False,+ log_requests=False,+ )+ )+ app.dependency_overrides[require_loopback] = lambda: None+ captured: dict[str, Any] = {}++ with TestClient(app) as client:+ proxy = client.app.state.proxy+ memory_handler = _MemoryHandler()+ memory_handler.config.inject_context = False+ proxy.memory_handler = memory_handler++ async def _fake_retry(+ method: str,+ url: str,+ headers: dict[str, str],+ body: dict[str, Any],+ stream: bool = False,+ **kwargs: Any,+ ) -> httpx.Response:+ captured["body"] = dict(body)+ return httpx.Response(+ 200,+ json={+ "id": "resp_no_memory_tools",+ "output": [],+ "usage": {"input_tokens": 1, "output_tokens": 1},+ },+ )++ proxy._retry_request = _fake_retry+ payload: dict[str, Any] = {"model": "gpt-4o-mini", "input": "hello"}+ if tools is not None:+ payload["tools"] = tools+ response = client.post(+ "/v1/responses",+ headers={+ "authorization": "Bearer test-key",+ "x-headroom-user-id": "user-no-memory-tools",+ },+ json=payload,+ )++ assert response.status_code == 200+ assert captured["body"].get("tools", []) == []