wave-agent-sdk 1.2.0 → 1.3.0

package/dist/utils/markdownParser.js

@@ -5,64 +5,22 @@ import { join } from "path";
 import { tmpdir } from "os";
 import { SKILL_BASH_MAX_OUTPUT_CHARS, PREVIEW_SIZE_BYTES, } from "../constants/toolLimits.js";
 import { logger } from "./globalLogger.js";
+import { parseFrontmatterYaml, splitFrontmatter } from "./frontmatterYaml.js";
 import { resolveShellPath } from "./shellResolver.js";
 const execAsync = promisify(exec);
 /**
- * Parse YAML frontmatter from markdown content
+ * Parse YAML frontmatter from markdown content.
+ *
+ * Value parsing is shared with skills, subagents and memory files — see
+ * `frontmatterYaml.ts` (spec `ui/slash-commands` 场景 3,
+ * `core/memory-management` 场景 4/13).
  */
 export function parseFrontmatter(content) {
-    const frontmatterRegex = /^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$/;
-    const match = content.match(frontmatterRegex);
-    if (!match) {
-        return { content };
-    }
-    const [, frontmatterStr, bodyContent] = match;
-    try {
-        // Simple YAML parser for our use case (supports key: value and list items)
-        const frontmatter = {};
-        const lines = frontmatterStr.split("\n");
-        let currentKey = null;
-        for (const line of lines) {
-            const trimmedLine = line.trim();
-            if (!trimmedLine || trimmedLine.startsWith("#"))
-                continue;
-            // Check if it's a list item
-            if (trimmedLine.startsWith("-") && currentKey) {
-                let value = trimmedLine.slice(1).trim();
-                if (value) {
-                    // Remove surrounding quotes if present
-                    if ((value.startsWith('"') && value.endsWith('"')) ||
-                        (value.startsWith("'") && value.endsWith("'"))) {
-                        value = value.slice(1, -1);
-                    }
-                    if (!Array.isArray(frontmatter[currentKey])) {
-                        frontmatter[currentKey] = [];
-                    }
-                    frontmatter[currentKey].push(value);
-                }
-                continue;
-            }
-            const colonIndex = trimmedLine.indexOf(":");
-            if (colonIndex === -1)
-                continue;
-            const key = trimmedLine.slice(0, colonIndex).trim();
-            const value = trimmedLine.slice(colonIndex + 1).trim();
-            currentKey = key;
-            if (value) {
-                // Remove surrounding quotes if present
-                const unquotedValue = (value.startsWith('"') && value.endsWith('"')) ||
-                    (value.startsWith("'") && value.endsWith("'"))
-                    ? value.slice(1, -1)
-                    : value;
-                frontmatter[key] = unquotedValue;
-            }
-        }
-        return { frontmatter, content: bodyContent };
-    }
-    catch {
-        // If parsing fails, just return the content without frontmatter
+    const { yaml, body } = splitFrontmatter(content);
+    if (yaml === null) {
         return { content };
     }
+    return { frontmatter: parseFrontmatterYaml(yaml), content: body };
 }
 /**
  * Parse markdown file and extract config and content

package/dist/utils/mcpInstructions.d.ts

@@ -0,0 +1,61 @@
+/**
+ * MCP server usage notes, announced in the conversation instead of the system
+ * prompt (aligned with Claude Code's `mcp_instructions_delta` attachment).
+ *
+ * A server's `initialize.instructions` is the one channel for "you need to know
+ * this without calling anything" content: rate limits, preconditions, whole-server
+ * conventions. It cannot ride in a tool description — the catalog compresses those
+ * — and it must not ride in the system prompt: it appears only when a connection
+ * happens, and a connection that happens mid-session would rewrite the whole
+ * cached prefix (that is exactly the note Claude Code left on the system-prompt
+ * variant it replaced: "busts the prompt cache on late MCP connect").
+ *
+ * So each server's notes are announced once, as a persisted meta message appended
+ * at the tail. Two consequences are deliberate:
+ *  - History is not rewritten, so a disconnection cannot take the prose back out
+ *    of the context. It gets a "no longer applies" notice instead.
+ *  - The announced set is derived from the history itself (a marker line), not
+ *    from process state, so there is nothing to desync: if the marker is no longer
+ *    there (compaction, rewind), the next turn announces the server again. A
+ *    duplicate is better than a loss.
+ */
+import type { Message } from "../types/messaging.js";
+/**
+ * Per-server cap on announced notes, in characters. Borrowed from Claude Code's
+ * `MAX_MCP_DESCRIPTION_LENGTH` (`services/mcp/client.ts`), which caps both MCP tool
+ * descriptions and server instructions at this value. Counted in characters like
+ * CC, not CJK-aware: what MCP servers write about themselves is overwhelmingly
+ * English, the same assumption the catalog budget makes.
+ */
+export declare const MCP_INSTRUCTIONS_MAX_CHARS = 2048;
+/** What one announcement carries: who appeared, who went away. */
+export interface McpInstructionsDelta {
+    added: Array<{
+        name: string;
+        instructions: string;
+    }>;
+    removed: string[];
+}
+/**
+ * Bound a server's notes to the cap, marking the cut so the model knows it is
+ * reading an incomplete copy rather than a short one.
+ */
+export declare function truncateMcpInstructions(raw: string | undefined): string | undefined;
+/**
+ * Servers whose notes the history already contains: markers are folded in message
+ * order, so an announced server that later went away stops counting as announced
+ * (and is announced again if it comes back).
+ *
+ * Only the scanner's own messages are read. A marker quoted anywhere else — a
+ * reply explaining the mechanism, a hook echoing one — is prose *about* a marker,
+ * not a statement of connection state. Counting it invents an announcement, and
+ * the invented server is then reported as departed as soon as it is unavailable.
+ */
+export declare function collectAnnouncedServers(messages: Message[]): Set<string>;
+/**
+ * Render one announcement, or null when there is nothing to say. The marker line
+ * leads so the scan reads state without parsing the prose, and the prose keeps
+ * opencode's `<mcp_instructions>` envelope so notes stay distinguishable per
+ * server and verbatim per line.
+ */
+export declare function buildMcpInstructionsAnnouncement(delta: McpInstructionsDelta): string | null;

package/dist/utils/mcpInstructions.js

@@ -0,0 +1,126 @@
+/**
+ * MCP server usage notes, announced in the conversation instead of the system
+ * prompt (aligned with Claude Code's `mcp_instructions_delta` attachment).
+ *
+ * A server's `initialize.instructions` is the one channel for "you need to know
+ * this without calling anything" content: rate limits, preconditions, whole-server
+ * conventions. It cannot ride in a tool description — the catalog compresses those
+ * — and it must not ride in the system prompt: it appears only when a connection
+ * happens, and a connection that happens mid-session would rewrite the whole
+ * cached prefix (that is exactly the note Claude Code left on the system-prompt
+ * variant it replaced: "busts the prompt cache on late MCP connect").
+ *
+ * So each server's notes are announced once, as a persisted meta message appended
+ * at the tail. Two consequences are deliberate:
+ *  - History is not rewritten, so a disconnection cannot take the prose back out
+ *    of the context. It gets a "no longer applies" notice instead.
+ *  - The announced set is derived from the history itself (a marker line), not
+ *    from process state, so there is nothing to desync: if the marker is no longer
+ *    there (compaction, rewind), the next turn announces the server again. A
+ *    duplicate is better than a loss.
+ */
+/**
+ * Per-server cap on announced notes, in characters. Borrowed from Claude Code's
+ * `MAX_MCP_DESCRIPTION_LENGTH` (`services/mcp/client.ts`), which caps both MCP tool
+ * descriptions and server instructions at this value. Counted in characters like
+ * CC, not CJK-aware: what MCP servers write about themselves is overwhelmingly
+ * English, the same assumption the catalog budget makes.
+ */
+export const MCP_INSTRUCTIONS_MAX_CHARS = 2048;
+/** Marks an announcement message so the history scan can find it. */
+const MARKER_PREFIX = "<!-- mcp-instructions ";
+const MARKER_SUFFIX = " -->";
+/**
+ * Bound a server's notes to the cap, marking the cut so the model knows it is
+ * reading an incomplete copy rather than a short one.
+ */
+export function truncateMcpInstructions(raw) {
+    if (raw === undefined || raw.length <= MCP_INSTRUCTIONS_MAX_CHARS) {
+        return raw;
+    }
+    return `${raw.slice(0, MCP_INSTRUCTIONS_MAX_CHARS)}… [truncated]`;
+}
+/**
+ * Servers whose notes the history already contains: markers are folded in message
+ * order, so an announced server that later went away stops counting as announced
+ * (and is announced again if it comes back).
+ *
+ * Only the scanner's own messages are read. A marker quoted anywhere else — a
+ * reply explaining the mechanism, a hook echoing one — is prose *about* a marker,
+ * not a statement of connection state. Counting it invents an announcement, and
+ * the invented server is then reported as departed as soon as it is unavailable.
+ */
+export function collectAnnouncedServers(messages) {
+    const announced = new Set();
+    for (const message of messages) {
+        if (message.isMeta !== true)
+            continue;
+        for (const block of message.blocks) {
+            if (block.type !== "text")
+                continue;
+            for (const line of block.content.split("\n")) {
+                const delta = parseMarkerLine(line);
+                if (!delta)
+                    continue;
+                for (const name of delta.added)
+                    announced.add(name);
+                for (const name of delta.removed)
+                    announced.delete(name);
+            }
+        }
+    }
+    return announced;
+}
+function parseMarkerLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith(MARKER_PREFIX) || !trimmed.endsWith(MARKER_SUFFIX)) {
+        return null;
+    }
+    const payload = trimmed.slice(MARKER_PREFIX.length, trimmed.length - MARKER_SUFFIX.length);
+    try {
+        const parsed = JSON.parse(payload);
+        return {
+            added: Array.isArray(parsed.added) ? parsed.added.map(String) : [],
+            removed: Array.isArray(parsed.removed) ? parsed.removed.map(String) : [],
+        };
+    }
+    catch {
+        // A marker we cannot read (hand-edited or corrupted history) must not take
+        // the turn down; the worst case is announcing that server once more.
+        return null;
+    }
+}
+/**
+ * Render one announcement, or null when there is nothing to say. The marker line
+ * leads so the scan reads state without parsing the prose, and the prose keeps
+ * opencode's `<mcp_instructions>` envelope so notes stay distinguishable per
+ * server and verbatim per line.
+ */
+export function buildMcpInstructionsAnnouncement(delta) {
+    if (delta.added.length === 0 && delta.removed.length === 0)
+        return null;
+    const parts = [
+        `${MARKER_PREFIX}${JSON.stringify({
+            added: delta.added.map((server) => server.name),
+            removed: delta.removed,
+        })}${MARKER_SUFFIX}`,
+    ];
+    if (delta.added.length > 0) {
+        parts.push("The following MCP servers have provided instructions for how to use their tools and resources:", "", renderEnvelope(delta.added));
+    }
+    if (delta.removed.length > 0) {
+        parts.push("The following MCP servers have disconnected. Their instructions above no longer apply:", ...delta.removed);
+    }
+    return parts.join("\n");
+}
+function renderEnvelope(servers) {
+    return [
+        "<mcp_instructions>",
+        ...servers.flatMap((server) => [
+            `  <server name="${server.name}">`,
+            ...server.instructions.split("\n").map((line) => `    ${line}`),
+            "  </server>",
+        ]),
+        "</mcp_instructions>",
+    ].join("\n");
+}

