@falai/agent 0.6.3 → 0.6.5

package/dist/core/Tool.js

@@ -2,33 +2,30 @@
  * Tool definition and creation utilities
  */
 import { generateToolId } from "../utils/id";
-/**
- * Define a new tool with type-safe context and arguments
- *
- * @param name - Name of the tool
- * @param handler - Handler function that executes the tool
- * @param options - Optional configuration
- * @returns A reference to the defined tool
- *
- * @example
- * ```ts
- * const getTool = defineTool<MyContext, [string, number], string>(
- *   'get_data',
- *   async ({ context }, id, count) => {
- *     return { data: `Retrieved ${count} items for ${id}` };
- *   }
- * );
- * ```
- */
-export function defineTool(name, handler, options) {
-    // Use provided ID or generate a deterministic one from the name
-    const id = options?.id || generateToolId(name);
-    return {
-        id,
-        name,
-        handler,
-        description: options?.description,
-        parameters: options?.parameters,
-    };
+export function defineTool(nameOrOptions, handler, options) {
+    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: toolId,
+            name,
+            handler: newHandler,
+            description,
+            parameters,
+        };
+    }
 }
 //# sourceMappingURL=Tool.js.map

package/dist/core/Tool.js.map

@@ -1 +1 @@
-{"version":3,"file":"Tool.js","sourceRoot":"","sources":["../../src/core/Tool.ts"],"names":[],"mappings":"AAAA;;GAEG;AAQH,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,UAAU,CACxB,IAAY,EACZ,OAA8C,EAC9C,OAIC;IAED,gEAAgE;IAChE,MAAM,EAAE,GAAG,OAAO,EAAE,EAAE,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC;IAE/C,OAAO;QACL,EAAE;QACF,IAAI;QACJ,OAAO;QACP,WAAW,EAAE,OAAO,EAAE,WAAW;QACjC,UAAU,EAAE,OAAO,EAAE,UAAU;KAChC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"Tool.js","sourceRoot":"","sources":["../../src/core/Tool.ts"],"names":[],"mappings":"AAAA;;GAEG;AAQH,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AA4C7C,MAAM,UAAU,UAAU,CAKxB,aAQK,EACL,OAA+C,EAC/C,OAIC;IAED,IAAI,OAAO,aAAa,KAAK,QAAQ,EAAE,CAAC;QACtC,yDAAyD;QACzD,MAAM,IAAI,GAAG,aAAa,CAAC;QAC3B,MAAM,EAAE,GAAG,OAAO,EAAE,EAAE,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC;QAE/C,OAAO;YACL,EAAE;YACF,IAAI;YACJ,OAAO,EAAE,OAAQ;YACjB,WAAW,EAAE,OAAO,EAAE,WAAW;YACjC,UAAU,EAAE,OAAO,EAAE,UAAU;SAChC,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,qCAAqC;QACrC,MAAM,EACJ,IAAI,EACJ,OAAO,EAAE,UAAU,EACnB,EAAE,EACF,WAAW,EACX,UAAU,GACX,GAAG,aAAa,CAAC;QAClB,MAAM,MAAM,GAAG,EAAE,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC;QAE1C,OAAO;YACL,EAAE,EAAE,MAAM;YACV,IAAI;YACJ,OAAO,EAAE,UAAU;YACnB,WAAW;YACX,UAAU;SACX,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/core/Transition.js

@@ -42,7 +42,7 @@ export class Transition {
         }
         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/dist/index.d.ts

@@ -34,7 +34,7 @@ export type { SqliteDatabase, SqliteStatement, SQLiteAdapterOptions, } from "./a
 export { MemoryAdapter } from "./adapters/MemoryAdapter";
 export { OpenSearchAdapter } from "./adapters/OpenSearchAdapter";
 export type { OpenSearchClient, OpenSearchAdapterOptions, } from "./adapters/OpenSearchAdapter";
-export { END_ROUTE } from "./constants";
+export { END_STATE, END_STATE_ID } from "./constants";
 export { generateRouteId, generateStateId, generateToolId } from "./utils/id";
 export type { AgentOptions, Term, Guideline, Capability, GuidelineMatch, ContextLifecycleHooks, ContextProvider, } from "./types/agent";
 export { CompositionMode } from "./types/agent";

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -27,7 +27,7 @@ export { SQLiteAdapter } from "./adapters/SQLiteAdapter";
 export { MemoryAdapter } from "./adapters/MemoryAdapter";
 export { OpenSearchAdapter } 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";
 export { CompositionMode } from "./types/agent";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO;AACP,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD,YAAY;AACZ,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAE5D,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAE5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAEpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAGlE,WAAW;AACX,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAMzD,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAEvD,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAOvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAMjE,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAMzD,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAMjE,YAAY;AACZ,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,QAAQ;AACR,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAY9E,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAUhD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAWzD,OAAO,EACL,aAAa,EACb,UAAU,EACV,UAAU,EACV,cAAc,GACf,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO;AACP,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD,YAAY;AACZ,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAE5D,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAE5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAEpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAGlE,WAAW;AACX,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAMzD,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAEvD,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAOvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAMjE,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAMzD,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAMjE,YAAY;AACZ,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEtD,QAAQ;AACR,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAY9E,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAUhD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAWzD,OAAO,EACL,aAAa,EACb,UAAU,EACV,UAAU,EACV,cAAc,GACf,MAAM,iBAAiB,CAAC"}

package/dist/types/agent.d.ts

@@ -5,6 +5,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
  */
@@ -60,8 +61,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/dist/types/agent.d.ts.map

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

package/dist/types/agent.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/types/agent.ts"],"names":[],"mappings":"AAAA;;GAEG;AAOH;;GAEG;AACH,MAAM,CAAN,IAAY,eASX;AATD,WAAY,eAAe;IACzB,2DAA2D;IAC3D,kCAAe,CAAA;IACf,2CAA2C;IAC3C,gDAA6B,CAAA;IAC7B,kCAAkC;IAClC,0DAAuC,CAAA;IACvC,mCAAmC;IACnC,kDAA+B,CAAA;AACjC,CAAC,EATW,eAAe,KAAf,eAAe,QAS1B"}
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/types/agent.ts"],"names":[],"mappings":"AAAA;;GAEG;AAQH;;GAEG;AACH,MAAM,CAAN,IAAY,eASX;AATD,WAAY,eAAe;IACzB,2DAA2D;IAC3D,kCAAe,CAAA;IACf,2CAA2C;IAC3C,gDAA6B,CAAA;IAC7B,kCAAkC;IAClC,0DAAuC,CAAA;IACvC,mCAAmC;IACnC,kDAA+B,CAAA;AACjC,CAAC,EATW,eAAe,KAAf,eAAe,QAS1B"}

package/dist/types/route.d.ts

@@ -61,10 +61,16 @@ 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">;
 }
 /**
  * Specification for a state transition

package/dist/types/route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/types/route.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC;;;GAGG;AACH,MAAM,WAAW,YAAY,CAAC,UAAU,GAAG,OAAO;IAChD,qGAAqG;IACrG,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,wCAAwC;IACxC,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IACzB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,4EAA4E;IAC5E,mBAAmB,CAAC,EAAE,gBAAgB,CAAC;IACvC,6EAA6E;IAC7E,oBAAoB,CAAC,EAAE,gBAAgB,CAAC;IACxC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IAClC;;;;OAIG;IACH,KAAK,CAAC,EAAE,cAAc,CAAC,OAAO,EAAE,UAAU,CAAC,EAAE,CAAC;CAC/C;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,QAAQ,GAAG,OAAO,EAAE,UAAU,GAAG,OAAO;IACtE,2FAA2F;IAC3F,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mCAAmC;IAEnC,SAAS,CAAC,EAAE,OAAO,CAAC,QAAQ,EAAE,GAAG,EAAE,EAAE,GAAG,CAAC,CAAC;IAC1C,mDAAmD;IACnD,KAAK,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC1B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC,KAAK,OAAO,CAAC;IACrD;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB,CAAC,QAAQ,GAAG,OAAO,EAAE,UAAU,GAAG,OAAO,CACxE,SAAQ,QAAQ;IAChB,iCAAiC;IACjC,YAAY,EAAE,CACZ,IAAI,EAAE,cAAc,CAAC,QAAQ,EAAE,UAAU,CAAC,KACvC,gBAAgB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;CAC7C"}
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/types/route.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC;;;GAGG;AACH,MAAM,WAAW,YAAY,CAAC,UAAU,GAAG,OAAO;IAChD,qGAAqG;IACrG,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,wCAAwC;IACxC,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IACzB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,4EAA4E;IAC5E,mBAAmB,CAAC,EAAE,gBAAgB,CAAC;IACvC,6EAA6E;IAC7E,oBAAoB,CAAC,EAAE,gBAAgB,CAAC;IACxC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IAClC;;;;OAIG;IACH,KAAK,CAAC,EAAE,cAAc,CAAC,OAAO,EAAE,UAAU,CAAC,EAAE,CAAC;IAC9C;;;;OAIG;IACH,YAAY,CAAC,EAAE,IAAI,CACjB,cAAc,CAAC,OAAO,EAAE,UAAU,CAAC,EACnC,WAAW,GAAG,OAAO,GAAG,WAAW,CACpC,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,QAAQ,GAAG,OAAO,EAAE,UAAU,GAAG,OAAO;IACtE,2FAA2F;IAC3F,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mCAAmC;IAEnC,SAAS,CAAC,EAAE,OAAO,CAAC,QAAQ,EAAE,GAAG,EAAE,EAAE,GAAG,CAAC,CAAC;IAC1C,mDAAmD;IACnD,KAAK,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC1B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC,KAAK,OAAO,CAAC;IACrD;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB,CAAC,QAAQ,GAAG,OAAO,EAAE,UAAU,GAAG,OAAO,CACxE,SAAQ,QAAQ;IAChB,iCAAiC;IACjC,YAAY,EAAE,CACZ,IAAI,EAAE,cAAc,CAAC,QAAQ,EAAE,UAAU,CAAC,KACvC,gBAAgB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;CAC7C"}

package/dist/types/session.d.ts

@@ -20,8 +20,17 @@ export interface SessionState<TExtracted = Record<string, unknown>> {
         description?: string;
         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<{
         routeId: string;
@@ -44,6 +53,7 @@ export interface SessionState<TExtracted = Record<string, unknown>> {
 export declare function createSession<TExtracted = Record<string, unknown>>(sessionId?: string, metadata?: SessionState<TExtracted>["metadata"]): SessionState<TExtracted>;
 /**
  * Helper to update session with new route
+ * Preserves extracted data per route in extractedByRoute map
  */
 export declare function enterRoute<TExtracted = Record<string, unknown>>(session: SessionState<TExtracted>, routeId: string, routeTitle: string): SessionState<TExtracted>;
 /**
@@ -52,6 +62,7 @@ export declare function enterRoute<TExtracted = Record<string, unknown>>(session
 export declare function enterState<TExtracted = Record<string, unknown>>(session: SessionState<TExtracted>, stateId: string, stateDescription?: string): SessionState<TExtracted>;
 /**
  * Helper to merge extracted data into session
+ * Updates both the extracted field and the extractedByRoute map
  */
 export declare function mergeExtracted<TExtracted = Record<string, unknown>>(session: SessionState<TExtracted>, extracted: Partial<TExtracted>): SessionState<TExtracted>;
 /**

package/dist/types/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/types/session.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;GAGG;AACH,MAAM,WAAW,YAAY,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAChE,yDAAyD;IACzD,EAAE,CAAC,EAAE,MAAM,CAAC;IAEZ,2CAA2C;IAC3C,YAAY,CAAC,EAAE;QACb,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,IAAI,CAAC;KACjB,CAAC;IAEF,qCAAqC;IACrC,YAAY,CAAC,EAAE;QACb,EAAE,EAAE,MAAM,CAAC;QACX,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,IAAI,CAAC;KACjB,CAAC;IAEF,8CAA8C;IAC9C,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IAE/B,gDAAgD;IAChD,YAAY,EAAE,KAAK,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,IAAI,CAAC;QAChB,QAAQ,CAAC,EAAE,IAAI,CAAC;QAChB,SAAS,EAAE,OAAO,CAAC;KACpB,CAAC,CAAC;IAEH,uBAAuB;IACvB,QAAQ,CAAC,EAAE;QACT,SAAS,CAAC,EAAE,IAAI,CAAC;QACjB,aAAa,CAAC,EAAE,IAAI,CAAC;QACrB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;CACH;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChE,SAAS,CAAC,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,YAAY,CAAC,UAAU,CAAC,CAAC,UAAU,CAAC,GAC9C,YAAY,CAAC,UAAU,CAAC,CAW1B;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7D,OAAO,EAAE,YAAY,CAAC,UAAU,CAAC,EACjC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,YAAY,CAAC,UAAU,CAAC,CAoC1B;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7D,OAAO,EAAE,YAAY,CAAC,UAAU,CAAC,EACjC,OAAO,EAAE,MAAM,EACf,gBAAgB,CAAC,EAAE,MAAM,GACxB,YAAY,CAAC,UAAU,CAAC,CAa1B;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,OAAO,EAAE,YAAY,CAAC,UAAU,CAAC,EACjC,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC,GAC7B,YAAY,CAAC,UAAU,CAAC,CAY1B;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrE,OAAO,EAAE,YAAY,CAAC,UAAU,CAAC,GAChC;IACD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC,CAYA;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrE,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE;IACJ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC,GACA,YAAY,CAAC,UAAU,CAAC,CA4B1B"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/types/session.ts"],"names":[],"mappings":"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"}

package/dist/types/session.js

@@ -10,6 +10,7 @@ export function createSession(sessionId, metadata) {
     return {
         id: sessionId,
         extracted: {},
+        extractedByRoute: {},
         routeHistory: [],
         metadata: {
             ...metadata,
@@ -20,8 +21,16 @@ export function createSession(sessionId, metadata) {
 }
 /**
  * Helper to update session with new route
+ * Preserves extracted data per route in extractedByRoute map
  */
 export function enterRoute(session, routeId, routeTitle) {
+    // 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) {
@@ -30,6 +39,8 @@ export function enterRoute(session, routeId, routeTitle) {
             routeHistory[lastRouteIndex].exitedAt = new Date();
         }
     }
