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.

feat(proxy): let /transformations/feed omit message bodies for number-only pollers (#3672)

gglucass46ac52d39d6d
diff --git a/headroom/proxy/request_logger.py b/headroom/proxy/request_logger.py
index 89a6fe9b6..ef79ad71e 100644
--- a/headroom/proxy/request_logger.py
+++ b/headroom/proxy/request_logger.py
@@ -165,10 +165,23 @@ class RequestLogger:
for e in entries
]
- def get_recent_with_messages(self, n: int = 20) -> list[dict]:
- """Get recent log entries including full request/response messages."""
+ def get_recent_with_messages(self, n: int = 20, include_messages: bool = True) -> list[dict]:
+ """Get recent log entries including full request/response messages.
+
+ ``include_messages=False`` returns the same entries without
+ ``request_messages`` / ``compressed_messages`` / ``response_content``,
+ and without walking them: ``asdict`` deep-copies every field, so a
+ caller that only reads the per-request numbers otherwise pays for a
+ full copy of each transcript (~160 KB per Claude Code turn, ~44 MB per
+ ``limit=100`` feed pull) on the event loop.
+ """
entries = list(self._logs)[-n:]
- return [asdict(e) for e in entries]
+ if include_messages:
+ return [asdict(e) for e in entries]
+ return [
+ {f.name: deepcopy(getattr(e, f.name)) for f in fields(e) if f.name not in _HEAVY_FIELDS}
+ for e in entries
+ ]
def stats(self) -> dict:
"""Get logging statistics."""
diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py
index a2371960a..e51165ee1 100644
--- a/headroom/proxy/server.py
+++ b/headroom/proxy/server.py
@@ -4967,9 +4967,15 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
return proxy.metrics.savings_tracker.history_response(history_mode=history_mode)
@app.get("/transformations/feed", dependencies=[Depends(_require_loopback)])
- async def transformations_feed(limit: int = 20):
+ async def transformations_feed(limit: int = 20, include_messages: bool = True):
"""Get recent message transformations for the live feed.
+ ``?include_messages=0`` omits the three message-body fields, and skips
+ copying them server-side, for pollers that only read the per-request
+ numbers. A ``limit=100`` pull with bodies is ~44 MB and its
+ serialization blocks the event loop; the dashboard's live feed keeps
+ the default.
+
Loopback-only: when ``log_full_messages`` is enabled this returns the
full request/response message bodies (prompt content and completions)
via ``request_messages`` / ``compressed_messages`` / ``response_content``.
@@ -4987,29 +4993,36 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
log_full_messages = proxy.config.log_full_messages if proxy else False
if proxy and proxy.logger:
- logs = proxy.logger.get_recent_with_messages(limit)
+ logs = proxy.logger.get_recent_with_messages(limit, include_messages=include_messages)
for log in logs:
- transformations.append(
- {
- "request_id": log.get("request_id"),
- "timestamp": log.get("timestamp"),
- "provider": resolve_display_provider(
- log.get("provider"),
- openai_api_url=proxy.config.openai_api_url,
- provider_name=proxy.config.provider_name,
- ),
- "model": log.get("model"),
- "input_tokens_original": log.get("input_tokens_original"),
- "input_tokens_optimized": log.get("input_tokens_optimized"),
- "tokens_saved": log.get("tokens_saved"),
- "savings_percent": log.get("savings_percent"),
- "transforms_applied": log.get("transforms_applied", []),
- "request_messages": log.get("request_messages"),
- "compressed_messages": log.get("compressed_messages"),
- "response_content": log.get("response_content"),
- "turn_id": log.get("turn_id"),
- }
- )
+ item = {
+ "request_id": log.get("request_id"),
+ "timestamp": log.get("timestamp"),
+ "provider": resolve_display_provider(
+ log.get("provider"),
+ openai_api_url=proxy.config.openai_api_url,
+ provider_name=proxy.config.provider_name,
+ ),
+ "model": log.get("model"),
+ "input_tokens_original": log.get("input_tokens_original"),
+ "input_tokens_optimized": log.get("input_tokens_optimized"),
+ "tokens_saved": log.get("tokens_saved"),
+ "savings_percent": log.get("savings_percent"),
+ "transforms_applied": log.get("transforms_applied", []),
+ "turn_id": log.get("turn_id"),
+ # Per-request prefix-cache split, so a number-only poller can put
+ # tokens_saved on the new-input basis /stats reports as
+ # new_input_savings_percent (saved / (saved + uncached + cache_write))
+ # instead of the full-transcript basis of savings_percent.
+ "uncached_input_tokens": log.get("uncached_input_tokens", 0),
+ "cache_write_tokens": log.get("cache_write_tokens", 0),
+ "cache_read_tokens": log.get("cache_read_tokens", 0),
+ }
+ if include_messages:
+ item["request_messages"] = log.get("request_messages")
+ item["compressed_messages"] = log.get("compressed_messages")
+ item["response_content"] = log.get("response_content")
+ transformations.append(item)
return {"transformations": transformations, "log_full_messages": log_full_messages}
diff --git a/tests/test_proxy/test_request_logger.py b/tests/test_proxy/test_request_logger.py
index a2ca71218..124e66878 100644
--- a/tests/test_proxy/test_request_logger.py
+++ b/tests/test_proxy/test_request_logger.py
@@ -132,3 +132,27 @@ def test_get_recent_never_walks_message_payloads():
again = logger.get_recent(10)[0]
assert again["tags"] == {"agent": "codex", "meta": {"depth": 1}}
assert again["savings_breakdown"] == [{"tokens": 60}]
+
+
+def test_get_recent_with_messages_can_skip_payloads_without_walking_them():
+ """A feed poller that only reads the numbers passes include_messages=False;
+ the three body fields are absent and never traversed (asdict deep-copied
+ them). A leaf that refuses to be deep-copied proves the walk is gone."""
+
+ class _NoCopy:
+ def __deepcopy__(self, memo):
+ raise AssertionError("get_recent_with_messages walked a message payload")
+
+ logger = RequestLogger(log_file=None, log_full_messages=True)
+ logger.log(
+ _entry(
+ request_messages=[{"role": "user", "content": _NoCopy()}],
+ compressed_messages=[{"role": "user", "content": _NoCopy()}],
+ response_content="ok",
+ )
+ )
+
+ slim = logger.get_recent_with_messages(10, include_messages=False)
+ assert slim[0]["tokens_saved"] == 60
+ assert slim[0]["transforms_applied"] == ["kompress:user:0.4"]
+ assert not {"request_messages", "compressed_messages", "response_content"} & slim[0].keys()
diff --git a/tests/test_proxy/test_transformations_feed.py b/tests/test_proxy/test_transformations_feed.py
index 280ad460d..c7834c43b 100644
--- a/tests/test_proxy/test_transformations_feed.py
+++ b/tests/test_proxy/test_transformations_feed.py
@@ -7,6 +7,7 @@ pytest.importorskip("fastapi")
from httpx import ASGITransport, AsyncClient
+from headroom.proxy.models import RequestLog
from headroom.proxy.server import create_app
@@ -67,3 +68,55 @@ async def test_transformations_feed_respects_limit(app):
data = response.json()
assert len(data["transformations"]) <= 5
+
+
+async def test_transformations_feed_can_omit_message_bodies(app):
+ """``?include_messages=0`` is for pollers that only read the numbers: the
+ three body fields are absent (not null) and every other field is the same
+ as the full response."""
+ app.state.proxy.logger.log(
+ RequestLog(
+ request_id="r1",
+ timestamp="2026-04-24T10:00:00Z",
+ provider="anthropic",
+ model="claude-sonnet-4-6",
+ input_tokens_original=100,
+ input_tokens_optimized=40,
+ output_tokens=10,
+ tokens_saved=60,
+ savings_percent=60.0,
+ optimization_latency_ms=1.0,
+ total_latency_ms=20.0,
+ tags={},
+ cache_hit=False,
+ transforms_applied=["kompress:user:0.4"],
+ cache_read_tokens=1000,
+ cache_write_tokens=5,
+ uncached_input_tokens=30,
+ request_messages=[{"role": "user", "content": "hi"}],
+ compressed_messages=[{"role": "user", "content": "hi"}],
+ response_content="ok",
+ )
+ )
+ async with AsyncClient(
+ transport=ASGITransport(app=app, client=("127.0.0.1", 12345)),
+ base_url="http://127.0.0.1",
+ ) as client:
+ full = (await client.get("/transformations/feed?limit=1")).json()
+ slim = (await client.get("/transformations/feed?limit=1&include_messages=0")).json()
+
+ full_item = full["transformations"][0]
+ slim_item = slim["transformations"][0]
+ assert full_item["request_messages"] == [{"role": "user", "content": "hi"}]
+ bodies = {"request_messages", "compressed_messages", "response_content"}
+ assert not bodies & slim_item.keys()
+ # The prefix-cache split rides along, so a poller can rate tokens_saved
+ # against new input (uncached + cache_write) like /stats does.
+ assert (
+ slim_item["uncached_input_tokens"],
+ slim_item["cache_write_tokens"],
+ slim_item["cache_read_tokens"],
+ ) == (30, 5, 1000)
+ assert {k: v for k, v in full_item.items() if k not in bodies} == slim_item
+ assert slim["log_full_messages"] == full["log_full_messages"]