@falai/agent 1.2.7 → 2.0.0

package/dist/core/BatchExecutor.js

@@ -1,856 +0,0 @@
-/**
- * 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, createSession } 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, maxSteps = 1 } = 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: createSession({ 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 (but silence in test suites to prevent fast-check spam)
-                    if (process.env.NODE_ENV !== 'test') {
-                        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,
-            });
-            // Check if we've reached the max steps limit
-            if (batchSteps.length >= maxSteps) {
-                stoppedReason = 'max_steps_reached';
-                logger.debug(`[BatchExecutor] Reached maxStepsPerBatch limit (${maxSteps}), stopping batch`);
-                this.emitBatchEvent('batch_stop', {
-                    stepId: step.id,
-                    reason: `Reached maxStepsPerBatch limit (${maxSteps})`,
-                    stoppedReason: 'max_steps_reached',
-                    batchSize: batchSteps.length,
-                });
-                break;
-            }
-            // 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