@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.11

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

@@ -1,23 +1,73 @@
-import { isSandboxGoneError, ToolError, validateSandboxPath, } from "@capybara-hq/plugin-sdk";
+import { DEFAULT_SANDBOX_ROOTS, DeviceProtocolError, isFileSystemGoneError, isSandboxGoneError, ToolError, validateSandboxPath, validateSandboxPathShape, } from "@capybara-hq/plugin-sdk";
+import { ANONYMOUS_NO_ENVIRONMENT, } from "../../../environments/conversation-environments.js";
 import { ApiError } from "../../../errors.js";
+import { environmentPathsChange } from "../../../runtime/context/environment-paths.js";
 import { SandboxPathBusyError } from "../../../sandbox/leases.js";
-import { SandboxLockLostError } from "../../../sandbox/sandbox.service.js";
+import { SandboxLockLostError, } from "../../../sandbox/sandbox.service.js";
+import { SandboxProviderUnreachableError } from "../../../sandbox/unreachable.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.";
+/** This conversation's first use of its environment (in the instance's workspace). */
+export const sandboxStartedNotice = (roots) => `Environment started (first use in this conversation); the working directory is ${roots.workspace}, shared with the environment's other conversations.`;
+/** {@link sandboxStartedNotice} of an instance with the default roots. */
+export const SANDBOX_STARTED_NOTICE = sandboxStartedNotice(DEFAULT_SANDBOX_ROOTS);
+/** A new instance came up on the environment's kept files. */
+export const SANDBOX_RESTARTED_NOTICE = "The environment's instance was restarted; files are kept, running processes are gone and temporary files may be gone.";
+/**
+ * The environment's files were reset (on request, or after they were lost) since this conversation
+ * last used it.
+ */
+export const sandboxFilesResetNotice = (roots) => `The environment's files were reset; earlier files in ${roots.workspace} and running processes are gone and temporary files may be gone, so recreate anything you still need.`;
+/** {@link sandboxFilesResetNotice} of an instance with the default roots. */
+export const SANDBOX_FILES_RESET_NOTICE = sandboxFilesResetNotice(DEFAULT_SANDBOX_ROOTS);
+const BUSY_TEXT = "The environment is busy: all its command slots are taken by commands of this or another conversation sharing it; wait for one 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.";
+/** 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 or another conversation in this environment is writing this file; wait a moment and retry.";
+const ANONYMOUS_TEXT = "The sandbox is not available to anonymous IM senders; do the task without the sandbox, or ask the person to link their account and start a new conversation.";
+const ENV_NOT_FOUND_TEXT = "This conversation's environment was deleted or its owner can no longer use it; ask the user to start a new conversation in another environment.";
+const ENV_FORBIDDEN_TEXT = "This conversation's owner may no longer use its environment; ask the user to start a new conversation in an environment they can use.";
+const ENV_UNAVAILABLE_TEXT = "This conversation's environment is kept by a sandbox provider that is not active in this deployment; ask the user to start a new conversation in another environment, or an administrator to re-enable that provider.";
+const ENV_FILES_LOST_TEXT = "This environment's files are gone. Ask the user to reset its files on the environments page, then retry.";
+/**
+ * A provider call that never connected (refused, unknown host, unreachable network): the request
+ * did not reach the provider, so the call did nothing in the sandbox.
+ */
+export const SANDBOX_UNREACHABLE_TEXT = "The sandbox provider can't be reached (the connection failed), so this call did nothing in the sandbox; retrying won't help until a super admin checks the sandbox extension's configuration (Admin console → Extensions). Continue without the sandbox, or ask the person to have a super admin check it.";
+/** A provider connection that broke during the call: the provider may have acted before it broke. */
+export const SANDBOX_CONNECTION_DROPPED_TEXT = "The connection to the sandbox provider broke during this call, so it may or may not have taken effect; check the sandbox state before retrying. If it fails again, continue without the sandbox and ask the person to have a super admin check the sandbox extension's configuration (Admin console → Extensions).";
+const DEVICE_FILES_LOST_TEXT = "This environment's directory is gone from its connected machine. Ask the person to run capybara-device logout, then capybara-device login into this environment, on that machine, then retry.";
+const FILES_GONE_TEXT = "This environment's files are gone. Ask the user to reset its files on the environments page (for a connected machine: to run capybara-device logout, then capybara-device login, on it), then retry.";
+const DEVICE_OFFLINE_TEXT = "The connected machine is offline. Ask the person to start capybara-device on it.";
+const DEVICE_OUTDATED_TEXT = "The connected machine runs an outdated capybara-device. Ask the person to update it on that machine and start it again.";
+const DEVICE_REVOKED_TEXT = "The connected machine of this environment was disconnected. Ask the person to run capybara-device logout, then capybara-device login on it, or to start a new conversation in another environment.";
+const deviceProtocolText = (detail) => `The connected machine sent an answer the platform cannot read (${detail}). Ask the person to update capybara-device on that machine, then 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`;
+/** The directory of attachments in the environment (each conversation has a subdirectory). */
+export const attachmentsRoot = (roots) => `${roots.workspace}/attachments`;
+/** {@link attachmentsRoot} of an instance with the default roots. */
+export const ATTACHMENTS_ROOT = attachmentsRoot(DEFAULT_SANDBOX_ROOTS);
+/**
+ * One conversation's attachment directory: the first 12 hex digits of the root conversation's
+ * UUID, so conversations sharing an environment do not overwrite each other's files.
+ */
+export const attachmentsDir = (roots, rootConversationId) => `${attachmentsRoot(roots)}/${rootConversationId.replaceAll("-", "").slice(0, 12)}`;
+/** The conversation's marker of synced attachments: `{ <attachment id>: <file name> }`. */
+export const syncMarkerPath = (roots, rootConversationId) => `${attachmentsDir(roots, rootConversationId)}/.capybara-sync.json`;
+const SYNC_MARKER_NAME = ".capybara-sync.json";
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/**
+ * Whether a path, or a Grep output line starting with one, belongs to a sync marker of the
+ * instance with `roots` (hidden from Glob / Grep). Build it once per call and test every entry.
+ */
+export function syncMarkerMatcher(roots = DEFAULT_SANDBOX_ROOTS) {
+    const re = new RegExp(`^${escapeRe(attachmentsRoot(roots))}/[^/]+/${escapeRe(SYNC_MARKER_NAME)}(?=$|[:-])`);
+    return (pathOrLine) => re.test(pathOrLine);
+}
 const MARKER_MAX_BYTES = 1024 * 1024;
 /** 附件文件名的上限（UTF-8 字节，常见文件系统单个文件名上限 255 字节，留出 `-N` 后缀的余量）。 */
 export const ATTACHMENT_NAME_MAX_BYTES = 200;
