@agent-compose/sdk 0.5.1 → 0.5.5

package/src/runtimes/claude.ts

@@ -1,9 +1,10 @@
 /** Claude Agent SDK runtime — replaces the old Claude CLI subprocess runtime. */
 
-import { query, type HookCallback, type PreToolUseHookInput, type ThinkingConfig } from "@anthropic-ai/claude-agent-sdk";
+import { query, type HookCallback, type PreToolUseHookInput, type SDKUserMessage, type ThinkingConfig } from "@anthropic-ai/claude-agent-sdk";
 import type { AgentMessage, ModelExecutionContract, RuntimeOptions, SandboxProvider, ToolCallGateResult } from "../index.js";
 import { defineRuntime } from "../types/runtime.js";
 import { DEFAULT_CLAUDE_MODEL } from "../agent/agent-loop.js";
+import { AsyncQueue } from "../agent/async-queue.js";
 import { runProcessorChain } from "../processors/runner.js";
 import type { ProcessorContext, ToolCall } from "../processors/processor.js";
 import { RequestContext } from "../request-context/request-context.js";
@@ -26,6 +27,12 @@ function translateMessage(message: Record<string, unknown>): AgentMessage[] {
       const b = block as Record<string, unknown>;
       if (b.type === "text") msgs.push({ type: "text", text: String(b.text ?? ""), timestamp: ts });
       if (b.type === "thinking") msgs.push({ type: "thinking", text: String(b.thinking ?? ""), timestamp: ts });
+      // `redacted_thinking` is the encrypted-thinking variant emitted by
+      // reasoning models that don't expose chain-of-thought (the content
+      // is an opaque encrypted blob, not human-readable text). Surface
+      // it as a placeholder so the Agent tab's thinking badge isn't
+      // visually empty for those models.
+      if (b.type === "redacted_thinking") msgs.push({ type: "thinking", text: "(redacted)", timestamp: ts });
       if (b.type === "tool_use") msgs.push({ type: "tool_use", toolName: String(b.name ?? ""), toolInput: (b.input ?? {}) as Record<string, unknown>, toolUseId: String(b.id ?? ""), timestamp: ts });
     }
     return msgs;
@@ -82,24 +89,63 @@ export interface ClaudeRuntimeConfig {
   effort?: "low" | "medium" | "high" | "xhigh" | "max";
 }
 
