@falai/agent 0.9.0 → 0.9.2

package/docs/api/README.md

@@ -74,6 +74,72 @@ Adds a domain glossary term. Returns `this` for chaining.
 
 Adds a behavioral guideline. Returns `this` for chaining.
 
+##### `addTool(definition: Tool<TContext, TData, TResult>): this`
+
+Creates and adds a tool to agent scope using the unified Tool interface. Returns `this` for chaining.
+
+```typescript
+// Simple return value approach
+agent.addTool({
+  id: "weather_check",
+  description: "Get current weather",
+  parameters: {
+    type: "object",
+    properties: {
+      location: { type: "string", description: "City name" }
+    },
+    required: ["location"]
+  },
+  handler: async ({ context, data }, args) => {
+    const weather = await weatherAPI.get(args.location);
+    return `Weather in ${args.location}: ${weather.condition}`;
+  }
+});
+
+// Advanced ToolResult pattern
+agent.addTool({
+  id: "user_lookup",
+  description: "Look up user information",
+  handler: async ({ context, data }, args) => {
+    const user = await userAPI.find(args.userId);
+    return {
+      data: `Found user: ${user.name}`,
+      success: true,
+      contextUpdate: { currentUser: user },
+      dataUpdate: { userName: user.name }
+    };
+  }
+});
+```
+
+##### `tool: ToolManager<TContext, TData>`
+
+Access to the ToolManager instance for advanced tool operations.
+
+```typescript
+// Register tools for ID-based reference
+agent.tool.register({
+  id: "reusable_search",
+  description: "Search across data sources",
+  handler: async ({ context, data }, args) => "Search results"
+});
+
+// Create tools without adding to scope
+const customTool = agent.tool.create({
+  id: "standalone_tool",
+  handler: async () => "Custom result"
+});
+
+// Use pattern helpers
+const enrichmentTool = agent.tool.createDataEnrichment({
+  id: "enrich_profile",
+  fields: ['name', 'email'],
+  enricher: async (context, data) => ({
+    displayName: `${data.name} <${data.email}>`
+  })
+});
+```
+
 ##### `respond(input: RespondInput<TContext>): Promise<RespondOutput>`
 
 Generates an AI response with session step management, tool execution, data extraction, and intelligent routing.
@@ -957,7 +1023,7 @@ Represents a step within a conversation route.
 
 #### Methods
 
-##### `nextStep(spec: StepOptions): StepResult`
+##### `nextStep(spec: StepOptions): Step`
 
 Creates a transition from this step and returns a chainable result.
 
@@ -982,10 +1048,14 @@ interface StepOptions<TData = unknown> {
   condition?: string;
 }
 
