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: C1 — byte-level SSE parser + state machines
chopratejasddc6f6ceb035
diff --git a/Cargo.lock b/Cargo.lockindex e08788a7b..c2261c95e 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -1454,6 +1454,7 @@ dependencies = ["hyper","hyper-util","pin-project-lite",+ "proptest","reqwest","serde","serde_json",diff --git a/crates/headroom-proxy/Cargo.toml b/crates/headroom-proxy/Cargo.tomlindex 308071d00..61e507661 100644--- a/crates/headroom-proxy/Cargo.toml+++ b/crates/headroom-proxy/Cargo.toml@@ -59,3 +59,9 @@ tokio-stream = "0.1"# value-equality misses whitespace, key order, and Unicode escape# differences that all bust the prompt cache.sha2 = "0.10"+# PR-C1: property tests for the byte-level SSE parser. The parser+# must never panic on arbitrary input bytes (TCP can hand us anything,+# including malformed UTF-8 split mid-codepoint or fuzz-generated+# noise). 100K cases is the project default for "no panic" parser+# invariants — see `feedback_realignment_build_constraints.md`.+proptest = "1"diff --git a/crates/headroom-proxy/src/lib.rs b/crates/headroom-proxy/src/lib.rsindex 3179c9fdc..acb601ab1 100644--- a/crates/headroom-proxy/src/lib.rs+++ b/crates/headroom-proxy/src/lib.rs@@ -7,6 +7,7 @@ pub mod error;pub mod headers;pub mod health;pub mod proxy;+pub mod sse;pub mod websocket;pub use config::Config;diff --git a/crates/headroom-proxy/src/proxy.rs b/crates/headroom-proxy/src/proxy.rsindex 66bc719a8..ca274a15b 100644--- a/crates/headroom-proxy/src/proxy.rs+++ b/crates/headroom-proxy/src/proxy.rs@@ -443,13 +443,54 @@ async fn forward_http(.clone().or_else(|| upstream_request_id_openai.clone());+ // PR-C1: detect SSE responses so the state machine can run in+ // parallel with the byte-passthrough. We classify ONCE here and+ // pick the response provider arm based on the request path —+ // bytes flow to the client unchanged; the state machine sinks+ // bytes into a `tokio::sync::mpsc` and runs in a spawned task+ // that can never block the byte path.+ let is_sse = is_sse_response(upstream_resp.headers());+ let sse_kind = if is_sse {+ SseStreamKind::for_request_path(&path_for_log)+ } else {+ SseStreamKind::None+ };+let resp_headers = filter_response_headers(upstream_resp.headers());// Stream response body back without buffering. Wrap errors so mid-stream// upstream failures are logged rather than silently truncating the client.+ //+ // PR-C1: when this is an SSE response, tee each chunk into a+ // bounded mpsc so the spawned state-machine task can update+ // telemetry without ever holding up the client. The mpsc is+ // bounded; if the parser falls behind, `try_send` fails and we+ // log + drop — the byte path is not affected. This is the+ // explicit "never block on parser readiness" contract.let rid = request_id.clone();+ let parser_tx = if !matches!(sse_kind, SseStreamKind::None) {+ let (tx, rx) = tokio::sync::mpsc::channel::<bytes::Bytes>(SSE_PARSER_QUEUE_DEPTH);+ let rid_for_parser = request_id.clone();+ tokio::spawn(run_sse_state_machine(sse_kind, rx, rid_for_parser));+ Some(tx)+ } else {+ None+ };let resp_stream = upstream_resp.bytes_stream().map(move |r| match r {- Ok(b) => Ok(b),+ Ok(b) => {+ if let Some(tx) = &parser_tx {+ // Best-effort tee. Bounded channel; the state+ // machine never blocks the client byte path.+ if let Err(e) = tx.try_send(b.clone()) {+ tracing::debug!(+ request_id = %rid,+ error = %e,+ "sse parser queue full or closed; skipping telemetry chunk"+ );+ }+ }+ Ok(b)+ }Err(e) => {tracing::warn!(request_id = %rid, error = %e, "upstream stream error mid-response");Err(e)@@ -495,6 +536,173 @@ async fn forward_http(Ok(response)}+/// Bound on the in-flight queue between the byte-passthrough and the+/// SSE state-machine task. Picked so that under steady-state streaming+/// load (~5 events/100ms typical) the parser is never blocked on+/// queue space, yet a stalled parser can't grow memory unboundedly.+/// Tunable via `proxy.toml` if a deployment finds this insufficient.+const SSE_PARSER_QUEUE_DEPTH: usize = 256;++/// Which provider's state machine should run on this stream. Picked+/// from the *request* path because the response content-type+/// (`text/event-stream`) is identical across providers.+#[derive(Debug, Clone, Copy)]+enum SseStreamKind {+ None,+ Anthropic,+ OpenAiChat,+ OpenAiResponses,+}++impl SseStreamKind {+ fn for_request_path(path: &str) -> Self {+ match path {+ "/v1/messages" => Self::Anthropic,+ "/v1/chat/completions" => Self::OpenAiChat,+ "/v1/responses" => Self::OpenAiResponses,+ // No telemetry parser registered for this endpoint.+ // We still pass bytes through unchanged.+ _ => Self::None,+ }+ }+}++/// True if the upstream response is an SSE stream. Compares+/// `content-type` against `text/event-stream` (with optional+/// parameters). RFC 7231 §3.1.1.1: media types compare+/// case-insensitive on the type/subtype tokens.+fn is_sse_response(headers: &http::HeaderMap) -> bool {+ headers+ .get(http::header::CONTENT_TYPE)+ .and_then(|v| v.to_str().ok())+ .map(|s| {+ let media_type = s.split(';').next().unwrap_or("").trim();+ media_type.eq_ignore_ascii_case("text/event-stream")+ })+ .unwrap_or(false)+}++/// Drive the per-provider state machine over a stream of byte chunks.+/// Lives in its own task; the byte path never waits on it.+async fn run_sse_state_machine(+ kind: SseStreamKind,+ mut rx: tokio::sync::mpsc::Receiver<bytes::Bytes>,+ request_id: String,+) {+ use crate::sse::framing::SseFramer;++ let mut framer = SseFramer::new();+ // The state machines are different types; rather than introducing+ // a trait object dance, run each variant in its own arm. The dead+ // branches compile out cleanly and the hot path stays monomorphic.+ match kind {+ SseStreamKind::Anthropic => {+ let mut state = crate::sse::anthropic::AnthropicStreamState::new();+ while let Some(chunk) = rx.recv().await {+ framer.push(&chunk);+ while let Some(ev_result) = framer.next_event() {+ match ev_result {+ Ok(ev) => {+ if let Err(e) = state.apply(ev) {+ tracing::warn!(+ request_id = %request_id,+ error = %e,+ "sse anthropic state-machine apply error"+ );+ }+ }+ Err(e) => {+ tracing::warn!(+ request_id = %request_id,+ error = %e,+ "sse framer error"+ );+ }+ }+ }+ }+ tracing::info!(+ request_id = %request_id,+ provider = "anthropic",+ input_tokens = state.usage.input_tokens,+ output_tokens = state.usage.output_tokens,+ cache_creation_input_tokens = state.usage.cache_creation_input_tokens,+ cache_read_input_tokens = state.usage.cache_read_input_tokens,+ stop_reason = state.stop_reason.as_deref().unwrap_or(""),+ blocks = state.blocks.len(),+ "sse stream closed"+ );+ }+ SseStreamKind::OpenAiChat => {+ let mut state = crate::sse::openai_chat::ChunkState::new();+ while let Some(chunk) = rx.recv().await {+ framer.push(&chunk);+ while let Some(ev_result) = framer.next_event() {+ match ev_result {+ Ok(ev) => {+ if let Err(e) = state.apply(ev) {+ tracing::warn!(+ request_id = %request_id,+ error = %e,+ "sse openai_chat state-machine apply error"+ );+ }+ }+ Err(e) => {+ tracing::warn!(+ request_id = %request_id,+ error = %e,+ "sse framer error"+ );+ }+ }+ }+ }+ tracing::info!(+ request_id = %request_id,+ provider = "openai_chat",+ choices = state.choices.len(),+ has_usage = state.usage.is_some(),+ "sse stream closed"+ );+ }+ SseStreamKind::OpenAiResponses => {+ let mut state = crate::sse::openai_responses::ResponseState::new();+ while let Some(chunk) = rx.recv().await {+ framer.push(&chunk);+ while let Some(ev_result) = framer.next_event() {+ match ev_result {+ Ok(ev) => {+ if let Err(e) = state.apply(ev) {+ tracing::warn!(+ request_id = %request_id,+ error = %e,+ "sse openai_responses state-machine apply error"+ );+ }+ }+ Err(e) => {+ tracing::warn!(+ request_id = %request_id,+ error = %e,+ "sse framer error"+ );+ }+ }+ }+ }+ tracing::info!(+ request_id = %request_id,+ provider = "openai_responses",+ items = state.items.len(),+ has_usage = state.usage.is_some(),+ "sse stream closed"+ );+ }+ SseStreamKind::None => {}+ }+}+fn ensure_request_id(headers: &HeaderMap) -> String {headers.get("x-request-id")diff --git a/crates/headroom-proxy/src/sse/anthropic.rs b/crates/headroom-proxy/src/sse/anthropic.rsnew file mode 100644index 000000000..4aaa03542--- /dev/null+++ b/crates/headroom-proxy/src/sse/anthropic.rs@@ -0,0 +1,415 @@+//! Anthropic Messages streaming state machine.+//!+//! Per the Anthropic Messages streaming guide §5.1, an Anthropic+//! response stream is a sequence of named events:+//!+//! message_start+//! content_block_start (index=0)+//! content_block_delta (index=0) ×N+//! content_block_stop (index=0)+//! content_block_start (index=1)+//! content_block_delta (index=1) ×N+//! content_block_stop (index=1)+//! ...+//! message_delta (carries final stop_reason, output_tokens)+//! message_stop+//!+//! Blocks are keyed by `index`, NOT by position. While in practice+//! Anthropic emits them in monotone ascending order, the spec does+//! not require this — our state machine tolerates out-of-order+//! interleaving (test `interleaved_blocks_by_index`).+//!+//! `content_block_delta` carries a `delta` object whose `type` field+//! determines how the payload accumulates:+//!+//! - `text_delta` — append `delta.text` to `text_buffer`.+//! - `thinking_delta` — append `delta.thinking` to `text_buffer`+//! (the block's `block_type == "thinking"`).+//! - `signature_delta` — set `signature` to `delta.signature`,+//! BYTE-FOR-BYTE preserved (cryptographic verification of+//! redacted thinking).+//! - `input_json_delta` — append `delta.partial_json` to+//! `partial_json`. At `content_block_stop` the accumulated string+//! is parsed once into the block's `input` (we keep the string+//! form for telemetry to avoid re-stringifying on the response+//! side).+//! - `citations_delta` — append `delta.citation` to `citations`.+//!+//! P1-8/9/14/17 in the production telemetry log come from missing+//! delta-type arms (the Python proxy ignored thinking_delta,+//! signature_delta, citations_delta). This module enumerates ALL+//! known delta types; any unknown delta type emits a tracing warn+//! with `event=sse_unknown_event` so operators see the wire-format+//! drift loudly.++use std::collections::HashMap;++use serde_json::Value;++use super::framing::SseEvent;++/// Streaming-stream-level status. `Open` is the steady state during+/// streaming. `MessageStop` and `Errored` are terminal — pushing more+/// events is logged but does not panic.+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]+pub enum StreamStatus {+ /// `message_start` has been received; events will follow.+ #[default]+ Open,+ /// `message_stop` has been received; the stream is done.+ MessageStop,+ /// An `error` event was received mid-stream OR we received a+ /// terminal-state-violation (events after `message_stop`).+ Errored,+}++/// Per-block state. A "block" is one entry in the `content` array+/// of the final response — text, tool_use, thinking, etc.+#[derive(Debug, Clone, Default)]+pub struct BlockState {+ /// `content_block_start.content_block.type`:+ /// "text" | "thinking" | "tool_use" | "redacted_thinking" | ...+ pub block_type: String,+ /// Accumulated text for `text_delta` / `thinking_delta`.+ pub text_buffer: String,+ /// Accumulated `partial_json` from `input_json_delta`. Intentionally+ /// kept as a String — the spec says it's a JSON-fragment string,+ /// not a partial value, and we only parse it once at+ /// `content_block_stop` (or never, if the consumer wants the raw+ /// fragment for replay).+ pub partial_json: String,+ /// Cryptographic signature for redacted_thinking blocks. Must be+ /// preserved BYTE-EQUAL across the proxy — Anthropic uses this+ /// for verification on subsequent calls. Storing as a `String`+ /// is safe because the wire format guarantees ASCII base64.+ pub signature: Option<String>,+ /// Accumulated citations from `citations_delta`. Stored as raw+ /// `serde_json::Value` because Anthropic continues to extend the+ /// citation shape; we do not enforce a strict schema here.+ pub citations: Vec<Value>,+ /// Initial metadata from `content_block_start.content_block` —+ /// the `id`, `name`, `input` (for tool_use), etc. Preserved+ /// verbatim so downstream code can introspect type-specific+ /// fields without re-parsing the wire.+ pub metadata: Value,+ /// True after `content_block_stop` for this index.+ pub complete: bool,+}++/// Per-stream state. Lives in a `tokio::spawn`ed task that consumes+/// framed events from the SSE framer; the response byte-passthrough+/// is independent (see `wire_state_machine` in `proxy.rs`).+#[derive(Debug, Default)]+pub struct AnthropicStreamState {+ pub message_id: Option<String>,+ pub model: Option<String>,+ /// Block index → block state. Keyed by index, not Vec position,+ /// because the spec allows out-of-order completion.+ pub blocks: HashMap<usize, BlockState>,+ /// The most recent block index opened via `content_block_start`.+ /// Tracks "which block is the live zone right now" but does NOT+ /// gate which block a delta applies to — every delta carries its+ /// own `index`.+ pub current_block_index: Option<usize>,+ /// Set on `message_delta` (NOT `message_stop` — Anthropic puts+ /// the final stop_reason on the delta).+ pub stop_reason: Option<String>,+ pub usage: UsageBuilder,+ pub status: StreamStatus,+}++/// Accumulator for token counts. `message_start` carries the input+/// tokens (and an initial `output_tokens: N` that may be 0); each+/// `message_delta.usage` carries an updated `output_tokens` that+/// strictly grows. We keep the latest values; the final values+/// surface at `message_stop`.+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]+pub struct UsageBuilder {+ pub input_tokens: u64,+ pub output_tokens: u64,+ pub cache_creation_input_tokens: u64,+ pub cache_read_input_tokens: u64,+}++/// Errors during state-machine application. Per project rules these+/// must NOT silently degrade — callers `tracing::warn!` and either+/// drop the event or close the stream. None of these is a panic.+#[derive(Debug, thiserror::Error)]+pub enum StateError {+ #[error("event payload is not valid UTF-8: {0}")]+ PayloadNotUtf8(#[from] std::str::Utf8Error),+ #[error("event payload is not valid JSON: {0}")]+ PayloadNotJson(#[from] serde_json::Error),+ #[error("event missing required field {field}")]+ MissingField { field: &'static str },+}++impl AnthropicStreamState {+ pub fn new() -> Self {+ Self::default()+ }++ /// Apply one framed event. The `event_name` is required (Anthropic+ /// always emits an `event:` line); a None name is logged and+ /// dropped silently because the SSE comment rule already filtered+ /// keepalives upstream.+ pub fn apply(&mut self, event: SseEvent) -> Result<(), StateError> {+ let Some(name) = event.event_name.as_deref() else {+ // No `event:` line. Anthropic always sends one; this is+ // wire-format drift. Log and drop. We do NOT route by+ // `data` shape because that would invite the+ // silent-fallback class of bug.+ tracing::warn!(+ event = "sse_unknown_event",+ provider = "anthropic",+ event_name = "<missing>",+ payload_preview = %payload_preview(&event.data),+ "anthropic event missing required event: line; dropping"+ );+ return Ok(());+ };++ match name {+ "ping" => {+ // Anthropic emits explicit `event: ping` events+ // alongside SSE-level `: ping` comments. Both are+ // keepalives; we already drop comments at the framer.+ Ok(())+ }+ "message_start" => self.on_message_start(&event),+ "content_block_start" => self.on_content_block_start(&event),+ "content_block_delta" => self.on_content_block_delta(&event),+ "content_block_stop" => self.on_content_block_stop(&event),+ "message_delta" => self.on_message_delta(&event),+ "message_stop" => {+ self.status = StreamStatus::MessageStop;+ Ok(())+ }+ "error" => {+ self.status = StreamStatus::Errored;+ tracing::warn!(+ event = "sse_anthropic_error_event",+ payload_preview = %payload_preview(&event.data),+ "anthropic stream emitted error event"+ );+ Ok(())+ }+ other => {+ // Unknown event name — wire-format drift or new+ // event type Anthropic added that we haven't ported+ // yet. Log loudly per `feedback_no_silent_fallbacks.md`.+ tracing::warn!(+ event = "sse_unknown_event",+ provider = "anthropic",+ event_name = other,+ payload_preview = %payload_preview(&event.data),+ "unknown anthropic event; preserving stream but not updating state"+ );+ Ok(())+ }+ }+ }++ fn on_message_start(&mut self, event: &SseEvent) -> Result<(), StateError> {+ let v: Value = parse_json(&event.data)?;+ let msg = v+ .get("message")+ .ok_or(StateError::MissingField { field: "message" })?;+ if let Some(id) = msg.get("id").and_then(|x| x.as_str()) {+ self.message_id = Some(id.to_string());+ }+ if let Some(model) = msg.get("model").and_then(|x| x.as_str()) {+ self.model = Some(model.to_string());+ }+ if let Some(usage) = msg.get("usage") {+ self.usage.merge_from(usage);+ }+ self.status = StreamStatus::Open;+ Ok(())+ }++ fn on_content_block_start(&mut self, event: &SseEvent) -> Result<(), StateError> {+ let v: Value = parse_json(&event.data)?;+ let index = v+ .get("index")+ .and_then(|x| x.as_u64())+ .ok_or(StateError::MissingField { field: "index" })? as usize;+ let cb = v.get("content_block").ok_or(StateError::MissingField {+ field: "content_block",+ })?;+ let block_type = cb+ .get("type")+ .and_then(|x| x.as_str())+ .unwrap_or("")+ .to_string();+ let mut block = BlockState {+ block_type,+ metadata: cb.clone(),+ ..Default::default()+ };+ // Some block types start with content already (e.g. a+ // `text` block whose initial chunk arrives in+ // `content_block.text`). Capture it so the subsequent+ // deltas append cleanly.+ if let Some(initial_text) = cb.get("text").and_then(|x| x.as_str()) {+ block.text_buffer.push_str(initial_text);+ }+ if let Some(initial_thinking) = cb.get("thinking").and_then(|x| x.as_str()) {+ block.text_buffer.push_str(initial_thinking);+ }+ self.blocks.insert(index, block);+ self.current_block_index = Some(index);+ Ok(())+ }++ fn on_content_block_delta(&mut self, event: &SseEvent) -> Result<(), StateError> {+ let v: Value = parse_json(&event.data)?;+ let index = v+ .get("index")+ .and_then(|x| x.as_u64())+ .ok_or(StateError::MissingField { field: "index" })? as usize;+ let delta = v+ .get("delta")+ .ok_or(StateError::MissingField { field: "delta" })?;+ let delta_type =+ delta+ .get("type")+ .and_then(|x| x.as_str())+ .ok_or(StateError::MissingField {+ field: "delta.type",+ })?;++ let block = self.blocks.entry(index).or_default();+ match delta_type {+ "text_delta" => {+ if let Some(t) = delta.get("text").and_then(|x| x.as_str()) {+ block.text_buffer.push_str(t);+ }+ }+ "thinking_delta" => {+ // Note: thinking_delta uses a `thinking` field, not `text`.+ if let Some(t) = delta.get("thinking").and_then(|x| x.as_str()) {+ block.text_buffer.push_str(t);+ }+ }+ "input_json_delta" => {+ if let Some(p) = delta.get("partial_json").and_then(|x| x.as_str()) {+ block.partial_json.push_str(p);+ }+ }+ "signature_delta" => {+ // BYTE-EQUAL preservation: take the wire string verbatim,+ // even if it's empty (an empty signature is itself a+ // signal — it means the model declined to sign).+ if let Some(sig) = delta.get("signature").and_then(|x| x.as_str()) {+ // Concatenate if a previous signature_delta arrived.+ // In practice Anthropic emits the full signature in+ // one delta, but the spec permits chunking.+ match &mut block.signature {+ Some(s) => s.push_str(sig),+ None => block.signature = Some(sig.to_string()),+ }+ }+ }+ "citations_delta" => {+ if let Some(c) = delta.get("citation") {+ block.citations.push(c.clone());+ }+ }+ other => {+ tracing::warn!(+ event = "sse_unknown_event",+ provider = "anthropic",+ event_name = "content_block_delta",+ delta_type = other,+ payload_preview = %payload_preview(&event.data),+ "unknown anthropic delta.type; preserving stream but not updating state"+ );+ }+ }+ Ok(())+ }++ fn on_content_block_stop(&mut self, event: &SseEvent) -> Result<(), StateError> {+ let v: Value = parse_json(&event.data)?;+ let index = v+ .get("index")+ .and_then(|x| x.as_u64())+ .ok_or(StateError::MissingField { field: "index" })? as usize;+ if let Some(block) = self.blocks.get_mut(&index) {+ block.complete = true;+ // If we accumulated input_json_delta fragments, attempt+ // to parse the final string. Failure is logged but does+ // not error — the raw fragment is still available for+ // replay/telemetry.+ if !block.partial_json.is_empty() {+ if let Err(e) = serde_json::from_str::<Value>(&block.partial_json) {+ tracing::warn!(+ event = "sse_partial_json_unparseable",+ provider = "anthropic",+ block_index = index,+ error = %e,+ "input_json_delta accumulated string did not parse; \+ keeping raw fragment in BlockState.partial_json"+ );+ }+ }+ }+ Ok(())+ }++ fn on_message_delta(&mut self, event: &SseEvent) -> Result<(), StateError> {+ let v: Value = parse_json(&event.data)?;+ if let Some(delta) = v.get("delta") {+ if let Some(stop_reason) = delta.get("stop_reason").and_then(|x| x.as_str()) {+ self.stop_reason = Some(stop_reason.to_string());+ }+ }+ if let Some(usage) = v.get("usage") {+ self.usage.merge_from(usage);+ }+ Ok(())+ }+}++impl UsageBuilder {+ /// Merge a JSON `usage` object into the accumulator. Per the+ /// Anthropic spec, fields are monotone non-decreasing within a+ /// single stream, so we simply take the maximum of (previous,+ /// incoming) for each field. If the incoming object is missing+ /// a field, the previous value is preserved.+ pub fn merge_from(&mut self, v: &Value) {+ if let Some(n) = v.get("input_tokens").and_then(|x| x.as_u64()) {+ self.input_tokens = self.input_tokens.max(n);+ }+ if let Some(n) = v.get("output_tokens").and_then(|x| x.as_u64()) {+ self.output_tokens = self.output_tokens.max(n);+ }+ if let Some(n) = v+ .get("cache_creation_input_tokens")+ .and_then(|x| x.as_u64())+ {+ self.cache_creation_input_tokens = self.cache_creation_input_tokens.max(n);+ }+ if let Some(n) = v.get("cache_read_input_tokens").and_then(|x| x.as_u64()) {+ self.cache_read_input_tokens = self.cache_read_input_tokens.max(n);+ }+ }+}++fn parse_json(data: &bytes::Bytes) -> Result<Value, StateError> {+ let s = std::str::from_utf8(data)?;+ Ok(serde_json::from_str(s)?)+}++/// Up to 96 bytes of the payload, lossy-decoded for log readability.+/// Used only on warn paths — never on the success hot path.+fn payload_preview(data: &bytes::Bytes) -> String {+ const LIMIT: usize = 96;+ let slice = if data.len() > LIMIT {+ &data[..LIMIT]+ } else {+ &data[..]+ };+ String::from_utf8_lossy(slice).into_owned()+}diff --git a/crates/headroom-proxy/src/sse/framing.rs b/crates/headroom-proxy/src/sse/framing.rsnew file mode 100644index 000000000..bd337c60b--- /dev/null+++ b/crates/headroom-proxy/src/sse/framing.rs@@ -0,0 +1,366 @@+//! Byte-level Server-Sent Events (SSE) framing.+//!+//! # Why byte-level+//!+//! The Python proxy decoded each TCP chunk to UTF-8 with+//! `errors="ignore"`, which silently lost bytes whenever a multi-byte+//! codepoint (any emoji, any non-ASCII character) straddled a chunk+//! boundary. Production telemetry logged 1946 parse failures over 9+//! days from this single quirk — see+//! `~/Desktop/HEADROOM_PROXY_LOG_FINDINGS_2026_05_03.md` (P1-15).+//!+//! The Rust framer accumulates raw bytes into a `BytesMut` buffer and+//! finds event terminators (`\n\n`) in **bytes**. UTF-8 is decoded+//! exactly once, per complete event, so split-codepoint chunks rejoin+//! correctly. Per project invariants we never call `from_utf8_lossy`+//! on partial buffers — the buffer holds bytes until a full event is+//! framed, then a single `String::from_utf8` decodes the whole thing.+//!+//! # Wire format+//!+//! Per WHATWG SSE spec + provider extensions:+//! - Lines end with `\n` (CR is tolerated and stripped, but providers+//! in practice send LF only).+//! - An event terminates on a blank line (i.e. consecutive `\n\n`).+//! - Lines starting with `:` are comments. Anthropic and OpenAI use+//! `: ping` keepalives; we drop them silently (they convey no data).+//! - The literal `data: [DONE]` is a stream-end sentinel used by+//! OpenAI Chat/Responses (Anthropic uses `event: message_stop`+//! instead). Some providers append a trailing `\n\n` after `[DONE]`;+//! we tolerate any number of trailing bytes.+//! - Multiple `data:` lines in one event concatenate with `\n` per+//! the WHATWG spec. (Anthropic does not currently use this; OpenAI+//! Responses occasionally does.)+//!+//! # Zero-copy where possible+//!+//! The framer is built on `bytes::Bytes` which is reference-counted;+//! `extract_event_payload` slices the underlying buffer rather than+//! copying. UTF-8 decoding is the one unavoidable allocation per+//! event (we need a `String`/`&str` for downstream parsing).++use bytes::{Bytes, BytesMut};++/// One framed SSE event ready for state-machine consumption.+///+/// `event_name` is the value of the `event:` field (e.g.+/// `message_start`, `content_block_delta`). It is `None` when the+/// event has no `event:` line — the OpenAI Chat Completions stream+/// does this for every chunk (only the `data:` field is present, and+/// the event type is encoded inside the JSON payload).+///+/// `data` is the concatenated value of all `data:` fields in the+/// event, joined by `\n` per the SSE spec. `data` is **not** UTF-8+/// validated here — the framer only guarantees that `data` is the+/// exact byte slice between the field prefix and the event+/// terminator. State-machine code that needs UTF-8 calls+/// `event.data_str()` which returns `Result<&str, Utf8Error>`.+#[derive(Debug, Clone, PartialEq, Eq)]+pub struct SseEvent {+ pub event_name: Option<String>,+ pub data: Bytes,+}++impl SseEvent {+ /// UTF-8 decode the data payload. Returns `Err` on invalid UTF-8;+ /// the framer never panics, so malformed bytes surface here as a+ /// recoverable error the state machine can log and skip.+ pub fn data_str(&self) -> Result<&str, std::str::Utf8Error> {+ std::str::from_utf8(&self.data)+ }++ /// True iff the data field is the literal `[DONE]` sentinel used+ /// by OpenAI Chat Completions and OpenAI Responses to mark end of+ /// stream. Anthropic does not use this — it terminates with an+ /// `event: message_stop`.+ pub fn is_done_sentinel(&self) -> bool {+ // Compare bytes directly so we never touch UTF-8 validation+ // on the hot path. `[DONE]` is pure ASCII, so any byte-equal+ // match is a genuine sentinel.+ self.data.as_ref() == b"[DONE]"+ }+}++/// Stateful byte-level SSE framer.+///+/// Feed `Bytes` chunks via [`SseFramer::push`]; pull complete framed+/// events via [`SseFramer::next_event`]. The framer never blocks and+/// never allocates on the input chunks (it appends to an internal+/// `BytesMut` and then slices that). On `take_remaining`, callers can+/// recover unparsed trailing bytes (used by tests; production code+/// just drops the framer at end-of-stream).+#[derive(Debug, Default)]+pub struct SseFramer {+ /// Accumulator for inbound bytes that have not yet been framed+ /// into a complete event. Always holds at most one in-flight+ /// event's worth of data plus any partial trailing bytes.+ buf: BytesMut,+ /// Once we see `[DONE]` we still tolerate further events (some+ /// providers append a final empty `\n\n`), but the state machine+ /// can use this to gate "no more useful events expected".+ done_seen: bool,+}++impl SseFramer {+ pub fn new() -> Self {+ Self::default()+ }++ /// True after the framer has yielded an event whose `data` is the+ /// `[DONE]` sentinel. Once this is set, additional bytes pushed+ /// in are still framed (so trailing whitespace doesn't error),+ /// but state-machine code may stop attending to events.+ pub fn done_seen(&self) -> bool {+ self.done_seen+ }++ /// Append a chunk of inbound bytes to the framer's buffer.+ ///+ /// `chunk` may straddle event boundaries, line boundaries, or+ /// multi-byte UTF-8 codepoints. The framer makes no assumptions+ /// beyond "these bytes appear, in order, after the bytes we've+ /// already seen on this stream". Zero-length chunks are a no-op.+ pub fn push(&mut self, chunk: &[u8]) {+ if chunk.is_empty() {+ return;+ }+ self.buf.extend_from_slice(chunk);+ }++ /// Drain the next complete event from the buffer, if one is+ /// available. Returns `None` if the buffer doesn't yet contain a+ /// blank-line terminator (`\n\n`). Returns `Some(Ok(event))` for+ /// each complete event. Returns `Some(Err(...))` only on+ /// genuinely malformed event content (e.g. `data:` line with+ /// invalid UTF-8 in `event:` name — `event:` must be ASCII per+ /// spec). Comments (`: ping`) and empty events are silently+ /// skipped: the framer keeps consuming bytes until either a real+ /// event surfaces or the buffer is exhausted.+ pub fn next_event(&mut self) -> Option<Result<SseEvent, FramingError>> {+ loop {+ let term_len: usize;+ let block_end = match find_double_newline(&self.buf) {+ Some((end, len)) => {+ term_len = len;+ end+ }+ None => return None,+ };+ // The block is bytes [0, block_end); skip past the+ // terminator (1 or 2 bytes — see find_double_newline).+ // BytesMut::split_to is O(1): it advances the head+ // pointer without copying, so we keep zero-copy framing.+ let block = self.buf.split_to(block_end).freeze();+ let _term = self.buf.split_to(term_len);++ match parse_event_block(block) {+ Ok(Some(event)) => {+ if event.is_done_sentinel() {+ self.done_seen = true;+ }+ return Some(Ok(event));+ }+ // No data lines (comment-only / empty event /+ // pure ping). Skip and try the next block.+ Ok(None) => continue,+ Err(e) => return Some(Err(e)),+ }+ }+ }++ /// Number of bytes currently buffered (un-framed). Useful for+ /// tests asserting that no bytes were lost across chunk boundaries.+ pub fn buffered_len(&self) -> usize {+ self.buf.len()+ }++ /// Drain any remaining un-framed bytes. Used by tests to assert+ /// "no bytes left over"; production code drops the framer.+ pub fn take_remaining(&mut self) -> Bytes {+ std::mem::take(&mut self.buf).freeze()+ }+}++/// Errors the framer surfaces. Per project rules we do **not**+/// silently swallow these — callers must `tracing::warn!` and either+/// drop the event or close the stream. The framer itself never+/// panics; the property test in `tests/sse_framing.rs` enforces this.+#[derive(Debug, thiserror::Error)]+pub enum FramingError {+ /// `event:` field present but not valid UTF-8. The SSE spec+ /// requires the field name and value to be ASCII; binary in+ /// `event:` is a wire-format violation, not data we can recover+ /// from. Real providers never emit this.+ #[error("event field is not valid UTF-8: {0}")]+ EventNameNotUtf8(std::str::Utf8Error),+}++/// Find the byte offset of the first `\n\n` (or `\r\n\r\n`) terminator+/// in `buf`. Returns `(offset, terminator_len)` so the caller can+/// split off the event block and skip the terminator. `\r\n\r\n` is+/// tolerated for completeness; in practice all production providers+/// emit pure `\n\n`.+fn find_double_newline(buf: &[u8]) -> Option<(usize, usize)> {+ // Manual byte-level search. Memchr would be faster on long+ // buffers, but a typical SSE event is < 4KB and we'd be searching+ // a tight window, so a simple loop wins on cache locality.+ let mut i = 0;+ while i + 1 < buf.len() {+ if buf[i] == b'\n' && buf[i + 1] == b'\n' {+ return Some((i, 2));+ }+ // \r\n\r\n+ if i + 3 < buf.len()+ && buf[i] == b'\r'+ && buf[i + 1] == b'\n'+ && buf[i + 2] == b'\r'+ && buf[i + 3] == b'\n'+ {+ return Some((i, 4));+ }+ i += 1;+ }+ None+}++/// Parse a single SSE event block (the bytes between two `\n\n`+/// terminators). Returns `Ok(None)` when the block contained no+/// `data:` lines (comment-only, empty, or pure ping).+fn parse_event_block(block: Bytes) -> Result<Option<SseEvent>, FramingError> {+ let mut event_name: Option<String> = None;+ let mut data_parts: Vec<Bytes> = Vec::new();++ let mut start = 0usize;+ while start < block.len() {+ // Find end of line.+ let line_end = block[start..]+ .iter()+ .position(|&b| b == b'\n')+ .map(|p| start + p)+ .unwrap_or(block.len());++ // Strip a single trailing \r if present (CRLF tolerance).+ let mut line_stop = line_end;+ if line_stop > start && block[line_stop.saturating_sub(1)] == b'\r' {+ line_stop -= 1;+ }+ let line = &block[start..line_stop];+ start = line_end.saturating_add(1);++ if line.is_empty() {+ continue;+ }+ if line[0] == b':' {+ // Comment line. Includes `: ping` keepalives and any+ // provider-specific debug comments. Drop silently.+ continue;+ }++ // Split field:value on the FIRST colon. Per SSE spec, a+ // single space following the colon is stripped from the value.+ let (field, value_with_space) = match line.iter().position(|&b| b == b':') {+ Some(p) => (&line[..p], &line[p + 1..]),+ // No colon → entire line is the field name with empty value.+ None => (line, &line[line.len()..]),+ };+ let value = if value_with_space.first() == Some(&b' ') {+ &value_with_space[1..]+ } else {+ value_with_space+ };++ match field {+ b"event" => {+ let name = std::str::from_utf8(value).map_err(FramingError::EventNameNotUtf8)?;+ event_name = Some(name.to_string());+ }+ b"data" => {+ // We slice `block` (a `Bytes`) so the resulting+ // payload shares the underlying allocation. No copy.+ let abs_start = value.as_ptr() as usize - block.as_ptr() as usize;+ let abs_end = abs_start + value.len();+ data_parts.push(block.slice(abs_start..abs_end));+ }+ // `id:` and `retry:` are valid SSE fields but neither+ // Anthropic nor OpenAI uses them on streamed responses.+ // Track-and-ignore: future providers can be added.+ _ => continue,+ }+ }++ if data_parts.is_empty() {+ return Ok(None);+ }++ // Per WHATWG SSE: multiple data: lines are joined with '\n'.+ // The vast majority of provider events have exactly one data: line.+ let data = if data_parts.len() == 1 {+ data_parts.into_iter().next().unwrap()+ } else {+ let total: usize =+ data_parts.iter().map(|b| b.len()).sum::<usize>() + (data_parts.len() - 1);+ let mut out = BytesMut::with_capacity(total);+ for (i, part) in data_parts.iter().enumerate() {+ if i > 0 {+ out.extend_from_slice(b"\n");+ }+ out.extend_from_slice(part);+ }+ out.freeze()+ };++ Ok(Some(SseEvent { event_name, data }))+}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn empty_buffer_yields_nothing() {+ let mut f = SseFramer::new();+ assert!(f.next_event().is_none());+ }++ #[test]+ fn comment_skipped_no_event_yielded() {+ let mut f = SseFramer::new();+ f.push(b": ping\n\n");+ assert!(f.next_event().is_none());+ }++ #[test]+ fn data_line_only_yields_event_with_no_event_name() {+ let mut f = SseFramer::new();+ f.push(b"data: hello\n\n");+ let ev = f.next_event().unwrap().unwrap();+ assert_eq!(ev.event_name, None);+ assert_eq!(ev.data.as_ref(), b"hello");+ }++ #[test]+ fn event_name_and_data() {+ let mut f = SseFramer::new();+ f.push(b"event: message_start\ndata: {\"x\":1}\n\n");+ let ev = f.next_event().unwrap().unwrap();+ assert_eq!(ev.event_name.as_deref(), Some("message_start"));+ assert_eq!(ev.data.as_ref(), b"{\"x\":1}");+ }++ #[test]+ fn multiple_data_lines_joined_with_newline() {+ let mut f = SseFramer::new();+ f.push(b"data: a\ndata: b\n\n");+ let ev = f.next_event().unwrap().unwrap();+ assert_eq!(ev.data.as_ref(), b"a\nb");+ }++ #[test]+ fn done_sentinel_detected() {+ let mut f = SseFramer::new();+ f.push(b"data: [DONE]\n\n");+ let ev = f.next_event().unwrap().unwrap();+ assert!(ev.is_done_sentinel());+ assert!(f.done_seen());+ }+}diff --git a/crates/headroom-proxy/src/sse/mod.rs b/crates/headroom-proxy/src/sse/mod.rsnew file mode 100644index 000000000..173b3cb3f--- /dev/null+++ b/crates/headroom-proxy/src/sse/mod.rs@@ -0,0 +1,40 @@+//! Server-Sent Events (SSE) parsing for streaming LLM responses.+//!+//! This module replaces the Python proxy's bug-prone `errors="ignore"`+//! UTF-8-decode-per-chunk SSE parsing with a byte-level framer plus+//! three provider-specific state machines.+//!+//! # Layering+//!+//! ```text+//! [TCP bytes] ─▶ SseFramer (framing.rs)+//! │ yields SseEvent { event_name, data: Bytes }+//! ▼+//! ┌─────────┴──────────┐+//! AnthropicStreamState ChunkState ResponseState+//! (anthropic.rs) (openai_chat.rs) (openai_responses.rs)+//! ```+//!+//! The framer is provider-agnostic. Each state machine consumes+//! `SseEvent`s and updates structured per-stream state used by+//! telemetry. None of these mutate the bytes flowing back to the+//! client — see `proxy.rs` for the byte-passthrough + parallel+//! state-machine wiring.+//!+//! # Bugs this retires+//!+//! - **P1-15** UTF-8 split across TCP reads (framer decodes per+//! complete event, not per chunk).+//! - **P1-8** missing `thinking_delta` arm.+//! - **P1-9** missing `signature_delta` arm.+//! - **P1-14** missing `citations_delta` arm.+//! - **P1-17** OpenAI Responses items keyed by position not id.+//! - **P4-48** OpenAI tool_call `id` overwritten by None on+//! subsequent chunks.++pub mod anthropic;+pub mod framing;+pub mod openai_chat;+pub mod openai_responses;++pub use framing::{FramingError, SseEvent, SseFramer};diff --git a/crates/headroom-proxy/src/sse/openai_chat.rs b/crates/headroom-proxy/src/sse/openai_chat.rsnew file mode 100644index 000000000..678ca89e5--- /dev/null+++ b/crates/headroom-proxy/src/sse/openai_chat.rs@@ -0,0 +1,231 @@+//! OpenAI Chat Completions streaming state machine.+//!+//! Per OpenAI's streaming spec (and §5.2 of the Headroom realignment+//! guide), a Chat Completions stream is a sequence of `data:` lines+//! with no `event:` field. Each `data:` payload is a JSON `chunk`+//! object whose shape mirrors the non-streaming response, except+//! that:+//!+//! - Each `choices[*]` carries a `delta` instead of a `message`.+//! - The first chunk for a choice carries `delta.role = "assistant"`.+//! - Subsequent chunks carry `delta.content` (string fragments to+//! concatenate) and/or `delta.tool_calls` (per-tool-call delta+//! objects keyed by `index`).+//! - For tool calls: ONLY the first chunk for a given index carries+//! `id` and `function.name`. Subsequent chunks carry just+//! `function.arguments` to concatenate. The Python proxy didn't+//! handle this and silently overwrote `arguments` when a chunk+//! omitted `id` (P4-48 telemetry).+//! - The literal `[DONE]` sentinel marks end-of-stream; no event+//! payload is parsed.+//! - When `stream_options.include_usage = true`, OpenAI emits a+//! final chunk with `choices: []` and a populated `usage` object.+//! Without that flag, no usage is emitted on the stream — the+//! client must use the non-streaming endpoint for token counts.+//! - The `refusal` field, used by GPT-4o-class safety responses,+//! carries fragments to concatenate just like `content`.++use serde_json::Value;+use std::collections::HashMap;++use super::framing::SseEvent;++/// Stream-level status mirroring the Anthropic shape.+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]+pub enum StreamStatus {+ #[default]+ Open,+ Done,+ Errored,+}++#[derive(Debug, Default, Clone)]+pub struct ChunkState {+ pub id: Option<String>,+ pub model: Option<String>,+ pub system_fingerprint: Option<String>,+ pub choices: HashMap<usize, ChoiceState>,+ pub usage: Option<Value>,+ pub status: StreamStatus,+}++#[derive(Debug, Default, Clone)]+pub struct ChoiceState {+ pub role: Option<String>,+ pub content: String,+ pub refusal: String,+ pub finish_reason: Option<String>,+ /// Tool calls, keyed by `index` from the wire (NOT vec position).+ pub tool_calls: HashMap<usize, ToolCallState>,+}++#[derive(Debug, Default, Clone)]+pub struct ToolCallState {+ pub id: Option<String>,+ pub call_type: Option<String>,+ pub function_name: Option<String>,+ /// Accumulated `function.arguments` string. Stays as a string+ /// (NOT parsed JSON) because OpenAI's tool-call argument shape+ /// is producer-defined and may legitimately not be JSON-parseable+ /// on partial-stream snapshots.+ pub function_arguments: String,+}++#[derive(Debug, thiserror::Error)]+pub enum StateError {+ #[error("event payload is not valid UTF-8: {0}")]+ PayloadNotUtf8(#[from] std::str::Utf8Error),+ #[error("event payload is not valid JSON: {0}")]+ PayloadNotJson(#[from] serde_json::Error),+}++impl ChunkState {+ pub fn new() -> Self {+ Self::default()+ }++ /// Apply one framed event. Chat Completions has no `event:` line;+ /// callers feed every framed event in here.+ pub fn apply(&mut self, event: SseEvent) -> Result<(), StateError> {+ if event.is_done_sentinel() {+ self.status = StreamStatus::Done;+ return Ok(());+ }+ // We do warn on `event:` being set because Chat Completions+ // doesn't use it — if a producer (or a reverse proxy in+ // front of us) added one, that's wire-format drift we want+ // to surface, not paper over.+ if let Some(name) = event.event_name.as_deref() {+ tracing::warn!(+ event = "sse_unknown_event",+ provider = "openai_chat",+ event_name = name,+ payload_preview = %payload_preview(&event.data),+ "openai chat event has an event: line; spec says it shouldn't"+ );+ }++ let v: Value = parse_json(&event.data)?;++ // Top-level fields: id, model, system_fingerprint, choices, usage.+ if let Some(id) = v.get("id").and_then(|x| x.as_str()) {+ // Only set on first chunk; later chunks repeat the same id.+ if self.id.is_none() {+ self.id = Some(id.to_string());+ }+ }+ if let Some(m) = v.get("model").and_then(|x| x.as_str()) {+ if self.model.is_none() {+ self.model = Some(m.to_string());+ }+ }+ if let Some(fp) = v.get("system_fingerprint").and_then(|x| x.as_str()) {+ if self.system_fingerprint.is_none() {+ self.system_fingerprint = Some(fp.to_string());+ }+ }++ if let Some(choices) = v.get("choices").and_then(|x| x.as_array()) {+ for choice in choices {+ self.apply_choice(choice);+ }+ }++ // Usage (final chunk when include_usage is set).+ if let Some(usage) = v.get("usage") {+ if !usage.is_null() {+ self.usage = Some(usage.clone());+ }+ }+ Ok(())+ }++ fn apply_choice(&mut self, choice: &Value) {+ let Some(index) = choice.get("index").and_then(|x| x.as_u64()) else {+ // Spec mandates `index`; missing → log and drop the+ // choice (don't fall back to choice[0] silently).+ tracing::warn!(+ event = "sse_unknown_event",+ provider = "openai_chat",+ event_name = "choice_missing_index",+ "choice missing index; dropping"+ );+ return;+ };+ let index = index as usize;+ let cs = self.choices.entry(index).or_default();++ if let Some(delta) = choice.get("delta") {+ if let Some(role) = delta.get("role").and_then(|x| x.as_str()) {+ // Set on first delta only; subsequent deltas omit it.+ if cs.role.is_none() {+ cs.role = Some(role.to_string());+ }+ }+ if let Some(text) = delta.get("content").and_then(|x| x.as_str()) {+ cs.content.push_str(text);+ }+ if let Some(text) = delta.get("refusal").and_then(|x| x.as_str()) {+ cs.refusal.push_str(text);+ }+ if let Some(tcs) = delta.get("tool_calls").and_then(|x| x.as_array()) {+ for tc in tcs {+ apply_tool_call_delta(cs, tc);+ }+ }+ }++ if let Some(fr) = choice.get("finish_reason").and_then(|x| x.as_str()) {+ cs.finish_reason = Some(fr.to_string());+ }+ }+}++fn apply_tool_call_delta(cs: &mut ChoiceState, tc: &Value) {+ let Some(idx) = tc.get("index").and_then(|x| x.as_u64()) else {+ tracing::warn!(+ event = "sse_unknown_event",+ provider = "openai_chat",+ event_name = "tool_call_missing_index",+ "tool_call delta missing index; dropping"+ );+ return;+ };+ let entry = cs.tool_calls.entry(idx as usize).or_default();+ // id and function.name only on first chunk for this tool call.+ if let Some(id) = tc.get("id").and_then(|x| x.as_str()) {+ if entry.id.is_none() {+ entry.id = Some(id.to_string());+ }+ }+ if let Some(t) = tc.get("type").and_then(|x| x.as_str()) {+ if entry.call_type.is_none() {+ entry.call_type = Some(t.to_string());+ }+ }+ if let Some(func) = tc.get("function") {+ if let Some(n) = func.get("name").and_then(|x| x.as_str()) {+ if entry.function_name.is_none() {+ entry.function_name = Some(n.to_string());+ }+ }+ if let Some(args) = func.get("arguments").and_then(|x| x.as_str()) {+ entry.function_arguments.push_str(args);+ }+ }+}++fn parse_json(data: &bytes::Bytes) -> Result<Value, StateError> {+ let s = std::str::from_utf8(data)?;+ Ok(serde_json::from_str(s)?)+}++fn payload_preview(data: &bytes::Bytes) -> String {+ const LIMIT: usize = 96;+ let slice = if data.len() > LIMIT {+ &data[..LIMIT]+ } else {+ &data[..]+ };+ String::from_utf8_lossy(slice).into_owned()+}diff --git a/crates/headroom-proxy/src/sse/openai_responses.rs b/crates/headroom-proxy/src/sse/openai_responses.rsnew file mode 100644index 000000000..9fc75b003--- /dev/null+++ b/crates/headroom-proxy/src/sse/openai_responses.rs@@ -0,0 +1,389 @@+//! OpenAI Responses streaming state machine.+//!+//! Per OpenAI's Responses streaming spec (and §5.3 of the Headroom+//! realignment guide), the Responses stream uses **named events**+//! (an `event:` SSE line per event), unlike Chat Completions. Each+//! event corresponds to a structured update on the response object.+//!+//! Top-level events we handle:+//!+//! response.created — initial envelope; carries `response.id`.+//! response.in_progress — periodic status; usually no state change.+//! output_item.added — a new output item appears at `item.id`.+//! output_item.done — that item is complete (final shape in+//! `item`). Items can complete in any order+//! (parallel reasoning + function_call).+//! content_part.added — a content_part entry under an item.+//! content_part.done — that content_part is complete.+//! output_text.delta — text fragment to append to a message item.+//! output_text.done — text is finished.+//! function_call_arguments.delta — fragment of a function_call's `arguments`+//! string. STAYS A STRING end-to-end.+//! function_call_arguments.done — done; `arguments` final value.+//! reasoning_summary.delta — fragment of a reasoning summary.+//! reasoning_summary.done — summary complete.+//! response.completed — final usage + status.+//! response.failed — error; status = Errored.+//! response.incomplete — incomplete (usually max_output_tokens).+//!+//! P1-17 telemetry: items keyed by position broke when OpenAI's spec+//! permitted out-of-order completion (item 1 completed before item 0).+//! This module keys EVERYTHING by `item.id` (a string like+//! `msg_abc123`), never by position. Test+//! `out_of_order_item_completion_by_id` enforces this.++use serde_json::Value;+use std::collections::HashMap;++use super::framing::SseEvent;++#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]+pub enum StreamStatus {+ #[default]+ Open,+ Completed,+ Failed,+ Incomplete,+}++#[derive(Debug, Default, Clone)]+pub struct ResponseState {+ pub response_id: Option<String>,+ pub model: Option<String>,+ /// Items keyed by their wire `id` field (NOT position). Out-of-+ /// order completion is allowed by spec.+ pub items: HashMap<String, ItemState>,+ pub usage: Option<Value>,+ pub status: StreamStatus,+}++#[derive(Debug, Default, Clone)]+pub struct ItemState {+ pub item_type: String,+ /// Concatenated `output_text` for message-type items.+ pub output_text: String,+ /// Concatenated `reasoning_summary` deltas.+ pub reasoning_summary: String,+ /// Concatenated `function_call_arguments`. Stays as a STRING —+ /// arguments may be JSON but the proxy never re-parses it.+ pub function_call_arguments: String,+ /// Initial metadata captured at output_item.added.+ pub metadata: Value,+ /// True after output_item.done for this id.+ pub complete: bool,+ /// Per-content_part state, keyed by part's `index`. We do not+ /// presently surface fields from the part beyond what the Anthropic+ /// state-machine surfaces — this keeps the structure small.+ pub content_parts: HashMap<usize, ContentPartState>,+}++#[derive(Debug, Default, Clone)]+pub struct ContentPartState {+ pub part_type: String,+ pub text: String,+ pub complete: bool,+}++#[derive(Debug, thiserror::Error)]+pub enum StateError {+ #[error("event payload is not valid UTF-8: {0}")]+ PayloadNotUtf8(#[from] std::str::Utf8Error),+ #[error("event payload is not valid JSON: {0}")]+ PayloadNotJson(#[from] serde_json::Error),+ #[error("event missing required field {field}")]+ MissingField { field: &'static str },+}++impl ResponseState {+ pub fn new() -> Self {+ Self::default()+ }++ /// Apply one framed event. The `event:` line is required (the+ /// Responses spec mandates one per event); a None name is logged+ /// and dropped.+ pub fn apply(&mut self, event: SseEvent) -> Result<(), StateError> {+ let Some(name) = event.event_name.as_deref() else {+ tracing::warn!(+ event = "sse_unknown_event",+ provider = "openai_responses",+ event_name = "<missing>",+ payload_preview = %payload_preview(&event.data),+ "openai responses event missing event: line; dropping"+ );+ return Ok(());+ };++ let v: Value = parse_json(&event.data)?;+ match name {+ "response.created" => self.on_response_created(&v),+ "response.in_progress" => Ok(()),+ "output_item.added" => self.on_output_item_added(&v),+ "output_item.done" => self.on_output_item_done(&v),+ "content_part.added" => self.on_content_part_added(&v),+ "content_part.done" => self.on_content_part_done(&v),+ "response.output_text.delta" | "output_text.delta" => self.on_output_text_delta(&v),+ "response.output_text.done" | "output_text.done" => self.on_output_text_done(&v),+ "response.function_call_arguments.delta" | "function_call_arguments.delta" => {+ self.on_function_call_arguments_delta(&v)+ }+ "response.function_call_arguments.done" | "function_call_arguments.done" => {+ self.on_function_call_arguments_done(&v)+ }+ "response.reasoning_summary.delta"+ | "response.reasoning_summary_text.delta"+ | "reasoning_summary.delta" => self.on_reasoning_summary_delta(&v),+ "response.reasoning_summary.done"+ | "response.reasoning_summary_text.done"+ | "reasoning_summary.done" => self.on_reasoning_summary_done(&v),+ "response.completed" => self.on_response_completed(&v),+ "response.failed" => {+ self.status = StreamStatus::Failed;+ Ok(())+ }+ "response.incomplete" => {+ self.status = StreamStatus::Incomplete;+ Ok(())+ }+ other => {+ tracing::warn!(+ event = "sse_unknown_event",+ provider = "openai_responses",+ event_name = other,+ payload_preview = %payload_preview(&event.data),+ "unknown openai responses event; preserving stream but not updating state"+ );+ Ok(())+ }+ }+ }++ fn on_response_created(&mut self, v: &Value) -> Result<(), StateError> {+ let resp = v+ .get("response")+ .ok_or(StateError::MissingField { field: "response" })?;+ if let Some(id) = resp.get("id").and_then(|x| x.as_str()) {+ self.response_id = Some(id.to_string());+ }+ if let Some(m) = resp.get("model").and_then(|x| x.as_str()) {+ self.model = Some(m.to_string());+ }+ Ok(())+ }++ fn on_output_item_added(&mut self, v: &Value) -> Result<(), StateError> {+ let item = v+ .get("item")+ .ok_or(StateError::MissingField { field: "item" })?;+ let id = item+ .get("id")+ .and_then(|x| x.as_str())+ .ok_or(StateError::MissingField { field: "item.id" })?+ .to_string();+ let item_type = item+ .get("type")+ .and_then(|x| x.as_str())+ .unwrap_or("")+ .to_string();+ self.items.insert(+ id,+ ItemState {+ item_type,+ metadata: item.clone(),+ ..Default::default()+ },+ );+ Ok(())+ }++ fn on_output_item_done(&mut self, v: &Value) -> Result<(), StateError> {+ let item = v+ .get("item")+ .ok_or(StateError::MissingField { field: "item" })?;+ let id = item+ .get("id")+ .and_then(|x| x.as_str())+ .ok_or(StateError::MissingField { field: "item.id" })?;+ // Out-of-order completion: the item may not have an+ // output_item.added if the producer is exotic; insert-or-update.+ let entry = self.items.entry(id.to_string()).or_default();+ entry.complete = true;+ // Refresh metadata to the final shape — the `done` payload+ // is authoritative.+ entry.metadata = item.clone();+ if entry.item_type.is_empty() {+ if let Some(t) = item.get("type").and_then(|x| x.as_str()) {+ entry.item_type = t.to_string();+ }+ }+ Ok(())+ }++ fn on_content_part_added(&mut self, v: &Value) -> Result<(), StateError> {+ let item_id = v+ .get("item_id")+ .and_then(|x| x.as_str())+ .ok_or(StateError::MissingField { field: "item_id" })?+ .to_string();+ let part_index = v+ .get("content_index")+ .or_else(|| v.get("part_index"))+ .and_then(|x| x.as_u64())+ .ok_or(StateError::MissingField {+ field: "content_index",+ })? as usize;+ let part = v+ .get("part")+ .ok_or(StateError::MissingField { field: "part" })?;+ let part_type = part+ .get("type")+ .and_then(|x| x.as_str())+ .unwrap_or("")+ .to_string();+ let item = self.items.entry(item_id).or_default();+ item.content_parts.insert(+ part_index,+ ContentPartState {+ part_type,+ ..Default::default()+ },+ );+ Ok(())+ }++ fn on_content_part_done(&mut self, v: &Value) -> Result<(), StateError> {+ let item_id = v+ .get("item_id")+ .and_then(|x| x.as_str())+ .ok_or(StateError::MissingField { field: "item_id" })?;+ let part_index = v+ .get("content_index")+ .or_else(|| v.get("part_index"))+ .and_then(|x| x.as_u64())+ .ok_or(StateError::MissingField {+ field: "content_index",+ })? as usize;+ if let Some(item) = self.items.get_mut(item_id) {+ if let Some(part) = item.content_parts.get_mut(&part_index) {+ part.complete = true;+ }+ }+ Ok(())+ }++ fn on_output_text_delta(&mut self, v: &Value) -> Result<(), StateError> {+ let item_id = v+ .get("item_id")+ .and_then(|x| x.as_str())+ .ok_or(StateError::MissingField { field: "item_id" })?+ .to_string();+ let delta = v+ .get("delta")+ .and_then(|x| x.as_str())+ .ok_or(StateError::MissingField { field: "delta" })?;+ let item = self.items.entry(item_id).or_default();+ item.output_text.push_str(delta);+ // Also append to the addressed content_part if present.+ if let Some(part_index) = v+ .get("content_index")+ .or_else(|| v.get("part_index"))+ .and_then(|x| x.as_u64())+ {+ if let Some(part) = item.content_parts.get_mut(&(part_index as usize)) {+ part.text.push_str(delta);+ }+ }+ Ok(())+ }++ fn on_output_text_done(&mut self, _v: &Value) -> Result<(), StateError> {+ // The `done` event carries the final aggregated `text`. We+ // could overwrite output_text from this, but the delta-sum+ // is already authoritative and matches the wire — we keep it+ // for robustness.+ Ok(())+ }++ fn on_function_call_arguments_delta(&mut self, v: &Value) -> Result<(), StateError> {+ let item_id = v+ .get("item_id")+ .and_then(|x| x.as_str())+ .ok_or(StateError::MissingField { field: "item_id" })?+ .to_string();+ let delta = v+ .get("delta")+ .and_then(|x| x.as_str())+ .ok_or(StateError::MissingField { field: "delta" })?;+ let item = self.items.entry(item_id).or_default();+ item.function_call_arguments.push_str(delta);+ Ok(())+ }++ fn on_function_call_arguments_done(&mut self, v: &Value) -> Result<(), StateError> {+ // The done event carries the final `arguments` string. Replace+ // our accumulator with it iff present and nonempty — guarantees+ // a producer that sends ONLY the done event (no deltas) still+ // ends up with the right value.+ let item_id = v+ .get("item_id")+ .and_then(|x| x.as_str())+ .ok_or(StateError::MissingField { field: "item_id" })?+ .to_string();+ if let Some(args) = v.get("arguments").and_then(|x| x.as_str()) {+ let item = self.items.entry(item_id).or_default();+ // Only overwrite if our delta accumulator is empty;+ // otherwise the deltas are authoritative (they may+ // include trailing content the `done` shape elides).+ if item.function_call_arguments.is_empty() {+ item.function_call_arguments.push_str(args);+ }+ }+ Ok(())+ }++ fn on_reasoning_summary_delta(&mut self, v: &Value) -> Result<(), StateError> {+ let item_id = v+ .get("item_id")+ .and_then(|x| x.as_str())+ .ok_or(StateError::MissingField { field: "item_id" })?+ .to_string();+ let delta = v+ .get("delta")+ .and_then(|x| x.as_str())+ .ok_or(StateError::MissingField { field: "delta" })?;+ let item = self.items.entry(item_id).or_default();+ item.reasoning_summary.push_str(delta);+ Ok(())+ }++ fn on_reasoning_summary_done(&mut self, _v: &Value) -> Result<(), StateError> {+ Ok(())+ }++ fn on_response_completed(&mut self, v: &Value) -> Result<(), StateError> {+ self.status = StreamStatus::Completed;+ if let Some(resp) = v.get("response") {+ if let Some(usage) = resp.get("usage") {+ if !usage.is_null() {+ self.usage = Some(usage.clone());+ }+ }+ }+ Ok(())+ }+}++fn parse_json(data: &bytes::Bytes) -> Result<Value, StateError> {+ let s = std::str::from_utf8(data)?;+ Ok(serde_json::from_str(s)?)+}++fn payload_preview(data: &bytes::Bytes) -> String {+ const LIMIT: usize = 96;+ let slice = if data.len() > LIMIT {+ &data[..LIMIT]+ } else {+ &data[..]+ };+ String::from_utf8_lossy(slice).into_owned()+}diff --git a/crates/headroom-proxy/tests/sse_anthropic.rs b/crates/headroom-proxy/tests/sse_anthropic.rsnew file mode 100644index 000000000..8fc9e71ee--- /dev/null+++ b/crates/headroom-proxy/tests/sse_anthropic.rs@@ -0,0 +1,281 @@+//! Integration tests for the Anthropic Messages SSE state machine.+//!+//! Each test feeds a curated event stream through `SseFramer ++//! AnthropicStreamState` and asserts the structured state matches what+//! the Anthropic Messages spec (and the Headroom realignment guide+//! §5.1) requires.+//!+//! These tests retire P1-8 (`thinking_delta`), P1-9 (`signature_delta`),+//! P1-14 (`citations_delta`) — wire-format quirks the Python proxy+//! mishandled in production telemetry.++use bytes::Bytes;+use headroom_proxy::sse::anthropic::{AnthropicStreamState, StreamStatus};+use headroom_proxy::sse::SseFramer;++/// Push raw bytes into a framer and drain all framed events through+/// the state machine. Test failure on any framing OR state-machine+/// error — the curated inputs in these tests are valid by construction.+fn run(state: &mut AnthropicStreamState, raw: &[u8]) {+ let mut framer = SseFramer::new();+ framer.push(raw);+ while let Some(r) = framer.next_event() {+ let ev = r.expect("framer must not fail on valid inputs");+ state+ .apply(ev)+ .expect("state machine must not fail on valid inputs");+ }+}++#[test]+fn four_event_dance_text_block() {+ let mut s = AnthropicStreamState::new();+ let raw = concat!(+ "event: message_start\n",+ "data: {\"type\":\"message_start\",\"message\":{\"id\":\"msg_1\",\"model\":\"claude-3-5-sonnet\",\"usage\":{\"input_tokens\":100,\"output_tokens\":0}}}\n\n",+ "event: content_block_start\n",+ "data: {\"type\":\"content_block_start\",\"index\":0,\"content_block\":{\"type\":\"text\",\"text\":\"\"}}\n\n",+ "event: content_block_delta\n",+ "data: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"text_delta\",\"text\":\"Hello, \"}}\n\n",+ "event: content_block_delta\n",+ "data: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"text_delta\",\"text\":\"world!\"}}\n\n",+ "event: content_block_stop\n",+ "data: {\"type\":\"content_block_stop\",\"index\":0}\n\n",+ "event: message_delta\n",+ "data: {\"type\":\"message_delta\",\"delta\":{\"stop_reason\":\"end_turn\"},\"usage\":{\"output_tokens\":42}}\n\n",+ "event: message_stop\n",+ "data: {\"type\":\"message_stop\"}\n\n",+ );+ run(&mut s, raw.as_bytes());++ assert_eq!(s.message_id.as_deref(), Some("msg_1"));+ assert_eq!(s.model.as_deref(), Some("claude-3-5-sonnet"));+ assert_eq!(s.status, StreamStatus::MessageStop);+ let block = s.blocks.get(&0).expect("block 0 must exist");+ assert_eq!(block.block_type, "text");+ assert_eq!(block.text_buffer, "Hello, world!");+ assert!(block.complete);+ assert_eq!(s.stop_reason.as_deref(), Some("end_turn"));+ assert_eq!(s.usage.input_tokens, 100);+ assert_eq!(s.usage.output_tokens, 42);+}++#[test]+fn thinking_delta_accumulated() {+ let mut s = AnthropicStreamState::new();+ let raw = concat!(+ "event: message_start\n",+ "data: {\"type\":\"message_start\",\"message\":{\"id\":\"msg_2\",\"model\":\"claude-3-5-sonnet\",\"usage\":{\"input_tokens\":50,\"output_tokens\":0}}}\n\n",+ "event: content_block_start\n",+ "data: {\"type\":\"content_block_start\",\"index\":0,\"content_block\":{\"type\":\"thinking\",\"thinking\":\"\"}}\n\n",+ "event: content_block_delta\n",+ "data: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"thinking_delta\",\"thinking\":\"Let me think...\"}}\n\n",+ "event: content_block_delta\n",+ "data: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"thinking_delta\",\"thinking\":\" about this.\"}}\n\n",+ "event: content_block_stop\n",+ "data: {\"type\":\"content_block_stop\",\"index\":0}\n\n",+ );+ run(&mut s, raw.as_bytes());++ let block = s.blocks.get(&0).expect("thinking block must exist");+ assert_eq!(block.block_type, "thinking");+ assert_eq!(block.text_buffer, "Let me think... about this.");+ assert!(block.complete);+}++#[test]+fn signature_delta_preserved_byte_equal() {+ // Cryptographic signatures must round-trip BYTE-EQUAL. We verify+ // by feeding a base64-shaped value with characters that would be+ // mangled by any naive Unicode normalization (the `+/=` triad).+ let signature = "EqQBCkYIBxgCKkBcXt9+abc==/+ABC";+ let mut s = AnthropicStreamState::new();+ let raw = format!(+ concat!(+ "event: message_start\n",+ "data: {{\"type\":\"message_start\",\"message\":{{\"id\":\"msg_3\",\"model\":\"claude-3-5-sonnet\",\"usage\":{{\"input_tokens\":10,\"output_tokens\":0}}}}}}\n\n",+ "event: content_block_start\n",+ "data: {{\"type\":\"content_block_start\",\"index\":0,\"content_block\":{{\"type\":\"redacted_thinking\"}}}}\n\n",+ "event: content_block_delta\n",+ "data: {{\"type\":\"content_block_delta\",\"index\":0,\"delta\":{{\"type\":\"signature_delta\",\"signature\":\"{}\"}}}}\n\n",+ "event: content_block_stop\n",+ "data: {{\"type\":\"content_block_stop\",\"index\":0}}\n\n",+ ),+ signature+ );+ run(&mut s, raw.as_bytes());++ let block = s.blocks.get(&0).expect("redacted block must exist");+ assert_eq!(+ block.signature.as_deref(),+ Some(signature),+ "signature must be byte-equal preserved (no normalization, no escaping)"+ );+}++#[test]+fn input_json_delta_concatenated_parsed_at_stop() {+ let mut s = AnthropicStreamState::new();+ // Tool-use block: input_json_delta fragments accumulate into a+ // partial_json string. At content_block_stop, the proxy attempts+ // to parse it (failure logs but does not panic).+ let raw = concat!(+ "event: message_start\n",+ "data: {\"type\":\"message_start\",\"message\":{\"id\":\"msg_4\",\"model\":\"claude-3-5-sonnet\",\"usage\":{\"input_tokens\":1,\"output_tokens\":0}}}\n\n",+ "event: content_block_start\n",+ "data: {\"type\":\"content_block_start\",\"index\":0,\"content_block\":{\"type\":\"tool_use\",\"id\":\"toolu_1\",\"name\":\"calc\",\"input\":{}}}\n\n",+ "event: content_block_delta\n",+ "data: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"input_json_delta\",\"partial_json\":\"{\\\"a\\\":\"}}\n\n",+ "event: content_block_delta\n",+ "data: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"input_json_delta\",\"partial_json\":\"42}\"}}\n\n",+ "event: content_block_stop\n",+ "data: {\"type\":\"content_block_stop\",\"index\":0}\n\n",+ );+ run(&mut s, raw.as_bytes());++ let block = s.blocks.get(&0).expect("tool_use block must exist");+ assert_eq!(block.block_type, "tool_use");+ assert_eq!(block.partial_json, r#"{"a":42}"#);+ // The accumulated string must parse as JSON now that all+ // fragments are concatenated. (The state machine doesn't store+ // the parsed value; we verify here.)+ let parsed: serde_json::Value =+ serde_json::from_str(&block.partial_json).expect("concatenated partial_json must parse");+ assert_eq!(parsed["a"], 42);+ assert!(block.complete);+}++#[test]+fn citations_delta_accumulated() {+ let mut s = AnthropicStreamState::new();+ let raw = concat!(+ "event: message_start\n",+ "data: {\"type\":\"message_start\",\"message\":{\"id\":\"msg_5\",\"model\":\"claude-3-5-sonnet\",\"usage\":{\"input_tokens\":1,\"output_tokens\":0}}}\n\n",+ "event: content_block_start\n",+ "data: {\"type\":\"content_block_start\",\"index\":0,\"content_block\":{\"type\":\"text\",\"text\":\"\"}}\n\n",+ "event: content_block_delta\n",+ "data: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"citations_delta\",\"citation\":{\"type\":\"page_location\",\"start_page\":1,\"end_page\":2}}}\n\n",+ "event: content_block_delta\n",+ "data: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"citations_delta\",\"citation\":{\"type\":\"page_location\",\"start_page\":3,\"end_page\":4}}}\n\n",+ "event: content_block_stop\n",+ "data: {\"type\":\"content_block_stop\",\"index\":0}\n\n",+ );+ run(&mut s, raw.as_bytes());++ let block = s.blocks.get(&0).expect("text block must exist");+ assert_eq!(block.citations.len(), 2);+ assert_eq!(block.citations[0]["start_page"], 1);+ assert_eq!(block.citations[1]["start_page"], 3);+}++#[test]+fn message_delta_finalizes_stop_reason_and_output_tokens() {+ let mut s = AnthropicStreamState::new();+ let raw = concat!(+ "event: message_start\n",+ "data: {\"type\":\"message_start\",\"message\":{\"id\":\"msg_6\",\"model\":\"claude-3-5-sonnet\",\"usage\":{\"input_tokens\":7,\"output_tokens\":0,\"cache_creation_input_tokens\":3,\"cache_read_input_tokens\":2}}}\n\n",+ "event: message_delta\n",+ "data: {\"type\":\"message_delta\",\"delta\":{\"stop_reason\":\"max_tokens\"},\"usage\":{\"output_tokens\":1024}}\n\n",+ "event: message_stop\n",+ "data: {\"type\":\"message_stop\"}\n\n",+ );+ run(&mut s, raw.as_bytes());++ assert_eq!(s.stop_reason.as_deref(), Some("max_tokens"));+ assert_eq!(s.usage.input_tokens, 7);+ assert_eq!(s.usage.output_tokens, 1024);+ assert_eq!(s.usage.cache_creation_input_tokens, 3);+ assert_eq!(s.usage.cache_read_input_tokens, 2);+ assert_eq!(s.status, StreamStatus::MessageStop);+}++#[test]+fn mid_stream_error_event_handled() {+ let mut s = AnthropicStreamState::new();+ let raw = concat!(+ "event: message_start\n",+ "data: {\"type\":\"message_start\",\"message\":{\"id\":\"msg_7\",\"model\":\"claude-3-5-sonnet\",\"usage\":{\"input_tokens\":1,\"output_tokens\":0}}}\n\n",+ "event: error\n",+ "data: {\"type\":\"error\",\"error\":{\"type\":\"overloaded_error\",\"message\":\"Overloaded\"}}\n\n",+ );+ run(&mut s, raw.as_bytes());++ assert_eq!(+ s.status,+ StreamStatus::Errored,+ "error event must transition status to Errored"+ );+ assert_eq!(s.message_id.as_deref(), Some("msg_7"));+}++#[test]+fn interleaved_blocks_by_index() {+ // The spec permits blocks to interleave deltas (block 0 delta,+ // then block 1 delta, then block 0 delta, etc). Each block's+ // text_buffer must be independent — keyed by `index`, not by+ // arrival order.+ let mut s = AnthropicStreamState::new();+ let raw = concat!(+ "event: message_start\n",+ "data: {\"type\":\"message_start\",\"message\":{\"id\":\"msg_8\",\"model\":\"claude-3-5-sonnet\",\"usage\":{\"input_tokens\":1,\"output_tokens\":0}}}\n\n",+ "event: content_block_start\n",+ "data: {\"type\":\"content_block_start\",\"index\":0,\"content_block\":{\"type\":\"text\",\"text\":\"\"}}\n\n",+ "event: content_block_start\n",+ "data: {\"type\":\"content_block_start\",\"index\":1,\"content_block\":{\"type\":\"text\",\"text\":\"\"}}\n\n",+ "event: content_block_delta\n",+ "data: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"text_delta\",\"text\":\"A0 \"}}\n\n",+ "event: content_block_delta\n",+ "data: {\"type\":\"content_block_delta\",\"index\":1,\"delta\":{\"type\":\"text_delta\",\"text\":\"B0 \"}}\n\n",+ "event: content_block_delta\n",+ "data: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"text_delta\",\"text\":\"A1\"}}\n\n",+ "event: content_block_delta\n",+ "data: {\"type\":\"content_block_delta\",\"index\":1,\"delta\":{\"type\":\"text_delta\",\"text\":\"B1\"}}\n\n",+ "event: content_block_stop\n",+ "data: {\"type\":\"content_block_stop\",\"index\":0}\n\n",+ "event: content_block_stop\n",+ "data: {\"type\":\"content_block_stop\",\"index\":1}\n\n",+ );+ run(&mut s, raw.as_bytes());++ assert_eq!(s.blocks.get(&0).unwrap().text_buffer, "A0 A1");+ assert_eq!(s.blocks.get(&1).unwrap().text_buffer, "B0 B1");+ assert!(s.blocks.get(&0).unwrap().complete);+ assert!(s.blocks.get(&1).unwrap().complete);+}++#[test]+fn split_chunks_preserve_event_boundaries() {+ // Feed the events one byte at a time. The state machine must+ // produce identical structured output regardless of how the bytes+ // arrive — this is the cache-safety invariant under degenerate TCP.+ let raw = concat!(+ "event: message_start\n",+ "data: {\"type\":\"message_start\",\"message\":{\"id\":\"msg_9\",\"model\":\"claude-3-5-sonnet\",\"usage\":{\"input_tokens\":1,\"output_tokens\":0}}}\n\n",+ "event: content_block_start\n",+ "data: {\"type\":\"content_block_start\",\"index\":0,\"content_block\":{\"type\":\"text\",\"text\":\"\"}}\n\n",+ "event: content_block_delta\n",+ "data: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"text_delta\",\"text\":\"hi\"}}\n\n",+ "event: content_block_stop\n",+ "data: {\"type\":\"content_block_stop\",\"index\":0}\n\n",+ )+ .as_bytes();++ let mut framer = SseFramer::new();+ let mut s = AnthropicStreamState::new();+ for byte in raw {+ framer.push(std::slice::from_ref(byte));+ while let Some(r) = framer.next_event() {+ s.apply(r.unwrap()).unwrap();+ }+ }+ assert_eq!(s.blocks.get(&0).unwrap().text_buffer, "hi");+}++/// Reference SseEvent used to verify Bytes payload typing in this file.+#[allow(dead_code)]+fn _ref_event() -> headroom_proxy::sse::SseEvent {+ headroom_proxy::sse::SseEvent {+ event_name: None,+ data: Bytes::from_static(b""),+ }+}diff --git a/crates/headroom-proxy/tests/sse_framing.rs b/crates/headroom-proxy/tests/sse_framing.rsnew file mode 100644index 000000000..e04208859--- /dev/null+++ b/crates/headroom-proxy/tests/sse_framing.rs@@ -0,0 +1,217 @@+//! Integration tests for the byte-level SSE framer.+//!+//! These tests pin down the wire-format invariants the framer must+//! preserve regardless of how the underlying TCP stream chunks the+//! bytes:+//!+//! - Multi-byte UTF-8 codepoints split across chunks must rejoin+//! intact (P1-15: the Python proxy lost bytes here).+//! - A single `\n` is NOT an event terminator; only `\n\n` is.+//! - `: ping` keepalive comments yield no event (silently skipped).+//! - `data: [DONE]` is detected via the `is_done_sentinel()` API.+//! - Trailing bytes after `[DONE]` (some providers send `\n\n` or+//! additional pings) are tolerated without error.++use bytes::Bytes;+use headroom_proxy::sse::{SseEvent, SseFramer};++/// A 4-byte UTF-8 emoji (U+1F600 GRINNING FACE) is a deterministic+/// torture-test for split-codepoint chunking. Bytes: F0 9F 98 80.+const EMOJI: &[u8] = "\u{1F600}".as_bytes();++#[test]+fn utf8_split_emoji_across_chunks_preserved() {+ // Build the event "data: <emoji>\n\n" then split it at the+ // BYTE BOUNDARY in the middle of the emoji's 4-byte sequence.+ // Concretely we split between the second and third byte of the+ // codepoint, the worst case for naive per-chunk decoders.+ let mut full = Vec::from(b"data: ".as_slice());+ full.extend_from_slice(EMOJI);+ full.extend_from_slice(b"\n\n");++ // Find the emoji's first byte index (always 6 — `data: ` is six+ // ASCII bytes — but compute it so a future doc-edit can't drift).+ let emoji_start = 6usize;+ let split_at = emoji_start + 2; // mid-codepoint split.+ assert!(split_at < full.len() - 2);++ let mut framer = SseFramer::new();+ framer.push(&full[..split_at]);+ // No complete event yet (no \n\n in the first chunk).+ assert!(framer.next_event().is_none());+ framer.push(&full[split_at..]);++ let ev = framer.next_event().expect("event must surface").unwrap();+ assert_eq!(ev.event_name, None);+ // The bytes in `data` must equal the original emoji bytes EXACTLY.+ assert_eq!(ev.data.as_ref(), EMOJI, "no bytes lost across split");+ // And the UTF-8 decode must round-trip.+ assert_eq!(ev.data_str().unwrap(), "\u{1F600}");+ // No more events; buffer empty.+ assert!(framer.next_event().is_none());+ assert_eq!(framer.buffered_len(), 0);+}++#[test]+fn single_newline_does_not_emit_event() {+ let mut framer = SseFramer::new();+ framer.push(b"data: hello\n");+ // Only one newline — event not yet terminated. The framer must+ // hold the bytes pending the second newline.+ assert!(framer.next_event().is_none());+ // The full payload is still buffered (no bytes silently consumed).+ assert!(framer.buffered_len() > 0);+}++#[test]+fn double_newline_emits_event() {+ let mut framer = SseFramer::new();+ framer.push(b"data: hello\n\n");+ let ev = framer.next_event().expect("event must surface").unwrap();+ assert_eq!(ev.event_name, None);+ assert_eq!(ev.data.as_ref(), b"hello");+ // Buffer fully drained.+ assert_eq!(framer.buffered_len(), 0);+}++#[test]+fn ping_keepalive_skipped() {+ let mut framer = SseFramer::new();+ // Both forms of keepalive a real provider might send:+ // `: ping\n\n` — SSE-spec comment line.+ // `event: ping\ndata: {}\n\n` — Anthropic's explicit ping event+ // (handled at the state-machine layer, not the framer).+ framer.push(b": ping\n\n");+ // Comment-only block: framer skips silently.+ assert!(framer.next_event().is_none());++ // After a real event arrives, the framer surfaces it.+ framer.push(b"data: real\n\n");+ let ev = framer.next_event().expect("event must surface").unwrap();+ assert_eq!(ev.data.as_ref(), b"real");+}++#[test]+fn done_sentinel_detected() {+ let mut framer = SseFramer::new();+ framer.push(b"data: [DONE]\n\n");+ let ev = framer.next_event().expect("event must surface").unwrap();+ assert!(ev.is_done_sentinel(), "[DONE] must be detected via the API");+ assert!(framer.done_seen(), "framer flag must record the sentinel");+}++#[test]+fn trailing_data_after_done_tolerated() {+ let mut framer = SseFramer::new();+ framer.push(b"data: [DONE]\n\n");+ let ev = framer.next_event().unwrap().unwrap();+ assert!(ev.is_done_sentinel());+ // Some providers append a final empty event or comment after+ // [DONE]. None of these may cause the framer to error.+ framer.push(b": closing\n\n");+ framer.push(b"\n\n"); // empty event+ framer.push(b"data: trailing\n\n");+ // The empty / comment events yield None; the data event surfaces.+ let next = framer.next_event().expect("trailing data event").unwrap();+ assert_eq!(next.data.as_ref(), b"trailing");+ // done_seen remains true even after subsequent events.+ assert!(framer.done_seen());+}++#[test]+fn multiple_events_one_chunk() {+ // A single TCP read may deliver several complete SSE events.+ let mut framer = SseFramer::new();+ framer.push(b"event: a\ndata: 1\n\nevent: b\ndata: 2\n\n");+ let e1 = framer.next_event().unwrap().unwrap();+ assert_eq!(e1.event_name.as_deref(), Some("a"));+ assert_eq!(e1.data.as_ref(), b"1");+ let e2 = framer.next_event().unwrap().unwrap();+ assert_eq!(e2.event_name.as_deref(), Some("b"));+ assert_eq!(e2.data.as_ref(), b"2");+ assert!(framer.next_event().is_none());+}++#[test]+fn chunk_boundary_inside_event_name() {+ // Chunk boundary in the middle of `event: messa|ge_start`.+ let mut framer = SseFramer::new();+ framer.push(b"event: messa");+ assert!(framer.next_event().is_none());+ framer.push(b"ge_start\ndata: x\n\n");+ let ev = framer.next_event().unwrap().unwrap();+ assert_eq!(ev.event_name.as_deref(), Some("message_start"));+ assert_eq!(ev.data.as_ref(), b"x");+}++// ───────────────────────────── property test ─────────────────────────+//+// The framer must NEVER panic on arbitrary byte input. TCP can hand us+// anything — partial codepoints, NUL bytes, fuzz noise. 100K random+// inputs is the project default for "no panic" parser invariants per+// `feedback_realignment_build_constraints.md`. The test does not assert+// what the framer yields, only that pushing arbitrary bytes and pulling+// events terminates without panic.++use proptest::prelude::*;++proptest! {+ #![proptest_config(ProptestConfig {+ cases: 100_000,+ // Disable shrinking timeout — 100K trivial cases run fast on+ // CI and we want the fuzzer to actually shrink any panic it+ // finds (vs. give up early).+ max_shrink_iters: 1024,+ ..ProptestConfig::default()+ })]+ #[test]+ fn sse_parser_no_panic_on_arbitrary_bytes(+ bytes in proptest::collection::vec(any::<u8>(), 0..2048),+ ) {+ let mut framer = SseFramer::new();+ framer.push(&bytes);+ // Drain until next_event returns None or yields an Err. Either+ // outcome is acceptable; what's NOT acceptable is a panic.+ loop {+ match framer.next_event() {+ None => break,+ Some(Ok(_)) => continue,+ Some(Err(_)) => continue,+ }+ }+ // Sanity: take_remaining never panics either.+ let rest: Bytes = framer.take_remaining();+ // Touch the bytes so the optimizer doesn't elide the call.+ prop_assert!(rest.len() <= bytes.len() + 1);+ }++ /// Same as above but feeds the bytes one byte at a time, simulating+ /// a degenerate slow TCP. The framer's chunk-independence invariant+ /// requires this to behave identically (no panic).+ #[test]+ fn sse_parser_no_panic_one_byte_at_a_time(+ bytes in proptest::collection::vec(any::<u8>(), 0..512),+ ) {+ let mut framer = SseFramer::new();+ for b in &bytes {+ framer.push(std::slice::from_ref(b));+ while let Some(r) = framer.next_event() {+ let _ = r; // tolerate Ok or Err.+ }+ }+ let _ = framer.take_remaining();+ }+}++/// Sanity: `SseEvent` derives the trait we documented (Clone/Eq).+/// This catches accidental future regressions where someone removes+/// a derive that internal callers depend on.+#[test]+fn sse_event_traits_present() {+ let e = SseEvent {+ event_name: Some("x".into()),+ data: Bytes::from_static(b"y"),+ };+ let cloned = e.clone();+ assert_eq!(e, cloned);+}diff --git a/crates/headroom-proxy/tests/sse_openai_chat.rs b/crates/headroom-proxy/tests/sse_openai_chat.rsnew file mode 100644index 000000000..6494c3c4b--- /dev/null+++ b/crates/headroom-proxy/tests/sse_openai_chat.rs@@ -0,0 +1,144 @@+//! Integration tests for the OpenAI Chat Completions SSE state machine.+//!+//! Wire-format quirks under test (per realignment guide §5.2):+//!+//! - Tool calls: `id` and `function.name` arrive ONLY on the first+//! chunk per `index`. Subsequent chunks omit them; the proxy must+//! NOT overwrite the cached values with `None` (P4-48).+//! - `function.arguments` is concatenated as a STRING — never+//! re-parsed as JSON mid-stream.+//! - When `stream_options.include_usage = true`, the FINAL chunk+//! carries `choices: []` and a populated `usage` object. Without+//! that flag, `usage` is never sent over the stream.+//! - The `refusal` field (GPT-4o safety-class responses) carries+//! fragments to concatenate just like `content`.++use headroom_proxy::sse::openai_chat::{ChunkState, StreamStatus};+use headroom_proxy::sse::SseFramer;++fn run(state: &mut ChunkState, raw: &[u8]) {+ let mut framer = SseFramer::new();+ framer.push(raw);+ while let Some(r) = framer.next_event() {+ let ev = r.expect("framer must not fail on valid inputs");+ state+ .apply(ev)+ .expect("state machine must not fail on valid inputs");+ }+}++#[test]+fn tool_call_id_and_name_only_first_chunk() {+ let mut s = ChunkState::new();+ let raw = concat!(+ // First chunk: id + function.name + first arguments fragment.+ "data: {\"id\":\"chatcmpl-1\",\"model\":\"gpt-4o\",\"choices\":[{\"index\":0,\"delta\":{\"role\":\"assistant\",\"tool_calls\":[{\"index\":0,\"id\":\"call_abc\",\"type\":\"function\",\"function\":{\"name\":\"get_weather\",\"arguments\":\"{\\\"loc\\\":\"}}]}}]}\n\n",+ // Second chunk: NO id, NO function.name; just more arguments.+ // The Python proxy used to overwrite id with null here.+ "data: {\"id\":\"chatcmpl-1\",\"model\":\"gpt-4o\",\"choices\":[{\"index\":0,\"delta\":{\"tool_calls\":[{\"index\":0,\"function\":{\"arguments\":\"\\\"NYC\\\"}\"}}]}}]}\n\n",+ "data: [DONE]\n\n",+ );+ run(&mut s, raw.as_bytes());++ let choice = s.choices.get(&0).expect("choice 0 must exist");+ let tc = choice.tool_calls.get(&0).expect("tool call 0 must exist");+ assert_eq!(+ tc.id.as_deref(),+ Some("call_abc"),+ "id must NOT be overwritten by the second chunk's missing id (P4-48)"+ );+ assert_eq!(tc.function_name.as_deref(), Some("get_weather"));+ assert_eq!(tc.call_type.as_deref(), Some("function"));+ assert_eq!(s.status, StreamStatus::Done);+}++#[test]+fn tool_call_arguments_concatenated() {+ let mut s = ChunkState::new();+ let raw = concat!(+ "data: {\"id\":\"chatcmpl-2\",\"model\":\"gpt-4o\",\"choices\":[{\"index\":0,\"delta\":{\"tool_calls\":[{\"index\":0,\"id\":\"call_1\",\"type\":\"function\",\"function\":{\"name\":\"f\",\"arguments\":\"{\\\"a\\\":\"}}]}}]}\n\n",+ "data: {\"id\":\"chatcmpl-2\",\"choices\":[{\"index\":0,\"delta\":{\"tool_calls\":[{\"index\":0,\"function\":{\"arguments\":\"1,\"}}]}}]}\n\n",+ "data: {\"id\":\"chatcmpl-2\",\"choices\":[{\"index\":0,\"delta\":{\"tool_calls\":[{\"index\":0,\"function\":{\"arguments\":\"\\\"b\\\":2}\"}}]}}]}\n\n",+ "data: [DONE]\n\n",+ );+ run(&mut s, raw.as_bytes());++ let choice = s.choices.get(&0).unwrap();+ let tc = choice.tool_calls.get(&0).unwrap();+ assert_eq!(tc.function_arguments, r#"{"a":1,"b":2}"#);+ // The string MUST parse as JSON now that it's concatenated, but+ // the state machine itself doesn't parse mid-stream — that's the+ // contract we lock down here.+ let parsed: serde_json::Value =+ serde_json::from_str(&tc.function_arguments).expect("concatenated arguments must parse");+ assert_eq!(parsed["a"], 1);+ assert_eq!(parsed["b"], 2);+}++#[test]+fn usage_in_final_chunk_when_include_usage_set() {+ let mut s = ChunkState::new();+ let raw = concat!(+ // Body chunks with content fragments.+ "data: {\"id\":\"chatcmpl-3\",\"model\":\"gpt-4o\",\"choices\":[{\"index\":0,\"delta\":{\"role\":\"assistant\",\"content\":\"hi\"}}]}\n\n",+ "data: {\"id\":\"chatcmpl-3\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\" there\"},\"finish_reason\":\"stop\"}]}\n\n",+ // Final usage-only chunk: choices is empty, usage is populated.+ "data: {\"id\":\"chatcmpl-3\",\"choices\":[],\"usage\":{\"prompt_tokens\":12,\"completion_tokens\":7,\"total_tokens\":19}}\n\n",+ "data: [DONE]\n\n",+ );+ run(&mut s, raw.as_bytes());++ let choice = s.choices.get(&0).unwrap();+ assert_eq!(choice.role.as_deref(), Some("assistant"));+ assert_eq!(choice.content, "hi there");+ assert_eq!(choice.finish_reason.as_deref(), Some("stop"));++ let usage = s.usage.as_ref().expect("usage must be set on final chunk");+ assert_eq!(usage["prompt_tokens"], 12);+ assert_eq!(usage["completion_tokens"], 7);+ assert_eq!(usage["total_tokens"], 19);+}++#[test]+fn refusal_field_handled() {+ // GPT-4o-class safety responses substitute `refusal` for `content`.+ // Both fields concatenate identically.+ let mut s = ChunkState::new();+ let raw = concat!(+ "data: {\"id\":\"chatcmpl-4\",\"model\":\"gpt-4o\",\"choices\":[{\"index\":0,\"delta\":{\"role\":\"assistant\",\"refusal\":\"I can't \"}}]}\n\n",+ "data: {\"id\":\"chatcmpl-4\",\"choices\":[{\"index\":0,\"delta\":{\"refusal\":\"help with that.\"},\"finish_reason\":\"stop\"}]}\n\n",+ "data: [DONE]\n\n",+ );+ run(&mut s, raw.as_bytes());++ let choice = s.choices.get(&0).unwrap();+ assert_eq!(choice.refusal, "I can't help with that.");+ // Content stayed empty — refusal and content are mutually exclusive+ // in the wire format but both must be supported.+ assert_eq!(choice.content, "");+ assert_eq!(choice.finish_reason.as_deref(), Some("stop"));+}++#[test]+fn done_sentinel_terminates_stream_status() {+ let mut s = ChunkState::new();+ let raw = b"data: [DONE]\n\n";+ run(&mut s, raw);+ assert_eq!(s.status, StreamStatus::Done);+}++#[test]+fn multiple_choices_keyed_by_index() {+ // OpenAI's `n>1` mode emits multiple choices per chunk. Each must+ // be kept independent, keyed by `choice.index`.+ let mut s = ChunkState::new();+ let raw = concat!(+ "data: {\"id\":\"chatcmpl-5\",\"model\":\"gpt-4o\",\"choices\":[{\"index\":0,\"delta\":{\"role\":\"assistant\",\"content\":\"A\"}},{\"index\":1,\"delta\":{\"role\":\"assistant\",\"content\":\"B\"}}]}\n\n",+ "data: {\"id\":\"chatcmpl-5\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"A2\"}},{\"index\":1,\"delta\":{\"content\":\"B2\"}}]}\n\n",+ "data: [DONE]\n\n",+ );+ run(&mut s, raw.as_bytes());++ assert_eq!(s.choices.get(&0).unwrap().content, "AA2");+ assert_eq!(s.choices.get(&1).unwrap().content, "BB2");+}diff --git a/crates/headroom-proxy/tests/sse_openai_responses.rs b/crates/headroom-proxy/tests/sse_openai_responses.rsnew file mode 100644index 000000000..5b24f8d44--- /dev/null+++ b/crates/headroom-proxy/tests/sse_openai_responses.rs@@ -0,0 +1,163 @@+//! Integration tests for the OpenAI Responses SSE state machine.+//!+//! Wire-format quirks under test (per realignment guide §5.3):+//!+//! - Items are keyed by `item.id`, NOT by position. The spec permits+//! out-of-order completion: item B can complete before item A even+//! when both are open. (P1-17 in production telemetry.)+//! - `function_call_arguments.delta` fragments concatenate as a+//! STRING; the proxy never parses them as JSON.+//! - `reasoning_summary.delta` fragments accumulate per item.++use headroom_proxy::sse::openai_responses::{ResponseState, StreamStatus};+use headroom_proxy::sse::SseFramer;++fn run(state: &mut ResponseState, raw: &[u8]) {+ let mut framer = SseFramer::new();+ framer.push(raw);+ while let Some(r) = framer.next_event() {+ let ev = r.expect("framer must not fail on valid inputs");+ state+ .apply(ev)+ .expect("state machine must not fail on valid inputs");+ }+}++#[test]+fn out_of_order_item_completion_by_id() {+ // Two items open: msg_A and msg_B. msg_B completes BEFORE msg_A.+ // The state machine must record completion against the right+ // item by id, not by arrival order.+ let mut s = ResponseState::new();+ let raw = concat!(+ "event: response.created\n",+ "data: {\"type\":\"response.created\",\"response\":{\"id\":\"resp_1\",\"model\":\"gpt-5\"}}\n\n",+ "event: output_item.added\n",+ "data: {\"type\":\"output_item.added\",\"item\":{\"id\":\"msg_A\",\"type\":\"message\"}}\n\n",+ "event: output_item.added\n",+ "data: {\"type\":\"output_item.added\",\"item\":{\"id\":\"msg_B\",\"type\":\"message\"}}\n\n",+ // Out-of-order: B finishes first.+ "event: output_item.done\n",+ "data: {\"type\":\"output_item.done\",\"item\":{\"id\":\"msg_B\",\"type\":\"message\",\"status\":\"completed\"}}\n\n",+ "event: output_item.done\n",+ "data: {\"type\":\"output_item.done\",\"item\":{\"id\":\"msg_A\",\"type\":\"message\",\"status\":\"completed\"}}\n\n",+ "event: response.completed\n",+ "data: {\"type\":\"response.completed\",\"response\":{\"id\":\"resp_1\",\"usage\":{\"input_tokens\":10,\"output_tokens\":20}}}\n\n",+ );+ run(&mut s, raw.as_bytes());++ assert_eq!(s.response_id.as_deref(), Some("resp_1"));+ assert_eq!(s.status, StreamStatus::Completed);+ assert!(s.items.get("msg_A").unwrap().complete);+ assert!(s.items.get("msg_B").unwrap().complete);+ assert!(s.usage.is_some());+}++#[test]+fn reasoning_summary_accumulated() {+ let mut s = ResponseState::new();+ let raw = concat!(+ "event: response.created\n",+ "data: {\"type\":\"response.created\",\"response\":{\"id\":\"resp_2\",\"model\":\"gpt-5\"}}\n\n",+ "event: output_item.added\n",+ "data: {\"type\":\"output_item.added\",\"item\":{\"id\":\"rs_1\",\"type\":\"reasoning\"}}\n\n",+ "event: response.reasoning_summary_text.delta\n",+ "data: {\"type\":\"response.reasoning_summary_text.delta\",\"item_id\":\"rs_1\",\"delta\":\"First, \"}\n\n",+ "event: response.reasoning_summary_text.delta\n",+ "data: {\"type\":\"response.reasoning_summary_text.delta\",\"item_id\":\"rs_1\",\"delta\":\"second.\"}\n\n",+ "event: response.reasoning_summary_text.done\n",+ "data: {\"type\":\"response.reasoning_summary_text.done\",\"item_id\":\"rs_1\"}\n\n",+ "event: output_item.done\n",+ "data: {\"type\":\"output_item.done\",\"item\":{\"id\":\"rs_1\",\"type\":\"reasoning\"}}\n\n",+ );+ run(&mut s, raw.as_bytes());++ let item = s.items.get("rs_1").expect("reasoning item must exist");+ assert_eq!(item.reasoning_summary, "First, second.");+ assert!(item.complete);+}++#[test]+fn function_call_arguments_string_preserved() {+ // function_call_arguments must STAY A STRING end-to-end. Even+ // though the wire payload happens to be valid JSON in this test,+ // the state machine must not parse it; we verify by feeding a+ // payload with content that would round-trip differently if parsed+ // (whitespace inside the JSON, key ordering).+ let mut s = ResponseState::new();+ let arg_part_1 = "{ \"loc\" : \"NYC\""; // intentional whitespace+ let arg_part_2 = " , \"days\" : 7 }"; // intentional whitespace + key order+ let raw = format!(+ concat!(+ "event: response.created\n",+ "data: {{\"type\":\"response.created\",\"response\":{{\"id\":\"resp_3\",\"model\":\"gpt-5\"}}}}\n\n",+ "event: output_item.added\n",+ "data: {{\"type\":\"output_item.added\",\"item\":{{\"id\":\"fc_1\",\"type\":\"function_call\",\"name\":\"weather\"}}}}\n\n",+ "event: response.function_call_arguments.delta\n",+ "data: {{\"type\":\"response.function_call_arguments.delta\",\"item_id\":\"fc_1\",\"delta\":{a1}}}\n\n",+ "event: response.function_call_arguments.delta\n",+ "data: {{\"type\":\"response.function_call_arguments.delta\",\"item_id\":\"fc_1\",\"delta\":{a2}}}\n\n",+ "event: response.function_call_arguments.done\n",+ "data: {{\"type\":\"response.function_call_arguments.done\",\"item_id\":\"fc_1\",\"arguments\":\"FINAL\"}}\n\n",+ ),+ a1 = serde_json::to_string(arg_part_1).unwrap(),+ a2 = serde_json::to_string(arg_part_2).unwrap(),+ );+ run(&mut s, raw.as_bytes());++ let item = s.items.get("fc_1").unwrap();+ let expected = format!("{}{}", arg_part_1, arg_part_2);+ assert_eq!(+ item.function_call_arguments, expected,+ "arguments must be byte-equal concatenation (NOT re-serialized JSON)"+ );+ // Whitespace inside the wire string must be preserved verbatim.+ assert!(item.function_call_arguments.contains(" \"loc\" "));+ assert!(item.function_call_arguments.contains(" , "));+}++#[test]+fn output_text_delta_accumulated_per_item() {+ let mut s = ResponseState::new();+ let raw = concat!(+ "event: response.created\n",+ "data: {\"type\":\"response.created\",\"response\":{\"id\":\"resp_4\",\"model\":\"gpt-5\"}}\n\n",+ "event: output_item.added\n",+ "data: {\"type\":\"output_item.added\",\"item\":{\"id\":\"msg_X\",\"type\":\"message\"}}\n\n",+ "event: response.output_text.delta\n",+ "data: {\"type\":\"response.output_text.delta\",\"item_id\":\"msg_X\",\"delta\":\"Hello \"}\n\n",+ "event: response.output_text.delta\n",+ "data: {\"type\":\"response.output_text.delta\",\"item_id\":\"msg_X\",\"delta\":\"world\"}\n\n",+ "event: response.output_text.done\n",+ "data: {\"type\":\"response.output_text.done\",\"item_id\":\"msg_X\",\"text\":\"Hello world\"}\n\n",+ );+ run(&mut s, raw.as_bytes());+ let item = s.items.get("msg_X").unwrap();+ assert_eq!(item.output_text, "Hello world");+}++#[test]+fn response_failed_status() {+ let mut s = ResponseState::new();+ let raw = concat!(+ "event: response.created\n",+ "data: {\"type\":\"response.created\",\"response\":{\"id\":\"resp_5\",\"model\":\"gpt-5\"}}\n\n",+ "event: response.failed\n",+ "data: {\"type\":\"response.failed\",\"response\":{\"id\":\"resp_5\",\"status\":\"failed\",\"error\":{\"code\":\"server_error\"}}}\n\n",+ );+ run(&mut s, raw.as_bytes());+ assert_eq!(s.status, StreamStatus::Failed);+}++#[test]+fn response_incomplete_status() {+ let mut s = ResponseState::new();+ let raw = concat!(+ "event: response.created\n",+ "data: {\"type\":\"response.created\",\"response\":{\"id\":\"resp_6\",\"model\":\"gpt-5\"}}\n\n",+ "event: response.incomplete\n",+ "data: {\"type\":\"response.incomplete\",\"response\":{\"id\":\"resp_6\",\"status\":\"incomplete\",\"incomplete_details\":{\"reason\":\"max_output_tokens\"}}}\n\n",+ );+ run(&mut s, raw.as_bytes());+ assert_eq!(s.status, StreamStatus::Incomplete);+}