@falai/agent 0.9.0-alpha-2 → 0.9.0

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/README.md

@@ -58,6 +58,7 @@ Welcome to the `@falai/agent` documentation! This comprehensive framework enable
 
 - **[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 +94,7 @@ 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/)
+- **Advanced**: [Building Agents](./guides/building-agents/) | [Patterns](./guides/advanced-patterns/) | [Migration](./guides/migration/) | [API Reference](./api/)
 
 ## 💡 Examples by Domain
 

package/docs/api/README.md

@@ -78,6 +78,8 @@ Adds a behavioral guideline. Returns `this` for chaining.
 
 Generates an AI response with session step management, tool execution, data extraction, and intelligent routing.
 
+**Note:** This method now delegates to the internal `ResponseModal` class for improved architecture and maintainability.
+
 **Enhanced Response Pipeline:**
 
 1. **Tool Execution** - Execute tools if current step has `tool` (enriches context before AI response)
@@ -454,6 +456,8 @@ See also: [Custom Database Integration Example](../examples/custom-database-pers
 
 Generates an AI response as a real-time stream for better user experience. Provides the same structured output as `respond()` but delivers it incrementally.
 
+**Note:** This method now delegates to the internal `ResponseModal` class for improved architecture and maintainability.
+
 ```typescript
 interface StreamChunk {
   /** The incremental text delta */
@@ -515,6 +519,68 @@ for await (const chunk of agent.respondStream({ history, session })) {
 }
 ```
 
+##### `stream(message?: string, options?: StreamOptions<TContext>): AsyncGenerator<AgentResponseStreamChunk<TData>>`
+
+**NEW:** Modern streaming API that provides a simple interface similar to `chat()` but returns a stream. This is the recommended way to implement streaming responses.
+
+```typescript
+interface StreamOptions<TContext = unknown> {
+  contextOverride?: Partial<TContext>;
+  signal?: AbortSignal;
+  history?: History; // Optional: override session history
+}
+```
+
+**Key Features:**
+
+- 🎯 **Simple Interface**: Just `agent.stream("message")` - no complex parameters
+- 🔄 **Automatic Session Management**: Handles conversation history automatically
+- 🌊 **Real-time Streaming**: Same performance as `respondStream()` but easier to use
+- 🛑 **Cancellable**: Supports AbortSignal for cancellation
+
+**Example:**
+
+```typescript
+// Simple streaming - automatically manages session history
+for await (const chunk of agent.stream("Hello, how are you?")) {
+  if (chunk.delta) {
+    process.stdout.write(chunk.delta);
+  }
+  
+  if (chunk.done) {
+    console.log("\n✅ Stream complete!");
+    // Session history is automatically updated
+  }
+}
+
+// With cancellation
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 5000); // Cancel after 5s
+
+for await (const chunk of agent.stream("Tell me a long story", {
+  signal: controller.signal
+})) {
+  process.stdout.write(chunk.delta);
+}
+```
+
+**Migration from `respondStream()`:**
+
+```typescript
+// Old way (still supported)
+for await (const chunk of agent.respondStream({
+  history: agent.session.getHistory(),
+  session: await agent.session.getOrCreate()
+})) {
+  // Handle chunk
+}
+
+// New way (recommended)
+for await (const chunk of agent.stream("Your message")) {
+  // Handle chunk - session management is automatic
+}
+```
+
 **With Cancellation:**
 
 ```typescript
@@ -582,6 +648,100 @@ Agent's identity template (readonly).
 
 ---
 
+### `ResponseModal<TContext, TData>`
+
+**NEW:** Internal class that handles all response generation logic for the Agent. This class centralizes response processing, provides unified streaming and non-streaming APIs, and improves maintainability.
+
+**Note:** This class is primarily used internally by the Agent class. Most users should use the Agent's response methods (`respond`, `respondStream`, `stream`, `chat`) rather than accessing ResponseModal directly.
+
+#### Constructor
+
+```typescript
+new ResponseModal<TContext, TData>(
+  agent: Agent<TContext, TData>,
+  options?: ResponseModalOptions
+)
+
+interface ResponseModalOptions {
+  /** Maximum number of tool loops allowed during response generation */
+  maxToolLoops?: number;
+  /** Enable automatic session saving after response generation */
+  enableAutoSave?: boolean;
+  /** Enable debug mode for detailed logging */
+  debugMode?: boolean;
+}
+```
+
+#### Methods
+
+##### `respond(params: RespondParams<TContext, TData>): Promise<AgentResponse<TData>>`
+
+Generates a non-streaming response using unified logic. This method consolidates all response generation logic including routing, tool execution, and data collection.
+
+##### `respondStream(params: RespondParams<TContext, TData>): AsyncGenerator<AgentResponseStreamChunk<TData>>`
+
+Generates a streaming response using unified logic. Provides the same functionality as `respond()` but delivers results incrementally.
+
+##### `stream(message?: string, options?: StreamOptions<TContext>): AsyncGenerator<AgentResponseStreamChunk<TData>>`
+
+Modern streaming API with automatic session management. This is the recommended way to implement streaming responses.
+
+```typescript
+// Simple usage
+for await (const chunk of responseModal.stream("Hello")) {
+  console.log(chunk.delta);
+}
+
+// With options
+for await (const chunk of responseModal.stream("Hello", {
+  contextOverride: { userId: "123" },
+  signal: abortController.signal
+})) {
+  console.log(chunk.delta);
+}
+```
+
+##### `generate(message?: string, options?: GenerateOptions<TContext>): Promise<AgentResponse<TData>>`
+
+Modern non-streaming API equivalent to `chat()` but more explicit. Provides automatic session management for non-streaming responses.
+
+```typescript
+// Simple usage
+const response = await responseModal.generate("Hello");
+console.log(response.message);
+
+// With options
+const response = await responseModal.generate("Hello", {
+  contextOverride: { userId: "123" }
+});
+```
+
+#### Error Handling
+
+ResponseModal includes comprehensive error handling with the `ResponseGenerationError` class:
+
+```typescript
+try {
+  const response = await responseModal.respond(params);
+} catch (error) {
+  if (ResponseGenerationError.isResponseGenerationError(error)) {
+    console.log("Response generation failed:", error.message);
+    console.log("Phase:", error.details?.phase);
+    console.log("Original error:", error.details?.originalError);
+  }
+}
+```
+
+#### Architecture Benefits
+
+- **Separation of Concerns**: Agent focuses on configuration and orchestration, ResponseModal handles response generation
+- **Unified Logic**: Both streaming and non-streaming responses use the same underlying logic
+- **Modern APIs**: Provides simple `stream()` and `generate()` methods alongside legacy compatibility
+- **Error Handling**: Comprehensive error handling with detailed context
+- **Performance**: Optimized response pipeline with minimal duplication
+
+---
+
 ### `Route`
 
 Represents a conversation flow with steps and transitions.

package/docs/api/overview.md

@@ -6,6 +6,7 @@ Complete API documentation for `@falai/agent`. This framework provides a strongl
 
 - [Core Classes](#core-classes)
   - [Agent](#agent)
+  - [ResponseModal](#responsemodal)
   - [Route](#route)
   - [Step](#step)
   - [RoutingEngine](#routingengine)
@@ -117,7 +118,20 @@ respondStream(params: {
 }>
 ```
 
-Generates a streaming response with real-time updates.
+Generates a streaming response with real-time updates. **Note:** Now delegates to internal ResponseModal class.
+
+```typescript
+stream(message?: string, options?: StreamOptions<TContext>): AsyncGenerator<AgentResponseStreamChunk<TData>>
+```
+
+**NEW:** Modern streaming API with automatic session management. Recommended for new implementations.
+
+```typescript
+// Simple streaming
+for await (const chunk of agent.stream("Hello")) {
+  console.log(chunk.delta);
+}
+```
 
 ##### Tool Management
 
@@ -168,6 +182,57 @@ hasPersistence(): boolean
 
 ---
 
+### ResponseModal
+
+**NEW:** Internal class that centralizes all response generation logic for improved architecture and maintainability.
+
+#### Constructor
+
+```typescript
+new ResponseModal<TContext = unknown, TData = unknown>(
+  agent: Agent<TContext, TData>,
+  options?: ResponseModalOptions
+)
+```
+
+#### Methods
+
+##### Modern APIs (Recommended)
+
+```typescript
+stream(message?: string, options?: StreamOptions<TContext>): AsyncGenerator<AgentResponseStreamChunk<TData>>
+generate(message?: string, options?: GenerateOptions<TContext>): Promise<AgentResponse<TData>>
+```
+
+Modern streaming and non-streaming APIs with automatic session management.
+
+##### Legacy APIs (Backward Compatible)
+
+```typescript
+respond(params: RespondParams<TContext, TData>): Promise<AgentResponse<TData>>
+respondStream(params: RespondParams<TContext, TData>): AsyncGenerator<AgentResponseStreamChunk<TData>>
+```
+
+Legacy APIs that maintain full backward compatibility with existing code.
+
+##### Error Handling
+
+```typescript
+ResponseGenerationError: Error class for response-specific errors
+```
+
+Comprehensive error handling with detailed context and phase information.
+
+#### Key Features
+
+- **Unified Logic**: Both streaming and non-streaming use the same underlying logic
+- **Modern APIs**: Simple `stream()` and `generate()` methods for new code
+- **Backward Compatibility**: Existing `respond()` and `respondStream()` methods work unchanged
+- **Error Handling**: Detailed error context with phase and original error information
+- **Performance**: Optimized response pipeline with minimal code duplication
+
+---
+
 ### Route
 
 Represents a conversational journey with required fields specification and steps that collect data into the agent-level schema.