@falai/agent 2.1.1 → 2.2.1

package/src/core/ResponseModal.ts

@@ -363,18 +363,11 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
     }
 
     /**
-     * Get the ToolManager instance from the agent
+     * Get the ToolManager instance from the agent.
      * @private
      */
-    private getToolManager(): ToolManager<TContext, TData> | undefined {
-        // Check if agent has a tool property (ToolManager)
-        if (this.agent && 'tool' in this.agent && this.agent.tool) {
-            return this.agent.tool;
-        }
-
-        // Log warning if ToolManager is not available
-        logger.warn(`[ResponseModal] ToolManager not available on agent - tool execution will use fallback methods`);
-        return undefined;
+    private getToolManager(): ToolManager<TContext, TData> {
+        return this.agent.tool;
     }
 
     /**
@@ -1983,7 +1976,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                     const toolManager = this.getToolManager();
 
                     // Use concurrent execution for the initial batch of tool calls
-                    if (toolManager && typeof toolManager.executeWithConcurrency === 'function') {
+                    {
                         const toolCallRequests: ToolCallRequest[] = toolCalls.map((tc, i) => ({
                             id: `${tc.toolName}-${i}-${Date.now()}`,
                             toolName: tc.toolName,
@@ -2046,14 +2039,6 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                             session = toolResult.session;
                             toolCalls = toolResult.finalToolCalls;
                         }
-                    } else {
-                        // Fallback: no ToolManager or no executeWithConcurrency, use unified tool loop
-                        const toolResult = await this.executeUnifiedToolLoop({
-                            toolCalls, context, session, history, selectedFlow,
-                            responsePrompt, availableTools, responseSchema, signal,
-                        });
-                        session = toolResult.session;
-                        toolCalls = toolResult.finalToolCalls;
                     }
                 }
 
@@ -2150,22 +2135,15 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                     try {
                         // Use ToolManager for unified tool execution
                         const toolManager = this.getToolManager();
-                        let toolResult;
-
-                        if (toolManager) {
-                            toolResult = await toolManager.executeTool({
-                                tool: tool,
-                                context,
-                                updateContext: this.agent.updateContext.bind(this.agent),
-                                updateData: this.agent.updateCollectedData.bind(this.agent),
-                                history: historyEvents, // Use Event[] for tool execution
-                                data: session.data,
-                                toolArguments: toolCall.arguments,
-                            });
-                        } else {
-                            // Fallback: execute tool directly if ToolManager not available
-                            throw new Error(`ToolManager not available for tool execution: ${toolCall.toolName}`);
-                        }
+                        const toolResult = await toolManager.executeTool({
+                            tool: tool,
+                            context,
+                            updateContext: this.agent.updateContext.bind(this.agent),
+                            updateData: this.agent.updateCollectedData.bind(this.agent),
+                            history: historyEvents, // Use Event[] for tool execution
+                            data: session.data,
+                            toolArguments: toolCall.arguments,
+                        });
 
                         // Store the actual tool result data for history
                         toolResultsMap.set(toolCall.toolName, serializeToolResult(toolResult));
@@ -2298,22 +2276,15 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                         try {
                             // Use ToolManager for unified tool execution
                             const toolManager = this.getToolManager();
-                            let toolResult;
-
-                            if (toolManager) {
-                                toolResult = await toolManager.executeTool({
-                                    tool: tool,
-                                    context,
-                                    updateContext: this.agent.updateContext.bind(this.agent),
-                                    updateData: this.agent.updateCollectedData.bind(this.agent),
-                                    history: historyToEvents(updatedHistory), // Convert to Event[] for tool execution
-                                    data: session.data,
-                                    toolArguments: toolCall.arguments,
-                                });
-                            } else {
-                                // Fallback: execute tool directly if ToolManager not available
-                                throw new Error(`ToolManager not available for follow-up tool execution: ${toolCall.toolName}`);
-                            }
+                            const toolResult = await toolManager.executeTool({
+                                tool: tool,
+                                context,
+                                updateContext: this.agent.updateContext.bind(this.agent),
+                                updateData: this.agent.updateCollectedData.bind(this.agent),
+                                history: historyToEvents(updatedHistory), // Convert to Event[] for tool execution
+                                data: session.data,
+                                toolArguments: toolCall.arguments,
+                            });
 
                             // Check if tool execution was successful
                             if (!toolResult.success) {
@@ -2815,41 +2786,20 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
 
 
     /**
-     * Find an available tool by name for the given flow using ToolManager
-     * Delegates to ToolManager for unified tool resolution
+     * Find an available tool by name for the given flow.
+     * Delegates to ToolManager for unified tool resolution.
      * @private
      */
     private findAvailableTool(
         toolName: string,
         flow?: Flow<TContext, TData>
     ): Tool<TContext, TData> | undefined {
-        // Use ToolManager for unified tool resolution
-        const toolManager = this.getToolManager();
-        if (toolManager) {
-            return toolManager.find(toolName, undefined, undefined, flow);
-        }
-
-        // Fallback to legacy resolution if ToolManager not available
-        logger.warn(`[ResponseModal] ToolManager not available, using legacy tool resolution for: ${toolName}`);
-
-        // Check flow-level tools first (if flow provided)
-        if (flow) {
-            const flowTool = flow
-                .getTools()
-                .find((tool: Tool<TContext, TData>) => tool.id === toolName || tool.id === toolName);
-            if (flowTool) return flowTool;
-        }
-
-        // Fall back to agent-level tools
-        const agentTools = this.agent.getTools();
-        return agentTools.find(
-            (tool) => tool.id === toolName || tool.id === toolName
-        );
+        return this.getToolManager().find(toolName, undefined, undefined, flow);
     }
 
     /**
-     * Collect all available tools for the given flow and step context using ToolManager
-     * Delegates to ToolManager for unified tool resolution and deduplication
+     * Collect all available tools for the given flow and step context.
+     * Delegates to ToolManager for unified tool resolution and deduplication.
      * @private
      */
     private collectAvailableTools(
@@ -2861,77 +2811,10 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
         description?: string;
         parameters?: unknown;
     }> {
-        // Use ToolManager for unified tool collection if available
-        const toolManager = this.getToolManager();
-        if (toolManager) {
-            const availableTools = toolManager.getAvailable(undefined, step, flow);
-            return availableTools.map((tool) => ({
-                id: tool.id,
-                name: tool.id || tool.id,
-                description: tool.description,
-                parameters: tool.parameters,
-            }));
-        }
-
-        // Fallback to legacy collection logic if ToolManager not available
-        logger.warn(`[ResponseModal] ToolManager not available, using legacy tool collection`);
-
-        const availableTools = new Map<string, Tool<TContext, TData>>();
-
-        // Add agent-level tools
-        this.agent.getTools().forEach((tool) => {
-            availableTools.set(tool.id, tool);
-        });
-
-        // Add flow-level tools (these take precedence)
-        if (flow) {
-            flow.getTools().forEach((tool: Tool<TContext, TData>) => {
-                availableTools.set(tool.id, tool);
-            });
-        }
-
-        // Filter by step-level allowed tools if specified
-        if (step?.tools) {
-            const allowedToolIds = new Set<string>();
-            const stepTools: Tool<TContext, TData>[] = [];
-
-            for (const toolRef of step.tools) {
-                if (typeof toolRef === "string") {
-                    // Reference to registered tool
-                    allowedToolIds.add(toolRef);
-                } else {
-                    // Inline tool definition
-                    if (toolRef.id) {
-                        allowedToolIds.add(toolRef.id);
-                        stepTools.push(toolRef);
-                    }
-                }
-            }
-
-            // If step specifies tools, only include those
-            if (allowedToolIds.size > 0) {
-                const filteredTools = new Map<string, Tool<TContext, TData>>();
-                for (const toolId of Array.from(allowedToolIds)) {
-                    const tool = availableTools.get(toolId);
-                    if (tool) {
-                        filteredTools.set(toolId, tool);
-                    }
-                }
-                // Add inline tools
-                stepTools.forEach((tool) => {
-                    if (tool.id) {
-                        filteredTools.set(tool.id, tool);
-                    }
-                });
-                availableTools.clear();
-                filteredTools.forEach((tool, id) => availableTools.set(id, tool));
-            }
-        }
-
-        // Convert to the format expected by AI providers
-        return Array.from(availableTools.values()).map((tool) => ({
+        const availableTools = this.getToolManager().getAvailable(undefined, step, flow);
+        return availableTools.map((tool) => ({
             id: tool.id,
-            name: tool.id || tool.id,
+            name: tool.id,
             description: tool.description,
             parameters: tool.parameters,
         }));
@@ -2963,40 +2846,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
 
             if (typeof prepareOrFinalize === "string") {
                 // Tool ID - use ToolManager for unified resolution
-                const toolManager = this.getToolManager();
-                if (toolManager) {
-                    tool = toolManager.find(prepareOrFinalize, undefined, step, flow);
-                } else {
-                    // Fallback to legacy resolution if ToolManager not available
-                    logger.warn(`[ResponseModal] ToolManager not available, using legacy tool resolution for prepare/finalize: ${prepareOrFinalize}`);
-
-                    const availableTools = new Map<string, Tool<TContext, TData>>();
-
-                    // Add agent-level tools
-                    this.agent.getTools().forEach((t) => {
-                        availableTools.set(t.id, t);
-                    });
-
-                    // Add flow-level tools
-                    if (flow) {
-                        flow.getTools().forEach((t: Tool<TContext, TData>) => {
-                            availableTools.set(t.id, t);
-                        });
-                    }
-
-                    // Add step-level tools
-                    if (step?.tools) {
-                        for (const toolRef of step.tools) {
-                            if (typeof toolRef === "string") {
-                                // Keep as is
-                            } else if (typeof toolRef === 'object' && 'id' in toolRef && toolRef.id) {
-                                availableTools.set(toolRef.id, toolRef);
-                            }
-                        }
-                    }
-
-                    tool = availableTools.get(prepareOrFinalize);
-                }
+                tool = this.getToolManager().find(prepareOrFinalize, undefined, step, flow);
             } else {
                 // Tool object - use directly
                 tool = prepareOrFinalize;
@@ -3004,22 +2854,14 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
 
             if (tool) {
                 // Use ToolManager for unified tool execution
-                const toolManager = this.getToolManager();
-                let result;
-
-                if (toolManager) {
-                    result = await toolManager.executeTool({
-                        tool,
-                        context,
-                        updateContext: this.agent.updateContext.bind(this.agent),
-                        updateData: this.agent.updateCollectedData.bind(this.agent),
-                        history: [], // Empty history for prepare/finalize
-                        data,
-                    });
-                } else {
-                    // Fallback: execute tool directly if ToolManager not available
-                    throw new Error(`ToolManager not available for prepare/finalize tool execution: ${typeof prepareOrFinalize === "string" ? prepareOrFinalize : "inline tool"}`);
-                }
+                const result = await this.getToolManager().executeTool({
+                    tool,
+                    context,
+                    updateContext: this.agent.updateContext.bind(this.agent),
+                    updateData: this.agent.updateCollectedData.bind(this.agent),
+                    history: [], // Empty history for prepare/finalize
+                    data,
+                });
 
                 if (!result.success) {
                     logger.error(

package/src/core/Step.ts

@@ -448,7 +448,8 @@ export class Step<TContext = unknown, TData = unknown> {
   /**
    * Evaluate when/if conditions using the v2 split logic.
    * `if` (code predicate) evaluates first (free); `when` (AI) evaluates only when `if` passes.
-   * Both are combined with AND semantics.
+   * `if` predicates use AND semantics. `when` strings use OR semantics.
+   * When both fields are set, the passing `if` gate and AI match are combined with AND.
    */
   async evaluateWhen(
     templateContext: TemplateContext<TContext, TData>

package/src/core/ToolManager.ts

@@ -663,193 +663,7 @@ export class ToolManager<TContext = unknown, TData = unknown> {
   }
 
   /**
-   * Execute a tool by ID with proper error handling and fallback strategies
-   * Consolidates tool execution logic from ToolExecutor and ResponseModal
-   */
-  async execute(
-    toolId: string,
-    args?: Record<string, unknown>,
-    context?: {
-      step?: Step<TContext, TData>;
-      flow?: Flow<TContext, TData>;
-      context?: TContext;
-      data?: Partial<TData>;
-      history?: Event[];
-      updateContext?: (updates: Partial<TContext>) => Promise<void>;
-      updateData?: (updates: Partial<TData>) => Promise<void>;
-      fallbackTools?: string[]; // Alternative tools to try if primary fails
-      retryCount?: number; // Number of retries for transient failures
-    }
-  ): Promise<ToolExecutionResult> {
-    const maxRetries = context?.retryCount || 2;
-    const fallbackTools = context?.fallbackTools || [];
-    let lastError: Error | undefined;
-
-    // Validate input parameters
-    if (!toolId || typeof toolId !== 'string' || toolId.trim() === '') {
-      return {
-        success: false,
-        error: 'Tool ID is required and must be a non-empty string',
-        metadata: { toolId, args }
-      };
-    }
-
-    // Try primary tool with retries
-    for (let attempt = 0; attempt <= maxRetries; attempt++) {
-      try {
-        const tool = this.find(toolId, undefined, context?.step, context?.flow);
-        if (!tool) {
-          // Tool not found - try fallback tools if available
-          if (fallbackTools.length > 0) {
-            logger.warn(`[ToolManager] Primary tool '${toolId}' not found, trying fallback tools: ${fallbackTools.join(', ')}`);
-
-            for (const fallbackId of fallbackTools) {
-              const fallbackResult = await this.execute(fallbackId, args, {
-                ...context,
-                fallbackTools: [], // Prevent infinite recursion
-                retryCount: 0 // Don't retry fallback tools
-              });
-
-              if (fallbackResult.success) {
-                logger.info(`[ToolManager] Fallback tool '${fallbackId}' succeeded for primary tool '${toolId}'`);
-                return {
-                  ...fallbackResult,
-                  metadata: {
-                    ...fallbackResult.metadata,
-                    primaryTool: toolId,
-                    fallbackUsed: fallbackId
-                  }
-                };
-              }
-            }
-          }
-
-          return {
-            success: false,
-            error: `Tool not found: ${toolId}${fallbackTools.length > 0 ? ` (fallback tools also failed: ${fallbackTools.join(', ')})` : ''}`,
-            metadata: { toolId, args, fallbackTools }
-          };
-        }
-
-        // Execute the tool with proper context
-        const result = await this.executeTool({
-          tool,
-          context: context?.context || (await this.agent.getContext()) as TContext,
-          updateContext: context?.updateContext || this.agent.updateContext.bind(this.agent),
-          updateData: context?.updateData || this.agent.updateCollectedData.bind(this.agent),
-          history: context?.history || [],
-          data: context?.data,
-          toolArguments: args,
-        });
-
-        // Success - return result with execution metadata
-        if (result.success) {
-          return {
-            ...result,
-            metadata: {
-              ...result.metadata,
-              toolId,
-              attempt: attempt + 1,
-              maxRetries
-            }
-          };
-        } else {
-          // Tool execution returned failure - don't retry, return immediately
-          return {
-            ...result,
-            metadata: {
-              ...result.metadata,
-              toolId,
-              attempt: attempt + 1,
-              maxRetries
-            }
-          };
-        }
-      } catch (error) {
-        lastError = error instanceof Error ? error : new Error(String(error));
-        const errorMessage = lastError.message;
-
-        // Check if this is a transient error that should be retried
-        const isTransientError = this.isTransientError(lastError);
-
-        if (attempt < maxRetries && isTransientError) {
-          logger.warn(`[ToolManager] Tool execution attempt ${attempt + 1} failed for ${toolId}, retrying: ${errorMessage}`);
-
-          // Exponential backoff for retries
-          const delay = Math.min(1000 * Math.pow(2, attempt), 5000);
-          await new Promise(resolve => setTimeout(resolve, delay));
-          continue;
-        } else {
-          logger.error(`[ToolManager] Tool execution failed for ${toolId} after ${attempt + 1} attempts: ${errorMessage}`);
-          break;
-        }
-      }
-    }
-
-    // All retries failed - try fallback tools
-    if (fallbackTools.length > 0) {
-      logger.warn(`[ToolManager] Primary tool '${toolId}' failed after retries, trying fallback tools: ${fallbackTools.join(', ')}`);
-
-      for (const fallbackId of fallbackTools) {
-        try {
-          const fallbackResult = await this.execute(fallbackId, args, {
-            ...context,
-            fallbackTools: [], // Prevent infinite recursion
-            retryCount: 0 // Don't retry fallback tools
-          });
-
-          if (fallbackResult.success) {
-            logger.info(`[ToolManager] Fallback tool '${fallbackId}' succeeded for failed primary tool '${toolId}'`);
-            return {
-              ...fallbackResult,
-              metadata: {
-                ...fallbackResult.metadata,
-                primaryTool: toolId,
-                primaryError: lastError?.message,
-                fallbackUsed: fallbackId
-              }
-            };
-          }
-        } catch (fallbackError) {
-          logger.warn(`[ToolManager] Fallback tool '${fallbackId}' also failed: ${fallbackError instanceof Error ? fallbackError.message : String(fallbackError)}`);
-        }
-      }
-    }
-
-    // All attempts and fallbacks failed
-    throw new ToolExecutionError(
-      `[ToolExecutionError] Tool "${toolId}" execution failed: all ${maxRetries + 1} attempts exhausted${fallbackTools.length > 0 ? ` and fallback tools [${fallbackTools.join(', ')}] also failed` : ''}. ` +
-      `Check the tool handler for errors or increase maxRetries. Last error: ${lastError?.message || 'Unknown'}.`,
-      toolId,
-      { args, context, attempts: maxRetries + 1, fallbackTools },
-      lastError
-    );
-  }
-
-  /**
-   * Determine if an error is transient and should be retried
-   */
-  private isTransientError(error: Error): boolean {
-    const transientPatterns = [
-      /network/i,
-      /timeout/i,
-      /connection/i,
-      /temporary/i,
-      /rate limit/i,
-      /503/,
-      /502/,
-      /504/,
-      /ECONNRESET/,
-      /ETIMEDOUT/,
-      /ENOTFOUND/
-    ];
-
-    return transientPatterns.some(pattern => pattern.test(error.message));
-  }
-
-  /**
-   * Execute a single tool with context and collected data
-   * Consolidates logic from ToolExecutor class with enhanced error handling
+   * Execute a single tool with context and collected data.
    */
   async executeTool(params: {
     tool: Tool<TContext, TData>;
@@ -1023,57 +837,11 @@ export class ToolManager<TContext = unknown, TData = unknown> {
 
       logger.error(`[ToolManager] Tool execution error for ${tool.id} after ${executionTime}ms:`, error);
 
-      // Re-throw the error so the execute method can handle retries
+      // Re-throw the error so callers can handle it
       throw error;
     }
   }
 
-  /**
-   * Execute multiple tools in sequence
-   * Consolidates logic from ToolExecutor class
-   */
-  async executeTools(params: {
-    tools: Array<Tool<TContext, TData>>;
-    context: TContext;
-    updateContext: (updates: Partial<TContext>) => Promise<void>;
-    updateData: (updates: Partial<TData>) => Promise<void>;
-    history: Event[];
-    data?: Partial<TData>;
-  }): Promise<ToolExecutionResult[]> {
-    const { tools, context, updateContext, updateData, history, data } = params;
-    const results: ToolExecutionResult[] = [];
-
-    for (const tool of tools) {
-      const result = await this.executeTool({
-        tool,
-        context,
-        updateContext,
-        updateData,
-        history,
-        data,
-      });
-      results.push(result);
-
-      // If tool failed, stop execution chain
-      if (!result.success) {
-        logger.error(`[ToolManager] Tool ${tool.id || "unknown"} failed:`, result.error);
-        break;
-      }
-
-      // Apply context updates from tool result
-      if (result.contextUpdate) {
-        await updateContext(result.contextUpdate as Partial<TContext>);
-      }
-
-      // Apply data updates from tool result
-      if (result.dataUpdate) {
-        await updateData(result.dataUpdate as Partial<TData>);
-      }
-    }
-
-    return results;
-  }
-
   /**
    * Execute tool calls with concurrency control using StreamingToolExecutor.
    * Creates a StreamingToolExecutor, resolves tools, queues them, and yields

package/src/index.ts

@@ -57,7 +57,7 @@ export type {
 export { SQLiteAdapter } from "./adapters/SQLiteAdapter";
 export type {
   SqliteDatabase,
-  SqliteStepment,
+  SqliteStatement,
   SQLiteAdapterOptions,
 } from "./adapters/SQLiteAdapter";
 export { MemoryAdapter } from "./adapters/MemoryAdapter";
@@ -77,7 +77,6 @@ export {
   hasProgrammaticConditions
 } from "./utils/condition";
 export {
-  normalizeHistory,
   historyItemToEvent,
   historyToEvents,
   eventToHistoryItem,
@@ -181,5 +180,5 @@ export type {
   ConditionIf,
   ConditionWhen,
 } from "./types";
-export { CompositionMode, EventKind, MessageRole } from "./types";
+export { EventKind, MessageRole } from "./types";
 export { createSession, createSessionId, enterFlow, enterStep, completeCurrentFlow, isFlowCompletedThisSession, mergeCollected } from "./utils";

package/src/types/agent.ts

@@ -12,7 +12,7 @@ import type { StructuredSchema } from "./schema";
 import type { Event } from "./history";
 import type { Template } from "./template";
 import type { ConditionWhen, ConditionIf } from "./flow";
-import type { PromptCacheConfig } from "../core/PromptSectionCache";
+import type { PromptCacheConfig } from "./prompt-cache";
 
 /**
  * Context passed to every lifecycle hook (flow and step).
@@ -73,14 +73,6 @@ export interface AgentCompactionConfig {
   enabled?: boolean;
 }
 
-/**
- * Composition mode determines how the agent processes and structures responses
- */
-export enum CompositionMode {
-  /** Fluid, natural conversation without strict structure */
-  FLUID = "fluid",
-}
-
 /**
  * Context lifecycle hooks for managing step persistence
  */
@@ -275,7 +267,7 @@ export interface Instruction<TContext = unknown, TData = unknown> {
    */
   kind?: 'must' | 'never' | 'should';
   /**
-   * AI-evaluated activation condition. String or array of strings (AND semantics).
+   * AI-evaluated activation condition. String or array of strings (OR semantics).
    * Undefined = always active. Functions are NOT allowed here — use `if`.
    */
   when?: ConditionWhen;
@@ -315,7 +307,8 @@ export interface ScopedInstructions<TContext = unknown, TData = unknown> {
 }
 
 /**
- * Observability record for an instruction that was active and rendered into a turn's prompt.
+ * Observability record for an instruction that was rendered into a turn's prompt.
+ * Textual `when` conditions are included in the prompt for the AI to evaluate.
  * Deterministic — derived from rendering, not from LLM self-report.
  */
 export interface AppliedInstruction {
@@ -337,7 +330,8 @@ export interface AgentResponse<TData = Record<string, unknown>> {
   /** Why execution stopped (for multi-step execution) */
   stoppedReason?: StoppedReason;
   /**
-   * Instructions whose conditions passed and were rendered into this turn's prompt.
+   * Instructions rendered into this turn's prompt after code-evaluated gates passed.
+   * Textual `when` conditions remain in the prompt for the AI to evaluate.
    * Deterministic — derived from rendering, not from LLM self-report.
    */
   appliedInstructions?: AppliedInstruction[];