ai 7.0.30 → 7.0.32

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

@@ -1043,7 +1043,7 @@ The following tool input lifecycle hooks are available:
 - **`onInputDelta`**: Called for each chunk of text as the input is streamed
 - **`onInputAvailable`**: Called when the complete input is available and validated
 
-`onInputStart` and `onInputDelta` are only called in streaming contexts (when using `streamText`). They are not called when using `generateText`.
+`onInputStart` is always called before `onInputAvailable`, including when using `generateText`. `onInputDelta` is only called in streaming contexts (when using `streamText`).
 
 ### Example
 

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

@@ -100,6 +100,10 @@ or a message-array `prompt`, `HarnessAgent` takes the latest user message as the
 fresh input for the turn. It does not replay the full prior conversation into
 the harness.
 
+A trailing tool message is handled differently: tool approval responses and
+client-provided tool results continue the unfinished harness turn that produced
+the corresponding request or tool call.
+
 This is different from model calls, where the application usually sends the full
 message history. In chat routes, persist and resume the harness session instead
 of relying on message replay.
@@ -116,6 +120,8 @@ End every session explicitly:
   the turn is unfinished, the resume state includes the continuation state.
 - `session.suspendTurn()` is for advanced active-turn continuation across a
   process boundary.
+- `session.hasUnfinishedTurn()` reports whether the current turn must be
+  continued or suspended before the session accepts a new prompt.
 
 Use `destroy()` for one-off scripts and tests. Use `detach()` or `stop()` for
 HTTP routes that need multi-turn continuity.
@@ -165,8 +171,10 @@ For advanced workflows that must hand off an active turn across a process
 boundary, suspend the turn and persist the continuation state:
 
 ```ts
-const continuationState = await session.suspendTurn();
-await persistContinuationState({ chatId, continuationState });
+if (session.hasUnfinishedTurn()) {
+  const continuationState = await session.suspendTurn();
+  await persistContinuationState({ chatId, continuationState });
+}
 ```
 
 When you only have raw continuation state from `suspendTurn()`, resume with

package/docs/03-ai-sdk-harnesses/03-tools.mdx

