@falai/agent 2.2.4 → 2.4.1

package/dist/core/ResponseModal.js

@@ -3,38 +3,15 @@
  * Provides both streaming and non-streaming response generation with unified logic
  */
 import { ResponseEngine } from "./ResponseEngine";
-import { ResponsePipeline, hasDirectivePositionField } from "./ResponsePipeline";
+import { ResponsePipeline } from "./ResponsePipeline";
 import { AutoChainExecutor } from "./AutoChainExecutor";
-import { cloneDeep, mergeCollected, enterStep, enterFlow, getLastMessageFromHistory, logger, historyToEvents, eventsToHistory, serializeToolResult, completeCurrentFlow, render } from "../utils";
+import { StepLifecycle } from "./StepLifecycle";
+import { SessionFinalizer } from "./SessionFinalizer";
+import { ToolLoopExecutor } from "./ToolLoopExecutor";
+import { SignalCoordinator } from "./SignalCoordinator";
+import { ResponseGenerationError } from "./ResponseGenerationError";
+import { cloneDeep, mergeCollected, logger, historyToEvents, completeCurrentFlow, render } from "../utils";
 import { createTemplateContext } from "../utils/template";
-/**
- * Error class for response generation failures
- */
-export class ResponseGenerationError extends Error {
-    constructor(message, details) {
-        super(message);
-        this.details = details;
-        this.name = 'ResponseGenerationError';
-        // Preserve stack trace from original error if available
-        if (details?.originalError instanceof Error && details.originalError.stack) {
-            this.stack = `${this.stack}\nCaused by: ${details.originalError.stack}`;
-        }
-    }
-    /**
-     * Create a ResponseGenerationError from an unknown error
-     */
-    static fromError(error, phase, params, context) {
-        const message = error instanceof Error ? error.message : String(error);
-        return new ResponseGenerationError(`[ResponseGenerationError] Response generation failed in ${phase}: ${message}. ` +
-            `Check provider configuration and the ${phase} phase handler.`, { originalError: error, params, phase, context });
-    }
-    /**
-     * Check if an error is a ResponseGenerationError
-     */
-    static isResponseGenerationError(error) {
-        return error instanceof ResponseGenerationError;
-    }
-}
 /**
  * ResponseModal class that encapsulates all response generation logic
  * Uses unified approach for both streaming and non-streaming responses
@@ -45,24 +22,64 @@ export class ResponseModal {
         this.options = options;
         // Initialize response engine
         this.responseEngine = new ResponseEngine(this.agent.promptSectionCache);
+        // Signal pre/post phase orchestration
+        this.signalCoordinator = new SignalCoordinator({
+            getFlows: () => this.agent.getFlows(),
+            signalProcessor: this.agent.signalProcessor,
+        });
         // Initialize response pipeline with agent dependencies
         this.responsePipeline = new ResponsePipeline(this.agent.getAgentOptions(), () => this.agent.getFlows(), // Pass a function to get flows dynamically
-        this.agent.getTools(), this.agent.getFlowRouter(), this.agent.updateContext.bind(this.agent), this.agent.getUpdateDataMethod(), this.agent.updateCollectedData.bind(this.agent), this.getToolManager(), this.agent.signalProcessor);
+        this.agent.getFlowRouter(), this.signalCoordinator, this.agent.updateCollectedData.bind(this.agent), () => this.agent.schema);
+        // Step prepare/finalize execution, shared by the prepare phase and finalizer
+        this.stepLifecycle = new StepLifecycle({
+            getFlows: () => this.agent.getFlows(),
+            toolManager: this.getToolManager(),
+            updateContext: this.agent.updateContext.bind(this.agent),
+            updateData: this.agent.updateCollectedData.bind(this.agent),
+        });
+        // Single owner of end-of-turn finalization (compaction + persistence + sync)
+        this.sessionFinalizer = new SessionFinalizer({
+            getCompactionOptions: () => this.agent.getCompactionOptions(),
+            getPersistenceManager: () => this.agent.getPersistenceManager(),
+            getAgentOptions: () => this.agent.getAgentOptions(),
+            getCurrentSession: () => this.agent.currentSession,
+            setCurrentSession: (session) => { this.agent.currentSession = session; },
+            stepLifecycle: this.stepLifecycle,
+            enableAutoSave: this.options?.enableAutoSave,
+        });
+        // Tool follow-up loop (run tools, ask the LLM again) + streaming batch execution
+        this.toolLoopExecutor = new ToolLoopExecutor({
+            toolManager: this.getToolManager(),
+            getAgentOptions: () => this.agent.getAgentOptions(),
+            updateContext: this.agent.updateContext.bind(this.agent),
+            updateCollectedData: this.agent.updateCollectedData.bind(this.agent),
+            updateSessionData: this.agent.getUpdateDataMethod(),
+            maxToolLoops: this.options?.maxToolLoops,
+        });
     }
     /**
      * Generate a non-streaming response using unified logic
      */
     async respond(params) {
+        // Snapshot the managed session so a failed turn has no in-memory effect:
+        // without this, mutations made before the failure leave the live session
+        // diverged from persisted state
+        const preTurnSession = this.agent.session.current
+            ? cloneDeep(this.agent.session.current)
+            : undefined;
         try {
             // Use unified response preparation and routing
             const responseContext = await this.prepareUnifiedResponseContext(params);
             // Generate response using unified logic
             const result = await this.generateUnifiedResponse(responseContext);
-            // Finalize session
-            await this.finalizeSession(result.session, responseContext.effectiveContext);
+            // Finalize session — the non-streaming turn's single finalize
+            await this.sessionFinalizer.finalize(result.session, responseContext.effectiveContext);
             return result;
         }
         catch (error) {
+            if (preTurnSession) {
+                this.agent.session.syncSession(preTurnSession);
+            }
             throw new ResponseGenerationError(`[ResponseGenerationError] Response generation failed: ${error instanceof Error ? error.message : String(error)}. ` +
                 `Check provider configuration and network connectivity.`, { originalError: error, params, phase: 'response_generation' });
         }
@@ -71,6 +88,10 @@ export class ResponseModal {
      * Generate a streaming response using unified logic
      */
     async *respondStream(params) {
+        // Same failed-turn rollback semantics as respond()
+        const preTurnSession = this.agent.session.current
+            ? cloneDeep(this.agent.session.current)
+            : undefined;
         try {
             // Use unified response preparation and routing
             const responseContext = await this.prepareUnifiedResponseContext(params);
@@ -78,6 +99,9 @@ export class ResponseModal {
             yield* this.generateUnifiedStreamingResponse(responseContext);
         }
         catch (error) {
+            if (preTurnSession) {
+                this.agent.session.syncSession(preTurnSession);
+            }
             // Stream error to caller
             yield {
                 delta: "",
@@ -105,16 +129,9 @@ export class ResponseModal {
             }
             history = this.agent.session.getHistory();
         }
-        // Get or create session
-        let session = await this.agent.session.getOrCreate();
-        // Merge agent's collected data into session (agent data takes precedence)
-        const collectedData = this.agent.getCollectedData();
-        if (Object.keys(collectedData).length > 0) {
-            session = mergeCollected(session, collectedData);
-            // Update the session manager with the merged data
-            await this.agent.session.setData(collectedData);
-            logger.debug("[ResponseModal] Merged agent collected data into stream session:", collectedData);
-        }
+        // Get or create session — session.data is the single source of truth,
+        // so no agent-side data merge is needed
+        const session = await this.agent.session.getOrCreate();
         // Stream response using existing respondStream method
         let finalMessage = "";
         let finalizedSession;
@@ -158,16 +175,9 @@ export class ResponseModal {
             }
             history = this.agent.session.getHistory();
         }
-        // Get or create session
-        let session = await this.agent.session.getOrCreate();
-        // Merge agent's collected data into session (agent data takes precedence)
-        const collectedData = this.agent.getCollectedData();
-        if (Object.keys(collectedData).length > 0) {
-            session = mergeCollected(session, collectedData);
-            // Update the session manager with the merged data
-            await this.agent.session.setData(collectedData);
-            logger.debug("[ResponseModal] Merged agent collected data into generate session:", collectedData);
-        }
+        // Get or create session — session.data is the single source of truth,
+        // so no agent-side data merge is needed
+        const session = await this.agent.session.getOrCreate();
         // Generate response using existing respond method
         const result = await this.respond({
             history,
@@ -211,14 +221,6 @@ export class ResponseModal {
     getToolManager() {
         return this.agent.tool;
     }
-    /**
-     * Post-phase signal replies replace the user-visible message after the
-     * response has otherwise completed. Undefined means "leave it unchanged";
-     * an empty string is an explicit replacement.
-     */
-    applyPostSignalReply(message, directive) {
-        return directive?.reply !== undefined ? directive.reply : message;
-    }
     /**
      * Collect scoped instructions from agent, flow, and step into a ScopedInstructions value.
      * @private
@@ -249,47 +251,48 @@ export class ResponseModal {
             const historyEvents = historyToEvents(simpleHistory);
             // Keep original HistoryItem[] format for external APIs
             const history = simpleHistory;
-            // Use ResponsePipeline for optimized context and session preparation
-            // This leverages existing optimizations and avoids code duplication
+            // Use ResponsePipeline for context and session preparation; context
+            // and session are passed explicitly — the pipeline holds no state
             let responseContext;
             try {
-                // Set current context and session in pipeline for consistency
-                this.responsePipeline.setContext(await this.agent.getContext());
-                this.responsePipeline.setCurrentSession(this.agent.currentSession);
                 responseContext = await this.responsePipeline.prepareResponseContext({
                     contextOverride,
                     session: params.session ? cloneDeep(params.session) : undefined,
+                    currentContext: await this.agent.getContext(),
+                    currentSession: this.agent.currentSession,
                 });
             }
             catch (error) {
                 throw ResponseGenerationError.fromError(error, 'pipeline_context_preparation', params);
             }
-            const { effectiveContext } = responseContext;
+            const { effectiveContext, contextAfterHook } = responseContext;
             let session = responseContext.session;
-            // Update our stored context if it was modified by beforeRespond hook
-            const storedContext = this.responsePipeline.getStoredContext();
-            if (storedContext !== undefined) {
+            // Sync the beforeRespond hook's context result back to the agent
+            if (contextAfterHook !== undefined) {
                 try {
-                    await this.agent.updateContext(storedContext);
+                    await this.agent.updateContext(contextAfterHook);
                 }
                 catch (error) {
-                    throw ResponseGenerationError.fromError(error, 'context_update_from_pipeline', params, { storedContext });
+                    throw ResponseGenerationError.fromError(error, 'context_update_from_pipeline', params, { contextAfterHook });
                 }
             }
-            // Merge agent's collected data into session (agent data takes precedence)
-            const collectedData = this.agent.getCollectedData();
-            if (Object.keys(collectedData).length > 0) {
+            // Apply data staged before any session existed (initialData,
+            // pre-session updateCollectedData calls). Reading the live session's
+            // data here would leak state across sessions when an explicit
+            // session is passed, so only the staging buffer is merged.
+            const stagedData = this.agent.consumePendingData();
+            if (Object.keys(stagedData).length > 0) {
                 try {
-                    session = mergeCollected(session, collectedData);
-                    logger.debug("[ResponseModal] Merged agent collected data into session:", collectedData);
+                    session = mergeCollected(session, stagedData);
+                    logger.debug("[ResponseModal] Merged staged agent data into session:", stagedData);
                 }
                 catch (error) {
-                    throw ResponseGenerationError.fromError(error, 'data_merging', params, { collectedData });
+                    throw ResponseGenerationError.fromError(error, 'data_merging', params, { stagedData });
                 }
             }
             // PHASE 1: PREPARE - Execute prepare function if current step has one
             try {
-                await this.executeStepPrepare(session, effectiveContext);
+                await this.stepLifecycle.runPrepare(session, effectiveContext);
             }
             catch (error) {
                 throw ResponseGenerationError.fromError(error, 'step_preparation', params, { session, effectiveContext });
@@ -298,7 +301,7 @@ export class ResponseModal {
             // Performs pre-extraction and step selection
             let routingResult;
             try {
-                routingResult = await this.handleUnifiedRoutingAndStepSelection({
+                routingResult = await this.responsePipeline.routeAndSelectStep({
                     session,
                     history: historyEvents,
                     context: effectiveContext,
@@ -331,443 +334,6 @@ export class ResponseModal {
             throw ResponseGenerationError.fromError(error, 'preparation', params);
         }
     }
-    /**
-     * Unified routing and step selection logic using ResponsePipeline for optimization
-     * @private
-     */
-    async handleUnifiedRoutingAndStepSelection(params) {
-        try {
-            // Create a fresh chain tracker for this turn (Requirement 22.1)
-            this.responsePipeline.createChainTracker();
-            // ROUTING SKIP OPTIMIZATION (Requirements 20.1, 20.2, 20.3):
-            // When the current step has collect fields AND pre-extraction populates at least
-            // one of those fields, skip FlowRouter.decideFlowAndStep for this turn.
-            const routingSkipResult = await this.attemptRoutingSkipForCollect(params);
-            if (routingSkipResult) {
-                // Even when routing is skipped, run pre-signal phase if processor is present
-                if (this.agent.signalProcessor) {
-                    const signalResult = await this.responsePipeline.runPreSignalPhase(params.session, params.context, params.history);
-                    // If signal halts, override the routing skip result
-                    if (signalResult.mergedDirective?.halt) {
-                        return {
-                            ...routingSkipResult,
-                            session: signalResult.updatedSession,
-                            signalFirings: signalResult.firings,
-                            signalHalted: true,
-                            signalHaltReply: signalResult.mergedDirective.reply,
-                        };
-                    }
-                    // If signal has position fields, override routing skip result
-                    if (hasDirectivePositionField(signalResult.mergedDirective)) {
-                        return this.applySignalPositionDirective(signalResult, params);
-                    }
-                    // Non-position directive: propagate for pre-LLM augmentation
-                    return {
-                        ...routingSkipResult,
-                        session: signalResult.updatedSession,
-                        signalFirings: signalResult.firings,
-                        signalPreDirective: signalResult.mergedDirective || undefined,
-                    };
-                }
-                return routingSkipResult;
-            }
-            // ── PARALLEL PRE-SIGNAL PHASE + ROUTING (Algorithm 5) ────────────────
-            // When signalProcessor is present, run pre-signals in parallel with routing.
-            // When absent, call the router directly (zero overhead, preserve current behavior).
-            if (this.agent.signalProcessor) {
-                // Run pre-signal phase in parallel with routing (Requirement 8.1)
-                const [signalResult, routingResult] = await Promise.all([
-                    this.responsePipeline.runPreSignalPhase(params.session, params.context, params.history),
-                    this.responsePipeline.handleRoutingAndStepSelection({
-                        session: params.session,
-                        history: params.history,
-                        context: params.context,
-                        signal: params.signal,
-                    }),
-                ]);
-                // ── Requirement 8.2: halt → discard routing, skip LLM ────────────
-                if (signalResult.mergedDirective?.halt) {
-                    return {
-                        selectedFlow: undefined,
-                        selectedStep: undefined,
-                        session: signalResult.updatedSession,
-                        isFlowComplete: false,
-                        signalFirings: signalResult.firings,
-                        signalHalted: true,
-                        signalHaltReply: signalResult.mergedDirective.reply,
-                    };
-                }
-                // ── Requirement 8.3: position directive → discard routing, apply signal position ──
-                if (hasDirectivePositionField(signalResult.mergedDirective)) {
-                    return this.applySignalPositionDirective(signalResult, params);
-                }
-                // ── Requirement 8.4: non-position directive → use routing, propagate augmentation ──
-                // ── Requirement 8.5: no directive → use routing as-is ─────────────
-                let updatedSession = signalResult.updatedSession;
-                // Apply data/context updates from signal to the routed session
-                if (signalResult.mergedDirective?.dataUpdate) {
-                    updatedSession = mergeCollected(updatedSession, signalResult.mergedDirective.dataUpdate);
-                }
-                // Use routing result for flow/step, but carry signal session state
-                // Merge routing session changes on top of signal session
-                const routingSession = routingResult.session;
-                updatedSession = {
-                    ...updatedSession,
-                    currentFlow: routingSession.currentFlow,
-                    currentStep: routingSession.currentStep,
-                    flowHistory: routingSession.flowHistory,
-                    pendingDirective: routingSession.pendingDirective,
-                };
-                const isFlowComplete = routingResult.isFlowComplete;
-                // PRE-EXTRACTION: same logic as below — extract data from user message
-                if (routingResult.selectedFlow && !isFlowComplete) {
-                    if (this.shouldPreExtractData(routingResult.selectedFlow)) {
-                        logger.debug(`[ResponseModal] Pre-extracting data for flow: ${routingResult.selectedFlow.title}`);
-                        const extractedData = await this.preExtractFlowData({
-                            route: routingResult.selectedFlow,
-                            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);
-                            updatedSession = mergeCollected(updatedSession, extractedData);
-                            await this.agent.updateCollectedData(extractedData);
-                        }
-                    }
-                }
-                // Determine next step
-                const stepResult = await this.responsePipeline.determineNextStep({
-                    selectedFlow: routingResult.selectedFlow,
-                    selectedStep: routingResult.selectedStep,
-                    session: updatedSession,
-                    isFlowComplete,
-                });
-                return {
-                    selectedFlow: stepResult.flowChanged || routingResult.selectedFlow,
-                    selectedStep: stepResult.nextStep,
-                    responseDirectives: routingResult.responseDirectives,
-                    session: stepResult.session,
-                    isFlowComplete: stepResult.flowChanged ? false : isFlowComplete,
-                    signalFirings: signalResult.firings,
-                    signalPreDirective: signalResult.mergedDirective || undefined,
-                };
-            }
-            // ── No signal processor: existing behavior (zero overhead) ────────────
-            const routingResult = await this.responsePipeline.handleRoutingAndStepSelection({
-                session: params.session,
-                history: params.history,
-                context: params.context,
-                signal: params.signal,
-            });
-            let updatedSession = routingResult.session;
-            const isFlowComplete = routingResult.isFlowComplete;
-            // PRE-EXTRACTION: If entering a flow that collects data, extract data from user message first
-            // This allows us to skip steps whose data is already provided
-            if (routingResult.selectedFlow && !isFlowComplete) {
-                // Always pre-extract when flow collects data (not just on new flow entry)
-                // This ensures step selection has the most up-to-date data
-                if (this.shouldPreExtractData(routingResult.selectedFlow)) {
-                    logger.debug(`[ResponseModal] Pre-extracting data for flow: ${routingResult.selectedFlow.title}`);
-                    const extractedData = await this.preExtractFlowData({
-                        route: routingResult.selectedFlow,
-                        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);
-                        // Merge pre-extracted data into session before step selection
-                        updatedSession = mergeCollected(updatedSession, extractedData);
-                        // Also update agent's collected data
-                        await this.agent.updateCollectedData(extractedData);
-                    }
-                }
-            }
-            // Determine next step using pipeline method for consistency
-            const stepResult = await this.responsePipeline.determineNextStep({
-                selectedFlow: routingResult.selectedFlow,
-                selectedStep: routingResult.selectedStep,
-                session: updatedSession, // Use updated session with pre-extracted data
-                isFlowComplete, // Use updated completion status
-            });
-            return {
-                selectedFlow: stepResult.flowChanged || routingResult.selectedFlow,
-                selectedStep: stepResult.nextStep, // Use the determined next step
-                responseDirectives: routingResult.responseDirectives,
-                session: stepResult.session,
-                // If a branch changed the flow, the original isFlowComplete no longer applies
-                isFlowComplete: stepResult.flowChanged ? false : isFlowComplete,
-            };
-        }
-        catch (error) {
-            throw ResponseGenerationError.fromError(error, 'routing_optimization', params);
-        }
-    }
-    /**
-     * Apply a signal's position directive (goTo, goToStep, complete, abort, reset).
-     * Discards routing result and uses the signal's position decision.
-     * @private
-     * @requirements 8.3
-     */
-    applySignalPositionDirective(signalResult, _params) {
-        const directive = signalResult.mergedDirective;
-        let session = signalResult.updatedSession;
-        const flows = this.agent.getFlows();
-        let selectedFlow;
-        let selectedStep;
-        let isFlowComplete = false;
-        // Apply data updates if present alongside position
-        if (directive.dataUpdate) {
-            session = mergeCollected(session, directive.dataUpdate);
-        }
-        if (directive.goTo) {
-            const flowTarget = typeof directive.goTo === 'string'
-                ? directive.goTo
-                : directive.goTo.flow ?? directive.goTo.step;
-            if (flowTarget) {
-                const targetFlow = flows.find(f => f.id === flowTarget || f.title === flowTarget);
-                if (targetFlow) {
-                    session = enterFlow(session, targetFlow.id, targetFlow.title);
-                    selectedFlow = targetFlow;
-                    if (typeof directive.goTo === 'object' && directive.goTo.step) {
-                        const targetStep = targetFlow.getStep(directive.goTo.step);
-                        if (targetStep) {
-                            session = enterStep(session, targetStep.id, targetStep.description);
-                            selectedStep = targetStep;
-                        }
-                    }
-                }
-                else {
-                    logger.warn(`[Signals] Pre-phase goTo target not found: "${flowTarget}". Falling back to no flow.`);
-                }
-            }
-        }
-        else if (directive.goToStep) {
-            const stepTarget = typeof directive.goToStep === 'string'
-                ? directive.goToStep
-                : directive.goToStep.step;
-            const flowTarget = typeof directive.goToStep === 'object'
-                ? directive.goToStep.flow
-                : undefined;
-            if (flowTarget) {
-                const targetFlow = flows.find(f => f.id === flowTarget || f.title === flowTarget);
-                if (targetFlow) {
-                    session = enterFlow(session, targetFlow.id, targetFlow.title);
-                    selectedFlow = targetFlow;
-                    const targetStep = targetFlow.getStep(stepTarget);
-                    if (targetStep) {
-                        session = enterStep(session, targetStep.id, targetStep.description);
-                        selectedStep = targetStep;
-                    }
-                }
-            }
-            else if (session.currentFlow) {
-                const currentFlow = flows.find(f => f.id === session.currentFlow?.id);
-                if (currentFlow) {
-                    selectedFlow = currentFlow;
-                    const targetStep = currentFlow.getStep(stepTarget);
-                    if (targetStep) {
-                        session = enterStep(session, targetStep.id, targetStep.description);
-                        selectedStep = targetStep;
-                    }
-                }
-            }
-        }
-        else if (directive.complete) {
-            isFlowComplete = true;
-        }
-        else if (directive.abort) {
-            // Abort — no flow, session cleared or marked
-            isFlowComplete = true;
-        }
-        else if (directive.reset) {
-            if (session.currentFlow) {
-                const currentFlow = flows.find(f => f.id === session.currentFlow?.id);
-                if (currentFlow) {
-                    selectedFlow = currentFlow;
-                    const resetStep = typeof directive.reset === 'object' && directive.reset.step
-                        ? directive.reset.step
-                        : undefined;
-                    if (resetStep) {
-                        const targetStep = currentFlow.getStep(resetStep);
-                        if (targetStep) {
-                            session = enterStep(session, targetStep.id, targetStep.description);
-                            selectedStep = targetStep;
-                        }
-                    }
-                    else {
-                        const initialStep = currentFlow.initialStep;
-                        session = enterStep(session, initialStep.id, initialStep.description);
-                        selectedStep = initialStep;
-                    }
-                }
-            }
-        }
-        return {
-            selectedFlow,
-            selectedStep,
-            session,
-            isFlowComplete,
-            signalFirings: signalResult.firings,
-            signalPreDirective: signalResult.mergedDirective || undefined,
-        };
-    }
-    /**
-     * Routing skip optimization (Requirements 20.1, 20.2, 20.3):
-     * When the current step declares `collect` fields AND pre-extraction populates
-     * at least one of those fields from the user's message, skip routing for this turn.
-     *
-     * Returns the routing result if the skip applies, or undefined to fall through
-     * to normal routing.
-     * @private
-     */
-    async attemptRoutingSkipForCollect(params) {
-        const { session } = params;
-        // Only applies when we already have a current flow and step
-        if (!session.currentFlow || !session.currentStep) {
-            return undefined;
-        }
-        // Also skip this optimization if there's a pending directive (it takes priority)
-        if (session.pendingDirective) {
-            return undefined;
-        }
-        // Look up the actual Flow and Step objects to access `collect`
-        const currentFlow = this.agent.getFlows().find((f) => f.id === session.currentFlow?.id);
-        if (!currentFlow) {
-            return undefined;
-        }
-        const currentStep = currentFlow.getStep(session.currentStep.id);
-        if (!currentStep || !currentStep.collect || currentStep.collect.length === 0) {
-            return undefined;
-        }
-        // We have a step with collect fields. Run pre-extraction to see if the
-        // user's message populates any of them.
-        const collectFields = currentStep.collect;
-        // Snapshot current data for comparison
-        const dataBefore = { ...session.data };
-        // Run pre-extraction against the current flow
-        const extractedData = await this.preExtractFlowData({
-            route: currentFlow,
-            history: params.history,
-            context: params.context,
-            session,
-            signal: params.signal,
-        });
-        if (!extractedData || Object.keys(extractedData).length === 0) {
-            return undefined;
-        }
-        // Determine which collect fields were newly populated by pre-extraction
-        const populatedCollectFields = [];
-        for (const field of collectFields) {
-            const key = field;
-            const hadValue = dataBefore[field] !== undefined && dataBefore[field] !== null;
-            const hasNewValue = extractedData[field] !== undefined && extractedData[field] !== null;
-            if (hasNewValue && !hadValue) {
-                populatedCollectFields.push(key);
-            }
-        }
-        if (populatedCollectFields.length === 0) {
-            // Pre-extraction didn't populate any declared collect field — no skip
-            return undefined;
-        }
-        // ROUTING SKIP: pre-extraction populated collect fields → retain current flow/step
-        logger.debug(`[ResponseModal] Routing skip: pre-extraction populated collect fields [${populatedCollectFields.join(', ')}] for step "${currentStep.id}" — skipping FlowRouter`);
-        // Merge extracted data into session
-        const updatedSession = mergeCollected(session, extractedData);
-        await this.agent.updateCollectedData(extractedData);
-        // Determine next step using pipeline method for consistency
-        // Pass the current flow/step as the routing result (retained)
-        const stepResult = await this.responsePipeline.determineNextStep({
-            selectedFlow: currentFlow,
-            selectedStep: currentStep,
-            session: updatedSession,
-            isFlowComplete: false,
-        });
-        return {
-            selectedFlow: stepResult.flowChanged || currentFlow,
-            selectedStep: stepResult.nextStep,
-            responseDirectives: undefined,
-            session: stepResult.session,
-            isFlowComplete: stepResult.flowChanged ? false : false,
-        };
-    }
-    /**
-     * Check if a flow should pre-extract data before determining the initial step
-     * @private
-     */
-    shouldPreExtractData(flow) {
-        // Pre-extract if flow has declared required or optional fields
-        if (flow.requiredFields && flow.requiredFields.length > 0) {
-            return true;
-        }
-        if (flow.optionalFields && flow.optionalFields.length > 0) {
-            return true;
-        }
-        // Pre-extract if any step in the flow collects data
-        const steps = flow.getAllSteps();
-        const hasDataCollectionSteps = steps.some(step => step.collect && step.collect.length > 0);
-        return hasDataCollectionSteps;
-    }
-    /**
-     * Pre-extract data from user message when entering a flow
-     * This allows skipping steps whose data is already provided
-     * @private
-     */
-    async preExtractFlowData(params) {
-        const { route: flow, history, signal } = params;
-        // Build a schema for data extraction based on flow's fields
-        const extractionSchema = this.agent.schema;
-        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 (flow.requiredFields) {
-            extractionPrompt.push(`Required fields: ${flow.requiredFields.join(', ')}`);
-        }
-        if (flow.optionalFields) {
-            extractionPrompt.push(`Optional fields: ${flow.optionalFields.join(', ')}`);
-        }
-        extractionPrompt.push(``, `Return ONLY the extracted data as JSON. If no data can be extracted, return an empty object {}.`);
-        // Convert Event[] to HistoryItem[] for provider call
-        const historyItems = eventsToHistory(history);
-        // Call AI to extract data
-        const agentOptions = this.agent.getAgentOptions();
-        try {
-            const result = await agentOptions.provider.generateMessage({
-                prompt: extractionPrompt.join('\n'),
-                history: historyItems,
-                context: {}, // Passed as empty object so AI doesn't "extract" from context
-                // NOTE: context is intentionally NOT passed here.
-                // Passing context caused the AI to "extract" data from the lead's context
-                // (e.g., name, sector, city) instead of from what the user actually said.
-                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
@@ -785,15 +351,12 @@ export class ResponseModal {
         if (signalHalted) {
             const haltMessage = signalHaltReply || '';
             // Run post-signal phase even on halt (post-phase sees complete turn context)
-            const postResult = await this.responsePipeline.runPostSignalPhase(session, effectiveContext, historyEvents);
-            session = postResult.updatedSession;
-            signalFirings.push(...postResult.firings);
-            // Apply post-phase position directive as pendingDirective (Requirement 9.3)
-            if (postResult.mergedDirective && hasDirectivePositionField(postResult.mergedDirective)) {
-                session = { ...session, pendingDirective: postResult.mergedDirective };
-            }
-            const message = this.applyPostSignalReply(haltMessage, postResult.mergedDirective);
-            await this.finalizeSession(session, effectiveContext);
+            const post = await this.signalCoordinator.applyPostPhase({
+                session, context: effectiveContext, historyEvents, message: haltMessage,
+            });
+            session = post.session;
+            signalFirings.push(...post.firings);
+            const message = post.message;
             return {
                 message,
                 session,
@@ -827,12 +390,12 @@ export class ResponseModal {
                     flow: selectedFlow,
                 });
                 session = autoResult.session;
-                // Handle halt: emit verbatim reply, persist, return — no LLM call.
+                // Handle halt: emit verbatim reply, return — no LLM call.
+                // respond() finalizes the returned session exactly once.
                 if (autoResult.stoppedReason === 'halt') {
                     message = autoResult.mergedDirective?.reply || '';
                     stoppedReason = 'halt';
                     executedSteps = [];
-                    await this.finalizeSession(session, effectiveContext);
                     return {
                         message,
                         session,
@@ -854,7 +417,6 @@ export class ResponseModal {
                         context: effectiveContext,
                         history,
                     });
-                    await this.finalizeSession(session, effectiveContext);
                     return {
                         message: '',
                         session,
@@ -934,17 +496,13 @@ export class ResponseModal {
         // Runs after finalize/onComplete and before session persistence.
         // Post-phase signals see the complete turn result: assistant message in
         // history, collected data, tool results.
-        const postResult = await this.responsePipeline.runPostSignalPhase(session, effectiveContext, historyEvents);
-        session = postResult.updatedSession;
+        const post = await this.signalCoordinator.applyPostPhase({
+            session, context: effectiveContext, historyEvents, message,
+        });
+        session = post.session;
         // Append post-phase firings to the accumulator (preserves fire order)
-        signalFirings.push(...postResult.firings);
-        // Requirement 9.3: Post-phase position directive sets session.pendingDirective
-        // (no mid-turn re-entry per D6 decision). Pre-LLM-only fields are already
-        // dropped inside runPostSignalPhase per Phase 4.5.
-        if (postResult.mergedDirective && hasDirectivePositionField(postResult.mergedDirective)) {
-            session = { ...session, pendingDirective: postResult.mergedDirective };
-        }
-        message = this.applyPostSignalReply(message, postResult.mergedDirective);
+        signalFirings.push(...post.firings);
+        message = post.message;
         // 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)
@@ -960,43 +518,6 @@ export class ResponseModal {
             triggeredSignals: signalFirings.length > 0 ? signalFirings : undefined,
         };
     }
-    /**
-       * Execute prepare function for current step if available
-       * @private
-       */
-    async executeStepPrepare(session, context) {
-        if (session.currentFlow && session.currentStep) {
-            const currentFlow = this.agent.getFlows().find((r) => r.id === session.currentFlow?.id);
-            if (currentFlow) {
-                const currentStep = currentFlow.getStep(session.currentStep.id);
-                // Skip auto-steps — their prepare is handled by AutoChainExecutor
-                if (currentStep?.auto) {
-                    logger.debug(`[ResponseModal] Skipping pre-routing prepare for auto-step: ${currentStep.id}`);
-                    return;
-                }
-                if (currentStep?.prepare) {
-                    logger.debug(`[ResponseModal] Executing prepare for step: ${currentStep.id}`);
-                    await this.executePrepareFinalize(currentStep.prepare, context, session.data, currentFlow, currentStep);
-                }
-            }
-        }
-    }
-    /**
-     * Execute finalize function for current step if available
-     * @private
-     */
-    async executeStepFinalize(session, context) {
-        if (session.currentFlow && session.currentStep) {
-            const currentFlow = this.agent.getFlows().find((r) => r.id === session.currentFlow?.id);
-            if (currentFlow) {
-                const currentStep = currentFlow.getStep(session.currentStep.id);
-                if (currentStep?.finalize) {
-                    logger.debug(`[ResponseModal] Executing finalize for step: ${currentStep.id}`);
-                    await this.executePrepareFinalize(currentStep.finalize, context, session.data, currentFlow, currentStep);
-                }
-            }
-        }
-    }
     /**
      * Process flow response with unified tool execution and data collection
      * @private
@@ -1004,79 +525,20 @@ export class ResponseModal {
     async processFlowResponse(params) {
         const { selectedFlow, selectedStep, responseDirectives, history, context, historyEvents, signal, transientAppendage, mergedPreDirective } = params;
         let session = params.session;
-        // Determine next step
-        let nextStep;
-        if (selectedStep) {
-            nextStep = selectedStep;
-        }
-        else {
-            // Determine current step from session if we're already in this flow
-            const isInSameFlow = session.currentFlow?.id === selectedFlow.id;
-            const currentStep = isInSameFlow && session.currentStep
-                ? selectedFlow.getStep(session.currentStep.id)
-                : undefined;
-            logger.debug(`[ResponseModal] Step determination: flow match=${isInSameFlow}, currentFlow=${session.currentFlow?.id}, selectedFlow=${selectedFlow.id}, currentStep=${currentStep?.id || 'none'}`);
-            // STEP 1 (Algorithm 1): branches win over linear chain
-            if (currentStep?.branches && currentStep.branches.length > 0) {
-                const branchResult = await this.responsePipeline.evaluateStepBranches(currentStep, selectedFlow, session, context);
-                if (branchResult) {
-                    if (branchResult.nextStep) {
-                        nextStep = branchResult.nextStep;
-                        session = branchResult.session;
-                    }
-                    else {
-                        // Flow transition or completion — no local step to render
-                        // Return empty message with updated session; caller handles flow transition
-                        return { message: '', session: branchResult.session };
-                    }
-                }
-            }
-            if (!nextStep) {
-                // Get candidate steps based on current position in the flow
-                const flowRouter = this.agent.getFlowRouter();
-                const candidates = await flowRouter.getCandidateStepsWithConditions(selectedFlow, 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 flow entry)'}`);
-                if (candidates.length > 0) {
-                    nextStep = candidates[0].step;
-                    logger.debug(`[ResponseModal] Using first valid step: ${nextStep.id}${currentStep ? ' (progressing from ' + currentStep.id + ')' : ' for new flow'}`);
-                }
-                else {
-                    // Fallback to initial step even if it should be skipped
-                    nextStep = selectedFlow.initialStep;
-                    logger.warn(`[FlowConfigurationError] No valid steps found: all candidates were skipped in flow. Falling back to initial step "${nextStep.id}". Review step skip conditions.`);
-                }
-            }
-        }
-        // Update session with next step
-        // If the next step has requires fields that are missing, stay at the previous step
-        if (nextStep.requires && nextStep.requires.length > 0) {
-            const sessionData = session.data || {};
-            const missingRequires = nextStep.requires.filter(field => sessionData[String(field)] === undefined);
-            if (missingRequires.length > 0) {
-                const warning = `[FlowConfigurationError] Cannot advance to step "${nextStep.description || nextStep.id}": ` +
-                    `missing required fields [${missingRequires.join(', ')}]. Staying at current step. Ensure preceding steps collect these fields.`;
-                logger.warn(warning);
-                console.warn(warning);
-                // Stay at the current step - don't enter the next one
-                const currentStepId = session.currentStep?.id;
-                if (currentStepId) {
-                    const currentStepInstance = selectedFlow.getStep(currentStepId);
-                    if (currentStepInstance) {
-                        nextStep = currentStepInstance;
-                        logger.debug(`[ResponseModal] Staying at current step: ${nextStep.id} due to missing requires`);
-                    }
-                }
-            }
-            else {
-                session = enterStep(session, nextStep.id, nextStep.description);
-                logger.debug(`[ResponseModal] Entered step: ${nextStep.id}`);
-            }
-        }
-        else {
-            session = enterStep(session, nextStep.id, nextStep.description);
-            logger.debug(`[ResponseModal] Entered step: ${nextStep.id}`);
+        // Resolve the step to render (branches win over linear chain; requires enforced)
+        const stepResolution = await this.responsePipeline.resolveRenderStep({
+            selectedFlow,
+            selectedStep,
+            session,
+            context,
+        });
+        if (stepResolution.flowTransition) {
+            // Flow transition or completion — no local step to render
+            // Return empty message with updated session; caller handles flow transition
+            return { message: '', session: stepResolution.session };
         }
+        const nextStep = stepResolution.nextStep;
+        session = stepResolution.session;
         // Build response schema for this flow (with collect fields from step)
         const responseSchema = this.responseEngine.responseSchemaForFlow(selectedFlow, nextStep, this.agent.schema);
         // ── HALT SHORT-CIRCUIT (Requirement 2.5, 2.6, 2.7) ──────────────────────
@@ -1149,7 +611,7 @@ export class ResponseModal {
                 toolNames: toolCalls?.map(tc => tc.toolName) || [],
             });
             // Execute tools with unified loop handling
-            const toolResult = await this.executeUnifiedToolLoop({
+            const toolResult = await this.toolLoopExecutor.runLoop({
                 toolCalls,
                 context,
                 session,
@@ -1195,14 +657,13 @@ export class ResponseModal {
         if (signalHalted) {
             const haltMessage = signalHaltReply || '';
             // Run post-signal phase even on halt
-            const postResult = await this.responsePipeline.runPostSignalPhase(session, effectiveContext, historyEvents);
-            session = postResult.updatedSession;
-            signalFirings.push(...postResult.firings);
-            if (postResult.mergedDirective && hasDirectivePositionField(postResult.mergedDirective)) {
-                session = { ...session, pendingDirective: postResult.mergedDirective };
-            }
-            const message = this.applyPostSignalReply(haltMessage, postResult.mergedDirective);
-            await this.finalizeSession(session, effectiveContext);
+            const post = await this.signalCoordinator.applyPostPhase({
+                session, context: effectiveContext, historyEvents, message: haltMessage,
+            });
+            session = post.session;
+            signalFirings.push(...post.firings);
+            const message = post.message;
+            await this.sessionFinalizer.finalize(session, effectiveContext);
             yield {
                 delta: message,
                 accumulated: message,
@@ -1235,7 +696,7 @@ export class ResponseModal {
                 // Handle halt: emit verbatim reply as a single chunk, done.
                 if (autoResult.stoppedReason === 'halt') {
                     const reply = autoResult.mergedDirective?.reply || '';
-                    await this.finalizeSession(session, effectiveContext);
+                    await this.sessionFinalizer.finalize(session, effectiveContext);
                     yield {
                         delta: reply,
                         accumulated: reply,
@@ -1312,24 +773,26 @@ export class ResponseModal {
                 session,
             });
         }
-        // ── Intercept the inner stream to run post-signal phase on the final chunk ──
-        // This mirrors the non-streaming path: post-phase runs after finalize/onComplete
-        // and before session persistence, attaching triggeredSignals to the final chunk
-        // (Requirement 11.2).
+        // ── Intercept the inner stream on the final chunk ──────────────────────
+        // Mirrors the non-streaming path: post-signal phase runs first, then the
+        // session (including post-phase mutations) is finalized exactly once,
+        // attaching triggeredSignals to the final chunk (Requirement 11.2).
         for await (const chunk of innerStream) {
             if (chunk.done) {
                 // Run post-signal phase on final chunk (Requirement 9.1, 9.2)
-                const postResult = await this.responsePipeline.runPostSignalPhase(chunk.session || session, effectiveContext, historyEvents);
-                let finalSession = postResult.updatedSession;
-                signalFirings.push(...postResult.firings);
-                // Requirement 9.3: Post-phase position directive sets session.pendingDirective
-                if (postResult.mergedDirective && hasDirectivePositionField(postResult.mergedDirective)) {
-                    finalSession = { ...finalSession, pendingDirective: postResult.mergedDirective };
-                }
-                const accumulated = this.applyPostSignalReply(chunk.accumulated, postResult.mergedDirective);
-                const delta = postResult.mergedDirective?.reply !== undefined
-                    ? accumulated
-                    : chunk.delta;
+                const post = await this.signalCoordinator.applyPostPhase({
+                    session: chunk.session || session,
+                    context: effectiveContext,
+                    historyEvents,
+                    message: chunk.accumulated,
+                });
+                const finalSession = post.session;
+                signalFirings.push(...post.firings);
+                const accumulated = post.message;
+                const delta = post.replyOverridden ? accumulated : chunk.delta;
+                // Single streaming exit: finalize the post-phase session so
+                // post-signal mutations (e.g. pendingDirective) are persisted
+                await this.sessionFinalizer.finalize(finalSession, effectiveContext);
                 yield {
                     ...chunk,
                     delta,
@@ -1350,80 +813,25 @@ export class ResponseModal {
     async *processFlowStreamingResponse(params) {
         const { selectedFlow, selectedStep, responseDirectives, history, context, historyEvents, signal, transientAppendage, mergedPreDirective } = params;
         let session = params.session;
-        // Determine next step (same logic as non-streaming)
-        let nextStep;
-        if (selectedStep) {
-            nextStep = selectedStep;
-        }
-        else {
-            // Determine current step from session if we're already in this flow
-            const currentStep = session.currentFlow?.id === selectedFlow.id && session.currentStep
-                ? selectedFlow.getStep(session.currentStep.id)
-                : undefined;
-            // STEP 1 (Algorithm 1): branches win over linear chain
-            if (currentStep?.branches && currentStep.branches.length > 0) {
-                const branchResult = await this.responsePipeline.evaluateStepBranches(currentStep, selectedFlow, session, context);
-                if (branchResult) {
-                    // Branch resolved — yield a final chunk with the updated session and return
-                    if (branchResult.nextStep) {
-                        session = branchResult.session;
-                        nextStep = branchResult.nextStep;
-                    }
-                    else {
-                        // Flow transition or completion — no step to render
-                        yield {
-                            delta: '',
-                            accumulated: '',
-                            done: true,
-                            session: branchResult.session,
-                        };
-                        return;
-                    }
-                }
-            }
-            if (!nextStep) {
-                // Get candidate steps based on current position in the flow
-                const flowRouter = this.agent.getFlowRouter();
-                const candidates = await flowRouter.getCandidateStepsWithConditions(selectedFlow, 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}${currentStep ? ' (progressing from ' + currentStep.id + ')' : ' for new flow'}`);
-                }
-                else {
-                    nextStep = selectedFlow.initialStep;
-                    logger.warn(`[FlowConfigurationError] No valid steps found: all candidates were skipped in flow. Falling back to initial step "${nextStep.id}". Review step skip conditions.`);
-                }
-            }
-        }
-        // Update session with next step
-        // If the next step has requires fields that are missing, stay at the previous step
-        if (nextStep.requires && nextStep.requires.length > 0) {
-            const sessionData = session.data || {};
-            const missingRequires = nextStep.requires.filter(field => sessionData[String(field)] === undefined);
-            if (missingRequires.length > 0) {
-                const warning = `[FlowConfigurationError] Cannot advance to step "${nextStep.description || nextStep.id}": ` +
-                    `missing required fields [${missingRequires.join(', ')}]. Staying at current step. Ensure preceding steps collect these fields.`;
-                logger.warn(warning);
-                console.warn(warning);
-                const currentStepId = session.currentStep?.id;
-                if (currentStepId) {
-                    const currentStepInstance = selectedFlow.getStep(currentStepId);
-                    if (currentStepInstance) {
-                        nextStep = currentStepInstance;
-                        logger.debug(`[ResponseModal] Staying at current step: ${nextStep.id} due to missing requires`);
-                    }
-                }
-            }
-            else {
-                session = enterStep(session, nextStep.id, nextStep.description);
-                logger.debug(`[ResponseModal] Entered step: ${nextStep.id}`);
-            }
-        }
-        else {
-            session = enterStep(session, nextStep.id, nextStep.description);
-            logger.debug(`[ResponseModal] Entered step: ${nextStep.id}`);
+        // Resolve the step to render (same logic as non-streaming)
+        const stepResolution = await this.responsePipeline.resolveRenderStep({
+            selectedFlow,
+            selectedStep,
+            session,
+            context,
+        });
+        if (stepResolution.flowTransition) {
+            // Flow transition or completion — no step to render
+            yield {
+                delta: '',
+                accumulated: '',
+                done: true,
+                session: stepResolution.session,
+            };
+            return;
         }
+        const nextStep = stepResolution.nextStep;
+        session = stepResolution.session;
         // Build response schema and prompt (same as non-streaming)
         const responseSchema = this.responseEngine.responseSchemaForFlow(selectedFlow, nextStep, this.agent.schema);
         // ── HALT SHORT-CIRCUIT (Requirement 2.5, 2.6, 2.7) ──────────────────────
@@ -1433,7 +841,6 @@ export class ResponseModal {
             const reply = mergedPreDirective.reply || '';
             const reason = mergedPreDirective.reply ? 'reply' : 'halt';
             logger.debug(`[ResponseModal] Halt (streaming) — skipping LLM call for step ${nextStep.id}, stoppedReason: ${reason}`);
-            await this.finalizeSession(session, context);
             yield {
                 delta: reply,
                 accumulated: reply,
@@ -1451,7 +858,6 @@ export class ResponseModal {
         if (nextStep.reply != null) {
             const effectiveReply = mergedPreDirective?.reply ?? await render(nextStep.reply, createTemplateContext({ data: session.data || {}, context, session }));
             logger.debug(`[ResponseModal] Step.reply (streaming) — skipping LLM call for step ${nextStep.id}`);
-            await this.finalizeSession(session, context);
             yield {
                 delta: effectiveReply,
                 accumulated: effectiveReply,
@@ -1500,70 +906,23 @@ export class ResponseModal {
                 // Extract tool calls from AI response on final chunk
                 if (chunk.done && chunk.structured?.toolCalls) {
                     toolCalls = chunk.structured.toolCalls;
-                    const toolManager = this.getToolManager();
-                    // Use concurrent execution for the initial batch of tool calls
-                    {
-                        const toolCallRequests = toolCalls.map((tc, i) => ({
-                            id: `${tc.toolName}-${i}-${Date.now()}`,
-                            toolName: tc.toolName,
-                            arguments: tc.arguments,
-                        }));
-                        const historyEvents = historyToEvents(history);
-                        try {
-                            for await (const update of toolManager.executeWithConcurrency({
-                                toolCalls: toolCallRequests,
-                                context,
-                                data: session.data,
-                                history: historyEvents,
-                                signal,
-                                flow: selectedFlow,
-                                step: nextStep,
-                            })) {
-                                // Apply context updates
-                                if (update.contextUpdate) {
-                                    try {
-                                        await this.agent.updateContext(update.contextUpdate);
-                                    }
-                                    catch (error) {
-                                        logger.error(`[ResponseModal] Failed to update context from concurrent tool:`, error);
-                                    }
-                                }
-                                // Apply data updates
-                                if (update.dataUpdate) {
-                                    try {
-                                        const updateDataMethod = this.agent.getUpdateDataMethod();
-                                        session = await updateDataMethod(session, update.dataUpdate);
-                                    }
-                                    catch (error) {
-                                        logger.error(`[ResponseModal] Failed to update data from concurrent tool:`, error);
-                                    }
-                                }
-                                // Yield progress updates immediately
-                                if (update.progress) {
-                                    yield {
-                                        delta: '',
-                                        accumulated: chunk.accumulated,
-                                        done: false,
-                                        session,
-                                        toolCalls: undefined,
-                                        isFlowComplete: false,
-                                        metadata: { toolProgress: update.progress, toolCallId: update.toolCallId },
-                                    };
-                                }
-                            }
-                            logger.debug(`[ResponseModal] Concurrent tool execution completed for ${toolCallRequests.length} tools`);
-                        }
-                        catch (error) {
-                            logger.error(`[ResponseModal] Concurrent tool execution failed, falling back to sequential:`, error);
-                            // Fall back to the unified tool loop on failure
-                            const toolResult = await this.executeUnifiedToolLoop({
-                                toolCalls, context, session, history, selectedFlow,
-                                responsePrompt, availableTools, responseSchema, signal,
-                            });
-                            session = toolResult.session;
-                            toolCalls = toolResult.finalToolCalls;
-                        }
-                    }
+                    // Concurrent execution for the initial batch of tool calls,
+                    // yielding tool-progress chunks as they arrive
+                    const batchResult = yield* this.toolLoopExecutor.runStreamingBatch({
+                        toolCalls,
+                        context,
+                        session,
+                        history,
+                        selectedFlow,
+                        step: nextStep,
+                        accumulated: chunk.accumulated,
+                        responsePrompt,
+                        availableTools,
+                        responseSchema,
+                        signal,
+                    });
+                    session = batchResult.session;
+                    toolCalls = batchResult.toolCalls;
                 }
                 // Extract collected data on final chunk
                 if (chunk.done && chunk.structured && nextStep.collect) {
@@ -1574,10 +933,6 @@ export class ResponseModal {
                         session,
                     });
                 }
-                // Handle session finalization on final chunk
-                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)
@@ -1605,293 +960,6 @@ export class ResponseModal {
         }
     }
     /**
-     * Unified tool execution logic with loop handling
-     * Consolidates the complex tool execution logic from both streaming and non-streaming responses
-     * @private
-     */
-    async executeUnifiedToolLoop(params) {
-        try {
-            const { context, history, selectedFlow, responsePrompt, availableTools, responseSchema, signal } = params;
-            let { toolCalls, session } = params;
-            // Convert HistoryItem[] to Event[] for internal processing
-            const historyEvents = historyToEvents(history);
-            // Map to store tool execution results for history
-            const toolResultsMap = new Map();
-            // Map to store tool call arguments for history reconstruction
-            const toolArgsMap = new Map();
-            // Execute initial dynamic tool calls
-            if (toolCalls && toolCalls.length > 0) {
-                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, selectedFlow);
-                    if (!tool) {
-                        logger.warn(`[ToolExecutionError] Tool not found: "${toolCall.toolName}" is not registered in any scope. Skipping this tool call. Register the tool or check the tool name.`);
-                        continue;
-                    }
-                    try {
-                        // Use ToolManager for unified tool execution
-                        const toolManager = this.getToolManager();
-                        const toolResult = await toolManager.executeTool({
-                            tool: tool,
-                            context,
-                            updateContext: this.agent.updateContext.bind(this.agent),
-                            updateData: this.agent.updateCollectedData.bind(this.agent),
-                            history: historyEvents, // Use Event[] for tool execution
-                            data: session.data,
-                            toolArguments: toolCall.arguments,
-                        });
-                        // Store the actual tool result data for history
-                        toolResultsMap.set(toolCall.toolName, serializeToolResult(toolResult));
-                        toolArgsMap.set(toolCall.toolName, toolCall.arguments);
-                        // Check if tool execution was successful
-                        if (!toolResult.success) {
-                            logger.error(`[ResponseModal] Tool execution failed: ${toolCall.toolName} - ${toolResult.error}`);
-                            // Continue with other tools rather than failing completely
-                            continue;
-                        }
-                        // Update context with tool results
-                        if (toolResult.contextUpdate) {
-                            try {
-                                await this.agent.updateContext(toolResult.contextUpdate);
-                            }
-                            catch (error) {
-                                logger.error(`[ResponseModal] Failed to update context from tool ${toolCall.toolName}:`, error);
-                                // Continue execution but log the error
-                            }
-                        }
-                        // Update collected data with tool results
-                        if (toolResult.dataUpdate) {
-                            try {
-                                const updateDataMethod = this.agent.getUpdateDataMethod();
-                                session = await updateDataMethod(session, toolResult.dataUpdate);
-                                logger.debug(`[ResponseModal] Tool updated collected data:`, toolResult.dataUpdate);
-                            }
-                            catch (error) {
-                                logger.error(`[ResponseModal] Failed to update data from tool ${toolCall.toolName}:`, error);
-                                // Continue execution but log the error
-                            }
-                        }
-                        logger.debug(`[ResponseModal] Executed dynamic tool: ${toolCall.toolName} (success: ${toolResult.success})`);
-                    }
-                    catch (error) {
-                        logger.error(`[ResponseModal] Tool execution error for ${toolCall.toolName}:`, error);
-                        // Continue with other tools rather than failing the entire response
-                        continue;
-                    }
-                }
-            }
-            // TOOL LOOP: Allow AI to make follow-up tool calls after initial tool execution
-            const MAX_TOOL_LOOPS = this.options?.maxToolLoops || 5;
-            let toolLoopCount = 0;
-            let hasToolCalls = toolCalls && toolCalls.length > 0;
-            let finalMessage;
-            let followUpStructured;
-            while (hasToolCalls && toolLoopCount < MAX_TOOL_LOOPS) {
-                toolLoopCount++;
-                logger.debug(`[ResponseModal] Starting tool loop ${toolLoopCount}/${MAX_TOOL_LOOPS} with ${toolCalls?.length || 0} tool calls`);
-                // Create tool result history items
-                const toolResultHistoryItems = [];
-                for (const toolCall of toolCalls || []) {
-                    const tool = this.findAvailableTool(toolCall.toolName, selectedFlow);
-                    if (tool) {
-                        // Create HistoryItem format for tool results
-                        // Add assistant message with tool_calls
-                        toolResultHistoryItems.push({
-                            role: "assistant",
-                            content: null,
-                            tool_calls: [{
-                                    id: toolCall.toolName,
-                                    name: toolCall.toolName,
-                                    arguments: toolCall.arguments,
-                                }],
-                        });
-                        // Add tool result
-                        toolResultHistoryItems.push({
-                            role: "tool",
-                            tool_call_id: toolCall.toolName,
-                            name: toolCall.toolName,
-                            content: toolResultsMap.get(toolCall.toolName) || "Tool executed successfully",
-                        });
-                    }
-                }
-                // Create updated history with tool results
-                const updatedHistory = [...history, ...toolResultHistoryItems];
-                // 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 + (toolLoopCount > 1 ? "\n\nProvide a text response to the user based on the tool results." : ""),
-                    history: updatedHistory, // Use HistoryItem[] for AI provider
-                    context,
-                    tools: shouldProvideTools ? availableTools : [], // Only provide tools on first iteration
-                    parameters: responseSchema ? {
-                        jsonSchema: responseSchema,
-                        schemaName: "tool_followup",
-                    } : undefined,
-                    signal,
-                });
-                // Check if follow-up call has more tool calls
-                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`);
-                    // Execute the follow-up tool calls
-                    for (const toolCall of followUpToolCalls) {
-                        const tool = this.findAvailableTool(toolCall.toolName, selectedFlow);
-                        if (!tool) {
-                            logger.warn(`[ToolExecutionError] Tool not found in follow-up: "${toolCall.toolName}" is not registered in any scope. Skipping this tool call. Register the tool or check the tool name.`);
-                            continue;
-                        }
-                        try {
-                            // Use ToolManager for unified tool execution
-                            const toolManager = this.getToolManager();
-                            const toolResult = await toolManager.executeTool({
-                                tool: tool,
-                                context,
-                                updateContext: this.agent.updateContext.bind(this.agent),
-                                updateData: this.agent.updateCollectedData.bind(this.agent),
-                                history: historyToEvents(updatedHistory), // Convert to Event[] for tool execution
-                                data: session.data,
-                                toolArguments: toolCall.arguments,
-                            });
-                            // Check if tool execution was successful
-                            if (!toolResult.success) {
-                                logger.error(`[ResponseModal] Follow-up tool execution failed: ${toolCall.toolName} - ${toolResult.error}`);
-                                continue;
-                            }
-                            // Update context with follow-up tool results
-                            if (toolResult.contextUpdate) {
-                                try {
-                                    await this.agent.updateContext(toolResult.contextUpdate);
-                                }
-                                catch (error) {
-                                    logger.error(`[ResponseModal] Failed to update context from follow-up tool ${toolCall.toolName}:`, error);
-                                }
-                            }
-                            if (toolResult.dataUpdate) {
-                                try {
-                                    const updateDataMethod = this.agent.getUpdateDataMethod();
-                                    session = await updateDataMethod(session, toolResult.dataUpdate);
-                                    logger.debug(`[ResponseModal] Follow-up tool updated collected data:`, toolResult.dataUpdate);
-                                }
-                                catch (error) {
-                                    logger.error(`[ResponseModal] Failed to update data from follow-up tool ${toolCall.toolName}:`, error);
-                                }
-                            }
-                            // Store the follow-up tool result for potential next loop iteration
-                            toolResultsMap.set(toolCall.toolName, serializeToolResult(toolResult));
-                            toolArgsMap.set(toolCall.toolName, toolCall.arguments);
-                            logger.debug(`[ResponseModal] Executed follow-up tool: ${toolCall.toolName} (success: ${toolResult.success})`);
-                        }
-                        catch (error) {
-                            logger.error(`[ResponseModal] Follow-up tool execution error for ${toolCall.toolName}:`, error);
-                            continue;
-                        }
-                    }
-                    // Update toolCalls for next iteration or final response
-                    toolCalls = followUpToolCalls;
-                }
-                else {
-                    logger.debug(`[ResponseModal] Tool loop completed after ${toolLoopCount} iterations`);
-                    // Update final message and toolCalls from follow-up result if no more tools
-                    finalMessage = followUpResult.structured?.message || followUpResult.message;
-                    followUpStructured = followUpResult.structured;
-                    toolCalls = followUpToolCalls || [];
-                    break;
-                }
-            }
-            if (toolLoopCount >= MAX_TOOL_LOOPS) {
-                logger.warn(`[ResponseGenerationError] Tool loop limit reached: ${toolLoopCount} iterations hit the cap (${MAX_TOOL_LOOPS}). Stopping tool execution. Increase MAX_TOOL_LOOPS or reduce recursive tool calls.`);
-            }
-            // If tools were executed but no final text message was produced,
-            // make one more LLM call to generate a proper text response from tool results.
-            // This prevents the original tool-invocation message (e.g. "Let me check...")
-            // from being returned as the final user-facing response.
-            if (!finalMessage && toolLoopCount > 0) {
-                logger.debug(`[ResponseModal] No final message after tool loop, making additional LLM call for text response`);
-                // Build tool result history from toolResultsMap which contains ALL
-                // tool executions (initial + follow-up). We can't use `toolCalls` here
-                // because it was reassigned to the (empty) follow-up tool calls when
-                // the while loop broke out.
-                const finalToolResultHistoryItems = [];
-                for (const [toolName, toolResult] of toolResultsMap) {
-                    finalToolResultHistoryItems.push({
-                        role: "assistant",
-                        content: null,
-                        tool_calls: [{
-                                id: toolName,
-                                name: toolName,
-                                arguments: toolArgsMap.get(toolName) || {},
-                            }],
-                    });
-                    finalToolResultHistoryItems.push({
-                        role: "tool",
-                        tool_call_id: toolName,
-                        name: toolName,
-                        content: toolResult,
-                    });
-                }
-                const finalHistory = [...history, ...finalToolResultHistoryItems];
-                const agentOptions = this.agent.getAgentOptions();
-                try {
-                    const textResult = await agentOptions.provider.generateMessage({
-                        prompt: responsePrompt + "\n\nProvide a text response to the user based on the tool results. Do not call any tools.",
-                        history: finalHistory,
-                        context,
-                        tools: [], // No tools - force text response
-                        parameters: responseSchema ? {
-                            jsonSchema: responseSchema,
-                            schemaName: "tool_final_text",
-                        } : undefined,
-                        signal,
-                    });
-                    finalMessage = textResult.structured?.message || textResult.message;
-                    if (textResult.structured) {
-                        followUpStructured = textResult.structured;
-                    }
-                    logger.debug(`[ResponseModal] Generated final text response after tool loop:`, {
-                        hasMessage: !!finalMessage,
-                        messageLength: finalMessage?.length || 0,
-                    });
-                }
-                catch (error) {
-                    logger.error(`[ResponseModal] Failed to generate final text response after tool loop:`, error);
-                    // finalMessage remains undefined; caller will use original message as fallback
-                }
-            }
-            logger.debug(`[ResponseModal] Tool loop completed:`, {
-                totalIterations: toolLoopCount,
-                hasFinalMessage: !!finalMessage,
-                finalMessageLength: finalMessage?.length || 0,
-                finalToolCallsCount: toolCalls?.length || 0,
-            });
-            return {
-                session,
-                finalToolCalls: toolCalls,
-                finalMessage,
-                structured: followUpStructured,
-            };
-        }
-        catch (error) {
-            throw ResponseGenerationError.fromError(error, 'tool_execution', params, {
-                toolCallsCount: params.toolCalls?.length || 0,
-                availableToolsCount: params.availableTools.length
-            });
-        }
-    } /**
      * Unified data collection from AI response
      * @private
      */
@@ -2037,10 +1105,6 @@ export class ResponseModal {
         }
         return nextSession;
     }
-    /**
-     * Stream flow completion response
-     * @private
-     */
     /**
      * Stream a flow completion as a single terminal chunk.
      *
@@ -2062,7 +1126,6 @@ export class ResponseModal {
             context,
             history,
         });
-        await this.finalizeSession(session, context);
         yield {
             delta: '',
             accumulated: '',
@@ -2137,10 +1200,6 @@ export class ResponseModal {
             },
         });
         for await (const chunk of stream) {
-            // Update current session if we have one
-            if (chunk.done) {
-                await this.finalizeSession(session, context);
-            }
             // Response structure completeness (Requirement 8.1, 8.2, 8.3)
             // - executedSteps: empty for fallback (no flow/step execution)
             // - stoppedReason: undefined for fallback (no flow context)
@@ -2160,39 +1219,9 @@ export class ResponseModal {
             };
         }
     }
-    /**
-     * Handle session persistence and finalization
-     * @private
-     */
-    async finalizeSession(session, context) {
-        // Auto-save session step to persistence if configured
-        const persistenceManager = this.agent.getPersistenceManager();
-        const agentOptions = this.agent.getAgentOptions();
-        if (persistenceManager &&
-            session.id &&
-            (this.options?.enableAutoSave !== false && agentOptions.persistence?.autoSave !== false)) {
-            await persistenceManager.saveSessionState(session.id, session);
-            logger.debug(`[ResponseModal] Auto-saved session step to persistence: ${session.id}`);
-        }
-        // Execute finalize function
-        await this.executeStepFinalize(session, context);
-        // Update current session if we have one
-        const currentSession = this.agent.currentSession;
-        if (currentSession) {
-            this.agent.currentSession = session;
-        }
-    }
     // ============================================================================
     // UTILITY METHODS - Helper methods for tool management and other utilities
     // ============================================================================
-    /**
-     * Find an available tool by name for the given flow.
-     * Delegates to ToolManager for unified tool resolution.
-     * @private
-     */
-    findAvailableTool(toolName, flow) {
-        return this.getToolManager().find(toolName, undefined, undefined, flow);
-    }
     /**
      * Collect all available tools for the given flow and step context.
      * Delegates to ToolManager for unified tool resolution and deduplication.
@@ -2207,49 +1236,5 @@ export class ResponseModal {
             parameters: tool.parameters,
         }));
     }
-    /**
-     * Execute a prepare or finalize function/tool
-     * @private
-     */
-    async executePrepareFinalize(prepareOrFinalize, context, data, flow, step) {
-        if (!prepareOrFinalize)
-            return;
-        if (typeof prepareOrFinalize === "function") {
-            // It's a function - call it directly
-            await prepareOrFinalize(context, data);
-        }
-        else {
-            // It's a tool reference - find and execute the tool
-            let tool;
-            if (typeof prepareOrFinalize === "string") {
-                // Tool ID - use ToolManager for unified resolution
-                tool = this.getToolManager().find(prepareOrFinalize, undefined, step, flow);
-            }
-            else {
-                // Tool object - use directly
-                tool = prepareOrFinalize;
-            }
-            if (tool) {
-                // Use ToolManager for unified tool execution
-                const result = await this.getToolManager().executeTool({
-                    tool,
-                    context,
-                    updateContext: this.agent.updateContext.bind(this.agent),
-                    updateData: this.agent.updateCollectedData.bind(this.agent),
-                    history: [], // Empty history for prepare/finalize
-                    data,
-                });
-                if (!result.success) {
-                    logger.error(`[ResponseModal] Tool execution failed in prepare/finalize: ${result.error}`);
-                    throw new Error(`Tool execution failed: ${result.error}`);
-                }
-            }
-            else {
-                logger.warn(`[ResponseModal] Tool not found for prepare/finalize: ${typeof prepareOrFinalize === "string"
-                    ? prepareOrFinalize
-                    : "inline tool"}`);
-            }
-        }
-    }
 }
 //# sourceMappingURL=ResponseModal.js.map