ai 6.0.270 → 6.0.271

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.271" : "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.271" : "0.0.0-test";
 
 // src/util/download/download.ts
 var download = async ({

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai",
-  "version": "6.0.270",
+  "version": "6.0.271",
   "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,

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/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,
     });

package/src/ui/validate-ui-messages.ts

@@ -5,6 +5,7 @@ import {
 } from '@ai-sdk/provider';
 import {
   lazySchema,
+  safeValidateTypes,
   StandardSchemaV1,
   validateTypes,
   zodSchema,
@@ -17,6 +18,7 @@ import { jsonValueSchema } from '../types/json-value';
 import { providerMetadataSchema } from '../types/provider-metadata';
 import type {
   DataUIPart,
+  DynamicToolUIPart,
   InferUIMessageData,
   InferUIMessageTools,
   ToolUIPart,
@@ -28,6 +30,25 @@ const toolMetadataSchema: z.ZodType<JSONObject> = z.record(
   jsonValueSchema.optional(),
 );
 
+function isEmptyObject(value: unknown): value is Record<string, never> {
+  return (
+    value != null &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    Object.keys(value).length === 0
+  );
+}
+
+function asDynamicToolPart(toolPart: ToolUIPart): DynamicToolUIPart {
+  const { type, ...part } = toolPart;
+
+  return {
+    ...part,
+    type: 'dynamic-tool',
+    toolName: type.slice(5),
+  } as DynamicToolUIPart;
+}
+
 const uiMessagesSchema = lazySchema(() =>
   zodSchema(
     z
@@ -354,17 +375,7 @@ export type SafeValidateUIMessagesResult<UI_MESSAGE extends UIMessage> =
       error: Error;
     };
 
-/**
- * Validates a list of UI messages like `validateUIMessages`,
- * but instead of throwing it returns `{ success: true, data }`
- * or `{ success: false, error }`.
- */
-export async function safeValidateUIMessages<UI_MESSAGE extends UIMessage>({
-  messages,
-  metadataSchema,
-  dataSchemas,
-  tools,
-}: {
+type ValidateUIMessagesOptions<UI_MESSAGE extends UIMessage> = {
   messages: unknown;
   metadataSchema?: FlexibleSchema<UIMessage['metadata']>;
   dataSchemas?: {
@@ -378,7 +389,21 @@ export async function safeValidateUIMessages<UI_MESSAGE extends UIMessage>({
       InferUIMessageTools<UI_MESSAGE>[NAME]['output']
     >;
   };
-}): Promise<SafeValidateUIMessagesResult<UI_MESSAGE>> {
+};
+
+async function safeValidateUIMessagesInternal<UI_MESSAGE extends UIMessage>(
+  {
+    messages,
+    metadataSchema,
+    dataSchemas,
+    tools,
+  }: ValidateUIMessagesOptions<UI_MESSAGE>,
+  {
+    convertMissingTerminalToolsToDynamic,
+  }: {
+    convertMissingTerminalToolsToDynamic: boolean;
+  },
+): Promise<SafeValidateUIMessagesResult<UI_MESSAGE>> {
   try {
     if (messages == null) {
       return {
@@ -409,7 +434,10 @@ export async function safeValidateUIMessages<UI_MESSAGE extends UIMessage>({
       }
     }
 
-    if (dataSchemas || tools) {
+    const shouldValidateToolParts =
+      tools != null || convertMissingTerminalToolsToDynamic;
+
+    if (dataSchemas || shouldValidateToolParts) {
       for (const [msgIdx, message] of validatedMessages.entries()) {
         for (const [partIdx, part] of message.parts.entries()) {
           // Data part validation
@@ -445,19 +473,26 @@ export async function safeValidateUIMessages<UI_MESSAGE extends UIMessage>({
           }
 
           // Tool part validation
-          if (tools && part.type.startsWith('tool-')) {
+          if (shouldValidateToolParts && part.type.startsWith('tool-')) {
             const toolPart = part as ToolUIPart<
               InferUIMessageTools<UI_MESSAGE>
             >;
             const toolName = toolPart.type.slice(5);
-            const tool = tools[toolName];
+            const tool = tools?.[toolName];
+            const isTerminal =
+              toolPart.state === 'output-available' ||
+              toolPart.state === 'output-error' ||
+              toolPart.state === 'output-denied';
 
-            if (
-              !tool &&
-              (toolPart.state === 'output-available' ||
-                toolPart.state === 'output-error' ||
-                toolPart.state === 'output-denied')
-            ) {
+            if (!tool && isTerminal) {
+              if (tools != null || convertMissingTerminalToolsToDynamic) {
+                // Persisted terminal history can reference tools that are no
+                // longer registered. Normalize those parts so callers do not
+                // receive unvalidated values under current static tool types.
+                message.parts[partIdx] = asDynamicToolPart(
+                  toolPart,
+                ) as (typeof message.parts)[number];
+              }
               continue;
             }
 
@@ -477,19 +512,53 @@ export async function safeValidateUIMessages<UI_MESSAGE extends UIMessage>({
               };
             }
 
+            const inputValidationContext = {
+              field: `messages[${msgIdx}].parts[${partIdx}].input`,
+              entityName: toolName,
+              entityId: toolPart.toolCallId,
+            };
+            let convertToDynamic = false;
+
             // Tool input validation
-            // Note: input is intentionally not re-validated for terminal states.
-            // Terminal tool calls can keep invalid or incomplete input, and
-            // re-validating it on replay would crash follow-up messages.
-            if (toolPart.state === 'input-available') {
+            if (toolPart.state === 'output-error') {
+              // Failed calls can retain invalid input. Keep them loadable, but
+              // expose incompatible input as unknown instead of the current
+              // static tool input type.
+              if (toolPart.input !== undefined) {
+                const result = await safeValidateTypes({
+                  value: toolPart.input,
+                  schema: tool.inputSchema,
+                  context: inputValidationContext,
+                });
+                convertToDynamic = !result.success;
+              }
+            } else if (toolPart.state === 'output-available') {
+              const result = await safeValidateTypes({
+                value: toolPart.input,
+                schema: tool.inputSchema,
+                context: inputValidationContext,
+              });
+
+              if (!result.success) {
+                // Empty terminal input can represent aborted or incomplete
+                // history whose input was never streamed. Preserve it without
+                // claiming that it matches the current static input type.
+                if (isEmptyObject(toolPart.input)) {
+                  convertToDynamic = true;
+                } else {
+                  throw result.error;
+                }
+              }
+            } else if (
+              toolPart.state === 'input-available' ||
+              toolPart.state === 'approval-requested' ||
+              toolPart.state === 'approval-responded' ||
+              toolPart.state === 'output-denied'
+            ) {
               await validateTypes({
                 value: toolPart.input,
                 schema: tool.inputSchema,
-                context: {
-                  field: `messages[${msgIdx}].parts[${partIdx}].input`,
-                  entityName: toolName,
-                  entityId: toolPart.toolCallId,
-                },
+                context: inputValidationContext,
               });
             }
 
@@ -505,6 +574,12 @@ export async function safeValidateUIMessages<UI_MESSAGE extends UIMessage>({
                 },
               });
             }
+
+            if (convertToDynamic) {
+              message.parts[partIdx] = asDynamicToolPart(
+                toolPart,
+              ) as (typeof message.parts)[number];
+            }
           }
         }
       }
@@ -524,6 +599,19 @@ export async function safeValidateUIMessages<UI_MESSAGE extends UIMessage>({
   }
 }
 
+/**
+ * Validates a list of UI messages like `validateUIMessages`,
+ * but instead of throwing it returns `{ success: true, data }`
+ * or `{ success: false, error }`.
+ */
+export async function safeValidateUIMessages<UI_MESSAGE extends UIMessage>(
+  options: ValidateUIMessagesOptions<UI_MESSAGE>,
+): Promise<SafeValidateUIMessagesResult<UI_MESSAGE>> {
+  return safeValidateUIMessagesInternal(options, {
+    convertMissingTerminalToolsToDynamic: false,
+  });
+}
+
 /**
  * Validates a list of UI messages.
  *
@@ -531,31 +619,24 @@ export async function safeValidateUIMessages<UI_MESSAGE extends UIMessage>({
  * the corresponding schemas are provided. Otherwise, they are assumed to be
  * valid.
  */
-export async function validateUIMessages<UI_MESSAGE extends UIMessage>({
-  messages,
-  metadataSchema,
-  dataSchemas,
-  tools,
-}: {
-  messages: unknown;
-  metadataSchema?: FlexibleSchema<UIMessage['metadata']>;
-  dataSchemas?: {
-    [NAME in keyof InferUIMessageData<UI_MESSAGE> & string]?: FlexibleSchema<
-      InferUIMessageData<UI_MESSAGE>[NAME]
-    >;
-  };
-  tools?: {
-    [NAME in keyof InferUIMessageTools<UI_MESSAGE> & string]?: Tool<
-      InferUIMessageTools<UI_MESSAGE>[NAME]['input'],
-      InferUIMessageTools<UI_MESSAGE>[NAME]['output']
-    >;
-  };
-}): Promise<Array<UI_MESSAGE>> {
-  const response = await safeValidateUIMessages({
-    messages,
-    metadataSchema,
-    dataSchemas,
-    tools,
+export async function validateUIMessages<UI_MESSAGE extends UIMessage>(
+  options: ValidateUIMessagesOptions<UI_MESSAGE>,
+): Promise<Array<UI_MESSAGE>> {
+  const response = await safeValidateUIMessages(options);
+
+  if (!response.success) throw response.error;
+
+  return response.data;
+}
+
+export async function validateUIMessagesForAgent<UI_MESSAGE extends UIMessage>(
+  options: ValidateUIMessagesOptions<UI_MESSAGE>,
+): Promise<Array<UI_MESSAGE>> {
+  const response = await safeValidateUIMessagesInternal(options, {
+    // Agent tool sets can include ephemeral tools (for example, tools from a
+    // disconnected MCP server), so terminal history is converted to dynamic
+    // tool parts when those tools are no longer registered.
+    convertMissingTerminalToolsToDynamic: true,
   });
 
   if (!response.success) throw response.error;