groundswell 0.0.3 → 1.0.0

package/dist/core/workflow.js

@@ -1,4 +1,8 @@
+import { z } from 'zod';
 import { generateId } from '../utils/id.js';
+import { validateAgentResponse } from '../utils/agent-validation.js';
+import { analyzeErrorForRestart } from '../utils/restart-analysis.js';
+import { mergeWorkflowErrors } from '../utils/workflow-error-utils.js';
 import { WorkflowLogger } from './logger.js';
 import { getObservedState } from '../decorators/observed-state.js';
 import { createWorkflowContext } from './workflow-context.js';
@@ -46,16 +50,25 @@ export class Workflow {
     executor;
     /** Workflow configuration */
     config;
+    /** Error collection state for workflow-level error merge */
+    collectedErrors = [];
+    /** Event history entries with insertion timestamps for replay functionality (ES2022 private field) */
+    #eventHistory = [];
+    /** Total operations count for error merge context */
+    totalOperations = 0;
+    /** Operation counter for error merge context */
+    operationCounter = 0;
     /**
      * Create a new workflow instance
      *
-     * @overload Class-based pattern
-     * @param name Human-readable name (defaults to class name)
-     * @param parent Optional parent workflow
+     * @overload Class-based pattern: constructor(name?: string, parent?: Workflow)
+     * @overload Functional pattern: constructor(config: WorkflowConfig, executor?: WorkflowExecutor)
+     * @param name For class-based pattern, human-readable name. Allowed characters: alphanumeric (a-z, A-Z, 0-9), spaces, hyphens (-), underscores (_). (default: class name).
+     * For functional pattern, config object with workflow settings.
+     * @param parentOrExecutor For class-based pattern, optional parent workflow.
+     * For functional pattern, executor function.
      *
-     * @overload Functional pattern
-     * @param config Workflow configuration
-     * @param executor Executor function
+     * @remarks Security validation rejects names containing control characters, HTML tags, JavaScript patterns, path traversal sequences (..), and file system special characters (/ \ : * ? " < > |). This prevents XSS attacks, injection attacks, and path traversal vulnerabilities.
      */
     constructor(name, parentOrExecutor) {
         this.id = generateId();
@@ -80,6 +93,32 @@ export class Workflow {
             if (this.config.name.length > 100) {
                 throw new Error('Workflow name cannot exceed 100 characters');
             }
+            // Shared message for all security validations below.
+            const invalidNameMessage = 'Invalid workflow name. Names may contain letters, numbers, spaces, hyphens, underscores, and emoji.';
+            // Security validation: control characters (ASCII 0x00-0x1F, 0x7F)
+            if (/[\x00-\x1F\x7F]/.test(trimmedName)) {
+                throw new Error(invalidNameMessage);
+            }
+            // Security validation: HTML/JavaScript injection patterns
+            if (/<[^>]*>/.test(trimmedName) || /javascript:/i.test(trimmedName)) {
+                throw new Error(invalidNameMessage);
+            }
+            // Security validation: path traversal patterns
+            if (/\.\./.test(trimmedName)) {
+                throw new Error(invalidNameMessage);
+            }
+            // Security validation: file system special characters
+            if (/[\/\\:*?"<>|]/.test(trimmedName)) {
+                throw new Error(invalidNameMessage);
+            }
+            // Security validation: allowed characters (allowlist - defense in depth)
+            // Unicode-aware: permits letters (\p{L}), numbers (\p{N}), and emoji
+            // (including pictographic bases, variation selectors U+FE0F, and ZWJ
+            // sequences U+200D) from any script, while still blocking exotic or
+            // symbolic characters not covered by the targeted checks above.
+            if (!/^[\p{L}\p{N}\p{Emoji_Presentation}\p{Extended_Pictographic}\u200D\uFE0F _-]+$/u.test(trimmedName)) {
+                throw new Error(invalidNameMessage);
+            }
         }
         // Create the node representation
         this.node = {
@@ -118,6 +157,64 @@ export class Workflow {
         }
         return root.observers;
     }
+    /**
+     * Check if event history is enabled for this workflow
+     *
+     * @returns true if event history is enabled, false otherwise
+     */
+    isEventHistoryEnabled() {
+        return this.config.eventHistory?.enabled === true;
+    }
+    /**
+     * Get event history configuration with defaults applied
+     *
+     * @returns Configuration object with all required fields populated
+     */
+    getEventHistoryConfig() {
+        return {
+            enabled: this.config.eventHistory?.enabled ?? false,
+            maxEvents: this.config.eventHistory?.maxEvents ?? 1000,
+            maxAgeMs: this.config.eventHistory?.maxAgeMs ?? 3600000,
+        };
+    }
+    /**
+     * Trim event history based on configuration
+     *
+     * Uses lazy trimming for performance:
+     * - Only trims when at least 1.5x over the maxEvents limit
+     * - Applies both count and age constraints
+     * - Uses slice() for efficiency (not shift())
+     *
+     * @remarks
+     * Lazy trimming reduces the number of trim operations by only trimming
+     * when the history is significantly over the limit (1.5x). This provides
+     * better performance for high-frequency event emission.
+     */
+    trimEventHistory() {
+        const config = this.getEventHistoryConfig();
+        // Lazy trimming: only trim when significantly over limit
+        const trimThreshold = Math.floor(config.maxEvents * 1.5);
+        if (this.#eventHistory.length < trimThreshold) {
+            return;
+        }
+        const now = Date.now();
+        const ageCutoff = now - config.maxAgeMs;
+        // Age-based trimming: find first entry within age limit
+        let keepFromIndex = 0;
+        for (let i = 0; i < this.#eventHistory.length; i++) {
+            if (this.#eventHistory[i].insertedAt > ageCutoff) {
+                keepFromIndex = i;
+                break;
+            }
+        }
+        // Count-based trimming: remove excess events
+        const countBasedIndex = Math.max(0, this.#eventHistory.length - config.maxEvents);
+        // Use the more aggressive constraint
+        const finalIndex = Math.max(keepFromIndex, countBasedIndex);
+        if (finalIndex > 0) {
+            this.#eventHistory = this.#eventHistory.slice(finalIndex);
+        }
+    }
     /**
      * Check if this workflow is a descendant of the given ancestor workflow.
      *
@@ -126,12 +223,11 @@ export class Workflow {
      * a convenient way to check workflow hierarchy relationships without manually
      * traversing the parent chain.
      *
-     * @warning This method reveals workflow hierarchy information. If your
-     * application exposes workflows via an API, ensure you implement proper
-     * access control to prevent unauthorized topology discovery. Note that
-     * the `parent` and `children` properties are already public, so this
-     * method does not expose any new information beyond what is currently
-     * accessible.
+     * @remarks SECURITY WARNING: This method reveals workflow hierarchy information.
+     * If your application exposes workflows via an API, ensure you implement proper
+     * access control to prevent unauthorized topology discovery. Note that the parent
+     * and children properties are already public, so this method does not expose any
+     * new information beyond what is currently accessible.
      *
      * **Time Complexity**: O(d) where d is the depth of the hierarchy
      * **Space Complexity**: O(d) for the visited Set in worst case (cycle detection)
@@ -203,6 +299,8 @@ export class Workflow {
     /**
      * Add an observer to this workflow (must be root)
      * @throws Error if called on non-root workflow
+     * @side effects Adds observer to internal observers array for root workflows.
+     * Observers will receive notifications for workflow events.
      */
     addObserver(observer) {
         if (this.parent) {
@@ -233,6 +331,7 @@ export class Workflow {
      * - Sets child.parent = this (workflow tree)
      * - Sets child.node.parent = this.node (node tree)
      * - Emits childAttached event to notify observers
+     * - Emits treeUpdated event to trigger tree debugger rebuild
      *
      * **Invariants Maintained:**
      * - Single-parent rule: A workflow can only have one parent
@@ -247,6 +346,8 @@ export class Workflow {
      * @throws {Error} If the child is already attached to this workflow
      * @throws {Error} If the child already has a different parent (use detachChild() first for reparenting)
      * @throws {Error} If the child is an ancestor of this parent (would create circular reference)
+     * @side effects Modifies workflow tree structure, emits childAttached event,
+     * and triggers treeUpdated event for debugger.
      *
      * @example
      * ```ts
@@ -298,7 +399,7 @@ export class Workflow {
         }
         this.children.push(child);
         this.node.children.push(child.node);
-        // Emit child attached event
+        // Emit child attached event (triggers onTreeChanged via emitEvent)
         this.emitEvent({
             type: 'childAttached',
             parentId: this.id,
@@ -312,10 +413,14 @@ export class Workflow {
      * the node tree (this.node.children), clears the child's parent reference,
      * and emits a childDetached event to notify observers.
      *
+     * Also emits treeUpdated event to trigger tree debugger rebuild.
+     *
      * This enables reparenting workflows: oldParent.detachChild(child); newParent.attachChild(child);
      *
      * @param child - The child workflow to detach
      * @throws {Error} If the child is not attached to this parent workflow
+     * @side effects Modifies workflow tree structure, emits childDetached event,
+     * and triggers treeUpdated event for debugger.
      *
      * @example
      * ```ts
@@ -343,7 +448,7 @@ export class Workflow {
         // Clear child's parent reference (both workflow tree and node tree)
         child.parent = null;
         child.node.parent = null; // Maintain 1:1 mirror between workflow tree and node tree
-        // Emit childDetached event
+        // Emit childDetached event (triggers onTreeChanged via emitEvent)
         this.emitEvent({
             type: 'childDetached',
             parentId: this.id,
@@ -352,8 +457,15 @@ export class Workflow {
     }
     /**
      * Emit an event to all root observers
+     * @side effects Pushes event to node.events array and notifies all registered observers.
+     * May trigger treeUpdated notifications for specific event types.
      */
     emitEvent(event) {
+        // Store event in history FIRST (for replay functionality) - only if enabled
+        if (this.isEventHistoryEnabled()) {
+            this.#eventHistory.push({ event, insertedAt: Date.now() });
+            this.trimEventHistory();
+        }
         this.node.events.push(event);
         const observers = this.getRootObservers();
         for (const obs of observers) {
@@ -369,8 +481,117 @@ export class Workflow {
             }
         }
     }
+    /**
+     * Replay historical events to an observer
+     *
+     * **Strategy:**
+     * 1. Start with event history array
+     * 2. Filter by timestamp if `since` is provided
+     * 3. Limit events if `limit` is provided
+     * 4. Call observer.onEvent() for each event
+     * 5. Handle observer errors gracefully
+     *
+     * **Performance:** O(n) where n = number of events in history
+     *
+     * **Timestamp Handling:**
+     * - Events with timestamps: stepRetry, stepRestarted, invalidResponse
+     * - Events without timestamps: Always included (considered timeless)
+     * - Filter applies only to events with timestamp field
+     *
+     * **Order of Operations:** Filter first, then limit (more efficient)
+     *
+     * **Use Case:**
+     * - Catch up new observers to current state
+     * - Debug by replaying events to diagnostic observers
+     * - Test scenarios by replaying historical events
+     *
+     * @param observer - The observer to replay events to
+     * @param options - Optional replay configuration
+     * @param options.since - Only replay events after this timestamp (ms since epoch)
+     * @param options.limit - Maximum number of events to replay
+     *
+     * @example Replay all events to new observer
+     * ```ts
+     * const observer = {
+     *   onLog: () => {},
+     *   onEvent: (e) => console.log(e.type),
+     *   onStateUpdated: () => {},
+     *   onTreeChanged: () => {},
+     * };
+     * workflow.replayEvents(observer);
+     * ```
+     *
+     * @example Replay last 10 events
+     * ```ts
+     * workflow.replayEvents(observer, { limit: 10 });
+     * ```
+     *
+     * @example Replay events from last 5 minutes
+     * ```ts
+     * const fiveMinutesAgo = Date.now() - 5 * 60 * 1000;
+     * workflow.replayEvents(observer, { since: fiveMinutesAgo });
+     * ```
+     */
+    replayEvents(observer, options) {
+        // Extract events from entries
+        let events = this.#eventHistory.map(entry => entry.event);
+        // Filter by timestamp if provided
+        if (options?.since !== undefined) {
+            events = events.filter(event => {
+                // Extract timestamp from events that have it
+                const timestamp = event.type === 'stepRetry' ? event.timestamp :
+                    event.type === 'stepRestarted' ? event.timestamp :
+                        event.type === 'invalidResponse' ? event.timestamp :
+                            undefined;
+                // Include events without timestamp or events after since
+                return timestamp === undefined || timestamp >= options.since;
+            });
+        }
+        // Apply limit if provided
+        if (options?.limit !== undefined) {
+            events = events.slice(0, options.limit);
+        }
+        // Replay events to observer
+        for (const event of events) {
+            try {
+                observer.onEvent(event);
+            }
+            catch (err) {
+                this.logger.error('Observer replay error', { error: err, eventType: event.type });
+            }
+        }
+    }
+    /**
+     * Clear the event history array
+     *
+     * **Strategy:**
+     * - Reassign #eventHistory to empty array
+     * - Frees memory by discarding all stored events
+     * - Events in node.events are preserved
+     *
+     * **Use Case:**
+     * - Free memory after workflow completes
+     * - Reset history between test runs
+     * - Prevent memory leaks in long-running workflows
+     *
+     * **Side Effects:**
+     * - Frees memory for discarded events
+     * - Future replayEvents() calls will return empty
+     * - Does NOT affect node.events array
+     *
+     * @example Clear history after workflow completes
+     * ```ts
+     * await workflow.run();
+     * workflow.clearEventHistory();  // Free memory
+     * ```
+     */
+    clearEventHistory() {
+        this.#eventHistory = [];
+    }
     /**
      * Capture and emit a state snapshot
+     * @side effects Updates node.stateSnapshot, notifies observers via onStateUpdated callback,
+     * emits snapshot event, and triggers treeUpdated event for debugger.
      */
     snapshotState() {
         const snapshot = getObservedState(this);
@@ -393,6 +614,278 @@ export class Workflow {
         // Emit treeUpdated event to trigger tree debugger rebuild
         this.emitEvent({ type: 'treeUpdated', root: this.getRoot().node });
     }
+    /**
+     * Restart a specific step with state restoration and retry tracking
+     *
+     * This method enables manual step restart from parent workflows. It validates
+     * the step exists, checks retry limits, optionally restores state, re-executes
+     * the step method, and emits a stepRestarted event for observability.
+     *
+     * @param stepName - The name of the step method to restart
+     * @param options - Optional configuration for the restart attempt
+     * @returns The result of the step execution
+     * @throws {WorkflowError} When step is not found or max retries exceeded
+     *
+     * @example Restart a step with default retry tracking
+     * ```ts
+     * class MyWorkflow extends Workflow {
+     *   @Step({ restartable: true })
+     *   async myStep() { return 'result'; }
+     *
+     *   async run() {
+     *     const result = await this.restartStep('myStep');
+     *   }
+     * }
+     * ```
+     *
+     * @example Restart with explicit retry count and state override
+     * ```ts
+     * await this.restartStep('failingStep', {
+     *   retryCount: 1,
+     *   maxRetries: 3,
+     *   stateOverride: { counter: 5 }
+     * });
+     * ```
+     */
+    async restartStep(stepName, options) {
+        // Calculate the retry count for this attempt
+        const retryCount = (options?.retryCount ?? 0) + 1;
+        const maxRetries = options?.maxRetries ?? 3;
+        // Check retry limit
+        if (retryCount > maxRetries) {
+            const error = {
+                message: `Max retries (${maxRetries}) exceeded for step '${stepName}'`,
+                original: new Error('Max retries exceeded'),
+                workflowId: this.id,
+                state: getObservedState(this),
+                logs: [...this.node.logs],
+            };
+            throw error;
+        }
+        // Verify the step method exists and is callable
+        const method = this[stepName];
+        if (typeof method !== 'function') {
+            const error = {
+                message: `Step '${stepName}' not found`,
+                original: new Error('Step not found'),
+                workflowId: this.id,
+                state: getObservedState(this),
+                logs: [...this.node.logs],
+            };
+            throw error;
+        }
+        // Restore state - use override if provided, otherwise capture current state
+        let restoredState;
+        if (options?.stateOverride !== undefined) {
+            restoredState = options.stateOverride;
+            // For state override, we'd ideally restore the state here
+            // Since no restoreState() method exists, stateOverride is primarily for the event payload
+            // and any future state restoration implementation
+        }
+        else {
+            // Capture current state as the restored state
+            this.snapshotState();
+            restoredState = this.node.stateSnapshot ?? {};
+        }
+        // Execute the step method
+        const result = await method.call(this);
+        // Emit stepRestarted event
+        this.emitEvent({
+            type: 'stepRestarted',
+            node: this.node,
+            stepName,
+            retryCount,
+            restoredState,
+            timestamp: Date.now(),
+        });
+        return result;
+    }
+    /**
+     * Analyze a WorkflowError from a child workflow and determine restart action
+     *
+     * This method enables parent workflows to make intelligent decisions about child
+     * workflow failures by analyzing the error and step metadata to determine whether
+     * to retry the child, abort the parent, or rebuild the execution plan.
+     *
+     * **Analysis Flow:**
+     * 1. Check `error.original?.recoverable` - if false, return 'abort'
+     * 2. Extract stepName from error metadata (if available)
+     * 3. Retrieve step metadata from stepMetadata map (if exists)
+     * 4. Check if step is marked as restartable - if not, return 'abort'
+     * 5. Use `analyzeErrorForRestart` utility to check retry criteria
+     * 6. Return 'retry' if any criteria match, otherwise 'abort'
+     *
+     * **Integration with restartStep:**
+     * This method is designed to be used alongside `restartStep()`:
+     * - Call `analyzeError()` to get the decision
+     * - If 'retry', call `restartStep(stepName)` to execute
+     * - If 'abort', throw the error or return early
+     * - If 'rebuild', trigger plan rebuild logic
+     *
+     * @param error - The WorkflowError to analyze (typically from child workflow)
+     * @returns The recommended action: 'retry', 'abort', or 'rebuild'
+     *
+     * @example Parent workflow error handling
+     * ```ts
+     * class ParentWorkflow extends Workflow {
+     *   @Step({ restartable: true, retryOn: [{ code: 'TIMEOUT' }] })
+     *   async childWorkflow(): Promise<void> {
+     *     // Child logic that may fail
+     *   }
+     *
+     *   async run(): Promise<void> {
+     *     try {
+     *       await this.childWorkflow();
+     *     } catch (err) {
+     *       const error = err as WorkflowError;
+     *       const action = this.analyzeError(error);
+     *
+     *       if (action === 'retry') {
+     *         await this.restartStep('childWorkflow');
+     *       } else if (action === 'abort') {
+     *         throw error;
+     *       } else if (action === 'rebuild') {
+     *         // Trigger plan rebuild logic
+     *       }
+     *     }
+     *   }
+     * }
+     * ```
+     *
+     * @example Analyze error from child workflow event
+     * ```ts
+     * class ParentWorkflow extends Workflow {
+     *   private lastError: WorkflowError | null = null;
+     *
+     *   async run(): Promise<void> {
+     *     // Subscribe to error events
+     *     this.on('error', (event) => {
+     *       this.lastError = event.error;
+     *     });
+     *
+     *     // Later, analyze the error
+     *     if (this.lastError) {
+     *       const action = this.analyzeError(this.lastError);
+     *       // Take action based on decision
+     *     }
+     *   }
+     * }
+     * ```
+     *
+     * @remarks
+     * **Known Limitation:**
+     * The `stepMetadata` map is not yet populated by the `@Step` decorator.
+     * This method will return 'abort' if stepMetadata is not available or the step
+     * is not found. This will be improved in a future update to the decorator.
+     *
+     * **Error Metadata:**
+     * The stepName is extracted from `error.state?.stepName`. Ensure child
+     * workflows populate this field when creating WorkflowError instances.
+     *
+     * @see {@link restartStep} - For executing a retry after analysis
+     * @see {@link analyzeErrorForRestart} - For the underlying utility function
+     */
+    analyzeError(error) {
+        // STEP 1: Check recoverable flag
+        const original = error.original;
+        if (original && 'recoverable' in original && !original.recoverable) {
+            return 'abort';
+        }
+        // STEP 2: Extract stepName from error metadata
+        // GOTCHA: WorkflowError doesn't have stepName property
+        // Check if error.state or error.original has step information
+        const stepName = error.state?.stepName;
+        if (!stepName) {
+            return 'abort'; // Can't determine which step failed
+        }
+        // STEP 3: Get step metadata with graceful handling
+        // CRITICAL: stepMetadata may not exist yet (decorator doesn't store it)
+        if (!('stepMetadata' in this)) {
+            return 'abort'; // No metadata available
+        }
+        const stepMeta = this.stepMetadata.get(stepName);
+        if (!stepMeta) {
+            return 'abort'; // Step not found in metadata
+        }
+        // STEP 4: Check if step is restartable
+        if (!stepMeta.options?.restartable) {
+            return 'abort'; // Step not marked as restartable
+        }
+        // STEP 5: Use analyzeErrorForRestart for criterion matching
+        const analysis = analyzeErrorForRestart(error, stepMeta.options);
+        if (analysis.shouldRestart) {
+            return 'retry';
+        }
+        // STEP 6: Default to abort
+        return 'abort';
+    }
+    /**
+     * Validate an agent response at the workflow level
+     *
+     * This method enables parent workflows to validate agent responses
+     * before processing them. It follows the same validation pattern as
+     * Agent.validateResponse() but emits events and creates WorkflowError
+     * for workflow-level error handling.
+     *
+     * @template T - The type of response data
+     * @param response - The AgentResponse to validate
+     * @param agentId - Identifier of the agent that produced the response
+     * @param dataSchema - Optional Zod schema for response data (defaults to z.unknown())
+     * @returns true if validation passes, false if validation fails
+     *
+     * @example Validate response from child workflow
+     * ```ts
+     * class ParentWorkflow extends Workflow {
+     *   @Step()
+     *   async processChildResult() {
+     *     const response = await this.childWorkflow.run();
+     *
+     *     if (!this.validateAgentResponse(response, this.childWorkflow.agent.id)) {
+     *       // Handle validation failure
+     *       const action = this.analyzeError(this.lastError);
+     *       if (action === 'retry') {
+     *         return await this.restartStep('processChildResult');
+     *       }
+     *     }
+     *
+     *     // Process valid response
+     *     return response.data;
+     *   }
+     * }
+     * ```
+     */
+    validateAgentResponse(response, agentId, dataSchema = z.unknown()) {
+        // Call shared utility for validation
+        const result = validateAgentResponse(response, dataSchema);
+        if (result.valid) {
+            // Response is valid
+            return true;
+        }
+        // Validation failed - emit event and create error
+        const zodError = result.errors; // Safe: errors exists when valid is false
+        // Emit invalidResponse event
+        this.emitEvent({
+            type: 'invalidResponse',
+            node: this.node,
+            response,
+            agentId,
+            errors: zodError,
+            timestamp: Date.now(),
+        });
+        // Create WorkflowError with INVALID_RESPONSE_FORMAT context
+        const validationError = {
+            message: `Agent response validation failed for agent '${agentId}'`,
+            original: zodError,
+            workflowId: this.id,
+            stack: zodError.stack,
+            state: getObservedState(this),
+            logs: [...this.node.logs],
+        };
+        // Store error for potential use by analyzeError/restartStep
+        // Note: Consider adding lastError property to Workflow class if not exists
+        // For now, emit event and return false
+        return false;
+    }
     /**
      * Update workflow status and sync with node
      */
@@ -431,10 +924,34 @@ export class Workflow {
         }
         const startTime = Date.now();
         this.setStatus('running');
-        // Create workflow context
-        const ctx = createWorkflowContext(this, this.parent?.id, this.config.enableReflection ? { enabled: true } : undefined);
+        // Reset error collection state
+        this.collectedErrors = [];
+        this.operationCounter = 0;
+        // Create workflow context with error merge strategy
+        const ctx = createWorkflowContext(this, this.parent?.id, this.config.enableReflection ? { enabled: true } : undefined, this.config.autoValidateResponses ?? true, this.config.errorMergeStrategy);
         try {
             const result = await this.executor(ctx);
+            // Check if we should merge collected errors
+            if (this.collectedErrors.length > 0) {
+                if (this.config.errorMergeStrategy?.enabled) {
+                    // Merge errors
+                    const mergedError = this.config.errorMergeStrategy?.combine
+                        ? this.config.errorMergeStrategy.combine(this.collectedErrors)
+                        : mergeWorkflowErrors(this.collectedErrors, this.config.name || this.id, this.id, this.operationCounter);
+                    // Emit error event with merged error
+                    this.emitEvent({
+                        type: 'error',
+                        node: this.node,
+                        error: mergedError,
+                    });
+                    // Throw merged error
+                    throw mergedError;
+                }
+                else {
+                    // Throw first error (backward compatibility)
+                    throw this.collectedErrors[0];
+                }
+            }
             this.setStatus('completed');
             return {
                 data: result,
@@ -443,20 +960,25 @@ export class Workflow {
             };
         }
         catch (error) {
-            this.setStatus('failed');
-            // Emit error event
-            this.emitEvent({
-                type: 'error',
-                node: this.node,
-                error: {
-                    message: error instanceof Error ? error.message : 'Unknown error',
-                    original: error,
-                    workflowId: this.id,
-                    stack: error instanceof Error ? error.stack : undefined,
-                    state: getObservedState(this),
-                    logs: [...this.node.logs],
-                },
-            });
+            // Handle errors thrown directly (not collected)
+            if (!this.config.errorMergeStrategy?.enabled) {
+                this.setStatus('failed');
+                this.emitEvent({
+                    type: 'error',
+                    node: this.node,
+                    error: {
+                        message: error instanceof Error ? error.message : 'Unknown error',
+                        original: error,
+                        workflowId: this.id,
+                        stack: error instanceof Error ? error.stack : undefined,
+                        state: getObservedState(this),
+                        logs: [...this.node.logs],
+                    },
+                });
+                throw error;
+            }
+            // If in collection mode, error should have been collected already
+            // Re-throw if it somehow escaped collection
             throw error;
         }
     }