wave-agent-sdk 1.1.5 → 1.3.0

package/dist/tools/bashTool.js

@@ -11,6 +11,7 @@ import { processToolResult } from "../utils/toolResultStorage.js";
 import { BASH_MAX_OUTPUT_CHARS } from "../constants/toolLimits.js";
 import { BASH_TOOL_NAME, GLOB_TOOL_NAME, GREP_TOOL_NAME, READ_TOOL_NAME, EDIT_TOOL_NAME, WRITE_TOOL_NAME, } from "../constants/tools.js";
 const BASH_DEFAULT_TIMEOUT_MS = 120000;
+const BASH_MAX_TIMEOUT_MS = 600000;
 // After the shell exits, its last stdout/stderr chunks may still be in flight:
 // Node emits the child's 'exit' event as soon as the process terminates, then
 // delivers the remaining pipe data on a later event-loop turn and finally
@@ -64,7 +65,7 @@ export const bashTool = {
                     },
                     timeout: {
                         type: "number",
-                        description: "Optional timeout in milliseconds (max 600000)",
+                        description: `Optional timeout in milliseconds (max ${BASH_MAX_TIMEOUT_MS})`,
                     },
                     description: {
                         type: "string",
@@ -102,7 +103,7 @@ Before executing the command, please follow these steps:
 
 Usage notes:
   - The command argument is required.
-  - You can specify an optional timeout in milliseconds (up to ${BASH_DEFAULT_TIMEOUT_MS}ms / ${BASH_DEFAULT_TIMEOUT_MS / 60000} minutes). If not specified, commands will timeout after ${BASH_DEFAULT_TIMEOUT_MS}ms (${BASH_DEFAULT_TIMEOUT_MS / 60000} minutes).
+  - You may specify an optional timeout in milliseconds (up to ${BASH_MAX_TIMEOUT_MS}ms / ${BASH_MAX_TIMEOUT_MS / 60000} minutes). By default, your command will timeout after ${BASH_DEFAULT_TIMEOUT_MS}ms (${BASH_DEFAULT_TIMEOUT_MS / 60000} minutes).
   - It is very helpful if you write a clear, concise description of what this command does in 5-10 words.
   - If the output exceeds ${BASH_MAX_OUTPUT_CHARS.toLocaleString()} characters, output will be truncated and the full output will be persisted to a file you can read with the Read tool.
   - You can use the \`run_in_background\` parameter to run the command in the background, which allows you to continue working while the command runs. You can monitor the output using the ${READ_TOOL_NAME} tool as it becomes available. You do not need to use '&' at the end of the command when using this parameter.
@@ -179,13 +180,14 @@ The working directory persists between commands. Try to maintain your current wo
                     : "No suitable shell found. Please ensure bash or zsh is installed, or set WAVE_SHELL environment variable.",
             };
         }
-        // Validate timeout
-        if (timeout !== undefined &&
-            (typeof timeout !== "number" || timeout < 0 || timeout > 600000)) {
+        // Validate the timeout's type only. An upper bound is deliberately not
+        // enforced (matching Claude Code, which leaves the type check to its zod
+        // schema and applies whatever value the model sends).
+        if (timeout !== undefined && (typeof timeout !== "number" || timeout < 0)) {
             return {
                 success: false,
                 content: "",
-                error: "Timeout must be a number between 0 and 600000 milliseconds",
+                error: "Timeout must be a non-negative number of milliseconds",
             };
         }
         // Permission check after validation but before real operation
@@ -413,6 +415,7 @@ The working directory persists between commands. Try to maintain your current wo
                                 ? `${processedOutput}\n\n${reason}`
                                 : reason,
                         error: reason,
+                        metadata: { exitCode: 130 },
                     });
                 }
             };
@@ -554,6 +557,7 @@ The working directory persists between commands. Try to maintain your current wo
                     error: exitCode !== 0
                         ? `Command failed with exit code: ${exitCode}`
                         : undefined,
+                    metadata: { exitCode },
                 });
             };
             child.on("exit", (code) => {

package/dist/tools/editTool.js

@@ -1,6 +1,7 @@
-import { readFile, writeFile, stat } from "fs/promises";
+import { readFile, stat } from "fs/promises";
 import { createHash } from "crypto";
 import { logger } from "../utils/globalLogger.js";
+import { atomicWriteFile } from "../utils/atomicWrite.js";
 import { resolvePath, getDisplayPath } from "../utils/path.js";
 import { escapeRegExp, analyzeEditMismatch } from "../utils/editUtils.js";
 import { EDIT_TOOL_NAME, READ_TOOL_NAME } from "../constants/tools.js";
@@ -221,9 +222,10 @@ Usage:
             if (context.reversionManager && context.messageId) {
                 snapshotId = await context.reversionManager.recordSnapshot(context.messageId, resolvedPath, "modify");
             }
-            // 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, newContent, "utf-8");
+                await atomicWriteFile(resolvedPath, newContent);
                 // Commit snapshot on success
                 if (context.reversionManager && snapshotId) {
                     await context.reversionManager.commitSnapshot(snapshotId);
@@ -244,6 +246,7 @@ Usage:
                     mtime: newStats.mtime.getTime(),
                     hash,
                     source: "edit",
+                    content: newContent,
                     offset: undefined,
                     limit: undefined,
                 });

package/dist/tools/execTool.d.ts

@@ -0,0 +1,2 @@
+import type { ToolPlugin } from "./types.js";
+export declare const execTool: ToolPlugin;

package/dist/tools/execTool.js

@@ -0,0 +1,165 @@
+import { EXEC_TOOL_NAME } from "../constants/tools.js";
+import { EXEC_RESERVED_NAMESPACE } from "../exec/constants.js";
+import { buildExecPool } from "../exec/catalog.js";
+import { runExecScript } from "../exec/execRuntime.js";
+/**
+ * The `search` bullet of the sandbox API blurb. It names the entry point and stops
+ * there: the call form is taught by the catalog announcement, and only while the
+ * catalog is actually truncated. Printing it here would advertise a search on every
+ * turn, complete catalog or not — the tool has no idea how many tools exist.
+ *
+ * The path is derived from the reserved namespace, the same constant the sandbox
+ * builds its `tools` object from, so the two cannot drift.
+ */
+const SEARCH_ENTRY = `- \`tools[${JSON.stringify(EXEC_RESERVED_NAMESPACE)}].search(...)\` — ` +
+    "search the whole pool from inside the script.";
+/**
+ * Model-visible API description.
+ *
+ * Static on purpose, and not merely "no tunable limits in it": it must be identical
+ * for any tool pool. `tools[]` sits in the cached prefix, so a description that
+ * mentioned the MCP servers (or their tools) would rewrite that prefix every time a
+ * server connected or dropped. The catalog is a tail announcement instead — see
+ * `exec/catalogAnnouncement.ts`.
+ */
+const EXEC_DESCRIPTION = `Run a JavaScript script in a sandbox where every MCP tool of this session is exposed as a function, so a whole sequence of MCP calls can be composed in a single turn instead of one model round-trip per call.
+
+Sandbox API:
+- \`await tools.<name>(args)\` — call an MCP tool, passing that tool's own arguments object directly. Resolves to the tool's output: its \`structuredContent\` object when it returned one, otherwise its text, otherwise \`null\`. The catalog gives each tool's return type.
+${SEARCH_ENTRY}
+- \`console.log(...)\` — collected and returned alongside the result. Use it to inspect intermediate values.
+- \`return <value>\` — the returned value is JSON-serialized and given back to you.
+
+It is very helpful if you write a clear, concise description of what this script does in 5-10 words.
+
+Which MCP tools are reachable is announced in the conversation as the catalog changes. The script has no filesystem, no network, no \`import\`, and no \`eval\`/\`new Function\`. It stops when it exceeds its time or tool-call budget. Every nested MCP call goes through the normal permission check, so it can still be denied — a denied call rejects with the reason.`;
+/**
+ * How many of the most recent nested calls the result summary lists, mirroring
+ * how the `Agent` tool lists the subagent tools it just ran.
+ */
+const RECENT_CALLS_SHOWN = 2;
+/**
+ * The collapsed result row: the call count, then the most recent calls by name.
+ *
+ * Names only — MCP tools have no compact-params summary of their own, and a
+ * flat MCP call's collapsed row shows just the name. No "Exec" prefix either:
+ * the row this text sits in already prints the tool name.
+ *
+ * Derived from the calls the sandbox actually issued, so it can be rendered
+ * mid-run as well as at the end.
+ */
+function formatSummary(calls) {
+    const count = calls.length;
+    const lines = [
+        `${count > RECENT_CALLS_SHOWN ? "... " : ""}${count} tool call${count === 1 ? "" : "s"}`,
+    ];
+    for (const name of calls.slice(-RECENT_CALLS_SHOWN)) {
+        lines.push(name);
+    }
+    return lines.join("\n");
+}
+function formatRun(result, calls) {
+    const lines = [];
+    if (result.logs.length > 0) {
+        lines.push(result.logs.join("\n"));
+    }
+    if (result.ok) {
+        if (result.value !== undefined && result.value !== "undefined") {
+            lines.push(result.value);
+        }
+        else if (lines.length === 0) {
+            lines.push("Exec finished without a return value or console output.");
+        }
+    }
+    else {
+        lines.push(result.error ?? "Exec script failed");
+    }
+    const content = lines.join("\n");
+    return {
+        success: result.ok,
+        content,
+        ...(result.ok ? {} : { error: result.error }),
+        shortResult: result.ok ? formatSummary(calls) : "failed",
+        ...(result.images.length > 0 ? { images: result.images } : {}),
+    };
+}
+export const execTool = {
+    name: EXEC_TOOL_NAME,
+    // Nested calls reach arbitrary MCP tools, which are conservatively non-safe.
+    isConcurrencySafe: false,
+    config: {
+        type: "function",
+        function: {
+            name: EXEC_TOOL_NAME,
+            description: EXEC_DESCRIPTION,
+            parameters: {
+                type: "object",
+                properties: {
+                    code: {
+                        type: "string",
+                        description: "JavaScript to run in the sandbox. It may `await` tool calls and `return` a value.",
+                    },
+                    description: {
+                        type: "string",
+                        description: "Clear, concise description of what this script does in 5-10 words.",
+                    },
+                },
+                required: ["code"],
+            },
+        },
+    },
+    prompt: () => EXEC_DESCRIPTION,
+    /**
+     * The parameter slot of the collapsed row, shared by the TUI and the desktop
+     * UI: the model's own one-line summary of the script, taken verbatim — no
+     * prefix (the row already prints `Exec`), no rewrite, no truncation.
+     *
+     * `Bash` can fall back to the command string; a script has no equivalent, and
+     * the first line of a multi-line blob usually says nothing, so an absent or
+     * empty description leaves the slot blank rather than inventing text. What the
+     * script actually did is the result slot's job (`formatSummary`).
+     *
+     * Deliberately reads nothing but the argument: no code scan, no pool, no
+     * catalog, so the preview cannot claim a call the script never makes.
+     */
+    formatCompactParams: (params) => {
+        const description = params.description;
+        return typeof description === "string" ? description : "";
+    },
+    execute: async (args, context) => {
+        const code = typeof args.code === "string" ? args.code : "";
+        if (code.trim().length === 0) {
+            return {
+                success: false,
+                content: "",
+                error: `${EXEC_TOOL_NAME}: missing required parameter "code"`,
+            };
+        }
+        const mcpManager = context.mcpManager;
+        if (!mcpManager) {
+            return {
+                success: false,
+                content: "",
+                error: `${EXEC_TOOL_NAME}: MCP manager is not available in this session`,
+            };
+        }
+        // Recomputed here rather than reused from the declaration-time catalog: a
+        // server may have connected or dropped since. Both are derived from the same
+        // `buildExecPool`, so the sandbox can never reach a tool the agent could not
+        // already call directly.
+        const pool = buildExecPool(mcpManager, context.permissionManager);
+        const calls = [];
+        const result = await runExecScript({
+            code,
+            pool,
+            context,
+            // Report each call as it is issued, so the collapsed row shows what the
+            // script is doing while it runs — the same live update the Agent tool does.
+            onToolCall: (name) => {
+                calls.push(name);
+                context.onShortResultUpdate?.(formatSummary(calls));
+            },
+        });
+        return formatRun(result, calls);
+    },
+};

package/dist/tools/exitPlanMode.js

@@ -2,6 +2,11 @@ import { readFile } from "fs/promises";
 import { logger } from "../utils/globalLogger.js";
 import { EXIT_PLAN_MODE_TOOL_NAME } from "../constants/tools.js";
 import { OPERATION_CANCELLED_BY_USER } from "../types/permissions.js";
+// Rejection feedback format aligned with Claude Code (messages.ts):
+// the model reads the fixed prefix + the user's verbatim feedback, without
+// any additional prompt injection.
+const REJECT_MESSAGE = "The user doesn't want to proceed with this tool use. The tool use was rejected (eg. if it was a file edit, the new_string was NOT written to the file). STOP what you are doing and wait for the user to tell you how to proceed.";
+const REJECT_MESSAGE_WITH_REASON_PREFIX = "The user doesn't want to proceed with this tool use. The tool use was rejected (eg. if it was a file edit, the new_string was NOT written to the file). To tell you how to proceed, the user said:\n";
 /**
  * Exit Plan Mode Tool Plugin
  */
@@ -90,10 +95,13 @@ Ensure your plan is complete and unambiguous:
                         content: OPERATION_CANCELLED_BY_USER,
                     };
                 }
