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

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

@@ -1,20 +1,28 @@
 import { ToolError } from "@capybara-hq/plugin-sdk";
-import { checkPath, clip, display, inSandbox, SYNC_MARKER, 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. */
+const DEFAULT_HEAD_LIMIT = 250;
 /** 每个匹配行最多显示的字符数。 */
 const MAX_LINE_CHARS = 500;
 /** grep 输出的上限（字节）。 */
 const MAX_GREP_BYTES = 4 * 1024 * 1024;
+const MODES = ["content", "files_with_matches", "count"];
 const SPEC = {
-    name: "sandbox_grep",
+    name: "Grep",
     // Display only (the tool row; not in the fingerprint, never sent to the model).
     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 " +
-        'the files searched by name, e.g. "*.py". Returns matching lines as <path>:<line>:<text>, up ' +
-        "to 500. To find files by name, use sandbox_glob.",
+        "(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), " +
+        '"count" returns <path>:<number of matching lines> per file. -n (line numbers) and the context ' +
+        "options apply only to content mode. head_limit caps the entries returned (default 250; " +
+        "0 = up to 500); pass offset to skip entries and page through more. To find files by " +
+        "name, use Glob.",
     inputSchema: {
         type: "object",
         properties: {
@@ -26,31 +34,73 @@ 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",
                 minLength: 1,
                 description: 'Only search files whose name matches this glob, e.g. "*.md".',
             },
-            ignoreCase: { type: "boolean", description: "Case-insensitive match. Default false." },
+            "-i": { type: "boolean", description: "Case-insensitive match. Default false." },
+            output_mode: {
+                type: "string",
+                enum: [...MODES],
+                description: 'What to return: "files_with_matches" (file paths, default), "content" (matching lines) or "count" (matching lines per file).',
+            },
+            "-n": {
+                type: "boolean",
+                description: "Show line numbers in content mode. Default true.",
+            },
+            "-A": {
+                type: "integer",
+                minimum: 0,
+                description: "Lines of context after each match (content mode).",
+            },
+            "-B": {
+                type: "integer",
+                minimum: 0,
+                description: "Lines of context before each match (content mode).",
+            },
+            "-C": {
+                type: "integer",
+                minimum: 0,
+                description: "Lines of context before and after each match (content mode).",
+            },
+            head_limit: {
+                type: "integer",
+                minimum: 0,
+                description: `Return at most this many entries (lines, files or counts, by mode). Default ${DEFAULT_HEAD_LIMIT}; 0 = up to ${MAX_MATCHES}.`,
+            },
+            offset: {
+                type: "integer",
+                minimum: 0,
+                description: "Skip this many entries before returning (for paging). Default 0.",
+            },
         },
         required: ["pattern"],
         additionalProperties: false,
     },
     annotations: { readOnlyHint: true },
 };
-const notFound = (path) => `${clip(path, 200)} does not exist; check the path with sandbox_glob.`;
+const notFound = (path) => `${clip(path, 200)} does not exist; check the path with Glob.`;
 const failed = (stderr) => `grep failed: ${clip(stderr, 300)}. Check the pattern (POSIX extended regular expression) and retry.`;
 const GREP_TIMEOUT = "The search did not finish in time; pass a narrower path or a glob and retry.";
 /**
- * 解析 `grep -nH --null` 的输出：每条为 `<文件名>\0<行号>:<行>\n`（文件名可能含换行，行本身不含）。
- * 返回 `<绝对路径>:<行号>:<行>`；文件名里的换行显示为 `\n`。最后一条不完整（输出被截断）时丢掉。
+ * Parses the output of `grep -H --null` (with `-n` when `numbered`): each entry is
+ * `<file name>\0<line number>:<line>\n` (the file name may contain newlines, the line does not).
+ * Returns `<absolute path>:<line number>:<line>`; context lines (`<line number>-<line>`, only with
+ * `-A/-B/-C`) become `<absolute path>-<line number>-<line>`, and the `--` group separator is kept.
+ * A newline in a file name shows as `\n`. An incomplete last entry (truncated output) is dropped.
  */
