@falai/agent 0.6.3 → 0.6.4

package/README.md

@@ -93,7 +93,6 @@
 
 ---
 
-
 ## 📦 Installation
 
 ```bash
@@ -113,7 +112,7 @@ yarn add @falai/agent
 
 ## 🚀 Quick Start
 
-Build a conversational AI agent in 2 minutes:
+Build a data-driven conversational AI agent in minutes. This example shows how to intelligently gather structured data over multiple turns.
 
 ```typescript
 import {
@@ -122,65 +121,117 @@ import {
   defineTool,
   createMessageEvent,
   EventSource,
+  END_STATE,
+  type ToolContext,
 } from "@falai/agent";
 
-// 1️⃣ Create your agent
+// 1️⃣ Define the data you want to collect
+interface HotelBookingData {
+  hotelName: string;
+  date: string;
+  guests: number;
+}
+
+// 2️⃣ Create your agent
 const agent = new Agent({
   name: "BookingBot",
-  description: "Hotel booking assistant",
+  description: "A hotel booking assistant that gathers information.",
   ai: new GeminiProvider({
     apiKey: process.env.GEMINI_API_KEY!,
-    model: "models/gemini-2.5-flash",
+    model: "models/gemini-2.5-flash", // or your preferred model
   }),
-  context: { userId: "user_123" },
 });
 
-// 2️⃣ Define a simple tool
-const checkAvailability = defineTool(
-  "check_availability",
-  async (ctx, hotelName: string, date: string) => {
-    return { data: `${hotelName} has rooms available on ${date}` };
+// 3️⃣ Define a tool that uses the collected data
+const bookHotel = defineTool(
+  "book_hotel",
+  async ({ extracted }: ToolContext<{}, HotelBookingData>) => {
+    // Logic to book the hotel...
+    return {
+      data: `Booking confirmed for ${extracted?.guests} at ${extracted?.hotelName} on ${extracted?.date}!`,
+    };
   },
-  { description: "Check hotel availability" }
+  { description: "Books a hotel once all information is collected." }
 );
 
-// 3️⃣ Create a route with 2 states
-const bookingRoute = agent.createRoute({
+// 4️⃣ Create a data-driven route
+const bookingRoute = agent.createRoute<HotelBookingData>({
   title: "Book Hotel",
+  description: "Guides the user through the hotel booking process.",
   conditions: ["User wants to book a hotel"],
+  extractionSchema: {
+    type: "object",
+    properties: {
+      hotelName: { type: "string", description: "The name of the hotel." },
+      date: { type: "string", description: "The desired booking date." },
+      guests: { type: "number", description: "The number of guests." },
+    },
+    required: ["hotelName", "date", "guests"],
+  },
+});
+
+// 5️⃣ Build the flow to gather data step-by-step
+const askHotel = bookingRoute.initialState.transitionTo({
+  chatState: "Ask which hotel they want to book",
+  gather: ["hotelName"],
+  skipIf: (extracted) => !!extracted.hotelName, // Skip if we already have it
 });
 
-bookingRoute.initialState
-  .transitionTo({
-    toolState: checkAvailability,
-    condition: "User provided hotel name and date",
-  })
-  .transitionTo({ chatState: "Confirm booking and provide summary" });
+const askDate = askHotel.transitionTo({
+  chatState: "Ask for the booking date",
+  gather: ["date"],
+  skipIf: (extracted) => !!extracted.date,
+});
+
+const askGuests = askDate.transitionTo({
+  chatState: "Ask for the number of guests",
+  gather: ["guests"],
+  skipIf: (extracted) => !!extracted.guests,
+});
 
-// 4️⃣ Start conversing
+const confirmBooking = askGuests.transitionTo({
+  toolState: bookHotel,
+  condition:
+    "All required information (hotel, date, guests) has been collected.",
+});
+
+confirmBooking.transitionTo({
+  state: END_STATE, // End the conversation flow
+});
+
+// 6️⃣ Start conversing
 const response = await agent.respond({
   history: [
     createMessageEvent(
       EventSource.CUSTOMER,
       "Alice",
-      "Book me a room at Grand Hotel for tomorrow"
+      "I want to book a room at the Grand Hotel for 2 people."
     ),
   ],
 });
 
-console.log(response.message); // 🎉 AI handles the rest!
+// The agent sees that `hotelName` and `guests` are provided,
+// skips the first and third steps, and only asks for the date.
+console.log(response.message);
+// Expected: "Sure, for what date would you like to book at the Grand Hotel?"
 ```
 
-**That's it!** The agent will:
-- ✅ Route to the correct conversation flow
-- ✅ Execute tools automatically when conditions match
-- ✅ Generate natural responses based on state
+**That's it!** The data-driven agent will:
+
+- ✅ **Understand the Goal** - Route to the `Book Hotel` flow based on user intent.
+- ✅ **Extract Known Data** - Automatically pull `hotelName` and `guests` from the first message.
+- ✅ **Skip Unneeded Steps** - Use `skipIf` to bypass questions for data it already has.
+- ✅ **Gather Missing Data** - Intelligently ask only for the missing `date`.
+- ✅ **Execute Deterministically** - Call the `bookHotel` tool only when all required data is present.
+
+This creates a flexible and natural conversation, guided by a clear data structure.
 
 📖 **[See more examples →](./docs/EXAMPLES.md)** | **[Full tutorial →](./docs/GETTING_STARTED.md)**
 
 ### ⚡ Advanced Features
 
 **Streaming responses** for real-time UX:
+
 ```typescript
 for await (const chunk of agent.respondStream({ history })) {
   process.stdout.write(chunk.delta);
@@ -188,6 +239,7 @@ for await (const chunk of agent.respondStream({ history })) {
 ```
 
 **Session state** for multi-turn conversations:
+
 ```typescript
 let session = createSession<MyData>();
 const response = await agent.respond({ history, session });
@@ -195,10 +247,11 @@ session = response.session!; // Tracks progress across turns
 ```
 
 **Database persistence** with any adapter:
+
 ```typescript
 import { PrismaAdapter } from "@falai/agent";
 const agent = new Agent({
-  persistence: { adapter: new PrismaAdapter({ prisma }) }
+  persistence: { adapter: new PrismaAdapter({ prisma }) },
 });
 ```
 
@@ -211,15 +264,19 @@ const agent = new Agent({
 📋 **[Complete Documentation Index →](docs/DOCS.md)** - Searchable index of all docs
 
 **Core Guides:**
+
 - 📘 **[Getting Started](./docs/GETTING_STARTED.md)** - Build your first agent in 5 minutes
 - 🏗️ **[Architecture](./docs/ARCHITECTURE.md)** - Design principles & philosophy
 - 🔧 **[API Reference](./docs/API_REFERENCE.md)** - Complete API documentation
 - 📝 **[Examples](./docs/EXAMPLES.md)** - Production-ready code examples
 
 **Feature Guides:**
+
+- 🛤️ **[Routes](./docs/ROUTES.md)** - Creating conversational routes & flows
+- 🔄 **[States](./docs/STATES.md)** - Managing states & transitions
 - 💾 **[Persistence](./docs/PERSISTENCE.md)** - Database integration with adapters
 - 🔒 **[Domains](./docs/DOMAINS.md)** - Optional tool security & organization
-- 🎛️ **[Constructor Options](./docs/CONSTRUCTOR_OPTIONS.md)** - Configuration patterns
+- 🎛️ **[Agent](./docs/AGENT.md)** - Configuration patterns
 - 📊 **[Context Management](./docs/CONTEXT_MANAGEMENT.md)** - Session state & lifecycle hooks
 - 🤖 **[AI Providers](./docs/PROVIDERS.md)** - Anthropic, OpenAI, Gemini, OpenRouter
 
@@ -228,6 +285,7 @@ const agent = new Agent({
 ## 🎯 Examples
 
 **Core Examples:**
+
 - 🏢 **[Business Onboarding](./examples/business-onboarding.ts)** - Complex multi-step flow with branching
 - ✈️ **[Travel Agent](./examples/travel-agent.ts)** - Multi-route booking system with session state
 - 🏥 **[Healthcare Assistant](./examples/healthcare-agent.ts)** - Appointment scheduling & lab results
@@ -235,6 +293,7 @@ const agent = new Agent({
 - ⚡ **[Streaming Responses](./examples/streaming-agent.ts)** - Real-time response streaming
 
 **Persistence & Advanced:**
+
 - 💾 **[Prisma Persistence](./examples/prisma-persistence.ts)** - Auto-save with Prisma ORM
 - ⚡ **[Redis Persistence](./examples/redis-persistence.ts)** - Fast in-memory sessions
 - 🔐 **[Domain Scoping](./examples/domain-scoping.ts)** - Tool security per route
@@ -255,6 +314,7 @@ const agent = new Agent({
 5. **Message Generation** - AI generates natural responses based on current state
 
 **Behind the scenes:**
+
 - The AI only generates messages and extracts data - it never decides which tools to call
 - Tools execute deterministically based on state transitions and code-based conditions
 - Session state tracks progress and extracted data across conversation turns

package/dist/cjs/constants/index.d.ts

@@ -1,5 +1,10 @@
 /**
  * Special marker to end a route/journey
  */
-export declare const END_ROUTE: unique symbol;
+export declare const END_STATE: unique symbol;
+/**
+ * String constant for END_STATE comparisons
+ * Use this when checking if currentState.id has reached END_STATE
+ */
+export declare const END_STATE_ID = "END_STATE";
 //# sourceMappingURL=index.d.ts.map

package/dist/cjs/constants/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/constants/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,SAAS,eAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/constants/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,SAAS,eAAsB,CAAC;AAE7C;;;GAGG;AACH,eAAO,MAAM,YAAY,cAAc,CAAC"}

package/dist/cjs/constants/index.js

@@ -1,8 +1,13 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.END_STATE_ID = exports.END_STATE = void 0;
 /**
  * Special marker to end a route/journey
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.END_ROUTE = void 0;
-exports.END_ROUTE = Symbol("END_ROUTE");
+exports.END_STATE = Symbol("END_STATE");
+/**
+ * String constant for END_STATE comparisons
+ * Use this when checking if currentState.id has reached END_STATE
+ */
+exports.END_STATE_ID = "END_STATE";
 //# sourceMappingURL=index.js.map

package/dist/cjs/constants/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/constants/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEU,QAAA,SAAS,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/constants/index.ts"],"names":[],"mappings":";;;AAAA;;GAEG;AACU,QAAA,SAAS,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;AAE7C;;;GAGG;AACU,QAAA,YAAY,GAAG,WAAW,CAAC"}

package/dist/cjs/core/Agent.d.ts

@@ -22,6 +22,7 @@ export declare class Agent<TContext = unknown> {
     private persistenceManager;
     private routingEngine;
     private responseEngine;
+    private currentSession?;
     /**
      * Dynamic domain property - populated via addDomain
      */
@@ -95,6 +96,7 @@ export declare class Agent<TContext = unknown> {
             toolName: string;
             arguments: Record<string, unknown>;
         }>;
+        isRouteComplete?: boolean;
     }>;
     /**
      * Generate a response based on history and context
@@ -112,6 +114,7 @@ export declare class Agent<TContext = unknown> {
             toolName: string;
             arguments: Record<string, unknown>;
         }>;
+        isRouteComplete?: boolean;
     }>;
     /**
      * Get all routes
@@ -153,5 +156,24 @@ export declare class Agent<TContext = unknown> {
      * @returns Filtered domains object, or all domains if route has no restrictions
      */
     getDomainsForRouteByTitle(routeTitle: string): Record<string, Record<string, unknown>>;
+    /**
+     * Set the current session for convenience methods
+     * @param session - Session state to use for subsequent calls
+     */
+    setCurrentSession(session: SessionState): void;
+    /**
+     * Get the current session (if set)
+     */
+    getCurrentSession(): SessionState | undefined;
+    /**
+     * Clear the current session
+     */
+    clearCurrentSession(): void;
+    /**
+     * 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>;
 }
 //# sourceMappingURL=Agent.d.ts.map

package/dist/cjs/core/Agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../../src/core/Agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../../src/core/Agent.ts"],"names":[],"mappings":"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"}

package/dist/cjs/core/Agent.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Agent = void 0;
 const session_1 = require("../types/session");
 const PromptComposer_1 = require("./PromptComposer");
+const logger_1 = require("../utils/logger");
 const Route_1 = require("./Route");
 const DomainRegistry_1 = require("./DomainRegistry");
 const PersistenceManager_1 = require("./PersistenceManager");
@@ -13,6 +14,7 @@ const RoutingEngine_1 = require("./RoutingEngine");
 const ResponseEngine_1 = require("./ResponseEngine");
 const ToolExecutor_1 = require("./ToolExecutor");
 const event_1 = require("../utils/event");
+const constants_1 = require("../constants");
 /**
  * Main Agent class with generic context support
  */
@@ -29,12 +31,18 @@ class Agent {
          * Dynamic domain property - populated via addDomain
          */
         this.domain = {};
+        // Set log level based on debug option
+        if (options.debug) {
+            logger_1.logger.setLevel(logger_1.LoggerLevel.DEBUG);
+        }
         // Validate context configuration
         if (options.context !== undefined && options.contextProvider) {
             throw new Error("Cannot provide both 'context' and 'contextProvider'. Choose one.");
         }
         // 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_1.RoutingEngine({
             maxCandidates: 5,
@@ -48,7 +56,7 @@ class Agent {
             // Initialize the adapter if it has an initialize method
             if (options.persistence.adapter.initialize) {
                 options.persistence.adapter.initialize().catch((error) => {
-                    console.error("[Agent] Persistence adapter initialization failed:", error);
+                    logger_1.logger.error("[Agent] Persistence adapter initialization failed:", error);
                 });
             }
         }
@@ -218,8 +226,8 @@ class Agent {
             ...currentContext,
             ...contextOverride,
         };
-        // Initialize or get session
-        let session = params.session || (0, session_1.createSession)();
+        // Initialize or get session (use current session if available)
+        let session = params.session || this.currentSession || (0, session_1.createSession)();
         // PHASE 1: TOOL EXECUTION - Execute tools if current state has toolState
         if (session.currentRoute && session.currentState) {
             const currentRoute = this.routes.find((r) => r.id === session.currentRoute?.id);
@@ -240,9 +248,9 @@ class Agent {
                         // Update extracted data with tool results
                         if (result.extractedUpdate) {
                             session = await this.updateExtracted(session, result.extractedUpdate);
-                            console.log(`[Agent] Tool updated extracted data:`, result.extractedUpdate);
+                            logger_1.logger.debug(`[Agent] Tool updated extracted data:`, result.extractedUpdate);
                         }
-                        console.log(`[Agent] Executed tool: ${result.toolName} (success: ${result.success})`);
+                        logger_1.logger.debug(`[Agent] Executed tool: ${result.toolName} (success: ${result.success})`);
                     }
                 }
             }
@@ -251,6 +259,7 @@ class Agent {
         let selectedRoute;
         let responseDirectives;
         let selectedState;
+        let isRouteComplete = false;
         if (this.routes.length > 0) {
             const orchestration = await this.routingEngine.decideRouteAndState({
                 routes: this.routes,
@@ -270,9 +279,14 @@ class Agent {
             selectedState = orchestration.selectedState;
             responseDirectives = orchestration.responseDirectives;
             session = orchestration.session;
+            isRouteComplete = orchestration.isRouteComplete || false;
+            // Log if route is complete
+            if (isRouteComplete) {
+                logger_1.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;
             // If we have a selected state from the combined routing decision, use it
             if (selectedState) {
@@ -283,17 +297,17 @@ class Agent {
                 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`);
+                    logger_1.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(`[Agent] No valid states found, using initial state: ${nextState.id}`);
+                    logger_1.logger.warn(`[Agent] No valid states found, using initial state: ${nextState.id}`);
                 }
             }
             // Update session with next state
             session = (0, session_1.enterState)(session, nextState.id, nextState.description);
-            console.log(`[Agent] Entered state: ${nextState.id}`);
+            logger_1.logger.debug(`[Agent] Entered state: ${nextState.id}`);
             // PHASE 4: RESPONSE GENERATION - Stream message using selected route and state
             // Get last user message
             const lastUserMessage = (0, event_1.getLastMessageFromHistory)(history);
@@ -333,7 +347,7 @@ class Agent {
                     // Merge gathered data into session
                     if (Object.keys(gatheredData).length > 0) {
                         session = await this.updateExtracted(session, gatheredData);
-                        console.log(`[Agent] Extracted data:`, gatheredData);
+                        logger_1.logger.debug(`[Agent] Extracted data:`, gatheredData);
                     }
                 }
                 // Extract any additional data from structured response on final chunk
@@ -350,7 +364,11 @@ class Agent {
                     session.id &&
                     this.options.persistence?.autoSave !== false) {
                     await this.persistenceManager.saveSessionState(session.id, session);
-                    console.log(`[Agent] Auto-saved session state to persistence: ${session.id}`);
+                    logger_1.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,
@@ -358,9 +376,23 @@ class Agent {
                     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 = (0, session_1.enterState)(session, constants_1.END_STATE_ID, "Route completed");
+            logger_1.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_1.PromptComposer()
@@ -393,12 +425,17 @@ class Agent {
                 },
             });
             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,
                 };
             }
         }
@@ -421,8 +458,8 @@ class Agent {
             ...currentContext,
             ...contextOverride,
         };
-        // Initialize or get session
-        let session = params.session || (0, session_1.createSession)();
+        // Initialize or get session (use current session if available)
+        let session = params.session || this.currentSession || (0, session_1.createSession)();
         // PHASE 1: TOOL EXECUTION - Execute tools if current state has toolState
         if (session.currentRoute && session.currentState) {
             const currentRoute = this.routes.find((r) => r.id === session.currentRoute?.id);
@@ -443,9 +480,9 @@ class Agent {
                         // Update extracted data with tool results
                         if (result.extractedUpdate) {
                             session = await this.updateExtracted(session, result.extractedUpdate);
-                            console.log(`[Agent] Tool updated extracted data:`, result.extractedUpdate);
+                            logger_1.logger.debug(`[Agent] Tool updated extracted data:`, result.extractedUpdate);
                         }
-                        console.log(`[Agent] Executed tool: ${result.toolName} (success: ${result.success})`);
+                        logger_1.logger.debug(`[Agent] Executed tool: ${result.toolName} (success: ${result.success})`);
                     }
                 }
             }
