@falai/agent 0.4.1 → 0.5.0

package/docs/CONTEXT_MANAGEMENT.md

@@ -1,57 +1,340 @@
-# Context Management & Persistence
+# Session State & Data Management
 
 ## Overview
 
-The `@falai/agent` framework provides flexible patterns for managing context in both **single-turn** and **multi-turn persistent** conversations. This guide explains how to handle stateful conversations that persist across requests.
+The `@falai/agent` framework provides **session state management** for tracking conversation progress, extracted data, and user intent across multiple turns. This enables sophisticated data-driven conversations with intelligent state progression.
 
 ---
 
-## 🤔 The Context Lifecycle Problem
+## 🎯 Session State: The Foundation
 
-### Single-Turn Conversations (Simple)
+Session state tracks three key aspects of a conversation:
+
+1. **Current Route** - Which conversation flow the user is in
+2. **Current State** - Where in the flow they currently are
+3. **Extracted Data** - Structured data collected so far
 
 ```typescript
-// ✅ Works great for single-turn conversations
-const agent = new Agent({
-  name: "Bot",
-  ai: provider,
-  context: { userId: "123", preferences: {} },
+import { createSession, SessionState } from "@falai/agent";
+
+// Define your data extraction type
+interface FlightData {
+  destination: string;
+  departureDate: string;
+  passengers: number;
+  cabinClass: "economy" | "business" | "first";
+}
+
+// Initialize session state
+let session = createSession<FlightData>();
+
+// Session starts empty
+console.log(session.currentRoute); // undefined
+console.log(session.currentState); // undefined
+console.log(session.extracted); // {}
+
+// Use in conversation
+const response = await agent.respond({ history, session });
+
+// Session updated with progress and extracted data
+console.log(response.session?.currentRoute?.title); // "Book Flight"
+console.log(response.session?.currentState?.id); // "ask_destination"
+console.log(response.session?.extracted); // { destination: "Paris", ... }
+```
+
+**Benefits of Session State:**
+
+- **Always-On Routing** - Users can change their mind mid-conversation
+- **Data Persistence** - Extracted data survives across turns
+- **Context Awareness** - Router sees current progress and extracted data
+- **State Recovery** - Resume conversations from any point
+
+---
+
+## 🔄 Session State Helpers
+
+### Creating and Managing Sessions
+
+```typescript
+import {
+  createSession,
+  enterRoute,
+  enterState,
+  mergeExtracted,
+  type SessionState,
+} from "@falai/agent";
+
+// Create a new session
+let session = createSession<FlightData>();
+
+// Enter a route (when routing decides to switch)
+session = enterRoute(session, "book_flight", "Book Flight");
+
+// Enter a state (when progressing through the flow)
+session = enterState(session, "ask_destination", "Ask where they want to fly");
+
+// Merge extracted data (when AI extracts new information)
+session = mergeExtracted(session, {
+  destination: "Paris",
+  departureDate: "2025-10-15",
+  passengers: 2,
 });
+```
+
+### Session State Structure
 
-const response = await agent.respond({ history });
+```typescript
+interface SessionState<TExtracted = unknown> {
+  currentRoute?: {
+    id: string;
+    title: string;
+    enteredAt: Date;
+  };
+  currentState?: {
+    id: string;
+    description?: string;
+    enteredAt: Date;
+  };
+  extracted: Partial<TExtracted>; // Data collected so far
+  routeHistory: Array<{
+    routeId: string;
+    routeTitle: string;
+    enteredAt: Date;
+    exitedAt?: Date;
+  }>;
+  metadata?: Record<string, unknown>;
+}
 ```
 
-**Works because:** Agent is used once and discarded.
+## 🔄 Enhanced Lifecycle Hooks
 
