@snappedly-tools/shipyard 0.2.0

package/dist/sandboxes/docker.d.ts

@@ -0,0 +1,125 @@
+import { I as IsolatedSandboxProvider } from '../SandboxProvider-KeFp_nju.js';
+import { M as MountConfig } from '../MountConfig-bZoCs4Dd.js';
+
+/**
+ * Shared mount utilities for the Docker sandbox provider.
+ *
+ * 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 `shipyard:<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;
+
+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 isolated repository and Git storage.
+ * Changes are transferred through git bundle and validated sync-out.
+ */
+declare const docker: (options?: DockerOptions) => IsolatedSandboxProvider;
+
+export { type DockerOptions, defaultImageName, docker };

package/dist/sandboxes/docker.js

@@ -0,0 +1,9 @@
+import { createRequire } from 'node:module';
+export { docker } from '../chunk-OAHPDSOJ.js';
+export { defaultImageName } from '../chunk-4VDXZY7T.js';
+import '../chunk-CP6YEQKU.js';
+import '../chunk-BU6XJFJ2.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,37 @@
+import { N as NoSandboxProvider } from '../SandboxProvider-KeFp_nju.js';
+
+/**
+ * No-sandbox provider — runs the agent directly on the host with no container isolation.
+ *
+ * Usage:
+ *   import { noSandbox } from "@snappedly-tools/shipyard/sandboxes/no-sandbox";
+ *   await run({ agent: codex(CODEX_MODELS.routine), sandbox: noSandbox(), prompt: "..." });
+ *
+ * Accepted by `run()`, `interactive()`, and `createSandbox()`. It skips
+ * container isolation entirely and does not pass
+ * `--dangerously-skip-permissions` to the agent.
+ */
+
+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-YVJHSJUW.js';
+import '../chunk-BU6XJFJ2.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/vercel.d.ts

@@ -0,0 +1,104 @@
+import { I as IsolatedSandboxProvider } from '../SandboxProvider-KeFp_nju.js';
+
+/**
+ * Vercel isolated sandbox provider — wraps `@vercel/sandbox` into a SandboxProvider.
+ *
+ * Usage:
+ *   import { vercel } from "@snappedly-tools/shipyard/sandboxes/vercel";
+ *   await run({ agent: codex(CODEX_MODELS.routine), sandbox: vercel() });
+ */
+
+/**
+ * Options for creating a Vercel sandbox provider.
+ *
+ * All `@vercel/sandbox` `Sandbox.create()` options are accepted as pass-through,
+ * plus Shipyard-specific options for auth and branch strategy.
+ */
+interface VercelOptions {
+    /**
+     * Vercel access token.
+     *
+     * Falls back to the SDK's default auth behavior, which reads
+     * `VERCEL_OIDC_TOKEN` (recommended for Vercel-hosted environments) or
+     * `VERCEL_TOKEN` from the environment.
+     */
+    readonly token?: string;
+    /**
+     * The source of the sandbox (git repo, tarball, or snapshot).
+     * Omit to start an empty sandbox.
+     */
+    readonly source?: {
+        type: "git";
+        url: string;
+        depth?: number;
+        revision?: string;
+        username?: string;
+        password?: string;
+    } | {
+        type: "tarball";
+        url: string;
+    } | {
+        type: "snapshot";
+        snapshotId: string;
+    };
+    /** Array of port numbers to expose from the sandbox (up to 4). */
+    readonly ports?: number[];
+    /** Timeout in milliseconds before the sandbox auto-terminates. */
+    readonly timeout?: number;
+    /**
+     * Resources to allocate to the sandbox.
+     * Each vCPU gets 2048 MB of memory.
+     */
+    readonly resources?: {
+        vcpus: number;
+    };
+    /**
+     * The runtime of the sandbox (e.g. `"node24"`, `"node22"`, `"python3.13"`).
+     * Defaults to `"node24"`.
+     */
+    readonly runtime?: string;
+    /**
+     * Network policy for the sandbox.
+     * Defaults to full internet access if not specified.
+     */
+    readonly networkPolicy?: Record<string, unknown>;
+    /**
+     * Vercel project ID to associate sandbox operations with.
+     */
+    readonly projectId?: string;
+    /**
+     * Vercel team ID to associate sandbox operations with.
+     */
+    readonly teamId?: string;
+    /**
+     * Timeout in milliseconds (alias for `timeout`, kept for discoverability).
+     */
+    readonly timeoutMs?: number;
+    /**
+     * Sandbox template shorthand (e.g. `"node-22"`).
+     * Maps to the `runtime` option.
+     */
+    readonly template?: string;
+    /** 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 Vercel isolated sandbox provider.
+ *
+ * The returned provider creates Vercel Firecracker microVM sandboxes via
+ * the `@vercel/sandbox` SDK. Each sandbox is ephemeral — one sandbox per run.
+ *
+ * Requires `@vercel/sandbox` to be installed as a peer dependency.
+ */
+declare const vercel: (options?: VercelOptions) => IsolatedSandboxProvider;
+
+export { type VercelOptions, vercel };

package/dist/sandboxes/vercel.js

@@ -0,0 +1,188 @@
+import { createRequire } from 'node:module';
+import { createIsolatedSandboxProvider, shellQuote } from '../chunk-CP6YEQKU.js';
+import { MAX_TAIL_CHARS, OutputByteCounter, BoundedTail } from '../chunk-BU6XJFJ2.js';
+import { execFileSync } from 'child_process';
+import { mkdir, lstat, writeFile, chmod, mkdtemp, readFile, rm } from 'fs/promises';
+import { randomUUID } from 'crypto';
+import { tmpdir } from 'os';
+import { dirname, join } from 'path';
+import { Writable } from 'stream';
+
+createRequire(import.meta.url);
+var VERCEL_REPO_PATH = "/vercel/sandbox/workspace";
+var vercel = (options) => createIsolatedSandboxProvider({
+  name: "vercel",
+  env: options?.env,
+  create: async (createOptions) => {
+    const maxOutputTailChars = options?.maxOutputTailChars ?? MAX_TAIL_CHARS;
+    const { Sandbox } = await import('@vercel/sandbox');
+    const createParams = {};
+    if (options?.source) createParams.source = options.source;
+    if (options?.ports) createParams.ports = options.ports;
+    if (options?.resources) createParams.resources = options.resources;
+    if (options?.networkPolicy)
+      createParams.networkPolicy = options.networkPolicy;
+    const resolvedRuntime = options?.runtime ?? options?.template;
+    if (resolvedRuntime) createParams.runtime = resolvedRuntime;
+    const timeoutValue = options?.timeout ?? options?.timeoutMs;
+    if (timeoutValue !== void 0) createParams.timeout = timeoutValue;
+    createParams.env = createOptions.env;
+    if (options?.token) createParams.token = options.token;
+    if (options?.projectId) createParams.projectId = options.projectId;
+    if (options?.teamId) createParams.teamId = options.teamId;
+    const sandbox = await Sandbox.create(
+      createParams
+    );
+    await sandbox.mkDir(VERCEL_REPO_PATH);
+    const handle = {
+      worktreePath: VERCEL_REPO_PATH,
+      exec: async (command, opts) => {
+        if (opts?.onLine || opts?.maxOutputBytes !== void 0) {
+          const onLine = opts?.onLine ?? (() => {
+          });
+          const outputLimit = opts?.maxOutputBytes === void 0 ? void 0 : new OutputByteCounter(opts.maxOutputBytes);
+          const tailChars = opts?.maxOutputBytes ?? maxOutputTailChars;
+          const stdoutTail = new BoundedTail(tailChars, "\n");
+          const stderrTail = new BoundedTail(tailChars, "");
+          let outputLimitError;
+          const checkOutputLimit = (chunk) => {
+            if (outputLimit === void 0 || outputLimitError !== void 0) {
+              return;
+            }
+            outputLimit.add(chunk);
+            if (outputLimit.exceeded) {
+              outputLimitError = new Error(
+                `Sandbox command output exceeded ${opts.maxOutputBytes} bytes`
+              );
+            }
+          };
+          let partial = "";
+          const stdoutWritable = new Writable({
+            write(chunk, _encoding, callback) {
+              checkOutputLimit(chunk.toString());
+              if (outputLimitError !== void 0) {
+                callback(outputLimitError);
+                return;
+              }
+              const text = partial + chunk.toString();
+              const lines = text.split("\n");
+              partial = lines.pop() ?? "";
+              for (const line of lines) {
+                stdoutTail.push(line);
+                onLine(line);
+              }
+              callback();
+            },
+            final(callback) {
+              if (partial) {
+                stdoutTail.push(partial);
+                onLine(partial);
+                partial = "";
+              }
+              callback();
+            }
+          });
+          const stderrWritable = new Writable({
+            write(chunk, _encoding, callback) {
+              checkOutputLimit(chunk.toString());
+              if (outputLimitError !== void 0) {
+                callback(outputLimitError);
+                return;
+              }
+              stderrTail.push(chunk.toString());
+              callback();
+            }
+          });
+          const result2 = await sandbox.runCommand({
+            cmd: "sh",
+            args: ["-c", command],
+            cwd: opts?.cwd ?? VERCEL_REPO_PATH,
+            stdout: stdoutWritable,
+            stderr: stderrWritable,
+            ...opts?.sudo ? { sudo: true } : {}
+          });
+          if (outputLimitError !== void 0) throw outputLimitError;
+          return {
+            stdout: stdoutTail.toString(),
+            stderr: stderrTail.toString(),
+            exitCode: result2.exitCode
+          };
+        }
+        const result = await sandbox.runCommand({
+          cmd: "sh",
+          args: ["-c", command],
+          cwd: opts?.cwd ?? VERCEL_REPO_PATH,
+          ...opts?.sudo ? { sudo: true } : {}
+        });
+        const stdout = await result.stdout();
+        const stderr = await result.stderr();
+        return {
+          stdout,
+          stderr,
+          exitCode: result.exitCode
+        };
+      },
+      copyIn: async (hostPath, sandboxPath) => {
+        const info = await lstat(hostPath);
+        if (info.isSymbolicLink()) {
+          throw new Error(`Refusing to copy a symbolic link: ${hostPath}`);
+        }
+        if (info.isDirectory()) {
+          const tempDir = await mkdtemp(join(tmpdir(), "shipyard-copyin-"));
+          const tarPath = join(tempDir, "archive.tar.gz");
+          try {
+            execFileSync("tar", ["-czf", tarPath, "-C", hostPath, "."]);
+            const tarContent = await readFile(tarPath);
+            const sandboxTarPath = `/tmp/shipyard-copyin-${randomUUID()}.tar.gz`;
+            await sandbox.writeFiles([
+              { path: sandboxTarPath, content: tarContent }
+            ]);
+            await sandbox.runCommand({
+              cmd: "sh",
+              args: [
+                "-c",
+                `mkdir -p ${shellQuote(sandboxPath)} && tar -xzf ${shellQuote(sandboxTarPath)} -C ${shellQuote(sandboxPath)} && rm -f ${shellQuote(sandboxTarPath)}`
+              ]
+            });
+          } finally {
+            await rm(tempDir, { recursive: true, force: true }).catch(
+              () => {
+              }
+            );
+          }
+        } else {
+          const content = await readFile(hostPath);
+          await sandbox.writeFiles([{ path: sandboxPath, content }]);
+        }
+      },
+      copyFileOut: async (sandboxPath, hostPath) => {
+        const buffer = await sandbox.readFileToBuffer({
+          path: sandboxPath
+        });
+        if (!buffer) {
+          throw new Error(`File not found in Vercel sandbox: ${sandboxPath}`);
+        }
+        await mkdir(dirname(hostPath), { recursive: true, mode: 448 });
+        try {
+          if ((await lstat(hostPath)).isSymbolicLink()) {
+            throw new Error(
+              `Refusing to overwrite symbolic link: ${hostPath}`
+            );
+          }
+        } catch (error) {
+          if (error.code !== "ENOENT") throw error;
+        }
+        await writeFile(hostPath, buffer, { mode: 384 });
+        await chmod(hostPath, 384);
+      },
+      close: async () => {
+        await sandbox.stop();
+      }
+    };
+    return handle;
+  }
+});
+
+export { vercel };
+//# sourceMappingURL=vercel.js.map
+//# sourceMappingURL=vercel.js.map

package/dist/sandboxes/vercel.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/sandboxes/vercel.ts"],"names":["result"],"mappings":"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","file":"vercel.js","sourcesContent":["/**\n * Vercel isolated sandbox provider — wraps `@vercel/sandbox` into a SandboxProvider.\n *\n * Usage:\n *   import { vercel } from \"@snappedly-tools/shipyard/sandboxes/vercel\";\n *   await run({ agent: codex(CODEX_MODELS.routine), sandbox: vercel() });\n */\n\nimport { execFileSync } from \"node:child_process\";\nimport {\n  lstat,\n  chmod,\n  mkdir,\n  mkdtemp,\n  readFile,\n  rm,\n  writeFile,\n} from \"node:fs/promises\";\nimport { randomUUID } from \"node:crypto\";\nimport { tmpdir } from \"node:os\";\nimport { dirname, join } from \"node:path\";\nimport { Writable } from \"node:stream\";\nimport {\n  createIsolatedSandboxProvider,\n  type ExecResult,\n  type IsolatedSandboxHandle,\n  type IsolatedSandboxProvider,\n} from \"../SandboxProvider.js\";\nimport {\n  BoundedTail,\n  MAX_TAIL_CHARS,\n  OutputByteCounter,\n} from \"../boundedTail.js\";\nimport { shellQuote } from \"../shellQuote.js\";\n\n/** Worktree path inside the Vercel sandbox. */\nconst VERCEL_REPO_PATH = \"/vercel/sandbox/workspace\";\n\n/**\n * Options for creating a Vercel sandbox provider.\n *\n * All `@vercel/sandbox` `Sandbox.create()` options are accepted as pass-through,\n * plus Shipyard-specific options for auth and branch strategy.\n */\nexport interface VercelOptions {\n  /**\n   * Vercel access token.\n   *\n   * Falls back to the SDK's default auth behavior, which reads\n   * `VERCEL_OIDC_TOKEN` (recommended for Vercel-hosted environments) or\n   * `VERCEL_TOKEN` from the environment.\n   */\n  readonly token?: string;\n\n  // ---- Pass-through @vercel/sandbox Sandbox.create() options ----\n\n  /**\n   * The source of the sandbox (git repo, tarball, or snapshot).\n   * Omit to start an empty sandbox.\n   */\n  readonly source?:\n    | {\n        type: \"git\";\n        url: string;\n        depth?: number;\n        revision?: string;\n        username?: string;\n        password?: string;\n      }\n    | {\n        type: \"tarball\";\n        url: string;\n      }\n    | {\n        type: \"snapshot\";\n        snapshotId: string;\n      };\n\n  /** Array of port numbers to expose from the sandbox (up to 4). */\n  readonly ports?: number[];\n\n  /** Timeout in milliseconds before the sandbox auto-terminates. */\n  readonly timeout?: number;\n\n  /**\n   * Resources to allocate to the sandbox.\n   * Each vCPU gets 2048 MB of memory.\n   */\n  readonly resources?: {\n    vcpus: number;\n  };\n\n  /**\n   * The runtime of the sandbox (e.g. `\"node24\"`, `\"node22\"`, `\"python3.13\"`).\n   * Defaults to `\"node24\"`.\n   */\n  readonly runtime?: string;\n\n  /**\n   * Network policy for the sandbox.\n   * Defaults to full internet access if not specified.\n   */\n  readonly networkPolicy?: Record<string, unknown>;\n\n  /**\n   * Vercel project ID to associate sandbox operations with.\n   */\n  readonly projectId?: string;\n\n  /**\n   * Vercel team ID to associate sandbox operations with.\n   */\n  readonly teamId?: string;\n\n  /**\n   * Timeout in milliseconds (alias for `timeout`, kept for discoverability).\n   */\n  readonly timeoutMs?: number;\n\n  /**\n   * Sandbox template shorthand (e.g. `\"node-22\"`).\n   * Maps to the `runtime` option.\n   */\n  readonly template?: string;\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 Vercel isolated sandbox provider.\n *\n * The returned provider creates Vercel Firecracker microVM sandboxes via\n * the `@vercel/sandbox` SDK. Each sandbox is ephemeral — one sandbox per run.\n *\n * Requires `@vercel/sandbox` to be installed as a peer dependency.\n */\nexport const vercel = (options?: VercelOptions): IsolatedSandboxProvider =>\n  createIsolatedSandboxProvider({\n    name: \"vercel\",\n    env: options?.env,\n    create: async (createOptions): Promise<IsolatedSandboxHandle> => {\n      const maxOutputTailChars = options?.maxOutputTailChars ?? MAX_TAIL_CHARS;\n      // Dynamic import so the peer dependency is only loaded at runtime\n      const { Sandbox } = await import(\"@vercel/sandbox\");\n\n      const createParams: Record<string, unknown> = {};\n\n      // Pass through SDK options\n      if (options?.source) createParams.source = options.source;\n      if (options?.ports) createParams.ports = options.ports;\n      if (options?.resources) createParams.resources = options.resources;\n      if (options?.networkPolicy)\n        createParams.networkPolicy = options.networkPolicy;\n      // runtime takes precedence over the template convenience alias\n      const resolvedRuntime = options?.runtime ?? options?.template;\n      if (resolvedRuntime) createParams.runtime = resolvedRuntime;\n\n      // Timeout: prefer explicit timeout, fall back to timeoutMs alias\n      const timeoutValue = options?.timeout ?? options?.timeoutMs;\n      if (timeoutValue !== undefined) createParams.timeout = timeoutValue;\n\n      // Merge provider env with Shipyard env\n      createParams.env = createOptions.env;\n\n      // Auth: pass token and team/project IDs if provided\n      if (options?.token) createParams.token = options.token;\n      if (options?.projectId) createParams.projectId = options.projectId;\n      if (options?.teamId) createParams.teamId = options.teamId;\n\n      const sandbox = await Sandbox.create(\n        createParams as Parameters<typeof Sandbox.create>[0],\n      );\n\n      // Ensure worktree directory exists\n      await sandbox.mkDir(VERCEL_REPO_PATH);\n\n      const handle: IsolatedSandboxHandle = {\n        worktreePath: VERCEL_REPO_PATH,\n\n        exec: async (\n          command: string,\n          opts?: {\n            onLine?: (line: string) => void;\n            cwd?: string;\n            sudo?: boolean;\n            maxOutputBytes?: number;\n          },\n        ): Promise<ExecResult> => {\n          if (opts?.onLine || opts?.maxOutputBytes !== undefined) {\n            const onLine = opts?.onLine ?? (() => {});\n            const outputLimit =\n              opts?.maxOutputBytes === undefined\n                ? undefined\n                : new OutputByteCounter(opts.maxOutputBytes);\n            const tailChars = opts?.maxOutputBytes ?? maxOutputTailChars;\n            const stdoutTail = new BoundedTail(tailChars, \"\\n\");\n            const stderrTail = new BoundedTail(tailChars, \"\");\n            let outputLimitError: Error | undefined;\n            const checkOutputLimit = (chunk: string): void => {\n              if (outputLimit === undefined || outputLimitError !== undefined) {\n                return;\n              }\n              outputLimit.add(chunk);\n              if (outputLimit.exceeded) {\n                outputLimitError = new Error(\n                  `Sandbox command output exceeded ${opts.maxOutputBytes} bytes`,\n                );\n              }\n            };\n            let partial = \"\";\n\n            const stdoutWritable = new Writable({\n              write(chunk, _encoding, callback) {\n                checkOutputLimit(chunk.toString());\n                if (outputLimitError !== undefined) {\n                  callback(outputLimitError);\n                  return;\n                }\n                const text = partial + chunk.toString();\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                callback();\n              },\n              final(callback) {\n                if (partial) {\n                  stdoutTail.push(partial);\n                  onLine(partial);\n                  partial = \"\";\n                }\n                callback();\n              },\n            });\n\n            const stderrWritable = new Writable({\n              write(chunk, _encoding, callback) {\n                checkOutputLimit(chunk.toString());\n                if (outputLimitError !== undefined) {\n                  callback(outputLimitError);\n                  return;\n                }\n                stderrTail.push(chunk.toString());\n                callback();\n              },\n            });\n\n            const result = await sandbox.runCommand({\n              cmd: \"sh\",\n              args: [\"-c\", command],\n              cwd: opts?.cwd ?? VERCEL_REPO_PATH,\n              stdout: stdoutWritable,\n              stderr: stderrWritable,\n              ...(opts?.sudo ? { sudo: true } : {}),\n            });\n\n            if (outputLimitError !== undefined) throw outputLimitError;\n\n            return {\n              stdout: stdoutTail.toString(),\n              stderr: stderrTail.toString(),\n              exitCode: result.exitCode,\n            };\n          }\n\n          const result = await sandbox.runCommand({\n            cmd: \"sh\",\n            args: [\"-c\", command],\n            cwd: opts?.cwd ?? VERCEL_REPO_PATH,\n            ...(opts?.sudo ? { sudo: true } : {}),\n          });\n\n          const stdout = await result.stdout();\n          const stderr = await result.stderr();\n\n          return {\n            stdout,\n            stderr,\n            exitCode: result.exitCode,\n          };\n        },\n\n        copyIn: async (\n          hostPath: string,\n          sandboxPath: string,\n        ): Promise<void> => {\n          const info = await lstat(hostPath);\n          if (info.isSymbolicLink()) {\n            throw new Error(`Refusing to copy a symbolic link: ${hostPath}`);\n          }\n          if (info.isDirectory()) {\n            const tempDir = await mkdtemp(join(tmpdir(), \"shipyard-copyin-\"));\n            const tarPath = join(tempDir, \"archive.tar.gz\");\n            try {\n              execFileSync(\"tar\", [\"-czf\", tarPath, \"-C\", hostPath, \".\"]);\n              const tarContent = await readFile(tarPath);\n              const sandboxTarPath = `/tmp/shipyard-copyin-${randomUUID()}.tar.gz`;\n              await sandbox.writeFiles([\n                { path: sandboxTarPath, content: tarContent },\n              ]);\n              await sandbox.runCommand({\n                cmd: \"sh\",\n                args: [\n                  \"-c\",\n                  `mkdir -p ${shellQuote(sandboxPath)} && tar -xzf ${shellQuote(sandboxTarPath)} -C ${shellQuote(sandboxPath)} && rm -f ${shellQuote(sandboxTarPath)}`,\n                ],\n              });\n            } finally {\n              await rm(tempDir, { recursive: true, force: true }).catch(\n                () => {},\n              );\n            }\n          } else {\n            const content = await readFile(hostPath);\n            await sandbox.writeFiles([{ path: sandboxPath, content }]);\n          }\n        },\n\n        copyFileOut: async (\n          sandboxPath: string,\n          hostPath: string,\n        ): Promise<void> => {\n          const buffer = await sandbox.readFileToBuffer({\n            path: sandboxPath,\n          });\n          if (!buffer) {\n            throw new Error(`File not found in Vercel sandbox: ${sandboxPath}`);\n          }\n          await mkdir(dirname(hostPath), { recursive: true, mode: 0o700 });\n          try {\n            if ((await lstat(hostPath)).isSymbolicLink()) {\n              throw new Error(\n                `Refusing to overwrite symbolic link: ${hostPath}`,\n              );\n            }\n          } catch (error) {\n            if ((error as NodeJS.ErrnoException).code !== \"ENOENT\") throw error;\n          }\n          await writeFile(hostPath, buffer, { mode: 0o600 });\n          await chmod(hostPath, 0o600);\n        },\n\n        close: async (): Promise<void> => {\n          await sandbox.stop();\n        },\n      };\n\n      return handle;\n    },\n  });\n"]}

package/dist/templates/blank/main.mts

@@ -0,0 +1,13 @@
+import { CODEX_MODELS, run, codex } from "@snappedly-tools/shipyard";
+import { docker } from "@snappedly-tools/shipyard/sandboxes/docker";
+
+// Blank template: customize this to build your own orchestration.
+// Generated entrypoint: .shipyard/main.mts
+// Run this with: npx shipyard run
+// Or add to package.json scripts: "shipyard": "shipyard run"
+
+await run({
+  agent: codex(CODEX_MODELS.routine),
+  sandbox: docker(),
+  promptFile: "./.shipyard/prompt.md",
+});

package/dist/templates/blank/prompt.md

@@ -0,0 +1,12 @@
+# Context
+
+<!-- Use !`command` to pull in dynamic context. Commands run inside the sandbox. -->
+<!-- Example: !`git log --oneline -10` or !`{{LIST_TASKS_COMMAND}}` -->
+
+# Task
+
+<!-- Describe what the agent should do. -->
+
+# Done
+
+<!-- When the task is complete, output <promise>COMPLETE</promise> to signal early termination. -->

package/dist/templates/blank/template.json

@@ -0,0 +1,4 @@
+{
+  "name": "blank",
+  "description": "Bare scaffold — write your own prompt and orchestration"
+}

