@capybara-hq/kernel 0.1.0-rc.0 → 0.1.0-rc.10

package/dist/tools/builtins/send-message.js

@@ -0,0 +1,100 @@
+import { z } from "zod";
+export { SEND_MESSAGE } from "../builtin-names.js";
+/**
+ * The `SendMessage` builtin tool (agent map spec §4.2, §5.1, §5.2): moves text between the agents
+ * of one tree. An agent sends to one of its own sub-agents by agentId (a running one reads it at its
+ * next step, an idle one starts again with its earlier context), and a sub-agent to `"parent"`.
+ * The result says the message was delivered, never the target's reply. The tool pipeline handles
+ * the call itself (`SubagentMessages`), so {@link sendMessageTool}'s `run` is only a guard.
+ */
+/** The input of a `SendMessage` call. */
+export const SendMessageInput = z
+    .object({
+    to: z.string().min(1).max(64),
+    message: z.string().min(1).max(100_000),
+})
+    .strict();
+/** The target a sub-agent uses for the agent that dispatched it. */
+export const PARENT_TARGET = "parent";
+const SPEC = {
+    name: "SendMessage",
+    description: "Send a message to another agent of this conversation. To reach one of your sub-agents, pass " +
+        "its agentId (from the Agent result) as to: a sub-agent that is working reads the message at " +
+        "its next step, and one that already finished starts working again with its earlier context. " +
+        'A sub-agent can pass "parent" as to, to send a note to the agent that dispatched it. This ' +
+        "tool only delivers the message and returns at once; it never waits for a reply. Replies, " +
+        "reports and finishes arrive later in this conversation as notifications. A sub-agent hands " +
+        "back its final report with SubagentHandback, not with this tool.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            to: {
+                type: "string",
+                minLength: 1,
+                maxLength: 64,
+                description: 'The agentId of one of your sub-agents, or "parent" in a sub-agent.',
+            },
+            message: {
+                type: "string",
+                minLength: 1,
+                maxLength: 100000,
+                description: "The message. The receiving agent sees only this text, so include everything it needs.",
+            },
+        },
+        required: ["to", "message"],
+        additionalProperties: false,
+    },
+    // display only (UI refresh B): who the message goes to; never sent to the model
+    keyArgs: ["to"],
+};
+/** `12345` → `12,345` (no locale data involved, so the text is the same on every replica). */
+const count = (n) => String(Math.round(n)).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+/** How a target is listed in a refusal. */
+const targetLine = (t) => `${t.id} (${JSON.stringify(t.description)})`;
+/** Refusals: `isError` results written without delivering anything (model-visible). */
+export const SEND_MESSAGE_REFUSALS = {
+    /**
+     * `to` is none of the caller's own sub-agents (nor `"parent"` in a sub-agent): lists the valid
+     * targets, at most the newest {@link SEND_TARGETS_LISTED} sub-agents.
+     */
+    unknownTarget: (to, targets, opts) => {
+        const lines = [
+            ...targets.map(targetLine),
+            ...(opts.hasParent ? [`"${PARENT_TARGET}" (the agent that dispatched you)`] : []),
+        ];
+        if (lines.length === 0) {
+            return `There is no agent "${to}" to send to: you have no sub-agents yet. Use Agent to dispatch one.`;
+        }
+        const more = opts.more > 0 ? `, and ${opts.more} older sub-agents` : "";
+        return `There is no agent "${to}" you can send to. Pass one of these as to: ${lines.join(", ")}${more}.`;
+    },
+    /** The sub-agent's type or org agent is no longer available to the caller (its gates). */
+    notAvailable: (id, type) => `Sub-agent ${id} can no longer receive messages: its agent type "${type}" is not available to you any more. Use Agent to dispatch another sub-agent instead.`,
+    /** The limits of a send that would start an idle sub-agent again (agent map spec §6). */
+    tooManyConcurrent: (n) => `At most ${n} of your sub-agents can run at once in this conversation, and this one has finished; send the message again after one of the running sub-agents finishes.`,
+    tooManyDispatches: (n) => `${n} sub-agents have been dispatched or restarted since the user's latest message, counted across all levels of sub-agents; that is the limit, so this finished sub-agent cannot start again. Do the remaining work yourself.`,
+    budget: (n) => `Sub-agents have used their token budget since the user's latest message (${count(n)} tokens, counted across all levels of sub-agents), so this finished sub-agent cannot start again. Do the remaining work yourself.`,
+    depthLimit: (maxDepth) => `Sub-agents can be nested at most ${maxDepth} levels deep and you are at the deepest level, so this finished sub-agent cannot start again. Do the remaining work yourself.`,
+    notAvailableHere: "Messages between agents are not available in this conversation.",
+};
+/** How many of the caller's sub-agents an unknown-target refusal lists (the newest). */
+export const SEND_TARGETS_LISTED = 20;
+/** The result of a message to a sub-agent whose run was active (agent map spec §5.1). */
+export const sentToRunningText = (t) => `Message delivered to sub-agent ${targetLine(t)}, which is working; it reads the message at its next step. Its reply or report arrives later as a notification; keep working or end your turn.`;
+/** The result of a message that started an idle sub-agent again (agent map spec §5.1, §6). */
+export const sentToIdleText = (t) => `Message delivered to sub-agent ${targetLine(t)}, which had finished; it is working again with its earlier context. Its reply or report arrives later as a notification; keep working or end your turn.`;
+/** The result of a sub-agent's note to its parent (agent map spec §5.2). */
+export const SENT_TO_PARENT_TEXT = "Message delivered to the agent that dispatched you. Keep working; its reply, if any, arrives as a message in this conversation.";
+/**
+ * The builtin. `defaultPolicy: "allow"` (agent map spec §4.2): it only moves text inside one tree
+ * the person already started. The tool pipeline handles `SendMessage` calls itself; `run` answers
+ * only when a call reaches it anyway.
+ */
+export const sendMessageTool = {
+    spec: SPEC,
+    defaultPolicy: "allow",
+    run: async () => ({
+        content: [{ type: "text", text: SEND_MESSAGE_REFUSALS.notAvailableHere }],
+        isError: true,
+    }),
+};

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

@@ -1,34 +1,40 @@
 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 { KernelSchemaDb, 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 写，命令用户只读）；没有沙箱提供方时只给正文，并说明脚本不可用。
+ * 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
+ * environment 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 declare const SKILLS_MARKER_DIR = "/skills/.capybara";
-/** 一个技能的标记文件。 */
-export declare const skillMarkerPath: (name: string) => string;
+export declare const skillsMarkerDir: (skillsRoot?: string) => string;
+/** {@link skillsMarkerDir} of an instance with the default roots. */
+export declare const SKILLS_MARKER_DIR: string;
+/** The marker file of one skill version. */
+export declare const skillMarkerPath: (name: string, digest: string, skillsRoot?: string) => string;
 /** 依赖：沙箱工具的依赖，加上读技能行用的库与读快照用的日志。 */
 export interface SkillLoadDeps extends SandboxToolDeps {
-    db: KernelDb;
-    eventLog: Pick<EventLog, "append" | "latestOfType">;
+    db: KernelSchemaDb;
+    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 {
@@ -44,10 +50,15 @@ export declare function readSkillFile(store: ObjectStore, key: string, file: Ski
  * 批准时草稿前缀原样成为版本前缀，版本号变了也能找到），再找本对话发起、仍待批准、前缀相同的技能改动（试用草稿：
  * 没有 `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 declare function findSkillVersion(db: KernelDb, ctx: Pick<BuiltinCallContext, "orgId" | "conversationId">, entry: Pick<CatalogSkill, "id" | "source">): Promise<{
+export declare function findSkillVersion(db: KernelSchemaDb, ctx: Pick<BuiltinCallContext, "orgId" | "conversationId">, entry: Pick<CatalogSkill, "id" | "source">): Promise<{
     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, 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
+ * environment 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 environment; 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")
@@ -219,6 +227,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 +364,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,15 +377,15 @@ 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,
         defaultPolicy: "allow",
         // 可能要创建 / 恢复沙箱并复制文件：与沙箱工具同一时限
-        timeoutMs: () => sandboxBaseTimeoutMs(deps.config()),
+        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 +410,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 +438,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 +461,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/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;