feat: expose cached token count in usage statistics

packages/typescript/ai-anthropic/src/adapters/text.ts

@@ -1053,6 +1053,9 @@ export class AnthropicTextAdapter<
                     totalTokens:
                       (event.usage.input_tokens || 0) +
                       (event.usage.output_tokens || 0),
+                    ...(event.usage.cache_read_input_tokens != null && {
+                      cachedTokens: event.usage.cache_read_input_tokens,
+                    }),
                   },
                 }
                 break
@@ -1096,6 +1099,9 @@ export class AnthropicTextAdapter<
                     totalTokens:
                       (event.usage.input_tokens || 0) +
                       (event.usage.output_tokens || 0),
+                    ...(event.usage.cache_read_input_tokens != null && {
+                      cachedTokens: event.usage.cache_read_input_tokens,
+                    }),
                   },
                 }
               }

packages/typescript/ai-gemini/src/adapters/text.ts

@@ -631,6 +631,9 @@ export class GeminiTextAdapter<
               promptTokens: chunk.usageMetadata.promptTokenCount ?? 0,
               completionTokens: chunk.usageMetadata.candidatesTokenCount ?? 0,
               totalTokens: chunk.usageMetadata.totalTokenCount ?? 0,
+              ...(chunk.usageMetadata.cachedContentTokenCount != null && {
+                cachedTokens: chunk.usageMetadata.cachedContentTokenCount,
+              }),
             },
           }),
         }

packages/typescript/ai-openrouter/src/adapters/text.ts

@@ -549,6 +549,9 @@ export class OpenRouterTextAdapter<
             promptTokens: lastUsage.promptTokens,
             completionTokens: lastUsage.completionTokens,
             totalTokens: lastUsage.totalTokens,
+            ...(lastUsage.promptTokensDetails?.cachedTokens != null && {
+              cachedTokens: lastUsage.promptTokensDetails.cachedTokens,
+            }),
           },
         }),
       }
@@ -1076,6 +1079,9 @@ export class OpenRouterTextAdapter<
               promptTokens: lastUsage.promptTokens || 0,
               completionTokens: lastUsage.completionTokens || 0,
               totalTokens: lastUsage.totalTokens || 0,
+              ...(lastUsage.promptTokensDetails?.cachedTokens != null && {
+                cachedTokens: lastUsage.promptTokensDetails.cachedTokens,
+              }),
             },
           }),
           finishReason,

packages/typescript/ai/src/activities/chat/middleware/types.ts

@@ -267,6 +267,8 @@ export interface UsageInfo {
   promptTokens: number
   completionTokens: number
   totalTokens: number
+  /** Number of prompt tokens served from cache (provider-dependent) */
+  cachedTokens?: number
 }
 
 // ===========================
@@ -289,6 +291,8 @@ export interface FinishInfo {
         promptTokens: number
         completionTokens: number
         totalTokens: number
+        /** Number of prompt tokens served from cache (provider-dependent) */
+        cachedTokens?: number
       }
     | undefined
 }

packages/typescript/ai/src/types.ts

@@ -925,6 +925,8 @@ export interface RunFinishedEvent extends AGUIRunFinishedEvent {
     promptTokens: number
     completionTokens: number
     totalTokens: number
+    /** Number of prompt tokens served from cache (provider-dependent) */
+    cachedTokens?: number
   }
 }
 
@@ -1375,6 +1377,7 @@ export interface TextCompletionChunk {
     promptTokens: number
     completionTokens: number
     totalTokens: number
+    cachedTokens?: number
   }
 }
 
@@ -1403,6 +1406,7 @@ export interface SummarizationResult {
     promptTokens: number
     completionTokens: number
     totalTokens: number
+    cachedTokens?: number
   }
 }
 

packages/typescript/openai-base/src/adapters/chat-completions-text.ts

@@ -502,6 +502,9 @@ export abstract class OpenAIBaseChatCompletionsTextAdapter<
             promptTokens: lastUsage.prompt_tokens,
             completionTokens: lastUsage.completion_tokens,
             totalTokens: lastUsage.total_tokens,
+            ...(lastUsage.prompt_tokens_details?.cached_tokens != null && {
+              cachedTokens: lastUsage.prompt_tokens_details.cached_tokens,
+            }),
           },
         }),
       }
@@ -1057,6 +1060,9 @@ export abstract class OpenAIBaseChatCompletionsTextAdapter<
               promptTokens: lastUsage.prompt_tokens || 0,
               completionTokens: lastUsage.completion_tokens || 0,
               totalTokens: lastUsage.total_tokens || 0,
+              ...(lastUsage.prompt_tokens_details?.cached_tokens != null && {
+                cachedTokens: lastUsage.prompt_tokens_details.cached_tokens,
+              }),
             },
           }),
           finishReason,

packages/typescript/openai-base/src/adapters/responses-text.ts

@@ -594,6 +594,9 @@ export abstract class OpenAIBaseResponsesTextAdapter<
             promptTokens: usage.input_tokens,
             completionTokens: usage.output_tokens,
             totalTokens: usage.total_tokens,
+            ...(usage.input_tokens_details?.cached_tokens != null && {
+              cachedTokens: usage.input_tokens_details.cached_tokens,
+            }),
           },
         }),
       }
@@ -1505,6 +1508,11 @@ export abstract class OpenAIBaseResponsesTextAdapter<
               promptTokens: chunk.response.usage?.input_tokens || 0,
               completionTokens: chunk.response.usage?.output_tokens || 0,
               totalTokens: chunk.response.usage?.total_tokens || 0,
+              ...(chunk.response.usage?.input_tokens_details?.cached_tokens !=
+                null && {
+                cachedTokens:
+                  chunk.response.usage.input_tokens_details.cached_tokens,
+              }),
             },
             finishReason,
           }