wave-agent-sdk 1.2.0 → 1.3.0

package/dist/managers/pluginManager.js

@@ -4,10 +4,27 @@ import * as path from "path";
 import { existsSync, readdirSync } from "fs";
 import { getBuiltinPluginsDir } from "../utils/configPaths.js";
 import { MarketplaceService } from "../services/MarketplaceService.js";
+import { DEFAULT_PLUGIN_VERSION } from "../constants/plugins.js";
 export class PluginManager {
+    serialize(task) {
+        const result = this.loadChain.then(task, task);
+        // Keep the chain alive after a failure so later reloads still run.
+        this.loadChain = result.then(() => undefined, () => undefined);
+        return result;
+    }
     constructor(container, options) {
         this.container = container;
         this.plugins = new Map();
+        /** Explicit configs from the last load, replayed by reloadAllPlugins(). */
+        this.lastLoadConfigs = [];
+        /** Failures collected by the current loadPlugins() run. */
+        this.loadFailures = [];
+        /**
+         * Serializes plugin (re)loads. A managed-settings sync (or an early
+         * `/reload-plugins`) can ask for a reload while the startup load is still
+         * running; interleaving them would leave half-unloaded capability registries.
+         */
+        this.loadChain = Promise.resolve();
         this.workdir = options.workdir;
         this.enabledPlugins = options.enabledPlugins || {};
     }
@@ -51,12 +68,6 @@ export class PluginManager {
                 this.enabledPlugins = this.configurationService.getMergedEnabledPlugins(this.workdir);
             }
             const marketplaceService = new MarketplaceService(this.workdir, this.configurationService);
-            // Trigger auto-update for marketplaces in the background
-            if (!process.env.VITEST) {
-                marketplaceService.autoUpdateAll().catch((error) => {
-                    logger?.error("Background marketplace auto-update failed:", error);
-                });
-            }
             let installedRegistry = await marketplaceService.getInstalledPlugins();
             const knownMarketplaces = await marketplaceService.listMarketplaces();
             // Identify missing enabled plugins and auto-install them if marketplace is known
@@ -74,7 +85,7 @@ export class PluginManager {
                     const isMarketplaceKnown = knownMarketplaces.some((m) => m.name === marketplaceName);
                     if (isMarketplaceKnown) {
                         // Pre-check: verify the plugin still exists in the marketplace manifest
-                        // before acquiring the lock in installPlugin (which can block ~8s during autoUpdate)
+                        // before acquiring the lock in installPlugin (which can block ~8s during a marketplace refresh)
                         const marketplace = knownMarketplaces.find((m) => m.name === marketplaceName);
                         if (!marketplace)
                             continue;
@@ -119,12 +130,18 @@ export class PluginManager {
             }
             // Refresh registry after potential auto-installs
             installedRegistry = await marketplaceService.getInstalledPlugins();
+            // 同一插件在本机可能有多条安装记录（各作用域/各项目各一条，spec plugin
+            // A-015）；按插件去重，否则同一个 cachePath 会被加载多次。
+            const loaded = new Set();
             for (const p of installedRegistry.plugins) {
                 const pluginId = `${p.name}@${p.marketplace}`;
                 if (this.enabledPlugins[pluginId] !== true) {
                     logger?.debug(`Plugin ${pluginId} is not enabled via configuration`);
                     continue;
                 }
+                if (loaded.has(pluginId))
+                    continue;
+                loaded.add(pluginId);
                 await this.loadSinglePlugin(p.cachePath);
             }
         }
@@ -145,12 +162,15 @@ export class PluginManager {
             }
             const plugin = {
                 ...manifest,
+                // A manifest without `version` is legal (spec plugin A-022); the default
+                // matches what the install path files under `installed_plugins.json`.
+                version: manifest.version || DEFAULT_PLUGIN_VERSION,
                 path: absolutePath,
                 commands: PluginLoader.loadCommands(absolutePath),
                 skills: await PluginLoader.loadSkills(absolutePath),
                 agents: await PluginLoader.loadAgents(absolutePath),
                 lspConfig: await PluginLoader.loadLspConfig(absolutePath),
-                mcpConfig: await PluginLoader.loadMcpConfig(absolutePath),
+                mcpConfig: await PluginLoader.loadMcpConfig(absolutePath, manifest.mcpServers),
                 hooksConfig: await PluginLoader.loadHooksConfig(absolutePath),
             };
             // Register components with managers
@@ -168,8 +188,15 @@ export class PluginManager {
             }
             if (this.mcpManager && plugin.mcpConfig) {
                 for (const [name, config] of Object.entries(plugin.mcpConfig.mcpServers)) {
-                    const configWithPluginRoot = { ...config, pluginRoot: plugin.path };
-                    this.mcpManager.addServer(name, configWithPluginRoot);
+                    // One unusable server declaration must not take the rest of the plugin
+                    // down with it (spec plugin A-023).
+                    try {
+                        const configWithPluginRoot = { ...config, pluginRoot: plugin.path };
+                        this.mcpManager.addServer(name, configWithPluginRoot);
+                    }
+                    catch (error) {
+                        logger?.warn(`Failed to register MCP server '${name}' from plugin ${plugin.name}: ${error instanceof Error ? error.message : String(error)}`);
+                    }
                 }
             }
             if (this.hookManager && plugin.hooksConfig) {
@@ -179,17 +206,31 @@ export class PluginManager {
                 this.subagentManager.registerPluginAgents(plugin.name, plugin.agents);
             }
             this.plugins.set(manifest.name, plugin);
-            logger?.debug(`Loaded plugin: ${manifest.name} v${manifest.version}`);
+            logger?.debug(`Loaded plugin: ${manifest.name} v${plugin.version}`);
         }
         catch (error) {
+            this.loadFailures.push({
+                path: absolutePath,
+                error: error instanceof Error ? error.message : String(error),
+            });
             logger?.error(`Failed to load plugin from ${absolutePath}`, error);
         }
     }
     /**
      * Load plugins from configuration
      * @param configs Array of plugin configurations
+     * @returns the plugins that failed to load
      */
     async loadPlugins(configs) {
+        return this.serialize(() => this.doLoadPlugins(configs));
+    }
+    /**
+     * The actual load. Reached through [loadPlugins] (which serializes concurrent
+     * requests) and directly from [reloadAllPlugins], which already holds the slot.
+     */
+    async doLoadPlugins(configs) {
+        this.lastLoadConfigs = configs;
+        this.loadFailures = [];
         // Load plugins from configuration (e.g. --plugin-dir) first to give them higher priority
         for (const config of configs) {
             if (config.type !== "local") {
@@ -205,6 +246,71 @@ export class PluginManager {
         await this.loadInstalledPlugins();
         // Load built-in plugins bundled with the SDK (lowest priority)
         await this.loadBuiltinPlugins();
+        return [...this.loadFailures];
+    }
+    /**
+     * Unload a single plugin: drop everything it contributed from the six
+     * capability registries, then forget it. Other plugins and the running
+     * session are untouched.
+     * @returns true if the plugin was loaded
+     */
+    async unloadPlugin(name) {
+        const plugin = this.plugins.get(name);
+        if (!plugin) {
+            return false;
+        }
+        // Managers key their entries off the plugin name (commands/skills/agents)
+        // or the plugin root path (hooks/LSP/MCP), so each needs its own removal.
+        this.slashCommandManager?.unregisterPluginCommands(plugin.name);
+        this.skillManager?.unregisterPluginSkills(plugin.name);
+        this.subagentManager?.unregisterPluginAgents(plugin.name);
+        this.hookManager?.unregisterPluginHooks(plugin.path);
+        await this.lspManager?.unregisterServersForPlugin(plugin.path);
+        this.mcpManager?.removeServersForPlugin(plugin.path);
+        // Revoke the builtin helper-script grants this plugin added, so disabling
+        // it does not leave a standing permission behind.
+        for (const rule of PluginManager.BUILTIN_PLUGIN_ALLOW_RULES[plugin.name] ||
+            []) {
+            this.permissionManager?.removeInstanceAllowedRule(rule);
+        }
+        this.plugins.delete(name);
+        logger?.debug(`Unloaded plugin: ${name}`);
+        return true;
+    }
+    /**
+     * Re-read every plugin in place — the `/reload-plugins` command.
+     *
+     * Unloads everything currently loaded, re-reads `enabledPlugins` from the
+     * configuration chain (so a settings edit is honored), then replays the
+     * original load order (explicit configs → installed → builtin). The session,
+     * transcript and sessionId are untouched; only the capability registries are
+     * swapped, which is what makes this an in-place reload instead of a rebuild.
+     *
+     * Unload must happen before any caller-side mutation of the plugin cache dir:
+     * hooks, MCP, LSP, skills and agents all bake absolute plugin paths at
+     * registration time, so an entry left pointing at a deleted directory is
+     * worse than a merely stale one.
+     */
+    async reloadAllPlugins() {
+        return this.serialize(async () => {
+            for (const name of Array.from(this.plugins.keys())) {
+                await this.unloadPlugin(name);
+            }
+            this.enabledPlugins = this.refreshEnabledPlugins();
+            const failures = await this.doLoadPlugins(this.lastLoadConfigs);
+            return {
+                plugins: Array.from(this.plugins.keys()),
+                failures,
+            };
+        });
+    }
+    /**
+     * Re-read enabled plugins from the merged configuration chain, falling back
+     * to the last known value when the service is unavailable.
+     */
+    refreshEnabledPlugins() {
+        const merged = this.configurationService?.getMergedEnabledPlugins(this.workdir);
+        return merged ?? this.enabledPlugins;
     }
     /**
      * Load built-in plugins bundled with the SDK (e.g. sdd).

package/dist/managers/pluginScopeManager.d.ts

@@ -1,6 +1,6 @@
 import { ConfigurationService } from "../services/configurationService.js";
 import { PluginManager } from "./pluginManager.js";
-import { Logger } from "../types/index.js";
+import { Logger, PluginInstallLocation } from "../types/index.js";
 import { Scope } from "../types/configuration.js";
 export interface PluginScopeManagerOptions {
     workdir: string;
@@ -31,9 +31,22 @@ export declare class PluginScopeManager {
      * Priority: local > project > user
      */
     findPluginScope(pluginId: string): Scope | null;
+    /**
+     * The install location a record for `scope` is keyed by (spec plugin A-015):
+     * 用户作用域是本机全局的（不带 projectPath），项目/本地作用域归属当前仓库。
+     */
+    getInstallLocation(scope: Scope): PluginInstallLocation;
+    /**
+     * Remove a plugin's enabled record from a single scope, leaving every other
+     * scope (including other projects' project/local records) untouched — the
+     * uninstall semantics of spec plugin A-015. Use [removePluginFromAllScopes]
+     * only for 「更换安装作用域」.
+     */
+    removePluginFromScope(scope: Scope, pluginId: string): Promise<void>;
     /**
      * Remove a plugin from all scopes (user, project, local)
-     * This is useful when uninstalling a plugin to clean up all configuration
+     * This is useful when moving a plugin to another scope: the old scope must
+     * not keep the plugin (spec plugin「设置页插件市场」场景 11).
      */
     removePluginFromAllScopes(pluginId: string): Promise<void>;
     /**

package/dist/managers/pluginScopeManager.js

@@ -56,9 +56,28 @@ export class PluginScopeManager {
         }
         return null;
     }
+    /**
+     * The install location a record for `scope` is keyed by (spec plugin A-015):
+     * 用户作用域是本机全局的（不带 projectPath），项目/本地作用域归属当前仓库。
+     */
+    getInstallLocation(scope) {
+        return scope === "user" ? { scope } : { scope, projectPath: this.workdir };
+    }
+    /**
+     * Remove a plugin's enabled record from a single scope, leaving every other
+     * scope (including other projects' project/local records) untouched — the
+     * uninstall semantics of spec plugin A-015. Use [removePluginFromAllScopes]
+     * only for 「更换安装作用域」.
+     */
+    async removePluginFromScope(scope, pluginId) {
+        await this.configurationService.removeEnabledPlugin(this.workdir, scope, pluginId);
+        this.logger?.info(`Removed plugin ${pluginId} from ${scope} scope`);
+        this.refreshPluginManager();
+    }
     /**
      * Remove a plugin from all scopes (user, project, local)
-     * This is useful when uninstalling a plugin to clean up all configuration
+     * This is useful when moving a plugin to another scope: the old scope must
+     * not keep the plugin (spec plugin「设置页插件市场」场景 11).
      */
     async removePluginFromAllScopes(pluginId) {
         const scopes = ["user", "project", "local"];

package/dist/managers/skillManager.d.ts

@@ -103,6 +103,17 @@ export declare class SkillManager extends EventEmitter {
         content: string;
         skill?: undefined;
     }>;
+    /**
+     * Render a skill's body the way the model must see it: frontmatter stripped,
+     * parameters substituted, `${WAVE_SKILL_DIR}` / `${CLAUDE_SKILL_DIR}` /
+     * `${WAVE_PLUGIN_ROOT}` replaced with real paths, and the
+     * `Base directory for this skill: <path>` header prepended.
+     *
+     * Public because the post-compaction re-injection has to render the same
+     * text when it cannot reuse the content recorded at invocation time
+     * (spec core/message-compact 场景 4).
+     */
+    renderSkillContent(skill: Skill, argsString?: string): string;
     /**
      * Prepare skill content with arguments but without bash execution
      */
@@ -119,6 +130,14 @@ export declare class SkillManager extends EventEmitter {
      * Register skills provided by a plugin
      */
     registerPluginSkills(pluginName: string, skills: Skill[]): void;
+    /**
+     * Drop every skill contributed by a plugin, addressed by its plugin name.
+     * Clears the plugin-specific maps too: refreshSkills() re-seeds the visible
+     * maps from them, so clearing only those would resurrect the skills on the
+     * next disk refresh. Called by the in-place plugin reload path before
+     * re-registering.
+     */
+    unregisterPluginSkills(pluginName: string): void;
     /**
      * Directory roots that may hold deletable copies of a skill in the given
      * discovery scope. Personal skills are scanned from three user-level dirs

package/dist/managers/skillManager.js

@@ -422,6 +422,19 @@ export class SkillManager extends EventEmitter {
             };
         }
     }
+    /**
+     * Render a skill's body the way the model must see it: frontmatter stripped,
+     * parameters substituted, `${WAVE_SKILL_DIR}` / `${CLAUDE_SKILL_DIR}` /
+     * `${WAVE_PLUGIN_ROOT}` replaced with real paths, and the
+     * `Base directory for this skill: <path>` header prepended.
+     *
+     * Public because the post-compaction re-injection has to render the same
+     * text when it cannot reuse the content recorded at invocation time
+     * (spec core/message-compact 场景 4).
+     */
+    renderSkillContent(skill, argsString = "") {
+        return this.prepareSkillContent(skill, argsString);
+    }
     /**
      * Prepare skill content with arguments but without bash execution
      */
@@ -496,6 +509,37 @@ export class SkillManager extends EventEmitter {
         }
         logger?.debug(`Registered ${skills.length} plugin skills from ${pluginName}. Total skills: ${this.skillMetadata.size}`);
     }
+    /**
+     * Drop every skill contributed by a plugin, addressed by its plugin name.
+     * Clears the plugin-specific maps too: refreshSkills() re-seeds the visible
+     * maps from them, so clearing only those would resurrect the skills on the
+     * next disk refresh. Called by the in-place plugin reload path before
+     * re-registering.
+     */
+    unregisterPluginSkills(pluginName) {
+        const prefix = `${pluginName}:`;
+        for (const name of Array.from(this.pluginSkillMetadata.keys())) {
+            if (name.startsWith(prefix)) {
+                this.pluginSkillMetadata.delete(name);
+            }
+        }
+        for (const name of Array.from(this.pluginSkillContent.keys())) {
+            if (name.startsWith(prefix)) {
+                this.pluginSkillContent.delete(name);
+            }
+        }
+        for (const name of Array.from(this.skillMetadata.keys())) {
+            if (name.startsWith(prefix)) {
+                this.skillMetadata.delete(name);
+            }
+        }
+        for (const name of Array.from(this.skillContent.keys())) {
+            if (name.startsWith(prefix)) {
+                this.skillContent.delete(name);
+            }
+        }
+        logger?.debug(`Unregistered plugin skills from ${pluginName}`);
+    }
     /**
      * Directory roots that may hold deletable copies of a skill in the given
      * discovery scope. Personal skills are scanned from three user-level dirs

package/dist/managers/slashCommandManager.d.ts

@@ -9,6 +9,9 @@ export declare class SlashCommandManager {
     private commands;
     private customCommands;
     private skillCommandIds;
+    /** Ids registered by plugins, so they can be dropped per-plugin and are not
+     * mistaken for disk-sourced custom commands. */
+    private pluginCommandIds;
     private workdir;
     private currentCommandAbortController;
     constructor(container: Container, options: SlashCommandManagerOptions);
@@ -29,6 +32,13 @@ export declare class SlashCommandManager {
      * Register commands from a plugin with namespacing
      */
     registerPluginCommands(pluginName: string, commands: CustomSlashCommand[]): void;
+    /**
+     * Drop every slash command contributed by a plugin, addressed by its plugin
+     * name. Removes the registry entry and the customCommands source entry.
+     * Called by the in-place plugin reload path before re-registering.
+     * @returns the number of commands removed
+     */
+    unregisterPluginCommands(pluginName: string): number;
     /**
      * Reload custom commands (useful for development)
      */

package/dist/managers/slashCommandManager.js

@@ -9,6 +9,9 @@ export class SlashCommandManager {
         this.commands = new Map();
         this.customCommands = new Map();
         this.skillCommandIds = new Set();
+        /** Ids registered by plugins, so they can be dropped per-plugin and are not
+         * mistaken for disk-sourced custom commands. */
+        this.pluginCommandIds = new Set();
         this.currentCommandAbortController = null;
         this.workdir = options.workdir;
     }
@@ -233,6 +236,7 @@ export class SlashCommandManager {
             const namespacedId = `${pluginName}:${command.id}`;
             const namespacedName = `${pluginName}:${command.name}`;
             this.customCommands.set(namespacedId, command);
+            this.pluginCommandIds.add(namespacedId);
             // Generate description: prioritize custom description, otherwise use default description
             const description = command.description ||
                 `Plugin command: ${namespacedName}${hasParameterPlaceholders(command.content) ? " (supports parameters)" : ""}`;
@@ -252,15 +256,43 @@ export class SlashCommandManager {
         }
         logger?.debug(`Registered ${commands.length} commands from plugin '${pluginName}'`);
     }
+    /**
+     * Drop every slash command contributed by a plugin, addressed by its plugin
+     * name. Removes the registry entry and the customCommands source entry.
+     * Called by the in-place plugin reload path before re-registering.
+     * @returns the number of commands removed
+     */
+    unregisterPluginCommands(pluginName) {
+        const prefix = `${pluginName}:`;
+        let removed = 0;
+        for (const commandId of Array.from(this.pluginCommandIds)) {
+            if (!commandId.startsWith(prefix)) {
+                continue;
+            }
+            this.pluginCommandIds.delete(commandId);
+            this.customCommands.delete(commandId);
+            this.unregisterCommand(commandId);
+            removed += 1;
+        }
+        if (removed > 0) {
+            logger?.debug(`Unregistered ${removed} commands from plugin '${pluginName}'`);
+        }
+        return removed;
+    }
     /**
      * Reload custom commands (useful for development)
      */
     reloadCustomCommands() {
-        // Clear existing custom commands
-        for (const commandId of this.customCommands.keys()) {
+        // Reload only disk-sourced custom commands. Plugin commands live in the
+        // same map but are owned by the plugin lifecycle, so re-reading the disk
+        // must not drop them.
+        for (const [commandId] of this.customCommands) {
+            if (this.pluginCommandIds.has(commandId)) {
+                continue;
+            }
             this.unregisterCommand(commandId);
+            this.customCommands.delete(commandId);
         }
-        this.customCommands.clear();
         // Reload
         this.loadCustomCommands();
     }

package/dist/managers/subagentManager.d.ts

@@ -120,6 +120,14 @@ export declare class SubagentManager {
      * Names each agent as `pluginName:agentName` to avoid collisions.
      */
     registerPluginAgents(pluginName: string, agents: SubagentConfiguration[]): void;
+    /**
+     * Drop every subagent contributed by a plugin, addressed by its plugin name.
+     * Running instances are deliberately left alone — an in-place reload must not
+     * interrupt work already in flight. Called by the plugin reload path before
+     * re-registering.
+     * @returns the number of configurations removed
+     */
+    unregisterPluginAgents(pluginName: string): number;
     /**
      * Create a new subagent instance with isolated managers
      */

package/dist/managers/subagentManager.js

@@ -183,6 +183,22 @@ export class SubagentManager {
             return a.name.localeCompare(b.name);
         });
     }
+    /**
+     * Drop every subagent contributed by a plugin, addressed by its plugin name.
+     * Running instances are deliberately left alone — an in-place reload must not
+     * interrupt work already in flight. Called by the plugin reload path before
+     * re-registering.
+     * @returns the number of configurations removed
+     */
+    unregisterPluginAgents(pluginName) {
+        if (this.cachedConfigurations === null) {
+            return 0;
+        }
+        const prefix = `${pluginName}:`;
+        const before = this.cachedConfigurations.length;
+        this.cachedConfigurations = this.cachedConfigurations.filter((config) => !config.name.startsWith(prefix));
+        return before - this.cachedConfigurations.length;
+    }
     /**
      * Create a new subagent instance with isolated managers
      */
@@ -232,6 +248,10 @@ export class SubagentManager {
         const subagentPermissionManager = new PermissionManager(subagentContainer, {
             configuredPermissionMode: parameters.permissionModeOverride ??
                 parentPermissionManager?.getConfiguredPermissionMode(),
+            // Inherit the parent session's bypass authorization: the subagent is
+            // created mid-session, so re-deriving it from its own mode would
+            // (wrongly) deny an authorized session's plan-mode subagent.
+            bypassAuthorization: parentPermissionManager?.getBypassAuthorization?.(),
             allowedRules: parentPermissionManager?.getAllowedRules(),
             deniedRules: parentPermissionManager?.getDeniedRules(),
             instanceAllowedRules: parentPermissionManager?.getInstanceAllowedRules?.(),

package/dist/managers/toolManager.d.ts

@@ -1,4 +1,5 @@
 import type { ToolContext, ToolPlugin, ToolResult } from "../tools/types.js";
+import type { RenderedCatalog } from "../exec/catalog.js";
 import { PermissionManager } from "./permissionManager.js";
 import { ChatCompletionFunctionTool } from "openai/resources.js";
 import type { PermissionMode } from "../types/index.js";
@@ -56,15 +57,21 @@ declare class ToolManager {
     /**
      * Re-evaluate feature-gated built-in tools after a live configuration
      * reload. Currently gates the Artifact tool on settings.json
-     * `enableArtifact`. Safe to call multiple times: gated tools are removed
-     * from the registry first, then initializeBuiltInTools() re-registers them
-     * only if still enabled (so toggling the flag off actually unregisters).
+     * `enableArtifact` and the Exec tool on `enableExec`. Safe to call multiple
+     * times: gated tools are removed from the registry first, then
+     * initializeBuiltInTools() re-registers them only if still enabled (so
+     * toggling a flag off actually unregisters).
      */
     reloadFeatureGatedTools(): void;
     /**
      * Check if a tool should be enabled based on tools configuration and permission rules
      */
     private shouldEnableTool;
+    /**
+     * The auto-memory directory for this session, or undefined when the feature
+     * is off. Consumers (Read) treat "unset" as "not a memory file".
+     */
+    private resolveAutoMemoryDir;
     /**
      * Execute a tool by name with the provided arguments and context
      *
@@ -80,6 +87,25 @@ declare class ToolManager {
      */
     execute(name: string, args: Record<string, unknown>, context: ToolContext): Promise<ToolResult>;
     list(): ToolPlugin[];
+    /**
+     * Whether `Exec` is declared at all: registered and not denied. Exactly when the
+     * catalog channel is open — an undeclared `Exec` cannot be called, so a catalog
+     * for it would advertise a way in that does not exist.
+     */
+    private isExecDeclared;
+    /** The tools the sandbox may reach — the pool the flat declarations give up. */
+    private execPool;
+    /**
+     * The MCP catalog as the model is meant to see it, or `undefined` when the
+     * catalog channel is closed.
+     *
+     * A function of the pool alone, and computed per call: with the catalog out of
+     * `tools[]` the declaration no longer moves when a server comes or goes, and the
+     * announcement channel diffs this against the history. Caching the rendering would
+     * mean caching pool state, which is exactly the process-side bookkeeping the
+     * channel is built to avoid.
+     */
+    getExecCatalog(): RenderedCatalog | undefined;
     getToolsConfig(options?: {
         availableSubagents?: SubagentConfiguration[];
         availableSkills?: SkillMetadata[];