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

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 { checkPathShape, checkWritable, clip, display, inSandbox, looksBinary, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, withNotices, withPathLease, } from "./common.js";
+import { assertReadAndUnchanged, fileStateOf, normalizeSandboxPath, recordedFile, } from "./file-state.js";
+import { READ_MAX_BYTES } from "./read.js";
+/** 可编辑的最大文件（字节）：更大的用 Bash 处理。 */
 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".',
+                description: "Absolute path of the file, e.g. src/app.py in the workspace directory.",
             },
-            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,44 +44,55 @@ 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;
+            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
-            withPathLease(deps, ctx, path, signal, async (signal) => {
-                const st = await p.stat(h, path, signal);
-                if (st === null)
-                    throw new ToolError(notFound(path));
-                if (st.isDir)
-                    throw new ToolError(notText(path));
-                const got = await p.readFile(h, path, { maxBytes: EDIT_MAX_BYTES, signal });
-                if (got === null)
-                    throw new ToolError(notFound(path));
-                if (got.truncated || looksBinary(got.data))
-                    throw new ToolError(notText(path));
-                const text = new TextDecoder().decode(got.data);
-                const count = occurrences(text, oldText);
-                if (count === 0)
-                    throw new ToolError(noMatch(path));
-                if (count > 1 && !replaceAll)
-                    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 };
-            }));
+            checkPathShape(input.file_path, "file_path");
+            let path = "";
+            const { value: edit, notices } = await inSandbox(deps, ctx, ({ environmentId, h, roots, p, signal }) => {
+                path = checkWritable(input.file_path, roots);
+                // read, replace, write: one holder at a time per file
+                return withPathLease(deps, { environmentId }, path, signal, async (signal) => {
+                    const st = await p.stat(h, path, signal);
+                    if (st === null)
+                        throw new ToolError(notFound(path));
+                    if (st.isDir)
+                        throw new ToolError(notText(path));
+                    const got = await p.readFile(h, path, { maxBytes: EDIT_MAX_BYTES, signal });
+                    if (got === null)
+                        throw new ToolError(notFound(path));
+                    if (got.truncated || looksBinary(got.data))
+                        throw new ToolError(notText(path));
+                    await assertReadAndUnchanged(deps, ctx.conversationId, path, fileStateOf(got.data, st.size));
+                    const text = new TextDecoder().decode(got.data);
+                    const count = occurrences(text, old_string);
+                    if (count === 0)
+                        throw new ToolError(noMatch(path));
+                    if (count > 1 && !replace_all)
+                        throw new ToolError(ambiguous(count));
+                    // 用函数形式替换：new_string 里的 `$&` 等不被当成替换模式
+                    const next = replace_all
+                        ? text.split(old_string).join(new_string)
+                        : text.replace(old_string, () => new_string);
+                    const nextBytes = new TextEncoder().encode(next);
+                    await p.writeFile(h, path, nextBytes, signal);
+                    return {
+                        n: replace_all ? count : 1,
+                        before: text,
+                        after: next,
+                        // over the bytes the next Write / Edit reads back (Read's limit), as Read records it
+                        file: recordedFile(normalizeSandboxPath(path), nextBytes.subarray(0, READ_MAX_BYTES), nextBytes.byteLength),
+                    };
+                });
+            });
             const { n } = edit;
             const text = `Edited ${path}: replaced ${n} occurrence${n === 1 ? "" : "s"}.`;
             return {
@@ -91,6 +104,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

@@ -1,19 +1,19 @@
 import { ToolError } from "@capybara-hq/plugin-sdk";
-import { checkPath, clip, display, inSandbox, SYNC_MARKER, sandboxBaseTimeoutMs, searchTimeoutMs, unavailableWhenNoSandbox, withNotices, } from "./common.js";
+import { checkPath, checkPathShape, clip, display, inSandbox, sandboxBaseTimeoutMs, searchTimeoutMs, syncMarkerMatcher, unavailableWhenNoSandbox, withNotices, } from "./common.js";
 import { compileGlob, GlobPatternError } from "./glob-match.js";
 /** 最多列出的文件数。 */
 const MAX_RESULTS = 1000;
 /** `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, ** " +
+        "against paths relative to path (default: the workspace directory): * matches within one directory, ** " +
         "matches across directories, ? matches one character, {a,b} matches either. Returns absolute " +
-        "paths sorted by name, up to 1000. To search file contents, use sandbox_grep.",
+        "paths sorted by name, up to 1000. To search file contents, use Grep.",
     inputSchema: {
         type: "object",
         properties: {
@@ -25,7 +25,7 @@ const SPEC = {
             path: {
                 type: "string",
                 minLength: 1,
-                description: "Absolute directory to search in. Default /workspace.",
+                description: "Absolute directory to search in. Default: the workspace directory.",
             },
         },
         required: ["pattern"],
@@ -34,21 +34,20 @@ const SPEC = {
     annotations: { readOnlyHint: true },
 };
 const ABSOLUTE_PATTERN = 'The pattern must be relative to path; pass the directory in path and a relative pattern such as "**/*.py".';
-const notDirectory = (path) => `${clip(path, 200)} is not a directory; pass an existing directory in path (default /workspace).`;
+const notDirectory = (path, workspace) => `${clip(path, 200)} is not a directory; pass an existing directory in path (default ${workspace}).`;
 const FIND_FAILED = "Listing files did not finish in time; pass a narrower path or pattern and retry.";
-/** 内置工具 `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;
             if (pattern.startsWith("/"))
                 throw new ToolError(ABSOLUTE_PATTERN);
-            const dir = checkPath(input.path ?? "/workspace");
             let matches;
             try {
                 matches = compileGlob(pattern);
@@ -58,14 +57,19 @@ export function sandboxGlobTool(deps) {
                     throw e;
                 throw new ToolError(`Invalid glob pattern: ${e.message}; pass a simpler pattern (fewer wildcards and braces) and retry.`);
             }
-            const { value: files, notices } = await inSandbox(deps, ctx, async ({ h, p, signal }) => {
+            const given = input.path;
+            if (given !== undefined)
+                checkPathShape(given);
+            let dir = "";
+            const { value: files, notices } = await inSandbox(deps, ctx, async ({ h, roots, p, signal }) => {
+                dir = checkPath(input.path ?? roots.workspace, roots);
                 const st = await p.stat(h, dir, signal);
                 if (!st?.isDir)
-                    throw new ToolError(notDirectory(dir));
+                    throw new ToolError(notDirectory(dir, roots.workspace));
                 const r = await p.exec(h, {
                     command: "find . -type f -print0",
                     cwd: dir,
-                    timeoutMs: searchTimeoutMs(deps.config(), startedAt, Date.now(), ctx.runDeadline),
+                    timeoutMs: searchTimeoutMs(deps.config.get(), startedAt, Date.now(), ctx.runDeadline),
                     maxOutputBytes: MAX_FIND_BYTES,
                     signal,
                 });
@@ -77,14 +81,15 @@ export function sandboxGlobTool(deps) {
                 if (r.truncated)
                     names.pop();
                 const base = dir === "/" ? "" : dir;
+                const isMarker = syncMarkerMatcher(roots);
                 return (names
                     .filter((l) => l.startsWith("./"))
                     .map((l) => l.slice(2))
                     .filter((rel) => matches(rel))
                     .map((rel) => `${base}/${rel}`)
-                    .filter((abs) => abs !== SYNC_MARKER)
+                    .filter((abs) => !isMarker(abs))
                     .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;