Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

fix: C1 — byte-level SSE parser + state machines

chopratejasddc6f6ceb035
diff --git a/Cargo.lock b/Cargo.lock
index 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.toml
index 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.rs
index 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.rs
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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);
+}