@falai/agent 0.5.3 → 0.5.4

package/README.md

@@ -70,6 +70,7 @@
 - **Session State Integration** - Automatic saving of extracted data & conversation progress
 - **Provider Pattern** - Simple API like AI providers
 - **Multiple Adapters** - Prisma, Redis, MongoDB, PostgreSQL, SQLite, OpenSearch, Memory
+- **Custom Database Support** - Manual session state management for existing schemas
 - **Auto-save** - Automatic session state & message persistence
 - **Type-Safe** - Full TypeScript support with generics
 - **Extensible** - Create adapters for any database
@@ -972,6 +973,16 @@ Full-text search and analytics-powered persistence:
 - 🌐 Compatible with Elasticsearch 7.x
 - ☁️ AWS OpenSearch Service ready
 
+### 🗄️ [Custom Database Integration](./examples/custom-database-persistence.ts)
+
+Manual session state management for existing database schemas:
+
+- 🔧 Full control over database operations
+- 📦 Works with any database (no adapter needed)
+- 🔄 Manual session state save/restore
+- 🎯 Perfect for integrating with existing schemas
+- ✅ Complete example with validation hooks
+
 ---
 
 ## 💾 Database Adapters

package/dist/cjs/core/State.js

@@ -46,7 +46,8 @@ class State {
             return this.createStateRefWithTransition(spec.state);
         }
         // Create new target state for chatState or toolState
-        const targetState = new State(this.routeId, spec.chatState, undefined, spec.gather, spec.skipIf, spec.requiredData);
+        const targetState = new State(this.routeId, spec.chatState, spec.id, // Use custom ID if provided
+        spec.gather, spec.skipIf, spec.requiredData);
         const transition = new Transition_1.Transition(this.getRef(), spec, condition);
         transition.setTarget(targetState);
         this.transitions.push(transition);

package/dist/cjs/core/State.js.map

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

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