-### Multi-Turn Conversations (Complex)
+### Context Hooks (Traditional Context Management)
 
 ```typescript
-// ❌ PROBLEM: Context updates don't persist
 const agent = new Agent({
-  name: "Bot",
-  ai: provider,
-  context: { userId: "123", preferences: {} },
+  // ... other options
+  hooks: {
+    // Refresh context before each response
+    beforeRespond: async (currentContext) => {
+      const freshData = await loadUserData(currentContext.userId);
+      return { ...currentContext, ...freshData };
+    },
+
+    // Persist context updates
+    onContextUpdate: async (newContext, previousContext) => {
+      await saveUserData(newContext.userId, newContext);
+    },
+
+    // NEW: Validate and enrich extracted data
+    onExtractedUpdate: async (extracted, previousExtracted) => {
+      // Normalize passenger count
+      if (extracted.passengers < 1) extracted.passengers = 1;
+      if (extracted.passengers > 9) extracted.passengers = 9;
+
+      // Enrich with computed fields
+      if (extracted.destination) {
+        extracted.destinationCode = await lookupAirportCode(
+          extracted.destination
+        );
+      }
+
+      // Auto-trigger actions
+      if (hasAllRequiredData(extracted)) {
+        extracted.shouldSearchFlights = true;
+      }
+
+      return extracted;
+    },
+  },
 });
+```
+
+### Context Provider Pattern
 
-// Turn 1
-await agent.respond({ history: [message1] });
-// Tool modifies context in memory...
+For always-fresh context from external sources:
 
-// Turn 2 (new request, agent recreated)
-const agent2 = new Agent({ context: { userId: "123", preferences: {} } });
-await agent2.respond({ history: [message2] });
-// ❌ Lost the context changes from Turn 1!
+```typescript
+const agent = new Agent({
+  // ... other options
+  contextProvider: async () => {
+    // Load fresh context for each response
+    return await loadFullContextFromDatabase();
+  },
+});
 ```
 
-**Problem:** When agents are recreated (e.g., across HTTP requests), context updates are lost.
+## 📊 Data Extraction Pipeline
 
----
+Schema-first data extraction with intelligent state progression:
 
-## 💡 Solution: Context Lifecycle Hooks
+### 1. Define Your Data Schema
+
+```typescript
+interface FlightData {
+  destination: string;
+  destinationCode?: string; // Enriched by tools
+  departureDate: string;
+  departureDateParsed?: string; // Enriched by tools
+  passengers: number;
+  cabinClass: "economy" | "business" | "first";
+  shouldSearchFlights?: boolean; // Action flag
+}
 
-The framework provides **lifecycle hooks** to integrate with your persistence layer (database, cache, etc.).
+const route = agent.createRoute<FlightData>({
+  title: "Book Flight",
+  gatherSchema: {
+    type: "object",
+    properties: {
+      destination: { type: "string" },
+      departureDate: { type: "string" },
+      passengers: { type: "number", minimum: 1, maximum: 9 },
+      cabinClass: {
+        type: "string",
+        enum: ["economy", "business", "first"],
+        default: "economy",
+      },
+    },
+    required: ["destination", "departureDate", "passengers"],
+  },
+  initialData: {
+    cabinClass: "economy", // Pre-populate defaults
+  },
+});
+```
+
+### 2. Create Smart State Machines
+
+```typescript
+// State with code-based logic (no fuzzy LLM conditions!)
+const askDestination = route.initialState.transitionTo({
+  chatState: "Ask where they want to fly",
+  gather: ["destination"],
+  skipIf: (extracted) => !!extracted.destination, // Skip if already have destination
+});
+
+const enrichDestination = askDestination.transitionTo({
+  toolState: lookupAirportCode, // Tool executes automatically
+  requiredData: ["destination"], // Prerequisites
+});
+
+const askDates = enrichDestination.transitionTo({
+  chatState: "Ask about travel dates",
+  gather: ["departureDate"],
+  skipIf: (extracted) => !!extracted.departureDate,
+  requiredData: ["destination"], // Must have destination first
+});
+
+const validateDate = askDates.transitionTo({
+  toolState: parseAndValidateDate,
+  requiredData: ["departureDate"],
+});
+
+const askPassengers = validateDate.transitionTo({
+  chatState: "How many passengers?",
+  gather: ["passengers"],
+  skipIf: (extracted) => !!extracted.passengers,
+});
+
+const searchFlights = askPassengers.transitionTo({
+  toolState: searchFlightAPI,
+  // Triggered when shouldSearchFlights flag is set by hook
+});
+```
+
+### 3. Tools Access Extracted Data
+
+```typescript
+const searchFlights = defineTool<Context, [], void, FlightData>(
+  "search_flights",
+  async ({ context, extracted }) => {
+    // Access extracted data directly (no LLM extraction needed!)
+    if (!extracted.destination || !extracted.departureDate) {
+      return { data: undefined };
+    }
+
+    const flights = await searchFlightAPI(
+      extracted.destination,
+      extracted.departureDate
+    );
+
+    return {
+      data: undefined,
+      contextUpdate: { availableFlights: flights },
+      extractedUpdate: {
+        shouldSearchFlights: false, // Clear the flag
+      },
+    };
+  }
+);
+```
+
+### 4. Lifecycle Hooks for Validation & Enrichment
+
+```typescript
+const agent = new Agent({
+  // ... other options
+  hooks: {
+    onExtractedUpdate: async (extracted, previous) => {
+      // Normalize data
+      if (extracted.passengers < 1) extracted.passengers = 1;
+      if (extracted.passengers > 9) extracted.passengers = 9;
+
+      // Enrich data
+      if (extracted.destination && !extracted.destinationCode) {
+        extracted.destinationCode = await lookupAirportCode(
+          extracted.destination
+        );
+      }
+
+      // Auto-trigger actions
+      if (hasAllRequiredData(extracted) && !extracted.shouldSearchFlights) {
+        extracted.shouldSearchFlights = true;
+      }
+
+      return extracted;
+    },
+  },
+});
+```
+
+## 🎯 Always-On Routing with Context
+
+Routing happens every turn with full session context:
+
+```typescript
+// User starts booking a flight
+const response1 = await agent.respond({
+  history: [
+    createMessageEvent(
+      EventSource.CUSTOMER,
+      "User",
+      "I want to fly to Paris tomorrow with 2 people"
+    ),
+  ],
+  session,
+});
+
+// User changes mind mid-conversation
+const response2 = await agent.respond({
+  history: [
+    ...previousHistory,
+    createMessageEvent(
+      EventSource.CUSTOMER,
+      "User",
+      "Actually, make that Tokyo instead"
+    ),
+  ],
+  session: response1.session, // Router sees context and switches appropriately
+});
+
+// Router understands:
+// - Current route: "Book Flight"
+// - Current state: "ask_passengers"
+// - Extracted data: { destination: "Paris", departureDate: "tomorrow", passengers: 2 }
+// - User intent: "Tokyo instead" → switches to new destination
+```
 
