@agent-compose/sdk 0.5.9 → 0.6.0

package/dist/runtimes/openai-desktop.js

@@ -1103,6 +1103,98 @@ function redactPattern(pattern, replacement = "[REDACTED]") {
     }
   };
 }
+// src/agent/pause-client.ts
+var isAbort = (signal) => Boolean(signal?.aborted);
+async function requestPauseAndAwait(opts, fetchImpl = fetch) {
+  const base = opts.baseUrl.replace(/\/+$/, "");
+  const headers = {
+    authorization: `Bearer ${opts.token}`,
+    "content-type": "application/json",
+    accept: "application/json"
+  };
+  const createRes = await fetchImpl(`${base}/api/v1/runs/${opts.runId}/pauses`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      reason: opts.reason,
+      ...opts.ttlMs !== undefined ? { ttlMs: opts.ttlMs } : {},
+      ...opts.options ? { options: opts.options } : {},
+      ...opts.action ? { action: opts.action } : {},
+      ...opts.correlationKey ? { correlationKey: opts.correlationKey } : {}
+    }),
+    ...opts.signal ? { signal: opts.signal } : {}
+  });
+  if (!createRes.ok) {
+    const text = await createRes.text().catch(() => "");
+    throw new Error(`pause create failed (${createRes.status}): ${text.slice(0, 300)}`);
+  }
+  const { pauseId } = await createRes.json();
+  const pollUrl = `${base}/api/v1/runs/${opts.runId}/pauses/${pauseId}`;
+  let backoffMs = 0;
+  for (;; ) {
+    if (isAbort(opts.signal))
+      throw new Error("pause wait aborted");
+    if (backoffMs > 0)
+      await new Promise((r) => setTimeout(r, backoffMs));
+    let res;
+    try {
+      res = await fetchImpl(pollUrl, { method: "GET", headers, ...opts.signal ? { signal: opts.signal } : {} });
+    } catch (err) {
+      if (isAbort(opts.signal))
+        throw err;
+      backoffMs = Math.min(8000, (backoffMs || 500) * 2);
+      continue;
+    }
+    if (!res.ok) {
+      backoffMs = Math.min(8000, (backoffMs || 500) * 2);
+      continue;
+    }
+    backoffMs = 0;
+    const body = await res.json();
+    if (body.status === "pending")
+      continue;
+    return { status: body.status, decision: body.resumePayload ?? null };
+  }
+}
+
+// src/processors/gate-pause.ts
+var DENY_ANSWERS = new Set(["deny", "no", "reject", "decline", "block"]);
+function answerText(decision) {
+  const raw = decision !== null && typeof decision === "object" && "decision" in decision ? decision.decision : decision;
+  return typeof raw === "string" ? raw.trim() : raw == null ? "" : JSON.stringify(raw);
+}
+function createGatePauseProcessor(opts) {
+  return {
+    name: "gate-pause",
+    async processToolCall(call, ctx) {
+      const approval = await opts.policy(call, ctx);
+      if (!approval)
+        return Verdict.continue(call);
+      const conn = opts.connection ?? {
+        baseUrl: process.env.AGENT_COMPOSE_URL ?? "",
+        token: process.env.AGENT_COMPOSE_RUN_TOKEN ?? "",
+        runId: process.env.RUN_ID ?? ""
+      };
+      if (!conn.baseUrl || !conn.token || !conn.runId)
+        return Verdict.continue(call);
+      const decision = await requestPauseAndAwait({
+        baseUrl: conn.baseUrl,
+        token: conn.token,
+        runId: conn.runId,
+        reason: approval.reason,
+        action: { tool: call.toolName, input: call.toolInput },
+        options: approval.options ?? [{ id: "approve", label: "Approve" }, { id: "deny", label: "Deny" }],
+        signal: ctx.abortSignal
+      });
+      const answer = answerText(decision.decision);
+      if (decision.status === "resolved" && !DENY_ANSWERS.has(answer.toLowerCase())) {
+        return Verdict.continue(call);
+      }
+      const why = decision.status === "resolved" ? `denied: ${answer}` : `${decision.status} with no approval`;
+      return Verdict.deny(`Human ${why}. Tool "${call.toolName}" was not run — adjust course or ask again.`);
+    }
+  };
+}
 // src/client.ts
 import { ofetch } from "ofetch";
 
