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
feat(proxy): accept the OpenAI Responses shape on the gateway turn (#3661)
Tejas Choprabe00a798c344
diff --git a/headroom/ccr/tool_injection.py b/headroom/ccr/tool_injection.pyindex 0ec9cf21e..b4933610b 100644--- a/headroom/ccr/tool_injection.py+++ b/headroom/ccr/tool_injection.py@@ -97,6 +97,35 @@ def create_ccr_tool_definition(},}+ elif provider == "openai_responses":+ # Responses API: the same function, declared flat. `name` and+ # `parameters` sit directly on the tool rather than nested under+ # "function" as chat completions wants, and the nested shape is+ # rejected -- so falling through to `openai_definition` here would+ # inject a tool the provider refuses, on exactly the turns where+ # compression markers made the tool necessary.+ return {+ "type": "function",+ "name": CCR_TOOL_NAME,+ "description": (+ "Retrieve original uncompressed content that was compressed to save tokens. "+ "Use this when you need more data than what's shown in compressed tool results. "+ "The hash is provided in compression markers like [N items compressed... hash=abc123]."+ ),+ "parameters": {+ "type": "object",+ "properties": {+ "hash": {+ "type": "string",+ "description": (+ "Hash key from the compression marker (e.g., 'abc123' from hash=abc123)"+ ),+ },+ },+ "required": ["hash"],+ },+ }+elif provider == "google":# Google/Gemini formatreturn {diff --git a/headroom/proxy/gateway_extension.py b/headroom/proxy/gateway_extension.pyindex 1bbac9cd9..90c18ddf0 100644--- a/headroom/proxy/gateway_extension.py+++ b/headroom/proxy/gateway_extension.py@@ -28,6 +28,7 @@ from headroom.proxy.compress_turn import (register_compress_turn_extension,registered_compress_turn_extensions,)+from headroom.proxy.gateway_responses import carries_viewfrom headroom.proxy.gateway_turn import (OBLIGATION_RELAY_USAGE,GatewayCapabilities,@@ -80,6 +81,10 @@ class GatewayTurn:self.caps = capsself.client = clientself.provider = provider_for_model(str(body.get("model") or ""))+ # The wire shape is a property of the body, not of the model name, and+ # it is fixed for the life of the turn: the response half has to write+ # a re-drive in the same shape the request half read.+ self.responses_shape = carries_view(body)self.model_name = str(body.get("model") or "")self.tags: dict[str, Any] = {}self._transformer: RequestTransformer | None = None@@ -158,6 +163,7 @@ class GatewayTurn:caps=self.caps,mode=mode,ccr_hashes=ccr_hashes,+ responses_shape=self.responses_shape,)transforms = list(transforms_applied or ()) + list(result.transforms)# Gateway fields are built BEFORE the outcome: output shaping runs on@@ -208,11 +214,16 @@ class GatewayTurn:if provider_body.get("tools") is not None:provider_body["tools"] = toolstransforms.append("cache_breakpoint_budget")- # I-BODY: top-level `messages` and `body.messages` are one list.+ # I-BODY: top-level `messages` and `body.messages` are one list --+ # `body.messages` is authoritative because the cache-breakpoint guard+ # above may have replaced it. A Responses body has no `body.messages`+ # at all (its transcript went back into `input`), so the top-level+ # field falls back to the list this turn actually transformed: the two+ # still describe the same content, which is what the invariant is for.return FinishedTurn(fields=self._fields,transforms=transforms,- messages=self._fields["body"]["messages"],+ messages=self._fields["body"].get("messages", messages),)def commit(@@ -242,6 +253,7 @@ class GatewayTurn:tags=self.tags,client=self.client,ccr_armed=self._ccr_armed,+ wire_shape="openai_responses" if self.responses_shape else None,)return deferdiff --git a/headroom/proxy/gateway_responses.py b/headroom/proxy/gateway_responses.pynew file mode 100644index 000000000..260a38447--- /dev/null+++ b/headroom/proxy/gateway_responses.py@@ -0,0 +1,355 @@+"""The OpenAI Responses wire shape on the gateway turn.++``POST /v1/compress`` grew up on two shapes that both carry a ``messages``+list: Anthropic Messages and OpenAI Chat Completions. Codex speaks the third+one — OpenAI Responses — where the transcript is ``input`` (a list of typed+items) and the system prompt is ``instructions``. That body reached the+endpoint and was rejected outright: ``Missing required field: messages``.++The tempting fix is to translate Responses into chat messages, compress, and+translate back. It is the wrong fix, and this module deliberately does not do+it. A Responses transcript carries fields that are opaque to us and that the+provider requires back byte-for-byte — ``reasoning.encrypted_content`` above+all, plus ``call_id`` pairing and Codex's own+``internal_chat_message_metadata_passthrough``. A translation round trip is+lossy by construction, and the loss is silent: the request still looks valid+and the provider rejects it, or worse, accepts it with the model's reasoning+chain quietly severed. ``_responses_input_to_waste_messages`` in the OpenAI+handler carries the same warning for the same reason — it is telemetry-only,+"never used as a compression input".++So this module builds a *view*, not a translation:++* Every compressible text slot in the body becomes one chat-shaped pseudo+ message. One slot, one message — never joined, so putting the text back+ never has to guess how to split it again.+* Every item that is not a text slot — ``reasoning`` above all — produces no+ message at all. It is not shown to the compressor, cannot be rewritten by+ it, and survives in the outgoing body exactly as it arrived.+* A call item's input (``custom_tool_call.input``, ``function_call.arguments``)+ *is* a text slot: 9.2% of transcript bytes across 51 real Codex sessions,+ and resent on every turn like everything else. ``arguments`` is a JSON+ document the provider parses, so it carries one extra condition on the way+ back (``_json_safe``).+* Putting it back is by position: view message *i* owns slot *i*. The slots+ are rebuilt from the original ``input`` rather than carried along, because+ ``build_view`` is a pure function of the body — recomputing is cheaper than+ threading state through the turn and cannot go stale.++If the pipeline ever hands back a list that does not line up with the slots,+``apply_view`` returns the body unchanged rather than guessing. Compression is+an optimisation; a mangled transcript is a broken request.+"""++from __future__ import annotations++import copy+import json+from dataclasses import dataclass+from typing import Any++#: ``*_call_output`` items: a tool's result coming back into the transcript.+#: This is where nearly all the compressible bulk in an agent session lives.+OUTPUT_ITEM_TYPES: frozenset[str] = frozenset(+ {+ "function_call_output",+ "custom_tool_call_output",+ "local_shell_call_output",+ "apply_patch_call_output",+ }+)++#: Call items, and the field carrying what the model passed to the tool.+#: Measured over 51 real Codex sessions these are 9.2% of transcript bytes --+#: worth taking, but they are not tool *output* and the two differ in kind:+#: output is data the tool produced, while this is what the model said. It is+#: still resent on every turn, and ``custom_tool_call.input`` in particular+#: carries whole scripts and patches.+#:+#: ``function_call.arguments`` is a JSON string the provider parses, so it is+#: guarded separately on the way back (see ``_json_safe``); it is also only+#: 0.3% of bytes, and real ones have been seen carrying encrypted payloads,+#: so very little is lost when the guard refuses.+CALL_INPUT_FIELDS: dict[str, str] = {+ "custom_tool_call": "input",+ "local_shell_call": "input",+ "apply_patch_call": "input",+ "function_call": "arguments",+}++#: Content part types that hold plain text we may rewrite. Responses uses+#: ``input_text`` on the way in and ``output_text`` on the way out; both appear+#: in a resent transcript.+TEXT_PART_TYPES: frozenset[str] = frozenset({"input_text", "output_text", "text"})+++#: Where a piece of text lived, so it can be put back.+#: ``kind`` is one of:+#: ``instructions`` — the top-level ``instructions`` string+#: ``content`` — ``input[i]["content"][j]["text"]``+#: ``content_str`` — ``input[i]["content"]`` held a bare string+#: ``output`` — ``input[i]["output"][j]["text"]``+#: ``output_str`` — ``input[i]["output"]`` held a bare string+#: ``input_str`` — the whole ``input`` was a bare string+#: ``call`` — ``input[i][<the item's call-input field>]``+@dataclass(frozen=True)+class Slot:+ kind: str+ item: int = -1+ part: int = -1+ field: str = ""+++@dataclass+class ResponsesView:+ """A chat-shaped read of a Responses body, plus how to undo it."""++ messages: list[dict[str, Any]]+ slots: list[Slot]++ def __len__(self) -> int:+ return len(self.slots)+++def is_responses_body(body: Any) -> bool:+ """True for a Responses-shaped request body.++ ``input`` is the discriminator and ``messages`` is the veto: a body+ carrying both is a chat body that happens to have an ``input`` field, and+ the chat path already knows what to do with it.+ """+ if not isinstance(body, dict):+ return False+ return "input" in body and "messages" not in body+++#: Set on the body when a view is attached, so rebuilding the provider body+#: knows to fold it back rather than having to re-derive the wire shape. It is+#: a Headroom control key and is stripped like the rest of them, so it never+#: reaches a provider.+#:+#: Sniffing for ``input`` instead looks equivalent and is not: by then the view+#: is sitting under ``messages``, so the arrival-time predicate cannot be+#: reused, and a chat body that merely happens to carry an ``input`` field+#: would be mistaken for a Responses turn and have its ``messages`` dropped.+#: The marker says what actually happened rather than inferring it.+VIEW_MARKER = "_headroom_responses_view"+++def mark_view(body: dict[str, Any]) -> None:+ body[VIEW_MARKER] = True+++def carries_view(body: Any) -> bool:+ """True when :func:`mark_view` attached a view to this body."""+ return isinstance(body, dict) and body.get(VIEW_MARKER) is True+++def _part_text(part: Any) -> str | None:+ if not isinstance(part, dict):+ return None+ if part.get("type") not in TEXT_PART_TYPES:+ return None+ text = part.get("text")+ return text if isinstance(text, str) else None+++def build_view(body: dict[str, Any]) -> ResponsesView:+ """A chat-shaped view of every text slot in *body*, in document order.++ Pure: the same body always yields the same slots, which is what lets+ ``apply_view`` rebuild them instead of being handed them.+ """+ messages: list[dict[str, Any]] = []+ slots: list[Slot] = []++ def emit(role: str, text: str, slot: Slot, *, tool_call_id: str | None = None) -> None:+ message: dict[str, Any] = {"role": role, "content": text}+ if tool_call_id:+ # The pipeline keys tool results off this; without it a fold that+ # groups by call would treat every result as the same call.+ message["tool_call_id"] = tool_call_id+ messages.append(message)+ slots.append(slot)++ instructions = body.get("instructions")+ if isinstance(instructions, str) and instructions:+ emit("system", instructions, Slot("instructions"))++ data = body.get("input")+ if isinstance(data, str):+ if data:+ emit("user", data, Slot("input_str"))+ return ResponsesView(messages, slots)+ if not isinstance(data, list):+ return ResponsesView(messages, slots)++ for index, item in enumerate(data):+ if not isinstance(item, dict):+ continue+ kind = item.get("type")++ if kind in OUTPUT_ITEM_TYPES:+ call_id = item.get("call_id")+ call_id = call_id if isinstance(call_id, str) else None+ output = item.get("output")+ if isinstance(output, str):+ if output:+ emit("tool", output, Slot("output_str", index), tool_call_id=call_id)+ elif isinstance(output, list):+ for part_index, part in enumerate(output):+ text = _part_text(part)+ if text:+ emit(+ "tool",+ text,+ Slot("output", index, part_index),+ tool_call_id=call_id,+ )+ continue++ call_field = CALL_INPUT_FIELDS.get(kind or "")+ if call_field is not None:+ value = item.get(call_field)+ if isinstance(value, str) and value:+ call_id = item.get("call_id")+ emit(+ "assistant",+ value,+ Slot("call", index, field=call_field),+ tool_call_id=call_id if isinstance(call_id, str) else None,+ )+ continue++ # A `message` item. Anything else -- `reasoning` above all -- is opaque+ # on purpose and contributes no slot.+ if kind is not None and kind != "message":+ continue++ role = item.get("role")+ role = role if isinstance(role, str) and role else "user"+ content = item.get("content")+ if isinstance(content, str):+ if content:+ emit(role, content, Slot("content_str", index))+ elif isinstance(content, list):+ for part_index, part in enumerate(content):+ text = _part_text(part)+ if text:+ emit(role, text, Slot("content", index, part_index))++ return ResponsesView(messages, slots)+++def _json_safe(original: Any, replacement: str) -> bool:+ """May *replacement* stand in for *original* in a call-input field?++ ``function_call.arguments`` is a JSON document the provider parses to+ dispatch the call. A compressor works on text and has no reason to emit+ valid JSON, so shortening one would usually turn a working request into a+ parse error at the provider -- the exact failure this module exists to+ avoid. When the original parses as JSON the replacement must too, or the+ field keeps what it had.++ A field that was never JSON (``custom_tool_call.input`` holds shell+ commands and patches) has nothing to protect and passes straight through.+ """+ if not isinstance(original, str):+ return False+ try:+ json.loads(original)+ except (ValueError, TypeError):+ return True+ try:+ json.loads(replacement)+ except (ValueError, TypeError):+ return False+ return True+++def _message_text(message: Any) -> str | None:+ """The text the pipeline left in a view message.++ It may hand back a bare string or a content list, depending on which+ stage last touched it, so both are accepted.+ """+ if not isinstance(message, dict):+ return None+ content = message.get("content")+ if isinstance(content, str):+ return content+ if isinstance(content, list):+ parts = [t for t in (_part_text(p) for p in content) if t is not None]+ if parts:+ return "\n".join(parts)+ return ""+ return None+++def apply_view(+ body: dict[str, Any],+ messages: list[dict[str, Any]],+) -> tuple[dict[str, Any], bool]:+ """Write the view's text back into a copy of *body*.++ Returns ``(body, applied)``. ``applied`` is False when the messages do not+ line up with the slots rebuilt from *body*, in which case the body comes+ back untouched: a transcript we cannot map confidently is one we must not+ rewrite.+ """+ view = build_view(body)+ if len(messages) != len(view.slots):+ return body, False++ out = copy.deepcopy(body)+ data = out.get("input")+ changed = False++ for message, slot in zip(messages, view.slots):+ text = _message_text(message)+ if text is None:+ continue++ if slot.kind == "instructions":+ if out.get("instructions") != text:+ out["instructions"] = text+ changed = True+ continue++ if slot.kind == "input_str":+ if out.get("input") != text:+ out["input"] = text+ changed = True+ continue++ if not isinstance(data, list) or not (0 <= slot.item < len(data)):+ continue+ item = data[slot.item]+ if not isinstance(item, dict):+ continue++ if slot.kind == "call":+ if not _json_safe(item.get(slot.field), text):+ continue+ if item.get(slot.field) != text:+ item[slot.field] = text+ changed = True+ continue++ if slot.kind in ("content_str", "output_str"):+ field = "content" if slot.kind == "content_str" else "output"+ if item.get(field) != text:+ item[field] = text+ changed = True+ continue++ field = "content" if slot.kind == "content" else "output"+ parts = item.get(field)+ if not isinstance(parts, list) or not (0 <= slot.part < len(parts)):+ continue+ part = parts[slot.part]+ if isinstance(part, dict) and part.get("text") != text:+ part["text"] = text+ changed = True++ return out, changeddiff --git a/headroom/proxy/gateway_turn.py b/headroom/proxy/gateway_turn.pyindex 851a03cae..3d7e92d52 100644--- a/headroom/proxy/gateway_turn.py+++ b/headroom/proxy/gateway_turn.py@@ -49,6 +49,7 @@ from collections.abc import Callablefrom dataclasses import dataclass, fieldfrom typing import Any+from headroom.proxy.gateway_responses import VIEW_MARKER as GATEWAY_RESPONSES_VIEW_MARKERfrom headroom.proxy.outcome import RequestOutcomefrom headroom.proxy.turn_hooks import (TurnContext,@@ -61,7 +62,9 @@ from headroom.proxy.turn_hooks import (logger = logging.getLogger(__name__)# Keys that steer Headroom itself and must never reach the provider.-BODY_CONTROL_KEYS: frozenset[str] = frozenset({"config", "gateway", "token_budget"})+BODY_CONTROL_KEYS: frozenset[str] = frozenset(+ {"config", "gateway", "token_budget", GATEWAY_RESPONSES_VIEW_MARKER}+)OBLIGATION_REDRIVE = "redrive"OBLIGATION_RELAY_USAGE = "relay_usage"@@ -517,6 +520,21 @@ class PendingTurn:# config.mode="ccr" with markers inserted and re-drive allowed: the# response half answers headroom_retrieve calls itself (see arm_ccr_redrive).ccr_armed: bool = False+ # The wire shape this turn arrived in, when it is not the one `provider`+ # implies: "openai_responses" for a Codex body. Deliberately separate from+ # `provider`, which picks pricing, tokenizer and the upstream the gateway+ # is advised to call -- all three want "openai" for a Responses turn while+ # the tool-call shape and the re-drive body want "openai_responses".+ wire_shape: str | None = None++ @property+ def tool_call_provider(self) -> str:+ """The shape the CCR helpers read and write tool calls in."""+ return self.wire_shape or self.provider++ @property+ def responses_shape(self) -> bool:+ return self.wire_shape == "openai_responses"@propertydef hooks_armed(self) -> bool:@@ -929,6 +947,7 @@ def arm_ccr_redrive(caps: GatewayCapabilities,mode: str | None,ccr_hashes: list[str],+ responses_shape: bool = False,) -> bool:"""``config.mode="ccr"`` on the gateway contract: inject ``headroom_retrieve``and make the response half answer it.@@ -955,7 +974,9 @@ def arm_ccr_redrive(for t in tools)if not present:- tools.append(create_ccr_tool_definition(provider))+ tools.append(+ create_ccr_tool_definition("openai_responses" if responses_shape else provider)+ )result.transforms.append("ccr_tool_injected")result.tools = toolsif result.ctx is not None:@@ -979,7 +1000,7 @@ def make_response_runner(proxy: Any, turn: PendingTurn) -> Callable[..., Any]:handler = getattr(proxy, "ccr_response_handler", None)if turn.ccr_armed and handler is not None:try:- if handler.has_ccr_tool_calls(current, turn.provider):+ if handler.has_ccr_tool_calls(current, turn.tool_call_provider):async def api_call_fn(messages: list[dict[str, Any]], tools: Any) -> Any:# Mirrors the chat path's continuation closure: the@@ -989,7 +1010,11 @@ def make_response_runner(proxy: Any, turn: PendingTurn) -> Callable[..., Any]:return await call_model(messages)current = await handler.handle_response(- current, ctx.messages, ctx.tools, api_call_fn, provider=turn.provider+ current,+ ctx.messages,+ ctx.tools,+ api_call_fn,+ provider=turn.tool_call_provider,)except asyncio.CancelledError:raise@@ -1006,9 +1031,38 @@ def build_provider_body(tools: Any,) -> dict[str, Any]:"""The complete provider request: every pass-through field, final- ``messages`` and ``tools``; never the Headroom control keys."""+ ``messages`` and ``tools``; never the Headroom control keys.++ A Responses body (Codex) reached the handler as ``input`` and was given a+ chat-shaped view under ``messages`` so the pipeline could work on it. Here+ that goes back: the compressed text is written into ``input`` and the view+ is dropped, so the gateway forwards the shape its client actually sent. If+ the view cannot be mapped back confidently the original ``input`` is+ forwarded uncompressed -- a smaller request is worth nothing next to a+ transcript the provider will reject.+ """+ from headroom.proxy.gateway_responses import apply_view as apply_responses_view+ from headroom.proxy.gateway_responses import carries_view, is_responses_body+out = {k: v for k, v in body.items() if k not in BODY_CONTROL_KEYS}- out["messages"] = messages+ if carries_view(body):+ out, applied = apply_responses_view(out, messages)+ out.pop("messages", None)+ if not applied and messages:+ # The transcript goes out as it arrived while the answer's+ # `tokens_after` says otherwise, so say so once rather than let a+ # gateway quietly report a saving that was not taken.+ logger.warning(+ "gateway turn: Responses view did not map back; forwarding the original input"+ )+ elif is_responses_body(out):+ # A Responses body that never got a view: the bypass header returns+ # before one is built. Adding `messages` here is a guaranteed 400+ # ("Unsupported parameter: 'messages'"), so the safest path in the+ # handler would have been the one that broke every Codex request.+ pass+ else:+ out["messages"] = messagesif tools is not None:out["tools"] = toolsreturn out@@ -1186,6 +1240,7 @@ def register_pending_turn(tags: dict[str, Any],client: str | None,ccr_armed: bool = False,+ wire_shape: str | None = None,) -> PendingTurn | None:"""Register the turn when there is something to wait for; ``None`` otherwise."""registry = getattr(proxy, "gateway_turns", None)@@ -1208,6 +1263,7 @@ def register_pending_turn(tags=tags,client=client,ccr_armed=ccr_armed,+ wire_shape=wire_shape,)registry.register(turn)return turn@@ -1348,7 +1404,23 @@ def _redrive_payload(turn: PendingTurn, step: Step) -> dict[str, Any]:its (possibly reloaded) tools, everything else exactly as the gateway sent."""redrive_body = dict(turn.body)- redrive_body["messages"] = step.messages+ if turn.responses_shape:+ # `turn.body` is the provider body: a Responses turn's transcript lives+ # in `input`, and writing `messages` beside it -- even a null one --+ # hands the gateway the shape the provider rejects. Fold the hook's+ # messages back the way the request half did, and when a step carries+ # none, leave the transcript exactly as it is.+ if step.messages is not None:+ from headroom.proxy.gateway_responses import apply_view as apply_responses_view++ redrive_body, applied = apply_responses_view(redrive_body, step.messages)+ if not applied and step.messages:+ logger.warning(+ "gateway turn %s: re-drive view did not map back; sending the original input",+ turn.turn_id,+ )+ else:+ redrive_body["messages"] = step.messagesif step.tools is not None:redrive_body["tools"] = step.toolsreturn {diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.pyindex cb7078e54..15f2d545e 100644--- a/headroom/proxy/handlers/openai.py+++ b/headroom/proxy/handlers/openai.py@@ -9727,6 +9727,9 @@ class OpenAIHandlerMixin:# outcome (`commit`). With none claiming it — legacy mode — nothing# below this comment changes behaviour.from headroom.proxy.compress_turn import CompressTurnError, begin_compress_turn+ from headroom.proxy.gateway_responses import build_view as build_responses_view+ from headroom.proxy.gateway_responses import is_responses_body+ from headroom.proxy.gateway_responses import mark_view as mark_responses_viewfrom headroom.proxy.helpers import _read_request_jsondef _gateway_invalid(e: CompressTurnError) -> JSONResponse:@@ -9785,6 +9788,15 @@ class OpenAIHandlerMixin:},)+ # A Responses body (Codex) carries `input`, not `messages`. Give the+ # pipeline a chat-shaped view of its text slots and leave the original+ # `input` in place: `build_provider_body` rebuilds the same view to put+ # the compressed text back, so nothing outside these two points needs+ # to know which wire shape arrived. See `gateway_responses`.+ if is_responses_body(body):+ body["messages"] = build_responses_view(body).messages+ mark_responses_view(body)+messages = body.get("messages")model = body.get("model")@@ -9794,7 +9806,7 @@ class OpenAIHandlerMixin:content={"error": {"type": "invalid_request",- "message": "Missing required field: messages",+ "message": "Missing required field: messages or input",}},)diff --git a/tests/gateway/test_responses_shape.py b/tests/gateway/test_responses_shape.pynew file mode 100644index 000000000..2dfab4214--- /dev/null+++ b/tests/gateway/test_responses_shape.py@@ -0,0 +1,384 @@+"""The OpenAI Responses wire shape on ``/v1/compress``.++Codex sends ``input``/``instructions``, not ``messages``. Before this, the+endpoint answered ``400 Missing required field: messages`` and a gateway in+front of Codex failed open on every turn.++The tests that matter here are the ones about what must NOT change. A+Responses transcript carries fields the provider hands back to itself --+``reasoning.encrypted_content`` above all -- and a compressor that rewrites or+reorders them produces a request that is smaller and rejected. Round-trip+fidelity is the feature; the token saving is the easy part.+"""++from __future__ import annotations++import copy++from headroom.proxy.gateway_responses import (+ VIEW_MARKER,+ apply_view,+ build_view,+ carries_view,+ is_responses_body,+ mark_view,+)+from headroom.proxy.gateway_turn import build_provider_body++ENCRYPTED = "gAAAAABqmk3crgbgbbcsDuoytKItfYE_AeLFYB0cl2Ikew"+++def codex_body() -> dict:+ """A Responses body with one of each item type Codex actually sends."""+ return {+ "model": "gpt-5-codex",+ "instructions": "You are Codex.",+ "input": [+ {+ "type": "message",+ "id": "msg_1",+ "role": "developer",+ "content": [{"type": "input_text", "text": "project instructions"}],+ "internal_chat_message_metadata_passthrough": {"opaque": True},+ },+ {+ "type": "message",+ "id": "msg_2",+ "role": "user",+ "content": [{"type": "input_text", "text": "list the files"}],+ },+ {+ "type": "reasoning",+ "id": "rs_1",+ "summary": [],+ "encrypted_content": ENCRYPTED,+ },+ {+ "type": "custom_tool_call",+ "id": "ctc_1",+ "call_id": "call_abc",+ "name": "shell",+ "input": "ls -R",+ "status": "completed",+ },+ {+ "type": "custom_tool_call_output",+ "id": "ctco_1",+ "call_id": "call_abc",+ "output": [{"type": "input_text", "text": "a.py\nb.py\n" * 200}],+ },+ ],+ }+++def test_a_responses_body_is_recognised_and_a_chat_body_is_not():+ assert is_responses_body(codex_body())+ assert not is_responses_body({"model": "gpt-4o", "messages": []})+++def test_a_chat_body_that_happens_to_carry_input_stays_on_the_chat_path():+ """``messages`` is the veto, not a tiebreak.++ Sniffing for ``input`` alone once cost this path a chat body's entire+ ``messages`` list: it was classified as Responses on the way out and the+ transcript was dropped.+ """+ body = {"model": "gpt-4o", "messages": [{"role": "user", "content": "hi"}], "input": "stray"}+ assert not is_responses_body(body)+ assert not carries_view(body)++ out = build_provider_body(body, body["messages"], None)+ assert out["messages"] == body["messages"]+ assert out["input"] == "stray"+++def test_every_text_slot_becomes_exactly_one_view_message():+ view = build_view(codex_body())+ # instructions + 2 message items + the call's input + the call's output.+ # Only `reasoning` contributes nothing.+ assert len(view.messages) == 5+ assert [m["role"] for m in view.messages] == [+ "system",+ "developer",+ "user",+ "assistant",+ "tool",+ ]+ assert view.messages[-2]["content"] == "ls -R"+ assert view.messages[-1]["tool_call_id"] == "call_abc"+++def test_reasoning_is_never_shown_to_the_compressor():+ """What the compressor cannot see, it cannot corrupt.++ Reasoning is the one item that must never reach it: the provider hands+ ``encrypted_content`` back to itself and a single rewritten byte severs the+ model's own chain of thought.+ """+ view = build_view(codex_body())+ blob = "\n".join(str(m["content"]) for m in view.messages)+ assert ENCRYPTED not in blob+++def test_an_untouched_view_round_trips_to_an_identical_body():+ body = codex_body()+ view = build_view(body)+ out, changed = apply_view(body, view.messages)+ assert changed is False+ assert out == body+++def test_a_rewrite_reaches_the_text_and_nothing_else():+ body = codex_body()+ view = build_view(body)+ rewritten = [dict(m, content="SHORTER") for m in view.messages]+ out, changed = apply_view(body, rewritten)++ assert changed is True+ assert out["instructions"] == "SHORTER"+ assert out["input"][0]["content"][0]["text"] == "SHORTER"+ assert out["input"][4]["output"][0]["text"] == "SHORTER"+ assert out["input"][3]["input"] == "SHORTER" # the call's own input+ # ...and everything opaque survives byte-for-byte.+ assert out["input"][2] == body["input"][2]+ assert out["input"][2]["encrypted_content"] == ENCRYPTED+ assert out["input"][0]["internal_chat_message_metadata_passthrough"] == {"opaque": True}+ assert [i["type"] for i in out["input"]] == [i["type"] for i in body["input"]]+ assert [i.get("call_id") for i in out["input"]] == [i.get("call_id") for i in body["input"]]+++def test_a_view_that_does_not_line_up_is_refused_rather_than_guessed():+ """Fewer messages back than slots means we cannot say which slot lost its+ text. Forwarding the original uncompressed is the only safe answer."""+ body = codex_body()+ view = build_view(body)+ out, changed = apply_view(body, view.messages[:-1])+ assert changed is False+ assert out == body+++def test_apply_view_does_not_mutate_the_body_it_was_given():+ body = codex_body()+ before = copy.deepcopy(body)+ view = build_view(body)+ apply_view(body, [dict(m, content="SHORTER") for m in view.messages])+ assert body == before+++def test_the_provider_body_goes_back_in_the_shape_the_client_sent():+ body = codex_body()+ body["messages"] = build_view(body).messages+ mark_view(body)++ out = build_provider_body(body, [dict(m, content="SHORTER") for m in body["messages"]], None)++ assert "input" in out and "instructions" in out+ assert "messages" not in out, "the view is ours; the provider must never see it"+ assert VIEW_MARKER not in out, "control keys never reach a provider"+ assert out["input"][0]["content"][0]["text"] == "SHORTER"+ assert out["input"][2]["encrypted_content"] == ENCRYPTED+++def test_a_bare_string_input_is_handled():+ body = {"model": "gpt-5-codex", "input": "just a string"}+ view = build_view(body)+ assert [m["content"] for m in view.messages] == ["just a string"]+ out, changed = apply_view(body, [{"role": "user", "content": "shorter"}])+ assert changed is True+ assert out["input"] == "shorter"+++def test_string_valued_content_and_output_are_handled():+ """Not every client sends parts; both fields also accept a bare string."""+ body = {+ "model": "gpt-5-codex",+ "input": [+ {"type": "message", "role": "user", "content": "hello"},+ {"type": "function_call_output", "call_id": "c1", "output": "raw output"},+ ],+ }+ view = build_view(body)+ assert [m["content"] for m in view.messages] == ["hello", "raw output"]++ out, changed = apply_view(body, [dict(m, content="X") for m in view.messages])+ assert changed is True+ assert out["input"][0]["content"] == "X"+ assert out["input"][1]["output"] == "X"+ assert out["input"][1]["call_id"] == "c1"+++def test_an_empty_input_yields_an_empty_view():+ view = build_view({"model": "gpt-5-codex", "input": []})+ assert view.messages == []+ assert len(view) == 0+++def _call_body(item: dict) -> dict:+ return {"model": "gpt-5-codex", "input": [item]}+++def test_a_call_input_is_compressible():+ """``custom_tool_call.input`` holds scripts and patches and is resent every+ turn: 8.9% of transcript bytes across real Codex sessions."""+ body = _call_body(+ {"type": "custom_tool_call", "call_id": "c1", "name": "exec", "input": "ls -R " * 500}+ )+ view = build_view(body)+ assert len(view.messages) == 1+ assert view.messages[0]["role"] == "assistant"++ out, changed = apply_view(body, [{"role": "assistant", "content": "ls -R"}])+ assert changed is True+ assert out["input"][0]["input"] == "ls -R"+ assert out["input"][0]["call_id"] == "c1"+++def test_json_arguments_are_rewritten_only_when_the_result_still_parses():+ """``function_call.arguments`` is a JSON document the provider parses.++ A compressor works on text and has no reason to emit valid JSON, so+ shortening one would usually turn a working call into a parse error at the+ provider. The field keeps what it had unless the replacement parses.+ """+ body = _call_body(+ {"type": "function_call", "call_id": "c1", "name": "f", "arguments": '{"path": "/tmp/x"}'}+ )+ out, changed = apply_view(body, [{"role": "assistant", "content": "path=/tmp/x"}])+ assert changed is False, "plain text must not replace a JSON document"+ assert out["input"][0]["arguments"] == '{"path": "/tmp/x"}'++ out, changed = apply_view(body, [{"role": "assistant", "content": '{"path":"/tmp/x"}'}])+ assert changed is True, "valid JSON may replace valid JSON"+ assert out["input"][0]["arguments"] == '{"path":"/tmp/x"}'+++def test_a_call_input_that_was_never_json_has_nothing_to_protect():+ """The guard is about preserving a parse, not about refusing to compress."""+ body = _call_body(+ {"type": "custom_tool_call", "call_id": "c1", "name": "exec", "input": "pwd && ls"}+ )+ out, changed = apply_view(body, [{"role": "assistant", "content": "pwd"}])+ assert changed is True+ assert out["input"][0]["input"] == "pwd"+++# --------------------------------------------------------------------------- #+# CCR re-drive #+# --------------------------------------------------------------------------- #+++def test_the_ccr_tool_is_declared_in_the_flat_responses_shape():+ """Responses rejects the chat-completions nested declaration.++ Falling through to the OpenAI shape would inject a tool the provider+ refuses, on exactly the turns where compression markers made it necessary.+ """+ from headroom.ccr import CCR_TOOL_NAME+ from headroom.ccr.tool_injection import create_ccr_tool_definition++ flat = create_ccr_tool_definition("openai_responses")+ assert flat["type"] == "function"+ assert flat["name"] == CCR_TOOL_NAME+ assert "function" not in flat, "that is the chat-completions shape"+ assert "hash" in flat["parameters"]["properties"]++ nested = create_ccr_tool_definition("openai")+ assert nested["function"]["name"] == CCR_TOOL_NAME, "chat shape must not change"+++def test_arming_ccr_on_a_responses_turn_injects_the_flat_tool():+ from headroom.ccr import CCR_TOOL_NAME+ from headroom.proxy.gateway_turn import (+ GatewayCapabilities,+ RequestTransformResult,+ arm_ccr_redrive,+ )++ caps = GatewayCapabilities(can_redrive=True, can_relay_response=True, session_affinity=True)+ result = RequestTransformResult(+ messages=[], tools=[], ctx=None, transforms=[], redrive_armed=False+ )+ armed = arm_ccr_redrive(+ result,+ provider="openai",+ caps=caps,+ mode="ccr",+ ccr_hashes=["abc123"],+ responses_shape=True,+ )+ assert armed is True+ injected = [t for t in result.tools if t.get("name") == CCR_TOOL_NAME]+ assert len(injected) == 1+ assert "function" not in injected[0], "a Responses turn needs the flat shape"+++def test_a_redrive_goes_back_in_the_responses_shape():+ """The second request must look like the first.++ ``_redrive_payload`` wrote ``messages`` unconditionally, so a re-drive on a+ Responses turn handed the gateway a body carrying both ``input`` and+ ``messages`` -- which the provider rejects. This covers every re-drive, CCR+ and tool-router alike.+ """+ from headroom.proxy.gateway_turn import PendingTurn, Step, _redrive_payload++ body = codex_body()+ view = build_view(body)+ turn = PendingTurn(+ turn_id="t1",+ session_key=None,+ session_id=None,+ provider="openai",+ model="gpt-5-codex",+ body=body,+ ctx=None,+ obligations=["redrive"],+ outcome_draft=None,+ created_at=0.0,+ deadline=0.0,+ wire_shape="openai_responses",+ )+ step = Step(+ kind="redrive",+ messages=[dict(m, content="SHORTER") for m in view.messages],+ tools=None,+ )++ sent = _redrive_payload(turn, step)["request"]++ assert "input" in sent+ assert "messages" not in sent, "the provider rejects a body carrying both"+ assert sent["input"][0]["content"][0]["text"] == "SHORTER"+ assert sent["input"][2]["encrypted_content"] == ENCRYPTED+++def test_a_responses_body_with_no_view_never_grows_a_messages_key():+ """The bypass header returns before a view is built.++ ``build_provider_body`` used to add ``messages`` unconditionally, so+ ``x-headroom-bypass: true`` -- the path whose whole job is to change+ nothing -- turned every Codex request into a provider 400: "Unsupported+ parameter: 'messages'. In the Responses API, this parameter has moved to+ 'input'."+ """+ body = codex_body()+ assert not carries_view(body)++ out = build_provider_body(body, [], None)++ assert "messages" not in out+ assert out["input"] == body["input"]+ assert out["instructions"] == body["instructions"]+++def test_a_view_that_cannot_map_back_forwards_the_original_transcript():+ """Fail open on the transcript, not on a half-applied rewrite."""+ body = codex_body()+ body["messages"] = build_view(body).messages+ mark_view(body)++ # One message short: the slots cannot be matched up.+ out = build_provider_body(body, body["messages"][:-1], None)++ assert "messages" not in out+ assert out["input"] == codex_body()["input"], "the original goes out untouched"