fix(usage): handle terminal stream failures and preserve usage updates

crates/aether-ai-formats/src/formats/openai/chat/stream.rs

@@ -1180,6 +1180,23 @@ impl OpenAIResponsesProviderState {
                     }
                 }
             }
+            event_type if openai_stream_payload_is_terminal_error(&value) => {
+                self.finished = true;
+                let mut payload = value.clone();
+                if event_type != "response.failed"
+                    && event_type != "response.incomplete"
+                    && event_type != "error"
+                {
+                    payload = openai_stream_terminal_error_body(&value).unwrap_or(payload);
+                    if let Some(object) = payload.as_object_mut() {
+                        object.insert(
+                            "type".to_string(),
+                            Value::String("response.failed".to_string()),
+                        );
+                    }
+                }
+                out.push(self.unknown_frame(report_context, payload));
+            }
             "response.completed" => {
                 let Some(response) = value.get("response").and_then(Value::as_object) else {
                     return Ok(out);
@@ -1559,6 +1576,13 @@ impl OpenAIChatClientEmitter {
                 )?);
                 Ok(out)
             }
+            CanonicalStreamEvent::UnknownEvent(payload)
+                if openai_stream_terminal_error_body(&payload).is_some() =>
+            {
+                self.finished = true;
+                let error_body = openai_stream_terminal_error_body(&payload).unwrap_or(payload);
+                encode_json_sse(None, &error_body)
+            }
             CanonicalStreamEvent::UnknownEvent(_) => Ok(Vec::new()),
             CanonicalStreamEvent::Finish {
                 finish_reason,
@@ -2456,6 +2480,29 @@ impl OpenAIResponsesClientEmitter {
                 }
                 Ok(out)
             }
+            CanonicalStreamEvent::UnknownEvent(payload)
+                if openai_stream_terminal_error_body(&payload).is_some() =>
+            {
+                self.finished = true;
+                let raw_event = payload.get("type").and_then(Value::as_str);
+                let event = raw_event
+                    .filter(|event| {
+                        matches!(*event, "response.failed" | "response.incomplete" | "error")
+                    })
+                    .unwrap_or("response.failed")
+                    .to_string();
+                let mut payload = if raw_event == Some(event.as_str()) {
+                    payload
+                } else {
+                    openai_stream_terminal_error_body(&payload).unwrap_or(payload)
+                };
+                if payload.get("type").is_none() {
+                    if let Some(object) = payload.as_object_mut() {
+                        object.insert("type".to_string(), Value::String(event.clone()));
+                    }
+                }
+                self.encode_response_event(event.as_str(), payload)
+            }
             CanonicalStreamEvent::UnknownEvent(_) => Ok(Vec::new()),
             CanonicalStreamEvent::Finish { usage, .. } => {
                 if self.finished {
@@ -2682,6 +2729,40 @@ mod tests {
         )));
     }
 
