wave-agent-sdk 1.2.0 → 1.3.0

package/dist/exec/workerSource.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Source of the Exec sandbox worker.
+ *
+ * It is a plain string evaluated with `new Worker(source, { eval: true })` so
+ * that no extra dist file is needed and no host bundler (esbuild in
+ * `packages/vscode`, the JetBrains/desktop packaging steps) has to know about
+ * it.
+ *
+ * Two properties are load-bearing and were both measured on Node 22:
+ *
+ * 1. **Isolation is a thread + plain-data boundary, not `node:vm`.** Handing a
+ *    host function or host object to a `vm` context lets the script reach the
+ *    HOST realm through `tools.x.constructor(...)` — `codeGeneration` cannot
+ *    stop that, because the host realm has code generation enabled. So the
+ *    sandbox receives no host value at all: every bridge is built inside the
+ *    context and every value crossing back is deep-cloned into the context
+ *    realm.
+ * 2. **Termination is `worker.terminate()`.** `vm`'s `{ timeout }` only bounds
+ *    synchronous execution: `(async () => { await 0; while (true) {} })()`
+ *    returns in ~1ms and then spins inside the host event loop forever, which
+ *    hangs the whole process. `{ timeout }` is still passed as a cheap first
+ *    line for purely synchronous spins.
+ *
+ * `codeGeneration: { strings: false, wasm: false }` remains the mechanism that
+ * blocks `eval` / `new Function` / dynamic `import` at the engine level.
+ */
+/** The worker body. Receives `run` / `result` messages on the parent port. */
+export declare const EXEC_WORKER_SOURCE: string;

package/dist/exec/workerSource.js

