wave-agent-sdk 1.2.0 → 1.3.0

package/dist/utils/frontmatterYaml.js

@@ -0,0 +1,192 @@
+const FRONTMATTER_REGEX = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n([\s\S]*))?$/;
+/**
+ * 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 function splitFrontmatter(content) {
+    const match = content.match(FRONTMATTER_REGEX);
+    if (!match) {
+        return { yaml: null, body: content };
+    }
+    return { yaml: match[1], body: match[2] ?? "" };
+}
+/**
+ * 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 function parseFrontmatterYaml(yamlContent) {
+    const frontmatter = {};
+    try {
+        const lines = yamlContent.split("\n");
+        let currentKey = null;
+        for (let index = 0; index < lines.length; index++) {
+            const raw = lines[index].replace(/\r$/, "");
+            const trimmed = raw.trim();
+            if (!trimmed || trimmed.startsWith("#"))
+                continue;
+            const indent = raw.length - raw.trimStart().length;
+            // Block list item belonging to the key above it.
+            if (trimmed.startsWith("-") && currentKey) {
+                const value = stripQuotes(trimmed.substring(1).trim());
+                if (value) {
+                    const existing = frontmatter[currentKey];
+                    if (Array.isArray(existing)) {
+                        existing.push(value);
+                    }
+                    else {
+                        frontmatter[currentKey] = [value];
+                    }
+                }
+                continue;
+            }
+            const colonIndex = trimmed.indexOf(":");
+            if (colonIndex === -1)
+                continue;
+            const key = trimmed.substring(0, colonIndex).trim();
+            if (!key)
+                continue;
+            const inlineValue = trimmed.substring(colonIndex + 1).trim();
+            currentKey = key;
+            // Block scalar: `>-`, `|`, `>+`, `|-`, ...
+            const blockIndicator = /^([>|])([-+]?)$/.exec(inlineValue);
+            if (blockIndicator) {
+                const block = readBlockScalar(lines, index + 1, indent, blockIndicator[1]);
+                // Same treatment as inline scalars: chomping indicators only decide how
+                // the block's line breaks are trimmed, and a metadata scalar never
+                // keeps leading/trailing whitespace.
+                frontmatter[key] = block.text.trim();
+                index = block.nextIndex - 1;
+                continue;
+            }
+            if (inlineValue) {
+                frontmatter[key] = stripQuotes(inlineValue);
+                continue;
+            }
+            // Key with no inline value: either an indented block list or an indented
+            // (multi-line) scalar.
+            const continuation = readIndentedValue(lines, index + 1, indent);
+            index = continuation.nextIndex - 1;
+            if (continuation.items) {
+                frontmatter[key] = continuation.items;
+            }
+            else {
+                frontmatter[key] = continuation.text ?? [];
+            }
+        }
+    }
+    catch {
+        // Return whatever was parsed so far — callers validate required fields.
+    }
+    return frontmatter;
+}
+function stripQuotes(value) {
+    return value.replace(/^["']|["']$/g, "");
+}
+/**
+ * Fold a block scalar's lines the way YAML does: `|` keeps line breaks, `>`
+ * folds a single break into a space and turns each blank line into one line
+ * break (a blank line is a paragraph break, not two).
+ */
+function foldBlockLines(lines, indicator) {
+    if (indicator === "|")
+        return lines.join("\n");
+    let text = "";
+    for (let index = 0; index < lines.length; index++) {
+        const line = lines[index];
+        if (line === "") {
+            let blanks = 0;
+            while (lines[index] === "") {
+                blanks++;
+                index++;
+            }
+            index--;
+            text += "\n".repeat(blanks);
+            continue;
+        }
+        text += line;
+        if (index + 1 < lines.length && lines[index + 1] !== "") {
+            text += " ";
+        }
+    }
+    return text;
+}
+/**
+ * Read the block scalar that starts at `startIndex` (the line after its key).
+ * Lines belong to the block while they are blank or indented deeper than the
+ * key; the block's own indentation is taken from its first non-blank line.
+ */
+function readBlockScalar(lines, startIndex, keyIndent, indicator) {
+    let index = startIndex;
+    let baseIndent = null;
+    const collected = [];
+    while (index < lines.length) {
+        const raw = lines[index].replace(/\r$/, "");
+        if (!raw.trim()) {
+            // Blank lines before the first content line belong to the YAML document,
+            // not to the scalar; afterwards they are paragraph breaks.
+            if (baseIndent !== null)
+                collected.push("");
+            index++;
+            continue;
+        }
+        const indent = raw.length - raw.trimStart().length;
+        if (indent <= keyIndent)
+            break;
+        if (baseIndent === null)
+            baseIndent = indent;
+        if (indent < baseIndent)
+            break;
+        collected.push(raw.slice(baseIndent));
+        index++;
+    }
+    // Trailing blank lines belong to the following key, not to the scalar's
+    // content (chomping decides how many line breaks survive).
+    while (collected.length > 0 && collected[collected.length - 1] === "") {
+        collected.pop();
+    }
+    if (collected.length === 0) {
+        return { text: "", nextIndex: index };
+    }
+    return {
+        text: foldBlockLines(collected, indicator),
+        nextIndex: index,
+    };
+}
+/**
+ * Read the value of a key whose value starts on the following lines: an
+ * indented block list (`- item`) or an indented multi-line plain scalar (folded
+ * with spaces).
+ */
+function readIndentedValue(lines, startIndex, keyIndent) {
+    let index = startIndex;
+    const items = [];
+    const textLines = [];
+    let sawListItem = false;
+    while (index < lines.length) {
+        const raw = lines[index].replace(/\r$/, "");
+        if (!raw.trim())
+            break;
+        const indent = raw.length - raw.trimStart().length;
+        if (indent <= keyIndent)
+            break;
+        const trimmed = raw.trim();
+        if (trimmed.startsWith("- ")) {
+            sawListItem = true;
+            items.push(stripQuotes(trimmed.substring(1).trim()));
+        }
+        else if (sawListItem) {
+            break;
+        }
+        else {
+            textLines.push(trimmed);
+        }
+        index++;
+    }
+    if (sawListItem)
+        return { items, nextIndex: index };
+    if (textLines.length === 0)
+        return { nextIndex: index };
+    return { text: textLines.join(" "), nextIndex: index };
+}

