wave-agent-sdk 1.2.0 → 1.3.0

package/dist/utils/convertMessagesForAPI.js

@@ -1,3 +1,4 @@
+import { imageFileCacheKey, planOutboundImage } from "./imageRewrite.js";
 import { convertImageToBase64 } from "./messageOperations.js";
 import { taskNotificationToXml } from "./notificationXml.js";
 import { recoverTruncatedJson, stripAnsiColors } from "./stringUtils.js";
@@ -35,11 +36,17 @@ function safeToolArguments(args) {
 /**
  * Convert message format to API call format, stopping when a compacted message is encountered.
  * Messages with no meaningful content or tool calls are filtered out.
+ *
+ * Async because every outbound image is routed through `planOutboundImage`,
+ * which may have to re-encode an oversized image with the optional `sharp`
+ * codec (`utils/imageRewrite.ts`). Images that are already inside the budget —
+ * the common case — take a synchronous fast path and come out byte-identical.
+ *
  * @param messages Message list
  * @param options Optional conversion options (e.g. supportsVision)
  * @returns Converted API message format list
  */
-export function convertMessagesForAPI(messages, options) {
+export async function convertMessagesForAPI(messages, options) {
     const supportsVision = options?.supportsVision !== false;
     const recentMessages = [];
     const startIndex = messages.length - 1;
@@ -70,7 +77,7 @@ export function convertMessagesForAPI(messages, options) {
             if (toolBlocks.length > 0) {
                 // Collect image user messages to place after all tool messages
                 const imageUserMessages = [];
-                toolBlocks.forEach((toolBlock) => {
+                for (const toolBlock of toolBlocks) {
                     // Only add completed tool blocks (i.e., stage is 'end')
                     if (toolBlock.id && toolBlock.stage === "end") {
                         completedToolIds.add(toolBlock.id);
@@ -84,18 +91,34 @@ export function convertMessagesForAPI(messages, options) {
                         if (toolBlock.images && toolBlock.images.length > 0) {
                             if (supportsVision) {
                                 const contentParts = [];
-                                toolBlock.images.forEach((image) => {
+                                for (const image of toolBlock.images) {
                                     const imageUrl = image.data.startsWith("data:")
                                         ? image.data
                                         : `data:${image.mediaType || "image/png"};base64,${image.data}`;
+                                    // Tool-produced images (Read screenshots, MCP results, Exec
+                                    // output) go through the same outbound budget as attachments:
+                                    // an image the gateway would reject is shrunk, or omitted with
+                                    // an actionable note, instead of failing the whole request.
+                                    const plan = await planOutboundImage({
+                                        dataUrl: imageUrl,
+                                        cacheKey: imageUrl,
+                                        sourcePath: image.path,
+                                    });
+                                    if (plan.kind === "omit") {
+                                        contentParts.push({ type: "text", text: plan.note });
+                                        continue;
+                                    }
                                     contentParts.push({
                                         type: "image_url",
                                         image_url: {
-                                            url: imageUrl,
+                                            url: plan.dataUrl,
                                             detail: "auto",
                                         },
                                     });
-                                });
+                                    if (plan.note) {
+                                        contentParts.push({ type: "text", text: plan.note });
+                                    }
+                                }
                                 imageUserMessages.push({
                                     role: "user",
                                     content: contentParts,
@@ -129,7 +152,7 @@ export function convertMessagesForAPI(messages, options) {
                             }
                         }
                     }
-                });
+                }
                 // Insert image user messages after all tool messages but before the
                 // assistant message (which will be unshifted next). Since tool messages
                 // were unshifted to the front, we splice images right after them.
@@ -218,7 +241,7 @@ export function convertMessagesForAPI(messages, options) {
         else if (message.role === "user") {
             // User messages converted to standard format
             const contentParts = [];
-            message.blocks.forEach((block) => {
+            for (const block of message.blocks) {
                 // Add text content - only if it has meaningful content
                 if (block.type === "text" &&
                     block.content &&
@@ -253,28 +276,55 @@ export function convertMessagesForAPI(messages, options) {
                         });
                     }
                     else {
-                        block.imageUrls.forEach((imageUrl) => {
+                        for (const imageUrl of block.imageUrls) {
                             // Check if it's already base64, convert if not
                             const isDataUrl = imageUrl.startsWith("data:image/");
                             let finalImageUrl = imageUrl;
                             if (!isDataUrl) {
-                                // If it's a file path, it needs to be converted to base64
+                                // If it's a file path, it needs to be converted to base64.
+                                // Unreadable/empty/unknown-format files come back as
+                                // undefined: skip the image rather than send an empty payload.
+                                let converted;
                                 try {
-                                    finalImageUrl = convertImageToBase64(imageUrl);
+                                    converted = convertImageToBase64(imageUrl);
                                 }
                                 catch (error) {
                                     logger.error("Failed to convert image path to base64:", imageUrl, error);
                                     // Skip this image, do not add to content
-                                    return;
+                                    continue;
                                 }
+                                if (!converted) {
+                                    logger.warn("Skipping unusable image file:", imageUrl);
+                                    continue;
+                                }
+                                finalImageUrl = converted;
+                            }
+                            // Outbound budget: an image the vision gateway would reject, or
+                            // one over our own size budget, is shrunk here (or replaced by an
+                            // actionable note when it cannot be). See utils/imageRewrite.ts.
+                            const plan = await planOutboundImage({
+                                dataUrl: finalImageUrl,
+                                cacheKey: isDataUrl
+                                    ? finalImageUrl
+                                    : imageFileCacheKey(imageUrl),
+                                sourcePath: isDataUrl ? undefined : imageUrl,
+                            });
+                            if (plan.kind === "omit") {
+                                contentParts.push({ type: "text", text: plan.note });
+                                continue;
                             }
                             contentParts.push({
                                 type: "image_url",
                                 image_url: {
-                                    url: finalImageUrl,
+                                    url: plan.dataUrl,
                                     detail: "auto",
                                 },
                             });
+                            // Tell the model when the image it sees is not the full-size
+                            // original, so it can map coordinates back.
+                            if (plan.note) {
+                                contentParts.push({ type: "text", text: plan.note });
+                            }
                             // Aligned with Claude Code: when the image comes from a local
                             // file (not an inline dataURL), append its source path as text
                             // metadata so the model can reference the file with tools
@@ -285,7 +335,7 @@ export function convertMessagesForAPI(messages, options) {
                                     text: `[Image source: ${imageUrl}]`,
                                 });
                             }
-                        });
+                        }
                     }
                 }
                 // If there is a tool block in user message, add its result
@@ -302,7 +352,7 @@ export function convertMessagesForAPI(messages, options) {
                         text: `A background agent completed a task:\n${taskNotificationToXml(block)}`,
                     });
                 }
-            });
+            }
             // Only add user message if there is meaningful content
             if (contentParts.length > 0) {
                 // Filter out empty text parts

package/dist/utils/fileChangeReminder.d.ts

@@ -0,0 +1,20 @@
+import type { ReadFileState } from "../tools/types.js";
+/** Max number of changed files reported in a single reminder. */
+export declare const CHANGED_FILES_MAX_FILES = 10;
+/** Max bytes of the changed-lines snippet rendered for a single file. */
+export declare const CHANGED_FILES_SNIPPET_MAX_BYTES = 2048;
+/** Max bytes of the whole reminder (all reported files combined). */
+export declare const CHANGED_FILES_TOTAL_MAX_BYTES = 8192;
+/**
+ * Build a compact "what changed" snippet from the new file content: trim the
+ * common prefix/suffix, then render the differing region with line numbers.
+ * A deletion-only region renders as a removal note. Truncates at a line
+ * boundary to `maxBytes`. Returns "" when the contents are identical.
+ */
+export declare function buildChangedSnippet(oldContent: string, newContent: string, maxBytes?: number): string;
+/**
+ * Detect files that changed on disk since they were read and return a reminder
+ * body for the agent, or null when nothing changed. Refreshes the read state
+ * for every detected change (see the module comment).
+ */
+export declare function getChangedFilesReminder(readFileState: ReadFileState | undefined): Promise<string | null>;

package/dist/utils/fileChangeReminder.js

@@ -0,0 +1,153 @@
+/**
+ * External file-change detection for the main agent loop (aligned with Claude
+ * Code's `changed_files` attachment).
+ *
+ * For every file recorded in the session read state by a *full* read/write,
+ * this compares the on-disk mtime against the mtime recorded at read time and,
+ * when the file is newer AND the content actually differs, produces a short
+ * changed-lines summary. The read state entry is then refreshed to the new
+ * mtime/hash/content so that (a) the same change is reported only once, and
+ * (b) a subsequent Edit/Write passes the staleness check — the agent has just
+ * been told the new content.
+ *
+ * The writers this surfaces are the ones other than the main agent: the
+ * auto-memory extraction fork, an external editor, another session. The main
+ * agent's own Write/Edit refresh the read state on write, so they never show up
+ * here.
+ */
+import { readFile, stat } from "node:fs/promises";
+import { createHash } from "node:crypto";
+/** Max number of changed files reported in a single reminder. */
+export const CHANGED_FILES_MAX_FILES = 10;
+/** Max bytes of the changed-lines snippet rendered for a single file. */
+export const CHANGED_FILES_SNIPPET_MAX_BYTES = 2048;
+/** Max bytes of the whole reminder (all reported files combined). */
+export const CHANGED_FILES_TOTAL_MAX_BYTES = 8192;
+function sha256(text) {
+    return createHash("sha256").update(text).digest("hex");
+}
+/** UTF-8 byte length — CJK content is ~3 bytes/char, so `.length` would under-count. */
+function byteLength(text) {
+    return Buffer.byteLength(text, "utf-8");
+}
+/**
+ * Build a compact "what changed" snippet from the new file content: trim the
+ * common prefix/suffix, then render the differing region with line numbers.
+ * A deletion-only region renders as a removal note. Truncates at a line
+ * boundary to `maxBytes`. Returns "" when the contents are identical.
+ */
+export function buildChangedSnippet(oldContent, newContent, maxBytes = CHANGED_FILES_SNIPPET_MAX_BYTES) {
+    const oldLines = oldContent.replace(/\r\n/g, "\n").split("\n");
+    const newLines = newContent.replace(/\r\n/g, "\n").split("\n");
+    const shared = Math.min(oldLines.length, newLines.length);
+    let prefix = 0;
+    while (prefix < shared && oldLines[prefix] === newLines[prefix])
+        prefix++;
+    let suffix = 0;
+    const maxSuffix = shared - prefix;
+    while (suffix < maxSuffix &&
+        oldLines[oldLines.length - 1 - suffix] ===
+            newLines[newLines.length - 1 - suffix]) {
+        suffix++;
+    }
+    const changedOld = oldLines.slice(prefix, oldLines.length - suffix);
+    const changedNew = newLines.slice(prefix, newLines.length - suffix);
+    if (changedOld.length === 0 && changedNew.length === 0)
+        return "";
+    if (changedNew.length === 0) {
+        const plural = changedOld.length === 1 ? "line" : "lines";
+        return `(${changedOld.length} ${plural} removed at line ${prefix + 1})`;
+    }
+    const rendered = [];
+    let used = 0;
+    let truncated = 0;
+    for (let i = 0; i < changedNew.length; i++) {
+        const line = `${String(prefix + i + 1).padStart(4, " ")} | ${changedNew[i]}`;
+        const cost = byteLength(line) + 1; // + trailing newline
+        if (used + cost > maxBytes) {
+            truncated = changedNew.length - i;
+            break;
+        }
+        rendered.push(line);
+        used += cost;
+    }
+    let snippet = rendered.join("\n");
+    if (truncated > 0) {
+        snippet += `\n... [${truncated} lines truncated] ...`;
+    }
+    return snippet;
+}
+/**
+ * Detect files that changed on disk since they were read and return a reminder
+ * body for the agent, or null when nothing changed. Refreshes the read state
+ * for every detected change (see the module comment).
+ */
+export async function getChangedFilesReminder(readFileState) {
+    if (!readFileState || readFileState.size === 0)
+        return null;
+    const blocks = [];
+    let totalBytes = 0;
+    for (const [filePath, state] of readFileState) {
+        if (blocks.length >= CHANGED_FILES_MAX_FILES)
+            break;
+        // Partial reads cache only a slice — no reliable diff baseline.
+        if (state.offset !== undefined || state.limit !== undefined)
+            continue;
+        let mtimeMs;
+        let newContent;
+        try {
+            const stats = await stat(filePath);
+            mtimeMs = stats.mtime.getTime();
+            // Not newer than the recorded mtime → untouched, or touched by the main
+            // agent's own Write/Edit (which refreshes the entry to the post-write mtime).
+            if (mtimeMs <= state.mtime)
+                continue;
+            newContent = await readFile(filePath, "utf-8");
+        }
+        catch {
+            // Deleted or transiently unreadable — leave the entry alone and move on.
+            continue;
+        }
+        // Refresh the baseline so the same observation is not re-processed on every
+        // turn and a subsequent Edit passes the staleness check (the agent has just
+        // been told the new content).
+        const refresh = () => {
+            readFileState.set(filePath, {
+                mtime: mtimeMs,
+                hash: sha256(newContent),
+                source: "changed",
+                content: newContent,
+                offset: undefined,
+                limit: undefined,
+            });
+        };
+        const oldContent = state.content;
+        // No baseline, or the file was touched but its content is unchanged
+        // (git checkout / editor round-trip save / cloud sync / antivirus).
+        if (oldContent === undefined || oldContent === newContent) {
+            refresh();
+            continue;
+        }
+        const snippet = buildChangedSnippet(oldContent, newContent);
+        if (!snippet) {
+            refresh();
+            continue;
+        }
+        const block = `${filePath}\n${snippet}`;
+        if (totalBytes + byteLength(block) > CHANGED_FILES_TOTAL_MAX_BYTES) {
+            // Leave the entry un-refreshed so the change is reported on a later turn
+            // rather than silently dropped.
+            break;
+        }
+        refresh();
+        blocks.push(block);
+        totalBytes += byteLength(block);
+    }
+    if (blocks.length === 0)
+        return null;
+    return [
+        "The following files were modified on disk since you last read them — by another process such as a background agent, an external editor, or another session. Your earlier read of these files is out of date; re-read a file before editing it if the changed lines below are not enough.",
+        "",
+        blocks.join("\n\n"),
+    ].join("\n");
+}

package/dist/utils/fileSearch.js

@@ -1,5 +1,5 @@
 import { spawn } from "child_process";
-import { rgPath } from "./ripgrep.js";
+import { getRgPath } from "./ripgrep.js";
 import fuzzysort from "fuzzysort";
 import { logger } from "./globalLogger.js";
 const EXCLUDED_FILES = [".git", ".DS_Store"];
@@ -7,12 +7,13 @@ const EXCLUDED_FILES = [".git", ".DS_Store"];
  * Execute ripgrep to get all file paths
  */
 async function getAllFiles(workingDirectory) {
-    if (!rgPath) {
+    const rgBinary = getRgPath();
+    if (!rgBinary) {
         throw new Error("ripgrep is not available");
     }
     const rgArgs = ["--files", "--color=never", "--hidden"];
     return new Promise((resolve, reject) => {
-        const child = spawn(rgPath, rgArgs, {
+        const child = spawn(rgBinary, rgArgs, {
             cwd: workingDirectory,
             stdio: ["ignore", "pipe", "pipe"],
         });

package/dist/utils/fileUtils.d.ts

@@ -13,6 +13,25 @@ export declare function readFirstLine(filePath: string): Promise<string>;
  * @return {Promise<string[]>} - Array of non-empty lines (up to maxLines).
  */
 export declare function readFirstNLines(filePath: string, maxLines: number): Promise<string[]>;
+/**
+ * Streams a file line by line without holding it in memory.
+ *
+ * Splits on `\n` and hands each segment to `onLine`; a trailing `\r` is left
+ * for the callback's own `trim()`. When the file does not end with a newline,
+ * the trailing partial segment is delivered too, so callers can apply the same
+ * "interrupted append" tolerance `JsonlHandler.read()` uses — its
+ * `endsWithNewline` flag is exactly the return value here.
+ *
+ * Memory stays at one line: chunks are consumed as they arrive and are not
+ * accumulated.
+ *
+ * @param {string} filePath - The path to the file.
+ * @param {(line: string) => void | Promise<void>} onLine - Called per segment, in file order.
+ * @return {Promise<{ endsWithNewline: boolean }>} - Whether the file ended with a newline (empty files count as true).
+ */
+export declare function forEachLine(filePath: string, onLine: (line: string) => void | Promise<void>): Promise<{
+    endsWithNewline: boolean;
+}>;
 /**
  * Reads a file from the end and returns the last non-empty line.
  *
@@ -37,6 +56,20 @@ export declare function getLastLine(filePath: string, minLength?: number): Promi
  * @return {Promise<string[]>} - Trailing non-empty lines, or [] if unreadable.
  */
 export declare function readTailLines(filePath: string, maxBytes?: number): Promise<string[]>;
+/**
+ * Synchronously read up to `maxBytes` from the end of a file and return the
+ * raw tail text (blank lines preserved). When the window starts mid-line the
+ * partial first line is dropped, so the result holds complete lines only.
+ *
+ * Synchronous on purpose: the caller (`BackgroundTaskManager.getOutput`) sits
+ * on the synchronous `getBackgroundTaskOutput` path that hosts and the CLI
+ * already consume. The window is capped, so the blocking read stays small.
+ *
+ * @param {string} filePath - The path to the file.
+ * @param {number} maxBytes - Size of the tail window (default 64KB).
+ * @return {string} - Tail text, or "" when the file is empty or unreadable.
+ */
+export declare function readTailTextSync(filePath: string, maxBytes?: number): string;
 /**
  * Suggests similar paths if a file is not found.
  */

package/dist/utils/fileUtils.js

@@ -1,4 +1,5 @@
 import fs from "node:fs/promises";
+import fsSync from "node:fs";
 import { createReadStream } from "node:fs";
 import path from "node:path";
 import { glob } from "glob";
@@ -68,6 +69,44 @@ export async function readFirstNLines(filePath, maxLines) {
         fileStream.destroy();
     }
 }
+/**
+ * Streams a file line by line without holding it in memory.
+ *
+ * Splits on `\n` and hands each segment to `onLine`; a trailing `\r` is left
+ * for the callback's own `trim()`. When the file does not end with a newline,
+ * the trailing partial segment is delivered too, so callers can apply the same
+ * "interrupted append" tolerance `JsonlHandler.read()` uses — its
+ * `endsWithNewline` flag is exactly the return value here.
+ *
+ * Memory stays at one line: chunks are consumed as they arrive and are not
+ * accumulated.
+ *
+ * @param {string} filePath - The path to the file.
+ * @param {(line: string) => void | Promise<void>} onLine - Called per segment, in file order.
+ * @return {Promise<{ endsWithNewline: boolean }>} - Whether the file ended with a newline (empty files count as true).
+ */
+export async function forEachLine(filePath, onLine) {
+    const fileStream = createReadStream(filePath, { encoding: "utf8" });
+    try {
+        let carry = "";
+        for await (const chunk of fileStream) {
+            carry += chunk;
+            let newlineIndex = carry.indexOf("\n");
+            while (newlineIndex !== -1) {
+                await onLine(carry.slice(0, newlineIndex));
+                carry = carry.slice(newlineIndex + 1);
+                newlineIndex = carry.indexOf("\n");
+            }
+        }
+        if (carry.length > 0) {
+            await onLine(carry);
+        }
+        return { endsWithNewline: carry.length === 0 };
+    }
+    finally {
+        fileStream.destroy();
+    }
+}
 /**
  * Reads a file from the end and returns the last non-empty line.
  *
@@ -173,6 +212,48 @@ export async function readTailLines(filePath, maxBytes = 64 * 1024) {
         }
     }
 }
+/**
+ * Synchronously read up to `maxBytes` from the end of a file and return the
+ * raw tail text (blank lines preserved). When the window starts mid-line the
+ * partial first line is dropped, so the result holds complete lines only.
+ *
+ * Synchronous on purpose: the caller (`BackgroundTaskManager.getOutput`) sits
+ * on the synchronous `getBackgroundTaskOutput` path that hosts and the CLI
+ * already consume. The window is capped, so the blocking read stays small.
+ *
+ * @param {string} filePath - The path to the file.
+ * @param {number} maxBytes - Size of the tail window (default 64KB).
+ * @return {string} - Tail text, or "" when the file is empty or unreadable.
+ */
+export function readTailTextSync(filePath, maxBytes = 64 * 1024) {
+    let fd;
+    try {
+        const fileSize = fsSync.statSync(filePath).size;
+        if (fileSize === 0)
+            return "";
+        const readSize = Math.min(maxBytes, fileSize);
+        const start = fileSize - readSize;
+        const buffer = Buffer.alloc(readSize);
+        fd = fsSync.openSync(filePath, "r");
+        const bytesRead = fsSync.readSync(fd, buffer, 0, readSize, start);
+        const text = buffer.subarray(0, bytesRead).toString("utf8");
+        if (start === 0)
+            return text;
+        // The window began mid-line, so its first line is partial (and may start
+        // with a byte-truncated multibyte character): drop it.
+        const firstNewline = text.indexOf("\n");
+        return firstNewline === -1 ? "" : text.slice(firstNewline + 1);
+    }
+    catch {
+        // Missing file, permissions, race with deletion: no tail to show.
+        return "";
+    }
+    finally {
+        if (fd !== undefined) {
+            fsSync.closeSync(fd);
+        }
+    }
+}
 /**
  * Simple Levenshtein distance implementation
  */

package/dist/utils/frontmatterYaml.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared YAML frontmatter reader for wave's markdown artifacts: skills
+ * (SKILL.md), subagents, custom slash commands, memory rules and memory files.
+ *
+ * Wave ships no YAML dependency, so this is a hand-rolled parser for the subset
+ * those files actually use: `key: value`, block lists (`key:` + indented
+ * `- item`), block scalars (`key: >-` / `key: |` and their chomping variants)
+ * and indented multi-line plain scalars. Block scalars matter in practice — a
+ * folded `description: >-` used to be read as the literal string ">-", which
+ * silently threw away the whole "when to use this" text (see spec
+ * `ecosystem/agent-skills` 场景 2, `multi-agent/subagent` 场景 6,
+ * `ui/slash-commands` 场景 3, `core/memory-management` 场景 4/13).
+ *
+ * Values are strings or string arrays only — no boolean/number coercion — so
+ * callers comparing against `"true"` or `parseInt`-ing the value keep working.
+ */
+export type FrontmatterValue = string | string[];
+export type ParsedFrontmatter = Record<string, FrontmatterValue>;
+/**
+ * Split a markdown file into its leading `---` frontmatter block and the body.
+ * `yaml` is null when the file has no frontmatter; the body is then the whole
+ * content, untrimmed.
+ */
+export declare function splitFrontmatter(content: string): {
+    yaml: string | null;
+    body: string;
+};
+/**
+ * Parse a frontmatter block (without the `---` delimiters) into key/value
+ * pairs. Unparseable input yields an empty object; callers that require fields
+ * report the missing ones themselves.
+ */
+export declare function parseFrontmatterYaml(yamlContent: string): ParsedFrontmatter;