@capybara-hq/kernel 0.1.0-rc.8 → 0.1.0-rc.9

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

@@ -1,4 +1,4 @@
-import { type SandboxHandle, ToolError } from "@capybara-hq/plugin-sdk";
+import { type SandboxHandle, type SandboxRoots, 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";
@@ -9,7 +9,7 @@ import { type ConversationEnvironments } from "../../../environments/conversatio
 import type { KernelConfigService } from "../../../infra/config/kernel-config.service.js";
 import { type HeldProvider, type SandboxService } from "../../../sandbox/sandbox.service.js";
 import type { StorageService } from "../../../storage/storage.service.js";
-import type { BuiltinCallContext } from "../../registry.js";
+import type { BuiltinCallContext, ToolListingScope } from "../../registry.js";
 /** 沙箱工具的依赖（都按调用时取，多副本下无进程内状态）。 */
 export interface SandboxToolDeps {
     /**
@@ -17,9 +17,13 @@ export interface SandboxToolDeps {
      * `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">>;
-    /** The environment a call enters: the root conversation's, checked for its owner every call. */
-    environments: Pick<ConversationEnvironments, "forTool">;
+    sandbox: Pick<SandboxService, "cloudAvailable" | "availableFor" | "withSandbox"> & Partial<Pick<SandboxService, "pathLease" | "currentInstance" | "ifRunning">>;
+    /**
+     * The environment a call enters: the root conversation's, checked for its owner every call.
+     * `usableNow` (absent in test stubs: only the cloud provider counts) tells a listing whether a
+     * conversation's environment can run without a cloud provider (ruling R8).
+     */
+    environments: Pick<ConversationEnvironments, "forTool"> & Partial<Pick<ConversationEnvironments, "usableNow">>;
     /** Background `Bash` tasks; absent in test stubs, where `run_in_background` is refused. */
     background?: Pick<BackgroundTaskStore, "reserve" | "markStarted" | "failLaunch" | "finishStoppedLaunch" | "releaseStop" | "get" | "advanceOffset">;
     /**
@@ -32,8 +36,11 @@ export interface SandboxToolDeps {
     };
     attachments: Pick<AttachmentsService, "listForConversation" | "openForConversation">;
     storage: Pick<StorageService, "kernel" | "deployment" | "available">;
-    /** `publishChanged`: `Deliver` announces `changed: files` (UI refresh B). */
-    eventLog: Pick<EventLog, "append" | "latestFileState"> & Partial<Pick<EventLog, "publishChanged">>;
+    /**
+     * `publishChanged`: `Deliver` announces `changed: files` (UI refresh B). `latestOfType` reads the
+     * conversation's latest `environment_paths` (absent in test stubs, which record none).
+     */
+    eventLog: Pick<EventLog, "append" | "latestFileState"> & Partial<Pick<EventLog, "publishChanged" | "latestOfType">>;
     config: Pick<KernelConfigService, "get">;
 }
 /**
@@ -45,29 +52,37 @@ export interface SandboxSession {
     /** The environment the call runs in (path leases are taken on it). */
     environmentId: string;
     h: SandboxHandle;
+    /** The instance's roots: every path the call builds or checks is under one of them. */
+    roots: SandboxRoots;
     p: HeldProvider;
     signal: AbortSignal;
 }
-/** 没有沙箱提供方时「工具不可用」的原因（进提醒与调用结果）。 */
-/** This conversation's first use of its environment. */
-export declare const SANDBOX_STARTED_NOTICE = "Environment started (first use in this conversation); the working directory is /workspace, shared with the environment's other conversations.";
+/** This conversation's first use of its environment (in the instance's workspace). */
+export declare const sandboxStartedNotice: (roots: SandboxRoots) => string;
+/** {@link sandboxStartedNotice} of an instance with the default roots. */
+export declare const SANDBOX_STARTED_NOTICE: string;
 /** A new instance came up on the environment's kept files. */
