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.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
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.pyindex 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 RequestLogfrom 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_messageselse None,+ turn_id=compute_turn_id(+ model, body.get("system"), body.get("messages")+ ),))@@ -1618,6 +1622,9 @@ class AnthropicHandlerMixin:request_messages=messagesif self.config.log_full_messageselse 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.pyindex f14f107dd..f6298d97e 100644--- a/headroom/proxy/handlers/streaming.py+++ b/headroom/proxy/handlers/streaming.py@@ -13,7 +13,7 @@ import timefrom datetime import datetimefrom typing import TYPE_CHECKING, Any-from headroom.proxy.helpers import jitter_delay_ms+from headroom.proxy.helpers import compute_turn_id, jitter_delay_msif TYPE_CHECKING:from fastapi.responses import Response, StreamingResponse@@ -1044,6 +1044,9 @@ class StreamingMixin:request_messages=body.get("messages")if self.config.log_full_messageselse None,+ turn_id=compute_turn_id(+ model, body.get("system"), body.get("messages")+ ),))diff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.pyindex 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 hashlibimport jsonimport loggingimport 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.pyindex 5708ee96a..c46f0878a 100644--- a/headroom/proxy/models.py+++ b/headroom/proxy/models.py@@ -48,6 +48,11 @@ class RequestLog:response_content: str | None = Noneerror: 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.pyindex 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.pynew file mode 100644index 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