ai 7.0.99 → 7.0.100

package/docs/02-getting-started/07-expo.mdx

@@ -103,6 +103,13 @@ Let's take a look at what is happening in this code:
 
 This API route creates a POST request endpoint at `/api/chat`.
 
+<Note>
+  If a deployed Expo API Route buffers the response despite the streaming
+  headers above, test the same handler without the deployment adapter to isolate
+  the cause. As a workaround, host the chat endpoint in a separate Vercel
+  Function and set `EXPO_PUBLIC_API_BASE_URL` to that function's base URL.
+</Note>
+
 ## Choosing a Provider
 
 The AI SDK supports dozens of model providers through [first-party](/providers/ai-sdk-providers), [OpenAI-compatible](/providers/openai-compatible-providers), and [ community ](/providers/community-providers) packages.

package/docs/03-ai-sdk-core/55-testing.mdx

@@ -179,6 +179,81 @@ const result = streamText({
 });
 ```
 
+### ToolLoopAgent
+
+You can provide a sequence of mock responses to test an agent that calls a tool
+and continues to a final response:
+
+```ts
+import { ToolLoopAgent, tool } from 'ai';
+import { MockLanguageModelV4 } from 'ai/test';
+import { expect, it } from 'vitest';
+import { z } from 'zod';
+
+it('executes a tool and continues the loop', async () => {
+  const weatherRequests: string[] = [];
+  const usage = {
+    inputTokens: {
+      total: 10,
+      noCache: 10,
+      cacheRead: undefined,
+      cacheWrite: undefined,
+    },
+    outputTokens: {
+      total: 5,
+      text: 5,
+      reasoning: undefined,
+    },
+  };
+
+  const model = new MockLanguageModelV4({
+    doGenerate: [
+      {
+        content: [
+          {
+            type: 'tool-call',
+            toolCallId: 'call-1',
+            toolName: 'weather',
+            input: '{"city":"San Francisco"}',
+          },
+        ],
+        finishReason: { unified: 'tool-calls', raw: undefined },
+        usage,
+        warnings: [],
+      },
+      {
+        content: [{ type: 'text', text: 'It is 72°F in San Francisco.' }],
+        finishReason: { unified: 'stop', raw: undefined },
+        usage,
+        warnings: [],
+      },
+    ],
+  });
+
+  const agent = new ToolLoopAgent({
+    model,
+    tools: {
+      weather: tool({
+        description: 'Get the weather for a city.',
+        inputSchema: z.object({ city: z.string() }),
+        execute: async ({ city }) => {
+          weatherRequests.push(city);
+          return { temperature: 72 };
+        },
+      }),
+    },
+  });
+
+  const result = await agent.generate({
+    prompt: 'What is the weather in San Francisco?',
+  });
+
+  expect(weatherRequests).toEqual(['San Francisco']);
+  expect(result.text).toBe('It is 72°F in San Francisco.');
+  expect(model.doGenerateCalls).toHaveLength(2);
+});
+```
+
 ### Simulate UI Message Stream Responses
 
 You can also simulate [UI Message Stream](/docs/ai-sdk-ui/stream-protocol#ui-message-stream-example) responses for testing,

package/docs/04-ai-sdk-ui/21-error-handling.mdx

@@ -169,8 +169,23 @@ export default function Chat() {
 Errors can be processed by passing an [`onError`](/docs/reference/ai-sdk-ui/use-chat#on-error) callback function as an option to the [`useChat`](/docs/reference/ai-sdk-ui/use-chat) or [`useCompletion`](/docs/reference/ai-sdk-ui/use-completion) hooks.
 The callback function receives an error object as an argument.
 
-```tsx file="app/page.tsx" highlight="6-9"
+AI SDK-created client errors use exported error classes with marker-based
+`.isInstance()` guards:
+
+| Error class                                                                                         | AI SDK UI failure                                                                         |
+| --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| [`APICallError`](/docs/reference/ai-sdk-errors/ai-api-call-error)                                   | A chat transport or completion request returns a non-successful HTTP response.            |
+| [`EmptyResponseBodyError`](/docs/reference/ai-sdk-errors/ai-empty-response-body-error)              | A successful chat transport or completion response has no body.                           |
+| [`UIMessageStreamError`](/docs/reference/ai-sdk-errors/ai-ui-message-stream-error)                  | A completion data stream reports an error or a UI message stream contains invalid chunks. |
+| [`InvalidArgumentError`](/docs/reference/ai-sdk-errors/ai-invalid-argument-error)                   | An invalid stream protocol or message ID is used.                                         |
+| [`UnsupportedFunctionalityError`](/docs/reference/ai-sdk-errors/ai-unsupported-functionality-error) | A `FileList` is used in an environment that does not support it.                          |
+
+Errors thrown by custom fetch implementations, callbacks, and stream parsers
+continue to propagate unchanged.
+
+```tsx file="app/page.tsx" highlight="2,9-15"
 import { useChat } from '@ai-sdk/react';
+import { APICallError, EmptyResponseBodyError } from 'ai';
 
 export default function Page() {
   const {
@@ -178,12 +193,23 @@ export default function Page() {
   } = useChat({
     // handle error:
     onError: error => {
-      console.error(error);
+      if (APICallError.isInstance(error)) {
+        console.error('Request failed with status:', error.statusCode);
+      } else if (EmptyResponseBodyError.isInstance(error)) {
+        console.error('The server returned no response body.');
+      } else {
+        console.error(error);
+      }
     },
   });
 }
 ```
 
+For AI SDK UI requests, `APICallError.requestBodyValues` is `undefined` so
+prompts and messages are not copied into client-facing error objects. The
+response text remains available as `message` and `responseBody`; display a
+generic message to users to avoid leaking server information.
+
 ### Injecting Errors for Testing
 
 You might want to create errors for testing.

package/docs/07-reference/05-ai-sdk-errors/ai-api-call-error.mdx

@@ -18,6 +18,10 @@ This error occurs when an API call fails.
 - `data`: Any additional data associated with the error (optional)
 - `cause`: The underlying error that caused the API call to fail (optional)
 
+When this error is created for an AI SDK UI chat transport or completion
+request, `requestBodyValues` is `undefined` so prompts and messages are not
+copied into the client-facing error object.
+
 ## Checking for this Error
 
 You can check if an error is an instance of `AI_APICallError` using:

package/docs/07-reference/05-ai-sdk-errors/ai-ui-message-stream-error.mdx

@@ -5,10 +5,12 @@ description: Learn how to fix AI_UIMessageStreamError
 
 # AI_UIMessageStreamError
 
-This error occurs when a UI message stream contains invalid or out-of-sequence chunks.
+This error occurs when a UI message stream reports an error or contains invalid
+or out-of-sequence chunks.
 
 Common causes:
 
+- Receiving an `error` chunk in a completion data stream
 - Receiving a `text-delta` chunk without a preceding `text-start` chunk
 - Receiving a `text-end` chunk without a preceding `text-start` chunk
 - Receiving a `reasoning-delta` chunk without a preceding `reasoning-start` chunk
@@ -21,7 +23,9 @@ This error often surfaces when an upstream request fails **before any tokens are
 ## Properties
 
 - `chunkType`: The type of chunk that caused the error (e.g., `text-delta`, `reasoning-end`, `tool-input-delta`)
-- `chunkId`: The ID associated with the failing chunk (part ID or toolCallId)
+- `chunkId`: The ID associated with the failing chunk (part ID or toolCallId).
+  This is an empty string for chunks, such as completion `error` chunks, that do
+  not have an ID.
 - `message`: The error message with details about what went wrong
 
 ## Checking for this Error

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai",
-  "version": "7.0.99",
+  "version": "7.0.100",
   "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,7 +42,7 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/gateway": "4.0.80",
+    "@ai-sdk/gateway": "4.0.81",
     "@ai-sdk/provider": "4.0.14",
     "@ai-sdk/provider-utils": "5.0.40"
   },

package/src/error/ui-message-stream-error.ts

@@ -5,9 +5,11 @@ const marker = `vercel.ai.error.${name}`;
 const symbol = Symbol.for(marker);
 
 /**
- * Error thrown when a UI message stream contains invalid or out-of-sequence chunks.
+ * Error thrown when a UI message stream reports an error or contains invalid
+ * or out-of-sequence chunks.
  *
  * This typically occurs when:
+ * - An error chunk is received
  * - A delta chunk is received without a corresponding start chunk
  * - An end chunk is received without a corresponding start chunk
  * - A tool invocation is not found for the given toolCallId
@@ -23,7 +25,8 @@ export class UIMessageStreamError extends AISDKError {
   readonly chunkType: string;
 
   /**
-   * The ID associated with the failing chunk (part ID or toolCallId).
+   * The ID associated with the failing chunk (part ID or toolCallId), or an
+   * empty string when the chunk does not have an ID.
    */
   readonly chunkId: string;
 

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

@@ -4,11 +4,15 @@ import {
   getRuntimeEnvironmentUserAgent,
   type ParseResult,
 } from '@ai-sdk/provider-utils';
+import { EmptyResponseBodyError } from '@ai-sdk/provider';
+import { InvalidArgumentError } from '../error/invalid-argument-error';
+import { UIMessageStreamError } from '../error/ui-message-stream-error';
 import {
   uiMessageChunkSchema,
   type UIMessageChunk,
 } from '../ui-message-stream/ui-message-chunks';
 import { consumeStream } from '../util/consume-stream';
+import { createUIApiCallError } from './create-ui-api-call-error';
 import { processTextStream } from './process-text-stream';
 import { VERSION } from '../version';
 
@@ -75,13 +79,17 @@ export async function callCompletionApi({
     });
 
     if (!response.ok) {
-      throw new Error(
-        (await response.text()) || 'Failed to fetch the chat response.',
-      );
+      throw await createUIApiCallError({
+        response,
+        url: api,
+        fallbackMessage: 'Failed to fetch the chat response.',
+      });
     }
 
     if (!response.body) {
-      throw new Error('The response body is empty.');
+      throw new EmptyResponseBodyError({
+        message: 'The response body is empty.',
+      });
     }
 
     let result = '';
@@ -114,7 +122,11 @@ export async function callCompletionApi({
                   result += streamPart.delta;
                   setCompletion(result);
                 } else if (streamPart.type === 'error') {
-                  throw new Error(streamPart.errorText);
+                  throw new UIMessageStreamError({
+                    chunkType: 'error',
+                    chunkId: '',
+                    message: streamPart.errorText,
+                  });
                 }
               },
             }),
@@ -127,7 +139,11 @@ export async function callCompletionApi({
       }
       default: {
         const exhaustiveCheck: never = streamProtocol;
-        throw new Error(`Unknown stream protocol: ${exhaustiveCheck}`);
+        throw new InvalidArgumentError({
+          parameter: 'streamProtocol',
+          value: exhaustiveCheck,
+          message: `Unknown stream protocol: ${exhaustiveCheck}`,
+        });
       }
     }
 

package/src/ui/chat.ts

@@ -4,6 +4,7 @@ import {
   type IdGenerator,
   type InferSchema,
 } from '@ai-sdk/provider-utils';
+import { InvalidArgumentError } from '../error/invalid-argument-error';
 import type { FinishReason } from '../types/language-model';
 import type { UIMessageChunk } from '../ui-message-stream/ui-message-chunks';
 import { consumeStream } from '../util/consume-stream';
@@ -406,13 +407,19 @@ export abstract class AbstractChat<UI_MESSAGE extends UIMessage> {
       );
 
       if (messageIndex === -1) {
-        throw new Error(`message with id ${message.messageId} not found`);
+        throw new InvalidArgumentError({
+          parameter: 'message.messageId',
+          value: message.messageId,
+          message: `message with id ${message.messageId} not found`,
+        });
       }
 
       if (this.state.messages[messageIndex].role !== 'user') {
-        throw new Error(
-          `message with id ${message.messageId} is not a user message`,
-        );
+        throw new InvalidArgumentError({
+          parameter: 'message.messageId',
+          value: message.messageId,
+          message: `message with id ${message.messageId} is not a user message`,
+        });
       }
 
       // remove all messages after the message with the given id
