@agent-compose/sdk 0.5.0 → 0.5.2

package/src/index.ts

@@ -117,6 +117,9 @@ export type {
   ApiKey, ApiKeyCreated,
   UsageRollupRow, UsageResponse,
   CancelRunResponse,
+  RequestAgentPauseOptions, RequestAgentPauseResponse,
+  SendAgentMessageOptions, SendAgentMessageResponse,
+  AnswerSteerOptions,
 } from "./client.js";
 
 // SSE parser — exposed so tests and downstream callers can reuse it.
@@ -126,8 +129,7 @@ export { parseSseStream } from "./sse.js";
 export { AgentComposeError } from "./errors.js";
 export { formatError } from "./utils/errors.js";
 
-// Source discovery + bundling utilities
-export { discoverRuntimeName } from "./utils/discovery.js";
+// Bundling utilities
 export {
   bundleWorkflow,
   BUNDLER_VERSION,
@@ -209,16 +211,30 @@ export {
   buildStepEnvs,
   StepExecutionError,
   STEP_RESULT_PREFIX,
+  STEP_PAUSE_PREFIX,
   STEP_ENV,
   RUNNER_BUNDLE_PATH,
   RUNNER_COMMAND,
   stepInputPath,
   requestContextPath,
 } from "./step-invocation/index.js";
+
+// Pause errors (ADR-0006 / ADR-0011) — thrown into user step/agent code when
+// a pause cannot return a value, so callers can catch and classify them.
+export {
+  PauseError,
+  PauseExpiredError,
+  PauseSchemaError,
+  PauseRequestError,
+} from "./pause/errors.js";
+export type { PauseErrorCode } from "./pause/errors.js";
+export type { PauseRequest } from "./pause/pause-core.js";
+export type { RequestDecisionRequest, WaitForEventRequest } from "./pause/wrappers.js";
 export type {
   StepRequest,
   StepResult,
   StepInvocationError,
+  StepPauseRequest,
   StepHandler,
   StepHandlerResult,
   ServeStepRequest,

package/src/pause/checkpoint.ts

@@ -0,0 +1,44 @@
+/**
+ * `ctx.checkpoint(name, fn)` — disk-backed memoise across pause-resume.
+ *
+ * First call: `fn()` runs, the result is atomically written to
+ * `/tmp/wf/state/checkpoints/<name>.json`. On any subsequent invocation
+ * of the same step body (e.g. after pause-resume re-enters the
+ * subprocess), the file exists in the restored sandbox; `fn` is NOT
+ * called, the recorded value is returned.
+ *
+ * Use for: large context loads, expensive deterministic transforms,
+ * idempotent-but-slow computations that you want to skip on resume.
+ *
+ * Do NOT use for: side effects with external systems (DB writes, HTTP
+ * POSTs, sending email). Those need `ctx.invokeChild(...)` — Temporal's
+ * exactly-once guarantee covers cross-process side effects; disk-backed
+ * memoisation is in-sandbox only and would silently retry on a sandbox
+ * recreation that lost the checkpoint file.
+ *
+ * See ADR-0006 §"`ctx.checkpoint(name, fn)` — disk-backed memoisation".
+ */
+
+import { assertSafeCheckpointName, readCheckpoint, writeCheckpoint } from "./state-dir.js";
+
+/** Read-or-run-and-write helper. `name` is validated by the state-dir
+ *  layer (rejects path-escape attempts); `fn` is awaited if it returns
+ *  a Promise so sync and async callers compose identically. */
+export async function checkpoint<T>(name: string, fn: () => Promise<T> | T): Promise<T> {
+  const existing = await readCheckpoint<T>(name);
+  if (existing.found) return existing.value;
+  const value = await fn();
+  await writeCheckpoint(name, value);
+  return value;
+}
+
+/** Bind user checkpoint names to a runner-owned namespace. The user's
+ *  `name` is still validated independently so a scope prefix cannot turn
+ *  an empty or path-escaping name into a valid filename. */
+export function scopedCheckpoint(scope: string): typeof checkpoint {
+  assertSafeCheckpointName(scope);
+  return async <T>(name: string, fn: () => Promise<T> | T): Promise<T> => {
+    assertSafeCheckpointName(name);
+    return checkpoint(`${scope}.${name}`, fn);
+  };
+}

package/src/pause/errors.ts

@@ -0,0 +1,70 @@
+/**
+ * User-facing pause errors (ADR-0006 / ADR-0011).
+ *
+ * These are thrown into USER step/agent code when a pause cannot return a
+ * value — the caller can catch them. They are distinct from `PauseSignal`
+ * (the internal control-flow signal in `pause-core.ts` that unwinds the
+ * stack to `serveStep`): `PauseSignal` never reaches user code, these do.
+ *
+ * Each carries a stable `code` so the activity boundary and the dashboard
+ * can classify the failure without string-matching the message — the same
+ * pattern as `StepExecutionError` (`step-invocation/types.ts`).
+ *
+ * `target: ESNext` (sdk/tsconfig.json) makes `extends Error` + `instanceof`
+ * work without a manual prototype fix; `this.name = new.target.name` gives
+ * each subclass its own class name on the instance.
+ */
+
+/** Stable, machine-readable discriminator for each pause error. */
+export type PauseErrorCode =
+  | "pause_expired"
+  | "pause_schema"
+  | "pause_request";
+
+/** Base for every user-facing pause error. Not thrown directly. */
+export abstract class PauseError extends Error {
+  abstract readonly code: PauseErrorCode;
+  constructor(message: string) {
+    super(message);
+    this.name = new.target.name;
+  }
+}
+
+/**
+ * The pause's TTL elapsed before it was resolved, and `onExpiry` was
+ * `{ mode: "throw" }` (the default). When `onExpiry` is
+ * `{ mode: "resolve", value }`, `ctx.pause` returns `value` instead of
+ * throwing this.
+ */
+export class PauseExpiredError extends PauseError {
+  readonly code = "pause_expired";
+  constructor(message = "pause expired before it was resolved") {
+    super(message);
+  }
+}
+
+/**
+ * The resume payload failed the caller's `schema`. `issues` carries the
+ * validation detail for an in-sandbox `catch`; note only `message` survives
+ * the serveStep wire boundary, so do not rely on `issues` outside the
+ * throwing process.
+ */
+export class PauseSchemaError extends PauseError {
+  readonly code = "pause_schema";
+  readonly issues: unknown;
+  constructor(message: string, issues?: unknown) {
+    super(message);
+    this.issues = issues;
+  }
+}
+
+/**
+ * The pause request itself is invalid before it can be emitted to the engine:
+ * empty reason, non-positive ttl, invalid kind, or a non-JSON payload.
+ */
+export class PauseRequestError extends PauseError {
+  readonly code = "pause_request";
+  constructor(message = "pause request is invalid") {
+    super(message);
+  }
+}

package/src/pause/manager.ts

@@ -0,0 +1,177 @@
+/**
+ * Local pause/resume manager.
+ *
+ * This module owns the SDK-local state machine that makes a re-entered
+ * runner subprocess pick up agent work correctly. It deliberately does not
+ * know about Temporal, Postgres, HTTP resume routes, or dashboard feeds.
+ * Those layers own durable wait/audit state; this layer owns only the
+ * `/tmp/wf/state` files captured by sandbox snapshots.
+ */
+
+import { z } from "zod";
+import type { AgentStatus } from "../types/protocol.js";
+import type { ModelExecutionContract } from "../types/runtime.js";
+import { AgentStatusSchema } from "../utils/schemas.js";
+import {
+  readAgentState,
+  readRuntimeCheckpoint,
+  writeAgentState,
+  writeRuntimeCheckpoint,
+} from "./state-dir.js";
+
+// v2 (PR 7) adds `pendingSteerPause`. The change is purely additive — a v1
+// `agent-<id>.json` is a valid v2 object minus that one `.default(null)` field —
+// so this build WRITES the current version but ACCEPTS both on read. A hard
+// `literal(2)` would reject every v1 checkpoint as invalid and reset the agent
+// to iteration 0: `flushState` writes this file at every iteration boundary for
+// crash recovery (shipped in #100), independent of whether a pause ever fires,
+// so durable v1 snapshots exist for any in-flight run across a deploy.
+const AGENT_LOOP_STATE_SCHEMA_VERSION = 2;
+/** Versions this build can READ. Every field added since v1 is optional or
+ *  defaulted, so older checkpoints stay loadable across a rolling deploy. */
+const SUPPORTED_AGENT_LOOP_STATE_VERSIONS = z.union([z.literal(1), z.literal(2)]);
+
+const RunningAgentLoopStateSchema = z.object({
+  schemaVersion:               SUPPORTED_AGENT_LOOP_STATE_VERSIONS,
+  phase:                       z.literal("running"),
+  iteration:                   z.number().int().nonnegative(),
+  completedIterations:         z.number().int().nonnegative(),
+  lastSessionId:               z.string(),
+  lastStatus:                  AgentStatusSchema.nullable(),
+  lastResponseText:            z.string(),
+  lastResponseValidationError: z.string(),
+  iterationsWithoutStatus:     z.number().int().nonnegative(),
+  blockerStreak:               z.object({ key: z.string(), count: z.number().int().nonnegative() }).nullable(),
+  // PR 7: a human-requested steer-pause intent, persisted so it survives a
+  // resume and the loop re-issues the boundary pause on re-entry.
+  pendingSteerPause:            z.object({ reason: z.string(), correlationKey: z.string().nullable(), at: z.number().int() }).nullable().default(null),
+});
+
+const SettledAgentLoopStateSchema = z.object({
+  schemaVersion: SUPPORTED_AGENT_LOOP_STATE_VERSIONS,
+  phase:         z.literal("settled"),
+  result:        z.object({
+    sessionId:  z.string(),
+    lastStatus: AgentStatusSchema.nullable(),
+    iterations: z.number().int().nonnegative(),
+    response:   z.unknown().optional(),
+  }),
+});
+
+const AgentLoopStateSchema = z.discriminatedUnion("phase", [
+  RunningAgentLoopStateSchema,
+  SettledAgentLoopStateSchema,
+]);
+
+type RunningAgentLoopState = z.infer<typeof RunningAgentLoopStateSchema>;
+
+export interface AgentLoopProgressState {
+  iteration:                   number;
+  completedIterations:         number;
+  lastSessionId:               string;
+  lastStatus:                  AgentStatus | null;
+  lastResponseText:            string;
+  lastResponseValidationError: string;
+  iterationsWithoutStatus:     number;
+  blockerStreak:               { key: string; count: number } | null;
+  /** PR 7 steer-pause intent — see RunningAgentLoopStateSchema. Optional so the
+   *  loop can omit it until it wires steer (the schema defaults it to null). */
+  pendingSteerPause?:           { reason: string; correlationKey: string | null; at: number } | null;
+}
+
+export interface SettledAgentLoopResult<TResponse = unknown> {
+  sessionId:   string;
+  lastStatus:  AgentStatus | null;
+  iterations:  number;
+  response?:   TResponse;
+}
+
+export type AgentLoopRestore<TResponse = unknown> =
+  | { kind: "fresh" }
+  | { kind: "invalid"; error: string }
+  | { kind: "running"; state: AgentLoopProgressState }
+  | { kind: "settled"; result: SettledAgentLoopResult<TResponse> };
+
+function toProgressState(state: RunningAgentLoopState): AgentLoopProgressState {
+  return {
+    iteration:                   state.iteration,
+    completedIterations:         state.completedIterations,
+    lastSessionId:               state.lastSessionId,
+    lastStatus:                  state.lastStatus,
+    lastResponseText:            state.lastResponseText,
+    lastResponseValidationError: state.lastResponseValidationError,
+    iterationsWithoutStatus:     state.iterationsWithoutStatus,
+    blockerStreak:               state.blockerStreak,
+    pendingSteerPause:            state.pendingSteerPause,
+  };
+}
+
+/**
+ * Coordinates the agent-loop files in `/tmp/wf/state`.
+ *
+ * Raw filesystem safety lives in `state-dir.ts`; runtime blob shape lives in
+ * each runtime adapter. `PauseManager` is the seam that binds those two to
+ * the agent-loop state machine.
+ */
+export class PauseManager {
+  constructor(private readonly agentId: string) {}
+
+  async restoreAgentLoop<TResponse = unknown>(runtime: ModelExecutionContract): Promise<AgentLoopRestore<TResponse>> {
+    const priorState = await readAgentState<unknown>(this.agentId);
+    if (priorState === null) return { kind: "fresh" };
+
+    const parsed = AgentLoopStateSchema.safeParse(priorState);
+    if (!parsed.success) return { kind: "invalid", error: parsed.error.message };
+
+    const state = parsed.data;
+    if (state.phase === "settled") {
+      return {
+        kind:   "settled",
+        result: {
+          sessionId:  state.result.sessionId,
+          lastStatus: state.result.lastStatus,
+          iterations: state.result.iterations,
+          ...(Object.prototype.hasOwnProperty.call(state.result, "response")
+            ? { response: state.result.response as TResponse }
+            : {}),
+        },
+      };
+    }
+
+    const runtimeBlob = await readRuntimeCheckpoint<unknown>(this.agentId);
+    if (runtimeBlob !== null && !runtime.restoreCheckpoint) {
+      throw new Error(`runtime checkpoint exists for resumed agentId=${this.agentId}, but runtime cannot restore it`);
+    }
+    if (runtime.restoreCheckpoint && runtimeBlob === null) {
+      throw new Error(`missing runtime checkpoint for resumed agentId=${this.agentId}`);
+    }
+    if (runtimeBlob !== null) runtime.restoreCheckpoint?.(runtimeBlob);
+
+    return { kind: "running", state: toProgressState(state) };
+  }
+
+  async saveRunningAgentLoop(state: AgentLoopProgressState, runtime: ModelExecutionContract): Promise<void> {
+    await writeAgentState(this.agentId, {
+      schemaVersion: AGENT_LOOP_STATE_SCHEMA_VERSION,
+      phase:         "running",
+      ...state,
+    });
+    if (runtime.captureCheckpoint) {
+      const blob = runtime.captureCheckpoint();
+      if (blob !== undefined) await writeRuntimeCheckpoint(this.agentId, blob);
+    }
+  }
+
+  async saveSettledAgentLoop<TResponse = unknown>(result: SettledAgentLoopResult<TResponse>): Promise<void> {
+    await writeAgentState(this.agentId, {
+      schemaVersion: AGENT_LOOP_STATE_SCHEMA_VERSION,
+      phase:         "settled",
+      result:        {
+        sessionId:  result.sessionId,
+        lastStatus: result.lastStatus,
+        iterations: result.iterations,
+        ...(result.response !== undefined ? { response: result.response } : {}),
+      },
+    });
+  }
+}

package/src/pause/pause-core.ts

@@ -0,0 +1,267 @@
+/**
+ * `pause-core` — the engine behind `ctx.pause` (ADR-0006 / ADR-0011 PR 6).
+ *
+ * How a pause works (and why this shape):
+ *
+ *   First reach (fresh):  read `pauses/<pauseId>.json` → absent/unresolved →
+ *     write the placeholder record and `throw new PauseSignal(...)`. The
+ *     exception unwinds the step body to `serveStep`, which emits the
+ *     `__AC_STEP_PAUSE__` sentinel and exits 0. The engine snapshots, inserts
+ *     a `run_pauses` row keyed by `pauseId`, and waits durably.
+ *
+ *   Re-entry (resolved): the engine has written the resolution onto the same
+ *     file. The runner re-runs the step body from the top in a fresh
+ *     subprocess; the SAME `ctx.pause` call recomputes the SAME `pauseId`,
+ *     reads the file, and returns the resume payload (or applies `onExpiry`).
+ *
+ * The whole thing hinges on `pauseId` being recomputed identically across the
+ * exit/re-enter boundary, with NO surviving in-process state. So `pauseId` is
+ * a **deterministic UUIDv5** of a stable coordinate — never random. UUIDv5
+ * (not a free-form string) because `run_pauses.id` is a `uuid` PRIMARY KEY.
+ *
+ * `PauseSignal` is internal control flow, NOT a user-facing error — `serveStep`
+ * and the agent loop must let it propagate (the user-facing `Pause*Error` classes in
+ * `errors.ts` are the ones user code catches). It deliberately does not extend
+ * `Error`, so a stray `catch (e) { if (e instanceof Error) … }` cannot quietly
+ * absorb it; callers add explicit `instanceof PauseSignal` re-throw guards.
+ *
+ * Runs in the runner subprocess (may use `node:crypto`), never in the Temporal
+ * workflow VM.
+ */
+
+import { createHash } from "node:crypto";
+import type { z } from "zod";
+import { StepPauseRequestSchema, type StepPauseRequest } from "../step-invocation/types.js";
+import type { StepObservability } from "../workflow-steps/observability.js";
+import { nextPauseOrdinalInActiveStep } from "../active-step.js";
+import { readPauseRecord, writePauseRecord } from "./state-dir.js";
+import { PauseExpiredError, PauseRequestError, PauseSchemaError } from "./errors.js";
+
+/** Public `ctx.pause` argument shape (ADR-0006 §"SDK surface"). `schema` and
+ *  `onExpiry` are SDK-local — consumed here, never sent on the wire. The wire
+ *  `kind` is NOT a public field: a raw `ctx.pause` is always `kind: "custom"`;
+ *  `decision`/`sleep`/`event` come only from the wrappers. */
+export interface PauseRequest<T = unknown> {
+  reason:          string;
+  payload?:        Record<string, unknown>;
+  schema?:         z.ZodType<T>;
+  ttlMs?:          number;
+  onExpiry?:       { mode: "throw" } | { mode: "resolve"; value: T };
+  correlationKey?: string;
+  snapshot?:       boolean;
+}
+
+/** The coordinate that makes `pauseId` deterministic + re-entry-stable. */
+export interface PauseCoordinate {
+  runId:     string;
+  stepIndex: number;
+  /** Present when the pause fires inside an agent loop (PR 7 steer-pause).
+   *  Pins the id to the loop boundary (agentId + iteration) so it stays stable
+   *  across the loop's iteration-skipping on resume — a bare per-step ordinal
+   *  desyncs because completed iterations don't re-run, landing the ordinal at
+   *  a different value. Step-body pauses leave it absent (the `:bare` form). */
+  agentScope?: { agentId: string; iteration: number };
+}
+
+/** Realm-global brand so `isPauseSignal` recognises a PauseSignal thrown by a
+ *  DIFFERENT SDK instance. A bundled workflow inlines its own SDK copy (its
+ *  `agent()` steer-pause throws the bundle's `PauseSignal`), but the runner
+ *  catches with its own class — a plain `instanceof` is false across that
+ *  boundary, so the pause was mis-classified as a step failure and no
+ *  `run_pauses` row was written. `ctx.pause` avoided this only because its
+ *  signal is runner-thrown. `Symbol.for` is shared across the realm, so the
+ *  brand survives the instance split. */
+const PAUSE_SIGNAL_BRAND = Symbol.for("agent-compose.PauseSignal");
+
+/**
+ * Internal control-flow signal thrown by `corePause` on a fresh pause.
+ * Caught by `serveStep` (emits the sentinel + exits) and re-thrown past every
+ * intermediate catch. NOT an `Error` and NOT user-facing.
+ */
+export class PauseSignal {
+  readonly [PAUSE_SIGNAL_BRAND] = true as const;
+  constructor(
+    readonly pauseId: string,
+    readonly pauseRequest: StepPauseRequest,
+    readonly observability?: StepObservability,
+  ) {}
+}
+
+/** Cross-instance-safe `PauseSignal` check. Use this instead of
+ *  `err instanceof PauseSignal` anywhere a signal may have been thrown by a
+ *  different SDK instance (the runner catching a bundled workflow's signal). */
+export function isPauseSignal(err: unknown): err is PauseSignal {
+  return typeof err === "object" && err !== null && (err as Record<symbol, unknown>)[PAUSE_SIGNAL_BRAND] === true;
+}
+
+// ── Deterministic pauseId ───────────────────────────────────────────────────
+
+/** Fixed namespace for agent-compose pause ids (UUIDv5). Constant — must
+ *  never change, or in-flight paused workflows would recompute different ids
+ *  on resume and fail to find their resolved records. */
+const PAUSE_NAMESPACE = "5f3e2b8a-0c41-4e9d-9a7b-6d2c1f8e3a40";
+
+function uuidToBytes(uuid: string): Buffer {
+  return Buffer.from(uuid.replace(/-/g, ""), "hex");
+}
+
+function bytesToUuid(b: Buffer): string {
+  const h = b.toString("hex");
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20, 32)}`;
+}
+
+/** RFC 4122 v5 (SHA-1, name-based). Deterministic: same name → same uuid. */
+function uuidv5(name: string, namespace: string): string {
+  const hash = createHash("sha1")
+    .update(uuidToBytes(namespace))
+    .update(Buffer.from(name, "utf8"))
+    .digest();
+  const bytes = Buffer.from(hash.subarray(0, 16));
+  bytes[6] = (bytes[6] & 0x0f) | 0x50; // version 5
+  bytes[8] = (bytes[8] & 0x3f) | 0x80; // RFC 4122 variant
+  return bytesToUuid(bytes);
+}
+
+/** The call-site family this pause belongs to. The ordinal is counted per
+ *  scope; `nextPauseId` appends `:${ordinal}`. An in-agent-loop pause keys on
+ *  `agentId:iteration` (stable across iteration-skipping on resume); a
+ *  step-body pause keeps the `:bare` form — byte-identical to shipped ids. */
+function scopeOf(coord: PauseCoordinate): string {
+  return coord.agentScope
+    ? `${coord.runId}:${coord.stepIndex}:${coord.agentScope.agentId}:${coord.agentScope.iteration}`
+    : `${coord.runId}:${coord.stepIndex}:bare`;
+}
+
+// Per-scope ordinal. Module-level so it resets on a fresh subprocess (the
+// resume boundary) — which is exactly what makes the k-th pause in a scope
+// recompute the same id across re-entry. Mirrors `nextAgentCallIndexByStep`.
+const pauseOrdinalByScope = new Map<string, number>();
+
+function nextPauseOrdinal(scope: string): number {
+  const activeOrdinal = nextPauseOrdinalInActiveStep(scope);
+  if (activeOrdinal !== null) return activeOrdinal;
+  const next = pauseOrdinalByScope.get(scope) ?? 0;
+  pauseOrdinalByScope.set(scope, next + 1);
+  return next;
+}
+
+/** Wipe the ordinal counters. Called by the runner at first-boot alongside
+ *  `resetStateDir()`; a fresh module load already starts empty, so this is
+ *  belt-and-braces for any in-process reuse. */
+export function resetPauseOrdinals(): void {
+  pauseOrdinalByScope.clear();
+}
+
+/** Compute the deterministic pauseId for the next pause in `coord`'s scope. */
+function nextPauseId(coord: PauseCoordinate): string {
+  const scope = scopeOf(coord);
+  const ordinal = nextPauseOrdinal(scope);
+  return uuidv5(`${scope}:${ordinal}`, PAUSE_NAMESPACE);
+}
+
+// ── Wire request ─────────────────────────────────────────────────────────────
+
+function nonJsonPath(value: unknown, path = "$", seen = new Set<object>()): string | null {
+  if (value === null) return null;
+  const kind = typeof value;
+  if (kind === "string" || kind === "boolean") return null;
+  if (kind === "number") return Number.isFinite(value) ? null : path;
+  if (kind === "undefined" || kind === "bigint" || kind === "function" || kind === "symbol") return path;
+  if (kind !== "object") return path;
+
+  const obj = value as object;
+  if (seen.has(obj)) return path;
+  seen.add(obj);
+
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) {
+      const child = nonJsonPath(value[i], `${path}[${i}]`, seen);
+      if (child) return child;
+    }
+    seen.delete(obj);
+    return null;
+  }
+
+  const proto = Object.getPrototypeOf(obj);
+  if (proto !== Object.prototype && proto !== null) return path;
+  for (const key of Reflect.ownKeys(obj)) {
+    if (typeof key !== "string") return `${path}.${String(key)}`;
+    const desc = Object.getOwnPropertyDescriptor(obj, key);
+    if (!desc?.enumerable) return `${path}.${key}`;
+    const child = nonJsonPath((value as Record<string, unknown>)[key], `${path}.${key}`, seen);
+    if (child) return child;
+  }
+  seen.delete(obj);
+  return null;
+}
+
+function toWireRequest(req: PauseRequest<unknown>, kind: StepPauseRequest["kind"]): StepPauseRequest {
+  // Allowlist-pick the wire fields explicitly — never spread `req`, or the
+  // SDK-local `schema` (a non-JSON-serialisable ZodType) and `onExpiry` would
+  // ride onto the sentinel / `run_pauses.request_payload`. `kind` is supplied
+  // by the caller (the wrappers; "custom" for a raw pause), not read from req.
+  const wire = {
+    reason: req.reason,
+    kind,
+    ...(req.payload !== undefined ? { payload: req.payload } : {}),
+    ...(req.ttlMs !== undefined ? { ttlMs: req.ttlMs } : {}),
+    ...(req.correlationKey !== undefined ? { correlationKey: req.correlationKey } : {}),
+    ...(req.snapshot !== undefined ? { snapshot: req.snapshot } : {}),
+  };
+  const parsed = StepPauseRequestSchema.safeParse(wire);
+  if (!parsed.success) {
+    throw new PauseRequestError(`pause request failed validation: ${parsed.error.message}`);
+  }
+  const badPath = nonJsonPath(parsed.data);
+  if (badPath) {
+    throw new PauseRequestError(`pause request must be JSON-serializable (invalid value at ${badPath})`);
+  }
+  return parsed.data;
+}
+
+// ── The engine ───────────────────────────────────────────────────────────────
+
+/**
+ * The body of `ctx.pause`. On a fresh pause it throws `PauseSignal`; on
+ * re-entry it returns the resume payload (or applies `onExpiry` / throws
+ * `PauseSchemaError`). See the module header.
+ */
+export async function corePause<T = unknown>(
+  req: PauseRequest<T>,
+  coord: PauseCoordinate,
+  kind: StepPauseRequest["kind"] = "custom",
+): Promise<T> {
+  const wire = toWireRequest(req, kind);
+  const pauseId = nextPauseId(coord);
+  const record = await readPauseRecord(pauseId);
+
+  // Fresh pause (no file yet) OR our own un-resolved placeholder: write the
+  // placeholder and signal. `resolved !== true` is the guard — a placeholder
+  // we just wrote in a prior pass has no `resolved` key.
+  if (record === null || record.resolved !== true) {
+    await writePauseRecord({ pauseId, request: wire });
+    throw new PauseSignal(pauseId, wire);
+  }
+
+  // Resolved by a TTL expiry.
+  if (record.expired === true) {
+    const onExpiry = req.onExpiry ?? { mode: "throw" };
+    if (onExpiry.mode === "resolve") return onExpiry.value;
+    throw new PauseExpiredError(`pause "${req.reason}" expired before it was resolved`);
+  }
+
+  // Resolved by a real resume. Validate against the caller's schema if given.
+  const payload = record.resumePayload ?? null;
+  if (req.schema) {
+    const parsed = req.schema.safeParse(payload);
+    if (!parsed.success) {
+      // v1: schema failure always throws; lax reopen-on-failure is deferred (ADR-0011).
+      throw new PauseSchemaError(
+        `resume payload for pause "${req.reason}" failed schema validation: ${parsed.error.message}`,
+        parsed.error.issues,
+      );
+    }
+    return parsed.data;
+  }
+  return payload as T;
+}