feat (provider): support reasoning tokens, cached input tokens, total token in usage information (#6140)

## Background

Over the past year, additional token usage information such as cached
input tokens and reasoning tokens were added by many providers. In
addition, the meaning of total tokens is now provider-dependent, with
some providers including reasoning tokens in the total token count.

## Summary

Standardize sending reasoning tokens, cached prompt tokens, and total
tokens from the providers.

Author: lgrammel

.changeset/silver-vans-march.md

@@ -0,0 +1,5 @@
+---
+'@ai-sdk/provider': major
+---
+
+feat (provider): support reasoning tokens, cached input tokens, total token in usage information

content/providers/01-ai-sdk-providers/05-anthropic.mdx

@@ -183,7 +183,7 @@ const result = await generateText({
 
 console.log(result.text);
 console.log(result.providerMetadata?.anthropic);
-// e.g. { cacheCreationInputTokens: 2118, cacheReadInputTokens: 0 }
+// e.g. { cacheCreationInputTokens: 2118 }
 ```
 
 You can also use cache control on system messages by providing multiple system messages at the head of your messages array:

examples/ai-core/src/generate-object/mock-error.ts

@@ -16,7 +16,11 @@ async function main() {
             modelId: 'model-1',
           },
           finishReason: 'stop',
-          usage: { inputTokens: 10, outputTokens: 20 },
+          usage: {
+            inputTokens: 10,
+            outputTokens: 20,
+            totalTokens: 30,
+          },
         }),
       }),
       schema: z.object({ content: z.string() }),

examples/ai-core/src/generate-object/mock-repair-add-close.ts

@@ -7,7 +7,11 @@ async function main() {
   const result = await generateObject({
     model: new MockLanguageModelV2({
       doGenerate: async () => ({
-        usage: { inputTokens: 10, outputTokens: 20 },
+        usage: {
+          inputTokens: 10,
+          outputTokens: 20,
+          totalTokens: 30,
+        },
         warnings: [],
         finishReason: 'tool-calls',
         content: [

examples/ai-core/src/generate-object/mock.ts

@@ -9,7 +9,11 @@ async function main() {
       doGenerate: async () => ({
         content: [{ type: 'text', text: `{"content":"Hello, world!"}` }],
         finishReason: 'stop',
-        usage: { inputTokens: 10, outputTokens: 20 },
+        usage: {
+          inputTokens: 10,
+          outputTokens: 20,
+          totalTokens: 30,
+        },
         warnings: [],
       }),
     }),

examples/ai-core/src/generate-text/anthropic-cache-control.ts

@@ -35,8 +35,13 @@ async function main() {
   });
 
   console.log(result.text);
-  console.log(result.providerMetadata?.anthropic);
-  // e.g. { cacheCreationInputTokens: 2118, cacheReadInputTokens: 0 }
+  console.log();
+
+  console.log('Cache read tokens:', result.usage.cachedInputTokens);
+  console.log(
+    'Cache write tokens:',
+    result.providerMetadata?.anthropic?.cacheCreationInputTokens,
+  );
 }
 
 main().catch(console.error);

examples/ai-core/src/generate-text/mock-tool-call-repair-reask.ts

@@ -9,7 +9,11 @@ async function main() {
     model: new MockLanguageModelV2({
       doGenerate: async () => ({
         warnings: [],
-        usage: { inputTokens: 10, outputTokens: 20 },
+        usage: {
+          inputTokens: 10,
+          outputTokens: 20,
+          totalTokens: 30,
+        },
         finishReason: 'tool-calls',
         content: [
           {

examples/ai-core/src/generate-text/mock-tool-call-repair-structured-model.ts

@@ -9,7 +9,11 @@ async function main() {
     model: new MockLanguageModelV2({
       doGenerate: async () => ({
         warnings: [],
-        usage: { inputTokens: 10, outputTokens: 20 },
+        usage: {
+          inputTokens: 10,
+          outputTokens: 20,
+          totalTokens: 30,
+        },
         finishReason: 'tool-calls',
         content: [
           {

examples/ai-core/src/generate-text/mock.ts

@@ -8,7 +8,11 @@ async function main() {
       doGenerate: async () => ({
         content: [{ type: 'text', text: `Hello, world!` }],
         finishReason: 'stop',
-        usage: { inputTokens: 10, outputTokens: 20 },
+        usage: {
+          inputTokens: 10,
+          outputTokens: 20,
+          totalTokens: 30,
+        },
         warnings: [],
       }),
     }),

examples/ai-core/src/generate-text/openai-reasoning.ts

@@ -3,19 +3,15 @@ import { generateText } from 'ai';
 import 'dotenv/config';
 
 async function main() {
-  const { text, usage, providerMetadata } = await generateText({
+  const { text, usage } = await generateText({
     model: openai('o3-mini'),
     prompt: 'How many "r"s are in the word "strawberry"?',
     temperature: 0.5, // should get ignored (warning)
     maxOutputTokens: 1000, // mapped to max_completion_tokens
   });
 
   console.log(text);
-  console.log();
-  console.log('Usage:', {
-    ...usage,
-    reasoningTokens: providerMetadata?.openai?.reasoningTokens,
-  });
+  console.log('Usage:', usage);
 }
 
 main().catch(console.error);