@@ -64,6 +64,8 @@ export interface RouteOptions<TExtracted = unknown> {
  * Specification for a state transition
  */
 export interface TransitionSpec<TContext = unknown, TExtracted = unknown> {
+    /** Custom ID for this state (optional - will generate deterministic ID if not provided) */
+    id?: string;
     /** Transition to a chat state with this description */
     chatState?: string;
     /** Transition to execute a tool */

package/dist/cjs/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,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,QAAQ,GAAG,OAAO,EAAE,UAAU,GAAG,OAAO;IACtE,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;CACzB;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,EAC1C,SAAS,CAAC,EAAE,MAAM,KACf,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,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;CACnC;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;CACzB;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,EAC1C,SAAS,CAAC,EAAE,MAAM,KACf,gBAAgB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;CAC7C"}

package/dist/core/State.js

@@ -43,7 +43,8 @@ export class State {
             return this.createStateRefWithTransition(spec.state);
         }
         // Create new target state for chatState or toolState
-        const targetState = new State(this.routeId, spec.chatState, undefined, spec.gather, spec.skipIf, spec.requiredData);
+        const targetState = new State(this.routeId, spec.chatState, spec.id, // Use custom ID if provided
+        spec.gather, spec.skipIf, spec.requiredData);
         const transition = new Transition(this.getRef(), spec, condition);
         transition.setTarget(targetState);
         this.transitions.push(transition);

package/dist/core/State.js.map

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

package/dist/types/route.d.ts

@@ -64,6 +64,8 @@ export interface RouteOptions<TExtracted = unknown> {
  * Specification for a state transition
  */
 export interface TransitionSpec<TContext = unknown, TExtracted = unknown> {
+    /** Custom ID for this state (optional - will generate deterministic ID if not provided) */
+    id?: string;
     /** Transition to a chat state with this description */
     chatState?: string;
     /** Transition to execute a tool */

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,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,QAAQ,GAAG,OAAO,EAAE,UAAU,GAAG,OAAO;IACtE,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;CACzB;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,EAC1C,SAAS,CAAC,EAAE,MAAM,KACf,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,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;CACnC;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;CACzB;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,EAC1C,SAAS,CAAC,EAAE,MAAM,KACf,gBAAgB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;CAC7C"}

package/docs/API_REFERENCE.md

@@ -87,29 +87,99 @@ interface RespondOutput {
 - Enables "I changed my mind" scenarios with context-aware routing
 - Automatically merges new extracted data with existing session data
 
-**Example:**
+**Example with Persistence Adapters:**
 
 ```typescript
+import { createSession } from "@falai/agent";
+
+// Using built-in persistence adapters
+const { sessionData, sessionState } =
+  await persistence.createSessionWithState<FlightData>({
+    userId: "user_123",
+    agentName: "Travel Agent",
+  });
+
 const response = await agent.respond({
-  history: conversationHistory,
+  history,
+  session: sessionState, // Auto-saves if autoSave: true
 });
+```
 
-// Save to database
-await db.agentMessages.create({
-  sessionId: session.id,
+**Example with Custom Database (Manual):**
+
+```typescript
+import { createSession, SessionState } from "@falai/agent";
+
+// Load from your custom database
+const dbSession = await yourDb.sessions.findOne({ id: sessionId });
+
+// Restore or create session state
+let agentSession: SessionState<YourDataType>;
+
+if (dbSession && dbSession.currentRoute && dbSession.collectedData) {
+  // Restore existing session from database
+  agentSession = {
+    currentRoute: {
+      id: dbSession.currentRoute,
+      title:
+        dbSession.collectedData?.currentRouteTitle || dbSession.currentRoute,
+      enteredAt: new Date(),
+    },
+    currentState: dbSession.currentState
+      ? {
+          id: dbSession.currentState,
+          description: dbSession.collectedData?.currentStateDescription,
+          enteredAt: new Date(),
+        }
+      : undefined,
+    extracted: dbSession.collectedData?.extracted || {},
+    routeHistory: dbSession.collectedData?.routeHistory || [],
+    metadata: {
+      sessionId: dbSession.id,
+      createdAt: dbSession.createdAt,
+      lastUpdatedAt: new Date(),
+    },
+  };
+} else {
+  // Create new session
+  agentSession = createSession<YourDataType>({
+    sessionId: dbSession?.id || "new-session-id",
+  });
+}
+
+// Use session in conversation
+const response = await agent.respond({
+  history,
+  session: agentSession,
+});
+
+// Manually save to your database
+await yourDb.sessions.update({
+  id: dbSession.id,
+  currentRoute: response.session?.currentRoute?.id,
+  currentState: response.session?.currentState?.id,
+  collectedData: {
+    extracted: response.session?.extracted,
+    routeHistory: response.session?.routeHistory,
+    currentRouteTitle: response.session?.currentRoute?.title,
+    currentStateDescription: response.session?.currentState?.description,
+    metadata: response.session?.metadata,
+  },
+  lastMessageAt: new Date(),
+});
+
+// Save message
+await yourDb.messages.create({
+  sessionId: dbSession.id,
   role: "agent",
   content: response.message,
-  route: response.route?.title,
-  state: response.state?.description,
-  toolCalls: response.toolCalls || [],
+  route: response.session?.currentRoute?.id,
+  state: response.session?.currentState?.id,
 });
-
-// Check if conversation is complete
-if (response.route?.title === END_ROUTE) {
-  await markSessionComplete(session.id);
-}
 ```
 
+See also: [Custom Database Integration Example](../examples/custom-database-persistence.ts)
+
 ##### `respondStream(input: RespondInput<TContext>): AsyncGenerator<StreamChunk>`
 
 Generates an AI response as a real-time stream for better user experience. Provides the same structured output as `respond()` but delivers it incrementally.

package/docs/ARCHITECTURE.md

@@ -58,7 +58,11 @@ import {
   mergeExtracted,
 } from "@falai/agent";
 
-let session = createSession<FlightData>();
+// Create session with optional metadata including session ID
+let session = createSession<FlightData>(sessionId, {
+  userId: "user_456",
+  createdAt: new Date(),
+});
 
 // Turn 1 - Extract data
 const response1 = await agent.respond({ history, session });
@@ -67,6 +71,31 @@ session = response1.session!; // Updated with extracted data
 // Turn 2 - User changes mind (always-on routing)
 const response2 = await agent.respond({ history, session: response1.session });
 session = response2.session!; // Route/state updated if user changed direction
+
+// Access session metadata
+console.log(session.metadata?.sessionId); // "unique-session-123"
+```
+
+**Session with Persistence:**
+
+When using persistence adapters, set the session ID from the database:
+
+```typescript
+// Create database session and in-memory session state
+const { sessionData, sessionState } =
+  await persistence.createSessionWithState<FlightData>({
+    userId: "user_123",
+    agentName: "Travel Agent",
+  });
+
+// sessionState.metadata.sessionId is automatically set to sessionData.id
+console.log(sessionState.metadata?.sessionId); // "cuid_from_database"
+
+// Use it in conversation
+const response = await agent.respond({
+  history,
+  session: sessionState, // Auto-saves to database!
+});
 ```
 
 **Why?** Session state enables:
@@ -75,6 +104,7 @@ session = response2.session!; // Route/state updated if user changed direction
 - **Context Awareness** - Router sees current progress and extracted data
 - **Data Persistence** - Extracted data survives across turns
 - **State Recovery** - Resume conversations from any point
+- **Session Tracking** - Track conversations via session ID in database
 
 ### 3. 🔧 Code-Based State Logic
 
@@ -83,12 +113,14 @@ Use TypeScript functions instead of LLM conditions for deterministic flow:
 ```typescript
 // State with smart bypassing based on extracted data
 const askDestination = route.initialState.transitionTo({
+  id: "ask_destination", // Optional: custom state ID
   chatState: "Ask where they want to fly",
   gather: ["destination"],
   skipIf: (extracted) => !!extracted.destination, // Code-based condition!
 });
 
 const askDate = askDestination.transitionTo({
+  id: "ask_date", // Optional: custom state ID for easier tracking
   chatState: "Ask about travel dates",
   gather: ["departureDate"],
   skipIf: (extracted) => !!extracted.departureDate,
@@ -96,12 +128,27 @@ const askDate = askDestination.transitionTo({
 });
 ```
 
+**Custom State IDs:**
+
+You can optionally provide custom IDs for states to make them easier to track and reference:
+
+```typescript
+const confirmBooking = askDate.transitionTo({
+  id: "confirm_booking", // ✅ Custom ID instead of auto-generated
+  chatState: "Confirm all booking details",
+  requiredData: ["destination", "departureDate", "passengers"],
+});
+```
+
+If you don't provide an ID, one is automatically generated from the route ID and state description.
+
 **Why?** Code-based logic provides:
 
 - **Predictability** - No fuzzy LLM interpretation of conditions
 - **Performance** - No extra LLM calls for condition checking
 - **Debugging** - Clear logic flow you can trace
 - **Type Safety** - Full TypeScript support for data validation
+- **Custom IDs** - Easier tracking and debugging with meaningful state identifiers
 
 ### 4. 🛠️ Tools with Data Access
 

package/docs/PERSISTENCE.md

@@ -121,11 +121,18 @@ const bookingRoute = agent.createRoute<BookingData>({
   },
 });
 
-// Define states with smart data gathering
-bookingRoute.initialState.transitionTo({
-  chatState: "Collect booking details",
-  gather: ["destination", "date", "passengers"],
-});
+// Define states with smart data gathering and custom IDs
+bookingRoute.initialState
+  .transitionTo({
+    id: "collect_details", // ✅ Custom state ID for easier tracking
+    chatState: "Collect booking details",
+    gather: ["destination", "date", "passengers"],
+  })
+  .transitionTo({
+    id: "confirm_booking", // ✅ Custom state ID
+    chatState: "Confirm all details",
+    requiredData: ["destination", "date", "passengers"],
+  });
 
 // Access persistence methods
 const persistence = agent.getPersistenceManager();
@@ -137,17 +144,22 @@ const { sessionData, sessionState } =
     agentName: "My Agent",
   });
 
+// Session ID is automatically set in metadata
+console.log("Session ID:", sessionState.metadata?.sessionId);
+// Outputs: sessionData.id (e.g., "cuid_abc123")
+
 // Load history
 const history = await persistence.loadSessionHistory(sessionData.id);
 
 // Generate response with session state
 const response = await agent.respond({
   history,
-  session: sessionState, // Pass session state
+  session: sessionState, // Pass session state with ID
 });
 
 // Session state is auto-saved! ✨
 console.log("Extracted data:", response.session?.extracted);
+console.log("Current state ID:", response.session?.currentState?.id); // Custom or auto-generated ID
 
 // Save message
 await persistence.saveMessage({

package/examples/custom-database-persistence.ts

@@ -0,0 +1,533 @@
+/**
+ * Example: Custom Database Integration (Manual Session State Management)
+ *
+ * This example shows how to manually manage session state when using your own
+ * database structure instead of the built-in persistence adapters.
+ *
+ * Use this approach if you:
+ * - Have an existing database schema you want to integrate with
+ * - Need custom data structures beyond what adapters provide
+ * - Want full control over database operations
+ */
+
+import {
+  Agent,
+  GeminiProvider,
+  createMessageEvent,
+  EventSource,
+  createSession,
+  SessionState,
+  MessageEventData,
+  Event,
+} from "../src/index";
+
+/**
+ * Example: Your existing database structure
+ * This could be any ORM (Prisma, TypeORM, Drizzle) or query builder
+ */
+interface CustomDatabaseSession {
+  id: string;
+  userId: string;
+  currentRoute?: string;
+  currentState?: string;
+  collectedData?: {
+    extracted?: Record<string, unknown>;
+    routeHistory?: unknown[];
+    currentRouteTitle?: string;
+    currentStateDescription?: string;
+    metadata?: Record<string, unknown>;
+  };
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+interface CustomDatabaseMessage {
+  id: string;
+  sessionId: string;
+  userId: string;
+  role: "user" | "agent" | "system";
+  content: string;
+  route?: string;
+  state?: string;
+  createdAt: Date;
+}
+
+// Mock database - replace with your actual database
+class CustomDatabase {
+  private sessions: Map<string, CustomDatabaseSession> = new Map();
+  private messages: Map<string, CustomDatabaseMessage[]> = new Map();
+
+  async findSession(id: string): Promise<CustomDatabaseSession | null> {
+    return this.sessions.get(id) || null;
+  }
+
+  async createSession(
+    data: Omit<CustomDatabaseSession, "id" | "createdAt" | "updatedAt">
+  ): Promise<CustomDatabaseSession> {
+    const session: CustomDatabaseSession = {
+      id: `session_${Date.now()}`,
+      ...data,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    };
+    this.sessions.set(session.id, session);
+    return session;
+  }
+
+  async updateSession(
+    id: string,
+    data: Partial<CustomDatabaseSession>
+  ): Promise<CustomDatabaseSession | null> {
+    const session = this.sessions.get(id);
+    if (!session) return null;
+
+    const updated = {
+      ...session,
+      ...data,
+      updatedAt: new Date(),
+    };
+    this.sessions.set(id, updated);
+    return updated;
+  }
+
+  async createMessage(
+    data: Omit<CustomDatabaseMessage, "id" | "createdAt">
+  ): Promise<CustomDatabaseMessage> {
+    const message: CustomDatabaseMessage = {
+      id: `msg_${Date.now()}`,
+      ...data,
+      createdAt: new Date(),
+    };
+
+    const messages = this.messages.get(data.sessionId) || [];
+    messages.push(message);
+    this.messages.set(data.sessionId, messages);
+
+    return message;
+  }
+
+  async getSessionMessages(
+    sessionId: string
+  ): Promise<CustomDatabaseMessage[]> {
+    return this.messages.get(sessionId) || [];
+  }
+}
+
+// Example data type for a customer onboarding route
+interface OnboardingData {
+  fullName: string;
+  email: string;
+  companyName: string;
+  phoneNumber?: string;
+  industry?: string;
+}
+
+async function example() {
+  const db = new CustomDatabase();
+  const userId = "user_123";
+
+  // Create agent
+  const agent = new Agent({
+    name: "Onboarding Assistant",
+    description: "Help new customers get started",
+    goal: "Collect customer information efficiently",
+    ai: new GeminiProvider({
+      apiKey: process.env.GEMINI_API_KEY!,
+      model: "models/gemini-2.0-flash-exp",
+    }),
+    // NOTE: No persistence adapter - we handle it manually!
+  });
+
+  // Create onboarding route
+  const onboardingRoute = agent.createRoute<OnboardingData>({
+    title: "Customer Onboarding",
+    description: "Collect customer information",
+    conditions: [
+      "User is a new customer",
+      "User needs to set up their account",
+    ],
+    gatherSchema: {
+      type: "object",
+      properties: {
+        fullName: { type: "string" },
+        email: { type: "string" },
+        companyName: { type: "string" },
+        phoneNumber: { type: "string" },
+        industry: { type: "string" },
+      },
+      required: ["fullName", "email", "companyName"],
+    },
+  });
+
+  // Define states with custom IDs
+  onboardingRoute.initialState
+    .transitionTo({
+      id: "ask_name",
+      chatState: "Ask for full name",
+      gather: ["fullName"],
+      skipIf: (data) => !!data.fullName,
+    })
+    .transitionTo({
+      id: "ask_email",
+      chatState: "Ask for email address",
+      gather: ["email"],
+      skipIf: (data) => !!data.email,
+    })
+    .transitionTo({
+      id: "ask_company",
+      chatState: "Ask for company name",
+      gather: ["companyName"],
+      skipIf: (data) => !!data.companyName,
+    })
+    .transitionTo({
+      id: "ask_phone",
+      chatState: "Ask for phone number (optional)",
+      gather: ["phoneNumber"],
+    })
+    .transitionTo({
+      id: "ask_industry",
+      chatState: "Ask for industry",
+      gather: ["industry"],
+    })
+    .transitionTo({
+      id: "confirm_details",
+      chatState: "Confirm all details",
+      requiredData: ["fullName", "email", "companyName"],
+    });
+
+  /**
+   * Create or load session from your custom database
+   */
+  let dbSession = await db.findSession("existing_session_id");
+
+  if (!dbSession) {
+    // Create new session in your database
+    dbSession = await db.createSession({
+      userId,
+      collectedData: {},
+    });
+    console.log("✨ Created new database session:", dbSession.id);
+  }
+
+  /**
+   * Convert database session to agent SessionState
+   */
+  let agentSession: SessionState<OnboardingData>;
+
+  if (dbSession.currentRoute && dbSession.collectedData) {
+    // Restore existing session from database
+    console.log("📥 Restoring session from database...");
+
+    agentSession = {
+      currentRoute: {
+        id: dbSession.currentRoute,
+        title:
+          dbSession.collectedData?.currentRouteTitle || dbSession.currentRoute,
+        enteredAt: new Date(),
+      },
+      currentState: dbSession.currentState
+        ? {
+            id: dbSession.currentState,
+            description: dbSession.collectedData?.currentStateDescription,
+            enteredAt: new Date(),
+          }
+        : undefined,
+      extracted:
+        (dbSession.collectedData?.extracted as Partial<OnboardingData>) || {},
+      routeHistory:
+        (dbSession.collectedData
+          ?.routeHistory as SessionState<OnboardingData>["routeHistory"]) || [],
+      metadata: {
+        sessionId: dbSession.id,
+        userId,
+        createdAt: dbSession.createdAt,
+        lastUpdatedAt: dbSession.updatedAt,
+        ...(dbSession.collectedData?.metadata as Record<string, unknown>),
+      },
+    };
+
+    console.log("✅ Session restored:", {
+      sessionId: agentSession.metadata?.sessionId,
+      currentRoute: agentSession.currentRoute?.title,
+      currentState: agentSession.currentState?.id,
+      extracted: agentSession.extracted,
+    });
+  } else {
+    // Create new session state
+    console.log("🆕 Creating new session state...");
+
+    agentSession = createSession<OnboardingData>(dbSession.id, {
+      sessionId: dbSession.id,
+      userId,
+      createdAt: dbSession.createdAt,
+    });
+  }
+
+  /**
+   * Simulate conversation
+   */
+  const history: Event<MessageEventData>[] = [];
+
+  // Turn 1: User provides name and email
+  console.log("\n--- Turn 1 ---");
+  const userMessage1 = createMessageEvent(
+    EventSource.CUSTOMER,
+    "User",
+    "Hi! I'm John Smith and my email is john@acme.com"
+  );
+  history.push(userMessage1);
+
+  // Save user message to database
+  await db.createMessage({
+    sessionId: dbSession.id,
+    userId,
+    role: "user",
+    content: userMessage1.data.message,
+  });
+
+  const response1 = await agent.respond({
+    history,
+    session: agentSession,
+  });
+
+  console.log("🤖 Agent:", response1.message);
+  console.log("📊 Extracted so far:", response1.session?.extracted);
+
+  // Save agent message to database
+  await db.createMessage({
+    sessionId: dbSession.id,
+    userId,
+    role: "agent",
+    content: response1.message,
+    route: response1.session?.currentRoute?.id,
+    state: response1.session?.currentState?.id,
+  });
+
+  // Manually save session state back to database
+  await db.updateSession(dbSession.id, {
+    currentRoute: response1.session?.currentRoute?.id,
+    currentState: response1.session?.currentState?.id,
+    collectedData: {
+      extracted: response1.session?.extracted,
+      routeHistory: response1.session?.routeHistory,
+      currentRouteTitle: response1.session?.currentRoute?.title,
+      currentStateDescription: response1.session?.currentState?.description,
+      metadata: response1.session?.metadata,
+    },
+  });
+
+  console.log("💾 Session saved to database");
+
+  // Update session for next turn
+  agentSession = response1.session!;
+
+  // Turn 2: User provides company
+  console.log("\n--- Turn 2 ---");
+  history.push(
+    createMessageEvent(EventSource.AI_AGENT, "Agent", response1.message)
+  );
+
+  const userMessage2 = createMessageEvent(
+    EventSource.CUSTOMER,
+    "User",
+    "I work for Acme Corporation"
+  );
+  history.push(userMessage2);
+
+  await db.createMessage({
+    sessionId: dbSession.id,
+    userId,
+    role: "user",
+    content: userMessage2.data.message,
+  });
+
+  const response2 = await agent.respond({
+    history,
+    session: agentSession,
+  });
+
+  console.log("🤖 Agent:", response2.message);
+  console.log("📊 Extracted so far:", response2.session?.extracted);
+
+  await db.createMessage({
+    sessionId: dbSession.id,
+    userId,
+    role: "agent",
+    content: response2.message,
+    route: response2.session?.currentRoute?.id,
+    state: response2.session?.currentState?.id,
+  });
+
+  // Save session state
+  await db.updateSession(dbSession.id, {
+    currentRoute: response2.session?.currentRoute?.id,
+    currentState: response2.session?.currentState?.id,
+    collectedData: {
+      extracted: response2.session?.extracted,
+      routeHistory: response2.session?.routeHistory,
+      currentRouteTitle: response2.session?.currentRoute?.title,
+      currentStateDescription: response2.session?.currentState?.description,
+      metadata: response2.session?.metadata,
+    },
+  });
+
+  console.log("💾 Session saved to database");
+
+  /**
+   * Demonstrate session recovery
+   */
+  console.log("\n--- Session Recovery ---");
+  console.log("Simulating app restart...\n");
+
+  // Load session from database again
+  const reloadedDbSession = await db.findSession(dbSession.id);
+  if (!reloadedDbSession) throw new Error("Session not found");
+
+  // Reconstruct session state
+  const recoveredSession: SessionState<OnboardingData> = {
+    currentRoute: reloadedDbSession.currentRoute
+      ? {
+          id: reloadedDbSession.currentRoute,
+          title:
+            reloadedDbSession.collectedData?.currentRouteTitle ||
+            reloadedDbSession.currentRoute,
+          enteredAt: new Date(),
+        }
+      : undefined,
+    currentState: reloadedDbSession.currentState
+      ? {
+          id: reloadedDbSession.currentState,
+          description: reloadedDbSession.collectedData?.currentStateDescription,
+          enteredAt: new Date(),
+        }
+      : undefined,
+    extracted:
+      (reloadedDbSession.collectedData?.extracted as Partial<OnboardingData>) ||
+      {},
+    routeHistory:
+      (reloadedDbSession.collectedData
+        ?.routeHistory as SessionState<OnboardingData>["routeHistory"]) || [],
+    metadata: {
+      sessionId: reloadedDbSession.id,
+      userId,
+      createdAt: reloadedDbSession.createdAt,
+      lastUpdatedAt: reloadedDbSession.updatedAt,
+    },
+  };
+
+  console.log("✅ Session recovered from database:", {
+    sessionId: recoveredSession.metadata?.sessionId,
+    currentRoute: recoveredSession.currentRoute?.title,
+    currentState: recoveredSession.currentState?.id,
+    extracted: recoveredSession.extracted,
+  });
+
+  // Load message history
+  const messages = await db.getSessionMessages(dbSession.id);
+  console.log(`📜 Loaded ${messages.length} messages from history`);
+
+  console.log("\n✅ Example complete!");
+}
+
+/**
+ * Advanced Example: With validation hooks
+ */
+async function advancedExample() {
+  const db = new CustomDatabase();
+  const userId = "user_456";
+
+  const agent = new Agent({
+    name: "Smart Onboarding",
+    ai: new GeminiProvider({
+      apiKey: process.env.GEMINI_API_KEY!,
+      model: "models/gemini-2.0-flash-exp",
+    }),
+    hooks: {
+      // Validate and enrich extracted data
+      onExtractedUpdate: async (extracted, previous) => {
+        console.log("🔄 Data extracted, validating...");
+
+        // Normalize email
+        if (extracted.email) {
+          extracted.email = extracted.email.toLowerCase().trim();
+        }
+
+        // Normalize phone
+        if (extracted.phoneNumber) {
+          extracted.phoneNumber = extracted.phoneNumber.replace(/\D/g, "");
+        }
+
+        return extracted;
+      },
+    },
+  });
+
+  const route = agent.createRoute<OnboardingData>({
+    title: "Onboarding",
+    gatherSchema: {
+      type: "object",
+      properties: {
+        fullName: { type: "string" },
+        email: { type: "string" },
+        companyName: { type: "string" },
+        phoneNumber: { type: "string" },
+      },
+      required: ["fullName", "email", "companyName"],
+    },
+  });
+
+  route.initialState.transitionTo({
+    id: "collect_all",
+    chatState: "Collect all information",
+    gather: ["fullName", "email", "companyName", "phoneNumber"],
+  });
+
+  // Create database session
+  const dbSession = await db.createSession({
+    userId,
+    collectedData: {},
+  });
+
+  // Create agent session
+  let agentSession = createSession<OnboardingData>(dbSession.id, {
+    userId,
+  });
+
+  // Simulate conversation
+  const response = await agent.respond({
+    history: [
+      createMessageEvent(
+        EventSource.CUSTOMER,
+        "User",
+        "I'm Alice Johnson, alice@EXAMPLE.COM, working for TechCorp. Phone: (555) 123-4567"
+      ),
+    ],
+    session: agentSession,
+  });
+
+  console.log("🤖 Agent:", response.message);
+  console.log("📊 Normalized data:", response.session?.extracted);
+  // Shows: { email: "alice@example.com", phoneNumber: "5551234567", ... }
+
+  // Save to database
+  await db.updateSession(dbSession.id, {
+    currentRoute: response.session?.currentRoute?.id,
+    currentState: response.session?.currentState?.id,
+    collectedData: {
+      extracted: response.session?.extracted,
+      routeHistory: response.session?.routeHistory,
+      currentRouteTitle: response.session?.currentRoute?.title,
+      currentStateDescription: response.session?.currentState?.description,
+      metadata: response.session?.metadata,
+    },
+  });
+
+  console.log("✅ Validated data saved to custom database!");
+}
+
+// Run the example
+if (require.main === module) {
+  example().catch(console.error);
+}
+
+export { example, advancedExample };

package/examples/prisma-persistence.ts

@@ -128,14 +128,16 @@ async function example() {
     },
   });
 
-  // State flow with smart data gathering
+  // State flow with smart data gathering and custom IDs
   const askDestination = flightRoute.initialState.transitionTo({
+    id: "ask_destination", // Custom state ID for easier tracking
     chatState: "Ask where they want to fly",
     gather: ["destination"],
     skipIf: (extracted) => !!extracted.destination,
   });
 
   const askDates = askDestination.transitionTo({
+    id: "ask_dates", // Custom state ID
     chatState: "Ask about travel dates",
     gather: ["departureDate", "returnDate"],
     skipIf: (extracted) => !!extracted.departureDate,
@@ -143,6 +145,7 @@ async function example() {
   });
 
   const askPassengers = askDates.transitionTo({
+    id: "ask_passengers", // Custom state ID
     chatState: "Ask how many passengers",
     gather: ["passengers"],
     skipIf: (extracted) => !!extracted.passengers,
@@ -150,6 +153,7 @@ async function example() {
   });
 
   const askCabinClass = askPassengers.transitionTo({
+    id: "ask_cabin_class", // Custom state ID
     chatState: "Ask about cabin class preference",
     gather: ["cabinClass"],
     skipIf: (extracted) => !!extracted.cabinClass,
@@ -157,6 +161,7 @@ async function example() {
   });
 
   const confirmBooking = askCabinClass.transitionTo({
+    id: "confirm_booking", // Custom state ID
     chatState: "Present options and confirm booking details",
     requiredData: ["destination", "departureDate", "passengers", "cabinClass"],
   });
@@ -186,6 +191,10 @@ async function example() {
   const dbSessionId = sessionResult.sessionData.id;
 
   console.log("✨ Created new session:", dbSessionId);
+  console.log("📊 Session metadata:", {
+    sessionId: session.metadata?.sessionId, // Same as dbSessionId
+    createdAt: session.metadata?.createdAt,
+  });
   console.log("📊 Initial session state:", {
     currentRoute: session.currentRoute,
     extracted: session.extracted,
@@ -216,8 +225,10 @@ async function example() {
 
   console.log("🤖 Agent:", response1.message);
   console.log("📊 Session state after turn 1:", {
+    sessionId: response1.session?.metadata?.sessionId,
     currentRoute: response1.session?.currentRoute?.title,
-    currentState: response1.session?.currentState?.id,
+    currentStateId: response1.session?.currentState?.id, // Custom ID like "ask_destination"
+    currentStateDescription: response1.session?.currentState?.description,
     extracted: response1.session?.extracted,
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "description": "Standalone, strongly-typed AI Agent framework with route DSL and AI provider strategy",
   "type": "module",
   "main": "./dist/cjs/index.js",

package/src/core/State.ts

@@ -83,7 +83,7 @@ export class State<TContext = unknown, TExtracted = unknown> {
     const targetState = new State<TContext, TExtracted>(
       this.routeId,
       spec.chatState,
-      undefined,
+      spec.id, // Use custom ID if provided
       spec.gather,
       spec.skipIf,
       spec.requiredData

package/src/types/route.ts

@@ -70,6 +70,8 @@ export interface RouteOptions<TExtracted = unknown> {
  * Specification for a state transition
  */
 export interface TransitionSpec<TContext = unknown, TExtracted = unknown> {
+  /** Custom ID for this state (optional - will generate deterministic ID if not provided) */
+  id?: string;
   /** Transition to a chat state with this description */
   chatState?: string;
   /** Transition to execute a tool */