@dexto/core 1.1.4 → 1.1.6

package/dist/session/chat-session.js

@@ -0,0 +1,333 @@
+import { createDatabaseHistoryProvider } from "./history/factory.js";
+import { createLLMService } from "../llm/services/factory.js";
+import {
+  SessionEventBus,
+  SessionEventNames
+} from "../events/index.js";
+import { logger } from "../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 SessionEventBus();
+    this.setupEventForwarding();
+    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() {
+    SessionEventNames.forEach((eventName) => {
+      const forwarder = (payload) => {
+        const payloadWithSession = payload && typeof payload === "object" ? { ...payload, sessionId: this.id } : { sessionId: this.id };
+        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 = createDatabaseHistoryProvider(
+      this.services.storage.database,
+      this.id
+    );
+    this.llmService = 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
+    );
+    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) {
+    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 = 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;
+      logger.info(
+        `ChatSession ${this.id}: LLM switched to ${newLLMConfig.provider}/${newLLMConfig.model}`
+      );
+      this.eventBus.emit("llmservice:switched", {
+        newConfig: newLLMConfig,
+        router,
+        historyRetained: true
+      });
+    } catch (error) {
+      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();
+      logger.debug(
+        `ChatSession ${this.id}: Memory cleanup completed (chat history preserved)`
+      );
+    } catch (error) {
+      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() {
+    logger.debug(`Disposing session ${this.id} - cleaning up event listeners`);
+    this.forwarders.forEach((forwarder, eventName) => {
+      this.eventBus.off(eventName, forwarder);
+    });
+    this.forwarders.clear();
+    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;
+    }
+  }
+}
+export {
+  ChatSession
+};

package/dist/session/error-codes.cjs

@@ -0,0 +1,35 @@
+"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 error_codes_exports = {};
+__export(error_codes_exports, {
+  SessionErrorCode: () => SessionErrorCode
+});
+module.exports = __toCommonJS(error_codes_exports);
+var SessionErrorCode = /* @__PURE__ */ ((SessionErrorCode2) => {
+  SessionErrorCode2["SESSION_NOT_FOUND"] = "session_not_found";
+  SessionErrorCode2["SESSION_INITIALIZATION_FAILED"] = "session_initialization_failed";
+  SessionErrorCode2["SESSION_MAX_SESSIONS_EXCEEDED"] = "session_max_sessions_exceeded";
+  SessionErrorCode2["SESSION_STORAGE_FAILED"] = "session_storage_failed";
+  SessionErrorCode2["SESSION_RESET_FAILED"] = "session_reset_failed";
+  return SessionErrorCode2;
+})(SessionErrorCode || {});
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SessionErrorCode
+});

package/dist/session/error-codes.d.cts

@@ -0,0 +1,13 @@
+/**
+ * Session-specific error codes
+ * Includes session lifecycle, management, and state errors
+ */
+declare enum SessionErrorCode {
+    SESSION_NOT_FOUND = "session_not_found",
+    SESSION_INITIALIZATION_FAILED = "session_initialization_failed",
+    SESSION_MAX_SESSIONS_EXCEEDED = "session_max_sessions_exceeded",
+    SESSION_STORAGE_FAILED = "session_storage_failed",
+    SESSION_RESET_FAILED = "session_reset_failed"
+}
+
+export { SessionErrorCode };

package/dist/session/error-codes.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Session-specific error codes
+ * Includes session lifecycle, management, and state errors
+ */
+declare enum SessionErrorCode {
+    SESSION_NOT_FOUND = "session_not_found",
+    SESSION_INITIALIZATION_FAILED = "session_initialization_failed",
+    SESSION_MAX_SESSIONS_EXCEEDED = "session_max_sessions_exceeded",
+    SESSION_STORAGE_FAILED = "session_storage_failed",
+    SESSION_RESET_FAILED = "session_reset_failed"
+}
+
+export { SessionErrorCode };

package/dist/session/error-codes.js

@@ -0,0 +1,11 @@
+var SessionErrorCode = /* @__PURE__ */ ((SessionErrorCode2) => {
+  SessionErrorCode2["SESSION_NOT_FOUND"] = "session_not_found";
+  SessionErrorCode2["SESSION_INITIALIZATION_FAILED"] = "session_initialization_failed";
+  SessionErrorCode2["SESSION_MAX_SESSIONS_EXCEEDED"] = "session_max_sessions_exceeded";
+  SessionErrorCode2["SESSION_STORAGE_FAILED"] = "session_storage_failed";
+  SessionErrorCode2["SESSION_RESET_FAILED"] = "session_reset_failed";
+  return SessionErrorCode2;
+})(SessionErrorCode || {});
+export {
+  SessionErrorCode
+};