@@ -0,0 +1,299 @@
+/**
+ * Source of the Exec sandbox worker.
+ *
+ * It is a plain string evaluated with `new Worker(source, { eval: true })` so
+ * that no extra dist file is needed and no host bundler (esbuild in
+ * `packages/vscode`, the JetBrains/desktop packaging steps) has to know about
+ * it.
+ *
+ * Two properties are load-bearing and were both measured on Node 22:
+ *
+ * 1. **Isolation is a thread + plain-data boundary, not `node:vm`.** Handing a
+ *    host function or host object to a `vm` context lets the script reach the
+ *    HOST realm through `tools.x.constructor(...)` — `codeGeneration` cannot
+ *    stop that, because the host realm has code generation enabled. So the
+ *    sandbox receives no host value at all: every bridge is built inside the
+ *    context and every value crossing back is deep-cloned into the context
+ *    realm.
+ * 2. **Termination is `worker.terminate()`.** `vm`'s `{ timeout }` only bounds
+ *    synchronous execution: `(async () => { await 0; while (true) {} })()`
+ *    returns in ~1ms and then spins inside the host event loop forever, which
+ *    hangs the whole process. `{ timeout }` is still passed as a cheap first
+ *    line for purely synchronous spins.
+ *
+ * `codeGeneration: { strings: false, wasm: false }` remains the mechanism that
+ * blocks `eval` / `new Function` / dynamic `import` at the engine level.
+ */
+/** Helpers compiled *inside* the context, so everything the script can reach belongs to the sandbox realm. */
+const SANDBOX_HELPERS = `
+(function () {
+  "use strict";
+  function cloneValue(v) {
+    if (v === null || typeof v !== "object") return v;
+    if (Array.isArray(v)) {
+      const out = [];
+      for (let i = 0; i < v.length; i++) out.push(cloneValue(v[i]));
+      return out;
+    }
+    const obj = { __proto__: null };
+    const keys = Object.keys(v);
+    for (let i = 0; i < keys.length; i++) {
+      const key = keys[i];
+      if (key === "__proto__") continue;
+      const child = v[key];
+      if (typeof child === "function") continue;
+      obj[key] = cloneValue(child);
+    }
+    return obj;
+  }
+  return {
+    build: function (callHost, emit, toolNames, searchName, reservedNamespace) {
+      // Everything handed to the script is built here, so every function object
+      // the script receives belongs to the context realm: reaching
+      // \`tools.x.constructor\` yields the context's Function, which refuses to
+      // compile without code generation. Handing out \`callHost\` itself — a
+      // worker-realm function whose Function can compile — would be the way out.
+      function makeTool(name) {
+        return function () {
+          const arg = arguments.length > 0 ? arguments[0] : {};
+          return Promise.resolve(callHost(name, arg)).then(cloneValue);
+        };
+      }
+      const tools = { __proto__: null };
+      for (let i = 0; i < toolNames.length; i++) {
+        tools[toolNames[i]] = makeTool(toolNames[i]);
+      }
+      const namespace = { __proto__: null };
+      namespace.search = makeTool(searchName);
+      tools[reservedNamespace] = Object.freeze(namespace);
+
+      // A name that is not in the pool must reach the host so it can answer with
+      // a pointer to search; otherwise the script would only see a bare
+      // "tools.foo is not a function". Restricted to the mcp__ prefix so
+      // ordinary property reads stay untouched — in particular "then", which
+      // would otherwise make this object look like a thenable.
+      const reachable = new Proxy(tools, {
+        get: function (target, key) {
+          if (
+            typeof key === "string" &&
+            !(key in target) &&
+            key.indexOf("mcp__") === 0
+          ) {
+            return makeTool(key);
+          }
+          return target[key];
+        },
+      });
+      Object.freeze(tools);
+
+      const levels = ["log", "info", "warn", "error", "debug"];
+      const consoleObj = {};
+      for (let i = 0; i < levels.length; i++) {
+        const level = levels[i];
+        consoleObj[level] = function () {
+          emit(level, Array.prototype.slice.call(arguments));
+        };
+      }
+
+      return {
+        tools: reachable,
+        console: Object.freeze(consoleObj),
+      };
+    },
+  };
+})()
+`;
+/**
+ * Surface reduction. These globals have no legitimate use inside a bounded
+ * script: they either expose an alternate code-generation path (`ShadowRealm`,
+ * `WebAssembly`), schedule host callbacks outside the run's try/catch
+ * (`FinalizationRegistry`, `WeakRef`, `queueMicrotask`), or only matter with
+ * shared memory (`Atomics`, `SharedArrayBuffer`). Some are engine-optional
+ * today, so the loop is defensive.
+ */
+const HARDEN_SOURCE = `
+(function () {
+  "use strict";
+  const removed = [
+    "ShadowRealm",
+    "WebAssembly",
+    "FinalizationRegistry",
+    "WeakRef",
+    "Atomics",
+    "SharedArrayBuffer",
+    "queueMicrotask",
+  ];
+  for (let i = 0; i < removed.length; i++) {
+    try {
+      delete globalThis[removed[i]];
+    } catch (error) {
+      /* non-configurable in some engines */
+    }
+  }
+})()
+`;
+/** The worker body. Receives `run` / `result` messages on the parent port. */
+export const EXEC_WORKER_SOURCE = `
+"use strict";
+const vm = require("node:vm");
+const { parentPort } = require("node:worker_threads");
+
+const pending = new Map();
+let callSeq = 0;
+let logs = [];
+let logChars = 0;
+let maxLogChars = 8000;
+let maxResultChars = 100000;
+
+function describeError(err) {
+  if (err && typeof err === "object") {
+    const message = err.message;
+    if (typeof message === "string" && message.length > 0) return message;
+    try {
+      return String(err);
+    } catch (stringifyError) {
+      return "an unprintable error";
+    }
+  }
+  return String(err);
+}
+
+function safeStringify(value) {
+  if (value === undefined) return "undefined";
+  if (typeof value === "string") return value;
+  try {
+    const json = JSON.stringify(value, function (key, item) {
+      return typeof item === "function" ? undefined : item;
+    });
+    if (json !== undefined) return json;
+  } catch (error) {
+    /* circular structure or a hostile toJSON */
+  }
+  try {
+    return String(value);
+  } catch (error) {
+    return "<unprintable>";
+  }
+}
+
+function emit(level, args) {
+  if (logChars >= maxLogChars) return;
+  const parts = [];
+  for (let i = 0; i < args.length; i++) parts.push(safeStringify(args[i]));
+  const line = (level === "log" ? "" : level + ": ") + parts.join(" ");
+  logChars += line.length;
+  logs.push(line);
+}
+
+/**
+ * Bound what the script hands back. The flat MCP path caps its own results
+ * (toolResultStorage), so returning an unbounded value here would make the
+ * nested call *more* expensive than the call it replaced.
+ */
+function boundResult(text) {
+  if (text.length <= maxResultChars) return text;
+  return (
+    text.slice(0, maxResultChars) +
+    "\\n... (returned value truncated: " + text.length + " characters total)"
+  );
+}
+
+function callHost(name, args) {
+  return new Promise(function (resolve, reject) {
+    let payload;
+    try {
+      payload = args === undefined || args === null ? {} : JSON.parse(JSON.stringify(args));
+    } catch (error) {
+      reject(new Error("Exec tool arguments must be JSON-serializable"));
+      return;
+    }
+    if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+      reject(new Error("Exec tool arguments must be a plain object"));
+      return;
+    }
+    const id = ++callSeq;
+    pending.set(id, { resolve: resolve, reject: reject });
+    parentPort.postMessage({ kind: "call", id: id, name: name, args: payload });
+  });
+}
+
+function runScript(message) {
+  maxLogChars = message.maxLogChars;
+  if (typeof message.maxResultChars === "number") {
+    maxResultChars = message.maxResultChars;
+  }
+  const sandbox = { __proto__: null };
+  const context = vm.createContext(sandbox, {
+    codeGeneration: { strings: false, wasm: false },
+  });
+
+  vm.runInContext(${JSON.stringify(HARDEN_SOURCE)}, context);
+  const helpers = vm.runInContext(${JSON.stringify(SANDBOX_HELPERS)}, context);
+  const globals = helpers.build(
+    callHost,
+    emit,
+    message.toolNames,
+    message.searchName,
+    message.reservedNamespace,
+  );
+  sandbox.tools = globals.tools;
+  sandbox.console = globals.console;
+
+  let scriptResult;
+  try {
+    scriptResult = vm.runInContext("(async () => {\\n" + message.code + "\\n})()", context, {
+      timeout: message.timeoutMs,
+    });
+  } catch (error) {
+    parentPort.postMessage({
+      kind: "done",
+      ok: false,
+      error: describeError(error),
+      logs: logs,
+    });
+    return;
+  }
+
+  Promise.resolve(scriptResult).then(
+    function (value) {
+      parentPort.postMessage({
+        kind: "done",
+        ok: true,
+        value: boundResult(safeStringify(value)),
+        logs: logs,
+      });
+    },
+    function (error) {
+      parentPort.postMessage({
+        kind: "done",
+        ok: false,
+        error: describeError(error),
+        logs: logs,
+      });
+    },
+  );
+}
+
+parentPort.on("message", function (message) {
+  if (message.kind === "result") {
+    const entry = pending.get(message.id);
+    if (!entry) return;
+    pending.delete(message.id);
+    if (message.ok) entry.resolve(message.value);
+    else entry.reject(new Error(message.error));
+    return;
+  }
+  if (message.kind === "run") {
+    try {
+      runScript(message);
+    } catch (error) {
+      parentPort.postMessage({
+        kind: "done",
+        ok: false,
+        error: describeError(error),
+        logs: logs,
+      });
+    }
+  }
+});
+`;

