@agent-compose/sdk 0.5.8 → 0.6.0

package/dist/runtimes/vercel.js

@@ -330,6 +330,391 @@ class RequestContext {
   }
 }
 
+// src/pause/pause-core.ts
+import { createHash } from "node:crypto";
+
+// src/step-invocation/types.ts
+import { z as z3 } from "zod";
+var StepPauseRequestSchema = z3.object({
+  reason: z3.string().min(1),
+  kind: z3.enum(["decision", "sleep", "event", "custom"]),
+  payload: z3.record(z3.string(), z3.unknown()).optional(),
+  ttlMs: z3.number().int().positive().optional(),
+  correlationKey: z3.string().min(1).optional(),
+  snapshot: z3.boolean().optional()
+});
+
+class StepExecutionError extends Error {
+  kind;
+  exitCode;
+  constructor(error, stepLabel) {
+    super(`[${error.kind}] ${stepLabel}: ${error.message}`);
+    this.name = "StepExecutionError";
+    this.kind = error.kind;
+    this.exitCode = error.kind === "runner-exit" ? error.exitCode : undefined;
+  }
+}
+
+// src/active-step.ts
+import { AsyncLocalStorage } from "node:async_hooks";
+var activeStepStorage = new AsyncLocalStorage;
+var fallbackActive = null;
+var BRIDGE_KEY = Symbol.for("agent-compose.activeStep.bridge");
+function bridgeSlot() {
+  const g = globalThis;
+  return g[BRIDGE_KEY] ??= { state: null };
+}
+function makeState(step) {
+  return {
+    stepIndex: step.stepIndex,
+    nextAgentCallIndex: 0,
+    pauseOrdinalByScope: new Map
+  };
+}
+function currentState() {
+  return activeStepStorage.getStore() ?? bridgeSlot().state ?? fallbackActive;
+}
+async function runWithActiveStep(step, fn) {
+  return activeStepStorage.run(makeState(step), fn);
+}
+function setActiveStepBridge(step) {
+  const slot = bridgeSlot();
+  const prev = { state: slot.state };
+  slot.state = step ? makeState(step) : null;
+  return prev;
+}
+function restoreActiveStepBridge(prev) {
+  bridgeSlot().state = prev.state;
+}
+function getActiveStep() {
+  const state = currentState();
+  return state ? { stepIndex: state.stepIndex } : null;
+}
+function nextAgentCallInActiveStep() {
+  const state = currentState();
+  if (!state)
+    return null;
+  const callIndex = state.nextAgentCallIndex;
+  state.nextAgentCallIndex += 1;
+  return { stepIndex: state.stepIndex, callIndex };
+}
+function nextPauseOrdinalInActiveStep(scope) {
+  const state = currentState();
+  if (!state)
+    return null;
+  const next = state.pauseOrdinalByScope.get(scope) ?? 0;
+  state.pauseOrdinalByScope.set(scope, next + 1);
+  return next;
+}
+
+// src/pause/state-dir.ts
+import { promises as fs } from "node:fs";
+import { join as join2 } from "node:path";
+import { randomBytes } from "node:crypto";
+function getStateDir() {
+  return process.env.AGENT_COMPOSE_STATE_DIR ?? "/tmp/wf/state";
+}
+var checkpointsDir = () => join2(getStateDir(), "checkpoints");
+var pausesDir = () => join2(getStateDir(), "pauses");
+var agentStatePath = (agentInstanceId) => join2(getStateDir(), `agent-${agentInstanceId}.json`);
+var runtimeStatePath = (agentInstanceId) => join2(getStateDir(), `runtime-${agentInstanceId}.json`);
+var checkpointPath = (name) => join2(checkpointsDir(), `${name}.json`);
+var pausePath = (pauseId) => join2(pausesDir(), `${pauseId}.json`);
+var NAME_RE = /^[a-zA-Z0-9_][a-zA-Z0-9_.-]*$/;
+function assertSafeName(label, name) {
+  if (!NAME_RE.test(name)) {
+    throw new Error(`${label} name must match ${NAME_RE} (got ${JSON.stringify(name)})`);
+  }
+}
+function assertSafeCheckpointName(name) {
+  assertSafeName("checkpoint", name);
+}
+async function ensureDirs() {
+  await fs.mkdir(checkpointsDir(), { recursive: true });
+  await fs.mkdir(pausesDir(), { recursive: true });
+}
+async function atomicWriteJSON(path, value) {
+  await ensureDirs();
+  const tmp = `${path}.tmp.${randomBytes(6).toString("hex")}`;
+  const payload = JSON.stringify(value);
+  if (payload === undefined) {
+    throw new Error("pause state values must be JSON-serialisable");
+  }
+  const handle = await fs.open(tmp, "w");
+  try {
+    await handle.writeFile(payload, { encoding: "utf8" });
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  await fs.rename(tmp, path);
+}
+async function readJSON(path) {
+  try {
+    const raw = await fs.readFile(path, "utf8");
+    return JSON.parse(raw);
+  } catch (err) {
+    if (err.code === "ENOENT")
+      return null;
+    throw err;
+  }
+}
+async function readJSONWithPresence(path) {
+  try {
+    const raw = await fs.readFile(path, "utf8");
+    return { found: true, value: JSON.parse(raw) };
+  } catch (err) {
+    if (err.code === "ENOENT")
+      return { found: false };
+    throw err;
+  }
+}
+async function readAgentState(agentInstanceId) {
+  assertSafeName("agent", agentInstanceId);
+  return readJSON(agentStatePath(agentInstanceId));
+}
+async function writeAgentState(agentInstanceId, state) {
+  assertSafeName("agent", agentInstanceId);
+  await atomicWriteJSON(agentStatePath(agentInstanceId), state);
+}
+async function readRuntimeCheckpoint(agentInstanceId) {
+  assertSafeName("runtime", agentInstanceId);
+  return readJSON(runtimeStatePath(agentInstanceId));
+}
+async function writeRuntimeCheckpoint(agentInstanceId, blob) {
+  assertSafeName("runtime", agentInstanceId);
+  await atomicWriteJSON(runtimeStatePath(agentInstanceId), blob);
+}
+async function readCheckpoint(name) {
+  assertSafeCheckpointName(name);
+  return readJSONWithPresence(checkpointPath(name));
+}
+async function writeCheckpoint(name, value) {
+  assertSafeCheckpointName(name);
+  await atomicWriteJSON(checkpointPath(name), value);
+}
+function hasOwn(obj, key) {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+function validatePauseRecord(value, expectedPauseId) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`pause record ${expectedPauseId} is malformed: expected object`);
+  }
+  const record = value;
+  if (record.pauseId !== undefined && record.pauseId !== expectedPauseId) {
+    throw new Error(`pause record ${expectedPauseId} is malformed: pauseId mismatch`);
+  }
+  if (record.resolved === true) {
+    if (typeof record.expired !== "boolean") {
+      throw new Error(`pause record ${expectedPauseId} is malformed: resolved records require boolean expired`);
+    }
+    if (!hasOwn(record, "resumePayload") || record.resumePayload === undefined) {
+      throw new Error(`pause record ${expectedPauseId} is malformed: resolved records require resumePayload`);
+    }
+    return {
+      pauseId: expectedPauseId,
+      request: hasOwn(record, "request") ? record.request : null,
+      ...record
+    };
+  }
+  if (record.pauseId !== expectedPauseId) {
+    throw new Error(`pause record ${expectedPauseId} is malformed: unresolved records require matching pauseId`);
+  }
+  if (!hasOwn(record, "request") || record.request === undefined) {
+    throw new Error(`pause record ${expectedPauseId} is malformed: unresolved records require request`);
+  }
+  if (record.resolved !== undefined && record.resolved !== false) {
+    throw new Error(`pause record ${expectedPauseId} is malformed: resolved must be true, false, or absent`);
+  }
+  if (hasOwn(record, "expired") || hasOwn(record, "resumePayload")) {
+    throw new Error(`pause record ${expectedPauseId} is malformed: unresolved records must not include resolution fields`);
+  }
+  return record;
+}
+async function readPauseRecord(pauseId) {
+  assertSafeName("pause", pauseId);
+  const record = await readJSON(pausePath(pauseId));
+  return record === null ? null : validatePauseRecord(record, pauseId);
+}
+async function writePauseRecord(record) {
+  assertSafeName("pause", record.pauseId);
+  validatePauseRecord(record, record.pauseId);
+  await atomicWriteJSON(pausePath(record.pauseId), record);
+}
+
+// src/pause/errors.ts
+class PauseError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = new.target.name;
+  }
+}
+
+class PauseExpiredError extends PauseError {
+  code = "pause_expired";
+  constructor(message = "pause expired before it was resolved") {
+    super(message);
+  }
+}
+
+class PauseSchemaError extends PauseError {
+  code = "pause_schema";
+  issues;
+  constructor(message, issues) {
+    super(message);
+    this.issues = issues;
+  }
+}
+
+class PauseRequestError extends PauseError {
+  code = "pause_request";
+  constructor(message = "pause request is invalid") {
+    super(message);
+  }
+}
+
+// src/pause/pause-core.ts
+var PAUSE_SIGNAL_BRAND = Symbol.for("agent-compose.PauseSignal");
+
+class PauseSignal {
+  pauseId;
+  pauseRequest;
+  observability;
+  [PAUSE_SIGNAL_BRAND] = true;
+  constructor(pauseId, pauseRequest, observability) {
+    this.pauseId = pauseId;
+    this.pauseRequest = pauseRequest;
+    this.observability = observability;
+  }
+}
+function isPauseSignal(err) {
+  return typeof err === "object" && err !== null && err[PAUSE_SIGNAL_BRAND] === true;
+}
+function boundProcessorPause(boundary, scope) {
+  return (req) => {
+    if (!boundary) {
+      return Promise.reject(new PauseRequestError("ctx.pause is unavailable here: no pause boundary is wired (a processor can " + "only pause inside a sandboxed workflow step, not in a local/unit-test run)"));
+    }
+    return boundary(req, scope);
+  };
+}
+var PAUSE_NAMESPACE = "5f3e2b8a-0c41-4e9d-9a7b-6d2c1f8e3a40";
+function uuidToBytes(uuid) {
+  return Buffer.from(uuid.replace(/-/g, ""), "hex");
+}
+function bytesToUuid(b) {
+  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)}`;
+}
+function uuidv5(name, namespace) {
+  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] & 15 | 80;
+  bytes[8] = bytes[8] & 63 | 128;
+  return bytesToUuid(bytes);
+}
+function scopeOf(coord) {
+  return coord.agentScope ? `${coord.runId}:${coord.stepIndex}:${coord.agentScope.agentId}:${coord.agentScope.iteration}` : `${coord.runId}:${coord.stepIndex}:bare`;
+}
+var pauseOrdinalByScope = new Map;
+function nextPauseOrdinal(scope) {
+  const activeOrdinal = nextPauseOrdinalInActiveStep(scope);
+  if (activeOrdinal !== null)
+    return activeOrdinal;
+  const next = pauseOrdinalByScope.get(scope) ?? 0;
+  pauseOrdinalByScope.set(scope, next + 1);
+  return next;
+}
+function nextPauseId(coord) {
+  const scope = scopeOf(coord);
+  const ordinal = nextPauseOrdinal(scope);
+  return uuidv5(`${scope}:${ordinal}`, PAUSE_NAMESPACE);
+}
+function nonJsonPath(value, path = "$", seen = new Set) {
+  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;
+  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[key], `${path}.${key}`, seen);
+    if (child)
+      return child;
+  }
+  seen.delete(obj);
+  return null;
+}
+function toWireRequest(req, kind) {
+  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;
+}
+async function corePause(req, coord, kind = "custom") {
+  const wire = toWireRequest(req, kind);
+  const pauseId = nextPauseId(coord);
+  const record = await readPauseRecord(pauseId);
+  if (record === null || record.resolved !== true) {
+    await writePauseRecord({ pauseId, request: wire });
+    throw new PauseSignal(pauseId, wire);
+  }
+  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`);
+  }
+  const payload = record.resumePayload ?? null;
+  if (req.schema) {
+    const parsed = req.schema.safeParse(payload);
+    if (!parsed.success) {
+      throw new PauseSchemaError(`resume payload for pause "${req.reason}" failed schema validation: ${parsed.error.message}`, parsed.error.issues);
+    }
+    return parsed.data;
+  }
+  return payload;
+}
+
 // src/utils/errors.ts
 function formatError(err) {
   return err instanceof Error ? err.message : String(err);
@@ -441,12 +826,14 @@ class VercelRunner {
             apiKeyScopes: [],
             parentRunId: null
           });
