@falai/agent 1.1.1 → 1.1.3

package/src/core/ResponseModal.ts

@@ -358,7 +358,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
         if (this.agent && 'tool' in this.agent && this.agent.tool) {
             return this.agent.tool;
         }
-        
+
         // Log warning if ToolManager is not available
         logger.warn(`[ResponseModal] ToolManager not available on agent - tool execution will use fallback methods`);
         return undefined;
@@ -514,7 +514,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
             });
 
             let updatedSession = routingResult.session;
-            let isRouteComplete = routingResult.isRouteComplete;
+            const isRouteComplete = routingResult.isRouteComplete;
 
             // PRE-EXTRACTION: If entering a route that collects data, extract data from user message first
             // This allows us to skip steps whose data is already provided
@@ -544,15 +544,6 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                         updatedSession = mergeCollected(updatedSession, extractedData);
                         // Also update agent's collected data
                         await this.agent.updateCollectedData(extractedData);
-
-                        // Re-check route completion after pre-extraction
-                        const allRequiredFieldsCollected = routingResult.selectedRoute.isComplete(updatedSession.data || {});
-                        if (allRequiredFieldsCollected) {
-                            logger.debug(
-                                `[ResponseModal] Route ${routingResult.selectedRoute.title} completed after pre-extraction`
-                            );
-                            isRouteComplete = true;
-                        }
                     }
                 }
             }
