@agent-compose/sdk 0.5.9 → 0.7.0

package/dist/runtimes/opencode.d.ts

@@ -0,0 +1,25 @@
+/**
+ * OpenCode CLI runtime — drives sst's `opencode` agentic CLI inside the sandbox.
+ * OpenCode speaks ACP natively (`opencode acp`, protocolVersion 1 — verified
+ * live on E2B), so the runner drives it over ACP; the JSONL members below are
+ * only the version-mismatch fallback (vestigial for a v1 agent).
+ *
+ * Auth + model via OpenRouter: set OPENROUTER_API_KEY (a factory/workflow
+ * secret) and use a model id like `openrouter/z-ai/glm-5.2`. The runtime
+ * installs the `opencode-ai` CLI on demand; pair with
+ * `snapshots: { bootFrom: "reuse" }` to install once and boot from the capture.
+ *
+ * Verified live on E2B (2026-06-30): `npm i -g opencode-ai` (v1.17.12);
+ * `opencode run --model openrouter/z-ai/glm-5.2` drove a GLM-5.2 turn through
+ * OpenRouter; `opencode acp` answered the ACP `initialize` handshake with
+ * protocolVersion 1.
+ */
+import { type CliAgentSpec } from "./_cli-agent.js";
+export declare const opencodeSpec: CliAgentSpec;
+export interface OpencodeRuntimeConfig {
+    /** OpenRouter-prefixed model id (default `openrouter/z-ai/glm-5.2`). */
+    model?: string;
+}
+export declare function createOpencodeRuntime(config?: OpencodeRuntimeConfig): import("../index.js").AgentRuntime<import("../index.js").SandboxProvider>;
+declare const _default: import("../index.js").AgentRuntime<import("../index.js").SandboxProvider>;
+export default _default;

package/dist/runtimes/vercel.js

