@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.0

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

@@ -0,0 +1,180 @@
+import { randomUUID } from "node:crypto";
+import { ExtensionPointUnavailableError, MEDIA_NAME_MAX_CHARS, ToolError, } from "@capybara-hq/plugin-sdk";
+import { isValidArtifactName } from "../../../conversations/events.js";
+import { ApiError } from "../../../errors.js";
+import { checkPath, clip, display, inSandbox, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, withNotices, } from "./common.js";
+const SPEC = {
+    name: "sandbox_deliver",
+    // Display only (the tool row; not in the fingerprint, never sent to the model).
+    keyArgs: ["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 " +
+        "limited (100 MB by default). Do not use it for intermediate files the user does not need.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            path: {
+                type: "string",
+                minLength: 1,
+                description: 'Absolute path of the file in the sandbox, e.g. "/workspace/out/report.pdf".',
+            },
+            name: {
+                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.',
+            },
+        },
+        required: ["path"],
+        additionalProperties: false,
+    },
+};
+/** 按扩展名猜的内容类型（下载一律 `attachment`，类型只用于显示与预览判断）。 */
+const CONTENT_TYPES = {
+    txt: "text/plain",
+    log: "text/plain",
+    md: "text/markdown",
+    csv: "text/csv",
+    tsv: "text/tab-separated-values",
+    json: "application/json",
+    xml: "application/xml",
+    yaml: "application/yaml",
+    yml: "application/yaml",
+    html: "text/html",
+    htm: "text/html",
+    css: "text/css",
+    js: "text/javascript",
+    ts: "text/plain",
+    py: "text/x-python",
+    sql: "application/sql",
+    pdf: "application/pdf",
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    webp: "image/webp",
+    svg: "image/svg+xml",
+    zip: "application/zip",
+    gz: "application/gzip",
+    tar: "application/x-tar",
+    xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    mp3: "audio/mpeg",
+    mp4: "video/mp4",
+    wav: "audio/wav",
+};
+export function contentTypeFor(name) {
+    const dot = name.lastIndexOf(".");
+    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 BAD_NAME = "name must not contain control characters, / or \\; pass a plain file name such as report.pdf.";
+/** 默认产物名：路径的文件名部分，过长时保留末尾（扩展名）截到 255 个 UTF-16 单元以内。 */
+function defaultName(path) {
+    const cps = [...path.slice(path.lastIndexOf("/") + 1)];
+    let out = "";
+    for (let i = cps.length - 1; i >= 0; i--) {
+        const next = cps[i] + out;
+        if (next.length > MEDIA_NAME_MAX_CHARS)
+            break;
+        out = next;
+    }
+    return isValidArtifactName(out) ? out : "artifact";
+}
+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`，用户可下载。 */
+export function sandboxDeliverTool(deps) {
+    return {
+        spec: SPEC,
+        defaultPolicy: "allow",
+        // 没有沙箱或没有对象存储都交付不了（先报沙箱的原因）
+        unavailable: () => unavailableWhenNoSandbox(deps)() ?? (deps.storage.available ? null : NO_STORAGE_REASON),
+        timeoutMs: () => 2 * sandboxBaseTimeoutMs(deps.config()),
+        async run(input, ctx) {
+            // 存储在调用前就核对：不为一个交付不了的文件去 stat / 读沙箱
+            if (!deps.storage.available)
+                throw new ToolError(NO_STORAGE);
+            const path = checkPath(input.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 { value: data, notices } = await inSandbox(deps, ctx, async ({ h, p, signal }) => {
+                const st = await p.stat(h, path, signal);
+                if (st === null)
+                    throw new ToolError(notFound(path));
+                if (st.isDir)
+                    throw new ToolError(isDirectory(path));
+                if (st.size > max)
+                    throw new ToolError(tooLarge(path, st.size, max));
+                const got = await p.readFile(h, path, { maxBytes: max, signal });
+                if (got === null)
+                    throw new ToolError(notFound(path));
+                // 读的过程中文件变大了
+                if (got.truncated)
+                    throw new ToolError(tooLarge(path, max + 1, max));
+                return got.data;
+            });
+            // 上传在沙箱锁之外进行：不占着沙箱
+            const artifactId = randomUUID();
+            const objectKey = `artifacts/${ctx.conversationId}/${artifactId}`;
+            const contentType = contentTypeFor(name);
+            try {
+                await deps.storage.kernel(ctx.orgId).put(objectKey, data, {
+                    contentType,
+                    size: data.byteLength,
+                    signal: ctx.signal,
+                });
+            }
+            catch (e) {
+                if ((e instanceof ApiError && e.code === "storage.unavailable") ||
+                    e instanceof ExtensionPointUnavailableError) {
+                    throw new ToolError(NO_STORAGE);
+                }
+                throw e;
+            }
+            try {
+                await deps.eventLog.append(ctx.conversationId, [
+                    {
+                        type: "artifact_created",
+                        ...(ctx.runId !== undefined && { runId: ctx.runId }),
+                        payload: {
+                            artifactId,
+                            name,
+                            contentType,
+                            size: data.byteLength,
+                            objectKey,
+                            sourcePath: path,
+                            callId: ctx.callId,
+                        },
+                    },
+                ]);
+            }
+            catch (e) {
+                // 事件没写进去：对象没人引用，尽力删掉
+                await deps.storage
+                    .kernel(ctx.orgId)
+                    .delete(objectKey)
+                    .catch(() => { });
+                throw e;
+            }
+            await deps.eventLog.publishChanged?.(ctx.conversationId, "files");
+            const text = `Delivered ${name} (${data.byteLength} bytes, ${contentType}) to the user as artifact ${artifactId}; the user can download it from the conversation.`;
+            return {
+                content: [{ type: "text", text: withNotices(notices, text) }],
+                display: display(`交付文件 ${clip(name, 180)}`, `Delivered ${clip(name, 180)}`),
+            };
+        },
+    };
+}

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

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

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

@@ -0,0 +1,98 @@
+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 处理。 */
+const EDIT_MAX_BYTES = 10 * 1024 * 1024;
+const SPEC = {
+    name: "sandbox_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.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            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: {
+                type: "boolean",
+                description: "Replace every occurrence of oldText instead of exactly one. Default false.",
+            },
+        },
+        required: ["path", "oldText", "newText"],
+        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.`;
+/** 出现次数（不重叠）。 */
+function occurrences(text, sub) {
+    let n = 0;
+    for (let i = text.indexOf(sub); i !== -1; i = text.indexOf(sub, i + sub.length))
+        n++;
+    return n;
+}
+/** 内置工具 `sandbox_edit`：按精确文本替换。 */
+export function sandboxEditTool(deps) {
+    return {
+        spec: SPEC,
+        defaultPolicy: "allow",
+        unavailable: unavailableWhenNoSandbox(deps),
+        timeoutMs: () => sandboxBaseTimeoutMs(deps.config()),
+        async run(input, ctx) {
+            const { oldText, newText, replaceAll = false } = input;
+            const path = checkWritable(input.path);
+            if (oldText === newText)
+                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 };
+            }));
+            const { n } = edit;
+            const text = `Edited ${path}: replaced ${n} occurrence${n === 1 ? "" : "s"}.`;
+            return {
+                content: [{ type: "text", text: withNotices(notices, text) }],
+                display: display(`编辑 ${clip(path, 180)}`, `Edited ${clip(path, 180)}`),
+                // display only: the diff on the row
+                view: {
+                    kind: "edit",
+                    path: viewPath(path),
+                    created: false,
+                    ...lineDiff(edit.before, edit.after),
+                },
+            };
+        },
+    };
+}

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

@@ -0,0 +1,25 @@
+/**
+ * 线性时间的 glob 匹配（sandbox_glob 用；模式由模型给出，不能编译成会回溯爆炸的正则）。
+ *
+ * 语法：路径按 `/` 分段；整段 `**` 跨任意层目录（含零层）；段内 `*` 匹配任意个字符（不跨 `/`），`?` 一个字符，
+ * `[abc]` / `[a-z]` / `[!x]`（或 `[^x]`）字符类，`{a,b}` 二选一（可嵌套，展开后最多 {@link MAX_ALTERNATIVES} 个）；
+ * 其余字符按字面。
+ *
+ * 复杂度：段内用双指针通配匹配（只回溯到最近的 `*`），O(段长 × 模式段长)；跨段的 `**` 用
+ * (模式段数 + 1) × (路径段数 + 1) 的记忆化，整体为多项式，最坏也不会指数回溯。
+ * 另限制模式长度、`*` 个数（连续的 `*` 先合并）与展开后的分支数，超过即拒绝。
+ */
+/** 模式最长字符数。 */
+export declare const MAX_GLOB_LENGTH = 1000;
+/** 模式里最多的 `*`（合并连续的之后，各分支合计）。 */
+export declare const MAX_GLOB_STARS = 32;
+/** `{a,b}` 展开后最多的分支数。 */
+export declare const MAX_ALTERNATIVES = 64;
+/** 模式不合法或超出限制；message 为英文，供工具层拼进给模型的错误。 */
+export declare class GlobPatternError extends Error {
+    constructor(message: string);
+}
+/**
+ * 编译 glob（相对路径，`/` 分隔）为匹配函数。模式不合法或超出限制抛 {@link GlobPatternError}。
+ */
+export declare function compileGlob(pattern: string): (relPath: string) => boolean;

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

@@ -0,0 +1,240 @@
+/**
+ * 线性时间的 glob 匹配（sandbox_glob 用；模式由模型给出，不能编译成会回溯爆炸的正则）。
+ *
+ * 语法：路径按 `/` 分段；整段 `**` 跨任意层目录（含零层）；段内 `*` 匹配任意个字符（不跨 `/`），`?` 一个字符，
+ * `[abc]` / `[a-z]` / `[!x]`（或 `[^x]`）字符类，`{a,b}` 二选一（可嵌套，展开后最多 {@link MAX_ALTERNATIVES} 个）；
+ * 其余字符按字面。
+ *
+ * 复杂度：段内用双指针通配匹配（只回溯到最近的 `*`），O(段长 × 模式段长)；跨段的 `**` 用
+ * (模式段数 + 1) × (路径段数 + 1) 的记忆化，整体为多项式，最坏也不会指数回溯。
+ * 另限制模式长度、`*` 个数（连续的 `*` 先合并）与展开后的分支数，超过即拒绝。
+ */
+/** 模式最长字符数。 */
+export const MAX_GLOB_LENGTH = 1000;
+/** 模式里最多的 `*`（合并连续的之后，各分支合计）。 */
+export const MAX_GLOB_STARS = 32;
+/** `{a,b}` 展开后最多的分支数。 */
+export const MAX_ALTERNATIVES = 64;
+/** 模式不合法或超出限制；message 为英文，供工具层拼进给模型的错误。 */
+export class GlobPatternError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "GlobPatternError";
+    }
+}
+/** 展开 `{a,b}`（可嵌套）；分支数超过上限抛错。未闭合的 `{` 按字面。 */
+function expandBraces(p) {
+    let depth = 0;
+    let open = -1;
+    for (let i = 0; i < p.length; i++) {
+        const c = p[i];
+        if (c === "[") {
+            // 字符类里的花括号按字面
+            const end = p.indexOf("]", i + 2);
+            if (end !== -1)
+                i = end;
+            continue;
+        }
+        if (c === "{") {
+            if (depth === 0)
+                open = i;
+            depth++;
+        }
+        else if (c === "}" && depth > 0) {
+            depth--;
+            if (depth === 0) {
+                const body = p.slice(open + 1, i);
+                const parts = [];
+                let d = 0;
+                let start = 0;
+                for (let j = 0; j < body.length; j++) {
+                    if (body[j] === "{")
+                        d++;
+                    else if (body[j] === "}")
+                        d--;
+                    else if (body[j] === "," && d === 0) {
+                        parts.push(body.slice(start, j));
+                        start = j + 1;
+                    }
+                }
+                parts.push(body.slice(start));
+                const prefix = p.slice(0, open);
+                const rest = expandBraces(p.slice(i + 1));
+                const out = [];
+                for (const part of parts) {
+                    for (const inner of expandBraces(part)) {
+                        for (const tail of rest) {
+                            out.push(prefix + inner + tail);
+                            if (out.length > MAX_ALTERNATIVES) {
+                                throw new GlobPatternError(`the pattern expands to more than ${MAX_ALTERNATIVES} alternatives`);
+                            }
+                        }
+                    }
+                }
+                return out;
+            }
+        }
+    }
+    return [p];
+}
+/** 解析一段（不含 `/`）为 token；连续的 `*` 合并为一个。 */
+function parseSegment(seg) {
+    const chars = Array.from(seg);
+    const out = [];
+    for (let i = 0; i < chars.length; i++) {
+        const c = chars[i];
+        if (c === "*") {
+            if (out.at(-1)?.kind !== "star")
+                out.push({ kind: "star" });
+        }
+        else if (c === "?") {
+            out.push({ kind: "any" });
+        }
+        else if (c === "[") {
+            let j = i + 1;
+            let negate = false;
+            if (chars[j] === "!" || chars[j] === "^") {
+                negate = true;
+                j++;
+            }
+            // `]` 紧跟在开头时按字面
+            const first = j;
+            while (j < chars.length && (chars[j] !== "]" || j === first))
+                j++;
+            if (j >= chars.length) {
+                out.push({ kind: "char", c });
+                continue;
+            }
+            const body = chars.slice(first, j);
+            const items = [];
+            for (let k = 0; k < body.length; k++) {
+                const a = body[k];
+                if (body[k + 1] === "-" && k + 2 < body.length) {
+                    items.push([a, body[k + 2]]);
+                    k += 2;
+                }
+                else {
+                    items.push(a);
+                }
+            }
+            out.push({ kind: "class", negate, items });
+            i = j;
+        }
+        else {
+            out.push({ kind: "char", c });
+        }
+    }
+    return out;
+}
+function tokenMatches(t, c) {
+    switch (t.kind) {
+        case "char":
+            return t.c === c;
+        case "any":
+            return true;
+        case "class": {
+            const hit = t.items.some((it) => typeof it === "string" ? it === c : it[0] <= c && c <= it[1]);
+            return hit !== t.negate;
+        }
+        default:
+            return false;
+    }
+}
+/** 段内通配匹配：双指针，失配时只回溯到最近的 `*`（O(n × m)）。 */
+function matchSegment(tokens, name) {
+    const s = Array.from(name);
+    let p = 0;
+    let i = 0;
+    let star = -1;
+    let mark = 0;
+    while (i < s.length) {
+        const t = tokens[p];
+        if (t !== undefined && t.kind !== "star" && tokenMatches(t, s[i])) {
+            p++;
+            i++;
+        }
+        else if (t !== undefined && t.kind === "star") {
+            star = p;
+            mark = i;
+            p++;
+        }
+        else if (star !== -1) {
+            p = star + 1;
+            mark++;
+            i = mark;
+        }
+        else {
+            return false;
+        }
+    }
+    while (tokens[p]?.kind === "star")
+        p++;
+    return p === tokens.length;
+}
+/** 一个分支：按段匹配，`**` 用 (段数 + 1)² 的记忆化。 */
+function matchSegments(pattern, path) {
+    const P = pattern.length;
+    const N = path.length;
+    // 0 = 未算，1 = 不匹配，2 = 匹配
+    const memo = new Uint8Array((P + 1) * (N + 1));
+    const go = (i, j) => {
+        const k = i * (N + 1) + j;
+        const m = memo[k];
+        if (m !== 0)
+            return m === 2;
+        let r;
+        if (i === P) {
+            r = j === N;
+        }
+        else {
+            const seg = pattern[i];
+            if (seg.globstar) {
+                r = go(i + 1, j) || (j < N && go(i, j + 1));
+            }
+            else {
+                r = j < N && matchSegment(seg.tokens, path[j]) && go(i + 1, j + 1);
+            }
+        }
+        memo[k] = r ? 2 : 1;
+        return r;
+    };
+    return go(0, 0);
+}
+/**
+ * 编译 glob（相对路径，`/` 分隔）为匹配函数。模式不合法或超出限制抛 {@link GlobPatternError}。
+ */
+export function compileGlob(pattern) {
+    if (pattern.length > MAX_GLOB_LENGTH) {
+        throw new GlobPatternError(`the pattern is longer than ${MAX_GLOB_LENGTH} characters`);
+    }
+    const branches = expandBraces(pattern).map((alt) => {
+        const segs = [];
+        for (const raw of alt.split("/")) {
+            if (raw === "")
+                continue;
+            if (raw === "**") {
+                // 连续的 `**` 合并
+                if (!segs.at(-1)?.globstar) {
+                    segs.push({ globstar: true });
+                }
+            }
+            else {
+                segs.push({ globstar: false, tokens: parseSegment(raw) });
+            }
+        }
+        return segs;
+    });
+    let stars = 0;
+    for (const segs of branches) {
+        for (const s of segs) {
+            stars += s.globstar ? 1 : s.tokens.filter((t) => t.kind === "star").length;
+        }
+    }
+    if (stars > MAX_GLOB_STARS) {
+        throw new GlobPatternError(`the pattern has more than ${MAX_GLOB_STARS} wildcards`);
+    }
+    return (relPath) => {
+        const parts = relPath.split("/").filter((x) => x !== "");
+        return branches.some((segs) => matchSegments(segs, parts));
+    };
+}

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

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

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

