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

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, skillDigest, skillSandboxDir, skillSandboxPath, ToolError, } from "@capybara-hq/plugin-sdk";
 import { sql } from "kysely";
 import { normalizeStoredDefinition } from "../../agents/definition.js";
 import { ApiError } from "../../errors.js";
@@ -7,55 +7,67 @@ 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 { clip, display, inSandbox, sandboxBaseTimeoutMs, withNotices, withPathLease, } from "./sandbox/common.js";
-import { SANDBOX_TOOL_NAMES } from "./sandbox/names.js";
+import { PLATFORM_SOURCE, skillFileStore } from "../../skills/usable.js";
+import { AGENT_TOOL, SANDBOX_TOOL_NAMES } from "../builtin-names.js";
+import { clip, display, inSandbox, sandboxBaseTimeoutMs, sandboxConversationOf, sandboxUsable, withNotices, withPathLease, } from "./sandbox/common.js";
 /**
- * 内置工具 `skill_load`（M5 T14，Ruling M17）：按日志里最新一份技能目录快照把名字解析为 id 与版本，返回该版本
- * SKILL.md 的正文与文件清单（结果里写明版本）。技能带其他文件时把整个技能复制进本对话沙箱的 `/skills/<name>/`
- * （提供方以 root 写，命令用户只读）；没有沙箱提供方时只给正文，并说明脚本不可用。
+ * Builtin tool `Skill` (M5 T14, ruling M17): resolves the name against the latest skills catalog
+ * snapshot in the log to an id and version, and returns that version's SKILL.md body and file list
+ * (the result names the version). A skill with other files is copied whole into the conversation's
+ * device at `<skills root>/<name>@<digest>/` (the instance's skills root, `/skills` by default; the provider writes as root, commands read only; the
+ * digest is {@link skillDigest} of the version's file manifest, so versions of one skill coexist in
+ * the shared file system). Without a sandbox provider only the body is given, with a note that
+ * scripts are unavailable.
  *
- * - 存储里读出的每个文件都按清单的 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`，每次加载都在结果里列出「不属于当前版本、忽略它们」。
+ * - Every file read from storage is checked against the manifest's sha256; a mismatch is refused.
+ * - The copy is recorded in a kernel-controlled marker, one per skill version
+ *   ({@link skillMarkerPath}: `<skills root>/.capybara/<name>@<digest>.json`, commands cannot change it):
+ *   `{ digest, files }`. A present marker with the same digest skips the copy.
+ * - An agent without any sandbox tool creates no sandbox and copies nothing (the model could not
+ *   run the scripts), and is told so.
+ * - Executable bit: files the provider writes are never executable (0644). The result tells the model
+ *   to run scripts with an interpreter (`sh` / `python3` / `node`).
  */
 /**
- * 已复制进沙箱的技能的标记目录（内核控制：`/skills` 只有提供方以 root 能写；技能名不以 `.` 开头，不会撞名）。
+ * 已复制进沙箱的技能的标记目录（内核控制：技能根目录只有提供方以 root 能写；技能名不以 `.` 开头，不会撞名）。
+ * `skillsRoot`: the instance's skills root.
  */
-export const SKILLS_MARKER_DIR = `${SKILLS_SANDBOX_ROOT}/.capybara`;
-/** 一个技能的标记文件。 */
-export const skillMarkerPath = (name) => `${SKILLS_MARKER_DIR}/${name}.json`;
+export const skillsMarkerDir = (skillsRoot = SKILLS_SANDBOX_ROOT) => `${skillsRoot}/.capybara`;
+/** {@link skillsMarkerDir} of an instance with the default roots. */
+export const SKILLS_MARKER_DIR = skillsMarkerDir();
+/** The marker file of one skill version. */
+export const skillMarkerPath = (name, digest, skillsRoot = SKILLS_SANDBOX_ROOT) => `${skillsMarkerDir(skillsRoot)}/${name}@${digest}.json`;
 const MARKER_MAX_BYTES = 256 * 1024;
 /** 结果里最多列出的文件数（其余只给数量）。 */
 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.",
