@falai/agent 0.8.1 → 0.9.0-alpha-2

package/src/core/RoutingEngine.ts

@@ -1,14 +1,24 @@
-import type { Event } from "../types/history";
+import type {
+  Event,
+  AgentOptions,
+  StructuredSchema,
+  RoutingDecision,
+  SessionState,
+  AiProvider,
+} from "../types";
+import { enterRoute, mergeCollected } from "../utils";
 import type { Route } from "./Route";
 import type { Step } from "./Step";
-import type { StructuredSchema } from "../types/schema";
-import type { RoutingDecision } from "../types/routing";
-import type { SessionState } from "../types/session";
-import type { AiProvider } from "../types/ai";
-import { enterRoute, mergeCollected } from "../types/session";
 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";
+
+export interface CandidateStep<TContext = unknown, TData = unknown> {
+  step: Step<TContext, TData>;
+  isRouteComplete?: boolean;
+}
 
 export interface RoutingDecisionOutput {
   context: string;
@@ -32,8 +42,33 @@ export interface RoutingEngineOptions {
   maxCandidates?: number;
 }
 
-export class RoutingEngine<TContext = unknown> {
-  constructor(private readonly options?: RoutingEngineOptions) {}
+export interface BuildStepSelectionPromptParams<
+  TContext = unknown,
+  TData = unknown
+> {
+  route: Route<TContext, TData>;
+  currentStep: Step<TContext, TData> | undefined;
+  candidates: CandidateStep<TContext, TData>[];
+  data: Partial<TData>;
+  history: Event[];
+  lastMessage: string;
+  agentOptions?: AgentOptions<TContext, TData>;
+  context?: TContext;
+  session?: SessionState<TData>;
+}
+
+export interface BuildRoutingPromptParams<TContext = unknown, TData = unknown> {
+  history: Event[];
+  routes: Route<TContext, TData>[];
+  lastMessage: string;
+  agentOptions?: AgentOptions<TContext, TData>;
+  session?: SessionState<TData>;
+  activeRouteSteps?: Step<TContext, TData>[];
+  context?: TContext;
+}
+
+export class RoutingEngine<TContext = unknown, TData = unknown> {
+  constructor(private readonly options?: RoutingEngineOptions) { }
 
   /**
    * Optimized decision for single-route scenarios
@@ -41,31 +76,30 @@ export class RoutingEngine<TContext = unknown> {
    * @private
    */
   private async decideSingleRouteStep(params: {
-    route: Route<TContext, unknown>;
-    session: SessionState;
+    route: Route<TContext, TData>;
+    session: SessionState<TData>;
     history: Event[];
-    agentMeta?: {
-      name?: string;
-      goal?: string;
-      description?: string;
-      personality?: string;
-    };
+    agentOptions?: AgentOptions<TContext, TData>;
     provider: AiProvider;
     context: TContext;
     signal?: AbortSignal;
   }): Promise<{
-    selectedRoute?: Route<TContext>;
-    selectedStep?: Step<TContext>;
+    selectedRoute?: Route<TContext, TData>;
+    selectedStep?: Step<TContext, TData>;
     responseDirectives?: string[];
-    session: SessionState;
+    session: SessionState<TData>;
     isRouteComplete?: boolean;
+    completedRoutes?: Route<TContext, TData>[];
   }> {
-    const { route, session, history, agentMeta, provider, context, signal } =
+    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
     if (!session.currentRoute || session.currentRoute.id !== route.id) {
       updatedSession = enterRoute(session, route.id, route.title);
@@ -109,6 +143,7 @@ export class RoutingEngine<TContext = unknown> {
           selectedStep: undefined,
           session: updatedSession,
           isRouteComplete: true,
+          completedRoutes,
         };
       } else {
         logger.debug(
@@ -119,24 +154,27 @@ export class RoutingEngine<TContext = unknown> {
           selectedStep: candidates[0].step,
           session: updatedSession,
           isRouteComplete: false,
+          completedRoutes,
         };
       }
     }
 
     // Multiple candidates - use AI to select best step
     const lastUserMessage = getLastMessageFromHistory(history);
-    const stepPrompt = this.buildStepSelectionPrompt(
+    const stepPrompt = await this.buildStepSelectionPrompt({
       route,
       currentStep,
       candidates,
-      updatedSession.data || {},
+      data: updatedSession.data || {},
       history,
-      lastUserMessage,
-      agentMeta
-    );
+      lastMessage: lastUserMessage,
+      agentOptions,
+      context,
+      session: updatedSession,
+    });
 
     const stepSchema = this.buildStepSelectionSchema(
-      candidates.map((c) => c.step.id)
+      candidates.map((c) => c.step)
     );
 
     const stepResult = await provider.generateMessage<
@@ -158,13 +196,11 @@ export class RoutingEngine<TContext = unknown> {
     });
 
     const selectedStepId = stepResult.structured?.selectedStepId;
-    const selectedStep = candidates.find(
-      (c) => c.step.id === selectedStepId
-    )?.step;
+    const selectedStep = candidates.find((c) => c.step.id === selectedStepId);
 
     if (selectedStep) {
       logger.debug(
-        `[RoutingEngine] Single-route: AI selected step: ${selectedStep.id}`
+        `[RoutingEngine] Single-route: AI selected step: ${selectedStep.step.id}`
       );
       logger.debug(
         `[RoutingEngine] Single-route: Reasoning: ${stepResult.structured?.reasoning}`
@@ -177,9 +213,10 @@ export class RoutingEngine<TContext = unknown> {
 
     return {
       selectedRoute,
-      selectedStep: selectedStep || candidates[0].step,
+      selectedStep: selectedStep?.step || candidates[0].step,
       responseDirectives: stepResult.structured?.responseDirectives,
       session: updatedSession,
+      completedRoutes,
     };
   }
 
@@ -187,13 +224,12 @@ export class RoutingEngine<TContext = unknown> {
    * Recursively traverse step chain to find first non-skipped step or END_ROUTE
    * @private
    */
-  private findFirstValidStepRecursive<TData = unknown>(
+  private findFirstValidStepRecursive(
     currentStep: Step<TContext, TData>,
     data: Partial<TData>,
     visited: Set<string>
   ): {
     step?: Step<TContext, TData>;
-    condition?: string;
     isRouteComplete?: boolean;
   } {
     // Prevent infinite loops
@@ -205,14 +241,10 @@ export class RoutingEngine<TContext = unknown> {
     const transitions = currentStep.getTransitions();
 
     for (const transition of transitions) {
-      const target = transition.getTarget();
+      const target = transition;
 
       // Check for END_ROUTE transition
-      if (
-        !target &&
-        transition.spec.step &&
-        typeof transition.spec.step === "symbol"
-      ) {
+      if (target && target.id === END_ROUTE_ID) {
         // Found END_ROUTE - route is complete
         return {
           isRouteComplete: true,
@@ -228,7 +260,7 @@ export class RoutingEngine<TContext = unknown> {
         );
         return {
           step: target,
-          condition: transition.condition,
+          isRouteComplete: false,
         };
       }
 
@@ -252,24 +284,12 @@ export class RoutingEngine<TContext = unknown> {
    * Identify valid next candidate steps based on current step and collected data
    * Returns step with isRouteComplete flag if route is complete (all steps skipped + has END_ROUTE transition)
    */
-  getCandidateSteps<TData = unknown>(
+  getCandidateSteps(
     route: Route<TContext, TData>,
     currentStep: Step<TContext, TData> | undefined,
     data: Partial<TData>
-  ): Array<{
-    step: Step<TContext, TData>;
-    condition?: string;
-    requires?: string[];
-    collectFields?: string[];
-    isRouteComplete?: boolean;
-  }> {
-    const candidates: Array<{
-      step: Step<TContext, TData>;
-      condition?: string;
-      requires?: string[];
-      collectFields?: string[];
-      isRouteComplete?: boolean;
-    }> = [];
+  ): CandidateStep<TContext, TData>[] {
+    const candidates: CandidateStep<TContext, TData>[] = [];
 
     if (!currentStep) {
       const initialStep = route.initialStep;
@@ -286,28 +306,22 @@ export class RoutingEngine<TContext = unknown> {
           logger.debug(
             `[RoutingEngine] Route complete on entry: all steps skipped, END_ROUTE reached`
           );
-          return [
-            {
-              step: initialStep,
-              condition: "Route complete - all data collected on entry",
-              isRouteComplete: true,
-            },
-          ];
+          candidates.push({
+            step: initialStep,
+            isRouteComplete: true,
+          });
         } else if (result.step) {
           // Found a non-skipped step
           candidates.push({
             step: result.step,
-            condition: result.condition,
-            requires: result.step.requires,
-            collectFields: result.step.collectFields,
+            isRouteComplete: result.isRouteComplete || false,
           });
         }
         // If no step found and not complete, fall through to return empty candidates
       } else {
         candidates.push({
           step: initialStep,
-          requires: initialStep.requires,
-          collectFields: initialStep.collectFields,
+          isRouteComplete: false,
         });
       }
       return candidates;
@@ -317,14 +331,10 @@ export class RoutingEngine<TContext = unknown> {
     let hasEndRoute = false;
 
     for (const transition of transitions) {
-      const target = transition.getTarget();
+      const target = transition;
 
       // Check for END_ROUTE transition (no target step)
-      if (
-        !target &&
-        transition.spec.step &&
-        typeof transition.spec.step === "symbol"
-      ) {
+      if (target && target.id === END_ROUTE_ID) {
         hasEndRoute = true;
         continue;
       }
@@ -349,9 +359,7 @@ export class RoutingEngine<TContext = unknown> {
           // Found a non-skipped step deeper in the chain
           candidates.push({
             step: result.step,
-            condition: result.condition || transition.condition,
-            requires: result.step.requires,
-            collectFields: result.step.collectFields,
+            isRouteComplete: result.isRouteComplete || false,
           });
         }
         continue;
@@ -359,9 +367,7 @@ export class RoutingEngine<TContext = unknown> {
 
       candidates.push({
         step: target,
-        condition: transition.condition,
-        requires: target.requires,
-        collectFields: target.collectFields,
+        isRouteComplete: hasEndRoute || false,
       });
     }
 
@@ -376,7 +382,6 @@ export class RoutingEngine<TContext = unknown> {
         return [
           {
             step: currentStep,
-            condition: "Route complete - all data collected",
             isRouteComplete: true,
           },
         ];
@@ -386,9 +391,7 @@ export class RoutingEngine<TContext = unknown> {
       if (!currentStep.shouldSkip(data)) {
         candidates.push({
           step: currentStep,
-          condition: "Continue in current step (no valid transitions)",
-          requires: currentStep.requires,
-          collectFields: currentStep.collectFields,
+          isRouteComplete: hasEndRoute || false,
         });
       }
     }
@@ -401,59 +404,69 @@ export class RoutingEngine<TContext = unknown> {
    * 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: {
-    routes: Route<TContext, unknown>[];
-    session: SessionState;
+    routes: Route<TContext, TData>[];
+    session: SessionState<TData>;
     history: Event[];
-    agentMeta?: {
-      name?: string;
-      goal?: string;
-      description?: string;
-      personality?: string;
-    };
+    agentOptions?: AgentOptions<TContext, TData>;
     provider: AiProvider;
     context: TContext;
     signal?: AbortSignal;
   }): Promise<{
-    selectedRoute?: Route<TContext>;
-    selectedStep?: Step<TContext>;
+    selectedRoute?: Route<TContext, TData>;
+    selectedStep?: Step<TContext, TData>;
     responseDirectives?: string[];
-    session: SessionState;
+    session: SessionState<TData>;
     isRouteComplete?: boolean;
+    completedRoutes?: Route<TContext, TData>[];
   }> {
-    const { routes, session, history, agentMeta, provider, context, signal } =
-      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) {
+      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) {
-      return this.decideSingleRouteStep({
+      const result = await this.decideSingleRouteStep({
         route: routes[0],
         session,
         history,
-        agentMeta,
+        agentOptions,
         provider,
         context,
         signal,
       });
+      return {
+        ...result,
+        completedRoutes,
+      };
     }
 
     const lastUserMessage = getLastMessageFromHistory(history);
 
-    let activeRouteSteps:
-      | Array<{
-          stepId: string;
-          description: string;
-          condition?: string;
-          requires?: string[];
-          collectFields?: string[];
-        }>
-      | undefined;
-    let activeRoute: Route<TContext> | undefined;
+    let activeRouteSteps: Step<TContext, TData>[] | undefined;
+    let activeRoute: Route<TContext, TData> | undefined;
     let isRouteComplete = false;
 
     if (session.currentRoute) {
@@ -477,13 +490,7 @@ export class RoutingEngine<TContext = unknown> {
           // Don't include steps in routing if route is complete
           activeRouteSteps = undefined;
         } else {
-          activeRouteSteps = candidates.map((c) => ({
-            stepId: c.step.id,
-            description: c.step.description || "",
-            condition: c.condition,
-            requires: c.requires,
-            collectFields: c.collectFields,
-          }));
+          activeRouteSteps = candidates.map((c) => c.step);
           logger.debug(
             `[RoutingEngine] Found ${activeRouteSteps.length} candidate steps for active route`
           );
@@ -497,14 +504,15 @@ export class RoutingEngine<TContext = unknown> {
       activeRouteSteps
     );
 
-    const routingPrompt = this.buildRoutingPrompt(
+    const routingPrompt = await this.buildRoutingPrompt({
       history,
       routes,
-      lastUserMessage,
-      agentMeta,
+      lastMessage: lastUserMessage,
+      agentOptions,
       session,
-      activeRouteSteps
-    );
+      activeRouteSteps,
+      context,
+    });
 
     const routingResult = await provider.generateMessage<
       TContext,
@@ -520,18 +528,29 @@ export class RoutingEngine<TContext = unknown> {
       },
     });
 
-    let selectedRoute: Route<TContext> | undefined;
-    let selectedStep: Step<TContext> | undefined;
+    let selectedRoute: Route<TContext, TData> | undefined;
+    let selectedStep: Step<TContext, TData> | undefined;
     let responseDirectives: string[] | undefined;
     let updatedSession = session;
 
     if (routingResult.structured?.routes) {
-      const decision = this.decideRouteFromScores({
-        context: routingResult.structured.context,
-        routes: routingResult.structured.routes,
-        responseDirectives: routingResult.structured.responseDirectives,
-      });
-      selectedRoute = routes.find((r) => r.id === decision.routeId);
+      // 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);
+      })();
+
       responseDirectives = routingResult.structured.responseDirectives;
 
       if (
@@ -584,104 +603,175 @@ export class RoutingEngine<TContext = unknown> {
       responseDirectives,
       session: updatedSession,
       isRouteComplete,
+      completedRoutes,
     };
   }
 
+  /**
+   * 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: Route<TContext, TData>[], data: Partial<TData>): Route<TContext, TData>[] {
+    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: Route<TContext, TData>[], data: Partial<TData>): Map<string, number> {
+    const completionStatus = new Map<string, number>();
+
+    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
+   * @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: Route<TContext, TData>[],
+    data: Partial<TData>,
+    routeScores: Record<string, number>
+  ): Route<TContext, TData> | undefined {
+    const completionStatus = this.getRouteCompletionStatus(routes, data);
+
+    // 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;
+
+      // Skip fully completed routes unless they have very high AI scores
+      if (completionProgress >= 1.0 && aiScore < 80) {
+        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) {
+      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
    */
-  private buildStepSelectionPrompt(
-    route: Route<TContext>,
-    currentStep: Step<TContext> | undefined,
-    candidates: Array<{
-      step: Step<TContext>;
-      condition?: string;
-      requires?: string[];
-      collectFields?: string[];
-    }>,
-    data: Partial<unknown>,
-    history: Event[],
-    lastMessage: string,
-    agentMeta?: {
-      name?: string;
-      goal?: string;
-      description?: string;
-      personality?: string;
-    }
-  ): string {
-    const pc = new PromptComposer();
+  private async buildStepSelectionPrompt(
+    params: BuildStepSelectionPromptParams<TContext, TData>
+  ): Promise<string> {
+    const {
+      route,
+      currentStep,
+      candidates,
+      data,
+      history,
+      lastMessage,
+      agentOptions,
+      context,
+      session,
+    } = params;
+    const templateContext = { context, session, history };
+    const pc = new PromptComposer<TContext, TData>(templateContext);
 
     // Add agent metadata
-    if (agentMeta?.name || agentMeta?.goal || agentMeta?.description) {
-      pc.addAgentMeta({
-        name: agentMeta?.name || "Agent",
-        description: agentMeta?.description,
-        goal: agentMeta?.goal,
-      });
+    if (agentOptions) {
+      await pc.addAgentMeta(agentOptions);
     }
 
-    const personality =
-      agentMeta?.personality || "Tone: brief, natural, 1-2 short sentences.";
-    pc.addPersonality(personality);
-
     // Add route context
-    pc.addInstruction(
+    await pc.addInstruction(
       `Active Route: ${route.title}\nDescription: ${route.description || "N/A"}`
     );
 
     // Add current step context
     if (currentStep) {
-      pc.addInstruction(
-        `Current Step: ${currentStep.id}\nDescription: ${
-          currentStep.description || "N/A"
+      await pc.addInstruction(
+        `Current Step: ${currentStep.id}\nDescription: ${currentStep.description || "N/A"
         }`
       );
     } else {
-      pc.addInstruction("Current Step: None (entering route)");
+      await pc.addInstruction("Current Step: None (entering route)");
     }
 
     // Add collected data context
     if (Object.keys(data).length > 0) {
-      pc.addInstruction(
+      await pc.addInstruction(
         `Collected Data So Far:\n${JSON.stringify(data, null, 2)}`
       );
     } else {
-      pc.addInstruction("Collected Data: None yet");
+      await pc.addInstruction("Collected Data: None yet");
     }
 
     // Add conversation history
-    pc.addInteractionHistory(history);
-    pc.addLastMessage(lastMessage);
+    await pc.addInteractionHistory(history);
+    await pc.addLastMessage(lastMessage);
 
     // Add candidate steps
-    const stepDescriptions = candidates.map((candidate, idx) => {
+    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"}`,
       ];
 
-      if (candidate.condition) {
-        parts.push(`   Condition: ${candidate.condition}`);
+      if (candidate.step.when) {
+        const renderedWhen = await render(candidate.step.when, templateContext);
+        parts.push(`   When this step should be completed: ${renderedWhen}`);
       }
 
-      if (candidate.requires && candidate.requires.length > 0) {
-        parts.push(`   Required Data: ${candidate.requires.join(", ")}`);
+      if (candidate.step.requires && candidate.step.requires.length > 0) {
+        parts.push(`   Required Data: ${candidate.step.requires.join(", ")}`);
       }
 
-      if (candidate.collectFields && candidate.collectFields.length > 0) {
-        parts.push(`   Collects: ${candidate.collectFields.join(", ")}`);
+      if (candidate.step.collect && candidate.step.collect.length > 0) {
+        parts.push(`   Collects: ${candidate.step.collect.join(", ")}`);
       }
 
-      return parts.join("\n");
-    });
+      stepDescriptions.push(parts.join("\n"));
+    }
 
-    pc.addInstruction(
+    await pc.addInstruction(
       `Available Steps to Transition To:\n${stepDescriptions.join("\n\n")}`
     );
 
-    // Add decision instructions
-    pc.addInstruction(
+    // Add decision prompt
+    await pc.addInstruction(
       [
         "Task: Decide which step to transition to based on:",
         "1. The user's current message and intent",
@@ -707,7 +797,9 @@ export class RoutingEngine<TContext = unknown> {
    * Build schema for step selection
    * @private
    */
-  private buildStepSelectionSchema(validStepIds: string[]): StructuredSchema {
+  private buildStepSelectionSchema(
+    validSteps: Step<TContext, TData>[]
+  ): StructuredSchema {
     return {
       description:
         "Step transition decision based on conversation context and collected data",
@@ -722,7 +814,7 @@ export class RoutingEngine<TContext = unknown> {
           type: "string",
           nullable: false,
           description: "The ID of the selected step to transition to",
-          enum: validStepIds,
+          enum: validSteps.map((s) => s.id),
         },
         responseDirectives: {
           type: "array",
@@ -737,9 +829,9 @@ export class RoutingEngine<TContext = unknown> {
   }
 
   buildDynamicRoutingSchema(
-    routes: Route<TContext>[],
+    routes: Route<TContext, TData>[],
     extrasSchema?: StructuredSchema,
-    activeRouteSteps?: { stepId: string; description: string }[]
+    activeRouteSteps?: Step<TContext, TData>[]
   ): StructuredSchema {
     const routeIds = routes.map((r) => r.id);
     const routeProperties: Record<string, StructuredSchema> = {};
@@ -789,7 +881,7 @@ export class RoutingEngine<TContext = unknown> {
         nullable: false,
         description:
           "The step ID to transition to within the active route (required if continuing in current route)",
-        enum: activeRouteSteps.map((s) => s.stepId),
+        enum: activeRouteSteps.map((s) => s.id),
       };
       base.properties.stepReasoning = {
         type: "string",
@@ -811,37 +903,24 @@ export class RoutingEngine<TContext = unknown> {
     return base;
   }
 
-  buildRoutingPrompt(
-    history: Event[],
-    routes: Route<TContext>[],
-    lastMessage: string,
-    agentMeta?: {
-      name?: string;
-      goal?: string;
-      description?: string;
-      personality?: string;
-    },
-    session?: SessionState,
-    activeRouteSteps?: Array<{
-      stepId: string;
-      description: string;
-      condition?: string;
-      requires?: string[];
-      collectFields?: string[];
-    }>
-  ): string {
-    const pc = new PromptComposer();
-    if (agentMeta?.name || agentMeta?.goal || agentMeta?.description) {
-      pc.addAgentMeta({
-        name: agentMeta?.name || "Agent",
-        description: agentMeta?.description,
-        goal: agentMeta?.goal,
-      });
+  async buildRoutingPrompt(
+    params: BuildRoutingPromptParams<TContext, TData>
+  ): Promise<string> {
+    const {
+      history,
+      routes,
+      lastMessage,
+      agentOptions,
+      session,
+      activeRouteSteps,
+      context,
+    } = params;
+    const templateContext = { context, session, history };
+    const pc = new PromptComposer<TContext, TData>(templateContext);
+    if (agentOptions) {
+      await pc.addAgentMeta(agentOptions);
     }
-    const personality =
-      agentMeta?.personality || "Tone: brief, natural, 1-2 short sentences.";
-    pc.addPersonality(personality);
-    pc.addInstruction(
+    await pc.addInstruction(
       "Task: Intent analysis and route scoring (0-100). Score ALL listed routes."
     );
 
@@ -863,7 +942,42 @@ export class RoutingEngine<TContext = unknown> {
       sessionInfo.push(
         "Note: User is mid-conversation. They may want to continue current route or switch to a new one based on their intent."
       );
-      pc.addInstruction(sessionInfo.join("\n"));
+      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) {
@@ -871,21 +985,25 @@ export class RoutingEngine<TContext = unknown> {
           "",
           "Available steps in active route (choose one to transition to):",
         ];
-        activeRouteSteps.forEach((step, idx) => {
-          stepInfo.push(`${idx + 1}. Step: ${step.stepId}`);
+        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}`);
           }
-          if (step.condition) {
-            stepInfo.push(`   Condition: ${step.condition}`);
+          const renderedWhen = await render(step.when, templateContext);
+          if (step.when) {
+            stepInfo.push(
+              `   When this step should be completed: ${renderedWhen}`
+            );
           }
           if (step.requires && step.requires.length > 0) {
             stepInfo.push(`   Required data: ${step.requires.join(", ")}`);
           }
-          if (step.collectFields && step.collectFields.length > 0) {
-            stepInfo.push(`   Will collect: ${step.collectFields.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:"
@@ -894,16 +1012,14 @@ export class RoutingEngine<TContext = unknown> {
         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");
-        pc.addInstruction(stepInfo.join("\n"));
+        await pc.addInstruction(stepInfo.join("\n"));
       }
     }
 
-    pc.addInteractionHistory(history);
-    pc.addLastMessage(lastMessage);
-    // Cast to unknown to satisfy generic constraints in composer
-    // This is safe because PromptComposer only reads route metadata (id, title, description)
-    pc.addRoutingOverview(routes as unknown as Route<unknown>[]);
-    pc.addInstruction(
+    await pc.addInteractionHistory(history);
+    await pc.addLastMessage(lastMessage);
+    await pc.addRoutingOverview(routes);
+    await pc.addInstruction(
       [
         "Scoring rules:",
         "- 90-100: explicit keywords + clear intent",