@falai/agent 0.9.0 → 0.9.2

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

@@ -11,8 +11,9 @@ import type {
   Guideline,
   Tool,
 } from "../types";
+import { ToolScope } from "../types";
 import { Template } from "../types/template";
-
+import { Agent } from './Agent'
 import { END_ROUTE, END_ROUTE_ID } from "../constants";
 import { generateStepId } from "../utils/id";
 
@@ -32,17 +33,21 @@ export class Step<TContext = unknown, TData = unknown> {
   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 +62,9 @@ export class Step<TContext = unknown, TData = unknown> {
     this.prepare = options.prepare;
     this.finalize = options.finalize;
     this.tools = options.tools;
+
+    // Store reference to parent agent for ToolManager access
+    this.parentAgent = parentAgent;
   }
 
   /**
@@ -70,31 +78,31 @@ export class Step<TContext = unknown, TData = unknown> {
     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 +145,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 +158,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 +182,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
@@ -202,6 +210,170 @@ export class Step<TContext = unknown, TData = unknown> {
     return [...this.guidelines];
   }
 
+  /**
+   * 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
+            console.warn(`[Step] Tool ID '${toolRef}' not found in any scope for step ${this.id}`);
+          }
+        } else {
+          console.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 {
+          console.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
    */
@@ -250,6 +422,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 +444,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 +458,8 @@ 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),
     };
   }
 }