@cjhyy/code-shell-core 0.5.0-rc.0 → 0.5.0-rc.2

package/dist/engine/goal.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Goal mode P0 — run-scoped budget guardrails.
+ *
+ * `GoalConfig` is the normalized internal shape. Public entry points
+ * (protocol/server, engine run) accept `string | GoalConfig` for
+ * back-compat and call `normalizeGoal()` once at the boundary; everything
+ * inward uses `GoalConfig`.
+ *
+ * The budget tracker is RUN-scoped (not per-turn like token-budget.ts):
+ * it accumulates total tokens across turns and stamps a wall-clock start,
+ * so an unattended goal run can't burn tokens or wall time without bound.
+ */
+export interface GoalConfig {
+    /** The objective text shown to the judge / injected into context. */
+    objective: string;
+    /** Hard cap on total tokens (prompt+completion) for the whole goal run. */
+    tokenBudget?: number;
+    /** Hard cap on wall-clock duration of the whole goal run, in ms. */
+    timeBudgetMs?: number;
+}
+/**
+ * Coerce a raw goal input into a normalized GoalConfig, or undefined when
+ * there is effectively no goal (empty objective). Drops non-positive
+ * budgets (0 / negative → "no limit", same as absent).
+ */
+export declare function normalizeGoal(raw: string | GoalConfig | undefined): GoalConfig | undefined;
+export interface GoalBudgetTracker {
+    goal: GoalConfig;
+    /** Wall-clock start (ms epoch), captured at run start. */
+    startedAtMs: number;
+    /** Accumulated total tokens (prompt + completion) across all turns. */
+    tokensUsed: number;
+}
+/** Create a run-scoped tracker. `nowMs` is injected for testability. */
+export declare function createGoalBudgetTracker(goal: GoalConfig, nowMs: number): GoalBudgetTracker;
+/** Add this turn's token usage to the running total. */
+export declare function recordGoalUsage(tracker: GoalBudgetTracker, turnTokens: number): void;
+/**
+ * Has the run exceeded any configured budget? `nowMs` is injected so callers
+ * pass the current clock (and tests pass a fixed value).
+ */
+export declare function goalBudgetExceeded(tracker: GoalBudgetTracker, nowMs: number): boolean;

package/dist/engine/goal.js

@@ -0,0 +1,52 @@
+/**
+ * Goal mode P0 — run-scoped budget guardrails.
+ *
+ * `GoalConfig` is the normalized internal shape. Public entry points
+ * (protocol/server, engine run) accept `string | GoalConfig` for
+ * back-compat and call `normalizeGoal()` once at the boundary; everything
+ * inward uses `GoalConfig`.
+ *
+ * The budget tracker is RUN-scoped (not per-turn like token-budget.ts):
+ * it accumulates total tokens across turns and stamps a wall-clock start,
+ * so an unattended goal run can't burn tokens or wall time without bound.
+ */
+/**
+ * Coerce a raw goal input into a normalized GoalConfig, or undefined when
+ * there is effectively no goal (empty objective). Drops non-positive
+ * budgets (0 / negative → "no limit", same as absent).
+ */
+export function normalizeGoal(raw) {
+    if (raw == null)
+        return undefined;
+    const obj = typeof raw === "string" ? { objective: raw } : { ...raw };
+    const objective = (obj.objective ?? "").trim();
+    if (!objective)
+        return undefined;
+    const out = { objective };
+    if (typeof obj.tokenBudget === "number" && obj.tokenBudget > 0)
+        out.tokenBudget = obj.tokenBudget;
+    if (typeof obj.timeBudgetMs === "number" && obj.timeBudgetMs > 0)
+        out.timeBudgetMs = obj.timeBudgetMs;
+    return out;
+}
+/** Create a run-scoped tracker. `nowMs` is injected for testability. */
+export function createGoalBudgetTracker(goal, nowMs) {
+    return { goal, startedAtMs: nowMs, tokensUsed: 0 };
+}
+/** Add this turn's token usage to the running total. */
+export function recordGoalUsage(tracker, turnTokens) {
+    if (turnTokens > 0)
+        tracker.tokensUsed += turnTokens;
+}
+/**
+ * Has the run exceeded any configured budget? `nowMs` is injected so callers
+ * pass the current clock (and tests pass a fixed value).
+ */
+export function goalBudgetExceeded(tracker, nowMs) {
+    const { tokenBudget, timeBudgetMs } = tracker.goal;
+    if (typeof tokenBudget === "number" && tracker.tokensUsed > tokenBudget)
+        return true;
+    if (typeof timeBudgetMs === "number" && nowMs - tracker.startedAtMs > timeBudgetMs)
+        return true;
+    return false;
+}

