@falai/agent 0.3.11 → 0.3.12

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);
+  }
+}

package/src/index.ts

@@ -16,6 +16,7 @@ export { adaptEvent, createMessageEvent, createToolEvent } from "./core/Events";
 export { PromptBuilder } from "./core/PromptBuilder";
 export type { Customer, AgentInfo } from "./core/PromptBuilder";
 export { BuiltInSection } from "./core/PromptBuilder";
+export { PersistenceManager } from "./core/PersistenceManager";
 
 // Providers
 export { GeminiProvider } from "./providers/GeminiProvider";
@@ -27,6 +28,14 @@ export type { OpenRouterProviderOptions } from "./providers/OpenRouterProvider";
 export { AnthropicProvider } from "./providers/AnthropicProvider";
 export type { AnthropicProviderOptions } from "./providers/AnthropicProvider";
 
+// Adapters
+export { PrismaAdapter } from "./adapters/PrismaAdapter";
+export type {
+  PrismaClient,
+  FieldMappings,
+  PrismaAdapterOptions,
+} from "./adapters/PrismaAdapter";
+
 // Constants
 export { END_ROUTE } from "./constants";
 
@@ -94,3 +103,15 @@ export type {
   Observation as IObservation,
   ObservationOptions,
 } from "./types/observation";
+
+export type {
+  SessionData,
+  MessageData,
+  SessionStatus,
+  MessageRole,
+  SessionRepository,
+  MessageRepository,
+  PersistenceConfig,
+  CreateSessionOptions,
+  SaveMessageOptions,
+} from "./types/persistence";

package/src/types/agent.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";
 
 /**
  * Composition mode determines how the agent processes and structures responses
@@ -85,6 +86,8 @@ export interface AgentOptions<TContext = unknown> {
   routes?: RouteOptions[];
   /** Initial observations for disambiguation */
   observations?: ObservationOptions[];