-### Pattern 1: `beforeRespond` + `onContextUpdate` (Recommended)
+## 📋 Multi-Turn Conversation Patterns
 
 ```typescript
 import { Agent, type ContextLifecycleHooks } from "@falai/agent";

package/docs/CONTRIBUTING.md

@@ -244,7 +244,7 @@ Follow [Conventional Commits](https://www.conventionalcommits.org/):
 
 ```bash
 git add .
-git commit -m "feat: add disambiguation support for routes"
+git commit -m "feat: add support for routes"
 ```
 
 **Commit types:**

package/docs/DOMAINS.md

@@ -662,6 +662,67 @@ route.initialState.transitionTo({
 });
 ```
 
+## How Enforcement Works (Under the Hood)
+
+For developers who want to understand the implementation:
+
+### Automatic Tool Tagging
+
+When you register tools via `agent.addDomain()`, each tool is automatically tagged with its domain name:
+
+```typescript
+// When you do this:
+agent.addDomain("payment", {
+  processPayment: defineTool(/* ... */),
+});
+
+// The framework automatically adds:
+// processPayment.domainName = "payment"
+```
+
+### Runtime Enforcement
+
+When a tool tries to execute, `ToolExecutor` checks:
+
+1. **Get allowed domains** from the current route
+2. **Check tool's domain** against the allowed list
+3. **Block execution** if domain not allowed
+4. **Throw security error** with clear message
+
+```typescript
+// ToolExecutor enforcement code:
+if (allowedDomains !== undefined && tool.domainName) {
+  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(
+          ", "
+        )}]`
+    );
+  }
+}
+```
+
+### What Gets Enforced
+
+✅ **Tools in state machine transitions** (`toolState`)  
+✅ **Multiple domain access** (route can allow several domains)  
+✅ **Empty array enforcement** (`domains: []` blocks all tools)  
+✅ **Undefined = all allowed** (backward compatible)
+
+### Type Safety
+
+The domain system is fully type-safe:
+
+```typescript
+interface ToolRef {
+  id: string;
+  name: string;
+  handler: Function;
+  domainName?: string; // Added by addDomain()
+}
+```
+
 ## See Also
 
 - [Architecture Guide](./ARCHITECTURE.md) - Core design principles