@falai/agent 0.9.0-alpha-2 → 0.9.2

package/docs/core/agent/session-management.md

@@ -104,7 +104,7 @@ const response3 = await agent.respond("Also book me a hotel in Tokyo");
 
 **SessionManager API:**
 
-The `SessionManager` provides a clean API for session operations:
+The `SessionManager` provides a clean API for session operations with comprehensive error handling:
 
 ```typescript
 // Access the session manager
@@ -114,13 +114,19 @@ const sessionManager = agent.session;
 await sessionManager.getOrCreate("user-123");
 await sessionManager.getOrCreate(); // Auto-generates ID
 
-// History management
-await sessionManager.addMessage("user", "Hello");
-await sessionManager.addMessage("assistant", "Hi there!");
+// History management with error handling
+try {
+  await sessionManager.addMessage("user", "Hello");
+  await sessionManager.addMessage("assistant", "Hi there!");
+} catch (error) {
+  console.error("Failed to add message to history:", error);
+  // Message will be rolled back automatically
+}
+
 const history = sessionManager.getHistory();
 sessionManager.clearHistory();
 
-// Data access
+// Data access with synchronization
 const data = sessionManager.getData<FlightData>();
 await sessionManager.setData({ destination: "Paris" });
 
@@ -130,6 +136,147 @@ await sessionManager.delete();
 const newSession = await sessionManager.reset(true); // Preserve history
 ```
 
+### Agent-Session Data Synchronization
+
+The framework ensures bidirectional synchronization between agent collected data and session data:
+
+```typescript
+// Agent data updates automatically sync with session
+const agent = new Agent<{}, BookingData>({
+  sessionId: "user-123",
+  // ... other config
+});
+
+try {
+  // Update agent data - automatically syncs with session
+  await agent.updateCollectedData({
+    destination: "Tokyo",
+    passengers: 2
+  });
+  
+  // Session data is automatically updated
+  const sessionData = agent.session.getData<BookingData>();
+  console.log(sessionData.destination); // "Tokyo"
+  
+  // Update session data - automatically syncs with agent
+  await agent.session.setData({
+    checkInDate: "2025-03-15"
+  });
+  
+  // Agent data is automatically updated
+  const agentData = agent.getCollectedData();
+  console.log(agentData.checkInDate); // "2025-03-15"
+  
+} catch (error) {
+  console.error("Data synchronization failed:", error);
+  // Both agent and session data remain in consistent state
+}
+```
+
+### Error Handling in Data Synchronization
+
+```typescript
+class SessionManager<TData> {
+  async setData(data: Partial<TData>): Promise<void> {
+    const previousData = { ...this.session.data };
+    
+    try {
+      // Validate data if schema is available
+      if (this.schema) {
+        this.validateData(data);
+      }
+      
+      // Update session data
+      this.session.data = { ...this.session.data, ...data };
+      
+      // Sync with agent collected data
+      if (this.agent) {
+        await this.agent.updateCollectedData(data);
+      }
+      
+      // Persist changes
+      await this.save();
+      
+    } catch (error) {
+      // Rollback session data on any failure
+      this.session.data = previousData;
+      
+      console.error("Session data update failed, rolled back:", error);
+      throw new Error(`Data synchronization failed: ${error.message}`);
+    }
+  }
+  
+  async addMessage(role: "user" | "assistant", content: string): Promise<void> {
+    const message: HistoryItem = {
+      role,
+      content,
+      timestamp: new Date().toISOString()
+    };
+    
+    try {
+      // Add to session history
+      this.session.history.push(message);
+      
+      // Persist immediately for reliability
+      await this.save();
+      
+    } catch (error) {
+      // Remove message from history on persistence failure
+      this.session.history.pop();
+      
+      console.error("Failed to persist message:", error);
+      throw new Error(`Message persistence failed: ${error.message}`);
+    }
+  }
+}
+```
+
+### Chat Method with Proper Error Handling
+
+```typescript
+class Agent<TContext, TData> {
+  async chat(message: string, sessionId?: string): Promise<AgentResponse<TData>> {
+    try {
+      // Ensure session is loaded
+      if (!this.session || this.session.id !== sessionId) {
+        await this.loadSession(sessionId);
+      }
+      
+      // Add user message to history BEFORE processing
+      await this.session.addMessage("user", message);
+      
+      // Process the message
+      const response = await this.respond({
+        message,
+        sessionId: this.session.id
+      });
+      
+      // Add assistant response to history
+      if (response.message) {
+        await this.session.addMessage("assistant", response.message);
+      }
+      
+      return response;
+      
+    } catch (error) {
+      console.error("Chat method failed:", error);
+      
+      // Try to remove the user message if response failed
+      try {
+        const history = this.session.getHistory();
+        if (history.length > 0 && history[history.length - 1].role === "user") {
+          await this.session.removeLastMessage();
+        }
+      } catch (rollbackError) {
+        console.error("Failed to rollback user message:", rollbackError);
+      }
+      
+      throw new Error(`Chat failed: ${error.message}`);
+    }
+  }
+}
+```
+
 **Why?** Automatic session management provides:
 
 - **Zero Boilerplate** - No manual session creation or persistence code

