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.

fix(proxy): gate mid-turn message coalescing to Claude Code clients (#1643)

TenderDevea4bd2e62a5bb
diff --git a/headroom/proxy/auth_mode.py b/headroom/proxy/auth_mode.py
index 2c7e97021..97a76259a 100644
--- a/headroom/proxy/auth_mode.py
+++ b/headroom/proxy/auth_mode.py
@@ -162,6 +162,28 @@ def should_stamp_codex_client(path: str, headers: Mapping[str, Any] | Any) -> bo
return should_stamp_codex_client_signals(path, _auth_signals(headers))
+# Client harnesses that can consume Headroom's mid-turn message-coalescing
+# protocol: the 202 ``headroom_queued`` reply and the synthetic
+# ``headroom_pending_messages`` SSE event. This is a custom protocol only Claude
+# Code parses today; other harnesses would receive events they can't decode, so
+# a concurrent same-session request from them must stream normally instead of
+# being queued and replayed. Keeping the capability in one named place — rather
+# than scattering ``client == "claude-code"`` string checks across the request
+# handlers — makes it a single, documented decision to revisit as more clients
+# learn the protocol (#1608).
+_COALESCING_CAPABLE_CLIENTS = frozenset({"claude-code"})
+
+
+def supports_mid_turn_coalescing(client: str | None) -> bool:
+ """Whether ``client`` can consume the mid-turn coalescing protocol.
+
+ ``client`` is a value returned by :func:`classify_client`. See
+ :data:`_COALESCING_CAPABLE_CLIENTS` for why the set is currently limited to
+ Claude Code.
+ """
+ return client in _COALESCING_CAPABLE_CLIENTS
+
+
__all__ = [
"AuthMode",
"CLIENT_UA_MAP",
@@ -170,4 +192,5 @@ __all__ = [
"classify_auth_mode",
"classify_client",
"should_stamp_codex_client",
+ "supports_mid_turn_coalescing",
]
diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.py
index 059fdb8f0..9e79e3a27 100644
--- a/headroom/proxy/handlers/anthropic.py
+++ b/headroom/proxy/handlers/anthropic.py
@@ -27,7 +27,11 @@ from headroom.agent_savings import proxy_pipeline_kwargs
from headroom.ccr.context_tracker import looks_like_claude_code_compact_summary
from headroom.copilot_auth import build_copilot_upstream_url
from headroom.pipeline import PipelineStage, summarize_routing_markers
-from headroom.proxy.auth_mode import classify_auth_mode, classify_client
+from headroom.proxy.auth_mode import (
+ classify_auth_mode,
+ classify_client,
+ supports_mid_turn_coalescing,
+)
from headroom.proxy.compression_decision import CompressionDecision
from headroom.proxy.forwarded_headers import resolve_client_ip
from headroom.proxy.handlers._debug_dump import _debug_dump_mode, _redact_debug_value
@@ -3024,11 +3028,18 @@ class AnthropicHandlerMixin:
body,
session_header=explicit_session_header,
)
- # Only opt-in (header-bearing) callers participate in
- # mid-turn steering; see StreamingMixin._should_queue_mid_turn
- # for why the coarse md5 fallback must not queue concurrent
- # independent streams (it wrongly 202s a streaming caller).
- if self._should_queue_mid_turn(session_key, explicit_session_header):
+ # Coalesce mid-turn messages only for Claude Code, the sole
+ # client that understands the 202 `headroom_queued` reply and
+ # the `headroom_pending_messages` SSE event. Other harnesses
+ # (e.g. OpenCode subagents sharing a body-derived session key)
+ # would otherwise have their request swallowed and never
+ # answered. (#1608) `_should_queue_mid_turn` further restricts
+ # this to opt-in (header-bearing) callers with an active
+ # stream, so the coarse md5 fallback can't 202 a streaming
+ # caller.
+ if supports_mid_turn_coalescing(
+ classify_client(request.headers)
+ ) and self._should_queue_mid_turn(session_key, explicit_session_header):
from fastapi.responses import JSONResponse
queued = self._queue_mid_turn_message(session_key, body)
diff --git a/headroom/proxy/handlers/streaming.py b/headroom/proxy/handlers/streaming.py
index ef9600381..07d4f70be 100644
--- a/headroom/proxy/handlers/streaming.py
+++ b/headroom/proxy/handlers/streaming.py
@@ -12,7 +12,7 @@ import logging
import time
from typing import TYPE_CHECKING, Any
-from headroom.proxy.auth_mode import classify_client
+from headroom.proxy.auth_mode import classify_client, supports_mid_turn_coalescing
from headroom.proxy.helpers import (
RETRYABLE_OVERLOAD_STATUSES,
jitter_delay_ms,
@@ -1033,7 +1033,6 @@ class StreamingMixin:
4. Streams the final response to the client
"""
session_key = session_key or self._get_session_key(body)
- self._active_streams.add(session_key)
# Guard everything up to the generator's own try/finally (which owns
# cleanup once streaming starts): any exception here — including
@@ -1106,6 +1105,15 @@ class StreamingMixin:
# ...) from the *client's* User-Agent before copilot-auth
# potentially rewrites headers for upstream.
client = classify_client(headers)
+ # Mid-turn message coalescing (queueing a concurrent same-session
+ # request and later replaying it via a `headroom_pending_messages`
+ # SSE event) is a Claude Code-only protocol. Only register the stream
+ # as active for coalescing when the client can consume that protocol,
+ # so concurrent requests from other harnesses (e.g. OpenCode subagents
+ # that share a body-derived session key) are streamed normally instead
+ # of being swallowed. (#1608)
+ if supports_mid_turn_coalescing(client):
+ self._active_streams.add(session_key)
headers = await apply_copilot_api_auth(headers, url=url)
start_time = time.time()
@@ -1651,7 +1659,7 @@ class StreamingMixin:
client=client,
waste_signals=waste_signals,
)
- if pending_messages:
+ if supports_mid_turn_coalescing(client) and pending_messages:
pending_event = json.dumps(
{"type": "headroom_pending_messages", "messages": pending_messages}
)
diff --git a/tests/test_mid_turn_steering.py b/tests/test_mid_turn_steering.py
index 1776190a6..81534ae0d 100644
--- a/tests/test_mid_turn_steering.py
+++ b/tests/test_mid_turn_steering.py
@@ -201,3 +201,115 @@ class TestMidTurnSteering:
finally:
proxy._active_streams.discard(session_key)
proxy._mid_turn_queues.pop(session_key, None)
+
+ # --- #1608: mid-turn coalescing must be gated to Claude Code clients ---
+
+ def _normal_stream(self):
+ return self._create_mock_upstream_response(
+ [
+ b'event: message_start\ndata: {"type":"message_start"}\n\n',
+ b'event: message_stop\ndata: {"type":"message_stop"}\n\n',
+ ]
+ )
+
+ async def _run_stream(self, proxy, session_key, user_agent):
+ mock_response = self._normal_stream()
+ proxy.http_client.build_request = MagicMock(return_value=MagicMock())
+ proxy.http_client.send = AsyncMock(return_value=mock_response)
+ return await proxy._stream_response(
+ url="https://api.anthropic.com/v1/messages",
+ headers={"x-api-key": "sk-test", "user-agent": user_agent},
+ body={
+ "model": "claude-sonnet-4-20250514",
+ "max_tokens": 100,
+ "stream": True,
+ "messages": [{"role": "user", "content": "hi"}],
+ },
+ provider="anthropic",
+ model="claude-sonnet-4-20250514",
+ request_id="test-1608",
+ original_tokens=10,
+ optimized_tokens=10,
+ tokens_saved=0,
+ transforms_applied=[],
+ tags={},
+ optimization_latency=0.0,
+ session_key=session_key,
+ )
+
+ @pytest.mark.asyncio
+ async def test_non_claude_client_not_registered_active(self):
+ # An OpenCode subagent shares the main agent's body-derived session
+ # key; if it registered as active, the concurrent request would be
+ # swallowed. Non-Claude-Code clients must never be registered.
+ proxy = self._create_mock_proxy()
+ session_key = "opencode-session"
+ result = await self._run_stream(proxy, session_key, "opencode/1.0")
+ try:
+ assert session_key not in proxy._active_streams
+ finally:
+ async for _chunk in result.body_iterator:
+ pass
+ proxy._active_streams.discard(session_key)
+ proxy._mid_turn_queues.pop(session_key, None)
+
+ @pytest.mark.asyncio
+ async def test_claude_code_client_registered_active(self):
+ proxy = self._create_mock_proxy()
+ session_key = "claude-session"
+ result = await self._run_stream(proxy, session_key, "claude-code/1.2.3")
+ try:
+ assert session_key in proxy._active_streams
+ finally:
+ async for _chunk in result.body_iterator:
+ pass
+ proxy._active_streams.discard(session_key)
+ proxy._mid_turn_queues.pop(session_key, None)
+
+ @pytest.mark.asyncio
+ async def test_pending_event_not_emitted_for_non_claude(self):
+ # Even with a queued message, a non-Claude-Code stream must not emit the
+ # custom `headroom_pending_messages` SSE event — @ai-sdk/anthropic can't
+ # parse it and throws "invalid_union / No matching discriminator".
+ proxy = self._create_mock_proxy()
+ session_key = "opencode-pending"
+ proxy._queue_mid_turn_message(
+ session_key, {"messages": [{"role": "user", "content": "queued"}]}
+ )
+ result = await self._run_stream(proxy, session_key, "opencode/1.0")
+ try:
+ body = b"".join([chunk async for chunk in result.body_iterator])
+ assert b"headroom_pending_messages" not in body
+ finally:
+ proxy._active_streams.discard(session_key)
+ proxy._mid_turn_queues.pop(session_key, None)
+
+ @pytest.mark.asyncio
+ async def test_pending_event_emitted_for_claude_code(self):
+ proxy = self._create_mock_proxy()
+ session_key = "claude-pending"
+ proxy._queue_mid_turn_message(
+ session_key, {"messages": [{"role": "user", "content": "queued"}]}
+ )
+ result = await self._run_stream(proxy, session_key, "claude-code/1.2.3")
+ try:
+ body = b"".join([chunk async for chunk in result.body_iterator])
+ assert b"headroom_pending_messages" in body
+ finally:
+ proxy._active_streams.discard(session_key)
+ proxy._mid_turn_queues.pop(session_key, None)
+
+
+class TestCoalescingCapability:
+ """The capability predicate that gates the mid-turn coalescing protocol."""
+
+ def test_claude_code_supports_coalescing(self):
+ from headroom.proxy.auth_mode import supports_mid_turn_coalescing
+
+ assert supports_mid_turn_coalescing("claude-code") is True
+
+ def test_other_clients_do_not_support_coalescing(self):
+ from headroom.proxy.auth_mode import supports_mid_turn_coalescing
+
+ for client in ("opencode", "codex", "cursor", "aider", "", None):
+ assert supports_mid_turn_coalescing(client) is False