ai 7.0.91 → 7.0.93

package/docs/02-foundations/02-providers-and-models.mdx

@@ -122,6 +122,7 @@ Here are the capabilities of popular models:
 | [xAI Grok](/providers/ai-sdk-providers/xai)        | `grok-4`                                    | <Cross />   | <Check />         | <Check />  | <Check />      |
 | [xAI Grok](/providers/ai-sdk-providers/xai)        | `grok-3`                                    | <Cross />   | <Check />         | <Check />  | <Check />      |
 | [xAI Grok](/providers/ai-sdk-providers/xai)        | `grok-3-mini`                               | <Cross />   | <Check />         | <Check />  | <Check />      |
+| [OpenAI](/providers/ai-sdk-providers/openai)       | `gpt-6-astra`                               | <Check />   | <Check />         | <Check />  | <Check />      |
 | [OpenAI](/providers/ai-sdk-providers/openai)       | `gpt-5.6`                                   | <Check />   | <Check />         | <Check />  | <Check />      |
 | [OpenAI](/providers/ai-sdk-providers/openai)       | `gpt-5.6-luna`                              | <Check />   | <Check />         | <Check />  | <Check />      |
 | [OpenAI](/providers/ai-sdk-providers/openai)       | `gpt-5.6-sol`                               | <Check />   | <Check />         | <Check />  | <Check />      |

package/docs/03-agents/04-loop-control.mdx

@@ -16,7 +16,9 @@ The AI SDK provides built-in loop control through two parameters: `stopWhen` for
 
 ## Stop Conditions
 