package/docs/core/ai-integration/response-processing.md

@@ -118,10 +118,121 @@ agentContext.lastResponseTime = Date.now();
 
 Robust error handling for various failure scenarios:
 
-- **Schema validation failures** - Graceful fallback to manual extraction
-- **Tool execution errors** - Error recovery and user notification
-- **Context update failures** - Rollback and logging
-- **Routing errors** - Safe fallback to default behavior
+### Schema Validation Failures
+
+When AI responses don't match expected schemas, the system gracefully falls back:
+
+```typescript
+const processResponse = async (response: string, schema: JSONSchema) => {
+  try {
+    // Try schema-based extraction first
+    const extracted = await extractWithSchema(response, schema);
+    return { success: true, data: extracted };
+  } catch (schemaError) {
+    console.warn("Schema extraction failed, falling back to manual parsing:", schemaError.message);
+    
+    // Fallback to manual extraction
+    try {
+      const manualData = await manualExtraction(response);
+      return { success: true, data: manualData, fallback: true };
+    } catch (fallbackError) {
+      return { 
+        success: false, 
+        error: `Both schema and manual extraction failed: ${fallbackError.message}` 
+      };
+    }
+  }
+};
+```
+
+### Tool Execution Errors
+
+Tool failures are handled gracefully with proper error propagation:
+
+```typescript
+const executeTool = async (tool: Tool, params: any) => {
+  try {
+    const result = await tool.handler(params);
+    return { success: true, result };
+  } catch (error) {
+    console.error(`Tool ${tool.id} execution failed:`, error);
+    
+    return {
+      success: false,
+      error: error.message,
+      fallbackMessage: "I encountered an issue while processing your request. Please try again."
+    };
+  }
+};
+```
+
+### Context Update Failures
+
+Context updates include rollback mechanisms:
+
+```typescript
+const updateContext = async (newContext: any, previousContext: any) => {
+  try {
+    await persistContext(newContext);
+    return { success: true };
+  } catch (error) {
+    console.error("Context update failed, rolling back:", error);
+    
+    try {
+      await persistContext(previousContext);
+      return { success: false, rolledBack: true, error: error.message };
+    } catch (rollbackError) {
+      return { 
+        success: false, 
+        rolledBack: false, 
+        error: `Update and rollback both failed: ${rollbackError.message}` 
+      };
+    }
+  }
+};
+```
+
+### Streaming Error Propagation
+
+Streaming responses properly propagate provider errors:
+
+```typescript
+async function* processStreamingResponse(provider: AIProvider, prompt: string) {
+  try {
+    for await (const chunk of provider.generateMessageStream(prompt)) {
+      yield { success: true, chunk };
+    }
+  } catch (error) {
+    // Ensure streaming errors are properly propagated
+    yield { success: false, error: error.message };
+    throw error; // Re-throw to stop the stream
+  }
+}
+```
+
+### Routing Errors
+
+Safe fallback to default behavior when routing fails:
+
+```typescript
+const selectRoute = async (routes: Route[], context: any) => {
+  try {
+    const selectedRoute = await aiRouting.selectBestRoute(routes, context);
+    return { success: true, route: selectedRoute };
+  } catch (routingError) {
+    console.warn("AI routing failed, using default route:", routingError.message);
+    
+    // Fallback to first available route or default
+    const fallbackRoute = routes.find(r => r.isDefault) || routes[0];
+    return { 
+      success: true, 
+      route: fallbackRoute, 
+      fallback: true,
+      error: routingError.message 
+    };
+  }
+};
+```
 
 ## Streaming Response Processing
 

package/docs/core/conversation-flows/routes.md

