@falai/agent 0.9.0 → 1.0.0

package/src/types/template.ts

@@ -1,5 +1,5 @@
 import type { SessionState } from "./session";
-import type { Event } from "./history";
+import type { Event, MessageRole } from "./history";
 
 /**
  * Context object passed to template functions for dynamic rendering.
@@ -24,7 +24,46 @@ export interface TemplateContext<TContext = unknown, TData = unknown> {
    * The data collected in the current route.
    * A convenience alias for `session.data`.
    */
-  data?: Partial<TData>;
+  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;
+  };
 }
 
 /**
@@ -34,3 +73,32 @@ export interface TemplateContext<TContext = unknown, TData = unknown> {
 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

@@ -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/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/index.ts

@@ -28,6 +28,7 @@ export {
   renderTemplate,
   renderTemplateObject,
   formatKnowledgeBase,
+  createTemplateContext,
 } from "./template";
 
 // Cloning utilities
@@ -55,3 +56,14 @@ export { LoggerLevel, logger } from "./logger";
 // Retry utilities
 export type { RetryOptions } from "./retry";
 export { retry, withTimeoutAndRetry } from "./retry";
+
+// Condition utilities
+export {
+  ConditionEvaluator,
+  createConditionEvaluator,
+  extractAIContextStrings,
+  hasProgrammaticConditions,
+} from "./condition";
+
+// JSON utilities
+export { parseJSONResponse, tryParseJSONResponse } from "./json";

package/src/utils/json.ts

@@ -0,0 +1,46 @@
+/**
+ * JSON parsing utilities
+ */
+
+/**
+ * Clean and parse JSON response that might be wrapped in markdown code blocks
+ * Handles cases like:
+ * - ```json\n{...}\n```
+ * - ```\n{...}\n```
+ * - Plain JSON: {...}
+ */
+export function parseJSONResponse(text: string): unknown {
+  if (!text || typeof text !== 'string') {
+    throw new Error('Invalid JSON response: empty or non-string input');
+  }
+
+  // Trim whitespace
+  let cleaned = text.trim();
+
+  // Remove markdown code block markers
+  // Match: ```json or ``` at start, and ``` at end
+  const codeBlockRegex = /^```(?:json)?\s*\n?([\s\S]*?)\n?```$/;
+  const match = cleaned.match(codeBlockRegex);
+  
+  if (match) {
+    cleaned = match[1].trim();
+  }
+
+  // Try to parse the cleaned JSON
+  try {
+    return JSON.parse(cleaned);
+  } catch (error) {
+    throw new Error(`Failed to parse JSON response: ${error instanceof Error ? error.message : String(error)}\nContent: ${cleaned.substring(0, 200)}...`);
+  }
+}
+
+/**
+ * Safely parse JSON response, returning undefined on failure
+ */
+export function tryParseJSONResponse(text: string): unknown {
+  try {
+    return parseJSONResponse(text);
+  } catch {
+    return undefined;
+  }
+}

package/src/utils/retry.ts

@@ -1,6 +1,7 @@
 /**
  * Retry utility with exponential backoff
  */