package/dist/session/errors.cjs

@@ -0,0 +1,93 @@
+"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 errors_exports = {};
+__export(errors_exports, {
+  SessionError: () => SessionError
+});
+module.exports = __toCommonJS(errors_exports);
+var import_DextoRuntimeError = require("../errors/DextoRuntimeError.cjs");
+var import_types = require("../errors/types.cjs");
+var import_error_codes = require("./error-codes.js");
+class SessionError {
+  /**
+   * Session not found
+   */
+  static notFound(sessionId) {
+    return new import_DextoRuntimeError.DextoRuntimeError(
+      import_error_codes.SessionErrorCode.SESSION_NOT_FOUND,
+      import_types.ErrorScope.SESSION,
+      import_types.ErrorType.NOT_FOUND,
+      `Session ${sessionId} not found`,
+      { sessionId }
+    );
+  }
+  /**
+   * Session initialization failed
+   */
+  static initializationFailed(sessionId, reason) {
+    return new import_DextoRuntimeError.DextoRuntimeError(
+      import_error_codes.SessionErrorCode.SESSION_INITIALIZATION_FAILED,
+      import_types.ErrorScope.SESSION,
+      import_types.ErrorType.SYSTEM,
+      `Failed to initialize session '${sessionId}': ${reason}`,
+      { sessionId, reason }
+    );
+  }
+  /**
+   * Maximum number of sessions exceeded
+   */
+  static maxSessionsExceeded(currentCount, maxSessions) {
+    return new import_DextoRuntimeError.DextoRuntimeError(
+      import_error_codes.SessionErrorCode.SESSION_MAX_SESSIONS_EXCEEDED,
+      import_types.ErrorScope.SESSION,
+      import_types.ErrorType.USER,
+      `Maximum sessions (${maxSessions}) reached`,
+      { currentCount, maxSessions },
+      "Delete unused sessions or increase maxSessions limit in configuration"
+    );
+  }
+  /**
+   * Session storage failed
+   */
+  static storageFailed(sessionId, operation, reason) {
+    return new import_DextoRuntimeError.DextoRuntimeError(
+      import_error_codes.SessionErrorCode.SESSION_STORAGE_FAILED,
+      import_types.ErrorScope.SESSION,
+      import_types.ErrorType.SYSTEM,
+      `Failed to ${operation} session '${sessionId}': ${reason}`,
+      { sessionId, operation, reason }
+    );
+  }
+  /**
+   * Session reset failed
+   */
+  static resetFailed(sessionId, reason) {
+    return new import_DextoRuntimeError.DextoRuntimeError(
+      import_error_codes.SessionErrorCode.SESSION_RESET_FAILED,
+      import_types.ErrorScope.SESSION,
+      import_types.ErrorType.SYSTEM,
+      `Failed to reset session '${sessionId}': ${reason}`,
+      { sessionId, reason }
+    );
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SessionError
+});

package/dist/session/errors.d.cts

@@ -0,0 +1,58 @@
+import { DextoRuntimeError } from '../errors/DextoRuntimeError.cjs';
+import '../errors/DextoBaseError.cjs';
+import '../errors/types.cjs';
+import '../agent/error-codes.cjs';
+import '../config/error-codes.cjs';
+import '../context/error-codes.cjs';
+import '../llm/error-codes.cjs';
+import '../mcp/error-codes.cjs';
+import './error-codes.cjs';
+import '../storage/error-codes.cjs';
+import '../systemPrompt/error-codes.cjs';
+import '../tools/error-codes.cjs';
+import '../preferences/error-codes.cjs';
+import '../agent/registry/error-codes.cjs';
+
+/**
+ * Session error factory with typed methods for creating session-specific errors
+ * Each method creates a properly typed DextoError with SESSION scope
+ */
+declare class SessionError {
+    /**
+     * Session not found
+     */
+    static notFound(sessionId: string): DextoRuntimeError<{
+        sessionId: string;
+    }>;
+    /**
+     * Session initialization failed
+     */
+    static initializationFailed(sessionId: string, reason: string): DextoRuntimeError<{
+        sessionId: string;
+        reason: string;
+    }>;
+    /**
+     * Maximum number of sessions exceeded
+     */
+    static maxSessionsExceeded(currentCount: number, maxSessions: number): DextoRuntimeError<{
+        currentCount: number;
+        maxSessions: number;
+    }>;
+    /**
+     * Session storage failed
+     */
+    static storageFailed(sessionId: string, operation: string, reason: string): DextoRuntimeError<{
+        sessionId: string;
+        operation: string;
+        reason: string;
+    }>;
+    /**
+     * Session reset failed
+     */
+    static resetFailed(sessionId: string, reason: string): DextoRuntimeError<{
+        sessionId: string;
+        reason: string;
+    }>;
+}
+
+export { SessionError };

