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

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";
-/** 最多返回的匹配行数。 */
+/** 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.",
+        '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: {
@@ -33,24 +41,66 @@ const SPEC = {
                 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,22 +109,58 @@ 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 g = input;
+            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 }) => {
                 const st = await p.stat(h, path, signal);
                 if (st === null)
@@ -83,10 +169,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 +194,53 @@ 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 entries = all.filter((l) => l !== SYNC_MARKER &&
+                    !l.startsWith(`${SYNC_MARKER}:`) &&
+                    !l.startsWith(`${SYNC_MARKER}-`));
                 // 退出码 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,9 +1,9 @@
 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 { 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`。没有沙箱提供方时报不可用。

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

@@ -5,10 +5,10 @@ import { sandboxGlobTool } from "./glob.js";
 import { sandboxGrepTool } from "./grep.js";
 import { sandboxReadTool } from "./read.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 { 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`。没有沙箱提供方时报不可用。

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,25 +1,27 @@
 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 { 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.",
+        "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".',
@@ -35,13 +37,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,16 +72,16 @@ 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 path = checkPath(input.file_path, "file_path");
             const { value, notices } = await inSandbox(deps, ctx, async ({ h, p, signal }) => {
                 const st = await p.stat(h, path, signal);
                 if (st === null)
@@ -95,7 +97,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 +110,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/write.d.ts

@@ -1,4 +1,4 @@
 import type { BuiltinTool } from "../../registry.js";
 import { type SandboxToolDeps } from "./common.js";
-/** 内置工具 `sandbox_write`：整文件写入。 */
+/** 内置工具 `Write`：整文件写入。 */
 export declare function sandboxWriteTool(deps: SandboxToolDeps): BuiltinTool;

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

@@ -1,26 +1,29 @@
-import { isSandboxGoneError, ToolError } from "@capybara-hq/plugin-sdk";
+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 { assertReadAndUnchanged, fileStateOf, normalizeSandboxPath, recordedFile, } from "./file-state.js";
+import { READ_MAX_BYTES } from "./read.js";
 const SPEC = {
-    name: "sandbox_write",
+    name: "Write",
     // Display only (the tool row; not in the fingerprint, never sent to the model).
-    keyArgs: ["path"],
+    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). To change part of an existing file, use sandbox_edit instead; to give a file to " +
-        "the user, use sandbox_deliver.",
+        "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: {
         type: "object",
         properties: {
-            path: {
+            file_path: {
                 type: "string",
                 minLength: 1,
                 description: 'Absolute path of the file, e.g. "/workspace/report.md".',
             },
             content: { type: "string", description: "The complete new content of the file." },
         },
-        required: ["path", "content"],
+        required: ["file_path", "content"],
         additionalProperties: false,
     },
 };
