Merge branch 'pr-390' into aether-rust-pioneer

apps/aether-gateway/src/data/state/runtime.rs

@@ -30,8 +30,9 @@ use super::{
     WalletLookupKey, WalletMutationOutcome,
 };
 use aether_data_contracts::repository::usage::{
-    PendingUsageCleanupSummary, StoredUsageDailySummary, UsageAuditListQuery, UsageCleanupSummary,
+    PendingUsageCleanupSummary, ProviderApiKeyWindowUsageRequest,
-    UsageCleanupWindow, UsageDailyHeatmapQuery,
+    StoredProviderApiKeyWindowUsageSummary, StoredUsageDailySummary, UsageAuditListQuery,
+    UsageCleanupSummary, UsageCleanupWindow, UsageDailyHeatmapQuery,
 };
 use aether_video_tasks_core::read_data_backed_video_task_response;
 
@@ -1366,6 +1367,20 @@ impl GatewayDataState {
         }
     }
 
+    pub(crate) async fn summarize_usage_by_provider_api_key_windows(
+        &self,
+        requests: &[ProviderApiKeyWindowUsageRequest],
+    ) -> Result<Vec<StoredProviderApiKeyWindowUsageSummary>, DataLayerError> {
+        match &self.usage_reader {
+            Some(repository) => {
+                repository
+                    .summarize_usage_by_provider_api_key_windows(requests)
+                    .await
+            }
+            None => Ok(Vec::new()),
+        }
+    }
+
     pub(crate) async fn list_users_by_ids(
         &self,
         user_ids: &[String],

apps/aether-gateway/src/handlers/admin/provider/pool_admin/payloads.rs

@@ -9,7 +9,11 @@ use aether_admin::provider::quota as admin_provider_quota_pure;
 use aether_data_contracts::repository::provider_catalog::{
     StoredProviderCatalogEndpoint, StoredProviderCatalogKey,
 };
+use aether_data_contracts::repository::usage::{
+    ProviderApiKeyWindowUsageRequest, StoredProviderApiKeyWindowUsageSummary,
+};
 use serde_json::json;
+use std::collections::BTreeMap;
 
 fn admin_pool_string_list(value: Option<&serde_json::Value>) -> Option<Vec<String>> {
     let values = value
@@ -289,6 +293,124 @@ fn admin_pool_quota_window<'a>(
         })
 }
 
