storing credits (#6858)

Expand the rate-limit cache/TUI: store credit snapshots alongside
primary and secondary windows, render “Credits” when the backend reports
they exist (unlimited vs rounded integer balances)

Author: zhao-oai

codex-rs/app-server-protocol/src/protocol/v2.rs

@@ -11,6 +11,7 @@ use codex_protocol::items::AgentMessageContent as CoreAgentMessageContent;
 use codex_protocol::items::TurnItem as CoreTurnItem;
 use codex_protocol::models::ResponseItem;
 use codex_protocol::parse_command::ParsedCommand as CoreParsedCommand;
+use codex_protocol::protocol::CreditsSnapshot as CoreCreditsSnapshot;
 use codex_protocol::protocol::RateLimitSnapshot as CoreRateLimitSnapshot;
 use codex_protocol::protocol::RateLimitWindow as CoreRateLimitWindow;
 use codex_protocol::user_input::UserInput as CoreUserInput;
@@ -994,13 +995,15 @@ pub struct AccountRateLimitsUpdatedNotification {
 pub struct RateLimitSnapshot {
     pub primary: Option<RateLimitWindow>,
     pub secondary: Option<RateLimitWindow>,
+    pub credits: Option<CreditsSnapshot>,
 }
 
 impl From<CoreRateLimitSnapshot> for RateLimitSnapshot {
     fn from(value: CoreRateLimitSnapshot) -> Self {
         Self {
             primary: value.primary.map(RateLimitWindow::from),
             secondary: value.secondary.map(RateLimitWindow::from),
+            credits: value.credits.map(CreditsSnapshot::from),
         }
     }
 }
@@ -1024,6 +1027,25 @@ impl From<CoreRateLimitWindow> for RateLimitWindow {
     }
 }
 
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
+#[serde(rename_all = "camelCase")]
+#[ts(export_to = "v2/")]
+pub struct CreditsSnapshot {
+    pub has_credits: bool,
+    pub unlimited: bool,
+    pub balance: Option<String>,
+}
+
+impl From<CoreCreditsSnapshot> for CreditsSnapshot {
+    fn from(value: CoreCreditsSnapshot) -> Self {
+        Self {
+            has_credits: value.has_credits,
+            unlimited: value.unlimited,
+            balance: value.balance,
+        }
+    }
+}
+
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
 #[serde(rename_all = "camelCase")]
 #[ts(export_to = "v2/")]

codex-rs/app-server/src/outgoing_message.rs

@@ -229,6 +229,7 @@ mod tests {
                         resets_at: Some(123),
                     }),
                     secondary: None,
+                    credits: None,
                 },
             });
 
@@ -243,7 +244,8 @@ mod tests {
                             "windowDurationMins": 15,
                             "resetsAt": 123
                         },
-                        "secondary": null
+                        "secondary": null,
+                        "credits": null
                     }
                 },
             }),

codex-rs/app-server/tests/suite/v2/rate_limits.rs

@@ -152,6 +152,7 @@ async fn get_account_rate_limits_returns_snapshot() -> Result<()> {
                 window_duration_mins: Some(1440),
                 resets_at: Some(secondary_reset_timestamp),
             }),
+            credits: None,
         },
     };
     assert_eq!(received, expected);

codex-rs/backend-client/src/client.rs

@@ -1,11 +1,13 @@
 use crate::types::CodeTaskDetailsResponse;
+use crate::types::CreditStatusDetails;
 use crate::types::PaginatedListTaskListItem;
 use crate::types::RateLimitStatusPayload;
 use crate::types::RateLimitWindowSnapshot;
 use crate::types::TurnAttemptsSiblingTurnsResponse;
 use anyhow::Result;
 use codex_core::auth::CodexAuth;
 use codex_core::default_client::get_codex_user_agent;
+use codex_protocol::protocol::CreditsSnapshot;
 use codex_protocol::protocol::RateLimitSnapshot;
 use codex_protocol::protocol::RateLimitWindow;
 use reqwest::header::AUTHORIZATION;
@@ -272,19 +274,23 @@ impl Client {
 
     // rate limit helpers
     fn rate_limit_snapshot_from_payload(payload: RateLimitStatusPayload) -> RateLimitSnapshot {
-        let Some(details) = payload
+        let rate_limit_details = payload
             .rate_limit
-            .and_then(|inner| inner.map(|boxed| *boxed))
-        else {
-            return RateLimitSnapshot {
-                primary: None,
-                secondary: None,
-            };
+            .and_then(|inner| inner.map(|boxed| *boxed));
+
+        let (primary, secondary) = if let Some(details) = rate_limit_details {
+            (
+                Self::map_rate_limit_window(details.primary_window),
+                Self::map_rate_limit_window(details.secondary_window),
+            )
+        } else {
+            (None, None)
         };
 
         RateLimitSnapshot {
-            primary: Self::map_rate_limit_window(details.primary_window),
-            secondary: Self::map_rate_limit_window(details.secondary_window),
+            primary,
+            secondary,
+            credits: Self::map_credits(payload.credits),
         }
     }
 
@@ -306,6 +312,19 @@ impl Client {
         })
     }
 
