Lightweight coding agent that runs in your terminal
Rust
Add per-thread usage queries to the backend client (#38270)
Felipe Coury842fae26c945
diff --git a/codex-rs/backend-client/src/client.rs b/codex-rs/backend-client/src/client.rsindex da9b0a3d3f..6de0df4211 100644--- a/codex-rs/backend-client/src/client.rs+++ b/codex-rs/backend-client/src/client.rs@@ -35,6 +35,10 @@ use serde::de::DeserializeOwned;use std::fmt;mod rate_limit_resets;+mod thread_usage;++pub use thread_usage::ThreadUsage;+pub use thread_usage::ThreadUsageBreakdownGroup;#[derive(Debug)]pub enum RequestError {diff --git a/codex-rs/backend-client/src/client/thread_usage.rs b/codex-rs/backend-client/src/client/thread_usage.rsnew file mode 100644index 0000000000..9e879f7f1d--- /dev/null+++ b/codex-rs/backend-client/src/client/thread_usage.rs@@ -0,0 +1,88 @@+//! Authoritative estimated credit and dollar usage for an individual Codex thread.++use super::Client;+use super::PathStyle;+use super::RequestError;+use anyhow::anyhow;+use http::Method;+use http::header::CONTENT_TYPE;+use http::header::HeaderValue;+use serde::Deserialize;+use serde::Serialize;++/// Backend usage grouped by model, reasoning effort, and response speed.+#[derive(Clone, Debug, Deserialize, PartialEq, Eq)]+pub struct ThreadUsageBreakdownGroup {+ pub model: Option<String>,+ pub reasoning_effort: Option<String>,+ pub speed: Option<String>,+ pub estimated_usage_credits_micros: i64,+ pub net_new_input_tokens: Option<i64>,+ pub cached_input_tokens: Option<i64>,+ pub input_tokens: Option<i64>,+ pub output_tokens: Option<i64>,+ pub total_tokens: Option<i64>,+}++/// Backend-estimated usage totals expressed in integer millionths.+#[derive(Clone, Debug, Deserialize, PartialEq, Eq)]+pub struct ThreadUsage {+ pub thread_id: String,+ pub estimated_usage_credits_micros: i64,+ pub estimated_usage_usd_micros: Option<i64>,+ #[serde(default)]+ pub groups: Vec<ThreadUsageBreakdownGroup>,+}++#[derive(Serialize)]+struct ThreadUsageQueryRequest<'a> {+ thread_ids: [&'a str; 1],+}++#[derive(Deserialize)]+struct ThreadUsageQueryResponse {+ threads: Vec<ThreadUsage>,+}++impl Client {+ /// Reads authoritative estimated totals without maintaining a second usage ledger.+ pub async fn get_thread_usage(&self, thread_id: &str) -> Result<ThreadUsage, RequestError> {+ let url = self.thread_usage_url();+ let request = self+ .request(Method::POST, &url)+ .headers(self.headers())+ .header(CONTENT_TYPE, HeaderValue::from_static("application/json"))+ .json(&ThreadUsageQueryRequest {+ thread_ids: [thread_id],+ });+ let (body, content_type) = self.exec_request_detailed(request, "POST", &url).await?;+ let response = self+ .decode_json::<ThreadUsageQueryResponse>(&url, &content_type, &body)+ .map_err(RequestError::from)?;++ response+ .threads+ .into_iter()+ .find(|usage| usage.thread_id == thread_id)+ .ok_or_else(|| {+ RequestError::from(anyhow!(+ "thread usage response did not contain requested thread {thread_id}"+ ))+ })+ }++ fn thread_usage_url(&self) -> String {+ match self.path_style {+ PathStyle::CodexApi => {+ format!("{}/api/codex/usage/thread_usage/query", self.base_url)+ }+ PathStyle::ChatGptApi => {+ format!("{}/wham/usage/thread_usage/query", self.base_url)+ }+ }+ }+}++#[cfg(test)]+#[path = "thread_usage_tests.rs"]+mod tests;diff --git a/codex-rs/backend-client/src/client/thread_usage_tests.rs b/codex-rs/backend-client/src/client/thread_usage_tests.rsnew file mode 100644index 0000000000..d8dc620856--- /dev/null+++ b/codex-rs/backend-client/src/client/thread_usage_tests.rs@@ -0,0 +1,146 @@+use super::*;+use codex_http_client::HttpClientFactory;+use codex_http_client::OutboundProxyPolicy;+use pretty_assertions::assert_eq;+use serde_json::json;+use wiremock::Mock;+use wiremock::MockServer;+use wiremock::ResponseTemplate;+use wiremock::matchers::body_json;+use wiremock::matchers::method;+use wiremock::matchers::path;++#[test]+fn thread_usage_contract_uses_expected_paths_and_payload() {+ let factory = HttpClientFactory::new(OutboundProxyPolicy::ReqwestDefault);+ assert_eq!(+ Client::new("https://example.test", factory.clone()).thread_usage_url(),+ "https://example.test/api/codex/usage/thread_usage/query"+ );+ assert_eq!(+ Client::new("https://chatgpt.com/backend-api", factory).thread_usage_url(),+ "https://chatgpt.com/backend-api/wham/usage/thread_usage/query"+ );+ assert_eq!(+ serde_json::to_value(ThreadUsageQueryRequest {+ thread_ids: ["thread-123"],+ })+ .expect("serialize thread usage request"),+ json!({ "thread_ids": ["thread-123"] })+ );+}++#[tokio::test]+async fn get_thread_usage_returns_requested_thread_totals() {+ let server = MockServer::start().await;+ Mock::given(method("POST"))+ .and(path("/api/codex/usage/thread_usage/query"))+ .and(body_json(json!({ "thread_ids": ["thread-123"] })))+ .respond_with(ResponseTemplate::new(/*s*/ 200).set_body_json(json!({+ "threads": [{+ "thread_id": "thread-123",+ "estimated_usage_credits_micros": 46_000_000,+ "estimated_usage_usd_micros": 1_820_000,+ "groups": [{+ "model": "gpt-5.4",+ "reasoning_effort": "high",+ "speed": "fast",+ "estimated_usage_credits_micros": 46_000_000,+ "net_new_input_tokens": 80,+ "cached_input_tokens": 20,+ "input_tokens": 100,+ "output_tokens": 40,+ "total_tokens": 140+ }]+ }]+ })))+ .expect(/*r*/ 1)+ .mount(&server)+ .await;++ let client = Client::new(+ server.uri(),+ HttpClientFactory::new(OutboundProxyPolicy::ReqwestDefault),+ );+ assert_eq!(+ client+ .get_thread_usage("thread-123")+ .await+ .expect("read thread usage"),+ ThreadUsage {+ thread_id: "thread-123".to_string(),+ estimated_usage_credits_micros: 46_000_000,+ estimated_usage_usd_micros: Some(1_820_000),+ groups: vec![ThreadUsageBreakdownGroup {+ model: Some("gpt-5.4".to_string()),+ reasoning_effort: Some("high".to_string()),+ speed: Some("fast".to_string()),+ estimated_usage_credits_micros: 46_000_000,+ net_new_input_tokens: Some(80),+ cached_input_tokens: Some(20),+ input_tokens: Some(100),+ output_tokens: Some(40),+ total_tokens: Some(140),+ }],+ }+ );+}++#[tokio::test]+async fn get_thread_usage_accepts_credits_without_usd_estimate() {+ let server = MockServer::start().await;+ Mock::given(method("POST"))+ .and(path("/api/codex/usage/thread_usage/query"))+ .respond_with(ResponseTemplate::new(/*s*/ 200).set_body_json(json!({+ "threads": [{+ "thread_id": "thread-123",+ "estimated_usage_credits_micros": 46_000_000,+ "estimated_usage_usd_micros": null+ }]+ })))+ .expect(/*r*/ 1)+ .mount(&server)+ .await;++ let client = Client::new(+ server.uri(),+ HttpClientFactory::new(OutboundProxyPolicy::ReqwestDefault),+ );+ assert_eq!(+ client+ .get_thread_usage("thread-123")+ .await+ .expect("read credits without a dollar estimate"),+ ThreadUsage {+ thread_id: "thread-123".to_string(),+ estimated_usage_credits_micros: 46_000_000,+ estimated_usage_usd_micros: None,+ groups: Vec::new(),+ }+ );+}++#[tokio::test]+async fn get_thread_usage_rejects_totals_for_another_thread() {+ let server = MockServer::start().await;+ Mock::given(method("POST"))+ .respond_with(ResponseTemplate::new(/*s*/ 200).set_body_json(json!({+ "threads": [{+ "thread_id": "another-thread",+ "estimated_usage_credits_micros": 1,+ "estimated_usage_usd_micros": 1+ }]+ })))+ .mount(&server)+ .await;++ let client = Client::new(+ server.uri(),+ HttpClientFactory::new(OutboundProxyPolicy::ReqwestDefault),+ );+ let error = client+ .get_thread_usage("thread-123")+ .await+ .expect_err("reject usage for a different thread");+ assert!(error.to_string().contains("requested thread thread-123"));+}diff --git a/codex-rs/backend-client/src/lib.rs b/codex-rs/backend-client/src/lib.rsindex 91aa10488d..9963687b0f 100644--- a/codex-rs/backend-client/src/lib.rs+++ b/codex-rs/backend-client/src/lib.rs@@ -4,6 +4,8 @@ pub(crate) mod types;pub use client::AddCreditsNudgeCreditType;pub use client::Client;pub use client::RequestError;+pub use client::ThreadUsage;+pub use client::ThreadUsageBreakdownGroup;pub use types::AccountEntry;pub use types::AccountsCheckResponse;pub use types::CodeTaskDetailsResponse;