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

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

@@ -0,0 +1,133 @@
+import { ToolError } from "@capybara-hq/plugin-sdk";
+import { checkPath, clip, display, inSandbox, SYNC_MARKER, sandboxBaseTimeoutMs, searchTimeoutMs, shellQuote, unavailableWhenNoSandbox, withNotices, } from "./common.js";
+/** 最多返回的匹配行数。 */
+const MAX_MATCHES = 500;
+/** 每个匹配行最多显示的字符数。 */
+const MAX_LINE_CHARS = 500;
+/** grep 输出的上限（字节）。 */
+const MAX_GREP_BYTES = 4 * 1024 * 1024;
+const SPEC = {
+    name: "sandbox_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.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            pattern: {
+                type: "string",
+                minLength: 1,
+                description: 'Regular expression (POSIX extended), e.g. "def [a-z_]+\\(" or "TODO".',
+            },
+            path: {
+                type: "string",
+                minLength: 1,
+                description: "Absolute file or directory to search. Default /workspace.",
+            },
+            glob: {
+                type: "string",
+                minLength: 1,
+                description: 'Only search files whose name matches this glob, e.g. "*.md".',
+            },
+            ignoreCase: { type: "boolean", description: "Case-insensitive match. Default false." },
+        },
+        required: ["pattern"],
+        additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true },
+};
+const notFound = (path) => `${clip(path, 200)} does not exist; check the path with sandbox_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`。最后一条不完整（输出被截断）时丢掉。
+ */
+export function parseGrepNull(stdout, base) {
+    const out = [];
+    let pos = 0;
+    for (;;) {
+        const nul = stdout.indexOf("\0", pos);
+        if (nul === -1)
+            break;
+        const nl = stdout.indexOf("\n", nul);
+        if (nl === -1)
+            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)}`);
+        pos = nl + 1;
+    }
+    return out;
+}
+/** 内置工具 `sandbox_grep`：按正则搜文件内容（只读）。 */
+export function sandboxGrepTool(deps) {
+    return {
+        spec: SPEC,
+        defaultPolicy: "allow",
+        unavailable: unavailableWhenNoSandbox(deps),
+        timeoutMs: () => sandboxBaseTimeoutMs(deps.config()),
+        async run(input, ctx) {
+            const startedAt = Date.now();
+            const { pattern, glob, ignoreCase = false } = input;
+            const path = checkPath(input.path ?? "/workspace");
+            const { value, notices } = await inSandbox(deps, ctx, async ({ h, p, signal }) => {
+                const st = await p.stat(h, path, signal);
+                if (st === null)
+                    throw new ToolError(notFound(path));
+                // 在目标所在目录里搜相对路径，输出再拼回绝对路径（命令里不出现沙箱绝对路径）
+                const slash = path.lastIndexOf("/");
+                const cwd = st.isDir ? path : path.slice(0, slash) || "/";
+                const target = st.isDir ? "." : path.slice(slash + 1);
+                const command = [
+                    // --null：文件名后跟 NUL 而不是 `:`，文件名里有换行或冒号也能解析
+                    "grep -rnHIE --null",
+                    ...(ignoreCase ? ["-i"] : []),
+                    ...(glob !== undefined ? [`--include=${shellQuote(glob)}`] : []),
+                    "-e",
+                    shellQuote(pattern),
+                    "--",
+                    shellQuote(target),
+                ].join(" ");
+                const r = await p.exec(h, {
+                    command,
+                    cwd,
+                    timeoutMs: searchTimeoutMs(deps.config(), 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}:`));
+                // 退出码 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 };
+            });
+            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 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;
+            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

@@ -0,0 +1,12 @@
+import type { BuiltinTool } from "../../registry.js";
+import type { SandboxToolDeps } from "./common.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`。没有沙箱提供方时报不可用。
+ * 默认 allow；组织设置 `sandboxToolPolicy` 为 ask 时除 read / glob / grep 外需要审批（见 policy.ts）。
+ */
+export declare function sandboxTools(deps: SandboxToolDeps): BuiltinTool[];

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

@@ -0,0 +1,27 @@
+import { sandboxBashTool } from "./bash.js";
+import { sandboxDeliverTool } from "./deliver.js";
+import { sandboxEditTool } from "./edit.js";
+import { sandboxGlobTool } from "./glob.js";
+import { sandboxGrepTool } from "./grep.js";
+import { sandboxReadTool } from "./read.js";
+import { sandboxWriteTool } from "./write.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`。没有沙箱提供方时报不可用。
+ * 默认 allow；组织设置 `sandboxToolPolicy` 为 ask 时除 read / glob / grep 外需要审批（见 policy.ts）。
+ */
+export function sandboxTools(deps) {
+    return [
+        sandboxBashTool(deps),
+        sandboxReadTool(deps),
+        sandboxWriteTool(deps),
+        sandboxEditTool(deps),
+        sandboxGlobTool(deps),
+        sandboxGrepTool(deps),
+        sandboxDeliverTool(deps),
+    ];
+}

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

@@ -0,0 +1,7 @@
+/**
+ * 沙箱内置工具的名字（M5 T8，Ruling M12：工具 key 只能含字母数字、`_`、`-`，所以是 `sandbox_<动作>`）。
+ * 单独成文件：注册表与策略判定只需要名字，不引入工具实现。
+ */
+export declare const SANDBOX_TOOL_NAMES: readonly ["sandbox_bash", "sandbox_read", "sandbox_write", "sandbox_edit", "sandbox_glob", "sandbox_grep", "sandbox_deliver"];
+/** 组织设置 `sandboxToolPolicy` 为 `ask` 时需要审批的沙箱工具（只读的 read / glob / grep 除外）。 */
+export declare const SANDBOX_ASK_TOOL_NAMES: ReadonlySet<string>;

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

@@ -0,0 +1,20 @@
+/**
+ * 沙箱内置工具的名字（M5 T8，Ruling M12：工具 key 只能含字母数字、`_`、`-`，所以是 `sandbox_<动作>`）。
+ * 单独成文件：注册表与策略判定只需要名字，不引入工具实现。
+ */
+export const SANDBOX_TOOL_NAMES = [
+    "sandbox_bash",
+    "sandbox_read",
+    "sandbox_write",
+    "sandbox_edit",
+    "sandbox_glob",
+    "sandbox_grep",
+    "sandbox_deliver",
+];
+/** 组织设置 `sandboxToolPolicy` 为 `ask` 时需要审批的沙箱工具（只读的 read / glob / grep 除外）。 */
+export const SANDBOX_ASK_TOOL_NAMES = new Set([
+    "sandbox_bash",
+    "sandbox_write",
+    "sandbox_edit",
+    "sandbox_deliver",
+]);

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

@@ -0,0 +1,8 @@
+import type { BuiltinTool } from "../../registry.js";
+import { type SandboxToolDeps } from "./common.js";
+/** 最多读出的字节数（更大的文件只读开头，并说明用 sandbox_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 时也不审批）。 */
+export declare function sandboxReadTool(deps: SandboxToolDeps): BuiltinTool;

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

