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 unit router (#4115)

Tejas Chopra25cc2d586316
diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.py
index 35bf1652c..1a3421c2b 100644
--- a/headroom/proxy/handlers/openai.py
+++ b/headroom/proxy/handlers/openai.py
@@ -777,27 +777,6 @@ def _codex_compression_debug_enabled() -> bool:
return _log_codex_compression_debug is not _CODEX_COMPRESSION_DEBUG_NOOP
-def _json_shape(value: str) -> dict[str, Any]:
- try:
- parsed = json.loads(value)
- except Exception as exc:
- return {"is_json": False, "error": type(exc).__name__}
- if isinstance(parsed, dict):
- return {
- "is_json": True,
- "kind": "object",
- "keys": list(parsed.keys()),
- "length": len(parsed),
- }
- if isinstance(parsed, list):
- return {"is_json": True, "kind": "array", "length": len(parsed)}
- return {"is_json": True, "kind": type(parsed).__name__}
-
-
-def _routing_log_debug(_router_result: Any) -> list[dict[str, Any]]:
- return []
-
-
_OPENAI_TOOL_SCHEMA_DROP_KEYS = {
"$id",
"$schema",
@@ -2138,7 +2117,6 @@ class OpenAIHandlerMixin:
*,
model: str,
request_id: str,
- pass_id: str | None = None,
timing: dict[str, float] | None = None,
deadline_started_at: float | None = None,
) -> tuple[dict[str, Any], bool, int, list[str], dict[str, int], list[str], int]:
@@ -2152,18 +2130,6 @@ class OpenAIHandlerMixin:
are intentionally not exposed as text units.
"""
- debug_enabled = _codex_compression_debug_enabled()
-
- def _log(_event: str, **_fields: Any) -> None:
- if debug_enabled:
- _log_codex_compression_debug(
- _event,
- request_id=request_id,
- pass_id=pass_id,
- model=model,
- **_fields,
- )
-
input_items = payload.get("input")
messages_items = payload.get("messages")
items = input_items if isinstance(input_items, list) else messages_items
@@ -2408,7 +2374,6 @@ class OpenAIHandlerMixin:
# (item_index, slot_ref, folded_text, original_text). Spliced after the
# normal candidate compression — no ML, byte/data-lossless only.
lossless_excluded: list[tuple[int, tuple[str, int | None], str, str]] = []
- extraction_debug: list[dict[str, Any]] = []
last_user_item_idx = max(
(
idx
@@ -2421,65 +2386,20 @@ class OpenAIHandlerMixin:
)
for idx, item in enumerate(items):
if not isinstance(item, dict):
- if debug_enabled:
- extraction_debug.append(
- {
- "index": idx,
- "eligible": False,
- "reason": "item_not_dict",
- "item_type": type(item).__name__,
- "item": item,
- }
- )
continue
item_type = item.get("type")
if item_type in self.OPENAI_RESPONSES_OUTPUT_TYPES:
call_id = item.get("call_id")
if isinstance(call_id, str) and call_id in headroom_retrieve_call_ids:
- if debug_enabled:
- extraction_debug.append(
- {
- "index": idx,
- "eligible": False,
- "reason": "headroom_retrieve_output_protected",
- "item_type": item_type,
- "call_id": call_id,
- "item": item,
- }
- )
continue
if isinstance(call_id, str) and call_id in read_command_by_call_id:
# Finalize by CONTENT (same gate as ContentRouter.apply):
# protect unless the output is confidently non-code DATA.
if _read_output_should_be_protected(_responses_part_text(item.get("output"))):
read_protected_call_ids.add(call_id)
- if debug_enabled:
- extraction_debug.append(
- {
- "index": idx,
- "eligible": False,
- "reason": "read_command_protected",
- "item_type": item_type,
- "call_id": call_id,
- "command": read_command_by_call_id[call_id],
- "item": item,
- }
- )
continue
if isinstance(call_id, str) and call_id in excluded_call_ids:
if call_id in verbatim_excluded_call_ids:
- if debug_enabled:
- extraction_debug.append(
- {
- "index": idx,
- "eligible": False,
- "reason": "exclude_tools_verbatim",
- "item_type": item_type,
- "call_id": call_id,
- "tool_name": function_name_by_call_id.get(call_id),
- "item": item,
- }
- )
continue
# Protected from lossy compression — but grep/log/json output
# can still be losslessly compacted. Reuse the router helper
@@ -2490,10 +2410,9 @@ class OpenAIHandlerMixin:
# A file read skips the fold entirely: this is the Codex wire,
# where `read` really does return raw file bytes, so a fold here
# is exactly what breaks the next `Edit(old_string=…)`.
- excluded_folded = False
raw_output = item.get("output")
if call_id in byte_exact_call_ids:
- pass # byte-exact: no fold, fall through to the debug record
+ pass # byte-exact: no fold
elif isinstance(raw_output, list):
for pidx, part in enumerate(raw_output):
if (
@@ -2504,7 +2423,6 @@ class OpenAIHandlerMixin:
part_text = part["text"]
pf = router._lossless_compact_excluded(part_text)
if pf is not None:
- excluded_folded = True
lossless_excluded.append(
(idx, ("output_part", pidx), pf[0], part_text)
)
@@ -2512,128 +2430,20 @@ class OpenAIHandlerMixin:
excl_out = _responses_part_text(raw_output)
fold = router._lossless_compact_excluded(excl_out) if excl_out else None
if fold is not None:
- excluded_folded = True
lossless_excluded.append((idx, ("output", None), fold[0], excl_out))
- if debug_enabled:
- extraction_debug.append(
- {
- "index": idx,
- "eligible": False,
- "reason": (
- "exclude_tools_lossless_fold"
- if excluded_folded
- else "exclude_tools_protected"
- ),
- "item_type": item_type,
- "call_id": call_id,
- "tool_name": function_name_by_call_id.get(call_id),
- "item": item,
- }
- )
continue
slots = _slot_texts(item)
- if slots:
- for text, slot_ref in slots:
- candidates.append((idx, slot_ref, text))
- if debug_enabled:
- extraction_debug.append(
- {
- "index": idx,
- "eligible": True,
- "item_type": item_type,
- "role": item.get("role"),
- "slot": slot_ref,
- "text_chars": len(text),
- "text_bytes": len(text.encode("utf-8", errors="replace")),
- "text_json_shape": _json_shape(text),
- "item": item,
- "text": text,
- }
- )
- else:
- if debug_enabled:
- extraction_debug.append(
- {
- "index": idx,
- "eligible": False,
- "reason": "output_type_without_text_slot",
- "item_type": item_type,
- "item": item,
- }
- )
+ for text, slot_ref in slots:
+ candidates.append((idx, slot_ref, text))
elif item_type == "message":
if item.get("role") == "user" and idx == last_user_item_idx:
- if debug_enabled:
- extraction_debug.append(
- {
- "index": idx,
- "eligible": False,
- "reason": "current_user_message_protected",
- "item_type": item_type,
- "role": item.get("role"),
- "item": item,
- }
- )
continue
slots = _slot_texts(item)
for text, slot_ref in slots:
candidates.append((idx, slot_ref, text))
- if debug_enabled:
- extraction_debug.append(
- {
- "index": idx,
- "eligible": True,
- "item_type": item_type,
- "role": item.get("role"),
- "slot": slot_ref,
- "text_chars": len(text),
- "text_bytes": len(text.encode("utf-8", errors="replace")),
- "text_json_shape": _json_shape(text),
- "item": item,
- "text": text,
- }
- )
- if not slots and debug_enabled:
- extraction_debug.append(
- {
- "index": idx,
- "eligible": False,
- "reason": "supported_type_without_text_slot",
- "item_type": item_type,
- "item": item,
- }
- )
- else:
- if debug_enabled:
- extraction_debug.append(
- {
- "index": idx,
- "eligible": False,
- "reason": "unsupported_item_type",
- "item_type": item_type,
- "role": item.get("role"),
- "item": item,
- }
- )
_add_timing("compression_live_unit_extraction", extraction_started)
- _log(
- "codex_compression_extraction",
- item_count=len(items),
- candidate_count=len(candidates),
- payload=payload,
- extraction=extraction_debug,
- )
if not candidates and not lossless_excluded:
- _log(
- "codex_compression_payload_result",
- modified=False,
- reason="no_candidates",
- tokens_saved_total=0,
- transforms=[],
- input_payload=payload,
- output_payload=payload,
- )
return payload, False, 0, [], {}, [], 0
deepcopy_started = time.perf_counter()
@@ -2662,7 +2472,6 @@ class OpenAIHandlerMixin:
routed_units: list[RoutedCompressionUnit] = []
unit_build_started = time.perf_counter()
- unit_debug: list[dict[str, Any]] = []
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"
@@ -2689,34 +2498,10 @@ class OpenAIHandlerMixin:
metadata=metadata,
)
routed_units.append(RoutedCompressionUnit(unit=unit, slot=(item_idx, slot_ref)))
- if debug_enabled:
- unit_debug.append(
- {
- "item_index": item_idx,
- "slot": slot_ref,
- "provider": unit.provider,
- "endpoint": unit.endpoint,
- "role": unit.role,
- "item_type": unit.item_type,
- "cache_zone": unit.cache_zone,
- "mutable": unit.mutable,
- "min_bytes": unit.min_bytes,
- "text_chars": len(unit.text),
- "text_bytes": len(unit.text.encode("utf-8", errors="replace")),
- "text_json_shape": _json_shape(unit.text),
- "text": unit.text,
- }
- )
_add_timing("compression_unit_build", unit_build_started)
- _log(
- "codex_compression_units",
- units=unit_debug,
- )
-
- # Tally per-category counts as units stream in so the pass_summary
- # event below can emit a one-line breakdown — log readers shouldn't
- # have to re-aggregate from scattered unit_result events.
+ # Per-category unit counts and the union of strategy chains, returned
+ # to the caller with the compressed payload.
units_by_category: dict[str, int] = {}
strategy_chain_union: list[str] = []
@@ -2937,33 +2722,6 @@ class OpenAIHandlerMixin:
# role-protected, or in a frozen cache_zone don't count.
if result.router_result is not None or result.modified:
attempted_input_tokens += result.tokens_before
- if debug_enabled:
- _log(
- "codex_compression_unit_result",
- item_index=item_idx,
- slot=slot_ref,
- modified=result.modified,
- reason=result.reason,
- reason_category=cat,
- text_bytes=result.text_bytes,
- min_bytes=result.min_bytes,
- strategy=result.strategy,
- strategy_chain=router_chain,
- tokens_before=result.tokens_before,
- tokens_after=result.tokens_after,
- tokens_saved=result.tokens_saved,
- transforms_applied=result.transforms_applied,
- router_strategy=(
- result.router_result.strategy_used.value if result.router_result else None
- ),
- router_summary=result.router_result.summary() if result.router_result else None,
- router_routing_log=_routing_log_debug(result.router_result),
- router_cache_hit=(
- result.router_result.cache_hit if result.router_result else False
- ),
- original=result.original,
- compressed=result.compressed,
- )
if not result.modified:
continue
@@ -3015,17 +2773,6 @@ class OpenAIHandlerMixin:
if "router:responses_cross_turn_dedup" not in transforms:
transforms.append("router:responses_cross_turn_dedup")
- _log(
- "codex_compression_payload_result",
- modified=modified,
- tokens_saved_total=tokens_saved_total,
- attempted_input_tokens=attempted_input_tokens,
- transforms=transforms,
- units_by_category=units_by_category,
- strategy_chain=strategy_chain_union,
- input_payload=payload,
- output_payload=updated if modified else payload,
- )
return (
updated,
modified,
@@ -3311,7 +3058,6 @@ class OpenAIHandlerMixin:
working,
model=model,
request_id=request_id,
- pass_id=pass_id,
timing=timing_sink,
deadline_started_at=deadline_started_at,
)
diff --git a/tests/test_openai_responses_compression_units.py b/tests/test_openai_responses_compression_units.py
index 268db0a97..0bd41ab02 100644
--- a/tests/test_openai_responses_compression_units.py
+++ b/tests/test_openai_responses_compression_units.py
@@ -882,14 +882,12 @@ def test_openai_responses_adapter_never_folds_a_file_read(tool, as_content_part)
assert new_payload["input"][1]["output"] == output
-def test_openai_responses_adapter_excludes_tool_case_insensitively_with_debug(monkeypatch):
- """Excluded match is case-insensitive, and the debug path stays exercised.
+def test_openai_responses_adapter_excludes_tool_case_insensitively():
+ """Excluded match is case-insensitive.
The configured name is lowercase only; the call advertises a mixed-case
- name, so the protection must hit via the lowercased fallback. Debug logging
- is enabled so the protected-extraction debug record is also covered.
+ name, so the protection must hit via the lowercased fallback.
"""
- monkeypatch.setattr(openai_handler, "_log_codex_compression_debug", lambda *_a, **_k: None)
router = ContentRouter()
router.config.exclude_tools = {"serena.find_symbol"}
diff --git a/tests/test_openai_responses_read_protection.py b/tests/test_openai_responses_read_protection.py
index 28a0118fc..df5be93cc 100644
--- a/tests/test_openai_responses_read_protection.py
+++ b/tests/test_openai_responses_read_protection.py
@@ -384,12 +384,9 @@ def test_responses_protected_read_survives_cross_turn_dedup(monkeypatch):
assert new_payload["input"][3]["output"] == _NL_OUTPUT
-def test_responses_debug_path_with_excluded_list_output(monkeypatch):
- """Regression: debug logging over an excluded tool's content-part output must
- not raise (latent unbound `fold` variable in the list branch)."""
- from headroom.proxy.handlers import openai as openai_handler
-
- monkeypatch.setattr(openai_handler, "_log_codex_compression_debug", lambda *a, **k: None)
+def test_responses_excluded_list_output_does_not_raise():
+ """An excluded tool's content-part output takes the list branch without
+ raising and is forwarded unchanged."""
handler = _handler_with_router(_lossy_router())
parts = [{"type": "output_text", "text": _FILE_CONTENT}]
payload = {
@@ -468,11 +465,8 @@ def test_responses_local_shell_call_string_command_read_stays_verbatim(monkeypat
assert new_payload["input"][1]["output"] == _NL_OUTPUT
-def test_responses_debug_path_with_read_protected_output(monkeypatch):
- """Debug logging over a read-protected output records and does not raise."""
- from headroom.proxy.handlers import openai as openai_handler
-
- monkeypatch.setattr(openai_handler, "_log_codex_compression_debug", lambda *a, **k: None)
+def test_responses_read_protected_output_is_forwarded_unchanged(monkeypatch):
+ """A read-protected output does not raise and reaches the model verbatim."""
monkeypatch.setenv("HEADROOM_PROTECT_READS", "1")
handler = _handler_with_router(_lossy_router())
payload = {