@rockclaver/sandcastle 0.7.0

package/dist/MountConfig-CmXclHA5.d.ts

@@ -0,0 +1,26 @@
+/**
+ * User-facing mount configuration for bind-mount sandbox providers.
+ *
+ * Each entry describes a host directory to mount into the sandbox container.
+ */
+/** A single bind-mount descriptor for docker()/podman() providers. */
+interface MountConfig {
+    /**
+     * Path on the host. Supports:
+     * - Absolute paths (`/data/cache`)
+     * - Tilde-expanded paths (`~/data` → `<home>/data`)
+     * - Relative paths (`data` or `./data`) — resolved from `process.cwd()`
+     */
+    readonly hostPath: string;
+    /**
+     * Path inside the sandbox container. Supports:
+     * - Absolute paths (`/mnt/data`)
+     * - Tilde-expanded paths (`~/.npm` → `/home/agent/.npm`) — expanded using the provider's sandbox home directory
+     * - Relative paths (`data` or `./data`) — resolved from the worktree directory (`/home/agent/workspace`)
+     */
+    readonly sandboxPath: string;
+    /** Mount as read-only. Defaults to `false`. */
+    readonly readonly?: boolean;
+}
+
+export type { MountConfig as M };

package/dist/SandboxProvider-EkSMuBp8.d.ts

