@falai/agent 0.1.0-alpha2 → 0.1.0-alpha3

package/dist/cjs/src/core/ResponseModal.js

@@ -9,6 +9,8 @@ const types_1 = require("../types");
 const Step_1 = require("./Step");
 const ResponseEngine_1 = require("./ResponseEngine");
 const ResponsePipeline_1 = require("./ResponsePipeline");
+const BatchExecutor_1 = require("./BatchExecutor");
+const BatchPromptBuilder_1 = require("./BatchPromptBuilder");
 const utils_1 = require("../utils");
 const template_1 = require("../utils/template");
 const constants_1 = require("../constants");
@@ -53,6 +55,10 @@ class ResponseModal {
         // Initialize response pipeline with agent dependencies
         this.responsePipeline = new ResponsePipeline_1.ResponsePipeline(this.agent.getAgentOptions(), () => this.agent.getRoutes(), // Pass a function to get routes dynamically
         this.agent.getTools(), this.agent.getRoutingEngine(), this.agent.updateContext.bind(this.agent), this.agent.getUpdateDataMethod(), this.agent.updateCollectedData.bind(this.agent), this.getToolManager());
+        // Initialize batch executor for multi-step execution
+        this.batchExecutor = new BatchExecutor_1.BatchExecutor();
+        // Initialize batch prompt builder for combined prompts
+        this.batchPromptBuilder = new BatchPromptBuilder_1.BatchPromptBuilder();
     }
     /**
      * Generate a non-streaming response using unified logic
@@ -273,6 +279,7 @@ class ResponseModal {
                 throw ResponseGenerationError.fromError(error, 'step_preparation', params, { session, effectiveContext });
             }
             // PHASE 2: ROUTING + STEP SELECTION - Determine which route and step to use
+            // Also performs pre-extraction and batch determination
             let routingResult;
             try {
                 routingResult = await this.handleUnifiedRoutingAndStepSelection({
@@ -293,6 +300,9 @@ class ResponseModal {
                 selectedStep: routingResult.selectedStep,
                 responseDirectives: routingResult.responseDirectives,
                 isRouteComplete: routingResult.isRouteComplete,
+                batchSteps: routingResult.batchSteps,
+                batchStoppedReason: routingResult.batchStoppedReason,
+                batchStoppedAtStep: routingResult.batchStoppedAtStep,
             };
         }
         catch (error) {
@@ -320,12 +330,13 @@ class ResponseModal {
             });
             let updatedSession = routingResult.session;
             let isRouteComplete = routingResult.isRouteComplete;
-            // PRE-EXTRACTION: If entering a new route that collects data, extract data from user message first
+            // 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) {
-                const isEnteringNewRoute = !params.session.currentRoute ||
-                    params.session.currentRoute.id !== routingResult.selectedRoute.id;
-                if (isEnteringNewRoute && this.shouldPreExtractData(routingResult.selectedRoute)) {
+                // 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)) {
                     utils_1.logger.debug(`[ResponseModal] Pre-extracting data for route: ${routingResult.selectedRoute.title}`);
                     const extractedData = await this.preExtractRouteData({
                         route: routingResult.selectedRoute,
@@ -336,7 +347,7 @@ class ResponseModal {
                     });
                     if (extractedData && Object.keys(extractedData).length > 0) {
                         utils_1.logger.debug(`[ResponseModal] Pre-extracted data:`, extractedData);
-                        // Update session with pre-extracted data
+                        // Requirement 3.3: Merge pre-extracted data into session before batch determination
                         updatedSession = (0, utils_1.mergeCollected)(updatedSession, extractedData);
                         // Also update agent's collected data
                         await this.agent.updateCollectedData(extractedData);
@@ -349,6 +360,27 @@ class ResponseModal {
                     }
                 }
             }
+            // BATCH DETERMINATION: Use BatchExecutor to determine which steps can execute together
+            // Requirement 3.4: Pre-extraction results affect batch determination
+            let batchSteps;
+            let batchStoppedReason;
+            let batchStoppedAtStep;
+            if (routingResult.selectedRoute && !isRouteComplete) {
+                // Determine current step position for batch determination
+                const currentStep = routingResult.selectedStep ||
+                    (updatedSession.currentStep ? routingResult.selectedRoute.getStep(updatedSession.currentStep.id) : undefined);
+                utils_1.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;
+                utils_1.logger.debug(`[ResponseModal] Batch determined: ${batchSteps.length} steps, stopped reason: ${batchStoppedReason}`);
+            }
             // Determine next step using pipeline method for consistency
             const stepResult = await this.responsePipeline.determineNextStep({
                 selectedRoute: routingResult.selectedRoute,
@@ -362,6 +394,9 @@ class ResponseModal {
                 responseDirectives: routingResult.responseDirectives,
                 session: stepResult.session,
                 isRouteComplete, // Use updated completion status
+                batchSteps,
+                batchStoppedReason,
+                batchStoppedAtStep,
             };
         }
         catch (error) {
@@ -442,7 +477,7 @@ class ResponseModal {
      * @private
      */
     async generateUnifiedResponse(responseContext) {
-        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)
         // Convert HistoryItem[] to Event[] for internal processing