package/dist/engine/image-compression.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Engine-side image compression — the fallback for hosts that didn't
+ * pre-compress.
+ *
+ * The desktop renderer already compresses via <canvas> + Blob before
+ * sending; the TUI and MCP image-returning tools historically didn't.
+ * When the {@link enforceImagePolicy} gate would otherwise refuse a
+ * turn for "image too large", we try to bring the offender(s) under
+ * the limit first by:
+ *
+ *   1. Decoding the base64 payload.
+ *   2. Resizing the longest edge down to {@link IMAGE_TARGETS.targetMaxDimension}.
+ *   3. Re-encoding as JPEG at {@link IMAGE_TARGETS.jpegQuality}.
+ *
+ * jimp is the obvious pick — pure-JS, no native binaries, runs in
+ * both Node and Bun, supports PNG / JPEG / WebP input. But shipping
+ * it as a hard `core` dep would balloon the published bundle for
+ * every consumer. So we resolve it dynamically: hosts that want
+ * automatic compression just `npm install jimp`; everyone else gets
+ * the existing "image too large" refusal.
+ *
+ * Hosts can also inject a custom {@link ImageCompressor} via
+ * {@link setEngineImageCompressor} — useful for tests, future
+ * sharp-based compressors, or arena agents with different size
+ * targets.
+ *
+ * The defaults must stay pure-JS so this module is safe to bundle for
+ * Electron preload / browser worker contexts. Anything that needs
+ * native code (e.g. sharp) should be injected explicitly.
+ */
+import type { ParsedImage } from "./parse-task.js";
+/**
+ * Outcome of one compression attempt. `compressed` is set only when
+ * the host actually re-encoded the image — callers can compare bytes
+ * before/after to decide whether to log the optimization.
+ */
+export interface ImageCompressionResult {
+    /** The (possibly) re-encoded image, ready to replace the original. */
+    image: ParsedImage;
+    /** True if the host actually produced new bytes. */
+    compressed: boolean;
+    /** Source size in decoded bytes (informational only). */
+    originalBytes: number;
+    /** Final size in decoded bytes (informational only). */
+    finalBytes: number;
+}
+/**
+ * Compressor strategy. Implementations should be idempotent — re-
+ * running compression on an already-small image should be a no-op,
+ * returning `compressed: false`.
+ */
+export interface ImageCompressor {
+    /**
+     * Attempt to bring `image` under `maxBytes`. Implementations may
+     * downscale, re-encode, or otherwise transform the payload. Return
+     * the original image with `compressed: false` if nothing helped.
+     *
+     * Implementations MUST NOT mutate `image` — return a new ParsedImage
+     * with the new base64.
+     */
+    compress(image: ParsedImage, maxBytes: number): Promise<ImageCompressionResult>;
+}
+/**
+ * Override the engine's active compressor. Pass `null` to clear the
+ * override and fall back to lazy jimp resolution. Hosts that want
+ * deterministic behavior in tests typically call this with a stub.
+ */
+export declare function setEngineImageCompressor(c: ImageCompressor | null): void;
+/** Reset state — for tests. */
+export declare function resetEngineImageCompressor(): void;
+/**
+ * Try compressing every image in the batch so it fits under the
+ * single-image cap. Returns the (possibly transformed) batch plus a
+ * summary of what changed. Callers should hand the returned images
+ * back into {@link enforceImagePolicy} to confirm; this function
+ * doesn't itself decide whether the result is acceptable.
+ */
+export declare function tryCompressImages(images: readonly ParsedImage[]): Promise<{
+    images: ParsedImage[];
+    anyCompressed: boolean;
+}>;

package/dist/engine/image-compression.js