@@ -0,0 +1,243 @@
+/**
+ * Sandbox provider types — the pluggable interface for sandbox runtimes.
+ *
+ * Provider authors implement a small Promise-based interface. Sandcastle
+ * handles worktree creation, git mount resolution, and commit extraction.
+ */
+/** Result of executing a command inside a sandbox. */
+interface ExecResult {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode: number;
+}
+/** Options for interactiveExec — the streams the provider should wire to the spawned process. */
+interface InteractiveExecOptions {
+    readonly stdin: NodeJS.ReadableStream;
+    readonly stdout: NodeJS.WritableStream;
+    readonly stderr: NodeJS.WritableStream;
+    readonly cwd?: string;
+}
+/** Handle to a running bind-mount sandbox. */
+interface BindMountSandboxHandle {
+    /** Absolute path to the worktree inside the sandbox. */
+    readonly worktreePath: string;
+    /**
+     * Execute a command in the sandbox.
+     *
+     * Implementations MUST support line-by-line streaming via `onLine`. This is
+     * how Sandcastle delivers live feedback to the user and enforces idle timeouts —
+     * without a streaming implementation, neither will work. A buffered/batch
+     * implementation that only calls `onLine` after the process exits does NOT
+     * satisfy this contract.
+     *
+     * When `stdin` is set, the implementation pipes the string to the child
+     * process's stdin and closes it. This avoids the Linux 128 KB per-arg limit.
+     */
+    exec(command: string, options?: {
+        onLine?: (line: string) => void;
+        cwd?: string;
+        sudo?: boolean;
+        stdin?: string;
+    }): Promise<ExecResult>;
+    /**
+     * Launch an interactive process inside the sandbox.
+     * Optional — providers that support interactive sessions implement this.
+     * The provider detects TTY mode from the streams (e.g. stdin.isTTY) and
+     * allocates a pseudo-terminal accordingly.
+     */
+    interactiveExec?(args: string[], options: InteractiveExecOptions): Promise<{
+        exitCode: number;
+    }>;
+    /** Copy a single file from the host into the sandbox. */
+    copyFileIn(hostPath: string, sandboxPath: string): Promise<void>;
+    /** Copy a single file from the sandbox to the host. */
+    copyFileOut(sandboxPath: string, hostPath: string): Promise<void>;
+    /** Tear down the sandbox. */
+    close(): Promise<void>;
+}
+/** Options passed to a bind-mount provider's `create` function. */
+interface BindMountCreateOptions {
+    /** Host-side path to the worktree directory. */
+    readonly worktreePath: string;
+    /** Host-side path to the original repo root. */
+    readonly hostRepoPath: string;
+    /** Volume mounts to apply (host:sandbox pairs). */
+    readonly mounts: Array<{
+        hostPath: string;
+        sandboxPath: string;
+        readonly?: boolean;
+    }>;
+    /** Environment variables to inject into the sandbox. */
+    readonly env: Record<string, string>;
+}
+/** Configuration for createBindMountSandboxProvider. */
+interface BindMountSandboxProviderConfig {
+    /** Human-readable name for this provider (e.g. "docker", "podman"). */
+    readonly name: string;
+    /** Environment variables injected by this provider. Merged at launch time. */
+    readonly env?: Record<string, string>;
+    /**
+     * Absolute path to the home directory inside the sandbox (e.g. `"/home/agent"`).
+     * Used to expand `~` in user-provided `sandboxPath` mount configs.
+     * Set to `undefined` for providers that do not have a fixed home directory.
+     */
+    readonly sandboxHomedir?: string;
+    /** Create a sandbox handle from the given options. */
+    readonly create: (options: BindMountCreateOptions) => Promise<BindMountSandboxHandle>;
+}
+/** Handle to a running isolated sandbox (extends bind-mount with file transfer). */
+interface IsolatedSandboxHandle {
+    /** Absolute path to the worktree inside the sandbox. */
+    readonly worktreePath: string;
+    /**
+     * Execute a command in the sandbox.
+     *
+     * Implementations MUST support line-by-line streaming via `onLine`. This is
+     * how Sandcastle delivers live feedback to the user and enforces idle timeouts —
+     * without a streaming implementation, neither will work. A buffered/batch
+     * implementation that only calls `onLine` after the process exits does NOT
+     * satisfy this contract.
+     *
+     * When `stdin` is set, the implementation pipes the string to the child
+     * process's stdin and closes it. This avoids the Linux 128 KB per-arg limit.
+     */
+    exec(command: string, options?: {
+        onLine?: (line: string) => void;
+        cwd?: string;
+        sudo?: boolean;
+        stdin?: string;
+    }): Promise<ExecResult>;
+    /**
+     * Launch an interactive process inside the sandbox.
+     * Optional — providers that support interactive sessions implement this.
+     * The provider detects TTY mode from the streams (e.g. stdin.isTTY) and
+     * allocates a pseudo-terminal accordingly.
+     */
+    interactiveExec?(args: string[], options: InteractiveExecOptions): Promise<{
+        exitCode: number;
+    }>;
+    /** Copy a file or directory from the host into the sandbox. */
+    copyIn(hostPath: string, sandboxPath: string): Promise<void>;
+    /** Copy a single file from the sandbox to the host. */
+    copyFileOut(sandboxPath: string, hostPath: string): Promise<void>;
+    /** Tear down the sandbox. */
+    close(): Promise<void>;
+}
+/** Options passed to an isolated provider's `create` function. */
+interface IsolatedCreateOptions {
+    /** Environment variables to inject into the sandbox. */
+    readonly env: Record<string, string>;
+}
+/** Configuration for createIsolatedSandboxProvider. */
+interface IsolatedSandboxProviderConfig {
+    /** Human-readable name for this provider (e.g. "daytona", "e2b"). */
+    readonly name: string;
+    /** Environment variables injected by this provider. Merged at launch time. */
+    readonly env?: Record<string, string>;
+    /** Create an isolated sandbox handle from the given options. */
+    readonly create: (options: IsolatedCreateOptions) => Promise<IsolatedSandboxHandle>;
+}
+/** A bind-mount sandbox provider. */
+interface BindMountSandboxProvider {
+    /** Human-readable provider name. */
+    readonly name: string;
+    /** Environment variables injected by this provider. */
+    readonly env: Record<string, string>;
+    /**
+     * Absolute path to the home directory inside the sandbox (e.g. `"/home/agent"`).
+     * `undefined` when the provider does not declare a sandbox home directory.
+     */
+    readonly sandboxHomedir: string | undefined;
+}
+/** An isolated sandbox provider. */
+interface IsolatedSandboxProvider {
+    /** Human-readable provider name. */
+    readonly name: string;
+    /** Environment variables injected by this provider. */
+    readonly env: Record<string, string>;
+}
+/** Handle to a no-sandbox session — runs commands directly on the host. */
+interface NoSandboxHandle {
+    /** Absolute path to the worktree on the host. */
+    readonly worktreePath: string;
+    /**
+     * Execute a command on the host.
+     *
+     * Implementations MUST support line-by-line streaming via `onLine`. This is
+     * how Sandcastle delivers live feedback to the user and enforces idle timeouts —
+     * without a streaming implementation, neither will work.
+     *
+     * When `stdin` is set, the implementation pipes the string to the child
+     * process's stdin and closes it. This avoids the Linux 128 KB per-arg limit.
+     */
+    exec(command: string, options?: {
+        onLine?: (line: string) => void;
+        cwd?: string;
+        sudo?: boolean;
+        stdin?: string;
+    }): Promise<ExecResult>;
+    /**
+     * Launch an interactive process on the host with inherited stdio.
+     */
+    interactiveExec(args: string[], options: InteractiveExecOptions): Promise<{
+        exitCode: number;
+    }>;
+    /** No-op — no container to tear down. */
+    close(): Promise<void>;
+}
+/** A no-sandbox provider — runs the agent directly on the host with no container isolation. */
+interface NoSandboxProvider {
+    /** Human-readable provider name. */
+    readonly name: string;
+    /** Environment variables injected by this provider. */
+    readonly env: Record<string, string>;
+}
+/** Head strategy: agent writes directly to host working directory. Bind-mount only. */
+interface HeadBranchStrategy {
+    readonly type: "head";
+}
+/** Merge-to-head strategy: temp branch, merge back to HEAD, delete temp branch. */
+interface MergeToHeadBranchStrategy {
+    readonly type: "merge-to-head";
+}
+/** Branch strategy: commits land on an explicit named branch. */
+interface NamedBranchStrategy {
+    readonly type: "branch";
+    readonly branch: string;
+    /**
+     * Git ref to use as the starting point when creating a new branch.
+     * Only used when the branch doesn't already exist — ignored otherwise.
+     * Callers are responsible for ensuring the ref is current (e.g. `git fetch`).
+     * Defaults to `HEAD` when omitted.
+     */
+    readonly baseBranch?: string;
+}
+/** Branch strategy for bind-mount providers (all three variants). */
+type BindMountBranchStrategy = HeadBranchStrategy | MergeToHeadBranchStrategy | NamedBranchStrategy;
+/** Branch strategy for isolated providers (no head — can't write to host). */
+type IsolatedBranchStrategy = MergeToHeadBranchStrategy | NamedBranchStrategy;
+/** Branch strategy for no-sandbox providers (all three — same as bind-mount). */
+type NoSandboxBranchStrategy = HeadBranchStrategy | MergeToHeadBranchStrategy | NamedBranchStrategy;
+/** Union of all branch strategy variants. */
+type BranchStrategy = BindMountBranchStrategy | IsolatedBranchStrategy | NoSandboxBranchStrategy;
+/**
+ * A sandbox provider — the pluggable unit that `run()`, `interactive()`, and
+ * `createSandbox()` accept. Tagged for internal dispatch: "bind-mount",
+ * "isolated", or "none". When `NoSandboxProvider` is used, the agent runs
+ * directly on the host with no container isolation — opt in at your own risk.
+ */
+type SandboxProvider = BindMountSandboxProvider | IsolatedSandboxProvider | NoSandboxProvider;
+/** @deprecated Use `SandboxProvider` — it now includes `NoSandboxProvider`. */
+type AnySandboxProvider = SandboxProvider;
+/**
+ * Create a bind-mount sandbox provider from a config object.
+ * The returned provider can be passed to `run()` or `createSandbox()`.
+ */
+declare const createBindMountSandboxProvider: (config: BindMountSandboxProviderConfig) => BindMountSandboxProvider;
+/**
+ * Create an isolated sandbox provider from a config object.
+ * The returned provider can be passed to `run()` or `createSandbox()`.
+ */
+declare const createIsolatedSandboxProvider: (config: IsolatedSandboxProviderConfig) => IsolatedSandboxProvider;
+
+export { type AnySandboxProvider as A, type BindMountSandboxHandle as B, type ExecResult as E, type HeadBranchStrategy as H, type IsolatedSandboxProvider as I, type MergeToHeadBranchStrategy as M, type NoSandboxProvider as N, type SandboxProvider as S, type BranchStrategy as a, type NamedBranchStrategy as b, type BindMountBranchStrategy as c, type BindMountCreateOptions as d, type BindMountSandboxProvider as e, type BindMountSandboxProviderConfig as f, type InteractiveExecOptions as g, type IsolatedBranchStrategy as h, type IsolatedCreateOptions as i, type IsolatedSandboxHandle as j, type IsolatedSandboxProviderConfig as k, type NoSandboxBranchStrategy as l, type NoSandboxHandle as m, createBindMountSandboxProvider as n, createIsolatedSandboxProvider as o };

