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

package/dist/plugin-package.js

@@ -0,0 +1,448 @@
+import semver from "semver";
+import { ConnectorAuthSchema } from "./connector-auth.js";
+import { EXTENSION_NAME_RE } from "./define-extension.js";
+/**
+ * Plugin package (npm-pack tgz) rules shared by the SDK, the packer and the kernel (spec §4.1). Pure
+ * functions only: the kernel reads the tgz and scans imports, `packages/plugin-tools` packs it. The
+ * manifest is `.capybara-plugin/plugin.json` (plugin-manifest.ts); an extension's static manifest
+ * ({@link StaticExtensionManifest}) is written into it by the packer and compared with the real
+ * module's {@link staticManifestOf} at load (a difference is `manifest_mismatch`). The extension
+ * entry is single-file ESM with third-party dependencies bundled; only {@link HOST_PROVIDED_PACKAGES}
+ * come from the host.
+ */
+/** 宿主提供的包（peerDependencies，安装时链接到宿主副本）；其余三方依赖必须打进 entry。 */
+export const HOST_PROVIDED_PACKAGES = ["@capybara-hq/plugin-sdk", "zod"];
+/** npm 安装时会自动执行的脚本：插件包一律不许有（安装不跑脚本，有也是误导）。 */
+export const FORBIDDEN_INSTALL_SCRIPTS = [
+    "preinstall",
+    "install",
+    "postinstall",
+    "prepare",
+];
+/** 不许出现的依赖字段：三方依赖必须打进 entry。 */
+const FORBIDDEN_DEP_FIELDS = [
+    "dependencies",
+    "optionalDependencies",
+    "bundleDependencies",
+    "bundledDependencies",
+];
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** npm 包名规则（简化）：可带 scope，小写，≤ 214 字符（长度另行检查）。 */
+export const NPM_PACKAGE_NAME_RE = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
+const NPM_NAME_RE = NPM_PACKAGE_NAME_RE;
+/**
+ * 包内相对路径是否安全：非空、不以 `/` 开头、不含 `\`、控制字符与盘符，没有空段、`.` 与 `..` 段，≤ 1024 字符。
+ */
+export function isSafePackagePath(p) {
+    if (typeof p !== "string" || p === "" || p.length > 1024)
+        return false;
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: 正是要拒绝控制字符
+    if (p.startsWith("/") || p.includes("\\") || /[\u0000-\u001f\u007f]/.test(p))
+        return false;
+    if (/^[A-Za-z]:/.test(p))
+        return false;
+    return p.split("/").every((seg) => seg !== "" && seg !== "." && seg !== "..");
+}
+const isHostPackage = (name) => HOST_PROVIDED_PACKAGES.some((h) => name === h || name.startsWith(`${h}/`));
+/**
+ * 核对入口模块的 import（C11）：静态与字面量动态 import 只许 `node:*`、{@link HOST_PROVIDED_PACKAGES}（含子路径）
+ * 与包内相对路径（`./`、`../`；是否越出包外由调用方按文件位置判断）；非字面量的动态 import 一律拒绝。
+ * 返回问题列表（空表示合法）。
+ */
+export function checkEntryImports(specifiers) {
+    const out = [];
+    for (const s of specifiers) {
+        if (s.dynamic && !s.literal) {
+            out.push("dynamic import() with a non-literal specifier is not allowed");
+            continue;
+        }
+        const n = s.name;
+        if (n.startsWith("node:") && n.length > 5)
+            continue;
+        if (isHostPackage(n))
+            continue;
+        if (n.startsWith("./") || n.startsWith("../"))
+            continue;
+        out.push(`import of "${n}" is not allowed: bundle third-party dependencies into the entry ` +
+            `(only node:*, ${HOST_PROVIDED_PACKAGES.join(", ")} and relative paths are resolved at load)`);
+    }
+    return out;
+}
+const WRAPPERS = new Set(["default", "prefault", "optional", "nullable", "readonly", "catch"]);
+const defOf = (s) => s._zod.def;
+const metaOf = (s) => s.meta();
+/** 与内核 `configFields` 相同的遍历：对象递归展开，default / optional 等包装剥掉，对象上的 secret 向下继承。 */
+function configFieldsOf(schema, prefix = "", inheritedSecret = false) {
+    if (!schema)
+        return [];
+    let node = schema;
+    let meta = metaOf(node);
+    while (WRAPPERS.has(defOf(node).type) && defOf(node).innerType) {
+        node = defOf(node).innerType;
+        meta ??= metaOf(node);
+    }
+    const secret = inheritedSecret || meta?.secret === true;
+    const def = defOf(node);
+    if (def.type === "object" && def.shape) {
+        return Object.entries(def.shape).flatMap(([k, v]) => configFieldsOf(v, prefix ? `${prefix}.${k}` : k, secret));
+    }
+    return [{ path: prefix, secret, hot: meta?.hot === true }];
+}
+const byPath = (a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
+const jsonClone = (v) => JSON.parse(JSON.stringify(v));
+/**
+ * 真实清单的静态部分：打包时写进 `capybara.manifest`，加载时与包内的比对（`manifest_mismatch`）。
+ * 结果可 JSON 往返（undefined 字段去掉）；配置字段按路径排序。
+ */
+export function staticManifestOf(m) {
+    const out = {
+        name: m.name,
+        version: m.version,
+        sdk: m.sdk,
+        provides: [...m.provides],
+        requires: [...(m.requires ?? [])],
+        optional: [...(m.optional ?? [])],
+        permissions: jsonClone(m.permissions ?? {}),
+        config: {
+            deployment: configFieldsOf(m.config?.deployment).sort(byPath),
+            org: configFieldsOf(m.config?.org).sort(byPath),
+        },
+    };
+    if (m.ui !== undefined)
+        out.ui = jsonClone(m.ui);
+    return out;
+}
+/**
+ * The package.json rules shared by every plugin tgz: npm name, semver version, no install scripts,
+ * no `gypfile`, no dependency fields, `peerDependencies` only host packages, and a `zod` peer range
+ * that is valid (and satisfied by `hostZodVersion` when given). Returns the peerDependencies object.
+ */
+function checkPluginPackageBasics(pkg, opts, errs) {
+    if (typeof pkg.name !== "string" || pkg.name.length > 214 || !NPM_NAME_RE.test(pkg.name)) {
+        errs.push("package.json name must be a valid npm package name");
+    }
+    if (typeof pkg.version !== "string" || semver.valid(pkg.version) === null) {
+        errs.push("package.json version must be a valid semver version");
+    }
+    if (pkg.scripts !== undefined) {
+        if (!isObj(pkg.scripts))
+            errs.push("package.json scripts must be an object");
+        else {
+            for (const s of FORBIDDEN_INSTALL_SCRIPTS) {
+                if (Object.hasOwn(pkg.scripts, s)) {
+                    errs.push(`package.json scripts.${s} is not allowed: plugin packages never run scripts`);
+                }
+            }
+        }
+    }
+    if (pkg.gypfile !== undefined && pkg.gypfile !== false) {
+        errs.push("package.json gypfile is not allowed: native addons are not supported");
+    }
+    for (const f of FORBIDDEN_DEP_FIELDS) {
+        const v = pkg[f];
+        if (v === undefined)
+            continue;
+        const empty = Array.isArray(v) ? v.length === 0 : isObj(v) && Object.keys(v).length === 0;
+        if (!empty) {
+            errs.push(`package.json ${f} is not allowed: bundle third-party dependencies into the entry`);
+        }
+    }
+    let peers = {};
+    if (pkg.peerDependencies !== undefined) {
+        if (!isObj(pkg.peerDependencies))
+            errs.push("package.json peerDependencies must be an object");
+        else {
+            peers = pkg.peerDependencies;
+            for (const k of Object.keys(peers)) {
+                if (!HOST_PROVIDED_PACKAGES.includes(k)) {
+                    errs.push(`package.json peerDependencies "${k}" is not provided by the host (only ${HOST_PROVIDED_PACKAGES.join(", ")})`);
+                }
+            }
+        }
+    }
+    const zodRange = peers.zod;
+    if (zodRange !== undefined) {
+        if (typeof zodRange !== "string" || semver.validRange(zodRange) === null) {
+            errs.push("package.json peerDependencies zod must be a valid semver range");
+        }
+        else if (opts.hostZodVersion !== undefined &&
+            !semver.satisfies(opts.hostZodVersion, zodRange, { includePrerelease: true })) {
+            errs.push(`package.json peerDependencies zod "${zodRange}" is not satisfied by the host zod ${opts.hostZodVersion}`);
+        }
+    }
+    return peers;
+}
+/**
+ * Validates the `package.json` of a plugin tgz against its parsed `.capybara-plugin/plugin.json`
+ * ({@link PluginManifest}), returning the problems (empty when valid): the rules shared with every
+ * plugin package (npm name, semver version, no install scripts, no `gypfile`, no dependency fields,
+ * `peerDependencies` only host packages, a valid `zod` peer range satisfied by `hostZodVersion`),
+ * no `capybara` section, the version equal to the manifest's, and:
+ * - with an extension: `peerDependencies["@capybara-hq/plugin-sdk"]` present and equal to
+ *   `extension.manifest.sdk`, which the host SDK version satisfies (includePrerelease), and
+ *   `main` / `exports` absent or naming `extension.entry` (the packer writes both);
+ * - without one: no `peerDependencies`, `main` or `exports` at all.
+ */
+export function validatePluginPackageJsonFor(pkg, manifest, hostSdkVersion, opts = {}) {
+    if (!isObj(pkg))
+        return ["package.json must be a JSON object"];
+    const errs = [];
+    const peers = checkPluginPackageBasics(pkg, opts, errs);
+    if (pkg.capybara !== undefined) {
+        errs.push("package.json must not have a capybara section (the manifest is .capybara-plugin/plugin.json)");
+    }
+    if (typeof pkg.version === "string" && pkg.version !== manifest.version) {
+        errs.push(`package.json version "${pkg.version}" does not match plugin.json version "${manifest.version}"`);
+    }
+    const ext = manifest.extension;
+    if (ext === undefined) {
+        if (isObj(pkg.peerDependencies) && Object.keys(pkg.peerDependencies).length > 0) {
+            errs.push("package.json peerDependencies is not allowed in a plugin without an extension (nothing is loaded from the host)");
+        }
+        for (const f of ["main", "exports"]) {
+            if (pkg[f] !== undefined) {
+                errs.push(`package.json ${f} is not allowed in a plugin without an extension (there is no module to load)`);
+            }
+        }
+        return errs;
+    }
+    errs.push(...entryFieldIssues(pkg, ext.entry));
+    const sdk = ext.manifest.sdk;
+    const peerSdk = peers["@capybara-hq/plugin-sdk"];
+    if (peerSdk === undefined) {
+        errs.push(`package.json peerDependencies "@capybara-hq/plugin-sdk" is required and must equal extension.manifest.sdk "${sdk}"`);
+    }
+    else if (peerSdk !== sdk) {
+        errs.push(`package.json peerDependencies "@capybara-hq/plugin-sdk" "${String(peerSdk)}" must equal extension.manifest.sdk "${sdk}"`);
+    }
+    const sdkProblem = hostSdkProblem(sdk, hostSdkVersion);
+    if (sdkProblem !== undefined)
+        errs.push(sdkProblem);
+    return errs;
+}
+/**
+ * `main` and `exports` of an extension-bearing plugin: absent, or naming the extension entry
+ * (`"main": "<entry>"`, `"exports": "<entry>"` or `{ ".": "<entry>" }`), so the package resolves by
+ * name (`require.resolve`, a test loading the extension by package name) to the module the kernel
+ * loads, and to nothing else.
+ */
+function entryFieldIssues(pkg, entry) {
+    const errs = [];
+    const why = `must be absent or name the extension entry "${entry}"`;
+    // `main` may omit the leading ./ (`dist/index.mjs`); an `exports` target must keep it (Node)
+    const bare = (p) => (typeof p === "string" ? p.replace(/^\.\//, "") : p);
+    if (pkg.main !== undefined && bare(pkg.main) !== bare(entry)) {
+        errs.push(`package.json main ${why}`);
+    }
+    const ex = pkg.exports;
+    const exportsOk = ex === undefined ||
+        ex === entry ||
+        (isObj(ex) && Object.keys(ex).length === 1 && ex["."] === entry);
+    if (!exportsOk)
+        errs.push(`package.json exports ${why} (as a string or { ".": "${entry}" })`);
+    return errs;
+}
+/**
+ * Whether the host SDK satisfies an extension's `extension.manifest.sdk` range: the problem
+ * (English), or undefined when it does (an invalid range is reported by the manifest parser).
+ */
+export function hostSdkProblem(sdk, hostSdkVersion) {
+    if (semver.validRange(sdk) === null)
+        return undefined;
+    if (semver.satisfies(hostSdkVersion, sdk, { includePrerelease: true }))
+        return undefined;
+    return `extension.manifest.sdk "${sdk}" is not satisfied by the host SDK version ${hostSdkVersion}`;
+}
+/** 连接器模板与目录段的上限。 */
+export const CONNECTOR_TEMPLATE_LIMITS = {
+    /** 图标字节数上限。 */
+    iconBytes: 64 * 1024,
+    /** 端点预设 JSON 序列化后的字符数上限。 */
+    endpointChars: 16 * 1024,
+    /** `editableEndpoint` 条数上限。 */
+    editablePaths: 50,
+    /** `defaultToolPolicies` 条数上限。 */
+    toolPolicies: 1000,
+    /** publisher 字符数上限。 */
+    publisherChars: 100,
+    /** description 字符数上限。 */
+    descriptionChars: 1024,
+    /** displayName 每种语言的字符数上限。 */
+    displayNameChars: 100,
+};
+/** 目录条目名（与清单条目名同一规则）：小写字母或数字开头，之后小写字母、数字、连字符，≤ 64。 */
+export const CATALOG_ITEM_NAME_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+/** An exact semver version (a regex JSON Schema can use). */
+export const SEMVER_VERSION_RE = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*)?(?:\+[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*)?$/;
+/** The sha512 SRI of an npm package tgz: `sha512-<86 base64 chars>==`. */
+export const SHA512_INTEGRITY_RE = /^sha512-[A-Za-z0-9+/]{86}==$/;
+const PATH_SEG_RE = /^[A-Za-z0-9_-]{1,100}$/;
+const PROTO_KEYS = new Set(["__proto__", "prototype", "constructor"]);
+/**
+ * 凭据样式的字段名（比较时转小写、去掉 `-` 与 `_`）：模板会被所有组织看到，端点预设里出现这些键一律拒绝。
+ * `authorization` / `cookie` 等头名同样在列（端点头里的凭据）。
+ */
+const CREDENTIAL_KEYS = new Set([
+    "token",
+    "accesstoken",
+    "refreshtoken",
+    "idtoken",
+    "bearertoken",
+    "authtoken",
+    "apikey",
+    "apitoken",
+    "xapikey",
+    "secret",
+    "clientsecret",
+    "password",
+    "passwd",
+    "credential",
+    "credentials",
+    "privatekey",
+    "authorization",
+    "proxyauthorization",
+    "cookie",
+    "sessiontoken",
+]);
+const normKey = (k) => k.toLowerCase().replace(/[-_]/g, "");
+/** 递归找出凭据样式的键（只报路径，不回显值）。 */
+function credentialKeyPaths(v, at, out, depth = 0) {
+    if (depth > 20)
+        return;
+    if (Array.isArray(v)) {
+        v.forEach((x, i) => {
+            credentialKeyPaths(x, `${at}.${i}`, out, depth + 1);
+        });
+        return;
+    }
+    if (!isObj(v))
+        return;
+    for (const [k, x] of Object.entries(v)) {
+        const p = `${at}.${k}`;
+        if (CREDENTIAL_KEYS.has(normKey(k)))
+            out.push(p);
+        credentialKeyPaths(x, p, out, depth + 1);
+    }
+}
+const TEMPLATE_KEYS = new Set([
+    "plugin",
+    "pluginVersion",
+    "connector",
+    "endpoint",
+    "editableEndpoint",
+    "auth",
+    "ownership",
+    "defaultToolPolicies",
+    "icon",
+]);
+/**
+ * 校验连接器模板（{@link ConnectorTemplateSpec}）的静态部分，返回问题列表（空表示合法；路径相对模板根，不回显值）：
+ * 字段齐全、无未知字段；`auth` 符合 {@link ConnectorAuthSchema}（strict：夹带 `token` 等多余字段即拒绝）；
+ * 端点预设里任何层级都不许有凭据样式的键；`editableEndpoint` 是不重复的点路径；`ownership` 与 `auth.ownership`
+ * 一致；默认策略只许 allow / ask / deny；icon 是包内 .svg / .png 路径。
+ * 端点是否符合连接器的 `endpointSchema`、`editableEndpoint` 是否存在于其中，由内核在导入时按已加载的连接器校验。
+ */
+export function validateConnectorTemplate(t) {
+    if (!isObj(t))
+        return ["template must be an object"];
+    const errs = [];
+    for (const k of Object.keys(t)) {
+        if (!TEMPLATE_KEYS.has(k))
+            errs.push(`template has unknown field "${k}"`);
+    }
+    if (typeof t.plugin !== "string" || !EXTENSION_NAME_RE.test(t.plugin)) {
+        errs.push(`template.plugin must be a plugin name matching ${EXTENSION_NAME_RE}`);
+    }
+    if (t.pluginVersion !== undefined &&
+        (typeof t.pluginVersion !== "string" || semver.validRange(t.pluginVersion) === null)) {
+        errs.push("template.pluginVersion must be a valid semver range");
+    }
+    if (typeof t.connector !== "string" || t.connector.length < 1 || t.connector.length > 100) {
+        errs.push("template.connector must be a connector kind (1-100 characters)");
+    }
+    if (!isObj(t.endpoint))
+        errs.push("template.endpoint must be an object");
+    else {
+        if (JSON.stringify(t.endpoint).length > CONNECTOR_TEMPLATE_LIMITS.endpointChars) {
+            errs.push(`template.endpoint is larger than ${CONNECTOR_TEMPLATE_LIMITS.endpointChars} characters`);
+        }
+        const leaks = [];
+        credentialKeyPaths(t.endpoint, "template.endpoint", leaks);
+        for (const p of leaks) {
+            errs.push(`${p} looks like a credential: templates must not contain credentials; organizations provide them when installing`);
+        }
+    }
+    if (t.editableEndpoint !== undefined) {
+        if (!Array.isArray(t.editableEndpoint) ||
+            t.editableEndpoint.length > CONNECTOR_TEMPLATE_LIMITS.editablePaths) {
+            errs.push(`template.editableEndpoint must be an array of at most ${CONNECTOR_TEMPLATE_LIMITS.editablePaths} paths`);
+        }
+        else {
+            const seen = new Set();
+            for (const p of t.editableEndpoint) {
+                const ok = typeof p === "string" &&
+                    p.split(".").every((s) => PATH_SEG_RE.test(s) && !PROTO_KEYS.has(s));
+                if (!ok) {
+                    errs.push(`template.editableEndpoint entries must be dot paths of letters, digits, "_" and "-" (got ${JSON.stringify(typeof p === "string" ? p.slice(0, 100) : typeof p)})`);
+                    continue;
+                }
+                if (p.split(".").some((seg) => CREDENTIAL_KEYS.has(normKey(seg)))) {
+                    errs.push(`template.editableEndpoint "${p}" looks like a credential field: organizations provide credentials through the connector's auth, not the endpoint`);
+                    continue;
+                }
+                if (seen.has(p))
+                    errs.push(`template.editableEndpoint has duplicate path "${p}"`);
+                seen.add(p);
+            }
+        }
+    }
+    const auth = ConnectorAuthSchema.safeParse(t.auth);
+    if (!auth.success) {
+        for (const i of auth.error.issues) {
+            const path = ["template.auth", ...i.path.map(String)].join(".");
+            const keys = i.keys;
+            errs.push(keys && keys.length > 0
+                ? `${path} has unknown field(s) ${keys.map((k) => `"${k}"`).join(", ")}: auth presets must not contain credentials`
+                : `${path}: ${i.message}`);
+        }
+    }
+    if (t.ownership !== undefined) {
+        if (t.ownership !== "org" && t.ownership !== "personal") {
+            errs.push('template.ownership must be "org" or "personal"');
+        }
+        else if (auth.success) {
+            const a = auth.data;
+            if (a.type === "none") {
+                errs.push("template.ownership is not allowed with auth type none (no credential)");
+            }
+            else if (a.ownership !== t.ownership) {
+                errs.push(`template.ownership "${t.ownership}" does not match template.auth.ownership "${a.ownership}"`);
+            }
+        }
+    }
+    if (t.defaultToolPolicies !== undefined) {
+        const p = t.defaultToolPolicies;
+        if (!isObj(p) || Object.keys(p).length > CONNECTOR_TEMPLATE_LIMITS.toolPolicies) {
+            errs.push(`template.defaultToolPolicies must be an object with at most ${CONNECTOR_TEMPLATE_LIMITS.toolPolicies} entries`);
+        }
+        else {
+            for (const [name, v] of Object.entries(p)) {
+                if (name.length < 1 || name.length > 200) {
+                    errs.push("template.defaultToolPolicies keys must be tool names (1-200 characters)");
+                }
+                else if (PROTO_KEYS.has(name)) {
+                    errs.push(`template.defaultToolPolicies key "${name}" is not allowed`);
+                }
+                else if (v !== "allow" && v !== "ask" && v !== "deny") {
+                    errs.push(`template.defaultToolPolicies.${name} must be "allow", "ask" or "deny"`);
+                }
+            }
+        }
+    }
+    if (t.icon !== undefined) {
+        if (typeof t.icon !== "string" || !isSafePackagePath(t.icon) || !/\.(svg|png)$/i.test(t.icon)) {
+            errs.push("template.icon must be a relative .svg or .png path inside the package");
+        }
+    }
+    return errs;
+}

package/dist/sandbox.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Sandbox contract `sandbox@1`: 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`.
+ */
+/** Sandbox extension point ref. */
+export declare const SANDBOX_EXTENSION_POINT = "sandbox@1";
+/** 沙箱内允许模型访问的根目录。 */
+export declare const SANDBOX_ROOTS: readonly ["/workspace", "/skills", "/tmp"];
+/** 沙箱资源与出站限制。 */
+export interface SandboxLimits {
+    cpu: number;
+    memoryMb: number;
+    diskMb: number;
+    egress: "none" | "allowlist" | "open";
+    /** 出站白名单（`egress` 为 `allowlist` 时生效）；每项须通过 {@link validateAllowHost}。 */
+    allowHosts: string[];
+}
+/** 提供方的实例句柄。 */
+export interface SandboxHandle {
+    /** 提供方的实例 id。 */
+    id: string;
+}
+/** 命令执行结果。 */
+export interface ExecResult {
+    /** 超时或在执行中被中止为 null（此时 `timedOut` 分别为 true / false）。 */
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    truncated: boolean;
+    timedOut: boolean;
+}
+/**
+ * 实例在提供方那边确定已经不在了（容器被删、E2B 沙箱过期）。`exec` / `readFile` / `writeFile` / `stat`
+ * 发现实例不在时必须抛它（而不是普通 Error），内核据此重建沙箱并重试一次；只是暂时连不上时抛普通错误。
+ */
+export declare class SandboxGoneError extends Error {
+    readonly sandboxGone: true;
+    constructor(message: string, opts?: {
+        cause?: unknown;
+    });
+}
+/** 鸭子类型判断（不用 instanceof），兼容插件自带另一份 plugin-sdk 副本的情况。 */
+export declare function isSandboxGoneError(e: unknown): e is SandboxGoneError;
+/**
+ * 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
+ * kill pattern.
+ */
+export declare const SANDBOX_TAG_RE: RegExp;
+/**
+ * `sandbox@1` 的实现（由沙箱插件提供，如 Docker、E2B）。
+ * 实例确定不在时：`resume` 返回 `gone`；`exec` / `readFile` / `writeFile` / `stat` 抛 {@link SandboxGoneError}；
+ * `suspend` / `destroy` 照常成功。
+ *
+ * **自动启动**：实例还在、但已停止 / 暂停（被内核之外的原因停掉：宿主机重启、守护进程重启、沙箱里的进程把
+ * 自己的 init 弄停了、休眠扫描停了实例却没来得及记下 `suspended`……）时，`exec` / `readFile` / `writeFile` /
+ * `stat` 必须先透明地把它启动起来（同 `resume`，文件保留）再执行，而不是报错——内核只信自己记的 `running`。
+ *
+ * **命令时限在沙箱里也要生效**：`exec` 除了在提供方这边按 `timeoutMs` 停掉命令，还必须让沙箱里的命令自己在
+ * `timeoutMs` 之后不久（几秒的余量）被杀掉。内核副本崩溃时提供方这边的计时随之消失，断开连接也不会结束命令；
+ * 沙箱里的时限保证它不会无限期地与下一个持锁方的命令同时运行。
+ *
+ * **中止**：每个方法都必须及时响应 `signal`（已中止就立即失败，进行中被中止就尽快以中止原因结束）——内核在锁丢失、
+ * 运行被中止或超时时靠它停下，不响应就可能与新的持锁方同时操作同一实例。`exec` 被中止时必须杀掉正在跑的命令
+ * （连同它派生的进程），而不只是不再等待它的输出；命令启动后才被中止的 `exec` 以 `exitCode: null`、
+ * `timedOut: false` 正常 resolve（带上已收集的输出），不 reject。调用时 signal 已中止则立即 reject。
+ *
+ * **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).
+ */
+export interface SandboxProvider {
+    /**
+     * Declares that `exec` / `readFile` / `writeFile` / `stat` may run concurrently on one instance
+     * (see the contract above). Requires {@link SandboxProvider.killTagged}.
+     */
+    readonly concurrentExec?: boolean;
+    /** `name` 形如 `cap-<conversationId>`。 */
+    create(args: {
+        name: string;
+        image: string;
+        limits: SandboxLimits;
+        signal: AbortSignal;
+    }): Promise<SandboxHandle>;
+    /** `gone` 表示提供方那边已经没有这个实例。 */
+    resume(h: SandboxHandle, signal: AbortSignal): Promise<"resumed" | "gone">;
+    /** 文件必须保留。实例不存在也算成功。 */
+    suspend(h: SandboxHandle, signal: AbortSignal): Promise<void>;
+    /** 不存在也算成功。 */
+    destroy(h: SandboxHandle, signal: AbortSignal): Promise<void>;
+    /**
+     * 可选：按 `create` 时的 `name`（`cap-<conversationId>`）销毁实例，不存在也算成功。
+     * 内核在拿不到句柄时用它清理（例如 `create` 已在提供方那边完成、内核却在记下句柄前退出）。
+     */
+    destroyByName?(name: string, signal: AbortSignal): Promise<void>;
+    /**
+     * 可选：杀掉这个实例里经 `exec` 启动、仍在运行的全部命令（连同它们派生的、没有自己另起会话的进程）。
+     * 内核在接手一个前任持锁方没有正常结束的沙箱（前任崩溃）时、第一次执行前调用，清掉前任遗留的命令；
+     * 命令自己放到后台、另起会话的进程不保证被杀。实例已停止时同样先启动；不在时抛 {@link SandboxGoneError}。
+     */
+    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.
+     */
+    killTagged?(h: SandboxHandle, tags: string[], signal: AbortSignal): Promise<void>;
+    /**
+     * 执行一条命令。`maxOutputBytes` 是 stdout 与 stderr **合计**最多收集的字节，超出的丢弃、`truncated` 为 true。
+     */
+    exec(h: SandboxHandle, args: {
+        command: string;
+        cwd?: string;
+        env?: Record<string, string>;
+        timeoutMs: number;
+        maxOutputBytes: number;
+        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.
+         */
+        tag?: string;
+    }): Promise<ExecResult>;
+    /** 读文件（最多 `maxBytes` 字节，更长的截断、`truncated` 为 true）。不存在、或是目录时返回 null。 */
+    readFile(h: SandboxHandle, path: string, opts: {
+        maxBytes: number;
+        signal: AbortSignal;
+    }): Promise<{
+        data: Uint8Array;
+        truncated: boolean;
+    } | null>;
+    /** 父目录自动创建。 */
+    writeFile(h: SandboxHandle, path: string, data: Uint8Array, signal: AbortSignal): Promise<void>;
+    stat(h: SandboxHandle, path: string, signal: AbortSignal): Promise<{
+        size: number;
+        isDir: boolean;
+    } | null>;
+}
+/** 校验沙箱内路径：返回错误列表，空数组表示合法。 */
+export declare function validateSandboxPath(p: string): string[];
+/** 校验出站白名单主机名：小写、无协议与端口、可选前导 `*.`、IDN 只认 punycode。 */
+export declare function validateAllowHost(h: string): string[];