-interface StepResult<TData = unknown> {
+interface Step<TContext = unknown, TData = unknown> {
   id: string; // Step identifier
   routeId: string; // Route identifier
-  nextStep: (spec: StepOptions<TData>) => StepResult<TData>;
+  nextStep: (spec: StepOptions<TContext, TData>) => Step<TContext, TData>;
+  description?: string; // Step description
+  collect?: (keyof TData)[]; // Fields to collect in this step
+  skipIf?: (data: Partial<TData>) => boolean; // Skip condition function
+  requires?: (keyof TData)[]; // Required data prerequisites
 }
 ```
 
@@ -993,7 +1063,7 @@ interface StepResult<TData = unknown> {
 
 - `spec`: The transition specification (see `StepOptions` above). Can include an optional `condition` property for AI-evaluated step selection guidance.
 
-**Returns:** A `StepResult` that includes the target step's reference (`id`, `routeId`) and a `nextStep` method for chaining additional transitions.
+**Returns:** A `Step` that includes the target step's reference (`id`, `routeId`) and a `nextStep` method for chaining additional transitions.
 
 **Example:**
 
@@ -1110,14 +1180,7 @@ if (step.hasRequires(session.data)) {
 }
 ```
 
-##### `asStepResult(): StepResult<TContext, TData>`
 
-Creates a transition result for this step that supports chaining.
-
-```typescript
-const result = step.asStepResult();
-// Returns StepResult with nextStep method for chaining
-```
 
 ##### `configure(config): this`
 
@@ -1566,39 +1629,6 @@ Builds a fallback prompt when no routes are configured.
 
 ---
 
-### `ToolExecutor<TContext, TData>`
-
-Executes tools with context and security enforcement.
-
-#### Constructor
-
-```typescript
-new ToolExecutor<TContext, TData>();
-```
-
-#### Methods
-
-##### `executeTool(params): Promise<ToolExecutionResult>`
-
-Executes a single tool with domain security enforcement.
-
-**Parameters:**
-
-- `tool`: Tool reference to execute
-- `context`: Agent context
-- `updateContext`: Function to update context
-- `history`: Conversation history
-- `data`: Collected session data
-- `allowedDomains`: Array of allowed domain names
-
-**Returns:** Tool execution result with success status and data
-
-##### `executeTools(params): Promise<ToolExecutionResult[]>`
-
-Executes multiple tools in sequence, stopping on first failure.
-
----
-
 ### `Events`
 
 Utility functions for creating and adapting conversation events.
@@ -3016,4 +3046,4 @@ agent.createGuideline({
 
 ---
 
-**Made with ❤️ for the community**
+**Made with ❤️ for the community**

package/docs/api/overview.md

@@ -12,7 +12,7 @@ Complete API documentation for `@falai/agent`. This framework provides a strongl
   - [RoutingEngine](#routingengine)
   - [ResponseEngine](#responseengine)
   - [PromptComposer](#promptcomposer)
-  - [ToolExecutor](#toolexecutor)
+
 - [AI Providers](#ai-providers)
 - [Persistence Adapters](#persistence-adapters)
 - [Types & Interfaces](#types--interfaces)
@@ -136,9 +136,58 @@ for await (const chunk of agent.stream("Hello")) {
 ##### Tool Management
 
 ```typescript
-createTool(tool: Tool<TContext, unknown[], unknown, unknown>): this
-registerTools(tools: Tool<TContext, unknown[], unknown, unknown>[]): this
-getTools(): Tool<TContext, unknown[], unknown, unknown>[]
+addTool(definition: Tool<TContext, TData, TResult>): this
+tool: ToolManager<TContext, TData> // Access to ToolManager instance
+```
+
+**Comprehensive Tool Examples:**
+
+```typescript
+// 1. Simple return value (most common)
+agent.addTool({
+  id: "calculate_tip",
+  description: "Calculate tip amount",
+  handler: async ({ context, data }, args) => {
+    const tip = args.amount * args.percentage;
+    return `Tip: $${tip.toFixed(2)}`; // Simple string return
+  }
+});
+
+// 2. Complex ToolResult pattern
+agent.addTool({
+  id: "process_order",
+  description: "Process customer order",
+  handler: async ({ context, data }, args) => {
+    const order = await orderService.process(args.items);
+    return {
+      data: `Order ${order.id} processed successfully`,
+      success: true,
+      contextUpdate: { lastOrderId: order.id },
+      dataUpdate: { orderStatus: 'processed' }
+    }; // Detailed ToolResult object
+  }
+});
+
+// 3. Registry for reuse
+agent.tool.register({
+  id: "send_notification",
+  description: "Send notification to user",
+  handler: async ({ context }, args) => {
+    await notificationService.send(context.userId, args.message);
+    return "Notification sent"; // Simple return
+  }
+});
+
+// 4. Pattern helper
+const validationTool = agent.tool.createValidation({
+  id: "validate_email",
+  fields: ['email'],
+  validator: async (context, data) => ({
+    valid: /\S+@\S+\.\S+/.test(data.email),
+    errors: []
+  })
+});
+agent.tool.register(validationTool);
 ```
 
 ##### Domain Knowledge
@@ -301,9 +350,7 @@ getRoutingExtrasSchema(): StructuredSchema | undefined
 ##### Tool Management
 
 ```typescript
-createTool(tool: Tool<TContext, unknown[], unknown, TData>): this
-registerTools(tools: Tool<TContext, unknown[], unknown, TData>[]): this
-getTools(): Tool<TContext, unknown[], unknown, TData>[]
+addTool(definition: Tool<TContext, TData, TResult>): this
 ```
 
 ##### Lifecycle Hooks
@@ -347,9 +394,9 @@ configure(config: Partial<StepOptions<TContext, TData>>): this
 ##### Transitions
 
 ```typescript
-nextStep(spec: StepOptions<TContext, TData>): StepResult<TContext, TData>
+nextStep(spec: StepOptions<TContext, TData>): Step<TContext, TData>
 branch(branches: BranchSpec<TContext, TData>[]): BranchResult<TContext, TData>
-endRoute(options?: Omit<StepOptions<TContext, TData>, 'step'>): StepResult<TContext, TData>
+endRoute(options?: Omit<StepOptions<TContext, TData>, 'step'>): Step<TContext, TData>
 ```
 
 ##### Validation
@@ -371,7 +418,6 @@ getTransitions(): Step<TContext, TData>[]
 
 ```typescript
 getRef(): StepRef
-asStepResult(): StepResult<TContext, TData>
 ```
 
 ---
@@ -505,23 +551,7 @@ addDirectives(directives?: string[]): Promise<this>
 build(): Promise<string>
 ```
 
----
-
-### ToolExecutor
-
-Handles tool execution with context updates and data collection.
 
-#### Methods
-
-```typescript
-executeTool(params: {
-  tool: Tool;
-  context: unknown;
-  updateContext: (updates: Partial<unknown>) => Promise<void>;
-  history: Event[];
-  data: unknown;
-}): Promise<ToolExecutionResult>
-```
 
 ---
 
@@ -756,21 +786,33 @@ interface StepOptions<TContext = unknown, TData = unknown> {
   }
 }
 
-// Example: Using existing tools (new approach)
+// Example: Using existing tools (unified Tool interface)
 {
-  prepare: "validate_user_data",  // Tool ID string
-  finalize: myCustomTool,         // Tool object
+  prepare: "validate_user_data",  // Tool ID string - simple return value
+  finalize: "send_notification",  // Tool ID string - ToolResult pattern
 }
 
-// Example: Inline tool definition
+// Example: Inline tool definition with flexible returns
 {
   prepare: {
     id: "setup_step_context",
     description: "Prepare context for this step",
     parameters: { type: "object", properties: {} },
     handler: ({ context, data }) => {
-      // Custom logic here
-      return { data: "Setup complete" };
+      // Simple return value
+      return "Setup complete";
+    }
+  },
+  finalize: {
+    id: "cleanup_step_context", 
+    description: "Clean up after step completion",
+    handler: ({ context, data }) => {
+      // Complex ToolResult pattern
+      return {
+        data: "Cleanup complete",
+        success: true,
+        contextUpdate: { lastCleanup: new Date() }
+      };
     }
   }
 }

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