@@ -450,22 +485,54 @@ class ResponseModal {
         const lastMessageText = (0, utils_1.getLastMessageFromHistory)(historyEvents);
         let message;
         let toolCalls = undefined;
+        let executedSteps;
+        let stoppedReason;
         if (selectedRoute && !isRouteComplete) {
-            // Handle normal route processing
-            const result = await this.processRouteResponse({
-                selectedRoute,
-                selectedStep,
-                responseDirectives,
-                session,
-                history,
-                context: effectiveContext,
-                lastMessageText,
-                historyEvents,
-                signal: responseContext.history ? undefined : undefined, // TODO: Fix signal passing
-            });
-            message = result.message;
-            toolCalls = result.toolCalls;
-            session = result.session;
+            // Check if we have batch steps to execute
+            if (batchSteps && batchSteps.length > 0) {
+                // BATCH EXECUTION: Execute multiple steps in a single LLM call
+                utils_1.logger.debug(`[ResponseModal] Executing batch of ${batchSteps.length} steps`);
+                const batchResult = await this.executeBatchResponse({
+                    selectedRoute,
+                    batchSteps,
+                    responseDirectives,
+                    session,
+                    history,
+                    context: effectiveContext,
+                    historyEvents,
+                });
+                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
@@ -477,10 +544,11 @@ class ResponseModal {
                     context: effectiveContext,
                     lastMessageText,
                     historyEvents,
-                    signal: undefined, // TODO: Pass signal from responseContext
+                    signal: undefined,
                 });
                 // Set step to END_ROUTE marker
                 session = (0, utils_1.enterStep)(session, constants_1.END_ROUTE_ID, "Route completed");
+                stoppedReason = 'route_complete';
                 utils_1.logger.debug(`[ResponseModal] Route ${selectedRoute.title} completed. Entered END_ROUTE step.`);
             }
             catch (error) {
@@ -488,6 +556,7 @@ class ResponseModal {
                 // Fallback to simple completion message
                 message = `Thank you! I've recorded all the information for your ${selectedRoute.title.toLowerCase()}.`;
                 session = (0, utils_1.enterStep)(session, constants_1.END_ROUTE_ID, "Route completed");
+                stoppedReason = 'route_complete';
             }
         }
         else {
@@ -497,37 +566,268 @@ class ResponseModal {
                 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**
+     */
+    async executeBatchResponse(params) {
+        const { selectedRoute, batchSteps, history, context, historyEvents, signal } = params;
+        let session = params.session;
+        utils_1.logger.debug(`[ResponseModal] Starting batch execution for ${batchSteps.length} steps`);
+        // Create hook executor function
+        const executeHook = async (hook, hookContext, data, step) => {
+            // 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)
+        utils_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
+            utils_1.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)
+        utils_1.logger.debug(`[ResponseModal] Building batch prompt`);
+        const batchPromptResult = await this.batchPromptBuilder.buildBatchPrompt({
+            steps: batchSteps,
+            route: selectedRoute,
+            history: historyEvents,
+            context,
+            session,
+            agentOptions: this.agent.getAgentOptions(),
+        });
+        utils_1.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)
+        utils_1.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;
+        utils_1.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)
+        utils_1.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);
+            utils_1.logger.debug(`[ResponseModal] Batch collected data:`, collectResult.collectedData);
+        }
+        if (collectResult.validationErrors && collectResult.validationErrors.length > 0) {
+            utils_1.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 = (0, utils_1.enterStep)(session, lastStep.id, lastStep.description);
+            utils_1.logger.debug(`[ResponseModal] Updated session to final batch step: ${lastStep.id}`);
+        }
+        // PHASE 5: Execute all finalize hooks (Requirement 5.2)
+        utils_1.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)
+            utils_1.logger.warn(`[ResponseModal] Some finalize hooks failed:`, finalizeResult.errors);
+        }
+        // Build executed steps list
+        const executedSteps = batchSteps
+            .filter(step => step.id)
+            .map(step => ({
+            id: step.id,
+            routeId: selectedRoute.id,
+        }));
+        utils_1.logger.debug(`[ResponseModal] Batch execution complete. Executed ${executedSteps.length} steps`);
+        return {
+            message,
+            toolCalls,
+            session,
+            executedSteps,
         };
     }
