@falai/agent 0.9.0-alpha-2 → 0.9.2

package/src/index.ts

@@ -8,11 +8,17 @@
 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";
-export { ToolExecutor } from "./core/ToolExecutor";
-export type { ToolExecutionResult } from "./core/ToolExecutor";
+export { ToolManager, ToolCreationError, ToolExecutionError } from "./core/ToolManager";
 
 // Providers
 export { GeminiProvider } from "./providers/GeminiProvider";
@@ -67,6 +73,10 @@ export { generateRouteId, generateStepId, generateToolId } from "./utils/id";
 export { formatKnowledgeBase } from "./utils/template";
 export {
   normalizeHistory,
+  historyItemToEvent,
+  historyToEvents,
+  eventToHistoryItem,
+  eventsToHistory,
   userMessage,
   assistantMessage,
   toolMessage,
@@ -91,7 +101,6 @@ export type {
   StepRef,
   RouteOptions,
   StepOptions,
-  StepResult,
   RouteTransitionConfig,
   RouteCompletionHandler,
   SessionState,
@@ -100,6 +109,13 @@ export type {
   ToolResult,
   ToolHandler,
   Tool,
+
+  DataEnrichmentConfig,
+  ValidationConfig,
+  ValidationError,
+  ApiCallConfig,
+  ComputationConfig,
+  ToolScope,
   AiProvider,
   GenerateMessageInput,
   GenerateMessageOutput,

package/src/types/agent.ts

@@ -99,7 +99,7 @@ export interface AgentOptions<TContext = unknown, TData = unknown> {
   /** Initial guidelines for agent behavior */
   guidelines?: Guideline<TContext, TData>[];
   /** Global tools available to all routes */
-  tools?: Tool<TContext, TData, unknown[], unknown>[];
+  tools?: Tool<TContext, TData, unknown>[];
   /** Initial routes (will be instantiated as Route objects) */
   routes?: RouteOptions<TContext, TData>[];
   /** Optional persistence configuration for auto-saving sessions and messages */
@@ -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/types/index.ts

@@ -45,8 +45,8 @@ export type {
   RouteRef,
   StepRef,
   StepOptions,
-  StepResult,
   BranchSpec,
+  StepResult,
   BranchResult,
   RouteCompletionHandler,
   RouteTransitionConfig,
@@ -58,7 +58,18 @@ export * from "./route";
 export type { SessionState, PendingTransition } from "./session";
 
 // Tool types
-export type { Tool, ToolContext, ToolResult, ToolHandler } from "./tool";
+export type { 
+  Tool, 
+  ToolContext, 
+  ToolResult, 
+  ToolHandler,
+  ToolExecutionResult,
+  DataEnrichmentConfig,
+  ValidationConfig,
+  ApiCallConfig,
+  ComputationConfig
+} from "./tool";
+export { ToolScope } from "./tool";
 
 // AI provider types
 export type {

package/src/types/route.ts

@@ -104,7 +104,7 @@ export interface RouteOptions<TContext = unknown, TData = unknown> {
   /** Initial terms for the route's domain glossary */
   terms?: Term<TContext>[];
   /** Tools available in this route */
-  tools?: Tool<TContext, TData, unknown[], unknown>[];
+  tools?: Tool<TContext, TData>[];
   /** Absolute rules the agent must follow in this route */
   rules?: Template<TContext, TData>[];
   /** Absolute prohibitions the agent must never do in this route */
@@ -197,16 +197,16 @@ export interface StepOptions<TContext = unknown, TData = unknown> {
   /** Transition to a chat state with this description */
   prompt?: Template<TContext, TData>;
   /** Tools available for AI to call in this step (by ID reference or inline definition) */
-  tools?: (string | Tool<TContext, TData, unknown[], unknown>)[];
+  tools?: (string | Tool<TContext, TData>)[];
   /** Programmatic function or tool to run before AI responds */
   prepare?:
     | string
-    | Tool<TContext, TData, unknown[], unknown>
+    | Tool<TContext, TData>
     | ((context: TContext, data?: Partial<TData>) => void | Promise<void>);
   /** Programmatic function or tool to run after AI responds */
   finalize?:
     | string
-    | Tool<TContext, TData, unknown[], unknown>
+    | Tool<TContext, TData>
     | ((context: TContext, data?: Partial<TData>) => void | Promise<void>);
   /** Transition to a specific step or end marker */
   step?: StepRef | symbol;
@@ -267,4 +267,6 @@ export interface StepResult<TContext = unknown, TData = unknown>
   branch: (
     branches: BranchSpec<TContext, TData>[]
   ) => BranchResult<TContext, TData>;
+  /** Shortcut to end the current route */
+  endRoute: (options?: Omit<StepOptions<TContext, TData>, "step">) => StepResult<TContext, TData>;
 }

package/src/types/tool.ts

@@ -1,36 +1,44 @@
+/* eslint @typescript-eslint/no-explicit-any: "off"*/
 /**
  * Tool system type definitions
  */
 
-import type { Event, StepRef } from "./index";
+import type { Event, StepRef, ValidationResult } from "./index";
 
 /**
  * Context provided to tool handlers
  */
-export interface ToolContext<TContext = unknown, TData = unknown> {
+export interface ToolContext<TContext = any, TData = any> {
   /** The agent's context data */
   context: TContext;
-  /** Update the agent's context (triggers lifecycle hooks if configured) */
-  updateContext: (updates: Partial<TContext>) => Promise<void>;
-  /** Update the agent's collected data (triggers lifecycle hooks if configured) */
-  updateData: (updates: Partial<TData>) => Promise<void>;
-  /** Current step reference (if in a route) */
-  step?: StepRef;
+  /** Complete agent-level data collected so far */
+  data: Partial<TData>;
   /** Interaction history */
   history: Event[];
-  /** Complete agent-level data collected so far */
-  data?: Partial<TData>;
+  /** Current step reference (if in a route) */
+  step?: StepRef;
   /** Additional metadata */
   metadata?: Record<string, unknown>;
+
+  /** Update the agent's context (triggers lifecycle hooks if configured) */
+  updateContext: (updates: Partial<TContext>) => Promise<void>;
+  /** Update the agent's collected data (triggers lifecycle hooks if configured) */
+  updateData: (updates: Partial<TData>) => Promise<void>;
+  /** Get a specific field from collected data */
+  getField<K extends keyof TData>(key: K): TData[K] | undefined;
+  /** Set a specific field in collected data */
+  setField<K extends keyof TData>(key: K, value: TData[K]): Promise<void>;
+  /** Check if a field exists in collected data */
+  hasField<K extends keyof TData>(key: K): boolean;
 }
 
 /**
  * Result returned by a tool
  */
 export interface ToolResult<
-  TResultData = unknown,
-  TContext = unknown,
-  TData = unknown
+  TResultData = any,
+  TContext = any,
+  TData = any
 > {
   /** The result data */
   data?: TResultData;
@@ -50,34 +58,117 @@ export interface ToolResult<
  * Handler function for a tool
  */
 export type ToolHandler<
-  TContext,
-  TData = unknown,
-  TArgs extends unknown[] = unknown[],
-  TResult = unknown
+  TContext = any,
+  TData = any,
+  TResult = any
 > = (
   context: ToolContext<TContext, TData>,
-  ...args: TArgs
+  args?: Record<string, unknown>
 ) =>
-  | Promise<ToolResult<TResult, TContext, TData>>
-  | ToolResult<TResult, TContext, TData>;
+    | Promise<TResult | ToolResult<TResult, TContext, TData>>
+    | TResult
+    | ToolResult<TResult, TContext, TData>;
 
 /**
  * Tool definition - plain object interface
  */
 export interface Tool<
-  TContext = unknown,
-  TData = unknown,
-  TArgs extends unknown[] = unknown[],
-  TResult = unknown
+  TContext = any,
+  TData = any,
+  TResult = any
 > {
   /** Tool identifier */
   id: string;
   /** Tool display name (shown to AI models) */
   name?: string;
   /** Tool handler function */
-  handler: ToolHandler<TContext, TData, TArgs, TResult>;
+  handler: ToolHandler<TContext, TData, TResult>;
   /** Description of what the tool does (for AI discovery) */
   description?: string;
   /** Parameter schema or description */
   parameters?: unknown;
 }
+
+
+
+/**
+ * Tool execution result
+ */
+export interface ToolExecutionResult {
+  success: boolean;
+  data?: unknown;
+  error?: string;
+  contextUpdate?: Record<string, unknown>;
+  dataUpdate?: Record<string, unknown>;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Tool scope enumeration
+ */
+export enum ToolScope {
+  AGENT = 'agent',
+  ROUTE = 'route',
+  STEP = 'step',
+  REGISTERED = 'registered',
+  ALL = 'all'
+}
+
+
+
+/**
+ * Configuration for data enrichment tools
+ */
+export interface DataEnrichmentConfig<TContext, TData, TFields extends keyof TData> {
+  id: string;
+  name?: string;
+  description?: string;
+  fields: TFields[];
+  enricher: (
+    context: TContext,
+    data: Pick<TData, TFields>
+  ) => Promise<Partial<TData>> | Partial<TData>;
+}
+
+/**
+ * Configuration for validation tools
+ */
+export interface ValidationConfig<TContext, TData, TFields extends keyof TData> {
+  id: string;
+  name?: string;
+  description?: string;
+  fields: TFields[];
+  validator: (
+    context: TContext,
+    data: Pick<TData, TFields>
+  ) => Promise<ValidationResult> | ValidationResult;
+}
+
+/**
+ * Configuration for API call tools
+ */
+export interface ApiCallConfig<TContext, TData, TResult> {
+  id: string;
+  name?: string;
+  description?: string;
+  endpoint: string | ((context: TContext, data: Partial<TData>) => string);
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  headers?: Record<string, string> | ((context: TContext) => Record<string, string>);
+  body?: (context: TContext, data: Partial<TData>, args?: Record<string, unknown>) => unknown;
+  transform?: (response: unknown) => TResult;
+}
+
+/**
+ * Configuration for computation tools
+ */
+export interface ComputationConfig<TContext, TData, TResult> {
+  id: string;
+  name?: string;
+  description?: string;
+  inputs: (keyof TData)[];
+  compute: (
+    context: TContext,
+    inputs: Partial<TData>,
+    args?: Record<string, unknown>
+  ) => Promise<TResult> | TResult;
+}

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,