@ottimis/jack-provider-sdk 0.7.0 → 0.10.0

package/dist/cjs/index.js

@@ -48,4 +48,5 @@ __exportStar(require("./provider"), exports);
 __exportStar(require("./usage"), exports);
 __exportStar(require("./host"), exports);
 __exportStar(require("./profiles"), exports);
+__exportStar(require("./sandbox"), exports);
 //# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;;;;;;;;;;;;;;;;AAEH,4CAAyB;AACzB,4CAAyB;AACzB,6CAA0B;AAC1B,0CAAuB;AACvB,yCAAsB;AACtB,6CAA0B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;;;;;;;;;;;;;;;;AAEH,4CAAyB;AACzB,4CAAyB;AACzB,6CAA0B;AAC1B,0CAAuB;AACvB,yCAAsB;AACtB,6CAA0B;AAC1B,4CAAyB"}

package/dist/cjs/sandbox.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * SandboxApi — provider-declared Docker sandbox capability.
+ *
+ * Jack runs sessions in a Docker container ("sandbox mode") to isolate the
+ * provider's CLI from the host filesystem and network. The container itself
+ * is generic — Jack owns the Docker orchestration, security policy (CapDrop,
+ * memory cap, non-privileged), project mount, and user-defined shared
+ * volumes. The PROVIDER-SPECIFIC bits live here:
+ *
+ *   - which image to pull (each provider needs its own CLI installed)
+ *   - which binary name to invoke inside the container (used by the host to
+ *     rewrite host-resolved absolute paths like
+ *     `/Users/foo/.local/bin/claude` to a bare command the container's
+ *     PATH resolves)
+ *   - which config dir to mount (`~/.claude`, `~/.codex`, `~/.gemini`, …)
+ *   - optional env extras
+ *
+ * A provider declaring `sandbox` opts itself into sandbox mode. The
+ * matching capability flag {@link CapabilityMatrix.sandbox} MUST be `true`
+ * — the host derives it from `provider.sandbox != null` at registration.
+ *
+ * Providers that don't declare `sandbox` (or set it to `undefined`) are
+ * treated as sandbox-incompatible: the host hides the toggle in the UI and
+ * blocks spawn-time requests with a clear error.
+ *
+ * The host's distribution model expects images at
+ * `ghcr.io/ottimis/jack-sandbox-<provider-id>:<X.Y.Z>` (monorepo
+ * `github.com/ottimis/JACK-sandbox`). Providers can point `defaultImage`
+ * elsewhere — third-party plugin authors who maintain their own image are
+ * free to host wherever they like.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=sandbox.js.map

package/dist/cjs/sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.js","sourceRoot":"","sources":["../../src/sandbox.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG"}

package/dist/index.d.ts

@@ -32,6 +32,7 @@ export * from './provider';
 export * from './usage';
 export * from './host';
 export * from './profiles';
+export * from './sandbox';
 /**
  * Re-export of `NormalizedMessage` from chat-core so consumers don't need
  * to depend on it directly when their only entrypoint into the wire shape

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,QAAQ,CAAA;AACtB,cAAc,YAAY,CAAA;AAE1B;;;;;GAKG;AACH,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,QAAQ,CAAA;AACtB,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AAEzB;;;;;GAKG;AACH,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA"}

package/dist/index.js

@@ -32,4 +32,5 @@ export * from './provider';
 export * from './usage';
 export * from './host';
 export * from './profiles';
+export * from './sandbox';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,QAAQ,CAAA;AACtB,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,QAAQ,CAAA;AACtB,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA"}

package/dist/provider.d.ts

@@ -18,6 +18,7 @@
 import type { AgentBackend, AgentPermissionMode, AgentQueryOptions, McpServerSpec } from './backend';
 import type { HostServices } from './host';
 import type { ProfilesApi } from './profiles';
+import type { SandboxApi } from './sandbox';
 import type { UsageApi } from './usage';
 import type { ZodType } from 'zod';
 import type { ClientToolHandler, NormalizedMessage, NormalizedToolRef, ProviderUserContentPolicy, ToolShape } from '@ottimis/jack-chat-core';
@@ -270,6 +271,17 @@ export type CapabilityMatrix = {
      * config dir; the host hides every profile-related affordance.
      */
     profiles: boolean;
+    /**
+     * Provider can run inside Jack's Docker sandbox. When `true`,
+     * {@link JackProvider.sandbox} MUST be defined; the host enables the
+     * sandbox toggle in the new-session dialog and renders an entry for this
+     * provider in `Settings → Sandbox`.
+     *
+     * When `false` (or omitted), sandbox mode is unavailable for this
+     * provider — the toggle is hidden / disabled in the UI, and a spawn-time
+     * sandbox request returns a clear error.
+     */
+    sandbox: boolean;
     /**
      * Permission modes the provider actually supports. Drives the
      * Shift-Tab cycle in the renderer (`MessageInputBar`) and any
@@ -288,6 +300,23 @@ export type CapabilityMatrix = {
      * or settings); the catalog only governs UI affordances.
      */
     permissionModes: readonly AgentPermissionMode[];
+    /**
+     * Suggested prompt-cache TTL in milliseconds — how long the provider's
+     * server-side prompt cache stays warm between user turns before a new
+     * cache-write is required. Optional: providers without prompt caching
+     * (or without a documented TTL) leave it undefined and the host hides
+     * the cache-countdown chip entirely for sessions on that provider.
+     *
+     * This is only the **suggested default**: the user can override per
+     * provider in `Settings → Prompt cache` and disable the chip outright.
+     * The host treats this as a UI-only countdown hint — never as a
+     * contract for actual cache eviction (the provider is the source of
+     * truth at request time).
+     *
+     * Claude declares 300_000 (5 min) per its prompt-caching docs. Codex
+     * and Gemini leave it undefined.
+     */
+    cacheTtlMs?: number;
 };
 /**
  * Re-exports of canonical wire-shape types from chat-core so consumers of
@@ -645,6 +674,14 @@ export type JackProvider = {
      * Codex `CODEX_HOME`, …).
      */
     profiles?: ProfilesApi;
+    /**
+     * Docker sandbox capability — provider declares the image, binary name,
+     * and config-dir mount the host needs to spawn a sandboxed session for
+     * this provider. See {@link SandboxApi}. Optional; when undefined
+     * `capabilities.sandbox` MUST be `false` and the host disables sandbox
+     * mode for this provider's sessions.
+     */
+    sandbox?: SandboxApi;
     /**
      * Optional one-shot activation hook. Called once by the host during
      * registration with a {@link HostServices} bag scoped to this

package/dist/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"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"}

package/dist/sandbox.d.ts

@@ -0,0 +1,116 @@
+/**
+ * SandboxApi — provider-declared Docker sandbox capability.
+ *
+ * Jack runs sessions in a Docker container ("sandbox mode") to isolate the
+ * provider's CLI from the host filesystem and network. The container itself
+ * is generic — Jack owns the Docker orchestration, security policy (CapDrop,
+ * memory cap, non-privileged), project mount, and user-defined shared
+ * volumes. The PROVIDER-SPECIFIC bits live here:
+ *
+ *   - which image to pull (each provider needs its own CLI installed)
+ *   - which binary name to invoke inside the container (used by the host to
+ *     rewrite host-resolved absolute paths like
+ *     `/Users/foo/.local/bin/claude` to a bare command the container's
+ *     PATH resolves)
+ *   - which config dir to mount (`~/.claude`, `~/.codex`, `~/.gemini`, …)
+ *   - optional env extras
+ *
+ * A provider declaring `sandbox` opts itself into sandbox mode. The
+ * matching capability flag {@link CapabilityMatrix.sandbox} MUST be `true`
+ * — the host derives it from `provider.sandbox != null` at registration.
+ *
+ * Providers that don't declare `sandbox` (or set it to `undefined`) are
+ * treated as sandbox-incompatible: the host hides the toggle in the UI and
+ * blocks spawn-time requests with a clear error.
+ *
+ * The host's distribution model expects images at
+ * `ghcr.io/ottimis/jack-sandbox-<provider-id>:<X.Y.Z>` (monorepo
+ * `github.com/ottimis/JACK-sandbox`). Providers can point `defaultImage`
+ * elsewhere — third-party plugin authors who maintain their own image are
+ * free to host wherever they like.
+ */
+/**
+ * Mount a provider-side config artifact (directory or file) into the
+ * container. Most providers persist auth + sessions + per-user settings in
+ * a dotfile dir under `$HOME` (Claude `~/.claude`, Codex `~/.codex`,
+ * Gemini `~/.gemini`); some additionally need a sibling config file
+ * mounted alongside (Claude `~/.claude.json` is a good example — the CLI
+ * reads it as the "main config" separate from the dotfile dir). The host
+ * mounts each entry into the container at {@link containerPath} so the CLI
+ * inside the container has access to the same state as the host.
+ *
+ * Read-only is recommended whenever the provider's CLI doesn't genuinely
+ * need to mutate state. Set `readOnly: false` when the CLI writes back —
+ * Claude writes session-env, project history, MCP additions; Codex appends
+ * thread JSONL; etc. The trade-off when RW is enabled: sandbox sessions
+ * share the same on-disk state as the host CLI (history, project state,
+ * MCP edits). If you need credential isolation, build a copy-on-write
+ * scratch volume — the {@link SandboxApi} contract doesn't impose one.
+ */
+export type SandboxConfigMount = {
+    /**
+     * Absolute host path. Provider implementations resolve this lazily — call
+     * `os.homedir()` + `path.join(...)` at the time `configMounts` is read,
+     * not at module-load time, so test environments and per-process HOME
+     * overrides work correctly. May point to either a directory or a single
+     * file — Docker's bind mount accepts both.
+     */
+    hostPath: string;
+    /** Absolute container path. */
+    containerPath: string;
+    /** When `true`, the host adds `:ro` to the bind. */
+    readOnly: boolean;
+};
+/**
+ * Provider-declared Docker sandbox capability. Optional on
+ * {@link JackProvider}; when present the matching
+ * {@link CapabilityMatrix.sandbox} flag MUST be `true`.
+ */
+export interface SandboxApi {
+    /**
+     * Default image reference, pinned per provider release. Format:
+     * `<registry>/<repo>:<tag>`. Users can override per-provider via the host
+     * setting `sandbox.image.<providerId>`.
+     *
+     * For Jack's first-party providers the recommended location is
+     * `ghcr.io/ottimis/jack-sandbox-<providerId>:<X.Y.Z>` (monorepo built
+     * from `github.com/ottimis/JACK-sandbox`). Third-party plugins are free
+     * to host elsewhere.
+     */
+    readonly defaultImage: string;
+    /**
+     * CLI binary name as it should be invoked inside the container (e.g.
+     * `'claude'`, `'codex'`, `'gemini'`). Used by the host's spawner to
+     * rewrite host-resolved absolute binary paths to a bare command the
+     * container's PATH resolves.
+     *
+     * The image MUST install this binary at a location reachable from
+     * `$PATH` (typically `/usr/local/bin/<binaryName>` via `npm install -g`).
+     */
+    readonly binaryName: string;
+    /**
+     * Mount provider-side config artifacts (directories and/or files) into
+     * the container. Optional — providers that are stateless on the host
+     * (none today) leave this undefined or pass an empty array.
+     *
+     * Multiple entries support providers whose CLI splits state across more
+     * than one path (e.g. Claude needs both `~/.claude/` for the dotfile dir
+     * and `~/.claude.json` for the main config file). Order is preserved
+     * but mounts are independent — if two entries overlap, Docker resolves
+     * them in declaration order.
+     */
+    readonly configMounts?: readonly SandboxConfigMount[];
+    /**
+     * Optional environment extras to inject into the container. Layered AFTER
+     * the spawn-arg env so provider-specific overrides can win, but BEFORE
+     * the user can override (the user-facing override is per-provider via
+     * the host setting, not per-env-var).
+     *
+     * Most provider env is already on `SpawnArgs.env` from the backend's
+     * spawn pipeline. Use this only when the SDK contract doesn't expose a
+     * cleaner channel — e.g. forcing a CLI to disable telemetry inside the
+     * sandbox even when the user has it on globally.
+     */
+    envExtras?(): Record<string, string>;
+}
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;;;;;OAMG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB,+BAA+B;IAC/B,aAAa,EAAE,MAAM,CAAA;IACrB,oDAAoD;IACpD,QAAQ,EAAE,OAAO,CAAA;CAClB,CAAA;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB;;;;;;;;;OASG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAE7B;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAE3B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAErD;;;;;;;;;;OAUG;IACH,SAAS,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACrC"}

package/dist/sandbox.js

@@ -0,0 +1,33 @@
+/**
+ * SandboxApi — provider-declared Docker sandbox capability.
+ *
+ * Jack runs sessions in a Docker container ("sandbox mode") to isolate the
+ * provider's CLI from the host filesystem and network. The container itself
+ * is generic — Jack owns the Docker orchestration, security policy (CapDrop,
+ * memory cap, non-privileged), project mount, and user-defined shared
+ * volumes. The PROVIDER-SPECIFIC bits live here:
+ *
+ *   - which image to pull (each provider needs its own CLI installed)
+ *   - which binary name to invoke inside the container (used by the host to
+ *     rewrite host-resolved absolute paths like
+ *     `/Users/foo/.local/bin/claude` to a bare command the container's
+ *     PATH resolves)
+ *   - which config dir to mount (`~/.claude`, `~/.codex`, `~/.gemini`, …)
+ *   - optional env extras
+ *
+ * A provider declaring `sandbox` opts itself into sandbox mode. The
+ * matching capability flag {@link CapabilityMatrix.sandbox} MUST be `true`
+ * — the host derives it from `provider.sandbox != null` at registration.
+ *
+ * Providers that don't declare `sandbox` (or set it to `undefined`) are
+ * treated as sandbox-incompatible: the host hides the toggle in the UI and
+ * blocks spawn-time requests with a clear error.
+ *
+ * The host's distribution model expects images at
+ * `ghcr.io/ottimis/jack-sandbox-<provider-id>:<X.Y.Z>` (monorepo
+ * `github.com/ottimis/JACK-sandbox`). Providers can point `defaultImage`
+ * elsewhere — third-party plugin authors who maintain their own image are
+ * free to host wherever they like.
+ */
+export {};
+//# sourceMappingURL=sandbox.js.map

