@voltagent/core 0.1.78 → 0.1.80

package/dist/index.d.mts

@@ -269,6 +269,11 @@ interface WorkflowExecuteContext<INPUT, DATA, SUSPEND_DATA, RESUME_DATA> {
      * Provides execution-scoped logging with full context (userId, conversationId, executionId).
      */
     logger: Logger;
+    /**
+     * Stream writer for emitting events during streaming execution.
+     * Always available for writing custom events.
+     */
+    writer: WorkflowStreamWriter;
 }
 /**
  * A function that can be executed by the workflow
@@ -371,6 +376,8 @@ type WorkflowState<INPUT, RESULT> = {
     error: Error | null;
     /** suspension metadata when workflow is suspended */
     suspension?: WorkflowSuspensionMetadata;
+    /** accumulated usage from andAgent calls */
+    usage: UsageInfo;
 };
 
 interface WorkflowSuspensionMetadata<SUSPEND_DATA = DangerouslyAllowAny> {
@@ -441,6 +448,10 @@ interface WorkflowExecutionResult<RESULT_SCHEMA extends z.ZodTypeAny, RESUME_SCH
      * The result data if workflow completed successfully
      */
     result: z.infer<RESULT_SCHEMA> | null;
+    /**
+     * Stream of workflow events for real-time monitoring
+     */
+    stream: AsyncIterableIterator<WorkflowStreamEvent>;
     /**
      * Suspension metadata if workflow was suspended
      */
@@ -449,6 +460,10 @@ interface WorkflowExecutionResult<RESULT_SCHEMA extends z.ZodTypeAny, RESUME_SCH
      * Error information if workflow failed
      */
     error?: unknown;
+    /**
+     * Total token usage from all andAgent steps in the workflow
+     */
+    usage: UsageInfo;
     /**
      * Resume a suspended workflow execution
      * @param input - Optional new input data for resuming (validated against resumeSchema if provided)
@@ -650,7 +665,8 @@ type Workflow<INPUT_SCHEMA extends InternalBaseWorkflowInputSchema, RESULT_SCHEM
     /**
      * Execute the workflow with the given input
      * @param input - The input to the workflow
-     * @returns The result of the workflow
+     * @param options - Options for the workflow execution
+     * @returns Execution result with stream and final result
      */
     run: (input: WorkflowInput<INPUT_SCHEMA>, options?: WorkflowRunOptions) => Promise<WorkflowExecutionResult<RESULT_SCHEMA, RESUME_SCHEMA>>;
     /**
@@ -744,6 +760,80 @@ interface WorkflowStats {
     averageExecutionTime: number;
     lastExecutionTime?: Date;
 }
+/**
+ * Event emitted during workflow streaming
+ */
+interface WorkflowStreamEvent {
+    /**
+     * Type of the event (e.g., "step-start", "step-complete", "custom", "agent-stream")
+     */
+    type: string;
+    /**
+     * Unique execution ID for this workflow run
+     */
+    executionId: string;
+    /**
+     * Source of the event (step ID or name)
+     */
+    from: string;
+    /**
+     * Input data for the step/event
+     */
+    input?: Record<string, DangerouslyAllowAny>;
+    /**
+     * Output data from the step/event
+     */
+    output?: Record<string, DangerouslyAllowAny>;
+    /**
+     * Current status of the step/event
+     */
+    status: "pending" | "running" | "success" | "error" | "suspended";
+    /**
+     * User context passed through the workflow
+     */
+    userContext?: UserContext;
+    /**
+     * Timestamp of the event
+     */
+    timestamp: string;
+    /**
+     * Current step index in the workflow
+     */
+    stepIndex?: number;
+    /**
+     * Step type for step events
+     */
+    stepType?: "agent" | "func" | "conditional-when" | "parallel-all" | "parallel-race" | "tap" | "workflow";
+    /**
+     * Additional metadata
+     */
+    metadata?: Record<string, DangerouslyAllowAny>;
+    /**
+     * Error information if status is "error"
+     */
+    error?: DangerouslyAllowAny;
+}
+/**
+ * Writer interface for emitting stream events from workflow steps
+ */
+interface WorkflowStreamWriter {
+    /**
+     * Write a custom event to the stream
+     */
+    write(event: Partial<WorkflowStreamEvent> & {
+        type: string;
+    }): void;
+    /**
+     * Pipe events from an agent's fullStream to the workflow stream
+     * @param fullStream - The agent's fullStream async iterable
+     * @param options - Optional configuration for piping
+     */
+    pipeFrom(fullStream: AsyncIterable<DangerouslyAllowAny>, options?: {
+        prefix?: string;
+        agentId?: string;
+        filter?: (part: DangerouslyAllowAny) => boolean;
+    }): Promise<void>;
+}
 /**
  * Options for creating workflow execution
  */
@@ -842,6 +932,11 @@ interface WorkflowExecutionContext {
      * Provides execution-scoped logging with full context (userId, conversationId, executionId)
      */
     logger: Logger;
+    /**
+     * Stream writer for emitting events during streaming execution
+     * Always available for writing custom events
+     */
+    streamWriter: WorkflowStreamWriter;
 }
 /**
  * Workflow step context for individual step tracking
@@ -1906,6 +2001,23 @@ type ProviderOptions = {
 /**
  * Configuration for supervisor agents that have subagents
  */
+/**
+ * Configuration for forwarding events from subagents to the parent agent's stream
+ */
+type FullStreamEventForwardingConfig = {
+    /**
+     * Array of event types to forward from subagents
+     * Uses StreamEventType which includes: 'text-delta', 'reasoning', 'source', 'tool-call', 'tool-result', 'finish', 'error'
+     * @default ['tool-call', 'tool-result']
+     * @example ['tool-call', 'tool-result', 'text-delta', 'reasoning', 'source']
+     */
+    types?: StreamEventType[];
+    /**
+     * Whether to add the subagent name as a prefix to tool names in forwarded events
+     * @default true
+     */
+    addSubAgentPrefix?: boolean;
+};
 type SupervisorConfig = {
     /**
      * Complete custom system message for the supervisor agent
@@ -1922,6 +2034,12 @@ type SupervisorConfig = {
      * Additional custom guidelines for the supervisor agent
      */
     customGuidelines?: string[];
+    /**
+     * Configuration for forwarding events from subagents to the parent agent's full stream
+     * Controls which event types are forwarded and how they are formatted
+     * @default { types: ['tool-call', 'tool-result'], addSubAgentPrefix: true }
+     */
+    fullStreamEventForwarding?: FullStreamEventForwardingConfig;
 };
 /**
  * Agent configuration options
@@ -4494,13 +4612,18 @@ declare class SubAgentManager {
      * Can be either direct Agent instances or SubAgentConfigObject instances
      */
     private subAgentConfigs;
+    /**
+     * Supervisor configuration including event forwarding settings
+     */
+    private supervisorConfig?;
     /**
      * Creates a new SubAgentManager instance
      *
      * @param agentName - The name of the agent that owns this sub-agent manager
      * @param subAgents - Initial sub-agent configurations to add
+     * @param supervisorConfig - Optional supervisor configuration including event forwarding
      */
-    constructor(agentName: string, subAgents?: SubAgentConfig[]);
+    constructor(agentName: string, subAgents?: SubAgentConfig[], supervisorConfig?: SupervisorConfig);
     /**
      * Add a sub-agent that the parent agent can delegate tasks to
      */
@@ -5436,6 +5559,8 @@ declare class WorkflowChain<INPUT_SCHEMA extends InternalBaseWorkflowInputSchema
             } | undefined;
             suspend: (reason?: string, suspendData?: SS extends z.ZodTypeAny ? z.infer<SS> : z.infer<SUSPEND_SCHEMA>) => Promise<never>;
             resumeData?: RS extends z.ZodTypeAny ? z.infer<RS> : z.infer<RESUME_SCHEMA>;