@@ -0,0 +1,121 @@
+import { ToolError } from "@capybara-hq/plugin-sdk";
+import { viewPath } from "../../view.js";
+import { checkPath, clip, display, inSandbox, looksBinary, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, withNotices, } from "./common.js";
+/** 不给 `limit` 时一次读的行数。 */
+const DEFAULT_LIMIT = 2000;
+/** 单行最多显示的字符数（更长的截断并注明）。 */
+const MAX_LINE_CHARS = 2000;
+/** 最多读出的字节数（更大的文件只读开头，并说明用 sandbox_bash 读其余部分）。 */
+export const READ_MAX_BYTES = 10 * 1024 * 1024;
+const SPEC = {
+    name: "sandbox_read",
+    // Display only (the tool row; not in the fingerprint, never sent to the model).
+    keyArgs: ["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.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            path: {
+                type: "string",
+                minLength: 1,
+                description: 'Absolute path of the file, e.g. "/workspace/src/main.py".',
+            },
+            offset: {
+                type: "integer",
+                minimum: 1,
+                description: "First line to read (1-based). Default 1.",
+            },
+            limit: {
+                type: "integer",
+                minimum: 1,
+                description: `Maximum number of lines to read. Default ${DEFAULT_LIMIT}.`,
+            },
+        },
+        required: ["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 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) {
+    const lines = text.split("\n");
+    if (lines.length > 1 && lines.at(-1) === "")
+        lines.pop();
+    return lines;
+}
+/** 按行编号显示 `[offset, offset + limit)`（1 起），结尾注明还有多少行。 */
+export function numberLines(text, offset, limit) {
+    const lines = fileLines(text);
+    const total = lines.length;
+    if (offset > total)
+        throw new ToolError(pastEnd(offset, total));
+    const end = Math.min(total, offset - 1 + limit);
+    const out = [];
+    for (let i = offset - 1; i < end; i++) {
+        const line = lines[i];
+        const shown = line.length > MAX_LINE_CHARS
+            ? `${line.slice(0, MAX_LINE_CHARS)}… [line cut at ${MAX_LINE_CHARS} characters]`
+            : line;
+        out.push(`${String(i + 1).padStart(6)}\t${shown}`);
+    }
+    if (end < total) {
+        out.push(`[Lines ${offset}–${end} of ${total}; continue with offset=${end + 1}]`);
+    }
+    return out.join("\n");
+}
+/** 内置工具 `sandbox_read`：读沙箱里的文本文件（只读，组织策略为 ask 时也不审批）。 */
+export function sandboxReadTool(deps) {
+    return {
+        spec: SPEC,
+        defaultPolicy: "allow",
+        unavailable: unavailableWhenNoSandbox(deps),
+        timeoutMs: () => sandboxBaseTimeoutMs(deps.config()),
+        async run(input, ctx) {
+            const { offset = 1, limit = DEFAULT_LIMIT } = input;
+            const path = checkPath(input.path);
+            const { value, notices } = await inSandbox(deps, ctx, async ({ h, p, signal }) => {
+                const st = await p.stat(h, path, signal);
+                if (st === null)
+                    throw new ToolError(notFound(path));
+                if (st.isDir)
+                    throw new ToolError(isDirectory(path));
+                const got = await p.readFile(h, path, { maxBytes: READ_MAX_BYTES, signal });
+                if (got === null)
+                    throw new ToolError(notFound(path));
+                return { ...got, size: st.size };
+            });
+            let text;
+            // 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).`;
+            }
+            else if (value.data.byteLength === 0) {
+                text = "(empty file)";
+            }
+            else {
+                const decoded = new TextDecoder().decode(value.data);
+                text = numberLines(decoded, offset, limit);
+                range = {
+                    fromLine: offset,
+                    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.]`;
+                }
+            }
+            return {
+                content: [{ type: "text", text: withNotices(notices, text) }],
+                display: display(`读取 ${clip(path, 180)}`, `Read ${clip(path, 180)}`),
+                view: { kind: "read", path: viewPath(path), ...range },
+            };
+        },
+    };
+}

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

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

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

@@ -0,0 +1,88 @@
+import { isSandboxGoneError, 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";
+const SPEC = {
+    name: "sandbox_write",
+    // Display only (the tool row; not in the fingerprint, never sent to the model).
+    keyArgs: ["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.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            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"],
+        additionalProperties: false,
+    },
+};
+/**
+ * The most of an existing file read to diff against (display only): the size above which a diff
+ * has no hunks anyway. A larger or binary file (a NUL anywhere) is overwritten as usual and the
+ * result carries no view.
+ */
+const PREVIOUS_MAX_BYTES = TOOL_VIEW_DIFF_MAX_BYTES;
+const isDirectory = (path) => `${clip(path, 200)} is a directory; pass the path of a file inside it.`;
+/** 内置工具 `sandbox_write`：整文件写入。 */
+export function sandboxWriteTool(deps) {
+    return {
+        spec: SPEC,
+        defaultPolicy: "allow",
+        unavailable: unavailableWhenNoSandbox(deps),
+        timeoutMs: () => sandboxBaseTimeoutMs(deps.config()),
+        async run(input, ctx) {
+            const path = checkWritable(input.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
+            withPathLease(deps, ctx, path, signal, async (signal) => {
+                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)
+                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;
+                    }
+                }
+                await p.writeFile(h, path, data, signal);
+                return { existed: st !== null, previous };
+            }));
+            const { existed, previous } = value;
+            const text = `${existed ? "Overwrote" : "Created"} ${path} (${data.byteLength} bytes).`;
+            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),
+                    },
+                }),
+            };
+        },
+    };
+}

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

@@ -0,0 +1,53 @@
+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 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.md 的正文与文件清单（结果里写明版本）。技能带其他文件时把整个技能复制进本对话沙箱的 `/skills/<name>/`
+ * （提供方以 root 写，命令用户只读）；没有沙箱提供方时只给正文，并说明脚本不可用。
+ *
+ * - 存储里读出的每个文件都按清单的 sha256 核对，不符即拒绝（不把被替换的内容给模型或放进沙箱）。
+ * - 复制记录在内核控制的标记文件（每个技能一个，{@link skillMarkerPath}：`/skills/.capybara/<name>.json`，
+ *   命令用户改不了）：`{ id, version, prefix, files, stale }`。新建 / 重建的沙箱、版本或来源前缀变化、同名换了技能时
+ *   重新复制，否则跳过。
+ * - agent 没有任何沙箱工具时不创建沙箱、不复制（模型也跑不了脚本），只给正文并说明。
+ * - 可执行位：提供方写的文件一律不可执行（0644）。不扩展 `sandbox@1` 的 `writeFile`，而是在结果里告诉模型用解释器
+ *   运行（`sh` / `python3` / `node`）：契约与两个提供方不变，技能包里的 shebang 脚本照样能跑，代价只是不能 `./x`。
+ * - 旧版本多出的文件：`sandbox@1` 没有删除原语，命令用户也删不了 `/skills` 下的文件，所以新版本原地覆盖，
+ *   旧版本独有的文件留在原处、记进标记的 `stale`，每次加载都在结果里列出「不属于当前版本、忽略它们」。
+ */
+/**
+ * 已复制进沙箱的技能的标记目录（内核控制：`/skills` 只有提供方以 root 能写；技能名不以 `.` 开头，不会撞名）。
+ */
+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">;
+}
+/** A stored skill file is missing or does not match its manifest entry (size, sha256). */
+export declare class SkillIntegrityError extends Error {
+}
+/**
+ * Reads one skill file and checks it against its manifest entry (size and sha256). A missing or
+ * mismatching object throws {@link SkillIntegrityError}; a storage error is rethrown as is
+ * (`storage.unavailable` from the store). Shared with a person's skill invocation (phase D).
+ */
+export declare function readSkillFile(store: ObjectStore, key: string, file: SkillManifest["files"][number], signal?: AbortSignal): Promise<Uint8Array>;
+/**
+ * 目录条目对应的内容，按条目的 `source`（对象前缀，T15）精确解析：先找该技能前缀相同的已生成版本（技能未删除；
+ * 批准时草稿前缀原样成为版本前缀，版本号变了也能找到），再找本对话发起、仍待批准、前缀相同的技能改动（试用草稿：
+ * 没有 `skill_versions` 行，新技能连 `skills` 行都没有）。绝不按版本号解析——被拒绝的草稿与之后别人批准的同号版本
+ * 内容不同。都没有 → undefined（已移除）。
+ */
+export declare function findSkillVersion(db: KernelDb, ctx: Pick<BuiltinCallContext, "orgId" | "conversationId">, entry: Pick<CatalogSkill, "id" | "source">): Promise<{
+    manifest: SkillManifest;
+    object_prefix: string;
+} | undefined>;
+/** 内置工具 `skill_load`（见文件头）。 */
+export declare function skillLoadTool(deps: SkillLoadDeps): BuiltinTool;