wave-agent-sdk 1.1.5 → 1.3.0

package/dist/core/plugin.d.ts

@@ -14,13 +14,24 @@ export declare class PluginCore {
     private workdir;
     constructor(workdir?: string);
     /**
-     * Installs a plugin from a marketplace
+     * Installs a plugin from a marketplace and, when a scope is given, enables it
+     * there — the install record is filed under that same scope (spec plugin A-015).
      */
     installPlugin(pluginId: string, scope?: Scope): Promise<InstalledPlugin>;
     /**
-     * Uninstalls a plugin and removes it from all configuration scopes
+     * Managed plugins are the ones the organization pushed through remote managed
+     * settings: a member cannot uninstall or disable them (spec plugin A-024).
+     * The check reads the managed layer only — a plugin the admin never mentioned
+     * stays the user's to manage, and dropping the entry restores that at once.
      */
-    uninstallPlugin(pluginId: string): Promise<void>;
+    private assertNotManaged;
+    /**
+     * Uninstalls a plugin from a single scope (spec plugin A-015)：只清除该作用域的
+     * 启用记录与该作用域的安装记录，其它作用域（含其它项目的项目/本地作用域）不受
+     * 影响；本机产物仅在该插件再无安装记录时删除。未指定作用域时按
+     * `local` > `project` > `user` 探测当前生效作用域（与 enable/disable 一致）。
+     */
+    uninstallPlugin(pluginId: string, scope?: Scope): Promise<Scope>;
     /**
      * Enables a plugin in the specified scope. If no scope is provided, it tries to find
      * the scope where the plugin is already configured, or defaults to "user".
@@ -32,20 +43,32 @@ export declare class PluginCore {
      */
     disablePlugin(pluginId: string, scope?: Scope): Promise<Scope>;
     /**
-     * Updates an installed plugin to the latest version from its marketplace
+     * Moves an installed plugin to another installation scope: clears its
+     * enabledPlugins record from every scope, then enables it in the target one
+     * (spec plugin「设置页插件市场」场景 11：更换作用域后旧作用域不再保留该插件)。
+     * The install record follows the plugin, otherwise uninstalling it at the new
+     * scope would find no record there (spec plugin A-015)。
      */
-    updatePlugin(pluginId: string): Promise<InstalledPlugin>;
+    setPluginScope(pluginId: string, scope: Scope): Promise<Scope>;
     /**
-     * Toggles auto-update for a marketplace
+     * Updates an installed plugin to the latest version from its marketplace
      */
-    toggleAutoUpdate(name: string, enabled: boolean): Promise<void>;
+    updatePlugin(pluginId: string): Promise<InstalledPlugin>;
     /**
-     * Lists all plugins from all registered marketplaces with their installation and enabled status
+     * Lists all plugins from all registered marketplaces with their installation and enabled status.
      */
     listPlugins(): Promise<{
         plugins: MarketplacePluginStatus[];
         mergedEnabled: Record<string, boolean>;
     }>;
+    /**
+     * Reads the version declared by a marketplace plugin's own manifest inside the
+     * marketplace checkout — the version a fresh install would get. Sources that
+     * live outside the checkout (Git URLs and both object shapes, which always point
+     * at an external repository) have no local copy until install, so they yield
+     * undefined (spec plugin A-010 / A-021).
+     */
+    private readLatestVersion;
     /**
      * Adds a new marketplace
      */
@@ -55,9 +78,30 @@ export declare class PluginCore {
      */
     removeMarketplace(name: string, scope?: Scope): Promise<void>;
     /**
-     * Updates a specific marketplace or all marketplaces
+     * Updates a specific marketplace or all marketplaces: refreshes the checkout
+     * from its upstream and reinstalls any plugins that are already installed from
+     * it (mirrors Claude Code's refresh-and-bump).
+     *
+     * 无界面可依赖的入口（非交互命令 `wave plugin marketplace update`）走这里；
+     * 交互界面的「批量更新插件」走 [updateMarketplacePlugins]（不拉检出）。
+     *
+     * @returns 实际发生版本变化的插件数量（0 = 全部已是最新），供 GUI 宿主区分提示。
+     */
+    updateMarketplace(name?: string): Promise<number>;
+    /**
+     * 批量升级某市场内已安装的插件，且不拉取检出——交互界面的「批量更新插件」
+     * （GUI 三端按钮与 CLI 插件管理器的同名项）。清单的新鲜度由打开这些界面时的
+     * 后台刷新保证（spec 插件市场 A-013、场景 14）。
+     *
+     * @returns 实际发生版本变化的插件数量（0 = 该市场已是最新），供宿主区分提示。
+     */
+    updateMarketplacePlugins(name?: string): Promise<number>;
+    /**
+     * Refreshes the checkout of every registered marketplace, without touching
+     * installed plugins. Called by hosts when the user opens a plugin
+     * marketplace surface (spec 插件市场 A-013 场景 5/13).
      */
-    updateMarketplace(name?: string): Promise<void>;
+    refreshMarketplaces(): Promise<void>;
     /**
      * Lists all registered marketplaces
      */

package/dist/core/plugin.js

@@ -1,8 +1,13 @@
 import { Container } from "../utils/container.js";
+import path from "node:path";
+import fs from "node:fs/promises";
 import { PluginManager } from "../managers/pluginManager.js";
 import { PluginScopeManager } from "../managers/pluginScopeManager.js";
 import { MarketplaceService } from "../services/MarketplaceService.js";
 import { ConfigurationService } from "../services/configurationService.js";
+import { remoteSettingsService } from "../services/remoteSettingsService.js";
+import { parsePluginSource } from "../utils/pluginSource.js";
+import { logger } from "../utils/globalLogger.js";
 /**
  * PluginCore
  *
@@ -12,6 +17,11 @@ import { ConfigurationService } from "../services/configurationService.js";
 export class PluginCore {
     constructor(workdir = process.cwd()) {
         this.workdir = workdir;
+        // 托管层（spec plugin A-024）读的是远端设置的磁盘缓存，而 `wave plugin
+        // uninstall` 这类独立命令不经过 Agent 初始化，没人调过 initialize() ⇒
+        // 缓存为空、托管限制在这些入口上形同虚设。这里补上：initialize() 只是
+        // 同步读一次 `~/.wave/remote-settings.json`（幂等），已加载过的进程不受影响。
+        remoteSettingsService.initialize();
         this.container = new Container();
         this.configurationService = new ConfigurationService();
         this.marketplaceService = new MarketplaceService(this.workdir, this.configurationService);
@@ -27,21 +37,45 @@ export class PluginCore {
         });
     }
     /**
-     * Installs a plugin from a marketplace
+     * Installs a plugin from a marketplace and, when a scope is given, enables it
+     * there — the install record is filed under that same scope (spec plugin A-015).
      */
     async installPlugin(pluginId, scope) {
-        const installedPlugin = await this.marketplaceService.installPlugin(pluginId);
+        const installedPlugin = await this.marketplaceService.installPlugin(pluginId, scope ? this.pluginScopeManager.getInstallLocation(scope) : undefined);
         if (scope) {
             await this.enablePlugin(pluginId, scope);
         }
         return installedPlugin;
     }
     /**
-     * Uninstalls a plugin and removes it from all configuration scopes
+     * Managed plugins are the ones the organization pushed through remote managed
+     * settings: a member cannot uninstall or disable them (spec plugin A-024).
+     * The check reads the managed layer only — a plugin the admin never mentioned
+     * stays the user's to manage, and dropping the entry restores that at once.
      */
-    async uninstallPlugin(pluginId) {
-        await this.marketplaceService.uninstallPlugin(pluginId);
-        await this.pluginScopeManager.removePluginFromAllScopes(pluginId);
+    assertNotManaged(pluginId, action) {
+        const managed = this.configurationService.getManagedEnabledPlugins();
+        if (!managed || !Object.prototype.hasOwnProperty.call(managed, pluginId)) {
+            return;
+        }
+        const verb = action === "uninstall" ? "uninstalled" : "disabled";
+        throw new Error(`Plugin ${pluginId} is managed by your organization and cannot be ${verb}. Contact your admin to change the managed plugin configuration.`);
+    }
+    /**
+     * Uninstalls a plugin from a single scope (spec plugin A-015)：只清除该作用域的
+     * 启用记录与该作用域的安装记录，其它作用域（含其它项目的项目/本地作用域）不受
+     * 影响；本机产物仅在该插件再无安装记录时删除。未指定作用域时按
+     * `local` > `project` > `user` 探测当前生效作用域（与 enable/disable 一致）。
+     */
+    async uninstallPlugin(pluginId, scope) {
+        this.assertNotManaged(pluginId, "uninstall");
+        const targetScope = scope ?? this.findPluginScope(pluginId);
+        if (!targetScope) {
+            throw new Error(`Plugin ${pluginId} is not enabled in any scope for ${this.workdir}. Use --scope to pick the scope to uninstall from.`);
+        }
+        await this.marketplaceService.uninstallPlugin(pluginId, this.pluginScopeManager.getInstallLocation(targetScope));
+        await this.pluginScopeManager.removePluginFromScope(targetScope, pluginId);
+        return targetScope;
     }
     /**
      * Enables a plugin in the specified scope. If no scope is provided, it tries to find
@@ -57,49 +91,77 @@ export class PluginCore {
      * the scope where the plugin is already configured, or defaults to "user".
      */
     async disablePlugin(pluginId, scope) {
+        this.assertNotManaged(pluginId, "disable");
         const targetScope = scope || this.findPluginScope(pluginId) || "user";
         await this.pluginScopeManager.disablePlugin(targetScope, pluginId);
         return targetScope;
     }
     /**
-     * Updates an installed plugin to the latest version from its marketplace
+     * Moves an installed plugin to another installation scope: clears its
+     * enabledPlugins record from every scope, then enables it in the target one
+     * (spec plugin「设置页插件市场」场景 11：更换作用域后旧作用域不再保留该插件)。
+     * The install record follows the plugin, otherwise uninstalling it at the new
+     * scope would find no record there (spec plugin A-015)。
      */
-    async updatePlugin(pluginId) {
-        return await this.marketplaceService.updatePlugin(pluginId);
+    async setPluginScope(pluginId, scope) {
+        const previousScope = this.findPluginScope(pluginId);
+        await this.pluginScopeManager.removePluginFromAllScopes(pluginId);
+        await this.pluginScopeManager.enablePlugin(scope, pluginId);
+        await this.marketplaceService.relocatePlugin(pluginId, previousScope
+            ? this.pluginScopeManager.getInstallLocation(previousScope)
+            : undefined, this.pluginScopeManager.getInstallLocation(scope));
+        return scope;
     }
     /**
-     * Toggles auto-update for a marketplace
+     * Updates an installed plugin to the latest version from its marketplace
      */
-    async toggleAutoUpdate(name, enabled) {
-        await this.marketplaceService.toggleAutoUpdate(name, enabled);
+    async updatePlugin(pluginId) {
+        return await this.marketplaceService.updatePlugin(pluginId);
     }
     /**
-     * Lists all plugins from all registered marketplaces with their installation and enabled status
+     * Lists all plugins from all registered marketplaces with their installation and enabled status.
      */
     async listPlugins() {
         const installedPlugins = await this.marketplaceService.getInstalledPlugins();
         const marketplaces = await this.marketplaceService.listMarketplaces();
         const mergedEnabled = this.configurationService.getMergedEnabledPlugins(this.workdir);
+        const managedEnabled = this.configurationService.getManagedEnabledPlugins() ?? {};
         const allMarketplacePlugins = [];
         for (const m of marketplaces) {
             try {
-                const manifest = await this.marketplaceService.loadMarketplaceManifest(this.marketplaceService.getMarketplacePath(m.source));
-                manifest.plugins.forEach((p) => {
+                const marketplacePath = this.marketplaceService.getMarketplacePath(m.source);
+                const manifest = await this.marketplaceService.loadMarketplaceManifest(marketplacePath);
+                for (const p of manifest.plugins) {
                     const pluginId = `${p.name}@${m.name}`;
-                    const installed = installedPlugins.plugins.find((ip) => ip.name === p.name && ip.marketplace === m.name);
+                    const scope = this.pluginScopeManager.findPluginScope(pluginId) ?? undefined;
+                    const installedEntry = installedPlugins.plugins.find((ip) => ip.name === p.name && ip.marketplace === m.name);
+                    // 安装状态以当前工作目录为准（spec plugin A-012）：配置链里有启用记录、
+                    // 且本机已有安装产物，才视为「已安装」。安装产物单独存在只说明该插件曾被
+                    // 下载过（例如以项目/本地作用域装在别的项目里），若据此判为已安装，会在
+                    // 当前目录渲染出「已安装 + 作用域未知」。作用域标签与安装态同源，未安装时
+                    // 不回传作用域。
+                    // 托管插件由组织下发（spec plugin A-024）：它在任何工程都算已安装，
+                    // 成员本机没有可卸载的记录，界面据此把卸载入口判为不可用。
+                    const managed = Object.prototype.hasOwnProperty.call(managedEnabled, pluginId);
+                    const installed = managed || scope ? installedEntry : undefined;
                     allMarketplacePlugins.push({
                         ...p,
                         marketplace: m.name,
-                        installed: !!installed,
+                        installed: managed || !!installed,
                         version: installed?.version,
+                        latestVersion: await this.readLatestVersion(marketplacePath, p.source),
                         cachePath: installed?.cachePath,
                         projectPath: installed?.projectPath,
-                        scope: this.pluginScopeManager.findPluginScope(pluginId) || undefined,
+                        scope: installed ? scope : undefined,
+                        managed: managed || undefined,
                     });
-                });
+                }
             }
-            catch {
-                // Skip marketplaces that fail to load
+            catch (error) {
+                // A marketplace that fails to load must be diagnosable: swallowing this
+                // silently is what made an unparsable entry look like an empty market
+                // (spec plugin「兼容 Claude Code 生态的市场清单与插件」场景 5).
+                logger.warn(`Failed to load marketplace ${m.name}: ${error instanceof Error ? error.message : String(error)}`);
             }
         }
         return {
@@ -107,6 +169,31 @@ export class PluginCore {
             mergedEnabled,
         };
     }
+    /**
+     * Reads the version declared by a marketplace plugin's own manifest inside the
+     * marketplace checkout — the version a fresh install would get. Sources that
+     * live outside the checkout (Git URLs and both object shapes, which always point
+     * at an external repository) have no local copy until install, so they yield
+     * undefined (spec plugin A-010 / A-021).
+     */
+    async readLatestVersion(marketplacePath, source) {
+        const parsed = parsePluginSource(source);
+        if (!parsed || parsed.kind !== "local")
+            return undefined;
+        const pluginPath = path.resolve(marketplacePath, parsed.path);
+        for (const dir of [".wave-plugin", ".claude-plugin"]) {
+            try {
+                const raw = await fs.readFile(path.join(pluginPath, dir, "plugin.json"), "utf-8");
+                const version = JSON.parse(raw).version;
+                if (version)
+                    return version;
+            }
+            catch {
+                // Try the next manifest location
+            }
+        }
+        return undefined;
+    }
     /**
      * Adds a new marketplace
      */
@@ -120,10 +207,37 @@ export class PluginCore {
         await this.marketplaceService.removeMarketplace(name, scope);
     }
     /**
-     * Updates a specific marketplace or all marketplaces
+     * Updates a specific marketplace or all marketplaces: refreshes the checkout
+     * from its upstream and reinstalls any plugins that are already installed from
+     * it (mirrors Claude Code's refresh-and-bump).
+     *
+     * 无界面可依赖的入口（非交互命令 `wave plugin marketplace update`）走这里；
+     * 交互界面的「批量更新插件」走 [updateMarketplacePlugins]（不拉检出）。
+     *
+     * @returns 实际发生版本变化的插件数量（0 = 全部已是最新），供 GUI 宿主区分提示。
      */
     async updateMarketplace(name) {
-        await this.marketplaceService.updateMarketplace(name);
+        return await this.marketplaceService.updateMarketplace(name, {
+            updatePlugins: true,
+        });
+    }
+    /**
+     * 批量升级某市场内已安装的插件，且不拉取检出——交互界面的「批量更新插件」
+     * （GUI 三端按钮与 CLI 插件管理器的同名项）。清单的新鲜度由打开这些界面时的
+     * 后台刷新保证（spec 插件市场 A-013、场景 14）。
+     *
+     * @returns 实际发生版本变化的插件数量（0 = 该市场已是最新），供宿主区分提示。
+     */
+    async updateMarketplacePlugins(name) {
+        return await this.marketplaceService.updateMarketplacePlugins(name);
+    }
+    /**
+     * Refreshes the checkout of every registered marketplace, without touching
+     * installed plugins. Called by hosts when the user opens a plugin
+     * marketplace surface (spec 插件市场 A-013 场景 5/13).
+     */
+    async refreshMarketplaces() {
+        await this.marketplaceService.refreshMarketplaces();
     }
     /**
      * Lists all registered marketplaces

package/dist/core/session.d.ts

@@ -1,2 +1,2 @@
-export { listSessions, listAllSessions, truncateContent, loadSessionFromJsonl, loadFullMessageThread, deleteSession, } from "../services/session.js";
+export { listSessions, listAllSessions, setSessionCustomTitle, truncateContent, loadSessionFromJsonl, loadFullMessageThread, deleteSession, } from "../services/session.js";
 export type { SessionMetadata, SessionData } from "../services/session.js";

package/dist/core/session.js

@@ -1 +1 @@
-export { listSessions, listAllSessions, truncateContent, loadSessionFromJsonl, loadFullMessageThread, deleteSession, } from "../services/session.js";
+export { listSessions, listAllSessions, setSessionCustomTitle, truncateContent, loadSessionFromJsonl, loadFullMessageThread, deleteSession, } from "../services/session.js";

package/dist/exec/catalog.d.ts

@@ -0,0 +1,140 @@
+/**
+ * The Exec catalog: which MCP tools exist, how they are rendered, how that
+ * rendering is budgeted, and the shape of the sandbox's `search` entry point.
+ *
+ * "Rendered" means into the catalog announcement (`exec/catalogAnnouncement.ts`),
+ * not into `Exec`'s tool description: the description has to stay a
+ * pool-independent constant, or every server that connects rewrites the cached
+ * prefix. This module produces the entries; the announcement wraps them.
+ *
+ * This module is the single source of truth for "what the sandbox may reach".
+ * The hard constraint is that the pool must equal the tools the agent could
+ * already call directly — if a tool were reachable from the sandbox but hidden
+ * from the agent, Exec would be a permission-escalation channel.
+ *
+ * The same reasoning applies to `search`: its call form is written once, as a
+ * schema, and both the model-visible prose and the host-side validation derive
+ * from that one object. Teaching a form in prose while accepting a different one
+ * in code is a bug with no diff to review.
+ */
+import type { McpManager } from "../managers/mcpManager.js";
+import type { PermissionManager } from "../managers/permissionManager.js";
+export interface ExecPoolEntry {
+    /** Flattened `mcp__<server>__<tool>` name — the key on the sandbox `tools` object. */
+    name: string;
+    description?: string;
+    /** Raw MCP input schema (JSON Schema), used only to render a compact signature. */
+    inputSchema?: Record<string, unknown>;
+    /**
+     * The schema the server declared for this tool's output, rendered as the
+     * signature's return type. Absent for most servers today; a tool without one
+     * still gets a return type (`Promise<unknown>`), because leaving it out would
+     * read as "this call returns nothing".
+     */
+    outputSchema?: Record<string, unknown>;
+}
+/**
+ * Every MCP tool the current agent may call, in catalog form.
+ *
+ * Derived from `getMcpToolsConfig()` — the exact source that produces the flat
+ * `tools[]` declarations when the pool is not collapsed, and the one whose
+ * connected/reconnecting filtering already keeps a transient disconnect from
+ * churning the tool list. So "the catalog equals what would have been declared"
+ * holds structurally, not by parallel construction.
+ */
+export declare function buildExecPool(mcpManager: McpManager, permissionManager?: PermissionManager): ExecPoolEntry[];
+/**
+ * The callable signature for one tool: parameters and return type. The catalog and
+ * search results share it, so the model can copy either one verbatim.
+ *
+ * The return type comes from the schema the server declared for its output, and a
+ * tool that declared none still gets `Promise<unknown>` rather than no return type
+ * at all: the sandbox resolves every call to the tool's output (its structured
+ * content, else its text, else `null`), and a signature ending at the parameters
+ * would read as "calls this, get nothing". Rendering it from the same rule the
+ * runtime applies is what keeps the catalog from teaching a shape the host will
+ * not deliver.
+ */
+export declare function renderToolSignature(entry: ExecPoolEntry): string;
+/**
+ * The callable signature of search, rendered by the very function that renders
+ * every catalog entry, so its shape cannot drift from what the host accepts or
+ * returns. Multi-line, for the sandbox API blurb where there is room to show the
+ * field docs.
+ */
+export declare function renderSearchSignature(): string;
+/**
+ * The one-line call form of search: the path plus a placeholder per field, all
+ * derived from `SEARCH_INPUT_SCHEMA`. For prose that cannot afford the multi-line
+ * block — the catalog's `PARTIAL` notice and error messages, which must still name
+ * a shape the host accepts.
+ */
+export declare function renderSearchCallForm(): string;
+/**
+ * Validate a search call's arguments against `SEARCH_INPUT_SCHEMA` and return the
+ * query to match on.
+ *
+ * The sandbox only guarantees a plain object (see `callHost`); it knows nothing
+ * about this schema, so a call naming a field the schema does not have must fail
+ * loudly here. Treating `{ q: "..." }` as an empty query would answer "here is the
+ * whole pool" and dress a typo up as a successful search.
+ */
+export declare function resolveSearchQuery(args: Record<string, unknown>): string;
+/**
+ * A single catalog entry: its signature (possibly several lines) followed by the
+ * first line of its description.
+ */
+export declare function renderCatalogEntry(entry: ExecPoolEntry): string;
+export interface RenderedCatalog {
+    text: string;
+    /** How many entries actually appear in `text`. */
+    shown: number;
+    total: number;
+    /** True when the budget forced entries out. Never silent. */
+    truncated: boolean;
+    /**
+     * Per-server tool counts, in pool order. The rendered entries cannot tell a later
+     * turn what moved — the announcement diff is count-level — so the snapshot is
+     * handed back here rather than recovered by parsing `text`.
+     */
+    namespaces: Array<{
+        name: string;
+        count: number;
+        shown: number;
+    }>;
+}
+/**
+ * The one-line index of a server: `- mcp__github (40 tools, 13 shown)`. The tail
+ * is dropped when the server is fully shown, and reads `none shown` when it got
+ * no seat at all.
+ *
+ * The prefix is the flattened name's, not the routing key alone, so the line is a
+ * substring of every tool name it covers (and of what search matches on). For a
+ * server whose name itself contains `__` the key is only the first segment — the
+ * same pre-existing ambiguity the grouping key has (see `execNamespace`).
+ *
+ * Exported for the announcement's per-namespace delta lines: the same renderer for
+ * the same counts, so a summary line and a delta line cannot drift apart.
+ */
+export declare function summarizeNamespace(name: string, count: number, shownCount: number): string;
+/**
+ * Render the catalog within an estimated-token budget.
+ *
+ * Selection round-robins across servers: one entry per server per round, so
+ * every server gets a seat before any server gets its second. A plain first-N
+ * cut would drop whole servers that happen to be connected later, and the model
+ * reads a missing server as "those tools do not exist" — the failure mode this
+ * whole feature has to avoid.
+ *
+ * An entry is a whole multi-line block and is budgeted and placed atomically: a
+ * server either gets the block this round or sits the round out, never half a
+ * signature.
+ *
+ * A truncated catalog additionally prints one summary line per server (see
+ * `summarizeNamespace`), before that server's blocks and outside the budget.
+ *
+ * The truncation notice deliberately carries no budget number: the budget is a
+ * tuning knob, and rendering it would make an unchanged tool pool produce
+ * different model-visible text after a config change.
+ */
+export declare function renderCatalog(entries: ExecPoolEntry[], budgetTokens: number): RenderedCatalog;