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

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

@@ -1,8 +1,8 @@
 import type { BuiltinTool } from "../../registry.js";
 import { type SandboxToolDeps } from "./common.js";
-/** 最多读出的字节数（更大的文件只读开头，并说明用 sandbox_bash 读其余部分）。 */
+/** 最多读出的字节数（更大的文件只读开头，并说明用 Bash 读其余部分）。 */
 export declare const READ_MAX_BYTES: number;
 /** 按行编号显示 `[offset, offset + limit)`（1 起），结尾注明还有多少行。 */
 export declare function numberLines(text: string, offset: number, limit: number): string;
-/** 内置工具 `sandbox_read`：读沙箱里的文本文件（只读，组织策略为 ask 时也不审批）。 */
+/** 内置工具 `Read`：读沙箱里的文本文件（只读，组织策略为 ask 时也不审批）。 */
 export declare function sandboxReadTool(deps: SandboxToolDeps): BuiltinTool;

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

@@ -1,25 +1,27 @@
 import { ToolError } from "@capybara-hq/plugin-sdk";
 import { viewPath } from "../../view.js";
 import { checkPath, clip, display, inSandbox, looksBinary, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, withNotices, } from "./common.js";
+import { normalizeSandboxPath, recordedFile } from "./file-state.js";
 /** 不给 `limit` 时一次读的行数。 */
 const DEFAULT_LIMIT = 2000;
 /** 单行最多显示的字符数（更长的截断并注明）。 */
 const MAX_LINE_CHARS = 2000;
-/** 最多读出的字节数（更大的文件只读开头，并说明用 sandbox_bash 读其余部分）。 */
+/** 最多读出的字节数（更大的文件只读开头，并说明用 Bash 读其余部分）。 */
 export const READ_MAX_BYTES = 10 * 1024 * 1024;
 const SPEC = {
-    name: "sandbox_read",
+    name: "Read",
     // Display only (the tool row; not in the fingerprint, never sent to the model).
-    keyArgs: ["path"],
+    keyArgs: ["file_path"],
     description: "Read a text file from this conversation's sandbox, with line numbers. Use it to look at " +
         "source code, data files, logs and files the user attached (under /workspace/attachments). " +
         "Paths are absolute, under /workspace, /skills or /tmp. Lines are numbered from 1; pass " +
-        "offset and limit to read part of a long file. Binary files are not shown; use sandbox_bash " +
-        "to inspect them. Do not use it to list directories; use sandbox_glob instead.",
+        "offset and limit to read part of a long file. Binary files are not shown; use Bash " +
+        "to inspect them. Do not use it to list directories; use Glob instead. Read a file before you " +
+        "write it: Write and Edit fail on a file you have not read, or one changed since you read it.",
     inputSchema: {
         type: "object",
         properties: {
-            path: {
+            file_path: {
                 type: "string",
                 minLength: 1,
                 description: 'Absolute path of the file, e.g. "/workspace/src/main.py".',
@@ -35,13 +37,13 @@ const SPEC = {
                 description: `Maximum number of lines to read. Default ${DEFAULT_LIMIT}.`,
             },
         },
-        required: ["path"],
+        required: ["file_path"],
         additionalProperties: false,
     },
     annotations: { readOnlyHint: true },
 };
-const notFound = (path) => `File not found: ${clip(path, 200)}. Check the path with sandbox_glob.`;
-const isDirectory = (path) => `${clip(path, 200)} is a directory; use sandbox_glob to list its files.`;
+const notFound = (path) => `File not found: ${clip(path, 200)}. Check the path with Glob.`;
+const isDirectory = (path) => `${clip(path, 200)} is a directory; use Glob to list its files.`;
 const pastEnd = (offset, total) => `offset ${offset} is past the end of the file (${total} lines); pass an offset of at most ${total}.`;
 /** The file's lines (a final newline does not start another line). */
 function fileLines(text) {
@@ -70,7 +72,7 @@ export function numberLines(text, offset, limit) {
     }
     return out.join("\n");
 }
-/** 内置工具 `sandbox_read`：读沙箱里的文本文件（只读，组织策略为 ask 时也不审批）。 */
+/** 内置工具 `Read`：读沙箱里的文本文件（只读，组织策略为 ask 时也不审批）。 */
 export function sandboxReadTool(deps) {
     return {
         spec: SPEC,
@@ -79,7 +81,7 @@ export function sandboxReadTool(deps) {
         timeoutMs: () => sandboxBaseTimeoutMs(deps.config.get()),
         async run(input, ctx) {
             const { offset = 1, limit = DEFAULT_LIMIT } = input;
-            const path = checkPath(input.path);
+            const path = checkPath(input.file_path, "file_path");
             const { value, notices } = await inSandbox(deps, ctx, async ({ h, p, signal }) => {
                 const st = await p.stat(h, path, signal);
                 if (st === null)
@@ -95,7 +97,7 @@ export function sandboxReadTool(deps) {
             // display only: the line range shown on the row
             let range = {};
             if (looksBinary(value.data)) {
-                text = `Binary file (${value.size} bytes); use sandbox_bash to inspect it (for example file or xxd).`;
+                text = `Binary file (${value.size} bytes); use Bash to inspect it (for example file or xxd).`;
             }
             else if (value.data.byteLength === 0) {
                 text = "(empty file)";
@@ -108,13 +110,18 @@ export function sandboxReadTool(deps) {
                     toLine: Math.min(fileLines(decoded).length, offset - 1 + limit),
                 };
                 if (value.truncated) {
-                    text += `\n[Only the first ${READ_MAX_BYTES} bytes of this ${value.size}-byte file were read; use sandbox_bash (e.g. sed -n or tail) for the rest.]`;
+                    text += `\n[Only the first ${READ_MAX_BYTES} bytes of this ${value.size}-byte file were read; use Bash (e.g. sed -n or tail) for the rest.]`;
                 }
             }
             return {
                 content: [{ type: "text", text: withNotices(notices, text) }],
                 display: display(`读取 ${clip(path, 180)}`, `Read ${clip(path, 180)}`),
-                view: { kind: "read", path: viewPath(path), ...range },
+                view: {
+                    kind: "read",
+                    path: viewPath(path),
+                    ...range,
+                    file: recordedFile(normalizeSandboxPath(path), value.data, value.size),
+                },
             };
         },
     };

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

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

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

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

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

@@ -5,7 +5,7 @@ import { type CatalogSkill } from "../../runtime/context/skills.js";
 import type { BuiltinCallContext, BuiltinTool } from "../registry.js";
 import { type SandboxToolDeps } from "./sandbox/common.js";
 /**
- * 内置工具 `skill_load`（M5 T14，Ruling M17）：按日志里最新一份技能目录快照把名字解析为 id 与版本，返回该版本
+ * 内置工具 `Skill`（M5 T14，Ruling M17）：按日志里最新一份技能目录快照把名字解析为 id 与版本，返回该版本
  * SKILL.md 的正文与文件清单（结果里写明版本）。技能带其他文件时把整个技能复制进本对话沙箱的 `/skills/<name>/`
  * （提供方以 root 写，命令用户只读）；没有沙箱提供方时只给正文，并说明脚本不可用。
  *
@@ -28,7 +28,7 @@ export declare const skillMarkerPath: (name: string) => string;
 /** 依赖：沙箱工具的依赖，加上读技能行用的库与读快照用的日志。 */
 export interface SkillLoadDeps extends SandboxToolDeps {
     db: KernelSchemaDb;
-    eventLog: Pick<EventLog, "append" | "latestOfType">;
+    eventLog: Pick<EventLog, "append" | "latestOfType" | "latestFileState">;
 }
 /** A stored skill file is missing or does not match its manifest entry (size, sha256). */
 export declare class SkillIntegrityError extends Error {
@@ -49,5 +49,5 @@ export declare function findSkillVersion(db: KernelSchemaDb, ctx: Pick<BuiltinCa
     manifest: SkillManifest;
     object_prefix: string;
 } | undefined>;
-/** 内置工具 `skill_load`（见文件头）。 */
+/** 内置工具 `Skill`（见文件头）。 */
 export declare function skillLoadTool(deps: SkillLoadDeps): BuiltinTool;

package/dist/tools/builtins/skill-load.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { parseSkillMd, SKILL_ENTRY_FILE, SKILLS_SANDBOX_ROOT, skillSandboxPath, ToolError, } from "@capybara-hq/plugin-sdk";
+import { parseSkillMd, renderSkillBody, SKILL_ENTRY_FILE, SKILL_INVOCATION_LIMITS, SKILLS_SANDBOX_ROOT, skillSandboxPath, ToolError, } from "@capybara-hq/plugin-sdk";
 import { sql } from "kysely";
 import { normalizeStoredDefinition } from "../../agents/definition.js";
 import { ApiError } from "../../errors.js";
@@ -7,10 +7,10 @@ import { latestInvocation } from "../../runtime/context/skills.js";
 import { dispatchOfChildRun } from "../../runtime/subagents/child.js";
 import { resolveSkillForkType } from "../../runtime/subagents/roster.js";
 import { invocationOf, resolveSkills } from "../../skills/catalog.js";
+import { AGENT_TOOL, SANDBOX_TOOL_NAMES } from "../builtin-names.js";
 import { clip, display, inSandbox, sandboxBaseTimeoutMs, withNotices, withPathLease, } from "./sandbox/common.js";
-import { SANDBOX_TOOL_NAMES } from "./sandbox/names.js";
 /**
- * 内置工具 `skill_load`（M5 T14，Ruling M17）：按日志里最新一份技能目录快照把名字解析为 id 与版本，返回该版本
+ * 内置工具 `Skill`（M5 T14，Ruling M17）：按日志里最新一份技能目录快照把名字解析为 id 与版本，返回该版本
  * SKILL.md 的正文与文件清单（结果里写明版本）。技能带其他文件时把整个技能复制进本对话沙箱的 `/skills/<name>/`
  * （提供方以 root 写，命令用户只读）；没有沙箱提供方时只给正文，并说明脚本不可用。
  *
@@ -36,26 +36,32 @@ const MAX_LISTED_FILES = 200;
 /** 「不在目录里」的错误里最多列出的技能名。 */
 const MAX_LISTED_NAMES = 50;
 const SPEC = {
-    name: "skill_load",
+    name: "Skill",
     // Display only (the tool row; not in the fingerprint, never sent to the model).
-    keyArgs: ["name"],
+    keyArgs: ["skill"],
     description: "Load a skill from the skills list: returns the skill's instructions " +
         "(its SKILL.md) and the list of its files. Call it before starting a task that matches a " +
         "skill's description, then follow the returned instructions. If the skill has scripts or other " +
         "files, they are copied read-only to /skills/<name>/ in this conversation's sandbox; run scripts " +
         "there with an interpreter (sh, python3, node). Call it again when the skills list changes or " +
-        "the sandbox was recreated. Do not use it for skills that are not in the list.",
+        "the sandbox was recreated. Pass args when the task gives the skill arguments (they replace " +
+        "$ARGUMENTS and $1, $2… in the instructions). Do not use it for skills that are not in the list.",
     inputSchema: {
         type: "object",
         properties: {
-            name: {
+            skill: {
                 type: "string",
                 minLength: 1,
                 maxLength: 64,
                 description: 'The skill name exactly as listed, e.g. "pdf-report".',
             },
+            args: {
+                type: "string",
+                maxLength: SKILL_INVOCATION_LIMITS.argumentsMaxChars,
+                description: 'Optional arguments for the skill, e.g. "123 api".',
+            },
         },
-        required: ["name"],
+        required: ["skill"],
         additionalProperties: false,
     },
     annotations: { readOnlyHint: true },
@@ -66,11 +72,11 @@ const STORAGE_UNAVAILABLE_TEXT = "File storage is temporarily unavailable, so th
 const notInCatalog = (name, skills) => {
     const names = skills.slice(0, MAX_LISTED_NAMES).map((s) => s.name);
     const more = skills.length > names.length ? ", …" : "";
-    return `Skill "${clip(name, 80)}" is not in the skills catalog for this conversation; call skill_load with one of the listed names: ${names.join(", ")}${more}.`;
+    return `Skill "${clip(name, 80)}" is not in the skills catalog for this conversation; call Skill with one of the listed names: ${names.join(", ")}${more}.`;
 };
 const removedText = (name) => `Skill "${name}" was removed after the skills list was shown and can no longer be loaded; do the task without it, or ask the user to restore it.`;
 /** Phase D spec §4.4: the line before a forked skill's instructions (model-visible, English). */
-const forkAvailableText = (type) => `This skill is written to run in a sub-agent: call agent with subagent_type "${type}" and a prompt containing these instructions and the details of the task, then use its report; do not follow the instructions yourself.`;
+const forkAvailableText = (type) => `This skill is written to run in a sub-agent: call Agent with subagent_type "${type}" and a prompt containing these instructions and the details of the task, then use its report; do not follow the instructions yourself.`;
 const FORK_UNAVAILABLE_TEXT = "This skill is written to run in a sub-agent, which is not available here; follow the instructions yourself.";
 const integrityText = (name) => `Skill "${name}" failed an integrity check (its stored files do not match the uploaded package); ask an administrator to upload the skill again.`;
 const strings = (v) => Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
@@ -333,11 +339,11 @@ async function invokedEntry(db, ctx, name) {
     };
 }
 /**
- * The line before a forked skill's instructions (spec §4.4): run it through `agent` when this step
+ * The line before a forked skill's instructions (spec §4.4): run it through `Agent` when this step
  * offers the tool and the skill's type is in the agent's roster, else follow it yourself.
  */
 async function forkLine(db, ctx, fork, plugin) {
-    const hasAgent = (ctx.tools ?? []).some((t) => t.source.kind === "builtin" && t.source.name === "agent");
+    const hasAgent = (ctx.tools ?? []).some((t) => t.source.kind === "builtin" && t.source.name === AGENT_TOOL);
     if (!hasAgent)
         return FORK_UNAVAILABLE_TEXT;
     const agent = await runAgent(db, ctx);
@@ -346,7 +352,7 @@ async function forkLine(db, ctx, fork, plugin) {
     const type = await resolveSkillForkType(db, ctx.orgId, agent.definition, fork.agent, plugin);
     return type.inRoster ? forkAvailableText(type.agentType) : FORK_UNAVAILABLE_TEXT;
 }
-/** 内置工具 `skill_load`（见文件头）。 */
+/** 内置工具 `Skill`（见文件头）。 */
 export function skillLoadTool(deps) {
     return {
         spec: SPEC,
@@ -354,7 +360,7 @@ export function skillLoadTool(deps) {
         // 可能要创建 / 恢复沙箱并复制文件：与沙箱工具同一时限
         timeoutMs: () => sandboxBaseTimeoutMs(deps.config.get()),
         async run(input, ctx) {
-            const asked = input.name;
+            const { skill: asked, args } = input;
             const snap = await deps.eventLog.latestOfType(ctx.conversationId, "skills_catalog");
             const skills = snap?.payload.skills ?? [];
             let entry = findEntry(skills, asked);
@@ -430,12 +436,22 @@ export function skillLoadTool(deps) {
                         "or `node`; the files are not executable, so `./script` does not work. Write outputs under " +
                         `/workspace, not ${SKILLS_SANDBOX_ROOT}.${stale}`;
             }
-            const fork = invocationOf(manifest).fork;
+            const invocation = invocationOf(manifest);
+            const fork = invocation.fork;
+            let instructions;
+            try {
+                instructions = renderSkillBody(parsed.body.trim(), invocation, args ?? "", name);
+            }
+            catch (e) {
+                if (!(e instanceof RangeError))
+                    throw e;
+                throw new ToolError(`Skill "${name}" cannot be rendered: ${e.message}; check the args against the skill's placeholders and retry with shorter args.`);
+            }
             const text = [
                 ...(fork ? [await forkLine(deps.db, ctx, fork, entry.plugin)] : []),
                 `Loaded skill "${name}" (version ${entry.version}).`,
                 filesText,
-                `<skill name="${name}" version="${entry.version}">\n${parsed.body.trim()}\n</skill>`,
+                `<skill name="${name}" version="${entry.version}">\n${instructions}\n</skill>`,
             ].join("\n\n");
             return {
                 content: [{ type: "text", text: withNotices(notices, text) }],

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

@@ -2,7 +2,7 @@ import type { SkillManifest } from "../../db/kernel-schema.js";
 import type { SkillChangesService } from "../../skills/changes.service.js";
 import type { BuiltinTool } from "../registry.js";
 /**
- * 内置工具 `skill_write`（M5 T15，R4）：agent 新建或更新它自己的技能（`scope = agent`）。
+ * 内置工具 `SkillWrite`（M5 T15，R4）：agent 新建或更新它自己的技能（`scope = agent`）。
  * - 输入 `{ name, description, files: [{ path, content }] }`，只收文本文件，整个技能 ≤ {@link SKILL_WRITE_MAX_BYTES}；
  * - the kernel generates SKILL.md ({@link buildSkillWrite}): its frontmatter is `name` / `description`
  *   plus the invocation keys (`disable-model-invocation`, `context`, ... phase D) of the frontmatter
@@ -11,13 +11,13 @@ import type { BuiltinTool } from "../registry.js";
  * - 每次调用写一个完整的新版本（上一版有、这次没给的文件不再属于新版本）；
  * - 私有 agent 直接生成新版本并立即生效；共享 agent 由触发对话的人先确认这次调用（R3 固定 ask，见 tools/policy.ts），
  *   再生成变更申请等负责人批准，期间只有本对话试用新版本（见 skills/changes.service.ts）；
- * - 成功后立即在日志追加技能目录快照（`skills_catalog`，Ruling M17），同一运行的下一步就能 `skill_load`。
+ * - 成功后立即在日志追加技能目录快照（`skills_catalog`，Ruling M17），同一运行的下一步就能 `Skill`。
  */
 /** 一个技能（含合成的 SKILL.md）的总大小上限（UTF-8 字节）。 */
 export declare const SKILL_WRITE_MAX_BYTES: number;
 /** 一次最多的文件数（含 SKILL.md）。 */
 export declare const SKILL_WRITE_MAX_FILES = 200;
-/** `skill_write` 的输入（已按 inputSchema 校验）。 */
+/** `SkillWrite` 的输入（已按 inputSchema 校验）。 */
 export interface SkillWriteInput {
     name: string;
     description: string;
@@ -55,5 +55,5 @@ export declare function buildSkillWrite(input: SkillWriteInput): BuiltSkill | {
 export interface SkillWriteDeps {
     changes: Pick<SkillChangesService, "write">;
 }
-/** 内置工具 `skill_write`（见文件头）。 */
+/** 内置工具 `SkillWrite`（见文件头）。 */
 export declare function skillWriteTool(deps: SkillWriteDeps): BuiltinTool;

package/dist/tools/builtins/skill-write.js

@@ -4,7 +4,7 @@ import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 import { storedInvocation } from "../../skills/package.js";
 import { display } from "./sandbox/common.js";
 /**
- * 内置工具 `skill_write`（M5 T15，R4）：agent 新建或更新它自己的技能（`scope = agent`）。
+ * 内置工具 `SkillWrite`（M5 T15，R4）：agent 新建或更新它自己的技能（`scope = agent`）。
  * - 输入 `{ name, description, files: [{ path, content }] }`，只收文本文件，整个技能 ≤ {@link SKILL_WRITE_MAX_BYTES}；
  * - the kernel generates SKILL.md ({@link buildSkillWrite}): its frontmatter is `name` / `description`
  *   plus the invocation keys (`disable-model-invocation`, `context`, ... phase D) of the frontmatter
@@ -13,16 +13,16 @@ import { display } from "./sandbox/common.js";
  * - 每次调用写一个完整的新版本（上一版有、这次没给的文件不再属于新版本）；
  * - 私有 agent 直接生成新版本并立即生效；共享 agent 由触发对话的人先确认这次调用（R3 固定 ask，见 tools/policy.ts），
  *   再生成变更申请等负责人批准，期间只有本对话试用新版本（见 skills/changes.service.ts）；
- * - 成功后立即在日志追加技能目录快照（`skills_catalog`，Ruling M17），同一运行的下一步就能 `skill_load`。
+ * - 成功后立即在日志追加技能目录快照（`skills_catalog`，Ruling M17），同一运行的下一步就能 `Skill`。
  */
 /** 一个技能（含合成的 SKILL.md）的总大小上限（UTF-8 字节）。 */
 export const SKILL_WRITE_MAX_BYTES = 1024 * 1024;
 /** 一次最多的文件数（含 SKILL.md）。 */
 export const SKILL_WRITE_MAX_FILES = 200;
 const SPEC = {
-    name: "skill_write",
+    name: "SkillWrite",
     description: "Create or update one of this agent's own skills: reusable instructions plus optional text files " +
-        "(scripts, templates, reference notes) that you or later conversations can load with skill_load. " +
+        "(scripts, templates, reference notes) that you or later conversations can load with Skill. " +
         "Each call writes a complete new version. SKILL.md is generated for you: its frontmatter comes from " +
         "`name` and `description`, and its body is the content of the `SKILL.md` entry in `files` if you " +
         "include one (its frontmatter is dropped, except the invocation keys disable-model-invocation, " +
@@ -186,7 +186,7 @@ export function buildSkillWrite(input) {
         },
     };
 }
-/** 内置工具 `skill_write`（见文件头）。 */
+/** 内置工具 `SkillWrite`（见文件头）。 */
 export function skillWriteTool(deps) {
     return {
         spec: SPEC,
@@ -195,7 +195,7 @@ export function skillWriteTool(deps) {
         async run(input, ctx) {
             const built = buildSkillWrite(input);
             if ("errors" in built) {
-                throw new ToolError(`The skill was not written. Fix these problems and call skill_write again:\n- ${built.errors.slice(0, 20).join("\n- ")}`);
+                throw new ToolError(`The skill was not written. Fix these problems and call SkillWrite again:\n- ${built.errors.slice(0, 20).join("\n- ")}`);
             }
             const r = await deps.changes.write({
                 orgId: ctx.orgId,
@@ -205,10 +205,10 @@ export function skillWriteTool(deps) {
                 ...(ctx.runId !== undefined && { runId: ctx.runId }),
             }, built);
             const name = built.name;
-            // A manual-only version (phase D) is not in the model's catalog, so skill_load cannot load it
+            // A manual-only version (phase D) is not in the model's catalog, so Skill cannot load it
             const manualOnly = built.manifest.invocation?.model === false;
             const manualText = `It is manual-only (disable-model-invocation: true): it is not in your skills catalog and ` +
-                `skill_load cannot load it; a person invokes it with /${name}.`;
+                `Skill cannot load it; a person invokes it with /${name}.`;
             if (r.kind === "version") {
                 const what = r.created ? "Created" : "Updated";
                 return {
@@ -218,7 +218,7 @@ export function skillWriteTool(deps) {
                             text: `${what} skill "${name}" (version ${r.version}, ${built.files.length} files). ` +
                                 (manualOnly
                                     ? `It is in effect now for every conversation with this agent. ${manualText}`
-                                    : "It is in effect now for every conversation with this agent; call skill_load to use it."),
+                                    : "It is in effect now for every conversation with this agent; call Skill to use it."),
                         },
                     ],
                     display: display(`${r.created ? "新建" : "更新"}技能 ${name}（版本 ${r.version}）`, `${what} skill ${name} (version ${r.version})`),
@@ -232,7 +232,7 @@ export function skillWriteTool(deps) {
                             "awaiting the owner's approval, because this agent is shared. Until the owner approves it, " +
                             (manualOnly
                                 ? `the new version applies only in this conversation; other conversations keep the current version. ${manualText} `
-                                : "the new version is usable only in this conversation (call skill_load to use it); other " +
+                                : "the new version is usable only in this conversation (call Skill to use it); other " +
                                     "conversations keep the current version. ") +
                             "Tell the user the change needs the owner's approval.",
                     },

package/dist/tools/builtins/tool-search.d.ts

@@ -1,13 +1,15 @@
-import type { ToolSpec } from "@capybara-hq/plugin-sdk";
-import { type BuiltinTool, type ResolvedTool } from "../registry.js";
-/** 内置工具名。 */
-export declare const TOOL_SEARCH = "tool_search";
+import { type ToolSpec } from "@capybara-hq/plugin-sdk";
+import type { BuiltinTool, ResolvedTool } from "../registry.js";
+export { TOOL_SEARCH } from "../builtin-names.js";
 export declare const TOOL_SEARCH_SPEC: ToolSpec;
 /** 目录（system 第二个块）的开头说明（模型可见，英文）。 */
 export declare const CATALOG_HEADER: string;
 /** 调用目录里尚未加载的工具（模型可见，英文；spec 5.5：不自动加载）。 */
 export declare const notLoadedText: (key: string) => string;
-/** 始终完整加载、不进目录的工具（内置工具）。 */
+/**
+ * 始终完整加载、不进目录的工具（内置工具）。A release-candidate builtin key counts too: a request
+ * recorded before the tool rename is rebuilt with its old keys, and its builtins were loaded.
+ */
 export declare const isAlwaysLoaded: (key: string) => boolean;
 type CatalogTool = Pick<ResolvedTool, "key" | "spec">;
 /** 分词：切开驼峰，按非字母数字切分，转小写。 */
@@ -20,12 +22,14 @@ export declare function tokenize(text: string): string[];
 export declare function searchTools<T extends CatalogTool>(query: string, tools: readonly T[], limit: number): T[];
 /** 目录行：`- <key>: <描述的第一行>`（超长截断）。 */
 export declare function catalogLine(t: CatalogTool): string;
-/** 目录全文：开头说明 + 按 key 排序的目录行。只依赖工具集合，与加载状态无关（缓存前缀稳定）。 */
-export declare function catalogText(tools: readonly CatalogTool[]): string;
 /**
- * 内置工具 `tool_search`（spec 5.5）：在本次运行可用、但未直接加载的工具中按关键词搜索，返回完整定义，
+ * 目录全文：开头说明 + 按 key 排序的目录行。只依赖工具集合，与加载状态无关（缓存前缀稳定）。
+ * `header`: a request recorded before the tool rename passes the frozen legacy header.
+ */
+export declare function catalogText(tools: readonly CatalogTool[], header?: string): string;
+/**
+ * 内置工具 `ToolSearch`（spec 5.5）：在本次运行可用、但未直接加载的工具中按关键词搜索，返回完整定义，
  * 并在结果里带 `loadedTools`（管线写进 `tool_result.loadedTools`；已加载集合只由日志还原）。
  * 搜索范围来自管线传入的 `ctx.tools`（本步解析出的工具）；内置工具始终加载，不参与搜索。
  */
 export declare function toolSearchTool(): BuiltinTool;
-export {};

package/dist/tools/builtins/tool-search.js

@@ -1,6 +1,7 @@
-import { BUILTIN_TOOL_NAMES } from "../registry.js";
-/** 内置工具名。 */
-export const TOOL_SEARCH = "tool_search";
+import { parseToolKey } from "@capybara-hq/plugin-sdk";
+import { BUILTIN_TOOL_NAMES, TOOL_SEARCH } from "../builtin-names.js";
+import { isLegacyBuiltinKey } from "../legacy-keys.js";
+export { TOOL_SEARCH } from "../builtin-names.js";
 /** 默认返回的匹配数。 */
 const DEFAULT_LIMIT = 5;
 /** 单次最多返回的匹配数。 */
@@ -27,7 +28,7 @@ export const TOOL_SEARCH_SPEC = {
                 maxLength: 500,
                 description: "Keywords describing the tool you need, e.g. 'create calendar event'.",
             },
-            limit: {
+            max_results: {
                 type: "integer",
                 minimum: 1,
                 maximum: MAX_LIMIT,
@@ -40,16 +41,23 @@ export const TOOL_SEARCH_SPEC = {
     annotations: { readOnlyHint: true },
 };
 /** 目录（system 第二个块）的开头说明（模型可见，英文）。 */
-export const CATALOG_HEADER = "More tools are available but not loaded. To use one, first call tool_search with keywords; " +
+export const CATALOG_HEADER = "More tools are available but not loaded. To use one, first call ToolSearch with keywords; " +
     "it returns the full definitions and loads the matching tools for your next step. " +
     "Calling a tool that is not loaded returns an error. Tool catalog:";
 /** 调用目录里尚未加载的工具（模型可见，英文；spec 5.5：不自动加载）。 */
-export const notLoadedText = (key) => `Tool "${key}" is not loaded. Call tool_search first with keywords for this tool, then call it in a later step.`;
-/** 始终完整加载、不进目录的工具（内置工具）。 */
-export const isAlwaysLoaded = (key) => BUILTIN_TOOL_NAMES.includes(key);
+export const notLoadedText = (key) => `Tool "${key}" is not loaded. Call ToolSearch first with keywords for this tool, then call it in a later step.`;
+/**
+ * 始终完整加载、不进目录的工具（内置工具）。A release-candidate builtin key counts too: a request
+ * recorded before the tool rename is rebuilt with its old keys, and its builtins were loaded.
+ */
+export const isAlwaysLoaded = (key) => BUILTIN_TOOL_NAMES.includes(key) || isLegacyBuiltinKey(key);
 /** 分词：切开驼峰，按非字母数字切分，转小写。 */
 export function tokenize(text) {
+    const parsed = parseToolKey(text);
+    // The family token (`mcp`, `plugin`) is the same on every connector or extension key: drop it.
+    const family = parsed && parsed.kind !== "builtin" ? text.indexOf("__") + 2 : 0;
     return text
+        .slice(family)
         .replace(/([\p{Ll}\p{N}])(\p{Lu})/gu, "$1 $2")
         .toLowerCase()
         .split(/[^\p{L}\p{N}]+/u)
@@ -106,12 +114,15 @@ export function catalogLine(t) {
         : first;
     return `- ${t.key}: ${desc}`;
 }
-/** 目录全文：开头说明 + 按 key 排序的目录行。只依赖工具集合，与加载状态无关（缓存前缀稳定）。 */
-export function catalogText(tools) {
+/**
+ * 目录全文：开头说明 + 按 key 排序的目录行。只依赖工具集合，与加载状态无关（缓存前缀稳定）。
+ * `header`: a request recorded before the tool rename passes the frozen legacy header.
+ */
+export function catalogText(tools, header = CATALOG_HEADER) {
     const sorted = [...tools].sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
-    return [CATALOG_HEADER, ...sorted.map(catalogLine)].join("\n");
+    return [header, ...sorted.map(catalogLine)].join("\n");
 }
-/** 一个工具的完整定义文本（tool_search 的结果）。 */
+/** 一个工具的完整定义文本（`ToolSearch` 的结果）。 */
 function definitionText(t) {
     return [
         `Tool: ${t.key}`,
@@ -128,7 +139,7 @@ function displayQuery(query) {
     return cps.length > DISPLAY_QUERY_MAX ? `${cps.slice(0, DISPLAY_QUERY_MAX - 1).join("")}…` : one;
 }
 /**
- * 内置工具 `tool_search`（spec 5.5）：在本次运行可用、但未直接加载的工具中按关键词搜索，返回完整定义，
+ * 内置工具 `ToolSearch`（spec 5.5）：在本次运行可用、但未直接加载的工具中按关键词搜索，返回完整定义，
  * 并在结果里带 `loadedTools`（管线写进 `tool_result.loadedTools`；已加载集合只由日志还原）。
  * 搜索范围来自管线传入的 `ctx.tools`（本步解析出的工具）；内置工具始终加载，不参与搜索。
  */
@@ -137,7 +148,7 @@ export function toolSearchTool() {
         spec: TOOL_SEARCH_SPEC,
         defaultPolicy: "allow",
         async run(input, ctx) {
-            const { query, limit = DEFAULT_LIMIT } = input;
+            const { query, max_results: limit = DEFAULT_LIMIT } = input;
             const catalog = (ctx.tools ?? []).filter((t) => !isAlwaysLoaded(t.key));
             const found = searchTools(query, catalog, limit);
             const q = displayQuery(query);