@ai-hero/sandcastle 0.10.0 → 0.12.0

package/dist/index.js

@@ -1,8 +1,8 @@
 import { createRequire } from 'node:module';
-import { NodeContext_exports, NodeFileSystem_exports, formatErrorMessage } from './chunk-52CIJF45.js';
-import { Context_exports, CwdError, Effect_exports, resolveCwd, getCurrentBranch, generateTempBranchName, Layer_exports, FileDisplay, ClackDisplay, WorktreeDockerSandboxFactory, SandboxConfig, Display, pruneStale, create, copyToWorktree, runHostHooks, startSandbox, resolveGitMounts, SANDBOX_REPO_DIR, remove, makeSandboxFromHandle, syncOut, withSandboxLifecycle, hasUncommittedChanges, patchGitMountsForWindows, registerShutdown, SandboxFactory, PromptError, FileSystem_exports, SessionCaptureError, Clock_exports, Duration_exports, Option_exports, PromptExpansionTimeoutError, Deferred_exports, AgentError, Ref_exports, SilentDisplay, AgentIdleTimeoutError, Fiber_exports } from './chunk-5VM5QZ26.js';
+import { NodeContext_exports, NodeFileSystem_exports, formatErrorMessage } from './chunk-DJRHWPEH.js';
+import { Context_exports, CwdError, Effect_exports, resolveCwd, getCurrentBranch, generateTempBranchName, Layer_exports, FileDisplay, ClackDisplay, WorktreeDockerSandboxFactory, SandboxConfig, Display, pruneStale, create, copyToWorktree, runHostHooks, startSandbox, resolveGitMounts, patchGitMountsForWindows, SANDBOX_REPO_DIR, remove, makeSandboxFromHandle, syncOut, withSandboxLifecycle, hasUncommittedChanges, registerShutdown, SandboxFactory, PromptError, FileSystem_exports, SessionCaptureError, Clock_exports, Duration_exports, Option_exports, PromptExpansionTimeoutError, Deferred_exports, AgentError, Ref_exports, SilentDisplay, AgentIdleTimeoutError, Fiber_exports } from './chunk-VOG34SRF.js';
 export { createBindMountSandboxProvider, createIsolatedSandboxProvider } from './chunk-BIWNFKGV.js';
-import { noSandbox } from './chunk-72UVAC7B.js';
+import { noSandbox } from './chunk-62WN33RK.js';
 import './chunk-NGBM7T3E.js';
 import { mkdirSync, appendFileSync } from 'fs';
 import path, { join, posix, dirname, relative } from 'path';
