@falai/agent 0.1.5 → 0.3.0

package/examples/persistent-onboarding.ts

@@ -0,0 +1,464 @@
+/**
+ * Persistent multi-turn onboarding agent example
+ * Demonstrates context lifecycle management for stateful conversations
+ */
+
+import {
+  Agent,
+  defineTool,
+  GeminiProvider,
+  END_ROUTE,
+  EventSource,
+  createMessageEvent,
+  type ContextLifecycleHooks,
+} from "../src/index";
+
+// ============================================================================
+// DATABASE SIMULATION
+// ============================================================================
+
+interface SessionData {
+  sessionId: string;
+  userId: string;
+  collectedData: {
+    businessName?: string;
+    businessDescription?: string;
+    industry?: string;
+    contactEmail?: string;
+  };
+  completedSteps: string[];
+  lastUpdated: Date;
+}
+
+// Simple in-memory database simulation
+const database = new Map<string, SessionData>();
+
+const db = {
+  sessions: {
+    async findById(sessionId: string): Promise<SessionData | undefined> {
+      return database.get(sessionId);
+    },
+
+    async update(
+      sessionId: string,
+      updates: Partial<SessionData>
+    ): Promise<void> {
+      const existing = database.get(sessionId);
+      if (existing) {
+        database.set(sessionId, {
+          ...existing,
+          ...updates,
+          lastUpdated: new Date(),
+        });
+      }
+    },
+
+    async create(sessionData: SessionData): Promise<void> {
+      database.set(sessionData.sessionId, sessionData);
+    },
+  },
+};
+
+// ============================================================================
+// CONTEXT TYPE
+// ============================================================================
+
+interface OnboardingContext {
+  sessionId: string;
+  userId: string;
+  userName?: string;
+  collectedData: {
+    businessName?: string;
+    businessDescription?: string;
+    industry?: string;
+    contactEmail?: string;
+  };
+  completedSteps: string[];
+}
+
+// ============================================================================
+// AGENT FACTORY WITH LIFECYCLE HOOKS
+// ============================================================================
+
+/**
+ * Creates an onboarding agent with persistent context management
+ *
+ * PATTERN 1: Factory + Lifecycle Hooks
+ * - Load fresh context from database before each response
+ * - Persist context updates automatically after changes
+ */
+async function createPersistentOnboardingAgent(sessionId: string) {
+  // Load session from database
+  const session = await db.sessions.findById(sessionId);
+
+  if (!session) {
+    throw new Error(`Session ${sessionId} not found`);
+  }
+
+  // Define lifecycle hooks for automatic persistence
+  const hooks: ContextLifecycleHooks<OnboardingContext> = {
+    // Called before respond() - load fresh context from database
+    beforeRespond: async (currentContext) => {
+      console.log("🔄 Loading fresh context from database...");
+      const freshSession = await db.sessions.findById(sessionId);
+
+      if (!freshSession) {
+        return currentContext; // Fallback to current
+      }
+
+      return {
+        sessionId: freshSession.sessionId,
+        userId: freshSession.userId,
+        collectedData: freshSession.collectedData,
+        completedSteps: freshSession.completedSteps,
+      };
+    },
+
+    // Called after context updates - persist to database
+    onContextUpdate: async (newContext) => {
+      console.log("💾 Persisting context update to database...");
+      await db.sessions.update(sessionId, {
+        collectedData: newContext.collectedData,
+        completedSteps: newContext.completedSteps,
+      });
+    },
+  };
+
+  const provider = new GeminiProvider({
+    apiKey: process.env.GEMINI_API_KEY || "test-key",
+    model: "models/gemini-2.5-flash",
+  });
+
+  const agent = new Agent<OnboardingContext>({
+    name: "OnboardingBot",
+    description: "A friendly assistant that helps businesses get started",
+    goal: "Collect business information efficiently while being conversational",
+    ai: provider,
+    context: {
+      sessionId: session.sessionId,
+      userId: session.userId,
+      collectedData: session.collectedData,
+      completedSteps: session.completedSteps,
+    },
+    hooks, // Enable lifecycle hooks for persistence
+  });
+
+  // ============================================================================
+  // TOOLS (with context updates)
+  // ============================================================================
+
+  // OPTION 1: Using contextUpdate in return value
+  const saveBusinessInfo = defineTool<
+    OnboardingContext,
+    [name: string, description: string],
+    boolean
+  >(
+    "save_business_info",
+    async (toolContext, name, description) => {
+      console.log(`📝 Saving business info: ${name}`);
+
+      return {
+        data: true,
+        // Context update is automatically persisted via onContextUpdate hook
+        contextUpdate: {
+          collectedData: {
+            ...toolContext.context.collectedData,
+            businessName: name,
+            businessDescription: description,
+          },
+          completedSteps: [
+            ...toolContext.context.completedSteps,
+            "business_info",
+          ],
+        },
+      };
+    },
+    {
+      description: "Save business name and description",
+    }
+  );
+
+  // OPTION 2: Using updateContext method directly
+  const saveIndustry = defineTool<
+    OnboardingContext,
+    [industry: string],
+    boolean
+  >(
+    "save_industry",
+    async (toolContext, industry) => {
+      console.log(`🏭 Saving industry: ${industry}`);
+
+      // Direct context update (triggers onContextUpdate hook)
+      await toolContext.updateContext({
+        collectedData: {
+          ...toolContext.context.collectedData,
+          industry,
+        },
+        completedSteps: [...toolContext.context.completedSteps, "industry"],
+      });
+
+      return { data: true };
+    },
+    {
+      description: "Save business industry",
+    }
+  );
+
+  const saveContactEmail = defineTool<
+    OnboardingContext,
+    [email: string],
+    boolean
+  >(
+    "save_contact_email",
+    async (toolContext, email) => {
+      console.log(`📧 Saving contact email: ${email}`);
+
+      await toolContext.updateContext({
+        collectedData: {
+          ...toolContext.context.collectedData,
+          contactEmail: email,
+        },
+        completedSteps: [...toolContext.context.completedSteps, "contact"],
+      });
+
+      return { data: true };
+    },
+    {
+      description: "Save contact email",
+    }
+  );
+
+  // ============================================================================
+  // ONBOARDING ROUTE
+  // ============================================================================
+
+  const onboardingRoute = agent.createRoute({
+    title: "Business Onboarding",
+    description: "Guide user through business information collection",
+    conditions: ["User is onboarding their business"],
+  });
+
+  // Step 1: Collect business info
+  const askBusinessInfo = onboardingRoute.initialState.transitionTo({
+    chatState: "Ask for business name and a brief description",
+  });
+
+  const saveBusinessStep = askBusinessInfo.transitionTo({
+    toolState: saveBusinessInfo,
+  });
+
+  // Step 2: Collect industry
+  const askIndustry = saveBusinessStep.transitionTo({
+    chatState: "Ask what industry the business operates in",
+  });
+
+  const saveIndustryStep = askIndustry.transitionTo({
+    toolState: saveIndustry,
+  });
+
+  // Step 3: Collect contact
+  const askContact = saveIndustryStep.transitionTo({
+    chatState: "Ask for their contact email",
+  });
+
+  const saveContactStep = askContact.transitionTo({
+    toolState: saveContactEmail,
+  });
+
+  // Step 4: Confirmation
+  const confirm = saveContactStep.transitionTo({
+    chatState: "Summarize all collected information and ask for confirmation",
+  });
+
+  confirm.transitionTo({ state: END_ROUTE });
+
+  // Guidelines
+  onboardingRoute.createGuideline({
+    condition: "User provides invalid email format",
+    action: "Politely ask for a valid email address",
+    tags: ["validation"],
+  });
+
+  onboardingRoute.createGuideline({
+    condition: "User wants to skip a step",
+    action: "Explain why the information is important but allow them to skip",
+    tags: ["flexibility"],
+  });
+
+  agent.createGuideline({
+    condition: "User asks to start over",
+    action:
+      "Confirm they want to clear their progress, then restart the onboarding",
+    tags: ["reset"],
+  });
+
+  return agent;
+}
+
+// ============================================================================
+// ALTERNATIVE PATTERN: CONTEXT PROVIDER
+// ============================================================================
+
+/**
+ * Creates an onboarding agent using the contextProvider pattern
+ *
+ * PATTERN 2: Context Provider (Always Fresh)
+ * - Context is fetched fresh on every respond() call
+ * - No need for beforeRespond hook
+ * - Still use onContextUpdate for persistence
+ */
+async function createOnboardingAgentWithProvider(sessionId: string) {
+  const provider = new GeminiProvider({
+    apiKey: process.env.GEMINI_API_KEY || "test-key",
+    model: "models/gemini-2.5-flash",
+  });
+
+  const agent = new Agent<OnboardingContext>({
+    name: "OnboardingBot",
+    description: "A friendly assistant that helps businesses get started",
+    ai: provider,
+
+    // Context is always fetched fresh from database
+    contextProvider: async () => {
+      const session = await db.sessions.findById(sessionId);
+      if (!session) {
+        throw new Error(`Session ${sessionId} not found`);
+      }
+
+      return {
+        sessionId: session.sessionId,
+        userId: session.userId,
+        collectedData: session.collectedData,
+        completedSteps: session.completedSteps,
+      };
+    },
+
+    // Still persist updates
+    hooks: {
+      onContextUpdate: async (newContext) => {
+        await db.sessions.update(sessionId, {
+          collectedData: newContext.collectedData,
+          completedSteps: newContext.completedSteps,
+        });
+      },
+    },
+  });
+
+  // ... rest of agent setup (same as above)
+
+  return agent;
+}
+
+// ============================================================================
+// USAGE EXAMPLE
+// ============================================================================
+
+async function main() {
+  const sessionId = "session_123";
+  const userId = "user_456";
+
+  // Initialize session in database
+  await db.sessions.create({
+    sessionId,
+    userId,
+    collectedData: {},
+    completedSteps: [],
+    lastUpdated: new Date(),
+  });
+
+  console.log("=== MULTI-TURN CONVERSATION SIMULATION ===\n");
+
+  // Turn 1: Start onboarding
+  console.log("📱 Turn 1: User starts onboarding");
+  const agent1 = await createPersistentOnboardingAgent(sessionId);
+  const response1 = await agent1.respond({
+    history: [
+      createMessageEvent(
+        EventSource.CUSTOMER,
+        "Alice",
+        "Hi, I want to onboard my business"
+      ),
+    ],
+  });
+  console.log("🤖 Bot:", response1.message);
+  console.log("📊 Context after turn 1:", agent1["context"]);
+  console.log();
+
+  // Turn 2: User provides business info
+  // NOTE: We create a NEW agent instance - context is loaded from database
+  console.log("📱 Turn 2: User provides business info");
+  const agent2 = await createPersistentOnboardingAgent(sessionId);
+  const response2 = await agent2.respond({
+    history: [
+      createMessageEvent(
+        EventSource.CUSTOMER,
+        "Alice",
+        "My business is called 'TechFlow' and we build AI-powered workflow automation tools"
+      ),
+    ],
+  });
+  console.log("🤖 Bot:", response2.message);
+  console.log("📊 Context after turn 2:", agent2["context"]);
+  console.log();
+
+  // Turn 3: User provides industry
+  console.log("📱 Turn 3: User provides industry");
+  const agent3 = await createPersistentOnboardingAgent(sessionId);
+  const response3 = await agent3.respond({
+    history: [
+      createMessageEvent(
+        EventSource.CUSTOMER,
+        "Alice",
+        "We're in the SaaS industry"
+      ),
+    ],
+  });
+  console.log("🤖 Bot:", response3.message);
+  console.log("📊 Context after turn 3:", agent3["context"]);
+  console.log();
+
+  // Verify persistence
+  console.log("=== PERSISTENCE VERIFICATION ===");
+  const finalSession = await db.sessions.findById(sessionId);
+  console.log(
+    "💾 Final persisted session:",
+    JSON.stringify(finalSession, null, 2)
+  );
+}
+
+// ============================================================================
+// KEY PATTERNS DEMONSTRATED
+// ============================================================================
+
+/*
+ * ✅ PATTERN 1: Lifecycle Hooks (Recommended for most cases)
+ *    - beforeRespond: Load fresh context before each response
+ *    - onContextUpdate: Persist context after updates
+ *    - Works with both static context and updates
+ *
+ * ✅ PATTERN 2: Context Provider (For always-fresh context)
+ *    - contextProvider: Function that returns fresh context
+ *    - onContextUpdate: Still needed for persistence
+ *    - Best when context is always loaded from external source
+ *
+ * ✅ PATTERN 3: Tool Context Updates (Two options)
+ *    - Option A: Return { data, contextUpdate } in tool result
+ *    - Option B: Call toolContext.updateContext() directly
+ *    - Both trigger onContextUpdate hook automatically
+ *
+ * ✅ PATTERN 4: Explicit Updates
+ *    - agent.updateContext() for manual updates
+ *    - Triggers onContextUpdate hook
+ *    - Useful outside of tool execution
+ *
+ * ❌ ANTI-PATTERN: Caching Agents
+ *    - DON'T cache agent instances across requests
+ *    - DO recreate agents with fresh context
+ *    - Context gets stale if agent is cached
+ */
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch(console.error);
+}
+
+export { createPersistentOnboardingAgent, createOnboardingAgentWithProvider };

