@dexto/core 1.1.7 → 1.1.8

package/dist/agent/DextoAgent.cjs

@@ -36,6 +36,8 @@ 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");
 const requiredServices = [
   "mcpManager",
   "toolManager",
@@ -781,6 +783,138 @@ 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'
+   * ```
+   */
+  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
+    };
+  }
+  /**
+   * Installs an agent from the registry.
+   * Downloads and sets up the specified agent, making it available for use.
+   *
+   * @param agentName The name of the agent to install from the registry
+   * @returns Promise that resolves when installation is complete
+   *
+   * @throws {AgentError} When agent is not found in registry or installation fails
+   *
+   * @example
+   * ```typescript
+   * await agent.installAgent('productivity');
+   * console.log('Productivity agent installed successfully');
+   * ```
+   */
+  async installAgent(agentName) {
+    const agentRegistry = (0, import_registry2.getAgentRegistry)();
+    if (!agentRegistry.hasAgent(agentName)) {
+      throw import_errors.AgentError.apiValidationError(`Agent '${agentName}' not found in registry`);
+    }
+    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
+      );
+    }
+  }
+  /**
+   * 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
+   *
+   * @example
+   * ```typescript
+   * const newAgent = await DextoAgent.createAgent('productivity');
+   * await newAgent.start();
+   * ```
+   */
+  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);
+    }
+  }
   // Future methods could encapsulate more complex agent behaviors:
   // - Multi-step task execution with progress tracking
   // - Memory and context management across sessions

package/dist/agent/DextoAgent.d.cts

@@ -468,6 +468,74 @@ declare class DextoAgent {
      * @returns The effective configuration object
      */
     getEffectiveConfig(sessionId?: string): Readonly<AgentConfig>;
+    /**
+     * 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'
+     * ```
+     */
+    listAgents(): Promise<{
+        installed: Array<{
+            name: string;
+            description: string;
+            author?: string;
+            tags?: string[];
+        }>;
+        available: Array<{
+            name: string;
+            description: string;
+            author?: string;
+            tags?: string[];
+        }>;
+        current?: {
+            name?: string | null;
+        };
+    }>;
+    /**
+     * Installs an agent from the registry.
+     * Downloads and sets up the specified agent, making it available for use.
+     *
+     * @param agentName The name of the agent to install from the registry
+     * @returns Promise that resolves when installation is complete
+     *
+     * @throws {AgentError} When agent is not found in registry or installation fails
+     *
+     * @example
+     * ```typescript
+     * await agent.installAgent('productivity');
+     * console.log('Productivity agent installed successfully');
+     * ```
+     */
+    installAgent(agentName: string): Promise<void>;
+    /**
+     * 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
+     *
+     * @example
+     * ```typescript
+     * const newAgent = await DextoAgent.createAgent('productivity');
+     * await newAgent.start();
+     * ```
+     */
+    static createAgent(agentName: string): Promise<DextoAgent>;
 }
 
 export { DextoAgent };

package/dist/agent/DextoAgent.d.ts

@@ -468,6 +468,74 @@ declare class DextoAgent {
      * @returns The effective configuration object
      */
     getEffectiveConfig(sessionId?: string): Readonly<AgentConfig>;
+    /**
+     * 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'
+     * ```
+     */
+    listAgents(): Promise<{
+        installed: Array<{
+            name: string;
+            description: string;
+            author?: string;
+            tags?: string[];
+        }>;
+        available: Array<{
+            name: string;
+            description: string;
+            author?: string;
+            tags?: string[];
+        }>;
+        current?: {
+            name?: string | null;
+        };
+    }>;
+    /**
+     * Installs an agent from the registry.
+     * Downloads and sets up the specified agent, making it available for use.
+     *
+     * @param agentName The name of the agent to install from the registry
+     * @returns Promise that resolves when installation is complete
+     *
+     * @throws {AgentError} When agent is not found in registry or installation fails
+     *
+     * @example
+     * ```typescript
+     * await agent.installAgent('productivity');
+     * console.log('Productivity agent installed successfully');
+     * ```
+     */
+    installAgent(agentName: string): Promise<void>;
+    /**
+     * 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
+     *
+     * @example
+     * ```typescript
+     * const newAgent = await DextoAgent.createAgent('productivity');
+     * await newAgent.start();
+     * ```
+     */
+    static createAgent(agentName: string): Promise<DextoAgent>;
 }
 
 export { DextoAgent };

