@agent-compose/sdk 0.5.7 → 0.5.9

package/src/step-invocation/types.ts

@@ -43,7 +43,7 @@ export type StepResult<TOutput = unknown> =
  *  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` /
+ *  the engine needs): the SDK wrapper layer (`sleep` /
  *  `sleep` / `waitForEvent`) owns its own payload contract, and the
  *  engine treats `payload` as opaque. */
 export const StepPauseRequestSchema = z.object({

package/src/types/execution-context.ts

@@ -3,7 +3,7 @@
 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 { WaitForEventRequest } from "../pause/wrappers.js";
 import type { SandboxProvider } from "./sandbox.js";
 
 /** The identity of this workflow run. */
@@ -29,14 +29,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
@@ -46,8 +38,6 @@ export interface BaseExecutionContext {
    * 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`. */

package/src/types/protocol.ts

@@ -33,6 +33,16 @@ export interface AgentMessageToolResult extends AgentMessageBase {
   toolUseId: string;
   output: string;
   isError: boolean;
+  /** Structured file diffs produced by the tool call, carried alongside the
+   *  rendered `output` so a richer renderer can use the structure without
+   *  re-plumbing the normaliser. Sourced from ACP `tool_call`/`tool_call_update`
+   *  `diff` content blocks (WS-C / ADR-0020 Q3). Optional and additive:
+   *  existing producers (claude / vercel / legacy JSONL) omit it. `oldText` is
+   *  null for a newly created file. */
+  diffs?: { path: string; oldText: string | null; newText: string }[];
+  /** File locations touched by the tool call (ACP `locations` field), enabling
+   *  "follow-along" UI. Optional and additive (WS-C / ADR-0020 Q3). */
+  locations?: { path: string; line?: number }[];
 }
 
 export interface AgentMessageDone extends AgentMessageBase {
@@ -55,6 +65,21 @@ export interface AgentMessageUsage extends AgentMessageBase {
   numTurns: number;
 }
 
+/** Structured execution plan emitted by an agent (ACP `plan` session update,
+ *  WS-C / ADR-0020 Q2). Each `plan` notification REPLACES the whole plan — the
+ *  normaliser emits one `AgentMessagePlan` per notification carrying the entire
+ *  `entries` array, and downstream treats the latest as authoritative. This is
+ *  NOT an `AgentStatus` and does not feed self-pause; it is observability only.
+ *  Additive 9th kind: existing producers never emit it. */
+export interface AgentMessagePlan extends AgentMessageBase {
+  type: "plan";
+  entries: {
+    content: string;
+    priority: "high" | "medium" | "low";
+    status: "pending" | "in_progress" | "completed";
+  }[];
+}
+
 export type AgentMessage =
   | AgentMessageInit
   | AgentMessageText
@@ -63,7 +88,8 @@ export type AgentMessage =
   | AgentMessageToolResult
   | AgentMessageDone
   | AgentMessageError
-  | AgentMessageUsage;
+  | AgentMessageUsage
+  | AgentMessagePlan;
 
 /** Status block the agent emits to signal iteration completion or blockers. */
 export interface AgentStatus {

package/src/types/runtime.ts

@@ -5,6 +5,7 @@
 import type { SandboxProvider } from "./sandbox.js";
 import type { AgentMessage } from "./protocol.js";
 import type { Processor, ProcessorContext, ToolCall } from "../processors/processor.js";
+import type { BoundaryPauseFn } from "../pause/pause-core.js";
 import type { RequestContext } from "../request-context/request-context.js";
 
 /** Configuration for a single MCP server. */
@@ -31,6 +32,12 @@ export interface RuntimeOptions {
   /** Agent id and label for processor context / adapter logs. */
   agentId?: string;
   iteration?: number;
+  /** The run's pause boundary, threaded from the agent loop so a runtime-driven
+   *  pre-tool gate (e.g. the ACP `session/request_permission` path through
+   *  `gateToolCall`) can raise a human-approval `ctx.pause`. The runtime binds it
+   *  to the current `{ agentId, iteration }` when it builds a ProcessorContext.
+   *  Absent ⇒ a processor pause throws (no boundary; see `boundProcessorPause`). */
+  pause?: BoundaryPauseFn;
   /** Optional JSON schema for runtimes with native structured-output support. */
   outputFormat?: { type: "json_schema"; schema: Record<string, unknown> };
 }

package/src/types/sandbox-environment.ts

@@ -37,7 +37,7 @@
 import type { SandboxProvider } from "./sandbox.js";
 import { defineWorkflow } from "./workflow.js";
 import type { Workflow } from "../workflow-steps/types.js";
-import type { SnapshotConfig } from "./workflow-metadata.js";
+import type { SandboxResources, SnapshotConfig } from "./workflow-metadata.js";
 
 export interface SandboxEnvironmentDefinition {
   name: string;
@@ -48,6 +48,11 @@ export interface SandboxEnvironmentDefinition {
    *  useful — an env with no snapshot can't be referenced as a
    *  `bootFrom` on another workflow). */
   snapshots?: SnapshotConfig;
+  /** Which substrate to build this environment on (and any sizing).
+   *  An env image is provider-specific — a snapshot captured on E2B
+   *  can't boot on Vercel and vice-versa — so building the E2B base/
+   *  agent-env requires `resources: { provider: "e2b" }`. */
+  resources?: SandboxResources;
 }
 
 /** Sugar over `defineWorkflow` for setup-only workflows that exist to
@@ -61,7 +66,13 @@ export function defineSandboxEnvironment(
   }
   return defineWorkflow<void, Record<string, unknown>>({
     ...(env.description !== undefined ? { description: env.description } : {}),
+    ...(env.resources !== undefined ? { resources: env.resources } : {}),
     snapshots: env.snapshots ?? { saveLatest: true },
+    // Mark this as an environment build so the server skips the /factory mount
+    // for its runs — an env build builds a platform image and never touches the
+    // shared drive; baking a live Archil mount into its snapshot breaks the
+    // re-mount of every workflow that later boots from it (#13).
+    environmentBuild: true,
     run: async (_ctx, sandbox) => env.setup(sandbox),
   });
 }

package/src/types/sandbox.ts

@@ -25,6 +25,35 @@ export interface SandboxCommandResult {
   stderr: string;
 }
 
+/** A spawned long-lived command with a writable stdin and readable stdout,
+ *  exposed as byte web-streams. Unlike `commands.run` (which buffers to
+ *  completion and exposes stdout only via an `onStdout` callback), a duplex
+ *  handle keeps the process alive and lets the caller WRITE to its stdin —
+ *  the half `commands.run` cannot provide. It is the transport the ACP client
+ *  (`AcpClientPeer` over `ndJsonStream`) needs: the agent CLI reads JSON-RPC
+ *  request frames on stdin and answers on stdout.
+ *
+ *  Only `makeLocalSandboxProvider` implements it. The runner runs IN the
+ *  sandbox VM and spawns CLIs via the local provider (a plain `child_process`
+ *  pipe), so a duplex stdin works identically on Vercel/E2B/local. The
+ *  vercel/e2b providers are the SERVER→sandbox view and never spawn the in-VM
+ *  CLI, so they leave `spawnDuplex` undefined and callers fall back cleanly. */
+export interface SandboxDuplexProcess {
+  /** Subprocess stdin. JSON-RPC request frames are written here. */
+  stdin: WritableStream<Uint8Array>;
+  /** Subprocess stdout. JSON-RPC response/notification frames arrive here. */
+  stdout: ReadableStream<Uint8Array>;
+  /** Resolves when the subprocess exits, carrying the captured stderr tail. */
+  exited: Promise<{ exitCode: number; stderr: string }>;
+  /** Force-terminate the subprocess. */
+  kill(): void;
+}
+
+export interface SandboxSpawnDuplexOptions {
+  cwd?: string;
+  envs?: Record<string, string>;
+}
+
 /**
  * A sandbox provider implements the RAW provider operations only. It does NOT
  * implement transient-failure retry/backoff: reconnecting and snapshotting both
@@ -51,6 +80,11 @@ export interface SandboxProvider {
     // `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>;
+    /** Spawn a long-lived command with a real duplex stdin/stdout. OPTIONAL —
+     *  implemented only by `makeLocalSandboxProvider` (the in-VM `child_process`
+     *  view). The vercel/e2b providers (server→sandbox) leave it undefined; an
+     *  ACP caller that finds it absent falls back to the JSONL transport. */
+    spawnDuplex?(cmd: string, opts?: SandboxSpawnDuplexOptions): SandboxDuplexProcess;
   };
   files: {
     write(path: string, content: string): Promise<void>;
@@ -65,12 +99,12 @@ export interface SandboxProvider {
    *  be omitted when the provider doesn't expose it; the server stores
    *  `null` for missing values rather than estimating. */
   snapshot?(): Promise<{ snapshotId: string; sizeBytes?: number }>;
-  /** Replace the live sandbox's egress policy in place. Vercel implements
-   *  it via `sandbox.update({ networkPolicy })` (2.x) so the server can
-   *  push a freshly resolved policy — with re-minted connector access
-   *  tokens — before each step instead of relying on the policy baked at
-   *  create. Providers whose enforcement lives inside the VM (E2B
-   *  iron-proxy) leave it undefined. */
+  /** Replace the live sandbox's egress policy in place — so the server can
+   *  push a freshly resolved policy (with re-minted connector access tokens)
+   *  before each step instead of relying on the policy baked at create.
+   *  Vercel implements it via `sandbox.update({ networkPolicy })` (2.x); E2B
+   *  via its native `sandbox.updateNetwork(...)`. Providers without a live
+   *  network-update primitive leave it undefined. */
   updateNetworkPolicy?(policy: SandboxNetworkPolicy): Promise<void>;
 }
 

package/src/types/workflow-metadata.ts

@@ -9,9 +9,15 @@
  * `workflow-steps/workflow.ts` — it is the cycle-break point.
  */
 
-import type { SandboxNetworkPolicy } from "../sandbox.js";
+import type { SandboxNetworkPolicy, SandboxSize, SandboxProviderName } from "../sandbox.js";
 import type { Processor } from "../processors/processor.js";
 
+/** The sandbox providers selectable per-workflow. A narrowing of
+ *  `SandboxProviderName` to the two substrates that execute step workloads —
+ *  `e2b-desktop` (registry-only, never a workflow's runtime) is deliberately
+ *  excluded so a workflow can only ask for a substrate that actually runs steps. */
+export type WorkflowSandboxProvider = Extract<SandboxProviderName, "vercel" | "e2b">;
+
 /**
  * Workflow-level metadata read by the server at registration. Lives on
  * every `Workflow` as `workflow.metadata`, regardless of which form of
@@ -77,11 +83,14 @@ export interface IOSchema {
  *  output-only release. New code should prefer `IOSchema`. */
 export type OutputSchema = IOSchema;
 
-/** Per-connector HTTP request matcher (Tier-2 capability narrowing). The
- *  iron-proxy / firewall consults these when deciding whether to attach the
- *  brokered Authorization header to an outbound request. A request to the
- *  connector host whose method is not in `methods`, or whose path matches no
- *  entry in `pathPrefixes`, is refused (403) and the token is WITHHELD. */
+/** Per-connector HTTP request matcher (Tier-2 capability narrowing). Vercel's
+ *  firewall consults these when deciding whether to attach the brokered
+ *  Authorization header to an outbound request: a request to the connector
+ *  host whose method is not in `methods`, or whose path matches no entry in
+ *  `pathPrefixes`, goes out WITHOUT the token. NOT enforced on E2B — its
+ *  native rules carry only a header transform, no method/path matcher, so the
+ *  token rides every request to an allowed connector host there (the host
+ *  allowlist still confines which hosts are reachable). See `toE2bNetwork`. */
 export interface ConnectorRequestRules {
   /** Allowed HTTP methods (upper-case). Omit = any method (subject to
    *  `access`). */
@@ -141,6 +150,25 @@ export interface InvokePolicy {
   workflows?: string[];
 }
 
+/** Sandbox machine resources for a workflow's runs. A coarse size knob
+ *  today; kept as its own object so finer controls (disk, gpu, …) can be
+ *  added later without reshaping `WorkflowMetadata`. */
+export interface SandboxResources {
+  /** Machine hardware SKU — one of the `SandboxSize` vCPU strings
+   *  (`2vcpu-4gb` | `4vcpu-8gb` | `8vcpu-16gb` | `32vcpu-64gb`). Maps to
+   *  provider specs at create time (Vercel: 2 / 4 / 8 / 32 vCPU, 2048 MB RAM
+   *  per vCPU). Omit → the smallest SKU. E2B sizing is template-defined and
+   *  ignores this. */
+  size?: SandboxSize;
+  /** Sandbox provider this workflow's runs execute on — `"vercel"` or
+   *  `"e2b"`. Optional and additive: omit and the run resolves to the
+   *  platform default (`vercel`). Set explicitly to pin a workflow to a
+   *  substrate regardless of the deployment default. Snapshot formats are
+   *  provider-specific, so the resolved provider is stamped on the run row
+   *  at first dispatch and reused across pause/resume/replay. */
+  provider?: WorkflowSandboxProvider;
+}
+
 export interface WorkflowMetadata {
   /** One-line, human-readable description of what the workflow does.
    *  Surfaced on the dashboard template tile + run page header. Authors
@@ -161,6 +189,9 @@ export interface WorkflowMetadata {
   outputSchema?: IOSchema;
   /** All snapshot config — boot source + capture mode. */
   snapshots?:     SnapshotConfig;
+  /** Sandbox machine resources — size + provider. Optional; omit → smallest
+   *  SKU on the platform-default provider (`vercel`). */
+  resources?:     SandboxResources;
   processors?:    readonly Processor[];
   /** Connector requirements — providers whose APIs this workflow calls.
    *  Dispatch resolves an authorized grant per provider and injects a
@@ -172,6 +203,18 @@ export interface WorkflowMetadata {
   /** Tier-1 invoke ACL — who may dispatch this connector-brokering workflow.
    *  See `InvokePolicy`. */
   invokePolicy?: InvokePolicy;
+  /** Set by `defineSandboxEnvironment` to mark this workflow as an ENVIRONMENT
+   *  BUILD — a setup-only workflow whose job is to leave its VM configured and
+   *  snapshot it (base-env / agent-env). Environment builds build a platform
+   *  IMAGE and never use the shared factory drive, so the server SKIPS mounting
+   *  /factory for them: a live Archil mount baked into the captured snapshot
+   *  fails the NEXT boot's re-mount ("an older Archil process is still running
+   *  for this mountpoint"), degrading /factory for every workflow booting from
+   *  that snapshot. Absent on ordinary workflows — which mount /factory exactly
+   *  as before. Optional + additive: an ABSENT flag contributes nothing to the
+   *  canonical metadata hash (frozen-metadata rule), so existing workflows are
+   *  not forced to re-register. */
+  environmentBuild?: boolean;
 }
 
 /**
@@ -198,10 +241,12 @@ export function extractMetadata(source: Partial<WorkflowMetadata>): WorkflowMeta
   if (source.inputSchema   !== undefined) out.inputSchema   = freezeMetadataValue(source.inputSchema);
   if (source.outputSchema  !== undefined) out.outputSchema  = freezeMetadataValue(source.outputSchema);
   if (source.snapshots     !== undefined) out.snapshots     = Object.freeze({ ...source.snapshots });
+  if (source.resources     !== undefined) out.resources     = Object.freeze({ ...source.resources });
   if (source.processors    !== undefined) out.processors    = Object.freeze([...source.processors]);
   if (source.connectors        !== undefined) out.connectors        = freezeMetadataValue(source.connectors);
   if (source.connectorOperation !== undefined) out.connectorOperation = Object.freeze({ ...source.connectorOperation });
   if (source.invokePolicy       !== undefined) out.invokePolicy       = freezeMetadataValue(source.invokePolicy);
+  if (source.environmentBuild   !== undefined) out.environmentBuild   = source.environmentBuild;
   return Object.freeze(out);
 }
 

package/src/types/workflow.ts

@@ -37,8 +37,8 @@ export interface AgentEventSink {
   emit(event: AgentLifecycleEvent): void | Promise<void>;
 }
 
-import type { SnapshotConfig, BootSnapshot, ReuseSnapshot, IOSchema, OutputSchema } from "./workflow-metadata.js";
-export type { SnapshotConfig, BootSnapshot, ReuseSnapshot, IOSchema, OutputSchema };
+import type { SnapshotConfig, BootSnapshot, ReuseSnapshot, IOSchema, OutputSchema, SandboxResources } from "./workflow-metadata.js";
+export type { SnapshotConfig, BootSnapshot, ReuseSnapshot, IOSchema, OutputSchema, SandboxResources };
 
 /** Turn/iteration budget for `agent(opts)`. Re-exported here so authors
  *  can type per-invoke budget overrides they pass as workflow input. */
@@ -53,9 +53,16 @@ export interface WorkflowCtx<TInput extends Record<string, unknown> = Record<str
   /** Persist key-value metadata on the run record (e.g. prUrl, planUrl). */
   setMetadata: (data: Record<string, unknown>) => Promise<void>;
   /**
-   * Wrap a named step for observability. Emits step_started / step_completed /
-   * step_failed lifecycle events with duration. Use for long phases you want
+   * Durable named step (ADR-0012). Runs `fn` once and memoises its result to
+   * the sandbox state-dir; on a pause-resume re-entry the recorded value is
+   * returned and `fn` is NOT re-run (a duration-0 "restored" sub-step). Also
+   * emits substep_started / substep_completed / substep_failed lifecycle
+   * events with duration — use for long phases you want both durable and
    * visible on the run's timeline (setup, external API calls, submit).
+   *
+   * Names must be unique within a step body (they key the memoise file).
+   * A body that pauses is never memoised — the resume re-runs it. For
+   * cross-process side effects (DB writes, emails) use `invokeChild`.
    */
   step<T>(name: string, fn: () => Promise<T>): Promise<T>;
   /** Pass to `agent({ events: ctx.agentEvents })` to stream agent lifecycle events. */
@@ -120,6 +127,15 @@ export interface WorkflowDefinition<
    * `invoke({ snapshots })` overrides this default.
    */
   snapshots?: SnapshotConfig;
+  /**
+   * Sandbox resources — machine SKU (`size`, a `SandboxSize` vCPU string:
+   * `2vcpu-4gb` | `4vcpu-8gb` | `8vcpu-16gb` | `32vcpu-64gb`) and `provider`
+   * (`vercel` | `e2b`). `size` maps to provider machine specs at create
+   * (Vercel: vCPUs, 2048 MB RAM per vCPU); E2B sizing is template-defined and
+   * ignores it. Optional; omit → smallest SKU on the default provider.
+   * Per-invocation `invoke({ size })` overrides the size.
+   */
+  resources?: SandboxResources;
   /**
    * Outbound network policy for the runner sandbox.
    * Use "*": [] to allow all traffic while still injecting headers for specific domains.
@@ -191,6 +207,13 @@ export interface WorkflowDefinition<
    * invokePolicy: { users: "owner", workflows: ["nightly-orchestrator"] }
    */
   invokePolicy?: InvokePolicy;
+  /**
+   * Internal — set by `defineSandboxEnvironment`, not by workflow authors.
+   * Marks the workflow as an environment build (base-env / agent-env) so the
+   * server skips mounting the shared factory drive for its runs (#13). See
+   * `WorkflowMetadata.environmentBuild`.
+   */
+  environmentBuild?: boolean;
 }
 
 /**
@@ -237,9 +260,7 @@ function compileRunForm<TOutput, TInput extends Record<string, unknown>>(
         setMetadata:    stepCtx.setMetadata,
         step:           stepCtx.step,
         agentEvents:    stepCtx.agentEvents,
-        checkpoint:      stepCtx.checkpoint,
         pause:           stepCtx.pause,
-        requestDecision: stepCtx.requestDecision,
         sleep:           stepCtx.sleep,
         waitForEvent:    stepCtx.waitForEvent,
         processors:      metadata.processors ?? [],

package/src/utils/bundler.ts

@@ -25,7 +25,7 @@ import { parse as babelParse } from "@babel/parser";
 import type { File, ExportDefaultDeclaration, CallExpression, Expression, Statement } from "@babel/types";
 import { importSourceModule } from "./source-loader.js";
 import type { SnapshotConfig } from "../types/workflow.js";
-import type { IOSchema, OutputSchema, ConnectorRequirements, ConnectorOperationTag, InvokePolicy } from "../types/workflow-metadata.js";
+import type { IOSchema, OutputSchema, ConnectorRequirements, ConnectorOperationTag, InvokePolicy, SandboxResources } from "../types/workflow-metadata.js";
 import type { SandboxNetworkPolicy } from "../sandbox.js";
 import { isWorkflow } from "../workflow-steps/workflow.js";
 import type { Workflow } from "../workflow-steps/types.js";
@@ -98,6 +98,9 @@ export interface BundledWorkflow {
   /** Snapshot config from the workflow definition — `bootFrom` (where to
    *  restore at run start), `save`, `retain`. */
   snapshots?: SnapshotConfig;
+  /** Sandbox resources declared via `defineWorkflow({ resources })` — machine
+   *  SKU (`size`) and `provider` (`vercel` | `e2b`). */
+  resources?: SandboxResources;
   workflowPlan: WorkflowPlan;
   /** Compact JSON-Schema-shaped description of the workflow's input
    *  type. Extracted from the workflow's declared `input` zod schema
@@ -112,6 +115,9 @@ export interface BundledWorkflow {
   /** Tier-1 invoke ACL — who may dispatch this connector-brokering
    *  workflow (`defineWorkflow({ invokePolicy })`). */
   invokePolicy?: InvokePolicy;
+  /** Set by `defineSandboxEnvironment` — marks an environment build so the
+   *  server skips the /factory mount for its runs (#13). */
+  environmentBuild?: boolean;
 }
 
 async function bundle(path: string, label: string): Promise<string> {
@@ -334,9 +340,11 @@ export async function bundleWorkflow(
     ...(inputSchema              !== undefined ? { inputSchema }                        : {}),
     ...(outputSchema             !== undefined ? { outputSchema }                       : {}),
     ...(metadata.snapshots       !== undefined ? { snapshots:    metadata.snapshots }    : {}),
+    ...(metadata.resources       !== undefined ? { resources:    metadata.resources }    : {}),
     ...(metadata.connectors          !== undefined ? { connectors:          metadata.connectors }          : {}),
     ...(metadata.connectorOperation  !== undefined ? { connectorOperation:  metadata.connectorOperation }  : {}),
     ...(metadata.invokePolicy        !== undefined ? { invokePolicy:        metadata.invokePolicy }        : {}),
+    ...(metadata.environmentBuild    !== undefined ? { environmentBuild:    metadata.environmentBuild }    : {}),
   };
 }
 

package/src/workflow-steps/observability.ts

@@ -32,15 +32,21 @@
 import type { AgentLifecycleEvent } from "../agent/agent-loop.js";
 import type { AgentEventSink } from "../types/workflow.js";
 import type { LiveAgentEventEmitter } from "./run-callback.js";
-import { PauseSignal, isPauseSignal } from "../pause/pause-core.js";
+import { isPauseSignal } from "../pause/pause-core.js";
+import type { ScopedMemoize } from "../pause/checkpoint.js";
 
 /** One named sub-step (from `ctx.step("name", async () => ...)`).
- *  Becomes a `workflow_substep_*` lifecycle event on the run timeline. */
+ *  Becomes a `workflow_substep_*` lifecycle event on the run timeline.
+ *
+ *  `restored` is the durable-step resume case (ADR-0012): the body did NOT
+ *  re-run — its memoised result was read from the state-dir checkpoint a
+ *  prior subprocess wrote. Always `durationMs: 0` (no work happened this
+ *  pass) and never carries `error`. */
 export interface SubStepEvent {
   name:       string;
   startedAt:  number;
   durationMs: number;
-  status:     "completed" | "failed";
+  status:     "completed" | "failed" | "restored";
   /** Present when status="failed" — the user error's message. */
   error?:     string;
 }
@@ -76,22 +82,60 @@ export class StepObservabilityCollector {
   private events:   AgentLifecycleEvent[]   = [];
   private subSteps: SubStepEvent[]          = [];
   private readonly liveEmitter?: LiveAgentEventEmitter;
+  /** State-dir memoise bound to this step's `step<idx>` scope. Present in
+   *  the sandbox runner (durable `ctx.step`); absent in-process so unit
+   *  tests record observability without touching disk. */
+  private readonly memoize?: ScopedMemoize;
+  /** Sub-step names already used in THIS step body. A durable `ctx.step`
+   *  memoises by name, so a reused name would alias two distinct bodies
+   *  onto one checkpoint file — guarded by throwing on reuse (ADR-0012). */
+  private readonly usedStepNames: Set<string> = new Set();
   /** Seqs of events the server confirmed via the live route. */
   private readonly ackedSeqs: Set<number> = new Set();
   /** Promises for in-flight live emits — awaited at snapshot time. */
   private readonly inFlight: Set<Promise<void>> = new Set();
 
-  constructor(opts: { liveEmitter?: LiveAgentEventEmitter } = {}) {
+  constructor(opts: { liveEmitter?: LiveAgentEventEmitter; memoize?: ScopedMemoize } = {}) {
     this.liveEmitter = opts.liveEmitter;
+    this.memoize = opts.memoize;
   }
 
   readonly setMetadata = async (data: Record<string, unknown>): Promise<void> => {
     Object.assign(this.metadata, data);
   };
 
+  /**
+   * Durable named sub-step (ADR-0012). The body's result is memoised to the
+   * state-dir checkpoint keyed `step<idx>.<name>`; on a pause-resume re-entry
+   * the value is read from disk and `fn` is NOT re-run (recorded as a
+   * duration-0 `"restored"` sub-step). A body that PAUSES (PauseSignal)
+   * propagates BEFORE any memoise write — partial work is never stored, so
+   * the resume re-runs it.
+   *
+   * When no memoise store is wired (in-process tests), the body always runs
+   * and is recorded as a normal timed `"completed"` / `"failed"` sub-step.
+   */
   readonly step = async <T>(name: string, fn: () => Promise<T>): Promise<T> => {
+    if (this.usedStepNames.has(name)) {
+      throw new Error(
+        `ctx.step("${name}", …) reuses a step name already used in this step body. ` +
+        `Durable step names must be unique — they key the resume-time memoise file.`,
+      );
+    }
+    this.usedStepNames.add(name);
+
     const startedAt = Date.now();
     try {
+      if (this.memoize) {
+        const { value, restored } = await this.memoize(name, fn);
+        this.subSteps.push({
+          name,
+          startedAt,
+          durationMs: restored ? 0 : Date.now() - startedAt,
+          status:     restored ? "restored" : "completed",
+        });
+        return value;
+      }
       const result = await fn();
       this.subSteps.push({
         name,
@@ -102,7 +146,9 @@ export class StepObservabilityCollector {
       return result;
     } catch (err) {
       // A pause inside ctx.step is control flow, not a failed sub-step — let
-      // it propagate untouched so serveStep emits the pause sentinel.
+      // it propagate untouched so serveStep emits the pause sentinel. The
+      // memoise write is skipped (it only runs after `fn` resolves), so no
+      // partial result is stored — the resume re-enters and re-runs the body.
       if (isPauseSignal(err)) throw err;
       this.subSteps.push({
         name,

package/src/workflow-steps/runner.ts

@@ -29,7 +29,7 @@ import type { SandboxProvider } from "../types/sandbox.js";
 import type { WorkflowRun, WorkflowCtx } from "../types/workflow.js";
 import { StepObservabilityCollector, type StepObservability } from "./observability.js";
 import type { LiveAgentEventEmitter } from "./run-callback.js";
-import { scopedCheckpoint } from "../pause/checkpoint.js";
+import { scopedMemoize } from "../pause/checkpoint.js";
 import { corePause, PauseSignal, isPauseSignal, type PauseRequest } from "../pause/pause-core.js";
 import type { StepPauseRequest } from "../step-invocation/types.js";
 import { buildPauseWrappers, type PauseFn, type KindedPauseFn } from "../pause/wrappers.js";
@@ -129,7 +129,10 @@ export async function runWorkflowSingleStep(opts: RunWorkflowSingleStepOpts): Pr
   if (!step) throw new Error(`Step index ${opts.stepIndex} not found in workflow "${opts.workflow.id}"`);
   const parsedInput = step.input.safeParse(opts.input);
   if (!parsedInput.success) throw new StepValidationError(step.name, "input", parsedInput.error);
-  const collector = new StepObservabilityCollector({ liveEmitter: opts.liveAgentEventEmitter });
+  const collector = new StepObservabilityCollector({
+    liveEmitter: opts.liveAgentEventEmitter,
+    memoize:     scopedMemoize(`step${opts.stepIndex}`),
+  });
   const coord = { runId: opts.run.id, stepIndex: opts.stepIndex };
   const pauseWithKind: KindedPauseFn = function <T>(req: PauseRequest<T>, kind: StepPauseRequest["kind"]): Promise<T> {
     return corePause(req, coord, kind);
@@ -148,7 +151,6 @@ export async function runWorkflowSingleStep(opts: RunWorkflowSingleStepOpts): Pr
     setMetadata: collector.setMetadata,
     step:        collector.step,
     agentEvents: collector.agentEvents,
-    checkpoint:  scopedCheckpoint(`step${opts.stepIndex}`),
     pause,
     ...buildPauseWrappers(pauseWithKind),
   };
@@ -223,7 +225,10 @@ export async function runWorkflowSteps<TInput, TOutput>(
       throw err;
     }
 
-    const collector = new StepObservabilityCollector({ liveEmitter: opts.liveAgentEventEmitter });
+    const collector = new StepObservabilityCollector({
+      liveEmitter: opts.liveAgentEventEmitter,
+      memoize:     scopedMemoize(`step${i}`),
+    });
     const coord = { runId: run.id, stepIndex: i };
     const pauseWithKind: KindedPauseFn = function <T>(req: PauseRequest<T>, kind: StepPauseRequest["kind"]): Promise<T> {
       return corePause(req, coord, kind);
@@ -242,7 +247,6 @@ export async function runWorkflowSteps<TInput, TOutput>(
       setMetadata:    collector.setMetadata,
       step:           collector.step,
       agentEvents:    collector.agentEvents,
-      checkpoint:     scopedCheckpoint(`step${i}`),
       pause,
       ...buildPauseWrappers(pauseWithKind),
     };

package/src/workflow-steps/types.ts

@@ -38,14 +38,18 @@ export interface StepContext<TInput = unknown> extends BaseExecutionContext {
    */
   setMetadata(data: Record<string, unknown>): Promise<void>;
   /**
-   * Wrap a named sub-step for observability. Emits
-   * `workflow_substep_started` / `workflow_substep_completed` /
-   * `workflow_substep_failed` lifecycle events on the run timeline with
-   * the measured `durationMs`. Use for long sub-phases inside one step
-   * (setup, external API call, submit).
+   * Durable named sub-step (ADR-0012). Runs `fn` once and memoises its
+   * result to the state-dir checkpoint keyed `step<idx>.<name>`; on a
+   * pause-resume re-entry the value is read from disk and `fn` is NOT
+   * re-run. Emits `workflow_substep_started` /
+   * `workflow_substep_completed` / `workflow_substep_failed` lifecycle
+   * events on the run timeline with the measured `durationMs` — a restored
+   * sub-step reports `durationMs: 0` and status `"restored"`.
    *
-   * The block runs even if observability flushing fails — instrumentation
-   * never breaks the workflow.
+   * Names must be unique within one step body — they key the memoise file,
+   * so a reused name throws. A body that pauses (PauseSignal) is never
+   * memoised: the resume re-enters and re-runs it. For cross-process side
+   * effects (DB writes, emails) use `invokeChild`, not `step`.
    */
   step<T>(name: string, fn: () => Promise<T>): Promise<T>;
   /**

package/src/workflow-steps/workflow.ts

@@ -23,7 +23,7 @@ import type { z } from "zod";
 import type { Step, Workflow } from "./types.js";
 import { WORKFLOW_BRAND } from "./types.js";
 import { extractMetadata } from "../types/workflow-metadata.js";
-import type { SnapshotConfig } from "../types/workflow-metadata.js";
+import type { SnapshotConfig, SandboxResources } from "../types/workflow-metadata.js";
 import type { SandboxNetworkPolicy } from "../sandbox.js";
 import type { Processor } from "../processors/processor.js";
 
@@ -51,6 +51,10 @@ export interface StepWorkflowDefinition<TInput, TOutput> {
   networkPolicy?: SandboxNetworkPolicy;
   placeholders?:  Record<string, string>;
   snapshots?:     SnapshotConfig;
+  /** Sandbox resources — machine SKU (`size`, a `SandboxSize` vCPU string)
+   *  and `provider` (`vercel` | `e2b`). Vercel maps `size` to vCPUs; E2B
+   *  sizing is template-defined. Omit → smallest SKU on the default provider. */
+  resources?:     SandboxResources;
   processors?:    readonly Processor[];
 }
 

package/src/workflows/invoke-child.ts

@@ -24,6 +24,12 @@ export function buildInvokeChild(
   return (name, input, childOpts) => getChildClient().invokeAndWait(name, input, {
     ...childOpts,
     parentRunId: runId,
-    factorySlug: childOpts?.factorySlug ?? opts.defaultFactorySlug ?? process.env.AGENT_COMPOSE_FACTORY_SLUG ?? "default",
+    // The runner sets `AGENT_COMPOSE_FACTORY` (the run's factory slug — see
+    // activities.ts loadRunnerEnvs). Default the child to it so it lands in the
+    // SAME factory as the parent — the per-run API key is factory-scoped, so a
+    // child dispatched into another factory 403s. (Was reading the never-set
+    // `AGENT_COMPOSE_FACTORY_SLUG`, silently falling back to "default".)
+    factorySlug: childOpts?.factorySlug ?? opts.defaultFactorySlug
+      ?? process.env.AGENT_COMPOSE_FACTORY ?? process.env.AGENT_COMPOSE_FACTORY_SLUG ?? "default",
   });
 }