+/** Canonical install path for Claude Code inside a Vercel sandbox.
+ *  Our `agent-env` setup copies the native binary here as a real file
+ *  (not a symlink) so it survives snapshotting. The Anthropic installer
+ *  drops a symlink at `~/.local/bin/claude` pointing into user-home,
+ *  which Vercel sandbox snapshots don't preserve reliably — pinning
+ *  `/usr/local/bin/claude` instead bypasses both PATH-priority issues
+ *  (`~/.local/bin` comes earlier than `/usr/local/bin`) and the
+ *  broken-symlink-after-restore problem. Callers can override via
+ *  `pathToClaudeCodeExecutable` or `CLAUDE_CODE_EXECUTABLE`. */
+const DEFAULT_CLAUDE_PATH = "/usr/local/bin/claude";
+
 export class ClaudeRunner implements ModelExecutionContract {
   supportsToolCallProcessor = true;
+  readonly kind = "claude";
+
+  // ADR-0006 pause-resume hooks intentionally omitted.
+  //
+  // The Claude Agent SDK keeps the conversation SERVER-SIDE at
+  // Anthropic, addressed by `session_id`. Each `sendMessage` call
+  // passes `resume: sessionId` and Anthropic rehydrates the prior
+  // transcript; `ClaudeRunner` holds no instance state across calls.
+  //
+  // `sessionId` itself lives in the agent loop (see
+  // agent-loop.ts :: `lastSessionId`) and is part of the loop's own
+  // state file — restored automatically on pause-resume. So the loop
+  // gets everything it needs without any per-runtime blob; defining
+  // `captureCheckpoint`/`restoreCheckpoint` here would just be empty.
+  //
+  // Caveat: Anthropic's server-side session retention is bounded by
+  // their TTL (not ours). For workflow pauses inside that window
+  // (default workflowRunTimeout is 7 days) the resume succeeds; a
+  // 30-day pause may get session-not-found from `resume:` and would
+  // need a fallback to client-managed messages. Documented limitation.
 
   constructor(
-    // Claude Agent SDK executes in this process. In dispatched workflows this
-    // process is already the runner sandbox, so there is no remote provider hop.
     _sandbox: SandboxProvider,
     private readonly options: RuntimeOptions = {},
     private readonly config: ClaudeRuntimeConfig = {},
   ) {}
 
+  get model(): string {
+    return this.config.model ?? this.options.model ?? DEFAULT_CLAUDE_MODEL;
+  }
+
   async gateToolCall(call: ToolCall, ctx: ProcessorContext): Promise<ToolCallGateResult> {
     const verdict = await runProcessorChain(this.options.processors ?? [], p => p.processToolCall, call, ctx);
     if (verdict.kind === "continue") return { kind: "allow", call: verdict.value };
     return verdict;
   }
 
-  async *sendMessage(opts: { prompt: string; sessionId?: string; iteration?: number; signal?: AbortSignal }): AsyncGenerator<AgentMessage> {
+  async *sendMessage(opts: {
+    prompt: string;
+    sessionId?: string;
+    iteration?: number;
+    signal?: AbortSignal;
+    inboxStream?: AsyncIterable<{ text: string; senderName?: string | null }>;
+  }): AsyncGenerator<AgentMessage> {
     const requestContext = this.options.requestContext ?? RequestContext.fromReserved({
       teamId: "", runId: "", workflowId: "",
       factoryId: null, apiKeyScopes: [], parentRunId: null,
@@ -124,10 +170,48 @@ export class ClaudeRunner implements ModelExecutionContract {
       return { continue: false, systemMessage: gate.reason };
     };
 
+    // Streaming-input mode (Claude Agent SDK):
+    //   When the caller passes `inboxStream`, we build a pushable
+    //   AsyncIterable<SDKUserMessage> queue. The initial prompt is
+    //   pushed as the first user turn; inbox messages arriving while
+    //   the assistant is mid-turn are pushed as additional user turns
+    //   and the SDK delivers them at the next safe boundary.
+    //
+    //   Without an inboxStream we keep the simple string-prompt path —
+    //   no queue, same behaviour as before. This keeps non-interactive
+    //   workflows (memory extractor, etc.) on the original code path.
+    //
+    //   The queue is closed when the SDK's `result` message indicates
+    //   the iteration's assistant turns are done; without close() the
+    //   iterable would block forever waiting for more user input.
+    const inboxQueue = opts.inboxStream ? new AsyncQueue<SDKUserMessage>() : null;
+    if (inboxQueue) {
+      inboxQueue.push({
+        type: "user",
+        message: { role: "user", content: opts.prompt },
+        parent_tool_use_id: null,
+      });
+      // Drain the inbox iterable into the queue. Runs in parallel
+      // with the assistant; pushes user turns as they arrive.
+      void (async () => {
+        try {
+          for await (const ev of opts.inboxStream!) {
+            const tag = ev.senderName ? `[message from ${ev.senderName}]\n` : "[user message]\n";
+            inboxQueue.push({
+              type: "user",
+              message: { role: "user", content: tag + ev.text },
+              parent_tool_use_id: null,
+            });
+          }
+        } catch { /* iterable ended or aborted */ }
+      })();
+    }
+    const promptForQuery: string | AsyncIterable<SDKUserMessage> = inboxQueue ?? opts.prompt;
+
     try {
       let emittedAssistantText = false;
       for await (const message of query({
-        prompt: opts.prompt,
+        prompt: promptForQuery,
         options: {
           tools: this.options.allowedTools,
           allowedTools: this.options.allowedTools,
@@ -138,7 +222,9 @@ export class ClaudeRunner implements ModelExecutionContract {
           effort: this.config.effort,
           cwd: this.options.cwd,
           env: { ...process.env, ...(this.config.env ?? {}) },
-          pathToClaudeCodeExecutable: this.config.pathToClaudeCodeExecutable ?? process.env.CLAUDE_CODE_EXECUTABLE ?? "claude",
+          pathToClaudeCodeExecutable: this.config.pathToClaudeCodeExecutable
+            ?? process.env.CLAUDE_CODE_EXECUTABLE
+            ?? DEFAULT_CLAUDE_PATH,
           ...(this.config.claudeMdContent ? { systemPrompt: { type: "preset" as const, preset: "claude_code" as const, append: this.config.claudeMdContent } } : {}),
           resume: opts.sessionId,
           mcpServers: this.config.mcpServers,
@@ -158,9 +244,18 @@ export class ClaudeRunner implements ModelExecutionContract {
           if (msg.type === "text" && raw.type === "assistant") emittedAssistantText = true;
           yield msg;
         }
+        // End-of-iteration signal: SDK emits a `result` message after the
+        // assistant's turn completes. Close the queue so the AsyncIterable
+        // drains and query() returns. Without this, the iterable would
+        // block forever waiting for the next user turn that never comes.
+        if (raw.type === "result" && inboxQueue) inboxQueue.close();
       }
     } catch (err) {
       yield { type: "error", text: formatError(err), timestamp: now() };
+    } finally {
+      // Belt-and-braces — close on error/abort too so the dangling
+      // iterable doesn't leak the inboxStream consumer.
+      inboxQueue?.close();
     }
   }
 }

package/src/runtimes/codex.ts

@@ -0,0 +1,109 @@
+/**
+ * Codex CLI runtime — drives OpenAI's `codex exec --json` agentic CLI inside
+ * the sandbox and maps its JSONL event stream onto the AgentMessage contract.
+ * Built on the shared CLI-agent base; Codex brings its own loop + tools, so we
+ * only stream-parse what it prints.
+ *
+ * Auth: set `CODEX_API_KEY` (or `OPENAI_API_KEY`) in the sandbox env via a
+ * workflow secret. Requires the `codex` CLI installed in the sandbox image.
+ *
+ * ⚠️ NOT verified against a live `codex` run — the resume flag and the exact
+ * item shapes (command_execution / reasoning fields) are mapped from the docs
+ * (developers.openai.com/codex/noninteractive). Verify before production use.
+ */
+
+import type { AgentMessage } from "../index.js";
+import { createCliAgentRuntime, shellQuote, type CliAgentSpec } from "./_cli-agent.js";
+import { formatError } from "../utils/errors.js";
+
+function now(): string { return new Date().toISOString(); }
+
+const codexSpec: CliAgentSpec = {
+  kind: "codex",
+  authEnv: "CODEX_API_KEY",
+  // Codex reads the prompt from stdin when invoked as `codex exec ... -`.
+  promptPayload: (prompt) => prompt,
+  buildCommand: ({ promptPath, sessionId, model, cwd }) => {
+    const flags = [
+      "--json",
+      "--skip-git-repo-check",
+      // agent-compose already runs us inside an isolated sandbox VM, so codex
+      // must not try to nest its own seccomp/landlock sandbox or block on
+      // approvals (non-interactive). codex docs: this flag is "intended solely
+      // for running in environments that are externally sandboxed".
+      "--dangerously-bypass-approvals-and-sandbox",
+      ...(model ? ["-m", shellQuote(model)] : []),
+      ...(cwd ? ["-C", shellQuote(cwd)] : []),
+    ].join(" ");
+    // Fresh turn: `codex exec <flags> - < prompt`. Continue a thread:
+    // `codex exec resume <id> <flags> - < prompt`. (`-` = read prompt from stdin.)
+    const exec = sessionId
+      ? `codex exec resume ${shellQuote(sessionId)} ${flags}`
+      : `codex exec ${flags}`;
+    return `${exec} - < ${shellQuote(promptPath)}`;
+  },
+  extractSessionId: (p) =>
+    p.type === "thread.started" && typeof p.thread_id === "string" ? p.thread_id : undefined,
+  mapEvent: (p): AgentMessage[] => {
+    const ts = now();
+    switch (p.type) {
+      case "item.started":
+      case "item.completed": {
+        const item = p.item as Record<string, unknown> | undefined;
+        if (!item) return [];
+        const itype = String(item.type ?? "");
+        // Text + reasoning land on completion (started carries no final text).
+        if (itype === "agent_message") {
+          return p.type === "item.completed" ? [{ type: "text", text: String(item.text ?? ""), timestamp: ts }] : [];
+        }
+        if (itype === "reasoning") {
+          return p.type === "item.completed" ? [{ type: "thinking", text: String(item.text ?? ""), timestamp: ts }] : [];
+        }
+        // Command execution: started → tool_use, completed → tool_result.
+        if (itype === "command_execution") {
+          const id = String(item.id ?? "");
+          if (p.type === "item.started") {
+            return [{ type: "tool_use", toolName: "shell", toolInput: { command: String(item.command ?? "") }, toolUseId: id, timestamp: ts }];
+          }
+          const failed = item.status === "failed" || (typeof item.exit_code === "number" && item.exit_code !== 0);
+          return [{ type: "tool_result", toolUseId: id, output: String(item.aggregated_output ?? item.output ?? ""), isError: failed, timestamp: ts }];
+        }
+        // file_change / mcp_tool_call / web_search / todo: surface once, on completion.
+        if (p.type === "item.completed") {
+          return [{ type: "tool_use", toolName: itype || "item", toolInput: item, toolUseId: String(item.id ?? ""), timestamp: ts }];
+        }
+        return [];
+      }
+      case "turn.completed": {
+        const u = p.usage as Record<string, number> | undefined;
+        if (!u) return [];
+        return [{
+          type: "usage",
+          inputTokens: u.input_tokens ?? 0,
+          outputTokens: u.output_tokens ?? 0,
+          cacheReadTokens: u.cached_input_tokens ?? 0,
+          cacheCreationTokens: 0,
+          durationMs: 0,
+          numTurns: 1,
+          timestamp: ts,
+        }];
+      }
+      case "turn.failed":
+      case "error":
+        return [{ type: "error", text: formatError(p.error ?? p.message ?? p), timestamp: ts }];
+      default:
+        return [];
+    }
+  },
+};
+
+export interface CodexRuntimeConfig {
+  /** Codex model id (`-m`). Omit to use the codex CLI's configured default. */
+  model?: string;
+}
+
+export function createCodexRuntime(config: CodexRuntimeConfig = {}) {
+  return createCliAgentRuntime(codexSpec, config.model);
+}
+
+export default createCodexRuntime();

package/src/runtimes/openai-desktop.ts

@@ -21,9 +21,20 @@ export interface OpenAIDesktopRunnerOptions extends RuntimeOptions {
 }
 
 export class OpenAIDesktopRunner implements ModelExecutionContract {
+  readonly kind = "openai-desktop";
+  readonly model = "computer-use-preview";
   private openai: OpenAI;
   private label: string;
 
+  // ADR-0006 pause-resume hooks intentionally omitted.
+  //
+  // The computer-use-preview model treats every `sendMessage` as a
+  // fresh conversation seeded with the current desktop screenshot —
+  // the `messages` array and `previousResponseId` are scoped to ONE
+  // call, never carried across. The desktop screenshot IS the state,
+  // and the sandbox snapshot already captures that on the filesystem.
+  // No runtime-private blob needed.
+
   constructor(
     private sandbox: DesktopSandboxProvider,
     opts: OpenAIDesktopRunnerOptions,

package/src/runtimes/vercel.ts

@@ -3,7 +3,7 @@
  * owned coding tools over SandboxProvider.
  */
 
-import { streamText, stepCountIs, tool, type LanguageModel } from "ai";
+import { streamText, stepCountIs, tool, gateway, type LanguageModel } from "ai";
 import type { AgentMessage, ModelExecutionContract, RuntimeOptions, SandboxProvider, ToolCallGateResult } from "../index.js";
 import { defineRuntime } from "../types/runtime.js";
 import { codingTools, type CodingTool } from "../tools/index.js";
@@ -15,12 +15,27 @@ import { formatError } from "../utils/errors.js";
 type AiToolSet = Record<string, ReturnType<typeof tool<Record<string, unknown>, string>>>;
 
 export interface VercelRuntimeConfig {
-  /** Vercel AI SDK language model (e.g. openai("gpt-5"), anthropic("claude-sonnet-4-5")). */
+  /** The model to drive — this is the only thing that varies per provider;
+   *  there is no per-provider runtime. `LanguageModel` accepts every provider:
+   *   - a gateway model-id string routed via the Vercel AI Gateway (set
+   *     `AI_GATEWAY_API_KEY`; no provider package needed), e.g. "openai/gpt-5",
+   *     "google/gemini-2.5-pro", "xai/grok-4", "deepseek/deepseek-chat",
+   *     "mistral/mistral-large-latest", "anthropic/claude-sonnet-4-5";
+   *   - or a `LanguageModel` object from a provider package (add the dep + set
+   *     its API-key env), e.g. `openai("gpt-5")`, `google("gemini-2.5-pro")`. */
   model: LanguageModel;
   /** Optional system prompt prepended to every model call. */
   system?: string;
   /** Override/extend the default coding tools. Defaults: Read, Write, Edit, Bash. */
   tools?: readonly CodingTool[];
+  /** Short runtime self-id surfaced on `agent.spawned` so the dashboard can
+   *  show a per-agent runtime icon (e.g. "openai", "gemini"). Provider presets
+   *  set this; bare `createVercelRuntime` callers can leave it unset. */
+  kind?: string;
+  /** Display model id surfaced on `agent.spawned` (the Agent tab labels which
+   *  model each agent ran). `model` above is the AI SDK LanguageModel object;
+   *  this is its human-readable id string. */
+  modelId?: string;
 }
 
 function now(): string { return new Date().toISOString(); }
@@ -71,6 +86,11 @@ function toAgentMessages(part: Record<string, unknown>): AgentMessage[] {
 
 export class VercelRunner implements ModelExecutionContract {
   supportsToolCallProcessor = true;
+  /** Surfaced on `agent.spawned` for the dashboard's per-agent runtime icon +
+   *  model label. Set from the (provider preset's) config; undefined for a
+   *  bare `createVercelRuntime` that didn't label itself. */
+  readonly kind?: string;
+  readonly model?: string;
   private readonly tools: readonly CodingTool[];
   private readonly messages: unknown[] = [];
 
@@ -80,6 +100,8 @@ export class VercelRunner implements ModelExecutionContract {
     private readonly config: VercelRuntimeConfig,
   ) {
     this.tools = config.tools ?? codingTools;
+    this.kind = config.kind;
+    this.model = config.modelId;
   }
 
   async gateToolCall(call: ToolCall, ctx: ProcessorContext): Promise<ToolCallGateResult> {
@@ -88,6 +110,32 @@ export class VercelRunner implements ModelExecutionContract {
     return verdict;
   }
 
+  /** ADR-0006 pause-resume hooks. The Vercel AI SDK holds the running
+   *  conversation client-side in `this.messages` — every `streamText`
+   *  call passes the full array as `messages` and reconstructs it from
+   *  `response.messages` after completion. A pause-induced subprocess
+   *  exit loses the array; the new subprocess constructs a fresh
+   *  `VercelRunner` with `this.messages = []` and the next sendMessage
+   *  would see only the current iteration's prompt — conversation
+   *  history broken. The agent loop calls these at every iteration
+   *  boundary so the messages array round-trips through the sandbox
+   *  snapshot. */
+  captureCheckpoint(): unknown {
+    return { messages: [...this.messages] };
+  }
+
+  restoreCheckpoint(blob: unknown): void {
+    if (!blob || typeof blob !== "object") {
+      throw new Error("Vercel runtime checkpoint is invalid: expected an object with messages[]");
+    }
+    const incoming = (blob as { messages?: unknown }).messages;
+    if (!Array.isArray(incoming)) {
+      throw new Error("Vercel runtime checkpoint is invalid: expected messages[]");
+    }
+    this.messages.length = 0;
+    this.messages.push(...incoming);
+  }
+
   private buildTools(iteration: number, signal?: AbortSignal): AiToolSet {
     const set: AiToolSet = {};
     for (const t of this.tools) {
@@ -178,3 +226,31 @@ export function createVercelRuntime(config: VercelRuntimeConfig) {
     create: (sandbox, opts) => new VercelRunner(sandbox, opts, config),
   });
 }
+
+/** One model offered by the Vercel AI Gateway. Pass `id` straight to
+ *  `createVercelRuntime({ model: id })`. */
+export interface VercelRuntimeModel {
+  /** Gateway model id, e.g. "openai/gpt-5". Usable directly as the runtime model. */
+  id: string;
+  /** Human-readable display name. */
+  name: string;
+}
+
+/**
+ * List the models the Vercel runtime accepts as a gateway model-id string — the
+ * LIVE Vercel AI Gateway catalog, so it never goes stale. This is the canonical
+ * answer to "what models can I pass to `createVercelRuntime`?" for the string
+ * form (`createVercelRuntime({ model: "openai/gpt-5" })`).
+ *
+ * Requires `AI_GATEWAY_API_KEY`. The other form — a `LanguageModel` object from
+ * an `@ai-sdk/<provider>` package — supports whatever that provider package
+ * does (see its docs); there's no single cross-form list because the runtime is
+ * model-agnostic. Browse the catalog in a UI at https://vercel.com/ai-gateway/models.
+ */
+export async function listVercelRuntimeModels(): Promise<VercelRuntimeModel[]> {
+  const { models } = await gateway.getAvailableModels();
+  return models
+    .filter((m) => m.modelType == null || m.modelType === "language")
+    .map((m) => ({ id: m.id, name: m.name }))
+    .sort((a, b) => a.id.localeCompare(b.id));
+}

package/src/sandbox.ts

@@ -118,9 +118,28 @@ interface SandboxProviderDef {
 // ── E2B helpers ───────────────────────────────────────────────────────────────
 
 export function makeSandboxProvider(sb: Sandbox | Desktop): SandboxProvider {
+  const commands = sb.commands as { run: (cmd: string, opts?: unknown) => Promise<{ exitCode: number; stdout: string; stderr?: string }> };
   return {
     sandboxId: sb.sandboxId,
-    commands: sb.commands,
+    commands: {
+      async run(cmd, opts) {
+        let stderr = "";
+        const result = await commands.run(cmd, {
+          ...opts,
+          onStderr: (chunk: string) => {
+            stderr += chunk;
+            opts?.onStderr?.(chunk);
+          },
+        });
+        return {
+          exitCode: result.exitCode,
+          stdout: result.stdout,
+          stderr: typeof (result as { stderr?: unknown }).stderr === "string"
+            ? (result as { stderr: string }).stderr
+            : stderr,
+        };
+      },
+    },
     files: {
       async write(path, content) { await sb.files.write(path, content); },
     },
@@ -161,7 +180,7 @@ export async function parseSseExecStream(
   body: ReadableStream<Uint8Array>,
   opts?: ParseSseExecStreamOptions,
 ): Promise<SandboxCommandResult> {
-  let stdout = "", exitCode = 0, exited = false;
+  let stdout = "", stderr = "", exitCode = 0, exited = false;
   const reader = body.getReader(), decoder = new TextDecoder();
   let buf = "";
   while (true) {
@@ -173,9 +192,10 @@ export async function parseSseExecStream(
     for (const line of lines) {
       if (!line.startsWith("data: ")) continue;
       let event: SseEvent;
-      try { event = JSON.parse(line.slice(6)) as SseEvent; } catch { continue; }
+      try { event = JSON.parse(line.slice(6)) as SseEvent; }
+      catch (err) { throw new Error(`Malformed sandbox exec event: ${err instanceof Error ? err.message : String(err)}`); }
       if (event.type === "stdout")       { stdout += event.data ?? ""; opts?.onStdout?.(event.data ?? ""); }
-      else if (event.type === "stderr")  { opts?.onStderr?.(event.data ?? ""); }
+      else if (event.type === "stderr")  { stderr += event.data ?? ""; opts?.onStderr?.(event.data ?? ""); }
       else if (event.type === "exit")    { exitCode = event.exitCode ?? 0; exited = true; }
       else if (event.type === "error")   { throw new Error(`Sandbox exec error: ${event.data}`); }
     }
@@ -183,7 +203,8 @@ export async function parseSseExecStream(
     // QUIC tunnels can delay the stream-end signal even after all data has arrived.
     if (exited) break;
   }
-  return { exitCode, stdout };
+  if (!exited) throw new Error("Sandbox exec stream ended without an exit event");
+  return { exitCode, stdout, stderr };
 }
 
 // ── Vercel helpers ────────────────────────────────────────────────────────────
@@ -200,31 +221,28 @@ function makeVercelSandboxProvider(sb: any, globalEnvs?: Record<string, string>)
     sandboxId: sb.sandboxId,
     commands: {
       async run(cmd, opts) {
-        // Vercel's runCommand takes a native `sudo` flag — pass it on the `sh`
-        // invocation so the whole shell (and every command it spawns) runs as
-        // root, matching `sb.runCommand({ cmd, args, sudo: true })` semantics.
-        const sudo = opts?.sudo === true;
-        if (opts?.background) {
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          void (sb.runCommand({ cmd: "sh", args: ["-c", cmd], cwd: opts.cwd, env: mergeEnvs(opts.envs), detached: true, ...(sudo ? { sudo: true } : {}) }) as Promise<any>)
-            .catch((err: unknown) => console.error(`[sandbox] background command failed: ${err instanceof Error ? err.message : String(err)}`));
-          return { exitCode: 0, stdout: "" };
-        }
         const signal = opts?.timeoutMs ? AbortSignal.timeout(opts.timeoutMs) : undefined;
         let stdout = "";
+        let stderr = "";
+        // `sudo: true` is Vercel's native root flag — applied to the `sh`
+        // invocation so the whole shell (and its children) runs as root.
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const handle: any = await sb.runCommand({ cmd: "sh", args: ["-c", cmd], cwd: opts?.cwd, env: mergeEnvs(opts?.envs), detached: true, signal, ...(sudo ? { sudo: true } : {}) });
+        const handle: any = await sb.runCommand({ cmd: "sh", args: ["-c", cmd], cwd: opts?.cwd, env: mergeEnvs(opts?.envs), detached: true, signal, ...(opts?.sudo ? { sudo: true } : {}) });
         // Reconnect to the already-running command on transient stream failures (e.g. BrotliDecompressionError).
+        // `h.logs()` replays from the start on reconnect, so reset accumulators per
+        // attempt to avoid double-counting. The streaming callbacks may still fire
+        // for duplicate chunks during retries — an acceptable tradeoff for resilience.
         await pRetry(async (attempt) => {
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
           const h: any = attempt === 1 ? handle : await sb.getCommand(handle.cmdId);
+          if (attempt > 1) { stdout = ""; stderr = ""; }
           for await (const log of h.logs()) {
             if (log.stream === "stdout") { stdout += log.data; opts?.onStdout?.(log.data); }
-            else { opts?.onStderr?.(log.data); }
+            else { stderr += log.data; opts?.onStderr?.(log.data); }
           }
         }, { retries: 3, minTimeout: 1_000, factor: 2 });
         const finished = await handle.wait();
-        return { exitCode: finished.exitCode, stdout };
+        return { exitCode: finished.exitCode, stdout, stderr };
       },
     },
     files: {
@@ -277,12 +295,13 @@ export function makeLocalSandboxProvider(): SandboxProvider {
             stdio: ["ignore", "pipe", "pipe"],
           });
           let stdout = "";
+          let stderr = "";
           proc.stdout?.setEncoding("utf8");
           proc.stderr?.setEncoding("utf8");
           proc.stdout?.on("data", (chunk: string) => { stdout += chunk; opts?.onStdout?.(chunk); });
-          proc.stderr?.on("data", (chunk: string) => { opts?.onStderr?.(chunk); });
+          proc.stderr?.on("data", (chunk: string) => { stderr += chunk; opts?.onStderr?.(chunk); });
           proc.on("error", reject);
-          proc.on("close", (code) => resolve({ exitCode: code ?? 0, stdout }));
+          proc.on("close", (code) => resolve({ exitCode: code ?? 0, stdout, stderr }));
         });
       },
     },

package/src/sse.ts

@@ -7,9 +7,8 @@
  *   - `event`: event name (from `event:` line; `""` if absent)
  *   - `data`:  parsed JSON payload (the SDK's stream events are always JSON)
  *
- * Malformed payloads are silently skipped — same behaviour as the previous
- * CLI-side parser. Caller drives the loop via `for await (...)` and is
- * responsible for breaking on terminal events.
+ * Malformed payloads throw. A dropped terminal event is worse than a loud
+ * protocol error for log consumers.
  *
  * Output type stays loose (`Record<string, unknown>`) on purpose: typed
  * unions like `RunEvent` aren't structurally narrowable from
@@ -42,10 +41,13 @@ export async function* parseSseStream(
         if (line.startsWith("event:")) { event = line.slice(6).trim();         continue; }
         if (line.startsWith("data:"))  { dataLines.push(line.slice(5).trim()); continue; }
         if (line === "" && dataLines.length > 0) {
+          let data: Record<string, unknown>;
           try {
-            const data = JSON.parse(dataLines.join("\n")) as Record<string, unknown>;
-            yield { id: seq, event, data };
-          } catch { /* malformed — skip */ }
+            data = JSON.parse(dataLines.join("\n")) as Record<string, unknown>;
+          } catch (err) {
+            throw new Error(`Malformed SSE JSON payload for event "${event || "message"}": ${err instanceof Error ? err.message : String(err)}`);
+          }
+          yield { id: seq, event, data };
           event = ""; seq = 0; dataLines = [];
         }
       }

package/src/step-invocation/index.ts

@@ -20,6 +20,7 @@
 
 export {
   STEP_RESULT_PREFIX,
+  STEP_PAUSE_PREFIX,
   STEP_ENV,
   RUNNER_BUNDLE_PATH,
   RUNNER_COMMAND,
@@ -30,4 +31,4 @@ export { invokeStep, parseStepResult, buildStepEnvs } from "./invoker.js";
 export { serveStep } from "./server.js";
 export type { StepHandler, ServeStepRequest, StepHandlerResult } from "./server.js";
 export { StepExecutionError } from "./types.js";
-export type { StepRequest, StepResult, StepInvocationError } from "./types.js";
+export type { StepRequest, StepResult, StepInvocationError, StepPauseRequest } from "./types.js";