@falai/agent 0.3.11 → 0.3.20

package/src/adapters/RedisAdapter.ts

@@ -0,0 +1,365 @@
+/**
+ * Redis adapter for persistence
+ * Uses Redis for fast session/message storage
+ */
+
+import type {
+  SessionRepository,
+  MessageRepository,
+  SessionData,
+  MessageData,
+  SessionStatus,
+  PersistenceAdapter,
+} from "../types/persistence";
+
+/**
+ * Redis client interface - matches ioredis/redis clients
+ */
+export interface RedisClient {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string): Promise<string | null>;
+  setex(key: string, seconds: number, value: string): Promise<string>;
+  del(...keys: string[]): Promise<number>;
+  keys(pattern: string): Promise<string[]>;
+  hgetall(key: string): Promise<Record<string, string>>;
+  hset(key: string, field: string, value: string): Promise<number>;
+  expire(key: string, seconds: number): Promise<number>;
+  quit(): Promise<string>;
+}
+
+/**
+ * Options for Redis adapter
+ */
+export interface RedisAdapterOptions {
+  /**
+   * Redis client instance (ioredis or node-redis)
+   */
+  redis: RedisClient;
+
+  /**
+   * Key prefix for all keys (default: "agent:")
+   */
+  keyPrefix?: string;
+
+  /**
+   * TTL in seconds for sessions (default: 7 days)
+   */
+  sessionTTL?: number;
+
+  /**
+   * TTL in seconds for messages (default: 30 days)
+   */
+  messageTTL?: number;
+}
+
+/**
+ * Redis Adapter - Provider-style API for Redis persistence
+ *
+ * @example
+ * ```typescript
+ * import Redis from 'ioredis';
+ * import { Agent, RedisAdapter } from '@falai/agent';
+ *
+ * const redis = new Redis();
+ *
+ * const agent = new Agent({
+ *   name: "My Agent",
+ *   ai: provider,
+ *   persistence: {
+ *     adapter: new RedisAdapter({ redis }),
+ *     userId: "user_123",
+ *   },
+ * });
+ * ```
+ */
+export class RedisAdapter implements PersistenceAdapter {
+  public readonly sessionRepository: SessionRepository;
+  public readonly messageRepository: MessageRepository;
+  private redis: RedisClient;
+  private keyPrefix: string;
+  private sessionTTL: number;
+  private messageTTL: number;
+
+  constructor(options: RedisAdapterOptions) {
+    this.redis = options.redis;
+    this.keyPrefix = options.keyPrefix || "agent:";
+    this.sessionTTL = options.sessionTTL || 7 * 24 * 60 * 60; // 7 days
+    this.messageTTL = options.messageTTL || 30 * 24 * 60 * 60; // 30 days
+
+    this.sessionRepository = new RedisSessionRepository(
+      this.redis,
+      this.keyPrefix,
+      this.sessionTTL
+    );
+
+    this.messageRepository = new RedisMessageRepository(
+      this.redis,
+      this.keyPrefix,
+      this.messageTTL
+    );
+  }
+
+  async disconnect(): Promise<void> {
+    await this.redis.quit();
+  }
+}
+
+/**
+ * Redis Session Repository
+ */
+class RedisSessionRepository implements SessionRepository {
+  constructor(
+    private redis: RedisClient,
+    private keyPrefix: string,
+    private ttl: number
+  ) {}
+
+  private getKey(id: string): string {
+    return `${this.keyPrefix}session:${id}`;
+  }
+
+  private getUserKey(userId: string): string {
+    return `${this.keyPrefix}user:${userId}:sessions`;
+  }
+
+  async create(
+    data: Omit<SessionData, "id" | "createdAt" | "updatedAt">
+  ): Promise<SessionData> {
+    const id = `session_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+    const now = new Date();
+    const session: SessionData = {
+      ...data,
+      id,
+      createdAt: now,
+      updatedAt: now,
+      status: data.status || "active",
+      messageCount: data.messageCount || 0,
+    };
+
+    await this.redis.setex(this.getKey(id), this.ttl, JSON.stringify(session));
+
+    // Add to user's session list
+    if (data.userId) {
+      await this.redis.hset(
+        this.getUserKey(data.userId),
+        id,
+        now.toISOString()
+      );
+    }
+
+    return session;
+  }
+
+  async findById(id: string): Promise<SessionData | null> {
+    const data = await this.redis.get(this.getKey(id));
+    if (!data) return null;
+    try {
+      return JSON.parse(data) as SessionData;
+    } catch (error) {
+      console.error(`Error parsing session data for id ${id}:`, error);
+      return null;
+    }
+  }
+
+  async findActiveByUserId(userId: string): Promise<SessionData | null> {
+    const sessionIds = await this.redis.hgetall(this.getUserKey(userId));
+
+    for (const sessionId of Object.keys(sessionIds)) {
+      const session = await this.findById(sessionId);
+      if (session && session.status === "active") {
+        return session;
+      }
+    }
+
+    return null;
+  }
+
+  async findByUserId(userId: string, limit = 100): Promise<SessionData[]> {
+    const sessionIds = await this.redis.hgetall(this.getUserKey(userId));
+    const sessions: SessionData[] = [];
+
+    for (const sessionId of Object.keys(sessionIds).slice(0, limit)) {
+      const session = await this.findById(sessionId);
+      if (session) {
+        sessions.push(session);
+      }
+    }
+
+    return sessions.sort(
+      (a, b) => b.createdAt.getTime() - a.createdAt.getTime()
+    );
+  }
+
+  async update(
+    id: string,
+    data: Partial<Omit<SessionData, "id" | "createdAt">>
+  ): Promise<SessionData | null> {
+    const existing = await this.findById(id);
+    if (!existing) return null;
+
+    const updated: SessionData = {
+      ...existing,
+      ...data,
+      updatedAt: new Date(),
+    };
+
+    await this.redis.setex(this.getKey(id), this.ttl, JSON.stringify(updated));
+
+    return updated;
+  }
+
+  async updateStatus(
+    id: string,
+    status: SessionStatus,
+    completedAt?: Date
+  ): Promise<SessionData | null> {
+    return this.update(id, { status, completedAt });
+  }
+
+  async updateCollectedData(
+    id: string,
+    collectedData: Record<string, unknown>
+  ): Promise<SessionData | null> {
+    return this.update(id, { collectedData });
+  }
+
+  async updateRouteState(
+    id: string,
+    route?: string,
+    state?: string
+  ): Promise<SessionData | null> {
+    return this.update(id, { currentRoute: route, currentState: state });
+  }
+
+  async incrementMessageCount(id: string): Promise<SessionData | null> {
+    const session = await this.findById(id);
+    if (!session) return null;
+
+    return this.update(id, {
+      messageCount: (session.messageCount || 0) + 1,
+      lastMessageAt: new Date(),
+    });
+  }
+
+  async delete(id: string): Promise<boolean> {
+    const result = await this.redis.del(this.getKey(id));
+    return result > 0;
+  }
+}
+
+/**
+ * Redis Message Repository
+ */
+class RedisMessageRepository implements MessageRepository {
+  constructor(
+    private redis: RedisClient,
+    private keyPrefix: string,
+    private ttl: number
+  ) {}
+
+  private getKey(id: string): string {
+    return `${this.keyPrefix}message:${id}`;
+  }
+
+  private getSessionKey(sessionId: string): string {
+    return `${this.keyPrefix}session:${sessionId}:messages`;
+  }
+
+  async create(
+    data: Omit<MessageData, "id" | "createdAt">
+  ): Promise<MessageData> {
+    const id = `msg_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+    const message: MessageData = {
+      ...data,
+      id,
+      createdAt: new Date(),
+    };
+
+    await this.redis.setex(this.getKey(id), this.ttl, JSON.stringify(message));
+    await this.redis.hset(
+      this.getSessionKey(data.sessionId),
+      id,
+      message.createdAt.toISOString()
+    );
+
+    return message;
+  }
+
+  async findById(id: string): Promise<MessageData | null> {
+    const data = await this.redis.get(this.getKey(id));
+    if (!data) return null;
+    try {
+      return JSON.parse(data) as MessageData;
+    } catch (error) {
+      console.error(`Error parsing message data for id ${id}:`, error);
+      return null;
+    }
+  }
+
+  async findBySessionId(
+    sessionId: string,
+    limit = 1000
+  ): Promise<MessageData[]> {
+    const messageIds = await this.redis.hgetall(this.getSessionKey(sessionId));
+    const messages: MessageData[] = [];
+
+    for (const messageId of Object.keys(messageIds).slice(0, limit)) {
+      const message = await this.findById(messageId);
+      if (message) {
+        messages.push(message);
+      }
+    }
+
+    return messages.sort(
+      (a, b) => a.createdAt.getTime() - b.createdAt.getTime()
+    );
+  }
+
+  async findByUserId(userId: string, limit = 100): Promise<MessageData[]> {
+    // Redis doesn't have efficient user-level querying
+    // This would require additional indexing
+    const pattern = `${this.keyPrefix}message:*`;
+    const keys = await this.redis.keys(pattern);
+    const messages: MessageData[] = [];
+
+    for (const key of keys.slice(0, limit)) {
+      const data = await this.redis.get(key);
+      if (data) {
+        const message: MessageData = JSON.parse(data) as MessageData;
+        if (message.userId === userId) {
+          messages.push(message);
+        }
+      }
+    }
+
+    return messages.sort(
+      (a, b) => b.createdAt.getTime() - a.createdAt.getTime()
+    );
+  }
+
+  async delete(id: string): Promise<boolean> {
+    const result = await this.redis.del(this.getKey(id));
+    return result > 0;
+  }
+
+  async deleteBySessionId(sessionId: string): Promise<number> {
+    const messageIds = await this.redis.hgetall(this.getSessionKey(sessionId));
+    const keys = Object.keys(messageIds).map((id) => this.getKey(id));
+
+    if (keys.length === 0) return 0;
+
+    const result = await this.redis.del(...keys);
+    await this.redis.del(this.getSessionKey(sessionId));
+
+    return result;
+  }
+
+  async deleteByUserId(userId: string): Promise<number> {
+    const messages = await this.findByUserId(userId);
+    const keys = messages.map((m) => this.getKey(m.id));
+
+    if (keys.length === 0) return 0;
+
+    return await this.redis.del(...keys);
+  }
+}

