@ai-sdk/workflow 2.0.20 → 2.0.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/workflow",
-  "version": "2.0.20",
+  "version": "2.0.21",
   "type": "module",
   "description": "WorkflowAgent for building AI agents with AI SDK",
   "license": "Apache-2.0",
@@ -32,8 +32,8 @@
   },
   "dependencies": {
     "@ai-sdk/provider": "4.0.10",
-    "@ai-sdk/provider-utils": "5.0.35",
-    "ai": "7.0.89",
+    "@ai-sdk/provider-utils": "5.0.36",
+    "ai": "7.0.90",
     "ajv": "^8.20.0"
   },
   "devDependencies": {

package/src/do-stream-step.ts

@@ -1,6 +1,9 @@
 import type {
+  JSONObject,
   LanguageModelV4CallOptions,
   LanguageModelV4Prompt,
+  LanguageModelV4Source,
+  SharedV4ProviderMetadata,
 } from '@ai-sdk/provider';
 import { isAbortError } from '@ai-sdk/provider-utils';
 import {
@@ -78,7 +81,9 @@ export interface ParsedToolCall {
   toolName: string;
   input: unknown;
   providerExecuted?: boolean;
-  providerMetadata?: Record<string, unknown>;
+  providerMetadata?: SharedV4ProviderMetadata;
+  title?: string;
+  toolMetadata?: JSONObject;
   dynamic?: boolean;
   invalid?: boolean;
   error?: unknown;
@@ -94,18 +99,46 @@ export interface StreamFinish {
   providerMetadata?: Record<string, unknown>;
 }
 
+export type DoStreamStepRawContentPart =
+  | {
+      type: 'text';
+      text: string;
+      providerMetadata?: SharedV4ProviderMetadata;
+    }
+  | {
+      type: 'file';
+      data: string;
+      mediaType: string;
+      providerMetadata?: SharedV4ProviderMetadata;
+    }
+  | LanguageModelV4Source
+  | {
+      type: 'tool-call';
+      toolCallIndex: number;
+    };
+
+/**
+ * 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 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
+ * 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
  * `buildStepResult`.
  */
 export interface DoStreamStepRawResult {
-  text: string;
+  content: DoStreamStepRawContentPart[];
   reasoning: Array<{ text: string }>;
   responseMetadata?: { id?: string; timestamp?: Date; modelId?: string };
   warnings?: unknown[];
@@ -119,6 +152,11 @@ export type DoStreamStepResult =
       finish: StreamFinish | undefined;
       raw: DoStreamStepRawResult;
       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. */
       terminalError?: unknown;
     };
@@ -158,6 +196,7 @@ export async function doStreamStep(
   // 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 toolInputLifecycleEvents: ToolInputLifecycleEvent[] = [];
   const tools = serializedTools
     ? resolveSerializableTools(serializedTools)
     : undefined;
@@ -244,7 +283,8 @@ export async function doStreamStep(
   let finish: StreamFinish | undefined;
 
   // Minimal aggregation — only what buildStepResult needs outside the step.
-  let text = '';
+  const content: DoStreamStepRawContentPart[] = [];
+  const textPartIndexes = new Map<string, number>();
   const reasoningParts: Array<{ text: string }> = [];
   let responseMetadata:
     | { id?: string; timestamp?: Date; modelId?: string }
@@ -252,6 +292,7 @@ export async function doStreamStep(
   let warnings: unknown[] | undefined;
   let terminalError: unknown;
   let hasTerminalError = false;
+  const ongoingToolCallToolNames = new Map<string, string>();
 
   // Acquire writer once before the loop to avoid per-chunk lock overhead
   const writer = writable?.getWriter();
@@ -264,28 +305,99 @@ export async function doStreamStep(
 
     for await (const part of modelStream) {
       switch (part.type) {
+        case 'tool-input-start':
+          ongoingToolCallToolNames.set(part.id, part.toolName);
+          if (
+            serializedTools?.[part.toolName]?.hasOnInputStart ||
+            serializedTools?.[part.toolName]?.hasOnInputDelta ||
+            serializedTools?.[part.toolName]?.hasOnInputAvailable
+          ) {
+            toolInputLifecycleEvents.push(['start', part.id, part.toolName]);
+          }
+          break;
+        case 'tool-input-delta': {
+          const toolName = ongoingToolCallToolNames.get(part.id);
+          if (
+            toolName != null &&
+            serializedTools?.[toolName]?.hasOnInputDelta
+          ) {
+            toolInputLifecycleEvents.push(['delta', part.id, part.delta]);
+          }
+          break;
+        }
+        case 'text-start':
+          upsertTextContentPart({
+            content,
+            textPartIndexes,
+            id: part.id,
+            providerMetadata: part.providerMetadata,
+          });
+          break;
         case 'text-delta':
-          text += part.text;
+          upsertTextContentPart({
+            content,
+            textPartIndexes,
+            id: part.id,
+            textDelta: part.text,
+            providerMetadata: part.providerMetadata,
+          });
+          break;
+        case 'text-end':
+          upsertTextContentPart({
+            content,
+            textPartIndexes,
+            id: part.id,
+            providerMetadata: part.providerMetadata,
+          });
+          textPartIndexes.delete(part.id);
           break;
         case 'reasoning-delta':
           reasoningParts.push({ text: part.text });
           break;
+        case 'file':
+          content.push({
+            type: 'file',
+            data: part.file.base64,
+            mediaType: part.file.mediaType,
+            ...(part.providerMetadata != null
+              ? { providerMetadata: part.providerMetadata }
+              : {}),
+          });
+          break;
+        case 'source':
+          content.push(part);
+          break;
         case 'tool-call': {
           // parseToolCall adds dynamic/invalid/error at runtime
           const toolCallPart = part as typeof part & Partial<ParsedToolCall>;
+          const toolCallIndex = toolCalls.length;
+          const lifecycleToolName = ongoingToolCallToolNames.get(
+            toolCallPart.toolCallId,
+          );
+          ongoingToolCallToolNames.delete(toolCallPart.toolCallId);
+          if (
+            lifecycleToolName != null &&
+            serializedTools?.[lifecycleToolName]?.hasOnInputAvailable
+          ) {
+            toolInputLifecycleEvents.push([
+              'available',
+              toolCallPart.toolCallId,
+            ]);
+          }
           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,
+            providerMetadata: toolCallPart.providerMetadata,
+            title: toolCallPart.title,
+            toolMetadata: toolCallPart.toolMetadata,
             dynamic: toolCallPart.dynamic,
             invalid: toolCallPart.invalid,
             error: toolCallPart.error,
           });
+          content.push({ type: 'tool-call', toolCallIndex });
           break;
         }
         case 'tool-result':
@@ -374,12 +486,13 @@ export async function doStreamStep(
     toolCalls,
     finish,
     raw: {
-      text,
+      content,
       reasoning: reasoningParts,
       responseMetadata,
       warnings,
     },
     providerExecutedToolResults,
+    toolInputLifecycleEvents,
     ...(hasTerminalError ? { terminalError } : {}),
   };
 }
@@ -387,3 +500,43 @@ export async function doStreamStep(
 // Model-call retries are handled above so the workflow runtime must not add
 // another retry layer around the durable step.
 doStreamStep.maxRetries = 0;
+
+function upsertTextContentPart({
+  content,
+  textPartIndexes,
+  id,
+  textDelta,
+  providerMetadata,
+}: {
+  content: DoStreamStepRawContentPart[];
+  textPartIndexes: Map<string, number>;
+  id: string;
+  textDelta?: string;
+  providerMetadata?: SharedV4ProviderMetadata;
+}) {
+  let partIndex = textPartIndexes.get(id);
+
+  if (partIndex == null) {
+    partIndex =
+      content.push({
+        type: 'text',
+        text: '',
+        ...(providerMetadata != null ? { providerMetadata } : {}),
+      }) - 1;
+    textPartIndexes.set(id, partIndex);
+  }
+
+  const part = content[partIndex];
+
+  if (part.type !== 'text') {
+    throw new Error(`Expected text content at index ${partIndex}.`);
+  }
+
+  if (textDelta != null) {
+    part.text += textDelta;
+  }
+
+  if (providerMetadata != null) {
+    part.providerMetadata = providerMetadata;
+  }
+}

package/src/resolve-tool-context.ts

@@ -0,0 +1,28 @@
+import { validateTypes, type Context, type Tool } from '@ai-sdk/provider-utils';
+
+/**
+ * Resolves the per-tool context passed to tool callbacks and execution.
+ * Context schemas validate and normalize the value before any tool-owned
+ * callback observes it.
+ */
+export async function resolveToolContext({
+  toolName,
+  tool,
+  toolsContext,
+}: {
+  toolName: string;
+  tool: Tool;
+  toolsContext: Record<string, Context | undefined> | undefined;
+}): Promise<unknown> {
+  const contextSchema = tool.contextSchema;
+  const entry = toolsContext?.[toolName];
+  if (contextSchema == null) {
+    return entry;
+  }
+
+  return await validateTypes({
+    value: entry,
+    schema: contextSchema,
+    context: { field: 'tool context', entityName: toolName },
+  });
+}

package/src/serializable-schema.ts

@@ -10,7 +10,7 @@
  * `~standard.jsonSchema` (Standard Schema v2), extraction can be simplified
  * to use that interface directly.
  */
-import type { JSONSchema7 } from '@ai-sdk/provider';
+import type { JSONObject, JSONSchema7 } from '@ai-sdk/provider';
 import {
   asSchema,
   type Experimental_SandboxSession as SandboxSession,
@@ -18,23 +18,33 @@ import {
   jsonSchema,
   type Tool,
 } from '@ai-sdk/provider-utils';
-import { tool, type ToolSet } from 'ai';
+import { dynamicTool, tool, type ToolSet } from 'ai';
 import Ajv from 'ajv';
 
 /**
  * Serializable tool definition — plain objects only, safe for workflow steps.
  */
 export type SerializableToolDef = {
+  title?: string;
+  metadata?: JSONObject;
   description?: string;
   inputSchema: JSONSchema7;
+  /** Whether providers should enforce strict tool input generation. */
+  strict?: boolean;
   /** Input examples forwarded to providers that support them. */
   inputExamples?: Array<{ input: unknown }>;
   /** Provider-specific options attached to the tool definition. */
   providerOptions?: Tool['providerOptions'];
-  /** Present on provider tools (e.g. anthropic.tools.webSearch). */
-  type?: 'provider';
+  /** Input lifecycle callbacks that must be invoked outside the step. */
+  hasOnInputStart?: boolean;
+  hasOnInputDelta?: boolean;
+  hasOnInputAvailable?: boolean;
+  /** Present on dynamic and provider tools. */
+  type?: 'dynamic' | 'provider';
   /** Provider tool is executed by the provider. */
   isProviderExecuted?: boolean;
+  /** Provider tool results may arrive in a later model response. */
+  supportsDeferredResults?: boolean;
   /** Provider tool ID, e.g. 'anthropic.web_search_20250305'. */
   id?: `${string}.${string}`;
   /** Provider tool configuration args (maxUses, allowedDomains, etc.). */
@@ -59,6 +69,8 @@ export function serializeToolSet<TOOLS extends ToolSet>(
   return Object.fromEntries(
     Object.entries(tools).map(([name, t]) => {
       const def: SerializableToolDef = {
+        title: t.title,
+        metadata: t.metadata,
         description: resolveToolDescription({
           tool: t,
           toolName: name,
@@ -66,17 +78,32 @@ export function serializeToolSet<TOOLS extends ToolSet>(
           experimental_sandbox: sandbox,
         }),
         inputSchema: asSchema(t.inputSchema).jsonSchema as JSONSchema7,
+        strict: t.strict,
         inputExamples: t.inputExamples,
         providerOptions: t.providerOptions,
       };
 
+      if (t.type === 'dynamic') {
+        def.type = 'dynamic';
+      }
+      if (t.onInputStart != null) {
+        def.hasOnInputStart = true;
+      }
+      if (t.onInputDelta != null) {
+        def.hasOnInputDelta = true;
+      }
+      if (t.onInputAvailable != null) {
+        def.hasOnInputAvailable = true;
+      }
+
       // Preserve provider tool identity so the Gateway can recognize
       // them as provider-executed tools (e.g. anthropic webSearch).
-      if ((t as any).type === 'provider') {
+      if (t.type === 'provider') {
         def.type = 'provider';
-        def.isProviderExecuted = (t as any).isProviderExecuted ?? false;
-        def.id = (t as any).id;
-        def.args = (t as any).args;
+        def.isProviderExecuted = t.isProviderExecuted ?? false;
+        def.supportsDeferredResults = t.supportsDeferredResults;
+        def.id = t.id;
+        def.args = t.args;
       }
 
       return [name, def];
@@ -122,39 +149,81 @@ export function resolveSerializableTools(
       // Provider tools are executed server-side — pass them through
       // with their identity intact, no client-side validation needed.
       if (t.type === 'provider') {
+        const providerTool = {
+          type: 'provider' as const,
+          title: t.title,
+          metadata: t.metadata,
+          id: t.id!,
+          args: t.args ?? {},
+          inputSchema: jsonSchema(t.inputSchema),
+          providerOptions: t.providerOptions,
+        };
+
         return [
           name,
-          tool({
-            type: 'provider' as const,
-            id: t.id!,
-            args: t.args ?? {},
-            isProviderExecuted: t.isProviderExecuted ?? false,
-            inputSchema: jsonSchema(t.inputSchema),
+          t.isProviderExecuted
+            ? tool({
+                ...providerTool,
+                isProviderExecuted: true,
+                supportsDeferredResults: t.supportsDeferredResults,
+              })
+            : tool({
+                ...providerTool,
+                isProviderExecuted: false,
+              }),
+        ];
+      }
+
+      if (t.type === 'dynamic') {
+        const validateFn = ajv.compile(t.inputSchema);
+
+        return [
+          name,
+          dynamicTool({
+            description: t.description,
+            inputExamples: t.inputExamples,
             providerOptions: t.providerOptions,
+            inputSchema: jsonSchema(t.inputSchema, {
+              validate: value => {
+                if (validateFn(value)) {
+                  return { success: true, value };
+                }
+                return {
+                  success: false,
+                  error: new Error(ajv.errorsText(validateFn.errors)),
+                };
+              },
+            }),
           }),
         ];
       }
 
       const validateFn = ajv.compile(t.inputSchema);
+      const functionTool = {
+        title: t.title,
+        metadata: t.metadata,
+        description: t.description,
+        strict: t.strict,
+        inputExamples: t.inputExamples,
+        providerOptions: t.providerOptions,
+        inputSchema: jsonSchema(t.inputSchema, {
+          validate: value => {
+            if (validateFn(value)) {
+              return { success: true, value: value as any };
+            }
+            return {
+              success: false,
+              error: new Error(ajv.errorsText(validateFn.errors)),
+            };
+          },
+        }),
+      };
 
       return [
         name,
-        tool({
-          description: t.description,
-          inputExamples: t.inputExamples,
-          providerOptions: t.providerOptions,
-          inputSchema: jsonSchema(t.inputSchema, {
-            validate: value => {
-              if (validateFn(value)) {
-                return { success: true, value: value as any };
-              }
-              return {
-                success: false,
-                error: new Error(ajv.errorsText(validateFn.errors)),
-              };
-            },
-          }),
-        }),
+        t.type === 'dynamic'
+          ? tool({ ...functionTool, type: 'dynamic' })
+          : tool(functionTool),
       ];
     }),
   );