@voltagent/core 0.1.70 → 0.1.72

package/dist/index.d.ts

@@ -167,7 +167,7 @@ type AgentTool = BaseTool;
 /**
  * Tool options for creating a new tool
  */
-type ToolOptions<T extends ToolSchema = ToolSchema> = {
+type ToolOptions<T extends ToolSchema = ToolSchema, O extends ToolSchema | undefined = undefined> = {
     /**
      * Unique identifier for the tool
      */
@@ -184,15 +184,19 @@ type ToolOptions<T extends ToolSchema = ToolSchema> = {
      * Tool parameter schema
      */
     parameters: T;
+    /**
+     * Tool output schema (optional)
+     */
+    outputSchema?: O;
     /**
      * Function to execute when the tool is called
      */
-    execute: (args: z.infer<T>, options?: ToolExecuteOptions) => Promise<unknown>;
+    execute: (args: z.infer<T>, options?: ToolExecuteOptions) => Promise<O extends ToolSchema ? z.infer<O> : unknown>;
 };
 /**
  * Tool class for defining tools that agents can use
  */
-declare class Tool<T extends ToolSchema = ToolSchema> {
+declare class Tool<T extends ToolSchema = ToolSchema, O extends ToolSchema | undefined = undefined> {
     /**
      * Unique identifier for the tool
      */
@@ -209,23 +213,28 @@ declare class Tool<T extends ToolSchema = ToolSchema> {
      * Tool parameter schema
      */
     readonly parameters: T;
+    /**
+     * Tool output schema
+     */
+    readonly outputSchema?: O;
     /**
      * Function to execute when the tool is called
      */
-    readonly execute: (args: z.infer<T>, options?: ToolExecuteOptions) => Promise<unknown>;
+    readonly execute: (args: z.infer<T>, options?: ToolExecuteOptions) => Promise<O extends ToolSchema ? z.infer<O> : unknown>;
     /**
      * Create a new tool
      */
-    constructor(options: ToolOptions<T>);
+    constructor(options: ToolOptions<T, O>);
 }
 /**
  * Helper function for creating a new tool
  */
-declare const createTool: <T extends ToolSchema>(options: ToolOptions<T>) => Tool<T>;
+declare function createTool<T extends ToolSchema>(options: ToolOptions<T, undefined>): Tool<T, undefined>;
+declare function createTool<T extends ToolSchema, O extends ToolSchema>(options: ToolOptions<T, O>): Tool<T, O>;
 /**
  * Alias for createTool function
  */
-declare const tool: <T extends ToolSchema>(options: ToolOptions<T>) => Tool<T>;
+declare const tool: typeof createTool;
 
 /**
  * The base input type for the workflow
@@ -335,10 +344,13 @@ type InternalAnyWorkflowStep<INPUT, DATA = DangerouslyAllowAny, RESULT = Dangero
  * Infer the result type from a list of steps
  * @private - INTERNAL USE ONLY
  */
-type InternalInferWorkflowStepsResult<STEPS extends ReadonlyArray<InternalAnyWorkflowStep<DangerouslyAllowAny, DangerouslyAllowAny, DangerouslyAllowAny>>> = {
-    [K in keyof STEPS]: Awaited<ReturnType<STEPS[K]["execute"]>>;
+type InternalInferWorkflowStepsResult<STEPS extends ReadonlyArray<InternalAnyWorkflowStep<any, any, any, any, any>>> = {
+    [K in keyof STEPS]: ExtractExecuteResult<STEPS[K]>;
 };
 type InternalExtractWorkflowInputData<T> = TF.IsUnknown<T> extends true ? BaseMessage | BaseMessage[] | string : TF.IsAny<T> extends true ? BaseMessage | BaseMessage[] | string : T extends z.ZodType ? z.infer<T> : T;
+type ExtractExecuteResult<T> = T extends {
+    execute: (...args: any[]) => infer R;
+} ? R extends Promise<infer U> ? U : R : never;
 
 type WorkflowStateStatus = "pending" | "running" | "completed" | "failed" | "suspended";
 type WorkflowState<INPUT, RESULT> = {
@@ -1832,7 +1844,7 @@ type ModelDynamicValue<T> = T | DynamicValue<T>;
 /**
  * Enhanced dynamic value for tools that supports static or dynamic values
  */
-type ToolsDynamicValue = (Tool<any> | Toolkit)[] | DynamicValue<(Tool<any> | Toolkit)[]>;
+type ToolsDynamicValue = (Tool<any, any> | Toolkit)[] | DynamicValue<(Tool<any, any> | Toolkit)[]>;
 /**
  * Provider options type for LLM configurations
  */
@@ -2670,7 +2682,7 @@ type ToolExecuteOptions = {
      */
     [key: string]: any;
 };
-type BaseTool = Tool<any>;
+type BaseTool = Tool<any, any>;
 type BaseToolCall = {
     name: string;
     arguments: Record<string, any>;
@@ -3536,6 +3548,17 @@ interface LibSQLStorageOptions extends MemoryOptions {
      * @default 100
      */
     storageLimit?: number;
+    /**
+     * Number of retry attempts for database operations when encountering busy/locked errors
+     * @default 3
+     */
+    retryAttempts?: number;
+    /**
+     * Base delay in milliseconds before retrying a failed operation
+     * Uses a jittered exponential backoff strategy for better load distribution
+     * @default 50
+     */
+    baseDelayMs?: number;
 }
 /**
  * A LibSQL storage implementation of the Memory and WorkflowMemory interfaces
@@ -3551,6 +3574,8 @@ declare class LibSQLStorage implements Memory {
     private initialized;
     private workflowExtension;
     private logger;
+    private retryAttempts;
+    private baseDelayMs;
     /**
      * Create a new LibSQL storage
      * @param options Configuration options
@@ -3568,6 +3593,20 @@ declare class LibSQLStorage implements Memory {
      * @param data Additional data to log
      */
     private debug;
+    /**
+     * Calculate delay with jitter for better load distribution
+     * @param attempt Current retry attempt number
+     * @returns Delay in milliseconds
+     */
+    private calculateRetryDelay;
+    /**
+     * Execute a database operation with retry strategy
+     * Implements jittered exponential backoff
+     * @param operationFn The operation function to execute
+     * @param operationName Operation name for logging
+     * @returns The result of the operation
+     */
+    private executeWithRetryStrategy;
     /**
      * Initialize workflow tables
      */
@@ -3610,7 +3649,7 @@ declare class LibSQLStorage implements Memory {
     /**
      * Close the database connection
      */
-    close(): void;
+    close(): Promise<void>;
     /**
      * Add or update a history entry
      * @param key Entry ID
@@ -4636,7 +4675,8 @@ declare class Agent<TProvider extends {
             name: string;
             description: string;
             parameters: any;
-            execute: (args: any, options?: ToolExecuteOptions) => Promise<unknown>;
+            outputSchema?: any;
+            execute: (args: any, options?: ToolExecuteOptions) => Promise<any>;
         }[];
         subAgents: {
             node_id: string;
@@ -4779,11 +4819,14 @@ type AgentConfig$1<SCHEMA extends z.ZodTypeAny> = PublicGenerateOptions & {
  * ```ts
  * const w = createWorkflow(
  *   andAgent(
- *     (data) => `Generate a greeting for the user ${data.name}`,
+ *     ({ data }) => `Generate a greeting for the user ${data.name}`,
  *     agent,
- *    { schema: z.object({ greeting: z.string() }) }
+ *     { schema: z.object({ greeting: z.string() }) }
  *   ),
- *   andThen(async (data) => data.greeting)
+ *   andThen({
+ *     id: "extract-greeting",
+ *     execute: async ({ data }) => data.greeting
+ *   })
  * );
  * ```
  *
@@ -4882,17 +4925,23 @@ interface InternalWorkflowRunOptions extends WorkflowRunOptions {
  * @example
  * ```ts
  * const w = createWorkflow(
- *   andThen(async (data) => {
- *     const processed = await someAsyncOperation(data.value);
- *     return { ...data, processed };
+ *   andThen({
+ *     id: "process-data",
+ *     execute: async ({ data }) => {
+ *       const processed = await someAsyncOperation(data.value);
+ *       return { ...data, processed };
+ *     }
  *   }),
- *   andThen(async (data) => {
- *     return { result: `Processed: ${data.processed}` };
+ *   andThen({
+ *     id: "format-result",
+ *     execute: async ({ data }) => {
+ *       return { result: `Processed: ${data.processed}` };
+ *     }
  *   })
  * );
  * ```
  *
- * @param fn - The async function to execute with the workflow data
+ * @param config - Configuration object with execute function and metadata
  * @returns A workflow step that executes the function and returns the result
  */
 declare function andThen<INPUT, DATA, RESULT, SUSPEND_DATA = DangerouslyAllowAny, RESUME_DATA = DangerouslyAllowAny>({ execute, inputSchema, outputSchema, suspendSchema, resumeSchema, ...config }: WorkflowStepFuncConfig<INPUT, DATA, RESULT, SUSPEND_DATA, RESUME_DATA>): WorkflowStepFunc<INPUT, DATA, RESULT, SUSPEND_DATA, RESUME_DATA>;
@@ -4904,24 +4953,25 @@ declare function andThen<INPUT, DATA, RESULT, SUSPEND_DATA = DangerouslyAllowAny
  * ```ts
  * const w = createWorkflow(
  *   andWhen({
- *     condition: (data) => data.userType === "admin",
- *     stepOrFunc: andThen(async (data) => {
+ *     id: "admin-permissions",
+ *     condition: async ({ data }) => data.userType === "admin",
+ *     execute: async ({ data }) => {
  *       return { ...data, permissions: ["read", "write", "delete"] };
- *     })
+ *     }
  *   }),
  *   andWhen({
- *       condition: (data) => data.value > 100,
- *     andAgent(
- *       (data) => `Process high value transaction: ${data.value}`,
+ *     id: "high-value-processing",
+ *     condition: async ({ data }) => data.value > 100,
+ *     step: andAgent(
+ *       ({ data }) => `Process high value transaction: ${data.value}`,
  *       agent,
  *       { schema: z.object({ processed: z.boolean() }) }
  *     )
- *   )
+ *   })
  * );
  * ```
  *
- * @param condition - Function that determines if the step should execute based on the input data
- * @param stepOrFunc - Either a workflow step or an agent to execute when the condition is true
+ * @param config - Configuration object with condition, step/execute function, and metadata
  * @returns A conditional workflow step that executes the step only when the condition evaluates to true
  */
 declare function andWhen<INPUT, DATA, RESULT>({ condition, step, inputSchema, outputSchema, suspendSchema, resumeSchema, ...config }: WorkflowStepConditionalWhenConfig<INPUT, DATA, RESULT>): WorkflowStepConditionalWhen<INPUT, DATA, RESULT>;
@@ -4932,35 +4982,47 @@ declare function andWhen<INPUT, DATA, RESULT>({ condition, step, inputSchema, ou
  * @example
  * ```ts
  * const w = createWorkflow(
- *   andAll([
- *     andThen(async (data) => {
- *       const userInfo = await fetchUserInfo(data.userId);
- *       return { userInfo };
- *     }),
- *     andThen(async (data) => {
- *       const permissions = await fetchPermissions(data.userId);
- *       return { permissions };
- *     }),
- *     andAgent(
- *       (data) => `Generate recommendations for user ${data.userId}`,
- *       agent,
- *       { schema: z.object({ recommendations: z.array(z.string()) }) }
- *     )
- *   ]),
- *   andThen(async (data) => {
- *     // data is now an array: [{ userInfo }, { permissions }, { recommendations }]
- *     return { combined: data.flat() };
+ *   andAll({
+ *     id: "parallel-fetch",
+ *     steps: [
+ *       andThen({
+ *         id: "fetch-user",
+ *         execute: async ({ data }) => {
+ *           const userInfo = await fetchUserInfo(data.userId);
+ *           return { userInfo };
+ *         }
+ *       }),
+ *       andThen({
+ *         id: "fetch-permissions",
+ *         execute: async ({ data }) => {
+ *           const permissions = await fetchPermissions(data.userId);
+ *           return { permissions };
+ *         }
+ *       }),
+ *       andAgent(
+ *         ({ data }) => `Generate recommendations for user ${data.userId}`,
+ *         agent,
+ *         { schema: z.object({ recommendations: z.array(z.string()) }) }
+ *       )
+ *     ]
+ *   }),
+ *   andThen({
+ *     id: "combine-results",
+ *     execute: async ({ data }) => {
+ *       // data is now an array: [{ userInfo }, { permissions }, { recommendations }]
+ *       return { combined: data.flat() };
+ *     }
  *   })
  * );
  * ```
  *
- * @param steps - Array of workflow steps to execute in parallel
+ * @param config - Configuration object with steps array and metadata
  * @returns A workflow step that executes all steps simultaneously and returns their results as an array
  */
-declare function andAll<INPUT, DATA, RESULT, STEPS extends ReadonlyArray<InternalAnyWorkflowStep<INPUT, DATA, RESULT>>, INFERRED_RESULT = InternalInferWorkflowStepsResult<STEPS>>({ steps, ...config }: WorkflowStepParallelAllConfig<STEPS>): {
+declare function andAll<INPUT, DATA, RESULT, STEPS extends ReadonlyArray<InternalAnyWorkflowStep<INPUT, DATA, RESULT>>>({ steps, ...config }: WorkflowStepParallelAllConfig<STEPS>): {
     type: "parallel-all";
-    steps: InternalAnyWorkflowStep<INPUT, DATA, INFERRED_RESULT>[];
-    execute: (context: WorkflowExecuteContext<INPUT, DATA, any, any>) => Promise<INFERRED_RESULT>;
+    steps: InternalAnyWorkflowStep<INPUT, DATA, InternalInferWorkflowStepsResult<STEPS>>[];
+    execute: (context: WorkflowExecuteContext<INPUT, DATA, any, any>) => Promise<InternalInferWorkflowStepsResult<STEPS>>;
     id: string;
     name: string;
     purpose: string;
@@ -4972,39 +5034,51 @@ declare function andAll<INPUT, DATA, RESULT, STEPS extends ReadonlyArray<Interna
  * @example
  * ```ts
  * const w = createWorkflow(
- *   andRace([
- *     andThen(async (data) => {
- *       // Fast operation
- *       const cacheResult = await checkCache(data.query);
- *       return { source: "cache", result: cacheResult };
- *     }),
- *     andThen(async (data) => {
- *       // Slower operation
- *       const dbResult = await queryDatabase(data.query);
- *       return { source: "database", result: dbResult };
- *     }),
- *     andAgent(
- *       (data) => `Generate fallback response for: ${data.query}`,
- *       agent,
- *       { schema: z.object({ source: z.literal("ai"), result: z.string() }) }
- *     )
- *   ]),
- *   andThen(async (data) => {
- *     // data is the result from whichever step completed first
- *     return { finalResult: data.result, source: data.source };
+ *   andRace({
+ *     id: "race-data-sources",
+ *     steps: [
+ *       andThen({
+ *         id: "check-cache",
+ *         execute: async ({ data }) => {
+ *           // Fast operation
+ *           const cacheResult = await checkCache(data.query);
+ *           return { source: "cache", result: cacheResult };
+ *         }
+ *       }),
+ *       andThen({
+ *         id: "query-database",
+ *         execute: async ({ data }) => {
+ *           // Slower operation
+ *           const dbResult = await queryDatabase(data.query);
+ *           return { source: "database", result: dbResult };
+ *         }
+ *       }),
+ *       andAgent(
+ *         ({ data }) => `Generate fallback response for: ${data.query}`,
+ *         agent,
+ *         { schema: z.object({ source: z.literal("ai"), result: z.string() }) }
+ *       )
+ *     ]
+ *   }),
+ *   andThen({
+ *     id: "process-result",
+ *     execute: async ({ data }) => {
+ *       // data is the result from whichever step completed first
+ *       return { finalResult: data.result, source: data.source };
+ *     }
  *   })
  * );
  * ```
  *
- * @param steps - Array of workflow steps to execute in parallel
+ * @param config - Configuration object with steps array and metadata
  * @returns A workflow step that executes all steps simultaneously and returns the result from the first step to complete
  */
-declare function andRace<INPUT, DATA, RESULT, STEPS extends ReadonlyArray<InternalAnyWorkflowStep<INPUT, DATA, RESULT>>, INFERRED_RESULT = InternalInferWorkflowStepsResult<STEPS>[number]>({ steps, ...config }: InternalWorkflowStepConfig<{
+declare function andRace<INPUT, DATA, RESULT, STEPS extends ReadonlyArray<InternalAnyWorkflowStep<INPUT, DATA, RESULT>>>({ steps, ...config }: InternalWorkflowStepConfig<{
     steps: STEPS;
 }>): {
     type: "parallel-race";
-    steps: InternalAnyWorkflowStep<INPUT, DATA, INFERRED_RESULT>[];
-    execute: (context: WorkflowExecuteContext<INPUT, DATA, any, any>) => Promise<INFERRED_RESULT>;
+    steps: InternalAnyWorkflowStep<INPUT, DATA, InternalInferWorkflowStepsResult<STEPS>[number]>[];
+    execute: (context: WorkflowExecuteContext<INPUT, DATA, any, any>) => Promise<InternalInferWorkflowStepsResult<STEPS>[number]>;
     id: string;
     name: string;
     purpose: string;
@@ -5012,7 +5086,27 @@ declare function andRace<INPUT, DATA, RESULT, STEPS extends ReadonlyArray<Intern
 
 /**
  * A safe way to tap into the workflow state without affecting the result.
- * @param fn - The async function to execute
+ *
+ * @example
+ * ```ts
+ * const w = createWorkflow(
+ *   andTap({
+ *     id: "log-processing",
+ *     execute: async ({ data }) => {
+ *       console.log("Processing data:", data);
+ *     }
+ *   }),
+ *   andThen({
+ *     id: "process-data",
+ *     execute: async ({ data }) => {
+ *       // data is unchanged from the tap step
+ *       return { ...data, processed: true };
+ *     }
+ *   })
+ * );
+ * ```
+ *
+ * @param config - Configuration object with execute function and metadata
  * @returns A workflow step that executes the function
  */
 declare function andTap<INPUT, DATA, RESULT, SUSPEND_DATA = DangerouslyAllowAny, RESUME_DATA = DangerouslyAllowAny>({ execute, inputSchema, suspendSchema, resumeSchema, ...config }: WorkflowStepTapConfig<INPUT, DATA, RESULT, SUSPEND_DATA, RESUME_DATA>): {
@@ -5028,6 +5122,50 @@ declare function andTap<INPUT, DATA, RESULT, SUSPEND_DATA = DangerouslyAllowAny,
 
 /**
  * Creates a workflow from multiple and* functions
+ *
+ * @example
+ * ```ts
+ * const workflow = createWorkflow({
+ *   id: "user-processing",
+ *   name: "User Processing Workflow",
+ *   purpose: "Process user data and generate personalized content",
+ *   input: z.object({ userId: z.string(), userType: z.enum(["admin", "user"]) }),
+ *   result: z.object({ processed: z.boolean(), content: z.string() }),
+ *   memory: new LibSQLStorage({ url: "file:memory.db" }) // Optional workflow-specific memory
+ * },
+ *   andThen({
+ *     id: "fetch-user",
+ *     execute: async ({ data }) => {
+ *       const userInfo = await fetchUserInfo(data.userId);
+ *       return { ...data, userInfo };
+ *     }
+ *   }),
+ *   andWhen({
+ *     id: "admin-permissions",
+ *     condition: async ({ data }) => data.userType === "admin",
+ *     execute: async ({ data }) => ({ ...data, permissions: ["read", "write", "delete"] })
+ *   }),
+ *   andAgent(
+ *     ({ data }) => `Generate personalized content for ${data.userInfo.name}`,
+ *     agent,
+ *     { schema: z.object({ content: z.string() }) }
+ *   ),
+ *   andThen({
+ *     id: "finalize-result",
+ *     execute: async ({ data }) => ({
+ *       processed: true,
+ *       content: data.content
+ *     })
+ *   })
+ * );
+ *
+ * // Run with optional memory override
+ * const result = await workflow.run(
+ *   { userId: "123", userType: "admin" },
+ *   { memory: new LibSQLStorage({ url: "file:memory.db" }) }
+ * );
+ * ```
+ *
  * @param config - The workflow configuration
  * @param steps - Variable number of and* functions to execute
  * @returns A configured workflow instance
@@ -5072,23 +5210,30 @@ type AgentConfig<SCHEMA extends z.ZodTypeAny> = {
  *   result: z.object({ processed: z.boolean(), content: z.string() }),
  *   memory: new LibSQLStorage({ url: "file:memory.db" }) // Optional workflow-specific memory
  * })
- *   .andThen(async (data) => {
- *     const userInfo = await fetchUserInfo(data.userId);
- *     return { ...data, userInfo };
+ *   .andThen({
+ *     id: "fetch-user",
+ *     execute: async ({ data }) => {
+ *       const userInfo = await fetchUserInfo(data.userId);
+ *       return { ...data, userInfo };
+ *     }
+ *   })
+ *   .andWhen({
+ *     id: "admin-permissions",
+ *     condition: async ({ data }) => data.userType === "admin",
+ *     execute: async ({ data }) => ({ ...data, permissions: ["read", "write", "delete"] })
  *   })
- *   .andWhen(
- *     (data) => data.userType === "admin",
- *     async (data) => ({ ...data, permissions: ["read", "write", "delete"] })
- *   )
  *   .andAgent(
- *     (data) => `Generate personalized content for ${data.userInfo.name}`,
+ *     ({ data }) => `Generate personalized content for ${data.userInfo.name}`,
  *     agent,
  *     { schema: z.object({ content: z.string() }) }
  *   )
- *   .andThen(async (data) => ({
- *     processed: true,
- *     content: data.content
- *   }));
+ *   .andThen({
+ *     id: "finalize-result",
+ *     execute: async ({ data }) => ({
+ *       processed: true,
+ *       content: data.content
+ *     })
+ *   });
  *
  * // Run with optional memory override
  * const result = await workflow.run(
@@ -5106,13 +5251,20 @@ declare class WorkflowChain<INPUT_SCHEMA extends InternalBaseWorkflowInputSchema
      *
      * @example
      * ```ts
-     * const w = createWorkflowChain<{ name: string }>()
+     * const w = createWorkflowChain({
+     *   id: "greeting-workflow",
+     *   input: z.object({ name: z.string() }),
+     *   result: z.string()
+     * })
      *   .andAgent(
-     *     (data) => `Generate a greeting for the user ${data.name}`,
+     *     ({ data }) => `Generate a greeting for the user ${data.name}`,
      *     agent,
      *     { schema: z.object({ greeting: z.string() }) }
      *   )
-     *   .andThen(async (data) => data.greeting)
+     *   .andThen({
+     *     id: "extract-greeting",
+     *     execute: async ({ data }) => data.greeting
+     *   })
      * ```
      *
      * @param task - The task (prompt) to execute for the agent, can be a string or a function that returns a string
@@ -5290,22 +5442,27 @@ declare class WorkflowChain<INPUT_SCHEMA extends InternalBaseWorkflowInputSchema
      * @example
      * ```ts
      * const workflow = createWorkflowChain(config)
-     *   .andWhen(
-     *     (data) => data.userType === "admin",
-     *     async (data) => ({ ...data, permissions: ["read", "write", "delete"] })
-     *   )
-     *   .andWhen(
-     *     (data) => data.value > 1000,
-     *     async (data) => ({ ...data, flagged: true, requiresReview: true })
-     *   )
-     *   .andWhen(
-     *     (data) => data.status === "pending",
-     *     (data) => andAgent(
-     *       `Process pending request for ${data.userId}`,
-     *       agent,
-     *       { schema: z.object({ processed: z.boolean() }) }
-     *     )
-     *   );
+     *   .andWhen({
+     *     id: "admin-permissions",
+     *     condition: async ({ data }) => data.userType === "admin",
+     *     execute: async ({ data }) => ({ ...data, permissions: ["read", "write", "delete"] })
+     *   })
+     *   .andWhen({
+     *     id: "high-value-flag",
+     *     condition: async ({ data }) => data.value > 1000,
+     *     execute: async ({ data }) => ({ ...data, flagged: true, requiresReview: true })
+     *   })
+     *   .andWhen({
+     *     id: "process-pending",
+     *     condition: async ({ data }) => data.status === "pending",
+     *     execute: async ({ data }) => {
+     *       const result = await agent.generateObject(
+     *         `Process pending request for ${data.userId}`,
+     *         z.object({ processed: z.boolean() })
+     *       );
+     *       return { ...data, ...result.object };
+     *     }
+     *   });
      * ```
      *
      * @param condition - Function that determines if the step should execute based on the current data
@@ -5348,13 +5505,15 @@ declare class WorkflowChain<INPUT_SCHEMA extends InternalBaseWorkflowInputSchema
      * ```ts
      * const workflow = createWorkflowChain(config)
      *   .andTap({
-     *     execute: async (data) => {
+     *     id: "log-translation",
+     *     execute: async ({ data }) => {
      *       console.log("🔄 Translating text:", data);
      *     }
      *   })
      *   .andThen({
+     *     id: "return-translation",
      *     // the input data is still the same as the andTap ONLY executes, it doesn't return anything
-     *     execute: async (data) => {
+     *     execute: async ({ data }) => {
      *       return { ...data, translatedText: data.translatedText };
      *     }
      *   });
@@ -5363,7 +5522,7 @@ declare class WorkflowChain<INPUT_SCHEMA extends InternalBaseWorkflowInputSchema
      * @param fn - The async function to execute with the current workflow data
      * @returns A new chain with the tap step added
      */
-    andTap<NEW_DATA>(config: {
+    andTap<_NEW_DATA>(config: {
         execute: (context: {
             data: CURRENT_DATA;
             state: any;
@@ -5389,9 +5548,12 @@ declare class WorkflowChain<INPUT_SCHEMA extends InternalBaseWorkflowInputSchema
      * import { myWorkflow } from "./my-workflow";
      *
      * const workflow = createWorkflowChain(config)
-     *   .andThen(async (data) => {
-     *     const userInfo = await fetchUserInfo(data.userId);
-     *     return { userInfo };
+     *   .andThen({
+     *     id: "fetch-user",
+     *     execute: async ({ data }) => {
+     *       const userInfo = await fetchUserInfo(data.userId);
+     *       return { userInfo };
+     *     }
      *   })
      *   .andWorkflow(myWorkflow)
      * ```
@@ -5403,24 +5565,41 @@ declare class WorkflowChain<INPUT_SCHEMA extends InternalBaseWorkflowInputSchema
      * @example
      * ```ts
      * const workflow = createWorkflowChain(config)
-     *   .andAll([
-     *     async (data) => {
-     *       const userInfo = await fetchUserInfo(data.userId);
-     *       return { userInfo };
-     *     },
-     *     async (data) => {
-     *       const permissions = await fetchPermissions(data.userId);
-     *       return { permissions };
-     *     },
-     *     (data) => andAgent(
-     *       `Generate recommendations for user ${data.userId}`,
-     *       agent,
-     *       { schema: z.object({ recommendations: z.array(z.string()) }) }
-     *     )
-     *   ])
-     *   .andThen(async (data) => {
-     *     // data is now an array: [{ userInfo }, { permissions }, { recommendations }]
-     *     return { combined: data.flat() };
+     *   .andAll({
+     *     id: "parallel-fetch",
+     *     steps: [
+     *       {
+     *         id: "fetch-user",
+     *         execute: async ({ data }) => {
+     *           const userInfo = await fetchUserInfo(data.userId);
+     *           return { userInfo };
+     *         }
+     *       },
+     *       {
+     *         id: "fetch-permissions",
+     *         execute: async ({ data }) => {
+     *           const permissions = await fetchPermissions(data.userId);
+     *           return { permissions };
+     *         }
+     *       },
+     *       {
+     *         id: "generate-recommendations",
+     *         execute: async ({ data }) => {
+     *           const result = await agent.generateObject(
+     *             `Generate recommendations for user ${data.userId}`,
+     *             z.object({ recommendations: z.array(z.string()) })
+     *           );
+     *           return result.object;
+     *         }
+     *       }
+     *     ]
+     *   })
+     *   .andThen({
+     *     id: "combine-results",
+     *     execute: async ({ data }) => {
+     *       // data is now an array: [{ userInfo }, { permissions }, { recommendations }]
+     *       return { combined: data.flat() };
+     *     }
      *   });
      * ```
      *
@@ -5434,26 +5613,43 @@ declare class WorkflowChain<INPUT_SCHEMA extends InternalBaseWorkflowInputSchema
      * @example
      * ```ts
      * const workflow = createWorkflowChain(config)
-     *   .andRace([
-     *     async (data) => {
-     *       // Fast operation
-     *       const cacheResult = await checkCache(data.query);
-     *       return { source: "cache", result: cacheResult };
-     *     },
-     *     async (data) => {
-     *       // Slower operation
-     *       const dbResult = await queryDatabase(data.query);
-     *       return { source: "database", result: dbResult };
-     *     },
-     *     (data) => andAgent(
-     *       `Generate fallback response for: ${data.query}`,
-     *       agent,
-     *       { schema: z.object({ source: z.literal("ai"), result: z.string() }) }
-     *     )
-     *   ])
-     *   .andThen(async (data) => {
-     *     // data is the result from whichever step completed first
-     *     return { finalResult: data.result, source: data.source };
+     *   .andRace({
+     *     id: "race-data-sources",
+     *     steps: [
+     *       {
+     *         id: "check-cache",
+     *         execute: async ({ data }) => {
+     *           // Fast operation
+     *           const cacheResult = await checkCache(data.query);
+     *           return { source: "cache", result: cacheResult };
+     *         }
+     *       },
+     *       {
+     *         id: "query-database",
+     *         execute: async ({ data }) => {
+     *           // Slower operation
+     *           const dbResult = await queryDatabase(data.query);
+     *           return { source: "database", result: dbResult };
+     *         }
+     *       },
+     *       {
+     *         id: "ai-fallback",
+     *         execute: async ({ data }) => {
+     *           const result = await agent.generateObject(
+     *             `Generate fallback response for: ${data.query}`,
+     *             z.object({ source: z.literal("ai"), result: z.string() })
+     *           );
+     *           return result.object;
+     *         }
+     *       }
+     *     ]
+     *   })
+     *   .andThen({
+     *     id: "process-result",
+     *     execute: async ({ data }) => {
+     *       // data is the result from whichever step completed first
+     *       return { finalResult: data.result, source: data.source };
+     *     }
      *   });
      * ```
      *