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

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

@@ -1,15 +1,14 @@
-import { ToolError } from "@capybara-hq/plugin-sdk";
 import { clip, display, inSandbox, runBudgetNote, runTimeLeftMs, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, withNotices, } from "./common.js";
-/** 不给 `timeoutSeconds` 时的命令超时（秒），不超过 `sandbox.limits.maxCommandSeconds`。 */
+/** The command timeout in seconds when `timeout` is not given, at most `sandbox.limits.maxCommandSeconds`. */
 export const BASH_DEFAULT_TIMEOUT_SECONDS = 120;
 /** The longest `description` (the shell row shows it instead of the command). */
 export const BASH_DESCRIPTION_MAX_CHARS = 120;
-/** bash 结果超过这么多字符即转存（走现有输出存档，模型用 read_tool_output 分页读）。 */
+/** bash 结果超过这么多字符即转存（走现有输出存档，模型用 ReadToolOutput 分页读）。 */
 export const BASH_SPILL_CHARS = 30_000;
 /** 一次命令最多收集的输出字节（stdout + stderr）；超出的丢弃并在结果里说明。 */
 const MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
 const SPEC = {
-    name: "sandbox_bash",
+    name: "Bash",
     // Display only (the tool row; not in the fingerprint, never sent to the model).
     keyArgs: ["command"],
     description: "Run a shell command (bash) in this conversation's sandbox, an isolated Linux machine. " +
@@ -20,10 +19,10 @@ const SPEC = {
         "Files the user attached to the conversation are under /workspace/attachments, " +
         "and skill files under /skills (read-only). Each call runs in a fresh shell (no state such as " +
         "cd or environment variables carries over). The result has stdout, stderr and the exit code; " +
-        "long output is saved and can be paged with read_tool_output. A command that runs longer than " +
-        "timeoutSeconds is stopped. Prefer sandbox_read, sandbox_write, sandbox_edit, sandbox_glob and " +
-        "sandbox_grep for reading, writing and searching files. To give a file to the user, use " +
-        "sandbox_deliver. Other sub-agents of this conversation may run commands in this sandbox at " +
+        "long output is saved and can be paged with ReadToolOutput. A command that runs longer than " +
+        "timeout milliseconds is stopped. Prefer Read, Write, Edit, Glob and " +
+        "Grep for reading, writing and searching files. To give a file to the user, use " +
+        "Deliver. Other sub-agents of this conversation may run commands in this sandbox at " +
         "the same time. Always pass description: a few words saying what the command is for; the " +
         "user sees it instead of the command.",
     inputSchema: {
@@ -40,21 +39,21 @@ const SPEC = {
                 maxLength: BASH_DESCRIPTION_MAX_CHARS,
                 description: 'What this command does, in a few words (e.g. "Generate the final PDF"). Shown to the user.',
             },
-            timeoutSeconds: {
+            timeout: {
                 type: "integer",
                 minimum: 1,
-                description: `Seconds before the command is stopped. Default ${BASH_DEFAULT_TIMEOUT_SECONDS}; the deployment sets a maximum (7200 by default).`,
+                description: `Milliseconds before the command is stopped. Default ${BASH_DEFAULT_TIMEOUT_SECONDS * 1000}; the deployment sets a maximum (7200000 by default); a larger value is lowered to it.`,
             },
         },
         required: ["command", "description"],
         additionalProperties: false,
     },
 };
-/** 本次命令的超时（秒）：给定的值，或默认值（不超过上限）。 */
-const secondsFor = (input, max) => input.timeoutSeconds ?? Math.min(BASH_DEFAULT_TIMEOUT_SECONDS, max);
+/** This command's timeout in milliseconds: the given value or the default, at most the maximum. */
+const msFor = (input, maxSeconds) => Math.min(input.timeout ?? BASH_DEFAULT_TIMEOUT_SECONDS * 1000, maxSeconds * 1000);
 /**
  * 命令结果 → 给模型的文本。`budgetClamped`：运行的时限把超时收紧到了 `seconds`（Ruling M20），超时说明改为
- * 指向 `runtime.maxRunSeconds`，而不是让模型加大 timeoutSeconds。
+ * 指向 `runtime.maxRunSeconds`，而不是让模型加大 timeout。
  */
 export function formatExec(r, seconds, budgetClamped = false) {
     const parts = [];
@@ -68,7 +67,7 @@ export function formatExec(r, seconds, budgetClamped = false) {
         parts.push(`[timedOut: the command did not finish within ${seconds}s and was stopped. ${runBudgetNote(seconds)} The sandbox is still usable; split the work into shorter steps that save progress to files under /workspace, or run long jobs in the background and check on them in a later run.]`);
     }
     else if (r.timedOut) {
-        parts.push(`[timedOut: the command did not finish within ${seconds}s and was stopped. The sandbox is still usable; pass a larger timeoutSeconds (up to the deployment maximum), or split the work into shorter steps that save progress to files under /workspace.]`);
+        parts.push(`[timedOut: the command did not finish within ${seconds}s and was stopped. The sandbox is still usable; pass a larger timeout in milliseconds (up to the deployment maximum), or split the work into shorter steps that save progress to files under /workspace.]`);
     }
     else if (r.exitCode === null) {
         parts.push("[The command was stopped before it finished; its effects may be partial. Check the sandbox state before retrying.]");
@@ -80,7 +79,7 @@ export function formatExec(r, seconds, budgetClamped = false) {
     }
     return parts.join("\n");
 }
-/** 内置工具 `sandbox_bash`：在本对话的沙箱里执行命令。 */
+/** 内置工具 `Bash`：在本对话的沙箱里执行命令。 */
 export function sandboxBashTool(deps) {
     return {
         spec: SPEC,
@@ -89,35 +88,39 @@ export function sandboxBashTool(deps) {
         unavailable: unavailableWhenNoSandbox(deps),
         // 命令自己的超时先到（提供方停掉命令、返回 timedOut），管线的时限再留出等锁与创建 / 恢复的余量
         timeoutMs: (input) => {
-            const cfg = deps.config();
+            const cfg = deps.config.get();
             const max = cfg.sandbox.limits.maxCommandSeconds;
-            return Math.min(secondsFor(input, max), max) * 1000 + sandboxBaseTimeoutMs(cfg);
+            return msFor(input, max) + sandboxBaseTimeoutMs(cfg);
         },
         async run(input, ctx) {
             const { command, description } = input;
-            const max = deps.config().sandbox.limits.maxCommandSeconds;
-            const req = input.timeoutSeconds;
-            if (req !== undefined && req > max) {
-                throw new ToolError(`timeoutSeconds ${req} is over the limit of ${max} seconds; pass a value of at most ${max}.`);
-            }
-            const asked = secondsFor(input, max);
-            // 运行截止前命令要自己超时（Ruling M20）：在拿到沙箱之后算，等锁与恢复用掉的时间一并扣掉
-            let seconds = asked;
+            const max = deps.config.get().sandbox.limits.maxCommandSeconds;
+            const requested = input.timeout;
+            const maxMs = max * 1000;
+            const askedMs = msFor(input, max);
+            // The run's deadline makes the command time out itself first (Ruling M20): counted after the
+            // sandbox is obtained, so the time spent waiting for the lock and resuming is deducted
+            let ms = askedMs;
             const { value: r, notices } = await inSandbox(deps, ctx, ({ h, p, signal }) => {
-                const left = Math.floor(runTimeLeftMs(ctx.runDeadline) / 1000);
-                seconds = Math.max(1, Math.min(asked, left));
+                const left = Math.floor(runTimeLeftMs(ctx.runDeadline) / 1000) * 1000;
+                ms = Math.max(1000, Math.min(askedMs, left));
                 return p.exec(h, {
                     command,
                     cwd: "/workspace",
-                    timeoutMs: seconds * 1000,
+                    timeoutMs: ms,
                     maxOutputBytes: MAX_OUTPUT_BYTES,
                     signal,
                 });
             });
-            const clamped = seconds < asked;
+            const seconds = ms / 1000;
+            const clamped = ms < askedMs;
             const shown = clip(command, 120);
+            const lowered = requested !== undefined && requested > maxMs
+                ? `\n[timeout ${requested} ms is over the deployment maximum; it was lowered to ${maxMs} ms.]`
+                : "";
+            const text = formatExec(r, seconds, clamped) + lowered;
             return {
-                content: [{ type: "text", text: withNotices(notices, formatExec(r, seconds, clamped)) }],
+                content: [{ type: "text", text: withNotices(notices, text) }],
                 isError: r.timedOut || r.exitCode === null,
                 // display only: a non-zero exit shows as failed on the row, `isError` stays as it was
                 view: {

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

@@ -2,6 +2,7 @@ import { type SandboxHandle, type SandboxProvider } from "@capybara-hq/plugin-sd
 import type { KernelConfig } from "../../../config/schema.js";
 import type { AttachmentsService } from "../../../conversations/attachments.service.js";
 import type { EventLog } from "../../../conversations/event-log.js";
+import type { KernelConfigService } from "../../../infra/config/kernel-config.service.js";
 import { type SandboxService } from "../../../sandbox/sandbox.service.js";
 import type { StorageService } from "../../../storage/storage.service.js";
 import type { BuiltinCallContext } from "../../registry.js";
@@ -11,9 +12,9 @@ export interface SandboxToolDeps {
     sandbox: Pick<SandboxService, "available" | "withSandbox"> & Partial<Pick<SandboxService, "pathLease">>;
     attachments: Pick<AttachmentsService, "listForConversation" | "openForConversation">;
     storage: Pick<StorageService, "kernel" | "available">;
-    /** `publishChanged`: `sandbox_deliver` announces `changed: files` (UI refresh B). */
-    eventLog: Pick<EventLog, "append"> & Partial<Pick<EventLog, "publishChanged">>;
-    config: () => KernelConfig;
+    /** `publishChanged`: `Deliver` announces `changed: files` (UI refresh B). */
+    eventLog: Pick<EventLog, "append" | "latestFileState"> & Partial<Pick<EventLog, "publishChanged">>;
+    config: Pick<KernelConfigService, "get">;
 }
 /** 回调拿到的沙箱：句柄、提供方与「调用 signal + 锁丢失」合并后的 signal（每个提供方调用都传它）。 */
 export interface SandboxSession {
@@ -79,7 +80,7 @@ export declare function clip(s: string, max: number): string;
 export declare function withNotices(notices: readonly string[], text: string): string;
 /** 校验沙箱内路径（`validateSandboxPath`）；不合法抛给模型可执行的错误。 */
 export declare function checkPath(path: string, field?: string): string;
-/** 写入类工具的路径：`/skills` 是技能文件的只读副本。 */
+/** A writing tool's `file_path`: `/skills` is the read-only copy of the skill files. */
 export declare function checkWritable(path: string): string;
 /** POSIX shell 单引号转义。 */
 export declare function shellQuote(s: string): string;

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

@@ -78,9 +78,9 @@ export function checkPath(path, field = "path") {
     }
     return path.length > 1 && path.endsWith("/") ? path.slice(0, -1) : path;
 }
-/** 写入类工具的路径：`/skills` 是技能文件的只读副本。 */
+/** A writing tool's `file_path`: `/skills` is the read-only copy of the skill files. */
 export function checkWritable(path) {
-    const p = checkPath(path);
+    const p = checkPath(path, "file_path");
     if (p === "/skills" || p.startsWith("/skills/")) {
         throw new ToolError(`Path ${clip(p, 200)} is read-only (/skills holds skill files); pass a path under /workspace or /tmp instead.`);
     }

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

@@ -1,5 +1,5 @@
 import type { BuiltinTool } from "../../registry.js";
 import { type SandboxToolDeps } from "./common.js";
 export declare function contentTypeFor(name: string): string;
-/** 内置工具 `sandbox_deliver`：把沙箱里的文件存进对象存储，写 `artifact_created`，用户可下载。 */
+/** 内置工具 `Deliver`：把沙箱里的文件存进对象存储，写 `artifact_created`，用户可下载。 */
 export declare function sandboxDeliverTool(deps: SandboxToolDeps): BuiltinTool;

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

@@ -4,18 +4,18 @@ import { isValidArtifactName } from "../../../conversations/events.js";
 import { ApiError } from "../../../errors.js";
 import { checkPath, clip, display, inSandbox, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, withNotices, } from "./common.js";
 const SPEC = {
-    name: "sandbox_deliver",
+    name: "Deliver",
     // Display only (the tool row; not in the fingerprint, never sent to the model).
-    keyArgs: ["path"],
+    keyArgs: ["file_path"],
     description: "Deliver a file from this conversation's sandbox to the user as a downloadable artifact. Use " +
         "it when the user should receive a file you produced (a report, chart, spreadsheet, archive " +
         "and so on); files that stay in the sandbox are not visible to the user. Delivers one file " +
-        "per call; archive a directory first (e.g. zip -r with sandbox_bash). The file size is " +
+        "per call; archive a directory first (e.g. tar -czf with Bash). The file size is " +
         "limited (100 MB by default). Do not use it for intermediate files the user does not need.",
     inputSchema: {
         type: "object",
         properties: {
-            path: {
+            file_path: {
                 type: "string",
                 minLength: 1,
                 description: 'Absolute path of the file in the sandbox, e.g. "/workspace/out/report.pdf".',
@@ -24,10 +24,10 @@ const SPEC = {
                 type: "string",
                 minLength: 1,
                 maxLength: MEDIA_NAME_MAX_CHARS,
-                description: 'File name shown to the user, e.g. "Q3 report.pdf". Default: the file name in path.',
+                description: 'File name shown to the user, e.g. "Q3 report.pdf". Default: the file name in file_path.',
             },
         },
-        required: ["path"],
+        required: ["file_path"],
         additionalProperties: false,
     },
 };
@@ -71,9 +71,9 @@ export function contentTypeFor(name) {
     const ext = dot > 0 ? name.slice(dot + 1).toLowerCase() : "";
     return CONTENT_TYPES[ext] ?? "application/octet-stream";
 }
-const notFound = (path) => `File not found: ${clip(path, 200)}. Check the path with sandbox_glob.`;
-const isDirectory = (path) => `${clip(path, 200)} is a directory; deliver one file, e.g. archive the directory first with sandbox_bash (zip -r) and retry.`;
-const tooLarge = (path, size, max) => `File ${clip(path, 200)} is ${size} bytes, over the delivery limit of ${max} bytes; compress or split it with sandbox_bash and retry.`;
+const notFound = (path) => `File not found: ${clip(path, 200)}. Check the path with Glob.`;
+const isDirectory = (path) => `${clip(path, 200)} is a directory; deliver one file, e.g. archive the directory first with Bash (tar -czf) and retry.`;
+const tooLarge = (path, size, max) => `File ${clip(path, 200)} is ${size} bytes, over the delivery limit of ${max} bytes; compress or split it with Bash and retry.`;
 const BAD_NAME = "name must not contain control characters, / or \\; pass a plain file name such as report.pdf.";
 /** 默认产物名：路径的文件名部分，过长时保留末尾（扩展名）截到 255 个 UTF-16 单元以内。 */
 function defaultName(path) {
@@ -90,26 +90,26 @@ function defaultName(path) {
 const NO_STORAGE = "File storage is not configured in this deployment, so files cannot be delivered; ask an administrator, or provide the result in your reply instead.";
 /** 「工具不可用」提醒里的原因（内核在后面补句号）。 */
 const NO_STORAGE_REASON = NO_STORAGE.slice(0, -1);
-/** 内置工具 `sandbox_deliver`：把沙箱里的文件存进对象存储，写 `artifact_created`，用户可下载。 */
+/** 内置工具 `Deliver`：把沙箱里的文件存进对象存储，写 `artifact_created`，用户可下载。 */
 export function sandboxDeliverTool(deps) {
     return {
         spec: SPEC,
         defaultPolicy: "allow",
         // 没有沙箱或没有对象存储都交付不了（先报沙箱的原因）
         unavailable: () => unavailableWhenNoSandbox(deps)() ?? (deps.storage.available ? null : NO_STORAGE_REASON),
-        timeoutMs: () => 2 * sandboxBaseTimeoutMs(deps.config()),
+        timeoutMs: () => 2 * sandboxBaseTimeoutMs(deps.config.get()),
         async run(input, ctx) {
             // 存储在调用前就核对：不为一个交付不了的文件去 stat / 读沙箱
             if (!deps.storage.available)
                 throw new ToolError(NO_STORAGE);
-            const path = checkPath(input.path);
+            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().sandbox.deliverMaxBytes;
+            const max = deps.config.get().sandbox.deliverMaxBytes;
             const { value: data, notices } = await inSandbox(deps, ctx, async ({ h, p, signal }) => {
                 const st = await p.stat(h, path, signal);
                 if (st === null)

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

@@ -1,4 +1,4 @@
 import type { BuiltinTool } from "../../registry.js";
 import { type SandboxToolDeps } from "./common.js";
-/** 内置工具 `sandbox_edit`：按精确文本替换。 */
+/** 内置工具 `Edit`：按精确文本替换。 */
 export declare function sandboxEditTool(deps: SandboxToolDeps): BuiltinTool;

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

@@ -1,40 +1,42 @@
 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";
-/** 可编辑的最大文件（字节）：更大的用 sandbox_bash 处理。 */
+import { assertReadAndUnchanged, fileStateOf, normalizeSandboxPath, recordedFile, } from "./file-state.js";
+import { READ_MAX_BYTES } from "./read.js";
+/** 可编辑的最大文件（字节）：更大的用 Bash 处理。 */
 const EDIT_MAX_BYTES = 10 * 1024 * 1024;
 const SPEC = {
-    name: "sandbox_edit",
+    name: "Edit",
     // Display only (the tool row; not in the fingerprint, never sent to the model).
-    keyArgs: ["path"],
-    description: "Edit a text file in this conversation's sandbox by replacing exact text. oldText must match " +
-        "the file exactly (including whitespace and indentation) and, unless replaceAll is true, occur " +
-        "exactly once; include enough surrounding lines to make it unique. Read the file with " +
-        "sandbox_read first. Use sandbox_write to create a file or replace all of it.",
+    keyArgs: ["file_path"],
+    description: "Edit a text file in this conversation's sandbox by replacing exact text. old_string must match " +
+        "the file exactly (including whitespace and indentation) and, unless replace_all is true, occur " +
+        "exactly once; include enough surrounding lines to make it unique. Read the file first; " +
+        "editing a file you have not read, or one changed since you read it, fails. Use Write to create a file or replace all of it.",
     inputSchema: {
         type: "object",
         properties: {
-            path: {
+            file_path: {
                 type: "string",
                 minLength: 1,
                 description: 'Absolute path of the file, e.g. "/workspace/src/app.py".',
             },
-            oldText: { type: "string", minLength: 1, description: "The exact text to replace." },
-            newText: { type: "string", description: "The replacement text." },
-            replaceAll: {
+            old_string: { type: "string", minLength: 1, description: "The exact text to replace." },
+            new_string: { type: "string", description: "The replacement text." },
+            replace_all: {
                 type: "boolean",
-                description: "Replace every occurrence of oldText instead of exactly one. Default false.",
+                description: "Replace every occurrence of old_string instead of exactly one. Default false.",
             },
         },
-        required: ["path", "oldText", "newText"],
+        required: ["file_path", "old_string", "new_string"],
         additionalProperties: false,
     },
 };
-const notFound = (path) => `File not found: ${clip(path, 200)}. Check the path with sandbox_glob, or use sandbox_write to create it.`;
-const notText = (path) => `${clip(path, 200)} is a directory, a binary file or larger than ${EDIT_MAX_BYTES} bytes; use sandbox_bash to change it.`;
-const SAME_TEXT = "oldText and newText are the same; pass the text you want to change and its replacement.";
-const noMatch = (path) => `oldText was not found in ${clip(path, 200)}; call sandbox_read and pass the exact text, including whitespace.`;
-const ambiguous = (n) => `oldText occurs ${n} times; pass more surrounding text to make it unique, or pass replaceAll: true.`;
+const notFound = (path) => `File not found: ${clip(path, 200)}. Check the path with Glob, or use Write to create it.`;
+const notText = (path) => `${clip(path, 200)} is a directory, a binary file or larger than ${EDIT_MAX_BYTES} bytes; use Bash to change it.`;
+const SAME_TEXT = "old_string and new_string are the same; pass the text you want to change and its replacement.";
+const noMatch = (path) => `old_string was not found in ${clip(path, 200)}; call Read and pass the exact text, including whitespace.`;
+const ambiguous = (n) => `old_string occurs ${n} times; pass more surrounding text to make it unique, or pass replace_all: true.`;
 /** 出现次数（不重叠）。 */
 function occurrences(text, sub) {
     let n = 0;
@@ -42,17 +44,17 @@ function occurrences(text, sub) {
         n++;
     return n;
 }
-/** 内置工具 `sandbox_edit`：按精确文本替换。 */
+/** 内置工具 `Edit`：按精确文本替换。 */
 export function sandboxEditTool(deps) {
     return {
         spec: SPEC,
         defaultPolicy: "allow",
         unavailable: unavailableWhenNoSandbox(deps),
-        timeoutMs: () => sandboxBaseTimeoutMs(deps.config()),
+        timeoutMs: () => sandboxBaseTimeoutMs(deps.config.get()),
         async run(input, ctx) {
-            const { oldText, newText, replaceAll = false } = input;
-            const path = checkWritable(input.path);
-            if (oldText === newText)
+            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, ({ h, p, signal }) => 
             // read, replace, write: one holder at a time per file
@@ -67,18 +69,26 @@ export function sandboxEditTool(deps) {
                     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, oldText);
+                const count = occurrences(text, old_string);
                 if (count === 0)
                     throw new ToolError(noMatch(path));
-                if (count > 1 && !replaceAll)
+                if (count > 1 && !replace_all)
                     throw new ToolError(ambiguous(count));
-                // 用函数形式替换：newText 里的 `$&` 等不被当成替换模式
-                const next = replaceAll
-                    ? text.split(oldText).join(newText)
-                    : text.replace(oldText, () => newText);
-                await p.writeFile(h, path, new TextEncoder().encode(next), signal);
-                return { n: replaceAll ? count : 1, before: text, after: next };
+                // 用函数形式替换：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"}.`;
@@ -91,6 +101,7 @@ export function sandboxEditTool(deps) {
                     path: viewPath(path),
                     created: false,
                     ...lineDiff(edit.before, edit.after),
+                    file: edit.file,
                 },
             };
         },

package/dist/tools/builtins/sandbox/file-state.d.ts

@@ -0,0 +1,34 @@
+import type { EventLog } from "../../../conversations/event-log.js";
+/**
+ * Read before `Write` / `Edit` (tool naming spec §4.5). The state of a file as a `Read`, `Write` or
+ * `Edit` saw or left it is recorded in the display-only `tool_result.view.file`; before writing,
+ * the tools compare the latest recorded state of the path in this conversation's log with the
+ * content they read anyway. Nothing lives in process memory, so every replica decides the same.
+ */
+export interface FileState {
+    /** The file's full size in bytes. */
+    size: number;
+    /** sha256 (hex) of the bytes handled: the first bytes only for a file over `Read`'s byte limit. */
+    sha256: string;
+}
+/** What the tools put into `view.file`: the state plus the full normalized path (never cut). */
+export interface RecordedFile extends FileState {
+    path: string;
+}
+export declare const NOT_READ_TEXT = "File has not been read yet. Read it first before writing to it.";
+export declare const MODIFIED_TEXT = "File has been modified since it was read, either by the user or by another command. Read it again before writing to it.";
+/** The state of `bytes`, the bytes handled of a file whose full size is `fullSize`. */
+export declare function fileStateOf(bytes: Uint8Array, fullSize: number): FileState;
+/** The `view.file` value for a file at `path` (already normalized). */
+export declare function recordedFile(path: string, bytes: Uint8Array, fullSize: number): RecordedFile;
+/** POSIX-normalized absolute path (`/workspace/./a.txt` and `/workspace/a.txt` are one file). */
+export declare function normalizeSandboxPath(path: string): string;
+/** The latest recorded state of `path` in the conversation's log; null when it was never recorded. */
+export declare function lastFileState(log: Pick<EventLog, "latestFileState">, conversationId: string, path: string): Promise<FileState | null>;
+/**
+ * Throws the model-visible error unless the conversation read (or wrote) the file and it is
+ * unchanged: `current` is the state of the content the caller just read.
+ */
+export declare function assertReadAndUnchanged(deps: {
+    eventLog: Pick<EventLog, "latestFileState">;
+}, conversationId: string, path: string, current: FileState): Promise<void>;

package/dist/tools/builtins/sandbox/file-state.js

@@ -0,0 +1,34 @@
+import { createHash } from "node:crypto";
+import { posix } from "node:path";
+import { ToolError } from "@capybara-hq/plugin-sdk";
+export const NOT_READ_TEXT = "File has not been read yet. Read it first before writing to it.";
+export const MODIFIED_TEXT = "File has been modified since it was read, either by the user or by another command. Read it again before writing to it.";
+/** The state of `bytes`, the bytes handled of a file whose full size is `fullSize`. */
+export function fileStateOf(bytes, fullSize) {
+    return { size: fullSize, sha256: createHash("sha256").update(bytes).digest("hex") };
+}
+/** The `view.file` value for a file at `path` (already normalized). */
+export function recordedFile(path, bytes, fullSize) {
+    return { path, ...fileStateOf(bytes, fullSize) };
+}
+/** POSIX-normalized absolute path (`/workspace/./a.txt` and `/workspace/a.txt` are one file). */
+export function normalizeSandboxPath(path) {
+    const n = posix.normalize(path);
+    return n.length > 1 && n.endsWith("/") ? n.slice(0, -1) : n;
+}
+/** The latest recorded state of `path` in the conversation's log; null when it was never recorded. */
+export async function lastFileState(log, conversationId, path) {
+    return log.latestFileState(conversationId, normalizeSandboxPath(path));
+}
+/**
+ * Throws the model-visible error unless the conversation read (or wrote) the file and it is
+ * unchanged: `current` is the state of the content the caller just read.
+ */
+export async function assertReadAndUnchanged(deps, conversationId, path, current) {
+    const seen = await lastFileState(deps.eventLog, conversationId, path);
+    if (seen === null)
+        throw new ToolError(NOT_READ_TEXT);
+    if (seen.size !== current.size || seen.sha256 !== current.sha256) {
+        throw new ToolError(MODIFIED_TEXT);
+    }
+}

package/dist/tools/builtins/sandbox/glob-match.d.ts

@@ -1,5 +1,5 @@
 /**
- * 线性时间的 glob 匹配（sandbox_glob 用；模式由模型给出，不能编译成会回溯爆炸的正则）。
+ * 线性时间的 glob 匹配（Glob 用；模式由模型给出，不能编译成会回溯爆炸的正则）。
  *
  * 语法：路径按 `/` 分段；整段 `**` 跨任意层目录（含零层）；段内 `*` 匹配任意个字符（不跨 `/`），`?` 一个字符，
  * `[abc]` / `[a-z]` / `[!x]`（或 `[^x]`）字符类，`{a,b}` 二选一（可嵌套，展开后最多 {@link MAX_ALTERNATIVES} 个）；

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

@@ -1,5 +1,5 @@
 /**
- * 线性时间的 glob 匹配（sandbox_glob 用；模式由模型给出，不能编译成会回溯爆炸的正则）。
+ * 线性时间的 glob 匹配（Glob 用；模式由模型给出，不能编译成会回溯爆炸的正则）。
  *
  * 语法：路径按 `/` 分段；整段 `**` 跨任意层目录（含零层）；段内 `*` 匹配任意个字符（不跨 `/`），`?` 一个字符，
  * `[abc]` / `[a-z]` / `[!x]`（或 `[^x]`）字符类，`{a,b}` 二选一（可嵌套，展开后最多 {@link MAX_ALTERNATIVES} 个）；

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

@@ -1,4 +1,4 @@
 import type { BuiltinTool } from "../../registry.js";
 import { type SandboxToolDeps } from "./common.js";
-/** 内置工具 `sandbox_glob`：按文件名模式找文件（只读）。 */
+/** 内置工具 `Glob`：按文件名模式找文件（只读）。 */
 export declare function sandboxGlobTool(deps: SandboxToolDeps): BuiltinTool;

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

@@ -6,14 +6,14 @@ const MAX_RESULTS = 1000;
 /** `find` 输出的上限（字节）。 */
 const MAX_FIND_BYTES = 8 * 1024 * 1024;
 const SPEC = {
-    name: "sandbox_glob",
+    name: "Glob",
     // Display only (the tool row; not in the fingerprint, never sent to the model).
     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, ** " +
         "matches across directories, ? matches one character, {a,b} matches either. Returns absolute " +
-        "paths sorted by name, up to 1000. To search file contents, use sandbox_grep.",
+        "paths sorted by name, up to 1000. To search file contents, use Grep.",
     inputSchema: {
         type: "object",
         properties: {
@@ -36,13 +36,13 @@ const SPEC = {
 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 FIND_FAILED = "Listing files did not finish in time; pass a narrower path or pattern and retry.";
-/** 内置工具 `sandbox_glob`：按文件名模式找文件（只读）。 */
+/** 内置工具 `Glob`：按文件名模式找文件（只读）。 */
 export function sandboxGlobTool(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 } = input;
@@ -65,7 +65,7 @@ export function sandboxGlobTool(deps) {
                 const r = await p.exec(h, {
                     command: "find . -type f -print0",
                     cwd: dir,
-                    timeoutMs: searchTimeoutMs(deps.config(), startedAt, Date.now(), ctx.runDeadline),
+                    timeoutMs: searchTimeoutMs(deps.config.get(), startedAt, Date.now(), ctx.runDeadline),
                     maxOutputBytes: MAX_FIND_BYTES,
                     signal,
                 });
@@ -84,7 +84,7 @@ export function sandboxGlobTool(deps) {
                     .map((rel) => `${base}/${rel}`)
                     .filter((abs) => abs !== SYNC_MARKER)
                     .sort()
-                    // 文件名里的换行显示为 `\n`（与 sandbox_grep 一致），一行一个文件
+                    // 文件名里的换行显示为 `\n`（与 Grep 一致），一行一个文件
                     .map((abs) => abs.replace(/\n/g, "\\n")));
             });
             const shown = files.slice(0, MAX_RESULTS);

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

@@ -1,9 +1,12 @@
 import type { BuiltinTool } from "../../registry.js";
 import { type SandboxToolDeps } from "./common.js";
 /**
- * 解析 `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 declare function parseGrepNull(stdout: string, base: string): string[];
-/** 内置工具 `sandbox_grep`：按正则搜文件内容（只读）。 */
+export declare function parseGrepNull(stdout: string, base: string, numbered?: boolean): string[];
+/** 内置工具 `Grep`：按正则搜文件内容（只读）。 */
 export declare function sandboxGrepTool(deps: SandboxToolDeps): BuiltinTool;