@armadra/agent 0.3.0 → 0.5.0

package/dist/tools/background-jobs.js

@@ -0,0 +1,198 @@
+/**
+ * 后台命令（docs/wave5-plan.md §8.3 H6，D29：不加新工具，`bash{background}` + `bash{job, action}`）。[W5-H2]
+ *
+ * - `start`：调用方（bash.ts）给出 `spawn(stdout)`——**进程只在 bash.ts 的 `spawnShell` 里创建**，
+ *   这里只拿到 ChildProcess；stdout / stderr 直接写进 `outputPath`（文件描述符交给子进程，ama 退出也不
+ *   会因管道断开而 SIGPIPE）。POSIX 自成进程组并登记（进程退出时同步 SIGKILL 残留组）。
+ * - `wait(id, timeoutMs)`：等到退出或超时；`stop(id)`：杀整棵树（SIGTERM → 宽限 → SIGKILL）；
+ *   `output(id)`：读输出文件尾部（2000 行 / 50 KB）。
+ * - 生命周期事件经 `onChange` 发出（started / exited / stopped）；`takeExited()` 取走尚未通知的已退出
+ *   任务（提醒通道 reminders.ts 据此告诉模型「后台命令 jobId 已退出（码 N）」）。
+ * - 按会话 id 登记（`jobsForSession`）；`disposeSessionJobs` 在会话 dispose 时回收进程树。
+ */
+import { closeSync, mkdirSync, openSync, readFileSync, statSync } from "node:fs";
+import { dirname } from "node:path";
+import { exitCodeOf, isGroupAlive, killProcessTree, trackProcessGroup, untrackProcessGroup, } from "./process-tree.js";
+import { truncateTail } from "./truncate.js";
+/** 后台 bash 的查询形状：`{ job, action: wait | stop | output }`，不带 command。 */
+export function isBackgroundJobQuery(toolName, input) {
+    if (toolName !== "bash" || typeof input !== "object" || input === null)
+        return false;
+    const record = input;
+    return typeof record.job === "string" && record.command === undefined;
+}
+export class BackgroundJobs {
+    entries = new Map();
+    listeners = new Set();
+    seq = 0;
+    start(command, options) {
+        mkdirSync(dirname(options.outputPath), { recursive: true });
+        const fd = openSync(options.outputPath, "a");
+        let child;
+        try {
+            child = options.spawn(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        const id = `bg${++this.seq}`;
+        const job = {
+            id,
+            command,
+            cwd: options.cwd,
+            outputPath: options.outputPath,
+            startedAt: Date.now(),
+            status: "running",
+        };
+        if (child.pid !== undefined)
+            job.pid = child.pid;
+        const isWindows = (options.processDeps?.platform ?? process.platform) === "win32";
+        if (job.pid !== undefined && !isWindows)
+            trackProcessGroup(job.pid);
+        const entry = {
+            job,
+            notified: false,
+            stopping: false,
+            processDeps: options.processDeps,
+            done: new Promise((resolve) => {
+                const finish = (code, signal) => {
+                    if (job.status !== "running")
+                        return resolve();
+                    job.exitCode = exitCodeOf(code, signal);
+                    job.endedAt = Date.now();
+                    job.status = entry.stopping ? "stopped" : "exited";
+                    const pid = job.pid;
+                    if (pid !== undefined && !isWindows && !isGroupAlive(pid, options.processDeps ?? {}))
+                        untrackProcessGroup(pid);
+                    this.notify({ phase: job.status === "stopped" ? "stopped" : "exited", job });
+                    resolve();
+                };
+                child.once("exit", finish);
+                child.once("error", () => finish(127, null));
+            }),
+        };
+        child.unref();
+        this.entries.set(id, entry);
+        this.notify({ phase: "started", job });
+        return job;
+    }
+    get(id) {
+        return this.entries.get(id)?.job;
+    }
+    list() {
+        return [...this.entries.values()].map((entry) => entry.job);
+    }
+    /** 等到退出或超时（`signal` 可提前结束等待，不杀进程）。 */
+    async wait(id, timeoutMs, signal) {
+        const entry = this.entries.get(id);
+        if (entry === undefined)
+            return undefined;
+        if (entry.job.status !== "running")
+            return entry.job;
+        let timer;
+        let onAbort;
+        await Promise.race([
+            entry.done,
+            new Promise((resolve) => {
+                timer = setTimeout(resolve, Math.max(0, timeoutMs));
+                onAbort = () => resolve();
+                signal?.addEventListener("abort", onAbort, { once: true });
+            }),
+        ]);
+        if (timer !== undefined)
+            clearTimeout(timer);
+        if (onAbort !== undefined)
+            signal?.removeEventListener("abort", onAbort);
+        return entry.job;
+    }
+    async stop(id) {
+        const entry = this.entries.get(id);
+        if (entry === undefined)
+            return undefined;
+        if (entry.job.status !== "running")
+            return entry.job;
+        entry.stopping = true;
+        // 已经由调用方知道结果：停止的任务不再经提醒通道通知
+        entry.notified = true;
+        if (entry.job.pid !== undefined)
+            await killProcessTree(entry.job.pid, entry.processDeps);
+        await entry.done;
+        return entry.job;
+    }
+    /** 输出文件尾部（2000 行 / 50 KB）。 */
+    output(id) {
+        const entry = this.entries.get(id);
+        if (entry === undefined)
+            return undefined;
+        let text = "";
+        try {
+            if (statSync(entry.job.outputPath).size > 0)
+                text = readFileSync(entry.job.outputPath, "utf8");
+        }
+        catch {
+            // 输出文件被删：按空输出
+        }
+        return { ...truncateTail(text), job: entry.job };
+    }
+    /** 取走已退出、尚未通知的任务（提醒通道用；wait 已看到退出的也算已知）。 */
+    takeExited() {
+        const out = [];
+        for (const entry of this.entries.values()) {
+            if (entry.job.status === "running" || entry.notified)
+                continue;
+            entry.notified = true;
+            out.push(entry.job);
+        }
+        return out;
+    }
+    /** 标记为已知（模型已经通过 wait / output 看到了退出）。 */
+    markSeen(id) {
+        const entry = this.entries.get(id);
+        if (entry !== undefined && entry.job.status !== "running")
+            entry.notified = true;
+    }
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    get running() {
+        return this.list().filter((job) => job.status === "running").length;
+    }
+    /** 杀掉全部仍在运行的任务（会话 dispose）。 */
+    async disposeAll() {
+        await Promise.all([...this.entries.keys()].map((id) => this.stop(id).catch(() => undefined)));
+        this.listeners.clear();
+    }
+    notify(change) {
+        for (const listener of this.listeners) {
+            try {
+                listener(change);
+            }
+            catch {
+                // 监听器异常不影响任务
+            }
+        }
+    }
+}
+const registry = new Map();
+/** 会话的后台任务表（按会话 id，首次使用时建）。 */
+export function jobsForSession(sessionId) {
+    let jobs = registry.get(sessionId);
+    if (jobs === undefined) {
+        jobs = new BackgroundJobs();
+        registry.set(sessionId, jobs);
+    }
+    return jobs;
+}
+/** 已有的任务表（不新建）。 */
+export function existingJobs(sessionId) {
+    return registry.get(sessionId);
+}
+/** 会话 dispose：杀掉该会话仍在运行的后台任务并注销。 */
+export async function disposeSessionJobs(sessionId) {
+    const jobs = registry.get(sessionId);
+    if (jobs === undefined)
+        return;
+    registry.delete(sessionId);
+    await jobs.disposeAll();
+}

package/dist/tools/bash.d.ts

@@ -7,17 +7,43 @@
  * - 结构化结果 `{ 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 { type ChildProcess } from "node:child_process";
 import type { ToolContext, ToolDefinition, ToolResult } from "./types.js";
 import { type ShellConfig } from "./shell.js";
 import { type ProcessDeps } from "./process-tree.js";
+import { type BackgroundJobs } from "./background-jobs.js";
+import { type BashCallPlace, type BashSandbox } from "../sandbox/bash.js";
 export declare const DEFAULT_BASH_TIMEOUT_MS = 120000;
 export declare const MAX_BASH_TIMEOUT_MS = 600000;
 export interface BashInput {
-    command: string;
+    /** 前台 / 后台命令；查询后台任务时不给。 */
+    command?: string;
     timeoutMs?: number;
     cwd?: string;
     description?: string;
+    /** [W5-H2] 后台运行：立即返回 jobId。 */
+    background?: boolean;
+    /** [W5-H2] 后台任务 id（与 action 一起用）。 */
+    job?: string;
+    action?: "wait" | "output" | "stop";
+    /** [S2] false：不经 OS 沙箱运行（走正常审批）。只在沙箱生效时出现在 schema 里。 */
+    sandbox?: boolean;
+}
+/** [W5-H2] `wait` 的缺省等待（毫秒）。 */
+export declare const DEFAULT_JOB_WAIT_MS = 30000;
+export interface BackgroundStart {
+    jobId: string;
+    outputPath: string;
+    pid?: number;
+    /** [S2] 经 OS 沙箱运行。 */
+    sandboxed?: true;
 }
 export interface BashStructured {
     output: string;
@@ -25,6 +51,8 @@ export interface BashStructured {
     truncated: boolean;
     full_output_path?: string;
     wall_time_seconds: number;
+    /** [S2] 经 OS 沙箱运行。 */
+    sandboxed?: true;
 }
 export interface BashDetails extends BashStructured {
     timedOut: boolean;
@@ -44,6 +72,30 @@ export interface BashToolOptions {
     processDeps?: ProcessDeps;
     /** 测试注入：基础环境，缺省 process.env。 */
     baseEnv?(): NodeJS.ProcessEnv;
+    /** 测试注入：会话的后台任务表，缺省按会话 id 登记（background-jobs.ts）。 */
+    jobs?(sessionId: string): BackgroundJobs;
+    /** [S2] bash 的 OS 沙箱设定（组装时算一次，会话内不变）；缺省不用沙箱。 */
+    sandbox?: BashSandbox;
+}
+export interface SpawnShellOptions {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    /** POSIX 自成进程组（杀树用）；Windows 为 false。 */
+    detached: boolean;
+    /** 前台 `["ignore", "pipe", "pipe"]`；后台把输出文件描述符直接交给子进程。 */
+    stdio: ["ignore", "pipe" | number, "pipe" | number];
+    /** [S2] 经 OS 沙箱运行：设定与这次调用的位置（工作区、输出目录）。 */
+    sandbox?: {
+        settings: BashSandbox;
+        place: BashCallPlace;
+    };
 }
+/**
+ * bash 工具唯一的进程创建点（前台 / 后台共用）；[S2] 给了 `sandbox` 时经 OS 沙箱包装（包不上抛错，
+ * 不悄悄裸跑）。
+ */
+export declare function spawnShell(shell: ShellConfig, command: string, options: SpawnShellOptions): ChildProcess;
 export declare function executeBash(input: BashInput, ctx: ToolContext, options?: BashToolOptions): Promise<ToolResult>;
+/** [S2] 沙箱生效时追加到描述末尾的一句（会话内不变）。 */
+export declare function sandboxDescription(sandbox: BashSandbox | undefined): string;
 export declare function createBashTool(options?: BashToolOptions): ToolDefinition<BashInput>;

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[]>;