@@ -372,7 +372,8 @@ var orchestrate = (options) => {
             hostWorktreePath,
             applyToHost,
             signal: options.signal,
-            timeouts: options.timeouts
+            timeouts: options.timeouts,
+            keepSourceBranch: options.keepSourceBranch
           },
           sandbox,
           (ctx) => Effect_exports.gen(function* () {
@@ -400,7 +401,7 @@ var orchestrate = (options) => {
             );
             yield* display.status(label("Agent started"), "success");
             const textBuffer = new TextDeltaBuffer((chunk) => {
-              Effect_exports.runPromise(display.text(chunk));
+              Effect_exports.runPromise(display.textChunk(chunk));
               Effect_exports.runPromise(
                 streamEmitter.emit({
                   type: "text",
@@ -751,20 +752,30 @@ var Output = {
    * Declare an object-typed structured output extracted from an XML tag in
    * the agent's stdout. The tag contents are JSON-parsed (with fence-aware
    * unwrapping) and validated against the provided Standard Schema validator.
+   *
+   * Set `maxRetries` to have `run()` automatically resume the failed session
+   * and ask the agent to re-emit corrected output when extraction or
+   * validation fails. Default: `0` (no retries).
    */
   object: (opts) => ({
     _tag: "object",
     tag: opts.tag,
-    schema: opts.schema
+    schema: opts.schema,
+    maxRetries: opts.maxRetries
   }),
   /**
    * Declare a string-typed structured output extracted from an XML tag in
    * the agent's stdout. The tag contents are whitespace-trimmed and returned
    * as a plain string — no JSON parsing, no schema validation.
+   *
+   * Set `maxRetries` to have `run()` automatically resume the failed session
+   * and ask the agent to re-emit corrected output when extraction fails.
+   * Default: `0` (no retries).
    */
   string: (opts) => ({
     _tag: "string",
-    tag: opts.tag
+    tag: opts.tag,
+    maxRetries: opts.maxRetries
   })
 };
 var StructuredOutputError = class extends Error {
@@ -870,6 +881,24 @@ var unwrapFences = (text2) => {
 };
 
 // src/run.ts
+var buildStructuredOutputRetryFeedback = (error, retriesRemaining) => {
+  const raw = error.rawMatched === void 0 ? "(no matching tag was emitted)" : error.rawMatched;
+  const cause = error.cause === void 0 ? "(no parser detail)" : typeof error.cause === "string" ? error.cause : JSON.stringify(error.cause, null, 2);
+  return `Your previous response did not produce valid structured output.
+
+Retries remaining after this attempt: ${retriesRemaining}.
+
+Problem:
+${error.message}
+
+Parser detail:
+${cause}
+
+Previous matched output:
+${raw}
+
+Emit only a corrected <${error.tag}> block. Do not change files or run commands.`;
+};
 var DEFAULT_MAX_ITERATIONS = 1;
 var sanitizeBranchForFilename = (branch) => branch.replace(/[/\\:*?"<>|]/g, "-");
 var printFileDisplayStartup = (options) => {
@@ -982,6 +1011,17 @@ async function run(options) {
       "output requires maxIterations to be 1. Structured output is only supported for single-iteration runs."
     );
   }
+  const outputMaxRetries = options.output?.maxRetries ?? 0;
+  if (outputMaxRetries < 0 || !Number.isInteger(outputMaxRetries)) {
+    throw new Error(
+      `output.maxRetries must be a non-negative integer. Received: ${outputMaxRetries}`
+    );
+  }
+  if (outputMaxRetries > 0 && !provider.sessionStorage) {
+    throw new Error(
+      `output.maxRetries requires an agent provider that supports session resumption. The "${provider.name}" provider does not. Use claudeCode, codex, or pi, or set maxRetries to 0.`
+    );
+  }
   const branch = branchStrategy.type === "branch" ? branchStrategy.branch : void 0;
   const hostRepoDir = await Effect_exports.runPromise(
     resolveCwd(options.cwd).pipe(Effect_exports.provide(NodeContext_exports.layer))
@@ -1183,18 +1223,41 @@ async function run(options) {
   };
   if (options.output) {
     const lastIteration = baseResult.iterations.at(-1);
-    const output = await extractStructuredOutput(
-      baseResult.stdout,
-      options.output,
-      {
-        commits: baseResult.commits,
-        branch: baseResult.branch,
-        preservedWorktreePath: baseResult.preservedWorktreePath,
-        sessionId: lastIteration?.sessionId,
-        sessionFilePath: lastIteration?.sessionFilePath
+    try {
+      const output = await extractStructuredOutput(
+        baseResult.stdout,
+        options.output,
+        {
+          commits: baseResult.commits,
+          branch: baseResult.branch,
+          preservedWorktreePath: baseResult.preservedWorktreePath,
+          sessionId: lastIteration?.sessionId,
+          sessionFilePath: lastIteration?.sessionFilePath
+        }
+      );
+      return { ...baseResult, output };
+    } catch (error) {
+      if (error instanceof StructuredOutputError && outputMaxRetries > 0 && error.sessionId !== void 0) {
+        const retriesRemainingAfter = outputMaxRetries - 1;
+        const retryOutput = {
+          ...options.output,
+          maxRetries: retriesRemainingAfter
+        };
+        return run({
+          ...options,
+          prompt: buildStructuredOutputRetryFeedback(
+            error,
+            retriesRemainingAfter
+          ),
+          promptFile: void 0,
+          promptArgs: void 0,
+          resumeSession: error.sessionId,
+          forkSession: false,
+          output: retryOutput
+        });
       }
-    );
-    return { ...baseResult, output };
+      throw error;
+    }
   }
   return baseResult;
 }
@@ -1363,14 +1426,20 @@ var interactive = async (options) => {
         return startResult.handle;
       } else {
         const gitPath = join(hostRepoDir, ".git");
-        const gitMounts = yield* resolveGitMounts(gitPath);
+        const rawGitMounts = yield* resolveGitMounts(gitPath);
+        const worktreeOrRepoPath = isHeadMode ? hostRepoDir : worktreeInfo.path;
+        const gitMounts = yield* patchGitMountsForWindows(
+          rawGitMounts,
+          worktreeOrRepoPath,
+          SANDBOX_REPO_DIR
+        );
         const startResult = yield* d.taskLog(
           "Starting sandbox",
           () => startSandbox({
             provider: sandboxProvider,
             hostRepoDir,
             env: effectiveEnv,
-            worktreeOrRepoPath: isHeadMode ? hostRepoDir : worktreeInfo.path,
+            worktreeOrRepoPath,
             gitMounts,
             repoDir: SANDBOX_REPO_DIR
           })
@@ -1492,9 +1561,12 @@ var buildSandboxHandle = (ctx, close) => {
     sandboxRepoDir,
     sandbox,
     providerHandle,
+    bindMountHandle,
     applyToHost,
-    timeouts
+    timeouts,
+    branchStrategy
   } = ctx;
+  const mergeToHead = branchStrategy?.type === "merge-to-head";
   const sandboxHandle = {
     branch,
     worktreePath,
@@ -1506,6 +1578,24 @@ var buildSandboxHandle = (ctx, close) => {
         promptFile,
         maxIterations = 1
       } = runOptions;
+      if (runOptions.resumeSession && maxIterations > 1) {
+        throw new Error(
+          "resumeSession cannot be combined with maxIterations > 1. Resume applies to iteration 1 only; multi-iteration resume semantics are not supported."
+        );
+      }
+      if (runOptions.forkSession && !runOptions.resumeSession) {
+        throw new Error(
+          "forkSession requires resumeSession. Use sandboxRunResult.fork(prompt) to fork the most recent captured session."
+        );
+      }
+      if (runOptions.resumeSession) {
+        await assertResumeSessionExists({
+          provider,
+          sandboxTag: ctx.providerTag,
+          hostRepoDir,
+          resumeSession: runOptions.resumeSession
+        });
+      }
       const resolved = await Effect_exports.runPromise(
         resolvePrompt({ prompt, promptFile }).pipe(
           Effect_exports.provide(NodeContext_exports.layer)
@@ -1564,7 +1654,8 @@ var buildSandboxHandle = (ctx, close) => {
           {
             hostWorktreePath: worktreePath,
             sandboxRepoPath: sandboxRepoDir,
-            applyToHost
+            applyToHost,
+            bindMountHandle
           },
           sandbox
         ).pipe(
@@ -1592,15 +1683,18 @@ var buildSandboxHandle = (ctx, close) => {
               hostRepoDir,
               iterations: maxIterations,
               prompt: resolvedPrompt,
-              branch,
+              branch: mergeToHead ? void 0 : branch,
               provider,
               completionSignal: runOptions.completionSignal,
               idleTimeoutSeconds: runOptions.idleTimeoutSeconds,
               completionTimeoutSeconds: runOptions.completionTimeoutSeconds,
               name: runOptions.name,
+              resumeSession: runOptions.resumeSession,
+              forkSession: runOptions.forkSession,
               signal: runOptions.signal,
               skipPromptExpansion: isInlinePrompt,
-              timeouts
+              timeouts,
+              keepSourceBranch: mergeToHead
             });
             const completion = buildCompletionMessage(
               orchestrateResult.completionSignal,
@@ -1619,13 +1713,38 @@ var buildSandboxHandle = (ctx, close) => {
         runOptions.signal?.throwIfAborted();
         throw error;
       }
-      return {
+      const baseResult = {
         iterations: result.iterations,
         completionSignal: result.completionSignal,
         stdout: result.stdout,
         commits: result.commits,
         logFilePath: resolvedLogging.type === "file" ? resolvedLogging.path : void 0
       };
+      const lastIteration = result.iterations.at(-1);
+      if (provider.sessionStorage && lastIteration?.sessionId) {
+        const capturedSessionId = lastIteration.sessionId;
+        return {
+          ...baseResult,
+          resume: (nextPrompt, resumeOptions) => sandboxHandle.run({
+            ...runOptions,
+            ...resumeOptions,
+            prompt: nextPrompt,
+            promptFile: void 0,
+            maxIterations: 1,
+            resumeSession: capturedSessionId
+          }),
+          fork: (nextPrompt, forkOptions) => sandboxHandle.run({
+            ...runOptions,
+            ...forkOptions,
+            prompt: nextPrompt,
+            promptFile: void 0,
+            maxIterations: 1,
+            resumeSession: capturedSessionId,
+            forkSession: true
+          })
+        };
+      }
+      return baseResult;
     },
     interactive: async (interactiveOptions) => {
       interactiveOptions.signal?.throwIfAborted();
@@ -1674,10 +1793,11 @@ var buildSandboxHandle = (ctx, close) => {
               {
                 hostRepoDir,
                 sandboxRepoDir,
-                branch,
+                branch: mergeToHead ? void 0 : branch,
                 hostWorktreePath: worktreePath,
                 applyToHost,
-                timeouts
+                timeouts,
+                keepSourceBranch: mergeToHead
               },
               sandbox,
               (ctx2) => Effect_exports.gen(function* () {
@@ -1736,6 +1856,13 @@ var buildSandboxHandle = (ctx, close) => {
         exitCode: lifecycleResult.result
       };
     },
+    exec: async (command, options) => {
+      const mergedOptions = { cwd: sandboxRepoDir, ...options };
+      if (providerHandle) {
+        return providerHandle.exec(command, mergedOptions);
+      }
+      return Effect_exports.runPromise(sandbox.exec(command, mergedOptions));
+    },
     close: async () => close(),
     [Symbol.asyncDispose]: async () => {
       await sandboxHandle.close();
@@ -1763,6 +1890,7 @@ var createSandboxFromWorktree = async (options) => {
   if (isTestMode) {
     sandbox = options._test.buildSandbox(worktreePath);
     sandboxRepoDir = worktreePath;
+    providerHandle = options._test.bindMountHandle;
   } else {
     const resolvedEnv = await Effect_exports.runPromise(
       resolveEnv(hostRepoDir).pipe(Effect_exports.provide(NodeContext_exports.layer))
@@ -1794,16 +1922,7 @@ var createSandboxFromWorktree = async (options) => {
         Effect_exports.catchAll(() => Effect_exports.succeed([])),
         // Patch git mounts for Windows worktree compatibility (ADR-0006)
         Effect_exports.flatMap(
-          (gitMounts) => Effect_exports.tryPromise({
-            try: () => patchGitMountsForWindows(
-              gitMounts,
-              worktreePath,
-              SANDBOX_REPO_DIR
-            ),
-            catch: (e) => new Error(
-              `Failed to patch git mounts: ${e instanceof Error ? e.message : String(e)}`
-            )
-          })
+          (gitMounts) => patchGitMountsForWindows(gitMounts, worktreePath, SANDBOX_REPO_DIR)
         ),
         Effect_exports.flatMap(
           (gitMounts) => startSandbox({
@@ -1848,6 +1967,7 @@ var createSandboxFromWorktree = async (options) => {
   }
   const applyToHost = isIsolated && providerHandle ? () => syncOut(worktreePath, providerHandle) : () => Effect_exports.void;
   let closed = false;
+  const bindMountHandle = options.sandbox.tag === "bind-mount" ? providerHandle : void 0;
   return buildSandboxHandle(
     {
       branch,
@@ -1856,8 +1976,11 @@ var createSandboxFromWorktree = async (options) => {
       sandboxRepoDir,
       sandbox,
       providerHandle,
+      bindMountHandle,
+      providerTag: options.sandbox.tag,
       applyToHost,
-      timeouts: options.timeouts
+      timeouts: options.timeouts,
+      branchStrategy: options.branchStrategy
     },
     async () => {
       if (closed) return { preservedWorktreePath: void 0 };
@@ -1902,6 +2025,7 @@ var createSandbox = async (options) => {
         if (isTestMode) {
           sandbox2 = options._test.buildSandbox(worktreePath2);
           sandboxRepoDir2 = worktreePath2;
+          providerHandle2 = options._test.bindMountHandle;
         } else {
           const resolvedEnv = yield* resolveEnv(hostRepoDir2);
           const env = mergeProviderEnv({
@@ -1925,16 +2049,11 @@ var createSandbox = async (options) => {
             Effect_exports.catchAll(() => Effect_exports.succeed([])),
             // Patch git mounts for Windows worktree compatibility (ADR-0006)
             Effect_exports.flatMap(
-              (gitMounts) => Effect_exports.tryPromise({
-                try: () => patchGitMountsForWindows(
-                  gitMounts,
-                  worktreePath2,
-                  SANDBOX_REPO_DIR
-                ),
-                catch: (e) => new Error(
-                  `Failed to patch git mounts: ${e instanceof Error ? e.message : String(e)}`
-                )
-              })
+              (gitMounts) => patchGitMountsForWindows(
+                gitMounts,
+                worktreePath2,
+                SANDBOX_REPO_DIR
+              )
             ),
             Effect_exports.flatMap(
               (gitMounts) => startSandbox({
@@ -2019,6 +2138,7 @@ Worktree preserved at ${worktreePath}`);
       })
     );
   };
+  const bindMountHandle = options.sandbox.tag === "bind-mount" ? providerHandle : void 0;
   return buildSandboxHandle(
     {
       branch,
@@ -2027,6 +2147,8 @@ Worktree preserved at ${worktreePath}`);
       sandboxRepoDir,
       sandbox,
       providerHandle,
+      bindMountHandle,
+      providerTag: options.sandbox.tag,
       applyToHost,
       timeouts: options.timeouts
     },
@@ -2039,6 +2161,7 @@ Worktree preserved at ${worktreePath}`);
 var createWorktree = async (options) => {
   const branch = options.branchStrategy.type === "branch" ? options.branchStrategy.branch : void 0;
   const baseBranch = options.branchStrategy.type === "branch" ? options.branchStrategy.baseBranch : void 0;
+  const isMergeToHead = options.branchStrategy.type === "merge-to-head";
   const { hostRepoDir, worktreeInfo } = await Effect_exports.gen(function* () {
     const hostRepoDir2 = yield* resolveCwd(options.cwd);
     yield* pruneStale(hostRepoDir2).pipe(
@@ -2144,7 +2267,12 @@ var createWorktree = async (options) => {
         handle = startResult.handle;
       } else {
         const gitPath = join(hostRepoDir, ".git");
-        const gitMounts = yield* resolveGitMounts(gitPath);
+        const rawGitMounts = yield* resolveGitMounts(gitPath);
+        const gitMounts = yield* patchGitMountsForWindows(
+          rawGitMounts,
+          worktreeInfo.path,
+          SANDBOX_REPO_DIR
+        );
         const startResult = yield* d.taskLog(
           "Starting sandbox",
           () => startSandbox({
@@ -2173,10 +2301,14 @@ var createWorktree = async (options) => {
             hostRepoDir,
             sandboxRepoDir: worktreePath,
             hooks,
-            branch: worktreeInfo.branch,
+            // merge-to-head: pass `undefined` so the lifecycle records the
+            // host's current branch and merges the worktree's commits back into
+            // it. branch strategy: pin to the worktree's branch.
+            branch: isMergeToHead ? void 0 : worktreeInfo.branch,
             hostWorktreePath: worktreeInfo.path,
             applyToHost,
-            timeouts: options.timeouts
+            timeouts: options.timeouts,
+            keepSourceBranch: isMergeToHead
           },
           sandbox,
           (ctx) => Effect_exports.gen(function* () {
@@ -2304,7 +2436,12 @@ var createWorktree = async (options) => {
         sandboxRepoDir = startResult.worktreePath;
       } else {
         const gitPath = join(hostRepoDir, ".git");
-        const gitMounts = yield* resolveGitMounts(gitPath);
+        const rawGitMounts = yield* resolveGitMounts(gitPath);
+        const gitMounts = yield* patchGitMountsForWindows(
+          rawGitMounts,
+          worktreeInfo.path,
+          SANDBOX_REPO_DIR
+        );
         const startResult = yield* startSandbox({
           provider: sandboxProvider,
           hostRepoDir,
@@ -2338,12 +2475,14 @@ var createWorktree = async (options) => {
           NodeFileSystem_exports.layer
         );
       })() : ClackDisplay.layer;
+      const bindMountHandle = sandboxProvider.tag === "bind-mount" ? handle : void 0;
       const reuseFactoryLayer = Layer_exports.succeed(SandboxFactory, {
         withSandbox: (makeEffect) => makeEffect(
           {
             hostWorktreePath: worktreeInfo.path,
             sandboxRepoPath: sandboxRepoDir,
-            applyToHost
+            applyToHost,
+            bindMountHandle
           },
           sandbox
         ).pipe(
@@ -2369,7 +2508,10 @@ var createWorktree = async (options) => {
           iterations: maxIterations,
           hooks,
           prompt: resolvedPrompt,
-          branch: worktreeInfo.branch,
+          // merge-to-head: pass `undefined` so the lifecycle records the host's
+          // current branch and routes through the merge step. branch strategy:
+          // pin to the worktree's branch so commits stay there.
+          branch: isMergeToHead ? void 0 : worktreeInfo.branch,
           provider,
           completionSignal: opts.completionSignal,
           idleTimeoutSeconds: opts.idleTimeoutSeconds,
@@ -2378,7 +2520,8 @@ var createWorktree = async (options) => {
           resumeSession: opts.resumeSession,
           signal: opts.signal,
           skipPromptExpansion: isInlinePrompt,
-          timeouts: options.timeouts
+          timeouts: options.timeouts,
+          keepSourceBranch: isMergeToHead
         });
         const completion = buildCompletionMessage(
           orchestrateResult.completionSignal,
@@ -2428,6 +2571,7 @@ var createWorktree = async (options) => {
       hooks: opts.hooks,
       copyToWorktree: opts.copyToWorktree,
       timeouts: opts.timeouts,
+      branchStrategy: options.branchStrategy,
       _test: opts._test
     });
   };