+    /**
+     * Build response schema for batch execution
+     * @private
+     */
+    buildBatchResponseSchema(collectFields) {
+        const properties = {
+            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
+     */
+    collectBatchAvailableTools(route, batchSteps) {
+        const availableTools = new Map();
+        // Add agent-level tools
+        this.agent.getTools().forEach((tool) => {
+            availableTools.set(tool.id, tool);
+        });
+        // Add route-level tools
+        route.getTools().forEach((tool) => {
+            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
      */
     async *generateUnifiedStreamingResponse(responseContext) {
-        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)
         // Convert HistoryItem[] to Event[] for internal processing
         const historyEvents = (0, utils_1.historyToEvents)(history);
         const lastMessageText = (0, utils_1.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
+                utils_1.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
@@ -548,6 +848,114 @@ class ResponseModal {
             });
         }
     }
+    /**
+     * Stream a batch response with multiple steps
+     *
+     * Similar to executeBatchResponse but streams the LLM response.
+     *
+     * @private
+     */
+    async *streamBatchResponse(params) {
+        const { selectedRoute, batchSteps, context, historyEvents, batchStoppedReason, signal } = params;
+        let session = params.session;
+        // Create hook executor function
+        const executeHook = async (hook, hookContext, data, step) => {
+            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 = 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 = (0, utils_1.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
@@ -774,6 +1182,10 @@ class ResponseModal {
             if (chunk.done) {
                 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,
@@ -781,6 +1193,8 @@ class ResponseModal {
                 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,
             };
@@ -1266,6 +1680,10 @@ class ResponseModal {
             if (chunk.done) {
                 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,
@@ -1273,6 +1691,8 @@ class ResponseModal {
                 session,
                 toolCalls: undefined,
                 isRouteComplete: true,
+                executedSteps: chunk.done ? [] : undefined,
+                stoppedReason: chunk.done ? 'route_complete' : undefined,
                 metadata: chunk.metadata,
                 structured: chunk.structured,
             };
@@ -1347,6 +1767,10 @@ class ResponseModal {
             if (chunk.done) {
                 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,
@@ -1354,6 +1778,8 @@ class ResponseModal {
                 session,
                 toolCalls: undefined,
                 isRouteComplete: false,
+                executedSteps: chunk.done ? [] : undefined,
+                stoppedReason: undefined,
                 metadata: chunk.metadata,
                 structured: chunk.structured,
             };