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
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.pyindex 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 = payloadmodified = Falsetokens_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.pyindex 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, patchimport anyioimport pytest-import headroom.proxy.handlers.openai as openai_handlerfrom 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.pyindex 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 Anyfrom 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: