@falai/agent 0.9.0-alpha-1 → 0.9.0

package/src/utils/history.ts

@@ -3,33 +3,53 @@
  * Convert simplified history format to internal Event format
  */
 
-import type { Event, MessageEventData } from "../types";
+import type { Event, MessageEventData, ToolEventData, StatusEventData } from "../types";
 import { EventKind, MessageRole } from "../types";
-import type { History, HistoryItem } from "../types/history";
+import type { History, HistoryItem, UserHistoryItem, AssistantHistoryItem, ToolHistoryItem } from "../types/history";
 
 /**
  * Convert a simplified history item to an internal Event
+ * @param item - The HistoryItem to convert
+ * @returns Event with proper type-safe structure
+ * @throws Error if the history item is malformed or has invalid data
  */
-function convertHistoryItemToEvent(item: HistoryItem): Event {
+export function historyItemToEvent(item: HistoryItem): Event<MessageEventData | ToolEventData | StatusEventData> {
+  if (!item || typeof item !== 'object') {
+    throw new Error('Invalid history item: must be a non-null object');
+  }
+
+  if (!item.role || typeof item.role !== 'string') {
+    throw new Error('Invalid history item: role is required and must be a string');
+  }
+
   const timestamp = new Date().toISOString();
 
   switch (item.role) {
     case "user": {
+      const userItem = item;
+      if (typeof userItem.content !== 'string') {
+        throw new Error('Invalid user history item: content must be a string');
+      }
+      
       return {
         kind: EventKind.MESSAGE,
         source: MessageRole.USER,
         timestamp,
         data: {
           participant: {
-            display_name: item.name || "User",
+            display_name: userItem.name || "User",
           },
-          message: item.content,
+          message: userItem.content,
         },
       };
     }
     case "assistant": {
-      // Handle assistant message with optional tool calls
-      const event: Event = {
+      const assistantItem = item;
+      if (assistantItem.content !== null && typeof assistantItem.content !== 'string') {
+        throw new Error('Invalid assistant history item: content must be a string or null');
+      }
+
+      const event: Event<MessageEventData> = {
         kind: EventKind.MESSAGE,
         source: MessageRole.ASSISTANT,
         timestamp,
@@ -37,19 +57,36 @@ function convertHistoryItemToEvent(item: HistoryItem): Event {
           participant: {
             display_name: "Assistant",
           },
-          message: item.content || "",
+          message: assistantItem.content || "",
         },
       };
 
-      // If there are tool calls, we need to create a separate tool event
-      // But for now, we'll just store the tool calls in the message data
-      if (item.tool_calls && item.tool_calls.length > 0) {
-        (event.data as MessageEventData).toolCalls = item.tool_calls;
+      // If there are tool calls, validate and add them
+      if (assistantItem.tool_calls && assistantItem.tool_calls.length > 0) {
+        if (!Array.isArray(assistantItem.tool_calls)) {
+          throw new Error('Invalid assistant history item: tool_calls must be an array');
+        }
+        
+        for (const toolCall of assistantItem.tool_calls) {
+          if (!toolCall.id || !toolCall.name || typeof toolCall.arguments !== 'object') {
+            throw new Error('Invalid tool call: id, name, and arguments are required');
+          }
+        }
+        
+        event.data.toolCalls = assistantItem.tool_calls;
       }
 
       return event;
     }
     case "tool": {
+      const toolItem = item;
+      if (!toolItem.tool_call_id || typeof toolItem.tool_call_id !== 'string') {
+        throw new Error('Invalid tool history item: tool_call_id is required and must be a string');
+      }
+      if (!toolItem.name || typeof toolItem.name !== 'string') {
+        throw new Error('Invalid tool history item: name is required and must be a string');
+      }
+
       return {
         kind: EventKind.TOOL,
         source: MessageRole.AGENT,
@@ -57,10 +94,10 @@ function convertHistoryItemToEvent(item: HistoryItem): Event {
         data: {
           tool_calls: [
             {
-              tool_id: item.tool_call_id,
+              tool_id: toolItem.tool_call_id,
               arguments: {}, // Tool results don't have arguments
               result: {
-                data: item.content,
+                data: toolItem.content,
               },
             },
           ],
@@ -68,6 +105,11 @@ function convertHistoryItemToEvent(item: HistoryItem): Event {
       };
     }
     case "system": {
+      const systemItem = item;
+      if (typeof systemItem.content !== 'string') {
+        throw new Error('Invalid system history item: content must be a string');
+      }
+      
       return {
         kind: EventKind.MESSAGE,
         source: MessageRole.SYSTEM,
@@ -76,31 +118,152 @@ function convertHistoryItemToEvent(item: HistoryItem): Event {
           participant: {
             display_name: "System",
           },
-          message: item.content,
+          message: systemItem.content,
         },
       };
     }
     default:
-      // This should never happen due to TypeScript, but fallback just in case
+      throw new Error(`Invalid history item role: ${String((item as { role?: unknown }).role)}`);
+  }
+}
+
+/**
+ * Convert an array of HistoryItems to Events
+ * @param history - Array of HistoryItems to convert
+ * @returns Array of Events with proper type-safe structure
+ * @throws Error if any history item is malformed
+ */
+export function historyToEvents(history: History): Event<MessageEventData | ToolEventData | StatusEventData>[] {
+  if (!Array.isArray(history)) {
+    throw new Error('Invalid history: must be an array');
+  }
+  
+  return history.map((item, index) => {
+    try {
+      return historyItemToEvent(item);
+    } catch (error) {
+      throw new Error(`Error converting history item at index ${index}: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+  });
+}
+
+/**
+ * Convert an Event back to a HistoryItem
+ * @param event - The Event to convert
+ * @returns HistoryItem with simplified structure
+ * @throws Error if the event is malformed or has invalid data
+ */
+export function eventToHistoryItem(event: Event): HistoryItem {
+  if (!event || typeof event !== 'object') {
+    throw new Error('Invalid event: must be a non-null object');
+  }
+
+  if (!event.kind || !event.source || !event.data) {
+    throw new Error('Invalid event: kind, source, and data are required');
+  }
+
+  switch (event.kind) {
+    case EventKind.MESSAGE: {
+      const messageData = event.data as MessageEventData;
+      if (!messageData.message && messageData.message !== '') {
+        throw new Error('Invalid message event: message is required');
+      }
+
+      switch (event.source) {
+        case MessageRole.USER: {
+          const userItem: UserHistoryItem = {
+            role: "user",
+            content: messageData.message,
+          };
+          
+          if (messageData.participant?.display_name && messageData.participant.display_name !== "User") {
+            userItem.name = messageData.participant.display_name;
+          }
+          
+          return userItem;
+        }
+        case MessageRole.ASSISTANT: {
+          const assistantItem: AssistantHistoryItem = {
+            role: "assistant",
+            content: messageData.message || null,
+          };
+          
+          if (messageData.toolCalls && messageData.toolCalls.length > 0) {
+            assistantItem.tool_calls = messageData.toolCalls;
+          }
+          
+          return assistantItem;
+        }
+        case MessageRole.SYSTEM: {
+          return {
+            role: "system",
+            content: messageData.message,
+          };
+        }
+        default:
+          throw new Error(`Unsupported message source for conversion: ${event.source}`);
+      }
+    }
+    case EventKind.TOOL: {
+      const toolData = event.data as ToolEventData;
+      if (!toolData.tool_calls || !Array.isArray(toolData.tool_calls) || toolData.tool_calls.length === 0) {
+        throw new Error('Invalid tool event: tool_calls array is required and must not be empty');
+      }
+
+      const firstToolCall = toolData.tool_calls[0];
+      if (!firstToolCall.tool_id) {
+        throw new Error('Invalid tool call: tool_id is required');
+      }
+
+      const toolItem: ToolHistoryItem = {
+        role: "tool",
+        tool_call_id: firstToolCall.tool_id,
+        name: firstToolCall.tool_id, // Use tool_id as name for simplicity
+        content: firstToolCall.result?.data,
+      };
+      
+      return toolItem;
+    }
+    case EventKind.STATUS: {
+      // Status events don't have a direct HistoryItem equivalent
+      // Convert to system message for compatibility
+      const statusData = event.data as StatusEventData;
       return {
-        kind: EventKind.MESSAGE,
-        source: MessageRole.SYSTEM,
-        timestamp,
-        data: {
-          participant: {
-            display_name: "Unknown",
-          },
-          message: "Unknown message type",
-        },
+        role: "system",
+        content: statusData.status || "Status update",
       };
+    }
+    default:
+      throw new Error(`Unsupported event kind for conversion: ${String(event.kind)}`);
   }
 }
 
+/**
+ * Convert an array of Events back to HistoryItems
+ * @param events - Array of Events to convert
+ * @returns Array of HistoryItems with simplified structure
+ * @throws Error if any event is malformed
+ */
+export function eventsToHistory(events: Event[]): History {
+  if (!Array.isArray(events)) {
+    throw new Error('Invalid events: must be an array');
+  }
+  
+  return events.map((event, index) => {
+    try {
+      return eventToHistoryItem(event);
+    } catch (error) {
+      throw new Error(`Error converting event at index ${index}: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+  });
+}
+
 /**
  * Normalize a simplified history array to internal Event array
+ * @deprecated Use historyToEvents instead
  */
 export function normalizeHistory(history: History): Event[] {
-  return history.map(convertHistoryItemToEvent);
+  return historyToEvents(history);
 }
 
 /**
@@ -140,4 +303,4 @@ export function toolMessage(
  */
 export function systemMessage(content: string): HistoryItem {
   return { role: "system", content };
-}
+}

package/src/utils/index.ts

@@ -39,6 +39,10 @@ export { getLastMessageFromHistory } from "./event";
 // History utilities
 export {
   normalizeHistory,
+  historyItemToEvent,
+  historyToEvents,
+  eventToHistoryItem,
+  eventsToHistory,
   userMessage,
   assistantMessage,
   toolMessage,

package/src/utils/session.ts

@@ -16,8 +16,7 @@ export function createSession<TData = Record<string, unknown>>(
 
   return {
     id,
-    data: {} as Partial<TData>,
-    dataByRoute: {},
+    data: {} as Partial<TData>, // Agent-level data structure
     routeHistory: [],
     metadata: {
       ...metadata,
@@ -44,23 +43,13 @@ export function cloneSession<TData>(
 
 /**
  * Helper to update session with new route
- * Preserves collected data per route in dataByRoute map
+ * With agent-level data, routes share the same data structure
  */
 export function enterRoute<TData = Record<string, unknown>>(
   session: SessionState<TData>,
   routeId: string,
   routeTitle: string
 ): SessionState<TData> {
-  // Save current route's collected data before switching (if any)
-  const dataByRoute = { ...session.dataByRoute };
-  if (
-    session.currentRoute &&
-    session.data &&
-    Object.keys(session.data).length > 0
-  ) {
-    dataByRoute[session.currentRoute.id] = session.data;
-  }
-
   // Exit current route if exists
   const routeHistory = [...(session.routeHistory || [])];
   if (session.currentRoute) {
@@ -72,10 +61,7 @@ export function enterRoute<TData = Record<string, unknown>>(
     }
   }
 
-  // Load collected data for new route (if resuming) or start fresh
-  const newCollected = dataByRoute[routeId] || {};
-
-  // Enter new route
+  // Enter new route - data persists across routes at agent level
   const now = new Date();
   return {
     ...session,
@@ -85,8 +71,7 @@ export function enterRoute<TData = Record<string, unknown>>(
       enteredAt: now,
     },
     currentStep: undefined,
-    data: newCollected, // Load route's data or start fresh
-    dataByRoute,
+    // data remains the same - shared across all routes
     routeHistory: [
       ...routeHistory,
       {
@@ -126,7 +111,7 @@ export function enterStep<TData = Record<string, unknown>>(
 
 /**
  * Helper to merge collected data into session
- * Updates both data and dataByRoute for current route
+ * Updates agent-level data structure
  */
 export function mergeCollected<TData = Record<string, unknown>>(
   session: SessionState<TData>,
@@ -137,16 +122,9 @@ export function mergeCollected<TData = Record<string, unknown>>(
     ...data,
   } as Partial<TData>;
 
-  // Also update the dataByRoute map for the current route
-  const dataByRoute = { ...session.dataByRoute };
-  if (session.currentRoute) {
-    dataByRoute[session.currentRoute.id] = newCollected;
-  }
-
   return {
     ...session,
-    data: newCollected,
-    dataByRoute,
+    data: newCollected, // Agent-level data update
     metadata: {
       ...session.metadata,
       lastUpdatedAt: new Date(),
@@ -170,7 +148,6 @@ export function sessionStepToData<TData = Record<string, unknown>>(
     currentStep: session.currentStep?.id,
     collectedData: {
       data: session.data || {},
-      dataByRoute: session.dataByRoute || {}, // Include per-route data
       routeHistory: session.routeHistory,
       history: session.history, // Include conversation history
       currentRouteTitle: session.currentRoute?.title,
@@ -196,7 +173,6 @@ export function sessionDataToStep<TData = Record<string, unknown>>(
 ): SessionState<TData> {
   const collectedData: CollectedStateData<TData> = data.collectedData || {
     data: {},
-    dataByRoute: {},
     routeHistory: [],
     history: [],
     metadata: {},
@@ -221,7 +197,6 @@ export function sessionDataToStep<TData = Record<string, unknown>>(
         }
       : undefined,
     data: collectedData.data || {},
-    dataByRoute: collectedData.dataByRoute || {},
     routeHistory: collectedData.routeHistory || [],
     history: collectedData.history || [],
     metadata: collectedData.metadata || {},