@ai-hero/sandcastle 0.2.4 → 0.3.0

package/dist/syncOut.js

@@ -0,0 +1,192 @@
+/**
+ * Sync-out: extract changes from an isolated sandbox back to the host.
+ *
+ * Two-phase approach:
+ * 1. Save phase: eagerly save all artifacts (patches, diff, untracked files)
+ *    to `.sandcastle/patches/<timestamp>/` before attempting to apply.
+ * 2. Apply phase: apply from the saved directory.
+ *    - On success: clean up the patch directory.
+ *    - On failure: preserve the patch directory and print recovery commands.
+ *
+ * Three-prong extraction within each phase:
+ * 1. Committed changes: `git format-patch` + `git am --3way`
+ * 2. Uncommitted changes (staged + unstaged): `git diff HEAD` + `git apply`
+ * 3. Untracked files: `git ls-files --others` + `copyOut` each file
+ */
+import { existsSync } from "node:fs";
+import { mkdir, readdir, readFile, rm, stat, writeFile, } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { buildRecoveryMessage } from "./RecoveryMessage.js";
+import { execHost, execOk } from "./sandboxExec.js";
+/**
+ * Check if a patch file is empty or header-only.
+ * Merge commits produce patches with headers but no diff content.
+ * A patch is considered empty if it has no lines starting with "diff --git".
+ */
+const isEmptyPatch = async (patchPath) => {
+    const info = await stat(patchPath);
+    if (info.size === 0)
+        return true;
+    const content = await readFile(patchPath, "utf-8");
+    return !content.includes("diff --git");
+};
+/**
+ * Generate a YYYYMMDD-HHMMSS timestamp directory name.
+ * Appends a counter suffix (-1, -2, ...) if the directory already exists.
+ */
+const createPatchDir = async (hostRepoDir) => {
+    const now = new Date();
+    const pad = (n) => String(n).padStart(2, "0");
+    const base = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+    const patchesRoot = join(hostRepoDir, ".sandcastle", "patches");
+    await mkdir(patchesRoot, { recursive: true });
+    let dirName = base;
+    let counter = 0;
+    while (existsSync(join(patchesRoot, dirName))) {
+        counter++;
+        dirName = `${base}-${counter}`;
+    }
+    const patchDir = join(patchesRoot, dirName);
+    await mkdir(patchDir, { recursive: true });
+    return patchDir;
+};
+/**
+ * Sync changes from an isolated sandbox back to the host repo.
+ *
+ * Two-phase extraction with artifact persistence:
+ * 1. Save all artifacts to `.sandcastle/patches/<timestamp>/`
+ * 2. Apply from saved directory; on failure, preserve artifacts and print recovery
+ */
+export const syncOut = async (hostRepoDir, handle) => {
+    const workspacePath = handle.workspacePath;
+    const hostHead = (await execHost("git rev-parse HEAD", hostRepoDir)).trim();
+    const sandboxHead = (await execOk(handle, "git rev-parse HEAD", { cwd: workspacePath })).stdout.trim();
+    const hasCommits = hostHead !== sandboxHead;
+    // Check for uncommitted changes
+    const diffResult = await handle.exec("git diff HEAD", { cwd: workspacePath });
+    const hasDiff = diffResult.exitCode === 0 && diffResult.stdout.trim().length > 0;
+    // Check for untracked files
+    const lsFilesResult = await handle.exec("git ls-files --others --exclude-standard", { cwd: workspacePath });
+    const hasUntracked = lsFilesResult.exitCode === 0 && lsFilesResult.stdout.trim().length > 0;
+    const untrackedFiles = hasUntracked
+        ? lsFilesResult.stdout
+            .trim()
+            .split("\n")
+            .filter((f) => f.length > 0)
+        : [];
+    // Nothing to sync
+    if (!hasCommits && !hasDiff && !hasUntracked) {
+        return;
+    }
+    // --- Phase 1: Save all artifacts ---
+    const patchDir = await createPatchDir(hostRepoDir);
+    const relativePatchDir = join(".sandcastle", "patches", basename(patchDir));
+    const nonEmptyPatches = [];
+    // Save committed patches
+    if (hasCommits) {
+        const mkTempResult = await execOk(handle, "mktemp -d -t sandcastle-patches-XXXXXX");
+        const sandboxPatchDir = mkTempResult.stdout.trim();
+        try {
+            await execOk(handle, `git format-patch "${hostHead}..HEAD" -o "${sandboxPatchDir}"`, { cwd: workspacePath });
+            const lsResult = await execOk(handle, `ls -1 "${sandboxPatchDir}"`);
+            const patchNames = lsResult.stdout
+                .trim()
+                .split("\n")
+                .filter((name) => name.length > 0);
+            for (const patchName of patchNames) {
+                const sandboxPatchPath = `${sandboxPatchDir}/${patchName}`;
+                const hostPatchPath = join(patchDir, patchName);
+                await handle.copyOut(sandboxPatchPath, hostPatchPath);
+                if (!(await isEmptyPatch(hostPatchPath))) {
+                    nonEmptyPatches.push(hostPatchPath);
+                }
+            }
+        }
+        finally {
+            await handle.exec(`rm -rf "${sandboxPatchDir}"`);
+        }
+    }
+    // Save uncommitted diff
+    if (hasDiff) {
+        const diffPath = join(patchDir, "changes.patch");
+        await writeFile(diffPath, diffResult.stdout);
+    }
+    // Save untracked files
+    if (hasUntracked) {
+        const untrackedDir = join(patchDir, "untracked");
+        for (const relPath of untrackedFiles) {
+            const sandboxFilePath = `${workspacePath}/${relPath}`;
+            const hostFilePath = join(untrackedDir, relPath);
+            await mkdir(dirname(hostFilePath), { recursive: true });
+            await handle.copyOut(sandboxFilePath, hostFilePath);
+        }
+    }
+    // --- Phase 2: Apply from saved directory ---
+    let failedStep;
+    // Apply committed patches
+    if (nonEmptyPatches.length > 0) {
+        try {
+            await execHost("git am --abort", hostRepoDir).catch(() => { });
+            const patchArgs = nonEmptyPatches.map((p) => `"${p}"`).join(" ");
+            await execHost(`git am --3way ${patchArgs}`, hostRepoDir);
+        }
+        catch {
+            failedStep = "commits";
+        }
+    }
+    // Apply uncommitted diff
+    if (!failedStep && hasDiff) {
+        const diffPath = join(patchDir, "changes.patch");
+        try {
+            await execHost(`git apply "${diffPath}"`, hostRepoDir);
+        }
+        catch {
+            failedStep = "diff";
+        }
+    }
+    // Copy untracked files
+    if (!failedStep && hasUntracked) {
+        try {
+            const untrackedDir = join(patchDir, "untracked");
+            for (const relPath of untrackedFiles) {
+                const srcPath = join(untrackedDir, relPath);
+                const destPath = join(hostRepoDir, relPath);
+                await mkdir(dirname(destPath), { recursive: true });
+                const content = await readFile(srcPath);
+                await writeFile(destPath, content);
+            }
+        }
+        catch {
+            failedStep = "untracked";
+        }
+    }
+    // --- Cleanup or preserve ---
+    if (failedStep) {
+        const msg = buildRecoveryMessage({
+            patchDir: relativePatchDir,
+            failedStep,
+            hasCommits: nonEmptyPatches.length > 0,
+            hasDiff,
+            hasUntracked,
+        });
+        console.error(`\n${msg}`);
+    }
+    else {
+        await rm(patchDir, { recursive: true, force: true });
+        // Clean up empty parent dirs
+        const patchesRoot = join(hostRepoDir, ".sandcastle", "patches");
+        try {
+            const remaining = await readdir(patchesRoot);
+            if (remaining.length === 0) {
+                await rm(join(hostRepoDir, ".sandcastle"), {
+                    recursive: true,
+                    force: true,
+                });
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+};
+//# sourceMappingURL=syncOut.js.map

package/dist/syncOut.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncOut.js","sourceRoot":"","sources":["../src/syncOut.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EACL,KAAK,EACL,OAAO,EACP,QAAQ,EACR,EAAE,EACF,IAAI,EACJ,SAAS,GACV,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEpD,OAAO,EAAE,oBAAoB,EAAmB,MAAM,sBAAsB,CAAC;AAC7E,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;GAIG;AACH,MAAM,YAAY,GAAG,KAAK,EAAE,SAAiB,EAAoB,EAAE;IACjE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,CAAC;IACnC,IAAI,IAAI,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEjC,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACnD,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;AACzC,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,cAAc,GAAG,KAAK,EAAE,WAAmB,EAAmB,EAAE;IACpE,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACtD,MAAM,IAAI,GAAG,GAAG,GAAG,CAAC,WAAW,EAAE,GAAG,GAAG,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,EAAE,CAAC;IAE1J,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,EAAE,aAAa,EAAE,SAAS,CAAC,CAAC;IAChE,MAAM,KAAK,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE9C,IAAI,OAAO,GAAG,IAAI,CAAC;IACnB,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,OAAO,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;QAC9C,OAAO,EAAE,CAAC;QACV,OAAO,GAAG,GAAG,IAAI,IAAI,OAAO,EAAE,CAAC;IACjC,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IAC5C,MAAM,KAAK,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3C,OAAO,QAAQ,CAAC;AAClB,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,KAAK,EAC1B,WAAmB,EACnB,MAA6B,EACd,EAAE;IACjB,MAAM,aAAa,GAAG,MAAM,CAAC,aAAa,CAAC;IAE3C,MAAM,QAAQ,GAAG,CAAC,MAAM,QAAQ,CAAC,oBAAoB,EAAE,WAAW,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5E,MAAM,WAAW,GAAG,CAClB,MAAM,MAAM,CAAC,MAAM,EAAE,oBAAoB,EAAE,EAAE,GAAG,EAAE,aAAa,EAAE,CAAC,CACnE,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IAEhB,MAAM,UAAU,GAAG,QAAQ,KAAK,WAAW,CAAC;IAE5C,gCAAgC;IAChC,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,eAAe,EAAE,EAAE,GAAG,EAAE,aAAa,EAAE,CAAC,CAAC;IAC9E,MAAM,OAAO,GACX,UAAU,CAAC,QAAQ,KAAK,CAAC,IAAI,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;IAEnE,4BAA4B;IAC5B,MAAM,aAAa,GAAG,MAAM,MAAM,CAAC,IAAI,CACrC,0CAA0C,EAC1C,EAAE,GAAG,EAAE,aAAa,EAAE,CACvB,CAAC;IACF,MAAM,YAAY,GAChB,aAAa,CAAC,QAAQ,KAAK,CAAC,IAAI,aAAa,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;IAEzE,MAAM,cAAc,GAAG,YAAY;QACjC,CAAC,CAAC,aAAa,CAAC,MAAM;aACjB,IAAI,EAAE;aACN,KAAK,CAAC,IAAI,CAAC;aACX,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;QAChC,CAAC,CAAC,EAAE,CAAC;IAEP,kBAAkB;IAClB,IAAI,CAAC,UAAU,IAAI,CAAC,OAAO,IAAI,CAAC,YAAY,EAAE,CAAC;QAC7C,OAAO;IACT,CAAC;IAED,sCAAsC;IACtC,MAAM,QAAQ,GAAG,MAAM,cAAc,CAAC,WAAW,CAAC,CAAC;IACnD,MAAM,gBAAgB,GAAG,IAAI,CAAC,aAAa,EAAE,SAAS,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;IAE5E,MAAM,eAAe,GAAa,EAAE,CAAC;IAErC,yBAAyB;IACzB,IAAI,UAAU,EAAE,CAAC;QACf,MAAM,YAAY,GAAG,MAAM,MAAM,CAC/B,MAAM,EACN,wCAAwC,CACzC,CAAC;QACF,MAAM,eAAe,GAAG,YAAY,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAEnD,IAAI,CAAC;YACH,MAAM,MAAM,CACV,MAAM,EACN,qBAAqB,QAAQ,eAAe,eAAe,GAAG,EAC9D,EAAE,GAAG,EAAE,aAAa,EAAE,CACvB,CAAC;YAEF,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,MAAM,EAAE,UAAU,eAAe,GAAG,CAAC,CAAC;YACpE,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM;iBAC/B,IAAI,EAAE;iBACN,KAAK,CAAC,IAAI,CAAC;iBACX,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YAErC,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;gBACnC,MAAM,gBAAgB,GAAG,GAAG,eAAe,IAAI,SAAS,EAAE,CAAC;gBAC3D,MAAM,aAAa,GAAG,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;gBAChD,MAAM,MAAM,CAAC,OAAO,CAAC,gBAAgB,EAAE,aAAa,CAAC,CAAC;gBAEtD,IAAI,CAAC,CAAC,MAAM,YAAY,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC;oBACzC,eAAe,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;gBACtC,CAAC;YACH,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,MAAM,MAAM,CAAC,IAAI,CAAC,WAAW,eAAe,GAAG,CAAC,CAAC;QACnD,CAAC;IACH,CAAC;IAED,wBAAwB;IACxB,IAAI,OAAO,EAAE,CAAC;QACZ,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC;QACjD,MAAM,SAAS,CAAC,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAC/C,CAAC;IAED,uBAAuB;IACvB,IAAI,YAAY,EAAE,CAAC;QACjB,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;QACjD,KAAK,MAAM,OAAO,IAAI,cAAc,EAAE,CAAC;YACrC,MAAM,eAAe,GAAG,GAAG,aAAa,IAAI,OAAO,EAAE,CAAC;YACtD,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;YACjD,MAAM,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACxD,MAAM,MAAM,CAAC,OAAO,CAAC,eAAe,EAAE,YAAY,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;IAED,8CAA8C;IAC9C,IAAI,UAAkC,CAAC;IAEvC,0BAA0B;IAC1B,IAAI,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/B,IAAI,CAAC;YACH,MAAM,QAAQ,CAAC,gBAAgB,EAAE,WAAW,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YAC9D,MAAM,SAAS,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACjE,MAAM,QAAQ,CAAC,iBAAiB,SAAS,EAAE,EAAE,WAAW,CAAC,CAAC;QAC5D,CAAC;QAAC,MAAM,CAAC;YACP,UAAU,GAAG,SAAS,CAAC;QACzB,CAAC;IACH,CAAC;IAED,yBAAyB;IACzB,IAAI,CAAC,UAAU,IAAI,OAAO,EAAE,CAAC;QAC3B,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC;QACjD,IAAI,CAAC;YACH,MAAM,QAAQ,CAAC,cAAc,QAAQ,GAAG,EAAE,WAAW,CAAC,CAAC;QACzD,CAAC;QAAC,MAAM,CAAC;YACP,UAAU,GAAG,MAAM,CAAC;QACtB,CAAC;IACH,CAAC;IAED,uBAAuB;IACvB,IAAI,CAAC,UAAU,IAAI,YAAY,EAAE,CAAC;QAChC,IAAI,CAAC;YACH,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;YACjD,KAAK,MAAM,OAAO,IAAI,cAAc,EAAE,CAAC;gBACrC,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;gBAC5C,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;gBAC5C,MAAM,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;gBACpD,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,CAAC;gBACxC,MAAM,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YACrC,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,UAAU,GAAG,WAAW,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,8BAA8B;IAC9B,IAAI,UAAU,EAAE,CAAC;QACf,MAAM,GAAG,GAAG,oBAAoB,CAAC;YAC/B,QAAQ,EAAE,gBAAgB;YAC1B,UAAU;YACV,UAAU,EAAE,eAAe,CAAC,MAAM,GAAG,CAAC;YACtC,OAAO;YACP,YAAY;SACb,CAAC,CAAC;QACH,OAAO,CAAC,KAAK,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC;IAC5B,CAAC;SAAM,CAAC;QACN,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACrD,6BAA6B;QAC7B,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,EAAE,aAAa,EAAE,SAAS,CAAC,CAAC;QAChE,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC,CAAC;YAC7C,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC3B,MAAM,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,aAAa,CAAC,EAAE;oBACzC,SAAS,EAAE,IAAI;oBACf,KAAK,EAAE,IAAI;iBACZ,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;IACH,CAAC;AACH,CAAC,CAAC"}

package/dist/templates/blank/main.mts

@@ -1,4 +1,5 @@
 import { run, claudeCode } from "@ai-hero/sandcastle";
+import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
 
 // Blank template: customize this to build your own orchestration.
 // Run this with: npx tsx .sandcastle/main.mts
@@ -6,5 +7,6 @@ import { run, claudeCode } from "@ai-hero/sandcastle";
 
 await run({
   agent: claudeCode("claude-opus-4-6"),
+  sandbox: docker(),
   promptFile: "./.sandcastle/prompt.md",
 });

package/dist/templates/parallel-planner/main.mts

@@ -17,6 +17,7 @@
 //   "scripts": { "sandcastle": "npx tsx .sandcastle/main.mts" }
 
 import * as sandcastle from "@ai-hero/sandcastle";
+import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
 
 // ---------------------------------------------------------------------------
 // Configuration
@@ -56,6 +57,7 @@ for (let iteration = 1; iteration <= MAX_ITERATIONS; iteration++) {
   const plan = await sandcastle.run({
     hooks,
     copyToSandbox,
+    sandbox: docker(),
     name: "planner",
     // One iteration is enough: the planner just needs to read and reason,
     // not write code.
@@ -105,6 +107,7 @@ for (let iteration = 1; iteration <= MAX_ITERATIONS; iteration++) {
       sandcastle.run({
         hooks,
         copyToSandbox,
+        sandbox: docker(),
         name: "implementer",
         // Give each agent plenty of room to implement and iterate on tests.
         maxIterations: 100,
@@ -179,6 +182,7 @@ for (let iteration = 1; iteration <= MAX_ITERATIONS; iteration++) {
   await sandcastle.run({
     hooks,
     copyToSandbox,
+    sandbox: docker(),
     name: "merger",
     maxIterations: 10,
     // Sonnet is sufficient for merge conflict resolution.

package/dist/templates/sequential-reviewer/main.mts

@@ -17,6 +17,7 @@
 //   "scripts": { "sandcastle": "npx tsx .sandcastle/main.mts" }
 
 import * as sandcastle from "@ai-hero/sandcastle";
+import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
 
 // ---------------------------------------------------------------------------
 // Configuration
@@ -57,6 +58,7 @@ for (let iteration = 1; iteration <= MAX_ITERATIONS; iteration++) {
   const implement = await sandcastle.run({
     hooks,
     copyToSandbox,
+    sandbox: docker(),
     name: "implementer",
     maxIterations: 100,
     agent: sandcastle.claudeCode("claude-sonnet-4-6"),
@@ -84,6 +86,7 @@ for (let iteration = 1; iteration <= MAX_ITERATIONS; iteration++) {
   await sandcastle.run({
     hooks,
     copyToSandbox,
+    sandbox: docker(),
     name: "reviewer",
     maxIterations: 10,
     agent: sandcastle.claudeCode("claude-sonnet-4-6"),

package/dist/templates/simple-loop/main.mts

@@ -1,4 +1,5 @@
 import { run, claudeCode } from "@ai-hero/sandcastle";
+import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
 
 // Simple loop: an agent that picks open GitHub issues one by one and closes them.
 // Run this with: npx tsx .sandcastle/main.mts
@@ -8,6 +9,9 @@ await run({
   // A name for this run, shown as a prefix in log output.
   name: "worker",
 
+  // Sandbox provider — Docker is the default runtime.
+  sandbox: docker(),
+
   // The agent provider. Pass a model string to claudeCode() — sonnet balances
   // capability and speed for most tasks. Switch to claude-opus-4-6 for harder
   // problems, or claude-haiku-4-5-20251001 for speed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-hero/sandcastle",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "CLI for orchestrating AI agents in isolated sandbox environments",
   "type": "module",
   "main": "./dist/index.js",
@@ -9,6 +9,10 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./sandboxes/docker": {
+      "import": "./dist/sandboxes/docker.js",
+      "types": "./dist/sandboxes/docker.d.ts"
     }
   },
   "bin": {