@falai/agent 2.2.3 → 2.4.1

package/src/core/ResponsePipeline.ts

@@ -6,31 +6,28 @@ import type {
   AgentOptions,
   Event,
   SessionState,
-  AgentStructuredResponse,
-  Tool,
   Directive,
+  StructuredSchema,
 } from "../types";
 import type { SignalFiring } from "../types/signals";
-import type { SignalProcessor } from "./SignalProcessor";
-import type { HistoryItem } from "../types/history";
 import {
   createSession,
   enterStep,
   mergeCollected,
-  completeCurrentFlow,
   logger,
   historyToEvents,
-  serializeToolResult,
+  eventsToHistory,
+  getLastMessageFromHistory,
 } from "../utils";
 import { enterFlow } from "../utils/session";
 import { createTemplateContext } from "../utils/template";
 import { Flow } from "./Flow";
 import { Step, FlowConfigurationError } from "../core/Step";
 import { FlowRouter } from "./FlowRouter";
-import type { ToolManager } from "../core/ToolManager";
 import { evaluateBranches, createAiConditionEvaluator } from "./BranchEvaluator";
 import { DirectiveChainTracker } from "./DirectiveChainTracker";
-import { DirectiveBus } from "./DirectiveBus";
+import { ResponseGenerationError } from "./ResponseGenerationError";
+import type { SignalCoordinator } from "./SignalCoordinator";
 
 /**
  * Position fields on a Directive that represent a navigation decision.
@@ -57,6 +54,8 @@ export function hasDirectivePositionField<TContext = unknown, TData = unknown>(
 export interface ResponsePreparationResult<TContext, TData = unknown> {
   effectiveContext: TContext;
   session: SessionState<TData>;
+  /** Context returned by the beforeRespond hook, for the caller to sync back to the agent. */
+  contextAfterHook?: TContext;
 }
 
 export interface RoutingResult<TContext, TData = unknown> {
@@ -68,20 +67,6 @@ export interface RoutingResult<TContext, TData = unknown> {
   completedFlows?: Flow<TContext, TData>[];
 }
 
-export interface ToolExecutionResult<TData = unknown> {
-  session: SessionState<TData>;
-  toolCalls:
-  | Array<{ toolName: string; arguments: Record<string, unknown> }>
-  | undefined;
-  /** Map of tool name to serialized result data for inclusion in conversation history */
-  toolResults?: Map<string, string>;
-}
-
-export interface DataCollectionResult<TData = unknown> {
-  session: SessionState<TData>;
-  collectedData?: Partial<TData>;
-}
-
 /**
  * Shared response processing logic between respond() and respondStream() methods
  */
@@ -96,20 +81,10 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
   constructor(
     private readonly options: AgentOptions<TContext, TData>,
     private readonly getFlows: () => Flow<TContext, TData>[],
-    private readonly tools: Tool<TContext, TData>[],
     private readonly flowRouter: FlowRouter<TContext, TData>,
-    private readonly updateContext: (
-      updates: Partial<TContext>
-    ) => Promise<void>,
-    private readonly updateData: (
-      session: SessionState<TData>,
-      dataUpdate: Partial<TData>
-    ) => Promise<SessionState<TData>>,
-    private readonly updateCollectedData?: (
-      updates: Partial<TData>
-    ) => Promise<void>,
-    private readonly toolManager?: ToolManager<TContext, TData>,
-    private readonly signalProcessor?: SignalProcessor<TContext, TData>
+    private readonly signalCoordinator: SignalCoordinator<TContext, TData>,
+    private readonly updateCollectedData: (updates: Partial<TData>) => Promise<void>,
+    private readonly getSchema: () => StructuredSchema | undefined
   ) { }
 
   /**
@@ -132,101 +107,27 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
     return this._chainTracker;
   }
 
-  /**
-   * Create a fresh DirectiveBus for a new turn.
-   * The bus collects directives from hooks, tools, and branches during the turn
-   * and merges them at phase boundaries via Algorithm 4.
-   */
-  createDirectiveBus(): DirectiveBus<TContext, TData> {
-    return new DirectiveBus<TContext, TData>();
-  }
-
-  // ──────────────────────────────────────────────────────────────────────────
-  // Signal pipeline phases
-  // ──────────────────────────────────────────────────────────────────────────
-
-  /**
-   * PRE-SIGNAL PHASE — Evaluates pre/both signals in parallel with routing.
-   *
-   * Delegates to `signalProcessor.runPreSignalPhase(...)` when configured.
-   * When no signal processor is present (zero-cost path), returns a stable
-   * empty shape so callers don't need to branch.
-   *
-   * @requirements 2.1, 2.3, 8.6, 13.3
-   */
-  async runPreSignalPhase(
-    session: SessionState<TData>,
-    context: TContext,
-    history: Event[],
-  ): Promise<{
-    firings: SignalFiring<TContext, TData>[];
-    updatedSession: SessionState<TData>;
-    mergedDirective: Directive<TContext, TData> | undefined;
-  }> {
-    if (!this.signalProcessor) {
-      return { firings: [], updatedSession: session, mergedDirective: undefined };
-    }
-    const result = await this.signalProcessor.runPreSignalPhase({ session, history, context });
-    return {
-      firings: result.firings,
-      updatedSession: result.updatedSession,
-      mergedDirective: result.mergedDirective,
-    };
-  }
-
-  /**
-   * POST-SIGNAL PHASE — Evaluates post/both signals after finalize/onComplete.
-   *
-   * Delegates to `signalProcessor.runPostSignalPhase(...)` when configured.
-   * When no signal processor is present, returns a stable empty shape.
-   *
-   * Post-phase signals see the complete turn result: assistant message in history,
-   * collected data, tool results. Position directives from this phase set
-   * `session.pendingDirective` (no mid-turn re-entry per D6 decision).
-   *
-   * Pre-LLM-only fields (`appendPrompt`, `injectTools`, `halt`) are already
-   * dropped inside `runPostSignalPhase` per Phase 4.5 — this seam does NOT
-   * re-introduce them.
-   *
-   * @requirements 9.1, 9.2, 9.3, 9.4
-   */
-  async runPostSignalPhase(
-    session: SessionState<TData>,
-    context: TContext,
-    history: Event[],
-  ): Promise<{
-    firings: SignalFiring<TContext, TData>[];
-    updatedSession: SessionState<TData>;
-    mergedDirective: Directive<TContext, TData> | undefined;
-  }> {
-    if (!this.signalProcessor) {
-      return { firings: [], updatedSession: session, mergedDirective: undefined };
-    }
-    const result = await this.signalProcessor.runPostSignalPhase({ session, history, context });
-    return {
-      firings: result.firings,
-      updatedSession: result.updatedSession,
-      mergedDirective: result.mergedDirective,
-    };
-  }
-
   /**
    * Prepare context and session for response generation
    */
   async prepareResponseContext(params: {
     contextOverride?: Partial<TContext>;
     session?: SessionState<TData>;
+    /** The agent's current context, resolved by the caller (contextProvider already applied). */
+    currentContext?: TContext;
+    /** The agent's live session, used when no explicit session is passed. */
+    currentSession?: SessionState<TData>;
   }): Promise<ResponsePreparationResult<TContext, TData>> {
     const { contextOverride, session } = params;
 
-    // Get current context (may fetch from provider)
-    let currentContext = await this.getContext();
+    let currentContext = params.currentContext;
+    let contextAfterHook: TContext | undefined;
 
     // Call beforeRespond hook if configured
     if (this.options.hooks?.beforeRespond && currentContext !== undefined) {
       currentContext = await this.options.hooks.beforeRespond(currentContext);
-      // Update stored context with the result from beforeRespond
-      this.context = currentContext;
+      // Surface the hook result so the caller can sync it back to the agent
+      contextAfterHook = currentContext;
     }
 
     // Merge context with override
@@ -235,12 +136,13 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
       ...(contextOverride as Record<string, unknown>),
     } as TContext;
 
-    // Initialize or get session (use current session if available)
-    const targetSession = session || this.currentSession || createSession<TData>();
+    // Initialize or get session (use the live session if available)
+    const targetSession = session || params.currentSession || createSession<TData>();
 
     return {
       effectiveContext,
       session: targetSession,
+      contextAfterHook,
     };
   }
 
