ai 7.0.153 → 7.0.155

package/src/agent/create-agent-ui-stream-response.ts

@@ -16,6 +16,7 @@ import {
   createAgentUIStream,
   type AgentUIMessageStreamOptions,
 } from './create-agent-ui-stream';
+import type { Steering } from '../generate-text/steering';
 
 /**
  * Runs the agent and returns a response object with a UI message stream.
@@ -26,6 +27,7 @@ import {
  * @param abortSignal - Abort signal. Optional.
  * @param timeout - Timeout in milliseconds. Optional.
  * @param experimental_sandbox - The sandbox environment that is passed through to tool execution. Optional.
+ * @param experimental_steering - A steering object that adds user messages to the run at the next step boundary. Only supported by `ToolLoopAgent`. Optional.
  * @param options - The options for the agent. Optional.
  * @param experimental_transform - Stream transformations. Optional.
  * @param onStepEnd - Callback that is called when each step ends. Optional.
@@ -70,6 +72,7 @@ export async function createAgentUIStreamResponse<
   abortSignal?: AbortSignal;
   timeout?: TimeoutConfiguration<TOOLS>;
   experimental_sandbox?: SandboxSession;
+  experimental_steering?: Steering;
   options?: CALL_OPTIONS;
   experimental_transform?: Arrayable<StreamTextTransform<TOOLS>>;
 } & UIMessageStreamResponseInit &

package/src/agent/create-agent-ui-stream.ts

@@ -28,7 +28,10 @@ import {
   createAsyncIterableStream,
   type AsyncIterableStream,
 } from '../util/async-iterable-stream';
+import { InvalidArgumentError } from '../error/invalid-argument-error';
+import type { Steering } from '../generate-text/steering';
 import type { Agent } from './agent';
+import { ToolLoopAgent } from './tool-loop-agent';
 
 /**
  * UI stream options with separate generation and UI message step callbacks.
@@ -56,6 +59,7 @@ export type AgentUIMessageStreamOptions<
  * @param abortSignal - The abort signal. Optional.
  * @param timeout - Timeout in milliseconds. Optional.
  * @param experimental_sandbox - The sandbox environment that is passed through to tool execution. Optional.
+ * @param experimental_steering - A steering object that adds user messages to the run at the next step boundary. Only supported by `ToolLoopAgent`. Optional.
  * @param options - The options for the agent.
  * @param experimental_transform - The stream transformations. Optional.
  * @param onStepEnd - Callback that is called when each step ends. Optional.
@@ -83,6 +87,7 @@ export async function createAgentUIStream<
   abortSignal,
   timeout,
   experimental_sandbox: sandbox,
+  experimental_steering: steering,
   experimental_transform,
   onStepEnd,
   onStepFinish,
@@ -101,12 +106,22 @@ export async function createAgentUIStream<
   abortSignal?: AbortSignal;
   timeout?: TimeoutConfiguration<TOOLS>;
   experimental_sandbox?: SandboxSession;
+  experimental_steering?: Steering;
   options?: CALL_OPTIONS;
   experimental_transform?: Arrayable<StreamTextTransform<TOOLS>>;
   // TODO `originalMessages` is part of this for bc, omit in v7
 } & AgentUIMessageStreamOptions<TOOLS, UI_MESSAGE>): Promise<
   AsyncIterableStream<InferUIMessageChunk<UI_MESSAGE>>
 > {
+  // other agents would ignore the steering object and never resolve its messages:
+  if (steering != null && !(agent instanceof ToolLoopAgent)) {
+    throw new InvalidArgumentError({
+      parameter: 'experimental_steering',
+      value: steering,
+      message: 'Steering is only supported by ToolLoopAgent.',
+    });
+  }
+
   const validatedMessages = await validateUIMessagesForAgent<UI_MESSAGE>({
     messages: uiMessages,
     // tools are compatible; the casting is required because the context param is
@@ -130,6 +145,7 @@ export async function createAgentUIStream<
     abortSignal,
     timeout,
     experimental_sandbox: sandbox,
+    experimental_steering: steering,
     experimental_transform,
     onStepEnd: onStepEnd ?? onStepFinish,
   });

package/src/agent/pipe-agent-ui-stream-to-response.ts

@@ -17,6 +17,7 @@ import {
   createAgentUIStream,
   type AgentUIMessageStreamOptions,
 } from './create-agent-ui-stream';
+import type { Steering } from '../generate-text/steering';
 
 /**
  * Pipes the agent UI message stream to a Node.js ServerResponse object.
@@ -28,6 +29,7 @@ import {
  * @param abortSignal - Abort signal. Optional.
  * @param timeout - Timeout in milliseconds. Optional.
  * @param experimental_sandbox - The sandbox environment that is passed through to tool execution. Optional.
+ * @param experimental_steering - A steering object that adds user messages to the run at the next step boundary. Only supported by `ToolLoopAgent`. Optional.
  * @param options - The options for the agent. Optional.
  * @param experimental_transform - Stream transformations. Optional.
  * @param onStepEnd - Callback that is called when each step ends. Optional.
@@ -72,6 +74,7 @@ export async function pipeAgentUIStreamToResponse<
   abortSignal?: AbortSignal;
   timeout?: TimeoutConfiguration<TOOLS>;
   experimental_sandbox?: SandboxSession;
+  experimental_steering?: Steering;
   options?: CALL_OPTIONS;
   experimental_transform?: Arrayable<StreamTextTransform<TOOLS>>;
 } & UIMessageStreamResponseInit &

package/src/agent/tool-loop-agent-settings.ts

@@ -13,6 +13,7 @@ import type {
   GenerateTextOnEndCallback,
   GenerateTextOnStartCallback,
   GenerateTextOnStepEndCallback,
+  GenerateTextOnStepErrorCallback,
   GenerateTextOnStepFinishCallback,
   GenerateTextOnStepStartCallback,
 } from '../generate-text/generate-text-events';
@@ -24,7 +25,11 @@ import type {
 import type { Output } from '../generate-text/output';
 import type { PrepareStepFunction } from '../generate-text/prepare-step';
 import type { StopCondition } from '../generate-text/stop-condition';
-import type { StreamTextInclude } from '../generate-text/stream-text';
+import type {
+  StreamTextInclude,
+  StreamTextOnAbortCallback,
+  StreamTextOnErrorCallback,
+} from '../generate-text/stream-text';
 import type { ToolApprovalConfiguration } from '../generate-text/tool-approval-configuration';
 import type { Experimental_ToolCallers } from '../generate-text/tool-caller-configuration';
 import type { ToolCallRepairFunction } from '../generate-text/tool-call-repair-function';
@@ -253,6 +258,37 @@ export type ToolLoopAgentSettings<
       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.
+     *
+     * Unlike `onStepStart` and `onStepEnd`, it can only be set here and not
+     * per call, because the per-call callbacks are shared with other `Agent`
+     * implementations that do not report step errors.
+     */
+    onStepError?: GenerateTextOnStepErrorCallback<
+      NoInfer<TOOLS>,
+      NoInfer<RUNTIME_CONTEXT>,
+      NoInfer<OUTPUT>
+    >;
+
+    /**
+     * Callback that is called when an error occurs. For `stream()` it receives
+     * the errors of the stream, for `generate()` it receives the error before
+     * it is thrown. Aborts and timeouts are not reported.
+     */
+    onError?: StreamTextOnErrorCallback;
+
+    /**
+     * Callback that is called when `stream()` is aborted or times out.
+     * `generate()` does not call it: an aborted or timed out `generate()` call
+     * rejects, and its step ends with `onStepError`.
+     */
+    onAbort?: StreamTextOnAbortCallback<
+      NoInfer<TOOLS>,
+      NoInfer<RUNTIME_CONTEXT>
+    >;
+
     /**
      * Callback that is called when each step (LLM call) ends, including intermediate steps.
      *

package/src/agent/tool-loop-agent.ts

@@ -15,8 +15,11 @@ import type { GenerateTextResult } from '../generate-text/generate-text-result';
 import type { Output } from '../generate-text/output';
 import { streamText } from '../generate-text/stream-text';
 import type { StreamTextResult } from '../generate-text/stream-text-result';
+import type { Steering } from '../generate-text/steering';
 import type { Prompt } from '../prompt';
+import { isCausedByAbort } from '../util/is-caused-by-abort';
 import { mergeCallbacks } from '../util/merge-callbacks';
+import { notify } from '../util/notify';
 import type {
   Agent,
   AgentCallParameters,
@@ -25,6 +28,17 @@ import type {
 import type { ToolLoopAgentSettings } from './tool-loop-agent-settings';
 import { createDefaultStopCondition } from './default-stop-condition';
 
+/**
+ * Call parameters that only `ToolLoopAgent` supports.
+ */
+export interface ToolLoopAgentCallExtensions {
+  /**
+   * A steering object created with `experimental_createSteering()`.
+   * Messages sent with it are added to the run at the next step boundary.
+   */
+  experimental_steering?: Steering;
+}
+
 /**
  * A tool loop agent is an agent that runs tools in a loop. In each step,
  * it calls the LLM, and if there are tool calls, it executes the tools
@@ -96,6 +110,8 @@ export class ToolLoopAgent<
       | 'onToolExecutionEnd'
       | 'onStepEnd'
       | 'onStepFinish'
+      | 'onError'
+      | 'onAbort'
       | 'onEnd'
       | 'onFinish'
     > &
@@ -122,6 +138,8 @@ export class ToolLoopAgent<
       onToolExecutionEnd: _settingsOnToolExecutionEnd,
       onStepEnd: _settingsOnStepEnd,
       onStepFinish: _settingsOnStepFinish,
+      onError: _settingsOnError,
+      onAbort: _settingsOnAbort,
       onFinish: _settingsOnFinish,
       onEnd: _settingsOnEnd,
       ...settingsWithoutCallbacks
@@ -198,6 +216,7 @@ export class ToolLoopAgent<
     abortSignal,
     timeout,
     experimental_sandbox: sandbox,
+    experimental_steering: steering,
     onStart,
     experimental_onStart,
     onStepStart,
@@ -209,7 +228,8 @@ export class ToolLoopAgent<
     onFinish,
     onEnd = onFinish,
     ...options
-  }: AgentCallParameters<CALL_OPTIONS, TOOLS, RUNTIME_CONTEXT>): Promise<
+  }: AgentCallParameters<CALL_OPTIONS, TOOLS, RUNTIME_CONTEXT> &
+    ToolLoopAgentCallExtensions): Promise<
     GenerateTextResult<TOOLS, RUNTIME_CONTEXT, OUTPUT>
   > {
     const generate = generateText<TOOLS, RUNTIME_CONTEXT, OUTPUT>;
@@ -221,6 +241,7 @@ export class ToolLoopAgent<
       abortSignal,
       timeout: timeout ?? preparedCall.timeout,
       experimental_sandbox: sandbox,
+      experimental_steering: steering,
       onStart: mergeCallbacks(
         this.settings.onStart ?? this.settings.experimental_onStart,
         (onStart ?? experimental_onStart) as
@@ -248,11 +269,21 @@ export class ToolLoopAgent<
       onEnd: mergeCallbacks(this.settings.onEnd, onEnd),
     };
 
-    return await generate({
-      ...preparedCall,
-      ...callbackArgs,
-      headers: this.agentHeaders(preparedCall),
-    } as unknown as Parameters<typeof generate>[0]);
+    try {
+      return await generate({
+        ...preparedCall,
+        ...callbackArgs,
+        headers: this.agentHeaders(preparedCall),
+      } as unknown as Parameters<typeof generate>[0]);
+    } catch (error) {
+      // generateText has no onError option, so report the error before it is
+      // thrown. Aborts (with any reason) and timeouts are not reported, like in
+      // streamText:
+      if (!isCausedByAbort(error) && !abortSignal?.aborted) {
+        await notify({ event: { error }, callbacks: this.settings.onError });
+      }
+      throw error;
+    }
   }
 
   /**
@@ -262,6 +293,7 @@ export class ToolLoopAgent<
     abortSignal,
     timeout,
     experimental_sandbox: sandbox,
+    experimental_steering: steering,
     experimental_transform,
     onStart,
     experimental_onStart,
@@ -274,7 +306,8 @@ export class ToolLoopAgent<
     onFinish,
     onEnd = onFinish,
     ...options
-  }: AgentStreamParameters<CALL_OPTIONS, TOOLS, RUNTIME_CONTEXT>): Promise<
+  }: AgentStreamParameters<CALL_OPTIONS, TOOLS, RUNTIME_CONTEXT> &
+    ToolLoopAgentCallExtensions): Promise<
     StreamTextResult<TOOLS, RUNTIME_CONTEXT, OUTPUT>
   > {
     const stream = streamText<TOOLS, RUNTIME_CONTEXT, OUTPUT>;
@@ -286,6 +319,7 @@ export class ToolLoopAgent<
       abortSignal,
       timeout: timeout ?? preparedCall.timeout,
       experimental_sandbox: sandbox,
+      experimental_steering: steering,
       experimental_transform,
       onStart: mergeCallbacks(
         this.settings.onStart ?? this.settings.experimental_onStart,
@@ -312,6 +346,8 @@ export class ToolLoopAgent<
         onStepEnd ?? onStepFinish,
       ),
       onEnd: mergeCallbacks(this.settings.onEnd, onEnd),
+      onError: this.settings.onError,
+      onAbort: this.settings.onAbort,
     };
 
     return await stream({

package/src/batch/batch.ts

@@ -491,14 +491,6 @@ function validateBatchReference({
   batchApi: BatchV4;
   batch: BatchReference;
 }) {
-  if (batch.version !== 2) {
-    throw new InvalidArgumentError({
-      parameter: 'batch',
-      value: batch,
-      message: 'batch must be a supported batch reference',
-    });
-  }
-
   if (batch.provider !== batchApi.provider) {
     throw new InvalidArgumentError({
       parameter: 'provider',

package/src/decide/validate-decision.ts

@@ -3,7 +3,6 @@ import {
   type Experimental_DecisionModelV4Result as DecisionModelV4Result,
   type Experimental_DecisionModelV4Question as DecisionQuestion,
 } from '@ai-sdk/provider';
-import { filePartSchema, textPartSchema } from '../prompt/content-part';
 import type { DecisionState } from './decision-state';
 import { InvalidArgumentError } from '../error/invalid-argument-error';
 
@@ -17,30 +16,28 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return prototype === Object.prototype || prototype === null;
 }
 
-function isJSON(value: unknown, ancestors = new Set<object>()): boolean {
-  if (value === null || typeof value === 'string' || typeof value === 'boolean')
-    return true;
+/**
+ * Checks the JSON constraints that types cannot express: finite numbers, no
+ * cycles, and no array holes. These would otherwise be silently changed by
+ * `JSON.stringify` or make it throw.
+ */
+function isSerializableJSON(
+  value: unknown,
+  ancestors = new Set<object>(),
+): boolean {
   if (typeof value === 'number') return Number.isFinite(value);
-  if (typeof value !== 'object' || (!Array.isArray(value) && !isRecord(value)))
-    return false;
+  if (value == null || typeof value !== 'object') return true;
   if (ancestors.has(value)) return false;
   ancestors.add(value);
-  const valid =
-    Object.getOwnPropertySymbols(value).length === 0 &&
-    (Array.isArray(value)
-      ? Array.from(value).every(item => isJSON(item, ancestors))
-      : Object.values(value).every(item => isJSON(item, ancestors)));
+  const valid = Array.isArray(value)
+    ? Array.from(value.keys()).every(
+        index => index in value && isSerializableJSON(value[index], ancestors),
+      )
+    : Object.values(value).every(item => isSerializableJSON(item, ancestors));
   ancestors.delete(value);
   return valid;
 }
 
