@dexto/core 1.1.10 → 1.2.0

package/dist/agent/registry/registry.d.ts

@@ -1,67 +1,130 @@
-import { AgentRegistry, Registry, AgentRegistryEntry } from './types.js';
-import 'zod';
-
+import { Registry, AgentRegistry, AgentRegistryEntry } from './types.js';
 /**
  * Local agent registry implementation
- * TODO: MOVE THIS INTO CLI WHERE IT IS USED, and add posthog instrumentation for install/uninstall/resolve/etc, similar to manual install command
+ *
+ * TODO: ARCHITECTURAL REFACTOR - Move registry, preferences, and agent resolution to CLI
+ *
+ * PROBLEM: Registry operations are CLI concerns but live in Core, causing:
+ * - Missing analytics for auto-install (when running `dexto`, registry installs agents but doesn't track)
+ * - Wrong separation of concerns (Core = execution engine, not discovery/setup)
+ * - Registry manages ~/.dexto/agents filesystem which is CLI-level setup
+ *
+ * THE RIGHT ARCHITECTURE:
+ *
+ * Move to CLI:
+ * 1. Agent Registry (packages/core/src/agent/registry/) → packages/cli/src/registry/
+ *    - installAgent(), uninstallAgent(), resolveAgent(), listAgents()
+ *    - Can directly call capture() for analytics
+ *    - Manages ~/.dexto/agents installation directory
+ *
+ * 2. Global Preferences (packages/core/src/preferences/) → packages/cli/src/preferences/
+ *    - User's default LLM, model, default agent
+ *    - Used by `dexto setup` command
+ *    - Manages ~/.dexto/preferences.json
+ *
+ * 3. Agent Resolution (packages/core/src/config/agent-resolver.ts) → packages/cli/src/agent-resolver.ts
+ *    - Discovery logic: check registry, trigger installs, apply preferences
+ *    - Returns resolved config PATH to core
+ *
+ * Core keeps:
+ * - config/loader.ts - Load YAML from path
+ * - config/schemas.ts - Zod validation
+ * - Agent execution (DextoAgent, LLM, tools, MCP)
+ *
+ * FLOW AFTER REFACTOR:
+ * CLI index.ts:
+ *   → CLI: resolveAgentPath() (discovery logic)
+ *     → CLI: registry.resolveAgent()
+ *       → CLI: registry.installAgent() if needed
+ *       → CLI: capture('dexto_install_agent', ...) ✓ Natural!
+ *   → Core: new DextoAgent(configPath) (just loads & runs)
+ *
+ * BENEFITS:
+ * - Clear separation: CLI = setup/discovery, Core = execution
+ * - Analytics naturally colocated with operations
+ * - Core is portable (no CLI dependencies)
+ * - No circular deps (CLI → Core, correct direction)
+ *
+ * ESTIMATE: ~3-4 hours (mostly moving code + updating imports)
  */
-declare class LocalAgentRegistry implements AgentRegistry {
+export declare class LocalAgentRegistry implements AgentRegistry {
     private _registry;
     /**
      * Lazy load registry from JSON file
      */
     getRegistry(): Registry;
     /**
-     * Load registry from bundled JSON file
+     * Load and merge bundled + user registries
      * Uses fail-fast approach - throws RegistryError for any loading issues
      */
     private loadRegistry;
     /**
-     * Check if agent exists in registry
+     * Check if agent exists in registry by ID
      */
-    hasAgent(name: string): boolean;
+    hasAgent(agentId: string): boolean;
     /**
      * Get available agents with their metadata from registry
      */
     getAvailableAgents(): Record<string, AgentRegistryEntry>;
+    /**
+     * Validate custom agent ID doesn't conflict with bundled registry
+     * @throws RegistryError if ID conflicts with builtin agent
+     */
+    private validateCustomAgentId;
     /**
      * Resolve main config file for installed agent
      * Handles both directory agents (with main field) and single-file agents
      */
-    resolveMainConfig(agentDir: string, agentName: string): string;
+    resolveMainConfig(agentDir: string, agentId: string): string;
     /**
      * Install agent atomically using temp + rename pattern
-     * @param agentName Name of the agent to install
+     * @param agentId ID of the agent to install
      * @param injectPreferences Whether to inject global preferences into installed agent (default: true)
      */
-    installAgent(agentName: string, injectPreferences?: boolean): Promise<string>;
+    installAgent(agentId: string, injectPreferences?: boolean): Promise<string>;
+    /**
+     * Install a custom agent from a local file path
+     * @param agentId Unique identifier for the custom agent
+     * @param sourcePath Absolute path to agent YAML file or directory
+     * @param metadata Agent metadata (name for display, description, author, tags, main)
+     * @param injectPreferences Whether to inject global preferences (default: true)
+     * @returns Path to the installed agent's main config file
+     */
+    installCustomAgentFromPath(agentId: string, sourcePath: string, metadata: {
+        name?: string;
+        description: string;
+        author: string;
+        tags: string[];
+        main?: string;
+    }, injectPreferences?: boolean): Promise<string>;
     /**
-     * Resolve a registry agent name to a config path
-     * NOTE: Only handles registry names, not file paths (routing done in loadAgentConfig)
+     * Resolve a registry agent ID to a config path
+     * NOTE: Only handles registry IDs, not file paths (routing done in loadAgentConfig)
      * Handles installing agent if needed
-     * @param agentName Name of the agent to resolve
+     * @param agentId ID of the agent to resolve
      * @param autoInstall Whether to automatically install missing agents from registry (default: true)
      * @param injectPreferences Whether to inject preferences during auto-installation (default: true)
      */
-    resolveAgent(agentName: string, autoInstall?: boolean, injectPreferences?: boolean): Promise<string>;
+    resolveAgent(agentId: string, autoInstall?: boolean, injectPreferences?: boolean): Promise<string>;
     /**
      * Get list of currently installed agents
      */
     getInstalledAgents(): Promise<string[]>;
     /**
-     * Check if an agent is safe to uninstall (not the default-agent which is critical)
+     * Check if an agent is safe to uninstall (not the default agent from preferences)
      */
     private isAgentSafeToUninstall;
     /**
      * Uninstall an agent by removing its directory
-     * @param agentName Name of the agent to uninstall
+     * For custom agents: also removes from user registry
+     * For builtin agents: only removes from disk
+     * @param agentId ID of the agent to uninstall
      * @param force Whether to force uninstall even if agent is protected (default: false)
      */
-    uninstallAgent(agentName: string, force?: boolean): Promise<void>;
+    uninstallAgent(agentId: string, force?: boolean): Promise<void>;
 }
 /**
  * Get cached registry instance (singleton pattern)
  */
-declare function getAgentRegistry(): LocalAgentRegistry;
-
-export { LocalAgentRegistry, getAgentRegistry };
+export declare function getAgentRegistry(): LocalAgentRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/agent/registry/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/agent/registry/registry.ts"],"names":[],"mappings":"AAOA,OAAO,EACH,QAAQ,EAER,aAAa,EACb,kBAAkB,EAErB,MAAM,YAAY,CAAC;AAYpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,qBAAa,kBAAmB,YAAW,aAAa;IACpD,OAAO,CAAC,SAAS,CAAyB;IAE1C;;OAEG;IACH,WAAW,IAAI,QAAQ;IAOvB;;;OAGG;IACH,OAAO,CAAC,YAAY;IAyCpB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAKlC;;OAEG;IACH,kBAAkB,IAAI,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC;IAKxD;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAgC7B;;;OAGG;IACH,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM;IAqC5D;;;;OAIG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,iBAAiB,GAAE,OAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAqGvF;;;;;;;OAOG;IACG,0BAA0B,CAC5B,OAAO,EAAE,MAAM,EACf,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;IAqKlB;;;;;;;OAOG;IACG,YAAY,CACd,OAAO,EAAE,MAAM,EACf,WAAW,GAAE,OAAc,EAC3B,iBAAiB,GAAE,OAAc,GAClC,OAAO,CAAC,MAAM,CAAC;IAsClB;;OAEG;IACG,kBAAkB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAsB7C;;OAEG;YACW,sBAAsB;IAYpC;;;;;;OAMG;IACG,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,GAAE,OAAe,GAAG,OAAO,CAAC,IAAI,CAAC;CA8C/E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,kBAAkB,CAKrD"}

package/dist/agent/registry/registry.js

@@ -1,3 +1,4 @@
+import "../../chunk-C6A6W6XS.js";
 import { existsSync, readFileSync } from "fs";
 import { promises as fs } from "fs";
 import path from "path";
@@ -5,8 +6,17 @@ import { logger } from "../../logger/index.js";
 import { resolveBundledScript, getDextoGlobalPath, copyDirectory } from "../../utils/path.js";
 import { loadGlobalPreferences } from "../../preferences/loader.js";
 import { writePreferencesToAgent } from "../../config/writer.js";
-import { RegistrySchema } from "./types.js";
+import {
+  RegistrySchema,
+  normalizeRegistryJson
+} from "./types.js";
 import { RegistryError } from "./errors.js";
+import {
+  loadUserRegistry,
+  mergeRegistries,
+  removeAgentFromUserRegistry,
+  addAgentToUserRegistry
+} from "./user-registry.js";
 let cachedRegistry = null;
 class LocalAgentRegistry {
   _registry = null;
@@ -20,7 +30,7 @@ class LocalAgentRegistry {
     return this._registry;
   }
   /**
-   * Load registry from bundled JSON file
+   * Load and merge bundled + user registries
    * Uses fail-fast approach - throws RegistryError for any loading issues
    */
   loadRegistry() {
@@ -36,23 +46,30 @@ class LocalAgentRegistry {
     if (!existsSync(jsonPath)) {
       throw RegistryError.registryNotFound(jsonPath, "File doesn't exist");
     }
+    let bundledRegistry;
     try {
       const jsonData = readFileSync(jsonPath, "utf-8");
       const rawRegistry = JSON.parse(jsonData);
-      return RegistrySchema.parse(rawRegistry);
+      bundledRegistry = RegistrySchema.parse(normalizeRegistryJson(rawRegistry));
     } catch (error) {
       throw RegistryError.registryParseError(
         jsonPath,
         error instanceof Error ? error.message : String(error)
       );
     }
+    const userRegistry = loadUserRegistry();
+    const merged = mergeRegistries(bundledRegistry, userRegistry);
+    logger.debug(
+      `Loaded registry: ${Object.keys(bundledRegistry.agents).length} bundled, ${Object.keys(userRegistry.agents).length} custom`
+    );
+    return merged;
   }
   /**
-   * Check if agent exists in registry
+   * Check if agent exists in registry by ID
    */
-  hasAgent(name) {
+  hasAgent(agentId) {
     const registry = this.getRegistry();
-    return name in registry.agents;
+    return agentId in registry.agents;
   }
   /**
    * Get available agents with their metadata from registry
@@ -61,27 +78,59 @@ class LocalAgentRegistry {
     const registry = this.getRegistry();
     return registry.agents;
   }
+  /**
+   * Validate custom agent ID doesn't conflict with bundled registry
+   * @throws RegistryError if ID conflicts with builtin agent
+   */
+  validateCustomAgentId(agentId) {
+    let jsonPath;
+    try {
+      jsonPath = resolveBundledScript("agents/agent-registry.json");
+    } catch (error) {
+      throw RegistryError.registryNotFound(
+        "agents/agent-registry.json",
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+    try {
+      const jsonData = readFileSync(jsonPath, "utf-8");
+      const bundledRegistry = RegistrySchema.parse(
+        normalizeRegistryJson(JSON.parse(jsonData))
+      );
+      if (agentId in bundledRegistry.agents) {
+        throw RegistryError.customAgentNameConflict(agentId);
+      }
+    } catch (error) {
+      if (error instanceof Error && /name conflicts with builtin agent/.test(error.message)) {
+        throw error;
+      }
+      throw RegistryError.registryParseError(
+        jsonPath,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
   /**
    * Resolve main config file for installed agent
    * Handles both directory agents (with main field) and single-file agents
    */
-  resolveMainConfig(agentDir, agentName) {
+  resolveMainConfig(agentDir, agentId) {
     const registry = this.getRegistry();
-    const agentData = registry.agents[agentName];
+    const agentData = registry.agents[agentId];
     if (!agentData) {
       const available = Object.keys(registry.agents);
-      throw RegistryError.agentNotFound(agentName, available);
+      throw RegistryError.agentNotFound(agentId, available);
     }
     if (agentData.source.endsWith("/")) {
       if (!agentData.main) {
         throw RegistryError.agentInvalidEntry(
-          agentName,
+          agentId,
           "directory entry missing main field"
         );
       }
       const mainConfigPath = path.join(agentDir, agentData.main);
       if (!existsSync(mainConfigPath)) {
-        throw RegistryError.mainConfigMissing(agentName, mainConfigPath);
+        throw RegistryError.mainConfigMissing(agentId, mainConfigPath);
       }
       return mainConfigPath;
     } else {
@@ -95,22 +144,29 @@ class LocalAgentRegistry {
   }
   /**
    * Install agent atomically using temp + rename pattern
-   * @param agentName Name of the agent to install
+   * @param agentId ID of the agent to install
    * @param injectPreferences Whether to inject global preferences into installed agent (default: true)
    */
-  async installAgent(agentName, injectPreferences = true) {
-    logger.info(`Installing agent: ${agentName}`);
+  async installAgent(agentId, injectPreferences = true) {
+    logger.info(`Installing agent: ${agentId}`);
     const registry = this.getRegistry();
-    const agentData = registry.agents[agentName];
+    const agentData = registry.agents[agentId];
     if (!agentData) {
       const available = Object.keys(registry.agents);
-      throw RegistryError.agentNotFound(agentName, available);
+      throw RegistryError.agentNotFound(agentId, available);
     }
     const globalAgentsDir = getDextoGlobalPath("agents");
-    const targetDir = path.join(globalAgentsDir, agentName);
+    const targetDir = path.resolve(globalAgentsDir, agentId);
+    const relTarget = path.relative(globalAgentsDir, targetDir);
+    if (relTarget.startsWith("..") || path.isAbsolute(relTarget)) {
+      throw RegistryError.installationFailed(
+        agentId,
+        "invalid agentId: path traversal detected"
+      );
+    }
     if (existsSync(targetDir)) {
-      logger.info(`Agent '${agentName}' already installed`);
-      return this.resolveMainConfig(targetDir, agentName);
+      logger.info(`Agent '${agentId}' already installed`);
+      return this.resolveMainConfig(targetDir, agentId);
     }
     await fs.mkdir(globalAgentsDir, { recursive: true });
     const sourcePath = resolveBundledScript(`agents/${agentData.source}`);
@@ -123,31 +179,144 @@ class LocalAgentRegistry {
         const targetFile = path.join(tempDir, path.basename(sourcePath));
         await fs.copyFile(sourcePath, targetFile);
       }
-      const mainConfigPath = this.resolveMainConfig(tempDir, agentName);
+      const mainConfigPath = this.resolveMainConfig(tempDir, agentId);
       if (!existsSync(mainConfigPath)) {
-        throw RegistryError.installationValidationFailed(agentName, mainConfigPath);
+        throw RegistryError.installationValidationFailed(agentId, mainConfigPath);
       }
       await fs.rename(tempDir, targetDir);
-      logger.info(`\u2713 Installed agent '${agentName}' to ${targetDir}`);
+      logger.info(`\u2713 Installed agent '${agentId}' to ${targetDir}`);
       if (injectPreferences) {
         try {
           const preferences = await loadGlobalPreferences();
           await writePreferencesToAgent(targetDir, preferences);
-          logger.info(`\u2713 Applied global preferences to installed agent '${agentName}'`);
+          logger.info(`\u2713 Applied global preferences to installed agent '${agentId}'`);
         } catch (error) {
           logger.warn(
-            `Failed to inject preferences to '${agentName}': ${error instanceof Error ? error.message : String(error)}`
+            `Failed to inject preferences to '${agentId}': ${error instanceof Error ? error.message : String(error)}`
           );
           console.log(
-            `\u26A0\uFE0F  Warning: Could not apply preferences to '${agentName}' - agent will use bundled settings`
+            `\u26A0\uFE0F  Warning: Could not apply preferences to '${agentId}' - agent will use bundled settings`
           );
         }
       } else {
         logger.info(
-          `Skipped preference injection for '${agentName}' (injectPreferences=false)`
+          `Skipped preference injection for '${agentId}' (injectPreferences=false)`
+        );
+      }
+      return this.resolveMainConfig(targetDir, agentId);
+    } catch (error) {
+      try {
+        if (existsSync(tempDir)) {
+          await fs.rm(tempDir, { recursive: true, force: true });
+        }
+      } catch (cleanupError) {
+        logger.error(
+          `Failed to clean up temp directory: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}. Skipping cleanup...`
         );
       }
-      return this.resolveMainConfig(targetDir, agentName);
+      throw RegistryError.installationFailed(
+        agentId,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
+  /**
+   * Install a custom agent from a local file path
+   * @param agentId Unique identifier for the custom agent
+   * @param sourcePath Absolute path to agent YAML file or directory
+   * @param metadata Agent metadata (name for display, description, author, tags, main)
+   * @param injectPreferences Whether to inject global preferences (default: true)
+   * @returns Path to the installed agent's main config file
+   */
+  async installCustomAgentFromPath(agentId, sourcePath, metadata, injectPreferences = true) {
+    logger.info(`Installing custom agent '${agentId}' from ${sourcePath}`);
+    this.validateCustomAgentId(agentId);
+    if (!existsSync(sourcePath)) {
+      throw RegistryError.configNotFound(sourcePath);
+    }
+    const globalAgentsDir = getDextoGlobalPath("agents");
+    const targetDir = path.resolve(globalAgentsDir, agentId);
+    const relTarget = path.relative(globalAgentsDir, targetDir);
+    if (relTarget.startsWith("..") || path.isAbsolute(relTarget)) {
+      throw RegistryError.installationFailed(
+        agentId,
+        "invalid agentId: path traversal detected"
+      );
+    }
+    if (existsSync(targetDir)) {
+      throw RegistryError.agentAlreadyExists(agentId);
+    }
+    await fs.mkdir(globalAgentsDir, { recursive: true });
+    const stats = await fs.stat(sourcePath);
+    const isDirectory = stats.isDirectory();
+    const configFileName = isDirectory ? void 0 : `${agentId}.yml`;
+    if (!metadata.description) {
+      throw RegistryError.installationFailed(agentId, "description is required");
+    }
+    if (isDirectory && !metadata.main) {
+      throw RegistryError.installationFailed(
+        agentId,
+        "main field is required for directory-based agents"
+      );
+    }
+    const displayName = metadata.name || agentId.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+    const registryEntry = {
+      id: agentId,
+      name: displayName,
+      description: metadata.description,
+      author: metadata.author,
+      tags: metadata.tags,
+      source: isDirectory ? `${agentId}/` : configFileName,
+      main: metadata.main
+    };
+    const tempDir = `${targetDir}.tmp.${Date.now()}`;
+    try {
+      if (isDirectory) {
+        await copyDirectory(sourcePath, tempDir);
+      } else {
+        await fs.mkdir(tempDir, { recursive: true });
+        const targetFile = path.join(tempDir, configFileName);
+        await fs.copyFile(sourcePath, targetFile);
+      }
+      const tempMainConfigPath = isDirectory ? path.join(tempDir, metadata.main) : path.join(tempDir, configFileName);
+      if (!existsSync(tempMainConfigPath)) {
+        throw RegistryError.installationValidationFailed(agentId, tempMainConfigPath);
+      }
+      await fs.rename(tempDir, targetDir);
+      logger.info(`\u2713 Installed custom agent '${agentId}' to ${targetDir}`);
+      const mainConfigPath = isDirectory && metadata.main ? path.join(targetDir, metadata.main) : path.join(targetDir, configFileName);
+      try {
+        await addAgentToUserRegistry(agentId, registryEntry);
+        logger.info(`\u2713 Added '${agentId}' to user registry`);
+        this._registry = null;
+      } catch (registryError) {
+        try {
+          if (existsSync(targetDir)) {
+            await fs.rm(targetDir, { recursive: true, force: true });
+            logger.info(`Rolled back installation: removed ${targetDir}`);
+          }
+        } catch (rollbackError) {
+          logger.error(
+            `Rollback failed for '${agentId}': ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`
+          );
+        }
+        throw registryError;
+      }
+      if (injectPreferences) {
+        try {
+          const preferences = await loadGlobalPreferences();
+          await writePreferencesToAgent(targetDir, preferences);
+          logger.info(`\u2713 Applied global preferences to custom agent '${agentId}'`);
+        } catch (error) {
+          logger.warn(
+            `Failed to inject preferences to '${agentId}': ${error instanceof Error ? error.message : String(error)}`
+          );
+          console.log(
+            `\u26A0\uFE0F  Warning: Could not apply preferences to '${agentId}' - agent will use default settings`
+          );
+        }
+      }
+      return mainConfigPath;
     } catch (error) {
       try {
         if (existsSync(tempDir)) {
@@ -155,46 +324,50 @@ class LocalAgentRegistry {
         }
       } catch (cleanupError) {
         logger.error(
-          `Failed to clean up temp directory: ${cleanupError}. Skipping cleanup...`
+          `Failed to clean up temp directory: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}. Skipping cleanup...`
         );
       }
       throw RegistryError.installationFailed(
-        agentName,
+        agentId,
         error instanceof Error ? error.message : String(error)
       );
     }
   }
   /**
-   * Resolve a registry agent name to a config path
-   * NOTE: Only handles registry names, not file paths (routing done in loadAgentConfig)
+   * Resolve a registry agent ID to a config path
+   * NOTE: Only handles registry IDs, not file paths (routing done in loadAgentConfig)
    * Handles installing agent if needed
-   * @param agentName Name of the agent to resolve
+   * @param agentId ID of the agent to resolve
    * @param autoInstall Whether to automatically install missing agents from registry (default: true)
    * @param injectPreferences Whether to inject preferences during auto-installation (default: true)
    */
-  async resolveAgent(agentName, autoInstall = true, injectPreferences = true) {
-    logger.debug(`Resolving registry agent: ${agentName}`);
+  async resolveAgent(agentId, autoInstall = true, injectPreferences = true) {
+    logger.debug(`Resolving registry agent: ${agentId}`);
     const globalAgentsDir = getDextoGlobalPath("agents");
-    const installedPath = path.join(globalAgentsDir, agentName);
+    const installedPath = path.resolve(globalAgentsDir, agentId);
+    const relInstalled = path.relative(globalAgentsDir, installedPath);
+    if (relInstalled.startsWith("..") || path.isAbsolute(relInstalled)) {
+      throw RegistryError.agentNotFound(agentId, Object.keys(this.getRegistry().agents));
+    }
     if (existsSync(installedPath)) {
-      const mainConfig = this.resolveMainConfig(installedPath, agentName);
-      logger.debug(`Resolved installed agent '${agentName}' to: ${mainConfig}`);
+      const mainConfig = this.resolveMainConfig(installedPath, agentId);
+      logger.debug(`Resolved installed agent '${agentId}' to: ${mainConfig}`);
       return mainConfig;
     }
-    logger.debug(`Agent '${agentName}' not found in installed path: ${installedPath}`);
-    if (this.hasAgent(agentName)) {
+    logger.debug(`Agent '${agentId}' not found in installed path: ${installedPath}`);
+    if (this.hasAgent(agentId)) {
       if (autoInstall) {
-        logger.info(`Installing agent '${agentName}' from registry...`);
-        return await this.installAgent(agentName, injectPreferences);
+        logger.info(`Installing agent '${agentId}' from registry...`);
+        return await this.installAgent(agentId, injectPreferences);
       } else {
         const registry2 = this.getRegistry();
         const available2 = Object.keys(registry2.agents);
-        throw RegistryError.agentNotInstalledAutoInstallDisabled(agentName, available2);
+        throw RegistryError.agentNotInstalledAutoInstallDisabled(agentId, available2);
       }
     }
     const registry = this.getRegistry();
     const available = Object.keys(registry.agents);
-    throw RegistryError.agentNotFound(agentName, available);
+    throw RegistryError.agentNotFound(agentId, available);
   }
   /**
    * Get list of currently installed agents
@@ -213,32 +386,56 @@ class LocalAgentRegistry {
     }
   }
   /**
-   * Check if an agent is safe to uninstall (not the default-agent which is critical)
+   * Check if an agent is safe to uninstall (not the default agent from preferences)
    */
-  isAgentSafeToUninstall(agentName) {
-    return agentName !== "default-agent";
+  async isAgentSafeToUninstall(agentId) {
+    try {
+      const preferences = await loadGlobalPreferences();
+      const defaultAgent = preferences.defaults.defaultAgent;
+      return agentId !== defaultAgent;
+    } catch {
+      logger.warn("Could not load preferences, using fallback protection for default-agent");
+      return agentId !== "default-agent";
+    }
   }
   /**
    * Uninstall an agent by removing its directory
-   * @param agentName Name of the agent to uninstall
+   * For custom agents: also removes from user registry
+   * For builtin agents: only removes from disk
+   * @param agentId ID of the agent to uninstall
    * @param force Whether to force uninstall even if agent is protected (default: false)
    */
-  async uninstallAgent(agentName, force = false) {
+  async uninstallAgent(agentId, force = false) {
     const globalAgentsDir = getDextoGlobalPath("agents");
-    const agentDir = path.join(globalAgentsDir, agentName);
-    logger.info(`Uninstalling agent: ${agentName} from ${agentDir}`);
+    const agentDir = path.resolve(globalAgentsDir, agentId);
+    const relAgent = path.relative(globalAgentsDir, agentDir);
+    if (relAgent.startsWith("..") || path.isAbsolute(relAgent)) {
+      throw RegistryError.uninstallationFailed(
+        agentId,
+        "invalid agentId: path traversal detected"
+      );
+    }
+    logger.info(`Uninstalling agent: ${agentId} from ${agentDir}`);
     if (!existsSync(agentDir)) {
-      throw RegistryError.agentNotInstalled(agentName);
+      throw RegistryError.agentNotInstalled(agentId);
     }
-    if (!force && !this.isAgentSafeToUninstall(agentName)) {
-      throw RegistryError.agentProtected(agentName);
+    if (!force && !await this.isAgentSafeToUninstall(agentId)) {
+      throw RegistryError.agentProtected(agentId);
     }
+    const registry = this.getRegistry();
+    const agentData = registry.agents[agentId];
+    const isCustomAgent = agentData?.type === "custom";
     try {
       await fs.rm(agentDir, { recursive: true, force: true });
-      logger.info(`\u2713 Removed agent '${agentName}' from ${agentDir}`);
+      logger.info(`\u2713 Removed agent '${agentId}' from ${agentDir}`);
+      if (isCustomAgent) {
+        await removeAgentFromUserRegistry(agentId);
+        logger.info(`\u2713 Removed custom agent '${agentId}' from user registry`);
+        this._registry = null;
+      }
     } catch (error) {
       throw RegistryError.uninstallationFailed(
-        agentName,
+        agentId,
         error instanceof Error ? error.message : String(error)
       );
     }

package/dist/agent/registry/types.cjs

@@ -19,23 +19,56 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var types_exports = {};
 __export(types_exports, {
   AgentRegistryEntrySchema: () => AgentRegistryEntrySchema,
-  RegistrySchema: () => RegistrySchema
+  RegistrySchema: () => RegistrySchema,
+  deriveDisplayName: () => deriveDisplayName,
+  normalizeRegistryJson: () => normalizeRegistryJson
 });
 module.exports = __toCommonJS(types_exports);
 var import_zod = require("zod");
+function deriveDisplayName(slug) {
+  return slug.split("-").filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+}
 const AgentRegistryEntrySchema = import_zod.z.object({
+  id: import_zod.z.string().describe("Unique identifier for the agent"),
+  name: import_zod.z.string().describe("Display name for the agent"),
   description: import_zod.z.string(),
   author: import_zod.z.string(),
   tags: import_zod.z.array(import_zod.z.string()),
   source: import_zod.z.string(),
-  main: import_zod.z.string().optional()
+  main: import_zod.z.string().optional(),
+  type: import_zod.z.enum(["builtin", "custom"]).default("builtin").describe("Agent type")
 }).strict();
 const RegistrySchema = import_zod.z.object({
   version: import_zod.z.string(),
   agents: import_zod.z.record(import_zod.z.string(), AgentRegistryEntrySchema)
 }).strict();
+function normalizeRegistryJson(raw) {
+  if (!raw || typeof raw !== "object") {
+    return { version: "1.0.0", agents: {} };
+  }
+  const input = raw;
+  const normalizedAgents = {};
+  const agents = input.agents && typeof input.agents === "object" && input.agents !== null ? input.agents : {};
+  for (const [agentId, value] of Object.entries(agents)) {
+    if (!value || typeof value !== "object") continue;
+    const entry = { ...value };
+    if (!entry.id || typeof entry.id !== "string" || entry.id.trim() !== agentId) {
+      entry.id = agentId;
+    }
+    if (!entry.name || typeof entry.name !== "string" || !entry.name.trim()) {
+      entry.name = deriveDisplayName(agentId);
+    }
+    normalizedAgents[agentId] = entry;
+  }
+  return {
+    version: typeof input.version === "string" && input.version.trim().length > 0 ? input.version : "1.0.0",
+    agents: normalizedAgents
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AgentRegistryEntrySchema,
-  RegistrySchema
+  RegistrySchema,
+  deriveDisplayName,
+  normalizeRegistryJson
 });