wave-agent-sdk 1.1.5 → 1.3.0

package/dist/tools/webFetchTool.js

@@ -1,19 +1,16 @@
-import TurndownService from "turndown";
 import { LRUCache } from "lru-cache";
 import { WEB_FETCH_TOOL_NAME } from "../constants/tools.js";
 import { logger } from "../utils/globalLogger.js";
 import { isArtifactEnabled } from "../services/artifactAvailability.js";
-import { authService, createAuthAwareFetch } from "../services/authService.js";
 import { recordVersion } from "../services/artifactSession.js";
-import { buildPersistedOutputMessage, generatePreview, persistToolResult, } from "../utils/toolResultStorage.js";
+import { extractArtifactSlug, htmlToMarkdown, readArtifactContent, summarizeArtifactAsReader, } from "../services/artifactContent.js";
+import { formatSize, processContentWithAI, } from "../services/contentSummarizer.js";
 // --- Security Limits ---
 const MAX_HTTP_CONTENT_LENGTH = 10 * 1024 * 1024; // 10MB
 const FETCH_TIMEOUT_MS = 60000; // 60s
 const MAX_REDIRECTS = 10;
 const MAX_MARKDOWN_LENGTH = 100000;
 const USER_AGENT = "Wave-User (+https://github.com/netease-lcap/wave-agent)";
-/** Artifact HTML beyond this size is persisted to a temp file (path + head preview). */
-const ARTIFACT_PREVIEW_BYTES = 2 * 1024; // ~2KB
 // --- Cache (LRU with 15min TTL, 50MB max) ---
 const CACHE_TTL = 15 * 60 * 1000; // 15 minutes
 const CACHE_MAX_BYTES = 50 * 1024 * 1024; // 50MB
@@ -22,14 +19,6 @@ const cache = new LRUCache({
     maxSize: CACHE_MAX_BYTES,
     sizeCalculation: (entry) => entry.bytes,
 });