package/dist/session/errors.d.ts

@@ -0,0 +1,58 @@
+import { DextoRuntimeError } from '../errors/DextoRuntimeError.js';
+import '../errors/DextoBaseError.js';
+import '../errors/types.js';
+import '../agent/error-codes.js';
+import '../config/error-codes.js';
+import '../context/error-codes.js';
+import '../llm/error-codes.js';
+import '../mcp/error-codes.js';
+import './error-codes.js';
+import '../storage/error-codes.js';
+import '../systemPrompt/error-codes.js';
+import '../tools/error-codes.js';
+import '../preferences/error-codes.js';
+import '../agent/registry/error-codes.js';
+
+/**
+ * Session error factory with typed methods for creating session-specific errors
+ * Each method creates a properly typed DextoError with SESSION scope
+ */
+declare class SessionError {
+    /**
+     * Session not found
+     */
+    static notFound(sessionId: string): DextoRuntimeError<{
+        sessionId: string;
+    }>;
+    /**
+     * Session initialization failed
+     */
+    static initializationFailed(sessionId: string, reason: string): DextoRuntimeError<{
+        sessionId: string;
+        reason: string;
+    }>;
+    /**
+     * Maximum number of sessions exceeded
+     */
+    static maxSessionsExceeded(currentCount: number, maxSessions: number): DextoRuntimeError<{
+        currentCount: number;
+        maxSessions: number;
+    }>;
+    /**
+     * Session storage failed
+     */
+    static storageFailed(sessionId: string, operation: string, reason: string): DextoRuntimeError<{
+        sessionId: string;
+        operation: string;
+        reason: string;
+    }>;
+    /**
+     * Session reset failed
+     */
+    static resetFailed(sessionId: string, reason: string): DextoRuntimeError<{
+        sessionId: string;
+        reason: string;
+    }>;
+}
+
+export { SessionError };

package/dist/session/errors.js

@@ -0,0 +1,69 @@
+import { DextoRuntimeError } from "../errors/DextoRuntimeError.js";
+import { ErrorScope, ErrorType } from "../errors/types.js";
+import { SessionErrorCode } from "./error-codes.js";
+class SessionError {
+  /**
+   * Session not found
+   */
+  static notFound(sessionId) {
+    return new DextoRuntimeError(
+      SessionErrorCode.SESSION_NOT_FOUND,
+      ErrorScope.SESSION,
+      ErrorType.NOT_FOUND,
+      `Session ${sessionId} not found`,
+      { sessionId }
+    );
+  }
+  /**
+   * Session initialization failed
+   */
+  static initializationFailed(sessionId, reason) {
+    return new DextoRuntimeError(
+      SessionErrorCode.SESSION_INITIALIZATION_FAILED,
+      ErrorScope.SESSION,
+      ErrorType.SYSTEM,
+      `Failed to initialize session '${sessionId}': ${reason}`,
+      { sessionId, reason }
+    );
+  }
+  /**
+   * Maximum number of sessions exceeded
+   */
+  static maxSessionsExceeded(currentCount, maxSessions) {
+    return new DextoRuntimeError(
+      SessionErrorCode.SESSION_MAX_SESSIONS_EXCEEDED,
+      ErrorScope.SESSION,
+      ErrorType.USER,
+      `Maximum sessions (${maxSessions}) reached`,
+      { currentCount, maxSessions },
+      "Delete unused sessions or increase maxSessions limit in configuration"
+    );
+  }
+  /**
+   * Session storage failed
+   */
+  static storageFailed(sessionId, operation, reason) {
+    return new DextoRuntimeError(
+      SessionErrorCode.SESSION_STORAGE_FAILED,
+      ErrorScope.SESSION,
+      ErrorType.SYSTEM,
+      `Failed to ${operation} session '${sessionId}': ${reason}`,
+      { sessionId, operation, reason }
+    );
+  }
+  /**
+   * Session reset failed
+   */
+  static resetFailed(sessionId, reason) {
+    return new DextoRuntimeError(
+      SessionErrorCode.SESSION_RESET_FAILED,
+      ErrorScope.SESSION,
+      ErrorType.SYSTEM,
+      `Failed to reset session '${sessionId}': ${reason}`,
+      { sessionId, reason }
+    );
+  }
+}
+export {
+  SessionError
+};