@ai-sdk/workflow 0.0.0-6b196531-20260710185421

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@ai-sdk/workflow",
+  "version": "0.0.0-6b196531-20260710185421",
+  "type": "module",
+  "description": "WorkflowAgent for building AI agents with AI SDK",
+  "license": "Apache-2.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "source": "./src/index.ts",
+  "files": [
+    "dist/**/*",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "!src/**/__snapshots__",
+    "!src/**/__fixtures__",
+    "CHANGELOG.md",
+    "README.md"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "@ai-sdk/provider": "4.0.3",
+    "@ai-sdk/provider-utils": "0.0.0-6b196531-20260710185421",
+    "ai": "0.0.0-6b196531-20260710185421"
+  },
+  "devDependencies": {
+    "@types/node": "22.19.19",
+    "@workflow/vitest": "4.0.1",
+    "tsup": "^8.5.1",
+    "typescript": "5.8.3",
+    "vitest": "4.1.6",
+    "workflow": "4.2.4",
+    "zod": "3.25.76",
+    "@vercel/ai-tsconfig": "0.0.0"
+  },
+  "peerDependencies": {
+    "zod": "^3.25.76 || ^4.1.8"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "homepage": "https://ai-sdk.dev/docs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vercel/ai",
+    "directory": "packages/workflow"
+  },
+  "bugs": {
+    "url": "https://github.com/vercel/ai/issues"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "workflow"
+  ],
+  "scripts": {
+    "build": "pnpm clean && tsup --tsconfig tsconfig.build.json",
+    "build:watch": "pnpm clean && tsup --watch --tsconfig tsconfig.build.json",
+    "clean": "del-cli dist *.tsbuildinfo",
+    "type-check": "tsc --build",
+    "test": "pnpm test:node && pnpm test:edge",
+    "test:update": "pnpm test:node -u",
+    "test:watch": "vitest --config vitest.node.config.js",
+    "test:edge": "vitest --config vitest.edge.config.js --run",
+    "test:integration": "vitest --config vitest.integration.config.mjs --run",
+    "test:node": "vitest --config vitest.node.config.js --run"
+  }
+}

package/src/create-language-model-tool-result-output.ts

@@ -0,0 +1,85 @@
+import type { LanguageModelV4ToolResultOutput } from '@ai-sdk/provider';
+import type { Tool } from '@ai-sdk/provider-utils';
+import type { ModelMessage } from 'ai';
+import {
+  createDefaultDownloadFunction,
+  createToolModelOutput,
+  downloadAssets,
+  mapToolResultOutput,
+  type DownloadFunction,
+} from 'ai/internal';
+
+/**
+ * Converts a single tool result into a provider-level
+ * `LanguageModelV4ToolResultOutput`, honoring the tool's optional
+ * `toModelOutput` hook.
+ *
+ * Unlike `generateText`/`streamText`, `WorkflowAgent` assembles the
+ * `LanguageModelV4` prompt incrementally — appending one tool result at a time
+ * — instead of building AI-level `ModelMessage`s and converting the whole
+ * prompt once via `convertToLanguageModelPrompt`. This helper performs the
+ * equivalent per-result conversion using the shared `ai/internal` primitives:
+ *
+ *   1. `createToolModelOutput` — applies `tool.toModelOutput` (or the
+ *      text/json/error fallback).
+ *   2. `downloadAssets` — for `content`-type outputs, downloads any file/image
+ *      assets so URLs become bytes the provider can consume.
+ *   3. `mapToolResultOutput` — maps the AI-level `ToolResultOutput` to the
+ *      provider-level output and converts legacy file types.
+ */
+export async function createLanguageModelToolResultOutput({
+  toolCallId,
+  toolName,
+  input,
+  output,
+  tool,
+  errorMode,
+  supportedUrls,
+  download = createDefaultDownloadFunction(),
+  provider,
+}: {
+  toolCallId: string;
+  toolName: string;
+  input: unknown;
+  output: unknown;
+  tool: Tool | undefined;
+  errorMode: 'none' | 'text' | 'json';
+  supportedUrls: Record<string, RegExp[]>;
+  download?: DownloadFunction;
+  provider?: string;
+}): Promise<LanguageModelV4ToolResultOutput> {
+  const modelOutput = await createToolModelOutput({
+    toolCallId,
+    input,
+    output,
+    tool,
+    errorMode,
+  });
+
+  const downloadedAssets =
+    modelOutput.type === 'content'
+      ? await downloadAssets(
+          [
+            {
+              role: 'tool',
+              content: [
+                {
+                  type: 'tool-result',
+                  toolCallId,
+                  toolName,
+                  output: modelOutput,
+                },
+              ],
+            } satisfies ModelMessage,
+          ],
+          download,
+          supportedUrls,
+        )
+      : {};
+
+  return mapToolResultOutput({
+    output: modelOutput,
+    provider,
+    downloadedAssets,
+  });
+}

