ai 7.0.153 → 7.0.154

package/src/generate-text/index.ts

@@ -10,10 +10,12 @@ export type {
   GenerateTextOnEndCallback,
   GenerateTextOnStartCallback,
   GenerateTextOnStepEndCallback,
+  GenerateTextOnStepErrorCallback,
   GenerateTextOnStepFinishCallback,
   GenerateTextOnStepStartCallback,
   GenerateTextStartEvent,
   GenerateTextStepEndEvent,
+  GenerateTextStepErrorEvent,
   GenerateTextStepStartEvent,
   OnFinishEvent,
   OnStartEvent,
@@ -48,6 +50,12 @@ export type {
   StepResult,
   StepResultPerformance,
 } from './step-result';
+export {
+  createSteering as experimental_createSteering,
+  type Steering as Experimental_Steering,
+  type SteeringNotDeliveredReason as Experimental_SteeringNotDeliveredReason,
+  type SteeringOutcome as Experimental_SteeringOutcome,
+} from './steering';
 export {
   hasToolCall,
   isLoopFinished,

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

@@ -5,6 +5,7 @@ import type {
   ModelMessage,
   ProviderOptions,
   ToolSet,
+  UserModelMessage,
 } from '@ai-sdk/provider-utils';
 import type { Instructions } from '../prompt';
 import type { LanguageModelCallOptions } from '../prompt/language-model-call-options';
@@ -26,6 +27,7 @@ import type { ToolOrder } from './tool-order';
  * @param options.messages - The messages that will be sent to the model for the current step. If you return a `messages` override, those messages carry forward to later steps.
  * @param options.initialMessages - The initial messages that were passed into generateText or streamText.
  * @param options.responseMessages - The response messages that have been accumulated from previous steps.
+ * @param options.experimental_steeringMessages - The steering messages that were added to `messages` for the current step.
  * @param options.runtimeContext - The user-defined runtime context.
  *
  * @returns An object that contains the settings for the step.
@@ -76,6 +78,16 @@ export type PrepareStepFunction<
    */
   responseMessages: Array<ResponseMessage>;
 
+  /**
+   * The user messages that were sent with `experimental_steering` and added to
+   * `messages` for the current step. Undefined when the step received no
+   * steering messages. `messages` already contains them. If you return a
+   * `messages` override that is rebuilt from other fields, e.g.
+   * `initialMessages` and `responseMessages`, add them back together with the
+   * steering messages of previous steps from `steps`.
+   */
+  experimental_steeringMessages?: Array<UserModelMessage>;
+
   /**
    * Tool context.
    */

package/src/generate-text/restricted-telemetry-dispatcher.ts

@@ -16,8 +16,10 @@ import type {
   GenerateTextOnEndCallback,
   GenerateTextOnStartCallback,
   GenerateTextOnStepEndCallback,
+  GenerateTextOnStepErrorCallback,
   GenerateTextOnStepFinishCallback,
   GenerateTextOnStepStartCallback,
+  GenerateTextStepStartEvent,
 } from './generate-text-events';
 import type { Output } from './output';
 import { DefaultStepResult, type StepResult } from './step-result';
@@ -40,6 +42,7 @@ export type RestrictedTelemetryDispatcher<
   | 'onStepStart'
   | 'onStepEnd'
   | 'onStepFinish'
+  | 'onStepError'
   | 'onEnd'
   | 'onAbort'
   | 'onToolExecutionStart'
@@ -50,6 +53,7 @@ export type RestrictedTelemetryDispatcher<
   onStepEnd: GenerateTextOnStepEndCallback<TOOLS, RUNTIME_CONTEXT>;
   /** @deprecated Use `onStepEnd` instead. */
   onStepFinish: GenerateTextOnStepFinishCallback<TOOLS, RUNTIME_CONTEXT>;
+  onStepError: GenerateTextOnStepErrorCallback<TOOLS, RUNTIME_CONTEXT, OUTPUT>;
   onEnd: GenerateTextOnEndCallback<TOOLS, RUNTIME_CONTEXT>;
   onAbort?: GenerateTextOnAbortCallback<TOOLS, RUNTIME_CONTEXT>;
   onToolExecutionStart?: OnToolExecutionStartCallback<TOOLS>;
@@ -94,6 +98,7 @@ function restrictStepResult<
     request: step.request,
     response: step.response,
     providerMetadata: step.providerMetadata,
+    steeringMessages: step.experimental_steeringMessages,
   });
 }
 
