@dexto/core 1.1.4 → 1.1.6

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

@@ -0,0 +1,219 @@
+import { ChatSession } from './chat-session.js';
+import { PromptManager } from '../systemPrompt/manager.js';
+import { ToolManager } from '../tools/tool-manager.js';
+import { AgentEventBus } from '../events/index.js';
+import { AgentStateManager } from '../agent/state-manager.js';
+import { ValidatedLLMConfig } from '../llm/schemas.js';
+import { StorageBackends } from '../storage/backend/types.js';
+import '../context/manager.js';
+import '../llm/formatters/types.js';
+import '../context/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 '../llm/services/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 'events';
+import '../agent/schemas.js';
+import '../storage/backend/cache-backend.js';
+import '../storage/schemas.js';
+
+interface SessionMetadata {
+    createdAt: number;
+    lastActivity: number;
+    messageCount: number;
+}
+interface SessionManagerConfig {
+    maxSessions?: number;
+    sessionTTL?: number;
+}
+interface SessionData {
+    id: string;
+    userId?: string;
+    createdAt: number;
+    lastActivity: number;
+    messageCount: number;
+    metadata?: Record<string, any>;
+}
+/**
+ * Manages multiple chat sessions within a Dexto agent.
+ *
+ * The SessionManager is responsible for:
+ * - Creating and managing multiple isolated chat sessions
+ * - Enforcing session limits and TTL policies
+ * - Cleaning up expired sessions
+ * - Providing session lifecycle management
+ * - Persisting session data using the simplified storage backends
+ */
+declare class SessionManager {
+    private services;
+    private sessions;
+    private readonly maxSessions;
+    private readonly sessionTTL;
+    private initialized;
+    private cleanupInterval?;
+    private initializationPromise;
+    private readonly pendingCreations;
+    constructor(services: {
+        stateManager: AgentStateManager;
+        promptManager: PromptManager;
+        toolManager: ToolManager;
+        agentEventBus: AgentEventBus;
+        storage: StorageBackends;
+    }, config?: SessionManagerConfig);
+    /**
+     * Initialize the SessionManager with persistent storage.
+     * This must be called before using any session operations.
+     */
+    init(): Promise<void>;
+    /**
+     * Restore sessions from persistent storage on startup.
+     * This allows sessions to survive application restarts.
+     */
+    private restoreSessionsFromStorage;
+    /**
+     * Ensures the SessionManager is initialized before operations.
+     */
+    private ensureInitialized;
+    /**
+     * Creates a new chat session or returns an existing one.
+     *
+     * @param sessionId Optional session ID. If not provided, a UUID will be generated.
+     * @returns The created or existing ChatSession
+     * @throws Error if maximum sessions limit is reached
+     */
+    createSession(sessionId?: string): Promise<ChatSession>;
+    /**
+     * Internal method that handles the actual session creation logic.
+     * This method implements atomic session creation to prevent race conditions.
+     */
+    private createSessionInternal;
+    /**
+     * Gets or creates the default session.
+     * This is used for backward compatibility with single-session operations.
+     *
+     * @returns The default ChatSession (creates one if it doesn't exist)
+     */
+    getDefaultSession(): Promise<ChatSession>;
+    /**
+     * Retrieves an existing session by ID.
+     *
+     * @param sessionId The session ID to retrieve
+     * @param restoreFromStorage Whether to restore from storage if not in memory (default: true)
+     * @returns The ChatSession if found, undefined otherwise
+     */
+    getSession(sessionId: string, restoreFromStorage?: boolean): Promise<ChatSession | undefined>;
+    /**
+     * Ends a session by removing it from memory without deleting conversation history.
+     * Used for cleanup, agent shutdown, and session expiry.
+     *
+     * @param sessionId The session ID to end
+     */
+    endSession(sessionId: string): Promise<void>;
+    /**
+     * Deletes a session and its conversation history, removing everything from memory and storage.
+     * Used for user-initiated permanent deletion.
+     *
+     * @param sessionId The session ID to delete
+     */
+    deleteSession(sessionId: string): Promise<void>;
+    /**
+     * Resets the conversation history for a session while keeping the session alive.
+     *
+     * @param sessionId The session ID to reset
+     * @throws Error if session doesn't exist
+     */
+    resetSession(sessionId: string): Promise<void>;
+    /**
+     * Lists all active session IDs.
+     *
+     * @returns Array of active session IDs
+     */
+    listSessions(): Promise<string[]>;
+    /**
+     * Gets metadata for a specific session.
+     *
+     * @param sessionId The session ID
+     * @returns Session metadata if found, undefined otherwise
+     */
+    getSessionMetadata(sessionId: string): Promise<SessionMetadata | undefined>;
+    /**
+     * Get the global session manager configuration.
+     */
+    getConfig(): SessionManagerConfig;
+    /**
+     * Updates the last activity timestamp for a session.
+     */
+    private updateSessionActivity;
+    /**
+     * Increments the message count for a session.
+     */
+    incrementMessageCount(sessionId: string): Promise<void>;
+    /**
+     * Cleans up expired sessions from memory only, preserving chat history in storage.
+     * This allows inactive sessions to be garbage collected while keeping conversations restorable.
+     */
+    private cleanupExpiredSessions;
+    /**
+     * Switch LLM for all sessions.
+     * @param newLLMConfig The new LLM configuration to apply
+     * @returns Result object with success message and any warnings
+     */
+    switchLLMForAllSessions(newLLMConfig: ValidatedLLMConfig): Promise<{
+        message: string;
+        warnings: string[];
+    }>;
+    /**
+     * Switch LLM for a specific session.
+     * @param newLLMConfig The new LLM configuration to apply
+     * @param sessionId The session ID to switch LLM for
+     * @returns Result object with success message and any warnings
+     */
+    switchLLMForSpecificSession(newLLMConfig: ValidatedLLMConfig, sessionId: string): Promise<{
+        message: string;
+        warnings: string[];
+    }>;
+    /**
+     * Switch LLM for the default session.
+     * @param newLLMConfig The new LLM configuration to apply
+     * @returns Result object with success message and any warnings
+     */
+    switchLLMForDefaultSession(newLLMConfig: ValidatedLLMConfig): Promise<{
+        message: string;
+        warnings: string[];
+    }>;
+    /**
+     * Get session statistics for monitoring and debugging.
+     */
+    getSessionStats(): Promise<{
+        totalSessions: number;
+        inMemorySessions: number;
+        maxSessions: number;
+        sessionTTL: number;
+    }>;
+    /**
+     * Cleanup all sessions and resources.
+     * This should be called when shutting down the application.
+     */
+    cleanup(): Promise<void>;
+}
+
+export { type SessionData, SessionManager, type SessionManagerConfig, type SessionMetadata };