+    // Load extracted data for new route (if resuming) or start fresh
+    const newExtracted = extractedByRoute[routeId] || {};
     // Enter new route
     const now = new Date();
     return {
@@ -40,7 +51,8 @@ export function enterRoute(session, routeId, routeTitle) {
             enteredAt: now,
         },
         currentState: undefined,
-        extracted: {}, // Reset extracted data for new route
+        extracted: newExtracted, // Load route's data or start fresh
+        extractedByRoute,
         routeHistory: [
             ...routeHistory,
             {
@@ -74,14 +86,22 @@ export function enterState(session, stateId, stateDescription) {
 }
 /**
  * Helper to merge extracted data into session
+ * Updates both the extracted field and the extractedByRoute map
  */
 export function mergeExtracted(session, extracted) {
+    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(),
@@ -98,6 +118,7 @@ export function sessionStateToData(session) {
         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,
@@ -130,6 +151,8 @@ export function sessionDataToState(sessionId, data) {
             }
             : undefined,
         extracted: collectedData.extracted || {},
+        extractedByRoute: collectedData.extractedByRoute ||
+            {}, // Restore per-route data
         routeHistory: collectedData.routeHistory ||
             [],
         metadata: collectedData.metadata || {},

package/dist/types/session.js.map

@@ -1 +1 @@
-{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/types/session.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/types/session.ts"],"names":[],"mappings":"AAAA;;GAEG;AAqDH;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC3B,SAAkB,EAClB,QAA+C;IAE/C,OAAO;QACL,EAAE,EAAE,SAAS;QACb,SAAS,EAAE,EAAE;QACb,gBAAgB,EAAE,EAAE;QACpB,YAAY,EAAE,EAAE;QAChB,QAAQ,EAAE;YACR,GAAG,QAAQ;YACX,SAAS,EAAE,IAAI,IAAI,EAAE;YACrB,aAAa,EAAE,IAAI,IAAI,EAAE;SAC1B;KACF,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CACxB,OAAiC,EACjC,OAAe,EACf,UAAkB;IAElB,uDAAuD;IACvD,MAAM,gBAAgB,GAAG,EAAE,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IACzD,IACE,OAAO,CAAC,YAAY;QACpB,OAAO,CAAC,SAAS;QACjB,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,MAAM,GAAG,CAAC,EACzC,CAAC;QACD,gBAAgB,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC;IAChE,CAAC;IAED,+BAA+B;IAC/B,MAAM,YAAY,GAAG,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAC/C,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;QACzB,MAAM,cAAc,GAAG,YAAY,CAAC,SAAS,CAC3C,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,OAAO,CAAC,YAAY,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,QAAQ,CAC7D,CAAC;QACF,IAAI,cAAc,IAAI,CAAC,EAAE,CAAC;YACxB,YAAY,CAAC,cAAc,CAAC,CAAC,QAAQ,GAAG,IAAI,IAAI,EAAE,CAAC;QACrD,CAAC;IACH,CAAC;IAED,iEAAiE;IACjE,MAAM,YAAY,GAAI,gBAAgB,CAAC,OAAO,CAAyB,IAAI,EAAE,CAAC;IAE9E,kBAAkB;IAClB,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,OAAO;QACL,GAAG,OAAO;QACV,YAAY,EAAE;YACZ,EAAE,EAAE,OAAO;YACX,KAAK,EAAE,UAAU;YACjB,SAAS,EAAE,GAAG;SACf;QACD,YAAY,EAAE,SAAS;QACvB,SAAS,EAAE,YAAY,EAAE,mCAAmC;QAC5D,gBAAgB;QAChB,YAAY,EAAE;YACZ,GAAG,YAAY;YACf;gBACE,OAAO;gBACP,SAAS,EAAE,GAAG;gBACd,SAAS,EAAE,KAAK;aACjB;SACF;QACD,QAAQ,EAAE;YACR,GAAG,OAAO,CAAC,QAAQ;YACnB,aAAa,EAAE,GAAG;SACnB;KACF,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CACxB,OAAiC,EACjC,OAAe,EACf,gBAAyB;IAEzB,OAAO;QACL,GAAG,OAAO;QACV,YAAY,EAAE;YACZ,EAAE,EAAE,OAAO;YACX,WAAW,EAAE,gBAAgB;YAC7B,SAAS,EAAE,IAAI,IAAI,EAAE;SACtB;QACD,QAAQ,EAAE;YACR,GAAG,OAAO,CAAC,QAAQ;YACnB,aAAa,EAAE,IAAI,IAAI,EAAE;SAC1B;KACF,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAiC,EACjC,SAA8B;IAE9B,MAAM,YAAY,GAAG;QACnB,GAAG,OAAO,CAAC,SAAS;QACpB,GAAG,SAAS;KACb,CAAC;IAEF,6DAA6D;IAC7D,MAAM,gBAAgB,GAAG,EAAE,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IACzD,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;QACzB,gBAAgB,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC,GAAG,YAAY,CAAC;IAC3D,CAAC;IAED,OAAO;QACL,GAAG,OAAO;QACV,SAAS,EAAE,YAAY;QACvB,gBAAgB;QAChB,QAAQ,EAAE;YACR,GAAG,OAAO,CAAC,QAAQ;YACnB,aAAa,EAAE,IAAI,IAAI,EAAE;SAC1B;KACF,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAiC;IAMjC,OAAO;QACL,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE,EAAE;QACtC,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE,EAAE;QACtC,aAAa,EAAE;YACb,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,EAAE,yBAAyB;YACrE,YAAY,EAAE,OAAO,CAAC,YAAY;YAClC,iBAAiB,EAAE,OAAO,CAAC,YAAY,EAAE,KAAK;YAC9C,uBAAuB,EAAE,OAAO,CAAC,YAAY,EAAE,WAAW;YAC1D,QAAQ,EAAE,OAAO,CAAC,QAAQ;SAC3B;KACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,SAAiB,EACjB,IAIC;IAED,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,IAAI,EAAE,CAAC;IAE/C,OAAO;QACL,EAAE,EAAE,SAAS;QACb,YAAY,EAAE,IAAI,CAAC,YAAY;YAC7B,CAAC,CAAC;gBACE,EAAE,EAAE,IAAI,CAAC,YAAY;gBACrB,KAAK,EACF,aAAa,CAAC,iBAA4B,IAAI,IAAI,CAAC,YAAY;gBAClE,SAAS,EAAE,IAAI,IAAI,EAAE;aACtB;YACH,CAAC,CAAC,SAAS;QACb,YAAY,EAAE,IAAI,CAAC,YAAY;YAC7B,CAAC,CAAC;gBACE,EAAE,EAAE,IAAI,CAAC,YAAY;gBACrB,WAAW,EACR,aAAa,CAAC,uBAAkC,IAAI,SAAS;gBAChE,SAAS,EAAE,IAAI,IAAI,EAAE;aACtB;YACH,CAAC,CAAC,SAAS;QACb,SAAS,EAAG,aAAa,CAAC,SAAiC,IAAI,EAAE;QACjE,gBAAgB,EACb,aAAa,CAAC,gBAAqD;YACpE,EAAE,EAAE,yBAAyB;QAC/B,YAAY,EACT,aAAa,CAAC,YAAyD;YACxE,EAAE;QACJ,QAAQ,EACL,aAAa,CAAC,QAAiD,IAAI,EAAE;KACzE,CAAC;AACJ,CAAC"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,10 @@
+import log from "loglevel";
+export declare enum LoggerLevel {
+    DEBUG = "debug",
+    INFO = "info",
+    WARN = "warn",
+    ERROR = "error",
+    SILENT = "silent"
+}
+export declare const logger: log.RootLogger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,UAAU,CAAC;AAE3B,oBAAY,WAAW;IACrB,KAAK,UAAU;IACf,IAAI,SAAS;IACb,IAAI,SAAS;IACb,KAAK,UAAU;IACf,MAAM,WAAW;CAClB;AAUD,eAAO,MAAM,MAAM,gBAAM,CAAC"}

package/dist/utils/logger.js

@@ -0,0 +1,17 @@
+import log from "loglevel";
+export var LoggerLevel;
+(function (LoggerLevel) {
+    LoggerLevel["DEBUG"] = "debug";
+    LoggerLevel["INFO"] = "info";
+    LoggerLevel["WARN"] = "warn";
+    LoggerLevel["ERROR"] = "error";
+    LoggerLevel["SILENT"] = "silent";
+})(LoggerLevel || (LoggerLevel = {}));
+/**
+ * Default log level
+ */
+const DEFAULT_LOG_LEVEL = LoggerLevel.SILENT;
+// Initialize logger
+log.setLevel(DEFAULT_LOG_LEVEL);
+export const logger = log;
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,UAAU,CAAC;AAE3B,MAAM,CAAN,IAAY,WAMX;AAND,WAAY,WAAW;IACrB,8BAAe,CAAA;IACf,4BAAa,CAAA;IACb,4BAAa,CAAA;IACb,8BAAe,CAAA;IACf,gCAAiB,CAAA;AACnB,CAAC,EANW,WAAW,KAAX,WAAW,QAMtB;AAED;;GAEG;AACH,MAAM,iBAAiB,GAAG,WAAW,CAAC,MAAM,CAAC;AAE7C,oBAAoB;AACpB,GAAG,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC;AAEhC,MAAM,CAAC,MAAM,MAAM,GAAG,GAAG,CAAC"}

package/docs/{CONSTRUCTOR_OPTIONS.md → AGENT.md}

@@ -1,4 +1,4 @@
-# Constructor Configuration Guide
+# Agent Configuration Guide
 
 ## Overview
 
@@ -7,11 +7,11 @@ The `@falai/agent` framework supports **two complementary patterns** for configu
 1. **Declarative** - Pass arrays/objects in constructors (great for static configs)
 2. **Fluent/Programmatic** - Chain methods to build dynamically (great for runtime logic)
 
-You can **mix both patterns** - initialize with constructor options, then add more dynamically!
+You can **mix both patterns** - initialize with agent, then add more dynamically!
 
 ---
 
-## 📦 Agent Constructor Options
+## 📦 Agent Agent
 
 ```typescript
 interface AgentOptions<TContext = unknown> {
@@ -24,6 +24,9 @@ interface AgentOptions<TContext = unknown> {
   goal?: string;
   context?: TContext;
 
+  // Optional current session for convenience methods
+  session?: SessionState;
+
   // Context provider for always-fresh context
   contextProvider?: () => Promise<TContext> | TContext;
 
@@ -74,6 +77,11 @@ const agent = new Agent<FlightBookingContext>({
     availableFlights: [],
   },
 
+  // Optional: Set initial session for convenience methods
+  session: createSession<FlightData>({
+    extracted: { destination: 'Paris' }, // Pre-populate with known data
+  }),
+
   // Enhanced lifecycle hooks
   hooks: {
     // Refresh context before each response
@@ -141,24 +149,87 @@ const agent = new Agent<FlightBookingContext>({
       enabled: true,
     },
   ],
-  ],
 
   capabilities: [
     { title: 'Ticket Management', description: 'Create and track tickets' },
   ],
 });
 
-// Use with session state
+// Option 1: Use session passed to respond (traditional)
 let session = createSession<FlightData>();
 const response = await agent.respond({ history, session });
 console.log(response.session?.extracted); // Extracted flight data
+
+// Option 2: Use session set in constructor (convenience methods)
+// Since we set session in constructor, no need to pass it!
+const response2 = await agent.respond({ history });
+console.log(agent.getExtractedData()); // Uses constructor session
+
+// Option 3: Override session for specific calls
+const customSession = createSession<FlightData>({ extracted: { destination: 'Tokyo' } });
+const response3 = await agent.respond({ history, session: customSession });
+console.log(response3.session?.extracted); // Uses custom session
 ```
 
 ````
 
 ---
 
-## 🛤️ Route Constructor Options
+## 💾 Session Management
+
+The agent supports flexible session management for conversation state tracking:
+
+### Constructor Session (Optional)
+
+Set an initial session in the constructor for convenience:
+
+```typescript
+const agent = new Agent({
+  name: 'Bot',
+  ai: provider,
+  session: createSession<MyData>({
+    extracted: { name: 'John' }, // Pre-populate data
+  }),
+});
+
+// Use convenience methods without passing session
+const response = await agent.respond({ history });
+const data = agent.getExtractedData(); // Uses constructor session
+```
+
+### Runtime Session Management
+
+```typescript
+// Set session for convenience methods
+agent.setCurrentSession(session);
+
+// Use without passing session parameter
+const extracted = agent.getExtractedData();
+const routeData = agent.getExtractedData('onboarding');
+
+// Override for specific calls
+const response = await agent.respond({ history, session: customSession });
+
+// Clear when done
+agent.clearCurrentSession();
+```
+
+### Session Preservation
+
+When switching routes, extracted data is preserved in `extractedByRoute`:
+
+```typescript
+// User switches from onboarding to booking
+const response = await agent.respond({ history }); // Switches routes
+
+// Access data from previous routes
+const onboardingData = agent.getExtractedData('onboarding');
+const bookingData = agent.getExtractedData('booking');
+```
+
+---
+
+## 🛤️ Route Agent
 
 ```typescript
 interface RouteOptions<TExtracted = unknown> {
@@ -375,7 +446,7 @@ const agent = new Agent({
 
 ## 🔄 Fluent API (Still Available!)
 
-All constructor options also have fluent methods that **return `this`** for chaining:
+All agents also have fluent methods that **return `this`** for chaining:
 
 ```typescript
 agent
@@ -449,6 +520,7 @@ const agent = new Agent<MyContext>({
   goal?: string,
   ai: AiProvider,
   context?: MyContext,
+  session?: SessionState,        // Optional current session
   maxEngineIterations?: number,
   compositionMode?: CompositionMode,
   terms?: Term[],