package/dist/utils/mcpUtils.d.ts

@@ -1,6 +1,13 @@
 import { ChatCompletionFunctionTool } from "openai/resources.js";
 import type { ToolPlugin, ToolContext } from "../tools/types.js";
 import type { McpTool, McpServerStatus } from "../types/index.js";
+/**
+ * The flattened name an MCP tool is declared and called under.
+ *
+ * Single source of truth: `McpManager.executeMcpTool` parses names in this
+ * shape back into (server, tool), so every producer must agree exactly.
+ */
+export declare function mcpToolFlatName(serverName: string, toolName: string): string;
 /**
  * Convert MCP tool to OpenAI function tool format
  */

package/dist/utils/mcpUtils.js

@@ -36,12 +36,21 @@ function cleanSchema(schema) {
     }
     return newSchema;
 }
+/**
+ * The flattened name an MCP tool is declared and called under.
+ *
+ * Single source of truth: `McpManager.executeMcpTool` parses names in this
+ * shape back into (server, tool), so every producer must agree exactly.
+ */
+export function mcpToolFlatName(serverName, toolName) {
+    return `mcp__${serverName}__${toolName}`;
+}
 /**
  * Convert MCP tool to OpenAI function tool format
  */
 export function mcpToolToOpenAITool(mcpTool, serverName) {
     const cleanInputSchema = cleanSchema(mcpTool.inputSchema);
-    const prefixedName = `mcp__${serverName}__${mcpTool.name}`;
+    const prefixedName = mcpToolFlatName(serverName, mcpTool.name);
     return {
         type: "function",
         function: {
@@ -55,7 +64,7 @@ export function mcpToolToOpenAITool(mcpTool, serverName) {
  * Create a tool plugin wrapper for an MCP tool
  */
 export function createMcpToolPlugin(mcpTool, serverName, executeTool) {
-    const prefixedName = `mcp__${serverName}__${mcpTool.name}`;
+    const prefixedName = mcpToolFlatName(serverName, mcpTool.name);
     return {
         name: prefixedName,
         config: mcpToolToOpenAITool(mcpTool, serverName),

package/dist/utils/memoryAge.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Staleness annotations for auto-memory files.
+ *
+ * A memory is a point-in-time observation, so its `file:line` citations and
+ * symbol names can silently rot as the code moves on. A stale claim that
+ * carries a citation reads as *more* authoritative, not less, so the age has to
+ * be stated explicitly when the file is read.
+ *
+ * Aligned with Claude Code's `memdir/memoryAge.ts`.
+ */
+/**
+ * Days elapsed since mtime, floor-rounded — 0 for today, 1 for yesterday, 2+
+ * for older. Negative inputs (future mtime, clock skew) clamp to 0.
+ */
+export declare function memoryAgeDays(mtimeMs: number): number;
+/**
+ * Plain-text staleness caveat for memories more than a day old, or `""` for
+ * fresh ones (warning there is noise). Models are poor at date arithmetic — a
+ * raw ISO timestamp does not trigger staleness reasoning the way "47 days ago"
+ * does.
+ *
+ * Only the day count is derived from the clock, so the text is byte-stable
+ * within a day: re-reading the same file at the same mtime cannot change the
+ * bytes in the conversation history.
+ */
+export declare function memoryFreshnessText(mtimeMs: number): string;
+/**
+ * Per-memory staleness note wrapped in `<system-reminder>` tags, or `""` for
+ * memories up to a day old. For callers that do not add their own wrapper
+ * (the Read tool prepends this to the file content it returns).
+ */
+export declare function memoryFreshnessNote(mtimeMs: number): string;

package/dist/utils/memoryAge.js

@@ -0,0 +1,47 @@
+/**
+ * Staleness annotations for auto-memory files.
+ *
+ * A memory is a point-in-time observation, so its `file:line` citations and
+ * symbol names can silently rot as the code moves on. A stale claim that
+ * carries a citation reads as *more* authoritative, not less, so the age has to
+ * be stated explicitly when the file is read.
+ *
+ * Aligned with Claude Code's `memdir/memoryAge.ts`.
+ */
+/**
+ * Days elapsed since mtime, floor-rounded — 0 for today, 1 for yesterday, 2+
+ * for older. Negative inputs (future mtime, clock skew) clamp to 0.
+ */
+export function memoryAgeDays(mtimeMs) {
+    return Math.max(0, Math.floor((Date.now() - mtimeMs) / 86400000));
+}
+/**
+ * Plain-text staleness caveat for memories more than a day old, or `""` for
+ * fresh ones (warning there is noise). Models are poor at date arithmetic — a
+ * raw ISO timestamp does not trigger staleness reasoning the way "47 days ago"
+ * does.
+ *
+ * Only the day count is derived from the clock, so the text is byte-stable
+ * within a day: re-reading the same file at the same mtime cannot change the
+ * bytes in the conversation history.
+ */
+export function memoryFreshnessText(mtimeMs) {
+    const days = memoryAgeDays(mtimeMs);
+    if (days <= 1)
+        return "";
+    return (`This memory is ${days} days old. ` +
+        `Memories are point-in-time observations, not live state — ` +
+        `claims about code behavior or file:line citations may be outdated. ` +
+        `Verify against current code before asserting as fact.`);
+}
+/**
+ * Per-memory staleness note wrapped in `<system-reminder>` tags, or `""` for
+ * memories up to a day old. For callers that do not add their own wrapper
+ * (the Read tool prepends this to the file content it returns).
+ */
+export function memoryFreshnessNote(mtimeMs) {
+    const text = memoryFreshnessText(mtimeMs);
+    if (!text)
+        return "";
+    return `<system-reminder>${text}</system-reminder>\n`;
+}

package/dist/utils/memoryEntrypoint.d.ts

@@ -0,0 +1,20 @@
+export interface EntrypointTruncation {
+    /** Content ready to be injected, including the warning when truncated. */
+    content: string;
+    lineCount: number;
+    charCount: number;
+    wasLineTruncated: boolean;
+    wasCharTruncated: boolean;
+}
+/**
+ * Truncate the auto-memory entrypoint to the line AND character caps, appending
+ * a warning that names which cap fired.
+ *
+ * Line-truncates first (a natural boundary), then character-truncates at the
+ * last newline before the cap so a line is never cut in half. The character cap
+ * is checked against the *original* size: long lines are the failure mode it
+ * targets, so measuring after the line truncation would understate the warning.
+ *
+ * Aligned with Claude Code's `truncateEntrypointContent()` in `memdir.ts`.
+ */
+export declare function truncateEntrypointContent(raw: string): EntrypointTruncation;

package/dist/utils/memoryEntrypoint.js

@@ -0,0 +1,49 @@
+import { MAX_MEMORY_ENTRYPOINT_CHARS, MAX_MEMORY_ENTRYPOINT_LINES, MEMORY_ENTRYPOINT_NAME, } from "../constants/memory.js";
+/**
+ * Truncate the auto-memory entrypoint to the line AND character caps, appending
+ * a warning that names which cap fired.
+ *
+ * Line-truncates first (a natural boundary), then character-truncates at the
+ * last newline before the cap so a line is never cut in half. The character cap
+ * is checked against the *original* size: long lines are the failure mode it
+ * targets, so measuring after the line truncation would understate the warning.
+ *
+ * Aligned with Claude Code's `truncateEntrypointContent()` in `memdir.ts`.
+ */
+export function truncateEntrypointContent(raw) {
+    const trimmed = raw.trim();
+    const contentLines = trimmed.split("\n");
+    const lineCount = contentLines.length;
+    const charCount = trimmed.length;
+    const wasLineTruncated = lineCount > MAX_MEMORY_ENTRYPOINT_LINES;
+    const wasCharTruncated = charCount > MAX_MEMORY_ENTRYPOINT_CHARS;
+    if (!wasLineTruncated && !wasCharTruncated) {
+        return {
+            content: trimmed,
+            lineCount,
+            charCount,
+            wasLineTruncated,
+            wasCharTruncated,
+        };
+    }
+    let truncated = wasLineTruncated
+        ? contentLines.slice(0, MAX_MEMORY_ENTRYPOINT_LINES).join("\n")
+        : trimmed;
+    if (truncated.length > MAX_MEMORY_ENTRYPOINT_CHARS) {
+        const cutAt = truncated.lastIndexOf("\n", MAX_MEMORY_ENTRYPOINT_CHARS);
+        truncated = truncated.slice(0, cutAt > 0 ? cutAt : MAX_MEMORY_ENTRYPOINT_CHARS);
+    }
+    const reason = wasCharTruncated && !wasLineTruncated
+        ? `${charCount} characters (limit: ${MAX_MEMORY_ENTRYPOINT_CHARS}) — index entries are too long`
+        : wasLineTruncated && !wasCharTruncated
+            ? `${lineCount} lines (limit: ${MAX_MEMORY_ENTRYPOINT_LINES})`
+            : `${lineCount} lines and ${charCount} characters`;
+    return {
+        content: truncated +
+            `\n\n> WARNING: ${MEMORY_ENTRYPOINT_NAME} is ${reason}. Only part of it was loaded. Keep index entries to one line under ~200 chars; move detail into topic files.`,
+        lineCount,
+        charCount,
+        wasLineTruncated,
+        wasCharTruncated,
+    };
+}

package/dist/utils/memoryIndex.d.ts

@@ -0,0 +1,30 @@
+import { type MemoryType } from "../constants/memory.js";
+export interface MemoryHeader {
+    filename: string;
+    filePath: string;
+    mtimeMs: number;
+    description: string | null;
+    type: MemoryType | undefined;
+}
+/**
+ * List the topic files in the auto-memory directory with their frontmatter
+ * metadata, newest first.
+ *
+ * The listing is injected into the extraction fork prompt so the agent can tell
+ * whether a memory already exists without spending a turn on `ls`. `MEMORY.md`
+ * is excluded — it is the index, not a topic file.
+ *
+ * Aligned with Claude Code's `memdir/memoryScan.ts`. Two deliberate
+ * differences: Wave has a single memory directory (no private/team split), and
+ * we read the whole file instead of the first 30 lines — memory topic files are
+ * small, and one `readFile` plus one `stat` is simpler than a bounded read that
+ * has to return the mtime itself.
+ */
+export declare function scanMemoryFiles(memoryDir: string): Promise<MemoryHeader[]>;
+/**
+ * Format memory headers as one line per file:
+ * `- [type] filename (timestamp): description`. The type tag and the
+ * description are each omitted when absent, so a legacy file without
+ * frontmatter degrades to `- filename (timestamp)`.
+ */
+export declare function formatMemoryManifest(memories: MemoryHeader[]): string;

package/dist/utils/memoryIndex.js

@@ -0,0 +1,76 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { MEMORY_ENTRYPOINT_NAME, parseMemoryType, } from "../constants/memory.js";
+import { parseFrontmatter } from "./markdownParser.js";
+const MAX_MEMORY_FILES = 200;
+/**
+ * List the topic files in the auto-memory directory with their frontmatter
+ * metadata, newest first.
+ *
+ * The listing is injected into the extraction fork prompt so the agent can tell
+ * whether a memory already exists without spending a turn on `ls`. `MEMORY.md`
+ * is excluded — it is the index, not a topic file.
+ *
+ * Aligned with Claude Code's `memdir/memoryScan.ts`. Two deliberate
+ * differences: Wave has a single memory directory (no private/team split), and
+ * we read the whole file instead of the first 30 lines — memory topic files are
+ * small, and one `readFile` plus one `stat` is simpler than a bounded read that
+ * has to return the mtime itself.
+ */
+export async function scanMemoryFiles(memoryDir) {
+    let entries;
+    try {
+        entries = await fs.readdir(memoryDir, { recursive: true });
+    }
+    catch {
+        // The directory is created lazily; a missing one simply has no memories.
+        return [];
+    }
+    const headers = await Promise.all(entries
+        .filter((entry) => entry.endsWith(".md") &&
+        path.basename(entry) !== MEMORY_ENTRYPOINT_NAME)
+        .map(async (filename) => {
+        const filePath = path.join(memoryDir, filename);
+        try {
+            const [content, stats] = await Promise.all([
+                fs.readFile(filePath, "utf-8"),
+                fs.stat(filePath),
+            ]);
+            const { frontmatter } = parseFrontmatter(content);
+            return {
+                filename,
+                filePath,
+                mtimeMs: stats.mtimeMs,
+                description: typeof frontmatter?.description === "string"
+                    ? frontmatter.description
+                    : null,
+                type: parseMemoryType(frontmatter?.type),
+            };
+        }
+        catch {
+            // A single unreadable file must not hide the rest of the directory.
+            return null;
+        }
+    }));
+    return headers
+        .filter((header) => header !== null)
+        .sort((a, b) => b.mtimeMs - a.mtimeMs)
+        .slice(0, MAX_MEMORY_FILES);
+}
+/**
+ * Format memory headers as one line per file:
+ * `- [type] filename (timestamp): description`. The type tag and the
+ * description are each omitted when absent, so a legacy file without
+ * frontmatter degrades to `- filename (timestamp)`.
+ */
+export function formatMemoryManifest(memories) {
+    return memories
+        .map((memory) => {
+        const tag = memory.type ? `[${memory.type}] ` : "";
+        const timestamp = new Date(memory.mtimeMs).toISOString();
+        return memory.description
+            ? `- ${tag}${memory.filename} (${timestamp}): ${memory.description}`
+            : `- ${tag}${memory.filename} (${timestamp})`;
+    })
+        .join("\n");
+}

package/dist/utils/messageOperations.d.ts

@@ -57,9 +57,13 @@ export interface AddErrorBlockParams {
 /**
  * Convert image file path to base64 format
  * @param imagePath Image file path
- * @returns base64 format image data URL
+ * @returns base64 format image data URL, or `undefined` when the file cannot be
+ *   used as an image (unreadable, empty, or an extension we cannot map to a
+ *   MIME type). Callers must skip the image instead of sending an empty or
+ *   mislabelled payload — the model gateway rejects both with
+ *   `HTTP 400 ... You have uploaded an unsupported image`.
  */
-export declare const convertImageToBase64: (imagePath: string) => string;
+export declare const convertImageToBase64: (imagePath: string) => string | undefined;
 export declare const generateMessageId: () => string;
 export declare const addUserMessageToMessages: ({ messages, content, customCommandContent, images, source, id, isMeta, }: AddUserMessageParams) => Message[];
 /**

package/dist/utils/messageOperations.js

@@ -5,42 +5,53 @@ import { logger } from "./globalLogger.js";
 /**
  * Convert image file path to base64 format
  * @param imagePath Image file path
- * @returns base64 format image data URL
+ * @returns base64 format image data URL, or `undefined` when the file cannot be
+ *   used as an image (unreadable, empty, or an extension we cannot map to a
+ *   MIME type). Callers must skip the image instead of sending an empty or
+ *   mislabelled payload — the model gateway rejects both with
+ *   `HTTP 400 ... You have uploaded an unsupported image`.
  */
 export const convertImageToBase64 = (imagePath) => {
+    let imageBuffer;
     try {
-        const imageBuffer = readFileSync(imagePath);
-        const ext = extname(imagePath).toLowerCase().substring(1);
-        // Determine MIME type based on file extension
-        let mimeType = "image/png"; // Default
-        switch (ext) {
-            case "jpg":
-            case "jpeg":
-                mimeType = "image/jpeg";
-                break;
-            case "png":
-                mimeType = "image/png";
-                break;
-            case "gif":
-                mimeType = "image/gif";
-                break;
-            case "webp":
-                mimeType = "image/webp";
-                break;
-            case "bmp":
-                mimeType = "image/bmp";
-                break;
-            default:
-                mimeType = "image/png";
-        }
-        const base64String = imageBuffer.toString("base64");
-        return `data:${mimeType};base64,${base64String}`;
+        imageBuffer = readFileSync(imagePath);
     }
     catch (error) {
         logger.error(`Failed to convert image to base64: ${imagePath}`, error);
-        // Return an error placeholder or throw error
-        return `data:image/png;base64,`; // Empty base64, avoid program crash
+        return undefined;
+    }
+    if (imageBuffer.length === 0) {
+        logger.warn(`Skipping empty image file: ${imagePath}`);
+        return undefined;
+    }
+    const ext = extname(imagePath).toLowerCase().substring(1);
+    // Determine MIME type based on file extension. Unknown extensions are NOT
+    // relabelled as image/png (that is how svg/heic/avif bytes used to reach the
+    // model dressed up as PNG).
+    let mimeType;
+    switch (ext) {
+        case "jpg":
+        case "jpeg":
+            mimeType = "image/jpeg";
+            break;
+        case "png":
+            mimeType = "image/png";
+            break;
+        case "gif":
+            mimeType = "image/gif";
+            break;
+        case "webp":
+            mimeType = "image/webp";
+            break;
+        case "bmp":
+            mimeType = "image/bmp";
+            break;
+        default:
+            logger.warn(`Skipping image with unsupported extension: ${imagePath}`);
+            return undefined;
     }
+    const base64String = imageBuffer.toString("base64");
+    return `data:${mimeType};base64,${base64String}`;
 };
 export const generateMessageId = () => `msg-${randomUUID()}`;
 // Add user message