-export function parseGrepNull(stdout, base) {
+export function parseGrepNull(stdout, base, numbered = true) {
     const out = [];
     let pos = 0;
     for (;;) {
+        if (stdout.startsWith("--\n", pos)) {
+            out.push("--");
+            pos += 3;
+            continue;
+        }
         const nul = stdout.indexOf("\0", pos);
         if (nul === -1)
             break;
@@ -59,23 +109,62 @@ export function parseGrepNull(stdout, base) {
             break;
         const raw = stdout.slice(pos, nul);
         const name = (raw.startsWith("./") ? raw.slice(2) : raw).replace(/\n/g, "\\n");
-        out.push(`${base}/${name}:${stdout.slice(nul + 1, nl)}`);
+        const rest = stdout.slice(nul + 1, nl);
+        out.push(numbered && /^\d+-/.test(rest) ? `${base}/${name}-${rest}` : `${base}/${name}:${rest}`);
         pos = nl + 1;
     }
     return out;
 }
-/** 内置工具 `sandbox_grep`：按正则搜文件内容（只读）。 */
+const displayName = (raw) => (raw.startsWith("./") ? raw.slice(2) : raw).replace(/\n/g, "\\n");
+/** `grep -l --null` output: the matching files, each followed by NUL. */
+function parseFileList(stdout, base) {
+    const parts = stdout.split("\0");
+    // the last part is empty, or an incomplete name when the output was truncated: dropped
+    parts.pop();
+    return parts.filter((n) => n !== "").map((n) => `${base}/${displayName(n)}`);
+}
+/**
+ * `grep -c` output as `<path>:<count>` for the files with at least one matching line. GNU grep
+ * with `--null` writes `<file>\0<count>\n`; other implementations write `<file>:<count>`.
+ */
+function parseCounts(stdout, base) {
+    const out = [];
+    if (stdout.includes("\0")) {
+        for (const l of parseGrepNull(stdout, base, false)) {
+            if (!l.endsWith(":0"))
+                out.push(l);
+        }
+        return out;
+    }
+    for (const line of stdout.split("\n")) {
+        const i = line.lastIndexOf(":");
+        if (i <= 0)
+            continue;
+        const count = line.slice(i + 1);
+        if (count === "0" || !/^\d+$/.test(count))
+            continue;
+        out.push(`${base}/${displayName(line.slice(0, i))}:${count}`);
+    }
+    return out;
+}
+/** 内置工具 `Grep`：按正则搜文件内容（只读）。 */
 export function sandboxGrepTool(deps) {
     return {
         spec: SPEC,
         defaultPolicy: "allow",
         unavailable: unavailableWhenNoSandbox(deps),
-        timeoutMs: () => sandboxBaseTimeoutMs(deps.config()),
+        timeoutMs: () => sandboxBaseTimeoutMs(deps.config.get()),
         async run(input, ctx) {
             const startedAt = Date.now();
-            const { pattern, glob, ignoreCase = false } = input;
-            const path = checkPath(input.path ?? "/workspace");
-            const { value, notices } = await inSandbox(deps, ctx, async ({ h, p, signal }) => {
+            const g = input;
+            const { pattern, glob } = g;
+            const mode = g.output_mode ?? "files_with_matches";
+            const numbered = g["-n"] ?? true;
+            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));
@@ -83,10 +172,22 @@ export function sandboxGrepTool(deps) {
                 const slash = path.lastIndexOf("/");
                 const cwd = st.isDir ? path : path.slice(0, slash) || "/";
                 const target = st.isDir ? "." : path.slice(slash + 1);
+                const base = cwd === "/" ? "" : cwd;
+                // GNU grep options (`-l`, `-c`, `-n`, `-A/-B/-C`, `--null`): the sandbox images are Debian
+                const modeFlags = mode === "files_with_matches"
+                    ? ["-rlIE", "--null"]
+                    : mode === "count"
+                        ? ["-rcHIE", "--null"]
+                        : [numbered ? "-rnHIE" : "-rHIE", "--null"];
+                const context = mode === "content"
+                    ? ["-A", "-B", "-C"].flatMap((f) => g[f] !== undefined ? [f, String(g[f])] : [])
+                    : [];
                 const command = [
                     // --null：文件名后跟 NUL 而不是 `:`，文件名里有换行或冒号也能解析
-                    "grep -rnHIE --null",
-                    ...(ignoreCase ? ["-i"] : []),
+                    "grep",
+                    ...modeFlags,
+                    ...(g["-i"] === true ? ["-i"] : []),
+                    ...context,
                     ...(glob !== undefined ? [`--include=${shellQuote(glob)}`] : []),
                     "-e",
                     shellQuote(pattern),
@@ -96,34 +197,52 @@ export function sandboxGrepTool(deps) {
                 const r = await p.exec(h, {
                     command,
                     cwd,
-                    timeoutMs: searchTimeoutMs(deps.config(), startedAt, Date.now(), ctx.runDeadline),
+                    timeoutMs: searchTimeoutMs(deps.config.get(), startedAt, Date.now(), ctx.runDeadline),
                     maxOutputBytes: MAX_GREP_BYTES,
                     signal,
                 });
                 if (r.timedOut || r.exitCode === null)
                     throw new ToolError(GREP_TIMEOUT);
                 if (r.exitCode === 1)
-                    return { lines: [], warning: null };
-                const all = parseGrepNull(r.stdout, cwd === "/" ? "" : cwd);
-                const lines = all.filter((l) => !l.startsWith(`${SYNC_MARKER}:`));
+                    return { entries: [], warning: null };
+                const all = mode === "files_with_matches"
+                    ? parseFileList(r.stdout, base)
+                    : mode === "count"
+                        ? parseCounts(r.stdout, base)
+                        : parseGrepNull(r.stdout, base, numbered);
+                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));
                 const warning = r.exitCode !== 0 ? clip(r.stderr, 300) : null;
-                return { lines, warning };
+                return { entries, warning };
             });
-            const { lines, warning } = value;
-            const shown = lines
-                .slice(0, MAX_MATCHES)
-                .map((l) => (l.length > MAX_LINE_CHARS ? `${l.slice(0, MAX_LINE_CHARS)}…` : l));
+            const { entries, warning } = value;
+            const total = entries.length;
+            const offset = g.offset ?? 0;
+            const headLimit = g.head_limit === undefined ? DEFAULT_HEAD_LIMIT : g.head_limit;
+            const limit = headLimit === 0 ? MAX_MATCHES : Math.min(headLimit, MAX_MATCHES);
+            const page = entries.slice(offset, offset + limit);
+            const shown = page.map((l) => l.length > MAX_LINE_CHARS ? `${l.slice(0, MAX_LINE_CHARS)}…` : l);
             const note = warning !== null ? `\n[grep also reported errors: ${warning}]` : "";
-            const text = (lines.length === 0
-                ? `No matches for ${pattern} in ${path}.`
-                : shown.join("\n") +
-                    (lines.length > MAX_MATCHES
-                        ? `\n[Showing the first ${MAX_MATCHES} of ${lines.length} matching lines; use a narrower pattern, path or glob.]`
-                        : "")) + note;
-            const n = lines.length;
+            let text;
+            if (total === 0) {
+                text = `No matches for ${pattern} in ${path}.${note}`;
+            }
+            else if (page.length === 0) {
+                text = `No more results (${total} total).${note}`;
+            }
+            else {
+                const end = offset + page.length;
+                text =
+                    shown.join("\n") +
+                        (end < total
+                            ? `\n[Showing entries ${offset + 1}–${end} of ${total}; pass offset=${end} to continue, or use a narrower pattern, path or glob.]`
+                            : "") +
+                        note;
+            }
+            const n = total;
             return {
                 content: [{ type: "text", text: withNotices(notices, text) }],
                 display: display(`搜索 ${clip(pattern, 120)}（${n} 处）`, `Searched for ${clip(pattern, 120)} (${n} match${n === 1 ? "" : "es"})`),

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

@@ -1,12 +1,16 @@
 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_RECREATED_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";
-export { SANDBOX_ASK_TOOL_NAMES, SANDBOX_TOOL_NAMES } from "./names.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.
  */
 export declare function sandboxTools(deps: SandboxToolDeps): BuiltinTool[];

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

@@ -4,15 +4,21 @@ import { sandboxEditTool } from "./edit.js";
 import { sandboxGlobTool } from "./glob.js";
 import { sandboxGrepTool } from "./grep.js";
 import { sandboxReadTool } from "./read.js";
+import { taskOutputTool } from "./task-output.js";
+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_RECREATED_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";
-export { SANDBOX_ASK_TOOL_NAMES, SANDBOX_TOOL_NAMES } from "./names.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.
  */
 export function sandboxTools(deps) {
     return [
@@ -23,5 +29,7 @@ export function sandboxTools(deps) {
         sandboxGlobTool(deps),
         sandboxGrepTool(deps),
         sandboxDeliverTool(deps),
+        taskOutputTool(deps),
+        taskStopTool(deps),
     ];
 }

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

@@ -1,8 +1,8 @@
 import type { BuiltinTool } from "../../registry.js";
 import { type SandboxToolDeps } from "./common.js";
-/** 最多读出的字节数（更大的文件只读开头，并说明用 sandbox_bash 读其余部分）。 */
+/** 最多读出的字节数（更大的文件只读开头，并说明用 Bash 读其余部分）。 */
 export declare const READ_MAX_BYTES: number;
 /** 按行编号显示 `[offset, offset + limit)`（1 起），结尾注明还有多少行。 */
 export declare function numberLines(text: string, offset: number, limit: number): string;
-/** 内置工具 `sandbox_read`：读沙箱里的文本文件（只读，组织策略为 ask 时也不审批）。 */
+/** 内置工具 `Read`：读沙箱里的文本文件（只读，组织策略为 ask 时也不审批）。 */
 export declare function sandboxReadTool(deps: SandboxToolDeps): BuiltinTool;

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

@@ -1,28 +1,31 @@
 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;
 /** 单行最多显示的字符数（更长的截断并注明）。 */
 const MAX_LINE_CHARS = 2000;
-/** 最多读出的字节数（更大的文件只读开头，并说明用 sandbox_bash 读其余部分）。 */
+/** 最多读出的字节数（更大的文件只读开头，并说明用 Bash 读其余部分）。 */
 export const READ_MAX_BYTES = 10 * 1024 * 1024;
 const SPEC = {
-    name: "sandbox_read",
+    name: "Read",
     // Display only (the tool row; not in the fingerprint, never sent to the model).
-    keyArgs: ["path"],
+    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). " +
-        "Paths are absolute, under /workspace, /skills or /tmp. Lines are numbered from 1; pass " +
-        "offset and limit to read part of a long file. Binary files are not shown; use sandbox_bash " +
-        "to inspect them. Do not use it to list directories; use sandbox_glob instead.",
+        "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.",
     inputSchema: {
         type: "object",
         properties: {
-            path: {
+            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",
@@ -35,13 +38,13 @@ const SPEC = {
                 description: `Maximum number of lines to read. Default ${DEFAULT_LIMIT}.`,
             },
         },
-        required: ["path"],
+        required: ["file_path"],
         additionalProperties: false,
     },
     annotations: { readOnlyHint: true },
 };
-const notFound = (path) => `File not found: ${clip(path, 200)}. Check the path with sandbox_glob.`;
-const isDirectory = (path) => `${clip(path, 200)} is a directory; use sandbox_glob to list its files.`;
+const notFound = (path) => `File not found: ${clip(path, 200)}. Check the path with Glob.`;
+const isDirectory = (path) => `${clip(path, 200)} is a directory; use Glob to list its files.`;
 const pastEnd = (offset, total) => `offset ${offset} is past the end of the file (${total} lines); pass an offset of at most ${total}.`;
 /** The file's lines (a final newline does not start another line). */
 function fileLines(text) {
@@ -70,17 +73,19 @@ export function numberLines(text, offset, limit) {
     }
     return out.join("\n");
 }
-/** 内置工具 `sandbox_read`：读沙箱里的文本文件（只读，组织策略为 ask 时也不审批）。 */
+/** 内置工具 `Read`：读沙箱里的文本文件（只读，组织策略为 ask 时也不审批）。 */
 export function sandboxReadTool(deps) {
     return {
         spec: SPEC,
         defaultPolicy: "allow",
         unavailable: unavailableWhenNoSandbox(deps),
-        timeoutMs: () => sandboxBaseTimeoutMs(deps.config()),
+        timeoutMs: () => sandboxBaseTimeoutMs(deps.config.get()),
         async run(input, ctx) {
             const { offset = 1, limit = DEFAULT_LIMIT } = input;
-            const path = checkPath(input.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));
@@ -95,7 +100,7 @@ export function sandboxReadTool(deps) {
             // display only: the line range shown on the row
             let range = {};
             if (looksBinary(value.data)) {
-                text = `Binary file (${value.size} bytes); use sandbox_bash to inspect it (for example file or xxd).`;
+                text = `Binary file (${value.size} bytes); use Bash to inspect it (for example file or xxd).`;
             }
             else if (value.data.byteLength === 0) {
                 text = "(empty file)";
@@ -108,13 +113,18 @@ export function sandboxReadTool(deps) {
                     toLine: Math.min(fileLines(decoded).length, offset - 1 + limit),
                 };
                 if (value.truncated) {
-                    text += `\n[Only the first ${READ_MAX_BYTES} bytes of this ${value.size}-byte file were read; use sandbox_bash (e.g. sed -n or tail) for the rest.]`;
+                    text += `\n[Only the first ${READ_MAX_BYTES} bytes of this ${value.size}-byte file were read; use Bash (e.g. sed -n or tail) for the rest.]`;
                 }
             }
             return {
                 content: [{ type: "text", text: withNotices(notices, text) }],
                 display: display(`读取 ${clip(path, 180)}`, `Read ${clip(path, 180)}`),
-                view: { kind: "read", path: viewPath(path), ...range },
+                view: {
+                    kind: "read",
+                    path: viewPath(path),
+                    ...range,
+                    file: recordedFile(normalizeSandboxPath(path), value.data, value.size),
+                },
             };
         },
     };

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

@@ -0,0 +1,79 @@
+import { type SandboxHandle } from "@capybara-hq/plugin-sdk";
+import type { BackgroundTaskRow } from "../../../background/store.js";
+import type { HeldProvider, IfRunningResult, SandboxService } from "../../../sandbox/sandbox.service.js";
+import type { BuiltinCallContext, BuiltinTool } from "../../registry.js";
+import { type SandboxToolDeps } from "./common.js";
+/** How long `TaskOutput` waits with `block` when `timeout` is not given (ms). */
+export declare const TASK_OUTPUT_DEFAULT_TIMEOUT_MS = 30000;
+/** The longest `TaskOutput` wait (ms). */
+export declare const TASK_OUTPUT_MAX_TIMEOUT_MS = 600000;
+/** How often a blocking `TaskOutput` checks the task (each check a short exec of its own). */
+export declare const TASK_CHECK_INTERVAL_MS = 2000;
+/** What `TaskOutput` and `TaskStop` work with. */
+export interface TaskEnv {
+    store: NonNullable<SandboxToolDeps["background"]>;
+    tasks: NonNullable<SandboxToolDeps["tasks"]>;
+    ifRunning: SandboxService["ifRunning"];
+    environments: SandboxToolDeps["environments"];
+    log: SandboxToolDeps["log"];
+}
+/**
+ * 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.
+ */
+export declare function ownedTask(env: TaskEnv, ctx: BuiltinCallContext, id: string): Promise<BackgroundTaskRow>;
+/**
+ * The per-call access re-check of every sandbox tool (`inSandbox`): the conversation's environment
+ * may still be used by its owner. The task tools read a task's own instance without `inSandbox`,
+ * so they check here first; errors become the tools' errors.
+ */
+export declare function recheckEnvironment(env: TaskEnv, ctx: BuiltinCallContext): Promise<void>;
+/**
+ * `ifRunning` on the task's own environment instance (its execs act for the task's trigger in its
+ * conversation); sandbox errors become the tools' errors. A task from before environments has no
+ * instance (`not_running`).
+ */
+export declare function onTaskInstance<T>(env: TaskEnv, task: BackgroundTaskRow, fn: (p: HeldProvider, h: SandboxHandle, signal: AbortSignal) => Promise<T>, signal: AbortSignal): Promise<IfRunningResult<T>>;
+/**
+ * The task's status line: `Status: running (2m05s)`, `Status: failed, exit code 3, after 4m12s`,
+ * `Status: stopped after 1m00s`, `Status: lost (the sandbox was suspended) after 3s`.
+ */
+export declare function statusLine(task: BackgroundTaskRow, now?: Date): string;
+/** The absolute path of the task's output file, as the model sees it. */
+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 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
+ * status line.
+ */
+export declare function taskReadScript(t: {
+    id: string;
+    sid: string | null;
+    running: boolean;
+}, offset: number, cap: number, read?: boolean): string;
+/**
+ * The bytes of `buf` up to its last whole UTF-8 character: a character cut by the read's cap is
+ * left for the next read.
+ */
+export declare function wholeUtf8Length(buf: Uint8Array): number;
+/**
+ * Built-in `TaskOutput` (spec 2026-11-05-background-bash-design §2.2): a task's status and the
+ * output since this conversation's last read of it. Every check is a short exec through
+ * `SandboxService.ifRunning` on the task's own sandbox instance: it never creates or resumes a
+ * sandbox, so a suspended or rebuilt one means the task is lost (its output unavailable). With
+ * `block`, checks every {@link TASK_CHECK_INTERVAL_MS}, each under a lease of its own, until the
+ * task ends or the wait (at most `timeout` and the run's time left) is over; the checks only
+ * detect the end, and the one read that makes the result finishes the task (reported). The output
+ * read is capped at `tools.outputSpillChars` bytes; the pipeline spills the result beyond that.
+ */
+export declare function taskOutputTool(deps: SandboxToolDeps): BuiltinTool;