@dexto/core 1.1.4 → 1.1.6

package/dist/agent/DextoAgent.cjs

@@ -0,0 +1,793 @@
+"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 DextoAgent_exports = {};
+__export(DextoAgent_exports, {
+  DextoAgent: () => DextoAgent
+});
+module.exports = __toCommonJS(DextoAgent_exports);
+var import_session = require("../session/index.js");
+var import_logger = require("../logger/index.js");
+var import_schemas = require("../llm/schemas.cjs");
+var import_resolver = require("../llm/resolver.js");
+var import_validation = require("../llm/validation.js");
+var import_errors = require("./errors.js");
+var import_errors2 = require("../mcp/errors.js");
+var import_result_bridge = require("../errors/result-bridge.cjs");
+var import_result = require("../utils/result.cjs");
+var import_resolver2 = require("../mcp/resolver.js");
+var import_registry = require("../llm/registry.js");
+var import_service_initializer2 = require("../utils/service-initializer.js");
+var import_schemas2 = require("./schemas.js");
+var import_path = require("../utils/path.js");
+var import_safe_stringify = require("../utils/safe-stringify.cjs");
+const requiredServices = [
+  "mcpManager",
+  "toolManager",
+  "promptManager",
+  "agentEventBus",
+  "stateManager",
+  "sessionManager",
+  "searchService"
+];
+class DextoAgent {
+  constructor(config, configPath) {
+    this.configPath = configPath;
+    this.config = import_schemas2.AgentConfigSchema.parse(config);
+    import_logger.logger.info("DextoAgent created.");
+  }
+  /**
+   * These services are public for use by the outside world
+   * This gives users the option to use methods of the services directly if they know what they are doing
+   * But the main recommended entry points/functions would still be the wrapper methods we define below
+   */
+  mcpManager;
+  promptManager;
+  agentEventBus;
+  stateManager;
+  sessionManager;
+  toolManager;
+  services;
+  // Search service for conversation search
+  searchService;
+  // Default session for backward compatibility
+  defaultSession = null;
+  // Current default session ID for loadSession functionality
+  currentDefaultSessionId = "default";
+  // Track initialization state
+  _isStarted = false;
+  _isStopped = false;
+  // Store config for async initialization
+  config;
+  /**
+   * Starts the agent by initializing all async services.
+   * This method handles storage backends, MCP connections, session manager initialization, and other async operations.
+   * Must be called before using any agent functionality.
+   *
+   * @throws Error if agent is already started or initialization fails
+   */
+  async start() {
+    if (this._isStarted) {
+      throw import_errors.AgentError.alreadyStarted();
+    }
+    try {
+      import_logger.logger.info("Starting DextoAgent...");
+      const services = await (0, import_service_initializer2.createAgentServices)(this.config, this.configPath);
+      for (const service of requiredServices) {
+        if (!services[service]) {
+          throw import_errors.AgentError.initializationFailed(
+            `Required service ${service} is missing during agent start`
+          );
+        }
+      }
+      Object.assign(this, {
+        mcpManager: services.mcpManager,
+        toolManager: services.toolManager,
+        promptManager: services.promptManager,
+        agentEventBus: services.agentEventBus,
+        stateManager: services.stateManager,
+        sessionManager: services.sessionManager,
+        services
+      });
+      this.searchService = services.searchService;
+      this._isStarted = true;
+      import_logger.logger.info("DextoAgent started successfully.");
+      const logPath = (0, import_path.getDextoPath)("logs", "dexto.log");
+      console.log(`\u{1F4CB} Logs available at: ${logPath}`);
+    } catch (error) {
+      import_logger.logger.error("Failed to start DextoAgent", error);
+      throw error;
+    }
+  }
+  /**
+   * Stops the agent and gracefully shuts down all services.
+   * This method handles disconnecting MCP clients, cleaning up sessions, closing storage connections,
+   * and releasing all resources. The agent cannot be restarted after being stopped.
+   *
+   * @throws Error if agent has not been started or shutdown fails
+   */
+  async stop() {
+    if (this._isStopped) {
+      import_logger.logger.warn("Agent is already stopped");
+      return;
+    }
+    if (!this._isStarted) {
+      throw import_errors.AgentError.notStarted();
+    }
+    try {
+      import_logger.logger.info("Stopping DextoAgent...");
+      const shutdownErrors = [];
+      try {
+        if (this.sessionManager) {
+          await this.sessionManager.cleanup();
+          import_logger.logger.debug("SessionManager cleaned up successfully");
+        }
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        shutdownErrors.push(new Error(`SessionManager cleanup failed: ${err.message}`));
+      }
+      try {
+        if (this.mcpManager) {
+          await this.mcpManager.disconnectAll();
+          import_logger.logger.debug("MCPManager disconnected all clients successfully");
+        }
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        shutdownErrors.push(new Error(`MCPManager disconnect failed: ${err.message}`));
+      }
+      try {
+        if (this.services?.storageManager) {
+          await this.services.storageManager.disconnect();
+          import_logger.logger.debug("Storage manager disconnected successfully");
+        }
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        shutdownErrors.push(new Error(`Storage disconnect failed: ${err.message}`));
+      }
+      this._isStopped = true;
+      this._isStarted = false;
+      if (shutdownErrors.length > 0) {
+        const errorMessages = shutdownErrors.map((e) => e.message).join("; ");
+        import_logger.logger.warn(`DextoAgent stopped with some errors: ${errorMessages}`);
+      } else {
+        import_logger.logger.info("DextoAgent stopped successfully.");
+      }
+    } catch (error) {
+      import_logger.logger.error("Failed to stop DextoAgent", error);
+      throw error;
+    }
+  }
+  /**
+   * Checks if the agent has been started.
+   * @returns true if agent is started, false otherwise
+   */
+  isStarted() {
+    return this._isStarted;
+  }
+  /**
+   * Checks if the agent has been stopped.
+   * @returns true if agent is stopped, false otherwise
+   */
+  isStopped() {
+    return this._isStopped;
+  }
+  /**
+   * Ensures the agent is started before executing operations.
+   * @throws Error if agent is not started or has been stopped
+   */
+  ensureStarted() {
+    if (this._isStopped) {
+      import_logger.logger.warn("Agent is stopped");
+      throw import_errors.AgentError.stopped();
+    }
+    if (!this._isStarted) {
+      import_logger.logger.warn("Agent is not started");
+      throw import_errors.AgentError.notStarted();
+    }
+  }
+  // ============= CORE AGENT FUNCTIONALITY =============
+  /**
+   * Main method for processing user input.
+   * Processes user input through the agent's LLM service and returns the response.
+   *
+   * @param textInput - The user's text message or query to process
+   * @param imageDataInput - Optional image data and MIME type for multimodal input
+   * @param fileDataInput - Optional file data and MIME type for file input
+   * @param sessionId - Optional session ID for multi-session scenarios
+   * @returns Promise that resolves to the AI's response text, or null if no significant response
+   * @throws Error if processing fails
+   */
+  async run(textInput, imageDataInput, fileDataInput, sessionId, stream = false) {
+    this.ensureStarted();
+    try {
+      const targetSessionId = sessionId || this.currentDefaultSessionId;
+      const llmConfig = this.stateManager.getLLMConfig(targetSessionId);
+      const validation = (0, import_validation.validateInputForLLM)(
+        {
+          text: textInput,
+          ...imageDataInput && { imageData: imageDataInput },
+          ...fileDataInput && { fileData: fileDataInput }
+        },
+        {
+          provider: llmConfig.provider,
+          model: llmConfig.model
+        }
+      );
+      (0, import_result_bridge.ensureOk)(validation);
+      const existingSession = await this.sessionManager.getSession(targetSessionId);
+      const session = existingSession || await this.sessionManager.createSession(targetSessionId);
+      import_logger.logger.debug(
+        `DextoAgent.run: sessionId=${targetSessionId}, textLength=${textInput?.length ?? 0}, hasImage=${Boolean(
+          imageDataInput
+        )}, hasFile=${Boolean(fileDataInput)}`
+      );
+      const response = await session.run(textInput, imageDataInput, fileDataInput, stream);
+      this.sessionManager.incrementMessageCount(session.id).catch(
+        (error) => import_logger.logger.warn(
+          `Failed to increment message count: ${error instanceof Error ? error.message : String(error)}`
+        )
+      );
+      return response;
+    } catch (error) {
+      import_logger.logger.error(
+        `Error during DextoAgent.run: ${error instanceof Error ? error.message : JSON.stringify(error)}`
+      );
+      throw error;
+    }
+  }
+  /**
+   * Cancels the currently running turn for a session (or the default session).
+   * Safe to call even if no run is in progress.
+   * @param sessionId Optional session id; defaults to current default session
+   * @returns true if a run was in progress and was signaled to abort; false otherwise
+   */
+  async cancel(sessionId) {
+    this.ensureStarted();
+    const targetSessionId = sessionId || this.currentDefaultSessionId;
+    if (!sessionId && this.defaultSession && this.defaultSession.id === targetSessionId) {
+      return this.defaultSession.cancel();
+    }
+    const existing = await this.sessionManager.getSession(targetSessionId, false);
+    if (existing) {
+      return existing.cancel();
+    }
+    return false;
+  }
+  // ============= SESSION MANAGEMENT =============
+  /**
+   * 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
+   */
+  async createSession(sessionId) {
+    this.ensureStarted();
+    return await this.sessionManager.createSession(sessionId);
+  }
+  /**
+   * Retrieves an existing session by ID.
+   * @param sessionId The session ID to retrieve
+   * @returns The ChatSession if found, undefined otherwise
+   */
+  async getSession(sessionId) {
+    this.ensureStarted();
+    return await this.sessionManager.getSession(sessionId);
+  }
+  /**
+   * Lists all active session IDs.
+   * @returns Array of session IDs
+   */
+  async listSessions() {
+    this.ensureStarted();
+    return await this.sessionManager.listSessions();
+  }
+  /**
+   * 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) {
+    this.ensureStarted();
+    if (sessionId === this.currentDefaultSessionId) {
+      this.defaultSession = null;
+    }
+    return this.sessionManager.endSession(sessionId);
+  }
+  /**
+   * Deletes a session and its conversation history permanently.
+   * Used for user-initiated permanent deletion.
+   * @param sessionId The session ID to delete
+   */
+  async deleteSession(sessionId) {
+    this.ensureStarted();
+    if (sessionId === this.currentDefaultSessionId) {
+      this.defaultSession = null;
+    }
+    return this.sessionManager.deleteSession(sessionId);
+  }
+  /**
+   * Gets metadata for a specific session.
+   * @param sessionId The session ID
+   * @returns The session metadata if found, undefined otherwise
+   */
+  async getSessionMetadata(sessionId) {
+    this.ensureStarted();
+    return await this.sessionManager.getSessionMetadata(sessionId);
+  }
+  /**
+   * Gets the conversation history for a specific session.
+   * @param sessionId The session ID
+   * @returns Promise that resolves to the session's conversation history
+   * @throws Error if session doesn't exist
+   */
+  async getSessionHistory(sessionId) {
+    this.ensureStarted();
+    const session = await this.sessionManager.getSession(sessionId);
+    if (!session) {
+      throw import_session.SessionError.notFound(sessionId);
+    }
+    return await session.getHistory();
+  }
+  /**
+   * Search for messages across all sessions or within a specific session
+   *
+   * @param query The search query string
+   * @param options Search options including session filter, role filter, and pagination
+   * @returns Promise that resolves to search results
+   */
+  async searchMessages(query, options = {}) {
+    this.ensureStarted();
+    return await this.searchService.searchMessages(query, options);
+  }
+  /**
+   * Search for sessions that contain the specified query
+   *
+   * @param query The search query string
+   * @returns Promise that resolves to session search results
+   */
+  async searchSessions(query) {
+    this.ensureStarted();
+    return await this.searchService.searchSessions(query);
+  }
+  /**
+   * Loads a session as the new "default" session for this agent.
+   * All subsequent operations that don't specify a session ID will use this session.
+   * This provides a clean "current working session" pattern for API users.
+   *
+   * @param sessionId The session ID to load as default, or null to reset to original default
+   * @throws Error if session doesn't exist
+   *
+   * @example
+   * ```typescript
+   * // Load a specific session as default
+   * await agent.loadSessionAsDefault('project-alpha');
+   * await agent.run("What's the status?"); // Uses project-alpha session
+   *
+   * // Reset to original default
+   * await agent.loadSessionAsDefault(null);
+   * await agent.run("Hello"); // Uses 'default' session
+   * ```
+   */
+  async loadSessionAsDefault(sessionId = null) {
+    this.ensureStarted();
+    if (sessionId === null) {
+      this.currentDefaultSessionId = "default";
+      this.defaultSession = null;
+      import_logger.logger.debug("Agent default session reset to original default");
+      return;
+    }
+    const session = await this.sessionManager.getSession(sessionId);
+    if (!session) {
+      throw import_session.SessionError.notFound(sessionId);
+    }
+    this.currentDefaultSessionId = sessionId;
+    this.defaultSession = null;
+    import_logger.logger.info(`Agent default session changed to: ${sessionId}`);
+  }
+  /**
+   * Gets the currently loaded default session ID.
+   * This reflects the session loaded via loadSession().
+   *
+   * @returns The current default session ID
+   */
+  getCurrentSessionId() {
+    this.ensureStarted();
+    return this.currentDefaultSessionId;
+  }
+  /**
+   * Gets the currently loaded default session.
+   * This respects the session loaded via loadSession().
+   *
+   * @returns The current default ChatSession
+   */
+  async getDefaultSession() {
+    this.ensureStarted();
+    if (!this.defaultSession || this.defaultSession.id !== this.currentDefaultSessionId) {
+      this.defaultSession = await this.sessionManager.createSession(
+        this.currentDefaultSessionId
+      );
+    }
+    return this.defaultSession;
+  }
+  /**
+   * Resets the conversation history for a specific session or the default session.
+   * Keeps the session alive but the conversation history is cleared.
+   * @param sessionId Optional session ID. If not provided, resets the currently loaded default session.
+   */
+  async resetConversation(sessionId) {
+    this.ensureStarted();
+    try {
+      const targetSessionId = sessionId || this.currentDefaultSessionId;
+      if (!sessionId) {
+        if (!this.defaultSession || this.defaultSession.id !== this.currentDefaultSessionId) {
+          this.defaultSession = await this.sessionManager.createSession(
+            this.currentDefaultSessionId
+          );
+        }
+      }
+      await this.sessionManager.resetSession(targetSessionId);
+      import_logger.logger.info(`DextoAgent conversation reset for session: ${targetSessionId}`);
+      this.agentEventBus.emit("dexto:conversationReset", {
+        sessionId: targetSessionId
+      });
+    } catch (error) {
+      import_logger.logger.error(
+        `Error during DextoAgent.resetConversation: ${error instanceof Error ? error.message : String(error)}`
+      );
+      throw error;
+    }
+  }
+  // ============= LLM MANAGEMENT =============
+  /**
+   * Gets the current LLM configuration with all defaults applied.
+   * @returns Current LLM configuration
+   */
+  getCurrentLLMConfig() {
+    this.ensureStarted();
+    return structuredClone(this.stateManager.getLLMConfig());
+  }
+  /**
+   * Switches the LLM service while preserving conversation history.
+   * This is a comprehensive method that handles ALL validation, configuration building, and switching internally.
+   *
+   * Design:
+   * - Input: Partial<LLMConfig> (allows optional fields like maxIterations?, router?)
+   * - Output: LLMConfig (user-friendly type with all defaults applied)
+   *
+   * Key features:
+   * - Accepts partial LLM configuration object
+   * - Extracts and validates parameters internally
+   * - Infers provider from model if not provided
+   * - Automatically resolves API keys from environment variables
+   * - Uses LLMConfigSchema for comprehensive validation
+   * - Prevents inconsistent partial updates
+   * - Smart defaults for missing configuration values
+   *
+   * @param llmUpdates Partial LLM configuration object containing the updates to apply
+   * @param sessionId Session ID to switch LLM for. If not provided, switches for default session. Use '*' for all sessions
+   * @returns Promise that resolves with the validated LLM configuration
+   * @throws DextoLLMError if validation fails or switching fails
+   *
+   * @example
+   * ```typescript
+   * // Switch to a different model (provider will be inferred, API key auto-resolved)
+   * await agent.switchLLM({ model: 'gpt-4o' });
+   *
+   * // Switch to a different provider with explicit API key
+   * await agent.switchLLM({ provider: 'anthropic', model: 'claude-4-sonnet-20250514', apiKey: 'sk-ant-...' });
+   *
+   * // Switch with router and session options
+   * await agent.switchLLM({ provider: 'anthropic', model: 'claude-4-sonnet-20250514', router: 'in-built' }, 'user-123');
+   *
+   * // Switch for all sessions
+   * await agent.switchLLM({ model: 'gpt-4o' }, '*');
+   * ```
+   */
+  async switchLLM(llmUpdates, sessionId) {
+    this.ensureStarted();
+    import_logger.logger.debug(`DextoAgent.switchLLM: llmUpdates: ${(0, import_safe_stringify.safeStringify)(llmUpdates)}`);
+    const parseResult = import_schemas.LLMUpdatesSchema.safeParse(llmUpdates);
+    if (!parseResult.success) {
+      const validation = (0, import_result.fail)((0, import_result.zodToIssues)(parseResult.error, "error"));
+      (0, import_result_bridge.ensureOk)(validation);
+      throw new Error("Unreachable");
+    }
+    const validatedUpdates = parseResult.data;
+    const currentLLMConfig = sessionId ? this.stateManager.getRuntimeConfig(sessionId).llm : this.stateManager.getRuntimeConfig().llm;
+    const result = (0, import_resolver.resolveAndValidateLLMConfig)(currentLLMConfig, validatedUpdates);
+    const validatedConfig = (0, import_result_bridge.ensureOk)(result);
+    await this.performLLMSwitch(validatedConfig, sessionId);
+    import_logger.logger.info(`DextoAgent.switchLLM: LLM switched to: ${(0, import_safe_stringify.safeStringify)(validatedConfig)}`);
+    const warnings = result.issues.filter((issue) => issue.severity === "warning");
+    if (warnings.length > 0) {
+      import_logger.logger.warn(
+        `LLM switch completed with warnings: ${warnings.map((w) => w.message).join(", ")}`
+      );
+    }
+    return validatedConfig;
+  }
+  /**
+   * Performs the actual LLM switch with a validated configuration.
+   * This is a helper method that handles state management and session switching.
+   *
+   * @param validatedConfig - The validated LLM configuration to apply
+   * @param sessionScope - Session ID, '*' for all sessions, or undefined for default session
+   */
+  async performLLMSwitch(validatedConfig, sessionScope) {
+    this.stateManager.updateLLM(validatedConfig, sessionScope);
+    if (sessionScope === "*") {
+      await this.sessionManager.switchLLMForAllSessions(validatedConfig);
+    } else if (sessionScope) {
+      const session = await this.sessionManager.getSession(sessionScope);
+      if (!session) {
+        throw import_session.SessionError.notFound(sessionScope);
+      }
+      await this.sessionManager.switchLLMForSpecificSession(validatedConfig, sessionScope);
+    } else {
+      await this.sessionManager.switchLLMForDefaultSession(validatedConfig);
+    }
+  }
+  /**
+   * Gets all supported LLM providers.
+   * Returns a strongly-typed array of valid provider names that can be used with the agent.
+   *
+   * @returns Array of supported provider names
+   *
+   * @example
+   * ```typescript
+   * const providers = agent.getSupportedProviders();
+   * console.log(providers); // ['openai', 'anthropic', 'google', 'groq']
+   * ```
+   */
+  getSupportedProviders() {
+    return (0, import_registry.getSupportedProviders)();
+  }
+  /**
+   * Gets all supported models grouped by provider with detailed information.
+   * Returns a strongly-typed object mapping each provider to its available models,
+   * including model metadata such as token limits and default status.
+   *
+   * @returns Object mapping provider names to their model information
+   *
+   * @example
+   * ```typescript
+   * const models = agent.getSupportedModels();
+   * console.log(models.openai); // Array of OpenAI models with metadata
+   * console.log(models.anthropic[0].maxInputTokens); // Token limit for first Anthropic model
+   *
+   * // Check if a model is the default for its provider
+   * const hasDefault = models.google.some(model => model.isDefault);
+   * ```
+   */
+  getSupportedModels() {
+    const result = {};
+    const providers = (0, import_registry.getSupportedProviders)();
+    for (const provider of providers) {
+      const defaultModel = (0, import_registry.getDefaultModelForProvider)(provider);
+      const providerInfo = import_registry.LLM_REGISTRY[provider];
+      result[provider] = providerInfo.models.map((model) => ({
+        ...model,
+        isDefault: model.name === defaultModel
+      }));
+    }
+    return result;
+  }
+  /**
+   * Gets supported models for a specific provider.
+   * Returns model information including metadata for the specified provider only.
+   *
+   * @param provider The provider to get models for
+   * @returns Array of model information for the specified provider
+   * @throws Error if provider is not supported
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   const openaiModels = agent.getSupportedModelsForProvider('openai');
+   *   const defaultModel = openaiModels.find(model => model.isDefault);
+   *   console.log(`Default OpenAI model: ${defaultModel?.name}`);
+   * } catch (error) {
+   *   console.error('Unsupported provider');
+   * }
+   * ```
+   */
+  getSupportedModelsForProvider(provider) {
+    const defaultModel = (0, import_registry.getDefaultModelForProvider)(provider);
+    const providerInfo = import_registry.LLM_REGISTRY[provider];
+    return providerInfo.models.map((model) => ({
+      ...model,
+      isDefault: model.name === defaultModel
+    }));
+  }
+  /**
+   * Infers the provider from a model name.
+   * Searches through all supported providers to find which one supports the given model.
+   *
+   * @param modelName The model name to search for
+   * @returns The provider name if found, null if the model is not supported
+   *
+   * @example
+   * ```typescript
+   * const provider = agent.inferProviderFromModel('gpt-4o');
+   * console.log(provider); // 'openai'
+   *
+   * const provider2 = agent.inferProviderFromModel('claude-4-sonnet-20250514');
+   * console.log(provider2); // 'anthropic'
+   *
+   * const provider3 = agent.inferProviderFromModel('unknown-model');
+   * console.log(provider3); // null
+   * ```
+   */
+  inferProviderFromModel(modelName) {
+    try {
+      return (0, import_registry.getProviderFromModel)(modelName);
+    } catch {
+      return null;
+    }
+  }
+  // ============= MCP SERVER MANAGEMENT =============
+  /**
+   * Connects a new MCP server and adds it to the runtime configuration.
+   * This method handles validation, state management, and establishing the connection.
+   *
+   * @param name The name of the server to connect.
+   * @param config The configuration object for the server.
+   * @throws DextoError if validation fails or connection fails
+   */
+  async connectMcpServer(name, config) {
+    this.ensureStarted();
+    const existingServerNames = Object.keys(this.stateManager.getRuntimeConfig().mcpServers);
+    const validation = (0, import_resolver2.resolveAndValidateMcpServerConfig)(name, config, existingServerNames);
+    const validatedConfig = (0, import_result_bridge.ensureOk)(validation);
+    this.stateManager.addMcpServer(name, validatedConfig);
+    try {
+      await this.mcpManager.connectServer(name, validatedConfig);
+      this.agentEventBus.emit("dexto:mcpServerConnected", {
+        name,
+        success: true
+      });
+      this.agentEventBus.emit("dexto:availableToolsUpdated", {
+        tools: Object.keys(await this.toolManager.getAllTools()),
+        source: "mcp"
+      });
+      import_logger.logger.info(`DextoAgent: Successfully added and connected to MCP server '${name}'.`);
+      const warnings = validation.issues.filter((i) => i.severity === "warning");
+      if (warnings.length > 0) {
+        import_logger.logger.warn(
+          `MCP server connected with warnings: ${warnings.map((w) => w.message).join(", ")}`
+        );
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      import_logger.logger.error(`DextoAgent: Failed to connect to MCP server '${name}': ${errorMessage}`);
+      this.stateManager.removeMcpServer(name);
+      this.agentEventBus.emit("dexto:mcpServerConnected", {
+        name,
+        success: false,
+        error: errorMessage
+      });
+      throw import_errors2.MCPError.connectionFailed(name, errorMessage);
+    }
+  }
+  /**
+   * Removes and disconnects an MCP server.
+   * @param name The name of the server to remove.
+   */
+  async removeMcpServer(name) {
+    this.ensureStarted();
+    await this.mcpManager.removeClient(name);
+    this.stateManager.removeMcpServer(name);
+  }
+  /**
+   * Executes a tool from any source (MCP servers, custom tools, or internal tools).
+   * This is the unified interface for tool execution that can handle all tool types.
+   * @param toolName The name of the tool to execute
+   * @param args The arguments to pass to the tool
+   * @returns The result of the tool execution
+   */
+  async executeTool(toolName, args) {
+    this.ensureStarted();
+    return await this.toolManager.executeTool(toolName, args);
+  }
+  /**
+   * Gets all available tools from all connected MCP servers.
+   * Useful for users to discover what tools are available.
+   * @returns Promise resolving to a map of tool names to tool definitions
+   */
+  async getAllMcpTools() {
+    this.ensureStarted();
+    return await this.mcpManager.getAllTools();
+  }
+  /**
+   * Gets all available tools from all sources (MCP servers and custom tools).
+   * This is the unified interface for tool discovery that includes both MCP and custom tools.
+   * @returns Promise resolving to a map of tool names to tool definitions
+   */
+  async getAllTools() {
+    this.ensureStarted();
+    return await this.toolManager.getAllTools();
+  }
+  /**
+   * Gets all connected MCP clients.
+   * Used by the API layer to inspect client status.
+   * @returns Map of client names to client instances
+   */
+  getMcpClients() {
+    this.ensureStarted();
+    return this.mcpManager.getClients();
+  }
+  /**
+   * Gets all failed MCP connections.
+   * Used by the API layer to report connection errors.
+   * @returns Record of failed connection names to error messages
+   */
+  getMcpFailedConnections() {
+    this.ensureStarted();
+    return this.mcpManager.getFailedConnections();
+  }
+  // ============= PROMPT MANAGEMENT =============
+  /**
+   * Gets the current system prompt with all dynamic content resolved.
+   * This method builds the complete prompt by invoking all configured prompt contributors
+   * (static content, dynamic placeholders, MCP resources, etc.) and returns the final
+   * prompt string that will be sent to the LLM.
+   *
+   * Useful for debugging prompt issues, inspecting what context the AI receives,
+   * and understanding how dynamic content is being incorporated.
+   *
+   * @returns Promise resolving to the complete system prompt string
+   *
+   * @example
+   * ```typescript
+   * // Get the current system prompt for inspection
+   * const prompt = await agent.getSystemPrompt();
+   * console.log('Current system prompt:', prompt);
+   *
+   * // Useful for debugging prompt-related issues
+   * if (response.quality === 'poor') {
+   *   const prompt = await agent.getSystemPrompt();
+   *   console.log('Check if prompt includes expected context:', prompt);
+   * }
+   * ```
+   */
+  async getSystemPrompt() {
+    this.ensureStarted();
+    const context = {
+      mcpManager: this.mcpManager
+    };
+    return await this.promptManager.build(context);
+  }
+  // ============= CONFIGURATION ACCESS =============
+  /**
+   * Gets the effective configuration for a session or the default configuration.
+   * @param sessionId Optional session ID. If not provided, returns default config.
+   * @returns The effective configuration object
+   */
+  getEffectiveConfig(sessionId) {
+    this.ensureStarted();
+    return sessionId ? this.stateManager.getRuntimeConfig(sessionId) : this.stateManager.getRuntimeConfig();
+  }
+  // Future methods could encapsulate more complex agent behaviors:
+  // - Multi-step task execution with progress tracking
+  // - Memory and context management across sessions
+  // - Tool chaining and workflow automation
+  // - Agent collaboration and delegation
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DextoAgent
+});