@falai/agent 0.9.2 → 1.0.0

package/src/core/ResponseModal.ts

@@ -15,6 +15,7 @@ import type {
     ToolEventData,
     AgentStructuredResponse,
     Term,
+    StoppedReason,
 } from "../types";
 import { EventKind, MessageRole } from "../types";
 import type { Agent } from "./Agent";
@@ -22,9 +23,13 @@ import type { Route } from "./Route";
 import { Step } from "./Step";
 import { ResponseEngine } from "./ResponseEngine";
 import { ResponsePipeline } from "./ResponsePipeline";
+import { BatchExecutor, type HookFunction } from "./BatchExecutor";
+import { BatchPromptBuilder } from "./BatchPromptBuilder";
 import { cloneDeep, mergeCollected, enterStep, getLastMessageFromHistory, render, logger, historyToEvents } from "../utils";
+import { createTemplateContext } from "../utils/template";
 import type { ToolManager } from "./ToolManager";
 import { END_ROUTE_ID } from "../constants";
+import type { StepOptions } from "../types/route";
 
 /**
  * Configuration options for ResponseModal
@@ -129,6 +134,12 @@ interface ResponseContext<TContext = unknown, TData = unknown> {
     selectedStep?: Step<TContext, TData>;
     responseDirectives?: string[];
     isRouteComplete: boolean;
+    /** Batch of steps to execute (for multi-step execution) */
+    batchSteps?: StepOptions<TContext, TData>[];
+    /** Reason why batch determination stopped */
+    batchStoppedReason?: StoppedReason;
+    /** Step that caused batch to stop (if applicable) */
+    batchStoppedAtStep?: StepOptions<TContext, TData>;
 }
 
 /**
@@ -138,6 +149,8 @@ interface ResponseContext<TContext = unknown, TData = unknown> {
 export class ResponseModal<TContext = unknown, TData = unknown> {
     private readonly responseEngine: ResponseEngine<TContext, TData>;
     private readonly responsePipeline: ResponsePipeline<TContext, TData>;
+    private readonly batchExecutor: BatchExecutor<TContext, TData>;
+    private readonly batchPromptBuilder: BatchPromptBuilder<TContext, TData>;
 
     constructor(
         private readonly agent: Agent<TContext, TData>,
@@ -157,6 +170,12 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
             this.agent.updateCollectedData.bind(this.agent),
             this.getToolManager()
         );
+
+        // Initialize batch executor for multi-step execution
+        this.batchExecutor = new BatchExecutor<TContext, TData>();
+
+        // Initialize batch prompt builder for combined prompts
+        this.batchPromptBuilder = new BatchPromptBuilder<TContext, TData>();
     }
 
     /**
@@ -418,12 +437,16 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
             }
 
             // PHASE 2: ROUTING + STEP SELECTION - Determine which route and step to use
+            // Also performs pre-extraction and batch determination
             let routingResult: {
                 selectedRoute?: Route<TContext, TData>;
                 selectedStep?: Step<TContext, TData>;
                 responseDirectives?: string[];
                 session: SessionState<TData>;
                 isRouteComplete: boolean;
+                batchSteps?: StepOptions<TContext, TData>[];
+                batchStoppedReason?: StoppedReason;
+                batchStoppedAtStep?: StepOptions<TContext, TData>;
             };
             try {
                 routingResult = await this.handleUnifiedRoutingAndStepSelection({
@@ -444,6 +467,9 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 selectedStep: routingResult.selectedStep,
                 responseDirectives: routingResult.responseDirectives,
                 isRouteComplete: routingResult.isRouteComplete,
+                batchSteps: routingResult.batchSteps,
+                batchStoppedReason: routingResult.batchStoppedReason,
+                batchStoppedAtStep: routingResult.batchStoppedAtStep,
             };
         } catch (error) {
             // Re-throw ResponseGenerationError as-is, wrap others
@@ -469,6 +495,12 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
         responseDirectives?: string[];
         session: SessionState<TData>;
         isRouteComplete: boolean;
+        /** Batch of steps to execute (for multi-step execution) */
+        batchSteps?: StepOptions<TContext, TData>[];
+        /** Reason why batch determination stopped */
+        batchStoppedReason?: StoppedReason;
+        /** Step that caused batch to stop (if applicable) */
+        batchStoppedAtStep?: StepOptions<TContext, TData>;
     }> {
         try {
             // Use the ResponsePipeline for optimized routing and step selection
@@ -480,12 +512,84 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 context: params.context,
                 signal: params.signal,
             });