package/dist/agent/DextoAgent.js

@@ -18,6 +18,8 @@ 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";
 const requiredServices = [
   "mcpManager",
   "toolManager",
@@ -763,6 +765,138 @@ 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'
+   * ```
+   */
+  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
+    };
+  }
+  /**
+   * Installs an agent from the registry.
+   * Downloads and sets up the specified agent, making it available for use.
+   *
+   * @param agentName The name of the agent to install from the registry
+   * @returns Promise that resolves when installation is complete
+   *
+   * @throws {AgentError} When agent is not found in registry or installation fails
+   *
+   * @example
+   * ```typescript
+   * await agent.installAgent('productivity');
+   * console.log('Productivity agent installed successfully');
+   * ```
+   */
+  async installAgent(agentName) {
+    const agentRegistry = getAgentRegistry();
+    if (!agentRegistry.hasAgent(agentName)) {
+      throw AgentError.apiValidationError(`Agent '${agentName}' not found in registry`);
+    }
+    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
+      );
+    }
+  }
+  /**
+   * 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
+   *
+   * @example
+   * ```typescript
+   * const newAgent = await DextoAgent.createAgent('productivity');
+   * await newAgent.start();
+   * ```
+   */
+  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);
+    }
+  }
   // Future methods could encapsulate more complex agent behaviors:
   // - Multi-step task execution with progress tracking
   // - Memory and context management across sessions

package/dist/agent/errors.cjs

@@ -77,6 +77,19 @@ class AgentError {
       "Check logs for initialization errors"
     );
   }
+  /**
+   * API validation error
+   */
+  static apiValidationError(message, details) {
+    return new import_DextoRuntimeError.DextoRuntimeError(
+      import_error_codes.AgentErrorCode.API_VALIDATION_ERROR,
+      import_types.ErrorScope.AGENT,
+      import_types.ErrorType.USER,
+      message,
+      details,
+      "Check the request parameters and try again"
+    );
+  }
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/agent/errors.d.cts

@@ -35,6 +35,10 @@ declare class AgentError {
      * Agent initialization failed
      */
     static initializationFailed(reason: string, details?: unknown): DextoRuntimeError<unknown>;
+    /**
+     * API validation error
+     */
+    static apiValidationError(message: string, details?: unknown): DextoRuntimeError<unknown>;
 }
 
 export { AgentError };

package/dist/agent/errors.d.ts

@@ -35,6 +35,10 @@ declare class AgentError {
      * Agent initialization failed
      */
     static initializationFailed(reason: string, details?: unknown): DextoRuntimeError<unknown>;
+    /**
+     * API validation error
+     */
+    static apiValidationError(message: string, details?: unknown): DextoRuntimeError<unknown>;
 }
 
 export { AgentError };

package/dist/agent/errors.js

@@ -54,6 +54,19 @@ class AgentError {
       "Check logs for initialization errors"
     );
   }
+  /**
+   * API validation error
+   */
+  static apiValidationError(message, details) {
+    return new DextoRuntimeError(
+      AgentErrorCode.API_VALIDATION_ERROR,
+      ErrorScope.AGENT,
+      ErrorType.USER,
+      message,
+      details,
+      "Check the request parameters and try again"
+    );
+  }
 }
 export {
   AgentError

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dexto/core",
-  "version": "1.1.7",
+  "version": "1.1.8",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",