@falai/agent 0.3.30 → 0.4.1

package/src/core/PreparationEngine.ts

@@ -0,0 +1,561 @@
+/**
+ * PreparationEngine - Handles the preparation iteration loop
+ *
+ * This engine implements the core Parlant/Emcie architecture:
+ * 1. Before generating a message, run preparation iterations
+ * 2. Each iteration:
+ *    - Match guidelines against current context
+ *    - Walk the state machine and execute tool transitions
+ *    - Execute tools when conditions are met
+ *    - Update context from tool results
+ *    - Check if prepared to respond
+ * 3. After preparation, the AI generates the final message
+ *
+ * The AI NEVER sees tools - tools execute automatically based on:
+ * - State machine transitions ({ toolState: tool })
+ * - Guideline matching with associated tools
+ */
+
+import type { Event, StateRef, AiProvider } from "../types/index";
+import type { Guideline, GuidelineMatch } from "../types/agent";
+import type { ToolRef } from "../types/tool";
+import type { Route } from "./Route";
+import { State } from "./State";
+import { ConditionEvaluator } from "./ConditionEvaluator";
+
+/**
+ * Tool execution result
+ */
+export interface ToolExecutionResult {
+  toolName: string;
+  arguments: Record<string, unknown>;
+  result: unknown;
+  success: boolean;
+  error?: string;
+}
+
+/**
+ * Preparation iteration state
+ */
+export interface IterationState {
+  iterationNumber: number;
+  matchedGuidelines: GuidelineMatch[];
+  executedTools: ToolExecutionResult[];
+  contextUpdates: Record<string, unknown>;
+  preparedToRespond: boolean;
+}
+
+/**
+ * Preparation context
+ */
+export interface PreparationContext<TContext = unknown> {
+  history: Event[];
+  currentState?: StateRef;
+  context: TContext;
+  routes: Route<TContext>[];
+  guidelines: Guideline[];
+  maxIterations: number;
+}
+
+/**
+ * Preparation result
+ */
+export interface PreparationResult<TContext = unknown> {
+  iterations: IterationState[];
+  finalContext: TContext;
+  toolExecutions: ToolExecutionResult[];
+  preparedToRespond: boolean;
+}
+
+/**
+ * PreparationEngine - Executes the preparation iteration loop
+ */
+export interface PreparationEngineOptions {
+  maxParallelLlmCalls?: number;
+  maxParallelTools?: number;
+}
+
+export class PreparationEngine<TContext = unknown> {
+  private readonly conditionEvaluator?: ConditionEvaluator<TContext>;
+  private readonly maxParallelLlmCalls: number;
+  private readonly maxParallelTools: number;
+
+  /**
+   * Run a list of async jobs with a concurrency limit, preserving order of results.
+   */
+  private async processWithConcurrency<T>(
+    tasks: Array<() => Promise<T>>,
+    runner: (task: () => Promise<T>) => Promise<T>,
+    concurrency: number
+  ): Promise<T[]> {
+    const results: T[] = new Array<T>(tasks.length);
+    let nextIndex = 0;
+    const workers: Promise<void>[] = [];
+
+    const runNext = async (): Promise<void> => {
+      const current = nextIndex++;
+      if (current >= tasks.length) {
+        return;
+      }
+      try {
+        results[current] = await runner(tasks[current]);
+      } finally {
+        await runNext();
+      }
+    };
+
+    const workerCount = Math.min(concurrency, tasks.length);
+    for (let i = 0; i < workerCount; i++) {
+      workers.push(runNext());
+    }
+    await Promise.all(workers);
+    return results;
+  }
+
+  constructor(ai?: AiProvider, options?: PreparationEngineOptions) {
+    if (ai) {
+      this.conditionEvaluator = new ConditionEvaluator<TContext>(ai);
+    }
+    this.maxParallelLlmCalls = options?.maxParallelLlmCalls ?? 4;
+    this.maxParallelTools = options?.maxParallelTools ?? 8;
+  }
+
+  /**
+   * Run preparation iterations before message generation
+   *
+   * This is the core engine that executes tools automatically
+   * based on state machine transitions and guideline matching.
+   */
+  async prepare(
+    preparationContext: PreparationContext<TContext>
+  ): Promise<PreparationResult<TContext>> {
+    const iterations: IterationState[] = [];
+    let currentContext = { ...preparationContext.context };
+    const allToolExecutions: ToolExecutionResult[] = [];
+    let preparedToRespond = false;
+
+    // Run preparation iterations
+    for (
+      let i = 0;
+      i < preparationContext.maxIterations && !preparedToRespond;
+      i++
+    ) {
+      const iteration = await this.runIteration({
+        iterationNumber: i + 1,
+        history: preparationContext.history,
+        currentState: preparationContext.currentState,
+        context: currentContext,
+        routes: preparationContext.routes,
+        guidelines: preparationContext.guidelines,
+      });
+
+      iterations.push(iteration);
+      allToolExecutions.push(...iteration.executedTools);
+
+      // Update context from tool results
+      if (Object.keys(iteration.contextUpdates).length > 0) {
+        currentContext = {
+          ...currentContext,
+          ...iteration.contextUpdates,
+        } as TContext;
+      }
+
+      // Check if we're prepared to respond
+      // We're prepared if:
+      // 1. No tools were executed in this iteration (nothing left to do)
+      // 2. OR we've reached max iterations
+      // 3. OR iteration explicitly set preparedToRespond to true
+      if (
+        iteration.executedTools.length === 0 ||
+        i === preparationContext.maxIterations - 1 ||
+        iteration.preparedToRespond
+      ) {
+        preparedToRespond = true;
+      }
+    }
+
+    return {
+      iterations,
+      finalContext: currentContext,
+      toolExecutions: allToolExecutions,
+      preparedToRespond,
+    };
+  }
+
+  /**
+   * Run a single preparation iteration
+   */
+  private async runIteration(params: {
+    iterationNumber: number;
+    history: Event[];
+    currentState?: StateRef;
+    context: TContext;
+    routes: Route<TContext>[];
+    guidelines: Guideline[];
+  }): Promise<IterationState> {
+    const executedTools: ToolExecutionResult[] = [];
+    const contextUpdates: Record<string, unknown> = {};
+    const matchedGuidelines: GuidelineMatch[] = [];
+
+    // Step 1: Match guidelines against current context
+    const matchedResults = await this.matchGuidelines(
+      params.guidelines,
+      params.context,
+      params.history
+    );
+    matchedGuidelines.push(...matchedResults);
+
+    // Step 2: Execute tools from matched guidelines
+    // Guidelines with associated tools should execute those tools
+    const guidelineToolCalls: Array<() => Promise<ToolExecutionResult | null>> =
+      [];
+    for (const match of matchedGuidelines) {
+      if (match.guideline.tools && match.guideline.tools.length > 0) {
+        for (const tool of match.guideline.tools) {
+          const t = tool as ToolRef<TContext, unknown[], unknown>;
+          guidelineToolCalls.push(() =>
+            this.executeTool(t, params.context, params.history)
+          );
+        }
+      }
+    }
+    if (guidelineToolCalls.length > 0) {
+      const results = await this.processWithConcurrency(
+        guidelineToolCalls,
+        (fn) => fn(),
+        this.maxParallelTools
+      );
+      for (const toolResult of results) {
+        if (toolResult) {
+          executedTools.push(toolResult);
+          if (toolResult.result && typeof toolResult.result === "object") {
+            const result = toolResult.result as Record<string, unknown>;
+            if (result.contextUpdate) {
+              Object.assign(contextUpdates, result.contextUpdate);
+            }
+          }
+        }
+      }
+    }
+
+    // Step 3: Walk state machine and execute tool transitions
+    // Find current route and state, then execute any toolState transitions
+    if (params.currentState?.id) {
+      const currentRoute = params.routes.find(
+        (r) => r.id === params.currentState!.routeId
+      );
+
+      if (currentRoute) {
+        const toolResults = await this.executeStateToolTransitions(
+          currentRoute,
+          params.currentState,
+          params.context,
+          params.history
+        );
+        executedTools.push(...toolResults);
+
+        // Update context from state tool results
+        for (const toolResult of toolResults) {
+          if (toolResult.result && typeof toolResult.result === "object") {
+            const result = toolResult.result as Record<string, unknown>;
+            if (result.contextUpdate) {
+              Object.assign(contextUpdates, result.contextUpdate);
+            }
+          }
+        }
+      }
+    }
+
+    return {
+      iterationNumber: params.iterationNumber,
+      matchedGuidelines,
+      executedTools,
+      contextUpdates,
+      preparedToRespond: false, // Will be determined by caller
+    };
+  }
+
+  /**
+   * Match guidelines against current context
+   *
+   * Evaluates guideline conditions against the current context and history
+   * using AI to determine relevance and priority
+   */
+  private async matchGuidelines(
+    guidelines: Guideline[],
+    context: TContext,
+    history: Event[]
+  ): Promise<GuidelineMatch[]> {
+    const alwaysMatches = guidelines.filter(
+      (g) => g.enabled !== false && !g.condition
+    );
+    const conditional = guidelines.filter(
+      (g) => g.enabled !== false && g.condition
+    );
+
+    const matches: GuidelineMatch[] = alwaysMatches.map((guideline) => ({
+      guideline,
+      rationale: "Guideline has no condition - always active",
+    }));
+
+    if (!this.conditionEvaluator) {
+      // No AI available, match all enabled guidelines with conditions
+      for (const guideline of conditional) {
+        matches.push({
+          guideline,
+          rationale: "AI not available - defaulting to match",
+        });
+      }
+      return matches;
+    }
+
+    // Evaluate conditional guidelines with limited parallelism
+    const workers = conditional.map((guideline) => async () => {
+      const evaluation =
+        await this.conditionEvaluator!.evaluateGuidelineCondition(
+          guideline,
+          context,
+          history
+        );
+      if (evaluation.matches) {
+        return {
+          guideline,
+          rationale: evaluation.rationale || "Condition evaluated as true",
+        } as GuidelineMatch;
+      }
+      return null;
+    });
+
+    const evaluated = await this.processWithConcurrency(
+      workers,
+      (w) => w(),
+      this.maxParallelLlmCalls
+    );
+    for (const r of evaluated) {
+      if (r) {
+        matches.push(r);
+      }
+    }
+
+    return matches;
+  }
+
+  /**
+   * Execute a single tool
+   */
+  private async executeTool(
+    tool: ToolRef<TContext, unknown[], unknown>,
+    context: TContext,
+    history: Event[]
+  ): Promise<ToolExecutionResult | null> {
+    try {
+      // Extract arguments from context and history
+      let args: unknown[];
+
+      if (this.conditionEvaluator && tool.parameters) {
+        // Use AI-powered extraction if available
+        const extraction = await this.conditionEvaluator.extractToolArguments(
+          tool,
+          context,
+          history
+        );
+        args = extraction.arguments;
+      } else {
+        // Fallback to simple extraction
+        args = this.conditionEvaluator
+          ? this.conditionEvaluator.simpleArgumentExtraction(tool, context)
+          : [];
+      }
+
+      // Execute the tool handler
+      const result = await tool.handler(
+        {
+          context,
+          history,
+          updateContext: async (_updates: Partial<TContext>) => {
+            // Context updates are handled separately in the preparation loop
+            // This is a no-op placeholder
+          },
+        },
+        ...args
+      );
+
+      return {
+        toolName: tool.name,
+        arguments: { args }, // Wrap array in object for logging
+        result,
+        success: true,
+      };
+    } catch (error) {
+      console.error(
+        `[PreparationEngine] Tool execution failed: ${tool.name}`,
+        error
+      );
+      return {
+        toolName: tool.name,
+        arguments: {},
+        result: null,
+        success: false,
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  /**
+   * Execute tool transitions in the state machine
+   *
+   * Walks through state transitions and executes tools when
+   * reaching a { toolState: tool } transition
+   */
+  private async executeStateToolTransitions(
+    route: Route<TContext>,
+    currentStateRef: StateRef,
+    context: TContext,
+    history: Event[]
+  ): Promise<ToolExecutionResult[]> {
+    const executedTools: ToolExecutionResult[] = [];
+
+    // Get the current state from the route or use initial state
+    let stateToWalk: State<TContext>;
+
+    try {
+      const foundState = route.getState(currentStateRef.id);
+      if (foundState) {
+        stateToWalk = foundState;
+      } else {
+        stateToWalk = route.initialState;
+      }
+    } catch {
+      // If any error occurs, fallback to initial state
+      stateToWalk = route.initialState;
+    }
+
+    // Walk the state machine starting from the determined state
+    const toolResults = await this.walkStateChain(
+      stateToWalk,
+      context,
+      history,
+      new Set() // Track visited states to prevent loops
+    );
+
+    executedTools.push(...toolResults);
+
+    return executedTools;
+  }
+
+  /**
+   * Walk through a chain of states, executing tools along the way
+   */
+  private async walkStateChain(
+    state: State<TContext>,
+    context: TContext,
+    history: Event[],
+    visited: Set<string>
+  ): Promise<ToolExecutionResult[]> {
+    const executedTools: ToolExecutionResult[] = [];
+
+    // Prevent infinite loops
+    if (visited.has(state.id)) {
+      return executedTools;
+    }
+    visited.add(state.id);
+
+    // Get all transitions from this state
+    const transitions = state.getTransitions();
+
+    // Process each transition
+    for (const transition of transitions) {
+      // Check if transition has a condition
+      if (transition.hasCondition()) {
+        // Evaluate condition
+        const shouldFollow = await this.evaluateTransitionCondition(
+          transition,
+          context,
+          history
+        );
+
+        if (!shouldFollow) {
+          continue; // Skip this transition
+        }
+      }
+
+      // Check if this is a toolState transition
+      if (transition.spec.toolState) {
+        // Execute the tool
+        const toolResult = await this.executeTool(
+          transition.spec.toolState,
+          context,
+          history
+        );
+
+        if (toolResult) {
+          executedTools.push(toolResult);
+
+          // Update context with tool results for next transitions
+          if (toolResult.result && typeof toolResult.result === "object") {
+            const result = toolResult.result as Record<string, unknown>;
+            if (result.contextUpdate) {
+              context = {
+                ...context,
+                ...(result.contextUpdate as Partial<TContext>),
+              };
+            }
+          }
+        }
+      }
+
+      // Get the target state and recursively walk it
+      const targetState = transition.getTarget();
+      if (targetState && !visited.has(targetState.id)) {
+        const childResults = await this.walkStateChain(
+          targetState,
+          context,
+          history,
+          visited
+        );
+        executedTools.push(...childResults);
+      }
+    }
+
+    return executedTools;
+  }
+
+  /**
+   * Evaluate a transition condition
+   */
+  private async evaluateTransitionCondition(
+    transition: { condition?: string },
+    context: TContext,
+    history: Event[]
+  ): Promise<boolean> {
+    if (!transition.condition) {
+      return true; // No condition = always follow
+    }
+
+    // If no AI evaluator available, default to true
+    if (!this.conditionEvaluator) {
+      return true;
+    }
+
+    try {
+      const evaluation =
+        await this.conditionEvaluator.evaluateTransitionCondition(
+          transition.condition,
+          context,
+          history
+        );
+
+      return evaluation.shouldFollow;
+    } catch (error) {
+      console.error(
+        `[PreparationEngine] Failed to evaluate transition condition`,
+        error
+      );
+      // On error, default to false (don't follow)
+      return false;
+    }
+  }
+}
+
+// Helper methods (outside class scope are not necessary; keep inside class)
+export type _Internal = unknown;

package/src/core/Route.ts

@@ -132,6 +132,16 @@ export class Route<TContext = unknown> {
     return states;
   }
 
+  /**
+   * Get a specific state by ID
+   * @param stateId - The state ID to find
+   * @returns The state if found, undefined otherwise
+   */
+  getState(stateId: string): State<TContext> | undefined {
+    const states = this.getAllStates();
+    return states.find((state) => state.id === stateId);
+  }
+
   /**
    * Get a description of the route structure for debugging
    */