@dexto/core 1.1.4 → 1.1.6

package/dist/session/chat-session.d.cts

@@ -0,0 +1,284 @@
+import { ContextManager } from '../context/manager.cjs';
+import { InternalMessage } from '../context/types.cjs';
+import { ILLMService } from '../llm/services/types.cjs';
+import { PromptManager } from '../systemPrompt/manager.cjs';
+import { ToolManager } from '../tools/tool-manager.cjs';
+import { ValidatedLLMConfig } from '../llm/schemas.cjs';
+import { AgentStateManager } from '../agent/state-manager.cjs';
+import { StorageBackends } from '../storage/backend/types.cjs';
+import { SessionEventBus, AgentEventBus } from '../events/index.cjs';
+import '../llm/formatters/types.cjs';
+import '../llm/types.cjs';
+import '../llm/tokenizer/types.cjs';
+import '../context/compression/types.cjs';
+import '../systemPrompt/types.cjs';
+import '../mcp/manager.cjs';
+import '../mcp/schemas.cjs';
+import 'zod';
+import '../mcp/types.cjs';
+import '@modelcontextprotocol/sdk/client/index.js';
+import '../tools/types.cjs';
+import 'json-schema';
+import '@modelcontextprotocol/sdk/types.js';
+import './history/types.cjs';
+import 'ai';
+import '../systemPrompt/schemas.cjs';
+import '../tools/internal-tools/registry.cjs';
+import '../search/search-service.cjs';
+import '../storage/backend/database-backend.cjs';
+import '../search/types.cjs';
+import '../tools/schemas.cjs';
+import '../tools/confirmation/types.cjs';
+import '../tools/confirmation/allowed-tools-provider/types.cjs';
+import '../agent/schemas.cjs';
+import '../storage/backend/cache-backend.cjs';
+import '../storage/schemas.cjs';
+import 'events';
+
+/**
+ * Represents an isolated conversation session within a Dexto agent.
+ *
+ * ChatSession provides session-level isolation for conversations, allowing multiple
+ * independent chat contexts to exist within a single DextoAgent instance. Each session
+ * maintains its own conversation history, message management, and event handling.
+ *
+ * ## Architecture
+ *
+ * The ChatSession acts as a lightweight wrapper around core Dexto services, providing
+ * session-specific instances of:
+ * - **ContextManager**: Handles conversation history and message formatting
+ * - **LLMService**: Manages AI model interactions and tool execution
+ * - **TypedEventEmitter**: Provides session-scoped event handling
+ *
+ * ## Event Handling
+ *
+ * Each session has its own event bus that emits standard Dexto events:
+ * - `llmservice:*` events (thinking, toolCall, response, etc.)
+ *
+ * Session events are forwarded to the global agent event bus with session prefixes.
+ *
+ * ## Usage Example
+ *
+ * ```typescript
+ * // Create a new session
+ * const session = agent.createSession('user-123');
+ *
+ * // Listen for session events
+ * session.eventBus.on('llmservice:response', (payload) => {
+ *   console.log('Session response:', payload.content);
+ * });
+ *
+ * // Run a conversation turn
+ * const response = await session.run('Hello, how are you?');
+ *
+ * // Reset session history
+ * await session.reset();
+ * ```
+ *
+ * @see {@link SessionManager} for session lifecycle management
+ * @see {@link ContextManager} for conversation history management
+ * @see {@link ILLMService} for AI model interaction interface
+ */
+declare class ChatSession {
+    private services;
+    readonly id: string;
+    /**
+     * Session-scoped event emitter for handling conversation events.
+     *
+     * This is a session-local SessionEventBus instance that forwards events
+     * to the global agent event bus.
+     *
+     * Events emitted include:
+     * - `llmservice:thinking` - AI model is processing
+     * - `llmservice:toolCall` - Tool execution requested
+     * - `llmservice:response` - Final response generated
+     */
+    readonly eventBus: SessionEventBus;
+    /**
+     * History provider that persists conversation messages.
+     * Shared across LLM switches to maintain conversation continuity.
+     */
+    private historyProvider;
+    /**
+     * Handles AI model interactions, tool execution, and response generation for this session.
+     *
+     * Each session has its own LLMService instance that uses the session's
+     * ContextManager and event bus.
+     */
+    private llmService;
+    /**
+     * Map of event forwarder functions for cleanup.
+     * Stores the bound functions so they can be removed from the event bus.
+     */
+    private forwarders;
+    /**
+     * AbortController for the currently running turn, if any.
+     * Calling cancel() aborts the in-flight LLM request and tool execution checks.
+     */
+    private currentRunController;
+    /**
+     * Creates a new ChatSession instance.
+     *
+     * Each session creates its own isolated services:
+     * - ConversationHistoryProvider (with session-specific storage, shared across LLM switches)
+     * - LLMService (creates its own properly-typed ContextManager internally)
+     * - SessionEventBus (session-local event handling with forwarding)
+     *
+     * @param services - The shared services from the agent (state manager, prompt, client managers, etc.)
+     * @param id - Unique identifier for this session
+     */
+    constructor(services: {
+        stateManager: AgentStateManager;
+        promptManager: PromptManager;
+        toolManager: ToolManager;
+        agentEventBus: AgentEventBus;
+        storage: StorageBackends;
+    }, id: string);
+    /**
+     * Initialize the session services asynchronously.
+     * This must be called after construction to set up the storage-backed services.
+     */
+    init(): Promise<void>;
+    /**
+     * Sets up event forwarding from session bus to global agent bus.
+     *
+     * All session events are automatically forwarded to the global bus with the same
+     * event names, but with session context added to the payload. This allows the app
+     * layer to continue listening to standard events while having access to session
+     * information when needed.
+     */
+    private setupEventForwarding;
+    /**
+     * Initializes session-specific services.
+     */
+    private initializeServices;
+    /**
+     * Processes user input through the session's LLM service and returns the response.
+     *
+     * This method:
+     * 1. Takes user input (text, optionally with image or file data)
+     * 2. Passes it to the LLM service for processing
+     * 3. Returns the AI's response text
+     *
+     * The method handles both text-only and multimodal input (text + images/files).
+     * Tool calls and conversation management are handled internally by the LLM service.
+     *
+     * @param input - The user's text input
+     * @param imageDataInput - Optional image data for multimodal input
+     * @param fileDataInput - Optional file data for file input
+     * @param stream - Optional flag to enable streaming responses
+     * @returns Promise that resolves to the AI's response text
+     *
+     * @example
+     * ```typescript
+     * const response = await session.run('What is the weather like today?');
+     * console.log(response); // "I'll check the weather for you..."
+     * ```
+     */
+    run(input: string, imageDataInput?: {
+        image: string;
+        mimeType: string;
+    }, fileDataInput?: {
+        data: string;
+        mimeType: string;
+        filename?: string;
+    }, stream?: boolean): Promise<string>;
+    /**
+     * Retrieves the complete conversation history for this session.
+     *
+     * Returns a read-only copy of all messages in the conversation, including:
+     * - User messages
+     * - Assistant responses
+     * - Tool call results
+     * - System messages
+     *
+     * The history is formatted as internal messages and may include multimodal
+     * content (text and images).
+     *
+     * @returns Promise that resolves to a read-only array of conversation messages in chronological order
+     *
+     * @example
+     * ```typescript
+     * const history = await session.getHistory();
+     * console.log(`Conversation has ${history.length} messages`);
+     * history.forEach(msg => console.log(`${msg.role}: ${msg.content}`));
+     * ```
+     */
+    getHistory(): Promise<InternalMessage[]>;
+    /**
+     * Reset the conversation history for this session.
+     *
+     * This method:
+     * 1. Clears all messages from the session's conversation history
+     * 2. Removes persisted history from the storage provider
+     * 3. Emits a `dexto:conversationReset` event with session context
+     *
+     * The system prompt and session configuration remain unchanged.
+     * Only the conversation messages are cleared.
+     *
+     * @returns Promise that resolves when the reset is complete
+     *
+     * @example
+     * ```typescript
+     * await session.reset();
+     * console.log('Conversation history cleared');
+     * ```
+     *
+     * @see {@link ContextManager.resetConversation} for the underlying implementation
+     */
+    reset(): Promise<void>;
+    /**
+     * Gets the session's ContextManager instance.
+     *
+     * @returns The ContextManager for this session
+     */
+    getContextManager(): ContextManager<unknown>;
+    /**
+     * Gets the session's LLMService instance.
+     *
+     * @returns The LLMService for this session
+     */
+    getLLMService(): ILLMService;
+    /**
+     * Switches the LLM service for this session while preserving conversation history.
+     *
+     * This method creates a new LLM service with the specified configuration and router,
+     * while maintaining the existing ContextManager and conversation history. This allows
+     * users to change AI models mid-conversation without losing context.
+     *
+     * @param newLLMConfig The new LLM configuration to use (includes router)
+     *
+     * @example
+     * ```typescript
+     * // Switch from Claude to GPT-4 while keeping conversation history
+     * session.switchLLM({
+     *   provider: 'openai',
+     *   model: 'gpt-4',
+     *   apiKey: process.env.OPENAI_API_KEY,
+     *   router: 'in-built'
+     * });
+     * ```
+     */
+    switchLLM(newLLMConfig: ValidatedLLMConfig): Promise<void>;
+    /**
+     * Cleanup the session and its in-memory resources.
+     * This method should be called when the session is being removed from memory.
+     * Chat history is preserved in storage and can be restored later.
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Cleans up listeners and other resources to prevent memory leaks.
+     *
+     * This method should be called when the session is being discarded to ensure
+     * that event listeners are properly removed from the global event bus.
+     * Without this cleanup, sessions would remain in memory due to listener references.
+     */
+    dispose(): void;
+    /**
+     * Cancel the currently running turn for this session, if any.
+     * Returns true if a run was in progress and was signaled to abort.
+     */
+    cancel(): boolean;
+}
+
+export { ChatSession };

