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

package/dist/file-preview.d.ts

@@ -53,6 +53,14 @@ export interface FilePreviewArgs {
      * rejects a file over the previewer's `maxBytes`. The extension never gets a storage key or URL.
      */
     read(): Promise<Uint8Array>;
+    /**
+     * 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;
 }
 /** Checks a `file-preview@1` provider; returns the problems (empty = valid). */
 export declare function validateFilePreviewProvider(p: unknown): string[];

package/dist/hooks.d.ts

@@ -169,9 +169,18 @@ export type HookVerdict = void | {
 };
 /**
  * A hook handler. The payload is a deep-frozen copy (mutating it throws). `signal` aborts when the
- * hook runs past `hooks.timeoutMs` or the call it observes is aborted.
+ * hook runs past `hooks.timeoutMs` or the call it observes is aborted. `call.config` is the
+ * extension's effective deployment config for the payload's org (the platform's config with the
+ * org's copy applied to the overridable fields, or `ctx.config` while the org follows it); the
+ * kernel always passes it, and never calls a hook for an org where that config is not valid
+ * (observe hooks are skipped, policy hooks deny).
  */
-export type HookHandler<K extends AvailableHook> = (payload: HookPayloads[K], signal: AbortSignal) => Promise<HookVerdict> | HookVerdict;
+export type HookHandler<K extends AvailableHook> = (payload: HookPayloads[K], signal: AbortSignal, call?: HookCall) => Promise<HookVerdict> | HookVerdict;
+/** The per-call context of a hook handler (see {@link HookHandler}). */
+export interface HookCall {
+    /** The extension's effective deployment config for the payload's org. */
+    config: unknown;
+}
 /**
  * - `policy` (only on {@link POLICY_HOOKS}): policy hooks run serially by plugin name (registration
  *   order within a plugin) before the call; the first `{ deny }`, error or timeout blocks the call and

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const SDK_VERSION = "0.1.0-rc.2";
+export declare const SDK_VERSION = "0.1.0-rc.3";
 export * from "./agent-template.js";
 export * from "./bootstrap.js";
 export * from "./cards.js";
@@ -16,6 +16,7 @@ export * from "./identity.js";
 export * from "./marketplace.js";
 export * from "./model.js";
 export * from "./model-params.js";
+export * from "./org-access.js";
 export * from "./permissions.js";
 export * from "./plugin-manifest.js";
 export * from "./plugin-package.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export const SDK_VERSION = "0.1.0-rc.2";
+export const SDK_VERSION = "0.1.0-rc.3";
 export * from "./agent-template.js";
 export * from "./bootstrap.js";
 export * from "./cards.js";
@@ -16,6 +16,7 @@ export * from "./identity.js";
 export * from "./marketplace.js";
 export * from "./model.js";
 export * from "./model-params.js";
+export * from "./org-access.js";
 export * from "./permissions.js";
 export * from "./plugin-manifest.js";
 export * from "./plugin-package.js";

package/dist/marketplace.d.ts

@@ -1,8 +1,10 @@
 import { z } from "zod";
 /**
  * The marketplace manifest `marketplace.json` (package ecosystem spec §5.2): a list of plugins,
- * each with one source. One entry is one version: a marketplace that offers several versions lists
- * the plugin once per version, so `(name, marketplaceEntryVersion)` is unique in a manifest.
+ * each with one source. One entry is one version. `capybara-plugin marketplace --write` lists one
+ * entry per plugin, its current version (plugin component management spec §13.2); readers still
+ * accept several versions of a plugin (marketplaces written in the older form), so
+ * `(name, marketplaceEntryVersion)` is unique in a manifest.
  *
  * Sources: a same-repo `path`, a `git` repo, an `npm` package (exact version + sha512, downloads
  * are verified against it, never npm metadata) or an `archive` URL (sha512 or sha256 SRI).
@@ -19,6 +21,10 @@ export declare const MARKETPLACE_MANIFEST_SCHEMA_VERSION = 1;
 export declare const MARKETPLACE_LIMITS: {
     readonly nameChars: 100;
     readonly summaryChars: 280;
+    /** Characters of each `displayName` language (as `plugin.json`'s). */
+    readonly displayNameChars: 100;
+    /** Characters of a `deprecated.reason`. */
+    readonly deprecationReasonChars: 280;
     readonly plugins: 5000;
     readonly permissionKeys: 500;
     readonly urlChars: 2000;
@@ -53,6 +59,11 @@ export interface MarketplaceEntry {
         en: string;
         zh?: string;
     };
+    /** Display name (the plugin's `plugin.json` `displayName`); lists show it, else the name. */
+    displayName?: {
+        zh: string;
+        en: string;
+    };
     /** Exact semver; defaults to the npm source's version, otherwise the plugin's own. */
     version?: string;
     /** Exact semver. */
@@ -64,6 +75,15 @@ export interface MarketplaceEntry {
     };
     /** https URL. */
     homepage?: string;
+    /**
+     * This version is deprecated (`true`, or with a reason shown to admins): browsing lists it under
+     * the plugin's other versions, never as the one to import, and the kernel refuses importing it
+     * (`marketplace.entry_deprecated`). Set by hand on the entry by the marketplace maintainer;
+     * `capybara-plugin marketplace --write` keeps it. `false` is the same as absent.
+     */
+    deprecated?: boolean | {
+        reason?: string;
+    };
     source: MarketplaceSource;
 }
 /** `marketplace.json`. */
@@ -97,3 +117,10 @@ export declare function parseMarketplaceManifest(json: unknown, opts?: Marketpla
 };
 /** The entry's version: `version`, else the npm source's version, else `null` (the plugin's own). */
 export declare function marketplaceEntryVersion(e: MarketplaceEntry): string | null;
+/**
+ * The entry's deprecation (see {@link MarketplaceEntry.deprecated}): `null` when it is not
+ * deprecated (absent or `false`), else its reason (`null` without one).
+ */
+export declare function marketplaceEntryDeprecation(e: MarketplaceEntry): {
+    reason: string | null;
+} | null;

package/dist/marketplace.js

@@ -2,8 +2,10 @@ import { z } from "zod";
 import { CATALOG_ITEM_NAME_RE, isSafePackagePath, NPM_PACKAGE_NAME_RE, SEMVER_VERSION_RE, SHA512_INTEGRITY_RE, } from "./plugin-package.js";
 /**
  * The marketplace manifest `marketplace.json` (package ecosystem spec §5.2): a list of plugins,
- * each with one source. One entry is one version: a marketplace that offers several versions lists
- * the plugin once per version, so `(name, marketplaceEntryVersion)` is unique in a manifest.
+ * each with one source. One entry is one version. `capybara-plugin marketplace --write` lists one
+ * entry per plugin, its current version (plugin component management spec §13.2); readers still
+ * accept several versions of a plugin (marketplaces written in the older form), so
+ * `(name, marketplaceEntryVersion)` is unique in a manifest.
  *
  * Sources: a same-repo `path`, a `git` repo, an `npm` package (exact version + sha512, downloads
  * are verified against it, never npm metadata) or an `archive` URL (sha512 or sha256 SRI).
@@ -20,6 +22,10 @@ export const MARKETPLACE_MANIFEST_SCHEMA_VERSION = 1;
 export const MARKETPLACE_LIMITS = {
     nameChars: 100,
     summaryChars: 280,
+    /** Characters of each `displayName` language (as `plugin.json`'s). */
+    displayNameChars: 100,
+    /** Characters of a `deprecated.reason`. */
+    deprecationReasonChars: 280,
     plugins: 5000,
     permissionKeys: 500,
     urlChars: 2000,
@@ -123,6 +129,12 @@ function buildSchema(opts) {
             en: z.string().min(1).max(M.summaryChars),
             zh: z.string().min(1).max(M.summaryChars).optional(),
         }),
+        displayName: z
+            .object({
+            zh: z.string().min(1).max(M.displayNameChars),
+            en: z.string().min(1).max(M.displayNameChars),
+        })
+            .optional(),
         version: exactVersion("version").optional(),
         minKernel: exactVersion("minKernel").optional(),
         permissions: z
@@ -132,6 +144,12 @@ function buildSchema(opts) {
         })
             .optional(),
         homepage: urlString(HTTPS_URL_RE).optional(),
+        deprecated: z
+            .union([
+            z.boolean(),
+            z.object({ reason: z.string().min(1).max(M.deprecationReasonChars).optional() }),
+        ])
+            .optional(),
         source,
     });
     return z
@@ -254,3 +272,13 @@ export function marketplaceEntryVersion(e) {
         return e.source.npm.version;
     return null;
 }
+/**
+ * The entry's deprecation (see {@link MarketplaceEntry.deprecated}): `null` when it is not
+ * deprecated (absent or `false`), else its reason (`null` without one).
+ */
+export function marketplaceEntryDeprecation(e) {
+    const d = e.deprecated;
+    if (d === undefined || d === false)
+        return null;
+    return { reason: d === true ? null : (d.reason ?? null) };
+}

package/dist/org-access.d.ts

@@ -0,0 +1,27 @@
+import type { z } from "zod";
+/**
+ * How an org may treat a deployment config field: `readonly` (the org sees it, never sets it) or
+ * `override` (an org may set its own value). A field without a level is deployment-only.
+ */
+export type OrgAccess = "readonly" | "override";
+/**
+ * Marks a deployment config field with an org access level (Zod 4 meta `{ org: access }`), merging
+ * with existing meta (`secret`, `hot`, `ui`), so `orgAccess(secret(x), …)` and
+ * `secret(orgAccess(x, …))` are the same. `configJsonSchema` publishes it as `"x-org"`.
+ *
+ * The author's promise for `override`: the extension reads the field from the per-call `config`
+ * the kernel passes with each request, not from `ctx.config`, and the field may be absent from
+ * `ctx.config` (the deployment value is the default, which an org may replace per call).
+ *
+ * The per-call config of an org that has its own copy still contains the platform's hidden
+ * (platform-only) secrets, which an org cannot set; it never contains an overridable platform
+ * secret. Never send a hidden secret to an endpoint taken from an overridable field: an org could
+ * point that endpoint at a server it controls.
+ */
+export declare function orgAccess<T extends z.ZodTypeAny>(schema: T, access: OrgAccess): T;
+/**
+ * The org access level of a schema's meta, or undefined when it has none. It sees through
+ * `.optional()`, `.default()`, `.nullable()`, `.prefault()`, `.catch()` and `.readonly()` (the
+ * outermost level wins), so it agrees with the `"x-org"` that `configJsonSchema` publishes.
+ */
+export declare function orgAccessOf(schema: z.ZodTypeAny): OrgAccess | undefined;

