@agent-compose/sdk 0.5.8 → 0.6.0

package/src/types/workflow-metadata.ts

@@ -9,9 +9,15 @@
  * `workflow-steps/workflow.ts` — it is the cycle-break point.
  */
 
-import type { SandboxNetworkPolicy, SandboxSize } 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`). */
@@ -145,10 +154,19 @@ export interface InvokePolicy {
  *  today; kept as its own object so finer controls (disk, gpu, …) can be
  *  added later without reshaping `WorkflowMetadata`. */
 export interface SandboxResources {
-  /** Machine size — `small | medium | large`. Maps to provider specs at
-   *  create time (Vercel: 2 / 4 / 8 vCPU, 2048 MB RAM per vCPU). Omit →
-   *  `"small"`. E2B sizing is template-defined and ignores this. */
+  /** 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 {
@@ -171,7 +189,8 @@ export interface WorkflowMetadata {
   outputSchema?: IOSchema;
   /** All snapshot config — boot source + capture mode. */
   snapshots?:     SnapshotConfig;
-  /** Sandbox machine resources (size). Optional; omit → small. */
+  /** 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.
@@ -184,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;
 }
 
 /**
@@ -215,6 +246,7 @@ export function extractMetadata(source: Partial<WorkflowMetadata>): WorkflowMeta
   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

@@ -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. */
@@ -121,10 +128,12 @@ export interface WorkflowDefinition<
    */
   snapshots?: SnapshotConfig;
   /**
-   * Sandbox machine size — `small` (default) | `medium` | `large`. Maps to
-   * provider machine specs at create (Vercel: 2 / 4 / 8 vCPU, 2048 MB RAM
-   * per vCPU). Optional; omit for `small`. E2B sizing is template-defined
-   * and ignores this. Per-invocation `invoke({ size })` overrides it.
+   * 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;
   /**
@@ -198,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;
 }
 
 /**
@@ -244,7 +260,6 @@ function compileRunForm<TOutput, TInput extends Record<string, unknown>>(
         setMetadata:    stepCtx.setMetadata,
         step:           stepCtx.step,
         agentEvents:    stepCtx.agentEvents,
-        checkpoint:      stepCtx.checkpoint,
         pause:           stepCtx.pause,
         sleep:           stepCtx.sleep,
         waitForEvent:    stepCtx.waitForEvent,

package/src/utils/bundler.ts

@@ -98,7 +98,8 @@ export interface BundledWorkflow {
   /** Snapshot config from the workflow definition — `bootFrom` (where to
    *  restore at run start), `save`, `retain`. */
   snapshots?: SnapshotConfig;
-  /** Sandbox machine size declared via `defineWorkflow({ resources: { size } })`. */
+  /** 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
@@ -114,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> {
@@ -340,6 +344,7 @@ export async function bundleWorkflow(
     ...(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

@@ -51,8 +51,9 @@ export interface StepWorkflowDefinition<TInput, TOutput> {
   networkPolicy?: SandboxNetworkPolicy;
   placeholders?:  Record<string, string>;
   snapshots?:     SnapshotConfig;
-  /** Sandbox machine size — small (default) | medium | large. Vercel maps
-   *  it to vCPUs; E2B sizing is template-defined. Omit → small. */
+  /** 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[];
 }