@falai/agent 0.8.1 → 0.9.0-alpha-2

package/docs/{CONTEXT_MANAGEMENT.md → core/agent/context-management.md}

@@ -1,84 +1,105 @@
-# Session Step & Data Management
+# Context & Session Management
 
 ## Overview
 
-The `@falai/agent` framework provides **session step management** for tracking conversation progress, collected data, and user intent across multiple turns. This enables sophisticated data-driven conversations with intelligent step progression.
+The `@falai/agent` framework provides **automatic session management** through the integrated `SessionManager` class, tracking conversation progress, collected data, and user intent across multiple turns. This enables sophisticated data-driven conversations with zero boilerplate code.
 
 ---
 
-## 🎯 Session Step: The Foundation
+## 🎯 Automatic Session Management
 
-Session step tracks three key aspects of a conversation:
+The `SessionManager` automatically tracks four key aspects of a conversation:
 
 1. **Current Route** - Which conversation flow the user is in
 2. **Current Step** - Where in the flow they currently are
-3. **Collected data** - Structured data collected so far
+3. **Agent-Level Data** - Centralized structured data collected across all routes
+4. **Conversation History** - Complete message history within the session
 
 ```typescript
-import { createSession, SessionState } from "@falai/agent";
-
-// Define your data extraction type
-interface FlightData {
+// Define your agent-level data extraction type
+interface TravelData {
   destination: string;
   departureDate: string;
   passengers: number;
   cabinClass: "economy" | "business" | "first";
+  hotelPreference?: string;
+  budgetRange?: string;
+  specialRequests?: string;
 }
 
-// Initialize session step
-let session = createSession<FlightData>();
-
-// Session starts empty
-console.log(session.currentRoute); // undefined
-console.log(session.currentStep); // undefined
-console.log(session.data); // {}
+// Agent with automatic session management and agent-level schema
+const agent = new Agent<{}, TravelData>({
+  name: "Travel Agent",
+  provider: new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }),
+  persistence: { adapter: new PrismaAdapter({ prisma }) },
+  sessionId: "user-123", // Automatically loads or creates session
+  
+  // Agent-level schema for all data collection
+  schema: {
+    type: "object",
+    properties: {
+      destination: { type: "string" },
+      departureDate: { type: "string", format: "date" },
+      passengers: { type: "number", minimum: 1, maximum: 9 },
+      cabinClass: { type: "string", enum: ["economy", "business", "first"] },
+      hotelPreference: { type: "string" },
+      budgetRange: { type: "string" },
+      specialRequests: { type: "string" }
+    }
+  }
+});
 
-// Use in conversation
-const response = await agent.respond({ history, session });
+// Simple conversation - session managed automatically
+const response = await agent.respond("I want to book a flight to Paris");
 
-// Session updated with progress and collected data
-console.log(response.session?.currentRoute?.title); // "Book Flight"
-console.log(response.session?.currentStep?.id); // "ask_destination"
-console.log(response.session?.data); // { destination: "Paris", ... }
+// Access session information
+console.log(agent.session.id); // "user-123"
+console.log(agent.session.getData<TravelData>()); // { destination: "Paris", ... }
+console.log(agent.session.getHistory()); // Conversation history
 ```
 
-**Benefits of Session Step:**
+**Benefits of Automatic Session Management:**
 
+- **Zero Boilerplate** - No manual session creation or persistence code
 - **Always-On Routing** - Users can change their mind mid-conversation
-- **Data Persistence** - Collected data survives across turns
+- **Data Persistence** - Collected data automatically saved and restored
 - **Context Awareness** - Router sees current progress and collected data
-- **Step Recovery** - Resume conversations from any point
+- **History Management** - Conversation history automatically maintained
+- **Server-Friendly** - Perfect for stateless server environments
 
 ---
 
-## 🔄 Session Step Helpers
+## 🔄 SessionManager API
 
-### Creating and Managing Sessions
+### Session Operations
 
 ```typescript
-import {
-  createSession,
-  enterRoute,
-  enterStep,
-  mergeData,
-  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");
+// Access the session manager
+const sessionManager = agent.session;
 
-// Enter a step (when progressing through the flow)
-session = enterStep(session, "ask_destination", "Ask where they want to fly");
+// Get or create session (works for existing, new, or auto-generated IDs)
+await sessionManager.getOrCreate("user-123");
+await sessionManager.getOrCreate(); // Auto-generates ID
 
-// Merge collected data (when AI extracts new information)
-session = mergeData(session, {
+// Agent-level data management
+const data = sessionManager.getData<TravelData>();
+await sessionManager.setData({
   destination: "Paris",
   departureDate: "2025-10-15",
   passengers: 2,
+  cabinClass: "economy"
 });
+
+// History management
+await sessionManager.addMessage("user", "I want to book a flight");
+await sessionManager.addMessage("assistant", "Where would you like to go?");
+const history = sessionManager.getHistory();
+sessionManager.clearHistory();
+
+// Session operations
+await sessionManager.save(); // Manual save (auto-saves on addMessage)
+await sessionManager.delete();
+const newSession = await sessionManager.reset(true); // Preserve history
 ```
 
 ### Session Step Structure