package/dist/chunk-72UVAC7B.js

@@ -0,0 +1,99 @@
+import { createRequire } from 'node:module';
+import { MAX_TAIL_CHARS, BoundedTail } from './chunk-NGBM7T3E.js';
+import { spawn } from 'child_process';
+import { createInterface } from 'readline';
+
+createRequire(import.meta.url);
+var noSandbox = (options) => ({
+  tag: "none",
+  name: "no-sandbox",
+  env: options?.env ?? {},
+  create: async (createOptions) => {
+    const worktreePath = createOptions.worktreePath;
+    const processEnv = { ...process.env, ...createOptions.env };
+    const maxOutputTailChars = options?.maxOutputTailChars ?? MAX_TAIL_CHARS;
+    const handle = {
+      worktreePath,
+      exec: (command, opts) => {
+        const cwd = opts?.cwd ?? worktreePath;
+        return new Promise((resolve, reject) => {
+          const proc = spawn("sh", ["-c", command], {
+            cwd,
+            env: processEnv,
+            stdio: [
+              opts?.stdin !== void 0 ? "pipe" : "ignore",
+              "pipe",
+              "pipe"
+            ]
+          });
+          if (opts?.stdin !== void 0) {
+            proc.stdin.write(opts.stdin);
+            proc.stdin.end();
+          }
+          proc.on("error", (error) => {
+            reject(new Error(`exec failed: ${error.message}`));
+          });
+          if (opts?.onLine) {
+            const onLine = opts.onLine;
+            const stdoutTail = new BoundedTail(maxOutputTailChars, "\n");
+            const stderrTail = new BoundedTail(maxOutputTailChars, "");
+            const rl = createInterface({ input: proc.stdout });
+            rl.on("line", (line) => {
+              stdoutTail.push(line);
+              onLine(line);
+            });
+            proc.stderr.on("data", (chunk) => {
+              stderrTail.push(chunk.toString());
+            });
+            proc.on("close", (code) => {
+              resolve({
+                stdout: stdoutTail.toString(),
+                stderr: stderrTail.toString(),
+                exitCode: code ?? 0
+              });
+            });
+          } else {
+            const stdoutChunks = [];
+            const stderrChunks = [];
+            proc.stdout.on("data", (chunk) => {
+              stdoutChunks.push(chunk.toString());
+            });
+            proc.stderr.on("data", (chunk) => {
+              stderrChunks.push(chunk.toString());
+            });
+            proc.on("close", (code) => {
+              resolve({
+                stdout: stdoutChunks.join(""),
+                stderr: stderrChunks.join(""),
+                exitCode: code ?? 0
+              });
+            });
+          }
+        });
+      },
+      interactiveExec: (args, opts) => {
+        return new Promise((resolve, reject) => {
+          const [cmd, ...rest] = args;
+          const proc = spawn(cmd, rest, {
+            cwd: opts.cwd ?? worktreePath,
+            env: processEnv,
+            stdio: [opts.stdin, opts.stdout, opts.stderr]
+          });
+          proc.on("error", (error) => {
+            reject(new Error(`exec failed: ${error.message}`));
+          });
+          proc.on("close", (code) => {
+            resolve({ exitCode: code ?? 0 });
+          });
+        });
+      },
+      close: async () => {
+      }
+    };
+    return handle;
+  }
+});
+
+export { noSandbox };
+//# sourceMappingURL=chunk-72UVAC7B.js.map
+//# sourceMappingURL=chunk-72UVAC7B.js.map

package/dist/chunk-72UVAC7B.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/sandboxes/no-sandbox.ts"],"names":[],"mappings":"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","file":"chunk-72UVAC7B.js","sourcesContent":["/**\n * No-sandbox provider — runs the agent directly on the host with no container isolation.\n *\n * Usage:\n *   import { noSandbox } from \"sandcastle/sandboxes/no-sandbox\";\n *   await interactive({ agent: claudeCode(\"claude-opus-4-7\"), sandbox: noSandbox() });\n *\n * Accepted by `run()`, `interactive()`, and `createSandbox()`. Skips\n * container isolation entirely — the agent executes on the host. Does not\n * pass `--dangerously-skip-permissions` to the agent — the user manages\n * permissions themselves.\n */\n\nimport { spawn, type StdioOptions } from \"node:child_process\";\nimport { createInterface } from \"node:readline\";\nimport type {\n  NoSandboxProvider,\n  NoSandboxHandle,\n  ExecResult,\n  InteractiveExecOptions,\n} from \"../SandboxProvider.js\";\nimport { BoundedTail, MAX_TAIL_CHARS } from \"../boundedTail.js\";\n\nexport interface NoSandboxOptions {\n  /** Environment variables injected by this provider. Merged at launch time. */\n  readonly env?: Record<string, string>;\n  /**\n   * Maximum number of characters of streamed `exec` output retained per stream\n   * (stdout and stderr) when an `onLine` callback is supplied (default: 64KiB).\n   *\n   * Output is delivered live to `onLine` regardless; this only bounds the tail\n   * returned in `ExecResult`, preventing a long-running agent's output from\n   * overflowing V8's max string length and crashing the run.\n   */\n  readonly maxOutputTailChars?: number;\n}\n\n/**\n * Create a no-sandbox provider.\n *\n * The returned provider runs the agent directly on the host. All three\n * branch strategies are supported (head, merge-to-head, branch),\n * defaulting to head.\n */\nexport const noSandbox = (options?: NoSandboxOptions): NoSandboxProvider => ({\n  tag: \"none\",\n  name: \"no-sandbox\",\n  env: options?.env ?? {},\n  create: async (createOptions): Promise<NoSandboxHandle> => {\n    const worktreePath = createOptions.worktreePath;\n    const processEnv = { ...process.env, ...createOptions.env };\n    const maxOutputTailChars = options?.maxOutputTailChars ?? MAX_TAIL_CHARS;\n\n    const handle: NoSandboxHandle = {\n      worktreePath,\n\n      exec: (\n        command: string,\n        opts?: {\n          onLine?: (line: string) => void;\n          cwd?: string;\n          sudo?: boolean;\n          stdin?: string;\n        },\n      ): Promise<ExecResult> => {\n        // sudo is a no-op for no-sandbox — the user is already on the host\n        const cwd = opts?.cwd ?? worktreePath;\n\n        return new Promise((resolve, reject) => {\n          const proc = spawn(\"sh\", [\"-c\", command], {\n            cwd,\n            env: processEnv,\n            stdio: [\n              opts?.stdin !== undefined ? \"pipe\" : \"ignore\",\n              \"pipe\",\n              \"pipe\",\n            ],\n          });\n\n          if (opts?.stdin !== undefined) {\n            proc.stdin!.write(opts.stdin);\n            proc.stdin!.end();\n          }\n\n          proc.on(\"error\", (error) => {\n            reject(new Error(`exec failed: ${error.message}`));\n          });\n\n          if (opts?.onLine) {\n            const onLine = opts.onLine;\n            const stdoutTail = new BoundedTail(maxOutputTailChars, \"\\n\");\n            const stderrTail = new BoundedTail(maxOutputTailChars, \"\");\n            const rl = createInterface({ input: proc.stdout! });\n            rl.on(\"line\", (line) => {\n              stdoutTail.push(line);\n              onLine(line);\n            });\n            proc.stderr!.on(\"data\", (chunk: Buffer) => {\n              stderrTail.push(chunk.toString());\n            });\n            proc.on(\"close\", (code) => {\n              resolve({\n                stdout: stdoutTail.toString(),\n                stderr: stderrTail.toString(),\n                exitCode: code ?? 0,\n              });\n            });\n          } else {\n            const stdoutChunks: string[] = [];\n            const stderrChunks: string[] = [];\n            proc.stdout!.on(\"data\", (chunk: Buffer) => {\n              stdoutChunks.push(chunk.toString());\n            });\n            proc.stderr!.on(\"data\", (chunk: Buffer) => {\n              stderrChunks.push(chunk.toString());\n            });\n            proc.on(\"close\", (code) => {\n              resolve({\n                stdout: stdoutChunks.join(\"\"),\n                stderr: stderrChunks.join(\"\"),\n                exitCode: code ?? 0,\n              });\n            });\n          }\n        });\n      },\n\n      interactiveExec: (\n        args: string[],\n        opts: InteractiveExecOptions,\n      ): Promise<{ exitCode: number }> => {\n        return new Promise((resolve, reject) => {\n          const [cmd, ...rest] = args;\n          const proc = spawn(cmd!, rest, {\n            cwd: opts.cwd ?? worktreePath,\n            env: processEnv,\n            stdio: [opts.stdin, opts.stdout, opts.stderr] as StdioOptions,\n          });\n\n          proc.on(\"error\", (error: Error) => {\n            reject(new Error(`exec failed: ${error.message}`));\n          });\n\n          proc.on(\"close\", (code: number | null) => {\n            resolve({ exitCode: code ?? 0 });\n          });\n        });\n      },\n\n      close: async (): Promise<void> => {\n        // No-op — no container to tear down\n      },\n    };\n\n    return handle;\n  },\n});\n"]}

