@falai/agent 0.9.2 → 1.0.1

package/dist/core/BatchExecutor.js

@@ -0,0 +1,845 @@
+/**
+ * BatchExecutor - Core component for multi-step execution
+ *
+ * Responsible for determining which Steps can execute together in a single batch
+ * and orchestrating their execution with a single LLM call.
+ */
+import { END_ROUTE_ID } from '../constants';
+import { logger, createTemplateContext, mergeCollected } from '../utils';
+/**
+ * Determine if a Step needs user input to proceed
+ *
+ * IMPORTANT: sessionData MUST already include pre-extracted fields.
+ * This function is called AFTER pre-extraction has been merged into session data.
+ *
+ * A Step needs input when:
+ * 1. It has `requires` fields and at least one is missing from session data (after pre-extraction)
+ * 2. It has non-empty `collect` fields and none of those fields have data (after pre-extraction)
+ *
+ * @param step - The Step to evaluate (can be Step instance or StepOptions)
+ * @param sessionDataAfterPreExtraction - Session data with pre-extracted fields already merged
+ * @returns true if the step needs user input, false otherwise
+ *
+ * @example
+ * ```typescript
+ * // Step with requires - needs input if any required field is missing
+ * const step = { requires: ['name', 'email'], collect: [] };
+ * needsInput(step, { name: 'John' }); // true - email is missing
+ * needsInput(step, { name: 'John', email: 'john@example.com' }); // false - all present
+ *
+ * // Step with collect - needs input if no collect fields have data
+ * const step2 = { collect: ['preference', 'feedback'] };
+ * needsInput(step2, {}); // true - no collect fields have data
+ * needsInput(step2, { preference: 'A' }); // false - at least one has data
+ * ```
+ *
+ * **Validates: Requirements 1.2, 1.3**
+ */
+export function needsInput(step, sessionDataAfterPreExtraction) {
+    // Check requires - all must be present (after pre-extraction)
+    // Requirement 1.2: A Step Needs_Input WHEN it has `requires` fields that are not present
+    // in session data after Pre_Extraction
+    if (step.requires && step.requires.length > 0) {
+        const missingRequired = step.requires.some(field => {
+            const key = String(field);
+            return sessionDataAfterPreExtraction[key] === undefined;
+        });
+        if (missingRequired)
+            return true;
+    }
+    // Check collect - needs input if collecting and no data exists (after pre-extraction)
+    // Requirement 1.3: A Step Needs_Input WHEN it has `collect` fields (non-empty array) and
+    // no data for those fields exists in session data
+    if (step.collect && step.collect.length > 0) {
+        const hasAnyCollectData = step.collect.some(field => {
+            const key = String(field);
+            return sessionDataAfterPreExtraction[key] !== undefined;
+        });
+        if (!hasAnyCollectData)
+            return true;
+    }
+    return false;
+}
+/**
+ * BatchExecutor class - orchestrates multi-step execution
+ *
+ * Determines which Steps can execute together in a single batch based on:
+ * - skipIf conditions (skip steps that evaluate to true)
+ * - needsInput detection (stop when a step needs user input)
+ * - END_ROUTE detection (stop when reaching end of route)
+ *
+ * Supports event emission for debugging and observability:
+ * - batch_start: Emitted when batch determination begins
+ * - step_included: Emitted when a step is included in the batch
+ * - step_skipped: Emitted when a step is skipped (due to skipIf)
+ * - batch_stop: Emitted when batch determination stops
+ * - batch_complete: Emitted when batch execution completes
+ *
+ * **Validates: Requirements 1.1, 1.4, 1.5, 7.1, 7.2, 7.3, 11.1, 11.2, 11.3**
+ */
+export class BatchExecutor {
+    constructor() {
+        /** Event listeners for batch execution events */
+        this.eventListeners = [];
+    }
+    /**
+     * Add an event listener for batch execution events
+     *
+     * @param listener - Callback function to receive events
+     * @returns Function to remove the listener
+     *
+     * **Validates: Requirements 11.3**
+     */
+    addEventListener(listener) {
+        this.eventListeners.push(listener);
+        return () => {
+            const index = this.eventListeners.indexOf(listener);
+            if (index !== -1) {
+                this.eventListeners.splice(index, 1);
+            }
+        };
+    }
+    /**
+     * Remove an event listener
+     *
+     * @param listener - The listener to remove
+     */
+    removeEventListener(listener) {
+        const index = this.eventListeners.indexOf(listener);
+        if (index !== -1) {
+            this.eventListeners.splice(index, 1);
+        }
+    }
+    /**
+     * Emit a batch execution event to all listeners
+     *
+     * @param event - The event to emit
+     * @private
+     */
+    emitEvent(event) {
+        for (const listener of this.eventListeners) {
+            try {
+                listener(event);
+            }
+            catch (error) {
+                // Log but don't fail on listener errors
+                logger.warn(`[BatchExecutor] Event listener error:`, error);
+            }
+        }
+    }
+    /**
+     * Create and emit a batch execution event
+     *
+     * @param type - Event type
+     * @param details - Event details
+     * @private
+     */
+    emitBatchEvent(type, details) {
+        const event = {
+            type,
+            timestamp: new Date(),
+            details,
+        };
+        this.emitEvent(event);
+        // Also log the event when debug mode is enabled
+        logger.debug(`[BatchExecutor] Event: ${type}`, details);
+    }
+    /**
+     * Determine which Steps can execute in the current batch
+     * starting from the given Step position.
+     *
+     * Algorithm:
+     * 1. Start from currentStep (or initialStep if undefined)
+     * 2. For each step:
+     *    a. Check if it's END_ROUTE - stop with 'end_route'
+     *    b. Evaluate skipIf condition
+     *    c. If skipIf is true - skip step, continue to next
+     *    d. If skipIf throws error - treat as non-skippable (Requirement 7.3)
+     *    e. Evaluate needsInput
+     *    f. If needsInput is false - include in batch, continue to next
+     *    g. If needsInput is true - stop with 'needs_input'
+     * 3. If all steps processed - stop with 'route_complete'
+     *
+     * @param params - Parameters for batch determination
+     * @returns BatchResult with steps to execute and stopping reason
+     *
+     * **Validates: Requirements 1.1, 1.4, 1.5, 7.1, 7.2, 7.3**
+     */
+    async determineBatch(params) {
+        const { route, currentStep, sessionData, context } = params;
+        const startTime = Date.now();
+        const batchSteps = [];
+        let stoppedReason = 'route_complete';
+        let stoppedAtStep;
+        // Get all steps in the route for traversal
+        const allSteps = route.getAllSteps();
+        // Find starting position
+        let startIndex = 0;
+        if (currentStep) {
+            const currentIndex = allSteps.findIndex(s => s.id === currentStep.id);
+            if (currentIndex !== -1) {
+                startIndex = currentIndex;
+            }
+        }
+        // Log batch determination start (Requirement 11.1)
+        logger.debug(`[BatchExecutor] Starting batch determination from step index ${startIndex}, total steps: ${allSteps.length}`);
+        // Emit batch_start event (Requirement 11.3)
+        this.emitBatchEvent('batch_start', {
+            stepId: currentStep?.id,
+            reason: `Starting batch determination from ${currentStep?.id || 'initial step'}`,
+            batchSize: 0,
+        });
+        // Create template context for condition evaluation
+        const templateContext = createTemplateContext({
+            context,
+            data: sessionData,
+            session: {
+                id: `batch-${Date.now()}`,
+                data: sessionData
+            },
+        });
+        // Walk through steps starting from current position
+        for (let i = startIndex; i < allSteps.length; i++) {
+            const step = allSteps[i];
+            const stepOptions = step.toOptions();
+            // Check for END_ROUTE (Requirement 2.2)
+            if (step.id === END_ROUTE_ID) {
+                stoppedReason = 'end_route';
+                stoppedAtStep = stepOptions;
+                // Log stopping reason (Requirement 11.2)
+                logger.debug(`[BatchExecutor] Reached END_ROUTE, stopping batch`);
+                // Emit batch_stop event (Requirement 11.3)
+                this.emitBatchEvent('batch_stop', {
+                    stepId: step.id,
+                    reason: 'Reached END_ROUTE',
+                    stoppedReason: 'end_route',
+                    batchSize: batchSteps.length,
+                });
+                break;
+            }
+            // Evaluate skipIf condition (Requirements 7.1, 7.2, 7.3)
+            let shouldSkip = false;
+            if (step.skipIf) {
+                try {
+                    const skipResult = await step.evaluateSkipIf(templateContext);
+                    shouldSkip = skipResult.shouldSkip;
+                    // Log skipIf evaluation (Requirement 11.1)
+                    logger.debug(`[BatchExecutor] Step ${step.id} skipIf evaluated to: ${shouldSkip}`);
+                }
+                catch (error) {
+                    // Requirement 7.3: If skipIf evaluation throws an error, treat as non-skippable
+                    logger.warn(`[BatchExecutor] skipIf evaluation error for step ${step.id}, treating as non-skippable:`, error);
+                    shouldSkip = false;
+                }
+            }
+            // If skipIf is true, skip this step and continue (Requirement 7.2)
+            if (shouldSkip) {
+                // Log step skip (Requirement 11.1)
+                logger.debug(`[BatchExecutor] Skipping step ${step.id} due to skipIf condition`);
+                // Emit step_skipped event (Requirement 11.3)
+                this.emitBatchEvent('step_skipped', {
+                    stepId: step.id,
+                    reason: 'skipIf condition evaluated to true',
+                });
+                continue;
+            }
+            // Evaluate needsInput (Requirements 1.2, 1.3)
+            const stepNeedsInput = needsInput(step, sessionData);
+            if (stepNeedsInput) {
+                // Requirement 1.5: Stop when a step needs input
+                stoppedReason = 'needs_input';
+                stoppedAtStep = stepOptions;
+                // Log stopping reason with details (Requirement 11.1, 11.2)
+                const missingRequires = step.requires?.filter(field => sessionData[String(field)] === undefined) || [];
+                const collectFields = step.collect || [];
+                // Warn about missing required fields from previous steps
+                if (missingRequires.length > 0) {
+                    const warning = `[Agent] Step "${step.description || step.id}" requires data [${missingRequires.join(', ')}] that was not collected by previous steps. ` +
+                        `Ensure earlier steps collect these fields before this step can proceed.`;
+                    logger.warn(warning);
+                    // Also log to console for developer visibility
+                    console.warn(warning);
+                }
+                logger.debug(`[BatchExecutor] Step ${step.id} needs input, stopping batch. Missing requires: [${missingRequires.join(', ')}], Collect fields: [${collectFields.join(', ')}]`);
+                // Emit batch_stop event (Requirement 11.3)
+                this.emitBatchEvent('batch_stop', {
+                    stepId: step.id,
+                    reason: `Step needs input - missing requires: [${missingRequires.join(', ')}], collect fields: [${collectFields.join(', ')}]`,
+                    stoppedReason: 'needs_input',
+                    batchSize: batchSteps.length,
+                });
+                break;
+            }
+            // Requirement 1.4: Step doesn't need input, include in batch
+            batchSteps.push(stepOptions);
+            // Log step inclusion with reason (Requirement 11.1)
+            logger.debug(`[BatchExecutor] Including step ${step.id} in batch (all requirements satisfied)`);
+            // Emit step_included event (Requirement 11.3)
+            this.emitBatchEvent('step_included', {
+                stepId: step.id,
+                reason: 'All requirements satisfied, no input needed',
+                batchSize: batchSteps.length,
+            });
+            // Move to next step in the sequence
+            const transitions = step.getTransitions();
+            if (transitions.length === 0) {
+                // No more transitions, route is complete
+                stoppedReason = 'route_complete';
+                // Log stopping reason (Requirement 11.2)
+                logger.debug(`[BatchExecutor] No more transitions from step ${step.id}, route complete`);
+                // Emit batch_stop event (Requirement 11.3)
+                this.emitBatchEvent('batch_stop', {
+                    stepId: step.id,
+                    reason: 'No more transitions, route complete',
+                    stoppedReason: 'route_complete',
+                    batchSize: batchSteps.length,
+                });
+                break;
+            }
+            // For linear routes, follow the first transition
+            // For branching routes, we'd need more complex logic
+            const nextStep = transitions[0];
+            if (nextStep) {
+                // Update the loop to continue from the next step
+                const nextIndex = allSteps.findIndex(s => s.id === nextStep.id);
+                if (nextIndex !== -1 && nextIndex > i) {
+                    // Continue from next step (will be incremented by loop)
+                    i = nextIndex - 1;
+                }
+                else if (nextStep.id === END_ROUTE_ID) {
+                    // Next step is END_ROUTE
+                    stoppedReason = 'end_route';
+                    stoppedAtStep = nextStep.toOptions();
+                    // Log stopping reason (Requirement 11.2)
+                    logger.debug(`[BatchExecutor] Next step is END_ROUTE, stopping batch`);
+                    // Emit batch_stop event (Requirement 11.3)
+                    this.emitBatchEvent('batch_stop', {
+                        stepId: nextStep.id,
+                        reason: 'Next step is END_ROUTE',
+                        stoppedReason: 'end_route',
+                        batchSize: batchSteps.length,
+                    });
+                    break;
+                }
+            }
+        }
+        // Log batch determination complete with timing (Requirement 11.1, 11.2)
+        const determinationTime = Date.now() - startTime;
+        logger.debug(`[BatchExecutor] Batch determination complete. Steps: ${batchSteps.length}, Stopped reason: ${stoppedReason}, Time: ${determinationTime}ms`);
+        return {
+            steps: batchSteps,
+            stoppedReason,
+            stoppedAtStep,
+        };
+    }
+    /**
+     * Execute prepare hooks for all steps in the batch
+     *
+     * Executes all prepare hooks in Step order before the LLM call.
+     * If any prepare hook fails, execution stops immediately and returns an error.
+     *
+     * @param params - Parameters for hook execution
+     * @returns Result indicating success or failure with error details
+     *
+     * **Validates: Requirements 5.1, 5.3, 5.4**
+     */
+    async executePrepareHooks(params) {
+        const { steps, context, data, executeHook } = params;
+        const executedSteps = [];
+        logger.debug(`[BatchExecutor] Executing prepare hooks for ${steps.length} steps`);
+        for (const step of steps) {
+            if (step.prepare) {
+                logger.debug(`[BatchExecutor] Executing prepare hook for step: ${step.id}`);
+                try {
+                    await executeHook(step.prepare, context, data, step);
+                    executedSteps.push(step.id || 'unknown');
+                    logger.debug(`[BatchExecutor] Prepare hook completed for step: ${step.id}`);
+                }
+                catch (error) {
+                    // Requirement 5.4: Stop on prepare hook failure
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    logger.error(`[BatchExecutor] Prepare hook failed for step ${step.id}: ${errorMessage}`);
+                    return {
+                        success: false,
+                        executedSteps,
+                        error: {
+                            type: 'prepare_hook',
+                            message: errorMessage,
+                            stepId: step.id,
+                            details: error,
+                        },
+                    };
+                }
+            }
+        }
+        logger.debug(`[BatchExecutor] All prepare hooks completed successfully`);
+        return {
+            success: true,
+            executedSteps,
+        };
+    }
+    /**
+     * Execute finalize hooks for all steps in the batch
+     *
+     * Executes all finalize hooks in Step order after the LLM response.
+     * If a finalize hook fails, the error is logged but execution continues
+     * with remaining hooks.
+     *
+     * @param params - Parameters for hook execution
+     * @returns Result with any errors that occurred (always succeeds)
+     *
+     * **Validates: Requirements 5.2, 5.3, 5.5**
+     */
+    async executeFinalizeHooks(params) {
+        const { steps, context, data, executeHook } = params;
+        const executedSteps = [];
+        const errors = [];
+        logger.debug(`[BatchExecutor] Executing finalize hooks for ${steps.length} steps`);
+        for (const step of steps) {
+            if (step.finalize) {
+                logger.debug(`[BatchExecutor] Executing finalize hook for step: ${step.id}`);
+                try {
+                    await executeHook(step.finalize, context, data, step);
+                    executedSteps.push(step.id || 'unknown');
+                    logger.debug(`[BatchExecutor] Finalize hook completed for step: ${step.id}`);
+                }
+                catch (error) {
+                    // Requirement 5.5: Log error and continue with remaining hooks
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    logger.error(`[BatchExecutor] Finalize hook failed for step ${step.id}: ${errorMessage}`);
+                    errors.push({
+                        stepId: step.id || 'unknown',
+                        error: {
+                            type: 'finalize_hook',
+                            message: errorMessage,
+                            stepId: step.id,
+                            details: error,
+                        },
+                    });
+                    // Continue to next step despite error
+                }
+            }
+        }
+        if (errors.length > 0) {
+            logger.warn(`[BatchExecutor] ${errors.length} finalize hook(s) failed, but execution continued`);
+        }
+        else {
+            logger.debug(`[BatchExecutor] All finalize hooks completed successfully`);
+        }
+        // Always return success for finalize hooks (errors are logged but don't stop execution)
+        return {
+            success: true,
+            executedSteps,
+            errors: errors.length > 0 ? errors : undefined,
+        };
+    }
+    /**
+     * Execute all hooks for a batch of steps
+     *
+     * This is a convenience method that executes prepare hooks, then allows
+     * the caller to perform the LLM call, and finally executes finalize hooks.
+     *
+     * @param params - Parameters for hook execution
+     * @returns Object with methods to execute prepare and finalize phases
+     *
+     * **Validates: Requirements 5.1, 5.2, 5.3, 5.4, 5.5**
+     */
+    createHookExecutor(params) {
+        return {
+            executePrepare: () => this.executePrepareHooks(params),
+            executeFinalize: () => this.executeFinalizeHooks(params),
+        };
+    }
+    /**
+     * Execute a batch of steps with comprehensive error handling
+     *
+     * This method orchestrates the complete batch execution flow:
+     * 1. Execute prepare hooks (stop on failure)
+     * 2. Make LLM call (preserve session state on failure)
+     * 3. Collect and validate data (include errors in response)
+     * 4. Execute finalize hooks (continue on failure, log errors)
+     *
+     * Error handling behavior:
+     * - LLM call failures: Return error response with last successful session state
+     * - Validation failures: Include validation errors in response, preserve partial data
+     * - Prepare hook failures: Stop execution, return error with appropriate stoppedReason
+     * - Finalize hook failures: Log errors, continue execution (non-fatal)
+     *
+     * @param params - Parameters for batch execution
+     * @returns BatchExecutionResult with message, session, executed steps, and any errors
+     *
+     * **Validates: Requirements 9.1, 9.2, 9.3, 2.4**
+     */
+    async executeBatch(params) {
+        const { batch, session: initialSession, context, executeHook, generateMessage, schema, routeId, } = params;
+        // Track timing for each phase (Requirement 11.1)
+        const timing = {
+            totalMs: 0,
+        };
+        const batchStartTime = Date.now();
+        // Track the last successful session state for error recovery
+        let lastSuccessfulSession = initialSession;
+        let currentSession = initialSession;
+        // Track executed steps for the response
+        const executedSteps = [];
+        // Log batch execution start with details (Requirement 11.1)
+        logger.debug(`[BatchExecutor] Starting batch execution with ${batch.steps.length} steps, route: ${routeId || 'unknown'}`);
+        // If batch is empty, return early with appropriate reason
+        if (batch.steps.length === 0) {
+            logger.debug(`[BatchExecutor] Empty batch, returning with stopped reason: ${batch.stoppedReason}`);
+            // Emit batch_complete event for empty batch (Requirement 11.3)
+            timing.totalMs = Date.now() - batchStartTime;
+            this.emitBatchEvent('batch_complete', {
+                batchSize: 0,
+                stoppedReason: batch.stoppedReason,
+                reason: 'Empty batch',
+                timing,
+            });
+            return {
+                message: '',
+                session: currentSession,
+                executedSteps: [],
+                stoppedReason: batch.stoppedReason,
+                collectedData: {},
+            };
+        }
+        // PHASE 1: Execute prepare hooks (Requirement 5.4 - stop on failure)
+        const prepareStartTime = Date.now();
+        logger.debug(`[BatchExecutor] Phase 1: Executing prepare hooks`);
+        const prepareResult = await this.executePrepareHooks({
+            steps: batch.steps,
+            context,
+            data: currentSession.data,
+            executeHook,
+        });
+        timing.prepareHooksMs = Date.now() - prepareStartTime;
+        logger.debug(`[BatchExecutor] Prepare hooks completed in ${timing.prepareHooksMs}ms`);
+        if (!prepareResult.success) {
+            // Requirement 9.3: Preserve partial progress on errors
+            // Requirement 2.4: Stop and include error information
+            logger.error(`[BatchExecutor] Prepare hook failed:`, prepareResult.error);
+            // Emit batch_complete event with error (Requirement 11.3)
+            timing.totalMs = Date.now() - batchStartTime;
+            this.emitBatchEvent('batch_complete', {
+                batchSize: batch.steps.length,
+                stoppedReason: 'prepare_error',
+                reason: `Prepare hook failed: ${prepareResult.error?.message}`,
+                timing,
+            });
+            return {
+                message: '',
+                session: lastSuccessfulSession, // Return last successful state
+                executedSteps: prepareResult.executedSteps.map(stepId => ({
+                    id: stepId,
+                    routeId: routeId || 'unknown',
+                })),
+                stoppedReason: 'prepare_error',
+                error: prepareResult.error,
+            };
+        }
+        // Update last successful session after prepare hooks complete
+        lastSuccessfulSession = currentSession;
+        // PHASE 2: Make LLM call (Requirement 9.1 - preserve session state on failure)
+        const llmStartTime = Date.now();
+        logger.debug(`[BatchExecutor] Phase 2: Making LLM call`);
+        let llmResponse;
+        let message;
+        try {
+            const result = await generateMessage();
+            llmResponse = result.structured || {};
+            message = result.message || '';
+            timing.llmCallMs = Date.now() - llmStartTime;
+            logger.debug(`[BatchExecutor] LLM call successful in ${timing.llmCallMs}ms`);
+        }
+        catch (error) {
+            // Requirement 9.1: Return error response with last successful session state
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            timing.llmCallMs = Date.now() - llmStartTime;
+            logger.error(`[BatchExecutor] LLM call failed after ${timing.llmCallMs}ms:`, errorMessage);
+            // Emit batch_complete event with error (Requirement 11.3)
+            timing.totalMs = Date.now() - batchStartTime;
+            this.emitBatchEvent('batch_complete', {
+                batchSize: batch.steps.length,
+                stoppedReason: 'llm_error',
+                reason: `LLM call failed: ${errorMessage}`,
+                timing,
+            });
+            return {
+                message: '',
+                session: lastSuccessfulSession, // Preserve session state
+                executedSteps: [], // No steps were fully executed
+                stoppedReason: 'llm_error',
+                error: {
+                    type: 'llm_call',
+                    message: errorMessage,
+                    details: error,
+                },
+            };
+        }
+        // Update last successful session after LLM call
+        lastSuccessfulSession = currentSession;
+        // PHASE 3: Collect and validate data (Requirement 9.2 - include validation errors)
+        const collectStartTime = Date.now();
+        logger.debug(`[BatchExecutor] Phase 3: Collecting and validating data`);
+        const collectResult = this.collectBatchData({
+            steps: batch.steps,
+            llmResponse,
+            session: currentSession,
+            schema,
+        });
+        timing.dataCollectionMs = Date.now() - collectStartTime;
+        logger.debug(`[BatchExecutor] Data collection completed in ${timing.dataCollectionMs}ms`);
+        // Update session with collected data (even if validation failed)
+        currentSession = collectResult.session;
+        // Track collected data for response
+        const collectedData = collectResult.collectedData;
+        // Check for validation errors
+        let validationError;
+        if (!collectResult.success && collectResult.validationErrors && collectResult.validationErrors.length > 0) {
+            // Requirement 9.2: Include validation errors in response
+            logger.warn(`[BatchExecutor] Data validation failed:`, collectResult.validationErrors);
+            validationError = {
+                type: 'data_validation',
+                message: `Validation failed for ${collectResult.validationErrors.length} field(s): ${collectResult.validationErrors.map(e => e.field).join(', ')}`,
+                details: collectResult.validationErrors,
+            };
+            // Note: We continue execution despite validation errors
+            // The error is included in the response for the caller to handle
+        }
+        // Update last successful session after data collection
+        // (even with validation errors, we preserve the collected data)
+        lastSuccessfulSession = currentSession;
+        // Build executed steps list
+        for (const step of batch.steps) {
+            if (step.id) {
+                executedSteps.push({
+                    id: step.id,
+                    routeId: routeId || 'unknown',
+                });
+            }
+        }
+        // PHASE 4: Execute finalize hooks (Requirement 5.5 - continue on failure)
+        const finalizeStartTime = Date.now();
+        logger.debug(`[BatchExecutor] Phase 4: Executing finalize hooks`);
+        const finalizeResult = await this.executeFinalizeHooks({
+            steps: batch.steps,
+            context,
+            data: currentSession.data,
+            executeHook,
+        });
+        timing.finalizeHooksMs = Date.now() - finalizeStartTime;
+        logger.debug(`[BatchExecutor] Finalize hooks completed in ${timing.finalizeHooksMs}ms`);
+        // Log finalize errors but don't fail the batch
+        let finalizeError;
+        if (finalizeResult.errors && finalizeResult.errors.length > 0) {
+            logger.warn(`[BatchExecutor] Some finalize hooks failed:`, finalizeResult.errors);
+            // Create a summary error for finalize failures
+            finalizeError = {
+                type: 'finalize_hook',
+                message: `${finalizeResult.errors.length} finalize hook(s) failed`,
+                details: finalizeResult.errors,
+            };
+        }
+        // Determine the final stopped reason
+        // Priority: validation_error > finalize_error > batch.stoppedReason
+        let finalStoppedReason = batch.stoppedReason;
+        let finalError;
+        if (validationError) {
+            finalStoppedReason = 'validation_error';
+            finalError = validationError;
+        }
+        else if (finalizeError) {
+            // Finalize errors are non-fatal, so we keep the original stopped reason
+            // but include the error in the response
+            finalError = finalizeError;
+        }
+        // Calculate total time and log completion (Requirement 11.1, 11.2)
+        timing.totalMs = Date.now() - batchStartTime;
+        logger.debug(`[BatchExecutor] Batch execution complete. Stopped reason: ${finalStoppedReason}, Executed steps: ${executedSteps.length}, Total time: ${timing.totalMs}ms`);
+        // Emit batch_complete event (Requirement 11.3)
+        this.emitBatchEvent('batch_complete', {
+            batchSize: executedSteps.length,
+            stoppedReason: finalStoppedReason,
+            reason: `Batch completed with ${executedSteps.length} steps`,
+            timing,
+        });
+        return {
+            message,
+            session: currentSession,
+            executedSteps,
+            stoppedReason: finalStoppedReason,
+            collectedData,
+            error: finalError,
+        };
+    }
+    /**
+     * Collect data from LLM response for all steps in the batch
+     *
+     * This method:
+     * 1. Gathers all collect fields from all steps in the batch
+     * 2. Extracts those fields from the LLM response
+     * 3. Validates extracted data against the agent schema (if provided)
+     * 4. Updates session data with all collected values
+     *
+     * @param params - Parameters for data collection
+     * @returns Result with collected data, updated session, and any validation errors
+     *
+     * **Validates: Requirements 6.1, 6.2, 6.3**
+     */
+    collectBatchData(params) {
+        const { steps, llmResponse, session, schema } = params;
+        logger.debug(`[BatchExecutor] Collecting batch data from ${steps.length} steps`);
+        // Requirement 6.1: Gather all collect fields from all steps in the batch
+        const allCollectFields = new Set();
+        for (const step of steps) {
+            if (step.collect && step.collect.length > 0) {
+                for (const field of step.collect) {
+                    allCollectFields.add(String(field));
+                }
+            }
+        }
+        logger.debug(`[BatchExecutor] Collect fields to extract: ${Array.from(allCollectFields).join(', ')}`);
+        // If no fields to collect, return early with unchanged session
+        if (allCollectFields.size === 0) {
+            logger.debug(`[BatchExecutor] No collect fields defined, skipping data collection`);
+            return {
+                success: true,
+                collectedData: {},
+                session,
+                fieldsCollected: [],
+            };
+        }
+        // Extract data from LLM response for all collect fields
+        const collectedData = {};
+        const fieldsCollected = [];
+        const fieldsMissing = [];
+        for (const field of allCollectFields) {
+            // Check if the field exists in the LLM response
+            if (field in llmResponse && llmResponse[field] !== undefined) {
+                collectedData[field] = llmResponse[field];
+                fieldsCollected.push(field);
+                logger.debug(`[BatchExecutor] Collected field '${field}': ${JSON.stringify(llmResponse[field])}`);
+            }
+            else {
+                fieldsMissing.push(field);
+                logger.debug(`[BatchExecutor] Field '${field}' not found in LLM response`);
+            }
+        }
+        // Requirement 6.2: Validate collected data against the agent schema
+        const validationErrors = [];
+        if (schema && Object.keys(collectedData).length > 0) {
+            logger.debug(`[BatchExecutor] Validating collected data against schema`);
+            const validationResult = this.validateAgainstSchema(collectedData, schema);
+            if (!validationResult.valid) {
+                validationErrors.push(...validationResult.errors);
+                logger.warn(`[BatchExecutor] Schema validation found ${validationErrors.length} error(s)`);
+            }
+        }
+        // Requirement 6.3: Update session data with all collected values
+        // Only merge valid data (data that passed validation or had no schema to validate against)
+        let updatedSession = session;
+        if (Object.keys(collectedData).length > 0) {
+            // Filter out fields with validation errors if we want strict validation
+            // For now, we include all collected data and report errors separately
+            updatedSession = mergeCollected(session, collectedData);
+            logger.debug(`[BatchExecutor] Updated session with collected data`);
+        }
+        const success = validationErrors.length === 0;
+        logger.debug(`[BatchExecutor] Data collection complete. Success: ${success}, Fields collected: ${fieldsCollected.length}, Fields missing: ${fieldsMissing.length}`);
+        return {
+            success,
+            collectedData,
+            session: updatedSession,
+            fieldsCollected,
+            fieldsMissing: fieldsMissing.length > 0 ? fieldsMissing : undefined,
+            validationErrors: validationErrors.length > 0 ? validationErrors : undefined,
+        };
+    }
+    /**
+     * Validate data against a JSON schema
+     *
+     * Performs basic validation of collected data against the agent schema.
+     * Checks:
+     * - Fields exist in schema properties
+     * - Required fields are present (as warnings)
+     * - Basic type validation
+     *
+     * @param data - Data to validate
+     * @param schema - JSON schema to validate against
+     * @returns Validation result with errors
+     * @private
+     */
+    validateAgainstSchema(data, schema) {
+        const errors = [];
+        // Check if provided fields exist in schema
+        if (schema.properties) {
+            for (const [key, value] of Object.entries(data)) {
+                if (!(key in schema.properties)) {
+                    errors.push({
+                        field: key,
+                        value,
+                        message: `Field '${key}' is not defined in schema`,
+                        schemaPath: `properties.${key}`,
+                    });
+                }
+                else {
+                    // Basic type validation
+                    const fieldSchema = schema.properties[key];
+                    const typeError = this.validateFieldType(key, value, fieldSchema);
+                    if (typeError) {
+                        errors.push(typeError);
+                    }
+                }
+            }
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+        };
+    }
+    /**
+     * Validate a single field's type against its schema
+     * @private
+     */
+    validateFieldType(field, value, fieldSchema) {
+        if (value === null || value === undefined) {
+            // Null/undefined values are handled separately (required field check)
+            return null;
+        }
+        const expectedType = fieldSchema.type;
+        if (!expectedType) {
+            // No type specified, consider valid
+            return null;
+        }
+        const actualType = Array.isArray(value) ? 'array' : typeof value;
+        // Handle array of types
+        const allowedTypes = Array.isArray(expectedType) ? expectedType : [expectedType];
+        // Map JavaScript types to JSON Schema types
+        const typeMapping = {
+            'string': 'string',
+            'number': 'number',
+            'boolean': 'boolean',
+            'object': 'object',
+            'array': 'array',
+        };
+        const mappedActualType = typeMapping[actualType] || actualType;
+        // Check if actual type matches any allowed type
+        // Also handle 'integer' as a valid number type
+        const isValidType = allowedTypes.some(t => {
+            if (t === 'integer') {
+                return typeof value === 'number' && Number.isInteger(value);
+            }
+            return t === mappedActualType;
+        });
+        if (!isValidType) {
+            return {
+                field,
+                value,
+                message: `Field '${field}' has type '${actualType}' but expected '${allowedTypes.join(' | ')}'`,
+                schemaPath: `properties.${field}.type`,
+            };
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=BatchExecutor.js.map