@voltagent/core 2.3.0 → 2.3.1

package/dist/index.d.mts

@@ -8697,6 +8697,230 @@ declare class Agent {
     private createWorkingMemoryTools;
 }
 
+/**
+ * WorkflowTraceContext - Manages trace hierarchy and common attributes for workflows
+ *
+ * Similar to AgentTraceContext but tailored for workflow execution:
+ * 1. Common attributes (workflowId, executionId, userId, etc.) are set once and inherited
+ * 2. Parent-child span relationships for workflow steps
+ * 3. Support for parallel step execution
+ * 4. Suspend/resume state tracking
+ * 5. Clean integration with VoltAgentObservability
+ */
+
+interface WorkflowTraceContextOptions {
+    workflowId: string;
+    workflowName: string;
+    executionId: string;
+    userId?: string;
+    conversationId?: string;
+    parentSpan?: Span;
+    input?: any;
+    context?: Map<string | symbol, unknown>;
+    resumedFrom?: {
+        traceId: string;
+        spanId: string;
+    };
+}
+declare class WorkflowTraceContext {
+    private rootSpan;
+    private tracer;
+    private commonAttributes;
+    private activeContext;
+    private stepSpans;
+    constructor(observability: VoltAgentObservability, operationName: string, options: WorkflowTraceContextOptions);
+    /**
+     * Create a child span for a workflow step
+     */
+    createStepSpan(stepIndex: number, stepType: string, stepName: string, options?: {
+        stepId?: string;
+        parentStepId?: string;
+        parallelIndex?: number;
+        input?: any;
+        attributes?: Record<string, any>;
+    }): Span;
+    /**
+     * Create spans for parallel steps
+     */
+    createParallelStepSpans(parentStepIndex: number, parentStepType: string, parentStepName: string, parallelSteps: Array<{
+        index: number;
+        type: string;
+        name: string;
+        id?: string;
+    }>): {
+        parentSpan: Span;
+        childSpans: Span[];
+    };
+    /**
+     * Create a generic child span under the workflow root or an optional parent span
+     */
+    createChildSpan(name: string, type: string, options?: {
+        label?: string;
+        attributes?: Record<string, any>;
+        kind?: SpanKind$1;
+        parentSpan?: Span;
+    }): Span;
+    /**
+     * Record a suspension event on the workflow
+     */
+    recordSuspension(stepIndex: number, reason: string, suspendData?: any, checkpoint?: any): void;
+    /**
+     * Record a cancellation event on the workflow
+     */
+    recordCancellation(reason?: string): void;
+    /**
+     * Record a resume event on the workflow
+     */
+    recordResume(stepIndex: number, resumeData?: any): void;
+    /**
+     * Execute a function within a span's context
+     */
+    withSpan<T>(span: Span, fn: () => T | Promise<T>): Promise<T>;
+    /**
+     * Get the root span
+     */
+    getRootSpan(): Span;
+    /**
+     * Set input on the root span
+     */
+    setInput(input: any): void;
+    /**
+     * Set output on the root span
+     */
+    setOutput(output: any): void;
+    /**
+     * Set usage information on the root span
+     */
+    setUsage(usage: any): void;
+    /**
+     * End the root span with a status
+     */
+    end(status: "completed" | "suspended" | "cancelled" | "error", error?: Error | any): void;
+    /**
+     * End a step span with proper status
+     */
+    endStepSpan(span: Span, status: "completed" | "skipped" | "suspended" | "cancelled" | "error", options?: {
+        output?: any;
+        error?: Error | any;
+        attributes?: Record<string, any>;
+        skippedReason?: string;
+        suspensionReason?: string;
+        cancellationReason?: string;
+    }): void;
+    /**
+     * Get the active context for manual context propagation
+     */
+    getActiveContext(): Context;
+    /**
+     * Update active context with a new span
+     */
+    updateActiveContext(span: Span): void;
+    /**
+     * Clear step spans (useful for cleanup after parallel execution)
+     */
+    clearStepSpans(): void;
+}
+
+/**
+ * Context information for a workflow execution
+ * Contains all the runtime information about a workflow execution
+ */
+interface WorkflowExecutionContext {
+    /**
+     * Unique identifier for the workflow definition
+     */
+    workflowId: string;
+    /**
+     * Unique identifier for this specific execution
+     */
+    executionId: string;
+    /**
+     * Human-readable name of the workflow
+     */
+    workflowName: string;
+    /**
+     * User-defined context passed around during execution
+     */
+    context: Map<string | symbol, unknown>;
+    /**
+     * Shared workflow state available to all steps
+     */
+    workflowState: WorkflowStateStore;
+    /**
+     * Whether the workflow is still actively running
+     */
+    isActive: boolean;
+    /**
+     * When the workflow execution started
+     */
+    startTime: Date;
+    /**
+     * Current step index being executed
+     */
+    currentStepIndex: number;
+    /**
+     * Array of completed steps (for tracking)
+     */
+    steps: any[];
+    /**
+     * AbortSignal for cancelling the workflow
+     */
+    signal?: AbortSignal;
+    /**
+     * Memory storage instance for this workflow execution
+     * Can be workflow-specific or global
+     */
+    memory?: Memory;
+    /**
+     * Map of executed step data (input and output) by step ID
+     * Used for accessing previous step results
+     */
+    stepData: Map<string, WorkflowStepData>;
+    /**
+     * Current event sequence number for this workflow execution
+     * Used to maintain event ordering even after server restarts
+     */
+    eventSequence: number;
+    /**
+     * Logger instance for this workflow execution
+     * Provides execution-scoped logging with full context (userId, conversationId, executionId)
+     */
+    logger: Logger;
+    /**
+     * Stream writer for emitting events during streaming execution
+     * Always available - uses NoOpWorkflowStreamWriter when not streaming
+     */
+    streamWriter: WorkflowStreamWriter;
+    /**
+     * OpenTelemetry trace context for observability
+     * Manages span hierarchy and attributes for the workflow execution
+     */
+    traceContext?: WorkflowTraceContext;
+    /**
+     * Optional agent instance supplied to workflow guardrails
+     */
+    guardrailAgent?: Agent;
+    /**
+     * Current step span for passing to agents called within workflow steps
+     * This enables agent spans to appear as children of workflow step spans
+     */
+    currentStepSpan?: Span;
+}
+/**
+ * Workflow step context for individual step tracking
+ */
+interface WorkflowStepContext {
+    stepId: string;
+    stepIndex: number;
+    stepType: "agent" | "func" | "conditional-when" | "parallel-all" | "parallel-race" | "tap" | "workflow" | "guardrail" | "sleep" | "sleep-until" | "foreach" | "loop" | "branch" | "map";
+    stepName: string;
+    workflowId: string;
+    executionId: string;
+    parentStepId?: string;
+    parallelIndex?: number;
+    startTime: Date;
+}
+
 type WorkflowStateStatus = "pending" | "running" | "completed" | "failed" | "suspended" | "cancelled";
 type WorkflowState<INPUT, RESULT> = {
     executionId: string;
@@ -9367,252 +9591,18 @@ type WorkflowStepState<INPUT> = Omit<WorkflowState<INPUT, DangerouslyAllowAny>,
     signal?: AbortSignal;
 };
 