+    fn map_credits(credits: Option<Option<Box<CreditStatusDetails>>>) -> Option<CreditsSnapshot> {
+        let details = match credits {
+            Some(Some(details)) => *details,
+            _ => return None,
+        };
+
+        Some(CreditsSnapshot {
+            has_credits: details.has_credits,
+            unlimited: details.unlimited,
+            balance: details.balance.and_then(|inner| inner),
+        })
+    }
+
     fn window_minutes_from_seconds(seconds: i32) -> Option<i64> {
         if seconds <= 0 {
             return None;

codex-rs/backend-client/src/types.rs

@@ -1,3 +1,4 @@
+pub use codex_backend_openapi_models::models::CreditStatusDetails;
 pub use codex_backend_openapi_models::models::PaginatedListTaskListItem;
 pub use codex_backend_openapi_models::models::PlanType;
 pub use codex_backend_openapi_models::models::RateLimitStatusDetails;

codex-rs/core/src/client.rs

@@ -56,6 +56,7 @@ use crate::model_family::ModelFamily;
 use crate::model_provider_info::ModelProviderInfo;
 use crate::model_provider_info::WireApi;
 use crate::openai_model_info::get_model_info;
+use crate::protocol::CreditsSnapshot;
 use crate::protocol::RateLimitSnapshot;
 use crate::protocol::RateLimitWindow;
 use crate::protocol::TokenUsage;
@@ -726,7 +727,13 @@ fn parse_rate_limit_snapshot(headers: &HeaderMap) -> Option<RateLimitSnapshot> {
         "x-codex-secondary-reset-at",
     );
 
-    Some(RateLimitSnapshot { primary, secondary })
+    let credits = parse_credits_snapshot(headers);
+
+    Some(RateLimitSnapshot {
+        primary,
+        secondary,
+        credits,
+    })
 }
 
 fn parse_rate_limit_window(
@@ -753,6 +760,20 @@ fn parse_rate_limit_window(
     })
 }
 
+fn parse_credits_snapshot(headers: &HeaderMap) -> Option<CreditsSnapshot> {
+    let has_credits = parse_header_bool(headers, "x-codex-credits-has-credits")?;
+    let unlimited = parse_header_bool(headers, "x-codex-credits-unlimited")?;
+    let balance = parse_header_str(headers, "x-codex-credits-balance")
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .map(std::string::ToString::to_string);
+    Some(CreditsSnapshot {
+        has_credits,
+        unlimited,
+        balance,
+    })
+}
+
 fn parse_header_f64(headers: &HeaderMap, name: &str) -> Option<f64> {
     parse_header_str(headers, name)?
         .parse::<f64>()
@@ -764,6 +785,17 @@ fn parse_header_i64(headers: &HeaderMap, name: &str) -> Option<i64> {
     parse_header_str(headers, name)?.parse::<i64>().ok()
 }
 
+fn parse_header_bool(headers: &HeaderMap, name: &str) -> Option<bool> {
+    let raw = parse_header_str(headers, name)?;
+    if raw.eq_ignore_ascii_case("true") || raw == "1" {
+        Some(true)
+    } else if raw.eq_ignore_ascii_case("false") || raw == "0" {
+        Some(false)
+    } else {
+        None
+    }
+}
+
 fn parse_header_str<'a>(headers: &'a HeaderMap, name: &str) -> Option<&'a str> {
     headers.get(name)?.to_str().ok()
 }

codex-rs/core/src/error.rs

@@ -499,6 +499,7 @@ mod tests {
                 window_minutes: Some(120),
                 resets_at: Some(secondary_reset_at),
             }),
+            credits: None,
         }
     }
 

codex-rs/core/tests/suite/client.rs

@@ -1121,7 +1121,8 @@ async fn token_count_includes_rate_limits_snapshot() {
                     "used_percent": 40.0,
                     "window_minutes": 60,
                     "resets_at": 1704074400
-                }
+                },
+                "credits": null
             }
         })
     );
@@ -1168,7 +1169,8 @@ async fn token_count_includes_rate_limits_snapshot() {
                     "used_percent": 40.0,
                     "window_minutes": 60,
                     "resets_at": 1704074400
-                }
+                },
+                "credits": null
             }
         })
     );
@@ -1238,7 +1240,8 @@ async fn usage_limit_error_emits_rate_limit_event() -> anyhow::Result<()> {
             "used_percent": 87.5,
             "window_minutes": 60,
             "resets_at": null
-        }
+        },
+        "credits": null
     });
 
     let submission_id = codex

codex-rs/protocol/src/protocol.rs

@@ -790,6 +790,7 @@ pub struct TokenCountEvent {
 pub struct RateLimitSnapshot {
     pub primary: Option<RateLimitWindow>,
     pub secondary: Option<RateLimitWindow>,
+    pub credits: Option<CreditsSnapshot>,
 }
 
 #[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema, TS)]
@@ -804,6 +805,13 @@ pub struct RateLimitWindow {
     pub resets_at: Option<i64>,
 }
 
+#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema, TS)]
+pub struct CreditsSnapshot {
+    pub has_credits: bool,
+    pub unlimited: bool,
+    pub balance: Option<String>,
+}
+
 // Includes prompts, tools and space to call compact.
 const BASELINE_TOKENS: i64 = 12000;
 

codex-rs/tui/src/chatwidget/tests.rs

@@ -81,6 +81,7 @@ fn snapshot(percent: f64) -> RateLimitSnapshot {
             resets_at: None,
         }),
         secondary: None,
+        credits: None,
     }
 }