@@ -717,7 +717,17 @@ async function corePause(req, coord, kind = "custom") {
 
 // src/utils/errors.ts
 function formatError(err) {
-  return err instanceof Error ? err.message : String(err);
+  if (!(err instanceof Error))
+    return String(err);
+  const parts = [err.message];
+  const seen = new Set([err]);
+  let cause = err.cause;
+  while (cause != null && !seen.has(cause)) {
+    seen.add(cause);
+    parts.push(cause instanceof Error ? cause.message : String(cause));
+    cause = cause instanceof Error ? cause.cause : undefined;
+  }
+  return parts.join(": ");
 }
 
 // src/runtimes/vercel.ts

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

@@ -64,5 +64,54 @@ export interface InvokeStepOptions {
      *  the caller's job; the activity batches and inserts at step completion. */
     onStdout?: (line: string) => void;
     onStderr?: (line: string) => void;
+    /** Called when the LIVE output stream fails mid-run (e.g. E2B's connect-web
+     *  transport throws `received unsupported compressed output` on a large
+     *  compressed frame) and the invoker falls back to recovering the result +
+     *  full logs from the durable token-keyed files. The run is NOT failed — this
+     *  is the hook to emit a structured alert so the degradation is visible/paged.
+     *  Best-effort: keep it cheap and non-throwing. */
+    onStreamDegraded?: (info: {
+        error: unknown;
+        runnerPid: number;
+        resultToken: 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"> & {
+    signal?: AbortSignal;
+}): Promise<RunningStep<TOutput>>;

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

@@ -60,3 +60,11 @@ export declare function requestContextPath(stepIndex: number): string;
  *  drop the tail of a heavy stdout stream — the invoker falls back to
  *  reading this file when no sentinel is found on stdout. */
 export declare function stepResultFilePath(token: string): string;
+/** Sandbox-side path where the runner's stdout is tee'd as a durable LOG file,
+ *  keyed by the per-invocation token. The live output rides E2B's connect-web
+ *  command stream, which THROWS on a compressed large frame (gRPC-web cannot
+ *  decode message compression) and kills the feed mid-run. This file, read back
+ *  over the envd HTTP file transport (compression-immune), lets the invoker
+ *  recover the FULL logs after such a fault instead of losing the tail — the
+ *  log-side analogue of `stepResultFilePath` for the result. */
+export declare function stepLogFilePath(token: string): string;

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,9 +101,28 @@ 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>;
+        /** Read a file's text content over the provider's FILE transport. On E2B this
+         *  is the envd HTTP API (`Sandbox.files.read`), a DIFFERENT transport from
+         *  `commands` — so a large readback is immune to the connect-web gRPC
+         *  message-compression that can abort `commands.run` output on a big frame
+         *  ("received unsupported compressed output"). This is what lets `launchStep`
+         *  recover the full logs + result after a live-stream fault. OPTIONAL —
+         *  implemented where durable file-readback is needed (E2B, local); providers
+         *  that never drive the recovery path (Vercel — foreground only) may omit it. */
+        read?(path: string): Promise<string>;
     };
     kill(): Promise<void>;
     /** Capture the running sandbox's state as a reusable snapshot. Vercel and E2B
@@ -95,6 +137,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/dist/types/workflow.d.ts

@@ -90,6 +90,12 @@ export interface WorkflowDefinition<TOutput = unknown, TInput extends Record<str
     /** Same as `input`, for the workflow's return value. Captured into
      *  `outputSchema` metadata and rendered in the IO panel. */
     output?: z.ZodType<TOutput>;
+    /**
+     * @deprecated Legacy run-form. Prefer step-form — the
+     * `.step(defineStep(...))` builder — for per-step durability/replay and
+     * working pause. A run-form body compiles to one opaque step
+     * (`compileRunForm`), so any failure/resume re-runs the whole body.
+     */
     run: WorkflowFn<TOutput, TInput>;
     /**
      * All snapshot config — boot source plus capture mode.
@@ -210,6 +216,12 @@ export interface WorkflowDefinition<TOutput = unknown, TInput extends Record<str
  * stores the step plan; runner subprocesses execute one step at a time
  * via the StepInvocation seam.
  */
+/**
+ * @deprecated Run-form is legacy. Use the step-form overload —
+ * `defineWorkflow({ id, input, output }).step(defineStep(...)).build()` — for
+ * durable, replayable steps and working pause. Run-form compiles to a single
+ * opaque step (`compileRunForm`); there is no per-step replay.
+ */
 export declare function defineWorkflow<TOutput = unknown, TInput extends Record<string, unknown> = Record<string, unknown>>(def: WorkflowDefinition<TOutput, TInput>): Workflow<TInput, TOutput>;
 export declare function defineWorkflow<TInput, TOutput>(def: StepWorkflowDefinition<TInput, TOutput>): import("../workflow-steps/workflow.js").WorkflowBuilder<TInput, TInput>;
 /** Observability-only lifecycle hooks — passed to the workflow engine, not workflow authors. */

package/dist/utils/errors.d.ts

@@ -1,2 +1,10 @@
-/** Convert any thrown value to a string message. */
+/** Convert any thrown value to a string message, INCLUDING its `.cause` chain.
+ *
+ *  Many wrapped errors carry the real reason on `.cause` and only a generic
+ *  summary on `.message` — the Temporal SDK's "Failed to start Workflow" is the
+ *  canonical example (its `.cause` is the actual gRPC rejection, e.g. "search
+ *  attribute X is not defined"). Returning `.message` alone swallowed that, so
+ *  failures surfaced as opaque one-liners. Walk the chain and join the messages
+ *  so the root cause is always visible. Cycle-guarded against self-referential
+ *  `cause` links. */
 export declare function formatError(err: unknown): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-compose/sdk",
-  "version": "0.5.9",
+  "version": "0.7.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-context.ts

@@ -71,29 +71,36 @@ Names like \`note.created\` / \`brief.posted\` surface in the Workbench;
 
 ## Writing workflow / agent code — the SDK
 
-\`@agent-compose/sdk\` is installed in \`/workspace\` — import it from any script
-you write there:
+\`@agent-compose/sdk\` is installed in \`/workspace\`. **To author a workflow,
+ALWAYS run \`/ac:generate-workflow\`** (and \`/ac:generate-agent\` for an agent
+step) instead of writing source from memory — the skill scaffolds the correct,
+current shape. Then \`agentc register <file.ts>\` (or \`/ac:register\`).
 
-    import { defineWorkflow, agent, AgentComposeClient } from "@agent-compose/sdk";
+The skill writes **step-form** (a builder of discrete, durable \`.step()\`s).
+Never write the legacy run-form (\`defineWorkflow({ run(ctx, sandbox) { … } })\`):
+it is one opaque step, so any failure or resume re-runs the whole body — and
+**pause does not work in run-form**.
 
-Use \`/ac:generate-workflow\` / \`/ac:generate-agent\` to scaffold, then
-\`agentc register <file.ts>\` (or \`/ac:register\`).
+## Pausing to ask the human
 
-## Pausing to ask the human — \`agentc pause\`
-
-When you can't or shouldn't proceed without a human, run \`agentc pause\`, then
-**END YOUR TURN**:
+To ask a human and get an answer back, use the **\`AskUserQuestion\`** tool if
+you have it; otherwise run **\`agentc pause\`**:
 
     agentc pause --reason "Notion returned 401 — connect Notion to continue" \\
                  --option retry --option skip
 
-\`agentc pause\` does NOT block and does NOT print the answer. It records your
-question and returns immediately. The moment you end your turn, the run pauses
-(your sandbox is snapshotted and compute stops while the human decides) and the
-human's answer is delivered to you as your **next message** — you pick up
-exactly where you left off, with the answer in hand. So: ask, end your turn,
-and wait. Do NOT keep working, do NOT call more tools, and do NOT mark the task
-complete after pausing.
+**Both BLOCK and hand you the answer inline.** While you wait, the run is
+suspended — your sandbox is frozen and compute stops, so a pause is free while
+the human decides. When they answer, the call RETURNS with their decision: the
+\`AskUserQuestion\` tool result, or \`agentc pause\`'s output
+(\`▶ Resumed. The human answered: …\`), carries it.
+
+**Then USE that answer to finish your work — do NOT end your turn.** This is NOT
+fire-and-forget, and the answer does NOT arrive in a later message: it comes
+back right where you called it, on the SAME turn. The shape is: ask → the call
+blocks → it returns the human's answer → you act on it and produce your result.
+Never end your turn before the call returns, never guess an answer, and never
+proceed without one.
 
 Reach for it the moment you hit — or foresee — any of these:
 - **A wall only a human can clear:** a 401/403, a missing credential, an

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";
@@ -172,9 +164,16 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
   const logLabel           = opts.label ?? "[Agent Loop]";
   const startedAt          = Date.now();
   // No budget ⇒ no turn cap: the harness runtime (Claude Code) decides when it's
-  // done. A numeric budget is an explicit caller choice, not a default we impose.
+  // done in one unbounded session. A numeric budget is an explicit caller choice.
+  // Default to a SMALL allowance (not 1) so the loop can RE-PROMPT for the closing
+  // <status>/<response> when a session ends EARLY — e.g. a human pause (agentc
+  // pause / AskUserQuestion) freezes the VM mid-tool and the resumed session can
+  // drop its final turn after doing the work. The re-prompt (PROTOCOL_SUFFIX)
+  // only fires when an iteration produced no exit_signal, so a clean run still
+  // settles in ONE iteration — these extra iterations are a recovery path, not
+  // the norm.
   const turnsPerIteration  = opts.turnsPerIteration;
-  const maxIterations      = opts.maxIterations ?? (turnsPerIteration === undefined ? 1 : 8);
+  const maxIterations      = opts.maxIterations ?? (turnsPerIteration === undefined ? 3 : 8);
   // A responseSchema is a CONTRACT, not a hope: when the agent's <response> fails
   // validation, the loop re-prompts with the exact errors until it conforms —
   // without consuming the caller's iteration budget. The backstop below only
@@ -462,29 +461,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

package/src/agent/pause-client.ts

@@ -0,0 +1,108 @@
+/**
+ * In-sandbox pause client (ADR-0028). The single way an agent pauses its OWN
+ * run: `agentc pause` and the gate-pause processor both call
+ * `requestPauseAndAwait`, which drives the server pause API and blocks until a
+ * human resolves it.
+ *
+ * Create-then-poll, NOT a held connection:
+ *   1. POST /pauses creates the pending row. The server wakes the step
+ *      activity, which freezes the live VM in place (E2B native suspend). The
+ *      poll loop below is part of that frozen process — between polls it costs
+ *      ZERO compute while the run is parked.
+ *   2. GET /pauses/:id long-polls (each request a bounded ~5s server-side
+ *      LISTEN race) until the row is terminal, then returns the human's answer.
+ *
+ * There is no marker file and no exception threaded through workflow code — the
+ * pause is a server operation, so nothing a `try/catch` can swallow.
+ */
+
+export interface PauseDecision {
+  status:   "resolved" | "expired" | "cancelled";
+  /** The human's answer (present on `resolved`). Caller-defined shape; the
+   *  dashboard sends `{ decision: string }`. Null on expiry/cancel. */
+  decision: unknown;
+}
+
+export interface RequestPauseOptions {
+  /** `AGENT_COMPOSE_URL` — the server base URL injected into the sandbox. */
+  baseUrl: string;
+  /** `AGENT_COMPOSE_RUN_TOKEN` — the run credential the agent already carries. */
+  token:   string;
+  /** `RUN_ID`. */
+  runId:   string;
+  /** Human-readable reason shown on the pause feed / approval UI. */
+  reason:  string;
+  /** Optional pause TTL; the workflow auto-expires the pause after this. */
+  ttlMs?:  number;
+  /** Optional decision options the human picks from (e.g. approve / deny). */
+  options?: Array<{ id: string; label: string }>;
+  /** The action under review (e.g. the tool call), surfaced to the human. */
+  action?: Record<string, unknown>;
+  /** Optional second-key resume route. */
+  correlationKey?: string;
+  /** Abort the wait (the agent loop's signal). */
+  signal?: AbortSignal;
+}
+
+/** Inject a custom fetch (tests). Defaults to global fetch. */
+type FetchFn = typeof fetch;
+
+const isAbort = (signal: AbortSignal | undefined) => Boolean(signal?.aborted);
+
+export async function requestPauseAndAwait(
+  opts: RequestPauseOptions,
+  fetchImpl: FetchFn = fetch,
+): Promise<PauseDecision> {
+  const base = opts.baseUrl.replace(/\/+$/, "");
+  const headers = {
+    authorization:  `Bearer ${opts.token}`,
+    "content-type": "application/json",
+    accept:         "application/json",
+  } as const;
+
+  // 1. Create the pending pause. The server wakes the step activity → the live
+  //    VM suspends in place. 202 → { pauseId }.
+  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() as { pauseId: string };
+
+  // 2. Poll until terminal. Each GET is a bounded server long-poll; the loop
+  //    reissues. A transient error backs off and retries — the durable row is
+  //    the source of truth, so a dropped poll never loses the decision.
+  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: Awaited<ReturnType<FetchFn>>;
+    try {
+      res = await fetchImpl(pollUrl, { method: "GET", headers, ...(opts.signal ? { signal: opts.signal } : {}) });
+    } catch (err) {
+      if (isAbort(opts.signal)) throw err;
+      backoffMs = Math.min(8_000, (backoffMs || 500) * 2);
+      continue;
+    }
+    if (!res.ok) {
+      backoffMs = Math.min(8_000, (backoffMs || 500) * 2);
+      continue;
+    }
+    backoffMs = 0;
+    const body = await res.json() as { status: string; resumePayload?: unknown };
+    if (body.status === "pending") continue;
+    return { status: body.status as PauseDecision["status"], decision: body.resumePayload ?? null };
+  }
+}

package/src/agent/run-agent.ts

@@ -14,15 +14,15 @@ import { z } from "zod";
 import { randomUUID } from "node:crypto";
 import { getActiveStep, nextAgentCallInActiveStep } from "../active-step.js";
 import { corePause, type PauseRequest } from "../pause/pause-core.js";
+import { createAskHumanProcessor } from "../processors/ask-human.js";
 import { agentLoop } from "./agent-loop.js";
 import { consumeSteerPending, runControlPoller } from "./steer-control.js";
-import { consumeLocalPauseRequest } from "./local-pause-request.js";
 import type { AgentLifecycleEvent, AgentLoopResult } from "./agent-loop.js";
 import { AsyncQueue } from "./async-queue.js";
 import type { AgentMessage, AgentStatus } from "../types/protocol.js";
 import type { AgentRuntime, RuntimeOptions } from "../types/runtime.js";
 import type { SandboxProvider } from "../types/sandbox.js";
-import { writeAgentContext } from "./agent-context.js";
+import { writeAgentContext, buildAgentContextDoc } from "./agent-context.js";
 import type { AgentBudget } from "../types/workflow.js";
 import type { Processor } from "../processors/processor.js";
 import { RequestContext } from "../request-context/request-context.js";
@@ -331,10 +331,22 @@ export async function agent<T = unknown>(opts: AgentOpts<T>): Promise<AgentLoopR
   // (the boundary self-pause trigger + the prompt instruction above). Human
   // steering works regardless — see the ungated control poller.
   const mode = opts.mode ?? "auto";
+  // Ask-a-human is TOOLS-driven, not a separate mode: the ask-human processor is
+  // a chain default that maps the `AskUserQuestion` tool to a server pause (the
+  // run freezes, the human answers, the answer returns as the tool result). It's
+  // a no-op for any agent that doesn't have / call `AskUserQuestion`, so granting
+  // that tool to an agent IS its "can ask a human" switch — withhold it and the
+  // agent simply can't (it reports blockers up instead).
+  const processors = [createAskHumanProcessor(), ...(opts.processors ?? [])];
 
   try {
   return await agentLoop({
-    runtime: (runtimeOpts: RuntimeOptions) => opts.runtime.create(opts.sandbox, runtimeOpts),
+    // Inject the platform manual into every runtime create() so a runtime that
+    // supports a system-prompt append (claude) carries it IN CONTEXT — not
+    // dependent on the agent choosing to `cat` AGENTS.md (which the SDK doesn't
+    // auto-load) or on writeAgentContext succeeding (it EACCES's on a read-only
+    // /workspace). buildAgentContextDoc is the same content writeAgentContext writes.
+    runtime: (runtimeOpts: RuntimeOptions) => 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 } : {}),
@@ -357,7 +369,7 @@ export async function agent<T = unknown>(opts: AgentOpts<T>): Promise<AgentLoopR
     ...(opts.events ? { onAgentLifecycleEvent: (event: AgentLifecycleEvent) => { void opts.events?.emit(event); } } : {}),
     ...(opts.onAgentEvent ? { onAgentEvent: opts.onAgentEvent } : {}),
     ...(opts.onIteration  ? { onIteration:  opts.onIteration  } : {}),
-    ...(opts.processors?.length ? { processors: opts.processors } : {}),
+    ...(processors.length ? { processors } : {}),
     requestContext: opts.requestContext ?? RequestContext.fromReserved({
       teamId: "", runId: "", workflowId: "",
       factoryId: null, apiKeyScopes: [], parentRunId: null,
@@ -366,9 +378,6 @@ export async function agent<T = unknown>(opts: AgentOpts<T>): Promise<AgentLoopR
     // PR 7 steer-pause wiring.
     mode,
     consumeSteerPending: () => consumeSteerPending(agentId),
-    // `agentc pause` self-pause: the loop reads the marker this agent's CLI
-    // dropped in the state dir and stages a snapshot-release pause from it.
-    consumeLocalPauseRequest: () => consumeLocalPauseRequest(agentId),
     ...(steerPause ? { pause: steerPause } : {}),
   });
   } finally {

package/src/index.ts

@@ -76,12 +76,18 @@ export {
   humanApproval,
   requireScope,
   redactPattern,
+  createGatePauseProcessor,
+  createAskHumanProcessor,
+  ASK_USER_QUESTION_TOOL,
 } from "./processors/index.js";
 export type {
   Processor,
   ProcessorContext,
   ProcessorVerdict,
   ToolCall,
+  GatePausePolicy,
+  GatePauseApproval,
+  GatePauseConnection,
 } from "./processors/index.js";
 
 // Protocol types (agent-loop input/output shapes)
@@ -170,6 +176,17 @@ export { default as codexRuntime } from "./runtimes/codex.js";
 export { createAmpRuntime } from "./runtimes/amp.js";
 export type { AmpRuntimeConfig } from "./runtimes/amp.js";
 export { default as ampRuntime } from "./runtimes/amp.js";
+export { createOpencodeRuntime, opencodeSpec } from "./runtimes/opencode.js";
+export type { OpencodeRuntimeConfig } from "./runtimes/opencode.js";
+export { default as opencodeRuntime } from "./runtimes/opencode.js";
+
+export { createCursorRuntime, cursorSpec } from "./runtimes/cursor.js";
+export type { CursorRuntimeConfig } from "./runtimes/cursor.js";
+export { default as cursorRuntime } from "./runtimes/cursor.js";
+
+export { createDroidRuntime, droidSpec } from "./runtimes/droid.js";
+export type { DroidRuntimeConfig } from "./runtimes/droid.js";
+export { default as droidRuntime } from "./runtimes/droid.js";
 
 // Built-in coding tools for Vercel AI SDK runtime.
 export { bashTool, codingTools, editTool, readTool, writeTool } from "./tools/index.js";
@@ -232,6 +249,8 @@ export type {
 // `invokeStep` (server) and `serveStep` (runner).
 export {
   invokeStep,
+  launchStep,
+  reconnectStep,
   serveStep,
   parseStepResult,
   buildStepEnvs,
@@ -256,10 +275,12 @@ export {
 export type { PauseErrorCode } from "./pause/errors.js";
 export type { PauseRequest } from "./pause/pause-core.js";
 export type { WaitForEventRequest } from "./pause/wrappers.js";
-// `agentc pause` writes a local pause-request marker the agent loop consumes
-// (the snapshot-release bridge); the CLI imports the writer.
-export { writeLocalPauseRequest, consumeLocalPauseRequest } from "./agent/local-pause-request.js";
-export type { LocalPauseRequest, PauseOption } from "./agent/local-pause-request.js";
+// ADR-0028 — the in-sandbox pause client. `agentc pause` and the gate-pause
+// processor both pause their OWN run through the server pause API and block
+// until a human answers (create-then-poll; the VM suspends in place while
+// parked). No marker, no exception threaded through workflow code.
+export { requestPauseAndAwait } from "./agent/pause-client.js";
+export type { PauseDecision, RequestPauseOptions } from "./agent/pause-client.js";
 export type {
   StepRequest,
   StepResult,
@@ -268,6 +289,8 @@ export type {
   StepHandler,
   StepHandlerResult,
   ServeStepRequest,
+  RunningStep,
+  InvokeStepOptions,
 } from "./step-invocation/index.js";
 
 // Agent loop — for workflows that embed an LLM agent in their run() body.