@@ -2178,19 +2270,6 @@ Re-emit the COMPLETE corrected <response> JSON now: every required field present
       }
       lastResponseText = responseText;
       let status = parseAgentStatus(responseText);
-      if (opts.pause && pendingSteerPause === null) {
-        const localPause = opts.consumeLocalPauseRequest?.() ?? null;
-        if (localPause) {
-          pendingSteerPause = {
-            reason: localPause.reason,
-            correlationKey: null,
-            ...localPause.options && localPause.options.length > 0 ? { payload: { options: localPause.options } } : {},
-            at: Date.now()
-          };
-          blockerStreak = null;
-          continue;
-        }
-      }
       const rawResponse = opts.responseSchema ? parseAgentResponse(responseText) ?? parseRawJsonResponse(responseText) : null;
       const validateResponse = (target) => {
         const parsed = opts.responseSchema.safeParse(target);
@@ -2523,6 +2602,9 @@ class ClaudeRunner {
       else
         opts.signal.addEventListener("abort", onLoopAbort, { once: true });
     }
+    const systemPromptAppend = [this.config.claudeMdContent, this.options.agentManual].filter((s) => Boolean(s && s.trim())).join(`
+
+`);
     try {
       let emittedAssistantText = false;
       for await (const message of query({
@@ -2537,9 +2619,9 @@ class ClaudeRunner {
           effort: this.config.effort,
           cwd: this.options.cwd,
           abortController: queryAbort,
-          env: { ...process.env, ...this.config.env ?? {}, ...this.options.agentId ? { AGENT_COMPOSE_AGENT_ID: this.options.agentId } : {} },
+          env: { ...process.env, ...this.config.env ?? {} },
           pathToClaudeCodeExecutable: this.config.pathToClaudeCodeExecutable ?? process.env.CLAUDE_CODE_EXECUTABLE ?? DEFAULT_CLAUDE_PATH,
-          ...this.config.claudeMdContent ? { systemPrompt: { type: "preset", preset: "claude_code", append: this.config.claudeMdContent } } : {},
+          ...systemPromptAppend ? { systemPrompt: { type: "preset", preset: "claude_code", append: systemPromptAppend } } : {},
           skills: this.config.skills ?? "all",
           resume: opts.sessionId,
           mcpServers: this.config.mcpServers,
@@ -3051,7 +3133,7 @@ class CliAgentRunner {
       throw new Error("spawnAcpProcess called on a provider without commands.spawnDuplex");
     }
     const cmd = `${acp.command} ${acp.args.map(shellQuote).join(" ")}`.trim();
-    const agentEnv = { ...acp.env, ...this.options.agentId ? { AGENT_COMPOSE_AGENT_ID: this.options.agentId } : {} };
+    const agentEnv = { ...acp.env };
     const proc = spawnDuplex.call(this.sandbox.commands, cmd, {
       ...this.options.cwd ? { cwd: this.options.cwd } : {},
       ...Object.keys(agentEnv).length > 0 ? { envs: agentEnv } : {}
@@ -3401,13 +3483,64 @@ function withSnapshotRetry(p) {
   const snapshot = p.snapshot.bind(p);
   return { ...p, snapshot: () => withSandboxRetry(snapshot) };
 }
+function wrapE2bBackgroundProcess(handle) {
+  return {
+    pid: handle.pid,
+    async wait() {
+      try {
+        const r = await handle.wait();
+        return { exitCode: r.exitCode ?? 0, stdout: r.stdout, stderr: r.stderr };
+      } catch (e) {
+        const ce = e;
+        if (typeof ce.exitCode === "number") {
+          return {
+            exitCode: ce.exitCode,
+            stdout: typeof ce.stdout === "string" ? ce.stdout : "",
+            stderr: typeof ce.stderr === "string" ? ce.stderr : ""
+          };
+        }
+        throw e;
+      }
+    },
+    async kill() {
+      await handle.kill();
+    }
+  };
+}
 function makeE2bSandboxProvider(sb) {
+  const base = makeSandboxProvider(sb);
   return {
-    ...makeSandboxProvider(sb),
+    ...base,
+    commands: {
+      ...base.commands,
+      async runBackground(cmd, opts) {
+        const { sudo, onStdout, onStderr, ...rest } = opts ?? {};
+        const handle = await sb.commands.run(cmd, {
+          ...rest,
+          background: true,
+          ...sudo ? { user: "root" } : {},
+          ...onStdout ? { onStdout } : {},
+          ...onStderr ? { onStderr } : {}
+        });
+        return wrapE2bBackgroundProcess(handle);
+      },
+      async connectProcess(pid, opts) {
+        const handle = await sb.commands.connect(pid, {
+          ...opts?.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {},
+          ...opts?.onStdout ? { onStdout: opts.onStdout } : {},
+          ...opts?.onStderr ? { onStderr: opts.onStderr } : {}
+        });
+        return wrapE2bBackgroundProcess(handle);
+      }
+    },
     async snapshot() {
       const { snapshotId } = await sb.createSnapshot();
       return { snapshotId };
     },
+    async pauseProcess() {
+      await sb.pause();
+      return { resumeHandle: sb.sandboxId };
+    },
     async updateNetworkPolicy(policy) {
       await sb.updateNetwork(toE2bNetwork(policy));
     }
@@ -4478,25 +4611,11 @@ function parseStepResult(stdout, resultToken) {
   const message = baseMessage;
   return { ok: false, error: { kind, message } };
 }
-async function invokeStep(sandbox, request, opts) {
-  const resultToken = randomBytes2(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
-    })
-  };
+function makeStreamSplitters(opts, resultToken) {
   const resultSentinel = stepResultLinePrefix(resultToken);
   const pauseSentinel = stepPauseLinePrefix(resultToken);
   const isSentinel = (line) => line.startsWith(resultSentinel) || line.startsWith(pauseSentinel);
-  const makeLineSplitter = (sink, filterSentinel) => {
+  const make = (sink, filterSentinel) => {
     if (!sink)
       return { onChunk: undefined, flush: () => {} };
     let buf = "";
@@ -4524,29 +4643,19 @@ async function invokeStep(sandbox, request, opts) {
       }
     };
   };
-  const stdoutSplitter = makeLineSplitter(opts?.onStdout, true);
-  const stderrSplitter = makeLineSplitter(opts?.onStderr, false);
-  let result;
-  try {
-    result = await sandbox.commands.run(RUNNER_COMMAND, {
-      envs,
-      timeoutMs: 0,
-      ...stdoutSplitter.onChunk ? { onStdout: stdoutSplitter.onChunk } : {},
-      ...stderrSplitter.onChunk ? { onStderr: stderrSplitter.onChunk } : {}
-    });
-  } catch (e) {
-    if (e instanceof SandboxUnavailableError)
-      throw e;
-    const ce = e;
-    result = {
-      stdout: ce.stdout ?? ce.result?.stdout ?? "",
-      stderr: ce.stderr ?? ce.result?.stderr ?? (e instanceof Error ? e.message : String(e)),
-      exitCode: ce.exitCode ?? ce.result?.exitCode ?? 1
-    };
-  }
-  stdoutSplitter.flush();
-  stderrSplitter.flush();
-  const parsed = parseStepResult(result.stdout, resultToken);
+  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();
+    }
+  };
+}
+async function classifyRunnerOutcome(sandbox, output, resultToken) {
+  const parsed = parseStepResult(output.stdout, resultToken);
   if (parsed)
     return parsed;
   const fileRead = await sandbox.commands.run(`cat ${stepResultFilePath(resultToken)} 2>/dev/null || true`).catch(() => null);
@@ -4555,9 +4664,9 @@ async function invokeStep(sandbox, request, opts) {
     if (fromFile)
       return fromFile;
   }
-  if (result.exitCode !== 0) {
-    const stderrTail = result.stderr.trim().slice(-2000);
-    const stdoutTail = result.stdout.trim().slice(-2000);
+  if (output.exitCode !== 0) {
+    const stderrTail = output.stderr.trim().slice(-2000);
+    const stdoutTail = output.stdout.trim().slice(-2000);
     const details = [
       stderrTail ? `stderr:
 ${stderrTail}` : "",
@@ -4569,13 +4678,13 @@ ${stdoutTail}` : ""
       ok: false,
       error: {
         kind: "runner-exit",
-        message: `runner subprocess exited ${result.exitCode} before emitting a step result${details ? `
+        message: `runner subprocess exited ${output.exitCode} before emitting a step result${details ? `
 ${details}` : ""}`,
-        exitCode: result.exitCode
+        exitCode: output.exitCode
       }
     };
   }
-  const tail = result.stdout.trim().slice(-500);
+  const tail = output.stdout.trim().slice(-500);
   return {
     ok: false,
     error: {
@@ -4586,6 +4695,99 @@ ${tail}` : ""}`
     }
   };
 }
+async function prepareStepLaunch(sandbox, request, opts) {
+  const resultToken = randomBytes2(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 };
+}
+async function invokeStep(sandbox, request, opts) {
+  const { resultToken, envs } = await prepareStepLaunch(sandbox, request, opts);
+  const splitters = makeStreamSplitters(opts, resultToken);
+  let result;
+  try {
+    result = await sandbox.commands.run(RUNNER_COMMAND, {
+      envs,
+      timeoutMs: 0,
+      ...splitters.onStdout ? { onStdout: splitters.onStdout } : {},
+      ...splitters.onStderr ? { onStderr: splitters.onStderr } : {}
+    });
+  } catch (e) {
+    if (e instanceof SandboxUnavailableError)
+      throw e;
+    const ce = e;
+    result = {
+      stdout: ce.stdout ?? ce.result?.stdout ?? "",
+      stderr: ce.stderr ?? ce.result?.stderr ?? (e instanceof Error ? e.message : String(e)),
+      exitCode: ce.exitCode ?? ce.result?.exitCode ?? 1
+    };
+  }
+  splitters.flush();
+  return classifyRunnerOutcome(sandbox, result, resultToken);
+}
+async function launchStep(sandbox, request, opts) {
+  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(sandbox, result, resultToken);
+    }
+  };
+}
+async function reconnectStep(sandbox, resume, opts) {
+  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 = null;
+  try {
+    proc = await sandbox.commands.connectProcess(runnerPid, {
+      ...splitters.onStdout ? { onStdout: splitters.onStdout } : {},
+      ...splitters.onStderr ? { onStderr: splitters.onStderr } : {}
+    });
+  } catch (e) {
+    if (e instanceof SandboxUnavailableError)
+      throw e;
+  }
+  const attached = proc;
+  return {
+    runnerPid,
+    resultToken,
+    async wait() {
+      let output = { stdout: "", stderr: "", exitCode: 0 };
+      if (attached) {
+        try {
+          output = await attached.wait();
+        } catch (e) {
+          if (e instanceof SandboxUnavailableError)
+            throw e;
+        }
+      }
+      splitters.flush();
+      return classifyRunnerOutcome(sandbox, output, resultToken);
+    }
+  };
+}
 // src/step-invocation/server.ts
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 function writeSentinelLine(line) {
@@ -4692,41 +4894,6 @@ async function serveStep(handler) {
   await emitResult(token, payload);
   process.exit(exitCode);
 }
-// src/agent/local-pause-request.ts
-import { existsSync, mkdirSync as mkdirSync2, readFileSync as readFileSync2, renameSync, rmSync, writeFileSync as writeFileSync2 } from "node:fs";
-import { join as join3 } from "node:path";
-import { randomBytes as randomBytes3 } from "node:crypto";
-var UNSCOPED = "_unscoped";
-var requestsDir = () => join3(getStateDir(), "pause-requests");
-var markerPath = (agentId) => join3(requestsDir(), `${slug(agentId) || UNSCOPED}.json`);
-function slug(agentId) {
-  return (agentId ?? "").replace(/[^a-zA-Z0-9_.-]/g, "_");
-}
-function writeLocalPauseRequest(agentId, req) {
-  mkdirSync2(requestsDir(), { recursive: true });
-  const final = markerPath(agentId);
-  const tmp = `${final}.${randomBytes3(6).toString("hex")}.tmp`;
-  writeFileSync2(tmp, JSON.stringify(req), "utf8");
-  renameSync(tmp, final);
-}
-function consumeLocalPauseRequest(agentId) {
-  const paths = [...new Set([markerPath(agentId), markerPath(null)])];
-  for (const path of paths) {
-    if (!existsSync(path))
-      continue;
-    try {
-      const raw = JSON.parse(readFileSync2(path, "utf8"));
-      rmSync(path, { force: true });
-      if (raw && typeof raw === "object" && typeof raw.reason === "string" && raw.reason.trim().length > 0) {
-        const r = raw;
-        return { reason: r.reason.trim(), ...Array.isArray(r.options) && r.options.length > 0 ? { options: r.options } : {} };
-      }
-    } catch {
-      rmSync(path, { force: true });
-    }
-  }
-  return null;
-}
 // src/agent/run-agent.ts
 import { z as z12 } from "zod";
 import { randomUUID as randomUUID2 } from "node:crypto";
@@ -5055,7 +5222,7 @@ async function agent(opts) {
   const mode = opts.mode ?? "auto";
   try {
     return await agentLoop({
-      runtime: (runtimeOpts) => opts.runtime.create(opts.sandbox, runtimeOpts),
+      runtime: (runtimeOpts) => opts.runtime.create(opts.sandbox, { ...runtimeOpts, agentManual: buildAgentContextDoc(process.env) }),
       agentId,
       ...opts.label !== undefined ? { label: opts.label } : {},
       ...opts.budget?.turnsPerIteration !== undefined ? { turnsPerIteration: opts.budget.turnsPerIteration } : {},
@@ -5093,7 +5260,6 @@ async function agent(opts) {
       ...inbox ? { inbox } : {},
       mode,
       consumeSteerPending: () => consumeSteerPending(agentId),
-      consumeLocalPauseRequest: () => consumeLocalPauseRequest(agentId),
       ...steerPause ? { pause: steerPause } : {}
     });
   } finally {

package/dist/step-invocation/__tests__/background-invoker.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/step-invocation/index.d.ts

@@ -18,7 +18,8 @@
  * to test in isolation.
  */
 export { STEP_RESULT_PREFIX, STEP_PAUSE_PREFIX, STEP_ENV, RUNNER_BUNDLE_PATH, RUNNER_COMMAND, stepInputPath, requestContextPath, } from "./protocol.js";
-export { invokeStep, parseStepResult, buildStepEnvs } from "./invoker.js";
+export { invokeStep, launchStep, reconnectStep, parseStepResult, buildStepEnvs } from "./invoker.js";
+export type { RunningStep, InvokeStepOptions } from "./invoker.js";
 export { serveStep } from "./server.js";
 export type { StepHandler, ServeStepRequest, StepHandlerResult } from "./server.js";
 export { StepExecutionError } from "./types.js";

package/dist/step-invocation/invoker.d.ts

@@ -65,4 +65,40 @@ export interface InvokeStepOptions {
     onStdout?: (line: string) => void;
     onStderr?: (line: string) => void;
 }
+/** 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>>;
+}
 export declare function invokeStep<TOutput = unknown>(sandbox: SandboxProvider, request: StepRequest, opts?: InvokeStepOptions): Promise<StepResult<TOutput>>;
+/**
+ * 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 declare function launchStep<TOutput = unknown>(sandbox: SandboxProvider, request: StepRequest, opts?: InvokeStepOptions): Promise<RunningStep<TOutput>>;
+/**
+ * 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 declare function reconnectStep<TOutput = unknown>(sandbox: SandboxProvider, resume: {
+    runnerPid: number;
+    resultToken: string;
+    stepIndex: number;
+}, opts?: Pick<InvokeStepOptions, "onStdout" | "onStderr">): Promise<RunningStep<TOutput>>;

package/dist/types/runtime.d.ts

@@ -29,6 +29,13 @@ 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

package/dist/types/sandbox.d.ts

@@ -21,6 +21,29 @@ export interface SandboxCommandResult {
     stdout: string;
     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
@@ -78,6 +101,16 @@ export interface SandboxProvider {
          *  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>;
@@ -95,6 +128,18 @@ export interface SandboxProvider {
         snapshotId: string;
         sizeBytes?: number;
     }>;
+    /** 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-compose/sdk",
-  "version": "0.5.9",
+  "version": "0.6.0",
   "description": "Client library for agent-compose — define agents, runtimes, and workflows, and invoke them against an agent-compose server.",
   "license": "MIT",
   "repository": {

package/src/agent/agent-loop.ts

@@ -15,7 +15,6 @@ import { RequestContext } from "../request-context/request-context.js";
 import { PauseManager } from "../pause/manager.js";
 import { PauseSignal, isPauseSignal } from "../pause/pause-core.js";
 import { SteerDecisionSchema, type SteerDecision, type SteerPayload } from "./steer-control.js";
-import { type LocalPauseRequest } from "./local-pause-request.js";
 
 export const DEFAULT_CLAUDE_MODEL = "claude-fable-5";
 
@@ -154,13 +153,6 @@ export interface AgentLoopOpts<TResponse = unknown> {
    *  The boundary consumes it once per check, and only when no steer is
    *  already staged. */
   consumeSteerPending?: () => SteerPayload | null;
-  /** Take-once read of a local `agentc pause` request this agent dropped in the
-   *  state dir during its turn (the CLI writes it; see local-pause-request.ts).
-   *  Returns the request (reason + offered options) or null. The loop turns it
-   *  into a staged self-pause the next boundary takes — the same snapshot-release
-   *  path as `needs_input`, but triggered by an explicit `agentc pause` call so
-   *  it is honored regardless of `mode`. */
-  consumeLocalPauseRequest?: () => LocalPauseRequest | null;
   /** PR 7: `auto` (autonomous, default) or `hitl` (can be steer-paused). The
    *  boundary is inert unless `hitl`. */
   mode?: "auto" | "hitl";
@@ -462,29 +454,10 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
 
     let status = parseAgentStatus(responseText);
 
-    // `agentc pause` — the agent shelled out to the CLI during this turn, which
-    // dropped a durable pause-request marker in the state dir. Honor it like a
-    // self-pause: stage the pause the NEXT boundary takes, carrying the agent's
-    // question as the reason and any offered choices as the pause payload (the
-    // dashboard renders them as buttons). Checked BEFORE the settle / needs_input
-    // paths and independent of the <status> block — the common case is an agent
-    // that called the tool and ended its turn with no status at all, which would
-    // otherwise fall through to the empty-output re-prompt below. UNGATED by
-    // `mode`: an explicit `agentc pause` is a deliberate ask, not the `needs_input`
-    // heuristic that only `hitl` agents may trigger.
-    if (opts.pause && pendingSteerPause === null) {
-      const localPause = opts.consumeLocalPauseRequest?.() ?? null;
-      if (localPause) {
-        pendingSteerPause = {
-          reason:         localPause.reason,
-          correlationKey: null,
-          ...(localPause.options && localPause.options.length > 0 ? { payload: { options: localPause.options } } : {}),
-          at:             Date.now(),
-        };
-        blockerStreak = null;   // an explicit ask is not a stuck loop
-        continue;               // pause fires at the next boundary
-      }
-    }
+    // ADR-0028 — `agentc pause` is no longer a marker the loop consumes here. It
+    // is a server operation: the CLI blocks on the pause API and the run is
+    // frozen in place by the step activity, with no loop involvement. The steer
+    // (human-driven) and `needs_input` (self-pause) paths below are unaffected.
 
     // Inline safeParse (instead of letting parseAgentResponse validate)
     // so a schema failure surfaces via lastResponseValidationError on