@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.4

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

@@ -1,15 +1,17 @@
 import { ToolError } from "@capybara-hq/plugin-sdk";
-import { clip, display, inSandbox, runBudgetNote, runTimeLeftMs, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, withNotices, } from "./common.js";
-/** 不给 `timeoutSeconds` 时的命令超时（秒），不超过 `sandbox.limits.maxCommandSeconds`。 */
+import { backgroundMaxSeconds, LAUNCH_EXEC_TIMEOUT_MS, launchScript, newTaskId, startedText, taskOutputPath, taskSidPath, } from "../../../background/launch.js";
+import { KILL_SESSION_TIMEOUT_MS, killSession, SID_RE } from "../../../background/session.js";
+import { clip, display, inSandbox, noSandboxError, runBudgetNote, runTimeLeftMs, sandboxBaseTimeoutMs, sandboxConversationOf, unavailableWhenNoSandbox, withNotices, } from "./common.js";
+/** The command timeout in seconds when `timeout` is not given, at most `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 分页读）。 */
+/** bash 结果超过这么多字符即转存（走现有输出存档，模型用 ReadToolOutput 分页读）。 */
 export const BASH_SPILL_CHARS = 30_000;
 /** 一次命令最多收集的输出字节（stdout + stderr）；超出的丢弃并在结果里说明。 */
 const MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
 const SPEC = {
-    name: "sandbox_bash",
+    name: "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. " +
@@ -20,12 +22,22 @@ const SPEC = {
         "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 " +
+        "long output is saved and can be paged with ReadToolOutput. A command that runs longer than " +
+        "timeout milliseconds is stopped. Prefer Read, Write, Edit, Glob and " +
+        "Grep for reading, writing and searching files. To give a file to the user, use " +
+        "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.",
+        "user sees it instead of the command.\n\n" +
+        "You can use the run_in_background parameter to run the command in the background, which " +
+        "allows you to continue working while the command runs, e.g. a dev server, a long build or a " +
+        "test suite. The call returns at once with a task id and the command's output goes to a file " +
+        "under /workspace/.capybara/tasks. Read the output with TaskOutput (or Read) and stop the " +
+        "task with TaskStop; you will be told when it finishes. You do not need to use '&' at the end " +
+        "of the command when using this parameter. In the background, timeout defaults to the " +
+        "deployment's background maximum (7200000 by default). A background task ends when its " +
+        "command exits, and processes it left running are stopped. A background task is lost if the " +
+        "sandbox is suspended (it is suspended after it has been running for a while, " +
+        "sandbox.limits.maxRunningMinutes), so keep its results in files under /workspace.",
     inputSchema: {
         type: "object",
         properties: {
@@ -40,21 +52,25 @@ const SPEC = {
                 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: {
+            timeout: {
                 type: "integer",
                 minimum: 1,
-                description: `Seconds before the command is stopped. Default ${BASH_DEFAULT_TIMEOUT_SECONDS}; the deployment sets a maximum (7200 by default).`,
+                description: `Milliseconds before the command is stopped. Default ${BASH_DEFAULT_TIMEOUT_SECONDS * 1000} (in the background: the background maximum); the deployment sets a maximum (7200000 by default); a larger value is lowered to it.`,
+            },
+            run_in_background: {
+                type: "boolean",
+                description: "Set to true to run this command in the background. Use TaskOutput to read the output later.",
             },
         },
         required: ["command", "description"],
         additionalProperties: false,
     },
 };
-/** 本次命令的超时（秒）：给定的值，或默认值（不超过上限）。 */
-const secondsFor = (input, max) => input.timeoutSeconds ?? Math.min(BASH_DEFAULT_TIMEOUT_SECONDS, max);
+/** This command's timeout in milliseconds: the given value or the default, at most the maximum. */
+const msFor = (input, maxSeconds) => Math.min(input.timeout ?? BASH_DEFAULT_TIMEOUT_SECONDS * 1000, maxSeconds * 1000);
 /**
  * 命令结果 → 给模型的文本。`budgetClamped`：运行的时限把超时收紧到了 `seconds`（Ruling M20），超时说明改为
- * 指向 `runtime.maxRunSeconds`，而不是让模型加大 timeoutSeconds。
+ * 指向 `runtime.maxRunSeconds`，而不是让模型加大 timeout。
  */
 export function formatExec(r, seconds, budgetClamped = false) {
     const parts = [];
@@ -68,7 +84,7 @@ export function formatExec(r, seconds, budgetClamped = false) {
         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.]`);
+        parts.push(`[timedOut: the command did not finish within ${seconds}s and was stopped. The sandbox is still usable; pass a larger timeout in milliseconds (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.]");
@@ -80,7 +96,210 @@ export function formatExec(r, seconds, budgetClamped = false) {
     }
     return parts.join("\n");
 }
-/** 内置工具 `sandbox_bash`：在本对话的沙箱里执行命令。 */
+/** The most output the launch exec keeps (it prints only the session id, or an error). */
+const LAUNCH_MAX_OUTPUT_BYTES = 64 * 1024;
+/** Above about this many bytes of base64, a provider may refuse the launch exec's command. */
+const LARGE_COMMAND_BASE64_BYTES = 96 * 1024;
+/** Why a launch exec did not start the command, for the model and the row's reason. */
+function launchFailure(r) {
+    if (r.timedOut)
+        return `the launch did not finish within ${LAUNCH_EXEC_TIMEOUT_MS / 1000}s`;
+    if (r.exitCode === null)
+        return "the launch was stopped before it finished";
+    const said = clip(r.stderr || (r.exitCode === 0 ? "" : r.stdout), 500).replace(/\.$/, "");
+    if (said !== "")
+        return said;
+    return r.exitCode === 0
+        ? "the launch printed no session id"
+        : `the launch exited with code ${r.exitCode}`;
+}
+/**
+ * `Bash` with `run_in_background` (spec 2026-11-05-background-bash-design §2.1, §4.2):
+ * 1. reserves the task's row (`BackgroundTaskStore.reserve`: `running`, no `sid`), refused once
+ *    the sandbox runs `sandbox.background.maxTasks` tasks; the count and the insert are one step
+ *    under the sandbox's launch lock;
+ * 2. runs one short launch exec under the call's shared lease, and in the same lease records the
+ *    session id and the instance (`markStarted`); a command that started but could not be
+ *    recorded is killed there (`pkill -KILL -s <sid>`), so no process runs untracked;
+ * 3. any failure finishes the row as `failed` with the reason (`failLaunch`);
+ * 4. a stop that claimed the reservation meanwhile (`markStarted` answers `stopping`) has the
+ *    command killed at once and the row finished `stopped` (`finishStoppedLaunch`).
+ * The command runs in a session of its own under its own `timeout` (default and maximum
+ * {@link backgroundMaxSeconds}).
+ */
+async function runInBackground(deps, ctx, input) {
+    const { background, sandbox } = deps;
+    if (!background || !sandbox.currentInstance) {
+        throw new ToolError("Background tasks are not available here; call Bash without run_in_background.");
+    }
+    if (ctx.runId === undefined) {
+        throw new ToolError("Background tasks can only be started from an agent run; call Bash without run_in_background.");
+    }
+    if (!sandbox.available)
+        throw noSandboxError();
+    const currentInstance = sandbox.currentInstance.bind(sandbox);
+    const cfg = deps.config.get();
+    const maxMs = backgroundMaxSeconds(cfg) * 1000;
+    const requested = input.timeout;
+    const seconds = Math.max(1, Math.ceil(Math.min(requested ?? maxMs, maxMs) / 1000));
+    const root = sandboxConversationOf(ctx);
+    const maxTasks = cfg.sandbox.background.maxTasks;
+    const id = newTaskId();
+    const description = input.description ?? clip(input.command, 120);
+    const startedAt = new Date();
+    const reserved = await background.reserve({
+        id,
+        orgId: ctx.orgId,
+        conversationId: ctx.conversationId,
+        sandboxConversationId: root,
+        runId: ctx.runId,
+        callId: ctx.callId,
+        // the run's trigger account (the pipeline passes `runs.trigger_account_id` as `accountId`)
+        triggerAccountId: ctx.accountId,
+        description,
+        command: input.command,
+        outputPath: taskOutputPath(id),
+        startedAt,
+        deadlineAt: new Date(startedAt.getTime() + seconds * 1000),
+    }, maxTasks);
+    if (!reserved) {
+        throw new ToolError(`${maxTasks} background tasks are already running; stop one with TaskStop or wait for one to finish, then retry`);
+    }
+    // the conversation's background panel lists the task live (a sub-agent's task shows in its
+    // parent's panel too): announced when it starts and when its launch ends it (failed, stopped),
+    // since a client may have listed the reservation as running meanwhile; a failed publish only logs
+    const announce = async () => {
+        if (!deps.eventLog.publishChanged)
+            return;
+        for (const c of new Set([ctx.conversationId, root])) {
+            await deps.eventLog.publishChanged(c, "background");
+        }
+    };
+    const large = Math.ceil(Buffer.byteLength(input.command, "utf8") / 3) * 4 > LARGE_COMMAND_BASE64_BYTES
+        ? " A very large command (over about 96 KB after base64) cannot be started in the background; write it to a script under /workspace and run that instead."
+        : "";
+    // set once the row has its sid: from then on the task runs and is tracked, whatever follows
+    let started = false;
+    let launch;
+    let notices;
+    try {
+        ({ value: launch, notices } = await inSandbox(deps, ctx, async ({ h, p, signal }) => {
+            // right after the launch a process may fork while it is killed: killSession repeats
+            const kill = (sid) => killSession(p, h, sid);
+            // the session id the launch wrote before printing it: the launch may have ended (aborted,
+            // timed out, thrown) after starting the command but before its output came back
+            const sidFile = async () => {
+                const f = await p
+                    .readFile(h, `/workspace/${taskSidPath(id)}`, {
+                    maxBytes: 64,
+                    signal: AbortSignal.timeout(KILL_SESSION_TIMEOUT_MS),
+                })
+                    .catch(() => null);
+                const v = f ? new TextDecoder().decode(f.data).trim() : "";
+                return SID_RE.test(v) ? v : null;
+            };
+            let r;
+            try {
+                r = await p.exec(h, {
+                    command: launchScript(id, input.command, seconds),
+                    cwd: "/workspace",
+                    timeoutMs: LAUNCH_EXEC_TIMEOUT_MS,
+                    maxOutputBytes: LAUNCH_MAX_OUTPUT_BYTES,
+                    signal,
+                });
+            }
+            catch (e) {
+                const sid = await sidFile();
+                if (sid !== null)
+                    await kill(sid);
+                throw e;
+            }
+            const out = r.stdout.trim();
+            if (r.exitCode !== 0 || !SID_RE.test(out)) {
+                const sid = SID_RE.test(out) ? out : await sidFile();
+                if (sid !== null)
+                    await kill(sid);
+                return { kind: "not_started", why: launchFailure(r) };
+            }
+            const sid = out;
+            try {
+                // under the shared lease: no rebuild can come between the launch and this read
+                const instance = await currentInstance(root);
+                if (instance === null)
+                    throw new Error("the sandbox instance could not be read");
+                const marked = await background.markStarted(id, {
+                    sid,
+                    sandboxCreatedAt: instance.createdAt,
+                });
+                if (!marked)
+                    throw new Error("its task record was finished meanwhile");
+                started = true;
+                if (marked === "stopping") {
+                    // a stop claimed the reservation before the command started: kill it at once
+                    if (await kill(sid)) {
+                        await background.finishStoppedLaunch(id);
+                        return { kind: "stopped" };
+                    }
+                    // not confirmed: the task runs on and is tracked like any other (the poller checks it)
+                    await background.releaseStop(id);
+                }
+                return { kind: "started" };
+            }
+            catch (e) {
+                const stopped = await kill(sid);
+                const why = e instanceof Error ? e.message : String(e);
+                return { kind: "unrecorded", why, stopped };
+            }
+        }));
+    }
+    catch (e) {
+        if (started) {
+            // the task runs and its row has its sid: an error after that (releasing the lease, say)
+            // does not undo the launch
+            launch = { kind: "started" };
+            notices = [];
+        }
+        else {
+            // no sandbox, a busy or lost lease, an abort, a provider error: nothing started (or what
+            // did was killed above, when its session id could be read)
+            const why = e instanceof Error ? e.message : String(e);
+            await background.failLaunch(id, `launch failed: ${why}`).catch(() => undefined);
+            await announce();
+            if (large === "" || e instanceof ToolError)
+                throw e;
+            throw new ToolError(`The background task was not started: ${clip(why, 500).replace(/\.$/, "")}. Check the sandbox, or call Bash without run_in_background.${large}`);
+        }
+    }
+    if (launch.kind === "not_started") {
+        await background.failLaunch(id, launch.why);
+        await announce();
+        throw new ToolError(`The background task was not started: ${launch.why}. Check the sandbox, or call Bash without run_in_background.${large}`);
+    }
+    if (launch.kind === "stopped") {
+        await announce();
+        throw new ToolError(`Background task ${id} ("${description}") was stopped while it was starting, so nothing runs. Call Bash again if it is still needed.`);
+    }
+    if (launch.kind === "unrecorded") {
+        await background.failLaunch(id, `started but not recorded: ${launch.why}`);
+        await announce();
+        if (launch.stopped) {
+            throw new ToolError(`The background command started but could not be recorded (${launch.why}), so it was stopped. Retry, or call Bash without run_in_background.`);
+        }
+        throw new ToolError(`The background command started but could not be recorded (${launch.why}); an attempt to stop it failed, so it ends at its timeout. Check the sandbox before you retry, or call Bash without run_in_background.`);
+    }
+    await announce();
+    const lowered = requested !== undefined && requested > maxMs
+        ? `\n[timeout ${requested} ms is over the background task maximum; it was lowered to ${maxMs} ms.]`
+        : "";
+    const shown = clip(input.command, 120);
+    return {
+        content: [{ type: "text", text: withNotices(notices, startedText(id, description) + lowered) }],
+        isError: false,
+        view: { kind: "command", description, exitCode: null, timedOut: false },
+        display: display(`后台运行命令：${shown}`, `Started in the background: ${shown}`),
+    };
+}
+/** 内置工具 `Bash`：在本对话的沙箱里执行命令。 */
 export function sandboxBashTool(deps) {
     return {
         spec: SPEC,
@@ -90,34 +309,45 @@ export function sandboxBashTool(deps) {
         // 命令自己的超时先到（提供方停掉命令、返回 timedOut），管线的时限再留出等锁与创建 / 恢复的余量
         timeoutMs: (input) => {
             const cfg = deps.config.get();
+            // a background call is only the short launch; the task's own timeout runs in the sandbox
+            if (input.run_in_background === true) {
+                return LAUNCH_EXEC_TIMEOUT_MS + sandboxBaseTimeoutMs(cfg);
+            }
             const max = cfg.sandbox.limits.maxCommandSeconds;
-            return Math.min(secondsFor(input, max), max) * 1000 + sandboxBaseTimeoutMs(cfg);
+            return msFor(input, max) + sandboxBaseTimeoutMs(cfg);
         },
         async run(input, ctx) {
+            if (input.run_in_background === true) {
+                return runInBackground(deps, ctx, input);
+            }
             const { command, description } = input;
             const max = deps.config.get().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 requested = input.timeout;
+            const maxMs = max * 1000;
+            const askedMs = msFor(input, max);
+            // The run's deadline makes the command time out itself first (Ruling M20): counted after the
+            // sandbox is obtained, so the time spent waiting for the lock and resuming is deducted
+            let ms = askedMs;
             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));
+                const left = Math.floor(runTimeLeftMs(ctx.runDeadline) / 1000) * 1000;
+                ms = Math.max(1000, Math.min(askedMs, left));
                 return p.exec(h, {
                     command,
                     cwd: "/workspace",
-                    timeoutMs: seconds * 1000,
+                    timeoutMs: ms,
                     maxOutputBytes: MAX_OUTPUT_BYTES,
                     signal,
                 });
             });
-            const clamped = seconds < asked;
+            const seconds = ms / 1000;
+            const clamped = ms < askedMs;
             const shown = clip(command, 120);
+            const lowered = requested !== undefined && requested > maxMs
+                ? `\n[timeout ${requested} ms is over the deployment maximum; it was lowered to ${maxMs} ms.]`
+                : "";
+            const text = formatExec(r, seconds, clamped) + lowered;
             return {
-                content: [{ type: "text", text: withNotices(notices, formatExec(r, seconds, clamped)) }],
+                content: [{ type: "text", text: withNotices(notices, text) }],
                 isError: r.timedOut || r.exitCode === null,
                 // display only: a non-zero exit shows as failed on the row, `isError` stays as it was
                 view: {

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

@@ -1,4 +1,7 @@
-import { type SandboxHandle, type SandboxProvider } from "@capybara-hq/plugin-sdk";
+import { type SandboxHandle, type SandboxProvider, ToolError } from "@capybara-hq/plugin-sdk";
+import type { BackgroundTaskFinisher } from "../../../background/finish.js";
+import type { BackgroundTaskStopper } from "../../../background/stop.js";
+import type { BackgroundTaskStore } from "../../../background/store.js";
 import type { KernelConfig } from "../../../config/schema.js";
 import type { AttachmentsService } from "../../../conversations/attachments.service.js";
 import type { EventLog } from "../../../conversations/event-log.js";
@@ -8,12 +11,26 @@ 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">>;
+    /**
+     * `pathLease` may be absent (test stubs): the kernel's own file writes then take no path lease.
+     * `currentInstance` too: a background `Bash` launch records the instance it started in; and
+     * `ifRunning`, which `TaskOutput` reads a task through.
+     */
+    sandbox: Pick<SandboxService, "available" | "withSandbox"> & Partial<Pick<SandboxService, "pathLease" | "currentInstance" | "ifRunning">>;
+    /** Background `Bash` tasks; absent in test stubs, where `run_in_background` is refused. */
+    background?: Pick<BackgroundTaskStore, "reserve" | "markStarted" | "failLaunch" | "finishStoppedLaunch" | "releaseStop" | "get" | "advanceOffset">;
+    /**
+     * What `TaskOutput` and `TaskStop` finish and stop tasks with; absent in test stubs, where both
+     * answer that background tasks are not available.
+     */
+    tasks?: {
+        finisher: Pick<BackgroundTaskFinisher, "finish">;
+        stopper: Pick<BackgroundTaskStopper, "stop">;
+    };
     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">>;
+    /** `publishChanged`: `Deliver` announces `changed: files` (UI refresh B). */
+    eventLog: Pick<EventLog, "append" | "latestFileState"> & Partial<Pick<EventLog, "publishChanged">>;
     config: Pick<KernelConfigService, "get">;
 }
 /** 回调拿到的沙箱：句柄、提供方与「调用 signal + 锁丢失」合并后的 signal（每个提供方调用都传它）。 */
@@ -31,6 +48,8 @@ export declare const SANDBOX_STARTED_NOTICE = "Sandbox started for this conversa
 export declare const SANDBOX_RECREATED_NOTICE = "Sandbox was recreated; previous files are gone.";
 /** 没有沙箱提供方时「工具不可用」的原因（进提醒，内核在后面补句号）：与调用时的错误同一句话。 */
 export declare const SANDBOX_UNAVAILABLE_REASON: string;
+/** The error of a sandbox call in a deployment without a sandbox provider. */
+export declare function noSandboxError(): ToolError;
 /** 沙箱里附件所在目录。 */
 export declare const ATTACHMENTS_DIR = "/workspace/attachments";
 /** 已同步附件的标记文件：`{ <附件 id>: <文件名> }`。 */
@@ -80,7 +99,7 @@ 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` 是技能文件的只读副本。 */
+/** A writing tool's `file_path`: `/skills` is the read-only copy of the skill files. */
 export declare function checkWritable(path: string): string;
 /** POSIX shell 单引号转义。 */
 export declare function shellQuote(s: string): string;
@@ -93,6 +112,8 @@ export declare function assignAttachmentNames(items: readonly {
     id: string;
     name: string;
 }[], used: ReadonlySet<string>): Map<string, string>;
+/** 沙箱服务的错误 → 给模型的可执行说明；其余原样抛出（管线按「工具失败」处理）。 */
+export declare function mapSandboxError(e: unknown): unknown;
 /**
  * 在本对话的沙箱上执行 `fn`（`SandboxService.withSandbox`：懒创建、恢复、重建）：先同步附件，
  * 再执行；返回结果与要加在结果开头的状态说明（首次使用 / 重建 / 新复制的附件）。
@@ -112,6 +133,8 @@ export declare const sandboxConversationOf: (ctx: BuiltinCallContext) => string;
  */
 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;
+export declare const unavailableWhenNoSandbox: (deps: Pick<SandboxToolDeps, "sandbox">) => (_ctx?: {
+    orgId: string;
+}) => string | null;
 /** 读出的字节是否像二进制（开头 8 KB 里有 NUL）。 */
 export declare function looksBinary(data: Uint8Array): boolean;

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

@@ -12,6 +12,10 @@ const BUSY_TEXT = "The sandbox is busy with another command in this conversation
 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);
+/** The error of a sandbox call in a deployment without a sandbox provider. */
+export function noSandboxError() {
+    return new ToolError(NO_SANDBOX_TEXT);
+}
 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.";
 /** 沙箱里附件所在目录。 */
@@ -78,9 +82,9 @@ export function checkPath(path, field = "path") {
     }
     return path.length > 1 && path.endsWith("/") ? path.slice(0, -1) : path;
 }
-/** 写入类工具的路径：`/skills` 是技能文件的只读副本。 */
+/** A writing tool's `file_path`: `/skills` is the read-only copy of the skill files. */
 export function checkWritable(path) {
-    const p = checkPath(path);
+    const p = checkPath(path, "file_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.`);
     }
@@ -235,7 +239,7 @@ async function copyAttachments(deps, ctx, s, reset, conv, list) {
     return { copied, failures };
 }
 /** 沙箱服务的错误 → 给模型的可执行说明；其余原样抛出（管线按「工具失败」处理）。 */
-function mapError(e) {
+export function mapSandboxError(e) {
     if (e instanceof ApiError) {
         if (e.code === "sandbox.busy")
             return new ToolError(BUSY_TEXT);
@@ -276,7 +280,7 @@ export async function inSandbox(deps, ctx, fn) {
         }, ctx.signal);
     }
     catch (e) {
-        throw mapError(e);
+        throw mapSandboxError(e);
     }
 }
 /** The conversation whose sandbox a call uses (the parent's for a sub-agent). */
@@ -299,7 +303,7 @@ export async function withPathLease(deps, ctx, path, signal, fn) {
     }
 }
 /** 本部署是否有沙箱：没有时返回「不可用」原因（注册表据此把沙箱工具报为不可用）。 */
-export const unavailableWhenNoSandbox = (deps) => () => deps.sandbox.available ? null : SANDBOX_UNAVAILABLE_REASON;
+export const unavailableWhenNoSandbox = (deps) => (_ctx) => 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

@@ -1,5 +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`，用户可下载。 */
+/** 内置工具 `Deliver`：把沙箱里的文件存进对象存储，写 `artifact_created`，用户可下载。 */
 export declare function sandboxDeliverTool(deps: SandboxToolDeps): BuiltinTool;

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

@@ -4,18 +4,18 @@ import { isValidArtifactName } from "../../../conversations/events.js";
 import { ApiError } from "../../../errors.js";
 import { checkPath, clip, display, inSandbox, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, withNotices, } from "./common.js";
 const SPEC = {
-    name: "sandbox_deliver",
+    name: "Deliver",
     // Display only (the tool row; not in the fingerprint, never sent to the model).
-    keyArgs: ["path"],
+    keyArgs: ["file_path"],
     description: "Deliver a file from this conversation's sandbox to the user as a downloadable artifact. Use " +
         "it when the user should receive a file you produced (a report, chart, spreadsheet, archive " +
         "and so on); files that stay in the sandbox are not visible to the user. Delivers one file " +
-        "per call; archive a directory first (e.g. zip -r with sandbox_bash). The file size is " +
+        "per call; archive a directory first (e.g. tar -czf with Bash). The file size is " +
         "limited (100 MB by default). Do not use it for intermediate files the user does not need.",
     inputSchema: {
         type: "object",
         properties: {
-            path: {
+            file_path: {
                 type: "string",
                 minLength: 1,
                 description: 'Absolute path of the file in the sandbox, e.g. "/workspace/out/report.pdf".',
@@ -24,10 +24,10 @@ const SPEC = {
                 type: "string",
                 minLength: 1,
                 maxLength: MEDIA_NAME_MAX_CHARS,
-                description: 'File name shown to the user, e.g. "Q3 report.pdf". Default: the file name in path.',
+                description: 'File name shown to the user, e.g. "Q3 report.pdf". Default: the file name in file_path.',
             },
         },
-        required: ["path"],
+        required: ["file_path"],
         additionalProperties: false,
     },
 };
@@ -71,9 +71,9 @@ export function contentTypeFor(name) {
     const ext = dot > 0 ? name.slice(dot + 1).toLowerCase() : "";
     return CONTENT_TYPES[ext] ?? "application/octet-stream";
 }
-const notFound = (path) => `File not found: ${clip(path, 200)}. Check the path with sandbox_glob.`;
-const isDirectory = (path) => `${clip(path, 200)} is a directory; deliver one file, e.g. archive the directory first with sandbox_bash (zip -r) and retry.`;
-const tooLarge = (path, size, max) => `File ${clip(path, 200)} is ${size} bytes, over the delivery limit of ${max} bytes; compress or split it with sandbox_bash and retry.`;
+const notFound = (path) => `File not found: ${clip(path, 200)}. Check the path with Glob.`;
+const isDirectory = (path) => `${clip(path, 200)} is a directory; deliver one file, e.g. archive the directory first with Bash (tar -czf) and retry.`;
+const tooLarge = (path, size, max) => `File ${clip(path, 200)} is ${size} bytes, over the delivery limit of ${max} bytes; compress or split it with Bash and retry.`;
 const BAD_NAME = "name must not contain control characters, / or \\; pass a plain file name such as report.pdf.";
 /** 默认产物名：路径的文件名部分，过长时保留末尾（扩展名）截到 255 个 UTF-16 单元以内。 */
 function defaultName(path) {
@@ -90,19 +90,19 @@ function defaultName(path) {
 const NO_STORAGE = "File storage is not configured in this deployment, so files cannot be delivered; ask an administrator, or provide the result in your reply instead.";
 /** 「工具不可用」提醒里的原因（内核在后面补句号）。 */
 const NO_STORAGE_REASON = NO_STORAGE.slice(0, -1);
-/** 内置工具 `sandbox_deliver`：把沙箱里的文件存进对象存储，写 `artifact_created`，用户可下载。 */
+/** 内置工具 `Deliver`：把沙箱里的文件存进对象存储，写 `artifact_created`，用户可下载。 */
 export function sandboxDeliverTool(deps) {
     return {
         spec: SPEC,
         defaultPolicy: "allow",
         // 没有沙箱或没有对象存储都交付不了（先报沙箱的原因）
-        unavailable: () => unavailableWhenNoSandbox(deps)() ?? (deps.storage.available ? null : NO_STORAGE_REASON),
+        unavailable: (ctx) => unavailableWhenNoSandbox(deps)(ctx) ?? (deps.storage.available ? null : NO_STORAGE_REASON),
         timeoutMs: () => 2 * sandboxBaseTimeoutMs(deps.config.get()),
         async run(input, ctx) {
             // 存储在调用前就核对：不为一个交付不了的文件去 stat / 读沙箱
             if (!deps.storage.available)
                 throw new ToolError(NO_STORAGE);
-            const path = checkPath(input.path);
+            const path = checkPath(input.file_path, "file_path");
             const given = input.name?.trim();
             // 与 artifact_created 的 schema 同一规则，在上传前检查（不合法的名字不会在写事件时才失败）
             if (given !== undefined && (!isValidArtifactName(given) || /[/\\]/.test(given))) {

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

@@ -1,4 +1,4 @@
 import type { BuiltinTool } from "../../registry.js";
 import { type SandboxToolDeps } from "./common.js";
-/** 内置工具 `sandbox_edit`：按精确文本替换。 */
+/** 内置工具 `Edit`：按精确文本替换。 */
 export declare function sandboxEditTool(deps: SandboxToolDeps): BuiltinTool;