package/src/do-stream-step.ts

@@ -0,0 +1,265 @@
+import type {
+  LanguageModelV4CallOptions,
+  LanguageModelV4Prompt,
+} from '@ai-sdk/provider';
+import {
+  experimental_streamLanguageModelCall as streamModelCall,
+  gateway,
+  type Experimental_LanguageModelStreamPart as ModelCallStreamPart,
+  type FinishReason,
+  type LanguageModel,
+  type LanguageModelUsage,
+  type ModelMessage,
+  type StopCondition,
+  type ToolCallRepairFunction,
+  type ToolChoice,
+  type ToolSet,
+} from 'ai';
+import type { ProviderOptions } from './workflow-agent.js';
+import {
+  resolveSerializableTools,
+  type SerializableToolDef,
+} from './serializable-schema.js';
+export type { Experimental_LanguageModelStreamPart as ModelCallStreamPart } from 'ai';
+
+export type ModelStopCondition = StopCondition<NoInfer<ToolSet>, any>;
+
+/**
+ * Provider-executed tool result captured from the stream.
+ */
+export interface ProviderExecutedToolResult {
+  toolCallId: string;
+  toolName: string;
+  result: unknown;
+  isError?: boolean;
+}
+
+/**
+ * Options for the doStreamStep function.
+ */
+export interface DoStreamStepOptions {
+  maxOutputTokens?: number;
+  temperature?: number;
+  topP?: number;
+  topK?: number;
+  presencePenalty?: number;
+  frequencyPenalty?: number;
+  stopSequences?: string[];
+  seed?: number;
+  maxRetries?: number;
+  abortSignal?: AbortSignal;
+  headers?: Record<string, string | undefined>;
+  reasoning?: LanguageModelV4CallOptions['reasoning'];
+  providerOptions?: ProviderOptions;
+  toolChoice?: ToolChoice<ToolSet>;
+  includeRawChunks?: boolean;
+  repairToolCall?: ToolCallRepairFunction<ToolSet>;
+  responseFormat?: LanguageModelV4CallOptions['responseFormat'];
+}
+
+/**
+ * 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?: Record<string, unknown>;
+  dynamic?: boolean;
+  invalid?: boolean;
+  error?: unknown;
+}
+
+/**
+ * Finish metadata from the stream.
+ */
+export interface StreamFinish {
+  finishReason: FinishReason;
+  rawFinishReason: string | undefined;
+  usage: LanguageModelUsage;
+  providerMetadata?: Record<string, unknown>;
+}
+
+/**
+ * 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 copies — `content`, the duplicate
+ * `toolCalls`/`dynamicToolCalls` lists, `reasoningText`, the always-empty
+ * `*ToolResults` arrays, and the per-chunk `chunks[]` snapshot the iterator
+ * never reads. The caller reconstructs the full StepResult via
+ * `buildStepResult`.
+ */
+export interface DoStreamStepRawResult {
+  text: string;
+  reasoning: Array<{ text: string }>;
+  responseMetadata?: { id?: string; timestamp?: Date; modelId?: string };
+  warnings?: unknown[];
+}
+
+export async function doStreamStep(
+  conversationPrompt: LanguageModelV4Prompt,
+  modelInit: LanguageModel,
+  writable?: WritableStream<ModelCallStreamPart<ToolSet>>,
+  serializedTools?: Record<string, SerializableToolDef>,
+  options?: DoStreamStepOptions,
+): Promise<{
+  toolCalls: ParsedToolCall[];
+  finish: StreamFinish | undefined;
+  raw: DoStreamStepRawResult;
+  providerExecutedToolResults: Map<string, ProviderExecutedToolResult>;
+}> {
+  'use step';
+
+  // Resolve model inside step (must happen here for serialization boundary)
+  const model: LanguageModel =
+    typeof modelInit === 'string'
+      ? gateway.languageModel(modelInit)
+      : modelInit;
+
+  // Reconstruct tools from serializable definitions with Ajv validation.
+  // Tools are serialized before crossing the step boundary because zod schemas
+  // contain functions that can't be serialized by the workflow runtime.
+  const tools = serializedTools
+    ? resolveSerializableTools(serializedTools)
+    : undefined;
+
+  // streamModelCall handles: prompt standardization, tool preparation,
+  // model.doStream(), retry logic, and stream part transformation
+  // (tool call parsing, finish reason mapping, file wrapping).
+  const { stream: 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,
+    abortSignal: options?.abortSignal,
+    headers: options?.headers,
+    reasoning: options?.reasoning,
+    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,
+  });
+
+  // Consume the stream: capture data and write to writable in real-time
+  const toolCalls: ParsedToolCall[] = [];
+  const providerExecutedToolResults = new Map<
+    string,
+    ProviderExecutedToolResult
+  >();
+  let finish: StreamFinish | undefined;
+
+  // Minimal aggregation — only what buildStepResult needs outside the step.
+  let text = '';
+  const reasoningParts: Array<{ text: string }> = [];
+  let responseMetadata:
+    | { id?: string; timestamp?: Date; modelId?: string }
+    | undefined;
+  let warnings: unknown[] | undefined;
+
+  // Acquire writer once before the loop to avoid per-chunk lock overhead
+  const writer = writable?.getWriter();
+
+  try {
+    for await (const part of modelStream) {
+      switch (part.type) {
+        case 'text-delta':
+          text += part.text;
+          break;
+        case 'reasoning-delta':
+          reasoningParts.push({ text: part.text });
+          break;
+        case 'tool-call': {
+          // parseToolCall adds dynamic/invalid/error at runtime
+          const toolCallPart = part as typeof part & Partial<ParsedToolCall>;
+          toolCalls.push({
+            type: 'tool-call',
+            toolCallId: toolCallPart.toolCallId,
+            toolName: toolCallPart.toolName,
+            input: toolCallPart.input,
+            providerExecuted: toolCallPart.providerExecuted,
+            providerMetadata: toolCallPart.providerMetadata as
+              | Record<string, unknown>
+              | undefined,
+            dynamic: toolCallPart.dynamic,
+            invalid: toolCallPart.invalid,
+            error: toolCallPart.error,
+          });
+          break;
+        }
+        case 'tool-result':
+          if (part.providerExecuted) {
+            providerExecutedToolResults.set(part.toolCallId, {
+              toolCallId: part.toolCallId,
+              toolName: part.toolName,
+              result: part.output,
+              isError: false,
+            });
+          }
+          break;
+        case 'tool-error': {
+          const errorPart = part as typeof part & {
+            providerExecuted?: boolean;
+          };
+          if (errorPart.providerExecuted) {
+            providerExecutedToolResults.set(errorPart.toolCallId, {
+              toolCallId: errorPart.toolCallId,
+              toolName: errorPart.toolName,
+              result: errorPart.error,
+              isError: true,
+            });
+          }
+          break;
+        }
+        case 'model-call-end':
+          finish = {
+            finishReason: part.finishReason,
+            rawFinishReason: part.rawFinishReason,
+            usage: part.usage,
+            providerMetadata: part.providerMetadata as
+              | Record<string, unknown>
+              | undefined,
+          };
+          break;
+        case 'model-call-start':
+          warnings = part.warnings;
+          break;
+        case 'model-call-response-metadata':
+          responseMetadata = part;
+          break;
+      }
+
+      // Write to writable in real-time
+      if (writer) {
+        await writer.write(part);
+      }
+    }
+  } finally {
+    writer?.releaseLock();
+  }
+
+  return {
+    toolCalls,
+    finish,
+    raw: {
+      text,
+      reasoning: reasoningParts,
+      responseMetadata,
+      warnings,
+    },
+    providerExecutedToolResults,
+  };
+}

