@falai/agent 0.6.3 → 0.6.4

package/examples/streaming-agent.ts

@@ -14,6 +14,7 @@ import {
   OpenAIProvider,
   GeminiProvider,
   createSession,
+  END_STATE,
 } from "../src/index";
 
 // Custom context type
@@ -257,6 +258,37 @@ async function streamingWithRoutes() {
     chatState: "Understand the user's product question",
   });
 
+  // Create a feedback route
+  const feedbackRoute = agent.createRoute<{
+    rating: number;
+    comments: string;
+  }>({
+    title: "Collect Feedback",
+    description: "Collect user feedback on their support experience",
+    conditions: ["User wants to provide feedback"],
+    extractionSchema: {
+      type: "object",
+      properties: {
+        rating: { type: "number", minimum: 1, maximum: 5 },
+        comments: { type: "string" },
+      },
+      required: ["rating"],
+    },
+    steps: [
+      {
+        chatState: "How would you rate your support experience from 1 to 5?",
+        gather: ["rating"],
+      },
+      {
+        chatState: "Thanks for the rating! Any other comments?",
+        gather: ["comments"],
+      },
+      {
+        chatState: "We appreciate your feedback!",
+      },
+    ],
+  });
+
   const history = [
     createMessageEvent(
       EventSource.CUSTOMER,
@@ -285,6 +317,19 @@ async function streamingWithRoutes() {
         );
         console.log(`   - Extracted:`, chunk.session?.extracted || "None");
 
+        // Check for route completion
+        if (chunk.isRouteComplete) {
+          console.log("\n✅ Route complete!");
+          if (chunk.session?.currentRoute?.title === "Collect Feedback") {
+            await logFeedback(
+              agent.getExtractedData(chunk.session?.id) as {
+                rating: number;
+                comments: string;
+              }
+            );
+          }
+        }
+
         // Update session with progress
         session = chunk.session!;
       }
@@ -372,6 +417,21 @@ async function streamingWithAbortSignal() {
   }
 }
 
+/**
+ * Mock function to log feedback.
+ * @param data - The feedback data.
+ */
+async function logFeedback(data: { rating: number; comments: string }) {
+  console.log("\n" + "=".repeat(60));
+  console.log("📝 Logging Feedback...");
+  console.log("=".repeat(60));
+  console.log("Feedback Details:", JSON.stringify(data, null, 2));
+  console.log(`   - Rating: ${data.rating}`);
+  console.log(`   - Comments: ${data.comments}`);
+  await new Promise((resolve) => setTimeout(resolve, 1000));
+  console.log("✨ Feedback logged successfully!");
+}
+
 async function main() {
   console.log("🚀 Starting Streaming Examples\n");
   console.log("=".repeat(60));

package/examples/travel-agent.ts

@@ -7,7 +7,7 @@ import {
   Agent,
   defineTool,
   OpenRouterProvider,
-  END_ROUTE,
+  END_STATE,
   EventSource,
   createMessageEvent,
   createSession,
@@ -200,6 +200,7 @@ async function createTravelAgent() {
       customerId: "test-123",
       customerName: "Test Customer",
     },
+    debug: true,
   });
 
   // Add domain glossary
@@ -328,7 +329,7 @@ async function createTravelAgent() {
   });
 
   provideConfirmation.transitionTo({
-    state: END_ROUTE,
+    state: END_STATE,
     condition: "Customer has confirmation, booking flow complete",
   });
 
@@ -388,7 +389,7 @@ async function createTravelAgent() {
   });
 
   provideStatus.transitionTo({
-    state: END_ROUTE,
+    state: END_STATE,
     condition: "Booking information provided to customer",
   });
 
@@ -431,16 +432,16 @@ async function main() {
     ),
   ];
 
-  console.log("Agent:", agent.name);
-  console.log("Description:", agent.description);
+  console.info("Agent:", agent.name);
+  console.info("Description:", agent.description);
 
   // Turn 1 - Agent extracts data and starts booking flow
   const response1 = await agent.respond({ history, session });
-  console.log("\n=== TURN 1 ===");
-  console.log("Agent:", response1.message);
-  console.log("Route:", response1.session?.currentRoute?.title);
-  console.log("State:", response1.session?.currentState?.id);
-  console.log("Extracted:", response1.session?.extracted);
+  console.info("\n=== TURN 1 ===");
+  console.info("Agent:", response1.message);
+  console.info("Route:", response1.session?.currentRoute?.title);
+  console.info("State:", response1.session?.currentState?.id);
+  console.info("Extracted:", response1.session?.extracted);
 
   // Session state updated with progress
   session = response1.session!;
