@agent-compose/sdk 0.5.0 → 0.5.2

package/src/sandbox.ts

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

package/src/sse.ts

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

package/src/step-invocation/index.ts

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

package/src/step-invocation/invoker.ts

@@ -22,12 +22,50 @@
  */
 
 import { randomBytes } from "node:crypto";
+import { z } from "zod";
 import type { SandboxProvider } from "../types/sandbox.js";
-import { RUNNER_COMMAND, STEP_ENV, stepResultLinePrefix, requestContextPath, stepInputPath } from "./protocol.js";
+import { RUNNER_COMMAND, STEP_ENV, stepResultLinePrefix, stepPauseLinePrefix, requestContextPath, stepInputPath } from "./protocol.js";
+import { StepPauseRequestSchema } from "./types.js";
 import type { StepRequest, StepResult } from "./types.js";
+import type { StepObservability } from "../workflow-steps/observability.js";
 
 export { RUNNER_COMMAND } from "./protocol.js";
 
+const StepObservabilitySchema = z.object({
+  metadata: z.record(z.string(), z.unknown()).optional(),
+  events: z.array(z.unknown()).optional(),
+  subSteps: z.array(z.object({
+    name: z.string(),
+    startedAt: z.number(),
+    durationMs: z.number(),
+    status: z.enum(["completed", "failed"]),
+    error: z.string().optional(),
+  })).optional(),
+}).passthrough();
+
+const StepResultEnvelopeSchema = z.discriminatedUnion("ok", [
+  z.object({
+    ok: z.literal(true),
+    output: z.unknown().optional(),
+    observability: StepObservabilitySchema.optional(),
+  }),
+  z.object({
+    ok: z.literal(false),
+    kind: z.enum(["protocol", "user-step"]),
+    error: z.string().optional(),
+  }),
+]);
+
+/** Wire schema for the pause sentinel — what the runner emits on stdout
+ *  when user code calls `ctx.pause(...)`. The inner `pauseRequest` schema
+ *  is the canonical `StepPauseRequestSchema` from types.ts so the runtime
+ *  type (`StepPauseRequest`) and the parsed shape can't drift. */
+const StepPauseEnvelopeSchema = z.object({
+  pauseId:      z.string().min(1),
+  pauseRequest: StepPauseRequestSchema,
+  observability: StepObservabilitySchema.optional(),
+});
+
 /** Build the env map for one step invocation. Pure function; tests use it
  *  to assert the env shape (and to assert that no server-held credentials
  *  leak in) without spawning a sandbox. */
