@falai/agent 0.1.0-alpha2

package/src/core/Events.ts

@@ -0,0 +1,164 @@
+/**
+ * Event utilities and helpers
+ */
+
+import type {
+  Event,
+  EmittedEvent,
+  MessageEventData,
+  ToolEventData,
+  HistoryMessage,
+  MessageData,
+  HistoryItem,
+  History,
+} from "../types";
+import { EventKind, MessageRole } from "../types";
+
+/**
+ * Convert a simple JSON history message to an internal Event
+ */
+export function convertHistoryMessage<TData = unknown>(
+  message: HistoryMessage<TData>
+): Event<MessageEventData> {
+  return {
+    kind: EventKind.MESSAGE,
+    source: message.role,
+    data: {
+      participant: {
+        display_name: message.name || getDefaultName(message.role),
+      },
+      message: message.content,
+      session: message.session,
+    },
+    timestamp: message.timestamp || new Date().toISOString(),
+    id: message.metadata?.id as string,
+  };
+}
+
+/**
+ * Get default participant name for a role
+ */
+function getDefaultName(role: MessageRole): string {
+  switch (role) {
+    case MessageRole.USER:
+      return "User";
+    case MessageRole.ASSISTANT:
+      return "Assistant";
+    case MessageRole.SYSTEM:
+      return "System";
+    default:
+      return "Unknown";
+  }
+}
+
+/**
+ * Convert an array of history messages to Events
+ */
+export function convertHistoryToEvents<TData = unknown>(
+  history: HistoryMessage<TData>[]
+): Event[] {
+  return history.map(convertHistoryMessage);
+}
+
+/**
+ * Adapt an event for inclusion in prompts
+ * Transforms event data into a serializable format
+ */
+export function adaptEvent(e: Event | EmittedEvent): string {
+  let data: unknown = e.data;
+
+  if (e.kind === EventKind.MESSAGE) {
+    const messageData = e.data as MessageEventData;
+
+    if (messageData.flagged) {
+      data = {
+        participant: messageData.participant.display_name,
+        message: "<N/A>",
+        censored: true,
+        reasons: messageData.tags,
+      };
+    } else {
+      data = {
+        participant: messageData.participant.display_name,
+        message: messageData.message,
+      };
+    }
+  }
+
+  if (e.kind === EventKind.TOOL) {
+    const toolData = e.data as ToolEventData;
+
+    data = {
+      tool_calls: toolData.tool_calls.map((tc) => ({
+        tool_id: tc.tool_id,
+        arguments: tc.arguments,
+        result: tc.result.data,
+      })),
+    };
+  }
+
+  const sourceMap: Record<MessageRole, string> = {
+    [MessageRole.USER]: "user",
+    [MessageRole.ASSISTANT]: "assistant",
+    [MessageRole.AGENT]: "agent",
+    [MessageRole.SYSTEM]: "system",
+  };
+
+  return JSON.stringify({
+    event_kind: e.kind,
+    event_source: sourceMap[e.source],
+    data,
+  });
+}
+
+/**
+ * Convert MessageData to HistoryItem
+ */
+export function convertMessageDataToHistoryItem(
+  message: MessageData
+): HistoryItem {
+  switch (message.role) {
+    case MessageRole.USER:
+      return {
+        role: "user",
+        content: message.content,
+      };
+    case MessageRole.ASSISTANT:
+      return {
+        role: "assistant",
+        content: message.content,
+        tool_calls: message.toolCalls?.map((tc, index) => ({
+          id: `call_${index}`, // Generate an ID since MessageData doesn't have tool call IDs
+          name: tc.toolName,
+          arguments: tc.arguments,
+        })),
+      };
+    case MessageRole.AGENT:
+      // Agent role typically represents tool execution results
+      // Since we don't have tool_call_id in MessageData, we'll use a placeholder
+      return {
+        role: "tool",
+        tool_call_id: "unknown", // MessageData doesn't store tool call IDs
+        name: "unknown_tool",
+        content: message.content,
+      };
+    case MessageRole.SYSTEM:
+      return {
+        role: "system",
+        content: message.content,
+      };
+    default:
+      // Fallback for unknown roles
+      return {
+        role: "system",
+        content: message.content,
+      };
+  }
+}
+
+/**
+ * Convert an array of MessageData to History (HistoryItem[])
+ */
+export function convertMessagesToHistory(messages: MessageData[]): History {
+  return messages.map(convertMessageDataToHistoryItem);
+}

package/src/core/PersistenceManager.ts

