@ai-sdk/workflow 1.0.67 → 1.0.69

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/workflow",
-  "version": "1.0.67",
+  "version": "1.0.69",
   "type": "module",
   "description": "WorkflowAgent for building AI agents with AI SDK",
   "license": "Apache-2.0",
@@ -29,7 +29,7 @@
     "ajv": "^8.20.0",
     "@ai-sdk/provider": "4.0.7",
     "@ai-sdk/provider-utils": "5.0.27",
-    "ai": "7.0.66"
+    "ai": "7.0.68"
   },
   "devDependencies": {
     "@types/node": "22.19.19",

package/src/do-stream-step.ts

@@ -16,6 +16,7 @@ import {
   type ToolChoice,
   type ToolSet,
 } from 'ai';
+import { prepareRetries } from 'ai/internal';
 import type { ProviderOptions } from './workflow-agent.js';
 import {
   resolveSerializableTools,
@@ -109,6 +110,8 @@ export type DoStreamStepResult =
       finish: StreamFinish | undefined;
       raw: DoStreamStepRawResult;
       providerExecutedToolResults: Map<string, ProviderExecutedToolResult>;
+      /** Present when the model stream emitted an error part. */
+      terminalError?: unknown;
     };
 
 export async function doStreamStep(
@@ -172,42 +175,52 @@ export async function doStreamStep(
           },
         };
 
-  // streamModelCall handles: prompt standardization, tool preparation,
-  // model.doStream(), retry logic, and stream part transformation
-  // (tool call parsing, finish reason mapping, file wrapping).
-  const modelStream = await streamModelCall({
-    model,
-    // streamModelCall expects Prompt (ModelMessage[]) but we pass the
-    // pre-converted LanguageModelV4Prompt. standardizePrompt inside
-    // streamModelCall handles both formats.
-    messages: conversationPrompt as unknown as ModelMessage[],
-    allowSystemInMessages: true,
-    tools,
-    toolChoice: options?.toolChoice,
-    includeRawChunks: options?.includeRawChunks,
-    providerOptions: options?.providerOptions,
+  // streamModelCall handles prompt standardization, tool preparation,
+  // model.doStream(), and stream part transformation. Retries are applied
+  // around the model dispatch because streamModelCall itself does not retry.
+  const { retry } = prepareRetries({
+    maxRetries: options?.maxRetries,
     abortSignal,
-    headers: options?.headers,
-    reasoning: options?.reasoning,
-    output,
-    maxOutputTokens: options?.maxOutputTokens,
-    temperature: options?.temperature,
-    topP: options?.topP,
-    topK: options?.topK,
-    presencePenalty: options?.presencePenalty,
-    frequencyPenalty: options?.frequencyPenalty,
-    stopSequences: options?.stopSequences,
-    seed: options?.seed,
-    repairToolCall: options?.repairToolCall,
-  })
-    .then(result => result.stream)
-    .catch(error => {
+  });
+  const modelStream = await (async () => {
+    try {
+      const { stream } = await retry(() =>
+        streamModelCall({
+          model,
+          // streamModelCall expects Prompt (ModelMessage[]) but we pass the
+          // pre-converted LanguageModelV4Prompt. standardizePrompt inside
+          // streamModelCall handles both formats.
+          messages: conversationPrompt as unknown as ModelMessage[],
+          allowSystemInMessages: true,
+          tools,
+          toolChoice: options?.toolChoice,
+          includeRawChunks: options?.includeRawChunks,
+          providerOptions: options?.providerOptions,
+          abortSignal,
+          headers: options?.headers,
+          reasoning: options?.reasoning,
+          output,
+          maxOutputTokens: options?.maxOutputTokens,
+          temperature: options?.temperature,
+          topP: options?.topP,
+          topK: options?.topK,
+          presencePenalty: options?.presencePenalty,
+          frequencyPenalty: options?.frequencyPenalty,
+          stopSequences: options?.stopSequences,
+          seed: options?.seed,
+          repairToolCall: options?.repairToolCall,
+        }),
+      );
+
+      return stream;
+    } catch (error) {
       if (abortSignal?.aborted && isAbortError(error)) {
         return undefined;
       }
 
       throw error;
-    });
+    }
+  })();
 
   if (modelStream == null) {
     return { aborted: true };
@@ -228,6 +241,8 @@ export async function doStreamStep(
     | { id?: string; timestamp?: Date; modelId?: string }
     | undefined;
   let warnings: unknown[] | undefined;
+  let terminalError: unknown;
+  let hasTerminalError = false;
 
   // Acquire writer once before the loop to avoid per-chunk lock overhead
   const writer = writable?.getWriter();
@@ -305,6 +320,15 @@ export async function doStreamStep(
       if (writer) {
         await writer.write(part);
       }
+
+      if (part.type === 'error' && !hasTerminalError) {
+        // Retain the first model error as step data. Throwing here would make
+        // the durable workflow runtime retry the model step and normalize the
+        // original value before WorkflowAgent can surface it. Continue
+        // consuming so the existing finish reason and usage are preserved.
+        terminalError = part.error;
+        hasTerminalError = true;
+      }
     }
   } catch (error) {
     if (abortSignal?.aborted && isAbortError(error)) {
@@ -333,5 +357,10 @@ export async function doStreamStep(
       warnings,
     },
     providerExecutedToolResults,
+    ...(hasTerminalError ? { terminalError } : {}),
   };
 }
+
+// Model-call retries are handled above so the workflow runtime must not add
+// another retry layer around the durable step.
+doStreamStep.maxRetries = 0;

package/src/providers/mock-function-wrapper.ts

@@ -66,20 +66,30 @@ class SerializableMockLanguageModel extends MockLanguageModelV4 {
                   usage,
                 },
               ]
-            : [
-                ...prefix,
-                {
-                  type: 'tool-call',
-                  toolCallId: `call-${responseIndex + 1}`,
-                  toolName: response.toolName,
-                  input: response.input,
-                },
-                {
-                  type: 'finish',
-                  finishReason: { unified: 'tool-calls', raw: undefined },
-                  usage,
-                },
-              ];
+            : response.type === 'tool-call'
+              ? [
+                  ...prefix,
+                  {
+                    type: 'tool-call',
+                    toolCallId: `call-${responseIndex + 1}`,
+                    toolName: response.toolName,
+                    input: response.input,
+                  },
+                  {
+                    type: 'finish',
+                    finishReason: { unified: 'tool-calls', raw: undefined },
+                    usage,
+                  },
+                ]
+              : [
+                  ...prefix,
+                  { type: 'error', error: response.error },
+                  {
+                    type: 'finish',
+                    finishReason: { unified: 'error', raw: 'error' },
+                    usage,
+                  },
+                ];
 
         return { stream: convertArrayToReadableStream(streamParts) };
       },

