@armadra/agent 0.4.0 → 0.5.1

package/dist/tools/bash.js

@@ -7,6 +7,12 @@
  * - 结构化结果 `{ output, exit_code, truncated, full_output_path?, wall_time_seconds }`；
  *   信号退出 `128 + signo`；非零退出码 → isError；
  * - 注入 `AMA_*` 环境变量（shell.ts）。shell 退出后不等仍占着管道的后台进程。
+ * - [W5-H2] 后台命令（§8.3 H6，不加新工具）：`{ command, background: true }` 立即返回
+ *   `{ jobId, outputPath, pid }`；`{ job, action: "wait" | "output" | "stop" }` 查询 / 结束
+ *   （background-jobs.ts，按会话登记，会话 dispose 时回收进程树；退出经提醒通道通知）。
+ * - **进程只在 `spawnShell` 里创建**（前台与后台共用）。[S2] `sandbox.bash: auto` 且有能限制写入的
+ *   OS 沙箱时在这一处包一层（src/sandbox/bash.ts）；`sandbox: false` 不包装（权限管线照常审批）。
+ *   失败输出像是被沙箱拒绝时末尾追加一行说明。
  */
 import { spawn } from "node:child_process";
 import { stat } from "node:fs/promises";
@@ -16,11 +22,32 @@ import { buildShellArgs, buildToolEnv, resolveShell } from "./shell.js";
 import { exitCodeOf, isGroupAlive, killProcessTree, trackProcessGroup, untrackProcessGroup, } from "./process-tree.js";
 import { OutputAccumulator } from "./output-accumulator.js";
 import { formatSize, resolveOutputDir, safeFileName } from "./truncate.js";
+import { jobsForSession } from "./background-jobs.js";
+import { looksLikeSandboxDenial, runsSandboxed, sandboxDenialHint, wrapBashCommand, } from "../sandbox/bash.js";
 export const DEFAULT_BASH_TIMEOUT_MS = 120_000;
 export const MAX_BASH_TIMEOUT_MS = 600_000;
 const UPDATE_THROTTLE_MS = 100;
 /** shell 退出后等管道关闭的上限（后台子进程可能一直占着）。 */
 const STDIO_DRAIN_MS = 200;
+/** [W5-H2] `wait` 的缺省等待（毫秒）。 */
+export const DEFAULT_JOB_WAIT_MS = 30_000;
+/**
+ * bash 工具唯一的进程创建点（前台 / 后台共用）；[S2] 给了 `sandbox` 时经 OS 沙箱包装（包不上抛错，
+ * 不悄悄裸跑）。
+ */
+export function spawnShell(shell, command, options) {
+    const args = buildShellArgs(shell, command);
+    const wrapped = options.sandbox === undefined
+        ? { command: shell.shell, args }
+        : wrapBashCommand(options.sandbox.settings, shell.shell, args, options.sandbox.place);
+    return spawn(wrapped.command, wrapped.args, {
+        cwd: options.cwd,
+        env: options.env,
+        detached: options.detached,
+        stdio: options.stdio,
+        windowsHide: true,
+    });
+}
 function fail(message) {
     return { content: message, isError: true };
 }
@@ -56,9 +83,14 @@ function waitForExit(child) {
     });
 }
 export async function executeBash(input, ctx, options = {}) {
+    if (input.job !== undefined)
+        return jobAction(input, ctx, options);
+    if (input.action !== undefined)
+        return fail("action needs job (a background job id)");
     if (typeof input.command !== "string" || input.command.trim() === "") {
         return fail("command must be a non-empty string");
     }
+    const command = input.command;
     const timeoutMs = input.timeoutMs ?? options.defaultTimeoutMs ?? DEFAULT_BASH_TIMEOUT_MS;
     if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > MAX_BASH_TIMEOUT_MS) {
         return fail(`timeoutMs must be between 1 and ${MAX_BASH_TIMEOUT_MS}`);
@@ -83,18 +115,29 @@ export async function executeBash(input, ctx, options = {}) {
         depth: ctx.depth,
     });
     const isWindows = (options.processDeps?.platform ?? process.platform) === "win32";
