@dexto/agent-management 1.3.0 → 1.4.0

package/dist/AgentOrchestrator.d.ts

@@ -1,191 +0,0 @@
-import { DextoAgent } from '@dexto/core';
-/**
- * AgentOrchestrator - Main orchestrator class for managing Dexto agents
- *
- * 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
- * const agents = await AgentOrchestrator.listAgents();
- * console.log(agents.installed, agents.available);
- *
- * // Install agent
- * await AgentOrchestrator.installAgent('productivity');
- *
- * // Create and start agent
- * const agent = await AgentOrchestrator.createAgent('productivity');
- * await agent.start();
- *
- * // Install custom agent
- * await AgentOrchestrator.installCustomAgent('my-agent', '/path/to/config.yml', {
- *   description: 'My custom agent',
- *   author: 'John Doe',
- *   tags: ['custom', 'specialized']
- * });
- * ```
- */
-export declare class AgentOrchestrator {
-    /**
-     * 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 AgentOrchestrator.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 AgentOrchestrator.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 AgentOrchestrator.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 AgentOrchestrator.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 newAgent = await AgentOrchestrator.createAgent('productivity');
-     * await newAgent.start();
-     * ```
-     */
-    static createAgent(agentName: string): Promise<DextoAgent>;
-}
-//# sourceMappingURL=AgentOrchestrator.d.ts.map

package/dist/AgentOrchestrator.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"AgentOrchestrator.d.ts","sourceRoot":"","sources":["../src/AgentOrchestrator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,UAAU,EAAwB,MAAM,aAAa,CAAC;AAOnF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH,qBAAa,iBAAiB;IAC1B;;;;;;;;;;;;;;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;;;;;;;;;;;;;;;;;;OAkBG;WACiB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;CA2C1E"}

package/dist/AgentOrchestrator.js

@@ -1,239 +0,0 @@
-import { logger, AgentError, DextoAgent, DextoValidationError } from "@dexto/core";
-import { loadAgentConfig, enrichAgentConfig } from "./config/index.js";
-import { getAgentRegistry } from "./registry/registry.js";
-import { deriveDisplayName } from "./registry/types.js";
-import { ZodError } from "zod";
-import { zodToIssues } from "@dexto/core";
-class AgentOrchestrator {
-  /**
-   * 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 AgentOrchestrator.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 = 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 loadAgentConfig(agentId);
-            const author = config.agentCard?.provider?.organization;
-            const result = {
-              id: agentId,
-              name: typeof config.agentCard?.name === "string" ? config.agentCard.name : 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: 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 AgentOrchestrator.installAgent('productivity');
-   * console.log('Productivity agent installed successfully');
-   * ```
-   */
-  static 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) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      logger.error(`Failed to install agent ${agentName}: ${errorMessage}`);
-      throw 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 AgentOrchestrator.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 = getAgentRegistry();
-    try {
-      const mainConfigPath = await agentRegistry.installCustomAgentFromPath(
-        agentName,
-        sourcePath,
-        metadata,
-        injectPreferences
-      );
-      logger.info(`Successfully installed custom agent: ${agentName}`);
-      return mainConfigPath;
-    } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      logger.error(`Failed to install custom agent ${agentName}: ${errorMessage}`);
-      throw 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 AgentOrchestrator.uninstallAgent('my-custom-agent');
-   * console.log('Agent uninstalled successfully');
-   * ```
-   */
-  static async uninstallAgent(agentName, force = false) {
-    const agentRegistry = getAgentRegistry();
-    try {
-      await agentRegistry.uninstallAgent(agentName, force);
-      logger.info(`Successfully uninstalled agent: ${agentName}`);
-    } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      logger.error(`Failed to uninstall agent ${agentName}: ${errorMessage}`);
-      throw 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 newAgent = await AgentOrchestrator.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);
-      const enrichedConfig = enrichAgentConfig(config, agentPath);
-      logger.info(`Creating agent: ${agentName}`);
-      const newAgent = new DextoAgent(enrichedConfig, agentPath);
-      logger.info(`Successfully created agent: ${agentName}`);
-      return newAgent;
-    } catch (error) {
-      if (error instanceof ZodError) {
-        const issues = zodToIssues(error, "error");
-        const formatted = issues.map((issue) => {
-          const path = Array.isArray(issue.path) ? issue.path.join(".") : String(issue.path);
-          return `${path}: ${issue.message}`;
-        });
-        const message = `Configuration validation failed for agent '${agentName}':
-${formatted.join("\n")}`;
-        logger.error(message);
-        throw new DextoValidationError(issues);
-      }
-      logger.error(
-        `Failed to create agent '${agentName}': ${error instanceof Error ? error.message : String(error)}`
-      );
-      throw AgentError.apiValidationError(`Failed to create agent '${agentName}'`, error);
-    }
-  }
-}
-export {
-  AgentOrchestrator
-};