-export declare const SANDBOX_RESTARTED_NOTICE = "The environment's instance was restarted; files are kept, running processes and /tmp are gone.";
+export declare const SANDBOX_RESTARTED_NOTICE = "The environment's instance was restarted; files are kept, running processes are gone and temporary files may be 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;
 /** The directory of attachments in the environment (each conversation has a subdirectory). */
-export declare const ATTACHMENTS_ROOT = "/workspace/attachments";
+export declare const attachmentsRoot: (roots: SandboxRoots) => string;
+/** {@link attachmentsRoot} of an instance with the default roots. */
+export declare const ATTACHMENTS_ROOT: string;
 /**
  * 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 declare const attachmentsDir: (rootConversationId: string) => string;
+export declare const attachmentsDir: (roots: SandboxRoots, rootConversationId: string) => string;
 /** The conversation's marker of synced attachments: `{ <attachment id>: <file name> }`. */
-export declare const syncMarkerPath: (rootConversationId: string) => string;
-/** Whether a path, or a Grep output line starting with one, belongs to a sync marker (hidden from Glob / Grep). */
-export declare const isSyncMarkerEntry: (pathOrLine: string) => boolean;
+export declare const syncMarkerPath: (roots: SandboxRoots, rootConversationId: string) => string;
+/**
+ * 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 declare function syncMarkerMatcher(roots?: SandboxRoots): (pathOrLine: string) => boolean;
 /** 附件文件名的上限（UTF-8 字节，常见文件系统单个文件名上限 255 字节，留出 `-N` 后缀的余量）。 */
 export declare const ATTACHMENT_NAME_MAX_BYTES = 200;
 /**
@@ -111,10 +126,20 @@ export declare function display(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;
-/** A writing tool's `file_path`: `/skills` is the read-only copy of the skill files. */
-export declare function checkWritable(path: string): string;
+/**
+ * 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 declare function checkPathShape(path: string, field?: string): void;
+/**
+ * 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 declare function checkPath(path: string, roots: SandboxRoots, field?: string): string;
+/** A writing tool's `file_path`: the skills root is the read-only copy of the skill files. */
+export declare function checkWritable(path: string, roots: SandboxRoots): string;
 /** POSIX shell 单引号转义。 */
 export declare function shellQuote(s: string): string;
 /**
@@ -135,7 +160,8 @@ export declare function mapSandboxError(e: unknown): unknown;
  * 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.
+ * `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 declare function inSandbox<T>(deps: SandboxToolDeps, ctx: BuiltinCallContext, fn: (s: SandboxSession) => Promise<T>): Promise<{
     value: T;
@@ -151,9 +177,18 @@ export declare const sandboxConversationOf: (ctx: BuiltinCallContext) => string;
  * stubs) it just runs `fn` with `signal`.
  */
 export declare function withPathLease<T>(deps: Pick<SandboxToolDeps, "sandbox">, s: Pick<SandboxSession, "environmentId">, path: string, signal: AbortSignal, fn: (signal: AbortSignal) => Promise<T>): Promise<T>;
-/** 本部署是否有沙箱：没有时返回「不可用」原因（注册表据此把沙箱工具报为不可用）。 */
-export declare const unavailableWhenNoSandbox: (deps: Pick<SandboxToolDeps, "sandbox">) => (_ctx?: {
-    orgId: string;
-}) => string | null;
+/**
+ * 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 declare function sandboxUsable(deps: Pick<SandboxToolDeps, "sandbox" | "environments">, orgId: string, conversationId: string | undefined): Promise<boolean>;
+/**
+ * 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 declare const unavailableWhenNoSandbox: (deps: Pick<SandboxToolDeps, "sandbox" | "environments">) => (ctx: ToolListingScope) => Promise<string | null>;
 /** 读出的字节是否像二进制（开头 8 KB 里有 NUL）。 */
 export declare function looksBinary(data: Uint8Array): boolean;

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

