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.

Extract wire debug format policy (#1978)

JD Davis41ce14bd645d
diff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.py
index c21b24de8..7a415e882 100644
--- a/headroom/proxy/helpers.py
+++ b/headroom/proxy/helpers.py
@@ -24,7 +24,12 @@ from typing import TYPE_CHECKING, Any, Literal, cast
from headroom import paths as _paths
from headroom._subprocess import run
-from headroom.proxy import request_limit_policy, sse_byte_buffer_policy, wire_debug_redaction_policy
+from headroom.proxy import (
+ request_limit_policy,
+ sse_byte_buffer_policy,
+ wire_debug_format_policy,
+ wire_debug_redaction_policy,
+)
from headroom.proxy.body_forwarding import (
BodyMutationTracker as BodyMutationTracker, # noqa: F401 - compatibility export
)
@@ -119,7 +124,7 @@ def redact_for_wire_debug(value: Any) -> Any:
def _safe_event_name(event: str) -> str:
- return "".join(ch if ch.isalnum() or ch in ("-", "_") else "_" for ch in event)[:80]
+ return wire_debug_format_policy.safe_wire_debug_name(event)
def _wire_debug_preview(value: Any, *, max_chars: int | None = None) -> str:
@@ -130,22 +135,7 @@ def _wire_debug_preview(value: Any, *, max_chars: int | None = None) -> str:
deliberate trim boundary belongs.
"""
- try:
- if isinstance(value, bytes):
- text = value.decode("utf-8", errors="replace")
- elif isinstance(value, str):
- text = value
- elif value is None:
- return ""
- else:
- text = json.dumps(value, ensure_ascii=False, default=str, separators=(",", ":"))
- except Exception:
- text = repr(value)
-
- text = " ".join(text.split())
- if max_chars is not None and len(text) > max_chars:
- return text[: max_chars - 1] + "…"
- return text
+ return wire_debug_format_policy.wire_debug_preview(value, max_chars=max_chars)
def capture_codex_wire_debug(
diff --git a/headroom/proxy/wire_debug_format_policy.py b/headroom/proxy/wire_debug_format_policy.py
new file mode 100644
index 000000000..bb68b3ded
--- /dev/null
+++ b/headroom/proxy/wire_debug_format_policy.py
@@ -0,0 +1,35 @@
+"""Formatting policy for opt-in proxy wire debug artifacts."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+WIRE_DEBUG_NAME_MAX_CHARS = 80
+
+
+def safe_wire_debug_name(value: str) -> str:
+ """Return a filename-safe wire-debug name fragment."""
+ return "".join(ch if ch.isalnum() or ch in ("-", "_") else "_" for ch in value)[
+ :WIRE_DEBUG_NAME_MAX_CHARS
+ ]
+
+
+def wire_debug_preview(value: Any, *, max_chars: int | None = None) -> str:
+ """Return the compact wire payload preview used in proxy logs."""
+ try:
+ if isinstance(value, bytes):
+ text = value.decode("utf-8", errors="replace")
+ elif isinstance(value, str):
+ text = value
+ elif value is None:
+ return ""
+ else:
+ text = json.dumps(value, ensure_ascii=False, default=str, separators=(",", ":"))
+ except Exception:
+ text = repr(value)
+
+ text = " ".join(text.split())
+ if max_chars is not None and len(text) > max_chars:
+ return text[: max_chars - 1] + "…"
+ return text
diff --git a/tests/test_wire_debug_format_policy.py b/tests/test_wire_debug_format_policy.py
new file mode 100644
index 000000000..ed2a5b943
--- /dev/null
+++ b/tests/test_wire_debug_format_policy.py
@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from headroom.proxy.wire_debug_format_policy import (
+ WIRE_DEBUG_NAME_MAX_CHARS,
+ safe_wire_debug_name,
+ wire_debug_preview,
+)
+
+
+def test_safe_wire_debug_name_replaces_path_unsafe_characters() -> None:
+ assert safe_wire_debug_name("req/id:with spaces") == "req_id_with_spaces"
+
+
+def test_safe_wire_debug_name_caps_length() -> None:
+ assert safe_wire_debug_name("a" * 200) == "a" * WIRE_DEBUG_NAME_MAX_CHARS
+
+
+def test_wire_debug_preview_compacts_json_like_values() -> None:
+ preview = wire_debug_preview({"message": "hello\nworld", "count": 2})
+
+ assert preview == '{"message":"hello\\nworld","count":2}'
+
+
+def test_wire_debug_preview_decodes_bytes_and_truncates() -> None:
+ assert wire_debug_preview(b"hello world", max_chars=8) == "hello w…"
+
+
+def test_wire_debug_preview_returns_empty_string_for_none() -> None:
+ assert wire_debug_preview(None) == ""