fix: surface Codex responses traffic in dashboard (#399)

## Description

Fixes Codex `/v1/responses` traffic not showing up correctly in
Headroom’s dashboard-visible telemetry surfaces.

This branch restores Python-side fallback handling for OpenAI/Codex
Responses API traffic so that when the Python proxy handles
`/v1/responses` directly, request compression + telemetry are still
recorded instead of appearing as pass-through /
 zero-savings traffic.

## Problem

Issue: #310

Codex traffic over `/v1/responses` was reaching Headroom, but
dashboard-visible request surfaces could stay stale or misleading
because:

- Python fallback handling for `/v1/responses` did not properly compress
Responses-shaped input
- WebSocket `response.create` traffic was not consistently turned into
request log entries comparable to other paths
- Codex tool-output item types such as `local_shell_call_output` and
`apply_patch_call_output` were not treated as compressible tool content
in the Python fallback path

Result:
- real Codex traffic could flow through Headroom
- compression savings could remain `0`
- recent request telemetry could be incomplete or misleading for
`/v1/responses`

## Changes Made

### Proxy behavior
- Re-enabled Python fallback compression for `/v1/responses`
- Convert Responses API item input into chat-style messages before
compression
- Reconstruct Responses API items after compression before forwarding
upstream
- Compress first WebSocket `response.create` frames for Python-handled
`/v1/responses`
- Record request telemetry for these Responses API paths so
dashboard-visible request surfaces reflect Codex traffic

### Responses item handling
- Added `headroom/proxy/responses_converter.py`
- Supports conversion/reconstruction for Responses API payloads
- Treats these output item types as compressible tool content:
  - `function_call_output`
  - `local_shell_call_output`
  - `apply_patch_call_output`

### Tests
Added/updated regression coverage for:
- HTTP `/v1/responses` compression path
- WebSocket `/v1/responses` lifecycle + telemetry path
- Responses item conversion/reconstruction behavior

## Files

- `headroom/proxy/handlers/openai.py`
- `headroom/proxy/responses_converter.py`
- `tests/test_openai_codex_routing.py`
- `tests/test_openai_codex_ws_lifecycle.py`
- `tests/test_responses_converter.py`

## Testing

- [x] Focused Responses HTTP/WebSocket tests pass
- [x] Current-main dashboard and compression regressions pass

### Test Output

Ran:

```bash
HEADROOM_REQUIRE_RUST_CORE=false .venv/bin/python -m pytest \
  tests/test_responses_converter.py \
  tests/test_openai_codex_ws_lifecycle.py \
  tests/test_openai_codex_routing.py -q
```
Result:

 ```text
21 passed
 ```

## Type of Change

- [x] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring

## Real Behavior Proof

- Environment: current-main reconciled OpenAI Responses proxy and
dashboard test environment.
- Exact command / steps: ran focused Responses routing/WebSocket tests
and current compression-unit, dashboard-cache, and savings-history
regressions; rendered the dashboard screenshot artifact.
- Observed result: Responses traffic contributes compression and request
telemetry, historical items remain compressible while the current user
turn is protected, and dashboard session data refreshes correctly.
- Not tested: a long-running production Codex session under sustained
WebSocket traffic.

## Review Readiness

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

---------

Co-authored-by: Kayzo <kayzo@users.noreply.github.com>
Co-authored-by: JD Davis <jd@jds-macbook-air.tail2a279.ts.net>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
This commit is contained in:
Mohamed EL HAJJAJI
2026-10-01 22:05:58 -05:00
committed by GitHub
co-authored by Kayzo JD Davis JerrettDavis
parent f90a56b038
commit ecc496709b
8 changed files with 175 additions and 31 deletions
Binary file not shown.

After

Width:  |  Height:  |  Size: 260 KiB

+26 -21
View File
@@ -2134,15 +2134,26 @@
return /^\d+\.\d+\.\d+$/.test(label) ? 'v' + label : label;
},
async fetchJson(url) {
const separator = url.includes('?') ? '&' : '?';
const response = await fetch(`${url}${separator}_=${Date.now()}`, {
cache: 'no-store',
headers: { 'Cache-Control': 'no-cache' }
});
if (!response.ok) {
throw new Error(`HTTP ${response.status} for ${url}`);
}
return await response.json();
},
async fetchStats() {
try {
const [statsRes, healthRes] = await Promise.all([
fetch('/stats?cached=1'),
fetch('/health')
const [stats, health] = await Promise.all([
this.fetchJson('/stats?cached=1'),
this.fetchJson('/health')
]);
this.stats = await statsRes.json();
const health = await healthRes.json();
this.stats = stats;
this.healthy = health.status === 'healthy';
this.version = health.version || 'unknown';
this.log_full_messages = this.stats.log_full_messages || false;
@@ -2175,11 +2186,8 @@
},
async fetchHistoryStats() {
try {
const response = await fetch('/stats-history');
if (response.ok) {
this.historyStats = await response.json();
this.lastHistoryFetchMs = Date.now();
}
this.historyStats = await this.fetchJson('/stats-history');
this.lastHistoryFetchMs = Date.now();
} catch (e) {
console.error('Failed to fetch history stats:', e);
}
@@ -2188,18 +2196,15 @@
async fetchTransformations() {
try {
const prevLen = this.transformations.length;
const response = await fetch('/transformations/feed?limit=50');
if (response.ok) {
const data = await response.json();
const newLen = (data.transformations || []).length;
if (this.feedScrolled_ && newLen > prevLen) {
this.feedNewCount = newLen - prevLen;
}
this.transformations = data.transformations || [];
this.log_full_messages = data.log_full_messages ?? this.log_full_messages;
this.lastFeedFetchMs = Date.now();
this.renderTransformations();
const data = await this.fetchJson('/transformations/feed?limit=50');
const newLen = (data.transformations || []).length;
if (this.feedScrolled_ && newLen > prevLen) {
this.feedNewCount = newLen - prevLen;
}
this.transformations = data.transformations || [];
this.log_full_messages = data.log_full_messages ?? this.log_full_messages;
this.lastFeedFetchMs = Date.now();
this.renderTransformations();
} catch (e) {
console.error('Failed to fetch transformations:', e);
}
+94 -6
View File
@@ -1835,6 +1835,7 @@ class OpenAIHandlerMixin:
return await count_tokens_offloaded(self, model, messages)
OPENAI_RESPONSES_ROUTER_MIN_BYTES = 512
OPENAI_RESPONSES_MESSAGE_ROUTER_MIN_BYTES = 8192
OPENAI_RESPONSES_OUTPUT_TYPES = _RESPONSES_OUTPUT_ITEM_TYPES
def _openai_responses_unit_cache(self) -> tuple[Any, OrderedDict[str, Any]]:
@@ -2177,12 +2178,22 @@ class OpenAIHandlerMixin:
return payload, False, 0, [], {}, [], 0
def _slot_texts(item: dict[str, Any]) -> list[tuple[str, tuple[str, int | None]]]:
# Only tool-output items are eligible for in-place compression.
# Message items (user/system/assistant) sit inside the request's
# cacheable prefix; mutating them busts prefix caching on every
# subsequent turn. Role-level guards in compression_units.py
# remain as defense-in-depth.
# Tool outputs and historical message text are eligible for
# in-place compression. The current user message is filtered below.
type_tag = item.get("type")
if type_tag == "message":
content = item.get("content")
if isinstance(content, str):
return [(content, ("content", None))]
if not isinstance(content, list):
return []
return [
(part["text"], ("content_text", index))
for index, part in enumerate(content)
if isinstance(part, dict)
and part.get("type") in {"input_text", "output_text", "text"}
and isinstance(part.get("text"), str)
]
if type_tag not in self.OPENAI_RESPONSES_OUTPUT_TYPES:
return []
output = item.get("output")
@@ -2214,6 +2225,20 @@ class OpenAIHandlerMixin:
if isinstance(part, dict) and part.get("type") in {"input_text", "output_text"}:
part["text"] = replacement
return True
if kind == "content":
item["content"] = replacement
return True
if kind == "content_text" and isinstance(index, int):
content = item.get("content")
if isinstance(content, list) and 0 <= index < len(content):
part = content[index]
if isinstance(part, dict) and part.get("type") in {
"input_text",
"output_text",
"text",
}:
part["text"] = replacement
return True
return False
headroom_retrieve_call_ids: set[str] = set()
@@ -2350,6 +2375,16 @@ class OpenAIHandlerMixin:
# 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
for idx, item in enumerate(items)
if isinstance(item, dict)
and item.get("type") == "message"
and item.get("role") == "user"
),
default=-1,
)
for idx, item in enumerate(items):
if not isinstance(item, dict):
if debug_enabled:
@@ -2492,6 +2527,48 @@ class OpenAIHandlerMixin:
"item": item,
}
)
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(
@@ -2556,6 +2633,16 @@ class OpenAIHandlerMixin:
item = items[item_idx] if item_idx < len(items) else {}
item_type = item.get("type", "unknown") if isinstance(item, dict) else "unknown"
role = str(item.get("role") or "tool") if isinstance(item, dict) else "tool"
metadata: dict[str, str] = {}
if role == "assistant":
metadata["compress_assistant"] = "true"
if role == "user" and item_idx != last_user_item_idx:
metadata["compress_user"] = "true"
min_bytes = (
self.OPENAI_RESPONSES_MESSAGE_ROUTER_MIN_BYTES
if item_type == "message"
else self.OPENAI_RESPONSES_ROUTER_MIN_BYTES
)
unit = CompressionUnit(
text=original_text,
provider="openai",
@@ -2564,7 +2651,8 @@ class OpenAIHandlerMixin:
item_type=str(item_type),
cache_zone="live",
mutable=True,
min_bytes=self.OPENAI_RESPONSES_ROUTER_MIN_BYTES,
min_bytes=min_bytes,
metadata=metadata,
)
routed_units.append(RoutedCompressionUnit(unit=unit, slot=(item_idx, slot_ref)))
if debug_enabled:
+1 -1
View File
@@ -256,7 +256,7 @@ def compress_unit_with_router(
if not unit.mutable:
return _with_reason(reason="immutable")
if unit.role == "user":
if unit.role == "user" and unit.metadata.get("compress_user") != "true":
return _with_reason(reason="protected_user_message")
if unit.role in {"system", "developer"}:
return _with_reason(reason="protected_system_message")
+1 -1
View File
@@ -5500,7 +5500,7 @@ class ContentRouter(Transform):
protect_analysis = kwargs.get(
"protect_analysis_context", self.config.protect_analysis_context
)
min_tokens = kwargs.get("min_tokens_to_compress", 50)
min_tokens = int(kwargs.get("min_tokens_to_compress", 50) or 50)
# Cache-safety knobs for content-block (Anthropic-format) handling:
compress_assistant_text_blocks = kwargs.get(
"compress_assistant_text_blocks",
@@ -1365,3 +1365,53 @@ def test_openai_responses_cache_mode_never_batches_old_small_outputs():
assert calls == []
assert modified is False
assert second["input"][:4] == first["input"]
def test_openai_responses_adapter_compresses_historical_messages_not_current_user():
router = ContentRouter()
def compress(self, content: str, **_kwargs) -> RouterCompressionResult:
return RouterCompressionResult(
compressed="compressed history",
original=content,
strategy_used=CompressionStrategy.KOMPRESS,
)
router.compress = MethodType(compress, router)
handler = _handler_with_router(router)
historical_text = " ".join(f"history{i}" for i in range(2000))
current_text = " ".join(f"current{i}" for i in range(2000))
payload = {
"model": "gpt-5",
"input": [
{
"type": "message",
"role": "user",
"content": [{"type": "input_text", "text": historical_text}],
},
{
"type": "message",
"role": "assistant",
"content": [{"type": "output_text", "text": historical_text}],
},
{
"type": "message",
"role": "user",
"content": [{"type": "input_text", "text": current_text}],
},
],
}
new_payload, modified, saved, transforms, units_by_category, _chain, _attempted = (
handler._compress_openai_responses_live_text_units_with_router(
payload, model="gpt-5", request_id="req_history"
)
)
assert modified is True
assert saved > 0
assert new_payload["input"][0]["content"][0]["text"] == "compressed history"
assert new_payload["input"][1]["content"][0]["text"] == "compressed history"
assert new_payload["input"][2]["content"][0]["text"] == current_text
assert units_by_category == {"applied": 2}
assert any(t.startswith("router:openai:responses:message:") for t in transforms)
+2 -1
View File
@@ -175,7 +175,8 @@ def test_stats_reset_clears_runtime_proxy_counters(monkeypatch: pytest.MonkeyPat
def test_dashboard_uses_cached_stats_and_lazy_history_feed_polling() -> None:
html = get_dashboard_html()
assert "fetch('/stats?cached=1')" in html
assert "this.fetchJson('/stats?cached=1')" in html
assert "cache: 'no-store'" in html
assert "version: 'loading'" in html
assert 'x-text="formatVersion(version)"' in html
assert "return /^\\d+\\.\\d+\\.\\d+$/.test(label)" in html
+1 -1
View File
@@ -1488,7 +1488,7 @@ def test_dashboard_includes_history_toggle_and_endpoint(tmp_path, monkeypatch):
html = response.text
assert "Session" in html
assert "Historical" in html
assert "fetch('/stats-history')" in html
assert "this.fetchJson('/stats-history')" in html
assert "Export CSV" in html
assert "Weekly Savings" in html
assert "Monthly Savings" in html