-The `stopWhen` parameter controls when to stop execution when there are tool results in the last step. By default, agents stop after 20 steps using `isStepCount(20)`. This default is a safety measure to prevent runaway loops that could result in excessive API calls and costs.
+The `stopWhen` parameter controls when to stop execution when there are tool results in the last step. By default, `ToolLoopAgent` stops after 20 steps using `isStepCount(20)`. This default is a safety measure to prevent runaway loops that could result in excessive API calls and costs.
+
+`WorkflowAgent` does not apply a default step limit. It continues until the model stops calling tools or another natural termination condition is met. Configure an explicit condition such as `isStepCount(20)` when you need to bound its model calls. See [WorkflowAgent Loop Control](/docs/agents/workflow-agent#loop-control) for details.
 
 When you provide `stopWhen`, the agent continues executing after tool calls until a stopping condition is met. When the condition is an array, execution stops when any of the conditions are met.
 
@@ -39,7 +41,7 @@ const agent = new ToolLoopAgent({
   tools: {
     // your tools
   },
-  stopWhen: isStepCount(50), // Increasing the default of 20 to 50.
+  stopWhen: isStepCount(50), // Increase ToolLoopAgent's default from 20 to 50.
 });
 
 const result = await agent.generate({
@@ -49,7 +51,7 @@ const result = await agent.generate({
 
 ### Run Until Finished
 
-If you want the agent to run until the model naturally stops making tool calls, use `isLoopFinished()`. This removes the default step limit:
+If you want a `ToolLoopAgent` to run until the model naturally stops making tool calls, use `isLoopFinished()`. This removes its default step limit:
 
 ```ts
 import { ToolLoopAgent, isLoopFinished } from 'ai';

package/docs/03-agents/07-workflow-agent.mdx

@@ -399,6 +399,16 @@ The stream-level value overrides the constructor default.
 
 ## Loop Control
 
+Unlike `ToolLoopAgent`, `WorkflowAgent` does not apply a default step limit.
+When `stopWhen` is omitted, it continues until the model stops calling tools or
+another natural termination condition is met.
+
+<Note>
+  A model that repeatedly calls tools can make an unlimited number of model
+  calls. Configure an explicit stop condition when you need to bound execution
+  time and cost.
+</Note>
+
 Control how many steps the agent can take:
 
 ```ts
@@ -410,7 +420,8 @@ const result = await agent.stream({
 });
 ```
 
-If you want the agent to keep running until it has finished calling tools, you can also use `isLoopFinished()`:
+Omitting `stopWhen` already lets `WorkflowAgent` continue until it has finished
+calling tools. You can make that intent explicit with `isLoopFinished()`:
 
 ```ts
 import { isLoopFinished } from 'ai';
@@ -421,9 +432,10 @@ const result = await agent.stream({
 });
 ```
 
-`isLoopFinished()` lets the agent run until all tool calls have completed, but you should still pair it with `maxSteps` to avoid runaway loops. See https://ai-sdk.dev/v7/docs/reference/ai-sdk-core/loop-finished#isloopfinished.
-
-By default, the agent loops until the model stops calling tools (no maximum).
+`isLoopFinished()` is equivalent to omitting `stopWhen` for `WorkflowAgent`.
+Use it with caution because a model that keeps calling tools can run
+indefinitely and incur significant costs. See
+[`isLoopFinished()`](/docs/reference/ai-sdk-core/loop-finished).
 
 ## Structured Output
 
@@ -599,8 +611,11 @@ const agent = new WorkflowAgent({
     console.log(`Calling tool: ${toolCall.toolName}`);
   },
 
-  onToolExecutionEnd({ toolCall, toolOutput }) {
-    console.log(`Tool finished: ${toolCall.toolName}`);
+  onToolExecutionEnd({ toolCall, success, durationMs }) {
+    console.log(`Tool finished: ${toolCall.toolName}`, {
+      success,
+      durationMs,
+    });
   },
 
   onStepEnd({ usage, finishReason }) {
@@ -613,6 +628,12 @@ const agent = new WorkflowAgent({
 });
 ```
 
+For concrete tool sets, `WorkflowAgentToolExecutionStartEvent` and
+`WorkflowAgentToolExecutionEndEvent` preserve the relationship between each
+tool name and its input, context, and output types. TypeScript narrows the
+nested `toolCall` directly, but use `Extract` or a user-defined type guard when
+you need to narrow the correlated `toolContext` or `output` fields by tool name.
+
 Tool input callbacks (`onInputStart`, `onInputDelta`, and
 `onInputAvailable`) are also preserved by `WorkflowAgent`. The model call runs
 inside a durable step, while callback functions remain in the workflow

package/docs/03-ai-sdk-core/10-generating-structured-data.mdx

@@ -177,7 +177,9 @@ const { output } = await generateText({
 
 ### `Output.array()`
 
-Use `Output.array({ element })` to specify that you expect an array of typed objects from the model, where each element should conform to a schema (defined in the `element` property).
+Use `Output.array({ element, minItems, maxItems })` to specify that you expect
+an array of typed objects from the model. Each element must conform to the
+`element` schema, and the optional bounds constrain the number of elements.
 
 ```ts
 import { generateText, Output } from 'ai';
@@ -191,6 +193,8 @@ const { output } = await generateText({
       temperature: z.number(),
       condition: z.string(),
     }),
+    minItems: 2,
+    maxItems: 2,
   }),
   prompt: 'List the weather for San Francisco and Paris.',
 });
@@ -201,6 +205,11 @@ const { output } = await generateText({
 // ]
 ```
 
+`minItems` and `maxItems` must be non-negative integers, and `minItems` cannot
+be greater than `maxItems`. Use the same value for both options to require an
+exact length. The bounds are sent to providers as part of the structured output
+schema when supported, and the AI SDK independently validates the final output.
+
 When streaming arrays with `streamText`, you can use `elementStream` to receive each completed element as it is generated:
 
 ```ts
@@ -227,7 +236,10 @@ for await (const hero of elementStream) {
 <Note>
   Each element emitted by `elementStream` is complete and validated against your
   element schema. This differs from `partialOutputStream`, which streams the
-  entire partial array including incomplete elements.
+  entire partial array including incomplete elements. If the model generates
+  more than `maxItems`, `elementStream` errors before emitting the first excess
+  element. This does not automatically abort provider generation, and the final
+  `output` promise rejects.
 </Note>
 
 ### `Output.choice()`
@@ -378,7 +390,7 @@ const { output } = await generateText({
 This works with all output types that support structured generation:
 
 - `Output.object({ name, description, schema })`
-- `Output.array({ name, description, element })`
+- `Output.array({ name, description, element, minItems, maxItems })`
 - `Output.choice({ name, description, options })`
 - `Output.json({ name, description })`
 

package/docs/03-ai-sdk-core/16-mcp-tools.mdx

@@ -320,6 +320,67 @@ const tools = await mcpClient.tools();
 
 This approach is simpler to implement and automatically stays in sync with server changes. However, you won't have TypeScript type safety during development, and all tools from the server will be loaded
 
+### Tool Annotations and Approval
+
+MCP servers can describe tool behavior with annotations such as
+`readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint`. The
+MCP client exposes these annotations on each tool's `metadata.annotations` and
+on the resulting tool call's `toolMetadata.annotations`.
+
+Annotations are untrusted, server-provided hints. The MCP client does not turn
+them into an approval policy automatically. Applications should combine them
+with deterministic controls such as tool allowlists, scoped credentials, and
+their own [`toolApproval`](/docs/agents/tool-approvals) policy.
+
+The following conservative policy allows tools to run automatically only when
+the server explicitly marks them as read-only. Tools with `readOnlyHint: false`
+or no `readOnlyHint` require user approval:
+
+```typescript
+import { type McpProviderMetadata } from '@ai-sdk/mcp';
+
+const result = streamText({
+  model: __MODEL__,
+  tools,
+  toolApproval: ({ toolCall }) => {
+    const annotations = (
+      toolCall.toolMetadata as McpProviderMetadata | undefined
+    )?.annotations;
+
+    return annotations?.readOnlyHint === true
+      ? 'not-applicable'
+      : {
+          type: 'user-approval',
+          reason:
+            annotations?.destructiveHint === true
+              ? 'The MCP server marks this tool as destructive.'
+              : 'The MCP server does not mark this tool as read-only.',
+        };
+  },
+  prompt,
+});
+```
+
+See the
+[local tool annotations example](https://github.com/vercel/ai/tree/main/examples/mcp/src/tool-annotations)
+for a complete annotated MCP server and application-layer approval
+configuration. Start the server and client in separate terminals:
+
+```bash
+cd examples/mcp
+pnpm server:tool-annotations
+```
+
+```bash
+cd examples/mcp
+pnpm client:tool-annotations
+```
+
+Ask the client to read, delete, or create a note. The read-only tool executes
+immediately. The destructive and unannotated tools prompt for approval; after
+you enter `y` or `n`, the client sends the decision back and prints the model's
+response.
+
 ### Schema Definition
 
 For better type safety and control, you can define the tools and their input schemas explicitly in your client code:
@@ -347,7 +408,7 @@ This approach provides full TypeScript type safety and IDE autocompletion, letti
 
 ### Typed Tool Outputs
 
-When MCP servers return `structuredContent` (per the [MCP specification](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#structured-content)), you can define an `outputSchema` to get typed tool results:
+When MCP servers return `structuredContent` (per the [MCP specification](https://modelcontextprotocol.io/specification/2026-07-28/server/tools#structured-content)), you can define an `outputSchema` to get typed tool results:
 
 ```typescript
 import { z } from 'zod';
@@ -384,6 +445,8 @@ When `outputSchema` is provided:
 
 If the server doesn't return `structuredContent`, the client falls back to parsing JSON from the text content. If neither is available or validation fails, an error is thrown.
 
+If a server returns `structuredContent` without the backwards-compatible `content` field, the client adds a text content block containing the serialized JSON before returning the result. This compatibility behavior handles servers that omit the text mirror recommended by the MCP specification.
+
 <Note>
   Without `outputSchema`, the tool returns the raw `CallToolResult` object
   containing `content` and optional `isError` fields.

package/docs/03-ai-sdk-core/35-image-generation.mdx

@@ -230,6 +230,7 @@ This error occurs when the AI provider fails to generate an image. It can arise
 
 The error preserves the following information to help you log the issue:
 
+- `calls`: Results from the underlying image model calls, including generated images, provider metadata, response metadata, warnings, and usage.
 - `responses`: Metadata about the image model responses, including timestamp, model, and headers.
 - `cause`: The cause of the error. You can use this for more detailed error handling
 
@@ -243,6 +244,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/docs/03-ai-sdk-core/36-transcription.mdx

@@ -293,40 +293,41 @@ try {
 
 ## Transcription Models
 
-| Provider                                                                            | Model                    |
-| ----------------------------------------------------------------------------------- | ------------------------ |
-| [OpenAI](/providers/ai-sdk-providers/openai#transcription-models)                   | `whisper-1`              |
-| [OpenAI](/providers/ai-sdk-providers/openai#transcription-models)                   | `gpt-4o-transcribe`      |
-| [OpenAI](/providers/ai-sdk-providers/openai#transcription-models)                   | `gpt-4o-mini-transcribe` |
-| [ElevenLabs](/providers/ai-sdk-providers/elevenlabs#transcription-models)           | `scribe_v1`              |
-| [ElevenLabs](/providers/ai-sdk-providers/elevenlabs#transcription-models)           | `scribe_v1_experimental` |
-| [ElevenLabs](/providers/ai-sdk-providers/elevenlabs#transcription-models)           | `scribe_v2`              |
-| [ElevenLabs](/providers/ai-sdk-providers/elevenlabs#streaming-transcription-models) | `scribe_v2_realtime`     |
-| [Groq](/providers/ai-sdk-providers/groq#transcription-models)                       | `whisper-large-v3-turbo` |
-| [Groq](/providers/ai-sdk-providers/groq#transcription-models)                       | `whisper-large-v3`       |
-| [Mistral](/providers/ai-sdk-providers/mistral#transcription-models)                 | `voxtral-mini-latest`    |
-| [Azure OpenAI](/providers/ai-sdk-providers/azure#transcription-models)              | `whisper-1`              |
-| [Azure OpenAI](/providers/ai-sdk-providers/azure#transcription-models)              | `gpt-4o-transcribe`      |
-| [Azure OpenAI](/providers/ai-sdk-providers/azure#transcription-models)              | `gpt-4o-mini-transcribe` |
-| [Rev.ai](/providers/ai-sdk-providers/revai#transcription-models)                    | `machine`                |
-| [Rev.ai](/providers/ai-sdk-providers/revai#transcription-models)                    | `low_cost`               |
-| [Rev.ai](/providers/ai-sdk-providers/revai#transcription-models)                    | `fusion`                 |
-| [Deepgram](/providers/ai-sdk-providers/deepgram#transcription-models)               | `base` (+ variants)      |
-| [Deepgram](/providers/ai-sdk-providers/deepgram#transcription-models)               | `enhanced` (+ variants)  |
-| [Deepgram](/providers/ai-sdk-providers/deepgram#transcription-models)               | `nova` (+ variants)      |
-| [Deepgram](/providers/ai-sdk-providers/deepgram#transcription-models)               | `nova-2` (+ variants)    |
-| [Deepgram](/providers/ai-sdk-providers/deepgram#transcription-models)               | `nova-3` (+ variants)    |
-| [Gladia](/providers/ai-sdk-providers/gladia#transcription-models)                   | `default`                |
-| [AssemblyAI](/providers/ai-sdk-providers/assemblyai#transcription-models)           | `universal-3-5-pro`      |
-| [AssemblyAI](/providers/ai-sdk-providers/assemblyai#transcription-models)           | `universal-3-pro`        |
-| [Fal](/providers/ai-sdk-providers/fal#transcription-models)                         | `whisper`                |
-| [Fal](/providers/ai-sdk-providers/fal#transcription-models)                         | `wizper`                 |
-| [Google Vertex](/providers/ai-sdk-providers/google-vertex#transcription-models)     | `chirp_2`                |
-| [Google Vertex](/providers/ai-sdk-providers/google-vertex#transcription-models)     | `chirp_3`                |
-| [Google Vertex](/providers/ai-sdk-providers/google-vertex#transcription-models)     | `telephony`              |
-| [xAI](/providers/ai-sdk-providers/xai#transcription-models)                         | `default`                |
-| [Cartesia](/providers/ai-sdk-providers/cartesia#transcription-models)               | `ink-whisper`            |
-| [Cartesia](/providers/ai-sdk-providers/cartesia#streaming-transcription-models)     | `ink-2`                  |
-| [Fish Audio](/providers/ai-sdk-providers/fish-audio#transcription-models)           | `transcribe-1`           |
+| Provider                                                                            | Model                       |
+| ----------------------------------------------------------------------------------- | --------------------------- |
+| [OpenAI](/providers/ai-sdk-providers/openai#transcription-models)                   | `whisper-1`                 |
+| [OpenAI](/providers/ai-sdk-providers/openai#transcription-models)                   | `gpt-4o-transcribe`         |
+| [OpenAI](/providers/ai-sdk-providers/openai#transcription-models)                   | `gpt-4o-mini-transcribe`    |
+| [OpenAI](/providers/ai-sdk-providers/openai#transcription-models)                   | `gpt-4o-transcribe-diarize` |
+| [ElevenLabs](/providers/ai-sdk-providers/elevenlabs#transcription-models)           | `scribe_v1`                 |
+| [ElevenLabs](/providers/ai-sdk-providers/elevenlabs#transcription-models)           | `scribe_v1_experimental`    |
+| [ElevenLabs](/providers/ai-sdk-providers/elevenlabs#transcription-models)           | `scribe_v2`                 |
+| [ElevenLabs](/providers/ai-sdk-providers/elevenlabs#streaming-transcription-models) | `scribe_v2_realtime`        |
+| [Groq](/providers/ai-sdk-providers/groq#transcription-models)                       | `whisper-large-v3-turbo`    |
+| [Groq](/providers/ai-sdk-providers/groq#transcription-models)                       | `whisper-large-v3`          |
+| [Mistral](/providers/ai-sdk-providers/mistral#transcription-models)                 | `voxtral-mini-latest`       |
+| [Azure OpenAI](/providers/ai-sdk-providers/azure#transcription-models)              | `whisper-1`                 |
+| [Azure OpenAI](/providers/ai-sdk-providers/azure#transcription-models)              | `gpt-4o-transcribe`         |
+| [Azure OpenAI](/providers/ai-sdk-providers/azure#transcription-models)              | `gpt-4o-mini-transcribe`    |
+| [Rev.ai](/providers/ai-sdk-providers/revai#transcription-models)                    | `machine`                   |
+| [Rev.ai](/providers/ai-sdk-providers/revai#transcription-models)                    | `low_cost`                  |
+| [Rev.ai](/providers/ai-sdk-providers/revai#transcription-models)                    | `fusion`                    |
+| [Deepgram](/providers/ai-sdk-providers/deepgram#transcription-models)               | `base` (+ variants)         |
+| [Deepgram](/providers/ai-sdk-providers/deepgram#transcription-models)               | `enhanced` (+ variants)     |
+| [Deepgram](/providers/ai-sdk-providers/deepgram#transcription-models)               | `nova` (+ variants)         |
+| [Deepgram](/providers/ai-sdk-providers/deepgram#transcription-models)               | `nova-2` (+ variants)       |
+| [Deepgram](/providers/ai-sdk-providers/deepgram#transcription-models)               | `nova-3` (+ variants)       |
+| [Gladia](/providers/ai-sdk-providers/gladia#transcription-models)                   | `default`                   |
+| [AssemblyAI](/providers/ai-sdk-providers/assemblyai#transcription-models)           | `universal-3-5-pro`         |
+| [AssemblyAI](/providers/ai-sdk-providers/assemblyai#transcription-models)           | `universal-3-pro`           |
+| [Fal](/providers/ai-sdk-providers/fal#transcription-models)                         | `whisper`                   |
+| [Fal](/providers/ai-sdk-providers/fal#transcription-models)                         | `wizper`                    |
+| [Google Vertex](/providers/ai-sdk-providers/google-vertex#transcription-models)     | `chirp_2`                   |
+| [Google Vertex](/providers/ai-sdk-providers/google-vertex#transcription-models)     | `chirp_3`                   |
+| [Google Vertex](/providers/ai-sdk-providers/google-vertex#transcription-models)     | `telephony`                 |
+| [xAI](/providers/ai-sdk-providers/xai#transcription-models)                         | `default`                   |
+| [Cartesia](/providers/ai-sdk-providers/cartesia#transcription-models)               | `ink-whisper`               |
+| [Cartesia](/providers/ai-sdk-providers/cartesia#streaming-transcription-models)     | `ink-2`                     |
+| [Fish Audio](/providers/ai-sdk-providers/fish-audio#transcription-models)           | `transcribe-1`              |
 
 Above are a small subset of the transcription models supported by the AI SDK providers. For more, see the respective provider documentation.

package/docs/03-ai-sdk-harnesses/02-harness-agent.mdx

@@ -98,6 +98,39 @@ try {
 }
 ```
 
+## Lifecycle Callbacks
+
+Configure lifecycle callbacks on `HarnessAgent` to observe agent calls, model
+steps, and tool executions:
+
+```ts
+const agent = new HarnessAgent({
+  harness: claudeCode,
+  sandbox,
+  tools: { weather },
+  onStart: event => console.log('call started', event.callId),
+  onStepStart: event => console.log('step started', event.stepNumber),
+  onLanguageModelCallStart: event =>
+    console.log('model call started', event.modelId),
+  onLanguageModelCallEnd: event =>
+    console.log('model call ended', event.finishReason),
+  onToolExecutionStart: event =>
+    console.log('tool started', event.toolCall.toolName),
+  onToolExecutionEnd: event => console.log('tool ended', event.toolOutput.type),
+  onStepEnd: step => console.log('step ended', step.stepNumber),
+  onEnd: event => console.log('call ended', event.finishReason),
+});
+```
+
+Callbacks configured on individual `generate()` and `stream()` calls are
+invoked in addition to settings callbacks, with settings callbacks invoked
+first. Callback errors are ignored and do not change agent execution.
+
+Harness runtimes execute their built-in tools internally. For those tools,
+`onToolExecutionStart` and `onToolExecutionEnd` describe the logical tool
+lifecycle after the runtime reports the result. The callbacks are still
+delivered before the tool result is published to the result stream.
+
 ## Generate Structured Output
 
 Set `output` when constructing `HarnessAgent` to require the same typed output
@@ -510,6 +543,9 @@ console.log(preparation.identity);
 - `id`: optional stable agent identifier.
 - `instructions`: instructions appended to the runtime's system or developer
   prompt when supported, or prepended to the user prompt otherwise.
+- `headers`: additional headers sent with model requests. Headers are fixed at
+  construction time. `authorization`, `x-api-key`, `user-agent`, and
+  `x-client-app` are not allowed.
 - `callOptionsSchema` and `prepareCall`: validate custom call options and derive
   model, skills, instructions, and tools for each new turn.
 - `output`: typed output specification applied to every turn.

package/docs/04-ai-sdk-ui/20-streaming-data.mdx

@@ -63,14 +63,17 @@ export async function POST(req: Request) {
 
   const stream = createUIMessageStream<MyUIMessage>({
     execute: ({ writer }) => {
-      // 1. Send initial status (transient - won't be added to message history)
+      // 1. Start the assistant message before writing any message parts.
+      writer.write({ type: 'start' });
+
+      // 2. Send initial status (transient - won't be added to message history)
       writer.write({
         type: 'data-notification',
         data: { message: 'Processing your request...', level: 'info' },
         transient: true, // This part won't be added to message history
       });
 
-      // 2. Send sources (useful for RAG use cases)
+      // 3. Send sources (useful for RAG use cases)
       writer.write({
         type: 'source',
         value: {
@@ -82,7 +85,7 @@ export async function POST(req: Request) {
         },
       });
 
-      // 3. Send data parts with loading state
+      // 4. Send data parts with loading state
       writer.write({
         type: 'data-weather',
         id: 'weather-1',
@@ -93,7 +96,7 @@ export async function POST(req: Request) {
         model: __MODEL__,
         messages: await convertToModelMessages(messages),
         onEnd() {
-          // 4. Update the same data part (reconciliation)
+          // 5. Update the same data part (reconciliation)
           writer.write({
             type: 'data-weather',
             id: 'weather-1', // Same ID = update existing part
@@ -104,7 +107,7 @@ export async function POST(req: Request) {
             },
           });
 
-          // 5. Send completion notification (transient)
+          // 6. Send completion notification (transient)
           writer.write({
             type: 'data-notification',
             data: { message: 'Request completed', level: 'info' },
@@ -113,7 +116,9 @@ export async function POST(req: Request) {
         },
       });
 
-      writer.merge(toUIMessageStream({ stream: result.stream }));
+      writer.merge(
+        toUIMessageStream({ stream: result.stream, sendStart: false }),
+      );
     },
   });
 

package/docs/07-reference/01-ai-sdk-core/01-generate-text.mdx

@@ -996,6 +996,20 @@ To see `generateText` in action, check out [these examples](#examples).
                       description:
                         'The schema of the array elements to generate.',
                     },
+                    {
+                      name: 'minItems',
+                      type: 'number',
+                      isOptional: true,
+                      description:
+                        'Optional minimum number of array elements. Must be a non-negative integer.',
+                    },
+                    {
+                      name: 'maxItems',
+                      type: 'number',
+                      isOptional: true,
+                      description:
+                        'Optional maximum number of array elements. Must be a non-negative integer and greater than or equal to minItems.',
+                    },
                     {
                       name: 'name',
                       type: 'string',

package/docs/07-reference/01-ai-sdk-core/02-stream-text.mdx

@@ -1272,6 +1272,20 @@ To see `streamText` in action, check out [these examples](#examples).
                       description:
                         'The schema of the array elements to generate.',
                     },
+                    {
+                      name: 'minItems',
+                      type: 'number',
+                      isOptional: true,
+                      description:
+                        'Optional minimum number of array elements. Must be a non-negative integer.',
+                    },
+                    {
+                      name: 'maxItems',
+                      type: 'number',
+                      isOptional: true,
+                      description:
+                        'Optional maximum number of array elements. Must be a non-negative integer and greater than or equal to minItems.',
+                    },
                     {
                       name: 'name',
                       type: 'string',
@@ -2069,11 +2083,24 @@ To see `streamText` in action, check out [these examples](#examples).
         {
           type: 'OnAbortResult',
           parameters: [
+            {
+              name: 'callId',
+              type: 'string',
+              description:
+                'Unique identifier for this generation call, used to correlate events.',
+            },
             {
               name: 'steps',
               type: 'Array<StepResult>',
               description: 'Details for all previously finished steps.',
             },
+            {
+              name: 'reason',
+              type: 'unknown',
+              isOptional: true,
+              description:
+                'The raw abort reason from the AbortSignal, when one is available.',
+            },
           ],
         },
       ],
@@ -3979,10 +4006,10 @@ To see `streamText` in action, check out [these examples](#examples).
             },
             {
               name: 'reason',
-              type: 'unknown',
+              type: 'string',
               isOptional: true,
               description:
-                'Optional abort reason (from AbortSignal.reason) when the stream is aborted.',
+                'Optional serialized abort reason when the stream is aborted.',
             },
           ],
         },
@@ -4004,7 +4031,7 @@ To see `streamText` in action, check out [these examples](#examples).
       name: 'elementStream',
       type: 'AsyncIterableStream<ELEMENT_OUTPUT>',
       description:
-        'A stream of individual array elements as they complete. Only available when using `output: Output.array()`. Each element is complete and validated against the element schema. AsyncIterableStream is defined as AsyncIterable<T> & ReadableStream<T>.',
+        'A stream of individual array elements as they complete. Only available when using `output: Output.array()`. Each element is complete and validated against the element schema. When `maxItems` is set, the stream errors before emitting the first excess element. AsyncIterableStream is defined as AsyncIterable<T> & ReadableStream<T>.',
     },
     {
       name: 'output',

package/docs/07-reference/01-ai-sdk-core/28-output.mdx

@@ -135,6 +135,8 @@ const { output } = await generateText({
       temperature: z.number(),
       condition: z.string(),
     }),
+    minItems: 2,
+    maxItems: 2,
   }),
   prompt: 'List the weather for San Francisco and Paris.',
 });
@@ -151,6 +153,20 @@ const { output } = await generateText({
       description:
         'The schema that defines the structure of each array element. Supports Zod schemas, Valibot schemas, or JSON schemas.',
     },
+    {
+      name: 'minItems',
+      type: 'number',
+      isOptional: true,
+      description:
+        'The minimum number of elements to generate. Must be a non-negative integer.',
+    },
+    {
+      name: 'maxItems',
+      type: 'number',
+      isOptional: true,
+      description:
+        'The maximum number of elements to generate. Must be a non-negative integer and greater than or equal to minItems.',
+    },
     {
       name: 'name',
       type: 'string',
@@ -173,8 +189,15 @@ const { output } = await generateText({
 An `Output<Array<ELEMENT>, Array<ELEMENT>>` specification where:
 
 - Complete output is an array with all elements validated
+- Complete output is validated against `minItems` and `maxItems`
 - Partial output contains only fully validated elements (incomplete elements are excluded)
 
+Set `minItems` and `maxItems` to the same value to require an exact number of
+elements. The bounds are included in the provider-facing schema when the
+provider supports them. The AI SDK also validates the completed output, so
+providers that ignore these schema keywords cannot return an out-of-bounds
+result.
+
 #### Streaming with `elementStream`
 
 When using `streamText` with `Output.array()`, you can iterate over elements as they are generated using `elementStream`:
@@ -202,7 +225,10 @@ for await (const hero of elementStream) {
 
 <Note>
   Each element emitted by `elementStream` is complete and validated against your
-  element schema, ensuring type safety for each item as it is generated.
+  element schema, ensuring type safety for each item as it is generated. If the
+  model generates more than `maxItems`, `elementStream` errors before emitting
+  the first excess element. Provider generation is not aborted automatically,
+  and the final `output` promise also rejects.
 </Note>
 
 ---

package/docs/07-reference/01-ai-sdk-core/80-smooth-stream.mdx

@@ -38,7 +38,7 @@ const result = streamText({
       type: 'number | null',
       isOptional: true,
       description:
-        'The delay in milliseconds between outputting each chunk. Defaults to 10ms. Set to `null` to disable delays.',
+        'The delay in milliseconds between outputting each chunk. Defaults to 10ms. Set to `null` to disable delays. The delay is skipped while the document is hidden (e.g. browser background tabs), where timer throttling would otherwise stall the stream.',
     },
     {
       name: 'chunking',

package/docs/07-reference/02-ai-sdk-ui/01-use-chat.mdx

@@ -408,7 +408,7 @@ Allows you to easily create a conversational user interface for your chatbot app
       name: 'sendMessage',
       type: '(message?: { text: string; files?: FileList | FileUIPart[]; metadata?; messageId?: string } | CreateUIMessage, options?: ChatRequestOptions) => Promise<void>',
       description:
-        'Function to send a new message to the chat. This will trigger an API call to generate the assistant response. If a messageId is provided, the message will be replaced (useful for editing). If no message is provided, resubmits the current messages (useful after adding tool outputs).',
+        'Function to send a new message to the chat. This will trigger an API call to generate the assistant response. If a messageId is provided, the message will be replaced (useful for editing). When replacing with a CreateUIMessage, provide its id to assign a new ID to the replacement. If no message is provided, resubmits the current messages (useful after adding tool outputs).',
       properties: [
         {
           type: 'ChatRequestOptions',

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

@@ -20,6 +20,9 @@ const existingMessages: UIMessage[] = [
 
 const stream = createUIMessageStream({
   async execute({ writer }) {
+    // The outer stream owns the assistant message lifecycle.
+    writer.write({ type: 'start' });
+
     // Start a text message
     // Note: The id must be consistent across text-start, text-delta, and text-end steps
     // This allows the system to correctly identify they belong to the same text block
@@ -50,6 +53,7 @@ const stream = createUIMessageStream({
     writer.merge(
       toUIMessageStream({
         stream: result.stream,
+        sendStart: false,
         onEnd: ({ outcome }) => {
           // The composer decides that the model stream outcome is also the
           // aggregate stream outcome.