+        "files, they are copied read-only to <name>@<version-id>/ in the skills directory of this device; run scripts " +
+        "there with an interpreter (sh, python3, node). Call it again when the skills list changes. 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,29 +78,27 @@ 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") : [];
-/** 解析一个技能的标记文件；坏的按没有处理（重新复制）。 */
+/** Parses a version's marker; a broken one counts as missing (the version is copied again). */
 function parseMarker(data) {
     try {
         const r = JSON.parse(new TextDecoder().decode(data));
         if (r === null || typeof r !== "object" || Array.isArray(r))
             return undefined;
         const e = r;
-        if (typeof e.id !== "string" || typeof e.version !== "number")
+        if (typeof e.digest !== "string")
             return undefined;
         return {
-            id: e.id,
-            version: e.version,
-            ...(typeof e.prefix === "string" && { prefix: e.prefix }),
-            files: strings(e.files),
-            stale: strings(e.stale),
+            digest: e.digest,
+            files: Array.isArray(e.files)
+                ? e.files.filter((x) => typeof x === "string")
+                : [],
         };
     }
     catch {
@@ -150,34 +160,25 @@ async function readVerified(store, key, file, skill, signal) {
     }
 }
 /**
- * 把技能整个复制到 `/skills/<name>/`（标记命中则跳过）。每个文件按清单核对后写入，全部写完才更新标记：
- * 中途失败下次整体重来。返回旧版本留下的文件。
+ * Copies the skill version whole to `<skills root>/<name>@<digest>/` (skipped when its marker matches).
+ * Every file is checked against the manifest before it is written; the marker is written last, so
+ * a failure midway means the next call starts over.
  */
 async function copySkill(s, v) {
-    const { name, id, version } = v.entry;
-    const markerPath = skillMarkerPath(name);
-    let cur;
-    if (!s.reset) {
-        const m = await s.p.readFile(s.h, markerPath, { maxBytes: MARKER_MAX_BYTES, signal: s.signal });
-        if (m && !m.truncated)
-            cur = parseMarker(m.data);
-    }
-    if (cur && cur.id === id && cur.version === version && cur.prefix === v.prefix) {
-        return { stale: cur.stale };
-    }
+    const { name } = v.entry;
+    const markerPath = skillMarkerPath(name, v.digest, s.roots.skills);
+    const m = await s.p.readFile(s.h, markerPath, { maxBytes: MARKER_MAX_BYTES, signal: s.signal });
+    const cur = m && !m.truncated ? parseMarker(m.data) : undefined;
+    if (cur?.digest === v.digest)
+        return;
     for (const f of v.manifest.files) {
         const data = f.path === SKILL_ENTRY_FILE
             ? v.entryBytes
-            : await readVerified(v.store, `${v.prefix}${f.path}`, f, name, s.signal);
-        await s.p.writeFile(s.h, skillSandboxPath(name, f.path), data, s.signal);
+            : await readVerified(v.store, `${v.keyPrefix}${f.path}`, f, name, s.signal);
+        await s.p.writeFile(s.h, skillSandboxPath(name, v.digest, f.path, s.roots.skills), data, s.signal);
     }
-    const files = v.manifest.files.map((f) => f.path);
-    const now = new Set(files);
-    const stale = cur ? [...new Set([...cur.stale, ...cur.files])].filter((p) => !now.has(p)) : [];
-    stale.sort();
-    const entry = { id, version, prefix: v.prefix, files, stale };
+    const entry = { digest: v.digest, files: v.manifest.files.map((f) => f.path) };
     await s.p.writeFile(s.h, markerPath, new TextEncoder().encode(JSON.stringify(entry)), s.signal);
-    return { stale };
 }
 /** 本步可用的工具里是否有沙箱工具（没有时模型用不了复制进去的文件）。 */
 const hasSandboxTools = (ctx) => (ctx.tools ?? []).some((t) => t.source.kind === "builtin" &&
@@ -194,8 +195,15 @@ function fileList(files) {
  * 批准时草稿前缀原样成为版本前缀，版本号变了也能找到），再找本对话发起、仍待批准、前缀相同的技能改动（试用草稿：
  * 没有 `skill_versions` 行，新技能连 `skills` 行都没有）。绝不按版本号解析——被拒绝的草稿与之后别人批准的同号版本
  * 内容不同。都没有 → undefined（已移除）。
+ *
+ * Phase 2 (ruling D2): a `platform:<prefix>` source is a platform skill version: found by its
+ * prefix for the platform skill with the entry's id, or the platform skill an org copy with that id
+ * links to (ruling B2), while neither is deleted. The returned `object_prefix` keeps the
+ * `platform:` form; `skillFileStore` picks the store for it.
  */
 export async function findSkillVersion(db, ctx, entry) {
+    if (entry.source.startsWith(PLATFORM_SOURCE))
+        return findPlatformVersion(db, ctx.orgId, entry);
     const row = await db
         .selectFrom("skills")
         .innerJoin("skill_versions", "skill_versions.skill_id", "skills.id")
@@ -212,6 +220,7 @@ export async function findSkillVersion(db, ctx, entry) {
         .where("org_id", "=", ctx.orgId)
         .where("requested_in_conversation", "=", ctx.conversationId)
         .where("status", "=", "pending")
+        .where("kind", "=", "version")
         .where("object_prefix", "=", entry.source)
         .where(sql `proposed_version ->> 'skillId'`, "=", entry.id)
         .executeTakeFirst();
@@ -219,6 +228,29 @@ export async function findSkillVersion(db, ctx, entry) {
         return undefined;
     return { manifest: draft.proposed_version.manifest, object_prefix: draft.object_prefix };
 }
+/** {@link findSkillVersion} for a `platform:<prefix>` source. */
+async function findPlatformVersion(db, orgId, entry) {
+    const row = await db
+        .selectFrom("platform_skill_versions as v")
+        .innerJoin("platform_skills as p", "p.id", "v.skill_id")
+        .select(["v.manifest"])
+        .where("v.object_prefix", "=", entry.source.slice(PLATFORM_SOURCE.length))
+        .where("p.deleted_at", "is", null)
+        // a platform skill disabled on the deployment is not loaded, even from an older snapshot
+        .where("p.disabled", "=", false)
+        .where((eb) => eb.or([
+        eb("p.id", "=", entry.id),
+        eb("p.id", "in", eb
+            .selectFrom("skills")
+            .select("platform_skill_id")
+            .where("id", "=", entry.id)
+            .where("org_id", "=", orgId)
+            .where("deleted_at", "is", null)
+            .where("platform_skill_id", "is not", null)),
+    ]))
+        .executeTakeFirst();
+    return row && { manifest: row.manifest, object_prefix: entry.source };
+}
 /** A Claude Code style qualified name `<plugin>:<skill>` (phase B, spec §9.3). */
 const QUALIFIED_NAME_RE = /^([a-z0-9][a-z0-9-]{0,63}):(.+)$/;
 /**
@@ -333,11 +365,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 +378,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 +386,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);
@@ -379,13 +411,23 @@ export function skillLoadTool(deps) {
             if (!row)
                 throw new ToolError(removedText(name));
             const manifest = row.manifest;
-            const store = deps.storage.kernel(ctx.orgId);
+            // the marker records the source (`platform:` included); keys use the store's own prefix
             const prefix = row.object_prefix;
+            const { store, prefix: keyPrefix } = skillFileStore(deps.storage, ctx.orgId, prefix);
             const md = manifest.files.find((f) => f.path === SKILL_ENTRY_FILE);
             if (!md)
                 throw new ToolError(integrityText(name));
-            const mdBytes = await readVerified(store, `${prefix}${md.path}`, md, name, ctx.signal);
-            const v = { entry, manifest, prefix, store, entryBytes: mdBytes };
+            const mdBytes = await readVerified(store, `${keyPrefix}${md.path}`, md, name, ctx.signal);
+            const digest = skillDigest(manifest.files);
+            const v = {
+                entry,
+                manifest,
+                digest,
+                prefix,
+                keyPrefix,
+                store,
+                entryBytes: mdBytes,
+            };
             let parsed;
             try {
                 parsed = parseSkillMd(new TextDecoder("utf-8", { fatal: true }).decode(mdBytes), {
@@ -397,14 +439,15 @@ export function skillLoadTool(deps) {
             }
             if ("errors" in parsed)
                 throw new ToolError(integrityText(name));
-            const dir = `${SKILLS_SANDBOX_ROOT}/${name}/`;
+            // the skills root of the instance the files were copied to (the default without a copy)
+            let skillsRoot = SKILLS_SANDBOX_ROOT;
             const others = manifest.files.filter((f) => f.path !== SKILL_ENTRY_FILE);
             let notices = [];
             let filesText;
             if (others.length === 0) {
                 filesText = "This skill has no files besides its instructions.";
             }
-            else if (!deps.sandbox.available) {
+            else if (!(await sandboxUsable(deps, ctx.orgId, sandboxConversationOf(ctx)))) {
                 filesText =
                     `Skill files (for reference):\n${fileList(manifest.files)}\n` +
                         "This deployment has no sandbox, so the skill's scripts and other files are not available; " +
@@ -419,23 +462,32 @@ export function skillLoadTool(deps) {
             }
             else {
                 // the skill's marker is read, compared and written: one holder at a time per skill
-                const r = await inSandbox(deps, ctx, (s) => withPathLease(deps, ctx, skillMarkerPath(v.entry.name), s.signal, (signal) => copySkill({ ...s, signal }, v)));
+                const r = await inSandbox(deps, ctx, (s) => withPathLease(deps, s, skillMarkerPath(name, digest, s.roots.skills), s.signal, (signal) => copySkill({ ...s, signal }, v).then(() => s.roots)));
                 notices = r.notices;
-                const stale = r.value.stale.length > 0
-                    ? `\nFiles left over from an earlier version (not part of this version; ignore them): ${r.value.stale.join(", ")}`
-                    : "";
+                skillsRoot = r.value.skills;
+                const dir = `${skillSandboxDir(name, digest, skillsRoot)}/`;
                 filesText =
                     `Skill files (copied to ${dir} in the sandbox, read-only):\n${fileList(manifest.files)}\n` +
                         `Run scripts with an interpreter, e.g. \`sh ${dir}<script>.sh\`, \`python3 ${dir}<script>.py\` ` +
                         "or `node`; the files are not executable, so `./script` does not work. Write outputs under " +
-                        `/workspace, not ${SKILLS_SANDBOX_ROOT}.${stale}`;
+                        `${r.value.workspace}, not ${skillsRoot}.`;
+            }
+            const invocation = invocationOf(manifest);
+            const fork = invocation.fork;
+            let instructions;
+            try {
+                instructions = renderSkillBody(parsed.body.trim(), invocation, args ?? "", name, digest, skillsRoot);
+            }
+            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 fork = invocationOf(manifest).fork;
             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/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);

package/dist/tools/builtins/web/errors.d.ts

@@ -0,0 +1,8 @@
+/** Which web tool is calling its provider (it names the provider in some texts). */
+export type WebToolKind = "search" | "fetch";
+/**
+ * Rethrows a web provider's failure for the tool pipeline: a `WebProviderError` becomes a
+ * `ToolError` with its kind's fixed text; anything else is rethrown unchanged (the pipeline's
+ * generic failure, which names only the error class, never the provider's message).
+ */
+export declare function webToolError(e: unknown, tool: WebToolKind): never;

package/dist/tools/builtins/web/errors.js

@@ -0,0 +1,53 @@
+import { ToolError, WebProviderError } from "@capybara-hq/plugin-sdk";
+const KINDS = new Set([
+    "not_found",
+    "blocked",
+    "auth",
+    "rate_limited",
+    "unavailable",
+    "invalid",
+]);
+/**
+ * The kind of a provider's `WebProviderError`, or undefined for any other error. Matched by name
+ * as well as by class, so an extension bundled with its own copy of the class still maps.
+ */
+function providerErrorKind(e) {
+    if (!(e instanceof Error))
+        return undefined;
+    if (!(e instanceof WebProviderError) && e.name !== "WebProviderError")
+        return undefined;
+    const kind = e.kind;
+    return typeof kind === "string" && KINDS.has(kind) ? kind : undefined;
+}
+/**
+ * The fixed model-visible text of a provider error kind (web tools spec §4.2): providers never
+ * write model-visible text.
+ */
+function providerErrorText(kind, tool) {
+    const provider = tool === "search" ? "web search" : "web fetch";
+    switch (kind) {
+        case "auth":
+            return `The ${provider} provider rejected its credentials; ask an org admin to check the provider's configuration.`;
+        case "rate_limited":
+            return `The ${provider} provider is rate limiting this org; retry in a minute or continue without it.`;
+        case "not_found":
+            return "No results or page found; check the query or URL and retry.";
+        case "blocked":
+            return "The site refused the provider; use another source.";
+        case "unavailable":
+            return "The web provider is unavailable right now; retry later or continue without it.";
+        case "invalid":
+            return "The provider rejected the request; check the query or URL and retry.";
+    }
+}
+/**
+ * Rethrows a web provider's failure for the tool pipeline: a `WebProviderError` becomes a
+ * `ToolError` with its kind's fixed text; anything else is rethrown unchanged (the pipeline's
+ * generic failure, which names only the error class, never the provider's message).
+ */
+export function webToolError(e, tool) {
+    const kind = providerErrorKind(e);
+    if (kind === undefined)
+        throw e;
+    throw new ToolError(providerErrorText(kind, tool));
+}

package/dist/tools/builtins/web/extract.d.ts

@@ -0,0 +1,62 @@
+import { type Logger, type WebFetchPage } from "@capybara-hq/plugin-sdk";
+import type { EventLog } from "../../../conversations/event-log.js";
+import type { KernelConfigService } from "../../../infra/config/kernel-config.service.js";
+import { type ModelPurposesService } from "../../../models/purposes.js";
+import { type HookRunner } from "../../../runtime/hook-calls.js";
+import type { StepLog } from "../../../runtime/step-log.js";
+import type { UsageReporter } from "../../../runtime/usage-report.js";
+import type { BuiltinCallContext } from "../../registry.js";
+/**
+ * The `WebFetch` extraction call (web tools spec §5): the fetched page and the model's prompt go to
+ * the `web_fetch` model purpose (unmapped → the calling conversation's current chat model, a
+ * sub-agent's call: the sub-agent's), and only its answer comes back. One call, no tools, output
+ * capped at `web.fetch.maxAnswerTokens`. The page sits between a random per-call tag the system
+ * prompt names, so page text cannot close it or fake the prompt; it is cut to fit the purpose
+ * model's context window ({@link fitPage}). It fires `model.request` (a policy denial is the tool error
+ * {@link WEB_FETCH_DENIED_TEXT}, logged as any hook denial) and `model.response` like the title
+ * call; its tokens are a `usage` event with `purpose: "web_fetch"` and the call id, reported, and
+ * counted on the parent run of a sub-agent. The page itself is never stored and never returned:
+ * a failure is the tool error {@link WEB_FETCH_EXTRACT_FAILED_TEXT}. The call is not model-visible
+ * to the agent (its result is the recorded `tool_result`), so replays never make it.
+ */
+/**
+ * The fixed start of the extraction call's system prompt (model-facing, English; a core constant).
+ * The prompt sent is {@link webFetchSystemPrompt}, which adds the call's page tag.
+ */
+export declare const WEB_FETCH_SYSTEM_PROMPT: string;
+/** The system prompt of one extraction call: {@link WEB_FETCH_SYSTEM_PROMPT} naming its page tag. */
+export declare function webFetchSystemPrompt(tag: string): string;
+/** The tool error when the extraction call fails (the page is never returned instead). */
+export declare const WEB_FETCH_EXTRACT_FAILED_TEXT = "Could not extract an answer from the page; retry, or try another URL.";
+/** The tool error when a `model.request` policy hook denies the extraction call. */
+export declare const WEB_FETCH_DENIED_TEXT = "An org policy blocked reading this page; continue without it or ask the user.";
+/** What {@link extractAnswer} needs. */
+export interface WebFetchExtractDeps {
+    purposes: Pick<ModelPurposesService, "chat" | "chatLimits">;
+    eventLog: Pick<EventLog, "append" | "notify" | "latestOfType">;
+    stepLog: Pick<StepLog, "appendCounted" | "appendAudited">;
+    config: Pick<KernelConfigService, "get">;
+    log: Pick<Logger, "warn">;
+    /** Extension hooks (absent: none fire). */
+    hooks?: HookRunner | undefined;
+    usageReport?: Pick<UsageReporter, "enqueue"> | undefined;
+}
+/**
+ * The user message of the extraction call: the URL, then the page (title, markdown) between
+ * `<tag>` and `</tag>`, then the prompt.
+ */
+export declare function extractionMessage(page: WebFetchPage, prompt: string, tag: string): string;
+/**
+ * The page cut so the extraction request fits the purpose model's context (web tools spec §4.2):
+ * system prompt + message + answer cap + headroom within `contextWindow`, by the kernel's
+ * `estimateTokens`. A cut page ends with {@link TRUNCATED_MARKER}; one that fits is unchanged.
+ */
+export declare function fitPage(page: WebFetchPage, prompt: string, tag: string, system: string, limits: {
+    contextWindow: number;
+    answerTokens: number;
+}): WebFetchPage;
+/**
+ * Answers `prompt` from `page` with one call on the `web_fetch` purpose (see the module comment).
+ * Returns the answer text; throws a {@link ToolError} on a denial or a failure.
+ */
+export declare function extractAnswer(deps: WebFetchExtractDeps, ctx: BuiltinCallContext, page: WebFetchPage, prompt: string): Promise<string>;