@falai/agent 0.9.2 → 1.0.1

package/docs/guides/migration/multi-step-execution.md

@@ -0,0 +1,373 @@
+# Multi-Step Execution Migration Guide
+
+This guide covers the behavioral changes from single-step to multi-step execution and provides migration guidance for existing routes.
+
+## Breaking Changes in v1.0.0
+
+### History API Simplified
+
+The `createMessageEvent` and `EventSource` exports have been replaced with simpler helper functions:
+
+**Before (v0.x):**
+```typescript
+import { createMessageEvent, EventSource } from "@falai/agent";
+
+const history = [
+  createMessageEvent(EventSource.CUSTOMER, "Hello"),
+  createMessageEvent(EventSource.AI_AGENT, "Hi there!"),
+];
+```
+
+**After (v1.0.0):**
+```typescript
+import { userMessage, assistantMessage } from "@falai/agent";
+
+const history = [
+  userMessage("Hello"),
+  assistantMessage("Hi there!"),
+];
+```
+
+The history is now a simple array of objects with `role` and `content` properties:
+
+```typescript
+// Available helper functions
+import { 
+  userMessage,      // (content, name?) => { role: "user", content, name? }
+  assistantMessage, // (content, toolCalls?) => { role: "assistant", content, tool_calls? }
+  toolMessage,      // (toolCallId, name, content) => { role: "tool", ... }
+  systemMessage,    // (content) => { role: "system", content }
+} from "@falai/agent";
+
+// Or create history items directly
+const history = [
+  { role: "user", content: "Hello" },
+  { role: "assistant", content: "Hi there!" },
+];
+```
+
+### StepOptions: `instructions` → `prompt`
+
+The `instructions` property in `StepOptions` has been renamed to `prompt`:
+
+**Before:**
+```typescript
+steps: [
+  {
+    id: "greeting",
+    instructions: "Greet the user warmly",
+  }
+]
+```
+
+**After:**
+```typescript
+steps: [
+  {
+    id: "greeting",
+    prompt: "Greet the user warmly",
+  }
+]
+```
+
+---
+
+## Overview
+
+Multi-step execution is a **major behavioral change** that allows multiple consecutive steps to execute in a single LLM call. While the public API shape remains compatible, the execution semantics differ from the previous single-step model.
+
+## Key Behavioral Changes
+
+### Before: Single-Step Execution
+
+Previously, each `.respond()` call executed exactly one step:
+
+```typescript
+// Turn 1
+const response1 = await agent.respond("Book Grand Hotel for 2 on Friday");
+// Executes: ask-hotel step
+// Response: "What date would you like to book?"
+
+// Turn 2
+const response2 = await agent.respond("Friday");
+// Executes: ask-date step
+// Response: "How many guests?"
+
+// Turn 3
+const response3 = await agent.respond("2 people");
+// Executes: ask-guests step
+// Response: "Booking confirmed!"
+
+// Total: 3 LLM calls
+```
+
+### After: Multi-Step Execution
+
+Now, multiple steps can execute in a single call when data requirements are satisfied:
+
+```typescript
+// Turn 1
+const response = await agent.respond("Book Grand Hotel for 2 on Friday");
+// Pre-extraction captures: { hotel: "Grand Hotel", date: "Friday", guests: 2 }
+// Executes: ask-hotel, ask-date, ask-guests steps (all in one batch)
+// Response: "Booking confirmed for 2 guests at Grand Hotel on Friday!"
+
+// Total: 1 LLM call
+```
+
+## What Changed
+
+| Aspect | Before | After |
+|--------|--------|-------|
+| Steps per call | Always 1 | 1 or more (batched) |
+| LLM calls | One per step | One per batch |
+| Pre-extraction | Per-step | Before batch determination |
+| Response fields | Basic | Includes `executedSteps`, `stoppedReason` |
+| Hook execution | Per-step | All prepare hooks, then LLM, then all finalize hooks |
+
+## Migration Checklist
+
+### 1. Review Hook Dependencies
+
+If your hooks depend on being called between steps, they may need adjustment:
+
+```typescript
+// Before: Hooks called between each step
+const step1 = {
+  finalize: async (ctx, data) => {
+    // This ran before step2's prepare
+    await saveProgress(data);
+  }
+};
+
+const step2 = {
+  prepare: async (ctx, data) => {
+    // This expected step1's finalize to have run
+    const progress = await loadProgress();
+  }
+};
+
+// After: All prepare hooks run first, then all finalize hooks
+// If step1 and step2 are batched together:
+// 1. step1.prepare runs
+// 2. step2.prepare runs
+// 3. LLM call
+// 4. step1.finalize runs
+// 5. step2.finalize runs
+
+// Migration: Use session data instead of external state
+const step1 = {
+  finalize: async (ctx, data) => {
+    // Store in session data, not external state
+    data.step1Complete = true;
+  }
+};
+
+const step2 = {
+  prepare: async (ctx, data) => {
+    // Check session data
+    if (!data.step1Complete) {
+      // Handle case where step1 hasn't finalized yet
+    }
+  }
+};
+```
+
+### 2. Update Response Handling
+
+Check for new response fields:
+
+```typescript
+// Before
+const response = await agent.respond(message);
+console.log(response.message);
+console.log(response.isRouteComplete);
+
+// After - additional fields available
+const response = await agent.respond(message);
+console.log(response.message);
+console.log(response.isRouteComplete);
+console.log(response.executedSteps);    // NEW: Array of executed steps
+console.log(response.stoppedReason);    // NEW: Why execution stopped
+console.log(response.error);            // NEW: Error details if any
+```
+
+### 3. Review SkipIf Conditions
+
+SkipIf conditions now affect batch determination:
+
+```typescript
+// Before: skipIf evaluated when entering step
+const step = {
+  skipIf: (data) => {
+    // Called when transitioning to this step
+    return data.alreadyHaveInfo;
+  }
+};
+
+// After: skipIf evaluated during batch determination
+// If skipIf returns true, step is skipped and next step is evaluated
+// If skipIf throws, step is treated as non-skippable (included in batch)
+
+// Migration: Ensure skipIf is pure and doesn't have side effects
+const step = {
+  skipIf: (data) => {
+    // GOOD: Pure function
+    return data.alreadyHaveInfo;
+  }
+};
+
+// AVOID: Side effects in skipIf
+const badStep = {
+  skipIf: (data) => {
+    // BAD: Side effect
+    logSkipCheck(data);
+    return data.alreadyHaveInfo;
+  }
+};
+```
+
+### 4. Handle Partial Execution
+
+Errors may leave partial progress:
+
+```typescript
+// Before: Single step, all or nothing
+
+// After: Batch may partially complete
+const response = await agent.respond(message);
+
+if (response.stoppedReason === 'prepare_error') {
+  // Some steps may have executed before the error
+  console.log("Executed before error:", response.executedSteps);
+  console.log("Error details:", response.error);
+}
+```
+
+### 5. Update Tests
+
+Tests expecting single-step behavior need updates:
+
+```typescript
+// Before
+test("collects hotel name", async () => {
+  const response = await agent.respond("Book Grand Hotel");
+  expect(response.session.data.hotel).toBe("Grand Hotel");
+  // Assumed only hotel step executed
+});
+
+// After
+test("collects hotel name", async () => {
+  const response = await agent.respond("Book Grand Hotel");
+  expect(response.session.data.hotel).toBe("Grand Hotel");
+  
+  // Check which steps actually executed
+  expect(response.executedSteps).toContainEqual(
+    expect.objectContaining({ id: "ask-hotel" })
+  );
+  
+  // May have executed more steps if data was available
+  expect(response.stoppedReason).toBe("needs_input");
+});
+```
+
+## Before/After Examples
+
+### Example 1: Simple Booking Flow
+
+**Before (3 turns):**
+```
+User: "I want to book a hotel"
+Bot: "Which hotel would you like?"
+User: "Grand Hotel"
+Bot: "What date?"
+User: "Friday"
+Bot: "Booking confirmed!"
+```
+
+**After (potentially 1-2 turns):**
+```
+User: "I want to book Grand Hotel for Friday"
+Bot: "Booking confirmed for Grand Hotel on Friday!"
+```
+
+### Example 2: Partial Information
+
+**Before:**
+```
+User: "Book Grand Hotel"
+Bot: "What date?" (only hotel step executed)
+```
+
+**After:**
+```
+User: "Book Grand Hotel"
+Bot: "What date?" (hotel step executed, stopped at date step)
+// response.executedSteps = [{ id: "ask-hotel" }]
+// response.stoppedReason = "needs_input"
+```
+
+### Example 3: With SkipIf Conditions
+
+**Before:**
+```typescript
+// Each step evaluated individually
+const step1 = { skipIf: (d) => !!d.name };  // Skipped if name exists
+const step2 = { skipIf: (d) => !!d.email }; // Skipped if email exists
+```
+
+**After:**
+```typescript
+// All skipIf conditions evaluated during batch determination
+// If user provides "I'm John, john@example.com":
+// - Pre-extraction: { name: "John", email: "john@example.com" }
+// - step1 skipIf: true (skipped)
+// - step2 skipIf: true (skipped)
+// - Both steps skipped, route may complete immediately
+```
+
+## Opting Out of Batching
+
+If you need single-step behavior for specific steps, use `requires` to create dependencies:
+
+```typescript
+// Force step2 to wait for step1's data
+const step1 = {
+  collect: ["name"],
+};
+
+const step2 = {
+  collect: ["email"],
+  requires: ["name"], // Won't batch with step1
+};
+
+// Now step2 will only execute after step1 completes
+// (in a separate batch/LLM call)
+```
+
+## Debugging Migration Issues
+
+Enable debug mode to see batch behavior:
+
+```typescript
+const agent = new Agent({
+  debug: true,
+  // ...
+});
+
+// Logs will show:
+// [BatchExecutor] Starting batch determination...
+// [BatchExecutor] Including step ask-hotel in batch
+// [BatchExecutor] Step ask-date needs input, stopping batch
+```
+
+## Summary
+
+1. **Multiple steps can now execute together** - reducing LLM calls
+2. **Pre-extraction happens before batch determination** - maximizing batching
+3. **New response fields** - `executedSteps`, `stoppedReason`, `error`
+4. **Hook execution order changed** - all prepare, then LLM, then all finalize
+5. **SkipIf affects batching** - evaluated during batch determination
+6. **Partial progress preserved** - on errors, completed steps are retained
+
+The changes improve efficiency and UX while maintaining API compatibility. Most existing code will work without changes, but reviewing hook dependencies and test expectations is recommended.