+    #[test]
+    fn openai_responses_provider_state_treats_failed_event_as_terminal() {
+        let mut state = OpenAIResponsesProviderState::default();
+        let report_context = json!({});
+        let frames = state
+            .push_line(
+                &report_context,
+                data_line(json!({
+                    "type": "response.failed",
+                    "response": {
+                        "id": "resp_failed_123",
+                        "model": "gpt-5.4",
+                        "status": "failed",
+                        "error": {
+                            "message": "policy failure",
+                            "type": "invalid_request_error",
+                            "code": "cyber_policy"
+                        }
+                    }
+                })),
+            )
+            .expect("failed response event should parse");
+
+        assert!(frames.iter().any(|frame| matches!(
+            frame.event,
+            CanonicalStreamEvent::UnknownEvent(ref payload)
+                if payload.get("type").and_then(Value::as_str) == Some("response.failed")
+        )));
+        assert!(state
+            .finish(&report_context)
+            .expect("terminal failure should not synthesize completion")
+            .is_empty());
+    }
+
     #[test]
     fn openai_usage_derives_missing_input_tokens_from_total() {
         let usage = canonical_usage_from_openai_usage(Some(&json!({
@@ -2848,6 +2929,41 @@ mod tests {
         assert_eq!(response_sequence_numbers(&sse), (1..=9).collect::<Vec<_>>());
     }
 
+    #[test]
+    fn openai_responses_client_emitter_forwards_failed_unknown_event() {
+        let mut emitter = OpenAIResponsesClientEmitter::default();
+        let bytes = emitter
+            .emit(CanonicalStreamFrame {
+                id: "resp_failed_123".to_string(),
+                model: "gpt-5.4".to_string(),
+                event: CanonicalStreamEvent::UnknownEvent(json!({
+                    "type": "response.failed",
+                    "response": {
+                        "id": "resp_failed_123",
+                        "model": "gpt-5.4",
+                        "status": "failed",
+                        "error": {
+                            "message": "policy failure",
+                            "type": "invalid_request_error",
+                            "code": "cyber_policy"
+                        }
+                    }
+                })),
+            })
+            .expect("failed response event should encode");
+        let mut all = bytes;
+        all.extend(
+            emitter
+                .finish()
+                .expect("failed stream should not synthesize completion"),
+        );
+
+        let sse = String::from_utf8(all).expect("sse should be utf8");
+        assert!(sse.contains("event: response.failed\n"));
+        assert!(sse.contains("\"message\":\"policy failure\""));
+        assert!(!sse.contains("event: response.completed\n"));
+    }
+
     #[test]
     fn openai_responses_client_emitter_keeps_text_item_id_stable_after_text_started() {
         let mut emitter = OpenAIResponsesClientEmitter::default();

crates/aether-ai-formats/src/formats/openai/responses/codex.rs

@@ -239,6 +239,224 @@ fn extract_codex_prompt_cache_session_seed(provider_request_body: &Value) -> Opt
         .or_else(|| object.get("metadata").and_then(session_seed_from_metadata))
 }
 
+fn sha256_hex(input: &[u8]) -> String {
+    let digest = Sha256::digest(input);
+    let mut output = String::with_capacity(digest.len() * 2);
+    for byte in digest {
+        let _ = write!(&mut output, "{byte:02x}");
+    }
+    output
+}
+
+fn stable_json_digest(value: &Value) -> Option<String> {
+    serde_json::to_vec(value)
+        .ok()
+        .map(|serialized| sha256_hex(&serialized))
+}
+
+fn compact_prompt_cache_text(value: &str) -> Option<Value> {
+    const MAX_PROMPT_CACHE_TEXT_CHARS: usize = 4096;
+    let normalized = value.trim();
+    if normalized.is_empty() {
+        return None;
+    }
+    let mut text = normalized
+        .chars()
+        .take(MAX_PROMPT_CACHE_TEXT_CHARS)
+        .collect::<String>();
+    if normalized.chars().count() > MAX_PROMPT_CACHE_TEXT_CHARS {
+        text.push_str("...");
+    }
+    Some(Value::String(text))
+}
+
+fn compact_prompt_cache_anchor(value: &Value) -> Value {
+    match value {
+        Value::String(text) => compact_prompt_cache_text(text).unwrap_or(Value::Null),
+        Value::Array(items) => Value::Array(
+            items
+                .iter()
+                .take(16)
+                .map(compact_prompt_cache_anchor)
+                .filter(|value| !value.is_null())
+                .collect(),
+        ),
+        Value::Object(object) => {
+            let mut compacted = serde_json::Map::new();
+            for key in [
+                "type",
+                "role",
+                "id",
+                "name",
+                "description",
+                "text",
+                "input_text",
+                "output_text",
+                "content",
+                "call_id",
+                "arguments",
+                "output",
+                "parameters",
+                "strict",
+                "function",
+                "effort",
+                "summary",
+            ] {
+                let Some(value) = object.get(key) else {
+                    continue;
+                };
+                let value = compact_prompt_cache_anchor(value);
+                if !value.is_null() {
+                    compacted.insert(key.to_string(), value);
+                }
+            }
+            Value::Object(compacted)
+        }
+        Value::Null | Value::Bool(_) | Value::Number(_) => value.clone(),
+    }
+}
+
+fn compact_prompt_cache_json_anchor(value: &Value) -> Value {
+    match value {
+        Value::String(text) => compact_prompt_cache_text(text).unwrap_or(Value::Null),
+        Value::Array(items) => Value::Array(
+            items
+                .iter()
+                .take(16)
+                .map(compact_prompt_cache_json_anchor)
+                .filter(|value| !value.is_null())
+                .collect(),
+        ),
+        Value::Object(object) => {
+            let mut compacted = serde_json::Map::new();
+            let mut keys = object.keys().collect::<Vec<_>>();
+            keys.sort();
+            for key in keys {
+                if key == "cache_control" {
+                    continue;
+                }
+                let Some(value) = object.get(key) else {
+                    continue;
+                };
+                let value = compact_prompt_cache_json_anchor(value);
+                if !value.is_null() {
+                    compacted.insert(key.clone(), value);
+                }
+            }
+            Value::Object(compacted)
+        }
+        Value::Null | Value::Bool(_) | Value::Number(_) => value.clone(),
+    }
+}
+
+fn collect_codex_prompt_cache_control_anchors(value: &Value, anchors: &mut Vec<Value>) {
+    const MAX_PROMPT_CACHE_CONTROL_ANCHORS: usize = 16;
+    if anchors.len() >= MAX_PROMPT_CACHE_CONTROL_ANCHORS {
+        return;
+    }
+
+    match value {
+        Value::Object(object) => {
+            if object.contains_key("cache_control") {
+                let mut anchor = object.clone();
+                anchor.remove("cache_control");
+                let anchor = compact_prompt_cache_anchor(&Value::Object(anchor));
+                if !anchor.is_null() {
+                    anchors.push(anchor);
+                }
+            }
+            for child in object.values() {
+                if anchors.len() >= MAX_PROMPT_CACHE_CONTROL_ANCHORS {
+                    break;
+                }
+                collect_codex_prompt_cache_control_anchors(child, anchors);
+            }
+        }
+        Value::Array(items) => {
+            for child in items {
+                if anchors.len() >= MAX_PROMPT_CACHE_CONTROL_ANCHORS {
+                    break;
+                }
+                collect_codex_prompt_cache_control_anchors(child, anchors);
+            }
+        }
+        _ => {}
+    }
+}
+
+fn extract_codex_prompt_cache_control_seed(provider_request_body: &Value) -> Option<String> {
+    let mut anchors = Vec::new();
+    collect_codex_prompt_cache_control_anchors(provider_request_body, &mut anchors);
+    if anchors.is_empty() {
+        return None;
+    }
+
+    let seed = json!({
+        "model": provider_request_body.get("model"),
+        "anchors": anchors,
+    });
+    stable_json_digest(&seed).map(|digest| format!("cache_control:{digest}"))
+}
+
+fn first_responses_input_anchor(input: &Value) -> Option<Value> {
+    let items = input.as_array()?;
+    let first_user_message = items.iter().find(|item| {
+        item.get("type")
+            .and_then(Value::as_str)
+            .is_some_and(|value| value == "message")
+            && item
+                .get("role")
+                .and_then(Value::as_str)
+                .is_some_and(|value| value == "user")
+    });
+    let first_item = first_user_message.or_else(|| items.first())?;
+    let anchor = compact_prompt_cache_anchor(first_item);
+    (!anchor.is_null()).then_some(anchor)
+}
+
+fn extract_codex_stable_request_prompt_cache_seed(
+    provider_request_body: &Value,
+    user_api_key_id: Option<&str>,
+) -> Option<String> {
+    let object = provider_request_body.as_object()?;
+    let mut seed = serde_json::Map::new();
+
+    for key in [
+        "model",
+        "instructions",
+        "reasoning",
+        "tools",
+        "tool_choice",
+        "parallel_tool_calls",
+    ] {
+        if let Some(value) = object.get(key).filter(|value| !value.is_null()) {
+            let value = if key == "tools" {
+                compact_prompt_cache_json_anchor(value)
+            } else {
+                compact_prompt_cache_anchor(value)
+            };
+            seed.insert(key.to_string(), value);
+        }
+    }
+    if let Some(input_anchor) = object.get("input").and_then(first_responses_input_anchor) {
+        seed.insert("first_input".to_string(), input_anchor);
+    }
+    if let Some(user_api_key_id) = user_api_key_id
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+    {
+        seed.insert(
+            "api_key_id".to_string(),
+            Value::String(user_api_key_id.to_string()),
+        );
+    }
+
+    if seed.len() < 2 {
+        return None;
+    }
+    stable_json_digest(&Value::Object(seed)).map(|digest| format!("stable_request:{digest}"))
+}
+
 fn build_short_codex_header_id(seed: &str) -> Option<String> {
     let normalized = seed.trim();
     if normalized.is_empty() {
@@ -335,6 +553,14 @@ fn maybe_inject_codex_prompt_cache_key(
 
     let prompt_cache_key = extract_codex_prompt_cache_session_seed(provider_request_body)
         .and_then(|seed| build_stable_codex_prompt_cache_key_from_seed("session", &seed))
+        .or_else(|| {
+            extract_codex_prompt_cache_control_seed(provider_request_body)
+                .and_then(|seed| build_stable_codex_prompt_cache_key_from_seed("anchor", &seed))
+        })
+        .or_else(|| {
+            extract_codex_stable_request_prompt_cache_seed(provider_request_body, user_api_key_id)
+                .and_then(|seed| build_stable_codex_prompt_cache_key_from_seed("request", &seed))
+        })
         .or_else(|| user_api_key_id.and_then(build_stable_codex_prompt_cache_key));
     let Some(prompt_cache_key) = prompt_cache_key else {
         return;
@@ -854,6 +1080,157 @@ mod tests {
         assert!(body_c.get("metadata").is_none());
     }
 
+    #[test]
+    fn codex_responses_body_edits_derive_prompt_cache_key_from_cache_control_anchor() {
+        let mut body_a = json!({
+            "input": [{
+                "type": "message",
+                "role": "user",
+                "content": [{
+                    "type": "input_text",
+                    "text": "stable project brief",
+                    "cache_control": {"type": "ephemeral"}
+                }]
+            }, {
+                "type": "message",
+                "role": "user",
+                "content": [{"type": "input_text", "text": "new turn A"}]
+            }],
+            "model": "gpt-5.4"
+        });
+        let mut body_b = json!({
+            "input": [{
+                "type": "message",
+                "role": "user",
+                "content": [{
+                    "type": "input_text",
+                    "text": "stable project brief",
+                    "cache_control": {"type": "ephemeral"}
+                }]
+            }, {
+                "type": "message",
+                "role": "user",
+                "content": [{"type": "input_text", "text": "new turn B"}]
+            }],
+            "model": "gpt-5.4"
+        });
+        let mut body_c = json!({
+            "input": [{
+                "type": "message",
+                "role": "user",
+                "content": [{
+                    "type": "input_text",
+                    "text": "different project brief",
+                    "cache_control": {"type": "ephemeral"}
+                }]
+            }],
+            "model": "gpt-5.4"
+        });
+
+        apply_codex_openai_responses_special_body_edits(
+            &mut body_a,
+            "codex",
+            "openai:responses",
+            None,
+            Some("key-a"),
+        );
+        apply_codex_openai_responses_special_body_edits(
+            &mut body_b,
+            "codex",
+            "openai:responses",
+            None,
+            Some("key-b"),
+        );
+        apply_codex_openai_responses_special_body_edits(
+            &mut body_c,
+            "codex",
+            "openai:responses",
+            None,
+            Some("key-a"),
+        );
+
+        assert_eq!(body_a["prompt_cache_key"], body_b["prompt_cache_key"]);
+        assert_ne!(body_a["prompt_cache_key"], body_c["prompt_cache_key"]);
+    }
+
+    #[test]
+    fn codex_responses_body_edits_derive_prompt_cache_key_from_stable_request_anchor() {
+        let mut body_a = json!({
+            "input": [{
+                "type": "message",
+                "role": "user",
+                "content": [{"type": "input_text", "text": "open workspace"}]
+            }, {
+                "type": "message",
+                "role": "user",
+                "content": [{"type": "input_text", "text": "new turn A"}]
+            }],
+            "model": "gpt-5.4",
+            "instructions": "Be concise.",
+            "tools": [{
+                "type": "function",
+                "name": "shell",
+                "parameters": {"type": "object", "properties": {}}
+            }],
+            "reasoning": {"effort": "medium"}
+        });
+        let mut body_b = json!({
+            "input": [{
+                "type": "message",
+                "role": "user",
+                "content": [{"type": "input_text", "text": "open workspace"}]
+            }, {
+                "type": "message",
+                "role": "user",
+                "content": [{"type": "input_text", "text": "new turn B"}]
+            }],
+            "model": "gpt-5.4",
+            "instructions": "Be concise.",
+            "tools": [{
+                "type": "function",
+                "name": "shell",
+                "parameters": {"type": "object", "properties": {}}
+            }],
+            "reasoning": {"effort": "medium"}
+        });
+        let mut body_c = json!({
+            "input": [{
+                "type": "message",
+                "role": "user",
+                "content": [{"type": "input_text", "text": "open another workspace"}]
+            }],
+            "model": "gpt-5.4",
+            "instructions": "Be concise.",
+            "tools": [{"type": "function", "name": "shell"}],
+            "reasoning": {"effort": "medium"}
+        });
+
+        apply_codex_openai_responses_special_body_edits(
+            &mut body_a,
+            "codex",
+            "openai:responses",
+            None,
+            Some("key-a"),
+        );
+        apply_codex_openai_responses_special_body_edits(
+            &mut body_b,
+            "codex",
+            "openai:responses",
+            None,
+            Some("key-a"),
+        );
+        apply_codex_openai_responses_special_body_edits(
+            &mut body_c,
+            "codex",
+            "openai:responses",
+            None,
+            Some("key-a"),
+        );
+
+        assert_eq!(body_a["prompt_cache_key"], body_b["prompt_cache_key"]);
+        assert_ne!(body_a["prompt_cache_key"], body_c["prompt_cache_key"]);
+    }
+
     #[test]
     fn compact_body_edits_strip_include_store_and_stream() {
         let mut provider_request_body = json!({

crates/aether-ai-formats/src/formats/shared/stream_core/common.rs

@@ -108,6 +108,107 @@ pub fn canonical_usage_from_openai_usage(value: Option<&Value>) -> Option<Canoni
     })
 }
 
+pub fn openai_stream_payload_is_terminal_error(payload: &Value) -> bool {
+    let event_type = payload
+        .get("type")
+        .and_then(Value::as_str)
+        .unwrap_or_default();
+    if payload.get("error").is_some() {
+        return true;
+    }
+    if matches!(
+        event_type,
+        "error" | "response.failed" | "response.incomplete"
+    ) {
+        return true;
+    }
+
+    payload
+        .get("response")
+        .and_then(Value::as_object)
+        .and_then(|response| response.get("status"))
+        .and_then(Value::as_str)
+        .is_some_and(|status| matches!(status, "failed" | "incomplete"))
+}
+
+pub fn openai_stream_terminal_error_body(payload: &Value) -> Option<Value> {
+    if !openai_stream_payload_is_terminal_error(payload) {
+        return None;
+    }
+
+    let event_type = payload
+        .get("type")
+        .and_then(Value::as_str)
+        .unwrap_or_default();
+    let response = payload.get("response").and_then(Value::as_object);
+    let status = response
+        .and_then(|response| response.get("status"))
+        .and_then(Value::as_str);
+    let raw_error = response
+        .and_then(|response| response.get("error"))
+        .or_else(|| payload.get("error"));
+
+    let mut error = raw_error
+        .and_then(Value::as_object)
+        .cloned()
+        .unwrap_or_default();
+
+    let message = error
+        .get("message")
+        .and_then(Value::as_str)
+        .map(ToOwned::to_owned)
+        .or_else(|| raw_error.and_then(Value::as_str).map(ToOwned::to_owned))
+        .or_else(|| {
+            payload
+                .get("message")
+                .and_then(Value::as_str)
+                .map(ToOwned::to_owned)
+        })
+        .or_else(|| {
+            response
+                .and_then(|response| response.get("incomplete_details"))
+                .and_then(|details| details.get("reason"))
+                .and_then(Value::as_str)
+                .map(|reason| format!("Response incomplete: {reason}"))
+        })
+        .or_else(|| status.map(|status| format!("Response ended with status {status}")))
+        .unwrap_or_else(|| "Upstream stream ended with an error".to_string());
+
+    error
+        .entry("message".to_string())
+        .or_insert_with(|| Value::String(message));
+    error.entry("type".to_string()).or_insert_with(|| {
+        if event_type == "response.incomplete" || status == Some("incomplete") {
+            Value::String("incomplete".to_string())
+        } else {
+            Value::String("server_error".to_string())
+        }
+    });
+
+    if !error.contains_key("code") {
+        if let Some(reason) = response
+            .and_then(|response| response.get("incomplete_details"))
+            .and_then(|details| details.get("reason"))
+            .and_then(Value::as_str)
+        {
+            error.insert("code".to_string(), Value::String(reason.to_string()));
+        }
+    }
+
+    Some(json!({ "error": Value::Object(error) }))
+}
+
+pub fn openai_stream_terminal_error_message(payload: &Value) -> Option<String> {
+    openai_stream_terminal_error_body(payload)
+        .and_then(|body| body.get("error").cloned())
+        .and_then(|error| {
+            error
+                .get("message")
+                .and_then(Value::as_str)
+                .map(ToOwned::to_owned)
+        })
+}
+
 pub fn canonical_usage_from_claude_usage(value: Option<&Value>) -> Option<CanonicalUsage> {
     let usage = value?.as_object()?;
     let input_tokens = usage

crates/aether-ai-formats/src/formats/shared/stream_core/format_matrix.rs

@@ -14,7 +14,8 @@ use crate::formats::shared::error_body::{
 };
 use crate::formats::shared::sse::encode_json_sse;
 use crate::formats::shared::stream_core::common::{
-    decode_json_data_line, CanonicalStreamEvent, CanonicalStreamFrame, CanonicalUsage,
+    decode_json_data_line, openai_stream_terminal_error_body, openai_stream_terminal_error_message,
+    CanonicalStreamEvent, CanonicalStreamFrame, CanonicalUsage,
 };
 use crate::formats::shared::AiSurfaceFinalizeError;
 
@@ -197,6 +198,14 @@ impl StreamingStandardTerminalObserver {
             summary.model = Some(model);
         }
         match event {
+            CanonicalStreamEvent::UnknownEvent(payload)
+                if openai_stream_terminal_error_body(&payload).is_some() =>
+            {
+                summary.unknown_event_count = summary.unknown_event_count.saturating_add(1);
+                summary.observed_finish = true;
+                summary.finish_reason = Some("error".to_string());
+                summary.parser_error = openai_stream_terminal_error_message(&payload);
+            }
             CanonicalStreamEvent::UnknownEvent(_) => {
                 summary.unknown_event_count = summary.unknown_event_count.saturating_add(1);
             }
@@ -410,7 +419,8 @@ fn parse_provider_error(
 }
 
 fn parse_openai_error(payload: &Value) -> Option<(String, Option<String>, LocalCoreSyncErrorKind)> {
-    let error = payload.get("error")?.as_object()?;
+    let error_body = openai_stream_terminal_error_body(payload)?;
+    let error = error_body.get("error")?.as_object()?;
     let message = error.get("message").and_then(Value::as_str)?.to_string();
     let code = error
         .get("code")
@@ -973,6 +983,41 @@ mod tests {
         assert!(!summary.observed_finish);
     }
 
+    #[test]
+    fn terminal_observer_marks_openai_responses_failed_event_as_terminal_error() {
+        let mut report_context = report_context("openai:chat", "openai:responses");
+        report_context["provider_stream_event_api_format"] = json!("openai:responses");
+        let mut observer = StreamingStandardTerminalObserver::default();
+
+        observer
+            .push_line(
+                &report_context,
+                data_line(json!({
+                    "type": "response.failed",
+                    "response": {
+                        "id": "resp_failed_123",
+                        "model": "gpt-5.4",
+                        "status": "failed",
+                        "error": {
+                            "message": "policy failure",
+                            "type": "invalid_request_error",
+                            "code": "cyber_policy"
+                        }
+                    }
+                })),
+            )
+            .expect("failed event should be observed");
+
+        let summary = observer
+            .latest_summary()
+            .cloned()
+            .expect("summary should exist");
+        assert!(summary.observed_finish);
+        assert_eq!(summary.finish_reason.as_deref(), Some("error"));
+        assert_eq!(summary.parser_error.as_deref(), Some("policy failure"));
+        assert_eq!(summary.unknown_event_count, 1);
+    }
+
     #[test]
     fn terminal_observer_tracks_openai_image_stream_usage() {
         let mut report_context = report_context("openai:image", "openai:chat");