+            logger: Logger;
+            writer: WorkflowStreamWriter;
         }) => Promise<z.infer<OS>>;
         id: string;
         name?: string;
@@ -5460,6 +5585,8 @@ declare class WorkflowChain<INPUT_SCHEMA extends InternalBaseWorkflowInputSchema
             } | undefined;
             suspend: (reason?: string, suspendData?: SS extends z.ZodTypeAny ? z.infer<SS> : z.infer<SUSPEND_SCHEMA>) => Promise<never>;
             resumeData?: RS extends z.ZodTypeAny ? z.infer<RS> : z.infer<RESUME_SCHEMA>;
+            logger: Logger;
+            writer: WorkflowStreamWriter;
         }) => Promise<NEW_DATA>;
         id: string;
         name?: string;
@@ -5484,6 +5611,8 @@ declare class WorkflowChain<INPUT_SCHEMA extends InternalBaseWorkflowInputSchema
             } | undefined;
             suspend: (reason?: string, suspendData?: SS extends z.ZodTypeAny ? z.infer<SS> : z.infer<SUSPEND_SCHEMA>) => Promise<never>;
             resumeData?: RS extends z.ZodTypeAny ? z.infer<RS> : z.infer<RESUME_SCHEMA>;
+            logger: Logger;
+            writer: WorkflowStreamWriter;
         }) => Promise<z.infer<OS>>;
         id: string;
         name?: string;