@@ -116,6 +121,29 @@ export function createRestrictedTelemetryDispatcher<
 }): RestrictedTelemetryDispatcher<TOOLS, RUNTIME_CONTEXT, OUTPUT> {
   const telemetryDispatcher = createTelemetryDispatcher({ telemetry });
 
+  const restrictStepStartEvent = <
+    EVENT extends GenerateTextStepStartEvent<TOOLS, RUNTIME_CONTEXT, OUTPUT>,
+  >(
+    event: EVENT,
+  ) => ({
+    ...event,
+    runtimeContext: filterIncludedContext({
+      context: event.runtimeContext,
+      includeContext: includeRuntimeContext,
+    }),
+    steps: event.steps.map(step =>
+      restrictStepResult({
+        step,
+        includeRuntimeContext,
+        includeToolsContext,
+      }),
+    ),
+    toolsContext: filterToolsContext({
+      toolsContext: event.toolsContext,
+      includeToolsContext,
+    }),
+  });
+
   return {
     ...telemetryDispatcher,
     onStart: event =>
@@ -131,24 +159,7 @@ export function createRestrictedTelemetryDispatcher<
         }),
       }),
     onStepStart: event =>
-      telemetryDispatcher.onStepStart?.({
-        ...event,
-        runtimeContext: filterIncludedContext({
-          context: event.runtimeContext,
-          includeContext: includeRuntimeContext,
-        }),
-        steps: event.steps.map(step =>
-          restrictStepResult({
-            step,
-            includeRuntimeContext,
-            includeToolsContext,
-          }),
-        ),
-        toolsContext: filterToolsContext({
-          toolsContext: event.toolsContext,
-          includeToolsContext,
-        }),
-      }),
+      telemetryDispatcher.onStepStart?.(restrictStepStartEvent(event)),
     onStepEnd: event =>
       telemetryDispatcher.onStepEnd?.(
         restrictStepResult({
@@ -165,6 +176,8 @@ export function createRestrictedTelemetryDispatcher<
           includeToolsContext,
         }),
       ),