-function isInput(value: unknown): boolean {
-  return (
-    (typeof value === 'string' || Array.isArray(value) || isRecord(value)) &&
-    isJSON(value)
-  );
-}
-
 function invalidInput(
   parameter: string,
   value: unknown,
@@ -56,50 +53,43 @@ export function validateDecisionInput({
   state: DecisionState;
   questions: Readonly<Record<string, DecisionQuestion>>;
 }) {
-  const validState = Array.isArray(state)
-    ? Array.from(state).every(part => {
-        if (!isRecord(part)) return false;
-        switch (part.type) {
-          case 'text':
-            return textPartSchema.safeParse(part).success;
-          case 'file':
-            return filePartSchema.safeParse(part).success;
-          case 'json':
-            return isJSON(part.value);
-          default:
-            return false;
-        }
-      })
-    : (typeof state === 'string' || isRecord(state)) && isJSON(state);
-  if (!validState) {
+  if (
+    Array.isArray(state) &&
+    Array.from(state.keys()).some(index => !(index in state))
+  ) {
+    invalidInput('state', state, 'state parts must not contain array holes');
+  }
+
+  const stateJSON = Array.isArray(state)
+    ? state.flatMap(part => (part.type === 'json' ? [part.value] : []))
+    : state;
+  if (!isSerializableJSON(stateJSON)) {
     invalidInput(
       'state',
       state,
-      'must be a string, JSON object, or array of text, file, or json parts',
+      'JSON content must not contain non-finite numbers, cycles, or array holes',
     );
   }
-  if (!isRecord(questions) || Object.keys(questions).length === 0) {
+
+  if (Object.keys(questions).length === 0) {
     invalidInput('questions', questions, 'must be a nonempty question map');
   }
 
   for (const [id, question] of Object.entries(questions)) {
     const parameter = `questions.${id}`;
     if (
-      !isRecord(question) ||
-      ((question.type === 'box' || question.instructions != null) &&
-        !isInput(question.instructions))
+      !isSerializableJSON(question.instructions) ||
+      ('criteria' in question && !isSerializableJSON(question.criteria))
     ) {
       invalidInput(
         parameter,
         question,
-        'instructions must be a JSON-compatible string, object, or array',
+        'instructions and criteria must not contain non-finite numbers, cycles, or array holes',
       );
     }
-    if (question.type === 'box') continue;
-    const criteria = question.criteria;
     switch (question.type) {
       case 'choice':
-        if (!isRecord(criteria) || Object.keys(criteria).length === 0) {
+        if (Object.keys(question.criteria).length === 0) {
           invalidInput(
             parameter,
             question,
@@ -108,7 +98,7 @@ export function validateDecisionInput({
         }
         break;
       case 'score':
-        if (!Array.isArray(criteria) || criteria.length === 0) {
+        if (question.criteria.length === 0) {
           invalidInput(
             parameter,
             question,
@@ -116,10 +106,11 @@ export function validateDecisionInput({
           );
         }
         break;
-      case 'boolean':
+      case 'boolean': {
+        const criteria = question.criteria;
         if (
           question.instructions == null &&
-          (!isRecord(criteria) ||
+          (criteria == null ||
             !Object.values(criteria).some(value => value != null))
         ) {
           invalidInput(
@@ -128,9 +119,8 @@ export function validateDecisionInput({
             'boolean questions require instructions or at least one non-null criterion',
           );
         }
-        if (criteria === undefined) continue;
         if (
-          !isRecord(criteria) ||
+          criteria != null &&
           Object.keys(criteria).some(key => key !== 'true' && key !== 'false')
         ) {
           invalidInput(
@@ -140,22 +130,7 @@ export function validateDecisionInput({
           );
         }
         break;
-      default:
-        invalidInput(
-          parameter,
-          question,
-          'question type must be choice, score, boolean, or box',
-        );
-    }
-    if (
-      !isJSON(criteria) ||
-      Object.values(criteria).some(value => value !== null && !isInput(value))
-    ) {
-      invalidInput(
-        parameter,
-        question,
-        'criteria descriptions must be JSON-compatible strings, objects, arrays, or null',
-      );
+      }
     }
   }
 }

package/src/generate-object/validate-object-generation-input.ts

@@ -14,20 +14,6 @@ export function validateObjectGenerationInput({
   schemaDescription?: string;
   enumValues?: Array<unknown>;
 }) {
-  if (
-    output != null &&
-    output !== 'object' &&
-    output !== 'array' &&
-    output !== 'enum' &&
-    output !== 'no-schema'
-  ) {
-    throw new InvalidArgumentError({
-      parameter: 'output',
-      value: output,
-      message: 'Invalid output type.',
-    });
-  }
-
   if (output === 'no-schema') {
     if (schema != null) {
       throw new InvalidArgumentError({
@@ -63,14 +49,6 @@ export function validateObjectGenerationInput({
   }
 
   if (output === 'object') {
-    if (schema == null) {
-      throw new InvalidArgumentError({
-        parameter: 'schema',
-        value: schema,
-        message: 'Schema is required for object output.',
-      });
-    }
-
     if (enumValues != null) {
       throw new InvalidArgumentError({
         parameter: 'enumValues',
@@ -81,14 +59,6 @@ export function validateObjectGenerationInput({
   }
 
   if (output === 'array') {
-    if (schema == null) {
-      throw new InvalidArgumentError({
-        parameter: 'schema',
-        value: schema,
-        message: 'Element schema is required for array output.',
-      });
-    }
-
     if (enumValues != null) {
       throw new InvalidArgumentError({
         parameter: 'enumValues',
@@ -123,15 +93,7 @@ export function validateObjectGenerationInput({
       });
     }
 
-    if (enumValues == null) {
-      throw new InvalidArgumentError({
-        parameter: 'enumValues',
-        value: enumValues,
-        message: 'Enum values are required for enum output.',
-      });
-    }
-
-    for (const value of enumValues) {
+    for (const value of enumValues ?? []) {
       if (typeof value !== 'string') {
         throw new InvalidArgumentError({
           parameter: 'enumValues',

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

@@ -12,7 +12,6 @@ import {
   withUserAgentSuffix,
   type ProviderOptions,
 } from '@ai-sdk/provider-utils';
-import { InvalidArgumentError } from '../error/invalid-argument-error';
 import { NoSpeechGeneratedError } from '../error/no-speech-generated-error';
 import { StreamProviderError } from '../error/stream-provider-error';
 import { logWarnings } from '../logger/log-warnings';
@@ -533,23 +532,12 @@ function toSourceStream(
       iterable[Symbol.asyncIterator](),
     );
   }
-  if (
-    typeof (text as Partial<Iterable<unknown>>)?.[Symbol.iterator] ===
-    'function'
-  ) {
-    const iterable = text as Iterable<string | SpeechTextPart>;
-    return convertAsyncIteratorToReadableStream(
-      (async function* () {
-        yield* iterable;
-      })(),
-    );
-  }
-  throw new InvalidArgumentError({
-    parameter: 'text',
-    value: text,
-    message:
-      'Expected a string, an iterable or async iterable, or a ReadableStream of strings or text parts.',
-  });
+  const iterable = text as Iterable<string | SpeechTextPart>;
+  return convertAsyncIteratorToReadableStream(
+    (async function* () {
+      yield* iterable;
+    })(),
+  );
 }
 
 function toTextPart(

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

@@ -392,6 +392,43 @@ export type GenerateTextOnStepFinishCallback<
   RUNTIME_CONTEXT extends Context = Context,
 > = GenerateTextOnStepEndCallback<TOOLS, RUNTIME_CONTEXT>;
 
+/**
+ * Event passed to the `onStepError` callback.
+ *
+ * Contains the step start event of the step that failed before it produced
+ * a step result, along with the error.
+ */
+export type GenerateTextStepErrorEvent<
+  TOOLS extends ToolSet = ToolSet,
+  RUNTIME_CONTEXT extends Context = Context,
+  OUTPUT extends Output = Output,
+> = GenerateTextStepStartEvent<TOOLS, RUNTIME_CONTEXT, OUTPUT> & {
+  /** The error that ended the step. */
+  readonly error: unknown;
+};
+
+/**
+ * Callback that is set using the `onStepError` option.
+ *
+ * Called when a step that started fails before it produces a step result:
+ * when the provider call throws or rejects, or when the model stream ends
+ * without output. `onStepEnd` is not called for such a step. A provider
+ * `error` chunk does not fail the step, it still ends with `onStepEnd` and
+ * `finishReason: 'error'`.
+ *
+ * In `generateText`, an abort or timeout also ends the step here. The error
+ * is the abort or timeout error, or a provider error that has it as its
+ * `cause`. In `streamText`, an abort or timeout ends the step
+ * with `onAbort` instead.
+ *
+ * @param event - The step that failed and the error.
+ */
+export type GenerateTextOnStepErrorCallback<
+  TOOLS extends ToolSet = ToolSet,
+  RUNTIME_CONTEXT extends Context = Context,
+  OUTPUT extends Output = Output,
+> = Callback<GenerateTextStepErrorEvent<TOOLS, RUNTIME_CONTEXT, OUTPUT>>;
+
 /**
  * Callback that is set using the `onEnd` option.
  *