@falai/agent 0.9.0-alpha-2 → 0.9.2

package/dist/src/utils/history.js

@@ -5,25 +5,41 @@
 import { EventKind, MessageRole } from "../types";
 /**
  * Convert a simplified history item to an internal Event
+ * @param item - The HistoryItem to convert
+ * @returns Event with proper type-safe structure
+ * @throws Error if the history item is malformed or has invalid data
  */
-function convertHistoryItemToEvent(item) {
+export function historyItemToEvent(item) {
+    if (!item || typeof item !== 'object') {
+        throw new Error('Invalid history item: must be a non-null object');
+    }
+    if (!item.role || typeof item.role !== 'string') {
+        throw new Error('Invalid history item: role is required and must be a string');
+    }
     const timestamp = new Date().toISOString();
     switch (item.role) {
         case "user": {
+            const userItem = item;
+            if (typeof userItem.content !== 'string') {
+                throw new Error('Invalid user history item: content must be a string');
+            }
             return {
                 kind: EventKind.MESSAGE,
                 source: MessageRole.USER,
                 timestamp,
                 data: {
                     participant: {
-                        display_name: item.name || "User",
+                        display_name: userItem.name || "User",
                     },
-                    message: item.content,
+                    message: userItem.content,
                 },
             };
         }
         case "assistant": {
-            // Handle assistant message with optional tool calls
+            const assistantItem = item;
+            if (assistantItem.content !== null && typeof assistantItem.content !== 'string') {
+                throw new Error('Invalid assistant history item: content must be a string or null');
+            }
             const event = {
                 kind: EventKind.MESSAGE,
                 source: MessageRole.ASSISTANT,
@@ -32,17 +48,31 @@ function convertHistoryItemToEvent(item) {
                     participant: {
                         display_name: "Assistant",
                     },
-                    message: item.content || "",
+                    message: assistantItem.content || "",
                 },
             };
-            // If there are tool calls, we need to create a separate tool event
-            // But for now, we'll just store the tool calls in the message data
-            if (item.tool_calls && item.tool_calls.length > 0) {
-                event.data.toolCalls = item.tool_calls;
+            // If there are tool calls, validate and add them
+            if (assistantItem.tool_calls && assistantItem.tool_calls.length > 0) {
+                if (!Array.isArray(assistantItem.tool_calls)) {
+                    throw new Error('Invalid assistant history item: tool_calls must be an array');
+                }
+                for (const toolCall of assistantItem.tool_calls) {
+                    if (!toolCall.id || !toolCall.name || typeof toolCall.arguments !== 'object') {
+                        throw new Error('Invalid tool call: id, name, and arguments are required');
+                    }
+                }
+                event.data.toolCalls = assistantItem.tool_calls;
             }
             return event;
         }
         case "tool": {
+            const toolItem = item;
+            if (!toolItem.tool_call_id || typeof toolItem.tool_call_id !== 'string') {
+                throw new Error('Invalid tool history item: tool_call_id is required and must be a string');
+            }
+            if (!toolItem.name || typeof toolItem.name !== 'string') {
+                throw new Error('Invalid tool history item: name is required and must be a string');
+            }
             return {
                 kind: EventKind.TOOL,
                 source: MessageRole.AGENT,
@@ -50,10 +80,10 @@ function convertHistoryItemToEvent(item) {
                 data: {
                     tool_calls: [
                         {
-                            tool_id: item.tool_call_id,
+                            tool_id: toolItem.tool_call_id,
                             arguments: {}, // Tool results don't have arguments
                             result: {
-                                data: item.content,
+                                data: toolItem.content,
                             },
                         },
                     ],
@@ -61,6 +91,10 @@ function convertHistoryItemToEvent(item) {
             };
         }
         case "system": {
+            const systemItem = item;
+            if (typeof systemItem.content !== 'string') {
+                throw new Error('Invalid system history item: content must be a string');
+            }
             return {
                 kind: EventKind.MESSAGE,
                 source: MessageRole.SYSTEM,
@@ -69,30 +103,138 @@ function convertHistoryItemToEvent(item) {
                     participant: {
                         display_name: "System",
                     },
-                    message: item.content,
+                    message: systemItem.content,
                 },
             };
         }
         default:
-            // This should never happen due to TypeScript, but fallback just in case
+            throw new Error(`Invalid history item role: ${String(item.role)}`);
+    }
+}
+/**
+ * Convert an array of HistoryItems to Events
+ * @param history - Array of HistoryItems to convert
+ * @returns Array of Events with proper type-safe structure
+ * @throws Error if any history item is malformed
+ */
+export function historyToEvents(history) {
+    if (!Array.isArray(history)) {
+        throw new Error('Invalid history: must be an array');
+    }
+    return history.map((item, index) => {
+        try {
+            return historyItemToEvent(item);
+        }
+        catch (error) {
+            throw new Error(`Error converting history item at index ${index}: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    });
+}
+/**
+ * Convert an Event back to a HistoryItem
+ * @param event - The Event to convert
+ * @returns HistoryItem with simplified structure
+ * @throws Error if the event is malformed or has invalid data
+ */
+export function eventToHistoryItem(event) {
+    if (!event || typeof event !== 'object') {
+        throw new Error('Invalid event: must be a non-null object');
+    }
+    if (!event.kind || !event.source || !event.data) {
+        throw new Error('Invalid event: kind, source, and data are required');
+    }
+    switch (event.kind) {
+        case EventKind.MESSAGE: {
+            const messageData = event.data;
+            if (!messageData.message && messageData.message !== '') {
+                throw new Error('Invalid message event: message is required');
+            }
+            switch (event.source) {
+                case MessageRole.USER: {
+                    const userItem = {
+                        role: "user",
+                        content: messageData.message,
+                    };
+                    if (messageData.participant?.display_name && messageData.participant.display_name !== "User") {
+                        userItem.name = messageData.participant.display_name;
+                    }
+                    return userItem;
+                }
+                case MessageRole.ASSISTANT: {
+                    const assistantItem = {
+                        role: "assistant",
+                        content: messageData.message || null,
+                    };
+                    if (messageData.toolCalls && messageData.toolCalls.length > 0) {
+                        assistantItem.tool_calls = messageData.toolCalls;
+                    }
+                    return assistantItem;
+                }
+                case MessageRole.SYSTEM: {
+                    return {
+                        role: "system",
+                        content: messageData.message,
+                    };
+                }
+                default:
+                    throw new Error(`Unsupported message source for conversion: ${event.source}`);
+            }
+        }
+        case EventKind.TOOL: {
+            const toolData = event.data;
+            if (!toolData.tool_calls || !Array.isArray(toolData.tool_calls) || toolData.tool_calls.length === 0) {
+                throw new Error('Invalid tool event: tool_calls array is required and must not be empty');
+            }
+            const firstToolCall = toolData.tool_calls[0];
+            if (!firstToolCall.tool_id) {
+                throw new Error('Invalid tool call: tool_id is required');
+            }
+            const toolItem = {
+                role: "tool",
+                tool_call_id: firstToolCall.tool_id,
+                name: firstToolCall.tool_id, // Use tool_id as name for simplicity
+                content: firstToolCall.result?.data,
+            };
+            return toolItem;
+        }
+        case EventKind.STATUS: {
+            // Status events don't have a direct HistoryItem equivalent
+            // Convert to system message for compatibility
+            const statusData = event.data;
             return {
-                kind: EventKind.MESSAGE,
-                source: MessageRole.SYSTEM,
-                timestamp,
-                data: {
-                    participant: {
-                        display_name: "Unknown",
-                    },
-                    message: "Unknown message type",
-                },
+                role: "system",
+                content: statusData.status || "Status update",
             };
+        }
+        default:
+            throw new Error(`Unsupported event kind for conversion: ${String(event.kind)}`);
+    }
+}
+/**
+ * Convert an array of Events back to HistoryItems
+ * @param events - Array of Events to convert
+ * @returns Array of HistoryItems with simplified structure
+ * @throws Error if any event is malformed
+ */
+export function eventsToHistory(events) {
+    if (!Array.isArray(events)) {
+        throw new Error('Invalid events: must be an array');
     }
+    return events.map((event, index) => {
+        try {
+            return eventToHistoryItem(event);
+        }
+        catch (error) {
+            throw new Error(`Error converting event at index ${index}: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    });
 }
 /**
  * Normalize a simplified history array to internal Event array
+ * @deprecated Use historyToEvents instead
  */
 export function normalizeHistory(history) {
-    return history.map(convertHistoryItemToEvent);
+    return historyToEvents(history);
 }
 /**
  * Helper function to create a user message

package/dist/src/utils/history.js.map

@@ -1 +1 @@
-{"version":3,"file":"history.js","sourceRoot":"","sources":["../../../src/utils/history.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"history.js","sourceRoot":"","sources":["../../../src/utils/history.ts"],"names":[],"mappings":"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"}

package/dist/src/utils/index.d.ts

@@ -6,7 +6,7 @@ export { createSession, createSessionId, enterRoute, enterStep, mergeCollected,
 export { render, renderMany, renderTemplate, renderTemplateObject, formatKnowledgeBase, } from "./template";
 export { cloneDeep } from "./clone";
 export { getLastMessageFromHistory } from "./event";
-export { normalizeHistory, userMessage, assistantMessage, toolMessage, systemMessage, } from "./history";
+export { normalizeHistory, historyItemToEvent, historyToEvents, eventToHistoryItem, eventsToHistory, userMessage, assistantMessage, toolMessage, systemMessage, } from "./history";
 export { LoggerLevel, logger } from "./logger";
 export type { RetryOptions } from "./retry";
 export { retry, withTimeoutAndRetry } from "./retry";

package/dist/src/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EACL,eAAe,EACf,cAAc,EACd,cAAc,EACd,oBAAoB,GACrB,MAAM,MAAM,CAAC;AAGd,OAAO,EACL,aAAa,EACb,eAAe,EACf,UAAU,EACV,SAAS,EACT,cAAc,EACd,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,MAAM,EACN,UAAU,EACV,cAAc,EACd,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAGpC,OAAO,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAC;AAGpD,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,aAAa,GACd,MAAM,WAAW,CAAC;AAGnB,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAG/C,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EACL,eAAe,EACf,cAAc,EACd,cAAc,EACd,oBAAoB,GACrB,MAAM,MAAM,CAAC;AAGd,OAAO,EACL,aAAa,EACb,eAAe,EACf,UAAU,EACV,SAAS,EACT,cAAc,EACd,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,MAAM,EACN,UAAU,EACV,cAAc,EACd,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAGpC,OAAO,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAC;AAGpD,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,aAAa,GACd,MAAM,WAAW,CAAC;AAGnB,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAG/C,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC"}

package/dist/src/utils/index.js

@@ -12,7 +12,7 @@ export { cloneDeep } from "./clone";
 // Event utilities
 export { getLastMessageFromHistory } from "./event";
 // History utilities
-export { normalizeHistory, userMessage, assistantMessage, toolMessage, systemMessage, } from "./history";
+export { normalizeHistory, historyItemToEvent, historyToEvents, eventToHistoryItem, eventsToHistory, userMessage, assistantMessage, toolMessage, systemMessage, } from "./history";
 // Logging
 export { LoggerLevel, logger } from "./logger";
 export { retry, withTimeoutAndRetry } from "./retry";

package/dist/src/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,gBAAgB;AAChB,OAAO,EACL,eAAe,EACf,cAAc,EACd,cAAc,EACd,oBAAoB,GACrB,MAAM,MAAM,CAAC;AAEd,qBAAqB;AACrB,OAAO,EACL,aAAa,EACb,eAAe,EACf,UAAU,EACV,SAAS,EACT,cAAc,EACd,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,WAAW,CAAC;AAEnB,qBAAqB;AACrB,OAAO,EACL,MAAM,EACN,UAAU,EACV,cAAc,EACd,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAEpB,oBAAoB;AACpB,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEpC,kBAAkB;AAClB,OAAO,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAC;AAEpD,oBAAoB;AACpB,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,aAAa,GACd,MAAM,WAAW,CAAC;AAEnB,UAAU;AACV,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAI/C,OAAO,EAAE,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,gBAAgB;AAChB,OAAO,EACL,eAAe,EACf,cAAc,EACd,cAAc,EACd,oBAAoB,GACrB,MAAM,MAAM,CAAC;AAEd,qBAAqB;AACrB,OAAO,EACL,aAAa,EACb,eAAe,EACf,UAAU,EACV,SAAS,EACT,cAAc,EACd,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,WAAW,CAAC;AAEnB,qBAAqB;AACrB,OAAO,EACL,MAAM,EACN,UAAU,EACV,cAAc,EACd,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAEpB,oBAAoB;AACpB,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEpC,kBAAkB;AAClB,OAAO,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAC;AAEpD,oBAAoB;AACpB,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,aAAa,GACd,MAAM,WAAW,CAAC;AAEnB,UAAU;AACV,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAI/C,OAAO,EAAE,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC"}

package/docs/CONTRIBUTING.md

@@ -39,6 +39,46 @@ This project and everyone participating in it is governed by our commitment to f
 
 ---
 
+## Tool System Overview
+
+@falai/agent features a unified Tool interface that supports both simple return values and complex ToolResult patterns:
+
+### Unified Tool Interface
+
+```typescript
+interface Tool<TContext = unknown, TData = unknown, TResult = unknown> {
+  id: string;
+  name?: string;
+  description?: string;
+  parameters?: unknown;
+  handler: (
+    context: ToolContext<TContext, TData>,
+    args?: Record<string, unknown>
+  ) => Promise<TResult | ToolResult<TResult, TContext, TData>> | TResult | ToolResult<TResult, TContext, TData>;
+}
+```
+
+### Tool Creation Methods
+
+- **`agent.addTool()`** - Direct addition to agent scope
+- **`agent.tool.register()`** - Registry for ID-based reference
+- **`agent.tool.create()`** - Create without adding to scope
+- **Pattern helpers** - `createDataEnrichment()`, `createValidation()`, etc.
+
+### Return Value Flexibility
+
+```typescript
+// Simple return value
+handler: async () => "Simple result"
+
+// Complex ToolResult object
+handler: async () => ({
+  data: "Result data",
+  success: true,
+  contextUpdate: { lastAction: "completed" }
+})
+```
+
 ## How Can I Contribute?
 
 ### 🐛 Reporting Bugs

package/docs/README.md

@@ -8,8 +8,9 @@ Welcome to the `@falai/agent` documentation! This comprehensive framework enable
 - 🎯 **Schema-First Data Collection**: Type-safe, structured data extraction from natural conversations
 - 🔀 **Route DSL**: Fluent, composable API for building complex multi-step conversation flows
 - 🏗️ **Type-Safe Context**: Generic context management with lifecycle hooks and dynamic providers
-- 🔄 **Streaming & Tools**: Real-time streaming responses with dynamic tool execution
+- 🔄 **Streaming & Tools**: Real-time streaming responses with dynamic tool execution using unified Tool interface
 - 💾 **Comprehensive Persistence**: Database-agnostic session and message storage across multiple adapters
+- 🛠️ **Unified Tool System**: Simplified tool creation with flexible return types and powerful pattern helpers
 
 ## 📖 Documentation Structure
 
@@ -54,10 +55,16 @@ Welcome to the `@falai/agent` documentation! This comprehensive framework enable
 - **[Session Storage](./core/persistence/session-storage.md)** - Session persistence patterns
 - **[Database Adapters](./core/persistence/adapters.md)** - Built-in adapter configurations
 
+#### Error Handling
+
+- **[Error Handling](./core/error-handling.md)** - Comprehensive error handling patterns and recovery strategies
+- **[Error Handling Patterns](./guides/error-handling-patterns.md)** - Practical patterns for streaming, routing, and data sync errors
+
 ### 🚀 Advanced Guides
 
 - **[Building Agents](./guides/building-agents/)** - Complete agent construction patterns
 - **[Advanced Patterns](./guides/advanced-patterns/)** - Complex use cases & integrations
+- **[Migration Guides](./guides/migration/)** - Upgrade guides for major changes
 - **[API Reference](./api/README.md)** - Complete API documentation
 
 ## 🎯 Quick Links
@@ -93,7 +100,8 @@ Welcome to the `@falai/agent` documentation! This comprehensive framework enable
 - **AI Integration**: [Providers](./core/ai-integration/providers.md) | [Prompts](./core/ai-integration/prompt-composition.md) | [Responses](./core/ai-integration/response-processing.md)
 - **Tools & Execution**: [Tool Definition](./core/tools/tool-definition.md) | [Tool Execution](./core/tools/tool-execution.md) | [Tool Scoping](./core/tools/tool-scoping.md)
 - **Persistence**: [Session Storage](./core/persistence/session-storage.md) | [Adapters](./core/persistence/adapters.md)
-- **Advanced**: [Building Agents](./guides/building-agents/) | [Patterns](./guides/advanced-patterns/) | [API Reference](./api/)
+- **Error Handling**: [Core Error Handling](./core/error-handling.md) | [Error Patterns](./guides/error-handling-patterns.md)
+- **Advanced**: [Building Agents](./guides/building-agents/) | [Patterns](./guides/advanced-patterns/) | [Migration](./guides/migration/) | [API Reference](./api/)
 
 ## 💡 Examples by Domain
 
@@ -128,10 +136,10 @@ Check out the [`examples/`](../examples/) directory for complete, runnable examp
 
 ### 🔧 Tools & Execution
 
-- **[Basic Tools](../examples/tools/basic-tools.ts)** - Simple tool creation and execution
-- **[Data Enrichment Tools](../examples/tools/data-enrichment-tools.ts)** - Tools that modify collected data
-- **[Context Updating Tools](../examples/tools/context-updating-tools.ts)** - Tools that modify agent context
-- **[Domain Scoped Tools](../examples/tools/domain-scoped-tools.ts)** - Tool security and access control
+- **[Basic Tools](../examples/tools/basic-tools.ts)** - Unified Tool interface with simple return values
+- **[Data Enrichment Tools](../examples/tools/data-enrichment-tools.ts)** - Pattern helpers for data modification
+- **[Context Updating Tools](../examples/tools/context-updating-tools.ts)** - Advanced ToolResult patterns with context updates
+- **[Domain Scoped Tools](../examples/tools/domain-scoped-tools.ts)** - Tool registry and scoping with agent.tool.register()
 
 ### 💾 Persistence