+
+            let updatedSession = routingResult.session;
+            let isRouteComplete = routingResult.isRouteComplete;
+
+            // PRE-EXTRACTION: If entering a route that collects data, extract data from user message first
+            // This allows us to skip steps whose data is already provided
+            // Requirement 3.1: Perform Pre_Extraction before determining the Batch
+            if (routingResult.selectedRoute && !isRouteComplete) {
+                // Always pre-extract when route collects data (not just on new route entry)
+                // This ensures batch determination has the most up-to-date data
+                if (this.shouldPreExtractData(routingResult.selectedRoute)) {
+                    logger.debug(
+                        `[ResponseModal] Pre-extracting data for route: ${routingResult.selectedRoute.title}`
+                    );
+
+                    const extractedData = await this.preExtractRouteData({
+                        route: routingResult.selectedRoute,
+                        history: params.history,
+                        context: params.context,
+                        session: updatedSession,
+                        signal: params.signal,
+                    });
+
+                    if (extractedData && Object.keys(extractedData).length > 0) {
+                        logger.debug(
+                            `[ResponseModal] Pre-extracted data:`,
+                            extractedData
+                        );
+                        // Requirement 3.3: Merge pre-extracted data into session before batch determination
+                        updatedSession = mergeCollected(updatedSession, extractedData);
+                        // Also update agent's collected data
+                        await this.agent.updateCollectedData(extractedData);
+
+                        // Re-check route completion after pre-extraction
+                        const allRequiredFieldsCollected = routingResult.selectedRoute.isComplete(updatedSession.data || {});
+                        if (allRequiredFieldsCollected) {
+                            logger.debug(
+                                `[ResponseModal] Route ${routingResult.selectedRoute.title} completed after pre-extraction`
+                            );
+                            isRouteComplete = true;
+                        }
+                    }
+                }
+            }
+
+            // BATCH DETERMINATION: Use BatchExecutor to determine which steps can execute together
+            // Requirement 3.4: Pre-extraction results affect batch determination
+            let batchSteps: StepOptions<TContext, TData>[] | undefined;
+            let batchStoppedReason: StoppedReason | undefined;
+            let batchStoppedAtStep: StepOptions<TContext, TData> | undefined;
+
+            if (routingResult.selectedRoute && !isRouteComplete) {
+                // Determine current step position for batch determination
+                const currentStep = routingResult.selectedStep || 
+                    (updatedSession.currentStep ? routingResult.selectedRoute.getStep(updatedSession.currentStep.id) : undefined);
+
+                logger.debug(`[ResponseModal] Determining batch starting from step: ${currentStep?.id || 'initial'}`);
+
+                const batchResult = await this.batchExecutor.determineBatch({
+                    route: routingResult.selectedRoute,
+                    currentStep,
+                    sessionData: updatedSession.data || {},
+                    context: params.context,
+                });
+
+                batchSteps = batchResult.steps;
+                batchStoppedReason = batchResult.stoppedReason;
+                batchStoppedAtStep = batchResult.stoppedAtStep;
+
+                logger.debug(`[ResponseModal] Batch determined: ${batchSteps.length} steps, stopped reason: ${batchStoppedReason}`);
+            }
+
             // Determine next step using pipeline method for consistency
-            const stepResult = this.responsePipeline.determineNextStep({
+            const stepResult = await this.responsePipeline.determineNextStep({
                 selectedRoute: routingResult.selectedRoute,
                 selectedStep: routingResult.selectedStep,
-                session: routingResult.session,
-                isRouteComplete: routingResult.isRouteComplete,
+                session: updatedSession, // Use updated session with pre-extracted data
+                isRouteComplete, // Use updated completion status
             });
 
             return {
@@ -493,13 +597,106 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 selectedStep: stepResult.nextStep, // Use the determined next step
                 responseDirectives: routingResult.responseDirectives,
                 session: stepResult.session,
-                isRouteComplete: routingResult.isRouteComplete,
+                isRouteComplete, // Use updated completion status
+                batchSteps,
+                batchStoppedReason,
+                batchStoppedAtStep,
             };
         } catch (error) {
             throw ResponseGenerationError.fromError(error, 'routing_optimization', params);
         }
     }
 