package/dist/session/chat-session.d.ts

@@ -0,0 +1,284 @@
+import { ContextManager } from '../context/manager.js';
+import { InternalMessage } from '../context/types.js';
+import { ILLMService } from '../llm/services/types.js';
+import { PromptManager } from '../systemPrompt/manager.js';
+import { ToolManager } from '../tools/tool-manager.js';
+import { ValidatedLLMConfig } from '../llm/schemas.js';
+import { AgentStateManager } from '../agent/state-manager.js';
+import { StorageBackends } from '../storage/backend/types.js';
+import { SessionEventBus, AgentEventBus } from '../events/index.js';
+import '../llm/formatters/types.js';
+import '../llm/types.js';
+import '../llm/tokenizer/types.js';
+import '../context/compression/types.js';
+import '../systemPrompt/types.js';
+import '../mcp/manager.js';
+import '../mcp/schemas.js';
+import 'zod';
+import '../mcp/types.js';
+import '@modelcontextprotocol/sdk/client/index.js';
+import '../tools/types.js';
+import 'json-schema';
+import '@modelcontextprotocol/sdk/types.js';
+import './history/types.js';
+import 'ai';
+import '../systemPrompt/schemas.js';
+import '../tools/internal-tools/registry.js';
+import '../search/search-service.js';
+import '../storage/backend/database-backend.js';
+import '../search/types.js';
+import '../tools/schemas.js';
+import '../tools/confirmation/types.js';
+import '../tools/confirmation/allowed-tools-provider/types.js';
+import '../agent/schemas.js';
+import '../storage/backend/cache-backend.js';
+import '../storage/schemas.js';
+import 'events';
+
+/**
+ * Represents an isolated conversation session within a Dexto agent.
+ *
+ * ChatSession provides session-level isolation for conversations, allowing multiple
+ * independent chat contexts to exist within a single DextoAgent instance. Each session
+ * maintains its own conversation history, message management, and event handling.
+ *
+ * ## Architecture
+ *
+ * The ChatSession acts as a lightweight wrapper around core Dexto services, providing
+ * session-specific instances of:
+ * - **ContextManager**: Handles conversation history and message formatting
+ * - **LLMService**: Manages AI model interactions and tool execution
+ * - **TypedEventEmitter**: Provides session-scoped event handling
+ *
+ * ## Event Handling
+ *
+ * Each session has its own event bus that emits standard Dexto events:
+ * - `llmservice:*` events (thinking, toolCall, response, etc.)
+ *
+ * Session events are forwarded to the global agent event bus with session prefixes.
+ *
+ * ## Usage Example
+ *
+ * ```typescript
+ * // Create a new session
+ * const session = agent.createSession('user-123');
+ *
+ * // Listen for session events
+ * session.eventBus.on('llmservice:response', (payload) => {
+ *   console.log('Session response:', payload.content);
+ * });
+ *
+ * // Run a conversation turn
+ * const response = await session.run('Hello, how are you?');
+ *
+ * // Reset session history
+ * await session.reset();
+ * ```
+ *
+ * @see {@link SessionManager} for session lifecycle management
+ * @see {@link ContextManager} for conversation history management
+ * @see {@link ILLMService} for AI model interaction interface
+ */
+declare class ChatSession {
+    private services;
+    readonly id: string;
+    /**
+     * Session-scoped event emitter for handling conversation events.
+     *
+     * This is a session-local SessionEventBus instance that forwards events
+     * to the global agent event bus.
+     *
+     * Events emitted include:
+     * - `llmservice:thinking` - AI model is processing
+     * - `llmservice:toolCall` - Tool execution requested
+     * - `llmservice:response` - Final response generated
+     */
+    readonly eventBus: SessionEventBus;
+    /**
+     * History provider that persists conversation messages.
+     * Shared across LLM switches to maintain conversation continuity.
+     */
+    private historyProvider;
+    /**
+     * Handles AI model interactions, tool execution, and response generation for this session.
+     *
+     * Each session has its own LLMService instance that uses the session's
+     * ContextManager and event bus.
+     */
+    private llmService;
+    /**
+     * Map of event forwarder functions for cleanup.
+     * Stores the bound functions so they can be removed from the event bus.
+     */
+    private forwarders;
+    /**
+     * AbortController for the currently running turn, if any.
+     * Calling cancel() aborts the in-flight LLM request and tool execution checks.
+     */
+    private currentRunController;
+    /**
+     * Creates a new ChatSession instance.
+     *
+     * Each session creates its own isolated services:
+     * - ConversationHistoryProvider (with session-specific storage, shared across LLM switches)
+     * - LLMService (creates its own properly-typed ContextManager internally)
+     * - SessionEventBus (session-local event handling with forwarding)
+     *
+     * @param services - The shared services from the agent (state manager, prompt, client managers, etc.)
+     * @param id - Unique identifier for this session
+     */
+    constructor(services: {
+        stateManager: AgentStateManager;
+        promptManager: PromptManager;
+        toolManager: ToolManager;
+        agentEventBus: AgentEventBus;
+        storage: StorageBackends;
+    }, id: string);
+    /**
+     * Initialize the session services asynchronously.
+     * This must be called after construction to set up the storage-backed services.
+     */
+    init(): Promise<void>;
+    /**
+     * Sets up event forwarding from session bus to global agent bus.
+     *
+     * All session events are automatically forwarded to the global bus with the same
+     * event names, but with session context added to the payload. This allows the app
+     * layer to continue listening to standard events while having access to session
+     * information when needed.
+     */
+    private setupEventForwarding;
+    /**
+     * Initializes session-specific services.
+     */
+    private initializeServices;
+    /**
+     * Processes user input through the session's LLM service and returns the response.
+     *
+     * This method:
+     * 1. Takes user input (text, optionally with image or file data)
+     * 2. Passes it to the LLM service for processing
+     * 3. Returns the AI's response text
+     *
+     * The method handles both text-only and multimodal input (text + images/files).
+     * Tool calls and conversation management are handled internally by the LLM service.
+     *
+     * @param input - The user's text input
+     * @param imageDataInput - Optional image data for multimodal input
+     * @param fileDataInput - Optional file data for file input
+     * @param stream - Optional flag to enable streaming responses
+     * @returns Promise that resolves to the AI's response text
+     *
+     * @example
+     * ```typescript
+     * const response = await session.run('What is the weather like today?');
+     * console.log(response); // "I'll check the weather for you..."
+     * ```
+     */
+    run(input: string, imageDataInput?: {
+        image: string;
+        mimeType: string;
+    }, fileDataInput?: {
+        data: string;
+        mimeType: string;
+        filename?: string;
+    }, stream?: boolean): Promise<string>;
+    /**
+     * Retrieves the complete conversation history for this session.
+     *
+     * Returns a read-only copy of all messages in the conversation, including:
+     * - User messages
+     * - Assistant responses
+     * - Tool call results
+     * - System messages
+     *
+     * The history is formatted as internal messages and may include multimodal
+     * content (text and images).
+     *
+     * @returns Promise that resolves to a read-only array of conversation messages in chronological order
+     *
+     * @example
+     * ```typescript
+     * const history = await session.getHistory();
+     * console.log(`Conversation has ${history.length} messages`);
+     * history.forEach(msg => console.log(`${msg.role}: ${msg.content}`));
+     * ```
+     */
+    getHistory(): Promise<InternalMessage[]>;
+    /**
+     * Reset the conversation history for this session.
+     *
+     * This method:
+     * 1. Clears all messages from the session's conversation history
+     * 2. Removes persisted history from the storage provider
+     * 3. Emits a `dexto:conversationReset` event with session context
+     *
+     * The system prompt and session configuration remain unchanged.
+     * Only the conversation messages are cleared.
+     *
+     * @returns Promise that resolves when the reset is complete
+     *
+     * @example
+     * ```typescript
+     * await session.reset();
+     * console.log('Conversation history cleared');
+     * ```
+     *
+     * @see {@link ContextManager.resetConversation} for the underlying implementation
+     */
+    reset(): Promise<void>;
+    /**
+     * Gets the session's ContextManager instance.
+     *
+     * @returns The ContextManager for this session
+     */
+    getContextManager(): ContextManager<unknown>;
+    /**
+     * Gets the session's LLMService instance.
+     *
+     * @returns The LLMService for this session
+     */
+    getLLMService(): ILLMService;
+    /**
+     * Switches the LLM service for this session while preserving conversation history.
+     *
+     * This method creates a new LLM service with the specified configuration and router,
+     * while maintaining the existing ContextManager and conversation history. This allows
+     * users to change AI models mid-conversation without losing context.
+     *
+     * @param newLLMConfig The new LLM configuration to use (includes router)
+     *
+     * @example
+     * ```typescript
+     * // Switch from Claude to GPT-4 while keeping conversation history
+     * session.switchLLM({
+     *   provider: 'openai',
+     *   model: 'gpt-4',
+     *   apiKey: process.env.OPENAI_API_KEY,
+     *   router: 'in-built'
+     * });
+     * ```
+     */
+    switchLLM(newLLMConfig: ValidatedLLMConfig): Promise<void>;
+    /**
+     * Cleanup the session and its in-memory resources.
+     * This method should be called when the session is being removed from memory.
+     * Chat history is preserved in storage and can be restored later.
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Cleans up listeners and other resources to prevent memory leaks.
+     *
+     * This method should be called when the session is being discarded to ensure
+     * that event listeners are properly removed from the global event bus.
+     * Without this cleanup, sessions would remain in memory due to listener references.
+     */
+    dispose(): void;
+    /**
+     * Cancel the currently running turn for this session, if any.
+     * Returns true if a run was in progress and was signaled to abort.
+     */
+    cancel(): boolean;
+}
+
+export { ChatSession };