package/dist/chunk-BIWNFKGV.js

@@ -0,0 +1,22 @@
+import { createRequire } from 'node:module';
+
+createRequire(import.meta.url);
+
+// src/SandboxProvider.ts
+var createBindMountSandboxProvider = (config) => ({
+  tag: "bind-mount",
+  name: config.name,
+  env: config.env ?? {},
+  sandboxHomedir: config.sandboxHomedir,
+  create: config.create
+});
+var createIsolatedSandboxProvider = (config) => ({
+  tag: "isolated",
+  name: config.name,
+  env: config.env ?? {},
+  create: config.create
+});
+
+export { createBindMountSandboxProvider, createIsolatedSandboxProvider };
+//# sourceMappingURL=chunk-BIWNFKGV.js.map
+//# sourceMappingURL=chunk-BIWNFKGV.js.map

package/dist/chunk-BIWNFKGV.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/SandboxProvider.ts"],"names":[],"mappings":";;;;;AAoTO,IAAM,8BAAA,GAAiC,CAC5C,MAAA,MAC8B;AAAA,EAC9B,GAAA,EAAK,YAAA;AAAA,EACL,MAAM,MAAA,CAAO,IAAA;AAAA,EACb,GAAA,EAAK,MAAA,CAAO,GAAA,IAAO,EAAC;AAAA,EACpB,gBAAgB,MAAA,CAAO,cAAA;AAAA,EACvB,QAAQ,MAAA,CAAO;AACjB,CAAA;AAMO,IAAM,6BAAA,GAAgC,CAC3C,MAAA,MAC6B;AAAA,EAC7B,GAAA,EAAK,UAAA;AAAA,EACL,MAAM,MAAA,CAAO,IAAA;AAAA,EACb,GAAA,EAAK,MAAA,CAAO,GAAA,IAAO,EAAC;AAAA,EACpB,QAAQ,MAAA,CAAO;AACjB,CAAA","file":"chunk-BIWNFKGV.js","sourcesContent":["/**\n * Sandbox provider types — the pluggable interface for sandbox runtimes.\n *\n * Provider authors implement a small Promise-based interface. Sandcastle\n * handles worktree creation, git mount resolution, and commit extraction.\n */\n\n/** Result of executing a command inside a sandbox. */\nexport interface ExecResult {\n  readonly stdout: string;\n  readonly stderr: string;\n  readonly exitCode: number;\n}\n\n/** Options for interactiveExec — the streams the provider should wire to the spawned process. */\nexport interface InteractiveExecOptions {\n  readonly stdin: NodeJS.ReadableStream;\n  readonly stdout: NodeJS.WritableStream;\n  readonly stderr: NodeJS.WritableStream;\n  readonly cwd?: string;\n}\n\n/** Handle to a running bind-mount sandbox. */\nexport interface BindMountSandboxHandle {\n  /** Absolute path to the worktree inside the sandbox. */\n  readonly worktreePath: string;\n  /**\n   * Execute a command in the sandbox.\n   *\n   * Implementations MUST support line-by-line streaming via `onLine`. This is\n   * how Sandcastle delivers live feedback to the user and enforces idle timeouts —\n   * without a streaming implementation, neither will work. A buffered/batch\n   * implementation that only calls `onLine` after the process exits does NOT\n   * satisfy this contract.\n   *\n   * When `stdin` is set, the implementation pipes the string to the child\n   * process's stdin and closes it. This avoids the Linux 128 KB per-arg limit.\n   */\n  exec(\n    command: string,\n    options?: {\n      onLine?: (line: string) => void;\n      cwd?: string;\n      sudo?: boolean;\n      stdin?: string;\n    },\n  ): Promise<ExecResult>;\n  /**\n   * Launch an interactive process inside the sandbox.\n   * Optional — providers that support interactive sessions implement this.\n   * The provider detects TTY mode from the streams (e.g. stdin.isTTY) and\n   * allocates a pseudo-terminal accordingly.\n   */\n  interactiveExec?(\n    args: string[],\n    options: InteractiveExecOptions,\n  ): Promise<{ exitCode: number }>;\n  /** Copy a single file from the host into the sandbox. */\n  copyFileIn(hostPath: string, sandboxPath: string): Promise<void>;\n  /** Copy a single file from the sandbox to the host. */\n  copyFileOut(sandboxPath: string, hostPath: string): Promise<void>;\n  /** Tear down the sandbox. */\n  close(): Promise<void>;\n}\n\n/** Options passed to a bind-mount provider's `create` function. */\nexport interface BindMountCreateOptions {\n  /** Host-side path to the worktree directory. */\n  readonly worktreePath: string;\n  /** Host-side path to the original repo root. */\n  readonly hostRepoPath: string;\n  /** Volume mounts to apply (host:sandbox pairs). */\n  readonly mounts: Array<{\n    hostPath: string;\n    sandboxPath: string;\n    readonly?: boolean;\n  }>;\n  /** Environment variables to inject into the sandbox. */\n  readonly env: Record<string, string>;\n}\n\n/** Configuration for createBindMountSandboxProvider. */\nexport interface BindMountSandboxProviderConfig {\n  /** Human-readable name for this provider (e.g. \"docker\", \"podman\"). */\n  readonly name: string;\n  /** Environment variables injected by this provider. Merged at launch time. */\n  readonly env?: Record<string, string>;\n  /**\n   * Absolute path to the home directory inside the sandbox (e.g. `\"/home/agent\"`).\n   * Used to expand `~` in user-provided `sandboxPath` mount configs.\n   * Set to `undefined` for providers that do not have a fixed home directory.\n   */\n  readonly sandboxHomedir?: string;\n  /** Create a sandbox handle from the given options. */\n  readonly create: (\n    options: BindMountCreateOptions,\n  ) => Promise<BindMountSandboxHandle>;\n}\n\n/** Handle to a running isolated sandbox (extends bind-mount with file transfer). */\nexport interface IsolatedSandboxHandle {\n  /** Absolute path to the worktree inside the sandbox. */\n  readonly worktreePath: string;\n  /**\n   * Execute a command in the sandbox.\n   *\n   * Implementations MUST support line-by-line streaming via `onLine`. This is\n   * how Sandcastle delivers live feedback to the user and enforces idle timeouts —\n   * without a streaming implementation, neither will work. A buffered/batch\n   * implementation that only calls `onLine` after the process exits does NOT\n   * satisfy this contract.\n   *\n   * When `stdin` is set, the implementation pipes the string to the child\n   * process's stdin and closes it. This avoids the Linux 128 KB per-arg limit.\n   */\n  exec(\n    command: string,\n    options?: {\n      onLine?: (line: string) => void;\n      cwd?: string;\n      sudo?: boolean;\n      stdin?: string;\n    },\n  ): Promise<ExecResult>;\n  /**\n   * Launch an interactive process inside the sandbox.\n   * Optional — providers that support interactive sessions implement this.\n   * The provider detects TTY mode from the streams (e.g. stdin.isTTY) and\n   * allocates a pseudo-terminal accordingly.\n   */\n  interactiveExec?(\n    args: string[],\n    options: InteractiveExecOptions,\n  ): Promise<{ exitCode: number }>;\n  /** Copy a file or directory from the host into the sandbox. */\n  copyIn(hostPath: string, sandboxPath: string): Promise<void>;\n  /** Copy a single file from the sandbox to the host. */\n  copyFileOut(sandboxPath: string, hostPath: string): Promise<void>;\n  /** Tear down the sandbox. */\n  close(): Promise<void>;\n}\n\n/** Options passed to an isolated provider's `create` function. */\nexport interface IsolatedCreateOptions {\n  /** Environment variables to inject into the sandbox. */\n  readonly env: Record<string, string>;\n}\n\n/** Configuration for createIsolatedSandboxProvider. */\nexport interface IsolatedSandboxProviderConfig {\n  /** Human-readable name for this provider (e.g. \"daytona\", \"e2b\"). */\n  readonly name: string;\n  /** Environment variables injected by this provider. Merged at launch time. */\n  readonly env?: Record<string, string>;\n  /** Create an isolated sandbox handle from the given options. */\n  readonly create: (\n    options: IsolatedCreateOptions,\n  ) => Promise<IsolatedSandboxHandle>;\n}\n\n/** A bind-mount sandbox provider. */\nexport interface BindMountSandboxProvider {\n  /** @internal Discriminator for internal dispatch. */\n  readonly tag: \"bind-mount\";\n  /** Human-readable provider name. */\n  readonly name: string;\n  /** Environment variables injected by this provider. */\n  readonly env: Record<string, string>;\n  /**\n   * Absolute path to the home directory inside the sandbox (e.g. `\"/home/agent\"`).\n   * `undefined` when the provider does not declare a sandbox home directory.\n   */\n  readonly sandboxHomedir: string | undefined;\n  /** @internal Create a sandbox handle. */\n  readonly create: (\n    options: BindMountCreateOptions,\n  ) => Promise<BindMountSandboxHandle>;\n}\n\n/** An isolated sandbox provider. */\nexport interface IsolatedSandboxProvider {\n  /** @internal Discriminator for internal dispatch. */\n  readonly tag: \"isolated\";\n  /** Human-readable provider name. */\n  readonly name: string;\n  /** Environment variables injected by this provider. */\n  readonly env: Record<string, string>;\n  /** @internal Create an isolated sandbox handle. */\n  readonly create: (\n    options: IsolatedCreateOptions,\n  ) => Promise<IsolatedSandboxHandle>;\n}\n\n/** Handle to a no-sandbox session — runs commands directly on the host. */\nexport interface NoSandboxHandle {\n  /** Absolute path to the worktree on the host. */\n  readonly worktreePath: string;\n  /**\n   * Execute a command on the host.\n   *\n   * Implementations MUST support line-by-line streaming via `onLine`. This is\n   * how Sandcastle delivers live feedback to the user and enforces idle timeouts —\n   * without a streaming implementation, neither will work.\n   *\n   * When `stdin` is set, the implementation pipes the string to the child\n   * process's stdin and closes it. This avoids the Linux 128 KB per-arg limit.\n   */\n  exec(\n    command: string,\n    options?: {\n      onLine?: (line: string) => void;\n      cwd?: string;\n      sudo?: boolean;\n      stdin?: string;\n    },\n  ): Promise<ExecResult>;\n  /**\n   * Launch an interactive process on the host with inherited stdio.\n   */\n  interactiveExec(\n    args: string[],\n    options: InteractiveExecOptions,\n  ): Promise<{ exitCode: number }>;\n  /** No-op — no container to tear down. */\n  close(): Promise<void>;\n}\n\n/** A no-sandbox provider — runs the agent directly on the host with no container isolation. */\nexport interface NoSandboxProvider {\n  /** @internal Discriminator for internal dispatch. */\n  readonly tag: \"none\";\n  /** Human-readable provider name. */\n  readonly name: string;\n  /** Environment variables injected by this provider. */\n  readonly env: Record<string, string>;\n  /** @internal Create a no-sandbox handle. */\n  readonly create: (options: {\n    readonly worktreePath: string;\n    readonly env: Record<string, string>;\n  }) => Promise<NoSandboxHandle>;\n}\n\n// ---------- Branch strategy types ----------\n\n/** Head strategy: agent writes directly to host working directory. Bind-mount only. */\nexport interface HeadBranchStrategy {\n  readonly type: \"head\";\n}\n\n/** Merge-to-head strategy: temp branch, merge back to HEAD, delete temp branch. */\nexport interface MergeToHeadBranchStrategy {\n  readonly type: \"merge-to-head\";\n}\n\n/** Branch strategy: commits land on an explicit named branch. */\nexport interface NamedBranchStrategy {\n  readonly type: \"branch\";\n  readonly branch: string;\n  /**\n   * Git ref to use as the starting point when creating a new branch.\n   * Only used when the branch doesn't already exist — ignored otherwise.\n   * Callers are responsible for ensuring the ref is current (e.g. `git fetch`).\n   * Defaults to `HEAD` when omitted.\n   */\n  readonly baseBranch?: string;\n}\n\n/** Branch strategy for bind-mount providers (all three variants). */\nexport type BindMountBranchStrategy =\n  | HeadBranchStrategy\n  | MergeToHeadBranchStrategy\n  | NamedBranchStrategy;\n\n/** Branch strategy for isolated providers (no head — can't write to host). */\nexport type IsolatedBranchStrategy =\n  | MergeToHeadBranchStrategy\n  | NamedBranchStrategy;\n\n/** Branch strategy for no-sandbox providers (all three — same as bind-mount). */\nexport type NoSandboxBranchStrategy =\n  | HeadBranchStrategy\n  | MergeToHeadBranchStrategy\n  | NamedBranchStrategy;\n\n/** Union of all branch strategy variants. */\nexport type BranchStrategy =\n  | BindMountBranchStrategy\n  | IsolatedBranchStrategy\n  | NoSandboxBranchStrategy;\n\n/**\n * A sandbox provider — the pluggable unit that `run()`, `interactive()`, and\n * `createSandbox()` accept. Tagged for internal dispatch: \"bind-mount\",\n * \"isolated\", or \"none\". When `NoSandboxProvider` is used, the agent runs\n * directly on the host with no container isolation — opt in at your own risk.\n */\nexport type SandboxProvider =\n  | BindMountSandboxProvider\n  | IsolatedSandboxProvider\n  | NoSandboxProvider;\n\n/** @deprecated Use `SandboxProvider` — it now includes `NoSandboxProvider`. */\nexport type AnySandboxProvider = SandboxProvider;\n\n/**\n * Create a bind-mount sandbox provider from a config object.\n * The returned provider can be passed to `run()` or `createSandbox()`.\n */\nexport const createBindMountSandboxProvider = (\n  config: BindMountSandboxProviderConfig,\n): BindMountSandboxProvider => ({\n  tag: \"bind-mount\",\n  name: config.name,\n  env: config.env ?? {},\n  sandboxHomedir: config.sandboxHomedir,\n  create: config.create,\n});\n\n/**\n * Create an isolated sandbox provider from a config object.\n * The returned provider can be passed to `run()` or `createSandbox()`.\n */\nexport const createIsolatedSandboxProvider = (\n  config: IsolatedSandboxProviderConfig,\n): IsolatedSandboxProvider => ({\n  tag: \"isolated\",\n  name: config.name,\n  env: config.env ?? {},\n  create: config.create,\n});\n"]}