@capybara-hq/plugin-sdk 0.1.0-rc.5 → 0.1.0-rc.6

package/dist/device-protocol.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Device protocol v1: the WebSocket frames between the kernel and a `capybara-device` program
+ * (a connected machine that serves as an environment). Pure types and hand-written guards.
+ */
+import { type ExecResult, type SandboxActor, type SandboxLimits, type SandboxRoots } from "./sandbox.js";
+/** The protocol version carried in `X-Capybara-Device-Protocol` and the hello frame. */
+export declare const DEVICE_PROTOCOL_VERSION = 1;
+/** The operations the kernel asks a device to run. */
+export type DeviceOp = "create" | "exec" | "readFile" | "writeFile" | "stat" | "killTagged" | "killAll" | "stop";
+/** First frame from the device after the WebSocket opens. */
+export interface DeviceHello {
+    type: "hello";
+    protocol: number;
+    programVersion: string;
+    os: "darwin" | "linux";
+    arch: string;
+    mode: "os" | "docker";
+    roots: SandboxRoots;
+    sessionIsolation: boolean;
+}
+/** Error kinds a device reports for a failed request. */
+export type DeviceErrorKind = "gone" | "fs_gone" | "policy" | "error";
+/** The device's answer to a {@link KernelReq}. */
+export type DeviceRes = {
+    type: "res";
+    id: string;
+    ok: true;
+    result: unknown;
+} | {
+    type: "res";
+    id: string;
+    ok: false;
+    error: {
+        kind: DeviceErrorKind;
+        message: string;
+    };
+};
+/** A request from the kernel. */
+export interface KernelReq {
+    type: "req";
+    id: string;
+    op: DeviceOp;
+    args: unknown;
+    deadlineMs: number;
+}
+/** The kernel gives up on a request (abort or deadline). */
+export interface KernelCancel {
+    type: "cancel";
+    id: string;
+}
+export type DeviceFrame = DeviceHello | DeviceRes | KernelReq | KernelCancel;
+export interface DeviceExecArgs {
+    command: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutMs: number;
+    maxOutputBytes: number;
+    tag: string;
+    actor: SandboxActor;
+    limits: SandboxLimits;
+}
+export type DeviceExecResult = ExecResult;
+export interface DeviceReadFileArgs {
+    path: string;
+    maxBytes: number;
+}
+export type DeviceReadFileResult = {
+    dataB64: string;
+    truncated: boolean;
+} | null;
+export interface DeviceWriteFileArgs {
+    path: string;
+    dataB64: string;
+}
+export type DeviceWriteFileResult = null;
+export interface DeviceStatArgs {
+    path: string;
+}
+export type DeviceStatResult = {
+    size: number;
+    isDir: boolean;
+} | null;
+export interface DeviceKillTaggedArgs {
+    tags: string[];
+}
+export type DeviceKillAllArgs = Record<string, never>;
+export interface DeviceCreateArgs {
+    limits: SandboxLimits;
+}
+export interface DeviceCreateResult {
+    roots: SandboxRoots;
+}
+export interface DeviceStopArgs {
+    reason: "revoked" | "deleted";
+}
+/** A frame that is not valid protocol v1 (or came from the wrong side). */
+export declare class DeviceProtocolError extends Error {
+    constructor(message: string);
+}
+/** Result type per op. */
+export interface DeviceOpResults {
+    create: DeviceCreateResult;
+    exec: DeviceExecResult;
+    readFile: DeviceReadFileResult;
+    writeFile: DeviceWriteFileResult;
+    stat: DeviceStatResult;
+    killTagged: null;
+    killAll: null;
+    stop: null;
+}
+/** Validates the `result` of a successful `res` for `op`; throws {@link DeviceProtocolError}. */
+export declare function parseOpResult<Op extends DeviceOp>(op: Op, result: unknown): DeviceOpResults[Op];
+/**
+ * Parses one WebSocket text frame. `from` is the sender: a device may send `hello` and `res`, the
+ * kernel `req` and `cancel`. Throws {@link DeviceProtocolError} on bad JSON, an unknown `type`,
+ * missing fields or a frame of the wrong direction.
+ */
+export declare function parseDeviceFrame(raw: string, from: "device" | "kernel"): DeviceFrame;