package/examples/travel-agent.ts

@@ -162,20 +162,20 @@ async function createTravelAgent() {
     chatState: "Ask about the destination",
   });
 
-  const t1 = t0.target.transitionTo({
+  const t1 = t0.transitionTo({
     chatState: "Ask about preferred travel dates",
   });
 
-  const t2 = t1.target.transitionTo({
+  const t2 = t1.transitionTo({
     toolState: getAvailableFlights,
   });
 
-  const t3 = t2.target.transitionTo({
+  const t3 = t2.transitionTo({
     chatState: "Present available flights and ask which one works for them",
   });
 
   // Happy path: customer selects a flight
-  const t4 = t3.target.transitionTo(
+  const t4 = t3.transitionTo(
     {
       chatState:
         "Collect passenger information and confirm booking details before proceeding",
@@ -183,41 +183,41 @@ async function createTravelAgent() {
     "The customer selects a flight"
   );
 
-  const t5 = t4.target.transitionTo(
+  const t5 = t4.transitionTo(
     {
       toolState: bookFlight,
     },
     "The customer confirms the booking details"
   );
 
-  const t6 = t5.target.transitionTo({
+  const t6 = t5.transitionTo({
     chatState: "Provide confirmation number and booking summary",
   });
 
-  t6.target.transitionTo({ state: END_ROUTE });
+  t6.transitionTo({ state: END_ROUTE });
 
   // Alternative path: no flights work
-  const t7 = t3.target.transitionTo(
+  const t7 = t3.transitionTo(
     {
       toolState: getAlternativeFlights,
     },
     "None of the flights work for the customer"
   );
 
-  const t8 = t7.target.transitionTo({
+  const t8 = t7.transitionTo({
     chatState: "Present alternative flights and ask if any work",
   });
 
   // Link back to happy path
-  t8.target.transitionTo(
+  t8.transitionTo(
     {
-      state: t4.target,
+      state: t4,
     },
     "The customer selects a flight"
   );
 
   // No alternative flights work either
-  const t9 = t8.target.transitionTo(
+  const t9 = t8.transitionTo(
     {
       chatState:
         "Suggest calling our office or visiting our website for more options",
@@ -225,7 +225,7 @@ async function createTravelAgent() {
     "None of the alternative flights work either"
   );
 
-  t9.target.transitionTo({ state: END_ROUTE });
+  t9.transitionTo({ state: END_ROUTE });
 
   // Add route-specific guidelines
   flightBookingRoute.createGuideline({
@@ -253,11 +253,11 @@ async function createTravelAgent() {
     chatState: "Ask for the confirmation number or booking reference",
   });
 
-  const s1 = s0.target.transitionTo({
+  const s1 = s0.transitionTo({
     toolState: getBookingStatus,
   });
 
-  s1.target.transitionTo(
+  s1.transitionTo(
     {
       chatState:
         "Tell the customer that the booking could not be found and ask them to verify the confirmation number or call the office",
@@ -265,7 +265,7 @@ async function createTravelAgent() {
     "The booking could not be found"
   );
 
-  s1.target.transitionTo(
+  s1.transitionTo(
     {
       chatState:
         "Provide the booking details and confirm everything is in order",
@@ -273,7 +273,7 @@ async function createTravelAgent() {
     "The booking is confirmed and all details are correct"
   );
 
-  s1.target.transitionTo(
+  s1.transitionTo(
     {
       chatState:
         "Present the booking information and mention any issues or pending actions required",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "0.1.5",
+  "version": "0.3.0",
   "description": "Standalone, strongly-typed AI Agent framework with route DSL and AI provider strategy",
   "type": "module",
   "main": "./dist/cjs/index.js",

package/src/core/Agent.ts

@@ -27,6 +27,7 @@ export class Agent<TContext = unknown> {
   private routes: Route<TContext>[] = [];
   private observations: Observation[] = [];
   private domainRegistry = new DomainRegistry();
+  private context: TContext | undefined;
 
   /**
    * Dynamic domain property - populated via addDomain
@@ -39,6 +40,16 @@ export class Agent<TContext = unknown> {
       this.options.maxEngineIterations = 1;
     }
 
+    // Validate context configuration
+    if (options.context !== undefined && options.contextProvider) {
+      throw new Error(
+        "Cannot provide both 'context' and 'contextProvider'. Choose one."
+      );
+    }
+
+    // Initialize context if provided
+    this.context = options.context;
+
     // Initialize from options
     if (options.terms) {
       this.terms = [...options.terms];
@@ -167,6 +178,39 @@ export class Agent<TContext = unknown> {
     this.domain[name] = domainObject;
   }
 
+  /**
+   * Update the agent's context
+   * Triggers the onContextUpdate lifecycle hook if configured
+   */
+  async updateContext(updates: Partial<TContext>): Promise<void> {
+    const previousContext = this.context;
+
+    // Merge updates with current context
+    this.context = {
+      ...(this.context as Record<string, unknown>),
+      ...(updates as Record<string, unknown>),
+    } as TContext;
+
+    // Trigger lifecycle hook if configured
+    if (this.options.hooks?.onContextUpdate && previousContext !== undefined) {
+      await this.options.hooks.onContextUpdate(this.context, previousContext);
+    }
+  }
+
+  /**
+   * Get current context (fetches from provider if configured)
+   * @internal
+   */
+  private async getContext(): Promise<TContext | undefined> {
+    // If context provider is configured, use it to fetch fresh context
+    if (this.options.contextProvider) {
+      return await this.options.contextProvider();
+    }
+
+    // Otherwise return the stored context
+    return this.context;
+  }
+
   /**
    * Generate a response based on history and context
    */
@@ -183,9 +227,19 @@ export class Agent<TContext = unknown> {
   }> {
     const { history, contextOverride, signal } = params;
 
-    // Merge context
+    // Get current context (may fetch from provider)
+    let currentContext = await this.getContext();
+
+    // Call beforeRespond hook if configured
+    if (this.options.hooks?.beforeRespond && currentContext !== undefined) {
+      currentContext = await this.options.hooks.beforeRespond(currentContext);
+      // Update stored context with the result from beforeRespond
+      this.context = currentContext;
+    }
+
+    // Merge context with override
     const effectiveContext = {
-      ...(this.options.context as Record<string, unknown>),
+      ...(currentContext as Record<string, unknown>),
       ...(contextOverride as Record<string, unknown>),
     } as TContext;