-// --- Helpers ---
-function formatSize(bytes) {
-    if (bytes < 1024)
-        return `${bytes}B`;
-    if (bytes < 1024 * 1024)
-        return `${(bytes / 1024).toFixed(1)}KB`;
-    return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
-}
 function validateURL(url) {
     if (url.length > 2000) {
         return {
@@ -79,124 +68,6 @@ function isPermittedRedirect(originalUrl, redirectUrl) {
         return false;
     }
 }
-// --- Artifact read channel ---
-/** Extract the artifact slug from a `{host}/code/artifact/{slug}` URL. */
-function extractArtifactSlug(url) {
-    try {
-        const parsed = new URL(url);
-        const match = parsed.pathname.match(/^\/code\/artifact\/([^/]+)\/?$/);
-        return match ? decodeURIComponent(match[1]) : null;
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Fetch artifact metadata (`via=model_read`) then the HTML content (Bearer).
- * Returns markdown (HTML converted via turndown) on success.
- */
-async function readArtifact(url, slug, abortSignal) {
-    const serverUrl = authService.getServerUrl();
-    const authFetch = createAuthAwareFetch(globalThis.fetch);
-    const signal = abortSignal
-        ? AbortSignal.any([abortSignal, AbortSignal.timeout(FETCH_TIMEOUT_MS)])
-        : AbortSignal.timeout(FETCH_TIMEOUT_MS);
-    let meta;
-    try {
-        const metaRes = await authFetch(`${serverUrl}/api/frame/${encodeURIComponent(slug)}?via=model_read`, { method: "GET", signal });
-        if (metaRes.status === 404) {
-            return {
-                kind: "error",
-                error: `Artifact not found: ${url} (it may have been deleted)`,
-            };
-        }
-        if (!metaRes.ok) {
-            return {
-                kind: "error",
-                error: `Failed to fetch artifact metadata: ${metaRes.status} ${metaRes.statusText}`,
-            };
-        }
-        meta = (await metaRes.json());
-    }
-    catch (error) {
-        logger?.warn("Artifact read metadata failed", {
-            slug,
-            error: String(error),
-        });
-        return {
-            kind: "error",
-            error: `Failed to fetch artifact metadata: ${error instanceof Error ? error.message : String(error)}`,
-        };
-    }
-    const contentUrl = typeof meta.contentUrl === "string" ? meta.contentUrl : "";
-    const version = typeof meta.version === "string" ? meta.version : "";
-    if (!contentUrl) {
-        return {
-            kind: "error",
-            error: "Artifact metadata did not include a contentUrl",
-        };
-    }
-    let html;
-    try {
-        const contentRes = await authFetch(new URL(contentUrl, serverUrl).toString(), { method: "GET", signal });
-        if (!contentRes.ok) {
-            return {
-                kind: "error",
-                error: `Failed to fetch artifact content: ${contentRes.status} ${contentRes.statusText}`,
-            };
-        }
-        html = await contentRes.text();
-    }
-    catch (error) {
-        logger?.warn("Artifact read content failed", {
-            slug,
-            error: String(error),
-        });
-        return {
-            kind: "error",
-            error: `Failed to fetch artifact content: ${error instanceof Error ? error.message : String(error)}`,
-        };
-    }
-    const turndownService = new TurndownService();
-    const markdown = turndownService.turndown(html);
-    return {
-        kind: "ok",
-        slug,
-        version,
-        markdown,
-        bytes: new TextEncoder().encode(markdown).length,
-    };
-}
-/**
- * Process an artifact read result: persist content >~2KB to a temp file
- * (return file path + head preview), run the prompt, attach artifactRead metadata.
- */
-async function processArtifactRead(url, prompt, markdown, slug, version, context) {
-    const bytes = new TextEncoder().encode(markdown).length;
-    let aiInput = markdown;
-    let persistedMessage = "";
-    if (bytes > ARTIFACT_PREVIEW_BYTES) {
-        const filePath = persistToolResult(markdown, "artifact");
-        if (filePath) {
-            persistedMessage = buildPersistedOutputMessage(markdown.length, filePath, generatePreview(markdown));
-            aiInput = persistedMessage;
-        }
-        else {
-            aiInput =
-                markdown.substring(0, MAX_MARKDOWN_LENGTH) +
-                    "\n\n... (content truncated, failed to persist full output)";
-        }
-    }
-    const result = await processWithAI(url, prompt, aiInput, 200, "OK", context, bytes);
-    result.metadata = { artifactRead: { slug, ver: version } };
-    if (persistedMessage) {
-        // Append the persisted-output message so the model can Read the full content.
-        result.content = result.content
-            ? result.content + "\n\n" + persistedMessage
-            : persistedMessage;
-    }
-    return result;
-}
 // --- Tool ---
 export const webFetchTool = {
     name: WEB_FETCH_TOOL_NAME,
@@ -271,22 +142,28 @@ Usage notes:
         if (isArtifactEnabled(context.workdir)) {
             const artifactSlug = extractArtifactSlug(url);
             if (artifactSlug) {
-                const readResult = await readArtifact(url, artifactSlug, context.abortSignal);
+                const readResult = await readArtifactContent(artifactSlug, {
+                    url,
+                    abortSignal: context.abortSignal,
+                });
                 if (readResult.kind === "error") {
                     return { success: false, content: "", error: readResult.error };
                 }
-                if (context.sessionId && readResult.version) {
+                const { slug, version, html } = readResult.artifact;
+                if (context.sessionId && version) {
                     // Keep the stale-version guard in sync with what the model has seen.
-                    recordVersion(context.sessionId, artifactSlug, readResult.version);
+                    recordVersion(context.sessionId, slug, version);
                 }
-                return processArtifactRead(url, prompt, readResult.markdown, artifactSlug, readResult.version, context);
+                const result = await summarizeArtifactAsReader(url, prompt, html, context);
+                result.metadata = { artifactRead: { slug, ver: version } };
+                return result;
             }
         }
         try {
             const cached = cache.get(url);
             if (cached) {
                 const markdown = cached.content;
-                return processWithAI(url, prompt, markdown, cached.code, cached.codeText, context);
+                return processContentWithAI(url, prompt, markdown, cached.code, cached.codeText, context);
             }
             // Fetch with redirect following
             const result = await fetchWithRedirects(url, context.abortSignal);
@@ -323,8 +200,7 @@ Usage notes:
                 };
             }
             const html = await response.text();
-            const turndownService = new TurndownService();
-            let markdown = turndownService.turndown(html);
+            let markdown = htmlToMarkdown(html);
             const markdownBytes = new TextEncoder().encode(markdown).length;
             // Truncate if too large
             if (markdown.length > MAX_MARKDOWN_LENGTH) {
@@ -340,7 +216,7 @@ Usage notes:
                 content: markdown,
                 contentType: response.headers.get("content-type") || "",
             });
-            return processWithAI(finalUrl, prompt, markdown, response.status, response.statusText, context, markdownBytes);
+            return processContentWithAI(finalUrl, prompt, markdown, response.status, response.statusText, context, markdownBytes);
         }
         catch (error) {
             logger.error(`WebFetch failed for ${url}:`, error);
@@ -398,30 +274,3 @@ async function fetchWithRedirects(initialUrl, abortSignal, redirectCount = 0) {
     }
     return { kind: "response", response, finalUrl: initialUrl };
 }
-// --- AI Processing ---
-async function processWithAI(url, prompt, markdown, statusCode, statusText, context, contentSize) {
-    if (!context.aiManager || !context.aiService) {
-        return {
-            success: false,
-            content: markdown,
-            error: "AI Manager or AI Service not available for processing content",
-        };
-    }
-    const modelConfig = context.aiManager.getModelConfig();
-    const fastModel = modelConfig.fastModel;
-    const aiResponse = await context.aiService.processWebContent({
-        gatewayConfig: context.aiManager.getGatewayConfig(),
-        modelConfig: modelConfig,
-        content: markdown,
-        prompt: prompt,
-        model: fastModel,
-        abortSignal: context.abortSignal,
-    });
-    const sizeStr = contentSize !== undefined ? formatSize(contentSize) : "unknown size";
-    const statusStr = `${statusCode} ${statusText}`.trim();
-    return {
-        success: true,
-        content: aiResponse.content || "",
-        shortResult: `Received ${sizeStr} (${statusStr}) from ${url}`,
-    };
-}

package/dist/tools/workflowTool.js

@@ -1,5 +1,33 @@
+import * as path from "node:path";
 import { WORKFLOW_TOOL_NAME } from "../constants/tools.js";
+import { parseScript } from "../workflow/scriptRuntime.js";
 import { logger } from "../utils/globalLogger.js";
+/** Characters that would corrupt a single-line summary (ANSI-adjacent controls, separators, invisibles). */
+const SUMMARY_UNSAFE_CHARS = /[\p{Cc}\p{Cf}\p{Cs}\p{Default_Ignorable_Code_Point}\u2028\u2029]/gu;
+/** Max characters of the script head shown when `meta` cannot be parsed. */
+const FALLBACK_SUMMARY_MAX_CHARS = 80;
+function sanitizeForSummary(text) {
+    return text.replace(SUMMARY_UNSAFE_CHARS, "");
+}
+/**
+ * Summary for a script whose `meta` could not be parsed: its first non-empty
+ * line, truncated if needed, plus a hint that more lines follow.
+ */
+function summarizeUnparsedScript(script) {
+    const lines = script.split("\n");
+    const head = sanitizeForSummary(lines.find((line) => line.trim()) ?? "");
+    if (!head) {
+        return "";
+    }
+    const preview = head.length > FALLBACK_SUMMARY_MAX_CHARS
+        ? `${head.slice(0, FALLBACK_SUMMARY_MAX_CHARS - 1)}…`
+        : head;
+    const extraLines = lines.length - 1;
+    if (extraLines <= 0) {
+        return preview;
+    }
+    return `${preview} … +${extraLines} line${extraLines === 1 ? "" : "s"}`;
+}
 /**
  * Workflow tool plugin for executing deterministic multi-subagent orchestration scripts.
  *
@@ -176,15 +204,19 @@ Use this tool for multi-step orchestration where control flow should be determin
         }
     },
     formatCompactParams: (params) => {
-        if (params.scriptPath) {
-            return `scriptPath: ${params.scriptPath}`;
-        }
         const script = params.script;
-        if (script) {
-            // Extract meta.name from the script
-            const nameMatch = script.match(/name:\s*['"]([^'"]+)['"]/);
-            return nameMatch ? nameMatch[1] : script.slice(0, 50) + "...";
+        if (typeof script === "string" && script) {
+            try {
+                return sanitizeForSummary(parseScript(script).meta.description);
+            }
+            catch {
+                return summarizeUnparsedScript(script);
+            }
+        }
+        const scriptPath = params.scriptPath;
+        if (typeof scriptPath === "string" && scriptPath) {
+            return sanitizeForSummary(path.basename(scriptPath));
         }
-        return "workflow";
+        return "";
     },
 };

package/dist/tools/writeTool.js

@@ -1,7 +1,8 @@
-import { readFile, writeFile, mkdir, stat } from "fs/promises";
+import { readFile, mkdir, stat } from "fs/promises";
 import { createHash } from "crypto";
 import { dirname } from "path";
 import { logger } from "../utils/globalLogger.js";
+import { atomicWriteFile } from "../utils/atomicWrite.js";
 import { resolvePath, getDisplayPath } from "../utils/path.js";
 import { READ_TOOL_NAME } from "../constants/tools.js";
 /**
@@ -157,9 +158,10 @@ Usage:
             if (context.reversionManager && context.messageId) {
                 snapshotId = await context.reversionManager.recordSnapshot(context.messageId, resolvedPath, isExistingFile ? "modify" : "create");
             }
-            // Write file
+            // Write file (atomic: temp file + rename, so concurrent readers never
+            // observe a truncated file). Staleness/OCC was checked above.
             try {
-                await writeFile(resolvedPath, content, "utf-8");
+                await atomicWriteFile(resolvedPath, content);
                 // Commit snapshot on success
                 if (context.reversionManager && snapshotId) {
                     await context.reversionManager.commitSnapshot(snapshotId);
@@ -180,6 +182,7 @@ Usage:
                     mtime: newStats.mtime.getTime(),
                     hash,
                     source: "write",
+                    content,
                     offset: undefined,
                     limit: undefined,
                 });

package/dist/types/agent.d.ts

@@ -29,8 +29,25 @@ export interface AgentOptions {
     visionModel?: string;
     maxInputTokens?: number;
     maxTokens?: number;
-    /** Preferred language for agent communication */
+    /**
+     * Preferred language for agent communication, injected verbatim into the
+     * system prompt (`# Language\nAlways respond in <value>`). When unset, the
+     * resolve chain falls back to `DEFAULT_LANGUAGE` (`zh-CN`).
+     */
     language?: string;
+    /**
+     * Per-session override for auto-memory extraction (程序化会话级覆盖).
+     * Takes precedence over settings.json merged config and
+     * WAVE_DISABLE_AUTO_MEMORY env; undefined defers to them. 三端设置页的开关
+     * **不**经这一层下发——它落用户级 `~/.wave/settings.json`，由实时重载在下一轮
+     * 生效（spec core/agent-config.md「设置实时重载」）。
+     */
+    autoMemoryEnabled?: boolean;
+    /**
+     * Per-session override for auto-memory extraction frequency (turns). 同
+     * `autoMemoryEnabled`：设置页的值不在这一层。
+     */
+    autoMemoryFrequency?: number;
     callbacks?: AgentCallbacks;
     restoreSessionId?: string;
     continueLastSession?: boolean;
@@ -111,4 +128,10 @@ export interface AgentCallbacks extends MessageManagerCallbacks, BackgroundTaskM
     onCompactionContentUpdate?: (content: string) => void;
     /** Streaming reasoning from the compaction fork (accumulated). */
     onCompactionReasoningUpdate?: (content: string) => void;
+    /**
+     * Full content of the plan file right after a successful `Write`/`Edit` of
+     * that file (spec: 计划文件更新后刷新计划面板). Hosts use it to refresh an
+     * already-open plan panel; it is not emitted for other files.
+     */
+    onPlanFileUpdated?: (content: string) => void;
 }

package/dist/types/commands.d.ts

@@ -2,10 +2,17 @@
  * Slash command and custom command types
  * Dependencies: None
  */
+/** UI-facing source of a skill-derived slash command. "user" covers personal
+ *  (~/.wave、~/.claude、~/.agents) skills; plugin skills carry pluginName. */
+export type SkillSource = "builtin" | "user" | "project" | "plugin";
 export interface SlashCommand {
     id: string;
     name: string;
     description: string;
+    /** Set only on commands registered from skills — GUI slash-command popup
+     * renders a source tag (内置/用户/项目/插件) from it. Plain/custom/plugin
+     * commands leave it undefined. */
+    skillSource?: SkillSource;
     handler: (args?: string, signal?: AbortSignal) => Promise<void> | void;
     /** Whether this command should bypass the message queue when AI is busy.
      * - `true`: always immediate

package/dist/types/configuration.d.ts

@@ -13,7 +13,6 @@ import type { TelemetryConfig } from "./telemetry.js";
 export type Scope = "user" | "project" | "local";
 export interface MarketplaceConfig {
     source: MarketplaceSource;
-    autoUpdate?: boolean;
 }
 /**
  * Root configuration structure for all Wave Agent settings including hooks and environment variables
@@ -25,7 +24,12 @@ export interface WaveConfiguration {
     permissions?: {
         allow?: string[];
         deny?: string[];
-        permissionMode?: PermissionMode;
+        /**
+         * Default permission mode for restricted tools. Settings key aligns with
+         * Claude Code's `permissions.defaultMode`; the runtime permission context
+         * and CLI `--permission-mode` keep the "permission mode" naming.
+         */
+        defaultMode?: PermissionMode;
         /**
          * List of directories that are considered part of the Safe Zone.
          * File operations within these directories can be auto-accepted.
@@ -57,6 +61,8 @@ export interface WaveConfiguration {
     };
     /** Whether the Artifact tool is enabled. Unset follows the code default constant (ARTIFACT_DEFAULT_ENABLED). */
     enableArtifact?: boolean;
+    /** Whether the Exec tool is enabled. Unset follows the code default constant (EXEC_DEFAULT_ENABLED). */
+    enableExec?: boolean;
     /**
      * Session transcript retention in days (aligned with Claude Code's
      * cleanupPeriodDays). Session jsonl files in ~/.wave/projects older than
@@ -65,6 +71,43 @@ export interface WaveConfiguration {
      */
     cleanupPeriodDays?: number;
 }
+/**
+ * 设置页读写的用户偏好子集（落点 = 用户级 `~/.wave/settings.json`；读写实现见
+ * `utils/userSettings.ts`）。三端（VSCE / JetBrains / desktop）设置页与 CLI 的
+ * `getUserSettings` / `updateUserSettings` RPC 共用这一形状；`contextLength` 单位
+ * 为 K（落盘换算为 `env.WAVE_MAX_INPUT_TOKENS`）。
+ */
+export interface UserPreferenceSettings {
+    /** AI 回复语言（settings.json 顶层 `language`，如 zh-CN / en-US）。 */
+    language?: string;
+    /** 上下文长度，单位 K（如 200 = 200K）。 */
+    contextLength?: number;
+    /** 是否开启自动记忆提取。 */
+    autoMemoryEnabled?: boolean;
+    /** 自动记忆提取的轮次频率（1–100）。 */
+    autoMemoryFrequency?: number;
+    /** Wave 服务端地址（settings.json 的 `env.WAVE_SERVER_URL`，如 https://…）。 */
+    serverUrl?: string;
+}
+/** 用户偏好键（设置页控件）。 */
+export type UserPreferenceKey = keyof UserPreferenceSettings;
+/**
+ * 生效值的来源层。只归因**进程级可达**的层（Remote 组织下发 / 用户级文件 /
+ * 机器环境变量 / SDK 默认）：`project` / `local` 需要 workdir，而
+ * `getUserSettings` 是刻意的无会话全局 RPC；`override` / `options` 是会话级
+ * 语义，不在这条链路上（见 spec core/agent-config.md 边界说明「用户偏好的层与来源」）。
+ */
+export type UserPreferenceSource = "remote" | "user" | "env" | "default";
+/**
+ * `getUserSettings` / `updateUserSettings` 的回包：**生效**用户偏好——键缺失
+ * 表示该偏好没有任何提供者（设置页据此显示「未设置」态）——外加每个键的来源层
+ * （`preferenceSources`，设置页对来源为 `remote` 的键显示生效值 + 置灰 +
+ * 「由组织配置管理」）。
+ */
+export interface UserPreferenceSettingsView extends UserPreferenceSettings {
+    /** 每个键恒有来源（缺省即 `default`）。 */
+    preferenceSources?: Partial<Record<UserPreferenceKey, UserPreferenceSource>>;
+}
 /**
  * Legacy alias for backward compatibility - will be deprecated
  */

package/dist/types/hooks.d.ts

@@ -6,6 +6,7 @@
  */
 export type { WaveConfiguration, HookConfiguration, PartialHookConfiguration, HookConfigurationRecord, } from "./configuration.js";
 export type HookEvent = "PreToolUse" | "PostToolUse" | "UserPromptSubmit" | "Stop" | "SubagentStop" | "PermissionRequest" | "WorktreeCreate" | "WorktreeRemove" | "CwdChanged" | "SessionStart" | "SessionEnd" | "PreCompact" | "PostCompact";
+export declare const HOOK_EVENT_SUMMARIES: Record<HookEvent, string>;
 export interface HookCommand {
     type: "command";
     command: string;

package/dist/types/hooks.js

@@ -4,6 +4,25 @@
  * Provides comprehensive TypeScript types for the Wave Code hooks system,
  * enabling automated actions at specific workflow points.
  */
+// One-line summary per hook event, aligned with Claude Code's
+// HookEventMetadata.summary (hooksConfigManager.ts). Shared by the CLI
+// /hooks detail view and the webview settings hooks page; unknown/plugin
+// events fall back to displaying the event name itself.
+export const HOOK_EVENT_SUMMARIES = {
+    PreToolUse: "Before tool execution",
+    PostToolUse: "After tool execution",
+    UserPromptSubmit: "When the user submits a prompt",
+    Stop: "Right before Claude concludes its response",
+    SubagentStop: "Right before a subagent (Agent tool call) concludes its response",
+    PermissionRequest: "When a permission dialog is displayed",
+    WorktreeCreate: "Create an isolated worktree for VCS-agnostic isolation",
+    WorktreeRemove: "Remove a previously created worktree",
+    CwdChanged: "After the working directory changes",
+    SessionStart: "When a new session is started",
+    SessionEnd: "When a session is ending",
+    PreCompact: "Before conversation compaction",
+    PostCompact: "After conversation compaction",
+};
 // Hook execution errors (non-blocking)
 export class HookExecutionError extends Error {
     constructor(hookCommand, originalError, context) {

package/dist/types/marketplace.d.ts

@@ -3,18 +3,47 @@ export interface MarketplaceOwner {
     name: string;
     email?: string;
 }
+/**
+ * Object form of a plugin entry's `source` (spec plugin A-021): `url` is a whole
+ * repository, `git-subdir` is a subdirectory of one. Both are outside the
+ * marketplace checkout, so they carry no readable local copy for「最新版本」(A-010).
+ */
+export interface MarketplacePluginObjectSource {
+    source: "url" | "git-subdir";
+    url: string;
+    /** Only for `git-subdir`: path of the plugin inside the repository. */
+    path?: string;
+    /** Branch or tag. */
+    ref?: string;
+    /** Pinned commit; checked out after cloning. */
+    sha?: string;
+}
 export interface MarketplacePluginEntry {
     name: string;
-    source: string;
+    source: string | MarketplacePluginObjectSource;
     description: string;
 }
 export interface MarketplacePluginStatus extends MarketplacePluginEntry {
     marketplace: string;
     installed: boolean;
+    /** 已安装版本（未安装时 undefined） */
     version?: string;
+    /**
+     * 市场内该插件当前可安装的最新版本，取自市场检出目录内插件的
+     * `.wave-plugin/plugin.json`（兼容 `.claude-plugin/plugin.json`）。
+     * 插件来源是独立 Git 仓库等无法就地读取清单的情况为 undefined
+     * （spec plugin A-010：此时不展示最新版本）。
+     */
+    latestVersion?: string;
     cachePath?: string;
     projectPath?: string;
     scope?: Scope;
+    /**
+     * 该插件由组织的托管配置（远端托管设置）声明启用：成员不能卸载或禁用它，
+     * 界面据此把卸载入口判为不可用并给出由组织管理的说明（spec plugin A-024）。
+     * 判据只看下发值，本机不落任何标记。
+     */
+    managed?: boolean;
 }
 export interface MarketplaceManifest {
     name: string;
@@ -37,7 +66,6 @@ export interface KnownMarketplace {
     name: string;
     source: MarketplaceSource;
     isBuiltin?: boolean;
-    autoUpdate?: boolean;
     lastUpdated?: string;
     /** The scope where this marketplace was declared (user, project, local, or builtin) */
     declaredScope?: "user" | "project" | "local" | "builtin";
@@ -46,12 +74,22 @@ export interface KnownMarketplacesRegistry {
     builtinSeeded?: boolean;
     marketplaces: KnownMarketplace[];
 }
+/**
+ * 安装产物的记账位置（spec plugin A-015）：用户作用域是本机全局的，不带
+ * projectPath；项目作用域与本地作用域归属某个仓库，以该仓库路径为 projectPath。
+ */
+export interface PluginInstallLocation {
+    scope: Scope;
+    projectPath?: string;
+}
 export interface InstalledPlugin {
     name: string;
     marketplace: string;
     version: string;
     cachePath: string;
+    /** 该条安装记录所属的作用域；引入作用域维度之前写入的历史记录不带此字段（spec plugin A-015）。 */
     scope?: Scope;
+    /** 项目作用域与本地作用域所属仓库的路径；用户作用域不带。 */
     projectPath?: string;
 }
 export interface InstalledPluginsRegistry {

package/dist/types/mcp.d.ts

@@ -19,16 +19,58 @@ export interface McpTool {
     name: string;
     description?: string;
     inputSchema: Record<string, unknown>;
+    /**
+     * The schema the server declared for its *output*, raw as listed. Not passed
+     * through `cleanSchema` like `inputSchema`: that cleaning exists because the
+     * input schema travels inside a request, and this one is only ever rendered as
+     * a return type. Absent for most servers today, and degenerate
+     * (`{ type: "object" }`) when present.
+     */
+    outputSchema?: Record<string, unknown>;
+}
+/**
+ * What one MCP tool call produced. Two audiences, two fields:
+ *
+ * - `content` is the display text the flat path hands the model — a placeholder
+ *   when the tool said nothing (`No content`) or returned only images.
+ * - `output` is what a sandbox `await` resolves to: the server's
+ *   `structuredContent` when it returned one, otherwise its text, otherwise
+ *   `null`. The catalog renders its return types from this same rule, so a
+ *   signature can never promise a shape the sandbox does not deliver.
+ */
+export interface McpToolCallResult {
+    success: boolean;
+    content: string;
+    output: unknown;
+    serverName?: string;
+    images?: Array<{
+        data: string;
+        mediaType?: string;
+    }>;
 }
 export interface McpServerStatus {
     name: string;
     config: McpServerConfig;
     /** Pre-resolution URL with template variables preserved for safe display */
     originalUrl?: string;
+    /** Config source: user (~/.wave/mcp.json), project (<workdir>/.mcp.json),
+     *  or plugin (registered from a plugin manifest) */
+    scope?: "user" | "project" | "plugin";
     status: "disconnected" | "connected" | "connecting" | "reconnecting" | "error";
     tools?: McpTool[];
     toolCount?: number;
     capabilities?: string[];
+    /**
+     * Usage notes the server described about itself during `initialize`
+     * (`instructions`): rate limits, preconditions, how the server is meant to be
+     * used. Server-level prose, announced once in the conversation instead of the
+     * system prompt — see `utils/mcpInstructions.ts` for why, and for the per-server
+     * cap — and already truncated by the time it lands here, unlike a tool
+     * description, which the catalog compresses.
+     * Retained across a reconnecting server (like `tools`) and cleared once the
+     * server is gone, so a dropped server cannot keep talking to the model.
+     */
+    instructions?: string;
     lastConnected?: number;
     error?: string;
 }

package/dist/types/messaging.d.ts

@@ -16,7 +16,7 @@ export interface Message {
     additionalFields?: Record<string, unknown>;
     isMeta?: boolean;
 }
-export type MessageBlock = TextBlock | ErrorBlock | ToolBlock | ImageBlock | BangBlock | CompactBlock | ReasoningBlock | FileHistoryBlock | TaskNotificationBlock;
+export type MessageBlock = TextBlock | ErrorBlock | ToolBlock | ImageBlock | CompactBlock | ReasoningBlock | FileHistoryBlock | TaskNotificationBlock;
 export interface TextBlock {
     type: "text";
     content: string;
@@ -62,13 +62,6 @@ export interface ImageBlock {
     type: "image";
     imageUrls?: string[];
 }
-export interface BangBlock {
-    type: "bang";
-    command: string;
-    output: string;
-    stage: "running" | "end";
-    exitCode: number | null;
-}
 export interface CompactBlock {
     type: "compact";
     content: string;