package/dist/device-protocol.js

@@ -0,0 +1,276 @@
+/**
+ * Device protocol v1: the WebSocket frames between the kernel and a `capybara-device` program
+ * (a connected machine that serves as an environment). Pure types and hand-written guards.
+ */
+import { validateSandboxPathShape, } from "./sandbox.js";
+/** The protocol version carried in `X-Capybara-Device-Protocol` and the hello frame. */
+export const DEVICE_PROTOCOL_VERSION = 1;
+const DEVICE_OPS = [
+    "create",
+    "exec",
+    "readFile",
+    "writeFile",
+    "stat",
+    "killTagged",
+    "killAll",
+    "stop",
+];
+/** A frame that is not valid protocol v1 (or came from the wrong side). */
+export class DeviceProtocolError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DeviceProtocolError";
+    }
+}
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function str(o, k) {
+    const v = o[k];
+    if (typeof v !== "string")
+        throw new DeviceProtocolError(`field "${k}" must be a string`);
+    return v;
+}
+function nonEmptyStr(o, k) {
+    const v = str(o, k);
+    if (v === "")
+        throw new DeviceProtocolError(`field "${k}" must not be empty`);
+    return v;
+}
+function posInt(o, k) {
+    const v = o[k];
+    if (typeof v !== "number" || !Number.isInteger(v) || v <= 0) {
+        throw new DeviceProtocolError(`field "${k}" must be a positive integer`);
+    }
+    return v;
+}
+function obj(v, what) {
+    if (!isRecord(v))
+        throw new DeviceProtocolError(`${what} must be an object`);
+    return v;
+}
+function bool(o, k) {
+    const v = o[k];
+    if (typeof v !== "boolean")
+        throw new DeviceProtocolError(`field "${k}" must be a boolean`);
+    return v;
+}
+function strArray(o, k) {
+    const v = o[k];
+    if (!Array.isArray(v) || v.some((x) => typeof x !== "string")) {
+        throw new DeviceProtocolError(`field "${k}" must be an array of strings`);
+    }
+    return v;
+}
+function parseLimits(v) {
+    const o = obj(v, 'field "limits"');
+    const egress = str(o, "egress");
+    if (egress !== "none" && egress !== "allowlist" && egress !== "open") {
+        throw new DeviceProtocolError(`unknown egress "${egress}"`);
+    }
+    return {
+        cpu: num(o, "cpu"),
+        memoryMb: num(o, "memoryMb"),
+        diskMb: num(o, "diskMb"),
+        egress,
+        allowHosts: strArray(o, "allowHosts"),
+    };
+}
+function num(o, k) {
+    const v = o[k];
+    if (typeof v !== "number" || !Number.isFinite(v)) {
+        throw new DeviceProtocolError(`field "${k}" must be a number`);
+    }
+    return v;
+}
+function parseRoots(v) {
+    if (!isRecord(v))
+        throw new DeviceProtocolError('field "roots" must be an object');
+    const roots = {};
+    for (const k of ["workspace", "skills", "tmp"]) {
+        const p = str(v, k);
+        if (!p.startsWith("/")) {
+            throw new DeviceProtocolError(`root "${k}" must be an absolute path`);
+        }
+        // the kernel builds paths as `${root}/…` and checks membership by prefix: a root must be a
+        // clean absolute directory path
+        const shape = validateSandboxPathShape(p);
+        if (shape.length > 0)
+            throw new DeviceProtocolError(`root "${k}": ${shape.join("; ")}`);
+        if (p.endsWith("/")) {
+            throw new DeviceProtocolError(`root "${k}" must not end with a slash`);
+        }
+        roots[k] = p;
+    }
+    return roots;
+}
+function parseHello(o) {
+    const os = str(o, "os");
+    if (os !== "darwin" && os !== "linux")
+        throw new DeviceProtocolError(`unsupported os "${os}"`);
+    const mode = str(o, "mode");
+    if (mode !== "os" && mode !== "docker") {
+        throw new DeviceProtocolError(`unsupported mode "${mode}"`);
+    }
+    if (typeof o.sessionIsolation !== "boolean") {
+        throw new DeviceProtocolError('field "sessionIsolation" must be a boolean');
+    }
+    return {
+        type: "hello",
+        protocol: posInt(o, "protocol"),
+        programVersion: str(o, "programVersion"),
+        os,
+        arch: str(o, "arch"),
+        mode,
+        roots: parseRoots(o.roots),
+        sessionIsolation: o.sessionIsolation,
+    };
+}
+function parseRes(o) {
+    const id = nonEmptyStr(o, "id");
+    if (o.ok === true)
+        return { type: "res", id, ok: true, result: o.result };
+    if (o.ok !== false)
+        throw new DeviceProtocolError('field "ok" must be a boolean');
+    const e = o.error;
+    if (!isRecord(e))
+        throw new DeviceProtocolError('field "error" must be an object');
+    const kind = str(e, "kind");
+    if (kind !== "gone" && kind !== "fs_gone" && kind !== "policy" && kind !== "error") {
+        throw new DeviceProtocolError(`unknown error kind "${kind}"`);
+    }
+    return { type: "res", id, ok: false, error: { kind, message: str(e, "message") } };
+}
+function parseReq(o) {
+    const op = str(o, "op");
+    if (!DEVICE_OPS.includes(op))
+        throw new DeviceProtocolError(`unknown op "${op}"`);
+    const args = obj(o.args, 'field "args"');
+    validateArgs(op, args);
+    return {
+        type: "req",
+        id: nonEmptyStr(o, "id"),
+        op: op,
+        args,
+        deadlineMs: posInt(o, "deadlineMs"),
+    };
+}
+function validateArgs(op, a) {
+    switch (op) {
+        case "exec": {
+            nonEmptyStr(a, "command");
+            posInt(a, "timeoutMs");
+            posInt(a, "maxOutputBytes");
+            str(a, "tag");
+            const actor = obj(a.actor, 'field "actor"');
+            str(actor, "accountId");
+            str(actor, "conversationId");
+            parseLimits(a.limits);
+            if (a.cwd !== undefined)
+                str(a, "cwd");
+            if (a.env !== undefined) {
+                const env = obj(a.env, 'field "env"');
+                for (const k of Object.keys(env))
+                    str(env, k);
+            }
+            return;
+        }
+        case "readFile": {
+            str(a, "path");
+            const m = a.maxBytes;
+            if (typeof m !== "number" || !Number.isInteger(m) || m < 0) {
+                throw new DeviceProtocolError('field "maxBytes" must be a non-negative integer');
+            }
+            return;
+        }
+        case "writeFile":
+            str(a, "path");
+            str(a, "dataB64");
+            return;
+        case "stat":
+            str(a, "path");
+            return;
+        case "killTagged":
+            strArray(a, "tags");
+            return;
+        case "killAll":
+            return;
+        case "create":
+            parseLimits(a.limits);
+            return;
+        case "stop": {
+            const r = str(a, "reason");
+            if (r !== "revoked" && r !== "deleted") {
+                throw new DeviceProtocolError(`unknown stop reason "${r}"`);
+            }
+            return;
+        }
+    }
+}
+export function parseOpResult(op, result) {
+    switch (op) {
+        case "exec": {
+            const r = obj(result, "exec result");
+            const exitCode = r.exitCode;
+            if (exitCode !== null && (typeof exitCode !== "number" || !Number.isFinite(exitCode))) {
+                throw new DeviceProtocolError('field "exitCode" must be a number or null');
+            }
+            return {
+                exitCode: exitCode,
+                stdout: str(r, "stdout"),
+                stderr: str(r, "stderr"),
+                truncated: bool(r, "truncated"),
+                timedOut: bool(r, "timedOut"),
+            };
+        }
+        case "readFile": {
+            if (result === null)
+                return null;
+            const r = obj(result, "readFile result");
+            return { dataB64: str(r, "dataB64"), truncated: bool(r, "truncated") };
+        }
+        case "stat": {
+            if (result === null)
+                return null;
+            const r = obj(result, "stat result");
+            return { size: num(r, "size"), isDir: bool(r, "isDir") };
+        }
+        case "create":
+            return { roots: parseRoots(obj(result, "create result").roots) };
+        default:
+            if (result !== null)
+                throw new DeviceProtocolError(`${op} result must be null`);
+            return null;
+    }
+}
+/**
+ * Parses one WebSocket text frame. `from` is the sender: a device may send `hello` and `res`, the
+ * kernel `req` and `cancel`. Throws {@link DeviceProtocolError} on bad JSON, an unknown `type`,
+ * missing fields or a frame of the wrong direction.
+ */
+export function parseDeviceFrame(raw, from) {
+    let o;
+    try {
+        o = JSON.parse(raw);
+    }
+    catch {
+        throw new DeviceProtocolError("frame is not valid JSON");
+    }
+    if (!isRecord(o))
+        throw new DeviceProtocolError("frame must be a JSON object");
+    const type = o.type;
+    switch (type) {
+        case "hello":
+        case "res":
+            if (from !== "device")
+                throw new DeviceProtocolError(`"${type}" must come from the device`);
+            return type === "hello" ? parseHello(o) : parseRes(o);
+        case "req":
+        case "cancel":
+            if (from !== "kernel")
+                throw new DeviceProtocolError(`"${type}" must come from the kernel`);
+            return type === "req" ? parseReq(o) : { type: "cancel", id: nonEmptyStr(o, "id") };
+        default:
+            throw new DeviceProtocolError(`unknown frame type "${String(type)}"`);
+    }
+}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const SDK_VERSION = "0.1.0-rc.5";
+export declare const SDK_VERSION = "0.1.0-rc.6";
 export * from "./agent-template.js";
 export * from "./bootstrap.js";
 export * from "./cards.js";
