@falai/agent 0.8.1 → 0.9.0-alpha-2

package/src/core/SessionManager.ts

@@ -0,0 +1,265 @@
+/**
+ * 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>, // Agent-level data structure
+      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 agent-level collected data from the current session
+   */
+  getData(): Partial<TData> {
+    return this.currentSession?.data || ({} as Partial<TData>);
+  }
+
+  /**
+   * Set/merge agent-level data into the current session
+   * This updates the single source of truth for all collected data
+   */
+  async setData(data: Partial<TData>): Promise<void> {
+    // Ensure session exists
+    await this.getOrCreate();
+
+    if (this.currentSession && data) {
+      this.currentSession.data = {
+        ...this.currentSession.data,
+        ...data,
+      };
+      this.currentSession.metadata!.lastUpdatedAt = new Date();
+      
+      // Auto-save to persistence
+      await this.save();
+    }
+  }
+
+  /**
+   * Update specific fields in the agent-level data
+   * Provides a more explicit method for data updates
+   */
+  async updateData(updates: Partial<TData>): Promise<void> {
+    await this.setData(updates);
+  }
+
+  /**
+   * Clear all collected data while preserving session structure
+   */
+  async clearData(): Promise<void> {
+    if (this.currentSession) {
+      this.currentSession.data = {} as Partial<TData>;
+      this.currentSession.metadata!.lastUpdatedAt = new Date();
+      
+      // Auto-save to persistence
+      await this.save();
+    }
+  }
+
+  /**
+   * 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,42 @@ 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?: (keyof TData)[];
+  public description?: string;
+  public when?: Template<TContext, TData>;
   public skipIf?: (data: Partial<TData>) => boolean;
-  public requires?: string[];
-  public instructions?: string;
+  public requires?: (keyof TData)[];
+  public prompt?: Template<TContext, TData>;
+  public prepare?:
+    | string
+    | Tool<TContext, TData, unknown[], unknown>
+    | ((context: TContext, data?: Partial<TData>) => void | Promise<void>);
+  public finalize?:
+    | string
+    | Tool<TContext, TData, unknown[], unknown>
+    | ((context: TContext, data?: Partial<TData>) => void | Promise<void>);
+  public tools?: (string | Tool<TContext, TData, unknown[], unknown>)[];
 
   constructor(
-    public readonly routeId: string,
-    public description?: string,
-    customId?: string,
-    collectFields?: string[],
-    skipIf?: (data: Partial<TData>) => boolean,
-    requires?: string[],
-    instructions?: string
+    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,96 +65,148 @@ export class Step<TContext = unknown, TData = unknown> {
    */
   configure(config: {
     description?: string;
-    collectFields?: string[];
+    collect?: (keyof TData)[];
     skipIf?: (data: Partial<TData>) => boolean;
-    requires?: string[];
-    instructions?: string;
+    requires?: (keyof TData)[];
+    prompt?: Template<TContext, TData>;
+    prepare?:
+      | string
+      | Tool<TContext, TData, unknown[], unknown>
+      | ((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>)[];
   }): 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;
     }
+    
     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];
   }
 
   /**
@@ -149,7 +222,7 @@ export class Step<TContext = unknown, TData = unknown> {
    */
   hasRequires(data: Partial<TData>): boolean {
     if (!this.requires || this.requires.length === 0) return true;
-    return this.requires.every((key) => data[key as keyof TData] !== undefined);
+    return this.requires.every((key) => data[key] !== undefined);
   }
 
   /**
@@ -168,22 +241,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 +267,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),
     };
   }
 }