Merge pull request #875 from dalamudx/feat/claude-code-dynamic-client-profile

feat(claude-code): 统一各提供商的画像管理

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

@@ -7,7 +7,7 @@ use crate::ai_serving::transport::{
     build_gemini_cli_v1internal_request, build_standard_provider_request_headers,
     GatewayProviderTransportSnapshot, GeminiCliRequestAuth, GeminiCliRequestAuthSupport,
     GeminiCliRequestEnvelopeSupport, StandardProviderRequestHeaders,
-    StandardProviderRequestHeadersInput, GEMINI_CLI_USER_AGENT,
+    StandardProviderRequestHeadersInput,
 };
 use crate::AppState;
 
@@ -64,8 +64,10 @@ pub(crate) async fn build_gemini_cli_v1internal_provider_request(
     )
     .ok_or(GeminiCliV1InternalRequestError::UpstreamUrlUnavailable)?;
 
-    let extra_headers =
-        BTreeMap::from([("user-agent".to_string(), GEMINI_CLI_USER_AGENT.to_string())]);
+    let extra_headers = BTreeMap::from([(
+        "user-agent".to_string(),
+        crate::ai_serving::transport::gemini_cli::gemini_cli_client_user_agent(),
+    )]);
     let headers = build_standard_provider_request_headers(StandardProviderRequestHeadersInput {
         transport: &payload.transport,
         provider_api_format: input.provider_api_format,

apps/aether-gateway/src/ai_serving/planner/passthrough/provider/family/request.rs

@@ -21,8 +21,7 @@ use crate::ai_serving::transport::{
     build_same_format_provider_headers, resolve_local_gemini_cli_request_auth,
     GeminiCliRequestAuth, GeminiCliRequestAuthSupport, GeminiCliRequestEnvelopeSupport,
     GrokHeaderInput, SameFormatProviderCompatibilityEdit,
-    SameFormatProviderCompatibilityEditAction, SameFormatProviderHeadersInput,
-    GEMINI_CLI_USER_AGENT, GROK_CHAT_PATH,
+    SameFormatProviderCompatibilityEditAction, SameFormatProviderHeadersInput, GROK_CHAT_PATH,
 };
 use crate::ai_serving::{
     CandidateFailureDiagnostic, GatewayProviderTransportSnapshot, CODEX_RESPONSES_LITE_HEADER,
@@ -533,7 +532,10 @@ pub(crate) async fn resolve_local_same_format_provider_candidate_payload_parts(
         .map(build_antigravity_static_identity_headers)
         .unwrap_or_default();
     if prepared.behavior.is_gemini_cli {
-        extra_headers.insert("user-agent".to_string(), GEMINI_CLI_USER_AGENT.to_string());
+        extra_headers.insert(
+            "user-agent".to_string(),
+            crate::ai_serving::transport::gemini_cli::gemini_cli_client_user_agent(),
+        );
     }
     let Some(mut provider_request_headers) = (if is_grok {
         build_grok_browser_headers(GrokHeaderInput {

apps/aether-gateway/src/codex_profile.rs

@@ -1,465 +0,0 @@
-//! Codex 客户端画像的运行时发布与官方 CLI 版本刷新。
-
-use std::collections::BTreeMap;
-use std::future::Future;
-use std::time::Duration;
-
-use aether_runtime_state::RuntimeState;
-use futures_util::StreamExt as _;
-use reqwest::{redirect::Policy, Client};
-use semver::Version;
-use serde::{Deserialize, Serialize};
-use tracing::{info, warn};
-
-use crate::ai_serving::api::{codex_client_version, set_codex_cli_version};
-use crate::AppState;
-
-const CLI_RELEASE_ENDPOINT: &str = "https://registry.npmjs.org/@openai%2Fcodex/latest";
-const PROFILE_CACHE_KEY: &str = "aether:codex:client-profile:v1";
-const PROFILE_CACHE_TTL: Duration = Duration::from_secs(30 * 24 * 60 * 60);
-const PROFILE_REFRESH_INTERVAL: Duration = Duration::from_secs(24 * 60 * 60);
-const RELEASE_CONNECT_TIMEOUT: Duration = Duration::from_secs(10);
-const RELEASE_REQUEST_TIMEOUT: Duration = Duration::from_secs(30);
-const MAX_RELEASE_BYTES: usize = 256 * 1024;
-const CLI_TARGETS: [&str; 6] = [
-    "darwin-arm64",
-    "darwin-x64",
-    "linux-arm64",
-    "linux-x64",
-    "win32-arm64",
-    "win32-x64",
-];
-
-#[derive(Debug, Deserialize)]
-#[serde(rename_all = "camelCase")]
-struct NpmRelease {
-    name: String,
-    version: String,
-    optional_dependencies: BTreeMap<String, String>,
-}
-
-#[derive(Debug, Deserialize, Serialize)]
-struct CachedProfile {
-    version: String,
-    verified_at_unix_secs: u64,
-}
-
-#[derive(Debug, thiserror::Error)]
-enum ProfileRefreshError {
-    #[error("Codex CLI release client initialization failed: {0}")]
-    Client(#[from] reqwest::Error),
-    #[error("Codex CLI release request returned HTTP {0}")]
-    HttpStatus(u16),
-    #[error("Codex CLI release response exceeded {MAX_RELEASE_BYTES} bytes")]
-    ResponseTooLarge,
-    #[error("Codex CLI release metadata is invalid")]
-    InvalidMetadata,
-    #[error("Codex CLI release version is older than the active profile")]
-    Rollback,
-    #[error("Codex CLI profile cache operation failed: {0}")]
-    Cache(String),
-}
-
-fn version_sequence(version: &str) -> Result<u64, ProfileRefreshError> {
-    let parsed = Version::parse(version).map_err(|_| ProfileRefreshError::InvalidMetadata)?;
-    if !parsed.pre.is_empty()
-        || !parsed.build.is_empty()
-        || parsed.major > 999
-        || parsed.minor > 999
-        || parsed.patch > 999
-    {
-        return Err(ProfileRefreshError::InvalidMetadata);
-    }
-    Ok(1 + parsed.major * 1_000_000 + parsed.minor * 1_000 + parsed.patch)
-}
-
-/// 校验官方 npm stable 标签及六个平台依赖来自同一版本发布。
-fn parse_cli_release(bytes: &[u8]) -> Result<String, ProfileRefreshError> {
-    if bytes.len() > MAX_RELEASE_BYTES {
-        return Err(ProfileRefreshError::ResponseTooLarge);
-    }
-    let release = serde_json::from_slice::<NpmRelease>(bytes)
-        .map_err(|_| ProfileRefreshError::InvalidMetadata)?;
-    let sequence = version_sequence(&release.version)?;
-    if sequence == 0
-        || release.name != "@openai/codex"
-        || CLI_TARGETS.iter().any(|target| {
-            release
-                .optional_dependencies
-                .get(&format!("@openai/codex-{target}"))
-                != Some(&format!("npm:@openai/codex@{}-{target}", release.version))
-        })
-    {
-        return Err(ProfileRefreshError::InvalidMetadata);
-    }
-    Ok(release.version)
-}
-
-fn refresh_enabled_from(value: Option<&str>) -> bool {
-    !value.is_some_and(|value| {
-        matches!(
-            value.trim().to_ascii_lowercase().as_str(),
-            "0" | "false" | "off"
-        )
-    })
-}
-
-fn refresh_enabled() -> bool {
-    refresh_enabled_from(
-        std::env::var("AETHER_CODEX_CLIENT_PROFILE_REFRESH")
-            .ok()
-            .as_deref(),
-    )
-}
-
-fn fixed_version_from(value: Option<&str>) -> Option<String> {
-    let value = value?.trim();
-    if value.is_empty() || version_sequence(value).is_err() {
-        None
-    } else {
-        Some(value.to_owned())
-    }
-}
-
-fn fixed_version_override() -> Option<String> {
-    let value = std::env::var("AETHER_CODEX_CLIENT_VERSION").ok()?;
-    let version = fixed_version_from(Some(&value));
-    if version.is_none() {
-        warn!(
-            event_name = "codex_client_profile_fixed_version_invalid",
-            "AETHER_CODEX_CLIENT_VERSION is invalid; using cached or built-in profile"
-        );
-    }
-    version
-}
-
-fn build_release_client() -> Result<Client, ProfileRefreshError> {
-    Client::builder()
-        .https_only(true)
-        .no_proxy()
-        .redirect(Policy::none())
-        .connect_timeout(RELEASE_CONNECT_TIMEOUT)
-        .timeout(RELEASE_REQUEST_TIMEOUT)
-        .build()
-        .map_err(ProfileRefreshError::Client)
-}
-
-async fn fetch_latest_cli_version(client: &Client) -> Result<String, ProfileRefreshError> {
-    let response = client
-        .get(CLI_RELEASE_ENDPOINT)
-        .send()
-        .await
-        .map_err(ProfileRefreshError::Client)?;
-    if !response.status().is_success() {
-        return Err(ProfileRefreshError::HttpStatus(response.status().as_u16()));
-    }
-    if response
-        .content_length()
-        .is_some_and(|length| length > MAX_RELEASE_BYTES as u64)
-    {
-        return Err(ProfileRefreshError::ResponseTooLarge);
-    }
-
-    let mut bytes = Vec::new();
-    let mut stream = response.bytes_stream();
-    while let Some(chunk) = stream.next().await {
-        let chunk = chunk.map_err(ProfileRefreshError::Client)?;
-        if bytes.len().saturating_add(chunk.len()) > MAX_RELEASE_BYTES {
-            return Err(ProfileRefreshError::ResponseTooLarge);
-        }
-        bytes.extend_from_slice(&chunk);
-    }
-    parse_cli_release(&bytes)
-}
-
-async fn restore_cached_profile(runtime: &RuntimeState) -> Result<(), ProfileRefreshError> {
-    let Some(raw) = runtime
-        .kv_get(PROFILE_CACHE_KEY)
-        .await
-        .map_err(|err| ProfileRefreshError::Cache(err.to_string()))?
-    else {
-        return Ok(());
-    };
-    let cached = serde_json::from_str::<CachedProfile>(&raw)
-        .map_err(|_| ProfileRefreshError::InvalidMetadata)?;
-    if let Some(version) = cached_version_to_restore(&cached, &codex_client_version())? {
-        set_codex_cli_version(&version).map_err(|_| ProfileRefreshError::InvalidMetadata)?;
-        info!(
-            event_name = "codex_client_profile_restored",
-            version = %version,
-            verified_at_unix_secs = cached.verified_at_unix_secs,
-            "restored cached Codex CLI profile"
-        );
-    }
-    Ok(())
-}
-
-fn cached_version_to_restore(
-    cached: &CachedProfile,
-    active_version: &str,
-) -> Result<Option<String>, ProfileRefreshError> {
-    let cached_sequence = version_sequence(&cached.version)?;
-    let active_sequence = version_sequence(active_version)?;
-    Ok((cached_sequence >= active_sequence).then(|| cached.version.clone()))
-}
-
-async fn refresh_once_with_fetch<F, Fut>(
-    runtime: &RuntimeState,
-    fixed_version: Option<&str>,
-    refresh_is_enabled: bool,
-    fetch_latest: F,
-) -> Result<String, ProfileRefreshError>
-where
-    F: FnOnce() -> Fut,
-    Fut: Future<Output = Result<String, ProfileRefreshError>>,
-{
-    if let Some(version) = fixed_version {
-        set_codex_cli_version(version).map_err(|_| ProfileRefreshError::InvalidMetadata)?;
-        return Ok(version.to_owned());
-    }
-
-    if let Err(error) = restore_cached_profile(runtime).await {
-        // 缓存损坏或暂时不可用不应阻断官方版本检查；当前进程继续使用旧画像。
-        warn!(
-            event_name = "codex_client_profile_cache_restore_failed",
-            error = %error,
-            "could not restore cached Codex CLI profile"
-        );
-    }
-    if !refresh_is_enabled {
-        return Ok(codex_client_version());
-    }
-
-    let version = fetch_latest().await?;
-    let current = codex_client_version();
-    if version_sequence(&version)? < version_sequence(&current)? {
-        return Err(ProfileRefreshError::Rollback);
-    }
-
-    let cached = CachedProfile {
-        version: version.clone(),
-        verified_at_unix_secs: chrono::Utc::now().timestamp().max(0) as u64,
-    };
-    let serialized =
-        serde_json::to_string(&cached).map_err(|_| ProfileRefreshError::InvalidMetadata)?;
-    set_codex_cli_version(&version).map_err(|_| ProfileRefreshError::InvalidMetadata)?;
-    if let Err(error) = runtime
-        .kv_set(PROFILE_CACHE_KEY, serialized, Some(PROFILE_CACHE_TTL))
-        .await
-    {
-        // 本地画像已经完成原子替换；缓存写失败只影响下次进程启动的恢复。
-        warn!(
-            event_name = "codex_client_profile_cache_write_failed",
-            error = %error,
-            "published Codex CLI profile locally but could not persist the cache"
-        );
-    }
-    Ok(version)
-}
-
-async fn refresh_once(runtime: &RuntimeState) -> Result<String, ProfileRefreshError> {
-    let fixed_version = fixed_version_override();
-    refresh_once_with_fetch(
-        runtime,
-        fixed_version.as_deref(),
-        refresh_enabled(),
-        || async {
-            let client = build_release_client()?;
-            fetch_latest_cli_version(&client).await
-        },
-    )
-    .await
-}
-
-pub(crate) async fn prewarm(runtime: &RuntimeState) -> Result<String, String> {
-    refresh_once(runtime).await.map_err(|err| err.to_string())
-}
-
-pub(crate) fn spawn_worker(app: AppState) -> tokio::task::JoinHandle<()> {
-    crate::task_runtime::spawn_singleton_worker(
-        app,
-        crate::task_runtime::TASK_KEY_CODEX_CLIENT_PROFILE,
-        |app| async move {
-            let mut interval = tokio::time::interval(PROFILE_REFRESH_INTERVAL);
-            interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Delay);
-            // 启动阶段由 prewarm 完成一次检查；后台任务只负责后续每日刷新，避免重复建连。
-            interval.tick().await;
-            loop {
-                interval.tick().await;
-                match refresh_once(app.runtime_state()).await {
-                    Ok(version) => info!(
-                        event_name = "codex_client_profile_refreshed",
-                        version = %version,
-                        "refreshed Codex CLI profile"
-                    ),
-                    Err(error) => warn!(
-                        event_name = "codex_client_profile_refresh_failed",
-                        error = %error,
-                        "keeping the previous Codex CLI profile after refresh failure"
-                    ),
-                }
-            }
-        },
-    )
-}
-
-#[cfg(test)]
-mod tests {
-    use std::sync::atomic::{AtomicBool, Ordering};
-    use std::time::Duration;
-
-    use aether_runtime_state::{MemoryRuntimeStateConfig, RuntimeState};
-    use tokio::sync::{Mutex, MutexGuard};
-
-    use super::{
-        cached_version_to_restore, fixed_version_from, parse_cli_release, refresh_enabled_from,
-        refresh_once_with_fetch, CachedProfile, ProfileRefreshError, PROFILE_CACHE_KEY,
-    };
-    use crate::ai_serving::api::{
-        codex_client_profile, codex_client_version, set_codex_cli_version,
-        set_codex_client_profile, CodexClientProfile,
-    };
-
-    static PROFILE_TEST_LOCK: Mutex<()> = Mutex::const_new(());
-
-    struct ProfileRestore(CodexClientProfile);
-
-    impl Drop for ProfileRestore {
-        fn drop(&mut self) {
-            set_codex_client_profile(self.0.clone());
-        }
-    }
-
-    async fn profile_restore_guard() -> (MutexGuard<'static, ()>, ProfileRestore) {
-        let guard = PROFILE_TEST_LOCK.lock().await;
-        let restore = ProfileRestore(codex_client_profile());
-        (guard, restore)
-    }
-
-    #[test]
-    fn accepts_only_one_verified_cli_release_for_all_targets() {
-        let body = serde_json::json!({
-            "name": "@openai/codex",
-            "version": "0.200.1",
-            "optionalDependencies": {
-                "@openai/codex-darwin-arm64": "npm:@openai/[email protected]",
-                "@openai/codex-darwin-x64": "npm:@openai/[email protected]",
-                "@openai/codex-linux-arm64": "npm:@openai/[email protected]",
-                "@openai/codex-linux-x64": "npm:@openai/[email protected]",
-                "@openai/codex-win32-arm64": "npm:@openai/[email protected]",
-                "@openai/codex-win32-x64": "npm:@openai/[email protected]"
-            }
-        });
-        assert_eq!(
-            parse_cli_release(&serde_json::to_vec(&body).unwrap()).unwrap(),
-            "0.200.1"
-        );
-    }
-
-    #[test]
-    fn rejects_incomplete_platform_release() {
-        let body = serde_json::json!({
-            "name": "@openai/codex",
-            "version": "0.200.1",
-            "optionalDependencies": {}
-        });
-        assert!(parse_cli_release(&serde_json::to_vec(&body).unwrap()).is_err());
-    }
-
-    #[test]
-    fn refresh_and_fixed_version_environment_policies_are_strict() {
-        assert!(!refresh_enabled_from(Some("off")));
-        assert!(!refresh_enabled_from(Some(" FALSE ")));
-        assert!(refresh_enabled_from(None));
-        assert_eq!(
-            fixed_version_from(Some(" 0.200.1 ")).as_deref(),
-            Some("0.200.1")
-        );
-        assert!(fixed_version_from(Some("0.200.1-beta.1")).is_none());
-        assert!(fixed_version_from(Some("1.2")).is_none());
-    }
-
-    #[test]
-    fn cached_profile_never_rewinds_active_profile() {
-        let cached = CachedProfile {
-            version: "0.200.1".to_string(),
-            verified_at_unix_secs: 1,
-        };
-        assert_eq!(
-            cached_version_to_restore(&cached, "0.200.0").unwrap(),
-            Some("0.200.1".to_string())
-        );
-        assert_eq!(cached_version_to_restore(&cached, "0.201.0").unwrap(), None);
-    }
-
-    #[tokio::test]
-    async fn cache_hit_is_restored_without_network_when_refresh_is_disabled() {
-        let (_lock, _restore) = profile_restore_guard().await;
-        let runtime = RuntimeState::memory(MemoryRuntimeStateConfig::default());
-        runtime
-            .kv_set(
-                PROFILE_CACHE_KEY,
-                serde_json::to_string(&CachedProfile {
-                    version: "0.200.1".to_string(),
-                    verified_at_unix_secs: 1,
-                })
-                .unwrap(),
-                Some(Duration::from_secs(60)),
-            )
-            .await
-            .unwrap();
-
-        let result = refresh_once_with_fetch(&runtime, None, false, || async {
-            Err(ProfileRefreshError::HttpStatus(599))
-        })
-        .await
-        .unwrap();
-
-        assert_eq!(result, "0.200.1");
-        assert_eq!(codex_client_version(), "0.200.1");
-    }
-
-    #[tokio::test]
-    async fn refresh_failure_keeps_previous_profile() {
-        let (_lock, _restore) = profile_restore_guard().await;
-        let runtime = RuntimeState::memory(MemoryRuntimeStateConfig::default());
-        let before = codex_client_profile();
-        let result = refresh_once_with_fetch(&runtime, None, true, || async {
-            Err(ProfileRefreshError::HttpStatus(503))
-        })
-        .await;
-
-        assert!(matches!(result, Err(ProfileRefreshError::HttpStatus(503))));
-        assert_eq!(codex_client_profile(), before);
-    }
-
-    #[tokio::test]
-    async fn fixed_version_override_skips_network_and_publishes_profile() {
-        let (_lock, _restore) = profile_restore_guard().await;
-        let runtime = RuntimeState::memory(MemoryRuntimeStateConfig::default());
-        let fetch_called = AtomicBool::new(false);
-        let result = refresh_once_with_fetch(&runtime, Some("0.220.0"), true, || async {
-            fetch_called.store(true, Ordering::SeqCst);
-            Ok("0.221.0".to_string())
-        })
-        .await
-        .unwrap();
-
-        assert_eq!(result, "0.220.0");
-        assert!(!fetch_called.load(Ordering::SeqCst));
-        assert_eq!(codex_client_version(), "0.220.0");
-    }
-
-    #[tokio::test]
-    async fn rollback_is_rejected_without_replacing_profile() {
-        let (_lock, _restore) = profile_restore_guard().await;
-        set_codex_cli_version("0.220.0").unwrap();
-        let runtime = RuntimeState::memory(MemoryRuntimeStateConfig::default());
-        let result =
-            refresh_once_with_fetch(&runtime, None, true, || async { Ok("0.219.9".to_string()) })
-                .await;
-
-        assert!(matches!(result, Err(ProfileRefreshError::Rollback)));
-        assert_eq!(codex_client_version(), "0.220.0");
-    }
-}

apps/aether-gateway/src/execution_runtime/chatgpt_web_image.rs

@@ -43,12 +43,11 @@ use crate::AppState;
 
 const CHATGPT_WEB_INTERNAL_HEADER: &str = "x-aether-chatgpt-web-image";
 const CHATGPT_WEB_DEFAULT_BASE_URL: &str = "https://chatgpt.com";
-const CHATGPT_WEB_USER_AGENT: &str = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36 Edg/143.0.0.0";
-const CHATGPT_WEB_CLIENT_VERSION: &str = "prod-be885abbfcfe7b1f511e88b3003d9ee44757fbad";
-const CHATGPT_WEB_BUILD_NUMBER: &str = "5955942";
-const CHATGPT_WEB_SEC_CH_UA: &str =
-    r#""Microsoft Edge";v="143", "Chromium";v="143", "Not A(Brand";v="24""#;
-const CHATGPT_WEB_BROWSER_PROFILE: &str = "chrome143";
+use aether_provider_transport::client_identity::CHATGPT_WEB_BROWSER_PROFILE;
+use aether_provider_transport::client_identity::{
+    CHATGPT_WEB_BUILD_NUMBER, CHATGPT_WEB_CLIENT_VERSION, CHATGPT_WEB_SEC_CH_UA,
+    CHATGPT_WEB_USER_AGENT,
+};
 const CHATGPT_WEB_QUOTA_REFRESH_TIMEOUT_MS: u64 = 30_000;
 const CHATGPT_WEB_QUOTA_REFRESH_PROXY_TIMEOUT_MS: u64 = 60_000;
 const RUNTIME_METADATA_CAS_MAX_ATTEMPTS: usize = 16;

apps/aether-gateway/src/handlers/admin/provider/query/models/model_test.rs

@@ -3462,7 +3462,7 @@ async fn provider_query_execute_standard_test_candidate(
     {
         request_headers
             .entry("user-agent".to_string())
-            .or_insert_with(|| crate::provider_transport::GEMINI_CLI_USER_AGENT.to_string());
+            .or_insert_with(aether_provider_transport::gemini_cli::gemini_cli_client_user_agent);
     }
     let protected_headers = if uses_vertex_query_auth {
         vec!["content-type"]

apps/aether-gateway/src/lib.rs

@@ -35,9 +35,9 @@ mod auth;
 mod backup;
 mod bark_push;
 mod cache;
+mod cli_client_profile;
 mod client_session_affinity;
 mod clock;
-mod codex_profile;
 mod constants;
 mod control;
 mod data;
@@ -92,7 +92,7 @@ mod upstream_admission;
 mod usage;
 mod video_tasks;
 mod wallet_runtime;
-mod xai_profile;
+pub use cli_client_profile::ClientProfileSyncGuard;
 
 pub use self::ai_serving::api::{codex_client_originator, codex_client_user_agent};
 pub(crate) use self::ai_serving::api::{

apps/aether-gateway/src/main.rs

@@ -2513,34 +2513,16 @@ async fn run() -> Result<(), Box<dyn std::error::Error>> {
             );
         }
     }
-    match state.prewarm_codex_client_profile().await {
-        Ok(version) => {
-            info!(
-                codex_client_version = %version,
-                "prewarmed Codex client profile"
-            );
-        }
-        Err(err) => {
-            warn!(
-                error = %err,
-                "failed to refresh Codex client profile; built-in or cached profile remains active"
-            );
-        }
-    }
-    match state.prewarm_xai_client_profile().await {
-        Ok(version) => {
-            info!(
-                xai_client_version = %version,
-                "prewarmed Grok CLI client profile"
-            );
-        }
-        Err(err) => {
-            warn!(
-                error = %err,
-                "failed to refresh Grok CLI client profile; built-in or cached profile remains active"
-            );
+    for (client, result) in state.prewarm_client_profiles().await {
+        match result {
+            Ok(version) => info!(client, version = %version, "prewarmed client profile"),
+            Err(error) => warn!(client, error = %error,
+                "client profile refresh failed; built-in or cached profile remains active"),
         }
     }
+    // All roles synchronize local snapshots, not just the singleton owner.
+    // Keep the guard alive until main exits so shutdown cancels the task.
+    let _client_profile_cache_sync = state.spawn_client_profile_cache_sync();
     match prewarm_direct_h2c_sender_cache_from_env_for_startup().await {
         Ok(Some(report)) => {
             if report.failed_targets > 0 {

apps/aether-gateway/src/state/core.rs

@@ -54,7 +54,10 @@ use super::super::router::RequestAdmissionError;
 use super::super::{control::GatewayControlDecision, error::GatewayError};
 use super::super::{provider_transport, usage};
 
-use crate::codex_profile::spawn_worker as spawn_codex_client_profile_worker;
+use crate::cli_client_profile::{
+    spawn_worker as spawn_cli_client_profile_worker, CLAUDE_CODE_CLI_PROFILE, CLI_PROFILES,
+    CODEX_CLI_PROFILE, XAI_CLI_PROFILE,
+};
 use crate::maintenance::spawn_account_self_check_worker;
 use crate::maintenance::spawn_audit_cleanup_worker;
 use crate::maintenance::spawn_db_maintenance_worker;
@@ -76,7 +79,6 @@ use crate::maintenance::spawn_stats_hourly_aggregation_worker;
 use crate::maintenance::spawn_usage_cleanup_worker;
 use crate::maintenance::spawn_usage_counter_flush_worker;
 use crate::maintenance::spawn_wallet_daily_usage_aggregation_worker;
-use crate::xai_profile::spawn_worker as spawn_xai_client_profile_worker;
 
 const SYSTEM_CONFIG_CACHE_TTL: Duration = Duration::from_secs(30);
 // Requests may use a stale value after the fresh window until the entry reaches
@@ -152,11 +154,29 @@ fn system_config_key_affects_provider_transport_snapshot(key: &str) -> bool {
 
 impl AppState {
     pub async fn prewarm_codex_client_profile(&self) -> Result<String, String> {
-        crate::codex_profile::prewarm(self.runtime_state()).await
+        crate::cli_client_profile::prewarm(&CODEX_CLI_PROFILE, self.runtime_state()).await
+    }
+
+    pub async fn prewarm_claude_code_client_profile(&self) -> Result<String, String> {
+        crate::cli_client_profile::prewarm(&CLAUDE_CODE_CLI_PROFILE, self.runtime_state()).await
     }
 
     pub async fn prewarm_xai_client_profile(&self) -> Result<String, String> {
-        crate::xai_profile::prewarm(self.runtime_state()).await
+        crate::cli_client_profile::prewarm(&XAI_CLI_PROFILE, self.runtime_state()).await
+    }
+
+    pub async fn prewarm_client_profiles(&self) -> Vec<(&'static str, Result<String, String>)> {
+        futures_util::future::join_all(CLI_PROFILES.iter().map(|spec| async move {
+            (
+                spec.client_name(),
+                crate::cli_client_profile::prewarm(spec, self.runtime_state()).await,
+            )
+        }))
+        .await
+    }
+
+    pub fn spawn_client_profile_cache_sync(&self) -> crate::ClientProfileSyncGuard {
+        crate::cli_client_profile::spawn_cache_sync(self.clone())
     }
 
     pub async fn prewarm_chat_pii_redaction_runtime_config(&self) -> Result<bool, String> {
@@ -2357,14 +2377,15 @@ impl AppState {
             crate::task_runtime::TASK_KEY_MODEL_FETCH_WORKER,
             spawn_model_fetch_worker(background_state.clone()),
         );
-        supervise_worker(
-            crate::task_runtime::TASK_KEY_CODEX_CLIENT_PROFILE,
-            Some(spawn_codex_client_profile_worker(background_state.clone())),
-        );
-        supervise_worker(
-            crate::task_runtime::TASK_KEY_XAI_CLIENT_PROFILE,
-            Some(spawn_xai_client_profile_worker(background_state.clone())),
-        );
+        for spec in CLI_PROFILES {
+            supervise_worker(
+                spec.task_key(),
+                Some(spawn_cli_client_profile_worker(
+                    spec,
+                    background_state.clone(),
+                )),
+            );
+        }
         supervise_worker(
             crate::task_runtime::TASK_KEY_VIDEO_TASK_POLLER,
             spawn_video_task_poller(background_state.clone()),

apps/aether-gateway/src/task_runtime/mod.rs

@@ -25,7 +25,10 @@ pub(crate) const TASK_KEY_USAGE_COUNTER_FLUSH: &str = "usage.counter.flush.worke
 pub(crate) const TASK_KEY_VIDEO_TASK_POLLER: &str = "video.task.poller";
 pub(crate) const TASK_KEY_MODEL_FETCH_WORKER: &str = "model.fetch.worker";
 pub(crate) const TASK_KEY_CODEX_CLIENT_PROFILE: &str = "maintenance.codex.client.profile";
+pub(crate) const TASK_KEY_CLAUDE_CODE_CLIENT_PROFILE: &str =
+    "maintenance.claude_code.client.profile";
 pub(crate) const TASK_KEY_XAI_CLIENT_PROFILE: &str = "maintenance.xai.client.profile";
+pub(crate) const TASK_KEY_GEMINI_CLI_CLIENT_PROFILE: &str = "maintenance.gemini_cli.client.profile";
 pub(crate) const TASK_KEY_PROVIDER_QUOTA_RESET: &str = "provider.quota.reset.worker";
 pub(crate) const TASK_KEY_ACCOUNT_SELF_CHECK: &str = "account.self_check.worker";
 pub(crate) const TASK_KEY_POOL_SCORE_REBUILD: &str = "pool.score.rebuild.worker";
@@ -212,6 +215,22 @@ const TASK_DEFINITIONS: &[TaskDefinition] = &[
         true,
         RETRY_ONCE,
     ),
+    TaskDefinition::new(
+        TASK_KEY_CLAUDE_CODE_CLIENT_PROFILE,
+        TaskKind::Scheduled,
+        "daily",
+        true,
+        true,
+        RETRY_ONCE,
+    ),
+    TaskDefinition::new(
+        TASK_KEY_GEMINI_CLI_CLIENT_PROFILE,
+        TaskKind::Scheduled,
+        "daily",
+        true,
+        true,
+        RETRY_ONCE,
+    ),
     TaskDefinition::new(
         TASK_KEY_XAI_CLIENT_PROFILE,
         TaskKind::Scheduled,
@@ -957,3 +976,29 @@ mod worker_boot_run_id_tests {
         assert!(events.iter().all(|event| event.payload_json.is_none()));
     }
 }
+
+#[cfg(test)]
+mod client_profile_task_tests {
+    use super::*;
+
+    #[test]
+    fn all_cli_client_profile_tasks_are_registered_once() {
+        for (key, trigger) in [
+            (TASK_KEY_CODEX_CLIENT_PROFILE, "daily"),
+            (TASK_KEY_CLAUDE_CODE_CLIENT_PROFILE, "daily"),
+            (TASK_KEY_XAI_CLIENT_PROFILE, "interval"),
+            (TASK_KEY_GEMINI_CLI_CLIENT_PROFILE, "daily"),
+        ] {
+            let definitions: Vec<_> = task_definitions()
+                .iter()
+                .filter(|definition| definition.key == key)
+                .collect();
+            assert_eq!(definitions.len(), 1, "task {key} must be registered once");
+            let definition = definitions[0];
+            assert_eq!(definition.kind, TaskKind::Scheduled);
+            assert_eq!(definition.trigger, trigger);
+            assert!(definition.singleton);
+            assert!(definition.persist_history);
+        }
+    }
+}

apps/aether-gateway/src/xai_profile.rs

@@ -1,592 +0,0 @@
-//! Grok CLI 客户端版本的运行时发布与官方版本刷新。
-//!
-//! cli-chat-proxy.grok.com 会对低于最低版本的 `x-grok-client-version` 直接返回 426，
-//! 因此网关定期读取官方发布渠道并原子替换传输层使用的版本号。
-
-use std::collections::BTreeMap;
-use std::future::Future;
-use std::time::Duration;
-
-use aether_runtime_state::RuntimeState;
-use futures_util::StreamExt as _;
-use reqwest::{redirect::Policy, Client};
-use semver::Version;
-use serde::{Deserialize, Serialize};
-use tracing::{info, warn};
-
-use crate::provider_transport::{set_xai_client_version, xai_client_version};
-use crate::AppState;
-
-/// 官方安装脚本读取的 stable 渠道，响应体是纯文本版本号。
-const CLI_STABLE_CHANNEL_ENDPOINT: &str = "https://x.ai/cli/stable";
-/// stable 渠道不可达时（部分部署地区无法直连 x.ai）退回 npm 发布元数据。
-const CLI_NPM_RELEASE_ENDPOINT: &str = "https://registry.npmjs.org/@xai-official%2Fgrok/latest";
-const CLI_NPM_PACKAGE: &str = "@xai-official/grok";
-const PROFILE_CACHE_KEY: &str = "aether:xai:client-profile:v1";
-const PROFILE_CACHE_TTL: Duration = Duration::from_secs(30 * 24 * 60 * 60);
-/// xAI 会在发布后很快抬高最低版本，刷新间隔比 Codex 更短。
-const PROFILE_REFRESH_INTERVAL: Duration = Duration::from_secs(3 * 60 * 60);
-const RELEASE_CONNECT_TIMEOUT: Duration = Duration::from_secs(10);
-const RELEASE_REQUEST_TIMEOUT: Duration = Duration::from_secs(30);
-const MAX_RELEASE_BYTES: usize = 256 * 1024;
-const CLI_TARGETS: [&str; 6] = [
-    "darwin-arm64",
-    "darwin-x64",
-    "linux-arm64",
-    "linux-x64",
-    "win32-arm64",
-    "win32-x64",
-];
-
-#[derive(Debug, Deserialize)]
-#[serde(rename_all = "camelCase")]
-struct NpmRelease {
-    name: String,
-    version: String,
-    optional_dependencies: BTreeMap<String, String>,
-}
-
-#[derive(Debug, Deserialize, Serialize)]
-struct CachedProfile {
-    version: String,
-    verified_at_unix_secs: u64,
-}
-
-#[derive(Debug, thiserror::Error)]
-enum ProfileRefreshError {
-    #[error("Grok CLI release client initialization failed: {0}")]
-    Client(#[from] reqwest::Error),
-    #[error("Grok CLI release request returned HTTP {0}")]
-    HttpStatus(u16),
-    #[error("Grok CLI release response exceeded {MAX_RELEASE_BYTES} bytes")]
-    ResponseTooLarge,
-    #[error("Grok CLI release metadata is invalid")]
-    InvalidMetadata,
-    #[error("Grok CLI release version is older than the active profile")]
-    Rollback,
-    #[error("Grok CLI profile cache operation failed: {0}")]
-    Cache(String),
-    #[error("Grok CLI stable channel failed ({stable}); npm fallback failed ({npm})")]
-    AllSourcesFailed { stable: String, npm: String },
-}
-
-fn version_sequence(version: &str) -> Result<u64, ProfileRefreshError> {
-    let parsed = Version::parse(version).map_err(|_| ProfileRefreshError::InvalidMetadata)?;
-    if !parsed.pre.is_empty()
-        || !parsed.build.is_empty()
-        || parsed.major > 999
-        || parsed.minor > 999
-        || parsed.patch > 999
-    {
-        return Err(ProfileRefreshError::InvalidMetadata);
-    }
-    Ok(1 + parsed.major * 1_000_000 + parsed.minor * 1_000 + parsed.patch)
-}
-
-/// stable 渠道只返回一行版本号；任何多余内容都视为异常响应（例如被劫持的 HTML 页面）。
-fn parse_stable_channel(bytes: &[u8]) -> Result<String, ProfileRefreshError> {
-    if bytes.len() > MAX_RELEASE_BYTES {
-        return Err(ProfileRefreshError::ResponseTooLarge);
-    }
-    let text = std::str::from_utf8(bytes).map_err(|_| ProfileRefreshError::InvalidMetadata)?;
-    let version = text.trim();
-    version_sequence(version)?;
-    Ok(version.to_owned())
-}
-
-/// 校验 npm latest 标签及六个平台二进制包来自同一版本发布。
-fn parse_npm_release(bytes: &[u8]) -> Result<String, ProfileRefreshError> {
-    if bytes.len() > MAX_RELEASE_BYTES {
-        return Err(ProfileRefreshError::ResponseTooLarge);
-    }
-    let release = serde_json::from_slice::<NpmRelease>(bytes)
-        .map_err(|_| ProfileRefreshError::InvalidMetadata)?;
-    version_sequence(&release.version)?;
-    if release.name != CLI_NPM_PACKAGE
-        || CLI_TARGETS.iter().any(|target| {
-            release
-                .optional_dependencies
-                .get(&format!("{CLI_NPM_PACKAGE}-{target}"))
-                != Some(&release.version)
-        })
-    {
-        return Err(ProfileRefreshError::InvalidMetadata);
-    }
-    Ok(release.version)
-}
-
-fn refresh_enabled_from(value: Option<&str>) -> bool {
-    !value.is_some_and(|value| {
-        matches!(
-            value.trim().to_ascii_lowercase().as_str(),
-            "0" | "false" | "off"
-        )
-    })
-}
-
-fn refresh_enabled() -> bool {
-    refresh_enabled_from(
-        std::env::var("AETHER_XAI_CLIENT_PROFILE_REFRESH")
-            .ok()
-            .as_deref(),
-    )
-}
-
-fn fixed_version_from(value: Option<&str>) -> Option<String> {
-    let value = value?.trim();
-    if value.is_empty() || version_sequence(value).is_err() {
-        None
-    } else {
-        Some(value.to_owned())
-    }
-}
-
-fn fixed_version_override() -> Option<String> {
-    let value = std::env::var("AETHER_XAI_CLIENT_VERSION").ok()?;
-    let version = fixed_version_from(Some(&value));
-    if version.is_none() {
-        warn!(
-            event_name = "xai_client_profile_fixed_version_invalid",
-            "AETHER_XAI_CLIENT_VERSION is invalid; using cached or built-in profile"
-        );
-    }
-    version
-}
-
-fn build_release_client() -> Result<Client, ProfileRefreshError> {
-    Client::builder()
-        .https_only(true)
-        .no_proxy()
-        .redirect(Policy::none())
-        .connect_timeout(RELEASE_CONNECT_TIMEOUT)
-        .timeout(RELEASE_REQUEST_TIMEOUT)
-        .build()
-        .map_err(ProfileRefreshError::Client)
-}
-
-async fn fetch_bounded(client: &Client, url: &str) -> Result<Vec<u8>, ProfileRefreshError> {
-    let response = client
-        .get(url)
-        .send()
-        .await
-        .map_err(ProfileRefreshError::Client)?;
-    if !response.status().is_success() {
-        return Err(ProfileRefreshError::HttpStatus(response.status().as_u16()));
-    }
-    if response
-        .content_length()
-        .is_some_and(|length| length > MAX_RELEASE_BYTES as u64)
-    {
-        return Err(ProfileRefreshError::ResponseTooLarge);
-    }
-
-    let mut bytes = Vec::new();
-    let mut stream = response.bytes_stream();
-    while let Some(chunk) = stream.next().await {
-        let chunk = chunk.map_err(ProfileRefreshError::Client)?;
-        if bytes.len().saturating_add(chunk.len()) > MAX_RELEASE_BYTES {
-            return Err(ProfileRefreshError::ResponseTooLarge);
-        }
-        bytes.extend_from_slice(&chunk);
-    }
-    Ok(bytes)
-}
-
-async fn fetch_latest_with_fallback<S, SFut, N, NFut>(
-    fetch_stable: S,
-    fetch_npm: N,
-) -> Result<String, ProfileRefreshError>
-where
-    S: FnOnce() -> SFut,
-    SFut: Future<Output = Result<String, ProfileRefreshError>>,
-    N: FnOnce() -> NFut,
-    NFut: Future<Output = Result<String, ProfileRefreshError>>,
-{
-    let stable_error = match fetch_stable().await {
-        Ok(version) => return Ok(version),
-        Err(error) => error,
-    };
-    fetch_npm()
-        .await
-        .map_err(|npm_error| ProfileRefreshError::AllSourcesFailed {
-            stable: stable_error.to_string(),
-            npm: npm_error.to_string(),
-        })
-}
-
-async fn fetch_latest_cli_version(client: &Client) -> Result<String, ProfileRefreshError> {
-    fetch_latest_with_fallback(
-        || async {
-            let bytes = fetch_bounded(client, CLI_STABLE_CHANNEL_ENDPOINT).await?;
-            parse_stable_channel(&bytes)
-        },
-        || async {
-            let bytes = fetch_bounded(client, CLI_NPM_RELEASE_ENDPOINT).await?;
-            parse_npm_release(&bytes)
-        },
-    )
-    .await
-}
-
-fn publish_version(version: &str) -> Result<(), ProfileRefreshError> {
-    set_xai_client_version(version)
-        .map(|_| ())
-        .map_err(|_| ProfileRefreshError::InvalidMetadata)
-}
-
-async fn restore_cached_profile(runtime: &RuntimeState) -> Result<(), ProfileRefreshError> {
-    let Some(raw) = runtime
-        .kv_get(PROFILE_CACHE_KEY)
-        .await
-        .map_err(|err| ProfileRefreshError::Cache(err.to_string()))?
-    else {
-        return Ok(());
-    };
-    let cached = serde_json::from_str::<CachedProfile>(&raw)
-        .map_err(|_| ProfileRefreshError::InvalidMetadata)?;
-    if let Some(version) = cached_version_to_restore(&cached, &xai_client_version())? {
-        publish_version(&version)?;
-        info!(
-            event_name = "xai_client_profile_restored",
-            version = %version,
-            verified_at_unix_secs = cached.verified_at_unix_secs,
-            "restored cached Grok CLI profile"
-        );
-    }
-    Ok(())
-}
-
-fn cached_version_to_restore(
-    cached: &CachedProfile,
-    active_version: &str,
-) -> Result<Option<String>, ProfileRefreshError> {
-    let cached_sequence = version_sequence(&cached.version)?;
-    let active_sequence = version_sequence(active_version)?;
-    Ok((cached_sequence > active_sequence).then(|| cached.version.clone()))
-}
-
-async fn refresh_once_with_fetch<F, Fut>(
-    runtime: &RuntimeState,
-    fixed_version: Option<&str>,
-    refresh_is_enabled: bool,
-    fetch_latest: F,
-) -> Result<String, ProfileRefreshError>
-where
-    F: FnOnce() -> Fut,
-    Fut: Future<Output = Result<String, ProfileRefreshError>>,
-{
-    if let Some(version) = fixed_version {
-        publish_version(version)?;
-        return Ok(version.to_owned());
-    }
-
-    if let Err(error) = restore_cached_profile(runtime).await {
-        // 缓存损坏或暂时不可用不应阻断官方版本检查；当前进程继续使用旧画像。
-        warn!(
-            event_name = "xai_client_profile_cache_restore_failed",
-            error = %error,
-            "could not restore cached Grok CLI profile"
-        );
-    }
-    if !refresh_is_enabled {
-        return Ok(xai_client_version());
-    }
-
-    let version = fetch_latest().await?;
-    let current = xai_client_version();
-    if version_sequence(&version)? < version_sequence(&current)? {
-        return Err(ProfileRefreshError::Rollback);
-    }
-
-    let cached = CachedProfile {
-        version: version.clone(),
-        verified_at_unix_secs: chrono::Utc::now().timestamp().max(0) as u64,
-    };
-    let serialized =
-        serde_json::to_string(&cached).map_err(|_| ProfileRefreshError::InvalidMetadata)?;
-    publish_version(&version)?;
-    if let Err(error) = runtime
-        .kv_set(PROFILE_CACHE_KEY, serialized, Some(PROFILE_CACHE_TTL))
-        .await
-    {
-        // 本地版本已经完成原子替换；缓存写失败只影响下次进程启动的恢复。
-        warn!(
-            event_name = "xai_client_profile_cache_write_failed",
-            error = %error,
-            "published Grok CLI profile locally but could not persist the cache"
-        );
-    }
-    Ok(version)
-}
-
-async fn refresh_once(runtime: &RuntimeState) -> Result<String, ProfileRefreshError> {
-    let fixed_version = fixed_version_override();
-    refresh_once_with_fetch(
-        runtime,
-        fixed_version.as_deref(),
-        refresh_enabled(),
-        || async {
-            let client = build_release_client()?;
-            fetch_latest_cli_version(&client).await
-        },
-    )
-    .await
-}
-
-pub(crate) async fn prewarm(runtime: &RuntimeState) -> Result<String, String> {
-    refresh_once(runtime).await.map_err(|err| err.to_string())
-}
-
-pub(crate) fn spawn_worker(app: AppState) -> tokio::task::JoinHandle<()> {
-    crate::task_runtime::spawn_singleton_worker(
-        app,
-        crate::task_runtime::TASK_KEY_XAI_CLIENT_PROFILE,
-        |app| async move {
-            let mut interval = tokio::time::interval(PROFILE_REFRESH_INTERVAL);
-            interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Delay);
-            // 启动阶段由 prewarm 完成一次检查；后台任务只负责后续定时刷新，避免重复建连。
-            interval.tick().await;
-            loop {
-                interval.tick().await;
-                match refresh_once(app.runtime_state()).await {
-                    Ok(version) => info!(
-                        event_name = "xai_client_profile_refreshed",
-                        version = %version,
-                        "refreshed Grok CLI profile"
-                    ),
-                    Err(error) => warn!(
-                        event_name = "xai_client_profile_refresh_failed",
-                        error = %error,
-                        "keeping the previous Grok CLI profile after refresh failure"
-                    ),
-                }
-            }
-        },
-    )
-}
-
-#[cfg(test)]
-mod tests {
-    use std::sync::{
-        atomic::{AtomicBool, Ordering},
-        Mutex, OnceLock,
-    };
-    use std::time::Duration;
-
-    use aether_runtime_state::{MemoryRuntimeStateConfig, RuntimeState};
-
-    use super::{
-        cached_version_to_restore, fetch_latest_with_fallback, fixed_version_from,
-        parse_npm_release, parse_stable_channel, refresh_enabled_from, refresh_once_with_fetch,
-        CachedProfile, ProfileRefreshError, PROFILE_CACHE_KEY,
-    };
-    use crate::provider_transport::{set_xai_client_version, xai_client_version};
-
-    static PROFILE_TEST_LOCK: OnceLock<Mutex<()>> = OnceLock::new();
-
-    struct VersionRestore(String);
-
-    impl Drop for VersionRestore {
-        fn drop(&mut self) {
-            let _ = set_xai_client_version(&self.0);
-        }
-    }
-
-    fn version_restore_guard() -> (std::sync::MutexGuard<'static, ()>, VersionRestore) {
-        let lock = PROFILE_TEST_LOCK.get_or_init(|| Mutex::new(()));
-        let guard = lock
-            .lock()
-            .unwrap_or_else(std::sync::PoisonError::into_inner);
-        let restore = VersionRestore(xai_client_version());
-        (guard, restore)
-    }
-
-    fn npm_release(version: &str) -> serde_json::Value {
-        let mut deps = serde_json::Map::new();
-        for target in super::CLI_TARGETS {
-            deps.insert(
-                format!("@xai-official/grok-{target}"),
-                serde_json::Value::String(version.to_string()),
-            );
-        }
-        serde_json::json!({
-            "name": "@xai-official/grok",
-            "version": version,
-            "optionalDependencies": deps,
-        })
-    }
-
-    #[test]
-    fn stable_channel_accepts_only_a_bare_release_version() {
-        assert_eq!(parse_stable_channel(b"1.0.46\n").unwrap(), "1.0.46");
-        assert!(parse_stable_channel(b"<html>1.0.46</html>").is_err());
-        assert!(parse_stable_channel(b"1.0.47-alpha.1").is_err());
-        assert!(parse_stable_channel(b"").is_err());
-    }
-
-    #[test]
-    fn npm_release_requires_every_platform_binary_at_the_same_version() {
-        let body = npm_release("1.0.46");
-        assert_eq!(
-            parse_npm_release(&serde_json::to_vec(&body).unwrap()).unwrap(),
-            "1.0.46"
-        );
-
-        let mut mismatched = npm_release("1.0.46");
-        mismatched["optionalDependencies"]["@xai-official/grok-linux-x64"] =
-            serde_json::Value::String("1.0.45".to_string());
-        assert!(parse_npm_release(&serde_json::to_vec(&mismatched).unwrap()).is_err());
-
-        let mut wrong_package = npm_release("1.0.46");
-        wrong_package["name"] = serde_json::Value::String("grok".to_string());
-        assert!(parse_npm_release(&serde_json::to_vec(&wrong_package).unwrap()).is_err());
-    }
-
-    #[test]
-    fn refresh_and_fixed_version_environment_policies_are_strict() {
-        assert!(!refresh_enabled_from(Some("off")));
-        assert!(!refresh_enabled_from(Some(" FALSE ")));
-        assert!(refresh_enabled_from(None));
-        assert_eq!(
-            fixed_version_from(Some(" 1.0.46 ")).as_deref(),
-            Some("1.0.46")
-        );
-        assert!(fixed_version_from(Some("1.0.46-beta.1")).is_none());
-        assert!(fixed_version_from(Some("1.0")).is_none());
-    }
-
-    #[test]
-    fn cached_profile_never_rewinds_active_profile() {
-        let cached = CachedProfile {
-            version: "1.0.50".to_string(),
-            verified_at_unix_secs: 1,
-        };
-        assert_eq!(
-            cached_version_to_restore(&cached, "1.0.46").unwrap(),
-            Some("1.0.50".to_string())
-        );
-        assert_eq!(cached_version_to_restore(&cached, "1.1.0").unwrap(), None);
-    }
-
-    #[tokio::test]
-    async fn npm_is_used_only_when_the_stable_channel_fails() {
-        let npm_called = AtomicBool::new(false);
-        let version = fetch_latest_with_fallback(
-            || async { Ok("1.0.46".to_string()) },
-            || async {
-                npm_called.store(true, Ordering::SeqCst);
-                Ok("1.0.45".to_string())
-            },
-        )
-        .await
-        .unwrap();
-        assert_eq!(version, "1.0.46");
-        assert!(!npm_called.load(Ordering::SeqCst));
-
-        let version = fetch_latest_with_fallback(
-            || async { Err(ProfileRefreshError::HttpStatus(503)) },
-            || async { Ok("1.0.46".to_string()) },
-        )
-        .await
-        .unwrap();
-        assert_eq!(version, "1.0.46");
-
-        let result = fetch_latest_with_fallback(
-            || async { Err(ProfileRefreshError::HttpStatus(503)) },
-            || async { Err(ProfileRefreshError::InvalidMetadata) },
-        )
-        .await;
-        assert!(matches!(
-            result,
-            Err(ProfileRefreshError::AllSourcesFailed { .. })
-        ));
-    }
-
-    #[tokio::test]
-    async fn cache_hit_is_restored_without_network_when_refresh_is_disabled() {
-        let (_lock, _restore) = version_restore_guard();
-        set_xai_client_version("1.0.46").unwrap();
-        let runtime = RuntimeState::memory(MemoryRuntimeStateConfig::default());
-        runtime
-            .kv_set(
-                PROFILE_CACHE_KEY,
-                serde_json::to_string(&CachedProfile {
-                    version: "1.0.50".to_string(),
-                    verified_at_unix_secs: 1,
-                })
-                .unwrap(),
-                Some(Duration::from_secs(60)),
-            )
-            .await
-            .unwrap();
-
-        let result = refresh_once_with_fetch(&runtime, None, false, || async {
-            Err(ProfileRefreshError::HttpStatus(599))
-        })
-        .await
-        .unwrap();
-
-        assert_eq!(result, "1.0.50");
-        assert_eq!(xai_client_version(), "1.0.50");
-    }
-
-    #[tokio::test]
-    async fn refresh_failure_keeps_previous_profile() {
-        let (_lock, _restore) = version_restore_guard();
-        let runtime = RuntimeState::memory(MemoryRuntimeStateConfig::default());
-        let before = xai_client_version();
-        let result = refresh_once_with_fetch(&runtime, None, true, || async {
-            Err(ProfileRefreshError::HttpStatus(503))
-        })
-        .await;
-
-        assert!(matches!(result, Err(ProfileRefreshError::HttpStatus(503))));
-        assert_eq!(xai_client_version(), before);
-    }
-
-    #[tokio::test]
-    async fn successful_refresh_publishes_and_caches_version() {
-        let (_lock, _restore) = version_restore_guard();
-        set_xai_client_version("1.0.46").unwrap();
-        let runtime = RuntimeState::memory(MemoryRuntimeStateConfig::default());
-        let result =
-            refresh_once_with_fetch(&runtime, None, true, || async { Ok("1.0.51".to_string()) })
-                .await
-                .unwrap();
-
-        assert_eq!(result, "1.0.51");
-        assert_eq!(xai_client_version(), "1.0.51");
-        let cached = runtime.kv_get(PROFILE_CACHE_KEY).await.unwrap().unwrap();
-        assert!(cached.contains("\"1.0.51\""));
-    }
-
-    #[tokio::test]
-    async fn fixed_version_override_skips_network_and_publishes_version() {
-        let (_lock, _restore) = version_restore_guard();
-        let runtime = RuntimeState::memory(MemoryRuntimeStateConfig::default());
-        let fetch_called = AtomicBool::new(false);
-        let result = refresh_once_with_fetch(&runtime, Some("1.0.60"), true, || async {
-            fetch_called.store(true, Ordering::SeqCst);
-            Ok("1.0.61".to_string())
-        })
-        .await
-        .unwrap();
-
-        assert_eq!(result, "1.0.60");
-        assert!(!fetch_called.load(Ordering::SeqCst));
-        assert_eq!(xai_client_version(), "1.0.60");
-    }
-
-    #[tokio::test]
-    async fn rollback_is_rejected_without_replacing_profile() {
-        let (_lock, _restore) = version_restore_guard();
-        set_xai_client_version("1.0.60").unwrap();
-        let runtime = RuntimeState::memory(MemoryRuntimeStateConfig::default());
-        let result =
-            refresh_once_with_fetch(&runtime, None, true, || async { Ok("1.0.59".to_string()) })
-                .await;
-
-        assert!(matches!(result, Err(ProfileRefreshError::Rollback)));
-        assert_eq!(xai_client_version(), "1.0.60");
-    }
-}

crates/aether-ai/formats/src/client_profile.rs

@@ -0,0 +1,67 @@
+//! Immutable client identity snapshots shared by provider adapters.
+use std::sync::{Arc, RwLock};
+
+/// Readers release the lock before constructing a request. Publishing never
+/// changes snapshots already held by an in-flight request.
+#[derive(Debug)]
+pub struct ClientProfileStore<T> {
+    current: RwLock<Arc<T>>,
+}
+
+impl<T> ClientProfileStore<T> {
+    pub fn new(profile: T) -> Self {
+        Self {
+            current: RwLock::new(Arc::new(profile)),
+        }
+    }
+
+    pub fn snapshot(&self) -> Arc<T> {
+        self.current
+            .read()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+            .clone()
+    }
+
+    pub fn publish(&self, profile: T) -> Arc<T> {
+        let mut current = self
+            .current
+            .write()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        std::mem::replace(&mut *current, Arc::new(profile))
+    }
+}
+
+/// Constructors validate wire safety; release adapters separately validate
+/// official stable semantic versions before publishing them.
+pub fn validate_client_version(version: &str) -> Result<&str, &'static str> {
+    let version = version.trim();
+    if version.is_empty() || version.len() > 64 || !version.bytes().all(|b| (33..=126).contains(&b))
+    {
+        return Err("invalid client version");
+    }
+    Ok(version)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn publishing_does_not_mutate_inflight_snapshots() {
+        let store = ClientProfileStore::new(("1.0.0", "client/1.0.0"));
+        let inflight = store.snapshot();
+        let old = store.publish(("1.1.0", "client/1.1.0"));
+        assert_eq!(inflight, old);
+        assert_eq!(inflight.0, "1.0.0");
+        assert_eq!(store.snapshot().1, "client/1.1.0");
+    }
+
+    #[test]
+    fn rejects_header_injection_and_oversized_versions() {
+        for version in ["", "1.0\r\nx: y", "1.0 0", "é"] {
+            assert!(validate_client_version(version).is_err());
+        }
+        assert!(validate_client_version(&"1".repeat(65)).is_err());
+        assert_eq!(validate_client_version(" 1.0.0 ").unwrap(), "1.0.0");
+    }
+}

crates/aether-ai/formats/src/codex_profile.rs

@@ -1,4 +1,6 @@
-use std::sync::{LazyLock, OnceLock, RwLock};
+use std::sync::{LazyLock, OnceLock};
+
+use crate::client_profile::ClientProfileStore;
 
 static OS_INFO: LazyLock<os_info::Info> = LazyLock::new(os_info::get);
 
@@ -59,26 +61,20 @@ impl Default for CodexClientProfile {
     }
 }
 
-static ACTIVE_PROFILE: OnceLock<RwLock<CodexClientProfile>> = OnceLock::new();
+static ACTIVE_PROFILE: OnceLock<ClientProfileStore<CodexClientProfile>> = OnceLock::new();
 
-fn active_profile() -> &'static RwLock<CodexClientProfile> {
-    ACTIVE_PROFILE.get_or_init(|| RwLock::new(CodexClientProfile::default()))
+fn active_profile() -> &'static ClientProfileStore<CodexClientProfile> {
+    ACTIVE_PROFILE.get_or_init(|| ClientProfileStore::new(CodexClientProfile::default()))
 }
 
 /// 返回当前画像的独立快照，调用方不会持有全局锁。
 pub fn codex_client_profile() -> CodexClientProfile {
-    active_profile()
-        .read()
-        .unwrap_or_else(std::sync::PoisonError::into_inner)
-        .clone()
+    (*active_profile().snapshot()).clone()
 }
 
 /// 原子替换当前画像，并返回替换前的画像。
 pub fn set_codex_client_profile(profile: CodexClientProfile) -> CodexClientProfile {
-    let mut current = active_profile()
-        .write()
-        .unwrap_or_else(std::sync::PoisonError::into_inner);
-    std::mem::replace(&mut *current, profile)
+    (*active_profile().publish(profile)).clone()
 }
 
 /// 发布一份新的 CLI 画像。

crates/aether-ai/formats/src/lib.rs

@@ -1,6 +1,7 @@
 extern crate self as aether_ai_formats;
 
 pub mod api;
+pub mod client_profile;
 pub mod codex_profile;
 pub mod contracts;
 pub mod formats;

crates/aether-model-fetch/src/transport.rs

@@ -27,8 +27,6 @@ use crate::{
     build_models_fetch_url_for_client_version, deepseek_anthropic_models_fetch_uses_openai_auth,
 };
 
-const CLAUDE_CLI_USER_AGENT: &str = "claude-code/1.0.1";
-const GEMINI_CLI_USER_AGENT: &str = "GeminiCLI/0.1.5 (Windows; AMD64)";
 const CLAUDE_VERSION_HEADER: &str = "2023-06-01";
 const ANTIGRAVITY_FETCH_PROVIDER_API_FORMAT: &str = "antigravity:fetch_available_models";
 const ANTIGRAVITY_LOAD_CODE_ASSIST_PROVIDER_API_FORMAT: &str = "antigravity:load_code_assist";
@@ -37,7 +35,7 @@ const KIRO_LIST_AVAILABLE_MODELS_PROVIDER_API_FORMAT: &str = "kiro:list_availabl
 const WINDSURF_MODEL_CONFIGS_PROVIDER_API_FORMAT: &str = "windsurf:model_configs";
 const WINDSURF_MODEL_CONFIGS_PATH: &str =
     "/exa.api_server_pb.ApiServerService/GetCascadeModelConfigs";
-const WINDSURF_IDE_VERSION: &str = "1.9600.41";
+const WINDSURF_IDE_VERSION: &str = aether_provider_transport::client_identity::WINDSURF.version;
 
 const BROWSER_FINGERPRINT_HEADERS: &[(&str, &str)] = &[
     (
@@ -319,7 +317,10 @@ pub async fn build_gemini_cli_load_code_assist_plan(
         .ok_or_else(|| "GeminiCLI loadCodeAssist requires bearer or OAuth auth".to_string())?;
 
     let mut headers = BTreeMap::from([
-        ("user-agent".to_string(), GEMINI_CLI_USER_AGENT.to_string()),
+        (
+            "user-agent".to_string(),
+            aether_provider_transport::gemini_cli::gemini_cli_client_user_agent(),
+        ),
         ("accept-encoding".to_string(), "identity".to_string()),
         ("content-type".to_string(), "application/json".to_string()),
     ]);
@@ -662,8 +663,19 @@ fn standard_models_fetch_headers(
                 "anthropic-version".to_string(),
                 CLAUDE_VERSION_HEADER.to_string(),
             )]);
-            if matches!(provider_type.as_str(), "claude_code" | "kiro") {
-                headers.insert("user-agent".to_string(), CLAUDE_CLI_USER_AGENT.to_string());
+            if provider_type == "claude_code" {
+                headers.insert(
+                    "user-agent".to_string(),
+                    aether_provider_transport::claude_code::claude_code_client_profile()
+                        .user_agent
+                        .clone(),
+                );
+            } else if provider_type == "kiro" {
+                headers.insert(
+                    "user-agent".to_string(),
+                    aether_provider_transport::client_identity::KIRO_MODELS_LEGACY_USER_AGENT
+                        .to_string(),
+                );
             }
             headers
         }
@@ -673,7 +685,10 @@ fn standard_models_fetch_headers(
                 .map(|(key, value)| (key.to_string(), value.to_string()))
                 .collect::<BTreeMap<_, _>>();
             if provider_type == "gemini_cli" {
-                headers.insert("user-agent".to_string(), GEMINI_CLI_USER_AGENT.to_string());
+                headers.insert(
+                    "user-agent".to_string(),
+                    aether_provider_transport::gemini_cli::gemini_cli_client_user_agent(),
+                );
             }
             headers
         }

crates/aether-provider/pool/src/providers/chatgpt_web.rs

@@ -20,11 +20,10 @@ use crate::quota_refresh::ProviderPoolQuotaRequestSpec;
 pub const CHATGPT_WEB_DEFAULT_BASE_URL: &str = "https://chatgpt.com";
 pub const CHATGPT_WEB_CONVERSATION_INIT_PATH: &str = "/backend-api/conversation/init";
 
-const CHATGPT_WEB_USER_AGENT: &str = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36 Edg/143.0.0.0";
-const CHATGPT_WEB_CLIENT_VERSION: &str = "prod-be885abbfcfe7b1f511e88b3003d9ee44757fbad";
-const CHATGPT_WEB_BUILD_NUMBER: &str = "5955942";
-const CHATGPT_WEB_SEC_CH_UA: &str =
-    r#""Microsoft Edge";v="143", "Chromium";v="143", "Not A(Brand";v="24""#;
+use aether_provider_transport::client_identity::{
+    CHATGPT_WEB_BUILD_NUMBER, CHATGPT_WEB_CLIENT_VERSION, CHATGPT_WEB_SEC_CH_UA,
+    CHATGPT_WEB_USER_AGENT,
+};
 #[derive(Debug, Clone, Default)]
 pub struct ChatGptWebProviderPoolAdapter;
 

crates/aether-provider/pool/src/providers/claude_code.rs

@@ -11,7 +11,6 @@ use crate::quota_refresh::ProviderPoolQuotaRequestSpec;
 pub const CLAUDE_CODE_OAUTH_USAGE_URL: &str =
     "https://api.anthropic.com/api/oauth/usage?cedar_ember=1&skip_spend=1";
 pub const CLAUDE_CODE_OAUTH_BETA: &str = "oauth-2025-04-20";
-pub const CLAUDE_CODE_USAGE_USER_AGENT: &str = "claude-cli/2.1.284 (external, cli)";
 
 #[derive(Debug, Clone, Default)]
 pub struct ClaudeCodeProviderPoolAdapter;
@@ -62,7 +61,7 @@ pub fn build_claude_code_pool_quota_request(
         ("x-app".to_string(), "cli".to_string()),
         (
             "user-agent".to_string(),
-            CLAUDE_CODE_USAGE_USER_AGENT.to_string(),
+            aether_provider_transport::claude_code::claude_code_client_user_agent(),
         ),
     ]);
 

crates/aether-provider/pool/src/providers/gemini_cli.rs

@@ -10,7 +10,7 @@ use crate::provider::{
 use crate::quota_refresh::ProviderPoolQuotaRequestSpec;
 
 pub const GEMINI_CLI_RETRIEVE_USER_QUOTA_PATH: &str = "/v1internal:retrieveUserQuota";
-pub const GEMINI_CLI_USER_AGENT: &str = "GeminiCLI/0.1.5 (Windows; AMD64)";
+pub use aether_provider_transport::gemini_cli::GEMINI_CLI_USER_AGENT;
 
 #[derive(Debug, Clone, Default)]
 pub struct GeminiCliProviderPoolAdapter;
@@ -52,7 +52,10 @@ pub fn build_gemini_cli_pool_quota_request(
         ("authorization".to_string(), authorization.1),
         ("content-type".to_string(), "application/json".to_string()),
         ("accept".to_string(), "application/json".to_string()),
-        ("user-agent".to_string(), GEMINI_CLI_USER_AGENT.to_string()),
+        (
+            "user-agent".to_string(),
+            aether_provider_transport::gemini_cli::gemini_cli_client_user_agent(),
+        ),
     ]);
 
     ProviderPoolQuotaRequestSpec {

crates/aether-provider/pool/src/providers/kiro.rs

@@ -158,7 +158,7 @@ fn normalize_region(value: &str) -> &str {
 fn normalize_kiro_version(value: &str) -> &str {
     let value = value.trim();
     if value.is_empty() {
-        "0.3.210"
+        aether_provider_transport::client_identity::DEFAULT_KIRO_VERSION
     } else {
         value
     }

crates/aether-provider/pool/src/providers/mod.rs

@@ -24,7 +24,6 @@ pub use chatgpt_web::{
 pub use claude_code::ClaudeCodeProviderPoolAdapter;
 pub use claude_code::{
     build_claude_code_pool_quota_request, CLAUDE_CODE_OAUTH_BETA, CLAUDE_CODE_OAUTH_USAGE_URL,
-    CLAUDE_CODE_USAGE_USER_AGENT,
 };
 pub use codex::CodexProviderPoolAdapter;
 pub use codex::{

crates/aether-provider/pool/src/providers/windsurf.rs

@@ -177,7 +177,12 @@ fn build_windsurf_connect_rpc_request(
     headers.insert("content-type".to_string(), "application/json".to_string());
     headers.insert("accept".to_string(), "application/json".to_string());
     headers.insert("connect-protocol-version".to_string(), "1".to_string());
-    headers.insert("user-agent".to_string(), "windsurf/1.9600.41".to_string());
+    headers.insert(
+        "user-agent".to_string(),
+        aether_provider_transport::client_identity::WINDSURF
+            .user_agent
+            .to_string(),
+    );
 
     ProviderPoolQuotaRequestSpec {
         request_id,
@@ -200,9 +205,9 @@ fn windsurf_metadata(api_key: &str) -> Value {
     json!({
         "apiKey": api_key,
         "ideName": "windsurf",
-        "ideVersion": "1.9600.41",
+        "ideVersion": aether_provider_transport::client_identity::WINDSURF.version,
         "extensionName": "windsurf",
-        "extensionVersion": "1.9600.41",
+        "extensionVersion": aether_provider_transport::client_identity::WINDSURF.version,
         "locale": "en",
     })
 }

crates/aether-provider/transport/src/agent_identity.rs

@@ -769,6 +769,7 @@ async fn register_codex_agent_identity_from_access_token_with_auth_api_base_url(
         .map_err(|_| CodexAgentIdentityEnrollmentError::KeyGenerationFailed)?;
     let agent_private_key = STANDARD.encode(private_key_der.as_bytes());
     let agent_public_key = agent_identity_ssh_public_key(&signing_key);
+    let client_profile = aether_ai_formats::codex_client_profile();
     let registration_url = agent_registration_url(auth_api_base_url)
         .map_err(|_| CodexAgentIdentityEnrollmentError::RegistrationRequestFailed)?;
     let mut headers = BTreeMap::from([
@@ -778,14 +779,8 @@ async fn register_codex_agent_identity_from_access_token_with_auth_api_base_url(
             "authorization".to_string(),
             format!("Bearer {access_token}"),
         ),
-        (
-            "user-agent".to_string(),
-            aether_ai_formats::codex_client_user_agent(),
-        ),
-        (
-            "originator".to_string(),
-            aether_ai_formats::codex_client_originator(),
-        ),
+        ("user-agent".to_string(), client_profile.user_agent.clone()),
+        ("originator".to_string(), client_profile.originator.clone()),
     ]);
     if options.is_fedramp_account {
         headers.insert("x-openai-fedramp".to_string(), "true".to_string());
@@ -799,7 +794,7 @@ async fn register_codex_agent_identity_from_access_token_with_auth_api_base_url(
             content_type: Some("application/json".to_string()),
             json_body: Some(json!({
                 "abom": {
-                    "agent_version": aether_ai_formats::codex_client_version(),
+                    "agent_version": client_profile.codex_version,
                     "agent_harness_id": CODEX_AGENT_IDENTITY_AGENT_HARNESS_ID,
                     "running_location": format!("cli-{}", std::env::consts::OS),
                 },

crates/aether-provider/transport/src/antigravity/auth.rs

@@ -5,8 +5,8 @@ use serde_json::Value;
 use super::super::snapshot::GatewayProviderTransportSnapshot;
 
 pub const ANTIGRAVITY_PROVIDER_TYPE: &str = "antigravity";
-pub const ANTIGRAVITY_CLIENT_VERSION: &str = "4.3.0";
-pub const ANTIGRAVITY_REQUEST_USER_AGENT: &str = "vscode/1.X.X (Antigravity/4.3.0)";
+pub const ANTIGRAVITY_CLIENT_VERSION: &str = crate::client_identity::ANTIGRAVITY.version;
+pub const ANTIGRAVITY_REQUEST_USER_AGENT: &str = crate::client_identity::ANTIGRAVITY.user_agent;
 const ANTIGRAVITY_CLIENT_NAME: &str = "antigravity";
 const ANTIGRAVITY_GOOG_API_CLIENT: &str = "gl-node/18.18.2 fire/0.8.6 grpc/1.10.x";
 

crates/aether-provider/transport/src/claude_code/fingerprint.rs

@@ -14,7 +14,7 @@ pub fn generate_fingerprint(seed: &str) -> Value {
 }
 
 fn generate_header_fingerprint(seed: &str) -> Value {
-    let profile = *current_claude_code_transport_identity_profile();
+    let profile = current_claude_code_transport_identity_profile();
     let vscode_session_id = Uuid::new_v5(
         &Uuid::NAMESPACE_URL,
         format!("aether:fingerprint:{seed}").as_bytes(),
@@ -40,7 +40,7 @@ fn generate_header_fingerprint(seed: &str) -> Value {
 }
 
 fn wrap_header_fingerprint(header_fingerprint: Value) -> Value {
-    let profile = *current_claude_code_transport_identity_profile();
+    let profile = current_claude_code_transport_identity_profile();
     serde_json::json!({
         "transport_profile": {
             "profile_id": profile.transport_profile_id(),

crates/aether-provider/transport/src/claude_code/mimicry.rs

@@ -103,7 +103,7 @@ pub fn apply_claude_code_body_mimicry(
         return false;
     }
 
-    let profile = *current_claude_code_transport_identity_profile();
+    let profile = current_claude_code_transport_identity_profile();
     let model = object
         .get("model")
         .and_then(Value::as_str)

crates/aether-provider/transport/src/claude_code/mod.rs

@@ -20,12 +20,15 @@ pub use policy::{
     supports_local_claude_code_transport_with_network,
 };
 pub use profile::{
-    current_claude_code_transport_identity_profile, ClaudeCodeBodyCapabilityGate,
+    claude_code_client_profile, claude_code_client_user_agent, claude_code_client_version,
+    current_claude_code_transport_identity_profile, set_claude_code_cli_version,
+    set_claude_code_client_profile, ClaudeCodeBodyCapabilityGate, ClaudeCodeClientProfile,
     ClaudeCodeTransportIdentityProfile, ClaudeCodeTransportIdentityProfileVersion,
+    ClaudeCodeTransportIdentityTemplate, CLAUDE_CODE_BUILTIN_CLI_VERSION,
     CLAUDE_CODE_CONTEXT_MANAGEMENT_BETA, CLAUDE_CODE_TRANSPORT_IDENTITY_2026_04,
 };
 pub use request::{
-    build_claude_code_passthrough_headers, sanitize_claude_code_request_body,
-    sanitize_claude_code_request_body_for_beta_header,
+    build_claude_code_passthrough_headers, finalize_claude_code_request_identity,
+    sanitize_claude_code_request_body, sanitize_claude_code_request_body_for_beta_header,
 };
 pub use url::build_claude_code_messages_url;

crates/aether-provider/transport/src/claude_code/profile.rs

@@ -1,9 +1,16 @@
 use std::collections::{BTreeMap, BTreeSet};
+use std::sync::{Arc, OnceLock};
+
+use aether_ai_formats::client_profile::ClientProfileStore;
 
 use aether_ai_formats::ApiOperation;
 
 pub const CLAUDE_CODE_CONTEXT_MANAGEMENT_BETA: &str = "context-management-2025-06-27";
 
+/// Built-in Claude Code CLI version used until the gateway publishes a newer
+/// verified release (or when release checks are disabled / unavailable).
+pub const CLAUDE_CODE_BUILTIN_CLI_VERSION: &str = "2.1.284";
+
 const MESSAGE_BETAS_2026_04: &[&str] = &[
     "claude-code-20250219",
     "oauth-2025-04-20",
@@ -53,15 +60,89 @@ pub struct ClaudeCodeBodyCapabilityGate {
     pub default_edit_type: Option<&'static str>,
 }
 
-/// Versioned upstream identity used when Aether is intentionally acting as a
-/// Claude Code transport. Native Anthropic transports never resolve this
-/// profile and therefore keep their original headers and body untouched.
+/// Dynamic Claude Code CLI identity (version-derived wire values).
+///
+/// The gateway refreshes this from verified official releases in a background
+/// task; request paths only read an immutable snapshot and never touch the
+/// network.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ClaudeCodeClientProfile {
+    pub cli_version: String,
+    pub user_agent: String,
+}
+
+impl ClaudeCodeClientProfile {
+    /// Builds a CLI profile from a release version. Release verification is owned
+    /// by the release checker; the constructor only rejects clearly invalid values.
+    pub fn cli(version: &str) -> Result<Self, &'static str> {
+        let version = version.trim();
+        if version.is_empty()
+            || version.len() > 64
+            || !version.bytes().all(|byte| (33..=126).contains(&byte))
+        {
+            return Err("invalid Claude Code CLI version");
+        }
+        Ok(Self {
+            cli_version: version.to_owned(),
+            user_agent: format!("claude-cli/{version} (external, cli)"),
+        })
+    }
+}
+
+impl Default for ClaudeCodeClientProfile {
+    fn default() -> Self {
+        Self::cli(CLAUDE_CODE_BUILTIN_CLI_VERSION)
+            .expect("built-in Claude Code CLI profile must be valid")
+    }
+}
+
+static ACTIVE_CLIENT_PROFILE: OnceLock<ClientProfileStore<ClaudeCodeClientProfile>> =
+    OnceLock::new();
+
+fn active_client_profile() -> &'static ClientProfileStore<ClaudeCodeClientProfile> {
+    ACTIVE_CLIENT_PROFILE
+        .get_or_init(|| ClientProfileStore::new(ClaudeCodeClientProfile::default()))
+}
+
+/// Returns a snapshot of the active CLI profile without holding the global lock.
+pub fn claude_code_client_profile() -> Arc<ClaudeCodeClientProfile> {
+    active_client_profile().snapshot()
+}
+
+/// Atomically replaces the active CLI profile and returns the previous one.
+pub fn set_claude_code_client_profile(
+    profile: ClaudeCodeClientProfile,
+) -> Arc<ClaudeCodeClientProfile> {
+    active_client_profile().publish(profile)
+}
+
+/// Publishes a CLI profile for the given release version.
+pub fn set_claude_code_cli_version(
+    version: &str,
+) -> Result<Arc<ClaudeCodeClientProfile>, &'static str> {
+    let profile = ClaudeCodeClientProfile::cli(version)?;
+    Ok(set_claude_code_client_profile(profile))
+}
+
+/// Returns the active Claude Code CLI version.
+pub fn claude_code_client_version() -> String {
+    claude_code_client_profile().cli_version.clone()
+}
+
+/// Returns the active Claude Code CLI User-Agent.
+pub fn claude_code_client_user_agent() -> String {
+    claude_code_client_profile().user_agent.clone()
+}
+
+/// Versioned, static part of the Claude Code transport identity: Stainless SDK
+/// and runtime values, beta policy and body capability gates. These values are
+/// calibrated together and change only with a new template version; the CLI
+/// version itself is supplied by the dynamic [`ClaudeCodeClientProfile`].
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub struct ClaudeCodeTransportIdentityProfile {
+pub struct ClaudeCodeTransportIdentityTemplate {
     version: ClaudeCodeTransportIdentityProfileVersion,
     transport_profile_id: &'static str,
     anthropic_version: &'static str,
-    cli_version: &'static str,
     stainless_lang: &'static str,
     stainless_package_version: &'static str,
     stainless_os: &'static str,
@@ -77,12 +158,11 @@ pub struct ClaudeCodeTransportIdentityProfile {
     body_capability_gates: &'static [ClaudeCodeBodyCapabilityGate],
 }
 
-pub const CLAUDE_CODE_TRANSPORT_IDENTITY_2026_04: ClaudeCodeTransportIdentityProfile =
-    ClaudeCodeTransportIdentityProfile {
+pub const CLAUDE_CODE_TRANSPORT_IDENTITY_2026_04: ClaudeCodeTransportIdentityTemplate =
+    ClaudeCodeTransportIdentityTemplate {
         version: ClaudeCodeTransportIdentityProfileVersion::V2026_04,
         transport_profile_id: "claude_code_nodejs",
         anthropic_version: "2023-06-01",
-        cli_version: "2.1.284",
         stainless_lang: "js",
         stainless_package_version: "0.112.1",
         stainless_os: "Linux",
@@ -98,115 +178,144 @@ pub const CLAUDE_CODE_TRANSPORT_IDENTITY_2026_04: ClaudeCodeTransportIdentityPro
         body_capability_gates: BODY_CAPABILITY_GATES_2026_04,
     };
 
-pub const fn current_claude_code_transport_identity_profile(
-) -> &'static ClaudeCodeTransportIdentityProfile {
-    &CLAUDE_CODE_TRANSPORT_IDENTITY_2026_04
+/// Upstream identity used when Aether is intentionally acting as a Claude Code
+/// transport. Native Anthropic transports never resolve this profile and
+/// therefore keep their original headers and body untouched.
+///
+/// Each value is one coherent snapshot of the static template plus the active
+/// CLI profile, so headers and billing attribution derived from the same
+/// snapshot always agree on the CLI version.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ClaudeCodeTransportIdentityProfile {
+    template: &'static ClaudeCodeTransportIdentityTemplate,
+    client: Arc<ClaudeCodeClientProfile>,
+}
+
+pub fn current_claude_code_transport_identity_profile() -> ClaudeCodeTransportIdentityProfile {
+    ClaudeCodeTransportIdentityProfile::new(
+        &CLAUDE_CODE_TRANSPORT_IDENTITY_2026_04,
+        claude_code_client_profile(),
+    )
 }
 
 impl ClaudeCodeTransportIdentityProfile {
-    pub const fn version(self) -> ClaudeCodeTransportIdentityProfileVersion {
-        self.version
+    pub fn new(
+        template: &'static ClaudeCodeTransportIdentityTemplate,
+        client: Arc<ClaudeCodeClientProfile>,
+    ) -> Self {
+        Self { template, client }
     }
 
-    pub const fn transport_profile_id(self) -> &'static str {
-        self.transport_profile_id
+    pub fn version(&self) -> ClaudeCodeTransportIdentityProfileVersion {
+        self.template.version
     }
 
-    pub const fn cli_version(self) -> &'static str {
-        self.cli_version
+    pub fn transport_profile_id(&self) -> &'static str {
+        self.template.transport_profile_id
     }
 
-    pub const fn billing_cli_version(self) -> &'static str {
-        self.cli_version
+    pub fn cli_version(&self) -> &str {
+        &self.client.cli_version
     }
 
-    pub fn user_agent(self) -> String {
-        format!("claude-cli/{} (external, cli)", self.cli_version)
+    pub fn billing_cli_version(&self) -> &str {
+        &self.client.cli_version
     }
 
-    pub const fn stainless_package_version(self) -> &'static str {
-        self.stainless_package_version
+    pub fn user_agent(&self) -> &str {
+        &self.client.user_agent
     }
 
-    pub const fn stainless_lang(self) -> &'static str {
-        self.stainless_lang
+    pub fn stainless_package_version(&self) -> &'static str {
+        self.template.stainless_package_version
     }
 
-    pub const fn stainless_os(self) -> &'static str {
-        self.stainless_os
+    pub fn stainless_lang(&self) -> &'static str {
+        self.template.stainless_lang
     }
 
-    pub const fn stainless_arch(self) -> &'static str {
-        self.stainless_arch
+    pub fn stainless_os(&self) -> &'static str {
+        self.template.stainless_os
     }
 
-    pub const fn stainless_runtime(self) -> &'static str {
-        self.stainless_runtime
+    pub fn stainless_arch(&self) -> &'static str {
+        self.template.stainless_arch
     }
 
-    pub const fn stainless_runtime_version(self) -> &'static str {
-        self.stainless_runtime_version
+    pub fn stainless_runtime(&self) -> &'static str {
+        self.template.stainless_runtime
     }
 
-    pub const fn stainless_retry_count(self) -> &'static str {
-        self.stainless_retry_count
+    pub fn stainless_runtime_version(&self) -> &'static str {
+        self.template.stainless_runtime_version
     }
 
-    pub const fn stainless_timeout(self) -> &'static str {
-        self.stainless_timeout
+    pub fn stainless_retry_count(&self) -> &'static str {
+        self.template.stainless_retry_count
     }
 
-    pub fn required_beta_tokens(self, operation: Option<ApiOperation>) -> &'static [&'static str] {
+    pub fn stainless_timeout(&self) -> &'static str {
+        self.template.stainless_timeout
+    }
+
+    pub fn required_beta_tokens(&self, operation: Option<ApiOperation>) -> &'static [&'static str] {
         if operation == Some(ApiOperation::ClaudeCountTokens) {
-            self.count_tokens_required_betas
+            self.template.count_tokens_required_betas
         } else {
-            self.message_required_betas
+            self.template.message_required_betas
         }
     }
 
-    pub const fn preserves_incoming_betas(self) -> bool {
-        self.preserve_incoming_betas
+    pub fn preserves_incoming_betas(&self) -> bool {
+        self.template.preserve_incoming_betas
     }
 
-    pub const fn dropped_beta_tokens(self) -> &'static [&'static str] {
-        self.dropped_betas
+    pub fn dropped_beta_tokens(&self) -> &'static [&'static str] {
+        self.template.dropped_betas
     }
 
-    pub const fn body_capability_gates(self) -> &'static [ClaudeCodeBodyCapabilityGate] {
-        self.body_capability_gates
+    pub fn body_capability_gates(&self) -> &'static [ClaudeCodeBodyCapabilityGate] {
+        self.template.body_capability_gates
     }
 
-    pub fn body_capability_gate(self, field: &str) -> Option<ClaudeCodeBodyCapabilityGate> {
-        self.body_capability_gates
+    pub fn body_capability_gate(&self, field: &str) -> Option<ClaudeCodeBodyCapabilityGate> {
+        self.template
+            .body_capability_gates
             .iter()
             .copied()
             .find(|gate| gate.body_field == field)
     }
 
-    pub fn apply_fixed_headers(self, headers: &mut BTreeMap<String, String>, stream: bool) {
+    pub fn apply_fixed_headers(&self, headers: &mut BTreeMap<String, String>, stream: bool) {
+        let template = self.template;
         for (name, value) in [
             ("accept", "application/json"),
-            ("anthropic-version", self.anthropic_version),
+            ("anthropic-version", template.anthropic_version),
             ("anthropic-dangerous-direct-browser-access", "true"),
             ("x-app", "cli"),
-            ("x-stainless-lang", self.stainless_lang),
+            ("x-stainless-lang", template.stainless_lang),
             (
                 "x-stainless-package-version",
-                self.stainless_package_version,
+                template.stainless_package_version,
             ),
-            ("x-stainless-os", self.stainless_os),
-            ("x-stainless-arch", self.stainless_arch),
-            ("x-stainless-runtime", self.stainless_runtime),
+            ("x-stainless-os", template.stainless_os),
+            ("x-stainless-arch", template.stainless_arch),
+            ("x-stainless-runtime", template.stainless_runtime),
             (
                 "x-stainless-runtime-version",
-                self.stainless_runtime_version,
+                template.stainless_runtime_version,
             ),
-            ("x-stainless-retry-count", self.stainless_retry_count),
-            ("x-stainless-timeout", self.stainless_timeout),
+            ("x-stainless-retry-count", template.stainless_retry_count),
+            ("x-stainless-timeout", template.stainless_timeout),
         ] {
+            headers.retain(|existing, _| !existing.eq_ignore_ascii_case(name));
             headers.insert(name.to_string(), value.to_string());
         }
-        headers.insert("user-agent".to_string(), self.user_agent());
+        headers.retain(|name, _| {
+            !name.eq_ignore_ascii_case("user-agent")
+                && !name.eq_ignore_ascii_case("x-stainless-helper-method")
+        });
+        headers.insert("user-agent".to_string(), self.user_agent().to_string());
         if stream {
             headers.insert(
                 "x-stainless-helper-method".to_string(),
@@ -218,12 +327,18 @@ impl ClaudeCodeTransportIdentityProfile {
     }
 
     pub fn apply_beta_policy(
-        self,
+        &self,
         headers: &mut BTreeMap<String, String>,
         operation: Option<ApiOperation>,
     ) {
-        let incoming = headers.get("anthropic-beta").map(String::as_str);
-        let merged = self.merge_beta_tokens(incoming, operation);
+        let incoming = headers
+            .iter()
+            .filter(|(name, _)| name.eq_ignore_ascii_case("anthropic-beta"))
+            .map(|(_, value)| value.as_str())
+            .collect::<Vec<_>>()
+            .join(",");
+        let merged = self.merge_beta_tokens(Some(&incoming), operation);
+        headers.retain(|name, _| !name.eq_ignore_ascii_case("anthropic-beta"));
         if merged.is_empty() {
             headers.remove("anthropic-beta");
         } else {
@@ -232,7 +347,7 @@ impl ClaudeCodeTransportIdentityProfile {
     }
 
     pub fn merge_beta_tokens(
-        self,
+        &self,
         incoming: Option<&str>,
         operation: Option<ApiOperation>,
     ) -> String {
@@ -242,7 +357,7 @@ impl ClaudeCodeTransportIdentityProfile {
         for token in self.required_beta_tokens(operation) {
             self.append_beta_token(&mut seen, &mut merged, token);
         }
-        if self.preserve_incoming_betas {
+        if self.template.preserve_incoming_betas {
             for token in incoming.unwrap_or_default().split(',') {
                 self.append_beta_token(&mut seen, &mut merged, token);
             }
@@ -250,7 +365,7 @@ impl ClaudeCodeTransportIdentityProfile {
         merged.join(",")
     }
 
-    pub fn beta_header_enables_body_field(self, beta_header: &str, field: &str) -> bool {
+    pub fn beta_header_enables_body_field(&self, beta_header: &str, field: &str) -> bool {
         let Some(gate) = self.body_capability_gate(field) else {
             return true;
         };
@@ -260,10 +375,16 @@ impl ClaudeCodeTransportIdentityProfile {
             .any(|token| token.eq_ignore_ascii_case(gate.beta_token))
     }
 
-    fn append_beta_token(self, seen: &mut BTreeSet<String>, merged: &mut Vec<String>, token: &str) {
+    fn append_beta_token(
+        &self,
+        seen: &mut BTreeSet<String>,
+        merged: &mut Vec<String>,
+        token: &str,
+    ) {
         let token = token.trim();
         if token.is_empty()
             || self
+                .template
                 .dropped_betas
                 .iter()
                 .any(|dropped| token.eq_ignore_ascii_case(dropped))
@@ -278,12 +399,17 @@ impl ClaudeCodeTransportIdentityProfile {
 
 #[cfg(test)]
 mod tests {
-    use super::current_claude_code_transport_identity_profile;
+    use std::sync::Arc;
+
+    use super::{
+        current_claude_code_transport_identity_profile, ClaudeCodeClientProfile,
+        ClaudeCodeTransportIdentityProfile, CLAUDE_CODE_TRANSPORT_IDENTITY_2026_04,
+    };
     use aether_ai_formats::ApiOperation;
 
     #[test]
     fn profile_versions_cli_user_agent_stainless_and_billing_together() {
-        let profile = *current_claude_code_transport_identity_profile();
+        let profile = current_claude_code_transport_identity_profile();
 
         assert_eq!(profile.version().as_str(), "2026-04");
         assert_eq!(profile.cli_version(), "2.1.284");
@@ -296,9 +422,43 @@ mod tests {
         assert_eq!(profile.stainless_runtime_version(), "v26.3.0");
     }
 
+    #[test]
+    fn cli_profile_derives_wire_identity_from_version() {
+        let client = ClaudeCodeClientProfile::cli(" 2.1.300 ").expect("valid version");
+        assert_eq!(client.cli_version, "2.1.300");
+        assert_eq!(client.user_agent, "claude-cli/2.1.300 (external, cli)");
+
+        // A snapshot keeps headers and billing attribution on the same CLI version
+        // without mutating the process-wide active profile.
+        let profile = ClaudeCodeTransportIdentityProfile::new(
+            &CLAUDE_CODE_TRANSPORT_IDENTITY_2026_04,
+            Arc::new(client),
+        );
+        let mut headers = std::collections::BTreeMap::new();
+        profile.apply_fixed_headers(&mut headers, false);
+        assert_eq!(
+            headers.get("user-agent").map(String::as_str),
+            Some("claude-cli/2.1.300 (external, cli)")
+        );
+        assert_eq!(profile.billing_cli_version(), "2.1.300");
+        assert_eq!(
+            headers
+                .get("x-stainless-package-version")
+                .map(String::as_str),
+            Some("0.112.1")
+        );
+    }
+
+    #[test]
+    fn cli_profile_rejects_empty_or_control_values() {
+        assert!(ClaudeCodeClientProfile::cli("").is_err());
+        assert!(ClaudeCodeClientProfile::cli("2.1.0\nspoof").is_err());
+        assert!(ClaudeCodeClientProfile::cli("2.1.0 spoof").is_err());
+    }
+
     #[test]
     fn profile_preserves_context_1m_and_adds_operation_specific_betas() {
-        let profile = *current_claude_code_transport_identity_profile();
+        let profile = current_claude_code_transport_identity_profile();
         let messages = profile.merge_beta_tokens(Some("context-1m-2025-08-07,custom"), None);
 
         assert!(messages

crates/aether-provider/transport/src/claude_code/request.rs

@@ -49,23 +49,50 @@ pub fn build_claude_code_passthrough_headers(
         out.insert("anthropic-beta".to_string(), incoming_beta_values.join(","));
     }
 
-    let profile = *current_claude_code_transport_identity_profile();
+    let profile = current_claude_code_transport_identity_profile();
     profile.apply_fixed_headers(&mut out, stream);
     profile.apply_beta_policy(&mut out, None);
 
     out
 }
 
+/// Reconcile header/body identity using one immutable profile at the common
+/// outbound boundary. Preserve the planner's content negotiation and count-token contract.
+pub fn finalize_claude_code_request_identity(
+    headers: &mut BTreeMap<String, String>,
+    body: &mut Value,
+    profile: &ClaudeCodeTransportIdentityProfile,
+    operation: Option<aether_ai_formats::ApiOperation>,
+) {
+    let accept = headers.get("accept").cloned();
+    let stream = body.get("stream").and_then(Value::as_bool).unwrap_or(false)
+        || accept
+            .as_deref()
+            .is_some_and(|v| v.contains("text/event-stream"));
+    profile.apply_fixed_headers(headers, stream);
+    if stream {
+        crate::headers::force_identity_accept_encoding(headers);
+    }
+    profile.apply_beta_policy(headers, operation);
+    if let Some(accept) = accept {
+        headers.insert("accept".to_string(), accept);
+    }
+    if operation != Some(aether_ai_formats::ApiOperation::ClaudeCountTokens) {
+        let beta = headers.get("anthropic-beta").cloned().unwrap_or_default();
+        sanitize_claude_code_request_body_for_beta_header(body, &beta, profile);
+    }
+}
+
 pub fn sanitize_claude_code_request_body(body: &mut Value) {
-    let profile = *current_claude_code_transport_identity_profile();
+    let profile = current_claude_code_transport_identity_profile();
     let beta_header = profile.merge_beta_tokens(None, None);
-    sanitize_claude_code_request_body_for_beta_header(body, &beta_header, profile);
+    sanitize_claude_code_request_body_for_beta_header(body, &beta_header, &profile);
 }
 
 pub fn sanitize_claude_code_request_body_for_beta_header(
     body: &mut Value,
     beta_header: &str,
-    profile: ClaudeCodeTransportIdentityProfile,
+    profile: &ClaudeCodeTransportIdentityProfile,
 ) {
     let Some(body_object) = body.as_object_mut() else {
         return;
@@ -303,7 +330,7 @@ mod tests {
 
     #[test]
     fn context_management_body_is_gated_by_the_matching_beta_token() {
-        let profile = *current_claude_code_transport_identity_profile();
+        let profile = current_claude_code_transport_identity_profile();
         let original = json!({
             "context_management": {
                 "edits": [{"type":"clear_thinking_20251015", "keep":"all"}]
@@ -315,7 +342,7 @@ mod tests {
         sanitize_claude_code_request_body_for_beta_header(
             &mut without_beta,
             "oauth-2025-04-20",
-            profile,
+            &profile,
         );
         assert!(without_beta.get("context_management").is_none());
 
@@ -323,7 +350,7 @@ mod tests {
         sanitize_claude_code_request_body_for_beta_header(
             &mut with_beta,
             "oauth-2025-04-20, context-management-2025-06-27",
-            profile,
+            &profile,
         );
         assert_eq!(with_beta, original);
     }
@@ -371,3 +398,55 @@ mod tests {
         );
     }
 }
+#[cfg(test)]
+mod final_identity_tests {
+    use super::*;
+    use crate::claude_code::{ClaudeCodeClientProfile, CLAUDE_CODE_TRANSPORT_IDENTITY_2026_04};
+    use std::sync::Arc;
+    fn profile() -> ClaudeCodeTransportIdentityProfile {
+        ClaudeCodeTransportIdentityProfile::new(
+            &CLAUDE_CODE_TRANSPORT_IDENTITY_2026_04,
+            Arc::new(ClaudeCodeClientProfile::cli("2.1.286").unwrap()),
+        )
+    }
+    #[test]
+    fn terminal_snapshot_reconciles_billing_and_headers_without_changing_negotiation() {
+        let mut headers = BTreeMap::from([
+            ("accept".into(), "text/event-stream".into()),
+            ("User-Agent".into(), "old-client".into()),
+            ("X-Stainless-Package-Version".into(), "old-sdk".into()),
+            ("Anthropic-Beta".into(), "custom-beta".into()),
+        ]);
+        let mut body = serde_json::json!({"stream":true, "system":[{"type":"text", "text":"x-anthropic-billing-header: cc_version=2.1.280.abc; cc_entrypoint=cli;"}]});
+        finalize_claude_code_request_identity(&mut headers, &mut body, &profile(), None);
+        assert_eq!(headers["user-agent"], "claude-cli/2.1.286 (external, cli)");
+        assert_eq!(headers["accept"], "text/event-stream");
+        assert_eq!(headers["accept-encoding"], "identity");
+        assert_eq!(headers["x-stainless-package-version"], "0.112.1");
+        assert!(!headers.contains_key("User-Agent"));
+        assert!(!headers.contains_key("X-Stainless-Package-Version"));
+        assert!(!headers.contains_key("Anthropic-Beta"));
+        assert!(headers["anthropic-beta"].contains("custom-beta"));
+        assert!(body["system"][0]["text"]
+            .as_str()
+            .unwrap()
+            .contains("cc_version=2.1.286.abc;"));
+        let before = body.clone();
+        finalize_claude_code_request_identity(&mut headers, &mut body, &profile(), None);
+        assert_eq!(body, before);
+    }
+    #[test]
+    fn count_token_body_remains_untouched() {
+        let mut headers = BTreeMap::new();
+        let mut body = serde_json::json!({"model":"claude-test", "messages":[], "thinking":{"type":"enabled"}});
+        let before = body.clone();
+        finalize_claude_code_request_identity(
+            &mut headers,
+            &mut body,
+            &profile(),
+            Some(aether_ai_formats::ApiOperation::ClaudeCountTokens),
+        );
+        assert_eq!(body, before);
+        assert_eq!(headers["user-agent"], "claude-cli/2.1.286 (external, cli)");
+    }
+}

crates/aether-provider/transport/src/client_identity.rs

@@ -0,0 +1,65 @@
+//! Provider wire templates. Dynamic CLI versions are independent of SDK and
+//! browser fingerprints; pinned templates are changed only after verification.
+use aether_ai_formats::client_profile::validate_client_version;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct VersionedClientIdentity {
+    pub version: String,
+    pub user_agent: String,
+}
+
+impl VersionedClientIdentity {
+    pub fn new(version: &str, agent: &str, suffix: &str) -> Result<Self, &'static str> {
+        let version = validate_client_version(version)?;
+        Ok(Self {
+            version: version.to_owned(),
+            user_agent: format!("{agent}/{version}{suffix}"),
+        })
+    }
+}
+
+#[derive(Debug, Clone, Copy)]
+pub struct PinnedClientIdentity {
+    pub version: &'static str,
+    pub user_agent: &'static str,
+}
+
+pub const GEMINI_CLI: PinnedClientIdentity = PinnedClientIdentity {
+    version: "0.1.5",
+    user_agent: "GeminiCLI/0.1.5 (Windows; AMD64)",
+};
+// Legacy standard-models fallback; dedicated Kiro requests use OAuth SDK identity.
+pub const KIRO_MODELS_LEGACY_USER_AGENT: &str = "claude-code/1.0.1";
+
+pub const ANTIGRAVITY: PinnedClientIdentity = PinnedClientIdentity {
+    version: "4.3.0",
+    user_agent: "vscode/1.X.X (Antigravity/4.3.0)",
+};
+pub const WINDSURF: PinnedClientIdentity = PinnedClientIdentity {
+    version: "1.9600.41",
+    user_agent: "windsurf/1.9600.41",
+};
+// Verified browser release tuple, shared by inference and quota requests.
+// Do not update these independently or derive a web build from a CLI release.
+pub const CHATGPT_WEB_USER_AGENT: &str = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36 Edg/143.0.0.0";
+pub const CHATGPT_WEB_CLIENT_VERSION: &str = "prod-be885abbfcfe7b1f511e88b3003d9ee44757fbad";
+pub const CHATGPT_WEB_BUILD_NUMBER: &str = "5955942";
+pub const CHATGPT_WEB_SEC_CH_UA: &str =
+    r#""Microsoft Edge";v="143", "Chromium";v="143", "Not A(Brand";v="24""#;
+pub const CHATGPT_WEB_BROWSER_PROFILE: &str = "chrome143";
+
+// Kiro authentication and request adapters already share the OAuth model.
+pub use aether_oauth::provider::providers::{
+    DEFAULT_KIRO_VERSION, DEFAULT_NODE_VERSION, DEFAULT_SYSTEM_VERSION,
+};
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn pinned_headers_and_body_versions_are_calibrated_together() {
+        for identity in [ANTIGRAVITY, WINDSURF] {
+            assert!(identity.user_agent.contains(identity.version));
+        }
+    }
+}

crates/aether-provider/transport/src/gemini_cli/mod.rs

@@ -1,5 +1,9 @@
 mod auth;
 mod policy;
+mod profile;
+pub use profile::{
+    gemini_cli_client_user_agent, gemini_cli_client_version, set_gemini_cli_client_version,
+};
 mod request;
 mod url;
 

crates/aether-provider/transport/src/gemini_cli/profile.rs

@@ -0,0 +1,41 @@
+use crate::client_identity::VersionedClientIdentity;
+use aether_ai_formats::client_profile::ClientProfileStore;
+use std::sync::OnceLock;
+
+pub const GEMINI_CLI_BUILTIN_VERSION: &str = crate::client_identity::GEMINI_CLI.version;
+// Keep the established template; a version release does not change platform identity.
+fn identity(version: &str) -> Result<VersionedClientIdentity, &'static str> {
+    VersionedClientIdentity::new(version, "GeminiCLI", " (Windows; AMD64)")
+}
+static ACTIVE: OnceLock<ClientProfileStore<VersionedClientIdentity>> = OnceLock::new();
+fn active() -> &'static ClientProfileStore<VersionedClientIdentity> {
+    ACTIVE.get_or_init(|| {
+        ClientProfileStore::new(
+            identity(GEMINI_CLI_BUILTIN_VERSION).expect("valid built-in Gemini identity"),
+        )
+    })
+}
+pub fn gemini_cli_client_version() -> String {
+    active().snapshot().version.clone()
+}
+pub fn gemini_cli_client_user_agent() -> String {
+    active().snapshot().user_agent.clone()
+}
+pub fn set_gemini_cli_client_version(version: &str) -> Result<String, &'static str> {
+    Ok(active().publish(identity(version)?).version.clone())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn version_updates_preserve_the_existing_platform_template() {
+        let profile = identity("0.62.0").unwrap();
+        assert_eq!(profile.user_agent, "GeminiCLI/0.62.0 (Windows; AMD64)");
+        assert!(identity("0.62.0\nx: y").is_err());
+        assert_eq!(
+            identity(GEMINI_CLI_BUILTIN_VERSION).unwrap().user_agent,
+            super::super::GEMINI_CLI_USER_AGENT
+        );
+    }
+}

crates/aether-provider/transport/src/gemini_cli/url.rs

@@ -2,7 +2,7 @@ use std::collections::BTreeMap;
 
 use url::form_urlencoded;
 
-pub const GEMINI_CLI_USER_AGENT: &str = "GeminiCLI/0.1.5 (Windows; AMD64)";
+pub const GEMINI_CLI_USER_AGENT: &str = crate::client_identity::GEMINI_CLI.user_agent;
 pub const GEMINI_CLI_V1INTERNAL_PATH_TEMPLATE: &str = "/v1internal:{action}";
 pub const GEMINI_CLI_RETRIEVE_USER_QUOTA_PATH: &str = "/v1internal:retrieveUserQuota";
 

crates/aether-provider/transport/src/headers.rs

@@ -81,7 +81,7 @@ pub fn should_skip_request_header(name: &str) -> bool {
 }
 
 fn is_untrusted_forwarding_metadata_header(normalized_name: &str) -> bool {
-    matches!(normalized_name, "forwarded" | "via")
+    matches!(normalized_name, "forwarded" | "via" | "x-envoy-internal")
         || normalized_name.starts_with("x-forwarded-")
         || normalized_name.starts_with("x_forwarded_")
         || normalized_name.starts_with("x-real-")
@@ -186,6 +186,7 @@ pub(crate) fn remove_declared_connection_headers(
     ));
     headers.retain(|name, _| {
         !name.eq_ignore_ascii_case("connection")
+            && !name.eq_ignore_ascii_case("x-envoy-internal")
             && !is_declared_connection_header(name, &all_declared)
     });
 }
@@ -455,6 +456,7 @@ mod tests {
             "X-Rewrite-URL",
             "X-Override-URL",
             "X-Envoy-Original-Path",
+            "X-Envoy-Internal",
         ] {
             assert!(should_skip_request_header(header));
             assert!(should_skip_upstream_passthrough_header(header));

crates/aether-provider/transport/src/lib.rs

@@ -5,6 +5,7 @@ pub mod auth;
 mod auth_config;
 mod cache;
 pub mod claude_code;
+pub mod client_identity;
 mod codex_fingerprint;
 pub mod conversion;
 mod diagnostics;

crates/aether-provider/transport/src/network.rs

@@ -177,7 +177,7 @@ fn resolve_claude_code_transport_profile(
         return None;
     }
 
-    let identity_profile = *current_claude_code_transport_identity_profile();
+    let identity_profile = current_claude_code_transport_identity_profile();
     Some(ResolvedTransportProfile {
         profile_id: identity_profile.transport_profile_id().to_string(),
         backend: TRANSPORT_BACKEND_REQWEST_RUSTLS.to_string(),

crates/aether-provider/transport/src/outbound_request_policy.rs

@@ -199,6 +199,23 @@ pub fn apply_provider_outbound_request_policies(
     provider_request_headers: &mut BTreeMap<String, String>,
     provider_request_body: &mut Value,
 ) -> Vec<ProviderOutboundRequestPolicyResult> {
+    // This is the common boundary after planner rules and before transport.
+    provider_request_headers.retain(|name, _| !name.eq_ignore_ascii_case("x-envoy-internal"));
+    if transport
+        .provider
+        .provider_type
+        .trim()
+        .eq_ignore_ascii_case("claude_code")
+        && aether_ai_formats::normalize_api_format_alias(provider_api_format) == "claude:messages"
+    {
+        let profile = crate::claude_code::current_claude_code_transport_identity_profile();
+        crate::claude_code::finalize_claude_code_request_identity(
+            provider_request_headers,
+            provider_request_body,
+            &profile,
+            context.api_operation(),
+        );
+    }
     if !transport
         .provider
         .provider_type

crates/aether-provider/transport/src/same_format_provider/mod.rs

@@ -848,7 +848,7 @@ pub fn build_same_format_provider_headers(
     } else {
         replace_upstream_auth_headers(&mut provider_request_headers, "", "");
     }
-    let claude_code_profile = *current_claude_code_transport_identity_profile();
+    let claude_code_profile = current_claude_code_transport_identity_profile();
     if input.behavior.is_claude_code_transport {
         claude_code_profile.apply_fixed_headers(
             &mut provider_request_headers,

crates/aether-provider/transport/src/windsurf.rs

@@ -23,7 +23,7 @@ pub mod proto;
 pub const PROVIDER_TYPE: &str = "windsurf";
 pub const WINDSURF_ENVELOPE_NAME: &str = "windsurf:GetChatMessage";
 pub const GET_CHAT_MESSAGE_PATH: &str = "/exa.api_server_pb.ApiServerService/GetChatMessage";
-const DEFAULT_IDE_VERSION: &str = "1.9600.41";
+pub const DEFAULT_IDE_VERSION: &str = crate::client_identity::WINDSURF.version;
 const PLACEHOLDER_API_KEY: &str = "__placeholder__";
 
 pub fn is_windsurf_provider_transport(transport: &GatewayProviderTransportSnapshot) -> bool {

crates/aether-provider/transport/src/xai.rs

@@ -1,7 +1,10 @@
 pub mod video;
 
 use std::collections::BTreeMap;
-use std::sync::{OnceLock, RwLock};
+use std::sync::OnceLock;
+
+use crate::client_identity::VersionedClientIdentity;
+use aether_ai_formats::client_profile::ClientProfileStore;
 
 use aether_ai_formats::normalize_api_format_alias;
 use serde_json::Value;
@@ -23,37 +26,31 @@ pub const XAI_CLIENT_IDENTIFIER_VALUE: &str = "grok-shell";
 pub const XAI_AUTHENTICATE_RESPONSE_HEADER: &str = "x-authenticateresponse";
 pub const XAI_AUTHENTICATE_RESPONSE_VALUE: &str = "authenticate-response";
 
-static ACTIVE_CLIENT_VERSION: OnceLock<RwLock<String>> = OnceLock::new();
+static ACTIVE_CLIENT_VERSION: OnceLock<ClientProfileStore<VersionedClientIdentity>> =
+    OnceLock::new();
 
-fn active_client_version() -> &'static RwLock<String> {
-    ACTIVE_CLIENT_VERSION.get_or_init(|| RwLock::new(XAI_DEFAULT_CLIENT_VERSION.to_owned()))
+fn active_client_version() -> &'static ClientProfileStore<VersionedClientIdentity> {
+    ACTIVE_CLIENT_VERSION.get_or_init(|| {
+        ClientProfileStore::new(
+            VersionedClientIdentity::new(XAI_DEFAULT_CLIENT_VERSION, "xai-grok-workspace", "")
+                .expect("valid built-in Grok identity"),
+        )
+    })
 }
 
 /// 返回当前发布的 Grok CLI 版本快照。
 pub fn xai_client_version() -> String {
-    active_client_version()
-        .read()
-        .unwrap_or_else(std::sync::PoisonError::into_inner)
-        .clone()
+    active_client_version().snapshot().version.clone()
 }
 
-/// 原子替换当前 Grok CLI 版本，返回替换前的版本；版本校验由发布检查器负责，这里只拒绝明显非法值。
+/// 原子替换当前 Grok CLI 身份，返回替换前的版本。
 pub fn set_xai_client_version(version: &str) -> Result<String, &'static str> {
-    let version = version.trim();
-    if version.is_empty()
-        || version.len() > 64
-        || !version.bytes().all(|byte| (33..=126).contains(&byte))
-    {
-        return Err("invalid Grok CLI version");
-    }
-    let mut current = active_client_version()
-        .write()
-        .unwrap_or_else(std::sync::PoisonError::into_inner);
-    Ok(std::mem::replace(&mut *current, version.to_owned()))
+    let profile = VersionedClientIdentity::new(version, "xai-grok-workspace", "")?;
+    Ok(active_client_version().publish(profile).version.clone())
 }
 
 pub fn xai_cli_user_agent() -> String {
-    format!("xai-grok-workspace/{}", xai_client_version())
+    active_client_version().snapshot().user_agent.clone()
 }
 
 pub fn is_xai_provider_transport(transport: &GatewayProviderTransportSnapshot) -> bool {
@@ -125,7 +122,7 @@ pub fn should_attach_cli_identity_headers(
 
 pub fn insert_cli_identity_headers(headers: &mut BTreeMap<String, String>) {
     let client_version = xai_client_version();
-    let user_agent = xai_cli_user_agent();
+    let user_agent = format!("xai-grok-workspace/{client_version}");
     for (name, value) in [
         (XAI_TOKEN_AUTH_HEADER, XAI_TOKEN_AUTH_VALUE),
         (XAI_CLIENT_VERSION_HEADER, client_version.as_str()),

docs/operations/codex-cli-alignment.md

@@ -1,5 +1,6 @@
 # Codex CLI 通用协议对齐
 
+运行时版本刷新、每节点缓存同步及固定版本配置见[统一客户端画像](provider-client-profiles.md)。
 本次对齐以官方 `openai/codex` 稳定标签 `rust-v0.159.3` 为可发布版本依据，同时核查最新 `main` 的协议实现。稳定标签提交为 `01fc69f4026735edfdf6789820549727a4867b11`，核查的 main 提交为 `444da310e108da16aaeb18fd790b0ac464f08aca`。
 
 网关承接的是客户端与上游之间的协议，不复制 CLI 的本地工具执行、终端界面或个人账户状态。

docs/operations/provider-client-profiles.md

@@ -0,0 +1,102 @@
+# 提供商客户端画像
+
+网关统一管理客户端身份，但不把所有提供商伪装成同一个客户端。
+客户端发行版本、SDK/运行时模板、浏览器构建和账户/会话标识是不同维度。
+本次改造保留已有认证、请求体转换、原生端点和显式配置优先级。
+
+## 策略
+
+| 客户端 | 版本来源 | 检查间隔 | 不随发行版本改变的内容 |
+| --- | --- | --- | --- |
+| Codex CLI/Core | 官方 `@openai/codex` npm latest | 每日 | `codex_cli_rs` originator、现有 OS/架构 UA 模板 |
+| Claude Code | 官方 `@anthropic-ai/claude-code` npm latest | 每日 | 已校准的 Stainless SDK、运行时字段和 beta/能力模板 |
+| Grok CLI | `https://x.ai/cli/stable`，失败回退官方 npm latest | 3 小时 | 现有 CLI 身份字段、OAuth/API-key 路由与自定义网关优先级 |
+| Gemini CLI | 官方 `@google/gemini-cli` npm latest | 每日 | 现有 `(Windows; AMD64)` UA 模板与 Code Assist 请求协议 |
+| Antigravity、Windsurf | 经核验的固定模板 | 不自动更新 | IDE UA、请求体版本及现有平台模板 |
+| Kiro | 已有 OAuth SDK 模板及显式配置 | 不自动更新 | SDK、Node 和系统版本；保留旧模型查询兼容回退 |
+| ChatGPT Web、Grok Web | 固定浏览器构建或已有可配置浏览器画像 | 不自动更新 | 浏览器 UA、Client Hints、TLS/HTTP 指纹及 Web 构建信息 |
+| 原生/其他提供商 | 原有协议和配置 | 无 CLI 版本刷新 | 不注入无依据的 CLI、SDK 或浏览器指纹 |
+
+Codex Desktop 不仅凭客户端名称切换 originator 或 SDK 字段；沿用已确认的
+Codex Core 身份。代理客户端传入的版本不是官方发行版本来源。
+不会为 Rust CLI 强行添加 JavaScript Stainless 字段。
+
+## 集群刷新与本地同步
+
+- `apps/aether-gateway/src/cli_client_profile.rs` 保存四个动态 CLI 描述和共同引擎。
+- 启动预热和后台 singleton 共用发行查询互斥锁。新鲜的已验证缓存避免多个节点
+  启动时重复查询官方源。原有缓存 key 和字段保持兼容。
+- 各进程独立运行缓存同步任务，每 60 秒同步一次，包括仅承接请求的 frontdoor 节点。
+  此任务不查询发行源、不竞争 singleton；启动守卫随主程序退出而中止任务。
+- 多节点必须使用同一个共享运行时缓存。内存后端只提供进程内的缓存和互斥语义。
+- 自动恢复和刷新不接受比本地画像更旧的稳定版本。外部查询等待期间若共享缓存已升级，
+  发布前再次恢复并检查版本，拒绝过期结果。
+- 官方请求仅允许 HTTPS，禁止重定向及系统环境代理；连接、请求和响应大小均有上限。
+  npm 元数据需要包名、稳定版本以及相应原生平台依赖一致。Gemini CLI 的官方 JS 包
+  不要求不存在的原生平台依赖。
+- 发行源、校验或缓存读取失败不清空现有画像。缓存写入失败保留本地已验证画像并告警；
+  其他节点只能继续使用最近成功持久化的画像，因此需关注缓存失败日志并恢复共享缓存。
+
+## 配置
+
+| 客户端 | 固定版本 | 禁用外部刷新 |
+| --- | --- | --- |
+| Codex | `AETHER_CODEX_CLIENT_VERSION` | `AETHER_CODEX_CLIENT_PROFILE_REFRESH=false` |
+| Claude Code | `AETHER_CLAUDE_CODE_CLIENT_VERSION` | `AETHER_CLAUDE_CODE_CLIENT_PROFILE_REFRESH=false` |
+| Grok CLI | `AETHER_XAI_CLIENT_VERSION` | `AETHER_XAI_CLIENT_PROFILE_REFRESH=false` |
+| Gemini CLI | `AETHER_GEMINI_CLI_CLIENT_VERSION` | `AETHER_GEMINI_CLI_CLIENT_PROFILE_REFRESH=false` |
+
+有效固定版本优先于缓存、内置值和外部发行检查，可用于显式回退；该覆盖只改变当前
+进程，不写入集群缓存。需要集群固定版本时应为各节点配置同一个值。
+禁用刷新仅停止外部查询，仍允许从共享缓存同步。未配置固定版本或刷新开关时，
+默认使用缓存/内置值并启用外部检查。
+
+## 请求边界
+
+`aether-ai-formats::client_profile::ClientProfileStore` 用不可变 `Arc` 快照发布画像。
+请求已经持有的快照不会被后台更新修改。
+
+- Grok CLI 默认版本头和 UA 从同一个快照产生；保留既有显式头覆盖规则。
+- Gemini CLI 的推理、配额和模型发现读取同一进程内画像来源，而不是各自维护版本常量。
+- Claude Code 在共同出站策略边界重新对齐固定头、beta 和 billing `cc_version`，
+  使用一次取得的画像完成头/体校准。保留内容协商和流式行为；count-tokens 不执行
+  消息请求体改写。
+- Codex 使用现有受保护认证头、Core UA/originator 和可选会话指纹收敛策略；不改变
+  Responses-lite、compact、agent-identity 和原生记忆端点的契约。
+- 客户端的 `x-envoy-internal` 不能透传为上游可信内部标记；同格式、跨格式、
+  passthrough 和共同出站策略均包含过滤。
+- 不把用户 Bearer、Cookie、账号 ID、安装/窗口 ID 或 SDK 字段保存为发行画像。
+
+静态模板集中在 `crates/aether-provider/transport/src/client_identity.rs`；
+Kiro 复用 OAuth 的 SDK 模板，Grok Web 继续复用既有浏览器画像。
+静态版本只能按核验后的整套模板更新，不能直接套用 npm 的 CLI 版本。
+
+## 回归验证
+
+```bash
+cargo fmt --all -- --check
+cargo test -p aether-ai-formats --locked
+cargo test -p aether-provider-transport --locked
+cargo test -p aether-provider-pool --locked
+cargo test -p aether-model-fetch --locked
+cargo check -p aether-gateway --locked
+cargo test -p aether-gateway --lib client_profile --locked
+```
+
+回归覆盖不可变快照、头/体版本一致性、稳定源回退、npm 平台校验、缓存损坏和防回退、
+刷新期间共享缓存升级、独立节点同步、固定版本优先级，以及保留原有提供商协议行为。
+验证使用本地数据和模拟回调，不需要个人凭据或付费模型调用。
+
+## 已执行验证
+
+- Transport：550 项通过；formats：993 项通过；pool：71 项通过；model-fetch：83 项通过。
+- `cargo check -p aether-gateway --locked` 通过。
+- 网关专项：client_profile 21 项、Codex 249 项、Gemini CLI 39 项通过；
+  Claude Code 13 项通过，1 项失败。共 2019 项通过。
+- 格式与 `git diff --check` 通过。
+- 已知失败：`handlers::shared::catalog::tests::provider_key_status_snapshot_payload_backfills_claude_code_usage_windows`。
+  在独立 worktree 的改造前提交 `716c35bf5` 上单独运行，同样在 `catalog.rs:4373`
+  得到 `exhausted=false` 与预期 `true` 的断言失败。该配额展示逻辑未在本次改造中修改，
+  此失败不能计作通过，也不是画像改造引入的回归。
+
+相关说明：[Codex CLI 对齐](codex-cli-alignment.md)、[xAI 行为](xai-provider.md)。

docs/operations/xai-provider.md

@@ -3,6 +3,9 @@
 The following rules preserve the provider-specific behavior of the `xai` provider
 across Aether's request and transport layers.
 
+Release refresh, per-node cache synchronization, and version overrides are documented
+in [provider client profiles](provider-client-profiles.md). Grok retains its official stable
+channel with npm fallback and the existing three-hour refresh interval.
 ## Responses and tools
 
 - HTTP requests drop `previous_response_id`. Clients must supply conversation