package/dist/sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.js","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ottimis/jack-provider-sdk",
-  "version": "0.7.0",
+  "version": "0.10.0",
   "description": "Plugin contract for AI provider integrations in Jack — backend interface, capability matrix, spawner primitives, knowledge context. Consumed both by in-tree providers and external packages.",
   "license": "MIT",
   "repository": {

package/src/index.ts

@@ -33,6 +33,7 @@ export * from './provider'
 export * from './usage'
 export * from './host'
 export * from './profiles'
+export * from './sandbox'
 
 /**
  * Re-export of `NormalizedMessage` from chat-core so consumers don't need

package/src/provider.ts

@@ -19,6 +19,7 @@
 import type { AgentBackend, AgentPermissionMode, AgentQueryOptions, McpServerSpec } from './backend'
 import type { HostServices } from './host'
 import type { ProfilesApi } from './profiles'
+import type { SandboxApi } from './sandbox'
 import type { UsageApi } from './usage'
 import type { ZodType } from 'zod'
 import type {
@@ -286,6 +287,17 @@ export type CapabilityMatrix = {
    * config dir; the host hides every profile-related affordance.
    */
   profiles: boolean
+  /**
+   * Provider can run inside Jack's Docker sandbox. When `true`,
+   * {@link JackProvider.sandbox} MUST be defined; the host enables the
+   * sandbox toggle in the new-session dialog and renders an entry for this
+   * provider in `Settings → Sandbox`.
+   *
+   * When `false` (or omitted), sandbox mode is unavailable for this
+   * provider — the toggle is hidden / disabled in the UI, and a spawn-time
+   * sandbox request returns a clear error.
+   */
+  sandbox: boolean
   /**
    * Permission modes the provider actually supports. Drives the
    * Shift-Tab cycle in the renderer (`MessageInputBar`) and any
@@ -304,6 +316,23 @@ export type CapabilityMatrix = {
    * or settings); the catalog only governs UI affordances.
    */
   permissionModes: readonly AgentPermissionMode[]
+  /**
+   * Suggested prompt-cache TTL in milliseconds — how long the provider's
+   * server-side prompt cache stays warm between user turns before a new
+   * cache-write is required. Optional: providers without prompt caching
+   * (or without a documented TTL) leave it undefined and the host hides
+   * the cache-countdown chip entirely for sessions on that provider.
+   *
+   * This is only the **suggested default**: the user can override per
+   * provider in `Settings → Prompt cache` and disable the chip outright.
+   * The host treats this as a UI-only countdown hint — never as a
+   * contract for actual cache eviction (the provider is the source of
+   * truth at request time).
+   *
+   * Claude declares 300_000 (5 min) per its prompt-caching docs. Codex
+   * and Gemini leave it undefined.
+   */
+  cacheTtlMs?: number
 }
 
 /**
@@ -699,6 +728,14 @@ export type JackProvider = {
    * Codex `CODEX_HOME`, …).
    */
   profiles?: ProfilesApi
