ai 7.0.122 → 7.0.124

package/docs/07-reference/02-ai-sdk-ui/50-direct-chat-transport.mdx

@@ -61,14 +61,14 @@ export default function Chat() {
       type: 'UIMessage[]',
       isOptional: true,
       description:
-        'The original messages. If provided, persistence mode is assumed, and a message ID is provided for the response message.',
+        'The original messages. If provided, persistence mode is assumed, and a message ID is provided for the response message (generated with `generateMessageId`, or reused from the last message when it is an assistant message).',
     },
     {
       name: 'generateMessageId',
       type: 'IdGenerator',
       isOptional: true,
       description:
-        'Generate a message ID for the response message. If not provided, no message ID will be set for the response message.',
+        'Generate a message ID for the response message. If not provided, no message ID will be set for the response message (unless the original messages are provided and the last message is an assistant message).',
     },
     {
       name: 'messageMetadata',

package/docs/07-reference/03-ai-sdk-rsc/01-stream-ui.mdx

@@ -208,7 +208,7 @@ To see `streamUI` in action, check out [these examples](#examples).
             {
               name: 'role',
               type: "'tool'",
-              description: 'The role for the assistant message.',
+              description: 'The role for the tool message.',
             },
             {
               name: 'content',
@@ -364,7 +364,7 @@ To see `streamUI` in action, check out [these examples](#examples).
             {
               name: 'generate',
               isOptional: true,
-              type: '(async (parameters) => ReactNode) | AsyncGenerator<ReactNode, ReactNode, void>',
+              type: '(parameters) => ReactNode | Promise<ReactNode> | Generator<ReactNode, ReactNode, void> | AsyncGenerator<ReactNode, ReactNode, void>',
               description:
                 'A function or a generator function that is called with the arguments from the tool call and yields React nodes as the UI.',
             },

package/docs/07-reference/04-ai-sdk-workflow/01-workflow-agent.mdx

@@ -1022,7 +1022,7 @@ const result = await agent.stream({
   messages,
 
   // Per-call callbacks (both fire)
-  onStepEnd({ usage }) {
+  async onStepEnd({ usage }) {
     await trackUsage(usage);
   },
 

package/docs/08-migration-guides/25-migration-guide-5-0-data.mdx

@@ -127,6 +127,7 @@ type V4FilePart = Extract<V4Part, { type: 'file' }>;
 // Type guards
 function isV4Message(msg: V4Message | MyUIMessage): msg is V4Message {
   return (
+    msg?.parts == null ||
     'toolInvocations' in msg ||
     (msg?.parts?.some(p => p.type === 'tool-invocation') ?? false) ||
     msg?.role === 'data' ||
@@ -465,9 +466,8 @@ export async function POST(req: Request) {
     message: convertV5MessageToV4(message), // convert to v4
   });
 
-  // Load previous messages (already in v5 format)
-  const previousMessages = await loadChat(chatId);
-  const messages = [...previousMessages, message];
+  // Load all messages, including the one just saved (already in v5 format)
+  const messages = await loadChat(chatId);
 
   const result = streamText({
     model: __MODEL__,
@@ -827,8 +827,7 @@ export async function POST(req: Request) {
     message,
   });
 
-  const previousMessages = await loadChat(chatId);
-  const messages = [...previousMessages, message];
+  const messages = await loadChat(chatId);
 
   const result = streamText({
     model: __MODEL__,

package/docs/08-migration-guides/26-migration-guide-5-0.mdx

@@ -723,7 +723,8 @@ const runtimeTool = dynamicTool({
   inputSchema: z.object({}),
   execute: async input => {
     // Input and output are typed as 'unknown'
-    return { result: `Processed: ${input.query}` };
+    const { query } = input as { query: string };
+    return { result: `Processed: ${query}` };
   },
 });
 ```

package/docs/08-migration-guides/29-migration-guide-4-0.mdx

@@ -440,7 +440,7 @@ const result = streamText({
 
 result.toDataStream();
 result.pipeDataStreamToResponse(response);
-result.toUIMessageStreamResponse();
+result.toDataStreamResponse();
 ```
 
 ### Renamed "formatStreamPart" to "formatDataStreamPart"
@@ -573,7 +573,7 @@ const result = await streamText({
   // ...
 });
 
-result.toUIMessageStreamResponse(response, {
+result.pipeDataStreamToResponse(response, {
   init: {
     headers: {
       'X-Custom-Header': 'value',
@@ -588,7 +588,7 @@ const result = streamText({
   // ...
 });
 
-result.toUIMessageStreamResponse(response, {
+result.pipeDataStreamToResponse(response, {
   headers: {
     'X-Custom-Header': 'value',
   },
@@ -710,7 +710,7 @@ const warnings = await result.warnings;
   code manually.
 </Note>
 
-The `simulateReadableStream` function from `ai/test` has been renamed to `chunks`.
+The `values` option of the `simulateReadableStream` function from `ai/test` has been renamed to `chunks`.
 
 ```ts filename="AI SDK 3.4"
 import { simulateReadableStream } from 'ai/test';

package/docs/08-migration-guides/38-migration-guide-3-2.mdx

@@ -23,7 +23,7 @@ This guide will help you upgrade to AI SDK 3.2:
 
 To update to AI SDK version 3.2, run the following command using your preferred package manager:
 
-<Snippet text="pnpm add ai@latest" />
+<Snippet text="pnpm add ai@3.2" />
 
 ## Removed Functionality
 

package/docs/08-migration-guides/39-migration-guide-3-1.mdx

@@ -80,7 +80,7 @@ export async function POST(req: Request) {
     messages,
   });
 
-  return result.toUIMessageStreamResponse();
+  return result.toDataStreamResponse();
 }
 ```
 

package/docs/09-troubleshooting/12-use-chat-an-error-occurred.mdx

@@ -49,14 +49,16 @@ return createUIMessageStreamResponse({
 });
 ```
 
-In case you are using `createDataStreamResponse`, you can use the `onError` function when calling `toDataStreamResponse`:
+In case you are using `createUIMessageStream`, you can pass the `onError` function to it:
 
 ```tsx
-const response = createDataStreamResponse({
-  // ...
-  async execute(dataStream) {
+const response = createUIMessageStreamResponse({
+  stream: createUIMessageStream({
     // ...
-  },
-  onError: errorHandler,
+    async execute({ writer }) {
+      // ...
+    },
+    onError: errorHandler,
+  }),
 });
 ```

package/docs/09-troubleshooting/50-react-maximum-update-depth-exceeded.mdx

@@ -23,17 +23,17 @@ Use the `throttle` option to throttle the UI updates:
 ### `useChat`
 
 ```tsx filename="page.tsx" highlight="2-3"
-const { messages, ... } = useChat({
+const { messages } = useChat({
   // Throttle the messages and data updates to 50ms:
-  throttle: 50
-})
+  throttle: 50,
+});
 ```
 
 ### `useCompletion`
 
 ```tsx filename="page.tsx" highlight="2-3"
-const { completion, ... } = useCompletion({
+const { completion } = useCompletion({
   // Throttle the completion and data updates to 50ms:
-  throttle: 50
-})
+  throttle: 50,
+});
 ```

package/docs/09-troubleshooting/70-high-memory-usage-with-images.mdx

@@ -17,7 +17,7 @@ This is especially noticeable when using `experimental_download` to process imag
 
 ## Background
 
-By default, the AI SDK includes the full request messages plus request and response bodies in the step results. When processing images, the request messages and request body can contain base64-encoded image data, which can be very large (a single image can be 1MB+ when base64 encoded). If you process many images and keep references to the results, this data accumulates in memory.
+When enabled with the `include` option, the AI SDK includes the full request messages plus request and response bodies in the step results. When processing images, the request messages and request body can contain base64-encoded image data, which can be very large (a single image can be 1MB+ when base64 encoded). If you process many images and keep references to the results, this data accumulates in memory.
 
 For example, processing 100 images of 500KB each would include ~50MB+ of request body data in memory.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai",
-  "version": "7.0.122",
+  "version": "7.0.124",
   "type": "module",
   "description": "AI SDK by Vercel - build apps like ChatGPT, Claude, Gemini, and more with a single interface for any model using the Vercel AI Gateway or go direct to OpenAI, Anthropic, Google, or any other model provider.",
   "license": "Apache-2.0",
@@ -42,20 +42,20 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/gateway": "4.0.100",
-    "@ai-sdk/provider": "4.0.19",
-    "@ai-sdk/provider-utils": "5.0.51"
+    "@ai-sdk/gateway": "4.0.102",
+    "@ai-sdk/provider": "4.0.21",
+    "@ai-sdk/provider-utils": "5.0.53"
   },
   "devDependencies": {
-    "@ai-sdk/amazon-bedrock": "5.0.100",
-    "@ai-sdk/deepseek": "3.0.56",
-    "@ai-sdk/google": "4.0.85",
-    "@ai-sdk/groq": "4.0.52",
-    "@ai-sdk/huggingface": "2.0.59",
-    "@ai-sdk/moonshotai": "3.0.60",
-    "@ai-sdk/openai": "4.0.80",
-    "@ai-sdk/test-server": "2.0.2",
-    "@ai-sdk/xai": "5.0.12",
+    "@ai-sdk/amazon-bedrock": "5.0.103",
+    "@ai-sdk/deepseek": "3.0.58",
+    "@ai-sdk/google": "4.0.87",
+    "@ai-sdk/groq": "4.0.54",
+    "@ai-sdk/huggingface": "2.0.61",
+    "@ai-sdk/moonshotai": "3.0.62",
+    "@ai-sdk/openai": "4.0.83",
+    "@ai-sdk/test-server": "2.0.3",
+    "@ai-sdk/xai": "5.0.14",
     "@edge-runtime/vm": "^5.0.0",
     "@smithy/eventstream-codec": "^4.3.3",
     "@smithy/util-utf8": "^4.3.3",
@@ -63,7 +63,7 @@
     "@types/node": "22.19.19",
     "@vercel/ai-tsconfig": "0.0.0",
     "esbuild": "^0.28.1",
-    "tsup": "^8.5.1",
+    "tsdown": "^0.23.0",
     "tsx": "4.23.12",
     "typescript": "5.8.3",
     "zod": "3.25.76"
@@ -113,9 +113,9 @@
     "grok"
   ],
   "scripts": {
-    "build": "pnpm clean && tsup --tsconfig tsconfig.build.json",
-    "build:watch": "pnpm clean && tsup --watch --tsconfig tsconfig.build.json",
-    "clean": "del-cli dist docs *.tsbuildinfo",
+    "build": "pnpm clean && tsdown",
+    "build:watch": "pnpm clean && tsdown --watch",
+    "clean": "del-cli docs *.tsbuildinfo",
     "type-check": "tsc --build",
     "test": "pnpm test:node && pnpm test:edge",
     "test:update": "pnpm test:node -u",

package/src/agent/create-agent-ui-stream-response.ts

@@ -33,6 +33,7 @@ import { createAgentUIStream } from './create-agent-ui-stream';
  * @param headers - Additional headers for the response. Optional.
  * @param status - The status code for the response. Optional.
  * @param statusText - The status text for the response. Optional.
+ * @param keepAliveMs - Optional interval for sending SSE keep-alive comments.
  * @param consumeSseStream - Whether to consume the SSE stream. Optional.
  *
  * @returns The response object.
@@ -47,6 +48,7 @@ export async function createAgentUIStreamResponse<
   headers,
   status,
   statusText,
+  keepAliveMs,
   consumeSseStream,
   ...options
 }: {
@@ -68,6 +70,7 @@ export async function createAgentUIStreamResponse<
     headers,
     status,
     statusText,
+    keepAliveMs,
     consumeSseStream,
     stream: await createAgentUIStream(options),
   });

package/src/agent/pipe-agent-ui-stream-to-response.ts

@@ -35,6 +35,7 @@ import { createAgentUIStream } from './create-agent-ui-stream';
  * @param headers - Additional headers for the response. Optional.
  * @param status - The status code for the response. Optional.
  * @param statusText - The status text for the response. Optional.
+ * @param keepAliveMs - Optional interval for sending SSE keep-alive comments.
  * @param consumeSseStream - Whether to consume the SSE stream. Optional.
  */
 export async function pipeAgentUIStreamToResponse<
@@ -48,6 +49,7 @@ export async function pipeAgentUIStreamToResponse<
   headers,
   status,
   statusText,
+  keepAliveMs,
   consumeSseStream,
   ...options
 }: {
@@ -71,6 +73,7 @@ export async function pipeAgentUIStreamToResponse<
     headers,
     status,
     statusText,
+    keepAliveMs,
     consumeSseStream,
     stream: await createAgentUIStream(options),
   });

package/src/generate-speech/generate-speech.ts

@@ -1,5 +1,6 @@
 import type { JSONObject } from '@ai-sdk/provider';
 import {
+  createIdGenerator,
   detectMediaType,
   withUserAgentSuffix,
   type ProviderOptions,
@@ -7,16 +8,28 @@ import {
 import { NoSpeechGeneratedError } from '../error/no-speech-generated-error';
 import { logWarnings } from '../logger/log-warnings';
 import { resolveSpeechModel } from '../model/resolve-model';
+import { createTelemetryDispatcher } from '../telemetry/create-telemetry-dispatcher';
+import type { TelemetryOptions } from '../telemetry/telemetry-options';
 import type { SpeechModel } from '../types/speech-model';
 import type { SpeechModelResponseMetadata } from '../types/speech-model-response-metadata';
 import type { Warning } from '../types/warning';
 import { prepareRetries } from '../util/prepare-retries';
+import { notify } from '../util/notify';
 import { VERSION } from '../version';
 import type { SpeechResult } from './generate-speech-result';
 import {
   DefaultGeneratedAudioFile,
   type GeneratedAudioFile,
 } from './generated-audio-file';
+import type {
+  GenerateSpeechEndEvent,
+  GenerateSpeechStartEvent,
+} from './speech-events';
+
+const originalGenerateCallId = createIdGenerator({
+  prefix: 'call',
+  size: 24,
+});
 /**
  * Generates speech audio using a speech model.
  *
@@ -32,6 +45,7 @@ import {
  * @param maxRetries - Maximum number of retries. Set to 0 to disable retries. Default: 2.
  * @param abortSignal - An optional abort signal that can be used to cancel the call.
  * @param headers - Additional HTTP headers to be sent with the request. Only applicable for HTTP-based providers.
+ * @param telemetry - Optional telemetry configuration.
  *
  * @returns A result object that contains the generated audio data.
  */
@@ -47,6 +61,8 @@ export async function generateSpeech({
   maxRetries: maxRetriesArg,
   abortSignal,
   headers,
+  telemetry,
+  _internal: { generateCallId = originalGenerateCallId } = {},
 }: {
   /**
    * The speech model to use.
@@ -115,6 +131,18 @@ export async function generateSpeech({
    * Only applicable for HTTP-based providers.
    */
   headers?: Record<string, string>;
+
+  /**
+   * Optional telemetry configuration.
+   */
+  telemetry?: TelemetryOptions;
+
+  /**
+   * Internal. For test use only. May change without notice.
+   */
+  _internal?: {
+    generateCallId?: () => string;
+  };
 }): Promise<SpeechResult> {
   const resolvedModel = resolveSpeechModel(model);
   if (!resolvedModel) {
@@ -126,55 +154,152 @@ export async function generateSpeech({
     `ai/${VERSION}`,
   );
 
-  const { retry } = prepareRetries({
+  const { maxRetries, retry } = prepareRetries({
     maxRetries: maxRetriesArg,
     abortSignal,
   });
 
-  const result = await retry(() =>
-    resolvedModel.doGenerate({
-      text,
-      voice,
-      outputFormat,
-      instructions,
-      speed,
-      language,
-      abortSignal,
-      headers: headersWithUserAgent,
-      providerOptions,
-    }),
-  );
-
-  if (!result.audio || result.audio.length === 0) {
-    throw new NoSpeechGeneratedError({ responses: [result.response] });
-  }
+  const callId = generateCallId();
+  const telemetryDispatcher = createTelemetryDispatcher({ telemetry });
+  const runInTracingChannelSpan =
+    telemetryDispatcher.runInTracingChannelSpan ??
+    (async <T>({ execute }: { execute: () => PromiseLike<T> }) =>
+      await execute());
 
-  logWarnings({
-    warnings: result.warnings,
+  const startEvent: GenerateSpeechStartEvent = {
+    callId,
+    operationId: 'ai.generateSpeech',
     provider: resolvedModel.provider,
-    model: resolvedModel.modelId,
-  });
+    modelId: resolvedModel.modelId,
+    text,
+    voice,
+    outputFormat,
+    instructions,
+    speed,
+    language,
+    maxRetries,
+    headers,
+    providerOptions,
+  };
 
-  const detectedMediaType = detectMediaType({
-    data: result.audio,
-    topLevelType: 'audio',
-  });
+  return await runInTracingChannelSpan({
+    type: 'generateSpeech',
+    event: startEvent,
+    execute: async () => {
+      await notify({
+        event: startEvent,
+        callbacks: [telemetryDispatcher.onStart],
+      });
+
+      try {
+        const result = await retry(() =>
+          resolvedModel.doGenerate({
+            text,
+            voice,
+            outputFormat,
+            instructions,
+            speed,
+            language,
+            abortSignal,
+            headers: headersWithUserAgent,
+            providerOptions,
+          }),
+        );
+
+        if (!result.audio || result.audio.length === 0) {
+          throw new NoSpeechGeneratedError({ responses: [result.response] });
+        }
 
-  return new DefaultSpeechResult({
-    audio: new DefaultGeneratedAudioFile({
-      data: result.audio,
-      mediaType:
-        detectedMediaType ??
-        getResponseAudioMediaType(result.response.headers) ??
-        getOutputFormatMediaType(outputFormat) ??
-        'audio/mp3',
-    }),
-    warnings: result.warnings,
-    responses: [result.response],
-    providerMetadata: result.providerMetadata,
+        logWarnings({
+          warnings: result.warnings,
+          provider: resolvedModel.provider,
+          model: resolvedModel.modelId,
+        });
+
+        const detectedMediaType = detectMediaType({
+          data: result.audio,
+          topLevelType: 'audio',
+        });
+
+        const audio = new DefaultGeneratedAudioFile({
+          data: result.audio,
+          mediaType:
+            detectedMediaType ??
+            getResponseAudioMediaType(result.response.headers) ??
+            getOutputFormatMediaType(outputFormat) ??
+            'audio/mp3',
+        });
+
+        if (telemetryDispatcher.onEnd != null) {
+          const endEvent: GenerateSpeechEndEvent = {
+            callId,
+            operationId: 'ai.generateSpeech',
+            provider: resolvedModel.provider,
+            modelId: resolvedModel.modelId,
+            text,
+            audio: {
+              byteLength: getBase64OrBinaryByteLength(result.audio),
+              mediaType: audio.mediaType,
+              format: audio.format,
+            },
+            usage: result.usage,
+            warnings: result.warnings,
+            providerMetadata: result.providerMetadata,
+            response: getTelemetryResponseMetadata(result.response),
+          };
+
+          await notify({
+            event: endEvent,
+            callbacks: [telemetryDispatcher.onEnd],
+          });
+        }
+
+        return new DefaultSpeechResult({
+          audio,
+          warnings: result.warnings,
+          responses: [result.response],
+          providerMetadata: result.providerMetadata,
+        });
+      } catch (error) {
+        await telemetryDispatcher.onError?.({ callId, error });
+        throw error;
+      }
+    },
   });
 }
 
+function getBase64OrBinaryByteLength(audio: string | Uint8Array): number {
+  if (audio instanceof Uint8Array) {
+    return audio.byteLength;
+  }
+
+  let characterCount = 0;
+  let lastCharacter = '';
+  let secondLastCharacter = '';
+  for (const character of audio) {
+    if (/\s/.test(character)) {
+      continue;
+    }
+    characterCount++;
+    secondLastCharacter = lastCharacter;
+    lastCharacter = character;
+  }
+
+  const padding =
+    lastCharacter === '=' ? (secondLastCharacter === '=' ? 2 : 1) : 0;
+  return Math.floor((characterCount * 3) / 4) - padding;
+}
+
+function getTelemetryResponseMetadata(
+  response: SpeechModelResponseMetadata,
+): SpeechModelResponseMetadata {
+  return {
+    timestamp: response.timestamp,
+    modelId: response.modelId,
+    headers: response.headers,
+  };
+}
+
 function getResponseAudioMediaType(
   headers: Record<string, string> | undefined,
 ): string | undefined {

package/src/generate-speech/index.ts

@@ -4,6 +4,10 @@ import { generateSpeech } from './generate-speech';
 export { generateSpeech } from './generate-speech';
 export type { SpeechResult } from './generate-speech-result';
 export type { GeneratedAudioFile } from './generated-audio-file';
+export type {
+  GenerateSpeechEndEvent,
+  GenerateSpeechStartEvent,
+} from './speech-events';
 
 // deprecated exports
 

package/src/generate-speech/speech-events.ts

@@ -0,0 +1,91 @@
+import type { JSONObject } from '@ai-sdk/provider';
+import type { ProviderOptions } from '@ai-sdk/provider-utils';
+import type { ProviderMetadata } from '../types';
+import type { SpeechModelResponseMetadata } from '../types/speech-model-response-metadata';
+import type { Warning } from '../types/warning';
+
+/**
+ * Event passed to telemetry integrations when speech generation begins.
+ */
+export type GenerateSpeechStartEvent = {
+  /** Unique identifier for this speech generation call. */
+  readonly callId: string;
+
+  /** Identifies the operation type (`ai.generateSpeech`). */
+  readonly operationId: 'ai.generateSpeech';
+
+  /** The provider identifier. */
+  readonly provider: string;
+
+  /** The specific model identifier. */
+  readonly modelId: string;
+
+  /** The text to convert to speech. */
+  readonly text: string;
+
+  /** The requested voice. */
+  readonly voice: string | undefined;
+
+  /** The requested output format. */
+  readonly outputFormat: string | undefined;
+
+  /** Additional speech instructions. */
+  readonly instructions: string | undefined;
+
+  /** The requested speech speed. */
+  readonly speed: number | undefined;
+
+  /** The requested language. */
+  readonly language: string | undefined;
+
+  /** Maximum number of retries for failed requests. */
+  readonly maxRetries: number;
+
+  /** Additional HTTP headers sent with the request. */
+  readonly headers: Record<string, string> | undefined;
+
+  /** Additional provider-specific options. */
+  readonly providerOptions: ProviderOptions;
+};
+
+/**
+ * Event passed to telemetry integrations when speech generation completes.
+ *
+ * Raw audio is intentionally not included. Integrations receive only its size,
+ * media type, and format.
+ */
+export type GenerateSpeechEndEvent = {
+  /** Unique identifier for this speech generation call. */
+  readonly callId: string;
+
+  /** Identifies the operation type (`ai.generateSpeech`). */
+  readonly operationId: 'ai.generateSpeech';
+
+  /** The provider identifier. */
+  readonly provider: string;
+
+  /** The specific model identifier. */
+  readonly modelId: string;
+
+  /** The text that was converted to speech. */
+  readonly text: string;
+
+  /** Metadata about the generated audio. */
+  readonly audio: {
+    readonly byteLength: number;
+    readonly mediaType: string;
+    readonly format: string;
+  };
+
+  /** Usage reported by the provider, when available. */
+  readonly usage: JSONObject | undefined;
+
+  /** Warnings from the speech model. */
+  readonly warnings: Array<Warning>;
+
+  /** Optional provider-specific metadata. */
+  readonly providerMetadata: ProviderMetadata | undefined;
+
+  /** Response metadata from the provider. */
+  readonly response: SpeechModelResponseMetadata;
+};