@@ -8,6 +8,7 @@ export * from "./connector.js";
 export * from "./connector-auth.js";
 export * from "./ctx.js";
 export * from "./define-extension.js";
+export * from "./device-protocol.js";
 export * from "./directory.js";
 export * from "./extension-point.js";
 export * from "./file-preview.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export const SDK_VERSION = "0.1.0-rc.5";
+export const SDK_VERSION = "0.1.0-rc.6";
 export * from "./agent-template.js";
 export * from "./bootstrap.js";
 export * from "./cards.js";
@@ -8,6 +8,7 @@ export * from "./connector.js";
 export * from "./connector-auth.js";
 export * from "./ctx.js";
 export * from "./define-extension.js";
+export * from "./device-protocol.js";
 export * from "./directory.js";
 export * from "./extension-point.js";
 export * from "./file-preview.js";

package/dist/sandbox.d.ts

@@ -21,11 +21,23 @@ export interface SandboxLimits {
     /** Egress allowlist (used when `egress` is `allowlist`); each entry passes {@link validateAllowHost}. */
     allowHosts: string[];
 }
+/** The absolute roots inside one instance (a device may place them anywhere on its host). */
+export interface SandboxRoots {
+    workspace: string;
+    skills: string;
+    tmp: string;
+}
+/** The roots every container-like provider uses; the same paths as {@link SANDBOX_ROOTS}. */
+export declare const DEFAULT_SANDBOX_ROOTS: Readonly<SandboxRoots>;
 /** The provider's instance handle. */
 export interface SandboxHandle {
     /** The provider's instance id. */
     id: string;
+    /** The instance's roots; absent means {@link DEFAULT_SANDBOX_ROOTS}. */
+    roots?: SandboxRoots;
 }