package/dist/host/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 宿主面入口 —— 所有"由宿主进程驱动 agent"的消费者（desktop 主进程、VS Code
+ * 扩展宿主）**只从这里导入**，不要碰桶入口（`.`）。
+ *
+ * 宿主只通过 JSON-RPC 跟 `wave --stdio` 子进程讲话，它需要的东西恰好是这一组：
+ *   - `./stdio`：RPC 客户端封装（StdioAgent / rpcClient / NotificationRouter）
+ *   - `./constants`：与 CLI 共用的字面量（工具名、逐字文案）
+ *   - `./types`：协议与消息类型
+ *
+ * 为什么要有这个入口：桶入口会把整套 agent 运行时（工具、供应商 SDK、OTel…）连成
+ * 一张图，而图里有些模块在**求值期**就会抛（可选原生包缺席时，如 `sharp`）。
+ * v1.2.5 的桌面端/插件"装出来打不开"就是有人为了复用两条文案从桶入口 import，
+ * 把那份图连坐进了主进程与扩展后端（PR #2267 引入，#2281/#2283 修复）。
+ *
+ * 过去宿主从 `/types`、`/constants`、`/stdio` 三个窄入口分别取用，纪律是"记住别用
+ * 桶"——但需求出现时作者常常不知道新值该去哪个窄入口，于是又走回桶。这里把宿主面
+ * 收成一个**正向**入口：宿主需要的值都应该出现在这里，取不到就来这里加，而加完会
+ * 撞上 `scripts/check-sdk-surface.mjs` 的闭包预算检查（该入口的闭包必须零第三方
+ * 依赖、体积在预算内）。旧的三个子路径继续保留给外部消费者，不 breaking。
+ */
+export * from "../constants/index.js";
+export * from "../stdio/index.js";
+export * from "../types/index.js";

package/dist/host/index.js

