@falai/agent 0.9.0 → 1.0.0

package/dist/{src/core → core}/RoutingEngine.js

@@ -1,47 +1,59 @@
 import { enterRoute, mergeCollected } from "../utils";
 import { PromptComposer } from "./PromptComposer";
-import { getLastMessageFromHistory } from "../utils/event";
-import { logger } from "../utils/logger";
-import { render } from "../utils/template";
 import { END_ROUTE_ID } from "../constants";
+import { createTemplateContext, getLastMessageFromHistory, logger } from "../utils";
 export class RoutingEngine {
     constructor(options) {
         this.options = options;
     }
     /**
-     * Optimized decision for single-route scenarios
-     * Skips route scoring and only does step selection
+     * Enter a route if not already in it, merging initial data
      * @private
      */
-    async decideSingleRouteStep(params) {
-        const { route, session, history, agentOptions, provider, context, signal } = params;
-        let updatedSession = session;
-        const selectedRoute = route;
-        // Check if this single route is complete
-        const completedRoutes = route.isComplete(session.data || {}) ? [route] : [];
-        // Enter route if not already in it
+    enterRouteIfNeeded(session, route) {
         if (!session.currentRoute || session.currentRoute.id !== route.id) {
-            updatedSession = enterRoute(session, route.id, route.title);
+            let updatedSession = enterRoute(session, route.id, route.title);
             if (route.initialData) {
                 updatedSession = mergeCollected(updatedSession, route.initialData);
-                logger.debug(`[RoutingEngine] Single-route: Merged initial data:`, route.initialData);
+                logger.debug(`[RoutingEngine] Merged initial data for route ${route.title}:`, route.initialData);
             }
-            logger.debug(`[RoutingEngine] Single-route: Entered route: ${route.title}`);
+            logger.debug(`[RoutingEngine] Entered route: ${route.title}`);
+            return updatedSession;
         }
-        // Get candidate steps
+        return session;
+    }
+    /**
+     * Optimized decision for single-route scenarios
+     * Skips route scoring and only does step selection
+     * @private
+     */
+    async decideSingleRouteStep(params) {
+        const { route, session, history, agentOptions, provider, context, signal } = params;
+        const selectedRoute = route;
+        // Enter route if not already in it (this may merge initial data)
+        const updatedSession = this.enterRouteIfNeeded(session, route);
+        // Check if this single route is complete (use updated session data)
+        const completedRoutes = route.isComplete(updatedSession.data || {}) ? [route] : [];
+        // Get candidate steps using new condition evaluation
+        const templateContext = createTemplateContext({
+            context,
+            session: updatedSession,
+            history,
+            data: updatedSession.data
+        });
         const currentStep = updatedSession.currentStep
             ? route.getStep(updatedSession.currentStep.id)
             : undefined;
-        const candidates = this.getCandidateSteps(route, currentStep, updatedSession.data || {});
+        const candidates = await this.getCandidateStepsWithConditions(route, currentStep, templateContext);
         if (candidates.length === 0) {
             logger.warn(`[RoutingEngine] Single-route: No valid steps found`);
             return { selectedRoute, session: updatedSession };
         }
-        // If only one candidate, check if route is complete
+        // If only one candidate, check if it's a completion marker
         if (candidates.length === 1) {
-            const isRouteComplete = candidates[0].isRouteComplete;
-            if (isRouteComplete) {
-                logger.debug(`[RoutingEngine] Single-route: Route complete - all data collected, END_ROUTE reached`);
+            const candidate = candidates[0];
+            if (candidate.isRouteComplete) {
+                logger.debug(`[RoutingEngine] Single-route: Route complete - all required fields collected or END_ROUTE reached`);
                 // Don't return a selectedStep when route is complete - there's no step to enter
                 return {
                     selectedRoute,
@@ -52,18 +64,39 @@ export class RoutingEngine {
                 };
             }
             else {
-                logger.debug(`[RoutingEngine] Single-route: Only one valid step: ${candidates[0].step.id}`);
+                logger.debug(`[RoutingEngine] Single-route: Only one valid step: ${candidate.step.id}`);
                 return {
                     selectedRoute,
-                    selectedStep: candidates[0].step,
+                    selectedStep: candidate.step,
                     session: updatedSession,
                     isRouteComplete: false,
                     completedRoutes,
                 };
             }
         }
+        // No candidates means route is likely complete or has no valid next steps
+        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'})`);
+            return {
+                selectedRoute,
+                selectedStep: undefined,
+                session: updatedSession,
+                isRouteComplete: dataComplete,
+                completedRoutes,
+            };
+        }
         // Multiple candidates - use AI to select best step
         const lastUserMessage = getLastMessageFromHistory(history);
+        // Collect AI context strings from step conditions
+        const stepConditionContext = [];
+        for (const candidate of candidates) {
+            const whenResult = await candidate.step.evaluateWhen(templateContext);
+            stepConditionContext.push(...whenResult.aiContextStrings);
+        }
+        // Check if any candidate is a completion marker (isRouteComplete = true)
+        const hasCompletionOption = candidates.some(c => c.isRouteComplete);
         const stepPrompt = await this.buildStepSelectionPrompt({
             route,
             currentStep,
@@ -74,8 +107,10 @@ export class RoutingEngine {
             agentOptions,
             context,
             session: updatedSession,
+            stepConditionContext,
+            includeEndRoute: hasCompletionOption,
         });
-        const stepSchema = this.buildStepSelectionSchema(candidates.map((c) => c.step));
+        const stepSchema = this.buildStepSelectionSchema(candidates.filter(c => !c.isRouteComplete).map((c) => c.step), hasCompletionOption);
         const stepResult = await provider.generateMessage({
             prompt: stepPrompt,
             history,
@@ -87,6 +122,19 @@ export class RoutingEngine {
             },
         });
         const selectedStepId = stepResult.structured?.selectedStepId;
+        // Check if AI selected END_ROUTE
+        if (selectedStepId === END_ROUTE_ID) {
+            logger.debug(`[RoutingEngine] Single-route: AI selected END_ROUTE - completing route`);
+            logger.debug(`[RoutingEngine] Single-route: Reasoning: ${stepResult.structured?.reasoning}`);
+            return {
+                selectedRoute,
+                selectedStep: undefined,
+                responseDirectives: stepResult.structured?.responseDirectives,
+                session: updatedSession,
+                isRouteComplete: true,
+                completedRoutes,
+            };
+        }
         const selectedStep = candidates.find((c) => c.step.id === selectedStepId);
         if (selectedStep) {
             logger.debug(`[RoutingEngine] Single-route: AI selected step: ${selectedStep.step.id}`);
@@ -104,16 +152,17 @@ export class RoutingEngine {
         };
     }
     /**
-     * Recursively traverse step chain to find first non-skipped step or END_ROUTE
+     * Recursively traverse step chain to find first non-skipped step or END_ROUTE using new condition evaluation
      * @private
      */
-    findFirstValidStepRecursive(currentStep, data, visited) {
+    async findFirstValidStepRecursiveWithConditions(currentStep, templateContext, visited) {
         // Prevent infinite loops
         if (visited.has(currentStep.id)) {
-            return {};
+            return { aiContextStrings: [] };
         }
         visited.add(currentStep.id);
         const transitions = currentStep.getTransitions();
+        const allAiContextStrings = [];
         for (const transition of transitions) {
             const target = transition;
             // Check for END_ROUTE transition
@@ -121,40 +170,69 @@ export class RoutingEngine {
                 // Found END_ROUTE - route is complete
                 return {
                     isRouteComplete: true,
+                    aiContextStrings: allAiContextStrings,
                 };
             }
             if (!target)
                 continue;
+            // Evaluate skipIf condition using new system
+            const skipResult = await target.evaluateSkipIf(templateContext);
+            allAiContextStrings.push(...skipResult.aiContextStrings);
             // If target should NOT be skipped, we found our step
-            if (!target.shouldSkip(data)) {
+            if (!skipResult.shouldSkip) {
                 logger.debug(`[RoutingEngine] Found valid step after skipping: ${target.id}`);
                 return {
                     step: target,
                     isRouteComplete: false,
+                    aiContextStrings: allAiContextStrings,
                 };
             }
             // Target should be skipped too - recurse deeper
             logger.debug(`[RoutingEngine] Skipping step ${target.id} (skipIf condition met), continuing traversal...`);
-            const result = this.findFirstValidStepRecursive(target, data, visited);
+            const result = await this.findFirstValidStepRecursiveWithConditions(target, templateContext, visited);
+            // Collect AI context from recursive call
+            if (result.aiContextStrings) {
+                allAiContextStrings.push(...result.aiContextStrings);
+            }
             // If we found something (a valid step or END_ROUTE), return it
             if (result.step || result.isRouteComplete) {
-                return result;
+                return {
+                    ...result,
+                    aiContextStrings: allAiContextStrings,
+                };
             }
         }
         // No valid steps or END_ROUTE found in this branch
-        return {};
+        return { aiContextStrings: allAiContextStrings };
     }
     /**
-     * Identify valid next candidate steps based on current step and collected data
+     * Identify valid next candidate steps using new condition evaluation system
      * Returns step with isRouteComplete flag if route is complete (all steps skipped + has END_ROUTE transition)
+     *
+     * NEW: Automatically completes route when all required fields are collected
      */
-    getCandidateSteps(route, currentStep, data) {
+    async getCandidateStepsWithConditions(route, currentStep, templateContext) {
         const candidates = [];
+        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;
+            }
             const initialStep = route.initialStep;
-            if (initialStep.shouldSkip(data)) {
+            const skipResult = await initialStep.evaluateSkipIf(templateContext);
+            if (skipResult.shouldSkip) {
                 // Initial step should be skipped - recursively traverse to find first non-skipped step or END_ROUTE
-                const result = this.findFirstValidStepRecursive(initialStep, data, new Set());
+                const result = await this.findFirstValidStepRecursiveWithConditions(initialStep, templateContext, new Set());
                 if (result.isRouteComplete) {
                     // All steps are skipped and we reached END_ROUTE
                     logger.debug(`[RoutingEngine] Route complete on entry: all steps skipped, END_ROUTE reached`);
@@ -180,6 +258,55 @@ export class RoutingEngine {
             }
             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 = [];
+            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
         const transitions = currentStep.getTransitions();
         let hasEndRoute = false;
         for (const transition of transitions) {
@@ -191,10 +318,11 @@ export class RoutingEngine {
             }
             if (!target)
                 continue;
-            if (target.shouldSkip(data)) {
+            const skipResult = await target.evaluateSkipIf(templateContext);
+            if (skipResult.shouldSkip) {
                 logger.debug(`[RoutingEngine] Skipping step ${target.id} (skipIf condition met)`);
                 // Recursively traverse to find next valid step or END_ROUTE
-                const result = this.findFirstValidStepRecursive(target, data, new Set([currentStep.id]) // Already visited current step
+                const result = await this.findFirstValidStepRecursiveWithConditions(target, templateContext, new Set([currentStep.id]) // Already visited current step
                 );
                 if (result.isRouteComplete) {
                     hasEndRoute = true;
@@ -227,7 +355,8 @@ export class RoutingEngine {
                 ];
             }
             // Otherwise, stay in current step if it's still valid
-            if (!currentStep.shouldSkip(data)) {
+            const currentSkipResult = await currentStep.evaluateSkipIf(templateContext);
+            if (!currentSkipResult.shouldSkip) {
                 candidates.push({
                     step: currentStep,
                     isRouteComplete: hasEndRoute || false,
@@ -271,38 +400,69 @@ export class RoutingEngine {
             };
         }
         const lastUserMessage = getLastMessageFromHistory(history);
+        const templateContext = createTemplateContext({
+            context,
+            session,
+            history,
+            data: session.data
+        });
+        // Apply route filtering with new condition evaluation system
+        const skipIfResult = await this.filterRoutesBySkipIf(routes, templateContext);
+        const whenResult = await this.filterRoutesByWhen(skipIfResult.eligibleRoutes, templateContext);
+        // Collect all AI context strings from route conditions
+        const routeConditionContext = [...skipIfResult.aiContextStrings, ...whenResult.aiContextStrings];
+        // Use filtered routes for further processing
+        const eligibleRoutes = whenResult.eligibleRoutes;
+        logger.debug(`[RoutingEngine] Route filtering: ${routes.length} total → ${skipIfResult.eligibleRoutes.length} after skipIf → ${eligibleRoutes.length} after when`);
         let activeRouteSteps;
         let activeRoute;
         let isRouteComplete = false;
+        let updatedSession = session;
         if (session.currentRoute) {
-            activeRoute = routes.find((r) => r.id === session.currentRoute?.id);
+            activeRoute = eligibleRoutes.find((r) => r.id === session.currentRoute?.id);
             if (activeRoute) {
                 const currentStep = session.currentStep
                     ? activeRoute.getStep(session.currentStep.id)
                     : undefined;
-                const candidates = this.getCandidateSteps(activeRoute, currentStep, session.data || {});
+                const activeTemplateContext = createTemplateContext({
+                    ...templateContext,
+                    session: updatedSession,
+                    data: updatedSession.data
+                });
+                const candidates = await this.getCandidateStepsWithConditions(activeRoute, currentStep, activeTemplateContext);
                 // Check if route is complete
+                // getCandidateStepsWithConditions now automatically handles completion when required fields are collected
                 if (candidates.length === 1 && candidates[0].isRouteComplete) {
                     isRouteComplete = true;
-                    logger.debug(`[RoutingEngine] Route ${activeRoute.title} is complete - all data collected`);
+                    logger.debug(`[RoutingEngine] Route ${activeRoute.title} is complete - all required fields collected or END_ROUTE reached`);
                     // 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;
+                    logger.debug(`[RoutingEngine] Route ${activeRoute.title} has no valid steps - ` +
+                        `marking as ${isRouteComplete ? 'complete' : 'incomplete'}`);
+                    activeRouteSteps = undefined;
+                }
                 else {
+                    // Multiple candidates or single non-complete candidate
                     activeRouteSteps = candidates.map((c) => c.step);
                     logger.debug(`[RoutingEngine] Found ${activeRouteSteps.length} candidate steps for active route`);
                 }
             }
         }
-        const routingSchema = this.buildDynamicRoutingSchema(routes, undefined, activeRouteSteps);
+        const routingSchema = this.buildDynamicRoutingSchema(eligibleRoutes, undefined, activeRouteSteps);
         const routingPrompt = await this.buildRoutingPrompt({
             history,
-            routes,
+            routes: eligibleRoutes,
             lastMessage: lastUserMessage,
             agentOptions,
             session,
             activeRouteSteps,
             context,
+            routeConditionContext, // Pass AI context strings from route conditions
         });
         const routingResult = await provider.generateMessage({
             prompt: routingPrompt,
@@ -317,19 +477,26 @@ export class RoutingEngine {
         let selectedRoute;
         let selectedStep;
         let responseDirectives;
-        let updatedSession = session;
         if (routingResult.structured?.routes) {
             // Use cross-route completion evaluation to select optimal route
-            const optimalRoute = this.selectOptimalRoute(routes, updatedSession.data || {}, routingResult.structured.routes);
-            // Fall back to traditional scoring if no optimal route found
-            selectedRoute = optimalRoute || (() => {
-                const decision = this.decideRouteFromScores({
-                    context: routingResult.structured.context,
-                    routes: routingResult.structured.routes,
-                    responseDirectives: routingResult.structured.responseDirectives,
-                });
-                return routes.find((r) => r.id === decision.routeId);
-            })();
+            const optimalRoute = this.selectOptimalRoute(eligibleRoutes, updatedSession.data || {}, routingResult.structured.routes);
+            // If no optimal route found, check why
+            if (!optimalRoute) {
+                if (eligibleRoutes.length === 0) {
+                    // No routes passed filtering
+                    logger.debug(`[RoutingEngine] No eligible routes available - all routes filtered out`);
+                    selectedRoute = undefined;
+                }
+                else {
+                    // Routes exist but selectOptimalRoute returned undefined
+                    // This means all routes are 100% complete
+                    logger.debug(`[RoutingEngine] No optimal route found - all ${eligibleRoutes.length} eligible routes are complete`);
+                    selectedRoute = undefined;
+                }
+            }
+            else {
+                selectedRoute = optimalRoute;
+            }
             responseDirectives = routingResult.structured.responseDirectives;
             if (selectedRoute === activeRoute &&
                 routingResult.structured.selectedStepId &&
@@ -342,15 +509,7 @@ export class RoutingEngine {
             }
             if (selectedRoute) {
                 logger.debug(`[RoutingEngine] Selected route: ${selectedRoute.title}`);
-                if (!session.currentRoute ||
-                    session.currentRoute.id !== selectedRoute.id) {
-                    updatedSession = enterRoute(session, selectedRoute.id, selectedRoute.title);
-                    if (selectedRoute.initialData) {
-                        updatedSession = mergeCollected(updatedSession, selectedRoute.initialData);
-                        logger.debug(`[RoutingEngine] Merged initial data:`, selectedRoute.initialData);
-                    }
-                    logger.debug(`[RoutingEngine] Entered route: ${selectedRoute.title}`);
-                }
+                updatedSession = this.enterRouteIfNeeded(updatedSession, selectedRoute);
             }
         }
         return {
@@ -362,6 +521,52 @@ export class RoutingEngine {
             completedRoutes,
         };
     }
+    /**
+     * Filter routes based on skipIf conditions
+     * @param routes - All available routes
+     * @param templateContext - Context for condition evaluation
+     * @returns Object with eligible routes and collected AI context strings
+     */
+    async filterRoutesBySkipIf(routes, templateContext) {
+        const eligibleRoutes = [];
+        const aiContextStrings = [];
+        for (const route of routes) {
+            const skipResult = await route.evaluateSkipIf(templateContext);
+            // Collect AI context strings from skipIf conditions
+            aiContextStrings.push(...skipResult.aiContextStrings);
+            // If route should not be skipped, it's eligible
+            if (!skipResult.programmaticResult) {
+                eligibleRoutes.push(route);
+            }
+            else {
+                logger.debug(`[RoutingEngine] Skipping route ${route.title} (skipIf condition met)`);
+            }
+        }
+        return { eligibleRoutes, aiContextStrings };
+    }
+    /**
+     * Filter routes based on when conditions
+     * @param routes - Routes that passed skipIf filtering
+     * @param templateContext - Context for condition evaluation
+     * @returns Object with eligible routes and collected AI context strings
+     */
+    async filterRoutesByWhen(routes, templateContext) {
+        const eligibleRoutes = [];
+        const aiContextStrings = [];
+        for (const route of routes) {
+            const whenResult = await route.evaluateWhen(templateContext);
+            // Collect AI context strings from when conditions
+            aiContextStrings.push(...whenResult.aiContextStrings);
+            // If route has no programmatic conditions or they evaluate to true, it's eligible
+            if (!whenResult.hasProgrammaticConditions || whenResult.programmaticResult) {
+                eligibleRoutes.push(route);
+            }
+            else {
+                logger.debug(`[RoutingEngine] Route ${route.title} not eligible (when condition not met)`);
+            }
+        }
+        return { eligibleRoutes, aiContextStrings };
+    }
     /**
      * Evaluate all routes for completion based on collected data
      * @param routes - All available routes
@@ -388,6 +593,7 @@ export class RoutingEngine {
     /**
      * Find the best route to continue based on completion status and user intent
      * Prioritizes routes that are partially complete but not finished
+     * IMPORTANT: Completed routes are excluded to prevent re-entering finished tasks
      * @param routes - All available routes
      * @param data - Currently collected agent-level data
      * @param routeScores - AI-generated route scores from routing decision
@@ -400,8 +606,10 @@ export class RoutingEngine {
         for (const route of routes) {
             const aiScore = routeScores[route.id] || 0;
             const completionProgress = completionStatus.get(route.id) || 0;
-            // Skip fully completed routes unless they have very high AI scores
-            if (completionProgress >= 1.0 && aiScore < 80) {
+            // ALWAYS skip fully completed routes to prevent re-entering finished tasks
+            // Users should not be forced back into completed routes
+            if (completionProgress >= 1.0) {
+                logger.debug(`[RoutingEngine] Excluding completed route: ${route.title} (100% complete)`);
                 continue;
             }
             // Boost partially complete routes that match user intent
@@ -428,8 +636,8 @@ export class RoutingEngine {
      * @private
      */
     async buildStepSelectionPrompt(params) {
-        const { route, currentStep, candidates, data, history, lastMessage, agentOptions, context, session, } = params;
-        const templateContext = { context, session, history };
+        const { route, currentStep, candidates, data, history, lastMessage, agentOptions, context, session, stepConditionContext, includeEndRoute = false, } = params;
+        const templateContext = createTemplateContext({ context, session, history });
         const pc = new PromptComposer(templateContext);
         // Add agent metadata
         if (agentOptions) {
@@ -454,7 +662,7 @@ export class RoutingEngine {
         // Add conversation history
         await pc.addInteractionHistory(history);
         await pc.addLastMessage(lastMessage);
-        // Add candidate steps
+        // Add candidate steps with condition context
         const stepDescriptions = [];
         for (const candidate of candidates) {
             const idx = candidates.indexOf(candidate);
@@ -462,9 +670,15 @@ export class RoutingEngine {
                 `${idx + 1}. Step ID: ${candidate.step.id}`,
                 `   Description: ${candidate.step.description || "N/A"}`,
             ];
+            // Add when condition context
             if (candidate.step.when) {
-                const renderedWhen = await render(candidate.step.when, templateContext);
-                parts.push(`   When this step should be completed: ${renderedWhen}`);
+                const whenResult = await candidate.step.evaluateWhen(templateContext);
+                if (whenResult.aiContextStrings.length > 0) {
+                    parts.push(`   When conditions: ${whenResult.aiContextStrings.join(", ")}`);
+                }
+                else if (typeof candidate.step.when === 'string') {
+                    parts.push(`   When this step should be completed: ${candidate.step.when}`);
+                }
             }
             if (candidate.step.requires && candidate.step.requires.length > 0) {
                 parts.push(`   Required Data: ${candidate.step.requires.join(", ")}`);
@@ -475,8 +689,18 @@ export class RoutingEngine {
             stepDescriptions.push(parts.join("\n"));
         }
         await pc.addInstruction(`Available Steps to Transition To:\n${stepDescriptions.join("\n\n")}`);
+        // Add step condition context if available
+        if (stepConditionContext && stepConditionContext.length > 0) {
+            await pc.addInstruction([
+                "",
+                "Additional step context from conditions:",
+                ...stepConditionContext.map(ctx => `- ${ctx}`),
+                "",
+                "Consider this context when selecting the most appropriate step.",
+            ].join("\n"));
+        }
         // Add decision prompt
-        await pc.addInstruction([
+        const decisionRules = [
             "Task: Decide which step to transition to based on:",
             "1. The user's current message and intent",
             "2. The conversation history and context",
@@ -489,16 +713,24 @@ export class RoutingEngine {
             "- If a step requires data we don't have, consider if we should collect it now",
             "- Choose the step that makes the most sense for moving the conversation forward",
             "- Steps with skipIf conditions that are met have already been filtered out",
-            "",
-            "Return ONLY JSON matching the provided schema.",
-        ].join("\n"));
+        ];
+        if (includeEndRoute) {
+            decisionRules.push("", `- You can select '${END_ROUTE_ID}' to complete this route if:`, "  * All required data has been collected", "  * The user's intent suggests they're done with this task", "  * No further steps are needed to fulfill the user's request");
+        }
+        decisionRules.push("", "Return ONLY JSON matching the provided schema.");
+        await pc.addInstruction(decisionRules.join("\n"));
         return pc.build();
     }
     /**
      * Build schema for step selection
      * @private
      */
-    buildStepSelectionSchema(validSteps) {
+    buildStepSelectionSchema(validSteps, includeEndRoute = false) {
+        const stepIds = validSteps.map((s) => s.id);
+        // Add END_ROUTE as an option if requested (when required fields are complete)
+        if (includeEndRoute) {
+            stepIds.push(END_ROUTE_ID);
+        }
         return {
             description: "Step transition decision based on conversation context and collected data",
             type: "object",
@@ -511,8 +743,10 @@ export class RoutingEngine {
                 selectedStepId: {
                     type: "string",
                     nullable: false,
-                    description: "The ID of the selected step to transition to",
-                    enum: validSteps.map((s) => s.id),
+                    description: includeEndRoute
+                        ? `The ID of the selected step to transition to, or '${END_ROUTE_ID}' to complete the route`
+                        : "The ID of the selected step to transition to",
+                    enum: stepIds,
                 },
                 responseDirectives: {
                     type: "array",
@@ -588,8 +822,8 @@ export class RoutingEngine {
         return base;
     }
     async buildRoutingPrompt(params) {
-        const { history, routes, lastMessage, agentOptions, session, activeRouteSteps, context, } = params;
-        const templateContext = { context, session, history };
+        const { history, routes, lastMessage, agentOptions, session, activeRouteSteps, context, routeConditionContext, } = params;
+        const templateContext = createTemplateContext({ context, session, history });
         const pc = new PromptComposer(templateContext);
         if (agentOptions) {
             await pc.addAgentMeta(agentOptions);
@@ -641,15 +875,23 @@ export class RoutingEngine {
                     "",
                     "Available steps in active route (choose one to transition to):",
                 ];
+                const activeStepConditionContext = [];
                 for (const step of activeRouteSteps) {
                     const idx = activeRouteSteps.indexOf(step);
                     stepInfo.push(`${idx + 1}. Step: ${step.id}`);
                     if (step.description) {
                         stepInfo.push(`   Description: ${step.description}`);
                     }
-                    const renderedWhen = await render(step.when, templateContext);
+                    // Collect AI context from step conditions
                     if (step.when) {
-                        stepInfo.push(`   When this step should be completed: ${renderedWhen}`);
+                        const whenResult = await step.evaluateWhen(templateContext);
+                        if (whenResult.aiContextStrings.length > 0) {
+                            stepInfo.push(`   When conditions: ${whenResult.aiContextStrings.join(", ")}`);
+                            activeStepConditionContext.push(...whenResult.aiContextStrings);
+                        }
+                        else if (typeof step.when === 'string') {
+                            stepInfo.push(`   When this step should be completed: ${step.when}`);
+                        }
                     }
                     if (step.requires && step.requires.length > 0) {
                         stepInfo.push(`   Required data: ${step.requires.join(", ")}`);
@@ -665,11 +907,31 @@ export class RoutingEngine {
                 stepInfo.push("- The logical next step in the conversation");
                 stepInfo.push("- Whether conditions for steps are met");
                 await pc.addInstruction(stepInfo.join("\n"));
+                // Add active step condition context if available
+                if (activeStepConditionContext.length > 0) {
+                    await pc.addInstruction([
+                        "",
+                        "Additional context from step conditions:",
+                        ...activeStepConditionContext.map(ctx => `- ${ctx}`),
+                        "",
+                        "Use this context to inform your step selection decision.",
+                    ].join("\n"));
+                }
             }
         }
         await pc.addInteractionHistory(history);
         await pc.addLastMessage(lastMessage);
         await pc.addRoutingOverview(routes);
+        // Add route condition context if available
+        if (routeConditionContext && routeConditionContext.length > 0) {
+            await pc.addInstruction([
+                "",
+                "Additional routing context from route conditions:",
+                ...routeConditionContext.map(ctx => `- ${ctx}`),
+                "",
+                "Consider this context when scoring routes for relevance.",
+            ].join("\n"));
+        }
         await pc.addInstruction([
             "Scoring rules:",
             "- 90-100: explicit keywords + clear intent",