package/src/index.ts

@@ -0,0 +1,49 @@
+export {
+  WorkflowAgent,
+  Output,
+  type CompatibleLanguageModel,
+  type DownloadFunction,
+  type WorkflowAgentOptions,
+  type WorkflowAgentStreamOptions,
+  type WorkflowAgentStreamResult,
+  type GenerationSettings,
+  type InferWorkflowAgentTools,
+  type InferWorkflowAgentUIMessage,
+  type OutputSpecification,
+  type PrepareCallCallback,
+  type PrepareCallOptions,
+  type PrepareCallResult,
+  type PrepareStepCallback,
+  type PrepareStepInfo,
+  type PrepareStepResult,
+  type ProviderOptions,
+  type WorkflowAgentOnAbortCallback,
+  type WorkflowAgentOnEndCallback,
+  type WorkflowAgentOnErrorCallback,
+  type WorkflowAgentOnFinishCallback,
+  type WorkflowAgentOnStepEndCallback,
+  type WorkflowAgentOnStepFinishCallback,
+  type StreamTextTransform,
+  type TelemetryOptions,
+  type ToolCallRepairFunction,
+  type WorkflowAgentOnStartCallback,
+  type WorkflowAgentOnStepStartCallback,
+  type WorkflowAgentOnToolExecutionStartCallback,
+  type WorkflowAgentOnToolExecutionEndCallback,
+} from './workflow-agent.js';
+
+export {
+  createModelCallToUIChunkTransform,
+  toUIMessageChunk,
+} from './to-ui-message-chunk.js';
+
+export type { ModelCallStreamPart } from './do-stream-step.js';
+
+export {
+  WorkflowChatTransport,
+  type WorkflowChatTransportOptions,
+  type SendMessagesOptions,
+  type ReconnectToStreamOptions,
+} from './workflow-chat-transport.js';
+
+export { normalizeUIMessageStreamParts } from './normalize-ui-message-stream.js';

