Merge pull request #682 from MMEXA/codex/codex-prompt-cache-identity-20260717

fix(codex): 统一通用缓存键与原生会话身份

apps/aether-gateway/src/ai_serving/planner/decision_input.rs

@@ -133,6 +133,17 @@ pub(crate) fn apply_provider_request_routing_policy_to_decision(
     );
 
     let Some(context) = input.routing_context.as_ref() else {
+        // Cache identity headers are projected only at the terminal boundary. Any non-empty
+        // session headers already present here are explicit client or header-rule inputs and stay
+        // authoritative.
+        if let Some(provider_request_body) = decision.provider_request_body.as_ref() {
+            crate::ai_serving::apply_codex_openai_responses_identity_headers(
+                &mut decision.provider_request_headers,
+                provider_request_body,
+                provider_type.as_str(),
+                provider_api_format.as_str(),
+            );
+        }
         return Ok(());
     };
     let provider_body_rules = decision
@@ -182,6 +193,14 @@ pub(crate) fn apply_provider_request_routing_policy_to_decision(
     })?;
     ensure_report_context_routing_trace(input, decision, &policy);
     if policy.mutation_plan.is_empty() {
+        if let Some(provider_request_body) = decision.provider_request_body.as_ref() {
+            crate::ai_serving::apply_codex_openai_responses_identity_headers(
+                &mut decision.provider_request_headers,
+                provider_request_body,
+                provider_type.as_str(),
+                provider_api_format.as_str(),
+            );
+        }
         return Ok(());
     }
     if original_provider_request_body.is_none() && !policy.mutation_plan.body_patch.is_empty() {
@@ -255,6 +274,12 @@ pub(crate) fn apply_provider_request_routing_policy_to_decision(
             input.requested_model.as_str(),
         )
     });
+    crate::ai_serving::apply_codex_openai_responses_identity_headers(
+        &mut provider_request_headers,
+        &provider_request_body,
+        provider_type.as_str(),
+        provider_api_format.as_str(),
+    );
     crate::ai_serving::apply_codex_openai_responses_lite_header_for_request_body_with_capabilities(
         &mut provider_request_headers,
         Some(&provider_request_body),
@@ -1279,6 +1304,107 @@ mod tests {
         );
     }
 