@@ -0,0 +1,186 @@
+/**
+ * Engine-side image compression — the fallback for hosts that didn't
+ * pre-compress.
+ *
+ * The desktop renderer already compresses via <canvas> + Blob before
+ * sending; the TUI and MCP image-returning tools historically didn't.
+ * When the {@link enforceImagePolicy} gate would otherwise refuse a
+ * turn for "image too large", we try to bring the offender(s) under
+ * the limit first by:
+ *
+ *   1. Decoding the base64 payload.
+ *   2. Resizing the longest edge down to {@link IMAGE_TARGETS.targetMaxDimension}.
+ *   3. Re-encoding as JPEG at {@link IMAGE_TARGETS.jpegQuality}.
+ *
+ * jimp is the obvious pick — pure-JS, no native binaries, runs in
+ * both Node and Bun, supports PNG / JPEG / WebP input. But shipping
+ * it as a hard `core` dep would balloon the published bundle for
+ * every consumer. So we resolve it dynamically: hosts that want
+ * automatic compression just `npm install jimp`; everyone else gets
+ * the existing "image too large" refusal.
+ *
+ * Hosts can also inject a custom {@link ImageCompressor} via
+ * {@link setEngineImageCompressor} — useful for tests, future
+ * sharp-based compressors, or arena agents with different size
+ * targets.
+ *
+ * The defaults must stay pure-JS so this module is safe to bundle for
+ * Electron preload / browser worker contexts. Anything that needs
+ * native code (e.g. sharp) should be injected explicitly.
+ */
+import { IMAGE_LIMITS, IMAGE_TARGETS, byteLengthFromBase64 } from "./image-policy.js";
+/**
+ * No-op compressor: returns the input unchanged. Used when the host
+ * didn't install jimp and didn't inject anything else, so behavior
+ * stays the same as before this module existed.
+ */
+const NOOP_COMPRESSOR = {
+    async compress(image, _maxBytes) {
+        const bytes = byteLengthFromBase64(image.base64);
+        return {
+            image,
+            compressed: false,
+            originalBytes: bytes,
+            finalBytes: bytes,
+        };
+    },
+};
+let activeCompressor = null;
+/**
+ * Override the engine's active compressor. Pass `null` to clear the
+ * override and fall back to lazy jimp resolution. Hosts that want
+ * deterministic behavior in tests typically call this with a stub.
+ */
+export function setEngineImageCompressor(c) {
+    activeCompressor = c;
+}
+/** Reset state — for tests. */
+export function resetEngineImageCompressor() {
+    activeCompressor = null;
+    cachedJimpCompressor = null;
+}
+let cachedJimpCompressor = null;
+/**
+ * Resolve a jimp-backed compressor on first call. If jimp isn't
+ * installed, cache the no-op and stop retrying.
+ *
+ * jimp's API: `await Jimp.read(buffer)` → resize / quality / getBuffer.
+ * v0.x used CamelCase constants (e.g. `Jimp.MIME_JPEG`); v1 moved to
+ * an explicit string mime arg. We accept both by feature-testing.
+ */
+async function resolveJimpCompressor() {
+    if (cachedJimpCompressor)
+        return cachedJimpCompressor;
+    try {
+        // Dynamic import so consumers without jimp installed don't pay
+        // the bundle cost. The default export shape differs across v0/v1,
+        // hence the `any` cast. The literal module specifier is a string
+        // we resolve at runtime — TS sees no type info for it and would
+        // otherwise error TS2307 when jimp isn't on the host's path.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const dynImport = (s) => 
+        // eslint-disable-next-line @typescript-eslint/no-implied-eval
+        Function("s", "return import(s)")(s);
+        const mod = (await dynImport("jimp"));
+        const Jimp = (mod.default ?? mod.Jimp ?? mod);
+        cachedJimpCompressor = {
+            async compress(image, maxBytes) {
+                const original = Buffer.from(image.base64, "base64");
+                const originalBytes = original.byteLength;
+                if (originalBytes <= maxBytes) {
+                    return { image, compressed: false, originalBytes, finalBytes: originalBytes };
+                }
+                let pic;
+                try {
+                    pic = await Jimp.read(original);
+                }
+                catch {
+                    // Unknown / corrupt format. Leave it alone; the policy gate
+                    // will refuse and surface a meaningful message to the user.
+                    return { image, compressed: false, originalBytes, finalBytes: originalBytes };
+                }
+                // Scale longest edge down to the target. We may still be over
+                // after one pass for very large source images, so loop with
+                // decreasing quality / dimension until under cap or we hit the
+                // floor.
+                const targets = [
+                    { dim: IMAGE_TARGETS.targetMaxDimension, q: Math.round(IMAGE_TARGETS.jpegQuality * 100) },
+                    { dim: 1280, q: 75 },
+                    { dim: 1024, q: 65 },
+                    { dim: 800, q: 55 },
+                ];
+                const mime = Jimp.MIME_JPEG ?? "image/jpeg";
+                let bestBuf = null;
+                for (const t of targets) {
+                    const w = pic.bitmap?.width ?? t.dim;
+                    const h = pic.bitmap?.height ?? t.dim;
+                    const longest = Math.max(w, h);
+                    // Only scale down — never up an already-small image.
+                    if (longest > t.dim) {
+                        if (w >= h) {
+                            pic.resize(t.dim, Math.round((h / w) * t.dim));
+                        }
+                        else {
+                            pic.resize(Math.round((w / h) * t.dim), t.dim);
+                        }
+                    }
+                    pic.quality(t.q);
+                    const buf = await pic.getBufferAsync(mime);
+                    if (buf.byteLength <= maxBytes) {
+                        bestBuf = buf;
+                        break;
+                    }
+                    bestBuf = buf;
+                }
+                if (!bestBuf) {
+                    return { image, compressed: false, originalBytes, finalBytes: originalBytes };
+                }
+                const finalBytes = bestBuf.byteLength;
+                const out = {
+                    ...image,
+                    base64: bestBuf.toString("base64"),
+                    mime: "image/jpeg",
+                };
+                return {
+                    image: out,
+                    compressed: true,
+                    originalBytes,
+                    finalBytes,
+                };
+            },
+        };
+    }
+    catch {
+        cachedJimpCompressor = NOOP_COMPRESSOR;
+    }
+    return cachedJimpCompressor;
+}
+/**
+ * Try compressing every image in the batch so it fits under the
+ * single-image cap. Returns the (possibly transformed) batch plus a
+ * summary of what changed. Callers should hand the returned images
+ * back into {@link enforceImagePolicy} to confirm; this function
+ * doesn't itself decide whether the result is acceptable.
+ */
+export async function tryCompressImages(images) {
+    if (images.length === 0)
+        return { images: [], anyCompressed: false };
+    const compressor = activeCompressor ?? (await resolveJimpCompressor());
+    if (compressor === NOOP_COMPRESSOR) {
+        return { images: images.slice(), anyCompressed: false };
+    }
+    const out = [];
+    let anyCompressed = false;
+    for (const img of images) {
+        const bytes = byteLengthFromBase64(img.base64);
+        if (bytes <= IMAGE_LIMITS.maxBytesPerImage) {
+            out.push(img);
+            continue;
+        }
+        const result = await compressor.compress(img, IMAGE_LIMITS.maxBytesPerImage);
+        out.push(result.image);
+        if (result.compressed)
+            anyCompressed = true;
+    }
+    return { images: out, anyCompressed };
+}