+    /**
+     * Check if a route should pre-extract data before determining the initial step
+     * @private
+     */
+    private shouldPreExtractData(route: Route<TContext, TData>): boolean {
+        // Pre-extract if route has declared required or optional fields
+        if (route.requiredFields && route.requiredFields.length > 0) {
+            return true;
+        }
+        if (route.optionalFields && route.optionalFields.length > 0) {
+            return true;
+        }
+
+        // Pre-extract if any step in the route collects data
+        const steps = route.getAllSteps();
+        const hasDataCollectionSteps = steps.some(
+            step => step.collect && step.collect.length > 0
+        );
+
+        return hasDataCollectionSteps;
+    }
+
+    /**
+     * Pre-extract data from user message when entering a route
+     * This allows skipping steps whose data is already provided
+     * @private
+     */
+    private async preExtractRouteData(params: {
+        route: Route<TContext, TData>;
+        history: Event[];
+        context: TContext;
+        session: SessionState<TData>;
+        signal?: AbortSignal;
+    }): Promise<Partial<TData>> {
+        const { route, history, context, signal } = params;
+
+        // Build a schema for data extraction based on route's fields
+        const extractionSchema = this.agent.getSchema();
+        if (!extractionSchema) {
+            logger.warn(`[ResponseModal] No schema available for pre-extraction`);
+            return {};
+        }
+
+        // Get last user message
+        const lastMessage = getLastMessageFromHistory(history);
+
+        // Build extraction prompt
+        const extractionPrompt = [
+            `Extract any relevant information from the user's message that matches the following data fields.`,
+            `Only extract information that is explicitly stated or clearly implied.`,
+            ``,
+            `User's message: "${lastMessage}"`,
+            ``,
+            `Extract data for these fields if present:`,
+        ];
+
+        // Add field descriptions
+        if (route.requiredFields) {
+            extractionPrompt.push(`Required fields: ${route.requiredFields.join(', ')}`);
+        }
+        if (route.optionalFields) {
+            extractionPrompt.push(`Optional fields: ${route.optionalFields.join(', ')}`);
+        }
+
+        extractionPrompt.push(
+            ``,
+            `Return ONLY the extracted data as JSON. If no data can be extracted, return an empty object {}.`
+        );
+
+        // Call AI to extract data
+        const agentOptions = this.agent.getAgentOptions();
+        try {
+            const result = await agentOptions.provider.generateMessage<TContext, Partial<TData>>({
+                prompt: extractionPrompt.join('\n'),
+                history,
+                context,
+                signal,
+                parameters: {
+                    jsonSchema: extractionSchema,
+                    schemaName: 'data_extraction',
+                },
+            });
+
+            return result.structured || {};
+        } catch (error) {
+            logger.error(`[ResponseModal] Pre-extraction failed:`, error);
+            return {};
+        }
+    }
+
     /**
      * Unified response generation for non-streaming responses
      * @private
@@ -507,7 +704,17 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
     private async generateUnifiedResponse(
         responseContext: ResponseContext<TContext, TData>
     ): Promise<AgentResponse<TData>> {
-        const { effectiveContext, session: initialSession, history, selectedRoute, selectedStep, responseDirectives, isRouteComplete } = responseContext;
+        const { 
+            effectiveContext, 
+            session: initialSession, 
+            history, 
+            selectedRoute, 
+            selectedStep, 
+            responseDirectives, 
+            isRouteComplete,
+            batchSteps,
+            batchStoppedReason,
+        } = responseContext;
         let session = initialSession;
 
         // Get last user message (needed for both route and completion handling)
@@ -517,42 +724,87 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
 
         let message: string;
         let toolCalls: Array<{ toolName: string; arguments: Record<string, unknown> }> | undefined = undefined;
+        let executedSteps: StepRef[] | undefined;
+        let stoppedReason: StoppedReason | undefined;
 
 
         
         if (selectedRoute && !isRouteComplete) {
-            // Handle normal route processing
+            // Check if we have batch steps to execute
+            if (batchSteps && batchSteps.length > 0) {
+                // BATCH EXECUTION: Execute multiple steps in a single LLM call
+                logger.debug(`[ResponseModal] Executing batch of ${batchSteps.length} steps`);
 
-            const result = await this.processRouteResponse({
-                selectedRoute,
-                selectedStep,
-                responseDirectives,
-                session,
-                history,
-                context: effectiveContext,
-                lastMessageText,
-                historyEvents,
-                signal: responseContext.history ? undefined : undefined, // TODO: Fix signal passing
-            });
+                const batchResult = await this.executeBatchResponse({
+                    selectedRoute,
+                    batchSteps,
+                    responseDirectives,
+                    session,
+                    history,
+                    context: effectiveContext,
+                    historyEvents,
+                });
 
-            message = result.message;
-            toolCalls = result.toolCalls;
-            session = result.session;
+                message = batchResult.message;
+                toolCalls = batchResult.toolCalls;
+                session = batchResult.session;
+                executedSteps = batchResult.executedSteps;
+                stoppedReason = batchStoppedReason;
+
+            } else {
+                // SINGLE STEP EXECUTION: Fall back to single-step processing
+                // This happens when batch determination returns empty (first step needs input)
+                const result = await this.processRouteResponse({
+                    selectedRoute,
+                    selectedStep,
+                    responseDirectives,
+                    session,
+                    history,
+                    context: effectiveContext,
+                    lastMessageText,
+                    historyEvents,
+                    signal: undefined,
+                });
+
+                message = result.message;
+                toolCalls = result.toolCalls;
+                session = result.session;
+                
+                // Track executed step for single-step execution
+                if (selectedStep) {
+                    executedSteps = [{
+                        id: selectedStep.id,
+                        routeId: selectedRoute.id,
+                    }];
+                }
+                stoppedReason = batchStoppedReason || 'needs_input';
+            }
 
         } else if (isRouteComplete && selectedRoute) {
             // Handle route completion
+            logger.debug(`[ResponseModal] Generating completion message for route: ${selectedRoute.title}`);
 
-            message = await this.handleRouteCompletion({
-                selectedRoute,
-                session,
-                context: effectiveContext,
-                lastMessageText,
-                historyEvents,
-            });
+            try {
+                message = await this.handleRouteCompletion({
+                    selectedRoute,
+                    session,
+                    context: effectiveContext,
+                    lastMessageText,
+                    historyEvents,
+                    signal: undefined,
+                });
 
-            // Set step to END_ROUTE marker
-            session = enterStep(session, END_ROUTE_ID, "Route completed");
-            logger.debug(`[ResponseModal] Route ${selectedRoute.title} completed. Entered END_ROUTE step.`);
+                // Set step to END_ROUTE marker
+                session = enterStep(session, END_ROUTE_ID, "Route completed");
+                stoppedReason = 'route_complete';
+                logger.debug(`[ResponseModal] Route ${selectedRoute.title} completed. Entered END_ROUTE step.`);
+            } catch (error) {
+                logger.error(`[ResponseModal] Error generating completion message:`, error);
+                // Fallback to simple completion message
+                message = `Thank you! I've recorded all the information for your ${selectedRoute.title.toLowerCase()}.`;
+                session = enterStep(session, END_ROUTE_ID, "Route completed");
+                stoppedReason = 'route_complete';
+            }
 
         } else {
             // Fallback: No routes defined, generate a simple response
@@ -562,16 +814,291 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 context: effectiveContext,
                 session,
             });
+            
+            // For fallback responses, set empty executedSteps and no stoppedReason
+            // since there's no route/step execution happening
+            executedSteps = [];
+            stoppedReason = undefined;
         }
 
+        // Ensure response structure completeness (Requirement 8.1, 8.2, 8.3)
+        // - executedSteps: array of steps executed (empty array if none)
+        // - stoppedReason: why execution stopped (undefined for fallback)
+        // - session.currentStep: reflects final step position
         return {
             message,
             session,
             toolCalls,
             isRouteComplete,
+            executedSteps: executedSteps || [],
+            stoppedReason,
+        };
+    }
+
+    /**
+     * Execute a batch of steps with a single LLM call
+     * 
+     * This method:
+     * 1. Executes all prepare hooks for steps in the batch (in order)
+     * 2. Builds a combined prompt using BatchPromptBuilder
+     * 3. Makes a single LLM call
+     * 4. Collects data from the response for all steps
+     * 5. Executes all finalize hooks for steps in the batch (in order)
+     * 
+     * @private
+     * **Validates: Requirements 1.1, 4.4, 5.1, 5.2**
+     */
+    private async executeBatchResponse(params: {
+        selectedRoute: Route<TContext, TData>;
+        batchSteps: StepOptions<TContext, TData>[];
+        responseDirectives?: string[];
+        session: SessionState<TData>;
+        history: HistoryItem[];
+        context: TContext;
+        historyEvents: Event[];
+        signal?: AbortSignal;
+    }): Promise<{
+        message: string;
+        toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
+        session: SessionState<TData>;
+        executedSteps: StepRef[];
+    }> {
+        const { selectedRoute, batchSteps, history, context, historyEvents, signal } = params;
+        let session = params.session;
+
+        logger.debug(`[ResponseModal] Starting batch execution for ${batchSteps.length} steps`);
+
+        // Create hook executor function
+        const executeHook = async (
+            hook: HookFunction<TContext, TData>,
+            hookContext: TContext,
+            data?: Partial<TData>,
+            step?: StepOptions<TContext, TData>
+        ): Promise<void> => {
+            // Find the route for this step
+            const route = selectedRoute;
+            // Convert StepOptions to Step if needed for executePrepareFinalize
+            const stepInstance = step?.id ? route.getStep(step.id) : undefined;
+            await this.executePrepareFinalize(hook, hookContext, data, route, stepInstance);
+        };
+
+        // PHASE 1: Execute all prepare hooks (Requirement 5.1)
+        logger.debug(`[ResponseModal] Executing prepare hooks for batch`);
+        const prepareResult = await this.batchExecutor.executePrepareHooks({
+            steps: batchSteps,
+            context,
+            data: session.data,
+            executeHook,
+        });
+
+        if (!prepareResult.success) {
+            // Prepare hook failed - return error response
+            logger.error(`[ResponseModal] Prepare hook failed:`, prepareResult.error);
+            throw new ResponseGenerationError(
+                `Prepare hook failed: ${prepareResult.error?.message}`,
+                { 
+                    phase: 'prepare_hooks', 
+                    context: { 
+                        stepId: prepareResult.error?.stepId,
+                        executedSteps: prepareResult.executedSteps,
+                    } 
+                }
+            );
+        }
+
+        // PHASE 2: Build combined prompt using BatchPromptBuilder (Requirement 4.4)
+        logger.debug(`[ResponseModal] Building batch prompt`);
+        const batchPromptResult = await this.batchPromptBuilder.buildBatchPrompt({
+            steps: batchSteps,
+            route: selectedRoute,
+            history: historyEvents,
+            context,
+            session,
+            agentOptions: this.agent.getAgentOptions(),
+        });
+
+        logger.debug(`[ResponseModal] Batch prompt built with ${batchPromptResult.stepCount} steps, collecting: ${batchPromptResult.collectFields.join(', ')}`);
+
+        // Build response schema for batch (includes all collect fields)
+        const responseSchema = this.buildBatchResponseSchema(batchPromptResult.collectFields);
+
+        // Collect available tools for AI (from all steps in batch)
+        const availableTools = this.collectBatchAvailableTools(selectedRoute, batchSteps);
+
+        // PHASE 3: Make single LLM call (Requirement 4.4)
+        logger.debug(`[ResponseModal] Making LLM call for batch`);
+        const agentOptions = this.agent.getAgentOptions();
+        const result = await agentOptions.provider.generateMessage({
+            prompt: batchPromptResult.prompt,
+            history: historyEvents,
+            context,
+            tools: availableTools,
+            signal,
+            parameters: responseSchema ? { jsonSchema: responseSchema, schemaName: "batch_response" } : undefined,
+        });
+
+        let message = result.structured?.message || result.message;
+        let toolCalls = result.structured?.toolCalls;
+
+        logger.debug(`[ResponseModal] LLM response received for batch`);
+
+        // Execute tools if any
+        if (toolCalls && toolCalls.length > 0) {
+            const toolResult = await this.executeUnifiedToolLoop({
+                toolCalls,
+                context,
+                session,
+                history,
+                selectedRoute,
+                responsePrompt: batchPromptResult.prompt,
+                availableTools,
+                responseSchema,
+                signal,
+            });
+
+            session = toolResult.session;
+            toolCalls = toolResult.finalToolCalls;
+            if (toolResult.finalMessage) {
+                message = toolResult.finalMessage;
+            }
+        }
+
+        // PHASE 4: Collect data from response for all steps (Requirement 6.1, 6.2, 6.3)
+        logger.debug(`[ResponseModal] Collecting batch data`);
+        const collectResult = this.batchExecutor.collectBatchData({
+            steps: batchSteps,
+            llmResponse: result.structured || {},
+            session,
+            schema: this.agent.getSchema(),
+        });
+
+        session = collectResult.session;
+
+        if (collectResult.collectedData && Object.keys(collectResult.collectedData).length > 0) {
+            // Update agent's collected data
+            await this.agent.updateCollectedData(collectResult.collectedData);
+            logger.debug(`[ResponseModal] Batch collected data:`, collectResult.collectedData);
+        }
+
+        if (collectResult.validationErrors && collectResult.validationErrors.length > 0) {
+            logger.warn(`[ResponseModal] Batch data validation errors:`, collectResult.validationErrors);
+        }
+
+        // Update session to final step position
+        const lastStep = batchSteps[batchSteps.length - 1];
+        if (lastStep?.id) {
+            session = enterStep(session, lastStep.id, lastStep.description);
+            logger.debug(`[ResponseModal] Updated session to final batch step: ${lastStep.id}`);
+        }
+
+        // PHASE 5: Execute all finalize hooks (Requirement 5.2)
+        logger.debug(`[ResponseModal] Executing finalize hooks for batch`);
+        const finalizeResult = await this.batchExecutor.executeFinalizeHooks({
+            steps: batchSteps,
+            context,
+            data: session.data,
+            executeHook,
+        });
+
+        if (finalizeResult.errors && finalizeResult.errors.length > 0) {
+            // Log finalize errors but don't fail (Requirement 5.5)
+            logger.warn(`[ResponseModal] Some finalize hooks failed:`, finalizeResult.errors);
+        }
+
+        // Build executed steps list
+        const executedSteps: StepRef[] = batchSteps
+            .filter(step => step.id)
+            .map(step => ({
+                id: step.id!,
+                routeId: selectedRoute.id,
+            }));
+
+        logger.debug(`[ResponseModal] Batch execution complete. Executed ${executedSteps.length} steps`);
+
+        return {
+            message,
+            toolCalls,
+            session,
+            executedSteps,
         };
     }
 