@@ -35,6 +73,7 @@ export function buildStepEnvs(args: {
   runId:       string;
   stepIndex:   number;
   resultToken: string;
+  isResume?:   boolean;
 }): Record<string, string> {
   return {
     [STEP_ENV.RUN_ID]:               args.runId,
@@ -43,6 +82,7 @@ export function buildStepEnvs(args: {
     [STEP_ENV.STEP_INPUT_PATH]:      stepInputPath(args.stepIndex),
     [STEP_ENV.REQUEST_CONTEXT_PATH]: requestContextPath(args.stepIndex),
     [STEP_ENV.STEP_RESULT_TOKEN]:    args.resultToken,
+    [STEP_ENV.STEP_RESUME]:          args.isResume ? "1" : "0",
   };
 }
 
@@ -59,35 +99,61 @@ export function parseStepResult<TOutput = unknown>(
   stdout:      string,
   resultToken: string,
 ): StepResult<TOutput> | null {
-  const prefix = stepResultLinePrefix(resultToken);
-  const line = stdout.split(/\r?\n/).find((l) => l.startsWith(prefix));
-  if (!line) return null;
-  let parsed: {
-    ok:             boolean;
-    output?:        unknown;
-    kind?:          string;
-    error?:         string;
-    observability?: import("../workflow-steps/observability.js").StepObservability;
-  };
+  // Pause sentinel takes precedence: a step that called `ctx.pause(...)`
+  // exits without ever emitting a result, but if the runner did emit a
+  // partial / stale result in a prior buffer chunk, the pause sentinel
+  // is the load-bearing signal. Scan one pass, dispatch by prefix.
+  const resultPrefix = stepResultLinePrefix(resultToken);
+  const pausePrefix  = stepPauseLinePrefix(resultToken);
+  let resultLine: string | undefined;
+  let pauseLine:  string | undefined;
+  for (const line of stdout.split(/\r?\n/)) {
+    if (!pauseLine  && line.startsWith(pausePrefix))  pauseLine  = line;
+    if (!resultLine && line.startsWith(resultPrefix)) resultLine = line;
+    if (pauseLine && resultLine) break;
+  }
+
+  if (pauseLine) {
+    try {
+      const raw = JSON.parse(pauseLine.slice(pausePrefix.length));
+      const parsed = StepPauseEnvelopeSchema.safeParse(raw);
+      if (!parsed.success) {
+        return { ok: false, error: { kind: "protocol", message: `step pause schema validation failed: ${parsed.error.message}` } };
+      }
+      return {
+        ok:           "paused",
+        pauseId:      parsed.data.pauseId,
+        pauseRequest: parsed.data.pauseRequest,
+        ...(parsed.data.observability ? { observability: parsed.data.observability as StepObservability } : {}),
+      };
+    } catch {
+      return { ok: false, error: { kind: "protocol", message: "step pause JSON parse failed" } };
+    }
+  }
+
+  if (!resultLine) return null;
+  let parsed: z.infer<typeof StepResultEnvelopeSchema>;
   try {
-    parsed = JSON.parse(line.slice(prefix.length));
+    const raw = JSON.parse(resultLine.slice(resultPrefix.length));
+    const result = StepResultEnvelopeSchema.safeParse(raw);
+    if (!result.success) {
+      const kind = raw && typeof raw === "object" && typeof (raw as { kind?: unknown }).kind === "string"
+        ? ` (kind=${(raw as { kind: string }).kind})`
+        : "";
+      return { ok: false, error: { kind: "protocol", message: `step result schema validation failed${kind}: ${result.error.message}` } };
+    }
+    parsed = result.data;
   } catch {
     return { ok: false, error: { kind: "protocol", message: "step result JSON parse failed" } };
   }
   if (parsed.ok) {
     return parsed.observability
-      ? { ok: true, output: parsed.output as TOutput, observability: parsed.observability }
+      ? { ok: true, output: parsed.output as TOutput, observability: parsed.observability as StepObservability }
       : { ok: true, output: parsed.output as TOutput };
   }
-  const kind: "protocol" | "user-step" = parsed.kind === "user-step" ? "user-step" : "protocol";
+  const kind = parsed.kind;
   const baseMessage = parsed.error ?? "step body failed without a message";
-  // An unknown kind value means the runner emitted something this invoker
-  // doesn't recognise — most likely a version-skew deploy. Preserve the
-  // original kind string in the message so operators see the actual value
-  // instead of silently re-classifying it as "protocol".
-  const message = parsed.kind && parsed.kind !== "user-step" && parsed.kind !== "protocol"
-    ? `(unknown kind "${parsed.kind}") ${baseMessage}`
-    : baseMessage;
+  const message = baseMessage;
   return { ok: false, error: { kind, message } };
 }
 
@@ -101,6 +167,8 @@ export function parseStepResult<TOutput = unknown>(
  */
 export interface InvokeStepOptions {
   envs?: Record<string, string>;
+  /** True when re-entering a step after resolving or expiring a pause. */
+  isResume?: boolean;
   /** Live stdout / stderr from the runner subprocess, line-by-line. Called
    *  from inside `sandbox.commands.run` as chunks arrive. The sentinel line
    *  carrying the protocol result token is filtered out before delivery so
@@ -131,17 +199,21 @@ export async function invokeStep<TOutput = unknown>(
       runId:       request.runId,
       stepIndex:   request.stepIndex,
       resultToken,
+      isResume:    opts?.isResume,
     }),
   };
 
   // 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.
-  // The sentinel line (carrying `resultToken`) is filtered out so callers
-  // never see protocol bytes in user-log capture. The prefix is built
-  // from `stepResultLinePrefix` — the same helper `parseStepResult` uses,
-  // so the filter and the parser can't drift.
-  const sentinelPrefix = stepResultLinePrefix(resultToken);
+  // 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.
+  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) => {
     if (!sink) return { onChunk: undefined, flush: () => {} };
     let buf = "";
@@ -152,7 +224,7 @@ export async function invokeStep<TOutput = unknown>(
         while ((nl = buf.indexOf("\n")) !== -1) {
           const line = buf.slice(0, nl);
           buf = buf.slice(nl + 1);
-          if (filterSentinel && line.startsWith(sentinelPrefix)) continue;
+          if (filterSentinel && isSentinel(line)) continue;
           sink(line);
         }
       },
@@ -164,7 +236,7 @@ export async function invokeStep<TOutput = unknown>(
         if (buf.length === 0) return;
         const line = buf;
         buf = "";
-        if (filterSentinel && line.startsWith(sentinelPrefix)) return;
+        if (filterSentinel && isSentinel(line)) return;
         sink(line);
       },
     };
@@ -188,11 +260,17 @@ export async function invokeStep<TOutput = unknown>(
   // 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`,
+        message:  `runner subprocess exited ${result.exitCode} before emitting a step result${details ? `\n${details}` : ""}`,
         exitCode: result.exitCode,
       },
     };

package/src/step-invocation/protocol.ts

@@ -14,6 +14,13 @@
  *  with the same prefix but a wrong token is rejected. */
 export const STEP_RESULT_PREFIX = "__AC_STEP_RESULT__";
 
+/** Parallel sentinel for pause requests. The runner emits this — instead
+ *  of (not in addition to) a step result — when user code calls
+ *  `ctx.pause(...)`. Exits cleanly afterwards so the activity can snapshot
+ *  the now-frozen sandbox and durably wait via Temporal `condition()`.
+ *  See ADR-0006 §"How it actually pauses — Temporal-native, end-to-end". */
+export const STEP_PAUSE_PREFIX  = "__AC_STEP_PAUSE__";
+
 /** Build the line prefix the runner emits and the invoker scans for. The
  *  runner-side serveStep writes `<prefix><token>:<json>\n`; the invoker's
  *  result parser AND the stdout line splitter both match on this exact
@@ -23,6 +30,14 @@ export function stepResultLinePrefix(token: string): string {
   return `${STEP_RESULT_PREFIX}${token}:`;
 }
 
+/** Build the pause sentinel line prefix. Same per-invocation token as the
+ *  result sentinel so the two channels share one secret — a user
+ *  `console.log` can't forge either without knowing the token, and the
+ *  invoker can filter both prefixes from captured stdout with one token. */
+export function stepPauseLinePrefix(token: string): string {
+  return `${STEP_PAUSE_PREFIX}${token}:`;
+}
+
 /** Sandbox-side path where dispatch writes the compiled runner bundle.
  *  Both modes (full-mode `dispatch.ts` and step-mode `invokeStep`) spawn
  *  the runner from this path; single source of truth. */
@@ -41,6 +56,7 @@ export const STEP_ENV = {
   STEP_INPUT_PATH:      "AC_STEP_INPUT_PATH",
   REQUEST_CONTEXT_PATH: "AC_REQUEST_CONTEXT_PATH",
   STEP_RESULT_TOKEN:    "AC_STEP_RESULT_TOKEN",
+  STEP_RESUME:          "AC_STEP_RESUME",
 } as const;
 
 /** Sandbox-side path where the invoker writes the JSON-encoded step input.

package/src/step-invocation/server.ts

@@ -23,14 +23,17 @@
 
 import { readFileSync } from "node:fs";
 import type { RequestContextWire } from "../request-context/request-context.js";
+import { RequestContextWireSchema } from "../request-context/request-context.js";
 import type { StepObservability } from "../workflow-steps/observability.js";
-import { STEP_ENV, STEP_RESULT_PREFIX } from "./protocol.js";
+import { STEP_ENV, STEP_PAUSE_PREFIX, STEP_RESULT_PREFIX } from "./protocol.js";
+import { PauseSignal, isPauseSignal } from "../pause/pause-core.js";
 
 /** What the handler receives. The serveStep already parsed the input
  *  and request context from their JSON files. */
 export interface ServeStepRequest<TInput = unknown> {
   runId:          string;
   stepIndex:      number;
+  isResume:       boolean;
   input:          TInput;
   requestContext: RequestContextWire;
 }
@@ -64,9 +67,8 @@ type SentinelPayload =
  *  immediately after a non-awaited write can drop the data on Linux
  *  pipes, leaving the invoker with empty stdout and the runner-exit
  *  classification pointing at the wrong thing. */
-function emitResult(token: string, payload: SentinelPayload): Promise<void> {
+function writeSentinelLine(line: string): Promise<void> {
   return new Promise<void>((resolve, reject) => {
-    const line = `${STEP_RESULT_PREFIX}${token}:${JSON.stringify(payload)}\n`;
     process.stdout.write(line, (err) => {
       if (err) reject(err);
       else resolve();
@@ -74,6 +76,24 @@ function emitResult(token: string, payload: SentinelPayload): Promise<void> {
   });
 }
 
+function emitResult(token: string, payload: SentinelPayload): Promise<void> {
+  return writeSentinelLine(`${STEP_RESULT_PREFIX}${token}:${JSON.stringify(payload)}\n`);
+}
+
+/** Emit the tokenised pause sentinel — `__AC_STEP_PAUSE__<token>:{pauseId,
+ *  pauseRequest}` — when the handler threw a `PauseSignal` instead of
+ *  returning. Same per-invocation token + awaited-flush discipline as
+ *  `emitResult`; the invoker's `parseStepResult` matches this exact framing
+ *  (and pause takes precedence over any stray result line). */
+function emitPause(token: string, signal: PauseSignal): Promise<void> {
+  const body = JSON.stringify({
+    pauseId: signal.pauseId,
+    pauseRequest: signal.pauseRequest,
+    ...(signal.observability ? { observability: signal.observability } : {}),
+  });
+  return writeSentinelLine(`${STEP_PAUSE_PREFIX}${token}:${body}\n`);
+}
+
 /** Delete step-invocation transport envs so the user's workflow code
  *  (loaded inside the handler) can't read them. Matters most for
  *  AC_STEP_RESULT_TOKEN: if it stayed in env, a `console.log` from a dep
@@ -89,6 +109,7 @@ function scrubProtocolEnvs(): void {
     STEP_ENV.STEP_INPUT_PATH,
     STEP_ENV.REQUEST_CONTEXT_PATH,
     STEP_ENV.STEP_RESULT_TOKEN,
+    STEP_ENV.STEP_RESUME,
   ]) {
     delete process.env[key];
   }
@@ -129,13 +150,19 @@ export async function serveStep<TInput, TOutput>(
   // and re-emitted as a step failure.
   let exitCode = 0;
   let payload!: SentinelPayload;
+  // A pause is not a result. When the handler throws `PauseSignal` (user code
+  // called `ctx.pause`), emit the pause sentinel — not a result — and exit 0,
+  // so the activity snapshots the now-frozen sandbox and waits durably.
+  // ADR-0006 §"How it actually pauses".
+  let pauseSignal: PauseSignal | undefined;
 
-  let setupResult: { runId: string; stepIndex: number; input: TInput; requestContext: RequestContextWire } | undefined;
+  let setupResult: { runId: string; stepIndex: number; isResume: boolean; input: TInput; requestContext: RequestContextWire } | undefined;
   try {
     const runId         = process.env[STEP_ENV.RUN_ID];
     const stepIndexEnv  = process.env[STEP_ENV.STEP_INDEX];
     const inputPath     = process.env[STEP_ENV.STEP_INPUT_PATH];
     const ctxPath       = process.env[STEP_ENV.REQUEST_CONTEXT_PATH];
+    const isResume      = process.env[STEP_ENV.STEP_RESUME] === "1";
     const stepIndex     = stepIndexEnv === undefined ? Number.NaN : Number(stepIndexEnv);
 
     if (!runId || !inputPath || !ctxPath || !Number.isFinite(stepIndex)) {
@@ -150,13 +177,9 @@ export async function serveStep<TInput, TOutput>(
     }
 
     const input = JSON.parse(readFileSync(inputPath, "utf8")) as TInput;
-    // RequestContextWire parsing is loose here on purpose — the wire is
-    // server-controlled, malformed shape is a server bug, and we want a
-    // useful failure reason in `failRun`. Strict validation belongs at
-    // the workflow-level RequestContext.parse boundary, not here.
-    const requestContext = JSON.parse(readFileSync(ctxPath, "utf8")) as RequestContextWire;
+    const requestContext = RequestContextWireSchema.parse(JSON.parse(readFileSync(ctxPath, "utf8")));
 
-    setupResult = { runId, stepIndex, input, requestContext };
+    setupResult = { runId, stepIndex, isResume, input, requestContext };
   } catch (err) {
     exitCode = 1;
     payload  = { ok: false, kind: "protocol", error: err instanceof Error ? err.message : String(err) };
@@ -174,11 +197,21 @@ export async function serveStep<TInput, TOutput>(
         ? { ok: true, output, observability }
         : { ok: true, output };
     } catch (err) {
-      exitCode = 1;
-      payload  = { ok: false, kind: "user-step", error: err instanceof Error ? err.message : String(err) };
+      // PauseSignal is control flow, not a failure — emit a pause, not a
+      // user-step error. Checked first so it can't be misclassified.
+      if (isPauseSignal(err)) {
+        pauseSignal = err;
+      } else {
+        exitCode = 1;
+        payload  = { ok: false, kind: "user-step", error: err instanceof Error ? err.message : String(err) };
+      }
     }
   }
 
+  if (pauseSignal) {
+    await emitPause(token, pauseSignal);
+    process.exit(0);
+  }
   await emitResult(token, payload);
   process.exit(exitCode);
 }

package/src/step-invocation/types.ts

@@ -3,6 +3,7 @@
  * the discriminated error union that classifies failure modes.
  */
 
+import { z } from "zod";
 import type { RequestContextWire } from "../request-context/request-context.js";
 import type { StepObservability } from "../workflow-steps/observability.js";
 
@@ -19,15 +20,50 @@ export interface StepRequest<TInput = unknown> {
 }
 
 /**
- * Outcome of one step invocation. Successful runs carry the step's output;
- * failed runs carry a kinded error so the caller can distinguish "user
- * code threw" from "runner crashed before emitting" from "wire protocol
- * violation". The dashboard surfaces the kind to operators; the activity
- * uses the kind to pick a useful failRun reason.
+ * Outcome of one step invocation. Three terminal states:
+ *
+ * - `ok: true` — step body resolved with `output`.
+ * - `ok: false` — step body or runner errored; kind classifies why.
+ * - `ok: "paused"` — step body called `ctx.pause(...)` and exited cleanly.
+ *   The activity captures a sandbox snapshot and the workflow waits on
+ *   Temporal `condition()` until something resumes the pause (HTTP
+ *   resume route, TTL expiry, cancellation). `pauseRequest` is what the
+ *   caller passed to `ctx.pause` — the route surfaces it on the
+ *   pending-pauses dashboard so an operator sees the question being
+ *   asked. `observability` carries any ctx metadata/sub-step/agent events
+ *   recorded before the pause unwound. See ADR-0006.
  */
 export type StepResult<TOutput = unknown> =
-  | { ok: true;  output: TOutput; observability?: StepObservability }
-  | { ok: false; error: StepInvocationError };
+  | { ok: true;     output: TOutput; observability?: StepObservability }
+  | { ok: "paused"; pauseId: string; pauseRequest: StepPauseRequest; observability?: StepObservability }
+  | { ok: false;    error: StepInvocationError };
+
+/** Wire schema for one pause request. Canonical here — `parseStepResult`
+ *  imports it for validation, and `StepPauseRequest` is `z.infer`'d from
+ *  it so the runtime type and the parsed shape can't drift.
+ *
+ *  Loose by design (the inner zod shape stops at orchestration fields
+ *  the engine needs): the SDK wrapper layer (`requestDecision` /
+ *  `sleep` / `waitForEvent`) owns its own payload contract, and the
+ *  engine treats `payload` as opaque. */
+export const StepPauseRequestSchema = z.object({
+  /** Short human-readable label; surfaces on the pending-pauses feed. */
+  reason: z.string().min(1),
+  /** Wrapper discriminator: which SDK helper produced this pause. */
+  kind:   z.enum(["decision", "sleep", "event", "custom"]),
+  /** Caller-supplied payload — opaque to the engine. */
+  payload:        z.record(z.string(), z.unknown()).optional(),
+  /** Pause TTL in milliseconds. Bounded by Temporal's sleep durability. */
+  ttlMs:          z.number().int().positive().optional(),
+  /** Optional second-key resume route — pending pause is unique per
+   *  (run, correlationKey) so event-driven senders can resume without
+   *  knowing the pause id. */
+  correlationKey: z.string().min(1).optional(),
+  /** Skip the per-pause sandbox snapshot. Default behaviour is to
+   *  snapshot; only the lightweight wrappers (`ctx.sleep`) opt out. */
+  snapshot:       z.boolean().optional(),
+});
+export type StepPauseRequest = z.infer<typeof StepPauseRequestSchema>;
 
 /**
  * Discriminated error union.