ai 7.0.41 → 7.0.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai",
-  "version": "7.0.41",
+  "version": "7.0.43",
   "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.31",
+    "@ai-sdk/gateway": "4.0.33",
     "@ai-sdk/provider": "4.0.4",
-    "@ai-sdk/provider-utils": "5.0.14"
+    "@ai-sdk/provider-utils": "5.0.16"
   },
   "devDependencies": {
     "@edge-runtime/vm": "^5.0.0",
@@ -55,7 +55,7 @@
     "tsx": "^4.22.0",
     "typescript": "5.8.3",
     "zod": "3.25.76",
-    "@ai-sdk/test-server": "2.0.0",
+    "@ai-sdk/test-server": "2.0.1",
     "@vercel/ai-tsconfig": "0.0.0"
   },
   "peerDependencies": {

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

@@ -40,7 +40,9 @@ export interface GenerateTextResult<
   readonly content: Array<ContentPart<TOOLS>>;
 
   /**
-   * The text that was generated in the final step.
+   * The concatenation of all text parts generated in the final step.
+   * It is an empty string if the final step contains no text parts.
+   * Inspect `finalStep.content` to distinguish that case.
    */
   readonly text: string;
 

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

@@ -84,6 +84,7 @@ import { text, type Output } from './output';
 import type { InferCompleteOutput } from './output-utils';
 import { parseToolCall } from './parse-tool-call';
 import type { PrepareStepFunction } from './prepare-step';
+import { prepareStepCallSettings } from './prepare-step-call-settings';
 import { convertToReasoningOutputs } from './reasoning-output';
 import { resolveToolApproval } from './resolve-tool-approval';
 import type { ResponseMessage } from './response-message';
@@ -103,6 +104,11 @@ import { toResponseMessages } from './to-response-messages';
 import type { ToolApprovalConfiguration } from './tool-approval-configuration';
 import type { ToolApprovalRequestOutput } from './tool-approval-request-output';
 import type { ToolApprovalResponseOutput } from './tool-approval-response-output';
+import {
+  prepareToolsForToolCallers,
+  resolveToolCallerConfiguration,
+  type Experimental_ToolCallers,
+} from './tool-caller-configuration';
 import type { TypedToolCall } from './tool-call';
 import type { ToolCallRepairFunction } from './tool-call-repair-function';
 import type { TypedToolError } from './tool-error';
@@ -241,6 +247,7 @@ export async function generateText<
   experimental_sandbox: sandbox,
   output,
   toolApproval,
+  experimental_toolCallers,
   experimental_toolApprovalSecret,
   experimental_telemetry,
   telemetry = experimental_telemetry,
@@ -357,6 +364,11 @@ export async function generateText<
      */
     toolApproval?: ToolApprovalConfiguration<TOOLS, RUNTIME_CONTEXT>;
 
+    /**
+     * Configures which caller tools may invoke each tool.
+     */
+    experimental_toolCallers?: Experimental_ToolCallers<NoInfer<TOOLS>>;
+
     /**
      * Secret for HMAC-signing tool approval requests. When set, the server
      * signs each approval request at issuance and verifies the signature when
@@ -559,6 +571,10 @@ export async function generateText<
   };
 
   const model = resolveLanguageModel(modelArg);
+  const resolvedToolCallers = resolveToolCallerConfiguration({
+    tools,
+    toolCallers: experimental_toolCallers,
+  });
   const stopConditions = asArray(stopWhen);
   const resolvedOnStart = onStart ?? experimental_onStart;
   const resolvedOnStepStart = onStepStart ?? experimental_onStepStart;
@@ -862,10 +878,20 @@ export async function generateText<
                 tools,
                 activeTools: prepareStepResult?.activeTools ?? activeTools,
               });
+              const {
+                executionTools: stepExecutionTools,
+                modelTools: stepModelTools,
+              } = prepareToolsForToolCallers({
+                tools: stepActiveTools,
+                toolCallers: resolvedToolCallers,
+              });
               const stepToolOrder = prepareStepResult?.toolOrder ?? toolOrder;
 
               const stepTools = await prepareTools({
-                tools: stepActiveTools,
+                tools: stepModelTools as ActiveToolSubset<
+                  TOOLS,
+                  ActiveTools<NoInfer<TOOLS>>
+                >,
                 toolOrder: stepToolOrder as ToolOrder<
                   ActiveToolSubset<TOOLS, ActiveTools<NoInfer<TOOLS>>>
                 >,
@@ -888,6 +914,11 @@ export async function generateText<
                 prepareStepResult?.providerOptions,
               );
 
+              const stepCallSettings = prepareStepCallSettings({
+                callSettings,
+                stepSettings: prepareStepResult,
+              });
+
               await notify({
                 event: {
                   callId,
@@ -921,7 +952,7 @@ export async function generateText<
                 instructions: stepInstructions,
                 messages: stepMessages,
                 tools: stepTools,
-                ...callSettings,
+                ...stepCallSettings,
               };
               const languageModelCallStartEvent = {
                 callId,
@@ -951,7 +982,7 @@ export async function generateText<
                     ...languageModelCallStartEvent,
                     execute: async () =>
                       await stepModel.doGenerate({
-                        ...callSettings,
+                        ...stepCallSettings,
                         tools: stepTools,
                         toolChoice: stepToolChoice,
                         responseFormat: await output?.responseFormat,
@@ -988,7 +1019,7 @@ export async function generateText<
                   .map(toolCall =>
                     parseToolCall({
                       toolCall,
-                      tools,
+                      tools: stepExecutionTools as TOOLS,
                       repairToolCall,
                       refineToolInput,
                       instructions: stepInstructions,
@@ -1056,7 +1087,7 @@ export async function generateText<
                   continue; // ignore invalid tool calls
                 }
 
-                const tool = getOwn(tools, toolCall.toolName);
+                const tool = getOwn(stepExecutionTools, toolCall.toolName);
 
                 if (tool == null) {
                   // ignore tool calls for tools that are not available,
@@ -1084,7 +1115,7 @@ export async function generateText<
                 }
 
                 const toolApprovalStatus = await resolveToolApproval({
-                  tools,
+                  tools: stepExecutionTools as TOOLS,
                   toolApproval,
                   toolCall,
                   messages: stepMessages,
@@ -1193,14 +1224,14 @@ export async function generateText<
               );
               const toolExecutionMs: Record<string, number> = {};
 
-              if (tools != null) {
+              if (stepExecutionTools != null) {
                 const toolExecutionResults = await executeTools({
                   toolCalls: clientToolCalls.filter(
                     toolCall =>
                       !toolCall.invalid &&
                       !blockedToolCallIds.has(toolCall.toolCallId),
                   ),
-                  tools,
+                  tools: stepExecutionTools as TOOLS,
                   callId,
                   messages: stepMessages,
                   abortSignal: mergedAbortSignal,
@@ -1262,7 +1293,7 @@ export async function generateText<
               // the client tool's result is sent back.
               for (const toolCall of stepToolCalls) {
                 if (!toolCall.providerExecuted) continue;
-                const tool = getOwn(tools, toolCall.toolName);
+                const tool = getOwn(stepExecutionTools, toolCall.toolName);
                 if (tool?.type === 'provider' && tool.supportsDeferredResults) {
                   // Check if this tool call already has a result in the current response
                   const hasResultInResponse = currentModelResponse.content.some(

package/src/generate-text/index.ts

@@ -80,6 +80,10 @@ export type {
   ToolApprovalConfiguration,
   ToolApprovalStatus,
 } from './tool-approval-configuration';
+export type {
+  Experimental_ToolCallerReference,
+  Experimental_ToolCallers,
+} from './tool-caller-configuration';
 export { detectToolDrift, fingerprintTools } from './tool-fingerprint';
 export type { ToolApprovalRequestOutput } from './tool-approval-request-output';
 export type { ToolApprovalResponseOutput } from './tool-approval-response-output';

package/src/generate-text/prepare-step-call-settings.ts

@@ -0,0 +1,31 @@
+import type { LanguageModelCallOptions } from '../prompt/language-model-call-options';
+import { prepareLanguageModelCallOptions } from '../prompt/prepare-language-model-call-options';
+
+/**
+ * Resolves model call settings for a single step.
+ *
+ * Undefined step settings intentionally fall back to the outer call settings,
+ * while defined falsy values such as `temperature: 0` and `seed: 0` are kept.
+ */
+export function prepareStepCallSettings({
+  callSettings,
+  stepSettings,
+}: {
+  callSettings: LanguageModelCallOptions;
+  stepSettings: LanguageModelCallOptions | undefined;
+}): LanguageModelCallOptions {
+  return prepareLanguageModelCallOptions({
+    maxOutputTokens:
+      stepSettings?.maxOutputTokens ?? callSettings.maxOutputTokens,
+    temperature: stepSettings?.temperature ?? callSettings.temperature,
+    topP: stepSettings?.topP ?? callSettings.topP,
+    topK: stepSettings?.topK ?? callSettings.topK,
+    presencePenalty:
+      stepSettings?.presencePenalty ?? callSettings.presencePenalty,
+    frequencyPenalty:
+      stepSettings?.frequencyPenalty ?? callSettings.frequencyPenalty,
+    stopSequences: stepSettings?.stopSequences ?? callSettings.stopSequences,
+    seed: stepSettings?.seed ?? callSettings.seed,
+    reasoning: stepSettings?.reasoning ?? callSettings.reasoning,
+  });
+}

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

@@ -7,6 +7,7 @@ import type {
   ToolSet,
 } from '@ai-sdk/provider-utils';
 import type { Instructions } from '../prompt';
+import type { LanguageModelCallOptions } from '../prompt/language-model-call-options';
 import type { LanguageModel, ToolChoice } from '../types/language-model';
 import type { ActiveTools } from './active-tools';
 import type { ResponseMessage } from './response-message';
@@ -95,13 +96,17 @@ export type PrepareStepFunction<
 
 /**
  * The result type returned by a {@link PrepareStepFunction},
- * allowing per-step overrides of model, tools, instructions, or messages.
+ * allowing per-step overrides of model call settings, model, tools,
+ * instructions, or messages.
+ *
+ * Model call setting overrides apply only to the current step. Undefined
+ * settings fall back to the outer call settings.
  */
 export type PrepareStepResult<
   TOOLS extends ToolSet,
   RUNTIME_CONTEXT extends Context = Context,
 > =
-  | {
+  | ({
       /**
        * Optionally override which LanguageModel instance is used for this step.
        */
@@ -175,5 +180,5 @@ export type PrepareStepResult<
        * container IDs for Anthropic's code execution.
        */
       providerOptions?: ProviderOptions;
-    }
+    } & LanguageModelCallOptions)
   | undefined;

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

@@ -176,7 +176,8 @@ export type StepResult<
   readonly content: Array<ContentPart<TOOLS>>;
 
   /**
-   * The generated text. Can be an empty string if the model has not generated any text.
+   * The concatenation of all text parts generated in this step.
+   * It is an empty string if the step contains no text parts.
    */
   readonly text: string;
 

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

@@ -113,6 +113,7 @@ import type {
   InferPartialOutput,
 } from './output-utils';
 import type { PrepareStepFunction } from './prepare-step';
+import { prepareStepCallSettings } from './prepare-step-call-settings';
 import { convertToReasoningOutputs } from './reasoning-output';
 import type { ResponseMessage } from './response-message';
 import { createRestrictedTelemetryDispatcher } from './restricted-telemetry-dispatcher';
@@ -915,6 +916,11 @@ function createOutputTransformStream<
       textChunk += chunk.text;
       textProviderMetadata = chunk.providerMetadata ?? textProviderMetadata;
 
+      if (chunk.text.length === 0 && chunk.providerMetadata != null) {
+        controller.enqueue({ part: chunk, partialOutput: undefined });
+        return;
+      }
+
       // only publish if partial json can be parsed:
       const result = await output.parsePartialOutput({ text });
 
@@ -1963,6 +1969,11 @@ class DefaultStreamTextResult<
             prepareStepResult?.providerOptions,
           );
 
