Skip to content

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.

fix(proxy): preserve retrieval outputs across Codex WS deltas (#4574)

Jermaine Sizemore682bf73f48bb
diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.py
index 14484c3fa..4d0d30700 100644
--- a/headroom/proxy/handlers/openai.py
+++ b/headroom/proxy/handlers/openai.py
@@ -134,6 +134,7 @@ from headroom.proxy.token_counting import gemini_output_tokens
logger = logging.getLogger("headroom.proxy")
_OPENAI_RESPONSES_UNIT_CACHE_MAX_ENTRIES = 10_000
+_OPENAI_RESPONSES_TOOL_CONTEXT_LIMIT = 512
_OPENAI_RESPONSES_UNIT_CACHE_VERSION = "openai_responses_unit_v1"
_OPENAI_RESPONSES_UNIT_PARALLELISM_ENV = "HEADROOM_TOOL_OUTPUT_COMPRESSION_PARALLELISM"
_OPENAI_RESPONSES_UNIT_PARALLELISM_DEFAULT = 4
@@ -2222,6 +2223,7 @@ class OpenAIHandlerMixin:
request_id: str,
timing: dict[str, float] | None = None,
deadline_started_at: float | None = None,
+ tool_names_by_call_id: dict[str, str] | None = None,
) -> tuple[dict[str, Any], bool, int, list[str], dict[str, int], list[str], int]:
"""Run ContentRouter on OpenAI Responses text units.
@@ -2344,7 +2346,6 @@ class OpenAIHandlerMixin:
return True
return False
- headroom_retrieve_call_ids: set[str] = set()
# Map each Responses tool call to its name so that outputs belonging to
# excluded tools (HEADROOM_EXCLUDE_TOOLS) can be protected from
# compression. The chat/Anthropic paths get this via
@@ -2352,7 +2353,7 @@ class OpenAIHandlerMixin:
# name on the `function_call` (or Codex `custom_tool_call`) item and
# the originating call_id on the matching output, so we correlate
# them here.
- function_name_by_call_id: dict[str, str] = {}
+ function_name_by_call_id = dict(tool_names_by_call_id or {})
for item in items:
if not isinstance(item, dict):
continue
@@ -2366,12 +2367,13 @@ class OpenAIHandlerMixin:
name = unwrap_tool_call_name(name, item.get("arguments") or item.get("input"))
if isinstance(name, str) and isinstance(call_id, str) and call_id:
function_name_by_call_id[call_id] = name
- # Same matcher ContentRouter uses for its ccr_retrieve guard, so the
- # MCP alias forms (mcp__srv__x, Hermes' mcp_srv_x, OpenCode's
- # headroom_headroom_retrieve) are recognized here too.
- if isinstance(name, str) and is_tool_excluded(name, ("headroom_retrieve",)):
- if isinstance(call_id, str) and call_id:
- headroom_retrieve_call_ids.add(call_id)
+ # Continuations may contain outputs only; observed WS names retain the
+ # same unconditional retrieval guard as calls present in this payload.
+ headroom_retrieve_call_ids = {
+ call_id
+ for call_id, name in function_name_by_call_id.items()
+ if is_tool_excluded(name, ("headroom_retrieve",))
+ }
# Resolve the effective exclude set once (None -> built-in defaults),
# mirroring ContentRouter's policy. exclude_tools already contains both
@@ -2896,6 +2898,7 @@ class OpenAIHandlerMixin:
client: str | None = None,
savings_tags: dict[str, Any] | None = None,
deadline_started_at: float | None = None,
+ tool_names_by_call_id: dict[str, str] | None = None,
) -> tuple[dict[str, Any], bool, int, list[str], str | None, int, int, int]:
"""Compress an OpenAI Responses payload through the shared router.
@@ -3129,6 +3132,7 @@ class OpenAIHandlerMixin:
request_id=request_id,
timing=timing_sink,
deadline_started_at=deadline_started_at,
+ tool_names_by_call_id=tool_names_by_call_id,
)
_add_timing("compression_live_units_total", live_units_started)
if router_modified:
@@ -3196,6 +3200,7 @@ class OpenAIHandlerMixin:
timeout: float = COMPRESSION_TIMEOUT_SECONDS,
client: str | None = None,
savings_tags: dict[str, Any] | None = None,
+ tool_names_by_call_id: dict[str, str] | None = None,
) -> tuple[dict[str, Any], bool, int, list[str], str | None, int, int, int, dict[str, float]]:
timing: dict[str, float] = {}
@@ -3245,6 +3250,8 @@ class OpenAIHandlerMixin:
}
if savings_tags is not None:
compression_kwargs["savings_tags"] = savings_tags
+ if tool_names_by_call_id:
+ compression_kwargs["tool_names_by_call_id"] = tool_names_by_call_id
while True:
try:
result = self._compress_openai_responses_payload(
@@ -7883,6 +7890,43 @@ class OpenAIHandlerMixin:
body: dict[str, Any] = {}
current_response_input: list[dict[str, Any]] = []
current_response_template: dict[str, Any] = {}
+ # Codex sends only tool outputs on previous_response_id continuations.
+ # Retain resolved retrieval identities, never tool arguments or results,
+ # for this connection (including rejected/repeated continuations).
+ ws_tool_names_by_call_id: dict[str, str] = {}
+ ws_tool_context_exhausted = False
+
+ def _remember_ws_tool_call(item: Any) -> None:
+ nonlocal ws_tool_context_exhausted
+ if ws_tool_context_exhausted or not isinstance(item, dict):
+ return
+ if item.get("type") not in {"function_call", "custom_tool_call"}:
+ return
+ call_id = item.get("call_id")
+ name = item.get("name")
+ if not isinstance(call_id, str) or not call_id or not isinstance(name, str):
+ return
+ from headroom.config import is_tool_excluded, unwrap_tool_call_name
+
+ name = unwrap_tool_call_name(name, item.get("arguments") or item.get("input"))
+ if not is_tool_excluded(name, ("headroom_retrieve",)):
+ ws_tool_names_by_call_id.pop(call_id, None)
+ return
+ if (
+ call_id not in ws_tool_names_by_call_id
+ and len(ws_tool_names_by_call_id) >= _OPENAI_RESPONSES_TOOL_CONTEXT_LIMIT
+ ):
+ # Evicting an unconsumed identity would silently re-compress
+ # its original. Bound metadata and fail safe for this connection.
+ ws_tool_context_exhausted = True
+ logger.warning(
+ "[%s] WS retrieval context limit reached; "
+ "preserving tool outputs without compression for this connection",
+ request_id,
+ )
+ return
+ ws_tool_names_by_call_id[call_id] = name
+
tokens_saved = 0
# Session-scoped accumulator for tokens we *attempted* to
# compress (extracted units + schema). Drives the active-
@@ -8823,9 +8867,14 @@ class OpenAIHandlerMixin:
store_forced,
"chatgpt_store_false" if store_forced else "bypass_header",
)
- if not self.config.optimize:
+ if ws_tool_context_exhausted or not self.config.optimize:
+ passthrough_reason = (
+ "tool_context_limit"
+ if ws_tool_context_exhausted
+ else "optimize_disabled"
+ )
_log_ws_passthrough(
- "optimize_disabled",
+ passthrough_reason,
frame_index=frame_index,
raw_bytes=len(raw_after_store.encode("utf-8", errors="replace")),
frame_type="response.create",
@@ -8834,7 +8883,7 @@ class OpenAIHandlerMixin:
return (
raw_after_store,
store_forced,
- "chatgpt_store_false" if store_forced else "optimize_disabled",
+ "chatgpt_store_false" if store_forced else passthrough_reason,
)
frame_compression_elapsed_ms = 0.0
try:
@@ -8868,6 +8917,7 @@ class OpenAIHandlerMixin:
else COMPRESSION_TIMEOUT_SECONDS,
client=client,
savings_tags=frame_savings,
+ tool_names_by_call_id=dict(ws_tool_names_by_call_id),
)
for _timing_name, _timing_ms in frame_compression_timing.items():
_record_ws_compression_timing(_timing_name, _timing_ms)
@@ -9525,6 +9575,8 @@ class OpenAIHandlerMixin:
upstream_frame_index,
ws_last_upstream_frame_type,
)
+ if event_type == "response.output_item.done":
+ _remember_ws_tool_call(event.get("item"))
response = event.get("response")
completed_response_model = (
str(response.get("model") or "unknown")
diff --git a/tests/test_openai_codex_ws_lifecycle.py b/tests/test_openai_codex_ws_lifecycle.py
index 0d1fd56e5..f468183ed 100644
--- a/tests/test_openai_codex_ws_lifecycle.py
+++ b/tests/test_openai_codex_ws_lifecycle.py
@@ -343,6 +343,162 @@ class _FakeUpstream:
await asyncio.Event().wait()
+def _delta_compression_handler():
+ from types import MethodType
+
+ from headroom.transforms.content_router import (
+ CompressionStrategy,
+ ContentRouter,
+ RouterCompressionResult,
+ )
+
+ router = ContentRouter()
+
+ def compress(self, content, **kwargs):
+ return RouterCompressionResult(
+ original=content,
+ compressed="ordinary output compressed",
+ strategy_used=CompressionStrategy.KOMPRESS,
+ )
+
+ router.compress = MethodType(compress, router)
+ handler = _DummyOpenAIHandler()
+ handler.config.optimize = True
+ handler.openai_pipeline = SimpleNamespace(transforms=[router])
+ return handler
+
+
+async def _relay_delta_outputs(handler, calls, call_ids):
+ """Compact Codex wire fixture: the continuation omits its producing calls."""
+ output = " ".join(f"synthetic_original_{i}" for i in range(300))
+ deltas = [
+ {
+ "type": "response.create",
+ "response": {
+ "model": "gpt-5.4",
+ "previous_response_id": "resp_tools",
+ "input": [
+ {"type": "custom_tool_call_output", "call_id": call_id, "output": output}
+ ],
+ },
+ }
+ for call_id in call_ids
+ ]
+ completed = asyncio.Event()
+
+ class DeltaClient(_FakeWebSocket):
+ first = True
+
+ async def receive_text(self):
+ if not self.first:
+ await completed.wait()
+ self.first = False
+ return await super().receive_text()
+
+ async def send_text(self, text):
+ await super().send_text(text)
+ if json.loads(text).get("type") == "response.completed":
+ completed.set()
+
+ client = DeltaClient(frames=[_first_frame(), *(json.dumps(frame) for frame in deltas)])
+ upstream = _FakeUpstream(
+ [
+ json.dumps({"type": "response.created", "response": {"id": "resp_tools"}}),
+ *(json.dumps({"type": "response.output_item.done", "item": call}) for call in calls),
+ json.dumps({"type": "response.completed", "response": {"id": "resp_tools"}}),
+ ],
+ hold_after_events=True,
+ )
+ with patch.dict(sys.modules, {"websockets": _make_fake_websockets_module(upstream)}):
+ await asyncio.wait_for(handler.handle_openai_responses_ws(client), timeout=2.0)
+ forwarded = [json.loads(frame)["response"] for frame in upstream.sent[1:]]
+ return output, deltas, forwarded
+
+
+def _retrieval_call(call_id):
+ return {
+ "type": "custom_tool_call",
+ "call_id": call_id,
+ "name": "exec",
+ "input": 'const r = await tools.mcp__headroom__headroom_retrieve({hash: "fixture"});text(r);',
+ }
+
+
+async def test_ws_delta_retrieval_outputs_and_retries_stay_verbatim():
+ handler = _delta_compression_handler()
+ original, deltas, forwarded = await _relay_delta_outputs(
+ handler, [_retrieval_call("call_delta")], ["call_delta", "call_delta"]
+ )
+
+ assert len(forwarded) == 2
+ assert forwarded == [frame["response"] for frame in deltas]
+ assert all(frame["input"][0]["output"] == original for frame in forwarded)
+
+
+async def test_ws_delta_retrieval_old_compressor_signature_fails_open():
+ handler = _delta_compression_handler()
+ calls = 0
+
+ def old_compress(
+ payload,
+ *,
+ model,
+ request_id,
+ timing=None,
+ client=None,
+ savings_tags=None,
+ deadline_started_at=None,
+ ):
+ nonlocal calls
+ calls += 1
+ return {"model": model, "input": "legacy compressed"}, True, 5, ["text"], None, 10, 5, 10
+
+ handler._compress_openai_responses_payload = old_compress
+ original, deltas, forwarded = await _relay_delta_outputs(
+ handler, [_retrieval_call("call_old")], ["call_old", "call_old"]
+ )
+
+ assert calls == 1 # Only the first frame, before any retrieval identity exists.
+ assert forwarded == [frame["response"] for frame in deltas]
+ assert all(frame["input"][0]["output"] == original for frame in forwarded)
+
+
+async def test_ws_delta_retrieval_context_does_not_cross_connections():
+ handler = _delta_compression_handler()
+ await _relay_delta_outputs(handler, [_retrieval_call("reused_id")], ["reused_id"])
+ ordinary = {
+ "type": "custom_tool_call",
+ "call_id": "ordinary_id",
+ "name": "exec",
+ "input": 'const r = await tools.exec_command({cmd: "echo synthetic"});text(r);',
+ }
+ original, _deltas, forwarded = await _relay_delta_outputs(
+ handler, [ordinary], ["ordinary_id", "reused_id"]
+ )
+
+ assert len(forwarded) == 2
+ assert all(frame["input"][0]["output"] != original for frame in forwarded)
+
+
+async def test_ws_delta_tool_context_limit_preserves_untracked_outputs(monkeypatch, caplog):
+ monkeypatch.setattr(openai_module, "_OPENAI_RESPONSES_TOOL_CONTEXT_LIMIT", 1, raising=False)
+ handler = _delta_compression_handler()
+ original, deltas, forwarded = await _relay_delta_outputs(
+ handler,
+ [_retrieval_call("call_first"), _retrieval_call("call_overflow")],
+ ["call_first", "call_overflow"],
+ )
+
+ assert len(forwarded) == 2
+ assert forwarded == [frame["response"] for frame in deltas]
+ assert all(frame["input"][0]["output"] == original for frame in forwarded)
+ assert "WS retrieval context limit reached" in caplog.text
+
+
def _make_fake_websockets_module(
upstream: _FakeUpstream | None,
*,