@ai-hero/sandcastle 0.8.0 → 0.10.0

package/README.md

@@ -39,7 +39,7 @@ npm install --save-dev @ai-hero/sandcastle
 npx @ai-hero/sandcastle init
 ```
 
-3. Edit `.sandcastle/.env` and fill in your default values for `ANTHROPIC_API_KEY`. If you want to use your Claude subscription instead of an API key, see [#191](https://github.com/mattpocock/sandcastle/issues/191).
+3. Edit `.sandcastle/.env` and fill in your default values for `CLAUDE_CODE_OAUTH_TOKEN` (run `claude setup-token` on your host to get one). To use an Anthropic API key instead, uncomment and fill in `ANTHROPIC_API_KEY`.
 
 ```bash
 cp .sandcastle/.env.example .sandcastle/.env
@@ -218,14 +218,20 @@ const result = await run({
     type: "file",
     path: ".sandcastle/logs/my-run.log",
     // Optional: forward the agent's output stream to your own observability system.
-    // Fires for each text chunk and tool call the agent produces. Errors thrown
-    // by the callback are swallowed so a broken forwarder cannot kill the run.
+    // Fires for each text chunk, tool call, and raw stdout line the agent
+    // produces. Errors thrown by the callback are swallowed so a broken
+    // forwarder cannot kill the run.
     onAgentStreamEvent: (event) => {
-      // event is { type: "text" | "toolCall", iteration, timestamp, ... }
+      // event is { type: "text" | "toolCall" | "raw", iteration, timestamp, ... }
       myLogger.info(event);
     },
+    // Optional: append every raw stdout line the agent emits to the same
+    // log file, interleaved with the human-readable output. Includes lines
+    // the provider's stream parser would otherwise drop. Intended for
+    // debugging stuck or unexpected agent behaviour.
+    verbose: true,
   },
-  // logging: { type: "stdout" }, // OR render an interactive UI in the terminal
+  // logging: { type: "stdout", verbose: true }, // OR terminal mode (verbose: raw lines to stdout)
 
   // String (or array of strings) the agent emits to end the iteration loop early.
   // Default: "<promise>COMPLETE</promise>"
@@ -828,6 +834,8 @@ Removes the Podman image.
 
 After each resumable provider iteration, Sandcastle automatically captures the agent's session file from the sandbox to the host. Claude Code sessions are stored under `~/.claude/projects/<encoded-path>/<session-id>.jsonl`; Codex sessions are stored under `~/.codex/sessions/YYYY/MM/DD/rollout-*-<session-id>.jsonl`; Pi sessions are stored under `~/.pi/agent/sessions/--<encoded-cwd>--/<timestamp>_<session-id>.jsonl`. Any provider-specific `cwd` fields are rewritten to match the host repo root, so the provider's native resume command works.
 
+For Claude Code, any `Agent`-tool or `Workflow`-tool subagent transcripts written under `<session-id>/subagents/agent-*.jsonl` are captured alongside the main session. Subagent capture is best-effort: a failure on an individual transcript logs a warning and lets siblings and the main session through. Main-session capture failure still fails the run (see below).
+
 Session capture is enabled by default for `claudeCode()`, `codex()`, and `pi()` and can be opted out via `captureSessions: false`. Providers without `sessionStorage` do not attempt capture. Capture failure fails the run.
 
 ### Session resume

package/dist/index.d.ts

@@ -246,6 +246,12 @@ declare const claudeCode: (model: string, options?: ClaudeCodeOptions) => AgentP
  *
  * Emitted only in log-to-file mode when an `onAgentStreamEvent` callback is
  * provided via `logging`. See `run()`.
+ *
+ * The `"raw"` variant carries every stdout line the agent emits, verbatim and
+ * before parsing — including lines that the provider's stream parser would
+ * otherwise drop (e.g. tool-use blocks for unrecognised tools). Intended for
+ * debugging when the typed `"text"` / `"toolCall"` events don't surface
+ * enough detail.
  */
 type AgentStreamEvent = {
     readonly type: "text";
@@ -258,6 +264,11 @@ type AgentStreamEvent = {
     readonly formattedArgs: string;
     readonly iteration: number;
     readonly timestamp: Date;
+} | {
+    readonly type: "raw";
+    readonly line: string;
+    readonly iteration: number;
+    readonly timestamp: Date;
 };
 
 type SandboxHooks = {
@@ -414,16 +425,34 @@ type LoggingOption =
     readonly type: "file";
     readonly path: string;
     /**
-     * Optional callback invoked for each agent stream event (text chunk or
-     * tool call) in addition to being written to the log file. Intended for
-     * forwarding the agent's output stream to external observability
-     * systems. Errors thrown by the callback are swallowed.
+     * Optional callback invoked for each agent stream event (text chunk,
+     * tool call, or raw stdout line) in addition to being written to the
+     * log file. Intended for forwarding the agent's output stream to
+     * external observability systems. Errors thrown by the callback are
+     * swallowed.
      */
     readonly onAgentStreamEvent?: (event: AgentStreamEvent) => void;
+    /**
+     * When `true`, every raw stdout line the agent emits is appended
+     * verbatim to the same log file at `path`, in real time. Includes
+     * lines the provider's stream parser would otherwise drop (e.g.
+     * tool-use blocks for unrecognised tools). Intended for debugging
+     * stuck or unexpected agent behavior — note that the raw JSON is
+     * interleaved with the human-readable log output. Default: `false`.
+     */
+    readonly verbose?: boolean;
 }
 /** Render progress and agent output as an interactive UI in the terminal (terminal mode). */
  | {
     readonly type: "stdout";
+    /**
+     * When `true`, every raw stdout line the agent emits is written
+     * verbatim to `process.stdout`, in real time. Includes lines the
+     * provider's stream parser would otherwise drop. Intended for
+     * debugging stuck or unexpected agent behavior. Note: the raw output
+     * is interleaved with the interactive terminal UI. Default: `false`.
+     */
+    readonly verbose?: boolean;
 };
 /** Override default timeouts for built-in lifecycle steps. Unset keys keep their defaults. */
 interface Timeouts {

package/dist/index.js

@@ -4,6 +4,7 @@ import { Context_exports, CwdError, Effect_exports, resolveCwd, getCurrentBranch
 export { createBindMountSandboxProvider, createIsolatedSandboxProvider } from './chunk-BIWNFKGV.js';
 import { noSandbox } from './chunk-72UVAC7B.js';
 import './chunk-NGBM7T3E.js';
+import { mkdirSync, appendFileSync } from 'fs';
 import path, { join, posix, dirname, relative } from 'path';
 import { styleText } from 'util';
 import * as clack from '@clack/prompts';
@@ -177,7 +178,7 @@ var TextDeltaBuffer = class {
 
 // src/Orchestrator.ts
 var IDLE_WARNING_INTERVAL_MS = 6e4;
-var invokeAgent = (sandbox, sandboxRepoDir, prompt, provider, idleTimeoutMs, completionTimeoutMs, completionSignals, onText, onToolCall, onIdleWarning, onCompletionTimeout, idleWarningIntervalMs = IDLE_WARNING_INTERVAL_MS, resumeSession, forkSession, signal) => Effect_exports.gen(function* () {
+var invokeAgent = (sandbox, sandboxRepoDir, prompt, provider, idleTimeoutMs, completionTimeoutMs, completionSignals, onText, onToolCall, onRawLine, onIdleWarning, onCompletionTimeout, idleWarningIntervalMs = IDLE_WARNING_INTERVAL_MS, resumeSession, forkSession, signal) => Effect_exports.gen(function* () {
   let resultText = "";
   let sessionId;
   let usage;
@@ -256,6 +257,10 @@ var invokeAgent = (sandbox, sandboxRepoDir, prompt, provider, idleTimeoutMs, com
     });
     const execResult = yield* sandbox.exec(printCmd.command, {
       onLine: (line) => {
+        try {
+          onRawLine(line);
+        } catch {
+        }
         for (const parsed of provider.parseStreamLine(line)) {
           if (parsed.type === "text") {
             onText(parsed.text);
@@ -421,6 +426,16 @@ var orchestrate = (options) => {
                 })
               );
             };
+            const onRawLine = (line) => {
+              Effect_exports.runPromise(
+                streamEmitter.emit({
+                  type: "raw",
+                  line,
+                  iteration: i,
+                  timestamp: /* @__PURE__ */ new Date()
+                })
+              );
+            };
             const onIdleWarning = (minutes) => {
               const msg = minutes === 1 ? "Agent idle for 1 minute" : `Agent idle for ${minutes} minutes`;
               Effect_exports.runPromise(display.status(label(msg), "warn"));
@@ -449,6 +464,7 @@ var orchestrate = (options) => {
               completionSignals,
               onText,
               onToolCall,
+              onRawLine,
               onIdleWarning,
               onCompletionTimeout,
               options._idleWarningIntervalMs,
@@ -676,7 +692,7 @@ var findMissingPromptArgKeys = (prompt, providedArgs) => {
     if (seen.has(key)) continue;
     seen.add(key);
     if (builtInSet.has(key)) continue;
-    if (key in providedArgs) continue;
+    if (key in providedArgs && providedArgs[key] != null) continue;
     missing.push(key);
   }
   return missing;
@@ -704,6 +720,14 @@ var substitutePromptArgs = (prompt, args, silentKeys) => {
           })
         );
       }
+      const value = sanitizedArgs[key];
+      if (value == null) {
+        return yield* Effect_exports.fail(
+          new PromptError({
+            message: `Prompt argument "{{${key}}}" has value ${value === null ? "null" : "undefined"} in promptArgs`
+          })
+        );
+      }
     }
     for (const key of Object.keys(sanitizedArgs)) {
       if (!referencedKeys.has(key) && !silentKeys?.has(key)) {
@@ -888,6 +912,40 @@ var formatContextWindowSize = (usage) => {
   return `${Math.ceil(total / 1e3)}k`;
 };
 var buildContextWindowLines = (iterations) => iterations.filter((it) => it.usage !== void 0).map((it) => `Context window: ${formatContextWindowSize(it.usage)}`);
+var buildAgentStreamHandler = (logging) => {
+  const userHandler = logging.type === "file" ? logging.onAgentStreamEvent : void 0;
+  const verboseSink = logging.verbose ? buildVerboseRawLineSink(logging) : void 0;
+  if (!userHandler && !verboseSink) return void 0;
+  return (event) => {
+    if (userHandler) {
+      try {
+        userHandler(event);
+      } catch {
+      }
+    }
+    if (verboseSink && event.type === "raw") {
+      verboseSink(event.line);
+    }
+  };
+};
+var buildVerboseRawLineSink = (logging) => {
+  if (logging.type === "file") {
+    const logPath = logging.path;
+    try {
+      mkdirSync(path.dirname(logPath), { recursive: true });
+    } catch {
+    }
+    return (line) => {
+      try {
+        appendFileSync(logPath, line + "\n");
+      } catch {
+      }
+    };
+  }
+  return (line) => {
+    process.stdout.write(line + "\n");
+  };
+};
 async function run(options) {
   options.signal?.throwIfAborted();
   const {
@@ -1005,7 +1063,7 @@ async function run(options) {
     )
   );
   const streamEmitterLayer = agentStreamEmitterLayer(
-    resolvedLogging.type === "file" ? resolvedLogging.onAgentStreamEvent : void 0
+    buildAgentStreamHandler(resolvedLogging)
   );
   const runLayer = Layer_exports.mergeAll(
     factoryLayer,
@@ -1517,7 +1575,7 @@ var buildSandboxHandle = (ctx, close) => {
         )
       });
       const streamEmitterLayer = agentStreamEmitterLayer(
-        resolvedLogging.type === "file" ? resolvedLogging.onAgentStreamEvent : void 0
+        buildAgentStreamHandler(resolvedLogging)
       );
       const runLayer = Layer_exports.mergeAll(
         reuseFactoryLayer,
@@ -2296,7 +2354,7 @@ var createWorktree = async (options) => {
         )
       });
       const streamEmitterLayer = agentStreamEmitterLayer(
-        resolvedLogging.type === "file" ? resolvedLogging.onAgentStreamEvent : void 0
+        buildAgentStreamHandler(resolvedLogging)
       );
       const runLayer = Layer_exports.mergeAll(
         reuseFactoryLayer,
@@ -2403,6 +2461,21 @@ var claudeHostSessionPath = (cwd, id, projectsDir) => {
   return join(base, encodeProjectPath(cwd), `${id}.jsonl`);
 };
 var claudeSandboxSessionPath = (cwd, id, projectsDir) => posix.join(projectsDir, encodeProjectPath(cwd), `${id}.jsonl`);
+var claudeSubagentsDirInSandbox = (cwd, id, projectsDir) => posix.join(projectsDir, encodeProjectPath(cwd), id, "subagents");
+var claudeSubagentsDirOnHost = (cwd, id, projectsDir) => {
+  const base = projectsDir ?? join(process.env.HOME ?? "~", ".claude", "projects");
+  return join(base, encodeProjectPath(cwd), id, "subagents");
+};
+var listClaudeSubagentSessionsInSandbox = async (cwd, id, handle, sandboxProjectsDir) => {
+  const dir = claudeSubagentsDirInSandbox(cwd, id, sandboxProjectsDir);
+  const result = await handle.exec(
+    `find ${JSON.stringify(dir)} -type f -name ${JSON.stringify("agent-*.jsonl")} 2>/dev/null`
+  );
+  if (result.exitCode !== 0) return [];
+  const stdout = result.stdout.trim();
+  if (stdout === "") return [];
+  return stdout.split("\n").filter((line) => line !== "");
+};
 var findClaudeSessionOnHost = async (id, projectsDir) => {
   const root = projectsDir ?? join(process.env.HOME ?? "~", ".claude", "projects");
   let entries;
@@ -2424,14 +2497,18 @@ var rewriteSessionCwd = (content, fromCwd, toCwd) => {
   if (content === "") return "";
   return content.split("\n").map((line) => {
     if (line === "") return line;
-    const entry = JSON.parse(line);
-    if (typeof entry.cwd === "string" && entry.cwd === fromCwd) {
-      entry.cwd = toCwd;
-    }
-    if (entry.type === "session_meta" && typeof entry.payload === "object" && entry.payload !== null && typeof entry.payload.cwd === "string" && entry.payload.cwd === fromCwd) {
-      entry.payload.cwd = toCwd;
+    try {
+      const entry = JSON.parse(line);
+      if (typeof entry.cwd === "string" && entry.cwd === fromCwd) {
+        entry.cwd = toCwd;
+      }
+      if (entry.type === "session_meta" && typeof entry.payload === "object" && entry.payload !== null && typeof entry.payload.cwd === "string" && entry.payload.cwd === fromCwd) {
+        entry.payload.cwd = toCwd;
+      }
+      return JSON.stringify(entry);
+    } catch {
+      return line;
     }
-    return JSON.stringify(entry);
   }).join("\n");
 };
 var transferClaudeSession = (jsonl, fromCwd, toCwd) => rewriteSessionCwd(jsonl, fromCwd, toCwd);
@@ -2705,6 +2782,19 @@ var writeSandboxFile = async (handle, sandboxPath, content, tag) => {
     });
   }
 };
+var copyClaudeSessionFile = async ({
+  handle,
+  sourcePath,
+  fromCwd,
+  toCwd,
+  destPath,
+  tag
+}) => {
+  const jsonl = await readSandboxFile(handle, sourcePath, tag);
+  const rewritten = transferClaudeSession(jsonl, fromCwd, toCwd);
+  await mkdir(dirname(destPath), { recursive: true });
+  await writeFile(destPath, rewritten);
+};
 var makeClaudeSessionStorage = (options) => {
   const hostProjectsDir = options?.sessionStorage?.hostProjectsDir;
   const sandboxProjectsDir = options?.sessionStorage?.sandboxProjectsDir ?? "/home/agent/.claude/projects";
@@ -2717,20 +2807,48 @@ var makeClaudeSessionStorage = (options) => {
       return readFile(path2, "utf-8");
     },
     captureToHost: async ({ hostCwd, sandboxCwd, sessionId, handle }) => {
-      const sandboxPath = claudeSandboxSessionPath(
+      await copyClaudeSessionFile({
+        handle,
+        sourcePath: claudeSandboxSessionPath(
+          sandboxCwd,
+          sessionId,
+          sandboxProjectsDir
+        ),
+        fromCwd: sandboxCwd,
+        toCwd: hostCwd,
+        destPath: claudeHostSessionPath(hostCwd, sessionId, hostProjectsDir),
+        tag: "claude-cap"
+      });
+      const subagentSandboxPaths = await listClaudeSubagentSessionsInSandbox(
         sandboxCwd,
         sessionId,
+        handle,
         sandboxProjectsDir
       );
-      const jsonl = await readSandboxFile(handle, sandboxPath, "claude-cap");
-      const rewritten = transferClaudeSession(jsonl, sandboxCwd, hostCwd);
-      const hostPath = claudeHostSessionPath(
+      const hostSubagentsDir = claudeSubagentsDirOnHost(
         hostCwd,
         sessionId,
         hostProjectsDir
       );
-      await mkdir(dirname(hostPath), { recursive: true });
-      await writeFile(hostPath, rewritten);
+      for (const sandboxSubagentPath of subagentSandboxPaths) {
+        try {
+          await copyClaudeSessionFile({
+            handle,
+            sourcePath: sandboxSubagentPath,
+            fromCwd: sandboxCwd,
+            toCwd: hostCwd,
+            destPath: join(
+              hostSubagentsDir,
+              posix.basename(sandboxSubagentPath)
+            ),
+            tag: "claude-sub"
+          });
+        } catch (err) {
+          console.error(
+            `sandcastle: failed to capture Claude subagent transcript ${sandboxSubagentPath}: ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+      }
     },
     resumeIntoSandbox: async ({ hostCwd, sandboxCwd, sessionId, handle }) => {
       const hostPath = claudeHostSessionPath(