@falai/agent 0.8.1 → 0.9.0-alpha-2

package/src/types/session.ts

@@ -2,6 +2,8 @@
  * Session step types for tracking conversation progress
  */
 
+import type { History } from "./history";
+
 /**
  * Pending route transition information
  */
@@ -15,44 +17,38 @@ export interface PendingTransition {
 }
 
 /**
- * Session step tracks the current position in the conversation flow
- * and data collected during the route progression
+ * Session state tracks the current position in the conversation flow
+ * and data collected at the agent level across all routes
  */
-export interface SessionState<TData = Record<string, unknown>> {
+export interface SessionState<TData = unknown> {
   /** Unique session identifier (useful for persistence) */
-  id?: string;
+  id: string;
 
   /** Current route the conversation is in */
   currentRoute?: {
     id: string;
     title: string;
-    enteredAt: Date;
+    enteredAt?: Date;
   };
 
   /** Current step within the route */
   currentStep?: {
     id: string;
     description?: string;
-    enteredAt: Date;
+    enteredAt?: Date;
   };
 
   /**
-   * Data collected during the current route
-   * This is a convenience reference to dataByRoute[currentRoute.id]
-   */
-  data?: Partial<TData>;
-
-  /**
-   * Collected data organized by route ID
-   * Preserves data when switching between routes
-   * Format: { "routeId": { ...dataData } }
+   * Agent-level data collected across all routes
+   * This is the single source of truth for all collected data
+   * Routes can access and contribute to this shared data structure
    */
-  dataByRoute?: Record<string, Partial<unknown>>;
+  data: Partial<TData>;
 
   /** History of routes visited in this session */
-  routeHistory: Array<{
+  routeHistory?: Array<{
     routeId: string;
-    enteredAt: Date;
+    enteredAt?: Date;
     exitedAt?: Date;
     completed: boolean;
   }>;
@@ -63,6 +59,12 @@ export interface SessionState<TData = Record<string, unknown>> {
    */
   pendingTransition?: PendingTransition;
 
+  /**
+   * Conversation history managed by the session
+   * Contains the full conversation between user and assistant
+   */
+  history?: History;
+
   /** Session metadata */
   metadata?: {
     createdAt?: Date;
@@ -70,205 +72,3 @@ export interface SessionState<TData = Record<string, unknown>> {
     [key: string]: unknown;
   };
 }
-
-/**
- * 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> {
-  return {
-    id: sessionId,
-    data: {},
-    dataByRoute: {},
-    routeHistory: [],
-    metadata: {
-      ...metadata,
-      createdAt: new Date(),
-      lastUpdatedAt: new Date(),
-    },
-  };
-}
-
-/**
- * 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
-  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] as Partial<TData>) || {};
-
-  // 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 the data field and the dataByRoute map
- */
-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: Record<string, unknown>;
-} {
-  return {
-    currentRoute: session.currentRoute?.id,
-    currentStep: session.currentStep?.id,
-    collectedData: {
-      data: session.data,
-      dataByRoute: session.dataByRoute, // Include per-route data
-      routeHistory: session.routeHistory,
-      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?: Record<string, unknown>;
-  }
-): SessionState<TData> {
-  const collectedData = data.collectedData || {};
-
-  return {
-    id: sessionId,
-    currentRoute: data.currentRoute
-      ? {
-          id: data.currentRoute,
-          title:
-            (collectedData.currentRouteTitle as string) || data.currentRoute,
-          enteredAt: new Date(),
-        }
-      : undefined,
-    currentStep: data.currentStep
-      ? {
-          id: data.currentStep,
-          description:
-            (collectedData.currentStepDescription as string) || undefined,
-          enteredAt: new Date(),
-        }
-      : undefined,
-    data: (collectedData.data as Partial<TData>) || {},
-    dataByRoute:
-      (collectedData.dataByRoute as Record<string, Partial<unknown>>) || {}, // Restore per-route data
-    routeHistory:
-      (collectedData.routeHistory as SessionState<TData>["routeHistory"]) || [],
-    metadata: (collectedData.metadata as SessionState<TData>["metadata"]) || {},
-  };
-}

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

@@ -12,11 +12,13 @@ export interface ToolContext<TContext = unknown, TData = unknown> {
   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;
   /** Interaction history */
   history: Event[];
-  /** Data collected so far in the current route */
+  /** Complete agent-level data collected so far */
   data?: Partial<TData>;
   /** Additional metadata */
   metadata?: Record<string, unknown>;
@@ -31,11 +33,15 @@ export interface ToolResult<
   TData = unknown
 > {
   /** The result data */
-  data: TResultData;
+  data?: TResultData;
   /** 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>;
+  /** Optional agent-level data update to be merged with collected data */
+  dataUpdate?: Partial<TData>;
+  /** Success indicator */
+  success?: boolean;
+  /** Error message if operation failed */
+  error?: string;
   /** Optional metadata about the execution */
   meta?: Record<string, unknown>;
 }
@@ -45,9 +51,9 @@ export interface ToolResult<
  */
 export type ToolHandler<
   TContext,
-  TArgs extends unknown[],
-  TResult,
-  TData = unknown
+  TData = unknown,
+  TArgs extends unknown[] = unknown[],
+  TResult = unknown
 > = (
   context: ToolContext<TContext, TData>,
   ...args: TArgs
@@ -56,24 +62,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,
-  TData = unknown
+export interface Tool<
+  TContext = unknown,
+  TData = unknown,
+  TArgs extends unknown[] = unknown[],
+  TResult = 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 */
+  handler: ToolHandler<TContext, TData, TArgs, TResult>;
+  /** 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";