@@ -5508,6 +5637,8 @@ declare class WorkflowChain<INPUT_SCHEMA extends InternalBaseWorkflowInputSchema
             } | undefined;
             suspend: (reason?: string, suspendData?: SS extends z.ZodTypeAny ? z.infer<SS> : z.infer<SUSPEND_SCHEMA>) => Promise<never>;
             resumeData?: z.infer<RS>;
+            logger: Logger;
+            writer: WorkflowStreamWriter;
         }) => Promise<NEW_DATA>;
         id: string;
         name?: string;
@@ -5548,6 +5679,8 @@ declare class WorkflowChain<INPUT_SCHEMA extends InternalBaseWorkflowInputSchema
             } | undefined;
             suspend: (reason?: string, suspendData?: z.infer<SUSPEND_SCHEMA>) => Promise<never>;
             resumeData?: z.infer<RESUME_SCHEMA>;
+            logger: Logger;
+            writer: WorkflowStreamWriter;
         }) => Promise<NEW_DATA>;
         id: string;
         name?: string;
@@ -5576,6 +5709,8 @@ declare class WorkflowChain<INPUT_SCHEMA extends InternalBaseWorkflowInputSchema
             } | undefined;
             suspend: (reason?: string, suspendData?: SS extends z.ZodTypeAny ? z.infer<SS> : z.infer<SUSPEND_SCHEMA>) => Promise<never>;
             resumeData?: RS extends z.ZodTypeAny ? z.infer<RS> : z.infer<RESUME_SCHEMA>;
+            logger: Logger;
+            writer: WorkflowStreamWriter;
         }) => Promise<boolean>;
     }): WorkflowChain<INPUT_SCHEMA, RESULT_SCHEMA, z.infer<OS> | z.infer<IS>, SUSPEND_SCHEMA, RESUME_SCHEMA>;
     /**
@@ -5635,6 +5770,8 @@ declare class WorkflowChain<INPUT_SCHEMA extends InternalBaseWorkflowInputSchema
             } | undefined;
             suspend: (reason?: string, suspendData?: SS extends z.ZodTypeAny ? z.infer<SS> : z.infer<SUSPEND_SCHEMA>) => Promise<never>;
             resumeData?: RS extends z.ZodTypeAny ? z.infer<RS> : z.infer<RESUME_SCHEMA>;
+            logger: Logger;
+            writer: WorkflowStreamWriter;
         }) => Promise<void>;
         id: string;
         name?: string;
@@ -5674,6 +5811,8 @@ declare class WorkflowChain<INPUT_SCHEMA extends InternalBaseWorkflowInputSchema
             } | undefined;
             suspend: (reason?: string, suspendData?: z.infer<SUSPEND_SCHEMA>) => Promise<never>;
             resumeData?: z.infer<RESUME_SCHEMA>;
+            logger: Logger;
+            writer: WorkflowStreamWriter;
         }) => Promise<void>;
         id: string;
         name?: string;
@@ -6102,6 +6241,8 @@ declare class WorkflowRegistry extends EventEmitter {
         endAt: Date;
         status: "completed" | "suspended" | "error";
         result: any;
+        stream: AsyncIterableIterator<WorkflowStreamEvent>;
+        usage: UsageInfo;
         suspension?: any;
         error?: unknown;
     } | null>;

package/dist/index.d.ts

@@ -269,6 +269,11 @@ interface WorkflowExecuteContext<INPUT, DATA, SUSPEND_DATA, RESUME_DATA> {
      * Provides execution-scoped logging with full context (userId, conversationId, executionId).
      */
     logger: Logger;
