@falai/agent 0.8.0 → 0.9.0-alpha-1

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

@@ -1,22 +1,21 @@
-# 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 three 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
+4. **Conversation History** - Complete message history within the session
 
 ```typescript
-import { createSession, SessionStep } from "@falai/agent";
-
 // Define your data extraction type
 interface FlightData {
   destination: string;
@@ -25,66 +24,70 @@ interface FlightData {
   cabinClass: "economy" | "business" | "first";
 }
 
-// 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
+const agent = new Agent({
+  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
+});
 
-// 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<FlightData>()); // { 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 SessionStep,
-} from "@falai/agent";
-
-// Create a new session
-let session = createSession<FlightData>();
+// Access the session manager
+const sessionManager = agent.session;
 
-// Enter a route (when routing decides to switch)
-session = enterRoute(session, "book_flight", "Book Flight");
+// Get or create session (works for existing, new, or auto-generated IDs)
+await sessionManager.getOrCreate("user-123");
+await sessionManager.getOrCreate(); // Auto-generates ID
 
-// Enter a step (when progressing through the flow)
-session = enterStep(session, "ask_destination", "Ask where they want to fly");
-
-// Merge collected data (when AI extracts new information)
-session = mergeData(session, {
+// Data management
+const data = sessionManager.getData<FlightData>();
+await sessionManager.setData({
   destination: "Paris",
   departureDate: "2025-10-15",
   passengers: 2,
 });
+
+// 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
 
 ```typescript
-interface SessionStep<TData = unknown> {
+interface SessionState<TData = unknown> {
   currentRoute?: {
     id: string;
     title: string;
@@ -205,7 +208,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 +219,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 +231,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 +245,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 +270,8 @@ const searchFlights = defineTool<Context, [], void, FlightData>(
         shouldSearchFlights: false, // Clear the flag
       },
     };
-  }
-);
+  },
+};
 ```
 
 ### 4. Lifecycle Hooks for Validation & Enrichment
@@ -298,11 +309,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 +321,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 +379,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 +410,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 +481,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 +534,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 +592,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 +750,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 +761,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:

package/docs/{ARCHITECTURE.md → core/agent/session-management.md}

@@ -1,8 +1,8 @@
-# Architecture & Design Principles
+# Session Management
 
 ## Overview
 
-`@falai/agent` is built on a **schema-first, data-driven architecture** that prioritizes type safety, structured data extraction, and code-based step management over fuzzy LLM conditions. This creates predictable, maintainable, and efficient conversational AI agents.
+The `@falai/agent` framework provides **automatic session management** through the `SessionManager` class, eliminating the need for manual session creation, persistence, and state management. Sessions are automatically created, loaded, and saved, allowing developers to focus on building conversation logic rather than managing session lifecycle.
 
 ## Core Design Principles
 
@@ -46,60 +46,66 @@ const route = agent.createRoute<FlightData>({
 - **Predictability** - Same data structure every time
 - **Efficiency** - Extract multiple fields in one LLM call
 
-### 2. 📊 Session Step Management
+### 2. 🤖 Automatic Session Management
 
-Track conversation progress and collected data across turns:
+Sessions are automatically managed through the `SessionManager` class integrated into every `Agent`:
 
 ```typescript
-import { createSession, enterRoute, enterStep, mergeData } from "@falai/agent";
-
-// Create session with optional metadata including session ID
-let session = createSession<FlightData>(sessionId, {
-  userId: "user_456",
-  createdAt: new Date(),
+// Server-side: Agent with automatic session management
+const agent = new Agent({
+  name: "Travel Agent",
+  provider: new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }),
+  persistence: { adapter: new PrismaAdapter({ prisma }) },
+  sessionId: "user-123" // Automatically loads or creates this session
 });
 
-// Turn 1 - Extract data
-const response1 = await agent.respond({ history, session });
-session = response1.session!; // Updated with collected data
+// Simple conversation - no manual session management
+const response1 = await agent.respond("I want to book a flight to Paris");
+console.log(agent.session.id); // Session ID
+console.log(agent.session.getData()); // Collected data
 
-// Turn 2 - User changes mind (always-on routing)
-const response2 = await agent.respond({ history, session: response1.session });
-session = response2.session!; // Route/step updated if user changed direction
-
-// Access session metadata
-console.log(session.metadata?.sessionId); // "unique-session-123"
+// Continue conversation - session automatically maintained
+const response2 = await agent.respond("Make that Tokyo instead");
+// Session automatically updated with new data
 ```
 
-**Session with Persistence:**
+**SessionManager API:**
 
-When using persistence adapters, set the session ID from the database:
+The `SessionManager` provides a clean API for session operations:
 
 ```typescript
