@dexto/core 1.1.10 → 1.1.11

package/dist/Dexto.cjs

@@ -0,0 +1,261 @@
+"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 Dexto_exports = {};
+__export(Dexto_exports, {
+  Dexto: () => Dexto,
+  getDexto: () => getDexto
+});
+module.exports = __toCommonJS(Dexto_exports);
+var import_logger = require("./logger/index.js");
+var import_registry = require("./agent/registry/registry.js");
+var import_loader = require("./config/loader.js");
+var import_errors = require("./agent/errors.js");
+var import_DextoAgent = require("./agent/DextoAgent.js");
+var import_types = require("./agent/registry/types.js");
+let cachedDexto = null;
+class Dexto {
+  /**
+   * 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 Dexto.listAgents();
+   * console.log(agents.installed); // ['default', 'my-custom-agent']
+   * console.log(agents.available); // [{ name: 'productivity', description: '...', ... }]
+   * console.log(agents.current?.name); // 'default'
+   * ```
+   */
+  static async listAgents() {
+    const agentRegistry = (0, import_registry.getAgentRegistry)();
+    const availableMap = agentRegistry.getAvailableAgents();
+    const installedNames = await agentRegistry.getInstalledAgents();
+    const installed = await Promise.all(
+      installedNames.map(async (agentId) => {
+        const registryEntry = availableMap[agentId];
+        if (registryEntry) {
+          return {
+            id: agentId,
+            name: registryEntry.name,
+            description: registryEntry.description,
+            author: registryEntry.author,
+            tags: registryEntry.tags,
+            type: registryEntry.type
+          };
+        } else {
+          try {
+            const config = await (0, import_loader.loadAgentConfig)(agentId);
+            const author = config.agentCard?.provider?.organization;
+            const result = {
+              id: agentId,
+              name: typeof config.agentCard?.name === "string" ? config.agentCard.name : (0, import_types.deriveDisplayName)(agentId),
+              description: config.agentCard?.description || "Local agent",
+              tags: [],
+              type: "custom"
+              // Assume custom if not in registry
+            };
+            if (author) {
+              result.author = author;
+            }
+            return result;
+          } catch {
+            const result = {
+              id: agentId,
+              name: (0, import_types.deriveDisplayName)(agentId),
+              description: "Local agent (config unavailable)",
+              tags: [],
+              type: "custom"
+              // Assume custom if not in registry
+            };
+            return result;
+          }
+        }
+      })
+    );
+    const available = Object.entries(availableMap).filter(([agentId]) => !installedNames.includes(agentId)).map(([agentId, entry]) => ({
+      id: agentId,
+      name: entry.name,
+      description: entry.description,
+      author: entry.author,
+      tags: entry.tags,
+      type: entry.type
+    }));
+    return {
+      installed,
+      available,
+      current: { id: null, 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 Dexto.installAgent('productivity');
+   * console.log('Productivity agent installed successfully');
+   * ```
+   */
+  static async installAgent(agentName) {
+    const agentRegistry = (0, import_registry.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) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      import_logger.logger.error(`Failed to install agent ${agentName}: ${errorMessage}`);
+      throw import_errors.AgentError.apiValidationError(
+        `Installation failed for agent '${agentName}'`,
+        error
+      );
+    }
+  }
+  /**
+   * Installs a custom agent from a local file or directory path.
+   * Creates a new custom agent entry in the user registry with provided metadata.
+   *
+   * @param agentName The name to use for the custom agent (must be unique)
+   * @param sourcePath Absolute path to the agent YAML file or directory
+   * @param metadata Agent metadata (description, author, tags, main config file)
+   * @param injectPreferences Whether to inject global preferences into agent config (default: true)
+   * @returns Promise resolving to the path of the installed main config file
+   *
+   * @throws {AgentError} When name conflicts with existing agent or installation fails
+   *
+   * @example
+   * ```typescript
+   * await Dexto.installCustomAgent('my-coding-agent', '/path/to/agent.yml', {
+   *   description: 'Custom coding assistant',
+   *   author: 'John Doe',
+   *   tags: ['coding', 'custom']
+   * });
+   * console.log('Custom agent installed successfully');
+   * ```
+   */
+  static async installCustomAgent(agentName, sourcePath, metadata, injectPreferences = true) {
+    const agentRegistry = (0, import_registry.getAgentRegistry)();
+    try {
+      const mainConfigPath = await agentRegistry.installCustomAgentFromPath(
+        agentName,
+        sourcePath,
+        metadata,
+        injectPreferences
+      );
+      import_logger.logger.info(`Successfully installed custom agent: ${agentName}`);
+      return mainConfigPath;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      import_logger.logger.error(`Failed to install custom agent ${agentName}: ${errorMessage}`);
+      throw import_errors.AgentError.apiValidationError(
+        `Installation failed for custom agent '${agentName}'`,
+        error
+      );
+    }
+  }
+  /**
+   * Uninstalls an agent by removing its directory from disk.
+   * For custom agents: also removes from user registry.
+   * For builtin agents: only removes from disk (can be reinstalled).
+   *
+   * @param agentName The name of the agent to uninstall
+   * @param force Whether to force uninstall even if agent is protected (default: false)
+   * @returns Promise that resolves when uninstallation is complete
+   *
+   * @throws {AgentError} When agent is not installed or uninstallation fails
+   *
+   * @example
+   * ```typescript
+   * await Dexto.uninstallAgent('my-custom-agent');
+   * console.log('Agent uninstalled successfully');
+   * ```
+   */
+  static async uninstallAgent(agentName, force = false) {
+    const agentRegistry = (0, import_registry.getAgentRegistry)();
+    try {
+      await agentRegistry.uninstallAgent(agentName, force);
+      import_logger.logger.info(`Successfully uninstalled agent: ${agentName}`);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      import_logger.logger.error(`Failed to uninstall agent ${agentName}: ${errorMessage}`);
+      throw import_errors.AgentError.apiValidationError(
+        `Uninstallation 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 any existing agent instances.
+   * 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 dexto = new Dexto();
+   * const newAgent = await dexto.createAgent('productivity');
+   * await newAgent.start();
+   * ```
+   */
+  async createAgent(agentName) {
+    const agentRegistry = (0, import_registry.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 import_DextoAgent.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);
+    }
+  }
+}
+function getDexto() {
+  if (cachedDexto === null) {
+    cachedDexto = new Dexto();
+  }
+  return cachedDexto;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Dexto,
+  getDexto
+});

package/dist/Dexto.d.ts

@@ -0,0 +1,212 @@
+import { DextoAgent } from './agent/DextoAgent.js';
+/**
+ * Dexto - Main orchestrator class for managing Dexto agents (Singleton)
+ *
+ * This class serves as the primary entry point for agent lifecycle management,
+ * including installation, creation, and coordination of multiple agent instances.
+ *
+ * ## Current Features
+ * - **Agent Discovery**: List available and installed agents
+ * - **Agent Installation**: Install agents from registry or custom sources
+ * - **Agent Creation**: Factory methods for creating agent instances
+ * - **Agent Removal**: Uninstall agents from the system
+ *
+ * ## Future Orchestration Features (Planned)
+ * The following features are planned for future releases to enable advanced
+ * multi-agent orchestration and coordination:
+ *
+ * ### Multi-Agent Instance Management
+ * - Manage multiple concurrent agent instances with different configurations
+ * - Track agent lifecycle states (created, started, stopped, errored)
+ * - Provide APIs for listing and querying active agent instances
+ *
+ * ### Agent Switching & Routing
+ * - Switch between active agents dynamically during runtime
+ * - Route requests to appropriate agents based on context or capabilities
+ * - Maintain conversation continuity across agent switches
+ *
+ * ### Cross-Agent Coordination
+ * - Enable agents to collaborate on complex tasks requiring specialized skills
+ * - Delegate sub-tasks from one agent to another
+ * - Aggregate results from multiple agents working in parallel
+ *
+ * ### Global Event Bus
+ * - Centralized event bus for cross-agent communication
+ * - Subscribe to events from any managed agent instance
+ * - Coordinate state synchronization across agent boundaries
+ *
+ * ### Resource Management
+ * - Shared resource pools (API keys, rate limits, connection pools)
+ * - Resource allocation and quota management across agents
+ * - Prevent resource conflicts between concurrent agent instances
+ *
+ * ### Agent Persistence & Sessions
+ * - Save and restore agent instances with their full state
+ * - Support for long-running agent workflows that span multiple sessions
+ * - Checkpoint and resume capabilities for complex agent operations
+ *
+ * @example
+ * ```typescript
+ * // List available agents (static)
+ * const agents = await Dexto.listAgents();
+ * console.log(agents.installed, agents.available);
+ *
+ * // Install agent (static)
+ * await Dexto.installAgent('productivity');
+ *
+ * // Create orchestrator for agent operations
+ * const dexto = new Dexto();
+ * const agent = await dexto.createAgent('productivity');
+ * await agent.start();
+ *
+ * // Install custom agent (static)
+ * await Dexto.installCustomAgent('my-agent', '/path/to/config.yml', {
+ *   description: 'My custom agent',
+ *   author: 'John Doe',
+ *   tags: ['custom', 'specialized']
+ * });
+ * ```
+ */
+export declare class Dexto {
+    /**
+     * 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 Dexto.listAgents();
+     * console.log(agents.installed); // ['default', 'my-custom-agent']
+     * console.log(agents.available); // [{ name: 'productivity', description: '...', ... }]
+     * console.log(agents.current?.name); // 'default'
+     * ```
+     */
+    static listAgents(): Promise<{
+        installed: Array<{
+            id: string;
+            name: string;
+            description: string;
+            author?: string;
+            tags?: string[];
+            type: 'builtin' | 'custom';
+        }>;
+        available: Array<{
+            id: string;
+            name: string;
+            description: string;
+            author?: string;
+            tags?: string[];
+            type: 'builtin' | 'custom';
+        }>;
+        current?: {
+            id?: string | null;
+            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 Dexto.installAgent('productivity');
+     * console.log('Productivity agent installed successfully');
+     * ```
+     */
+    static installAgent(agentName: string): Promise<void>;
+    /**
+     * Installs a custom agent from a local file or directory path.
+     * Creates a new custom agent entry in the user registry with provided metadata.
+     *
+     * @param agentName The name to use for the custom agent (must be unique)
+     * @param sourcePath Absolute path to the agent YAML file or directory
+     * @param metadata Agent metadata (description, author, tags, main config file)
+     * @param injectPreferences Whether to inject global preferences into agent config (default: true)
+     * @returns Promise resolving to the path of the installed main config file
+     *
+     * @throws {AgentError} When name conflicts with existing agent or installation fails
+     *
+     * @example
+     * ```typescript
+     * await Dexto.installCustomAgent('my-coding-agent', '/path/to/agent.yml', {
+     *   description: 'Custom coding assistant',
+     *   author: 'John Doe',
+     *   tags: ['coding', 'custom']
+     * });
+     * console.log('Custom agent installed successfully');
+     * ```
+     */
+    static installCustomAgent(agentName: string, sourcePath: string, metadata: {
+        name?: string;
+        description: string;
+        author: string;
+        tags: string[];
+        main?: string;
+    }, injectPreferences?: boolean): Promise<string>;
+    /**
+     * Uninstalls an agent by removing its directory from disk.
+     * For custom agents: also removes from user registry.
+     * For builtin agents: only removes from disk (can be reinstalled).
+     *
+     * @param agentName The name of the agent to uninstall
+     * @param force Whether to force uninstall even if agent is protected (default: false)
+     * @returns Promise that resolves when uninstallation is complete
+     *
+     * @throws {AgentError} When agent is not installed or uninstallation fails
+     *
+     * @example
+     * ```typescript
+     * await Dexto.uninstallAgent('my-custom-agent');
+     * console.log('Agent uninstalled successfully');
+     * ```
+     */
+    static uninstallAgent(agentName: string, force?: boolean): 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 any existing agent instances.
+     * 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 dexto = new Dexto();
+     * const newAgent = await dexto.createAgent('productivity');
+     * await newAgent.start();
+     * ```
+     */
+    createAgent(agentName: string): Promise<DextoAgent>;
+}
+/**
+ * Get the singleton Dexto orchestrator instance
+ *
+ * @returns The global Dexto orchestrator instance
+ *
+ * @example
+ * ```typescript
+ * import { getDexto, Dexto } from '@dexto/core';
+ *
+ * // Use static methods for registry operations
+ * const agents = await Dexto.listAgents();
+ * await Dexto.installAgent('productivity');
+ *
+ * // Use instance for agent creation
+ * const dexto = getDexto();
+ * const agent = await dexto.createAgent('productivity');
+ * ```
+ */
+export declare function getDexto(): Dexto;
+//# sourceMappingURL=Dexto.d.ts.map

package/dist/Dexto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Dexto.d.ts","sourceRoot":"","sources":["../src/Dexto.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAMnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH,qBAAa,KAAK;IACd;;;;;;;;;;;;;;OAcG;WACiB,UAAU,IAAI,OAAO,CAAC;QACtC,SAAS,EAAE,KAAK,CAAC;YACb,EAAE,EAAE,MAAM,CAAC;YACX,IAAI,EAAE,MAAM,CAAC;YACb,WAAW,EAAE,MAAM,CAAC;YACpB,MAAM,CAAC,EAAE,MAAM,CAAC;YAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;YAChB,IAAI,EAAE,SAAS,GAAG,QAAQ,CAAC;SAC9B,CAAC,CAAC;QACH,SAAS,EAAE,KAAK,CAAC;YACb,EAAE,EAAE,MAAM,CAAC;YACX,IAAI,EAAE,MAAM,CAAC;YACb,WAAW,EAAE,MAAM,CAAC;YACpB,MAAM,CAAC,EAAE,MAAM,CAAC;YAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;YAChB,IAAI,EAAE,SAAS,GAAG,QAAQ,CAAC;SAC9B,CAAC,CAAC;QACH,OAAO,CAAC,EAAE;YAAE,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;SAAE,CAAC;KAC1D,CAAC;IAoFF;;;;;;;;;;;;;;OAcG;WACiB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBlE;;;;;;;;;;;;;;;;;;;;;OAqBG;WACiB,kBAAkB,CAClC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE;QACN,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,EAAE,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;KACjB,EACD,iBAAiB,GAAE,OAAc,GAClC,OAAO,CAAC,MAAM,CAAC;IAsBlB;;;;;;;;;;;;;;;;OAgBG;WACiB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,GAAE,OAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB5F;;;;;;;;;;;;;;;;;;;OAmBG;IACU,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;CAyBnE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,IAAI,KAAK,CAKhC"}