+    #[test]
+    fn codex_prompt_cache_identity_headers_are_terminal_after_routing_mutations() {
+        let mut input = sample_decision_input();
+        input
+            .routing_context
+            .as_mut()
+            .expect("routing context")
+            .client_api_format = "openai:responses".to_string();
+        set_provider_request_rules(
+            &mut input,
+            &["gpt-5"],
+            json!([{
+                "type": "patch_headers",
+                "patch": [
+                    {"op": "remove", "name": "session-id"},
+                    {"op": "remove", "name": "thread-id"}
+                ]
+            }]),
+        );
+        let identity = "172c39e6-c0a0-5a70-8b63-e0f8e0d185a3";
+        let mut decision = sample_decision();
+        decision.provider_type = Some("codex".to_string());
+        decision.provider_api_format = Some("openai:responses".to_string());
+        decision.client_api_format = Some("openai:responses".to_string());
+        decision.provider_request_body = Some(json!({
+            "model": "gpt-5",
+            "input": [],
+            "prompt_cache_key": identity,
+            "client_metadata": {
+                "session_id": identity,
+                "thread_id": identity
+            }
+        }));
+        assert!(!decision.provider_request_headers.contains_key("session-id"));
+        assert!(!decision.provider_request_headers.contains_key("thread-id"));
+
+        apply_provider_request_routing_policy_to_decision(&input, &mut decision, None)
+            .expect("terminal Codex identity contract should be restored");
+
+        assert_eq!(
+            decision
+                .provider_request_headers
+                .get("session-id")
+                .map(String::as_str),
+            Some(identity)
+        );
+        assert_eq!(
+            decision
+                .provider_request_headers
+                .get("thread-id")
+                .map(String::as_str),
+            Some(identity)
+        );
+    }
+
+    #[test]
+    fn codex_prompt_cache_identity_headers_fail_closed_after_body_identity_removal() {
+        let mut input = sample_decision_input();
+        input
+            .routing_context
+            .as_mut()
+            .expect("routing context")
+            .client_api_format = "openai:responses".to_string();
+        set_provider_request_rules(
+            &mut input,
+            &["gpt-5"],
+            json!([{
+                "type": "json_patch_body",
+                "patch": [
+                    {"op": "remove", "path": "/prompt_cache_key"},
+                    {"op": "remove", "path": "/client_metadata"}
+                ]
+            }]),
+        );
+        let identity = "172c39e6-c0a0-5a70-8b63-e0f8e0d185a3";
+        let mut decision = sample_decision();
+        decision.provider_type = Some("codex".to_string());
+        decision.provider_api_format = Some("openai:responses".to_string());
+        decision.client_api_format = Some("openai:responses".to_string());
+        decision.provider_request_body = Some(json!({
+            "model": "gpt-5",
+            "input": [],
+            "prompt_cache_key": identity,
+            "client_metadata": {
+                "session_id": identity,
+                "thread_id": identity
+            }
+        }));
+        assert!(!decision.provider_request_headers.contains_key("session-id"));
+        assert!(!decision.provider_request_headers.contains_key("thread-id"));
+
+        apply_provider_request_routing_policy_to_decision(&input, &mut decision, None)
+            .expect("terminal Codex identity contract should fail closed");
+
+        let body = decision.provider_request_body.as_ref().expect("body");
+        assert!(body.get("prompt_cache_key").is_none());
+        assert!(body.get("client_metadata").is_none());
+        assert!(!decision.provider_request_headers.contains_key("session-id"));
+        assert!(!decision.provider_request_headers.contains_key("thread-id"));
+    }
+
     #[test]
     fn codex_compact_contract_is_terminal_after_routing_mutations() {
         let mut input = sample_decision_input();

apps/aether-gateway/src/ai_serving/planner/standard/codex.rs

@@ -3,7 +3,8 @@
 mod tests;
 
 pub(crate) use crate::ai_serving::{
-    apply_codex_openai_responses_special_body_edits, apply_codex_openai_special_headers,
+    apply_codex_openai_responses_identity_headers, apply_codex_openai_responses_special_body_edits,
+    apply_codex_openai_special_headers,
 };
 
 pub(crate) fn codex_model_capabilities_for_transport(

apps/aether-gateway/src/ai_serving/planner/standard/codex/tests.rs

@@ -1,10 +1,12 @@
 use std::collections::BTreeMap;
 
 use super::{
-    apply_codex_openai_responses_special_body_edits, apply_codex_openai_special_headers,
-    codex_model_capabilities,
+    apply_codex_openai_responses_identity_headers, apply_codex_openai_responses_special_body_edits,
+    apply_codex_openai_special_headers, codex_model_capabilities,
+};
+use crate::ai_serving::planner::standard::{
+    build_cross_format_openai_responses_request_body, build_local_openai_responses_request_body,
 };
-use crate::ai_serving::planner::standard::build_local_openai_responses_request_body;
 use http::{HeaderMap, HeaderValue};
 use serde_json::json;
 
@@ -180,11 +182,11 @@ fn does_not_synthesize_prompt_cache_key_from_api_key_identity() {
 }
 
 #[test]
-fn keeps_existing_prompt_cache_key_for_codex_requests() {
+fn adapts_generic_prompt_cache_key_to_codex_native_identity() {
     let mut body = json!({
         "model": "gpt-5",
         "input": "hello",
-        "prompt_cache_key": "existing-key",
+        "prompt_cache_key": "ltm-pc-v2-5557e02f5c9b447a97673ba330dbe77a",
     });
 
     apply_codex_openai_responses_special_body_edits(
@@ -195,11 +197,291 @@ fn keeps_existing_prompt_cache_key_for_codex_requests() {
         Some("key-123"),
     );
 
-    assert_eq!(body["prompt_cache_key"], "existing-key");
+    let expected_identity = "d9c5d122-7c1c-5fb1-ba9d-656062eda44e";
+    assert_eq!(body["prompt_cache_key"], expected_identity);
+    assert_eq!(body["client_metadata"]["session_id"], expected_identity);
+    assert_eq!(body["client_metadata"]["thread_id"], expected_identity);
 }
 
 #[test]
-fn injects_identity_headers_without_deriving_session_headers_from_body() {
+fn preserves_native_codex_cache_identity_and_metadata() {
+    let mut body = json!({
+        "model": "gpt-5",
+        "input": "hello",
+        "prompt_cache_key": "guardian:parent-thread",
+        "client_metadata": {
+            "session_id": "native-session",
+            "thread_id": "native-thread",
+            "turn_id": "native-turn"
+        }
+    });
+    let expected = body.clone();
+
+    apply_codex_openai_responses_special_body_edits(
+        &mut body,
+        "codex",
+        "openai:responses",
+        None,
+        Some("key-123"),
+    );
+
+    assert_eq!(body["prompt_cache_key"], expected["prompt_cache_key"]);
+    assert_eq!(body["client_metadata"], expected["client_metadata"]);
+}
+
+#[test]
+fn preserves_uuid_prompt_cache_key_while_completing_codex_identity() {
+    let identity = "172c39e6-c0a0-5a70-8b63-e0f8e0d185a3";
+    let mut body = json!({
+        "model": "gpt-5.6-luna",
+        "input": "hello",
+        "prompt_cache_key": identity
+    });
+
+    apply_codex_openai_responses_special_body_edits(
+        &mut body,
+        "codex",
+        "openai:responses",
+        None,
+        None,
+    );
+
+    assert_eq!(body["prompt_cache_key"], identity);
+    assert_eq!(body["client_metadata"]["session_id"], identity);
+    assert_eq!(body["client_metadata"]["thread_id"], identity);
+}
+
+#[test]
+fn keeps_codex_prompt_cache_domains_distinct() {
+    let mut first = json!({
+        "model": "gpt-5.6-luna",
+        "input": "hello",
+        "prompt_cache_key": "tenant-a"
+    });
+    let mut second = json!({
+        "model": "gpt-5.6-luna",
+        "input": "hello",
+        "prompt_cache_key": "tenant-b"
+    });
+
+    for body in [&mut first, &mut second] {
+        apply_codex_openai_responses_special_body_edits(
+            body,
+            "codex",
+            "openai:responses",
+            None,
+            None,
+        );
+    }
+
+    assert_ne!(first["prompt_cache_key"], second["prompt_cache_key"]);
+    assert_eq!(
+        first["prompt_cache_key"],
+        first["client_metadata"]["session_id"]
+    );
+    assert_eq!(
+        second["prompt_cache_key"],
+        second["client_metadata"]["session_id"]
+    );
+}
+
+#[test]
+fn completes_partial_and_null_codex_client_metadata() {
+    let mut partial = json!({
+        "model": "gpt-5.6-luna",
+        "input": "hello",
+        "prompt_cache_key": "generic-affinity",
+        "client_metadata": {
+            "thread_id": "native-thread",
+            "caller": "sdk"
+        }
+    });
+    let mut null_metadata = json!({
+        "model": "gpt-5.6-luna",
+        "input": "hello",
+        "prompt_cache_key": "generic-affinity",
+        "client_metadata": null
+    });
+    let mut null_session = json!({
+        "model": "gpt-5.6-luna",
+        "input": "hello",
+        "prompt_cache_key": "generic-affinity",
+        "client_metadata": {
+            "session_id": null,
+            "thread_id": null,
+            "caller": "sdk"
+        }
+    });
+
+    for body in [&mut partial, &mut null_metadata, &mut null_session] {
+        apply_codex_openai_responses_special_body_edits(
+            body,
+            "codex",
+            "openai:responses",
+            None,
+            None,
+        );
+    }
+
+    assert_eq!(partial["client_metadata"]["thread_id"], "native-thread");
+    assert_eq!(partial["client_metadata"]["caller"], "sdk");
+    assert_eq!(
+        partial["client_metadata"]["session_id"],
+        partial["prompt_cache_key"]
+    );
+    assert_eq!(
+        null_metadata["client_metadata"]["session_id"],
+        null_metadata["prompt_cache_key"]
+    );
+    assert_eq!(
+        null_metadata["client_metadata"]["thread_id"],
+        null_metadata["prompt_cache_key"]
+    );
+    assert_eq!(
+        null_session["client_metadata"]["session_id"],
+        null_session["prompt_cache_key"]
+    );
+    assert_eq!(
+        null_session["client_metadata"]["thread_id"],
+        null_session["prompt_cache_key"]
+    );
+    assert_eq!(null_session["client_metadata"]["caller"], "sdk");
+}
+
+#[test]
+fn leaves_malformed_codex_client_metadata_unchanged() {
+    let mut body = json!({
+        "model": "gpt-5.6-luna",
+        "input": "hello",
+        "prompt_cache_key": "generic-affinity",
+        "client_metadata": "invalid"
+    });
+    let mut malformed_fields = json!({
+        "model": "gpt-5.6-luna",
+        "input": "hello",
+        "prompt_cache_key": "generic-affinity",
+        "client_metadata": {
+            "session_id": 42,
+            "thread_id": ""
+        }
+    });
+    let expected_malformed_metadata = malformed_fields["client_metadata"].clone();
+
+    for candidate in [&mut body, &mut malformed_fields] {
+        apply_codex_openai_responses_special_body_edits(
+            candidate,
+            "codex",
+            "openai:responses",
+            None,
+            None,
+        );
+    }
+
+    assert_eq!(body["prompt_cache_key"], "generic-affinity");
+    assert_eq!(body["client_metadata"], "invalid");
+    assert_eq!(malformed_fields["prompt_cache_key"], "generic-affinity");
+    assert_eq!(
+        malformed_fields["client_metadata"],
+        expected_malformed_metadata
+    );
+}
+
+#[test]
+fn limits_prompt_cache_identity_adaptation_to_codex_responses_family() {
+    let original = json!({
+        "model": "gpt-5.6-luna",
+        "input": "hello",
+        "prompt_cache_key": "generic-affinity"
+    });
+    let mut standard_openai = original.clone();
+    let mut codex_compact = original.clone();
+
+    apply_codex_openai_responses_special_body_edits(
+        &mut standard_openai,
+        "openai",
+        "openai:responses",
+        None,
+        None,
+    );
+    apply_codex_openai_responses_special_body_edits(
+        &mut codex_compact,
+        "codex",
+        "openai:responses:compact",
+        None,
+        None,
+    );
+
+    assert_eq!(standard_openai, original);
+    assert_ne!(codex_compact["prompt_cache_key"], "generic-affinity");
+    assert!(codex_compact.get("client_metadata").is_none());
+}
+
+#[test]
+fn chat_to_codex_responses_adapts_prompt_cache_identity_end_to_end() {
+    let body = json!({
+        "model": "gpt-5.6-luna",
+        "messages": [{"role": "user", "content": "hello"}],
+        "prompt_cache_key": "ltm-pc-v2-5557e02f5c9b447a97673ba330dbe77a"
+    });
+
+    let provider_request_body = build_cross_format_openai_responses_request_body(
+        &body,
+        "gpt-5.6-luna",
+        "openai:chat",
+        "openai:responses",
+        true,
+        false,
+        "codex",
+        None,
+        None,
+        &HeaderMap::new(),
+        false,
+    )
+    .expect("chat to Codex Responses request should build");
+
+    let expected_identity = "d9c5d122-7c1c-5fb1-ba9d-656062eda44e";
+    assert_eq!(provider_request_body["prompt_cache_key"], expected_identity);
+    assert_eq!(
+        provider_request_body["client_metadata"]["session_id"],
+        expected_identity
+    );
+    assert_eq!(
+        provider_request_body["client_metadata"]["thread_id"],
+        expected_identity
+    );
+
+    let mut provider_request_headers = BTreeMap::new();
+    apply_codex_openai_special_headers(
+        &mut provider_request_headers,
+        &provider_request_body,
+        &HeaderMap::new(),
+        "codex",
+        "openai:responses",
+        Some("trace-codex-cache-identity"),
+        None,
+    );
+    apply_codex_openai_responses_identity_headers(
+        &mut provider_request_headers,
+        &provider_request_body,
+        "codex",
+        "openai:responses",
+    );
+    assert_eq!(
+        provider_request_headers
+            .get("session-id")
+            .map(String::as_str),
+        Some(expected_identity)
+    );
+    assert_eq!(
+        provider_request_headers
+            .get("thread-id")
+            .map(String::as_str),
+        Some(expected_identity)
+    );
+}
+
+#[test]
+fn projects_uuid_prompt_cache_identity_into_missing_session_headers() {
     let mut headers = BTreeMap::new();
     let body = json!({
         "model": "gpt-5",
@@ -215,7 +497,7 @@ fn injects_identity_headers_without_deriving_session_headers_from_body() {
         Some("trace-codex-123"),
         Some(r#"{"account_id":"acc-123","is_fedramp":true}"#),
     );
-
+    apply_codex_openai_responses_identity_headers(&mut headers, &body, "codex", "openai:responses");
     assert_eq!(
         headers.get("chatgpt-account-id"),
         Some(&"acc-123".to_string())
@@ -228,8 +510,88 @@ fn injects_identity_headers_without_deriving_session_headers_from_body() {
     assert_eq!(headers.get("originator"), Some(&"codex_cli_rs".to_string()));
     assert!(!headers.contains_key("version"));
     assert_eq!(headers.get("x-openai-fedramp"), Some(&"true".to_string()));
-    assert_eq!(headers.get("session-id"), None);
-    assert_eq!(headers.get("thread-id"), None);
+    assert_eq!(
+        headers.get("session-id").map(String::as_str),
+        Some("172c39e6-c0a0-5a70-8b63-e0f8e0d185a3")
+    );
+    assert_eq!(
+        headers.get("thread-id").map(String::as_str),
+        Some("172c39e6-c0a0-5a70-8b63-e0f8e0d185a3")
+    );
+}
+
+#[test]
+fn projects_native_codex_metadata_for_non_uuid_cache_overrides() {
+    let mut headers = BTreeMap::new();
+    let body = json!({
+        "model": "gpt-5.6-luna",
+        "prompt_cache_key": "guardian:parent-thread",
+        "client_metadata": {
+            "session_id": "019f687b-8e92-7842-9631-d5bf0dba0a3b",
+            "thread_id": "019f6d20-1111-7222-8333-444455556666"
+        }
+    });
+
+    apply_codex_openai_special_headers(
+        &mut headers,
+        &body,
+        &HeaderMap::new(),
+        "codex",
+        "openai:responses",
+        None,
+        None,
+    );
+    apply_codex_openai_responses_identity_headers(&mut headers, &body, "codex", "openai:responses");
+
+    assert_eq!(
+        headers.get("session-id").map(String::as_str),
+        Some("019f687b-8e92-7842-9631-d5bf0dba0a3b")
+    );
+    assert_eq!(
+        headers.get("thread-id").map(String::as_str),
+        Some("019f6d20-1111-7222-8333-444455556666")
+    );
+}
+
+#[test]
+fn leaves_non_native_cache_keys_out_of_identity_headers() {
+    let mut headers = BTreeMap::new();
+    let body = json!({
+        "model": "gpt-5.6-luna",
+        "prompt_cache_key": "generic-cache-key"
+    });
+
+    apply_codex_openai_special_headers(
+        &mut headers,
+        &body,
+        &HeaderMap::new(),
+        "codex",
+        "openai:responses",
+        None,
+        None,
+    );
+    apply_codex_openai_responses_identity_headers(&mut headers, &body, "codex", "openai:responses");
+
+    assert!(!headers.contains_key("session-id"));
+    assert!(!headers.contains_key("thread-id"));
+}
+
+#[test]
+fn leaves_malformed_native_metadata_out_of_identity_headers() {
+    let mut headers = BTreeMap::new();
+    let body = json!({
+        "model": "gpt-5.6-luna",
+        "prompt_cache_key": "172c39e6-c0a0-5a70-8b63-e0f8e0d185a3",
+        "client_metadata": {
+            "session_id": 42,
+            "thread_id": ""
+        }
+    });
+
+    apply_codex_openai_responses_identity_headers(&mut headers, &body, "codex", "openai:responses");
+
+    assert!(!headers.contains_key("session-id"));
+    assert!(!headers.contains_key("thread-id"));
 }
 
 #[test]
@@ -247,7 +609,6 @@ fn injects_only_codex_client_headers_for_images_requests() {
         Some("trace-codex-image-123"),
         Some(r#"{"account_id":"acc-123","is_fedramp":true}"#),
     );
-
     assert_eq!(
         headers.get("chatgpt-account-id"),
         Some(&"acc-123".to_string())
@@ -330,6 +691,7 @@ fn preserves_client_context_headers_and_enforces_codex_provider_identity() {
         Some("trace-codex-123"),
         Some(r#"{"account_id":"acc-123","is_fedramp":true}"#),
     );
+    apply_codex_openai_responses_identity_headers(&mut headers, &body, "codex", "openai:responses");
 
     assert_eq!(
         headers.get("x-client-request-id"),
@@ -371,7 +733,7 @@ fn preserves_client_context_headers_and_enforces_codex_provider_identity() {
 }
 
 #[test]
-fn compact_does_not_derive_session_headers_from_body() {
+fn compact_projects_uuid_prompt_cache_identity_into_session_headers() {
     let mut headers = BTreeMap::new();
     let body = json!({
         "model": "gpt-5",
@@ -387,6 +749,12 @@ fn compact_does_not_derive_session_headers_from_body() {
         Some("trace-codex-compact-123"),
         Some(r#"{"account_id":"acc-123","is_fedramp":true}"#),
     );
+    apply_codex_openai_responses_identity_headers(
+        &mut headers,
+        &body,
+        "codex",
+        "openai:responses:compact",
+    );
 
     assert_eq!(
         headers.get("chatgpt-account-id"),
@@ -400,6 +768,12 @@ fn compact_does_not_derive_session_headers_from_body() {
     assert_eq!(headers.get("originator"), Some(&"codex_cli_rs".to_string()));
     assert!(!headers.contains_key("version"));
     assert_eq!(headers.get("x-openai-fedramp"), Some(&"true".to_string()));
-    assert_eq!(headers.get("session-id"), None);
-    assert_eq!(headers.get("thread-id"), None);
+    assert_eq!(
+        headers.get("session-id").map(String::as_str),
+        Some("172c39e6-c0a0-5a70-8b63-e0f8e0d185a3")
+    );
+    assert_eq!(
+        headers.get("thread-id").map(String::as_str),
+        Some("172c39e6-c0a0-5a70-8b63-e0f8e0d185a3")
+    );
 }

apps/aether-gateway/src/ai_serving/pure/mod.rs

@@ -4,6 +4,7 @@ pub(crate) use aether_ai_formats::api::{
     aggregate_standard_chat_stream_sync_response, aggregate_standard_cli_stream_sync_response,
     api_format_alias_matches, api_format_storage_aliases,
     apply_codex_openai_compact_terminal_headers, apply_codex_openai_responses_chat_body_edits,
+    apply_codex_openai_responses_identity_headers,
     apply_codex_openai_responses_lite_header_for_request_body_with_capabilities,
     apply_codex_openai_responses_lite_header_with_capabilities,
     apply_codex_openai_responses_special_body_edits,

apps/aether-gateway/src/tests/ai_execute/stream_cli/compact.rs

@@ -657,7 +657,8 @@ async fn gateway_executes_openai_responses_compact_as_unary_request_impl() {
     );
     assert_eq!(
         seen_execution_runtime_request.body["prompt_cache_key"],
-        json!("session:compact-e2e")
+        // Compact omits client_metadata, but keeps the same deterministic Codex cache identity.
+        json!("f3eb8726-b7b2-56c5-90b5-8789d628c8cf")
     );
     assert_eq!(
         seen_execution_runtime_request.proxy_node_id,