@@ -91,6 +91,46 @@ const agent = new HarnessAgent({
 When the harness calls `weather`, `HarnessAgent` executes the tool in your host
 process, then submits the result back to the harness runtime.
 
+## Client-Side Tools
+
+Omit `execute` when a browser, user interaction, or another external process
+provides the tool result:
+
+```ts
+const weather = tool({
+  description: 'Get the current temperature for a city.',
+  inputSchema: z.object({ city: z.string() }),
+});
+```
+
+When the harness calls a tool without `execute`, the returned result slice ends
+after the tool-call step while the underlying turn waits for a result.
+`session.hasUnfinishedTurn()` remains `true`, and `session.suspendTurn()`
+includes the pending tool call in its serializable continuation state.
+
+In UI flows, pass the model messages produced after `addToolOutput` to the next
+`stream()` or `generate()` call. `HarnessAgent` extracts the trailing tool
+result and continues the paused turn automatically.
+
+For direct agent calls, provide the raw result to `continueStream()` or
+`continueGenerate()`:
+
+```ts
+const continued = await agent.continueStream({
+  session,
+  toolResultContinuations: [
+    {
+      toolCallId,
+      output: { city: 'Paris', celsius: 12 },
+    },
+  ],
+});
+```
+
+Set `isError: true` when the external tool failed. To continue in another
+process, call `suspendTurn()`, recreate the session with `continueFrom`, and
+then pass the result to `continueStream()` or `continueGenerate()`.
+
 ## Tool Filtering
 
 Use `activeTools` or `inactiveTools` on `HarnessAgent` to control which tools the

package/docs/07-reference/01-ai-sdk-core/20-tool.mdx

@@ -171,7 +171,7 @@ export const weatherTool = tool({
               isOptional: true,
               type: '(options: ToolExecutionOptions<CONTEXT>) => void | PromiseLike<void>',
               description:
-                'Optional function that is called when the argument streaming starts. Only called when the tool is used in a streaming context.',
+                'Optional function that is called when the model starts generating the tool input. In non-streaming contexts, it is called immediately before onInputAvailable.',
             },
             {
               name: 'onInputDelta',

package/docs/07-reference/01-ai-sdk-core/22-dynamic-tool.mdx

@@ -130,7 +130,7 @@ export const customTool = dynamicTool({
               isOptional: true,
               type: '(options: ToolExecutionOptions<Context>) => void | PromiseLike<void>',
               description:
-                'Optional function that is called when the argument streaming starts. Only called when the tool is used in a streaming context.'
+                'Optional function that is called when the model starts generating the tool input. In non-streaming contexts, it is called immediately before onInputAvailable.'
             },
             {
               name: 'onInputDelta',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai",
-  "version": "7.0.30",
+  "version": "7.0.32",
   "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,9 +42,9 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/gateway": "4.0.22",
+    "@ai-sdk/gateway": "4.0.24",
     "@ai-sdk/provider": "4.0.3",
-    "@ai-sdk/provider-utils": "5.0.10"
+    "@ai-sdk/provider-utils": "5.0.11"
   },
   "devDependencies": {
     "@edge-runtime/vm": "^5.0.0",

package/src/generate-text/collect-tool-approvals.ts

@@ -2,17 +2,18 @@ import type {
   ModelMessage,
   ToolApprovalRequest,
   ToolApprovalResponse,
+  ToolResultPart,
   ToolSet,
 } from '@ai-sdk/provider-utils';
 import { InvalidToolApprovalError } from '../error/invalid-tool-approval-error';
 import { ToolCallNotFoundForApprovalError } from '../error/tool-call-not-found-for-approval-error';
 import type { TypedToolCall } from './tool-call';
-import type { TypedToolResult } from './tool-result';
 
 export type CollectedToolApprovals<TOOLS extends ToolSet> = {
   approvalRequest: ToolApprovalRequest;
   approvalResponse: ToolApprovalResponse;
   toolCall: TypedToolCall<TOOLS>;
+  existingToolResult?: ToolResultPart;
 };
 
 /**
@@ -75,12 +76,10 @@ export function collectToolApprovals<TOOLS extends ToolSet>({
   }
 
   // gather tool results from the last tool message
-  const toolResults: Record<string, TypedToolResult<TOOLS>> = Object.create(
-    null,
-  );
+  const toolResults: Record<string, ToolResultPart> = Object.create(null);
   for (const part of lastMessage.content) {
     if (part.type === 'tool-result') {
-      toolResults[part.toolCallId] = part as TypedToolResult<TOOLS>;
+      toolResults[part.toolCallId] = part;
     }
   }
 
@@ -100,7 +99,12 @@ export function collectToolApprovals<TOOLS extends ToolSet>({
       });
     }
 
-    if (toolResults[approvalRequest.toolCallId] != null) {
+    const existingToolResult = toolResults[approvalRequest.toolCallId];
+    if (
+      existingToolResult != null &&
+      (approvalResponse.approved ||
+        existingToolResult.output.type !== 'execution-denied')
+    ) {
       continue;
     }
 
@@ -116,6 +120,7 @@ export function collectToolApprovals<TOOLS extends ToolSet>({
       approvalRequest,
       approvalResponse,
       toolCall,
+      ...(existingToolResult != null ? { existingToolResult } : {}),
     };
 
     if (approvalResponse.approved) {

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

@@ -682,9 +682,12 @@ export async function generateText<
         ...collectedDeniedToolApprovals,
         ...revalidationDeniedToolApprovals,
       ];
+      const deniedToolApprovalsWithoutResults = deniedToolApprovals.filter(
+        toolApproval => toolApproval.existingToolResult == null,
+      );
 
       if (
-        deniedToolApprovals.length > 0 ||
+        deniedToolApprovalsWithoutResults.length > 0 ||
         localApprovedToolApprovals.length > 0
       ) {
         const toolResults = await executeTools({
@@ -741,7 +744,7 @@ export async function generateText<
         }
 
         // add execution denied tool results for all denied tool approvals:
-        for (const toolApproval of deniedToolApprovals) {
+        for (const toolApproval of deniedToolApprovalsWithoutResults) {
           toolContent.push({
             type: 'tool-result' as const,
             toolCallId: toolApproval.toolCall.toolCallId,
@@ -792,6 +795,10 @@ export async function generateText<
       const pendingDeferredToolCalls = new Map<string, { toolName: string }>();
 
       do {
+        if (steps.length > 0) {
+          mergedAbortSignal?.throwIfAborted();
+        }
+
         // Set up step timeout if configured
         const stepTimeoutId = setAbortTimeout({
           abortController: stepAbortController,
@@ -1057,6 +1064,15 @@ export async function generateText<
                   continue;
                 }
 
+                if (tool.onInputStart != null) {
+                  await tool.onInputStart({
+                    toolCallId: toolCall.toolCallId,
+                    messages: stepMessages,
+                    abortSignal: mergedAbortSignal,
+                    context: runtimeContext,
+                  });
+                }
+
                 if (tool?.onInputAvailable != null) {
                   await tool.onInputAvailable({
                     input: toolCall.input,

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

@@ -1637,6 +1637,10 @@ class DefaultStreamTextResult<
           ),
           ...revalidationDeniedToolApprovals,
         ];
+        const localDeniedToolApprovalsWithoutResults =
+          localDeniedToolApprovals.filter(
+            toolApproval => toolApproval.existingToolResult == null,
+          );
 
         const deniedProviderExecutedToolApprovals = deniedToolApprovals.filter(
           toolApproval => toolApproval.toolCall.providerExecuted,
@@ -1703,7 +1707,10 @@ class DefaultStreamTextResult<
           );
 
           // Local tool results (approved + denied) are sent as tool results:
-          if (toolOutputs.length > 0 || localDeniedToolApprovals.length > 0) {
+          if (
+            toolOutputs.length > 0 ||
+            localDeniedToolApprovalsWithoutResults.length > 0
+          ) {
             const localToolContent: ToolContent = [];
 
             // add regular tool results for approved tool calls:
@@ -1726,7 +1733,7 @@ class DefaultStreamTextResult<
             }
 
             // add execution denied tool results for denied local tool approvals:
-            for (const toolApproval of localDeniedToolApprovals) {
+            for (const toolApproval of localDeniedToolApprovalsWithoutResults) {
               localToolContent.push({
                 type: 'tool-result' as const,
                 toolCallId: toolApproval.toolCall.toolCallId,

package/src/ui/chat.ts

@@ -208,8 +208,8 @@ export interface ChatInit<UI_MESSAGE extends UIMessage> {
    * Optional callback function that is invoked when a tool call is received.
    * Intended for automatic client-side tool execution.
    *
-   * You can optionally return a result for the tool call,
-   * either synchronously or asynchronously.
+   * To add the tool output, call `addToolOutput` without awaiting it inside
+   * this callback. The callback's return value is not used.
    */
   onToolCall?: ChatOnToolCallCallback<UI_MESSAGE>;
 

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

@@ -21,29 +21,29 @@ const toolMetadataSchema: z.ZodType<JSONObject> = z.record(
 );
 
 export const uiMessageChunkSchema = lazySchema(() =>
-  zodSchema(
+  zodSchema<UIMessageChunk>(
     z.union([
-      z.strictObject({
+      z.looseObject({
         type: z.literal('text-start'),
         id: z.string(),
         providerMetadata: providerMetadataSchema.optional(),
       }),
-      z.strictObject({
+      z.looseObject({
         type: z.literal('text-delta'),
         id: z.string(),
         delta: z.string(),
         providerMetadata: providerMetadataSchema.optional(),
       }),
-      z.strictObject({
+      z.looseObject({
         type: z.literal('text-end'),
         id: z.string(),
         providerMetadata: providerMetadataSchema.optional(),
       }),
-      z.strictObject({
+      z.looseObject({
         type: z.literal('error'),
         errorText: z.string(),
       }),
-      z.strictObject({
+      z.looseObject({
         type: z.literal('tool-input-start'),
         toolCallId: z.string(),
         toolName: z.string(),
@@ -53,12 +53,12 @@ export const uiMessageChunkSchema = lazySchema(() =>
         dynamic: z.boolean().optional(),
         title: z.string().optional(),
       }),
-      z.strictObject({
+      z.looseObject({
         type: z.literal('tool-input-delta'),
         toolCallId: z.string(),
         inputTextDelta: z.string(),
       }),
-      z.strictObject({
+      z.looseObject({
         type: z.literal('tool-input-available'),
         toolCallId: z.string(),
         toolName: z.string(),
@@ -69,7 +69,7 @@ export const uiMessageChunkSchema = lazySchema(() =>
         dynamic: z.boolean().optional(),
         title: z.string().optional(),
       }),
-      z.strictObject({
+      z.looseObject({
         type: z.literal('tool-input-error'),
         toolCallId: z.string(),
         toolName: z.string(),
@@ -81,14 +81,14 @@ export const uiMessageChunkSchema = lazySchema(() =>
         errorText: z.string(),
         title: z.string().optional(),
       }),
-      z.strictObject({
+      z.looseObject({
         type: z.literal('tool-approval-request'),
         approvalId: z.string(),
         toolCallId: z.string(),
         isAutomatic: z.boolean().optional(),
         signature: z.string().optional(),
       }),
-      z.strictObject({
+      z.looseObject({
         type: z.literal('tool-approval-response'),
         approvalId: z.string(),
         approved: z.boolean(),
@@ -96,7 +96,7 @@ export const uiMessageChunkSchema = lazySchema(() =>
         providerExecuted: z.boolean().optional(),
         providerMetadata: providerMetadataSchema.optional(),
       }),
-      z.strictObject({
+      z.looseObject({
         type: z.literal('tool-output-available'),
         toolCallId: z.string(),
         output: z.unknown(),
@@ -106,7 +106,7 @@ export const uiMessageChunkSchema = lazySchema(() =>
         dynamic: z.boolean().optional(),
         preliminary: z.boolean().optional(),
       }),
-      z.strictObject({
+      z.looseObject({
         type: z.literal('tool-output-error'),
         toolCallId: z.string(),
         errorText: z.string(),
@@ -115,39 +115,39 @@ export const uiMessageChunkSchema = lazySchema(() =>
         toolMetadata: toolMetadataSchema.optional(),
         dynamic: z.boolean().optional(),
       }),
-      z.strictObject({
+      z.looseObject({
         type: z.literal('tool-output-denied'),
         toolCallId: z.string(),
       }),
-      z.strictObject({
+      z.looseObject({
         type: z.literal('reasoning-start'),
         id: z.string(),
         providerMetadata: providerMetadataSchema.optional(),
       }),
-      z.strictObject({
+      z.looseObject({
         type: z.literal('reasoning-delta'),
         id: z.string(),
         delta: z.string(),
         providerMetadata: providerMetadataSchema.optional(),
       }),
-      z.strictObject({
+      z.looseObject({
         type: z.literal('reasoning-end'),
         id: z.string(),
         providerMetadata: providerMetadataSchema.optional(),
       }),
-      z.strictObject({
+      z.looseObject({
         type: z.literal('custom'),
         kind: z.string().transform(value => value as `${string}.${string}`),
         providerMetadata: providerMetadataSchema.optional(),
       }),
-      z.strictObject({
+      z.looseObject({
         type: z.literal('source-url'),
         sourceId: z.string(),
         url: z.string(),
         title: z.string().optional(),
         providerMetadata: providerMetadataSchema.optional(),
       }),
-      z.strictObject({
+      z.looseObject({
         type: z.literal('source-document'),
         sourceId: z.string(),
         mediaType: z.string(),
@@ -155,19 +155,19 @@ export const uiMessageChunkSchema = lazySchema(() =>
         filename: z.string().optional(),
         providerMetadata: providerMetadataSchema.optional(),
       }),
-      z.strictObject({
+      z.looseObject({
         type: z.literal('file'),
         url: z.string(),
         mediaType: z.string(),
         providerMetadata: providerMetadataSchema.optional(),
       }),
-      z.strictObject({
+      z.looseObject({
         type: z.literal('reasoning-file'),
         url: z.string(),
         mediaType: z.string(),
         providerMetadata: providerMetadataSchema.optional(),
       }),
-      z.strictObject({
+      z.looseObject({
         type: z.custom<`data-${string}`>(
           (value): value is `data-${string}` =>
             typeof value === 'string' && value.startsWith('data-'),
@@ -177,18 +177,18 @@ export const uiMessageChunkSchema = lazySchema(() =>
         data: z.unknown(),
         transient: z.boolean().optional(),
       }),
-      z.strictObject({
+      z.looseObject({
         type: z.literal('start-step'),
       }),
-      z.strictObject({
+      z.looseObject({
         type: z.literal('finish-step'),
       }),
-      z.strictObject({
+      z.looseObject({
         type: z.literal('start'),
         messageId: z.string().optional(),
         messageMetadata: z.unknown().optional(),
       }),
-      z.strictObject({
+      z.looseObject({
         type: z.literal('finish'),
         finishReason: z
           .enum([
@@ -202,11 +202,11 @@ export const uiMessageChunkSchema = lazySchema(() =>
           .optional(),
         messageMetadata: z.unknown().optional(),
       }),
-      z.strictObject({
+      z.looseObject({
         type: z.literal('abort'),
         reason: z.string().optional(),
       }),
-      z.strictObject({
+      z.looseObject({
         type: z.literal('message-metadata'),
         messageMetadata: z.unknown(),
       }),