@agent-compose/sdk 0.5.1 → 0.5.5

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.

package/src/tools/coding.ts

@@ -10,6 +10,13 @@ function resolvePath(path: string, cwd?: string): string {
   return cwd && !isAbsolute(path) ? join(cwd, path) : path;
 }
 
+function formatCommandFailure(command: string, result: { exitCode: number; stdout: string; stderr: string }): string {
+  const parts = [`Command failed with exit code ${result.exitCode}: ${command}`];
+  if (result.stderr.trim()) parts.push(`stderr:\n${result.stderr}`);
+  if (result.stdout.trim()) parts.push(`stdout:\n${result.stdout}`);
+  return parts.join("\n");
+}
+
 async function readFile(sandbox: SandboxProvider, path: string, opts?: { offset?: number; limit?: number; cwd?: string }): Promise<string> {
   const script = `
 const fs = require("fs");
@@ -26,14 +33,18 @@ for (let i = start; i <= end; i++) console.log(String(i) + ": " + lines[i - 1]);
     .filter(Boolean)
     .map(q)
     .join(" ");
-  const { stdout } = await sandbox.commands.run(`node -e ${q(script)} ${args}`, { cwd: opts?.cwd, timeoutMs: 30_000 });
-  return stdout;
+  const command = `node -e ${q(script)} ${args}`;
+  const result = await sandbox.commands.run(command, { cwd: opts?.cwd, timeoutMs: 30_000 });
+  if (result.exitCode !== 0) throw new Error(formatCommandFailure(command, result));
+  return result.stdout;
 }
 
 async function readRawFile(sandbox: SandboxProvider, path: string, cwd?: string): Promise<string> {
   const script = `const fs = require("fs"); process.stdout.write(fs.readFileSync(process.argv[1], "utf8"));`;
-  const { stdout } = await sandbox.commands.run(`node -e ${q(script)} ${q(path)}`, { cwd, timeoutMs: 30_000 });
-  return stdout;
+  const command = `node -e ${q(script)} ${q(path)}`;
+  const result = await sandbox.commands.run(command, { cwd, timeoutMs: 30_000 });
+  if (result.exitCode !== 0) throw new Error(formatCommandFailure(command, result));
+  return result.stdout;
 }
 
 export interface CodingTool<TInput extends Record<string, unknown> = Record<string, unknown>> {
@@ -118,7 +129,7 @@ export const bashTool: CodingTool<{
       cwd: cwd ?? ctx.cwd,
       timeoutMs: timeoutMs ?? 120_000,
     });
-    if (result.exitCode !== 0) throw new Error(`Command failed with exit code ${result.exitCode}${result.stdout ? `\n${result.stdout}` : ""}`);
+    if (result.exitCode !== 0) throw new Error(formatCommandFailure(command, result));
     return result.stdout;
   },
 };

package/src/types/events.ts

@@ -15,6 +15,15 @@ export type RunEvent =
       seq?: number;
       agentId: string;
       label: string;
+      /** Tool whitelist passed to `agent({ tools: [...] })`. Drives the
+       *  per-agent "tools" badge on the dashboard. */
+      allowedTools?: string[];
+      /** Resolved model id (e.g. `claude-sonnet-4-6`). */
+      model?: string;
+      /** Short runtime self-identifier (`claude`, `openai-desktop`, …)
+       *  read off `ModelExecutionContract.kind`. The dashboard maps
+       *  this to a small runtime icon on the agent card header. */
+      runtimeKind?: string;
     }
   | {
       event: "agent.message";

package/src/types/execution-context.ts

@@ -2,6 +2,8 @@
 
 import type { InvokeAndWaitOptions, RunStatus } from "../client.js";
 import type { RequestContext } from "../request-context/request-context.js";
+import type { PauseRequest } from "../pause/pause-core.js";
+import type { RequestDecisionRequest, WaitForEventRequest } from "../pause/wrappers.js";
 import type { SandboxProvider } from "./sandbox.js";
 
 /** The identity of this workflow run. */
@@ -27,4 +29,27 @@ export interface BaseExecutionContext {
   setMetadata?: (data: Record<string, unknown>) => Promise<void>;
   /** Invoke another registered workflow and wait for it to settle. */
   invokeChild: InvokeChild;
+  /**
+   * Disk-backed memoise across pause-resume. First call runs `fn` and
+   * atomically writes the result to the sandbox; on resume the recorded
+   * value is returned and `fn` is NOT re-executed. Use for expensive
+   * deterministic transforms; for side effects, use `invokeChild`.
+   * See ADR-0006 §"`ctx.checkpoint(name, fn)` — disk-backed memoisation".
+   */
+  checkpoint<T>(name: string, fn: () => Promise<T> | T): Promise<T>;
+  /**
+   * Pause for feedback. The step exits and the workflow waits durably until
+   * something resolves the pause (a resume call, a TTL expiry); on resume the
+   * step body re-runs from the top and this call returns the resume payload.
+   * Provide a `schema` to validate the payload, `ttlMs` + `onExpiry` to bound
+   * the wait, `correlationKey` for by-key resume. Throws PauseRequestError /
+   * PauseExpiredError / PauseSchemaError. See ADR-0006 / ADR-0011.
+   */
+  pause<T = unknown>(req: PauseRequest<T>): Promise<T>;
+  /** Pause for a typed decision (a `schema` is required). Wrapper over `pause`. */
+  requestDecision<T>(req: RequestDecisionRequest<T>): Promise<T>;
+  /** Lightweight timed pause — resolves after `durationMs`, no snapshot. */
+  sleep(durationMs: number): Promise<void>;
+  /** Pause until an event resumes by `correlationKey`. Wrapper over `pause`. */
+  waitForEvent<T = unknown>(req: WaitForEventRequest<T>): Promise<T>;
 }

package/src/types/protocol.ts

@@ -71,4 +71,12 @@ export interface AgentStatus {
   completed: string[];
   blockers: string[];
   exit_signal: boolean;
+  /** PR 7 self-pause (honoured only for `mode: "hitl"` agents). The agent
+   *  cannot proceed without a human decision: it sets this true, puts the
+   *  question in `question`, and ends its turn. The loop pauses at the next
+   *  boundary and injects the human's answer as the next turn. `auto` agents
+   *  ignore it and keep going. Should be paired with `exit_signal: false`. */
+  needs_input?: boolean;
+  /** The question to put to the human when `needs_input` is true. */
+  question?: string;
 }

package/src/types/runtime.ts

@@ -48,14 +48,66 @@ export type ToolCallGateResult =
 export interface ModelExecutionContract {
   /** True when this runtime can run `processToolCall` before tool execution. */
   supportsToolCallProcessor?: boolean;
+  /** Short self-identifier ("claude", "openai-desktop", "vercel", …). Read
+   *  by the agent loop and surfaced on `agent.spawned` so the dashboard
+   *  can show a per-agent runtime icon without re-fetching template
+   *  metadata. Optional — runtimes that omit it stay anonymous. */
+  kind?: string;
+  /** Resolved model id used by this runtime instance (already merged with
+   *  config + runtime defaults). Surfaced on `agent.spawned` so each
+   *  agent card on the Agent tab can label which model it ran against. */
+  model?: string;
   /** Runtime-owned pre-tool gate. Adapters call the shared processor chain
    *  through this seam; the agent loop stays SDK-agnostic. */
   gateToolCall?(call: ToolCall, ctx: ProcessorContext): Promise<ToolCallGateResult>;
+  /**
+   * Capture runtime-private in-memory state that will not survive the
+   * runner subprocess exit. Called by the agent loop at pause time,
+   * AFTER the loop has flushed its own state to disk.
+   *
+   * Return value is opaque to the loop — whatever the runtime needs to
+   * round-trip its conversation across pause-resume. Must be JSON-
+   * serialisable; the loop atomically writes it to
+   * `/tmp/wf/state/runtime-<agentInstanceId>.json` and reads it back
+   * on resume to hand to `restoreCheckpoint`.
+   *
+   * Default (method omitted): runtime holds no instance state that
+   * needs to round-trip across pause. The shipped example is the
+   * Claude runtime — the conversation lives server-side at
+   * Anthropic, addressed by `session_id`, and the loop already holds
+   * `lastSessionId` as part of its own state. On resume the loop
+   * restores the id, the next `sendMessage` passes it through, and
+   * Anthropic resumes the server-side conversation.
+   *
+   * Runtimes that hold the conversation in-process — Vercel's
+   * `VercelRunner.messages` is the canonical case — MUST implement
+   * both hooks: the messages array is reconstructed from
+   * `response.messages` on each `streamText` and would be lost the
+   * moment the subprocess exits. See ADR-0006 §"Concrete examples
+   * for shipped runtimes" for the audit + worked examples.
+   */
+  captureCheckpoint?(): unknown;
+  /**
+   * Restore runtime-private state previously returned by
+   * `captureCheckpoint`. Called by the agent loop on resume, AFTER
+   * the loop has restored its own state but BEFORE iterations resume.
+   *
+   * `blob` is whatever this same runtime returned at pause time. If
+   * `captureCheckpoint` is omitted, this is never called.
+   */
+  restoreCheckpoint?(blob: unknown): void;
   sendMessage(opts: {
     prompt: string;
     sessionId?: string;
     iteration?: number;
     signal?: AbortSignal;
+    /** Push-iterable of mid-turn user messages from outside the agent
+     *  loop — e.g. dashboard chat injections. Runtimes that support
+     *  streaming-input mode (Claude Agent SDK) read from this in
+     *  parallel with the initial `prompt`; the SDK handles delivery
+     *  at the next safe boundary. Runtimes without streaming-input
+     *  support ignore this and fall back to per-iteration injection. */
+    inboxStream?: AsyncIterable<{ text: string; senderName?: string | null }>;
   }): AsyncGenerator<AgentMessage>;
 }
 

package/src/types/sandbox.ts

@@ -10,17 +10,17 @@ export interface SandboxCommandRunOptions {
   envs?: Record<string, string>;
   onStdout?: (data: string) => void;
   onStderr?: (data: string) => void;
-  background?: boolean;
   /** Run the command with root privileges. Vercel maps this to its native
-   *  `sudo` flag; E2B runs the command as `user: "root"`; the local provider
-   *  prepends `sudo`. Defaults to false. Requires the sandbox image to grant
-   *  the command root (Vercel's runtimes do — passwordless). */
+   *  `sudo` flag; the local provider prepends `sudo`. Defaults to false.
+   *  Requires the sandbox image to grant the command root (Vercel's runtimes
+   *  do — passwordless). */
   sudo?: boolean;
 }
 
 export interface SandboxCommandResult {
   exitCode: number;
   stdout: string;
+  stderr: string;
 }
 
 export interface SandboxProvider {
@@ -28,6 +28,10 @@ export interface SandboxProvider {
   /** Working directory for the agent process. Set by onStart after environment setup. */
   cwd?: string;
   commands: {
+    // NOTE: does NOT throw on non-zero exit. Callers must check
+    // `result.exitCode` themselves. The `agent-env` setup workflow's
+    // `run(sb, cmd)` helper is the canonical pattern — copy it into any
+    // setup workflow that needs to fail loudly on command errors.
     run(cmd: string, opts?: SandboxCommandRunOptions): Promise<SandboxCommandResult>;
   };
   files: {