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

## Description

This removes debug code that can never run from
`_compress_openai_responses_payload` in
`headroom/proxy/handlers/openai.py`.

`_log_codex_compression_debug` has been a no-op since e9cae013.
`_codex_compression_debug_enabled()` returns true only when a test
replaces it. The method still computed debug-only data on every call,
and its four `if debug_enabled:` branches never ran.

Refs #4136

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [x] Code refactoring (no functional changes)

## Changes Made

- Removed the four `if debug_enabled:` blocks.
- Removed the debug-only values:
  - the sha256 `pass_id`;
  - both `_openai_responses_context_budget` walks;
  - the `savings_pct` and `attempted_pct` figures.
- Removed `_openai_responses_context_budget` and
`_responses_input_item_text_bytes`. Their only production caller was
that debug code.
- Return values and the INFO-level logs are unchanged.
- Tests:
  - Removed the unit test of `_openai_responses_context_budget`.
- Removed
`test_codex_compression_debug_noop_skips_expensive_payload_debug`. What
it guarded is now structural.
- Removed the unreachable code after a bare `return` in
`test_compression_pass_debug_logs_are_suppressed`, and fixed its
docstring. It still asserts that no `event=codex_compression_*` record
reaches INFO.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [ ] New tests added for new functionality
- [ ] Manual testing performed

### Test Output

```text
$ uvx ruff@0.16.8 check headroom/proxy/handlers/openai.py tests/test_openai_codex_ws_timings.py tests/test_openai_responses_context_compaction.py
All checks passed!
$ python -m mypy headroom/proxy/handlers/openai.py --ignore-missing-imports
Success: no issues found in 1 source file
$ pytest -q tests/test_openai_responses_compression_units.py tests/test_openai_responses_read_protection.py tests/test_openai_responses_context_compaction.py tests/test_openai_codex_ws_timings.py tests/test_codex_openai_contract_parity.py tests/test_openai_responses_t3_replay_regression.py
92 passed in 8.17s
$ pytest -q tests/test_openai_codex_ws_lifecycle.py
53 passed in 3.77s
$ pytest -q tests/test_openai_responses_additional_tools.py tests/test_proxy_openai_responses_integration.py tests/test_codex_ws_compression_scheduler.py tests/test_openai_responses_traffic_learner.py tests/test_openai_responses_output_shaper.py tests/test_proxy_openai_responses_stream_ccr.py
39 passed, 15 skipped in 9.77s
```


## Real Behavior Proof

- Environment: macOS, Python 3.12, repo venv, branch
`cleanup/proxy-handlers-codex-debug-payload` @ f31519e3, temp
`HOME`/`HEADROOM_WORKSPACE_DIR`/`CODEX_HOME`, `HEADROOM_OFFLINE=1`
- Exact command / steps: (1) the shared smoke harness: a real `headroom
proxy` from this checkout against a local fake upstream, with one
Anthropic and one OpenAI chat turn carrying a compressible tool result;
(2) a direct run of the real app (`create_app` + TestClient) sending one
`/v1/responses` turn whose `function_call_output` is a 25 KB JSON array.
This goes through `_compress_openai_responses_payload`, the function
whose debug blocks this PR removes. The upstream send is replaced, which
records the forwarded body.
- Observed result: shown below. Both smoke turns return 200 with
savings. The Responses turn returns 200, the tool output is forwarded
compressed (25008 → 8261 bytes) and `/stats` books the saving.
`origin/main` gives the same three numbers for (2), so compression
output is unchanged.
- Not tested: a real Codex client or hosted upstream, and the Codex
WebSocket path

```text
$ bash smoke.sh <worktree>
branch: cleanup/proxy-handlers-codex-debug-payload @ f31519e3
health: 200
POST /v1/messages        -> HTTP200 smoke-ok
POST /v1/chat/completions -> HTTP200 smoke-ok
stats: requests=2 failed=0 tokens_saved=13574 savings_percent=99.82
proxy.log WARNING/ERROR lines:
   (only the pre-existing offline-mode notice and Kompress offline-prefetch warnings)

$ HOME=$T/h HEADROOM_WORKSPACE_DIR=$T/ws CODEX_HOME=$T/c HEADROOM_OFFLINE=1 python proof_responses.py
status: 200 ok
tool output bytes: client 25008 -> forwarded 8261
stats requests: 1 tokens_saved: 6787
```

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: stable
- Stable/default behavior changed: no; only branches gated on a flag
that is never true in production are removed
- Kill switch / disable path: not applicable (dead code removal)
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert this commit

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

N/A

## Additional Notes

Part of maintainer-requested cleanup #4136 (dead code, duplication,
debuggability), split into small PRs for review.

- `tests/test_openai_codex_ws_lifecycle.py` segfaults in a native worker
thread when it runs in one pytest process after the other Responses test
files. The same combined run segfaults on clean `origin/main`, so it is
pre-existing. That is why it was run on its own.
- The shared sink itself (`_log_codex_compression_debug`,
`_CODEX_COMPRESSION_DEBUG_NOOP`, `_codex_compression_debug_enabled`, 9
lines) stays until this PR and its sibling
`cleanup/proxy-handlers-codex-debug-units` have both merged; a
one-commit follow-up then deletes it. The two PRs touch different
methods, so they merge in either order.
- The `except Exception: pass` sites next to the removed blocks are left
as they are here. The separate PR
`cleanup/proxy-handlers-debuggable-logs` adds logging to them, so expect
a small textual conflict at those lines when rebasing whichever lands
second.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Tejas Chopra
2026-10-10 09:00:25 -07:00
committed by GitHub
co-authored by Claude Opus 5.5
parent 25cc2d5863
commit 132cd583da
3 changed files with 7 additions and 279 deletions
-182
View File
@@ -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,
-19
View File
@@ -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"
@@ -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: