ai 6.0.270 → 6.0.272

package/dist/internal/index.js

@@ -164,7 +164,7 @@ function detectMediaType({
 var import_provider_utils2 = require("@ai-sdk/provider-utils");
 
 // src/version.ts
-var VERSION = true ? "6.0.270" : "0.0.0-test";
+var VERSION = true ? "6.0.272" : "0.0.0-test";
 
 // src/util/download/download.ts
 var download = async ({

package/dist/internal/index.mjs

@@ -144,7 +144,7 @@ import {
 } from "@ai-sdk/provider-utils";
 
 // src/version.ts
-var VERSION = true ? "6.0.270" : "0.0.0-test";
+var VERSION = true ? "6.0.272" : "0.0.0-test";
 
 // src/util/download/download.ts
 var download = async ({

package/docs/03-ai-sdk-core/15-tools-and-tool-calling.mdx

@@ -218,6 +218,30 @@ const paymentTool = tool({
 
 In this example, only transactions over $1000 require approval. Smaller transactions execute automatically.
 
+### Securing Approval Requests
+
+When your application rebuilds a conversation from client-provided messages, a
+client could forge an approval response. For tools that perform sensitive
+operations, set `experimental_toolApprovalSecret` to cryptographically bind
+each approval to the server that issued it:
+
+```ts highlight="7"
+import { ToolLoopAgent } from 'ai';
+
+const agent = new ToolLoopAgent({
+  model: __MODEL__,
+  tools: { runCommand },
+  experimental_toolApprovalSecret: process.env.TOOL_APPROVAL_SECRET,
+});
+
+const result = await agent.generate({ messages });
+```
+
+The server HMAC-signs each approval request and verifies the signature when an
+approval is replayed. A forged or tampered approval is rejected before the tool
+executes. Keep the secret on the server and use the same value on every
+instance that can handle a later approval response.
+
 ### Tool Execution Approval with useChat
 
 When using `useChat`, the approval flow is handled through UI state. See [Chatbot Tool Usage](/docs/ai-sdk-ui/chatbot-tool-usage#tool-execution-approval) for details on handling approvals in your UI with `addToolApprovalResponse`.
@@ -811,11 +835,12 @@ async function generateSomething(prompt: string): Promise<{
 
 ## Handling Errors
 
-The AI SDK has three tool-call related errors:
+The AI SDK has four tool-call related errors:
 
 - [`NoSuchToolError`](/docs/reference/ai-sdk-errors/ai-no-such-tool-error): the model tries to call a tool that is not defined in the tools object
 - [`InvalidToolInputError`](/docs/reference/ai-sdk-errors/ai-invalid-tool-input-error): the model calls a tool with inputs that do not match the tool's input schema
 - [`ToolCallRepairError`](/docs/reference/ai-sdk-errors/ai-tool-call-repair-error): an error that occurred during tool call repair
+- [`ToolChoiceViolationError`](/docs/reference/ai-sdk-errors/ai-tool-choice-violation-error): the model response does not satisfy a required or specifically selected tool choice
 
 When tool execution fails (errors thrown by your tool's `execute` function), the AI SDK adds them as `tool-error` content parts to enable automated LLM roundtrips in multi-step scenarios.
 

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

@@ -3509,9 +3509,9 @@ To see `streamText` in action, check out [these examples](#examples).
             },
             {
               name: 'onFinish',
-              type: '(options: { messages: UIMessage[]; isContinuation: boolean; responseMessage: UIMessage; isAborted: boolean; }) => void',
+              type: '(options: { messages: UIMessage[]; isContinuation: boolean; responseMessage: UIMessage; isAborted: boolean; outcome: UIMessageStreamOutcome; finishReason?: FinishReason; }) => PromiseLike<void> | void',
               isOptional: true,
-              description: 'Callback function called when the stream finishes. Provides the updated list of UI messages, whether the response is a continuation, the response message, and whether the stream was aborted.',
+              description: 'Callback function called when the stream finishes. Provides the updated messages, continuation and abort state, model finish reason, and operation-level outcome.',
             },
             {
               name: 'messageMetadata',

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

@@ -47,16 +47,32 @@ const stream = createUIMessageStream({
       prompt: 'Write a haiku about AI',
     });
 
-    writer.merge(result.toUIMessageStream());
+    writer.merge(
+      result.toUIMessageStream({
+        onFinish: ({ outcome }) => {
+          // The composer decides that the model stream outcome is also the
+          // aggregate stream outcome.
+          writer.setOutcome(outcome);
+        },
+      }),
+    );
   },
   onError: error => `Custom error: ${error.message}`,
   originalMessages: existingMessages,
-  onFinish: ({ messages, isContinuation, responseMessage }) => {
+  onFinish: ({ messages, isContinuation, outcome, responseMessage }) => {
     console.log('Stream finished with messages:', messages);
+    console.log('Stream outcome:', outcome.status);
   },
 });
 ```
 
+`setOutcome` records the composer's policy without writing a chunk or closing
+the stream. The first outcome declared through `setOutcome` is retained, but a
+fatal execution, merge, error-handling, or downstream processing failure makes
+the final `onFinish` outcome `failed`. Individual `error` chunks do not change the
+outcome by themselves. When merging multiple child streams, aggregate their
+outcomes and call `setOutcome` once.
+
 ## API Signature
 
 ### Parameters
@@ -65,12 +81,12 @@ const stream = createUIMessageStream({
   content={[
     {
       name: 'execute',
-      type: '(options: { writer: UIMessageStreamWriter }) => Promise<void> | void',
+      type: '(options: { writer: UIMessageStreamWriterWithOutcome }) => Promise<void> | void',
       description:
         'A function that receives a writer instance and can use it to write UI message chunks to the stream.',
       properties: [
         {
-          type: 'UIMessageStreamWriter',
+          type: 'UIMessageStreamWriterWithOutcome',
           parameters: [
             {
               name: 'write',
@@ -83,6 +99,12 @@ const stream = createUIMessageStream({
               description:
                 'Merges the contents of another UI message stream into this stream.',
             },
+            {
+              name: 'setOutcome',
+              type: '(outcome: UIMessageStreamOutcome) => void',
+              description:
+                "Declares the operation-level outcome of the composed stream. The first outcome declared through this method is retained, while fatal execution, merge, error-handling, or downstream processing failures override declarations. Supported statuses are 'completed', 'failed', 'aborted', and 'unknown'. Declaring an outcome does not write a chunk or close the stream.",
+            },
             {
               name: 'onError',
               type: '(error: unknown) => string',
@@ -107,7 +129,7 @@ const stream = createUIMessageStream({
     },
     {
       name: 'onFinish',
-      type: '(options: { messages: UIMessage[]; isContinuation: boolean; isAborted: boolean; responseMessage: UIMessage; finishReason?: FinishReason }) => PromiseLike<void> | void',
+      type: '(options: { messages: UIMessage[]; isContinuation: boolean; isAborted: boolean; outcome: UIMessageStreamOutcome; responseMessage: UIMessage; finishReason?: FinishReason }) => PromiseLike<void> | void',
       description:
         'A callback function that is called when the stream finishes.',
       properties: [
@@ -130,6 +152,12 @@ const stream = createUIMessageStream({
               type: 'boolean',
               description: 'Indicates whether the stream was aborted.',
             },
+            {
+              name: 'outcome',
+              type: "UIMessageStreamOutcome = { status: 'completed' } | { status: 'failed'; error?: unknown } | { status: 'aborted' } | { status: 'unknown' }",
+              description:
+                'The operation-level outcome of the stream. It reflects the stream owner declaration unless a fatal stream-processing failure occurs, and is separate from model finish reasons and individual error chunks.',
+            },
             {
               name: 'responseMessage',
               type: 'UIMessage',

package/docs/07-reference/05-ai-sdk-errors/ai-tool-choice-violation-error.mdx

@@ -0,0 +1,38 @@
+---
+title: AI_ToolChoiceViolationError
+description: Learn how to handle AI_ToolChoiceViolationError
+---
+
+# AI_ToolChoiceViolationError
+
+This error occurs when a model response does not satisfy an enforced tool
+choice. It is thrown when `toolChoice` is set to `'required'` but the response
+contains no structured tool call, or when a specifically selected tool was not
+called.
+
+The error does not automatically interpret text or reasoning as an executable
+tool call. You can inspect `content` to implement opt-in recovery, including
+schema validation before executing any recovered call.
+
+## Properties
+
+- `toolChoice`: The effective tool choice that the response did not satisfy
+- `finishReason`: The reason why the model finished generating the response
+- `provider`: The provider that returned the response
+- `modelId`: The model that returned the response
+- `content`: The normalized content returned by the model
+- `message`: The error message
+
+## Checking for this Error
+
+You can check if an error is an instance of `AI_ToolChoiceViolationError` using:
+
+```typescript
+import { ToolChoiceViolationError } from 'ai';
+
+if (ToolChoiceViolationError.isInstance(error)) {
+  const serializedCall = error.content.find(part => part.type === 'text')?.text;
+
+  // Parse and validate serializedCall before treating it as a tool call.
+}
+```

package/docs/07-reference/05-ai-sdk-errors/index.mdx

@@ -33,6 +33,7 @@ collapsed: true
 - [AI_RetryError](/docs/reference/ai-sdk-errors/ai-retry-error)
 - [AI_ToolCallNotFoundForApprovalError](/docs/reference/ai-sdk-errors/ai-tool-call-not-found-for-approval-error)
 - [AI_ToolCallRepairError](/docs/reference/ai-sdk-errors/ai-tool-call-repair-error)
+- [AI_ToolChoiceViolationError](/docs/reference/ai-sdk-errors/ai-tool-choice-violation-error)
 - [AI_TooManyEmbeddingValuesForCallError](/docs/reference/ai-sdk-errors/ai-too-many-embedding-values-for-call-error)
 - [AI_TypeValidationError](/docs/reference/ai-sdk-errors/ai-type-validation-error)
 - [AI_UIMessageStreamError](/docs/reference/ai-sdk-errors/ai-ui-message-stream-error)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai",
-  "version": "6.0.270",
+  "version": "6.0.272",
   "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",
   "sideEffects": false,
@@ -45,9 +45,9 @@
   },
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "@ai-sdk/gateway": "3.0.184",
+    "@ai-sdk/gateway": "3.0.185",
     "@ai-sdk/provider": "3.0.15",
-    "@ai-sdk/provider-utils": "4.0.49"
+    "@ai-sdk/provider-utils": "4.0.50"
   },
   "devDependencies": {
     "@edge-runtime/vm": "^5.0.0",

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

@@ -8,7 +8,7 @@ import type { TimeoutConfiguration } from '../prompt/call-settings';
 import type { InferUIMessageChunk } from '../ui-message-stream';
 import { convertToModelMessages } from '../ui/convert-to-model-messages';
 import type { InferUITools, UIMessage } from '../ui/ui-messages';
-import { validateUIMessages } from '../ui/validate-ui-messages';
+import { validateUIMessagesForAgent } from '../ui/validate-ui-messages';
 import type { AsyncIterableStream } from '../util/async-iterable-stream';
 import type { Agent } from './agent';
 import type { ToolLoopAgentOnStepFinishCallback } from './tool-loop-agent-settings';
@@ -58,7 +58,7 @@ export async function createAgentUIStream<
     InferUIMessageChunk<UIMessage<MESSAGE_METADATA, never, InferUITools<TOOLS>>>
   >
 > {
-  const validatedMessages = await validateUIMessages<
+  const validatedMessages = await validateUIMessagesForAgent<
     UIMessage<MESSAGE_METADATA, never, InferUITools<TOOLS>>
   >({
     messages: uiMessages,

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

@@ -119,6 +119,13 @@ export type ToolLoopAgentSettings<
    */
   onFinish?: ToolLoopAgentOnFinishCallback<NoInfer<TOOLS>>;
 
+  /**
+   * Secret for HMAC-signing tool approval requests. When set, the server
+   * signs each approval request at issuance and verifies the signature when
+   * the approval is replayed, preventing client-forged approvals.
+   */
+  experimental_toolApprovalSecret?: string | Uint8Array;
+
   /**
    * Additional provider-specific options. They are passed through
    * to the provider from the AI SDK and enable provider-specific
@@ -185,6 +192,7 @@ export type ToolLoopAgentSettings<
         | 'stopWhen'
         | 'experimental_telemetry'
         | 'activeTools'
+        | 'experimental_toolApprovalSecret'
         | 'providerOptions'
         | 'experimental_context'
         | 'experimental_download'
@@ -209,6 +217,7 @@ export type ToolLoopAgentSettings<
       | 'stopWhen'
       | 'experimental_telemetry'
       | 'activeTools'
+      | 'experimental_toolApprovalSecret'
       | 'providerOptions'
       | 'experimental_context'
       | 'experimental_download'

package/src/error/index.ts

@@ -28,6 +28,7 @@ export { NoSpeechGeneratedError } from './no-speech-generated-error';
 export { NoTranscriptGeneratedError } from './no-transcript-generated-error';
 export { NoVideoGeneratedError } from './no-video-generated-error';
 export { NoSuchToolError } from './no-such-tool-error';
+export { ToolChoiceViolationError } from './tool-choice-violation-error';
 export { ToolCallRepairError } from './tool-call-repair-error';
 export { UnsupportedModelVersionError } from './unsupported-model-version-error';
 export { UIMessageStreamError } from './ui-message-stream-error';

package/src/error/tool-choice-violation-error.ts

@@ -0,0 +1,80 @@
+import {
+  AISDKError,
+  type LanguageModelV3Content,
+  type LanguageModelV3ToolChoice,
+} from '@ai-sdk/provider';
+import type { FinishReason } from '../types/language-model';
+
+const name = 'AI_ToolChoiceViolationError';
+const marker = `vercel.ai.error.${name}`;
+const symbol = Symbol.for(marker);
+
+type EnforcedToolChoice = Extract<
+  LanguageModelV3ToolChoice,
+  { type: 'required' } | { type: 'tool' }
+>;
+
+/**
+ * Thrown when a model response does not satisfy an enforced tool choice.
+ */
+export class ToolChoiceViolationError extends AISDKError {
+  private readonly [symbol] = true; // used in isInstance
+
+  /**
+   * The tool choice that the model response did not satisfy.
+   */
+  readonly toolChoice: EnforcedToolChoice;
+
+  /**
+   * Reason why the model finished generating the response.
+   */
+  readonly finishReason: FinishReason;
+
+  /**
+   * The provider that returned the response.
+   */
+  readonly provider: string;
+
+  /**
+   * The model that returned the response.
+   */
+  readonly modelId: string;
+
+  /**
+   * The normalized content returned by the model.
+   *
+   * This can be inspected to recover a tool call that the provider returned as
+   * text or reasoning instead of a structured tool call.
+   */
+  readonly content: Array<LanguageModelV3Content>;
+
+  constructor({
+    toolChoice,
+    finishReason,
+    provider,
+    modelId,
+    content,
+    message = toolChoice.type === 'required'
+      ? 'Model response did not contain a tool call even though tool choice was required.'
+      : `Model response did not contain a call to the required tool '${toolChoice.toolName}'.`,
+  }: {
+    toolChoice: EnforcedToolChoice;
+    finishReason: FinishReason;
+    provider: string;
+    modelId: string;
+    content: Array<LanguageModelV3Content>;
+    message?: string;
+  }) {
+    super({ name, message });
+
+    this.toolChoice = toolChoice;
+    this.finishReason = finishReason;
+    this.provider = provider;
+    this.modelId = modelId;
+    this.content = content;
+  }
+
+  static isInstance(error: unknown): error is ToolChoiceViolationError {
+    return AISDKError.hasMarker(error, marker);
+  }
+}

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

@@ -11,7 +11,7 @@ import {
   type ProviderOptions,
 } from '@ai-sdk/provider-utils';
 import type { Tracer } from '@opentelemetry/api';
-import { NoOutputGeneratedError } from '../error';
+import { NoOutputGeneratedError, ToolChoiceViolationError } from '../error';
 import { notify } from '../util/notify';
 import { logWarnings } from '../logger/log-warnings';
 import { resolveLanguageModel } from '../model/resolve-model';
@@ -961,6 +961,30 @@ export async function generateText<
                   }),
                 ),
             );
+
+            const enforcedToolChoice =
+              stepToolChoice?.type === 'required' ||
+              stepToolChoice?.type === 'tool'
+                ? stepToolChoice
+                : undefined;
+
+            if (
+              enforcedToolChoice != null &&
+              !stepToolCalls.some(
+                toolCall =>
+                  enforcedToolChoice.type === 'required' ||
+                  toolCall.toolName === enforcedToolChoice.toolName,
+              )
+            ) {
+              throw new ToolChoiceViolationError({
+                toolChoice: enforcedToolChoice,
+                finishReason: currentModelResponse.finishReason.unified,
+                provider: stepModel.provider,
+                modelId: stepModel.modelId,
+                content: currentModelResponse.content,
+              });
+            }
+
             const toolApprovalRequests: Record<
               string,
               ToolApprovalRequestOutput<TOOLS>

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

@@ -64,6 +64,7 @@ import type {
   InferUIMessageChunk,
   UIMessageChunk,
 } from '../ui-message-stream/ui-message-chunks';
+import type { UIMessageStreamOutcome } from '../ui-message-stream/ui-message-stream-outcome';
 import type { UIMessageStreamResponseInit } from '../ui-message-stream/ui-message-stream-response-init';
 import type {
   InferUIMessageData,
@@ -2660,6 +2661,26 @@ class DefaultStreamTextResult<
   }: UIMessageStreamOptions<UI_MESSAGE> = {}): AsyncIterableStream<
     InferUIMessageChunk<UI_MESSAGE>
   > {
+    let outcome: UIMessageStreamOutcome = { status: 'unknown' };
+    let hasFatalFailure = false;
+
+    const setSourceOutcome = (newOutcome: UIMessageStreamOutcome) => {
+      if (
+        !hasFatalFailure &&
+        outcome.status !== 'completed' &&
+        outcome.status !== 'aborted' &&
+        newOutcome.status !== 'unknown' &&
+        (outcome.status === 'unknown' || newOutcome.status !== 'failed')
+      ) {
+        outcome = newOutcome;
+      }
+    };
+
+    const failOutcome = (error: unknown) => {
+      hasFatalFailure = true;
+      outcome = { status: 'failed', error };
+    };
+
     const responseMessageId =
       generateMessageId != null
         ? getResponseUIMessageId({
@@ -2680,7 +2701,58 @@ class DefaultStreamTextResult<
       return tool?.type === 'dynamic' ? true : undefined;
     };
 
-    const baseStream = this.fullStream.pipeThrough(
+    const trackFatalFailures = <T>(stream: ReadableStream<T>) => {
+      const reader = stream.getReader();
+      let readerReleased = false;
+      let streamCancelled = false;
+
+      const releaseReader = () => {
+        if (!readerReleased) {
+          reader.releaseLock();
+          readerReleased = true;
+        }
+      };
+
+      return new ReadableStream<T>({
+        async pull(controller) {
+          try {
+            const { done, value } = await reader.read();
+
+            if (done) {
+              releaseReader();
+              if (!streamCancelled) {
+                controller.close();
+              }
+            } else {
+              controller.enqueue(value);
+            }
+          } catch (error) {
+            releaseReader();
+            if (!streamCancelled) {
+              failOutcome(error);
+              controller.error(error);
+            }
+          }
+        },
+
+        async cancel(reason) {
+          streamCancelled = true;
+          if (readerReleased) {
+            return;
+          }
+
+          try {
+            await reader.cancel(reason);
+          } finally {
+            releaseReader();
+          }
+        },
+      });
+    };
+
+    const sourceStream = trackFatalFailures(this.fullStream);
+
+    const convertedStream = sourceStream.pipeThrough(
       new TransformStream<
         TextStreamPart<TOOLS>,
         UIMessageChunk<
@@ -3021,10 +3093,20 @@ class DefaultStreamTextResult<
               messageMetadata: messageMetadataValue,
             });
           }
+
+          if (part.type === 'finish') {
+            setSourceOutcome({ status: 'completed' });
+          } else if (part.type === 'abort') {
+            setSourceOutcome({ status: 'aborted' });
+          } else if (part.type === 'error') {
+            setSourceOutcome({ status: 'failed', error: part.error });
+          }
         },
       }),
     );
 
+    const baseStream = trackFatalFailures(convertedStream);
+
     return createAsyncIterableStream(
       handleUIMessageStreamFinish<UI_MESSAGE>({
         stream: baseStream,
@@ -3032,6 +3114,7 @@ class DefaultStreamTextResult<
         originalMessages,
         onFinish,
         onError,
+        getOutcome: () => outcome,
       }),
     );
   }

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

@@ -6,7 +6,7 @@ import type { Agent } from '../agent/agent';
 import type { ChatTransport } from './chat-transport';
 import { convertToModelMessages } from './convert-to-model-messages';
 import type { InferUITools, UIMessage } from './ui-messages';
-import { validateUIMessages } from './validate-ui-messages';
+import { validateUIMessagesForAgent } from './validate-ui-messages';
 
 /**
  * Options for the `DirectChatTransport` class.
@@ -80,7 +80,7 @@ export class DirectChatTransport<
     ReadableStream<UIMessageChunk>
   > {
     // Validate the incoming UI messages
-    const validatedMessages = await validateUIMessages<UI_MESSAGE>({
+    const validatedMessages = await validateUIMessagesForAgent<UI_MESSAGE>({
       messages,
       tools: this.agent.tools,
     });