+    /**
+     * Build response schema for batch execution
+     * @private
+     */
+    private buildBatchResponseSchema(collectFields: string[]): Record<string, unknown> {
+        const properties: Record<string, unknown> = {
+            message: {
+                type: "string",
+                description: "Your response to the user",
+            },
+        };
+
+        // Add collect fields to schema
+        for (const field of collectFields) {
+            properties[field] = {
+                type: "string",
+                description: `Collected value for ${field}`,
+            };
+        }
+
+        return {
+            type: "object",
+            properties,
+            required: ["message"],
+            additionalProperties: true,
+        };
+    }
+
+    /**
+     * Collect available tools from all steps in the batch
+     * @private
+     */
+    private collectBatchAvailableTools(
+        route: Route<TContext, TData>,
+        batchSteps: StepOptions<TContext, TData>[]
+    ): Array<{
+        id: string;
+        name: string;
+        description?: string;
+        parameters?: unknown;
+    }> {
+        const availableTools = new Map<string, Tool<TContext, TData>>();
+
+        // Add agent-level tools
+        this.agent.getTools().forEach((tool) => {
+            availableTools.set(tool.id, tool);
+        });
+
+        // Add route-level tools
+        route.getTools().forEach((tool: Tool<TContext, TData>) => {
+            availableTools.set(tool.id, tool);
+        });
+
+        // Add step-level tools from all batch steps
+        for (const step of batchSteps) {
+            if (step.tools) {
+                for (const toolRef of step.tools) {
+                    if (typeof toolRef === "string") {
+                        // Reference to registered tool - already in availableTools
+                    } else if (typeof toolRef === 'object' && 'id' in toolRef && toolRef.id) {
+                        // Inline tool definition
+                        availableTools.set(toolRef.id, toolRef);
+                    }
+                }
+            }
+        }
+
+        // Convert to the format expected by AI providers
+        return Array.from(availableTools.values()).map((tool) => ({
+            id: tool.id,
+            name: tool.name || tool.id,
+            description: tool.description,
+            parameters: tool.parameters,
+        }));
+    }
+
     /**
      * Unified streaming response generation
      * @private
@@ -579,7 +1106,17 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
     private async *generateUnifiedStreamingResponse(
         responseContext: ResponseContext<TContext, TData>
     ): AsyncGenerator<AgentResponseStreamChunk<TData>> {
-        const { effectiveContext, session: initialSession, history, selectedRoute, selectedStep, responseDirectives, isRouteComplete } = responseContext;
+        const { 
+            effectiveContext, 
+            session: initialSession, 
+            history, 
+            selectedRoute, 
+            selectedStep, 
+            responseDirectives, 
+            isRouteComplete,
+            batchSteps,
+            batchStoppedReason,
+        } = responseContext;
         const session = initialSession;
 
         // Get last user message (needed for both route and completion handling)
@@ -588,17 +1125,35 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
         const lastMessageText = getLastMessageFromHistory(historyEvents);
 
         if (selectedRoute && !isRouteComplete) {
-            // Handle normal route processing with streaming
-            yield* this.processRouteStreamingResponse({
-                selectedRoute,
-                selectedStep,
-                responseDirectives,
-                session,
-                history,
-                context: effectiveContext,
-                lastMessageText,
-                historyEvents,
-            });
+            // Check if we have batch steps to execute
+            if (batchSteps && batchSteps.length > 0) {
+                // BATCH EXECUTION: Execute multiple steps with streaming
+                // Note: For streaming, we still use batch execution but stream the response
+                logger.debug(`[ResponseModal] Streaming batch execution for ${batchSteps.length} steps`);
+
+                yield* this.streamBatchResponse({
+                    selectedRoute,
+                    batchSteps,
+                    responseDirectives,
+                    session,
+                    history,
+                    context: effectiveContext,
+                    historyEvents,
+                    batchStoppedReason,
+                });
+            } else {
+                // SINGLE STEP EXECUTION: Fall back to single-step streaming
+                yield* this.processRouteStreamingResponse({
+                    selectedRoute,
+                    selectedStep,
+                    responseDirectives,
+                    session,
+                    history,
+                    context: effectiveContext,
+                    lastMessageText,
+                    historyEvents,
+                });
+            }
 
         } else if (isRouteComplete && selectedRoute) {
             // Handle route completion streaming
@@ -619,6 +1174,148 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
             });
         }
     }
+
+    /**
+     * Stream a batch response with multiple steps
+     * 
+     * Similar to executeBatchResponse but streams the LLM response.
+     * 
+     * @private
+     */
+    private async *streamBatchResponse(params: {
+        selectedRoute: Route<TContext, TData>;
+        batchSteps: StepOptions<TContext, TData>[];
+        responseDirectives?: string[];
+        session: SessionState<TData>;
+        history: HistoryItem[];
+        context: TContext;
+        historyEvents: Event[];
+        batchStoppedReason?: StoppedReason;
+        signal?: AbortSignal;
+    }): AsyncGenerator<AgentResponseStreamChunk<TData>> {
+        const { selectedRoute, batchSteps, context, historyEvents, batchStoppedReason, signal } = params;
+        let session = params.session;
+
+        // Create hook executor function
+        const executeHook = async (
+            hook: HookFunction<TContext, TData>,
+            hookContext: TContext,
+            data?: Partial<TData>,
+            step?: StepOptions<TContext, TData>
+        ): Promise<void> => {
+            const route = selectedRoute;
+            const stepInstance = step?.id ? route.getStep(step.id) : undefined;
+            await this.executePrepareFinalize(hook, hookContext, data, route, stepInstance);
+        };
+
+        // PHASE 1: Execute all prepare hooks
+        const prepareResult = await this.batchExecutor.executePrepareHooks({
+            steps: batchSteps,
+            context,
+            data: session.data,
+            executeHook,
+        });
+
+        if (!prepareResult.success) {
+            // Yield error chunk
+            yield {
+                delta: "",
+                accumulated: "",
+                done: true,
+                session,
+                error: new ResponseGenerationError(
+                    `Prepare hook failed: ${prepareResult.error?.message}`,
+                    { phase: 'prepare_hooks' }
+                ),
+            };
+            return;
+        }
+
+        // PHASE 2: Build combined prompt
+        const batchPromptResult = await this.batchPromptBuilder.buildBatchPrompt({
+            steps: batchSteps,
+            route: selectedRoute,
+            history: historyEvents,
+            context,
+            session,
+            agentOptions: this.agent.getAgentOptions(),
+        });
+
+        const responseSchema = this.buildBatchResponseSchema(batchPromptResult.collectFields);
+        const availableTools = this.collectBatchAvailableTools(selectedRoute, batchSteps);
+
+        // PHASE 3: Stream LLM response
+        const agentOptions = this.agent.getAgentOptions();
+        const stream = agentOptions.provider.generateMessageStream({
+            prompt: batchPromptResult.prompt,
+            history: historyEvents,
+            context,
+            tools: availableTools,
+            signal,
+            parameters: responseSchema ? { jsonSchema: responseSchema, schemaName: "batch_stream_response" } : undefined,
+        });
+
+        // Build executed steps list
+        const executedSteps: StepRef[] = batchSteps
+            .filter(step => step.id)
+            .map(step => ({
+                id: step.id!,
+                routeId: selectedRoute.id,
+            }));
+
+        // Stream chunks
+        for await (const chunk of stream) {
+            // On final chunk, collect data and execute finalize hooks
+            if (chunk.done) {
+                // Collect data from response
+                if (chunk.structured) {
+                    const collectResult = this.batchExecutor.collectBatchData({
+                        steps: batchSteps,
+                        llmResponse: chunk.structured,
+                        session,
+                        schema: this.agent.getSchema(),
+                    });
+
+                    session = collectResult.session;
+
+                    if (collectResult.collectedData && Object.keys(collectResult.collectedData).length > 0) {
+                        await this.agent.updateCollectedData(collectResult.collectedData);
+                    }
+                }
+
+                // Update session to final step position
+                const lastStep = batchSteps[batchSteps.length - 1];
+                if (lastStep?.id) {
+                    session = enterStep(session, lastStep.id, lastStep.description);
+                }
+
+                // Execute finalize hooks
+                await this.batchExecutor.executeFinalizeHooks({
+                    steps: batchSteps,
+                    context,
+                    data: session.data,
+                    executeHook,
+                });
+
+                // Finalize session
+                await this.finalizeSession(session, context);
+            }
+
+            yield {
+                delta: chunk.delta,
+                accumulated: chunk.accumulated,
+                done: chunk.done,
+                session,
+                toolCalls: chunk.structured?.toolCalls,
+                isRouteComplete: false,
+                executedSteps: chunk.done ? executedSteps : undefined,
+                stoppedReason: chunk.done ? batchStoppedReason : undefined,
+                metadata: chunk.metadata,
+                structured: chunk.structured,
+            };
+        }
+    }
+
     /**
        * Execute prepare function for current step if available
        * @private
@@ -698,12 +1395,27 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
         if (selectedStep) {
             nextStep = selectedStep;
         } else {
-            // New route or no step selected - get initial step or first valid step
+            // Determine current step from session if we're already in this route
+            const isInSameRoute = session.currentRoute?.id === selectedRoute.id;
+            const currentStep = isInSameRoute && session.currentStep
+                ? selectedRoute.getStep(session.currentStep.id)
+                : undefined;
+
+            logger.debug(`[ResponseModal] Step determination: route match=${isInSameRoute}, currentRoute=${session.currentRoute?.id}, selectedRoute=${selectedRoute.id}, currentStep=${currentStep?.id || 'none'}`);
+
+            // Get candidate steps based on current position in the route
             const routingEngine = this.agent.getRoutingEngine();
-            const candidates = routingEngine.getCandidateSteps(selectedRoute, undefined, session.data || {});
+            const candidates = await routingEngine.getCandidateStepsWithConditions(
+                selectedRoute, 
+                currentStep, // Pass current step instead of undefined to maintain progression
+                createTemplateContext({ data: session.data, session, context })
+            );
+            
+            logger.debug(`[ResponseModal] Found ${candidates.length} candidate steps${currentStep ? ' from current step ' + currentStep.id : ' (new route entry)'}`);
+            
             if (candidates.length > 0) {
                 nextStep = candidates[0].step;
-                logger.debug(`[ResponseModal] Using first valid step: ${nextStep.id} for new route`);
+                logger.debug(`[ResponseModal] Using first valid step: ${nextStep.id}${currentStep ? ' (progressing from ' + currentStep.id + ')' : ' for new route'}`);
             } else {
                 // Fallback to initial step even if it should be skipped
                 nextStep = selectedRoute.initialStep;
@@ -752,6 +1464,15 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
         let message = result.structured?.message || result.message;
         let toolCalls = result.structured?.toolCalls;
 
+        // Debug: Log initial AI response
+        logger.debug(`[ResponseModal] Initial AI response:`, {
+            hasMessage: !!message,
+            messageLength: message?.length || 0,
+            hasToolCalls: !!toolCalls,
+            toolCallsCount: toolCalls?.length || 0,
+            toolNames: toolCalls?.map(tc => tc.toolName) || [],
+        });
+
         // Execute tools with unified loop handling
         const toolResult = await this.executeUnifiedToolLoop({
             toolCalls,
@@ -800,11 +1521,22 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
         if (selectedStep) {
             nextStep = selectedStep;
         } else {
+            // Determine current step from session if we're already in this route
+            const currentStep = session.currentRoute?.id === selectedRoute.id && session.currentStep
+                ? selectedRoute.getStep(session.currentStep.id)
+                : undefined;
+
+            // Get candidate steps based on current position in the route
             const routingEngine = this.agent.getRoutingEngine();
-            const candidates = routingEngine.getCandidateSteps(selectedRoute, undefined, session.data || {});
+            const candidates = await routingEngine.getCandidateStepsWithConditions(
+                selectedRoute, 
+                currentStep, // Pass current step instead of undefined to maintain progression
+                createTemplateContext({ data: session.data, session, context })
+            );
+            
             if (candidates.length > 0) {
                 nextStep = candidates[0].step;
-                logger.debug(`[ResponseModal] Using first valid step: ${nextStep.id} for new route`);
+                logger.debug(`[ResponseModal] Using first valid step: ${nextStep.id}${currentStep ? ' (progressing from ' + currentStep.id + ')' : ' for new route'}`);
             } else {
                 nextStep = selectedRoute.initialStep;
                 logger.warn(`[ResponseModal] No valid steps found, using initial step: ${nextStep.id}`);
@@ -887,6 +1619,10 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 await this.finalizeSession(session, context);
             }
 
+            // Response structure completeness (Requirement 8.1, 8.2, 8.3)
+            // - executedSteps: single step executed in this response
+            // - stoppedReason: 'needs_input' for single-step execution (waiting for user input)
+            // - session.currentStep: reflects the executed step
             yield {
                 delta: chunk.delta,
                 accumulated: chunk.accumulated,
@@ -894,6 +1630,8 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 session,
                 toolCalls,
                 isRouteComplete: false,
+                executedSteps: chunk.done ? [{ id: nextStep.id, routeId: selectedRoute.id }] : undefined,
+                stoppedReason: chunk.done ? 'needs_input' : undefined,
                 metadata: chunk.metadata,
                 structured: chunk.structured,
             };
@@ -934,7 +1672,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
 
             // Execute initial dynamic tool calls
             if (toolCalls && toolCalls.length > 0) {
-                logger.debug(`[ResponseModal] Executing ${toolCalls.length} dynamic tool calls`);
+                logger.debug(`[ResponseModal] Executing ${toolCalls.length} dynamic tool calls:`, toolCalls.map(tc => tc.toolName));
 
                 for (const toolCall of toolCalls) {
                     const tool = this.findAvailableTool(toolCall.toolName, selectedRoute);
@@ -1009,7 +1747,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
 
             while (hasToolCalls && toolLoopCount < MAX_TOOL_LOOPS) {
                 toolLoopCount++;
-                logger.debug(`[ResponseModal] Starting tool loop ${toolLoopCount}/${MAX_TOOL_LOOPS}`);
+                logger.debug(`[ResponseModal] Starting tool loop ${toolLoopCount}/${MAX_TOOL_LOOPS} with ${toolCalls?.length || 0} tool calls`);
 
                 // Create tool result events with proper Event format structure
                 const toolResultEvents: Event<ToolEventData>[] = [];
@@ -1041,12 +1779,21 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 const updatedHistoryEvents = [...historyEvents, ...toolResultEvents];
 
                 // Make follow-up AI call to see if more tools are needed
+                // After first iteration, don't provide tools to force a text response
                 const agentOptions = this.agent.getAgentOptions();
+                const shouldProvideTools = toolLoopCount === 1;
+                
+                logger.debug(`[ResponseModal] Making follow-up AI call (loop ${toolLoopCount}):`, {
+                    providingTools: shouldProvideTools,
+                    toolsCount: shouldProvideTools ? availableTools.length : 0,
+                    addingTextInstruction: toolLoopCount > 1,
+                });
+
                 const followUpResult = await agentOptions.provider.generateMessage({
-                    prompt: responsePrompt,
+                    prompt: responsePrompt + (toolLoopCount > 1 ? "\n\nProvide a text response to the user based on the tool results." : ""),
                     history: updatedHistoryEvents, // Use Event[] for AI provider
                     context,
-                    tools: availableTools,
+                    tools: shouldProvideTools ? availableTools : [], // Only provide tools on first iteration
                     parameters: responseSchema ? {
                         jsonSchema: responseSchema,
                         schemaName: "tool_followup",
@@ -1058,6 +1805,14 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 const followUpToolCalls = followUpResult.structured?.toolCalls;
                 hasToolCalls = followUpToolCalls && followUpToolCalls.length > 0;
 
+                logger.debug(`[ResponseModal] Follow-up AI response (loop ${toolLoopCount}):`, {
+                    hasMessage: !!followUpResult.message,
+                    messageLength: followUpResult.message?.length || 0,
+                    hasToolCalls,
+                    toolCallsCount: followUpToolCalls?.length || 0,
+                    toolNames: followUpToolCalls?.map(tc => tc.toolName) || [],
+                });
+
                 if (hasToolCalls) {
                     logger.debug(`[ResponseModal] Follow-up call produced ${followUpToolCalls!.length} additional tool calls`);
 
@@ -1136,6 +1891,13 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 logger.warn(`[ResponseModal] Tool loop limit reached (${MAX_TOOL_LOOPS}), stopping`);
             }
 
+            logger.debug(`[ResponseModal] Tool loop completed:`, {
+                totalIterations: toolLoopCount,
+                hasFinalMessage: !!finalMessage,
+                finalMessageLength: finalMessage?.length || 0,
+                finalToolCallsCount: toolCalls?.length || 0,
+            });
+
             return {
                 session,
                 finalToolCalls: toolCalls,
@@ -1162,15 +1924,34 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
             let updatedSession = session;
 
             // Extract collected data from final response (only for route-based interactions)
-            if (selectedRoute && result.structured && nextStep?.collect) {
+            if (selectedRoute && result.structured) {
                 try {
                     const collectedData: Record<string, unknown> = {};
                     // AgentStructuredResponse extends Record<string, unknown>, so we can safely access properties
                     const structuredData = result.structured;
 
-                    for (const field of nextStep.collect) {
+                    // Collect ALL route fields (required + optional) from structured response
+                    const allRouteFields = new Set<string>();
+                    
+                    // Add route required fields
+                    if (selectedRoute.requiredFields) {
+                        selectedRoute.requiredFields.forEach(field => allRouteFields.add(String(field)));
+                    }
+                    
+                    // Add route optional fields
+                    if (selectedRoute.optionalFields) {
+                        selectedRoute.optionalFields.forEach(field => allRouteFields.add(String(field)));
+                    }
+                    
+                    // Also include current step's collect fields (in case they're not in route fields)
+                    if (nextStep?.collect) {
+                        nextStep.collect.forEach(field => allRouteFields.add(String(field)));
+                    }
+
+                    // Extract all available fields from structured response
+                    for (const field of allRouteFields) {
                         const fieldKey = String(field);
-                        if (fieldKey in structuredData) {
+                        if (fieldKey in structuredData && structuredData[fieldKey] !== undefined && structuredData[fieldKey] !== null) {
                             collectedData[fieldKey] = structuredData[fieldKey];
                         }
                     }
@@ -1244,37 +2025,66 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
             prompt: endStepSpec.prompt || "Summarize what was accomplished and confirm completion based on the conversation history and collected data",
         });
 
-        // Build response schema for completion
-        const responseSchema = this.responseEngine.responseSchemaForRoute(selectedRoute, completionStep, this.agent.getSchema());
-        const templateContext = { context, session, history: historyEvents }; // Use Event[] for template context
+        // Build response schema for completion (message only, no data collection)
+        const completionSchema = {
+            type: "object",
+            properties: {
+                message: {
+                    type: "string",
+                    description: "Completion message confirming what was accomplished",
+                },
+            },
+            required: ["message"],
+            additionalProperties: false,
+        };
+        
+        const templateContext = createTemplateContext({ context, session, history: historyEvents });
+
+        // Build completion response prompt using ResponseEngine
+        // Filter out conditional guidelines - only include always-active ones
+        const alwaysActiveGuidelines = [
+            ...this.agent.getGuidelines().filter(g => !g.condition),
+            ...selectedRoute.getGuidelines().filter(g => !g.condition),
+        ];
+        let completitionPrompt =  "Summarize what was accomplished and confirm completion"
+        if(endStepSpec.prompt){
+            completitionPrompt = await render(endStepSpec.prompt, templateContext)
+        }
 
-        // Build completion response prompt
         const completionPrompt = await this.responseEngine.buildResponsePrompt({
             route: selectedRoute,
             currentStep: completionStep,
             rules: selectedRoute.getRules(),
             prohibitions: selectedRoute.getProhibitions(),
-            directives: undefined, // No directives for completion
-            history: historyEvents, // Use Event[] for buildResponsePrompt
-            lastMessage: lastMessageText, // Use string for buildResponsePrompt
+            directives: [
+                `Task completed: ${selectedRoute.title}`,
+                `Collected data: ${JSON.stringify(session.data, null, 2)}`,
+                "Do NOT ask for more information - the task is complete",
+                completitionPrompt,
+            ],
+            history: historyEvents,
+            lastMessage: lastMessageText,
             agentOptions: this.agent.getAgentOptions(),
-            combinedGuidelines: [...this.agent.getGuidelines(), ...selectedRoute.getGuidelines()],
+            combinedGuidelines: alwaysActiveGuidelines, // Only non-conditional guidelines
             combinedTerms: this.mergeTerms(this.agent.getTerms(), selectedRoute.getTerms()),
             context,
             session,
-            agentSchema: this.agent.getSchema(),
+            agentSchema: undefined, // No data collection schema for completion
         });
 
         // Generate completion message using AI provider
         const agentOptions = this.agent.getAgentOptions();
+        logger.debug(`[ResponseModal] Calling AI provider for completion message...`);
+
         const completionResult = await agentOptions.provider.generateMessage({
             prompt: completionPrompt,
-            history: historyEvents, // Use Event[] for AI provider
+            history: historyEvents,
             context,
             signal,
-            parameters: { jsonSchema: responseSchema, schemaName: "completion_message" },
+            parameters: { jsonSchema: completionSchema, schemaName: "completion_message" },
         });
 
+        logger.debug(`[ResponseModal] AI provider returned completion result`);
         const message = completionResult.structured?.message || completionResult.message;
         logger.debug(`[ResponseModal] Generated completion message for route: ${selectedRoute.title}`);
 
@@ -1333,7 +2143,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
 
         // Build response schema for completion
         const responseSchema = this.responseEngine.responseSchemaForRoute(selectedRoute, completionStep, this.agent.getSchema());
-        const templateContext = { context, session, history: historyEvents }; // Use Event[] for template context
+        const templateContext = createTemplateContext({ context, session, history: historyEvents }); // Use Event[] for template context
 
         // Build completion response prompt
         const completionPrompt = await this.responseEngine.buildResponsePrompt({
@@ -1401,6 +2211,10 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 await this.finalizeSession(session, context);
             }
 
+            // Response structure completeness (Requirement 8.1, 8.2, 8.3)
+            // - executedSteps: empty for route completion (no new steps executed)
+            // - stoppedReason: 'route_complete' for completed routes
+            // - session.currentStep: set to END_ROUTE
             yield {
                 delta: chunk.delta,
                 accumulated: chunk.accumulated,
@@ -1408,6 +2222,8 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 session,
                 toolCalls: undefined,
                 isRouteComplete: true,
+                executedSteps: chunk.done ? [] : undefined,
+                stoppedReason: chunk.done ? 'route_complete' : undefined,
                 metadata: chunk.metadata,
                 structured: chunk.structured,
             };
@@ -1502,6 +2318,10 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 await this.finalizeSession(session, context);
             }
 
+            // Response structure completeness (Requirement 8.1, 8.2, 8.3)
+            // - executedSteps: empty for fallback (no route/step execution)
+            // - stoppedReason: undefined for fallback (no route context)
+            // - session.currentStep: unchanged (no step progression)
             yield {
                 delta: chunk.delta,
                 accumulated: chunk.accumulated,
@@ -1509,6 +2329,8 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 session,
                 toolCalls: undefined,
                 isRouteComplete: false,
+                executedSteps: chunk.done ? [] : undefined,
+                stoppedReason: undefined,
                 metadata: chunk.metadata,
                 structured: chunk.structured,
             };