@falai/agent 0.1.0-alpha2

package/src/types/template.ts

@@ -0,0 +1,104 @@
+import type { SessionState } from "./session";
+import type { Event, MessageRole } 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>;
+
+  /**
+   * Helper methods for working with history and context.
+   */
+  helpers: {
+    /**
+     * Get the last message from history, optionally filtered by role.
+     * @param role - Optional role to filter by (user, assistant, etc.)
+     * @returns The message content or undefined if not found
+     */
+    getLastMessage(role?: MessageRole): string | undefined;
+
+    /**
+     * Get the last user message from history.
+     * @returns The user message content or undefined if not found
+     */
+    getLastUserMessage(): string | undefined;
+
+    /**
+     * Get the last assistant message from history.
+     * @returns The assistant message content or undefined if not found
+     */
+    getLastAssistantMessage(): string | undefined;
+
+    /**
+     * Get all messages from history, optionally filtered by role.
+     * @param role - Optional role to filter by
+     * @returns Array of message contents
+     */
+    getMessages(role?: MessageRole): string[];
+
+    /**
+     * Check if the last message contains any of the given keywords.
+     * @param keywords - Keywords to search for
+     * @param caseSensitive - Whether to perform case-sensitive search (default: false)
+     * @returns True if any keyword is found
+     */
+    lastMessageContains(keywords: string | string[], caseSensitive?: boolean): boolean;
+  };
+}
+
+/**
+ * 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>);
+
+/**
+ * Represents a condition that can be used for routing decisions.
+ * Supports strings (AI context only), boolean functions (programmatic evaluation),
+ * and arrays of either for complex condition logic.
+ */
+export type ConditionTemplate<TContext = unknown, TData = unknown> =
+  | string  // AI context only - not evaluated programmatically
+  | ((params: TemplateContext<TContext, TData>) => boolean | Promise<boolean>) // Programmatic evaluation
+  | ConditionTemplate<TContext, TData>[]; // Array of either
+
+/**
+ * Result of condition evaluation containing both programmatic results
+ * and AI context strings.
+ */
+export interface ConditionEvaluationResult {
+  /** Result of function evaluations only */
+  programmaticResult: boolean;
+  /** String values for AI context */
+  aiContextStrings: string[];
+  /** Whether any functions were evaluated */
+  hasProgrammaticConditions: boolean;
+  /** Detailed evaluation information for debugging */
+  evaluationDetails?: {
+    condition: string;
+    result?: boolean; // Only present for functions
+    type: 'string' | 'function' | 'array';
+  }[];
+}

package/src/types/tool.ts