+/** The roots of an instance, falling back to {@link DEFAULT_SANDBOX_ROOTS}. */
+export declare function rootsOf(h: SandboxHandle): SandboxRoots;
 /** The provider's file system handle (an environment's files, independent of any instance). */
 export interface FileSystemHandle {
     /** The provider's file system id. */
@@ -226,7 +238,17 @@ export interface SandboxProvider {
         isDir: boolean;
     } | null>;
 }
-/** 校验沙箱内路径：返回错误列表，空数组表示合法。 */
-export declare function validateSandboxPath(p: string): string[];
+/**
+ * The root-independent checks of a path inside an instance (non-empty, at most 4096 characters, no
+ * control characters or backslashes, absolute, no empty or `..` segments); returns the errors,
+ * empty when valid. {@link validateSandboxPath} adds root membership.
+ */
+export declare function validateSandboxPathShape(p: string): string[];
+/**
+ * Checks a path inside an instance; returns the errors, empty when valid: the
+ * {@link validateSandboxPathShape} checks, then root membership. `roots`: the instance's roots
+ * ({@link rootsOf}); absent means {@link SANDBOX_ROOTS}. The path must be one of them or under one.
+ */
+export declare function validateSandboxPath(p: string, roots?: SandboxRoots): string[];
 /** 校验出站白名单主机名：小写、无协议与端口、可选前导 `*.`、IDN 只认 punycode。 */
 export declare function validateAllowHost(h: string): string[];