+    /**
+     * Stream writer for emitting events during streaming execution.
+     * Always available for writing custom events.
+     */
+    writer: WorkflowStreamWriter;
 }
 /**
  * A function that can be executed by the workflow
@@ -371,6 +376,8 @@ type WorkflowState<INPUT, RESULT> = {
     error: Error | null;
     /** suspension metadata when workflow is suspended */
     suspension?: WorkflowSuspensionMetadata;
+    /** accumulated usage from andAgent calls */
+    usage: UsageInfo;
 };
 
 interface WorkflowSuspensionMetadata<SUSPEND_DATA = DangerouslyAllowAny> {
@@ -441,6 +448,10 @@ interface WorkflowExecutionResult<RESULT_SCHEMA extends z.ZodTypeAny, RESUME_SCH
      * The result data if workflow completed successfully
      */
     result: z.infer<RESULT_SCHEMA> | null;
+    /**
+     * Stream of workflow events for real-time monitoring
+     */
+    stream: AsyncIterableIterator<WorkflowStreamEvent>;
     /**
      * Suspension metadata if workflow was suspended
      */
@@ -449,6 +460,10 @@ interface WorkflowExecutionResult<RESULT_SCHEMA extends z.ZodTypeAny, RESUME_SCH
      * Error information if workflow failed
      */
     error?: unknown;
+    /**
+     * Total token usage from all andAgent steps in the workflow
+     */
+    usage: UsageInfo;
     /**
      * Resume a suspended workflow execution
      * @param input - Optional new input data for resuming (validated against resumeSchema if provided)
@@ -650,7 +665,8 @@ type Workflow<INPUT_SCHEMA extends InternalBaseWorkflowInputSchema, RESULT_SCHEM
     /**
      * Execute the workflow with the given input
      * @param input - The input to the workflow
-     * @returns The result of the workflow
+     * @param options - Options for the workflow execution
+     * @returns Execution result with stream and final result
      */
     run: (input: WorkflowInput<INPUT_SCHEMA>, options?: WorkflowRunOptions) => Promise<WorkflowExecutionResult<RESULT_SCHEMA, RESUME_SCHEMA>>;
     /**
@@ -744,6 +760,80 @@ interface WorkflowStats {
     averageExecutionTime: number;
     lastExecutionTime?: Date;
 }
+/**
+ * Event emitted during workflow streaming
+ */
+interface WorkflowStreamEvent {
+    /**
+     * Type of the event (e.g., "step-start", "step-complete", "custom", "agent-stream")
+     */
+    type: string;
+    /**
+     * Unique execution ID for this workflow run
+     */
+    executionId: string;
+    /**
+     * Source of the event (step ID or name)
+     */
+    from: string;
+    /**
+     * Input data for the step/event
+     */
+    input?: Record<string, DangerouslyAllowAny>;
+    /**
+     * Output data from the step/event
+     */
+    output?: Record<string, DangerouslyAllowAny>;
+    /**
+     * Current status of the step/event
+     */
+    status: "pending" | "running" | "success" | "error" | "suspended";
+    /**
+     * User context passed through the workflow
+     */
+    userContext?: UserContext;
+    /**
+     * Timestamp of the event
+     */
+    timestamp: string;
+    /**
+     * Current step index in the workflow
+     */
+    stepIndex?: number;
+    /**
+     * Step type for step events
+     */
+    stepType?: "agent" | "func" | "conditional-when" | "parallel-all" | "parallel-race" | "tap" | "workflow";
+    /**
+     * Additional metadata
+     */
+    metadata?: Record<string, DangerouslyAllowAny>;
+    /**
+     * Error information if status is "error"
+     */
+    error?: DangerouslyAllowAny;
+}
+/**
+ * Writer interface for emitting stream events from workflow steps
+ */
+interface WorkflowStreamWriter {
+    /**
+     * Write a custom event to the stream
+     */
+    write(event: Partial<WorkflowStreamEvent> & {
+        type: string;
+    }): void;
+    /**
+     * Pipe events from an agent's fullStream to the workflow stream
+     * @param fullStream - The agent's fullStream async iterable
+     * @param options - Optional configuration for piping
+     */
+    pipeFrom(fullStream: AsyncIterable<DangerouslyAllowAny>, options?: {
+        prefix?: string;
+        agentId?: string;
+        filter?: (part: DangerouslyAllowAny) => boolean;
+    }): Promise<void>;
+}
 /**
  * Options for creating workflow execution
  */
@@ -842,6 +932,11 @@ interface WorkflowExecutionContext {
      * Provides execution-scoped logging with full context (userId, conversationId, executionId)
      */
     logger: Logger;
+    /**
+     * Stream writer for emitting events during streaming execution
+     * Always available for writing custom events
+     */
+    streamWriter: WorkflowStreamWriter;
 }
 /**
  * Workflow step context for individual step tracking
@@ -1906,6 +2001,23 @@ type ProviderOptions = {
 /**
  * Configuration for supervisor agents that have subagents
  */
+/**
+ * Configuration for forwarding events from subagents to the parent agent's stream
+ */
+type FullStreamEventForwardingConfig = {
+    /**
+     * Array of event types to forward from subagents
+     * Uses StreamEventType which includes: 'text-delta', 'reasoning', 'source', 'tool-call', 'tool-result', 'finish', 'error'
+     * @default ['tool-call', 'tool-result']
+     * @example ['tool-call', 'tool-result', 'text-delta', 'reasoning', 'source']
+     */
+    types?: StreamEventType[];
+    /**
+     * Whether to add the subagent name as a prefix to tool names in forwarded events
+     * @default true
+     */
+    addSubAgentPrefix?: boolean;
+};
 type SupervisorConfig = {
     /**
      * Complete custom system message for the supervisor agent
@@ -1922,6 +2034,12 @@ type SupervisorConfig = {
      * Additional custom guidelines for the supervisor agent
      */
     customGuidelines?: string[];
+    /**
+     * Configuration for forwarding events from subagents to the parent agent's full stream
+     * Controls which event types are forwarded and how they are formatted
+     * @default { types: ['tool-call', 'tool-result'], addSubAgentPrefix: true }
+     */
+    fullStreamEventForwarding?: FullStreamEventForwardingConfig;
 };
 /**
  * Agent configuration options
@@ -4494,13 +4612,18 @@ declare class SubAgentManager {
      * Can be either direct Agent instances or SubAgentConfigObject instances
      */
     private subAgentConfigs;
+    /**
+     * Supervisor configuration including event forwarding settings
+     */
+    private supervisorConfig?;
     /**
      * Creates a new SubAgentManager instance
      *
      * @param agentName - The name of the agent that owns this sub-agent manager
      * @param subAgents - Initial sub-agent configurations to add
+     * @param supervisorConfig - Optional supervisor configuration including event forwarding
      */
-    constructor(agentName: string, subAgents?: SubAgentConfig[]);
+    constructor(agentName: string, subAgents?: SubAgentConfig[], supervisorConfig?: SupervisorConfig);
     /**
      * Add a sub-agent that the parent agent can delegate tasks to
      */
@@ -5436,6 +5559,8 @@ declare class WorkflowChain<INPUT_SCHEMA extends InternalBaseWorkflowInputSchema
             } | undefined;
             suspend: (reason?: string, suspendData?: SS extends z.ZodTypeAny ? z.infer<SS> : z.infer<SUSPEND_SCHEMA>) => Promise<never>;
             resumeData?: RS extends z.ZodTypeAny ? z.infer<RS> : z.infer<RESUME_SCHEMA>;
