wave-agent-sdk 1.2.0 → 1.3.0

package/dist/managers/liveConfigManager.js

@@ -7,7 +7,9 @@
  * - Coordination between file watchers and configuration updates
  */
 import { existsSync } from "fs";
+import { dirname } from "path";
 import { FileWatcherService, } from "../services/fileWatcher.js";
+import { USER_MEMORY_FILE } from "../utils/constants.js";
 import { isValidHookEvent } from "../types/hooks.js";
 import { logger } from "../utils/globalLogger.js";
 export class LiveConfigManager {
@@ -18,6 +20,13 @@ export class LiveConfigManager {
         // Configuration state
         this.currentConfiguration = null;
         this.lastValidConfiguration = null;
+        // Turn-scoped snapshot of the settings.json-derived configuration the running
+        // turn reads from. Captured at turn start, dropped at turn end, so a live
+        // reload landing mid-turn takes effect at the next turn instead of shifting
+        // values under the running one (core/agent-config.md scenario 5). Nested turns
+        // (a subagent turn inside its parent's) share the outer snapshot.
+        this.turnSnapshot = null;
+        this.turnDepth = 0;
         this.isWatching = false;
         this.reloadInProgress = false;
         this.workdir = options.workdir;
@@ -33,6 +42,36 @@ export class LiveConfigManager {
     get configurationService() {
         return this.container.get("ConfigurationService");
     }
+    get memoryService() {
+        return this.container.get("MemoryService");
+    }
+    /**
+     * Keep the auto-memory system safe zone in sync with the live auto-memory
+     * toggle (core/agent-config.md scenario 6). Turning auto-memory off must
+     * revoke the privilege its directory got at construction time, and turning it
+     * back on must restore it — both without rebuilding the session. Idempotent:
+     * the underlying add/remove are dedup'ed by path.
+     */
+    syncAutoMemorySafeZone() {
+        const permissionManager = this.permissionManager;
+        const memoryService = this.memoryService;
+        if (!permissionManager || !memoryService) {
+            return;
+        }
+        const directories = [
+            memoryService.getAutoMemoryDirectory(this.workdir),
+            USER_MEMORY_FILE,
+        ];
+        const enabled = this.configurationService.resolveAutoMemoryEnabledNow();
+        for (const directory of directories) {
+            if (enabled) {
+                permissionManager.addSystemAdditionalDirectory(directory);
+            }
+            else {
+                permissionManager.removeSystemAdditionalDirectory(directory);
+            }
+        }
+    }
     /**
      * Initialize configuration watching
      * Maps to FR-004: System MUST watch settings.json files
@@ -44,18 +83,18 @@ export class LiveConfigManager {
             this.projectConfigPaths = projectPaths;
             // Load initial configuration
             await this.reloadConfiguration();
-            // Start watching user configs that exist
+            // Watch every configuration path, including ones that don't exist yet:
+            // chokidar delivers `add` once a missing path appears, but only if its
+            // parent chain exists when watching starts. Skipping absent paths (the
+            // pre-2026-09-10 behavior) silently dropped the very first save of a
+            // user-level settings.json created after session start
+            // (core/agent-config.md scenario 7).
             for (const userPath of userPaths) {
-                if (existsSync(userPath)) {
-                    await this.fileWatcher.watchFile(userPath, (event) => this.handleFileChange(event, "user"));
-                }
+                await this.fileWatcher.watchFile(this.resolveWatchTarget(userPath), (event) => this.handleFileChange(event, "user"));
             }
-            // Start watching local configs that exist
             if (projectPaths) {
                 for (const projectPath of projectPaths) {
-                    if (existsSync(projectPath)) {
-                        await this.fileWatcher.watchFile(projectPath, (event) => this.handleFileChange(event, "project"));
-                    }
+                    await this.fileWatcher.watchFile(this.resolveWatchTarget(projectPath), (event) => this.handleFileChange(event, "project"));
                 }
             }
             this.isWatching = true;
@@ -112,6 +151,41 @@ export class LiveConfigManager {
             throw error;
         }
     }
+    /**
+     * Turn boundary: pin the settings.json-derived configuration for the duration
+     * of a turn (called by AIManager). A live reload may land mid-turn and the
+     * turn must not see it (core/agent-config.md scenario 5) — the change is
+     * picked up by the snapshot taken when the next turn starts. Permission rules,
+     * hooks and env stay live: those are enforcement state and follow the file
+     * immediately.
+     */
+    onTurnStart() {
+        if (this.turnDepth === 0) {
+            const configuration = this.getCurrentConfiguration();
+            this.turnSnapshot = {
+                configuration: configuration ? structuredClone(configuration) : null,
+                // `env` on the merged configuration is exactly what was published as the
+                // session env snapshot when it was loaded (both come from the same
+                // merge), so the snapshot carries both without querying the service.
+                env: { ...(configuration?.env ?? {}) },
+            };
+        }
+        this.turnDepth++;
+    }
+    /** Turn boundary: drop the snapshot so the next turn reads live values. */
+    onTurnEnd() {
+        if (this.turnDepth === 0) {
+            return;
+        }
+        this.turnDepth--;
+        if (this.turnDepth === 0) {
+            this.turnSnapshot = null;
+        }
+    }
+    /** Configuration snapshot of the running turn, or null outside a turn. */
+    getTurnSnapshot() {
+        return this.turnDepth > 0 ? this.turnSnapshot : null;
+    }
     /**
      * Reload configuration from files
      * Maps to FR-008: Continue with previous valid configuration on errors
@@ -176,6 +250,7 @@ export class LiveConfigManager {
                 this.permissionManager.updateAllowedRules(this.currentConfiguration.permissions?.allow || []);
                 this.permissionManager.updateDeniedRules(this.currentConfiguration.permissions?.deny || []);
                 this.permissionManager.updateAdditionalDirectories(this.currentConfiguration.permissions?.additionalDirectories || []);
+                this.syncAutoMemorySafeZone();
             }
             // Trigger reload callback. Awaited so fire-and-forget work spawned by the
             // callback (e.g. skill rediscovery) completes before the reload resolves —
@@ -304,6 +379,26 @@ export class LiveConfigManager {
         }
         return { added, modified, removed };
     }
+    /**
+     * Chokidar only starts watching a non-existent path when its parent directory
+     * exists at watch time (a path whose parents are all missing is never
+     * picked up, not even after they appear). Walk up to the deepest node whose
+     * parent exists and watch that instead — events for its descendants still
+     * reach this path's callback (FileWatcherService matches by path prefix).
+     */
+    resolveWatchTarget(configPath) {
+        let candidate = configPath;
+        while (!existsSync(dirname(candidate))) {
+            const parent = dirname(candidate);
+            if (parent === candidate) {
+                // Reached the filesystem root without an existing parent: nothing to
+                // watch (unreachable for absolute paths).
+                return configPath;
+            }
+            candidate = parent;
+        }
+        return candidate;
+    }
     /**
      * Get configuration file paths for user and project settings
      * Returns paths in priority order (local.json first, then .json)

package/dist/managers/lspManager.d.ts

@@ -21,6 +21,14 @@ export declare class LspManager implements ILspManager {
     constructor(container: Container);
     initialize(workdir: string): Promise<void>;
     registerServer(language: string, config: LspServerConfig): void;
+    /**
+     * Drop every LSP server contributed by a plugin (matched on pluginRoot),
+     * stopping any process already started for those languages so the next
+     * request starts the reloaded command instead of reusing the stale one.
+     * Called by the in-place plugin reload path before re-registering.
+     * @returns the number of servers removed
+     */
+    unregisterServersForPlugin(pluginRoot: string): Promise<number>;
     private loadConfig;
     getProcessForFile(filePath: string): Promise<LspProcess | null>;
     private startServer;
@@ -36,6 +44,7 @@ export declare class LspManager implements ILspManager {
         success: boolean;
         content: string;
     }>;
+    private stopProcess;
     cleanup(): Promise<void>;
 }
 export {};

package/dist/managers/lspManager.js

@@ -17,6 +17,32 @@ export class LspManager {
         this.config[language] = config;
         logger?.debug(`Registered LSP server for ${language}`);
     }
+    /**
+     * Drop every LSP server contributed by a plugin (matched on pluginRoot),
+     * stopping any process already started for those languages so the next
+     * request starts the reloaded command instead of reusing the stale one.
+     * Called by the in-place plugin reload path before re-registering.
+     * @returns the number of servers removed
+     */
+    async unregisterServersForPlugin(pluginRoot) {
+        let removed = 0;
+        for (const [language, config] of Object.entries(this.config)) {
+            if (config.pluginRoot !== pluginRoot) {
+                continue;
+            }
+            delete this.config[language];
+            const lspProc = this.processes.get(language);
+            if (lspProc) {
+                this.processes.delete(language);
+                await this.stopProcess(language, lspProc);
+            }
+            removed += 1;
+        }
+        if (removed > 0) {
+            logger?.debug(`Unregistered ${removed} LSP servers for plugin root ${pluginRoot}`);
+        }
+        return removed;
+    }
     async loadConfig() {
         const lspJsonPath = join(this.workdir, ".lsp.json");
         try {
@@ -326,27 +352,30 @@ export class LspManager {
             return { success: false, content: `LSP error: ${JSON.stringify(error)}` };
         }
     }
-    async cleanup() {
-        for (const [language, lspProc] of this.processes.entries()) {
-            try {
-                // Try graceful shutdown
-                const timeout = lspProc.config.shutdownTimeout || 2000;
-                await this.sendRequest(lspProc, "shutdown", {}, timeout);
-                await this.sendNotification(lspProc, "exit", {});
-                // Give it a moment to exit
-                if (timeout > 100) {
-                    await new Promise((resolve) => setTimeout(resolve, 100));
-                }
-            }
-            catch (error) {
-                logger?.debug(`Failed to gracefully shutdown LSP for ${language}: ${error}`);
+    async stopProcess(language, lspProc) {
+        try {
+            // Try graceful shutdown
+            const timeout = lspProc.config.shutdownTimeout || 2000;
+            await this.sendRequest(lspProc, "shutdown", {}, timeout);
+            await this.sendNotification(lspProc, "exit", {});
+            // Give it a moment to exit
+            if (timeout > 100) {
+                await new Promise((resolve) => setTimeout(resolve, 100));
             }
-            finally {
-                if (!lspProc.process.killed) {
-                    lspProc.process.kill();
-                }
+        }
+        catch (error) {
+            logger?.debug(`Failed to gracefully shutdown LSP for ${language}: ${error}`);
+        }
+        finally {
+            if (!lspProc.process.killed) {
+                lspProc.process.kill();
             }
         }
+    }
+    async cleanup() {
+        for (const [language, lspProc] of this.processes.entries()) {
+            await this.stopProcess(language, lspProc);
+        }
         this.processes.clear();
     }
 }

package/dist/managers/mcpManager.d.ts

@@ -1,7 +1,7 @@
 import { ChatCompletionFunctionTool } from "openai/resources.js";
 import type { ToolPlugin, ToolResult, ToolContext } from "../tools/types.js";
 import { Container } from "../utils/container.js";
-import type { Logger, McpServerConfig, McpConfig, McpTool, McpServerStatus } from "../types/index.js";
+import type { Logger, McpServerConfig, McpConfig, McpTool, McpToolCallResult, McpServerStatus } from "../types/index.js";
 export interface McpManagerCallbacks {
     onMcpServersChange?: (servers: McpServerStatus[]) => void;
 }
@@ -69,9 +69,37 @@ export declare class McpManager {
     getConfig(): McpConfig | null;
     getAllServers(): McpServerStatus[];
     getServer(name: string): McpServerStatus | undefined;
+    /**
+     * The usage notes each usable server described about itself (`initialize`'s
+     * `instructions`), for the announcement appended to the conversation.
+     *
+     * "Usable" is the same predicate `getAllConnectedTools` uses — connected, or
+     * reconnecting with its last-known snapshot retained — so a server's prose is
+     * visible exactly while its tools are. A server that dropped, failed to connect
+     * or went to `error` keeps its snapshot but stops being reported here, which is
+     * what keeps a dead server from still talking to the model.
+     *
+     * `isDenied` receives flattened tool names (`mcp__server__tool`, the shape
+     * permission rules match on); a server whose tools are *all* excluded by rules is
+     * dropped whole, so prose cannot reach the context after the user ruled the
+     * server out. A server exposing no tools at all is still reported: nothing was
+     * excluded, it is simply a server that brings context rather than tools.
+     */
+    getServerInstructions(isDenied?: (toolName: string) => boolean): Array<{
+        name: string;
+        instructions: string;
+    }>;
     updateServerStatus(name: string, updates: Partial<McpServerStatus>): void;
     addServer(name: string, config: McpServerConfig): boolean;
     removeServer(name: string): boolean;
+    /**
+     * Drop every MCP server contributed by a plugin (matched on pluginRoot),
+     * disconnecting each one. Needed instead of re-adding under the same name
+     * because addServer refuses a name that is already registered.
+     * Called by the in-place plugin reload path before re-registering.
+     * @returns the number of servers removed
+     */
+    removeServersForPlugin(pluginRoot: string): number;
     /**
      * Remove a server from a persisted config file (user or project scope),
      * then disconnect and drop it from the in-memory registry.
@@ -94,15 +122,7 @@ export declare class McpManager {
     private cancelReconnect;
     disconnectServer(name: string): Promise<boolean>;
     getAllConnectedTools(): McpTool[];
-    executeMcpTool(toolName: string, args: Record<string, unknown>, context?: ToolContext): Promise<{
-        success: boolean;
-        content: string;
-        serverName?: string;
-        images?: Array<{
-            data: string;
-            mediaType?: string;
-        }>;
-    }>;
+    executeMcpTool(toolName: string, args: Record<string, unknown>, context?: ToolContext): Promise<McpToolCallResult>;
     private executeToolOnConnection;
     cleanup(): Promise<void>;
     /**
@@ -113,6 +133,21 @@ export declare class McpManager {
      * Get all currently available MCP tools as OpenAI function tools
      */
     getMcpToolsConfig(): ChatCompletionFunctionTool[];
+    /**
+     * Declared output schema per flattened tool name, for the Exec catalog's return
+     * types.
+     *
+     * A separate accessor because `getMcpToolsConfig()` cannot carry it: an OpenAI
+     * function declaration has room for `parameters` and nothing else, so the schema
+     * a server declared for its *output* has no field to travel in. Correlated with
+     * the same `findToolServer` lookup `getMcpToolPlugins` uses and keyed with the
+     * same `mcpToolFlatName`, so the two agree on which server owns a tool.
+     *
+     * Servers that declare no output schema are simply absent, which renders as
+     * `Promise<unknown>`: honest about the call returning *something* of unspecified
+     * shape.
+     */
+    getMcpToolOutputSchemas(): Map<string, Record<string, unknown>>;
     /**
      * Execute an MCP tool by name (registry version)
      */

package/dist/managers/mcpManager.js

@@ -5,7 +5,8 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { createMcpToolPlugin, findToolServer } from "../utils/mcpUtils.js";
+import { createMcpToolPlugin, findToolServer, mcpToolFlatName, } from "../utils/mcpUtils.js";
+import { truncateMcpInstructions } from "../utils/mcpInstructions.js";
 import { logger } from "../utils/globalLogger.js";
 /**
  * Expand environment variables in a string value.
@@ -283,6 +284,38 @@ export class McpManager {
     getServer(name) {
         return this.servers.get(name);
     }
+    /**
+     * The usage notes each usable server described about itself (`initialize`'s
+     * `instructions`), for the announcement appended to the conversation.
+     *
+     * "Usable" is the same predicate `getAllConnectedTools` uses — connected, or
+     * reconnecting with its last-known snapshot retained — so a server's prose is
+     * visible exactly while its tools are. A server that dropped, failed to connect
+     * or went to `error` keeps its snapshot but stops being reported here, which is
+     * what keeps a dead server from still talking to the model.
+     *
+     * `isDenied` receives flattened tool names (`mcp__server__tool`, the shape
+     * permission rules match on); a server whose tools are *all* excluded by rules is
+     * dropped whole, so prose cannot reach the context after the user ruled the
+     * server out. A server exposing no tools at all is still reported: nothing was
+     * excluded, it is simply a server that brings context rather than tools.
+     */
+    getServerInstructions(isDenied) {
+        const result = [];
+        for (const server of this.servers.values()) {
+            const usable = server.status === "connected" || server.status === "reconnecting";
+            const instructions = server.instructions?.trim();
+            if (!usable || !instructions)
+                continue;
+            const tools = server.tools ?? [];
+            if (tools.length > 0 &&
+                tools.every((tool) => isDenied?.(mcpToolFlatName(server.name, tool.name)))) {
+                continue;
+            }
+            result.push({ name: server.name, instructions });
+        }
+        return result;
+    }
     updateServerStatus(name, updates) {
         const server = this.servers.get(name);
         if (server) {
@@ -353,6 +386,27 @@ export class McpManager {
         }
         return removed;
     }
+    /**
+     * Drop every MCP server contributed by a plugin (matched on pluginRoot),
+     * disconnecting each one. Needed instead of re-adding under the same name
+     * because addServer refuses a name that is already registered.
+     * Called by the in-place plugin reload path before re-registering.
+     * @returns the number of servers removed
+     */
+    removeServersForPlugin(pluginRoot) {
+        let removed = 0;
+        for (const [name, server] of Array.from(this.servers.entries())) {
+            if (server.config.pluginRoot !== pluginRoot) {
+                continue;
+            }
+            this.removeServer(name);
+            removed += 1;
+        }
+        if (removed > 0) {
+            logger?.debug(`Removed ${removed} MCP servers for plugin root ${pluginRoot}`);
+        }
+        return removed;
+    }
     /**
      * Remove a server from a persisted config file (user or project scope),
      * then disconnect and drop it from the in-memory registry.
@@ -400,6 +454,9 @@ export class McpManager {
             let transport;
             let client;
             let tools = [];
+            // Server-level usage notes from `initialize`; part of the connection's
+            // handshake, so it is read once here rather than re-requested later.
+            let instructions;
             const createClient = () => new Client({
                 name: "wave-code",
                 version: "1.0.0",
@@ -419,12 +476,14 @@ export class McpManager {
                 });
                 client = createClient();
                 await client.connect(transport);
+                instructions = truncateMcpInstructions(client.getInstructions());
                 const toolsResponse = await client.listTools();
                 tools =
                     toolsResponse.tools?.map((tool) => ({
                         name: tool.name,
                         description: tool.description,
                         inputSchema: tool.inputSchema,
+                        outputSchema: tool.outputSchema,
                     })) || [];
                 logger?.info(`Connected to MCP server ${name} using Streamable HTTP`);
             }
@@ -440,12 +499,14 @@ export class McpManager {
                 });
                 client = createClient();
                 await client.connect(transport);
+                instructions = truncateMcpInstructions(client.getInstructions());
                 const toolsResponse = await client.listTools();
                 tools =
                     toolsResponse.tools?.map((tool) => ({
                         name: tool.name,
                         description: tool.description,
                         inputSchema: tool.inputSchema,
+                        outputSchema: tool.outputSchema,
                     })) || [];
                 logger?.info(`Connected to MCP server ${name} using SSE`);
             }
@@ -517,12 +578,14 @@ export class McpManager {
                     logger?.debug(`[MCP Server ${name}] Server stderr: ${stderrOutput.trim()}`);
                     stderrOutput = "";
                 }
+                instructions = truncateMcpInstructions(client.getInstructions());
                 const toolsResponse = await client.listTools();
                 tools =
                     toolsResponse.tools?.map((tool) => ({
                         name: tool.name,
                         description: tool.description,
                         inputSchema: tool.inputSchema,
+                        outputSchema: tool.outputSchema,
                     })) || [];
             }
             else if (serverType) {
@@ -568,6 +631,7 @@ export class McpManager {
                     status: "disconnected",
                     tools: [],
                     toolCount: 0,
+                    instructions: undefined,
                 });
                 // Auto-reconnect with exponential backoff. Skipped while an explicit
                 // disconnectServer teardown is in flight — that close is expected, and
@@ -588,6 +652,7 @@ export class McpManager {
                 tools,
                 toolCount: tools.length,
                 capabilities: ["tools"],
+                instructions,
                 lastConnected: Date.now(),
                 error: undefined,
             });
@@ -651,6 +716,7 @@ export class McpManager {
                     name: tool.name,
                     description: tool.description,
                     inputSchema: tool.inputSchema,
+                    outputSchema: tool.outputSchema,
                 })) || [];
                 logger?.info(`MCP Server ${name} auto-reconnected successfully (attempt ${i + 1})`);
                 this.updateServerStatus(name, {
@@ -692,6 +758,7 @@ export class McpManager {
                     status: "disconnected",
                     tools: [],
                     toolCount: 0,
+                    instructions: undefined,
                     error: undefined,
                 });
             }
@@ -716,6 +783,7 @@ export class McpManager {
                 status: "disconnected",
                 tools: [],
                 toolCount: 0,
+                instructions: undefined,
                 error: undefined,
             });
             return true;
@@ -732,6 +800,7 @@ export class McpManager {
                 status: "disconnected",
                 tools: [],
                 toolCount: 0,
+                instructions: undefined,
                 error: error instanceof Error ? error.message : String(error),
             });
             return false;
@@ -823,9 +892,17 @@ export class McpManager {
                 : images.length > 0
                     ? `Tool returned ${images.length} image(s).`
                     : "No content";
+            // The sandbox's value, decided from the text parts rather than from
+            // `textContentStr`: that one carries display placeholders ("No content"),
+            // and a script has to be able to tell "the tool said nothing" (`null`) from
+            // "the tool said 'No content'". Same rule the catalog renders return types
+            // from: structured, else text, else null.
+            const text = textContent.join("\n");
+            const output = result.structuredContent ?? (text === "" ? null : text);
             return {
                 success: true,
                 content: textContentStr,
+                output,
                 images: images.length > 0 ? images : undefined,
                 serverName,
             };
@@ -869,6 +946,31 @@ export class McpManager {
     getMcpToolsConfig() {
         return this.getMcpToolPlugins().map((tool) => tool.config);
     }
+    /**
+     * Declared output schema per flattened tool name, for the Exec catalog's return
+     * types.
+     *
+     * A separate accessor because `getMcpToolsConfig()` cannot carry it: an OpenAI
+     * function declaration has room for `parameters` and nothing else, so the schema
+     * a server declared for its *output* has no field to travel in. Correlated with
+     * the same `findToolServer` lookup `getMcpToolPlugins` uses and keyed with the
+     * same `mcpToolFlatName`, so the two agree on which server owns a tool.
+     *
+     * Servers that declare no output schema are simply absent, which renders as
+     * `Promise<unknown>`: honest about the call returning *something* of unspecified
+     * shape.
+     */
+    getMcpToolOutputSchemas() {
+        const schemas = new Map();
+        const servers = this.getAllServers();
+        for (const tool of this.getAllConnectedTools()) {
+            const server = findToolServer(tool.name, servers);
+            if (server && tool.outputSchema) {
+                schemas.set(mcpToolFlatName(server.name, tool.name), tool.outputSchema);
+            }
+        }
+        return schemas;
+    }
     /**
      * Execute an MCP tool by name (registry version)
      */