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.

refactor(proxy): remove the unreachable debug branches from the Responses payload compressor (#4116)

Tejas Chopra132cd583daeb
diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.py
index 1a3421c2b..b926c3ee0 100644
--- a/headroom/proxy/handlers/openai.py
+++ b/headroom/proxy/handlers/openai.py
@@ -1090,38 +1090,6 @@ def _ensure_chatgpt_responses_store_false(
return False
-def _responses_input_item_text_bytes(item: Any) -> int:
- if not isinstance(item, dict):
- return _json_byte_len(item)
-
- output = item.get("output")
- if isinstance(output, str):
- return len(output.encode("utf-8", errors="replace"))
- if isinstance(output, list):
- total = 0
- for part in output:
- if isinstance(part, str):
- total += len(part.encode("utf-8", errors="replace"))
- elif isinstance(part, dict) and isinstance(part.get("text"), str):
- total += len(part["text"].encode("utf-8", errors="replace"))
- if total > 0:
- return total
-
- content = item.get("content")
- if isinstance(content, str):
- return len(content.encode("utf-8", errors="replace"))
- if isinstance(content, list):
- total = 0
- for part in content:
- if isinstance(part, str):
- total += len(part.encode("utf-8", errors="replace"))
- elif isinstance(part, dict) and isinstance(part.get("text"), str):
- total += len(part["text"].encode("utf-8", errors="replace"))
- return total
-
- return _json_byte_len(item)
-
-
_RESPONSES_OUTPUT_ITEM_TYPES = frozenset(
{
"custom_tool_call_output",
@@ -1659,47 +1627,6 @@ def _shape_openai_response_create_frame(
return json.dumps(payload), True, labels, None
-def _openai_responses_context_budget(payload: dict[str, Any]) -> dict[str, Any]:
- payload_bytes = _json_byte_len(payload)
- buckets: dict[str, int] = {}
- for key in ("instructions", "tools", "input", "messages", "client_metadata"):
- if key in payload:
- buckets[key] = _json_byte_len(payload.get(key))
-
- other_bytes = max(payload_bytes - sum(buckets.values()), 0)
- if other_bytes:
- buckets["other"] = other_bytes
-
- input_breakdown: dict[str, dict[str, int]] = {}
- items = payload.get("input") or payload.get("messages")
- if isinstance(items, list):
- for item in items:
- item_type = item.get("type", "unknown") if isinstance(item, dict) else "non_dict"
- row = input_breakdown.setdefault(
- str(item_type),
- {"items": 0, "bytes": 0, "text_bytes": 0},
- )
- row["items"] += 1
- row["bytes"] += _json_byte_len(item)
- row["text_bytes"] += _responses_input_item_text_bytes(item)
-
- return {
- "payload_bytes": payload_bytes,
- "buckets": {
- key: {
- "bytes": value,
- "pct": (value / payload_bytes * 100.0) if payload_bytes else 0.0,
- }
- for key, value in sorted(
- buckets.items(),
- key=lambda item: item[1],
- reverse=True,
- )
- },
- "input_breakdown": input_breakdown,
- }
-
-
# Interactive Responses turns are latency-sensitive. Fail open quickly rather
# than holding the session hostage on memory lookup.
RESPONSES_CONTEXT_SEARCH_TIMEOUT_SECONDS = 2.0
@@ -2812,33 +2739,6 @@ class OpenAIHandlerMixin:
input_serialization_started = time.perf_counter()
input_bytes = json.dumps(payload).encode("utf-8")
_add_timing("compression_input_json_dump", input_serialization_started)
- # Codex/Responses requests can re-enter this method many times per
- # request_id (one per turn over the same websocket). Tag every
- # event in this single pass with a content-derived id so dashboards
- # can attribute each unit_result to its originating pass.
- # Aggregation note: per-pass `tokens_saved` SHOULD sum across
- # passes — every pass independently avoided sending those tokens
- # upstream, regardless of any prefix cache the upstream applies.
- # Identical pass_ids within one request_id indicate idempotent
- # retries on the same input bytes and are the only thing that
- # should be deduped.
- debug_enabled = _codex_compression_debug_enabled()
- pass_id = hashlib.sha256(input_bytes).hexdigest()[:12] if debug_enabled else None
- input_context_budget: dict[str, Any] | None = None
- if debug_enabled:
- input_context_budget = _openai_responses_context_budget(payload)
- _log_codex_compression_debug(
- "codex_compression_payload_input",
- request_id=request_id,
- pass_id=pass_id,
- model=model,
- input_bytes=len(input_bytes),
- context_budget=input_context_budget,
- input_top_level_keys=list(payload.keys()),
- input_field_type=type(payload.get("input")).__name__,
- messages_field_type=type(payload.get("messages")).__name__,
- payload=payload,
- )
working = payload
modified = False
tokens_saved = 0
@@ -2866,17 +2766,6 @@ class OpenAIHandlerMixin:
_add_timing("compression_tool_schema_token_count", tool_token_started)
except Exception:
pass
- if debug_enabled:
- _log_codex_compression_debug(
- "codex_tool_schema_compaction",
- request_id=request_id,
- pass_id=pass_id,
- model=model,
- modified=True,
- tools_bytes_before=tools_before_bytes,
- tools_bytes_after=tools_after_bytes,
- tools_bytes_saved=tools_before_bytes - tools_after_bytes,
- )
# Layer 2: Tool description truncation (opt-in via
# HEADROOM_TOOL_DESC_MAX_CHARS).
@@ -2906,17 +2795,6 @@ class OpenAIHandlerMixin:
)
except Exception:
pass
- if debug_enabled:
- _log_codex_compression_debug(
- "codex_tool_desc_compaction",
- request_id=request_id,
- pass_id=pass_id,
- model=model,
- modified=True,
- tools_bytes_before=desc_before,
- tools_bytes_after=desc_after,
- tools_bytes_saved=desc_before - desc_after,
- )
except Exception:
pass
@@ -3103,66 +2981,6 @@ class OpenAIHandlerMixin:
output_serialization_started = time.perf_counter()
output_bytes = json.dumps(working).encode("utf-8")
_add_timing("compression_output_json_dump", output_serialization_started)
- output_context_budget = _openai_responses_context_budget(working) if debug_enabled else None
- # One-line summary at INFO — the single event a human reading
- # logs should scan first to understand "what happened on this
- # pass". All the verbose per-event debug data stays available
- # but at DEBUG level. Contains: byte totals, savings, the
- # strategy chain we walked, unit-outcome counts by category,
- # and the transforms applied.
- savings_pct = (
- (1.0 - len(output_bytes) / len(input_bytes)) * 100.0 if len(input_bytes) else 0.0
- )
- # Active-compression ratio: savings as a fraction of what we
- # *attempted* to compress, not of the whole request. The whole-
- # request ratio is in `savings_pct`; this one is the metric the
- # dashboard should display (otherwise frozen prefix bytes drown
- # the wins from the compressible tail).
- #
- # Math note: `attempted_input_tokens` is the pre-compression
- # size of the eligible content (sum of unit.tokens_before +
- # original tool schema). `tokens_saved` is what we removed
- # from it. So the savings rate is plain `saved / attempted` —
- # NOT `saved / (attempted + saved)`, which would double-count.
- attempted_pct = (
- (tokens_saved / attempted_input_tokens) * 100.0 if attempted_input_tokens > 0 else 0.0
- )
- if debug_enabled:
- _log_codex_compression_debug(
- "codex_compression_pass_summary",
- request_id=request_id,
- pass_id=pass_id,
- model=model,
- modified=modified,
- reason=reason,
- input_bytes=len(input_bytes),
- output_bytes=len(output_bytes),
- bytes_saved=len(input_bytes) - len(output_bytes),
- savings_pct=round(savings_pct, 2),
- tokens_saved=tokens_saved,
- attempted_input_tokens=attempted_input_tokens,
- attempted_pct=round(attempted_pct, 2),
- strategy_chain=strategy_chain,
- units_by_category=units_by_category,
- transforms=deduped,
- )
- _log_codex_compression_debug(
- "codex_compression_payload_output",
- request_id=request_id,
- pass_id=pass_id,
- model=model,
- modified=modified,
- reason=reason,
- tokens_saved=tokens_saved,
- attempted_input_tokens=attempted_input_tokens,
- transforms=deduped,
- input_bytes=len(input_bytes),
- output_bytes=len(output_bytes),
- context_budget_before=input_context_budget,
- context_budget_after=output_context_budget,
- input_payload=payload,
- output_payload=working,
- )
return (
working,
modified,
diff --git a/tests/test_openai_codex_ws_timings.py b/tests/test_openai_codex_ws_timings.py
index d38458795..0cbb9e3fa 100644
--- a/tests/test_openai_codex_ws_timings.py
+++ b/tests/test_openai_codex_ws_timings.py
@@ -11,7 +11,6 @@ from unittest.mock import MagicMock, patch
import anyio
import pytest
-import headroom.proxy.handlers.openai as openai_handler
from headroom.proxy.handlers.openai import OpenAIHandlerMixin
@@ -350,21 +349,3 @@ def test_codex_ws_request_id_and_session_id_present_in_log(stage_log_capture):
assert payload["request_id"] == "req-ws-test"
assert isinstance(payload["session_id"], str)
assert len(payload["session_id"]) >= 16
-
-
-def test_codex_compression_debug_noop_skips_expensive_payload_debug(monkeypatch):
- handler = _DummyOpenAIHandler()
-
- def _fail_context_budget(_payload):
- raise AssertionError("debug context budget should not be built")
-
- monkeypatch.setattr(openai_handler, "_openai_responses_context_budget", _fail_context_budget)
-
- result = handler._compress_openai_responses_payload(
- {"model": "gpt-5.4", "input": "hello"},
- model="gpt-5.4",
- request_id="req-ws-test",
- )
-
- assert result[1] is False
- assert result[4] == "router_no_compression"
diff --git a/tests/test_openai_responses_context_compaction.py b/tests/test_openai_responses_context_compaction.py
index 48f7c11ca..16b2f8741 100644
--- a/tests/test_openai_responses_context_compaction.py
+++ b/tests/test_openai_responses_context_compaction.py
@@ -6,7 +6,6 @@ from typing import Any
from headroom.proxy.handlers.openai import (
OpenAIHandlerMixin,
_compact_openai_responses_tools,
- _openai_responses_context_budget,
)
from headroom.transforms.content_router import (
CompressionStrategy,
@@ -16,46 +15,6 @@ from headroom.transforms.content_router import (
)
-def test_openai_responses_context_budget_breaks_out_static_and_live_buckets() -> None:
- payload = {
- "instructions": "stable instructions",
- "tools": [
- {
- "type": "function",
- "name": "read_file",
- "description": "Read a file.",
- "parameters": {
- "type": "object",
- "properties": {"path": {"type": "string"}},
- "required": ["path"],
- },
- }
- ],
- "input": [
- {
- "type": "function_call_output",
- "call_id": "call_1",
- "output": "line one\nline two\n",
- },
- {
- "type": "message",
- "role": "user",
- "content": [{"type": "input_text", "text": "do the thing"}],
- },
- ],
- }
-
- budget = _openai_responses_context_budget(payload)
-
- assert budget["payload_bytes"] > 0
- assert {"instructions", "tools", "input"}.issubset(budget["buckets"])
- assert budget["input_breakdown"]["function_call_output"]["items"] == 1
- assert budget["input_breakdown"]["function_call_output"]["text_bytes"] == len(
- b"line one\nline two\n"
- )
- assert budget["input_breakdown"]["message"]["items"] == 1
-
-
def test_openai_tool_schema_compaction_preserves_invocation_shape() -> None:
verbose = " ".join(["Use this tool to read a file from the workspace."] * 40)
payload = {
@@ -301,12 +260,12 @@ def test_codex_payload_with_only_messages_field_also_reaches_router() -> None:
def test_compression_pass_debug_logs_are_suppressed(caplog) -> None:
- """Re-entrant Codex websocket passes share one `request_id` but
- process distinct payloads. The `pass_id` field on every compression
- event must be content-derived so dashboards can attribute each
- unit_result to its originating pass. Distinct payloads → distinct
- pass_ids (per-pass savings sum legitimately across passes); identical
- payloads → identical pass_ids (idempotent retries should dedup)."""
+ """Compression passes must not log per-pass payload events at INFO.
+
+ Re-entrant Codex websocket passes share one `request_id`; three passes
+ over two distinct payloads must emit no ``event=codex_compression_*``
+ records, which would carry request content.
+ """
import logging as _logging
@@ -343,42 +302,12 @@ def test_compression_pass_debug_logs_are_suppressed(caplog) -> None:
handler._compress_openai_responses_payload(
payload_b, model="gpt-5.5", request_id="hr_shared_request"
)
- # Same content twice → same pass_id (deterministic + idempotent).
+ # A repeat of the first payload, as a re-entrant pass would send.
handler._compress_openai_responses_payload(
payload_a, model="gpt-5.5", request_id="hr_shared_request"
)
assert not any("event=codex_compression_" in record.getMessage() for record in caplog.records)
- return
-
- # Collect pass_ids in call order — payload bodies are no longer
- # embedded at INFO so we can't grep for content; we rely on the
- # 3-call sequence [a, b, a] producing a [A, B, A] pass_id sequence.
- pass_id_sequence: list[str] = []
- for record in caplog.records:
- message = record.getMessage()
- if "event=codex_compression_payload_input" not in message:
- continue
- match_quoted = '"pass_id":"'
- idx = message.find(match_quoted)
- assert idx != -1, f"pass_id missing from event: {message[:200]}"
- start = idx + len(match_quoted)
- end = message.find('"', start)
- pass_id_sequence.append(message[start:end])
-
- assert len(pass_id_sequence) == 3, (
- f"expected exactly 3 payload_input events for 3 calls, got {len(pass_id_sequence)}"
- )
- # Two distinct payloads + one repeat → two distinct pass_ids overall.
- assert len(set(pass_id_sequence)) == 2, (
- f"expected two distinct pass_ids, got {set(pass_id_sequence)}"
- )
- # Repeated payload_a must be deterministic — index 0 and 2 are the
- # same call shape so they must produce the same pass_id.
- assert pass_id_sequence[0] == pass_id_sequence[2], (
- f"repeated identical payload produced different pass_ids: {pass_id_sequence}"
- )
- assert pass_id_sequence[0] != pass_id_sequence[1]
def test_codex_payload_without_either_field_is_skipped() -> None: