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

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

@@ -1,5 +1,5 @@
 import { ToolError } from "@capybara-hq/plugin-sdk";
-import { checkPath, clip, display, inSandbox, isSyncMarkerEntry, sandboxBaseTimeoutMs, searchTimeoutMs, unavailableWhenNoSandbox, withNotices, } from "./common.js";
+import { checkPath, checkPathShape, clip, display, inSandbox, sandboxBaseTimeoutMs, searchTimeoutMs, syncMarkerMatcher, unavailableWhenNoSandbox, withNotices, } from "./common.js";
 import { compileGlob, GlobPatternError } from "./glob-match.js";
 /** 最多列出的文件数。 */
 const MAX_RESULTS = 1000;
@@ -11,7 +11,7 @@ const SPEC = {
     keyArgs: ["pattern"],
     description: "Find files by name pattern in this conversation's sandbox. Use it to list files and to " +
         'locate files by name, e.g. pattern "**/*.py" for all Python files. The pattern is matched ' +
-        "against paths relative to path (default /workspace): * matches within one directory, ** " +
+        "against paths relative to path (default: the workspace directory): * matches within one directory, ** " +
         "matches across directories, ? matches one character, {a,b} matches either. Returns absolute " +
         "paths sorted by name, up to 1000. To search file contents, use Grep.",
     inputSchema: {
@@ -25,7 +25,7 @@ const SPEC = {
             path: {
                 type: "string",
                 minLength: 1,
-                description: "Absolute directory to search in. Default /workspace.",
+                description: "Absolute directory to search in. Default: the workspace directory.",
             },
         },
         required: ["pattern"],
@@ -34,7 +34,7 @@ const SPEC = {
     annotations: { readOnlyHint: true },
 };
 const ABSOLUTE_PATTERN = 'The pattern must be relative to path; pass the directory in path and a relative pattern such as "**/*.py".';
-const notDirectory = (path) => `${clip(path, 200)} is not a directory; pass an existing directory in path (default /workspace).`;
+const notDirectory = (path, workspace) => `${clip(path, 200)} is not a directory; pass an existing directory in path (default ${workspace}).`;
 const FIND_FAILED = "Listing files did not finish in time; pass a narrower path or pattern and retry.";
 /** 内置工具 `Glob`：按文件名模式找文件（只读）。 */
 export function sandboxGlobTool(deps) {
@@ -48,7 +48,6 @@ export function sandboxGlobTool(deps) {
             const { pattern } = input;
             if (pattern.startsWith("/"))
                 throw new ToolError(ABSOLUTE_PATTERN);
-            const dir = checkPath(input.path ?? "/workspace");
             let matches;
             try {
                 matches = compileGlob(pattern);
@@ -58,10 +57,15 @@ export function sandboxGlobTool(deps) {
                     throw e;
                 throw new ToolError(`Invalid glob pattern: ${e.message}; pass a simpler pattern (fewer wildcards and braces) and retry.`);
             }
-            const { value: files, notices } = await inSandbox(deps, ctx, async ({ h, p, signal }) => {
+            const given = input.path;
+            if (given !== undefined)
+                checkPathShape(given);
+            let dir = "";
+            const { value: files, notices } = await inSandbox(deps, ctx, async ({ h, roots, p, signal }) => {
+                dir = checkPath(input.path ?? roots.workspace, roots);
                 const st = await p.stat(h, dir, signal);
                 if (!st?.isDir)
-                    throw new ToolError(notDirectory(dir));
+                    throw new ToolError(notDirectory(dir, roots.workspace));
                 const r = await p.exec(h, {
                     command: "find . -type f -print0",
                     cwd: dir,
@@ -77,12 +81,13 @@ export function sandboxGlobTool(deps) {
                 if (r.truncated)
                     names.pop();
                 const base = dir === "/" ? "" : dir;
+                const isMarker = syncMarkerMatcher(roots);
                 return (names
                     .filter((l) => l.startsWith("./"))
                     .map((l) => l.slice(2))
                     .filter((rel) => matches(rel))
                     .map((rel) => `${base}/${rel}`)
-                    .filter((abs) => !isSyncMarkerEntry(abs))
+                    .filter((abs) => !isMarker(abs))
                     .sort()
                     // 文件名里的换行显示为 `\n`（与 Grep 一致），一行一个文件
                     .map((abs) => abs.replace(/\n/g, "\\n")));

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

@@ -1,5 +1,5 @@
 import { ToolError } from "@capybara-hq/plugin-sdk";
-import { checkPath, clip, display, inSandbox, isSyncMarkerEntry, sandboxBaseTimeoutMs, searchTimeoutMs, shellQuote, unavailableWhenNoSandbox, withNotices, } from "./common.js";
+import { checkPath, checkPathShape, clip, display, inSandbox, sandboxBaseTimeoutMs, searchTimeoutMs, shellQuote, syncMarkerMatcher, unavailableWhenNoSandbox, withNotices, } from "./common.js";
 /** The most output entries (lines, files or counts) returned in one call, whatever `head_limit` says. */
 const MAX_MATCHES = 500;
 /** `head_limit` when the model gives none. */
@@ -15,7 +15,7 @@ const SPEC = {
     keyArgs: ["pattern", "path"],
     description: "Search file contents in this conversation's sandbox with a regular expression (POSIX " +
         "extended, as grep -E). Use it to find where something is defined or mentioned. Searches path " +
-        "(a file, or a directory recursively; default /workspace), skipping binary files; glob limits " +
+        "(a file, or a directory recursively; default: the workspace directory), skipping binary files; glob limits " +
         'the files searched by name, e.g. "*.py". output_mode picks what comes back: ' +
         '"files_with_matches" (default) lists the paths of files that match, "content" returns the ' +
         "matching lines as <path>:<line>:<text> (with -A, -B or -C lines of context around them), " +
@@ -34,7 +34,7 @@ const SPEC = {
             path: {
                 type: "string",
                 minLength: 1,
-                description: "Absolute file or directory to search. Default /workspace.",
+                description: "Absolute file or directory to search. Default: the workspace directory.",
             },
             glob: {
                 type: "string",
@@ -160,8 +160,11 @@ export function sandboxGrepTool(deps) {
             const { pattern, glob } = g;
             const mode = g.output_mode ?? "files_with_matches";
             const numbered = g["-n"] ?? true;
-            const path = checkPath(g.path ?? "/workspace");
-            const { value, notices } = await inSandbox(deps, ctx, async ({ h, p, signal }) => {
+            if (g.path !== undefined)
+                checkPathShape(g.path);
+            let path = "";
+            const { value, notices } = await inSandbox(deps, ctx, async ({ h, roots, p, signal }) => {
+                path = checkPath(g.path ?? roots.workspace, roots);
                 const st = await p.stat(h, path, signal);
                 if (st === null)
                     throw new ToolError(notFound(path));
@@ -207,7 +210,8 @@ export function sandboxGrepTool(deps) {
                     : mode === "count"
                         ? parseCounts(r.stdout, base)
                         : parseGrepNull(r.stdout, base, numbered);
-                const entries = all.filter((l) => !isSyncMarkerEntry(l));
+                const isMarker = syncMarkerMatcher(roots);
+                const entries = all.filter((l) => !isMarker(l));
                 // 退出码 2 = 有错误（如个别文件不可读）；有输出时照常返回（可能为空：只匹配到隐藏的标记文件）并附上说明
                 if (r.exitCode !== 0 && all.length === 0)
                     throw new ToolError(failed(r.stderr));

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

@@ -2,12 +2,14 @@ import type { BuiltinTool } from "../../registry.js";
 import type { SandboxToolDeps } from "./common.js";
 export { SANDBOX_ASK_TOOL_NAMES, SANDBOX_TOOL_NAMES } from "../../builtin-names.js";
 export { BASH_SPILL_CHARS, formatExec } from "./bash.js";
-export { assignAttachmentNames, RUN_DEADLINE_MARGIN_MS, runTimeLeftMs, SANDBOX_RESTARTED_NOTICE, SANDBOX_SETUP_MARGIN_MS, SANDBOX_STARTED_NOTICE, SANDBOX_UNAVAILABLE_REASON, type SandboxToolDeps, sandboxBaseTimeoutMs, searchTimeoutMs, shellQuote, } from "./common.js";
+export { assignAttachmentNames, RUN_DEADLINE_MARGIN_MS, runTimeLeftMs, SANDBOX_RESTARTED_NOTICE, SANDBOX_SETUP_MARGIN_MS, SANDBOX_STARTED_NOTICE, SANDBOX_UNAVAILABLE_REASON, type SandboxToolDeps, sandboxBaseTimeoutMs, sandboxStartedNotice, sandboxUsable, searchTimeoutMs, shellQuote, } from "./common.js";
 export { compileGlob, GlobPatternError, MAX_GLOB_STARS } from "./glob-match.js";
 /**
- * 沙箱内置工具（M5 T8）：bash / read / write / edit / glob / grep / deliver，都在本对话的沙箱上执行
- * （`SandboxService.withSandbox`），执行前同步附件到 `/workspace/attachments`。没有沙箱提供方时报不可用。
- * 默认 allow；组织设置 `sandboxToolPolicy` 为 ask 时除 read / glob / grep 外需要审批（见 policy.ts）。
+ * The sandbox builtins (M5 T8): Bash / Read / Write / Edit / Glob / Grep / Deliver, all run in the
+ * conversation's environment (`SandboxService.withSandbox`) after syncing attachments to
+ * `<workspace>/attachments` (the instance's roots, environments spec §13.1); unavailable without
+ * a provider for it. Allowed by default; with the org setting `sandboxToolPolicy` set to ask,
+ * every one but Read / Glob / Grep needs approval (see policy.ts).
  * `TaskOutput` and `TaskStop` read and stop background `Bash` tasks through
  * `SandboxService.ifRunning` (never creating or resuming a sandbox); always allowed.
  */

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

@@ -9,12 +9,14 @@ import { taskStopTool } from "./task-stop.js";
 import { sandboxWriteTool } from "./write.js";
 export { SANDBOX_ASK_TOOL_NAMES, SANDBOX_TOOL_NAMES } from "../../builtin-names.js";
 export { BASH_SPILL_CHARS, formatExec } from "./bash.js";
-export { assignAttachmentNames, RUN_DEADLINE_MARGIN_MS, runTimeLeftMs, SANDBOX_RESTARTED_NOTICE, SANDBOX_SETUP_MARGIN_MS, SANDBOX_STARTED_NOTICE, SANDBOX_UNAVAILABLE_REASON, sandboxBaseTimeoutMs, searchTimeoutMs, shellQuote, } from "./common.js";
+export { assignAttachmentNames, RUN_DEADLINE_MARGIN_MS, runTimeLeftMs, SANDBOX_RESTARTED_NOTICE, SANDBOX_SETUP_MARGIN_MS, SANDBOX_STARTED_NOTICE, SANDBOX_UNAVAILABLE_REASON, sandboxBaseTimeoutMs, sandboxStartedNotice, sandboxUsable, searchTimeoutMs, shellQuote, } from "./common.js";
 export { compileGlob, GlobPatternError, MAX_GLOB_STARS } from "./glob-match.js";
 /**
- * 沙箱内置工具（M5 T8）：bash / read / write / edit / glob / grep / deliver，都在本对话的沙箱上执行
- * （`SandboxService.withSandbox`），执行前同步附件到 `/workspace/attachments`。没有沙箱提供方时报不可用。
- * 默认 allow；组织设置 `sandboxToolPolicy` 为 ask 时除 read / glob / grep 外需要审批（见 policy.ts）。
+ * The sandbox builtins (M5 T8): Bash / Read / Write / Edit / Glob / Grep / Deliver, all run in the
+ * conversation's environment (`SandboxService.withSandbox`) after syncing attachments to
+ * `<workspace>/attachments` (the instance's roots, environments spec §13.1); unavailable without
+ * a provider for it. Allowed by default; with the org setting `sandboxToolPolicy` set to ask,
+ * every one but Read / Glob / Grep needs approval (see policy.ts).
  * `TaskOutput` and `TaskStop` read and stop background `Bash` tasks through
  * `SandboxService.ifRunning` (never creating or resuming a sandbox); always allowed.
  */

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

@@ -1,6 +1,6 @@
 import { ToolError } from "@capybara-hq/plugin-sdk";
 import { viewPath } from "../../view.js";
-import { checkPath, clip, display, inSandbox, looksBinary, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, withNotices, } from "./common.js";
+import { checkPath, checkPathShape, clip, display, inSandbox, looksBinary, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, withNotices, } from "./common.js";
 import { normalizeSandboxPath, recordedFile } from "./file-state.js";
 /** 不给 `limit` 时一次读的行数。 */
 const DEFAULT_LIMIT = 2000;
@@ -13,8 +13,9 @@ const SPEC = {
     // Display only (the tool row; not in the fingerprint, never sent to the model).
     keyArgs: ["file_path"],
     description: "Read a text file from this conversation's sandbox, with line numbers. Use it to look at " +
-        "source code, data files, logs and files the user attached (under /workspace/attachments/<conversation>/). " +
-        "Paths are absolute, under /workspace, /skills or /tmp. Lines are numbered from 1; pass " +
+        "source code, data files, logs and files the user attached (under attachments/<conversation>/ in " +
+        "the workspace directory). Paths are absolute, under the workspace directory, the skills " +
+        "directory or the temporary files directory. Lines are numbered from 1; pass " +
         "offset and limit to read part of a long file. Binary files are not shown; use Bash " +
         "to inspect them. Do not use it to list directories; use Glob instead. Read a file before you " +
         "write it: Write and Edit fail on a file you have not read, or one changed since you read it.",
@@ -24,7 +25,7 @@ const SPEC = {
             file_path: {
                 type: "string",
                 minLength: 1,
-                description: 'Absolute path of the file, e.g. "/workspace/src/main.py".',
+                description: "Absolute path of the file, e.g. src/main.py in the workspace directory.",
             },
             offset: {
                 type: "integer",
@@ -81,8 +82,10 @@ export function sandboxReadTool(deps) {
         timeoutMs: () => sandboxBaseTimeoutMs(deps.config.get()),
         async run(input, ctx) {
             const { offset = 1, limit = DEFAULT_LIMIT } = input;
-            const path = checkPath(input.file_path, "file_path");
-            const { value, notices } = await inSandbox(deps, ctx, async ({ h, p, signal }) => {
+            checkPathShape(input.file_path, "file_path");
+            let path = "";
+            const { value, 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));

package/dist/tools/builtins/sandbox/task-output.d.ts

@@ -16,8 +16,12 @@ export interface TaskEnv {
     ifRunning: SandboxService["ifRunning"];
     environments: SandboxToolDeps["environments"];
 }
-/** The task tools' dependencies; throws the tool's error when they are missing. */
-export declare function taskEnv(deps: SandboxToolDeps): TaskEnv;
+/**
+ * The task tools' dependencies; throws the tool's error when they are missing, or when the
+ * conversation's environment cannot run (no cloud provider, and not a registered `@device` one:
+ * ruling R8).
+ */
+export declare function taskEnv(deps: SandboxToolDeps, ctx: BuiltinCallContext): Promise<TaskEnv>;
 /**
  * The task `id` when it belongs to the calling conversation; a task of another conversation (a
  * sub-agent's, when called from its parent) is not found, the same as an unknown id.
@@ -45,7 +49,7 @@ export declare const outputFile: (task: BackgroundTaskRow) => string;
 /** Why the output cannot be read: the task's sandbox instance is not running. */
 export declare function unavailableText(task: BackgroundTaskRow, r: IfRunningResult<unknown>): string;
 /**
- * The exec that checks and reads task `t` (relative to `/workspace`): for a running task first
+ * The exec that checks and reads task `t` (relative to the workspace root): for a running task first
  * its status line (the poller's, {@link pollScript}: liveness, then the exit file), then
  * `size <bytes>` and `out <base64>`, at most `cap` bytes of the output from byte `offset` on.
  * The file is never read whole: `tail -c +<offset+1> | head -c <cap>`. Without `read` only the

package/dist/tools/builtins/sandbox/task-output.js

@@ -1,11 +1,11 @@
 import { setTimeout as sleep } from "node:timers/promises";
-import { isSandboxGoneError, ToolError, } from "@capybara-hq/plugin-sdk";
-import { TASK_ID_RE, TASKS_DIR } from "../../../background/launch.js";
+import { isSandboxGoneError, rootsOf, ToolError, } from "@capybara-hq/plugin-sdk";
+import { TASK_ID_RE, TASKS_DIR, taskOutputFile } from "../../../background/launch.js";
 import { formatElapsed, lostReasonText } from "../../../background/render.js";
 import { actingAs, SID_RE, taskActor } from "../../../background/session.js";
 import { parsePollOutput, polledAs, pollScript, } from "../../../background/status.js";
 import { notRunningAs, RECREATED } from "../../../background/stop.js";
-import { clip, display, mapSandboxError, noSandboxError, runTimeLeftMs, sandboxBaseTimeoutMs, sandboxConversationOf, unavailableWhenNoSandbox, } from "./common.js";
+import { clip, display, mapSandboxError, noSandboxError, runTimeLeftMs, sandboxBaseTimeoutMs, sandboxConversationOf, sandboxUsable, unavailableWhenNoSandbox, } from "./common.js";
 /** How long `TaskOutput` waits with `block` when `timeout` is not given (ms). */
 export const TASK_OUTPUT_DEFAULT_TIMEOUT_MS = 30_000;
 /** The longest `TaskOutput` wait (ms). */
@@ -49,9 +49,13 @@ const SPEC = {
         additionalProperties: false,
     },
 };
-/** The task tools' dependencies; throws the tool's error when they are missing. */
-export function taskEnv(deps) {
-    if (!deps.sandbox.available)
+/**
+ * The task tools' dependencies; throws the tool's error when they are missing, or when the
+ * conversation's environment cannot run (no cloud provider, and not a registered `@device` one:
+ * ruling R8).
+ */
+export async function taskEnv(deps, ctx) {
+    if (!(await sandboxUsable(deps, ctx.orgId, sandboxConversationOf(ctx))))
         throw noSandboxError();
     const { background, tasks } = deps;
     if (!background || !tasks || !deps.sandbox.ifRunning) {
@@ -122,7 +126,7 @@ export function statusLine(task, now = new Date()) {
     return `${s} after ${elapsed}`;
 }
 /** The absolute path of the task's output file, as the model sees it. */
-export const outputFile = (task) => `/workspace/${task.outputPath}`;
+export const outputFile = (task) => taskOutputFile(task.outputPath);
 /** Why the output cannot be read: the task's sandbox instance is not running. */
 export function unavailableText(task, r) {
     if (r.kind === "not_running" && r.status === "suspended") {
@@ -132,7 +136,7 @@ export function unavailableText(task, r) {
 }
 // ---- reading a task ----
 /**
- * The exec that checks and reads task `t` (relative to `/workspace`): for a running task first
+ * The exec that checks and reads task `t` (relative to the workspace root): for a running task first
  * its status line (the poller's, {@link pollScript}: liveness, then the exit file), then
  * `size <bytes>` and `out <base64>`, at most `cap` bytes of the output from byte `offset` on.
  * The file is never read whole: `tail -c +<offset+1> | head -c <cap>`. Without `read` only the
@@ -189,7 +193,7 @@ async function look(env, task, read, signal) {
     return onTaskInstance(env, task, async (p, h, sig) => {
         const r = await p.exec(h, {
             command: script,
-            cwd: "/workspace",
+            cwd: rootsOf(h).workspace,
             timeoutMs: READ_EXEC_TIMEOUT_MS,
             maxOutputBytes: maxBytes,
             signal: sig,
@@ -262,7 +266,7 @@ export function taskOutputTool(deps) {
         },
         async run(input, ctx) {
             const { task_id, block = true, timeout } = input;
-            const env = taskEnv(deps);
+            const env = await taskEnv(deps, ctx);
             let task = await ownedTask(env, ctx, task_id);
             await recheckEnvironment(env, ctx);
             if (block && task.status === "running") {

package/dist/tools/builtins/sandbox/task-stop.js

@@ -1,4 +1,4 @@
-import { ToolError } from "@capybara-hq/plugin-sdk";
+import { rootsOf, ToolError } from "@capybara-hq/plugin-sdk";
 import { decodeTail, tailCommand } from "../../../background/session.js";
 import { clip, display, mapSandboxError, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, } from "./common.js";
 import { onTaskInstance, ownedTask, recheckEnvironment, statusLine, taskEnv, } from "./task-output.js";
@@ -33,7 +33,7 @@ async function lastLinesOf(env, task, signal) {
         const r = await onTaskInstance(env, task, async (p, h, sig) => {
             const res = await p.exec(h, {
                 command: tailCommand(task.id),
-                cwd: "/workspace",
+                cwd: rootsOf(h).workspace,
                 timeoutMs: TAIL_EXEC_TIMEOUT_MS,
                 maxOutputBytes: 64 * 1024,
                 signal: sig,
@@ -82,7 +82,7 @@ export function taskStopTool(deps) {
         timeoutMs: () => sandboxBaseTimeoutMs(deps.config.get()),
         async run(input, ctx) {
             const { task_id } = input;
-            const env = taskEnv(deps);
+            const env = await taskEnv(deps, ctx);
             const task = await ownedTask(env, ctx, task_id);
             await recheckEnvironment(env, ctx);
             if (task.status !== "running") {

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

@@ -1,6 +1,6 @@
 import { ToolError } from "@capybara-hq/plugin-sdk";
 import { lineDiff, TOOL_VIEW_DIFF_MAX_BYTES, 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";
 const SPEC = {
@@ -9,8 +9,8 @@ const SPEC = {
     keyArgs: ["file_path"],
     description: "Write a text file in this conversation's sandbox, creating parent directories as needed. " +
         "Each call replaces the whole file (it is created if missing). Use it to create scripts, " +
-        "source files and data files. The path is absolute, under /workspace or /tmp (/skills is " +
-        "read-only). Read an existing file first; overwriting a file you have not read, or one changed " +
+        "source files and data files. The path is absolute, under the workspace directory or the " +
+        "temporary files directory (the skills directory is read-only). Read an existing file first; overwriting a file you have not read, or one changed " +
         "since you read it, fails. To change part of an existing file, use Edit instead; to give a file to " +
         "the user, use Deliver.",
     inputSchema: {
@@ -19,7 +19,7 @@ const SPEC = {
             file_path: {
                 type: "string",
                 minLength: 1,
-                description: 'Absolute path of the file, e.g. "/workspace/report.md".',
+                description: "Absolute path of the file, e.g. report.md in the workspace directory.",
             },
             content: { type: "string", description: "The complete new content of the file." },
         },
@@ -43,33 +43,36 @@ export function sandboxWriteTool(deps) {
         unavailable: unavailableWhenNoSandbox(deps),
         timeoutMs: () => sandboxBaseTimeoutMs(deps.config.get()),
         async run(input, ctx) {
-            const path = checkWritable(input.file_path);
             const data = new TextEncoder().encode(input.content);
-            const { value, notices } = await inSandbox(deps, ctx, ({ environmentId, h, p, signal }) => 
-            // stat, read the previous content, 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?.isDir)
-                    throw new ToolError(isDirectory(path));
-                // the previous content: for the read-before-write check, and the diff on the row (display
-                // only: a file too large or binary to diff just leaves the view without hunks)
-                let previous = "";
-                if (st !== null) {
-                    const got = await p.readFile(h, path, { maxBytes: READ_MAX_BYTES, signal });
-                    if (got === null)
-                        throw new ToolError(vanished(path));
-                    await assertReadAndUnchanged(deps, ctx.conversationId, path, fileStateOf(got.data, st.size));
-                    previous =
-                        st.size > PREVIOUS_MAX_BYTES ||
-                            got.truncated ||
-                            looksBinary(got.data) ||
-                            got.data.includes(0)
-                            ? null
-                            : new TextDecoder().decode(got.data);
-                }
-                await p.writeFile(h, path, data, signal);
-                return { existed: st !== null, previous };
-            }));
+            checkPathShape(input.file_path, "file_path");
+            let path = "";
+            const { value, notices } = await inSandbox(deps, ctx, ({ environmentId, h, roots, p, signal }) => {
+                path = checkWritable(input.file_path, roots);
+                // stat, read the previous content, 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?.isDir)
+                        throw new ToolError(isDirectory(path));
+                    // the previous content: for the read-before-write check, and the diff on the row (display
+                    // only: a file too large or binary to diff just leaves the view without hunks)
+                    let previous = "";
+                    if (st !== null) {
+                        const got = await p.readFile(h, path, { maxBytes: READ_MAX_BYTES, signal });
+                        if (got === null)
+                            throw new ToolError(vanished(path));
+                        await assertReadAndUnchanged(deps, ctx.conversationId, path, fileStateOf(got.data, st.size));
+                        previous =
+                            st.size > PREVIOUS_MAX_BYTES ||
+                                got.truncated ||
+                                looksBinary(got.data) ||
+                                got.data.includes(0)
+                                ? null
+                                : new TextDecoder().decode(got.data);
+                    }
+                    await p.writeFile(h, path, data, signal);
+                    return { existed: st !== null, previous };
+                });
+            });
             const { existed, previous } = value;
             const text = `${existed ? "Overwrote" : "Created"} ${path} (${data.byteLength} bytes).`;
             return {

package/dist/tools/builtins/skill-load.d.ts

@@ -8,14 +8,14 @@ import { type SandboxToolDeps } from "./sandbox/common.js";
  * Builtin tool `Skill` (M5 T14, ruling M17): resolves the name against the latest skills catalog
  * snapshot in the log to an id and version, and returns that version's SKILL.md body and file list
  * (the result names the version). A skill with other files is copied whole into the conversation's
- * environment at `/skills/<name>@<digest>/` (the provider writes as root, commands read only; the
+ * environment at `<skills root>/<name>@<digest>/` (the instance's skills root, `/skills` by default; the provider writes as root, commands read only; the
  * digest is {@link skillDigest} of the version's file manifest, so versions of one skill coexist in
  * the shared file system). Without a sandbox provider only the body is given, with a note that
  * scripts are unavailable.
  *
  * - Every file read from storage is checked against the manifest's sha256; a mismatch is refused.
  * - The copy is recorded in a kernel-controlled marker, one per skill version
- *   ({@link skillMarkerPath}: `/skills/.capybara/<name>@<digest>.json`, commands cannot change it):
+ *   ({@link skillMarkerPath}: `<skills root>/.capybara/<name>@<digest>.json`, commands cannot change it):
  *   `{ digest, files }`. A present marker with the same digest skips the copy.
  * - An agent without any sandbox tool creates no sandbox and copies nothing (the model could not
  *   run the scripts), and is told so.
@@ -23,11 +23,14 @@ import { type SandboxToolDeps } from "./sandbox/common.js";
  *   to run scripts with an interpreter (`sh` / `python3` / `node`).
  */
 /**
- * 已复制进沙箱的技能的标记目录（内核控制：`/skills` 只有提供方以 root 能写；技能名不以 `.` 开头，不会撞名）。
+ * 已复制进沙箱的技能的标记目录（内核控制：技能根目录只有提供方以 root 能写；技能名不以 `.` 开头，不会撞名）。
+ * `skillsRoot`: the instance's skills root.
  */
-export declare const SKILLS_MARKER_DIR = "/skills/.capybara";
+export declare const skillsMarkerDir: (skillsRoot?: string) => string;
+/** {@link skillsMarkerDir} of an instance with the default roots. */
+export declare const SKILLS_MARKER_DIR: string;
 /** The marker file of one skill version. */
-export declare const skillMarkerPath: (name: string, digest: string) => string;
+export declare const skillMarkerPath: (name: string, digest: string, skillsRoot?: string) => string;
 /** 依赖：沙箱工具的依赖，加上读技能行用的库与读快照用的日志。 */
 export interface SkillLoadDeps extends SandboxToolDeps {
     db: KernelSchemaDb;

package/dist/tools/builtins/skill-load.js

@@ -9,19 +9,19 @@ import { resolveSkillForkType } from "../../runtime/subagents/roster.js";
 import { invocationOf, resolveSkills } from "../../skills/catalog.js";
 import { PLATFORM_SOURCE, skillFileStore } from "../../skills/usable.js";
 import { AGENT_TOOL, SANDBOX_TOOL_NAMES } from "../builtin-names.js";
-import { clip, display, inSandbox, sandboxBaseTimeoutMs, withNotices, withPathLease, } from "./sandbox/common.js";
+import { clip, display, inSandbox, sandboxBaseTimeoutMs, sandboxConversationOf, sandboxUsable, withNotices, withPathLease, } from "./sandbox/common.js";
 /**
  * Builtin tool `Skill` (M5 T14, ruling M17): resolves the name against the latest skills catalog
  * snapshot in the log to an id and version, and returns that version's SKILL.md body and file list
  * (the result names the version). A skill with other files is copied whole into the conversation's
- * environment at `/skills/<name>@<digest>/` (the provider writes as root, commands read only; the
+ * environment at `<skills root>/<name>@<digest>/` (the instance's skills root, `/skills` by default; the provider writes as root, commands read only; the
  * digest is {@link skillDigest} of the version's file manifest, so versions of one skill coexist in
  * the shared file system). Without a sandbox provider only the body is given, with a note that
  * scripts are unavailable.
  *
  * - Every file read from storage is checked against the manifest's sha256; a mismatch is refused.
  * - The copy is recorded in a kernel-controlled marker, one per skill version
- *   ({@link skillMarkerPath}: `/skills/.capybara/<name>@<digest>.json`, commands cannot change it):
+ *   ({@link skillMarkerPath}: `<skills root>/.capybara/<name>@<digest>.json`, commands cannot change it):
  *   `{ digest, files }`. A present marker with the same digest skips the copy.
  * - An agent without any sandbox tool creates no sandbox and copies nothing (the model could not
  *   run the scripts), and is told so.
@@ -29,11 +29,14 @@ import { clip, display, inSandbox, sandboxBaseTimeoutMs, withNotices, withPathLe
  *   to run scripts with an interpreter (`sh` / `python3` / `node`).
  */
 /**
- * 已复制进沙箱的技能的标记目录（内核控制：`/skills` 只有提供方以 root 能写；技能名不以 `.` 开头，不会撞名）。
+ * 已复制进沙箱的技能的标记目录（内核控制：技能根目录只有提供方以 root 能写；技能名不以 `.` 开头，不会撞名）。
+ * `skillsRoot`: the instance's skills root.
  */
-export const SKILLS_MARKER_DIR = `${SKILLS_SANDBOX_ROOT}/.capybara`;
+export const skillsMarkerDir = (skillsRoot = SKILLS_SANDBOX_ROOT) => `${skillsRoot}/.capybara`;
+/** {@link skillsMarkerDir} of an instance with the default roots. */
+export const SKILLS_MARKER_DIR = skillsMarkerDir();
 /** The marker file of one skill version. */
-export const skillMarkerPath = (name, digest) => `${SKILLS_MARKER_DIR}/${name}@${digest}.json`;
+export const skillMarkerPath = (name, digest, skillsRoot = SKILLS_SANDBOX_ROOT) => `${skillsMarkerDir(skillsRoot)}/${name}@${digest}.json`;
 const MARKER_MAX_BYTES = 256 * 1024;
 /** 结果里最多列出的文件数（其余只给数量）。 */
 const MAX_LISTED_FILES = 200;
@@ -46,7 +49,7 @@ const SPEC = {
     description: "Load a skill from the skills list: returns the skill's instructions " +
         "(its SKILL.md) and the list of its files. Call it before starting a task that matches a " +
         "skill's description, then follow the returned instructions. If the skill has scripts or other " +
-        "files, they are copied read-only to /skills/<name>@<version-id>/ in this environment; run scripts " +
+        "files, they are copied read-only to <name>@<version-id>/ in the skills directory of this environment; run scripts " +
         "there with an interpreter (sh, python3, node). Call it again when the skills list changes. Pass args when the task gives the skill arguments (they replace " +
         "$ARGUMENTS and $1, $2… in the instructions). Do not use it for skills that are not in the list.",
     inputSchema: {
@@ -157,13 +160,13 @@ async function readVerified(store, key, file, skill, signal) {
     }
 }
 /**
- * Copies the skill version whole to `/skills/<name>@<digest>/` (skipped when its marker matches).
+ * Copies the skill version whole to `<skills root>/<name>@<digest>/` (skipped when its marker matches).
  * Every file is checked against the manifest before it is written; the marker is written last, so
  * a failure midway means the next call starts over.
  */
 async function copySkill(s, v) {
     const { name } = v.entry;
-    const markerPath = skillMarkerPath(name, v.digest);
+    const markerPath = skillMarkerPath(name, v.digest, s.roots.skills);
     const m = await s.p.readFile(s.h, markerPath, { maxBytes: MARKER_MAX_BYTES, signal: s.signal });
     const cur = m && !m.truncated ? parseMarker(m.data) : undefined;
     if (cur?.digest === v.digest)
@@ -172,7 +175,7 @@ async function copySkill(s, v) {
         const data = f.path === SKILL_ENTRY_FILE
             ? v.entryBytes
             : await readVerified(v.store, `${v.keyPrefix}${f.path}`, f, name, s.signal);
-        await s.p.writeFile(s.h, skillSandboxPath(name, v.digest, f.path), data, s.signal);
+        await s.p.writeFile(s.h, skillSandboxPath(name, v.digest, f.path, s.roots.skills), data, s.signal);
     }
     const entry = { digest: v.digest, files: v.manifest.files.map((f) => f.path) };
     await s.p.writeFile(s.h, markerPath, new TextEncoder().encode(JSON.stringify(entry)), s.signal);
@@ -435,14 +438,15 @@ export function skillLoadTool(deps) {
             }
             if ("errors" in parsed)
                 throw new ToolError(integrityText(name));
-            const dir = `${skillSandboxDir(name, digest)}/`;
+            // the skills root of the instance the files were copied to (the default without a copy)
+            let skillsRoot = SKILLS_SANDBOX_ROOT;
             const others = manifest.files.filter((f) => f.path !== SKILL_ENTRY_FILE);
             let notices = [];
             let filesText;
             if (others.length === 0) {
                 filesText = "This skill has no files besides its instructions.";
             }
-            else if (!deps.sandbox.available) {
+            else if (!(await sandboxUsable(deps, ctx.orgId, sandboxConversationOf(ctx)))) {
                 filesText =
                     `Skill files (for reference):\n${fileList(manifest.files)}\n` +
                         "This deployment has no sandbox, so the skill's scripts and other files are not available; " +
@@ -457,19 +461,21 @@ export function skillLoadTool(deps) {
             }
             else {
                 // the skill's marker is read, compared and written: one holder at a time per skill
-                const r = await inSandbox(deps, ctx, (s) => withPathLease(deps, s, skillMarkerPath(name, digest), s.signal, (signal) => copySkill({ ...s, signal }, v)));
+                const r = await inSandbox(deps, ctx, (s) => withPathLease(deps, s, skillMarkerPath(name, digest, s.roots.skills), s.signal, (signal) => copySkill({ ...s, signal }, v).then(() => s.roots)));
                 notices = r.notices;
+                skillsRoot = r.value.skills;
+                const dir = `${skillSandboxDir(name, digest, skillsRoot)}/`;
                 filesText =
                     `Skill files (copied to ${dir} in the sandbox, read-only):\n${fileList(manifest.files)}\n` +
                         `Run scripts with an interpreter, e.g. \`sh ${dir}<script>.sh\`, \`python3 ${dir}<script>.py\` ` +
                         "or `node`; the files are not executable, so `./script` does not work. Write outputs under " +
-                        `/workspace, not ${SKILLS_SANDBOX_ROOT}.`;
+                        `${r.value.workspace}, not ${skillsRoot}.`;
             }
             const invocation = invocationOf(manifest);
             const fork = invocation.fork;
             let instructions;
             try {
-                instructions = renderSkillBody(parsed.body.trim(), invocation, args ?? "", name, digest);
+                instructions = renderSkillBody(parsed.body.trim(), invocation, args ?? "", name, digest, skillsRoot);
             }
             catch (e) {
                 if (!(e instanceof RangeError))

package/dist/tools/builtins/skill-write.js

@@ -29,7 +29,7 @@ const SPEC = {
         "user-invocable, context, agent, argument-hint and arguments, which are kept; with " +
         "disable-model-invocation: true only a person can invoke the skill and you cannot load it). " +
         "Every other entry in `files` is stored at " +
-        "/skills/<name>@<version-id>/<path> once loaded. Files of the previous version that you leave out are not part of the new " +
+        "<name>@<version-id>/<path> in the skills directory once loaded. Files of the previous version that you leave out are not part of the new " +
         "version. Text files only, at most 1 MB per skill in total. Use an existing skill's name to update " +
         "it; an organization skill with the same name is shadowed by this agent's own skill. On a private " +
         "agent the new version takes effect immediately. On a shared agent the change is sent to the " +
@@ -41,7 +41,7 @@ const SPEC = {
                 type: "string",
                 minLength: 1,
                 maxLength: SKILL_LIMITS.nameMaxChars,
-                description: 'Skill name: lowercase letters, digits and single hyphens, e.g. "weekly-report". Also the folder name under /skills/.',
+                description: 'Skill name: lowercase letters, digits and single hyphens, e.g. "weekly-report". Also the folder name in the skills directory.',
             },
             description: {
                 type: "string",

package/dist/tools/pipeline.js

@@ -249,6 +249,8 @@ let ToolPipeline = class ToolPipeline {
                     subagents: ctx.agent.subagents,
                     child: ctx.parent !== undefined,
                     forkChild: ctx.parent?.forSkill === true,
+                    sandboxConversationId: ctx.parent?.rootConversationId ?? ctx.conversationId,
+                    replay: ctx.conversationKind === "eval",
                 });
             }
             return resolved;