@@ -454,6 +491,7 @@ class Agent {
         let selectedRoute;
         let responseDirectives;
         let selectedState;
+        let isRouteComplete = false;
         if (this.routes.length > 0) {
             const orchestration = await this.routingEngine.decideRouteAndState({
                 routes: this.routes,
@@ -473,11 +511,16 @@ class Agent {
             selectedState = orchestration.selectedState;
             responseDirectives = orchestration.responseDirectives;
             session = orchestration.session;
+            isRouteComplete = orchestration.isRouteComplete || false;
+            // Log if route is complete
+            if (isRouteComplete) {
+                logger_1.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
         let message;
         const toolCalls = undefined;
-        if (selectedRoute) {
+        if (selectedRoute && !isRouteComplete) {
             let nextState;
             // If we have a selected state from the combined routing decision, use it
             if (selectedState) {
@@ -488,17 +531,17 @@ class Agent {
                 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`);
+                    logger_1.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(`[Agent] No valid states found, using initial state: ${nextState.id}`);
+                    logger_1.logger.warn(`[Agent] No valid states found, using initial state: ${nextState.id}`);
                 }
             }
             // Update session with next state
             session = (0, session_1.enterState)(session, nextState.id, nextState.description);
-            console.log(`[Agent] Entered state: ${nextState.id}`);
+            logger_1.logger.debug(`[Agent] Entered state: ${nextState.id}`);
             // PHASE 4: RESPONSE GENERATION - Generate message using selected route and state
             // Get last user message
             const lastUserMessage = (0, event_1.getLastMessageFromHistory)(history);
@@ -536,7 +579,7 @@ class Agent {
                 // Merge gathered data into session
                 if (Object.keys(gatheredData).length > 0) {
                     session = (0, session_1.mergeExtracted)(session, gatheredData);
-                    console.log(`[Agent] Extracted data:`, gatheredData);
+                    logger_1.logger.debug(`[Agent] Extracted data:`, gatheredData);
                 }
             }
             // Extract any additional data from structured response
@@ -547,6 +590,12 @@ class Agent {
                     .contextUpdate);
             }
         }
+        else if (isRouteComplete && selectedRoute) {
+            // Route is complete - set state to END_STATE marker and return completion signal
+            session = (0, session_1.enterState)(session, constants_1.END_STATE_ID, "Route completed");
+            message = "";
+            logger_1.logger.debug(`[Agent] Route ${selectedRoute.title} completed. Entered END_STATE state.`);
+        }
         else {
             // Fallback: No routes defined, generate a simple response
             const fallbackPrompt = new PromptComposer_1.PromptComposer()
@@ -585,12 +634,17 @@ class Agent {
             session.id &&
             this.options.persistence?.autoSave !== false) {
             await this.persistenceManager.saveSessionState(session.id, session);
-            console.log(`[Agent] Auto-saved session state to persistence: ${session.id}`);
+            logger_1.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
         };
     }
     /**
@@ -663,6 +717,39 @@ class Agent {
         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) {
+        this.currentSession = session;
+    }
+    /**
+     * Get the current session (if set)
+     */
+    getCurrentSession() {
+        return this.currentSession;
+    }
+    /**
+     * Clear the current session
+     */
+    clearCurrentSession() {
+        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(routeId) {
+        if (!this.currentSession) {
+            return {};
+        }
+        if (routeId) {
+            return (this.currentSession.extractedByRoute[routeId] || {});
+        }
+        return this.currentSession.extracted;
+    }
 }
 exports.Agent = Agent;
 //# sourceMappingURL=Agent.js.map