ai 6.0.95 → 6.0.97

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

@@ -1,6 +1,7 @@
 import {
   getErrorMessage,
   LanguageModelV3,
+  LanguageModelV3ToolChoice,
   SharedV3Warning,
   UnsupportedFunctionalityError,
 } from '@ai-sdk/provider';
@@ -9,7 +10,9 @@ import {
   DelayedPromise,
   IdGenerator,
   isAbortError,
+  ModelMessage,
   ProviderOptions,
+  SystemModelMessage,
   ToolApprovalResponse,
   ToolContent,
 } from '@ai-sdk/provider-utils';
@@ -23,6 +26,7 @@ import {
   getChunkTimeoutMs,
   getStepTimeoutMs,
   getTotalTimeoutMs,
+  TimeoutConfiguration,
 } from '../prompt/call-settings';
 import { convertToLanguageModelPrompt } from '../prompt/convert-to-language-model-prompt';
 import { createToolModelOutput } from '../prompt/create-tool-model-output';
@@ -77,6 +81,14 @@ import { mergeObjects } from '../util/merge-objects';
 import { now as originalNow } from '../util/now';
 import { prepareRetries } from '../util/prepare-retries';
 import { collectToolApprovals } from './collect-tool-approvals';
+import type {
+  OnFinishEvent,
+  OnStartEvent,
+  OnStepFinishEvent,
+  OnStepStartEvent,
+  OnToolCallFinishEvent,
+  OnToolCallStartEvent,
+} from './callback-events';
 import { ContentPart } from './content-part';
 import { executeToolCall } from './execute-tool-call';
 import { Output, text } from './output';
