@ai-sdk/workflow 2.0.57 → 2.0.59

package/src/model-call.ts

@@ -0,0 +1,196 @@
+import type {
+  JSONObject,
+  LanguageModelV4CallOptions,
+  LanguageModelV4Content,
+  LanguageModelV4Source,
+  SharedV4ProviderMetadata,
+} from '@ai-sdk/provider';
+import type {
+  Experimental_LanguageModelStreamPart,
+  FinishReason,
+  LanguageModelUsage,
+  StopCondition,
+  ToolCallRepairFunction,
+  ToolChoice,
+  ToolSet,
+} from 'ai';
+import type { ProviderOptions, StreamTextTransform } from './workflow-agent.js';
+
+export type ModelCallStreamPart<TTools extends ToolSet = ToolSet> =
+  | Experimental_LanguageModelStreamPart<TTools>
+  | {
+      type: 'tool-approval-request';
+      approvalId: string;
+      toolCallId: string;
+      signature?: string;
+    }
+  | { type: 'reset-step' };
+
+export type ModelStopCondition = StopCondition<NoInfer<ToolSet>, any>;
+
+/**
+ * Provider-executed tool result captured from a model call.
+ */
+export interface ProviderExecutedToolResult {
+  toolCallId: string;
+  toolName: string;
+  result: unknown;
+  isError?: boolean;
+  dynamic?: boolean;
+  providerMetadata?: SharedV4ProviderMetadata;
+}
+
+/**
+ * Serializable options for a durable model call.
+ */
+export interface ModelCallOptions {
+  maxOutputTokens?: number;
+  temperature?: number;
+  topP?: number;
+  topK?: number;
+  presencePenalty?: number;
+  frequencyPenalty?: number;
+  stopSequences?: string[];
+  seed?: number;
+  maxRetries?: number;
+  abortSignal?: AbortSignal;
+  timeoutAt?: number;
+  headers?: Record<string, string | undefined>;
+  reasoning?: LanguageModelV4CallOptions['reasoning'];
+  providerOptions?: ProviderOptions;
+  toolChoice?: ToolChoice<ToolSet>;
+  includeRawChunks?: boolean;
+  repairToolCall?: ToolCallRepairFunction<ToolSet>;
+  include?: {
+    requestBody?: boolean;
+    responseBody?: boolean;
+    requestMessages?: boolean;
+  };
+  responseFormat?: LanguageModelV4CallOptions['responseFormat'];
+  experimental_transform?:
+    | StreamTextTransform<ToolSet>
+    | Array<StreamTextTransform<ToolSet>>;
+}
+
+/**
+ * Parsed tool call from the stream (parsed by streamModelCall's transform).
+ */
+export interface ParsedToolCall {
+  type: 'tool-call';
+  toolCallId: string;
+  toolName: string;
+  input: unknown;
+  providerExecuted?: boolean;
+  providerMetadata?: SharedV4ProviderMetadata;
+  title?: string;
+  toolMetadata?: JSONObject;
+  dynamic?: boolean;
+  invalid?: boolean;
+  error?: unknown;
+}
+
+/**
+ * Finish metadata from a model call.
+ */
+export interface ModelCallFinish {
+  finishReason: FinishReason;
+  rawFinishReason: string | undefined;
+  usage: LanguageModelUsage;
+  providerMetadata?: Record<string, unknown>;
+}
+
+export type ModelCallRawContentPart =
+  | Extract<
+      LanguageModelV4Content,
+      {
+        type:
+          | 'reasoning'
+          | 'custom'
+          | 'reasoning-file'
+          | 'tool-approval-request';
+      }
+    >
+  | {
+      type: 'text';
+      text: string;
+      providerMetadata?: SharedV4ProviderMetadata;
+    }
+  | {
+      type: 'reasoning';
+      reasoningIndex: number;
+    }
+  | {
+      type: 'file';
+      data: string;
+      mediaType: string;
+      providerMetadata?: SharedV4ProviderMetadata;
+    }
+  | LanguageModelV4Source
+  | {
+      type: 'tool-call';
+      toolCallIndex: number;
+    }
+  | {
+      type: 'provider-tool-result';
+      toolCallId: string;
+    };
+
+/**
+ * Compact callback replay data. The start event establishes the tool name for
+ * a call, so delta events do not repeat it and available events reuse the
+ * parsed input already present in `toolCalls`.
+ */
+export type ToolInputLifecycleEvent =
+  | ['start', toolCallId: string, toolName: string]
+  | ['delta', toolCallId: string, inputTextDelta: string]
+  | ['available', toolCallId: string];
+
+/**
+ * Minimal aggregates needed to reconstruct a `StepResult` outside the step
+ * boundary. By returning only these fields (instead of a fully-populated
+ * StepResult plus the raw `chunks[]` array), the durable event log doesn't
+ * carry StepResult's redundant derived fields — duplicate tool-call lists,
+ * `text`, `files`, `sources`, `reasoningText`, or the tool-result arrays
+ * populated after execution. It also avoids the per-chunk `chunks[]` snapshot
+ * the iterator never reads. The caller reconstructs the full StepResult via
+ * `buildModelStepResult`.
+ */
+export interface ModelCallRawResult {
+  content: ModelCallRawContentPart[];
+  reasoning: Array<{
+    text: string;
+    providerMetadata?: SharedV4ProviderMetadata;
+  }>;
+  responseMetadata?: {
+    id?: string;
+    timestamp?: Date;
+    modelId?: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+  };
+  /** Present only on non-streaming results; old stream payloads remain valid. */
+  generation?: {
+    provider: string;
+    modelId: string;
+    request?: { body?: unknown };
+    responseTimeMs: number;
+  };
+  warnings?: unknown[];
+}
+
+export type ModelCallResult =
+  | { aborted: true }
+  | {
+      aborted?: false;
+      toolCalls: ParsedToolCall[];
+      finish: ModelCallFinish | undefined;
+      raw: ModelCallRawResult;
+      providerExecutedToolResults: Map<string, ProviderExecutedToolResult>;
+      /**
+       * Optional for compatibility with model-step results persisted before
+       * tool input lifecycle callback replay was added.
+       */
+      toolInputLifecycleEvents?: ToolInputLifecycleEvent[];
+      /** Present when the model stream emitted an error part or generation failed. */
+      terminalError?: unknown;
+    };

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