@@ -1,14 +1,16 @@
-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";
 // ---- 模型可见文案（英文） ----
-/** 没有沙箱提供方时「工具不可用」的原因（进提醒与调用结果）。 */
-/** This conversation's first use of its environment. */
-export const SANDBOX_STARTED_NOTICE = "Environment started (first use in this conversation); the working directory is /workspace, shared with the environment's other conversations.";
+/** 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 and /tmp are gone.";
+export const SANDBOX_RESTARTED_NOTICE = "The environment's instance was restarted; files are kept, running processes are gone and temporary files may be gone.";
 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.";
 /** 没有沙箱提供方时「工具不可用」的原因（进提醒，内核在后面补句号）：与调用时的错误同一句话。 */
@@ -23,20 +25,34 @@ const ENV_NOT_FOUND_TEXT = "This conversation's environment was deleted or its o
 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.";
+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.";
 /** The directory of attachments in the environment (each conversation has a subdirectory). */
-export const ATTACHMENTS_ROOT = "/workspace/attachments";
+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 = (rootConversationId) => `${ATTACHMENTS_ROOT}/${rootConversationId.replaceAll("-", "").slice(0, 12)}`;
+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 = (rootConversationId) => `${attachmentsDir(rootConversationId)}/.capybara-sync.json`;
+export const syncMarkerPath = (roots, rootConversationId) => `${attachmentsDir(roots, rootConversationId)}/.capybara-sync.json`;
 const SYNC_MARKER_NAME = ".capybara-sync.json";
-const SYNC_MARKER_RE = new RegExp(`^${ATTACHMENTS_ROOT}/[^/]+/${SYNC_MARKER_NAME.replaceAll(".", "\\.")}(?=$|[:-])`);
-/** Whether a path, or a Grep output line starting with one, belongs to a sync marker (hidden from Glob / Grep). */
-export const isSyncMarkerEntry = (pathOrLine) => SYNC_MARKER_RE.test(pathOrLine);
+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;
@@ -89,19 +105,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;
 }