@@ -141,7 +153,7 @@ export type StreamTextOnErrorCallback = (event: {
  * @param stepResult - The result of the step.
  */
 export type StreamTextOnStepFinishCallback<TOOLS extends ToolSet> = (
-  stepResult: StepResult<TOOLS>,
+  event: OnStepFinishEvent<TOOLS>,
 ) => PromiseLike<void> | void;
 
 /**
@@ -172,26 +184,7 @@ export type StreamTextOnChunkCallback<TOOLS extends ToolSet> = (event: {
  * @param event - The event that is passed to the callback.
  */
 export type StreamTextOnFinishCallback<TOOLS extends ToolSet> = (
-  event: StepResult<TOOLS> & {
-    /**
-     * Details for all steps.
-     */
-    readonly steps: StepResult<TOOLS>[];
-
-    /**
-     * Total usage for all steps. This is the sum of the usage of all steps.
-     */
-    readonly totalUsage: LanguageModelUsage;
-
-    /**
-     * Context that is passed into tool execution.
-     *
-     * Experimental (can break in patch releases).
-     *
-     * @default undefined
-     */
-    experimental_context: unknown;
-  },
+  event: OnFinishEvent<TOOLS>,
 ) => PromiseLike<void> | void;
 
 /**
@@ -206,6 +199,50 @@ export type StreamTextOnAbortCallback<TOOLS extends ToolSet> = (event: {
   readonly steps: StepResult<TOOLS>[];
 }) => PromiseLike<void> | void;
 
+/**
+ * Include settings for streamText (requestBody only).
+ */
+type StreamTextIncludeSettings = { requestBody?: boolean };
+
+/**
+ * Callback that is set using the `experimental_onStart` option.
+ *
+ * Called when the streamText operation begins, before any LLM calls.
+ * Use this callback for logging, analytics, or initializing state at the
+ * start of a generation.
+ *
+ * @param event - The event object containing generation configuration.
+ */
+export type StreamTextOnStartCallback<
+  TOOLS extends ToolSet = ToolSet,
+  OUTPUT extends Output = Output,
+> = (
+  event: OnStartEvent<TOOLS, OUTPUT, StreamTextIncludeSettings>,
+) => PromiseLike<void> | void;
+
+/**
+ * Callback that is set using the `experimental_onStepStart` option.
+ *
+ * Called when a step (LLM call) begins, before the provider is called.
+ * Each step represents a single LLM invocation. Multiple steps occur when
+ * using tool calls (the model may be called multiple times in a loop).
+ *
+ * @param event - The event object containing step configuration.
+ */
+export type StreamTextOnStepStartCallback<
+  TOOLS extends ToolSet = ToolSet,
+  OUTPUT extends Output = Output,
+> = (
+  event: OnStepStartEvent<TOOLS, OUTPUT, StreamTextIncludeSettings>,
+) => PromiseLike<void> | void;
+
+export type StreamTextOnToolCallStartCallback<TOOLS extends ToolSet = ToolSet> =
+  (event: OnToolCallStartEvent<TOOLS>) => PromiseLike<void> | void;
+
+export type StreamTextOnToolCallFinishCallback<
+  TOOLS extends ToolSet = ToolSet,
+> = (event: OnToolCallFinishEvent<TOOLS>) => PromiseLike<void> | void;
+
 /**
  * Generate a text and call tools for a given prompt using a language model.
  *
@@ -285,6 +322,10 @@ export function streamText<
   onFinish,
   onAbort,
   onStepFinish,
+  experimental_onStart: onStart,
+  experimental_onStepStart: onStepStart,
+  experimental_onToolCallStart: onToolCallStart,
+  experimental_onToolCallFinish: onToolCallFinish,
   experimental_context,
   experimental_include: include,
   _internal: { now = originalNow, generateId = originalGenerateId } = {},
@@ -421,6 +462,35 @@ export function streamText<
      */
     onStepFinish?: StreamTextOnStepFinishCallback<TOOLS>;
 
+    /**
+     * Callback that is called when the streamText operation begins,
+     * before any LLM calls are made.
+     */
+    experimental_onStart?: StreamTextOnStartCallback<NoInfer<TOOLS>, OUTPUT>;
+
+    /**
+     * Callback that is called when a step (LLM call) begins,
+     * before the provider is called.
+     */
+    experimental_onStepStart?: StreamTextOnStepStartCallback<
+      NoInfer<TOOLS>,
+      OUTPUT
+    >;
+
+    /**
+     * Callback that is called right before a tool's execute function runs.
+     */
+    experimental_onToolCallStart?: StreamTextOnToolCallStartCallback<
+      NoInfer<TOOLS>
+    >;
+
+    /**
+     * Callback that is called right after a tool's execute function completes (or errors).
+     */
+    experimental_onToolCallFinish?: StreamTextOnToolCallFinishCallback<
+      NoInfer<TOOLS>
+    >;
+
     /**
      * Context that is passed into tool execution.
      *
@@ -490,11 +560,18 @@ export function streamText<
     providerOptions,
     prepareStep,
     includeRawChunks,
+    timeout,
+    stopWhen,
+    originalAbortSignal: abortSignal,
     onChunk,
     onError,
     onFinish,
     onAbort,
     onStepFinish,
+    onStart,
+    onStepStart,
+    onToolCallStart,
+    onToolCallFinish,
     now,
     generateId,
     experimental_context,
@@ -663,11 +740,18 @@ class DefaultStreamTextResult<TOOLS extends ToolSet, OUTPUT extends Output>
     includeRawChunks,
     now,
     generateId,
+    timeout,
+    stopWhen,
+    originalAbortSignal,
     onChunk,
     onError,
     onFinish,
     onAbort,
     onStepFinish,
+    onStart,
+    onStepStart,
+    onToolCallStart,
+    onToolCallFinish,
     experimental_context,
     download,
     include,
@@ -697,6 +781,12 @@ class DefaultStreamTextResult<TOOLS extends ToolSet, OUTPUT extends Output>
     includeRawChunks: boolean;
     now: () => number;
     generateId: () => string;
+    timeout: TimeoutConfiguration | undefined;
+    stopWhen:
+      | StopCondition<NoInfer<TOOLS>>
+      | Array<StopCondition<NoInfer<TOOLS>>>
+      | undefined;
+    originalAbortSignal: AbortSignal | undefined;
     experimental_context: unknown;
     download: DownloadFunction | undefined;
     include: { requestBody?: boolean } | undefined;
@@ -707,6 +797,10 @@ class DefaultStreamTextResult<TOOLS extends ToolSet, OUTPUT extends Output>
     onFinish: undefined | StreamTextOnFinishCallback<TOOLS>;
     onAbort: undefined | StreamTextOnAbortCallback<TOOLS>;
     onStepFinish: undefined | StreamTextOnStepFinishCallback<TOOLS>;
+    onStart: undefined | StreamTextOnStartCallback<TOOLS, OUTPUT>;
+    onStepStart: undefined | StreamTextOnStepStartCallback<TOOLS, OUTPUT>;
+    onToolCallStart: undefined | StreamTextOnToolCallStartCallback<TOOLS>;
+    onToolCallFinish: undefined | StreamTextOnToolCallFinishCallback<TOOLS>;
   }) {
     this.outputSpecification = output;
     this.includeRawChunks = includeRawChunks;
@@ -918,14 +1012,8 @@ class DefaultStreamTextResult<TOOLS extends ToolSet, OUTPUT extends Output>
           // Add step information (after response messages are updated):
           const currentStepResult: StepResult<TOOLS> = new DefaultStepResult({
             stepNumber: recordedSteps.length,
-            model: {
-              provider: model.provider,
-              modelId: model.modelId,
-            },
-            functionId: telemetry?.functionId,
-            metadata: telemetry?.metadata as
-              | Record<string, unknown>
-              | undefined,
+            model: modelInfo,
+            ...callbackTelemetryProps,
             experimental_context,
             content: recordedContent,
             finishReason: part.finishReason,
@@ -944,8 +1032,8 @@ class DefaultStreamTextResult<TOOLS extends ToolSet, OUTPUT extends Output>
 
           logWarnings({
             warnings: recordedWarnings,
-            provider: model.provider,
-            model: model.modelId,
+            provider: modelInfo.provider,
+            model: modelInfo.modelId,
           });
 
           recordedSteps.push(currentStepResult);
@@ -1153,6 +1241,12 @@ class DefaultStreamTextResult<TOOLS extends ToolSet, OUTPUT extends Output>
 
     const self = this;
 
+    const modelInfo = { provider: model.provider, modelId: model.modelId };
+    const callbackTelemetryProps = {
+      functionId: telemetry?.functionId,
+      metadata: telemetry?.metadata as Record<string, unknown> | undefined,
+    };
+
     recordSpan({
       name: 'ai.streamText',
       attributes: selectTelemetryAttributes({
@@ -1177,6 +1271,38 @@ class DefaultStreamTextResult<TOOLS extends ToolSet, OUTPUT extends Output>
           messages,
         } as Prompt);
 
+        try {
+          await onStart?.({
+            model: modelInfo,
+            system,
+            prompt,
+            messages,
+            tools,
+            toolChoice,
+            activeTools,
+            maxOutputTokens: callSettings.maxOutputTokens,
+            temperature: callSettings.temperature,
+            topP: callSettings.topP,
+            topK: callSettings.topK,
+            presencePenalty: callSettings.presencePenalty,
+            frequencyPenalty: callSettings.frequencyPenalty,
+            stopSequences: callSettings.stopSequences,
+            seed: callSettings.seed,
+            maxRetries,
+            timeout,
+            headers,
+            providerOptions,
+            stopWhen,
+            output,
+            abortSignal: originalAbortSignal,
+            include,
+            ...callbackTelemetryProps,
+            experimental_context,
+          });
+        } catch (_ignored) {
+          // Errors in callbacks should not break the generation flow.
+        }
+
         const initialMessages = initialPrompt.messages;
         const initialResponseMessages: Array<ResponseMessage> = [];
 
@@ -1242,6 +1368,10 @@ class DefaultStreamTextResult<TOOLS extends ToolSet, OUTPUT extends Output>
                   messages: initialMessages,
                   abortSignal,
                   experimental_context,
+                  stepNumber: recordedSteps.length,
+                  model: modelInfo,
+                  onToolCallStart,
+                  onToolCallFinish,
                   onPreliminaryToolResult: result => {
                     toolExecutionStepStreamController?.enqueue(result);
                   },
@@ -1381,6 +1511,10 @@ class DefaultStreamTextResult<TOOLS extends ToolSet, OUTPUT extends Output>
             const stepModel = resolveLanguageModel(
               prepareStepResult?.model ?? model,
             );
+            const stepModelInfo = {
+              provider: stepModel.provider,
+              modelId: stepModel.modelId,
+            };
 
             const promptMessages = await convertToLanguageModelPrompt({
               prompt: {
@@ -1391,20 +1525,54 @@ class DefaultStreamTextResult<TOOLS extends ToolSet, OUTPUT extends Output>
               download,
             });
 
+            const stepActiveTools =
+              prepareStepResult?.activeTools ?? activeTools;
+
             const { toolChoice: stepToolChoice, tools: stepTools } =
               await prepareToolsAndToolChoice({
                 tools,
                 toolChoice: prepareStepResult?.toolChoice ?? toolChoice,
-                activeTools: prepareStepResult?.activeTools ?? activeTools,
+                activeTools: stepActiveTools,
               });
 
             experimental_context =
               prepareStepResult?.experimental_context ?? experimental_context;
 
+            const stepMessages =
+              prepareStepResult?.messages ?? stepInputMessages;
+
+            const stepSystem =
+              prepareStepResult?.system ?? initialPrompt.system;
+
             const stepProviderOptions = mergeObjects(
               providerOptions,
               prepareStepResult?.providerOptions,
             );
+
+            try {
+              await onStepStart?.({
+                stepNumber: recordedSteps.length,
+                model: stepModelInfo,
+                system: stepSystem,
+                messages: stepMessages,
+                tools,
+                toolChoice: stepToolChoice,
+                activeTools: stepActiveTools,
+                steps: [...recordedSteps],
+                providerOptions: stepProviderOptions,
+                timeout,
+                headers,
+                stopWhen,
+                output,
+                abortSignal: originalAbortSignal,
+                include,
+                ...callbackTelemetryProps,
+                experimental_context,
+              });
+            } catch (_ignored) {
+              // Errors in callbacks should not break the generation flow.
+            }
+
             const {
               result: { stream, response, request },
               doStreamSpan,
@@ -1483,6 +1651,10 @@ class DefaultStreamTextResult<TOOLS extends ToolSet, OUTPUT extends Output>
               abortSignal,
               experimental_context,
               generateId,
+              stepNumber: recordedSteps.length,
+              model: stepModelInfo,
+              onToolCallStart,
+              onToolCallFinish,
             });
 
             // Conditionally include request.body based on include settings.
@@ -1507,7 +1679,7 @@ class DefaultStreamTextResult<TOOLS extends ToolSet, OUTPUT extends Output>
               {
                 id: generateId(),
                 timestamp: new Date(),
-                modelId: model.modelId,
+                modelId: modelInfo.modelId,
               };
 
             // raw text as it comes from the provider. recorded for telemetry.

package/src/agent/tool-loop-agent-on-finish-callback.ts

@@ -1,31 +0,0 @@
-import { StepResult } from '../generate-text/step-result';
-import { ToolSet } from '../generate-text/tool-set';
-import { LanguageModelUsage } from '../types/usage';
-
-/**
- * Callback that is set using the `onFinish` option.
- *
- * @param event - The event that is passed to the callback.
- */
-export type ToolLoopAgentOnFinishCallback<TOOLS extends ToolSet = {}> = (
-  event: StepResult<TOOLS> & {
-    /**
-     * Details for all steps.
-     */
-    readonly steps: StepResult<TOOLS>[];
-
-    /**
-     * Total usage for all steps. This is the sum of the usage of all steps.
-     */
-    readonly totalUsage: LanguageModelUsage;
-
-    /**
-     * Context that is passed into tool execution.
-     *
-     * Experimental (can break in patch releases).
-     *
-     * @default undefined
-     */
-    experimental_context: unknown;
-  },
-) => PromiseLike<void> | void;

package/src/agent/tool-loop-agent-on-step-finish-callback.ts

@@ -1,11 +0,0 @@
-import { StepResult } from '../generate-text/step-result';
-import { ToolSet } from '../generate-text/tool-set';
-
-/**
- * Callback that is set using the `onStepFinish` option.
- *
- * @param stepResult - The result of the step.
- */
-export type ToolLoopAgentOnStepFinishCallback<TOOLS extends ToolSet = {}> = (
-  stepResult: StepResult<TOOLS>,
-) => Promise<void> | void;