package/src/providers/mock.ts

@@ -2,7 +2,8 @@ import { mockProvider } from './mock-function-wrapper.js';
 
 export type MockResponseDescriptor =
   | { type: 'text'; text: string }
-  | { type: 'tool-call'; toolName: string; input: string };
+  | { type: 'tool-call'; toolName: string; input: string }
+  | { type: 'error'; error: unknown };
 
 /**
  * Mock model that returns a fixed text response.

package/src/stream-text-iterator.ts

@@ -97,6 +97,11 @@ export interface StreamTextIteratorAbortedValue {
   messages: LanguageModelV4Prompt;
 }
 
+export interface StreamTextIteratorErrorValue {
+  error: unknown;
+  messages: LanguageModelV4Prompt;
+}
+
 // This runs in the workflow context
 export async function* streamTextIterator({
   prompt,
@@ -147,7 +152,9 @@ export async function* streamTextIterator({
   experimental_sandbox?: SandboxSession;
 }): AsyncGenerator<
   StreamTextIteratorYieldValue,
-  LanguageModelV4Prompt | StreamTextIteratorAbortedValue,
+  | LanguageModelV4Prompt
+  | StreamTextIteratorAbortedValue
+  | StreamTextIteratorErrorValue,
   LanguageModelV4ToolResultPart[]
 > {
   let conversationPrompt = [...prompt]; // Create a mutable copy
@@ -166,6 +173,8 @@ export async function* streamTextIterator({
   let lastStep: StepResult<any, any> | undefined;
   let lastStepWasToolCalls = false;
   let wasAborted = false;
+  let terminalError: unknown;
+  let hasTerminalError = false;
 
   // TODO(#12164): replace this AI-core telemetry bridge with a
   // WorkflowAgent-specific typed dispatcher. `streamTextIterator` widens
@@ -347,6 +356,11 @@ export async function* streamTextIterator({
         break;
       }
 
+      if ('terminalError' in streamStepResult) {
+        terminalError = streamStepResult.terminalError;
+        hasTerminalError = true;
+      }
+
       const { toolCalls, finish, raw, providerExecutedToolResults } =
         streamStepResult;
       // Reconstruct the full StepResult outside the step boundary so the
@@ -379,7 +393,12 @@ export async function* streamTextIterator({
 
       const finishReason = finish?.finishReason;
 
-      if (finishReason === 'tool-calls') {
+      if (hasTerminalError) {
+        // The error crossed the durable step boundary as data. End the loop
+        // without throwing so WorkflowAgent can preserve the existing
+        // resolved-result contract and expose the original value.
+        done = true;
+      } else if (finishReason === 'tool-calls') {
         lastStepWasToolCalls = true;
 
         const textContent = step.content.filter(
@@ -508,6 +527,10 @@ export async function* streamTextIterator({
     return { aborted: true, messages: conversationPrompt };
   }
 
+  if (hasTerminalError) {
+    return { error: terminalError, messages: conversationPrompt };
+  }
+
   return conversationPrompt;
 }
 

package/src/test/agent-e2e-workflows.ts

@@ -4,6 +4,7 @@
 import { tool } from 'ai';
 import { WorkflowAgent } from '../workflow-agent.js';
 import { mockTextModel, mockSequenceModel } from '../providers/mock.js';
+import { retryingModel } from './retrying-model.js';
 import { createTestSandbox } from './test-sandbox.js';
 import { FatalError, getWritable } from 'workflow';
 import { z } from 'zod/v4';
@@ -47,6 +48,46 @@ export async function agentBasicE2e(prompt: string) {
   };
 }
 
+export async function agentModelRetriesE2e() {
+  'use workflow';
+  const agent = new WorkflowAgent({
+    model: retryingModel(),
+    maxRetries: 2,
+  });
+  const result = await agent.stream({
+    messages: [{ role: 'user', content: 'retry the model call' }],
+    writable: getWritable(),
+  });
+  return result.steps.at(-1)?.text;
+}
+
+export async function agentStreamErrorE2e() {
+  'use workflow';
+  const terminal = {
+    type: 'credential',
+    code: 'safe-terminal-classification',
+  };
+  const callbackErrors: unknown[] = [];
+  const agent = new WorkflowAgent({
+    model: mockSequenceModel([{ type: 'error', error: terminal }]),
+  });
+
+  const result = await agent.stream({
+    messages: [{ role: 'user', content: 'trigger the terminal error' }],
+    writable: getWritable(),
+    onError: async ({ error }) => {
+      callbackErrors.push(error);
+    },
+  });
+
+  return {
+    error: result.error,
+    finishReason: result.finishReason,
+    stepCount: result.steps.length,
+    callbackErrors,
+  };
+}
+
 export async function agentToolCallE2e(a: number, b: number) {
   'use workflow';
   const agent = new WorkflowAgent({

package/src/test/retrying-model.ts

@@ -0,0 +1,79 @@
+import { APICallError } from '@ai-sdk/provider';
+import {
+  WORKFLOW_DESERIALIZE,
+  WORKFLOW_SERIALIZE,
+} from '@ai-sdk/provider-utils';
+import { convertArrayToReadableStream, MockLanguageModelV4 } from 'ai/test';
+import { getStepMetadata } from 'workflow';
+
+type MockStreamResult = Awaited<ReturnType<MockLanguageModelV4['doStream']>>;
+type MockStreamPart = MockStreamResult extends {
+  stream: ReadableStream<infer PART>;
+}
+  ? PART
+  : never;
+
+class SerializableRetryingModel extends MockLanguageModelV4 {
+  static [WORKFLOW_SERIALIZE](model: SerializableRetryingModel) {
+    return { failuresBeforeSuccess: model.failuresBeforeSuccess };
+  }
+
+  static [WORKFLOW_DESERIALIZE](options: { failuresBeforeSuccess: number }) {
+    return new SerializableRetryingModel(options.failuresBeforeSuccess);
+  }
+
+  constructor(readonly failuresBeforeSuccess: number) {
+    let modelAttempts = 0;
+
+    super({
+      provider: 'workflow-retry-test',
+      modelId: 'workflow-retry-test-model',
+      doStream: async () => {
+        modelAttempts++;
+
+        if (modelAttempts <= failuresBeforeSuccess) {
+          throw new APICallError({
+            message: `model call failed on attempt ${modelAttempts}`,
+            url: 'https://example.com/model',
+            requestBodyValues: {},
+            statusCode: 500,
+            responseHeaders: { 'retry-after-ms': '0' },
+          });
+        }
+
+        const text = `model-attempts=${modelAttempts};step-attempt=${getStepMetadata().attempt}`;
+        const streamParts: MockStreamPart[] = [
+          { type: 'stream-start', warnings: [] },
+          { type: 'text-start', id: '1' },
+          { type: 'text-delta', id: '1', delta: text },
+          { type: 'text-end', id: '1' },
+          {
+            type: 'finish',
+            finishReason: { unified: 'stop', raw: 'stop' },
+            usage: {
+              inputTokens: {
+                total: 1,
+                noCache: 1,
+                cacheRead: undefined,
+                cacheWrite: undefined,
+              },
+              outputTokens: {
+                total: 1,
+                text: 1,
+                reasoning: undefined,
+              },
+            },
+          },
+        ];
+
+        return { stream: convertArrayToReadableStream(streamParts) };
+      },
+    });
+  }
+}
+
+// Keep construction outside the workflow module to avoid the SWC closure
+// transformation issue tracked in https://github.com/vercel/workflow/issues/1365.
+export function retryingModel(): MockLanguageModelV4 {
+  return new SerializableRetryingModel(2);
+}

package/src/workflow-agent.ts

@@ -212,8 +212,7 @@ export interface GenerationSettings {
   seed?: number;
 
   /**
-   * Maximum number of retries. Set to 0 to disable retries.
-   * Note: In workflow context, retries are typically handled by the workflow step mechanism.
+   * Maximum number of retries for retryable model call failures. Set to 0 to disable retries.
    * @default 2
    */
   maxRetries?: number;
