@falai/agent 0.3.25 → 0.4.0

package/examples/domain-scoping.ts

@@ -2,7 +2,13 @@
  * Domain Scoping Example
  *
  * This example demonstrates how to use domain scoping to restrict which tools
- * are available in different conversation routes for security and clarity.
+ * can EXECUTE in different conversation routes for security and isolation.
+ *
+ * Important: Domains are OPTIONAL. If you never use domains, all tools are
+ * available everywhere. Use domains when you need security and organization.
+ *
+ * Key Concept: The AI never sees tools. Domains control which tools can
+ * execute automatically when triggered by the state machine or guidelines.
  */
 
 import { Agent, createMessageEvent, EventSource } from "../src/index";
@@ -186,19 +192,21 @@ async function demonstrateScoping() {
 // Benefits demonstration
 console.log(`
 🔒 Security Benefits:
-- Customer Support route cannot accidentally call payment.processPayment()
-- Data Collection route cannot access calendar.scheduleEvent()
-- Each route has minimum necessary permissions
+- Customer Support route cannot execute payment.processPayment()
+- Data Collection route cannot execute calendar.scheduleEvent()
+- Each route has minimum necessary tool permissions
+- Prevents prompt injection attacks from calling sensitive tools
 
-⚡ Performance Benefits:
-- AI only sees relevant tools for each route
-- Faster decision making with reduced context
-- Clearer intent and fewer errors
+🎯 Isolation Benefits:
+- Route execution is isolated - tools can't cross boundaries
+- Checkout can't accidentally trigger admin operations
+- Clear separation of concerns by capability
 
-🎯 Clarity Benefits:
+📋 Clarity Benefits:
 - Routes clearly document their capabilities
-- Easy to audit what each route can do
+- Easy to audit what each route can execute
 - Better debugging when tools are called
+- Self-documenting security model
 `);
 
 // Inspect route configurations

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "0.3.25",
+  "version": "0.4.0",
   "description": "Standalone, strongly-typed AI Agent framework with route DSL and AI provider strategy",
   "type": "module",
   "main": "./dist/cjs/index.js",

package/src/core/Agent.ts

@@ -17,6 +17,7 @@ import { DomainRegistry } from "./DomainRegistry";
 import { PromptBuilder } from "./PromptBuilder";
 import { Observation } from "./Observation";
 import { PersistenceManager } from "./PersistenceManager";
+import { PreparationEngine } from "./PreparationEngine";
 
 /**
  * Main Agent class with generic context support
@@ -30,6 +31,7 @@ export class Agent<TContext = unknown> {
   private domainRegistry = new DomainRegistry();
   private context: TContext | undefined;
   private persistenceManager: PersistenceManager | undefined;
+  private preparationEngine: PreparationEngine<TContext>;
 
   /**
    * Dynamic domain property - populated via addDomain
@@ -52,6 +54,9 @@ export class Agent<TContext = unknown> {
     // Initialize context if provided
     this.context = options.context;
 
+    // Initialize preparation engine with AI provider
+    this.preparationEngine = new PreparationEngine<TContext>(options.ai);
+
     // Initialize persistence if configured
     if (options.persistence) {
       this.persistenceManager = new PersistenceManager(options.persistence);
@@ -257,11 +262,36 @@ export class Agent<TContext = unknown> {
     }
 
     // Merge context with override
-    const effectiveContext = {
+    let effectiveContext = {
       ...(currentContext as Record<string, unknown>),
       ...(contextOverride as Record<string, unknown>),
     } as TContext;
 
+    // RUN PREPARATION ITERATIONS
+    // This is where tools execute automatically based on:
+    // 1. Matched guidelines with associated tools
+    // 2. State machine transitions with toolState
+    //
+    // The AI will NEVER see these tools - they execute before message generation
+    const preparationResult = await this.preparationEngine.prepare({
+      history,
+      currentState: params.state,
+      context: effectiveContext,
+      routes: this.routes,
+      guidelines: this.guidelines,
+      maxIterations: this.options.maxEngineIterations || 1,
+    });
+
+    // Update context with results from tool executions
+    effectiveContext = preparationResult.finalContext;
+
+    // Log tool executions for debugging
+    if (preparationResult.toolExecutions.length > 0) {
+      console.log(
+        `[Agent] Preparation complete: ${preparationResult.toolExecutions.length} tools executed in ${preparationResult.iterations.length} iterations`
+      );
+    }
+
     // Build prompt (same as respond method)
     const promptBuilder = new PromptBuilder();
 
@@ -328,11 +358,9 @@ export class Agent<TContext = unknown> {
       );
     }
 
-    // Add domains (tools) information if any domains are registered
-    const allDomains = this.domainRegistry.all();
-    if (Object.keys(allDomains).length > 0) {
-      promptBuilder.addDomains(allDomains);
-    }
+    // NOTE: Domains/tools are NOT added to the prompt.
+    // Tools execute automatically based on state transitions and guideline matching,
+    // NOT based on AI decisions. The AI should never see available tools.
 
     // Add JSON response schema instructions
     promptBuilder.addJsonResponseSchema();
@@ -429,11 +457,36 @@ export class Agent<TContext = unknown> {
     }
 
     // Merge context with override
-    const effectiveContext = {
+    let effectiveContext = {
       ...(currentContext as Record<string, unknown>),
       ...(contextOverride as Record<string, unknown>),
     } as TContext;
 
+    // RUN PREPARATION ITERATIONS
+    // This is where tools execute automatically based on:
+    // 1. Matched guidelines with associated tools
+    // 2. State machine transitions with toolState
+    //
+    // The AI will NEVER see these tools - they execute before message generation
+    const preparationResult = await this.preparationEngine.prepare({
+      history,
+      currentState: params.state,
+      context: effectiveContext,
+      routes: this.routes,
+      guidelines: this.guidelines,
+      maxIterations: this.options.maxEngineIterations || 1,
+    });
+
+    // Update context with results from tool executions
+    effectiveContext = preparationResult.finalContext;
+
+    // Log tool executions for debugging
+    if (preparationResult.toolExecutions.length > 0) {
+      console.log(
+        `[Agent] Preparation complete: ${preparationResult.toolExecutions.length} tools executed in ${preparationResult.iterations.length} iterations`
+      );
+    }
+
     // Build prompt
     const promptBuilder = new PromptBuilder();
 
@@ -500,11 +553,9 @@ export class Agent<TContext = unknown> {
       );
     }
 
-    // Add domains (tools) information if any domains are registered
-    const allDomains = this.domainRegistry.all();
-    if (Object.keys(allDomains).length > 0) {
-      promptBuilder.addDomains(allDomains);
-    }
+    // NOTE: Domains/tools are NOT added to the prompt.
+    // Tools execute automatically based on state transitions and guideline matching,
+    // NOT based on AI decisions. The AI should never see available tools.
 
     // Add JSON response schema instructions
     promptBuilder.addJsonResponseSchema();

package/src/core/ConditionEvaluator.ts

@@ -0,0 +1,381 @@
+/**
+ * ConditionEvaluator - Handles AI-powered condition evaluation
+ *
+ * This class is responsible for:
+ * - Evaluating guideline conditions
+ * - Evaluating transition conditions
+ * - Extracting tool arguments from context and history
+ */
+
+import type { Event, AiProvider, MessageEventData } from "../types/index";
+import { EventKind } from "../types/history";
+import type { Guideline } from "../types/agent";
+import type { ToolRef } from "../types/tool";
+
+/**
+ * Result of guideline condition evaluation
+ */
+export interface GuidelineEvaluationResult {
+  matches: boolean;
+  rationale?: string;
+}
+
+/**
+ * Result of transition condition evaluation
+ */
+export interface TransitionEvaluationResult {
+  shouldFollow: boolean;
+  rationale?: string;
+}
+
+/**
+ * Result of tool argument extraction
+ */
+export interface ArgumentExtractionResult {
+  arguments: unknown[];
+  rationale?: string;
+}
+
+/**
+ * Schema for guideline evaluation response
+ */
+interface GuidelineEvaluationSchema {
+  matches: boolean;
+  rationale: string;
+}
+
+/**
+ * Schema for transition evaluation response
+ */
+interface TransitionEvaluationSchema {
+  shouldFollow: boolean;
+  rationale: string;
+}
+
+/**
+ * Schema for argument extraction response
+ */
+interface ArgumentExtractionSchema {
+  arguments: unknown[];
+  rationale?: string;
+}
+
+/**
+ * ConditionEvaluator - Evaluates conditions using AI
+ */
+export class ConditionEvaluator<TContext = unknown> {
+  constructor(private readonly ai: AiProvider) {}
+
+  /**
+   * Evaluate a guideline condition against context and history
+   */
+  async evaluateGuidelineCondition(
+    guideline: Guideline,
+    context: TContext,
+    history: Event[]
+  ): Promise<GuidelineEvaluationResult> {
+    try {
+      const recentMessages = this.extractRecentMessages(history);
+
+      const prompt = `You are evaluating whether a guideline condition is met.
+
+Guideline Condition: ${guideline.condition}
+Action: ${guideline.action}
+
+Current Context:
+${JSON.stringify(context, null, 2)}
+
+Recent Conversation:
+${recentMessages || "(No recent messages)"}
+
+Evaluate whether the guideline condition is currently met based on the context and conversation.
+
+Your response must be a JSON object with this exact structure:
+{
+  "matches": boolean (true or false),
+  "rationale": string (brief explanation)
+}`;
+
+      const result = await this.ai.generateMessage<
+        TContext,
+        GuidelineEvaluationSchema
+      >({
+        prompt,
+        history,
+        context,
+        parameters: {
+          jsonMode: true,
+          maxOutputTokens: 500,
+        },
+      });
+
+      // Parse structured response
+      if (result.structured) {
+        return {
+          matches: result.structured.matches === true,
+          rationale: result.structured.rationale,
+        };
+      }
+
+      // Fallback parsing
+      return this.parseGuidelineResponse(result.message);
+    } catch (error) {
+      console.error(
+        `[ConditionEvaluator] Failed to evaluate guideline condition: ${guideline.id}`,
+        error
+      );
+      return {
+        matches: false,
+        rationale: "Failed to evaluate condition",
+      };
+    }
+  }
+
+  /**
+   * Evaluate a transition condition
+   */
+  async evaluateTransitionCondition(
+    condition: string,
+    context: TContext,
+    history: Event[]
+  ): Promise<TransitionEvaluationResult> {
+    try {
+      const recentMessages = this.extractRecentMessages(history);
+
+      const prompt = `You are evaluating whether a state transition condition is met.
+
+Transition Condition: ${condition}
+
+Current Context:
+${JSON.stringify(context, null, 2)}
+
+Recent Conversation:
+${recentMessages || "(No recent messages)"}
+
+Evaluate whether this transition should be followed based on the condition, context, and conversation.
+
+Your response must be a JSON object with this exact structure:
+{
+  "shouldFollow": boolean (true or false),
+  "rationale": string (brief explanation)
+}`;
+
+      const result = await this.ai.generateMessage<
+        TContext,
+        TransitionEvaluationSchema
+      >({
+        prompt,
+        history,
+        context,
+        parameters: {
+          jsonMode: true,
+          maxOutputTokens: 300,
+        },
+      });
+
+      // Parse structured response
+      if (result.structured) {
+        return {
+          shouldFollow: result.structured.shouldFollow === true,
+          rationale: result.structured.rationale,
+        };
+      }
+
+      // Fallback parsing
+      return this.parseTransitionResponse(result.message);
+    } catch (error) {
+      console.error(
+        `[ConditionEvaluator] Failed to evaluate transition condition`,
+        error
+      );
+      return {
+        shouldFollow: false,
+        rationale: "Failed to evaluate condition",
+      };
+    }
+  }
+
+  /**
+   * Extract tool arguments from context and history
+   */
+  async extractToolArguments(
+    tool: ToolRef<TContext, unknown[], unknown>,
+    context: TContext,
+    history: Event[]
+  ): Promise<ArgumentExtractionResult> {
+    try {
+      const recentMessages = this.extractRecentMessages(history);
+
+      const prompt = `You are extracting arguments for a tool call.
+
+Tool: ${tool.name}
+Description: ${tool.description || "No description"}
+Parameters: ${JSON.stringify(tool.parameters, null, 2)}
+
+Current Context:
+${JSON.stringify(context, null, 2)}
+
+Recent Conversation:
+${recentMessages || "(No recent messages)"}
+
+Extract the arguments needed to call this tool based on the context and conversation.
+If a parameter is not available, use null or a reasonable default value.
+
+Your response must be a JSON object with this exact structure:
+{
+  "arguments": [arg1, arg2, ...] (array of argument values),
+  "rationale": string (optional explanation)
+}`;
+
+      const result = await this.ai.generateMessage<
+        TContext,
+        ArgumentExtractionSchema
+      >({
+        prompt,
+        history,
+        context,
+        parameters: {
+          jsonMode: true,
+          maxOutputTokens: 500,
+        },
+      });
+
+      // Parse structured response
+      if (result.structured) {
+        if (
+          result.structured.arguments &&
+          Array.isArray(result.structured.arguments)
+        ) {
+          return {
+            arguments: result.structured.arguments,
+            rationale: result.structured.rationale,
+          };
+        }
+      }
+
+      // Fallback: try to parse from message
+      return this.parseArgumentResponse(result.message);
+    } catch (error) {
+      console.error(
+        `[ConditionEvaluator] Failed to extract tool arguments: ${tool.name}`,
+        error
+      );
+      return {
+        arguments: [],
+        rationale: "Failed to extract arguments",
+      };
+    }
+  }
+
+  /**
+   * Simple argument extraction from context (fallback)
+   */
+  simpleArgumentExtraction(
+    tool: ToolRef<TContext, unknown[], unknown>,
+    context: TContext
+  ): unknown[] {
+    const contextObj = context as Record<string, unknown>;
+    const args: unknown[] = [];
+
+    // If parameters is an object with properties, try to match context keys
+    if (
+      tool.parameters &&
+      typeof tool.parameters === "object" &&
+      !Array.isArray(tool.parameters)
+    ) {
+      const params = tool.parameters as Record<string, unknown>;
+
+      // Try to match parameter names with context keys
+      for (const [paramName, paramDef] of Object.entries(params)) {
+        if (contextObj[paramName] !== undefined) {
+          args.push(contextObj[paramName]);
+        } else if (
+          typeof paramDef === "object" &&
+          paramDef !== null &&
+          "default" in paramDef &&
+          typeof (paramDef as { default?: unknown }).default !== "undefined"
+        ) {
+          args.push((paramDef as { default: unknown }).default);
+        }
+      }
+    }
+
+    return args;
+  }
+
+  // Private helper methods
+
+  /**
+   * Extract recent messages from history
+   */
+  private extractRecentMessages(history: Event[], count = 5): string {
+    return history
+      .slice(-count)
+      .map((event) => {
+        if (event.kind === EventKind.MESSAGE) {
+          const data = event.data as MessageEventData;
+          return `${data.participant.display_name}: ${data.message}`;
+        }
+        return null;
+      })
+      .filter((msg): msg is string => msg !== null)
+      .join("\n");
+  }
+
+  /**
+   * Parse guideline evaluation from text response (fallback)
+   */
+  private parseGuidelineResponse(message: string): GuidelineEvaluationResult {
+    const lowerMessage = message.toLowerCase();
+    const matches =
+      lowerMessage.includes("true") || lowerMessage.includes('"matches": true');
+
+    return {
+      matches,
+      rationale: matches ? "Parsed from text response" : "Condition not met",
+    };
+  }
+
+  /**
+   * Parse transition evaluation from text response (fallback)
+   */
+  private parseTransitionResponse(message: string): TransitionEvaluationResult {
+    const lowerMessage = message.toLowerCase();
+    const shouldFollow =
+      lowerMessage.includes("true") ||
+      lowerMessage.includes('"shouldfollow": true');
+
+    return {
+      shouldFollow,
+      rationale: shouldFollow
+        ? "Parsed from text response"
+        : "Condition not met",
+    };
+  }
+
+  /**
+   * Parse argument extraction from text response (fallback)
+   */
+  private parseArgumentResponse(message: string): ArgumentExtractionResult {
+    try {
+      // Try to extract JSON from the message
+      const jsonMatch = message.match(/\{[\s\S]*\}/);
+      if (jsonMatch) {
+        const parsed = JSON.parse(jsonMatch[0]) as ArgumentExtractionSchema;
+        if (parsed.arguments && Array.isArray(parsed.arguments)) {
+          return {
+            arguments: parsed.arguments,
+            rationale: parsed.rationale,
+          };
+        }
+      }
+    } catch {
+      // Ignore parse errors
+    }
+
+    return {
+      arguments: [],
+      rationale: "Failed to parse arguments from response",
+    };
+  }
+}