package/src/adapters/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Database adapters for persistence
+ */
+
+export { PrismaAdapter } from "./PrismaAdapter";
+export type {
+  PrismaClient,
+  FieldMappings,
+  PrismaAdapterOptions,
+} from "./PrismaAdapter";
+
+export { RedisAdapter } from "./RedisAdapter";
+export type { RedisClient, RedisAdapterOptions } from "./RedisAdapter";
+
+export { MongoAdapter } from "./MongoAdapter";
+export type {
+  MongoClient,
+  MongoDatabase,
+  MongoCollection,
+  MongoAdapterOptions,
+} from "./MongoAdapter";
+
+export { PostgreSQLAdapter } from "./PostgreSQLAdapter";
+export type {
+  PgClient,
+  PgQueryResult,
+  PostgreSQLAdapterOptions,
+} from "./PostgreSQLAdapter";

package/src/core/Agent.ts

@@ -16,6 +16,7 @@ import { Route } from "./Route";
 import { DomainRegistry } from "./DomainRegistry";
 import { PromptBuilder } from "./PromptBuilder";
 import { Observation } from "./Observation";
+import { PersistenceManager } from "./PersistenceManager";
 
 /**
  * Main Agent class with generic context support
@@ -28,6 +29,7 @@ export class Agent<TContext = unknown> {
   private observations: Observation[] = [];
   private domainRegistry = new DomainRegistry();
   private context: TContext | undefined;
+  private persistenceManager: PersistenceManager | undefined;
 
   /**
    * Dynamic domain property - populated via addDomain
@@ -50,6 +52,21 @@ export class Agent<TContext = unknown> {
     // Initialize context if provided
     this.context = options.context;
 
+    // Initialize persistence if configured
+    if (options.persistence) {
+      this.persistenceManager = new PersistenceManager(options.persistence);
+
+      // 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
+          );
+        });
+      }
+    }
+
     // Initialize from options
     if (options.terms) {
       this.terms = [...options.terms];
@@ -598,6 +615,20 @@ export class Agent<TContext = unknown> {
     return this.domainRegistry;
   }
 
+  /**
+   * Get the persistence manager (if configured)
+   */
+  getPersistenceManager(): PersistenceManager | undefined {
+    return this.persistenceManager;
+  }
+
+  /**
+   * Check if persistence is enabled
+   */
+  hasPersistence(): boolean {
+    return this.persistenceManager !== undefined;
+  }
+
   /**
    * Get allowed domains for a specific route
    * @param routeId - Route ID to check

package/src/core/PersistenceManager.ts

@@ -0,0 +1,222 @@
+/**
+ * Persistence Manager
+ * Handles optional persistence of sessions and messages
+ */
+
+import type {
+  PersistenceConfig,
+  SessionData,
+  MessageData,
+  CreateSessionOptions,
+  SaveMessageOptions,
+  SessionStatus,
+  SessionRepository,
+  MessageRepository,
+} from "../types/persistence";
+import type { Event } from "../types/history";
+
+/**
+ * Manager for handling persistence operations
+ * Provides a clean interface for optional database persistence
+ */
+export class PersistenceManager {
+  private config: PersistenceConfig;
+  private sessionRepository: SessionRepository;
+  private messageRepository: MessageRepository;
+
+  constructor(config: PersistenceConfig) {
+    this.config = {
+      autoSave: true,
+      ...config,
+    };
+    this.sessionRepository = config.adapter.sessionRepository;
+    this.messageRepository = config.adapter.messageRepository;
+  }
+
+  /**
+   * Create a new session
+   */
+  async createSession(options: CreateSessionOptions): Promise<SessionData> {
+    const userId = options.userId || this.config.userId;
+
+    return await this.sessionRepository.create({
+      userId,
+      agentName: options.agentName,
+      status: "active",
+      collectedData: options.initialData || {},
+      messageCount: 0,
+    });
+  }
+
+  /**
+   * Get session by ID
+   */
+  async getSession(sessionId: string): Promise<SessionData | null> {
+    return await this.sessionRepository.findById(sessionId);
+  }
+
+  /**
+   * Find active session for a user
+   */
+  async findActiveSession(userId?: string): Promise<SessionData | null> {
+    const effectiveUserId = userId || this.config.userId;
+    if (!effectiveUserId) {
+      throw new Error(
+        "userId must be provided or configured in PersistenceConfig"
+      );
+    }
+    return await this.sessionRepository.findActiveByUserId(effectiveUserId);
+  }
+
+  /**
+   * Get all sessions for a user
+   */
+  async getUserSessions(
+    userId?: string,
+    limit?: number
+  ): Promise<SessionData[]> {
+    const effectiveUserId = userId || this.config.userId;
+    if (!effectiveUserId) {
+      throw new Error(
+        "userId must be provided or configured in PersistenceConfig"
+      );
+    }
+    return await this.sessionRepository.findByUserId(effectiveUserId, limit);
+  }
+
+  /**
+   * Update session status
+   */
+  async updateSessionStatus(
+    sessionId: string,
+    status: SessionStatus,
+    completedAt?: Date
+  ): Promise<SessionData | null> {
+    return await this.sessionRepository.updateStatus(
+      sessionId,
+      status,
+      completedAt
+    );
+  }
+
+  /**
+   * Update collected data in session
+   */
+  async updateCollectedData(
+    sessionId: string,
+    collectedData: Record<string, unknown>
+  ): Promise<SessionData | null> {
+    return await this.sessionRepository.updateCollectedData(
+      sessionId,
+      collectedData
+    );
+  }
+
+  /**
+   * Update current route and state
+   */
+  async updateRouteState(
+    sessionId: string,
+    route?: string,
+    state?: string
+  ): Promise<SessionData | null> {
+    return await this.sessionRepository.updateRouteState(
+      sessionId,
+      route,
+      state
+    );
+  }
+
+  /**
+   * Save a message
+   */
+  async saveMessage(options: SaveMessageOptions): Promise<MessageData> {
+    const userId = options.userId || this.config.userId;
+
+    const message = await this.messageRepository.create({
+      sessionId: options.sessionId,
+      userId,
+      role: options.role,
+      content: options.content,
+      route: options.route,
+      state: options.state,
+      toolCalls: options.toolCalls,
+      event: options.event,
+    });
+
+    // Increment message count in session if autoSave is enabled
+    if (this.config.autoSave) {
+      await this.sessionRepository.incrementMessageCount(options.sessionId);
+    }
+
+    return message;
+  }
+
+  /**
+   * Get all messages for a session
+   */
+  async getSessionMessages(
+    sessionId: string,
+    limit?: number
+  ): Promise<MessageData[]> {
+    return await this.messageRepository.findBySessionId(sessionId, limit);
+  }
+
+  /**
+   * Get messages for a user
+   */
+  async getUserMessages(
+    userId?: string,
+    limit?: number
+  ): Promise<MessageData[]> {
+    const effectiveUserId = userId || this.config.userId;
+    if (!effectiveUserId) {
+      throw new Error(
+        "userId must be provided or configured in PersistenceConfig"
+      );
+    }
+    return await this.messageRepository.findByUserId(effectiveUserId, limit);
+  }
+
+  /**
+   * Delete a session and all its messages
+   */
+  async deleteSession(sessionId: string): Promise<boolean> {
+    // Delete all messages first
+    await this.messageRepository.deleteBySessionId(sessionId);
+
+    // Then delete the session
+    return await this.sessionRepository.delete(sessionId);
+  }
+
+  /**
+   * Complete a session
+   */
+  async completeSession(sessionId: string): Promise<SessionData | null> {
+    return await this.updateSessionStatus(sessionId, "completed", new Date());
+  }
+
+  /**
+   * Abandon a session
+   */
+  async abandonSession(sessionId: string): Promise<SessionData | null> {
+    return await this.updateSessionStatus(sessionId, "abandoned");
+  }
+
+  /**
+   * Helper: Convert message data to Event format
+   */
+  messageToEvent(message: MessageData): Event | undefined {
+    return message.event;
+  }
+
+  /**
+   * Helper: Load history from session messages
+   */
+  async loadSessionHistory(sessionId: string): Promise<Event[]> {
+    const messages = await this.getSessionMessages(sessionId);
+    return messages
+      .map((m) => this.messageToEvent(m))
+      .filter((e): e is Event => e !== undefined);
+  }
+}