@agent-compose/sdk 0.5.8 → 0.6.0

package/src/step-invocation/invoker.ts

@@ -24,7 +24,7 @@
 import { randomBytes } from "node:crypto";
 import { z } from "zod";
 import { SandboxUnavailableError } from "../sandbox-errors.js";
-import type { SandboxProvider } from "../types/sandbox.js";
+import type { SandboxProvider, SandboxBackgroundProcess } from "../types/sandbox.js";
 import { RUNNER_COMMAND, STEP_ENV, stepResultLinePrefix, stepPauseLinePrefix, requestContextPath, stepInputPath, stepResultFilePath } from "./protocol.js";
 import { StepPauseRequestSchema } from "./types.js";
 import type { StepRequest, StepResult } from "./types.js";
@@ -196,40 +196,34 @@ export interface InvokeStepOptions {
   onStderr?: (line: string) => void;
 }
 
-export async function invokeStep<TOutput = unknown>(
-  sandbox: SandboxProvider,
-  request: StepRequest,
-  opts?: InvokeStepOptions,
-): Promise<StepResult<TOutput>> {
-  const resultToken = randomBytes(16).toString("hex");
-
-  await Promise.all([
-    sandbox.files.write(stepInputPath(request.stepIndex),      JSON.stringify(request.input)),
-    sandbox.files.write(requestContextPath(request.stepIndex), JSON.stringify(request.requestContext)),
-  ]);
-
-  const envs = {
-    ...(opts?.envs ?? {}),
-    ...buildStepEnvs({
-      runId:       request.runId,
-      stepIndex:   request.stepIndex,
-      resultToken,
-      isResume:    opts?.isResume,
-    }),
-  };
+/** A step running as a background command (ADR-0028). The activity races its
+ *  `wait()` against a server pause request; on a pause it freezes the VM
+ *  (`pauseProcess`) and persists `runnerPid` + `resultToken` so the resume
+ *  activity can `reconnectStep(...)` to the SAME process — no re-run. */
+export interface RunningStep<TOutput = unknown> {
+  /** OS pid of the background runner inside the VM — the reconnect handle. */
+  runnerPid: number;
+  /** Per-invocation token keying the durable result file the runner writes. */
+  resultToken: string;
+  /** Await the runner's exit and classify its output into a `StepResult`. */
+  wait(): Promise<StepResult<TOutput>>;
+}
 
-  // The sandbox emits stdout as raw chunks, not lines. Buffer between
-  // emissions so a `console.log` split across two chunks (or a partial
-  // trailing line) is delivered to onStdout/onStderr as one logical line.
-  // Sentinel lines (carrying `resultToken`) are filtered out so callers
-  // never see protocol bytes in user-log capture. Both the result and
-  // pause prefixes are built from the same shared helpers `parseStepResult`
-  // uses, so the filter and the parser can't drift apart.
+/** Buffer the sandbox's raw stdout/stderr chunks into whole lines, filtering
+ *  the protocol sentinel out of `onStdout` so user-log capture never sees
+ *  protocol bytes. Shared by the foreground (`invokeStep`), background
+ *  (`launchStep`), and resume (`reconnectStep`) paths so the filter and the
+ *  result parser can't drift. Returns the per-stream chunk handlers (undefined
+ *  when the caller passed no sink) plus a `flush` for trailing newline-less
+ *  output. */
+function makeStreamSplitters(
+  opts: Pick<InvokeStepOptions, "onStdout" | "onStderr"> | undefined,
+  resultToken: string,
+): { onStdout?: (chunk: string) => void; onStderr?: (chunk: string) => void; flush: () => void } {
   const resultSentinel = stepResultLinePrefix(resultToken);
   const pauseSentinel  = stepPauseLinePrefix(resultToken);
-  const isSentinel = (line: string) =>
-    line.startsWith(resultSentinel) || line.startsWith(pauseSentinel);
-  const makeLineSplitter = (sink: ((line: string) => void) | undefined, filterSentinel: boolean) => {
+  const isSentinel = (line: string) => line.startsWith(resultSentinel) || line.startsWith(pauseSentinel);
+  const make = (sink: ((line: string) => void) | undefined, filterSentinel: boolean) => {
     if (!sink) return { onChunk: undefined, flush: () => {} };
     let buf = "";
     return {
@@ -243,10 +237,6 @@ export async function invokeStep<TOutput = unknown>(
           sink(line);
         }
       },
-      // Drain any remaining buffered output that ended without a newline.
-      // Called after `sandbox.commands.run` resolves so a runner that
-      // exits with `process.stdout.write("final")` (no trailing \n)
-      // doesn't silently drop its last line.
       flush: () => {
         if (buf.length === 0) return;
         const line = buf;
@@ -256,16 +246,102 @@ export async function invokeStep<TOutput = unknown>(
       },
     };
   };
-  const stdoutSplitter = makeLineSplitter(opts?.onStdout, true);
-  const stderrSplitter = makeLineSplitter(opts?.onStderr, false);
+  const stdout = make(opts?.onStdout, true);
+  const stderr = make(opts?.onStderr, false);
+  return {
+    ...(stdout.onChunk ? { onStdout: stdout.onChunk } : {}),
+    ...(stderr.onChunk ? { onStderr: stderr.onChunk } : {}),
+    flush: () => { stdout.flush(); stderr.flush(); },
+  };
+}
+
+/** Turn the runner's terminal output into a kinded `StepResult`. stdout is the
+ *  fast path; the runner also persists the sentinel to a durable token-keyed
+ *  file, so when stdout carries no sentinel (providers drop the tail of heavy
+ *  streams; a reconnect captures only post-resume output) we read the file
+ *  back. Shared by all three invocation paths. */
+async function classifyRunnerOutcome<TOutput>(
+  sandbox: SandboxProvider,
+  output: { stdout: string; stderr: string; exitCode: number },
+  resultToken: string,
+): Promise<StepResult<TOutput>> {
+  const parsed = parseStepResult<TOutput>(output.stdout, resultToken);
+  if (parsed) return parsed;
+
+  // No sentinel on stdout — read the durable token-keyed file the runner wrote
+  // BEFORE its stdout emit. A runner that exited 1 after a user-step throw
+  // still wrote `{ok:false, kind:"user-step"}`, which beats a generic exit.
+  const fileRead = await sandbox.commands.run(
+    `cat ${stepResultFilePath(resultToken)} 2>/dev/null || true`,
+  ).catch(() => null);
+  if (fileRead?.stdout) {
+    const fromFile = parseStepResult<TOutput>(fileRead.stdout, resultToken);
+    if (fromFile) return fromFile;
+  }
+
+  // Distinguish "runner exited badly before emitting" (runner-exit) from
+  // "runner exited cleanly but didn't speak the protocol" (protocol).
+  if (output.exitCode !== 0) {
+    const stderrTail = output.stderr.trim().slice(-2000);
+    const stdoutTail = output.stdout.trim().slice(-2000);
+    const details = [
+      stderrTail ? `stderr:\n${stderrTail}` : "",
+      stdoutTail ? `stdout:\n${stdoutTail}` : "",
+    ].filter(Boolean).join("\n");
+    return {
+      ok: false,
+      error: {
+        kind:     "runner-exit",
+        message:  `runner subprocess exited ${output.exitCode} before emitting a step result${details ? `\n${details}` : ""}`,
+        exitCode: output.exitCode,
+      },
+    };
+  }
+  const tail = output.stdout.trim().slice(-500);
+  return {
+    ok: false,
+    error: {
+      kind: "protocol",
+      message: `no tokenised step result on stdout or in the result file (runner exited 0 without emitting)${tail ? `\nstdout tail:\n${tail}` : ""}`,
+    },
+  };
+}
+
+/** Write the step's input + request-context files and build the runner env.
+ *  Shared by the foreground and background launch paths. Returns the
+ *  per-invocation `resultToken` + the env map. */
+async function prepareStepLaunch(
+  sandbox: SandboxProvider,
+  request: StepRequest,
+  opts?: InvokeStepOptions,
+): Promise<{ resultToken: string; envs: Record<string, string> }> {
+  const resultToken = randomBytes(16).toString("hex");
+  await Promise.all([
+    sandbox.files.write(stepInputPath(request.stepIndex),      JSON.stringify(request.input)),
+    sandbox.files.write(requestContextPath(request.stepIndex), JSON.stringify(request.requestContext)),
+  ]);
+  const envs = {
+    ...(opts?.envs ?? {}),
+    ...buildStepEnvs({ runId: request.runId, stepIndex: request.stepIndex, resultToken, isResume: opts?.isResume }),
+  };
+  return { resultToken, envs };
+}
+
+export async function invokeStep<TOutput = unknown>(
+  sandbox: SandboxProvider,
+  request: StepRequest,
+  opts?: InvokeStepOptions,
+): Promise<StepResult<TOutput>> {
+  const { resultToken, envs } = await prepareStepLaunch(sandbox, request, opts);
+  const splitters = makeStreamSplitters(opts, resultToken);
 
   let result: { stdout: string; stderr: string; exitCode: number };
   try {
     result = await sandbox.commands.run(RUNNER_COMMAND, {
       envs,
       timeoutMs: 0,
-      ...(stdoutSplitter.onChunk ? { onStdout: stdoutSplitter.onChunk } : {}),
-      ...(stderrSplitter.onChunk ? { onStderr: stderrSplitter.onChunk } : {}),
+      ...(splitters.onStdout ? { onStdout: splitters.onStdout } : {}),
+      ...(splitters.onStderr ? { onStderr: splitters.onStderr } : {}),
     });
   } catch (e) {
     // Typed sandbox-infrastructure failure: the engine's recovery contract
@@ -286,55 +362,90 @@ export async function invokeStep<TOutput = unknown>(
       exitCode: ce.exitCode ?? ce.result?.exitCode ?? 1,
     };
   }
-  stdoutSplitter.flush();
-  stderrSplitter.flush();
-
-  const parsed = parseStepResult<TOutput>(result.stdout, resultToken);
-  if (parsed) return parsed;
+  splitters.flush();
+  return classifyRunnerOutcome<TOutput>(sandbox, result, resultToken);
+}
 
-  // No sentinel on stdout. The runner also persists the sentinel line to a
-  // token-keyed file before emitting — providers drop the tail of heavy
-  // stdout streams, so read the durable copy back. Tried before exit-code
-  // classification: a runner that exited 1 after a user-step throw still
-  // wrote the file, and its `{ok:false, kind:"user-step"}` beats a generic
-  // runner-exit error. A runner killed before emitting wrote no file and
-  // falls through.
-  const fileRead = await sandbox.commands.run(
-    `cat ${stepResultFilePath(resultToken)} 2>/dev/null || true`,
-  ).catch(() => null);
-  if (fileRead?.stdout) {
-    const fromFile = parseStepResult<TOutput>(fileRead.stdout, resultToken);
-    if (fromFile) return fromFile;
+/**
+ * Launch the step runner as a BACKGROUND command (ADR-0028) and return a handle
+ * the activity drives: it races `wait()` against a server pause request and, on
+ * a pause, freezes the VM (`pauseProcess`) and persists `runnerPid` +
+ * `resultToken` so `reconnectStep` can continue the SAME process — no re-run.
+ * Requires a provider with `commands.runBackground` (E2B); the foreground
+ * `invokeStep` is the path for providers without it (Vercel).
+ */
+export async function launchStep<TOutput = unknown>(
+  sandbox: SandboxProvider,
+  request: StepRequest,
+  opts?: InvokeStepOptions,
+): Promise<RunningStep<TOutput>> {
+  if (!sandbox.commands.runBackground) {
+    throw new Error("launchStep requires a provider with background-command support (commands.runBackground)");
   }
+  const { resultToken, envs } = await prepareStepLaunch(sandbox, request, opts);
+  const splitters = makeStreamSplitters(opts, resultToken);
+  const proc = await sandbox.commands.runBackground(RUNNER_COMMAND, {
+    envs,
+    timeoutMs: 0,
+    ...(splitters.onStdout ? { onStdout: splitters.onStdout } : {}),
+    ...(splitters.onStderr ? { onStderr: splitters.onStderr } : {}),
+  });
+  return {
+    runnerPid:   proc.pid,
+    resultToken,
+    async wait() {
+      const result = await proc.wait();
+      splitters.flush();
+      return classifyRunnerOutcome<TOutput>(sandbox, result, resultToken);
+    },
+  };
+}
 
-  // No tokenised sentinel on stdout. Distinguish "runner exited badly
-  // before emitting" (runner-exit) from "runner exited cleanly but didn't
-  // speak the protocol" (protocol) — the exit code is the evidence.
-  if (result.exitCode !== 0) {
-    const stderrTail = result.stderr.trim().slice(-2000);
-    const stdoutTail = result.stdout.trim().slice(-2000);
-    const details = [
-      stderrTail ? `stderr:\n${stderrTail}` : "",
-      stdoutTail ? `stdout:\n${stdoutTail}` : "",
-    ].filter(Boolean).join("\n");
-    return {
-      ok: false,
-      error: {
-        kind:     "runner-exit",
-        message:  `runner subprocess exited ${result.exitCode} before emitting a step result${details ? `\n${details}` : ""}`,
-        exitCode: result.exitCode,
-      },
-    };
+/**
+ * Resume a previously-paused background runner (ADR-0028) and return a
+ * `RunningStep` handle — uniform with `launchStep` so the activity can race
+ * `wait()` against a fresh pause request (a resumed step can pause again). After
+ * the workflow reconnects the suspended VM (`Sandbox.connect` auto-resumes it),
+ * this re-attaches to the still-running runner by `runnerPid`; `wait()` awaits
+ * its exit (event-driven — no polling) and classifies the output (the durable
+ * result file is authoritative on this path). If the runner already exited
+ * during resume, the re-attach fails and `wait()` classifies from the file.
+ */
+export async function reconnectStep<TOutput = unknown>(
+  sandbox: SandboxProvider,
+  resume: { runnerPid: number; resultToken: string; stepIndex: number },
+  opts?: Pick<InvokeStepOptions, "onStdout" | "onStderr">,
+): Promise<RunningStep<TOutput>> {
+  if (!sandbox.commands.connectProcess) {
+    throw new Error("reconnectStep requires a provider with background-command support (commands.connectProcess)");
+  }
+  const { runnerPid, resultToken } = resume;
+  const splitters = makeStreamSplitters(opts, resultToken);
+  let proc: SandboxBackgroundProcess | null = null;
+  try {
+    proc = await sandbox.commands.connectProcess(runnerPid, {
+      ...(splitters.onStdout ? { onStdout: splitters.onStdout } : {}),
+      ...(splitters.onStderr ? { onStderr: splitters.onStderr } : {}),
+    });
+  } catch (e) {
+    // A sandbox-infrastructure failure must propagate intact (recovery
+    // contract). Anything else means the runner already exited during resume
+    // (we re-attached too late) — its durable result file is written, so the
+    // handle's wait() classifies from the file below.
+    if (e instanceof SandboxUnavailableError) throw e;
   }
-  // Carry the stdout tail: "no tokenised step result" alone is useless to
-  // an operator — the tail usually shows whether the runner finished its
-  // work (output truncated by the provider) or never got there.
-  const tail = result.stdout.trim().slice(-500);
+  const attached = proc;
   return {
-    ok: false,
-    error: {
-      kind: "protocol",
-      message: `no tokenised step result on stdout or in the result file (runner exited 0 without emitting)${tail ? `\nstdout tail:\n${tail}` : ""}`,
+    runnerPid,
+    resultToken,
+    async wait() {
+      let output: { stdout: string; stderr: string; exitCode: number } = { stdout: "", stderr: "", exitCode: 0 };
+      if (attached) {
+        try { output = await attached.wait(); }
+        catch (e) { if (e instanceof SandboxUnavailableError) throw e; }
+      }
+      splitters.flush();
+      return classifyRunnerOutcome<TOutput>(sandbox, output, resultToken);
     },
   };
 }

package/src/types/execution-context.ts

@@ -29,14 +29,6 @@ export interface BaseExecutionContext {
   setMetadata?: (data: Record<string, unknown>) => Promise<void>;
   /** Invoke another registered workflow and wait for it to settle. */
   invokeChild: InvokeChild;
-  /**
-   * Disk-backed memoise across pause-resume. First call runs `fn` and
-   * atomically writes the result to the sandbox; on resume the recorded
-   * value is returned and `fn` is NOT re-executed. Use for expensive
-   * deterministic transforms; for side effects, use `invokeChild`.
-   * See ADR-0006 §"`ctx.checkpoint(name, fn)` — disk-backed memoisation".
-   */
-  checkpoint<T>(name: string, fn: () => Promise<T> | T): Promise<T>;
   /**
    * Pause for feedback. The step exits and the workflow waits durably until
    * something resolves the pause (a resume call, a TTL expiry); on resume the

package/src/types/protocol.ts

@@ -33,6 +33,16 @@ export interface AgentMessageToolResult extends AgentMessageBase {
   toolUseId: string;
   output: string;
   isError: boolean;
+  /** Structured file diffs produced by the tool call, carried alongside the
+   *  rendered `output` so a richer renderer can use the structure without
+   *  re-plumbing the normaliser. Sourced from ACP `tool_call`/`tool_call_update`
+   *  `diff` content blocks (WS-C / ADR-0020 Q3). Optional and additive:
+   *  existing producers (claude / vercel / legacy JSONL) omit it. `oldText` is
+   *  null for a newly created file. */
+  diffs?: { path: string; oldText: string | null; newText: string }[];
+  /** File locations touched by the tool call (ACP `locations` field), enabling
+   *  "follow-along" UI. Optional and additive (WS-C / ADR-0020 Q3). */
+  locations?: { path: string; line?: number }[];
 }
 
 export interface AgentMessageDone extends AgentMessageBase {
@@ -55,6 +65,21 @@ export interface AgentMessageUsage extends AgentMessageBase {
   numTurns: number;
 }
 
+/** Structured execution plan emitted by an agent (ACP `plan` session update,
+ *  WS-C / ADR-0020 Q2). Each `plan` notification REPLACES the whole plan — the
+ *  normaliser emits one `AgentMessagePlan` per notification carrying the entire
+ *  `entries` array, and downstream treats the latest as authoritative. This is
+ *  NOT an `AgentStatus` and does not feed self-pause; it is observability only.
+ *  Additive 9th kind: existing producers never emit it. */
+export interface AgentMessagePlan extends AgentMessageBase {
+  type: "plan";
+  entries: {
+    content: string;
+    priority: "high" | "medium" | "low";
+    status: "pending" | "in_progress" | "completed";
+  }[];
+}
+
 export type AgentMessage =
   | AgentMessageInit
   | AgentMessageText
@@ -63,7 +88,8 @@ export type AgentMessage =
   | AgentMessageToolResult
   | AgentMessageDone
   | AgentMessageError
-  | AgentMessageUsage;
+  | AgentMessageUsage
+  | AgentMessagePlan;
 
 /** Status block the agent emits to signal iteration completion or blockers. */
 export interface AgentStatus {

package/src/types/runtime.ts

@@ -5,6 +5,7 @@
 import type { SandboxProvider } from "./sandbox.js";
 import type { AgentMessage } from "./protocol.js";
 import type { Processor, ProcessorContext, ToolCall } from "../processors/processor.js";
+import type { BoundaryPauseFn } from "../pause/pause-core.js";
 import type { RequestContext } from "../request-context/request-context.js";
 
 /** Configuration for a single MCP server. */
@@ -31,6 +32,19 @@ export interface RuntimeOptions {
   /** Agent id and label for processor context / adapter logs. */
   agentId?: string;
   iteration?: number;
+  /** The platform manual (file conventions, connectors & access, how to pause).
+   *  `agent()` builds it per-run (`buildAgentContextDoc`) and threads it here so
+   *  a runtime that supports a system-prompt append (the claude runtime) injects
+   *  it directly — instead of relying on the agent to `cat` the on-disk
+   *  AGENTS.md/CLAUDE.md, which the Agent SDK doesn't auto-load and which can
+   *  fail to write on a read-only/degraded working dir. */
+  agentManual?: string;
+  /** The run's pause boundary, threaded from the agent loop so a runtime-driven
+   *  pre-tool gate (e.g. the ACP `session/request_permission` path through
+   *  `gateToolCall`) can raise a human-approval `ctx.pause`. The runtime binds it
+   *  to the current `{ agentId, iteration }` when it builds a ProcessorContext.
+   *  Absent ⇒ a processor pause throws (no boundary; see `boundProcessorPause`). */
+  pause?: BoundaryPauseFn;
   /** Optional JSON schema for runtimes with native structured-output support. */
   outputFormat?: { type: "json_schema"; schema: Record<string, unknown> };
 }

package/src/types/sandbox-environment.ts

@@ -37,7 +37,7 @@
 import type { SandboxProvider } from "./sandbox.js";
 import { defineWorkflow } from "./workflow.js";
 import type { Workflow } from "../workflow-steps/types.js";
-import type { SnapshotConfig } from "./workflow-metadata.js";
+import type { SandboxResources, SnapshotConfig } from "./workflow-metadata.js";
 
 export interface SandboxEnvironmentDefinition {
   name: string;
@@ -48,6 +48,11 @@ export interface SandboxEnvironmentDefinition {
    *  useful — an env with no snapshot can't be referenced as a
    *  `bootFrom` on another workflow). */
   snapshots?: SnapshotConfig;
+  /** Which substrate to build this environment on (and any sizing).
+   *  An env image is provider-specific — a snapshot captured on E2B
+   *  can't boot on Vercel and vice-versa — so building the E2B base/
+   *  agent-env requires `resources: { provider: "e2b" }`. */
+  resources?: SandboxResources;
 }
 
 /** Sugar over `defineWorkflow` for setup-only workflows that exist to
@@ -61,7 +66,13 @@ export function defineSandboxEnvironment(
   }
   return defineWorkflow<void, Record<string, unknown>>({
     ...(env.description !== undefined ? { description: env.description } : {}),
+    ...(env.resources !== undefined ? { resources: env.resources } : {}),
     snapshots: env.snapshots ?? { saveLatest: true },
+    // Mark this as an environment build so the server skips the /factory mount
+    // for its runs — an env build builds a platform image and never touches the
+    // shared drive; baking a live Archil mount into its snapshot breaks the
+    // re-mount of every workflow that later boots from it (#13).
+    environmentBuild: true,
     run: async (_ctx, sandbox) => env.setup(sandbox),
   });
 }

package/src/types/sandbox.ts

@@ -25,6 +25,59 @@ export interface SandboxCommandResult {
   stderr: string;
 }
 
+/** A long-running command launched in the background (ADR-0028). Unlike
+ *  `commands.run` (which awaits completion on one connection), a background
+ *  command keeps running inside the VM independent of the launching
+ *  connection: it survives `pauseProcess()`/resume and is re-attachable by
+ *  `pid` after a fresh `Sandbox.connect`. This is what lets the platform
+ *  freeze an agent mid-turn for a human-in-the-loop pause and continue the
+ *  SAME process on resume — no re-run.
+ *
+ *  Implemented ONLY by process-resume-capable providers (E2B); the presence
+ *  of `commands.runBackground` IS the capability flag, paired with
+ *  `pauseProcess`. Providers without it leave both undefined and pause via
+ *  `snapshot()` + re-run instead. */
+export interface SandboxBackgroundProcess {
+  /** OS pid inside the VM — the durable handle used to reconnect after a
+   *  pause/resume cycle via `commands.connectProcess(pid)`. */
+  pid: number;
+  /** Resolve when the process exits, with its buffered result. Live output
+   *  streams to the `onStdout`/`onStderr` passed at launch / connect time.
+   *  Does NOT throw on a non-zero exit — the result carries `exitCode`. */
+  wait(): Promise<SandboxCommandResult>;
+  /** Force-terminate the process. */
+  kill(): Promise<void>;
+}
+
+/** A spawned long-lived command with a writable stdin and readable stdout,
+ *  exposed as byte web-streams. Unlike `commands.run` (which buffers to
+ *  completion and exposes stdout only via an `onStdout` callback), a duplex
+ *  handle keeps the process alive and lets the caller WRITE to its stdin —
+ *  the half `commands.run` cannot provide. It is the transport the ACP client
+ *  (`AcpClientPeer` over `ndJsonStream`) needs: the agent CLI reads JSON-RPC
+ *  request frames on stdin and answers on stdout.
+ *
+ *  Only `makeLocalSandboxProvider` implements it. The runner runs IN the
+ *  sandbox VM and spawns CLIs via the local provider (a plain `child_process`
+ *  pipe), so a duplex stdin works identically on Vercel/E2B/local. The
+ *  vercel/e2b providers are the SERVER→sandbox view and never spawn the in-VM
+ *  CLI, so they leave `spawnDuplex` undefined and callers fall back cleanly. */
+export interface SandboxDuplexProcess {
+  /** Subprocess stdin. JSON-RPC request frames are written here. */
+  stdin: WritableStream<Uint8Array>;
+  /** Subprocess stdout. JSON-RPC response/notification frames arrive here. */
+  stdout: ReadableStream<Uint8Array>;
+  /** Resolves when the subprocess exits, carrying the captured stderr tail. */
+  exited: Promise<{ exitCode: number; stderr: string }>;
+  /** Force-terminate the subprocess. */
+  kill(): void;
+}
+
+export interface SandboxSpawnDuplexOptions {
+  cwd?: string;
+  envs?: Record<string, string>;
+}
+
 /**
  * A sandbox provider implements the RAW provider operations only. It does NOT
  * implement transient-failure retry/backoff: reconnecting and snapshotting both
@@ -51,6 +104,21 @@ export interface SandboxProvider {
     // `run(sb, cmd)` helper is the canonical pattern — copy it into any
     // setup workflow that needs to fail loudly on command errors.
     run(cmd: string, opts?: SandboxCommandRunOptions): Promise<SandboxCommandResult>;
+    /** Spawn a long-lived command with a real duplex stdin/stdout. OPTIONAL —
+     *  implemented only by `makeLocalSandboxProvider` (the in-VM `child_process`
+     *  view). The vercel/e2b providers (server→sandbox) leave it undefined; an
+     *  ACP caller that finds it absent falls back to the JSONL transport. */
+    spawnDuplex?(cmd: string, opts?: SandboxSpawnDuplexOptions): SandboxDuplexProcess;
+    /** Launch a command in the background and return immediately with a
+     *  reconnectable handle (ADR-0028). The process survives the launching
+     *  connection dropping AND a `pauseProcess()`/resume cycle. OPTIONAL —
+     *  only process-resume providers (E2B) implement it; its presence (paired
+     *  with `pauseProcess`) is the native-pause capability flag. */
+    runBackground?(cmd: string, opts?: SandboxCommandRunOptions): Promise<SandboxBackgroundProcess>;
+    /** Re-attach to a background command by `pid` after a fresh
+     *  `Sandbox.connect` (the resume half of `runBackground`). OPTIONAL,
+     *  E2B-only. Throws if no process with that pid is running. */
+    connectProcess?(pid: number, opts?: Pick<SandboxCommandRunOptions, "onStdout" | "onStderr" | "timeoutMs">): Promise<SandboxBackgroundProcess>;
   };
   files: {
     write(path: string, content: string): Promise<void>;
@@ -65,12 +133,22 @@ export interface SandboxProvider {
    *  be omitted when the provider doesn't expose it; the server stores
    *  `null` for missing values rather than estimating. */
   snapshot?(): Promise<{ snapshotId: string; sizeBytes?: number }>;
-  /** Replace the live sandbox's egress policy in place. Vercel implements
-   *  it via `sandbox.update({ networkPolicy })` (2.x) so the server can
-   *  push a freshly resolved policy — with re-minted connector access
-   *  tokens — before each step instead of relying on the policy baked at
-   *  create. Providers whose enforcement lives inside the VM (E2B
-   *  iron-proxy) leave it undefined. */
+  /** Suspend the live VM in place and return a handle to resume it (ADR-0027).
+   *  Present ONLY on process-resume-capable providers (E2B via `sandbox.pause()`,
+   *  returning the sandbox id; resume is `Sandbox.connect(handle)`, which
+   *  auto-resumes the paused VM). Unlike `snapshot()` — which captures an FS
+   *  image, kills the origin, and re-runs the step from a fresh sandbox — a
+   *  process-resume pause FREEZES the live process (zero compute) and continues
+   *  it exactly where it blocked. The presence of this method IS the capability
+   *  flag: providers without native VM-suspend leave it undefined and fall back
+   *  to `snapshot()` + re-run. */
+  pauseProcess?(): Promise<{ resumeHandle: string }>;
+  /** Replace the live sandbox's egress policy in place — so the server can
+   *  push a freshly resolved policy (with re-minted connector access tokens)
+   *  before each step instead of relying on the policy baked at create.
+   *  Vercel implements it via `sandbox.update({ networkPolicy })` (2.x); E2B
+   *  via its native `sandbox.updateNetwork(...)`. Providers without a live
+   *  network-update primitive leave it undefined. */
   updateNetworkPolicy?(policy: SandboxNetworkPolicy): Promise<void>;
 }