@capybara-hq/plugin-sdk 0.1.0-rc.1 → 0.1.0-rc.3

package/dist/sandbox.d.ts

@@ -1,30 +1,44 @@
 /**
- * Sandbox contract `sandbox@1`: a single-select, brokered extension point (extensions may not
+ * Sandbox contract `sandbox@2`: a single-select, brokered extension point (extensions may not
  * `requires` it; the kernel's `SandboxService` consumes it). The provider implements only the
  * primitives below; the kernel builds `glob` / `grep` / `edit` from `exec` plus `readFile` /
  * `writeFile`.
+ *
+ * `@2` separates an environment's **file system** from its **instance**: the file system
+ * (`createFileSystem`) lives until the environment is deleted (`destroyFileSystem`); instances
+ * (`create`) attach to it and come and go (`destroy` drops the instance and keeps the files).
  */
 /** Sandbox extension point ref. */
-export declare const SANDBOX_EXTENSION_POINT = "sandbox@1";
-/** 沙箱内允许模型访问的根目录。 */
+export declare const SANDBOX_EXTENSION_POINT = "sandbox@2";
+/** The roots inside the sandbox the model may access. */
 export declare const SANDBOX_ROOTS: readonly ["/workspace", "/skills", "/tmp"];
-/** 沙箱资源与出站限制。 */
+/** Sandbox resource and egress limits. */
 export interface SandboxLimits {
     cpu: number;
     memoryMb: number;
     diskMb: number;
     egress: "none" | "allowlist" | "open";
-    /** 出站白名单（`egress` 为 `allowlist` 时生效）；每项须通过 {@link validateAllowHost}。 */
+    /** Egress allowlist (used when `egress` is `allowlist`); each entry passes {@link validateAllowHost}. */
     allowHosts: string[];
 }
-/** 提供方的实例句柄。 */
+/** The provider's instance handle. */
 export interface SandboxHandle {
-    /** 提供方的实例 id。 */
+    /** The provider's instance id. */
+    id: string;
+}
+/** The provider's file system handle (an environment's files, independent of any instance). */
+export interface FileSystemHandle {
+    /** The provider's file system id. */
     id: string;
 }
-/** 命令执行结果。 */
+/** Who runs an `exec` (informational in phase 1: audit and attribution). */
+export interface SandboxActor {
+    accountId: string;
+    conversationId: string;
+}
+/** Result of a command. */
 export interface ExecResult {
-    /** 超时或在执行中被中止为 null（此时 `timedOut` 分别为 true / false）。 */
+    /** null on timeout or when aborted while running (`timedOut` is then true / false). */
     exitCode: number | null;
     stdout: string;
     stderr: string;
@@ -32,8 +46,10 @@ export interface ExecResult {
     timedOut: boolean;
 }
 /**
- * 实例在提供方那边确定已经不在了（容器被删、E2B 沙箱过期）。`exec` / `readFile` / `writeFile` / `stat`
- * 发现实例不在时必须抛它（而不是普通 Error），内核据此重建沙箱并重试一次；只是暂时连不上时抛普通错误。
+ * The instance is definitely gone on the provider's side (container removed, E2B sandbox expired).
+ * `exec` / `readFile` / `writeFile` / `stat` must throw it (not a plain Error) when they find the
+ * instance gone; the kernel then rebuilds the instance and retries once. A transient connection
+ * failure throws a plain error.
  */
 export declare class SandboxGoneError extends Error {
     readonly sandboxGone: true;
@@ -41,8 +57,21 @@ export declare class SandboxGoneError extends Error {
         cause?: unknown;
     });
 }
-/** 鸭子类型判断（不用 instanceof），兼容插件自带另一份 plugin-sdk 副本的情况。 */
+/** Duck-typed check (not instanceof), so a plugin bundling another plugin-sdk copy still matches. */
 export declare function isSandboxGoneError(e: unknown): e is SandboxGoneError;
+/**
+ * The file system is definitely gone on the provider's side (volume removed, E2B sandbox killed).
+ * `create` throws it instead of attaching the instance to a new, empty file system; the kernel then
+ * reports the environment's files as lost rather than handing out a silently empty workspace.
+ */
+export declare class FileSystemGoneError extends Error {
+    readonly fileSystemGone: true;
+    constructor(message: string, opts?: {
+        cause?: unknown;
+    });
+}
+/** Duck-typed check (not instanceof), so a plugin bundling another plugin-sdk copy still matches. */
+export declare function isFileSystemGoneError(e: unknown): e is FileSystemGoneError;
 /**
  * A holder tag (`exec` argument `tag`, {@link SandboxProvider.killTagged}): the kernel passes its
  * lease tokens (UUIDs). Providers check tags against it before putting them in a command line or a
@@ -50,73 +79,119 @@ export declare function isSandboxGoneError(e: unknown): e is SandboxGoneError;
  */
 export declare const SANDBOX_TAG_RE: RegExp;
 /**
- * `sandbox@1` 的实现（由沙箱插件提供，如 Docker、E2B）。
- * 实例确定不在时：`resume` 返回 `gone`；`exec` / `readFile` / `writeFile` / `stat` 抛 {@link SandboxGoneError}；
- * `suspend` / `destroy` 照常成功。
+ * The `sandbox@2` implementation (provided by a sandbox plugin such as Docker or E2B).
+ *
+ * **File systems and instances.** `createFileSystem` makes an environment's files; they live until
+ * `destroyFileSystem` (the environment is deleted). `create` makes an instance attached to an
+ * existing file system; `destroy` / `destroyByName` drop the instance only and keep the files, and
+ * `suspend` keeps them too. When the file system is gone, `create` must throw
+ * {@link FileSystemGoneError} and never create an empty one in its place (a Docker provider checks
+ * its volumes exist before mounting them, because Docker would otherwise create empty volumes).
+ *
+ * **Gone instances.** When the instance is definitely gone: `resume` returns `gone`; `exec` /
+ * `readFile` / `writeFile` / `stat` / `killAll` / `killTagged` throw {@link SandboxGoneError};
+ * `suspend` / `destroy` succeed as usual.
  *
- * **自动启动**：实例还在、但已停止 / 暂停（被内核之外的原因停掉：宿主机重启、守护进程重启、沙箱里的进程把
- * 自己的 init 弄停了、休眠扫描停了实例却没来得及记下 `suspended`……）时，`exec` / `readFile` / `writeFile` /
- * `stat` 必须先透明地把它启动起来（同 `resume`，文件保留）再执行，而不是报错——内核只信自己记的 `running`。
+ * **Auto-start**: when the instance still exists but is stopped or paused (for a reason outside the
+ * kernel: host or daemon restart, a process in the sandbox stopping its init, an idle sweep that
+ * stopped the instance before recording `suspended`...), `exec` / `readFile` / `writeFile` /
+ * `stat` / `killAll` / `killTagged` must start it transparently first (like `resume`, files kept)
+ * and then run, never fail: the kernel trusts only the `running` it recorded itself. Auto-start
+ * must be idempotent under concurrent calls: two calls that both find the instance stopped both
+ * start it without failing.
  *
- * **命令时限在沙箱里也要生效**：`exec` 除了在提供方这边按 `timeoutMs` 停掉命令，还必须让沙箱里的命令自己在
- * `timeoutMs` 之后不久（几秒的余量）被杀掉。内核副本崩溃时提供方这边的计时随之消失，断开连接也不会结束命令；
- * 沙箱里的时限保证它不会无限期地与下一个持锁方的命令同时运行。
+ * **Time limits apply inside the sandbox too**: besides stopping a command after `timeoutMs` on the
+ * provider's side, `exec` must make the command in the sandbox kill itself shortly (a few seconds)
+ * after `timeoutMs`. When a kernel replica crashes, the provider-side timer goes with it, and a
+ * dropped connection does not end the command; the in-sandbox limit keeps it from running
+ * indefinitely next to the next holder's commands.
  *
- * **中止**：每个方法都必须及时响应 `signal`（已中止就立即失败，进行中被中止就尽快以中止原因结束）——内核在锁丢失、
- * 运行被中止或超时时靠它停下，不响应就可能与新的持锁方同时操作同一实例。`exec` 被中止时必须杀掉正在跑的命令
- * （连同它派生的进程），而不只是不再等待它的输出；命令启动后才被中止的 `exec` 以 `exitCode: null`、
- * `timedOut: false` 正常 resolve（带上已收集的输出），不 reject。调用时 signal 已中止则立即 reject。
+ * **Abort**: every method must respond to `signal` promptly (fail at once when already aborted, end
+ * with the abort reason as soon as possible when aborted mid-way): the kernel relies on it to stop
+ * on lock loss, run abort or timeout, and ignoring it may let two holders operate on one instance.
+ * An aborted `exec` must kill its running command (and the processes it spawned), not just stop
+ * waiting for its output; an `exec` aborted after its command started resolves normally with
+ * `exitCode: null`, `timedOut: false` (and the output collected so far), it does not reject. An
+ * `exec` called with an already aborted signal rejects at once.
  *
- * **Concurrent use (optional)**: a provider that declares {@link SandboxProvider.concurrentExec}
- * lets the kernel call `exec`, `readFile`, `writeFile` and `stat` concurrently on one instance
- * (commands of parallel sub-agents sharing their parent conversation's sandbox). Then those four
- * methods must be safe to call concurrently, and **auto-start must be idempotent under concurrent
- * calls**: two calls that both find the instance stopped both start it without failing. Each
- * `exec` labels its command with its `tag`, and an aborted `exec` kills only its own command.
- * `concurrentExec` requires {@link SandboxProvider.killTagged}; a provider that declares one
- * without the other, or neither, is used one call at a time (the behavior without them).
+ * **Concurrent use** (required in `@2`): the sessions of one environment share its instance, so the
+ * kernel calls `exec`, `readFile`, `writeFile` and `stat` concurrently on one instance. Those four
+ * methods must be safe to call concurrently. Each `exec` labels its command with its `tag`, and an
+ * aborted `exec` kills only its own command.
  */
 export interface SandboxProvider {
+    /** `exec` / `readFile` / `writeFile` / `stat` may run concurrently on one instance (required). */
+    readonly concurrentExec: true;
     /**
-     * Declares that `exec` / `readFile` / `writeFile` / `stat` may run concurrently on one instance
-     * (see the contract above). Requires {@link SandboxProvider.killTagged}.
+     * Whether the provider isolates the sessions of one environment from each other inside the
+     * instance (a declared capability; absent means false).
+     */
+    readonly sessionIsolation?: boolean;
+    /**
+     * Creates an environment's file system. `name` looks like `cap-env-<environmentId>`. If a file
+     * system with this name already exists, return it.
+     */
+    createFileSystem(args: {
+        name: string;
+        limits: SandboxLimits;
+        signal: AbortSignal;
+    }): Promise<FileSystemHandle>;
+    /** Deletes the file system and its files. Succeeds when it does not exist. */
+    destroyFileSystem(fs: FileSystemHandle, signal: AbortSignal): Promise<void>;
+    /**
+     * Deletes the file system made under `name` by `createFileSystem`; succeeds when there is none.
+     * The kernel uses it when it has no handle (`createFileSystem` finished on the provider's side
+     * but the kernel stopped before recording the handle), and in its one-off cleanup of
+     * per-conversation sandboxes with `cap-<conversationId>` names that a `sandbox@1` provider's
+     * `create` made together with their files (Docker: the `cap-<conversationId>-workspace` and
+     * `-skills` volumes); a provider removes those under the same call.
+     */
+    destroyFileSystemByName(name: string, signal: AbortSignal): Promise<void>;
+    /**
+     * Creates an instance attached to `fileSystem`. Without `image` the provider uses its own
+     * published image. Throws {@link FileSystemGoneError} when the file system is gone.
      */
-    readonly concurrentExec?: boolean;
-    /** `name` 形如 `cap-<conversationId>`。 */
     create(args: {
         name: string;
-        image: string;
+        image?: string;
         limits: SandboxLimits;
+        fileSystem: FileSystemHandle;
         signal: AbortSignal;
     }): Promise<SandboxHandle>;
-    /** `gone` 表示提供方那边已经没有这个实例。 */
+    /** `gone` means the provider no longer has this instance. */
     resume(h: SandboxHandle, signal: AbortSignal): Promise<"resumed" | "gone">;
-    /** 文件必须保留。实例不存在也算成功。 */
+    /** Files must be kept. Succeeds when the instance does not exist. */
     suspend(h: SandboxHandle, signal: AbortSignal): Promise<void>;
-    /** 不存在也算成功。 */
+    /** Drops the instance only; the file system and its files are kept. Succeeds when it does not exist. */
     destroy(h: SandboxHandle, signal: AbortSignal): Promise<void>;
     /**
-     * 可选：按 `create` 时的 `name`（`cap-<conversationId>`）销毁实例，不存在也算成功。
-     * 内核在拿不到句柄时用它清理（例如 `create` 已在提供方那边完成、内核却在记下句柄前退出）。
+     * Drops the instance made under `name` by `create` (instance only, files kept); succeeds when
+     * there is none. The kernel uses it when it has no handle (`create` finished on the provider's
+     * side but the kernel stopped before recording the handle), and in its one-off cleanup of
+     * per-conversation sandboxes with `cap-<conversationId>` names made by a `sandbox@1` provider's
+     * `create`.
      */
-    destroyByName?(name: string, signal: AbortSignal): Promise<void>;
+    destroyByName(name: string, signal: AbortSignal): Promise<void>;
     /**
-     * 可选：杀掉这个实例里经 `exec` 启动、仍在运行的全部命令（连同它们派生的、没有自己另起会话的进程）。
-     * 内核在接手一个前任持锁方没有正常结束的沙箱（前任崩溃）时、第一次执行前调用，清掉前任遗留的命令；
-     * 命令自己放到后台、另起会话的进程不保证被杀。实例已停止时同样先启动；不在时抛 {@link SandboxGoneError}。
+     * Kills every running command started through `exec` in this instance (and the processes they
+     * spawned that did not start their own session). The kernel calls it only when no other holder
+     * can be running commands (an instance just resumed from `suspended`, or under the exclusive
+     * lease), never while another session may be; to clean up after one crashed holder it uses
+     * {@link SandboxProvider.killTagged}. Processes a command put in the background in their own
+     * session are not guaranteed to be killed.
      */
-    killAll?(h: SandboxHandle, signal: AbortSignal): Promise<void>;
+    killAll(h: SandboxHandle, signal: AbortSignal): Promise<void>;
     /**
-     * Optional: kill every running `exec` command labelled with one of `tags` (and its process
-     * tree), leaving other commands running. The kernel calls it for the tags of holders that
-     * crashed while live holders keep running commands. Tags match {@link SANDBOX_TAG_RE}. Match
-     * whole tags: one tag may be a prefix of another (`ab` of `ab-cd`), and killing `ab` must not
-     * touch `ab-cd`'s commands. Starts a stopped instance first; throws {@link SandboxGoneError}
-     * when the instance is gone.
+     * Kills every running `exec` command labelled with one of `tags` (and its process tree), leaving
+     * other commands running. The kernel calls it for the tags of holders that crashed while live
+     * holders keep running commands. Tags match {@link SANDBOX_TAG_RE}. Match whole tags: one tag
+     * may be a prefix of another (`ab` of `ab-cd`), and killing `ab` must not touch `ab-cd`'s
+     * commands.
      */
-    killTagged?(h: SandboxHandle, tags: string[], signal: AbortSignal): Promise<void>;
+    killTagged(h: SandboxHandle, tags: string[], signal: AbortSignal): Promise<void>;
     /**
-     * 执行一条命令。`maxOutputBytes` 是 stdout 与 stderr **合计**最多收集的字节，超出的丢弃、`truncated` 为 true。
+     * Runs a command. `maxOutputBytes` caps stdout and stderr **combined**; the rest is dropped and
+     * `truncated` is true.
      */
     exec(h: SandboxHandle, args: {
         command: string;
@@ -127,11 +202,16 @@ export interface SandboxProvider {
         signal: AbortSignal;
         /**
          * The holder's tag ({@link SANDBOX_TAG_RE}); label the command with it so
-         * {@link SandboxProvider.killTagged} can find it. Absent from kernels before phase C.
+         * {@link SandboxProvider.killTagged} can find it.
          */
-        tag?: string;
+        tag: string;
+        /** Who runs the command; informational in phase 1 (record it, do not act on it). */
+        actor: SandboxActor;
     }): Promise<ExecResult>;
-    /** 读文件（最多 `maxBytes` 字节，更长的截断、`truncated` 为 true）。不存在、或是目录时返回 null。 */
+    /**
+     * Reads a file (at most `maxBytes`; longer files are truncated and `truncated` is true). Returns
+     * null when it does not exist or is a directory.
+     */
     readFile(h: SandboxHandle, path: string, opts: {
         maxBytes: number;
         signal: AbortSignal;
@@ -139,7 +219,7 @@ export interface SandboxProvider {
         data: Uint8Array;
         truncated: boolean;
     } | null>;
-    /** 父目录自动创建。 */
+    /** Parent directories are created. */
     writeFile(h: SandboxHandle, path: string, data: Uint8Array, signal: AbortSignal): Promise<void>;
     stat(h: SandboxHandle, path: string, signal: AbortSignal): Promise<{
         size: number;

package/dist/sandbox.js

@@ -1,17 +1,23 @@
 /**
- * Sandbox contract `sandbox@1`: a single-select, brokered extension point (extensions may not
+ * Sandbox contract `sandbox@2`: a single-select, brokered extension point (extensions may not
  * `requires` it; the kernel's `SandboxService` consumes it). The provider implements only the
  * primitives below; the kernel builds `glob` / `grep` / `edit` from `exec` plus `readFile` /
  * `writeFile`.
+ *
+ * `@2` separates an environment's **file system** from its **instance**: the file system
+ * (`createFileSystem`) lives until the environment is deleted (`destroyFileSystem`); instances
+ * (`create`) attach to it and come and go (`destroy` drops the instance and keeps the files).
  */
 /** Sandbox extension point ref. */
-export const SANDBOX_EXTENSION_POINT = "sandbox@1";
-/** 沙箱内允许模型访问的根目录。 */
+export const SANDBOX_EXTENSION_POINT = "sandbox@2";
+/** The roots inside the sandbox the model may access. */
 export const SANDBOX_ROOTS = ["/workspace", "/skills", "/tmp"];
 const MAX_PATH_LENGTH = 4096;
 /**
- * 实例在提供方那边确定已经不在了（容器被删、E2B 沙箱过期）。`exec` / `readFile` / `writeFile` / `stat`
- * 发现实例不在时必须抛它（而不是普通 Error），内核据此重建沙箱并重试一次；只是暂时连不上时抛普通错误。
+ * The instance is definitely gone on the provider's side (container removed, E2B sandbox expired).
+ * `exec` / `readFile` / `writeFile` / `stat` must throw it (not a plain Error) when they find the
+ * instance gone; the kernel then rebuilds the instance and retries once. A transient connection
+ * failure throws a plain error.
  */
 export class SandboxGoneError extends Error {
     sandboxGone = true;
@@ -20,12 +26,30 @@ export class SandboxGoneError extends Error {
         this.name = "SandboxGoneError";
     }
 }
-/** 鸭子类型判断（不用 instanceof），兼容插件自带另一份 plugin-sdk 副本的情况。 */
+/** Duck-typed check (not instanceof), so a plugin bundling another plugin-sdk copy still matches. */
 export function isSandboxGoneError(e) {
     return (e instanceof Error &&
         e.name === "SandboxGoneError" &&
         e.sandboxGone === true);
 }
+/**
+ * The file system is definitely gone on the provider's side (volume removed, E2B sandbox killed).
+ * `create` throws it instead of attaching the instance to a new, empty file system; the kernel then
+ * reports the environment's files as lost rather than handing out a silently empty workspace.
+ */
+export class FileSystemGoneError extends Error {
+    fileSystemGone = true;
+    constructor(message, opts) {
+        super(message, opts && "cause" in opts ? { cause: opts.cause } : undefined);
+        this.name = "FileSystemGoneError";
+    }
+}
+/** Duck-typed check (not instanceof), so a plugin bundling another plugin-sdk copy still matches. */
+export function isFileSystemGoneError(e) {
+    return (e instanceof Error &&
+        e.name === "FileSystemGoneError" &&
+        e.fileSystemGone === true);
+}
 /**
  * A holder tag (`exec` argument `tag`, {@link SandboxProvider.killTagged}): the kernel passes its
  * lease tokens (UUIDs). Providers check tags against it before putting them in a command line or a

package/dist/secret.d.ts

@@ -1,5 +1,8 @@
 import type { z } from "zod";
-/** 标记一个 schema 为敏感字段（Zod 4 meta `{ secret: true }`）。 */
+/**
+ * Marks a schema as a secret field (Zod 4 meta `{ secret: true }`), merging with existing meta
+ * (`ui` hints, `hot`), so `secret(ui(x, …))` and `ui(secret(x), …)` are the same.
+ */
 export declare function secret<T extends z.ZodTypeAny>(schema: T): T;
 /** 读取 schema 的 meta，判断是否敏感；内核 `meta({secret:true})` 同样可识别。 */
 export declare function isSecret(schema: z.ZodTypeAny): boolean;

package/dist/secret.js

@@ -1,6 +1,9 @@
-/** 标记一个 schema 为敏感字段（Zod 4 meta `{ secret: true }`）。 */
+/**
+ * Marks a schema as a secret field (Zod 4 meta `{ secret: true }`), merging with existing meta
+ * (`ui` hints, `hot`), so `secret(ui(x, …))` and `ui(secret(x), …)` are the same.
+ */
 export function secret(schema) {
-    return schema.meta({ secret: true });
+    return schema.meta({ ...(schema.meta() ?? {}), secret: true });
 }
 /** 读取 schema 的 meta，判断是否敏感；内核 `meta({secret:true})` 同样可识别。 */
 export function isSecret(schema) {

package/dist/skill-invocation.d.ts

@@ -26,13 +26,14 @@ export declare function skillInvocation(frontmatter: Readonly<Record<string, unk
 export declare function parseSkillArguments(args: string): string[];
 /**
  * A skill body with its arguments substituted (see the file header), without the wrapper.
- * `skillName` is the resolved skill's bare name: `${CLAUDE_SKILL_DIR}` becomes
- * `/skills/<skillName>` (a qualified `<plugin>:<name>` throws a `TypeError`). `args` is trimmed;
+ * `skillName` is the resolved skill's bare name and `digest` its version's `skillDigest`:
+ * `${CLAUDE_SKILL_DIR}` becomes `/skills/<skillName>@<digest>` (a qualified `<plugin>:<name>` or a
+ * digest that is not 12 lowercase hex digits throws a `TypeError`). `args` is trimmed;
  * more than {@link SKILL_INVOCATION_LIMITS.argumentsMaxChars} characters throw a `RangeError`, and
  * so does a result longer than {@link SKILL_INVOCATION_LIMITS.renderedMaxChars} (checked while
  * substituting, before the long string is built).
  */
-export declare function renderSkillBody(body: string, invocation: SkillInvocation, args: string, skillName: string): string;
+export declare function renderSkillBody(body: string, invocation: SkillInvocation, args: string, skillName: string, digest: string): string;
 /** Input of {@link renderSkillInvocation}. */
 export interface RenderSkillInvocationInput {
     /**
@@ -41,10 +42,12 @@ export interface RenderSkillInvocationInput {
      */
     name: string;
     /**
-     * The resolved skill's bare name (never `<plugin>:<name>`): its sandbox directory
-     * `/skills/<skillName>/`, used for `${CLAUDE_SKILL_DIR}` and the files line.
+     * The resolved skill's bare name (never `<plugin>:<name>`): with `digest`, its sandbox
+     * directory `/skills/<skillName>@<digest>/`, used for `${CLAUDE_SKILL_DIR}` and the files line.
      */
     skillName: string;
+    /** The version's `skillDigest` (12 lowercase hex digits). */
+    digest: string;
     version: number;
     /** The SKILL.md body (after the frontmatter). */
     body: string;

package/dist/skill-invocation.js

@@ -6,12 +6,12 @@
  * The argument rules follow Claude Code (re-checked 2026-10-27): `$ARGUMENTS` is the whole argument
  * string, `$ARGUMENTS[N]` / `$N` are 0-based positional values (a missing one stays as written),
  * `$name` takes its value from frontmatter `arguments` (a missing one becomes empty), `\$` is a
- * literal `$`, `${CLAUDE_SKILL_DIR}` is `/skills/<name>` and every other `${…}` stays as written.
+ * literal `$`, `${CLAUDE_SKILL_DIR}` is `/skills/<name>@<digest>` and every other `${…}` stays as written.
  * When the body has no argument placeholder and the arguments are not empty, they are appended as
  * `ARGUMENTS: <args>`. Substituted text is never scanned again. Nothing is executed: shell
  * injections (`` !`cmd` ``) stay text, and the model is told how to run them.
  */
-import { isSkillName, SKILL_INVOCATION_LIMITS, SKILLS_SANDBOX_ROOT } from "./skill.js";
+import { isSkillName, SKILL_INVOCATION_LIMITS, SKILLS_SANDBOX_ROOT, skillSandboxDir, } from "./skill.js";
 import { argumentHintText, SKILL_ARGUMENT_NAME_RE } from "./skill-keys.js";
 /**
  * The invocation metadata of a SKILL.md frontmatter. Values of the wrong type are ignored here
@@ -102,17 +102,26 @@ const checkSkillName = (skillName) => {
         throw new TypeError(`skillName must be a bare skill name (its directory under ${SKILLS_SANDBOX_ROOT}), got "${skillName}"`);
     }
 };
+const DIGEST_RE = /^[0-9a-f]{12}$/;
+const checkDigest = (digest) => {
+    if (typeof digest !== "string" || !DIGEST_RE.test(digest)) {
+        throw new TypeError(`digest must be 12 lowercase hex digits (skillDigest), got "${digest}"`);
+    }
+};
 const tooLong = () => new RangeError(`the rendered skill must be at most ${SKILL_INVOCATION_LIMITS.renderedMaxChars} characters`);
 /**
  * A skill body with its arguments substituted (see the file header), without the wrapper.
- * `skillName` is the resolved skill's bare name: `${CLAUDE_SKILL_DIR}` becomes
- * `/skills/<skillName>` (a qualified `<plugin>:<name>` throws a `TypeError`). `args` is trimmed;
+ * `skillName` is the resolved skill's bare name and `digest` its version's `skillDigest`:
+ * `${CLAUDE_SKILL_DIR}` becomes `/skills/<skillName>@<digest>` (a qualified `<plugin>:<name>` or a
+ * digest that is not 12 lowercase hex digits throws a `TypeError`). `args` is trimmed;
  * more than {@link SKILL_INVOCATION_LIMITS.argumentsMaxChars} characters throw a `RangeError`, and
  * so does a result longer than {@link SKILL_INVOCATION_LIMITS.renderedMaxChars} (checked while
  * substituting, before the long string is built).
  */
-export function renderSkillBody(body, invocation, args, skillName) {
+export function renderSkillBody(body, invocation, args, skillName, digest) {
     checkSkillName(skillName);
+    checkDigest(digest);
+    const dir = skillSandboxDir(skillName, digest);
     const all = trimmedArgs(args);
     const values = parseSkillArguments(all);
     const named = invocation.arguments ?? [];
@@ -125,7 +134,7 @@ export function renderSkillBody(body, invocation, args, skillName) {
         if (m === "\\$")
             return "$";
         if (m === "${CLAUDE_SKILL_DIR}")
-            return `${SKILLS_SANDBOX_ROOT}/${skillName}`;
+            return dir;
         if (m === "$ARGUMENTS") {
             placeholder = true;
             return all;
@@ -173,14 +182,14 @@ const escapeAttr = (s) => s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").repla
  */
 export function renderSkillInvocation(i) {
     const args = trimmedArgs(i.args);
-    const body = renderSkillBody(i.body, i.invocation, args, i.skillName).replace(CLOSE_TAG_RE, "<\\/$1");
+    const body = renderSkillBody(i.body, i.invocation, args, i.skillName, i.digest).replace(CLOSE_TAG_RE, "<\\/$1");
     const parts = [];
     if (i.lead !== false) {
         parts.push(escapeTags(`The user invoked the skill "${i.name}" with /${i.name}${args === "" ? "" : ` ${args}`}. Follow its instructions for this request.`));
     }
     parts.push(`<skill_invocation name="${escapeAttr(i.name)}" version="${i.version}">\n${body}\n</skill_invocation>`);
     if (i.lines.files === "load") {
-        parts.push(`Its files are not in the sandbox yet: call Skill with "${i.name}" to copy them to ${SKILLS_SANDBOX_ROOT}/${i.skillName}/ before running its scripts.`);
+        parts.push(`Its files are not in the sandbox yet: call Skill with "${i.name}" to copy them to ${skillSandboxDir(i.skillName, i.digest)}/ before running its scripts.`);
     }
     else if (i.lines.files === "unavailable") {
         parts.push("Its other files are not available in this conversation.");

package/dist/skill.d.ts

@@ -30,12 +30,29 @@ export declare const SKILL_INVOCATION_LIMITS: {
 };
 /** 技能入口文件（包根目录，大小写敏感）。 */
 export declare const SKILL_ENTRY_FILE = "SKILL.md";
-/** 沙箱里放技能的根目录：每个技能在 `/skills/<name>/` 下（只读复制）。 */
+/**
+ * The sandbox root for skills: each skill version is copied (read-only to commands) to
+ * `/skills/<name>@<digest>/` ({@link skillSandboxDir}).
+ */
 export declare const SKILLS_SANDBOX_ROOT = "/skills";
 /** 是否为合法的技能名（见文件头的规范说明）。 */
 export declare function isSkillName(s: unknown): s is string;
-/** 技能文件在沙箱里的路径：`/skills/<name>/<path>`。 */
-export declare function skillSandboxPath(name: string, path: string): string;
+/**
+ * The digest of a skill version's file manifest: the first 12 hex digits of the sha256 of its
+ * files sorted by path (JavaScript string order), one `${path} ${size} ${sha256}\n` line each. Two
+ * versions with the same files get the same digest, so their sandbox directories coincide; any
+ * other change gives a different directory, so two versions of one skill never overwrite each
+ * other in a shared file system.
+ */
+export declare function skillDigest(files: {
+    path: string;
+    size: number;
+    sha256: string;
+}[]): string;
+/** A skill version's directory in the sandbox: `/skills/<name>@<digest>` ({@link skillDigest}). */
+export declare function skillSandboxDir(name: string, digest: string): string;
+/** A skill file's path in the sandbox: `/skills/<name>@<digest>/<path>`. */
+export declare function skillSandboxPath(name: string, digest: string, path: string): string;
 /** {@link parseSkillMd} 成功时的结果。 */
 export interface ParsedSkillMd {
     name: string;

package/dist/skill.js

@@ -16,8 +16,9 @@
  * whose types are checked because the kernel uses them (`skillInvocation`, phase D). Matching the
  * directory name is not enforced: an uploaded zip's outer directory often has another name (GitHub's
  * `repo-main/`); the skill's name is always the frontmatter `name`, and its sandbox directory is
- * `/skills/<name>/`.
+ * `/skills/<name>@<digest>/` ({@link skillSandboxDir}, {@link skillDigest}).
  */
+import { createHash } from "node:crypto";
 import { readFrontmatter } from "./frontmatter.js";
 import { hasControlChars } from "./model.js";
 import { validateSandboxPath } from "./sandbox.js";
@@ -54,7 +55,10 @@ export const SKILL_INVOCATION_LIMITS = {
 };
 /** 技能入口文件（包根目录，大小写敏感）。 */
 export const SKILL_ENTRY_FILE = "SKILL.md";
-/** 沙箱里放技能的根目录：每个技能在 `/skills/<name>/` 下（只读复制）。 */
+/**
+ * The sandbox root for skills: each skill version is copied (read-only to commands) to
+ * `/skills/<name>@<digest>/` ({@link skillSandboxDir}).
+ */
 export const SKILLS_SANDBOX_ROOT = "/skills";
 const NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 const XML_TAG_RE = /<\/?[A-Za-z][^<>]*>/;
@@ -63,9 +67,27 @@ const DRIVE_RE = /^[A-Za-z]:/;
 export function isSkillName(s) {
     return typeof s === "string" && s.length <= SKILL_LIMITS.nameMaxChars && NAME_RE.test(s);
 }
-/** 技能文件在沙箱里的路径：`/skills/<name>/<path>`。 */
-export function skillSandboxPath(name, path) {
-    return `${SKILLS_SANDBOX_ROOT}/${name}/${path}`;
+/**
+ * The digest of a skill version's file manifest: the first 12 hex digits of the sha256 of its
+ * files sorted by path (JavaScript string order), one `${path} ${size} ${sha256}\n` line each. Two
+ * versions with the same files get the same digest, so their sandbox directories coincide; any
+ * other change gives a different directory, so two versions of one skill never overwrite each
+ * other in a shared file system.
+ */
+export function skillDigest(files) {
+    const lines = [...files]
+        .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+        .map((f) => `${f.path} ${f.size} ${f.sha256}\n`)
+        .join("");
+    return createHash("sha256").update(lines).digest("hex").slice(0, 12);
+}
+/** A skill version's directory in the sandbox: `/skills/<name>@<digest>` ({@link skillDigest}). */
+export function skillSandboxDir(name, digest) {
+    return `${SKILLS_SANDBOX_ROOT}/${name}@${digest}`;
+}
+/** A skill file's path in the sandbox: `/skills/<name>@<digest>/<path>`. */
+export function skillSandboxPath(name, digest, path) {
+    return `${skillSandboxDir(name, digest)}/${path}`;
 }
 const chars = (s) => [...s].length;
 /**
@@ -179,7 +201,7 @@ function pathProblem(p) {
             return "path must not contain '.' or '..' segments";
     }
     // 再按沙箱路径规则核一遍（百分号编码的 `..` 等）
-    const errs = validateSandboxPath(skillSandboxPath("skill", p));
+    const errs = validateSandboxPath(skillSandboxPath("skill", "000000000000", p));
     return errs[0] ?? null;
 }
 /**

package/dist/tool.d.ts

@@ -129,6 +129,14 @@ export interface ToolCallContext {
         state: unknown;
         answer: FormAnswer | null;
     };
+    /**
+     * The extension's effective deployment config for this org: the platform's deployment config
+     * with the org's copy applied to the overridable fields (`orgAccess(…, "override")`), or the
+     * platform's config (equal to `ctx.config`) while the org follows it. Use it, not `ctx.config`,
+     * for work done for this org. Optional in the type so older extensions compile; the kernel
+     * always passes it.
+     */
+    config?: unknown;
 }
 export type ToolHandler = (input: unknown, ctx: ToolCallContext) => Promise<ToolResult | InputRequired>;
 /**

package/dist/ui.d.ts

@@ -175,6 +175,14 @@ export interface UiRenderArgs {
         callId: string;
         key?: string;
     };
+    /**
+     * The extension's effective deployment config for this org: the platform's deployment config
+     * with the org's copy applied to the overridable fields (`orgAccess(…, "override")`), or the
+     * platform's config (equal to `ctx.config`) while the org follows it. Use it, not `ctx.config`,
+     * for work done for this org. Optional in the type so older extensions compile; the kernel
+     * always passes it.
+     */
+    config?: unknown;
 }
 /** 视图里的按钮或表单提交：`actionId` 来自块；表单提交时带 `answer`。 */
 export interface UiActionArgs extends UiRenderArgs {