-/**
- * WorkflowTraceContext - Manages trace hierarchy and common attributes for workflows
- *
- * Similar to AgentTraceContext but tailored for workflow execution:
- * 1. Common attributes (workflowId, executionId, userId, etc.) are set once and inherited
- * 2. Parent-child span relationships for workflow steps
- * 3. Support for parallel step execution
- * 4. Suspend/resume state tracking
- * 5. Clean integration with VoltAgentObservability
- */
-
-interface WorkflowTraceContextOptions {
-    workflowId: string;
-    workflowName: string;
-    executionId: string;
-    userId?: string;
-    conversationId?: string;
-    parentSpan?: Span;
-    input?: any;
-    context?: Map<string | symbol, unknown>;
-    resumedFrom?: {
-        traceId: string;
-        spanId: string;
-    };
-}
-declare class WorkflowTraceContext {
-    private rootSpan;
-    private tracer;
-    private commonAttributes;
-    private activeContext;
-    private stepSpans;
-    constructor(observability: VoltAgentObservability, operationName: string, options: WorkflowTraceContextOptions);
-    /**
-     * Create a child span for a workflow step
-     */
-    createStepSpan(stepIndex: number, stepType: string, stepName: string, options?: {
-        stepId?: string;
-        parentStepId?: string;
-        parallelIndex?: number;
-        input?: any;
-        attributes?: Record<string, any>;
-    }): Span;
-    /**
-     * Create spans for parallel steps
-     */
-    createParallelStepSpans(parentStepIndex: number, parentStepType: string, parentStepName: string, parallelSteps: Array<{
-        index: number;
-        type: string;
-        name: string;
-        id?: string;
-    }>): {
-        parentSpan: Span;
-        childSpans: Span[];
-    };
-    /**
-     * Create a generic child span under the workflow root or an optional parent span
-     */
-    createChildSpan(name: string, type: string, options?: {
-        label?: string;
-        attributes?: Record<string, any>;
-        kind?: SpanKind$1;
-        parentSpan?: Span;
-    }): Span;
-    /**
-     * Record a suspension event on the workflow
-     */
-    recordSuspension(stepIndex: number, reason: string, suspendData?: any, checkpoint?: any): void;
-    /**
-     * Record a cancellation event on the workflow
-     */
-    recordCancellation(reason?: string): void;
-    /**
-     * Record a resume event on the workflow
-     */
-    recordResume(stepIndex: number, resumeData?: any): void;
-    /**
-     * Execute a function within a span's context
-     */
-    withSpan<T>(span: Span, fn: () => T | Promise<T>): Promise<T>;
-    /**
-     * Get the root span
-     */
-    getRootSpan(): Span;
-    /**
-     * Set input on the root span
-     */
-    setInput(input: any): void;
-    /**
-     * Set output on the root span
-     */
-    setOutput(output: any): void;
-    /**
-     * Set usage information on the root span
-     */
-    setUsage(usage: any): void;
-    /**
-     * End the root span with a status
-     */
-    end(status: "completed" | "suspended" | "cancelled" | "error", error?: Error | any): void;
-    /**
-     * End a step span with proper status
-     */
-    endStepSpan(span: Span, status: "completed" | "skipped" | "suspended" | "cancelled" | "error", options?: {
-        output?: any;
-        error?: Error | any;
-        attributes?: Record<string, any>;
-        skippedReason?: string;
-        suspensionReason?: string;
-        cancellationReason?: string;
-    }): void;
-    /**
-     * Get the active context for manual context propagation
-     */
-    getActiveContext(): Context;
-    /**
-     * Update active context with a new span
-     */
-    updateActiveContext(span: Span): void;
-    /**
-     * Clear step spans (useful for cleanup after parallel execution)
-     */
-    clearStepSpans(): void;
-}
-
-/**
- * Context information for a workflow execution
- * Contains all the runtime information about a workflow execution
- */
-interface WorkflowExecutionContext {
-    /**
-     * Unique identifier for the workflow definition
-     */
-    workflowId: string;
-    /**
-     * Unique identifier for this specific execution
-     */
-    executionId: string;
-    /**
-     * Human-readable name of the workflow
-     */
-    workflowName: string;
-    /**
-     * User-defined context passed around during execution
-     */
-    context: Map<string | symbol, unknown>;
-    /**
-     * Shared workflow state available to all steps
-     */
-    workflowState: WorkflowStateStore;
-    /**
-     * Whether the workflow is still actively running
-     */
-    isActive: boolean;
-    /**
-     * When the workflow execution started
-     */
-    startTime: Date;
-    /**
-     * Current step index being executed
-     */
-    currentStepIndex: number;
-    /**
-     * Array of completed steps (for tracking)
-     */
-    steps: any[];
-    /**
-     * AbortSignal for cancelling the workflow
-     */
-    signal?: AbortSignal;
-    /**
-     * Memory storage instance for this workflow execution
-     * Can be workflow-specific or global
-     */
-    memory?: Memory;
-    /**
-     * Map of executed step data (input and output) by step ID
-     * Used for accessing previous step results
-     */
-    stepData: Map<string, WorkflowStepData>;
-    /**
-     * Current event sequence number for this workflow execution
-     * Used to maintain event ordering even after server restarts
-     */
-    eventSequence: number;
-    /**
-     * Logger instance for this workflow execution
-     * Provides execution-scoped logging with full context (userId, conversationId, executionId)
-     */
-    logger: Logger;
-    /**
-     * Stream writer for emitting events during streaming execution
-     * Always available - uses NoOpWorkflowStreamWriter when not streaming
-     */
-    streamWriter: WorkflowStreamWriter;
-    /**
-     * OpenTelemetry trace context for observability
-     * Manages span hierarchy and attributes for the workflow execution
-     */
-    traceContext?: WorkflowTraceContext;
-    /**
-     * Optional agent instance supplied to workflow guardrails
-     */
-    guardrailAgent?: Agent;
-    /**
-     * Current step span for passing to agents called within workflow steps
-     * This enables agent spans to appear as children of workflow step spans
-     */
-    currentStepSpan?: Span;
-}
-/**
- * Workflow step context for individual step tracking
- */
-interface WorkflowStepContext {
-    stepId: string;
-    stepIndex: number;
-    stepType: "agent" | "func" | "conditional-when" | "parallel-all" | "parallel-race" | "tap" | "workflow" | "guardrail" | "sleep" | "sleep-until" | "foreach" | "loop" | "branch" | "map";
-    stepName: string;
-    workflowId: string;
-    executionId: string;
-    parentStepId?: string;
-    parallelIndex?: number;
-    startTime: Date;
-}
-
 /**
  * The base input type for the workflow
  * @private - INTERNAL USE ONLY
  */
 type InternalBaseWorkflowInputSchema = z.ZodTypeAny | BaseMessage | BaseMessage[] | UIMessage | UIMessage[] | string;
-/**
- * The state parameter for the workflow, used to pass the state to a step or other function (i.e. hooks)
- * @private - INTERNAL USE ONLY
- */
-type InternalWorkflowStateParam<INPUT> = Omit<WorkflowState<INPUT, DangerouslyAllowAny>, "data" | "result"> & {
-    /** Workflow execution context for event tracking */
-    workflowContext?: WorkflowExecutionContext;
-    /** AbortSignal for checking suspension during step execution */
-    signal?: AbortSignal;
-};
 /**
  * Context object for new execute API with helper functions
  * @private - INTERNAL USE ONLY
  */
 interface WorkflowExecuteContext<INPUT, DATA, SUSPEND_DATA, RESUME_DATA> {
     data: DATA;
-    state: InternalWorkflowStateParam<INPUT>;
+    state: WorkflowStepState<INPUT>;
     getStepData: (stepId: string) => WorkflowStepData | undefined;
     suspend: (reason?: string, suspendData?: SUSPEND_DATA) => Promise<never>;
     resumeData?: RESUME_DATA;