+  /** Optional persistence configuration for auto-saving sessions and messages */
+  persistence?: PersistenceConfig;
 }
 
 /**

package/src/types/index.ts

@@ -54,3 +54,17 @@ export { SectionStatus } from "./prompt";
 
 // Observation types
 export type { Observation, ObservationOptions } from "./observation";
+
+// Persistence types
+export type {
+  SessionData,
+  MessageData,
+  SessionStatus,
+  MessageRole,
+  SessionRepository,
+  MessageRepository,
+  PersistenceAdapter,
+  PersistenceConfig,
+  CreateSessionOptions,
+  SaveMessageOptions,
+} from "./persistence";

package/src/types/persistence.ts

@@ -0,0 +1,234 @@
+/**
+ * Persistence-related type definitions
+ * Support for optional database persistence (Prisma, etc.)
+ */
+
+import type { Event } from "./history";
+
+/**
+ * Session status enum
+ */
+export type SessionStatus = "active" | "completed" | "abandoned";
+
+/**
+ * Message role enum
+ */
+export type MessageRole = "user" | "agent" | "system";
+
+/**
+ * Base session data structure
+ */
+export interface SessionData {
+  id: string;
+  userId?: string;
+  agentName?: string;
+  status: SessionStatus;
+  currentRoute?: string;
+  currentState?: string;
+  collectedData?: Record<string, unknown>;
+  messageCount?: number;
+  lastMessageAt?: Date;
+  completedAt?: Date;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/**
+ * Base message data structure
+ */
+export interface MessageData {
+  id: string;
+  sessionId: string;
+  userId?: string;
+  role: MessageRole;
+  content: string;
+  route?: string;
+  state?: string;
+  toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
+  event?: Event; // Optional: store full event data
+  createdAt: Date;
+}
+
+/**
+ * Repository interface for sessions
+ * Implement this interface with your database of choice
+ */
+export interface SessionRepository {
+  /**
+   * Create a new session
+   */
+  create(
+    data: Omit<SessionData, "id" | "createdAt" | "updatedAt">
+  ): Promise<SessionData>;
+
+  /**
+   * Find session by ID
+   */
+  findById(id: string): Promise<SessionData | null>;
+
+  /**
+   * Find active session by user ID
+   */
+  findActiveByUserId(userId: string): Promise<SessionData | null>;
+
+  /**
+   * Find all sessions for a user
+   */
+  findByUserId(userId: string, limit?: number): Promise<SessionData[]>;
+
+  /**
+   * Update session
+   */
+  update(
+    id: string,
+    data: Partial<Omit<SessionData, "id" | "createdAt">>
+  ): Promise<SessionData | null>;
+
+  /**
+   * Update session status
+   */
+  updateStatus(
+    id: string,
+    status: SessionStatus,
+    completedAt?: Date
+  ): Promise<SessionData | null>;
+
+  /**
+   * Update collected data
+   */
+  updateCollectedData(
+    id: string,
+    collectedData: Record<string, unknown>
+  ): Promise<SessionData | null>;
+
+  /**
+   * Update current route and state
+   */
+  updateRouteState(
+    id: string,
+    route?: string,
+    state?: string
+  ): Promise<SessionData | null>;
+
+  /**
+   * Increment message count
+   */
+  incrementMessageCount(id: string): Promise<SessionData | null>;
+
+  /**
+   * Delete session
+   */
+  delete(id: string): Promise<boolean>;
+}
+
+/**
+ * Repository interface for messages
+ * Implement this interface with your database of choice
+ */
+export interface MessageRepository {
+  /**
+   * Create a new message
+   */
+  create(data: Omit<MessageData, "id" | "createdAt">): Promise<MessageData>;
+
+  /**
+   * Find message by ID
+   */
+  findById(id: string): Promise<MessageData | null>;
+
+  /**
+   * Find all messages for a session
+   */
+  findBySessionId(sessionId: string, limit?: number): Promise<MessageData[]>;
+
+  /**
+   * Find messages for a user
+   */
+  findByUserId(userId: string, limit?: number): Promise<MessageData[]>;
+
+  /**
+   * Delete message by ID
+   */
+  delete(id: string): Promise<boolean>;
+
+  /**
+   * Delete all messages for a session
+   */
+  deleteBySessionId(sessionId: string): Promise<number>;
+
+  /**
+   * Delete all messages for a user
+   */
+  deleteByUserId(userId: string): Promise<number>;
+}
+
+/**
+ * Persistence adapter interface
+ * Implement this to create adapters for different databases
+ */
+export interface PersistenceAdapter {
+  /**
+   * Session repository
+   */
+  readonly sessionRepository: SessionRepository;
+
+  /**
+   * Message repository
+   */
+  readonly messageRepository: MessageRepository;
+
+  /**
+   * Initialize the adapter (create tables, indexes, etc.)
+   * Called automatically when adapter is created
+   */
+  initialize?(): Promise<void>;
+
+  /**
+   * Disconnect/cleanup resources
+   */
+  disconnect?(): Promise<void>;
+}
+
+/**
+ * Configuration for persistence
+ */
+export interface PersistenceConfig {
+  /**
+   * Persistence adapter instance (e.g., PrismaAdapter)
+   */
+  adapter: PersistenceAdapter;
+
+  /**
+   * Whether to auto-save messages (default: true)
+   */
+  autoSave?: boolean;
+
+  /**
+   * User ID to associate with sessions/messages
+   * Can also be provided per-call in methods
+   */
+  userId?: string;
+}
+
+/**
+ * Options for creating a session
+ */
+export interface CreateSessionOptions {
+  userId?: string;
+  agentName?: string;
+  initialData?: Record<string, unknown>;
+}
+
+/**
+ * Options for saving a message
+ */
+export interface SaveMessageOptions {
+  sessionId: string;
+  userId?: string;
+  role: MessageRole;
+  content: string;
+  route?: string;
+  state?: string;
+  toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
+  event?: Event;
+}