@falai/agent 0.5.4 → 0.6.0

package/examples/travel-agent.ts

@@ -223,7 +223,7 @@ async function createTravelAgent() {
     description:
       "Helps the customer find and book a flight to their desired destination.",
     conditions: ["The customer wants to book a flight"],
-    gatherSchema: {
+    extractionSchema: {
       type: "object",
       properties: {
         destination: {
@@ -274,11 +274,13 @@ async function createTravelAgent() {
     chatState: "Ask about the destination",
     gather: ["destination"],
     skipIf: (extracted) => !!extracted.destination,
+    condition: "Customer needs to specify their travel destination",
   });
 
   const enrichDestination = askDestination.transitionTo({
     toolState: lookupDestinationCode,
     requiredData: ["destination"],
+    condition: "Destination provided, lookup airport code",
   });
 
   const askDates = enrichDestination.transitionTo({
@@ -286,6 +288,7 @@ async function createTravelAgent() {
     gather: ["departureDate"],
     skipIf: (extracted) => !!extracted.departureDate,
     requiredData: ["destination"],
+    condition: "Destination confirmed, need travel dates",
   });
 
   const askPassengers = askDates.transitionTo({
@@ -293,32 +296,41 @@ async function createTravelAgent() {
     gather: ["passengers"],
     skipIf: (extracted) => !!extracted.passengers,
     requiredData: ["destination", "departureDate"],
+    condition: "Dates confirmed, need passenger count",
   });
 
   const searchFlightsState = askPassengers.transitionTo({
     toolState: searchFlights,
     // Triggered when shouldSearchFlights flag is set by hook
+    condition: "All basic info gathered, search for available flights",
   });
 
   const presentFlights = searchFlightsState.transitionTo({
     chatState: "Present available flights and ask which one works for them",
+    condition: "Flight search complete, present options to customer",
   });
 
   // Happy path: customer selects a flight
   const confirmBooking = presentFlights.transitionTo({
     chatState: "Confirm booking details before proceeding",
     gather: ["cabinClass", "urgency"], // Additional optional data
+    condition: "Customer interested in a flight, confirm booking details",
   });
 
   const bookFlightState = confirmBooking.transitionTo({
     toolState: bookFlight,
+    condition: "Customer confirmed, proceed with booking",
   });
 
   const provideConfirmation = bookFlightState.transitionTo({
     chatState: "Provide confirmation number and booking summary",
+    condition: "Booking completed successfully",
   });
 
-  provideConfirmation.transitionTo({ state: END_ROUTE });
+  provideConfirmation.transitionTo({
+    state: END_ROUTE,
+    condition: "Customer has confirmation, booking flow complete",
+  });
 
   // Add route-specific guidelines
   flightBookingRoute.createGuideline({
@@ -340,7 +352,7 @@ async function createTravelAgent() {
     description:
       "Retrieves the customer's booking status and provides relevant information.",
     conditions: ["The customer wants to check their booking status"],
-    gatherSchema: {
+    extractionSchema: {
       type: "object",
       properties: {
         confirmationNumber: {
@@ -360,18 +372,25 @@ async function createTravelAgent() {
     chatState: "Ask for the confirmation number or booking reference",
     gather: ["confirmationNumber"],
     skipIf: (extracted) => !!extracted.confirmationNumber,
+    condition:
+      "Customer wants to check booking status but hasn't provided confirmation number",
   });
 
   const checkStatus = askConfirmation.transitionTo({
     toolState: getBookingStatus,
     requiredData: ["confirmationNumber"],
+    condition: "Confirmation number provided, look up booking details",
   });
 
   const provideStatus = checkStatus.transitionTo({
     chatState: "Provide booking status and relevant information",
+    condition: "Booking status retrieved successfully",
   });
 
-  provideStatus.transitionTo({ state: END_ROUTE });
+  provideStatus.transitionTo({
+    state: END_ROUTE,
+    condition: "Booking information provided to customer",
+  });
 
   // Global guidelines
   agent.createGuideline({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "description": "Standalone, strongly-typed AI Agent framework with route DSL and AI provider strategy",
   "type": "module",
   "main": "./dist/cjs/index.js",

package/src/core/Agent.ts

@@ -3,18 +3,12 @@
  */
 
 import type { AgentOptions, Term, Guideline, Capability } from "../types/agent";
-import type { Event, StateRef, MessageEventData } from "../types/index";
+import type { Event, StateRef } from "../types/index";
 import type { RouteOptions } from "../types/route";
-import type { RoutingDecisionOutput } from "./RoutingEngine";
+
 import type { SessionState } from "../types/session";
 import type { AgentStructuredResponse } from "../types/ai";
-import {
-  createSession,
-  enterRoute,
-  enterState,
-  mergeExtracted,
-} from "../types/session";
-import { EventKind } from "../types/history";
+import { createSession, enterState, mergeExtracted } from "../types/session";
 import { PromptComposer } from "./PromptComposer";
 
 import { Route } from "./Route";
@@ -24,19 +18,7 @@ import { PersistenceManager } from "./PersistenceManager";
 import { RoutingEngine } from "./RoutingEngine";
 import { ResponseEngine } from "./ResponseEngine";
 import { ToolExecutor } from "./ToolExecutor";
-
-/**
- * Helper to extract last message from history
- */
-function getLastMessageFromHistory(history: Event[]): string {
-  for (let i = history.length - 1; i >= 0; i--) {
-    const event = history[i];
-    if (event.kind === EventKind.MESSAGE) {
-      return (event.data as MessageEventData).message;
-    }
-  }
-  return "";
-}
+import { getLastMessageFromHistory } from "../utils/event";
 
 /**
  * Main Agent class with generic context support
@@ -275,57 +257,6 @@ export class Agent<TContext = unknown> {
     return this.context;
   }
 
-  /**
-   * Determine the next state in a route based on extracted data
-   * @internal
-   */
-  private getNextState<TExtracted = unknown>(
-    route: Route<TContext, TExtracted>,
-    currentState: State<TContext, TExtracted> | undefined,
-    extracted: Partial<TExtracted>
-  ): State<TContext, TExtracted> {
-    // If no current state, start from initial state
-    if (!currentState) {
-      // Check if initial state should be skipped
-      if (route.initialState.shouldSkip(extracted)) {
-        return this.getNextState(route, route.initialState, extracted);
-      }
-      return route.initialState;
-    }
-
-    // Get transitions from current state
-    const transitions = currentState.getTransitions();
-
-    // If no transitions, stay in current state
-    if (transitions.length === 0) {
-      return currentState;
-    }
-
-    // Try to find the next state to transition to
-    for (const transition of transitions) {
-      const target = transition.getTarget();
-      if (!target) continue;
-
-      // Check if target state should be skipped
-      if (target.shouldSkip(extracted)) {
-        // Recursively find next non-skipped state
-        return this.getNextState(route, target, extracted);
-      }
-
-      // Check if target state has required data
-      if (!target.hasRequiredData(extracted)) {
-        // Cannot enter this state yet, stay in current state
-        continue;
-      }
-
-      // Found valid next state
-      return target;
-    }
-
-    // No valid transition found, stay in current state
-    return currentState;
-  }
-
   /**
    * Generate a response based on history and context as a stream
    */
@@ -414,106 +345,66 @@ export class Agent<TContext = unknown> {
       }
     }
 
-    // PHASE 2: ROUTING - Determine which route to use
+    // PHASE 2: ROUTING + STATE SELECTION - Determine which route and state to use (combined)
     let selectedRoute: Route<TContext> | undefined;
     let responseDirectives: string[] | undefined;
+    let selectedState: State<TContext> | undefined;
 
     if (this.routes.length > 0) {
-      // Get last user message
-      const lastUserMessage = getLastMessageFromHistory(history);
-
-      // Build routing schema
-      const routingSchema = this.routingEngine.buildDynamicRoutingSchema(
-        this.routes
-      );
-
-      // Build routing prompt with session context
-      const routingPrompt = this.routingEngine.buildRoutingPrompt(
+      const orchestration = await this.routingEngine.decideRouteAndState({
+        routes: this.routes,
+        session,
         history,
-        this.routes,
-        lastUserMessage,
-        {
+        agentMeta: {
           name: this.options.name,
           goal: this.options.goal,
           description: this.options.description,
           personality: this.options.personality,
         },
-        session // Pass session for context-aware routing
-      );
-
-      // Call AI to score routes (non-streaming for routing decision)
-      const routingResult = await this.options.ai.generateMessage<
-        TContext,
-        RoutingDecisionOutput
-      >({
-        prompt: routingPrompt,
-        history,
+        ai: this.options.ai,
         context: effectiveContext,
         signal,
-        parameters: {
-          jsonSchema: routingSchema,
-          schemaName: "routing_output",
-        },
       });
 
-      // Select best route from scores
-      if (routingResult.structured?.routes) {
-        const decision = this.routingEngine.decideRouteFromScores({
-          context: routingResult.structured.context,
-          routes: routingResult.structured.routes,
-          responseDirectives: routingResult.structured.responseDirectives,
-        });
-        selectedRoute = this.routes.find((r) => r.id === decision.routeId);
-        responseDirectives = routingResult.structured.responseDirectives;
+      selectedRoute = orchestration.selectedRoute;
+      selectedState = orchestration.selectedState;
+      responseDirectives = orchestration.responseDirectives;
+      session = orchestration.session;
+    }
 
-        if (selectedRoute) {
+    // PHASE 3: DETERMINE NEXT STATE - Use state from combined decision or get initial state
+    if (selectedRoute) {
+      let nextState: State<TContext>;
+
+      // If we have a selected state from the combined routing decision, use it
+      if (selectedState) {
+        nextState = selectedState;
+      } else {
+        // New route or no state selected - get initial state or first valid state
+        const candidates = this.routingEngine.getCandidateStates(
+          selectedRoute,
+          undefined,
+          session.extracted
+        );
+        if (candidates.length > 0) {
+          nextState = candidates[0].state;
           console.log(
-            `[Agent] Selected route: ${selectedRoute.title} (score: ${decision.maxScore})`
+            `[Agent] Using first valid state: ${nextState.id} for new route`
+          );
+        } else {
+          // Fallback to initial state even if it should be skipped
+          nextState = selectedRoute.initialState;
+          console.warn(
+            `[Agent] No valid states found, using initial state: ${nextState.id}`
           );
-
-          // Update session with selected route (if changed)
-          if (
-            !session.currentRoute ||
-            session.currentRoute.id !== selectedRoute.id
-          ) {
-            session = enterRoute(
-              session,
-              selectedRoute.id,
-              selectedRoute.title
-            );
-
-            // Merge initial data if provided by the route
-            if (selectedRoute.initialData) {
-              session = mergeExtracted(session, selectedRoute.initialData);
-              console.log(
-                `[Agent] Merged initial data:`,
-                selectedRoute.initialData
-              );
-            }
-
-            console.log(`[Agent] Entered route: ${selectedRoute.title}`);
-          }
         }
       }
-    }
-
-    // PHASE 3: RESPONSE - Stream message using selected route
-    if (selectedRoute) {
-      // Determine next state based on current extracted data
-      const currentStateRef = session.currentState;
-      const currentState = currentStateRef
-        ? selectedRoute.getState(currentStateRef.id)
-        : undefined;
-      const nextState = this.getNextState(
-        selectedRoute,
-        currentState,
-        session.extracted
-      );
 
       // Update session with next state
       session = enterState(session, nextState.id, nextState.description);
       console.log(`[Agent] Entered state: ${nextState.id}`);
 
+      // PHASE 4: RESPONSE GENERATION - Stream message using selected route and state
       // Get last user message
       const lastUserMessage = getLastMessageFromHistory(history);
 
@@ -742,111 +633,71 @@ export class Agent<TContext = unknown> {
       }
     }
 
-    // PHASE 2: ROUTING - Determine which route to use
+    // PHASE 2: ROUTING + STATE SELECTION - Determine which route and state to use (combined)
     let selectedRoute: Route<TContext> | undefined;
     let responseDirectives: string[] | undefined;
+    let selectedState: State<TContext> | undefined;
 
     if (this.routes.length > 0) {
-      // Get last user message
-      const lastUserMessage = getLastMessageFromHistory(history);
-
-      // Build routing schema
-      const routingSchema = this.routingEngine.buildDynamicRoutingSchema(
-        this.routes
-      );
-
-      // Build routing prompt with session context
-      const routingPrompt = this.routingEngine.buildRoutingPrompt(
+      const orchestration = await this.routingEngine.decideRouteAndState({
+        routes: this.routes,
+        session,
         history,
-        this.routes,
-        lastUserMessage,
-        {
+        agentMeta: {
           name: this.options.name,
           goal: this.options.goal,
           description: this.options.description,
           personality: this.options.personality,
         },
-        session // Pass session for context-aware routing
-      );
-
-      // Call AI to score routes
-      const routingResult = await this.options.ai.generateMessage<
-        TContext,
-        RoutingDecisionOutput
-      >({
-        prompt: routingPrompt,
-        history,
+        ai: this.options.ai,
         context: effectiveContext,
         signal,
-        parameters: {
-          jsonSchema: routingSchema,
-          schemaName: "routing_output",
-        },
       });
 
-      // Select best route from scores
-      if (routingResult.structured?.routes) {
-        const decision = this.routingEngine.decideRouteFromScores({
-          context: routingResult.structured.context,
-          routes: routingResult.structured.routes,
-          responseDirectives: routingResult.structured.responseDirectives,
-        });
-        selectedRoute = this.routes.find((r) => r.id === decision.routeId);
-        responseDirectives = routingResult.structured.responseDirectives;
-
-        if (selectedRoute) {
-          console.log(
-            `[Agent] Selected route: ${selectedRoute.title} (score: ${decision.maxScore})`
-          );
-
-          // Update session with selected route (if changed)
-          if (
-            !session.currentRoute ||
-            session.currentRoute.id !== selectedRoute.id
-          ) {
-            session = enterRoute(
-              session,
-              selectedRoute.id,
-              selectedRoute.title
-            );
-
-            // Merge initial data if provided by the route
-            if (selectedRoute.initialData) {
-              session = mergeExtracted(session, selectedRoute.initialData);
-              console.log(
-                `[Agent] Merged initial data:`,
-                selectedRoute.initialData
-              );
-            }
-
-            console.log(`[Agent] Entered route: ${selectedRoute.title}`);
-          }
-        }
-      }
+      selectedRoute = orchestration.selectedRoute;
+      selectedState = orchestration.selectedState;
+      responseDirectives = orchestration.responseDirectives;
+      session = orchestration.session;
     }
 
-    // PHASE 3: RESPONSE - Generate message using selected route
+    // PHASE 3: DETERMINE NEXT STATE - Use state from combined decision or get initial state
     let message: string;
     const toolCalls:
       | Array<{ toolName: string; arguments: Record<string, unknown> }>
       | undefined = undefined;
 
     if (selectedRoute) {
-      // Determine next state based on current extracted data
-      const currentStateRef = session.currentState;
-      const currentState = currentStateRef
-        ? selectedRoute.getState(currentStateRef.id)
-        : undefined;
-      const nextState = this.getNextState(
-        selectedRoute,
-        currentState,
-        session.extracted
-      );
+      let nextState: State<TContext>;
+
+      // If we have a selected state from the combined routing decision, use it
+      if (selectedState) {
+        nextState = selectedState;
+      } else {
+        // New route or no state selected - get initial state or first valid state
+        const candidates = this.routingEngine.getCandidateStates(
+          selectedRoute,
+          undefined,
+          session.extracted
+        );
+        if (candidates.length > 0) {
+          nextState = candidates[0].state;
+          console.log(
+            `[Agent] Using first valid state: ${nextState.id} for new route`
+          );
+        } else {
+          // Fallback to initial state even if it should be skipped
+          nextState = selectedRoute.initialState;
+          console.warn(
+            `[Agent] No valid states found, using initial state: ${nextState.id}`
+          );
+        }
+      }
 
       // Update session with next state
       session = enterState(session, nextState.id, nextState.description);
       console.log(`[Agent] Entered state: ${nextState.id}`);
 
+      // PHASE 4: RESPONSE GENERATION - Generate message using selected route and state
       // Get last user message
       const lastUserMessage = getLastMessageFromHistory(history);
 

package/src/core/ResponseEngine.ts

@@ -30,9 +30,9 @@ export class ResponseEngine<TContext = unknown> {
     }
 
     // Add gather fields from current state
-    if (currentState?.gatherFields && route.gatherSchema?.properties) {
+    if (currentState?.gatherFields && route.extractionSchema?.properties) {
       for (const field of currentState.gatherFields) {
-        const fieldSchema = route.gatherSchema.properties[field];
+        const fieldSchema = route.extractionSchema.properties[field];
         if (fieldSchema) {
           base.properties![field] = fieldSchema;
         }

package/src/core/Route.ts

@@ -2,7 +2,12 @@
  * Route (Journey) DSL implementation
  */
 
-import type { RouteOptions, RouteRef } from "../types/route";
+import type {
+  RouteOptions,
+  RouteRef,
+  TransitionSpec,
+  TransitionResult,
+} from "../types/route";
 import type { StructuredSchema } from "../types/schema";
 import type { Guideline } from "../types/agent";
 
@@ -22,7 +27,7 @@ export class Route<TContext = unknown, TExtracted = unknown> {
   public readonly prohibitions: string[];
   public readonly initialState: State<TContext, TExtracted>;
   public readonly responseOutputSchema?: StructuredSchema;
-  public readonly gatherSchema?: StructuredSchema;
+  public readonly extractionSchema?: StructuredSchema;
   public readonly initialData?: Partial<TExtracted>;
   private routingExtrasSchema?: StructuredSchema;
   private guidelines: Guideline[] = [];
@@ -42,7 +47,7 @@ export class Route<TContext = unknown, TExtracted = unknown> {
     );
     this.routingExtrasSchema = options.routingExtrasSchema;
     this.responseOutputSchema = options.responseOutputSchema;
-    this.gatherSchema = options.gatherSchema;
+    this.extractionSchema = options.extractionSchema;
     this.initialData = options.initialData;
 
     // Initialize guidelines from options
@@ -51,6 +56,32 @@ export class Route<TContext = unknown, TExtracted = unknown> {
         this.createGuideline(guideline);
       });
     }
+
+    // Build sequential steps if provided
+    if (options.steps && options.steps.length > 0) {
+      this.buildSequentialSteps(options.steps);
+    }
+  }
+
+  /**
+   * Build a sequential state machine from an array of steps
+   * @private
+   */
+  private buildSequentialSteps(
+    steps: Array<TransitionSpec<TContext, TExtracted>>
+  ): void {
+    // Import END_ROUTE dynamically to avoid circular dependency
+    const END_ROUTE = Symbol.for("END_ROUTE");
+
+    let currentState: TransitionResult<TContext, TExtracted> =
+      this.initialState;
+
+    for (const step of steps) {
+      currentState = currentState.transitionTo(step);
+    }
+
+    // End the route
+    currentState.transitionTo({ state: END_ROUTE });
   }
 
   /**