package/src/normalize-ui-message-stream.ts

@@ -0,0 +1,164 @@
+import type { UIMessageChunk } from 'ai';
+
+/**
+ * Tracks, for one part family (text or reasoning), which part ids are open or
+ * ended within the current step.
+ */
+interface PartFrameState {
+  /** A `*-start` was seen and not yet ended in the current step. */
+  open: Set<string>;
+  /** A part that was opened and ended in the current step. */
+  ended: Set<string>;
+}
+
+const newPartFrameState = (): PartFrameState => ({
+  open: new Set(),
+  ended: new Set(),
+});
+
+/**
+ * Repairs the framing for a single `*-start` / `*-delta` / `*-end` chunk
+ * against the running per-step state, yielding the chunks the consumer should
+ * see. Text and reasoning parts share this logic (`startType` differentiates
+ * the synthesized start chunk).
+ *
+ * @yields the chunks (possibly synthesized, possibly none) the consumer should see.
+ */
+function* repairPart(
+  kind: 'start' | 'delta' | 'end',
+  id: string,
+  chunk: UIMessageChunk,
+  state: PartFrameState,
+  startType: 'text-start' | 'reasoning-start',
+): Generator<UIMessageChunk> {
+  if (kind === 'start') {
+    // Drop a duplicate/replayed start for a part already framed this step.
+    if (state.open.has(id) || state.ended.has(id)) {
+      return;
+    }
+    state.open.add(id);
+    yield chunk;
+    return;
+  }
+
+  // delta / end: drop a re-delivered chunk for an already-ended part.
+  if (state.ended.has(id)) {
+    return;
+  }
+  // Synthesize the missing start for an orphaned delta/end.
+  if (!state.open.has(id)) {
+    state.open.add(id);
+    yield { type: startType, id } as UIMessageChunk;
+  }
+  if (kind === 'end') {
+    state.open.delete(id);
+    state.ended.add(id);
+  }
+  yield chunk;
+}
+
+/**
+ * Normalizes the part framing of a UI message stream so it is always
+ * well-formed for the AI SDK's stream consumer (`processUIMessageStream`,
+ * which backs `useChat`/`readUIMessageStream`).
+ *
+ * ## Why this exists
+ *
+ * The consumer maintains a map of "active" text/reasoning parts keyed by id.
+ * A `text-delta`/`text-end` for an id that has no open part is a fatal error
+ * (`Received text-delta for missing text part with ID "0" ...`) that kills the
+ * whole turn. Two properties of the durable streaming model make that error
+ * reachable:
+ *
+ * - A workflow run owns a single shared stream, and the consumer resets its
+ *   active-part maps on every `finish-step`. Multi-step turns reuse the same
+ *   part id (commonly `"0"`) in each step, so a single dropped or duplicated
+ *   `*-start` across a step boundary orphans the rest of that step's content.
+ * - The same stream is read across reconnects, and a stream-producing step can
+ *   run more than once (retry/redelivery, or the concurrent-worker duplication
+ *   tracked in vercel/workflow#2331 and #2039). Either can interleave or
+ *   duplicate chunks on the shared stream — e.g. a `finish-step` landing in the
+ *   middle of another execution's text part.
+ *
+ * Since the content is still flowing and only the framing is damaged, repairing
+ * the framing here degrades the worst case to "text begins slightly into the
+ * step" or "a duplicated tail is dropped" instead of a dead turn.
+ *
+ * ## What it does
+ *
+ * Mirrors the consumer's part-lifetime state machine, per part type, per step:
+ * - resets tracking on `finish-step` (exactly where the consumer resets);
+ * - synthesizes a missing `*-start` when an orphaned `*-delta`/`*-end` arrives;
+ * - drops a re-delivered `*-start`/`*-delta`/`*-end` for a part already
+ *   open or ended in the current step (reconnect/replay overlap).
+ *
+ * A well-formed stream passes through unchanged.
+ *
+ * ## Scope: text and reasoning only
+ *
+ * `tool-input-delta` raises the same class of fatal error (`Received
+ * tool-input-delta for missing tool call ...`), but tool parts are deliberately
+ * left untouched: the consumer does not reset its tool-call map on `finish-step`
+ * and tool-call ids are unique, so the step-boundary id-reuse orphaning that
+ * makes text/reasoning fragile does not apply to them. If a future duplication
+ * mode is found to orphan tool-input parts, extend the same machine to that
+ * family rather than special-casing it.
+ *
+ * @param source the raw UI message chunk stream to normalize.
+ * @yields the framing-corrected UI message chunks.
+ */
+export async function* normalizeUIMessageStreamParts(
+  source: AsyncIterable<UIMessageChunk>,
+): AsyncGenerator<UIMessageChunk> {
+  const text = newPartFrameState();
+  const reasoning = newPartFrameState();
+
+  for await (const chunk of source) {
+    switch (chunk.type) {
+      case 'finish-step':
+        // The consumer clears its active-part maps here, so part ids may be
+        // legitimately reused in the next step. Reset to match.
+        text.open.clear();
+        text.ended.clear();
+        reasoning.open.clear();
+        reasoning.ended.clear();
+        yield chunk;
+        break;
+
+      case 'text-start':
+        yield* repairPart('start', chunk.id, chunk, text, 'text-start');
+        break;
+      case 'text-delta':
+        yield* repairPart('delta', chunk.id, chunk, text, 'text-start');
+        break;
+      case 'text-end':
+        yield* repairPart('end', chunk.id, chunk, text, 'text-start');
+        break;
+
+      case 'reasoning-start':
+        yield* repairPart(
+          'start',
+          chunk.id,
+          chunk,
+          reasoning,
+          'reasoning-start',
+        );
+        break;
+      case 'reasoning-delta':
+        yield* repairPart(
+          'delta',
+          chunk.id,
+          chunk,
+          reasoning,
+          'reasoning-start',
+        );
+        break;
+      case 'reasoning-end':
+        yield* repairPart('end', chunk.id, chunk, reasoning, 'reasoning-start');
+        break;
+
+      default:
+        yield chunk;
+    }
+  }
+}

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

@@ -0,0 +1,11 @@
+import { MockLanguageModelV4 } from 'ai/test';
+
+// Workaround for SWC plugin bug (https://github.com/vercel/workflow/issues/1365):
+// `new ClassName(...)` in a step closure doesn't get closure vars hoisted
+// correctly. Wrapping the constructor call in a plain function (imported
+// from a separate file) fixes it.
+export function mockProvider(
+  ...args: ConstructorParameters<typeof MockLanguageModelV4>
+) {
+  return new MockLanguageModelV4(...args);
+}