@@ -457,7 +464,11 @@ export abstract class AbstractChat<UI_MESSAGE extends UIMessage> {
         : this.state.messages.findIndex(message => message.id === messageId);
 
     if (messageIndex === -1) {
-      throw new Error(`message ${messageId} not found`);
+      throw new InvalidArgumentError({
+        parameter: 'messageId',
+        value: messageId,
+        message: `message ${messageId} not found`,
+      });
     }
 
     // set the messages to the message before the assistant message

package/src/ui/convert-file-list-to-file-ui-parts.ts

@@ -1,3 +1,4 @@
+import { UnsupportedFunctionalityError } from '@ai-sdk/provider';
 import type { FileUIPart } from './ui-messages';
 
 export async function convertFileListToFileUIParts(
@@ -9,7 +10,10 @@ export async function convertFileListToFileUIParts(
 
   // React-native doesn't have a FileList global:
   if (!globalThis.FileList || !(files instanceof globalThis.FileList)) {
-    throw new Error('FileList is not supported in the current environment');
+    throw new UnsupportedFunctionalityError({
+      functionality: 'FileList',
+      message: 'FileList is not supported in the current environment',
+    });
   }
 
   return Promise.all(

package/src/ui/create-ui-api-call-error.ts

@@ -0,0 +1,23 @@
+import { APICallError } from '@ai-sdk/provider';
+
+export async function createUIApiCallError({
+  response,
+  url,
+  fallbackMessage,
+}: {
+  response: Response;
+  url: string;
+  fallbackMessage: string;
+}) {
+  const responseBody = await response.text();
+
+  return new APICallError({
+    message: responseBody || fallbackMessage,
+    url,
+    // UI requests can contain prompts, messages, and other sensitive values.
+    // Keep them out of client-facing error objects.
+    requestBodyValues: undefined,
+    statusCode: response.status,
+    responseBody,
+  });
+}

package/src/ui/http-chat-transport.ts

@@ -4,8 +4,10 @@ import {
   type FetchFunction,
   type Resolvable,
 } from '@ai-sdk/provider-utils';
+import { EmptyResponseBodyError } from '@ai-sdk/provider';
 import type { UIMessageChunk } from '../ui-message-stream/ui-message-chunks';
 import type { ChatTransport } from './chat-transport';
+import { createUIApiCallError } from './create-ui-api-call-error';
 import type { UIMessage } from './ui-messages';
 
 export type PrepareSendMessagesRequest<UI_MESSAGE extends UIMessage> = (
@@ -200,13 +202,17 @@ export abstract class HttpChatTransport<
     });
 
     if (!response.ok) {
-      throw new Error(
-        (await response.text()) || 'Failed to fetch the chat response.',
-      );
+      throw await createUIApiCallError({
+        response,
+        url: api,
+        fallbackMessage: 'Failed to fetch the chat response.',
+      });
     }
 
     if (!response.body) {
-      throw new Error('The response body is empty.');
+      throw new EmptyResponseBodyError({
+        message: 'The response body is empty.',
+      });
     }
 
     return this.processResponseStream(response.body);
@@ -256,13 +262,17 @@ export abstract class HttpChatTransport<
     }
 
     if (!response.ok) {
-      throw new Error(
-        (await response.text()) || 'Failed to fetch the chat response.',
-      );
+      throw await createUIApiCallError({
+        response,
+        url: api,
+        fallbackMessage: 'Failed to fetch the chat response.',
+      });
     }
 
     if (!response.body) {
-      throw new Error('The response body is empty.');
+      throw new EmptyResponseBodyError({
+        message: 'The response body is empty.',
+      });
     }
 
     return this.processResponseStream(response.body);