@falai/agent 0.8.1 → 0.9.0-alpha-1

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,7 +42,32 @@ export interface RoutingEngineOptions {
   maxCandidates?: number;
 }
 
-export class RoutingEngine<TContext = unknown> {
+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>;
+  context?: TContext;
+  session?: SessionState<TData>;
+}
+
+export interface BuildRoutingPromptParams<TContext = unknown, TData = unknown> {
+  history: Event[];
+  routes: Route<TContext, TData>[];
+  lastMessage: string;
+  agentOptions?: AgentOptions<TContext>;
+  session?: SessionState<TData>;
+  activeRouteSteps?: Step<TContext, TData>[];
+  context?: TContext;
+}
+
+export class RoutingEngine<TContext = unknown, TData = unknown> {
   constructor(private readonly options?: RoutingEngineOptions) {}
 
   /**
@@ -41,15 +76,10 @@ 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>;
     provider: AiProvider;
     context: TContext;
     signal?: AbortSignal;
@@ -57,10 +87,10 @@ export class RoutingEngine<TContext = unknown> {
     selectedRoute?: Route<TContext>;
     selectedStep?: Step<TContext>;
     responseDirectives?: string[];
-    session: SessionState;
+    session: SessionState<TData>;
     isRouteComplete?: boolean;
   }> {
-    const { route, session, history, agentMeta, provider, context, signal } =
+    const { route, session, history, agentOptions, provider, context, signal } =
       params;
 
     let updatedSession = session;
@@ -125,18 +155,20 @@ export class RoutingEngine<TContext = unknown> {
 
     // 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 +190,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,7 +207,7 @@ export class RoutingEngine<TContext = unknown> {
 
     return {
       selectedRoute,
-      selectedStep: selectedStep || candidates[0].step,
+      selectedStep: selectedStep?.step || candidates[0].step,
       responseDirectives: stepResult.structured?.responseDirectives,
       session: updatedSession,
     };
@@ -193,7 +223,6 @@ export class RoutingEngine<TContext = unknown> {
     visited: Set<string>
   ): {
     step?: Step<TContext, TData>;
-    condition?: string;
     isRouteComplete?: boolean;
   } {
     // Prevent infinite loops
@@ -205,14 +234,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 +253,7 @@ export class RoutingEngine<TContext = unknown> {
         );
         return {
           step: target,
-          condition: transition.condition,
+          isRouteComplete: false,
         };
       }
 
@@ -256,20 +281,8 @@ export class RoutingEngine<TContext = unknown> {
     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 +299,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 +324,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 +352,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 +360,7 @@ export class RoutingEngine<TContext = unknown> {
 
       candidates.push({
         step: target,
-        condition: transition.condition,
-        requires: target.requires,
-        collectFields: target.collectFields,
+        isRouteComplete: hasEndRoute || false,
       });
     }
 
@@ -376,7 +375,6 @@ export class RoutingEngine<TContext = unknown> {
         return [
           {
             step: currentStep,
-            condition: "Route complete - all data collected",
             isRouteComplete: true,
           },
         ];
@@ -386,9 +384,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,
         });
       }
     }
@@ -403,15 +399,10 @@ export class RoutingEngine<TContext = unknown> {
    * OPTIMIZATION: If there's only 1 route, skips route scoring and only does step selection.
    */
   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>;
     provider: AiProvider;
     context: TContext;
     signal?: AbortSignal;
@@ -419,11 +410,18 @@ export class RoutingEngine<TContext = unknown> {
     selectedRoute?: Route<TContext>;
     selectedStep?: Step<TContext>;
     responseDirectives?: string[];
-    session: SessionState;
+    session: SessionState<TData>;
     isRouteComplete?: boolean;
   }> {
-    const { routes, session, history, agentMeta, provider, context, signal } =
-      params;
+    const {
+      routes,
+      session,
+      history,
+      agentOptions,
+      provider,
+      context,
+      signal,
+    } = params;
 
     if (routes.length === 0) {
       return { session };
@@ -435,7 +433,7 @@ export class RoutingEngine<TContext = unknown> {
         route: routes[0],
         session,
         history,
-        agentMeta,
+        agentOptions,
         provider,
         context,
         signal,
@@ -444,16 +442,8 @@ export class RoutingEngine<TContext = unknown> {
 
     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 +467,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 +481,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,
@@ -591,97 +576,88 @@ export class RoutingEngine<TContext = unknown> {
    * 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<TData>(
+    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(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(
+      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 +683,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 +700,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 +715,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 +767,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 +789,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(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 +828,7 @@ 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 available steps for the active route
       if (activeRouteSteps && activeRouteSteps.length > 0) {
@@ -871,21 +836,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 +863,16 @@ 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);
+    await pc.addInteractionHistory(history);
+    await 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.addRoutingOverview(routes);
+    await pc.addInstruction(
       [
         "Scoring rules:",
         "- 90-100: explicit keywords + clear intent",