@falai/agent 0.6.3 → 0.6.5

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"
+  >;
 }
 
 /**

package/src/types/session.ts

@@ -24,8 +24,18 @@ export interface SessionState<TExtracted = Record<string, unknown>> {
     enteredAt: Date;
   };
 
-  /** Data extracted during the current route */
-  extracted: Partial<TExtracted>;
+  /**
+   * Data extracted during the current route
+   * This is a convenience reference to extractedByRoute[currentRoute.id]
+   */
+  extracted?: Partial<TExtracted>;
+
+  /**
+   * Extracted data organized by route ID
+   * Preserves data when switching between routes
+   * Format: { "routeId": { ...extractedData } }
+   */
+  extractedByRoute?: Record<string, Partial<unknown>>;
 
   /** History of routes visited in this session */
   routeHistory: Array<{
@@ -55,6 +65,7 @@ export function createSession<TExtracted = Record<string, unknown>>(
   return {
     id: sessionId,
     extracted: {},
+    extractedByRoute: {},
     routeHistory: [],
     metadata: {
       ...metadata,
@@ -66,12 +77,23 @@ export function createSession<TExtracted = Record<string, unknown>>(
 
 /**
  * Helper to update session with new route
+ * Preserves extracted data per route in extractedByRoute map
  */
 export function enterRoute<TExtracted = Record<string, unknown>>(
   session: SessionState<TExtracted>,
   routeId: string,
   routeTitle: string
 ): SessionState<TExtracted> {
+  // Save current route's extracted data before switching
+  const extractedByRoute = { ...session.extractedByRoute };
+  if (
+    session.currentRoute &&
+    session.extracted &&
+    Object.keys(session.extracted).length > 0
+  ) {
+    extractedByRoute[session.currentRoute.id] = session.extracted;
+  }
+
   // Exit current route if exists
   const routeHistory = [...session.routeHistory];
   if (session.currentRoute) {
@@ -83,6 +105,9 @@ export function enterRoute<TExtracted = Record<string, unknown>>(
     }
   }
 
+  // Load extracted data for new route (if resuming) or start fresh
+  const newExtracted = (extractedByRoute[routeId] as Partial<TExtracted>) || {};
+
   // Enter new route
   const now = new Date();
   return {
@@ -93,7 +118,8 @@ export function enterRoute<TExtracted = Record<string, unknown>>(
       enteredAt: now,
     },
     currentState: undefined,
-    extracted: {}, // Reset extracted data for new route
+    extracted: newExtracted, // Load route's data or start fresh
+    extractedByRoute,
     routeHistory: [
       ...routeHistory,
       {
@@ -133,17 +159,27 @@ export function enterState<TExtracted = Record<string, unknown>>(
 
 /**
  * Helper to merge extracted data into session
+ * Updates both the extracted field and the extractedByRoute map
  */
 export function mergeExtracted<TExtracted = Record<string, unknown>>(
   session: SessionState<TExtracted>,
   extracted: Partial<TExtracted>
 ): SessionState<TExtracted> {
+  const newExtracted = {
+    ...session.extracted,
+    ...extracted,
+  };
+
+  // Also update the extractedByRoute map for the current route
+  const extractedByRoute = { ...session.extractedByRoute };
+  if (session.currentRoute) {
+    extractedByRoute[session.currentRoute.id] = newExtracted;
+  }
+
   return {
     ...session,
-    extracted: {
-      ...session.extracted,
-      ...extracted,
-    },
+    extracted: newExtracted,
+    extractedByRoute,
     metadata: {
       ...session.metadata,
       lastUpdatedAt: new Date(),
@@ -167,6 +203,7 @@ export function sessionStateToData<TExtracted = Record<string, unknown>>(
     currentState: session.currentState?.id,
     collectedData: {
       extracted: session.extracted,
+      extractedByRoute: session.extractedByRoute, // Include per-route data
       routeHistory: session.routeHistory,
       currentRouteTitle: session.currentRoute?.title,
       currentStateDescription: session.currentState?.description,
@@ -210,6 +247,9 @@ export function sessionDataToState<TExtracted = Record<string, unknown>>(
         }
       : undefined,
     extracted: (collectedData.extracted as Partial<TExtracted>) || {},
+    extractedByRoute:
+      (collectedData.extractedByRoute as Record<string, Partial<unknown>>) ||
+      {}, // Restore per-route data
     routeHistory:
       (collectedData.routeHistory as SessionState<TExtracted>["routeHistory"]) ||
       [],

package/src/utils/logger.ts

@@ -0,0 +1,19 @@
+import log from "loglevel";
+
+export enum LoggerLevel {
+  DEBUG = "debug",
+  INFO = "info",
+  WARN = "warn",
+  ERROR = "error",
+  SILENT = "silent",
+}
+
+/**
+ * Default log level
+ */
+const DEFAULT_LOG_LEVEL = LoggerLevel.SILENT;
+
+// Initialize logger
+log.setLevel(DEFAULT_LOG_LEVEL);
+
+export const logger = log;