package/dist/org-access.js

@@ -0,0 +1,35 @@
+/**
+ * Marks a deployment config field with an org access level (Zod 4 meta `{ org: access }`), merging
+ * with existing meta (`secret`, `hot`, `ui`), so `orgAccess(secret(x), …)` and
+ * `secret(orgAccess(x, …))` are the same. `configJsonSchema` publishes it as `"x-org"`.
+ *
+ * The author's promise for `override`: the extension reads the field from the per-call `config`
+ * the kernel passes with each request, not from `ctx.config`, and the field may be absent from
+ * `ctx.config` (the deployment value is the default, which an org may replace per call).
+ *
+ * The per-call config of an org that has its own copy still contains the platform's hidden
+ * (platform-only) secrets, which an org cannot set; it never contains an overridable platform
+ * secret. Never send a hidden secret to an endpoint taken from an overridable field: an org could
+ * point that endpoint at a server it controls.
+ */
+export function orgAccess(schema, access) {
+    return schema.meta({ ...(schema.meta() ?? {}), org: access });
+}
+/** The wrappers a field's org level is read through, as `configJsonSchema` inherits meta. */
+const WRAPPERS = new Set(["default", "prefault", "optional", "nullable", "readonly", "catch"]);
+/**
+ * The org access level of a schema's meta, or undefined when it has none. It sees through
+ * `.optional()`, `.default()`, `.nullable()`, `.prefault()`, `.catch()` and `.readonly()` (the
+ * outermost level wins), so it agrees with the `"x-org"` that `configJsonSchema` publishes.
+ */
+export function orgAccessOf(schema) {
+    let node = schema;
+    while (node) {
+        const v = node.meta()?.org;
+        if (v === "readonly" || v === "override")
+            return v;
+        const def = node._zod.def;
+        node = WRAPPERS.has(def.type) ? def.innerType : undefined;
+    }
+    return undefined;
+}

package/dist/plugin-manifest.d.ts

@@ -85,6 +85,19 @@ export interface PluginExtensionSection {
         org?: JsonSchema;
     };
 }
+/**
+ * A plugin's description: a string (English) or `{ en, zh? }`, each ≤ 1024 characters. Read it
+ * through {@link pluginDescription}.
+ */
+export type PluginDescription = string | {
+    en: string;
+    zh?: string;
+};
+/** A plugin description as `{ en, zh? }` (a plain string is the English text). */
+export declare function pluginDescription(d: PluginDescription): {
+    en: string;
+    zh?: string;
+};
 /** `.capybara-plugin/plugin.json`. */
 export interface PluginManifest {
     $schema?: string;
@@ -94,8 +107,8 @@ export interface PluginManifest {
     /** Exact semver version. */
     version: string;
     publisher: string;
-    /** ≤ 1024 characters. */
-    description: string;
+    /** A string (English) or `{ en, zh? }`, each ≤ 1024 characters; see {@link pluginDescription}. */
+    description: PluginDescription;
     displayName?: LocalizedName;
     /** `./…` .svg / .png inside the plugin. */
     icon?: string;

package/dist/plugin-manifest.js

@@ -48,6 +48,10 @@ export const PLUGIN_MANIFEST_LIMITS = {
     displayNameChars: 100,
     pathChars: 512,
 };
+/** A plugin description as `{ en, zh? }` (a plain string is the English text). */
+export function pluginDescription(d) {
+    return typeof d === "string" ? { en: d } : { en: d.en, ...(d.zh !== undefined && { zh: d.zh }) };
+}
 const L = PLUGIN_MANIFEST_LIMITS;
 const MAX_ERRORS = 50;
 const ICON_RE = /\.(?:svg|png)$/i;
@@ -116,7 +120,13 @@ const schema = z
         .max(256)
         .regex(SEMVER_VERSION_RE, { message: "version must be an exact semver version" }),
     publisher: text(L.publisherChars, "publisher"),
-    description: text(L.descriptionChars, "description"),
+    description: z.union([
+        text(L.descriptionChars, "description"),
+        z.strictObject({
+            en: text(L.descriptionChars, "description.en"),
+            zh: text(L.descriptionChars, "description.zh").optional(),
+        }),
+    ]),
     displayName: localized.optional(),
     icon: dotPath("icon")
         .regex(ICON_RE, { message: "icon must be a .svg or .png file" })

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;