package/dist/engine/image-policy.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Engine-side image policy: a single source of truth for what counts as
+ * an "OK to ship to the model" attachment.
+ *
+ * Why this exists
+ * ---------------
+ * The desktop renderer happily takes a 4 MB screenshot, base64-encodes it,
+ * and ships it to the LLM. OpenAI-compatible providers stream the request
+ * body; a payload that fat plus a flaky link manifests as
+ * `OpenAI API error: Connection error.` with no useful classification,
+ * three retries deep. That bug is in our session log
+ * `s-mppk3ot5-02d35ca4`: textLen=4,364,933, promptTokens=1,091,232.
+ *
+ * The right fix is to keep the bytes small *before* they leave the host.
+ * But not every entry point has the same compressor available:
+ *   - desktop renderer has <canvas> + Blob, no native deps
+ *   - TUI runs in plain Node and has neither
+ *   - MCP tools / future arena agents will need it too
+ *
+ * So this module owns:
+ *   1. The shared *thresholds* every host honors before sending to the LLM
+ *      (`IMAGE_LIMITS`).
+ *   2. A `byteLengthFromBase64()` helper everyone uses to measure decoded
+ *      payload size without actually decoding it.
+ *   3. An `enforceImagePolicy()` engine gate that runs *after* parse-task
+ *      and *before* the message hits the provider. When a single image
+ *      blows the limit, the gate refuses the turn with a friendly error
+ *      and a hint telling the user what to do. The engine is the last
+ *      place we can refuse cheaply — the next step is a $0.10 vision call
+ *      over a flaky socket.
+ *
+ * Hosts (desktop, TUI) are encouraged to compress upstream so this gate
+ * never fires in practice. When it does fire, the user gets a clear
+ * message instead of "Connection error. Connection error. Connection
+ * error.".
+ *
+ * Pure + no I/O — safe to use from any caller.
+ */
+import type { ParsedImage } from "./parse-task.js";
+/**
+ * Hard limits the engine enforces. Soft hints (target sizes) live in
+ * `IMAGE_TARGETS` so hosts know what to aim for when they pre-compress.
+ *
+ * Rationale for each number:
+ *   - `maxBytesPerImage`: 2 MB decoded. OpenAI's `gpt-4o` accepts up to
+ *     20 MB but charges by tile count; 2 MB ≈ a 2048×2048 PNG which is
+ *     plenty for every UI screenshot. Above this we've measured the
+ *     "Connection error" failure mode in practice.
+ *   - `maxBytesPerTurn`: 6 MB total, regardless of count. The four-image
+ *     attach is the typical worst case from the desktop UI, and 4× the
+ *     per-image cap would blow past most providers' rate-limited request
+ *     body sizes.
+ *   - `maxImagesPerTurn`: 6 (matches the desktop renderer's UI limit, so
+ *     a wider engine gate is just dead defense).
+ */
+export declare const IMAGE_LIMITS: {
+    readonly maxBytesPerImage: number;
+    readonly maxBytesPerTurn: number;
+    readonly maxImagesPerTurn: 6;
+};
+/**
+ * Soft targets hosts use when pre-compressing. `targetMaxDimension` is
+ * the longest-edge pixel cap that *almost always* keeps a JPEG under
+ * `maxBytesPerImage`. Hosts re-encode at `jpegQuality` and only escalate
+ * the compression if the result is still over.
+ */
+export declare const IMAGE_TARGETS: {
+    readonly targetMaxDimension: 2048;
+    readonly jpegQuality: 0.82;
+};
+/**
+ * Decode-free size estimate of a base64 string.
+ *
+ * Returns the count of bytes the base64 string would produce *after*
+ * decoding. Used everywhere we need to "weigh" an image without paying
+ * the cost of `Buffer.from(s, "base64")` allocation.
+ *
+ *   - 4 base64 chars → 3 decoded bytes.
+ *   - Trailing `=` padding subtracts from the byte count.
+ *   - Tolerates whitespace and missing padding by working off `length`
+ *     modulo 4 — the wire format strips whitespace via parse-task, so
+ *     this only matters when an exotic caller hands us raw textarea text.
+ */
+export declare function byteLengthFromBase64(b64: string): number;
+/**
+ * Verdict returned by {@link enforceImagePolicy}. `ok: true` means the
+ * caller can proceed with the original images unchanged. `ok: false`
+ * carries a user-facing message + machine-readable reason so callers can
+ * decide whether to render an error card or refuse the turn outright.
+ */
+export type ImagePolicyVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    /**
+     * Stable string the engine surfaces as the run's terminal reason.
+     * Distinct values so a future UI could pick different icons.
+     */
+    code: "image_too_large" | "images_total_too_large" | "too_many_images";
+    /** User-facing message — Chinese-friendly because both UIs are zh. */
+    message: string;
+    /** Optional fields the UI may use for finer-grained reporting. */
+    offender?: {
+        name: string;
+        mime: string;
+        bytes: number;
+    };
+    totals: {
+        imageCount: number;
+        totalBytes: number;
+    };
+};
+/**
+ * Run the per-turn image policy.
+ *
+ * Three failure modes, all surfaced with a Chinese-language hint that
+ * tells the user *what to do next*:
+ *
+ *   1. Per-image cap exceeded → name the file + the cap, suggest
+ *      re-saving / cropping. (`code: "image_too_large"`)
+ *   2. Per-turn cumulative cap exceeded → total bytes + cap. The user
+ *      likely attached too many screenshots; suggest removing some.
+ *      (`code: "images_total_too_large"`)
+ *   3. Count cap exceeded → the desktop UI already caps at 6, so this
+ *      mostly catches future-MCP / TUI batch paths. (`code: "too_many_images"`)
+ *
+ * The gate is **strict** — no silent truncation. The "Connection error"
+ * failure mode this exists to prevent was effectively a silent truncate
+ * (bytes lost mid-stream); a friendly refusal is strictly better.
+ */
+/**
+ * Drop the images that exceed {@link IMAGE_LIMITS.maxBytesPerImage}
+ * and return a textual placeholder describing what was removed. The
+ * engine uses this to keep a poisoned image out of conversation
+ * history while still letting the rest of the turn proceed — Claude
+ * Code's "5MB brick session" failure mode is exactly the bug where
+ * a too-large image enters history and every subsequent request
+ * re-sends it (see docs/research-cc-vs-codex-image-handling.md §A).
+ *
+ * Returns the filtered image list and, when anything was dropped, a
+ * Chinese-language note suitable for prepending to the user text.
+ */
+export interface DropOversizedResult {
+    /** Images that fit under the per-image cap (in original order). */
+    kept: ParsedImage[];
+    /** A human-readable note about what was removed, or "" if nothing was. */
+    placeholder: string;
+    /** Number of images removed. */
+    droppedCount: number;
+}
+export declare function dropOversizedImages(images: readonly ParsedImage[]): DropOversizedResult;
+export declare function enforceImagePolicy(images: readonly ParsedImage[]): ImagePolicyVerdict;

