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

package/dist/tools/builtins/sandbox/task-stop.js

@@ -0,0 +1,113 @@
+import { rootsOf, ToolError } from "@capybara-hq/plugin-sdk";
+import { decodeTail, tailCommand } from "../../../background/session.js";
+import { clip, display, mapSandboxError, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, } from "./common.js";
+import { onTaskInstance, ownedTask, recheckDevice, statusLine, taskEnv, } from "./task-output.js";
+/** The time limit of reading a stopped task's last lines. */
+const TAIL_EXEC_TIMEOUT_MS = 10_000;
+const SPEC = {
+    name: "TaskStop",
+    // Display only (the tool row; not in the fingerprint, never sent to the model).
+    keyArgs: ["task_id"],
+    description: "Stop a background task started with Bash and run_in_background: every process of the task " +
+        "gets SIGTERM, then SIGKILL after 5 seconds. The result has the final status and the last " +
+        "lines of output. Stopping a task that has already finished is not an error; the result says " +
+        "so. A conversation can stop only its own tasks.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            task_id: {
+                type: "string",
+                minLength: 1,
+                description: "The id of the background task (bt_...) that Bash returned.",
+            },
+        },
+        required: ["task_id"],
+        additionalProperties: false,
+    },
+};
+/** The task's last 20 lines, read from its own sandbox instance; null when that is not running. */
+async function lastLinesOf(env, task, signal) {
+    if (task.sandboxCreatedAt === null)
+        return null;
+    try {
+        const r = await onTaskInstance(env, task, async (p, h, sig) => {
+            const res = await p.exec(h, {
+                command: tailCommand(task.id),
+                cwd: rootsOf(h).workspace,
+                timeoutMs: TAIL_EXEC_TIMEOUT_MS,
+                maxOutputBytes: 64 * 1024,
+                signal: sig,
+            });
+            return res.exitCode === 0 ? decodeTail(res.stdout) : null;
+        }, signal);
+        return r.kind === "ran" ? r.value : null;
+    }
+    catch {
+        // the task is stopped either way; only its last lines are missing
+        return null;
+    }
+}
+/** The result text: what happened, the status line and the last lines. */
+async function ended(env, task, what, signal) {
+    const lines = await lastLinesOf(env, task, signal);
+    const tail = task.sandboxCreatedAt === null
+        ? "[No output: the command never started.]"
+        : lines === null
+            ? "[Last lines unavailable: the sandbox that ran this task is not running.]"
+            : lines === ""
+                ? "[No output.]"
+                : `Last lines:\n${lines.replace(/\n$/, "")}`;
+    return text(task, `Background task ${task.id} ("${task.description}") ${what}.\n${statusLine(task)}\n${tail}`);
+}
+function text(task, body) {
+    const d = clip(task.description, 120);
+    return {
+        content: [{ type: "text", text: body }],
+        isError: false,
+        display: display(`停止后台任务：${d}`, `Stop background task: ${d}`),
+    };
+}
+/**
+ * Built-in `TaskStop` (spec 2026-11-05-background-bash-design §2.3): stops one of this
+ * conversation's background tasks through `BackgroundTaskStopper` (SIGTERM to its session, SIGKILL
+ * after 5 s, never creating or resuming a sandbox). A task that had already finished is not an
+ * error; a reservation still launching, or a task another stop already claimed, is reported as
+ * stopping. A stop that failed leaves the task running and is an error the model can retry.
+ */
+export function taskStopTool(deps) {
+    return {
+        spec: SPEC,
+        defaultPolicy: "allow",
+        unavailable: unavailableWhenNoSandbox(deps),
+        timeoutMs: () => sandboxBaseTimeoutMs(deps.config.get()),
+        async run(input, ctx) {
+            const { task_id } = input;
+            const env = await taskEnv(deps, ctx);
+            const task = await ownedTask(env, ctx, task_id);
+            await recheckDevice(env, ctx);
+            if (task.status !== "running") {
+                return ended(env, task, "had already finished", ctx.signal);
+            }
+            let after;
+            try {
+                after = await env.tasks.stopper.stop(task, "tool", ctx.signal);
+            }
+            catch (e) {
+                const mapped = mapSandboxError(e, env.log);
+                if (mapped instanceof ToolError)
+                    throw mapped;
+                const why = e instanceof Error ? e.message : String(e);
+                throw new ToolError(`Background task ${task.id} could not be stopped (${clip(why, 300)}); it keeps running. Retry TaskStop, or check the sandbox with Bash.`);
+            }
+            if (after.status === "running") {
+                return text(after, `Background task ${after.id} ("${after.description}") is stopping: it is still starting, or another stop is in progress. Call TaskOutput to see when it has ended.`);
+            }
+            const what = after.status === "stopped"
+                ? "was stopped"
+                : after.status === "lost"
+                    ? "is lost"
+                    : "had already finished";
+            return ended(env, after, what, ctx.signal);
+        },
+    };
+}

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 { checkPathShape, 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.",
+        "source files and data files. The path is absolute, under the workspace directory or the " +
+        "temporary files directory (the skills directory is 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".',
+                description: "Absolute path of the file, e.g. report.md in the workspace directory.",
             },
             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,49 +43,52 @@ export function sandboxWriteTool(deps) {
         unavailable: unavailableWhenNoSandbox(deps),
         timeoutMs: () => sandboxBaseTimeoutMs(deps.config.get()),
         async run(input, ctx) {
-            const path = checkWritable(input.path);
             const data = new TextEncoder().encode(input.content);
-            const { value, notices } = await inSandbox(deps, ctx, ({ h, p, signal }) => 
-            // stat, read the previous content, write: one holder at a time per file
-            withPathLease(deps, ctx, path, signal, async (signal) => {
-                const st = await p.stat(h, path, signal);
-                if (st?.isDir)
-                    throw new ToolError(isDirectory(path));
-                // the previous content, for the diff on the row (display only: a failure here never
-                // fails the write, the result just carries no view)
-                let previous = "";
-                if (st !== null) {
-                    try {
-                        const got = st.size <= PREVIOUS_MAX_BYTES
-                            ? await p.readFile(h, path, { maxBytes: PREVIOUS_MAX_BYTES, signal })
-                            : null;
+            checkPathShape(input.file_path, "file_path");
+            let path = "";
+            const { value, notices } = await inSandbox(deps, ctx, ({ deviceId, h, roots, p, signal }) => {
+                path = checkWritable(input.file_path, roots);
+                // stat, read the previous content, write: one holder at a time per file
+                return withPathLease(deps, { deviceId }, path, signal, async (signal) => {
+                    const st = await p.stat(h, path, signal);
+                    if (st?.isDir)
+                        throw new ToolError(isDirectory(path));
+                    // the previous content: for the 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) {
+                        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 =
-                            got === null || got.truncated || looksBinary(got.data) || got.data.includes(0)
+                            st.size > PREVIOUS_MAX_BYTES ||
+                                got.truncated ||
+                                looksBinary(got.data) ||
+                                got.data.includes(0)
                                 ? null
                                 : new TextDecoder().decode(got.data);
                     }
-                    catch (e) {
-                        if (signal.aborted || isSandboxGoneError(e))
-                            throw e;
-                        previous = null;
-                    }
-                }
-                await p.writeFile(h, path, data, signal);
-                return { existed: st !== null, previous };
-            }));
+                    await p.writeFile(h, path, data, signal);
+                    return { existed: st !== null, previous };
+                });
+            });
             const { existed, previous } = value;
             const text = `${existed ? "Overwrote" : "Created"} ${path} (${data.byteLength} bytes).`;
             return {
                 content: [{ type: "text", text: withNotices(notices, text) }],
                 display: display(`写入 ${clip(path, 180)}`, `Wrote ${clip(path, 180)}`),
-                ...(previous !== null && {
-                    view: {
-                        kind: "edit",
-                        path: viewPath(path),
-                        created: !existed,
-                        ...lineDiff(previous, input.content),
-                    },
-                }),
+                // 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/send-message.d.ts

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import type { BuiltinTool } from "../registry.js";
+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 declare const SendMessageInput: z.ZodObject<{
+    to: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strict>;
+export type SendMessageInputT = z.infer<typeof SendMessageInput>;
+/** The target a sub-agent uses for the agent that dispatched it. */
+export declare const PARENT_TARGET = "parent";
+/** One valid target of a caller: a sub-agent of its own, by agentId and task label. */
+export interface SendTarget {
+    id: string;
+    description: string;
+}
+/** Refusals: `isError` results written without delivering anything (model-visible). */
+export declare 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.
+     */
+    readonly unknownTarget: (to: string, targets: readonly SendTarget[], opts: {
+        hasParent: boolean;
+        more: number;
+    }) => string;
+    /** The sub-agent's type or org agent is no longer available to the caller (its gates). */
+    readonly notAvailable: (id: string, type: string) => string;
+    /** The limits of a send that would start an idle sub-agent again (agent map spec §6). */
+    readonly tooManyConcurrent: (n: number) => string;
+    readonly tooManyDispatches: (n: number) => string;
+    readonly budget: (n: number) => string;
+    readonly depthLimit: (maxDepth: number) => string;
+    readonly 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 declare const SEND_TARGETS_LISTED = 20;
+/** The result of a message to a sub-agent whose run was active (agent map spec §5.1). */
+export declare const sentToRunningText: (t: SendTarget) => string;
+/** The result of a message that started an idle sub-agent again (agent map spec §5.1, §6). */
+export declare const sentToIdleText: (t: SendTarget) => string;
+/** The result of a sub-agent's note to its parent (agent map spec §5.2). */
+export declare 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 declare const sendMessageTool: BuiltinTool;

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

@@ -5,30 +5,36 @@ 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
+ * 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 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: 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 {
@@ -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: 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;