feat: improve usage

docs/protocol/chunk-definitions.md

@@ -266,15 +266,47 @@ Emitted when the stream completes successfully.
 interface DoneStreamChunk extends BaseStreamChunk {
   type: 'done';
   finishReason: 'stop' | 'length' | 'content_filter' | 'tool_calls' | null;
-  usage?: {
-    promptTokens: number;
-    completionTokens: number;
-    totalTokens: number;
+  usage?: TokenUsage;
+}
+
+interface TokenUsage {
+  // Core token counts (always present when usage is available)
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+
+  // Detailed prompt token breakdown
+  promptTokensDetails?: {
+    cachedTokens?: number;       // Tokens from prompt cache hits
+    cacheWriteTokens?: number;   // Tokens written to cache
+    cacheCreationTokens?: number; // Anthropic cache creation tokens
+    cacheReadTokens?: number;    // Anthropic cache read tokens
+    audioTokens?: number;        // Audio input tokens
+    videoTokens?: number;        // Video input tokens
+    imageTokens?: number;        // Image input tokens
+    textTokens?: number;         // Text input tokens
+  };
+
+  // Detailed completion token breakdown  
+  completionTokensDetails?: {
+    reasoningTokens?: number;    // Reasoning/thinking tokens (o1, Claude)
+    audioTokens?: number;        // Audio output tokens
+    videoTokens?: number;        // Video output tokens
+    imageTokens?: number;        // Image output tokens
+    textTokens?: number;         // Text output tokens
+    acceptedPredictionTokens?: number;  // Accepted prediction tokens
+    rejectedPredictionTokens?: number;  // Rejected prediction tokens
   };
+
+  // Provider-specific details
+  providerUsageDetails?: Record<string, unknown>;
+
+  // Duration (for some billing models)
+  durationSeconds?: number;
 }
 ```
 
-**Example:**
+**Example (basic usage):**
 ```json
 {
   "type": "done",
@@ -290,6 +322,64 @@ interface DoneStreamChunk extends BaseStreamChunk {
 }
 ```
 
+**Example (with cached tokens - OpenAI):**
+```json
+{
+  "type": "done",
+  "id": "chatcmpl-abc123",
+  "model": "gpt-4o",
+  "timestamp": 1701234567892,
+  "finishReason": "stop",
+  "usage": {
+    "promptTokens": 150,
+    "completionTokens": 75,
+    "totalTokens": 225,
+    "promptTokensDetails": {
+      "cachedTokens": 100
+    }
+  }
+}
+```
+
+**Example (with reasoning tokens - o1):**
+```json
+{
+  "type": "done",
+  "id": "chatcmpl-abc123",
+  "model": "o1-preview",
+  "timestamp": 1701234567892,
+  "finishReason": "stop",
+  "usage": {
+    "promptTokens": 150,
+    "completionTokens": 500,
+    "totalTokens": 650,
+    "completionTokensDetails": {
+      "reasoningTokens": 425
+    }
+  }
+}
+```
+
+**Example (Anthropic with cache):**
+```json
+{
+  "type": "done",
+  "id": "msg_abc123",
+  "model": "claude-3-5-sonnet",
+  "timestamp": 1701234567892,
+  "finishReason": "stop",
+  "usage": {
+    "promptTokens": 150,
+    "completionTokens": 75,
+    "totalTokens": 225,
+    "promptTokensDetails": {
+      "cacheCreationTokens": 50,
+      "cacheReadTokens": 100
+    }
+  }
+}
+```
+
 **Finish Reasons:**
 - `stop` - Natural completion
 - `length` - Reached max tokens
@@ -302,6 +392,13 @@ interface DoneStreamChunk extends BaseStreamChunk {
 - Clean up streaming state
 - Display token usage (if available)
 
+**Token Usage Notes:**
+- `promptTokensDetails.cachedTokens` - OpenAI prompt caching
+- `promptTokensDetails.cacheCreationTokens` / `cacheReadTokens` - Anthropic caching
+- `completionTokensDetails.reasoningTokens` - Internal reasoning tokens (o1, Claude thinking)
+- `providerUsageDetails` - Provider-specific fields not in the standard schema
+- For Gemini, modality-specific token counts (audio, video, image, text) are extracted from the response
+
 ---
 
 ### ErrorStreamChunk

examples/ts-react-chat/src/routes/api.tanchat.ts

@@ -129,8 +129,10 @@ export const Route = createFileRoute('/api/tanchat')({
           openai: () =>
             createChatOptions({
               adapter: openaiText((model || 'gpt-4o') as 'gpt-4o'),
-              temperature: 2,
-              modelOptions: {},
+              modelOptions: {
+                prompt_cache_key: 'user-session-12345',
+                prompt_cache_retention: '24h',
+              },
             }),
         }
 

packages/typescript/ai-anthropic/package.json

@@ -40,7 +40,7 @@
     "test:types": "tsc"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.71.0"
+    "@anthropic-ai/sdk": "^0.71.2"
   },
   "peerDependencies": {
     "@tanstack/ai": "workspace:^",

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

@@ -1,4 +1,5 @@
 import { BaseSummarizeAdapter } from '@tanstack/ai/adapters'
+import { buildAnthropicUsage } from '../usage'
 import {
   createAnthropicClient,
   generateId,
@@ -52,7 +53,7 @@ export class AnthropicSummarizeAdapter<
   async summarize(options: SummarizationOptions): Promise<SummarizationResult> {
     const systemPrompt = this.buildSummarizationPrompt(options)
 
-    const response = await this.client.messages.create({
+    const response = await this.client.beta.messages.create({
       model: options.model,
       messages: [{ role: 'user', content: options.text }],
       system: systemPrompt,
@@ -69,11 +70,7 @@ export class AnthropicSummarizeAdapter<
       id: response.id,
       model: response.model,
       summary: content,
-      usage: {
-        promptTokens: response.usage.input_tokens,
-        completionTokens: response.usage.output_tokens,
-        totalTokens: response.usage.input_tokens + response.usage.output_tokens,
-      },
+      usage: buildAnthropicUsage(response.usage),
     }
   }
 
@@ -84,10 +81,8 @@ export class AnthropicSummarizeAdapter<
     const id = generateId(this.name)
     const model = options.model
     let accumulatedContent = ''
-    let inputTokens = 0
-    let outputTokens = 0
 
-    const stream = await this.client.messages.create({
+    const stream = await this.client.beta.messages.create({
       model: options.model,
       messages: [{ role: 'user', content: options.text }],
       system: systemPrompt,
@@ -98,7 +93,6 @@ export class AnthropicSummarizeAdapter<
 
     for await (const event of stream) {
       if (event.type === 'message_start') {
-        inputTokens = event.message.usage.input_tokens
       } else if (event.type === 'content_block_delta') {
         if (event.delta.type === 'text_delta') {
           const delta = event.delta.text
@@ -114,7 +108,6 @@ export class AnthropicSummarizeAdapter<
           }
         }
       } else if (event.type === 'message_delta') {
-        outputTokens = event.usage.output_tokens
         yield {
           type: 'done',
           id,
@@ -125,11 +118,7 @@ export class AnthropicSummarizeAdapter<
             | 'length'
             | 'content_filter'
             | null,
-          usage: {
-            promptTokens: inputTokens,
-            completionTokens: outputTokens,
-            totalTokens: inputTokens + outputTokens,
-          },
+          usage: buildAnthropicUsage(event.usage),
         }
       }
     }

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

@@ -1,6 +1,7 @@
 import { BaseTextAdapter } from '@tanstack/ai/adapters'
 import { convertToolsToProviderFormat } from '../tools/tool-converter'
 import { validateTextProviderOptions } from '../text/text-provider-options'
+import { buildAnthropicUsage } from '../usage'
 import {
   createAnthropicClient,
   generateId,
@@ -175,7 +176,7 @@ export class AnthropicTextAdapter<
 
     try {
       // Make non-streaming request with tool_choice forced to our structured output tool
-      const response = await this.client.messages.create(
+      const response = await this.client.beta.messages.create(
         {
           ...requestParams,
           stream: false,
@@ -222,6 +223,7 @@ export class AnthropicTextAdapter<
       return {
         data: parsed,
         rawText,
+        usage: buildAnthropicUsage(response.usage),
       }
     } catch (error: unknown) {
       const err = error as Error
@@ -560,13 +562,7 @@ export class AnthropicTextAdapter<
                   model: model,
                   timestamp,
                   finishReason: 'tool_calls',
-                  usage: {
-                    promptTokens: event.usage.input_tokens || 0,
-                    completionTokens: event.usage.output_tokens || 0,
-                    totalTokens:
-                      (event.usage.input_tokens || 0) +
-                      (event.usage.output_tokens || 0),
-                  },
+                  usage: buildAnthropicUsage(event.usage),
                 }
                 break
               }
@@ -591,13 +587,7 @@ export class AnthropicTextAdapter<
                   model: model,
                   timestamp,
                   finishReason: 'stop',
-                  usage: {
-                    promptTokens: event.usage.input_tokens || 0,
-                    completionTokens: event.usage.output_tokens || 0,
-                    totalTokens:
-                      (event.usage.input_tokens || 0) +
-                      (event.usage.output_tokens || 0),
-                  },
+                  usage: buildAnthropicUsage(event.usage),
                 }
               }
             }

packages/typescript/ai-anthropic/src/index.ts

@@ -44,3 +44,6 @@ export { convertToolsToProviderFormat } from './tools/tool-converter'
 
 // Export tool types
 export type { AnthropicTool, CustomTool } from './tools'
+
+// Export provider usage types
+export type { AnthropicProviderUsageDetails } from './usage'

packages/typescript/ai-anthropic/src/usage.ts

@@ -0,0 +1,66 @@
+import { buildBaseUsage } from '@tanstack/ai'
+import type { TokenUsage } from '@tanstack/ai'
+import type Anthropic_SDK from '@anthropic-ai/sdk'
+
+/**
+ * Anthropic-specific provider usage details.
+ * These fields are unique to Anthropic and placed in providerUsageDetails.
+ */
+export interface AnthropicProviderUsageDetails {
+  /**
+   * Server-side tool usage metrics.
+   * Available when using Anthropic's built-in tools like web search.
+   */
+  serverToolUse?: {
+    /** Number of web search requests made during the response */
+    webSearchRequests?: number
+    /** Number of web fetch requests made during the response */
+    webFetchRequests?: number
+  }
+  /** Index signature for Record<string, unknown> compatibility */
+  [key: string]: unknown
+}
+
+/**
+ * Build normalized TokenUsage from Anthropic's usage object.
+ * Handles cache tokens and server tool use metrics.
+ */
+export function buildAnthropicUsage(
+  usage:
+    | Anthropic_SDK.Beta.BetaUsage
+    | Anthropic_SDK.Beta.BetaMessageDeltaUsage,
+): TokenUsage {
+  const inputTokens = usage.input_tokens ?? 0
+  const outputTokens = usage.output_tokens
+
+  const result = buildBaseUsage({
+    promptTokens: inputTokens,
+    completionTokens: outputTokens,
+    totalTokens: inputTokens + outputTokens,
+  })
+
+  // Add prompt token details for cache tokens
+  const cacheCreation = usage.cache_creation_input_tokens
+  const cacheRead = usage.cache_read_input_tokens
+
+  result.promptTokensDetails = {
+    ...(cacheCreation ? { cacheWriteTokens: cacheCreation } : {}),
+    ...(cacheRead ? { cachedTokens: cacheRead } : {}),
+  }
+
+  // Add provider-specific usage details for server tool use
+  const serverToolUse = usage.server_tool_use
+
+  result.providerUsageDetails = {
+    serverToolUse: {
+      ...(serverToolUse?.web_search_requests
+        ? { webSearchRequests: serverToolUse.web_search_requests }
+        : {}),
+      ...(serverToolUse?.web_fetch_requests
+        ? { webFetchRequests: serverToolUse.web_fetch_requests }
+        : {}),
+    },
+  } satisfies AnthropicProviderUsageDetails
+
+  return result
+}