@falai/agent 0.9.0 → 1.0.0

package/src/core/SessionManager.ts

@@ -9,6 +9,7 @@ import type { SessionState } from "../types/session";
 import type { History, HistoryItem } from "../types/history";
 import { PersistenceManager } from "./PersistenceManager";
 import type { PersistenceAdapter } from "../types/persistence";
+import type { Agent } from "./Agent";
 
 /**
  * SessionManager handles session lifecycle and conversation history
@@ -16,11 +17,16 @@ import type { PersistenceAdapter } from "../types/persistence";
 export class SessionManager<TData = unknown> {
   private currentSession?: SessionState<TData>;
   private persistenceManager?: PersistenceManager<TData>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private agent?: Agent<any, TData>;
+  private defaultSessionId?: string;
 
   constructor(
     persistenceManagerOrAdapter?:
       | PersistenceManager<TData>
-      | PersistenceAdapter<TData>
+      | PersistenceAdapter<TData>,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    agent?: Agent<any, TData>
   ) {
     if (persistenceManagerOrAdapter) {
       // Check if it's a PersistenceManager or an adapter
@@ -33,6 +39,16 @@ export class SessionManager<TData = unknown> {
         });
       }
     }
+
+    this.agent = agent;
+  }
+
+  /**
+   * Set the default session ID to use when getOrCreate is called without parameters
+   * @internal Used by Agent to set the sessionId from constructor options
+   */
+  setDefaultSessionId(sessionId: string): void {
+    this.defaultSessionId = sessionId;
   }
 
   /**
@@ -40,16 +56,24 @@ export class SessionManager<TData = unknown> {
    * Works for sessionIds that exist, don't exist, or auto-generated IDs
    */
   async getOrCreate(sessionId?: string): Promise<SessionState<TData>> {
+    // Use provided sessionId or fall back to default
+    const effectiveSessionId = sessionId || this.defaultSessionId;
+
     // If we already have a session and no sessionId specified, return it
-    if (this.currentSession && !sessionId) {
+    if (this.currentSession && !effectiveSessionId) {
+      return this.currentSession;
+    }
+
+    // If we have a session with the same ID, return it
+    if (this.currentSession && this.currentSession.id === effectiveSessionId) {
       return this.currentSession;
     }
 
     // If sessionId provided, try to load it first
-    if (sessionId && this.persistenceManager) {
+    if (effectiveSessionId && this.persistenceManager) {
       try {
         const session = await this.persistenceManager.loadSessionState(
-          sessionId
+          effectiveSessionId
         );
         if (session) {
           this.currentSession = session;
@@ -62,7 +86,7 @@ export class SessionManager<TData = unknown> {
     }
 
     // Create new session (with provided ID or auto-generated)
-    return this.create(sessionId);
+    return this.create(effectiveSessionId);
   }
 
   /**
@@ -117,6 +141,9 @@ export class SessionManager<TData = unknown> {
     session.history.push(historyItem);
     session.metadata!.lastUpdatedAt = new Date();
 
+    // Ensure currentSession is updated
+    this.currentSession = session;
+
     // Auto-save to persistence
     await this.save();
   }
@@ -205,7 +232,12 @@ export class SessionManager<TData = unknown> {
         ...data,
       };
       this.currentSession.metadata!.lastUpdatedAt = new Date();
-      
+
+      // Synchronize with agent's collected data for bidirectional sync
+      if (this.agent) {
+        await this.agent.updateCollectedData(this.currentSession.data);
+      }
+
       // Auto-save to persistence
       await this.save();
     }
@@ -226,7 +258,7 @@ export class SessionManager<TData = unknown> {
     if (this.currentSession) {
       this.currentSession.data = {} as Partial<TData>;
       this.currentSession.metadata!.lastUpdatedAt = new Date();
-      
+
       // Auto-save to persistence
       await this.save();
     }

package/src/core/Step.ts

@@ -9,12 +9,15 @@ import type {
   BranchSpec,
   BranchResult,
   Guideline,
+  GuidelineMatch,
   Tool,
+  SessionState,
+  Event,
 } from "../types";
-import { Template } from "../types/template";
-
+import { ToolScope, Template, ConditionTemplate, TemplateContext } from "../types";
+import { createConditionEvaluator, generateStepId, logger } from "../utils";
+import { Agent } from './Agent'
 import { END_ROUTE, END_ROUTE_ID } from "../constants";
-import { generateStepId } from "../utils/id";
 
 /**
  * Represents a step within a route
@@ -22,27 +25,31 @@ import { generateStepId } from "../utils/id";
 export class Step<TContext = unknown, TData = unknown> {
   public readonly id: string;
   private nextSteps: Step<TContext, TData>[] = [];
-  private guidelines: Guideline<TContext>[] = [];
+  private guidelines: Guideline<TContext, TData>[] = [];
   public readonly routeId: string;
   public collect?: (keyof TData)[];
   public description?: string;
-  public when?: Template<TContext, TData>;
-  public skipIf?: (data: Partial<TData>) => boolean;
+  public when?: ConditionTemplate<TContext, TData>;
+  public skipIf?: ConditionTemplate<TContext, TData>;
   public requires?: (keyof TData)[];
   public prompt?: Template<TContext, TData>;
   public prepare?:
     | string
-    | Tool<TContext, TData, unknown[], unknown>
+    | Tool<TContext, TData>
     | ((context: TContext, data?: Partial<TData>) => void | Promise<void>);
   public finalize?:
     | string
-    | Tool<TContext, TData, unknown[], unknown>
+    | Tool<TContext, TData>
     | ((context: TContext, data?: Partial<TData>) => void | Promise<void>);
-  public tools?: (string | Tool<TContext, TData, unknown[], unknown>)[];
+  public tools?: (string | Tool<TContext, TData>)[];
+
+  // Reference to parent agent for ToolManager access
+  private parentAgent?: Agent<TContext, TData>; 
 
   constructor(
-    routeId: string, 
-    options: StepOptions<TContext, TData> = {}
+    routeId: string,
+    options: StepOptions<TContext, TData> = {},
+    parentAgent?: Agent<TContext, TData> 
   ) {
     // Use provided ID or generate a deterministic one
     this.id = options.id || generateStepId(routeId, options.description);
@@ -57,6 +64,16 @@ export class Step<TContext = unknown, TData = unknown> {
     this.prepare = options.prepare;
     this.finalize = options.finalize;
     this.tools = options.tools;
+
+    // Initialize guidelines from options
+    if (options.guidelines) {
+      options.guidelines.forEach((guideline) => {
+        this.addGuideline(guideline);
+      });
+    }
+
+    // Store reference to parent agent for ToolManager access
+    this.parentAgent = parentAgent;
   }
 
   /**
@@ -66,35 +83,35 @@ export class Step<TContext = unknown, TData = unknown> {
   configure(config: {
     description?: string;
     collect?: (keyof TData)[];
-    skipIf?: (data: Partial<TData>) => boolean;
+    skipIf?: ConditionTemplate<TContext, TData>;
     requires?: (keyof TData)[];
     prompt?: Template<TContext, TData>;
     prepare?:
-      | string
-      | Tool<TContext, TData, unknown[], unknown>
-      | ((context: TContext, data?: Partial<TData>) => void | Promise<void>);
+    | string
+    | Tool<TContext, TData>
+    | ((context: TContext, data?: Partial<TData>) => void | Promise<void>);
     finalize?:
-      | string
-      | Tool<TContext, TData, unknown[], unknown>
-      | ((context: TContext, data?: Partial<TData>) => void | Promise<void>);
-    tools?: (string | Tool<TContext, TData, unknown[], unknown>)[];
+    | string
+    | Tool<TContext, TData>
+    | ((context: TContext, data?: Partial<TData>) => void | Promise<void>);
+    tools?: (string | Tool<TContext, TData>)[];
   }): this {
     if (config.description !== undefined) {
       this.description = config.description;
     }
-    
+
     if (config.collect !== undefined) {
       this.collect = config.collect;
     }
-    
+
     if (config.skipIf !== undefined) {
       this.skipIf = config.skipIf;
     }
-    
+
     if (config.requires !== undefined) {
       this.requires = config.requires;
     }
-    
+
     if (config.prompt !== undefined) {
       this.prompt = config.prompt;
     }
@@ -137,7 +154,7 @@ export class Step<TContext = unknown, TData = unknown> {
       const endStep = new Step<TContext, TData>(this.routeId, {
         ...spec,
         id: END_ROUTE_ID,
-      });
+      }, this.parentAgent);
       this.nextSteps.push(endStep);
       return this.createTerminalRef();
     }
@@ -150,7 +167,7 @@ export class Step<TContext = unknown, TData = unknown> {
     }
 
     // Create new target step for prompt or tool
-    const targetStep = new Step<TContext, TData>(this.routeId, spec);
+    const targetStep = new Step<TContext, TData>(this.routeId, spec, this.parentAgent);
     this.nextSteps.push(targetStep);
 
     return this.createStepRefWithTransition(targetStep.getRef(), targetStep);
@@ -174,7 +191,7 @@ export class Step<TContext = unknown, TData = unknown> {
         : branchSpec.step;
 
       // Create a new step for this branch
-      const branchStep = new Step<TContext, TData>(this.routeId, stepOptions);
+      const branchStep = new Step<TContext, TData>(this.routeId, stepOptions, this.parentAgent);
       // Add it to our transitions
       this.nextSteps.push(branchStep);
       // Create a step result for chaining
@@ -191,17 +208,230 @@ export class Step<TContext = unknown, TData = unknown> {
   /**
    * Add a guideline specific to this step
    */
-  addGuideline(guideline: Guideline<TContext>): void {
+  addGuideline(guideline: Guideline<TContext, TData>): void {
     this.guidelines.push(guideline);
   }
 
   /**
    * Get guidelines for this step
    */
-  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;
+  }
+
+  /**
+   * Add a tool to this step using the unified Tool interface
+   * Creates and adds the tool to step scope in one operation
+   */
+  addTool(
+    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');
+    }
+
+    // Add to step's tools array
+    if (!this.tools) {
+      this.tools = [];
+    }
+    this.tools.push(tool);
+
+    return this;
+  }
+
+  /**
+   * Resolve tool references in the tools array
+   * Supports both string IDs (resolved from registry) and inline tool objects
+   */
+  resolveTools(): Tool<TContext, TData>[] {
+    if (!this.tools) {
+      return [];
+    }
+
+    const resolvedTools: Tool<TContext, TData>[] = [];
+
+    for (const toolRef of this.tools) {
+      if (typeof toolRef === 'string') {
+        // Tool ID - try to resolve from ToolManager using proper scope resolution
+        if (this.parentAgent?.tool) {
+          const registeredTool = this.parentAgent.tool.find(toolRef);
+          if (registeredTool) {
+            resolvedTools.push(registeredTool);
+          } else {
+            // Tool not found - log warning but don't fail
+            logger.warn(`[Step] Tool ID '${toolRef}' not found in any scope for step ${this.id}`);
+          }
+        } else {
+          logger.warn(`[Step] No parent agent available to resolve tool ID '${toolRef}' for step ${this.id}`);
+        }
+      } else {
+        // Inline tool object - validate and use directly
+        if (toolRef && toolRef.id && typeof toolRef.handler === 'function') {
+          resolvedTools.push(toolRef);
+        } else {
+          logger.warn(`[Step] Invalid inline tool object in step ${this.id}:`, toolRef);
+        }
+      }
+    }
+
+    return resolvedTools;
+  }
+
+  /**
+   * Get all tools available to this step (both inline and resolved from registry)
+   */
+  getAvailableTools(): (string | Tool<TContext, TData>)[] {
+    return this.tools ? [...this.tools] : [];
+  }
+
+  /**
+   * Get all resolved tools available to this step using ToolManager
+   * This method provides the complete set of tools accessible from this step
+   */
+  getAllAvailableTools(): Tool<TContext, TData>[] {
+    if (!this.parentAgent?.tool) {
+      // Fallback to local resolution if no ToolManager available
+      return this.resolveTools();
+    }
+
+    // Use ToolManager to get all available tools for this step context
+    return this.parentAgent.tool.getAvailable(ToolScope.ALL, this, undefined);
+  }
+
+  /**
+   * Find a specific tool by ID using ToolManager resolution
+   * This method respects the tool resolution hierarchy: step → route → agent → registry
+   */
+  findTool(toolId: string, scope?: ToolScope): Tool<TContext, TData> | undefined {
+    if (!this.parentAgent?.tool) {
+      // Fallback to local resolution if no ToolManager available
+      const resolved = this.resolveTools();
+      return resolved.find(tool => tool.id === toolId || tool.name === toolId);
+    }
+
+    // Use ToolManager to find the tool with proper scope resolution
+    return this.parentAgent.tool.find(toolId, scope || ToolScope.ALL, this, undefined);
+  }
+
+  /**
+   * Get tools from a specific scope
+   */
+  getToolsFromScope(scope: ToolScope): Tool<TContext, TData>[] {
+    if (!this.parentAgent?.tool) {
+      // Fallback to local resolution if no ToolManager available
+      return scope === ToolScope.STEP ? this.resolveTools() : [];
+    }
+
+    return this.parentAgent.tool.getAvailable(scope, this, undefined);
+  }
+
+  /**
+   * Get only step-level tools (inline tools in this step)
+   */
+  getStepTools(): Tool<TContext, TData>[] {
+    return this.getToolsFromScope(ToolScope.STEP);
+  }
+
+  /**
+   * Get only registered tools accessible from this step
+   */
+  getRegisteredTools(): Tool<TContext, TData>[] {
+    return this.getToolsFromScope(ToolScope.REGISTERED);
+  }
+
+  /**
+   * Validate that all tool references in this step can be resolved
+   * Returns validation result with details about missing tools
+   */
+  validateToolReferences(): {
+    valid: boolean;
+    missing: string[];
+    found: string[];
+    details: Array<{ id: string; found: boolean; scope?: string; }>;
+  } {
+    if (!this.tools || this.tools.length === 0) {
+      return { valid: true, missing: [], found: [], details: [] };
+    }
+
+    // Extract tool IDs from the tools array
+    const toolIds: string[] = [];
+    for (const toolRef of this.tools) {
+      if (typeof toolRef === 'string') {
+        toolIds.push(toolRef);
+      } else if (toolRef && toolRef.id) {
+        toolIds.push(toolRef.id);
+      }
+    }
+
+    if (!this.parentAgent?.tool) {
+      // Fallback validation without ToolManager
+      const resolved = this.resolveTools();
+      const resolvedIds = resolved.map(tool => tool.id);
+      const missing = toolIds.filter(id => !resolvedIds.includes(id));
+      const found = toolIds.filter(id => resolvedIds.includes(id));
+      
+      return {
+        valid: missing.length === 0,
+        missing,
+        found,
+        details: toolIds.map(id => ({ id, found: resolvedIds.includes(id) }))
+      };
+    }
+
+    // Use ToolManager validation
+    return this.parentAgent.tool.validateToolReferences(toolIds, this);
+  }
+
   /**
    * Get all transitions from this step
    */
@@ -210,13 +440,63 @@ export class Step<TContext = unknown, TData = unknown> {
   }
 
   /**
-   * Check if this step should be skipped based on collected data
+   * Evaluate when condition using ConditionEvaluator
    */
-  shouldSkip(data: Partial<TData>): boolean {
-    if (!this.skipIf) return false;
-    return this.skipIf(data);
+  async evaluateWhen(
+    templateContext: TemplateContext<TContext, TData>
+  ): Promise<{ 
+    shouldActivate: boolean; 
+    aiContextStrings: string[];
+    hasProgrammaticConditions: boolean;
+  }> {
+    if (!this.when) {
+      return { 
+        shouldActivate: true, 
+        aiContextStrings: [], 
+        hasProgrammaticConditions: false 
+      };
+    }
+
+    const evaluator = createConditionEvaluator(templateContext);
+    const result = await evaluator.evaluateCondition(this.when, 'AND');
+    
+    return {
+      shouldActivate: result.programmaticResult,
+      aiContextStrings: result.aiContextStrings,
+      hasProgrammaticConditions: result.hasProgrammaticConditions
+    };
   }
 
+  /**
+   * Evaluate skipIf condition using ConditionEvaluator
+   */
+  async evaluateSkipIf(
+    templateContext: TemplateContext<TContext, TData>
+  ): Promise<{ 
+    shouldSkip: boolean; 
+    aiContextStrings: string[];
+    hasProgrammaticConditions: boolean;
+  }> {
+    if (!this.skipIf) {
+      return { 
+        shouldSkip: false, 
+        aiContextStrings: [], 
+        hasProgrammaticConditions: false 
+      };
+    }
+
+    const evaluator = createConditionEvaluator(templateContext);
+    const result = await evaluator.evaluateCondition(this.skipIf, 'OR');
+    
+    return {
+      shouldSkip: result.programmaticResult,
+      aiContextStrings: result.aiContextStrings,
+      hasProgrammaticConditions: result.hasProgrammaticConditions
+    };
+  }
+
+
+
   /**
    * Check if this step has all required data to proceed
    */
@@ -250,6 +530,8 @@ export class Step<TContext = unknown, TData = unknown> {
         stepInstance.nextStep(spec),
       branch: (branches: BranchSpec<TContext, TData>[]) =>
         stepInstance.branch(branches),
+      endRoute: (options?: Omit<StepOptions<TContext, TData>, "step">) =>
+        stepInstance.endRoute(options),
     };
   }
 
@@ -270,6 +552,8 @@ export class Step<TContext = unknown, TData = unknown> {
       branch: () => {
         throw new Error("Cannot branch from END_ROUTE step");
       },
+      endRoute: (options?: Omit<StepOptions<TContext, TData>, "step">) =>
+        this.endRoute(options),
     };
   }
 
@@ -282,6 +566,28 @@ export class Step<TContext = unknown, TData = unknown> {
       nextStep: (spec: StepOptions<TContext, TData>) => this.nextStep(spec),
       branch: (branches: BranchSpec<TContext, TData>[]) =>
         this.branch(branches),
+      endRoute: (options?: Omit<StepOptions<TContext, TData>, "step">) =>
+        this.endRoute(options),
+    };
+  }
+
+  /**
+   * Export step configuration as StepOptions for copying/cloning
+   * @returns StepOptions that can be used to create a new step with identical configuration
+   */
+  toOptions(): StepOptions<TContext, TData> {
+    return {
+      id: this.id,
+      description: this.description,
+      prompt: this.prompt,
+      tools: this.tools,
+      prepare: this.prepare,
+      finalize: this.finalize,
+      collect: this.collect,
+      skipIf: this.skipIf,
+      requires: this.requires,
+      when: this.when,
+      guidelines: this.getGuidelines(),
     };
   }
 }