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 retrieval outputs across Codex WS deltas (#4574)
Jermaine Sizemore682bf73f48bb
diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.pyindex 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_tokenslogger = 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 Truereturn 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_idwhile 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.0try:@@ -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.pyindex 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,*,