+            logger: Logger;
+            writer: WorkflowStreamWriter;
         }) => Promise<z.infer<OS>>;
         id: string;
         name?: string;
@@ -5460,6 +5585,8 @@ declare class WorkflowChain<INPUT_SCHEMA extends InternalBaseWorkflowInputSchema
             } | undefined;
             suspend: (reason?: string, suspendData?: SS extends z.ZodTypeAny ? z.infer<SS> : z.infer<SUSPEND_SCHEMA>) => Promise<never>;
             resumeData?: RS extends z.ZodTypeAny ? z.infer<RS> : z.infer<RESUME_SCHEMA>;
+            logger: Logger;
+            writer: WorkflowStreamWriter;
         }) => Promise<NEW_DATA>;
         id: string;
         name?: string;
@@ -5484,6 +5611,8 @@ declare class WorkflowChain<INPUT_SCHEMA extends InternalBaseWorkflowInputSchema
             } | undefined;
             suspend: (reason?: string, suspendData?: SS extends z.ZodTypeAny ? z.infer<SS> : z.infer<SUSPEND_SCHEMA>) => Promise<never>;
             resumeData?: RS extends z.ZodTypeAny ? z.infer<RS> : z.infer<RESUME_SCHEMA>;
+            logger: Logger;
+            writer: WorkflowStreamWriter;
         }) => Promise<z.infer<OS>>;
         id: string;
         name?: string;
