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): drop web_search_call history from a Responses request with no web_search tool (#4202)
gglucass2a70d1281955
diff --git a/docs/content/docs/security-model.mdx b/docs/content/docs/security-model.mdxindex 729769887..1540b1bb4 100644--- a/docs/content/docs/security-model.mdx+++ b/docs/content/docs/security-model.mdx@@ -284,6 +284,7 @@ accept arbitrary environment variables — writes are restricted to a hardcoded| `HEADROOM_INTERCEPT_READ_MIN_CHARS` | ast-grep read-interception threshold || `HEADROOM_VERIFY_TRUNCATION_ON_DISK` | Verify ast-grep Read truncation against disk when no client banner is found. Always returns `UNKNOWN` on Windows, where `dir_fd` / `O_NOFOLLOW` support is unavailable. || `HEADROOM_VERIFY_TRUNCATION_MAX_BYTES` | Max on-disk file size (bytes) the disk-verify fallback will read |+| `HEADROOM_WEB_SEARCH_HISTORY` | Drop `web_search_call` history from a Responses request that declares no web_search tool (default on; `0` disables) || `HEADROOM_BUFFERED_UPSTREAM_STREAM` | Send buffered CCR requests (and their continuations) upstream as `stream: true` and fold the reply (default on; `0` sends `stream: false`) |Keys outside this list are ignored, and `/admin/upstream` is read-only — there is nodiff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.pyindex afbf3a5da..741326e46 100644--- a/headroom/proxy/handlers/openai.py+++ b/headroom/proxy/handlers/openai.py@@ -1129,6 +1129,109 @@ def _ensure_chatgpt_responses_store_false(return False+def _web_search_history_drop_enabled() -> bool:+ from headroom.proxy import runtime_env++ return (runtime_env.getenv("HEADROOM_WEB_SEARCH_HISTORY", "1") or "1").strip().lower() not in (+ "0",+ "false",+ "no",+ "off",+ )+++def _drop_undeclared_web_search_calls(+ payload: dict[str, Any],+ *,+ request_id: str | None = None,+) -> int:+ """Drop hosted ``web_search_call`` items from a request that cannot search.++ Workaround for an OpenAI backend behaviour, not a Headroom bug. Codex on a+ custom model provider (how Headroom wraps it) compacts locally: it resends+ the whole history to ``/v1/responses`` with ``tools: []``. When that+ history holds a hosted ``web_search_call`` item, the ChatGPT backend+ answers 200 and then the in-band error "response protection is+ unavailable". Codex ignores in-band ``error`` events, reports "stream+ closed before response.completed", retries, and runs the same compaction+ before every later prompt, so the session never answers again. The same+ body completes with the ``web_search_call`` items removed, or with a+ web_search tool declared.++ Only the search action (its query or URL) leaves the history; the results+ were never in it, and the model's answer that followed is a separate+ ``message`` item that stays. A tool counts as declared in top-level+ ``tools`` or in a Codex ``additional_tools`` input item (Codex >= 0.149+ sends tools that way), under any ``web_search*`` type spelling. A request+ continuing ``previous_response_id`` is left alone: its declarations may+ live server-side.++ Mutates *payload* in place and returns the number of items dropped+ (0 = untouched). Callers skip it for a bypass request+ (``x-headroom-bypass: true``), which asked for its bytes untouched.+ Disable with ``HEADROOM_WEB_SEARCH_HISTORY=0`` (a registered runtime-env+ knob, so ``headroom wrap`` also pushes it to a reused proxy). Remove once+ the backend accepts such a body.+ """+ items = payload.get("input")+ if not isinstance(items, list) or payload.get("previous_response_id"):+ return 0+ if not any(isinstance(item, dict) and item.get("type") == "web_search_call" for item in items):+ return 0+ tools = payload.get("tools")+ declared = list(tools) if isinstance(tools, list) else []+ for item in items:+ if isinstance(item, dict) and item.get("type") == "additional_tools":+ declared.extend(item["tools"] if isinstance(item.get("tools"), list) else [])+ if any(+ isinstance(tool, dict) and str(tool.get("type") or "").startswith("web_search")+ for tool in declared+ ):+ return 0+ if not _web_search_history_drop_enabled():+ return 0+ kept = [+ item+ for item in items+ if not (isinstance(item, dict) and item.get("type") == "web_search_call")+ ]+ payload["input"] = kept+ dropped = len(items) - len(kept)+ logger.info(+ "event=web_search_history request_id=%s dropped=%d reason=no_web_search_tool",+ request_id or "-",+ dropped,+ )+ return dropped+++def _drop_undeclared_web_search_calls_from_frame(+ raw_msg: str,+ *,+ request_id: str | None = None,+) -> str:+ """Apply :func:`_drop_undeclared_web_search_calls` to a WS ``response.create`` frame.++ Returns *raw_msg* unchanged (same object) unless items were dropped. The+ substring prescreen keeps every frame without a ``web_search_call`` from+ paying a parse. JSON can spell the type with ``\\uXXXX`` escapes+ (``"web_search\\u005fcall"``), and a letter or underscore can only be+ escaped that way, so a frame holding any ``\\u`` is parsed too.+ """+ if '"web_search_call"' not in raw_msg and "\\u" not in raw_msg:+ return raw_msg+ try:+ frame = json.loads(raw_msg)+ except (json.JSONDecodeError, TypeError, ValueError):+ return raw_msg+ if not isinstance(frame, dict) or frame.get("type") != "response.create":+ return raw_msg+ payload = frame["response"] if isinstance(frame.get("response"), dict) else frame+ if not _drop_undeclared_web_search_calls(payload, request_id=request_id):+ return raw_msg+ return json.dumps(frame)++_RESPONSES_OUTPUT_ITEM_TYPES = frozenset({"custom_tool_call_output",@@ -5771,6 +5874,12 @@ class OpenAIHandlerMixin:# minimal `messages` list purely for downstream memory injection and# telemetry; list-typed `input` is consulted directly by the unit# extraction helpers.+ #+ # Before anything reads `input`: drop web_search_call history from a+ # request that declares no web_search tool (Codex local compaction).+ # A bypass request asked for its bytes untouched, so it is left alone.+ if not _bypass and _drop_undeclared_web_search_calls(body, request_id=request_id):+ body_mutation_tracker.mark_mutated("responses_web_search_history")input_data = body.get("input", "")instructions = body.get("instructions")@@ -7673,6 +7782,14 @@ class OpenAIHandlerMixin:model or "unknown",)+ # Resolved before the frame helpers below, which read it.+ _ws_bypass = self._headroom_bypass_enabled(ws_headers)+ if _ws_bypass:+ logger.info(+ "[%s] WS /v1/responses passthrough reason=bypass_header mutation=disabled",+ request_id,+ )+def _normalize_ws_response_create_for_upstream(raw_msg: str) -> str:"""Optionally flatten Codex WS response.create frames for gateways.@@ -7680,7 +7797,18 @@ class OpenAIHandlerMixin:OpenAI-compatible gateways accept the WebSocket upgrade but expectmodel/input/tools at the top level of response.create frames.Preserve default upstream behavior unless explicitly enabled.++ Every response.create frame headed upstream (first frame, which+ the HTTP fallback also replays, later frames, memory+ continuations) passes through here, so it also drops+ web_search_call history the frame declares no tool for (see+ ``_drop_undeclared_web_search_calls``), except on a bypass+ session, whose frames stay as the client sent them."""+ if not _ws_bypass:+ raw_msg = _drop_undeclared_web_search_calls_from_frame(+ raw_msg, request_id=request_id+ )if os.environ.get("HEADROOM_OPENAI_WS_FLATTEN_RESPONSE_CREATE", "").strip().lower() not in (diff --git a/headroom/proxy/runtime_env.py b/headroom/proxy/runtime_env.pyindex 08110776a..74a36a02e 100644--- a/headroom/proxy/runtime_env.py+++ b/headroom/proxy/runtime_env.py@@ -84,6 +84,12 @@ RUNTIME_ENV_KNOBS: tuple[Knob, ...] = ("int","Max on-disk file size (bytes) the disk-verify fallback will read.",),+ Knob(+ "HEADROOM_WEB_SEARCH_HISTORY",+ "bool",+ "Drop web_search_call history from a Responses request that declares no "+ "web_search tool (default on; 0 disables).",+ ),Knob("HEADROOM_BUFFERED_UPSTREAM_STREAM","bool",diff --git a/tests/test_openai_responses_web_search_history.py b/tests/test_openai_responses_web_search_history.pynew file mode 100644index 000000000..3d321c72c--- /dev/null+++ b/tests/test_openai_responses_web_search_history.py@@ -0,0 +1,413 @@+"""web_search_call history on a Responses request that declares no web_search tool.++Codex on a custom provider compacts locally: it resends the whole history with+``tools: []``. When that history holds a hosted ``web_search_call`` item, the+ChatGPT backend answers 200 and then the in-band error "response protection is+unavailable", and the Codex session never answers again. The proxy drops those+items from such a request (HTTP and WebSocket) and leaves every other body+byte-identical.+"""++from __future__ import annotations++import asyncio+import copy+import json+import sys+from typing import Any+from unittest.mock import patch++import pytest++from headroom.proxy.handlers.openai import (+ _drop_undeclared_web_search_calls,+ _drop_undeclared_web_search_calls_from_frame,+)+from tests.test_openai_codex_ws_lifecycle import (+ _codex_lite_headers,+ _DummyOpenAIHandler,+ _FakeUpstream,+ _FakeWebSocket,+ _make_fake_websockets_module,+)+from tests.test_proxy_byte_faithful_forwarding import (+ _make_no_optimize_app,+ _start_proxy_log_capture,+ _stop_proxy_log_capture,+)+++def _user(text: str) -> dict[str, Any]:+ return {"type": "message", "role": "user", "content": [{"type": "input_text", "text": text}]}+++def _search(n: int) -> dict[str, Any]:+ return {+ "type": "web_search_call",+ "id": f"ws_{n}",+ "status": "completed",+ "action": {"type": "search", "query": f"query {n}"},+ }+++def _answer(text: str) -> dict[str, Any]:+ return {+ "type": "message",+ "role": "assistant",+ "content": [{"type": "output_text", "text": text}],+ }+++def _compaction_body(**overrides: Any) -> dict[str, Any]:+ """A Codex local-compaction request: full history, ``tools: []``."""+ body: dict[str, Any] = {+ "model": "gpt-5.5",+ "instructions": "Summarize the conversation.",+ "input": [+ _user("look this up"),+ {"type": "reasoning", "id": "rs_1", "summary": [], "encrypted_content": "enc"},+ _search(1),+ _search(2),+ _answer("found it"),+ _user("Summarize the conversation so far."),+ ],+ "tools": [],+ "stream": True,+ "store": False,+ }+ body.update(overrides)+ return body+++def _types(body: dict[str, Any]) -> list[str]:+ return [item["type"] for item in body["input"]]+++# --- the decision ----------------------------------------------------------+++ "tools",+ [+ pytest.param([], id="empty"),+ pytest.param(None, id="absent"),+ pytest.param([{"type": "function", "name": "shell"}], id="function-only"),+ pytest.param([{"type": "function", "name": "web_search"}], id="function-named-web_search"),+ ],+)+def test_drops_web_search_calls_when_no_web_search_tool_is_declared(tools) -> None:+ body = _compaction_body()+ if tools is None:+ del body["tools"]+ else:+ body["tools"] = tools++ assert _drop_undeclared_web_search_calls(body, request_id="r1") == 2+ # Only the search actions leave; the answer and reasoning stay in order.+ assert _types(body) == ["message", "reasoning", "message", "message"]+ assert body["input"][2] == _answer("found it")+++ "tool_type",+ ["web_search", "web_search_preview", "web_search_preview_2025_03_11", "web_search_2025_08_26"],+)+def test_keeps_web_search_calls_when_a_web_search_tool_is_declared(tool_type: str) -> None:+ body = _compaction_body(tools=[{"type": "function", "name": "shell"}, {"type": tool_type}])+ before = copy.deepcopy(body)++ assert _drop_undeclared_web_search_calls(body) == 0+ assert body == before+++def test_keeps_web_search_calls_declared_through_codex_additional_tools() -> None:+ # Codex >= 0.149 sends tools as an ``additional_tools`` input item and no+ # top-level ``tools``; a normal turn there must not lose its history.+ body = _compaction_body()+ del body["tools"]+ body["input"].insert(0, {"type": "additional_tools", "tools": [{"type": "web_search"}]})+ before = copy.deepcopy(body)++ assert _drop_undeclared_web_search_calls(body) == 0+ assert body == before+++def test_leaves_unaffected_bodies_alone() -> None:+ no_search = _compaction_body()+ no_search["input"] = [item for item in no_search["input"] if item["type"] != "web_search_call"]+ continued = _compaction_body(previous_response_id="resp_1")+ string_input = _compaction_body(input="hello")+ for body in (no_search, continued, string_input):+ before = copy.deepcopy(body)+ assert _drop_undeclared_web_search_calls(body) == 0+ assert body == before+++def test_kill_switch_disables_the_drop(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv("HEADROOM_WEB_SEARCH_HISTORY", "0")+ body = _compaction_body()+ before = copy.deepcopy(body)++ assert _drop_undeclared_web_search_calls(body) == 0+ assert body == before+++def test_frame_helper_returns_the_same_string_unless_it_drops() -> None:+ wrapped = json.dumps({"type": "response.create", "response": _compaction_body()})+ out = _drop_undeclared_web_search_calls_from_frame(wrapped)+ assert _types(json.loads(out)["response"]) == ["message", "reasoning", "message", "message"]++ flat = json.dumps({"type": "response.create", **_compaction_body()})+ assert "web_search_call" not in _drop_undeclared_web_search_calls_from_frame(flat)++ for raw in (+ json.dumps(+ {+ "type": "response.create",+ "response": _compaction_body(tools=[{"type": "web_search"}]),+ }+ ),+ json.dumps({"type": "response.cancel", "response": _compaction_body()}),+ json.dumps({"type": "response.create", "response": {"model": "m", "input": "hi"}}),+ "not json",+ ):+ assert _drop_undeclared_web_search_calls_from_frame(raw) is raw+++def test_frame_helper_decodes_escaped_type_spellings() -> None:+ # json.loads reads "web_search_call" as web_search_call, and so does+ # the backend, so the prescreen must not skip it.+ escaped = (+ '{"type":"response.create","response":{"input":'+ '[{"type":"web_search\\u005fcall","id":"ws_1"}],"tools":[]}}'+ )+ assert json.loads(escaped)["response"]["input"][0]["type"] == "web_search_call"+ assert json.loads(_drop_undeclared_web_search_calls_from_frame(escaped))["response"] == {+ "input": [],+ "tools": [],+ }++ # Escapes alone change nothing: declared tool, no search history.+ for raw in (+ '{"type":"response.create","response":{"input":'+ '[{"type":"web_search\\u005fcall","id":"ws_1"}],"tools":[{"type":"web_search"}]}}',+ '{"type":"response.create","response":{"input":'+ '[{"type":"message","role":"user","content":"caf\\u00e9"}],"tools":[]}}',+ ):+ assert _drop_undeclared_web_search_calls_from_frame(raw) is raw+++# --- HTTP /v1/responses ----------------------------------------------------++_CODEX_HEADERS = {+ "authorization": "Bearer test-token",+ "chatgpt-account-id": "acct_test",+ "originator": "codex_cli_rs",+ "content-type": "application/json",+}+++def _post(+ body_bytes: bytes, *, stream: bool, extra_headers: dict[str, str] | None = None+) -> tuple[bytes, list[str]]:+ headers = {**_CODEX_HEADERS, **(extra_headers or {})}+ client, transport = _make_no_optimize_app()+ proxy_logger, handler, prev_level, records = _start_proxy_log_capture()+ try:+ if stream:+ with client.stream(+ "POST", "/v1/responses", headers=headers, content=body_bytes+ ) as response:+ assert response.status_code == 200+ for _ in response.iter_bytes():+ pass+ else:+ response = client.post("/v1/responses", headers=headers, content=body_bytes)+ assert response.status_code == 200, response.text+ finally:+ _stop_proxy_log_capture(proxy_logger, handler, prev_level)+ assert transport.captured_body is not None+ return transport.captured_body, [record.getMessage() for record in records]++[email protected]("stream", [True, False], ids=["stream", "buffered"])+def test_http_compaction_request_reaches_upstream_without_web_search_calls(stream: bool) -> None:+ body = _compaction_body(stream=stream)+ sent, logs = _post(json.dumps(body, indent=2).encode(), stream=stream)++ wire = json.loads(sent)+ assert _types(wire) == ["message", "reasoning", "message", "message"]+ expected = copy.deepcopy(body)+ expected["input"] = [item for item in body["input"] if item["type"] != "web_search_call"]+ assert wire == expected+ assert any("event=web_search_history" in m and "dropped=2" in m for m in logs), logs+ assert any(+ "event=outbound_request" in m and "responses_web_search_history" in m for m in logs+ ), logs+++ "body",+ [+ pytest.param(_compaction_body(tools=[{"type": "web_search"}]), id="tool-declared"),+ pytest.param(+ {**_compaction_body(), "input": [_user("hi"), _answer("hello")]}, id="no-search-history"+ ),+ ],+)+def test_http_unaffected_request_is_forwarded_byte_identical(body: dict[str, Any]) -> None:+ body_bytes = json.dumps(body, indent=2).encode()+ sent, logs = _post(body_bytes, stream=True)++ assert sent == body_bytes+ assert not any("event=web_search_history" in m for m in logs)++[email protected]("stream", [True, False], ids=["stream", "buffered"])+def test_http_bypass_request_is_forwarded_byte_identical(stream: bool) -> None:+ # A bypass client asked Headroom to stay out of its bytes, so even a body+ # the backend will refuse goes out exactly as sent.+ body_bytes = json.dumps(_compaction_body(stream=stream), indent=2).encode()+ sent, logs = _post(body_bytes, stream=stream, extra_headers={"x-headroom-bypass": "true"})++ assert sent == body_bytes+ assert not any("event=web_search_history" in m for m in logs)+++# --- Codex WebSocket /v1/responses ------------------------------------------+++def _frame(body: dict[str, Any]) -> str:+ return json.dumps({"type": "response.create", "response": body})+++def _upstream_events() -> list[str]:+ return [+ json.dumps({"type": "response.created", "response": {"id": "r_1"}}),+ json.dumps({"type": "response.completed", "response": {"id": "r_1"}}),+ ]+++async def test_ws_first_frame_reaches_upstream_without_web_search_calls() -> None:+ upstream = _FakeUpstream(_upstream_events())+ client_ws = _FakeWebSocket(frames=[_frame(_compaction_body())])++ with patch.dict(sys.modules, {"websockets": _make_fake_websockets_module(upstream)}):+ await _DummyOpenAIHandler().handle_openai_responses_ws(client_ws)++ assert len(upstream.sent) == 1+ assert _types(json.loads(upstream.sent[0])["response"]) == [+ "message",+ "reasoning",+ "message",+ "message",+ ]+++async def test_ws_bypass_session_frames_reach_upstream_unchanged() -> None:+ compaction = _frame(_compaction_body())+ upstream = _FakeUpstream([], hold_after_events=True)+ client_ws = _FakeWebSocket(+ frames=[compaction, compaction],+ headers={"authorization": "Bearer test", "x-headroom-bypass": "true"},+ hold_after_initial=True,+ )++ async def _disconnect_soon() -> None:+ await asyncio.sleep(0.05)+ client_ws.trigger_disconnect()++ with patch.dict(sys.modules, {"websockets": _make_fake_websockets_module(upstream)}):+ trigger = asyncio.create_task(_disconnect_soon())+ try:+ await asyncio.wait_for(+ _DummyOpenAIHandler().handle_openai_responses_ws(client_ws), timeout=2.0+ )+ finally:+ trigger.cancel()++ # First frame and a later frame both go out as the client sent them.+ assert upstream.sent == [compaction, compaction]++[email protected]("bypass", [False, True], ids=["normal", "bypass"])+async def test_ws_escaped_web_search_call_frame(bypass: bool) -> None:+ escaped = (+ '{"type":"response.create","response":{"model":"gpt-5-codex","input":'+ '[{"type":"web_search\\u005fcall","id":"ws_1"}],"tools":[]}}'+ )+ headers = {"authorization": "Bearer test"}+ if bypass:+ headers["x-headroom-bypass"] = "true"+ upstream = _FakeUpstream([], hold_after_events=True)+ client_ws = _FakeWebSocket(frames=[escaped], headers=headers, hold_after_initial=True)++ async def _disconnect_soon() -> None:+ await asyncio.sleep(0.05)+ client_ws.trigger_disconnect()++ with patch.dict(sys.modules, {"websockets": _make_fake_websockets_module(upstream)}):+ trigger = asyncio.create_task(_disconnect_soon())+ try:+ await asyncio.wait_for(+ _DummyOpenAIHandler().handle_openai_responses_ws(client_ws), timeout=2.0+ )+ finally:+ trigger.cancel()++ assert len(upstream.sent) == 1+ if bypass:+ assert upstream.sent[0] == escaped+ else:+ assert json.loads(upstream.sent[0])["response"]["input"] == []+++async def test_ws_later_frame_reaches_upstream_without_web_search_calls() -> None:+ normal_turn = _frame(_compaction_body(tools=[{"type": "web_search"}]))+ compaction = _frame(_compaction_body())+ upstream = _FakeUpstream([], hold_after_events=True)+ client_ws = _FakeWebSocket(frames=[normal_turn, compaction], hold_after_initial=True)++ async def _disconnect_soon() -> None:+ await asyncio.sleep(0.05)+ client_ws.trigger_disconnect()++ with patch.dict(sys.modules, {"websockets": _make_fake_websockets_module(upstream)}):+ trigger = asyncio.create_task(_disconnect_soon())+ try:+ await asyncio.wait_for(+ _DummyOpenAIHandler().handle_openai_responses_ws(client_ws), timeout=2.0+ )+ finally:+ trigger.cancel()++ assert len(upstream.sent) == 2+ # The turn that declares the tool goes out as the client sent it.+ assert upstream.sent[0] == normal_turn+ assert "web_search_call" not in upstream.sent[1]+++async def test_ws_http_fallback_gets_the_frame_without_web_search_calls() -> None:+ fake_ws_mod = _make_fake_websockets_module(None, connect_error=RuntimeError("HTTP 500"))+ client_ws = _FakeWebSocket(+ frames=[_frame(_compaction_body())], headers=_codex_lite_headers(chatgpt=True)+ )+ handler = _DummyOpenAIHandler()+ fallback_frames: list[str] = []++ async def _fallback(websocket, body, first_msg_raw, upstream_headers, request_id):+ fallback_frames.append(first_msg_raw)+ return 0, 0, 0, 0, 0++ handler._ws_http_fallback = _fallback # type: ignore[assignment]++ with patch.dict(sys.modules, {"websockets": fake_ws_mod}):+ await handler.handle_openai_responses_ws(client_ws)++ assert len(fallback_frames) == 1+ assert "web_search_call" not in fallback_frames[0]diff --git a/tests/test_runtime_env.py b/tests/test_runtime_env.pyindex 1d6973748..dfb7252d5 100644--- a/tests/test_runtime_env.py+++ b/tests/test_runtime_env.py@@ -129,6 +129,20 @@ def test_override_changes_astgrep_threshold_without_env():assert astgrep._min_chars_to_rewrite() == 500+def test_override_disables_web_search_history_drop_without_env():+ from headroom.proxy.handlers.openai import _drop_undeclared_web_search_calls++ def body() -> dict:+ return {"input": [{"type": "web_search_call", "id": "ws_1"}], "tools": []}++ assert _drop_undeclared_web_search_calls(body()) == 1+ rt.set_overrides({"HEADROOM_WEB_SEARCH_HISTORY": "0"})+ assert _drop_undeclared_web_search_calls(body()) == 0+ assert rt.explicit_env({"HEADROOM_WEB_SEARCH_HISTORY": "0"}) == {+ "HEADROOM_WEB_SEARCH_HISTORY": "0"+ }++# ---------------------------------------------------------------------------# /health surface + /admin/runtime-env hot-reload endpoint# ---------------------------------------------------------------------------