@dexto/core 1.1.10 → 1.1.11

package/dist/agent/DextoAgent.js

@@ -1,3 +1,6 @@
+import { expandMessageReferences } from "../resources/index.js";
+import { expandBlobReferences } from "../context/utils.js";
+import { PromptManager } from "../prompts/index.js";
 import { SessionError } from "../session/index.js";
 import { logger } from "../logger/index.js";
 import { LLMUpdatesSchema } from "../llm/schemas.js";
@@ -7,6 +10,7 @@ import { AgentError } from "./errors.js";
 import { MCPError } from "../mcp/errors.js";
 import { ensureOk } from "../errors/result-bridge.js";
 import { fail, zodToIssues } from "../utils/result.js";
+import { DextoValidationError } from "../errors/DextoValidationError.js";
 import { resolveAndValidateMcpServerConfig } from "../mcp/resolver.js";
 import {
   getSupportedProviders,
@@ -18,16 +22,19 @@ import { createAgentServices } from "../utils/service-initializer.js";
 import { AgentConfigSchema } from "./schemas.js";
 import { getDextoPath } from "../utils/path.js";
 import { safeStringify } from "../utils/safe-stringify.js";
-import { getAgentRegistry } from "./registry/registry.js";
 import { loadAgentConfig } from "../config/loader.js";
+import { promises as fs } from "fs";
+import { parseDocument } from "yaml";
+import { deriveHeuristicTitle, generateSessionTitle } from "../session/title-generator.js";
 const requiredServices = [
   "mcpManager",
   "toolManager",
-  "promptManager",
+  "systemPromptManager",
   "agentEventBus",
   "stateManager",
   "sessionManager",
-  "searchService"
+  "searchService",
+  "memoryManager"
 ];
 class DextoAgent {
   constructor(config, configPath) {
@@ -41,11 +48,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;
@@ -58,6 +68,8 @@ class DextoAgent {
   _isStopped = false;
   // Store config for async initialization
   config;
+  // Event subscribers (e.g., WebSocket, Webhook handlers)
+  eventSubscribers = /* @__PURE__ */ new Set();
   /**
    * Starts the agent by initializing all async services.
    * This method handles storage backends, MCP connections, session manager initialization, and other async operations.
@@ -82,15 +94,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 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;
       logger.info("DextoAgent started successfully.");
+      for (const subscriber of this.eventSubscribers) {
+        subscriber.subscribe(this.agentEventBus);
+      }
       const logPath = getDextoPath("logs", "dexto.log");
       console.log(`\u{1F4CB} Logs available at: ${logPath}`);
     } catch (error) {
@@ -125,6 +152,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();
+          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();
@@ -156,6 +192,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
@@ -220,7 +280,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 expandMessageReferences(
+            textInput,
+            resources,
+            (uri) => this.resourceManager.read(uri)
+          );
+          if (expansion.unresolvedReferences.length > 0) {
+            const unresolvedNames = expansion.unresolvedReferences.map((ref) => ref.originalRef).join(", ");
+            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) {
+            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
+              };
+              logger.debug(
+                `Using extracted image: ${firstImage.name} (${firstImage.mimeType})`
+              );
+            }
+          }
+        } catch (error) {
+          logger.error(
+            `Failed to expand resource references: ${error instanceof Error ? error.message : String(error)}. Continuing with original message.`
+          );
+        }
+      }
+      if (!finalText.trim() && !finalImageData && !fileDataInput) {
+        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) => logger.warn(
           `Failed to increment message count: ${error instanceof Error ? error.message : String(error)}`
@@ -312,6 +421,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) {
+        logger.debug(
+          `[SessionTitle] No session metadata available for ${sessionId}, skipping title generation`
+        );
+        return;
+      }
+      if (metadata.title) {
+        logger.debug(
+          `[SessionTitle] Session ${sessionId} already has title '${metadata.title}', skipping`
+        );
+        return;
+      }
+      if (!userText || !userText.trim()) {
+        logger.debug(
+          `[SessionTitle] User text empty for session ${sessionId}, skipping title generation`
+        );
+        return;
+      }
+      logger.debug(
+        `[SessionTitle] Checking title generation preconditions for session ${sessionId}`
+      );
+      const result = await generateSessionTitle(
+        llmConfig,
+        llmConfig.router,
+        this.toolManager,
+        this.systemPromptManager,
+        this.resourceManager,
+        userText
+      );
+      if (result.error) {
+        logger.debug(
+          `[SessionTitle] LLM title generation failed for ${sessionId}: ${result.error}${result.timedOut ? " (timeout)" : ""}`
+        );
+      }
+      let title = result.title;
+      if (!title) {
+        title = deriveHeuristicTitle(userText);
+        if (title) {
+          logger.info(`[SessionTitle] Using heuristic title for ${sessionId}: ${title}`);
+        } else {
+          logger.debug(
+            `[SessionTitle] No suitable title derived for session ${sessionId}`
+          );
+          return;
+        }
+      } else {
+        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) {
+      logger.silly(`Title generation skipped/failed for ${sessionId}: ${String(err)}`);
+    }
+  }
   /**
    * Gets the conversation history for a specific session.
    * @param sessionId The session ID
@@ -324,7 +509,23 @@ class DextoAgent {
     if (!session) {
       throw 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 expandBlobReferences(message.content, this.resourceManager).catch(
+          (error) => {
+            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
@@ -640,6 +841,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
@@ -675,6 +877,7 @@ class DextoAgent {
     this.ensureStarted();
     await this.mcpManager.removeClient(name);
     this.stateManager.removeMcpServer(name);
+    await this.toolManager.refresh();
   }
   /**
    * Executes a tool from any source (MCP servers, custom tools, or internal tools).
@@ -723,6 +926,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.
@@ -753,7 +993,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 =============
   /**
@@ -765,138 +1073,135 @@ 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 = 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 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 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 = getAgentRegistry();
-    if (!agentRegistry.hasAgent(agentName)) {
-      throw AgentError.apiValidationError(`Agent '${agentName}' not found in registry`);
+  async reloadConfig() {
+    if (!this.configPath) {
+      throw AgentError.noConfigPath();
     }
-    try {
-      await agentRegistry.installAgent(agentName, true);
-      logger.info(`Successfully installed agent: ${agentName}`);
-    } catch (error) {
-      logger.error(`Failed to install agent ${agentName}:`, error);
-      throw AgentError.apiValidationError(
-        `Installation failed for agent '${agentName}'`,
-        error
+    logger.info(`Reloading agent configuration from: ${this.configPath}`);
+    const oldConfig = this.config;
+    const newConfig = await loadAgentConfig(this.configPath);
+    const validated = AgentConfigSchema.parse(newConfig);
+    const restartRequired = this.detectRestartRequiredChanges(oldConfig, validated);
+    this.config = validated;
+    if (restartRequired.length > 0) {
+      logger.warn(
+        `Configuration updated. Restart required to apply: ${restartRequired.join(", ")}`
       );
+    } else {
+      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 AgentError.noConfigPath();
+    }
+    logger.info(`Updating and saving agent configuration to: ${path}`);
+    const rawYaml = await fs.readFile(path, "utf-8");
+    const doc = parseDocument(rawYaml);
+    const rawConfig = doc.toJSON();
+    const updatedRawConfig = { ...rawConfig, ...updates };
+    const parsed = AgentConfigSchema.safeParse(updatedRawConfig);
+    if (!parsed.success) {
+      const result = fail(zodToIssues(parsed.error, "error"));
+      throw new DextoValidationError(result.issues);
+    }
+    for (const [key, value] of Object.entries(updates)) {
+      doc.set(key, value);
+    }
+    const yamlContent = String(doc);
+    const tmpPath = `${path}.tmp`;
+    await fs.writeFile(tmpPath, yamlContent, "utf-8");
+    await fs.rename(tmpPath, path);
+    const reloadResult = await this.reloadConfig();
+    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 = getAgentRegistry();
-    try {
-      const agentPath = await agentRegistry.resolveAgent(agentName, true, true);
-      const config = await loadAgentConfig(agentPath);
-      logger.info(`Creating agent: ${agentName}`);
-      const newAgent = new DextoAgent(config, agentPath);
-      logger.info(`Successfully created agent: ${agentName}`);
-      return newAgent;
-    } catch (error) {
-      logger.error(
-        `Failed to create agent '${agentName}': ${error instanceof Error ? error.message : String(error)}`
-      );
-      throw 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