@falai/agent 0.3.25 → 0.4.0

package/src/core/PreparationEngine.ts

@@ -0,0 +1,500 @@
+/**
+ * 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 class PreparationEngine<TContext = unknown> {
+  private readonly conditionEvaluator?: ConditionEvaluator<TContext>;
+
+  constructor(ai?: AiProvider) {
+    if (ai) {
+      this.conditionEvaluator = new ConditionEvaluator<TContext>(ai);
+    }
+  }
+
+  /**
+   * 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
+    for (const match of matchedGuidelines) {
+      if (match.guideline.tools && match.guideline.tools.length > 0) {
+        for (const tool of match.guideline.tools) {
+          const toolResult = await this.executeTool(
+            tool as ToolRef<TContext, unknown[], unknown>,
+            params.context,
+            params.history
+          );
+          if (toolResult) {
+            executedTools.push(toolResult);
+
+            // Update context from tool result if tool provided context updates
+            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 matches: GuidelineMatch[] = [];
+
+    for (const guideline of guidelines) {
+      // Skip disabled guidelines
+      if (guideline.enabled === false) {
+        continue;
+      }
+
+      // If guideline has no condition, it's always matched
+      if (!guideline.condition) {
+        matches.push({
+          guideline,
+          rationale: "Guideline has no condition - always active",
+        });
+        continue;
+      }
+
+      // Evaluate condition using AI if evaluator is available
+      if (!this.conditionEvaluator) {
+        // No AI available, match all enabled guidelines with conditions
+        matches.push({
+          guideline,
+          rationale: "AI not available - defaulting to match",
+        });
+        continue;
+      }
+
+      const evaluation =
+        await this.conditionEvaluator.evaluateGuidelineCondition(
+          guideline,
+          context,
+          history
+        );
+
+      if (evaluation.matches) {
+        matches.push({
+          guideline,
+          rationale: evaluation.rationale || "Condition evaluated as true",
+        });
+      }
+    }
+
+    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;
+    }
+  }
+}

package/src/core/PromptBuilder.ts

@@ -449,7 +449,7 @@ When you detect any of these situations, consider which route would be most appr
               ? `\n  Triggered when: ${route.conditions.join(" OR ")}`
               : "";
           const desc = route.description ? `\n  ${route.description}` : "";
-          
+
           let domainInfo = "";
           if (route.domains !== undefined) {
             if (route.domains.length === 0) {
@@ -461,17 +461,23 @@ When you detect any of these situations, consider which route would be most appr
 
           let rulesInfo = "";
           if (route.rules && route.rules.length > 0) {
-            const rulesList = route.rules.map((r, idx) => `${idx + 1}. ${r}`).join("; ");
+            const rulesList = route.rules
+              .map((r, idx) => `${idx + 1}. ${r}`)
+              .join("; ");
             rulesInfo = `\n  RULES: ${rulesList}`;
           }
 
           let prohibitionsInfo = "";
           if (route.prohibitions && route.prohibitions.length > 0) {
-            const prohibitionsList = route.prohibitions.map((p, idx) => `${idx + 1}. ${p}`).join("; ");
+            const prohibitionsList = route.prohibitions
+              .map((p, idx) => `${idx + 1}. ${p}`)
+              .join("; ");
             prohibitionsInfo = `\n  PROHIBITIONS: ${prohibitionsList}`;
           }
 
-          return `${i + 1}) ${route.title}${desc}${conditions}${domainInfo}${rulesInfo}${prohibitionsInfo}`;
+          return `${i + 1}) ${
+            route.title
+          }${desc}${conditions}${domainInfo}${rulesInfo}${prohibitionsInfo}`;
         })
         .join("\n\n");
 
@@ -497,9 +503,7 @@ IMPORTANT:
   /**
    * Add domains (tools) information
    */
-  addDomains(
-    domains: Record<string, Record<string, unknown>>
-  ): this {
+  addDomains(domains: Record<string, Record<string, unknown>>): this {
     const domainNames = Object.keys(domains);
     if (domainNames.length > 0) {
       const domainsString = domainNames
@@ -526,21 +530,18 @@ When calling tools, use the format: domain.toolName (e.g., "payment.processPayme
     return this;
   }
 
-
   /**
    * Add JSON response schema instructions
+   *
+   * NOTE: toolCalls are NOT included. Tools execute automatically based on
+   * state transitions and guideline matching, NOT based on AI decisions.
    */
   addJsonResponseSchema(): this {
     const schema = {
       message: "The actual message to send to the user",
       route: "The title of the route you chose (or null if no specific route)",
-      state: "The current state within the route (or null if not in a route)",
-      toolCalls: [
-        {
-          toolName: "Name of the tool to call",
-          arguments: "Object with tool arguments",
-        },
-      ],
+      state:
+        "The current state within the chosen route (or null if not in a route)",
       reasoning: "Optional: Your internal reasoning for this response",
     };
 
@@ -556,7 +557,6 @@ Instructions:
 - "message": The actual message to send to the user (required)
 - "route": If you chose a specific conversation route, provide its exact title. If not in a route, use null.
 - "state": The current state within the chosen route. If not in a route or at initial state, use null.
-- "toolCalls": If you need to call any tools, provide an array of tool calls. If no tools needed, use an empty array or omit.
 - "reasoning": Optional field for your internal thinking process.
 
 Your entire response must be valid JSON. Do not include any text before or after the JSON object.`,

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
    */