+    const sandbox = options.sandbox !== undefined && runsSandboxed(options.sandbox, input)
+        ? {
+            settings: options.sandbox,
+            place: {
+                workspace: ctx.cwd,
+                outputDir: resolveOutputDir(ctx.outputDir),
+            },
+        }
+        : undefined;
+    if (input.background === true)
+        return startBackground(command, { cwd, env, shell, isWindows, sandbox }, ctx, options);
     const started = Date.now();
     const acc = new OutputAccumulator({
         spillPath: () => join(resolveOutputDir(ctx.outputDir), safeFileName(`bash-${ctx.toolCallId}.log`)),
     });
     let child;
     try {
-        child = spawn(shell.shell, buildShellArgs(shell, input.command), {
+        child = spawnShell(shell, command, {
             cwd,
             env,
             detached: !isWindows,
             stdio: ["ignore", "pipe", "pipe"],
-            windowsHide: true,
+            ...(sandbox === undefined ? {} : { sandbox }),
         });
     }
     catch (err) {
@@ -165,6 +208,7 @@ export async function executeBash(input, ctx, options = {}) {
         truncated: out.truncated,
         ...(out.fullOutputPath !== undefined ? { full_output_path: out.fullOutputPath } : {}),
         wall_time_seconds: wall,
+        ...(sandbox === undefined ? {} : { sandboxed: true }),
     };
     const details = {
         ...structured,
@@ -188,6 +232,10 @@ export async function executeBash(input, ctx, options = {}) {
         parts.push(`[Command timed out after ${timeoutMs} ms and was killed]`);
     if (exitCode !== 0)
         parts.push(`[exit code: ${exitCode}]`);
+    const networkDenied = sandbox?.settings.network === "deny";
+    if (sandbox !== undefined && exitCode !== 0 && !aborted && !timedOut)
+        if (looksLikeSandboxDenial(out.output, networkDenied))
+            parts.push(sandboxDenialHint(networkDenied));
     return {
         content: parts.join("\n\n"),
         isError: exitCode !== 0 || timedOut || aborted,
@@ -195,22 +243,125 @@ export async function executeBash(input, ctx, options = {}) {
         details,
     };
 }
+// ---------------------------------------------------------------------------
+// [W5-H2] 后台命令
+// ---------------------------------------------------------------------------
+function jobsOf(ctx, options) {
+    return options.jobs ? options.jobs(ctx.sessionId) : jobsForSession(ctx.sessionId);
+}
+function startBackground(command, spawnInfo, ctx, options) {
+    const { cwd, env, shell, isWindows, sandbox } = spawnInfo;
+    const outputPath = join(resolveOutputDir(ctx.outputDir), safeFileName(`bash-bg-${ctx.toolCallId}.log`));
+    let job;
+    try {
+        job = jobsOf(ctx, options).start(command, {
+            cwd,
+            outputPath,
+            ...(options.processDeps === undefined ? {} : { processDeps: options.processDeps }),
+            spawn: (fd) => spawnShell(shell, command, {
+                cwd,
+                env,
+                detached: !isWindows,
+                stdio: ["ignore", fd, fd],
+                ...(sandbox === undefined ? {} : { sandbox }),
+            }),
+        });
+    }
+    catch (err) {
+        return fail(`Failed to start shell ${shell.shell}: ${err.message}`);
+    }
+    const structured = { jobId: job.id, outputPath: job.outputPath };
+    if (job.pid !== undefined)
+        structured.pid = job.pid;
+    if (sandbox !== undefined)
+        structured.sandboxed = true;
+    return {
+        content: `Started background job ${job.id}${job.pid !== undefined ? ` (pid ${job.pid})` : ""}; ` +
+            `output: ${job.outputPath}. Check it with bash {"job":"${job.id}","action":"wait"|"output"|"stop"}; ` +
+            "you will be told when it exits.",
+        structured,
+        details: { ...structured, background: true, command, cwd },
+    };
+}
+function jobStatusLine(job) {
+    const state = job.status === "running"
+        ? "still running"
+        : job.status === "stopped"
+            ? `stopped (exit code ${job.exitCode ?? "?"})`
+            : `exited with code ${job.exitCode ?? "?"}`;
+    return `[job ${job.id} ${state}; output: ${job.outputPath}]`;
+}
+async function jobAction(input, ctx, options) {
+    const id = input.job;
+    if (input.command !== undefined || input.background === true || input.sandbox !== undefined)
+        return fail("job queries take only job, action and timeoutMs");
+    const action = input.action ?? "output";
+    const jobs = jobsOf(ctx, options);
+    if (jobs.get(id) === undefined) {
+        const known = jobs.list().map((job) => job.id);
+        return fail(`Unknown background job ${id}${known.length > 0 ? ` (jobs: ${known.join(", ")})` : ""}`);
+    }
+    if (action === "stop") {
+        const job = (await jobs.stop(id));
+        const out = jobs.output(id);
+        const text = out?.content ?? "";
+        return {
+            content: `${text === "" ? "(no output)" : text}\n\n${jobStatusLine(job)}`,
+            structured: { jobId: id, status: job.status, exit_code: job.exitCode ?? null },
+        };
+    }
+    if (action === "wait") {
+        const waitMs = input.timeoutMs ?? DEFAULT_JOB_WAIT_MS;
+        if (!Number.isFinite(waitMs) || waitMs <= 0 || waitMs > MAX_BASH_TIMEOUT_MS)
+            return fail(`timeoutMs must be between 1 and ${MAX_BASH_TIMEOUT_MS}`);
+        await jobs.wait(id, waitMs, ctx.signal);
+    }
+    const out = jobs.output(id);
+    if (out === undefined)
+        return fail(`Unknown background job ${id}`);
+    const job = out.job;
+    if (job.status !== "running")
+        jobs.markSeen(id);
+    const parts = [out.content === "" ? "(no output)" : out.content];
+    if (out.truncated)
+        parts.push(`[Output truncated: showing the last ${out.outputLines} of ${out.totalLines} lines ` +
+            `(${formatSize(out.totalBytes)} total). Full output: ${job.outputPath}]`);
+    parts.push(jobStatusLine(job));
+    return {
+        content: parts.join("\n\n"),
+        isError: job.status === "exited" && job.exitCode !== 0,
+        structured: { jobId: id, status: job.status, exit_code: job.exitCode ?? null },
+    };
+}
+/** [S2] 沙箱生效时追加到描述末尾的一句（会话内不变）。 */
+export function sandboxDescription(sandbox) {
+    if (sandbox?.active !== true)
+        return "";
+    const net = sandbox.network === "deny" ? ", no network" : "";
+    return ` Runs in an OS sandbox (writes only in workspace/temp${net}); sandbox:false needs approval.`;
+}
 export function createBashTool(options = {}) {
+    const sandboxed = options.sandbox?.active === true;
     return {
         name: "bash",
         label: "Bash",
-        description: "Run a shell command. stdout+stderr combined; over 2000 lines or 50 KB keeps the tail " +
-            "and saves the full output to a file. " +
-            `Timeout default ${DEFAULT_BASH_TIMEOUT_MS} ms, max ${MAX_BASH_TIMEOUT_MS} ms.`,
+        description: "Run a shell command; stdout+stderr combined, keeps the last 2000 lines / 50 KB (full " +
+            `output saved). Timeout ${DEFAULT_BASH_TIMEOUT_MS / 1000} s, max ${MAX_BASH_TIMEOUT_MS / 1000} s. ` +
+            "background:true gives a job id for {job, action}." +
+            sandboxDescription(options.sandbox),
         parameters: {
             type: "object",
             properties: {
                 command: { type: "string" },
                 timeoutMs: { type: "integer" },
                 cwd: { type: "string", description: "Default: session cwd" },
-                description: { type: "string", description: "What this does, briefly" },
+                description: { type: "string" },
+                background: { type: "boolean" },
+                job: { type: "string" },
+                action: { type: "string", enum: ["wait", "output", "stop"] },
+                // [S2] 只在沙箱生效时出现：沙箱关闭的会话工具 schema 与以前逐字节相同
+                ...(sandboxed ? { sandbox: { type: "boolean" } } : {}),
             },
-            required: ["command"],
             additionalProperties: false,
         },
         permission: "execute",

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

@@ -0,0 +1,44 @@
+/**
+ * 剪贴板图片（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 { type RunCommand } from "./image-resize.js";
+export declare const CLIPBOARD_DIR = "clipboard";
+export declare const CLIPBOARD_MAX_AGE_DAYS = 7;
+export interface ClipboardDeps {
+    platform?: NodeJS.Platform;
+    run?: RunCommand;
+    env?: NodeJS.ProcessEnv;
+    now?(): number;
+}
+export type ClipboardResult = {
+    ok: true;
+    path: string;
+    tool: string;
+}
+/** `no_tool`：一个可用命令都没有；`no_image`：命令能用但剪贴板里没有图。 */
+ | {
+    ok: false;
+    reason: "no_tool" | "no_image";
+};
+/** 读剪贴板图片到数据目录；返回结果与原因（界面据此给一行提示）。 */
+export declare function readClipboardImage(dataDir: string, deps?: ClipboardDeps): Promise<ClipboardResult>;
+/** §10.2 的签名：成功返回 PNG 路径，没有工具或没有图返回 undefined。 */
+export declare function pasteClipboardImage(dataDir: string, deps?: ClipboardDeps): Promise<string | undefined>;
+/** 清理 `<dataDir>/clipboard/` 里超过 `maxAgeDays`（缺省 7）天的文件；返回（将）删除的路径。 */
+export declare function gcClipboardImages(dataDir: string, options?: {
+    dryRun?: boolean;
+    maxAgeDays?: number;
+    now?: number;
+}): Promise<string[]>;

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 } : {}),
     };
 }