ai 7.0.152 → 7.0.154

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

@@ -21,6 +21,7 @@ import {
   type ToolApprovalResponse,
   type ToolContent,
   type ToolSet,
+  type UserModelMessage,
 } from '@ai-sdk/provider-utils';
 import type { ServerResponse } from 'node:http';
 import { NoOutputGeneratedError, ToolChoiceViolationError } from '../error';
@@ -105,8 +106,10 @@ import type {
   GenerateTextEndEvent,
   GenerateTextOnStartCallback,
   GenerateTextOnStepEndCallback,
+  GenerateTextOnStepErrorCallback,
   GenerateTextOnStepFinishCallback,
   GenerateTextOnStepStartCallback,
+  GenerateTextStepStartEvent,
 } from './generate-text-events';
 import { invokeToolCallbacksFromStream } from './invoke-tool-callbacks-from-stream';
 import type {
@@ -133,6 +136,12 @@ import {
   type StepResult,
   type StepResultPerformance,
 } from './step-result';
+import {
+  startSteeringRun,
+  type Steering,
+  type SteeringNotDeliveredReason,
+  type SteeringRun,
+} from './steering';
 import {
   isStepCount,
   isStopConditionMet,
@@ -348,6 +357,7 @@ type StreamTextOptions<
  * @param headers - Additional HTTP headers to be sent with the request. Only applicable for HTTP-based providers.
  *
  * @param experimental_sandbox - The sandbox environment that is passed through to tool execution.
+ * @param experimental_steering - A steering object that adds user messages to the generation at the next step boundary.
  * @param runtimeContext - User-defined runtime context that flows through the entire generation lifecycle.
  * @param experimental_refineToolInput - Optional mapping of tool names to functions that refine parsed tool inputs before tools are executed and before outputs, callbacks, and telemetry are recorded.
  *
@@ -366,6 +376,7 @@ type StreamTextOptions<
  * @param onToolExecutionEnd - Callback invoked after each tool execution completes.
  * @param experimental_onToolCallFinish - Deprecated alias for `onToolExecutionEnd`.
  * @param onStepEnd - Callback that is called when each step (LLM call) ends, including intermediate steps.
+ * @param onStepError - Callback that is called when a step that started fails before it produces a step result, i.e. when the provider call throws or rejects, or when the model stream ends without output. A provider `error` chunk still ends the step with `onStepEnd`, and an abort or timeout ends it with `onAbort`.
  * @param onStepFinish - Deprecated alias for `onStepEnd`.
  * @param onEnd - Callback that is called when all steps are finished and the response is complete.
  * @param onFinish - Deprecated alias for `onEnd`.
@@ -380,7 +391,7 @@ export function streamText<
 >(
   options: StreamTextOptions<TOOLS, RUNTIME_CONTEXT, OUTPUT>,
 ): StreamTextResult<TOOLS, RUNTIME_CONTEXT, OUTPUT> {
-  return streamTextInternal<TOOLS, RUNTIME_CONTEXT, OUTPUT>(options);
+  return startStreamText<TOOLS, RUNTIME_CONTEXT, OUTPUT>(options);
 }
 
 /**
@@ -417,7 +428,7 @@ export function streamTextLowMemory<
     (telemetry?.isEnabled !== false && integrations.length > 0);
 
   return createSingleConsumerStreamTextResult(
-    streamTextInternal<TOOLS, RUNTIME_CONTEXT, OUTPUT>({
+    startStreamText<TOOLS, RUNTIME_CONTEXT, OUTPUT>({
       ...options,
       _internal: {
         ...options._internal,
@@ -427,440 +438,489 @@ export function streamTextLowMemory<
   );
 }
 
+function startStreamText<
+  TOOLS extends ToolSet,
+  RUNTIME_CONTEXT extends Context,
+  OUTPUT extends Output,
+>(
+  options: StreamTextOptions<TOOLS, RUNTIME_CONTEXT, OUTPUT>,
+): StreamTextResult<TOOLS, RUNTIME_CONTEXT, OUTPUT> {
+  const steeringRun = startSteeringRun(options.experimental_steering);
+
+  try {
+    return streamTextInternal<TOOLS, RUNTIME_CONTEXT, OUTPUT>(
+      options,
+      steeringRun,
+    );
+  } catch (error) {
+    // the call can fail before the stream starts, e.g. for invalid settings:
+    steeringRun?.end('error');
+    throw error;
+  }
+}
+
 function streamTextInternal<
   TOOLS extends ToolSet,
   RUNTIME_CONTEXT extends Context = Context,
   OUTPUT extends Output = Output<string, string, never>,
->({
-  model,
-  tools,
-  toolChoice,
-  instructions,
-  system,
-  prompt,
-  messages,
-  allowSystemInMessages,
-  maxRetries,
-  streamRetries,
-  abortSignal,
-  timeout,
-  headers,
-  stopWhen = isStepCount(1),
-  experimental_sandbox: sandbox,
-  output,
-  toolApproval,
-  experimental_toolCallers,
-  experimental_toolApprovalSecret,
-  experimental_telemetry,
-  telemetry = experimental_telemetry,
-  prepareStep,
-  providerOptions,
-  activeTools,
-  toolOrder,
-  toolCallConcurrency,
-  experimental_repairToolCall,
-  repairToolCall = experimental_repairToolCall,
-  experimental_refineToolInput: refineToolInput,
-  experimental_transform: transform,
-  experimental_download: download,
-  includeRawChunks,
-  onChunk,
-  onError: onErrorArg,
-  onFinish,
-  onEnd = onFinish,
-  onAbort,
-  onStepEnd,
-  onStepFinish,
-  onStart,
-  experimental_onStart,
-  onStepStart,
-  experimental_onStepStart,
-  onLanguageModelCallStart,
-  experimental_onLanguageModelCallStart,
-  onLanguageModelCallEnd,
-  experimental_onLanguageModelCallEnd,
-  onToolExecutionStart,
-  onToolExecutionEnd,
-  experimental_onToolCallStart,
-  experimental_onToolCallFinish,
-  runtimeContext = {} as RUNTIME_CONTEXT,
-  toolsContext = {} as InferToolSetContext<TOOLS>,
-  experimental_include,
-  include = experimental_include,
-  _internal: {
-    now = originalNow,
-    generateId = originalGenerateId,
-    generateCallId = originalGenerateCallId,
-    retention = { replay: true, collectContent: true },
-  } = {},
-  ...settings
-}: LanguageModelCallOptions &
-  RequestOptions<TOOLS> &
-  Prompt &
-  ToolsContextParameter<TOOLS> & {
-    /**
-     * The language model to use.
-     */
-    model: LanguageModel;
-
-    /**
-     * The tool choice strategy. Default: 'auto'.
-     */
-    toolChoice?: ToolChoice<TOOLS>;
-
-    /**
-     * Condition for stopping the generation when there are tool results in the last step.
-     * When the condition is an array, any of the conditions can be met to stop the generation.
-     *
-     * @default isStepCount(1)
-     */
-    stopWhen?: Arrayable<StopCondition<NoInfer<TOOLS>, RUNTIME_CONTEXT>>;
-
-    /**
-     * Optional telemetry configuration.
-     */
-    telemetry?: TelemetryOptions<RUNTIME_CONTEXT, NoInfer<TOOLS>>;
-
-    /**
-     * Optional telemetry configuration.
-     *
-     * @deprecated Use `telemetry` instead. This alias will be removed in a future major release.
-     */
-    experimental_telemetry?: TelemetryOptions<RUNTIME_CONTEXT, NoInfer<TOOLS>>;
-
-    /**
-     * Additional provider-specific options. They are passed through
-     * to the provider from the AI SDK and enable provider-specific
-     * functionality that can be fully encapsulated in the provider.
-     */
-    providerOptions?: ProviderOptions;
-
-    /**
-     * The sandbox environment that is passed through to tool execution.
-     */
-    experimental_sandbox?: SandboxSession;
-
-    /**
-     * Runtime context. Treat runtime context as immutable.
-     * If you need to mutate runtime context, update it in `prepareStep`.
-     */
-    runtimeContext?: RUNTIME_CONTEXT;
-
-    /**
-     * Limits the tools that are available for the model to call without
-     * changing the tool call and result types in the result.
-     */
-    activeTools?: ActiveTools<NoInfer<TOOLS>>;
-
-    /**
-     * Controls the order in which tools are sent to the provider.
-     *
-     * The list can be partial. Tools not listed in `toolOrder` are sent after
-     * the listed tools, sorted alphabetically. This can improve provider-side
-     * caching by keeping tool definitions in a stable order.
-     */
-    toolOrder?: ToolOrder<NoInfer<TOOLS>>;
-
-    /**
-     * Maximum number of tool calls that may execute concurrently within a step.
-     *
-     * Set to `1` to execute tool calls sequentially in the order they were
-     * generated. By default, all tool calls execute concurrently.
-     */
-    toolCallConcurrency?: number;
-
-    /**
-     * Optional specification for parsing structured outputs from the LLM response.
-     */
-    output?: OUTPUT;
-
-    /**
-     * Optional tool approval configuration.
-     *
-     * This configuration takes precedence over tool-defined approval settings.
-     */
-    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
-     * the approval is replayed, preventing client-forged approvals.
-     */
-    experimental_toolApprovalSecret?: string | Uint8Array;
-
-    /**
-     * Optional function that you can use to provide different settings for a step.
-     *
-     * @param options - The options for the step.
-     * @param options.steps - The steps that have been executed so far.
-     * @param options.stepNumber - The number of the step that is being executed.
-     * @param options.model - The model that is being used.
-     *
-     * @returns An object that contains the settings for the step.
-     * If you return undefined (or for undefined settings), the settings from the outer level will be used.
-     */
-    prepareStep?: PrepareStepFunction<NoInfer<TOOLS>, RUNTIME_CONTEXT>;
-
-    /**
-     * A function that attempts to repair a tool call that failed to parse.
-     */
-    repairToolCall?: ToolCallRepairFunction<TOOLS>;
-
-    /**
-     * A function that attempts to repair a tool call that failed to parse.
-     *
-     * @deprecated Use `repairToolCall` instead.
-     */
-    experimental_repairToolCall?: ToolCallRepairFunction<TOOLS>;
-
-    /**
-     * Optional mapping of tool names to functions that refine parsed tool inputs.
-     *
-     * The refined input must have the same type shape as the tool input. Refined
-     * inputs are used for tool execution, stream parts, callbacks, and telemetry.
-     */
-    experimental_refineToolInput?: ToolInputRefinement<NoInfer<TOOLS>>;
-
-    /**
-     * Optional stream transformations.
-     * They are applied in the order they are provided.
-     * The stream transformations must maintain the stream structure for streamText to work correctly.
-     */
-    experimental_transform?: Arrayable<StreamTextTransform<TOOLS>>;
-
-    /**
-     * Custom download function to use for URLs.
-     *
-     * By default, files are downloaded if the model does not support the URL for the given media type.
-     */
-    experimental_download?: DownloadFunction | undefined;
-
-    /**
-     * Whether to include raw chunks from the provider in the stream.
-     * When enabled, you will receive raw chunks with type 'raw' that contain the unprocessed data from the provider.
-     * This allows access to cutting-edge provider features not yet wrapped by the AI SDK.
-     * Defaults to false.
-     *
-     * @deprecated Use `include.rawChunks` instead.
-     */
-    includeRawChunks?: boolean;
-
-    /**
-     * Callback that is called for each chunk of the stream.
-     * The stream processing will pause until the callback promise is resolved.
-     */
-    onChunk?: StreamTextOnChunkCallback<TOOLS>;
-
-    /**
-     * Callback that is invoked when an error occurs during streaming.
-     * You can use it to log errors.
-     * Return `{ retry: true }` to retry the current model step after a provider
-     * error is received from the response stream when `streamRetries` is
-     * explicitly configured.
-     * The stream processing will pause until the callback promise is resolved.
-     */
-    onError?:
-      | StreamTextOnErrorCallback
-      | StreamTextOnErrorRetryCallback
-      | StreamTextOnErrorHandler;
-
-    /**
-     * Maximum number of automatic retries for provider errors received after
-     * response streaming has started. Each retry reruns only the current model
-     * step. Completed earlier steps and their tool results are preserved.
-     *
-     * Partial output from a failed attempt that was already emitted cannot be
-     * retracted and remains in consumer-facing streams. It is excluded from
-     * the recovered step result, structured output parsing, response messages,
-     * and subsequent model steps.
-     *
-     * Set to `0` to disable automatic retries while allowing `onError` to
-     * request one retry. When automatic retries are configured, `onError` can
-     * request at most one additional retry after they are exhausted. Omit this
-     * option to disable all stream retry behavior and preserve incremental tool
-     * streaming for existing `onError` observers.
-     *
-     * @default 0 (stream retry behavior disabled when omitted)
-     */
-    streamRetries?: number;
-
-    /**
-     * Callback that is called when the LLM response and all request tool executions
-     * (for tools that have an `execute` function) are finished.
-     *
-     * The usage is the combined usage of all steps.
-     */
-    onEnd?: StreamTextOnEndCallback<
-      NoInfer<TOOLS>,
-      NoInfer<RUNTIME_CONTEXT>,
-      NoInfer<OUTPUT>
-    >;
-
-    /**
-     * Callback that is called when the LLM response and all request tool executions
-     * (for tools that have an `execute` function) are finished.
-     *
-     * The usage is the combined usage of all steps.
-     *
-     * @deprecated Use `onEnd` instead.
-     */
-    onFinish?: StreamTextOnEndCallback<
-      NoInfer<TOOLS>,
-      NoInfer<RUNTIME_CONTEXT>,
-      NoInfer<OUTPUT>
-    >;
-
-    onAbort?: StreamTextOnAbortCallback<
-      NoInfer<TOOLS>,
-      NoInfer<RUNTIME_CONTEXT>
-    >;
-
-    /**
-     * Callback that is called when each step (LLM call) ends, including intermediate steps.
-     */
-    onStepEnd?: GenerateTextOnStepEndCallback<
-      NoInfer<TOOLS>,
-      NoInfer<RUNTIME_CONTEXT>
-    >;
-
-    /**
-     * Callback that is called when each step (LLM call) ends, including intermediate steps.
-     *
-     * @deprecated Use `onStepEnd` instead.
-     */
-    onStepFinish?: GenerateTextOnStepFinishCallback<
-      NoInfer<TOOLS>,
-      NoInfer<RUNTIME_CONTEXT>
-    >;
-
-    /**
-     * Callback that is called when the streamText operation begins,
-     * before any LLM calls are made.
-     */
-    onStart?: GenerateTextOnStartCallback<
-      NoInfer<TOOLS>,
-      NoInfer<RUNTIME_CONTEXT>,
-      NoInfer<OUTPUT>
-    >;
-
-    /**
-     * Callback that is called when the streamText operation begins,
-     * before any LLM calls are made.
-     *
-     * @deprecated Use `onStart` instead.
-     */
-    experimental_onStart?: GenerateTextOnStartCallback<
-      NoInfer<TOOLS>,
-      NoInfer<RUNTIME_CONTEXT>,
-      NoInfer<OUTPUT>
-    >;
-
-    /**
-     * Callback that is called when a step (LLM call) begins,
-     * before the provider is called.
-     */
-    onStepStart?: GenerateTextOnStepStartCallback<
-      NoInfer<TOOLS>,
-      NoInfer<RUNTIME_CONTEXT>,
-      NoInfer<OUTPUT>
-    >;
-
-    /**
-     * Callback that is called when a step (LLM call) begins,
-     * before the provider is called.
-     *
-     * @deprecated Use `onStepStart` instead.
-     */
-    experimental_onStepStart?: GenerateTextOnStepStartCallback<
-      NoInfer<TOOLS>,
-      NoInfer<RUNTIME_CONTEXT>,
-      NoInfer<OUTPUT>
-    >;
-
-    /**
-     * Callback that is called immediately before the provider model call begins.
-     */
-    onLanguageModelCallStart?: OnLanguageModelCallStartCallback;
-
-    /**
-     * Callback that is called immediately before the provider model call begins.
-     *
-     * @deprecated Use `onLanguageModelCallStart` instead.
-     */
-    experimental_onLanguageModelCallStart?: OnLanguageModelCallStartCallback;
-
-    /**
-     * Callback that is called after the model response has been normalized and parsed,
-     * but before any client-side tool execution begins.
-     */
-    onLanguageModelCallEnd?: OnLanguageModelCallEndCallback<NoInfer<TOOLS>>;
-
-    /**
-     * Callback that is called after the model response has been normalized and parsed,
-     * but before any client-side tool execution begins.
-     *
-     * @deprecated Use `onLanguageModelCallEnd` instead.
-     */
-    experimental_onLanguageModelCallEnd?: OnLanguageModelCallEndCallback<
-      NoInfer<TOOLS>
-    >;
-
-    /**
-     * Callback that is called right before a tool's execute function runs.
-     */
-    onToolExecutionStart?: OnToolExecutionStartCallback<NoInfer<TOOLS>>;
-
-    /**
-     * Callback that is called right before a tool's execute function runs.
-     *
-     * @deprecated Use `onToolExecutionStart` instead.
-     */
-    experimental_onToolCallStart?: OnToolExecutionStartCallback<NoInfer<TOOLS>>;
-
-    /**
-     * Callback that is called right after a tool's execute function completes (or errors).
-     */
-    onToolExecutionEnd?: OnToolExecutionEndCallback<NoInfer<TOOLS>>;
-
-    /**
-     * Callback that is called right after a tool's execute function completes (or errors).
-     *
-     * @deprecated Use `onToolExecutionEnd` instead.
-     */
-    experimental_onToolCallFinish?: OnToolExecutionEndCallback<NoInfer<TOOLS>>;
-
-    /**
-     * Settings for controlling what data is included in step results.
-     * Disabling inclusion can help reduce memory usage when processing
-     * large payloads like images.
-     *
-     * By default, request bodies and request messages are excluded.
-     */
-    include?: StreamTextInclude;
-
-    /**
-     * Settings for controlling what data is included in step results.
-     *
-     * @deprecated Use `include` instead.
-     */
-    experimental_include?: StreamTextInclude;
-
-    /**
-     * Internal. For test use only. May change without notice.
-     */
-    _internal?: {
-      now?: () => number;
-      generateId?: IdGenerator;
-      generateCallId?: IdGenerator;
-      /** Internal policy used by the streaming-only facade. */
-      retention?: StreamTextRetention;
-    };
-  }): StreamTextResult<TOOLS, RUNTIME_CONTEXT, OUTPUT> {
+>(
+  {
+    model,
+    tools,
+    toolChoice,
+    instructions,
+    system,
+    prompt,
+    messages,
+    allowSystemInMessages,
+    maxRetries,
+    streamRetries,
+    abortSignal,
+    timeout,
+    headers,
+    stopWhen = isStepCount(1),
+    experimental_sandbox: sandbox,
+    output,
+    toolApproval,
+    experimental_toolCallers,
+    experimental_toolApprovalSecret,
+    experimental_telemetry,
+    telemetry = experimental_telemetry,
+    prepareStep,
+    providerOptions,
+    activeTools,
+    toolOrder,
+    toolCallConcurrency,
+    experimental_repairToolCall,
+    repairToolCall = experimental_repairToolCall,
+    experimental_refineToolInput: refineToolInput,
+    experimental_transform: transform,
+    experimental_download: download,
+    includeRawChunks,
+    onChunk,
+    onError: onErrorArg,
+    onFinish,
+    onEnd = onFinish,
+    onAbort,
+    onStepEnd,
+    onStepError,
+    onStepFinish,
+    onStart,
+    experimental_onStart,
+    onStepStart,
+    experimental_onStepStart,
+    onLanguageModelCallStart,
+    experimental_onLanguageModelCallStart,
+    onLanguageModelCallEnd,
+    experimental_onLanguageModelCallEnd,
+    onToolExecutionStart,
+    onToolExecutionEnd,
+    experimental_onToolCallStart,
+    experimental_onToolCallFinish,
+    runtimeContext = {} as RUNTIME_CONTEXT,
+    toolsContext = {} as InferToolSetContext<TOOLS>,
+    experimental_include,
+    include = experimental_include,
+    _internal: {
+      now = originalNow,
+      generateId = originalGenerateId,
+      generateCallId = originalGenerateCallId,
+      retention = { replay: true, collectContent: true },
+    } = {},
+    ...settings
+  }: LanguageModelCallOptions &
+    RequestOptions<TOOLS> &
+    Prompt &
+    ToolsContextParameter<TOOLS> & {
+      /**
+       * The language model to use.
+       */
+      model: LanguageModel;
+
+      /**
+       * The tool choice strategy. Default: 'auto'.
+       */
+      toolChoice?: ToolChoice<TOOLS>;
+
+      /**
+       * Condition for stopping the generation when there are tool results in the last step.
+       * When the condition is an array, any of the conditions can be met to stop the generation.
+       *
+       * @default isStepCount(1)
+       */
+      stopWhen?: Arrayable<StopCondition<NoInfer<TOOLS>, RUNTIME_CONTEXT>>;
+
+      /**
+       * Optional telemetry configuration.
+       */
+      telemetry?: TelemetryOptions<RUNTIME_CONTEXT, NoInfer<TOOLS>>;
+
+      /**
+       * Optional telemetry configuration.
+       *
+       * @deprecated Use `telemetry` instead. This alias will be removed in a future major release.
+       */
+      experimental_telemetry?: TelemetryOptions<
+        RUNTIME_CONTEXT,
+        NoInfer<TOOLS>
+      >;
+
+      /**
+       * Additional provider-specific options. They are passed through
+       * to the provider from the AI SDK and enable provider-specific
+       * functionality that can be fully encapsulated in the provider.
+       */
+      providerOptions?: ProviderOptions;
+
+      /**
+       * The sandbox environment that is passed through to tool execution.
+       */
+      experimental_sandbox?: SandboxSession;
+
+      /**
+       * A steering object created with `experimental_createSteering()`.
+       * Messages sent with it are added to the generation at the next step
+       * boundary.
+       */
+      experimental_steering?: Steering;
+
+      /**
+       * Runtime context. Treat runtime context as immutable.
+       * If you need to mutate runtime context, update it in `prepareStep`.
+       */
+      runtimeContext?: RUNTIME_CONTEXT;
+
+      /**
+       * Limits the tools that are available for the model to call without
+       * changing the tool call and result types in the result.
+       */
+      activeTools?: ActiveTools<NoInfer<TOOLS>>;
+
+      /**
+       * Controls the order in which tools are sent to the provider.
+       *
+       * The list can be partial. Tools not listed in `toolOrder` are sent after
+       * the listed tools, sorted alphabetically. This can improve provider-side
+       * caching by keeping tool definitions in a stable order.
+       */
+      toolOrder?: ToolOrder<NoInfer<TOOLS>>;
+
+      /**
+       * Maximum number of tool calls that may execute concurrently within a step.
+       *
+       * Set to `1` to execute tool calls sequentially in the order they were
+       * generated. By default, all tool calls execute concurrently.
+       */
+      toolCallConcurrency?: number;
+
+      /**
+       * Optional specification for parsing structured outputs from the LLM response.
+       */
+      output?: OUTPUT;
+
+      /**
+       * Optional tool approval configuration.
+       *
+       * This configuration takes precedence over tool-defined approval settings.
+       */
+      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
+       * the approval is replayed, preventing client-forged approvals.
+       */
+      experimental_toolApprovalSecret?: string | Uint8Array;
+
+      /**
+       * Optional function that you can use to provide different settings for a step.
+       *
+       * @param options - The options for the step.
+       * @param options.steps - The steps that have been executed so far.
+       * @param options.stepNumber - The number of the step that is being executed.
+       * @param options.model - The model that is being used.
+       *
+       * @returns An object that contains the settings for the step.
+       * If you return undefined (or for undefined settings), the settings from the outer level will be used.
+       */
+      prepareStep?: PrepareStepFunction<NoInfer<TOOLS>, RUNTIME_CONTEXT>;
+
+      /**
+       * A function that attempts to repair a tool call that failed to parse.
+       */
+      repairToolCall?: ToolCallRepairFunction<TOOLS>;
+
+      /**
+       * A function that attempts to repair a tool call that failed to parse.
+       *
+       * @deprecated Use `repairToolCall` instead.
+       */
+      experimental_repairToolCall?: ToolCallRepairFunction<TOOLS>;
+
+      /**
+       * Optional mapping of tool names to functions that refine parsed tool inputs.
+       *
+       * The refined input must have the same type shape as the tool input. Refined
+       * inputs are used for tool execution, stream parts, callbacks, and telemetry.
+       */
+      experimental_refineToolInput?: ToolInputRefinement<NoInfer<TOOLS>>;
+
+      /**
+       * Optional stream transformations.
+       * They are applied in the order they are provided.
+       * The stream transformations must maintain the stream structure for streamText to work correctly.
+       */
+      experimental_transform?: Arrayable<StreamTextTransform<TOOLS>>;
+
+      /**
+       * Custom download function to use for URLs.
+       *
+       * By default, files are downloaded if the model does not support the URL for the given media type.
+       */
+      experimental_download?: DownloadFunction | undefined;
+
+      /**
+       * Whether to include raw chunks from the provider in the stream.
+       * When enabled, you will receive raw chunks with type 'raw' that contain the unprocessed data from the provider.
+       * This allows access to cutting-edge provider features not yet wrapped by the AI SDK.
+       * Defaults to false.
+       *
+       * @deprecated Use `include.rawChunks` instead.
+       */
+      includeRawChunks?: boolean;
+
+      /**
+       * Callback that is called for each chunk of the stream.
+       * The stream processing will pause until the callback promise is resolved.
+       */
+      onChunk?: StreamTextOnChunkCallback<TOOLS>;
+
+      /**
+       * Callback that is invoked when an error occurs during streaming.
+       * You can use it to log errors.
+       * Return `{ retry: true }` to retry the current model step after a provider
+       * error is received from the response stream when `streamRetries` is
+       * explicitly configured.
+       * The stream processing will pause until the callback promise is resolved.
+       */
+      onError?:
+        | StreamTextOnErrorCallback
+        | StreamTextOnErrorRetryCallback
+        | StreamTextOnErrorHandler;
+
+      /**
+       * Maximum number of automatic retries for provider errors received after
+       * response streaming has started. Each retry reruns only the current model
+       * step. Completed earlier steps and their tool results are preserved.
+       *
+       * Partial output from a failed attempt that was already emitted cannot be
+       * retracted and remains in consumer-facing streams. It is excluded from
+       * the recovered step result, structured output parsing, response messages,
+       * and subsequent model steps.
+       *
+       * Set to `0` to disable automatic retries while allowing `onError` to
+       * request one retry. When automatic retries are configured, `onError` can
+       * request at most one additional retry after they are exhausted. Omit this
+       * option to disable all stream retry behavior and preserve incremental tool
+       * streaming for existing `onError` observers.
+       *
+       * @default 0 (stream retry behavior disabled when omitted)
+       */
+      streamRetries?: number;
+
+      /**
+       * Callback that is called when the LLM response and all request tool executions
+       * (for tools that have an `execute` function) are finished.
+       *
+       * The usage is the combined usage of all steps.
+       */
+      onEnd?: StreamTextOnEndCallback<
+        NoInfer<TOOLS>,
+        NoInfer<RUNTIME_CONTEXT>,
+        NoInfer<OUTPUT>
+      >;
+
+      /**
+       * Callback that is called when the LLM response and all request tool executions
+       * (for tools that have an `execute` function) are finished.
+       *
+       * The usage is the combined usage of all steps.
+       *
+       * @deprecated Use `onEnd` instead.
+       */
+      onFinish?: StreamTextOnEndCallback<
+        NoInfer<TOOLS>,
+        NoInfer<RUNTIME_CONTEXT>,
+        NoInfer<OUTPUT>
+      >;
+
+      onAbort?: StreamTextOnAbortCallback<
+        NoInfer<TOOLS>,
+        NoInfer<RUNTIME_CONTEXT>
+      >;
+
+      /**
+       * Callback that is called when each step (LLM call) ends, including intermediate steps.
+       */
+      onStepEnd?: GenerateTextOnStepEndCallback<
+        NoInfer<TOOLS>,
+        NoInfer<RUNTIME_CONTEXT>
+      >;
+
+      /**
+       * Callback that is called when a step that started fails before it
+       * produces a step result. `onStepEnd` is not called for such a step.
+       */
+      onStepError?: GenerateTextOnStepErrorCallback<
+        NoInfer<TOOLS>,
+        NoInfer<RUNTIME_CONTEXT>,
+        NoInfer<OUTPUT>
+      >;
+
+      /**
+       * Callback that is called when each step (LLM call) ends, including intermediate steps.
+       *
+       * @deprecated Use `onStepEnd` instead.
+       */
+      onStepFinish?: GenerateTextOnStepFinishCallback<
+        NoInfer<TOOLS>,
+        NoInfer<RUNTIME_CONTEXT>
+      >;
+
+      /**
+       * Callback that is called when the streamText operation begins,
+       * before any LLM calls are made.
+       */
+      onStart?: GenerateTextOnStartCallback<
+        NoInfer<TOOLS>,
+        NoInfer<RUNTIME_CONTEXT>,
+        NoInfer<OUTPUT>
+      >;
+
+      /**
+       * Callback that is called when the streamText operation begins,
+       * before any LLM calls are made.
+       *
+       * @deprecated Use `onStart` instead.
+       */
+      experimental_onStart?: GenerateTextOnStartCallback<
+        NoInfer<TOOLS>,
+        NoInfer<RUNTIME_CONTEXT>,
+        NoInfer<OUTPUT>
+      >;
+
+      /**
+       * Callback that is called when a step (LLM call) begins,
+       * before the provider is called.
+       */
+      onStepStart?: GenerateTextOnStepStartCallback<
+        NoInfer<TOOLS>,
+        NoInfer<RUNTIME_CONTEXT>,
+        NoInfer<OUTPUT>
+      >;
+
+      /**
+       * Callback that is called when a step (LLM call) begins,
+       * before the provider is called.
+       *
+       * @deprecated Use `onStepStart` instead.
+       */
+      experimental_onStepStart?: GenerateTextOnStepStartCallback<
+        NoInfer<TOOLS>,
+        NoInfer<RUNTIME_CONTEXT>,
+        NoInfer<OUTPUT>
+      >;
+
+      /**
+       * Callback that is called immediately before the provider model call begins.
+       */
+      onLanguageModelCallStart?: OnLanguageModelCallStartCallback;
+
+      /**
+       * Callback that is called immediately before the provider model call begins.
+       *
+       * @deprecated Use `onLanguageModelCallStart` instead.
+       */
+      experimental_onLanguageModelCallStart?: OnLanguageModelCallStartCallback;
+
+      /**
+       * Callback that is called after the model response has been normalized and parsed,
+       * but before any client-side tool execution begins.
+       */
+      onLanguageModelCallEnd?: OnLanguageModelCallEndCallback<NoInfer<TOOLS>>;
+
+      /**
+       * Callback that is called after the model response has been normalized and parsed,
+       * but before any client-side tool execution begins.
+       *
+       * @deprecated Use `onLanguageModelCallEnd` instead.
+       */
+      experimental_onLanguageModelCallEnd?: OnLanguageModelCallEndCallback<
+        NoInfer<TOOLS>
+      >;
+
+      /**
+       * Callback that is called right before a tool's execute function runs.
+       */
+      onToolExecutionStart?: OnToolExecutionStartCallback<NoInfer<TOOLS>>;
+
+      /**
+       * Callback that is called right before a tool's execute function runs.
+       *
+       * @deprecated Use `onToolExecutionStart` instead.
+       */
+      experimental_onToolCallStart?: OnToolExecutionStartCallback<
+        NoInfer<TOOLS>
+      >;
+
+      /**
+       * Callback that is called right after a tool's execute function completes (or errors).
+       */
+      onToolExecutionEnd?: OnToolExecutionEndCallback<NoInfer<TOOLS>>;
+
+      /**
+       * Callback that is called right after a tool's execute function completes (or errors).
+       *
+       * @deprecated Use `onToolExecutionEnd` instead.
+       */
+      experimental_onToolCallFinish?: OnToolExecutionEndCallback<
+        NoInfer<TOOLS>
+      >;
+
+      /**
+       * Settings for controlling what data is included in step results.
+       * Disabling inclusion can help reduce memory usage when processing
+       * large payloads like images.
+       *
+       * By default, request bodies and request messages are excluded.
+       */
+      include?: StreamTextInclude;
+
+      /**
+       * Settings for controlling what data is included in step results.
+       *
+       * @deprecated Use `include` instead.
+       */
+      experimental_include?: StreamTextInclude;
+
+      /**
+       * Internal. For test use only. May change without notice.
+       */
+      _internal?: {
+        now?: () => number;
+        generateId?: IdGenerator;
+        generateCallId?: IdGenerator;
+        /** Internal policy used by the streaming-only facade. */
+        retention?: StreamTextRetention;
+      };
+    },
+  steeringRun: SteeringRun | undefined,
+): StreamTextResult<TOOLS, RUNTIME_CONTEXT, OUTPUT> {
   const resolvedToolCallConcurrency =
     prepareToolCallConcurrency(toolCallConcurrency);
   const totalTimeoutMs = getTotalTimeoutMs(timeout);
@@ -916,6 +976,7 @@ function streamTextInternal<
     messages,
     allowSystemInMessages,
     experimental_sandbox: sandbox,
+    steeringRun,
     tools,
     toolsContext,
     runtimeContext,
@@ -940,6 +1001,7 @@ function streamTextInternal<
     onEnd,
     onAbort,
     onStepFinish: resolvedOnStepEnd,
+    onStepError,
     onStart: resolvedOnStart,
     onStepStart: resolvedOnStepStart,
     onLanguageModelCallStart: resolvedOnLanguageModelCallStart,
@@ -1316,6 +1378,7 @@ class DefaultStreamTextResult<
     messages,
     allowSystemInMessages,
     experimental_sandbox: sandbox,
+    steeringRun,
     tools,
     toolChoice,
     transforms,
@@ -1341,6 +1404,7 @@ class DefaultStreamTextResult<
     onEnd,
     onAbort,
     onStepFinish,
+    onStepError,
     onStart,
     onStepStart,
     onLanguageModelCallStart,
@@ -1374,6 +1438,7 @@ class DefaultStreamTextResult<
     messages: Prompt['messages'];
     allowSystemInMessages: Prompt['allowSystemInMessages'];
     experimental_sandbox: SandboxSession | undefined;
+    steeringRun: SteeringRun | undefined;
     tools: TOOLS | undefined;
     toolChoice: ToolChoice<TOOLS> | undefined;
     transforms: Array<StreamTextTransform<TOOLS>>;
@@ -1420,6 +1485,13 @@ class DefaultStreamTextResult<
           NoInfer<TOOLS>,
           NoInfer<RUNTIME_CONTEXT>
         >;
+    onStepError:
+      | undefined
+      | GenerateTextOnStepErrorCallback<
+          NoInfer<TOOLS>,
+          NoInfer<RUNTIME_CONTEXT>,
+          NoInfer<OUTPUT>
+        >;
     onStart:
       | undefined
       | GenerateTextOnStartCallback<
@@ -1479,6 +1551,7 @@ class DefaultStreamTextResult<
     const initialResponseMessages: Array<ResponseMessage> = [];
     let stepMessagesForNextStep: Array<ModelMessage> | undefined;
     let currentStepMessages: Array<ModelMessage> = [];
+    let currentStepSteeringMessages: Array<UserModelMessage> = [];
     let isAborted = false;
     let currentStepModel = model;
 
@@ -1537,6 +1610,30 @@ class DefaultStreamTextResult<
     let recordedNoOutputError: NoOutputGeneratedError | undefined;
     const errorsHandledForStreamRetry = new Set<unknown>();
 
+    // the step that has started but not ended and its last error that was not
+    // handled by a stream retry, reported to onStepError when the stream ends
+    // before the step produces a result:
+    let openStep:
+      | {
+          event: GenerateTextStepStartEvent<TOOLS, RUNTIME_CONTEXT, OUTPUT>;
+          error?: unknown;
+        }
+      | undefined;
+
+    const notifyStepError = async (error: unknown) => {
+      if (openStep == null || abortSignal?.aborted) {
+        return;
+      }
+
+      const { event } = openStep;
+      openStep = undefined;
+
+      await notify({
+        event: { ...event, error },
+        callbacks: [onStepError, telemetryDispatcher.onStepError],
+      });
+    };
+
     const eventProcessor = new TransformStream<
       InternalEnrichedStreamPart<TOOLS, InferPartialOutput<OUTPUT>>,
       EnrichedStreamPart<TOOLS, InferPartialOutput<OUTPUT>>
@@ -1576,6 +1673,9 @@ class DefaultStreamTextResult<
           if (callbacksHandledForStreamRetry) {
             errorsHandledForStreamRetry.delete(part.error);
           } else {
+            if (openStep != null) {
+              openStep.error = error;
+            }
             await notify({
               event: { error },
               callbacks: async event => {
@@ -1757,8 +1857,11 @@ class DefaultStreamTextResult<
                 messages: cloneModelMessages(stepResponseMessages),
               },
               providerMetadata: part.providerMetadata,
+              steeringMessages: currentStepSteeringMessages,
             });
 
+          openStep = undefined;
+
           await notify({
             event: currentStepResult,
             callbacks: [onStepFinish, telemetryDispatcher.onStepEnd],
@@ -1789,16 +1892,36 @@ class DefaultStreamTextResult<
       },
 
       async flush(controller) {
+        // steering messages that are still waiting cannot be delivered anymore:
+        steeringRun?.end(
+          recordedSteps.length === 0 || recordedNoOutputError != null
+            ? 'error'
+            : 'finished',
+        );
+
         try {
+          const noOutputError = new NoOutputGeneratedError({
+            message: 'No output generated. Check the stream for errors.',
+          });
+
+          // a step that started without producing a result has failed:
+          await notifyStepError(openStep?.error ?? noOutputError);
+
           // reject when no output was generated or an incomplete model stream
           // ended a continuation step:
           if (recordedSteps.length === 0 || recordedNoOutputError != null) {
             const error = abortSignal?.aborted
               ? abortSignal.reason
-              : (recordedNoOutputError ??
-                new NoOutputGeneratedError({
-                  message: 'No output generated. Check the stream for errors.',
-                }));
+              : (recordedNoOutputError ?? noOutputError);
+
+            // an incomplete model stream is not reported to telemetry by the
+            // stream itself, so report it here to close open spans:
+            if (recordedNoOutputError != null && !abortSignal?.aborted) {
+              await telemetryDispatcher.onError?.({
+                callId,
+                error: recordedNoOutputError,
+              });
+            }
 
             self.rejectResultPromises(error);
 
@@ -1954,6 +2077,7 @@ class DefaultStreamTextResult<
         async function abort() {
           isAborted = true;
           removeAbortListener();
+          steeringRun?.end('aborted');
 
           await notify({
             event: {
@@ -1997,6 +2121,9 @@ class DefaultStreamTextResult<
           if (isAbortError(error) && abortSignal?.aborted) {
             await abort();
           } else {
+            steeringRun?.end('error');
+            // an erroring stream skips the event processor flush:
+            await notifyStepError(wrapGatewayError(error));
             await telemetryDispatcher.onError?.({ callId, error });
             controller.error(error);
           }
@@ -2005,6 +2132,7 @@ class DefaultStreamTextResult<
 
       cancel(reason) {
         removeAbortListener();
+        steeringRun?.end('aborted');
         return reader.cancel(reason);
       },
     });
@@ -2430,9 +2558,14 @@ class DefaultStreamTextResult<
             ...initialResponseMessages,
             ...responseMessagesFromPreviousSteps,
           ];
-          const stepInputMessages = stepMessagesForNextStep ?? [
-            ...initialMessages,
-            ...initialResponseMessages,
+          const steeringMessages = steeringRun?.takeMessages() ?? [];
+
+          const stepInputMessages = [
+            ...(stepMessagesForNextStep ?? [
+              ...initialMessages,
+              ...initialResponseMessages,
+            ]),
+            ...steeringMessages,
           ];
 
           const prepareStepResult = await prepareStep?.({
@@ -2444,6 +2577,9 @@ class DefaultStreamTextResult<
             messages: stepInputMessages,
             initialMessages,
             responseMessages: accumulatedResponseMessages,
+            ...(steeringMessages.length > 0
+              ? { experimental_steeringMessages: steeringMessages }
+              : {}),
             toolsContext,
             runtimeContext,
             experimental_sandbox: sandbox,
@@ -2503,6 +2639,14 @@ class DefaultStreamTextResult<
             toolCallerMessages,
           });
           currentStepMessages = stepMessages;
+
+          // steering messages are delivered when they are in the messages that
+          // are sent to the model after prepareStep:
+          currentStepSteeringMessages =
+            steeringRun?.resolveTakenMessages({
+              stepNumber: currentStep,
+              sentMessages: stepMessages,
+            }) ?? [];
           const stepInstructions =
             prepareStepResult?.instructions ??
             prepareStepResult?.system ??
@@ -2566,30 +2710,33 @@ class DefaultStreamTextResult<
                     }
                     hasNotifiedStepStart = true;
 
+                    const stepStartEvent = {
+                      callId,
+                      provider: stepModel.provider,
+                      modelId: stepModel.modelId,
+                      stepNumber: recordedSteps.length,
+                      instructions: stepInstructions,
+                      messages: stepMessages,
+                      tools,
+                      toolChoice: prepareStepResult?.toolChoice ?? toolChoice,
+                      activeTools:
+                        prepareStepResult?.activeTools ?? activeTools,
+                      toolOrder: stepToolOrder,
+                      steps: [...recordedSteps],
+                      providerOptions: stepProviderOptions,
+                      runtimeContext,
+                      toolsContext,
+                      output,
+                      promptMessages,
+                      stepTools,
+                      stepToolChoice,
+                    };
                     await notify({
-                      event: {
-                        callId,
-                        provider: stepModel.provider,
-                        modelId: stepModel.modelId,
-                        stepNumber: recordedSteps.length,
-                        instructions: stepInstructions,
-                        messages: stepMessages,
-                        tools,
-                        toolChoice: prepareStepResult?.toolChoice ?? toolChoice,
-                        activeTools:
-                          prepareStepResult?.activeTools ?? activeTools,
-                        toolOrder: stepToolOrder,
-                        steps: [...recordedSteps],
-                        providerOptions: stepProviderOptions,
-                        runtimeContext,
-                        toolsContext,
-                        output,
-                        promptMessages,
-                        stepTools,
-                        stepToolChoice,
-                      },
+                      event: stepStartEvent,
                       callbacks: [onStepStart, telemetryDispatcher.onStepStart],
                     });
+
+                    openStep = { event: stepStartEvent };
                   },
                   _internal: {
                     now,
@@ -3216,21 +3363,58 @@ class DefaultStreamTextResult<
                   // Clear this step's timeouts before the next step is started.
                   cleanupStepTimeouts();
 
-                  if (
-                    stepFinishReason !== 'interrupted' &&
-                    // Continue only after all client tool calls have been executed or denied,
-                    // and if there are client results or pending deferred provider results.
-                    clientToolCalls.length ===
+                  // why waiting steering messages are not delivered when
+                  // the stream ends:
+                  let steeringEndReason: SteeringNotDeliveredReason =
+                    'finished';
+
+                  const shouldStartNextStep = async () => {
+                    if (stepFinishReason === 'interrupted') {
+                      return false;
+                    }
+
+                    // Continue only after all client tool calls have been executed or denied:
+                    if (
+                      clientToolCalls.length !==
                       clientToolOutputs.length +
-                        deniedToolApprovalResponses.length &&
-                    (clientToolCalls.length > 0 ||
-                      pendingDeferredToolCalls.size > 0) &&
+                        deniedToolApprovalResponses.length
+                    ) {
+                      steeringEndReason = 'waiting-for-tool-results';
+                      return false;
+                    }
+
+                    // Continue if there are client results, pending deferred
+                    // provider results, or steering messages:
+                    if (
+                      clientToolCalls.length === 0 &&
+                      pendingDeferredToolCalls.size === 0
+                    ) {
+                      if (!steeringRun?.hasPendingMessages()) {
+                        return false;
+                      }
+
+                      // steering messages do not continue a failed step:
+                      if (stepFinishReason === 'error') {
+                        steeringEndReason = 'error';
+                        return false;
+                      }
+                    }
+
                     // continue until a stop condition is met:
-                    !(await isStopConditionMet({
-                      stopConditions,
-                      steps: recordedSteps,
-                    }))
-                  ) {
+                    if (
+                      await isStopConditionMet({
+                        stopConditions,
+                        steps: recordedSteps,
+                      })
+                    ) {
+                      steeringEndReason = 'stop-condition';
+                      return false;
+                    }
+
+                    return true;
+                  };
+
+                  if (await shouldStartNextStep()) {
                     try {
                       await runInStreamTextTracingChannelContext(() =>
                         streamStep({
@@ -3239,6 +3423,8 @@ class DefaultStreamTextResult<
                         }),
                       );
                     } catch (error) {
+                      steeringRun?.end('error');
+
                       enqueueStepPart(controller, {
                         type: 'error',
                         error,
@@ -3247,6 +3433,8 @@ class DefaultStreamTextResult<
                       self.closeStream();
                     }
                   } else {
+                    steeringRun?.end(steeringEndReason);
+
                     enqueueStepPart(controller, {
                       type: 'finish',
                       finishReason: stepFinishReason,
@@ -3280,6 +3468,9 @@ class DefaultStreamTextResult<
         }),
       );
     })().catch(async error => {
+      steeringRun?.end(abortSignal?.aborted ? 'aborted' : 'error');
+      // report the failed step before the call error:
+      await notifyStepError(wrapGatewayError(error));
       await telemetryDispatcher.onError?.({ callId, error });
       self._initialResponseMessages.reject(error);
       markPromiseAsHandled(self._initialResponseMessages.promise);