@falai/agent 0.8.0 → 0.9.0-alpha-1

package/src/core/SessionManager.ts

@@ -0,0 +1,241 @@
+/**
+ * SessionManager - Simplified session management with history
+ *
+ * Provides a clean, pragmatic API for managing sessions and conversation history
+ * in both server and client environments.
+ */
+
+import type { SessionState } from "../types/session";
+import type { History, HistoryItem } from "../types/history";
+import { PersistenceManager } from "./PersistenceManager";
+import type { PersistenceAdapter } from "../types/persistence";
+
+/**
+ * SessionManager handles session lifecycle and conversation history
+ */
+export class SessionManager<TData = unknown> {
+  private currentSession?: SessionState<TData>;
+  private persistenceManager?: PersistenceManager<TData>;
+
+  constructor(
+    persistenceManagerOrAdapter?:
+      | PersistenceManager<TData>
+      | PersistenceAdapter<TData>
+  ) {
+    if (persistenceManagerOrAdapter) {
+      // Check if it's a PersistenceManager or an adapter
+      if ("saveSessionState" in persistenceManagerOrAdapter) {
+        this.persistenceManager = persistenceManagerOrAdapter;
+      } else {
+        // It's an adapter, create a PersistenceManager
+        this.persistenceManager = new PersistenceManager({
+          adapter: persistenceManagerOrAdapter,
+        });
+      }
+    }
+  }
+
+  /**
+   * Core method: getOrCreate handles both existing and new sessions
+   * Works for sessionIds that exist, don't exist, or auto-generated IDs
+   */
+  async getOrCreate(sessionId?: string): Promise<SessionState<TData>> {
+    // If we already have a session and no sessionId specified, return it
+    if (this.currentSession && !sessionId) {
+      return this.currentSession;
+    }
+
+    // If sessionId provided, try to load it first
+    if (sessionId && this.persistenceManager) {
+      try {
+        const session = await this.persistenceManager.loadSessionState(
+          sessionId
+        );
+        if (session) {
+          this.currentSession = session;
+          return session;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      } catch (_error) {
+        // Session doesn't exist, will create new one with this ID
+      }
+    }
+
+    // Create new session (with provided ID or auto-generated)
+    return this.create(sessionId);
+  }
+
+  /**
+   * Create a new session with optional custom ID
+   */
+  private async create(sessionId?: string): Promise<SessionState<TData>> {
+    const id =
+      sessionId ||
+      `session_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+
+    const session: SessionState<TData> = {
+      id,
+      data: {} as Partial<TData>,
+      dataByRoute: {},
+      routeHistory: [],
+      history: [], // Session manages its own history
+      metadata: {
+        createdAt: new Date(),
+        lastUpdatedAt: new Date(),
+      },
+    };
+
+    this.currentSession = session;
+
+    // Save to persistence if available
+    if (this.persistenceManager) {
+      await this.persistenceManager.saveSessionState(session.id, session);
+    }
+
+    return session;
+  }
+
+  /**
+   * Add a message to the session history
+   */
+  async addMessage(
+    role: "user" | "assistant",
+    content: string,
+    name?: string
+  ): Promise<void> {
+    const session = await this.getOrCreate();
+
+    if (!session.history) {
+      session.history = [];
+    }
+
+    const historyItem: HistoryItem = {
+      role,
+      content,
+      ...(name && { name }),
+    };
+
+    session.history.push(historyItem);
+    session.metadata!.lastUpdatedAt = new Date();
+
+    // Auto-save to persistence
+    await this.save();
+  }
+
+  /**
+   * Get the current conversation history
+   */
+  getHistory(): History {
+    return this.currentSession?.history || [];
+  }
+
+  /**
+   * Set the entire conversation history
+   */
+  setHistory(history: History): void {
+    if (this.currentSession) {
+      this.currentSession.history = history ? [...history] : [];
+      this.currentSession.metadata!.lastUpdatedAt = new Date();
+    }
+  }
+
+  /**
+   * Clear all conversation history
+   */
+  clearHistory(): void {
+    if (this.currentSession) {
+      this.currentSession.history = [];
+      this.currentSession.metadata!.lastUpdatedAt = new Date();
+    }
+  }
+
+  /**
+   * Save the current session to persistence
+   */
+  async save(): Promise<void> {
+    if (this.currentSession && this.persistenceManager) {
+      await this.persistenceManager.saveSessionState(
+        this.currentSession.id,
+        this.currentSession
+      );
+    }
+  }
+
+  /**
+   * Delete the current session from persistence
+   */
+  async delete(): Promise<void> {
+    if (this.currentSession && this.persistenceManager) {
+      await this.persistenceManager.deleteSession(this.currentSession.id);
+      this.currentSession = undefined;
+    }
+  }
+
+  /**
+   * Get the current session
+   */
+  get current(): SessionState<TData> | undefined {
+    return this.currentSession;
+  }
+
+  /**
+   * Get the current session ID
+   */
+  get id(): string | undefined {
+    return this.currentSession?.id;
+  }
+
+  /**
+   * Get collected data from the current session
+   */
+  getData<T = TData>(): Partial<T> | undefined {
+    return this.currentSession?.data as unknown as Partial<T> | undefined;
+  }
+
+  /**
+   * Set/merge data into the current session
+   */
+  async setData<T = TData>(data: Partial<T>): Promise<void> {
+    // Ensure session exists
+    await this.getOrCreate();
+
+    if (this.currentSession && data) {
+      this.currentSession.data = {
+        ...this.currentSession.data,
+        ...(data as unknown as Partial<TData>),
+      };
+      this.currentSession.metadata!.lastUpdatedAt = new Date();
+    }
+  }
+
+  /**
+   * Reset the session (creates new session, optionally preserving history)
+   */
+  async reset(preserveHistory = false): Promise<SessionState<TData>> {
+    const oldId = this.currentSession?.id;
+    const history = preserveHistory ? this.currentSession?.history : [];
+
+    // Create new session
+    const newSession = await this.create();
+
+    // Preserve history if requested
+    if (preserveHistory && history) {
+      newSession.history = [...history];
+    }
+
+    // Clean up old session from persistence
+    if (oldId && this.persistenceManager) {
+      await this.persistenceManager.deleteSession(oldId);
+    }
+
+    await this.save();
+    return newSession;
+  }
+
+  /**
+   * Get the persistence manager (for testing purposes)
+   */
+  getPersistenceManager(): PersistenceManager<TData> | undefined {
+    return this.persistenceManager;
+  }
+}

package/src/core/Step.ts

@@ -2,11 +2,18 @@
  * Step in the route DSL
  */
 
-import type { StepRef, TransitionSpec, TransitionResult } from "../types/route";
-import type { Guideline } from "../types/agent";
+import type {
+  StepRef,
+  StepOptions,
+  StepResult,
+  BranchSpec,
+  BranchResult,
+  Guideline,
+  Tool,
+} from "../types";
+import { Template } from "../types/template";
 
-import { END_ROUTE } from "../constants";
-import { Transition } from "./Transition";
+import { END_ROUTE, END_ROUTE_ID } from "../constants";
 import { generateStepId } from "../utils/id";
 
 /**
@@ -14,28 +21,38 @@ import { generateStepId } from "../utils/id";
  */
 export class Step<TContext = unknown, TData = unknown> {
   public readonly id: string;
-  private transitions: Transition<TContext, TData>[] = [];
-  private guidelines: Guideline[] = [];
-  public collectFields?: string[];
+  private nextSteps: Step<TContext, TData>[] = [];
+  private guidelines: Guideline<TContext>[] = [];
+  public readonly routeId: string;
+  public collect?: string[];
+  public description?: string;
+  public when?: Template<TContext, TData>;
   public skipIf?: (data: Partial<TData>) => boolean;
   public requires?: string[];
-  public instructions?: string;
-
-  constructor(
-    public readonly routeId: string,
-    public description?: string,
-    customId?: string,
-    collectFields?: string[],
-    skipIf?: (data: Partial<TData>) => boolean,
-    requires?: string[],
-    instructions?: string
-  ) {
+  public prompt?: Template<TContext, TData>;
+  public prepare?:
+    | string
+    | Tool<TContext, unknown[], unknown, TData>
+    | ((context: TContext, data?: Partial<TData>) => void | Promise<void>);
+  public finalize?:
+    | string
+    | Tool<TContext, unknown[], unknown, TData>
+    | ((context: TContext, data?: Partial<TData>) => void | Promise<void>);
+  public tools?: (string | Tool<TContext, unknown[], unknown, TData>)[];
+
+  constructor(routeId: string, options: StepOptions<TContext, TData> = {}) {
     // Use provided ID or generate a deterministic one
-    this.id = customId || generateStepId(routeId, description);
-    this.collectFields = collectFields;
-    this.skipIf = skipIf;
-    this.requires = requires;
-    this.instructions = instructions;
+    this.id = options.id || generateStepId(routeId, options.description);
+    this.routeId = routeId;
+    this.description = options.description;
+    this.collect = options.collect;
+    this.skipIf = options.skipIf;
+    this.requires = options.requires;
+    this.prompt = options.prompt;
+    this.when = options.when;
+    this.prepare = options.prepare;
+    this.finalize = options.finalize;
+    this.tools = options.tools;
   }
 
   /**
@@ -44,16 +61,25 @@ export class Step<TContext = unknown, TData = unknown> {
    */
   configure(config: {
     description?: string;
-    collectFields?: string[];
+    collect?: string[];
     skipIf?: (data: Partial<TData>) => boolean;
     requires?: string[];
-    instructions?: string;
+    prompt?: Template<TContext, TData>;
+    prepare?:
+      | string
+      | Tool<TContext, unknown[], unknown, TData>
+      | ((context: TContext, data?: Partial<TData>) => void | Promise<void>);
+    finalize?:
+      | string
+      | Tool<TContext, unknown[], unknown, TData>
+      | ((context: TContext, data?: Partial<TData>) => void | Promise<void>);
+    tools?: (string | Tool<TContext, unknown[], unknown, TData>)[];
   }): this {
     if (config.description !== undefined) {
       this.description = config.description;
     }
-    if (config.collectFields !== undefined) {
-      this.collectFields = config.collectFields;
+    if (config.collect !== undefined) {
+      this.collect = config.collect;
     }
     if (config.skipIf !== undefined) {
       this.skipIf = config.skipIf;
@@ -61,79 +87,118 @@ export class Step<TContext = unknown, TData = unknown> {
     if (config.requires !== undefined) {
       this.requires = config.requires;
     }
-    if (config.instructions !== undefined) {
-      this.instructions = config.instructions;
+    if (config.prompt !== undefined) {
+      this.prompt = config.prompt;
+    }
+    if (config.prepare !== undefined) {
+      this.prepare = config.prepare;
+    }
+    if (config.finalize !== undefined) {
+      this.finalize = config.finalize;
+    }
+    if (config.tools !== undefined) {
+      this.tools = config.tools;
     }
     return this;
   }
 
+  /**
+   * Shortcut to end the current route
+   *
+   * @param options - Optional step options for the end step
+   * @returns Terminal step result
+   */
+  endRoute(
+    options: Omit<StepOptions<TContext, TData>, "step"> = {}
+  ): StepResult<TContext, TData> {
+    return this.nextStep({
+      ...options,
+      step: END_ROUTE,
+    });
+  }
+
   /**
    * Create a transition from this step to another
    *
-   * @param spec - Transition specification (instructions, tool, or direct step)
-   * @returns TransitionResult that supports chaining
+   * @param spec - Transition specification (prompt, tool, or direct step)
+   * @returns StepResult that supports chaining
    */
-  nextStep(
-    spec: TransitionSpec<TContext, TData>
-  ): TransitionResult<TContext, TData> {
+  nextStep(spec: StepOptions<TContext, TData>): StepResult<TContext, TData> {
     // Handle END_ROUTE
     if (spec.step && typeof spec.step === "symbol" && spec.step === END_ROUTE) {
-      const endTransition = new Transition<TContext, TData>(this.getRef(), {
-        step: END_ROUTE,
-        condition: spec.condition,
-        instructions: spec.instructions,
+      const endStep = new Step<TContext, TData>(this.routeId, {
+        ...spec,
+        id: END_ROUTE_ID,
       });
-      this.transitions.push(endTransition);
-
-      // Return a terminal step reference
+      this.nextSteps.push(endStep);
       return this.createTerminalRef();
     }
 
     // Handle direct step reference
     if (spec.step && typeof spec.step !== "symbol") {
-      const transition = new Transition<TContext, TData>(this.getRef(), spec);
-      this.transitions.push(transition);
-
-      return this.createStepRefWithTransition(spec.step);
+      // This is a bit tricky. We need to find the actual Step instance.
+      // For now, let's assume the user will provide a Step instance directly.
+      // This part might need to be revisited.
     }
 
-    // Create new target step for instructions or tool
-    const targetStep = new Step<TContext, TData>(
-      this.routeId,
-      spec.instructions,
-      spec.id, // Use custom ID if provided
-      spec.collect,
-      spec.skipIf,
-      spec.requires,
-      spec.instructions
-    );
-    const transition = new Transition<TContext, TData>(this.getRef(), spec);
-    transition.setTarget(targetStep);
-
-    this.transitions.push(transition);
+    // Create new target step for prompt or tool
+    const targetStep = new Step<TContext, TData>(this.routeId, spec);
+    this.nextSteps.push(targetStep);
 
     return this.createStepRefWithTransition(targetStep.getRef(), targetStep);
   }
 
+  /**
+   * Create multiple branches from this step
+   *
+   * @param branches - Array of branch specifications
+   * @returns BranchResult mapping branch names to their step results
+   */
+  branch(
+    branches: BranchSpec<TContext, TData>[]
+  ): BranchResult<TContext, TData> {
+    const result = {} as BranchResult<TContext, TData>;
+
+    for (const branchSpec of branches) {
+      // Create step options with optional ID
+      const stepOptions: StepOptions<TContext, TData> = branchSpec.id
+        ? { ...branchSpec.step, id: branchSpec.id }
+        : branchSpec.step;
+
+      // Create a new step for this branch
+      const branchStep = new Step<TContext, TData>(this.routeId, stepOptions);
+      // Add it to our transitions
+      this.nextSteps.push(branchStep);
+      // Create a step result for chaining
+      const branchName: string = branchSpec.name;
+      result[branchName] = this.createStepRefWithTransition(
+        branchStep.getRef(),
+        branchStep
+      );
+    }
+
+    return result;
+  }
+
   /**
    * Add a guideline specific to this step
    */
-  addGuideline(guideline: Guideline): void {
+  addGuideline(guideline: Guideline<TContext>): void {
     this.guidelines.push(guideline);
   }
 
   /**
    * Get guidelines for this step
    */
-  getGuidelines(): Guideline[] {
+  getGuidelines(): Guideline<TContext>[] {
     return [...this.guidelines];
   }
 
   /**
    * Get all transitions from this step
    */
-  getTransitions(): Transition<TContext, TData>[] {
-    return [...this.transitions];
+  getTransitions(): Step<TContext, TData>[] {
+    return [...this.nextSteps];
   }
 
   /**
@@ -168,22 +233,24 @@ export class Step<TContext = unknown, TData = unknown> {
   private createStepRefWithTransition(
     ref: StepRef,
     step?: Step<TContext, TData>
-  ): TransitionResult<TContext, TData> {
+  ): StepResult<TContext, TData> {
     const stepInstance = step || this;
 
     return {
       ...ref,
-      nextStep: (spec: TransitionSpec<TContext, TData>) =>
+      nextStep: (spec: StepOptions<TContext, TData>) =>
         stepInstance.nextStep(spec),
+      branch: (branches: BranchSpec<TContext, TData>[]) =>
+        stepInstance.branch(branches),
     };
   }
 
   /**
    * Create a terminal step reference (for END_ROUTE)
    */
-  private createTerminalRef(): TransitionResult<TContext, TData> {
+  private createTerminalRef(): StepResult<TContext, TData> {
     const terminalRef: StepRef = {
-      id: "END",
+      id: END_ROUTE_ID,
       routeId: this.routeId,
     };
 
@@ -192,6 +259,21 @@ export class Step<TContext = unknown, TData = unknown> {
       nextStep: () => {
         throw new Error("Cannot transition from END_ROUTE step");
       },
+      branch: () => {
+        throw new Error("Cannot branch from END_ROUTE step");
+      },
+    };
+  }
+
+  /**
+   * Create a transition result for this step
+   */
+  asStepResult(): StepResult<TContext, TData> {
+    return {
+      ...this.getRef(),
+      nextStep: (spec: StepOptions<TContext, TData>) => this.nextStep(spec),
+      branch: (branches: BranchSpec<TContext, TData>[]) =>
+        this.branch(branches),
     };
   }
 }

package/src/core/ToolExecutor.ts

@@ -5,48 +5,45 @@
  * The LLM sees the enriched context when generating responses.
  */
 
-import type { Event } from "../types/history";
-import type { ToolRef, ToolContext } from "../types/tool";
+import type { Event, Tool, ToolContext } from "../types";
 
 export interface ToolExecutionResult {
   toolName: string;
   success: boolean;
   data?: unknown;
   contextUpdate?: Record<string, unknown>;
-  collectedUpdate?: Record<string, unknown>;
+  dataUpdate?: Record<string, unknown>;
   error?: string;
 }
 
+export interface ExecuteToolParams<TContext = unknown, TData = unknown> {
+  tool: Tool<TContext, unknown[], unknown>;
+  context: TContext;
+  updateContext: (updates: Partial<TContext>) => Promise<void>;
+  history: Event[];
+  data?: Partial<TData>;
+  toolArguments?: Record<string, unknown>;
+}
+
+export interface ExecuteToolsParams<TContext = unknown, TData = unknown> {
+  tools: Array<Tool<TContext, unknown[], unknown>>;
+  context: TContext;
+  updateContext: (updates: Partial<TContext>) => Promise<void>;
+  history: Event[];
+  data?: Partial<TData>;
+}
+
 export class ToolExecutor<TContext = unknown, TData = unknown> {
   /**
    * Execute a single tool with context and collected data
-   * @param allowedDomains - Array of domain names allowed for this execution context (undefined = all domains allowed)
+   * @param params - Execution parameters
    */
   async executeTool(
-    tool: ToolRef<TContext, unknown[], unknown>,
-    context: TContext,
-    updateContext: (updates: Partial<TContext>) => Promise<void>,
-    history: Event[],
-    data?: Partial<TData>,
-    allowedDomains?: string[]
+    params: ExecuteToolParams<TContext, TData>
   ): Promise<ToolExecutionResult> {
+    const { tool, context, updateContext, history, data, toolArguments } =
+      params;
     try {
-      // Domain enforcement: Check if tool's domain is allowed
-      if (allowedDomains !== undefined && tool.domainName) {
-        // allowedDomains is explicitly set (could be empty array)
-        if (!allowedDomains.includes(tool.domainName)) {
-          throw new Error(
-            `Domain security violation: Tool "${
-              tool.name
-            }" belongs to domain "${
-              tool.domainName
-            }" which is not allowed in this route. Allowed domains: [${allowedDomains.join(
-              ", "
-            )}]`
-          );
-        }
-      }
-
       // Build tool context with collected data
       const toolContext: ToolContext<TContext, TData> = {
         context,
@@ -55,20 +52,20 @@ export class ToolExecutor<TContext = unknown, TData = unknown> {
         data,
       };
 
-      // Execute tool (no arguments - tools read from context/data)
-      const result = await tool.handler(toolContext);
+      // Execute tool
+      const result = await tool.handler(toolContext, toolArguments);
 
       // Return execution result
       return {
-        toolName: tool.name,
+        toolName: tool.id || "unknown",
         success: true,
         data: result.data,
         contextUpdate: result.contextUpdate,
-        collectedUpdate: result.collectedUpdate,
+        dataUpdate: result.dataUpdate,
       };
     } catch (error) {
       return {
-        toolName: tool.name,
+        toolName: tool.id || "unknown",
         success: false,
         error: error instanceof Error ? error.message : String(error),
       };
@@ -77,32 +74,30 @@ export class ToolExecutor<TContext = unknown, TData = unknown> {
 
   /**
    * Execute multiple tools in sequence
-   * @param allowedDomains - Array of domain names allowed for this execution context (undefined = all domains allowed)
+   * @param params - Execution parameters
    */
   async executeTools(
-    tools: Array<ToolRef<TContext, unknown[], unknown>>,
-    context: TContext,
-    updateContext: (updates: Partial<TContext>) => Promise<void>,
-    history: Event[],
-    data?: Partial<TData>,
-    allowedDomains?: string[]
+    params: ExecuteToolsParams<TContext, TData>
   ): Promise<ToolExecutionResult[]> {
+    const { tools, context, updateContext, history, data } = params;
     const results: ToolExecutionResult[] = [];
 
     for (const tool of tools) {
-      const result = await this.executeTool(
+      const result = await this.executeTool({
         tool,
         context,
         updateContext,
         history,
         data,
-        allowedDomains
-      );
+      });
       results.push(result);
 
       // If tool failed, stop execution chain
       if (!result.success) {
-        console.error(`[ToolExecutor] Tool ${tool.name} failed:`, result.error);
+        console.error(
+          `[ToolExecutor] Tool ${tool.id || "unknown"} failed:`,
+          result.error
+        );
         break;
       }