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/responses): keep the Codex additional_tools carrier on the wire (#3194)
Tejas Chopra1617f839a197
diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.pyindex 51dfb527d..cb2f70766 100644--- a/headroom/proxy/handlers/openai.py+++ b/headroom/proxy/handlers/openai.py@@ -791,7 +791,12 @@ def _codex_additional_tools_lift_enabled() -> bool:)-def _lift_codex_additional_tools(payload: dict[str, Any], *, request_id: str | None = None) -> int:+def _lift_codex_additional_tools(+ payload: dict[str, Any],+ *,+ request_id: str | None = None,+ restore_plan: list[dict[str, Any]] | None = None,+) -> int:"""Lift Codex ``additional_tools`` input items into top-level ``tools``.Codex CLI 0.149.0 stopped sending a top-level ``tools`` array on@@ -804,7 +809,13 @@ def _lift_codex_additional_tools(payload: dict[str, Any], *, request_id: str | NMutates *payload* in place: concatenates the items' ``tools`` arrays into``payload["tools"]`` and drops the carrier items from ``input``. Returns- the number of lifted tool definitions (0 = no-op). No-op when the payload+ the number of lifted tool definitions (0 = no-op).++ This is an *internal* normalization only. The forwarded payload must keep+ the shape the client sent, so callers pass ``restore_plan`` and hand it to+ :func:`_restore_codex_additional_tools` before forwarding -- forwarding the+ lifted shape costs a stateful session its whole tool surface (the 0.36.3+ regression from #3186). No-op when the payloadalready carries top-level tools, so classic-encoding clients areuntouched and a future Codex reverting the change costs nothing. Theclassic top-level encoding is accepted upstream for these models --@@ -823,6 +834,7 @@ def _lift_codex_additional_tools(payload: dict[str, Any], *, request_id: str | Nreturn 0lifted: list[Any] = []kept: list[Any] = []+ plan: list[dict[str, Any]] = []for item in items:if (isinstance(item, dict)@@ -830,6 +842,16 @@ def _lift_codex_additional_tools(payload: dict[str, Any], *, request_id: str | Nand isinstance(item.get("tools"), list)and item["tools"]):+ # `kept_index` is the carrier's position among the items that+ # survive the lift, so the restore re-inserts it in the same+ # relative slot even when compression rewrites the transcript.+ plan.append(+ {+ "kept_index": len(kept),+ "item": {k: v for k, v in item.items() if k != "tools"},+ "tools": list(item["tools"]),+ }+ )lifted.extend(item["tools"])else:kept.append(item)@@ -837,6 +859,8 @@ def _lift_codex_additional_tools(payload: dict[str, Any], *, request_id: str | Nreturn 0payload["tools"] = liftedpayload["input"] = kept+ if restore_plan is not None:+ restore_plan.extend(plan)logger.info("[%s] Lifted %d Codex additional_tools definitions to top-level tools",request_id or "-",@@ -845,6 +869,91 @@ def _lift_codex_additional_tools(payload: dict[str, Any], *, request_id: str | Nreturn len(lifted)+def _restore_codex_additional_tools(+ payload: dict[str, Any],+ restore_plan: list[dict[str, Any]],+ *,+ request_id: str | None = None,+) -> int:+ """Undo :func:`_lift_codex_additional_tools`, keeping compaction's work.++ The lift exists so Headroom's tools consumers engage; it must not change+ what Codex sees on the wire. ``tools`` is a per-request parameter, while+ ``additional_tools`` is an ``input`` item and therefore part of the+ conversation transcript. A stateful session (Codex TUI/app-server over+ WebSocket) declares its tools once and relies on the transcript for every+ later turn, so forwarding the lifted shape leaves that transcript+ tool-less: turn one works, then shell/filesystem access vanishes for the+ rest of the session -- the 0.36.3 regression from #3186. Stateless HTTP+ hid it in review: every request re-sends the carrier, so the lift refires+ each turn and nothing is ever lost.++ Rewrites *payload* in place -- moves ``payload["tools"]`` (post-compaction)+ back into ``additional_tools`` carriers at their original positions and+ drops the top-level array. Returns the number of definitions restored.+ """+ if not isinstance(payload, dict) or not restore_plan:+ return 0+ items = payload.get("input")+ if not isinstance(items, list):+ return 0+ if any(+ isinstance(item, dict) and item.get("type") == "additional_tools" and item.get("tools")+ for item in items+ ):+ # Already in carrier form -- restoring again would duplicate the+ # definitions. Keeps the restore idempotent.+ return 0+ tools = payload.get("tools")+ if not isinstance(tools, list):+ tools = []++ original_total = sum(len(entry.get("tools") or []) for entry in restore_plan)+ if not tools:+ # A consumer emptied the array. Restoring the definitions as Codex+ # sent them is strictly safer than forwarding a tool-less payload.+ slices = [list(entry.get("tools") or []) for entry in restore_plan]+ elif len(tools) == original_total:+ slices = []+ offset = 0+ for entry in restore_plan:+ width = len(entry.get("tools") or [])+ slices.append(tools[offset : offset + width])+ offset += width+ else:+ # The definition count changed (deferral, injection), so the original+ # per-carrier split no longer maps. The whole set rides the first+ # carrier rather than being distributed on a stale boundary.+ slices = [list(tools)] + [[] for _ in restore_plan[1:]]++ restored_items = list(items)+ restored = 0+ shift = 0+ for entry, tool_slice in zip(restore_plan, slices):+ if not tool_slice:+ continue+ carrier = dict(entry.get("item") or {})+ carrier["type"] = "additional_tools"+ carrier["tools"] = tool_slice+ position = entry.get("kept_index")+ if not isinstance(position, int) or position < 0:+ position = len(restored_items)+ restored_items.insert(min(position + shift, len(restored_items)), carrier)+ shift += 1+ restored += len(tool_slice)++ if not restored:+ return 0+ payload["input"] = restored_items+ payload.pop("tools", None)+ logger.debug(+ "[%s] Restored %d Codex tool definitions to additional_tools",+ request_id or "-",+ restored,+ )+ return restored++def _allow_responses_memory_tools(is_chatgpt_auth: bool) -> bool:# Preserve the ChatGPT Codex route's existing store policy and memory-tool# exclusion while API Responses memory continuations stay stateless.@@ -2942,9 +3051,16 @@ class OpenAIHandlerMixin:# shaping/compression so every downstream tools consumer engages.# Runs once per pass, ahead of the executor closure, and never breaks# forwarding.+ _restore_plan: list[dict[str, Any]] = []try:- _lift_codex_additional_tools(payload, request_id=request_id)+ _lift_codex_additional_tools(+ payload,+ request_id=request_id,+ restore_plan=_restore_plan,+ )except Exception: # pragma: no cover - defensive; never break forwarding+ # The plan is deliberately kept: if the lift raised after mutating+ # the payload, the restore is what undoes it.logger.warning("[%s] additional_tools lift failed; continuing unlifted",request_id,@@ -3018,6 +3134,33 @@ class OpenAIHandlerMixin:_compress,timeout=timeout,)++ # Restore the carrier Codex sent the definitions in. The lift is an+ # internal normalization for the tools consumers; the forwarded shape+ # must match what the client sent, or a stateful session loses its+ # tool surface after the first turn (0.36.3 regression from #3186).+ if _restore_plan and result and isinstance(result[0], dict):+ try:+ if not _restore_codex_additional_tools(+ result[0],+ _restore_plan,+ request_id=request_id,+ ):+ # The lifted shape is about to go out: a stateful client+ # will lose its tools after this turn. Never silent.+ logger.warning(+ "[%s] additional_tools carrier could not be restored; "+ "forwarding lifted shape (set "+ "HEADROOM_CODEX_ADDITIONAL_TOOLS_LIFT=0 to opt out)",+ request_id,+ )+ except Exception: # pragma: no cover - defensive+ logger.warning(+ "[%s] additional_tools restore failed",+ request_id,+ exc_info=True,+ )+if len(result) == 8:return (*result, timing)return resultdiff --git a/tests/test_openai_responses_additional_tools.py b/tests/test_openai_responses_additional_tools.pyindex 3667c969d..1403a1565 100644--- a/tests/test_openai_responses_additional_tools.py+++ b/tests/test_openai_responses_additional_tools.py@@ -9,12 +9,16 @@ sees a tool-less request and records zero tool-schema savings.from __future__ import annotations+import asyncioimport copy+import jsonfrom typing import Anyfrom headroom.proxy.handlers.openai import (+ OpenAIHandlerMixin,_compact_openai_responses_tools,_lift_codex_additional_tools,+ _restore_codex_additional_tools,)@@ -148,3 +152,259 @@ def test_lifted_tools_reach_schema_compaction() -> None:assert after_bytes < before_bytes# Compaction preserves the invocation shape the model needs.assert [t["name"] for t in compacted["tools"]] == ["shell", "update_plan"]+++# ---------------------------------------------------------------------------+# Carrier restoration (0.36.3 regression from #3186)+#+# The lift is an internal normalization so the tools consumers engage. It must+# not change the forwarded wire shape: `tools` is a per-request parameter,+# while `additional_tools` is an `input` item and therefore part of the+# conversation transcript. Codex TUI/app-server over WebSocket declares its+# tools once and relies on the transcript for every later turn, so forwarding+# the lifted shape cost the session its whole tool surface after turn one --+# 0.36.3 regressed shell/filesystem access while 0.36.2 worked.+# ---------------------------------------------------------------------------+++def _handler(compress=None): # noqa: ANN001, ANN202+ """A bare mixin with the executor and compressor stubbed out."""+ handler = object.__new__(OpenAIHandlerMixin)++ async def _run_compression(fn, *, timeout): # noqa: ANN001, ANN202+ return fn()++ def _default_compress(payload, *, model, request_id, **kwargs): # noqa: ANN001, ANN202+ return (payload, True, 0, [], None, 0, 0, 0, {})++ handler._run_compression_in_executor = _run_compression+ handler._compress_openai_responses_payload = compress or _default_compress+ return handler+++def _forward(payload: dict[str, Any], compress=None) -> dict[str, Any]: # noqa: ANN001+ handler = _handler(compress)+ result = asyncio.run(+ handler._compress_openai_responses_payload_in_executor(+ payload,+ model="gpt-5.6-sol",+ request_id="req-carrier",+ )+ )+ return result[0]+++def test_lift_restore_round_trip_is_shape_preserving() -> None:+ payload = _codex_0149_payload()+ before = copy.deepcopy(payload)++ plan: list[dict[str, Any]] = []+ _lift_codex_additional_tools(payload, restore_plan=plan)+ _restore_codex_additional_tools(payload, plan)++ assert payload == before+++def test_compressor_sees_tools_but_forwarded_payload_does_not() -> None:+ """The whole point: consumers get top-level tools, the wire keeps the carrier."""+ seen: list[Any] = []++ def _compress(payload, *, model, request_id, **kwargs): # noqa: ANN001, ANN202+ seen.append(copy.deepcopy(payload.get("tools")))+ return (payload, True, 0, [], None, 0, 0, 0, {})++ payload = _codex_0149_payload()+ before = copy.deepcopy(payload)++ forwarded = _forward(payload, _compress)++ # The savings fix (#3185) still holds: compaction saw real tools.+ assert [t["name"] for t in seen[0]] == ["shell", "update_plan"]+ # The regression fix: the forwarded shape is what Codex sent.+ assert "tools" not in forwarded+ assert forwarded["input"] == before["input"]+++def test_stateful_second_turn_still_carries_tools() -> None:+ """Reproduces the 0.36.3 session: turn one worked, then tools vanished.++ A stateful client appends to the transcript it already sent. If Headroom+ forwards turn one without the carrier, the transcript the client builds+ turn two from has no tool definitions at all -- and turn two carries no+ top-level ``tools`` either, so the model is left with no tool surface.+ """+ forwarded_turn_1 = _forward(_codex_0149_payload())++ turn_2 = {+ "model": "gpt-5.6-sol",+ "input": [+ *forwarded_turn_1["input"],+ {+ "type": "message",+ "role": "user",+ "content": [{"type": "input_text", "text": "now run pwd again"}],+ },+ ],+ }++ # Turn two declares no tools of its own; everything rides the transcript.+ assert "tools" not in turn_2+ assert any(item.get("type") == "additional_tools" for item in turn_2["input"]), (+ "turn two lost every tool definition -- this is the 0.36.3 regression"+ )++ # And turn two survives its own trip through the proxy with tools intact.+ forwarded_turn_2 = _forward(turn_2)+ carriers = [i for i in forwarded_turn_2["input"] if i.get("type") == "additional_tools"]+ assert [t["name"] for c in carriers for t in c["tools"]] == ["shell", "update_plan"]+++def test_restore_keeps_the_compacted_schemas() -> None:+ """Restoration returns compaction's output, not the pre-compaction copy."""+ payload = _codex_0149_payload()+ plan: list[dict[str, Any]] = []+ _lift_codex_additional_tools(payload, restore_plan=plan)++ compacted, modified, _before, _after = _compact_openai_responses_tools(payload)+ assert modified, "fixture should be compactable"+ restored = _restore_codex_additional_tools(compacted, plan)++ assert restored == 2+ carrier = next(i for i in compacted["input"] if i.get("type") == "additional_tools")+ assert [t["name"] for t in carrier["tools"]] == ["shell", "update_plan"]+ # The verbose description is gone -- the savings survived the round trip.+ assert len(json.dumps(carrier["tools"])) < len(+ json.dumps(_codex_0149_payload()["input"][1]["tools"])+ )+++def test_restore_puts_the_carrier_back_in_position() -> None:+ payload = _codex_0149_payload()+ payload["input"].append(+ {"type": "message", "role": "user", "content": [{"type": "input_text", "text": "tail"}]}+ )+ before_types = [i["type"] for i in payload["input"]]++ plan: list[dict[str, Any]] = []+ _lift_codex_additional_tools(payload, restore_plan=plan)+ _restore_codex_additional_tools(payload, plan)++ assert [i["type"] for i in payload["input"]] == before_types+++def test_restore_handles_multiple_carriers() -> None:+ payload = _codex_0149_payload()+ payload["input"].append({"type": "additional_tools", "tools": [_verbose_tool("view_image")]})+ before = copy.deepcopy(payload)++ plan: list[dict[str, Any]] = []+ assert _lift_codex_additional_tools(payload, restore_plan=plan) == 3+ assert _restore_codex_additional_tools(payload, plan) == 3++ assert payload == before+++def test_restore_folds_into_first_carrier_when_the_count_changes() -> None:+ """Deferral/injection rewrites the array; the split no longer maps."""+ payload = _codex_0149_payload()+ payload["input"].append({"type": "additional_tools", "tools": [_verbose_tool("view_image")]})+ plan: list[dict[str, Any]] = []+ _lift_codex_additional_tools(payload, restore_plan=plan)++ payload["tools"] = [_verbose_tool("tool_search")]+ assert _restore_codex_additional_tools(payload, plan) == 1++ carriers = [i for i in payload["input"] if i.get("type") == "additional_tools"]+ assert len(carriers) == 1+ assert [t["name"] for t in carriers[0]["tools"]] == ["tool_search"]+ assert "tools" not in payload+++def test_restore_recovers_the_originals_when_the_array_is_emptied() -> None:+ """A tool-less forward is never the safer outcome."""+ payload = _codex_0149_payload()+ plan: list[dict[str, Any]] = []+ _lift_codex_additional_tools(payload, restore_plan=plan)++ payload["tools"] = []+ assert _restore_codex_additional_tools(payload, plan) == 2++ carrier = next(i for i in payload["input"] if i.get("type") == "additional_tools")+ assert [t["name"] for t in carrier["tools"]] == ["shell", "update_plan"]+++def test_restore_preserves_other_carrier_keys() -> None:+ payload = _codex_0149_payload()+ payload["input"][1]["id"] = "carrier_abc"+ before = copy.deepcopy(payload)++ plan: list[dict[str, Any]] = []+ _lift_codex_additional_tools(payload, restore_plan=plan)+ _restore_codex_additional_tools(payload, plan)++ assert payload == before+++def test_restore_is_a_noop_without_a_plan() -> None:+ payload = _codex_0149_payload()+ before = copy.deepcopy(payload)++ assert _restore_codex_additional_tools(payload, []) == 0+ assert payload == before+ assert _restore_codex_additional_tools("not-a-dict", [{"tools": []}]) == 0 # type: ignore[arg-type]+++def test_kill_switch_leaves_the_payload_completely_untouched(monkeypatch) -> None:+ monkeypatch.setenv("HEADROOM_CODEX_ADDITIONAL_TOOLS_LIFT", "0")+ payload = _codex_0149_payload()+ before = copy.deepcopy(payload)++ forwarded = _forward(payload)++ assert forwarded["input"] == before["input"]+ assert "tools" not in forwarded+++def test_classic_top_level_clients_are_untouched_by_the_restore() -> None:+ """A non-Codex payload never enters the lift, so it never enters the restore."""+ payload = {+ "model": "gpt-5.6-sol",+ "tools": [_verbose_tool("shell")],+ "input": [+ {"type": "message", "role": "user", "content": [{"type": "input_text", "text": "hi"}]}+ ],+ }+ before = copy.deepcopy(payload)++ forwarded = _forward(payload)++ assert forwarded["tools"] == before["tools"]+ assert forwarded["input"] == before["input"]+++def test_unrestorable_payload_warns_instead_of_failing_silently(caplog) -> None:+ """If the carrier cannot go back, say so -- a stateful client will lose tools."""++ def _mangle(payload, *, model, request_id, **kwargs): # noqa: ANN001, ANN202+ payload["input"] = "collapsed-to-a-string"+ return (payload, True, 0, [], None, 0, 0, 0, {})++ with caplog.at_level("WARNING", logger="headroom.proxy"):+ forwarded = _forward(_codex_0149_payload(), _mangle)++ assert any("could not be restored" in message for message in caplog.messages)+ # Degraded, not broken: this turn still carries its tools.+ assert [t["name"] for t in forwarded["tools"]] == ["shell", "update_plan"]+++def test_restore_is_idempotent() -> None:+ """A second restore must not duplicate the definitions."""+ payload = _codex_0149_payload()+ before = copy.deepcopy(payload)++ plan: list[dict[str, Any]] = []+ _lift_codex_additional_tools(payload, restore_plan=plan)+ assert _restore_codex_additional_tools(payload, plan) == 2+ assert _restore_codex_additional_tools(payload, plan) == 0++ assert payload == before