ai 7.0.152 → 7.0.154

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/generate-object/generate-object.ts

@@ -479,7 +479,7 @@ export async function generateObject<
     });
 
     const object = await parseAndValidateObjectResultWithRepair(
-      text,
+      generateResult.structuredOutputText ?? text,
       outputStrategy,
       repairText,
       {

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.
  *