-// Create database session and in-memory session step
-const { sessionData, sessionStep } =
-  await persistence.createSessionWithStep<FlightData>({
-    userId: "user_123",
-    agentName: "Travel Agent",
-  });
-
-// sessionStep.metadata.sessionId is automatically set to sessionData.id
-console.log(sessionStep.metadata?.sessionId); // "cuid_from_database"
-
-// Use it in conversation
-const response = await agent.respond({
-  history,
-  session: sessionStep, // Auto-saves to database!
-});
+// Access the session manager
+const sessionManager = agent.session;
+
+// Get or create session (works for existing, new, or auto-generated IDs)
+await sessionManager.getOrCreate("user-123");
+await sessionManager.getOrCreate(); // Auto-generates ID
+
+// History management
+await sessionManager.addMessage("user", "Hello");
+await sessionManager.addMessage("assistant", "Hi there!");
+const history = sessionManager.getHistory();
+sessionManager.clearHistory();
+
+// Data access
+const data = sessionManager.getData<FlightData>();
+await sessionManager.setData({ destination: "Paris" });
+
+// Session operations
+await sessionManager.save(); // Manual save (auto-saves on addMessage)
+await sessionManager.delete();
+const newSession = await sessionManager.reset(true); // Preserve history
 ```
 
-**Why?** Session step enables:
+**Why?** Automatic session management provides:
 
+- **Zero Boilerplate** - No manual session creation or persistence code
+- **Server-Friendly** - Perfect for stateless server environments
 - **Always-on Routing** - Users can change their mind mid-conversation
 - **Context Awareness** - Router sees current progress and collected data
-- **Data Persistence** - Collected data survives across turns
-- **Step Recovery** - Resume conversations from any point
-- **Session Tracking** - Track conversations via session ID in database
+- **Data Persistence** - Collected data automatically saved and restored
+- **History Management** - Conversation history automatically maintained
+- **Session Tracking** - Easy session identification for client/server communication
 
 ### 3. 🔧 Code-Based Step Logic + AI-Driven Transitions
 
@@ -109,7 +115,7 @@ Use TypeScript functions for deterministic flow control AND text conditions for
 // Step with smart bypassing based on collected data
 const askDestination = route.initialStep.nextStep({
   id: "ask_destination", // Optional: custom step ID
-  instructions: "Ask where they want to fly",
+  prompt: "Ask where they want to fly",
   collect: ["destination"],
   skipIf: (data) => !!data.destination, // Code-based condition!
   condition: "Customer hasn't specified destination yet", // Text condition for AI
@@ -117,7 +123,7 @@ const askDestination = route.initialStep.nextStep({
 
 const askDate = askDestination.nextStep({
   id: "ask_date", // Optional: custom step ID for easier tracking
-  instructions: "Ask about travel dates",
+  prompt: "Ask about travel dates",
   collect: ["departureDate"],
   skipIf: (data) => !!data.departureDate,
   requires: ["destination"], // Prerequisites
@@ -133,7 +139,7 @@ You can optionally provide custom IDs for steps to make them easier to track and
 ```typescript
 const confirmBooking = askDate.nextStep({
   id: "confirm_booking", // ✅ Custom ID instead of auto-generated
-  instructions: "Confirm all booking details",
+  prompt: "Confirm all booking details",
   requires: ["destination", "departureDate", "passengers"],
 });
 ```
@@ -170,9 +176,16 @@ If you don't provide an ID, one is automatically generated from the route ID and
 Tools execute with full context including collected data:
 
 ```typescript
-const searchFlights = defineTool<Context, [], void, FlightData>(
-  "search_flights",
-  async (toolContext) => {
+import { Tool } from "@falai/agent";
+
+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) => {
     const { data, context, history } = toolContext;
 
     // Access collected data directly
@@ -188,8 +201,8 @@ const searchFlights = defineTool<Context, [], void, FlightData>(
         departureDateParsed: parseDate(data.departureDate),
       },
     };
-  }
-);
+  },
+};
 ```
 
 **Why?** Tools with data access enable:
@@ -207,7 +220,10 @@ Routing happens every turn, allowing users to change direction:
 // User starts booking a flight
 const response1 = await agent.respond({
   history: [
-    createMessageEvent(EventSource.CUSTOMER, "User", "I want to fly to Paris"),
+    {
+      role: "user",
+      content: "I want to fly to Paris",
+    },
   ],
   session,
 });
@@ -216,11 +232,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
 });
@@ -372,7 +387,7 @@ const bookingRoute = agent.createRoute<BookingData>({
 
 bookingRoute.initialStep
   .nextStep({
-    instructions: "Ask destination",
+    prompt: "Ask destination",
     collect: ["destination"],
     skipIf: (data) => !!data.destination,
   })
@@ -381,7 +396,7 @@ bookingRoute.initialStep
     requires: ["destination"],
   })
   .nextStep({
-    instructions: "Ask dates",
+    prompt: "Ask dates",
     collect: ["dates"],
     skipIf: (data) => !!data.dates,
   });
@@ -399,7 +414,7 @@ const qnaRoute = agent.createRoute({
 });
 
 // Just use initial step
-qnaRoute.initialStep.instructions = "Answer from knowledge base";
+qnaRoute.initialStep.prompt = "Answer from knowledge base";
 ```
 
 ### Mixed Architecture
@@ -436,9 +451,9 @@ This framework draws inspiration from:
 
 ## Further Reading
 
-- [Getting Started Guide](./GETTING_STARTED.md) - Build your first agent
+- [Getting Started Guide](../guides/getting-started/README.md) - Build your first agent
 - [Session Step Guide](./CONTEXT_MANAGEMENT.md) - Session management patterns
-- [API Reference](./API_REFERENCE.md) - Complete API documentation
+- [API Reference](../api/README.md) - Complete API documentation
 - [Examples](../examples/) - Real-world implementations
 
 ---