@@ -30,16 +33,17 @@ const SPEC = {
  * result carries no view.
  */
 const PREVIOUS_MAX_BYTES = TOOL_VIEW_DIFF_MAX_BYTES;
+const vanished = (path) => `${clip(path, 200)} disappeared while it was being written; retry the call.`;
 const isDirectory = (path) => `${clip(path, 200)} is a directory; pass the path of a file inside it.`;
-/** 内置工具 `sandbox_write`：整文件写入。 */
+/** 内置工具 `Write`：整文件写入。 */
 export function sandboxWriteTool(deps) {
     return {
         spec: SPEC,
         defaultPolicy: "allow",
         unavailable: unavailableWhenNoSandbox(deps),
-        timeoutMs: () => sandboxBaseTimeoutMs(deps.config()),
+        timeoutMs: () => sandboxBaseTimeoutMs(deps.config.get()),
         async run(input, ctx) {
-            const path = checkWritable(input.path);
+            const path = checkWritable(input.file_path);
             const data = new TextEncoder().encode(input.content);
             const { value, notices } = await inSandbox(deps, ctx, ({ h, p, signal }) => 
             // stat, read the previous content, write: one holder at a time per file
@@ -47,24 +51,21 @@ export function sandboxWriteTool(deps) {
                 const st = await p.stat(h, path, signal);
                 if (st?.isDir)
                     throw new ToolError(isDirectory(path));
-                // the previous content, for the diff on the row (display only: a failure here never
-                // fails the write, the result just carries no view)
+                // 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) {
-                    try {
-                        const got = st.size <= PREVIOUS_MAX_BYTES
-                            ? await p.readFile(h, path, { maxBytes: PREVIOUS_MAX_BYTES, signal })
-                            : null;
-                        previous =
-                            got === null || got.truncated || looksBinary(got.data) || got.data.includes(0)
-                                ? null
-                                : new TextDecoder().decode(got.data);
-                    }
-                    catch (e) {
-                        if (signal.aborted || isSandboxGoneError(e))
-                            throw e;
-                        previous = 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 };
@@ -74,14 +75,17 @@ export function sandboxWriteTool(deps) {
             return {
                 content: [{ type: "text", text: withNotices(notices, text) }],
                 display: display(`写入 ${clip(path, 180)}`, `Wrote ${clip(path, 180)}`),
-                ...(previous !== null && {
-                    view: {
-                        kind: "edit",
-                        path: viewPath(path),
-                        created: !existed,
-                        ...lineDiff(previous, input.content),
-                    },
-                }),
+                // the view always carries the file state: the next Write / Edit of the path needs it
+                view: {
+                    kind: "edit",
+                    path: viewPath(path),
+                    created: !existed,
+                    ...(previous !== null
+                        ? lineDiff(previous, input.content)
+                        : { added: 0, removed: 0, truncated: true, hunks: [] }),
+                    // over the bytes the next Write / Edit reads back (Read's limit), as Read records it
+                    file: recordedFile(normalizeSandboxPath(path), data.subarray(0, READ_MAX_BYTES), data.byteLength),
+                },
             };
         },
     };

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

@@ -1,11 +1,11 @@
 import { type ObjectStore } from "@capybara-hq/plugin-sdk";
 import type { EventLog } from "../../conversations/event-log.js";
-import type { KernelDb, SkillManifest } from "../../db/kernel-schema.js";
+import type { KernelSchemaDb, SkillManifest } from "../../db/kernel-schema.js";
 import { type CatalogSkill } from "../../runtime/context/skills.js";
 import type { BuiltinCallContext, BuiltinTool } from "../registry.js";
 import { type SandboxToolDeps } from "./sandbox/common.js";
 /**
- * 内置工具 `skill_load`（M5 T14，Ruling M17）：按日志里最新一份技能目录快照把名字解析为 id 与版本，返回该版本
+ * 内置工具 `Skill`（M5 T14，Ruling M17）：按日志里最新一份技能目录快照把名字解析为 id 与版本，返回该版本
  * SKILL.md 的正文与文件清单（结果里写明版本）。技能带其他文件时把整个技能复制进本对话沙箱的 `/skills/<name>/`
  * （提供方以 root 写，命令用户只读）；没有沙箱提供方时只给正文，并说明脚本不可用。
  *
@@ -27,8 +27,8 @@ export declare const SKILLS_MARKER_DIR = "/skills/.capybara";
 export declare const skillMarkerPath: (name: string) => string;
 /** 依赖：沙箱工具的依赖，加上读技能行用的库与读快照用的日志。 */
 export interface SkillLoadDeps extends SandboxToolDeps {
-    db: KernelDb;
-    eventLog: Pick<EventLog, "append" | "latestOfType">;
+    db: KernelSchemaDb;
+    eventLog: Pick<EventLog, "append" | "latestOfType" | "latestFileState">;
 }
 /** A stored skill file is missing or does not match its manifest entry (size, sha256). */
 export declare class SkillIntegrityError extends Error {
@@ -45,9 +45,9 @@ export declare function readSkillFile(store: ObjectStore, key: string, file: Ski
  * 没有 `skill_versions` 行，新技能连 `skills` 行都没有）。绝不按版本号解析——被拒绝的草稿与之后别人批准的同号版本
  * 内容不同。都没有 → undefined（已移除）。
  */
-export declare function findSkillVersion(db: KernelDb, ctx: Pick<BuiltinCallContext, "orgId" | "conversationId">, entry: Pick<CatalogSkill, "id" | "source">): Promise<{
+export declare function findSkillVersion(db: KernelSchemaDb, ctx: Pick<BuiltinCallContext, "orgId" | "conversationId">, entry: Pick<CatalogSkill, "id" | "source">): Promise<{
     manifest: SkillManifest;
     object_prefix: string;
 } | undefined>;
-/** 内置工具 `skill_load`（见文件头）。 */
+/** 内置工具 `Skill`（见文件头）。 */
 export declare function skillLoadTool(deps: SkillLoadDeps): BuiltinTool;