@tanstack/ai 0.57.0 → 0.59.0

package/src/types.ts

@@ -19,12 +19,22 @@ import type {
   UsageCostBreakdown,
 } from '@tanstack/ai-event-client'
 import type {
+  ActivityDeltaEvent as AGUIActivityDeltaEvent,
+  ActivitySnapshotEvent as AGUIActivitySnapshotEvent,
+  AudioPart as AGUIAudioPart,
   BaseEvent as AGUIBaseEvent,
+  ContentPart as AGUIContentPart,
   CustomEvent as AGUICustomEvent,
+  DataSource as AGUIDataSource,
+  DocumentPart as AGUIDocumentPart,
+  FileSource as AGUIFileSource,
+  ImagePart as AGUIImagePart,
   Interrupt as AGUIInterrupt,
   MessagesSnapshotEvent as AGUIMessagesSnapshotEvent,
   ReasoningEncryptedValueEvent as AGUIReasoningEncryptedValueEvent,
   ReasoningEndEvent as AGUIReasoningEndEvent,
+  RawEvent as AGUIRawEvent,
+  ReasoningMessageChunkEvent as AGUIReasoningMessageChunkEvent,
   ReasoningMessageContentEvent as AGUIReasoningMessageContentEvent,
   ReasoningMessageEndEvent as AGUIReasoningMessageEndEvent,
   ReasoningMessageStartEvent as AGUIReasoningMessageStartEvent,
@@ -38,19 +48,31 @@ import type {
   StateSnapshotEvent as AGUIStateSnapshotEvent,
   StepFinishedEvent as AGUIStepFinishedEvent,
   StepStartedEvent as AGUIStepStartedEvent,
+  SubagentErrorEvent as AGUISubagentErrorEvent,
+  SubagentFinishedEvent as AGUISubagentFinishedEvent,
+  SubagentFinishedSuspendedOutcome as AGUISubagentFinishedSuspendedOutcome,
+  SubagentInfo as AGUISubagentInfo,
+  SubagentRunId as AGUISubagentRunId,
+  SubagentStartedEvent as AGUISubagentStartedEvent,
+  TextMessageChunkEvent as AGUITextMessageChunkEvent,
   TextMessageContentEvent as AGUITextMessageContentEvent,
   TextMessageEndEvent as AGUITextMessageEndEvent,
   TextMessageStartEvent as AGUITextMessageStartEvent,
+  ToolCall as AGUIToolCall,
   ToolCallArgsEvent as AGUIToolCallArgsEvent,
+  ToolCallChunkEvent as AGUIToolCallChunkEvent,
   ToolCallEndEvent as AGUIToolCallEndEvent,
   ToolCallResultEvent as AGUIToolCallResultEvent,
   ToolCallStartEvent as AGUIToolCallStartEvent,
+  UrlSource as AGUIUrlSource,
+  VideoPart as AGUIVideoPart,
   EventType,
 } from '@ag-ui/core'
 import type {
   SpecTokenUsage,
   TokenUsageLeftover,
 } from './utilities/ag-ui-usage'
+import type { SubagentWireInfo } from './utilities/subagent-wire'
 
 // Re-export ProviderTool so the type is reachable from `@tanstack/ai`'s root
 // entry via `export * from './types'` without forcing the subpath import.
@@ -163,13 +185,11 @@ export type InferSchemaType<T> =
       ? TInput
       : unknown
 
-export interface ToolCall<TMetadata = unknown> {
-  id: string
-  type: 'function'
-  function: {
-    name: string
-    arguments: string // JSON string
-  }
+/** AG-UI `ToolCall` with typed metadata. `function.arguments` is a JSON string. */
+export interface ToolCall<TMetadata = unknown> extends Omit<
+  AGUIToolCall,
+  'metadata'
+> {
   /** Provider-specific metadata to carry through the tool call lifecycle.
    * Typed per-adapter via `TToolCallMetadata`. For example,
    * `@tanstack/ai-gemini` sets this to `{ thoughtSignature?: string }`. */
@@ -201,106 +221,68 @@ export interface ProviderExecutedToolMetadata {
 // ============================================================================
 
 /**
- * Supported input modality types for multimodal content.
- * - 'text': Plain text content
- * - 'image': Image content (base64 or URL)
- * - 'audio': Audio content (base64 or URL)
- * - 'video': Video content (base64 or URL)
- * - 'document': Document content like PDFs (base64 or URL)
+ * Supported input modality types for multimodal content: the `type` of each
+ * AG-UI `ContentPart` (text, image, audio, video, document).
  */
-export type Modality = 'text' | 'image' | 'audio' | 'video' | 'document'
+export type Modality = AGUIContentPart['type']
 
 /**
- * Source specification for inline data content (base64).
- * Requires a mimeType to ensure providers receive proper content type information.
+ * Inline base64 content. AG-UI `DataSource`: `mimeType` is required.
  */
-export interface ContentPartDataSource {
-  /**
-   * Indicates this is inline data content.
-   */
-  type: 'data'
-  /**
-   * The base64-encoded content value.
-   */
-  value: string
-  /**
-   * The MIME type of the content (e.g., 'image/png', 'audio/wav').
-   * Required for data sources to ensure proper handling by providers.
-   */
-  mimeType: string
-}
+export interface ContentPartDataSource extends AGUIDataSource {}
 
 /**
- * Source specification for URL-based content.
- * mimeType is optional as it can often be inferred from the URL or response headers.
+ * URL-referenced content. AG-UI `UrlSource`: `mimeType` is optional.
  */
-export interface ContentPartUrlSource {
-  /**
-   * Indicates this is URL-referenced content.
-   */
-  type: 'url'
-  /**
-   * HTTP(S) URL or data URI pointing to the content.
-   */
-  value: string
-  /**
-   * Optional MIME type hint for cases where providers can't infer it from the URL.
-   */
-  mimeType?: string
-}
+export interface ContentPartUrlSource extends AGUIUrlSource {}
+
+/**
+ * A provider-issued file handle (Files API). AG-UI `FileSource`: the handle
+ * is opaque, do not fetch or parse it.
+ */
+export interface ContentPartFileSource extends AGUIFileSource {}
 
 /**
- * Source specification for multimodal content.
- * Discriminated union supporting both inline data (base64) and URL-based content.
- * - For 'data' sources: mimeType is required
- * - For 'url' sources: mimeType is optional
+ * Where a media part's bytes come from: inline data, a URL, or a provider
+ * file handle. Same members as AG-UI `PartSource`.
  */
-export type ContentPartSource = ContentPartDataSource | ContentPartUrlSource
+export type ContentPartSource =
+  | ContentPartDataSource
+  | ContentPartUrlSource
+  | ContentPartFileSource
 
 /**
- * Image content part for multimodal messages.
+ * Image content part for multimodal messages. AG-UI `ImagePart` with typed metadata.
  * @template TMetadata - Provider-specific metadata type (e.g., OpenAI's detail level)
  */
-export interface ImagePart<TMetadata = unknown> {
-  type: 'image'
-  /** Source of the image content */
-  source: ContentPartSource
+export interface ImagePart<TMetadata = unknown> extends AGUIImagePart {
   /** Provider-specific metadata (e.g., OpenAI's detail: 'auto' | 'low' | 'high') */
   metadata?: TMetadata
 }
 
 /**
- * Audio content part for multimodal messages.
+ * Audio content part for multimodal messages. AG-UI `AudioPart` with typed metadata.
  * @template TMetadata - Provider-specific metadata type
  */
-export interface AudioPart<TMetadata = unknown> {
-  type: 'audio'
-  /** Source of the audio content */
-  source: ContentPartSource
+export interface AudioPart<TMetadata = unknown> extends AGUIAudioPart {
   /** Provider-specific metadata (e.g., format, sample rate) */
   metadata?: TMetadata
 }
 
 /**
- * Video content part for multimodal messages.
+ * Video content part for multimodal messages. AG-UI `VideoPart` with typed metadata.
  * @template TMetadata - Provider-specific metadata type
  */
-export interface VideoPart<TMetadata = unknown> {
-  type: 'video'
-  /** Source of the video content */
-  source: ContentPartSource
+export interface VideoPart<TMetadata = unknown> extends AGUIVideoPart {
   /** Provider-specific metadata (e.g., duration, resolution) */
   metadata?: TMetadata
 }
 
 /**
- * Document content part for multimodal messages (e.g., PDFs).
+ * Document content part for multimodal messages (e.g., PDFs). AG-UI `DocumentPart` with typed metadata.
  * @template TMetadata - Provider-specific metadata type (e.g., Anthropic's media_type)
  */
-export interface DocumentPart<TMetadata = unknown> {
-  type: 'document'
-  /** Source of the document content */
-  source: ContentPartSource
+export interface DocumentPart<TMetadata = unknown> extends AGUIDocumentPart {
   /** Provider-specific metadata (e.g., media_type for PDFs) */
   metadata?: TMetadata
 }
@@ -492,6 +474,37 @@ export interface StructuredOutputPart<TData = unknown> {
   errorMessage?: string
 }
 
+export type SubagentStatus = 'running' | 'finished' | 'error' | 'suspended'
+
+/**
+ * One child invocation as the client sees it. AG-UI `SubagentInfo` names the
+ * child; the other AG-UI fields come from its `SUBAGENT_STARTED`,
+ * `SUBAGENT_FINISHED` and `SUBAGENT_ERROR` events. `id` is the AG-UI
+ * `subagentRunId`. `status`, `parentRunId` and `messages` are client state the
+ * spec does not model.
+ */
+export interface SubagentHandleData
+  extends
+    AGUISubagentInfo,
+    Pick<
+      AGUISubagentStartedEvent,
+      'parentSubagentRunId' | 'parentToolCallId' | 'metadata'
+    > {
+  id: AGUISubagentRunId
+  status: SubagentStatus
+  /** The parent chat run that started this child. */
+  parentRunId?: string
+  /** Interrupts this child raised, while `status` is `'suspended'`. */
+  interruptIds?: AGUISubagentFinishedSuspendedOutcome['interruptIds']
+  messages: Array<UIMessage>
+  error?: Pick<AGUISubagentErrorEvent, 'message' | 'code'>
+}
+
+export interface SubagentPart {
+  type: 'subagent'
+  subagent: SubagentHandleData
+}
+
 export interface UIResourcePart {
   type: 'ui-resource'
   /** The ui:// resource object in MCP-native shape — fed straight to the renderer. */
@@ -520,6 +533,7 @@ export type MessagePart<TData = unknown> =
   | ThinkingPart
   | StructuredOutputPart<TData>
   | UIResourcePart
+  | SubagentPart
 
 /**
  * Shape of `metadata.tanstack` on a message.
@@ -528,6 +542,10 @@ export type MessagePart<TData = unknown> =
 export interface TanStackMessageMetadata {
   createdAt?: string
   model?: string
+  /** Parent chat run that produced this assistant message. */
+  runId?: string
+  /** Card data on a child wire message. See `uiMessagesToWire`. */
+  subagent?: SubagentWireInfo
   /** Thinking signature for a `role: 'reasoning'` fan-out message. */
   signature?: string
   /** Per-tool-call provider metadata keyed by tool call id (e.g. Gemini thoughtSignature). */
@@ -629,6 +647,22 @@ type RuntimeContextField<TContext> =
         context: TContext
       }
 
+/**
+ * Options for a single `emitCustomEvent` call, on both the tool-execution and
+ * middleware contexts.
+ */
+export interface EmitCustomEventOptions {
+  /**
+   * Keep this event in the durability batch with later chunks.
+   * CUSTOM events flush as soon as they are emitted, so a progress
+   * indicator can render at emit time. Pass `{ batch: true }` for a
+   * high-volume stream that should share appends with later output.
+   * `process.stdout`, `process.stderr`, `sandbox.file`, and
+   * `sandbox.file.diff` already batch.
+   */
+  batch?: boolean
+}
+
 /**
  * Context passed to tool execute functions, providing capabilities like
  * emitting custom events during execution.
@@ -649,6 +683,8 @@ export type ToolExecutionContext<TContext = unknown> =
      *
      * @param eventName - Name of the custom event
      * @param value - Event payload value
+     * @param options - Pass `{ batch: true }` to keep this event in the
+     *   durability batch instead of flushing it immediately
      *
      * @example
      * ```ts
@@ -661,7 +697,11 @@ export type ToolExecutionContext<TContext = unknown> =
      * })
      * ```
      */
-    emitCustomEvent: (eventName: string, value: Record<string, any>) => void
+    emitCustomEvent: (
+      eventName: string,
+      value: Record<string, any>,
+      options?: EmitCustomEventOptions,
+    ) => void
   }
 
 export type ToolExecuteFunction<
@@ -1091,6 +1131,12 @@ export interface TextOptions<
    * Surfaced for observability/middleware; not consumed by the LLM call.
    */
   parentRunId?: string
+  /**
+   * AG-UI subagent run id when this chat runs as a child of another run.
+   * A child `chat()` passes `ctx.subagentRunId`. Middleware reads it as
+   * `ctx.subagentRunId`. Absent on a top-level run.
+   */
+  subagentRunId?: string
 
   /** Application state mirrored in a STATE_SNAPSHOT before an interrupt terminal. */
   state?: unknown
@@ -1263,15 +1309,12 @@ export interface TextMessageEndEvent extends AGUITextMessageEndEvent {}
 /**
  * Emitted when a tool call starts.
  *
- * @ag-ui/core provides: `toolCallId`, `toolCallName`, `parentMessageId?`
- *
- * Field shapes are taken from AG-UI via `Pick` (not `extends`) so Zod
- * `.passthrough()` index signatures do not pollute the StreamChunk
- * discriminated union — required for {@link KnownCustomEvent} narrowing.
+ * @ag-ui/core provides: `toolCallId`, `toolCallName`, `parentMessageId?`,
+ * `subagentRunId?`
  */
-export interface ToolCallStartEvent extends Pick<
+export interface ToolCallStartEvent extends Omit<
   AGUIToolCallStartEvent,
-  'toolCallId' | 'toolCallName' | 'parentMessageId' | 'timestamp' | 'rawEvent'
+  'type'
 > {
   type: 'TOOL_CALL_START'
   /** Alias of `toolCallName`. Kept so existing stream readers still compile. */
@@ -1290,14 +1333,9 @@ export interface ToolCallArgsEvent extends AGUIToolCallArgsEvent {}
 /**
  * Emitted when a tool call completes.
  *
- * @ag-ui/core provides: `toolCallId`
- *
- * Same `Pick` (not `extends`) rationale as {@link ToolCallStartEvent}.
+ * @ag-ui/core provides: `toolCallId`, `subagentRunId?`
  */
-export interface ToolCallEndEvent extends Pick<
-  AGUIToolCallEndEvent,
-  'toolCallId' | 'timestamp' | 'rawEvent'
-> {
+export interface ToolCallEndEvent extends Omit<AGUIToolCallEndEvent, 'type'> {
   type: 'TOOL_CALL_END'
   /** Parsed tool arguments when the adapter already parsed them. */
   input?: unknown
@@ -1355,15 +1393,9 @@ export interface StateDeltaEvent extends AGUIStateDeltaEvent {}
 /**
  * Custom event for extensibility.
  *
- * @ag-ui/core provides: `name`, `value`
- *
- * Uses `Pick` (not `extends`) so the Zod passthrough index signature does not
- * erase discriminant property access on {@link KnownCustomEvent} unions.
+ * @ag-ui/core provides: `name`, `value`, `subagentRunId?`
  */
-export interface CustomEvent extends Pick<
-  AGUICustomEvent,
-  'name' | 'value' | 'timestamp' | 'rawEvent'
-> {
+export interface CustomEvent extends Omit<AGUICustomEvent, 'type'> {
   type: 'CUSTOM'
   metadata?: Record<string, any>
 }
@@ -1649,6 +1681,24 @@ export interface ReasoningEndEvent extends AGUIReasoningEndEvent {}
  */
 export interface ReasoningEncryptedValueEvent extends AGUIReasoningEncryptedValueEvent {}
 
+/** AG-UI 1.0 ActivitySnapshotEvent shape. */
+export interface ActivitySnapshotEvent extends AGUIActivitySnapshotEvent {}
+
+/** AG-UI 1.0 ActivityDeltaEvent shape. */
+export interface ActivityDeltaEvent extends AGUIActivityDeltaEvent {}
+
+/** AG-UI 1.0 RawEvent shape. */
+export interface RawEvent extends AGUIRawEvent {}
+
+/** AG-UI 1.0 TextMessageChunkEvent shape. */
+export interface TextMessageChunkEvent extends AGUITextMessageChunkEvent {}
+
+/** AG-UI 1.0 ToolCallChunkEvent shape. */
+export interface ToolCallChunkEvent extends AGUIToolCallChunkEvent {}
+
+/** AG-UI 1.0 ReasoningMessageChunkEvent shape. */
+export interface ReasoningMessageChunkEvent extends AGUIReasoningMessageChunkEvent {}
+
 // ============================================================================
 // AG-UI Event Union
 // ============================================================================
@@ -1657,6 +1707,12 @@ export interface ReasoningEncryptedValueEvent extends AGUIReasoningEncryptedValu
  * Union of all AG-UI events.
  */
 export type AGUIEvent =
+  | ActivitySnapshotEvent
+  | ActivityDeltaEvent
+  | RawEvent
+  | TextMessageChunkEvent
+  | ToolCallChunkEvent
+  | ReasoningMessageChunkEvent
   | RunStartedEvent
   | RunFinishedEvent
   | RunErrorEvent
@@ -1679,6 +1735,32 @@ export type AGUIEvent =
   | ReasoningMessageEndEvent
   | ReasoningEndEvent
   | ReasoningEncryptedValueEvent
+  | SubagentStartedEvent
+  | SubagentFinishedEvent
+  | SubagentErrorEvent
+
+/**
+ * A child agent started. The later chunks for that child carry the same
+ * `subagentRunId`.
+ *
+ * @ag-ui/core provides: `subagentRunId`, `name`, `description?`,
+ * `parentSubagentRunId?`, `parentToolCallId?`, `parentMessageId?`, `metadata?`
+ */
+export interface SubagentStartedEvent extends AGUISubagentStartedEvent {}
+
+/**
+ * A child agent's segment of this run ended.
+ *
+ * @ag-ui/core provides: `subagentRunId`, `result?`, `outcome?`
+ */
+export interface SubagentFinishedEvent extends AGUISubagentFinishedEvent {}
+
+/**
+ * A child agent failed. The parent run can continue.
+ *
+ * @ag-ui/core provides: `subagentRunId`, `message`, `code?`
+ */
+export interface SubagentErrorEvent extends AGUISubagentErrorEvent {}
 
 /**
  * Chunk returned by the SDK during streaming chat completions.

package/src/utilities/adapter-yield-chunk.ts

@@ -4,11 +4,12 @@ import type { ContentPart, StreamChunk, ToolOutputState } from '../types'
 /**
  * Adapter / engine yield before normalize. Public StreamChunk is spec-only.
  * This type still allows the old extra fields.
+ * Extras never override a spec field (see WithAdapterExtras).
  */
-export type AdapterYieldChunk = StreamChunk & {
+type AdapterExtras = {
   model?: string
   finishReason?: 'stop' | 'length' | 'content_filter' | 'tool_calls' | null
-  // `any` so TokenUsage adapter yields stay assignable after public usage[]
+  // `any` so TokenUsage adapter yields stay assignable after public usage[].
   usage?: any
   content?: string
   args?: string
@@ -28,3 +29,10 @@ export type AdapterYieldChunk = StreamChunk & {
   threadId?: string
   runId?: string
 }
+
+// Preserve spec fields when an adapter extra uses the same name.
+type WithAdapterExtras<T> = T extends StreamChunk
+  ? T & Omit<AdapterExtras, keyof T>
+  : never
+
+export type AdapterYieldChunk = WithAdapterExtras<StreamChunk>

package/src/utilities/ag-ui-usage.test.ts

@@ -192,3 +192,41 @@ describe('rebuildTokenUsage', () => {
     })
   })
 })
+
+it('maps cache-write usage in both directions', () => {
+  const usage: TokenUsage = {
+    promptTokens: 12,
+    completionTokens: 3,
+    totalTokens: 15,
+    promptTokensDetails: { cachedTokens: 4, cacheWriteTokens: 5 },
+  }
+  const wire = toSpecTokenUsage(usage)
+  expect(wire.usage).toEqual([
+    {
+      inputTokens: 12,
+      outputTokens: 3,
+      totalTokens: 15,
+      cachedInputTokens: 4,
+      cacheWriteInputTokens: 5,
+    },
+  ])
+  // Old readers only know the leftover field, so it stays there too.
+  expect(wire.leftover).toEqual({
+    promptTokensDetails: { cacheWriteTokens: 5 },
+  })
+  expect(fromSpecTokenUsage(wire.usage, wire.leftover)).toEqual(usage)
+  expect(fromSpecTokenUsage(wire.usage)).toEqual(usage)
+})
+
+it('sums every spec usage entry', () => {
+  expect(
+    fromSpecTokenUsage([
+      { inputTokens: 1, outputTokens: 2, totalTokens: 3 },
+      { inputTokens: 4, outputTokens: 5, totalTokens: 9 },
+    ]),
+  ).toEqual({
+    promptTokens: 5,
+    completionTokens: 7,
+    totalTokens: 12,
+  })
+})

package/src/utilities/ag-ui-usage.ts

@@ -1,15 +1,8 @@
+import type { TokenUsage as SpecTokenUsage } from '@ag-ui/core'
 import type { TokenUsage } from '../types'
 
 /** AG-UI spec `usage[]` item (provider/model labels + token counts only). */
-export interface SpecTokenUsage {
-  provider?: string
-  model?: string
-  inputTokens?: number
-  outputTokens?: number
-  totalTokens?: number
-  reasoningTokens?: number
-  cachedInputTokens?: number
-}
+export type { TokenUsage as SpecTokenUsage } from '@ag-ui/core'
 
 export interface ToSpecTokenUsageOptions {
   provider?: string
@@ -68,11 +61,16 @@ export function toSpecTokenUsage(
   if (cachedInputTokens !== undefined) {
     spec.cachedInputTokens = cachedInputTokens
   }
+  if (promptTokensDetails?.cacheWriteTokens !== undefined) {
+    spec.cacheWriteInputTokens = promptTokensDetails.cacheWriteTokens
+  }
   const reasoningTokens = completionTokensDetails?.reasoningTokens
   if (reasoningTokens !== undefined) {
     spec.reasoningTokens = reasoningTokens
   }
 
+  // cacheWriteTokens stays in the leftover too, so clients built before
+  // cacheWriteInputTokens existed still rebuild it.
   const leftoverPrompt = promptTokensDetails
     ? definedDetails(withoutKey(promptTokensDetails, 'cachedTokens'))
     : undefined
@@ -94,6 +92,80 @@ export function toSpecTokenUsage(
   }
 }
 
+function sumNumbers<T extends object>(
+  current: T | undefined,
+  next: T | undefined,
+): T | undefined {
+  if (!current) return next
+  if (!next) return current
+  const result = { ...current }
+  for (const key of Object.keys(next) as Array<keyof T>) {
+    const value = next[key]
+    if (typeof value !== 'number') continue
+    const previous = current[key]
+    result[key] = ((typeof previous === 'number' ? previous : 0) +
+      value) as T[keyof T]
+  }
+  return result
+}
+
+function sumOptional(current?: number, next?: number): number | undefined {
+  if (current === undefined) return next
+  if (next === undefined) return current
+  return current + next
+}
+
+/**
+ * Add two usage totals, as for a parent run and its children. Numbers add
+ * up. `billed` adds up only in the same unit. `providerUsageDetails` is
+ * opaque, so the latest one stays. `@tanstack/ai-persistence` sums per-run
+ * usage with the same rules.
+ */
+export function addTokenUsage(
+  current: TokenUsage,
+  next: TokenUsage,
+): TokenUsage {
+  const promptTokensDetails = sumNumbers(
+    current.promptTokensDetails,
+    next.promptTokensDetails,
+  )
+  const completionTokensDetails = sumNumbers(
+    current.completionTokensDetails,
+    next.completionTokensDetails,
+  )
+  const costDetails = sumNumbers(current.costDetails, next.costDetails)
+  const cost = sumOptional(current.cost, next.cost)
+  const durationSeconds = sumOptional(
+    current.durationSeconds,
+    next.durationSeconds,
+  )
+  const unitsBilled = sumOptional(current.unitsBilled, next.unitsBilled)
+  const billed =
+    current.billed && next.billed && current.billed.unit === next.billed.unit
+      ? {
+          quantity: current.billed.quantity + next.billed.quantity,
+          unit: current.billed.unit,
+        }
+      : (next.billed ?? current.billed)
+  const providerUsageDetails =
+    next.providerUsageDetails ?? current.providerUsageDetails
+  return {
+    ...current,
+    ...next,
+    promptTokens: current.promptTokens + next.promptTokens,
+    completionTokens: current.completionTokens + next.completionTokens,
+    totalTokens: current.totalTokens + next.totalTokens,
+    ...(promptTokensDetails && { promptTokensDetails }),
+    ...(completionTokensDetails && { completionTokensDetails }),
+    ...(cost !== undefined && { cost }),
+    ...(costDetails && { costDetails }),
+    ...(durationSeconds !== undefined && { durationSeconds }),
+    ...(unitsBilled !== undefined && { unitsBilled }),
+    ...(billed && { billed }),
+    ...(providerUsageDetails && { providerUsageDetails }),
+  }
+}
+
 export function rebuildTokenUsage(
   usage: unknown,
   leftover?: TokenUsageLeftover,
@@ -111,8 +183,20 @@ export function fromSpecTokenUsage(
   usage: ReadonlyArray<SpecTokenUsage> | undefined,
   leftover?: TokenUsageLeftover,
 ): TokenUsage | undefined {
-  const spec = usage?.[0]
-  if (spec == null && leftover == null) {
+  const spec = usage?.reduce<SpecTokenUsage>((total, entry) => {
+    for (const key of [
+      'inputTokens',
+      'outputTokens',
+      'totalTokens',
+      'cachedInputTokens',
+      'cacheWriteInputTokens',
+      'reasoningTokens',
+    ] as const) {
+      if (entry[key] !== undefined) total[key] = (total[key] ?? 0) + entry[key]
+    }
+    return total
+  }, {})
+  if ((usage === undefined || usage.length === 0) && leftover == null) {
     return undefined
   }
 
@@ -126,6 +210,9 @@ export function fromSpecTokenUsage(
     ...(spec?.cachedInputTokens !== undefined
       ? { cachedTokens: spec.cachedInputTokens }
       : {}),
+    ...(spec?.cacheWriteInputTokens !== undefined
+      ? { cacheWriteTokens: spec.cacheWriteInputTokens }
+      : {}),
     ...leftoverPromptDetails,
   })
   const completionTokensDetails = definedDetails({