+  /**
+   * Docker sandbox capability — provider declares the image, binary name,
+   * and config-dir mount the host needs to spawn a sandboxed session for
+   * this provider. See {@link SandboxApi}. Optional; when undefined
+   * `capabilities.sandbox` MUST be `false` and the host disables sandbox
+   * mode for this provider's sessions.
+   */
+  sandbox?: SandboxApi
   /**
    * Optional one-shot activation hook. Called once by the host during
    * registration with a {@link HostServices} bag scoped to this

package/src/sandbox.ts

@@ -0,0 +1,120 @@
+/**
+ * SandboxApi — provider-declared Docker sandbox capability.
+ *
+ * Jack runs sessions in a Docker container ("sandbox mode") to isolate the
+ * provider's CLI from the host filesystem and network. The container itself
+ * is generic — Jack owns the Docker orchestration, security policy (CapDrop,
+ * memory cap, non-privileged), project mount, and user-defined shared
+ * volumes. The PROVIDER-SPECIFIC bits live here:
+ *
+ *   - which image to pull (each provider needs its own CLI installed)
+ *   - which binary name to invoke inside the container (used by the host to
+ *     rewrite host-resolved absolute paths like
+ *     `/Users/foo/.local/bin/claude` to a bare command the container's
+ *     PATH resolves)
+ *   - which config dir to mount (`~/.claude`, `~/.codex`, `~/.gemini`, …)
+ *   - optional env extras
+ *
+ * A provider declaring `sandbox` opts itself into sandbox mode. The
+ * matching capability flag {@link CapabilityMatrix.sandbox} MUST be `true`
+ * — the host derives it from `provider.sandbox != null` at registration.
+ *
+ * Providers that don't declare `sandbox` (or set it to `undefined`) are
+ * treated as sandbox-incompatible: the host hides the toggle in the UI and
+ * blocks spawn-time requests with a clear error.
+ *
+ * The host's distribution model expects images at
+ * `ghcr.io/ottimis/jack-sandbox-<provider-id>:<X.Y.Z>` (monorepo
+ * `github.com/ottimis/JACK-sandbox`). Providers can point `defaultImage`
+ * elsewhere — third-party plugin authors who maintain their own image are
+ * free to host wherever they like.
+ */
+
+/**
+ * Mount a provider-side config artifact (directory or file) into the
+ * container. Most providers persist auth + sessions + per-user settings in
+ * a dotfile dir under `$HOME` (Claude `~/.claude`, Codex `~/.codex`,
+ * Gemini `~/.gemini`); some additionally need a sibling config file
+ * mounted alongside (Claude `~/.claude.json` is a good example — the CLI
+ * reads it as the "main config" separate from the dotfile dir). The host
+ * mounts each entry into the container at {@link containerPath} so the CLI
+ * inside the container has access to the same state as the host.
+ *
+ * Read-only is recommended whenever the provider's CLI doesn't genuinely
+ * need to mutate state. Set `readOnly: false` when the CLI writes back —
+ * Claude writes session-env, project history, MCP additions; Codex appends
+ * thread JSONL; etc. The trade-off when RW is enabled: sandbox sessions
+ * share the same on-disk state as the host CLI (history, project state,
+ * MCP edits). If you need credential isolation, build a copy-on-write
+ * scratch volume — the {@link SandboxApi} contract doesn't impose one.
+ */
+export type SandboxConfigMount = {
+  /**
+   * Absolute host path. Provider implementations resolve this lazily — call
+   * `os.homedir()` + `path.join(...)` at the time `configMounts` is read,
+   * not at module-load time, so test environments and per-process HOME
+   * overrides work correctly. May point to either a directory or a single
+   * file — Docker's bind mount accepts both.
+   */
+  hostPath: string
+  /** Absolute container path. */
+  containerPath: string
+  /** When `true`, the host adds `:ro` to the bind. */
+  readOnly: boolean
+}
+
+/**
+ * Provider-declared Docker sandbox capability. Optional on
+ * {@link JackProvider}; when present the matching
+ * {@link CapabilityMatrix.sandbox} flag MUST be `true`.
+ */
+export interface SandboxApi {
+  /**
+   * Default image reference, pinned per provider release. Format:
+   * `<registry>/<repo>:<tag>`. Users can override per-provider via the host
+   * setting `sandbox.image.<providerId>`.
+   *
+   * For Jack's first-party providers the recommended location is
+   * `ghcr.io/ottimis/jack-sandbox-<providerId>:<X.Y.Z>` (monorepo built
+   * from `github.com/ottimis/JACK-sandbox`). Third-party plugins are free
+   * to host elsewhere.
+   */
+  readonly defaultImage: string
+
+  /**
+   * CLI binary name as it should be invoked inside the container (e.g.
+   * `'claude'`, `'codex'`, `'gemini'`). Used by the host's spawner to
+   * rewrite host-resolved absolute binary paths to a bare command the
+   * container's PATH resolves.
+   *
+   * The image MUST install this binary at a location reachable from
+   * `$PATH` (typically `/usr/local/bin/<binaryName>` via `npm install -g`).
+   */
+  readonly binaryName: string
+
+  /**
+   * Mount provider-side config artifacts (directories and/or files) into
+   * the container. Optional — providers that are stateless on the host
+   * (none today) leave this undefined or pass an empty array.
+   *
+   * Multiple entries support providers whose CLI splits state across more
+   * than one path (e.g. Claude needs both `~/.claude/` for the dotfile dir
+   * and `~/.claude.json` for the main config file). Order is preserved
+   * but mounts are independent — if two entries overlap, Docker resolves
+   * them in declaration order.
+   */
+  readonly configMounts?: readonly SandboxConfigMount[]
+
+  /**
+   * Optional environment extras to inject into the container. Layered AFTER
+   * the spawn-arg env so provider-specific overrides can win, but BEFORE
+   * the user can override (the user-facing override is per-provider via
+   * the host setting, not per-env-var).
+   *
+   * Most provider env is already on `SpawnArgs.env` from the backend's
+   * spawn pipeline. Use this only when the SDK contract doesn't expose a
+   * cleaner channel — e.g. forcing a CLI to disable telemetry inside the
+   * sandbox even when the user has it on globally.
+   */
+  envExtras?(): Record<string, string>
+}