@@ -0,0 +1,23 @@
+/**
+ * 宿主面入口 —— 所有"由宿主进程驱动 agent"的消费者（desktop 主进程、VS Code
+ * 扩展宿主）**只从这里导入**，不要碰桶入口（`.`）。
+ *
+ * 宿主只通过 JSON-RPC 跟 `wave --stdio` 子进程讲话，它需要的东西恰好是这一组：
+ *   - `./stdio`：RPC 客户端封装（StdioAgent / rpcClient / NotificationRouter）
+ *   - `./constants`：与 CLI 共用的字面量（工具名、逐字文案）
+ *   - `./types`：协议与消息类型
+ *
+ * 为什么要有这个入口：桶入口会把整套 agent 运行时（工具、供应商 SDK、OTel…）连成
+ * 一张图，而图里有些模块在**求值期**就会抛（可选原生包缺席时，如 `sharp`）。
+ * v1.2.5 的桌面端/插件"装出来打不开"就是有人为了复用两条文案从桶入口 import，
+ * 把那份图连坐进了主进程与扩展后端（PR #2267 引入，#2281/#2283 修复）。
+ *
+ * 过去宿主从 `/types`、`/constants`、`/stdio` 三个窄入口分别取用，纪律是"记住别用
+ * 桶"——但需求出现时作者常常不知道新值该去哪个窄入口，于是又走回桶。这里把宿主面
+ * 收成一个**正向**入口：宿主需要的值都应该出现在这里，取不到就来这里加，而加完会
+ * 撞上 `scripts/check-sdk-surface.mjs` 的闭包预算检查（该入口的闭包必须零第三方
+ * 依赖、体积在预算内）。旧的三个子路径继续保留给外部消费者，不 breaking。
+ */
+export * from "../constants/index.js";
+export * from "../stdio/index.js";
+export * from "../types/index.js";

package/dist/index.d.ts

@@ -23,12 +23,17 @@ export * from "./utils/tokenCalculation.js";
 export * from "./utils/gitUtils.js";
 export * from "./utils/nameGenerator.js";
 export * from "./utils/pathEncoder.js";
+export { ensureRuntimeDeps } from "./utils/runtimeDeps.js";
+export type { RuntimeDepsResult } from "./utils/runtimeDeps.js";
 export * from "./utils/worktreeSession.js";
 export * from "./utils/worktreeUtils.js";
 export { loadMergedWaveConfig, loadUserConfigEnv, loadWaveConfigFromFile, } from "./services/configurationService.js";
 export { getUserConfigPaths, getProjectConfigPaths, } from "./utils/configPaths.js";
+export { readUserPreferenceSettings, readUserPreferenceView, updateUserPreferenceSettings, userSettingsFilePath, contextLengthToMaxInputTokens, maxInputTokensToContextLength, MAX_INPUT_TOKENS_ENV_KEY, } from "./utils/userSettings.js";
+export type { UserPreferenceSettings, UserPreferenceView, } from "./utils/userSettings.js";
 export * from "./types/index.js";
 export type { SubagentConfiguration } from "./utils/subagentParser.js";
 export type { SubagentInstance } from "./managers/subagentManager.js";
+export { PLUGIN_CHANGE_PENDING_MESSAGE, PLUGIN_RELOADED_MESSAGE, } from "./constants/messages.js";
 export * from "./tools/buildTool.js";
 export type { ToolPlugin, ToolResult, ToolContext } from "./tools/types.js";

package/dist/index.js

@@ -27,10 +27,16 @@ export * from "./utils/tokenCalculation.js";
 export * from "./utils/gitUtils.js";
 export * from "./utils/nameGenerator.js";
 export * from "./utils/pathEncoder.js";
+export { ensureRuntimeDeps } from "./utils/runtimeDeps.js";
 export * from "./utils/worktreeSession.js";
 export * from "./utils/worktreeUtils.js";
 export { loadMergedWaveConfig, loadUserConfigEnv, loadWaveConfigFromFile, } from "./services/configurationService.js";
 export { getUserConfigPaths, getProjectConfigPaths, } from "./utils/configPaths.js";
+export { readUserPreferenceSettings, readUserPreferenceView, updateUserPreferenceSettings, userSettingsFilePath, contextLengthToMaxInputTokens, maxInputTokensToContextLength, MAX_INPUT_TOKENS_ENV_KEY, } from "./utils/userSettings.js";
 export * from "./types/index.js";
+// Plugin reload prompts, shared with the hosts that only display them. The
+// reload result types (PluginLoadFailure / PluginReloadResult) come with the
+// ./types/index.js re-export above.
+export { PLUGIN_CHANGE_PENDING_MESSAGE, PLUGIN_RELOADED_MESSAGE, } from "./constants/messages.js";
 // Export tool building utilities
 export * from "./tools/buildTool.js";

package/dist/managers/MemoryRuleManager.d.ts