package/dist/utils/imageBudget.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Outbound image budget: the size we deliberately keep every image under before
+ * it goes into a request body, and the arithmetic / wording around it.
+ *
+ * ## Why a budget on top of the gateway bound
+ *
+ * `imageDimensions.ts` documents the gateway's *hard* bound (8192px per side):
+ * exceeding it fails the whole request, so it must never be crossed. This module
+ * is a second, tighter bound we impose on ourselves, aligned with Claude Code —
+ * 2000px per side and 5 MB of base64 payload ({@link OUTBOUND_IMAGE_MAX_BASE64_BYTES},
+ * their `API_IMAGE_MAX_BASE64_SIZE`). Images inside the budget are sent
+ * byte-for-byte; images outside it are re-encoded by `imageRewrite.ts` (via
+ * sharp) and only fall back to the "omitted" note when no codec is available.
+ *
+ * Two consequences worth keeping in mind:
+ *
+ * - The budget is ours, not the gateway's — it is deliberately conservative and
+ *   may make a 3000px screenshot slightly softer. Raise it whenever we want
+ *   more fidelity; nothing upstream depends on the exact value.
+ * - The byte budget is expressed twice, in the two units that matter: base64
+ *   characters (what the request actually carries) and raw bytes (what an
+ *   encoder produces). Base64 inflates by 4/3, so bytes-on-the-wire = raw * 4/3,
+ *   i.e. raw = base64 * 3/4 — see {@link OUTBOUND_IMAGE_TARGET_RAW_BYTES}.
+ *
+ * ## Why raw bytes, not the whole data URL
+ *
+ * A data URL is `data:<mime>;base64,<payload>` — the prefix is metadata and is
+ * not part of the encoded image. Measuring the whole string would make the
+ * budget depend on the mime string's length and would reject images that are
+ * actually within budget; {@link rawBytesFromDataUrl} measures the payload only.
+ *
+ * This module holds no image codec and must stay dependency-free so it can be
+ * imported from anywhere in the SDK.
+ */
+import { OUTBOUND_IMAGE_MAX_DIMENSION_PX } from "../constants/images.js";
+import type { ImageDimensions } from "./imageDimensions.js";
+/**
+ * Client-side per-side dimension budget (Claude Code's `IMAGE_MAX_WIDTH` /
+ * `IMAGE_MAX_HEIGHT`). Distinct from — and much tighter than — the gateway's
+ * hard bound in `imageDimensions.ts`. The value itself lives in
+ * `constants/images.ts` so the webview paste path can share it instead of
+ * keeping a copy that could drift; re-exported here because this is the module
+ * every outbound-image caller already imports.
+ */
+export { OUTBOUND_IMAGE_MAX_DIMENSION_PX };
+/**
+ * Maximum base64 payload we are willing to put in a request, counting only the
+ * characters after the `,` in the data URL. Aligned with Claude Code's
+ * `API_IMAGE_MAX_BASE64_SIZE`.
+ */
+export declare const OUTBOUND_IMAGE_MAX_BASE64_BYTES: number;
+/**
+ * The same budget in raw bytes: `5 MiB * 3 / 4`. Encoders produce raw bytes, so
+ * comparing their output against this number is equivalent to comparing the
+ * resulting base64 against {@link OUTBOUND_IMAGE_MAX_BASE64_BYTES} — it keeps
+ * the input side and the output side of the ladder on one scale.
+ */
+export declare const OUTBOUND_IMAGE_TARGET_RAW_BYTES: number;
+/**
+ * Raw (decoded) byte count implied by a data URL's base64 payload — the inverse
+ * of the 4/3 base64 inflation. Padding makes this overstate the real payload by
+ * at most 2 bytes, which errs toward rewriting an image slightly before it
+ * actually has to.
+ */
+export declare function rawBytesFromDataUrl(dataUrl: string): number;
+/**
+ * Whether an image must be rewritten before it can be sent: it carries more
+ * base64 than the byte budget, or (when the container header gave us
+ * dimensions) exceeds the per-side budget.
+ *
+ * Unknown dimensions never count as oversized — see `imageDimensions.ts`; a
+ * header we cannot parse means "unknown", not "too big".
+ */
+export declare function exceedsOutboundBudget(dataUrl: string, dimensions?: ImageDimensions): boolean;
+/**
+ * Note appended after a rewritten image so the model can map what it sees back
+ * to the original pixels — the same contract as Claude Code's
+ * `createImageMetadataText` (`src/utils/imageResizer.ts`). Kept verbatim in
+ * shape: original size, displayed size, and the factor to multiply by.
+ *
+ * `fit: "inside"` scales both sides by one factor, so a single ratio (taken
+ * from whichever side shrank more, to stay correct under rounding) applies.
+ * Callers only append it when the dimensions actually changed.
+ */
+export declare function resizedImageNote(original: ImageDimensions, displayed: ImageDimensions): string;