@@ -74,6 +74,8 @@ Routes are selected by the AI routing system based on user intent and conversati
 
 Routes complete when all their required fields are present in the agent's collected data, regardless of which route collected the data. This enables flexible cross-route completion scenarios.
 
+### Basic Route Completion
+
 ```typescript
 // Route completion evaluation
 const isComplete = bookingRoute.isComplete(agent.getCollectedData());
@@ -86,6 +88,134 @@ if (missingFields.length > 0) {
 }
 ```
 
+### Route Completion with Error Handling
+
+Proper error handling ensures accurate route completion detection:
+
+```typescript
+const checkRouteCompletion = async (route: Route, agent: Agent) => {
+  try {
+    const collectedData = agent.getCollectedData();
+    
+    // Check data-based completion
+    if (route.isComplete(collectedData)) {
+      return { complete: true, reason: "all_required_data_collected" };
+    }
+    
+    // Check step-based completion (for routes with skipIf conditions)
+    const allStepsProcessed = route.steps.every(step => {
+      if (step.skipIf && step.skipIf(collectedData)) {
+        return true; // Step is skipped, counts as processed
+      }
+      return step.isCompleted;
+    });
+    
+    if (allStepsProcessed) {
+      return { complete: true, reason: "all_steps_processed" };
+    }
+    
+    // Check for explicit route termination
+    if (route.hasExplicitEnd()) {
+      return { complete: true, reason: "explicit_end_route" };
+    }
+    
+    return { 
+      complete: false, 
+      missingFields: route.getMissingRequiredFields(collectedData),
+      progress: route.getCompletionProgress(collectedData)
+    };
+  } catch (error) {
+    console.error("Route completion check failed:", error);
+    return { 
+      complete: false, 
+      error: error.message,
+      fallback: true 
+    };
+  }
+};
+
+// Usage with error handling
+const completionResult = await checkRouteCompletion(bookingRoute, agent);
+
+if (completionResult.error) {
+  console.warn("Completion check failed, assuming incomplete:", completionResult.error);
+} else if (completionResult.complete) {
+  console.log(`Route completed: ${completionResult.reason}`);
+} else {
+  console.log(`Route ${Math.round(completionResult.progress * 100)}% complete`);
+  console.log(`Missing: ${completionResult.missingFields.join(', ')}`);
+}
+```
+
+### Handling Routes with Conditional Steps
+
+Routes with `skipIf` conditions require special completion logic:
+
+```typescript
+const conditionalRoute = agent.createRoute({
+  title: "Conditional Booking",
+  requiredFields: ["destination", "dates", "passengers"]
+});
+
+const askDestination = conditionalRoute.initialStep.nextStep({
+  prompt: "Where would you like to go?",
+  collect: ["destination"],
+  skipIf: (data) => !!data.destination, // Skip if already collected
+});
+
+const askDates = askDestination.nextStep({
+  prompt: "When would you like to travel?",
+  collect: ["dates"],
+  skipIf: (data) => !!data.dates,
+});
+
+const confirmBooking = askDates.nextStep({
+  prompt: "Confirm your booking details",
+  requires: ["destination", "dates", "passengers"],
+  onComplete: () => ({ endRoute: true }) // Explicit route termination
+});
+
+// Completion detection handles skipped steps
+const response = await agent.respond({
+  message: "I want to go to Paris on March 15th for 2 passengers",
+  sessionId: "user-123"
+});
+
+// All steps may be skipped due to complete data extraction
+// Route should still be marked as complete
+console.log("Route complete:", response.isRouteComplete); // Should be true
+```
+
+### Error Recovery in Route Completion
+
+```typescript
+const safeRouteCompletion = async (route: Route, agent: Agent) => {
+  const maxRetries = 3;
+  let attempt = 0;
+  
+  while (attempt < maxRetries) {
+    try {
+      return await checkRouteCompletion(route, agent);
+    } catch (error) {
+      attempt++;
+      console.warn(`Route completion check attempt ${attempt} failed:`, error.message);
+      
+      if (attempt >= maxRetries) {
+        // Final fallback - assume incomplete
+        return {
+          complete: false,
+          error: `Completion check failed after ${maxRetries} attempts: ${error.message}`,
+          fallback: true
+        };
+      }
+      
+      // Brief delay before retry
+      await new Promise(resolve => setTimeout(resolve, 100 * attempt));
+    }
+  }
+};
+```
+
 ## Route Transitions
 
 Routes can automatically transition to other routes upon completion using the `onComplete` configuration. With agent-level data, the target route may already have some of its required data.