@@ -565,7 +556,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
 
             if (routingResult.selectedRoute && !isRouteComplete) {
                 // Determine current step position for batch determination
-                const currentStep = routingResult.selectedStep || 
+                const currentStep = routingResult.selectedStep ||
                     (updatedSession.currentStep ? routingResult.selectedRoute.getStep(updatedSession.currentStep.id) : undefined);
 
                 logger.debug(`[ResponseModal] Determining batch starting from step: ${currentStep?.id || 'initial'}`);
@@ -642,7 +633,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
         session: SessionState<TData>;
         signal?: AbortSignal;
     }): Promise<Partial<TData>> {
-        const { route, history, context, signal } = params;
+        const { route, history, signal } = params;
 
         // Build a schema for data extraction based on route's fields
         const extractionSchema = this.agent.getSchema();
@@ -683,7 +674,10 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
             const result = await agentOptions.provider.generateMessage<TContext, Partial<TData>>({
                 prompt: extractionPrompt.join('\n'),
                 history,
-                context,
+                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,
@@ -705,13 +699,13 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
     private async generateUnifiedResponse(
         responseContext: ResponseContext<TContext, TData>
     ): Promise<AgentResponse<TData>> {
-        const { 
-            effectiveContext, 
-            session: initialSession, 
-            history, 
-            selectedRoute, 
-            selectedStep, 
-            responseDirectives, 
+        const {
+            effectiveContext,
+            session: initialSession,
+            history,
+            selectedRoute,
+            selectedStep,
+            responseDirectives,
             isRouteComplete,
             batchSteps,
             batchStoppedReason,
@@ -729,7 +723,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
         let stoppedReason: StoppedReason | undefined;
 
 
-        
+
         if (selectedRoute && !isRouteComplete) {
             // Check if we have batch steps to execute
             if (batchSteps && batchSteps.length > 0) {
@@ -770,7 +764,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 message = result.message;
                 toolCalls = result.toolCalls;
                 session = result.session;
-                
+
                 // Track executed step for single-step execution
                 if (selectedStep) {
                     executedSteps = [{
@@ -815,7 +809,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 context: effectiveContext,
                 session,
             });
-            
+
             // For fallback responses, set empty executedSteps and no stoppedReason
             // since there's no route/step execution happening
             executedSteps = [];
@@ -897,12 +891,12 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
             logger.error(`[ResponseModal] Prepare hook failed:`, prepareResult.error);
             throw new ResponseGenerationError(
                 `Prepare hook failed: ${prepareResult.error?.message}`,
-                { 
-                    phase: 'prepare_hooks', 
-                    context: { 
+                {
+                    phase: 'prepare_hooks',
+                    context: {
                         stepId: prepareResult.error?.stepId,
                         executedSteps: prepareResult.executedSteps,
-                    } 
+                    }
                 }
             );
         }
@@ -1029,36 +1023,36 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
      * @private
      */
     private buildBatchResponseSchema(collectFields: string[]): Record<string, unknown> {
-            const properties: Record<string, unknown> = {
-                message: {
-                    type: "string",
-                    description: "Your response to the user",
-                },
-            };
+        const properties: Record<string, unknown> = {
+            message: {
+                type: "string",
+                description: "Natural, conversational response directed at the user. Must NOT contain field names, raw data, or internal information.",
+            },
+        };
 
-            const agentSchema = this.agent.getSchema();
+        const agentSchema = this.agent.getSchema();
 
-            // Add collect fields to schema, using agent schema definitions when available
-            for (const field of collectFields) {
-                if (agentSchema?.properties && agentSchema.properties[field]) {
-                    properties[field] = agentSchema.properties[field];
-                } else {
-                    // Dynamic fallback when no agent schema is defined
-                    properties[field] = {
-                        type: "string",
-                        description: `Collected value for ${field}`,
-                    };
-                }
+        // Add collect fields to schema, using agent schema definitions when available
+        for (const field of collectFields) {
+            if (agentSchema?.properties && agentSchema.properties[field]) {
+                properties[field] = agentSchema.properties[field];
+            } else {
+                // Dynamic fallback when no agent schema is defined
+                properties[field] = {
+                    type: "string",
+                    description: `Collected value for ${field}`,
+                };
             }
-
-            return {
-                type: "object",
-                properties,
-                required: ["message"],
-                additionalProperties: true,
-            };
         }
 
+        return {
+            type: "object",
+            properties,
+            required: ["message"],
+            additionalProperties: true,
+        };
+    }
+
     /**
      * Collect available tools from all steps in the batch
      * @private
@@ -1114,13 +1108,13 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
     private async *generateUnifiedStreamingResponse(
         responseContext: ResponseContext<TContext, TData>
     ): AsyncGenerator<AgentResponseStreamChunk<TData>> {
-        const { 
-            effectiveContext, 
-            session: initialSession, 
-            history, 
-            selectedRoute, 
-            selectedStep, 
-            responseDirectives, 
+        const {
+            effectiveContext,
+            session: initialSession,
+            history,
+            selectedRoute,
+            selectedStep,
+            responseDirectives,
             isRouteComplete,
             batchSteps,
             batchStoppedReason,
@@ -1414,13 +1408,13 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
             // Get candidate steps based on current position in the route
             const routingEngine = this.agent.getRoutingEngine();
             const candidates = await routingEngine.getCandidateStepsWithConditions(
-                selectedRoute, 
+                selectedRoute,
                 currentStep, // Pass current step instead of undefined to maintain progression
                 createTemplateContext({ data: session.data, session, context })
             );
-            
+
             logger.debug(`[ResponseModal] Found ${candidates.length} candidate steps${currentStep ? ' from current step ' + currentStep.id : ' (new route entry)'}`);
-            
+
             if (candidates.length > 0) {
                 nextStep = candidates[0].step;
                 logger.debug(`[ResponseModal] Using first valid step: ${nextStep.id}${currentStep ? ' (progressing from ' + currentStep.id + ')' : ' for new route'}`);
@@ -1468,8 +1462,8 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
         const responsePrompt = await this.responseEngine.buildResponsePrompt({
             route: selectedRoute,
             currentStep: nextStep,
-            rules: [...this.agent.getRules(), ...selectedRoute.getRules()],
-            prohibitions: [...this.agent.getProhibitions(), ...selectedRoute.getProhibitions()],
+            rules: selectedRoute.getRules(),
+            prohibitions: selectedRoute.getProhibitions(),
             directives: responseDirectives,
             history: historyEvents, // Use Event[] for buildResponsePrompt
             lastMessage: lastMessageText, // Use string for buildResponsePrompt
@@ -1563,11 +1557,11 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
             // Get candidate steps based on current position in the route
             const routingEngine = this.agent.getRoutingEngine();
             const candidates = await routingEngine.getCandidateStepsWithConditions(
-                selectedRoute, 
+                selectedRoute,
                 currentStep, // Pass current step instead of undefined to maintain progression
                 createTemplateContext({ data: session.data, session, context })
             );
-            
+
             if (candidates.length > 0) {
                 nextStep = candidates[0].step;
                 logger.debug(`[ResponseModal] Using first valid step: ${nextStep.id}${currentStep ? ' (progressing from ' + currentStep.id + ')' : ' for new route'}`);
@@ -1611,8 +1605,8 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
         const responsePrompt = await this.responseEngine.buildResponsePrompt({
             route: selectedRoute,
             currentStep: nextStep,
-            rules: [...this.agent.getRules(), ...selectedRoute.getRules()],
-            prohibitions: [...this.agent.getProhibitions(), ...selectedRoute.getProhibitions()],
+            rules: selectedRoute.getRules(),
+            prohibitions: selectedRoute.getProhibitions(),
             directives: responseDirectives,
             history: historyEvents, // Use Event[] for buildResponsePrompt
             lastMessage: lastMessageText, // Use string for buildResponsePrompt
@@ -1841,7 +1835,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 // 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,
@@ -1991,17 +1985,17 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
 
                     // Collect ALL route fields (required + optional) from structured response
                     const allRouteFields = new Set<string>();
-                    
+
                     // Add route required fields
                     if (selectedRoute.requiredFields) {
                         selectedRoute.requiredFields.forEach(field => allRouteFields.add(String(field)));
                     }
-                    
+
                     // Add route optional fields
                     if (selectedRoute.optionalFields) {
                         selectedRoute.optionalFields.forEach(field => allRouteFields.add(String(field)));
                     }
-                    
+
                     // Also include current step's collect fields (in case they're not in route fields)
                     if (nextStep?.collect) {
                         nextStep.collect.forEach(field => allRouteFields.add(String(field)));
@@ -2081,7 +2075,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
             id: endStepSpec.id || END_ROUTE_ID,
             collect: endStepSpec.collect,
             requires: endStepSpec.requires,
-            prompt: endStepSpec.prompt || "Summarize what was accomplished and confirm completion based on the conversation history and collected data",
+            prompt: endStepSpec.prompt || "Send a brief, natural farewell message thanking the user. Do NOT list or mention any collected data, field names, or internal information.",
         });
 
         // Build response schema for completion (message only, no data collection)
@@ -2090,13 +2084,13 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
             properties: {
                 message: {
                     type: "string",
-                    description: "Completion message confirming what was accomplished",
+                    description: "A natural, warm farewell message for the user. Must NOT contain task names, field names, collected data, or any internal/technical information.",
                 },
             },
             required: ["message"],
             additionalProperties: false,
         };
-        
+
         const templateContext = createTemplateContext({ context, session, history: historyEvents });
 
         // Build completion response prompt using ResponseEngine
@@ -2105,8 +2099,8 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
             ...this.agent.getGuidelines().filter(g => !g.condition),
             ...selectedRoute.getGuidelines().filter(g => !g.condition),
         ];
-        let completitionPrompt =  "Summarize what was accomplished and confirm completion"
-        if(endStepSpec.prompt){
+        let completitionPrompt = "Send a brief, natural farewell message. Do NOT mention internal data or task details."
+        if (endStepSpec.prompt) {
             completitionPrompt = await render(endStepSpec.prompt, templateContext)
         }
 
@@ -2116,9 +2110,13 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
             rules: selectedRoute.getRules(),
             prohibitions: selectedRoute.getProhibitions(),
             directives: [
-                `Task completed: ${selectedRoute.title}`,
-                `Collected data: ${JSON.stringify(session.data, null, 2)}`,
-                "Do NOT ask for more information - the task is complete",
+                "The conversation task has been completed successfully",
+                "Generate a natural, friendly farewell message for the user",
+                "Do NOT mention task names, route names, collected data, field names, or any internal/technical information",
+                "Do NOT list or summarize the data you collected - the user already knows what they told you",
+                "Do NOT use words like 'tarefa', 'dados coletados', 'prospecção', 'concluída' or similar internal terms",
+                "Keep it brief, warm, and conversational - as if ending a natural conversation",
+                "Do NOT ask for more information - the conversation is ending",
                 completitionPrompt,
             ],
             history: historyEvents,
@@ -2197,7 +2195,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
             id: endStepSpec.id || END_ROUTE_ID,
             collect: endStepSpec.collect,
             requires: endStepSpec.requires,
-            prompt: endStepSpec.prompt || "Summarize what was accomplished and confirm completion based on the conversation history and collected data",
+            prompt: endStepSpec.prompt || "Send a brief, natural farewell message thanking the user. Do NOT list or mention any collected data, field names, or internal information.",
         });
 
         // Build response schema for completion
@@ -2443,7 +2441,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
 
         // Fallback to legacy resolution if ToolManager not available
         logger.warn(`[ResponseModal] ToolManager not available, using legacy tool resolution for: ${toolName}`);
-        
+
         // Check route-level tools first (if route provided)
         if (route) {
             const routeTool = route
@@ -2487,7 +2485,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
 
         // Fallback to legacy collection logic if ToolManager not available
         logger.warn(`[ResponseModal] ToolManager not available, using legacy tool collection`);
-        
+
         const availableTools = new Map<string, Tool<TContext, TData>>();
 
         // Add agent-level tools
@@ -2581,7 +2579,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 } else {
                     // Fallback to legacy resolution if ToolManager not available
                     logger.warn(`[ResponseModal] ToolManager not available, using legacy tool resolution for prepare/finalize: ${prepareOrFinalize}`);
-                    
+
                     const availableTools = new Map<string, Tool<TContext, TData>>();
 
                     // Add agent-level tools

package/src/core/RoutingEngine.ts

@@ -179,18 +179,17 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
       }
     }
 
-    // No candidates means route is likely complete or has no valid next steps
+    // No candidates means route has no valid next steps (edge case)
+    // Don't mark as complete based on data alone — only END_ROUTE completes a route
     if (candidates.length === 0) {
-      const dataComplete = route.isComplete(updatedSession.data || {});
       logger.debug(
-        `[RoutingEngine] Single-route: No valid steps found - ` +
-        `(data: ${dataComplete ? 'complete' : 'incomplete'}, marking as ${dataComplete ? 'complete' : 'incomplete'})`
+        `[RoutingEngine] Single-route: No valid candidate steps found`
       );
       return {
         selectedRoute,
         selectedStep: undefined,
         session: updatedSession,
-        isRouteComplete: dataComplete,
+        isRouteComplete: false,
         completedRoutes,
       };
     }
@@ -379,26 +378,9 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
     templateContext: TemplateContext<TContext, TData>
   ): Promise<CandidateStep<TContext, TData>[]> {
     const candidates: CandidateStep<TContext, TData>[] = [];
-    const data = templateContext.data || {};
-
-    // Check if all required fields are collected
-    const allRequiredFieldsCollected = route.isComplete(data);
 
     if (!currentStep) {
-      // Entering route for the first time
-
-      // If all required fields already collected, route is immediately complete
-      if (allRequiredFieldsCollected) {
-        logger.debug(
-          `[RoutingEngine] Route ${route.title} complete on entry: all required fields already collected`
-        );
-        // Return a completion marker - use initial step with completion flag
-        candidates.push({
-          step: route.initialStep,
-          isRouteComplete: true,
-        });
-        return candidates;
-      }
+      // Entering route for the first time — always start the step flow
 
       const initialStep = route.initialStep;
       const skipResult = await initialStep.evaluateSkipIf(templateContext);
@@ -437,68 +419,7 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
       return candidates;
     }
 
-    // Check if all required fields are now collected (may have been collected during this step)
-    if (allRequiredFieldsCollected) {
-      // Required fields are complete - check if we should continue for optional fields
-      const transitions = currentStep.getTransitions();
-      const optionalFieldCandidates: CandidateStep<TContext, TData>[] = [];
-
-      for (const transition of transitions) {
-        const target = transition;
-
-        // Check for END_ROUTE transition
-        if (target && target.id === END_ROUTE_ID) {
-          continue;
-        }
-
-        if (!target) continue;
-
-        // Check if this step collects only optional fields
-        const collectsOnlyOptional = target.collect && target.collect.length > 0 &&
-          target.collect.every(field =>
-            route.optionalFields?.includes(field)
-          );
-
-        if (collectsOnlyOptional) {
-          // This step collects optional fields - it's a candidate
-          const skipResult = await target.evaluateSkipIf(templateContext);
-          if (!skipResult.shouldSkip) {
-            optionalFieldCandidates.push({
-              step: target,
-              isRouteComplete: false,
-            });
-          }
-        }
-      }
-
-      // If we have optional field candidates, include them along with END_ROUTE option
-      if (optionalFieldCandidates.length > 0) {
-        logger.debug(
-          `[RoutingEngine] Required fields complete, but ${optionalFieldCandidates.length} optional field steps available`
-        );
-        // Add optional field steps as candidates
-        candidates.push(...optionalFieldCandidates);
-        // Also add END_ROUTE as a candidate (AI can choose to skip optional fields)
-        candidates.push({
-          step: currentStep,
-          isRouteComplete: true,
-        });
-        return candidates;
-      }
-
-      // No optional fields to collect - route is complete
-      logger.debug(
-        `[RoutingEngine] Route ${route.title} complete: all required fields collected, no optional fields remain`
-      );
-      return [
-        {
-          step: currentStep,
-          isRouteComplete: true,
-        },
-      ];
-    }
-
-    // Required fields not yet complete - continue normal step progression
+    // Continue normal step progression — routes complete via END_ROUTE, not via data collection
     const transitions = currentStep.getTransitions();
     let hasEndRoute = false;
 
@@ -690,12 +611,9 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
           // Don't include steps in routing if route is complete
           activeRouteSteps = undefined;
         } else if (candidates.length === 0) {
-          // No candidates - check if data is complete
-          const dataComplete = activeRoute.isComplete(updatedSession.data || {});
-          isRouteComplete = dataComplete;
+          // No candidates available — don't end route based on data alone
           logger.debug(
-            `[RoutingEngine] Route ${activeRoute.title} has no valid steps - ` +
-            `marking as ${isRouteComplete ? 'complete' : 'incomplete'}`
+            `[RoutingEngine] Route ${activeRoute.title} has no valid candidate steps`
           );
           activeRouteSteps = undefined;
         } else {
@@ -911,77 +829,77 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
    * @returns Route that should be prioritized for continuation
    */
   selectOptimalRoute(
-      routes: Route<TContext, TData>[],
-      data: Partial<TData>,
-      routeScores: Record<string, number>,
-      currentRouteId?: string
-    ): Route<TContext, TData> | undefined {
-      const completionStatus = this.getRouteCompletionStatus(routes, data);
-      const switchMargin = this.options?.routeSwitchMargin ?? 15;
-
-      // Create weighted scores combining AI intent scores with completion progress
-      const weightedScores: Array<{ route: Route<TContext, TData>; score: number }> = [];
-
-      for (const route of routes) {
-        const aiScore = routeScores[route.id] || 0;
-        const completionProgress = completionStatus.get(route.id) || 0;
-
-        // ALWAYS skip fully completed routes to prevent re-entering finished tasks
-        if (completionProgress >= 1.0) {
-          logger.debug(
-            `[RoutingEngine] Excluding completed route: ${route.title} (100% complete)`
-          );
-          continue;
-        }
+    routes: Route<TContext, TData>[],
+    data: Partial<TData>,
+    routeScores: Record<string, number>,
+    currentRouteId?: string
+  ): Route<TContext, TData> | undefined {
+    const completionStatus = this.getRouteCompletionStatus(routes, data);
+    const switchMargin = this.options?.routeSwitchMargin ?? 15;
 
-        // Boost partially complete routes that match user intent
-        let weightedScore = aiScore;
-        if (completionProgress > 0 && completionProgress < 1.0) {
-          weightedScore += (completionProgress * 20); // Up to 20 point boost
-        }
+    // Create weighted scores combining AI intent scores with completion progress
+    const weightedScores: Array<{ route: Route<TContext, TData>; score: number }> = [];
 
-        weightedScores.push({ route, score: weightedScore });
-      }
+    for (const route of routes) {
+      const aiScore = routeScores[route.id] || 0;
+      const completionProgress = completionStatus.get(route.id) || 0;
 
-      // Sort by weighted score descending
-      weightedScores.sort((a, b) => b.score - a.score);
+      // ALWAYS skip fully completed routes to prevent re-entering finished tasks
+      if (completionProgress >= 1.0) {
+        logger.debug(
+          `[RoutingEngine] Excluding completed route: ${route.title} (100% complete)`
+        );
+        continue;
+      }
 
-      if (weightedScores.length === 0) {
-        return undefined;
+      // Boost partially complete routes that match user intent
+      let weightedScore = aiScore;
+      if (completionProgress > 0 && completionProgress < 1.0) {
+        weightedScore += (completionProgress * 20); // Up to 20 point boost
       }
 
-      // Apply sticky routing: if there's a current route, only switch if the
-      // best alternative exceeds the current route's score by the configured margin
-      if (currentRouteId) {
-        const currentEntry = weightedScores.find(e => e.route.id === currentRouteId);
-        const bestEntry = weightedScores[0];
-
-        if (currentEntry && bestEntry.route.id !== currentRouteId) {
-          if (bestEntry.score < currentEntry.score + switchMargin) {
-            logger.debug(
-              `[RoutingEngine] Staying on current route: ${currentEntry.route.title} ` +
-              `(current: ${currentEntry.score}, best alternative: ${bestEntry.score}, ` +
-              `margin required: ${switchMargin})`
-            );
-            return currentEntry.route;
-          }
+      weightedScores.push({ route, score: weightedScore });
+    }
+
+    // Sort by weighted score descending
+    weightedScores.sort((a, b) => b.score - a.score);
+
+    if (weightedScores.length === 0) {
+      return undefined;
+    }
+
+    // Apply sticky routing: if there's a current route, only switch if the
+    // best alternative exceeds the current route's score by the configured margin
+    if (currentRouteId) {
+      const currentEntry = weightedScores.find(e => e.route.id === currentRouteId);
+      const bestEntry = weightedScores[0];
+
+      if (currentEntry && bestEntry.route.id !== currentRouteId) {
+        if (bestEntry.score < currentEntry.score + switchMargin) {
           logger.debug(
-            `[RoutingEngine] Switching route: ${currentEntry.route.title} → ${bestEntry.route.title} ` +
-            `(current: ${currentEntry.score}, alternative: ${bestEntry.score}, ` +
-            `margin: ${switchMargin})`
+            `[RoutingEngine] Staying on current route: ${currentEntry.route.title} ` +
+            `(current: ${currentEntry.score}, best alternative: ${bestEntry.score}, ` +
+            `margin required: ${switchMargin})`
           );
+          return currentEntry.route;
         }
+        logger.debug(
+          `[RoutingEngine] Switching route: ${currentEntry.route.title} → ${bestEntry.route.title} ` +
+          `(current: ${currentEntry.score}, alternative: ${bestEntry.score}, ` +
+          `margin: ${switchMargin})`
+        );
       }
-
-      logger.debug(
-        `[RoutingEngine] Selected optimal route: ${weightedScores[0].route.title} ` +
-        `(AI: ${routeScores[weightedScores[0].route.id]}, ` +
-        `Completion: ${(completionStatus.get(weightedScores[0].route.id) || 0) * 100}%, ` +
-        `Weighted: ${weightedScores[0].score})`
-      );
-      return weightedScores[0].route;
     }
 
+    logger.debug(
+      `[RoutingEngine] Selected optimal route: ${weightedScores[0].route.title} ` +
+      `(AI: ${routeScores[weightedScores[0].route.id]}, ` +
+      `Completion: ${(completionStatus.get(weightedScores[0].route.id) || 0) * 100}%, ` +
+      `Weighted: ${weightedScores[0].score})`
+    );
+    return weightedScores[0].route;
+  }
+
   /**
    * Build prompt for step selection within a single route
    * @private