@falai/agent 0.6.2 → 0.6.4

package/src/core/Events.ts

@@ -81,17 +81,80 @@ export function createMessageEvent(
       extracted?: Record<string, unknown>;
     };
   }
-): Event<MessageEventData> {
-  return {
-    kind: EventKind.MESSAGE,
-    source,
-    data: {
-      participant: { display_name: participantName },
-      message,
-      session: options?.session,
-    },
-    timestamp: options?.timestamp || new Date().toISOString(),
+): Event<MessageEventData>;
+export function createMessageEvent(options: {
+  source: EventSource;
+  participantName: string;
+  message: string;
+  timestamp?: string;
+  session?: {
+    routeId?: string;
+    routeTitle?: string;
+    stateId?: string;
+    stateDescription?: string;
+    extracted?: Record<string, unknown>;
   };
+}): Event<MessageEventData>;
+export function createMessageEvent(
+  sourceOrOptions:
+    | EventSource
+    | {
+        source: EventSource;
+        participantName: string;
+        message: string;
+        timestamp?: string;
+        session?: {
+          routeId?: string;
+          routeTitle?: string;
+          stateId?: string;
+          stateDescription?: string;
+          extracted?: Record<string, unknown>;
+        };
+      },
+  participantName?: string,
+  message?: string,
+  options?: {
+    timestamp?: string;
+    session?: {
+      routeId?: string;
+      routeTitle?: string;
+      stateId?: string;
+      stateDescription?: string;
+      extracted?: Record<string, unknown>;
+    };
+  }
+): Event<MessageEventData> {
+  if (typeof sourceOrOptions === "object") {
+    // New signature: createMessageEvent(options)
+    const {
+      source,
+      participantName: pName,
+      message: msg,
+      ...restOptions
+    } = sourceOrOptions;
+    return {
+      kind: EventKind.MESSAGE,
+      source,
+      data: {
+        participant: { display_name: pName },
+        message: msg,
+        session: restOptions.session,
+      },
+      timestamp: restOptions.timestamp || new Date().toISOString(),
+    };
+  } else {
+    // Original signature: createMessageEvent(source, participantName, message, options)
+    return {
+      kind: EventKind.MESSAGE,
+      source: sourceOrOptions,
+      data: {
+        participant: { display_name: participantName! },
+        message: message!,
+        session: options?.session,
+      },
+      timestamp: options?.timestamp || new Date().toISOString(),
+    };
+  }
 }
 
 /**

package/src/core/Route.ts

@@ -43,7 +43,11 @@ export class Route<TContext = unknown, TExtracted = unknown> {
     this.prohibitions = options.prohibitions || ([] as string[]);
     this.initialState = new State<TContext, TExtracted>(
       this.id,
-      "Initial state"
+      options.initialState?.chatState || "Initial state",
+      options.initialState?.id,
+      options.initialState?.gather,
+      options.initialState?.skipIf,
+      options.initialState?.requiredData
     );
     this.routingExtrasSchema = options.routingExtrasSchema;
     this.responseOutputSchema = options.responseOutputSchema;
@@ -70,8 +74,8 @@ export class Route<TContext = unknown, TExtracted = unknown> {
   private buildSequentialSteps(
     steps: Array<TransitionSpec<TContext, TExtracted>>
   ): void {
-    // Import END_ROUTE dynamically to avoid circular dependency
-    const END_ROUTE = Symbol.for("END_ROUTE");
+    // Import END_STATE dynamically to avoid circular dependency
+    const END_STATE = Symbol.for("END_STATE");
 
     let currentState: TransitionResult<TContext, TExtracted> =
       this.initialState;
@@ -81,7 +85,7 @@ export class Route<TContext = unknown, TExtracted = unknown> {
     }
 
     // End the route
-    currentState.transitionTo({ state: END_ROUTE });
+    currentState.transitionTo({ state: END_STATE });
   }
 
   /**

package/src/core/RoutingEngine.ts

@@ -8,6 +8,7 @@ import type { AiProvider } from "../types/ai";
 import { enterRoute, mergeExtracted } from "../types/session";
 import { PromptComposer } from "./PromptComposer";
 import { getLastMessageFromHistory } from "../utils/event";
+import { logger } from "../utils/logger";
 
 export interface RoutingDecisionOutput {
   context: string;
@@ -69,12 +70,12 @@ export class RoutingEngine<TContext = unknown> {
       updatedSession = enterRoute(session, route.id, route.title);
       if (route.initialData) {
         updatedSession = mergeExtracted(updatedSession, route.initialData);
-        console.log(
+        logger.debug(
           `[RoutingEngine] Single-route: Merged initial data:`,
           route.initialData
         );
       }
-      console.log(
+      logger.debug(
         `[RoutingEngine] Single-route: Entered route: ${route.title}`
       );
     }
@@ -90,7 +91,7 @@ export class RoutingEngine<TContext = unknown> {
     );
 
     if (candidates.length === 0) {
-      console.warn(`[RoutingEngine] Single-route: No valid states found`);
+      logger.warn(`[RoutingEngine] Single-route: No valid states found`);
       return { selectedRoute, session: updatedSession };
     }
 
@@ -98,20 +99,27 @@ export class RoutingEngine<TContext = unknown> {
     if (candidates.length === 1) {
       const isRouteComplete = candidates[0].isRouteComplete;
       if (isRouteComplete) {
-        console.log(
-          `[RoutingEngine] Single-route: Route complete - all data collected`
+        logger.debug(
+          `[RoutingEngine] Single-route: Route complete - all data collected, END_STATE reached`
         );
+        // Don't return a selectedState when route is complete - there's no state to enter
+        return {
+          selectedRoute,
+          selectedState: undefined,
+          session: updatedSession,
+          isRouteComplete: true,
+        };
       } else {
-        console.log(
+        logger.debug(
           `[RoutingEngine] Single-route: Only one valid state: ${candidates[0].state.id}`
         );
+        return {
+          selectedRoute,
+          selectedState: candidates[0].state,
+          session: updatedSession,
+          isRouteComplete: false,
+        };
       }
-      return {
-        selectedRoute,
-        selectedState: candidates[0].state,
-        session: updatedSession,
-        isRouteComplete,
-      };
     }
 
     // Multiple candidates - use AI to select best state
@@ -154,14 +162,14 @@ export class RoutingEngine<TContext = unknown> {
     )?.state;
 
     if (selectedState) {
-      console.log(
+      logger.debug(
         `[RoutingEngine] Single-route: AI selected state: ${selectedState.id}`
       );
-      console.log(
+      logger.debug(
         `[RoutingEngine] Single-route: Reasoning: ${stateResult.structured?.reasoning}`
       );
     } else {
-      console.warn(
+      logger.warn(
         `[RoutingEngine] Single-route: Invalid state ID returned, using first candidate`
       );
     }
@@ -174,9 +182,76 @@ export class RoutingEngine<TContext = unknown> {
     };
   }
 
+  /**
+   * Recursively traverse state chain to find first non-skipped state or END_STATE
+   * @private
+   */
+  private findFirstValidStateRecursive<TExtracted = unknown>(
+    currentState: State<TContext, TExtracted>,
+    extracted: Partial<TExtracted>,
+    visited: Set<string>
+  ): {
+    state?: State<TContext, TExtracted>;
+    condition?: string;
+    isRouteComplete?: boolean;
+  } {
+    // Prevent infinite loops
+    if (visited.has(currentState.id)) {
+      return {};
+    }
+    visited.add(currentState.id);
+
+    const transitions = currentState.getTransitions();
+
+    for (const transition of transitions) {
+      const target = transition.getTarget();
+
+      // Check for END_STATE transition
+      if (
+        !target &&
+        transition.spec.state &&
+        typeof transition.spec.state === "symbol"
+      ) {
+        // Found END_STATE - route is complete
+        return { isRouteComplete: true };
+      }
+
+      if (!target) continue;
+
+      // If target should NOT be skipped, we found our state
+      if (!target.shouldSkip(extracted)) {
+        logger.debug(
+          `[RoutingEngine] Found valid state after skipping: ${target.id}`
+        );
+        return {
+          state: target,
+          condition: transition.condition,
+        };
+      }
+
+      // Target should be skipped too - recurse deeper
+      logger.debug(
+        `[RoutingEngine] Skipping state ${target.id} (skipIf condition met), continuing traversal...`
+      );
+      const result = this.findFirstValidStateRecursive(
+        target,
+        extracted,
+        visited
+      );
+
+      // If we found something (a valid state or END_STATE), return it
+      if (result.state || result.isRouteComplete) {
+        return result;
+      }
+    }
+
+    // No valid states or END_STATE found in this branch
+    return {};
+  }
+
   /**
    * Identify valid next candidate states based on current state and extracted data
-   * Returns state with isRouteComplete flag if route is complete (all states skipped + has END_ROUTE transition)
+   * Returns state with isRouteComplete flag if route is complete (all states skipped + has END_STATE transition)
    */
   getCandidateStates<TExtracted = unknown>(
     route: Route<TContext, TExtracted>,
@@ -200,18 +275,35 @@ export class RoutingEngine<TContext = unknown> {
     if (!currentState) {
       const initialState = route.initialState;
       if (initialState.shouldSkip(extracted)) {
-        const transitions = initialState.getTransitions();
-        for (const transition of transitions) {
-          const target = transition.getTarget();
-          if (target && !target.shouldSkip(extracted)) {
-            candidates.push({
-              state: target,
-              condition: transition.condition,
-              requiredData: target.requiredData,
-              gatherFields: target.gatherFields,
-            });
-          }
+        // Initial state should be skipped - recursively traverse to find first non-skipped state or END_STATE
+        const result = this.findFirstValidStateRecursive(
+          initialState,
+          extracted,
+          new Set<string>()
+        );
+
+        if (result.isRouteComplete) {
+          // All states are skipped and we reached END_STATE
+          logger.debug(
+            `[RoutingEngine] Route complete on entry: all states skipped, END_STATE reached`
+          );
+          return [
+            {
+              state: initialState,
+              condition: "Route complete - all data collected on entry",
+              isRouteComplete: true,
+            },
+          ];
+        } else if (result.state) {
+          // Found a non-skipped state
+          candidates.push({
+            state: result.state,
+            condition: result.condition,
+            requiredData: result.state.requiredData,
+            gatherFields: result.state.gatherFields,
+          });
         }
+        // If no state found and not complete, fall through to return empty candidates
       } else {
         candidates.push({
           state: initialState,
@@ -228,7 +320,7 @@ export class RoutingEngine<TContext = unknown> {
     for (const transition of transitions) {
       const target = transition.getTarget();
 
-      // Check for END_ROUTE transition (no target state)
+      // Check for END_STATE transition (no target state)
       if (
         !target &&
         transition.spec.state &&
@@ -241,9 +333,28 @@ export class RoutingEngine<TContext = unknown> {
       if (!target) continue;
 
       if (target.shouldSkip(extracted)) {
-        console.log(
+        logger.debug(
           `[RoutingEngine] Skipping state ${target.id} (skipIf condition met)`
         );
+
+        // Recursively traverse to find next valid state or END_STATE
+        const result = this.findFirstValidStateRecursive(
+          target,
+          extracted,
+          new Set<string>([currentState.id]) // Already visited current state
+        );
+
+        if (result.isRouteComplete) {
+          hasEndRoute = true;
+        } else if (result.state) {
+          // Found a non-skipped state deeper in the chain
+          candidates.push({
+            state: result.state,
+            condition: result.condition || transition.condition,
+            requiredData: result.state.requiredData,
+            gatherFields: result.state.gatherFields,
+          });
+        }
         continue;
       }
 
@@ -257,10 +368,10 @@ export class RoutingEngine<TContext = unknown> {
 
     // If no valid candidates found
     if (candidates.length === 0) {
-      // If current state has END_ROUTE transition, the route is complete
+      // If current state has END_STATE transition, the route is complete
       if (hasEndRoute) {
-        console.log(
-          `[RoutingEngine] Route complete: all states processed, END_ROUTE reached`
+        logger.debug(
+          `[RoutingEngine] Route complete: all states processed, END_STATE reached`
         );
         // Return current state with completion flag
         return [
@@ -360,7 +471,7 @@ export class RoutingEngine<TContext = unknown> {
         // Check if route is complete
         if (candidates.length === 1 && candidates[0].isRouteComplete) {
           isRouteComplete = true;
-          console.log(
+          logger.debug(
             `[RoutingEngine] Route ${activeRoute.title} is complete - all data collected`
           );
           // Don't include states in routing if route is complete
@@ -373,7 +484,7 @@ export class RoutingEngine<TContext = unknown> {
             requiredData: c.requiredData,
             gatherFields: c.gatherFields,
           }));
-          console.log(
+          logger.debug(
             `[RoutingEngine] Found ${activeRouteStates.length} candidate states for active route`
           );
         }
@@ -432,17 +543,17 @@ export class RoutingEngine<TContext = unknown> {
           routingResult.structured.selectedStateId
         );
         if (selectedState) {
-          console.log(
+          logger.debug(
             `[RoutingEngine] AI selected state: ${selectedState.id} in active route`
           );
-          console.log(
+          logger.debug(
             `[RoutingEngine] State reasoning: ${routingResult.structured.stateReasoning}`
           );
         }
       }
 
       if (selectedRoute) {
-        console.log(`[RoutingEngine] Selected route: ${selectedRoute.title}`);
+        logger.debug(`[RoutingEngine] Selected route: ${selectedRoute.title}`);
         if (
           !session.currentRoute ||
           session.currentRoute.id !== selectedRoute.id
@@ -457,12 +568,12 @@ export class RoutingEngine<TContext = unknown> {
               updatedSession,
               selectedRoute.initialData
             );
-            console.log(
+            logger.debug(
               `[RoutingEngine] Merged initial data:`,
               selectedRoute.initialData
             );
           }
-          console.log(`[RoutingEngine] Entered route: ${selectedRoute.title}`);
+          logger.debug(`[RoutingEngine] Entered route: ${selectedRoute.title}`);
         }
       }
     }

package/src/core/State.ts

@@ -9,7 +9,7 @@ import type {
 } from "../types/route";
 import type { Guideline } from "../types/agent";
 
-import { END_ROUTE } from "../constants";
+import { END_STATE } from "../constants";
 import { Transition } from "./Transition";
 import { generateStateId } from "../utils/id";
 
@@ -20,13 +20,13 @@ export class State<TContext = unknown, TExtracted = unknown> {
   public readonly id: string;
   private transitions: Transition<TContext, TExtracted>[] = [];
   private guidelines: Guideline[] = [];
-  public readonly gatherFields?: string[];
-  public readonly skipIf?: (extracted: Partial<TExtracted>) => boolean;
-  public readonly requiredData?: string[];
+  public gatherFields?: string[];
+  public skipIf?: (extracted: Partial<TExtracted>) => boolean;
+  public requiredData?: string[];
 
   constructor(
     public readonly routeId: string,
-    public readonly description?: string,
+    public description?: string,
     customId?: string,
     gatherFields?: string[],
     skipIf?: (extracted: Partial<TExtracted>) => boolean,
@@ -39,6 +39,31 @@ export class State<TContext = unknown, TExtracted = unknown> {
     this.requiredData = requiredData;
   }
 
+  /**
+   * Configure the state properties after creation
+   * Useful for overriding initial state configuration
+   */
+  configure(config: {
+    description?: string;
+    gatherFields?: string[];
+    skipIf?: (extracted: Partial<TExtracted>) => boolean;
+    requiredData?: string[];
+  }): this {
+    if (config.description !== undefined) {
+      this.description = config.description;
+    }
+    if (config.gatherFields !== undefined) {
+      this.gatherFields = config.gatherFields;
+    }
+    if (config.skipIf !== undefined) {
+      this.skipIf = config.skipIf;
+    }
+    if (config.requiredData !== undefined) {
+      this.requiredData = config.requiredData;
+    }
+    return this;
+  }
+
   /**
    * Create a transition from this state to another
    *
@@ -48,15 +73,15 @@ export class State<TContext = unknown, TExtracted = unknown> {
   transitionTo(
     spec: TransitionSpec<TContext, TExtracted>
   ): TransitionResult<TContext, TExtracted> {
-    // Handle END_ROUTE
+    // Handle END_STATE
     if (
       spec.state &&
       typeof spec.state === "symbol" &&
-      spec.state === END_ROUTE
+      spec.state === END_STATE
     ) {
       const endTransition = new Transition<TContext, TExtracted>(
         this.getRef(),
-        { state: END_ROUTE, condition: spec.condition }
+        { state: END_STATE, condition: spec.condition }
       );
       this.transitions.push(endTransition);
 
@@ -161,7 +186,7 @@ export class State<TContext = unknown, TExtracted = unknown> {
   }
 
   /**
-   * Create a terminal state reference (for END_ROUTE)
+   * Create a terminal state reference (for END_STATE)
    */
   private createTerminalRef(): TransitionResult<TContext, TExtracted> {
     const terminalRef: StateRef = {
@@ -172,7 +197,7 @@ export class State<TContext = unknown, TExtracted = unknown> {
     return {
       ...terminalRef,
       transitionTo: () => {
-        throw new Error("Cannot transition from END_ROUTE state");
+        throw new Error("Cannot transition from END_STATE state");
       },
     };
   }

package/src/core/Tool.ts

@@ -28,7 +28,11 @@ import { generateToolId } from "../utils/id";
  * );
  * ```
  */
-export function defineTool<TContext, TArgs extends unknown[], TResult>(
+export function defineTool<
+  TContext = unknown,
+  TArgs extends unknown[] = unknown[],
+  TResult = unknown
+>(
   name: string,
   handler: ToolHandler<TContext, TArgs, TResult>,
   options?: {
@@ -36,17 +40,70 @@ export function defineTool<TContext, TArgs extends unknown[], TResult>(
     description?: string;
     parameters?: unknown;
   }
+): ToolRef<TContext, TArgs, TResult>;
+export function defineTool<
+  TContext = unknown,
+  TArgs extends unknown[] = unknown[],
+  TResult = unknown
+>(options: {
+  name: string;
+  handler: ToolHandler<TContext, TArgs, TResult>;
+  id?: string;
+  description?: string;
+  parameters?: unknown;
+}): ToolRef<TContext, TArgs, TResult>;
+export function defineTool<
+  TContext = unknown,
+  TArgs extends unknown[] = unknown[],
+  TResult = unknown
+>(
+  nameOrOptions:
+    | string
+    | {
+        name: string;
+        handler: ToolHandler<TContext, TArgs, TResult>;
+        id?: string;
+        description?: string;
+        parameters?: unknown;
+      },
+  handler?: ToolHandler<TContext, TArgs, TResult>,
+  options?: {
+    id?: string;
+    description?: string;
+    parameters?: unknown;
+  }
 ): ToolRef<TContext, TArgs, TResult> {
-  // Use provided ID or generate a deterministic one from the name
-  const id = options?.id || generateToolId(name);
+  if (typeof nameOrOptions === "string") {
+    // Original signature: defineTool(name, handler, options)
+    const name = nameOrOptions;
+    const id = options?.id || generateToolId(name);
+
+    return {
+      id,
+      name,
+      handler: handler!,
+      description: options?.description,
+      parameters: options?.parameters,
+    };
+  } else {
+    // New signature: defineTool(options)
+    const {
+      name,
+      handler: newHandler,
+      id,
+      description,
+      parameters,
+    } = nameOrOptions;
+    const toolId = id || generateToolId(name);
 
-  return {
-    id,
-    name,
-    handler,
-    description: options?.description,
-    parameters: options?.parameters,
-  };
+    return {
+      id: toolId,
+      name,
+      handler: newHandler,
+      description,
+      parameters,
+    };
+  }
 }
 
 /**

package/src/core/Transition.ts

@@ -55,7 +55,7 @@ export class Transition<TContext = unknown, TExtracted = unknown> {
     }
     if (this.spec.state) {
       if (typeof this.spec.state === "symbol") {
-        parts.push("state: END_ROUTE");
+        parts.push("state: END_STATE");
       } else {
         parts.push(`state: ${this.spec.state.id}`);
       }

package/src/index.ts

@@ -62,7 +62,7 @@ export type {
 } from "./adapters/OpenSearchAdapter";
 
 // Constants
-export { END_ROUTE } from "./constants";
+export { END_STATE, END_STATE_ID } from "./constants";
 
 // Utils
 export { generateRouteId, generateStateId, generateToolId } from "./utils/id";

package/src/types/agent.ts

@@ -6,6 +6,7 @@ import type { AiProvider } from "./ai";
 import type { ToolRef } from "./tool";
 import type { RouteOptions } from "./route";
 import type { PersistenceConfig } from "./persistence";
+import type { SessionState } from "./session";
 
 /**
  * Composition mode determines how the agent processes and structures responses
@@ -74,8 +75,12 @@ export interface AgentOptions<TContext = unknown> {
   goal?: string;
   /** Optional personality/tone instructions used in prompts */
   personality?: string;
+  /** Enable debug logging */
+  debug?: boolean;
   /** Default context data available to the agent */
   context?: TContext;
+  /** Optional current session for convenience methods */
+  session?: SessionState;
   /** Context provider function for always-fresh context (alternative to static context) */
   contextProvider?: ContextProvider<TContext>;
   /** Lifecycle hooks for context management */

package/src/types/route.ts

@@ -66,10 +66,19 @@ export interface RouteOptions<TExtracted = unknown> {
   initialData?: Partial<TExtracted>;
   /**
    * NEW: Sequential steps for simple linear flows
-   * If provided, automatically chains the steps from initialState to END_ROUTE
+   * If provided, automatically chains the steps from initialState to END_STATE
    * For complex flows with branching, build the state machine manually instead
    */
   steps?: TransitionSpec<unknown, TExtracted>[];
+  /**
+   * Configure the initial state (optional)
+   * Accepts full TransitionSpec configuration (id, chatState, gather, skipIf, etc.)
+   * Note: toolState and state properties are ignored for initial state
+   */
+  initialState?: Omit<
+    TransitionSpec<unknown, TExtracted>,
+    "toolState" | "state" | "condition"
+  >;
 }
 
 /**