@@ -0,0 +1,353 @@
+/**
+ * Persistence Manager
+ * Handles optional persistence of sessions and messages
+ */
+
+import type {
+  PersistenceConfig,
+  SessionData,
+  MessageData,
+  CreateSessionOptions,
+  SaveMessageOptions,
+  SessionStatus,
+  SessionRepository,
+  MessageRepository,
+  Event,
+  SessionState,
+  History,
+  PersistenceAdapter,
+  CollectedStateData,
+} from "../types";
+import { createSession, sessionStepToData, sessionDataToStep } from "../utils";
+import { convertMessagesToHistory } from "./Events";
+
+/**
+ * Manager for handling persistence operations
+ * Provides a clean interface for optional database persistence
+ */
+export class PersistenceManager<TData = Record<string, unknown>> {
+  private config: PersistenceConfig<TData>;
+  private sessionRepository: SessionRepository<TData>;
+  private messageRepository: MessageRepository;
+
+  constructor(config: PersistenceConfig<TData>) {
+    this.config = {
+      autoSave: true,
+      ...config,
+    };
+    this.sessionRepository = config.adapter.sessionRepository;
+    this.messageRepository = config.adapter.messageRepository;
+  }
+
+  /**
+   * Create a new session
+   */
+  async createSession(
+    options: CreateSessionOptions<TData>
+  ): Promise<SessionData<TData>> {
+    const userId = options.userId || this.config.userId;
+
+    return await this.sessionRepository.create({
+      userId,
+      agentName: options.agentName,
+      status: "active",
+      collectedData: {
+        data: options.initialData || {},
+        routeHistory: [],
+        metadata: {},
+      },
+      messageCount: 0,
+    });
+  }
+
+  /**
+   * Get session by ID
+   */
+  async getSession(sessionId: string): Promise<SessionData<TData> | null> {
+    return await this.sessionRepository.findById(sessionId);
+  }
+
+  /**
+   * Find active session for a user
+   */
+  async findActiveSession(userId?: string): Promise<SessionData<TData> | 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<TData>[]> {
+    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<TData> | null> {
+    return await this.sessionRepository.updateStatus(
+      sessionId,
+      status,
+      completedAt
+    );
+  }
+
+  /**
+   * Update collected data in session
+   */
+  async updateCollectedData(
+    sessionId: string,
+    collectedData: CollectedStateData<TData>
+  ): Promise<SessionData<TData> | null> {
+    return await this.sessionRepository.updateCollectedData(
+      sessionId,
+      collectedData
+    );
+  }
+
+  /**
+   * Update current route and step
+   */
+  async updateRouteStep(
+    sessionId: string,
+    route?: string,
+    step?: string
+  ): Promise<SessionData<TData> | null> {
+    return await this.sessionRepository.updateRouteStep(sessionId, route, step);
+  }
+
+  /**
+   * 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,
+      step: options.step,
+      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<TData> | null> {
+    return await this.updateSessionStatus(sessionId, "completed", new Date());
+  }
+
+  /**
+   * Abandon a session
+   */
+  async abandonSession(sessionId: string): Promise<SessionData<TData> | 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<History> {
+    const messages = await this.getSessionMessages(sessionId);
+    return convertMessagesToHistory(messages);
+  }
+
+  /**
+   * Save SessionState to database
+   * Converts SessionState to SessionData and persists it
+   */
+  async saveSessionState(
+    sessionId: string,
+    sessionStep: SessionState<TData>
+  ): Promise<SessionData<TData> | null> {
+    // Validate input parameters
+    if (!sessionId || typeof sessionId !== 'string') {
+      throw new Error('Session ID must be a non-empty string');
+    }
+
+    if (!sessionStep || typeof sessionStep !== 'object') {
+      throw new Error('Session step must be a valid object');
+    }
+
+    // Validate session data structure
+    if (sessionStep.data && typeof sessionStep.data !== 'object') {
+      throw new Error('Session data must be an object');
+    }
+
+    let persistenceData;
+    try {
+      persistenceData = sessionStepToData(sessionStep);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new Error(`Failed to convert session step to persistence data: ${errorMessage}`);
+    }
+
+    try {
+      // First try to find existing session
+      const existingSession = await this.sessionRepository.findById(sessionId);
+
+      if (existingSession) {
+        // Update existing session
+        return await this.sessionRepository.update(sessionId, {
+          currentRoute: persistenceData.currentRoute,
+          currentStep: persistenceData.currentStep,
+          collectedData: persistenceData.collectedData,
+          lastMessageAt: new Date(),
+        });
+      } else {
+        // Create new session if it doesn't exist
+        return await this.sessionRepository.create({
+          id: sessionId,
+          userId: persistenceData.collectedData.metadata?.userId
+            ? JSON.stringify(persistenceData.collectedData.metadata?.userId)
+            : this.config.userId,
+          status: "active",
+          currentRoute: persistenceData.currentRoute,
+          currentStep: persistenceData.currentStep,
+          collectedData: persistenceData.collectedData,
+          messageCount: 0,
+        });
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new Error(`Failed to save session state to persistence: ${errorMessage}`);
+    }
+  }
+
+  /**
+   * Load SessionState from database
+   * Converts SessionData to SessionState
+   */
+  async loadSessionState(
+    sessionId: string
+  ): Promise<SessionState<TData> | null> {
+    const sessionData = await this.sessionRepository.findById(sessionId);
+
+    if (!sessionData) {
+      return null;
+    }
+
+    // Reconstruct SessionState from SessionData
+    const sessionState = sessionDataToStep<TData>(sessionId, sessionData);
+
+    // Create a full session step with the loaded data
+    const session = createSession<TData>(sessionId, {
+      createdAt: sessionData.createdAt,
+      lastUpdatedAt: sessionData.updatedAt,
+    });
+
+    return {
+      ...session,
+      ...sessionState,
+      metadata: {
+        ...session.metadata,
+        ...sessionState.metadata,
+      },
+    };
+  }
+
+  /**
+   * Get the underlying adapter
+   */
+  getAdapter(): PersistenceAdapter<TData> {
+    return this.config.adapter;
+  }
+
+  /**
+   * Create session with SessionState support
+   * Returns both SessionData and initialized SessionState
+   */
+  async createSessionWithStep(options: CreateSessionOptions<TData>): Promise<{
+    sessionData: SessionData<TData>;
+    sessionStep: SessionState<TData>;
+  }> {
+    const sessionData = await this.createSession(options);
+
+    // Create SessionState with database session ID
+    const sessionStep = createSession<TData>(sessionData.id, {
+      createdAt: sessionData.createdAt,
+      lastUpdatedAt: sessionData.updatedAt,
+    });
+
+    // If initial data was provided, merge it as collected data
+    if (options.initialData) {
+      sessionStep.data = options.initialData;
+    }
+
+    return { sessionData, sessionStep };
+  }
+}