+                const feedback = permissionResult.message?.trim();
                 return {
                     success: false,
-                    content: `Please update your proposal based on the following user feedback: ${permissionResult.message || "Plan rejected by user"}`,
-                    error: permissionResult.message ? undefined : "Plan rejected by user",
+                    content: feedback
+                        ? `${REJECT_MESSAGE_WITH_REASON_PREFIX}${feedback}`
+                        : REJECT_MESSAGE,
+                    error: feedback ? undefined : "Plan rejected by user",
                 };
             }
             context.permissionManager.setHasExitedPlanMode(true);

package/dist/tools/grepTool.js

@@ -1,5 +1,6 @@
 import { spawn } from "child_process";
-import { rgPath } from "../utils/ripgrep.js";
+import { getRgPath } from "../utils/ripgrep.js";
+import { ensureRuntimeDeps } from "../utils/runtimeDeps.js";
 import { getDisplayPath } from "../utils/path.js";
 import { logger } from "../utils/globalLogger.js";
 import { GREP_TOOL_NAME, BASH_TOOL_NAME, AGENT_TOOL_NAME, } from "../constants/tools.js";
@@ -122,7 +123,12 @@ export const grepTool = {
                 error: "pattern parameter is required and must be a string",
             };
         }
+        // Resolved per call, not at import time: the CLI installs this dependency
+        // itself, possibly after the module graph has been evaluated.
+        const rgPath = getRgPath();
         if (!rgPath) {
+            // Cover the entry points that do not await the installer at startup.
+            void ensureRuntimeDeps();
             return {
                 success: false,
                 content: "",

package/dist/tools/readTool.js

@@ -7,6 +7,8 @@ import { formatLineNumberPrefix } from "../utils/stringUtils.js";
 import { estimateTokens } from "../utils/tokenEstimate.js";
 import { isBinaryDocument, getBinaryDocumentError, } from "../utils/fileFormat.js";
 import { convertImageToBase64 } from "../utils/messageOperations.js";
+import { isPathInside } from "../utils/pathSafety.js";
+import { memoryFreshnessNote } from "../utils/memoryAge.js";
 import { READ_TOOL_NAME } from "../constants/tools.js";
 /**
  * Supported image file extensions
@@ -88,6 +90,15 @@ async function processImageFile(filePath, context) {
         }
         // Convert image to base64
         const imageDataUrl = convertImageToBase64(actualFilePath);
+        if (!imageDataUrl) {
+            // Unreadable, empty or unknown-format file: fail instead of handing the
+            // model an empty image payload.
+            return {
+                success: false,
+                content: "",
+                error: `Failed to process image: ${getDisplayPath(filePath, context.workdir)} is empty or not a readable image file`,
+            };
+        }
         const mimeType = getImageMimeType(actualFilePath);
         // Extract base64 data from data URL (remove data:image/type;base64, prefix)
         const base64Data = imageDataUrl.split(",")[1] || "";
@@ -254,8 +265,17 @@ Usage:
                     source: "read",
                     offset, // undefined for full reads
                     limit, // undefined for full reads
+                    // Retain the raw content only for full reads: it is the diff baseline
+                    // for the external-change notification, and partial entries are
+                    // excluded from that comparison anyway.
+                    ...(offset === undefined && limit === undefined
+                        ? { content: fileContent }
+                        : {}),
                 });
             }
+            // A successful read may pull in the memory files of its ancestor
+            // directories (see `collectNestedMemoryFiles`); only Read triggers this.
+            context.messageManager?.triggerNestedMemory(actualFilePath);
             // Check if file is empty
             if (fileContent.length === 0) {
                 logger.warn(`File ${filePath} exists but has empty contents`);
@@ -315,8 +335,16 @@ Usage:
                     },
                 };
             }
-            // Add file information header
-            let content = `File: ${filePath}\n`;
+            // Add file information header. A file inside the auto-memory directory
+            // gets a staleness note in front of it: memory is a point-in-time
+            // observation, and a stale `file:line` citation reads as authoritative.
+            // `autoMemoryDir` is unset when auto-memory is off, so the note can never
+            // fire for a disabled feature.
+            const memoryNote = context.autoMemoryDir &&
+                isPathInside(actualFilePath, context.autoMemoryDir)
+                ? memoryFreshnessNote(stats.mtime.getTime())
+                : "";
+            let content = `${memoryNote}File: ${filePath}\n`;
             if (startLine > 1 || endLine < totalLines) {
                 content += `Lines ${startLine}-${endLine} of ${totalLines}\n`;
             }

package/dist/tools/types.d.ts

@@ -5,6 +5,32 @@ import { ChatCompletionFunctionTool } from "openai/resources.js";
 import type { PermissionMode, PermissionCallback } from "../types/permissions.js";
 import type { SubagentConfiguration } from "../utils/subagentParser.js";
 import type { SkillMetadata } from "../types/skills.js";
+/**
+ * Read state recorded for a file by the Read/Write/Edit tools. Used for
+ * read-before-write enforcement, staleness detection, Read dedup, and the
+ * external-change notification (diffing `content` against the disk).
+ */
+export interface ReadFileStateEntry {
+    /** File mtime (ms) observed when this entry was recorded. */
+    mtime: number;
+    /** sha256 of the content observed when this entry was recorded. */
+    hash: string;
+    /**
+     * Which tool recorded the entry. Read dedups only entries from Read;
+     * "changed" is recorded when an external change was observed and reported.
+     */
+    source: "read" | "edit" | "write" | "changed";
+    /**
+     * Content observed when this entry was recorded (full reads and writes
+     * only). Serves as the diff baseline for the external-change notification.
+     */
+    content?: string;
+    /** Line offset the entry was recorded at; undefined = full read. */
+    offset?: number;
+    limit?: number;
+}
+/** Per-session read state keyed by resolved absolute path. */
+export type ReadFileState = Map<string, ReadFileStateEntry>;
 export interface ToolPlugin {
     name: string;
     config: ChatCompletionFunctionTool;
@@ -46,7 +72,7 @@ export interface ToolContext {
     abortSignal?: AbortSignal;
     backgroundTaskManager?: import("../managers/backgroundTaskManager.js").BackgroundTaskManager;
     workdir: string;
-    /** Tool manager instance for tool discovery (used by ToolSearchTool) */
+    /** Tool manager instance, for tools that need to change session tool state */
     toolManager?: import("../managers/toolManager.js").ToolManager;
     /** Permission mode for this tool execution */
     permissionMode?: PermissionMode;
@@ -92,13 +118,7 @@ export interface ToolContext {
         maxTokens: number;
     };
     /** State of files read in the current session for deduplication */
-    readFileState?: Map<string, {
-        mtime: number;
-        hash: string;
-        source: "read" | "edit" | "write";
-        offset?: number;
-        limit?: number;
-    }>;
+    readFileState?: ReadFileState;
     /** Hook manager instance for executing hooks */
     hookManager?: import("../managers/hookManager.js").HookManager;
     /** Callback to notify when the current working directory changes */
@@ -114,4 +134,10 @@ export interface ToolContext {
      * the subprocess without polluting other sessions in one stdio process.
      */
     sessionEnv?: Record<string, string>;
+    /**
+     * Auto-memory directory for this session, or undefined when auto-memory is
+     * off. Read uses it to prepend a staleness note to files inside it — leaving
+     * it unset is what keeps that note off when the feature is disabled.
+     */
+    autoMemoryDir?: string;
 }