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): emit turn_id linking agent-loop API calls from one user prompt

Garmc4464c066f73
diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.py
index a9625672c..6a19b10ba 100644
--- a/headroom/proxy/handlers/anthropic.py
+++ b/headroom/proxy/handlers/anthropic.py
@@ -308,6 +308,7 @@ class AnthropicHandlerMixin:
MAX_REQUEST_BODY_SIZE,
_get_image_compressor,
_read_request_json,
+ compute_turn_id,
)
from headroom.proxy.models import RequestLog
from headroom.proxy.modes import is_cache_mode, is_token_mode
@@ -1186,6 +1187,9 @@ class AnthropicHandlerMixin:
request_messages=body.get("messages")
if self.config.log_full_messages
else None,
+ turn_id=compute_turn_id(
+ model, body.get("system"), body.get("messages")
+ ),
)
)
@@ -1618,6 +1622,9 @@ class AnthropicHandlerMixin:
request_messages=messages
if self.config.log_full_messages
else None,
+ turn_id=compute_turn_id(
+ model, body.get("system"), body.get("messages")
+ ),
)
)
diff --git a/headroom/proxy/handlers/streaming.py b/headroom/proxy/handlers/streaming.py
index f14f107dd..f6298d97e 100644
--- a/headroom/proxy/handlers/streaming.py
+++ b/headroom/proxy/handlers/streaming.py
@@ -13,7 +13,7 @@ import time
from datetime import datetime
from typing import TYPE_CHECKING, Any
-from headroom.proxy.helpers import jitter_delay_ms
+from headroom.proxy.helpers import compute_turn_id, jitter_delay_ms
if TYPE_CHECKING:
from fastapi.responses import Response, StreamingResponse
@@ -1044,6 +1044,9 @@ class StreamingMixin:
request_messages=body.get("messages")
if self.config.log_full_messages
else None,
+ turn_id=compute_turn_id(
+ model, body.get("system"), body.get("messages")
+ ),
)
)
diff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.py
index c75d8436f..3ccbe0878 100644
--- a/headroom/proxy/helpers.py
+++ b/headroom/proxy/helpers.py
@@ -8,6 +8,7 @@ Extracted from server.py for maintainability.
from __future__ import annotations
+import hashlib
import json
import logging
import random
@@ -278,3 +279,69 @@ async def _read_request_json(request: Request) -> dict[str, Any]:
if not isinstance(result, dict):
raise ValueError("Request body must be a JSON object, not " + type(result).__name__)
return result
+
+
+def compute_turn_id(
+ model: str,
+ system: Any,
+ messages: list[dict[str, Any]] | None,
+) -> str | None:
+ """Group all agent-loop API calls triggered by a single user prompt.
+
+ A turn spans the user's text prompt plus every assistant tool-use and
+ user tool-result message the agent appends while executing that prompt.
+ Hashing the prefix up to and including the last user *text* message yields
+ an id that is stable across the turn but rolls over when the user sends a
+ new prompt.
+
+ Returns None when no user-text message is present (nothing to identify).
+ """
+ if not messages:
+ return None
+
+ last_text_user_idx: int | None = None
+ for i in range(len(messages) - 1, -1, -1):
+ msg = messages[i]
+ if not isinstance(msg, dict) or msg.get("role") != "user":
+ continue
+ content = msg.get("content")
+ if isinstance(content, str) and content:
+ last_text_user_idx = i
+ break
+ if isinstance(content, list):
+ has_text = any(
+ isinstance(block, dict) and block.get("type") == "text"
+ for block in content
+ )
+ has_tool_result = any(
+ isinstance(block, dict) and block.get("type") == "tool_result"
+ for block in content
+ )
+ # An agent-loop continuation carries tool_result blocks; only a
+ # fresh user turn is text-only.
+ if has_text and not has_tool_result:
+ last_text_user_idx = i
+ break
+
+ if last_text_user_idx is None:
+ return None
+
+ prefix = messages[: last_text_user_idx + 1]
+ try:
+ prefix_json = json.dumps(prefix, sort_keys=True, default=str)
+ except (TypeError, ValueError):
+ return None
+
+ h = hashlib.sha256()
+ h.update(model.encode("utf-8", errors="replace"))
+ h.update(b"\0")
+ if isinstance(system, str):
+ h.update(system.encode("utf-8", errors="replace"))
+ elif system is not None:
+ try:
+ h.update(json.dumps(system, sort_keys=True, default=str).encode("utf-8"))
+ except (TypeError, ValueError):
+ pass
+ h.update(b"\0")
+ h.update(prefix_json.encode("utf-8", errors="replace"))
+ return h.hexdigest()[:16]
diff --git a/headroom/proxy/models.py b/headroom/proxy/models.py
index 5708ee96a..c46f0878a 100644
--- a/headroom/proxy/models.py
+++ b/headroom/proxy/models.py
@@ -48,6 +48,11 @@ class RequestLog:
response_content: str | None = None
error: str | None = None
+ # Groups every agent-loop API call from one user prompt into a single turn.
+ # See ``headroom.proxy.helpers.compute_turn_id`` for the derivation. None
+ # when no user-text message is present in the request.
+ turn_id: str | None = None
+
# NOTE (Unit 2 follow-up): stage timings and session_id were briefly
# added here but are now emitted exclusively through
# ``emit_stage_timings_log`` (structured log line) and Prometheus.
diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py
index e96213507..f07e3c96b 100644
--- a/headroom/proxy/server.py
+++ b/headroom/proxy/server.py
@@ -1740,6 +1740,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
"transforms_applied": log.get("transforms_applied", []),
"request_messages": log.get("request_messages"),
"response_content": log.get("response_content"),
+ "turn_id": log.get("turn_id"),
}
)
diff --git a/tests/test_proxy/test_compute_turn_id.py b/tests/test_proxy/test_compute_turn_id.py
new file mode 100644
index 000000000..55d77f71a
--- /dev/null
+++ b/tests/test_proxy/test_compute_turn_id.py
@@ -0,0 +1,109 @@
+"""Tests for ``headroom.proxy.helpers.compute_turn_id``."""
+
+from __future__ import annotations
+
+from headroom.proxy.helpers import compute_turn_id
+
+
+MODEL = "claude-sonnet-4-5"
+SYSTEM = "You are helpful."
+
+
+def _user(text: str) -> dict:
+ return {"role": "user", "content": text}
+
+
+def _assistant_tool_use(tool_id: str, name: str) -> dict:
+ return {
+ "role": "assistant",
+ "content": [{"type": "tool_use", "id": tool_id, "name": name, "input": {}}],
+ }
+
+
+def _user_tool_result(tool_id: str, out: str) -> dict:
+ return {
+ "role": "user",
+ "content": [{"type": "tool_result", "tool_use_id": tool_id, "content": out}],
+ }
+
+
+def test_returns_none_when_messages_empty():
+ assert compute_turn_id(MODEL, SYSTEM, []) is None
+ assert compute_turn_id(MODEL, SYSTEM, None) is None
+
+
+def test_returns_none_when_no_user_text_message():
+ messages = [_assistant_tool_use("t1", "bash")]
+ assert compute_turn_id(MODEL, SYSTEM, messages) is None
+
+
+def test_stable_across_agent_loop_iterations():
+ iteration_1 = [_user("fix the bug")]
+ iteration_2 = iteration_1 + [
+ _assistant_tool_use("t1", "read"),
+ _user_tool_result("t1", "file contents"),
+ ]
+ iteration_3 = iteration_2 + [
+ _assistant_tool_use("t2", "edit"),
+ _user_tool_result("t2", "edit ok"),
+ ]
+
+ id1 = compute_turn_id(MODEL, SYSTEM, iteration_1)
+ id2 = compute_turn_id(MODEL, SYSTEM, iteration_2)
+ id3 = compute_turn_id(MODEL, SYSTEM, iteration_3)
+
+ assert id1 is not None
+ assert id1 == id2 == id3
+
+
+def test_rolls_over_on_new_user_prompt():
+ turn_1 = [_user("first prompt")]
+ turn_2 = turn_1 + [
+ _assistant_tool_use("t1", "bash"),
+ _user_tool_result("t1", "ok"),
+ _user("second prompt"),
+ ]
+
+ id1 = compute_turn_id(MODEL, SYSTEM, turn_1)
+ id2 = compute_turn_id(MODEL, SYSTEM, turn_2)
+
+ assert id1 != id2
+
+
+def test_different_model_yields_different_id():
+ messages = [_user("same prompt")]
+ id_a = compute_turn_id("claude-sonnet-4-5", SYSTEM, messages)
+ id_b = compute_turn_id("claude-opus-4-7", SYSTEM, messages)
+ assert id_a != id_b
+
+
+def test_different_system_yields_different_id():
+ messages = [_user("same prompt")]
+ id_a = compute_turn_id(MODEL, "system A", messages)
+ id_b = compute_turn_id(MODEL, "system B", messages)
+ assert id_a != id_b
+
+
+def test_accepts_list_system_prompt():
+ messages = [_user("hi")]
+ system_list = [{"type": "text", "text": "You are helpful."}]
+ assert compute_turn_id(MODEL, system_list, messages) is not None
+
+
+def test_text_block_in_list_content_is_a_user_turn():
+ messages = [{"role": "user", "content": [{"type": "text", "text": "hello"}]}]
+ assert compute_turn_id(MODEL, SYSTEM, messages) is not None
+
+
+def test_tool_result_only_content_is_not_a_turn_boundary():
+ # A message whose only content is a tool_result is a continuation, not a
+ # new turn — so the function must not latch onto it.
+ messages = [_user_tool_result("t1", "result only")]
+ assert compute_turn_id(MODEL, SYSTEM, messages) is None
+
+
+def test_returns_16_hex_chars():
+ turn_id = compute_turn_id(MODEL, SYSTEM, [_user("hi")])
+ assert turn_id is not None
+ assert len(turn_id) == 16
+ int(turn_id, 16) # raises if not hex