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

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

@@ -1,4 +1,4 @@
-import { ToolError } from "@capybara-hq/plugin-sdk";
+import { DEFAULT_SANDBOX_ROOTS, ToolError, } from "@capybara-hq/plugin-sdk";
 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, mapSandboxError, noSandboxError, runBudgetNote, runTimeLeftMs, sandboxBaseTimeoutMs, sandboxConversationOf, unavailableWhenNoSandbox, withNotices, } from "./common.js";
@@ -14,14 +14,14 @@ const SPEC = {
     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. " +
+    description: "Run a shell command (bash) in this conversation's sandbox, an isolated machine. " +
         "Use it to run programs and scripts, install packages, process files and inspect the " +
-        "filesystem. The working directory is /workspace; files persist between calls in the same " +
+        "filesystem. The working directory is the workspace directory; files persist between calls in the same " +
         "conversation, but background processes may not: when the sandbox is suspended after a period " +
-        "without use they can be stopped and /tmp cleared, so keep results in files under /workspace. " +
-        "Files the user attached to the conversation are copied to /workspace/attachments/<conversation>/ " +
-        "(the result names the paths), " +
-        "and skill files under /skills (read-only). Each call runs in a fresh shell (no state such as " +
+        "without use they can be stopped and the temporary files directory cleared, so keep results in " +
+        "files under the workspace directory. Files the user attached to the conversation are copied to " +
+        "attachments/<conversation>/ in the workspace directory (the result names the paths), " +
+        "and skill files to the skills directory (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 ReadToolOutput. A command that runs longer than " +
         "timeout milliseconds is stopped. Prefer Read, Write, Edit, Glob and " +
@@ -32,13 +32,13 @@ const SPEC = {
         "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 " +
+        "under .capybara/tasks in the workspace directory. 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.",
+        "sandbox.limits.maxRunningMinutes), so keep its results in files under the workspace directory.",
     inputSchema: {
         type: "object",
         properties: {
@@ -71,9 +71,9 @@ const SPEC = {
 const msFor = (input, maxSeconds) => Math.min(input.timeout ?? BASH_DEFAULT_TIMEOUT_SECONDS * 1000, maxSeconds * 1000);
 /**
  * 命令结果 → 给模型的文本。`budgetClamped`：运行的时限把超时收紧到了 `seconds`（Ruling M20），超时说明改为
- * 指向 `runtime.maxRunSeconds`，而不是让模型加大 timeout。
+ * 指向 `runtime.maxRunSeconds`，而不是让模型加大 timeout。`workspace`: the instance's workspace root.
  */
-export function formatExec(r, seconds, budgetClamped = false) {
+export function formatExec(r, seconds, budgetClamped = false, workspace = DEFAULT_SANDBOX_ROOTS.workspace) {
     const parts = [];
     if (r.stdout !== "")
         parts.push(r.stdout.replace(/\n$/, ""));
@@ -82,10 +82,10 @@ export function formatExec(r, seconds, budgetClamped = false) {
     if (r.truncated)
         parts.push(`[Output truncated: only the first ${MAX_OUTPUT_BYTES} bytes were kept.]`);
     if (r.timedOut && budgetClamped) {
-        parts.push(`[timedOut: the command did not finish within ${seconds}s and was stopped. ${runBudgetNote(seconds)} The sandbox is still usable; split the work into shorter steps that save progress to files under /workspace, or run long jobs in the background and check on them in a later run.]`);
+        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 timeout in milliseconds (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.]");
@@ -136,8 +136,6 @@ async function runInBackground(deps, ctx, input) {
     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;
@@ -152,6 +150,8 @@ async function runInBackground(deps, ctx, input) {
     catch (e) {
         throw mapSandboxError(e);
     }
+    if (!(await sandbox.availableFor(environmentId)))
+        throw noSandboxError();
     const maxTasks = cfg.sandbox.background.maxTasks;
     const id = newTaskId();
     const description = input.description ?? clip(input.command, 120);
@@ -185,22 +185,26 @@ async function runInBackground(deps, ctx, input) {
             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."
+    // the instance's workspace once the call entered it (the default until then)
+    let workspace = DEFAULT_SANDBOX_ROOTS.workspace;
+    const isLarge = Math.ceil(Buffer.byteLength(input.command, "utf8") / 3) * 4 > LARGE_COMMAND_BASE64_BYTES;
+    const largeText = () => isLarge
+        ? ` 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 }) => {
+        ({ value: launch, notices } = await inSandbox(deps, ctx, async ({ h, roots, p, signal }) => {
+            workspace = roots.workspace;
             // 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)}`, {
+                    .readFile(h, `${roots.workspace}/${taskSidPath(id)}`, {
                     maxBytes: 64,
                     signal: AbortSignal.timeout(KILL_SESSION_TIMEOUT_MS),
                 })
@@ -212,7 +216,7 @@ async function runInBackground(deps, ctx, input) {
             try {
                 r = await p.exec(h, {
                     command: launchScript(id, input.command, seconds),
-                    cwd: "/workspace",
+                    cwd: roots.workspace,
                     timeoutMs: LAUNCH_EXEC_TIMEOUT_MS,
                     maxOutputBytes: LAUNCH_MAX_OUTPUT_BYTES,
                     signal,
@@ -240,6 +244,7 @@ async function runInBackground(deps, ctx, input) {
                 const marked = await background.markStarted(id, {
                     sid,
                     sandboxCreatedAt: instance.createdAt,
+                    outputPath: `${roots.workspace}/${taskOutputPath(id)}`,
                 });
                 if (!marked)
                     throw new Error("its task record was finished meanwhile");
@@ -275,15 +280,15 @@ async function runInBackground(deps, ctx, input) {
             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)
+            if (!isLarge || 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}`);
+            throw new ToolError(`The background task was not started: ${clip(why, 500).replace(/\.$/, "")}. Check the sandbox, or call Bash without run_in_background.${largeText()}`);
         }
     }
     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}`);
+        throw new ToolError(`The background task was not started: ${launch.why}. Check the sandbox, or call Bash without run_in_background.${largeText()}`);
     }
     if (launch.kind === "stopped") {
         await announce();
@@ -303,7 +308,12 @@ async function runInBackground(deps, ctx, input) {
         : "";
     const shown = clip(input.command, 120);
     return {
-        content: [{ type: "text", text: withNotices(notices, startedText(id, description) + lowered) }],
+        content: [
+            {
+                type: "text",
+                text: withNotices(notices, startedText(id, description, workspace) + lowered),
+            },
+        ],
         isError: false,
         view: { kind: "command", description, exitCode: null, timedOut: false },
         display: display(`后台运行命令：${shown}`, `Started in the background: ${shown}`),
@@ -338,12 +348,14 @@ export function sandboxBashTool(deps) {
             // 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 }) => {
+            let workspace = DEFAULT_SANDBOX_ROOTS.workspace;
+            const { value: r, notices } = await inSandbox(deps, ctx, ({ h, roots, p, signal }) => {
                 const left = Math.floor(runTimeLeftMs(ctx.runDeadline) / 1000) * 1000;
                 ms = Math.max(1000, Math.min(askedMs, left));
+                workspace = roots.workspace;
                 return p.exec(h, {
                     command,
-                    cwd: "/workspace",
+                    cwd: roots.workspace,
                     timeoutMs: ms,
                     maxOutputBytes: MAX_OUTPUT_BYTES,
                     signal,
@@ -355,7 +367,7 @@ export function sandboxBashTool(deps) {
             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;
+            const text = formatExec(r, seconds, clamped, workspace) + lowered;
             return {
                 content: [{ type: "text", text: withNotices(notices, text) }],
                 isError: r.timedOut || r.exitCode === null,

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);