package/dist/session/session-manager.js

@@ -0,0 +1,457 @@
+import { randomUUID } from "crypto";
+import { ChatSession } from "./chat-session.js";
+import { logger } from "../logger/index.js";
+import { SessionError } from "./errors.js";
+class SessionManager {
+  constructor(services, config = {}) {
+    this.services = services;
+    this.maxSessions = config.maxSessions ?? 100;
+    this.sessionTTL = config.sessionTTL ?? 36e5;
+  }
+  sessions = /* @__PURE__ */ new Map();
+  maxSessions;
+  sessionTTL;
+  initialized = false;
+  cleanupInterval;
+  initializationPromise;
+  // Add a Map to track ongoing session creation operations to prevent race conditions
+  pendingCreations = /* @__PURE__ */ new Map();
+  /**
+   * Initialize the SessionManager with persistent storage.
+   * This must be called before using any session operations.
+   */
+  async init() {
+    if (this.initialized) {
+      return;
+    }
+    await this.restoreSessionsFromStorage();
+    const cleanupIntervalMs = Math.min(this.sessionTTL / 4, 15 * 60 * 1e3);
+    this.cleanupInterval = setInterval(
+      () => this.cleanupExpiredSessions().catch(
+        (err) => logger.error(`Periodic session cleanup failed: ${err}`)
+      ),
+      cleanupIntervalMs
+    );
+    this.initialized = true;
+    logger.debug(
+      `SessionManager initialized with periodic cleanup every ${Math.round(cleanupIntervalMs / 1e3 / 60)} minutes`
+    );
+  }
+  /**
+   * Restore sessions from persistent storage on startup.
+   * This allows sessions to survive application restarts.
+   */
+  async restoreSessionsFromStorage() {
+    try {
+      const sessionKeys = await this.services.storage.database.list("session:");
+      logger.debug(`Found ${sessionKeys.length} persisted sessions to restore`);
+      for (const sessionKey of sessionKeys) {
+        const sessionId = sessionKey.replace("session:", "");
+        const sessionData = await this.services.storage.database.get(sessionKey);
+        if (sessionData) {
+          const now = Date.now();
+          const lastActivity = sessionData.lastActivity;
+          if (now - lastActivity <= this.sessionTTL) {
+            logger.debug(`Session ${sessionId} restored from storage`);
+          } else {
+            await this.services.storage.database.delete(sessionKey);
+            logger.debug(`Expired session ${sessionId} cleaned up during restore`);
+          }
+        }
+      }
+    } catch (error) {
+      logger.error(
+        `Failed to restore sessions from storage: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  /**
+   * Ensures the SessionManager is initialized before operations.
+   */
+  async ensureInitialized() {
+    if (!this.initialized) {
+      if (!this.initializationPromise) {
+        this.initializationPromise = this.init();
+      }
+      await this.initializationPromise;
+    }
+  }
+  /**
+   * Creates a new chat session or returns an existing one.
+   *
+   * @param sessionId Optional session ID. If not provided, a UUID will be generated.
+   * @returns The created or existing ChatSession
+   * @throws Error if maximum sessions limit is reached
+   */
+  async createSession(sessionId) {
+    await this.ensureInitialized();
+    const id = sessionId ?? randomUUID();
+    if (this.pendingCreations.has(id)) {
+      return await this.pendingCreations.get(id);
+    }
+    if (this.sessions.has(id)) {
+      await this.updateSessionActivity(id);
+      return this.sessions.get(id);
+    }
+    const creationPromise = this.createSessionInternal(id);
+    this.pendingCreations.set(id, creationPromise);
+    try {
+      const session = await creationPromise;
+      return session;
+    } finally {
+      this.pendingCreations.delete(id);
+    }
+  }
+  /**
+   * Internal method that handles the actual session creation logic.
+   * This method implements atomic session creation to prevent race conditions.
+   */
+  async createSessionInternal(id) {
+    await this.cleanupExpiredSessions();
+    const sessionKey = `session:${id}`;
+    const existingMetadata = await this.services.storage.database.get(sessionKey);
+    if (existingMetadata) {
+      await this.updateSessionActivity(id);
+      const session2 = new ChatSession(this.services, id);
+      await session2.init();
+      this.sessions.set(id, session2);
+      logger.info(`Restored session from storage: ${id}`, null, "cyan");
+      return session2;
+    }
+    const activeSessionKeys = await this.services.storage.database.list("session:");
+    if (activeSessionKeys.length >= this.maxSessions) {
+      throw SessionError.maxSessionsExceeded(activeSessionKeys.length, this.maxSessions);
+    }
+    const sessionData = {
+      id,
+      createdAt: Date.now(),
+      lastActivity: Date.now(),
+      messageCount: 0
+    };
+    try {
+      await this.services.storage.database.set(sessionKey, sessionData);
+    } catch (error) {
+      logger.error(`Failed to store session metadata for ${id}:`, error);
+      throw error;
+    }
+    let session;
+    try {
+      session = new ChatSession(this.services, id);
+      await session.init();
+      this.sessions.set(id, session);
+      await this.services.storage.cache.set(sessionKey, sessionData, this.sessionTTL / 1e3);
+      logger.info(`Created new session: ${id}`, null, "green");
+      return session;
+    } catch (error) {
+      logger.error(
+        `Failed to initialize session ${id}: ${error instanceof Error ? error.message : String(error)}`
+      );
+      await this.services.storage.database.delete(sessionKey);
+      await this.services.storage.cache.delete(sessionKey);
+      const reason = error instanceof Error ? error.message : "unknown error";
+      throw SessionError.initializationFailed(id, reason);
+    }
+  }
+  /**
+   * Gets or creates the default session.
+   * This is used for backward compatibility with single-session operations.
+   *
+   * @returns The default ChatSession (creates one if it doesn't exist)
+   */
+  async getDefaultSession() {
+    const defaultSessionId = "default";
+    return await this.createSession(defaultSessionId);
+  }
+  /**
+   * Retrieves an existing session by ID.
+   *
+   * @param sessionId The session ID to retrieve
+   * @param restoreFromStorage Whether to restore from storage if not in memory (default: true)
+   * @returns The ChatSession if found, undefined otherwise
+   */
+  async getSession(sessionId, restoreFromStorage = true) {
+    await this.ensureInitialized();
+    if (this.pendingCreations.has(sessionId)) {
+      return await this.pendingCreations.get(sessionId);
+    }
+    if (this.sessions.has(sessionId)) {
+      return this.sessions.get(sessionId);
+    }
+    if (restoreFromStorage) {
+      const sessionKey = `session:${sessionId}`;
+      const sessionData = await this.services.storage.database.get(sessionKey);
+      if (sessionData) {
+        const session = new ChatSession(this.services, sessionId);
+        await session.init();
+        this.sessions.set(sessionId, session);
+        return session;
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Ends a session by removing it from memory without deleting conversation history.
+   * Used for cleanup, agent shutdown, and session expiry.
+   *
+   * @param sessionId The session ID to end
+   */
+  async endSession(sessionId) {
+    await this.ensureInitialized();
+    const session = this.sessions.get(sessionId);
+    if (session) {
+      await session.cleanup();
+      this.sessions.delete(sessionId);
+    }
+    const sessionKey = `session:${sessionId}`;
+    await this.services.storage.cache.delete(sessionKey);
+    logger.debug(`Ended session (removed from memory, chat history preserved): ${sessionId}`);
+  }
+  /**
+   * Deletes a session and its conversation history, removing everything from memory and storage.
+   * Used for user-initiated permanent deletion.
+   *
+   * @param sessionId The session ID to delete
+   */
+  async deleteSession(sessionId) {
+    await this.ensureInitialized();
+    const session = await this.getSession(sessionId);
+    if (session) {
+      await session.reset();
+      await session.cleanup();
+      this.sessions.delete(sessionId);
+    }
+    const sessionKey = `session:${sessionId}`;
+    await this.services.storage.database.delete(sessionKey);
+    await this.services.storage.cache.delete(sessionKey);
+    logger.debug(`Deleted session and conversation history: ${sessionId}`);
+  }
+  /**
+   * Resets the conversation history for a session while keeping the session alive.
+   *
+   * @param sessionId The session ID to reset
+   * @throws Error if session doesn't exist
+   */
+  async resetSession(sessionId) {
+    await this.ensureInitialized();
+    const session = await this.getSession(sessionId);
+    if (!session) {
+      throw SessionError.notFound(sessionId);
+    }
+    await session.reset();
+    const sessionKey = `session:${sessionId}`;
+    const sessionData = await this.services.storage.database.get(sessionKey);
+    if (sessionData) {
+      sessionData.messageCount = 0;
+      sessionData.lastActivity = Date.now();
+      await this.services.storage.database.set(sessionKey, sessionData);
+      await this.services.storage.cache.set(sessionKey, sessionData, this.sessionTTL / 1e3);
+    }
+    logger.debug(`Reset session conversation: ${sessionId}`);
+  }
+  /**
+   * Lists all active session IDs.
+   *
+   * @returns Array of active session IDs
+   */
+  async listSessions() {
+    await this.ensureInitialized();
+    const sessionKeys = await this.services.storage.database.list("session:");
+    return sessionKeys.map((key) => key.replace("session:", ""));
+  }
+  /**
+   * Gets metadata for a specific session.
+   *
+   * @param sessionId The session ID
+   * @returns Session metadata if found, undefined otherwise
+   */
+  async getSessionMetadata(sessionId) {
+    await this.ensureInitialized();
+    const sessionKey = `session:${sessionId}`;
+    const sessionData = await this.services.storage.database.get(sessionKey);
+    return sessionData ? {
+      createdAt: sessionData.createdAt,
+      lastActivity: sessionData.lastActivity,
+      messageCount: sessionData.messageCount
+    } : void 0;
+  }
+  /**
+   * Get the global session manager configuration.
+   */
+  getConfig() {
+    return {
+      maxSessions: this.maxSessions,
+      sessionTTL: this.sessionTTL
+    };
+  }
+  /**
+   * Updates the last activity timestamp for a session.
+   */
+  async updateSessionActivity(sessionId) {
+    const sessionKey = `session:${sessionId}`;
+    const sessionData = await this.services.storage.database.get(sessionKey);
+    if (sessionData) {
+      sessionData.lastActivity = Date.now();
+      await this.services.storage.database.set(sessionKey, sessionData);
+      await this.services.storage.cache.set(sessionKey, sessionData, this.sessionTTL / 1e3);
+    }
+  }
+  /**
+   * Increments the message count for a session.
+   */
+  async incrementMessageCount(sessionId) {
+    await this.ensureInitialized();
+    const sessionKey = `session:${sessionId}`;
+    const sessionData = await this.services.storage.database.get(sessionKey);
+    if (sessionData) {
+      sessionData.messageCount++;
+      sessionData.lastActivity = Date.now();
+      await this.services.storage.database.set(sessionKey, sessionData);
+      await this.services.storage.cache.set(sessionKey, sessionData, this.sessionTTL / 1e3);
+    }
+  }
+  /**
+   * Cleans up expired sessions from memory only, preserving chat history in storage.
+   * This allows inactive sessions to be garbage collected while keeping conversations restorable.
+   */
+  async cleanupExpiredSessions() {
+    const now = Date.now();
+    const expiredSessions = [];
+    for (const [sessionId, _session] of this.sessions.entries()) {
+      const sessionKey = `session:${sessionId}`;
+      const sessionData = await this.services.storage.database.get(sessionKey);
+      if (sessionData && now - sessionData.lastActivity > this.sessionTTL) {
+        expiredSessions.push(sessionId);
+      }
+    }
+    for (const sessionId of expiredSessions) {
+      const session = this.sessions.get(sessionId);
+      if (session) {
+        session.dispose();
+        this.sessions.delete(sessionId);
+        logger.debug(
+          `Removed expired session from memory: ${sessionId} (chat history preserved)`
+        );
+      }
+    }
+    if (expiredSessions.length > 0) {
+      logger.debug(
+        `Memory cleanup: removed ${expiredSessions.length} inactive sessions, chat history preserved`
+      );
+    }
+  }
+  /**
+   * Switch LLM for all sessions.
+   * @param newLLMConfig The new LLM configuration to apply
+   * @returns Result object with success message and any warnings
+   */
+  async switchLLMForAllSessions(newLLMConfig) {
+    await this.ensureInitialized();
+    const sessionIds = await this.listSessions();
+    const failedSessions = [];
+    for (const sId of sessionIds) {
+      const session = await this.getSession(sId);
+      if (session) {
+        try {
+          this.services.stateManager.updateLLM(newLLMConfig, sId);
+          await session.switchLLM(newLLMConfig);
+        } catch (error) {
+          failedSessions.push(sId);
+          logger.warn(
+            `Error switching LLM for session ${sId}: ${error instanceof Error ? error.message : String(error)}`
+          );
+        }
+      }
+    }
+    this.services.agentEventBus.emit("dexto:llmSwitched", {
+      newConfig: newLLMConfig,
+      router: newLLMConfig.router,
+      historyRetained: true,
+      sessionIds: sessionIds.filter((id) => !failedSessions.includes(id))
+    });
+    const message = failedSessions.length > 0 ? `Successfully switched to ${newLLMConfig.provider}/${newLLMConfig.model} using ${newLLMConfig.router} router (${failedSessions.length} sessions failed)` : `Successfully switched to ${newLLMConfig.provider}/${newLLMConfig.model} using ${newLLMConfig.router} router for all sessions`;
+    const warnings = failedSessions.length > 0 ? [`Failed to switch LLM for sessions: ${failedSessions.join(", ")}`] : [];
+    return { message, warnings };
+  }
+  /**
+   * Switch LLM for a specific session.
+   * @param newLLMConfig The new LLM configuration to apply
+   * @param sessionId The session ID to switch LLM for
+   * @returns Result object with success message and any warnings
+   */
+  async switchLLMForSpecificSession(newLLMConfig, sessionId) {
+    const session = await this.getSession(sessionId);
+    if (!session) {
+      throw SessionError.notFound(sessionId);
+    }
+    await session.switchLLM(newLLMConfig);
+    this.services.agentEventBus.emit("dexto:llmSwitched", {
+      newConfig: newLLMConfig,
+      router: newLLMConfig.router,
+      historyRetained: true,
+      sessionIds: [sessionId]
+    });
+    const message = `Successfully switched to ${newLLMConfig.provider}/${newLLMConfig.model} using ${newLLMConfig.router} router for session ${sessionId}`;
+    return { message, warnings: [] };
+  }
+  /**
+   * Switch LLM for the default session.
+   * @param newLLMConfig The new LLM configuration to apply
+   * @returns Result object with success message and any warnings
+   */
+  async switchLLMForDefaultSession(newLLMConfig) {
+    const defaultSession = await this.getDefaultSession();
+    await defaultSession.switchLLM(newLLMConfig);
+    this.services.agentEventBus.emit("dexto:llmSwitched", {
+      newConfig: newLLMConfig,
+      router: newLLMConfig.router,
+      historyRetained: true,
+      sessionIds: [defaultSession.id]
+    });
+    const message = `Successfully switched to ${newLLMConfig.provider}/${newLLMConfig.model} using ${newLLMConfig.router} router`;
+    return { message, warnings: [] };
+  }
+  /**
+   * Get session statistics for monitoring and debugging.
+   */
+  async getSessionStats() {
+    await this.ensureInitialized();
+    const totalSessions = (await this.listSessions()).length;
+    const inMemorySessions = this.sessions.size;
+    return {
+      totalSessions,
+      inMemorySessions,
+      maxSessions: this.maxSessions,
+      sessionTTL: this.sessionTTL
+    };
+  }
+  /**
+   * Cleanup all sessions and resources.
+   * This should be called when shutting down the application.
+   */
+  async cleanup() {
+    if (!this.initialized) {
+      return;
+    }
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      delete this.cleanupInterval;
+      logger.debug("Periodic session cleanup stopped");
+    }
+    const sessionIds = Array.from(this.sessions.keys());
+    for (const sessionId of sessionIds) {
+      try {
+        await this.endSession(sessionId);
+      } catch (error) {
+        logger.error(
+          `Failed to cleanup session ${sessionId}: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    }
+    this.sessions.clear();
+    this.initialized = false;
+    logger.debug("SessionManager cleanup completed");
+  }
+}
+export {
+  SessionManager
+};

package/dist/storage/backend/cache-backend.cjs

@@ -0,0 +1,16 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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 cache_backend_exports = {};
+module.exports = __toCommonJS(cache_backend_exports);