musonda 1.0.0

package/dist/plugins/pluginManager.js

@@ -0,0 +1,1016 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { ManifestValidator } from './manifest.js';
+import { SkillDiscovery } from './skills/skillDiscovery.js';
+import { SkillToolFactory } from './skills/skillTools.js';
+import { SkillFrontmatterParser } from './skills/frontmatterParser.js';
+import { McpConfigValidator } from './mcp/mcpConfig.js';
+import { McpBridge } from './mcp/mcpBridge.js';
+import { logger } from '../utils/logger.js';
+export class PluginManager {
+    config;
+    plugins = new Map();
+    skills = [];
+    mcpBridge = new McpBridge();
+    isLoaded = false;
+    constructor(config) {
+        this.config = config;
+    }
+    getAllSkills() {
+        return this.skills;
+    }
+    getAllPlugins() {
+        return Array.from(this.plugins.values());
+    }
+    getMcpBridge() {
+        return this.mcpBridge;
+    }
+    /**
+     * Discovers and loads all plugins from configured plugin directories.
+     * Registers skills and MCP tools into Musonda's ToolRegistry.
+     */
+    async loadAll(toolRegistry) {
+        const pluginsConfig = this.config.plugins;
+        if (!pluginsConfig || !pluginsConfig.enabled) {
+            logger.info('Agent Plugins subsystem is disabled.');
+            return;
+        }
+        logger.info('Initializing Agent Plugins subsystem...');
+        // Register built-in skill tools for progressive disclosure
+        const skillTools = SkillToolFactory.createTools(() => this.getAllSkills());
+        for (const tool of skillTools) {
+            toolRegistry.register(tool);
+        }
+        const baseDataDir = path.resolve(pluginsConfig.dataDir || './data/plugin_data');
+        if (!fs.existsSync(baseDataDir)) {
+            try {
+                fs.mkdirSync(baseDataDir, { recursive: true });
+            }
+            catch (err) {
+                logger.error(`Failed to create plugin data directory: ${err.message}`);
+            }
+        }
+        const disabledSet = new Set(pluginsConfig.disabledPlugins || []);
+        const searchDirs = pluginsConfig.directories || ['./data/plugins', './plugins'];
+        for (const searchDir of searchDirs) {
+            const resolvedSearchDir = path.resolve(searchDir);
+            if (!fs.existsSync(resolvedSearchDir)) {
+                continue;
+            }
+            let entries = [];
+            try {
+                entries = fs.readdirSync(resolvedSearchDir, { withFileTypes: true });
+            }
+            catch (err) {
+                logger.warn(`Could not read plugin search directory "${resolvedSearchDir}": ${err.message}`);
+                continue;
+            }
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                const candidateDir = path.join(resolvedSearchDir, entry.name);
+                await this.loadPluginFromDirectory(candidateDir, baseDataDir, disabledSet, toolRegistry);
+            }
+        }
+        this.isLoaded = true;
+        logger.info(`Agent Plugins loaded: ${this.plugins.size} plugin(s), ${this.skills.length} skill(s), ${this.mcpBridge.getActiveServers().length} active MCP server(s).`);
+    }
+    /**
+     * Loads a single plugin from a directory.
+     */
+    async loadPluginFromDirectory(pluginDir, baseDataDir, disabledSet, toolRegistry) {
+        const resolvedPluginDir = path.resolve(pluginDir);
+        const manifestPath = path.join(resolvedPluginDir, 'plugin.json');
+        if (!fs.existsSync(manifestPath)) {
+            return null;
+        }
+        // 1. Validate manifest
+        const manifestResult = ManifestValidator.loadFromDirectory(resolvedPluginDir);
+        if (!manifestResult.valid || !manifestResult.manifest) {
+            logger.error(`[Plugin Rejected] "${resolvedPluginDir}" has invalid plugin.json: ${manifestResult.errors.join('; ')}`);
+            return null;
+        }
+        const manifest = manifestResult.manifest;
+        const pluginName = manifest.name;
+        if (disabledSet.has(pluginName)) {
+            logger.info(`[Plugin: ${pluginName}] Disabled in configuration. Skipping.`);
+            return null;
+        }
+        if (this.plugins.has(pluginName)) {
+            logger.warn(`[Plugin: ${pluginName}] Already loaded from another location. Skipping duplicate.`);
+            return null;
+        }
+        // 2. Dedicated writable plugin data directory
+        const pluginDataDir = path.join(baseDataDir, pluginName);
+        if (!fs.existsSync(pluginDataDir)) {
+            try {
+                fs.mkdirSync(pluginDataDir, { recursive: true });
+            }
+            catch (err) {
+                logger.error(`Could not create data dir for plugin "${pluginName}": ${err.message}`);
+            }
+        }
+        logger.info(`[Plugin: ${pluginName}] Loading package (version: ${manifest.version || 'unspecified'})...`);
+        // 3. Discover skills
+        const skillResult = SkillDiscovery.discover(resolvedPluginDir, pluginName);
+        if (skillResult.skills.length > 0) {
+            this.skills.push(...skillResult.skills);
+        }
+        // 4. Discover and connect MCP servers
+        const mcpResult = McpConfigValidator.loadFromDirectory(resolvedPluginDir, pluginName, pluginDataDir);
+        if (mcpResult.valid && mcpResult.servers.length > 0) {
+            for (const server of mcpResult.servers) {
+                // Pass plugin root and data to server context
+                server.pluginRoot = resolvedPluginDir;
+                server.pluginData = pluginDataDir;
+                await this.mcpBridge.registerServer(server, toolRegistry);
+            }
+        }
+        const pkg = {
+            name: pluginName,
+            rootDir: resolvedPluginDir,
+            dataDir: pluginDataDir,
+            manifest,
+        };
+        this.plugins.set(pluginName, pkg);
+        return pkg;
+    }
+    /**
+     * Unloads a plugin from runtime: terminates its MCP servers, removes its bridged tools and skills.
+     */
+    async unloadPlugin(pluginName, toolRegistry) {
+        const pkg = this.plugins.get(pluginName);
+        if (!pkg) {
+            return false;
+        }
+        // 1. Unregister MCP servers and bridged tools
+        await this.mcpBridge.unregisterServersForPlugin(pluginName, toolRegistry);
+        // 2. Remove skills belonging to this plugin
+        this.skills = this.skills.filter((s) => s.pluginName !== pluginName);
+        // 3. Remove plugin from map
+        this.plugins.delete(pluginName);
+        logger.info(`[Plugin: ${pluginName}] Unloaded from runtime.`);
+        return true;
+    }
+    /**
+     * Reloads a specific plugin from disk into the live runtime.
+     */
+    async reloadPlugin(pluginName, toolRegistry) {
+        const existing = this.plugins.get(pluginName);
+        const rootDir = existing?.rootDir;
+        if (existing) {
+            await this.unloadPlugin(pluginName, toolRegistry);
+        }
+        const pluginsConfig = this.config.plugins;
+        const baseDataDir = path.resolve(pluginsConfig?.dataDir || './data/plugin_data');
+        const disabledSet = new Set(pluginsConfig?.disabledPlugins || []);
+        // If we already know the rootDir, reload from there
+        if (rootDir && fs.existsSync(rootDir)) {
+            return await this.loadPluginFromDirectory(rootDir, baseDataDir, disabledSet, toolRegistry);
+        }
+        // Otherwise search configured searchDirs
+        const searchDirs = pluginsConfig?.directories || ['./data/plugins', './plugins'];
+        for (const searchDir of searchDirs) {
+            const candidateDir = path.resolve(searchDir, pluginName);
+            if (fs.existsSync(candidateDir)) {
+                return await this.loadPluginFromDirectory(candidateDir, baseDataDir, disabledSet, toolRegistry);
+            }
+        }
+        return null;
+    }
+    /**
+     * Reloads all plugins from configured directories without shutting down the gateway.
+     */
+    async reloadAll(toolRegistry) {
+        logger.info('Reloading all Agent Plugins...');
+        await this.mcpBridge.shutdown();
+        this.plugins.clear();
+        this.skills = [];
+        const pluginsConfig = this.config.plugins;
+        if (!pluginsConfig || !pluginsConfig.enabled) {
+            return { loaded: 0, skills: 0, mcpServers: 0 };
+        }
+        const baseDataDir = path.resolve(pluginsConfig.dataDir || './data/plugin_data');
+        const disabledSet = new Set(pluginsConfig.disabledPlugins || []);
+        const searchDirs = pluginsConfig.directories || ['./data/plugins', './plugins'];
+        for (const searchDir of searchDirs) {
+            const resolvedSearchDir = path.resolve(searchDir);
+            if (!fs.existsSync(resolvedSearchDir))
+                continue;
+            let entries = [];
+            try {
+                entries = fs.readdirSync(resolvedSearchDir, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                const candidateDir = path.join(resolvedSearchDir, entry.name);
+                await this.loadPluginFromDirectory(candidateDir, baseDataDir, disabledSet, toolRegistry);
+            }
+        }
+        logger.info(`Agent Plugins reloaded: ${this.plugins.size} plugin(s), ${this.skills.length} skill(s), ${this.mcpBridge.getActiveServers().length} active MCP server(s).`);
+        return {
+            loaded: this.plugins.size,
+            skills: this.skills.length,
+            mcpServers: this.mcpBridge.getActiveServers().length,
+        };
+    }
+    /**
+     * Scaffolds a new plugin on disk with valid manifest, optional skills, and optional MCP servers,
+     * then immediately activates it in the live runtime.
+     */
+    async createAndLoadPlugin(params, toolRegistry) {
+        // 1. Validate plugin name
+        const nameValidation = ManifestValidator.validatePluginName(params.name);
+        if (!nameValidation.valid) {
+            return {
+                success: false,
+                error: `Invalid plugin name: ${nameValidation.error}`,
+                skillsLoaded: 0,
+                toolsRegistered: [],
+            };
+        }
+        const pluginName = params.name;
+        const version = params.version || '1.0.0';
+        const pluginsConfig = this.config.plugins;
+        const basePluginsDir = (pluginsConfig?.directories && pluginsConfig.directories[0]) || './plugins';
+        const pluginDir = path.resolve(params.targetDir || path.join(basePluginsDir, pluginName));
+        if (fs.existsSync(pluginDir)) {
+            const manifestPath = path.join(pluginDir, 'plugin.json');
+            if (fs.existsSync(manifestPath) && this.plugins.has(pluginName)) {
+                return {
+                    success: false,
+                    error: `Plugin "${pluginName}" already exists at "${pluginDir}". Use plugin_reload to refresh existing plugins.`,
+                    skillsLoaded: 0,
+                    toolsRegistered: [],
+                };
+            }
+        }
+        try {
+            fs.mkdirSync(pluginDir, { recursive: true });
+            // 2. Build manifest
+            const manifest = {
+                $schema: 'https://agent-plugins.org/schemas/1.0.0/plugin.schema.json',
+                name: pluginName,
+                version,
+                description: params.description,
+                author: params.author || { name: 'Musonda Agent' },
+                license: 'MIT',
+            };
+            fs.writeFileSync(path.join(pluginDir, 'plugin.json'), JSON.stringify(manifest, null, 2), 'utf-8');
+            // 3. Write skills if provided
+            if (params.skills && params.skills.length > 0) {
+                for (const skill of params.skills) {
+                    const skillDir = path.join(pluginDir, 'skills', skill.name);
+                    fs.mkdirSync(skillDir, { recursive: true });
+                    // Ensure markdown has valid YAML frontmatter
+                    let skillMd = skill.content.trim();
+                    if (!skillMd.startsWith('---')) {
+                        skillMd = `---\nname: ${skill.name}\ndescription: ${skill.description}\nlicense: MIT\n---\n\n${skillMd}`;
+                    }
+                    fs.writeFileSync(path.join(skillDir, 'SKILL.md'), skillMd, 'utf-8');
+                    if (skill.scripts && skill.scripts.length > 0) {
+                        const scriptsDir = path.join(skillDir, 'scripts');
+                        fs.mkdirSync(scriptsDir, { recursive: true });
+                        for (const script of skill.scripts) {
+                            fs.writeFileSync(path.join(scriptsDir, script.filename), script.content, 'utf-8');
+                        }
+                    }
+                }
+            }
+            // 4. Write MCP configuration if provided
+            if (params.mcp) {
+                const mcpPath = path.join(pluginDir, 'mcp.json');
+                const mcpData = {
+                    $schema: 'https://agent-plugins.org/schemas/1.0.0/mcp.schema.json',
+                    ...params.mcp,
+                };
+                fs.writeFileSync(mcpPath, JSON.stringify(mcpData, null, 2), 'utf-8');
+            }
+            // 5. Load into runtime
+            const baseDataDir = path.resolve(pluginsConfig?.dataDir || './data/plugin_data');
+            const disabledSet = new Set(pluginsConfig?.disabledPlugins || []);
+            const pkg = await this.loadPluginFromDirectory(pluginDir, baseDataDir, disabledSet, toolRegistry);
+            if (!pkg) {
+                return {
+                    success: false,
+                    error: `Plugin files were created at "${pluginDir}", but failed to load into runtime.`,
+                    skillsLoaded: 0,
+                    toolsRegistered: [],
+                };
+            }
+            const pluginSkills = this.skills.filter((s) => s.pluginName === pluginName);
+            const activeMcpServers = this.mcpBridge.getActiveServers().filter((s) => s.server.pluginName === pluginName);
+            const toolsRegistered = activeMcpServers.flatMap((s) => s.tools.map((t) => t.name));
+            return {
+                success: true,
+                plugin: pkg,
+                skillsLoaded: pluginSkills.length,
+                toolsRegistered,
+            };
+        }
+        catch (err) {
+            logger.error(`Failed to create plugin "${pluginName}":`, err);
+            return {
+                success: false,
+                error: `Plugin creation failed: ${err.message}`,
+                skillsLoaded: 0,
+                toolsRegistered: [],
+            };
+        }
+    }
+    /**
+     * Installs an Agent Plugin from a local directory path, Git repository URL (e.g. GitHub), or npm package,
+     * validates its specification conformance (https://agent-plugins.org), installs any package dependencies,
+     * and immediately activates it in the live Musonda Gateway runtime without restarting the server.
+     */
+    async installPlugin(params, toolRegistry) {
+        const rawSource = params.source?.trim();
+        if (!rawSource) {
+            return {
+                success: false,
+                error: 'Missing required "source" parameter. Provide a local directory path, Git repository URL, or package identifier.',
+                skillsLoaded: 0,
+                toolsRegistered: [],
+            };
+        }
+        const pluginsConfig = this.config.plugins;
+        const configuredDirs = pluginsConfig?.directories || ['./data/plugins', './plugins'];
+        const searchDirs = configuredDirs.map((d) => path.resolve(d));
+        const basePluginsDir = searchDirs[0] || path.resolve('./plugins');
+        if (!fs.existsSync(basePluginsDir)) {
+            try {
+                fs.mkdirSync(basePluginsDir, { recursive: true });
+            }
+            catch (err) {
+                logger.error(`Could not create base plugins directory "${basePluginsDir}": ${err.message}`);
+            }
+        }
+        const isInsideAllowedDir = (targetPath) => {
+            const resolvedTarget = path.resolve(targetPath);
+            return searchDirs.some((allowedDir) => {
+                const rel = path.relative(allowedDir, resolvedTarget);
+                return !rel.startsWith('..') && !path.isAbsolute(rel) && rel.length > 0;
+            });
+        };
+        let targetPluginDir;
+        let sourceIsLocal = false;
+        let resolvedSourcePath = '';
+        // Check if source is a local directory
+        const candidateLocal = path.resolve(rawSource);
+        if (fs.existsSync(candidateLocal) && fs.statSync(candidateLocal).isDirectory()) {
+            sourceIsLocal = true;
+            resolvedSourcePath = candidateLocal;
+        }
+        if (sourceIsLocal) {
+            const manifestPath = path.join(resolvedSourcePath, 'plugin.json');
+            if (!fs.existsSync(manifestPath)) {
+                return {
+                    success: false,
+                    error: `Source directory "${resolvedSourcePath}" is missing required "plugin.json" manifest (https://agent-plugins.org).`,
+                    skillsLoaded: 0,
+                    toolsRegistered: [],
+                };
+            }
+            let parsedManifest;
+            try {
+                parsedManifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+            }
+            catch (err) {
+                return {
+                    success: false,
+                    error: `Invalid JSON in manifest "${manifestPath}": ${err.message}`,
+                    skillsLoaded: 0,
+                    toolsRegistered: [],
+                };
+            }
+            const pluginName = params.name || parsedManifest.name;
+            const nameValidation = ManifestValidator.validatePluginName(pluginName);
+            if (!nameValidation.valid) {
+                return {
+                    success: false,
+                    error: `Invalid plugin name "${pluginName}": ${nameValidation.error}`,
+                    skillsLoaded: 0,
+                    toolsRegistered: [],
+                };
+            }
+            if (params.targetDir) {
+                const candidateTarget = path.resolve(params.targetDir);
+                if (!isInsideAllowedDir(candidateTarget)) {
+                    return {
+                        success: false,
+                        error: `Security violation: targetDir "${params.targetDir}" must resolve strictly within a configured plugin directory (${searchDirs.join(', ')}).`,
+                        skillsLoaded: 0,
+                        toolsRegistered: [],
+                    };
+                }
+                targetPluginDir = candidateTarget;
+            }
+            else {
+                targetPluginDir = path.join(basePluginsDir, pluginName);
+            }
+            // Copy directory if not already at target location
+            if (path.resolve(resolvedSourcePath) !== path.resolve(targetPluginDir)) {
+                if (this.plugins.has(pluginName)) {
+                    await this.unloadPlugin(pluginName, toolRegistry);
+                }
+                if (fs.existsSync(targetPluginDir)) {
+                    if (!isInsideAllowedDir(targetPluginDir)) {
+                        return {
+                            success: false,
+                            error: `Security violation: Refusing to delete unsafe target directory "${targetPluginDir}".`,
+                            skillsLoaded: 0,
+                            toolsRegistered: [],
+                        };
+                    }
+                    fs.rmSync(targetPluginDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+                }
+                fs.mkdirSync(path.dirname(targetPluginDir), { recursive: true });
+                fs.cpSync(resolvedSourcePath, targetPluginDir, { recursive: true });
+            }
+        }
+        else {
+            // Treat as Git repository or remote URL
+            let gitUrl = rawSource;
+            if (gitUrl.startsWith('github:')) {
+                gitUrl = `https://github.com/${gitUrl.slice(7)}.git`;
+            }
+            else if (/^[a-zA-Z0-9_-]+\/[a-zA-Z0-9_.-]+$/.test(gitUrl)) {
+                gitUrl = `https://github.com/${gitUrl}.git`;
+            }
+            let derivedName = params.name;
+            if (!derivedName) {
+                const urlParts = gitUrl.replace(/\/+$/, '').split('/');
+                const lastPart = urlParts[urlParts.length - 1] || 'plugin';
+                derivedName = lastPart.replace(/\.git$/, '').toLowerCase().replace(/[^a-z0-9.-]/g, '-');
+            }
+            if (params.targetDir) {
+                const candidateTarget = path.resolve(params.targetDir);
+                if (!isInsideAllowedDir(candidateTarget)) {
+                    return {
+                        success: false,
+                        error: `Security violation: targetDir "${params.targetDir}" must resolve strictly within a configured plugin directory (${searchDirs.join(', ')}).`,
+                        skillsLoaded: 0,
+                        toolsRegistered: [],
+                    };
+                }
+                targetPluginDir = candidateTarget;
+            }
+            else {
+                targetPluginDir = path.join(basePluginsDir, derivedName);
+            }
+            if (this.plugins.has(derivedName)) {
+                await this.unloadPlugin(derivedName, toolRegistry);
+            }
+            if (fs.existsSync(targetPluginDir)) {
+                if (!isInsideAllowedDir(targetPluginDir)) {
+                    return {
+                        success: false,
+                        error: `Security violation: Refusing to delete unsafe target directory "${targetPluginDir}".`,
+                        skillsLoaded: 0,
+                        toolsRegistered: [],
+                    };
+                }
+                fs.rmSync(targetPluginDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+            }
+            fs.mkdirSync(path.dirname(targetPluginDir), { recursive: true });
+            try {
+                logger.info(`Cloning Git repository "${gitUrl}" into "${targetPluginDir}"...`);
+                execFileSync('git', ['clone', '--depth', '1', gitUrl, targetPluginDir], {
+                    stdio: 'pipe',
+                    timeout: 60000,
+                });
+            }
+            catch (err) {
+                const stderrMsg = err.stderr?.toString() || err.message;
+                return {
+                    success: false,
+                    error: `Failed to clone Git repository from "${gitUrl}": ${stderrMsg}`,
+                    skillsLoaded: 0,
+                    toolsRegistered: [],
+                };
+            }
+        }
+        // Validate the plugin at targetPluginDir
+        const manifestResult = ManifestValidator.loadFromDirectory(targetPluginDir);
+        if (!manifestResult.valid || !manifestResult.manifest) {
+            if (!sourceIsLocal) {
+                if (isInsideAllowedDir(targetPluginDir)) {
+                    fs.rmSync(targetPluginDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+                }
+            }
+            return {
+                success: false,
+                error: `Plugin manifest validation failed for "${targetPluginDir}": ${manifestResult.errors.join('; ')}`,
+                skillsLoaded: 0,
+                toolsRegistered: [],
+            };
+        }
+        const pluginName = manifestResult.manifest.name;
+        // Install production dependencies if package.json has dependencies and node_modules is missing
+        // Security: always supply --ignore-scripts to avoid untrusted lifecycle code execution
+        if (params.installDependencies !== false) {
+            const packageJsonPath = path.join(targetPluginDir, 'package.json');
+            const nodeModulesPath = path.join(targetPluginDir, 'node_modules');
+            if (fs.existsSync(packageJsonPath) && !fs.existsSync(nodeModulesPath)) {
+                try {
+                    const pkgJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+                    if (pkgJson.dependencies && Object.keys(pkgJson.dependencies).length > 0) {
+                        logger.info(`Installing dependencies for plugin "${pluginName}"...`);
+                        const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+                        execFileSync(npmCmd, ['install', '--omit=dev', '--ignore-scripts'], {
+                            cwd: targetPluginDir,
+                            stdio: 'pipe',
+                            shell: false,
+                            timeout: 120000,
+                        });
+                    }
+                }
+                catch (err) {
+                    logger.warn(`Could not install dependencies for plugin "${pluginName}": ${err.message}`);
+                }
+            }
+        }
+        // Load into runtime
+        const baseDataDir = path.resolve(pluginsConfig?.dataDir || './data/plugin_data');
+        const disabledSet = new Set(pluginsConfig?.disabledPlugins || []);
+        const pkg = await this.loadPluginFromDirectory(targetPluginDir, baseDataDir, disabledSet, toolRegistry);
+        if (!pkg) {
+            return {
+                success: false,
+                error: `Plugin was downloaded to "${targetPluginDir}", but failed to load into runtime. Check logs for details.`,
+                skillsLoaded: 0,
+                toolsRegistered: [],
+            };
+        }
+        const pluginSkills = this.skills.filter((s) => s.pluginName === pluginName);
+        const activeMcpServers = this.mcpBridge.getActiveServers().filter((s) => s.server.pluginName === pluginName);
+        const toolsRegistered = activeMcpServers.flatMap((s) => s.tools.map((t) => t.name));
+        return {
+            success: true,
+            plugin: pkg,
+            skillsLoaded: pluginSkills.length,
+            toolsRegistered,
+            installedPath: targetPluginDir,
+        };
+    }
+    /**
+     * Unloads and uninstalls an Agent Plugin: stops its MCP servers, removes bridged tools and skills
+     * from runtime, optionally deletes its files from disk, and optionally purges its persistent data directory.
+     */
+    async removePlugin(params, toolRegistry) {
+        const pluginName = params.pluginName?.trim();
+        if (!pluginName) {
+            return {
+                success: false,
+                error: 'Missing required "pluginName" parameter.',
+                pluginName: '',
+                unloaded: false,
+                deletedFiles: false,
+                purgedData: false,
+                skillsRemoved: [],
+                toolsUnregistered: [],
+            };
+        }
+        const existing = this.plugins.get(pluginName);
+        const skillsRemoved = this.skills.filter((s) => s.pluginName === pluginName).map((s) => s.name);
+        const activeMcpServers = this.mcpBridge.getActiveServers().filter((s) => s.server.pluginName === pluginName);
+        const toolsUnregistered = activeMcpServers.flatMap((s) => s.tools.map((t) => t.name));
+        // Determine root directory
+        let rootDir = existing?.rootDir;
+        const pluginsConfig = this.config.plugins;
+        const searchDirs = pluginsConfig?.directories || ['./data/plugins', './plugins'];
+        if (!rootDir) {
+            for (const searchDir of searchDirs) {
+                const candidateDir = path.resolve(searchDir, pluginName);
+                if (fs.existsSync(candidateDir)) {
+                    rootDir = candidateDir;
+                    break;
+                }
+            }
+        }
+        // Determine data directory
+        const baseDataDir = path.resolve(pluginsConfig?.dataDir || './data/plugin_data');
+        const dataDir = existing?.dataDir || path.join(baseDataDir, pluginName);
+        if (!existing && (!rootDir || !fs.existsSync(rootDir))) {
+            return {
+                success: false,
+                error: `Plugin "${pluginName}" not found in active runtime or on disk in configured directories.`,
+                pluginName,
+                unloaded: false,
+                deletedFiles: false,
+                purgedData: false,
+                skillsRemoved: [],
+                toolsUnregistered: [],
+            };
+        }
+        // 1. Unload from live runtime
+        let unloaded = false;
+        if (existing) {
+            unloaded = await this.unloadPlugin(pluginName, toolRegistry);
+        }
+        const allowedPluginDirs = searchDirs.map((d) => path.resolve(d));
+        const isInside = (candidate, allowedRoots) => {
+            const resolved = path.resolve(candidate);
+            return allowedRoots.some((root) => {
+                const rel = path.relative(root, resolved);
+                return !rel.startsWith('..') && !path.isAbsolute(rel) && rel.length > 0;
+            });
+        };
+        // 2. Delete plugin files from disk
+        let deletedFiles = false;
+        if (params.deleteFiles !== false && rootDir && fs.existsSync(rootDir)) {
+            if (!isInside(rootDir, allowedPluginDirs)) {
+                logger.error(`Security error: Refusing to delete plugin root directory "${rootDir}" outside allowed directories.`);
+            }
+            else {
+                for (let i = 0; i < 6; i++) {
+                    try {
+                        fs.rmSync(rootDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 150 });
+                        deletedFiles = true;
+                        logger.info(`[Plugin: ${pluginName}] Deleted package directory: "${rootDir}"`);
+                        break;
+                    }
+                    catch (err) {
+                        if (i === 5) {
+                            logger.warn(`Could not delete directory "${rootDir}" for plugin "${pluginName}": ${err.message}`);
+                        }
+                        else {
+                            await new Promise((r) => setTimeout(r, 250));
+                        }
+                    }
+                }
+            }
+        }
+        // 3. Purge persistent data directory if requested
+        let purgedData = false;
+        if (params.purgeData === true && dataDir && fs.existsSync(dataDir)) {
+            if (!isInside(dataDir, [baseDataDir])) {
+                logger.error(`Security error: Refusing to delete plugin data directory "${dataDir}" outside base data directory.`);
+            }
+            else {
+                for (let i = 0; i < 6; i++) {
+                    try {
+                        fs.rmSync(dataDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 150 });
+                        purgedData = true;
+                        logger.info(`[Plugin: ${pluginName}] Purged persistent data directory: "${dataDir}"`);
+                        break;
+                    }
+                    catch (err) {
+                        if (i === 5) {
+                            logger.warn(`Could not purge data directory "${dataDir}" for plugin "${pluginName}": ${err.message}`);
+                        }
+                        else {
+                            await new Promise((r) => setTimeout(r, 250));
+                        }
+                    }
+                }
+            }
+        }
+        return {
+            success: true,
+            pluginName,
+            unloaded,
+            deletedFiles,
+            purgedData,
+            skillsRemoved,
+            toolsUnregistered,
+        };
+    }
+    /**
+     * Discovers Agent Plugins locally on disk and across the ecosystem (official repositories, GitHub, npm).
+     */
+    async findPlugins(params = {}) {
+        const query = params.query?.trim().toLowerCase() || '';
+        const source = params.source || 'all';
+        const localResults = [];
+        const remoteResults = [];
+        // 1. Scan Local Plugins
+        if (source === 'all' || source === 'local') {
+            const pluginsConfig = this.config.plugins;
+            const searchDirs = pluginsConfig?.directories || ['./data/plugins', './plugins'];
+            const seenDirs = new Set();
+            for (const sDir of searchDirs) {
+                const resolvedDir = path.resolve(sDir);
+                if (!fs.existsSync(resolvedDir))
+                    continue;
+                let entries = [];
+                try {
+                    entries = fs.readdirSync(resolvedDir, { withFileTypes: true });
+                }
+                catch {
+                    continue;
+                }
+                for (const entry of entries) {
+                    if (!entry.isDirectory())
+                        continue;
+                    const candidatePath = path.join(resolvedDir, entry.name);
+                    if (seenDirs.has(candidatePath))
+                        continue;
+                    seenDirs.add(candidatePath);
+                    const manifestPath = path.join(candidatePath, 'plugin.json');
+                    if (!fs.existsSync(manifestPath))
+                        continue;
+                    try {
+                        const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+                        const pName = manifest.name || entry.name;
+                        const pDesc = manifest.description || '';
+                        const pKeywords = manifest.keywords || [];
+                        if (query &&
+                            !pName.toLowerCase().includes(query) &&
+                            !pDesc.toLowerCase().includes(query) &&
+                            !pKeywords.some((k) => k.toLowerCase().includes(query))) {
+                            continue;
+                        }
+                        // Inspect skills in skills/
+                        const skillDir = path.join(candidatePath, 'skills');
+                        const skills = [];
+                        if (fs.existsSync(skillDir)) {
+                            try {
+                                const sEntries = fs.readdirSync(skillDir, { withFileTypes: true });
+                                for (const se of sEntries) {
+                                    if (se.isDirectory() && fs.existsSync(path.join(skillDir, se.name, 'SKILL.md'))) {
+                                        skills.push(se.name);
+                                    }
+                                }
+                            }
+                            catch { }
+                        }
+                        // Inspect MCP servers in mcp.json
+                        const mcpPath = path.join(candidatePath, 'mcp.json');
+                        const mcpServers = [];
+                        if (fs.existsSync(mcpPath)) {
+                            try {
+                                const mcpDoc = JSON.parse(fs.readFileSync(mcpPath, 'utf-8'));
+                                if (mcpDoc.mcpServers) {
+                                    mcpServers.push(...Object.keys(mcpDoc.mcpServers));
+                                }
+                            }
+                            catch { }
+                        }
+                        localResults.push({
+                            name: pName,
+                            version: manifest.version || '1.0.0',
+                            description: pDesc,
+                            isLoaded: this.plugins.has(pName),
+                            path: candidatePath,
+                            skills,
+                            mcpServers,
+                        });
+                    }
+                    catch { }
+                }
+            }
+        }
+        // 2. Scan Remote & Curated Ecosystem Plugins
+        if (source === 'all' || source === 'remote') {
+            const CURATED_PLUGINS = [
+                {
+                    name: 'agent-plugins-example',
+                    description: 'Official Agent Plugins reference implementation featuring Agent Skills and stdio MCP servers.',
+                    repository: 'https://github.com/agentplugins/agent-plugins-example',
+                    url: 'https://agent-plugins.org/',
+                    author: 'Agent Plugins Core Maintainers (Amazon, Cursor, Microsoft, OpenAI, Vercel)',
+                    keywords: ['example', 'reference', 'skills', 'mcp', 'stdio', 'agent-plugins'],
+                    official: true,
+                },
+                {
+                    name: 'agent-plugins-spec',
+                    description: 'The complete normative contract, JSON schemas, and technical specifications for Agent Plugins 1.0.0.',
+                    repository: 'https://github.com/agentplugins/agent-plugins-spec',
+                    url: 'https://agent-plugins.org/specification',
+                    author: 'Agent Plugins Technical Steering Committee',
+                    keywords: ['specification', 'spec', 'schemas', 'standards', 'agent-plugins'],
+                    official: true,
+                },
+                {
+                    name: 'agent-plugins-site',
+                    description: 'Documentation, guides, and compatible client catalog for Agent Plugins.',
+                    repository: 'https://github.com/agentplugins/agent-plugins-site',
+                    url: 'https://agent-plugins.org/',
+                    author: 'Agent Plugins Documentation Contributors',
+                    keywords: ['docs', 'documentation', 'compatible-clients', 'agent-plugins'],
+                    official: true,
+                },
+                {
+                    name: 'example-calc',
+                    description: 'Calculator and math service demonstrating Agent Skills and MCP stdio tools in Musonda.',
+                    repository: 'https://github.com/agentplugins',
+                    url: 'https://agent-plugins.org/',
+                    author: 'Musonda Team',
+                    keywords: ['calculator', 'math', 'stdio', 'mcp', 'tools'],
+                    official: true,
+                },
+                {
+                    name: 'plugin-builder',
+                    description: 'Meta-plugin providing guidelines, schemas, and skills for authoring, scaffolding, and dynamically managing Agent Plugins.',
+                    repository: 'https://github.com/agentplugins',
+                    url: 'https://agent-plugins.org/',
+                    author: 'Musonda Team',
+                    keywords: ['builder', 'authoring', 'management', 'developer-tools', 'scaffolding'],
+                    official: true,
+                },
+            ];
+            const seenRepos = new Set();
+            // Filter curated list
+            for (const p of CURATED_PLUGINS) {
+                seenRepos.add(p.repository.toLowerCase());
+                if (!query ||
+                    p.name.toLowerCase().includes(query) ||
+                    p.description.toLowerCase().includes(query) ||
+                    p.keywords.some((k) => k.toLowerCase().includes(query))) {
+                    remoteResults.push({
+                        ...p,
+                        isInstalled: this.plugins.has(p.name),
+                    });
+                }
+            }
+            // Query GitHub Search API for topic:agent-plugin
+            if (query) {
+                try {
+                    const ghRes = await fetch(`https://api.github.com/search/repositories?q=topic:agent-plugin+${encodeURIComponent(query)}&per_page=5`, {
+                        headers: {
+                            'User-Agent': 'Musonda-Gateway/1.0.0',
+                            Accept: 'application/vnd.github.v3+json',
+                        },
+                        signal: AbortSignal.timeout(3500),
+                    });
+                    if (ghRes.ok) {
+                        const data = await ghRes.json();
+                        if (data.items && Array.isArray(data.items)) {
+                            for (const item of data.items) {
+                                const repoUrl = (item.html_url || '').toLowerCase();
+                                if (seenRepos.has(repoUrl))
+                                    continue;
+                                seenRepos.add(repoUrl);
+                                remoteResults.push({
+                                    name: item.name,
+                                    description: item.description || '',
+                                    repository: item.html_url,
+                                    url: item.homepage || item.html_url,
+                                    author: item.owner?.login || '',
+                                    keywords: item.topics || ['agent-plugin'],
+                                    official: item.owner?.login === 'agentplugins',
+                                    isInstalled: this.plugins.has(item.name),
+                                });
+                            }
+                        }
+                    }
+                }
+                catch {
+                    // Graceful fallback if network is offline
+                }
+            }
+        }
+        return {
+            query: query || undefined,
+            totalFound: localResults.length + remoteResults.length,
+            local: localResults,
+            remote: remoteResults,
+        };
+    }
+    /**
+     * Returns detailed inspection information for a specific plugin.
+     */
+    getPluginInfo(pluginNameOrPath) {
+        const raw = pluginNameOrPath?.trim();
+        if (!raw) {
+            return {
+                found: false,
+                isLoaded: false,
+                skills: [],
+                mcpServers: [],
+                error: 'Missing plugin identifier or path.',
+            };
+        }
+        let rootDir;
+        const loaded = this.plugins.get(raw);
+        if (loaded) {
+            rootDir = loaded.rootDir;
+        }
+        else {
+            const candidateLocal = path.resolve(raw);
+            if (fs.existsSync(candidateLocal) && fs.statSync(candidateLocal).isDirectory()) {
+                rootDir = candidateLocal;
+            }
+            else {
+                const pluginsConfig = this.config.plugins;
+                const searchDirs = pluginsConfig?.directories || ['./data/plugins', './plugins'];
+                for (const sDir of searchDirs) {
+                    const cand = path.resolve(sDir, raw);
+                    if (fs.existsSync(cand)) {
+                        rootDir = cand;
+                        break;
+                    }
+                }
+            }
+        }
+        if (!rootDir || !fs.existsSync(rootDir)) {
+            return {
+                found: false,
+                isLoaded: false,
+                skills: [],
+                mcpServers: [],
+                error: `Plugin "${raw}" not found in loaded plugins or on disk.`,
+            };
+        }
+        const manifestPath = path.join(rootDir, 'plugin.json');
+        if (!fs.existsSync(manifestPath)) {
+            return {
+                found: false,
+                isLoaded: false,
+                skills: [],
+                mcpServers: [],
+                error: `Directory "${rootDir}" does not contain a valid plugin.json manifest.`,
+            };
+        }
+        let manifest;
+        try {
+            manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+        }
+        catch (err) {
+            return {
+                found: false,
+                isLoaded: false,
+                skills: [],
+                mcpServers: [],
+                error: `Could not parse plugin.json: ${err.message}`,
+            };
+        }
+        const pluginName = manifest.name || path.basename(rootDir);
+        const isLoaded = this.plugins.has(pluginName);
+        // Read skills
+        const skillsList = [];
+        const skillsDir = path.join(rootDir, 'skills');
+        if (fs.existsSync(skillsDir)) {
+            try {
+                const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+                for (const entry of entries) {
+                    if (!entry.isDirectory())
+                        continue;
+                    const skillFile = path.join(skillsDir, entry.name, 'SKILL.md');
+                    if (fs.existsSync(skillFile)) {
+                        try {
+                            const content = fs.readFileSync(skillFile, 'utf-8');
+                            const parsed = SkillFrontmatterParser.parse(content, entry.name);
+                            const summary = parsed.body.slice(0, 150).replace(/\n+/g, ' ');
+                            skillsList.push({
+                                name: parsed.frontmatter.name || entry.name,
+                                description: parsed.frontmatter.description || '',
+                                instructionsSummary: summary ? summary + '...' : undefined,
+                            });
+                        }
+                        catch { }
+                    }
+                }
+            }
+            catch { }
+        }
+        // Read MCP servers
+        const mcpServersList = [];
+        const mcpPath = path.join(rootDir, 'mcp.json');
+        if (fs.existsSync(mcpPath)) {
+            try {
+                const mcpDoc = JSON.parse(fs.readFileSync(mcpPath, 'utf-8'));
+                if (mcpDoc.mcpServers) {
+                    for (const [sName, sCfg] of Object.entries(mcpDoc.mcpServers)) {
+                        mcpServersList.push({
+                            name: sName,
+                            type: sCfg.type,
+                            command: sCfg.command,
+                            url: sCfg.url,
+                        });
+                    }
+                }
+            }
+            catch { }
+        }
+        // Active bridged tools if currently loaded
+        const activeServers = this.mcpBridge.getActiveServers().filter((s) => s.server.pluginName === pluginName);
+        const activeTools = activeServers.flatMap((s) => s.tools.map((t) => t.name));
+        return {
+            found: true,
+            isLoaded,
+            manifest,
+            rootDir,
+            dataDir: loaded?.dataDir || path.resolve(this.config.plugins?.dataDir || './data/plugin_data', pluginName),
+            skills: skillsList,
+            mcpServers: mcpServersList,
+            activeTools,
+        };
+    }
+    /**
+     * Shuts down all active plugin resources (MCP subprocesses).
+     */
+    async shutdownAll() {
+        await this.mcpBridge.shutdown();
+        this.plugins.clear();
+        this.skills = [];
+        this.isLoaded = false;
+    }
+}
+//# sourceMappingURL=pluginManager.js.map