@falai/agent 0.8.1 → 0.9.0-alpha-2

package/src/core/Events.ts

@@ -7,9 +7,58 @@ import type {
   EmittedEvent,
   MessageEventData,
   ToolEventData,
-  ToolCall,
-} from "../types/history";
-import { EventKind, EventSource } from "../types/history";
+  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
@@ -48,13 +97,11 @@ export function adaptEvent(e: Event | EmittedEvent): string {
     };
   }
 
-  const sourceMap: Record<EventSource, string> = {
-    [EventSource.CUSTOMER]: "user",
-    [EventSource.CUSTOMER_UI]: "frontend_application",
-    [EventSource.HUMAN_AGENT]: "human_service_agent",
-    [EventSource.HUMAN_AGENT_ON_BEHALF_OF_AI_AGENT]: "ai_agent",
-    [EventSource.AI_AGENT]: "ai_agent",
-    [EventSource.SYSTEM]: "system-provided",
+  const sourceMap: Record<MessageRole, string> = {
+    [MessageRole.USER]: "user",
+    [MessageRole.ASSISTANT]: "assistant",
+    [MessageRole.AGENT]: "agent",
+    [MessageRole.SYSTEM]: "system",
   };
 
   return JSON.stringify({
@@ -65,112 +112,53 @@ export function adaptEvent(e: Event | EmittedEvent): string {
 }
 
 /**
- * Create a message event
+ * Convert MessageData to HistoryItem
  */
-export function createMessageEvent(
-  source: EventSource,
-  participantName: string,
-  message: string,
-  options?: {
-    timestamp?: string;
-    session?: {
-      routeId?: string;
-      routeTitle?: string;
-      stepId?: string;
-      stepDescription?: string;
-      data?: Record<string, unknown>;
-    };
-  }
-): Event<MessageEventData>;
-export function createMessageEvent(options: {
-  source: EventSource;
-  participantName: string;
-  message: string;
-  timestamp?: string;
-  session?: {
-    routeId?: string;
-    routeTitle?: string;
-    stepId?: string;
-    stepDescription?: string;
-    data?: Record<string, unknown>;
-  };
-}): Event<MessageEventData>;
-export function createMessageEvent(
-  sourceOrOptions:
-    | EventSource
-    | {
-        source: EventSource;
-        participantName: string;
-        message: string;
-        timestamp?: string;
-        session?: {
-          routeId?: string;
-          routeTitle?: string;
-          stepId?: string;
-          stepDescription?: string;
-          data?: Record<string, unknown>;
-        };
-      },
-  participantName?: string,
-  message?: string,
-  options?: {
-    timestamp?: string;
-    session?: {
-      routeId?: string;
-      routeTitle?: string;
-      stepId?: string;
-      stepDescription?: string;
-      data?: Record<string, unknown>;
-    };
-  }
-): Event<MessageEventData> {
-  if (typeof sourceOrOptions === "object") {
-    // New signature: createMessageEvent(options)
-    const {
-      source,
-      participantName: pName,
-      message: msg,
-      ...restOptions
-    } = sourceOrOptions;
-    return {
-      kind: EventKind.MESSAGE,
-      source,
-      data: {
-        participant: { display_name: pName },
-        message: msg,
-        session: restOptions.session,
-      },
-      timestamp: restOptions.timestamp || new Date().toISOString(),
-    };
-  } else {
-    // Original signature: createMessageEvent(source, participantName, message, options)
-    return {
-      kind: EventKind.MESSAGE,
-      source: sourceOrOptions,
-      data: {
-        participant: { display_name: participantName! },
-        message: message!,
-        session: options?.session,
-      },
-      timestamp: options?.timestamp || new Date().toISOString(),
-    };
+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,
+      };
   }
 }
 
 /**
- * Create a tool event
+ * Convert an array of MessageData to History (HistoryItem[])
  */
-export function createToolEvent(
-  source: EventSource,
-  toolCalls: ToolCall[],
-  timestamp?: string
-): Event<ToolEventData> {
-  return {
-    kind: EventKind.TOOL,
-    source,
-    data: {
-      tool_calls: toolCalls,
-    },
-    timestamp: timestamp || new Date().toISOString(),
-  };
+export function convertMessagesToHistory(messages: MessageData[]): History {
+  return messages.map(convertMessageDataToHistoryItem);
 }

package/src/core/PersistenceManager.ts

@@ -12,25 +12,25 @@ import type {
   SessionStatus,
   SessionRepository,
   MessageRepository,
-} from "../types/persistence";
-import type { Event } from "../types/history";
-import type { SessionState } from "../types/session";
-import {
-  createSession,
-  sessionStepToData,
-  sessionDataToStep,
-} from "../types/session";
+  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 {
-  private config: PersistenceConfig;
-  private sessionRepository: SessionRepository;
+export class PersistenceManager<TData = Record<string, unknown>> {
+  private config: PersistenceConfig<TData>;
+  private sessionRepository: SessionRepository<TData>;
   private messageRepository: MessageRepository;
 
-  constructor(config: PersistenceConfig) {
+  constructor(config: PersistenceConfig<TData>) {
     this.config = {
       autoSave: true,
       ...config,
@@ -42,14 +42,20 @@ export class PersistenceManager {
   /**
    * Create a new session
    */
-  async createSession(options: CreateSessionOptions): Promise<SessionData> {
+  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: options.initialData || {},
+      collectedData: {
+        data: options.initialData || {},
+        routeHistory: [],
+        metadata: {},
+      },
       messageCount: 0,
     });
   }
@@ -57,14 +63,14 @@ export class PersistenceManager {
   /**
    * Get session by ID
    */
-  async getSession(sessionId: string): Promise<SessionData | null> {
+  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 | null> {
+  async findActiveSession(userId?: string): Promise<SessionData<TData> | null> {
     const effectiveUserId = userId || this.config.userId;
     if (!effectiveUserId) {
       throw new Error(
@@ -80,7 +86,7 @@ export class PersistenceManager {
   async getUserSessions(
     userId?: string,
     limit?: number
-  ): Promise<SessionData[]> {
+  ): Promise<SessionData<TData>[]> {
     const effectiveUserId = userId || this.config.userId;
     if (!effectiveUserId) {
       throw new Error(
@@ -97,7 +103,7 @@ export class PersistenceManager {
     sessionId: string,
     status: SessionStatus,
     completedAt?: Date
-  ): Promise<SessionData | null> {
+  ): Promise<SessionData<TData> | null> {
     return await this.sessionRepository.updateStatus(
       sessionId,
       status,
@@ -110,8 +116,8 @@ export class PersistenceManager {
    */
   async updateCollectedData(
     sessionId: string,
-    collectedData: Record<string, unknown>
-  ): Promise<SessionData | null> {
+    collectedData: CollectedStateData<TData>
+  ): Promise<SessionData<TData> | null> {
     return await this.sessionRepository.updateCollectedData(
       sessionId,
       collectedData
@@ -125,7 +131,7 @@ export class PersistenceManager {
     sessionId: string,
     route?: string,
     step?: string
-  ): Promise<SessionData | null> {
+  ): Promise<SessionData<TData> | null> {
     return await this.sessionRepository.updateRouteStep(sessionId, route, step);
   }
 
@@ -194,14 +200,14 @@ export class PersistenceManager {
   /**
    * Complete a session
    */
-  async completeSession(sessionId: string): Promise<SessionData | null> {
+  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 | null> {
+  async abandonSession(sessionId: string): Promise<SessionData<TData> | null> {
     return await this.updateSessionStatus(sessionId, "abandoned");
   }
 
@@ -215,36 +221,78 @@ export class PersistenceManager {
   /**
    * Helper: Load history from session messages
    */
-  async loadSessionHistory(sessionId: string): Promise<Event[]> {
+  async loadSessionHistory(sessionId: string): Promise<History> {
     const messages = await this.getSessionMessages(sessionId);
-    return messages
-      .map((m) => this.messageToEvent(m))
-      .filter((e): e is Event => e !== undefined);
+    return convertMessagesToHistory(messages);
   }
 
   /**
    * Save SessionState to database
    * Converts SessionState to SessionData and persists it
    */
-  async saveSessionState<TData = Record<string, unknown>>(
+  async saveSessionState(
     sessionId: string,
     sessionStep: SessionState<TData>
-  ): Promise<SessionData | null> {
-    const persistenceData = sessionStepToData(sessionStep);
-
-    return await this.sessionRepository.update(sessionId, {
-      currentRoute: persistenceData.currentRoute,
-      currentStep: persistenceData.currentStep,
-      collectedData: persistenceData.collectedData,
-      lastMessageAt: new Date(),
-    });
+  ): 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<TData = Record<string, unknown>>(
+  async loadSessionState(
     sessionId: string
   ): Promise<SessionState<TData> | null> {
     const sessionData = await this.sessionRepository.findById(sessionId);
@@ -253,11 +301,8 @@ export class PersistenceManager {
       return null;
     }
 
-    const stepData = sessionDataToStep<TData>(sessionId, {
-      currentRoute: sessionData.currentRoute,
-      currentStep: sessionData.currentStep,
-      collectedData: sessionData.collectedData,
-    });
+    // Reconstruct SessionState from SessionData
+    const sessionState = sessionDataToStep<TData>(sessionId, sessionData);
 
     // Create a full session step with the loaded data
     const session = createSession<TData>(sessionId, {
@@ -267,18 +312,27 @@ export class PersistenceManager {
 
     return {
       ...session,
-      ...stepData,
+      ...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<TData = Record<string, unknown>>(
-    options: CreateSessionOptions
-  ): Promise<{
-    sessionData: SessionData;
+  async createSessionWithStep(options: CreateSessionOptions<TData>): Promise<{
+    sessionData: SessionData<TData>;
     sessionStep: SessionState<TData>;
   }> {
     const sessionData = await this.createSession(options);
@@ -291,7 +345,7 @@ export class PersistenceManager {
 
     // If initial data was provided, merge it as collected data
     if (options.initialData) {
-      sessionStep.data = options.initialData as Partial<TData>;
+      sessionStep.data = options.initialData;
     }
 
     return { sessionData, sessionStep };