@falai/agent 0.8.0 → 0.9.0-alpha-1

package/src/types/template.ts

@@ -0,0 +1,36 @@
+import type { SessionState } from "./session";
+import type { Event } from "./history";
+
+/**
+ * Context object passed to template functions for dynamic rendering.
+ */
+export interface TemplateContext<TContext = unknown, TData = unknown> {
+  /**
+   * The agent's static or dynamically-provided context.
+   */
+  context?: TContext;
+
+  /**
+   * The current session state, including collected data.
+   */
+  session?: SessionState<TData>;
+
+  /**
+   * The recent interaction history.
+   */
+  history?: Event[];
+
+  /**
+   * The data collected in the current route.
+   * A convenience alias for `session.data`.
+   */
+  data?: Partial<TData>;
+}
+
+/**
+ * Represents a string that can be either a literal or a function
+ * that dynamically generates a string from context.
+ */
+export type Template<TContext = unknown, TData = unknown> =
+  | string
+  | ((params: TemplateContext<TContext, TData>) => string | Promise<string>);

package/src/types/tool.ts

@@ -35,7 +35,7 @@ export interface ToolResult<
   /** Optional context update to be merged with current context */
   contextUpdate?: Partial<TContext>;
   /** Optional collected data update to be merged with session step */
-  collectedUpdate?: Partial<TData>;
+  dataUpdate?: Partial<TData>;
   /** Optional metadata about the execution */
   meta?: Record<string, unknown>;
 }
@@ -56,24 +56,22 @@ export type ToolHandler<
   | ToolResult<TResult, TContext, TData>;
 
 /**
- * Reference to a defined tool
+ * Tool definition - plain object interface
  */
-export interface ToolRef<
-  TContext,
-  TArgs extends unknown[],
-  TResult,
+export interface Tool<
+  TContext = unknown,
+  TArgs extends unknown[] = unknown[],
+  TResult = unknown,
   TData = unknown
 > {
   /** Tool identifier */
   id: string;
-  /** Tool name */
-  name: string;
+  /** Tool display name (shown to AI models) */
+  name?: string;
   /** Tool handler function */
   handler: ToolHandler<TContext, TArgs, TResult, TData>;
-  /** Description of what the tool does */
+  /** Description of what the tool does (for AI discovery) */
   description?: string;
   /** Parameter schema or description */
   parameters?: unknown;
-  /** Domain this tool belongs to (set when added via agent.addDomain) */
-  domainName?: string;
 }

package/src/utils/clone.ts

@@ -0,0 +1,36 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Deep clone utility to avoid adding large dependencies like lodash.
+ * Handles objects, arrays, dates, and primitives.
+ * @param obj - The object to clone
+ * @returns A deep copy of the object
+ */
+export function cloneDeep<T>(obj: T): T {
+  if (obj === null || typeof obj !== "object") {
+    return obj;
+  }
+
+  if (obj instanceof Date) {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+    return new Date(obj.getTime()) as any;
+  }
+
+  if (Array.isArray(obj)) {
+    const arrCopy = [] as any[];
+    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;
+  }
+
+  const objCopy = {} as { [key: string]: any };
+  for (const key in obj) {
+    if (Object.prototype.hasOwnProperty.call(obj, key)) {
+      objCopy[key] = cloneDeep((obj as Record<string, unknown>)[key]);
+    }
+  }
+
+  return objCopy as T;
+}

package/src/utils/event.ts

@@ -1,4 +1,4 @@
-import { type Event, EventKind } from "../types/history";
+import { type Event, EventKind } from "../types";
 /**
  * Helper to extract last message from history
  */

package/src/utils/history.ts

