@ai-hero/sandcastle 0.6.5 → 0.7.0

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"]}

package/dist/chunk-NGBM7T3E.js

@@ -0,0 +1,76 @@
+import { createRequire } from 'node:module';
+
+const require$1 = createRequire(import.meta.url);
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __require = /* @__PURE__ */ ((x) => typeof require$1 !== "undefined" ? require$1 : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require$1 !== "undefined" ? require$1 : a)[b]
+}) : x)(function(x) {
+  if (typeof require$1 !== "undefined") return require$1.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __commonJS = (cb, mod) => function __require2() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/boundedTail.ts
+var MAX_TAIL_CHARS = 64 * 1024;
+var BoundedTail = class {
+  items = [];
+  totalChars = 0;
+  maxChars;
+  separator;
+  /**
+   * @param maxChars Maximum length of the joined tail. Defaults to {@link MAX_TAIL_CHARS}.
+   * @param separator String placed between items by {@link toString}. Must match
+   *   how the caller would otherwise have joined the accumulated chunks (e.g.
+   *   `"\n"` for line streams, `""` for raw chunk streams).
+   */
+  constructor(maxChars = MAX_TAIL_CHARS, separator = "") {
+    this.maxChars = maxChars;
+    this.separator = separator;
+  }
+  /** Append one item to the tail, evicting oldest items to stay within budget. */
+  push(item) {
+    const bounded = item.length > this.maxChars ? item.slice(item.length - this.maxChars) : item;
+    this.totalChars += bounded.length + (this.items.length > 0 ? this.separator.length : 0);
+    this.items.push(bounded);
+    while (this.totalChars > this.maxChars && this.items.length > 1) {
+      const dropped = this.items.shift();
+      this.totalChars -= dropped.length + this.separator.length;
+    }
+  }
+  /** Join the retained tail into a single string (length ≤ `maxChars`). */
+  toString() {
+    return this.items.join(this.separator);
+  }
+};
+
+export { BoundedTail, MAX_TAIL_CHARS, __commonJS, __export, __reExport, __require, __toESM };
+//# sourceMappingURL=chunk-NGBM7T3E.js.map
+//# sourceMappingURL=chunk-NGBM7T3E.js.map

package/dist/chunk-NGBM7T3E.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/boundedTail.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmBO,IAAM,iBAAiB,EAAA,GAAK;AAa5B,IAAM,cAAN,MAAkB;AAAA,EACN,QAAkB,EAAC;AAAA,EAC5B,UAAA,GAAa,CAAA;AAAA,EACJ,QAAA;AAAA,EACA,SAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQjB,WAAA,CAAY,QAAA,GAAmB,cAAA,EAAgB,SAAA,GAAY,EAAA,EAAI;AAC7D,IAAA,IAAA,CAAK,QAAA,GAAW,QAAA;AAChB,IAAA,IAAA,CAAK,SAAA,GAAY,SAAA;AAAA,EACnB;AAAA;AAAA,EAGA,KAAK,IAAA,EAAoB;AACvB,IAAA,MAAM,OAAA,GACJ,IAAA,CAAK,MAAA,GAAS,IAAA,CAAK,QAAA,GACf,IAAA,CAAK,KAAA,CAAM,IAAA,CAAK,MAAA,GAAS,IAAA,CAAK,QAAQ,CAAA,GACtC,IAAA;AACN,IAAA,IAAA,CAAK,UAAA,IACH,QAAQ,MAAA,IAAU,IAAA,CAAK,MAAM,MAAA,GAAS,CAAA,GAAI,IAAA,CAAK,SAAA,CAAU,MAAA,GAAS,CAAA,CAAA;AACpE,IAAA,IAAA,CAAK,KAAA,CAAM,KAAK,OAAO,CAAA;AACvB,IAAA,OAAO,KAAK,UAAA,GAAa,IAAA,CAAK,YAAY,IAAA,CAAK,KAAA,CAAM,SAAS,CAAA,EAAG;AAC/D,MAAA,MAAM,OAAA,GAAU,IAAA,CAAK,KAAA,CAAM,KAAA,EAAM;AACjC,MAAA,IAAA,CAAK,UAAA,IAAc,OAAA,CAAQ,MAAA,GAAS,IAAA,CAAK,SAAA,CAAU,MAAA;AAAA,IACrD;AAAA,EACF;AAAA;AAAA,EAGA,QAAA,GAAmB;AACjB,IAAA,OAAO,IAAA,CAAK,KAAA,CAAM,IAAA,CAAK,IAAA,CAAK,SAAS,CAAA;AAAA,EACvC;AACF","file":"chunk-NGBM7T3E.js","sourcesContent":["/**\n * A bounded, rolling tail of streamed output — a pure, provider-agnostic\n * utility shared by every sandbox provider that streams `exec` output.\n *\n * When a provider streams output line-by-line, it accumulates the stream only\n * to build the returned `ExecResult.stdout`/`stderr`. Consumers read just the\n * tail of that value (e.g. the last lines of an error, or a fallback for the\n * agent's final result), so retaining the whole stream is unnecessary — and,\n * once the accumulated string passes V8's ~512MB max string length, fatal: a\n * naive `chunks.join()` throws `RangeError: Invalid string length`, which on a\n * long agent run crashes the whole orchestration.\n */\n\n/**\n * Default maximum number of characters retained in a bounded output tail.\n *\n * 64KiB sits comfortably above any agent completion signal or structured-output\n * payload while staying far below V8's max string length.\n */\nexport const MAX_TAIL_CHARS = 64 * 1024;\n\n/**\n * A fixed-size rolling tail of strings, bounded by total character length.\n *\n * `push` appends to the tail; once the joined length would exceed `maxChars`,\n * the oldest items are dropped from the front. A single item longer than\n * `maxChars` is truncated to its own tail, so a newline-free blob can't\n * overflow on one push. `toString` joins the retained items, and its length is\n * always at most `maxChars`.\n *\n * The running length counter is encapsulated so callers can't desync it.\n */\nexport class BoundedTail {\n  private readonly items: string[] = [];\n  private totalChars = 0;\n  private readonly maxChars: number;\n  private readonly separator: string;\n\n  /**\n   * @param maxChars Maximum length of the joined tail. Defaults to {@link MAX_TAIL_CHARS}.\n   * @param separator String placed between items by {@link toString}. Must match\n   *   how the caller would otherwise have joined the accumulated chunks (e.g.\n   *   `\"\\n\"` for line streams, `\"\"` for raw chunk streams).\n   */\n  constructor(maxChars: number = MAX_TAIL_CHARS, separator = \"\") {\n    this.maxChars = maxChars;\n    this.separator = separator;\n  }\n\n  /** Append one item to the tail, evicting oldest items to stay within budget. */\n  push(item: string): void {\n    const bounded =\n      item.length > this.maxChars\n        ? item.slice(item.length - this.maxChars)\n        : item;\n    this.totalChars +=\n      bounded.length + (this.items.length > 0 ? this.separator.length : 0);\n    this.items.push(bounded);\n    while (this.totalChars > this.maxChars && this.items.length > 1) {\n      const dropped = this.items.shift()!;\n      this.totalChars -= dropped.length + this.separator.length;\n    }\n  }\n\n  /** Join the retained tail into a single string (length ≤ `maxChars`). */\n  toString(): string {\n    return this.items.join(this.separator);\n  }\n}\n"]}

package/dist/chunk-NSFQW6ML.js

@@ -0,0 +1,362 @@
+import { createRequire } from 'node:module';
+import { Effect_exports, resolveUserMounts, processFileMountParents, defaultImageName, registerShutdown, DockerError, formatVolumeMount } from './chunk-5VM5QZ26.js';
+import { createBindMountSandboxProvider } from './chunk-BIWNFKGV.js';
+import { MAX_TAIL_CHARS, BoundedTail } from './chunk-NGBM7T3E.js';
+import { execFile, execFileSync, spawn } from 'child_process';
+import { randomUUID } from 'crypto';
+import { createInterface } from 'readline';
+import { resolve } from 'path';
+
+createRequire(import.meta.url);
+var dockerExec = (args) => Effect_exports.async((resume) => {
+  execFile(
+    "docker",
+    args,
+    { maxBuffer: 10 * 1024 * 1024 },
+    (error, stdout, stderr) => {
+      if (error) {
+        resume(
+          Effect_exports.fail(
+            new DockerError({
+              message: `docker ${args[0]} failed: ${stderr?.toString() || error.message}`
+            })
+          )
+        );
+      } else {
+        resume(Effect_exports.succeed(stdout.toString()));
+      }
+    }
+  );
+});
+var buildImage = (imageName, dockerfileDir, options) => Effect_exports.gen(function* () {
+  const buildArgFlags = Object.entries(options?.buildArgs ?? {}).flatMap(
+    ([k, v]) => ["--build-arg", `${k}=${v}`]
+  );
+  if (options?.dockerfile) {
+    yield* dockerExec([
+      "build",
+      "-t",
+      imageName,
+      ...buildArgFlags,
+      "-f",
+      resolve(options.dockerfile),
+      process.cwd()
+    ]);
+  } else {
+    yield* dockerExec([
+      "build",
+      "-t",
+      imageName,
+      ...buildArgFlags,
+      resolve(dockerfileDir)
+    ]);
+  }
+});
+var startContainer = (containerName, imageName, env, options) => Effect_exports.gen(function* () {
+  const existing = yield* dockerExec([
+    "ps",
+    "-a",
+    "--filter",
+    `name=^${containerName}$`,
+    "--format",
+    "{{.Names}}"
+  ]);
+  if (existing.trim() === containerName) {
+    yield* Effect_exports.fail(
+      new DockerError({
+        message: `Container '${containerName}' already exists. Run cleanup first.`
+      })
+    );
+  }
+  const envFlags = Object.entries(env).flatMap(([k, v]) => [
+    "-e",
+    `${k}=${v}`
+  ]);
+  const selinuxLabel = options?.selinuxLabel ?? "z";
+  const volumeFlags = (options?.volumeMounts ?? []).flatMap((mount) => [
+    "-v",
+    formatVolumeMount(mount, selinuxLabel)
+  ]);
+  const workdirFlags = options?.workdir ? ["-w", options.workdir] : [];
+  const userFlags = options?.user ? ["--user", options.user] : [];
+  const networks = options?.network ? Array.isArray(options.network) ? options.network : [options.network] : [];
+  const networkFlags = networks.flatMap((n) => ["--network", n]);
+  const groupAddFlags = (options?.groups ?? []).flatMap((g) => [
+    "--group-add",
+    String(g)
+  ]);
+  const deviceFlags = (options?.devices ?? []).flatMap((d) => [
+    "--device",
+    d
+  ]);
+  const cpusFlags = options?.cpus !== void 0 ? ["--cpus", String(options.cpus)] : [];
+  yield* dockerExec([
+    "run",
+    "-d",
+    "--name",
+    containerName,
+    ...envFlags,
+    ...volumeFlags,
+    ...workdirFlags,
+    ...userFlags,
+    ...networkFlags,
+    ...groupAddFlags,
+    ...deviceFlags,
+    ...cpusFlags,
+    imageName
+  ]);
+});
+var removeContainer = (containerName) => Effect_exports.gen(function* () {
+  yield* Effect_exports.ignore(dockerExec(["stop", containerName]));
+  yield* Effect_exports.ignore(dockerExec(["rm", containerName]));
+});
+var removeImage = (imageName) => Effect_exports.gen(function* () {
+  yield* dockerExec(["rmi", imageName]);
+});
+
+// src/sandboxes/docker.ts
+var docker = (options) => {
+  const configuredImageName = options?.imageName;
+  const selinuxLabel = options?.selinuxLabel ?? "z";
+  const maxOutputTailChars = options?.maxOutputTailChars ?? MAX_TAIL_CHARS;
+  const sandboxHomedir = "/home/agent";
+  const userMounts = options?.mounts ? resolveUserMounts(options.mounts, sandboxHomedir) : [];
+  const parentDirsToCreate = processFileMountParents(
+    userMounts,
+    sandboxHomedir
+  );
+  return createBindMountSandboxProvider({
+    name: "docker",
+    env: options?.env,
+    sandboxHomedir,
+    create: async (createOptions) => {
+      const containerName = `sandcastle-${randomUUID()}`;
+      const worktreePath = createOptions.mounts.find(
+        (m) => m.hostPath === createOptions.worktreePath
+      )?.sandboxPath ?? "/home/agent/workspace";
+      const allMounts = [...createOptions.mounts, ...userMounts];
+      const volumeMounts = allMounts.map((m) => ({
+        hostPath: m.hostPath,
+        sandboxPath: m.sandboxPath,
+        readonly: m.readonly
+      }));
+      const imageName = configuredImageName ?? defaultImageName(createOptions.hostRepoPath);
+      const containerUid = options?.containerUid ?? process.getuid?.() ?? 1e3;
+      const containerGid = options?.containerGid ?? process.getgid?.() ?? 1e3;
+      await checkImageUid(imageName, containerUid);
+      await Effect_exports.runPromise(
+        startContainer(
+          containerName,
+          imageName,
+          {
+            ...createOptions.env,
+            HOME: "/home/agent"
+          },
+          {
+            volumeMounts,
+            workdir: worktreePath,
+            user: `${containerUid}:${containerGid}`,
+            network: options?.network,
+            groups: options?.groups,
+            devices: options?.devices,
+            cpus: options?.cpus,
+            selinuxLabel
+          }
+        )
+      );
+      for (const dir of parentDirsToCreate) {
+        await new Promise((resolve2, reject) => {
+          execFile(
+            "docker",
+            [
+              "exec",
+              "--user",
+              "0:0",
+              containerName,
+              "sh",
+              "-c",
+              `mkdir -p "$1" && chown "$2" "$1"`,
+              "sh",
+              dir,
+              `${containerUid}:${containerGid}`
+            ],
+            (error) => {
+              if (error) {
+                reject(
+                  new Error(
+                    `Failed to create parent directory '${dir}' in container: ${error.message}`
+                  )
+                );
+              } else {
+                resolve2();
+              }
+            }
+          );
+        });
+      }
+      const removeContainerSync = () => {
+        try {
+          execFileSync("docker", ["rm", "-f", containerName], {
+            stdio: "ignore"
+          });
+        } catch {
+        }
+      };
+      const unregisterShutdown = registerShutdown(removeContainerSync);
+      const handle = {
+        worktreePath,
+        exec: (command, opts) => {
+          const effectiveCommand = opts?.sudo ? `sudo ${command}` : command;
+          const args = ["exec"];
+          if (opts?.stdin !== void 0) args.push("-i");
+          if (opts?.cwd) args.push("-w", opts.cwd);
+          args.push(containerName, "sh", "-c", effectiveCommand);
+          return new Promise((resolve2, reject) => {
+            const proc = spawn("docker", args, {
+              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(`docker 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) => {
+                resolve2({
+                  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) => {
+                resolve2({
+                  stdout: stdoutChunks.join(""),
+                  stderr: stderrChunks.join(""),
+                  exitCode: code ?? 0
+                });
+              });
+            }
+          });
+        },
+        interactiveExec: (args, opts) => {
+          return new Promise((resolve2, reject) => {
+            const dockerArgs = ["exec"];
+            if ("isTTY" in opts.stdin && opts.stdin.isTTY) {
+              dockerArgs.push("-it");
+            } else {
+              dockerArgs.push("-i");
+            }
+            if (opts.cwd) dockerArgs.push("-w", opts.cwd);
+            dockerArgs.push(containerName, ...args);
+            const proc = spawn("docker", dockerArgs, {
+              stdio: [opts.stdin, opts.stdout, opts.stderr]
+            });
+            proc.on("error", (error) => {
+              reject(new Error(`docker exec failed: ${error.message}`));
+            });
+            proc.on("close", (code) => {
+              resolve2({ exitCode: code ?? 0 });
+            });
+          });
+        },
+        copyFileIn: (hostPath, sandboxPath) => new Promise((resolve2, reject) => {
+          execFile(
+            "docker",
+            ["cp", hostPath, `${containerName}:${sandboxPath}`],
+            (error) => {
+              if (error) {
+                reject(new Error(`docker cp (in) failed: ${error.message}`));
+              } else {
+                resolve2();
+              }
+            }
+          );
+        }),
+        copyFileOut: (sandboxPath, hostPath) => new Promise((resolve2, reject) => {
+          execFile(
+            "docker",
+            ["cp", `${containerName}:${sandboxPath}`, hostPath],
+            (error) => {
+              if (error) {
+                reject(new Error(`docker cp (out) failed: ${error.message}`));
+              } else {
+                resolve2();
+              }
+            }
+          );
+        }),
+        close: async () => {
+          unregisterShutdown();
+          await Effect_exports.runPromise(removeContainer(containerName));
+        }
+      };
+      return handle;
+    }
+  });
+};
+var checkImageUid = (imageName, expectedUid) => new Promise((resolve2, reject) => {
+  execFile(
+    "docker",
+    ["image", "inspect", imageName, "--format", "{{.Config.User}}"],
+    (error, stdout) => {
+      if (error) {
+        reject(
+          new Error(
+            `Image '${imageName}' not found locally. Build it first with 'sandcastle docker build-image'.`
+          )
+        );
+        return;
+      }
+      const imageUser = (stdout ?? "").toString().trim();
+      if (!imageUser) {
+        resolve2();
+        return;
+      }
+      const uidPart = imageUser.split(":")[0];
+      const imageUid = parseInt(uidPart, 10);
+      if (isNaN(imageUid)) {
+        resolve2();
+        return;
+      }
+      if (imageUid !== expectedUid) {
+        reject(
+          new Error(
+            `UID mismatch: image '${imageName}' was built with UID ${imageUid}, but the expected UID is ${expectedUid}. Rebuild the image with 'sandcastle docker build-image', or pass containerUid: ${imageUid} to docker() to match the image.`
+          )
+        );
+      } else {
+        resolve2();
+      }
+    }
+  );
+});
+
+export { buildImage, docker, removeImage };
+//# sourceMappingURL=chunk-NSFQW6ML.js.map
+//# sourceMappingURL=chunk-NSFQW6ML.js.map