package/dist/engine/image-policy.js

@@ -0,0 +1,165 @@
+/**
+ * Engine-side image policy: a single source of truth for what counts as
+ * an "OK to ship to the model" attachment.
+ *
+ * Why this exists
+ * ---------------
+ * The desktop renderer happily takes a 4 MB screenshot, base64-encodes it,
+ * and ships it to the LLM. OpenAI-compatible providers stream the request
+ * body; a payload that fat plus a flaky link manifests as
+ * `OpenAI API error: Connection error.` with no useful classification,
+ * three retries deep. That bug is in our session log
+ * `s-mppk3ot5-02d35ca4`: textLen=4,364,933, promptTokens=1,091,232.
+ *
+ * The right fix is to keep the bytes small *before* they leave the host.
+ * But not every entry point has the same compressor available:
+ *   - desktop renderer has <canvas> + Blob, no native deps
+ *   - TUI runs in plain Node and has neither
+ *   - MCP tools / future arena agents will need it too
+ *
+ * So this module owns:
+ *   1. The shared *thresholds* every host honors before sending to the LLM
+ *      (`IMAGE_LIMITS`).
+ *   2. A `byteLengthFromBase64()` helper everyone uses to measure decoded
+ *      payload size without actually decoding it.
+ *   3. An `enforceImagePolicy()` engine gate that runs *after* parse-task
+ *      and *before* the message hits the provider. When a single image
+ *      blows the limit, the gate refuses the turn with a friendly error
+ *      and a hint telling the user what to do. The engine is the last
+ *      place we can refuse cheaply — the next step is a $0.10 vision call
+ *      over a flaky socket.
+ *
+ * Hosts (desktop, TUI) are encouraged to compress upstream so this gate
+ * never fires in practice. When it does fire, the user gets a clear
+ * message instead of "Connection error. Connection error. Connection
+ * error.".
+ *
+ * Pure + no I/O — safe to use from any caller.
+ */
+/**
+ * Hard limits the engine enforces. Soft hints (target sizes) live in
+ * `IMAGE_TARGETS` so hosts know what to aim for when they pre-compress.
+ *
+ * Rationale for each number:
+ *   - `maxBytesPerImage`: 2 MB decoded. OpenAI's `gpt-4o` accepts up to
+ *     20 MB but charges by tile count; 2 MB ≈ a 2048×2048 PNG which is
+ *     plenty for every UI screenshot. Above this we've measured the
+ *     "Connection error" failure mode in practice.
+ *   - `maxBytesPerTurn`: 6 MB total, regardless of count. The four-image
+ *     attach is the typical worst case from the desktop UI, and 4× the
+ *     per-image cap would blow past most providers' rate-limited request
+ *     body sizes.
+ *   - `maxImagesPerTurn`: 6 (matches the desktop renderer's UI limit, so
+ *     a wider engine gate is just dead defense).
+ */
+export const IMAGE_LIMITS = {
+    maxBytesPerImage: 2 * 1024 * 1024,
+    maxBytesPerTurn: 6 * 1024 * 1024,
+    maxImagesPerTurn: 6,
+};
+/**
+ * Soft targets hosts use when pre-compressing. `targetMaxDimension` is
+ * the longest-edge pixel cap that *almost always* keeps a JPEG under
+ * `maxBytesPerImage`. Hosts re-encode at `jpegQuality` and only escalate
+ * the compression if the result is still over.
+ */
+export const IMAGE_TARGETS = {
+    targetMaxDimension: 2048,
+    jpegQuality: 0.82,
+};
+/**
+ * Decode-free size estimate of a base64 string.
+ *
+ * Returns the count of bytes the base64 string would produce *after*
+ * decoding. Used everywhere we need to "weigh" an image without paying
+ * the cost of `Buffer.from(s, "base64")` allocation.
+ *
+ *   - 4 base64 chars → 3 decoded bytes.
+ *   - Trailing `=` padding subtracts from the byte count.
+ *   - Tolerates whitespace and missing padding by working off `length`
+ *     modulo 4 — the wire format strips whitespace via parse-task, so
+ *     this only matters when an exotic caller hands us raw textarea text.
+ */
+export function byteLengthFromBase64(b64) {
+    if (!b64)
+        return 0;
+    // Strip whitespace defensively; the parser already does this, but other
+    // callers (logging stubs, MCP image blocks) might not.
+    const clean = b64.replace(/\s+/g, "");
+    const padding = clean.endsWith("==") ? 2 : clean.endsWith("=") ? 1 : 0;
+    return Math.floor((clean.length * 3) / 4) - padding;
+}
+function fmtMB(bytes) {
+    return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+export function dropOversizedImages(images) {
+    const kept = [];
+    const dropped = [];
+    for (const img of images) {
+        const bytes = byteLengthFromBase64(img.base64);
+        if (bytes > IMAGE_LIMITS.maxBytesPerImage) {
+            dropped.push({ name: img.name || "(未命名)", bytes });
+        }
+        else {
+            kept.push(img);
+        }
+    }
+    if (dropped.length === 0) {
+        return { kept, placeholder: "", droppedCount: 0 };
+    }
+    const list = dropped
+        .map((d) => `「${d.name}」(~${fmtMB(d.bytes)})`)
+        .join("、");
+    const placeholder = `[已自动跳过 ${dropped.length} 张超大图片:${list};` +
+        `单图上限 ${fmtMB(IMAGE_LIMITS.maxBytesPerImage)}。` +
+        `图片未进入对话历史,本轮其余内容继续。]`;
+    return { kept, placeholder, droppedCount: dropped.length };
+}
+export function enforceImagePolicy(images) {
+    if (images.length === 0)
+        return { ok: true };
+    if (images.length > IMAGE_LIMITS.maxImagesPerTurn) {
+        return {
+            ok: false,
+            code: "too_many_images",
+            message: `一次最多附 ${IMAGE_LIMITS.maxImagesPerTurn} 张图片，` +
+                `本次有 ${images.length} 张。请删掉一些再发。`,
+            totals: {
+                imageCount: images.length,
+                totalBytes: images.reduce((s, i) => s + byteLengthFromBase64(i.base64), 0),
+            },
+        };
+    }
+    let totalBytes = 0;
+    for (const img of images) {
+        const bytes = byteLengthFromBase64(img.base64);
+        if (bytes > IMAGE_LIMITS.maxBytesPerImage) {
+            return {
+                ok: false,
+                code: "image_too_large",
+                message: `图片「${img.name || "(未命名)"}」解码后约 ${fmtMB(bytes)}，` +
+                    `超过单图上限 ${fmtMB(IMAGE_LIMITS.maxBytesPerImage)}。` +
+                    `请先截图压缩或保存为 JPEG（最长边 ≤ ${IMAGE_TARGETS.targetMaxDimension}px）再发。`,
+                offender: { name: img.name, mime: img.mime, bytes },
+                totals: {
+                    imageCount: images.length,
+                    totalBytes: totalBytes + bytes,
+                },
+            };
+        }
+        totalBytes += bytes;
+    }
+    if (totalBytes > IMAGE_LIMITS.maxBytesPerTurn) {
+        return {
+            ok: false,
+            code: "images_total_too_large",
+            message: `本次附图合计约 ${fmtMB(totalBytes)}，超过每轮上限 ${fmtMB(IMAGE_LIMITS.maxBytesPerTurn)}。` +
+                `请删掉一些图片，或先把图片压缩后再发。`,
+            totals: {
+                imageCount: images.length,
+                totalBytes,
+            },
+        };
+    }
+    return { ok: true };
+}