@falai/agent 0.1.0-alpha2

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

@@ -0,0 +1,961 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RoutingEngine = void 0;
+const utils_1 = require("../utils");
+const PromptComposer_1 = require("./PromptComposer");
+const constants_1 = require("../constants");
+const utils_2 = require("../utils");
+class RoutingEngine {
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * Enter a route if not already in it, merging initial data
+     * @private
+     */
+    enterRouteIfNeeded(session, route) {
+        if (!session.currentRoute || session.currentRoute.id !== route.id) {
+            let updatedSession = (0, utils_1.enterRoute)(session, route.id, route.title);
+            if (route.initialData) {
+                updatedSession = (0, utils_1.mergeCollected)(updatedSession, route.initialData);
+                utils_2.logger.debug(`[RoutingEngine] Merged initial data for route ${route.title}:`, route.initialData);
+            }
+            utils_2.logger.debug(`[RoutingEngine] Entered route: ${route.title}`);
+            return updatedSession;
+        }
+        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 = (0, utils_2.createTemplateContext)({
+            context,
+            session: updatedSession,
+            history,
+            data: updatedSession.data
+        });
+        const currentStep = updatedSession.currentStep
+            ? route.getStep(updatedSession.currentStep.id)
+            : undefined;
+        const candidates = await this.getCandidateStepsWithConditions(route, currentStep, templateContext);
+        if (candidates.length === 0) {
+            utils_2.logger.warn(`[RoutingEngine] Single-route: No valid steps found`);
+            return { selectedRoute, session: updatedSession };
+        }
+        // If only one candidate, check if it's a completion marker
+        if (candidates.length === 1) {
+            const candidate = candidates[0];
+            if (candidate.isRouteComplete) {
+                utils_2.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,
+                    selectedStep: undefined,
+                    session: updatedSession,
+                    isRouteComplete: true,
+                    completedRoutes,
+                };
+            }
+            else {
+                utils_2.logger.debug(`[RoutingEngine] Single-route: Only one valid step: ${candidate.step.id}`);
+                return {
+                    selectedRoute,
+                    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 || {});
+            utils_2.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 = (0, utils_2.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,
+            candidates,
+            data: updatedSession.data || {},
+            history,
+            lastMessage: lastUserMessage,
+            agentOptions,
+            context,
+            session: updatedSession,
+            stepConditionContext,
+            includeEndRoute: hasCompletionOption,
+        });
+        const stepSchema = this.buildStepSelectionSchema(candidates.filter(c => !c.isRouteComplete).map((c) => c.step), hasCompletionOption);
+        const stepResult = await provider.generateMessage({
+            prompt: stepPrompt,
+            history,
+            context,
+            signal,
+            parameters: {
+                jsonSchema: stepSchema,
+                schemaName: "step_selection",
+            },
+        });
+        const selectedStepId = stepResult.structured?.selectedStepId;
+        // Check if AI selected END_ROUTE
+        if (selectedStepId === constants_1.END_ROUTE_ID) {
+            utils_2.logger.debug(`[RoutingEngine] Single-route: AI selected END_ROUTE - completing route`);
+            utils_2.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) {
+            utils_2.logger.debug(`[RoutingEngine] Single-route: AI selected step: ${selectedStep.step.id}`);
+            utils_2.logger.debug(`[RoutingEngine] Single-route: Reasoning: ${stepResult.structured?.reasoning}`);
+        }
+        else {
+            utils_2.logger.warn(`[RoutingEngine] Single-route: Invalid step ID returned, using first candidate`);
+        }
+        return {
+            selectedRoute,
+            selectedStep: selectedStep?.step || candidates[0].step,
+            responseDirectives: stepResult.structured?.responseDirectives,
+            session: updatedSession,
+            completedRoutes,
+        };
+    }
+    /**
+     * Recursively traverse step chain to find first non-skipped step or END_ROUTE using new condition evaluation
+     * @private
+     */
+    async findFirstValidStepRecursiveWithConditions(currentStep, templateContext, visited) {
+        // Prevent infinite loops
+        if (visited.has(currentStep.id)) {
+            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
+            if (target && target.id === constants_1.END_ROUTE_ID) {
+                // 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 (!skipResult.shouldSkip) {
+                utils_2.logger.debug(`[RoutingEngine] Found valid step after skipping: ${target.id}`);
+                return {
+                    step: target,
+                    isRouteComplete: false,
+                    aiContextStrings: allAiContextStrings,
+                };
+            }
+            // Target should be skipped too - recurse deeper
+            utils_2.logger.debug(`[RoutingEngine] Skipping step ${target.id} (skipIf condition met), continuing traversal...`);
+            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,
+                    aiContextStrings: allAiContextStrings,
+                };
+            }
+        }
+        // No valid steps or END_ROUTE found in this branch
+        return { aiContextStrings: allAiContextStrings };
+    }
+    /**
+     * 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
+     */
+    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) {
+                utils_2.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;
+            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 = await this.findFirstValidStepRecursiveWithConditions(initialStep, templateContext, new Set());
+                if (result.isRouteComplete) {
+                    // All steps are skipped and we reached END_ROUTE
+                    utils_2.logger.debug(`[RoutingEngine] Route complete on entry: all steps skipped, END_ROUTE reached`);
+                    candidates.push({
+                        step: initialStep,
+                        isRouteComplete: true,
+                    });
+                }
+                else if (result.step) {
+                    // Found a non-skipped step
+                    candidates.push({
+                        step: result.step,
+                        isRouteComplete: result.isRouteComplete || false,
+                    });
+                }
+                // If no step found and not complete, fall through to return empty candidates
+            }
+            else {
+                candidates.push({
+                    step: initialStep,
+                    isRouteComplete: false,
+                });
+            }
+            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 === constants_1.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) {
+                utils_2.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
+            utils_2.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) {
+            const target = transition;
+            // Check for END_ROUTE transition (no target step)
+            if (target && target.id === constants_1.END_ROUTE_ID) {
+                hasEndRoute = true;
+                continue;
+            }
+            if (!target)
+                continue;
+            const skipResult = await target.evaluateSkipIf(templateContext);
+            if (skipResult.shouldSkip) {
+                utils_2.logger.debug(`[RoutingEngine] Skipping step ${target.id} (skipIf condition met)`);
+                // Recursively traverse to find next valid step or END_ROUTE
+                const result = await this.findFirstValidStepRecursiveWithConditions(target, templateContext, new Set([currentStep.id]) // Already visited current step
+                );
+                if (result.isRouteComplete) {
+                    hasEndRoute = true;
+                }
+                else if (result.step) {
+                    // Found a non-skipped step deeper in the chain
+                    candidates.push({
+                        step: result.step,
+                        isRouteComplete: result.isRouteComplete || false,
+                    });
+                }
+                continue;
+            }
+            candidates.push({
+                step: target,
+                isRouteComplete: hasEndRoute || false,
+            });
+        }
+        // If no valid candidates found
+        if (candidates.length === 0) {
+            // If current step has END_ROUTE transition, the route is complete
+            if (hasEndRoute) {
+                utils_2.logger.debug(`[RoutingEngine] Route complete: all steps processed, END_ROUTE reached`);
+                // Return current step with completion flag
+                return [
+                    {
+                        step: currentStep,
+                        isRouteComplete: true,
+                    },
+                ];
+            }
+            // Otherwise, stay in current step if it's still valid
+            const currentSkipResult = await currentStep.evaluateSkipIf(templateContext);
+            if (!currentSkipResult.shouldSkip) {
+                candidates.push({
+                    step: currentStep,
+                    isRouteComplete: hasEndRoute || false,
+                });
+            }
+        }
+        return candidates;
+    }
+    /**
+     * Full routing orchestration: builds prompt and schema, calls AI, selects route/step,
+     * and updates the session (including initialData merge when entering a new route).
+     *
+     * OPTIMIZATION: If there's only 1 route, skips route scoring and only does step selection.
+     * CROSS-ROUTE COMPLETION: Evaluates all routes for completion based on collected data.
+     */
+    async decideRouteAndStep(params) {
+        const { routes, session, history, agentOptions, provider, context, signal, } = params;
+        if (routes.length === 0) {
+            return { session };
+        }
+        // CROSS-ROUTE COMPLETION EVALUATION: Check all routes for completion
+        const completedRoutes = this.evaluateRouteCompletions(routes, session.data || {});
+        // Log completed routes
+        if (completedRoutes.length > 0) {
+            utils_2.logger.debug(`[RoutingEngine] Found ${completedRoutes.length} completed routes: ${completedRoutes.map(r => r.title).join(', ')}`);
+        }
+        // OPTIMIZATION: Single route - skip route scoring, only do step selection
+        if (routes.length === 1) {
+            const result = await this.decideSingleRouteStep({
+                route: routes[0],
+                session,
+                history,
+                agentOptions,
+                provider,
+                context,
+                signal,
+            });
+            return {
+                ...result,
+                completedRoutes,
+            };
+        }
+        const lastUserMessage = (0, utils_2.getLastMessageFromHistory)(history);
+        const templateContext = (0, utils_2.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;
+        utils_2.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 = eligibleRoutes.find((r) => r.id === session.currentRoute?.id);
+            if (activeRoute) {
+                const currentStep = session.currentStep
+                    ? activeRoute.getStep(session.currentStep.id)
+                    : undefined;
+                const activeTemplateContext = (0, utils_2.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;
+                    utils_2.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;
+                    utils_2.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);
+                    utils_2.logger.debug(`[RoutingEngine] Found ${activeRouteSteps.length} candidate steps for active route`);
+                }
+            }
+        }
+        const routingSchema = this.buildDynamicRoutingSchema(eligibleRoutes, undefined, activeRouteSteps);
+        const routingPrompt = await this.buildRoutingPrompt({
+            history,
+            routes: eligibleRoutes,
+            lastMessage: lastUserMessage,
+            agentOptions,
+            session,
+            activeRouteSteps,
+            context,
+            routeConditionContext, // Pass AI context strings from route conditions
+        });
+        const routingResult = await provider.generateMessage({
+            prompt: routingPrompt,
+            history,
+            context,
+            signal,
+            parameters: {
+                jsonSchema: routingSchema,
+                schemaName: "routing_output",
+            },
+        });
+        let selectedRoute;
+        let selectedStep;
+        let responseDirectives;
+        if (routingResult.structured?.routes) {
+            // Use cross-route completion evaluation to select optimal route
+            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
+                    utils_2.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
+                    utils_2.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 &&
+                activeRoute) {
+                selectedStep = activeRoute.getStep(routingResult.structured.selectedStepId);
+                if (selectedStep) {
+                    utils_2.logger.debug(`[RoutingEngine] AI selected step: ${selectedStep.id} in active route`);
+                    utils_2.logger.debug(`[RoutingEngine] Step reasoning: ${routingResult.structured.stepReasoning}`);
+                }
+            }
+            if (selectedRoute) {
+                utils_2.logger.debug(`[RoutingEngine] Selected route: ${selectedRoute.title}`);
+                updatedSession = this.enterRouteIfNeeded(updatedSession, selectedRoute);
+            }
+        }
+        return {
+            selectedRoute,
+            selectedStep,
+            responseDirectives,
+            session: updatedSession,
+            isRouteComplete,
+            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 {
+                utils_2.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 {
+                utils_2.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
+     * @param data - Currently collected agent-level data
+     * @returns Array of routes that are complete
+     */
+    evaluateRouteCompletions(routes, data) {
+        return routes.filter(route => route.isComplete(data));
+    }
+    /**
+     * Get completion status for all routes
+     * @param routes - All available routes
+     * @param data - Currently collected agent-level data
+     * @returns Map of route ID to completion progress (0-1)
+     */
+    getRouteCompletionStatus(routes, data) {
+        const completionStatus = new Map();
+        for (const route of routes) {
+            const progress = route.getCompletionProgress(data);
+            completionStatus.set(route.id, progress);
+        }
+        return completionStatus;
+    }
+    /**
+     * 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
+     * @returns Route that should be prioritized for continuation
+     */
+    selectOptimalRoute(routes, data, routeScores) {
+        const completionStatus = this.getRouteCompletionStatus(routes, data);
+        // Create weighted scores combining AI intent scores with completion progress
+        const weightedScores = [];
+        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
+            // Users should not be forced back into completed routes
+            if (completionProgress >= 1.0) {
+                utils_2.logger.debug(`[RoutingEngine] Excluding completed route: ${route.title} (100% complete)`);
+                continue;
+            }
+            // Boost partially complete routes that match user intent
+            let weightedScore = aiScore;
+            if (completionProgress > 0 && completionProgress < 1.0) {
+                // Boost score for partially complete routes
+                weightedScore += (completionProgress * 20); // Up to 20 point boost
+            }
+            weightedScores.push({ route, score: weightedScore });
+        }
+        // Sort by weighted score and return the best option
+        weightedScores.sort((a, b) => b.score - a.score);
+        if (weightedScores.length > 0) {
+            utils_2.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;
+        }
+        return undefined;
+    }
+    /**
+     * Build prompt for step selection within a single route
+     * @private
+     */
+    async buildStepSelectionPrompt(params) {
+        const { route, currentStep, candidates, data, history, lastMessage, agentOptions, context, session, stepConditionContext, includeEndRoute = false, } = params;
+        const templateContext = (0, utils_2.createTemplateContext)({ context, session, history });
+        const pc = new PromptComposer_1.PromptComposer(templateContext);
+        // Add agent metadata
+        if (agentOptions) {
+            await pc.addAgentMeta(agentOptions);
+        }
+        // Add route context
+        await pc.addInstruction(`Active Route: ${route.title}\nDescription: ${route.description || "N/A"}`);
+        // Add current step context
+        if (currentStep) {
+            await pc.addInstruction(`Current Step: ${currentStep.id}\nDescription: ${currentStep.description || "N/A"}`);
+        }
+        else {
+            await pc.addInstruction("Current Step: None (entering route)");
+        }
+        // Add collected data context
+        if (Object.keys(data).length > 0) {
+            await pc.addInstruction(`Collected Data So Far:\n${JSON.stringify(data, null, 2)}`);
+        }
+        else {
+            await pc.addInstruction("Collected Data: None yet");
+        }
+        // Add conversation history
+        await pc.addInteractionHistory(history);
+        await pc.addLastMessage(lastMessage);
+        // Add candidate steps with condition context
+        const stepDescriptions = [];
+        for (const candidate of candidates) {
+            const idx = candidates.indexOf(candidate);
+            const parts = [
+                `${idx + 1}. Step ID: ${candidate.step.id}`,
+                `   Description: ${candidate.step.description || "N/A"}`,
+            ];
+            // Add when condition context
+            if (candidate.step.when) {
+                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(", ")}`);
+            }
+            if (candidate.step.collect && candidate.step.collect.length > 0) {
+                parts.push(`   Collects: ${candidate.step.collect.join(", ")}`);
+            }
+            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
+        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",
+            "3. The collected data we already have",
+            "4. The conditions and requirements of each step",
+            "5. The logical flow of the conversation",
+            "",
+            "Rules:",
+            "- If a step has a condition, evaluate whether it's met based on context",
+            "- 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",
+        ];
+        if (includeEndRoute) {
+            decisionRules.push("", `- You can select '${constants_1.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, 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(constants_1.END_ROUTE_ID);
+        }
+        return {
+            description: "Step transition decision based on conversation context and collected data",
+            type: "object",
+            properties: {
+                reasoning: {
+                    type: "string",
+                    nullable: false,
+                    description: "Brief explanation of why this step was selected",
+                },
+                selectedStepId: {
+                    type: "string",
+                    nullable: false,
+                    description: includeEndRoute
+                        ? `The ID of the selected step to transition to, or '${constants_1.END_ROUTE_ID}' to complete the route`
+                        : "The ID of the selected step to transition to",
+                    enum: stepIds,
+                },
+                responseDirectives: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Optional bullet points the response should address (concise)",
+                },
+            },
+            required: ["reasoning", "selectedStepId"],
+            additionalProperties: false,
+        };
+    }
+    buildDynamicRoutingSchema(routes, extrasSchema, activeRouteSteps) {
+        const routeIds = routes.map((r) => r.id);
+        const routeProperties = {};
+        for (const id of routeIds) {
+            routeProperties[id] = {
+                type: "number",
+                nullable: false,
+                description: `Score for route ${id} based on direct evidence, context and semantic fit (0-100)`,
+                minimum: 0,
+                maximum: 100,
+            };
+        }
+        const base = {
+            description: "Full intent analysis: score ALL available routes (0-100) using evidence and context",
+            type: "object",
+            properties: {
+                context: {
+                    type: "string",
+                    nullable: false,
+                    description: "Brief summary of the user's intent/context",
+                },
+                routes: {
+                    type: "object",
+                    properties: routeProperties,
+                    required: routeIds,
+                    nullable: false,
+                    description: "Mapping of routeId to score (0-100)",
+                },
+                responseDirectives: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Optional bullet points the response should address (concise)",
+                },
+            },
+            required: ["context", "routes"],
+            additionalProperties: false,
+        };
+        // Add step selection fields if there's an active route with steps
+        if (activeRouteSteps && activeRouteSteps.length > 0) {
+            base.properties = base.properties || {};
+            base.properties.selectedStepId = {
+                type: "string",
+                nullable: false,
+                description: "The step ID to transition to within the active route (required if continuing in current route)",
+                enum: activeRouteSteps.map((s) => s.id),
+            };
+            base.properties.stepReasoning = {
+                type: "string",
+                nullable: false,
+                description: "Brief explanation of why this step was selected",
+            };
+            base.required = [
+                ...(base.required || []),
+                "selectedStepId",
+                "stepReasoning",
+            ];
+        }
+        if (extrasSchema) {
+            base.properties = base.properties || {};
+            base.properties.extractions = extrasSchema;
+        }
+        return base;
+    }
+    async buildRoutingPrompt(params) {
+        const { history, routes, lastMessage, agentOptions, session, activeRouteSteps, context, routeConditionContext, } = params;
+        const templateContext = (0, utils_2.createTemplateContext)({ context, session, history });
+        const pc = new PromptComposer_1.PromptComposer(templateContext);
+        if (agentOptions) {
+            await pc.addAgentMeta(agentOptions);
+        }
+        await pc.addInstruction("Task: Intent analysis and route scoring (0-100). Score ALL listed routes.");
+        // Add session context if available
+        if (session?.currentRoute) {
+            const sessionInfo = [
+                "Current conversation context:",
+                `- Active route: ${session.currentRoute.title} (${session.currentRoute.id})`,
+            ];
+            if (session.currentStep) {
+                sessionInfo.push(`- Current step: ${session.currentStep.id}`);
+                if (session.currentStep.description) {
+                    sessionInfo.push(`  "${session.currentStep.description}"`);
+                }
+            }
+            if (session.data && Object.keys(session.data).length > 0) {
+                sessionInfo.push(`- Collected data: ${JSON.stringify(session.data)}`);
+            }
+            sessionInfo.push("Note: User is mid-conversation. They may want to continue current route or switch to a new one based on their intent.");
+            await pc.addInstruction(sessionInfo.join("\n"));
+            // Add cross-route completion status
+            const completionStatus = this.getRouteCompletionStatus(routes, session.data || {});
+            const completedRoutes = this.evaluateRouteCompletions(routes, session.data || {});
+            if (completionStatus.size > 0) {
+                const statusInfo = [
+                    "",
+                    "Route completion status based on collected data:",
+                ];
+                for (const route of routes) {
+                    const progress = completionStatus.get(route.id) || 0;
+                    const isComplete = completedRoutes.includes(route);
+                    const progressPercent = Math.round(progress * 100);
+                    statusInfo.push(`- ${route.title}: ${progressPercent}% complete${isComplete ? ' ✓ COMPLETE' : ''}`);
+                    if (!isComplete && route.requiredFields) {
+                        const missingFields = route.getMissingRequiredFields(session.data || {});
+                        if (missingFields.length > 0) {
+                            statusInfo.push(`  Missing: ${missingFields.join(', ')}`);
+                        }
+                    }
+                }
+                statusInfo.push("", "Consider route completion status when scoring. Partially complete routes may be good candidates for continuation.");
+                await pc.addInstruction(statusInfo.join("\n"));
+            }
+            // Add available steps for the active route
+            if (activeRouteSteps && activeRouteSteps.length > 0) {
+                const stepInfo = [
+                    "",
+                    "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}`);
+                    }
+                    // Collect AI context from step conditions
+                    if (step.when) {
+                        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(", ")}`);
+                    }
+                    if (step.collect && step.collect.length > 0) {
+                        stepInfo.push(`   Will collect: ${step.collect.join(", ")}`);
+                    }
+                }
+                stepInfo.push("");
+                stepInfo.push("IMPORTANT: You MUST select a step to transition to. Evaluate which step makes the most sense based on:");
+                stepInfo.push("- The conversation flow and what's been collected");
+                stepInfo.push("- What data is still needed vs already present");
+                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",
+            "- 70-89: strong contextual evidence + relevant keywords",
+            "- 50-69: moderate relevance",
+            "- 30-49: weak connection or ambiguous",
+            "- 0-29: minimal/none",
+            "Return ONLY JSON matching the provided schema. Include scores for ALL routes.",
+        ].join("\n"));
+        return pc.build();
+    }
+    decideRouteFromScores(output) {
+        // Optionally limit candidates and apply switching threshold
+        const entries = Object.entries(output.routes).sort((a, b) => b[1] - a[1]);
+        const limited = this.options?.maxCandidates
+            ? entries.slice(0, this.options.maxCandidates)
+            : entries;
+        const [topId, topScore] = limited[0] || ["", 0];
+        // switchThreshold is enforced by caller when a current route exists
+        return { routeId: topId, maxScore: topScore };
+    }
+}
+exports.RoutingEngine = RoutingEngine;
+//# sourceMappingURL=RoutingEngine.js.map