package/examples/advanced-patterns/knowledge-based-agent.ts

@@ -8,6 +8,12 @@
  * 3. Session step management even for stepless conversations
  * 4. Always-on routing with context awareness
  * 5. Three-phase pipeline: PREPARATION → ROUTING → RESPONSE
+ * 6. NEW: Complex ConditionTemplate patterns for intelligent routing:
+ *    - Mixed conditions: ["AI context", (ctx) => programmatic_check]
+ *    - Route skipIf: Dynamic route exclusion based on message content
+ *    - Function-only conditions: (ctx) => sophisticated_logic
+ *    - String-only conditions: "simple AI context"
+ *    - Fallback routing with programmatic logic
  */
 
 import {
@@ -119,7 +125,7 @@ const searchKnowledgeTool: Tool<CompanyContext, UnifiedData> = {
     ).message.toLowerCase();
 
     // Simple keyword matching (in real app, use vector search)
-    const relevantFaqs = context.context.faqs.filter(
+    const relevantFaqs = toolContext.context.faqs.filter(
       (faq) =>
         faq.question.toLowerCase().includes(query) ||
         faq.answer.toLowerCase().includes(query)
@@ -262,12 +268,25 @@ const agent = new Agent<CompanyContext, UnifiedData>({
 agent.createRoute({
   title: "Company Information",
   description: "Answer general questions about Acme Corp",
-  conditions: [
+  // Mixed condition: AI context + programmatic validation
+  when: [
     "User asks about the company",
     "Questions about company history, size, location",
     "When was the company founded",
     "How many employees",
     "Where is the headquarters",
+    (ctx) => {
+      const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+      return message.includes('company') || message.includes('acme') || message.includes('founded');
+    }
+  ],
+  // Skip if user is asking about specific products instead
+  skipIf: [
+    "user is asking about specific products or services",
+    (ctx) => {
+      const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+      return message.includes('widget') || message.includes('gadget') || message.includes('product');
+    }
   ],
   // Route-specific knowledge base for company information
   knowledgeBase: {
@@ -299,12 +318,18 @@ agent.createRoute({
 agent.createRoute({
   title: "Product Information",
   description: "Answer questions about products",
-  conditions: [
-    "User asks about products",
-    "Questions about features, pricing, availability",
-    "What products do you offer",
-    "Tell me about your widgets",
-  ],
+  // Function-only condition for programmatic logic
+  when: (ctx) => {
+    const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+    return message.includes('product') || message.includes('widget') || 
+           message.includes('gadget') || message.includes('price') || 
+           message.includes('feature');
+  },
+  // Skip if user is asking about company policies instead
+  skipIf: (ctx) => {
+    const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+    return message.includes('policy') || message.includes('return') || message.includes('warranty');
+  },
   // NO schema - just answering questions
 });
 
@@ -315,11 +340,25 @@ agent.createRoute({
 agent.createRoute({
   title: "Policy Information",
   description: "Answer questions about company policies",
-  conditions: [
+  // Mixed condition: AI context + programmatic check
+  when: [
     "User asks about policies",
     "Return policy",
-    "Shipping information",
+    "Shipping information", 
     "Warranty questions",
+    (ctx) => {
+      const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+      return message.includes('policy') || message.includes('return') || 
+             message.includes('shipping') || message.includes('warranty');
+    }
+  ],
+  // Skip if user is asking about news or updates
+  skipIf: [
+    "user wants latest news or updates",
+    (ctx) => {
+      const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+      return message.includes('news') || message.includes('update') || message.includes('new');
+    }
   ],
   // NO schema
 });
@@ -330,12 +369,13 @@ agent.createRoute({
 const newsRoute = agent.createRoute({
   title: "Company News",
   description: "Share latest company news and updates",
-  conditions: [
-    "User asks about news",
-    "What's new",
-    "Recent updates",
-    "Latest announcements",
-  ],
+  // String-only condition for AI context
+  when: "User asks about news, updates, or recent announcements",
+  // Skip if user is asking about general FAQ topics
+  skipIf: (ctx) => {
+    const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+    return message.includes('how do i') || message.includes('can i') || message.includes('is there');
+  },
 });
 
 // Add tool to initial step to fetch news
@@ -351,11 +391,25 @@ fetchNews.nextStep({
 const faqRoute = agent.createRoute({
   title: "FAQ Search",
   description: "Search FAQs for relevant answers",
-  conditions: [
+  // Mixed condition: AI context + programmatic pattern matching
+  when: [
     "User has a question that might be in FAQs",
     "How do I...",
     "Can I...",
     "Is there...",
+    (ctx) => {
+      const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+      return message.startsWith('how ') || message.startsWith('can ') || 
+             message.startsWith('is ') || message.includes('?');
+    }
+  ],
+  // Skip if user is clearly asking for news or company info
+  skipIf: [
+    "user wants company news or general company information",
+    (ctx) => {
+      const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+      return message.includes('news') || message.includes('company') || message.includes('founded');
+    }
   ],
 });
 
@@ -372,12 +426,15 @@ searchFaqs.nextStep({
 agent.createRoute({
   title: "General Conversation",
   description: "Handle general conversation or unclear questions",
-  conditions: [
-    "User message doesn't match other routes",
-    "Greetings",
-    "Small talk",
-    "Unclear intent",
-  ],
+  // Function-only condition for fallback logic
+  when: (ctx) => {
+    // This route catches everything that doesn't match other routes
+    const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+    return !message.includes('product') && !message.includes('policy') && 
+           !message.includes('news') && !message.includes('company');
+  },
+  // Never skip the fallback route
+  skipIf: ()=>false,
 });
 
 // Initial step is enough for fallback conversations
@@ -386,7 +443,27 @@ agent.createRoute({
 const feedbackRoute = agent.createRoute({
   title: "Collect Feedback",
   description: "Collect user feedback about their experience",
-  conditions: ["User wants to leave feedback", "User seems satisfied or upset"],
+  // Mixed condition: AI context + sentiment analysis
+  when: [
+    "User wants to leave feedback", 
+    "User seems satisfied or upset",
+    (ctx) => {
+      const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+      return message.includes('feedback') || message.includes('review') || 
+             message.includes('satisfied') || message.includes('disappointed');
+    }
+  ],
+  // Skip if user is in the middle of another task
+  skipIf: [
+    "user is actively getting help with something else",
+    (ctx) => {
+      const recentMessages = ctx.history?.filter((m) => "content" in m).slice(-3) || [];
+      return recentMessages.some(msg => 
+        (msg.content as string)?.toLowerCase().includes('help') || 
+        (msg.content as string)?.toLowerCase().includes('problem')
+      );
+    }
+  ],
   // NEW: Required fields for route completion
   requiredFields: ["rating", "comments"],
   // NEW: Optional fields

package/examples/advanced-patterns/persistent-onboarding.ts

@@ -1,6 +1,13 @@
 /**
  * Persistent multi-turn onboarding agent example
  * Updated for v2 architecture with session step management and schema-first data extraction
+ * 
+ * NEW: Enhanced with flexible ConditionTemplate patterns:
+ * - Mixed route conditions: ["AI context", (ctx) => state_check]
+ * - Route skipIf: Skip if onboarding already complete
+ * - Step skipIf: Enhanced conditional step skipping with AI context
+ * - Programmatic when conditions: (ctx) => data_validation
+ * - Performance patterns for condition evaluation
  */
 
 import {
@@ -327,7 +334,24 @@ function createPersistentOnboardingAgent(sessionId: string) {
   const onboardingRoute = agent.createRoute({
     title: "Business Onboarding",
     description: "Guide user through business information collection",
-    conditions: ["User is onboarding their business"],
+    // Mixed condition: AI context + programmatic validation
+    when: [
+      "User is onboarding their business",
+      (ctx) => {
+        const message = ctx.helpers.getLastUserMessage()?.toLowerCase() || '';
+        return message.includes('onboard') || message.includes('register') || 
+               message.includes('business') || message.includes('start');
+      }
+    ],
+    // Skip if user already has complete business info
+    skipIf: [
+      "business information already complete",
+      (ctx) => {
+        const data = ctx.data;
+        return !!(data?.businessName && data?.businessDescription && 
+                 data?.industry && data?.contactEmail);
+      }
+    ],
     // NEW: Required fields for route completion
     requiredFields: ["businessName", "businessDescription"],
     // NEW: Optional fields that enhance the experience
@@ -342,7 +366,12 @@ function createPersistentOnboardingAgent(sessionId: string) {
   const collectBusinessInfo = onboardingRoute.initialStep.nextStep({
     prompt: "Ask for business name and a brief description",
     collect: ["businessName", "businessDescription"],
-    skipIf: (data) => !!data.businessName && !!data.businessDescription,
+    // Mixed skipIf: AI context + programmatic check
+    skipIf: [
+      "business name and description already provided",
+      (ctx) => !!ctx.data?.businessName && !!ctx.data.businessDescription
+    ],
+    // String-only when condition for AI context
     when: "Need to collect basic business information first",
   });
 
@@ -350,14 +379,19 @@ function createPersistentOnboardingAgent(sessionId: string) {
   const saveBusiness = collectBusinessInfo.nextStep({
     tools: [saveBusinessInfo],
     requires: ["businessName", "businessDescription"],
-    when: "Business name and description provided, save to database",
+    // Function-only when condition for programmatic logic
+    when: (ctx) => !!ctx.data?.businessName && !!ctx.data?.businessDescription,
   });
 
   // Step 3: Collect industry
   const collectIndustry = saveBusiness.nextStep({
     prompt: "Ask what industry the business operates in",
     collect: ["industry"],
-    skipIf: (data) => !!data.industry,
+    // Mixed skipIf: AI context + programmatic logic
+    skipIf: [
+      "industry already specified",
+      (ctx) => !!ctx.data?.industry
+    ],
   });
 
   // Step 4: Save industry (tool execution)
@@ -370,7 +404,8 @@ function createPersistentOnboardingAgent(sessionId: string) {
   const collectContact = saveIndustryStep.nextStep({
     prompt: "Ask for their contact email",
     collect: ["contactEmail"],
-    skipIf: (data) => !!data.contactEmail,
+    // Function-only skipIf for programmatic check
+    skipIf: (ctx) => !!ctx.data?.contactEmail,
   });
 
   // Step 6: Save contact (tool execution)