@@ -125,19 +146,25 @@ const agent = new Agent({
       await saveUserData(newContext.userId, newContext);
     },
 
-    // NEW: Validate and enrich collected data
+    // Agent-level data validation and enrichment
     onDataUpdate: async (data, previousData) => {
       // Normalize passenger count
       if (data.passengers < 1) data.passengers = 1;
       if (data.passengers > 9) data.passengers = 9;
 
-      // Enrich with computed fields
-      if (data.destination) {
+      // Enrich with computed fields using agent-level data
+      if (data.destination && !data.destinationCode) {
         data.destinationCode = await lookupAirportCode(data.destination);
       }
 
-      // Auto-trigger actions
-      if (hasAllRequires(data)) {
+      // Auto-set budget range based on cabin class
+      if (data.cabinClass && !data.budgetRange) {
+        data.budgetRange = data.cabinClass === 'first' ? 'premium' : 
+                          data.cabinClass === 'business' ? 'high' : 'standard';
+      }
+
+      // Auto-trigger actions when we have complete booking data
+      if (data.destination && data.departureDate && data.passengers) {
         data.shouldSearchFlights = true;
       }
 
@@ -205,7 +232,7 @@ const route = agent.createRoute<FlightData>({
 ```typescript
 // Step with code-based logic (no fuzzy LLM conditions!)
 const askDestination = route.initialStep.nextStep({
-  instructions: "Ask where they want to fly",
+  prompt: "Ask where they want to fly",
   collect: ["destination"],
   skipIf: (data) => !!data.destination, // Skip if already have destination
 });
@@ -216,7 +243,7 @@ const enrichDestination = askDestination.nextStep({
 });
 
 const askDates = enrichDestination.nextStep({
-  instructions: "Ask about travel dates",
+  prompt: "Ask about travel dates",
   collect: ["departureDate"],
   skipIf: (data) => !!data.departureDate,
   requires: ["destination"], // Must have destination first
@@ -228,7 +255,7 @@ const validateDate = askDates.nextStep({
 });
 
 const askPassengers = validateDate.nextStep({
-  instructions: "How many passengers?",
+  prompt: "How many passengers?",
   collect: ["passengers"],
   skipIf: (data) => !!data.passengers,
 });
@@ -242,15 +269,23 @@ const searchFlights = askPassengers.nextStep({
 ### 3. Tools Access Collected data
 
 ```typescript
-const searchFlights = defineTool<Context, [], void, FlightData>(
-  "search_flights",
-  async ({ context, data }) => {
+const searchFlights: Tool<Context, [], void, FlightData> = {
+  id: "search_flights",
+  description: "Search for available flights based on collected data",
+  parameters: {
+    type: "object",
+    properties: {},
+  },
+  handler: async (toolContext) => {
     // Access collected data directly (no LLM extraction needed!)
-    if (!data.destination || !data.departureDate) {
+    if (!toolContext.data.destination || !toolContext.data.departureDate) {
       return { data: undefined };
     }
 
-    const flights = await searchFlightAPI(data.destination, data.departureDate);
+    const flights = await searchFlightAPI(
+      toolContext.data.destination,
+      toolContext.data.departureDate
+    );
 
     return {
       data: undefined,
@@ -259,8 +294,8 @@ const searchFlights = defineTool<Context, [], void, FlightData>(
         shouldSearchFlights: false, // Clear the flag
       },
     };
-  }
-);
+  },
+};
 ```
 
 ### 4. Lifecycle Hooks for Validation & Enrichment
@@ -298,11 +333,10 @@ Routing happens every turn with full session context:
 // 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"
-    ),
+    {
+      role: "user",
+      content: "I want to fly to Paris tomorrow with 2 people",
+    },
   ],
   session,
 });
@@ -311,11 +345,10 @@ const response1 = await agent.respond({
 const response2 = await agent.respond({
   history: [
     ...previousHistory,
-    createMessageEvent(
-      EventSource.CUSTOMER,
-      "User",
-      "Actually, make that Tokyo instead"
-    ),
+    {
+      role: "user",
+      content: "Actually, make that Tokyo instead",
+    },
   ],
   session: response1.session, // Router sees context and switches appropriately
 });
@@ -370,18 +403,26 @@ Tools can update context in **two ways**:
 ### Option A: Return `contextUpdate`
 
 ```typescript
-const saveName = defineTool<MyContext, [name: string], boolean>(
-  "save_name",
-  async (toolContext, name) => {
+const saveName: Tool<MyContext, [name: string], boolean> = {
+  id: "save_name",
+  description: "Save the user's name to context",
+  parameters: {
+    type: "object",
+    properties: {
+      name: { type: "string", description: "The user's name" },
+    },
+    required: ["name"],
+  },
+  handler: async (toolContext, args) => {
     return {
       data: true,
       contextUpdate: {
-        userName: name,
+        userName: args.name,
         updatedAt: new Date(),
       },
     };
-  }
-);
+  },
+};
 ```
 
 **Pros:**
@@ -393,17 +434,25 @@ const saveName = defineTool<MyContext, [name: string], boolean>(
 ### Option B: Call `updateContext()` directly
 
 ```typescript
-const saveName = defineTool<MyContext, [name: string], boolean>(
-  "save_name",
-  async (toolContext, name) => {
+const saveName: Tool<MyContext, [name: string], boolean> = {
+  id: "save_name",
+  description: "Save the user's name to context using direct update",
+  parameters: {
+    type: "object",
+    properties: {
+      name: { type: "string", description: "The user's name" },
+    },
+    required: ["name"],
+  },
+  handler: async (toolContext, args) => {
     await toolContext.updateContext({
-      userName: name,
+      userName: args.name,
       updatedAt: new Date(),
     });
 
     return { data: true };
-  }
-);
+  },
+};
 ```
 
 **Pros:**
@@ -456,7 +505,7 @@ const agent = new Agent({
 ## 🎯 Complete Example: Multi-Turn Onboarding
 
 ```typescript
-import { Agent, defineTool } from "@falai/agent";
+import { Agent, type Tool } from "@falai/agent";
 
 interface OnboardingContext {
   sessionId: string;
@@ -509,31 +558,50 @@ async function createOnboardingAgent(sessionId: string) {
   });
 
   // Define tools with context updates
-  const saveBusinessName = defineTool(
-    "save_business_name",
-    async (ctx, name: string) => {
+  const saveBusinessName: Tool<OnboardingContext, [name: string], boolean> = {
+    id: "save_business_name",
+    description: "Save the business name and mark step as completed",
+    parameters: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "The business name" },
+      },
+      required: ["name"],
+    },
+    handler: async (toolContext, args) => {
       return {
         data: true,
         contextUpdate: {
-          businessName: name,
-          completedSteps: [...ctx.context.completedSteps, "business_name"],
+          businessName: args.name,
+          completedSteps: [
+            ...toolContext.context.completedSteps,
+            "business_name",
+          ],
         },
       };
-    }
-  );
+    },
+  };
 
-  const saveIndustry = defineTool(
-    "save_industry",
-    async (ctx, industry: string) => {
+  const saveIndustry: Tool<OnboardingContext, [industry: string], boolean> = {
+    id: "save_industry",
+    description: "Save the industry and mark step as completed",
+    parameters: {
+      type: "object",
+      properties: {
+        industry: { type: "string", description: "The business industry" },
+      },
+      required: ["industry"],
+    },
+    handler: async (toolContext, args) => {
       // Alternative: use updateContext directly
-      await ctx.updateContext({
-        industry,
-        completedSteps: [...ctx.context.completedSteps, "industry"],
+      await toolContext.updateContext({
+        industry: args.industry,
+        completedSteps: [...toolContext.context.completedSteps, "industry"],
       });
 
       return { data: true };
-    }
-  );
+    },
+  };
 
   // Build conversation routes...
   const route = agent.createRoute({ title: "Onboarding" });
@@ -548,7 +616,12 @@ async function handleUserMessage(sessionId: string, message: string) {
   const agent = await createOnboardingAgent(sessionId);
 
   const response = await agent.respond({
-    history: [createMessageEvent(EventSource.CUSTOMER, "User", message)],
+    history: [
+      {
+        role: "user",
+        content: message,
+      },
+    ],
   });
 
   return response.message;
@@ -701,9 +774,9 @@ hooks: {
 ## 📚 Related Resources
 
 - [Complete Example: Persistent Onboarding](../examples/persistent-onboarding.ts)
-- [API Reference: AgentOptions](./API_REFERENCE.md#agentoptions)
-- [API Reference: ContextLifecycleHooks](./API_REFERENCE.md#contextlifecyclehooks)
-- [Getting Started](./GETTING_STARTED.md)
+- [API Reference: AgentOptions](../api/overview.md#agentoptions)
+- [API Reference: ContextLifecycleHooks](../api/overview.md#contextlifecyclehooks)
+- [Getting Started](../guides/getting-started/README.md)
 
 ---
 
@@ -712,7 +785,7 @@ hooks: {
 If you're still having issues:
 
 1. Check the [examples](../examples/) for working implementations
-2. Review the [API Reference](./API_REFERENCE.md) for detailed type information
+2. Review the [API Reference](../api/README.md) for detailed type information
 3. Open an issue on GitHub with your use case
 
 **Remember:** The key to persistent conversations is: