@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.1

package/dist/tools/builtins/sandbox/bash.js

@@ -0,0 +1,137 @@
+import { ToolError } from "@capybara-hq/plugin-sdk";
+import { clip, display, inSandbox, runBudgetNote, runTimeLeftMs, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, withNotices, } from "./common.js";
+/** 不给 `timeoutSeconds` 时的命令超时（秒），不超过 `sandbox.limits.maxCommandSeconds`。 */
+export const BASH_DEFAULT_TIMEOUT_SECONDS = 120;
+/** The longest `description` (the shell row shows it instead of the command). */
+export const BASH_DESCRIPTION_MAX_CHARS = 120;
+/** bash 结果超过这么多字符即转存（走现有输出存档，模型用 read_tool_output 分页读）。 */
+export const BASH_SPILL_CHARS = 30_000;
+/** 一次命令最多收集的输出字节（stdout + stderr）；超出的丢弃并在结果里说明。 */
+const MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
+const SPEC = {
+    name: "sandbox_bash",
+    // Display only (the tool row; not in the fingerprint, never sent to the model).
+    keyArgs: ["command"],
+    description: "Run a shell command (bash) in this conversation's sandbox, an isolated Linux machine. " +
+        "Use it to run programs and scripts, install packages, process files and inspect the " +
+        "filesystem. The working directory is /workspace; files persist between calls in the same " +
+        "conversation, but background processes may not: when the sandbox is suspended after a period " +
+        "without use they can be stopped and /tmp cleared, so keep results in files under /workspace. " +
+        "Files the user attached to the conversation are under /workspace/attachments, " +
+        "and skill files under /skills (read-only). Each call runs in a fresh shell (no state such as " +
+        "cd or environment variables carries over). The result has stdout, stderr and the exit code; " +
+        "long output is saved and can be paged with read_tool_output. A command that runs longer than " +
+        "timeoutSeconds is stopped. Prefer sandbox_read, sandbox_write, sandbox_edit, sandbox_glob and " +
+        "sandbox_grep for reading, writing and searching files. To give a file to the user, use " +
+        "sandbox_deliver. Other sub-agents of this conversation may run commands in this sandbox at " +
+        "the same time. Always pass description: a few words saying what the command is for; the " +
+        "user sees it instead of the command.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            command: {
+                type: "string",
+                minLength: 1,
+                description: 'The command line to run, e.g. "python3 analyze.py data.csv".',
+            },
+            description: {
+                type: "string",
+                minLength: 1,
+                maxLength: BASH_DESCRIPTION_MAX_CHARS,
+                description: 'What this command does, in a few words (e.g. "Generate the final PDF"). Shown to the user.',
+            },
+            timeoutSeconds: {
+                type: "integer",
+                minimum: 1,
+                description: `Seconds before the command is stopped. Default ${BASH_DEFAULT_TIMEOUT_SECONDS}; the deployment sets a maximum (7200 by default).`,
+            },
+        },
+        required: ["command", "description"],
+        additionalProperties: false,
+    },
+};
+/** 本次命令的超时（秒）：给定的值，或默认值（不超过上限）。 */
+const secondsFor = (input, max) => input.timeoutSeconds ?? Math.min(BASH_DEFAULT_TIMEOUT_SECONDS, max);
+/**
+ * 命令结果 → 给模型的文本。`budgetClamped`：运行的时限把超时收紧到了 `seconds`（Ruling M20），超时说明改为
+ * 指向 `runtime.maxRunSeconds`，而不是让模型加大 timeoutSeconds。
+ */
+export function formatExec(r, seconds, budgetClamped = false) {
+    const parts = [];
+    if (r.stdout !== "")
+        parts.push(r.stdout.replace(/\n$/, ""));
+    if (r.stderr !== "")
+        parts.push(`[stderr]\n${r.stderr.replace(/\n$/, "")}`);
+    if (r.truncated)
+        parts.push(`[Output truncated: only the first ${MAX_OUTPUT_BYTES} bytes were kept.]`);
+    if (r.timedOut && budgetClamped) {
+        parts.push(`[timedOut: the command did not finish within ${seconds}s and was stopped. ${runBudgetNote(seconds)} The sandbox is still usable; split the work into shorter steps that save progress to files under /workspace, or run long jobs in the background and check on them in a later run.]`);
+    }
+    else if (r.timedOut) {
+        parts.push(`[timedOut: the command did not finish within ${seconds}s and was stopped. The sandbox is still usable; pass a larger timeoutSeconds (up to the deployment maximum), or split the work into shorter steps that save progress to files under /workspace.]`);
+    }
+    else if (r.exitCode === null) {
+        parts.push("[The command was stopped before it finished; its effects may be partial. Check the sandbox state before retrying.]");
+    }
+    else {
+        parts.push(`[exit code: ${r.exitCode}]`);
+        if (budgetClamped)
+            parts.push(`[${runBudgetNote(seconds)}]`);
+    }
+    return parts.join("\n");
+}
+/** 内置工具 `sandbox_bash`：在本对话的沙箱里执行命令。 */
+export function sandboxBashTool(deps) {
+    return {
+        spec: SPEC,
+        defaultPolicy: "allow",
+        spillChars: BASH_SPILL_CHARS,
+        unavailable: unavailableWhenNoSandbox(deps),
+        // 命令自己的超时先到（提供方停掉命令、返回 timedOut），管线的时限再留出等锁与创建 / 恢复的余量
+        timeoutMs: (input) => {
+            const cfg = deps.config();
+            const max = cfg.sandbox.limits.maxCommandSeconds;
+            return Math.min(secondsFor(input, max), max) * 1000 + sandboxBaseTimeoutMs(cfg);
+        },
+        async run(input, ctx) {
+            const { command, description } = input;
+            const max = deps.config().sandbox.limits.maxCommandSeconds;
+            const req = input.timeoutSeconds;
+            if (req !== undefined && req > max) {
+                throw new ToolError(`timeoutSeconds ${req} is over the limit of ${max} seconds; pass a value of at most ${max}.`);
+            }
+            const asked = secondsFor(input, max);
+            // 运行截止前命令要自己超时（Ruling M20）：在拿到沙箱之后算，等锁与恢复用掉的时间一并扣掉
+            let seconds = asked;
+            const { value: r, notices } = await inSandbox(deps, ctx, ({ h, p, signal }) => {
+                const left = Math.floor(runTimeLeftMs(ctx.runDeadline) / 1000);
+                seconds = Math.max(1, Math.min(asked, left));
+                return p.exec(h, {
+                    command,
+                    cwd: "/workspace",
+                    timeoutMs: seconds * 1000,
+                    maxOutputBytes: MAX_OUTPUT_BYTES,
+                    signal,
+                });
+            });
+            const clamped = seconds < asked;
+            const shown = clip(command, 120);
+            return {
+                content: [{ type: "text", text: withNotices(notices, formatExec(r, seconds, clamped)) }],
+                isError: r.timedOut || r.exitCode === null,
+                // display only: a non-zero exit shows as failed on the row, `isError` stays as it was
+                view: {
+                    kind: "command",
+                    ...(description !== undefined && { description }),
+                    exitCode: r.exitCode,
+                    timedOut: r.timedOut,
+                },
+                display: r.timedOut
+                    ? display(`命令超时（${seconds} 秒）：${shown}`, `Command timed out (${seconds}s): ${shown}`)
+                    : r.exitCode === null
+                        ? display(`命令被中止：${shown}`, `Command stopped: ${shown}`)
+                        : display(`运行命令（退出码 ${r.exitCode}）：${shown}`, `Ran command (exit ${r.exitCode}): ${shown}`),
+            };
+        },
+    };
+}

package/dist/tools/builtins/sandbox/common.d.ts

@@ -0,0 +1,116 @@
+import { type SandboxHandle, type SandboxProvider } from "@capybara-hq/plugin-sdk";
+import type { KernelConfig } from "../../../config/schema.js";
+import type { AttachmentsService } from "../../../conversations/attachments.service.js";
+import type { EventLog } from "../../../conversations/event-log.js";
+import { type SandboxService } from "../../../sandbox/sandbox.service.js";
+import type { StorageService } from "../../../storage/storage.service.js";
+import type { BuiltinCallContext } from "../../registry.js";
+/** 沙箱工具的依赖（都按调用时取，多副本下无进程内状态）。 */
+export interface SandboxToolDeps {
+    /** `pathLease` may be absent (test stubs): the kernel's own file writes then take no path lease. */
+    sandbox: Pick<SandboxService, "available" | "withSandbox"> & Partial<Pick<SandboxService, "pathLease">>;
+    attachments: Pick<AttachmentsService, "listForConversation" | "openForConversation">;
+    storage: Pick<StorageService, "kernel" | "available">;
+    /** `publishChanged`: `sandbox_deliver` announces `changed: files` (UI refresh B). */
+    eventLog: Pick<EventLog, "append"> & Partial<Pick<EventLog, "publishChanged">>;
+    config: () => KernelConfig;
+}
+/** 回调拿到的沙箱：句柄、提供方与「调用 signal + 锁丢失」合并后的 signal（每个提供方调用都传它）。 */
+export interface SandboxSession {
+    h: SandboxHandle;
+    p: SandboxProvider;
+    signal: AbortSignal;
+    /** 本次是新建 / 重建的沙箱（之前复制进去的文件都已不在）。 */
+    reset: boolean;
+}
+/** 没有沙箱提供方时「工具不可用」的原因（进提醒与调用结果）。 */
+/** 本对话第一次用沙箱。 */
+export declare const SANDBOX_STARTED_NOTICE = "Sandbox started for this conversation (first use); the working directory is /workspace.";
+/** 沙箱被重建（之前的实例已销毁或不在了）。 */
+export declare const SANDBOX_RECREATED_NOTICE = "Sandbox was recreated; previous files are gone.";
+/** 没有沙箱提供方时「工具不可用」的原因（进提醒，内核在后面补句号）：与调用时的错误同一句话。 */
+export declare const SANDBOX_UNAVAILABLE_REASON: string;
+/** 沙箱里附件所在目录。 */
+export declare const ATTACHMENTS_DIR = "/workspace/attachments";
+/** 已同步附件的标记文件：`{ <附件 id>: <文件名> }`。 */
+export declare const SYNC_MARKER = "/workspace/attachments/.capybara-sync.json";
+/** 附件文件名的上限（UTF-8 字节，常见文件系统单个文件名上限 255 字节，留出 `-N` 后缀的余量）。 */
+export declare const ATTACHMENT_NAME_MAX_BYTES = 200;
+/**
+ * Extra margin (ms) on top of a sandbox tool's time limit: creating / resuming the sandbox, and the
+ * fallback for stopping a command after its timeout (when the E2B kill script does not finish, the
+ * sandbox is restarted: up to about 20 s to kill, plus pause and a cold connect of up to 120 s, about
+ * 160 s). Pulling the image on first creation is not included (deployments pre-pull
+ * `sandbox.image`; see the sandbox-docker plugin's README in capybara-hq/plugins).
+ */
+export declare const SANDBOX_SETUP_MARGIN_MS = 180000;
+/**
+ * 沙箱工具的基本执行时限：`tools.timeoutMs` + 等锁（`sandbox.lockWaitSeconds`）+ {@link SANDBOX_SETUP_MARGIN_MS}。
+ */
+export declare const sandboxBaseTimeoutMs: (cfg: KernelConfig) => number;
+/**
+ * 运行截止前给沙箱命令留的余量（毫秒）：命令超时后停命令、写工具结果的时间（Ruling M20）。
+ */
+export declare const RUN_DEADLINE_MARGIN_MS = 30000;
+/**
+ * 运行还允许沙箱命令跑多久（毫秒）：截止时间减去 {@link RUN_DEADLINE_MARGIN_MS}；没有截止时间为 Infinity。
+ * 可能为负（快到截止了），调用方自己取下限。
+ */
+export declare function runTimeLeftMs(runDeadline: number | undefined, now?: number): number;
+/**
+ * glob / grep 的命令超时：不超过 `tools.timeoutMs`，且放得进本次调用剩下的时间（基本时限从 `startedAt` 起算，
+ * 扣掉 {@link SANDBOX_SETUP_MARGIN_MS}，留给超时后停命令的兜底）与运行剩下的时间（{@link runTimeLeftMs}）——
+ * 等锁或恢复沙箱用掉的时间从这里扣，命令自己先超时、给模型可执行的说明，而不是被管线的时限或运行截止打断。
+ * 至少 1 秒。
+ */
+export declare function searchTimeoutMs(cfg: KernelConfig, startedAt: number, now?: number, runDeadline?: number): number;
+/** 运行时限收紧了命令超时时给模型的说明（英文）。 */
+export declare const runBudgetNote: (seconds: number) => string;
+/** 显示摘要（中英文，各截到 200 码点以内；只给界面看）。 */
+export declare function display(zh: string, en: string): {
+    summary: {
+        zh: string;
+        en: string;
+    };
+};
+/** 折叠空白并按码点截断（显示摘要与错误里引用用户 / 模型给的文本）。 */
+export declare function clip(s: string, max: number): string;
+/** 结果正文前加上沙箱状态说明。 */
+export declare function withNotices(notices: readonly string[], text: string): string;
+/** 校验沙箱内路径（`validateSandboxPath`）；不合法抛给模型可执行的错误。 */
+export declare function checkPath(path: string, field?: string): string;
+/** 写入类工具的路径：`/skills` 是技能文件的只读副本。 */
+export declare function checkWritable(path: string): string;
+/** POSIX shell 单引号转义。 */
+export declare function shellQuote(s: string): string;
+/**
+ * 给附件分配沙箱里的文件名（按给定顺序，确定性）：清理成安全的路径段（≤ {@link ATTACHMENT_NAME_MAX_BYTES}
+ * 字节），与 `used`（已同步的）及彼此不重名，重名时加 `-2`、`-3`……（加在扩展名之前）。
+ * 清理后仍不是合法沙箱路径的用 `attachment-<id 前 8 位>`。
+ */
+export declare function assignAttachmentNames(items: readonly {
+    id: string;
+    name: string;
+}[], used: ReadonlySet<string>): Map<string, string>;
+/**
+ * 在本对话的沙箱上执行 `fn`（`SandboxService.withSandbox`：懒创建、恢复、重建）：先同步附件，
+ * 再执行；返回结果与要加在结果开头的状态说明（首次使用 / 重建 / 新复制的附件）。
+ * `withSandbox` 遇到实例不在时会重建并再调用一次回调，说明按最后一次调用的为准。
+ */
+export declare function inSandbox<T>(deps: SandboxToolDeps, ctx: BuiltinCallContext, fn: (s: SandboxSession) => Promise<T>): Promise<{
+    value: T;
+    notices: string[];
+}>;
+/** The conversation whose sandbox a call uses (the parent's for a sub-agent). */
+export declare const sandboxConversationOf: (ctx: BuiltinCallContext) => string;
+/**
+ * Runs `fn` under the per-path lease of `path` in the call's sandbox (spec §10.4: the kernel's own
+ * read-modify-write of one file never loses another holder's update). `fn` gets `signal` combined
+ * with the path lease's: pass it to every provider call, so a lost path lease stops the write.
+ * Without `pathLease` (test stubs) it just runs `fn` with `signal`.
+ */
+export declare function withPathLease<T>(deps: Pick<SandboxToolDeps, "sandbox">, ctx: BuiltinCallContext, path: string, signal: AbortSignal, fn: (signal: AbortSignal) => Promise<T>): Promise<T>;
+/** 本部署是否有沙箱：没有时返回「不可用」原因（注册表据此把沙箱工具报为不可用）。 */
+export declare const unavailableWhenNoSandbox: (deps: Pick<SandboxToolDeps, "sandbox">) => () => string | null;
+/** 读出的字节是否像二进制（开头 8 KB 里有 NUL）。 */
+export declare function looksBinary(data: Uint8Array): boolean;

package/dist/tools/builtins/sandbox/common.js

@@ -0,0 +1,306 @@
+import { isSandboxGoneError, ToolError, validateSandboxPath, } from "@capybara-hq/plugin-sdk";
+import { ApiError } from "../../../errors.js";
+import { SandboxPathBusyError } from "../../../sandbox/leases.js";
+import { SandboxLockLostError } from "../../../sandbox/sandbox.service.js";
+// ---- 模型可见文案（英文） ----
+/** 没有沙箱提供方时「工具不可用」的原因（进提醒与调用结果）。 */
+/** 本对话第一次用沙箱。 */
+export const SANDBOX_STARTED_NOTICE = "Sandbox started for this conversation (first use); the working directory is /workspace.";
+/** 沙箱被重建（之前的实例已销毁或不在了）。 */
+export const SANDBOX_RECREATED_NOTICE = "Sandbox was recreated; previous files are gone.";
+const BUSY_TEXT = "The sandbox is busy with another command in this conversation; wait for it to finish and retry.";
+const NO_SANDBOX_TEXT = "No sandbox is configured in this deployment; ask an administrator to install a sandbox plugin, or do the task without the sandbox.";
+/** 没有沙箱提供方时「工具不可用」的原因（进提醒，内核在后面补句号）：与调用时的错误同一句话。 */
+export const SANDBOX_UNAVAILABLE_REASON = NO_SANDBOX_TEXT.slice(0, -1);
+const PATH_BUSY_TEXT = "Another sub-agent is writing this file; wait a moment and retry.";
+const LOCK_LOST_TEXT = "The sandbox operation was interrupted because the sandbox lock was lost; check the sandbox state and retry.";
+/** 沙箱里附件所在目录。 */
+export const ATTACHMENTS_DIR = "/workspace/attachments";
+/** 已同步附件的标记文件：`{ <附件 id>: <文件名> }`。 */
+export const SYNC_MARKER = `${ATTACHMENTS_DIR}/.capybara-sync.json`;
+const MARKER_MAX_BYTES = 1024 * 1024;
+/** 附件文件名的上限（UTF-8 字节，常见文件系统单个文件名上限 255 字节，留出 `-N` 后缀的余量）。 */
+export const ATTACHMENT_NAME_MAX_BYTES = 200;
+/**
+ * Extra margin (ms) on top of a sandbox tool's time limit: creating / resuming the sandbox, and the
+ * fallback for stopping a command after its timeout (when the E2B kill script does not finish, the
+ * sandbox is restarted: up to about 20 s to kill, plus pause and a cold connect of up to 120 s, about
+ * 160 s). Pulling the image on first creation is not included (deployments pre-pull
+ * `sandbox.image`; see the sandbox-docker plugin's README in capybara-hq/plugins).
+ */
+export const SANDBOX_SETUP_MARGIN_MS = 180_000;
+/**
+ * 沙箱工具的基本执行时限：`tools.timeoutMs` + 等锁（`sandbox.lockWaitSeconds`）+ {@link SANDBOX_SETUP_MARGIN_MS}。
+ */
+export const sandboxBaseTimeoutMs = (cfg) => cfg.tools.timeoutMs + cfg.sandbox.lockWaitSeconds * 1000 + SANDBOX_SETUP_MARGIN_MS;
+/**
+ * 运行截止前给沙箱命令留的余量（毫秒）：命令超时后停命令、写工具结果的时间（Ruling M20）。
+ */
+export const RUN_DEADLINE_MARGIN_MS = 30_000;
+/**
+ * 运行还允许沙箱命令跑多久（毫秒）：截止时间减去 {@link RUN_DEADLINE_MARGIN_MS}；没有截止时间为 Infinity。
+ * 可能为负（快到截止了），调用方自己取下限。
+ */
+export function runTimeLeftMs(runDeadline, now = Date.now()) {
+    return runDeadline === undefined ? Infinity : runDeadline - RUN_DEADLINE_MARGIN_MS - now;
+}
+/**
+ * glob / grep 的命令超时：不超过 `tools.timeoutMs`，且放得进本次调用剩下的时间（基本时限从 `startedAt` 起算，
+ * 扣掉 {@link SANDBOX_SETUP_MARGIN_MS}，留给超时后停命令的兜底）与运行剩下的时间（{@link runTimeLeftMs}）——
+ * 等锁或恢复沙箱用掉的时间从这里扣，命令自己先超时、给模型可执行的说明，而不是被管线的时限或运行截止打断。
+ * 至少 1 秒。
+ */
+export function searchTimeoutMs(cfg, startedAt, now = Date.now(), runDeadline) {
+    const left = startedAt + sandboxBaseTimeoutMs(cfg) - SANDBOX_SETUP_MARGIN_MS - now;
+    return Math.max(1000, Math.min(cfg.tools.timeoutMs, left, runTimeLeftMs(runDeadline, now)));
+}
+/** 运行时限收紧了命令超时时给模型的说明（英文）。 */
+export const runBudgetNote = (seconds) => `This run's time budget limits commands to ${seconds} seconds (configurable via runtime.maxRunSeconds).`;
+/** 显示摘要（中英文，各截到 200 码点以内；只给界面看）。 */
+export function display(zh, en) {
+    return { summary: { zh: clip(zh, 200), en: clip(en, 200) } };
+}
+/** 折叠空白并按码点截断（显示摘要与错误里引用用户 / 模型给的文本）。 */
+export function clip(s, max) {
+    const flat = s.replace(/\s+/g, " ").trim();
+    const cps = [...flat];
+    return cps.length <= max ? flat : `${cps.slice(0, max - 1).join("")}…`;
+}
+/** 结果正文前加上沙箱状态说明。 */
+export function withNotices(notices, text) {
+    return [...notices, text].join("\n\n");
+}
+/** 校验沙箱内路径（`validateSandboxPath`）；不合法抛给模型可执行的错误。 */
+export function checkPath(path, field = "path") {
+    const errors = validateSandboxPath(path);
+    if (errors.length > 0) {
+        throw new ToolError(`Invalid ${field} "${clip(path, 200)}": ${errors.join("; ")}. Pass an absolute path under /workspace, /skills or /tmp.`);
+    }
+    return path.length > 1 && path.endsWith("/") ? path.slice(0, -1) : path;
+}
+/** 写入类工具的路径：`/skills` 是技能文件的只读副本。 */
+export function checkWritable(path) {
+    const p = checkPath(path);
+    if (p === "/skills" || p.startsWith("/skills/")) {
+        throw new ToolError(`Path ${clip(p, 200)} is read-only (/skills holds skill files); pass a path under /workspace or /tmp instead.`);
+    }
+    return p;
+}
+/** POSIX shell 单引号转义。 */
+export function shellQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+const utf8 = new TextEncoder();
+const byteLength = (s) => Buffer.byteLength(s, "utf8");
+/** 拆成主名与扩展名（扩展名不超过 20 字节，`.` 开头的隐藏文件没有扩展名）。 */
+function splitExt(n) {
+    const dot = n.lastIndexOf(".");
+    return dot > 0 && byteLength(n.slice(dot)) <= 20 ? [n.slice(0, dot), n.slice(dot)] : [n, ""];
+}
+/** `stem + suffix + ext` 不超过 {@link ATTACHMENT_NAME_MAX_BYTES} 字节：按码点截短主名，保留后缀与扩展名。 */
+function fitName(stem, suffix, ext) {
+    const room = ATTACHMENT_NAME_MAX_BYTES - byteLength(suffix + ext);
+    let out = "";
+    let used = 0;
+    for (const cp of stem) {
+        const b = byteLength(cp);
+        if (used + b > room)
+            break;
+        out += cp;
+        used += b;
+    }
+    return out + suffix + ext;
+}
+/** 把一个文件名清理成单个安全的路径段（控制字符、`/`、`\` 换成 `_`），过长时保留扩展名按字节截断。 */
+function sanitizeName(raw) {
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: 正是要换掉控制字符
+    const n = raw.replace(/[\u0000-\u001f\u007f/\\]/g, "_").trim();
+    if (n === "" || n === "." || n === "..")
+        return "attachment";
+    if (byteLength(n) <= ATTACHMENT_NAME_MAX_BYTES)
+        return n;
+    const [stem, ext] = splitExt(n);
+    return fitName(stem, "", ext);
+}
+/**
+ * 给附件分配沙箱里的文件名（按给定顺序，确定性）：清理成安全的路径段（≤ {@link ATTACHMENT_NAME_MAX_BYTES}
+ * 字节），与 `used`（已同步的）及彼此不重名，重名时加 `-2`、`-3`……（加在扩展名之前）。
+ * 清理后仍不是合法沙箱路径的用 `attachment-<id 前 8 位>`。
+ */
+export function assignAttachmentNames(items, used) {
+    const taken = new Set(used);
+    taken.add(SYNC_MARKER.slice(ATTACHMENTS_DIR.length + 1));
+    const out = new Map();
+    for (const a of items) {
+        let base = sanitizeName(a.name);
+        if (validateSandboxPath(`${ATTACHMENTS_DIR}/${base}`).length > 0) {
+            base = `attachment-${a.id.slice(0, 8)}`;
+        }
+        let name = base;
+        if (taken.has(name)) {
+            const [stem, ext] = splitExt(base);
+            for (let i = 2; taken.has(name); i++)
+                name = fitName(stem, `-${i}`, ext);
+        }
+        taken.add(name);
+        out.set(a.id, name);
+    }
+    return out;
+}
+/** 解析标记文件；坏的按空处理（重新同步，同名文件被覆盖）。 */
+function parseMarker(data) {
+    try {
+        const v = JSON.parse(new TextDecoder().decode(data));
+        if (v === null || typeof v !== "object" || Array.isArray(v))
+            return {};
+        return Object.fromEntries(Object.entries(v).filter((e) => typeof e[1] === "string"));
+    }
+    catch {
+        return {};
+    }
+}
+/** 一个附件复制失败时给模型的原因（不带内部细节）。 */
+function copyFailureReason(e) {
+    if (e instanceof ApiError && e.code === "storage.unavailable") {
+        return "file storage is unavailable";
+    }
+    return "a temporary error occurred; it will be retried on the next sandbox call";
+}
+/**
+ * 把本对话已 ready 的附件复制到 `/workspace/attachments/<name>`，标记文件记下已复制的（不重复复制）。
+ * `reset`（新建 / 重建的沙箱，文件已不在）时忽略标记文件全部重新复制。对象已不在的附件跳过（下次再试）。
+ * 每复制一个就更新标记文件：中途超时 / 中止，下次从停下的地方继续。
+ * 单个附件失败（存储故障等）只跳过它并给出说明，不让工具调用失败；signal 已中止或实例已不在时照常抛出。
+ * 返回本次复制的沙箱路径与失败说明。
+ */
+async function syncAttachments(deps, ctx, s, reset) {
+    const none = { copied: [], failures: [] };
+    const conv = sandboxConversationOf(ctx);
+    const list = await deps.attachments.listForConversation(ctx.orgId, conv);
+    if (list.length === 0)
+        return none;
+    // nothing to copy (the usual case): no path lease, so calls do not queue on the marker
+    if (!reset) {
+        const marker = await readSyncMarker(s);
+        if (list.every((a) => Object.hasOwn(marker, a.id)))
+            return none;
+    }
+    // the sync marker is read, changed and written: one holder at a time
+    return withPathLease(deps, ctx, SYNC_MARKER, s.signal, (signal) => copyAttachments(deps, ctx, { ...s, signal }, reset, conv, list));
+}
+/** The sync marker's entries (`{}` when it is missing, too large or unreadable). */
+async function readSyncMarker(s) {
+    const m = await s.p.readFile(s.h, SYNC_MARKER, { maxBytes: MARKER_MAX_BYTES, signal: s.signal });
+    return m && !m.truncated ? parseMarker(m.data) : {};
+}
+async function copyAttachments(deps, ctx, s, reset, conv, list) {
+    const none = { copied: [], failures: [] };
+    let marker = reset ? {} : await readSyncMarker(s);
+    const pending = list.filter((a) => !Object.hasOwn(marker, a.id));
+    if (pending.length === 0)
+        return none;
+    const names = assignAttachmentNames(pending, new Set(Object.values(marker)));
+    const copied = [];
+    const failures = [];
+    for (const a of pending) {
+        const name = names.get(a.id);
+        const path = `${ATTACHMENTS_DIR}/${name}`;
+        try {
+            const opened = await deps.attachments.openForConversation(ctx.orgId, conv, a.id);
+            if (!opened)
+                continue;
+            const bytes = new Uint8Array(await new Response(opened.body).arrayBuffer());
+            await s.p.writeFile(s.h, path, bytes, s.signal);
+        }
+        catch (e) {
+            // 中止（超时 / 锁丢失 / 运行停止）与实例已不在（withSandbox 据此重建）不吞
+            if (s.signal.aborted || isSandboxGoneError(e))
+                throw e;
+            failures.push(`Attachment ${name} could not be copied: ${copyFailureReason(e)}.`);
+            continue;
+        }
+        // 文件已复制：本次算复制成功。标记写成功后才记进内存里的标记（之后的写入不带上未落盘的项）；
+        // 标记写失败只意味着下次会重新复制这个文件
+        copied.push(path);
+        const next = { ...marker, [a.id]: name };
+        try {
+            await s.p.writeFile(s.h, SYNC_MARKER, utf8.encode(JSON.stringify(next)), s.signal);
+            marker = next;
+        }
+        catch (e) {
+            if (s.signal.aborted || isSandboxGoneError(e))
+                throw e;
+        }
+    }
+    return { copied, failures };
+}
+/** 沙箱服务的错误 → 给模型的可执行说明；其余原样抛出（管线按「工具失败」处理）。 */
+function mapError(e) {
+    if (e instanceof ApiError) {
+        if (e.code === "sandbox.busy")
+            return new ToolError(BUSY_TEXT);
+        if (e.code === "sandbox.unavailable")
+            return new ToolError(NO_SANDBOX_TEXT);
+    }
+    if (e instanceof SandboxLockLostError)
+        return new ToolError(LOCK_LOST_TEXT);
+    if (e instanceof SandboxPathBusyError)
+        return new ToolError(PATH_BUSY_TEXT);
+    return e;
+}
+/**
+ * 在本对话的沙箱上执行 `fn`（`SandboxService.withSandbox`：懒创建、恢复、重建）：先同步附件，
+ * 再执行；返回结果与要加在结果开头的状态说明（首次使用 / 重建 / 新复制的附件）。
+ * `withSandbox` 遇到实例不在时会重建并再调用一次回调，说明按最后一次调用的为准。
+ */
+export async function inSandbox(deps, ctx, fn) {
+    try {
+        return await deps.sandbox.withSandbox({
+            orgId: ctx.orgId,
+            conversationId: sandboxConversationOf(ctx),
+            // a sub-agent is told when another holder rebuilt the shared sandbox (final review m5)
+            holderConversationId: ctx.conversationId,
+        }, async (h, p, info, signal) => {
+            const s = { h, p, signal, reset: info.fresh || info.recreated };
+            const notices = [];
+            if (info.recreated)
+                notices.push(SANDBOX_RECREATED_NOTICE);
+            else if (info.fresh)
+                notices.push(SANDBOX_STARTED_NOTICE);
+            const { copied, failures } = await syncAttachments(deps, ctx, s, s.reset);
+            if (copied.length > 0) {
+                notices.push(`Attachments copied into the sandbox: ${copied.join(", ")}.`);
+            }
+            notices.push(...failures);
+            return { value: await fn(s), notices };
+        }, ctx.signal);
+    }
+    catch (e) {
+        throw mapError(e);
+    }
+}
+/** The conversation whose sandbox a call uses (the parent's for a sub-agent). */
+export const sandboxConversationOf = (ctx) => ctx.sandboxConversationId ?? ctx.conversationId;
+/**
+ * Runs `fn` under the per-path lease of `path` in the call's sandbox (spec §10.4: the kernel's own
+ * read-modify-write of one file never loses another holder's update). `fn` gets `signal` combined
+ * with the path lease's: pass it to every provider call, so a lost path lease stops the write.
+ * Without `pathLease` (test stubs) it just runs `fn` with `signal`.
+ */
+export async function withPathLease(deps, ctx, path, signal, fn) {
+    if (!deps.sandbox.pathLease)
+        return fn(signal);
+    const lease = await deps.sandbox.pathLease(sandboxConversationOf(ctx), path, signal);
+    try {
+        return await fn(AbortSignal.any([signal, lease.signal]));
+    }
+    finally {
+        await lease.release().catch(() => { });
+    }
+}
+/** 本部署是否有沙箱：没有时返回「不可用」原因（注册表据此把沙箱工具报为不可用）。 */
+export const unavailableWhenNoSandbox = (deps) => () => deps.sandbox.available ? null : SANDBOX_UNAVAILABLE_REASON;
+/** 读出的字节是否像二进制（开头 8 KB 里有 NUL）。 */
+export function looksBinary(data) {
+    return data.subarray(0, 8192).includes(0);
+}

package/dist/tools/builtins/sandbox/deliver.d.ts

@@ -0,0 +1,5 @@
+import type { BuiltinTool } from "../../registry.js";
+import { type SandboxToolDeps } from "./common.js";
+export declare function contentTypeFor(name: string): string;
+/** 内置工具 `sandbox_deliver`：把沙箱里的文件存进对象存储，写 `artifact_created`，用户可下载。 */
+export declare function sandboxDeliverTool(deps: SandboxToolDeps): BuiltinTool;