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

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/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 {

package/dist/web.d.ts

@@ -12,10 +12,16 @@ export interface WebSearchResult {
     /** ISO 8601 date or datetime, when known. */
     publishedAt?: string;
 }
-/** A web search provider (`web-search@1`). The kernel passes the org's decrypted `orgConfig`. */
+/**
+ * A web search provider (`web-search@1`). The kernel passes the org's decrypted `orgConfig` and the
+ * extension's effective deployment config for the org (`config`).
+ */
 export interface WebSearchProvider {
-    /** False when this org's config lacks what the provider needs. */
-    configured?(orgConfig: unknown): boolean;
+    /**
+     * False when this org's config lacks what the provider needs. `config` is the effective
+     * deployment config for the org (see `search`'s `config`).
+     */
+    configured?(orgConfig: unknown, config?: unknown): boolean;
     search(args: {
         query: string;
         /** Hints only: the kernel filters the results again. */
@@ -23,6 +29,14 @@ export interface WebSearchProvider {
         blockedDomains?: string[];
         maxResults: number;
         orgConfig: unknown;
+        /**
+         * 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;
         signal: AbortSignal;
     }): Promise<{
         results: WebSearchResult[];
@@ -48,12 +62,23 @@ export interface WebFetchPage {
  * to (an IPv6 address in brackets, as in a URL).
  */
 export interface WebFetchProvider {
-    /** False when this org's config lacks what the provider needs. */
-    configured?(orgConfig: unknown): boolean;
+    /**
+     * False when this org's config lacks what the provider needs. `config` is the effective
+     * deployment config for the org (see `fetch`'s `config`).
+     */
+    configured?(orgConfig: unknown, config?: unknown): boolean;
     fetch(args: {
         /** Already validated and upgraded by the kernel. */
         url: string;
         orgConfig: unknown;
+        /**
+         * 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;
         signal: AbortSignal;
     }): Promise<WebFetchPage>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capybara-hq/plugin-sdk",
-  "version": "0.1.0-rc.2",
+  "version": "0.1.0-rc.3",
   "description": "Capybara plugin SDK: the types and pure functions plugins are written against",
   "license": "Apache-2.0",
   "repository": {
@@ -17,11 +17,13 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
     "schemas",
+    "agent-docs",
     "README.md",
     "NOTICE"
   ],

package/schemas/marketplace.v1.schema.json

@@ -68,6 +68,25 @@
               "en"
             ]
           },
+          "displayName": {
+            "type": "object",
+            "properties": {
+              "zh": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 100
+              },
+              "en": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 100
+              }
+            },
+            "required": [
+              "zh",
+              "en"
+            ]
+          },
           "version": {
             "type": "string",
             "maxLength": 256,
@@ -110,6 +129,23 @@
             "maxLength": 2000,
             "pattern": "^https:\\/\\/\\S+$"
           },
+          "deprecated": {
+            "anyOf": [
+              {
+                "type": "boolean"
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "reason": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 280
+                  }
+                }
+              }
+            ]
+          },
           "source": {
             "anyOf": [
               {

package/schemas/plugin.v1.schema.json

@@ -28,10 +28,35 @@
       "pattern": "\\S"
     },
     "description": {
-      "type": "string",
-      "minLength": 1,
-      "maxLength": 1024,
-      "pattern": "\\S"
+      "anyOf": [
+        {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024,
+          "pattern": "\\S"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "en": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 1024,
+              "pattern": "\\S"
+            },
+            "zh": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 1024,
+              "pattern": "\\S"
+            }
+          },
+          "required": [
+            "en"
+          ],
+          "additionalProperties": false
+        }
+      ]
     },
     "displayName": {
       "type": "object",