package/dist/utils/imageBudget.js

@@ -0,0 +1,109 @@
+/**
+ * Outbound image budget: the size we deliberately keep every image under before
+ * it goes into a request body, and the arithmetic / wording around it.
+ *
+ * ## Why a budget on top of the gateway bound
+ *
+ * `imageDimensions.ts` documents the gateway's *hard* bound (8192px per side):
+ * exceeding it fails the whole request, so it must never be crossed. This module
+ * is a second, tighter bound we impose on ourselves, aligned with Claude Code —
+ * 2000px per side and 5 MB of base64 payload ({@link OUTBOUND_IMAGE_MAX_BASE64_BYTES},
+ * their `API_IMAGE_MAX_BASE64_SIZE`). Images inside the budget are sent
+ * byte-for-byte; images outside it are re-encoded by `imageRewrite.ts` (via
+ * sharp) and only fall back to the "omitted" note when no codec is available.
+ *
+ * Two consequences worth keeping in mind:
+ *
+ * - The budget is ours, not the gateway's — it is deliberately conservative and
+ *   may make a 3000px screenshot slightly softer. Raise it whenever we want
+ *   more fidelity; nothing upstream depends on the exact value.
+ * - The byte budget is expressed twice, in the two units that matter: base64
+ *   characters (what the request actually carries) and raw bytes (what an
+ *   encoder produces). Base64 inflates by 4/3, so bytes-on-the-wire = raw * 4/3,
+ *   i.e. raw = base64 * 3/4 — see {@link OUTBOUND_IMAGE_TARGET_RAW_BYTES}.
+ *
+ * ## Why raw bytes, not the whole data URL
+ *
+ * A data URL is `data:<mime>;base64,<payload>` — the prefix is metadata and is
+ * not part of the encoded image. Measuring the whole string would make the
+ * budget depend on the mime string's length and would reject images that are
+ * actually within budget; {@link rawBytesFromDataUrl} measures the payload only.
+ *
+ * This module holds no image codec and must stay dependency-free so it can be
+ * imported from anywhere in the SDK.
+ */
+import { OUTBOUND_IMAGE_MAX_DIMENSION_PX } from "../constants/images.js";
+import { exceedsMaxDimension } from "./imageDimensions.js";
+/**
+ * Client-side per-side dimension budget (Claude Code's `IMAGE_MAX_WIDTH` /
+ * `IMAGE_MAX_HEIGHT`). Distinct from — and much tighter than — the gateway's
+ * hard bound in `imageDimensions.ts`. The value itself lives in
+ * `constants/images.ts` so the webview paste path can share it instead of
+ * keeping a copy that could drift; re-exported here because this is the module
+ * every outbound-image caller already imports.
+ */
+export { OUTBOUND_IMAGE_MAX_DIMENSION_PX };
+/**
+ * Maximum base64 payload we are willing to put in a request, counting only the
+ * characters after the `,` in the data URL. Aligned with Claude Code's
+ * `API_IMAGE_MAX_BASE64_SIZE`.
+ */
+export const OUTBOUND_IMAGE_MAX_BASE64_BYTES = 5 * 1024 * 1024;
+/**
+ * The same budget in raw bytes: `5 MiB * 3 / 4`. Encoders produce raw bytes, so
+ * comparing their output against this number is equivalent to comparing the
+ * resulting base64 against {@link OUTBOUND_IMAGE_MAX_BASE64_BYTES} — it keeps
+ * the input side and the output side of the ladder on one scale.
+ */
+export const OUTBOUND_IMAGE_TARGET_RAW_BYTES = (OUTBOUND_IMAGE_MAX_BASE64_BYTES * 3) / 4;
+/**
+ * Length of the base64 payload of a data URL, ignoring the `data:<mime>;base64,`
+ * prefix. A string without a comma is treated as bare payload.
+ */
+function base64PayloadLength(dataUrl) {
+    const comma = dataUrl.indexOf(",");
+    return comma === -1 ? dataUrl.length : dataUrl.length - comma - 1;
+}
+/**
+ * Raw (decoded) byte count implied by a data URL's base64 payload — the inverse
+ * of the 4/3 base64 inflation. Padding makes this overstate the real payload by
+ * at most 2 bytes, which errs toward rewriting an image slightly before it
+ * actually has to.
+ */
+export function rawBytesFromDataUrl(dataUrl) {
+    return Math.floor((base64PayloadLength(dataUrl) * 3) / 4);
+}
+/**
+ * Whether an image must be rewritten before it can be sent: it carries more
+ * base64 than the byte budget, or (when the container header gave us
+ * dimensions) exceeds the per-side budget.
+ *
+ * Unknown dimensions never count as oversized — see `imageDimensions.ts`; a
+ * header we cannot parse means "unknown", not "too big".
+ */
+export function exceedsOutboundBudget(dataUrl, dimensions) {
+    if (rawBytesFromDataUrl(dataUrl) > OUTBOUND_IMAGE_TARGET_RAW_BYTES) {
+        return true;
+    }
+    if (dimensions &&
+        exceedsMaxDimension(dimensions, OUTBOUND_IMAGE_MAX_DIMENSION_PX)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Note appended after a rewritten image so the model can map what it sees back
+ * to the original pixels — the same contract as Claude Code's
+ * `createImageMetadataText` (`src/utils/imageResizer.ts`). Kept verbatim in
+ * shape: original size, displayed size, and the factor to multiply by.
+ *
+ * `fit: "inside"` scales both sides by one factor, so a single ratio (taken
+ * from whichever side shrank more, to stay correct under rounding) applies.
+ * Callers only append it when the dimensions actually changed.
+ */
+export function resizedImageNote(original, displayed) {
+    const ratio = Math.max(original.width / displayed.width, original.height / displayed.height);
+    return (`[Image: original ${original.width}x${original.height}, displayed at ` +
+        `${displayed.width}x${displayed.height}. Multiply coordinates by ` +
+        `${ratio.toFixed(2)} to map to the original image.]`);
+}

package/dist/utils/imageDimensions.d.ts

@@ -0,0 +1,83 @@
+/**
+ * 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 declare const MAX_IMAGE_DIMENSION_PX = 8192;
+export interface ImageDimensions {
+    width: number;
+    height: number;
+}
+/**
+ * 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 declare function getImageDimensions(bytes: Uint8Array): ImageDimensions | undefined;
+export declare function getImageDimensionsFromDataUrl(dataUrl: string): ImageDimensions | undefined;
+export declare function exceedsMaxDimension(dimensions: ImageDimensions, max?: number): boolean;
+/**
+ * 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 declare function omittedImageNote(dimensions: ImageDimensions, sourcePath?: string): string;