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

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 {

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;