@@ -38,6 +38,38 @@ class SerializableMockLanguageModel extends MockLanguageModelV4 {
     super({
       provider: 'workflow-test',
       modelId: 'workflow-test-model',
+      doGenerate: async options => {
+        const index = Math.min(
+          options.prompt.filter(message => message.role === 'assistant').length,
+          responses.length - 1,
+        );
+        const response = responses[index];
+        if (response.type === 'error') throw response.error;
+        return {
+          content:
+            response.type === 'text'
+              ? [{ type: 'text', text: response.text }]
+              : [
+                  {
+                    type: 'tool-call',
+                    toolCallId: `call-${index + 1}`,
+                    toolName: response.toolName,
+                    input: response.input,
+                  },
+                ],
+          finishReason: {
+            unified: response.type === 'text' ? 'stop' : 'tool-calls',
+            raw: undefined,
+          },
+          usage,
+          warnings: [],
+          response: {
+            id: 'generate-response',
+            modelId: 'mock-generate',
+            timestamp: new Date(),
+          },
+        };
+      },
       doStream: async (options: MockStreamOptions) => {
         const responseIndex = Math.min(
           options.prompt.filter(message => message.role === 'assistant').length,

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

@@ -1,7 +1,7 @@
 /**
  * Integration test workflows for WorkflowAgent using mock providers.
  */
-import { tool } from 'ai';
+import { tool, type ModelMessage, type LanguageModelUsage } from 'ai';
 import { WorkflowAgent } from '../workflow-agent.js';
 import { mockTextModel, mockSequenceModel } from '../providers/mock.js';
 import { retryingModel } from './retrying-model.js';
@@ -809,3 +809,62 @@ export async function agentSandboxE2e() {
     prepareStepSawStepSandbox,
   };
 }
+
+export async function agentGenerateE2e(repair: boolean): Promise<{
+  text: string;
+  output: string;
+  toolOutputs: number[];
+  responseMessages: ModelMessage[];
+  usage: LanguageModelUsage;
+  events: string[];
+}> {
+  'use workflow';
+  const events: string[] = [];
+  const agent = new WorkflowAgent({
+    model: mockSequenceModel([
+      {
+        type: 'tool-call',
+        toolName: 'addNumbers',
+        input: repair ? '{' : '{"a":3,"b":7}',
+      },
+      { type: 'text', text: 'The sum is 10' },
+    ]),
+    tools: {
+      addNumbers: tool({
+        inputSchema: z.object({ a: z.number(), b: z.number() }),
+        execute: addNumbers,
+      }),
+    },
+    onStepEnd: () => {
+      events.push('step');
+    },
+    onEnd: () => {
+      events.push('end');
+    },
+  });
+  const result = await agent.generate({
+    prompt: 'Add 3 and 7',
+    repairToolCall: repairToolCall as any,
+  });
+  return {
+    text: result.text,
+    output: result.output,
+    toolOutputs: result.staticToolResults.map(result => result.output),
+    responseMessages: result.responseMessages,
+    usage: result.usage,
+    events,
+  };
+}
+
+export async function agentGenerateUndefinedFailureE2e() {
+  'use workflow';
+  try {
+    await new WorkflowAgent({
+      model: mockSequenceModel([{ type: 'error', error: undefined }]),
+      maxRetries: 0,
+    }).generate({ prompt: 'fail' });
+    return { rejected: false, wasUndefined: false };
+  } catch (error) {
+    return { rejected: true, wasUndefined: error === undefined };
+  }
+}

package/src/test/approval-workflows.ts

@@ -0,0 +1,105 @@
+import { tool, type ModelMessage } from 'ai';
+import { createHook } from 'workflow';
+import { z } from 'zod/v4';
+import { mockSequenceModel } from '../providers/mock.js';
+import { WorkflowAgent } from '../workflow-agent.js';
+
+const secret = { environmentVariable: 'WORKFLOW_TOOL_APPROVAL_SECRET' };
+
+async function performApprovedAction({ value }: { value: string }) {
+  'use step';
+  return `performed:${value}`;
+}
+
+function approvalTools() {
+  return {
+    action: tool({
+      inputSchema: z.object({ value: z.string() }),
+      needsApproval: true,
+      execute: performApprovedAction,
+    }),
+  };
+}
+
+export async function issueGenerateApproval(): Promise<ModelMessage[]> {
+  'use workflow';
+  const agent = new WorkflowAgent({
+    model: mockSequenceModel([
+      {
+        type: 'tool-call',
+        toolName: 'action',
+        input: '{"value":"approved-action"}',
+      },
+    ]),
+    tools: approvalTools(),
+    experimental_toolApprovalSecret: secret,
+  });
+  const result = await agent.generate({ prompt: 'Perform the action.' });
+  return result.responseMessages;
+}
+
+export async function resumeGenerateApproval(
+  messages: ModelMessage[],
+  approved: boolean,
+) {
+  'use workflow';
+  const agent = new WorkflowAgent({
+    model: mockSequenceModel([{ type: 'text', text: 'Finished.' }]),
+    tools: approvalTools(),
+    experimental_toolApprovalSecret: secret,
+  });
+  const result = await agent.generate({
+    messages: [
+      { role: 'user', content: 'Perform the action.' },
+      ...messages,
+      {
+        role: 'tool',
+        content: [
+          {
+            type: 'tool-approval-response',
+            approvalId: 'approval-call-1',
+            approved,
+          },
+        ],
+      },
+    ],
+  });
+  return { text: result.text, responseMessages: result.responseMessages } as {
+    text: string;
+    responseMessages: ModelMessage[];
+  };
+}
+
+async function completedWork() {
+  'use step';
+  return 'completed before suspension';
+}
+
+export async function generateWithSuspendingTool() {
+  'use workflow';
+  const agent = new WorkflowAgent({
+    model: mockSequenceModel([
+      { type: 'tool-call', toolName: 'completedWork', input: '{}' },
+      { type: 'tool-call', toolName: 'waitForInput', input: '{}' },
+      { type: 'text', text: 'Resumed.' },
+    ]),
+    tools: {
+      completedWork: tool({
+        inputSchema: z.object({}),
+        execute: completedWork,
+      }),
+      waitForInput: tool({
+        inputSchema: z.object({}),
+        execute: async () => {
+          using hook = createHook<string>();
+          return await hook;
+        },
+      }),
+    },
+  });
+  const result = await agent.generate({ prompt: 'Do work, then wait.' });
+  return {
+    text: result.text,
+    outputs: result.toolResults.map(result => result.output),
+  };
+}

package/src/test/generation-boundary-model.ts

@@ -0,0 +1,115 @@
+import { APICallError } from '@ai-sdk/provider';
+import {
+  WORKFLOW_DESERIALIZE,
+  WORKFLOW_SERIALIZE,
+} from '@ai-sdk/provider-utils';
+import { MockLanguageModelV4 } from 'ai/test';
+import { getStepMetadata, getWritable } from 'workflow';
+
+export type BoundaryScenario = 'retry' | 'deadline' | 'abort' | 'rich' | 'hook';
+
+const usage = {
+  inputTokens: { total: 3, noCache: 2, cacheRead: 1, cacheWrite: undefined },
+  outputTokens: { total: 2, text: 1, reasoning: 1 },
+};
+
+class BoundaryModel extends MockLanguageModelV4 {
+  static [WORKFLOW_SERIALIZE](model: BoundaryModel) {
+    return { scenario: model.scenario };
+  }
+  static [WORKFLOW_DESERIALIZE]({ scenario }: { scenario: BoundaryScenario }) {
+    return new BoundaryModel(scenario);
+  }
+  constructor(readonly scenario: BoundaryScenario) {
+    let calls = 0;
+    super({
+      provider: 'boundary-test',
+      modelId: 'boundary-model',
+      doGenerate: async options => {
+        calls++;
+        const writer = getWritable().getWriter();
+        try {
+          await writer.write({
+            modelAttempt: calls,
+            stepAttempt: getStepMetadata().attempt,
+          });
+        } finally {
+          writer.releaseLock();
+        }
+        if (scenario === 'abort')
+          throw new DOMException('Provider aborted.', 'AbortError');
+        if (scenario === 'deadline' || (scenario === 'retry' && calls < 3)) {
+          throw new APICallError({
+            message: 'Retryable fixture failure',
+            url: 'https://example.com/model',
+            requestBodyValues: {},
+            statusCode: 503,
+            responseHeaders: {
+              'retry-after-ms': scenario === 'deadline' ? '10000' : '0',
+            },
+          });
+        }
+        if (
+          scenario === 'hook' &&
+          !options.prompt.some(message => message.role === 'assistant')
+        ) {
+          return {
+            content: [
+              {
+                type: 'tool-call',
+                toolCallId: 'wait-call',
+                toolName: 'wait',
+                input: '{}',
+              },
+            ],
+            finishReason: { unified: 'tool-calls', raw: undefined },
+            usage,
+            warnings: [],
+          };
+        }
+        return {
+          content:
+            scenario === 'rich'
+              ? [
+                  {
+                    type: 'reasoning',
+                    text: 'Reasoning.',
+                    providerMetadata: { fixture: { reasoning: true } },
+                  },
+                  { type: 'text', text: 'Answer.' },
+                  {
+                    type: 'file',
+                    data: { type: 'data', data: new Uint8Array([104, 105]) },
+                    mediaType: 'text/plain',
+                    providerMetadata: { fixture: { file: true } },
+                  },
+                  {
+                    type: 'source',
+                    sourceType: 'url',
+                    id: 'source',
+                    url: 'https://example.com/source',
+                  },
+                ]
+              : [{ type: 'text', text: 'Recovered.' }],
+          finishReason: { unified: 'stop', raw: 'end_turn' },
+          usage,
+          warnings: [{ type: 'other', message: 'fixture warning' }],
+          providerMetadata: { fixture: { calls } },
+          request: { body: 'request body' },
+          response: {
+            id: 'boundary-response',
+            timestamp: new Date('2026-01-02T00:00:00Z'),
+            modelId: 'response-model',
+            headers: { 'x-fixture': 'yes' },
+            body: { fixture: 'response' },
+          },
+        };
+      },
+    });
+  }
+}
+
+// Keep construction outside workflow modules for the SWC closure transform.
+export function generationBoundaryModel(scenario: BoundaryScenario) {
+  return new BoundaryModel(scenario);
+}

package/src/test/generation-boundary-workflows.ts

@@ -0,0 +1,106 @@
+import { tool, type ModelMessage } from 'ai';
+import { createHook, getWritable } from 'workflow';
+import { z } from 'zod/v4';
+import { WorkflowAgent } from '../workflow-agent.js';
+import {
+  generationBoundaryModel,
+  type BoundaryScenario,
+} from './generation-boundary-model.js';
+
+async function closeTrace() {
+  'use step';
+  const writer = getWritable().getWriter();
+  try {
+    await writer.close();
+  } finally {
+    writer.releaseLock();
+  }
+}
+
+export async function generateAtBoundary(
+  scenario: BoundaryScenario,
+  timeout?: number,
+) {
+  'use workflow';
+  const agent = new WorkflowAgent({
+    model: generationBoundaryModel(scenario),
+    maxRetries: 2,
+  });
+  try {
+    const result = await agent.generate({
+      prompt: 'Test generation.',
+      timeout,
+    });
+    return { text: result.text };
+  } catch (error) {
+    return {
+      errorName: (error as Error).name,
+      errorMessage: (error as Error).message,
+    };
+  } finally {
+    await closeTrace();
+  }
+}
+
+export async function generateAcrossDeadline(timeout: number) {
+  'use workflow';
+  const agent = new WorkflowAgent({
+    model: generationBoundaryModel('hook'),
+    tools: {
+      wait: tool({
+        inputSchema: z.object({}),
+        execute: async () => {
+          using hook = createHook<string>();
+          return await hook;
+        },
+      }),
+    },
+  });
+  try {
+    const result = await agent.generate({
+      prompt: 'Wait for the user.',
+      timeout,
+    });
+    return { text: result.text };
+  } catch (error) {
+    return { errorName: (error as Error).name };
+  } finally {
+    await closeTrace();
+  }
+}
+
+export async function generateSerializableFields(include: boolean) {
+  'use workflow';
+  const agent = new WorkflowAgent({ model: generationBoundaryModel('rich') });
+  const result = await agent.generate({
+    prompt: 'Return rich content.',
+    include: {
+      requestBody: include,
+      responseBody: include,
+      requestMessages: include,
+    },
+  });
+  using hook = createHook<string>();
+  await hook;
+  await closeTrace();
+  return {
+    text: result.text,
+    output: result.output,
+    contentTypes: result.content.map(part => part.type),
+    file: {
+      base64: result.files[0].base64,
+      bytes: result.files[0].uint8Array,
+      mediaType: result.files[0].mediaType,
+    },
+    sources: result.sources,
+    response: {
+      ...result.finalStep.response,
+      messages: result.finalStep.response.messages as ModelMessage[],
+    },
+    request: result.finalStep.request,
+    usage: result.usage,
+    warnings: result.warnings,
+    providerMetadata: result.finalStep.providerMetadata,
+    responseMessages: result.responseMessages as ModelMessage[],
+  };
+}