wave-agent-sdk 1.1.5 → 1.3.0

package/dist/utils/imageDimensions.js

@@ -0,0 +1,232 @@
+/**
+ * Image dimensions probed from the container header, plus the gateway's
+ * per-side dimension limit.
+ *
+ * ## Why this exists
+ *
+ * The model gateway (codechat → vision model) rejects any image whose width
+ * **or** height exceeds `MAX_IMAGE_DIMENSION_PX`, answering with a misleading
+ * generic message:
+ *
+ *     HTTP 400 upstream_error:
+ *     .messages[N].image[0]: You have uploaded an unsupported image. Please
+ *     make sure your image is valid and has one of the following formats:
+ *     webp, png, jpeg, and gif.
+ *
+ * Live probes against `https://codechat.codewave.163.com/api/v1/chat/completions`
+ * (model `deepseek-flash`, single user message, `stream: true`, 2026-09-20)
+ * pinned the trigger down to that single dimension — everything else is
+ * irrelevant:
+ *
+ * | image            | px       | per-side | bytes    | result |
+ * |------------------|----------|----------|----------|--------|
+ * | 8192x1500        | 12.3 MP  | 8192     | 2.5 MB   | 200    |
+ * | 8193x1500        | 12.3 MP  | 8193     | 2.5 MB   | **400** |
+ * | 2250x8192        | 18.4 MP  | 8192     | 4.3 MB   | 200    |
+ * | 1500x8193        | 12.3 MP  | 8193     | 3.5 MB   | **400** |
+ * | 2250x9500        | 21.4 MP  | 9500     | 4.8 MB   | **400** |
+ * | 2250x15474       | 34.8 MP  | 15474    | 6.0 MB   | **400** |
+ * | 7000x4000        | 28.0 MP  | 7000     | 5.3 MB   | 200    |
+ * | 11000x1500       | 16.5 MP  | 11000    | 2.9 MB   | **400** |
+ * | 1500x1500 noise  | 2.3 MP   | 1500     | 6.8 MB (9.0 MB base64) | 200 |
+ * | 2250x12000 JPEG  | 27.0 MP  | 12000    | 2.1 MB   | **400** |
+ * | 2250x12000 WebP  | 27.0 MP  | 12000    | 1.3 MB   | **400** |
+ *
+ * So: pixel count does **not** matter (28 MP passes, 16.5 MP fails), byte
+ * size / request body size does **not** matter (a 6.8 MB PNG passes, a 1.3 MB
+ * WebP fails), and the container format does **not** matter (PNG/JPEG/WebP at
+ * the same dimensions all fail). The bound is a hard integer comparison on
+ * each side: exactly 8192 passes, 8193 fails.
+ *
+ * One caveat to keep in mind when re-testing: the probes above used
+ * `stream: true`, which is the path wave itself uses (`createParams.stream`).
+ * The identical body sent with `stream: false` returned 200 — the two gateway
+ * paths do not behave the same, so a non-streaming probe reproduces nothing.
+ *
+ * ## Why the client has to handle it
+ *
+ * Neither wave nor the proxy rejects oversized images: the request reaches the
+ * model and the whole turn fails with that 400. Outbound images come from
+ * paths that cannot all be downsampled (e.g. the model itself reading a long
+ * screenshot with the Read tool), so this module is the *detection* half:
+ * callers skip the image and tell the model what to do instead.
+ *
+ * The paste path in `packages/webview/src/utils/imageValidation.ts` no longer
+ * mirrors this bound. It targets the tighter outbound budget instead
+ * (`OUTBOUND_IMAGE_MAX_DIMENSION_PX`, shared through `constants/images.ts`) and
+ * *downsamples* an oversized paste rather than skipping it, so a pasted image
+ * is already compliant by the time it is sent. This module remains the
+ * detection half for the images nobody can re-encode — most of all the ones the
+ * model itself reads with the Read tool.
+ */
+export const MAX_IMAGE_DIMENSION_PX = 8192;
+/** JPEG frame headers (SOF0-SOF15) — the only segments carrying pixel size. */
+const SOF_MARKERS = new Set([
+    0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf,
+]);
+function u16be(bytes, offset) {
+    return (bytes[offset] << 8) | bytes[offset + 1];
+}
+function u16le(bytes, offset) {
+    return bytes[offset] | (bytes[offset + 1] << 8);
+}
+function u24le(bytes, offset) {
+    return bytes[offset] | (bytes[offset + 1] << 8) | (bytes[offset + 2] << 16);
+}
+function startsWith(bytes, signature, offset = 0) {
+    if (bytes.length < offset + signature.length)
+        return false;
+    return signature.every((byte, i) => bytes[offset + i] === byte);
+}
+function pngDimensions(bytes) {
+    // 8-byte signature, then the IHDR chunk: length(4) type(4) width(4) height(4)
+    if (bytes.length < 24)
+        return undefined;
+    if (!startsWith(bytes, [0x49, 0x48, 0x44, 0x52], 12))
+        return undefined; // "IHDR"
+    const width = (bytes[16] << 24) | (bytes[17] << 16) | (bytes[18] << 8) | bytes[19];
+    const height = (bytes[20] << 24) | (bytes[21] << 16) | (bytes[22] << 8) | bytes[23];
+    if (width <= 0 || height <= 0)
+        return undefined;
+    return { width, height };
+}
+/** Walk the JPEG marker segments until the frame header (SOFn). */
+function jpegDimensions(bytes) {
+    let offset = 2; // skip SOI
+    while (offset + 3 < bytes.length) {
+        if (bytes[offset] !== 0xff) {
+            offset++;
+            continue;
+        }
+        const marker = bytes[offset + 1];
+        // Padding fill bytes and standalone markers carry no length.
+        if (marker === 0xff) {
+            offset++;
+            continue;
+        }
+        if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd9)) {
+            offset += 2;
+            continue;
+        }
+        const length = u16be(bytes, offset + 2);
+        if (length < 2)
+            return undefined;
+        if (SOF_MARKERS.has(marker)) {
+            if (offset + 9 >= bytes.length)
+                return undefined;
+            const height = u16be(bytes, offset + 5);
+            const width = u16be(bytes, offset + 7);
+            if (width <= 0 || height <= 0)
+                return undefined;
+            return { width, height };
+        }
+        offset += 2 + length;
+    }
+    return undefined;
+}
+function webpDimensions(bytes) {
+    // "RIFF" <size> "WEBP" <fourcc> <chunk size> <chunk payload...>
+    if (bytes.length < 20)
+        return undefined;
+    const fourcc = String.fromCharCode(bytes[12], bytes[13], bytes[14], bytes[15]);
+    if (fourcc === "VP8X") {
+        // Extended: 24-bit little-endian (value - 1) for each side.
+        if (bytes.length < 30)
+            return undefined;
+        return { width: u24le(bytes, 24) + 1, height: u24le(bytes, 27) + 1 };
+    }
+    if (fourcc === "VP8L") {
+        if (bytes.length < 25)
+            return undefined;
+        if (bytes[20] !== 0x2f)
+            return undefined;
+        // 14 bits width-1, then 14 bits height-1, little-endian bit packing.
+        const bits = bytes[21] | (bytes[22] << 8) | (bytes[23] << 16) | (bytes[24] << 24);
+        return {
+            width: (bits & 0x3fff) + 1,
+            height: ((bits >> 14) & 0x3fff) + 1,
+        };
+    }
+    if (fourcc === "VP8 ") {
+        if (bytes.length < 30)
+            return undefined;
+        // Lossy: 3-byte frame tag, then the 0x9d012a start code.
+        if (!startsWith(bytes, [0x9d, 0x01, 0x2a], 23)) {
+            return undefined;
+        }
+        return {
+            width: u16le(bytes, 26) & 0x3fff,
+            height: u16le(bytes, 28) & 0x3fff,
+        };
+    }
+    return undefined;
+}
+function gifDimensions(bytes) {
+    // "GIF87a"/"GIF89a", then the logical screen descriptor.
+    if (bytes.length < 10)
+        return undefined;
+    const width = u16le(bytes, 6);
+    const height = u16le(bytes, 8);
+    if (width <= 0 || height <= 0)
+        return undefined;
+    return { width, height };
+}
+/**
+ * Read the pixel dimensions straight out of the header. Supports the four
+ * formats the gateway accepts (png / jpeg / gif / webp).
+ *
+ * Returns `undefined` when the format is unknown or the header is truncated —
+ * callers must treat that as "unknown", never as "oversized".
+ */
+export function getImageDimensions(bytes) {
+    if (startsWith(bytes, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) {
+        return pngDimensions(bytes);
+    }
+    if (startsWith(bytes, [0xff, 0xd8, 0xff])) {
+        return jpegDimensions(bytes);
+    }
+    if (startsWith(bytes, [0x47, 0x49, 0x46, 0x38])) {
+        return gifDimensions(bytes);
+    }
+    if (startsWith(bytes, [0x52, 0x49, 0x46, 0x46]) &&
+        startsWith(bytes, [0x57, 0x45, 0x42, 0x50], 8)) {
+        return webpDimensions(bytes);
+    }
+    return undefined;
+}
+/**
+ * Enough base64 to cover a header of any of the supported formats: PNG/WebP/GIF
+ * live in the first ~30 bytes, JPEG's SOF segment follows the app segments —
+ * a few KB at most (large EXIF/ICC blocks occasionally reach ~64 KB).
+ */
+const DATA_URL_PREFIX_B64_CHARS = Math.ceil((96 * 1024 * 4) / 3);
+export function getImageDimensionsFromDataUrl(dataUrl) {
+    const comma = dataUrl.indexOf(",");
+    if (comma === -1 || !dataUrl.startsWith("data:image/"))
+        return undefined;
+    const prefix = dataUrl.slice(comma + 1, comma + 1 + DATA_URL_PREFIX_B64_CHARS);
+    if (prefix.length === 0)
+        return undefined;
+    try {
+        return getImageDimensions(Buffer.from(prefix, "base64"));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function exceedsMaxDimension(dimensions, max = MAX_IMAGE_DIMENSION_PX) {
+    return dimensions.width > max || dimensions.height > max;
+}
+/**
+ * One-line, actionable note that replaces an image the gateway would reject.
+ * Modelled on opencode's `[N image omitted: ...]` placeholder: the model (and
+ * anyone reading the transcript) gets the real size, the bound, and the way
+ * out.
+ */
+export function omittedImageNote(dimensions, sourcePath) {
+    const where = sourcePath ? ` Path: ${sourcePath}` : "";
+    return (`[Image omitted: ${dimensions.width}x${dimensions.height} exceeds the ` +
+        `${MAX_IMAGE_DIMENSION_PX}px per-side limit of the vision model gateway, ` +
+        `which would reject the whole request. Crop it, split it into smaller ` +
+        `images, or downscale it before sending again.${where}]`);
+}

package/dist/utils/imageProcessor.d.ts

@@ -0,0 +1,66 @@
+export interface SharpMetadata {
+    width?: number;
+    height?: number;
+    /** Container format, e.g. `png` / `jpeg` / `webp` / `gif` / `svg`. */
+    format?: string;
+    hasAlpha?: boolean;
+}
+/**
+ * The slice of sharp's chainable API this codebase uses. Structural typing keeps
+ * the SDK compiling without sharp's own types (and without a dependency on a
+ * package that may not be installed).
+ */
+export interface SharpImage {
+    metadata(): Promise<SharpMetadata>;
+    resize(width: number, height: number, options?: {
+        fit?: "inside";
+        withoutEnlargement?: boolean;
+    }): SharpImage;
+    png(options?: {
+        compressionLevel?: number;
+        palette?: boolean;
+    }): SharpImage;
+    webp(options?: {
+        quality?: number;
+    }): SharpImage;
+    jpeg(options?: {
+        quality?: number;
+    }): SharpImage;
+    flatten(options?: {
+        background?: {
+            r: number;
+            g: number;
+            b: number;
+        };
+    }): SharpImage;
+    toBuffer(): Promise<Buffer>;
+}
+export interface SharpFactory {
+    (input: Buffer): SharpImage;
+    /** Populated at require time; `vips` doubles as a "the native side loaded" check. */
+    versions?: {
+        vips?: string;
+    };
+}
+/**
+ * Require sharp and check it is usable. Never throws: an absent package, a
+ * missing platform build, a failed `dlopen` all come back as `undefined`, with
+ * the underlying error logged once so an operator can tell the three apart.
+ *
+ * `requireFn` is injectable so tests can exercise every outcome without the real
+ * module.
+ */
+export declare function resolveSharp(requireFn: NodeRequire): SharpFactory | undefined;
+/**
+ * The image codec, or `undefined` when this process cannot resize images.
+ * Resolved once on first call — callers on a hot path pay a single boolean
+ * check after that.
+ */
+export declare function getImageProcessor(): SharpFactory | undefined;
+/**
+ * Forget the memoised result so the next {@link getImageProcessor} resolves
+ * again. Called by the runtime-dependency installer once sharp is on disk —
+ * without it a process that asked for a codec *before* the download finished
+ * would keep degrading for its whole lifetime. Also used by tests.
+ */
+export declare function resetImageProcessor(): void;

package/dist/utils/imageProcessor.js

@@ -0,0 +1,84 @@
+/**
+ * Lazy access to the optional `sharp` image codec.
+ *
+ * ## Why lazy, and why a runtime require
+ *
+ * `sharp` must never be pulled in by a plain `import`:
+ *
+ * - It is a native module — its wrapper does `require("../src/build/Release/
+ *   sharp-<platform>.node")` *relative to its own directory* and falls back to
+ *   `@img/sharp-<platform>/sharp.node`. Bundlers therefore cannot inline it, and
+ *   a top-level import would drag a `.node` file into every host bundle.
+ * - It is optional. Host processes (the desktop main process, the IDE extension
+ *   hosts) load the SDK barrel without a platform build present; evaluating
+ *   `require("sharp")` there would throw during module evaluation and take the
+ *   host down. Same rule as `utils/ripgrep.ts` — both optional runtime
+ *   dependencies are resolved lazily and memoised, so a missing one only costs
+ *   the tool that needs it (an image without a codec, grep without rg).
+ *
+ * So resolution happens on first use, through `createRequire(import.meta.url)`
+ * — a *runtime* require the host-bundle scanner does not match (it looks for
+ * literal `require("<bare specifier>")` calls), keeping the CLI bundle free of
+ * both the module and a load-time dependency on it.
+ *
+ * ## Failure memory
+ *
+ * The result (including "unavailable") is memoised for the life of the process,
+ * so a missing codec costs one failed resolution rather than one per image.
+ * Because a first-use failure is often just "the installer has not finished
+ * yet", the installer calls {@link resetImageProcessor} after it drops files on
+ * disk so the next turn can pick them up.
+ */
+import { createRequire } from "node:module";
+import { logger } from "./globalLogger.js";
+let cached;
+let resolutionAttempted = false;
+/**
+ * Require sharp and check it is usable. Never throws: an absent package, a
+ * missing platform build, a failed `dlopen` all come back as `undefined`, with
+ * the underlying error logged once so an operator can tell the three apart.
+ *
+ * `requireFn` is injectable so tests can exercise every outcome without the real
+ * module.
+ */
+export function resolveSharp(requireFn) {
+    try {
+        const loaded = requireFn("sharp");
+        if (typeof loaded !== "function") {
+            logger.warn("sharp resolved to a non-callable value; image resizing off");
+            return undefined;
+        }
+        const factory = loaded;
+        if (typeof factory.versions?.vips !== "string") {
+            logger.warn("sharp loaded without a libvips version; the native build is unusable");
+            return undefined;
+        }
+        return factory;
+    }
+    catch (error) {
+        logger.warn("sharp is unavailable, images will not be resized:", error);
+        return undefined;
+    }
+}
+/**
+ * The image codec, or `undefined` when this process cannot resize images.
+ * Resolved once on first call — callers on a hot path pay a single boolean
+ * check after that.
+ */
+export function getImageProcessor() {
+    if (!resolutionAttempted) {
+        resolutionAttempted = true;
+        cached = resolveSharp(createRequire(import.meta.url));
+    }
+    return cached;
+}
+/**
+ * Forget the memoised result so the next {@link getImageProcessor} resolves
+ * again. Called by the runtime-dependency installer once sharp is on disk —
+ * without it a process that asked for a codec *before* the download finished
+ * would keep degrading for its whole lifetime. Also used by tests.
+ */
+export function resetImageProcessor() {
+    cached = undefined;
+    resolutionAttempted = false;
+}

package/dist/utils/imageRewrite.d.ts

@@ -0,0 +1,29 @@
+export type OutboundImagePlan = {
+    kind: "send";
+    dataUrl: string;
+    note?: string;
+} | {
+    kind: "omit";
+    note: string;
+};
+/** Drop cached rewrites (tests, and any future "the codec just appeared" reset). */
+export declare function __resetImageRewriteCacheForTesting(): void;
+/**
+ * Cache key for an image that came from a local file: path plus size plus
+ * mtime. Cheaper than hashing the bytes, and a rewritten file (different size or
+ * mtime) gets a fresh entry instead of reusing a stale rewrite.
+ */
+export declare function imageFileCacheKey(path: string): string;
+export interface OutboundImageInput {
+    /** Data URL of the image (already base64, whatever its original source). */
+    dataUrl: string;
+    /** Cache identity: the data URL itself for inline images, path+size+mtime for files. */
+    cacheKey: string;
+    /** Local file the image came from, when it has one (used in notes). */
+    sourcePath?: string;
+}
+/**
+ * Decide what to send for one image. Never throws and never rejects — see the
+ * module comment.
+ */
+export declare function planOutboundImage(input: OutboundImageInput): Promise<OutboundImagePlan>;

package/dist/utils/imageRewrite.js

@@ -0,0 +1,251 @@
+/**
+ * Outbound image rewriting: decide whether an image can go into a request body
+ * as it is, or must be re-encoded first.
+ *
+ * ## Where this sits
+ *
+ * `convertMessagesForAPI` is the single choke point every image passes through
+ * on its way out (user attachments, tool results, Read-tool screenshots). This
+ * module answers one question per image: send it (untouched, or rewritten) or
+ * omit it with an explanatory note. The caller only wires the answer into the
+ * message.
+ *
+ * ## The ladder
+ *
+ * Only images outside the budget (`imageBudget.ts`) touch the codec, which keeps
+ * the common case — the model reads a normal-sized screenshot — free of any
+ * native work and byte-identical.
+ *
+ * An over-budget image is re-encoded by walking two nested loops: the source is
+ * first clamped to the dimension budget, then downscaled in steps (1 → 0.75 →
+ * 0.5 → 0.25) and, at each step, encoded at several qualities. The first output
+ * inside the raw-byte budget wins. Transparency drives the encoder order: alpha
+ * sources try PNG/WebP first and only fall back to JPEG after flattening onto
+ * white — a naive JPEG would turn transparent pixels black. JPEG sources skip
+ * PNG entirely (re-encoding a photo as PNG would inflate it).
+ *
+ * An image that is only over the *byte* budget keeps its dimensions: scale 1
+ * with the clamp being a no-op means "compress at full resolution", which is
+ * what Claude Code does too, and the model's coordinates stay valid.
+ *
+ * A **fresh `sharp(buffer)` instance per rung** is mandatory, not stylistic:
+ * sharp is chainable and a reused instance keeps returning the previous rung's
+ * bytes (documented sharp behaviour, and the reason Claude Code's implementation
+ * does the same).
+ *
+ * The output mime always comes from the rung that produced the bytes, never from
+ * a hardcoded string — mislabelling a container is exactly the 400 root cause
+ * fixed in `#2273`.
+ *
+ * ## Omission, not failure
+ *
+ * `planOutboundImage` never rejects and never throws: a turn must keep going.
+ * Outcomes are `send` (possibly with a size note the model can use to map
+ * coordinates back) or `omit` (with a note stating the real size and what to do
+ * instead).
+ */
+import { statSync } from "node:fs";
+import { LRUCache } from "lru-cache";
+import { logger } from "./globalLogger.js";
+import { OUTBOUND_IMAGE_MAX_DIMENSION_PX, OUTBOUND_IMAGE_TARGET_RAW_BYTES, exceedsOutboundBudget, resizedImageNote, } from "./imageBudget.js";
+import { exceedsMaxDimension, getImageDimensions, getImageDimensionsFromDataUrl, omittedImageNote, } from "./imageDimensions.js";
+import { getImageProcessor } from "./imageProcessor.js";
+import { ensureRuntimeDeps } from "./runtimeDeps.js";
+/**
+ * Downscale steps tried in order. The floor keeps a pathological aspect ratio
+ * (e.g. 20000x40) from collapsing to a zero-pixel edge.
+ */
+const SCALES = [1, 0.75, 0.5, 0.25];
+const MIN_DIMENSION_PX = 64;
+const JPEG_QUALITIES = [80, 60, 40, 20];
+const WEBP_QUALITIES = [80, 60];
+const PNG_COMPRESSION_LEVEL = 9;
+const OPAQUE_BACKGROUND = { r: 255, g: 255, b: 255 };
+const JPEG_RUNGS = JPEG_QUALITIES.map((quality) => ({
+    mime: "image/jpeg",
+    encode: (image) => image.jpeg({ quality }),
+}));
+/** Lossless first; `palette` narrows the colour depth when full PNG is too big. */
+const PNG_RUNGS = [
+    {
+        mime: "image/png",
+        encode: (image) => image.png({ compressionLevel: PNG_COMPRESSION_LEVEL }),
+    },
+    {
+        mime: "image/png",
+        encode: (image) => image.png({ compressionLevel: PNG_COMPRESSION_LEVEL, palette: true }),
+    },
+];
+const WEBP_RUNGS = WEBP_QUALITIES.map((quality) => ({
+    mime: "image/webp",
+    encode: (image) => image.webp({ quality }),
+}));
+/** Transparency survives the whole ladder; JPEG is a last resort, flattened white. */
+const ALPHA_LADDER = [
+    ...PNG_RUNGS,
+    ...WEBP_RUNGS,
+    {
+        mime: "image/jpeg",
+        encode: (image) => image
+            .flatten({ background: OPAQUE_BACKGROUND })
+            .jpeg({ quality: JPEG_QUALITIES[0] }),
+    },
+];
+const OPAQUE_LADDER = [...PNG_RUNGS, ...WEBP_RUNGS, ...JPEG_RUNGS];
+function ladderFor(format, hasAlpha) {
+    // A photo is never improved by a lossless PNG pass; go straight to JPEG.
+    if (format === "jpeg")
+        return JPEG_RUNGS;
+    if (hasAlpha)
+        return ALPHA_LADDER;
+    return OPAQUE_LADDER;
+}
+function toDataUrl(mime, bytes) {
+    return `data:${mime};base64,${bytes.toString("base64")}`;
+}
+/** Base64 payload of a data URL, without the `data:<mime>;base64,` prefix. */
+function dataUrlBody(dataUrl) {
+    const comma = dataUrl.indexOf(",");
+    return comma === -1 ? dataUrl : dataUrl.slice(comma + 1);
+}
+/**
+ * Shrink both sides into the dimension budget, preserving aspect ratio. `fit:
+ * "inside"` re-derives the ratio from the real image, so clamping each side
+ * independently is correct (3000x2000 → 2000x1333, 1000x4000 → 500x2000).
+ */
+function clampToBudget(dimensions) {
+    return {
+        width: Math.min(dimensions.width, OUTBOUND_IMAGE_MAX_DIMENSION_PX),
+        height: Math.min(dimensions.height, OUTBOUND_IMAGE_MAX_DIMENSION_PX),
+    };
+}
+/**
+ * Walk the ladder until something fits the byte budget. Throws when the codec
+ * itself fails (missing platform build, undecodable bytes) — the caller treats
+ * that as "no codec".
+ */
+async function runLadder(sharp, source, knownDimensions) {
+    const metadata = await sharp(source).metadata();
+    const width = metadata.width ?? knownDimensions?.width ?? 0;
+    const height = metadata.height ?? knownDimensions?.height ?? 0;
+    if (width <= 0 || height <= 0)
+        return { status: "unknown-dimensions" };
+    const withinBudget = clampToBudget({ width, height });
+    const rungs = ladderFor(metadata.format, metadata.hasAlpha === true);
+    for (const scale of SCALES) {
+        const targetWidth = Math.max(MIN_DIMENSION_PX, Math.floor(withinBudget.width * scale));
+        const targetHeight = Math.max(MIN_DIMENSION_PX, Math.floor(withinBudget.height * scale));
+        for (const rung of rungs) {
+            const encoded = await rung
+                .encode(sharp(source).resize(targetWidth, targetHeight, {
+                fit: "inside",
+                withoutEnlargement: true,
+            }))
+                .toBuffer();
+            if (encoded.length <= OUTBOUND_IMAGE_TARGET_RAW_BYTES) {
+                return {
+                    status: "fits",
+                    dataUrl: toDataUrl(rung.mime, encoded),
+                    dimensions: getImageDimensions(encoded),
+                };
+            }
+        }
+    }
+    return { status: "exhausted", sourceDimensions: { width, height } };
+}
+/**
+ * Results keyed by the caller-supplied cache key, capped at a handful of
+ * entries: every turn rebuilds the request body from the whole history, so
+ * without a cache each turn would re-encode the same oversized screenshots.
+ */
+const rewritten = new LRUCache({ max: 8 });
+/** Drop cached rewrites (tests, and any future "the codec just appeared" reset). */
+export function __resetImageRewriteCacheForTesting() {
+    rewritten.clear();
+}
+/**
+ * Cache key for an image that came from a local file: path plus size plus
+ * mtime. Cheaper than hashing the bytes, and a rewritten file (different size or
+ * mtime) gets a fresh entry instead of reusing a stale rewrite.
+ */
+export function imageFileCacheKey(path) {
+    try {
+        const stat = statSync(path);
+        return `${path}:${stat.size}:${stat.mtimeMs}`;
+    }
+    catch {
+        return path;
+    }
+}
+/**
+ * The degradation path used whenever we could not even try to shrink the image
+ * (no codec, codec failure, unknown size): an image the gateway would reject
+ * anyway is omitted with an actionable note; anything the gateway can still take
+ * is sent untouched, oversized bytes included — we have no way to shrink it, and
+ * refusing it would break a turn that used to work.
+ */
+function degrade(dataUrl, dimensions, sourcePath, reason) {
+    if (dimensions && exceedsMaxDimension(dimensions)) {
+        logger.warn(`Omitting oversized image (${reason}):`, dimensions, sourcePath);
+        return { kind: "omit", note: omittedImageNote(dimensions, sourcePath) };
+    }
+    logger.warn(`Sending image without rewriting (${reason}):`, sourcePath);
+    return { kind: "send", dataUrl };
+}
+/**
+ * Decide what to send for one image. Never throws and never rejects — see the
+ * module comment.
+ */
+export async function planOutboundImage(input) {
+    const { dataUrl, cacheKey, sourcePath } = input;
+    const dimensions = getImageDimensionsFromDataUrl(dataUrl);
+    if (!exceedsOutboundBudget(dataUrl, dimensions)) {
+        return { kind: "send", dataUrl };
+    }
+    const cached = rewritten.get(cacheKey);
+    if (cached)
+        return cached;
+    const plan = await rewrite(dataUrl, dimensions, sourcePath);
+    rewritten.set(cacheKey, plan);
+    return plan;
+}
+async function rewrite(dataUrl, dimensions, sourcePath) {
+    const sharp = getImageProcessor();
+    if (!sharp) {
+        // Kick a download so a later turn has the codec; this turn still degrades
+        // rather than blocking the request on ~8MB.
+        void ensureRuntimeDeps();
+        return degrade(dataUrl, dimensions, sourcePath, "no image codec available");
+    }
+    let outcome;
+    try {
+        outcome = await runLadder(sharp, Buffer.from(dataUrlBody(dataUrl), "base64"), dimensions);
+    }
+    catch (error) {
+        logger.warn("Image rewrite failed:", sourcePath, error);
+        return degrade(dataUrl, dimensions, sourcePath, "the image codec failed");
+    }
+    if (outcome.status === "unknown-dimensions") {
+        return degrade(dataUrl, dimensions, sourcePath, "its dimensions could not be determined");
+    }
+    if (outcome.status === "exhausted") {
+        // The codec ran out of rungs without fitting the budget (extreme aspect
+        // ratios). The spec routes this to the same note as an unshrinkable
+        // oversized image rather than sending something we know is over budget.
+        logger.warn("Omitting image that cannot fit the outbound budget:", outcome.sourceDimensions, sourcePath);
+        return {
+            kind: "omit",
+            note: omittedImageNote(outcome.sourceDimensions, sourcePath),
+        };
+    }
+    const resizedTo = outcome.dimensions;
+    const wasResized = dimensions !== undefined &&
+        resizedTo !== undefined &&
+        (dimensions.width !== resizedTo.width ||
+            dimensions.height !== resizedTo.height);
+    return {
+        kind: "send",
+        dataUrl: outcome.dataUrl,
+        ...(wasResized ? { note: resizedImageNote(dimensions, resizedTo) } : {}),
+    };
+}

package/dist/utils/markdownParser.d.ts

@@ -4,7 +4,11 @@ interface ParsedMarkdownFile {
     config?: CustomSlashCommandConfig;
 }
 /**
- * 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 declare function parseFrontmatter(content: string): {
     frontmatter?: Record<string, unknown>;