@@ -70,19 +120,34 @@ export function clip(s, max) {
 export function withNotices(notices, text) {
     return [...notices, text].join("\n\n");
 }
-/** 校验沙箱内路径（`validateSandboxPath`）；不合法抛给模型可执行的错误。 */
-export function checkPath(path, field = "path") {
-    const errors = validateSandboxPath(path);
+/**
+ * The root-independent checks of a path (`validateSandboxPathShape`: non-empty, absolute, no
+ * control characters, no empty or `..` segments), run before the call enters its environment, so
+ * a malformed path never creates or resumes an instance; root membership is checked inside
+ * ({@link checkPath}).
+ */
+export function checkPathShape(path, field = "path") {
+    const errors = validateSandboxPathShape(path);
     if (errors.length > 0) {
-        throw new ToolError(`Invalid ${field} "${clip(path, 200)}": ${errors.join("; ")}. Pass an absolute path under /workspace, /skills or /tmp.`);
+        throw new ToolError(`Invalid ${field} "${clip(path, 200)}": ${errors.join("; ")}. Pass an absolute path under the workspace, skills or temporary files directory.`);
+    }
+}
+/**
+ * Checks a path inside the instance with `roots` (`validateSandboxPath`: absolute, under one of its
+ * roots); an invalid one throws an error the model can act on, naming the instance's roots.
+ */
+export function checkPath(path, roots, field = "path") {
+    const errors = validateSandboxPath(path, roots);
+    if (errors.length > 0) {
+        throw new ToolError(`Invalid ${field} "${clip(path, 200)}": ${errors.join("; ")}. Pass an absolute path under ${roots.workspace}, ${roots.skills} or ${roots.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.`);
+/** A writing tool's `file_path`: the skills root is the read-only copy of the skill files. */
+export function checkWritable(path, roots) {
+    const p = checkPath(path, roots, "file_path");
+    if (p === roots.skills || p.startsWith(`${roots.skills}/`)) {
+        throw new ToolError(`Path ${clip(p, 200)} is read-only (${roots.skills} holds skill files); pass a path under ${roots.workspace} or ${roots.tmp} instead.`);
     }
     return p;
 }
@@ -129,11 +194,11 @@ function sanitizeName(raw) {
  */
 export function assignAttachmentNames(items, used) {
     const taken = new Set(used);
-    taken.add(SYNC_MARKER.slice(ATTACHMENTS_DIR.length + 1));
+    taken.add(SYNC_MARKER_NAME);
     const out = new Map();
     for (const a of items) {
         let base = sanitizeName(a.name);
-        if (validateSandboxPath(`${ATTACHMENTS_DIR}/${base}`).length > 0) {
+        if (validateSandboxPath(`${ATTACHMENTS_ROOT}/${base}`).length > 0) {
             base = `attachment-${a.id.slice(0, 8)}`;
         }
         let name = base;
@@ -167,35 +232,36 @@ function copyFailureReason(e) {
     return "a temporary error occurred; it will be retried on the next sandbox call";
 }
 /**
- * 把本对话已 ready 的附件复制到 `/workspace/attachments/<name>`，标记文件记下已复制的（不重复复制）。
- * `reset`（新建 / 重建的沙箱，文件已不在）时忽略标记文件全部重新复制。对象已不在的附件跳过（下次再试）。
+ * 把本对话已 ready 的附件复制到 `<workspace>/attachments/<conversation>/<name>`（{@link attachmentsDir}），
+ * 标记文件记下已复制的（不重复复制）。对象已不在的附件跳过（下次再试）。
  * 每复制一个就更新标记文件：中途超时 / 中止，下次从停下的地方继续。
  * 单个附件失败（存储故障等）只跳过它并给出说明，不让工具调用失败；signal 已中止或实例已不在时照常抛出。
  * 返回本次复制的沙箱路径与失败说明。
  */
-async function syncAttachments(deps, ctx, s, reset) {
+async function syncAttachments(deps, ctx, s) {
     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;
-    }
+    const marker = await readSyncMarker(s, conv);
+    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));
+    return withPathLease(deps, s, syncMarkerPath(s.roots, conv), s.signal, (signal) => copyAttachments(deps, ctx, { ...s, signal }, 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 });
+async function readSyncMarker(s, conv) {
+    const m = await s.p.readFile(s.h, syncMarkerPath(s.roots, conv), {
+        maxBytes: MARKER_MAX_BYTES,
+        signal: s.signal,
+    });
     return m && !m.truncated ? parseMarker(m.data) : {};
 }
-async function copyAttachments(deps, ctx, s, reset, conv, list) {
+async function copyAttachments(deps, ctx, s, conv, list) {
     const none = { copied: [], failures: [] };
-    let marker = reset ? {} : await readSyncMarker(s);
+    let marker = await readSyncMarker(s, conv);
     const pending = list.filter((a) => !Object.hasOwn(marker, a.id));
     if (pending.length === 0)
         return none;
@@ -204,7 +270,7 @@ async function copyAttachments(deps, ctx, s, reset, conv, list) {
     const failures = [];
     for (const a of pending) {
         const name = names.get(a.id);
-        const path = `${ATTACHMENTS_DIR}/${name}`;
+        const path = `${attachmentsDir(s.roots, conv)}/${name}`;
         try {
             const opened = await deps.attachments.openForConversation(ctx.orgId, conv, a.id);
             if (!opened)
@@ -224,7 +290,7 @@ async function copyAttachments(deps, ctx, s, reset, conv, list) {
         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);
+            await s.p.writeFile(s.h, syncMarkerPath(s.roots, conv), utf8.encode(JSON.stringify(next)), s.signal);
             marker = next;
         }
         catch (e) {
@@ -234,14 +300,55 @@ async function copyAttachments(deps, ctx, s, reset, conv, list) {
     }
     return { copied, failures };
 }
-/** 沙箱服务的错误 → 给模型的可执行说明；其余原样抛出（管线按「工具失败」处理）。 */
-function mapError(e) {
+/**
+ * Sandbox service errors → actionable text for the model; anything else is returned unchanged
+ * (the pipeline reports a generic tool failure). A provider that cannot be reached becomes a
+ * fixed text (providers never write model-visible text) with `kind: "unavailable"`, and its raw
+ * error is logged to `log` as a warning (the pipeline logs only errors it did not get as a
+ * `ToolError`).
+ */
+export function mapSandboxError(e, log) {
+    if (e instanceof SandboxProviderUnreachableError) {
+        log?.warn("sandbox provider unreachable", { failure: e.failure, err: e.cause });
+        if (e.failure === "connect") {
+            return new ToolError(SANDBOX_UNREACHABLE_TEXT, { kind: "unavailable" });
+        }
+        return new ToolError(SANDBOX_CONNECTION_DROPPED_TEXT, { kind: "unavailable" });
+    }
     if (e instanceof ApiError) {
         if (e.code === "sandbox.busy")
             return new ToolError(BUSY_TEXT);
-        if (e.code === "sandbox.unavailable")
+        if (e.code === "sandbox.unavailable") {
+            const reason = e.details?.[0]?.reason;
+            if (reason === ANONYMOUS_NO_ENVIRONMENT)
+                return new ToolError(ANONYMOUS_TEXT);
             return new ToolError(NO_SANDBOX_TEXT);
+        }
+        const detail = e.details?.[0];
+        if (e.code === "environment.not_found")
+            return new ToolError(ENV_NOT_FOUND_TEXT);
+        if (e.code === "environment.forbidden" && detail?.reason === "machine_revoked") {
+            return new ToolError(DEVICE_REVOKED_TEXT);
+        }
+        if (e.code === "environment.forbidden")
+            return new ToolError(ENV_FORBIDDEN_TEXT);
+        if (e.code === "environment.unavailable")
+            return new ToolError(ENV_UNAVAILABLE_TEXT);
+        if (e.code === "environment.files_lost" && detail?.source === "device") {
+            return new ToolError(DEVICE_FILES_LOST_TEXT);
+        }
+        if (e.code === "environment.files_lost")
+            return new ToolError(ENV_FILES_LOST_TEXT);
+        if (e.code === "environment.offline")
+            return new ToolError(DEVICE_OFFLINE_TEXT);
+        if (e.code === "environment.program_outdated")
+            return new ToolError(DEVICE_OUTDATED_TEXT);
     }
+    // an operation outside withSandbox's own mapping (it records lost files itself)
+    if (isFileSystemGoneError(e))
+        return new ToolError(FILES_GONE_TEXT);
+    if (e instanceof DeviceProtocolError)
+        return new ToolError(deviceProtocolText(e.message));
     if (e instanceof SandboxLockLostError)
         return new ToolError(LOCK_LOST_TEXT);
     if (e instanceof SandboxPathBusyError)
@@ -249,25 +356,35 @@ function mapError(e) {
     return e;
 }
 /**
- * 在本对话的沙箱上执行 `fn`（`SandboxService.withSandbox`：懒创建、恢复、重建）：先同步附件，
- * 再执行；返回结果与要加在结果开头的状态说明（首次使用 / 重建 / 新复制的附件）。
- * `withSandbox` 遇到实例不在时会重建并再调用一次回调，说明按最后一次调用的为准。
+ * Runs `fn` in the environment of the call's conversation (a sub-agent: its root's): resolves and
+ * checks the environment for the conversation's owner (binding an unbound conversation to the
+ * owner's default first), then `SandboxService.withSandbox` (the instance created, resumed or
+ * rebuilt on the kept files as needed, every `exec` carrying the call's actor). Attachments are
+ * synced first. Returns the value and the notices to put before the result (first use, a new
+ * instance, newly copied attachments). When `withSandbox` rebuilds a gone instance and calls
+ * `fn` again, the notices are the last call's. The instance's roots are recorded for the model
+ * on the conversation's first call and whenever they change ({@link recordEnvironmentPaths}).
  */
 export async function inSandbox(deps, ctx, fn) {
     try {
+        const environmentId = await deps.environments.forTool(ctx.orgId, sandboxConversationOf(ctx));
         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)
+            environmentId,
+            // a sub-agent is told when another holder rebuilt the shared instance (final review m5)
             holderConversationId: ctx.conversationId,
+            actor: { accountId: ctx.accountId, conversationId: ctx.conversationId },
         }, async (h, p, info, signal) => {
-            const s = { h, p, signal, reset: info.fresh || info.recreated };
+            const s = { environmentId, h, roots: info.roots, p, signal };
+            await recordEnvironmentPaths(deps, ctx, info.roots);
             const notices = [];
-            if (info.recreated)
-                notices.push(SANDBOX_RECREATED_NOTICE);
+            if (info.filesReset)
+                notices.push(sandboxFilesResetNotice(info.roots));
+            else if (info.restarted)
+                notices.push(SANDBOX_RESTARTED_NOTICE);
             else if (info.fresh)
-                notices.push(SANDBOX_STARTED_NOTICE);
-            const { copied, failures } = await syncAttachments(deps, ctx, s, s.reset);
+                notices.push(sandboxStartedNotice(info.roots));
+            const { copied, failures } = await syncAttachments(deps, ctx, s);
             if (copied.length > 0) {
                 notices.push(`Attachments copied into the sandbox: ${copied.join(", ")}.`);
             }
@@ -276,21 +393,37 @@ export async function inSandbox(deps, ctx, fn) {
         }, ctx.signal);
     }
     catch (e) {
-        throw mapError(e);
+        throw mapSandboxError(e, deps.log);
     }
 }
-/** The conversation whose sandbox a call uses (the parent's for a sub-agent). */
+/**
+ * Environments spec §13.1, ruling R22: the calling conversation's log (the log its model reads; a
+ * sub-agent's own too) gets an `environment_paths` event on its first sandbox call, the default
+ * roots included, and again whenever the held instance's roots differ from the latest recorded
+ * ones; always before the call's result. One indexed read per call (migration 0094); parallel
+ * calls that saw the same latest event write one event (its idempotency key).
+ */
+async function recordEnvironmentPaths(deps, ctx, roots) {
+    if (!deps.eventLog.latestOfType)
+        return;
+    const latest = await deps.eventLog.latestOfType(ctx.conversationId, "environment_paths");
+    const change = environmentPathsChange(latest, roots, ctx.runId);
+    if (change)
+        await deps.eventLog.append(ctx.conversationId, [change]);
+}
+/** The conversation whose environment a call uses (the root conversation'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`.
+ * Runs `fn` under the per-path lease of `path` in the session's environment (spec §10.4: the
+ * kernel's own read-modify-write of one file never loses another holder's update, from any
+ * conversation sharing the environment). `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) {
+export async function withPathLease(deps, s, path, signal, fn) {
     if (!deps.sandbox.pathLease)
         return fn(signal);
-    const lease = await deps.sandbox.pathLease(sandboxConversationOf(ctx), path, signal);
+    const lease = await deps.sandbox.pathLease(s.environmentId, path, signal);
     try {
         return await fn(AbortSignal.any([signal, lease.signal]));
     }
@@ -298,8 +431,35 @@ export async function withPathLease(deps, ctx, path, signal, fn) {
         await lease.release().catch(() => { });
     }
 }
-/** 本部署是否有沙箱：没有时返回「不可用」原因（注册表据此把沙箱工具报为不可用）。 */
-export const unavailableWhenNoSandbox = (deps) => () => deps.sandbox.available ? null : SANDBOX_UNAVAILABLE_REASON;
+/**
+ * Whether a sandbox tool call of the conversation tree rooted at `conversationId` can run: a
+ * cloud provider is loaded, or (ruling R8) the conversation's environment runs on a registered
+ * kernel provider (`@device`). Without a conversation only the cloud provider counts.
+ */
+export async function sandboxUsable(deps, orgId, conversationId) {
+    if (deps.sandbox.cloudAvailable)
+        return true;
+    if (conversationId === undefined || !deps.environments.usableNow)
+        return false;
+    return deps.environments.usableNow(orgId, conversationId);
+}
+/**
+ * The reason the registry reports the sandbox tools unavailable with, or null when they can run
+ * ({@link sandboxUsable}; the listing passes the root conversation of the run). An eval replay
+ * lists them as available (`replay`: its calls are never executed). `memo` (one per listing)
+ * makes every sandbox tool of a listing share one answer.
+ */
+export const unavailableWhenNoSandbox = (deps) => async (ctx) => {
+    if (ctx.replay === true)
+        return null;
+    const key = "sandboxUsable";
+    let usable = ctx.memo?.get(key);
+    if (usable === undefined) {
+        usable = sandboxUsable(deps, ctx.orgId, ctx.conversationId);
+        ctx.memo?.set(key, usable);
+    }
+    return (await usable) ? 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

@@ -2,32 +2,32 @@ import { randomUUID } from "node:crypto";
 import { ExtensionPointUnavailableError, MEDIA_NAME_MAX_CHARS, ToolError, } from "@capybara-hq/plugin-sdk";
 import { isValidArtifactName } from "../../../conversations/events.js";
 import { ApiError } from "../../../errors.js";
-import { checkPath, clip, display, inSandbox, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, withNotices, } from "./common.js";
+import { checkPath, checkPathShape, 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".',
+                description: "Absolute path of the file in the sandbox, e.g. out/report.pdf in the workspace directory.",
             },
             name: {
                 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,27 +90,29 @@ 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),
-        timeoutMs: () => 2 * sandboxBaseTimeoutMs(deps.config()),
+        unavailable: async (ctx) => (await 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 given = input.name?.trim();
             // 与 artifact_created 的 schema 同一规则，在上传前检查（不合法的名字不会在写事件时才失败）
             if (given !== undefined && (!isValidArtifactName(given) || /[/\\]/.test(given))) {
                 throw new ToolError(BAD_NAME);
             }
-            const name = given ?? defaultName(path);
-            const max = deps.config().sandbox.deliverMaxBytes;
-            const { value: data, notices } = await inSandbox(deps, ctx, async ({ h, p, signal }) => {
+            const max = deps.config.get().sandbox.deliverMaxBytes;
+            checkPathShape(input.file_path, "file_path");
+            let path = "";
+            const { value: data, notices } = await inSandbox(deps, ctx, async ({ h, roots, p, signal }) => {
+                path = checkPath(input.file_path, roots, "file_path");
                 const st = await p.stat(h, path, signal);
                 if (st === null)
                     throw new ToolError(notFound(path));
@@ -126,6 +128,7 @@ export function sandboxDeliverTool(deps) {
                     throw new ToolError(tooLarge(path, max + 1, max));
                 return got.data;
             });
+            const name = given ?? defaultName(path);
             // 上传在沙箱锁之外进行：不占着沙箱
             const artifactId = randomUUID();
             const objectKey = `artifacts/${ctx.conversationId}/${artifactId}`;

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;