@falai/agent 0.9.0-alpha-2 → 0.9.0

package/src/core/ResponsePipeline.ts

@@ -670,7 +670,7 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
           string,
           Tool<TContext, TData, unknown[], unknown>
         >();
-        for (const toolId of allowedToolIds) {
+        for (const toolId of Array.from(allowedToolIds)) {
           const tool = availableTools.get(toolId);
           if (tool) {
             filteredTools.set(toolId, tool);

package/src/index.ts

@@ -8,6 +8,13 @@
 export { Agent } from "./core/Agent";
 export { Route } from "./core/Route";
 export { Step } from "./core/Step";
+export { ResponseModal } from "./core/ResponseModal";
+export type { 
+  ResponseModalOptions, 
+  RespondParams, 
+  StreamOptions, 
+  GenerateOptions 
+} from "./core/ResponseModal";
 export { adaptEvent, convertHistoryToEvents } from "./core/Events";
 export { PersistenceManager } from "./core/PersistenceManager";
 export { SessionManager } from "./core/SessionManager";
@@ -67,6 +74,10 @@ export { generateRouteId, generateStepId, generateToolId } from "./utils/id";
 export { formatKnowledgeBase } from "./utils/template";
 export {
   normalizeHistory,
+  historyItemToEvent,
+  historyToEvents,
+  eventToHistoryItem,
+  eventsToHistory,
   userMessage,
   assistantMessage,
   toolMessage,

package/src/types/agent.ts

@@ -173,6 +173,7 @@ export interface AgentResponseStreamChunk<TData = Record<string, unknown>> {
     [key: string]: unknown;
   };
   structured?: AgentStructuredResponse;
+  error?: Error;
 }
 
 /**

package/src/types/ai.ts

@@ -66,7 +66,7 @@ export interface GenerateMessageInput<TContext = unknown> {
 /**
  * Structured response from AI containing message and metadata
  */
-export interface AgentStructuredResponse {
+export interface AgentStructuredResponse extends Record<string, unknown> {
   /** The actual message to send to the user */
   message: string;
   /** Route chosen by the agent (route title or null if no route) */

package/src/utils/clone.ts

@@ -1,4 +1,4 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
+
 /**
  * Deep clone utility to avoid adding large dependencies like lodash.
  * Handles objects, arrays, dates, and primitives.
@@ -11,21 +11,19 @@ export function cloneDeep<T>(obj: T): T {
   }
 
   if (obj instanceof Date) {
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
-    return new Date(obj.getTime()) as any;
+    return new Date(obj.getTime()) as T;
   }
 
   if (Array.isArray(obj)) {
-    const arrCopy = [] as any[];
+    const arrCopy: unknown[] = [];
     for (let i = 0; i < obj.length; i++) {
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+       
       arrCopy[i] = cloneDeep(obj[i]);
     }
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
-    return arrCopy as any;
+    return arrCopy as T;
   }
 
-  const objCopy = {} as { [key: string]: any };
+  const objCopy: Record<string, unknown> = {};
   for (const key in obj) {
     if (Object.prototype.hasOwnProperty.call(obj, key)) {
       objCopy[key] = cloneDeep((obj as Record<string, unknown>)[key]);

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,