@ai-hero/sandcastle 0.9.0 → 0.10.0

package/README.md

@@ -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>"

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,
@@ -896,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 {
@@ -1013,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,
@@ -1525,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,
@@ -2304,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,