ai 7.0.91 → 7.0.93

package/docs/07-reference/02-ai-sdk-ui/41-create-ui-message-stream-response.mdx

@@ -33,6 +33,9 @@ const response = createUIMessageStreamResponse({
   },
   stream: createUIMessageStream({
     execute({ writer }) {
+      // The outer stream owns the assistant message lifecycle.
+      writer.write({ type: 'start' });
+
       // Write custom data (type must be 'data-<name>')
       writer.write({
         type: 'data-message',
@@ -68,7 +71,9 @@ const response = createUIMessageStreamResponse({
         prompt: 'Say hello',
       });
 
-      writer.merge(toUIMessageStream({ stream: result.stream }));
+      writer.merge(
+        toUIMessageStream({ stream: result.stream, sendStart: false }),
+      );
     },
   }),
 });

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

@@ -99,7 +99,7 @@ To see `WorkflowAgent` in action, check out [these examples](#examples).
       type: 'StopCondition | StopCondition[]',
       isOptional: true,
       description:
-        'Default stop condition for the agent loop. Per-stream values override this default. Use `isLoopFinished()` to let the agent run until all tool calls have completed, but beware of potential runaway loops. See https://ai-sdk.dev/v7/docs/reference/ai-sdk-core/loop-finished#isloopfinished.',
+        'Default stop condition for the agent loop. When omitted, WorkflowAgent has no maximum step count and continues until natural completion. Use `isStepCount()` to bound execution. Per-stream values override this default.',
     },
     {
       name: 'activeTools',
@@ -268,24 +268,24 @@ To see `WorkflowAgent` in action, check out [these examples](#examples).
     },
     {
       name: 'onToolExecutionStart',
-      type: 'WorkflowAgentonToolExecutionStartCallback',
+      type: 'WorkflowAgentOnToolExecutionStartCallback',
       isOptional: true,
       description:
         "Callback called right before a tool's execute function runs. If also specified in `stream()`, both callbacks fire (constructor first). Experimental (can break in patch releases).",
       properties: [
         {
-          type: 'ToolExecutionStartEvent',
+          type: 'WorkflowAgentToolExecutionStartEvent',
           parameters: [
             {
-              name: 'callId',
-              type: 'string',
+              name: 'toolCall',
+              type: '{ type: "tool-call"; toolCallId: string; toolName: string; input: unknown }',
               description:
-                'Unique identifier for this generation call, used to correlate events.',
+                'The tool call being executed. For concrete tool sets, the tool name and input are correlated.',
             },
             {
-              name: 'toolCall',
-              type: '{ type: "tool-call"; toolCallId: string; toolName: string; input: unknown }',
-              description: 'The tool call being executed.',
+              name: 'stepNumber',
+              type: 'number',
+              description: 'The current step number, starting at zero.',
             },
             {
               name: 'messages',
@@ -295,9 +295,9 @@ To see `WorkflowAgent` in action, check out [these examples](#examples).
             },
             {
               name: 'toolContext',
-              type: 'InferToolContext<TOOLS[toolName]>',
+              type: 'InferToolContext<TOOLS[NAME]> | undefined',
               description:
-                'Tool-specific context object for the tool call that is about to execute. Narrowed to the context type of the individual tool, not the entire tool set.',
+                'The validated context for the tool call. For concrete tool sets, each event union member pairs it with the corresponding tool name.',
             },
           ],
         },
@@ -305,24 +305,24 @@ To see `WorkflowAgent` in action, check out [these examples](#examples).
     },
     {
       name: 'onToolExecutionEnd',
-      type: 'WorkflowAgentonToolExecutionEndCallback',
+      type: 'WorkflowAgentOnToolExecutionEndCallback',
       isOptional: true,
       description:
-        "Callback called right after a tool's execute function completes or errors. The `toolOutput` field is a discriminated union: check `toolOutput.type` to determine whether the result is `'tool-result'` or `'tool-error'`. If also specified in `stream()`, both callbacks fire (constructor first). Experimental (can break in patch releases).",
+        "Callback called right after a tool's execute function completes or errors. Check `success` to determine whether `output` or `error` is available. If also specified in `stream()`, both callbacks fire (constructor first). Experimental (can break in patch releases).",
       properties: [
         {
-          type: 'ToolExecutionEndEvent',
+          type: 'WorkflowAgentToolExecutionEndEvent',
           parameters: [
             {
-              name: 'callId',
-              type: 'string',
+              name: 'toolCall',
+              type: '{ type: "tool-call"; toolCallId: string; toolName: string; input: unknown }',
               description:
-                'Unique identifier for this generation call, used to correlate events.',
+                'The tool call that was executed. For concrete tool sets, the tool name and input are correlated.',
             },
             {
-              name: 'toolCall',
-              type: '{ type: "tool-call"; toolCallId: string; toolName: string; input: unknown }',
-              description: 'The tool call that was executed.',
+              name: 'stepNumber',
+              type: 'number',
+              description: 'The current step number, starting at zero.',
             },
             {
               name: 'durationMs',
@@ -338,15 +338,29 @@ To see `WorkflowAgent` in action, check out [these examples](#examples).
             },
             {
               name: 'toolContext',
-              type: 'InferToolContext<TOOLS[toolName]>',
+              type: 'InferToolContext<TOOLS[NAME]> | undefined',
+              description:
+                'The validated context for the tool call. For concrete tool sets, each event union member pairs it with the corresponding tool name.',
+            },
+            {
+              name: 'success',
+              type: 'boolean',
+              description:
+                'Whether the tool execution succeeded. Discriminates between the output and error event variants.',
+            },
+            {
+              name: 'output',
+              type: 'InferToolOutput<TOOLS[NAME]>',
+              isOptional: true,
               description:
-                'Tool-specific context object for the tool call that just completed. Narrowed to the context type of the individual tool, not the entire tool set.',
+                'The tool output. Available when `success` is `true` and correlated with the configured tool.',
             },
             {
-              name: 'toolOutput',
-              type: 'ToolOutput<TOOLS>',
+              name: 'error',
+              type: 'unknown',
+              isOptional: true,
               description:
-                "Discriminated union representing the tool execution result. When `type` is `'tool-result'`, the `output` field contains the tool's return value. When `type` is `'tool-error'`, the `error` field contains the error.",
+                'The tool execution error. Available when `success` is `false`.',
             },
           ],
         },
@@ -509,7 +523,7 @@ const result = await agent.stream({
       name: 'stopWhen',
       type: 'StopCondition | StopCondition[]',
       isOptional: true,
-      description: 'Condition(s) for ending the agent loop. Use `isLoopFinished()` to let the agent run until all tool calls have completed, but beware of potential runaway loops. See https://ai-sdk.dev/v7/docs/reference/ai-sdk-core/loop-finished#isloopfinished.',
+      description: 'Condition(s) for ending the agent loop. When omitted and no constructor-level condition is configured, WorkflowAgent has no maximum step count and continues until natural completion. Use `isStepCount()` to bound execution.',
     },
 
     {
@@ -644,14 +658,14 @@ const result = await agent.stream({
     },
     {
       name: 'onToolExecutionStart',
-      type: 'WorkflowAgentonToolExecutionStartCallback',
+      type: 'WorkflowAgentOnToolExecutionStartCallback',
       isOptional: true,
       description:
         'Per-call onToolExecutionStart callback. If also specified in the constructor, both fire (constructor first).',
     },
     {
       name: 'onToolExecutionEnd',
-      type: 'WorkflowAgentonToolExecutionEndCallback',
+      type: 'WorkflowAgentOnToolExecutionEndCallback',
       isOptional: true,
       description:
         'Per-call onToolExecutionEnd callback. If also specified in the constructor, both fire (constructor first).',

package/docs/07-reference/05-ai-sdk-errors/ai-no-image-generated-error.mdx

@@ -14,6 +14,7 @@ It can arise due to the following reasons:
 ## Properties
 
 - `message`: The error message (optional, defaults to `'No image generated.'`).
+- `calls`: Results from the underlying image model calls, including generated images, provider metadata, response metadata, warnings, and usage (optional).
 - `responses`: Metadata about the image model responses, including timestamp, model, and headers (optional).
 - `cause`: The cause of the error. You can use this for more detailed error handling (optional).
 
@@ -31,6 +32,12 @@ try {
     console.log('NoImageGeneratedError');
     console.log('Cause:', error.cause);
     console.log('Responses:', error.responses);
+
+    for (const call of error.calls ?? []) {
+      console.log('Provider metadata:', call.providerMetadata);
+      console.log('Warnings:', call.warnings);
+      console.log('Usage:', call.usage);
+    }
   }
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai",
-  "version": "7.0.91",
+  "version": "7.0.93",
   "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,18 +42,18 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/gateway": "4.0.73",
+    "@ai-sdk/gateway": "4.0.75",
     "@ai-sdk/provider": "4.0.10",
     "@ai-sdk/provider-utils": "5.0.36"
   },
   "devDependencies": {
-    "@ai-sdk/amazon-bedrock": "5.0.73",
+    "@ai-sdk/amazon-bedrock": "5.0.75",
     "@ai-sdk/deepseek": "3.0.39",
-    "@ai-sdk/google": "4.0.63",
+    "@ai-sdk/google": "4.0.64",
     "@ai-sdk/groq": "4.0.37",
-    "@ai-sdk/huggingface": "2.0.43",
+    "@ai-sdk/huggingface": "2.0.44",
     "@ai-sdk/moonshotai": "3.0.45",
-    "@ai-sdk/openai": "4.0.57",
+    "@ai-sdk/openai": "4.0.59",
     "@ai-sdk/test-server": "2.0.1",
     "@ai-sdk/xai": "4.0.54",
     "@edge-runtime/vm": "^5.0.0",

package/src/agent/tool-loop-agent-settings.ts

@@ -17,6 +17,10 @@ import type {
   GenerateTextOnStepStartCallback,
 } from '../generate-text/generate-text-events';
 import type { GenerateTextInclude } from '../generate-text/generate-text';
+import type {
+  OnLanguageModelCallEndCallback,
+  OnLanguageModelCallStartCallback,
+} from '../generate-text/language-model-events';
 import type { Output } from '../generate-text/output';
 import type { PrepareStepFunction } from '../generate-text/prepare-step';
 import type { StopCondition } from '../generate-text/stop-condition';
@@ -212,6 +216,17 @@ export type ToolLoopAgentSettings<
       NoInfer<OUTPUT>
     >;
 
+    /**
+     * Callback that is called immediately before the provider model call begins.
+     */
+    onLanguageModelCallStart?: OnLanguageModelCallStartCallback;
+
+    /**
+     * Callback that is called after the model response has been normalized and parsed,
+     * but before any client-side tool execution begins.
+     */
+    onLanguageModelCallEnd?: OnLanguageModelCallEndCallback<NoInfer<TOOLS>>;
+
     /**
      * Callback that is called before each tool execution begins.
      */

package/src/embed/embed-many.ts

@@ -1,3 +1,4 @@
+import { InvalidResponseDataError } from '@ai-sdk/provider';
 import {
   createIdGenerator,
   withUserAgentSuffix,
@@ -264,6 +265,8 @@ export async function embedMany({
               };
             });
 
+          validateEmbeddingCount({ embeddings, values });
+
           logWarnings({
             warnings,
             provider: model.provider,
@@ -325,8 +328,8 @@ export async function embedMany({
 
         for (const parallelChunk of parallelChunks) {
           const results = await Promise.all(
-            parallelChunk.map(chunk => {
-              return retry(async () => {
+            parallelChunk.map(async chunk => {
+              const result = await retry(async () => {
                 const embedCallId = generateCallId();
 
                 await notify({
@@ -373,6 +376,13 @@ export async function embedMany({
                   response: modelResponse.response,
                 };
               });
+
+              validateEmbeddingCount({
+                embeddings: result.embeddings,
+                values: chunk,
+              });
+
+              return result;
             }),
           );
 
@@ -436,6 +446,21 @@ export async function embedMany({
   });
 }
 
+function validateEmbeddingCount({
+  embeddings,
+  values,
+}: {
+  embeddings: Array<Embedding>;
+  values: Array<string>;
+}) {
+  if (embeddings.length !== values.length) {
+    throw new InvalidResponseDataError({
+      data: embeddings,
+      message: `Expected ${values.length} embeddings, but received ${embeddings.length}.`,
+    });
+  }
+}
+
 const textEncoder = new TextEncoder();
 
 function splitByEmbeddingLimits({

package/src/error/no-image-generated-error.ts

@@ -1,4 +1,5 @@
 import { AISDKError } from '@ai-sdk/provider';
+import type { GenerateImageCall } from '../generate-image/generate-image-result';
 import type { ImageModelResponseMetadata } from '../types/image-model-response-metadata';
 
 const name = 'AI_NoImageGeneratedError';
@@ -14,6 +15,11 @@ const symbol = Symbol.for(marker);
 export class NoImageGeneratedError extends AISDKError {
   private readonly [symbol] = true; // used in isInstance
 
+  /**
+   * The results of the underlying image model calls.
+   */
+  readonly calls: Array<GenerateImageCall> | undefined;
+
   /**
    * The response metadata for each call.
    */
@@ -22,14 +28,17 @@ export class NoImageGeneratedError extends AISDKError {
   constructor({
     message = 'No image generated.',
     cause,
+    calls,
     responses,
   }: {
     message?: string;
     cause?: Error;
+    calls?: Array<GenerateImageCall>;
     responses?: Array<ImageModelResponseMetadata>;
   }) {
     super({ name, message, cause });
 
+    this.calls = calls;
     this.responses = responses;
   }
 

package/src/generate-image/generate-image.ts

@@ -295,7 +295,7 @@ export async function generateImage({
   logWarnings({ warnings, provider: model.provider, model: model.modelId });
 
   if (!images.length) {
-    throw new NoImageGeneratedError({ responses });
+    throw new NoImageGeneratedError({ calls, responses });
   }
 
   return new DefaultGenerateImageResult({

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

@@ -294,7 +294,7 @@ export type GenerateTextEndEvent<
 };
 
 /**
- * Event passed to the telemetry `onAbort` callback.
+ * Event passed to an `onAbort` callback for text generation.
  *
  * Called when a streaming text generation operation is aborted before it
  * completes.

package/src/generate-text/output.ts

@@ -11,6 +11,7 @@ import {
   safeValidateTypes,
   type FlexibleSchema,
 } from '@ai-sdk/provider-utils';
+import { InvalidArgumentError } from '../error/invalid-argument-error';
 import { NoObjectGeneratedError } from '../error/no-object-generated-error';
 import type { FinishReason } from '../types/language-model';
 import type { LanguageModelResponseMetadata } from '../types/language-model-response-metadata';
@@ -189,6 +190,8 @@ export const object = <OBJECT>({
  * When the model generates a text response, it will return an array of elements.
  *
  * @param element - The schema of the array elements to generate.
+ * @param minItems - Optional minimum number of elements to generate.
+ * @param maxItems - Optional maximum number of elements to generate.
  * @param name - Optional name of the output that should be generated. Used by some providers for additional LLM guidance, e.g. via tool or schema name.
  * @param description - Optional description of the output that should be generated. Used by some providers for additional LLM guidance, e.g. via tool or schema description.
  *
@@ -196,10 +199,20 @@ export const object = <OBJECT>({
  */
 export const array = <ELEMENT>({
   element: inputElementSchema,
+  minItems,
+  maxItems,
   name,
   description,
 }: {
   element: FlexibleSchema<ELEMENT>;
+  /**
+   * Optional minimum number of elements to generate.
+   */
+  minItems?: number;
+  /**
+   * Optional maximum number of elements to generate.
+   */
+  maxItems?: number;
   /**
    * Optional name of the output that should be generated.
    * Used by some providers for additional LLM guidance, e.g. via tool or schema name.
@@ -211,6 +224,17 @@ export const array = <ELEMENT>({
    */
   description?: string;
 }): Output<Array<ELEMENT>, Array<ELEMENT>, ELEMENT> => {
+  validateArrayBound({ name: 'minItems', value: minItems });
+  validateArrayBound({ name: 'maxItems', value: maxItems });
+
+  if (minItems != null && maxItems != null && minItems > maxItems) {
+    throw new InvalidArgumentError({
+      parameter: 'minItems',
+      value: minItems,
+      message: 'minItems must be less than or equal to maxItems',
+    });
+  }
+
   const elementSchema = asSchema(inputElementSchema);
 
   return {
@@ -236,7 +260,12 @@ export const array = <ELEMENT>({
           ...($defs != null && { $defs }),
           type: 'object',
           properties: {
-            elements: { type: 'array', items: itemSchema },
+            elements: {
+              type: 'array',
+              items: itemSchema,
+              ...(minItems != null && { minItems }),
+              ...(maxItems != null && { maxItems }),
+            },
           },
           required: ['elements'],
           additionalProperties: false,
@@ -288,6 +317,23 @@ export const array = <ELEMENT>({
         });
       }
 
+      const lengthValidationError = getArrayLengthValidationError({
+        value: outerValue.elements,
+        minItems,
+        maxItems,
+      });
+
+      if (lengthValidationError != null) {
+        throw new NoObjectGeneratedError({
+          message: 'No object generated: response did not match schema.',
+          cause: lengthValidationError,
+          text,
+          response: context.response,
+          usage: context.usage,
+          finishReason: context.finishReason,
+        });
+      }
+
       const validatedElements: Array<ELEMENT> = [];
       for (const element of outerValue.elements) {
         const validationResult = await safeValidateTypes({
@@ -372,6 +418,16 @@ export const array = <ELEMENT>({
               publishedElements < partialOutput.length;
               publishedElements++
             ) {
+              if (maxItems != null && publishedElements >= maxItems) {
+                controller.error(
+                  getArrayLengthValidationError({
+                    value: partialOutput,
+                    maxItems,
+                  }),
+                );
+                return;
+              }
+
               controller.enqueue(partialOutput[publishedElements]);
             }
           }
@@ -381,6 +437,60 @@ export const array = <ELEMENT>({
   };
 };
 
+function validateArrayBound({
+  name,
+  value,
+}: {
+  name: 'minItems' | 'maxItems';
+  value: number | undefined;
+}) {
+  if (value == null) {
+    return;
+  }
+
+  if (!Number.isInteger(value)) {
+    throw new InvalidArgumentError({
+      parameter: name,
+      value,
+      message: `${name} must be an integer`,
+    });
+  }
+
+  if (value < 0) {
+    throw new InvalidArgumentError({
+      parameter: name,
+      value,
+      message: `${name} must be greater than or equal to 0`,
+    });
+  }
+}
+
+function getArrayLengthValidationError({
+  value,
+  minItems,
+  maxItems,
+}: {
+  value: Array<unknown>;
+  minItems?: number;
+  maxItems?: number;
+}): TypeValidationError | undefined {
+  if (minItems != null && value.length < minItems) {
+    return new TypeValidationError({
+      value,
+      cause: `elements array must contain at least ${minItems} items`,
+    });
+  }
+
+  if (maxItems != null && value.length > maxItems) {
+    return new TypeValidationError({
+      value,
+      cause: `elements array must contain at most ${maxItems} items`,
+    });
+  }
+
+  return undefined;
+}
+
 /**
  * Output specification for choice generation.
  * When the model generates a text response, it will return a one of the choice options.

package/src/generate-text/smooth-stream.ts

@@ -10,6 +10,15 @@ const CHUNKING_REGEXPS = {
   line: /\n+/m,
 };
 
+// Browsers heavily throttle timers in hidden documents (e.g. background tabs),
+// which would stall the smoothing delay and, through backpressure, the entire
+// stream. Smoothing has no visual purpose there, so the delay is skipped.
+function isDocumentHidden(): boolean {
+  return (
+    typeof document !== 'undefined' && document.visibilityState === 'hidden'
+  );
+}
+
 /**
  * Detects the first chunk in a buffer.
  *
@@ -22,7 +31,7 @@ export type ChunkDetector = (buffer: string) => string | undefined | null;
 /**
  * Smooths text and reasoning streaming output.
  *
- * @param delayInMs - The delay in milliseconds between each chunk. Defaults to 10ms. Can be set to `null` to skip the delay.
+ * @param delayInMs - The delay in milliseconds between each chunk. Defaults to 10ms. Can be set to `null` to skip the delay. The delay is skipped while the document is hidden (e.g. browser background tabs), where timer throttling would otherwise stall the stream.
  * @param chunking - Controls how the text is chunked for streaming. Use "word" to stream word by word (default), "line" to stream line by line, provide a custom RegExp pattern that does not match the empty string for custom chunking, provide an Intl.Segmenter for locale-aware word segmentation (recommended for CJK languages), or provide a custom ChunkDetector function.
  *
  * @returns A transform stream that smooths text streaming output.
@@ -126,7 +135,10 @@ export function smoothStream<TOOLS extends ToolSet>({
     function flushBuffer(
       controller: TransformStreamDefaultController<TextStreamPart<TOOLS>>,
     ) {
-      if (buffer.length > 0 && type !== undefined) {
+      if (
+        type !== undefined &&
+        (buffer.length > 0 || providerMetadata != null)
+      ) {
         controller.enqueue({
           type,
           text: buffer,
@@ -148,7 +160,10 @@ export function smoothStream<TOOLS extends ToolSet>({
         }
 
         // Flush buffer when type or id changes
-        if ((chunk.type !== type || chunk.id !== id) && buffer.length > 0) {
+        if (
+          (chunk.type !== type || chunk.id !== id) &&
+          (buffer.length > 0 || providerMetadata != null)
+        ) {
           flushBuffer(controller);
         }
 
@@ -167,7 +182,7 @@ export function smoothStream<TOOLS extends ToolSet>({
           controller.enqueue({ type, text: match, id });
           buffer = buffer.slice(match.length);
 
-          await delay(delayInMs);
+          await delay(isDocumentHidden() ? null : delayInMs);
         }
       },
     });

package/src/generate-text/stream-text.ts

@@ -95,6 +95,7 @@ import {
   type ActiveToolSubset,
 } from './filter-active-tools';
 import type {
+  GenerateTextAbortEvent,
   GenerateTextEndEvent,
   GenerateTextOnStartCallback,
   GenerateTextOnStepEndCallback,
@@ -329,12 +330,7 @@ export type StreamTextOnEndCallback<
 export type StreamTextOnAbortCallback<
   TOOLS extends ToolSet,
   RUNTIME_CONTEXT extends Context,
-> = Callback<{
-  /**
-   * Details for all previously finished steps.
-   */
-  readonly steps: StepResult<TOOLS, RUNTIME_CONTEXT>[];
-}>;
+> = Callback<GenerateTextAbortEvent<TOOLS, RUNTIME_CONTEXT>>;
 
 /**
  * Generate a text and call tools for a given prompt using a language model.

package/src/ui/call-completion-api.ts

@@ -76,7 +76,7 @@ export async function callCompletionApi({
 
     if (!response.ok) {
       throw new Error(
-        (await response.text()) ?? 'Failed to fetch the chat response.',
+        (await response.text()) || 'Failed to fetch the chat response.',
       );
     }
 

package/src/ui/chat.ts

@@ -420,8 +420,8 @@ export abstract class AbstractChat<UI_MESSAGE extends UIMessage> {
 
       // update the message with the new content
       this.state.replaceMessage(messageIndex, {
-        ...uiMessage,
         id: message.messageId,
+        ...uiMessage,
         role: uiMessage.role ?? 'user',
         metadata: message.metadata,
       } as UI_MESSAGE);

package/src/ui/convert-to-model-messages.ts

@@ -212,6 +212,12 @@ export async function convertToModelMessages<UI_MESSAGE extends UIMessage>(
                 const toolName = getToolName(part);
 
                 if (part.state !== 'input-streaming') {
+                  const callProviderMetadata =
+                    part.callProviderMetadata ??
+                    (part.state === 'output-error'
+                      ? part.resultProviderMetadata
+                      : undefined);
+
                   content.push({
                     type: 'tool-call' as const,
                     toolCallId: part.toolCallId,
@@ -222,8 +228,8 @@ export async function convertToModelMessages<UI_MESSAGE extends UIMessage>(
                           ('rawInput' in part ? part.rawInput : undefined))
                         : part.input,
                     providerExecuted: part.providerExecuted,
-                    ...(part.callProviderMetadata != null
-                      ? { providerOptions: part.callProviderMetadata }
+                    ...(callProviderMetadata != null
+                      ? { providerOptions: callProviderMetadata }
                       : {}),
                   });