@@ -0,0 +1,143 @@
+/**
+ * History normalization utilities
+ * Convert simplified history format to internal Event format
+ */
+
+import type { Event, MessageEventData } from "../types";
+import { EventKind, MessageRole } from "../types";
+import type { History, HistoryItem } from "../types/history";
+
+/**
+ * Convert a simplified history item to an internal Event
+ */
+function convertHistoryItemToEvent(item: HistoryItem): Event {
+  const timestamp = new Date().toISOString();
+
+  switch (item.role) {
+    case "user": {
+      return {
+        kind: EventKind.MESSAGE,
+        source: MessageRole.USER,
+        timestamp,
+        data: {
+          participant: {
+            display_name: item.name || "User",
+          },
+          message: item.content,
+        },
+      };
+    }
+    case "assistant": {
+      // Handle assistant message with optional tool calls
+      const event: Event = {
+        kind: EventKind.MESSAGE,
+        source: MessageRole.ASSISTANT,
+        timestamp,
+        data: {
+          participant: {
+            display_name: "Assistant",
+          },
+          message: item.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;
+      }
+
+      return event;
+    }
+    case "tool": {
+      return {
+        kind: EventKind.TOOL,
+        source: MessageRole.AGENT,
+        timestamp,
+        data: {
+          tool_calls: [
+            {
+              tool_id: item.tool_call_id,
+              arguments: {}, // Tool results don't have arguments
+              result: {
+                data: item.content,
+              },
+            },
+          ],
+        },
+      };
+    }
+    case "system": {
+      return {
+        kind: EventKind.MESSAGE,
+        source: MessageRole.SYSTEM,
+        timestamp,
+        data: {
+          participant: {
+            display_name: "System",
+          },
+          message: item.content,
+        },
+      };
+    }
+    default:
+      // This should never happen due to TypeScript, but fallback just in case
+      return {
+        kind: EventKind.MESSAGE,
+        source: MessageRole.SYSTEM,
+        timestamp,
+        data: {
+          participant: {
+            display_name: "Unknown",
+          },
+          message: "Unknown message type",
+        },
+      };
+  }
+}
+
+/**
+ * Normalize a simplified history array to internal Event array
+ */
+export function normalizeHistory(history: History): Event[] {
+  return history.map(convertHistoryItemToEvent);
+}
+
+/**
+ * Helper function to create a user message
+ */
+export function userMessage(content: string, name?: string): HistoryItem {
+  return { role: "user", content, name };
+}
+
+/**
+ * Helper function to create an assistant message
+ */
+export function assistantMessage(
+  content: string | null,
+  toolCalls?: Array<{
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+  }>
+): HistoryItem {
+  return { role: "assistant", content, tool_calls: toolCalls };
+}
+
+/**
+ * Helper function to create a tool message
+ */
+export function toolMessage(
+  toolCallId: string,
+  name: string,
+  content: unknown
+): HistoryItem {
+  return { role: "tool", tool_call_id: toolCallId, name, content };
+}
+
+/**
+ * Helper function to create a system message
+ */
+export function systemMessage(content: string): HistoryItem {
+  return { role: "system", content };
+}

package/src/utils/index.ts

@@ -0,0 +1,53 @@
+/**
+ * Utility functions and helpers
+ */
+
+// ID generation
+export {
+  generateRouteId,
+  generateStepId,
+  generateToolId,
+  generateInlineToolId,
+} from "./id";
+
+// Session management
+export {
+  createSession,
+  createSessionId,
+  enterRoute,
+  enterStep,
+  mergeCollected,
+  sessionStepToData,
+  sessionDataToStep,
+} from "./session";
+
+// Template rendering
+export {
+  render,
+  renderMany,
+  renderTemplate,
+  renderTemplateObject,
+  formatKnowledgeBase,
+} from "./template";
+
+// Cloning utilities
+export { cloneDeep } from "./clone";
+
+// Event utilities
+export { getLastMessageFromHistory } from "./event";
+
+// History utilities
+export {
+  normalizeHistory,
+  userMessage,
+  assistantMessage,
+  toolMessage,
+  systemMessage,
+} from "./history";
+
+// Logging
+export { LoggerLevel, logger } from "./logger";
+
+// Retry utilities
+export type { RetryOptions } from "./retry";
+export { retry, withTimeoutAndRetry } from "./retry";

package/src/utils/session.ts

@@ -0,0 +1,229 @@
+import { cloneDeep } from "./clone";
+import type { SessionState } from "../types/session";
+import type { CollectedStateData } from "../types/persistence";
+
+/**
+ * Helper to create a new session
+ * @param sessionId - Optional session ID (e.g., from database)
+ * @param metadata - Optional metadata to attach
+ */
+export function createSession<TData = Record<string, unknown>>(
+  sessionId?: string,
+  metadata?: SessionState<TData>["metadata"]
+): SessionState<TData> {
+  const id =
+    sessionId || `session_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+
+  return {
+    id,
+    data: {} as Partial<TData>,
+    dataByRoute: {},
+    routeHistory: [],
+    metadata: {
+      ...metadata,
+      createdAt: new Date(),
+      lastUpdatedAt: new Date(),
+    },
+  };
+}
+
+/**
+ * Helper to create a new session ID
+ */
+export function createSessionId(): string {
+  return `session_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+}
+/**
+ * Clones a session to prevent mutation
+ */
+export function cloneSession<TData>(
+  session: SessionState<TData>
+): SessionState<TData> {
+  return cloneDeep(session);
+}
+
+/**
+ * Helper to update session with new route
+ * Preserves collected data per route in dataByRoute map
+ */
+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) {
+    const lastRouteIndex = routeHistory.findIndex(
+      (r) => r.routeId === session.currentRoute?.id && !r.exitedAt
+    );
+    if (lastRouteIndex >= 0) {
+      routeHistory[lastRouteIndex].exitedAt = new Date();
+    }
+  }
+
+  // Load collected data for new route (if resuming) or start fresh
+  const newCollected = dataByRoute[routeId] || {};
+
+  // Enter new route
+  const now = new Date();
+  return {
+    ...session,
+    currentRoute: {
+      id: routeId,
+      title: routeTitle,
+      enteredAt: now,
+    },
+    currentStep: undefined,
+    data: newCollected, // Load route's data or start fresh
+    dataByRoute,
+    routeHistory: [
+      ...routeHistory,
+      {
+        routeId,
+        enteredAt: now,
+        completed: false,
+      },
+    ],
+    metadata: {
+      ...session.metadata,
+      lastUpdatedAt: now,
+    },
+  };
+}
+
+/**
+ * Helper to update session with new step
+ */
+export function enterStep<TData = Record<string, unknown>>(
+  session: SessionState<TData>,
+  stepId: string,
+  stepDescription?: string
+): SessionState<TData> {
+  return {
+    ...session,
+    currentStep: {
+      id: stepId,
+      description: stepDescription,
+      enteredAt: new Date(),
+    },
+    metadata: {
+      ...session.metadata,
+      lastUpdatedAt: new Date(),
+    },
+  };
+}
+
+/**
+ * Helper to merge collected data into session
+ * Updates both data and dataByRoute for current route
+ */
+export function mergeCollected<TData = Record<string, unknown>>(
+  session: SessionState<TData>,
+  data: Partial<unknown>
+): SessionState<TData> {
+  const newCollected = {
+    ...session.data,
+    ...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,
+    metadata: {
+      ...session.metadata,
+      lastUpdatedAt: new Date(),
+    },
+  };
+}
+
+/**
+ * Helper to convert SessionState to persistence-friendly format
+ * Used when saving to database
+ */
+export function sessionStepToData<TData = Record<string, unknown>>(
+  session: SessionState<TData>
+): {
+  currentRoute?: string;
+  currentStep?: string;
+  collectedData: CollectedStateData<TData>;
+} {
+  return {
+    currentRoute: session.currentRoute?.id,
+    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,
+      currentStepDescription: session.currentStep?.description,
+      metadata: session.metadata,
+    },
+  };
+}
+
+/**
+ * Helper to convert database SessionData back to SessionState
+ * Used when loading from database
+ * @param sessionId - The database session ID
+ * @param data - The database session data
+ */
+export function sessionDataToStep<TData = Record<string, unknown>>(
+  sessionId: string,
+  data: {
+    currentRoute?: string;
+    currentStep?: string;
+    collectedData?: CollectedStateData<TData>;
+  }
+): SessionState<TData> {
+  const collectedData: CollectedStateData<TData> = data.collectedData || {
+    data: {},
+    dataByRoute: {},
+    routeHistory: [],
+    history: [],
+    metadata: {},
+    currentRouteTitle: undefined,
+    currentStepDescription: undefined,
+  };
+
+  return {
+    id: sessionId,
+    currentRoute: data.currentRoute
+      ? {
+          id: data.currentRoute,
+          title: collectedData.currentRouteTitle || data.currentRoute,
+          enteredAt: new Date(),
+        }
+      : undefined,
+    currentStep: data.currentStep
+      ? {
+          id: data.currentStep,
+          description: collectedData.currentStepDescription || undefined,
+          enteredAt: new Date(),
+        }
+      : undefined,
+    data: collectedData.data || {},
+    dataByRoute: collectedData.dataByRoute || {},
+    routeHistory: collectedData.routeHistory || [],
+    history: collectedData.history || [],
+    metadata: collectedData.metadata || {},
+  };
+}