package/dist/templates/parallel-planner/implement-prompt.md

@@ -0,0 +1,62 @@
+# TASK
+
+Fix issue {{TASK_ID}}: {{ISSUE_TITLE}}
+
+Pull in the issue using `{{VIEW_TASK_COMMAND}}`. If it has a parent PRD, pull that in too.
+
+Only work on the issue specified.
+
+Work on branch {{BRANCH}}. Make commits and run tests.
+
+# CONTEXT
+
+Here are the last 10 commits:
+
+<recent-commits>
+
+!`git log -n 10 --format="%H%n%ad%n%B---" --date=short`
+
+</recent-commits>
+
+# EXPLORATION
+
+Explore the repo and fill your context window with relevant information that will allow you to complete the task.
+
+Pay extra attention to test files that touch the relevant parts of the code.
+
+# EXECUTION
+
+If applicable, use RGR to complete the task.
+
+1. RED: write one test
+2. GREEN: write the implementation to pass that test
+3. REPEAT until done
+4. REFACTOR the code
+
+# FEEDBACK LOOPS
+
+Before committing, read the repository's configured feedback-loop contract and run every applicable check for this change. Use the configured static check and focused behavior tests when they exist; include formatting, build, or broader checks when the contract or change requires them. Fix failures before committing.
+
+# COMMIT
+
+Make a git commit. The commit message must:
+
+1. Start with `RALPH:` prefix
+2. Include task completed + PRD reference
+3. Key decisions made
+4. Files changed
+5. Blockers or notes for next iteration
+
+Keep it concise.
+
+# THE ISSUE
+
+If the task is not complete, leave a comment on the issue with what was done.
+
+Do not close the issue - this will be done later.
+
+Once complete, output <promise>COMPLETE</promise>.
+
+# FINAL RULES
+
+ONLY WORK ON A SINGLE TASK.