@@ -1191,6 +1190,15 @@ export interface WorkflowAgentStreamResult<
    */
   finishReason: FinishReason;
 
+  /**
+   * The original value from a model stream error part.
+   *
+   * This property is present when the model emitted an error part, including
+   * when the supplied value is `undefined`. Check with `'error' in result` to
+   * distinguish that case from a result without a model stream error.
+   */
+  error?: unknown;
+
   /**
    * The total token usage across all steps.
    */
@@ -2146,7 +2154,6 @@ export class WorkflowAgent<
       stopConditions: effectiveStopWhenFromPrepare,
       onStepEnd: mergedOnStepEnd as any,
       onStepStart: mergedOnStepStart as any,
-      onError: options.onError,
       prepareStep: (options.prepareStep ??
         (this.prepareStep as
           | PrepareStepCallback<ToolSet, TRuntimeContext>
@@ -2168,7 +2175,10 @@ export class WorkflowAgent<
     // Track the final conversation messages from the iterator
     let finalMessages: LanguageModelV4Prompt | undefined;
     let encounteredError: unknown;
+    let hasEncounteredError = false;
     let wasAborted = false;
+    let terminalError: unknown;
+    let hasTerminalError = false;
 
     try {
       let result = await iterator.next();
@@ -2526,6 +2536,10 @@ export class WorkflowAgent<
       if (result.done) {
         if (Array.isArray(result.value)) {
           finalMessages = result.value;
+        } else if ('error' in result.value) {
+          finalMessages = result.value.messages;
+          terminalError = result.value.error;
+          hasTerminalError = true;
         } else {
           finalMessages = result.value.messages;
           wasAborted = true;
@@ -2536,6 +2550,7 @@ export class WorkflowAgent<
       }
     } catch (error) {
       encounteredError = error;
+      hasEncounteredError = true;
       // Check if this is an abort error
       if (isAbortError(error)) {
         wasAborted = true;
@@ -2550,6 +2565,13 @@ export class WorkflowAgent<
       // Don't throw yet - we want to call onEnd first
     }
 
+    if (hasTerminalError) {
+      if (options.onError) {
+        await options.onError({ error: terminalError });
+      }
+      await telemetryDispatcher.onError?.(terminalError);
+    }
+
     // Use the final messages from the iterator, or fall back to standardized messages
     const messages = (finalMessages ??
       prompt.messages) as unknown as ModelMessage[];
@@ -2573,8 +2595,9 @@ export class WorkflowAgent<
         } catch (parseError) {
           // If there's already an error, don't override it
           // If not, set this as the error
-          if (!encounteredError) {
+          if (!hasEncounteredError) {
             encounteredError = parseError;
+            hasEncounteredError = true;
           }
         }
       }
@@ -2610,7 +2633,7 @@ export class WorkflowAgent<
     }
 
     // Re-throw any error that occurred
-    if (encounteredError) {
+    if (hasEncounteredError) {
       // Close the stream before throwing
       if (options.writable) {
         const sendFinish = options.sendFinish ?? true;
@@ -2639,6 +2662,7 @@ export class WorkflowAgent<
       finishReason,
       totalUsage,
       output: experimentalOutput,
+      ...(hasTerminalError ? { error: terminalError } : {}),
     };
   }
 }