+    onStepError: event =>
+      telemetryDispatcher.onStepError?.(restrictStepStartEvent(event)),
     onEnd: event =>
       telemetryDispatcher.onEnd?.(
         ((restrictedSteps: StepResult<TOOLS, Context>[]) => {

package/src/generate-text/steering.ts

@@ -0,0 +1,293 @@
+import {
+  createIdGenerator,
+  type ModelMessage,
+  type UserModelMessage,
+} from '@ai-sdk/provider-utils';
+import { InvalidArgumentError } from '../error/invalid-argument-error';
+
+const generateSteeringId = createIdGenerator({ prefix: 'steer', size: 24 });
+
+const steeringRunStarter = Symbol.for('vercel.ai.steering.start');
+
+/**
+ * Why a steering message was not delivered:
+ *
+ * - `finished`: the run ended before the message could be delivered.
+ * - `removed-by-prepare-step`: `prepareStep` returned messages without it.
+ * - `stop-condition`: a stop condition ended the run.
+ * - `waiting-for-tool-results`: the run ended to wait for tool results,
+ *   e.g. a tool approval or a tool without an `execute` function.
+ * - `aborted`: the run was aborted.
+ * - `error`: the run failed.
+ */
+export type SteeringNotDeliveredReason =
+  | 'finished'
+  | 'removed-by-prepare-step'
+  | 'stop-condition'
+  | 'waiting-for-tool-results'
+  | 'aborted'
+  | 'error';
+
+/**
+ * The outcome of a steering message.
+ */
+export type SteeringOutcome =
+  | {
+      readonly type: 'delivered';
+
+      /** The id of the steering message. */
+      readonly id: string;
+
+      /** The user message that was added to the run. */
+      readonly message: UserModelMessage;
+
+      /** The number of the step whose model call received the message. */
+      readonly stepNumber: number;
+    }
+  | {
+      readonly type: 'not-delivered';
+
+      /** The id of the steering message. */
+      readonly id: string;
+
+      /** The user message that was not added to the run. */
+      readonly message: UserModelMessage;
+
+      /** Why the message was not delivered. */
+      readonly reason: SteeringNotDeliveredReason;
+    };
+
+/**
+ * Sends user messages to a running generation. Pass it to `generateText`,
+ * `streamText`, or an agent call with the `experimental_steering` option.
+ */
+export interface Steering {
+  /**
+   * Adds a user message to the run at the next step boundary, after the
+   * current step and its tool calls are done. If the run would end because the
+   * model finished its answer, it continues for another step unless a stop
+   * condition is met.
+   *
+   * Messages that are sent before the run starts are delivered in the first
+   * step. A steering object can only be used for one generation.
+   *
+   * @param message - The user message, or its text.
+   * @param options.id - The id of the message. Sending a message again with
+   * the same id returns the outcome of the first message.
+   *
+   * @returns The outcome of the message. It never rejects.
+   */
+  steer(
+    message: string | UserModelMessage,
+    options?: { id?: string },
+  ): Promise<SteeringOutcome>;
+}
+
+/**
+ * The run side of a steering object.
+ */
+export type SteeringRun = {
+  hasPendingMessages(): boolean;
+
+  /**
+   * Takes the waiting messages for the next step. They are resolved by
+   * `resolveTakenMessages` once the prompt of the step is known.
+   */
+  takeMessages(): Array<UserModelMessage>;
+
+  /**
+   * Resolves the taken messages as delivered when they are part of the
+   * messages that are sent to the model, and returns the delivered messages.
+   */
+  resolveTakenMessages(options: {
+    stepNumber: number;
+    sentMessages: ReadonlyArray<ModelMessage>;
+  }): Array<UserModelMessage>;
+
+  end(reason: SteeringNotDeliveredReason): void;
+};
+
+type PendingSteer = {
+  id: string;
+  message: UserModelMessage;
+  resolve: (outcome: SteeringOutcome) => void;
+};
+
+class DefaultSteering implements Steering {
+  private state: 'idle' | 'running' | 'ended' = 'idle';
+  private pending: Array<PendingSteer> = [];
+  private taken: Array<PendingSteer> = [];
+  private outcomes = new Map<string, Promise<SteeringOutcome>>();
+
+  steer(
+    message: string | UserModelMessage,
+    options?: { id?: string },
+  ): Promise<SteeringOutcome> {
+    const id = options?.id ?? generateSteeringId();
+
+    const existingOutcome = this.outcomes.get(id);
+    if (existingOutcome != null) {
+      return existingOutcome;
+    }
+
+    const userMessage: UserModelMessage =
+      typeof message === 'string'
+        ? { role: 'user', content: message }
+        : message;
+
+    if (userMessage.role !== 'user') {
+      throw new InvalidArgumentError({
+        parameter: 'message',
+        value: message,
+        message: 'Steering messages must be user messages.',
+      });
+    }
+
+    const outcome =
+      this.state === 'ended'
+        ? Promise.resolve<SteeringOutcome>({
+            type: 'not-delivered',
+            id,
+            message: userMessage,
+            reason: 'finished',
+          })
+        : new Promise<SteeringOutcome>(resolve => {
+            this.pending.push({ id, message: userMessage, resolve });
+          });
+
+    this.outcomes.set(id, outcome);
+
+    return outcome;
+  }
+
+  [steeringRunStarter](): SteeringRun {
+    if (this.state !== 'idle') {
+      throw new InvalidArgumentError({
+        parameter: 'experimental_steering',
+        value: this,
+        message:
+          'The steering object was already used by a generation. Create a new one with experimental_createSteering() for each call.',
+      });
+    }
+
+    this.state = 'running';
+
+    return {
+      hasPendingMessages: () =>
+        this.state === 'running' && this.pending.length > 0,
+
+      takeMessages: () => {
+        if (this.state !== 'running') {
+          return [];
+        }
+
+        this.taken = [...this.taken, ...this.pending];
+        this.pending = [];
+
+        return this.taken.map(({ message }) => message);
+      },
+
+      resolveTakenMessages: ({ stepNumber, sentMessages }) => {
+        const taken = this.taken;
+        this.taken = [];
+
+        const delivered: Array<UserModelMessage> = [];
+
+        for (const { id, message, resolve } of taken) {
+          if (isSent({ message, sentMessages })) {
+            delivered.push(message);
+            resolve({ type: 'delivered', id, message, stepNumber });
+          } else {
+            resolve({
+              type: 'not-delivered',
+              id,
+              message,
+              reason: 'removed-by-prepare-step',
+            });
+          }
+        }
+
+        return delivered;
+      },
+
+      end: reason => {
+        if (this.state !== 'running') {
+          return;
+        }
+
+        const notDelivered = [...this.taken, ...this.pending];
+        this.taken = [];
+        this.pending = [];
+        this.state = 'ended';
+
+        for (const { id, message, resolve } of notDelivered) {
+          resolve({ type: 'not-delivered', id, message, reason });
+        }
+      },
+    };
+  }
+}
+
+// prepareStep can map messages to new objects, e.g. to add provider options,
+// so a message also counts as sent when a user message has the same content:
+function isSent({
+  message,
+  sentMessages,
+}: {
+  message: UserModelMessage;
+  sentMessages: ReadonlyArray<ModelMessage>;
+}): boolean {
+  const content = JSON.stringify(message.content);
+
+  return sentMessages.some(
+    sentMessage =>
+      sentMessage === message ||
+      (sentMessage.role === 'user' &&
+        JSON.stringify(sentMessage.content) === content),
+  );
+}
+
+/**
+ * Creates a steering object that sends user messages to a running generation.
+ *
+ * @example
+ * ```ts
+ * const steering = experimental_createSteering();
+ *
+ * const result = streamText({
+ *   model,
+ *   tools,
+ *   stopWhen: isStepCount(20),
+ *   experimental_steering: steering,
+ * });
+ *
+ * const outcome = await steering.steer('Use Paris, Texas instead.');
+ * ```
+ */
+export function createSteering(): Steering {
+  return new DefaultSteering();
+}
+
+/**
+ * Starts a run for a steering object that was passed to a generation.
+ */
+export function startSteeringRun(
+  steering: Steering | undefined,
+): SteeringRun | undefined {
+  if (steering == null) {
+    return undefined;
+  }
+
+  const start = (steering as Partial<DefaultSteering>)[steeringRunStarter];
+
+  if (typeof start !== 'function') {
+    throw new InvalidArgumentError({
+      parameter: 'experimental_steering',
+      value: steering,
+      message:
+        'The steering object must be created with experimental_createSteering().',
+    });
+  }
+
+  return start.call(steering);
+}

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

@@ -4,6 +4,7 @@ import type {
   ReasoningFilePart,
   ReasoningPart,
   ToolSet,
+  UserModelMessage,
 } from '@ai-sdk/provider-utils';
 import type {
   CallWarning,
@@ -275,6 +276,13 @@ export type StepResult<
    * results that can be fully encapsulated in the provider.
    */
   readonly providerMetadata: ProviderMetadata | undefined;
+
+  /**
+   * The user messages that were sent with `experimental_steering` and added
+   * to the input of this step. Undefined when the step received no steering
+   * messages.
+   */
+  readonly experimental_steeringMessages?: Array<UserModelMessage>;
 };
 
 export class DefaultStepResult<
@@ -301,6 +309,10 @@ export class DefaultStepResult<
     TOOLS,
     RUNTIME_CONTEXT
   >['providerMetadata'];
+  declare readonly experimental_steeringMessages?: StepResult<
+    TOOLS,
+    RUNTIME_CONTEXT
+  >['experimental_steeringMessages'];
 
   constructor({
     callId,
@@ -318,6 +330,7 @@ export class DefaultStepResult<
     request,
     response,
     providerMetadata,
+    steeringMessages,
   }: {
     callId: StepResult<TOOLS, RUNTIME_CONTEXT>['callId'];
     stepNumber: StepResult<TOOLS, RUNTIME_CONTEXT>['stepNumber'];
@@ -334,6 +347,7 @@ export class DefaultStepResult<
     request: StepResult<TOOLS, RUNTIME_CONTEXT>['request'];
     response: StepResult<TOOLS, RUNTIME_CONTEXT>['response'];
     providerMetadata: StepResult<TOOLS, RUNTIME_CONTEXT>['providerMetadata'];
+    steeringMessages?: Array<UserModelMessage>;
   }) {
     this.callId = callId;
     this.stepNumber = stepNumber;
@@ -349,6 +363,10 @@ export class DefaultStepResult<
     this.request = request;
     this.response = response;
     this.providerMetadata = providerMetadata;
+
+    if (steeringMessages != null && steeringMessages.length > 0) {
+      this.experimental_steeringMessages = steeringMessages;
+    }
   }
 
   get text() {