+          const stepCallSettings = prepareStepCallSettings({
+            callSettings,
+            stepSettings: prepareStepResult,
+          });
+
           const stepStartTimestampMs = now();
 
           const { retry } = prepareRetries({ maxRetries, abortSignal });
@@ -2035,7 +2046,7 @@ class DefaultStreamTextResult<
                 _internal: {
                   now,
                 },
-                ...callSettings,
+                ...stepCallSettings,
               }),
             ),
           );
@@ -2198,7 +2209,10 @@ class DefaultStreamTextResult<
                     }
 
                     case 'text-delta': {
-                      if (chunk.text.length > 0) {
+                      if (
+                        chunk.text.length > 0 ||
+                        chunk.providerMetadata != null
+                      ) {
                         controller.enqueue(chunk);
                       }
                       break;

package/src/generate-text/tool-caller-configuration.ts

@@ -0,0 +1,186 @@
+import {
+  experimental_getToolCaller,
+  type Experimental_ToolCallerTool,
+  type Tool,
+  type ToolSet,
+} from '@ai-sdk/provider-utils';
+import { InvalidArgumentError } from '../error/invalid-argument-error';
+
+export interface Experimental_ToolCallerReference<
+  NAME extends string = string,
+> {
+  readonly toolName: NAME;
+}
+
+type ToolCallerName<TOOLS extends ToolSet> = {
+  [NAME in keyof TOOLS]: TOOLS[NAME] extends Experimental_ToolCallerTool
+    ? NAME
+    : never;
+}[keyof TOOLS] &
+  string;
+
+type ToolCallerReferenceUnion<TOOLS extends ToolSet> = {
+  [NAME in ToolCallerName<TOOLS>]: Experimental_ToolCallerReference<NAME>;
+}[ToolCallerName<TOOLS>];
+
+export type Experimental_ToolCallers<TOOLS extends ToolSet> = (callers: {
+  [NAME in ToolCallerName<TOOLS>]: Experimental_ToolCallerReference<NAME>;
+}) => {
+  [NAME in keyof TOOLS]?: ReadonlyArray<
+    'direct' | ToolCallerReferenceUnion<TOOLS>
+  >;
+};
+
+export type ResolvedToolCallers = Record<
+  string,
+  ReadonlyArray<'direct' | string>
+>;
+
+export function resolveToolCallerConfiguration<TOOLS extends ToolSet>({
+  tools,
+  toolCallers,
+}: {
+  tools: TOOLS | undefined;
+  toolCallers: Experimental_ToolCallers<TOOLS> | undefined;
+}): ResolvedToolCallers | undefined {
+  if (tools == null || toolCallers == null) {
+    return undefined;
+  }
+
+  const namesByReference = new WeakMap<object, string>();
+  const callerReferences: Record<string, Experimental_ToolCallerReference> = {};
+
+  for (const [toolName, tool] of Object.entries(tools)) {
+    if (experimental_getToolCaller(tool) == null) {
+      continue;
+    }
+
+    const reference = Object.freeze({ toolName });
+    namesByReference.set(reference, toolName);
+    callerReferences[toolName] = reference;
+  }
+
+  const configuration = toolCallers(callerReferences as never);
+  const resolved: ResolvedToolCallers = {};
+
+  for (const [toolName, callers] of Object.entries(configuration)) {
+    if (!Object.prototype.hasOwnProperty.call(tools, toolName)) {
+      throw new InvalidArgumentError({
+        parameter: 'experimental_toolCallers',
+        value: configuration,
+        message: `unknown tool "${toolName}".`,
+      });
+    }
+
+    if (!Array.isArray(callers)) {
+      throw new InvalidArgumentError({
+        parameter: 'experimental_toolCallers',
+        value: configuration,
+        message: `callers for tool "${toolName}" must be an array.`,
+      });
+    }
+
+    resolved[toolName] = callers.map(caller => {
+      if (caller === 'direct') {
+        return caller;
+      }
+
+      const callerName =
+        caller != null && typeof caller === 'object'
+          ? namesByReference.get(caller)
+          : undefined;
+
+      if (callerName == null) {
+        throw new InvalidArgumentError({
+          parameter: 'experimental_toolCallers',
+          value: configuration,
+          message: `tool "${toolName}" contains an invalid caller reference.`,
+        });
+      }
+
+      return callerName;
+    });
+  }
+
+  return resolved;
+}
+
+export function prepareToolsForToolCallers({
+  tools,
+  toolCallers,
+}: {
+  tools: ToolSet | undefined;
+  toolCallers: ResolvedToolCallers | undefined;
+}): {
+  executionTools: ToolSet | undefined;
+  modelTools: ToolSet | undefined;
+} {
+  if (tools == null || toolCallers == null) {
+    return { executionTools: tools, modelTools: tools };
+  }
+
+  const executionTools: ToolSet = { ...tools };
+  const modelTools: ToolSet = { ...tools };
+  const localToolsByCaller = new Map<string, ToolSet>();
+
+  for (const [toolName, callerNames] of Object.entries(toolCallers)) {
+    const tool = executionTools[toolName];
+    if (tool == null) {
+      continue;
+    }
+
+    let availableDirectly = false;
+    let availableToProvider = false;
+    let preparedTool: Tool = tool;
+
+    for (const callerName of callerNames) {
+      if (callerName === 'direct') {
+        availableDirectly = true;
+        continue;
+      }
+
+      const caller = experimental_getToolCaller(executionTools[callerName]);
+      if (caller == null) {
+        continue;
+      }
+
+      if (caller.type === 'provider') {
+        availableToProvider = true;
+        preparedTool = {
+          ...preparedTool,
+          providerOptions: caller.prepareProviderOptions(
+            preparedTool.providerOptions,
+          ),
+        } as Tool;
+      } else {
+        const localTools = localToolsByCaller.get(callerName) ?? {};
+        localTools[toolName] = preparedTool;
+        localToolsByCaller.set(callerName, localTools);
+      }
+    }
+
+    executionTools[toolName] = preparedTool;
+
+    if (availableDirectly || availableToProvider) {
+      modelTools[toolName] = preparedTool;
+    } else {
+      delete modelTools[toolName];
+    }
+  }
+
+  for (const [callerName, callerTool] of Object.entries(executionTools)) {
+    const caller = experimental_getToolCaller(callerTool);
+    if (caller?.type !== 'local') {
+      continue;
+    }
+
+    const boundCaller = caller.bind(localToolsByCaller.get(callerName) ?? {});
+    executionTools[callerName] = boundCaller;
+
+    if (Object.prototype.hasOwnProperty.call(modelTools, callerName)) {
+      modelTools[callerName] = boundCaller;
+    }
+  }
+
+  return { executionTools, modelTools };
+}

package/src/index.ts

@@ -7,6 +7,7 @@ export {
   asSchema,
   createIdGenerator,
   dynamicTool,
+  experimental_toolCaller,
   generateId,
   jsonSchema,
   parseJsonEventStream,
@@ -19,6 +20,7 @@ export {
   type InferToolOutput,
   type Experimental_SandboxSession,
   type Experimental_SandboxProcess,
+  type Experimental_ToolCallerTool,
   type Schema,
   type Tool,
   type ToolApprovalRequest,