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.

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.py
index 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 format
return {
diff --git a/headroom/proxy/gateway_extension.py b/headroom/proxy/gateway_extension.py
index 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_view
from headroom.proxy.gateway_turn import (
OBLIGATION_RELAY_USAGE,
GatewayCapabilities,
@@ -80,6 +81,10 @@ class GatewayTurn:
self.caps = caps
self.client = client
self.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"] = tools
transforms.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 defer
diff --git a/headroom/proxy/gateway_responses.py b/headroom/proxy/gateway_responses.py
new file mode 100644
index 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, changed
diff --git a/headroom/proxy/gateway_turn.py b/headroom/proxy/gateway_turn.py
index 851a03cae..3d7e92d52 100644
--- a/headroom/proxy/gateway_turn.py
+++ b/headroom/proxy/gateway_turn.py
@@ -49,6 +49,7 @@ from collections.abc import Callable
from dataclasses import dataclass, field
from typing import Any
+from headroom.proxy.gateway_responses import VIEW_MARKER as GATEWAY_RESPONSES_VIEW_MARKER
from headroom.proxy.outcome import RequestOutcome
from 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"
@property
def 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 = tools
if 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"] = messages
if tools is not None:
out["tools"] = tools
return 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.messages
if step.tools is not None:
redrive_body["tools"] = step.tools
return {
diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.py
index 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_view
from headroom.proxy.helpers import _read_request_json
def _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.py
new file mode 100644
index 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"