package/dist/sandbox.js

@@ -13,6 +13,16 @@ 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;
+/** The roots every container-like provider uses; the same paths as {@link SANDBOX_ROOTS}. */
+export const DEFAULT_SANDBOX_ROOTS = Object.freeze({
+    workspace: "/workspace",
+    skills: "/skills",
+    tmp: "/tmp",
+});
+/** The roots of an instance, falling back to {@link DEFAULT_SANDBOX_ROOTS}. */
+export function rootsOf(h) {
+    return h.roots ?? DEFAULT_SANDBOX_ROOTS;
+}
 /**
  * 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
@@ -58,8 +68,12 @@ export function isFileSystemGoneError(e) {
 export const SANDBOX_TAG_RE = /^[a-z0-9-]{1,64}$/;
 // biome-ignore lint/suspicious/noControlCharactersInRegex: 正是要拦控制字符
 const CONTROL = /[\u0000-\u001f\u007f]/;
-/** 校验沙箱内路径：返回错误列表，空数组表示合法。 */
-export function validateSandboxPath(p) {
+/**
+ * The root-independent checks of a path inside an instance (non-empty, at most 4096 characters, no
+ * control characters or backslashes, absolute, no empty or `..` segments); returns the errors,
+ * empty when valid. {@link validateSandboxPath} adds root membership.
+ */
+export function validateSandboxPathShape(p) {
     if (typeof p !== "string" || p.length === 0)
         return ["path must be a non-empty string"];
     if (p.length > MAX_PATH_LENGTH)
@@ -72,22 +86,41 @@ export function validateSandboxPath(p) {
         return ["path must be absolute"];
     if (p.includes("//"))
         return ["path must not contain empty segments"];
-    const errors = [];
     for (const seg of p.split("/")) {
         let decoded = seg;
         try {
             decoded = decodeURIComponent(seg);
         }
         catch {
-            // 非法百分号编码按字面处理
+            // invalid percent-encoding is taken literally
         }
         if (seg === ".." || decoded === ".." || decoded.includes("/") || decoded.includes("\\")) {
-            errors.push("path must not contain '..' segments");
-            break;
+            return ["path must not contain '..' segments"];
         }
     }
-    if (!SANDBOX_ROOTS.some((r) => p === r || p.startsWith(`${r}/`))) {
-        errors.push(`path must be under ${SANDBOX_ROOTS.join(", ")}`);
+    return [];
+}
+/** A structural error after which {@link validateSandboxPath} stops (before the root check). */
+const STOPS = new Set([
+    "path must be a non-empty string",
+    `path must be at most ${MAX_PATH_LENGTH} characters`,
+    "path must not contain control characters",
+    "path must not contain backslashes",
+    "path must be absolute",
+    "path must not contain empty segments",
+]);
+/**
+ * Checks a path inside an instance; returns the errors, empty when valid: the
+ * {@link validateSandboxPathShape} checks, then root membership. `roots`: the instance's roots
+ * ({@link rootsOf}); absent means {@link SANDBOX_ROOTS}. The path must be one of them or under one.
+ */
+export function validateSandboxPath(p, roots) {
+    const errors = validateSandboxPathShape(p);
+    if (errors.some((e) => STOPS.has(e)))
+        return errors;
+    const allowed = roots === undefined ? SANDBOX_ROOTS : [roots.workspace, roots.skills, roots.tmp];
+    if (!allowed.some((r) => p === r || p.startsWith(`${r}/`))) {
+        errors.push(`path must be under ${allowed.join(", ")}`);
     }
     return errors;
 }

package/dist/skill-invocation.d.ts

@@ -27,13 +27,14 @@ 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 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;
+ * `${CLAUDE_SKILL_DIR}` becomes `<skillsRoot>/<skillName>@<digest>` (`skillsRoot`: the instance's
+ * skills root, default `/skills`; 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, digest: string): string;
+export declare function renderSkillBody(body: string, invocation: SkillInvocation, args: string, skillName: string, digest: string, skillsRoot?: string): string;
 /** Input of {@link renderSkillInvocation}. */
 export interface RenderSkillInvocationInput {
     /**

package/dist/skill-invocation.js

@@ -112,16 +112,17 @@ const tooLong = () => new RangeError(`the rendered skill must be at most ${SKILL
 /**
  * A skill body with its arguments substituted (see the file header), without the wrapper.
  * `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;
+ * `${CLAUDE_SKILL_DIR}` becomes `<skillsRoot>/<skillName>@<digest>` (`skillsRoot`: the instance's
+ * skills root, default `/skills`; 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, digest) {
+export function renderSkillBody(body, invocation, args, skillName, digest, skillsRoot = SKILLS_SANDBOX_ROOT) {
     checkSkillName(skillName);
     checkDigest(digest);
-    const dir = skillSandboxDir(skillName, digest);
+    const dir = skillSandboxDir(skillName, digest, skillsRoot);
     const all = trimmedArgs(args);
     const values = parseSkillArguments(all);
     const named = invocation.arguments ?? [];

package/dist/skill.d.ts

@@ -49,10 +49,13 @@ export declare function skillDigest(files: {
     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;
+/**
+ * A skill version's directory in the sandbox: `<root>/<name>@<digest>` ({@link skillDigest});
+ * `root` is the instance's skills root (`SandboxRoots.skills`, default `/skills`).
+ */
+export declare function skillSandboxDir(name: string, digest: string, root?: string): string;
+/** A skill file's path in the sandbox: `<root>/<name>@<digest>/<path>` ({@link skillSandboxDir}). */
+export declare function skillSandboxPath(name: string, digest: string, path: string, root?: string): string;
 /** {@link parseSkillMd} 成功时的结果。 */
 export interface ParsedSkillMd {
     name: string;

package/dist/skill.js

@@ -81,13 +81,16 @@ export function skillDigest(files) {
         .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 version's directory in the sandbox: `<root>/<name>@<digest>` ({@link skillDigest});
+ * `root` is the instance's skills root (`SandboxRoots.skills`, default `/skills`).
+ */
+export function skillSandboxDir(name, digest, root = SKILLS_SANDBOX_ROOT) {
+    return `${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}`;
+/** A skill file's path in the sandbox: `<root>/<name>@<digest>/<path>` ({@link skillSandboxDir}). */
+export function skillSandboxPath(name, digest, path, root = SKILLS_SANDBOX_ROOT) {
+    return `${skillSandboxDir(name, digest, root)}/${path}`;
 }
 const chars = (s) => [...s].length;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capybara-hq/plugin-sdk",
-  "version": "0.1.0-rc.5",
+  "version": "0.1.0-rc.6",
   "description": "Capybara plugin SDK: the types and pure functions plugins are written against",
   "license": "Apache-2.0",
   "repository": {