+import {logger} from './logger'
 
 export interface RetryOptions<T> {
   operation: () => Promise<T>;
@@ -78,18 +79,18 @@ export const withTimeoutAndRetry = async <T>(
     delay: (attempt: number) => Math.min(1000 * Math.pow(2, attempt), 5000),
     onRetry: (attempt: number, error: unknown) => {
       const message = error instanceof Error ? error.message : String(error);
-      console.error(
+      logger.error(
         `[${operationName}] Failed attempt ${attempt + 1}:`,
         message
       );
       const delay = Math.min(1000 * Math.pow(2, attempt), 5000);
-      console.log(`[${operationName}] Retrying in ${delay}ms...`);
-      console.log(
+      logger.debug(`[${operationName}] Retrying in ${delay}ms...`);
+      logger.debug(
         `[${operationName}] Attempt ${attempt + 2}/${maxRetries + 1}`
       );
     },
     onFailure: (_error: unknown) => {
-      console.error(`[${operationName}] All ${maxRetries + 1} attempts failed`);
+      logger.error(`[${operationName}] All ${maxRetries + 1} attempts failed`);
       return true;
     },
   });

package/src/utils/template.ts

@@ -1,4 +1,6 @@
 import type { Template, TemplateContext } from "../types";
+import type { Event, MessageEventData } from "../types/history";
+import { MessageRole, EventKind } from "../types/history";
 
 /**
  * Renders a template, which can be a string or a function, using the provided context.
@@ -204,6 +206,113 @@ export function renderTemplateObject(
   return obj;
 }
 
+/**
+ * Creates helper functions for working with history and context in templates.
+ * These helpers make it easier to access message content and perform common operations.
+ *
+ * @param history - The event history array
+ * @returns Object containing helper functions
+ */
+export function createTemplateHelpers(history?: Event[]) {
+  const 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 {
+      if (!history || history.length === 0) return undefined;
+
+      // Search backwards through history for the most recent message
+      for (let i = history.length - 1; i >= 0; i--) {
+        const event = history[i];
+        if (event.kind === EventKind.MESSAGE) {
+          // If no role specified, return the first message found
+          if (!role || event.source === role) {
+            const messageData = event.data as MessageEventData;
+            return messageData.message;
+          }
+        }
+      }
+      return undefined;
+    },
+
+    /**
+     * Get the last user message from history.
+     * @returns The user message content or undefined if not found
+     */
+    getLastUserMessage(): string | undefined {
+      return helpers.getLastMessage(MessageRole.USER);
+    },
+
+    /**
+     * Get the last assistant message from history.
+     * @returns The assistant message content or undefined if not found
+     */
+    getLastAssistantMessage(): string | undefined {
+      return helpers.getLastMessage(MessageRole.ASSISTANT);
+    },
+
+    /**
+     * 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[] {
+      if (!history || history.length === 0) return [];
+
+      const messages: string[] = [];
+      for (const event of history) {
+        if (event.kind === EventKind.MESSAGE) {
+          if (!role || event.source === role) {
+            const messageData = event.data as MessageEventData;
+            messages.push(messageData.message);
+          }
+        }
+      }
+      return messages;
+    },
+
+    /**
+     * 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 = false): boolean {
+      const lastMessage = helpers.getLastMessage();
+      if (!lastMessage) return false;
+
+      const searchText = caseSensitive ? lastMessage : lastMessage.toLowerCase();
+      const keywordArray = Array.isArray(keywords) ? keywords : [keywords];
+      
+      return keywordArray.some(keyword => {
+        const searchKeyword = caseSensitive ? keyword : keyword.toLowerCase();
+        return searchText.includes(searchKeyword);
+      });
+    },
+  };
+
+  return helpers;
+}
+
+/**
+ * Creates a complete TemplateContext with helpers included.
+ * This is a convenience function for creating template contexts with all the helper methods.
+ *
+ * @param params - The base template context parameters
+ * @returns Complete TemplateContext with helpers
+ */
+export function createTemplateContext<TContext = unknown, TData = unknown>(
+  params: Omit<Partial<TemplateContext<TContext, TData>>, 'helpers'>
+): TemplateContext<TContext, TData> {
+  return {
+    ...params,
+    data: params.data || {},
+    helpers: createTemplateHelpers(params.history),
+  };
+}
+
 /**
  * Formats a JSON structure into readable markdown format.
  * Handles nested objects, arrays, and primitive values.

package/dist/cjs/src/adapters/MemoryAdapter.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"MemoryAdapter.d.ts","sourceRoot":"","sources":["../../../../src/adapters/MemoryAdapter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAEV,WAAW,EACX,iBAAiB,EACjB,kBAAkB,EAClB,WAAW,EACX,iBAAiB,EAGlB,MAAM,UAAU,CAAC;AAGlB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,aAAa,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CACxD,YAAW,kBAAkB,CAAC,KAAK,CAAC;IAEpC,SAAgB,iBAAiB,EAAE,iBAAiB,CAAC,KAAK,CAAC,CAAC;IAC5D,SAAgB,iBAAiB,EAAE,iBAAiB,CAAC;IACrD,OAAO,CAAC,QAAQ,CAAkC;IAClD,OAAO,CAAC,QAAQ,CAA2B;;IAU3C;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,WAAW,IAAI;QACb,QAAQ,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/B,QAAQ,EAAE,WAAW,EAAE,CAAC;KACzB;CAMF"}