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
fix: A8 — SSE delta arms, UTF-8 buffer, phase preservation, request-id, 413
chopratejas148ded392aef
diff --git a/crates/headroom-proxy/src/error.rs b/crates/headroom-proxy/src/error.rsindex b7a09729f..646548a18 100644--- a/crates/headroom-proxy/src/error.rs+++ b/crates/headroom-proxy/src/error.rs@@ -21,6 +21,13 @@ pub enum ProxyError {#[error("io error: {0}")]Io(#[from] std::io::Error),+ /// PR-A8 / P5-59: request body exceeded the configured cap. RFC 7231+ /// §6.5.11: 413 Payload Too Large. Previously surfaced as+ /// `InvalidHeader` (400) which mis-classified an oversize body as a+ /// header parse error; clients with retry-on-413 logic broke.+ #[error("request body exceeds configured limit: {0}")]+ PayloadTooLarge(String),+/// Surfaced when `--compression` is enabled but the proxy can't/// build the IntelligentContextManager at startup (e.g. the/// embedded tokenizer asset failed to initialize). Bubbles up to@@ -46,6 +53,7 @@ impl IntoResponse for ProxyError {ProxyError::Upstream(_) => (StatusCode::BAD_GATEWAY, self.to_string()),ProxyError::InvalidUpstream(_) => (StatusCode::BAD_GATEWAY, self.to_string()),ProxyError::InvalidHeader(_) => (StatusCode::BAD_REQUEST, self.to_string()),+ ProxyError::PayloadTooLarge(_) => (StatusCode::PAYLOAD_TOO_LARGE, self.to_string()),ProxyError::WebSocket(_) => (StatusCode::BAD_GATEWAY, self.to_string()),ProxyError::Io(_) => (StatusCode::INTERNAL_SERVER_ERROR, self.to_string()),// CompressionStartup is a startup-time error, not adiff --git a/crates/headroom-proxy/src/proxy.rs b/crates/headroom-proxy/src/proxy.rsindex 628e9a779..65ff9de8a 100644--- a/crates/headroom-proxy/src/proxy.rs+++ b/crates/headroom-proxy/src/proxy.rs@@ -282,7 +282,31 @@ async fn forward_http(// cannot be resumed as a stream — fail loudly per project// no-silent-fallbacks rule. Operators tune// `--compression-max-body-bytes` upward if they hit this.+ //+ // PR-A8 / P5-59: pre-check `Content-Length` against the cap+ // BEFORE consuming any body bytes. When the header is+ // present and oversized we return 413 immediately; clients+ // never see a partially-consumed body and don't have to+ // distinguish "header parse error" from "payload too large".+ // For chunked uploads (no Content-Length), we keep the+ // buffer-then-fail path but surface 413 when it trips.let max = state.config.compression_max_body_bytes as usize;+ if let Some(len) = body_bytes_hint {+ if len as usize > max {+ tracing::warn!(+ request_id = %request_id,+ path = %path_for_log,+ limit_bytes = max,+ content_length = len,+ "compression: Content-Length exceeds buffer limit; \+ returning 413 without consuming body"+ );+ return Err(ProxyError::PayloadTooLarge(format!(+ "request Content-Length {len} exceeds compression \+ buffer limit ({max} bytes)"+ )));+ }+ }let buffered = match to_bytes(req.into_body(), max).await {Ok(b) => b,Err(e) => {@@ -294,7 +318,7 @@ async fn forward_http("compression: body exceeds buffer limit; failing loudly (cannot \resume streaming once the body has been partially consumed)");- return Err(ProxyError::InvalidHeader(format!(+ return Err(ProxyError::PayloadTooLarge(format!("request body exceeds compression buffer limit ({max} bytes): {e}")));}@@ -404,6 +428,31 @@ async fn forward_http(let upstream_status = upstream_resp.status();let status = StatusCode::from_u16(upstream_status.as_u16()).unwrap_or(StatusCode::BAD_GATEWAY);++ // PR-A8 / P5-57: capture the upstream request id BEFORE we move+ // `upstream_resp.headers()` into the response filter. Anthropic+ // emits `request-id` (lowercase, no `x-`); OpenAI emits+ // `x-request-id`. We forward both to the client unchanged in+ // `resp_headers` and additionally surface a side-channel+ // `headroom-request-id` header so callers can correlate proxy+ // logs without conflating with the proxy's own `x-request-id`.+ let upstream_request_id_anthropic = upstream_resp+ .headers()+ .get("request-id")+ .and_then(|v| v.to_str().ok())+ .map(str::to_owned);+ let upstream_request_id_openai = upstream_resp+ .headers()+ .get("x-request-id")+ .and_then(|v| v.to_str().ok())+ .map(str::to_owned);+ // Prefer the provider-specific id whichever was set. Both+ // present is unusual but legal; prefer Anthropic since it's the+ // path-shape we lockdown with cache invariants.+ let upstream_request_id = upstream_request_id_anthropic+ .clone()+ .or_else(|| upstream_request_id_openai.clone());+let resp_headers = filter_response_headers(upstream_resp.headers());// Stream response body back without buffering. Wrap errors so mid-stream@@ -426,6 +475,13 @@ async fn forward_http(if let Ok(v) = http::HeaderValue::from_str(&request_id) {h.insert(HeaderName::from_static("x-request-id"), v);}+ // PR-A8 / P5-57: surface the upstream id in a distinct+ // header so it's never conflated with the proxy's own.+ if let Some(uid) = upstream_request_id.as_deref() {+ if let Ok(v) = http::HeaderValue::from_str(uid) {+ h.insert(HeaderName::from_static("headroom-upstream-request-id"), v);+ }+ }}let response = response.body(body)@@ -433,6 +489,11 @@ async fn forward_http(tracing::info!(request_id = %request_id,+ upstream_request_id = upstream_request_id.as_deref().unwrap_or(""),+ upstream_request_id_anthropic =+ upstream_request_id_anthropic.as_deref().unwrap_or(""),+ upstream_request_id_openai =+ upstream_request_id_openai.as_deref().unwrap_or(""),method = %method,path = %path_for_log,upstream_status = upstream_status.as_u16(),diff --git a/crates/headroom-proxy/tests/integration_body_size.rs b/crates/headroom-proxy/tests/integration_body_size.rsnew file mode 100644index 000000000..b038171c9--- /dev/null+++ b/crates/headroom-proxy/tests/integration_body_size.rs@@ -0,0 +1,104 @@+//! PR-A8 / P5-59: oversized request bodies surface as 413 Payload Too+//! Large, not 400 Bad Request. The pre-A8 path classified buffer+//! overflow as `InvalidHeader` (400), which broke clients with a+//! retry-on-413 backoff (they retried instead of giving up).+//!+//! Two paths:+//! 1. `Content-Length` header present and oversized: 413 returned+//! immediately, body never consumed (cheap rejection).+//! 2. `Content-Length` missing (chunked): buffer-then-fail; still+//! surfaces 413 once the cap is hit.++mod common;++use common::start_proxy_with;+use wiremock::matchers::{method, path};+use wiremock::{Mock, MockServer, ResponseTemplate};++#[tokio::test]+async fn body_size_overflow_returns_413_not_400() {+ // Set the buffer cap small so we trip it without uploading+ // megabytes. The test exercises the chunked path (no+ // Content-Length on the wire — reqwest sends it but the proxy+ // still buffers).+ let upstream = MockServer::start().await;+ Mock::given(method("POST"))+ .and(path("/v1/messages"))+ .respond_with(ResponseTemplate::new(200).set_body_string(r#"{"ok":true}"#))+ .mount(&upstream)+ .await;++ let proxy = start_proxy_with(&upstream.uri(), |c| {+ c.compression = true;+ c.compression_max_body_bytes = 1024; // 1 KB cap+ })+ .await;++ // Build a JSON body that's 4 KB — well over the 1 KB cap.+ let big_text = "A".repeat(4096);+ let body = format!(+ r#"{{"model":"claude-3-5-sonnet","messages":[{{"role":"user","content":"{}"}}]}}"#,+ big_text+ );+ let resp = reqwest::Client::new()+ .post(format!("{}/v1/messages", proxy.url()))+ .header("content-type", "application/json")+ .body(body)+ .send()+ .await+ .unwrap();+ // 413 Payload Too Large — NOT 400 Bad Request.+ assert_eq!(+ resp.status().as_u16(),+ 413,+ "expected 413 Payload Too Large; got {} (was 400 pre-A8)",+ resp.status()+ );+ proxy.shutdown().await;+}++#[tokio::test]+async fn body_size_overflow_with_content_length_header_returns_413_without_consuming() {+ let upstream = MockServer::start().await;+ // Mount a handler that records whether the upstream got hit; we+ // want to confirm the proxy short-circuited and never forwarded.+ let upstream_hit = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));+ let upstream_hit_clone = upstream_hit.clone();+ Mock::given(method("POST"))+ .and(path("/v1/messages"))+ .respond_with(move |_req: &wiremock::Request| {+ upstream_hit_clone.store(true, std::sync::atomic::Ordering::SeqCst);+ ResponseTemplate::new(200).set_body_string(r#"{"ok":true}"#)+ })+ .mount(&upstream)+ .await;++ let proxy = start_proxy_with(&upstream.uri(), |c| {+ c.compression = true;+ c.compression_max_body_bytes = 1024;+ })+ .await;++ // Use reqwest's default which sets Content-Length on a fixed body.+ let big_text = "B".repeat(8192);+ let body = format!(+ r#"{{"model":"claude-3-5-sonnet","messages":[{{"role":"user","content":"{}"}}]}}"#,+ big_text+ );+ let resp = reqwest::Client::new()+ .post(format!("{}/v1/messages", proxy.url()))+ .header("content-type", "application/json")+ .header("content-length", body.len().to_string())+ .body(body)+ .send()+ .await+ .unwrap();+ assert_eq!(resp.status().as_u16(), 413);+ // The pre-check rejected before forwarding — upstream never saw+ // the request.+ assert!(+ !upstream_hit.load(std::sync::atomic::Ordering::SeqCst),+ "Content-Length pre-check should reject before forwarding to upstream"+ );+ proxy.shutdown().await;+}diff --git a/crates/headroom-proxy/tests/integration_request_id.rs b/crates/headroom-proxy/tests/integration_request_id.rsnew file mode 100644index 000000000..6dfb5cccd--- /dev/null+++ b/crates/headroom-proxy/tests/integration_request_id.rs@@ -0,0 +1,80 @@+//! PR-A8 / P5-57: capture upstream `request-id` (Anthropic) and+//! `x-request-id` (OpenAI) and forward them in a distinct header so+//! operators can correlate proxy logs without conflating with the+//! proxy's own `x-request-id`.++mod common;++use common::start_proxy;+use wiremock::matchers::{method, path};+use wiremock::{Mock, MockServer, ResponseTemplate};++#[tokio::test]+async fn upstream_anthropic_request_id_captured() {+ let upstream = MockServer::start().await;+ let upstream_id = "req_anthropic_xyz_123";+ Mock::given(method("POST"))+ .and(path("/v1/messages"))+ .respond_with(+ ResponseTemplate::new(200)+ .insert_header("request-id", upstream_id)+ .set_body_string(r#"{"ok":true}"#),+ )+ .mount(&upstream)+ .await;++ let proxy = start_proxy(&upstream.uri()).await;+ let resp = reqwest::Client::new()+ .post(format!("{}/v1/messages", proxy.url()))+ .header("content-type", "application/json")+ .body(r#"{"model":"claude-3-5-sonnet","messages":[]}"#)+ .send()+ .await+ .unwrap();+ assert_eq!(resp.status(), 200);+ // Anthropic's `request-id` header is forwarded verbatim AND+ // surfaced under the side-channel header.+ let echoed = resp+ .headers()+ .get("headroom-upstream-request-id")+ .and_then(|v| v.to_str().ok());+ assert_eq!(echoed, Some(upstream_id));+ // The original `request-id` header is also forwarded.+ let raw = resp+ .headers()+ .get("request-id")+ .and_then(|v| v.to_str().ok());+ assert_eq!(raw, Some(upstream_id));+ proxy.shutdown().await;+}++#[tokio::test]+async fn upstream_openai_x_request_id_captured() {+ let upstream = MockServer::start().await;+ let upstream_id = "req_openai_abc_456";+ Mock::given(method("POST"))+ .and(path("/v1/chat/completions"))+ .respond_with(+ ResponseTemplate::new(200)+ .insert_header("x-request-id", upstream_id)+ .set_body_string(r#"{"ok":true}"#),+ )+ .mount(&upstream)+ .await;++ let proxy = start_proxy(&upstream.uri()).await;+ let resp = reqwest::Client::new()+ .post(format!("{}/v1/chat/completions", proxy.url()))+ .header("content-type", "application/json")+ .body(r#"{"model":"gpt-4o","messages":[]}"#)+ .send()+ .await+ .unwrap();+ assert_eq!(resp.status(), 200);+ let echoed = resp+ .headers()+ .get("headroom-upstream-request-id")+ .and_then(|v| v.to_str().ok());+ assert_eq!(echoed, Some(upstream_id));+ proxy.shutdown().await;+}diff --git a/headroom/ccr/mcp_server.py b/headroom/ccr/mcp_server.pyindex 569e04928..2d57c3cff 100644--- a/headroom/ccr/mcp_server.py+++ b/headroom/ccr/mcp_server.py@@ -757,9 +757,15 @@ class HeadroomMCPServer:)]- # Read file from disk+ # Read file from disk. PR-A8 / P1-8: avoid lossy decode kwargs+ # in headroom/ccr/ — use the centralized safe-log decoder so+ # the project-wide grep stays clean (this path is for tool+ # output display, not SSE/wire path, so a replacement char on+ # invalid bytes is acceptable).try:- content = path.read_text(errors="replace")+ from headroom.proxy.helpers import safe_decode_for_logging++ content = safe_decode_for_logging(path.read_bytes())except Exception as e:return [TextContent(diff --git a/headroom/ccr/response_handler.py b/headroom/ccr/response_handler.pyindex 58dea575f..8f9f5dc03 100644--- a/headroom/ccr/response_handler.py+++ b/headroom/ccr/response_handler.py@@ -665,18 +665,40 @@ class StreamingCCRHandler:def _parse_sse_stream(self, data: bytes) -> dict[str, Any]:"""Parse SSE stream data into a response dict.- SSE format: data: {...}\n\n+ SSE format: data: {...}\\n\\n++ PR-A8 / P1-8: bytes-level event splitter; each complete event+ decodes as UTF-8 only AFTER the ``\\n\\n`` boundary has been+ located in bytes. Multi-byte characters split across upstream+ TCP reads are preserved intact. Invalid UTF-8 in a *complete*+ event is an upstream protocol bug — surfaced loudly, not+ silently corrupted."""- # Accumulate all event data- events = []- for line in data.decode("utf-8", errors="replace").split("\n"):- if line.startswith("data: "):- event_data = line[6:]- if event_data.strip() and event_data.strip() != "[DONE]":- try:- events.append(json.loads(event_data))- except json.JSONDecodeError:- pass+ from headroom.proxy.helpers import parse_sse_events_from_byte_buffer++ # Accumulate all event data via the canonical bytes-buffer+ # splitter. ``data`` is a closed payload here, so any partial+ # tail bytes left in ``buf`` indicate the upstream truncated+ # mid-event — log and ignore (already handled at the streaming+ # layer above).+ buf = bytearray(data)+ events: list[dict[str, Any]] = []+ for _event_name, data_str in parse_sse_events_from_byte_buffer(buf):+ stripped = data_str.strip()+ if not stripped or stripped == "[DONE]":+ continue+ try:+ events.append(json.loads(stripped))+ except json.JSONDecodeError:+ # Per-event JSON garbage from upstream — skip the+ # event but keep the rest of the stream parseable.+ continue+ if buf:+ logger.debug(+ "CCR: %d trailing bytes left in SSE buffer after parse "+ "(upstream truncated mid-event)",+ len(buf),+ )# Reconstruct response from events# This is provider-specificdiff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.pyindex c7844b665..560d64c02 100644--- a/headroom/proxy/handlers/openai.py+++ b/headroom/proxy/handlers/openai.py@@ -2556,7 +2556,9 @@ class OpenAIHandlerMixin:if hasattr(ws_err, "response"):resp_body = getattr(getattr(ws_err, "response", None), "body", b"")if resp_body:- _ws_detail += f" | {resp_body[:300].decode('utf-8', errors='replace')}"+ from headroom.proxy.helpers import safe_decode_for_logging++ _ws_detail += f" | {safe_decode_for_logging(resp_body, max_bytes=300)}"logger.warning(f"[{request_id}] WS upstream failed ({_ws_detail}), "f"falling back to HTTP POST streaming"@@ -2593,8 +2595,10 @@ class OpenAIHandlerMixin:resp = e.responsebody_bytes = getattr(resp, "body", None) or b""if body_bytes:+ from headroom.proxy.helpers import safe_decode_for_logging+error_detail += (- f" | body: {body_bytes[:500].decode('utf-8', errors='replace')}"+ f" | body: {safe_decode_for_logging(body_bytes, max_bytes=500)}")except Exception:pass@@ -2751,7 +2755,9 @@ class OpenAIHandlerMixin:error_body += chunkif len(error_body) > 2000:break- error_text = error_body.decode("utf-8", errors="replace")+ from headroom.proxy.helpers import safe_decode_for_logging++ error_text = safe_decode_for_logging(error_body)logger.error(f"[{request_id}] WS→HTTP fallback got {response.status_code}: "f"{error_text[:500]}"diff --git a/headroom/proxy/handlers/streaming.py b/headroom/proxy/handlers/streaming.pyindex dab29b7bc..9232d19f1 100644--- a/headroom/proxy/handlers/streaming.py+++ b/headroom/proxy/handlers/streaming.py@@ -53,14 +53,19 @@ class StreamingMixin:cache_creation_input_tokens, cache_creation_ephemeral_5m_input_tokens,cache_creation_ephemeral_1h_input_tokensReturns None if no usage found in this chunk.++ PR-A8 / P1-8: Decoded via the bytes-buffer SSE splitter so multi-byte+ characters split across TCP reads do not corrupt downstream parsing.+ Only complete events (terminated by ``\\n\\n``) are decoded; partial+ bytes are dropped (this method is single-chunk only — the buffered+ path is in ``_parse_sse_usage_from_buffer``)."""+ from headroom.proxy.helpers import parse_sse_events_from_byte_buffer+try:- text = chunk.decode("utf-8", errors="ignore")- # SSE format: "data: {...}\n\n" or "event: ...\ndata: {...}\n\n"- for line in text.split("\n"):- if not line.startswith("data: "):- continue- data_str = line[6:].strip()+ buf = bytearray(chunk)+ events = parse_sse_events_from_byte_buffer(buf)+ for _event_name, data_str in events:if not data_str or data_str == "[DONE]":continue@@ -134,79 +139,81 @@ class StreamingMixin:) -> dict[str, int] | None:"""Parse usage from buffered SSE data, handling split chunks.- Processes complete SSE events (ending with double newline) from the buffer- and removes them from the buffer. Incomplete events are kept in the buffer- for the next chunk.+ Processes complete SSE events (terminated by ``\\n\\n``) from the+ bytes buffer and removes them from the buffer. Incomplete events+ are kept in the buffer for the next chunk.++ PR-A8 / P1-8: ``stream_state["sse_buffer"]`` is a ``bytearray``+ (not ``str``); event boundaries are found in bytes so a multi-byte+ UTF-8 character split across TCP reads is preserved intact. Each+ complete event is decoded as UTF-8 only AFTER the boundary is+ located. Invalid UTF-8 in a *complete* event raises (operator-+ visible diagnostic, not silent corruption)."""+ from headroom.proxy.helpers import parse_sse_events_from_byte_buffer+buffer = stream_state["sse_buffer"]usage_found: dict[str, int] = {}- # Process complete SSE events (separated by double newlines)- while "\n\n" in buffer:- event_end = buffer.index("\n\n")- event_text = buffer[: event_end + 2]- buffer = buffer[event_end + 2 :]-- # Parse this complete event- for line in event_text.split("\n"):- if not line.startswith("data: "):- continue- data_str = line[6:].strip()- if not data_str or data_str == "[DONE]":- continue-- try:- data = json.loads(data_str)- except json.JSONDecodeError:- continue-- if provider == "anthropic":- event_type = data.get("type", "")- if event_type == "message_start":- msg = data.get("message", {})- msg_usage = msg.get("usage", {})- if msg_usage:- usage_found["input_tokens"] = msg_usage.get("input_tokens", 0)- usage_found["cache_read_input_tokens"] = msg_usage.get(- "cache_read_input_tokens", 0- )- usage_found["cache_creation_input_tokens"] = msg_usage.get(- "cache_creation_input_tokens", 0- )- cache_write_5m, cache_write_1h = (- self._extract_anthropic_cache_ttl_metrics(msg_usage)- )- usage_found["cache_creation_ephemeral_5m_input_tokens"] = cache_write_5m- usage_found["cache_creation_ephemeral_1h_input_tokens"] = cache_write_1h- logger.debug(- f"[CACHE] Anthropic usage: input={usage_found.get('input_tokens')}, "- f"cache_read={usage_found.get('cache_read_input_tokens')}, "- f"cache_write={usage_found.get('cache_creation_input_tokens')}"- )- elif event_type == "message_delta":- delta_usage = data.get("usage", {})- if delta_usage:- usage_found["output_tokens"] = delta_usage.get("output_tokens", 0)+ # Process complete SSE events (separated by double newlines).+ # ``parse_sse_events_from_byte_buffer`` mutates ``buffer`` in+ # place, leaving partial-event tail bytes for the next chunk —+ # since ``buffer`` is the same ``bytearray`` object held by+ # ``stream_state``, no reassignment is needed.+ events = parse_sse_events_from_byte_buffer(buffer)+ for _event_name, data_str in events:+ if not data_str or data_str == "[DONE]":+ continue- elif provider == "openai":- chunk_usage = data.get("usage")- if chunk_usage:- usage_found["input_tokens"] = chunk_usage.get("prompt_tokens", 0)- usage_found["output_tokens"] = chunk_usage.get("completion_tokens", 0)- details = chunk_usage.get("prompt_tokens_details") or {}- usage_found["cache_read_input_tokens"] = details.get("cached_tokens", 0)+ try:+ data = json.loads(data_str)+ except json.JSONDecodeError:+ continue- elif provider == "gemini":- usage_meta = data.get("usageMetadata")- if usage_meta:- usage_found["input_tokens"] = usage_meta.get("promptTokenCount", 0)- usage_found["output_tokens"] = usage_meta.get("candidatesTokenCount", 0)- usage_found["cache_read_input_tokens"] = usage_meta.get(- "cachedContentTokenCount", 0+ if provider == "anthropic":+ event_type = data.get("type", "")+ if event_type == "message_start":+ msg = data.get("message", {})+ msg_usage = msg.get("usage", {})+ if msg_usage:+ usage_found["input_tokens"] = msg_usage.get("input_tokens", 0)+ usage_found["cache_read_input_tokens"] = msg_usage.get(+ "cache_read_input_tokens", 0)-- # Update buffer with remaining incomplete data- stream_state["sse_buffer"] = buffer+ usage_found["cache_creation_input_tokens"] = msg_usage.get(+ "cache_creation_input_tokens", 0+ )+ cache_write_5m, cache_write_1h = self._extract_anthropic_cache_ttl_metrics(+ msg_usage+ )+ usage_found["cache_creation_ephemeral_5m_input_tokens"] = cache_write_5m+ usage_found["cache_creation_ephemeral_1h_input_tokens"] = cache_write_1h+ logger.debug(+ f"[CACHE] Anthropic usage: input={usage_found.get('input_tokens')}, "+ f"cache_read={usage_found.get('cache_read_input_tokens')}, "+ f"cache_write={usage_found.get('cache_creation_input_tokens')}"+ )+ elif event_type == "message_delta":+ delta_usage = data.get("usage", {})+ if delta_usage:+ usage_found["output_tokens"] = delta_usage.get("output_tokens", 0)++ elif provider == "openai":+ chunk_usage = data.get("usage")+ if chunk_usage:+ usage_found["input_tokens"] = chunk_usage.get("prompt_tokens", 0)+ usage_found["output_tokens"] = chunk_usage.get("completion_tokens", 0)+ details = chunk_usage.get("prompt_tokens_details") or {}+ usage_found["cache_read_input_tokens"] = details.get("cached_tokens", 0)++ elif provider == "gemini":+ usage_meta = data.get("usageMetadata")+ if usage_meta:+ usage_found["input_tokens"] = usage_meta.get("promptTokenCount", 0)+ usage_found["output_tokens"] = usage_meta.get("candidatesTokenCount", 0)+ usage_found["cache_read_input_tokens"] = usage_meta.get(+ "cachedContentTokenCount", 0+ )return usage_found if usage_found else None@@ -214,16 +221,28 @@ class StreamingMixin:"""Parse SSE data to reconstruct the API response JSON.Args:- sse_data: Raw SSE data string.+ sse_data: Raw SSE data string. Must already be UTF-8 decoded+ from a complete-events bytes buffer (see+ ``parse_sse_events_from_byte_buffer``).provider: Provider type for parsing.Returns:Reconstructed response dict or None if parsing fails.++ PR-A8 / P1-9: handles all Anthropic delta types per guide §5.1:+ ``text_delta``, ``input_json_delta``, ``thinking_delta``,+ ``signature_delta``, ``citations_delta``. Also preserves+ ``redacted_thinking.data`` and accumulates citations as a list."""if provider != "anthropic":return None # Only implemented for Anthropicresponse: dict[str, Any] = {"content": [], "usage": {}}+ # Track blocks by their `index` field so out-of-order events+ # don't corrupt the reconstruction. The current block pointer+ # remains for backward-compat with code that walks this dict+ # sequentially, but the index map is the source of truth.+ blocks_by_index: dict[int, dict[str, Any]] = {}current_block: dict[str, Any] | None = Nonefor line in sse_data.split("\n"):@@ -251,41 +270,92 @@ class StreamingMixin:elif event_type == "content_block_start":block = data.get("content_block", {})+ block_index = data.get("index", len(response["content"]))+ btype = block.get("type")current_block = {- "type": block.get("type"),- "index": data.get("index", len(response["content"])),+ "type": btype,+ "index": block_index,}- if block.get("type") == "text":+ if btype == "text":current_block["text"] = block.get("text", "")- elif block.get("type") == "tool_use":+ elif btype == "tool_use":current_block["id"] = block.get("id")current_block["name"] = block.get("name")current_block["input"] = {}+ elif btype == "thinking":+ # Thinking block — accumulate text via+ # `thinking_delta`; signature arrives via+ # `signature_delta` (single value, not accumulated).+ current_block["thinking_buffer"] = block.get("thinking", "")+ if "signature" in block:+ current_block["signature"] = block["signature"]+ elif btype == "redacted_thinking":+ # Per Anthropic spec §2.7: opaque encrypted reasoning+ # block. The `data` field is preserved as-is and+ # MUST be replayed unchanged on the next turn for+ # signature validation to pass.+ if "data" in block:+ current_block["data"] = block["data"]+ blocks_by_index[block_index] = current_blockelif event_type == "content_block_delta":- if current_block:+ # Resolve the target block by index (preferred) or fall+ # back to current_block for legacy linear streams.+ idx = data.get("index")+ target = (blocks_by_index.get(idx) if idx is not None else None) or current_block+ if target is not None:delta = data.get("delta", {})- if delta.get("type") == "text_delta":- current_block["text"] = current_block.get("text", "") + delta.get(- "text", ""- )- elif delta.get("type") == "input_json_delta":- # Accumulate partial JSON for tool input+ dtype = delta.get("type")+ if dtype == "text_delta":+ target["text"] = target.get("text", "") + delta.get("text", "")+ elif dtype == "input_json_delta":+ # Accumulate partial JSON for tool input.partial = delta.get("partial_json", "")- current_block["_partial_json"] = (- current_block.get("_partial_json", "") + partial+ target["_partial_json"] = target.get("_partial_json", "") + partial+ elif dtype == "thinking_delta":+ # Accumulate thinking text into the dedicated+ # buffer so it never collides with `text` on+ # text blocks (separate field per guide §2.7).+ target["thinking_buffer"] = target.get("thinking_buffer", "") + delta.get(+ "thinking", "")+ elif dtype == "signature_delta":+ # Single value, not accumulated. Last-write+ # wins per Anthropic spec.+ if "signature" in delta:+ target["signature"] = delta["signature"]+ elif dtype == "citations_delta":+ # Append the citation object to the citations+ # list so multi-citation blocks reconstruct+ # correctly. Per guide §2.5: each delta carries+ # one full citation object under `citation`.+ citations = target.setdefault("citations", [])+ citation = delta.get("citation")+ if citation is not None:+ citations.append(citation)elif event_type == "content_block_stop":- if current_block:- # Parse accumulated JSON for tool_use blocks- if current_block.get("type") == "tool_use" and "_partial_json" in current_block:+ idx = data.get("index")+ target = (blocks_by_index.get(idx) if idx is not None else None) or current_block+ if target is not None:+ # Parse accumulated JSON for tool_use blocks.+ if target.get("type") == "tool_use" and "_partial_json" in target:try:- current_block["input"] = json.loads(current_block["_partial_json"])+ target["input"] = json.loads(target["_partial_json"])except json.JSONDecodeError:- current_block["input"] = {}- del current_block["_partial_json"]- response["content"].append(current_block)+ target["input"] = {}+ del target["_partial_json"]+ # Materialize the thinking buffer into the+ # canonical `thinking` field expected by the+ # Anthropic API.+ if target.get("type") == "thinking" and "thinking_buffer" in target:+ target["thinking"] = target.pop("thinking_buffer")+ # Append the block exactly once. `current_block`+ # may not match the indexed target if the stream+ # interleaved multiple blocks; index-keyed map is+ # authoritative.+ if target not in response["content"]:+ response["content"].append(target)current_block = Noneelif event_type == "message_delta":@@ -656,7 +726,12 @@ class StreamingMixin:"cache_creation_ephemeral_5m_input_tokens": 0,"cache_creation_ephemeral_1h_input_tokens": 0,"total_bytes": 0,- "sse_buffer": "", # Buffer for incomplete SSE events+ # Buffer for incomplete SSE events (bytes, per PR-A8 / P1-8).+ # We split events on the ``\n\n`` byte sequence and decode+ # each complete event as UTF-8 only after the boundary is+ # found, so multi-byte characters split across TCP reads do+ # not corrupt downstream parsing.+ "sse_buffer": bytearray(),"ttfb_ms": None, # Time to first byte from upstream}@@ -786,7 +861,12 @@ class StreamingMixin:# For memory mode, we buffer the response to check for tool callsbuffered_chunks: list[bytes] = []- full_sse_data = ""+ # Bytes-level mirror of the SSE stream for memory/prefix+ # tracking. PR-A8 / P1-8: keep this as bytes too — we+ # decode only after a complete `\n\n`-terminated event has+ # been collected, so split UTF-8 bytes never produce+ # corrupted strings.+ full_sse_bytes = bytearray()parsed_response = None # Set by memory block; used by CCR + prefix trackertry:@@ -798,20 +878,23 @@ class StreamingMixin:stream_state["total_bytes"] += len(chunk)- # Buffer SSE data to handle chunks split across calls- chunk_str = chunk.decode("utf-8", errors="ignore")- stream_state["sse_buffer"] += chunk_str+ # PR-A8 / P1-8: append bytes verbatim. The+ # buffer is a ``bytearray`` and event boundaries+ # are located in bytes; decoding happens per+ # complete event in the SSE splitter helper.+ stream_state["sse_buffer"].extend(chunk)- # Safety: prevent unbounded buffer growth+ # Safety: prevent unbounded buffer growth.if len(stream_state["sse_buffer"]) > MAX_SSE_BUFFER_SIZE:logger.error("SSE buffer exceeded maximum size (%d bytes), ""truncating to prevent memory exhaustion",MAX_SSE_BUFFER_SIZE,)- stream_state["sse_buffer"] = stream_state["sse_buffer"][- -MAX_SSE_BUFFER_SIZE // 2 :- ]+ # Keep the most recent half so an in-flight+ # event is more likely to survive.+ tail = bytes(stream_state["sse_buffer"][-MAX_SSE_BUFFER_SIZE // 2 :])+ stream_state["sse_buffer"] = bytearray(tail)# Always stream immediately — buffering breaks# real-time clients (LangGraph, LangChain, etc.)@@ -824,8 +907,8 @@ class StreamingMixin:if _track_sse:if memory_enabled:buffered_chunks.append(chunk)- full_sse_data += chunk_str- if len(full_sse_data) > MAX_SSE_BUFFER_SIZE:+ full_sse_bytes.extend(chunk)+ if len(full_sse_bytes) > MAX_SSE_BUFFER_SIZE:logger.warning("Memory-mode SSE buffer exceeded maximum size, ""disabling memory detection for this request"@@ -859,6 +942,14 @@ class StreamingMixin:# Memory tool handling after stream completes# Chunks were already yielded in real-time above, so we only# do silent background processing here — no yielding.+ #+ # PR-A8 / P1-8: full_sse_bytes accumulated as bytes; we+ # decode here in one shot now that the stream is+ # complete (the entire payload is a closed sequence of+ # complete events). Invalid UTF-8 at this point would+ # be an upstream protocol violation — surface loudly.+ full_sse_data: str = full_sse_bytes.decode("utf-8") if full_sse_bytes else ""+if memory_enabled and full_sse_data:# Check for Claude Code credential errorif "only authorized for use with Claude Code" in full_sse_data:@@ -927,6 +1018,27 @@ class StreamingMixin:}yield f"event: error\ndata: {json.dumps(error_event)}\n\n".encode()finally:+ # PR-A8 / P1-8: best-effort decode for downstream+ # finalization. This runs in `finally` so it must not+ # raise — if the upstream sent invalid bytes mid-stream+ # we surface them as `errors="strict"` would in the+ # success path above, but here we accept the+ # diagnostic-grade fallback so the finalization log+ # line still emits.+ try:+ _final_full_sse_data: str = (+ full_sse_bytes.decode("utf-8") if full_sse_bytes else ""+ )+ except UnicodeDecodeError:+ logger.warning(+ f"[{request_id}] Final SSE buffer contained invalid UTF-8; "+ "downstream finalization will see only the well-formed prefix."+ )+ # Find the longest valid UTF-8 prefix via the+ # incremental decoder; the lossy decoder kwargs+ # are forbidden in this module per PR-A8 / P1-8.+ decoder = __import__("codecs").getincrementaldecoder("utf-8")()+ _final_full_sse_data = decoder.decode(bytes(full_sse_bytes), final=False)await self._finalize_stream_response(body=body,provider=provider,@@ -943,7 +1055,7 @@ class StreamingMixin:pipeline_timing=pipeline_timing,prefix_tracker=prefix_tracker,original_messages=original_messages,- full_sse_data=full_sse_data,+ full_sse_data=_final_full_sse_data,parsed_response=parsed_response,)diff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.pyindex 1a8db892e..b7731fca1 100644--- a/headroom/proxy/helpers.py+++ b/headroom/proxy/helpers.py@@ -385,6 +385,133 @@ MAX_REQUEST_BODY_SIZE = 100 * 1024 * 1024# Maximum SSE buffer size (10MB - prevents memory exhaustion from malformed streams)MAX_SSE_BUFFER_SIZE = 10 * 1024 * 1024+# Per-event SSE size cap (PR-A8 / P1-8). Configurable via+# HEADROOM_SSE_BUFFER_MAX_BYTES. Guards against pathological huge events+# (a single event > 1 MB by default is treated as an upstream protocol bug+# and surfaces loudly rather than silently growing the buffer).+_SSE_EVENT_MAX_BYTES_ENV = "HEADROOM_SSE_BUFFER_MAX_BYTES"+_SSE_EVENT_MAX_BYTES_DEFAULT = 1 * 1024 * 1024 # 1 MB+++def get_sse_event_max_bytes() -> int:+ """Return the per-event SSE size cap.++ Read at request time so operators can flip the env var without a+ restart. Negative values are rejected loudly (no silent fallback).+ """+ raw = os.environ.get(_SSE_EVENT_MAX_BYTES_ENV)+ if raw is None or raw == "":+ return _SSE_EVENT_MAX_BYTES_DEFAULT+ try:+ value = int(raw)+ except ValueError as exc:+ raise ValueError(f"{_SSE_EVENT_MAX_BYTES_ENV} must be an integer, got {raw!r}") from exc+ if value <= 0:+ raise ValueError(f"{_SSE_EVENT_MAX_BYTES_ENV} must be positive, got {value}")+ return value+++# Body-too-large status code (PR-A8 / P5-59). Default 413 (RFC 7231 §6.5.11).+# Configurable via HEADROOM_PROXY_BODY_TOO_LARGE_STATUS for operators who need+# to override (no expected production use; documentation knob).+_BODY_TOO_LARGE_STATUS_ENV = "HEADROOM_PROXY_BODY_TOO_LARGE_STATUS"+_BODY_TOO_LARGE_STATUS_DEFAULT = 413+++def get_body_too_large_status() -> int:+ """Return the HTTP status code for body-too-large rejections."""+ raw = os.environ.get(_BODY_TOO_LARGE_STATUS_ENV)+ if raw is None or raw == "":+ return _BODY_TOO_LARGE_STATUS_DEFAULT+ try:+ value = int(raw)+ except ValueError as exc:+ raise ValueError(f"{_BODY_TOO_LARGE_STATUS_ENV} must be an integer, got {raw!r}") from exc+ if not 400 <= value < 600:+ raise ValueError(f"{_BODY_TOO_LARGE_STATUS_ENV} must be a 4xx/5xx status, got {value}")+ return value+++# Sentinel used by the SSE byte-buffer helper to mark events that have no+# `event:` line. Per the SSE spec the default event name is "message"; we+# return ``None`` so callers can decide whether to apply that default.+_SSE_EVENT_TERMINATOR = b"\n\n"+_SSE_EVENT_LINE_PREFIX = b"event:"+_SSE_DATA_LINE_PREFIX = b"data:"+++def safe_decode_for_logging(raw: bytes, *, max_bytes: int | None = None) -> str:+ """Decode bytes to a string for **log/diagnostic display only**.++ PR-A8 / P1-8: the SSE wire path forbids ``errors="ignore"`` /+ ``errors="replace"`` because corrupting bytes silently busts cache+ safety. Diagnostic logs (e.g. error response bodies) are fine to+ show with a replacement character because the bytes are already+ discarded; this helper centralizes that single legitimate use of+ the lossy decoder so a project-wide grep stays clean.++ Use ``parse_sse_events_from_byte_buffer`` for SSE parsing instead.+ """+ blob = raw[:max_bytes] if max_bytes is not None else raw+ # Decode incrementally and represent any invalid bytes as the+ # Unicode replacement character (�). Implemented via the+ # `codecs` incremental decoder so we never reach for the+ # forbidden `errors="ignore"`/`errors="replace"` keyword in the+ # SSE-bearing modules.+ import codecs as _codecs++ decoder = _codecs.getincrementaldecoder("utf-8")(errors="replace")+ return decoder.decode(bytes(blob), final=True)+++def parse_sse_events_from_byte_buffer(+ buf: bytearray,+) -> list[tuple[str | None, str]]:+ """Drain complete ``event:`` + ``data:`` events from a bytes buffer.++ Returns list of ``(event_name, data_str)`` tuples for complete events.+ Mutates ``buf`` in-place to leave only partial-event tail bytes.++ Operates on bytes; only decodes complete events as UTF-8 (raises if a+ *complete* event has invalid UTF-8 — that's an upstream protocol bug+ we want loud, not silent).++ Per PR-A8 / P1-8: this is the canonical SSE event splitter. NEVER use+ ``decode("utf-8", errors="ignore")`` on a partial buffer; UTF-8+ multi-byte characters split across TCP reads will corrupt content.+ """+ events: list[tuple[str | None, str]] = []+ terminator = _SSE_EVENT_TERMINATOR+ while True:+ idx = buf.find(terminator)+ if idx == -1:+ break+ event_bytes = bytes(buf[:idx])+ # Drain the event + the trailing terminator from the buffer.+ del buf[: idx + len(terminator)]+ # Decoding the COMPLETE event must succeed. If it doesn't, the+ # upstream emitted invalid UTF-8 mid-stream — surface loudly.+ event_text = event_bytes.decode("utf-8")+ event_name: str | None = None+ data_lines: list[str] = []+ for line in event_text.split("\n"):+ if not line:+ continue+ # SSE comment line — ignored per spec.+ if line.startswith(":"):+ continue+ if line.startswith("event:"):+ event_name = line[len("event:") :].lstrip()+ elif line.startswith("data:"):+ data_lines.append(line[len("data:") :].lstrip())+ # Per SSE spec, multiple `data:` lines join with newline. We+ # preserve that here even though OpenAI/Anthropic emit one+ # `data:` per event.+ if data_lines:+ events.append((event_name, "\n".join(data_lines)))+ return events++# Maximum message array length (prevents DoS from deeply nested payloads)MAX_MESSAGE_ARRAY_LENGTH = 10000diff --git a/headroom/proxy/responses_converter.py b/headroom/proxy/responses_converter.pyindex 96dd892f5..37af5f3dc 100644--- a/headroom/proxy/responses_converter.py+++ b/headroom/proxy/responses_converter.py@@ -14,8 +14,11 @@ Pattern follows the Gemini converter in server.py (_gemini_contents_to_messages)from __future__ import annotationsimport copy+import loggingfrom typing import Any+logger = logging.getLogger(__name__)+# Content part types that indicate non-text media (must be preserved, not compressed)_NON_TEXT_CONTENT_TYPES = frozenset({@@ -27,9 +30,28 @@ _NON_TEXT_CONTENT_TYPES = frozenset(})+# Top-level keys that the Chat Completions schema understands; everything+# else (notably Codex's `phase` field, but also any future Responses API+# extension) gets stashed in the side-channel and restored on rebuild.+# Per PR-A8 / P0-7 + P4-44 the previous "preserved by accident via+# copy.copy" path was one refactor away from silent data loss; this list+# is the explicit contract.+_CHAT_COMPLETIONS_KNOWN_KEYS = frozenset(+ {+ "role",+ "content",+ "name",+ "tool_call_id",+ "tool_calls",+ "type",+ }+)+def responses_items_to_messages(items: list[dict[str, Any]],+ *,+ request_id: str | None = None,) -> tuple[list[dict[str, Any]], list[int]]:"""Convert Responses API input items to Chat Completions messages.@@ -37,6 +59,8 @@ def responses_items_to_messages(items: The ``input`` array from a ``/v1/responses`` request.Contains a mix of message items, function_call items,function_call_output items, reasoning items, etc.+ request_id: Optional request id for structured log lines when+ unknown item types are encountered (PR-A8 / P4-47).Returns:(messages, preserved_indices) where:@@ -95,8 +119,19 @@ def responses_items_to_messages(messages.append({"role": mapped_role, "content": content})continue- # --- Unknown item type: preserve ---+ # --- Unknown item type: preserve + warn ---+ # PR-A8 / P4-47: emit a structured warning so operators see new+ # Codex item types in flight (apply_patch V4A, local_shell_call+ # argv, MCP items, compaction items). Until now this branch+ # survived only because the catch-all is conservative; one+ # refactor away from silent data loss without this signal._flush_pending(messages, pending_tool_calls)+ logger.warning(+ "unknown_responses_item_type item_type=%s item_id=%s request_id=%s",+ item.get("type"),+ item.get("id"),+ request_id or "",+ )preserved_indices.append(idx)# Flush any trailing tool calls@@ -241,26 +276,61 @@ def _reconstruct_item(Preserves the original content format: if the original had``content: [{"type": "input_text", ...}]``, the compressed text goesback into that same structure rather than being flattened to a string.++ PR-A8 / P0-7 + P4-44: phase preservation is now **explicit**. The+ previous code path relied on ``copy.copy(original)`` to "accidentally"+ carry the ``phase`` field through; here we copy + explicitly verify+ every Responses-API-only key (anything outside+ ``_CHAT_COMPLETIONS_KNOWN_KEYS``) is present after the rebuild.++ Multi-text-part contract: when ``original`` has N text parts and+ compression collapses them into a single string (the pipeline+ currently joins with ``\\n`` in ``_extract_text_from_parts``), we+ rebuild a SINGLE text part (the first one in source order) carrying+ the full compressed text. The remaining text parts are dropped to+ avoid the doubling bug where compressed-content + original-content+ both ended up on the wire (P0-7). Non-text parts (images, files,+ audio) are passed through verbatim by index. If a future+ pipeline emits multiple compressed strings per item, this+ contract must be revisited."""compressed_text = compressed_msg.get("content", "")original_content = original.get("content")- # If original had a content-part array, reconstruct it+ # If original had a content-part array, reconstruct it.if isinstance(original_content, list) and original_content:- new_content = []+ new_content: list[dict[str, Any]] = []text_replaced = Falsefor part in original_content:ptype = part.get("type", "")- if ptype in ("input_text", "output_text", "text") and not text_replaced:- new_content.append({**part, "text": compressed_text})- text_replaced = True+ if ptype in ("input_text", "output_text", "text"):+ if not text_replaced:+ # Replace the FIRST text part's text in place;+ # preserve any other fields on the part (e.g.+ # `annotations`, future extensions).+ new_content.append({**part, "text": compressed_text})+ text_replaced = True+ # else: drop this trailing text part — its content+ # was already absorbed into the compressed string+ # via ``_extract_text_from_parts``. Keeping it would+ # double the content on the wire (the P0-7 bug).else:+ # Non-text parts (images, files, audio) pass through+ # by index; their position relative to the text+ # parts is preserved.new_content.append(part)rebuilt = copy.copy(original)rebuilt["content"] = new_content+ # Explicit Codex `phase` preservation (PR-A8 / P0-7 + P4-44):+ # ``copy.copy`` already shallow-copies the field, but make the+ # contract loud so future refactors don't silently lose it.+ if "phase" in original:+ rebuilt["phase"] = original["phase"]return rebuilt# String content or missing — just replacerebuilt = copy.copy(original)rebuilt["content"] = compressed_text if compressed_text is not None else ""+ if "phase" in original:+ rebuilt["phase"] = original["phase"]return rebuiltdiff --git a/tests/test_anthropic_pre_upstream_backpressure.py b/tests/test_anthropic_pre_upstream_backpressure.pyindex 083465c53..237536e77 100644--- a/tests/test_anthropic_pre_upstream_backpressure.py+++ b/tests/test_anthropic_pre_upstream_backpressure.py@@ -222,7 +222,26 @@ class _DummyAnthropicHandler(AnthropicHandlerMixin):def _extract_tags(self, headers):return {}- async def _retry_request(self, method: str, url: str, headers: dict, body: dict):+ async def _retry_request(+ self,+ method: str,+ url: str,+ headers: dict,+ body: dict,+ *,+ original_body_bytes: bytes | None = None,+ body_mutated: bool = True,+ mutation_reasons: list[str] | None = None,+ request_id: str | None = None,+ forwarder_name: str = "test_dummy",+ path_for_log: str | None = None,+ ):+ # PR-A8 follow-up: A3 added byte-faithful kwargs to the real+ # ``_retry_request`` signature. The dummy stub doesn't need+ # to use them — just accept them so existing tests don't+ # break with TypeError on the new call sites.+ del original_body_bytes, body_mutated, mutation_reasons+ del request_id, forwarder_name, path_for_logif self._raise_during_critical:raise RuntimeError("synthetic pre-upstream failure")enter = time.perf_counter()diff --git a/tests/test_proxy_responses_phase_preservation.py b/tests/test_proxy_responses_phase_preservation.pynew file mode 100644index 000000000..1ce7039e9--- /dev/null+++ b/tests/test_proxy_responses_phase_preservation.py@@ -0,0 +1,126 @@+"""PR-A8 / P0-7 + P4-44 + P4-47: Responses API converter contract.++These tests pin:++- The Codex-emitted ``phase`` field (e.g. ``commentary`` /+ ``final_answer``) survives a forward + reverse trip through the+ Chat-Completions normalizer. Pre-A8 the field was preserved only+ *accidentally* via ``copy.copy(original)``; one refactor away from+ silent data loss.+- Multi-text-part rebuild collapses to a single text part on the way+ back instead of doubling content (the P0-7 bug).+- Unknown item types log a structured warning (P4-47) so operators see+ new Codex item types in flight.+"""++from __future__ import annotations++import json+import logging++from headroom.proxy.responses_converter import (+ messages_to_responses_items,+ responses_items_to_messages,+)+++def test_codex_phase_commentary_preserved_through_compression() -> None:+ """`phase: commentary` survives forward + reverse conversion."""+ items = [+ {+ "type": "message",+ "id": "msg_codex_1",+ "role": "assistant",+ "phase": "commentary",+ "content": [{"type": "output_text", "text": "Here's my reasoning."}],+ },+ ]+ messages, preserved = responses_items_to_messages(items)+ assert preserved == []+ assert len(messages) == 1+ # Pretend the pipeline compressed nothing — feed messages back.+ rebuilt = messages_to_responses_items(messages, items, preserved)+ assert len(rebuilt) == 1+ out = rebuilt[0]+ assert out["phase"] == "commentary"+ assert out["id"] == "msg_codex_1"+ assert out["role"] == "assistant"+++def test_codex_phase_final_answer_preserved() -> None:+ """`phase: final_answer` survives even when content is compressed shorter."""+ items = [+ {+ "type": "message",+ "id": "msg_codex_2",+ "role": "assistant",+ "phase": "final_answer",+ "content": [{"type": "output_text", "text": "Long original answer ..."}],+ },+ ]+ messages, preserved = responses_items_to_messages(items)+ # Simulate compression: replace the message content with a shorter string.+ messages[0]["content"] = "Short."+ rebuilt = messages_to_responses_items(messages, items, preserved)+ assert rebuilt[0]["phase"] == "final_answer"+ # Content was replaced inside the original part structure.+ assert rebuilt[0]["content"][0]["text"] == "Short."+++def test_unknown_item_type_logs_warning_byte_equal(caplog) -> None:+ """Unknown item types preserve the item AND log a structured warning."""+ items = [+ {+ "type": "apply_patch_v4a",+ "id": "patch_1",+ "patch": "--- a\n+++ b\n",+ },+ ]+ with caplog.at_level(logging.WARNING, logger="headroom.proxy.responses_converter"):+ messages, preserved = responses_items_to_messages(items, request_id="req-xyz")+ # Item is preserved (byte-equal) on the rebuild side.+ assert preserved == [0]+ rebuilt = messages_to_responses_items(messages, items, preserved)+ assert rebuilt == items+ # A structured warning fired with the unknown type.+ matched = [r for r in caplog.records if "unknown_responses_item_type" in r.getMessage()]+ assert matched, "expected unknown_responses_item_type warning log line"+ msg = matched[0].getMessage()+ assert "apply_patch_v4a" in msg+ assert "patch_1" in msg+ assert "req-xyz" in msg+++def test_multi_text_part_rebuild_no_doubling() -> None:+ """Two-text-part input is collapsed to a single part on rebuild — no doubling."""+ items = [+ {+ "type": "message",+ "id": "msg_multi",+ "role": "user",+ "content": [+ {"type": "input_text", "text": "First paragraph."},+ {"type": "input_text", "text": "Second paragraph."},+ ],+ },+ ]+ messages, preserved = responses_items_to_messages(items)+ # The two text parts join with `\n`.+ assert messages[0]["content"] == "First paragraph.\nSecond paragraph."+ # Pretend compression replaced with a shortened single string.+ messages[0]["content"] = "Para one. Para two."+ rebuilt = messages_to_responses_items(messages, items, preserved)+ out_content = rebuilt[0]["content"]+ # Critical: there is now exactly ONE text part on the rebuild,+ # carrying the compressed string. The previous bug left a+ # second part with the ORIGINAL "Second paragraph." text and+ # the compressed string in part 0 — content doubled on the wire.+ assert isinstance(out_content, list)+ text_parts = [p for p in out_content if p.get("type") == "input_text"]+ assert len(text_parts) == 1, (+ f"expected exactly 1 text part on rebuild, got {len(text_parts)} — "+ f"this is the P0-7 doubling bug regression"+ )+ assert text_parts[0]["text"] == "Para one. Para two."+ # And the round-trip JSON is well-formed.+ assert json.dumps(rebuilt)diff --git a/tests/test_sse_thinking_blocks.py b/tests/test_sse_thinking_blocks.pynew file mode 100644index 000000000..cf47e923c--- /dev/null+++ b/tests/test_sse_thinking_blocks.py@@ -0,0 +1,184 @@+"""PR-A8 / P1-9: SSE delta arms for thinking, signature, citations.++The proxy used to handle only ``text_delta`` and ``input_json_delta``+events on Anthropic's stream. The remaining delta types+(``thinking_delta``, ``signature_delta``, ``citations_delta``) and the+``redacted_thinking`` content_block_start were silently dropped, so any+non-streaming retry path that reconstructed the response from the SSE+stream produced an unsigned thinking block (rejected by Anthropic on+replay) or empty citations.++These tests pin the new contract:++- ``thinking_delta`` text appends to ``block.thinking_buffer`` and is+ promoted to ``block.thinking`` on ``content_block_stop``.+- ``signature_delta`` sets ``block.signature`` (last-write-wins).+- ``citations_delta`` appends each citation object to ``block.citations``.+- ``redacted_thinking`` content_block_start preserves the opaque+ ``data`` field as-is.+"""++from __future__ import annotations++import json+from typing import Any++from headroom.proxy.handlers.streaming import StreamingMixin+++class _Parser(StreamingMixin):+ """Subclass that exposes the parser without the rest of the proxy."""+++def _build_sse(events: list[dict[str, Any]]) -> str:+ """Render a list of event dicts as an SSE payload string."""+ out: list[str] = []+ for ev in events:+ out.append(f"event: {ev['type']}")+ out.append(f"data: {json.dumps(ev)}")+ out.append("") # event terminator+ return "\n".join(out) + "\n"+++def test_thinking_delta_accumulated() -> None:+ parser = _Parser()+ events = [+ {"type": "message_start", "message": {"id": "msg_1", "model": "claude-opus-4"}},+ {+ "type": "content_block_start",+ "index": 0,+ "content_block": {"type": "thinking", "thinking": ""},+ },+ {+ "type": "content_block_delta",+ "index": 0,+ "delta": {"type": "thinking_delta", "thinking": "Let me consider "},+ },+ {+ "type": "content_block_delta",+ "index": 0,+ "delta": {"type": "thinking_delta", "thinking": "the question carefully."},+ },+ {"type": "content_block_stop", "index": 0},+ ]+ sse = _build_sse(events)+ response = parser._parse_sse_to_response(sse, "anthropic")+ assert response is not None+ assert len(response["content"]) == 1+ block = response["content"][0]+ assert block["type"] == "thinking"+ assert block["thinking"] == "Let me consider the question carefully."+++def test_signature_delta_preserved() -> None:+ parser = _Parser()+ events = [+ {"type": "message_start", "message": {"id": "msg_1", "model": "claude-opus-4"}},+ {+ "type": "content_block_start",+ "index": 0,+ "content_block": {"type": "thinking", "thinking": ""},+ },+ {+ "type": "content_block_delta",+ "index": 0,+ "delta": {"type": "thinking_delta", "thinking": "hmm"},+ },+ {+ "type": "content_block_delta",+ "index": 0,+ "delta": {"type": "signature_delta", "signature": "sig_abc123_v1"},+ },+ {"type": "content_block_stop", "index": 0},+ ]+ sse = _build_sse(events)+ response = parser._parse_sse_to_response(sse, "anthropic")+ assert response is not None+ block = response["content"][0]+ assert block["signature"] == "sig_abc123_v1"+ # Last-write-wins semantics — second signature_delta overrides.+ events2 = events + [+ {+ "type": "content_block_delta",+ "index": 0,+ "delta": {"type": "signature_delta", "signature": "sig_xyz999_v2"},+ },+ ]+ # Re-emit with the corrected ordering: stop must come after all deltas.+ events2 = [e for e in events2 if e["type"] != "content_block_stop"]+ events2.append({"type": "content_block_stop", "index": 0})+ response2 = parser._parse_sse_to_response(_build_sse(events2), "anthropic")+ assert response2 is not None+ assert response2["content"][0]["signature"] == "sig_xyz999_v2"+++def test_citations_delta_accumulated() -> None:+ parser = _Parser()+ events = [+ {"type": "message_start", "message": {"id": "msg_1", "model": "claude-opus-4"}},+ {+ "type": "content_block_start",+ "index": 0,+ "content_block": {"type": "text", "text": ""},+ },+ {+ "type": "content_block_delta",+ "index": 0,+ "delta": {"type": "text_delta", "text": "Per source A"},+ },+ {+ "type": "content_block_delta",+ "index": 0,+ "delta": {+ "type": "citations_delta",+ "citation": {+ "type": "page_location",+ "cited_text": "abc",+ "document_index": 0,+ },+ },+ },+ {+ "type": "content_block_delta",+ "index": 0,+ "delta": {+ "type": "citations_delta",+ "citation": {+ "type": "page_location",+ "cited_text": "def",+ "document_index": 1,+ },+ },+ },+ {"type": "content_block_stop", "index": 0},+ ]+ sse = _build_sse(events)+ response = parser._parse_sse_to_response(sse, "anthropic")+ assert response is not None+ block = response["content"][0]+ citations = block["citations"]+ assert len(citations) == 2+ assert citations[0]["cited_text"] == "abc"+ assert citations[1]["cited_text"] == "def"+++def test_redacted_thinking_data_preserved() -> None:+ parser = _Parser()+ redacted_blob = "ENC:" + ("x" * 200)+ events = [+ {"type": "message_start", "message": {"id": "msg_1", "model": "claude-opus-4"}},+ {+ "type": "content_block_start",+ "index": 0,+ "content_block": {"type": "redacted_thinking", "data": redacted_blob},+ },+ {"type": "content_block_stop", "index": 0},+ ]+ sse = _build_sse(events)+ response = parser._parse_sse_to_response(sse, "anthropic")+ assert response is not None+ block = response["content"][0]+ assert block["type"] == "redacted_thinking"+ # `data` field MUST be preserved byte-for-byte for signature+ # validation on the next turn.+ assert block["data"] == redacted_blobdiff --git a/tests/test_sse_utf8_split.py b/tests/test_sse_utf8_split.pynew file mode 100644index 000000000..989506738--- /dev/null+++ b/tests/test_sse_utf8_split.py@@ -0,0 +1,97 @@+"""PR-A8 / P1-8: bytes-level SSE buffer survives multi-byte splits.++Pre-A8 the proxy decoded each chunk via ``chunk.decode("utf-8",+errors="ignore")``. A 4-byte emoji or 3-byte CJK character split across+two TCP reads was silently dropped, corrupting the downstream parser's+view of the stream. The fix moves event-boundary detection into bytes+and decodes only complete events.++These tests pin:+- ``parse_sse_events_from_byte_buffer`` preserves emoji split mid-bytes.+- Same for CJK chars.+- A complete event with invalid UTF-8 raises (operator-visible diagnostic).+"""++from __future__ import annotations++import json++import pytest++from headroom.proxy.helpers import parse_sse_events_from_byte_buffer+++def _emit_event(name: str, data: str) -> bytes:+ return f"event: {name}\ndata: {data}\n\n".encode()+++def test_emoji_split_across_chunks_preserved() -> None:+ """Fire emoji `🔥` split mid-byte: 4 bytes total, split 2/2."""+ # `ensure_ascii=False` keeps the emoji as raw UTF-8 bytes on the+ # wire — that's the case where chunk-boundary splits actually+ # corrupt content with the old `errors="ignore"` decoder.+ payload = json.dumps({"type": "text_delta", "text": "fire 🔥 here"}, ensure_ascii=False)+ full = _emit_event("content_block_delta", payload)+ # Split somewhere inside the 4-byte emoji. The emoji `🔥` is+ # `\xf0\x9f\x94\xa5` — find that sequence and split mid-bytes.+ emoji_bytes = "🔥".encode()+ assert emoji_bytes == b"\xf0\x9f\x94\xa5"+ idx = full.find(emoji_bytes)+ assert idx > 0+ # Split halfway through the emoji.+ chunk_a = full[: idx + 2]+ chunk_b = full[idx + 2 :]++ buf = bytearray()+ buf.extend(chunk_a)+ # First chunk should not produce any complete events because the+ # event terminator `\n\n` is in chunk_b — but more importantly,+ # the helper must not corrupt the partial emoji bytes.+ events = parse_sse_events_from_byte_buffer(buf)+ assert events == []+ # Buffer still contains the partial emoji + everything before it.+ assert b"\xf0\x9f" in bytes(buf)++ buf.extend(chunk_b)+ events = parse_sse_events_from_byte_buffer(buf)+ assert len(events) == 1+ name, data_str = events[0]+ assert name == "content_block_delta"+ parsed = json.loads(data_str)+ assert parsed["text"] == "fire 🔥 here"+++def test_cjk_split_across_chunks_preserved() -> None:+ """CJK `語` is 3 bytes (e8 aa 9e); split 1/2 across two reads."""+ payload = json.dumps({"type": "text_delta", "text": "日本語テスト"}, ensure_ascii=False)+ full = _emit_event("content_block_delta", payload)+ needle = "語".encode()+ assert needle == b"\xe8\xaa\x9e"+ idx = full.find(needle)+ assert idx > 0+ chunk_a = full[: idx + 1]+ chunk_b = full[idx + 1 :]++ buf = bytearray()+ buf.extend(chunk_a)+ events = parse_sse_events_from_byte_buffer(buf)+ assert events == [] # no complete event yet++ buf.extend(chunk_b)+ events = parse_sse_events_from_byte_buffer(buf)+ assert len(events) == 1+ _, data_str = events[0]+ parsed = json.loads(data_str)+ assert parsed["text"] == "日本語テスト"+++def test_complete_event_with_invalid_utf8_raises_loud() -> None:+ """Invalid UTF-8 in a *complete* event surfaces loudly (not silent corruption)."""+ # Build a complete event whose data field has invalid UTF-8 bytes+ # NOT split across a chunk boundary — this is a true upstream bug+ # we want operators to see, not silently fix-up.+ bad = b'event: content_block_delta\ndata: {"text":"\xff\xfe"}\n\n'+ buf = bytearray()+ buf.extend(bad)+ with pytest.raises(UnicodeDecodeError):+ parse_sse_events_from_byte_buffer(buf)