@falai/agent 1.1.0 → 1.1.1

package/docs/core/conversation-flows/route-dsl.md

@@ -481,8 +481,15 @@ const hasRequirements = step.hasRequires(collectedData);
 ### Route Testing
 
 ```typescript
-// Simulate route execution
+// Simulate route execution — classic signature
 const mockSession = createSession();
+
+// Or pre-populate with known data using partial state overload
+const prepopSession = createSession({
+  data: { name: "Test User" },
+  history: [{ role: "user", content: "Hello" }],
+});
+
 const mockHistory = [
   {
     role: "user",

package/docs/core/persistence/session-storage.md

@@ -154,12 +154,24 @@ model AgentMessage {
 While sessions are managed automatically, you can perform manual operations when needed:
 
 ```typescript
+import { createSession, createSessionId } from "@falai/agent";
+
 // Access session manager directly
 const sessionManager = agent.session;
 
 // Create session with specific ID
 await sessionManager.getOrCreate("custom-session-id");
 
+// Generate a session ID without creating a session object
+const id = createSessionId();
+
+// Create a pre-populated session using the partial state overload
+const restoredSession = createSession<MyDataType>({
+  id: "custom-session-id",
+  data: { userName: "John" },
+  history: previousHistory,
+});
+
 // Session data management
 await sessionManager.setData({
   userName: "John",

package/examples/integrations/database-integration.ts

@@ -17,6 +17,7 @@ import {
   SessionState,
   END_ROUTE,
   History,
+  createSessionId,
 } from "../../src";
 
 /**
@@ -64,7 +65,7 @@ class CustomDatabase {
     data: Omit<CustomDatabaseSession, "id" | "createdAt" | "updatedAt">
   ): CustomDatabaseSession {
     const session: CustomDatabaseSession = {
-      id: `session_${Date.now()}`,
+      id: createSessionId(),
       ...data,
       createdAt: new Date(),
       updatedAt: new Date(),
@@ -266,7 +267,7 @@ async function example() {
    * Simulate conversation with automatic sync
    */
   console.log("\n--- Turn 1 ---");
-  
+
   // Add user message to SessionManager
   await agent.session.addMessage("user", "Hi! I'm John Smith and my email is john@acme.com", "User");
 
@@ -286,7 +287,7 @@ async function example() {
 
   // Turn 2: User provides company
   console.log("\n--- Turn 2 ---");
-  
+
   await agent.session.addMessage("user", "I work for Acme Corporation", "User");
 
   const response2 = await agent.respond({
@@ -312,7 +313,7 @@ async function example() {
    * Demonstrate session recovery with new Agent instance
    */
   console.log("\n--- Session Recovery (New Agent Instance) ---");
-  
+
   // Create new agent instance (simulating app restart)
   const newAgent = new Agent({
     name: "Onboarding Assistant",
@@ -360,11 +361,11 @@ async function example() {
 
   // Continue conversation with recovered session
   await newAgent.session.addMessage("user", "Can you confirm my details?");
-  
+
   const confirmResponse = await newAgent.respond({
     history: newAgent.session.getHistory(),
   });
-  
+
   console.log("🤖 Confirmation:", confirmResponse.message);
   await newAgent.session.addMessage("assistant", confirmResponse.message);
 
@@ -414,7 +415,7 @@ async function syncSessionToDatabase(
 /**
  * Mock function to simulate processing the completed onboarding data.
  */
-async function processOnboarding(data) {
+async function processOnboarding(data: Partial<OnboardingData>) {
   console.log("\n🚀 Processing onboarding data...");
   console.log(
     `   - Creating account for ${data?.fullName} at ${data?.companyName}`
@@ -542,7 +543,7 @@ async function serverEndpointExample() {
     });
 
     // Load or create session
-    const effectiveSessionId = sessionId || `session_${userId}_${Date.now()}`;
+    const effectiveSessionId = sessionId || createSessionId();
     await agent.session.getOrCreate(effectiveSessionId);
 
     // Try to load from database if session exists
@@ -571,7 +572,7 @@ async function serverEndpointExample() {
 
     // Add user message and respond
     await agent.session.addMessage("user", message);
-    
+
     const response = await agent.respond({
       history: agent.session.getHistory(),
     });

package/examples/persistence/custom-adapter.ts

@@ -22,7 +22,7 @@ import type {
   SessionStatus,
   CollectedStateData,
 } from "../../src/types";
-import { Agent, GeminiProvider } from "../../src";
+import { Agent, GeminiProvider, createSessionId } from "../../src";
 
 /**
  * Simple in-memory storage for demonstration
@@ -40,7 +40,7 @@ class InMemoryStorage {
     }
   ): SessionData {
     const id =
-      data.id || `session_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+      data.id || createSessionId();
     const session: SessionData = {
       ...data,
       id,
@@ -249,9 +249,8 @@ class InMemoryStorage {
  * Custom Session Repository implementation
  */
 class CustomSessionRepository<TData = Record<string, unknown>>
-  implements SessionRepository<TData>
-{
-  constructor(private storage: InMemoryStorage) {}
+  implements SessionRepository<TData> {
+  constructor(private storage: InMemoryStorage) { }
 
   async create(
     data: Omit<SessionData<TData>, "createdAt" | "updatedAt"> & {
@@ -263,7 +262,7 @@ class CustomSessionRepository<TData = Record<string, unknown>>
         ...data,
         id:
           data.id ||
-          `session_${Date.now()}_${Math.random().toString(36).slice(2)}`,
+          createSessionId(),
       }) as SessionData<TData>
     );
   }
@@ -278,7 +277,7 @@ class CustomSessionRepository<TData = Record<string, unknown>>
     const sessions = this.storage.getSessionsByUserId(userId);
     return Promise.resolve(
       (sessions.find((s) => s.status === "active") as SessionData<TData>) ||
-        null
+      null
     );
   }
 
@@ -354,7 +353,7 @@ class CustomSessionRepository<TData = Record<string, unknown>>
  * Custom Message Repository implementation
  */
 class CustomMessageRepository implements MessageRepository {
-  constructor(private storage: InMemoryStorage) {}
+  constructor(private storage: InMemoryStorage) { }
 
   async create(
     data: Omit<MessageData, "id" | "createdAt">
@@ -398,9 +397,7 @@ class CustomMessageRepository implements MessageRepository {
  * This adapter demonstrates how to implement a custom persistence layer.
  * Replace the InMemoryStorage with actual database calls for production use.
  */
-export class CustomAdapter<TData = Record<string, unknown>>
-  implements PersistenceAdapter<TData>
-{
+export class CustomAdapter<TData = Record<string, unknown>> implements PersistenceAdapter<TData> {
   private storage = new InMemoryStorage();
 
   readonly sessionRepository: SessionRepository<TData>;
@@ -479,9 +476,9 @@ async function demonstrateCustomAdapter() {
 
   // First interaction
   console.log("\n💬 First interaction:");
-  
+
   await agent.session.addMessage("user", "Hi, I need help booking a flight", "Alice");
-  
+
   const response1 = await agent.respond({
     history: agent.session.getHistory(),
   });
@@ -493,9 +490,9 @@ async function demonstrateCustomAdapter() {
 
   // Second interaction
   console.log("\n💬 Second interaction:");
-  
+
   await agent.session.addMessage("user", "I want to fly to Paris next week", "Alice");
-  
+
   const response2 = await agent.respond({
     history: agent.session.getHistory(),
   });

package/package.json

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

package/src/adapters/MemoryAdapter.ts

@@ -14,6 +14,7 @@ import type {
   CreateSessionData,
 } from "../types";
 import { cloneDeep } from "../utils/clone";
+import { createSessionId } from "../utils";
 
 /**
  * Memory Adapter - Provider-style API for in-memory persistence
@@ -38,9 +39,7 @@ import { cloneDeep } from "../utils/clone";
  * });
  * ```
  */
-export class MemoryAdapter<TData = Record<string, unknown>>
-  implements PersistenceAdapter<TData>
-{
+export class MemoryAdapter<TData = Record<string, unknown>> implements PersistenceAdapter<TData> {
   public readonly sessionRepository: SessionRepository<TData>;
   public readonly messageRepository: MessageRepository;
   private sessions: Map<string, SessionData<TData>>;
@@ -80,13 +79,12 @@ export class MemoryAdapter<TData = Record<string, unknown>>
  * Memory Session Repository
  */
 class MemorySessionRepository<TData = Record<string, unknown>>
-  implements SessionRepository<TData>
-{
-  constructor(private sessions: Map<string, SessionData<TData>>) {}
+  implements SessionRepository<TData> {
+  constructor(private sessions: Map<string, SessionData<TData>>) { }
 
   create(data: CreateSessionData<TData>): Promise<SessionData<TData>> {
     const id =
-      data.id || `session_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+      data.id || createSessionId();
     const now = new Date();
 
     const session: SessionData<TData> = {
@@ -208,7 +206,7 @@ class MemorySessionRepository<TData = Record<string, unknown>>
  * Memory Message Repository
  */
 class MemoryMessageRepository implements MessageRepository {
-  constructor(private messages: Map<string, MessageData>) {}
+  constructor(private messages: Map<string, MessageData>) { }
 
   async create(
     data: Omit<MessageData, "id" | "createdAt">

package/src/adapters/MongoAdapter.ts

@@ -13,6 +13,7 @@ import type {
   CollectedStateData,
   CreateSessionData,
 } from "../types";
+import { createSessionId } from "../utils";
 
 /**
  * MongoDB collection interface - matches mongodb driver
@@ -100,9 +101,7 @@ export interface MongoAdapterOptions {
  * });
  * ```
  */
-export class MongoAdapter<TData = Record<string, unknown>>
-  implements PersistenceAdapter<TData>
-{
+export class MongoAdapter<TData = Record<string, unknown>> implements PersistenceAdapter<TData> {
   public readonly sessionRepository: SessionRepository<TData>;
   public readonly messageRepository: MessageRepository;
   private client: MongoClient;
@@ -133,9 +132,8 @@ export class MongoAdapter<TData = Record<string, unknown>>
  * MongoDB Session Repository
  */
 class MongoSessionRepository<TData = Record<string, unknown>>
-  implements SessionRepository<TData>
-{
-  constructor(private collection: MongoCollection<SessionData<TData>>) {}
+  implements SessionRepository<TData> {
+  constructor(private collection: MongoCollection<SessionData<TData>>) { }
 
   async create(data: CreateSessionData<TData>): Promise<SessionData<TData>> {
     const now = new Date();
@@ -143,7 +141,7 @@ class MongoSessionRepository<TData = Record<string, unknown>>
       ...data,
       id:
         data.id ||
-        `session_${Date.now()}_${Math.random().toString(36).slice(2)}`,
+        createSessionId(),
       status: data.status || "active",
       messageCount: data.messageCount || 0,
       createdAt: now,
@@ -249,7 +247,7 @@ class MongoSessionRepository<TData = Record<string, unknown>>
  * MongoDB Message Repository
  */
 class MongoMessageRepository implements MessageRepository {
-  constructor(private collection: MongoCollection<MessageData>) {}
+  constructor(private collection: MongoCollection<MessageData>) { }
 
   async create(
     data: Omit<MessageData, "id" | "createdAt">

package/src/adapters/OpenSearchAdapter.ts

@@ -33,6 +33,7 @@
  */
 
 import { cloneDeep } from "../utils/clone";
+import { createSessionId } from "../utils";
 import type {
   PersistenceAdapter,
   SessionRepository,
@@ -140,9 +141,7 @@ export interface OpenSearchAdapterOptions {
  * Stores sessions and messages as documents in OpenSearch indices.
  * Compatible with OpenSearch 1.x, 2.x and Elasticsearch 7.x.
  */
-export class OpenSearchAdapter<TData = Record<string, unknown>>
-  implements PersistenceAdapter<TData>
-{
+export class OpenSearchAdapter<TData = Record<string, unknown>> implements PersistenceAdapter<TData> {
   readonly sessionRepository: SessionRepository<TData>;
   readonly messageRepository: MessageRepository;
 
@@ -248,17 +247,16 @@ export class OpenSearchAdapter<TData = Record<string, unknown>>
  * OpenSearch-based session repository implementation
  */
 class OpenSearchSessionRepository<TData = Record<string, unknown>>
-  implements SessionRepository<TData>
-{
+  implements SessionRepository<TData> {
   constructor(
     private client: OpenSearchClient,
     private index: string,
     private refresh: boolean | "wait_for"
-  ) {}
+  ) { }
 
   async create(data: CreateSessionData<TData>): Promise<SessionData<TData>> {
     const id =
-      data.id || `session_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+      data.id || createSessionId();
     const now = new Date();
 
     const session: SessionData<TData> = {
@@ -514,7 +512,7 @@ class OpenSearchMessageRepository implements MessageRepository {
     private client: OpenSearchClient,
     private index: string,
     private refresh: boolean | "wait_for"
-  ) {}
+  ) { }
 
   async create(
     data: Omit<MessageData, "id" | "createdAt">

package/src/adapters/PostgreSQLAdapter.ts

@@ -12,6 +12,7 @@ import type {
   SessionStatus,
   PersistenceAdapter,
 } from "../types";
+import { createSessionId } from "../utils";
 
 /**
  * PostgreSQL query result interface
@@ -77,9 +78,7 @@ export interface PostgreSQLAdapterOptions {
  * });
  * ```
  */
-export class PostgreSQLAdapter<TData = Record<string, unknown>>
-  implements PersistenceAdapter<TData>
-{
+export class PostgreSQLAdapter<TData = Record<string, unknown>> implements PersistenceAdapter<TData> {
   public readonly sessionRepository: SessionRepository<TData>;
   public readonly messageRepository: MessageRepository;
   private client: PgClient;
@@ -159,9 +158,8 @@ export class PostgreSQLAdapter<TData = Record<string, unknown>>
  * PostgreSQL Session Repository
  */
 class PostgreSQLSessionRepository<TData = Record<string, unknown>>
-  implements SessionRepository<TData>
-{
-  constructor(private client: PgClient, private tableName: string) {}
+  implements SessionRepository<TData> {
+  constructor(private client: PgClient, private tableName: string) { }
 
   async create(
     data: Omit<SessionData<TData>, "createdAt" | "updatedAt"> & {
@@ -169,7 +167,7 @@ class PostgreSQLSessionRepository<TData = Record<string, unknown>>
     }
   ): Promise<SessionData<TData>> {
     const id =
-      data.id || `session_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+      data.id || createSessionId();
     const now = new Date();
 
     const result = await this.client.query<SessionData<TData>>(
@@ -335,7 +333,7 @@ class PostgreSQLSessionRepository<TData = Record<string, unknown>>
  * PostgreSQL Message Repository
  */
 class PostgreSQLMessageRepository implements MessageRepository {
-  constructor(private client: PgClient, private tableName: string) {}
+  constructor(private client: PgClient, private tableName: string) { }
 
   async create(
     data: Omit<MessageData, "id" | "createdAt">

package/src/adapters/PrismaAdapter.ts

@@ -16,6 +16,7 @@ import type {
   CreateSessionData,
 } from "../types";
 import { logger } from '../utils'
+import { createSessionId } from '../utils';
 
 /**
  * Prisma model operations
@@ -120,9 +121,7 @@ export interface PrismaAdapterOptions {
  * });
  * ```
  */
-export class PrismaAdapter<TData = Record<string, unknown>>
-  implements PersistenceAdapter<TData>
-{
+export class PrismaAdapter<TData = Record<string, unknown>> implements PersistenceAdapter<TData> {
   public readonly sessionRepository: SessionRepository<TData>;
   public readonly messageRepository: MessageRepository;
   private prisma: PrismaClient;
@@ -199,8 +198,7 @@ export class PrismaAdapter<TData = Record<string, unknown>>
  * Internal implementation - users should use PrismaAdapter instead
  */
 class PrismaSessionRepository<TData = Record<string, unknown>>
-  implements SessionRepository<TData>
-{
+  implements SessionRepository<TData> {
   private prisma: PrismaClient;
   private tableName: string;
   private fieldMap: Partial<Record<keyof SessionData<TData>, string>>;
@@ -270,7 +268,7 @@ class PrismaSessionRepository<TData = Record<string, unknown>>
       ...data,
       id:
         data.id ||
-        `session_${Date.now()}_${Math.random().toString(36).slice(2)}`,
+        createSessionId(),
     });
     const result = await this.getModel().create({
       data: mapped,

package/src/adapters/RedisAdapter.ts

@@ -74,9 +74,7 @@ export interface RedisAdapterOptions {
  * });
  * ```
  */
-export class RedisAdapter<TData = Record<string, unknown>>
-  implements PersistenceAdapter<TData>
-{
+export class RedisAdapter<TData = Record<string, unknown>> implements PersistenceAdapter<TData> {
   public readonly sessionRepository: SessionRepository<TData>;
   public readonly messageRepository: MessageRepository;
   private redis: RedisClient;
@@ -112,13 +110,12 @@ export class RedisAdapter<TData = Record<string, unknown>>
  * Redis Session Repository
  */
 class RedisSessionRepository<TData = Record<string, unknown>>
-  implements SessionRepository<TData>
-{
+  implements SessionRepository<TData> {
   constructor(
     private redis: RedisClient,
     private keyPrefix: string,
     private ttl: number
-  ) {}
+  ) { }
 
   private getKey(id: string): string {
     return `${this.keyPrefix}session:${id}`;
@@ -267,7 +264,7 @@ class RedisMessageRepository implements MessageRepository {
     private redis: RedisClient,
     private keyPrefix: string,
     private ttl: number
-  ) {}
+  ) { }
 
   private getKey(id: string): string {
     return `${this.keyPrefix}message:${id}`;

package/src/adapters/SQLiteAdapter.ts

@@ -71,9 +71,7 @@ export interface SQLiteAdapterOptions {
  * });
  * ```
  */
-export class SQLiteAdapter<TData = Record<string, unknown>>
-  implements PersistenceAdapter<TData>
-{
+export class SQLiteAdapter<TData = Record<string, unknown>> implements PersistenceAdapter<TData> {
   public readonly sessionRepository: SessionRepository<TData>;
   public readonly messageRepository: MessageRepository;
   private db: SqliteDatabase;
@@ -154,9 +152,8 @@ export class SQLiteAdapter<TData = Record<string, unknown>>
  * SQLite Session Repository
  */
 class SQLiteSessionRepository<TData = Record<string, unknown>>
-  implements SessionRepository<TData>
-{
-  constructor(private db: SqliteDatabase, private tableName: string) {}
+  implements SessionRepository<TData> {
+  constructor(private db: SqliteDatabase, private tableName: string) { }
 
   create(data: CreateSessionData<TData>): Promise<SessionData<TData>> {
     const id = data.id || createSessionId();
@@ -332,8 +329,8 @@ class SQLiteSessionRepository<TData = Record<string, unknown>>
       currentStep: (row.current_step as string) || undefined,
       collectedData: row.collected_data
         ? (JSON.parse(
-            row.collected_data as string
-          ) as CollectedStateData<TData>)
+          row.collected_data as string
+        ) as CollectedStateData<TData>)
         : undefined,
       messageCount: (row.message_count as number) || 0,
       lastMessageAt: row.last_message_at
@@ -352,7 +349,7 @@ class SQLiteSessionRepository<TData = Record<string, unknown>>
  * SQLite Message Repository
  */
 class SQLiteMessageRepository implements MessageRepository {
-  constructor(private db: SqliteDatabase, private tableName: string) {}
+  constructor(private db: SqliteDatabase, private tableName: string) { }
 
   create(data: Omit<MessageData, "id" | "createdAt">): Promise<MessageData> {
     const id = `msg_${Date.now()}_${Math.random().toString(36).slice(2)}`;