@@ -270,7 +172,7 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
     if (targetSession.pendingDirective) {
       const directive = targetSession.pendingDirective;
       logger.debug(
-        `[ResponseHandler] Applying pending directive at start of turn`
+        `[ResponsePipeline] Applying pending directive at start of turn`
       );
 
       // Track directive chain depth (Requirement 22.1)
@@ -306,7 +208,7 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
 
           if (targetFlow) {
             logger.debug(
-              `[ResponseHandler] Pending directive goTo → flow: ${targetFlow.title}`
+              `[ResponsePipeline] Pending directive goTo → flow: ${targetFlow.title}`
             );
             targetSession = enterFlow(
               targetSession,
@@ -436,7 +338,7 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
       // Log if flow is complete
       if (isFlowComplete) {
         logger.debug(
-          `[ResponseHandler] Flow complete: all required data collected or last step reached`
+          `[ResponsePipeline] Flow complete: all required data collected or last step reached`
         );
       }
     }
@@ -459,10 +361,12 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
     selectedStep: Step<TContext, TData> | undefined;
     session: SessionState<TData>;
     isFlowComplete: boolean;
+    /** The turn's effective context, passed explicitly (no stored pipeline state). */
+    context: TContext;
     /** Merged directive from the directive bus (pre-LLM + post-LLM phases). */
     busDirective?: Directive<TContext, TData>;
   }): Promise<{ nextStep: Step<TContext, TData> | undefined; session: SessionState<TData>; flowChanged?: Flow<TContext, TData> }> {
-    const { selectedFlow, selectedStep, session, isFlowComplete, busDirective } = params;
+    const { selectedFlow, selectedStep, session, isFlowComplete, context, busDirective } = params;
 
     if (!selectedFlow) {
       return { nextStep: undefined, session };
@@ -475,7 +379,7 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
     // branches or linear/AI selection — the caller applies the bus directive.
     if (hasDirectivePositionField(busDirective)) {
       logger.debug(
-        `[ResponseHandler] Directive bus winner has position field — skipping branch evaluation and linear/AI selection`,
+        `[ResponsePipeline] Directive bus winner has position field — skipping branch evaluation and linear/AI selection`,
       );
       return { nextStep: undefined, session };
     }
@@ -489,9 +393,8 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
         : undefined;
 
       if (currentStep?.branches && currentStep.branches.length > 0) {
-        const contextToUse = this.getStoredContext();
         const branchResult = await this.evaluateStepBranches(
-          currentStep, selectedFlow, session, contextToUse as TContext
+          currentStep, selectedFlow, session, context
         );
         if (branchResult) {
           return branchResult;
@@ -515,19 +418,17 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
         ? selectedFlow.getStep(session.currentStep.id)
         : undefined;
 
-      const contextToUse = this.getStoredContext();
-
       // Get candidate steps based on current position in the flow
       const candidates = await this.flowRouter.getCandidateStepsWithConditions(
         selectedFlow,
         currentStep, // Pass current step instead of undefined to maintain progression
-        createTemplateContext({ data: session.data, session, context: contextToUse })
+        createTemplateContext({ data: session.data, session, context })
       );
 
       if (candidates.length > 0) {
         nextStep = candidates[0].step;
         logger.debug(
-          `[ResponseHandler] Using first valid step: ${nextStep.id}${currentStep ? ' (progressing from ' + currentStep.id + ')' : ' for new flow'}`
+          `[ResponsePipeline] 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
@@ -546,7 +447,7 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
       );
       if (missingRequires.length > 0) {
         logger.debug(
-          `[ResponseHandler] Cannot enter step "${nextStep.id}": missing required fields [${missingRequires.join(', ')}]. Staying at current step.`
+          `[ResponsePipeline] Cannot enter step "${nextStep.id}": missing required fields [${missingRequires.join(', ')}]. Staying at current step.`
         );
         // Stay at current step - don't enter the next one
         const currentStepId = session.currentStep?.id;
@@ -566,7 +467,7 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
       nextStep.id,
       nextStep.description
     );
-    logger.debug(`[ResponseHandler] Entered step: ${nextStep.id}`);
+    logger.debug(`[ResponsePipeline] Entered step: ${nextStep.id}`);
 
     return { nextStep, session: updatedSession };
   }
@@ -626,7 +527,7 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
     const localStep = selectedFlow.getStep(result);
     if (localStep) {
       const updatedSession = enterStep(session, localStep.id, localStep.description);
-      logger.debug(`[ResponseHandler] Branch resolved to local step: ${localStep.id}`);
+      logger.debug(`[ResponsePipeline] Branch resolved to local step: ${localStep.id}`);
       return { nextStep: localStep, session: updatedSession };
     }
 
@@ -635,7 +536,7 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
     const targetFlow = flows.find(f => f.id === result || f.title === result);
     if (targetFlow) {
       // Treat as applyDirective({ goTo: result }) — enter the target flow
-      logger.debug(`[ResponseHandler] Branch resolved to flow: ${targetFlow.title}`);
+      logger.debug(`[ResponsePipeline] Branch resolved to flow: ${targetFlow.title}`);
       const updatedSession = enterFlow(session, targetFlow.id, targetFlow.title);
       return { nextStep: undefined, session: updatedSession, flowChanged: targetFlow };
     }
@@ -685,7 +586,7 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
           updatedSession = enterStep(updatedSession, stepTarget);
           // Try to resolve the target step instance for the caller
           const targetStepInstance = targetFlow.getStep(stepTarget);
-          logger.debug(`[ResponseHandler] Branch directive goToStep → ${flowTarget}.${stepTarget}`);
+          logger.debug(`[ResponsePipeline] Branch directive goToStep → ${flowTarget}.${stepTarget}`);
           return { nextStep: targetStepInstance || undefined, session: updatedSession, flowChanged: targetFlow };
         }
         throw new FlowConfigurationError(
@@ -698,7 +599,7 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
       const targetStep = selectedFlow.getStep(stepTarget);
       if (targetStep) {
         updatedSession = enterStep(updatedSession, targetStep.id, targetStep.description);
-        logger.debug(`[ResponseHandler] Branch directive goToStep → ${targetStep.id}`);
+        logger.debug(`[ResponsePipeline] Branch directive goToStep → ${targetStep.id}`);
         return { nextStep: targetStep, session: updatedSession };
       }
       throw new FlowConfigurationError(
@@ -723,7 +624,7 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
             updatedSession = enterStep(updatedSession, directive.goTo.step);
           }
 
-          logger.debug(`[ResponseHandler] Branch directive goTo → ${targetFlow.title}`);
+          logger.debug(`[ResponsePipeline] Branch directive goTo → ${targetFlow.title}`);
           return { nextStep: undefined, session: updatedSession, flowChanged: targetFlow };
         }
         throw new FlowConfigurationError(
@@ -734,12 +635,12 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
     }
 
     if (directive.complete) {
-      logger.debug(`[ResponseHandler] Branch directive complete`);
+      logger.debug(`[ResponsePipeline] Branch directive complete`);
       return { nextStep: undefined, session: updatedSession };
     }
 
     if (directive.abort) {
-      logger.debug(`[ResponseHandler] Branch directive abort`);
+      logger.debug(`[ResponsePipeline] Branch directive abort`);
       return { nextStep: undefined, session: updatedSession };
     }
 
@@ -757,7 +658,7 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
       // Reset to initial step
       const initialStep = selectedFlow.initialStep;
       updatedSession = enterStep(updatedSession, initialStep.id, initialStep.description);
-      logger.debug(`[ResponseHandler] Branch directive reset → ${initialStep.id}`);
+      logger.debug(`[ResponsePipeline] Branch directive reset → ${initialStep.id}`);
       return { nextStep: initialStep, session: updatedSession };
     }
 
@@ -766,612 +667,541 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
     return { nextStep: undefined, session: updatedSession };
   }
 
+
   /**
-   * Execute tool calls and handle results
+   * TURN ROUTING + STEP SELECTION — the single entry point for deciding which
+   * flow and step a turn renders. Runs the routing-skip optimization, the
+   * pre-signal phase (parallel with routing when a processor is configured),
+   * pre-extraction, and next-step determination.
    */
-  async executeToolCalls(params: {
-    toolCalls: Array<{ toolName: string; arguments: Record<string, unknown> }>;
-    selectedFlow?: Flow<TContext, TData>;
+  async routeAndSelectStep(params: {
+    session: SessionState<TData>;
+    history: Event[]; // Use Event[] for internal processing
     context: TContext;
+    signal?: AbortSignal;
+  }): Promise<{
+    selectedFlow?: Flow<TContext, TData>;
+    selectedStep?: Step<TContext, TData>;
+    responseDirectives?: string[];
     session: SessionState<TData>;
-    history: Event[];
-    isStreaming?: boolean;
-  }): Promise<ToolExecutionResult<TData>> {
-    const {
-      toolCalls,
-      selectedFlow,
-      context,
-      session,
-      history,
-      isStreaming = false,
-    } = params;
-
-    if (toolCalls.length === 0) {
-      return { session, toolCalls: undefined };
-    }
-
-    logger.debug(
-      `[ResponseHandler] Executing ${toolCalls.length} ${isStreaming ? "streaming " : ""
-      }tool calls`
-    );
-
-    let updatedSession = session;
-    const executedToolCalls: Array<{
-      toolName: string;
-      arguments: Record<string, unknown>;
-    }> = [];
-    const toolResults = new Map<string, string>();
-
-    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 (transient, step, flow, or agent). Skipping this tool call. Register the tool or check the tool name.`);
-        continue;
-      }
-
-      // Use ToolManager for unified tool execution
-      let result;
-      if (this.toolManager) {
-        result = await this.toolManager.executeTool({
-          tool,
-          context,
-          updateContext: this.updateContext,
-          updateData: this.updateCollectedData || (async () => { }),
-          history,
-          data: updatedSession.data,
-        });
-      } else {
-        // Fallback: execute tool directly if ToolManager not available
-        throw new Error(`ToolManager not available for tool execution: ${toolCall.toolName}`);
-      }
-
-      executedToolCalls.push(toolCall);
-
-      // Store the actual tool result data for history
-      toolResults.set(toolCall.toolName, serializeToolResult(result));
-
-      // Update context with tool results
-      if (result.contextUpdate) {
-        await this.updateContext(result.contextUpdate as Partial<TContext>);
-      }
-
-      // Update collected data with tool results
-      if (result.dataUpdate) {
-        updatedSession = await this.updateData(
-          updatedSession,
-          result.dataUpdate as Partial<TData>
-        );
-        logger.debug(
-          `[ResponseHandler] ${isStreaming ? "Streaming " : ""
-          }Tool updated collected data:`,
-          result.dataUpdate
-        );
+    isFlowComplete: boolean;
+    /** Signal firings from the pre-phase (threaded through for response surface). */
+    signalFirings?: SignalFiring<TContext, TData>[];
+    /** Non-position signal directive for pre-LLM augmentation (appendPrompt, injectTools, etc). */
+    signalPreDirective?: Directive<TContext, TData>;
+    /** Pre-signal phase halted the turn. */
+    signalHalted?: boolean;
+    /** Reply text from the halt directive. */
+    signalHaltReply?: string;
+  }> {
+    try {
+      // Create a fresh chain tracker for this turn (Requirement 22.1)
+      this.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.signalCoordinator.enabled) {
+          const signalResult = await this.signalCoordinator.runPrePhase(
+            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.signalCoordinator.applyPositionDirective(signalResult);
+          }
+          // Non-position directive: propagate for pre-LLM augmentation
+          return {
+            ...routingSkipResult,
+            session: signalResult.updatedSession,
+            signalFirings: signalResult.firings,
+            signalPreDirective: signalResult.mergedDirective || undefined,
+          };
+        }
+        return routingSkipResult;
       }
 
-      logger.debug(
-        `[ResponseHandler] Executed ${isStreaming ? "streaming " : ""}tool: ${String(tool.id || tool.id || 'unknown')
-        } (success: ${result.success})`
-      );
-    }
+      // ── 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.signalCoordinator.enabled) {
+        // Run pre-signal phase in parallel with routing (Requirement 8.1)
+        const [signalResult, routingResult] = await Promise.all([
+          this.signalCoordinator.runPrePhase(
+            params.session, params.context, params.history,
+          ),
+          this.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,
+          };
+        }
 
-    return {
-      session: updatedSession,
-      toolCalls: executedToolCalls.length > 0 ? executedToolCalls : undefined,
-      toolResults,
-    };
-  }
+        // ── Requirement 8.3: position directive → discard routing, apply signal position ──
+        if (hasDirectivePositionField(signalResult.mergedDirective)) {
+          return this.signalCoordinator.applyPositionDirective(signalResult);
+        }
 
-  /**
-   * Execute tool loop for follow-up tool calls
-   */
-  async executeToolLoop(params: {
-    initialToolCalls:
-    | Array<{ toolName: string; arguments: Record<string, unknown> }>
-    | undefined;
-    selectedFlow?: Flow<TContext, TData>;
-    nextStep: Step<TContext, TData>;
-    responsePrompt: string;
-    history: HistoryItem[];
-    context: TContext;
-    session: SessionState<TData>;
-    responseSchema: Record<string, unknown>;
-    isStreaming?: boolean;
-  }): Promise<ToolExecutionResult<TData>> {
-    const {
-      initialToolCalls,
-      selectedFlow,
-      nextStep,
-      responsePrompt,
-      history,
-      context,
-      session,
-      responseSchema,
-      isStreaming = false,
-    } = params;
-
-    const MAX_TOOL_LOOPS = 5;
-    let toolLoopCount = 0;
-    let currentToolCalls = initialToolCalls;
-    let hasToolCalls = currentToolCalls && currentToolCalls.length > 0;
-    let currentSession = session;
-    // Track tool results across loop iterations for history
-    let currentToolResults = new Map<string, string>();
-
-    while (hasToolCalls && toolLoopCount < MAX_TOOL_LOOPS) {
-      toolLoopCount++;
-      logger.debug(
-        `[ResponseHandler] Starting ${isStreaming ? "streaming " : ""
-        }tool loop ${toolLoopCount}/${MAX_TOOL_LOOPS}`
-      );
+        // ── Requirement 8.4: non-position directive → use routing, propagate augmentation ──
+        // ── Requirement 8.5: no directive → use routing as-is ─────────────
+        let updatedSession = signalResult.updatedSession;
 
-      // Add tool execution results to history so AI knows what happened
-      const toolResultItems: HistoryItem[] = [];
-      for (const toolCall of currentToolCalls || []) {
-        const tool = this.findAvailableTool(toolCall.toolName, selectedFlow);
-        if (tool) {
-          toolResultItems.push({
-            role: "assistant" as const,
-            content: null,
-            tool_calls: [{
-              id: toolCall.toolName,
-              name: toolCall.toolName,
-              arguments: toolCall.arguments,
-            }],
-          });
-          toolResultItems.push({
-            role: "tool" as const,
-            tool_call_id: toolCall.toolName,
-            name: toolCall.toolName,
-            content: currentToolResults.get(toolCall.toolName) || "Tool executed successfully",
-          });
+        // Apply data/context updates from signal to the routed session
+        if (signalResult.mergedDirective?.dataUpdate) {
+          updatedSession = mergeCollected(updatedSession, signalResult.mergedDirective.dataUpdate);
         }
-      }
-
-      // Create updated history with tool results
-      const updatedHistory = [...history, ...toolResultItems];
 
-      // Make follow-up AI call to see if more tools are needed
-      const followUpResult = await this.options.provider.generateMessage({
-        prompt: responsePrompt,
-        history: updatedHistory,
-        context,
-        tools: this.collectAvailableTools(selectedFlow, nextStep),
-        parameters: {
-          jsonSchema: responseSchema,
-          schemaName: isStreaming ? "tool_followup_streaming" : "tool_followup",
-        },
-      });
+        // 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,
+        };
 
-      // Check if follow-up call has more tool calls
-      const followUpToolCalls = followUpResult.structured?.toolCalls;
-      hasToolCalls = followUpToolCalls && followUpToolCalls.length > 0;
+        const isFlowComplete = routingResult.isFlowComplete;
 
-      if (hasToolCalls) {
-        logger.debug(
-          `[ResponseHandler] Follow-up call produced ${followUpToolCalls!.length
-          } additional tool calls`
-        );
+        // PRE-EXTRACTION: same logic as below — extract data from user message
+        if (routingResult.selectedFlow && !isFlowComplete) {
+          if (this.shouldPreExtractData(routingResult.selectedFlow)) {
+            logger.debug(
+              `[ResponsePipeline] 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(`[ResponsePipeline] Pre-extracted data:`, extractedData);
+              updatedSession = mergeCollected(updatedSession, extractedData);
+              await this.updateCollectedData(extractedData);
+            }
+          }
+        }
 
-        // Execute the follow-up tool calls
-        const toolResult = await this.executeToolCalls({
-          toolCalls: followUpToolCalls!,
-          selectedFlow,
-          context,
-          session: currentSession,
-          history: historyToEvents(updatedHistory),
-          isStreaming,
+        // Determine next step
+        const stepResult = await this.determineNextStep({
+          selectedFlow: routingResult.selectedFlow,
+          selectedStep: routingResult.selectedStep,
+          session: updatedSession,
+          isFlowComplete,
+          context: params.context,
         });
 
-        currentSession = toolResult.session;
-        currentToolCalls = followUpToolCalls;
-        currentToolResults = toolResult.toolResults || new Map();
-      } else {
-        logger.debug(
-          `[ResponseHandler] ${isStreaming ? "Streaming " : ""
-          }Tool loop completed after ${toolLoopCount} iterations`
-        );
-        // Update final toolCalls from follow-up result if no more tools
-        currentToolCalls = followUpToolCalls || [];
-        break;
+        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,
+        };
       }
-    }
-
-    if (toolLoopCount >= MAX_TOOL_LOOPS) {
-      logger.warn(
-        `[ResponseGenerationError] ${isStreaming ? "Streaming t" : "T"}ool loop limit reached: ${toolLoopCount} iterations hit the cap (${MAX_TOOL_LOOPS}). Stopping tool execution. Increase MAX_TOOL_LOOPS or reduce recursive tool calls.`
-      );
-    }
-
-    return {
-      session: currentSession,
-      toolCalls: currentToolCalls,
-    };
-  }
 
-  /**
-   * Handle data collection from structured response
-   */
-  async handleDataCollection(params: {
-    structured: AgentStructuredResponse | undefined;
-    nextStep: Step<TContext, TData>;
-    session: SessionState<TData>;
-  }): Promise<DataCollectionResult<TData>> {
-    const { structured, nextStep, session } = params;
-
-    if (!structured || !nextStep.collect) {
-      return { session };
-    }
+      // ── No signal processor: existing behavior (zero overhead) ────────────
+      const routingResult = await this.handleRoutingAndStepSelection({
+        session: params.session,
+        history: params.history,
+        context: params.context,
+        signal: params.signal,
+      });
 
-    const collectedData: Partial<TData> = {};
-    // The structured response includes both base fields and collected extraction fields
-    const structuredData = structured as AgentStructuredResponse &
-      Record<string, unknown>;
+      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(
+            `[ResponsePipeline] Pre-extracting data for flow: ${routingResult.selectedFlow.title}`
+          );
 
-    for (const field of nextStep.collect) {
-      const fieldKey = field as string;
-      if (fieldKey in structuredData) {
-        (collectedData as Record<string, unknown>)[fieldKey] = structuredData[fieldKey];
-      }
-    }
+          const extractedData = await this.preExtractFlowData({
+            route: routingResult.selectedFlow,
+            history: params.history,
+            context: params.context,
+            session: updatedSession,
+            signal: params.signal,
+          });
 
-    let updatedSession = session;
-    if (Object.keys(collectedData).length > 0) {
-      // Update agent-level collected data with validation if available
-      if (this.updateCollectedData) {
-        await this.updateCollectedData(collectedData);
+          if (extractedData && Object.keys(extractedData).length > 0) {
+            logger.debug(
+              `[ResponsePipeline] 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.updateCollectedData(extractedData);
+          }
+        }
       }
 
-      // Update session with validated data
-      updatedSession = await this.updateData(session, collectedData);
-      logger.debug(`[ResponseHandler] Collected data:`, collectedData);
-    }
-
-    return {
-      session: updatedSession,
-      collectedData,
-    };
-  }
+      // Determine next step using pipeline method for consistency
+      const stepResult = await this.determineNextStep({
+        selectedFlow: routingResult.selectedFlow,
+        selectedStep: routingResult.selectedStep,
+        session: updatedSession, // Use updated session with pre-extracted data
+        isFlowComplete, // Use updated completion status
+        context: params.context,
+      });
 
-  /**
-   * Handle context updates from structured response
-   */
-  async handleContextUpdate(
-    structured: AgentStructuredResponse | undefined
-  ): Promise<void> {
-    if (
-      structured &&
-      typeof structured === "object" &&
-      "contextUpdate" in structured
-    ) {
-      await this.updateContext(
-        (structured as { contextUpdate?: Partial<TContext> })
-          .contextUpdate as Partial<TContext>
-      );
+      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);
     }
   }
 
   /**
-   * Handle flow completion: pure state transition.
+   * RENDER-STEP RESOLUTION — resolve the step a flow response will render,
+   * shared by the streaming and non-streaming paths. When no step was
+   * pre-selected: branches win over the linear chain, then candidate steps,
+   * then the initial-step fallback. Enforces `requires` (stays at the current
+   * step when required fields are missing) and enters the resolved step.
    *
-   * Releases the session to idle (`currentFlow`/`currentStep` cleared),
-   * marks the active `flowHistory` entry completed, and (when `onComplete`
-   * is set) wires `pendingDirective` for the next turn. The framework
-   * emits no message of its own at the completion boundary; callers that
-   * need closing copy should add a final interactive step.
+   * Returns `flowTransition: true` when a branch resolved to a flow
+   * transition or completion — there is no local step to render and the
+   * caller handles the transition.
    */
-  async handleFlowCompletion(params: {
+  async resolveRenderStep(params: {
     selectedFlow: Flow<TContext, TData>;
+    selectedStep?: Step<TContext, TData>;
     session: SessionState<TData>;
     context: TContext;
-    history: Event[];
-  }): Promise<{ session: SessionState<TData>; hasTransition: boolean }> {
-    const { selectedFlow, session, context } = params;
-
-    // Check for onComplete transition
-    const transitionConfig = await selectedFlow.evaluateOnComplete(
-      { data: session.data },
-      context
-    );
-
-    // Release to idle. When the flow is reentrant, scrub its owned
-    // fields so a future re-selection doesn't short-circuit on stale data.
-    const ownedFields = selectedFlow.reentrant
-      ? [
-        ...(selectedFlow.requiredFields ?? []),
-        ...(selectedFlow.optionalFields ?? []),
-      ]
-      : undefined;
-    let updatedSession = completeCurrentFlow(session, {
-      clearOwnedFields: ownedFields,
-    });
+  }): Promise<{
+    nextStep?: Step<TContext, TData>;
+    session: SessionState<TData>;
+    flowTransition: boolean;
+  }> {
+    const { selectedFlow, selectedStep, context } = params;
+    let session = params.session;
 
-    if (transitionConfig) {
-      // Extract target from directive's goTo field
-      const goToTarget = typeof transitionConfig.goTo === 'string'
-        ? transitionConfig.goTo
-        : transitionConfig.goTo?.flow;
+    // Determine next step
+    let nextStep: Step<TContext, TData>;
+    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;
 
-      // Find target flow by ID or title
-      const targetFlow = goToTarget ? this.getFlows().find(
-        (r) =>
-          r.id === goToTarget ||
-          r.title === goToTarget
-      ) : undefined;
+      logger.debug(`[ResponsePipeline] Step determination: flow match=${isInSameFlow}, currentFlow=${session.currentFlow?.id}, selectedFlow=${selectedFlow.id}, currentStep=${currentStep?.id || 'none'}`);
 
-      if (targetFlow) {
-        updatedSession = {
-          ...updatedSession,
-          pendingDirective: {
-            goTo: targetFlow.id,
-          },
-        };
-        logger.debug(
-          `[ResponseHandler] Flow ${selectedFlow.title} completed with pending directive to: ${targetFlow.title}`
+      // STEP 1 (Algorithm 1): branches win over linear chain
+      if (currentStep?.branches && currentStep.branches.length > 0) {
+        const branchResult = await this.evaluateStepBranches(
+          currentStep, selectedFlow, session, context
         );
-        return { session: updatedSession, hasTransition: true };
-      } else if (goToTarget) {
-        logger.warn(
-          `[FlowConfigurationError] onComplete target not found: flow "${selectedFlow.title}" completed but onComplete target "${goToTarget}" does not match any flow. ` +
-          `Fix the onComplete value to reference an existing flow id/title, or remove onComplete to release the session to idle.`
+        if (branchResult) {
+          if (branchResult.nextStep) {
+            nextStep = branchResult.nextStep;
+            session = branchResult.session;
+          } else {
+            // Flow transition or completion — no local step to render
+            return { nextStep: undefined, session: branchResult.session, flowTransition: true };
+          }
+        }
+      }
+
+      if (!nextStep!) {
+        // Get candidate steps based on current position in the flow
+        const candidates = await this.flowRouter.getCandidateStepsWithConditions(
+          selectedFlow,
+          currentStep, // Pass current step instead of undefined to maintain progression
+          createTemplateContext({ data: session.data, session, context })
         );
+
+        logger.debug(`[ResponsePipeline] Found ${candidates.length} candidate steps${currentStep ? ' from current step ' + currentStep.id : ' (new flow entry)'}`);
+
+        if (candidates.length > 0) {
+          nextStep = candidates[0].step;
+          logger.debug(`[ResponsePipeline] 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.`);
+        }
       }
     }
 
-    logger.debug(
-      `[ResponseHandler] Flow ${selectedFlow.title} completed; session released to idle.`
-    );
+    // 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 as Record<string, unknown>)[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(`[ResponsePipeline] Staying at current step: ${nextStep.id} due to missing requires`);
+          }
+        }
+      } else {
+        session = enterStep(session, nextStep.id, nextStep.description);
+        logger.debug(`[ResponsePipeline] Entered step: ${nextStep.id}`);
+      }
+    } else {
+      session = enterStep(session, nextStep.id, nextStep.description);
+      logger.debug(`[ResponsePipeline] Entered step: ${nextStep.id}`);
+    }
 
-    return { session: updatedSession, hasTransition: false };
+    return { nextStep, session, flowTransition: false };
   }
 
-
   /**
-   * Find an available tool by name for the given flow using ToolManager
-   * Delegates to ToolManager for unified tool resolution
+   * 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 findAvailableTool(
-    toolName: string,
-    flow?: Flow<TContext, TData>
-  ): Tool<TContext, TData> | undefined {
-    // Use ToolManager for unified tool resolution if available
-    if (this.toolManager) {
-      return this.toolManager.find(toolName, undefined, undefined, flow);
-    }
+  private async attemptRoutingSkipForCollect(params: {
+    session: SessionState<TData>;
+    history: Event[];
+    context: TContext;
+    signal?: AbortSignal;
+  }): Promise<{
+    selectedFlow?: Flow<TContext, TData>;
+    selectedStep?: Step<TContext, TData>;
+    responseDirectives?: string[];
+    session: SessionState<TData>;
+    isFlowComplete: boolean;
+  } | undefined> {
+    const { session } = params;
 
-    // Fallback to legacy resolution if ToolManager not available
-    logger.warn(`[ResponsePipeline] ToolManager not available, using legacy tool resolution for: ${toolName}`);
+    // Only applies when we already have a current flow and step
+    if (!session.currentFlow || !session.currentStep) {
+      return undefined;
+    }
 
-    // Check flow-level tools first (if flow provided)
-    if (flow) {
-      const flowTool = flow
-        .getTools()
-        .find((tool) => tool.id === toolName || tool.id === toolName);
-      if (flowTool) return flowTool;
+    // Also skip this optimization if there's a pending directive (it takes priority)
+    if (session.pendingDirective) {
+      return undefined;
     }
 
-    // Fall back to agent-level tools
-    return this.tools.find(
-      (tool) => tool.id === toolName || tool.id === toolName
+    // Look up the actual Flow and Step objects to access `collect`
+    const currentFlow = this.getFlows().find(
+      (f) => f.id === session.currentFlow?.id
     );
-  }
+    if (!currentFlow) {
+      return undefined;
+    }
 
-  /**
-   * Collect all available tools for the given flow and step context using ToolManager
-   * Delegates to ToolManager for unified tool resolution and deduplication
-   */
-  private collectAvailableTools(
-    flow?: Flow<TContext, TData>,
-    step?: Step<TContext, TData>
-  ): Array<{ id: string; description?: string; parameters?: unknown }> {
-    // Use ToolManager for unified tool collection if available
-    if (this.toolManager) {
-      const availableTools = this.toolManager.getAvailable(undefined, step, flow);
-      return availableTools.map((tool) => ({
-        id: tool.id,
-        description: tool.description,
-        parameters: tool.parameters,
-      }));
+    const currentStep = currentFlow.getStep(session.currentStep.id);
+    if (!currentStep || !currentStep.collect || currentStep.collect.length === 0) {
+      return undefined;
     }
 
-    // Fallback to legacy collection logic if ToolManager not available
-    logger.warn(`[ResponsePipeline] ToolManager not available, using legacy tool collection`);
+    // 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;
 
-    const availableTools = new Map<
-      string,
-      Tool<TContext, TData>
-    >();
+    // Snapshot current data for comparison
+    const dataBefore = { ...session.data };
 
-    // Add agent-level tools
-    this.tools.forEach((tool) => {
-      availableTools.set(tool.id, tool);
+    // Run pre-extraction against the current flow
+    const extractedData = await this.preExtractFlowData({
+      route: currentFlow,
+      history: params.history,
+      context: params.context,
+      session,
+      signal: params.signal,
     });
 
-    // Add flow-level tools (these take precedence)
-    if (flow) {
-      flow.getTools().forEach((tool) => {
-        availableTools.set(tool.id, tool);
-      });
+    if (!extractedData || Object.keys(extractedData).length === 0) {
+      return undefined;
     }
 
-    // Filter by step-level allowed tools if specified
-    if (step?.tools) {
-      const allowedToolIds = new Set<string>();
-      const stepTools: Tool<TContext, TData>[] = [];
-
-      for (const toolRef of step.tools) {
-        if (typeof toolRef === "string") {
-          // Reference to registered tool
-          allowedToolIds.add(toolRef);
-        } else {
-          // Inline tool definition
-          if (toolRef.id) {
-            allowedToolIds.add(toolRef.id);
-            stepTools.push(toolRef);
-          }
-        }
-      }
-
-      // If step specifies tools, only include those
-      if (allowedToolIds.size > 0) {
-        const filteredTools = new Map<
-          string,
-          Tool<TContext, TData>
-        >();
-        for (const toolId of Array.from(allowedToolIds)) {
-          const tool = availableTools.get(toolId);
-          if (tool) {
-            filteredTools.set(toolId, tool);
-          }
-        }
-        // Add inline tools
-        stepTools.forEach((tool) => {
-          if (tool.id) {
-            filteredTools.set(tool.id, tool);
-          }
-        });
-        availableTools.clear();
-        filteredTools.forEach((tool, id) => availableTools.set(id, tool));
+    // Determine which collect fields were newly populated by pre-extraction
+    const populatedCollectFields: string[] = [];
+    for (const field of collectFields) {
+      const key = field as string;
+      const hadValue = dataBefore[field] !== undefined && dataBefore[field] !== null;
+      const hasNewValue = extractedData[field] !== undefined && extractedData[field] !== null;
+      if (hasNewValue && !hadValue) {
+        populatedCollectFields.push(key);
       }
     }
 
-    // Convert to the format expected by AI providers
-    return Array.from(availableTools.values()).map((tool) => ({
-      id: tool.id,
-      description: tool.description,
-      parameters: tool.parameters,
-    }));
-  }
-
-  /**
-   * Get current context (fetches from provider if configured)
-   */
-  private async getContext(): Promise<TContext | undefined> {
-    // If context provider is configured, use it to fetch fresh context
-    if (this.options.contextProvider) {
-      return await this.options.contextProvider();
+    if (populatedCollectFields.length === 0) {
+      // Pre-extraction didn't populate any declared collect field — no skip
+      return undefined;
     }
 
-    // Otherwise return the stored context
-    return this.context;
-  }
-
-  // These need to be passed in or accessed differently since ResponseHandler is not part of Agent
-  private context?: TContext;
-  private currentSession?: SessionState<TData>;
-
-  // Setters for context and current session (needed for beforeRespond hook)
-  setContext(context: TContext | undefined): void {
-    this.context = context;
-  }
+    // ROUTING SKIP: pre-extraction populated collect fields → retain current flow/step
+    logger.debug(
+      `[ResponsePipeline] Routing skip: pre-extraction populated collect fields [${populatedCollectFields.join(', ')}] for step "${currentStep.id}" — skipping FlowRouter`
+    );
 
-  setCurrentSession(session: SessionState<TData> | undefined): void {
-    this.currentSession = session;
-  }
+    // Merge extracted data into session
+    const updatedSession = mergeCollected(session, extractedData);
+    await this.updateCollectedData(extractedData);
 
-  public getStoredContext(): TContext | undefined {
-    return this.context;
-  }
+    // Determine next step using pipeline method for consistency
+    // Pass the current flow/step as the routing result (retained)
+    const stepResult = await this.determineNextStep({
+      selectedFlow: currentFlow,
+      selectedStep: currentStep,
+      session: updatedSession,
+      isFlowComplete: false,
+      context: params.context,
+    });
 
-  public getCurrentSession(): SessionState<TData> | undefined {
-    return this.currentSession;
+    return {
+      selectedFlow: stepResult.flowChanged || currentFlow,
+      selectedStep: stepResult.nextStep,
+      responseDirectives: undefined,
+      session: stepResult.session,
+      isFlowComplete: false,
+    };
   }
 
   /**
-   * Handle cross-flow completion evaluation and notifications
-   * This method evaluates all flows for completion and can trigger completion handlers
+   * Check if a flow should pre-extract data before determining the initial step
    */
-  async handleCrossFlowCompletion(params: {
-    flows: Flow<TContext, TData>[];
-    session: SessionState<TData>;
-    context: TContext;
-    history: Event[];
-  }): Promise<{
-    session: SessionState<TData>;
-    completedFlows: Flow<TContext, TData>[];
-    pendingTransitions: Array<{
-      flow: Flow<TContext, TData>;
-      transitionConfig: Directive<TContext, TData>;
-    }>;
-  }> {
-    const { flows, session, context } = params;
-
-    // Evaluate all flows for completion
-    const completedFlows: Flow<TContext, TData>[] = [];
-    const pendingTransitions: Array<{
-      flow: Flow<TContext, TData>;
-      transitionConfig: Directive<TContext, TData>;
-    }> = [];
-
-    for (const flow of flows) {
-      if (flow.isComplete(session.data || {})) {
-        completedFlows.push(flow);
-
-        // Check for onComplete transitions
-        const transitionConfig = await flow.evaluateOnComplete(
-          { data: session.data },
-          context
-        );
-
-        if (transitionConfig) {
-          pendingTransitions.push({ flow, transitionConfig });
-        }
-
-        logger.debug(
-          `[ResponsePipeline] Flow completed: ${flow.title} ` +
-          `(${Math.round(flow.getCompletionProgress(session.data || {}) * 100)}%)`
-        );
-      }
+  private shouldPreExtractData(flow: Flow<TContext, TData>): boolean {
+    // Pre-extract if flow has declared required or optional fields
+    if (flow.requiredFields && flow.requiredFields.length > 0) {
+      return true;
     }
-
-    // Log completion status for all flows
-    if (completedFlows.length > 0) {
-      logger.debug(
-        `[ResponsePipeline] Cross-flow completion evaluation: ` +
-        `${completedFlows.length}/${flows.length} flows complete`
-      );
+    if (flow.optionalFields && flow.optionalFields.length > 0) {
+      return true;
     }
 
-    return {
-      session,
-      completedFlows,
-      pendingTransitions,
-    };
+    // 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;
   }
 
   /**
-   * Update data flow to ensure agent-level data consistency
-   * This method ensures that data updates are properly validated and propagated
+   * Pre-extract data from user message when entering a flow
+   * This allows skipping steps whose data is already provided
    */
-  async updateDataFlow(params: {
+  private async preExtractFlowData(params: {
+    route: Flow<TContext, TData>;
+    history: Event[];
+    context: TContext;
     session: SessionState<TData>;
-    dataUpdate: Partial<TData>;
-    flows: Flow<TContext, TData>[];
-  }): Promise<SessionState<TData>> {
-    const { session, dataUpdate, flows } = params;
-
-    // Update session data
-    const updatedSession = await this.updateData(session, dataUpdate);
+    signal?: AbortSignal;
+  }): Promise<Partial<TData>> {
+    const { route: flow, history, signal } = params;
+
+    // Build a schema for data extraction based on flow's fields
+    const extractionSchema = this.getSchema();
+    if (!extractionSchema) {
+      logger.warn(`[ResponsePipeline] No schema available for pre-extraction`);
+      return {};
+    }
 
-    // Update agent-level data if handler is available
-    if (this.updateCollectedData) {
-      await this.updateCollectedData(dataUpdate);
+    // 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(', ')}`);
     }
 
-    // Evaluate flow completions after data update
-    const completionResults = await this.handleCrossFlowCompletion({
-      flows,
-      session: updatedSession,
-      context: this.context!,
-      history: [],
-    });
+    extractionPrompt.push(
+      ``,
+      `Return ONLY the extracted data as JSON. If no data can be extracted, return an empty object {}.`
+    );
 
-    // Log any newly completed flows
-    if (completionResults.completedFlows.length > 0) {
-      logger.debug(
-        `[ResponsePipeline] Data update resulted in ${completionResults.completedFlows.length} completed flows`
-      );
-    }
+    // Convert Event[] to HistoryItem[] for provider call
+    const historyItems = eventsToHistory(history);
+
+    // Call AI to extract data
+    try {
+      const result = await this.options.provider.generateMessage<TContext, Partial<TData>>({
+        prompt: extractionPrompt.join('\n'),
+        history: historyItems,
+        context: {} as TContext, // 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 completionResults.session;
+      return result.structured || {};
+    } catch (error) {
+      logger.error(`[ResponsePipeline] Pre-extraction failed:`, error);
+      return {};
+    }
   }
+
 }