@dexto/agent-management 1.3.0 → 1.5.0

package/dist/AgentManager.d.ts

@@ -0,0 +1,191 @@
+/**
+ * AgentManager - Registry-based agent lifecycle management
+ *
+ * USE THIS WHEN: You have a registry.json file with multiple predefined agents
+ * and need discovery/selection capabilities (listAgents, hasAgent, createAgent by ID).
+ *
+ * Examples:
+ * - CLI tools with multiple agent options
+ * - Projects with several predefined agents users can choose from
+ *
+ * FOR INLINE/DYNAMIC CONFIGS: Use `AgentFactory.createAgent(config)` instead.
+ * This is better when configs come from a database, API, or are constructed
+ * programmatically without a registry file.
+ *
+ * @see AgentFactory.createAgent() for inline config creation
+ * @see https://docs.dexto.ai/api/sdk/agent-manager for full documentation
+ */
+import { DextoAgent } from '@dexto/core';
+import { z } from 'zod';
+/**
+ * Agent metadata - describes an agent in the registry
+ */
+export interface AgentMetadata {
+    id: string;
+    name: string;
+    description: string;
+    author?: string | undefined;
+    tags?: string[] | undefined;
+}
+/**
+ * Registry file schema
+ */
+declare const RegistrySchema: z.ZodObject<{
+    agents: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodString;
+        configPath: z.ZodString;
+        author: z.ZodOptional<z.ZodString>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        name: string;
+        description: string;
+        configPath: string;
+        author?: string | undefined;
+        tags?: string[] | undefined;
+    }, {
+        id: string;
+        name: string;
+        description: string;
+        configPath: string;
+        author?: string | undefined;
+        tags?: string[] | undefined;
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    agents: {
+        id: string;
+        name: string;
+        description: string;
+        configPath: string;
+        author?: string | undefined;
+        tags?: string[] | undefined;
+    }[];
+}, {
+    agents: {
+        id: string;
+        name: string;
+        description: string;
+        configPath: string;
+        author?: string | undefined;
+        tags?: string[] | undefined;
+    }[];
+}>;
+type Registry = z.output<typeof RegistrySchema>;
+/**
+ * AgentManager - Simple registry-based agent lifecycle management
+ *
+ * Provides a clean API for loading agent configurations from a registry file
+ * and creating agent instances. The registry is a JSON file that lists available
+ * agents and their config file paths.
+ *
+ * @example
+ * ```typescript
+ * // Point to your registry
+ * const manager = new AgentManager('./agents/registry.json');
+ *
+ * // List available agents
+ * const agents = manager.listAgents();
+ * console.log(agents); // [{ id: 'coding-agent', name: '...', ... }]
+ *
+ * // Load an agent instance
+ * const agent = await manager.loadAgent('coding-agent');
+ * await agent.start();
+ * ```
+ */
+export declare class AgentManager {
+    private registry;
+    private registryPath;
+    private basePath;
+    /**
+     * Create a new AgentManager
+     *
+     * @param registryPath Absolute or relative path to registry.json file
+     *
+     * @example
+     * ```typescript
+     * // Project-local registry
+     * const manager = new AgentManager('./agents/registry.json');
+     *
+     * // Absolute path
+     * const manager = new AgentManager('/path/to/registry.json');
+     * ```
+     */
+    constructor(registryPath: string);
+    /**
+     * Load registry from file (lazy loaded, cached)
+     *
+     * Call this before using sync methods like `listAgents()` or `hasAgent()`.
+     * Alternatively, calling `loadAgent()` will automatically load the registry.
+     *
+     * @returns The loaded registry
+     *
+     * @example
+     * ```typescript
+     * const manager = new AgentManager('./registry.json');
+     * await manager.loadRegistry();
+     *
+     * // Now sync methods work
+     * const agents = manager.listAgents();
+     * ```
+     */
+    loadRegistry(): Promise<Registry>;
+    /**
+     * List all agents in the registry
+     *
+     * @returns Array of agent metadata
+     *
+     * @example
+     * ```typescript
+     * const manager = new AgentManager('./registry.json');
+     * const agents = manager.listAgents();
+     * console.log(agents);
+     * // [
+     * //   { id: 'coding-agent', name: 'Coding Assistant', description: '...', tags: ['coding'] },
+     * //   { id: 'support-agent', name: 'Support Assistant', description: '...', tags: ['support'] }
+     * // ]
+     * ```
+     */
+    listAgents(): AgentMetadata[];
+    /**
+     * Load a DextoAgent instance from registry
+     *
+     * @param id Agent ID from registry
+     * @returns Promise resolving to DextoAgent instance (not started)
+     *
+     * @throws {DextoRuntimeError} If agent not found or config loading fails
+     * @throws {DextoValidationError} If agent config validation fails
+     *
+     * @example
+     * ```typescript
+     * const manager = new AgentManager('./registry.json');
+     * const agent = await manager.loadAgent('coding-agent');
+     * await agent.start();
+     *
+     * // Use the agent
+     * const session = await agent.createSession();
+     * const response = await agent.generate('Write a function', session.id);
+     * ```
+     */
+    loadAgent(id: string): Promise<DextoAgent>;
+    /**
+     * Check if an agent exists in the registry
+     *
+     * @param id Agent ID to check
+     * @returns True if agent exists
+     *
+     * @example
+     * ```typescript
+     * const manager = new AgentManager('./registry.json');
+     * await manager.loadRegistry();
+     *
+     * if (manager.hasAgent('coding-agent')) {
+     *   const agent = await manager.loadAgent('coding-agent');
+     * }
+     * ```
+     */
+    hasAgent(id: string): boolean;
+}
+export {};
+//# sourceMappingURL=AgentManager.d.ts.map

package/dist/AgentManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentManager.d.ts","sourceRoot":"","sources":["../src/AgentManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,EAAU,UAAU,EAAqC,MAAM,aAAa,CAAC;AAGpF,OAAO,EAAE,CAAC,EAAY,MAAM,KAAK,CAAC;AAElC;;GAEG;AACH,MAAM,WAAW,aAAa;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;CAC/B;AAED;;GAEG;AACH,QAAA,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAeP,CAAC;AAEd,KAAK,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,YAAY;IACrB,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAS;IAEzB;;;;;;;;;;;;;OAaG;gBACS,YAAY,EAAE,MAAM;IAKhC;;;;;;;;;;;;;;;;OAgBG;IACG,YAAY,IAAI,OAAO,CAAC,QAAQ,CAAC;IA8BvC;;;;;;;;;;;;;;;OAeG;IACH,UAAU,IAAI,aAAa,EAAE;IAiB7B;;;;;;;;;;;;;;;;;;;OAmBG;IACG,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAuChD;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;CAUhC"}

package/dist/AgentManager.js

@@ -0,0 +1,192 @@
+import { promises as fs } from "fs";
+import path from "path";
+import { logger, DextoAgent, DextoValidationError, zodToIssues } from "@dexto/core";
+import { loadAgentConfig, enrichAgentConfig } from "./config/index.js";
+import { RegistryError } from "./registry/errors.js";
+import { z, ZodError } from "zod";
+const RegistrySchema = z.object({
+  agents: z.array(
+    z.object({
+      id: z.string(),
+      name: z.string(),
+      description: z.string(),
+      configPath: z.string(),
+      author: z.string().optional(),
+      tags: z.array(z.string()).optional()
+    }).strict()
+  )
+}).strict();
+class AgentManager {
+  registry = null;
+  registryPath;
+  basePath;
+  /**
+   * Create a new AgentManager
+   *
+   * @param registryPath Absolute or relative path to registry.json file
+   *
+   * @example
+   * ```typescript
+   * // Project-local registry
+   * const manager = new AgentManager('./agents/registry.json');
+   *
+   * // Absolute path
+   * const manager = new AgentManager('/path/to/registry.json');
+   * ```
+   */
+  constructor(registryPath) {
+    this.registryPath = path.resolve(registryPath);
+    this.basePath = path.dirname(this.registryPath);
+  }
+  /**
+   * Load registry from file (lazy loaded, cached)
+   *
+   * Call this before using sync methods like `listAgents()` or `hasAgent()`.
+   * Alternatively, calling `loadAgent()` will automatically load the registry.
+   *
+   * @returns The loaded registry
+   *
+   * @example
+   * ```typescript
+   * const manager = new AgentManager('./registry.json');
+   * await manager.loadRegistry();
+   *
+   * // Now sync methods work
+   * const agents = manager.listAgents();
+   * ```
+   */
+  async loadRegistry() {
+    if (this.registry) {
+      return this.registry;
+    }
+    try {
+      const content = await fs.readFile(this.registryPath, "utf-8");
+      const parsed = JSON.parse(content);
+      this.registry = RegistrySchema.parse(parsed);
+      logger.debug(
+        `Loaded registry from ${this.registryPath}: ${this.registry.agents.length} agents`
+      );
+      return this.registry;
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        throw RegistryError.registryNotFound(this.registryPath, "File does not exist");
+      }
+      if (error instanceof ZodError) {
+        throw RegistryError.registryParseError(
+          this.registryPath,
+          `Invalid registry schema: ${error.errors.map((e) => e.message).join(", ")}`
+        );
+      }
+      throw RegistryError.registryParseError(
+        this.registryPath,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
+  /**
+   * List all agents in the registry
+   *
+   * @returns Array of agent metadata
+   *
+   * @example
+   * ```typescript
+   * const manager = new AgentManager('./registry.json');
+   * const agents = manager.listAgents();
+   * console.log(agents);
+   * // [
+   * //   { id: 'coding-agent', name: 'Coding Assistant', description: '...', tags: ['coding'] },
+   * //   { id: 'support-agent', name: 'Support Assistant', description: '...', tags: ['support'] }
+   * // ]
+   * ```
+   */
+  listAgents() {
+    if (!this.registry) {
+      throw RegistryError.registryNotFound(
+        this.registryPath,
+        "Registry not loaded. Call loadRegistry() first or use async methods."
+      );
+    }
+    return this.registry.agents.map((entry) => ({
+      id: entry.id,
+      name: entry.name,
+      description: entry.description,
+      author: entry.author,
+      tags: entry.tags
+    }));
+  }
+  /**
+   * Load a DextoAgent instance from registry
+   *
+   * @param id Agent ID from registry
+   * @returns Promise resolving to DextoAgent instance (not started)
+   *
+   * @throws {DextoRuntimeError} If agent not found or config loading fails
+   * @throws {DextoValidationError} If agent config validation fails
+   *
+   * @example
+   * ```typescript
+   * const manager = new AgentManager('./registry.json');
+   * const agent = await manager.loadAgent('coding-agent');
+   * await agent.start();
+   *
+   * // Use the agent
+   * const session = await agent.createSession();
+   * const response = await agent.generate('Write a function', session.id);
+   * ```
+   */
+  async loadAgent(id) {
+    const registry = await this.loadRegistry();
+    const entry = registry.agents.find((a) => a.id === id);
+    if (!entry) {
+      const available = registry.agents.map((a) => a.id);
+      throw RegistryError.agentNotFound(id, available);
+    }
+    const configPath = path.resolve(this.basePath, entry.configPath);
+    try {
+      const config = await loadAgentConfig(configPath);
+      const enrichedConfig = enrichAgentConfig(config, configPath);
+      logger.debug(`Loading agent: ${id} from ${configPath}`);
+      return new DextoAgent(enrichedConfig, configPath);
+    } catch (error) {
+      if (error instanceof ZodError) {
+        const issues = zodToIssues(error, "error");
+        throw new DextoValidationError(issues);
+      }
+      if (error instanceof Error && error.name.startsWith("Dexto")) {
+        throw error;
+      }
+      throw RegistryError.installationFailed(
+        id,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
+  /**
+   * Check if an agent exists in the registry
+   *
+   * @param id Agent ID to check
+   * @returns True if agent exists
+   *
+   * @example
+   * ```typescript
+   * const manager = new AgentManager('./registry.json');
+   * await manager.loadRegistry();
+   *
+   * if (manager.hasAgent('coding-agent')) {
+   *   const agent = await manager.loadAgent('coding-agent');
+   * }
+   * ```
+   */
+  hasAgent(id) {
+    if (!this.registry) {
+      throw RegistryError.registryNotFound(
+        this.registryPath,
+        "Registry not loaded. Call loadRegistry() first or use async methods."
+      );
+    }
+    return this.registry.agents.some((a) => a.id === id);
+  }
+}
+export {
+  AgentManager
+};

package/dist/config/config-enrichment.cjs

@@ -29,11 +29,14 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var config_enrichment_exports = {};
 __export(config_enrichment_exports, {
   deriveAgentId: () => deriveAgentId,
+  discoverCommandPrompts: () => import_discover_prompts2.discoverCommandPrompts,
   enrichAgentConfig: () => enrichAgentConfig
 });
 module.exports = __toCommonJS(config_enrichment_exports);
 var import_path = require("../utils/path.js");
 var path = __toESM(require("path"), 1);
+var import_discover_prompts = require("./discover-prompts.js");
+var import_discover_prompts2 = require("./discover-prompts.js");
 function deriveAgentId(config, configPath) {
   if (config.agentCard?.name) {
     const sanitizedName = config.agentCard.name.toLowerCase().replace(/[^a-z0-9-_]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
@@ -47,9 +50,11 @@ function deriveAgentId(config, configPath) {
       return basename;
     }
   }
-  return "default-agent";
+  return "coding-agent";
 }
-function enrichAgentConfig(config, configPath, isInteractiveCli = false) {
+function enrichAgentConfig(config, configPath, options = {}) {
+  const opts = typeof options === "boolean" ? { isInteractiveCli: options } : options;
+  const { isInteractiveCli = false, logLevel = "error" } = opts;
   const agentId = deriveAgentId(config, configPath);
   const logPath = (0, import_path.getDextoPath)("logs", `${agentId}.log`);
   const dbPath = (0, import_path.getDextoPath)("database", `${agentId}.db`);
@@ -79,7 +84,7 @@ function enrichAgentConfig(config, configPath, isInteractiveCli = false) {
       }
     ];
     enriched.logger = {
-      level: "info",
+      level: logLevel,
       transports
     };
   } else {
@@ -108,10 +113,25 @@ function enrichAgentConfig(config, configPath, isInteractiveCli = false) {
       };
     }
   }
+  const discoveredPrompts = (0, import_discover_prompts.discoverCommandPrompts)();
+  if (discoveredPrompts.length > 0) {
+    const existingPrompts = config.prompts ?? [];
+    const existingFilePaths = /* @__PURE__ */ new Set();
+    for (const prompt of existingPrompts) {
+      if (prompt.type === "file") {
+        existingFilePaths.add(path.resolve(prompt.file));
+      }
+    }
+    const filteredDiscovered = discoveredPrompts.filter(
+      (p) => !existingFilePaths.has(path.resolve(p.file))
+    );
+    enriched.prompts = [...existingPrompts, ...filteredDiscovered];
+  }
   return enriched;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   deriveAgentId,
+  discoverCommandPrompts,
   enrichAgentConfig
 });

package/dist/config/config-enrichment.d.ts

@@ -5,27 +5,42 @@
  * This layer runs before agent initialization and injects explicit paths
  * into the configuration, eliminating the need for core services to resolve paths themselves.
  *
+ * Also discovers command prompts from:
+ * - Local: <projectRoot>/commands/ (in dev mode or dexto-project context)
+ * - Global: ~/.dexto/commands/
+ *
  * Core services now require explicit paths - this enrichment layer provides them.
  */
 import type { AgentConfig } from '@dexto/core';
+export { discoverCommandPrompts } from './discover-prompts.js';
 /**
  * Derives an agent ID from config or file path for per-agent isolation.
- * Priority: agentCard.name > filename (without extension) > 'default-agent'
+ * Priority: agentCard.name > filename (without extension) > 'coding-agent'
  */
 export declare function deriveAgentId(config: AgentConfig, configPath?: string): string;
 /**
- * Enriches agent configuration with per-agent file paths.
+ * Options for enriching agent configuration
+ */
+export interface EnrichAgentConfigOptions {
+    /** Whether this is interactive CLI mode (affects logger transports - file only vs console+file) */
+    isInteractiveCli?: boolean;
+    /** Override log level (defaults to 'error' for SDK, CLI/server can override to 'info') */
+    logLevel?: 'error' | 'warn' | 'info' | 'debug';
+}
+/**
+ * Enriches agent configuration with per-agent file paths and discovered commands.
  * This function is called before creating the DextoAgent instance.
  *
  * Enrichment adds:
  * - File transport to logger config (per-agent log file)
  * - Full paths to storage config (SQLite database, blob storage)
  * - Backup path to filesystem config (per-agent backups)
+ * - Discovered command prompts from local/global commands/ directories
  *
  * @param config Agent configuration from YAML file + CLI overrides
  * @param configPath Path to the agent config file (used for agent ID derivation)
- * @param isInteractiveCli Whether this is interactive CLI mode (affects logger defaults) - defaults to false
- * @returns Enriched configuration with explicit per-agent paths
+ * @param options Enrichment options (isInteractiveCli, logLevel)
+ * @returns Enriched configuration with explicit per-agent paths and discovered prompts
  */
-export declare function enrichAgentConfig(config: AgentConfig, configPath?: string, isInteractiveCli?: boolean): AgentConfig;
+export declare function enrichAgentConfig(config: AgentConfig, configPath?: string, options?: EnrichAgentConfigOptions | boolean): AgentConfig;
 //# sourceMappingURL=config-enrichment.d.ts.map

package/dist/config/config-enrichment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config-enrichment.d.ts","sourceRoot":"","sources":["../../src/config/config-enrichment.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG/C;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAyB9E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC7B,MAAM,EAAE,WAAW,EACnB,UAAU,CAAC,EAAE,MAAM,EACnB,gBAAgB,GAAE,OAAe,GAClC,WAAW,CAkFb"}
+{"version":3,"file":"config-enrichment.d.ts","sourceRoot":"","sources":["../../src/config/config-enrichment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAK/C,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAE/D;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAyB9E;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACrC,mGAAmG;IACnG,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,0FAA0F;IAC1F,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;CAClD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC7B,MAAM,EAAE,WAAW,EACnB,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,GAAE,wBAAwB,GAAG,OAAY,GACjD,WAAW,CA+Gb"}

package/dist/config/config-enrichment.js

@@ -1,5 +1,7 @@
 import { getDextoPath } from "../utils/path.js";
 import * as path from "path";
+import { discoverCommandPrompts } from "./discover-prompts.js";
+import { discoverCommandPrompts as discoverCommandPrompts2 } from "./discover-prompts.js";
 function deriveAgentId(config, configPath) {
   if (config.agentCard?.name) {
     const sanitizedName = config.agentCard.name.toLowerCase().replace(/[^a-z0-9-_]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
@@ -13,9 +15,11 @@ function deriveAgentId(config, configPath) {
       return basename;
     }
   }
-  return "default-agent";
+  return "coding-agent";
 }
-function enrichAgentConfig(config, configPath, isInteractiveCli = false) {
+function enrichAgentConfig(config, configPath, options = {}) {
+  const opts = typeof options === "boolean" ? { isInteractiveCli: options } : options;
+  const { isInteractiveCli = false, logLevel = "error" } = opts;
   const agentId = deriveAgentId(config, configPath);
   const logPath = getDextoPath("logs", `${agentId}.log`);
   const dbPath = getDextoPath("database", `${agentId}.db`);
@@ -45,7 +49,7 @@ function enrichAgentConfig(config, configPath, isInteractiveCli = false) {
       }
     ];
     enriched.logger = {
-      level: "info",
+      level: logLevel,
       transports
     };
   } else {
@@ -74,9 +78,24 @@ function enrichAgentConfig(config, configPath, isInteractiveCli = false) {
       };
     }
   }
+  const discoveredPrompts = discoverCommandPrompts();
+  if (discoveredPrompts.length > 0) {
+    const existingPrompts = config.prompts ?? [];
+    const existingFilePaths = /* @__PURE__ */ new Set();
+    for (const prompt of existingPrompts) {
+      if (prompt.type === "file") {
+        existingFilePaths.add(path.resolve(prompt.file));
+      }
+    }
+    const filteredDiscovered = discoveredPrompts.filter(
+      (p) => !existingFilePaths.has(path.resolve(p.file))
+    );
+    enriched.prompts = [...existingPrompts, ...filteredDiscovered];
+  }
   return enriched;
 }
 export {
   deriveAgentId,
+  discoverCommandPrompts2 as discoverCommandPrompts,
   enrichAgentConfig
 };