@@ -15,6 +15,12 @@ export declare class MemoryRuleManager {
     private workdir;
     private service;
     constructor(container: Container, options: MemoryRuleManagerOptions);
+    /**
+     * Re-point rule discovery at another working directory (in-session session
+     * switch). Project rules are resolved relative to the workdir, so the
+     * registry is rebuilt from scratch rather than merged.
+     */
+    setWorkdir(workdir: string): Promise<void>;
     /**
      * Scans .wave/rules and ~/.wave/rules for memory rule files.
      */

package/dist/managers/MemoryRuleManager.js

@@ -13,6 +13,18 @@ export class MemoryRuleManager {
         this.workdir = options.workdir;
         this.service = new MemoryRuleService();
     }
+    /**
+     * Re-point rule discovery at another working directory (in-session session
+     * switch). Project rules are resolved relative to the workdir, so the
+     * registry is rebuilt from scratch rather than merged.
+     */
+    async setWorkdir(workdir) {
+        if (this.workdir === workdir) {
+            return;
+        }
+        this.workdir = workdir;
+        await this.discoverRules();
+    }
     /**
      * Scans .wave/rules and ~/.wave/rules for memory rule files.
      */

package/dist/managers/aiManager.d.ts

@@ -23,6 +23,12 @@ export interface AIManagerCallbacks {
     onCompactionReasoningUpdate?: (content: string) => void;
     onUsageAdded?: (usage: Usage) => void;
     onCwdChange?: (newCwd: string) => void;
+    /**
+     * Full plan-file content after a successful `Write`/`Edit` of the plan file
+     * (spec: 计划文件更新后刷新计划面板). Inherited from AgentCallbacks via the
+     * spread in container setup.
+     */
+    onPlanFileUpdated?: (content: string) => void;
 }
 export interface AIManagerOptions {
     callbacks?: AIManagerCallbacks;
@@ -72,6 +78,7 @@ export declare class AIManager {
     private get hookManager();
     private get reversionManager();
     private get permissionManager();
+    private get mcpManager();
     private get planManager();
     private get configurationService();
     /**
@@ -85,7 +92,7 @@ export declare class AIManager {
     getGatewayConfig(): GatewayConfig;
     getModelConfig(): ModelConfig;
     getMaxInputTokens(): number;
-    getLanguage(): string | undefined;
+    getLanguage(): string;
     getAutoMemoryEnabled(): boolean;
     getWorktreeBaseRef(): "fresh" | "head";
     getWorkdir(): string;
@@ -160,6 +167,21 @@ export declare class AIManager {
      * match the main conversation's for the prompt cache to be reused.
      */
     private buildMainSystemPrompt;
+    /**
+     * Announce the connected MCP servers' own usage notes in the conversation,
+     * once per server. Not part of the system prompt: this content appears when a
+     * connection happens, and rewriting the system prompt mid-session would drop
+     * the whole cached prefix (see `utils/mcpInstructions.ts`).
+     */
+    private maybeAnnounceMcpInstructions;
+    /**
+     * Announce the MCP catalog in the conversation, whenever the pool renders
+     * differently from the last announcement. Keeping it out of `Exec`'s description
+     * is what makes that declaration a constant: a server connecting would otherwise
+     * rewrite `tools[]`, which sits in the cached prefix (see
+     * `exec/catalogAnnouncement.ts`).
+     */
+    private maybeAnnounceExecCatalog;
     private resolveFilteredTools;
     /**
      * Fork-path loop: run a bounded agent loop over a copy of the conversation
@@ -226,6 +248,7 @@ export declare class AIManager {
     private get subagentManager();
     private get cronManager();
     private get skillManager();
+    private get liveConfigManager();
     sendAIMessage(options?: {
         recursionDepth?: number;
         model?: string;
@@ -244,6 +267,17 @@ export declare class AIManager {
      * tool execution, PostToolUse hooks, and error handling.
      */
     private executeToolCall;
+    /**
+     * Plan panel refresh (spec: 计划文件更新后刷新计划面板).
+     *
+     * When a successful `Write`/`Edit` targets the current plan file, read it and
+     * emit the full content so hosts can update an already-open plan panel. The
+     * path comparison mirrors the plan-mode allow branch in PermissionManager so
+     * "the write that was allowed" and "the write that refreshes the panel" stay
+     * the same set. The path is only set while plan mode is active, so post-exit
+     * writes can't reach the panels.
+     */
+    private notifyPlanFileUpdate;
     /**
      * Execute PreToolUse hooks before tool execution
      * Returns true if hooks allow tool execution, false if blocked