@falai/agent 0.9.0-alpha-2 → 0.9.2

package/src/core/ResponsePipeline.ts

@@ -22,7 +22,7 @@ import {
 import { Route } from "../core/Route";
 import { Step } from "../core/Step";
 import { RoutingEngine } from "../core/RoutingEngine";
-import { ToolExecutor } from "../core/ToolExecutor";
+import type { ToolManager } from "../core/ToolManager";
 import { END_ROUTE_ID } from "../constants";
 
 export interface ResponsePreparationResult<TContext, TData = unknown> {
@@ -42,8 +42,8 @@ export interface RoutingResult<TContext, TData = unknown> {
 export interface ToolExecutionResult<TData = unknown> {
   session: SessionState<TData>;
   toolCalls:
-    | Array<{ toolName: string; arguments: Record<string, unknown> }>
-    | undefined;
+  | Array<{ toolName: string; arguments: Record<string, unknown> }>
+  | undefined;
 }
 
 export interface DataCollectionResult<TData = unknown> {
@@ -57,8 +57,8 @@ export interface DataCollectionResult<TData = unknown> {
 export class ResponsePipeline<TContext = unknown, TData = unknown> {
   constructor(
     private readonly options: AgentOptions<TContext, TData>,
-    private readonly routes: Route<TContext, TData>[],
-    private readonly tools: Tool<TContext, TData, unknown[], unknown>[],
+    private readonly getRoutes: () => Route<TContext, TData>[],
+    private readonly tools: Tool<TContext, TData>[],
     private readonly routingEngine: RoutingEngine<TContext, TData>,
     private readonly updateContext: (
       updates: Partial<TContext>
@@ -69,8 +69,9 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
     ) => Promise<SessionState<TData>>,
     private readonly updateCollectedData?: (
       updates: Partial<TData>
-    ) => Promise<void>
-  ) {}
+    ) => Promise<void>,
+    private readonly toolManager?: ToolManager<TContext, TData>
+  ) { }
 
   /**
    * Prepare context and session for response generation
@@ -125,9 +126,12 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
     let completedRoutes: Route<TContext, TData>[] = [];
     let targetSession = session;
 
+    // Get routes early since we need them for pending transitions
+    const routes = this.getRoutes();
+
     // Check for pending transition from previous route completion
     if (targetSession.pendingTransition) {
-      const targetRoute = this.routes.find(
+      const targetRoute = routes.find(
         (r) => r.id === targetSession.pendingTransition?.targetRouteId
       );
 
@@ -166,11 +170,11 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
         };
       }
     }
-
+    
     // If no pending transition or transition handled, do normal routing
-    if (this.routes.length > 0 && !selectedRoute) {
+    if (routes.length > 0 && !selectedRoute) {
       const orchestration = await this.routingEngine.decideRouteAndStep({
-        routes: this.routes,
+        routes: routes,
         session: targetSession,
         history,
         agentOptions: this.options,
@@ -281,8 +285,7 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
     }
 
     logger.debug(
-      `[ResponseHandler] Executing ${toolCalls.length} ${
-        isStreaming ? "streaming " : ""
+      `[ResponseHandler] Executing ${toolCalls.length} ${isStreaming ? "streaming " : ""
       }tool calls`
     );
 
@@ -299,15 +302,21 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
         continue;
       }
 
-      const toolExecutor = new ToolExecutor<TContext, TData>();
-      const result = await toolExecutor.executeTool({
-        tool,
-        context,
-        updateContext: this.updateContext,
-        updateData: this.updateCollectedData || (async () => {}),
-        history,
-        data: updatedSession.data,
-      });
+      // Use ToolManager for unified tool execution
+      let result;
+      if (this.toolManager) {
+        result = await this.toolManager.executeTool({
+          tool,
+          context,
+          updateContext: this.updateContext,
+          updateData: this.updateCollectedData || (async () => { }),
+          history,
+          data: updatedSession.data,
+        });
+      } else {
+        // Fallback: execute tool directly if ToolManager not available
+        throw new Error(`ToolManager not available for tool execution: ${toolCall.toolName}`);
+      }
 
       executedToolCalls.push(toolCall);
 
@@ -323,16 +332,14 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
           result.dataUpdate as Partial<TData>
         );
         logger.debug(
-          `[ResponseHandler] ${
-            isStreaming ? "Streaming " : ""
+          `[ResponseHandler] ${isStreaming ? "Streaming " : ""
           }Tool updated collected data:`,
           result.dataUpdate
         );
       }
 
       logger.debug(
-        `[ResponseHandler] Executed ${isStreaming ? "streaming " : ""}tool: ${
-          result.toolName
+        `[ResponseHandler] Executed ${isStreaming ? "streaming " : ""}tool: ${String(tool.id || tool.name || 'unknown')
         } (success: ${result.success})`
       );
     }
@@ -348,8 +355,8 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
    */
   async executeToolLoop(params: {
     initialToolCalls:
-      | Array<{ toolName: string; arguments: Record<string, unknown> }>
-      | undefined;
+    | Array<{ toolName: string; arguments: Record<string, unknown> }>
+    | undefined;
     selectedRoute?: Route<TContext, TData>;
     nextStep: Step<TContext, TData>;
     responsePrompt: string;
@@ -380,8 +387,7 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
     while (hasToolCalls && toolLoopCount < MAX_TOOL_LOOPS) {
       toolLoopCount++;
       logger.debug(
-        `[ResponseHandler] Starting ${
-          isStreaming ? "streaming " : ""
+        `[ResponseHandler] Starting ${isStreaming ? "streaming " : ""
         }tool loop ${toolLoopCount}/${MAX_TOOL_LOOPS}`
       );
 
@@ -430,8 +436,7 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
 
       if (hasToolCalls) {
         logger.debug(
-          `[ResponseHandler] Follow-up call produced ${
-            followUpToolCalls!.length
+          `[ResponseHandler] Follow-up call produced ${followUpToolCalls!.length
           } additional tool calls`
         );
 
@@ -449,8 +454,7 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
         currentToolCalls = followUpToolCalls;
       } else {
         logger.debug(
-          `[ResponseHandler] ${
-            isStreaming ? "Streaming " : ""
+          `[ResponseHandler] ${isStreaming ? "Streaming " : ""
           }Tool loop completed after ${toolLoopCount} iterations`
         );
         // Update final toolCalls from follow-up result if no more tools
@@ -461,8 +465,7 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
 
     if (toolLoopCount >= MAX_TOOL_LOOPS) {
       logger.warn(
-        `[ResponseHandler] ${
-          isStreaming ? "Streaming " : ""
+        `[ResponseHandler] ${isStreaming ? "Streaming " : ""
         }Tool loop limit reached (${MAX_TOOL_LOOPS}), stopping`
       );
     }
@@ -505,7 +508,7 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
       if (this.updateCollectedData) {
         await this.updateCollectedData(collectedData);
       }
-      
+
       // Update session with validated data
       updatedSession = await this.updateData(session, collectedData);
       logger.debug(`[ResponseHandler] Collected data:`, collectedData);
@@ -554,7 +557,7 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
 
     if (transitionConfig) {
       // Find target route by ID or title
-      const targetRoute = this.routes.find(
+      const targetRoute = this.getRoutes().find(
         (r) =>
           r.id === transitionConfig.nextStep ||
           r.title === transitionConfig.nextStep
@@ -602,12 +605,21 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
   }
 
   /**
-   * Find an available tool by name for the given route
+   * Find an available tool by name for the given route using ToolManager
+   * Delegates to ToolManager for unified tool resolution
    */
   private findAvailableTool(
     toolName: string,
     route?: Route<TContext, TData>
-  ): Tool<TContext, TData, unknown[], unknown> | undefined {
+  ): Tool<TContext, TData> | undefined {
+    // Use ToolManager for unified tool resolution if available
+    if (this.toolManager) {
+      return this.toolManager.find(toolName, undefined, undefined, route);
+    }
+
+    // Fallback to legacy resolution if ToolManager not available
+    logger.warn(`[ResponsePipeline] ToolManager not available, using legacy tool resolution for: ${toolName}`);
+
     // Check route-level tools first (if route provided)
     if (route) {
       const routeTool = route
@@ -623,15 +635,29 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
   }
 
   /**
-   * Collect all available tools for the given route and step context
+   * Collect all available tools for the given route and step context using ToolManager
+   * Delegates to ToolManager for unified tool resolution and deduplication
    */
   private collectAvailableTools(
     route?: Route<TContext, TData>,
     step?: Step<TContext, TData>
   ): Array<{ id: string; description?: string; parameters?: unknown }> {
+    // Use ToolManager for unified tool collection if available
+    if (this.toolManager) {
+      const availableTools = this.toolManager.getAvailable(undefined, step, route);
+      return availableTools.map((tool) => ({
+        id: tool.id,
+        description: tool.description,
+        parameters: tool.parameters,
+      }));
+    }
+
+    // Fallback to legacy collection logic if ToolManager not available
+    logger.warn(`[ResponsePipeline] ToolManager not available, using legacy tool collection`);
+
     const availableTools = new Map<
       string,
-      Tool<TContext, TData, unknown[], unknown>
+      Tool<TContext, TData>
     >();
 
     // Add agent-level tools
@@ -649,7 +675,7 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
     // Filter by step-level allowed tools if specified
     if (step?.tools) {
       const allowedToolIds = new Set<string>();
-      const stepTools: Tool<TContext, TData, unknown[], unknown>[] = [];
+      const stepTools: Tool<TContext, TData>[] = [];
 
       for (const toolRef of step.tools) {
         if (typeof toolRef === "string") {
@@ -668,9 +694,9 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
       if (allowedToolIds.size > 0) {
         const filteredTools = new Map<
           string,
-          Tool<TContext, TData, unknown[], unknown>
+          Tool<TContext, TData>
         >();
-        for (const toolId of allowedToolIds) {
+        for (const toolId of Array.from(allowedToolIds)) {
           const tool = availableTools.get(toolId);
           if (tool) {
             filteredTools.set(toolId, tool);
@@ -747,35 +773,35 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
     }>;
   }> {
     const { routes, session, context } = params;
-    
+
     // Evaluate all routes for completion
     const completedRoutes: Route<TContext, TData>[] = [];
     const pendingTransitions: Array<{
       route: Route<TContext, TData>;
       transitionConfig: RouteTransitionConfig<TContext, TData>;
     }> = [];
-    
+
     for (const route of routes) {
       if (route.isComplete(session.data || {})) {
         completedRoutes.push(route);
-        
+
         // Check for onComplete transitions
         const transitionConfig = await route.evaluateOnComplete(
           { data: session.data },
           context
         );
-        
+
         if (transitionConfig) {
           pendingTransitions.push({ route, transitionConfig });
         }
-        
+
         logger.debug(
           `[ResponsePipeline] Route completed: ${route.title} ` +
           `(${Math.round(route.getCompletionProgress(session.data || {}) * 100)}%)`
         );
       }
     }
-    
+
     // Log completion status for all routes
     if (completedRoutes.length > 0) {
       logger.debug(
@@ -783,7 +809,7 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
         `${completedRoutes.length}/${routes.length} routes complete`
       );
     }
-    
+
     return {
       session,
       completedRoutes,
@@ -801,15 +827,15 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
     routes: Route<TContext, TData>[];
   }): Promise<SessionState<TData>> {
     const { session, dataUpdate, routes } = params;
-    
+
     // Update session data
     const updatedSession = await this.updateData(session, dataUpdate);
-    
+
     // Update agent-level data if handler is available
     if (this.updateCollectedData) {
       await this.updateCollectedData(dataUpdate);
     }
-    
+
     // Evaluate route completions after data update
     const completionResults = await this.handleCrossRouteCompletion({
       routes,
@@ -817,14 +843,14 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
       context: this.context!,
       history: [],
     });
-    
+
     // Log any newly completed routes
     if (completionResults.completedRoutes.length > 0) {
       logger.debug(
         `[ResponsePipeline] Data update resulted in ${completionResults.completedRoutes.length} completed routes`
       );
     }
-    
+
     return completionResults.session;
   }
 }

package/src/core/Route.ts

@@ -18,6 +18,7 @@ import type {
 } from "../types";
 
 import { Step } from "./Step";
+import { Agent } from './Agent'
 import { generateRouteId } from "../utils/id";
 import { END_ROUTE } from "../constants";
 
@@ -50,10 +51,13 @@ export class Route<TContext = unknown, TData = unknown> {
   public routingExtrasSchema?: StructuredSchema;
   public guidelines: Guideline<TContext>[] = [];
   public terms: Term<TContext>[] = [];
-  public tools: Tool<TContext, TData, unknown[], unknown>[] = [];
+  public tools: Tool<TContext, TData>[] = [];
   public knowledgeBase: Record<string, unknown> = {};
 
-  constructor(options: RouteOptions<TContext, TData>) {
+  // Reference to parent agent for ToolManager access
+  private parentAgent?: Agent<TContext, TData>; 
+
+  constructor(options: RouteOptions<TContext, TData>, parentAgent?: Agent<TContext, TData>) {
     // Use provided ID or generate a deterministic one from the title
     this.id = options.id || generateRouteId(options.title);
     this.title = options.title;
@@ -64,6 +68,9 @@ export class Route<TContext = unknown, TData = unknown> {
     this.rules = options.rules || [];
     this.prohibitions = options.prohibitions || [];
 
+    // Store reference to parent agent for ToolManager access
+    this.parentAgent = parentAgent;
+
     // Handle initial step logic
     let initialStepOptions = options.initialStep;
     let stepsToChain: StepOptions<TContext, TData>[] = [];
@@ -79,7 +86,7 @@ export class Route<TContext = unknown, TData = unknown> {
       }
     }
 
-    this.initialStep = new Step<TContext, TData>(this.id, initialStepOptions);
+    this.initialStep = new Step<TContext, TData>(this.id, initialStepOptions, this.parentAgent);
 
     // Store endStep spec (will be used when route completes)
     this.endStepSpec = options.endStep || {
@@ -133,14 +140,13 @@ export class Route<TContext = unknown, TData = unknown> {
   private buildSequentialSteps(
     steps: Array<StepOptions<TContext, TData> | typeof END_ROUTE>
   ): void {
-    let currentStep: StepResult<TContext, TData> =
-      this.initialStep.asStepResult();
+    let currentStepResult: StepResult<TContext, TData> = this.initialStep.asStepResult();
 
     for (const step of steps) {
       if (step === END_ROUTE) {
-        currentStep.nextStep({ step: END_ROUTE });
+        currentStepResult.nextStep({ step: END_ROUTE });
       } else {
-        currentStep = currentStep.nextStep(step);
+        currentStepResult = currentStepResult.nextStep(step);
       }
     }
   }
@@ -168,7 +174,12 @@ export class Route<TContext = unknown, TData = unknown> {
   /**
    * Register a tool for this route
    */
-  createTool(tool: Tool<TContext, TData, unknown[], unknown>): this {
+  createTool(tool: Tool<TContext, TData>): this {
+    // Validate tool before adding
+    if (!tool || !tool.id || !tool.handler) {
+      throw new Error(`Invalid tool: must have id and handler properties`);
+    }
+    
     this.tools.push(tool);
     return this;
   }
@@ -176,11 +187,28 @@ export class Route<TContext = unknown, TData = unknown> {
   /**
    * Register multiple tools for this route
    */
-  registerTools(tools: Tool<TContext, TData, unknown[], unknown>[]): this {
+  registerTools(tools: Tool<TContext, TData>[]): this {
     tools.forEach((tool) => this.createTool(tool));
     return this;
   }
 
+  /**
+   * Add a tool to this route using the ToolManager API
+   * Creates and adds the tool to route scope in one operation
+   */
+  addTool(
+    tool: Tool<TContext, TData>
+  ): this {
+    if (this.parentAgent && this.parentAgent.tool) {
+      // Use ToolManager to add to route scope - no casting needed with unified interface
+      this.parentAgent.tool.addToRoute(this, tool);
+    } else {
+      // Fallback: add tool directly to route tools
+      this.createTool(tool);
+    }
+    return this;
+  }
+
   /**
    * Get all guidelines for this route
    */
@@ -198,7 +226,7 @@ export class Route<TContext = unknown, TData = unknown> {
   /**
    * Get all tools for this route
    */
-  getTools(): Tool<TContext, TData, unknown[], unknown>[] {
+  getTools(): Tool<TContext, TData>[] {
     return [...this.tools];
   }
 
@@ -311,8 +339,7 @@ export class Route<TContext = unknown, TData = unknown> {
       const transitions = step.getTransitions();
       for (const transition of transitions) {
         lines.push(
-          `    -> ${transition.id}${
-            transition.description ? `: ${transition.description}` : ""
+          `    -> ${transition.id}${transition.description ? `: ${transition.description}` : ""
           }`
         );
       }

package/src/core/RoutingEngine.ts

@@ -70,6 +70,29 @@ export interface BuildRoutingPromptParams<TContext = unknown, TData = unknown> {
 export class RoutingEngine<TContext = unknown, TData = unknown> {
   constructor(private readonly options?: RoutingEngineOptions) { }
 
+  /**
+   * Enter a route if not already in it, merging initial data
+   * @private
+   */
+  private enterRouteIfNeeded(
+    session: SessionState<TData>,
+    route: Route<TContext, TData>
+  ): SessionState<TData> {
+    if (!session.currentRoute || session.currentRoute.id !== route.id) {
+      let updatedSession = enterRoute(session, route.id, route.title);
+      if (route.initialData) {
+        updatedSession = mergeCollected(updatedSession, route.initialData);
+        logger.debug(
+          `[RoutingEngine] Merged initial data for route ${route.title}:`,
+          route.initialData
+        );
+      }
+      logger.debug(`[RoutingEngine] Entered route: ${route.title}`);
+      return updatedSession;
+    }
+    return session;
+  }
+
   /**
    * Optimized decision for single-route scenarios
    * Skips route scoring and only does step selection
@@ -94,26 +117,13 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
     const { route, session, history, agentOptions, provider, context, signal } =
       params;
 
-    let updatedSession = session;
     const selectedRoute = route;
 
-    // Check if this single route is complete
-    const completedRoutes = route.isComplete(session.data || {}) ? [route] : [];
+    // Enter route if not already in it (this may merge initial data)
+    const updatedSession = this.enterRouteIfNeeded(session, route);
 
-    // Enter route if not already in it
-    if (!session.currentRoute || session.currentRoute.id !== route.id) {
-      updatedSession = enterRoute(session, route.id, route.title);
-      if (route.initialData) {
-        updatedSession = mergeCollected(updatedSession, route.initialData);
-        logger.debug(
-          `[RoutingEngine] Single-route: Merged initial data:`,
-          route.initialData
-        );
-      }
-      logger.debug(
-        `[RoutingEngine] Single-route: Entered route: ${route.title}`
-      );
-    }
+    // Check if this single route is complete (use updated session data)
+    const completedRoutes = route.isComplete(updatedSession.data || {}) ? [route] : [];
 
     // Get candidate steps
     const currentStep = updatedSession.currentStep
@@ -130,9 +140,11 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
       return { selectedRoute, session: updatedSession };
     }
 
-    // If only one candidate, check if route is complete
+    // If only one candidate, no need for AI selection
     if (candidates.length === 1) {
-      const isRouteComplete = candidates[0].isRouteComplete;
+      const candidate = candidates[0];
+      const isRouteComplete = candidate.isRouteComplete;
+      
       if (isRouteComplete) {
         logger.debug(
           `[RoutingEngine] Single-route: Route complete - all data collected, END_ROUTE reached`
@@ -147,11 +159,11 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
         };
       } else {
         logger.debug(
-          `[RoutingEngine] Single-route: Only one valid step: ${candidates[0].step.id}`
+          `[RoutingEngine] Single-route: Only one valid step: ${candidate.step.id}`
         );
         return {
           selectedRoute,
-          selectedStep: candidates[0].step,
+          selectedStep: candidate.step,
           session: updatedSession,
           isRouteComplete: false,
           completedRoutes,
@@ -159,6 +171,18 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
       }
     }
 
+    // No candidates means route is likely complete or has no valid next steps
+    if (candidates.length === 0) {
+      logger.debug(`[RoutingEngine] Single-route: No valid steps found, route may be complete`);
+      return {
+        selectedRoute,
+        selectedStep: undefined,
+        session: updatedSession,
+        isRouteComplete: true, // Assume complete if no valid steps
+        completedRoutes,
+      };
+    }
+
     // Multiple candidates - use AI to select best step
     const lastUserMessage = getLastMessageFromHistory(history);
     const stepPrompt = await this.buildStepSelectionPrompt({
@@ -573,27 +597,7 @@ export class RoutingEngine<TContext = unknown, TData = unknown> {
 
       if (selectedRoute) {
         logger.debug(`[RoutingEngine] Selected route: ${selectedRoute.title}`);
-        if (
-          !session.currentRoute ||
-          session.currentRoute.id !== selectedRoute.id
-        ) {
-          updatedSession = enterRoute(
-            session,
-            selectedRoute.id,
-            selectedRoute.title
-          );
-          if (selectedRoute.initialData) {
-            updatedSession = mergeCollected(
-              updatedSession,
-              selectedRoute.initialData
-            );
-            logger.debug(
-              `[RoutingEngine] Merged initial data:`,
-              selectedRoute.initialData
-            );
-          }
-          logger.debug(`[RoutingEngine] Entered route: ${selectedRoute.title}`);
-        }
+        updatedSession = this.enterRouteIfNeeded(updatedSession, selectedRoute);
       }
     }