@armadra/agent 0.3.0 → 0.5.0

package/dist/tools/clipboard-image.js

@@ -0,0 +1,148 @@
+/**
+ * 剪贴板图片（docs/wave5-plan.md §4、D12）。[W5-I] 界面接线（`Ctrl+V`、`/paste`）归 W5-U。
+ *
+ * 零依赖读不了剪贴板位图，按平台依次调系统命令，成功写 `<dataDir>/clipboard/<时间戳>.png` 并返回
+ * 路径（编辑器插入 `@<路径>`，之后走 loadImageFile）；没有工具或剪贴板里没有图返回 undefined：
+ *
+ * | 平台    | 依次尝试                                                                    |
+ * | ------- | --------------------------------------------------------------------------- |
+ * | macOS   | `osascript`（`the clipboard as «class PNGf»` 写文件）、`pngpaste <文件>`     |
+ * | Linux   | Wayland（有 WAYLAND_DISPLAY）`wl-paste -t image/png`；`xclip -selection clipboard -t image/png -o` |
+ * | Windows | `powershell` 的 `Get-Clipboard -Format Image` 存 PNG（路径经环境变量传入）  |
+ *
+ * 写出的文件必须以 PNG 文件头开头，否则删掉按「没有图」处理。`ama sessions prune` 清理超过 7 天的
+ * 剪贴板文件（`gcClipboardImages`）。
+ */
+import { existsSync } from "node:fs";
+import { mkdir, readdir, rm, stat, writeFile, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { sniffImageMime } from "./image-file.js";
+import { runCommand } from "./image-resize.js";
+export const CLIPBOARD_DIR = "clipboard";
+export const CLIPBOARD_MAX_AGE_DAYS = 7;
+const OSASCRIPT = [
+    "on run argv",
+    "try",
+    "set png to the clipboard as «class PNGf»",
+    "on error",
+    'return "none"',
+    "end try",
+    "set f to open for access (POSIX file (item 1 of argv)) with write permission",
+    "set eof f to 0",
+    "write png to f",
+    "close access f",
+    'return "ok"',
+    "end run",
+];
+const POWERSHELL = "$img = Get-Clipboard -Format Image; " +
+    "if ($null -eq $img) { exit 3 }; " +
+    "$img.Save($env:AMA_CLIPBOARD_OUT, [System.Drawing.Imaging.ImageFormat]::Png)";
+function attempts(platform, file, env) {
+    if (platform === "darwin") {
+        return [
+            {
+                tool: "osascript",
+                command: "osascript",
+                args: [...OSASCRIPT.flatMap((line) => ["-e", line]), file],
+                via: "file",
+            },
+            { tool: "pngpaste", command: "pngpaste", args: [file], via: "file" },
+        ];
+    }
+    if (platform === "win32") {
+        return [
+            {
+                tool: "powershell",
+                command: "powershell",
+                args: ["-NoProfile", "-NonInteractive", "-STA", "-Command", POWERSHELL],
+                via: "file",
+                env: { ...env, AMA_CLIPBOARD_OUT: file },
+            },
+        ];
+    }
+    const list = [];
+    if (env["WAYLAND_DISPLAY"]) {
+        list.push({ tool: "wl-paste", command: "wl-paste", args: ["-t", "image/png"], via: "stdout" });
+    }
+    list.push({
+        tool: "xclip",
+        command: "xclip",
+        args: ["-selection", "clipboard", "-t", "image/png", "-o"],
+        via: "stdout",
+    });
+    return list;
+}
+async function isPng(file) {
+    try {
+        return sniffImageMime(await readFile(file)) === "image/png";
+    }
+    catch {
+        return false;
+    }
+}
+/** 读剪贴板图片到数据目录；返回结果与原因（界面据此给一行提示）。 */
+export async function readClipboardImage(dataDir, deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const env = deps.env ?? process.env;
+    const run = deps.run ?? runCommand;
+    const dir = join(dataDir, CLIPBOARD_DIR);
+    await mkdir(dir, { recursive: true });
+    const stamp = new Date((deps.now ?? Date.now)()).toISOString().replace(/[:.]/g, "-");
+    // 同一毫秒再贴：加序号，不能把上一张当成这次的结果
+    let file = join(dir, `${stamp}.png`);
+    for (let n = 1; existsSync(file); n++)
+        file = join(dir, `${stamp}-${n}.png`);
+    let anyTool = false;
+    for (const attempt of attempts(platform, file, env)) {
+        const options = attempt.via === "file" && attempt.env !== undefined ? { env: attempt.env } : {};
+        const result = await run(attempt.command, attempt.args, options);
+        if (result.missing === true)
+            continue;
+        anyTool = true;
+        if (result.code !== 0)
+            continue;
+        if (attempt.via === "stdout") {
+            if (sniffImageMime(result.stdout) !== "image/png")
+                continue;
+            await writeFile(file, result.stdout);
+        }
+        if (await isPng(file))
+            return { ok: true, path: file, tool: attempt.tool };
+        await rm(file, { force: true });
+    }
+    await rm(file, { force: true });
+    return { ok: false, reason: anyTool ? "no_image" : "no_tool" };
+}
+/** §10.2 的签名：成功返回 PNG 路径，没有工具或没有图返回 undefined。 */
+export async function pasteClipboardImage(dataDir, deps = {}) {
+    const result = await readClipboardImage(dataDir, deps);
+    return result.ok ? result.path : undefined;
+}
+/** 清理 `<dataDir>/clipboard/` 里超过 `maxAgeDays`（缺省 7）天的文件；返回（将）删除的路径。 */
+export async function gcClipboardImages(dataDir, options = {}) {
+    const dir = join(dataDir, CLIPBOARD_DIR);
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const cutoff = (options.now ?? Date.now()) - (options.maxAgeDays ?? CLIPBOARD_MAX_AGE_DAYS) * 86_400_000;
+    const removed = [];
+    for (const name of names) {
+        const file = join(dir, name);
+        try {
+            const info = await stat(file);
+            if (!info.isFile() || info.mtimeMs >= cutoff)
+                continue;
+            if (options.dryRun !== true)
+                await rm(file, { force: true });
+            removed.push(file);
+        }
+        catch {
+            // 并发删除等：跳过
+        }
+    }
+    return removed;
+}

package/dist/tools/edit.d.ts

@@ -34,5 +34,7 @@ export interface EditPlan {
 export declare function planEdits(content: string, edits: readonly EditOp[], replaceAll?: boolean): EditPlan;
 /** 统一 diff（LF 文本，3 行上下文）；无差异返回空串。 */
 export declare function unifiedDiff(oldText: string, newText: string, path: string, context?: number): string;
+/** 检查点：写前备份（docs/rewind-plan.md §2）；钩子按约定不抛，这里再兜一层，不让编辑失败。 */
+export declare function beforeWrite(ctx: ToolContext, abs: string): Promise<void>;
 export declare function executeEdit(input: EditInput, ctx: ToolContext): Promise<ToolResult>;
 export declare function createEditTool(): ToolDefinition<EditInput>;

package/dist/tools/edit.js

@@ -164,6 +164,17 @@ function firstChangedLine(oldText, newText) {
 // ---------------------------------------------------------------------------
 // 工具
 // ---------------------------------------------------------------------------
+/** 检查点：写前备份（docs/rewind-plan.md §2）；钩子按约定不抛，这里再兜一层，不让编辑失败。 */
+export async function beforeWrite(ctx, abs) {
+    if (ctx.checkpoint === undefined)
+        return;
+    try {
+        await ctx.checkpoint.beforeWrite(abs);
+    }
+    catch (error) {
+        ctx.log("warn", `checkpoint: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
 export async function executeEdit(input, ctx) {
     const abs = resolvePath(input.path, ctx.cwd);
     const shown = displayPath(abs, ctx.cwd);
@@ -192,7 +203,10 @@ export async function executeEdit(input, ctx) {
                 return { content: `${shown}: ${err.message}`, isError: true };
             throw err;
         }
-        await writeFile(abs, bom + restoreLineEndings(plan.result, ending), "utf8");
+        const output = bom + restoreLineEndings(plan.result, ending);
+        await beforeWrite(ctx, abs);
+        await writeFile(abs, output, "utf8");
+        ctx.checkpoint?.afterWrite(abs, output);
         const details = {
             path: abs,
             diff: unifiedDiff(content, plan.result, shown),
@@ -209,8 +223,9 @@ export function createEditTool() {
     return {
         name: "edit",
         label: "Edit",
-        description: "Replace text in a file (read it first). Each oldText must be unique in the original " +
-            "(unless replaceAll); edits must not overlap.",
+        description: "Replace text in a file (read it first). Give all changes to a file as edits[] in one call; " +
+            "each oldText matches the original file and must be unique (unless replaceAll), short and " +
+            "non-overlapping.",
         parameters: {
             type: "object",
             properties: {

package/dist/tools/image-file.d.ts

@@ -2,11 +2,15 @@
  * 图片文件（`read` 工具、`ama -p --image`、界面里的 `@图片路径` 共用）：MIME 检测、尺寸、大小上限。
  *
  * - MIME 以文件头为准（PNG / JPEG / GIF / WebP），文件头认不出时退回扩展名；
- * - 单张上限 5 MB（各家图片上限里最小的 Anthropic）；
+ * - [W5-I] 单张上限按 **base64 后**计算，按端点分档（ai/image-limits.ts，缺省 5 MB）；任一边
+ *   > 8000 px 拒绝；超限时按 `images.resize`（缺省 auto）用系统工具缩放（image-resize.ts），
+ *   没有工具则拒绝并提示；
  * - 不解码像素，只读文件头取尺寸。
  */
 import type { ImageBlock } from "../ai/types.js";
-export declare const MAX_IMAGE_BYTES: number;
+import { type ResizeDeps } from "./image-resize.js";
+/** 读进内存前的硬上限（原始字节）：再大的文件缩放也不现实，直接拒绝。 */
+export declare const MAX_IMAGE_FILE_BYTES: number;
 export declare const IMAGE_EXTENSIONS: Readonly<Record<string, string>>;
 /** 按扩展名（不分大小写）；不是图片返回 undefined。 */
 export declare function imageMimeFromPath(path: string): string | undefined;
@@ -22,10 +26,41 @@ export interface LoadedImage {
     block: ImageBlock;
     path: string;
     mimeType: string;
+    /** 实际附上的字节数（缩放后为缩放结果的大小）。 */
     bytes: number;
     size?: ImageSize;
 }
+export interface ImageFitOptions {
+    /** 单张 base64 后的上限（字节）；缺省 5 MB（未知端点 / 中转）。 */
+    maxBase64Bytes?: number;
+    /** 超限时缩放：`auto`（缺省）找 sips / magick，`off` 从不缩放。 */
+    resize?: "auto" | "off";
+    /** 测试注入（平台、命令执行器）。 */
+    resizeDeps?: ResizeDeps;
+}
+export type ImageFit = {
+    ok: true;
+    buf: Buffer;
+    mimeType: string;
+    size?: ImageSize;
+    /** 缩放过：用的工具与原尺寸。 */
+    resized?: {
+        tool: string;
+        from?: ImageSize;
+    };
+} | {
+    ok: false;
+    mimeType: string;
+    size?: ImageSize;
+    reason: "too_large" | "too_wide";
+    /** 给模型 / 日志的英文说明（read 工具原样放进结果）。 */
+    note: string;
+};
+/**
+ * 检查一张图是否在上限内（base64 后大小、边长）；超限且给了 `path`、`resize` 不是 off 时先缩放再查。
+ */
+export declare function fitImage(buf: Buffer, mimeType: string, options?: ImageFitOptions, path?: string): Promise<ImageFit>;
 /**
  * 读一张图片作为附件。文件不存在、不是图片、超过上限 → AmaError（`invalid_arguments`），文案给用户看。
  */
-export declare function loadImageFile(path: string): Promise<LoadedImage>;
+export declare function loadImageFile(path: string, options?: ImageFitOptions): Promise<LoadedImage>;

package/dist/tools/image-file.js

@@ -2,13 +2,18 @@
  * 图片文件（`read` 工具、`ama -p --image`、界面里的 `@图片路径` 共用）：MIME 检测、尺寸、大小上限。
  *
  * - MIME 以文件头为准（PNG / JPEG / GIF / WebP），文件头认不出时退回扩展名；
- * - 单张上限 5 MB（各家图片上限里最小的 Anthropic）；
+ * - [W5-I] 单张上限按 **base64 后**计算，按端点分档（ai/image-limits.ts，缺省 5 MB）；任一边
+ *   > 8000 px 拒绝；超限时按 `images.resize`（缺省 auto）用系统工具缩放（image-resize.ts），
+ *   没有工具则拒绝并提示；
  * - 不解码像素，只读文件头取尺寸。
  */
 import { readFile, stat } from "node:fs/promises";
 import { extname } from "node:path";
 import { AmaError } from "../errors.js";
-export const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+import { DEFAULT_IMAGE_BASE64_LIMIT, MAX_IMAGE_EDGE, base64Size, formatMb, } from "../ai/image-limits.js";
+import { resizeImage } from "./image-resize.js";
+/** 读进内存前的硬上限（原始字节）：再大的文件缩放也不现实，直接拒绝。 */
+export const MAX_IMAGE_FILE_BYTES = 64 * 1024 * 1024;
 export const IMAGE_EXTENSIONS = {
     ".png": "image/png",
     ".jpg": "image/jpeg",
@@ -84,10 +89,73 @@ function webpSize(buf) {
     }
     return undefined;
 }
+function longEdge(size) {
+    return size === undefined ? 0 : Math.max(size.width, size.height);
+}
+function checkFit(buf, mimeType, limit) {
+    const size = imageSize(buf, mimeType);
+    const sized = size !== undefined ? { size } : {};
+    if (longEdge(size) > MAX_IMAGE_EDGE) {
+        return {
+            ok: false,
+            mimeType,
+            ...sized,
+            reason: "too_wide",
+            note: `Image is larger than ${MAX_IMAGE_EDGE}px on a side; not attached.`,
+        };
+    }
+    if (base64Size(buf.length) > limit) {
+        return {
+            ok: false,
+            mimeType,
+            ...sized,
+            reason: "too_large",
+            note: `Image exceeds the ${formatMb(limit)} attachment limit (base64); not attached.`,
+        };
+    }
+    return { ok: true, buf, mimeType, ...sized };
+}
+/**
+ * 检查一张图是否在上限内（base64 后大小、边长）；超限且给了 `path`、`resize` 不是 off 时先缩放再查。
+ */
+export async function fitImage(buf, mimeType, options = {}, path) {
+    const limit = options.maxBase64Bytes ?? DEFAULT_IMAGE_BASE64_LIMIT;
+    const fit = checkFit(buf, mimeType, limit);
+    if (fit.ok || path === undefined || options.resize === "off")
+        return fit;
+    const resized = await resizeImage(path, { maxEdge: MAX_IMAGE_EDGE, maxBase64Bytes: limit, mimeType, size: fit.size }, options.resizeDeps);
+    if (!resized.ok) {
+        const hint = resized.reason === "no_tool"
+            ? " (no resize tool found: install ImageMagick, or sips on macOS)"
+            : " (resizing did not bring it under the limit)";
+        return { ...fit, note: fit.note.replace(/; not attached\.$/, `${hint}; not attached.`) };
+    }
+    const again = checkFit(resized.buf, resized.mimeType, limit);
+    if (!again.ok)
+        return fit;
+    return {
+        ...again,
+        resized: { tool: resized.tool, ...(fit.size !== undefined ? { from: fit.size } : {}) },
+    };
+}
+function fitError(path, fit, limit, bytes, resizeOff) {
+    const hint = resizeOff
+        ? "（images.resize 为 off）"
+        : fit.note.includes("no resize tool")
+            ? "（没找到缩放工具：装 ImageMagick，macOS 自带 sips）"
+            : fit.note.includes("resizing did not")
+                ? "（缩放后仍超限）"
+                : "";
+    if (fit.reason === "too_wide") {
+        const dims = fit.size !== undefined ? `（${fit.size.width}×${fit.size.height}）` : "";
+        return new AmaError("invalid_arguments", `图片任一边超过 ${MAX_IMAGE_EDGE} px：${path}${dims}${hint}`);
+    }
+    return new AmaError("invalid_arguments", `图片超过 ${formatMb(limit)} 上限（按 base64 后计算）：${path}（${formatMb(base64Size(bytes))}）${hint}`);
+}
 /**
  * 读一张图片作为附件。文件不存在、不是图片、超过上限 → AmaError（`invalid_arguments`），文案给用户看。
  */
-export async function loadImageFile(path) {
+export async function loadImageFile(path, options = {}) {
     let info;
     try {
         info = await stat(path);
@@ -97,18 +165,21 @@ export async function loadImageFile(path) {
     }
     if (!info.isFile())
         throw new AmaError("invalid_arguments", `不是文件：${path}`);
-    if (info.size > MAX_IMAGE_BYTES)
-        throw new AmaError("invalid_arguments", `图片超过 ${MAX_IMAGE_BYTES / 1024 / 1024} MB 上限：${path}（${(info.size / 1024 / 1024).toFixed(1)} MB）`);
+    const limit = options.maxBase64Bytes ?? DEFAULT_IMAGE_BASE64_LIMIT;
+    if (info.size > MAX_IMAGE_FILE_BYTES)
+        throw new AmaError("invalid_arguments", `图片超过 ${formatMb(limit)} 上限（按 base64 后计算）：${path}（${formatMb(base64Size(info.size))}）`);
     const buf = await readFile(path);
     const mimeType = sniffImageMime(buf) ?? imageMimeFromPath(path);
     if (mimeType === undefined)
         throw new AmaError("invalid_arguments", `不是支持的图片（PNG / JPEG / GIF / WebP）：${path}`);
-    const size = imageSize(buf, mimeType);
+    const fit = await fitImage(buf, mimeType, options, path);
+    if (!fit.ok)
+        throw fitError(path, fit, limit, buf.length, options.resize === "off");
     return {
-        block: { type: "image", data: buf.toString("base64"), mimeType },
+        block: { type: "image", data: fit.buf.toString("base64"), mimeType: fit.mimeType },
         path,
-        mimeType,
-        bytes: buf.length,
-        ...(size ? { size } : {}),
+        mimeType: fit.mimeType,
+        bytes: fit.buf.length,
+        ...(fit.size ? { size: fit.size } : {}),
     };
 }

package/dist/tools/image-resize.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 可选的图片缩放（docs/wave5-plan.md §4、D12）。[W5-I]
+ *
+ * 零依赖不能解码像素，只能调系统工具：macOS 依次试 `sips`、`magick`、`convert`；Linux 试
+ * `magick`、`convert`；Windows 只试 `magick`（`convert.exe` 是系统的磁盘转换工具）。都没有就返回
+ * `no_tool`，调用方按原规则拒绝并提示。只在超限时调用（`images.resize: "auto"`，缺省）。
+ *
+ * 输出写临时目录，读回后删掉；JPEG 保持 JPEG，其余格式输出 PNG（GIF 取第一帧）。边长先取
+ * min(目标边长, 原长边)，体积仍超限就按 0.7 逐次缩小，最多 5 次。
+ */
+import { type ImageSize } from "./image-file.js";
+export interface CommandResult {
+    /** 进程退出码；命令不存在 / 无法启动为 null。 */
+    code: number | null;
+    stdout: Buffer;
+    stderr: string;
+    /** 命令不存在（ENOENT）。 */
+    missing?: boolean;
+}
+export type RunCommand = (command: string, args: readonly string[], options?: {
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+}) => Promise<CommandResult>;
+/** 缺省的命令执行器：execFile，stdout 按 Buffer 收，30 s 超时。 */
+export declare const runCommand: RunCommand;
+export interface ResizeTarget {
+    /** 长边上限（像素）。 */
+    maxEdge: number;
+    /** base64 后的体积上限（字节）。 */
+    maxBase64Bytes: number;
+    mimeType: string;
+    /** 原图尺寸（已知时用来定起始边长）。 */
+    size?: ImageSize | undefined;
+}
+export interface ResizeDeps {
+    platform?: NodeJS.Platform;
+    run?: RunCommand;
+    /** 临时目录的父目录；缺省 os.tmpdir()。 */
+    tmpDir?: string;
+}
+export interface ResizedImage {
+    ok: true;
+    buf: Buffer;
+    mimeType: string;
+    size?: ImageSize;
+    /** 用到的工具（`sips` / `magick` / `convert`）。 */
+    tool: string;
+}
+export interface ResizeFailure {
+    ok: false;
+    reason: "no_tool" | "failed";
+}
+/** 按平台的候选工具，靠前的先试。 */
+export declare function resizeTools(platform: NodeJS.Platform): string[];
+/**
+ * 把 `input` 缩到目标以内。`no_tool`：一个可用工具都没有；`failed`：工具能用但缩不到目标。
+ */
+export declare function resizeImage(input: string, target: ResizeTarget, deps?: ResizeDeps): Promise<ResizedImage | ResizeFailure>;

package/dist/tools/image-resize.js

@@ -0,0 +1,97 @@
+/**
+ * 可选的图片缩放（docs/wave5-plan.md §4、D12）。[W5-I]
+ *
+ * 零依赖不能解码像素，只能调系统工具：macOS 依次试 `sips`、`magick`、`convert`；Linux 试
+ * `magick`、`convert`；Windows 只试 `magick`（`convert.exe` 是系统的磁盘转换工具）。都没有就返回
+ * `no_tool`，调用方按原规则拒绝并提示。只在超限时调用（`images.resize: "auto"`，缺省）。
+ *
+ * 输出写临时目录，读回后删掉；JPEG 保持 JPEG，其余格式输出 PNG（GIF 取第一帧）。边长先取
+ * min(目标边长, 原长边)，体积仍超限就按 0.7 逐次缩小，最多 5 次。
+ */
+import { execFile } from "node:child_process";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { base64Size } from "../ai/image-limits.js";
+import { imageSize } from "./image-file.js";
+/** 缺省的命令执行器：execFile，stdout 按 Buffer 收，30 s 超时。 */
+export const runCommand = (command, args, options = {}) => new Promise((resolvePromise) => {
+    execFile(command, [...args], {
+        encoding: "buffer",
+        maxBuffer: 128 * 1024 * 1024,
+        timeout: options.timeoutMs ?? 30_000,
+        windowsHide: true,
+        ...(options.env !== undefined ? { env: options.env } : {}),
+    }, (error, stdout, stderr) => {
+        const err = error;
+        const missing = err !== null && err.code === "ENOENT";
+        const code = err === null ? 0 : typeof err.code === "number" ? err.code : missing ? null : 1;
+        resolvePromise({
+            code,
+            stdout: Buffer.isBuffer(stdout) ? stdout : Buffer.alloc(0),
+            stderr: Buffer.isBuffer(stderr) ? stderr.toString("utf8") : String(stderr ?? ""),
+            ...(missing ? { missing: true } : {}),
+        });
+    });
+});
+const MAX_ATTEMPTS = 5;
+const SHRINK = 0.7;
+const MIN_EDGE = 64;
+/** 按平台的候选工具，靠前的先试。 */
+export function resizeTools(platform) {
+    if (platform === "darwin")
+        return ["sips", "magick", "convert"];
+    if (platform === "win32")
+        return ["magick"];
+    return ["magick", "convert"];
+}
+function resizeArgs(tool, input, output, edge, format) {
+    if (tool === "sips")
+        return ["-Z", String(edge), "-s", "format", format, input, "--out", output];
+    // ImageMagick：`[0]` 取第一帧，`>` 只缩小不放大
+    return [`${input}[0]`, "-resize", `${edge}x${edge}>`, output];
+}
+/**
+ * 把 `input` 缩到目标以内。`no_tool`：一个可用工具都没有；`failed`：工具能用但缩不到目标。
+ */
+export async function resizeImage(input, target, deps = {}) {
+    const run = deps.run ?? runCommand;
+    const format = target.mimeType === "image/jpeg" ? "jpeg" : "png";
+    const mimeType = format === "jpeg" ? "image/jpeg" : "image/png";
+    const long = target.size !== undefined ? Math.max(target.size.width, target.size.height) : 0;
+    const start = long > 0 ? Math.min(target.maxEdge, long) : target.maxEdge;
+    const dir = await mkdtemp(join(deps.tmpDir ?? tmpdir(), "ama-resize-"));
+    try {
+        for (const tool of resizeTools(deps.platform ?? process.platform)) {
+            let edge = start;
+            let worked = false;
+            for (let attempt = 0; attempt < MAX_ATTEMPTS && edge >= MIN_EDGE; attempt++) {
+                const output = join(dir, `out-${attempt}.${format === "jpeg" ? "jpg" : "png"}`);
+                const result = await run(tool, resizeArgs(tool, input, output, edge, format));
+                if (result.missing === true || result.code !== 0)
+                    break;
+                let buf;
+                try {
+                    buf = await readFile(output);
+                }
+                catch {
+                    break;
+                }
+                worked = true;
+                const size = imageSize(buf, mimeType);
+                const longOut = size !== undefined ? Math.max(size.width, size.height) : 0;
+                if (base64Size(buf.length) <= target.maxBase64Bytes && longOut <= target.maxEdge) {
+                    return { ok: true, buf, mimeType, tool, ...(size !== undefined ? { size } : {}) };
+                }
+                edge = Math.round(Math.min(edge, longOut > 0 ? longOut : edge) * SHRINK);
+            }
+            // 工具能用但缩不到目标：换工具也不会更好
+            if (worked)
+                return { ok: false, reason: "failed" };
+        }
+        return { ok: false, reason: "no_tool" };
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true }).catch(() => undefined);
+    }
+}

package/dist/tools/presets.d.ts

@@ -5,27 +5,57 @@
  * | ------------- | ----------------------------------------- |
  * | `default`     | read、edit、write、bash、grep、glob       |
  * | `minimal`     | read、edit、write、bash                   |
- * | `codemode`    | 只有 codemode（其余工具在脚本里调用）     |
+ * | `codemode-only` | 只有 codemode（其余工具在脚本里调用）   |
  * | `coordinator` | read + 宿主注册的工具                     |
  *
  * - 预设只管**内置**工具；宿主 / SDK 注册的工具（`canvas_*` 等）总在活动集里，除非用户
  *   `--tools a,b,c` 整组替换（之后只用列出的名字）。
  * - `tools.default`：`+name` / `-name` 在预设上增减；不带前缀的名字整组替换预设的内置工具，
  *   之后再应用带前缀的项。未注册的名字记 warning 并忽略。
- * - codemode 开关跟随预设：`codemode` 预设 → `only`，其余 → `off`；`codemode.mode` 显式配置覆盖。
- * - codemode 工具由 B10 经组装根的 `toolFactories` 注册（`codemode.mode` 为 off 时不注册）；不可用
- *   （例如 `codemode.requireStrict` 而运行时 Node 不隔离网络）时 codemode 预设**回退到 default 并
- *   warning**（不报错：零配置用户不应因此起不来），`on` 同样忽略。
+ * - （D20）`todo` 不在 `default` 里：W5-C0 曾把它加进来，以 `bench-presets` 复测为门（费用增幅 ≤ 5% 且
+ *   成功率不降）；W5-Z 用多步长任务复测（docs/benchmarks/presets-todo-2026-10-03.md）成功数下降 1、估价
+ *   +4.6%、保守计价 +11.3%，按门撤回。计划批准后的进度改用 `[DONE:n]` 文本标记（plan/done-markers.ts）；
+ *   要 todo 就 `tools.default: ["+todo"]`。
+ * - （W5-C0）`task_ctl` 与 `task` 同进退：`+task` 一起暴露、`-task` 一起去掉（`pairCompanions`）。
+ * - `codemode` 是 `codemode-only` 的旧名（0.3.0），配置合并与命令行解析时折成规范名。
+ * - codemode 开关跟随预设（`presetCodemodeMode`）：`default` → `on`（只在沙箱 strict，即 Node ≥ 25 隔离
+ *   网络时；Node 22 / 24 → `off`），`codemode-only` → `only`，`minimal` / `coordinator` → `off`。
+ *   `codemode.mode` 显式配置覆盖（缺省配置不写这个键，以后调整映射能惠及老用户）。
+ * - `coordinator` 预设即使显式 `on`，脚本里能调用的工具也只限活动集（read + 宿主工具），见
+ *   `codemodeCallableFilter`：协调者「不写文件、不跑 bash」的约定不能经 codemode 绕过。
+ * - codemode 工具由 B10 经组装根的 `toolFactories` 注册（生效模式为 off 时不注册）；不可用
+ *   （例如 `codemode.requireStrict` 而运行时 Node 不隔离网络）时 codemode-only 预设**回退到 default 并
+ *   warning**（不报错：零配置用户不应因此起不来），显式 `on` 同样忽略；跟随预设得到的 `on` 静默回退。
  * - `only` 模式活动集独占：宿主 / SDK 工具也不直接暴露，只能在脚本里调用（`exclusive`）。
  */
-import type { AmaConfig, CodemodeMode, ToolsPreset } from "../config/types.js";
+import { type AmaConfig, type CodemodeMode, type ToolsPreset } from "../config/types.js";
 import { ToolRegistry } from "./registry.js";
 import type { ToolDefinition, ToolSource } from "./types.js";
 export declare const CODEMODE_TOOL = "codemode";
-/** 各预设下模型直接看到的内置工具（codemode 预设见 `resolvePreset`）。 */
+/** 各预设下模型直接看到的内置工具（codemode-only 预设见 `resolvePreset`）。 */
 export declare const PRESET_TOOLS: Readonly<Record<ToolsPreset, readonly string[]>>;
+/**
+ * 预设对应的 codemode 模式（没有显式 `codemode.mode` 时）。`default` 只在沙箱 strict（Node ≥ 25，
+ * 权限模型同时隔离网络）时开 `on`：Node 22 / 24 下 codemode 属 execute 类，每次都要审批，`-p` 下
+ * 直接被拒，所以缺省关闭（启动时提示一次，见 cli/codemode-notice.ts）。
+ */
+export declare function presetCodemodeMode(preset: ToolsPreset, strict: boolean): CodemodeMode;
+export interface CodemodeModeResolution {
+    mode: CodemodeMode;
+    /** `config`：显式 `codemode.mode`；`preset`：跟随预设。 */
+    source: "config" | "preset";
+    preset: ToolsPreset;
+    strict: boolean;
+}
+/** 生效的 codemode 模式及其来源；`strict` 缺省按运行时探测（测试与组装根可注入）。 */
+export declare function resolveCodemodeMode(config: Pick<AmaConfig, "tools" | "codemode" | "sandbox">, strict?: boolean): CodemodeModeResolution;
 /** 生效的 codemode 模式：显式配置优先，否则跟随预设。 */
-export declare function effectiveCodemodeMode(config: Pick<AmaConfig, "tools" | "codemode">): CodemodeMode;
+export declare function effectiveCodemodeMode(config: Pick<AmaConfig, "tools" | "codemode" | "sandbox">, strict?: boolean): CodemodeMode;
+/**
+ * codemode 脚本里可调用工具的范围：`coordinator` 预设只能调活动集里的工具（`"active"`），其它预设
+ * 不限（`undefined`；`on` 模式下脚本还能调没直接暴露的 ls / task / todo 等）。
+ */
+export declare function codemodeCallableFilter(config: Pick<AmaConfig, "tools">): "active" | undefined;
 /**
  * `tools.default` 微调：不带前缀的名字整组替换 `base`，再依次应用 `+name` / `-name`。
  * 返回去重后的名字（保持首次出现顺序）。
@@ -43,6 +73,8 @@ export declare function resolvePreset(input: {
     config: Pick<AmaConfig, "tools" | "codemode">;
     /** 该名字是否已注册（且未禁用）。 */
     available(name: string): boolean;
+    /** 沙箱是否 strict；缺省按运行时探测。 */
+    strict?: boolean;
 }): PresetResolution;
 type RegisterListener = (tool: ToolDefinition, source: ToolSource) => void;
 /**