@dexto/core 1.1.10 → 1.2.0

package/dist/agent/DextoAgent.cjs

@@ -1,8 +1,15 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __knownSymbol = (name, symbol) => (symbol = Symbol[name]) ? symbol : Symbol.for("Symbol." + name);
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -16,13 +23,55 @@ var __copyProps = (to, from, except, desc) => {
   return to;
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __decoratorStart = (base) => [, , , __create(base?.[__knownSymbol("metadata")] ?? null)];
+var __decoratorStrings = ["class", "method", "getter", "setter", "accessor", "field", "value", "get", "set"];
+var __expectFn = (fn) => fn !== void 0 && typeof fn !== "function" ? __typeError("Function expected") : fn;
+var __decoratorContext = (kind, name, done, metadata, fns) => ({ kind: __decoratorStrings[kind], name, metadata, addInitializer: (fn) => done._ ? __typeError("Already initialized") : fns.push(__expectFn(fn || null)) });
+var __decoratorMetadata = (array, target) => __defNormalProp(target, __knownSymbol("metadata"), array[3]);
+var __runInitializers = (array, flags, self, value) => {
+  for (var i = 0, fns = array[flags >> 1], n = fns && fns.length; i < n; i++) flags & 1 ? fns[i].call(self) : value = fns[i].call(self, value);
+  return value;
+};
+var __decorateElement = (array, flags, name, decorators, target, extra) => {
+  var fn, it, done, ctx, access, k = flags & 7, s = !!(flags & 8), p = !!(flags & 16);
+  var j = k > 3 ? array.length + 1 : k ? s ? 1 : 2 : 0, key = __decoratorStrings[k + 5];
+  var initializers = k > 3 && (array[j - 1] = []), extraInitializers = array[j] || (array[j] = []);
+  var desc = k && (!p && !s && (target = target.prototype), k < 5 && (k > 3 || !p) && __getOwnPropDesc(k < 4 ? target : { get [name]() {
+    return __privateGet(this, extra);
+  }, set [name](x) {
+    return __privateSet(this, extra, x);
+  } }, name));
+  k ? p && k < 4 && __name(extra, (k > 2 ? "set " : k > 1 ? "get " : "") + name) : __name(target, name);
+  for (var i = decorators.length - 1; i >= 0; i--) {
+    ctx = __decoratorContext(k, name, done = {}, array[3], extraInitializers);
+    if (k) {
+      ctx.static = s, ctx.private = p, access = ctx.access = { has: p ? (x) => __privateIn(target, x) : (x) => name in x };
+      if (k ^ 3) access.get = p ? (x) => (k ^ 1 ? __privateGet : __privateMethod)(x, target, k ^ 4 ? extra : desc.get) : (x) => x[name];
+      if (k > 2) access.set = p ? (x, y) => __privateSet(x, target, y, k ^ 4 ? extra : desc.set) : (x, y) => x[name] = y;
+    }
+    it = (0, decorators[i])(k ? k < 4 ? p ? extra : desc[key] : k > 4 ? void 0 : { get: desc.get, set: desc.set } : target, ctx), done._ = 1;
+    if (k ^ 4 || it === void 0) __expectFn(it) && (k > 4 ? initializers.unshift(it) : k ? p ? extra = it : desc[key] = it : target = it);
+    else if (typeof it !== "object" || it === null) __typeError("Object expected");
+    else __expectFn(fn = it.get) && (desc.get = fn), __expectFn(fn = it.set) && (desc.set = fn), __expectFn(fn = it.init) && initializers.unshift(fn);
+  }
+  return k || __decoratorMetadata(array, target), desc && __defProp(target, name, desc), p ? k ^ 4 ? extra : desc : target;
+};
+var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateIn = (member, obj) => Object(obj) !== obj ? __typeError('Cannot use the "in" operator on this value') : member.has(obj);
+var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
+var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
+var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
 var DextoAgent_exports = {};
 __export(DextoAgent_exports, {
   DextoAgent: () => DextoAgent
 });
 module.exports = __toCommonJS(DextoAgent_exports);
+var import_resources = require("../resources/index.js");
+var import_utils = require("../context/utils.js");
+var import_prompts = require("../prompts/index.js");
 var import_session = require("../session/index.js");
 var import_logger = require("../logger/index.js");
+var import_decorators = require("../telemetry/decorators.js");
 var import_schemas = require("../llm/schemas.cjs");
 var import_resolver = require("../llm/resolver.js");
 var import_validation = require("../llm/validation.js");
@@ -30,23 +79,39 @@ 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_DextoValidationError = require("../errors/DextoValidationError.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");
-var import_registry2 = require("./registry/registry.js");
 var import_loader = require("../config/loader.js");
+var import_fs = require("fs");
+var import_yaml = require("yaml");
+var import_title_generator = require("../session/title-generator.js");
+var _DextoAgent_decorators, _init;
 const requiredServices = [
   "mcpManager",
   "toolManager",
-  "promptManager",
+  "systemPromptManager",
   "agentEventBus",
   "stateManager",
   "sessionManager",
-  "searchService"
+  "searchService",
+  "memoryManager"
 ];
+_DextoAgent_decorators = [(0, import_decorators.InstrumentClass)({
+  prefix: "agent",
+  excludeMethods: [
+    "isStarted",
+    "isStopped",
+    "getConfig",
+    "getEffectiveConfig",
+    "registerSubscriber",
+    "ensureStarted"
+  ]
+})];
 class DextoAgent {
   constructor(config, configPath) {
     this.configPath = configPath;
@@ -59,11 +124,14 @@ class DextoAgent {
    * But the main recommended entry points/functions would still be the wrapper methods we define below
    */
   mcpManager;
-  promptManager;
+  systemPromptManager;
   agentEventBus;
+  promptManager;
   stateManager;
   sessionManager;
   toolManager;
+  resourceManager;
+  memoryManager;
   services;
   // Search service for conversation search
   searchService;
@@ -76,6 +144,10 @@ class DextoAgent {
   _isStopped = false;
   // Store config for async initialization
   config;
+  // Event subscribers (e.g., WebSocket, Webhook handlers)
+  eventSubscribers = /* @__PURE__ */ new Set();
+  // Telemetry instance for distributed tracing
+  telemetry;
   /**
    * Starts the agent by initializing all async services.
    * This method handles storage backends, MCP connections, session manager initialization, and other async operations.
@@ -100,15 +172,30 @@ class DextoAgent {
       Object.assign(this, {
         mcpManager: services.mcpManager,
         toolManager: services.toolManager,
-        promptManager: services.promptManager,
+        resourceManager: services.resourceManager,
+        systemPromptManager: services.systemPromptManager,
         agentEventBus: services.agentEventBus,
         stateManager: services.stateManager,
         sessionManager: services.sessionManager,
+        memoryManager: services.memoryManager,
         services
       });
       this.searchService = services.searchService;
+      const promptManager = new import_prompts.PromptManager(
+        this.mcpManager,
+        this.resourceManager,
+        this.config,
+        this.agentEventBus,
+        services.storageManager.getDatabase()
+      );
+      await promptManager.initialize();
+      Object.assign(this, { promptManager });
       this._isStarted = true;
+      this._isStopped = false;
       import_logger.logger.info("DextoAgent started successfully.");
+      for (const subscriber of this.eventSubscribers) {
+        subscriber.subscribe(this.agentEventBus);
+      }
       const logPath = (0, import_path.getDextoPath)("logs", "dexto.log");
       console.log(`\u{1F4CB} Logs available at: ${logPath}`);
     } catch (error) {
@@ -143,6 +230,15 @@ class DextoAgent {
         const err = error instanceof Error ? error : new Error(String(error));
         shutdownErrors.push(new Error(`SessionManager cleanup failed: ${err.message}`));
       }
+      try {
+        if (this.services?.pluginManager) {
+          await this.services.pluginManager.cleanup();
+          import_logger.logger.debug("PluginManager cleaned up successfully");
+        }
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        shutdownErrors.push(new Error(`PluginManager cleanup failed: ${err.message}`));
+      }
       try {
         if (this.mcpManager) {
           await this.mcpManager.disconnectAll();
@@ -174,6 +270,30 @@ class DextoAgent {
       throw error;
     }
   }
+  /**
+   * Register an event subscriber that will be automatically re-subscribed on agent restart.
+   * Subscribers are typically API layer components (WebSocket, Webhook handlers) that need
+   * to receive agent events. If the agent is already started, the subscriber is immediately subscribed.
+   *
+   * @param subscriber - Object implementing AgentEventSubscriber interface
+   */
+  registerSubscriber(subscriber) {
+    this.eventSubscribers.add(subscriber);
+    if (this._isStarted) {
+      subscriber.subscribe(this.agentEventBus);
+    }
+  }
+  /**
+   * Restart the agent by stopping and starting it.
+   * Automatically re-subscribes all registered event subscribers to the new event bus.
+   * This is useful when configuration changes require a full agent restart.
+   *
+   * @throws Error if restart fails during stop or start phases
+   */
+  async restart() {
+    await this.stop();
+    await this.start();
+  }
   /**
    * Checks if the agent has been started.
    * @returns true if agent is started, false otherwise
@@ -238,7 +358,56 @@ class DextoAgent {
           imageDataInput
         )}, hasFile=${Boolean(fileDataInput)}`
       );
-      const response = await session.run(textInput, imageDataInput, fileDataInput, stream);
+      let finalText = textInput;
+      let finalImageData = imageDataInput;
+      if (textInput && textInput.includes("@")) {
+        try {
+          const resources = await this.resourceManager.list();
+          const expansion = await (0, import_resources.expandMessageReferences)(
+            textInput,
+            resources,
+            (uri) => this.resourceManager.read(uri)
+          );
+          if (expansion.unresolvedReferences.length > 0) {
+            const unresolvedNames = expansion.unresolvedReferences.map((ref) => ref.originalRef).join(", ");
+            import_logger.logger.warn(
+              `Could not resolve ${expansion.unresolvedReferences.length} resource reference(s): ${unresolvedNames}`
+            );
+          }
+          const MAX_EXPANDED_SIZE = 5 * 1024 * 1024;
+          const expandedSize = Buffer.byteLength(expansion.expandedMessage, "utf-8");
+          if (expandedSize > MAX_EXPANDED_SIZE) {
+            import_logger.logger.warn(
+              `Expanded message size (${(expandedSize / 1024 / 1024).toFixed(2)}MB) exceeds limit (${MAX_EXPANDED_SIZE / 1024 / 1024}MB). Content may be truncated.`
+            );
+          }
+          finalText = expansion.expandedMessage;
+          if (expansion.extractedImages.length > 0 && !imageDataInput) {
+            const firstImage = expansion.extractedImages[0];
+            if (firstImage) {
+              finalImageData = {
+                image: firstImage.image,
+                mimeType: firstImage.mimeType
+              };
+              import_logger.logger.debug(
+                `Using extracted image: ${firstImage.name} (${firstImage.mimeType})`
+              );
+            }
+          }
+        } catch (error) {
+          import_logger.logger.error(
+            `Failed to expand resource references: ${error instanceof Error ? error.message : String(error)}. Continuing with original message.`
+          );
+        }
+      }
+      if (!finalText.trim() && !finalImageData && !fileDataInput) {
+        import_logger.logger.warn(
+          "Resource expansion resulted in empty content. Using original message."
+        );
+        finalText = textInput;
+      }
+      void this.maybeGenerateTitle(targetSessionId, finalText, llmConfig);
+      const response = await session.run(finalText, finalImageData, 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)}`
@@ -330,6 +499,82 @@ class DextoAgent {
     this.ensureStarted();
     return await this.sessionManager.getSessionMetadata(sessionId);
   }
+  /**
+   * Sets a human-friendly title for the given session.
+   */
+  async setSessionTitle(sessionId, title) {
+    this.ensureStarted();
+    await this.sessionManager.setSessionTitle(sessionId, title);
+  }
+  /**
+   * Gets the human-friendly title for the given session, if any.
+   */
+  async getSessionTitle(sessionId) {
+    this.ensureStarted();
+    return await this.sessionManager.getSessionTitle(sessionId);
+  }
+  /**
+   * Background task: generate and persist a session title using the same LLM.
+   * Runs only for the first user message (messageCount === 0 and no existing title).
+   * Never throws; timeboxed in the generator.
+   */
+  async maybeGenerateTitle(sessionId, userText, llmConfig) {
+    try {
+      const metadata = await this.sessionManager.getSessionMetadata(sessionId);
+      if (!metadata) {
+        import_logger.logger.debug(
+          `[SessionTitle] No session metadata available for ${sessionId}, skipping title generation`
+        );
+        return;
+      }
+      if (metadata.title) {
+        import_logger.logger.debug(
+          `[SessionTitle] Session ${sessionId} already has title '${metadata.title}', skipping`
+        );
+        return;
+      }
+      if (!userText || !userText.trim()) {
+        import_logger.logger.debug(
+          `[SessionTitle] User text empty for session ${sessionId}, skipping title generation`
+        );
+        return;
+      }
+      import_logger.logger.debug(
+        `[SessionTitle] Checking title generation preconditions for session ${sessionId}`
+      );
+      const result = await (0, import_title_generator.generateSessionTitle)(
+        llmConfig,
+        llmConfig.router,
+        this.toolManager,
+        this.systemPromptManager,
+        this.resourceManager,
+        userText
+      );
+      if (result.error) {
+        import_logger.logger.debug(
+          `[SessionTitle] LLM title generation failed for ${sessionId}: ${result.error}${result.timedOut ? " (timeout)" : ""}`
+        );
+      }
+      let title = result.title;
+      if (!title) {
+        title = (0, import_title_generator.deriveHeuristicTitle)(userText);
+        if (title) {
+          import_logger.logger.info(`[SessionTitle] Using heuristic title for ${sessionId}: ${title}`);
+        } else {
+          import_logger.logger.debug(
+            `[SessionTitle] No suitable title derived for session ${sessionId}`
+          );
+          return;
+        }
+      } else {
+        import_logger.logger.info(`[SessionTitle] Generated LLM title for ${sessionId}: ${title}`);
+      }
+      await this.sessionManager.setSessionTitle(sessionId, title, { ifUnsetOnly: true });
+      this.agentEventBus.emit("dexto:sessionTitleUpdated", { sessionId, title });
+    } catch (err) {
+      import_logger.logger.silly(`Title generation skipped/failed for ${sessionId}: ${String(err)}`);
+    }
+  }
   /**
    * Gets the conversation history for a specific session.
    * @param sessionId The session ID
@@ -342,7 +587,23 @@ class DextoAgent {
     if (!session) {
       throw import_session.SessionError.notFound(sessionId);
     }
-    return await session.getHistory();
+    const history = await session.getHistory();
+    if (!this.resourceManager) {
+      return history;
+    }
+    return await Promise.all(
+      history.map(async (message) => ({
+        ...message,
+        content: await (0, import_utils.expandBlobReferences)(message.content, this.resourceManager).catch(
+          (error) => {
+            import_logger.logger.warn(
+              `Failed to expand blob references in message: ${error instanceof Error ? error.message : String(error)}`
+            );
+            return message.content;
+          }
+        )
+      }))
+    );
   }
   /**
    * Search for messages across all sessions or within a specific session
@@ -487,7 +748,7 @@ class DextoAgent {
    * @example
    * ```typescript
    * // Switch to a different model (provider will be inferred, API key auto-resolved)
-   * await agent.switchLLM({ model: 'gpt-4o' });
+   * await agent.switchLLM({ model: 'gpt-5' });
    *
    * // Switch to a different provider with explicit API key
    * await agent.switchLLM({ provider: 'anthropic', model: 'claude-4-sonnet-20250514', apiKey: 'sk-ant-...' });
@@ -496,7 +757,7 @@ class DextoAgent {
    * 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' }, '*');
+   * await agent.switchLLM({ model: 'gpt-5' }, '*');
    * ```
    */
   async switchLLM(llmUpdates, sessionId) {
@@ -624,7 +885,7 @@ class DextoAgent {
    *
    * @example
    * ```typescript
-   * const provider = agent.inferProviderFromModel('gpt-4o');
+   * const provider = agent.inferProviderFromModel('gpt-5');
    * console.log(provider); // 'openai'
    *
    * const provider2 = agent.inferProviderFromModel('claude-4-sonnet-20250514');
@@ -658,6 +919,7 @@ class DextoAgent {
     this.stateManager.addMcpServer(name, validatedConfig);
     try {
       await this.mcpManager.connectServer(name, validatedConfig);
+      await this.toolManager.refresh();
       this.agentEventBus.emit("dexto:mcpServerConnected", {
         name,
         success: true
@@ -693,6 +955,33 @@ class DextoAgent {
     this.ensureStarted();
     await this.mcpManager.removeClient(name);
     this.stateManager.removeMcpServer(name);
+    await this.toolManager.refresh();
+  }
+  /**
+   * Restarts an MCP server by disconnecting and reconnecting with its original configuration.
+   * This is useful for recovering from server errors or applying configuration changes.
+   * @param name The name of the server to restart.
+   * @throws MCPError if server is not found or restart fails
+   */
+  async restartMcpServer(name) {
+    this.ensureStarted();
+    try {
+      import_logger.logger.info(`DextoAgent: Restarting MCP server '${name}'...`);
+      await this.mcpManager.restartServer(name);
+      await this.toolManager.refresh();
+      this.agentEventBus.emit("dexto:mcpServerRestarted", {
+        serverName: name
+      });
+      this.agentEventBus.emit("dexto:availableToolsUpdated", {
+        tools: Object.keys(await this.toolManager.getAllTools()),
+        source: "mcp"
+      });
+      import_logger.logger.info(`DextoAgent: Successfully restarted MCP server '${name}'.`);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      import_logger.logger.error(`DextoAgent: Failed to restart MCP server '${name}': ${errorMessage}`);
+      throw error;
+    }
   }
   /**
    * Executes a tool from any source (MCP servers, custom tools, or internal tools).
@@ -741,6 +1030,43 @@ class DextoAgent {
     this.ensureStarted();
     return this.mcpManager.getFailedConnections();
   }
+  // ============= RESOURCE MANAGEMENT =============
+  /**
+   * Lists all available resources with their info.
+   * This includes resources from MCP servers and any custom resource providers.
+   */
+  async listResources() {
+    this.ensureStarted();
+    return await this.resourceManager.list();
+  }
+  /**
+   * Checks if a resource exists by URI.
+   */
+  async hasResource(uri) {
+    this.ensureStarted();
+    return await this.resourceManager.has(uri);
+  }
+  /**
+   * Reads the content of a specific resource by URI.
+   */
+  async readResource(uri) {
+    this.ensureStarted();
+    return await this.resourceManager.read(uri);
+  }
+  /**
+   * Lists resources for a specific MCP server.
+   */
+  async listResourcesForServer(serverId) {
+    this.ensureStarted();
+    const allResources = await this.resourceManager.list();
+    const serverResources = Object.values(allResources).filter((resource) => resource.serverName === serverId).map((resource) => {
+      const original = resource.metadata?.originalUri ?? resource.uri;
+      const name = resource.name ?? resource.uri.split("/").pop() ?? resource.uri;
+      const serverName = resource.serverName ?? serverId;
+      return { uri: original, name, originalUri: original, serverName };
+    });
+    return serverResources;
+  }
   // ============= PROMPT MANAGEMENT =============
   /**
    * Gets the current system prompt with all dynamic content resolved.
@@ -771,7 +1097,75 @@ class DextoAgent {
     const context = {
       mcpManager: this.mcpManager
     };
-    return await this.promptManager.build(context);
+    return await this.systemPromptManager.build(context);
+  }
+  /**
+   * Lists all available prompts from all providers (MCP, internal, starter, custom).
+   * @returns Promise resolving to a PromptSet with all available prompts
+   */
+  async listPrompts() {
+    this.ensureStarted();
+    return await this.promptManager.list();
+  }
+  /**
+   * Gets the definition of a specific prompt by name.
+   * @param name The name of the prompt
+   * @returns Promise resolving to the prompt definition or null if not found
+   */
+  async getPromptDefinition(name) {
+    this.ensureStarted();
+    return await this.promptManager.getPromptDefinition(name);
+  }
+  /**
+   * Checks if a prompt exists.
+   * @param name The name of the prompt to check
+   * @returns Promise resolving to true if the prompt exists, false otherwise
+   */
+  async hasPrompt(name) {
+    this.ensureStarted();
+    return await this.promptManager.has(name);
+  }
+  /**
+   * Gets a prompt with its messages.
+   * @param name The name of the prompt
+   * @param args Optional arguments to pass to the prompt
+   * @returns Promise resolving to the prompt result with messages
+   */
+  async getPrompt(name, args) {
+    this.ensureStarted();
+    return await this.promptManager.getPrompt(name, args);
+  }
+  /**
+   * Creates a new custom prompt.
+   * @param input The prompt creation input
+   * @returns Promise resolving to the created prompt info
+   */
+  async createCustomPrompt(input) {
+    this.ensureStarted();
+    return await this.promptManager.createCustomPrompt(input);
+  }
+  /**
+   * Deletes a custom prompt by name.
+   * @param name The name of the custom prompt to delete
+   */
+  async deleteCustomPrompt(name) {
+    this.ensureStarted();
+    return await this.promptManager.deleteCustomPrompt(name);
+  }
+  /**
+   * Resolves a prompt to its text content with all arguments applied.
+   * This is a high-level method that handles:
+   * - Prompt key resolution (resolving aliases)
+   * - Argument normalization (including special _context field)
+   * - Prompt execution and flattening
+   *
+   * @param name The prompt name or alias
+   * @param options Optional configuration for prompt resolution
+   * @returns Promise resolving to the resolved text and resource URIs
+   */
+  async resolvePrompt(name, options = {}) {
+    this.ensureStarted();
+    return await this.promptManager.resolvePrompt(name, options);
   }
   // ============= CONFIGURATION ACCESS =============
   /**
@@ -783,144 +1177,144 @@ class DextoAgent {
     this.ensureStarted();
     return sessionId ? this.stateManager.getRuntimeConfig(sessionId) : this.stateManager.getRuntimeConfig();
   }
-  // ============= AGENT MANAGEMENT =============
   /**
-   * Lists available and installed agents from the registry.
-   * Returns a structured object containing both installed and available agents,
-   * along with metadata like descriptions, authors, and tags.
-   *
-   * @returns Promise resolving to object with installed and available agent lists
-   *
-   * @example
-   * ```typescript
-   * const agents = await agent.listAgents();
-   * console.log(agents.installed); // ['default', 'my-custom-agent']
-   * console.log(agents.available); // [{ name: 'productivity', description: '...', ... }]
-   * console.log(agents.current?.name); // 'default'
-   * ```
+   * Gets the file path of the agent configuration currently in use.
+   * This returns the source agent file path, not session-specific overrides.
+   * @returns The path to the agent configuration file
+   * @throws AgentError if no config path is available
    */
-  async listAgents() {
-    const agentRegistry = (0, import_registry2.getAgentRegistry)();
-    const availableMap = agentRegistry.getAvailableAgents();
-    const installedNames = await agentRegistry.getInstalledAgents();
-    const installed = await Promise.all(
-      installedNames.map(async (name) => {
-        const registryEntry = availableMap[name];
-        if (registryEntry) {
-          return {
-            name,
-            description: registryEntry.description,
-            author: registryEntry.author,
-            tags: registryEntry.tags
-          };
-        } else {
-          try {
-            const config = await (0, import_loader.loadAgentConfig)(name);
-            const author = config.agentCard?.provider?.organization;
-            const result = {
-              name,
-              description: config.agentCard?.description || "Local agent",
-              tags: []
-            };
-            if (author) {
-              result.author = author;
-            }
-            return result;
-          } catch {
-            return {
-              name,
-              description: "Local agent (config unavailable)",
-              tags: []
-            };
-          }
-        }
-      })
-    );
-    const available = Object.entries(availableMap).filter(([name]) => !installedNames.includes(name)).map(([name, entry]) => ({
-      name,
-      description: entry.description,
-      author: entry.author,
-      tags: entry.tags
-    }));
-    return {
-      installed,
-      available,
-      current: { name: null }
-      // TODO: Track current agent name
-    };
+  getAgentFilePath() {
+    if (!this.configPath) {
+      throw import_errors.AgentError.noConfigPath();
+    }
+    return this.configPath;
   }
   /**
-   * Installs an agent from the registry.
-   * Downloads and sets up the specified agent, making it available for use.
+   * Reloads the agent configuration from disk.
+   * This will re-read the config file, validate it, and detect what changed.
+   * Most configuration changes require a full agent restart to take effect.
    *
-   * @param agentName The name of the agent to install from the registry
-   * @returns Promise that resolves when installation is complete
+   * To apply changes: stop the agent and start it again with the new config.
    *
-   * @throws {AgentError} When agent is not found in registry or installation fails
+   * @returns Object containing list of changes that require restart
+   * @throws Error if config file cannot be read or is invalid
    *
-   * @example
-   * ```typescript
-   * await agent.installAgent('productivity');
-   * console.log('Productivity agent installed successfully');
-   * ```
+   * TODO: improve hot reload capabilites so that we don't always require a restart
    */
-  async installAgent(agentName) {
-    const agentRegistry = (0, import_registry2.getAgentRegistry)();
-    if (!agentRegistry.hasAgent(agentName)) {
-      throw import_errors.AgentError.apiValidationError(`Agent '${agentName}' not found in registry`);
+  async reloadConfig() {
+    if (!this.configPath) {
+      throw import_errors.AgentError.noConfigPath();
     }
-    try {
-      await agentRegistry.installAgent(agentName, true);
-      import_logger.logger.info(`Successfully installed agent: ${agentName}`);
-    } catch (error) {
-      import_logger.logger.error(`Failed to install agent ${agentName}:`, error);
-      throw import_errors.AgentError.apiValidationError(
-        `Installation failed for agent '${agentName}'`,
-        error
+    import_logger.logger.info(`Reloading agent configuration from: ${this.configPath}`);
+    const oldConfig = this.config;
+    const newConfig = await (0, import_loader.loadAgentConfig)(this.configPath);
+    const validated = import_schemas2.AgentConfigSchema.parse(newConfig);
+    const restartRequired = this.detectRestartRequiredChanges(oldConfig, validated);
+    this.config = validated;
+    if (restartRequired.length > 0) {
+      import_logger.logger.warn(
+        `Configuration updated. Restart required to apply: ${restartRequired.join(", ")}`
       );
+    } else {
+      import_logger.logger.info("Agent configuration reloaded successfully (no changes detected)");
     }
+    return {
+      restartRequired
+    };
   }
   /**
-   * Creates a new agent instance for the specified agent name.
-   * This method resolves the agent (installing if needed), loads its configuration,
-   * and returns a new DextoAgent instance ready to be started.
-   *
-   * This is a factory method that doesn't affect the current agent instance.
-   * The caller is responsible for managing the lifecycle of the returned agent.
-   *
-   * @param agentName The name of the agent to create
-   * @returns Promise resolving to a new DextoAgent instance (not started)
-   *
-   * @throws {AgentError} When agent is not found or creation fails
+   * Updates and saves the agent configuration to disk.
+   * This merges the updates with the raw config from disk, validates, and writes to file.
+   * IMPORTANT: This preserves environment variable placeholders (e.g., $OPENAI_API_KEY)
+   * to avoid leaking secrets into the config file.
+   * @param updates Partial configuration updates to apply
+   * @param targetPath Optional path to save to (defaults to current config path)
+   * @returns Object containing list of changes that require restart
+   * @throws Error if validation fails or file cannot be written
+   */
+  async updateAndSaveConfig(updates, targetPath) {
+    const path = targetPath || this.configPath;
+    if (!path) {
+      throw import_errors.AgentError.noConfigPath();
+    }
+    import_logger.logger.info(`Updating and saving agent configuration to: ${path}`);
+    const rawYaml = await import_fs.promises.readFile(path, "utf-8");
+    const doc = (0, import_yaml.parseDocument)(rawYaml);
+    const rawConfig = doc.toJSON();
+    const updatedRawConfig = { ...rawConfig, ...updates };
+    const parsed = import_schemas2.AgentConfigSchema.safeParse(updatedRawConfig);
+    if (!parsed.success) {
+      const result = (0, import_result.fail)((0, import_result.zodToIssues)(parsed.error, "error"));
+      throw new import_DextoValidationError.DextoValidationError(result.issues);
+    }
+    for (const [key, value] of Object.entries(updates)) {
+      doc.set(key, value);
+    }
+    const yamlContent = String(doc);
+    const tmpPath = `${path}.tmp`;
+    await import_fs.promises.writeFile(tmpPath, yamlContent, "utf-8");
+    await import_fs.promises.rename(tmpPath, path);
+    const reloadResult = await this.reloadConfig();
+    import_logger.logger.info(`Agent configuration saved to: ${path}`);
+    return reloadResult;
+  }
+  /**
+   * Detects configuration changes that require a full agent restart.
+   * Returns an array of change descriptions.
    *
-   * @example
-   * ```typescript
-   * const newAgent = await DextoAgent.createAgent('productivity');
-   * await newAgent.start();
-   * ```
+   * @param oldConfig Previous validated configuration
+   * @param newConfig New validated configuration
+   * @returns Array of restart-required change descriptions
+   * @private
    */
-  static async createAgent(agentName) {
-    const agentRegistry = (0, import_registry2.getAgentRegistry)();
-    try {
-      const agentPath = await agentRegistry.resolveAgent(agentName, true, true);
-      const config = await (0, import_loader.loadAgentConfig)(agentPath);
-      import_logger.logger.info(`Creating agent: ${agentName}`);
-      const newAgent = new DextoAgent(config, agentPath);
-      import_logger.logger.info(`Successfully created agent: ${agentName}`);
-      return newAgent;
-    } catch (error) {
-      import_logger.logger.error(
-        `Failed to create agent '${agentName}': ${error instanceof Error ? error.message : String(error)}`
-      );
-      throw import_errors.AgentError.apiValidationError(`Failed to create agent '${agentName}'`, error);
+  detectRestartRequiredChanges(oldConfig, newConfig) {
+    const changes = [];
+    if (JSON.stringify(oldConfig.storage) !== JSON.stringify(newConfig.storage)) {
+      changes.push("Storage backend");
+    }
+    if (JSON.stringify(oldConfig.sessions) !== JSON.stringify(newConfig.sessions)) {
+      changes.push("Session configuration");
+    }
+    if (JSON.stringify(oldConfig.systemPrompt) !== JSON.stringify(newConfig.systemPrompt)) {
+      changes.push("System prompt");
     }
+    if (JSON.stringify(oldConfig.toolConfirmation) !== JSON.stringify(newConfig.toolConfirmation)) {
+      changes.push("Tool confirmation");
+    }
+    if (JSON.stringify(oldConfig.internalTools) !== JSON.stringify(newConfig.internalTools)) {
+      changes.push("Internal tools");
+    }
+    if (JSON.stringify(oldConfig.mcpServers) !== JSON.stringify(newConfig.mcpServers)) {
+      changes.push("MCP servers");
+    }
+    if (oldConfig.llm.provider !== newConfig.llm.provider || oldConfig.llm.model !== newConfig.llm.model || oldConfig.llm.apiKey !== newConfig.llm.apiKey) {
+      changes.push("LLM configuration");
+    }
+    return changes;
   }
+  // ============= AGENT MANAGEMENT =============
+  // Note: Agent management methods have been moved to the Dexto orchestrator class.
+  // See: /packages/core/src/Dexto.ts
+  //
+  // For agent lifecycle operations (list, install, uninstall, create), use:
+  // ```typescript
+  // await Dexto.listAgents();                 // Static
+  // await Dexto.installAgent(name);           // Static
+  // await Dexto.installCustomAgent(name, path, metadata); // Static
+  // await Dexto.uninstallAgent(name);         // Static
+  //
+  // const dexto = new Dexto();
+  // await dexto.createAgent(name);            // Instance method
+  // ```
   // 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
 }
+_init = __decoratorStart(null);
+DextoAgent = __decorateElement(_init, 0, "DextoAgent", _DextoAgent_decorators, DextoAgent);
+__runInitializers(_init, 1, DextoAgent);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DextoAgent