@falai/agent 0.9.2 → 1.0.0

package/src/core/ResponsePipeline.ts

@@ -19,6 +19,7 @@ import {
   logger,
   render,
 } from "../utils";
+import { createTemplateContext } from "../utils/template";
 import { Route } from "../core/Route";
 import { Step } from "../core/Step";
 import { RoutingEngine } from "../core/RoutingEngine";
@@ -211,12 +212,12 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
   /**
    * Determine next step and update session
    */
-  determineNextStep(params: {
+  async determineNextStep(params: {
     selectedRoute: Route<TContext, TData> | undefined;
     selectedStep: Step<TContext, TData> | undefined;
     session: SessionState<TData>;
     isRouteComplete: boolean;
-  }): { nextStep: Step<TContext, TData> | undefined; session: SessionState<TData> } {
+  }): Promise<{ nextStep: Step<TContext, TData> | undefined; session: SessionState<TData> }> {
     const { selectedRoute, selectedStep, session, isRouteComplete } = params;
 
     if (!selectedRoute || isRouteComplete) {
@@ -229,16 +230,23 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
     if (selectedStep) {
       nextStep = selectedStep;
     } else {
-      // New route or no step selected - get initial step or first valid step
-      const candidates = this.routingEngine.getCandidateSteps(
+      // Determine current step from session if we're already in this route
+      const currentStep = session.currentRoute?.id === selectedRoute.id && session.currentStep
+        ? selectedRoute.getStep(session.currentStep.id)
+        : undefined;
+
+      const contextToUse = this.getStoredContext();
+      // Get candidate steps based on current position in the route
+      const candidates = await this.routingEngine.getCandidateStepsWithConditions(
         selectedRoute,
-        undefined,
-        session.data || {}
+        currentStep, // Pass current step instead of undefined to maintain progression
+        createTemplateContext({ data: session.data, session, context: contextToUse })
       );
+      
       if (candidates.length > 0) {
         nextStep = candidates[0].step;
         logger.debug(
-          `[ResponseHandler] Using first valid step: ${nextStep.id} for new route`
+          `[ResponseHandler] Using first valid step: ${nextStep.id}${currentStep ? ' (progressing from ' + currentStep.id + ')' : ' for new route'}`
         );
       } else {
         // Fallback to initial step even if it should be skipped
@@ -564,11 +572,11 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
       );
 
       if (targetRoute) {
-        const templateContext = {
+        const templateContext = createTemplateContext({
           context,
           session,
           history,
-        };
+        });
         const renderedCondition: string =
           (await render(transitionConfig.condition, templateContext)) ||
           (typeof transitionConfig.condition === "string"

package/src/core/Route.ts

@@ -12,14 +12,21 @@ import type {
   RouteLifecycleHooks,
   StructuredSchema,
   Guideline,
+  GuidelineMatch,
   Term,
   Tool,
   Template,
+  ConditionTemplate,
+  TemplateContext,
+  ConditionEvaluationResult,
+  SessionState,
+  Event,
 } from "../types";
 
+import { createConditionEvaluator, generateRouteId, logger } from "../utils";
+
 import { Step } from "./Step";
 import { Agent } from './Agent'
-import { generateRouteId } from "../utils/id";
 import { END_ROUTE } from "../constants";
 
 /**
@@ -31,7 +38,8 @@ export class Route<TContext = unknown, TData = unknown> {
   public readonly description?: string;
   public readonly identity?: Template<TContext, TData>;
   public readonly personality?: Template<TContext, TData>;
-  public readonly conditions: Template<TContext, TData>[];
+  public readonly when?: ConditionTemplate<TContext, TData>;
+  public readonly skipIf?: ConditionTemplate<TContext, TData>;
   public readonly rules: Template<TContext, TData>[];
   public readonly prohibitions: Template<TContext, TData>[];
   public readonly initialStep: Step<TContext, TData>;
@@ -49,7 +57,7 @@ export class Route<TContext = unknown, TData = unknown> {
     | RouteCompletionHandler<TContext, TData>;
   public readonly hooks?: RouteLifecycleHooks<TContext, TData>;
   public routingExtrasSchema?: StructuredSchema;
-  public guidelines: Guideline<TContext>[] = [];
+  public guidelines: Guideline<TContext, TData>[] = [];
   public terms: Term<TContext>[] = [];
   public tools: Tool<TContext, TData>[] = [];
   public knowledgeBase: Record<string, unknown> = {};
@@ -64,7 +72,8 @@ export class Route<TContext = unknown, TData = unknown> {
     this.description = options.description;
     this.identity = options.identity;
     this.personality = options.personality;
-    this.conditions = options.conditions || [];
+    this.when = options.when;
+    this.skipIf = options.skipIf;
     this.rules = options.rules || [];
     this.prohibitions = options.prohibitions || [];
 
@@ -122,8 +131,28 @@ export class Route<TContext = unknown, TData = unknown> {
 
     // Initialize tools from options
     if (options.tools) {
-      options.tools.forEach((tool) => {
-        this.createTool(tool);
+      options.tools.forEach((toolRef) => {
+        if (typeof toolRef === 'string') {
+          // Tool ID - try to resolve from ToolManager
+          if (this.parentAgent?.tool) {
+            const registeredTool = this.parentAgent.tool.find(toolRef);
+            if (registeredTool) {
+              this.createTool(registeredTool);
+            } else {
+              // Tool not found - log warning but don't fail
+              logger.warn(`[Route] Tool ID '${toolRef}' not found in any scope for route ${this.title}`);
+            }
+          } else {
+            logger.warn(`[Route] No agent available to resolve tool ID '${toolRef}' for route ${this.title}`);
+          }
+        } else {
+          // Inline tool object - validate and use directly
+          if (toolRef && toolRef.id && typeof toolRef.handler === 'function') {
+            this.createTool(toolRef);
+          } else {
+            logger.warn(`[Route] Invalid inline tool object in route ${this.title}:`, toolRef);
+          }
+        }
       });
     }
 
@@ -151,10 +180,50 @@ export class Route<TContext = unknown, TData = unknown> {
     }
   }
 
+  /**
+   * Evaluate the when condition for this route
+   * @param templateContext - Context for condition evaluation
+   * @returns Evaluation result with programmatic result and AI context strings
+   */
+  async evaluateWhen(
+    templateContext: TemplateContext<TContext, TData>
+  ): Promise<ConditionEvaluationResult> {
+    if (!this.when) {
+      return {
+        programmaticResult: true, // No condition means always eligible
+        aiContextStrings: [],
+        hasProgrammaticConditions: false,
+      };
+    }
+
+    const evaluator = createConditionEvaluator(templateContext);
+    return await evaluator.evaluateCondition(this.when, 'AND');
+  }
+
+  /**
+   * Evaluate the skipIf condition for this route
+   * @param templateContext - Context for condition evaluation
+   * @returns Evaluation result with programmatic result and AI context strings
+   */
+  async evaluateSkipIf(
+    templateContext: TemplateContext<TContext, TData>
+  ): Promise<ConditionEvaluationResult> {
+    if (!this.skipIf) {
+      return {
+        programmaticResult: false, // No skipIf means never skip
+        aiContextStrings: [],
+        hasProgrammaticConditions: false,
+      };
+    }
+
+    const evaluator = createConditionEvaluator(templateContext);
+    return await evaluator.evaluateCondition(this.skipIf, 'OR');
+  }
+
   /**
    * Create a guideline specific to this route
    */
-  createGuideline(guideline: Guideline<TContext>): this {
+  createGuideline(guideline: Guideline<TContext, TData>): this {
     this.guidelines.push({
       ...guideline,
       id: guideline.id || `guideline_${this.id}_${this.guidelines.length}`,
@@ -212,10 +281,59 @@ export class Route<TContext = unknown, TData = unknown> {
   /**
    * Get all guidelines for this route
    */
-  getGuidelines(): Guideline<TContext>[] {
+  getGuidelines(): Guideline<TContext, TData>[] {
     return [...this.guidelines];
   }
 
+  /**
+   * Evaluate and match active guidelines based on their conditions
+   * Returns guidelines that should be active given the current context
+   */
+  async evaluateGuidelines(
+    context?: TContext,
+    session?: SessionState<TData>,
+    history?: Event[]
+  ): Promise<GuidelineMatch<TContext, TData>[]> {
+    const templateContext = { context, session, history, data: session?.data };
+    const evaluator = createConditionEvaluator(templateContext);
+    const matches: GuidelineMatch<TContext, TData>[] = [];
+
+    for (const guideline of this.guidelines) {
+      // Skip disabled guidelines
+      if (guideline.enabled === false) {
+        continue;
+      }
+
+      if (guideline.condition) {
+        const evaluation = await evaluator.evaluateCondition(guideline.condition, 'AND');
+        
+        // Include guideline if:
+        // 1. No programmatic conditions (only strings) - always active
+        // 2. Programmatic conditions evaluate to true
+        if (!evaluation.hasProgrammaticConditions || evaluation.programmaticResult) {
+          const rationale = evaluation.aiContextStrings.length > 0
+            ? `Condition met: ${evaluation.aiContextStrings.join(" AND ")}`
+            : evaluation.hasProgrammaticConditions
+              ? "Programmatic condition evaluated to true"
+              : "Always active (no conditions)";
+          
+          matches.push({
+            guideline,
+            rationale
+          });
+        }
+      } else {
+        // No condition means always active
+        matches.push({
+          guideline,
+          rationale: "Always active (no conditions)"
+        });
+      }
+    }
+
+    return matches;
+  }
+
   /**
    * Get all terms for this route
    */
@@ -325,7 +443,8 @@ export class Route<TContext = unknown, TData = unknown> {
       `Route: ${this.title}`,
       `ID: ${this.id}`,
       `Description: ${this.description || "N/A"}`,
-      `Conditions: ${this.conditions.join(", ") || "None"}`,
+      `When: ${this.when ? (typeof this.when === 'string' ? this.when : Array.isArray(this.when) ? '[Array]' : '[Function]') : "None"}`,
+      `SkipIf: ${this.skipIf ? (typeof this.skipIf === 'string' ? this.skipIf : Array.isArray(this.skipIf) ? '[Array]' : '[Function]') : "None"}`,
       "",
       "Steps:",
     ];
@@ -382,20 +501,93 @@ export class Route<TContext = unknown, TData = unknown> {
     }
   }
 
+  /**
+   * Export route configuration as RouteOptions for copying/cloning
+   * @returns RouteOptions that can be used to create a new route with identical configuration
+   */
+  toOptions(): RouteOptions<TContext, TData> {
+    // Convert steps to StepOptions
+    const steps = this.getAllSteps()
+      .filter(step => step.id !== this.initialStep.id) // Exclude initial step
+      .map(step => ({
+        id: step.id,
+        description: step.description,
+        prompt: step.prompt,
+        tools: step.tools,
+        prepare: step.prepare,
+        finalize: step.finalize,
+        collect: step.collect,
+        skipIf: step.skipIf,
+        requires: step.requires,
+        when: step.when,
+        guidelines: step.getGuidelines(),
+      }));
+
+    return {
+      id: this.id,
+      title: this.title,
+      description: this.description,
+      identity: this.identity,
+      personality: this.personality,
+      when: this.when,
+      skipIf: this.skipIf,
+      guidelines: this.getGuidelines(),
+      terms: this.getTerms(),
+      tools: this.getTools(),
+      rules: this.rules,
+      prohibitions: this.prohibitions,
+      routingExtrasSchema: this.routingExtrasSchema,
+      responseOutputSchema: this.responseOutputSchema,
+      requiredFields: this.requiredFields,
+      optionalFields: this.optionalFields,
+      initialData: this.initialData,
+      steps: steps.length > 0 ? steps : undefined,
+      initialStep: {
+        id: this.initialStep.id,
+        description: this.initialStep.description,
+        prompt: this.initialStep.prompt,
+        tools: this.initialStep.tools,
+        prepare: this.initialStep.prepare,
+        finalize: this.initialStep.finalize,
+        collect: this.initialStep.collect,
+        skipIf: this.initialStep.skipIf,
+        requires: this.initialStep.requires,
+        when: this.initialStep.when,
+        guidelines: this.initialStep.getGuidelines(),
+      },
+      endStep: this.endStepSpec,
+      onComplete: this.onComplete,
+      hooks: this.hooks,
+      knowledgeBase: this.knowledgeBase,
+    };
+  }
+
   /**
    * Check if this route is complete based on the provided data
    * @param data - Currently collected agent-level data
    * @returns true if all required fields are present, false otherwise
+   * 
+   * Note: Routes with no requiredFields AND no optionalFields are never complete
+   * based on data (they complete via END_ROUTE). Routes with only optionalFields
+   * are always complete (optional data doesn't block completion).
    */
   isComplete(data: Partial<TData>): boolean {
-    if (!this.requiredFields || this.requiredFields.length === 0) {
-      return true; // No required fields means route is always complete
+    // If route has required fields, check if they're all collected
+    if (this.requiredFields && this.requiredFields.length > 0) {
+      return this.requiredFields.every(field => {
+        const value = data[field];
+        return value !== undefined && value !== null && value !== '';
+      });
     }
 
-    return this.requiredFields.every(field => {
-      const value = data[field];
-      return value !== undefined && value !== null && value !== '';
-    });
+    // If route has optional fields but no required fields, it's always complete
+    if (this.optionalFields && this.optionalFields.length > 0) {
+      return true;
+    }
+
+    // No required or optional fields - route doesn't complete based on data
+    // It can only complete by reaching END_ROUTE in step flow
+    return false;
   }
 
   /**
@@ -418,18 +610,27 @@ export class Route<TContext = unknown, TData = unknown> {
    * Get the completion progress for this route as a percentage
    * @param data - Currently collected agent-level data
    * @returns Completion progress as a number between 0 and 1
+   * 
+   * Note: Must be consistent with isComplete() logic
    */
   getCompletionProgress(data: Partial<TData>): number {
-    if (!this.requiredFields || this.requiredFields.length === 0) {
-      return 1; // No required fields means 100% complete
+    // If route has required fields, calculate progress
+    if (this.requiredFields && this.requiredFields.length > 0) {
+      const completedFields = this.requiredFields.filter(field => {
+        const value = data[field];
+        return value !== undefined && value !== null && value !== '';
+      });
+      return completedFields.length / this.requiredFields.length;
     }
 
-    const completedFields = this.requiredFields.filter(field => {
-      const value = data[field];
-      return value !== undefined && value !== null && value !== '';
-    });
+    // If route has optional fields but no required fields, it's always complete
+    if (this.optionalFields && this.optionalFields.length > 0) {
+      return 1;
+    }
 
-    return completedFields.length / this.requiredFields.length;
+    // No required or optional fields - route doesn't complete based on data
+    // Progress is 0 (must reach END_ROUTE in step flow)
+    return 0;
   }
 
   /**