@@ -0,0 +1,104 @@
+import { ToolError } from "@capybara-hq/plugin-sdk";
+import { checkPath, clip, display, inSandbox, SYNC_MARKER, sandboxBaseTimeoutMs, searchTimeoutMs, 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",
+    // 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.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            pattern: {
+                type: "string",
+                minLength: 1,
+                description: 'Glob pattern relative to path, e.g. "**/*.csv" or "src/*.ts".',
+            },
+            path: {
+                type: "string",
+                minLength: 1,
+                description: "Absolute directory to search in. Default /workspace.",
+            },
+        },
+        required: ["pattern"],
+        additionalProperties: false,
+    },
+    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 FIND_FAILED = "Listing files did not finish in time; pass a narrower path or pattern and retry.";
+/** 内置工具 `sandbox_glob`：按文件名模式找文件（只读）。 */
+export function sandboxGlobTool(deps) {
+    return {
+        spec: SPEC,
+        defaultPolicy: "allow",
+        unavailable: unavailableWhenNoSandbox(deps),
+        timeoutMs: () => sandboxBaseTimeoutMs(deps.config()),
+        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);
+            }
+            catch (e) {
+                if (!(e instanceof GlobPatternError))
+                    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 st = await p.stat(h, dir, signal);
+                if (!st?.isDir)
+                    throw new ToolError(notDirectory(dir));
+                const r = await p.exec(h, {
+                    command: "find . -type f -print0",
+                    cwd: dir,
+                    timeoutMs: searchTimeoutMs(deps.config(), startedAt, Date.now(), ctx.runDeadline),
+                    maxOutputBytes: MAX_FIND_BYTES,
+                    signal,
+                });
+                if (r.timedOut || r.exitCode === null)
+                    throw new ToolError(FIND_FAILED);
+                // -print0：文件名里可能有换行，按 NUL 切分；最后一项（截断时不完整）丢掉
+                const names = r.stdout.split("\0");
+                names.pop();
+                if (r.truncated)
+                    names.pop();
+                const base = dir === "/" ? "" : dir;
+                return (names
+                    .filter((l) => l.startsWith("./"))
+                    .map((l) => l.slice(2))
+                    .filter((rel) => matches(rel))
+                    .map((rel) => `${base}/${rel}`)
+                    .filter((abs) => abs !== SYNC_MARKER)
+                    .sort()
+                    // 文件名里的换行显示为 `\n`（与 sandbox_grep 一致），一行一个文件
+                    .map((abs) => abs.replace(/\n/g, "\\n")));
+            });
+            const shown = files.slice(0, MAX_RESULTS);
+            const text = files.length === 0
+                ? `No files match ${pattern} under ${dir}.`
+                : shown.join("\n") +
+                    (files.length > MAX_RESULTS
+                        ? `\n[Showing the first ${MAX_RESULTS} of ${files.length} files; use a narrower pattern.]`
+                        : "");
+            const n = files.length;
+            return {
+                content: [{ type: "text", text: withNotices(notices, text) }],
+                display: display(`查找文件 ${clip(pattern, 120)}（${n} 个）`, `Found ${n} file${n === 1 ? "" : "s"} matching ${clip(pattern, 120)}`),
+            };
+        },
+    };
+}

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

@@ -0,0 +1,9 @@
+import type { BuiltinTool } from "../../registry.js";
+import { type SandboxToolDeps } from "./common.js";
+/**
+ * 解析 `grep -nH --null` 的输出：每条为 `<文件名>\0<行号>:<行>\n`（文件名可能含换行，行本身不含）。
+ * 返回 `<绝对路径>:<行号>:<行>`；文件名里的换行显示为 `\n`。最后一条不完整（输出被截断）时丢掉。
+ */
+export declare function parseGrepNull(stdout: string, base: string): string[];
+/** 内置工具 `sandbox_grep`：按正则搜文件内容（只读）。 */
+export declare function sandboxGrepTool(deps: SandboxToolDeps): BuiltinTool;