@@ -0,0 +1,174 @@
+/* eslint @typescript-eslint/no-explicit-any: "off"*/
+/**
+ * Tool system type definitions
+ */
+
+import type { Event, StepRef, ValidationResult } from "./index";
+
+/**
+ * Context provided to tool handlers
+ */
+export interface ToolContext<TContext = any, TData = any> {
+  /** The agent's context data */
+  context: TContext;
+  /** Complete agent-level data collected so far */
+  data: Partial<TData>;
+  /** Interaction history */
+  history: Event[];
+  /** 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 = any,
+  TContext = any,
+  TData = any
+> {
+  /** The result data */
+  data?: TResultData;
+  /** Optional context update to be merged with current context */
+  contextUpdate?: Partial<TContext>;
+  /** 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>;
+}
+
+/**
+ * Handler function for a tool
+ */
+export type ToolHandler<
+  TContext = any,
+  TData = any,
+  TResult = any
+> = (
+  context: ToolContext<TContext, TData>,
+  args?: Record<string, unknown>
+) =>
+    | Promise<TResult | ToolResult<TResult, TContext, TData>>
+    | TResult
+    | ToolResult<TResult, TContext, TData>;
+
+/**
+ * Tool definition - plain object interface
+ */
+export interface Tool<
+  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, 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

@@ -0,0 +1,34 @@
+
+/**
+ * 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) {
+    return new Date(obj.getTime()) as T;
+  }
+
+  if (Array.isArray(obj)) {
+    const arrCopy: unknown[] = [];
+    for (let i = 0; i < obj.length; i++) {
+       
+      arrCopy[i] = cloneDeep(obj[i]);
+    }
+    return arrCopy as T;
+  }
+
+  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]);
+    }
+  }
+
+  return objCopy as T;
+}

package/src/utils/condition.ts

@@ -0,0 +1,190 @@
+import type { TemplateContext, ConditionTemplate, ConditionEvaluationResult } from "../types/template";
+import { createTemplateContext } from "./template";
+import { logger } from './logger'
+
+/**
+ * Utility class for evaluating ConditionTemplate instances.
+ * Handles mixed string/function conditions and separates programmatic
+ * evaluation from AI context collection.
+ */
+export class ConditionEvaluator<TContext = unknown, TData = unknown> {
+  constructor(private templateContext: TemplateContext<TContext, TData>) {}
+
+  /**
+   * Evaluates a condition template and returns both programmatic results
+   * and AI context strings.
+   * 
+   * @param condition The condition to evaluate
+   * @param logic Logic to apply for arrays ('AND' for when conditions, 'OR' for skipIf)
+   * @returns Evaluation result with programmatic result and AI context
+   */
+  async evaluateCondition(
+    condition: ConditionTemplate<TContext, TData>,
+    logic: 'AND' | 'OR' = 'AND'
+  ): Promise<ConditionEvaluationResult> {
+    const result: ConditionEvaluationResult = {
+      programmaticResult: logic === 'AND' ? true : false,
+      aiContextStrings: [],
+      hasProgrammaticConditions: false,
+      evaluationDetails: []
+    };
+
+    if (!condition) {
+      return result;
+    }
+
+    // Handle array conditions
+    if (Array.isArray(condition)) {
+      return this.evaluateArrayCondition(condition, logic);
+    }
+
+    // Handle string conditions (AI context only)
+    if (typeof condition === 'string') {
+      result.aiContextStrings.push(condition);
+      result.evaluationDetails?.push({
+        condition: condition,
+        type: 'string'
+      });
+      // For string conditions, programmatic result depends on logic:
+      // AND logic: true (doesn't affect result)
+      // OR logic: false (doesn't trigger skip)
+      result.programmaticResult = logic === 'AND' ? true : false;
+      return result;
+    }
+
+    // Handle function conditions (programmatic evaluation)
+    if (typeof condition === 'function') {
+      result.hasProgrammaticConditions = true;
+      try {
+        const functionResult = await condition(this.templateContext);
+        result.programmaticResult = Boolean(functionResult);
+        result.evaluationDetails?.push({
+          condition: condition.toString(),
+          result: result.programmaticResult,
+          type: 'function'
+        });
+      } catch (error) {
+        // Log error and default to false for safety
+        logger.warn('Condition function evaluation failed:', error);
+        result.programmaticResult = false;
+        result.evaluationDetails?.push({
+          condition: condition.toString(),
+          result: false,
+          type: 'function'
+        });
+      }
+      return result;
+    }
+
+    // Fallback for unexpected types
+    logger.warn('Unexpected condition type:', typeof condition);
+    return result;
+  }
+
+  /**
+   * Evaluates an array of conditions with the specified logic.
+   */
+  private async evaluateArrayCondition(
+    conditions: ConditionTemplate<TContext, TData>[],
+    logic: 'AND' | 'OR'
+  ): Promise<ConditionEvaluationResult> {
+    const result: ConditionEvaluationResult = {
+      programmaticResult: logic === 'AND' ? true : false,
+      aiContextStrings: [],
+      hasProgrammaticConditions: false,
+      evaluationDetails: [{
+        condition: `Array[${conditions.length}]`,
+        type: 'array'
+      }]
+    };
+
+    const functionResults: boolean[] = [];
+
+    for (const condition of conditions) {
+      const conditionResult = await this.evaluateCondition(condition, logic);
+      
+      // Collect AI context strings
+      result.aiContextStrings.push(...conditionResult.aiContextStrings);
+      
+      // Track if we have programmatic conditions
+      if (conditionResult.hasProgrammaticConditions) {
+        result.hasProgrammaticConditions = true;
+        functionResults.push(conditionResult.programmaticResult);
+      }
+
+      // Merge evaluation details
+      if (conditionResult.evaluationDetails) {
+        result.evaluationDetails?.push(...conditionResult.evaluationDetails);
+      }
+    }
+
+    // Apply logic to function results only
+    if (functionResults.length > 0) {
+      if (logic === 'AND') {
+        result.programmaticResult = functionResults.every(r => r);
+      } else { // OR
+        result.programmaticResult = functionResults.some(r => r);
+      }
+    } else {
+      // No programmatic conditions, result depends on logic:
+      // AND: true (no functions to fail)
+      // OR: false (no functions to succeed)
+      result.programmaticResult = logic === 'AND' ? true : false;
+    }
+
+    return result;
+  }
+}
+
+/**
+ * Utility function to create a ConditionEvaluator instance.
+ * Ensures the template context has helpers included.
+ */
+export function createConditionEvaluator<TContext = unknown, TData = unknown>(
+  templateContext: Omit<Partial<TemplateContext<TContext, TData>>, 'helpers'>
+): ConditionEvaluator<TContext, TData> {
+  const contextWithHelpers = createTemplateContext(templateContext);
+  return new ConditionEvaluator(contextWithHelpers);
+}
+
+/**
+ * Utility function to extract AI context strings from a condition without evaluation.
+ * Useful for collecting context strings for prompt generation.
+ */
+export function extractAIContextStrings<TContext = unknown, TData = unknown>(
+  condition: ConditionTemplate<TContext, TData>
+): string[] {
+  const contextStrings: string[] = [];
+
+  if (!condition) {
+    return contextStrings;
+  }
+
+  if (Array.isArray(condition)) {
+    for (const subCondition of condition) {
+      contextStrings.push(...extractAIContextStrings(subCondition));
+    }
+  } else if (typeof condition === 'string') {
+    contextStrings.push(condition);
+  }
+  // Functions don't contribute to AI context
+
+  return contextStrings;
+}
+
+/**
+ * Utility function to check if a condition has any programmatic components.
+ */
+export function hasProgrammaticConditions<TContext = unknown, TData = unknown>(
+  condition: ConditionTemplate<TContext, TData>
+): boolean {
+  if (!condition) {
+    return false;
+  }
+
+  if (Array.isArray(condition)) {
+    return condition.some(subCondition => hasProgrammaticConditions(subCondition));
+  }
+
+  return typeof condition === 'function';
+}

package/src/utils/event.ts

@@ -0,0 +1,16 @@
+import { type Event, EventKind } from "../types";
+/**
+ * Helper to extract last message from history
+ */
+export function getLastMessageFromHistory(history: Event[]): string {
+  for (let i = history.length - 1; i >= 0; i--) {
+    const event = history[i];
+    if (event.kind === EventKind.MESSAGE) {
+      if (!event.data || !("message" in event.data)) {
+        continue;
+      }
+      return event.data.message;
+    }
+  }
+  return "";
+}