@ottimis/jack-provider-sdk 0.10.0 → 0.13.0

package/src/sandbox.ts

@@ -31,36 +31,36 @@
  */
 
 /**
- * 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.
+ * Mount a named Docker volume into the container at {@link containerPath}.
+ * The pattern Anthropic recommends for CLI config dirs (see
+ * https://code.claude.com/docs/en/devcontainer#persist-authentication-and-settings-across-rebuilds):
+ * the volume is auto-created on demand, persists across container
+ * restarts, and isolates writes from the host filesystem entirely.
+ * Best fit for `~/.claude`, `~/.codex`, `~/.gemini` since they hold auth
+ * tokens, session JSONLs, and CLI-mutated settings.
  *
- * 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.
+ * Read-only is recommended whenever the 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.
  */
 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.
+   * Docker volume name. The host auto-creates the volume if missing
+   * (via `docker volume create <name>`). Use a stable, namespaced name
+   * like `jack-sandbox-<provider>-config` so volumes can be inspected
+   * / pruned predictably from the Docker CLI.
+   *
+   * Volumes are NOT scoped per session by default — sharing one volume
+   * across sandbox sessions of the same provider is the common case
+   * and matches Anthropic's reference. If you need per-session
+   * isolation, embed the session id in the name.
    */
-  hostPath: string
+  readonly volumeName: string
   /** Absolute container path. */
-  containerPath: string
+  readonly containerPath: string
   /** When `true`, the host adds `:ro` to the bind. */
-  readOnly: boolean
+  readonly readOnly: boolean
 }
 
 /**
@@ -117,4 +117,54 @@ export interface SandboxApi {
    * sandbox even when the user has it on globally.
    */
   envExtras?(): Record<string, string>
+
+  /**
+   * Optional spawn-time setup hook. Runs once on the host before the
+   * container starts and lets the provider produce per-session artifacts
+   * (e.g. a sanitized `settings.json` with hooks stripped, a generated
+   * MCP manifest) and mount them into the container alongside the static
+   * {@link configMounts}.
+   *
+   * Returned `extraMounts` are appended to {@link configMounts} in
+   * declaration order. The `cleanup` callback (if provided) is invoked
+   * after the container exits so the provider can unlink temp files.
+   *
+   * Errors thrown here propagate as spawn failures — keep the work fast
+   * and synchronous-friendly (file I/O, not network calls).
+   */
+  prepareSpawn?(
+    ctx: SandboxSpawnContext
+  ): SandboxSpawnSetup | Promise<SandboxSpawnSetup>
+}
+
+/**
+ * Context passed to {@link SandboxApi.prepareSpawn}. Identifies the Jack
+ * session and the project root being mounted at `/workspace`. Providers
+ * use these to namespace temp files (one settings overlay per session)
+ * and avoid collisions across concurrent sandbox sessions.
+ */
+export interface SandboxSpawnContext {
+  /** Stable per-session id. Safe to embed in temp filenames. */
+  readonly sessionId: string
+  /** Absolute host path mounted at `/workspace` inside the container. */
+  readonly projectPath: string
+}
+
+/**
+ * Return value of {@link SandboxApi.prepareSpawn}. Both fields optional —
+ * a no-op setup just returns `{}`.
+ */
+export interface SandboxSpawnSetup {
+  /**
+   * Mounts to merge with the provider's static {@link configMounts}.
+   * Useful for overlaying generated files (e.g. a sanitized settings.json
+   * mounted on top of a config-dir mount shadows the original entry).
+   */
+  readonly extraMounts?: readonly SandboxConfigMount[]
+  /**
+   * Optional teardown. Invoked once after the container exits, even if
+   * the spawn fails after `prepareSpawn` resolved. Errors are logged but
+   * not propagated — cleanup is best-effort.
+   */
+  cleanup?(): void | Promise<void>
 }