@falai/agent 1.2.8 → 2.0.0

package/src/core/{RoutingEngine.ts → FlowRouter.ts}

@@ -7,23 +7,22 @@ import type {
   TemplateContext,
 } from "../types";
 import { MessageRole } from "../types";
-import { enterRoute, mergeCollected } from "../utils";
-import type { Route } from "./Route";
+import { enterFlow, mergeCollected, isFlowCompletedThisSession } from "../utils";
+import type { Flow } from "./Flow";
 import type { Step } from "./Step";
 import { PromptComposer } from "./PromptComposer";
 import { PromptSectionCache } from "./PromptSectionCache";
-import { END_ROUTE_ID } from "../constants";
 import { createTemplateContext, getLastMessageFromHistory, logger, eventsToHistory } from "../utils";
 
 export interface CandidateStep<TContext = unknown, TData = unknown> {
   step: Step<TContext, TData>;
-  isRouteComplete?: boolean;
+  isFlowComplete?: boolean;
 }
 
-export interface RoutingDecisionOutput {
+export interface FlowRoutingDecisionOutput {
   context: string;
-  routes: Record<string, number>;
-  selectedStepId?: string; // For active route, which step to transition to
+  flows: Record<string, number>;
+  selectedStepId?: string; // For active flow, which step to transition to
   stepReasoning?: string; // Why this step was selected
   responseDirectives?: string[];
   extractions?: Array<{
@@ -36,18 +35,18 @@ export interface RoutingDecisionOutput {
   contextUpdate?: Record<string, unknown>;
 }
 
-export interface RoutingEngineOptions {
+export interface FlowRouterOptions {
   /**
-   * Score margin the best alternative route must exceed the current route's score
-   * by before the agent switches routes. Prevents flip-flopping on marginal differences.
+   * Score margin the best alternative flow must exceed the current flow's score
+   * by before the agent switches flows. Prevents flip-flopping on marginal differences.
    * @default 15
    */
-  routeSwitchMargin?: number;
+  flowSwitchMargin?: number;
   /**
-   * Callback invoked when the active route changes.
-   * Used by Agent to invalidate route-dependent prompt cache sections.
+   * Callback invoked when the active flow changes.
+   * Used by Agent to invalidate flow-dependent prompt cache sections.
    */
-  onRouteSwitch?: () => void;
+  onFlowSwitch?: () => void;
   /**
    * Shared prompt section cache for memoizing static prompt sections.
    */
@@ -58,7 +57,7 @@ export interface BuildStepSelectionPromptParams<
   TContext = unknown,
   TData = unknown
 > {
-  route: Route<TContext, TData>;
+  flow: Flow<TContext, TData>;
   currentStep: Step<TContext, TData> | undefined;
   candidates: CandidateStep<TContext, TData>[];
   data: Partial<TData>;
@@ -72,20 +71,20 @@ export interface BuildStepSelectionPromptParams<
 
 export interface BuildRoutingPromptParams<TContext = unknown, TData = unknown> {
   history: Event[];
-  routes: Route<TContext, TData>[];
+  flows: Flow<TContext, TData>[];
   lastMessage: string;
   agentOptions?: AgentOptions<TContext, TData>;
   session?: SessionState<TData>;
-  activeRouteSteps?: Step<TContext, TData>[];
+  activeFlowSteps?: Step<TContext, TData>[];
   context?: TContext;
 }
 
-export class RoutingEngine<TContext = unknown, TData = unknown> {
-  constructor(private readonly options?: RoutingEngineOptions) { }
+export class FlowRouter<TContext = unknown, TData = unknown> {
+  constructor(private readonly options?: FlowRouterOptions) { }
 
   /**
    * Check whether the history contains any user messages.
-   * Used to detect "session resume" scenarios where a route/step was
+   * Used to detect "session resume" scenarios where a flow/step was
    * pre-set programmatically and the conversation starts with only
    * system messages (or no messages at all).
    * @private
@@ -98,75 +97,75 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
 
   /**
    * Handle the "session resume" fast-path: when a session already has a
-   * pre-set currentRoute (and optionally currentStep) and the conversation
+   * pre-set currentFlow (and optionally currentStep) and the conversation
    * history contains no user messages, honor the pre-set position instead
-   * of running AI route/step selection.
+   * of running AI flow/step selection.
    *
    * Returns `undefined` when the fast-path does not apply.
    * @private
    */
   private async handleSessionResume(params: {
-    routes: Route<TContext, TData>[];
+    flows: Flow<TContext, TData>[];
     session: SessionState<TData>;
     history: Event[];
     context: TContext;
   }): Promise<{
-    selectedRoute?: Route<TContext, TData>;
+    selectedFlow?: Flow<TContext, TData>;
     selectedStep?: Step<TContext, TData>;
     session: SessionState<TData>;
-    isRouteComplete?: boolean;
-    completedRoutes?: Route<TContext, TData>[];
+    isFlowComplete?: boolean;
+    completedFlows?: Flow<TContext, TData>[];
   } | undefined> {
-    const { routes, session, history, context } = params;
+    const { flows, session, history, context } = params;
 
     // Fast-path only applies when:
-    // 1. Session already has a currentRoute set
+    // 1. Session already has a currentFlow set
     // 2. There are no user messages in the history (system-only or empty)
-    if (!session.currentRoute || this.hasUserMessages(history)) {
+    if (!session.currentFlow || this.hasUserMessages(history)) {
       return undefined;
     }
 
-    // Find the pre-set route among available routes
-    const presetRoute = routes.find(
-      (r) => r.id === session.currentRoute!.id
+    // Find the pre-set flow among available flows
+    const presetFlow = flows.find(
+      (r) => r.id === session.currentFlow!.id
     );
 
-    if (!presetRoute) {
+    if (!presetFlow) {
       logger.warn(
-        `[RoutingEngine] Session resume: pre-set route '${session.currentRoute.id}' not found among available routes, falling back to normal routing`
+        `[FlowConfigurationError] Pre-set flow not found: session references flow "${session.currentFlow.id}" which does not exist among available flows. Falling back to normal routing. Remove the stale session reference or register the missing flow.`
       );
       return undefined;
     }
 
     logger.debug(
-      `[RoutingEngine] Session resume: honoring pre-set route '${presetRoute.title}' (no user messages in history)`
+      `[FlowRouter] Session resume: honoring pre-set flow '${presetFlow.title}' (no user messages in history)`
     );
 
-    // Enter route if needed (merges initialData, no-op if already entered)
-    const updatedSession = this.enterRouteIfNeeded(session, presetRoute);
+    // Enter flow if needed (merges initialData, no-op if already entered)
+    const updatedSession = this.enterFlowIfNeeded(session, presetFlow);
 
-    // Evaluate cross-route completions
-    const completedRoutes = this.evaluateRouteCompletions(routes, updatedSession.data || {});
+    // Evaluate cross-flow completions
+    const completedFlows = this.evaluateFlowCompletions(flows, updatedSession.data || {});
 
     // If a currentStep is also pre-set, honor it — stay on that step
     if (session.currentStep) {
-      const presetStep = presetRoute.getStep(session.currentStep.id);
+      const presetStep = presetFlow.getStep(session.currentStep.id);
 
       if (presetStep) {
         logger.debug(
-          `[RoutingEngine] Session resume: honoring pre-set step '${presetStep.id}'`
+          `[FlowRouter] Session resume: honoring pre-set step '${presetStep.id}'`
         );
         return {
-          selectedRoute: presetRoute,
+          selectedFlow: presetFlow,
           selectedStep: presetStep,
           session: updatedSession,
-          isRouteComplete: false,
-          completedRoutes,
+          isFlowComplete: false,
+          completedFlows,
         };
       }
 
       logger.warn(
-        `[RoutingEngine] Session resume: pre-set step '${session.currentStep.id}' not found in route '${presetRoute.title}', resolving from initial step`
+        `[FlowConfigurationError] Pre-set step not found: session references step "${session.currentStep.id}" which does not exist in flow "${presetFlow.title}". Resolving from initial step. Remove the stale step reference or register the missing step.`
       );
     }
 
@@ -180,82 +179,116 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
     });
 
     const candidates = await this.getCandidateStepsWithConditions(
-      presetRoute,
+      presetFlow,
       undefined, // No current step — start from beginning
       templateContext
     );
 
     if (candidates.length === 0) {
       logger.warn(
-        `[RoutingEngine] Session resume: no valid steps found for route '${presetRoute.title}'`
+        `[FlowConfigurationError] No valid steps found: all steps in flow "${presetFlow.title}" are skipped by their conditions. Check skip/when conditions on the flow's steps.`
       );
       return {
-        selectedRoute: presetRoute,
+        selectedFlow: presetFlow,
         selectedStep: undefined,
         session: updatedSession,
-        isRouteComplete: false,
-        completedRoutes,
+        isFlowComplete: false,
+        completedFlows,
       };
     }
 
     const candidate = candidates[0];
 
-    if (candidate.isRouteComplete) {
+    if (candidate.isFlowComplete) {
       logger.debug(
-        `[RoutingEngine] Session resume: route '${presetRoute.title}' is already complete`
+        `[FlowRouter] Session resume: flow '${presetFlow.title}' is already complete`
       );
       return {
-        selectedRoute: presetRoute,
+        selectedFlow: presetFlow,
         selectedStep: undefined,
         session: updatedSession,
-        isRouteComplete: true,
-        completedRoutes,
+        isFlowComplete: true,
+        completedFlows,
       };
     }
 
     logger.debug(
-      `[RoutingEngine] Session resume: resolved initial step '${candidate.step.id}'`
+      `[FlowRouter] Session resume: resolved initial step '${candidate.step.id}'`
     );
     return {
-      selectedRoute: presetRoute,
+      selectedFlow: presetFlow,
       selectedStep: candidate.step,
       session: updatedSession,
-      isRouteComplete: false,
-      completedRoutes,
+      isFlowComplete: false,
+      completedFlows,
     };
   }
 
   /**
-   * Enter a route if not already in it, merging initial data
+   * Enter a flow if not already in it, merging initial data.
+   *
+   * When the flow is `reentrant` and was previously completed in this
+   * session, clears every field declared in the flow's `requiredFields`
+   * and `optionalFields` before entering — so the flow starts fresh from
+   * its initial step instead of being instantly marked complete by stale
+   * data. Fields not owned by this flow are preserved.
+   *
    * @private
    */
-  private enterRouteIfNeeded(
+  private enterFlowIfNeeded(
     session: SessionState<TData>,
-    route: Route<TContext, TData>
+    route: Flow<TContext, TData>
   ): SessionState<TData> {
-    if (!session.currentRoute || session.currentRoute.id !== route.id) {
-      let updatedSession = enterRoute(session, route.id, route.title);
+    if (!session.currentFlow || session.currentFlow.id !== route.id) {
+      let workingSession = session;
+
+      // Re-entry into a `reentrant` flow that previously completed:
+      // clear owned fields so completion logic doesn't short-circuit on
+      // stale data from the prior run.
+      const previouslyCompleted = isFlowCompletedThisSession(session, route.id);
+      if (previouslyCompleted && route.reentrant) {
+        const ownedFields = [
+          ...(route.requiredFields ?? []),
+          ...(route.optionalFields ?? []),
+        ];
+        if (ownedFields.length > 0) {
+          const owned = new Set<keyof TData>(ownedFields);
+          const filtered: Partial<TData> = {};
+          for (const key of Object.keys(session.data ?? {}) as (keyof TData)[]) {
+            if (!owned.has(key)) {
+              (filtered as Record<keyof TData, unknown>)[key] =
+                (session.data as Record<keyof TData, unknown>)[key];
+            }
+          }
+          workingSession = { ...session, data: filtered };
+          logger.debug(
+            `[FlowRouter] Re-entering reentrant flow ${route.title}: cleared ${ownedFields.length} owned field(s)`
+          );
+        }
+      }
+
+      let updatedSession = enterFlow(workingSession, route.id, route.title);
       if (route.initialData) {
         updatedSession = mergeCollected(updatedSession, route.initialData);
         logger.debug(
-          `[RoutingEngine] Merged initial data for route ${route.title}:`,
+          `[FlowRouter] Merged initial data for flow ${route.title}:`,
           route.initialData
         );
       }
-      logger.debug(`[RoutingEngine] Entered route: ${route.title}`);
-      this.options?.onRouteSwitch?.();
+      logger.debug(`[FlowRouter] Entered flow: ${route.title}`);
+      this.options?.onFlowSwitch?.();
       return updatedSession;
     }
     return session;
   }
 
   /**
-   * Optimized decision for single-route scenarios
-   * Skips route scoring and only does step selection
+   * Optimized decision for single-flow scenarios
+   * Skips flow scoring and only does step selection
    * @private
    */
-  private async decideSingleRouteStep(params: {
-    route: Route<TContext, TData>;
+  private async decideSingleFlowStep(params: {
+    route: Flow<TContext, TData>;
     session: SessionState<TData>;
     history: Event[];
     agentOptions?: AgentOptions<TContext, TData>;
@@ -263,23 +296,23 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
     context: TContext;
     signal?: AbortSignal;
   }): Promise<{
-    selectedRoute?: Route<TContext, TData>;
+    selectedFlow?: Flow<TContext, TData>;
     selectedStep?: Step<TContext, TData>;
     responseDirectives?: string[];
     session: SessionState<TData>;
-    isRouteComplete?: boolean;
-    completedRoutes?: Route<TContext, TData>[];
+    isFlowComplete?: boolean;
+    completedFlows?: Flow<TContext, TData>[];
   }> {
     const { route, session, history, agentOptions, provider, context, signal } =
       params;
 
-    const selectedRoute = route;
+    const selectedFlow = route;
 
-    // Enter route if not already in it (this may merge initial data)
-    const updatedSession = this.enterRouteIfNeeded(session, route);
+    // Enter flow if not already in it (this may merge initial data)
+    const updatedSession = this.enterFlowIfNeeded(session, route);
 
-    // Check if this single route is complete (use updated session data)
-    const completedRoutes = route.isComplete(updatedSession.data || {}) ? [route] : [];
+    // Check if this single flow is complete (use updated session data)
+    const completedFlows = route.isComplete(updatedSession.data || {}) ? [route] : [];
 
     // Get candidate steps using new condition evaluation
     const templateContext = createTemplateContext({
@@ -298,52 +331,51 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
     );
 
     if (candidates.length === 0) {
-      logger.warn(`[RoutingEngine] Single-route: No valid steps found`);
-      return { selectedRoute, session: updatedSession };
+      logger.warn(`[FlowConfigurationError] No valid steps found: all candidates in the single-flow agent are skipped. Check step skip/when conditions.`);
+      return { selectedFlow, session: updatedSession };
     }
 
     // If only one candidate, check if it's a completion marker
     if (candidates.length === 1) {
       const candidate = candidates[0];
 
-      if (candidate.isRouteComplete) {
+      if (candidate.isFlowComplete) {
         logger.debug(
-          `[RoutingEngine] Single-route: Route complete - all required fields collected or END_ROUTE reached`
+          `[FlowRouter] Single-flow: Flow complete - all required fields collected or last step reached`
         );
-        // Don't return a selectedStep when route is complete - there's no step to enter
+        // Don't return a selectedStep when flow is complete - there's no step to enter
         return {
-          selectedRoute,
+          selectedFlow,
           selectedStep: undefined,
           session: updatedSession,
-          isRouteComplete: true,
-          completedRoutes,
+          isFlowComplete: true,
+          completedFlows,
         };
       } else {
         logger.debug(
-          `[RoutingEngine] Single-route: Only one valid step: ${candidate.step.id}`
+          `[FlowRouter] Single-flow: Only one valid step: ${candidate.step.id}`
         );
         return {
-          selectedRoute,
+          selectedFlow,
           selectedStep: candidate.step,
           session: updatedSession,
-          isRouteComplete: false,
-          completedRoutes,
+          isFlowComplete: false,
+          completedFlows,
         };
       }
     }
 
-    // No candidates means route has no valid next steps (edge case)
-    // Don't mark as complete based on data alone — only END_ROUTE completes a route
+    // No candidates means flow has no valid next steps (edge case)
     if (candidates.length === 0) {
       logger.debug(
-        `[RoutingEngine] Single-route: No valid candidate steps found`
+        `[FlowRouter] Single-flow: No valid candidate steps found`
       );
       return {
-        selectedRoute,
+        selectedFlow,
         selectedStep: undefined,
         session: updatedSession,
-        isRouteComplete: false,
-        completedRoutes,
+        isFlowComplete: false,
+        completedFlows,
       };
     }
 
@@ -357,11 +389,11 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
       stepConditionContext.push(...whenResult.aiContextStrings);
     }
 
-    // Check if any candidate is a completion marker (isRouteComplete = true)
-    const hasCompletionOption = candidates.some(c => c.isRouteComplete);
+    // Check if any candidate is a completion marker (isFlowComplete = true)
+    const hasCompletionOption = candidates.some(c => c.isFlowComplete);
 
     const stepPrompt = await this.buildStepSelectionPrompt({
-      route,
+      flow: route,
       currentStep,
       candidates,
       data: updatedSession.data || {},
@@ -371,11 +403,11 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
       context,
       session: updatedSession,
       stepConditionContext,
-      includeEndRoute: hasCompletionOption,
+      includeCompletion: hasCompletionOption,
     });
 
     const stepSchema = this.buildStepSelectionSchema(
-      candidates.filter(c => !c.isRouteComplete).map((c) => c.step),
+      candidates.filter(c => !c.isFlowComplete).map((c) => c.step),
       hasCompletionOption
     );
 
@@ -399,21 +431,21 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
 
     const selectedStepId = stepResult.structured?.selectedStepId;
 
-    // Check if AI selected END_ROUTE
-    if (selectedStepId === END_ROUTE_ID) {
+    // Check if AI selected flow completion
+    if (selectedStepId === '__COMPLETE__') {
       logger.debug(
-        `[RoutingEngine] Single-route: AI selected END_ROUTE - completing route`
+        `[FlowRouter] Single-flow: AI selected flow completion`
       );
       logger.debug(
-        `[RoutingEngine] Single-route: Reasoning: ${stepResult.structured?.reasoning}`
+        `[FlowRouter] Single-flow: Reasoning: ${stepResult.structured?.reasoning}`
       );
       return {
-        selectedRoute,
+        selectedFlow,
         selectedStep: undefined,
         responseDirectives: stepResult.structured?.responseDirectives,
         session: updatedSession,
-        isRouteComplete: true,
-        completedRoutes,
+        isFlowComplete: true,
+        completedFlows,
       };
     }
 
@@ -421,28 +453,28 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
 
     if (selectedStep) {
       logger.debug(
-        `[RoutingEngine] Single-route: AI selected step: ${selectedStep.step.id}`
+        `[FlowRouter] Single-flow: AI selected step: ${selectedStep.step.id}`
       );
       logger.debug(
-        `[RoutingEngine] Single-route: Reasoning: ${stepResult.structured?.reasoning}`
+        `[FlowRouter] Single-flow: Reasoning: ${stepResult.structured?.reasoning}`
       );
     } else {
       logger.warn(
-        `[RoutingEngine] Single-route: Invalid step ID returned, using first candidate`
+        `[FlowConfigurationError] Invalid step ID returned: AI router returned a step ID that does not match any candidate. Falling back to first candidate. Check flow step ids and router configuration.`
       );
     }
 
     return {
-      selectedRoute,
+      selectedFlow,
       selectedStep: selectedStep?.step || candidates[0].step,
       responseDirectives: stepResult.structured?.responseDirectives,
       session: updatedSession,
-      completedRoutes,
+      completedFlows,
     };
   }
 
   /**
-   * Recursively traverse step chain to find first non-skipped step or END_ROUTE using new condition evaluation
+   * Recursively traverse step chain to find first non-skipped step using new condition evaluation
    * @private
    */
   private async findFirstValidStepRecursiveWithConditions(
@@ -451,7 +483,7 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
     visited: Set<string>
   ): Promise<{
     step?: Step<TContext, TData>;
-    isRouteComplete?: boolean;
+    isFlowComplete?: boolean;
     aiContextStrings?: string[];
   }> {
     // Prevent infinite loops
@@ -463,39 +495,38 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
     const transitions = currentStep.getTransitions();
     const allAiContextStrings: string[] = [];
 
+    // No transitions means implicit terminus — flow is complete
+    if (transitions.length === 0) {
+      return {
+        isFlowComplete: true,
+        aiContextStrings: allAiContextStrings,
+      };
+    }
+
     for (const transition of transitions) {
       const target = transition;
 
-      // Check for END_ROUTE transition
-      if (target && target.id === 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);
+      // Evaluate skip condition (code-only, if-shape)
+      const skipResult = await target.evaluateSkip(templateContext);
       allAiContextStrings.push(...skipResult.aiContextStrings);
 
       // If target should NOT be skipped, we found our step
       if (!skipResult.shouldSkip) {
         logger.debug(
-          `[RoutingEngine] Found valid step after skipping: ${target.id}`
+          `[FlowRouter] Found valid step after skipping: ${target.id}`
         );
         return {
           step: target,
-          isRouteComplete: false,
+          isFlowComplete: false,
           aiContextStrings: allAiContextStrings,
         };
       }
 
       // Target should be skipped too - recurse deeper
       logger.debug(
-        `[RoutingEngine] Skipping step ${target.id} (skipIf condition met), continuing traversal...`
+        `[FlowRouter] Skipping step ${target.id} (skipIf condition met), continuing traversal...`
       );
       const result = await this.findFirstValidStepRecursiveWithConditions(target, templateContext, visited);
 
@@ -504,8 +535,8 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
         allAiContextStrings.push(...result.aiContextStrings);
       }
 
-      // If we found something (a valid step or END_ROUTE), return it
-      if (result.step || result.isRouteComplete) {
+      // If we found something (a valid step or flow complete), return it
+      if (result.step || result.isFlowComplete) {
         return {
           ...result,
           aiContextStrings: allAiContextStrings,
@@ -513,101 +544,114 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
       }
     }
 
-    // No valid steps or END_ROUTE found in this branch
-    return { aiContextStrings: allAiContextStrings };
+    // No valid steps found in this branch — all skipped with no further transitions
+    return {
+      isFlowComplete: true,
+      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)
+   * Returns step with isFlowComplete flag if flow is complete (all steps skipped or no transitions remain)
    * 
-   * NEW: Automatically completes route when all required fields are collected
+   * Flow completion is implicit: when the last step has no transitions, the flow is done.
    */
   async getCandidateStepsWithConditions(
-    route: Route<TContext, TData>,
+    route: Flow<TContext, TData>,
     currentStep: Step<TContext, TData> | undefined,
     templateContext: TemplateContext<TContext, TData>
   ): Promise<CandidateStep<TContext, TData>[]> {
     const candidates: CandidateStep<TContext, TData>[] = [];
 
     if (!currentStep) {
-      // Entering route for the first time — always start the step flow
+      // Entering flow for the first time — always start the step flow
 
       const initialStep = route.initialStep;
-      const skipResult = await initialStep.evaluateSkipIf(templateContext);
+      const skipResult = await initialStep.evaluateSkip(templateContext);
 
       if (skipResult.shouldSkip) {
-        // Initial step should be skipped - recursively traverse to find first non-skipped step or END_ROUTE
+        // Initial step should be skipped - recursively traverse to find first non-skipped step
         const result = await this.findFirstValidStepRecursiveWithConditions(
           initialStep,
           templateContext,
           new Set<string>()
         );
 
-        if (result.isRouteComplete) {
-          // All steps are skipped and we reached END_ROUTE
+        if (result.isFlowComplete) {
+          // All steps are skipped and no transitions remain
           logger.debug(
-            `[RoutingEngine] Route complete on entry: all steps skipped, END_ROUTE reached`
+            `[FlowRouter] Flow complete on entry: all steps skipped, no transitions remain`
           );
           candidates.push({
             step: initialStep,
-            isRouteComplete: true,
+            isFlowComplete: true,
           });
         } else if (result.step) {
           // Found a non-skipped step
           candidates.push({
             step: result.step,
-            isRouteComplete: result.isRouteComplete || false,
+            isFlowComplete: result.isFlowComplete || false,
           });
         }
         // If no step found and not complete, fall through to return empty candidates
       } else {
         candidates.push({
           step: initialStep,
-          isRouteComplete: false,
+          isFlowComplete: false,
         });
       }
       return candidates;
     }
 
-    // Continue normal step progression — routes complete via END_ROUTE, not via data collection
+    // Continue normal step progression — flows complete when last step has no transitions (implicit terminus)
     const transitions = currentStep.getTransitions();
-    let hasEndRoute = false;
+
+    // No transitions means this is the last step — flow is complete
+    if (transitions.length === 0) {
+      logger.debug(
+        `[FlowRouter] Flow complete: current step has no transitions (implicit terminus)`
+      );
+      return [
+        {
+          step: currentStep,
+          isFlowComplete: true,
+        },
+      ];
+    }
 
     for (const transition of transitions) {
       const target = transition;
 
-      // Check for END_ROUTE transition (no target step)
-      if (target && target.id === END_ROUTE_ID) {
-        hasEndRoute = true;
-        continue;
-      }
-
       if (!target) continue;
 
-      const skipResult = await target.evaluateSkipIf(templateContext);
+      const skipResult = await target.evaluateSkip(templateContext);
 
       if (skipResult.shouldSkip) {
         logger.debug(
-          `[RoutingEngine] Skipping step ${target.id} (skipIf condition met)`
+          `[FlowRouter] Skipping step ${target.id} (skip condition met)`
         );
 
-        // Recursively traverse to find next valid step or END_ROUTE
+        // Recursively traverse to find next valid step
         const result = await this.findFirstValidStepRecursiveWithConditions(
           target,
           templateContext,
           new Set<string>([currentStep.id]) // Already visited current step
         );
 
-        if (result.isRouteComplete) {
-          hasEndRoute = true;
+        if (result.isFlowComplete) {
+          // All forward paths lead to terminus
+          candidates.push({
+            step: currentStep,
+            isFlowComplete: true,
+          });
         } else if (result.step) {
           // Found a non-skipped step deeper in the chain
           candidates.push({
             step: result.step,
-            isRouteComplete: result.isRouteComplete || false,
+            isFlowComplete: false,
           });
         }
         continue;
@@ -615,34 +659,22 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
 
       candidates.push({
         step: target,
-        isRouteComplete: hasEndRoute || false,
+        isFlowComplete: false,
       });
     }
 
-    // If no valid candidates found
+    // If no valid candidates found after evaluating all transitions
     if (candidates.length === 0) {
-      // If current step has END_ROUTE transition, the route is complete
-      if (hasEndRoute) {
-        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({
+      // All transitions were skipped — flow is complete
+      logger.debug(
+        `[FlowRouter] Flow complete: all transitions skipped`
+      );
+      return [
+        {
           step: currentStep,
-          isRouteComplete: hasEndRoute || false,
-        });
-      }
+          isFlowComplete: true,
+        },
+      ];
     }
 
     return candidates;
@@ -650,13 +682,13 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
 
   /**
    * Full routing orchestration: builds prompt and schema, calls AI, selects route/step,
-   * and updates the session (including initialData merge when entering a new route).
+   * and updates the session (including initialData merge when entering a new flow).
    *
    * 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.
+   * CROSS-FLOW COMPLETION: Evaluates all flows for completion based on collected data.
    */
-  async decideRouteAndStep(params: {
-    routes: Route<TContext, TData>[];
+  async decideFlowAndStep(params: {
+    flows: Flow<TContext, TData>[];
     session: SessionState<TData>;
     history: Event[];
     agentOptions?: AgentOptions<TContext, TData>;
@@ -664,15 +696,15 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
     context: TContext;
     signal?: AbortSignal;
   }): Promise<{
-    selectedRoute?: Route<TContext, TData>;
+    selectedFlow?: Flow<TContext, TData>;
     selectedStep?: Step<TContext, TData>;
     responseDirectives?: string[];
     session: SessionState<TData>;
-    isRouteComplete?: boolean;
-    completedRoutes?: Route<TContext, TData>[];
+    isFlowComplete?: boolean;
+    completedFlows?: Flow<TContext, TData>[];
   }> {
     const {
-      routes,
+      flows,
       session,
       history,
       agentOptions,
@@ -681,15 +713,15 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
       signal,
     } = params;
 
-    if (routes.length === 0) {
+    if (flows.length === 0) {
       return { session };
     }
 
-    // SESSION RESUME: If the session has a pre-set route and there are no user
+    // SESSION RESUME: If the session has a pre-set flow and there are no user
     // messages in the history, honor the pre-set position without AI routing.
     // This supports programmatic session setup and persistence-based resume.
     const resumeResult = await this.handleSessionResume({
-      routes,
+      flows,
       session,
       history,
       context,
@@ -698,20 +730,33 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
       return resumeResult;
     }
 
-    // CROSS-ROUTE COMPLETION EVALUATION: Check all routes for completion
-    const completedRoutes = this.evaluateRouteCompletions(routes, session.data || {});
+    // Exclude flows that completed earlier in this session unless explicitly
+    // re-entrant. A completed flow surrenders the conversation back to
+    // routing — it cannot be re-selected without `flow.reentrant: true`.
+    const reEntryFiltered = flows.filter(
+      (f) => !isFlowCompletedThisSession(session, f.id) || f.reentrant === true
+    );
+    const excludedFlows = flows.length - reEntryFiltered.length;
+    if (excludedFlows > 0) {
+      logger.debug(
+        `[FlowRouter] Excluded ${excludedFlows} completed (non-reentrant) flow(s) from routing candidates`
+      );
+    }
+
+    // CROSS-FLOW COMPLETION EVALUATION: Check all eligible flows for completion
+    const completedFlows = this.evaluateFlowCompletions(reEntryFiltered, session.data || {});
 
-    // Log completed routes
-    if (completedRoutes.length > 0) {
+    // Log completed flows
+    if (completedFlows.length > 0) {
       logger.debug(
-        `[RoutingEngine] Found ${completedRoutes.length} completed routes: ${completedRoutes.map(r => r.title).join(', ')}`
+        `[FlowRouter] Found ${completedFlows.length} completed routes: ${completedFlows.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],
+    // OPTIMIZATION: Single flow - skip flow scoring, only do step selection
+    if (reEntryFiltered.length === 1) {
+      const result = await this.decideSingleFlowStep({
+        route: reEntryFiltered[0],
         session,
         history,
         agentOptions,
@@ -721,10 +766,19 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
       });
       return {
         ...result,
-        completedRoutes,
+        completedFlows,
       };
     }
 
+    // No eligible flows after re-entry filtering — caller falls back to the
+    // generic non-flow response path.
+    if (reEntryFiltered.length === 0) {
+      logger.debug(
+        `[FlowRouter] All flows completed and none are reentrant — releasing session to fallback`
+      );
+      return { session, completedFlows };
+    }
+
     const lastUserMessage = getLastMessageFromHistory(history);
     const templateContext = createTemplateContext({
       context,
@@ -733,25 +787,24 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
       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);
+    // Apply flow filtering with new condition evaluation system
+    const whenResult = await this.filterFlowsByWhen(reEntryFiltered, templateContext);
 
-    // Use filtered routes for further processing
+    // Use filtered flows for further processing
     const eligibleRoutes = whenResult.eligibleRoutes;
 
-    logger.debug(`[RoutingEngine] Route filtering: ${routes.length} total → ${skipIfResult.eligibleRoutes.length} after skipIf → ${eligibleRoutes.length} after when`);
+    logger.debug(`[FlowRouter] Flow filtering: ${flows.length} total → ${reEntryFiltered.length} after re-entry filter → ${eligibleRoutes.length} after when`);
 
-    let activeRouteSteps: Step<TContext, TData>[] | undefined;
-    let activeRoute: Route<TContext, TData> | undefined;
-    let isRouteComplete = false;
+    let activeFlowSteps: Step<TContext, TData>[] | undefined;
+    let activeFlow: Flow<TContext, TData> | undefined;
+    let isFlowComplete = false;
     let updatedSession = session;
 
-    if (session.currentRoute) {
-      activeRoute = eligibleRoutes.find((r) => r.id === session.currentRoute?.id);
-      if (activeRoute) {
+    if (session.currentFlow) {
+      activeFlow = eligibleRoutes.find((r) => r.id === session.currentFlow?.id);
+      if (activeFlow) {
         const currentStep = session.currentStep
-          ? activeRoute.getStep(session.currentStep.id)
+          ? activeFlow.getStep(session.currentStep.id)
           : undefined;
         const activeTemplateContext = createTemplateContext({
           ...templateContext,
@@ -759,55 +812,55 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
           data: updatedSession.data
         });
         const candidates = await this.getCandidateStepsWithConditions(
-          activeRoute,
+          activeFlow,
           currentStep,
           activeTemplateContext
         );
 
-        // Check if route is complete
+        // Check if flow is complete
         // getCandidateStepsWithConditions now automatically handles completion when required fields are collected
-        if (candidates.length === 1 && candidates[0].isRouteComplete) {
-          isRouteComplete = true;
+        if (candidates.length === 1 && candidates[0].isFlowComplete) {
+          isFlowComplete = true;
           logger.debug(
-            `[RoutingEngine] Route ${activeRoute.title} is complete - all required fields collected or END_ROUTE reached`
+            `[FlowRouter] Flow ${activeFlow.title} is complete - all required fields collected or last step reached`
           );
           // Don't include steps in routing if route is complete
-          activeRouteSteps = undefined;
+          activeFlowSteps = undefined;
         } else if (candidates.length === 0) {
-          // No candidates available — don't end route based on data alone
+          // No candidates available — don't end flow based on data alone
           logger.debug(
-            `[RoutingEngine] Route ${activeRoute.title} has no valid candidate steps`
+            `[FlowRouter] Flow ${activeFlow.title} has no valid candidate steps`
           );
-          activeRouteSteps = undefined;
+          activeFlowSteps = undefined;
         } else {
           // Multiple candidates or single non-complete candidate
-          activeRouteSteps = candidates.map((c) => c.step);
+          activeFlowSteps = candidates.map((c) => c.step);
           logger.debug(
-            `[RoutingEngine] Found ${activeRouteSteps.length} candidate steps for active route`
+            `[FlowRouter] Found ${activeFlowSteps.length} candidate steps for active route`
           );
         }
       }
     }
 
-    const routingSchema = this.buildDynamicRoutingSchema(
+    const routingSchema = this.buildDynamicFlowSchema(
       eligibleRoutes,
       undefined,
-      activeRouteSteps
+      activeFlowSteps
     );
 
     const routingPrompt = await this.buildRoutingPrompt({
       history,
-      routes: eligibleRoutes,
+      flows: eligibleRoutes,
       lastMessage: lastUserMessage,
       agentOptions,
       session,
-      activeRouteSteps,
+      activeFlowSteps,
       context,
     });
 
     const routingResult = await provider.generateMessage<
       TContext,
-      RoutingDecisionOutput
+      FlowRoutingDecisionOutput
     >({
       prompt: routingPrompt,
       history: eventsToHistory(history),
@@ -819,122 +872,89 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
       },
     });
 
-    let selectedRoute: Route<TContext, TData> | undefined;
+    let selectedFlow: Flow<TContext, TData> | undefined;
     let selectedStep: Step<TContext, TData> | undefined;
     let responseDirectives: string[] | undefined;
 
-    if (routingResult.structured?.routes) {
-      // Use cross-route completion evaluation to select optimal route
-      const optimalRoute = this.selectOptimalRoute(
+    if (routingResult.structured?.flows) {
+      // Use cross-flow completion evaluation to select optimal flow
+      const optimalRoute = this.selectOptimalFlow(
         eligibleRoutes,
         updatedSession.data || {},
-        routingResult.structured.routes,
-        updatedSession.currentRoute?.id
+        routingResult.structured.flows,
+        updatedSession.currentFlow?.id
       );
 
-      // If no optimal route found, check why
+      // If no optimal flow found, check why
       if (!optimalRoute) {
         if (eligibleRoutes.length === 0) {
-          // No routes passed filtering
+          // No flows passed filtering
           logger.debug(
-            `[RoutingEngine] No eligible routes available - all routes filtered out`
+            `[FlowRouter] No eligible flows available - all flows filtered out`
           );
-          selectedRoute = undefined;
+          selectedFlow = undefined;
         } else {
-          // Routes exist but selectOptimalRoute returned undefined
-          // This means all routes are 100% complete
+          // Routes exist but selectOptimalFlow returned undefined
+          // This means all flows are 100% complete
           logger.debug(
-            `[RoutingEngine] No optimal route found - all ${eligibleRoutes.length} eligible routes are complete`
+            `[FlowRouter] No optimal route found - all ${eligibleRoutes.length} eligible routes are complete`
           );
-          selectedRoute = undefined;
+          selectedFlow = undefined;
         }
       } else {
-        selectedRoute = optimalRoute;
+        selectedFlow = optimalRoute;
       }
 
       responseDirectives = routingResult.structured.responseDirectives;
 
       if (
-        selectedRoute === activeRoute &&
+        selectedFlow === activeFlow &&
         routingResult.structured.selectedStepId &&
-        activeRoute
+        activeFlow
       ) {
-        selectedStep = activeRoute.getStep(
+        selectedStep = activeFlow.getStep(
           routingResult.structured.selectedStepId
         );
         if (selectedStep) {
           logger.debug(
-            `[RoutingEngine] AI selected step: ${selectedStep.id} in active route`
+            `[FlowRouter] AI selected step: ${selectedStep.id} in active route`
           );
           logger.debug(
-            `[RoutingEngine] Step reasoning: ${routingResult.structured.stepReasoning}`
+            `[FlowRouter] Step reasoning: ${routingResult.structured.stepReasoning}`
           );
         }
       }
 
-      if (selectedRoute) {
-        logger.debug(`[RoutingEngine] Selected route: ${selectedRoute.title}`);
-        updatedSession = this.enterRouteIfNeeded(updatedSession, selectedRoute);
+      if (selectedFlow) {
+        logger.debug(`[FlowRouter] Selected route: ${selectedFlow.title}`);
+        updatedSession = this.enterFlowIfNeeded(updatedSession, selectedFlow);
       }
     }
 
     return {
-      selectedRoute,
+      selectedFlow,
       selectedStep,
       responseDirectives,
       session: updatedSession,
-      isRouteComplete,
-      completedRoutes,
+      isFlowComplete,
+      completedFlows,
     };
   }
 
   /**
-   * Filter routes based on skipIf conditions
-   * @param routes - All available routes
+   * Filter flows based on when conditions
+   * @param routes - Flows that passed skipIf filtering
    * @param templateContext - Context for condition evaluation
-   * @returns Object with eligible routes and collected AI context strings
+   * @returns Object with eligible flows and collected AI context strings
    */
-  async filterRoutesBySkipIf(
-    routes: Route<TContext, TData>[],
+  async filterFlowsByWhen(
+    routes: Flow<TContext, TData>[],
     templateContext: TemplateContext<TContext, TData>
   ): Promise<{
-    eligibleRoutes: Route<TContext, TData>[];
+    eligibleRoutes: Flow<TContext, TData>[];
     aiContextStrings: string[];
   }> {
-    const eligibleRoutes: Route<TContext, TData>[] = [];
-    const aiContextStrings: string[] = [];
-
-    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: Route<TContext, TData>[],
-    templateContext: TemplateContext<TContext, TData>
-  ): Promise<{
-    eligibleRoutes: Route<TContext, TData>[];
-    aiContextStrings: string[];
-  }> {
-    const eligibleRoutes: Route<TContext, TData>[] = [];
+    const eligibleRoutes: Flow<TContext, TData>[] = [];
     const aiContextStrings: string[] = [];
 
     for (const route of routes) {
@@ -943,11 +963,11 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
       // 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 flow 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)`);
+        logger.debug(`[FlowRouter] Flow ${route.title} not eligible (when condition not met)`);
       }
     }
 
@@ -955,22 +975,22 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
   }
 
   /**
-   * Evaluate all routes for completion based on collected data
-   * @param routes - All available routes
+   * Evaluate all flows for completion based on collected data
+   * @param routes - All available flows
    * @param data - Currently collected agent-level data
-   * @returns Array of routes that are complete
+   * @returns Array of flows that are complete
    */
-  evaluateRouteCompletions(routes: Route<TContext, TData>[], data: Partial<TData>): Route<TContext, TData>[] {
+  evaluateFlowCompletions(routes: Flow<TContext, TData>[], data: Partial<TData>): Flow<TContext, TData>[] {
     return routes.filter(route => route.isComplete(data));
   }
 
   /**
-   * Get completion status for all routes
-   * @param routes - All available routes
+   * Get completion status for all flows
+   * @param routes - All available flows
    * @param data - Currently collected agent-level data
-   * @returns Map of route ID to completion progress (0-1)
+   * @returns Map of flow ID to completion progress (0-1)
    */
-  getRouteCompletionStatus(routes: Route<TContext, TData>[], data: Partial<TData>): Map<string, number> {
+  getFlowCompletionStatus(routes: Flow<TContext, TData>[], data: Partial<TData>): Map<string, number> {
     const completionStatus = new Map<string, number>();
 
     for (const route of routes) {
@@ -982,39 +1002,39 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
   }
 
   /**
-   * 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
+   * Find the best flow to continue based on completion status and user intent
+   * Prioritizes flows that are partially complete but not finished
+   * IMPORTANT: Completed flows are excluded to prevent re-entering finished tasks
+   * @param routes - All available flows
    * @param data - Currently collected agent-level data
    * @param routeScores - AI-generated route scores from routing decision
-   * @returns Route that should be prioritized for continuation
+   * @returns Flow that should be prioritized for continuation
    */
-  selectOptimalRoute(
-    routes: Route<TContext, TData>[],
+  selectOptimalFlow(
+    routes: Flow<TContext, TData>[],
     data: Partial<TData>,
     routeScores: Record<string, number>,
     currentRouteId?: string
-  ): Route<TContext, TData> | undefined {
-    const completionStatus = this.getRouteCompletionStatus(routes, data);
-    const switchMargin = this.options?.routeSwitchMargin ?? 15;
+  ): Flow<TContext, TData> | undefined {
+    const completionStatus = this.getFlowCompletionStatus(routes, data);
+    const switchMargin = this.options?.flowSwitchMargin ?? 15;
 
     // Create weighted scores combining AI intent scores with completion progress
-    const weightedScores: Array<{ route: Route<TContext, TData>; score: number }> = [];
+    const weightedScores: Array<{ route: Flow<TContext, TData>; score: number }> = [];
 
     for (const route of routes) {
       const aiScore = routeScores[route.id] || 0;
       const completionProgress = completionStatus.get(route.id) || 0;
 
-      // ALWAYS skip fully completed routes to prevent re-entering finished tasks
+      // ALWAYS skip fully completed flows to prevent re-entering finished tasks
       if (completionProgress >= 1.0) {
         logger.debug(
-          `[RoutingEngine] Excluding completed route: ${route.title} (100% complete)`
+          `[FlowRouter] Excluding completed flow: ${route.title} (100% complete)`
         );
         continue;
       }
 
-      // Boost partially complete routes that match user intent
+      // Boost partially complete flows that match user intent
       let weightedScore = aiScore;
       if (completionProgress > 0 && completionProgress < 1.0) {
         weightedScore += (completionProgress * 20); // Up to 20 point boost
@@ -1031,7 +1051,7 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
     }
 
     // Apply sticky routing: if there's a current route, only switch if the
-    // best alternative exceeds the current route's score by the configured margin
+    // best alternative exceeds the current flow's score by the configured margin
     if (currentRouteId) {
       const currentEntry = weightedScores.find(e => e.route.id === currentRouteId);
       const bestEntry = weightedScores[0];
@@ -1039,14 +1059,14 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
       if (currentEntry && bestEntry.route.id !== currentRouteId) {
         if (bestEntry.score < currentEntry.score + switchMargin) {
           logger.debug(
-            `[RoutingEngine] Staying on current route: ${currentEntry.route.title} ` +
+            `[FlowRouter] Staying on current flow: ${currentEntry.route.title} ` +
             `(current: ${currentEntry.score}, best alternative: ${bestEntry.score}, ` +
             `margin required: ${switchMargin})`
           );
           return currentEntry.route;
         }
         logger.debug(
-          `[RoutingEngine] Switching route: ${currentEntry.route.title} → ${bestEntry.route.title} ` +
+          `[FlowRouter] Switching flow: ${currentEntry.route.title} → ${bestEntry.route.title} ` +
           `(current: ${currentEntry.score}, alternative: ${bestEntry.score}, ` +
           `margin: ${switchMargin})`
         );
@@ -1054,7 +1074,7 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
     }
 
     logger.debug(
-      `[RoutingEngine] Selected optimal route: ${weightedScores[0].route.title} ` +
+      `[FlowRouter] 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})`
@@ -1063,14 +1083,14 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
   }
 
   /**
-   * Build prompt for step selection within a single route
+   * Build prompt for step selection within a single flow
    * @private
    */
   private async buildStepSelectionPrompt(
-    params: BuildStepSelectionPromptParams<TContext, TData> & { includeEndRoute?: boolean }
+    params: BuildStepSelectionPromptParams<TContext, TData> & { includeCompletion?: boolean }
   ): Promise<string> {
     const {
-      route,
+      flow: route,
       currentStep,
       candidates,
       data,
@@ -1080,7 +1100,7 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
       context,
       session,
       stepConditionContext,
-      includeEndRoute = false,
+      includeCompletion = false,
     } = params;
     const templateContext = createTemplateContext({ context, session, history });
     const pc = new PromptComposer<TContext, TData>(templateContext, this.options?.promptSectionCache);
@@ -1090,9 +1110,9 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
       await pc.addAgentMeta(agentOptions);
     }
 
-    // Add route context
+    // Add flow context
     await pc.addInstruction(
-      `Active Route: ${route.title}\nDescription: ${route.description || "N/A"}`
+      `Active Flow: ${route.title}\nDescription: ${route.description || "N/A"}`
     );
 
     // Add current step context
@@ -1102,7 +1122,7 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
         }`
       );
     } else {
-      await pc.addInstruction("Current Step: None (entering route)");
+      await pc.addInstruction("Current Step: None (entering flow)");
     }
 
     // Add collected data context
@@ -1181,10 +1201,10 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
       "- Steps with skipIf conditions that are met have already been filtered out",
     ];
 
-    if (includeEndRoute) {
+    if (includeCompletion) {
       decisionRules.push(
         "",
-        `- You can select '${END_ROUTE_ID}' to complete this route if:`,
+        `- You can select '__COMPLETE__' to complete this flow 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"
@@ -1207,13 +1227,13 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
    */
   private buildStepSelectionSchema(
     validSteps: Step<TContext, TData>[],
-    includeEndRoute: boolean = false
+    includeCompletion: boolean = false
   ): StructuredSchema {
     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);
+    // Add completion option if requested (when required fields are complete)
+    if (includeCompletion) {
+      stepIds.push('__COMPLETE__');
     }
 
     return {
@@ -1229,8 +1249,8 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
         selectedStepId: {
           type: "string",
           nullable: false,
-          description: includeEndRoute
-            ? `The ID of the selected step to transition to, or '${END_ROUTE_ID}' to complete the route`
+          description: includeCompletion
+            ? "The ID of the selected step to transition to, or '__COMPLETE__' to complete the flow"
             : "The ID of the selected step to transition to",
           enum: stepIds,
         },
@@ -1246,10 +1266,10 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
     };
   }
 
-  buildDynamicRoutingSchema(
-    routes: Route<TContext, TData>[],
+  buildDynamicFlowSchema(
+    routes: Flow<TContext, TData>[],
     extrasSchema?: StructuredSchema,
-    activeRouteSteps?: Step<TContext, TData>[]
+    activeFlowSteps?: Step<TContext, TData>[]
   ): StructuredSchema {
     const routeIds = routes.map((r) => r.id);
     const routeProperties: Record<string, StructuredSchema> = {};
@@ -1257,7 +1277,7 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
       routeProperties[id] = {
         type: "number",
         nullable: false,
-        description: `Score for route ${id} based on direct evidence, context and semantic fit (0-100)`,
+        description: `Score for flow ${id} based on direct evidence, context and semantic fit (0-100)`,
         minimum: 0,
         maximum: 100,
       } as StructuredSchema;
@@ -1265,7 +1285,7 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
 
     const base: StructuredSchema = {
       description:
-        "Full intent analysis: score ALL available routes (0-100) using evidence and context",
+        "Full intent analysis: score ALL available flows (0-100) using evidence and context",
       type: "object",
       properties: {
         context: {
@@ -1273,12 +1293,12 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
           nullable: false,
           description: "Brief summary of the user's intent/context",
         },
-        routes: {
+        flows: {
           type: "object",
           properties: routeProperties,
           required: routeIds,
           nullable: false,
-          description: "Mapping of routeId to score (0-100)",
+          description: "Mapping of flowId to score (0-100)",
         },
         responseDirectives: {
           type: "array",
@@ -1287,19 +1307,19 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
             "Optional bullet points the response should address (concise)",
         },
       },
-      required: ["context", "routes"],
+      required: ["context", "flows"],
       additionalProperties: false,
     };
 
-    // Add step selection fields if there's an active route with steps
-    if (activeRouteSteps && activeRouteSteps.length > 0) {
+    // Add step selection fields if there's an active flow with steps
+    if (activeFlowSteps && activeFlowSteps.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),
+          "The step ID to transition to within the active flow (required if continuing in current flow)",
+        enum: activeFlowSteps.map((s) => s.id),
       };
       base.properties.stepReasoning = {
         type: "string",
@@ -1326,11 +1346,11 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
   ): Promise<string> {
     const {
       history,
-      routes,
+      flows: routes,
       lastMessage,
       agentOptions,
       session,
-      activeRouteSteps,
+      activeFlowSteps,
       context,
     } = params;
     const templateContext = createTemplateContext({ context, session, history });
@@ -1343,10 +1363,10 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
     );
 
     // Add session context if available
-    if (session?.currentRoute) {
+    if (session?.currentFlow) {
       const sessionInfo = [
         "Current conversation context:",
-        `- Active route: ${session.currentRoute.title} (${session.currentRoute.id})`,
+        `- Active route: ${session.currentFlow.title} (${session.currentFlow.id})`,
       ];
       if (session.currentStep) {
         sessionInfo.push(`- Current step: ${session.currentStep.id}`);
@@ -1363,18 +1383,18 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
       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 || {});
+      const completionStatus = this.getFlowCompletionStatus(routes, session.data || {});
+      const completedFlows = this.evaluateFlowCompletions(routes, session.data || {});
 
       if (completionStatus.size > 0) {
         const statusInfo = [
           "",
-          "Route completion status based on collected data:",
+          "Flow completion status based on collected data:",
         ];
 
         for (const route of routes) {
           const progress = completionStatus.get(route.id) || 0;
-          const isComplete = completedRoutes.includes(route);
+          const isComplete = completedFlows.includes(route);
           const progressPercent = Math.round(progress * 100);
 
           statusInfo.push(
@@ -1398,15 +1418,15 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
       }
 
       // Add available steps for the active route
-      if (activeRouteSteps && activeRouteSteps.length > 0) {
+      if (activeFlowSteps && activeFlowSteps.length > 0) {
         const stepInfo = [
           "",
           "Available steps in active route (choose one to transition to):",
         ];
         const activeStepConditionContext: string[] = [];
 
-        for (const step of activeRouteSteps) {
-          const idx = activeRouteSteps.indexOf(step);
+        for (const step of activeFlowSteps) {
+          const idx = activeFlowSteps.indexOf(step);
           stepInfo.push(`${idx + 1}. Step: ${step.id}`);
           if (step.description) {
             stepInfo.push(`   Description: ${step.description}`);
@@ -1457,7 +1477,7 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
 
     await pc.addInteractionHistory(history);
     await pc.addLastMessage(lastMessage);
-    await pc.addRoutingOverview(routes);
+    await pc.addFlowOverview(routes);
 
     await pc.addInstruction(
       [