@rockclaver/sandcastle 0.7.0

package/dist/mountUtils-CCA-bbpK.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared mount utilities for Docker and Podman sandbox providers.
+ *
+ * Handles host/sandbox path resolution, tilde expansion, user mount
+ * validation, image naming, and Windows path normalization.
+ */
+
+/**
+ * SELinux volume label suffix applied to bind mounts.
+ *
+ * - `"z"` — shared label. No-op on non-SELinux systems.
+ * - `"Z"` — private label; only this container can access the mount.
+ * - `false` — disable labeling entirely.
+ */
+type SelinuxLabel = "z" | "Z" | false;
+/**
+ * Derive the default image name from the repo directory.
+ * Returns `sandcastle:<dir-name>` where dir-name is the last path segment,
+ * lowercased and sanitized for image tag rules.
+ *
+ * Handles both POSIX (`/`) and Windows (`\`) path separators.
+ */
+declare const defaultImageName: (repoDir: string) => string;
+
+export { type SelinuxLabel as S, defaultImageName as d };

package/dist/sandboxes/daytona.d.ts

@@ -0,0 +1,60 @@
+import { I as IsolatedSandboxProvider } from '../SandboxProvider-EkSMuBp8.js';
+import { CreateSandboxFromImageParams, CreateSandboxFromSnapshotParams } from '@daytona/sdk';
+
+/**
+ * Daytona isolated sandbox provider.
+ *
+ * Creates ephemeral Daytona sandboxes via `@daytona/sdk`.
+ * Requires `@daytona/sdk` as a peer dependency.
+ */
+
+/** Options for the Daytona sandbox provider. */
+interface DaytonaOptions {
+    /**
+     * Daytona API key for authentication.
+     * Falls back to the `DAYTONA_API_KEY` environment variable if not provided.
+     */
+    readonly apiKey?: string;
+    /**
+     * Daytona API URL.
+     * Falls back to the `DAYTONA_API_URL` environment variable if not provided.
+     */
+    readonly apiUrl?: string;
+    /**
+     * Target environment for sandboxes.
+     * Falls back to the `DAYTONA_TARGET` environment variable if not provided.
+     */
+    readonly target?: string;
+    /**
+     * Options passed through to the Daytona SDK when creating a sandbox.
+     * Supports both image-based and snapshot-based creation.
+     */
+    readonly create?: CreateSandboxFromImageParams | CreateSandboxFromSnapshotParams;
+    /** Environment variables injected by this provider. Merged at launch time with env resolver and agent provider env. */
+    readonly env?: Record<string, string>;
+    /**
+     * Maximum number of characters of streamed `exec` output retained per stream
+     * (stdout and stderr) when an `onLine` callback is supplied (default: 64KiB).
+     *
+     * Output is delivered live to `onLine` regardless; this only bounds the tail
+     * returned in `ExecResult`, preventing a long-running agent's output from
+     * overflowing V8's max string length and crashing the run.
+     */
+    readonly maxOutputTailChars?: number;
+}
+/**
+ * Create a Daytona isolated sandbox provider.
+ *
+ * Sandboxes are ephemeral — each `create()` call spins up a new Daytona
+ * sandbox and `close()` destroys it.
+ *
+ * @example
+ * ```ts
+ * import { daytona } from "@ai-hero/sandcastle/sandboxes/daytona";
+ *
+ * const provider = daytona({ apiKey: "dyt_my_key" });
+ * ```
+ */
+declare const daytona: (options?: DaytonaOptions) => IsolatedSandboxProvider;
+
+export { type DaytonaOptions, daytona };

package/dist/sandboxes/daytona.js

@@ -0,0 +1,122 @@
+import { createRequire } from 'node:module';
+import { createIsolatedSandboxProvider } from '../chunk-BIWNFKGV.js';
+import { MAX_TAIL_CHARS, BoundedTail } from '../chunk-NGBM7T3E.js';
+import { stat, readdir } from 'fs/promises';
+import { relative, join } from 'path';
+
+createRequire(import.meta.url);
+var daytona = (options) => createIsolatedSandboxProvider({
+  name: "daytona",
+  env: options?.env,
+  create: async () => {
+    const maxOutputTailChars = options?.maxOutputTailChars ?? MAX_TAIL_CHARS;
+    const { Daytona } = await import('@daytona/sdk');
+    const config = {};
+    if (options?.apiKey) config.apiKey = options.apiKey;
+    if (options?.apiUrl) config.apiUrl = options.apiUrl;
+    if (options?.target) config.target = options.target;
+    const client = new Daytona(config);
+    const sandbox = await client.create(options?.create);
+    const worktreePath = await sandbox.getWorkDir() ?? await sandbox.getUserHomeDir() ?? "/home/daytona";
+    return {
+      worktreePath,
+      exec: async (command, opts) => {
+        const effectiveCommand = opts?.sudo ? `sudo ${command}` : command;
+        if (opts?.onLine) {
+          const onLine = opts.onLine;
+          const sessionId = `sandcastle-${crypto.randomUUID()}`;
+          await sandbox.process.createSession(sessionId);
+          try {
+            const execResponse = await sandbox.process.executeSessionCommand(
+              sessionId,
+              {
+                command: `cd ${opts?.cwd ?? worktreePath} && ${effectiveCommand}`,
+                async: true
+              }
+            );
+            const cmdId = execResponse.cmdId;
+            const stdoutTail = new BoundedTail(maxOutputTailChars, "\n");
+            const stderrTail = new BoundedTail(maxOutputTailChars, "");
+            let partial = "";
+            await sandbox.process.getSessionCommandLogs(
+              sessionId,
+              cmdId,
+              (chunk) => {
+                const text = partial + chunk;
+                const lines = text.split("\n");
+                partial = lines.pop() ?? "";
+                for (const line of lines) {
+                  stdoutTail.push(line);
+                  onLine(line);
+                }
+              },
+              (chunk) => {
+                stderrTail.push(chunk);
+              }
+            );
+            if (partial) {
+              stdoutTail.push(partial);
+              onLine(partial);
+            }
+            const cmdInfo = await sandbox.process.getSessionCommand(
+              sessionId,
+              cmdId
+            );
+            return {
+              stdout: stdoutTail.toString(),
+              stderr: stderrTail.toString(),
+              exitCode: cmdInfo.exitCode ?? 0
+            };
+          } finally {
+            await sandbox.process.deleteSession(sessionId).catch(() => {
+            });
+          }
+        }
+        const response = await sandbox.process.executeCommand(
+          effectiveCommand,
+          opts?.cwd ?? worktreePath
+        );
+        return {
+          stdout: response.result,
+          stderr: "",
+          exitCode: response.exitCode
+        };
+      },
+      copyIn: async (hostPath, sandboxPath) => {
+        const info = await stat(hostPath);
+        if (info.isDirectory()) {
+          const walk = async (dir) => {
+            const entries = await readdir(dir, { withFileTypes: true });
+            const files2 = [];
+            for (const entry of entries) {
+              const full = join(dir, entry.name);
+              if (entry.isDirectory()) {
+                files2.push(...await walk(full));
+              } else {
+                files2.push(full);
+              }
+            }
+            return files2;
+          };
+          const files = await walk(hostPath);
+          for (const file of files) {
+            const rel = relative(hostPath, file);
+            await sandbox.fs.uploadFile(file, join(sandboxPath, rel));
+          }
+        } else {
+          await sandbox.fs.uploadFile(hostPath, sandboxPath);
+        }
+      },
+      copyFileOut: async (sandboxPath, hostPath) => {
+        await sandbox.fs.downloadFile(sandboxPath, hostPath);
+      },
+      close: async () => {
+        await client.delete(sandbox);
+      }
+    };
+  }
+});
+
+export { daytona };
+//# sourceMappingURL=daytona.js.map
+//# sourceMappingURL=daytona.js.map

package/dist/sandboxes/daytona.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/sandboxes/daytona.ts"],"names":["files"],"mappings":"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","file":"daytona.js","sourcesContent":["/**\n * Daytona isolated sandbox provider.\n *\n * Creates ephemeral Daytona sandboxes via `@daytona/sdk`.\n * Requires `@daytona/sdk` as a peer dependency.\n */\n\nimport { readdir, stat } from \"node:fs/promises\";\nimport { join, relative } from \"node:path\";\nimport {\n  createIsolatedSandboxProvider,\n  type ExecResult,\n  type IsolatedSandboxHandle,\n  type IsolatedSandboxProvider,\n} from \"../SandboxProvider.js\";\nimport { BoundedTail, MAX_TAIL_CHARS } from \"../boundedTail.js\";\n\nimport type {\n  Daytona as DaytonaClient,\n  DaytonaConfig,\n  CreateSandboxFromImageParams,\n  CreateSandboxFromSnapshotParams,\n} from \"@daytona/sdk\";\n\n/** Options for the Daytona sandbox provider. */\nexport interface DaytonaOptions {\n  /**\n   * Daytona API key for authentication.\n   * Falls back to the `DAYTONA_API_KEY` environment variable if not provided.\n   */\n  readonly apiKey?: string;\n\n  /**\n   * Daytona API URL.\n   * Falls back to the `DAYTONA_API_URL` environment variable if not provided.\n   */\n  readonly apiUrl?: string;\n\n  /**\n   * Target environment for sandboxes.\n   * Falls back to the `DAYTONA_TARGET` environment variable if not provided.\n   */\n  readonly target?: string;\n\n  /**\n   * Options passed through to the Daytona SDK when creating a sandbox.\n   * Supports both image-based and snapshot-based creation.\n   */\n  readonly create?:\n    | CreateSandboxFromImageParams\n    | CreateSandboxFromSnapshotParams;\n\n  /** Environment variables injected by this provider. Merged at launch time with env resolver and agent provider env. */\n  readonly env?: Record<string, string>;\n\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 Daytona isolated sandbox provider.\n *\n * Sandboxes are ephemeral — each `create()` call spins up a new Daytona\n * sandbox and `close()` destroys it.\n *\n * @example\n * ```ts\n * import { daytona } from \"@ai-hero/sandcastle/sandboxes/daytona\";\n *\n * const provider = daytona({ apiKey: \"dyt_my_key\" });\n * ```\n */\nexport const daytona = (options?: DaytonaOptions): IsolatedSandboxProvider =>\n  createIsolatedSandboxProvider({\n    name: \"daytona\",\n    env: options?.env,\n    create: async (): Promise<IsolatedSandboxHandle> => {\n      const maxOutputTailChars = options?.maxOutputTailChars ?? MAX_TAIL_CHARS;\n      const { Daytona } =\n        (await import(\"@daytona/sdk\")) as typeof import(\"@daytona/sdk\");\n\n      const config: DaytonaConfig = {};\n      if (options?.apiKey) config.apiKey = options.apiKey;\n      if (options?.apiUrl) config.apiUrl = options.apiUrl;\n      if (options?.target) config.target = options.target;\n\n      const client: DaytonaClient = new Daytona(config);\n      const sandbox = await client.create(options?.create as any);\n\n      const worktreePath =\n        (await sandbox.getWorkDir()) ??\n        (await sandbox.getUserHomeDir()) ??\n        \"/home/daytona\";\n\n      return {\n        worktreePath,\n\n        exec: async (\n          command: string,\n          opts?: {\n            onLine?: (line: string) => void;\n            cwd?: string;\n            sudo?: boolean;\n          },\n        ): Promise<ExecResult> => {\n          const effectiveCommand = opts?.sudo ? `sudo ${command}` : command;\n          if (opts?.onLine) {\n            const onLine = opts.onLine;\n            const sessionId = `sandcastle-${crypto.randomUUID()}`;\n            await sandbox.process.createSession(sessionId);\n\n            try {\n              const execResponse = await sandbox.process.executeSessionCommand(\n                sessionId,\n                {\n                  command: `cd ${opts?.cwd ?? worktreePath} && ${effectiveCommand}`,\n                  async: true,\n                },\n              );\n\n              const cmdId = execResponse.cmdId!;\n\n              const stdoutTail = new BoundedTail(maxOutputTailChars, \"\\n\");\n              const stderrTail = new BoundedTail(maxOutputTailChars, \"\");\n              let partial = \"\";\n\n              await sandbox.process.getSessionCommandLogs(\n                sessionId,\n                cmdId,\n                (chunk: string) => {\n                  const text = partial + chunk;\n                  const lines = text.split(\"\\n\");\n                  partial = lines.pop() ?? \"\";\n                  for (const line of lines) {\n                    stdoutTail.push(line);\n                    onLine(line);\n                  }\n                },\n                (chunk: string) => {\n                  stderrTail.push(chunk);\n                },\n              );\n\n              if (partial) {\n                stdoutTail.push(partial);\n                onLine(partial);\n              }\n\n              const cmdInfo = await sandbox.process.getSessionCommand(\n                sessionId,\n                cmdId,\n              );\n\n              return {\n                stdout: stdoutTail.toString(),\n                stderr: stderrTail.toString(),\n                exitCode: cmdInfo.exitCode ?? 0,\n              };\n            } finally {\n              await sandbox.process.deleteSession(sessionId).catch(() => {});\n            }\n          }\n\n          const response = await sandbox.process.executeCommand(\n            effectiveCommand,\n            opts?.cwd ?? worktreePath,\n          );\n          return {\n            stdout: response.result,\n            stderr: \"\",\n            exitCode: response.exitCode,\n          };\n        },\n\n        copyIn: async (\n          hostPath: string,\n          sandboxPath: string,\n        ): Promise<void> => {\n          const info = await stat(hostPath);\n          if (info.isDirectory()) {\n            const walk = async (dir: string): Promise<string[]> => {\n              const entries = await readdir(dir, { withFileTypes: true });\n              const files: string[] = [];\n              for (const entry of entries) {\n                const full = join(dir, entry.name);\n                if (entry.isDirectory()) {\n                  files.push(...(await walk(full)));\n                } else {\n                  files.push(full);\n                }\n              }\n              return files;\n            };\n            const files = await walk(hostPath);\n            for (const file of files) {\n              const rel = relative(hostPath, file);\n              await sandbox.fs.uploadFile(file, join(sandboxPath, rel));\n            }\n          } else {\n            await sandbox.fs.uploadFile(hostPath, sandboxPath);\n          }\n        },\n\n        copyFileOut: async (\n          sandboxPath: string,\n          hostPath: string,\n        ): Promise<void> => {\n          await sandbox.fs.downloadFile(sandboxPath, hostPath);\n        },\n\n        close: async (): Promise<void> => {\n          await client.delete(sandbox);\n        },\n      };\n    },\n  });\n"]}

package/dist/sandboxes/docker.d.ts

@@ -0,0 +1,110 @@
+import { S as SandboxProvider } from '../SandboxProvider-EkSMuBp8.js';
+import { M as MountConfig } from '../MountConfig-CmXclHA5.js';
+import { S as SelinuxLabel } from '../mountUtils-CCA-bbpK.js';
+export { d as defaultImageName } from '../mountUtils-CCA-bbpK.js';
+
+/**
+ * Docker sandbox provider — wraps DockerLifecycle into a SandboxProvider.
+ *
+ * Usage:
+ *   import { docker } from "sandcastle/sandboxes/docker";
+ *   await run({ agent: claudeCode("claude-opus-4-7"), sandbox: docker() });
+ */
+
+interface DockerOptions {
+    /** Docker image name (default: derived from repo directory name). */
+    readonly imageName?: string;
+    /**
+     * The UID of the `agent` user inside the container image (default: host UID via `process.getuid()`, or 1000).
+     *
+     * Must match the UID baked into the image at build time. Used as the `--user` flag value
+     * and checked against the image's configured UID in the pre-flight diagnostic.
+     */
+    readonly containerUid?: number;
+    /**
+     * The GID of the `agent` user inside the container image (default: host GID via `process.getgid()`, or 1000).
+     *
+     * Must match the GID baked into the image at build time. Used as the `--user` flag value.
+     */
+    readonly containerGid?: number;
+    /**
+     * SELinux volume label suffix applied to bind mounts.
+     *
+     * - `"z"` — shared label (default). No-op on non-SELinux systems.
+     * - `"Z"` — private label; only this container can access the mount.
+     * - `false` — disable labeling entirely.
+     */
+    readonly selinuxLabel?: SelinuxLabel;
+    /**
+     * Additional host directories to bind-mount into the sandbox.
+     *
+     * Each entry specifies a `hostPath` (tilde-expanded) and `sandboxPath`.
+     * If `hostPath` does not exist, sandbox creation fails with a clear error.
+     */
+    readonly mounts?: readonly MountConfig[];
+    /** Environment variables injected by this provider. Merged at launch time with env resolver and agent provider env. */
+    readonly env?: Record<string, string>;
+    /**
+     * Docker network(s) to attach the container to.
+     *
+     * - `"my-network"` → `--network my-network`
+     * - `["net1", "net2"]` → `--network net1 --network net2`
+     *
+     * When omitted, Docker's default bridge network is used.
+     */
+    readonly network?: string | readonly string[];
+    /**
+     * Supplementary groups to add the container user to, via `--group-add`.
+     *
+     * Accepts group names or numeric GIDs:
+     *
+     * - `["docker"]` → `--group-add docker`
+     * - `[999]` → `--group-add 999`
+     * - `["docker", 999]` → `--group-add docker --group-add 999`
+     *
+     * Useful for granting access to a bind-mounted Docker socket (Docker-outside-of-Docker).
+     * When omitted, no `--group-add` flags are added.
+     */
+    readonly groups?: readonly (string | number)[];
+    /**
+     * Host devices to expose to the container, via `--device`.
+     *
+     * Each entry is a full device spec in `host[:container[:permissions]]` form:
+     *
+     * - `["/dev/kvm"]` → `--device /dev/kvm`
+     * - `["/dev/sda:/dev/xvda:rwm"]` → `--device /dev/sda:/dev/xvda:rwm`
+     * - `["/dev/kvm", "/dev/fuse"]` → `--device /dev/kvm --device /dev/fuse`
+     *
+     * When omitted, no `--device` flags are added.
+     */
+    readonly devices?: readonly string[];
+    /**
+     * Maximum number of characters of streamed `exec` output retained per stream
+     * (stdout and stderr) when an `onLine` callback is supplied (default: 64KiB).
+     *
+     * Output is delivered live to `onLine` regardless; this only bounds the tail
+     * returned in `ExecResult`, preventing a long-running agent's output from
+     * overflowing V8's max string length and crashing the run.
+     */
+    readonly maxOutputTailChars?: number;
+    /**
+     * Limit the CPU resources available to the container, via `--cpus`.
+     *
+     * Maps directly to `docker run --cpus`. Accepts fractional values:
+     *
+     * - `2` → `--cpus 2` (at most 2 CPUs)
+     * - `1.5` → `--cpus 1.5` (at most 1.5 CPUs)
+     *
+     * When omitted, no `--cpus` flag is added and the container is unconstrained.
+     */
+    readonly cpus?: number;
+}
+/**
+ * Create a Docker sandbox provider.
+ *
+ * The returned provider creates Docker containers with bind-mounts
+ * for the worktree and git directories.
+ */
+declare const docker: (options?: DockerOptions) => SandboxProvider;
+
+export { type DockerOptions, docker };

package/dist/sandboxes/docker.js

@@ -0,0 +1,9 @@
+import { createRequire } from 'node:module';
+export { docker } from '../chunk-FKX3DRTL.js';
+export { defaultImageName } from '../chunk-VAKEM3U2.js';
+import '../chunk-BIWNFKGV.js';
+import '../chunk-NGBM7T3E.js';
+
+createRequire(import.meta.url);
+//# sourceMappingURL=docker.js.map
+//# sourceMappingURL=docker.js.map

package/dist/sandboxes/docker.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"docker.js"}

package/dist/sandboxes/no-sandbox.d.ts

@@ -0,0 +1,38 @@
+import { N as NoSandboxProvider } from '../SandboxProvider-EkSMuBp8.js';
+
+/**
+ * No-sandbox provider — runs the agent directly on the host with no container isolation.
+ *
+ * Usage:
+ *   import { noSandbox } from "sandcastle/sandboxes/no-sandbox";
+ *   await interactive({ agent: claudeCode("claude-opus-4-7"), sandbox: noSandbox() });
+ *
+ * Accepted by `run()`, `interactive()`, and `createSandbox()`. Skips
+ * container isolation entirely — the agent executes on the host. Does not
+ * pass `--dangerously-skip-permissions` to the agent — the user manages
+ * permissions themselves.
+ */
+
+interface NoSandboxOptions {
+    /** Environment variables injected by this provider. Merged at launch time. */
+    readonly env?: Record<string, string>;
+    /**
+     * Maximum number of characters of streamed `exec` output retained per stream
+     * (stdout and stderr) when an `onLine` callback is supplied (default: 64KiB).
+     *
+     * Output is delivered live to `onLine` regardless; this only bounds the tail
+     * returned in `ExecResult`, preventing a long-running agent's output from
+     * overflowing V8's max string length and crashing the run.
+     */
+    readonly maxOutputTailChars?: number;
+}
+/**
+ * Create a no-sandbox provider.
+ *
+ * The returned provider runs the agent directly on the host. All three
+ * branch strategies are supported (head, merge-to-head, branch),
+ * defaulting to head.
+ */
+declare const noSandbox: (options?: NoSandboxOptions) => NoSandboxProvider;
+
+export { type NoSandboxOptions, noSandbox };

package/dist/sandboxes/no-sandbox.js

@@ -0,0 +1,7 @@
+import { createRequire } from 'node:module';
+export { noSandbox } from '../chunk-72UVAC7B.js';
+import '../chunk-NGBM7T3E.js';
+
+createRequire(import.meta.url);
+//# sourceMappingURL=no-sandbox.js.map
+//# sourceMappingURL=no-sandbox.js.map

package/dist/sandboxes/no-sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"no-sandbox.js"}

package/dist/sandboxes/podman.d.ts

@@ -0,0 +1,124 @@
+import { S as SandboxProvider } from '../SandboxProvider-EkSMuBp8.js';
+import { M as MountConfig } from '../MountConfig-CmXclHA5.js';
+import { S as SelinuxLabel } from '../mountUtils-CCA-bbpK.js';
+export { d as defaultImageName } from '../mountUtils-CCA-bbpK.js';
+
+/**
+ * Podman sandbox provider — creates Podman containers with bind-mounts.
+ *
+ * Usage:
+ *   import { podman } from "sandcastle/sandboxes/podman";
+ *   await run({ agent: claudeCode("claude-opus-4-7"), sandbox: podman() });
+ */
+
+interface PodmanOptions {
+    /** Podman image name (default: derived from repo directory name). */
+    readonly imageName?: string;
+    /**
+     * SELinux volume label suffix applied to bind mounts.
+     *
+     * - `"z"` — shared label (default). No-op on non-SELinux systems.
+     * - `"Z"` — private label; only this container can access the mount.
+     * - `false` — disable labeling entirely.
+     */
+    readonly selinuxLabel?: SelinuxLabel;
+    /**
+     * User namespace mode for rootless Podman.
+     *
+     * - `"keep-id"` (default) — maps host UID to `containerUid` inside the
+     *   container via `--userns=keep-id:uid=N,gid=N`, so both bind-mounted
+     *   files and image-built files have correct ownership without chown.
+     * - `false` — disable; use for rootful Podman setups.
+     */
+    readonly userns?: "keep-id" | false;
+    /**
+     * The UID of the `agent` user inside the container image (default: 1000).
+     *
+     * Must match the UID set in the Containerfile. Used with `--userns=keep-id`
+     * to map the host user to this UID inside the container.
+     */
+    readonly containerUid?: number;
+    /**
+     * The GID of the `agent` user inside the container image (default: 1000).
+     *
+     * Must match the GID set in the Containerfile. Used with `--userns=keep-id`
+     * to map the host group to this GID inside the container.
+     */
+    readonly containerGid?: number;
+    /**
+     * Additional host directories to bind-mount into the sandbox.
+     *
+     * Each entry specifies a `hostPath` (tilde-expanded) and `sandboxPath`.
+     * If `hostPath` does not exist, sandbox creation fails with a clear error.
+     */
+    readonly mounts?: readonly MountConfig[];
+    /** Environment variables injected by this provider. Merged at launch time with env resolver and agent provider env. */
+    readonly env?: Record<string, string>;
+    /**
+     * Podman network(s) to attach the container to.
+     *
+     * - `"my-network"` → `--network my-network`
+     * - `["net1", "net2"]` → `--network net1 --network net2`
+     *
+     * When omitted, Podman's default network is used.
+     */
+    readonly network?: string | readonly string[];
+    /**
+     * Supplementary groups to add the container user to, via `--group-add`.
+     *
+     * Accepts group names or numeric GIDs:
+     *
+     * - `["docker"]` → `--group-add docker`
+     * - `[999]` → `--group-add 999`
+     * - `["docker", 999]` → `--group-add docker --group-add 999`
+     *
+     * Useful for granting access to a bind-mounted Docker socket (Docker-outside-of-Docker).
+     * When omitted, no `--group-add` flags are added.
+     */
+    readonly groups?: readonly (string | number)[];
+    /**
+     * Host devices to expose to the container, via `--device`.
+     *
+     * Each entry is a full device spec in `host[:container[:permissions]]` form:
+     *
+     * - `["/dev/kvm"]` → `--device /dev/kvm`
+     * - `["/dev/sda:/dev/xvda:rwm"]` → `--device /dev/sda:/dev/xvda:rwm`
+     * - `["/dev/kvm", "/dev/fuse"]` → `--device /dev/kvm --device /dev/fuse`
+     *
+     * Under rootless Podman, exposing a host device often requires host-side
+     * group/permission setup and may interact with `--userns=keep-id`.
+     * When omitted, no `--device` flags are added.
+     */
+    readonly devices?: readonly string[];
+    /**
+     * Maximum number of characters of streamed `exec` output retained per stream
+     * (stdout and stderr) when an `onLine` callback is supplied (default: 64KiB).
+     *
+     * Output is delivered live to `onLine` regardless; this only bounds the tail
+     * returned in `ExecResult`, preventing a long-running agent's output from
+     * overflowing V8's max string length and crashing the run.
+     */
+    readonly maxOutputTailChars?: number;
+    /**
+     * Limit the CPU resources available to the container, via `--cpus`.
+     *
+     * Maps directly to `podman run --cpus`. Accepts fractional values:
+     *
+     * - `2` → `--cpus 2` (at most 2 CPUs)
+     * - `1.5` → `--cpus 1.5` (at most 1.5 CPUs)
+     *
+     * When omitted, no `--cpus` flag is added and the container is unconstrained.
+     */
+    readonly cpus?: number;
+}
+/**
+ * Create a Podman sandbox provider.
+ *
+ * The returned provider creates Podman containers with bind-mounts
+ * for the worktree and git directories. Calls the `podman` binary
+ * on PATH directly. On macOS/Windows, verifies that a Podman Machine
+ * is running before container creation.
+ */
+declare const podman: (options?: PodmanOptions) => SandboxProvider;
+
+export { type PodmanOptions, podman };