@falai/agent 0.9.2 → 1.0.1

package/src/types/agent.ts

@@ -4,11 +4,11 @@
 
 import type { AgentStructuredResponse, AiProvider } from "./ai";
 import type { Tool } from "./tool";
-import type { RouteOptions } from "./route";
+import type { RouteOptions, StepRef, StoppedReason } from "./route";
 import type { PersistenceConfig } from "./persistence";
 import type { SessionState } from "./session";
 import type { StructuredSchema } from "./schema";
-import { Template } from "./template";
+import { Template, ConditionTemplate } from "./template";
 
 /**
  * Composition mode determines how the agent processes and structures responses
@@ -106,6 +106,10 @@ export interface AgentOptions<TContext = unknown, TData = unknown> {
   persistence?: PersistenceConfig<TData>;
   /** Knowledge base containing any JSON structure the AI should know */
   knowledgeBase?: Record<string, unknown>;
+  /** Absolute rules the agent must follow across all routes */
+  rules?: Template<TContext, TData>[];
+  /** Absolute prohibitions the agent must never do across all routes */
+  prohibitions?: Template<TContext, TData>[];
   /** Agent-level data schema defining the complete data structure for collection */
   schema?: StructuredSchema;
   /** Initial data to pre-populate when creating the agent */
@@ -131,7 +135,7 @@ export interface Guideline<TContext = unknown, TData = unknown> {
   /** Unique identifier */
   id?: string;
   /** Condition that triggers this guideline (optional for always-active guidelines) */
-  condition?: Template<TContext, TData>;
+  condition?: ConditionTemplate<TContext, TData>;
   /** Action the agent should take when the condition is met */
   action: Template<TContext, TData>;
   /** Whether this guideline is currently enabled */
@@ -157,6 +161,10 @@ export interface AgentResponse<TData = Record<string, unknown>> {
   session?: SessionState<TData>;
   toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
   isRouteComplete?: boolean;
+  /** Steps executed in this response (for multi-step execution) */
+  executedSteps?: StepRef[];
+  /** Why execution stopped (for multi-step execution) */
+  stoppedReason?: StoppedReason;
 }
 
 export interface AgentResponseStreamChunk<TData = Record<string, unknown>> {
@@ -166,6 +174,10 @@ export interface AgentResponseStreamChunk<TData = Record<string, unknown>> {
   session?: SessionState<TData>;
   toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
   isRouteComplete?: boolean;
+  /** Steps executed in this response (for multi-step execution) */
+  executedSteps?: StepRef[];
+  /** Why execution stopped (for multi-step execution) */
+  stoppedReason?: StoppedReason;
   metadata?: {
     model?: string;
     tokensUsed?: number;

package/src/types/index.ts

@@ -105,4 +105,15 @@ export type {
 export * from "./persistence";
 
 // Template types
-export type { Template, TemplateContext } from "./template";
+export type { 
+  Template, 
+  TemplateContext, 
+  ConditionTemplate, 
+  ConditionEvaluationResult 
+} from "./template";
+export { 
+  ConditionEvaluator, 
+  createConditionEvaluator, 
+  extractAIContextStrings, 
+  hasProgrammaticConditions 
+} from "../utils/condition";

package/src/types/route.ts

@@ -4,7 +4,79 @@
 
 import type { Tool } from "./tool";
 import type { StructuredSchema } from "./schema";
-import { Template } from "./template";
+import type { Guideline, Term } from "./agent";
+import { Template, ConditionTemplate } from "./template";
+
+/**
+ * Reason why batch execution stopped
+ * Used to indicate the stopping condition for multi-step execution
+ */
+export type StoppedReason =
+  | 'needs_input'      // Step requires uncollected data
+  | 'end_route'        // Reached END_ROUTE
+  | 'route_complete'   // All Steps processed
+  | 'prepare_error'    // Error in prepare hook
+  | 'llm_error'        // Error during LLM call
+  | 'validation_error' // Error validating collected data
+  | 'finalize_error';  // Error in finalize hook (non-fatal, logged)
+
+/**
+ * Event types for batch execution observability
+ */
+export type BatchExecutionEventType = 
+  | 'batch_start' 
+  | 'step_included' 
+  | 'step_skipped' 
+  | 'batch_stop' 
+  | 'batch_complete';
+
+/**
+ * Event emitted during batch execution for debugging and observability
+ * 
+ * **Validates: Requirements 11.3**
+ */
+export interface BatchExecutionEvent {
+  /** Type of batch execution event */
+  type: BatchExecutionEventType;
+  /** Timestamp when the event occurred */
+  timestamp: Date;
+  /** Event-specific details */
+  details: {
+    /** Step ID related to this event (for step_included, step_skipped) */
+    stepId?: string;
+    /** Reason for the event (e.g., why step was skipped or batch stopped) */
+    reason?: string;
+    /** Current batch size (for batch_start, batch_complete) */
+    batchSize?: number;
+    /** Stopped reason (for batch_stop, batch_complete) */
+    stoppedReason?: StoppedReason;
+    /** Phase timing information (for batch_complete) */
+    timing?: BatchExecutionTiming;
+  };
+}
+
+/**
+ * Timing information for batch execution phases
+ */
+export interface BatchExecutionTiming {
+  /** Total batch execution time in milliseconds */
+  totalMs: number;
+  /** Time spent in batch determination phase */
+  determinationMs?: number;
+  /** Time spent executing prepare hooks */
+  prepareHooksMs?: number;
+  /** Time spent in LLM call */
+  llmCallMs?: number;
+  /** Time spent collecting data */
+  dataCollectionMs?: number;
+  /** Time spent executing finalize hooks */
+  finalizeHooksMs?: number;
+}
+
+/**
+ * Callback type for batch execution event listeners
+ */
+export type BatchExecutionEventListener = (event: BatchExecutionEvent) => void;
 
 /**
  * Reference to a route
@@ -25,9 +97,52 @@ export interface StepRef {
 }
 
 /**
- * Forward declare Guideline and Term for circular dependency
+ * Result of batch determination - which steps can execute together
+ * @template TContext - Type of context data
+ * @template TData - Type of collected data
  */
-import type { Guideline, Term } from "./agent";
+export interface BatchResult<TContext = unknown, TData = unknown> {
+  /** Steps included in this batch */
+  steps: StepOptions<TContext, TData>[];
+  /** Why the batch stopped */
+  stoppedReason: StoppedReason;
+  /** The Step that caused the stop (if applicable) */
+  stoppedAtStep?: StepOptions<TContext, TData>;
+}
+
+/**
+ * Error details for batch execution failures
+ */
+export interface BatchExecutionError {
+  /** Type of error that occurred */
+  type: 'pre_extraction' | 'skipif_evaluation' | 'prepare_hook' | 
+        'llm_call' | 'data_validation' | 'finalize_hook';
+  /** Error message */
+  message: string;
+  /** Step where error occurred (if applicable) */
+  stepId?: string;
+  /** Additional error details */
+  details?: unknown;
+}
+
+/**
+ * Result of executing a batch of steps
+ * @template TData - Type of collected data
+ */
+export interface BatchExecutionResult<TData = unknown> {
+  /** The generated message */
+  message: string;
+  /** Updated session state */
+  session: import('./session').SessionState<TData>;
+  /** Steps that were executed */
+  executedSteps: StepRef[];
+  /** Why execution stopped */
+  stoppedReason: StoppedReason;
+  /** Collected data from the batch */
+  collectedData?: Partial<TData>;
+  /** Any errors that occurred */
+  error?: BatchExecutionError;
+}
 
 /**
  * Route lifecycle hooks for managing route-specific data and behavior
@@ -98,13 +213,15 @@ export interface RouteOptions<TContext = unknown, TData = unknown> {
   /** Optional personality prompt defining the agent's communication style for this route */
   personality?: Template<TContext, TData>;
   /** Conditions that activate this route */
-  conditions?: Template<TContext, TData>[];
+  when?: ConditionTemplate<TContext, TData>;
+  /** Conditions that prevent this route from being considered */
+  skipIf?: ConditionTemplate<TContext, TData>;
   /** Initial guidelines for this route */
-  guidelines?: Guideline<TContext>[];
+  guidelines?: Guideline<TContext, TData>[];
   /** Initial terms for the route's domain glossary */
   terms?: Term<TContext>[];
   /** Tools available in this route */
-  tools?: Tool<TContext, TData>[];
+  tools?: (string | 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 */
@@ -216,12 +333,11 @@ export interface StepOptions<TContext = unknown, TData = unknown> {
    */
   collect?: (keyof TData)[];
   /**
-   * Function to determine if this step should be skipped
-   * If returns true, the step will be bypassed
-   * @param data - Currently collected agent-level data
-   * @returns true if step should be skipped, false otherwise
+   * Condition to determine if this step should be skipped
+   * If evaluates to true, the step will be bypassed
+   * Supports strings (AI context), functions (programmatic), and arrays
    */
-  skipIf?: (data: Partial<TData>) => boolean;
+  skipIf?: ConditionTemplate<TContext, TData>;
   /**
    * Required data fields that must be present before entering this step
    * If any required field is missing, step cannot be entered
@@ -231,8 +347,11 @@ export interface StepOptions<TContext = unknown, TData = unknown> {
   /**
    * Optional condition for this transition
    * Description of when this transition should be taken
+   * Supports strings (AI context), functions (programmatic), and arrays
    */
-  when?: Template<TContext, TData>;
+  when?: ConditionTemplate<TContext, TData>;
+  /** Initial guidelines for this step */
+  guidelines?: Guideline<TContext, TData>[];
 }
 
 /**

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/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;
     },
   });