Expose exact per-response usage in raw app-server events (#32985)

## Why

Clients that account for individual upstream Responses API calls need the exact
usage for each completion rather than accumulated or estimated thread usage.

## What changed

- Add the opt-in `rawResponse/completed` app-server notification with the
  `threadId`, `turnId`, `responseId`, and upstream `usage` payload.
- Emit the transient event for normal turns and compaction requests when
  `experimentalRawEvents` is enabled. The event is not persisted or replayed,
  and `usage` is `null` when the upstream response omits it.
- Export the notification in the app-server schemas and document its behavior.

## Testing

- Cover exact token breakdowns for turn and compaction completions.

GitOrigin-RevId: 49040a060bf1784c1ff1dd62112efb4a778428c4
This commit is contained in:
Dylan Hurd authored and copyberry committed 2026-07-14 06:39:42 +00:00
1 parent 393f64565a
commit 1c9f890c05
24 files changed
+387 -7

No files matched your search

@@ -1375,6 +1375,18 @@ pub struct ThreadTokenUsageUpdatedNotification {
pub token_usage: ThreadTokenUsage,
}
/// Internal-only notification containing the exact usage from one upstream
/// Responses API completion.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct RawResponseCompletedNotification {
pub thread_id: String,
pub turn_id: String,
pub response_id: String,
pub usage: Option<TokenUsageBreakdown>,
}
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]