@falai/agent 0.9.0 → 0.9.2

package/examples/tools/data-enrichment-tools.ts

@@ -1,19 +1,22 @@
 /**
- * Example: Modifying Collected data with Tools and Hooks
+ * Example: Modifying Collected data with Tools and Hooks using ToolManager
  *
  * This demonstrates:
  * 1. Schema-first data extraction with JSON Schema
- * 2. Tools that modify collected data (validation, enrichment)
+ * 2. Simplified tools that modify collected data (validation, enrichment)
  * 3. Lifecycle hooks for data validation and business logic
  * 4. Data-driven step flows with code-based logic (skipIf, requires)
  * 5. Three-phase pipeline: PREPARATION → ROUTING → RESPONSE
+ * 6. NEW: ToolManager pattern helpers for common data operations
  */
 
 import {
   Agent,
   END_ROUTE,
   OpenAIProvider,
-  type Tool,
+  Tool,
+  ToolContext,
+  ValidationError,
 } from "../../src";
 
 // ==============================================================================
@@ -44,60 +47,49 @@ interface FlightData {
 // TOOLS: Data Enrichment (PREPARATION Phase)
 // ==============================================================================
 
-// Tool 1: Convert city names to airport codes
-const enrichDestinationTool: Tool<FlightBookingContext, FlightData, [], void> =
-  {
-    id: "enrich_destination",
-    name: "Destination Code Lookup",
-    description: "Convert city names to IATA airport codes",
-    parameters: {
-      type: "object",
-      properties: {},
-    },
-    handler: ({ data }: { data?: Partial<FlightData> }) => {
-      const destination = (data as Partial<FlightData>)?.destination;
-
-      if (!destination) {
-        return { data: undefined };
-      }
-
-      // Simulate airport code lookup
-      const airportCodes: Record<string, string> = {
-        Paris: "CDG",
-        London: "LHR",
-        "New York": "JFK",
-        Tokyo: "NRT",
-        "Los Angeles": "LAX",
-      };
-
-      const destinationCode = airportCodes[destination];
-
-      console.log(`[Tool] Enriched: ${destination} → ${destinationCode}`);
-
-      return {
-        data: undefined,
-        dataUpdate: {
-          destinationCode,
-        } as Partial<FlightData>,
-      };
-    },
-  };
+// Tool 1: Convert city names to airport codes using ToolManager pattern helper
+const enrichDestinationConfig = {
+  id: "enrich_destination",
+  name: "Destination Code Lookup", 
+  description: "Convert city names to IATA airport codes",
+  fields: ["destination"] as const,
+  enricher: async (context: FlightBookingContext, data: Pick<FlightData, "destination">) => {
+    const destination = data.destination;
+
+    if (!destination) {
+      return {};
+    }
+
+    // Simulate airport code lookup
+    const airportCodes: Record<string, string> = {
+      Paris: "CDG",
+      London: "LHR",
+      "New York": "JFK",
+      Tokyo: "NRT",
+      "Los Angeles": "LAX",
+    };
 
-// Tool 2: Parse and validate dates
-const validateDateTool: Tool<FlightBookingContext, FlightData, [], void> = {
+    const destinationCode = airportCodes[destination];
+
+    console.log(`[Tool] Enriched: ${destination} → ${destinationCode}`);
+
+    return {
+      destinationCode,
+    } as Partial<FlightData>;
+  },
+};
+
+// Tool 2: Parse and validate dates using ToolManager pattern helper
+const validateDateConfig = {
   id: "validate_date",
   name: "Date Parser & Validator",
-  description:
-    "Parse relative dates (today, tomorrow) to ISO format and validate",
-  parameters: {
-    type: "object",
-    properties: {},
-  },
-  handler: ({ data }: { data?: Partial<FlightData> }) => {
-    const departureDate = (data as Partial<FlightData>)?.departureDate;
+  description: "Parse relative dates (today, tomorrow) to ISO format and validate",
+  fields: ["departureDate"] as const,
+  enricher: async (context: FlightBookingContext, data: Pick<FlightData, "departureDate">) => {
+    const departureDate = data.departureDate;
 
     if (!departureDate) {
-      return { data: undefined };
+      return {};
     }
 
     let parsedDate: string;
@@ -130,16 +122,13 @@ const validateDateTool: Tool<FlightBookingContext, FlightData, [], void> = {
     console.log(`[Tool] Parsed date: ${departureDate} → ${parsedDate}`);
 
     return {
-      data: undefined,
-      dataUpdate: {
-        departureDateParsed: parsedDate,
-      } as Partial<FlightData>,
-    };
+      departureDateParsed: parsedDate,
+    } as Partial<FlightData>;
   },
 };
 
-// Tool 3: Search for flights (triggered by flag)
-const searchFlightsTool: Tool<FlightBookingContext, FlightData, [], void> = {
+// Tool 3: Search for flights (triggered by flag) using unified Tool interface
+const searchFlightsTool: Tool<FlightBookingContext, FlightData> = {
   id: "search_flights",
   name: "Flight Availability Search",
   description: "Search for available flights based on collected data",
@@ -147,12 +136,12 @@ const searchFlightsTool: Tool<FlightBookingContext, FlightData, [], void> = {
     type: "object",
     properties: {},
   },
-  handler: ({ data }: { data?: Partial<FlightData> }) => {
-    const flightData = data as Partial<FlightData>;
+  handler: async (toolContext, args) => {
+    const flightData = toolContext.data;
 
     if (!flightData?.destinationCode || !flightData?.departureDateParsed) {
       console.log("[Tool] Cannot search flights: missing required data");
-      return { data: undefined };
+      return { data: "Missing required data for flight search" };
     }
 
     // Simulate flight search API call
@@ -176,19 +165,19 @@ const searchFlightsTool: Tool<FlightBookingContext, FlightData, [], void> = {
     );
 
     return {
-      data: undefined,
+      data: `Found ${flights.length} available flights`,
       contextUpdate: {
         availableFlights: flights,
       },
       dataUpdate: {
-        shouldSearchFlights: false, // Clear the flag to prevent re-execution
-      } as Partial<FlightData>,
+        shouldSearchFlights: false,
+      },
     };
   },
 };
 
-// Tool 4: Book the flight
-const bookFlightTool: Tool<FlightBookingContext, FlightData, [], void> = {
+// Tool 4: Book the flight using unified Tool interface
+const bookFlightTool: Tool<FlightBookingContext, FlightData> = {
   id: "book_flight",
   name: "Flight Booking Processor",
   description: "Finalize the flight booking",
@@ -196,11 +185,11 @@ const bookFlightTool: Tool<FlightBookingContext, FlightData, [], void> = {
     type: "object",
     properties: {},
   },
-  handler: ({ data }: { data?: Partial<FlightData> }) => {
-    const flightData = data as Partial<FlightData>;
+  handler: async (toolContext, args) => {
+    const flightData = toolContext.data;
     console.log("[Tool] Booking flight with data:", flightData);
     // Simulate booking API call
-    return { data: undefined };
+    return { data: "Flight booking confirmed!" };
   },
 };
 
@@ -296,7 +285,7 @@ const agent = new Agent<FlightBookingContext, FlightData>({
   description: "I help you find and book flights",
   provider: new OpenAIProvider({
     apiKey: process.env.OPENAI_API_KEY || "your-api-key-here",
-    model: "gpt-5o-mini",
+    model: "gpt-4o-mini",
   }),
   context: {},
   // NEW: Agent-level schema
@@ -306,6 +295,117 @@ const agent = new Agent<FlightBookingContext, FlightData>({
   },
 });
 
+// Pattern 1: Using the enrichDestinationConfig with inline tool creation
+const enrichDestinationTool = {
+  id: "enrich_destination",
+  name: "Destination Code Lookup", 
+  description: "Convert city names to IATA airport codes",
+  parameters: {
+    type: "object",
+    properties: {},
+  },
+  handler: async (context: ToolContext<FlightBookingContext, FlightData>, args?: Record<string, unknown>) => {
+    const destination = context.data.destination;
+
+    if (!destination) {
+      return { data: "No destination to enrich" };
+    }
+
+    // Use the original enricher function from the config
+    const result = await enrichDestinationConfig.enricher(context.context, { destination });
+
+    console.log(`[Tool] Enriched: ${destination} → ${result.destinationCode}`);
+
+    return {
+      data: `Destination code: ${result.destinationCode}`,
+      dataUpdate: result,
+    };
+  },
+};
+
+// Pattern 2: Using the validateDateConfig with typed tool interface
+const validateDateTool: Tool<FlightBookingContext, FlightData> = {
+  id: "validate_date",
+  name: "Date Parser & Validator",
+  description: "Parse relative dates (today, tomorrow) to ISO format and validate",
+  parameters: {
+    type: "object",
+    properties: {},
+  },
+  handler: async (context, args) => {
+    const departureDate = context.data.departureDate;
+
+    if (!departureDate) {
+      return { data: "No departure date to validate" };
+    }
+
+    // Use the original enricher function from the config
+    const result = await validateDateConfig.enricher(context.context, { departureDate });
+
+    console.log(`[Tool] Parsed date: ${departureDate} → ${result.departureDateParsed}`);
+
+    return {
+      data: `Parsed date: ${result.departureDateParsed}`,
+      dataUpdate: result,
+    };
+  },
+};
+
+// Demonstrate different registration methods for data enrichment tools
+
+// Method 1: Register enrichment tools for ID-based reference
+agent.tool.register(enrichDestinationTool);
+agent.tool.register(validateDateTool);
+
+// Method 2: Use registerMany for multiple tools
+agent.tool.registerMany([searchFlightsTool, bookFlightTool]);
+
+// Method 3: Create specialized data enrichment tools using the helper
+const passengerEnrichmentTool = agent.tool.createDataEnrichment({
+  id: "enrich_passenger_info",
+  fields: ["passengers"] as const,
+  enricher: async (context, data) => {
+    // Add passenger type classification - return fields that exist in FlightData
+    const cabinClass = data.passengers === 1 ? "business" : data.passengers <= 4 ? "economy" : "economy";
+    return {
+      cabinClass, // This matches the cabinClass field in FlightData
+    };
+  },
+});
+
+// Method 4: Create validation tool using the helper
+const flightDataValidator = agent.tool.createValidation({
+  id: "validate_flight_data",
+  fields: ["destination", "departureDate", "passengers"] as const,
+  validator: async (context, data) => {
+    const errors: ValidationError[] = [];
+    if (!data.destination) errors.push({ 
+      field: "destination", 
+      value: data.destination,
+      message: "Destination is required",
+      schemaPath: "destination"
+    });
+    if (!data.departureDate) errors.push({ 
+      field: "departureDate", 
+      value: data.departureDate,
+      message: "Departure date is required",
+      schemaPath: "departureDate"
+    });
+    if (!data.passengers || data.passengers < 1) errors.push({ 
+      field: "passengers", 
+      value: data.passengers,
+      message: "At least 1 passenger required",
+      schemaPath: "passengers"
+    });
+    
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings: [],
+    };
+  },
+});
+
 // Define route with data extraction
 const bookingRoute = agent.createRoute({
   title: "Book Flight",
@@ -320,6 +420,13 @@ const bookingRoute = agent.createRoute({
   optionalFields: ["destinationCode", "departureDateParsed", "cabinClass", "shouldSearchFlights"],
 });
 
+// Method 5: Add route-scoped tools (only available in this route)
+bookingRoute.addTool({
+  id: "route_specific_tool",
+  description: "Tool only available in booking route",
+  handler: () => "This tool is scoped to the booking route only",
+});
+
 // Step 1: Collect destination
 const collectDestination = bookingRoute.initialStep.nextStep({
   prompt: "Ask where they want to fly",
@@ -329,7 +436,7 @@ const collectDestination = bookingRoute.initialStep.nextStep({
 
 // Step 2: Enrich destination (tool execution)
 const enrichDestination = collectDestination.nextStep({
-  tools: [enrichDestinationTool],
+  tools: ["enrich_destination"], // Reference by ID
   requires: ["destination"],
 });
 
@@ -342,7 +449,7 @@ const collectDate = enrichDestination.nextStep({
 
 // Step 4: Validate/parse date (tool execution)
 const validateDate = collectDate.nextStep({
-  tools: [validateDateTool],
+  tools: ["validate_date"], // Reference by ID
   requires: ["departureDate"],
 });
 
@@ -355,7 +462,7 @@ const collectPassengers = validateDate.nextStep({
 
 // Step 6: Search flights (triggered by hook setting shouldSearchFlights)
 const searchFlights = collectPassengers.nextStep({
-  tools: [searchFlightsTool],
+  tools: ["search_flights"], // Reference by ID
   // This step is entered when shouldSearchFlights is true
   // The hook automatically sets this flag when all data is collected
 });
@@ -371,9 +478,12 @@ const confirmBooking = presentResults.nextStep({
   requires: ["destinationCode", "departureDateParsed", "passengers"],
 });
 
+// Method 6: Step-scoped tools can be added via the step's tools array
+// Note: Step-scoped tools are typically defined inline in the step configuration
+
 // Step 9: Finalize booking
 const finalizeBooking = confirmBooking.nextStep({
-  tools: [bookFlightTool],
+  tools: ["book_flight"], // Reference by ID
   when: "User confirms the booking",
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "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

@@ -16,6 +16,7 @@ import type {
   StructuredSchema,
   ValidationError,
   ValidationResult,
+
 } from "../types";
 import type { StreamOptions, GenerateOptions, RespondParams } from "./ResponseModal";
 import {
@@ -30,8 +31,9 @@ import { Step } from "./Step";
 import { PersistenceManager } from "./PersistenceManager";
 import { SessionManager } from "./SessionManager";
 import { RoutingEngine } from "./RoutingEngine";
-import { ToolExecutor } from "./ToolExecutor";
+
 import { ResponseModal } from "./ResponseModal";
+import { ToolManager } from "./ToolManager";
 
 /**
  * Error thrown when data validation fails
@@ -60,7 +62,7 @@ class RouteConfigurationError extends Error {
 export class Agent<TContext = any, TData = any> {
   private terms: Term<TContext, TData>[] = [];
   private guidelines: Guideline<TContext, TData>[] = [];
-  private tools: Tool<TContext, TData, unknown[], unknown>[] = [];
+  private tools: Tool<TContext, TData>[] = [];
   private routes: Route<TContext, TData>[] = [];
   private context: TContext | undefined;
   private persistenceManager: PersistenceManager<TData> | undefined;
@@ -74,6 +76,9 @@ export class Agent<TContext = any, TData = any> {
   /** Public session manager for easy session management */
   public session: SessionManager<TData>;
 
+  /** Public tool manager for simplified tool creation and management */
+  public tool: ToolManager<TContext, TData>;
+
   constructor(private readonly options: AgentOptions<TContext, TData>) {
     // Set log level based on debug option
     if (options.debug) {
@@ -188,13 +193,23 @@ export class Agent<TContext = any, TData = any> {
       this.knowledgeBase = { ...options.knowledgeBase };
     }
 
-    // Initialize session manager
-    this.session = new SessionManager<TData>(this.persistenceManager);
+    // Initialize session manager with reference to this agent for bidirectional sync
+    this.session = new SessionManager<TData>(this.persistenceManager, this);
+
+    // Initialize tool manager with proper type inference
+    this.tool = new ToolManager<TContext, TData>(this);
 
     // Store sessionId for later use in getOrCreate calls
     if (options.sessionId) {
+      this.session.setDefaultSessionId(options.sessionId);
       // The session will be loaded on first getOrCreate call
-      this.session.getOrCreate(options.sessionId).catch((err) => {
+      this.session.getOrCreate(options.sessionId).then((session) => {
+        // Sync session data to agent collected data
+        if (session.data && Object.keys(session.data).length > 0) {
+          this.collectedData = { ...session.data };
+          logger.debug("[Agent] Synced session data to collected data:", this.collectedData);
+        }
+      }).catch((err) => {
         logger.error("Failed to start session", err);
       });
     }
@@ -294,6 +309,8 @@ export class Agent<TContext = any, TData = any> {
    * Get the current collected data
    */
   getCollectedData(): Partial<TData> {
+    // Ensure agent collected data is synced with session
+    this.syncSessionDataToCollectedData();
     return { ...this.collectedData };
   }
 
@@ -334,6 +351,13 @@ export class Agent<TContext = any, TData = any> {
       this.currentSession = mergeCollected(this.currentSession, this.collectedData);
     }
 
+    // Also update the session manager's session data (avoid circular call)
+    const sessionManagerSession = this.session.current;
+    if (sessionManagerSession) {
+      sessionManagerSession.data = { ...this.collectedData };
+      sessionManagerSession.metadata!.lastUpdatedAt = new Date();
+    }
+
     logger.debug("[Agent] Collected data updated:", updates);
   }
 
@@ -401,7 +425,7 @@ export class Agent<TContext = any, TData = any> {
       }
     }
 
-    const route = new Route<TContext, TData>(options);
+    const route = new Route<TContext, TData>(options, this);
     this.routes.push(route);
     return route;
   }
@@ -428,18 +452,53 @@ export class Agent<TContext = any, TData = any> {
   }
 
   /**
-   * Register a tool at the agent level
+   * Add a tool to the agent using the unified Tool interface
+   * Creates and adds the tool to agent scope in one operation (BREAKING CHANGE: replaces createTool)
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  addTool<TResult = any>(
+    tool: Tool<TContext, TData, TResult>
+  ): this {
+    // Validate tool before adding
+    if (!tool || !tool.id || !tool.handler) {
+      throw new Error('Invalid tool: must have id and handler properties');
+    }
+    
+    // Add directly to agent's tools array, preserving the TResult type
+    this.tools.push(tool);
+    logger.debug(`[Agent] Added tool to agent scope: ${tool.id}`);
+    return this;
+  }
+
+  /**
+   * Register a tool at the agent level (legacy method for backward compatibility)
+   * @deprecated Use addTool() with Tool interface instead
    */
-  createTool(tool: Tool<TContext, TData, unknown[], unknown>): this {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  createTool<TResult = any>(tool: Tool<TContext, TData, TResult>): 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);
+    logger.debug(`[Agent] Created tool (legacy): ${tool.id}`);
     return this;
   }
 
   /**
    * Register multiple tools at the agent level
    */
-  registerTools(tools: Tool<TContext, TData, unknown[], unknown>[]): this {
-    tools.forEach((tool) => this.createTool(tool));
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  registerTools<TResult = any>(tools: Tool<TContext, TData, TResult>[]): this {
+    tools.forEach((tool) => {
+      // Validate each tool before adding
+      if (!tool || !tool.id || !tool.handler) {
+        throw new Error(`Invalid tool in batch: must have id and handler properties (tool: ${tool?.id || 'unknown'})`);
+      }
+      this.tools.push(tool);
+    });
+    logger.debug(`[Agent] Registered ${tools.length} tools`);
     return this;
   }
 
@@ -598,7 +657,7 @@ export class Agent<TContext = any, TData = any> {
   /**
    * Get all tools
    */
-  getTools(): Tool<TContext, TData, unknown[], unknown>[] {
+  getTools(): Tool<TContext, TData>[] {
     return [...this.tools];
   }
 
@@ -660,7 +719,7 @@ export class Agent<TContext = any, TData = any> {
   async executePrepareFinalize(
     prepareOrFinalize:
       | string
-      | Tool<TContext, TData, unknown[], unknown>
+      | Tool<TContext, TData>
       | ((context: TContext, data?: Partial<TData>) => void | Promise<void>)
       | undefined,
     context: TContext,
@@ -675,44 +734,24 @@ export class Agent<TContext = any, TData = any> {
       await prepareOrFinalize(context, data);
     } else {
       // It's a tool reference - find and execute the tool
-      let tool: Tool<TContext, TData, unknown[], unknown> | undefined;
+      let tool: Tool<TContext, TData> | undefined;
 
       if (typeof prepareOrFinalize === "string") {
-        // Tool ID - find it in available tools
-        const availableTools = new Map<string, Tool<TContext, TData, unknown[], unknown>>();
-
-        // Add agent-level tools
-        this.tools.forEach((t) => {
-          availableTools.set(t.id, t);
-        });
-
-        // Add route-level tools
-        if (route) {
-          route.getTools().forEach((t) => {
-            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 (toolRef.id) {
-              availableTools.set(toolRef.id, toolRef);
-            }
-          }
-        }
-
-        tool = availableTools.get(prepareOrFinalize);
+        // Tool ID - use ToolManager to find it across all scopes
+        tool = this.tool.find(prepareOrFinalize, undefined, step, route);
       } else {
-        // Tool object - use directly
-        tool = prepareOrFinalize;
+        // Tool object - validate it has required properties
+        if (prepareOrFinalize.id && typeof prepareOrFinalize.handler === 'function') {
+          tool = prepareOrFinalize;
+        } else {
+          logger.error(`[Agent] Invalid tool object for prepare/finalize: missing id or invalid handler`);
+          return;
+        }
       }
 
       if (tool) {
-        const toolExecutor = new ToolExecutor<TContext, TData>();
-        const result = await toolExecutor.executeTool({
+        // Use ToolManager for execution
+        const result = await this.tool.executeTool({
           tool,
           context,
           updateContext: this.updateContext.bind(this),
@@ -745,12 +784,27 @@ export class Agent<TContext = any, TData = any> {
     this.currentSession = undefined;
   }
 
+  /**
+   * Sync session data to agent collected data
+   * @internal Used to keep agent and session data in sync
+   */
+  private syncSessionDataToCollectedData(): void {
+    const sessionData = this.session.getData();
+    if (sessionData && Object.keys(sessionData).length > 0) {
+      this.collectedData = { ...sessionData };
+      logger.debug("[Agent] Synced session data to collected data:", this.collectedData);
+    }
+  }
+
   /**
    * Get collected data from current session or agent-level collected data
    * @param routeId - Optional route ID to get data for (uses current route if not provided)
    * @returns The collected data from the current session or agent-level data
    */
   getData(): Partial<TData> {
+    // Ensure agent collected data is synced with session
+    this.syncSessionDataToCollectedData();
+    
     // If we have a current session, use session data
     if (this.currentSession) {
       // With agent-level data, all routes share the same data structure