Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

fix(proxy): aggregate tool-output size floor so Codex sessions compress (#2050) (#2116)

Tejas Chopradbe2558c1855
diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.py
index ef839890e..8401470f1 100644
--- a/headroom/proxy/handlers/openai.py
+++ b/headroom/proxy/handlers/openai.py
@@ -1506,6 +1506,24 @@ class OpenAIHandlerMixin:
unit_build_started = time.perf_counter()
unit_debug: list[dict[str, Any]] = []
+ # Aggregate-then-floor: the Responses payload splits each tool output
+ # into its own unit, so a per-item size floor would reject every unit
+ # in a session made of many small tool outputs (e.g. Codex), yielding
+ # 0% savings even when the combined compressible text is large. The
+ # Anthropic path compresses the whole message list as one batch and is
+ # not subject to a per-item floor. Match that: evaluate the floor once
+ # against the *aggregate* compressible bytes of the extracted group. If
+ # the group as a whole clears the threshold, disable the per-unit floor
+ # so small units still reach the router; if the whole group is below
+ # the threshold, keep the floor so trivially small payloads are skipped.
+ aggregate_compressible_bytes = sum(
+ len(text.encode("utf-8", errors="replace")) for _, _, text in candidates
+ )
+ effective_unit_min_bytes = (
+ 0
+ if aggregate_compressible_bytes >= self.OPENAI_RESPONSES_ROUTER_MIN_BYTES
+ else self.OPENAI_RESPONSES_ROUTER_MIN_BYTES
+ )
for item_idx, slot_ref, original_text in candidates:
item = items[item_idx] if item_idx < len(items) else {}
item_type = item.get("type", "unknown") if isinstance(item, dict) else "unknown"
@@ -1518,7 +1536,7 @@ class OpenAIHandlerMixin:
item_type=str(item_type),
cache_zone="live",
mutable=True,
- min_bytes=self.OPENAI_RESPONSES_ROUTER_MIN_BYTES,
+ min_bytes=effective_unit_min_bytes,
)
routed_units.append(RoutedCompressionUnit(unit=unit, slot=(item_idx, slot_ref)))
if debug_enabled:
diff --git a/tests/test_openai_responses_compression_units.py b/tests/test_openai_responses_compression_units.py
index bd66bb013..9ac2bc162 100644
--- a/tests/test_openai_responses_compression_units.py
+++ b/tests/test_openai_responses_compression_units.py
@@ -749,3 +749,104 @@ def test_openai_responses_payload_routes_through_content_router_without_rust(
assert reason is None
assert new_payload["input"][0]["output"] == "compressed fallback"
assert any(t.startswith("router:openai:responses:") for t in transforms)
+
+
+def test_openai_responses_adapter_aggregates_small_tool_outputs_before_floor():
+ """Regression for #2050: many individually-small tool outputs whose combined
+ size clears the floor must still reach the router.
+
+ The Responses path extracts each ``function_call_output`` as its own unit.
+ A per-item size floor would reject every unit in a session made of many
+ small tool outputs (the Codex shape), yielding 0% savings even though the
+ aggregate compressible text is large. The floor must be evaluated against
+ the aggregate of the extracted group, matching the batch (Anthropic) path.
+ """
+ router = ContentRouter()
+
+ def compress(self, content: str, **_kwargs):
+ return RouterCompressionResult(
+ compressed="tiny summary",
+ original=content,
+ strategy_used=CompressionStrategy.KOMPRESS,
+ )
+
+ router.compress = MethodType(compress, router)
+ handler = _handler_with_router(router)
+
+ # Each output is individually below OPENAI_RESPONSES_ROUTER_MIN_BYTES (512),
+ # but the four combined exceed it — exactly the case that used to floor to
+ # zero savings. Guard the premise so the test stays honest if the byte
+ # shapes drift.
+ floor = OpenAIHandlerMixin.OPENAI_RESPONSES_ROUTER_MIN_BYTES
+ outputs = [" ".join(f"tok{i}_{j}" for j in range(30)) for i in range(4)]
+ assert all(len(o.encode("utf-8")) < floor for o in outputs)
+ assert sum(len(o.encode("utf-8")) for o in outputs) >= floor
+
+ payload = {
+ "model": "gpt-5",
+ "input": [
+ {
+ "type": "function_call_output",
+ "call_id": f"c{i}",
+ "output": output,
+ }
+ for i, output in enumerate(outputs)
+ ],
+ }
+
+ new_payload, modified, saved, transforms, units_by_category, _strategy_chain, _attempted = (
+ handler._compress_openai_responses_live_text_units_with_router(
+ payload,
+ model="gpt-5",
+ request_id="req_aggregate_floor",
+ )
+ )
+
+ assert modified is True
+ assert saved > 0
+ # No unit should be size-floored; every extracted unit is compressed.
+ assert "size_floor" not in units_by_category
+ assert units_by_category == {"applied": len(outputs)}
+ assert all(item["output"] == "tiny summary" for item in new_payload["input"])
+
+
+def test_openai_responses_adapter_floors_when_aggregate_below_threshold():
+ """Complement to #2050: when the *whole* group is below the floor the units
+ are still skipped, so trivially small payloads don't churn the router.
+ """
+ router = ContentRouter()
+
+ def compress(self, content: str, **_kwargs): # pragma: no cover - must not run
+ raise AssertionError("aggregate below floor should skip compression")
+
+ router.compress = MethodType(compress, router)
+ handler = _handler_with_router(router)
+
+ floor = OpenAIHandlerMixin.OPENAI_RESPONSES_ROUTER_MIN_BYTES
+ outputs = ["ok", "done"]
+ assert sum(len(o.encode("utf-8")) for o in outputs) < floor
+
+ payload = {
+ "model": "gpt-5",
+ "input": [
+ {
+ "type": "function_call_output",
+ "call_id": f"c{i}",
+ "output": output,
+ }
+ for i, output in enumerate(outputs)
+ ],
+ }
+
+ new_payload, modified, saved, _transforms, units_by_category, _strategy_chain, _attempted = (
+ handler._compress_openai_responses_live_text_units_with_router(
+ payload,
+ model="gpt-5",
+ request_id="req_aggregate_below",
+ )
+ )
+
+ assert modified is False
+ assert saved == 0
+ assert units_by_category == {"size_floor": len(outputs)}
+ assert new_payload == payload