+          const gateAgentId = this.options.agentId ?? "agent";
           const gate = await this.gateToolCall(call, {
             requestContext,
             abortSignal: execOpts.abortSignal ?? signal ?? new AbortController().signal,
             retryCount: 0,
-            agentId: this.options.agentId ?? "agent",
-            iteration
+            agentId: gateAgentId,
+            iteration,
+            pause: boundProcessorPause(this.options.pause, { agentId: gateAgentId, iteration })
           });
           if (gate.kind === "deny")
             return gate.reason;

package/dist/sandbox.d.ts

@@ -5,30 +5,35 @@
  * Each provider validates its required env vars at creation time.
  */
 import { Sandbox } from "e2b";
+import type { SandboxNetworkOpts as E2bNetworkOpts } from "e2b";
 import { Sandbox as Desktop } from "@e2b/desktop";
 import type { SandboxProvider, DesktopSandboxProvider, SandboxCommandResult } from "./types/sandbox.js";
 import type { ConnectorRequestRules } from "./types/workflow-metadata.js";
 import type { NetworkPolicy as VercelNetworkPolicy } from "@vercel/sandbox";
-export type { SandboxProvider, DesktopSandboxProvider, SandboxCommandRunOptions, SandboxCommandResult } from "./types/sandbox.js";
+export type { SandboxProvider, DesktopSandboxProvider, SandboxCommandRunOptions, SandboxCommandResult, SandboxDuplexProcess, SandboxSpawnDuplexOptions } from "./types/sandbox.js";
 export type SandboxProviderName = "vercel" | "e2b" | "e2b-desktop";
 export declare const AGENT_COMPOSE_TAG: string;
 /**
  * Network policy for outbound HTTPS requests — ONE shape for every provider;
  * only the enforcement point differs. When a sandbox makes a request matching
  * a domain in `allow`, the egress layer injects the specified headers before
- * forwarding — credentials never exist inside the VM. Vercel's firewall
- * enforces this natively (`requestRules` translate to native `match` rules);
- * E2B enforces it via the embedded iron-proxy, which pulls the identical
- * resolved policy from the server.
+ * forwarding — credentials never exist inside the VM. Both providers enforce
+ * this natively at the platform edge from the resolved policy passed at
+ * create: Vercel via its firewall (`requestRules` translate to native `match`
+ * rules), E2B via its native network firewall (`toE2bNetwork` →
+ * `allowOut`/`denyOut`/`rules`). See `toVercelNetworkPolicy` / `toE2bNetwork`.
  */
 export interface SandboxNetworkHeaderTransform {
     headers?: Record<string, string>;
 }
 export interface SandboxNetworkAllowRule {
     transform?: SandboxNetworkHeaderTransform[];
-    /** Tier-2 request gate (method/path) — the transform (and, on iron-proxy,
-     *  the request itself) only applies when the request matches. Present on
-     *  connector-auth rules; see `ConnectorRequestRules`. */
+    /** Tier-2 request gate (method/path) — the transform only applies when the
+     *  request matches. Honoured on Vercel (translated to native `match` rules).
+     *  NOT honoured on E2B: its native rules carry only a `transform`, no
+     *  method/path matcher, so a brokered credential rides ALL requests to an
+     *  allowed host there (see `toE2bNetwork`). Present on connector-auth rules;
+     *  see `ConnectorRequestRules`. */
     requestRules?: ConnectorRequestRules;
 }
 export interface SandboxNetworkSubnetPolicy {
@@ -54,12 +59,56 @@ export type SandboxSize = "2vcpu-4gb" | "4vcpu-8gb" | "8vcpu-16gb" | "32vcpu-64g
 /** SKU → Vercel vCPU count (RAM follows at 2048 MB/vCPU). */
 export declare const SANDBOX_VCPUS: Record<SandboxSize, number>;
 /** SDK fallback size when neither the caller nor the deployment specifies one.
- *  Deliberately conservative — the OPERATIONAL default is chosen per-environment
- *  by the server via the `SANDBOX_DEFAULT_SIZE` env var (prod = Enterprise →
- *  `32vcpu-64gb`; dev = `8vcpu-16gb`, since the dev account caps at 8 vCPU).
- *  TODO(sandbox-size): the prod default is temporarily `32vcpu-64gb` for a
- *  memory-hungry workload — lower it back when no longer needed. */
+ *  Deliberately conservative — the OPERATIONAL default is the server's
+ *  `SANDBOX_DEFAULT_SIZE` env var (now also `2vcpu-4gb`). Keeping the default
+ *  small matters because Vercel rate-limits creation by vCPUs-per-window
+ *  (`api-sandboxes-vcpus-creation`); a large default 429s bursty/simultaneous
+ *  creates. Workloads that need more RAM/CPU declare `resources.size` on the
+ *  workflow rather than inflating the default for everyone. */
 export declare const DEFAULT_SANDBOX_SIZE: SandboxSize;
+/** The E2B sizes we pre-build a template for. E2B sizing is template-baked
+ *  (no per-create cpu/mem knob), so honouring `resources.size` on E2B means
+ *  ONE pre-built template per size. `32vcpu-64gb` is absent (E2B has no
+ *  >8-vCPU equivalent). `8vcpu-16gb` is also absent: it needs 16 GiB RAM, but
+ *  the E2B account caps memory at 8 GiB (`Template.build` 400s with
+ *  "Memory can't be higher than 8192 MiB"). Add it back here (and rebuild the
+ *  templates) only once the account's memory limit is raised. The register/
+ *  invoke guards reject an unsupported E2B size before it can reach here. */
+export declare const E2B_TEMPLATE_SIZES: readonly SandboxSize[];
+/** Is `size` one E2B can be built/booted at? `32vcpu-64gb` (no >8-vCPU E2B
+ *  equivalent) and `8vcpu-16gb` (exceeds the account's 8 GiB memory cap) are
+ *  not — the guards lean on this so the "no E2B equivalent" decision lives in
+ *  exactly one place. */
+export declare function isE2bSupportedSize(size: SandboxSize): boolean;
+/** Machine spec for a SandboxSize, in the shape `Template.build` wants. RAM is
+ *  always 2048 MB/vCPU, matching the size name + Vercel parity
+ *  (`SANDBOX_VCPUS` × 2048). Used by `infra/e2b-template/build.ts` to stamp the
+ *  per-size base + agent-env templates. */
+export declare function e2bMachineSpec(size: SandboxSize): {
+    cpuCount: number;
+    memoryMB: number;
+};
+/** Stable E2B template ALIAS for the platform base at a given size
+ *  (`agent-compose-base-<size>`). Aliases — not snapshot ids — so the refs are
+ *  multi-account-clean: the same string resolves in any E2B account that built
+ *  the templates. Built by `infra/e2b-template/build.ts`; the E2B provider
+ *  boots this when a run on E2B declares no explicit `bootFrom`/template. */
+export declare function e2bBaseTemplate(size: SandboxSize): string;
+/** Stable E2B template ALIAS for the agent runtime (base + claude binary) at a
+ *  given size (`agent-env-<size>`). The agent default templates boot from this
+ *  via `bootFrom: { snapshotId: e2bAgentEnvTemplate(size) }`. Multi-account-clean
+ *  for the same reason as `e2bBaseTemplate`. */
+export declare function e2bAgentEnvTemplate(size: SandboxSize): string;
+/** Is `id` one of the platform-managed E2B template aliases — a
+ *  `agent-compose-base-<size>` or `agent-env-<size>` for a supported size?
+ *
+ *  These are stable, platform-built, multi-account-clean strings (NOT tenant
+ *  captures), so any workflow may boot from them: the same alias resolves to
+ *  the same platform base in every account, and there is no tenant data behind
+ *  it to leak. The dispatch snapshot gate uses this to vouch a platform E2B
+ *  boot alias without it having to be a team-owned capture or a published
+ *  template's bootFrom. */
+export declare function isPlatformE2bTemplateAlias(id: string): boolean;
 export interface SandboxCreateOpts {
     envs: Record<string, string>;
     metadata: Record<string, string>;
@@ -71,12 +120,10 @@ export interface SandboxCreateOpts {
      *  (size is template-defined). Omit → `DEFAULT_SANDBOX_SIZE`. */
     size?: SandboxSize;
     /** Outbound request policy with header transforms — ONE shape for every
-     *  provider; only the enforcement point differs. Vercel's firewall
-     *  enforces + injects natively from this value. E2B enforces it via an
-     *  EMBEDDED iron-proxy inside the VM (loopback DNS + iptables, started
-     *  at boot), which fetches the identical resolved policy from the
-     *  server's per-run egress-policy endpoint — so this field is not passed
-     *  to E2B's API. See server/src/sandbox/iron-proxy.ts. */
+     *  provider; only the enforcement point differs. Both providers enforce +
+     *  inject natively at create from this value: Vercel via its firewall
+     *  (`toVercelNetworkPolicy`), E2B via its native network firewall
+     *  (`toE2bNetwork` → `network: { allowOut, denyOut, rules }`). */
     networkPolicy?: SandboxNetworkPolicy;
 }
 /**
@@ -120,6 +167,16 @@ interface SandboxProviderDef {
      * up eventually by the provider's own retention.
      */
     deleteSnapshot?: (snapshotId: string, env: Record<string, string>) => Promise<void>;
+    /**
+     * Does this snapshot id resolve on the provider for this account? A cheap
+     * metadata lookup — NEVER provisions a sandbox. Used at server boot to
+     * validate that the platform base snapshots the default templates boot from
+     * actually exist for this deployment (catching e.g. a dev-account snapshot
+     * baked into prod). Returns true if it resolves, false if the provider
+     * reports it does not exist. Transport/credential errors PROPAGATE — an
+     * indeterminate result must not be reported as "missing".
+     */
+    snapshotExists?: (snapshotId: string, env: Record<string, string>) => Promise<boolean>;
 }
 export declare function makeSandboxProvider(sb: Sandbox | Desktop): SandboxProvider;
 export declare function makeDesktopSandboxProvider(sb: Desktop): DesktopSandboxProvider;
@@ -164,6 +221,35 @@ export declare const DOT_SEGMENT_PATH_RE2 = ".*(?:^|/|%2[fF])(?:\\.|%2[eE]){2}(?
  * method/path combinations. Pinned by vercel-network-policy.test.ts.
  */
 export declare function toVercelNetworkPolicy(policy: SandboxNetworkPolicy): VercelNetworkPolicy;
+/**
+ * Translate our policy shape into E2B's native `network` config
+ * (`SandboxNetworkOpts`) — the E2B analogue of `toVercelNetworkPolicy`.
+ *
+ *   - `allowOut`: the set of allowed egress targets — every host named in
+ *     `allow` PLUS every CIDR in `subnets.allow`. The Archil raw-TCP
+ *     data-plane CIDRs ride here as FIRST-CLASS allow entries (E2B has no
+ *     root-exemption to lean on, unlike the old in-VM iptables model).
+ *   - `denyOut`: the all-traffic sentinel (`0.0.0.0/0`) so the policy is
+ *     DEFAULT-DENY — only `allowOut` targets pass. E2B applies allow before
+ *     deny, so a host in both lists is allowed.
+ *   - `rules`: per-host header injection. For each host carrying transform(s),
+ *     emit one rule per transform with `{ transform: { headers } }`. A host
+ *     with a rule MUST also be in `allowOut` (registering a rule does not
+ *     grant egress on its own — E2B's API requires the host in `allowOut`).
+ *
+ * BEHAVIOURAL DIVERGENCE FROM iron-proxy / Vercel — path/method gating is NOT
+ * available on E2B native rules. An `SandboxNetworkRule` carries only a
+ * `transform` (header injection); there is no method/path matcher. So our
+ * Tier-2 `requestRules` (`{ methods, pathPrefixes }`) cannot be enforced here:
+ * a brokered credential rides EVERY request to an allowed host on E2B, whereas
+ * Vercel (native `match`) and the old iron-proxy gated it to the declared
+ * method+path. The host allowlist still confines WHICH hosts the credential
+ * can reach; it just can't narrow to a method/path within an allowed host.
+ *
+ * String policies map straight through: "allow-all" → no restriction (omit
+ * `allowOut`/`denyOut`), "deny-all" → block all egress.
+ */
+export declare function toE2bNetwork(policy: SandboxNetworkPolicy): E2bNetworkOpts;
 /** Vercel caps sandbox tags at 5. Build the tag set with the fleet `executor`
  *  tag always present and always winning over caller metadata — `listOwned` /
  *  orphan reconciliation scope on it, so a clobbered or dropped executor tag
@@ -186,6 +272,14 @@ export declare function createSandbox(provider: SandboxProviderName, opts: Sandb
 export declare function reconnectSandbox(provider: SandboxProviderName, sandboxId: string): Promise<SandboxProvider>;
 /** Delete a snapshot by id on the named provider. No live sandbox needed. */
 export declare function deleteSandboxSnapshot(provider: SandboxProviderName, snapshotId: string): Promise<void>;
+/**
+ * Does `snapshotId` resolve on the named provider for this account? A cheap
+ * metadata lookup — never provisions a sandbox. `true` = resolves, `false` =
+ * provider says it does not exist. Transport/credential errors propagate (an
+ * indeterminate result is not "missing"). Used at server boot to validate the
+ * platform base snapshots the default templates boot from.
+ */
+export declare function snapshotResolves(provider: SandboxProviderName, snapshotId: string): Promise<boolean>;
 /**
  * Current active-sandbox count per configured provider, for quota gauges.
  * Skips providers whose required env isn't set or which don't implement

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

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

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

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

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

@@ -65,4 +65,40 @@ export interface InvokeStepOptions {
     onStdout?: (line: string) => void;
     onStderr?: (line: string) => void;
 }
+/** A step running as a background command (ADR-0028). The activity races its
+ *  `wait()` against a server pause request; on a pause it freezes the VM
+ *  (`pauseProcess`) and persists `runnerPid` + `resultToken` so the resume
+ *  activity can `reconnectStep(...)` to the SAME process — no re-run. */
+export interface RunningStep<TOutput = unknown> {
+    /** OS pid of the background runner inside the VM — the reconnect handle. */
+    runnerPid: number;
+    /** Per-invocation token keying the durable result file the runner writes. */
+    resultToken: string;
+    /** Await the runner's exit and classify its output into a `StepResult`. */
+    wait(): Promise<StepResult<TOutput>>;
+}
 export declare function invokeStep<TOutput = unknown>(sandbox: SandboxProvider, request: StepRequest, opts?: InvokeStepOptions): Promise<StepResult<TOutput>>;
+/**
+ * Launch the step runner as a BACKGROUND command (ADR-0028) and return a handle
+ * the activity drives: it races `wait()` against a server pause request and, on
+ * a pause, freezes the VM (`pauseProcess`) and persists `runnerPid` +
+ * `resultToken` so `reconnectStep` can continue the SAME process — no re-run.
+ * Requires a provider with `commands.runBackground` (E2B); the foreground
+ * `invokeStep` is the path for providers without it (Vercel).
+ */
+export declare function launchStep<TOutput = unknown>(sandbox: SandboxProvider, request: StepRequest, opts?: InvokeStepOptions): Promise<RunningStep<TOutput>>;
+/**
+ * Resume a previously-paused background runner (ADR-0028) and return a
+ * `RunningStep` handle — uniform with `launchStep` so the activity can race
+ * `wait()` against a fresh pause request (a resumed step can pause again). After
+ * the workflow reconnects the suspended VM (`Sandbox.connect` auto-resumes it),
+ * this re-attaches to the still-running runner by `runnerPid`; `wait()` awaits
+ * its exit (event-driven — no polling) and classifies the output (the durable
+ * result file is authoritative on this path). If the runner already exited
+ * during resume, the re-attach fails and `wait()` classifies from the file.
+ */
+export declare function reconnectStep<TOutput = unknown>(sandbox: SandboxProvider, resume: {
+    runnerPid: number;
+    resultToken: string;
+    stepIndex: number;
+}, opts?: Pick<InvokeStepOptions, "onStdout" | "onStderr">): Promise<RunningStep<TOutput>>;

package/dist/types/__tests__/environment-build-flag.test.d.ts

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

package/dist/types/__tests__/workflow-metadata-provider.test.d.ts

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

package/dist/types/execution-context.d.ts

@@ -21,14 +21,6 @@ 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