Lightweight coding agent that runs in your terminal
Rust
Expose response usage metadata in completion events (#41087)
Dylan Hurd2c4a95736bea
diff --git a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.jsonindex a1b085a1a2..c9f8888d25 100644--- a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json+++ b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json@@ -17253,6 +17253,16 @@"type": "null"}]+ },+ "usageMetadata": {+ "anyOf": [+ {+ "$ref": "#/definitions/v2/ResponseUsageMetadata"+ },+ {+ "type": "null"+ }+ ]}},"required": [@@ -18501,6 +18511,18 @@}]},+ "ResponseUsageMetadata": {+ "description": "Usage metadata reported for one upstream response.",+ "properties": {+ "amount": {+ "type": [+ "string",+ "null"+ ]+ }+ },+ "type": "object"+ },"ResponsesApiWebSearchAction": {"oneOf": [{diff --git a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.jsonindex 55975acace..e0830128d8 100644--- a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json+++ b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json@@ -13386,6 +13386,16 @@"type": "null"}]+ },+ "usageMetadata": {+ "anyOf": [+ {+ "$ref": "#/definitions/ResponseUsageMetadata"+ },+ {+ "type": "null"+ }+ ]}},"required": [@@ -14634,6 +14644,18 @@}]},+ "ResponseUsageMetadata": {+ "description": "Usage metadata reported for one upstream response.",+ "properties": {+ "amount": {+ "type": [+ "string",+ "null"+ ]+ }+ },+ "type": "object"+ },"ResponsesApiWebSearchAction": {"oneOf": [{diff --git a/codex-rs/app-server-protocol/schema/json/v2/RawResponseCompletedNotification.json b/codex-rs/app-server-protocol/schema/json/v2/RawResponseCompletedNotification.jsonindex 77f9fbb057..266caa465d 100644--- a/codex-rs/app-server-protocol/schema/json/v2/RawResponseCompletedNotification.json+++ b/codex-rs/app-server-protocol/schema/json/v2/RawResponseCompletedNotification.json@@ -1,6 +1,18 @@{"$schema": "http://json-schema.org/draft-07/schema#","definitions": {+ "ResponseUsageMetadata": {+ "description": "Usage metadata reported for one upstream response.",+ "properties": {+ "amount": {+ "type": [+ "string",+ "null"+ ]+ }+ },+ "type": "object"+ },"TokenUsageBreakdown": {"properties": {"cacheWriteInputTokens": {@@ -59,6 +71,16 @@"type": "null"}]+ },+ "usageMetadata": {+ "anyOf": [+ {+ "$ref": "#/definitions/ResponseUsageMetadata"+ },+ {+ "type": "null"+ }+ ]}},"required": [diff --git a/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-experimental.json.zst b/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-experimental.json.zstindex f7911b4f69..4a239bffcb 100644Binary files a/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-experimental.json.zst and b/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-experimental.json.zst differdiff --git a/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst b/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zstindex 65abc73962..0413a9c14b 100644Binary files a/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst and b/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst differdiff --git a/codex-rs/app-server-protocol/schema/typescript/v2/RawResponseCompletedNotification.ts b/codex-rs/app-server-protocol/schema/typescript/v2/RawResponseCompletedNotification.tsindex b06e74b4c7..a442f7596d 100644--- a/codex-rs/app-server-protocol/schema/typescript/v2/RawResponseCompletedNotification.ts+++ b/codex-rs/app-server-protocol/schema/typescript/v2/RawResponseCompletedNotification.ts@@ -1,10 +1,11 @@// GENERATED CODE! DO NOT MODIFY BY HAND!// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.+import type { ResponseUsageMetadata } from "./ResponseUsageMetadata";import type { TokenUsageBreakdown } from "./TokenUsageBreakdown";/*** Internal-only notification containing the exact usage from one upstream* Responses API completion.*/-export type RawResponseCompletedNotification = { threadId: string, turnId: string, responseId: string, usage: TokenUsageBreakdown | null, };+export type RawResponseCompletedNotification = { threadId: string, turnId: string, responseId: string, usage: TokenUsageBreakdown | null, usageMetadata: ResponseUsageMetadata | null, };diff --git a/codex-rs/app-server-protocol/schema/typescript/v2/ResponseUsageMetadata.ts b/codex-rs/app-server-protocol/schema/typescript/v2/ResponseUsageMetadata.tsnew file mode 100644index 0000000000..1a32767aad--- /dev/null+++ b/codex-rs/app-server-protocol/schema/typescript/v2/ResponseUsageMetadata.ts@@ -0,0 +1,8 @@+// GENERATED CODE! DO NOT MODIFY BY HAND!++// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.++/**+ * Usage metadata reported for one upstream response.+ */+export type ResponseUsageMetadata = { amount: string | null, };diff --git a/codex-rs/app-server-protocol/schema/typescript/v2/index.ts b/codex-rs/app-server-protocol/schema/typescript/v2/index.tsindex a5f10d734d..7fd56bd5d4 100644--- a/codex-rs/app-server-protocol/schema/typescript/v2/index.ts+++ b/codex-rs/app-server-protocol/schema/typescript/v2/index.ts@@ -408,6 +408,7 @@ export type { RemoteControlEnableParams } from "./RemoteControlEnableParams";export type { RemoteControlStatusChangedNotification } from "./RemoteControlStatusChangedNotification";export type { RequestPermissionProfile } from "./RequestPermissionProfile";export type { ResidencyRequirement } from "./ResidencyRequirement";+export type { ResponseUsageMetadata } from "./ResponseUsageMetadata";export type { ReviewDelivery } from "./ReviewDelivery";export type { ReviewStartParams } from "./ReviewStartParams";export type { ReviewStartResponse } from "./ReviewStartResponse";diff --git a/codex-rs/app-server-protocol/src/protocol/v2/thread.rs b/codex-rs/app-server-protocol/src/protocol/v2/thread.rsindex 9df4bfbef9..dc56a78529 100644--- a/codex-rs/app-server-protocol/src/protocol/v2/thread.rs+++ b/codex-rs/app-server-protocol/src/protocol/v2/thread.rs@@ -1841,6 +1841,23 @@ pub struct RawResponseCompletedNotification {pub turn_id: String,pub response_id: String,pub usage: Option<TokenUsageBreakdown>,+ pub usage_metadata: Option<ResponseUsageMetadata>,+}++/// Usage metadata reported for one upstream response.+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]+#[serde(rename_all = "camelCase")]+#[ts(export_to = "v2/")]+pub struct ResponseUsageMetadata {+ pub amount: Option<String>,+}++impl From<codex_protocol::ResponseUsageMetadata> for ResponseUsageMetadata {+ fn from(value: codex_protocol::ResponseUsageMetadata) -> Self {+ Self {+ amount: value.amount,+ }+ }}#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]diff --git a/codex-rs/app-server/src/bespoke_event_handling.rs b/codex-rs/app-server/src/bespoke_event_handling.rsindex b05d6f4d6e..11c06d7f2a 100644--- a/codex-rs/app-server/src/bespoke_event_handling.rs+++ b/codex-rs/app-server/src/bespoke_event_handling.rs@@ -1118,6 +1118,7 @@ pub(crate) async fn apply_bespoke_event_handling(turn_id: event_turn_id,response_id: raw_response_completed_event.response_id,usage: raw_response_completed_event.token_usage.map(Into::into),+ usage_metadata: raw_response_completed_event.usage_metadata.map(Into::into),};outgoing.send_server_notification(ServerNotification::RawResponseCompleted(notification))diff --git a/codex-rs/app-server/tests/suite/v2/compaction.rs b/codex-rs/app-server/tests/suite/v2/compaction.rsindex f1637d13ba..d84017c62e 100644--- a/codex-rs/app-server/tests/suite/v2/compaction.rs+++ b/codex-rs/app-server/tests/suite/v2/compaction.rs@@ -15,6 +15,7 @@ use codex_app_server_protocol::ItemStartedNotification;use codex_app_server_protocol::JSONRPCError;use codex_app_server_protocol::RawResponseCompletedNotification;use codex_app_server_protocol::RequestId;+use codex_app_server_protocol::ResponseUsageMetadata;use codex_app_server_protocol::ThreadCompactStartParams;use codex_app_server_protocol::ThreadCompactStartResponse;use codex_app_server_protocol::ThreadItem;@@ -244,9 +245,11 @@ async fn thread_compact_start_triggers_compaction_and_returns_empty_response() -skip_if_no_network!(Ok(()));let server = responses::start_mock_server().await;+ let mut completed = responses::ev_completed_with_tokens("r1", /*total_tokens*/ 200);+ completed["response"]["usage_metadata"] = serde_json::json!({ "amount": "0.125" });let sse = responses::sse(vec![responses::ev_assistant_message("m1", "MANUAL_COMPACT_SUMMARY"),- responses::ev_completed_with_tokens("r1", /*total_tokens*/ 200),+ completed,]);responses::mount_sse_sequence(&server, vec![sse]).await;@@ -300,6 +303,9 @@ async fn thread_compact_start_triggers_compaction_and_returns_empty_response() -thread_id,turn_id: started.turn_id,response_id: "r1".to_string(),+ usage_metadata: Some(ResponseUsageMetadata {+ amount: Some("0.125".to_string()),+ }),usage: Some(TokenUsageBreakdown {total_tokens: 200,input_tokens: 200,diff --git a/codex-rs/app-server/tests/suite/v2/turn_start.rs b/codex-rs/app-server/tests/suite/v2/turn_start.rsindex 8b7cff939b..c10006202b 100644--- a/codex-rs/app-server/tests/suite/v2/turn_start.rs+++ b/codex-rs/app-server/tests/suite/v2/turn_start.rs@@ -799,27 +799,43 @@ async fn turn_start_sends_service_tier_id_to_model_request() -> Result<()> {Ok(())}+#[test_case(None, json!(null); "without_usage_metadata")]+#[test_case(Some(json!({})), json!({ "amount": null }); "without_amount")]+#[test_case(Some(json!({ "amount": null })), json!({ "amount": null }); "null_amount")]+#[test_case(Some(json!({ "amount": "0" })), json!({ "amount": "0" }); "zero_amount")]+#[test_case(+ Some(json!({ "amount": "0.12345678901234567890" })),+ json!({ "amount": "0.12345678901234567890" });+ "exact_amount"+)]#[tokio::test]-async fn turn_start_emits_raw_response_completed_with_upstream_usage() -> Result<()> {+async fn turn_start_emits_raw_response_completed_with_upstream_usage(+ upstream_metadata: Option<Value>,+ expected_metadata: Value,+) -> Result<()> {let server = responses::start_mock_server().await;+ let mut completed = json!({+ "type": "response.completed",+ "response": {+ "id": "resp-1",+ "usage": {+ "input_tokens": 30,+ "input_tokens_details": { "cached_tokens": 11 },+ "output_tokens": 7,+ "output_tokens_details": { "reasoning_tokens": 3 },+ "total_tokens": 37+ }+ }+ });+ if let Some(metadata) = upstream_metadata {+ completed["response"]["usage_metadata"] = metadata;+ }let body = responses::sse(vec![responses::ev_response_created("resp-1"),responses::ev_assistant_message("msg-1", "Done"),- json!({- "type": "response.completed",- "response": {- "id": "resp-1",- "usage": {- "input_tokens": 30,- "input_tokens_details": { "cached_tokens": 11 },- "output_tokens": 7,- "output_tokens_details": { "reasoning_tokens": 3 },- "total_tokens": 37- }- }- }),+ completed,]);- responses::mount_sse_once(&server, body).await;+ let response_mock = responses::mount_sse_once(&server, body).await;let codex_home = TempDir::new()?;MockResponsesConfig::new(&server.uri()).write(codex_home.path())?;@@ -856,6 +872,13 @@ async fn turn_start_emits_raw_response_completed_with_upstream_usage() -> Resultmcp.read_stream_until_notification_message("rawResponse/completed"),).await??;+ assert_eq!(+ notification+ .params+ .as_ref()+ .and_then(|params| params.get("usageMetadata")),+ Some(&expected_metadata),+ );let notification: codex_app_server_protocol::ServerNotification = notification.try_into()?;let codex_app_server_protocol::ServerNotification::RawResponseCompleted(notification) =notification@@ -869,6 +892,7 @@ async fn turn_start_emits_raw_response_completed_with_upstream_usage() -> Resultthread_id: thread.id,turn_id: turn.id,response_id: "resp-1".to_string(),+ usage_metadata: serde_json::from_value(expected_metadata)?,usage: Some(TokenUsageBreakdown {total_tokens: 37,input_tokens: 30,@@ -880,6 +904,7 @@ async fn turn_start_emits_raw_response_completed_with_upstream_usage() -> Result});+ response_mock.single_request();Ok(())}diff --git a/codex-rs/codex-api/src/common.rs b/codex-rs/codex-api/src/common.rsindex 937e6d83d0..5adfe8db6a 100644--- a/codex-rs/codex-api/src/common.rs+++ b/codex-rs/codex-api/src/common.rs@@ -1,4 +1,5 @@use crate::error::ApiError;+use codex_protocol::ResponseUsageMetadata;use codex_protocol::config_types::ReasoningSummary as ReasoningSummaryConfig;use codex_protocol::config_types::Verbosity as VerbosityConfig;use codex_protocol::models::ResponseItem;@@ -113,6 +114,7 @@ pub enum ResponseEvent {Completed {response_id: String,token_usage: Option<TokenUsage>,+ usage_metadata: Option<ResponseUsageMetadata>,/// Did the model affirmatively end its turn? Some providers do not set this,/// so we rely on fallback logic when this is `None`.end_turn: Option<bool>,diff --git a/codex-rs/codex-api/src/sse/responses.rs b/codex-rs/codex-api/src/sse/responses.rsindex 9789bdb088..58b55091bb 100644--- a/codex-rs/codex-api/src/sse/responses.rs+++ b/codex-rs/codex-api/src/sse/responses.rs@@ -8,6 +8,7 @@ use crate::safety_buffering::treatment_from_headers;use crate::telemetry::SseTelemetry;use codex_client::ByteStream;use codex_client::StreamResponse;+use codex_protocol::ResponseUsageMetadata;use codex_protocol::models::ResponseItem;use codex_protocol::protocol::MisalignmentErrorDetails;use codex_protocol::protocol::ModelVerification;@@ -118,6 +119,7 @@ struct ResponseCompleted {id: String,#[serde(default)]usage: Option<ResponseCompletedUsage>,+ usage_metadata: Option<ResponseUsageMetadata>,#[serde(default)]end_turn: Option<bool>,}@@ -481,6 +483,7 @@ pub fn process_responses_event(return Ok(Some(ResponseEvent::Completed {response_id: resp.id,token_usage: resp.usage.map(Into::into),+ usage_metadata: resp.usage_metadata,end_turn: resp.end_turn,}));}@@ -864,10 +867,12 @@ mod tests {Ok(ResponseEvent::Completed {response_id,token_usage,+ usage_metadata,end_turn,}) => {assert_eq!(response_id, "resp1");assert!(token_usage.is_none());+ assert!(usage_metadata.is_none());assert!(end_turn.is_none());}other => panic!("unexpected third event: {other:?}"),@@ -1060,10 +1065,12 @@ mod tests {Ok(ResponseEvent::Completed {response_id,token_usage,+ usage_metadata,end_turn,}) => {assert_eq!(response_id, "resp1");assert!(token_usage.is_none());+ assert!(usage_metadata.is_none());assert!(end_turn.is_none());}other => panic!("unexpected event: {other:?}"),@@ -1570,6 +1577,7 @@ mod tests {ResponseEvent::Completed {response_id,token_usage: None,+ usage_metadata: None,end_turn: None,} if response_id == "resp-1");@@ -1607,6 +1615,7 @@ mod tests {ResponseEvent::Completed {response_id,token_usage: None,+ usage_metadata: None,end_turn: None,} if response_id == "resp-1");@@ -1642,6 +1651,7 @@ mod tests {ResponseEvent::Completed {response_id,token_usage: None,+ usage_metadata: None,end_turn: None,} if response_id == "resp-1");@@ -1677,6 +1687,7 @@ mod tests {ResponseEvent::Completed {response_id,token_usage: None,+ usage_metadata: None,end_turn: None,} if response_id == "resp-1");diff --git a/codex-rs/codex-api/tests/sse_end_to_end.rs b/codex-rs/codex-api/tests/sse_end_to_end.rsindex 23871fb984..308ae54be3 100644--- a/codex-rs/codex-api/tests/sse_end_to_end.rs+++ b/codex-rs/codex-api/tests/sse_end_to_end.rs@@ -113,6 +113,7 @@ async fn responses_stream_parses_items_and_completed_end_to_end() -> Result<()>"type": "response.completed","response": {"id": "resp1",+ "usage_metadata": { "amount": "0.12345678901234567890" },"usage": {"input_tokens": 10,"output_tokens": 5,@@ -165,9 +166,16 @@ async fn responses_stream_parses_items_and_completed_end_to_end() -> Result<()>ResponseEvent::Completed {response_id,token_usage,+ usage_metadata,end_turn,} => {assert_eq!(response_id, "resp1");+ assert_eq!(+ usage_metadata,+ &Some(codex_protocol::ResponseUsageMetadata {+ amount: Some("0.12345678901234567890".to_string()),+ })+ );assert_eq!(token_usage.as_ref().map(|usage| usage.total_tokens),Some(15)diff --git a/codex-rs/core/src/client.rs b/codex-rs/core/src/client.rsindex 19f3c4ec21..1c9a7e2d55 100644--- a/codex-rs/core/src/client.rs+++ b/codex-rs/core/src/client.rs@@ -2184,6 +2184,7 @@ whereOk(ResponseEvent::Completed {response_id,token_usage,+ usage_metadata,end_turn,}) => {feedback_tags!(last_model_response_id = &response_id);@@ -2206,6 +2207,7 @@ where.send(Ok(ResponseEvent::Completed {response_id,token_usage,+ usage_metadata,end_turn,})).awaitdiff --git a/codex-rs/core/src/client_tests.rs b/codex-rs/core/src/client_tests.rsindex f686257772..64b56b0d81 100644--- a/codex-rs/core/src/client_tests.rs+++ b/codex-rs/core/src/client_tests.rs@@ -728,6 +728,7 @@ async fn response_stream_records_last_model_feedback_ids() {Ok(ResponseEvent::Completed {response_id: "resp-123".to_string(),token_usage: None,+ usage_metadata: None,end_turn: Some(true),}),]);diff --git a/codex-rs/core/src/compact.rs b/codex-rs/core/src/compact.rsindex 3ddbea4463..9994585011 100644--- a/codex-rs/core/src/compact.rs+++ b/codex-rs/core/src/compact.rs@@ -774,6 +774,7 @@ async fn drain_to_completed(Ok(ResponseEvent::Completed {response_id,token_usage,+ usage_metadata,..}) => {sess.send_event(@@ -781,6 +782,7 @@ async fn drain_to_completed(EventMsg::RawResponseCompleted(RawResponseCompletedEvent {response_id,token_usage: token_usage.clone(),+ usage_metadata,}),).await;diff --git a/codex-rs/core/src/compact_remote_v2.rs b/codex-rs/core/src/compact_remote_v2.rsindex 198c469f1c..ee82bbcb7a 100644--- a/codex-rs/core/src/compact_remote_v2.rs+++ b/codex-rs/core/src/compact_remote_v2.rs@@ -38,6 +38,7 @@ use codex_context_fragments::to_annotated_content;use codex_features::Feature;use codex_history::CodexHarnessMetadata;use codex_history::ResponseItemEnvelope;+use codex_protocol::ResponseUsageMetadata;use codex_protocol::error::CodexErr;use codex_protocol::error::CodexErrorDetails;use codex_protocol::error::Result as CodexResult;@@ -361,6 +362,7 @@ struct RemoteCompactionV2Output {compaction_output: ResponseItem,response_id: String,token_usage: Option<TokenUsage>,+ usage_metadata: Option<ResponseUsageMetadata>,}async fn run_remote_compaction_request_v2(@@ -422,6 +424,7 @@ async fn collect_compaction_output(let mut saw_completed = false;let mut completed_response_id = None;let mut completed_token_usage = None;+ let mut completed_usage_metadata = None;while let Some(event) = stream.next().await {match event? {ResponseEvent::OutputItemDone(item) => {@@ -436,11 +439,13 @@ async fn collect_compaction_output(ResponseEvent::Completed {response_id,token_usage,+ usage_metadata,..} => {saw_completed = true;completed_response_id = Some(response_id);completed_token_usage = token_usage;+ completed_usage_metadata = usage_metadata;break;}_ => {}@@ -469,6 +474,7 @@ async fn collect_compaction_output(compaction_output,response_id,token_usage: completed_token_usage,+ usage_metadata: completed_usage_metadata,})}@@ -1161,6 +1167,9 @@ mod tests {total_tokens: 123_498,codex_rollout_budget_units: None,}),+ usage_metadata: Some(codex_protocol::ResponseUsageMetadata {+ amount: Some("0.125".to_string()),+ }),end_turn: Some(true),}),]);@@ -1169,6 +1178,12 @@ mod tests {.await.expect("compaction should be collected");+ assert_eq!(+ output.usage_metadata,+ Some(codex_protocol::ResponseUsageMetadata {+ amount: Some("0.125".to_string()),+ }),+ );assert_eq!(output.compaction_output, compaction);assert_eq!(output.response_id, "resp-compact");assert_eq!(diff --git a/codex-rs/core/src/compact_remote_v2_attempt.rs b/codex-rs/core/src/compact_remote_v2_attempt.rsindex 9569649f8b..7fe14113a6 100644--- a/codex-rs/core/src/compact_remote_v2_attempt.rs+++ b/codex-rs/core/src/compact_remote_v2_attempt.rs@@ -119,6 +119,7 @@ pub(super) async fn run_remote_compact_v2_attempt(compaction_output,response_id,token_usage,+ usage_metadata,} = compaction_output_result?;// TODO: Emit this before compaction output validation so malformed completed// responses still surface their raw upstream usage.@@ -127,6 +128,7 @@ pub(super) async fn run_remote_compact_v2_attempt(EventMsg::RawResponseCompleted(RawResponseCompletedEvent {response_id,token_usage: token_usage.clone(),+ usage_metadata,}),).await;diff --git a/codex-rs/core/src/session/turn.rs b/codex-rs/core/src/session/turn.rsindex d1a0dc4bf3..bdc542fea8 100644--- a/codex-rs/core/src/session/turn.rs+++ b/codex-rs/core/src/session/turn.rs@@ -2565,6 +2565,7 @@ async fn try_run_sampling_request(ResponseEvent::Completed {response_id,token_usage,+ usage_metadata,end_turn,} => {sess.services@@ -2589,6 +2590,7 @@ async fn try_run_sampling_request(EventMsg::RawResponseCompleted(RawResponseCompletedEvent {response_id,token_usage: token_usage.clone(),+ usage_metadata,}),).await;diff --git a/codex-rs/core/tests/suite/client_websockets.rs b/codex-rs/core/tests/suite/client_websockets.rsindex 2d1253a04c..1ab1a640d0 100755--- a/codex-rs/core/tests/suite/client_websockets.rs+++ b/codex-rs/core/tests/suite/client_websockets.rs@@ -152,6 +152,53 @@ fn websocket_connection_metadata(harness: &WebsocketTestHarness) -> CodexRespons)}+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]+async fn responses_websocket_preserves_credit_usage_metadata() {+ skip_if_no_network!();++ let mut completed = ev_completed("resp-1");+ completed["response"]["usage_metadata"] = json!({ "amount": "0.12345678901234567890" });+ let server =+ start_websocket_server(vec![vec![vec![ev_response_created("resp-1"), completed]]]).await;+ let harness = websocket_harness_for_codex_backend(&server).await;+ let mut client_session = harness.client.new_session();+ let prompt = prompt_with_input(vec![message_item("hello")]);+ let responses_metadata = turn_metadata(&harness, /*turn_id*/ None);+ let mut stream = client_session+ .stream(+ &prompt,+ &harness.model_info,+ &harness.session_telemetry,+ harness.effort.clone(),+ harness.summary,+ /*service_tier*/ None,+ &responses_metadata,+ &InferenceTraceContext::disabled(),+ )+ .await+ .expect("websocket stream failed");++ let mut usage_metadata = None;+ while let Some(event) = stream.next().await {+ if let ResponseEvent::Completed {+ usage_metadata: metadata,+ ..+ } = event.expect("websocket stream failed")+ {+ usage_metadata = metadata;+ break;+ }+ }+ assert_eq!(+ usage_metadata,+ Some(codex_protocol::ResponseUsageMetadata {+ amount: Some("0.12345678901234567890".to_string()),+ }),+ );+ assert_eq!(server.single_connection().len(), 1);+ server.shutdown().await;+}+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]async fn responses_websocket_streams_request() {skip_if_no_network!();diff --git a/codex-rs/protocol/src/lib.rs b/codex-rs/protocol/src/lib.rsindex efdfda6eba..10af9c7317 100644--- a/codex-rs/protocol/src/lib.rs+++ b/codex-rs/protocol/src/lib.rs@@ -2,6 +2,7 @@ pub mod account;mod agent_path;pub mod auth;mod response_item_id;+mod response_usage;mod sanitized_git_url;mod session_id;mod thread_id;@@ -10,6 +11,7 @@ pub use agent_path::AgentPath;pub use permission_profile_intersection::PermissionIntersectionError;pub use permission_profile_intersection::intersect_effective_permission_profiles;pub use response_item_id::ResponseItemId;+pub use response_usage::ResponseUsageMetadata;pub use sanitized_git_url::SanitizedGitUrl;pub use session_id::SessionId;pub use thread_id::RolloutId;diff --git a/codex-rs/protocol/src/protocol.rs b/codex-rs/protocol/src/protocol.rsindex 0ab7c8d6df..f5986aa3ae 100644--- a/codex-rs/protocol/src/protocol.rs+++ b/codex-rs/protocol/src/protocol.rs@@ -1882,13 +1882,14 @@ pub struct RawResponseItemEvent {pub item: ResponseItem,}-/// Exact usage reported by one upstream Responses API completion.+/// Exact usage and metadata reported by one upstream Responses API completion.////// Unlike TokenCountEvent, this is not accumulated, estimated, or replayed.#[derive(Debug, Clone, Deserialize, Serialize, TS, JsonSchema)]pub struct RawResponseCompletedEvent {pub response_id: String,pub token_usage: Option<TokenUsage>,+ pub usage_metadata: Option<crate::ResponseUsageMetadata>,}#[derive(Debug, Clone, Deserialize, Serialize, TS, JsonSchema)]diff --git a/codex-rs/protocol/src/response_usage.rs b/codex-rs/protocol/src/response_usage.rsnew file mode 100644index 0000000000..f1a75689fd--- /dev/null+++ b/codex-rs/protocol/src/response_usage.rs@@ -0,0 +1,12 @@+//! Per-response usage metadata reported by the upstream service, without aggregation.++use schemars::JsonSchema;+use serde::Deserialize;+use serde::Serialize;+use ts_rs::TS;++/// Usage metadata reported for one upstream response.+#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq, TS, JsonSchema)]+pub struct ResponseUsageMetadata {+ pub amount: Option<String>,+}