-/** A writing tool's `file_path`: `/skills` is the read-only copy of the skill files. */
-export function checkWritable(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.`);
+/** 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;
 }
@@ -186,7 +217,7 @@ function copyFailureReason(e) {
     return "a temporary error occurred; it will be retried on the next sandbox call";
 }
 /**
- * 把本对话已 ready 的附件复制到 `/workspace/attachments/<conversation>/<name>`（{@link attachmentsDir}），
+ * 把本对话已 ready 的附件复制到 `<workspace>/attachments/<conversation>/<name>`（{@link attachmentsDir}），
  * 标记文件记下已复制的（不重复复制）。对象已不在的附件跳过（下次再试）。
  * 每复制一个就更新标记文件：中途超时 / 中止，下次从停下的地方继续。
  * 单个附件失败（存储故障等）只跳过它并给出说明，不让工具调用失败；signal 已中止或实例已不在时照常抛出。
@@ -203,11 +234,11 @@ async function syncAttachments(deps, ctx, 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, s, syncMarkerPath(conv), s.signal, (signal) => copyAttachments(deps, ctx, { ...s, signal }, 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, conv) {
-    const m = await s.p.readFile(s.h, syncMarkerPath(conv), {
+    const m = await s.p.readFile(s.h, syncMarkerPath(s.roots, conv), {
         maxBytes: MARKER_MAX_BYTES,
         signal: s.signal,
     });
@@ -224,7 +255,7 @@ async function copyAttachments(deps, ctx, s, conv, list) {
     const failures = [];
     for (const a of pending) {
         const name = names.get(a.id);
-        const path = `${attachmentsDir(conv)}/${name}`;
+        const path = `${attachmentsDir(s.roots, conv)}/${name}`;
         try {
             const opened = await deps.attachments.openForConversation(ctx.orgId, conv, a.id);
             if (!opened)
@@ -244,7 +275,7 @@ async function copyAttachments(deps, ctx, s, conv, list) {
         copied.push(path);
         const next = { ...marker, [a.id]: name };
         try {
-            await s.p.writeFile(s.h, syncMarkerPath(conv), 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) {
@@ -265,15 +296,31 @@ export function mapSandboxError(e) {
                 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)
@@ -287,7 +334,8 @@ export function mapSandboxError(e) {
  * 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.
+ * `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 {
@@ -299,12 +347,13 @@ export async function inSandbox(deps, ctx, fn) {
             holderConversationId: ctx.conversationId,
             actor: { accountId: ctx.accountId, conversationId: ctx.conversationId },
         }, async (h, p, info, signal) => {
-            const s = { environmentId, h, p, signal };
+            const s = { environmentId, h, roots: info.roots, p, signal };
+            await recordEnvironmentPaths(deps, ctx, info.roots);
             const notices = [];
             if (info.restarted)
                 notices.push(SANDBOX_RESTARTED_NOTICE);
             else if (info.fresh)
-                notices.push(SANDBOX_STARTED_NOTICE);
+                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(", ")}.`);
@@ -317,6 +366,21 @@ export async function inSandbox(deps, ctx, fn) {
         throw mapSandboxError(e);
     }
 }
+/**
+ * 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;
 /**
@@ -337,8 +401,35 @@ export async function withPathLease(deps, s, path, signal, fn) {
         await lease.release().catch(() => { });
     }
 }
-/** 本部署是否有沙箱：没有时返回「不可用」原因（注册表据此把沙箱工具报为不可用）。 */
-export const unavailableWhenNoSandbox = (deps) => (_ctx) => 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.js

@@ -2,7 +2,7 @@ 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: "Deliver",
     // Display only (the tool row; not in the fingerprint, never sent to the model).
@@ -18,7 +18,7 @@ const SPEC = {
             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",
@@ -96,21 +96,23 @@ export function sandboxDeliverTool(deps) {
         spec: SPEC,
         defaultPolicy: "allow",
         // 没有沙箱或没有对象存储都交付不了（先报沙箱的原因）
-        unavailable: (ctx) => unavailableWhenNoSandbox(deps)(ctx) ?? (deps.storage.available ? null : NO_STORAGE_REASON),
+        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.file_path, "file_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.get().sandbox.deliverMaxBytes;
-            const { value: data, notices } = await inSandbox(deps, ctx, async ({ h, p, signal }) => {
+            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.js

@@ -1,6 +1,6 @@
 import { ToolError } from "@capybara-hq/plugin-sdk";
 import { lineDiff, viewPath } from "../../view.js";
-import { checkWritable, clip, display, inSandbox, looksBinary, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, withNotices, withPathLease, } from "./common.js";
+import { checkPathShape, checkWritable, clip, display, inSandbox, looksBinary, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, withNotices, withPathLease, } from "./common.js";
 import { assertReadAndUnchanged, fileStateOf, normalizeSandboxPath, recordedFile, } from "./file-state.js";
 import { READ_MAX_BYTES } from "./read.js";
 /** 可编辑的最大文件（字节）：更大的用 Bash 处理。 */
@@ -19,7 +19,7 @@ const SPEC = {
             file_path: {
                 type: "string",
                 minLength: 1,
-                description: 'Absolute path of the file, e.g. "/workspace/src/app.py".',
+                description: "Absolute path of the file, e.g. src/app.py in the workspace directory.",
             },
             old_string: { type: "string", minLength: 1, description: "The exact text to replace." },
             new_string: { type: "string", description: "The replacement text." },
@@ -53,43 +53,46 @@ export function sandboxEditTool(deps) {
         timeoutMs: () => sandboxBaseTimeoutMs(deps.config.get()),
         async run(input, ctx) {
             const { old_string, new_string, replace_all = false } = input;
-            const path = checkWritable(input.file_path);
             if (old_string === new_string)
                 throw new ToolError(SAME_TEXT);
-            const { value: edit, notices } = await inSandbox(deps, ctx, ({ environmentId, h, p, signal }) => 
-            // read, replace, write: one holder at a time per file
-            withPathLease(deps, { environmentId }, path, signal, async (signal) => {
-                const st = await p.stat(h, path, signal);
-                if (st === null)
-                    throw new ToolError(notFound(path));
-                if (st.isDir)
-                    throw new ToolError(notText(path));
-                const got = await p.readFile(h, path, { maxBytes: EDIT_MAX_BYTES, signal });
-                if (got === null)
-                    throw new ToolError(notFound(path));
-                if (got.truncated || looksBinary(got.data))
-                    throw new ToolError(notText(path));
-                await assertReadAndUnchanged(deps, ctx.conversationId, path, fileStateOf(got.data, st.size));
-                const text = new TextDecoder().decode(got.data);
-                const count = occurrences(text, old_string);
-                if (count === 0)
-                    throw new ToolError(noMatch(path));
-                if (count > 1 && !replace_all)
-                    throw new ToolError(ambiguous(count));
-                // 用函数形式替换：new_string 里的 `$&` 等不被当成替换模式
-                const next = replace_all
-                    ? text.split(old_string).join(new_string)
-                    : text.replace(old_string, () => new_string);
-                const nextBytes = new TextEncoder().encode(next);
-                await p.writeFile(h, path, nextBytes, signal);
-                return {
-                    n: replace_all ? count : 1,
-                    before: text,
-                    after: next,
-                    // over the bytes the next Write / Edit reads back (Read's limit), as Read records it
-                    file: recordedFile(normalizeSandboxPath(path), nextBytes.subarray(0, READ_MAX_BYTES), nextBytes.byteLength),
-                };
-            }));
+            checkPathShape(input.file_path, "file_path");
+            let path = "";
+            const { value: edit, notices } = await inSandbox(deps, ctx, ({ environmentId, h, roots, p, signal }) => {
+                path = checkWritable(input.file_path, roots);
+                // read, replace, write: one holder at a time per file
+                return withPathLease(deps, { environmentId }, path, signal, async (signal) => {
+                    const st = await p.stat(h, path, signal);
+                    if (st === null)
+                        throw new ToolError(notFound(path));
+                    if (st.isDir)
+                        throw new ToolError(notText(path));
+                    const got = await p.readFile(h, path, { maxBytes: EDIT_MAX_BYTES, signal });
+                    if (got === null)
+                        throw new ToolError(notFound(path));
+                    if (got.truncated || looksBinary(got.data))
+                        throw new ToolError(notText(path));
+                    await assertReadAndUnchanged(deps, ctx.conversationId, path, fileStateOf(got.data, st.size));
+                    const text = new TextDecoder().decode(got.data);
+                    const count = occurrences(text, old_string);
+                    if (count === 0)
+                        throw new ToolError(noMatch(path));
+                    if (count > 1 && !replace_all)
+                        throw new ToolError(ambiguous(count));
+                    // 用函数形式替换：new_string 里的 `$&` 等不被当成替换模式
+                    const next = replace_all
+                        ? text.split(old_string).join(new_string)
+                        : text.replace(old_string, () => new_string);
+                    const nextBytes = new TextEncoder().encode(next);
+                    await p.writeFile(h, path, nextBytes, signal);
+                    return {
+                        n: replace_all ? count : 1,
+                        before: text,
+                        after: next,
+                        // over the bytes the next Write / Edit reads back (Read's limit), as Read records it
+                        file: recordedFile(normalizeSandboxPath(path), nextBytes.subarray(0, READ_MAX_BYTES), nextBytes.byteLength),
+                    };
+                });
+            });
             const { n } = edit;
             const text = `Edited ${path}: replaced ${n} occurrence${n === 1 ? "" : "s"}.`;
             return {