@@ -454,10 +455,10 @@ async function main() {
     ];
 
     const response2 = await agent.respond({ history: history2, session });
-    console.log("\n=== TURN 2 ===");
-    console.log("Agent:", response2.message);
-    console.log("Updated extracted:", response2.session?.extracted);
-    console.log("Current state:", response2.session?.currentState?.id);
+    console.info("\n=== TURN 2 ===");
+    console.info("Agent:", response2.message);
+    console.info("Updated extracted:", response2.session?.extracted);
+    console.info("Current state:", response2.session?.currentState?.id);
   }
 
   // Demonstrate booking status check
@@ -474,24 +475,65 @@ async function main() {
     history: statusHistory,
     session: statusSession,
   });
-  console.log("\n=== BOOKING STATUS CHECK ===");
-  console.log("Agent:", statusResponse.message);
-  console.log("Route:", statusResponse.session?.currentRoute?.title);
-  console.log("Extracted:", statusResponse.session?.extracted);
+  console.info("\n=== BOOKING STATUS CHECK ===");
+  console.info("Agent:", statusResponse.message);
+  console.info("Route:", statusResponse.session?.currentRoute?.title);
+  console.info("Extracted:", statusResponse.session?.extracted);
 
   // Show session state management benefits
-  console.log("\n=== SESSION STATE BENEFITS ===");
-  console.log("✅ Always-on routing - respects user intent changes");
-  console.log("✅ Data persistence - extracted data survives across turns");
-  console.log(
+  console.info("\n=== SESSION STATE BENEFITS ===");
+  console.info("✅ Always-on routing - respects user intent changes");
+  console.info("✅ Data persistence - extracted data survives across turns");
+  console.info(
     "✅ State progression - intelligent flow based on collected data"
   );
-  console.log("✅ Context awareness - router sees current progress");
+  console.info("✅ Context awareness - router sees current progress");
+
+  if (statusResponse.isRouteComplete) {
+    console.info("\n✅ Booking status check complete!");
+    await logBookingStatusCheck(
+      agent.getExtractedData(
+        statusResponse.session?.id
+      ) as unknown as BookingStatusData
+    );
+  }
+}
+
+/**
+ * Mock function to send a booking confirmation.
+ * @param data - The flight booking data.
+ */
+async function sendBookingConfirmation(data: FlightBookingData) {
+  console.info("\n" + "=".repeat(60));
+  console.info("🚀 Sending Booking Confirmation...");
+  console.info("=".repeat(60));
+  console.info("Booking Details:", JSON.stringify(data, null, 2));
+  console.info(
+    `   - Sending confirmation for ${data.passengers} passengers to ${data.destination}.`
+  );
+  await new Promise((resolve) => setTimeout(resolve, 1000));
+  console.info("✨ Confirmation sent!");
+}
+
+/**
+ * Mock function to log a booking status check.
+ * @param data - The booking status data.
+ */
+async function logBookingStatusCheck(data: BookingStatusData) {
+  console.info("\n" + "=".repeat(60));
+  console.info("📝 Logging Booking Status Check...");
+  console.info("=".repeat(60));
+  console.info("Check Details:", JSON.stringify(data, null, 2));
+  console.info(
+    `   - Logging status check for confirmation #${data.confirmationNumber}.`
+  );
+  await new Promise((resolve) => setTimeout(resolve, 500));
+  console.info("✨ Status check logged!");
 }
 
 // Run if executed directly
 if (import.meta.url === `file://${process.argv[1]}`) {
-  main().catch(console.error);
+  main().catch((err) => console.error(err));
 }
 
 export { createTravelAgent };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "Standalone, strongly-typed AI Agent framework with route DSL and AI provider strategy",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -79,12 +79,13 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.65.0",
     "@google/genai": "^0.3.0",