@@ -5508,6 +5637,8 @@ declare class WorkflowChain<INPUT_SCHEMA extends InternalBaseWorkflowInputSchema
             } | undefined;
             suspend: (reason?: string, suspendData?: SS extends z.ZodTypeAny ? z.infer<SS> : z.infer<SUSPEND_SCHEMA>) => Promise<never>;
             resumeData?: z.infer<RS>;
+            logger: Logger;
+            writer: WorkflowStreamWriter;
         }) => Promise<NEW_DATA>;
         id: string;
         name?: string;
@@ -5548,6 +5679,8 @@ declare class WorkflowChain<INPUT_SCHEMA extends InternalBaseWorkflowInputSchema
             } | undefined;
             suspend: (reason?: string, suspendData?: z.infer<SUSPEND_SCHEMA>) => Promise<never>;
             resumeData?: z.infer<RESUME_SCHEMA>;
+            logger: Logger;
+            writer: WorkflowStreamWriter;
         }) => Promise<NEW_DATA>;
         id: string;
         name?: string;
@@ -5576,6 +5709,8 @@ declare class WorkflowChain<INPUT_SCHEMA extends InternalBaseWorkflowInputSchema
             } | undefined;
             suspend: (reason?: string, suspendData?: SS extends z.ZodTypeAny ? z.infer<SS> : z.infer<SUSPEND_SCHEMA>) => Promise<never>;
             resumeData?: RS extends z.ZodTypeAny ? z.infer<RS> : z.infer<RESUME_SCHEMA>;
+            logger: Logger;
+            writer: WorkflowStreamWriter;
         }) => Promise<boolean>;
     }): WorkflowChain<INPUT_SCHEMA, RESULT_SCHEMA, z.infer<OS> | z.infer<IS>, SUSPEND_SCHEMA, RESUME_SCHEMA>;
     /**
@@ -5635,6 +5770,8 @@ declare class WorkflowChain<INPUT_SCHEMA extends InternalBaseWorkflowInputSchema
             } | undefined;
             suspend: (reason?: string, suspendData?: SS extends z.ZodTypeAny ? z.infer<SS> : z.infer<SUSPEND_SCHEMA>) => Promise<never>;
             resumeData?: RS extends z.ZodTypeAny ? z.infer<RS> : z.infer<RESUME_SCHEMA>;
+            logger: Logger;
+            writer: WorkflowStreamWriter;
         }) => Promise<void>;
         id: string;
         name?: string;
@@ -5674,6 +5811,8 @@ declare class WorkflowChain<INPUT_SCHEMA extends InternalBaseWorkflowInputSchema
             } | undefined;
             suspend: (reason?: string, suspendData?: z.infer<SUSPEND_SCHEMA>) => Promise<never>;
             resumeData?: z.infer<RESUME_SCHEMA>;
+            logger: Logger;
+            writer: WorkflowStreamWriter;
         }) => Promise<void>;
         id: string;
         name?: string;
@@ -6102,6 +6241,8 @@ declare class WorkflowRegistry extends EventEmitter {
         endAt: Date;
         status: "completed" | "suspended" | "error";
         result: any;
+        stream: AsyncIterableIterator<WorkflowStreamEvent>;
+        usage: UsageInfo;
         suspension?: any;
         error?: unknown;
     } | null>;