mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
fix(memory): avoid injecting tools into tool-free requests (#3677)
## Description Memory tool injection should be suppressed only for a client that is explicitly known not to support tools. An omitted or empty `tools` field is not enough to make that determination because Codex and other clients may advertise tool capability out of band. Closes #3676 ## Changes Made - Carry the client capability decision through the Anthropic and OpenAI Responses paths. - Preserve existing and sticky memory tools for Codex and unknown clients. - Suppress fresh and sticky memory-tool injection only for an explicitly tool-incapable client. - Add endpoint-level and helper regressions for that distinction. ## Testing - Targeted memory and routing tests passed locally. - `ruff check .` passed. - `ruff format --check .` passed. - `mypy` passed for the changed modules. - GitHub CI is running on the current head. ## Runtime Rollout Safety - No new feature flag, schema, or migration is introduced. - Existing memory injection configuration remains the available disable path. - Rollback is a normal revert of this change. ## Review Readiness - Self-review completed. - The PR is ready for human review. --------- Co-authored-by: JD Davis <mxjerrett@gmail.com>
This commit is contained in:
@@ -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 = True
|
||||
|
||||
@@ -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_tools
|
||||
|
||||
@@ -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 the
|
||||
bypass 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 a
|
||||
fresh list (caller-safe). ``was_injected`` is True iff at least one
|
||||
memory 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)
|
||||
|
||||
@@ -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"] = True
|
||||
request.scope["headers"].append((b"x-client", b"codex"))
|
||||
client = getattr(request, "client", None)
|
||||
client_addr = ""
|
||||
|
||||
@@ -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",
|
||||
]
|
||||
|
||||
|
||||
@@ -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_no
|
||||
first_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_tools
|
||||
assert forwarded_turns[0]["response"]["tools"] == forwarded_turns[1]["response"]["tools"]
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
@pytest.mark.parametrize("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.asyncio
|
||||
async def test_memory_lookup_skips_input_bearing_non_create_first_frame():
|
||||
upstream = _FakeUpstream(
|
||||
|
||||
@@ -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()
|
||||
|
||||
@@ -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, monkey
|
||||
body["store"] = store
|
||||
request = _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()
|
||||
|
||||
|
||||
@@ -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_initial
|
||||
self._disconnect_after_n_sends = disconnect_after_n_sends
|
||||
|
||||
@@ -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 == 0
|
||||
assert memory_handler.tool_calls == 0
|
||||
|
||||
|
||||
@pytest.mark.parametrize("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", []) == []
|
||||
|
||||
Reference in New Issue
Block a user