@dexto/core 1.1.4 → 1.1.6

package/dist/search/types.d.ts

@@ -0,0 +1,78 @@
+import { InternalMessage } from '../context/types.js';
+import '../llm/types.js';
+
+/**
+ * Options for searching messages
+ */
+interface SearchOptions {
+    /** Limit search to a specific session */
+    sessionId?: string;
+    /** Filter by message role */
+    role?: 'user' | 'assistant' | 'system' | 'tool';
+    /** Maximum number of results to return */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+}
+/**
+ * Result of a message search
+ */
+interface SearchResult {
+    /** Session ID where the message was found */
+    sessionId: string;
+    /** The message that matched the search */
+    message: InternalMessage;
+    /** The specific text that matched the search query */
+    matchedText: string;
+    /** Context around the match for preview */
+    context: string;
+    /** Index of the message within the session */
+    messageIndex: number;
+}
+/**
+ * Result of a session search
+ */
+interface SessionSearchResult {
+    /** Session ID */
+    sessionId: string;
+    /** Number of messages that matched in this session */
+    matchCount: number;
+    /** Preview of the first matching message */
+    firstMatch: SearchResult;
+    /** Session metadata */
+    metadata: {
+        createdAt: number;
+        lastActivity: number;
+        messageCount: number;
+    };
+}
+/**
+ * Response format for search API
+ */
+interface SearchResponse {
+    /** Array of search results */
+    results: SearchResult[];
+    /** Total number of results available */
+    total: number;
+    /** Whether there are more results beyond the current page */
+    hasMore: boolean;
+    /** Query that was searched */
+    query: string;
+    /** Options used for the search */
+    options: SearchOptions;
+}
+/**
+ * Response format for session search API
+ */
+interface SessionSearchResponse {
+    /** Array of session search results */
+    results: SessionSearchResult[];
+    /** Total number of sessions with matches */
+    total: number;
+    /** Whether there are more results beyond the current page */
+    hasMore: boolean;
+    /** Query that was searched */
+    query: string;
+}
+
+export type { SearchOptions, SearchResponse, SearchResult, SessionSearchResponse, SessionSearchResult };

package/dist/session/chat-session.cjs

@@ -0,0 +1,354 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var chat_session_exports = {};
+__export(chat_session_exports, {
+  ChatSession: () => ChatSession
+});
+module.exports = __toCommonJS(chat_session_exports);
+var import_factory = require("./history/factory.js");
+var import_factory2 = require("../llm/services/factory.js");
+var import_events = require("../events/index.js");
+var import_logger = require("../logger/index.js");
+class ChatSession {
+  /**
+   * 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, id) {
+    this.services = services;
+    this.id = id;
+    this.eventBus = new import_events.SessionEventBus();
+    this.setupEventForwarding();
+    import_logger.logger.debug(`ChatSession ${this.id}: Created, awaiting initialization`);
+  }
+  /**
+   * 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
+   */
+  eventBus;
+  /**
+   * History provider that persists conversation messages.
+   * Shared across LLM switches to maintain conversation continuity.
+   */
+  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.
+   */
+  llmService;
+  /**
+   * Map of event forwarder functions for cleanup.
+   * Stores the bound functions so they can be removed from the event bus.
+   */
+  forwarders = /* @__PURE__ */ new Map();
+  /**
+   * AbortController for the currently running turn, if any.
+   * Calling cancel() aborts the in-flight LLM request and tool execution checks.
+   */
+  currentRunController = null;
+  /**
+   * Initialize the session services asynchronously.
+   * This must be called after construction to set up the storage-backed services.
+   */
+  async init() {
+    await this.initializeServices();
+  }
+  /**
+   * 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.
+   */
+  setupEventForwarding() {
+    import_events.SessionEventNames.forEach((eventName) => {
+      const forwarder = (payload) => {
+        const payloadWithSession = payload && typeof payload === "object" ? { ...payload, sessionId: this.id } : { sessionId: this.id };
+        import_logger.logger.silly(
+          `Forwarding session event ${eventName} to agent bus with session context: ${JSON.stringify(payloadWithSession, null, 2)}`
+        );
+        this.services.agentEventBus.emit(eventName, payloadWithSession);
+      };
+      this.forwarders.set(eventName, forwarder);
+      this.eventBus.on(eventName, forwarder);
+    });
+  }
+  /**
+   * Initializes session-specific services.
+   */
+  async initializeServices() {
+    const llmConfig = this.services.stateManager.getLLMConfig(this.id);
+    this.historyProvider = (0, import_factory.createDatabaseHistoryProvider)(
+      this.services.storage.database,
+      this.id
+    );
+    this.llmService = (0, import_factory2.createLLMService)(
+      llmConfig,
+      llmConfig.router,
+      this.services.toolManager,
+      this.services.promptManager,
+      this.historyProvider,
+      // Pass history provider for service to use
+      this.eventBus,
+      // Use session event bus
+      this.id
+    );
+    import_logger.logger.debug(`ChatSession ${this.id}: Services initialized with storage`);
+  }
+  /**
+   * 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..."
+   * ```
+   */
+  async run(input, imageDataInput, fileDataInput, stream) {
+    import_logger.logger.debug(
+      `Running session ${this.id} with input: ${input}, imageDataInput: ${imageDataInput}, fileDataInput: ${fileDataInput}`
+    );
+    this.currentRunController = new AbortController();
+    const signal = this.currentRunController.signal;
+    try {
+      const response = await this.llmService.completeTask(
+        input,
+        { signal },
+        imageDataInput,
+        fileDataInput,
+        stream
+      );
+      return response;
+    } catch (error) {
+      const aborted = error instanceof Error && error.name === "AbortError" || typeof error === "object" && error !== null && error.aborted === true;
+      if (aborted) {
+        this.eventBus.emit("llmservice:error", {
+          error: new Error("Run cancelled"),
+          context: "user_cancelled",
+          recoverable: true
+        });
+        return "";
+      }
+      throw error;
+    } finally {
+      this.currentRunController = null;
+    }
+  }
+  /**
+   * 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}`));
+   * ```
+   */
+  async getHistory() {
+    return await this.historyProvider.getHistory();
+  }
+  /**
+   * 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
+   */
+  async reset() {
+    await this.historyProvider.clearHistory();
+    this.services.agentEventBus.emit("dexto:conversationReset", {
+      sessionId: this.id
+    });
+  }
+  /**
+   * Gets the session's ContextManager instance.
+   *
+   * @returns The ContextManager for this session
+   */
+  getContextManager() {
+    return this.llmService.getContextManager();
+  }
+  /**
+   * Gets the session's LLMService instance.
+   *
+   * @returns The LLMService for this session
+   */
+  getLLMService() {
+    return this.llmService;
+  }
+  /**
+   * 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'
+   * });
+   * ```
+   */
+  async switchLLM(newLLMConfig) {
+    try {
+      const router = newLLMConfig.router;
+      const newLLMService = (0, import_factory2.createLLMService)(
+        newLLMConfig,
+        router,
+        this.services.toolManager,
+        this.services.promptManager,
+        this.historyProvider,
+        // Pass the SAME history provider - preserves conversation!
+        this.eventBus,
+        // Use session event bus
+        this.id
+      );
+      this.llmService = newLLMService;
+      import_logger.logger.info(
+        `ChatSession ${this.id}: LLM switched to ${newLLMConfig.provider}/${newLLMConfig.model}`
+      );
+      this.eventBus.emit("llmservice:switched", {
+        newConfig: newLLMConfig,
+        router,
+        historyRetained: true
+      });
+    } catch (error) {
+      import_logger.logger.error(
+        `Error during ChatSession.switchLLM for session ${this.id}: ${error instanceof Error ? error.message : String(error)}`
+      );
+      throw error;
+    }
+  }
+  /**
+   * 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.
+   */
+  async cleanup() {
+    try {
+      this.dispose();
+      import_logger.logger.debug(
+        `ChatSession ${this.id}: Memory cleanup completed (chat history preserved)`
+      );
+    } catch (error) {
+      import_logger.logger.error(
+        `Error during ChatSession cleanup for session ${this.id}: ${error instanceof Error ? error.message : String(error)}`
+      );
+      throw error;
+    }
+  }
+  /**
+   * 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() {
+    import_logger.logger.debug(`Disposing session ${this.id} - cleaning up event listeners`);
+    this.forwarders.forEach((forwarder, eventName) => {
+      this.eventBus.off(eventName, forwarder);
+    });
+    this.forwarders.clear();
+    import_logger.logger.debug(`Session ${this.id} disposed successfully`);
+  }
+  /**
+   * Cancel the currently running turn for this session, if any.
+   * Returns true if a run was in progress and was signaled to abort.
+   */
+  cancel() {
+    const controller = this.currentRunController;
+    if (!controller || controller.signal.aborted) {
+      return false;
+    }
+    try {
+      controller.abort();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ChatSession
+});