+pub(super) type AdminPoolCodexWindowUsageByKey =
+    BTreeMap<(String, String), StoredProviderApiKeyWindowUsageSummary>;
+
+fn admin_pool_provider_type_is_codex(provider_type: &str) -> bool {
+    provider_type.trim().eq_ignore_ascii_case("codex")
+}
+
+fn admin_pool_codex_window_usage_code(
+    window: &serde_json::Map<String, serde_json::Value>,
+) -> Option<&'static str> {
+    let code = window
+        .get("code")
+        .and_then(serde_json::Value::as_str)
+        .map(str::trim)?;
+    if code.eq_ignore_ascii_case("5h") {
+        Some("5h")
+    } else if code.eq_ignore_ascii_case("weekly") {
+        Some("weekly")
+    } else {
+        None
+    }
+}
+
+fn admin_pool_codex_window_usage_bounds(
+    window: &serde_json::Map<String, serde_json::Value>,
+) -> Option<(u64, u64)> {
+    let reset_at = admin_pool_json_to_u64(window.get("reset_at"))?;
+    let window_minutes = admin_pool_json_to_u64(window.get("window_minutes"))?;
+    let window_seconds = window_minutes.checked_mul(60)?;
+    let start = reset_at.checked_sub(window_seconds)?;
+    (start < reset_at).then_some((start, reset_at))
+}
+
+pub(super) fn build_admin_pool_codex_window_usage_requests(
+    provider_type: &str,
+    keys: &[StoredProviderCatalogKey],
+) -> Vec<ProviderApiKeyWindowUsageRequest> {
+    if !admin_pool_provider_type_is_codex(provider_type) {
+        return Vec::new();
+    }
+
+    let mut requests = Vec::new();
+    for key in keys {
+        let status_snapshot = provider_key_status_snapshot_payload(key, provider_type);
+        let Some(windows) = status_snapshot
+            .get("quota")
+            .and_then(serde_json::Value::as_object)
+            .and_then(|quota| quota.get("windows"))
+            .and_then(serde_json::Value::as_array)
+        else {
+            continue;
+        };
+
+        for window in windows.iter().filter_map(serde_json::Value::as_object) {
+            let Some(window_code) = admin_pool_codex_window_usage_code(window) else {
+                continue;
+            };
+            let Some((start_unix_secs, end_unix_secs)) =
+                admin_pool_codex_window_usage_bounds(window)
+            else {
+                continue;
+            };
+            requests.push(ProviderApiKeyWindowUsageRequest {
+                provider_api_key_id: key.id.clone(),
+                window_code: window_code.to_string(),
+                start_unix_secs,
+                end_unix_secs,
+            });
+        }
+    }
+    requests
+}
+
+fn admin_pool_codex_window_usage_payload(
+    usage: &StoredProviderApiKeyWindowUsageSummary,
+) -> serde_json::Value {
+    json!({
+        "request_count": usage.request_count,
+        "total_tokens": usage.total_tokens,
+        "total_cost_usd": format!("{:.8}", usage.total_cost_usd),
+    })
+}
+
+fn admin_pool_attach_codex_window_usage(
+    status_snapshot: &mut serde_json::Value,
+    key_id: &str,
+    usage_by_key: &AdminPoolCodexWindowUsageByKey,
+) {
+    if usage_by_key.is_empty() {
+        return;
+    }
+
+    let Some(windows) = status_snapshot
+        .get_mut("quota")
+        .and_then(serde_json::Value::as_object_mut)
+        .and_then(|quota| quota.get_mut("windows"))
+        .and_then(serde_json::Value::as_array_mut)
+    else {
+        return;
+    };
+
+    for window in windows
+        .iter_mut()
+        .filter_map(serde_json::Value::as_object_mut)
+    {
+        let Some(window_code) = admin_pool_codex_window_usage_code(window) else {
+            continue;
+        };
+        let lookup_key = (key_id.to_string(), window_code.to_string());
+        if let Some(usage) = usage_by_key.get(&lookup_key) {
+            window.insert(
+                "usage".to_string(),
+                admin_pool_codex_window_usage_payload(usage),
+            );
+        }
+    }
+}
+
 fn admin_pool_quota_window_used_percent(
     window: &serde_json::Map<String, serde_json::Value>,
 ) -> Option<f64> {
@@ -804,6 +926,7 @@ pub(super) fn build_admin_pool_key_payload(
     key: &StoredProviderCatalogKey,
     runtime: &AdminProviderPoolRuntimeState,
     pool_config: Option<AdminProviderPoolConfig>,
+    codex_window_usage_by_key: &AdminPoolCodexWindowUsageByKey,
 ) -> serde_json::Value {
     let cooldown_reason = runtime.cooldown_reason_by_key.get(&key.id).cloned();
     let cooldown_ttl_seconds = cooldown_reason
@@ -821,7 +944,14 @@ pub(super) fn build_admin_pool_key_payload(
         admin_pool_derive_oauth_expires_at(provider_type, key, auth_config.as_ref());
     let oauth_plan_type =
         admin_pool_derive_oauth_plan_type(key, provider_type, auth_config.as_ref());
-    let status_snapshot = provider_key_status_snapshot_payload(key, provider_type);
+    let mut status_snapshot = provider_key_status_snapshot_payload(key, provider_type);
+    if admin_pool_provider_type_is_codex(provider_type) {
+        admin_pool_attach_codex_window_usage(
+            &mut status_snapshot,
+            &key.id,
+            codex_window_usage_by_key,
+        );
+    }
     let account_snapshot = status_snapshot
         .get("account")
         .and_then(serde_json::Value::as_object);

apps/aether-gateway/src/handlers/admin/provider/pool_admin/read_routes/keys.rs

@@ -253,6 +253,26 @@ pub(super) async fn build_admin_pool_list_keys_response(
         }
         _ => AdminProviderPoolRuntimeState::default(),
     };
+    let codex_window_usage_requests =
+        pool_payloads::build_admin_pool_codex_window_usage_requests(&provider.provider_type, &keys);
+    let codex_window_usage_by_key: pool_payloads::AdminPoolCodexWindowUsageByKey =
+        if codex_window_usage_requests.is_empty() {
+            pool_payloads::AdminPoolCodexWindowUsageByKey::new()
+        } else {
+            state
+                .app()
+                .summarize_usage_by_provider_api_key_windows(&codex_window_usage_requests)
+                .await?
+                .into_iter()
+                .map(|usage| {
+                    (
+                        (usage.provider_api_key_id.clone(), usage.window_code.clone()),
+                        usage,
+                    )
+                })
+                .collect()
+        };
+
     let items = keys
         .into_iter()
         .map(|key| {
@@ -263,6 +283,7 @@ pub(super) async fn build_admin_pool_list_keys_response(
                 &key,
                 &runtime,
                 pool_config.clone(),
+                &codex_window_usage_by_key,
             )
         })
         .collect::<Vec<_>>();

apps/aether-gateway/src/state/runtime/usage_queries.rs

@@ -345,6 +345,16 @@ impl AppState {
             .map_err(|err| GatewayError::Internal(err.to_string()))
     }
 
+    pub(crate) async fn summarize_usage_by_provider_api_key_windows(
+        &self,
+        requests: &[usage::ProviderApiKeyWindowUsageRequest],
+    ) -> Result<Vec<usage::StoredProviderApiKeyWindowUsageSummary>, GatewayError> {
+        self.data
+            .summarize_usage_by_provider_api_key_windows(requests)
+            .await
+            .map_err(|err| GatewayError::Internal(err.to_string()))
+    }
+
     pub(crate) async fn list_users_by_ids(
         &self,
         user_ids: &[String],

apps/aether-gateway/src/tests/control/admin/pool.rs

@@ -2,7 +2,9 @@ use std::sync::{Arc, Mutex};
 
 use aether_crypto::{encrypt_python_fernet_plaintext, DEVELOPMENT_ENCRYPTION_KEY};
 use aether_data::repository::provider_catalog::InMemoryProviderCatalogReadRepository;
+use aether_data::repository::usage::InMemoryUsageReadRepository;
 use aether_data_contracts::repository::provider_catalog::ProviderCatalogReadRepository;
+use aether_data_contracts::repository::usage::StoredRequestUsageAudit;
 use axum::body::{to_bytes, Body, Bytes};
 use axum::routing::{any, get, post};
 use axum::{extract::Request, Router};
@@ -21,6 +23,54 @@ use crate::constants::{
 use crate::control::resolve_public_request_context;
 use crate::data::GatewayDataState;
 
+fn sample_pool_usage_row(
+    request_id: &str,
+    provider_api_key_id: &str,
+    created_at_unix_secs: i64,
+    total_tokens: i32,
+    total_cost_usd: f64,
+) -> StoredRequestUsageAudit {
+    StoredRequestUsageAudit::new(
+        format!("usage-{request_id}"),
+        request_id.to_string(),
+        Some("user-codex".to_string()),
+        Some("api-key-codex".to_string()),
+        Some("codex-user".to_string()),
+        Some("codex-api-key".to_string()),
+        "codex".to_string(),
+        "gpt-5-codex".to_string(),
+        None,
+        Some("provider-codex".to_string()),
+        Some("endpoint-codex".to_string()),
+        Some(provider_api_key_id.to_string()),
+        Some("responses".to_string()),
+        Some("openai:responses".to_string()),
+        Some("openai".to_string()),
+        Some("responses".to_string()),
+        Some("openai:responses".to_string()),
+        Some("openai".to_string()),
+        Some("responses".to_string()),
+        false,
+        false,
+        total_tokens,
+        0,
+        total_tokens,
+        total_cost_usd,
+        total_cost_usd,
+        Some(200),
+        None,
+        None,
+        Some(240),
+        Some(80),
+        "completed".to_string(),
+        "settled".to_string(),
+        created_at_unix_secs,
+        created_at_unix_secs + 1,
+        Some(created_at_unix_secs + 2),
+    )
+    .expect("usage row should build")
+}
+
 fn trusted_admin_headers() -> HeaderMap {
     let mut headers = HeaderMap::new();
     headers.insert(GATEWAY_HEADER, HeaderValue::from_static("rust-phase3b"));
@@ -793,6 +843,233 @@ async fn gateway_sorts_admin_pool_keys_by_imported_and_last_used_time() {
     assert_eq!(last_used_names, vec!["active", "old", "fresh"]);
 }
 
+#[tokio::test]
+async fn gateway_pool_list_adds_codex_cycle_usage_to_quota_windows() {
+    const RESET_AT: u64 = 1_711_000_000;
+
+    let mut provider = sample_provider("provider-codex", "codex", 10).with_transport_fields(
+        true,
+        false,
+        true,
+        None,
+        None,
+        None,
+        None,
+        None,
+        Some(json!({
+            "pool_advanced": {
+                "enabled": true
+            }
+        })),
+    );
+    provider.provider_type = "codex".to_string();
+
+    let mut usage_key = sample_key(
+        "key-codex-cycle",
+        "provider-codex",
+        "openai:responses",
+        "oauth-placeholder",
+    );
+    usage_key.name = "codex cycle usage".to_string();
+    usage_key.auth_type = "oauth".to_string();
+    usage_key.request_count = Some(4);
+    usage_key.total_tokens = 999;
+    usage_key.total_cost_usd = 9.99;
+    usage_key.status_snapshot = Some(json!({
+        "quota": {
+            "version": 2,
+            "provider_type": "codex",
+            "code": "ok",
+            "label": serde_json::Value::Null,
+            "reason": serde_json::Value::Null,
+            "freshness": "fresh",
+            "source": "response_headers",
+            "observed_at": RESET_AT,
+            "exhausted": false,
+            "usage_ratio": 0.0,
+            "updated_at": RESET_AT,
+            "reset_seconds": serde_json::Value::Null,
+            "plan_type": "plus",
+            "windows": [
+                {
+                    "code": "weekly",
+                    "label": "周",
+                    "scope": "account",
+                    "unit": "percent",
+                    "used_ratio": 0.0,
+                    "remaining_ratio": 1.0,
+                    "reset_at": RESET_AT,
+                    "reset_seconds": 604_800,
+                    "window_minutes": 10_080
+                },
+                {
+                    "code": "5h",
+                    "label": "5H",
+                    "scope": "account",
+                    "unit": "percent",
+                    "used_ratio": 0.0,
+                    "remaining_ratio": 1.0,
+                    "reset_at": RESET_AT,
+                    "reset_seconds": 18_000,
+                    "window_minutes": 300
+                }
+            ]
+        }
+    }));
+
+    let mut zero_key = sample_key(
+        "key-codex-zero",
+        "provider-codex",
+        "openai:responses",
+        "oauth-placeholder",
+    );
+    zero_key.name = "codex zero usage".to_string();
+    zero_key.auth_type = "oauth".to_string();
+    zero_key.status_snapshot = usage_key.status_snapshot.clone();
+
+    let mut invalid_key = sample_key(
+        "key-codex-invalid",
+        "provider-codex",
+        "openai:responses",
+        "oauth-placeholder",
+    );
+    invalid_key.name = "codex invalid window".to_string();
+    invalid_key.auth_type = "oauth".to_string();
+    invalid_key.status_snapshot = Some(json!({
+        "quota": {
+            "version": 2,
+            "provider_type": "codex",
+            "code": "ok",
+            "windows": [
+                {
+                    "code": "weekly",
+                    "label": "周",
+                    "reset_at": serde_json::Value::Null,
+                    "window_minutes": 10_080
+                },
+                {
+                    "code": "5h",
+                    "label": "5H",
+                    "reset_at": RESET_AT,
+                    "window_minutes": serde_json::Value::Null
+                }
+            ]
+        }
+    }));
+
+    let provider_catalog_repository = Arc::new(InMemoryProviderCatalogReadRepository::seed(
+        vec![provider],
+        Vec::new(),
+        vec![usage_key, zero_key, invalid_key],
+    ));
+    let usage_repository = Arc::new(InMemoryUsageReadRepository::seed(vec![
+        sample_pool_usage_row(
+            "req-5h-a",
+            "key-codex-cycle",
+            RESET_AT as i64 - 60,
+            100,
+            0.10,
+        ),
+        sample_pool_usage_row(
+            "req-5h-b",
+            "key-codex-cycle",
+            RESET_AT as i64 - 17_999,
+            125,
+            0.20,
+        ),
+        sample_pool_usage_row(
+            "req-weekly-only",
+            "key-codex-cycle",
+            RESET_AT as i64 - 18_001,
+            150,
+            0.30,
+        ),
+        sample_pool_usage_row(
+            "req-before-weekly",
+            "key-codex-cycle",
+            RESET_AT as i64 - 604_801,
+            200,
+            0.40,
+        ),
+    ]));
+    let state = AppState::new()
+        .expect("gateway should build")
+        .with_data_state_for_tests(
+            GatewayDataState::with_provider_catalog_and_usage_reader_for_tests(
+                provider_catalog_repository,
+                usage_repository,
+            ),
+        );
+
+    let response = local_admin_pool_response(
+        &state,
+        http::Method::GET,
+        "/api/admin/pool/provider-codex/keys?page=1&page_size=50&status=all",
+        None,
+    )
+    .await;
+
+    assert_eq!(response.status(), StatusCode::OK);
+    let payload: serde_json::Value = serde_json::from_slice(
+        &to_bytes(response.into_body(), usize::MAX)
+            .await
+            .expect("body should read"),
+    )
+    .expect("json body should parse");
+    let keys = payload["keys"].as_array().expect("keys should be array");
+    fn key_by_id<'a>(keys: &'a [serde_json::Value], key_id: &str) -> &'a serde_json::Value {
+        keys.iter()
+            .find(|key| key["key_id"] == json!(key_id))
+            .expect("key payload should exist")
+    }
+
+    fn window_by_code<'a>(key_payload: &'a serde_json::Value, code: &str) -> &'a serde_json::Value {
+        key_payload["status_snapshot"]["quota"]["windows"]
+            .as_array()
+            .expect("quota windows should be array")
+            .iter()
+            .find(|window| window["code"] == json!(code))
+            .expect("quota window should exist")
+    }
+
+    let usage_key_payload = key_by_id(keys, "key-codex-cycle");
+    let five_hour_window = window_by_code(usage_key_payload, "5h");
+    let weekly_window = window_by_code(usage_key_payload, "weekly");
+    assert_eq!(five_hour_window["usage"]["request_count"], json!(2));
+    assert_eq!(five_hour_window["usage"]["total_tokens"], json!(225));
+    assert_eq!(
+        five_hour_window["usage"]["total_cost_usd"],
+        json!("0.30000000")
+    );
+    assert_eq!(weekly_window["usage"]["request_count"], json!(3));
+    assert_eq!(weekly_window["usage"]["total_tokens"], json!(375));
+    assert_eq!(
+        weekly_window["usage"]["total_cost_usd"],
+        json!("0.60000000")
+    );
+    assert_eq!(usage_key_payload["request_count"], json!(4));
+    assert_eq!(usage_key_payload["total_tokens"], json!(999));
+    assert_eq!(usage_key_payload["total_cost_usd"], json!("9.99000000"));
+
+    let zero_key_payload = key_by_id(keys, "key-codex-zero");
+    assert_eq!(
+        window_by_code(zero_key_payload, "5h")["usage"]["request_count"],
+        json!(0)
+    );
+    assert_eq!(
+        window_by_code(zero_key_payload, "weekly")["usage"]["total_tokens"],
+        json!(0)
+    );
+
+    let invalid_key_payload = key_by_id(keys, "key-codex-invalid");
+    assert!(window_by_code(invalid_key_payload, "5h")
+        .get("usage")
+        .is_none());
+    assert!(window_by_code(invalid_key_payload, "weekly")
+        .get("usage")
+        .is_none());
+}
+
 #[tokio::test]
 async fn gateway_marks_account_blocked_pool_key_in_list_keys_response() {
     let mut provider = sample_provider("provider-codex", "codex", 10).with_transport_fields(

crates/aether-data-contracts/src/repository/usage/mod.rs

@@ -2,7 +2,8 @@ mod types;
 
 pub use types::{
     parse_usage_body_ref, usage_body_ref, PendingUsageCleanupSummary,
-    StoredProviderApiKeyUsageSummary, StoredProviderUsageSummary, StoredProviderUsageWindow,
+    ProviderApiKeyWindowUsageRequest, StoredProviderApiKeyUsageSummary,
+    StoredProviderApiKeyWindowUsageSummary, StoredProviderUsageSummary, StoredProviderUsageWindow,
     StoredRequestUsageAudit, StoredUsageAuditAggregation, StoredUsageAuditSummary,
     StoredUsageBreakdownSummaryRow, StoredUsageCacheAffinityHitSummary,
     StoredUsageCacheAffinityIntervalRow, StoredUsageCacheHitSummary, StoredUsageCostSavingsSummary,

crates/aether-data-contracts/src/repository/usage/types.rs

@@ -619,6 +619,23 @@ pub struct StoredProviderApiKeyUsageSummary {
     pub last_used_at_unix_secs: Option<u64>,
 }
 
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub struct ProviderApiKeyWindowUsageRequest {
+    pub provider_api_key_id: String,
+    pub window_code: String,
+    pub start_unix_secs: u64,
+    pub end_unix_secs: u64,
+}
+
+#[derive(Debug, Clone, PartialEq, Default, serde::Serialize, serde::Deserialize)]
+pub struct StoredProviderApiKeyWindowUsageSummary {
+    pub provider_api_key_id: String,
+    pub window_code: String,
+    pub request_count: u64,
+    pub total_tokens: u64,
+    pub total_cost_usd: f64,
+}
+
 #[derive(Debug, Clone, PartialEq, Eq, Default, serde::Serialize, serde::Deserialize)]
 pub struct UsageAuditListQuery {
     pub created_from_unix_secs: Option<u64>,
@@ -1479,6 +1496,11 @@ pub trait UsageReadRepository: Send + Sync {
         crate::DataLayerError,
     >;
 
+    async fn summarize_usage_by_provider_api_key_windows(
+        &self,
+        requests: &[ProviderApiKeyWindowUsageRequest],
+    ) -> Result<Vec<StoredProviderApiKeyWindowUsageSummary>, crate::DataLayerError>;
+
     async fn summarize_provider_usage_since(
         &self,
         provider_id: &str,

crates/aether-data/src/repository/usage/memory.rs

@@ -30,9 +30,10 @@ use super::{
     api_key_usage_contribution, provider_api_key_usage_contribution,
     strip_deprecated_usage_display_fields, usage_can_recover_terminal_failure,
     ApiKeyUsageContribution, ApiKeyUsageDelta, ProviderApiKeyUsageContribution,
-    ProviderApiKeyUsageDelta, StoredProviderApiKeyUsageSummary, StoredProviderUsageSummary,
+    ProviderApiKeyUsageDelta, ProviderApiKeyWindowUsageRequest, StoredProviderApiKeyUsageSummary,
-    StoredProviderUsageWindow, StoredRequestUsageAudit, StoredUsageDailySummary, UpsertUsageRecord,
+    StoredProviderApiKeyWindowUsageSummary, StoredProviderUsageSummary, StoredProviderUsageWindow,
-    UsageAuditListQuery, UsageDailyHeatmapQuery, UsageReadRepository, UsageWriteRepository,
+    StoredRequestUsageAudit, StoredUsageDailySummary, UpsertUsageRecord, UsageAuditListQuery,
+    UsageDailyHeatmapQuery, UsageReadRepository, UsageWriteRepository,
 };
 use crate::repository::auth::InMemoryAuthApiKeySnapshotRepository;
 use crate::repository::provider_catalog::InMemoryProviderCatalogReadRepository;
@@ -2327,6 +2328,59 @@ impl UsageReadRepository for InMemoryUsageReadRepository {
         Ok(summaries)
     }
 
+    async fn summarize_usage_by_provider_api_key_windows(
+        &self,
+        requests: &[ProviderApiKeyWindowUsageRequest],
+    ) -> Result<Vec<StoredProviderApiKeyWindowUsageSummary>, DataLayerError> {
+        let usage = self.by_request_id.read().expect("usage repository lock");
+        let mut summaries = Vec::with_capacity(requests.len());
+
+        for request in requests {
+            let provider_api_key_id = request.provider_api_key_id.trim();
+            if provider_api_key_id.is_empty() {
+                return Err(DataLayerError::InvalidInput(
+                    "provider api key window usage provider_api_key_id cannot be empty".to_string(),
+                ));
+            }
+            let window_code = request.window_code.trim();
+            if window_code.is_empty() {
+                return Err(DataLayerError::InvalidInput(
+                    "provider api key window usage window_code cannot be empty".to_string(),
+                ));
+            }
+            if request.start_unix_secs >= request.end_unix_secs {
+                return Err(DataLayerError::InvalidInput(
+                    "provider api key window usage range must be non-empty".to_string(),
+                ));
+            }
+
+            let mut summary = StoredProviderApiKeyWindowUsageSummary {
+                provider_api_key_id: provider_api_key_id.to_string(),
+                window_code: window_code.to_string(),
+                ..StoredProviderApiKeyWindowUsageSummary::default()
+            };
+
+            for item in usage.values() {
+                if item.provider_api_key_id.as_deref() != Some(provider_api_key_id) {
+                    continue;
+                }
+                if item.created_at_unix_ms < request.start_unix_secs
+                    || item.created_at_unix_ms >= request.end_unix_secs
+                {
+                    continue;
+                }
+
+                summary.request_count = summary.request_count.saturating_add(1);
+                summary.total_tokens = summary.total_tokens.saturating_add(item.total_tokens);
+                summary.total_cost_usd += item.total_cost_usd;
+            }
+
+            summaries.push(summary);
+        }
+
+        Ok(summaries)
+    }
+
     async fn summarize_provider_usage_since(
         &self,
         provider_id: &str,
@@ -2934,8 +2988,9 @@ mod tests {
         UsageWriteRepository,
     };
     use aether_data_contracts::repository::usage::{
-        usage_body_ref, UsageAuditAggregationGroupBy, UsageAuditAggregationQuery, UsageBodyField,
+        usage_body_ref, ProviderApiKeyWindowUsageRequest, UsageAuditAggregationGroupBy,
-        UsageProviderPerformanceQuery, UsageTimeSeriesGranularity,
+        UsageAuditAggregationQuery, UsageBodyField, UsageProviderPerformanceQuery,
+        UsageTimeSeriesGranularity,
     };
     use serde_json::json;
 
@@ -4533,6 +4588,44 @@ mod tests {
         assert_eq!(item.last_used_at_unix_secs, Some(1_711_000_250));
     }
 
+    #[tokio::test]
+    async fn summarizes_provider_api_key_window_usage_with_zero_rows() {
+        let repository = InMemoryUsageReadRepository::seed(vec![
+            sample_usage("req-1", 1_711_000_000),
+            sample_usage("req-2", 1_711_000_250),
+        ]);
+
+        let usage = repository
+            .summarize_usage_by_provider_api_key_windows(&[
+                ProviderApiKeyWindowUsageRequest {
+                    provider_api_key_id: "provider-key-1".to_string(),
+                    window_code: "5h".to_string(),
+                    start_unix_secs: 1_711_000_000,
+                    end_unix_secs: 1_711_000_300,
+                },
+                ProviderApiKeyWindowUsageRequest {
+                    provider_api_key_id: "provider-key-empty".to_string(),
+                    window_code: "weekly".to_string(),
+                    start_unix_secs: 1_711_000_000,
+                    end_unix_secs: 1_711_000_300,
+                },
+            ])
+            .await
+            .expect("window summary should succeed");
+
+        assert_eq!(usage.len(), 2);
+        assert_eq!(usage[0].provider_api_key_id, "provider-key-1");
+        assert_eq!(usage[0].window_code, "5h");
+        assert_eq!(usage[0].request_count, 2);
+        assert_eq!(usage[0].total_tokens, 300);
+        assert_eq!(usage[0].total_cost_usd, 0.24);
+        assert_eq!(usage[1].provider_api_key_id, "provider-key-empty");
+        assert_eq!(usage[1].window_code, "weekly");
+        assert_eq!(usage[1].request_count, 0);
+        assert_eq!(usage[1].total_tokens, 0);
+        assert_eq!(usage[1].total_cost_usd, 0.0);
+    }
+
     #[tokio::test]
     async fn list_usage_audits_applies_second_based_time_filters() {
         let repository = InMemoryUsageReadRepository::seed(vec![

crates/aether-data/src/repository/usage/mod.rs

@@ -319,6 +319,17 @@ macro_rules! impl_materialized_usage_read_repository {
                 <$crate::repository::usage::InMemoryUsageReadRepository as $crate::repository::usage::UsageReadRepository>::summarize_usage_by_provider_api_key_ids(&repository, provider_api_key_ids).await
             }
 
+            async fn summarize_usage_by_provider_api_key_windows(
+                &self,
+                requests: &[$crate::repository::usage::ProviderApiKeyWindowUsageRequest],
+            ) -> Result<
+                Vec<$crate::repository::usage::StoredProviderApiKeyWindowUsageSummary>,
+                $crate::DataLayerError,
+            > {
+                let repository = self.materialize_read_model().await?;
+                <$crate::repository::usage::InMemoryUsageReadRepository as $crate::repository::usage::UsageReadRepository>::summarize_usage_by_provider_api_key_windows(&repository, requests).await
+            }
+
             async fn summarize_provider_usage_since(
                 &self,
                 provider_id: &str,
@@ -352,9 +363,10 @@ mod sqlite;
 
 #[allow(unused_imports)]
 pub(crate) use aether_data_contracts::repository::usage::{
-    PendingUsageCleanupSummary, StoredProviderApiKeyUsageSummary, StoredProviderUsageSummary,
+    PendingUsageCleanupSummary, ProviderApiKeyWindowUsageRequest, StoredProviderApiKeyUsageSummary,
-    StoredProviderUsageWindow, StoredRequestUsageAudit, StoredUsageAuditAggregation,
+    StoredProviderApiKeyWindowUsageSummary, StoredProviderUsageSummary, StoredProviderUsageWindow,
-    StoredUsageAuditSummary, StoredUsageBreakdownSummaryRow, StoredUsageCacheAffinityHitSummary,
+    StoredRequestUsageAudit, StoredUsageAuditAggregation, StoredUsageAuditSummary,
+    StoredUsageBreakdownSummaryRow, StoredUsageCacheAffinityHitSummary,
     StoredUsageCacheAffinityIntervalRow, StoredUsageCacheHitSummary, StoredUsageCostSavingsSummary,
     StoredUsageDailySummary, StoredUsageDashboardDailyBreakdownRow,
     StoredUsageDashboardProviderCount, StoredUsageDashboardSummary,

crates/aether-data/src/repository/usage/postgres/mod.rs

@@ -38,7 +38,8 @@ use super::{
     api_key_usage_contribution, incoming_usage_can_recover_terminal_failure,
     model_usage_contribution, provider_api_key_usage_contribution,
     strip_deprecated_usage_display_fields, ApiKeyUsageDelta, ModelUsageDelta,
-    PendingUsageCleanupSummary, ProviderApiKeyUsageDelta, StoredProviderApiKeyUsageSummary,
+    PendingUsageCleanupSummary, ProviderApiKeyUsageDelta, ProviderApiKeyWindowUsageRequest,
+    StoredProviderApiKeyUsageSummary, StoredProviderApiKeyWindowUsageSummary,
     StoredProviderUsageSummary, StoredRequestUsageAudit, StoredUsageDailySummary,
     UpsertUsageRecord, UsageAuditListQuery, UsageDailyHeatmapQuery, UsageReadRepository,
     UsageWriteRepository,
@@ -1314,6 +1315,9 @@ const SUMMARIZE_USAGE_TOTALS_BY_USER_IDS_SQL: &str =
 const SUMMARIZE_USAGE_BY_PROVIDER_API_KEY_IDS_SQL: &str =
     include_str!("queries/summarize_usage_by_provider_api_key_ids_sql.sql");
 
+const SUMMARIZE_PROVIDER_API_KEY_WINDOW_USAGE_SQL: &str =
+    include_str!("queries/summarize_provider_api_key_window_usage_sql.sql");
+
 const APPLY_API_KEY_USAGE_DELTA_SQL: &str =
     include_str!("queries/apply_api_key_usage_delta_sql.sql");
 
@@ -7225,6 +7229,98 @@ ORDER BY "usage".user_id ASC
         Ok(summaries)
     }
 
+    pub async fn summarize_usage_by_provider_api_key_windows(
+        &self,
+        requests: &[ProviderApiKeyWindowUsageRequest],
+    ) -> Result<Vec<StoredProviderApiKeyWindowUsageSummary>, DataLayerError> {
+        if requests.is_empty() {
+            return Ok(Vec::new());
+        }
+
+        let mut provider_api_key_ids = Vec::with_capacity(requests.len());
+        let mut window_codes = Vec::with_capacity(requests.len());
+        let mut start_unix_secs = Vec::with_capacity(requests.len());
+        let mut end_unix_secs = Vec::with_capacity(requests.len());
+
+        for request in requests {
+            let provider_api_key_id = request.provider_api_key_id.trim();
+            if provider_api_key_id.is_empty() {
+                return Err(DataLayerError::InvalidInput(
+                    "provider api key window usage provider_api_key_id cannot be empty".to_string(),
+                ));
+            }
+            let window_code = request.window_code.trim();
+            if window_code.is_empty() {
+                return Err(DataLayerError::InvalidInput(
+                    "provider api key window usage window_code cannot be empty".to_string(),
+                ));
+            }
+            if request.start_unix_secs >= request.end_unix_secs {
+                return Err(DataLayerError::InvalidInput(
+                    "provider api key window usage range must be non-empty".to_string(),
+                ));
+            }
+
+            provider_api_key_ids.push(provider_api_key_id.to_string());
+            window_codes.push(window_code.to_string());
+            start_unix_secs.push(i64::try_from(request.start_unix_secs).map_err(|_| {
+                DataLayerError::InvalidInput(
+                    "provider api key window usage start_unix_secs is out of range".to_string(),
+                )
+            })?);
+            end_unix_secs.push(i64::try_from(request.end_unix_secs).map_err(|_| {
+                DataLayerError::InvalidInput(
+                    "provider api key window usage end_unix_secs is out of range".to_string(),
+                )
+            })?);
+        }
+
+        let mut rows = sqlx::query(SUMMARIZE_PROVIDER_API_KEY_WINDOW_USAGE_SQL)
+            .bind(&provider_api_key_ids)
+            .bind(&window_codes)
+            .bind(&start_unix_secs)
+            .bind(&end_unix_secs)
+            .fetch(&self.pool);
+
+        let mut summaries = Vec::new();
+        while let Some(row) = rows.try_next().await.map_postgres_err()? {
+            let total_cost_usd = row.try_get::<f64, _>("total_cost_usd").map_postgres_err()?;
+            if !total_cost_usd.is_finite() {
+                return Err(DataLayerError::UnexpectedValue(
+                    "usage.total_cost_usd window aggregate is not finite".to_string(),
+                ));
+            }
+
+            summaries.push(StoredProviderApiKeyWindowUsageSummary {
+                provider_api_key_id: row
+                    .try_get::<String, _>("provider_api_key_id")
+                    .map_postgres_err()?,
+                window_code: row.try_get::<String, _>("window_code").map_postgres_err()?,
+                request_count: row
+                    .try_get::<i64, _>("request_count")
+                    .map_postgres_err()?
+                    .try_into()
+                    .map_err(|_| {
+                        DataLayerError::UnexpectedValue(
+                            "usage.request_count window aggregate is negative".to_string(),
+                        )
+                    })?,
+                total_tokens: row
+                    .try_get::<i64, _>("total_tokens")
+                    .map_postgres_err()?
+                    .try_into()
+                    .map_err(|_| {
+                        DataLayerError::UnexpectedValue(
+                            "usage.total_tokens window aggregate is negative".to_string(),
+                        )
+                    })?,
+                total_cost_usd,
+            });
+        }
+
+        Ok(summaries)
+    }
+
     pub async fn upsert(
         &self,
         usage: UpsertUsageRecord,
@@ -8044,6 +8140,13 @@ impl UsageReadRepository for SqlxUsageReadRepository {
         Self::summarize_usage_by_provider_api_key_ids(self, provider_api_key_ids).await
     }
 
+    async fn summarize_usage_by_provider_api_key_windows(
+        &self,
+        requests: &[ProviderApiKeyWindowUsageRequest],
+    ) -> Result<Vec<StoredProviderApiKeyWindowUsageSummary>, DataLayerError> {
+        Self::summarize_usage_by_provider_api_key_windows(self, requests).await
+    }
+
     async fn summarize_provider_usage_since(
         &self,
         provider_id: &str,

crates/aether-data/src/repository/usage/postgres/queries/summarize_provider_api_key_window_usage_sql.sql

@@ -0,0 +1,36 @@
+WITH requested AS (
+  SELECT
+    request_row.provider_api_key_id,
+    request_row.window_code,
+    request_row.start_unix_secs,
+    request_row.end_unix_secs,
+    request_row.ordinality
+  FROM UNNEST(
+    $1::TEXT[],
+    $2::TEXT[],
+    $3::BIGINT[],
+    $4::BIGINT[]
+  ) WITH ORDINALITY AS request_row(
+    provider_api_key_id,
+    window_code,
+    start_unix_secs,
+    end_unix_secs,
+    ordinality
+  )
+)
+SELECT
+  requested.provider_api_key_id,
+  requested.window_code,
+  COUNT("usage".id)::BIGINT AS request_count,
+  COALESCE(SUM("usage".total_tokens), 0)::BIGINT AS total_tokens,
+  CAST(COALESCE(SUM("usage".total_cost_usd), 0) AS DOUBLE PRECISION) AS total_cost_usd
+FROM requested
+LEFT JOIN usage_billing_facts AS "usage"
+  ON "usage".provider_api_key_id = requested.provider_api_key_id
+ AND "usage".created_at >= to_timestamp(requested.start_unix_secs::DOUBLE PRECISION)
+ AND "usage".created_at < to_timestamp(requested.end_unix_secs::DOUBLE PRECISION)
+GROUP BY
+  requested.provider_api_key_id,
+  requested.window_code,
+  requested.ordinality
+ORDER BY requested.ordinality ASC

crates/aether-data/src/repository/usage/postgres/tests.rs

@@ -234,6 +234,21 @@ fn usage_sql_summarizes_usage_by_provider_api_key_ids_in_database() {
     assert!(super::SUMMARIZE_USAGE_BY_PROVIDER_API_KEY_IDS_SQL.contains("ANY($1::TEXT[])"));
 }
 
+#[test]
+fn usage_sql_summarizes_provider_key_window_usage_from_billing_facts() {
+    assert!(super::SUMMARIZE_PROVIDER_API_KEY_WINDOW_USAGE_SQL.contains("UNNEST"));
+    assert!(super::SUMMARIZE_PROVIDER_API_KEY_WINDOW_USAGE_SQL
+        .contains("LEFT JOIN usage_billing_facts AS \"usage\""));
+    assert!(
+        super::SUMMARIZE_PROVIDER_API_KEY_WINDOW_USAGE_SQL.contains("created_at >= to_timestamp")
+    );
+    assert!(
+        super::SUMMARIZE_PROVIDER_API_KEY_WINDOW_USAGE_SQL.contains("created_at < to_timestamp")
+    );
+    assert!(super::SUMMARIZE_PROVIDER_API_KEY_WINDOW_USAGE_SQL
+        .contains("COUNT(\"usage\".id)::BIGINT AS request_count"));
+}
+
 #[test]
 fn usage_sql_serializes_request_id_upserts_before_reading_previous_usage() {
     assert!(super::LOCK_USAGE_REQUEST_ID_SQL.contains("pg_advisory_xact_lock"));
@@ -455,6 +470,8 @@ fn usage_sql_raw_aggregates_use_canonical_billing_facts() {
         .contains("FROM usage_billing_facts AS \"usage\""));
     assert!(super::SUMMARIZE_USAGE_TOTALS_BY_USER_IDS_SQL
         .contains("FROM usage_billing_facts AS \"usage\""));
+    assert!(super::SUMMARIZE_PROVIDER_API_KEY_WINDOW_USAGE_SQL
+        .contains("usage_billing_facts AS \"usage\""));
 }
 
 #[test]

frontend/src/api/endpoints/types/statusSnapshot.ts

@@ -18,6 +18,12 @@ export interface AccountStatusSnapshot {
   recoverable?: boolean
 }
 
+export interface QuotaWindowUsageSnapshot {
+  request_count?: number | null
+  total_tokens?: number | null
+  total_cost_usd?: number | string | null
+}
+
 export interface QuotaWindowSnapshot {
   code: string
   label?: string | null
@@ -33,6 +39,7 @@ export interface QuotaWindowSnapshot {
   reset_seconds?: number | null
   window_minutes?: number | null
   is_exhausted?: boolean | null
+  usage?: QuotaWindowUsageSnapshot | null
 }
 
 export interface QuotaCreditsSnapshot {

frontend/src/features/pool/utils/__tests__/poolManagementState.spec.ts

@@ -39,6 +39,7 @@ describe('poolManagementState', () => {
         pageSize: 20,
         sortBy: 'last_used_at',
         sortOrder: 'asc',
+        statsMode: 'account_total',
       },
       storage,
     )
@@ -52,6 +53,7 @@ describe('poolManagementState', () => {
         pageSize: '100',
         sortBy: 'imported_at',
         sortOrder: 'desc',
+        statsMode: 'current_cycle',
       },
       storage,
     )
@@ -64,6 +66,7 @@ describe('poolManagementState', () => {
       pageSize: 100,
       sortBy: 'imported_at',
       sortOrder: 'desc',
+      statsMode: 'current_cycle',
     })
   })
 
@@ -77,6 +80,7 @@ describe('poolManagementState', () => {
         pageSize: 50,
         sortBy: 'last_used_at',
         sortOrder: 'asc',
+        statsMode: 'account_total',
       },
       storage,
     )
@@ -91,6 +95,7 @@ describe('poolManagementState', () => {
       pageSize: 50,
       sortBy: 'last_used_at',
       sortOrder: 'asc',
+      statsMode: 'account_total',
     })
   })
 
@@ -104,6 +109,7 @@ describe('poolManagementState', () => {
         pageSize: 50,
         sortBy: null,
         sortOrder: 'desc',
+        statsMode: 'current_cycle',
       }),
     ).toEqual({
       providerId: 'provider-d',
@@ -113,6 +119,7 @@ describe('poolManagementState', () => {
       pageSize: undefined,
       sortBy: undefined,
       sortOrder: undefined,
+      statsMode: undefined,
     })
   })
 
@@ -126,13 +133,36 @@ describe('poolManagementState', () => {
         pageSize: 50,
         sortBy: 'last_used_at',
         sortOrder: 'asc',
+        statsMode: 'account_total',
       }),
     ).toMatchObject({
       sortBy: 'last_used_at',
       sortOrder: 'asc',
+      statsMode: 'account_total',
     })
   })
 
+  it('restores stats mode from storage and lets query override it', () => {
+    writePoolManagementViewState(
+      {
+        providerId: 'provider-f',
+        search: '',
+        status: 'all',
+        page: 1,
+        pageSize: 50,
+        sortBy: null,
+        sortOrder: 'desc',
+        statsMode: 'account_total',
+      },
+      storage,
+    )
+
+    expect(readPoolManagementViewState({}, storage).statsMode).toBe('account_total')
+    expect(
+      readPoolManagementViewState({ statsMode: 'current_cycle' }, storage).statsMode,
+    ).toBe('current_cycle')
+  })
+
   it('clamps a restored page to the last available page after load', () => {
     expect(
       resolvePoolManagementPageAfterLoad({

frontend/src/features/pool/utils/__tests__/poolStatsDisplay.spec.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  buildPoolStatsDisplay,
+  type PoolStatsKeyInput,
+} from '@/features/pool/utils/poolStatsDisplay'
+
+function metricValues(metrics: Array<{ key: string, value: string }>) {
+  return Object.fromEntries(metrics.map(metric => [metric.key, metric.value]))
+}
+
+function createCodexKey(overrides: Partial<PoolStatsKeyInput> = {}): PoolStatsKeyInput {
+  return {
+    request_count: 1234,
+    total_tokens: 5678000,
+    total_cost_usd: '12.3456',
+    status_snapshot: {
+      quota: {
+        windows: [
+          {
+            code: '5h',
+            usage: {
+              request_count: 5,
+              total_tokens: 2500,
+              total_cost_usd: '0.0045',
+            },
+          },
+          {
+            code: 'weekly',
+            usage: {
+              request_count: 0,
+              total_tokens: 0,
+              total_cost_usd: '0.00000000',
+            },
+          },
+        ],
+      },
+    },
+    ...overrides,
+  }
+}
+
+describe('poolStatsDisplay', () => {
+  it('builds Codex current-cycle groups in 5H and weekly order', () => {
+    const display = buildPoolStatsDisplay(createCodexKey(), 'codex', 'current_cycle')
+
+    expect(display.kind).toBe('codex_cycle')
+    if (display.kind !== 'codex_cycle') throw new Error('expected codex cycle display')
+
+    expect(display.groups.map(group => group.label)).toEqual(['5H', '周'])
+    expect(metricValues(display.groups[0].metrics)).toEqual({
+      request_count: '5',
+      total_tokens: '2.5K',
+      total_cost_usd: '$0.0045',
+    })
+    expect(metricValues(display.groups[1].metrics)).toEqual({
+      request_count: '0',
+      total_tokens: '0',
+      total_cost_usd: '0',
+    })
+  })
+
+  it('renders missing cycle usage as dashes instead of account-total fallback', () => {
+    const display = buildPoolStatsDisplay(
+      createCodexKey({
+        status_snapshot: {
+          quota: {
+            windows: [{ code: '5h', usage: null }],
+          },
+        },
+      }),
+      'codex',
+      'current_cycle',
+    )
+
+    expect(display.kind).toBe('codex_cycle')
+    if (display.kind !== 'codex_cycle') throw new Error('expected codex cycle display')
+
+    expect(metricValues(display.groups[0].metrics)).toEqual({
+      request_count: '—',
+      total_tokens: '—',
+      total_cost_usd: '—',
+    })
+    expect(metricValues(display.groups[1].metrics)).toEqual({
+      request_count: '—',
+      total_tokens: '—',
+      total_cost_usd: '—',
+    })
+  })
+
+  it('preserves account-total formatting when toggled away from current cycle', () => {
+    const display = buildPoolStatsDisplay(createCodexKey(), 'codex', 'account_total')
+
+    expect(display.kind).toBe('account_total')
+    if (display.kind !== 'account_total') throw new Error('expected account total display')
+
+    expect(metricValues(display.metrics)).toEqual({
+      request_count: '1,234',
+      total_tokens: '5.7M',
+      total_cost_usd: '$12.35',
+    })
+  })
+
+  it('keeps non-Codex providers on account totals even in current-cycle mode', () => {
+    const display = buildPoolStatsDisplay(createCodexKey(), 'openai', 'current_cycle')
+
+    expect(display.kind).toBe('account_total')
+    if (display.kind !== 'account_total') throw new Error('expected account total display')
+    expect(metricValues(display.metrics)).toMatchObject({
+      request_count: '1,234',
+      total_tokens: '5.7M',
+      total_cost_usd: '$12.35',
+    })
+  })
+})

frontend/src/features/pool/utils/poolManagementState.ts

@@ -1,6 +1,7 @@
 export type PoolManagementStatus = 'all' | 'active' | 'cooldown' | 'inactive'
 export type PoolManagementSortBy = 'imported_at' | 'last_used_at'
 export type PoolManagementSortOrder = 'asc' | 'desc'
+export type PoolManagementStatsMode = 'current_cycle' | 'account_total'
 
 export interface PoolManagementViewState {
   providerId: string | null
@@ -10,6 +11,7 @@ export interface PoolManagementViewState {
   pageSize: number
   sortBy: PoolManagementSortBy | null
   sortOrder: PoolManagementSortOrder
+  statsMode: PoolManagementStatsMode
 }
 
 export interface PoolManagementStateSource {
@@ -20,6 +22,7 @@ export interface PoolManagementStateSource {
   pageSize?: string
   sortBy?: string
   sortOrder?: string
+  statsMode?: string
 }
 
 export interface StorageLike {
@@ -28,6 +31,10 @@ export interface StorageLike {
   removeItem(key: string): void
 }
 
+type PoolManagementViewStateInput = Partial<{
+  [Key in keyof PoolManagementViewState]: unknown
+}>
+
 export const POOL_MANAGEMENT_VIEW_STORAGE_KEY = 'aether:pool-management:view-state'
 
 export const DEFAULT_POOL_MANAGEMENT_VIEW_STATE: PoolManagementViewState = {
@@ -38,6 +45,7 @@ export const DEFAULT_POOL_MANAGEMENT_VIEW_STATE: PoolManagementViewState = {
   pageSize: 50,
   sortBy: null,
   sortOrder: 'desc',
+  statsMode: 'current_cycle',
 }
 
 function normalizeProviderId(value: unknown): string | null {
@@ -75,7 +83,11 @@ function normalizeSortOrder(value: unknown): PoolManagementSortOrder {
   return value === 'asc' ? 'asc' : 'desc'
 }
 
-function normalizeViewState(input: Partial<PoolManagementViewState>): PoolManagementViewState {
+function normalizeStatsMode(value: unknown): PoolManagementStatsMode {
+  return value === 'account_total' ? 'account_total' : 'current_cycle'
+}
+
+function normalizeViewState(input: PoolManagementViewStateInput): PoolManagementViewState {
   return {
     providerId: normalizeProviderId(input.providerId),
     search: normalizeSearch(input.search),
@@ -84,6 +96,7 @@ function normalizeViewState(input: Partial<PoolManagementViewState>): PoolManage
     pageSize: normalizePositiveInteger(input.pageSize, DEFAULT_POOL_MANAGEMENT_VIEW_STATE.pageSize),
     sortBy: normalizeSortBy(input.sortBy),
     sortOrder: normalizeSortOrder(input.sortOrder),
+    statsMode: normalizeStatsMode(input.statsMode),
   }
 }
 
@@ -106,15 +119,20 @@ export function readPoolManagementViewState(
 ): PoolManagementViewState {
   const stored = normalizeViewState(readStoredState(storage))
 
-  return normalizeViewState({
+  return {
-    providerId: source.providerId ?? stored.providerId,
+    providerId: source.providerId !== undefined ? normalizeProviderId(source.providerId) : stored.providerId,
-    search: source.search ?? stored.search,
+    search: source.search !== undefined ? normalizeSearch(source.search) : stored.search,
-    status: source.status ?? stored.status,
+    status: source.status !== undefined ? normalizeStatus(source.status) : stored.status,
-    page: source.page ?? stored.page,
+    page: source.page !== undefined
-    pageSize: source.pageSize ?? stored.pageSize,
+      ? normalizePositiveInteger(source.page, DEFAULT_POOL_MANAGEMENT_VIEW_STATE.page)
-    sortBy: source.sortBy ?? stored.sortBy,
+      : stored.page,
-    sortOrder: source.sortOrder ?? stored.sortOrder,
+    pageSize: source.pageSize !== undefined
-  })
+      ? normalizePositiveInteger(source.pageSize, DEFAULT_POOL_MANAGEMENT_VIEW_STATE.pageSize)
+      : stored.pageSize,
+    sortBy: source.sortBy !== undefined ? normalizeSortBy(source.sortBy) : stored.sortBy,
+    sortOrder: source.sortOrder !== undefined ? normalizeSortOrder(source.sortOrder) : stored.sortOrder,
+    statsMode: source.statsMode !== undefined ? normalizeStatsMode(source.statsMode) : stored.statsMode,
+  }
 }
 
 export function writePoolManagementViewState(
@@ -150,6 +168,7 @@ export function buildPoolManagementQueryPatch(
         : String(normalized.pageSize),
     sortBy: normalized.sortBy || undefined,
     sortOrder: normalized.sortBy ? normalized.sortOrder : undefined,
+    statsMode: normalized.statsMode === 'account_total' ? 'account_total' : undefined,
   }
 }
 

frontend/src/features/pool/utils/poolStatsDisplay.ts

@@ -0,0 +1,178 @@
+import type { QuotaWindowUsageSnapshot } from '@/api/endpoints/types/statusSnapshot'
+import type { PoolManagementStatsMode } from '@/features/pool/utils/poolManagementState'
+
+export type PoolStatsMetricKey = 'request_count' | 'total_tokens' | 'total_cost_usd'
+export type PoolStatsDisplayKind = 'account_total' | 'codex_cycle'
+export type PoolCodexCycleWindowCode = '5h' | 'weekly'
+
+export interface PoolStatsKeyInput {
+  request_count?: number | null
+  total_tokens?: number | null
+  total_cost_usd?: number | string | null
+  status_snapshot?: {
+    quota?: {
+      windows?: Array<{
+        code?: string | null
+        usage?: QuotaWindowUsageSnapshot | null
+      } | null> | null
+    } | null
+  } | null
+}
+
+export interface PoolStatsMetric {
+  key: PoolStatsMetricKey
+  label: string
+  value: string
+  missing: boolean
+}
+
+export interface PoolAccountTotalStatsDisplay {
+  kind: 'account_total'
+  metrics: PoolStatsMetric[]
+}
+
+export interface PoolCodexCycleStatsGroup {
+  code: PoolCodexCycleWindowCode
+  label: string
+  metrics: PoolStatsMetric[]
+}
+
+export interface PoolCodexCycleStatsDisplay {
+  kind: 'codex_cycle'
+  groups: PoolCodexCycleStatsGroup[]
+}
+
+export type PoolStatsDisplay = PoolAccountTotalStatsDisplay | PoolCodexCycleStatsDisplay
+
+const MISSING_STAT_VALUE = '—'
+const CODEX_CYCLE_WINDOWS: Array<{ code: PoolCodexCycleWindowCode, label: string }> = [
+  { code: '5h', label: '5H' },
+  { code: 'weekly', label: '周' },
+]
+
+export function isCodexProviderType(providerType: string | null | undefined): boolean {
+  return String(providerType || '').trim().toLowerCase() === 'codex'
+}
+
+export function formatPoolStatInteger(value: number | null | undefined): string {
+  const n = Number(value ?? 0)
+  if (!Number.isFinite(n) || n <= 0) return '0'
+  return Math.round(n).toLocaleString('en-US')
+}
+
+export function formatPoolTokenCount(value: number | null | undefined): string {
+  const n = Number(value ?? 0)
+  if (!Number.isFinite(n) || n <= 0) return '0'
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`
+  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}K`
+  return String(Math.round(n))
+}
+
+export function formatPoolStatUsd(value: number | string | null | undefined): string {
+  const n = Number(value ?? 0)
+  if (!Number.isFinite(n) || n <= 0) return '$0.00'
+  if (n < 0.01) return `$${n.toFixed(4)}`
+  if (n < 1) return `$${n.toFixed(3)}`
+  if (n < 1000) return `$${n.toFixed(2)}`
+  return `$${n.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`
+}
+
+function formatCycleInteger(value: number | null | undefined): string | null {
+  if (value == null) return null
+  const n = Number(value)
+  if (!Number.isFinite(n)) return null
+  if (n <= 0) return '0'
+  return Math.round(n).toLocaleString('en-US')
+}
+
+function formatCycleTokenCount(value: number | null | undefined): string | null {
+  if (value == null) return null
+  const n = Number(value)
+  if (!Number.isFinite(n)) return null
+  return formatPoolTokenCount(n)
+}
+
+function formatCycleUsd(value: number | string | null | undefined): string | null {
+  if (value == null) return null
+  const n = Number(value)
+  if (!Number.isFinite(n)) return null
+  if (n <= 0) return '0'
+  return formatPoolStatUsd(value)
+}
+
+function createMetric(
+  key: PoolStatsMetricKey,
+  label: string,
+  value: string | null,
+): PoolStatsMetric {
+  return {
+    key,
+    label,
+    value: value ?? MISSING_STAT_VALUE,
+    missing: value == null,
+  }
+}
+
+function normalizeWindowCode(value: unknown): string {
+  return String(value || '').trim().toLowerCase()
+}
+
+function getQuotaWindowUsage(
+  key: PoolStatsKeyInput,
+  code: PoolCodexCycleWindowCode,
+): QuotaWindowUsageSnapshot | null {
+  const windows = key.status_snapshot?.quota?.windows
+  if (!Array.isArray(windows)) return null
+
+  const window = windows.find(item => normalizeWindowCode(item?.code) === code)
+  return window?.usage ?? null
+}
+
+function buildAccountTotalMetrics(key: PoolStatsKeyInput): PoolStatsMetric[] {
+  return [
+    createMetric('request_count', '请求', formatPoolStatInteger(key.request_count)),
+    createMetric('total_tokens', 'Token', formatPoolTokenCount(key.total_tokens)),
+    createMetric('total_cost_usd', '费用', formatPoolStatUsd(key.total_cost_usd)),
+  ]
+}
+
+function buildCycleMetrics(usage: QuotaWindowUsageSnapshot | null): PoolStatsMetric[] {
+  return [
+    createMetric('request_count', '请求', formatCycleInteger(usage?.request_count)),
+    createMetric('total_tokens', 'Token', formatCycleTokenCount(usage?.total_tokens)),
+    createMetric('total_cost_usd', '费用', formatCycleUsd(usage?.total_cost_usd)),
+  ]
+}
+
+export function buildAccountTotalStatsDisplay(
+  key: PoolStatsKeyInput,
+): PoolAccountTotalStatsDisplay {
+  return {
+    kind: 'account_total',
+    metrics: buildAccountTotalMetrics(key),
+  }
+}
+
+export function buildCodexCycleStatsDisplay(
+  key: PoolStatsKeyInput,
+): PoolCodexCycleStatsDisplay {
+  return {
+    kind: 'codex_cycle',
+    groups: CODEX_CYCLE_WINDOWS.map(window => ({
+      ...window,
+      metrics: buildCycleMetrics(getQuotaWindowUsage(key, window.code)),
+    })),
+  }
+}
+
+export function buildPoolStatsDisplay(
+  key: PoolStatsKeyInput,
+  providerType: string | null | undefined,
+  mode: PoolManagementStatsMode,
+): PoolStatsDisplay {
+  if (isCodexProviderType(providerType) && mode === 'current_cycle') {
+    return buildCodexCycleStatsDisplay(key)
+  }
+
+  return buildAccountTotalStatsDisplay(key)
+}

frontend/src/views/admin/PoolManagement.vue

@@ -76,6 +76,34 @@
               />
             </div>
           </div>
+          <div
+            v-if="showCodexStatsModeSwitch"
+            class="flex items-center"
+            data-testid="pool-mobile-header-actions"
+          >
+            <div
+              class="group inline-flex min-h-12 flex-col items-center justify-center gap-1 rounded-md border border-border/50 bg-muted/20 px-2.5 py-1.5 text-xs transition-all duration-200 hover:border-primary/40 hover:bg-muted/40"
+              data-testid="pool-stats-mode-control"
+            >
+              <div class="flex items-center gap-1 leading-none">
+                <span
+                  class="font-medium transition-colors"
+                  :class="!codexCurrentCycleStatsEnabled ? 'text-foreground/90' : 'text-muted-foreground/80'"
+                >累计</span>
+                <span class="text-muted-foreground/50 transition-colors group-hover:text-muted-foreground/80">/</span>
+                <span
+                  class="font-medium transition-colors"
+                  :class="codexCurrentCycleStatsEnabled ? 'text-foreground/90' : 'text-muted-foreground/80'"
+                >周期</span>
+              </div>
+              <Switch
+                v-model="codexCurrentCycleStatsEnabled"
+                class="shrink-0"
+                aria-label="Codex 统计模式"
+                data-testid="pool-stats-mode-switch"
+              />
+            </div>
+          </div>
           <div
             v-if="selectedProviderId"
             class="flex items-center gap-1"
@@ -171,7 +199,10 @@
               </span>
             </h3>
           </div>
-          <div class="flex items-center gap-2">
+          <div
+            class="flex items-center gap-2"
+            data-testid="pool-header-actions"
+          >
             <Select
               v-model="selectedProviderIdProxy"
               :disabled="providerSelectDisabled"
@@ -228,6 +259,33 @@
               v-if="selectedProviderId"
               class="h-4 w-px bg-border"
             />
+            <div
+              v-if="showCodexStatsModeSwitch"
+              class="group inline-flex min-h-12 flex-col items-center justify-center gap-1 rounded-md border border-border/50 bg-muted/20 px-2.5 py-1.5 text-xs transition-all duration-200 hover:border-primary/40 hover:bg-muted/40"
+              data-testid="pool-stats-mode-control"
+            >
+              <div class="flex items-center gap-1 leading-none">
+                <span
+                  class="font-medium transition-colors"
+                  :class="!codexCurrentCycleStatsEnabled ? 'text-foreground/90' : 'text-muted-foreground/80'"
+                >累计</span>
+                <span class="text-muted-foreground/50 transition-colors group-hover:text-muted-foreground/80">/</span>
+                <span
+                  class="font-medium transition-colors"
+                  :class="codexCurrentCycleStatsEnabled ? 'text-foreground/90' : 'text-muted-foreground/80'"
+                >周期</span>
+              </div>
+              <Switch
+                v-model="codexCurrentCycleStatsEnabled"
+                class="shrink-0"
+                aria-label="Codex 统计模式"
+                data-testid="pool-stats-mode-switch"
+              />
+            </div>
+            <div
+              v-if="showCodexStatsModeSwitch"
+              class="h-4 w-px bg-border"
+            />
             <Button
               v-if="selectedProviderId"
               variant="ghost"
@@ -571,23 +629,44 @@
                   >-</span>
                 </TableCell>
                 <TableCell class="py-3 px-2 align-middle">
-                  <div class="grid grid-rows-3 gap-0.5 w-[136px] mx-auto text-[10px] leading-4">
+                  <div
-                    <div class="flex items-center justify-between gap-2">
+                    v-if="isPoolKeyCycleStatsDisplay(key)"
-                      <span class="text-muted-foreground">请求</span>
+                    class="mx-auto w-[136px] space-y-1.5 text-[10px] leading-4"
-                      <span class="tabular-nums text-foreground/90">
+                    data-testid="pool-stats-cycle-groups"
-                        {{ formatStatInteger(key.request_count) }}
+                  >
-                      </span>
+                    <div
+                      v-for="group in getPoolKeyCycleStatsGroups(key)"
+                      :key="`${key.key_id}-${group.code}-desktop-stats`"
+                      :data-testid="`pool-stats-cycle-group-${group.code}`"
+                    >
+                      <div class="text-[9px] text-muted-foreground/70 font-medium mb-0.5">{{ group.label }}</div>
+                      <div
+                        v-for="metric in group.metrics"
+                        :key="`${group.code}-${metric.key}`"
+                        class="flex items-center justify-between gap-2"
+                      >
+                        <span class="text-muted-foreground">{{ metric.label }}</span>
+                        <span
+                          class="tabular-nums text-foreground/90"
+                          :class="metric.missing ? 'text-muted-foreground/80' : ''"
+                          :data-testid="`pool-stats-${group.code}-${metric.key}`"
+                        >{{ metric.value }}</span>
+                      </div>
                     </div>
-                    <div class="flex items-center justify-between gap-2">
+                  </div>
-                      <span class="text-muted-foreground">Token</span>
+                  <div
+                    v-else
+                    class="grid grid-rows-3 gap-0.5 w-[136px] mx-auto text-[10px] leading-4"
+                    data-testid="pool-stats-account-total"
+                  >
+                    <div
+                      v-for="metric in getPoolKeyAccountStatsMetrics(key)"
+                      :key="`${key.key_id}-${metric.key}-account-total`"
+                      class="flex items-center justify-between gap-2"
+                    >
+                      <span class="text-muted-foreground">{{ metric.label }}</span>
                       <span class="tabular-nums text-foreground/90">
-                        {{ formatTokenCount(key.total_tokens) }}
+                        {{ metric.value }}
-                      </span>
-                    </div>
-                    <div class="flex items-center justify-between gap-2">
-                      <span class="text-muted-foreground">费用</span>
-                      <span class="tabular-nums text-foreground/90">
-                        {{ formatStatUsd(key.total_cost_usd) }}
                       </span>
                     </div>
                   </div>
@@ -787,16 +866,48 @@
               </div>
 
               <div class="overflow-x-auto rounded-xl border border-border/50 bg-muted/30 px-3 py-2 text-[11px] text-muted-foreground">
-                <div class="flex min-w-max items-center justify-center whitespace-nowrap text-center">
+                <div class="space-y-1 text-center">
-                  <span class="font-medium text-foreground/90">请求:{{ formatStatInteger(key.request_count) }}</span>
+                  <template v-if="isPoolKeyCycleStatsDisplay(key)">
-                  <span class="mx-1.5 text-muted-foreground/40">|</span>
+                    <div
-                  <span class="font-medium text-foreground/90">Token:{{ formatTokenCount(key.total_tokens) }}</span>
+                      v-for="group in getPoolKeyCycleStatsGroups(key)"
-                  <span class="mx-1.5 text-muted-foreground/40">|</span>
+                      :key="`${key.key_id}-${group.code}-mobile-stats`"
-                  <span class="font-medium text-foreground/90">费用:{{ formatStatUsd(key.total_cost_usd) }}</span>
+                      class="flex items-start gap-3 text-left"
-                  <span class="mx-1.5 text-muted-foreground/40">|</span>
+                      :data-testid="`pool-mobile-stats-cycle-group-${group.code}`"
-                  <span class="font-medium text-foreground/90">导入:{{ keyUiStateMap[key.key_id]?.importedAtRelative || '-' }}</span>
+                    >
-                  <span class="mx-1.5 text-muted-foreground/40">|</span>
+                      <span class="w-10 shrink-0 pt-0.5 text-[10px] font-semibold text-foreground">{{ group.label }}</span>
-                  <span class="font-medium text-foreground/90">最后使用:{{ keyUiStateMap[key.key_id]?.lastUsedRelative || '-' }}</span>
+                      <div class="min-w-0 flex-1 space-y-0.5">
+                        <div
+                          v-for="metric in group.metrics"
+                          :key="`${group.code}-${metric.key}-mobile`"
+                          class="flex items-center justify-between gap-2"
+                        >
+                          <span class="text-muted-foreground">{{ metric.label }}</span>
+                          <span
+                            class="font-medium text-foreground/90 tabular-nums"
+                            :class="metric.missing ? 'text-muted-foreground/80' : ''"
+                          >{{ metric.value }}</span>
+                        </div>
+                      </div>
+                    </div>
+                  </template>
+                  <template v-else>
+                    <div
+                      v-for="metric in getPoolKeyAccountStatsMetrics(key)"
+                      :key="`${key.key_id}-${metric.key}-mobile-account-total`"
+                      class="flex items-center justify-between gap-2"
+                    >
+                      <span class="text-muted-foreground">{{ metric.label }}</span>
+                      <span class="font-medium text-foreground/90">{{ metric.value }}</span>
+                    </div>
+                  </template>
+                  <div class="flex items-center justify-between gap-2 border-t border-border/40 pt-1 mt-1">
+                    <span class="text-muted-foreground">导入</span>
+                    <span class="font-medium text-foreground/90">{{ keyUiStateMap[key.key_id]?.importedAtRelative || '-' }}</span>
+                  </div>
+                  <div class="flex items-center justify-between gap-2">
+                    <span class="text-muted-foreground">最后使用</span>
+                    <span class="font-medium text-foreground/90">{{ keyUiStateMap[key.key_id]?.lastUsedRelative || '-' }}</span>
+                  </div>
                 </div>
               </div>
 
@@ -1146,6 +1257,7 @@ import {
   SortableTableHead,
   TableFilterMenu,
   TableCell,
+  Switch,
   Pagination,
   Popover,
   PopoverTrigger,
@@ -1209,9 +1321,16 @@ import {
   resolvePoolManagementPageAfterLoad,
   type PoolManagementSortBy,
   type PoolManagementSortOrder,
+  type PoolManagementStatsMode,
   type PoolManagementViewState,
   writePoolManagementViewState,
 } from '@/features/pool/utils/poolManagementState'
+import {
+  buildPoolStatsDisplay,
+  type PoolCodexCycleStatsGroup,
+  type PoolStatsDisplay,
+  type PoolStatsMetric,
+} from '@/features/pool/utils/poolStatsDisplay'
 import { getOAuthOrgBadge } from '@/utils/oauthIdentity'
 import { getOAuthRefreshFeedback } from '@/utils/oauthRefreshFeedback'
 import {
@@ -1253,6 +1372,7 @@ const restoredViewState = readPoolManagementViewState(
     pageSize: getQueryValue('pageSize'),
     sortBy: getQueryValue('sortBy'),
     sortOrder: getQueryValue('sortOrder'),
+    statsMode: getQueryValue('statsMode'),
   },
   poolManagementViewStorage,
 )
@@ -1476,6 +1596,14 @@ const selectedProviderType = computed(() => {
   return String(fromOverview || '').trim().toLowerCase()
 })
 
+const showCodexStatsModeSwitch = computed(() => selectedProviderType.value === 'codex')
+const codexCurrentCycleStatsEnabled = computed({
+  get: () => poolStatsMode.value === 'current_cycle',
+  set: (enabled: boolean) => {
+    poolStatsMode.value = enabled ? 'current_cycle' : 'account_total'
+  },
+})
+
 const selectedProviderStatusText = computed(() => {
   if (!selectedProviderId.value) return ''
   const providerActive = selectedProviderData.value?.is_active
@@ -1600,6 +1728,7 @@ const currentPage = ref(restoredViewState.page)
 const pageSize = ref(restoredViewState.pageSize)
 const sortBy = ref<PoolManagementSortBy | null>(restoredViewState.sortBy)
 const sortOrder = ref<PoolManagementSortOrder>(restoredViewState.sortOrder)
+const poolStatsMode = ref<PoolManagementStatsMode>(restoredViewState.statsMode)
 const hasPoolKeyFilters = computed(() => searchQuery.value.trim().length > 0 || statusFilter.value !== 'all')
 const MANUAL_QUOTA_REFRESH_COOLDOWN_SECONDS = 5 * 60
 const refreshingOAuthKeyId = ref<string | null>(null)
@@ -1681,6 +1810,18 @@ watch(
   { immediate: true },
 )
 
+watch(
+  () => readPoolManagementViewState(
+    { statsMode: getQueryValue('statsMode') },
+    poolManagementViewStorage,
+  ).statsMode,
+  (value) => {
+    if (poolStatsMode.value === value) return
+    poolStatsMode.value = value
+  },
+  { immediate: true },
+)
+
 watch(
   () => getQueryValue('providerId'),
   (value) => {
@@ -1697,8 +1838,8 @@ watch(
 )
 
 watch(
-  [selectedProviderId, searchQuery, statusFilter, currentPage, pageSize, sortBy, sortOrder],
+  [selectedProviderId, searchQuery, statusFilter, currentPage, pageSize, sortBy, sortOrder, poolStatsMode],
-  ([providerId, search, status, page, pageSizeValue, sortByValue, sortOrderValue]) => {
+  ([providerId, search, status, page, pageSizeValue, sortByValue, sortOrderValue, statsMode]) => {
     const nextState: PoolManagementViewState = {
       providerId,
       search,
@@ -1707,6 +1848,7 @@ watch(
       pageSize: pageSizeValue,
       sortBy: sortByValue,
       sortOrder: sortOrderValue,
+      statsMode: statsMode as PoolManagementStatsMode,
     }
     patchQuery(buildPoolManagementQueryPatch(nextState))
     writePoolManagementViewState(nextState, poolManagementViewStorage)
@@ -1739,6 +1881,7 @@ type PoolKeyUiState = {
   quotaTextClass: string
   importedAtRelative: string
   lastUsedRelative: string
+  statsDisplay: PoolStatsDisplay
   mobileTagItems: PoolMobileTagItem[]
   mobileActionIds: PoolMobileActionId[]
 }
@@ -1778,6 +1921,7 @@ const keyUiStateMap = computed<Record<string, PoolKeyUiState>>(() => {
       quotaTextClass: quotaFallbackText ? getQuotaTextClass(quotaFallbackText) : '',
       importedAtRelative: formatPoolKeyImportedAt(key),
       lastUsedRelative: key.last_used_at ? formatRelativeTime(key.last_used_at) : '-',
+      statsDisplay: buildPoolStatsDisplay(key, selectedProviderType.value, poolStatsMode.value),
       mobileTagItems: getMobileTagItems(key),
       mobileActionIds: splitPoolMobileActions({
         canDownloadOrCopy: true,
@@ -1791,6 +1935,27 @@ const keyUiStateMap = computed<Record<string, PoolKeyUiState>>(() => {
   return map
 })
 
+function getPoolKeyStatsDisplay(key: PoolKeyDetail): PoolStatsDisplay {
+  return keyUiStateMap.value[key.key_id]?.statsDisplay
+    ?? buildPoolStatsDisplay(key, selectedProviderType.value, poolStatsMode.value)
+}
+
+function isPoolKeyCycleStatsDisplay(key: PoolKeyDetail): boolean {
+  return getPoolKeyStatsDisplay(key).kind === 'codex_cycle'
+}
+
+function getPoolKeyCycleStatsGroups(key: PoolKeyDetail): PoolCodexCycleStatsGroup[] {
+  const display = getPoolKeyStatsDisplay(key)
+  return display.kind === 'codex_cycle' ? display.groups : []
+}
+
+function getPoolKeyAccountStatsMetrics(key: PoolKeyDetail): PoolStatsMetric[] {
+  const display = getPoolKeyStatsDisplay(key)
+  return display.kind === 'account_total'
+    ? display.metrics
+    : buildPoolStatsDisplay(key, selectedProviderType.value, 'account_total').metrics
+}
+
 const quotaRefreshSupported = computed(() => {
   return selectedProviderType.value === 'codex'
     || selectedProviderType.value === 'kiro'

frontend/src/views/admin/__tests__/PoolManagement.codex-cycle-stats.spec.ts

@@ -0,0 +1,599 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { createApp, nextTick, type App } from 'vue'
+
+import PoolManagement from '@/views/admin/PoolManagement.vue'
+import type { PoolKeyDetail, PoolOverviewItem, PoolKeysPageResponse } from '@/api/endpoints/pool'
+import { POOL_MANAGEMENT_VIEW_STORAGE_KEY } from '@/features/pool/utils/poolManagementState'
+
+const endpointMocks = vi.hoisted(() => ({
+  getPoolOverview: vi.fn(),
+  getPoolSchedulingPresets: vi.fn(),
+  listPoolKeys: vi.fn(),
+  clearPoolCooldown: vi.fn(),
+  getProvider: vi.fn(),
+  updateProvider: vi.fn(),
+  revealEndpointKey: vi.fn(),
+  exportKey: vi.fn(),
+  deleteEndpointKey: vi.fn(),
+  updateProviderKey: vi.fn(),
+  refreshProviderQuota: vi.fn(),
+  refreshProviderOAuth: vi.fn(),
+}))
+
+const routeMocks = vi.hoisted(() => ({
+  query: {} as Record<string, string>,
+  patchQuery: vi.fn((patch: Record<string, string | undefined | null>) => {
+    for (const [key, value] of Object.entries(patch)) {
+      if (value == null || String(value).trim() === '') {
+        delete routeMocks.query[key]
+      } else {
+        routeMocks.query[key] = String(value)
+      }
+    }
+  }),
+}))
+
+const proxyStoreMocks = vi.hoisted(() => ({
+  ensureLoaded: vi.fn(),
+}))
+
+vi.mock('@/api/endpoints/pool', () => ({
+  getPoolOverview: endpointMocks.getPoolOverview,
+  getPoolSchedulingPresets: endpointMocks.getPoolSchedulingPresets,
+  listPoolKeys: endpointMocks.listPoolKeys,
+  clearPoolCooldown: endpointMocks.clearPoolCooldown,
+}))
+
+vi.mock('@/api/endpoints/keys', () => ({
+  revealEndpointKey: endpointMocks.revealEndpointKey,
+  exportKey: endpointMocks.exportKey,
+  deleteEndpointKey: endpointMocks.deleteEndpointKey,
+  updateProviderKey: endpointMocks.updateProviderKey,
+  refreshProviderQuota: endpointMocks.refreshProviderQuota,
+}))
+
+vi.mock('@/api/endpoints/provider_oauth', () => ({
+  refreshProviderOAuth: endpointMocks.refreshProviderOAuth,
+}))
+
+vi.mock('@/api/endpoints', () => ({
+  getProvider: endpointMocks.getProvider,
+  updateProvider: endpointMocks.updateProvider,
+}))
+
+vi.mock('@/composables/useRouteQuery', () => ({
+  useRouteQuery: () => ({
+    getQueryValue: (key: string) => routeMocks.query[key],
+    patchQuery: routeMocks.patchQuery,
+  }),
+}))
+
+vi.mock('@/stores/proxy-nodes', () => ({
+  useProxyNodesStore: () => ({
+    nodes: [],
+    ensureLoaded: proxyStoreMocks.ensureLoaded,
+  }),
+}))
+
+vi.mock('@/composables/useToast', () => ({
+  useToast: () => ({
+    success: vi.fn(),
+    error: vi.fn(),
+    warning: vi.fn(),
+  }),
+}))
+
+vi.mock('@/composables/useConfirm', () => ({
+  useConfirm: () => ({
+    confirm: vi.fn().mockResolvedValue(true),
+  }),
+}))
+
+vi.mock('@/composables/useClipboard', () => ({
+  useClipboard: () => ({
+    copyToClipboard: vi.fn().mockResolvedValue(undefined),
+  }),
+}))
+
+vi.mock('@/composables/useCountdownTimer', async () => {
+  const { ref } = await import('vue')
+  return {
+    useCountdownTimer: () => ({
+      tick: ref(0),
+      start: vi.fn(),
+    }),
+    getCodexResetCountdown: () => ({
+      isExpired: false,
+      text: '1h',
+    }),
+  }
+})
+
+vi.mock('lucide-vue-next', async () => {
+  const { defineComponent, h } = await import('vue')
+  const Icon = defineComponent({
+    name: 'IconStub',
+    setup() {
+      return () => h('span')
+    },
+  })
+
+  return {
+    Search: Icon,
+    Upload: Icon,
+    ChevronDown: Icon,
+    RefreshCw: Icon,
+    Power: Icon,
+    Database: Icon,
+    KeyRound: Icon,
+    Download: Icon,
+    Copy: Icon,
+    Shield: Icon,
+    Globe: Icon,
+    SquarePen: Icon,
+    Trash2: Icon,
+    Users: Icon,
+    Settings2: Icon,
+    SlidersHorizontal: Icon,
+  }
+})
+
+vi.mock('@/components/ui', async () => {
+  const { defineComponent, h } = await import('vue')
+  const passthrough = (name: string, tag = 'div') => defineComponent({
+    name,
+    inheritAttrs: false,
+    setup(_, { attrs, slots }) {
+      return () => h(tag, attrs, slots.default?.())
+    },
+  })
+
+  const Button = defineComponent({
+    name: 'ButtonStub',
+    inheritAttrs: false,
+    props: {
+      disabled: Boolean,
+    },
+    setup(props, { attrs, slots }) {
+      return () => h('button', { ...attrs, disabled: props.disabled, type: attrs.type ?? 'button' }, slots.default?.())
+    },
+  })
+
+  const Input = defineComponent({
+    name: 'InputStub',
+    inheritAttrs: false,
+    props: {
+      modelValue: { type: [String, Number], default: '' },
+    },
+    emits: ['update:modelValue'],
+    setup(props, { attrs, emit }) {
+      return () => h('input', {
+        ...attrs,
+        value: props.modelValue ?? '',
+        onInput: (event: Event) => emit('update:modelValue', (event.target as HTMLInputElement).value),
+      })
+    },
+  })
+
+  const Switch = defineComponent({
+    name: 'SwitchStub',
+    inheritAttrs: false,
+    props: {
+      modelValue: Boolean,
+    },
+    emits: ['update:modelValue'],
+    setup(props, { attrs, emit }) {
+      return () => h('input', {
+        ...attrs,
+        type: 'checkbox',
+        role: 'switch',
+        checked: props.modelValue,
+        onChange: (event: Event) => emit('update:modelValue', (event.target as HTMLInputElement).checked),
+      })
+    },
+  })
+
+  const Pagination = defineComponent({
+    name: 'PaginationStub',
+    setup() {
+      return () => h('nav')
+    },
+  })
+
+  return {
+    Card: passthrough('CardStub'),
+    Badge: passthrough('BadgeStub', 'span'),
+    Button,
+    Input,
+    Select: passthrough('SelectStub'),
+    SelectTrigger: passthrough('SelectTriggerStub', 'button'),
+    SelectValue: passthrough('SelectValueStub', 'span'),
+    SelectContent: passthrough('SelectContentStub'),
+    SelectItem: passthrough('SelectItemStub'),
+    Table: passthrough('TableStub', 'table'),
+    TableHeader: passthrough('TableHeaderStub', 'thead'),
+    TableBody: passthrough('TableBodyStub', 'tbody'),
+    TableRow: passthrough('TableRowStub', 'tr'),
+    TableHead: passthrough('TableHeadStub', 'th'),
+    SortableTableHead: passthrough('SortableTableHeadStub', 'th'),
+    TableFilterMenu: passthrough('TableFilterMenuStub'),
+    TableCell: passthrough('TableCellStub', 'td'),
+    Switch,
+    Pagination,
+    Popover: passthrough('PopoverStub'),
+    PopoverTrigger: passthrough('PopoverTriggerStub'),
+    PopoverContent: passthrough('PopoverContentStub'),
+  }
+})
+
+vi.mock('@/components/ui/refresh-button.vue', async () => {
+  const { defineComponent, h } = await import('vue')
+  return {
+    default: defineComponent({
+      name: 'RefreshButtonStub',
+      setup(_, { attrs }) {
+        return () => h('button', attrs, '刷新')
+      },
+    }),
+  }
+})
+
+vi.mock('@/features/pool/components/PoolSchedulingDialog.vue', async () => {
+  const { defineComponent } = await import('vue')
+  return {
+    default: defineComponent({
+      name: 'PoolSchedulingDialogStub',
+      setup() {
+        return () => null
+      },
+    }),
+  }
+})
+vi.mock('@/features/pool/components/PoolAdvancedDialog.vue', async () => {
+  const { defineComponent } = await import('vue')
+  return {
+    default: defineComponent({
+      name: 'PoolAdvancedDialogStub',
+      setup() {
+        return () => null
+      },
+    }),
+  }
+})
+vi.mock('@/features/pool/components/PoolAccountBatchDialog.vue', async () => {
+  const { defineComponent } = await import('vue')
+  return {
+    default: defineComponent({
+      name: 'PoolAccountBatchDialogStub',
+      setup() {
+        return () => null
+      },
+    }),
+  }
+})
+vi.mock('@/features/pool/components/ProviderProxyPopover.vue', async () => {
+  const { defineComponent } = await import('vue')
+  return {
+    default: defineComponent({
+      name: 'ProviderProxyPopoverStub',
+      setup() {
+        return () => null
+      },
+    }),
+  }
+})
+vi.mock('@/features/providers/components/KeyAllowedModelsEditDialog.vue', async () => {
+  const { defineComponent } = await import('vue')
+  return {
+    default: defineComponent({
+      name: 'KeyAllowedModelsEditDialogStub',
+      setup() {
+        return () => null
+      },
+    }),
+  }
+})
+vi.mock('@/features/providers/components/KeyFormDialog.vue', async () => {
+  const { defineComponent } = await import('vue')
+  return {
+    default: defineComponent({
+      name: 'KeyFormDialogStub',
+      setup() {
+        return () => null
+      },
+    }),
+  }
+})
+vi.mock('@/features/providers/components/OAuthKeyEditDialog.vue', async () => {
+  const { defineComponent } = await import('vue')
+  return {
+    default: defineComponent({
+      name: 'OAuthKeyEditDialogStub',
+      setup() {
+        return () => null
+      },
+    }),
+  }
+})
+vi.mock('@/features/providers/components/OAuthAccountDialog.vue', async () => {
+  const { defineComponent } = await import('vue')
+  return {
+    default: defineComponent({
+      name: 'OAuthAccountDialogStub',
+      setup() {
+        return () => null
+      },
+    }),
+  }
+})
+vi.mock('@/features/providers/components/ProxyNodeSelect.vue', async () => {
+  const { defineComponent } = await import('vue')
+  return {
+    default: defineComponent({
+      name: 'ProxyNodeSelectStub',
+      setup() {
+        return () => null
+      },
+    }),
+  }
+})
+
+const mountedApps: Array<{ app: App, root: HTMLElement }> = []
+
+function createOverview(providerType: string): PoolOverviewItem {
+  return {
+    provider_id: `${providerType}-provider`,
+    provider_name: `${providerType} Provider`,
+    provider_type: providerType,
+    total_keys: 1,
+    active_keys: 1,
+    cooldown_count: 0,
+    pool_enabled: true,
+  }
+}
+
+function createProvider(providerType: string) {
+  return {
+    id: `${providerType}-provider`,
+    name: `${providerType} Provider`,
+    provider_type: providerType,
+    is_active: true,
+    api_formats: ['openai:chat'],
+    proxy: null,
+    pool_advanced: null,
+    claude_code_advanced: null,
+  }
+}
+
+function createPoolKey(providerType = 'codex', overrides: Partial<PoolKeyDetail> = {}): PoolKeyDetail {
+  return {
+    key_id: `${providerType}-key-1`,
+    key_name: `${providerType} key`,
+    is_active: true,
+    auth_type: 'api_key',
+    api_formats: ['openai:chat'],
+    internal_priority: 50,
+    account_quota: null,
+    cooldown_reason: null,
+    cooldown_ttl_seconds: null,
+    cost_window_usage: 0,
+    cost_limit: null,
+    request_count: 9876,
+    total_tokens: 4321000,
+    total_cost_usd: '8.7654',
+    sticky_sessions: 0,
+    lru_score: null,
+    created_at: '2026-05-05T00:00:00Z',
+    imported_at: '2026-05-05T00:00:00Z',
+    last_used_at: '2026-05-05T01:00:00Z',
+    status_snapshot: {
+      oauth: { code: 'none' },
+      account: { code: 'ok', blocked: false },
+      quota: {
+        code: 'ok',
+        exhausted: false,
+        provider_type: providerType,
+        windows: providerType === 'codex'
+          ? [
+              {
+                code: '5h',
+                remaining_ratio: 0.8,
+                usage: { request_count: 7, total_tokens: 2500, total_cost_usd: '0.0045' },
+              },
+              {
+                code: 'weekly',
+                remaining_ratio: 0.5,
+                usage: { request_count: 0, total_tokens: 0, total_cost_usd: '0.00000000' },
+              },
+            ]
+          : [],
+      },
+    },
+    ...overrides,
+  }
+}
+
+function createKeyPage(key: PoolKeyDetail): PoolKeysPageResponse {
+  return {
+    total: 1,
+    page: 1,
+    page_size: 50,
+    keys: [key],
+  }
+}
+
+function resetQuery() {
+  for (const key of Object.keys(routeMocks.query)) {
+    delete routeMocks.query[key]
+  }
+}
+
+function mountPoolManagement() {
+  const root = document.createElement('div')
+  document.body.appendChild(root)
+  const app = createApp(PoolManagement)
+  app.mount(root)
+  mountedApps.push({ app, root })
+  return root
+}
+
+async function settle() {
+  for (let index = 0; index < 8; index += 1) {
+    await Promise.resolve()
+    await nextTick()
+  }
+}
+
+function seedStoredStatsMode(statsMode: 'current_cycle' | 'account_total') {
+  window.sessionStorage.setItem(
+    POOL_MANAGEMENT_VIEW_STORAGE_KEY,
+    JSON.stringify({ statsMode }),
+  )
+}
+
+beforeEach(() => {
+  resetQuery()
+  window.sessionStorage.clear()
+  routeMocks.patchQuery.mockClear()
+  proxyStoreMocks.ensureLoaded.mockClear()
+
+  endpointMocks.getPoolOverview.mockReset()
+  endpointMocks.getPoolSchedulingPresets.mockReset()
+  endpointMocks.listPoolKeys.mockReset()
+  endpointMocks.clearPoolCooldown.mockReset()
+  endpointMocks.getProvider.mockReset()
+  endpointMocks.updateProvider.mockReset()
+  endpointMocks.revealEndpointKey.mockReset()
+  endpointMocks.exportKey.mockReset()
+  endpointMocks.deleteEndpointKey.mockReset()
+  endpointMocks.updateProviderKey.mockReset()
+  endpointMocks.refreshProviderQuota.mockReset()
+  endpointMocks.refreshProviderOAuth.mockReset()
+
+  endpointMocks.getPoolSchedulingPresets.mockResolvedValue([])
+  endpointMocks.clearPoolCooldown.mockResolvedValue({ message: 'ok' })
+  endpointMocks.refreshProviderQuota.mockResolvedValue({ success: 0, failed: 0 })
+})
+
+afterEach(() => {
+  for (const { app, root } of mountedApps.splice(0)) {
+    app.unmount()
+    root.remove()
+  }
+})
+
+describe('PoolManagement Codex cycle stats mode', () => {
+  it('defaults Codex providers to current-cycle groups and toggles back to account totals', async () => {
+    const codexKey = createPoolKey('codex')
+    endpointMocks.getPoolOverview.mockResolvedValue({ items: [createOverview('codex')] })
+    endpointMocks.listPoolKeys.mockResolvedValue(createKeyPage(codexKey))
+    endpointMocks.getProvider.mockResolvedValue(createProvider('codex'))
+
+    const root = mountPoolManagement()
+    await settle()
+
+    const modeSwitch = root.querySelector<HTMLInputElement>('[data-testid="pool-stats-mode-switch"]')
+    expect(modeSwitch).not.toBeNull()
+    expect(modeSwitch?.checked).toBe(true)
+    expect(root.querySelectorAll('[data-testid="pool-stats-cycle-group-5h"]').length).toBeGreaterThan(0)
+    expect(root.querySelectorAll('[data-testid="pool-stats-cycle-group-weekly"]').length).toBeGreaterThan(0)
+    expect(root.querySelector('[data-testid="pool-stats-5h-request_count"]')?.textContent?.trim()).toBe('7')
+    expect(root.querySelector('[data-testid="pool-stats-weekly-total_tokens"]')?.textContent?.trim()).toBe('0')
+
+    if (!modeSwitch) throw new Error('expected stats switch')
+    modeSwitch.checked = false
+    modeSwitch.dispatchEvent(new Event('change', { bubbles: true }))
+    await settle()
+
+    expect(routeMocks.query.statsMode).toBe('account_total')
+    expect(window.sessionStorage.getItem(POOL_MANAGEMENT_VIEW_STORAGE_KEY)).toContain('"statsMode":"account_total"')
+    expect(root.querySelector('[data-testid="pool-stats-account-total"]')).not.toBeNull()
+    expect(root.textContent).toContain('9,876')
+    expect(root.textContent).toContain('4.3M')
+    expect(root.textContent).toContain('$8.77')
+  })
+
+  it('renders the Codex stats switch in header actions instead of a standalone mode bar', async () => {
+    const codexKey = createPoolKey('codex')
+    endpointMocks.getPoolOverview.mockResolvedValue({ items: [createOverview('codex')] })
+    endpointMocks.listPoolKeys.mockResolvedValue(createKeyPage(codexKey))
+    endpointMocks.getProvider.mockResolvedValue(createProvider('codex'))
+
+    const root = mountPoolManagement()
+    await settle()
+
+    const desktopHeaderActions = root.querySelector('[data-testid="pool-header-actions"]')
+    const mobileHeaderActions = root.querySelector('[data-testid="pool-mobile-header-actions"]')
+    const modeControls = Array.from(root.querySelectorAll('[data-testid="pool-stats-mode-control"]'))
+
+    expect(desktopHeaderActions?.querySelector('[data-testid="pool-stats-mode-control"]')).not.toBeNull()
+    expect(mobileHeaderActions?.querySelector('[data-testid="pool-stats-mode-control"]')).not.toBeNull()
+    expect(modeControls).toHaveLength(2)
+    expect(modeControls.every(control => control.closest('[data-testid="pool-header-actions"], [data-testid="pool-mobile-header-actions"]'))).toBe(true)
+    expect(desktopHeaderActions?.textContent).toContain('累计')
+    expect(desktopHeaderActions?.textContent).toContain('周期')
+    expect(root.textContent).not.toContain('Codex 统计模式')
+    expect(root.textContent).not.toContain('当前周期显示 5H 与周窗口')
+  })
+
+  it('restores stored Codex account-total mode when the query omits statsMode', async () => {
+    seedStoredStatsMode('account_total')
+    const codexKey = createPoolKey('codex')
+    endpointMocks.getPoolOverview.mockResolvedValue({ items: [createOverview('codex')] })
+    endpointMocks.listPoolKeys.mockResolvedValue(createKeyPage(codexKey))
+    endpointMocks.getProvider.mockResolvedValue(createProvider('codex'))
+
+    const root = mountPoolManagement()
+    await settle()
+
+    const modeSwitch = root.querySelector<HTMLInputElement>('[data-testid="pool-stats-mode-switch"]')
+    expect(modeSwitch).not.toBeNull()
+    expect(modeSwitch?.checked).toBe(false)
+    expect(root.querySelector('[data-testid="pool-stats-account-total"]')).not.toBeNull()
+    expect(root.querySelector('[data-testid="pool-stats-cycle-group-5h"]')).toBeNull()
+    expect(routeMocks.query.statsMode).toBe('account_total')
+    expect(window.sessionStorage.getItem(POOL_MANAGEMENT_VIEW_STORAGE_KEY)).toContain('"statsMode":"account_total"')
+  })
+
+  it('lets a current-cycle statsMode query override stored Codex account-total mode', async () => {
+    seedStoredStatsMode('account_total')
+    routeMocks.query.statsMode = 'current_cycle'
+    const codexKey = createPoolKey('codex')
+    endpointMocks.getPoolOverview.mockResolvedValue({ items: [createOverview('codex')] })
+    endpointMocks.listPoolKeys.mockResolvedValue(createKeyPage(codexKey))
+    endpointMocks.getProvider.mockResolvedValue(createProvider('codex'))
+
+    const root = mountPoolManagement()
+    await settle()
+
+    const modeSwitch = root.querySelector<HTMLInputElement>('[data-testid="pool-stats-mode-switch"]')
+    expect(modeSwitch).not.toBeNull()
+    expect(modeSwitch?.checked).toBe(true)
+    expect(root.querySelector('[data-testid="pool-stats-cycle-group-5h"]')).not.toBeNull()
+    expect(root.querySelector('[data-testid="pool-stats-account-total"]')).toBeNull()
+    expect(routeMocks.query.statsMode).toBeUndefined()
+    expect(window.sessionStorage.getItem(POOL_MANAGEMENT_VIEW_STORAGE_KEY)).toContain('"statsMode":"current_cycle"')
+  })
+
+  it('hides the stats mode switch for non-Codex providers and keeps account totals', async () => {
+    const openaiKey = createPoolKey('openai', {
+      request_count: 12,
+      total_tokens: 3456,
+      total_cost_usd: '1.25',
+    })
+    endpointMocks.getPoolOverview.mockResolvedValue({ items: [createOverview('openai')] })
+    endpointMocks.listPoolKeys.mockResolvedValue(createKeyPage(openaiKey))
+    endpointMocks.getProvider.mockResolvedValue(createProvider('openai'))
+
+    const root = mountPoolManagement()
+    await settle()
+
+    expect(root.querySelector('[data-testid="pool-stats-mode-switch"]')).toBeNull()
+    expect(root.querySelector('[data-testid="pool-stats-mode-control"]')).toBeNull()
+    expect(root.querySelector('[data-testid="pool-stats-cycle-group-5h"]')).toBeNull()
+    expect(root.querySelector('[data-testid="pool-stats-account-total"]')).not.toBeNull()
+    expect(root.textContent).toContain('12')
+    expect(root.textContent).toContain('3.5K')
+    expect(root.textContent).toContain('$1.25')
+  })
+})