+    "@types/redis": "^4.0.11",
+    "loglevel": "^1.9.2",
     "openai": "^6.3.0"
   },
   "peerDependencies": {
     "@prisma/client": "^6.0.0",
     "ioredis": "^5.7.0",
-    "redis": "^4.6.0 || ^5.0.0",
     "mongodb": "^6.0.0 || ^7.0.0",
     "pg": "^8.11.0",
     "mysql2": "^3.2.0",

package/src/constants/index.ts

@@ -1,5 +1,10 @@
 /**
  * Special marker to end a route/journey
  */
+export const END_STATE = Symbol("END_STATE");
 
-export const END_ROUTE = Symbol("END_ROUTE");
+/**
+ * String constant for END_STATE comparisons
+ * Use this when checking if currentState.id has reached END_STATE
+ */
+export const END_STATE_ID = "END_STATE";

package/src/core/Agent.ts

@@ -10,6 +10,7 @@ import type { SessionState } from "../types/session";
 import type { AgentStructuredResponse } from "../types/ai";
 import { createSession, enterState, mergeExtracted } from "../types/session";
 import { PromptComposer } from "./PromptComposer";
+import { logger, LoggerLevel } from "../utils/logger";
 
 import { Route } from "./Route";
 import { State } from "./State";
@@ -19,6 +20,7 @@ import { RoutingEngine } from "./RoutingEngine";
 import { ResponseEngine } from "./ResponseEngine";
 import { ToolExecutor } from "./ToolExecutor";
 import { getLastMessageFromHistory } from "../utils/event";
+import { END_STATE_ID } from "../constants";
 
 /**
  * Main Agent class with generic context support
@@ -34,6 +36,7 @@ export class Agent<TContext = unknown> {
   private persistenceManager: PersistenceManager | undefined;
   private routingEngine: RoutingEngine<TContext>;
   private responseEngine: ResponseEngine<TContext>;
+  private currentSession?: SessionState;
 
   /**
    * Dynamic domain property - populated via addDomain
@@ -41,6 +44,11 @@ export class Agent<TContext = unknown> {
   public readonly domain: Record<string, Record<string, unknown>> = {};
 
   constructor(private readonly options: AgentOptions<TContext>) {
+    // Set log level based on debug option
+    if (options.debug) {
+      logger.setLevel(LoggerLevel.DEBUG);
+    }
+
     // Validate context configuration
     if (options.context !== undefined && options.contextProvider) {
       throw new Error(
@@ -51,6 +59,9 @@ export class Agent<TContext = unknown> {
     // Initialize context if provided
     this.context = options.context;
 
+    // Initialize current session if provided
+    this.currentSession = options.session;
+
     // Initialize routing and response engines
     this.routingEngine = new RoutingEngine<TContext>({
       maxCandidates: 5,
@@ -66,7 +77,7 @@ export class Agent<TContext = unknown> {
       // Initialize the adapter if it has an initialize method
       if (options.persistence.adapter.initialize) {
         options.persistence.adapter.initialize().catch((error) => {
-          console.error(
+          logger.error(
             "[Agent] Persistence adapter initialization failed:",
             error
           );
@@ -272,6 +283,7 @@ export class Agent<TContext = unknown> {
     done: boolean;
     session?: SessionState;
     toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
+    isRouteComplete?: boolean;
   }> {
     const { history, contextOverride, signal } = params;
 
@@ -291,8 +303,8 @@ export class Agent<TContext = unknown> {
       ...(contextOverride as Record<string, unknown>),
     } as TContext;
 
-    // Initialize or get session
-    let session = params.session || createSession();
+    // Initialize or get session (use current session if available)
+    let session = params.session || this.currentSession || createSession();
 
     // PHASE 1: TOOL EXECUTION - Execute tools if current state has toolState
     if (session.currentRoute && session.currentState) {
@@ -331,13 +343,13 @@ export class Agent<TContext = unknown> {
                 session,
                 result.extractedUpdate
               );
-              console.log(
+              logger.debug(
                 `[Agent] Tool updated extracted data:`,
                 result.extractedUpdate
               );
             }
 
-            console.log(
+            logger.debug(
               `[Agent] Executed tool: ${result.toolName} (success: ${result.success})`
             );
           }
@@ -349,6 +361,7 @@ export class Agent<TContext = unknown> {
     let selectedRoute: Route<TContext> | undefined;
     let responseDirectives: string[] | undefined;
     let selectedState: State<TContext> | undefined;
+    let isRouteComplete = false;
 
     if (this.routes.length > 0) {
       const orchestration = await this.routingEngine.decideRouteAndState({
@@ -370,10 +383,18 @@ export class Agent<TContext = unknown> {
       selectedState = orchestration.selectedState;
       responseDirectives = orchestration.responseDirectives;
       session = orchestration.session;
+      isRouteComplete = orchestration.isRouteComplete || false;
+
+      // Log if route is complete
+      if (isRouteComplete) {
+        logger.debug(
+          `[Agent] Route complete: all required data collected, END_STATE reached`
+        );
+      }
     }
 
     // PHASE 3: DETERMINE NEXT STATE - Use state from combined decision or get initial state
-    if (selectedRoute) {
+    if (selectedRoute && !isRouteComplete) {
       let nextState: State<TContext>;
 
       // If we have a selected state from the combined routing decision, use it
@@ -388,13 +409,13 @@ export class Agent<TContext = unknown> {
         );
         if (candidates.length > 0) {
           nextState = candidates[0].state;
-          console.log(
+          logger.debug(
             `[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(
+          logger.warn(
             `[Agent] No valid states found, using initial state: ${nextState.id}`
           );
         }
@@ -402,7 +423,7 @@ export class Agent<TContext = unknown> {
 
       // Update session with next state
       session = enterState(session, nextState.id, nextState.description);
-      console.log(`[Agent] Entered state: ${nextState.id}`);
+      logger.debug(`[Agent] Entered state: ${nextState.id}`);
 
       // PHASE 4: RESPONSE GENERATION - Stream message using selected route and state
       // Get last user message
@@ -464,7 +485,7 @@ export class Agent<TContext = unknown> {
           // Merge gathered data into session
           if (Object.keys(gatheredData).length > 0) {
             session = await this.updateExtracted(session, gatheredData);
-            console.log(`[Agent] Extracted data:`, gatheredData);
+            logger.debug(`[Agent] Extracted data:`, gatheredData);
           }
         }
 
@@ -489,19 +510,39 @@ export class Agent<TContext = unknown> {
           this.options.persistence?.autoSave !== false
         ) {
           await this.persistenceManager.saveSessionState(session.id, session);
-          console.log(
+          logger.debug(
             `[Agent] Auto-saved session state to persistence: ${session.id}`
           );
         }
 
+        // Update current session if we have one
+        if (chunk.done && this.currentSession) {
+          this.currentSession = session;
+        }
+
         yield {
           delta: chunk.delta,
           accumulated: chunk.accumulated,
           done: chunk.done,
           session, // Return updated session
           toolCalls,
+          isRouteComplete,
         };
       }
+    } else if (isRouteComplete && selectedRoute) {
+      // Route is complete - set state to END_STATE marker and yield completion signal
+      session = enterState(session, END_STATE_ID, "Route completed");
+      logger.debug(
+        `[Agent] Route ${selectedRoute.title} completed. Entered END_STATE state.`
+      );
+      yield {
+        delta: "",
+        accumulated: "",
+        done: true,
+        session,
+        toolCalls: undefined,
+        isRouteComplete: true,
+      };
     } else {
       // Fallback: No routes defined, stream a simple response
       const fallbackPrompt = new PromptComposer<TContext>()
@@ -536,12 +577,18 @@ export class Agent<TContext = unknown> {
       });
 
       for await (const chunk of stream) {
+        // Update current session if we have one
+        if (chunk.done && this.currentSession) {
+          this.currentSession = session;
+        }
+
         yield {
           delta: chunk.delta,
           accumulated: chunk.accumulated,
           done: chunk.done,
           session, // Return updated session
           toolCalls: undefined,
+          isRouteComplete: false,
         };
       }
     }
@@ -560,6 +607,7 @@ export class Agent<TContext = unknown> {
     message: string;
     session?: SessionState;
     toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
+    isRouteComplete?: boolean;
   }> {
     const { history, contextOverride, signal } = params;
 
@@ -579,8 +627,9 @@ export class Agent<TContext = unknown> {
       ...(contextOverride as Record<string, unknown>),
     } as TContext;
 
-    // Initialize or get session
-    let session = params.session || createSession();
+    // Initialize or get session (use current session if available)
+    let session =
+      params.session || this.currentSession || createSession<TContext>();
 
     // PHASE 1: TOOL EXECUTION - Execute tools if current state has toolState
     if (session.currentRoute && session.currentState) {
@@ -619,13 +668,13 @@ export class Agent<TContext = unknown> {
                 session,
                 result.extractedUpdate
               );
-              console.log(
+              logger.debug(
                 `[Agent] Tool updated extracted data:`,
                 result.extractedUpdate
               );
             }
 
-            console.log(
+            logger.debug(
               `[Agent] Executed tool: ${result.toolName} (success: ${result.success})`
             );
           }
@@ -637,6 +686,7 @@ export class Agent<TContext = unknown> {
     let selectedRoute: Route<TContext> | undefined;
     let responseDirectives: string[] | undefined;
     let selectedState: State<TContext> | undefined;
+    let isRouteComplete = false;
 
     if (this.routes.length > 0) {
       const orchestration = await this.routingEngine.decideRouteAndState({
@@ -658,6 +708,14 @@ export class Agent<TContext = unknown> {
       selectedState = orchestration.selectedState;
       responseDirectives = orchestration.responseDirectives;
       session = orchestration.session;
+      isRouteComplete = orchestration.isRouteComplete || false;
+
+      // Log if route is complete
+      if (isRouteComplete) {
+        logger.debug(
+          `[Agent] Route complete: all required data collected, END_STATE reached`
+        );
+      }
     }
 
     // PHASE 3: DETERMINE NEXT STATE - Use state from combined decision or get initial state
@@ -666,7 +724,7 @@ export class Agent<TContext = unknown> {
       | Array<{ toolName: string; arguments: Record<string, unknown> }>
       | undefined = undefined;
 
-    if (selectedRoute) {
+    if (selectedRoute && !isRouteComplete) {
       let nextState: State<TContext>;
 
       // If we have a selected state from the combined routing decision, use it
@@ -681,13 +739,13 @@ export class Agent<TContext = unknown> {
         );
         if (candidates.length > 0) {
           nextState = candidates[0].state;
-          console.log(
+          logger.debug(
             `[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(
+          logger.warn(
             `[Agent] No valid states found, using initial state: ${nextState.id}`
           );
         }
@@ -695,7 +753,7 @@ export class Agent<TContext = unknown> {
 
       // Update session with next state
       session = enterState(session, nextState.id, nextState.description);
-      console.log(`[Agent] Entered state: ${nextState.id}`);
+      logger.debug(`[Agent] Entered state: ${nextState.id}`);
 
       // PHASE 4: RESPONSE GENERATION - Generate message using selected route and state
       // Get last user message
@@ -753,7 +811,7 @@ export class Agent<TContext = unknown> {
         // Merge gathered data into session
         if (Object.keys(gatheredData).length > 0) {
           session = mergeExtracted(session, gatheredData);
-          console.log(`[Agent] Extracted data:`, gatheredData);
+          logger.debug(`[Agent] Extracted data:`, gatheredData);
         }
       }
 
@@ -768,6 +826,13 @@ export class Agent<TContext = unknown> {
             .contextUpdate as Partial<TContext>
         );
       }
+    } else if (isRouteComplete && selectedRoute) {
+      // Route is complete - set state to END_STATE marker and return completion signal
+      session = enterState(session, END_STATE_ID, "Route completed");
+      message = "";
+      logger.debug(
+        `[Agent] Route ${selectedRoute.title} completed. Entered END_STATE state.`
+      );
     } else {
       // Fallback: No routes defined, generate a simple response
       const fallbackPrompt = new PromptComposer<TContext>()
@@ -811,15 +876,21 @@ export class Agent<TContext = unknown> {
       this.options.persistence?.autoSave !== false
     ) {
       await this.persistenceManager.saveSessionState(session.id, session);
-      console.log(
+      logger.debug(
         `[Agent] Auto-saved session state to persistence: ${session.id}`
       );
     }
 
+    // Update current session if we have one
+    if (this.currentSession) {
+      this.currentSession = session;
+    }
+
     return {
       message,
       session, // Return updated session with route/state info
       toolCalls,
+      isRouteComplete: !isRouteComplete, // Indicates if the route has reached END_STATE with all data collected
     };
   }
 
@@ -907,4 +978,47 @@ export class Agent<TContext = unknown> {
     const allowedDomains = route.getDomains();
     return this.domainRegistry.getFiltered(allowedDomains);
   }
+
+  /**
+   * Set the current session for convenience methods
+   * @param session - Session state to use for subsequent calls
+   */
+  setCurrentSession(session: SessionState): void {
+    this.currentSession = session;
+  }
+
+  /**
+   * Get the current session (if set)
+   */
+  getCurrentSession(): SessionState | undefined {
+    return this.currentSession;
+  }
+
+  /**
+   * Clear the current session
+   */
+  clearCurrentSession(): void {
+    this.currentSession = undefined;
+  }
+
+  /**
+   * Get extracted data from current session
+   * @param routeId - Optional route ID to get data for (uses current route if not provided)
+   * @returns The extracted data from the current session
+   */
+  getExtractedData<TExtracted = unknown>(
+    routeId?: string
+  ): Partial<TExtracted> {
+    if (!this.currentSession) {
+      return {} as Partial<TExtracted>;
+    }
+    if (routeId) {
+      return (
+        (this.currentSession.extractedByRoute[
+          routeId
+        ] as Partial<TExtracted>) || ({} as Partial<TExtracted>)
+      );
+    }
+    return this.currentSession.extracted as Partial<TExtracted>;
+  }
 }