@agent-compose/sdk 0.5.7 → 0.5.8

package/src/sandbox.ts

@@ -71,6 +71,35 @@ export type SandboxNetworkPolicy =
       subnets?: SandboxNetworkSubnetPolicy;
     };
 
+/** Sandbox machine size. A coarse small/medium/large knob that maps to
+ *  provider machine specs at create time. Vercel honours it natively via
+ *  `resources.vcpus` (2048 MB RAM per vCPU). E2B sizing is baked into the
+ *  template, so E2B ignores this field. Default: "small". */
+/** Sandbox hardware SKU. Named for the actual machine spec (vCPU + RAM) rather
+ *  than abstract t-shirt sizes. Memory is always 2048 MB per vCPU:
+ *    2vcpu-4gb   =  2 vCPU /  4 GiB  (Vercel's own default machine)
+ *    4vcpu-8gb   =  4 vCPU /  8 GiB
+ *    8vcpu-16gb  =  8 vCPU / 16 GiB  (per-sandbox ceiling on STANDARD accounts —
+ *                                     probed live: 16 & 32 vCPU 400 on dev)
+ *    32vcpu-64gb = 32 vCPU / 64 GiB  (ENTERPRISE ONLY — standard accounts reject >8 vCPU) */
+export type SandboxSize = "2vcpu-4gb" | "4vcpu-8gb" | "8vcpu-16gb" | "32vcpu-64gb";
+
+/** SKU → Vercel vCPU count (RAM follows at 2048 MB/vCPU). */
+export const SANDBOX_VCPUS: Record<SandboxSize, number> = {
+  "2vcpu-4gb":    2,
+  "4vcpu-8gb":    4,
+  "8vcpu-16gb":   8,
+  "32vcpu-64gb": 32,
+};
+
+/** 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. */
+export const DEFAULT_SANDBOX_SIZE: SandboxSize = "2vcpu-4gb";
+
 export interface SandboxCreateOpts {
   envs:           Record<string, string>;
   metadata:       Record<string, string>;
@@ -78,6 +107,9 @@ export interface SandboxCreateOpts {
   /** Provider-specific template/snapshot identifier. E2B: template id or
    *  snapshot id (omit → E2B's default base). Vercel: snapshot id (omit → node24). */
   template?:      string;
+  /** Machine size. Vercel maps it to `resources.vcpus`; E2B ignores it
+   *  (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
@@ -417,16 +449,11 @@ function makeVercelSandboxProvider(sb: any, globalEnvs?: Record<string, string>)
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const handle: any = await sb.runCommand({ cmd: "sh", args: ["-c", cmd], cwd: opts?.cwd, env: mergeEnvs(opts?.envs), detached: true, signal, ...(opts?.sudo ? { sudo: true } : {}) })
           .catch((err: unknown) => asUnavailable(err, true));
-        // Reconnect to the already-running command on transient stream failures (e.g. BrotliDecompressionError).
-        // `h.logs()` replays from the start on reconnect, so reset accumulators per
-        // attempt to avoid double-counting. The streaming callbacks may still fire
-        // for duplicate chunks during retries — an acceptable tradeoff for resilience.
-        //
-        // A failure here (mid-stream / on `wait`) is NOT safe to retry: the
-        // runner already launched, so user code may have produced side
-        // effects. Surface it as a terminal `SandboxUnavailableError` so it's
-        // classified honestly but not auto-replayed.
-        try {
+        // Stream + wait. Reconnect to the already-running command on transient
+        // stream failures (e.g. BrotliDecompressionError). `h.logs()` replays
+        // from the start on reconnect, so reset accumulators per attempt to
+        // avoid double-counting.
+        const collect = async () => {
           await pRetry(async (attempt) => {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             const h: any = attempt === 1 ? handle : await sb.getCommand(handle.cmdId);
@@ -438,17 +465,34 @@ function makeVercelSandboxProvider(sb: any, globalEnvs?: Record<string, string>)
           }, { retries: 3, minTimeout: 1_000, factor: 2 });
           const finished = await handle.wait();
           return { exitCode: finished.exitCode, stdout, stderr };
+        };
+        // `timeoutMs` MUST be authoritative. The AbortSignal alone is not: a
+        // command that RUNS but emits nothing (e.g. a wedged `archil checkout`
+        // on a blocked data plane) leaves `logs()`/`wait()` pending and the
+        // abort never interrupts the await — the call hangs for the activity's
+        // whole multi-hour ceiling. Race a hard client-side deadline so a hung
+        // command fails fast and the caller's degrade/retry policy takes over.
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        const deadline = opts?.timeoutMs
+          ? new Promise<never>((_, reject) => {
+              timer = setTimeout(
+                () => reject(new Error(`command timed out after ${opts.timeoutMs}ms: ${cmd.slice(0, 200)}`)),
+                opts.timeoutMs);
+            })
+          : undefined;
+        try {
+          return await (deadline ? Promise.race([collect(), deadline]) : collect());
         } catch (err) {
-          // A caller-requested timeout (opts.timeoutMs → AbortSignal) is a
-          // COMMAND timing out, not the sandbox dying — the VM is alive and
-          // answering; one command overran its budget. Classifying it as
-          // terminal sandbox-unavailable failed whole runs over a single
-          // slow mount probe (observed live). Surface it as a plain error
-          // so the caller's own retry/deadline policy decides.
-          if (signal?.aborted) {
-            throw new Error(`command timed out after ${opts?.timeoutMs}ms: ${cmd.slice(0, 200)}`);
-          }
+          // A timeout (hard deadline or AbortSignal) is a COMMAND overrunning
+          // its budget, not the sandbox dying — the VM is alive. Surface it as
+          // a plain error so the caller's own retry/deadline policy decides
+          // (classifying it as terminal sandbox-unavailable failed whole runs
+          // over a single slow mount probe, observed live).
+          if (err instanceof Error && err.message.startsWith("command timed out after")) throw err;
+          if (signal?.aborted) throw new Error(`command timed out after ${opts?.timeoutMs}ms: ${cmd.slice(0, 200)}`);
           return asUnavailable(err, false);
+        } finally {
+          if (timer) clearTimeout(timer);
         }
       },
     },
@@ -567,14 +611,19 @@ const SANDBOX_PROVIDERS: Record<string, SandboxProviderDef> = {
       // bakes on top of this base chains from it — the base tools are in
       // every derived snapshot for free.
       const tmpl = opts.template ?? process.env.VERCEL_DEFAULT_SNAPSHOT;
+      // Machine size → vCPUs (RAM auto-follows at 2048 MB/vCPU). Always sent
+      // explicitly so the spec is deterministic and self-documenting rather
+      // than riding Vercel's implicit default; "small" maps to that default
+      // anyway, so existing runs are unchanged.
+      const resources = { vcpus: SANDBOX_VCPUS[opts.size ?? DEFAULT_SANDBOX_SIZE] };
       // `persistent: false` — @vercel/sandbox 2.x creates persistent-by-default
       // sandboxes: stop() auto-snapshots (and keeps billing storage), commands
       // transparently resume a stopped VM, and kill no longer destroys. Our
       // sandboxes are single-run and lifecycle-managed by the engine (explicit
       // snapshot() / kill()), so opt out in BOTH branches.
       const sb = await VercelSandbox.create(tmpl
-        ? { source: { type: "snapshot" as const, snapshotId: tmpl }, timeout: opts.timeoutMs, env: opts.envs, tags, persistent: false, ...np, ...creds }
-        : { runtime: "node24" as const, timeout: opts.timeoutMs, env: opts.envs, tags, persistent: false, ...np, ...creds },
+        ? { source: { type: "snapshot" as const, snapshotId: tmpl }, timeout: opts.timeoutMs, env: opts.envs, tags, persistent: false, resources, ...np, ...creds }
+        : { runtime: "node24" as const, timeout: opts.timeoutMs, env: opts.envs, tags, persistent: false, resources, ...np, ...creds },
       );
       // Pass envs as globalEnvs so they're injected into every runCommand subprocess.
       // (Vercel's Sandbox.create env parameter does not flow to runCommand subprocesses.)
@@ -649,7 +698,10 @@ const SANDBOX_PROVIDERS: Record<string, SandboxProviderDef> = {
   },
   "e2b": {
     requiredEnv: { E2B_API_KEY: "E2B API key — e2b.dev/dashboard" },
-    create: async ({ template, timeoutMs, networkPolicy: _np, ...rest }) => {
+    // `size` dropped here: E2B has no create-time resource knob (specs are
+    // baked into the template/snapshot), so sizing on E2B = a pre-sized
+    // template, not this field. Honoured only on Vercel.
+    create: async ({ template, timeoutMs, networkPolicy: _np, size: _size, ...rest }) => {
       // `template` is an E2B template id, a snapshot id (a valid create source
       // that persists beyond its origin sandbox — bootFrom parity), or absent →
       // E2B's default base (Debian + node + npm/python/git), mirroring Vercel's
@@ -722,7 +774,10 @@ const SANDBOX_PROVIDERS: Record<string, SandboxProviderDef> = {
     // its transforms carry live connector tokens, and a credential-bearing
     // object must never cross into a third-party library's option bag.
     // Lifetime is clamped to E2B's per-plan cap the same way.
-    create: async ({ template, timeoutMs, networkPolicy: _np, ...rest }) => {
+    // `size` dropped here: E2B has no create-time resource knob (specs are
+    // baked into the template/snapshot), so sizing on E2B = a pre-sized
+    // template, not this field. Honoured only on Vercel.
+    create: async ({ template, timeoutMs, networkPolicy: _np, size: _size, ...rest }) => {
       if (!template) throw new Error("E2B Desktop provider requires an explicit `template` (Dockerfile-based — no default base image)");
       return makeDesktopSandboxProvider(
         await Desktop.create(template, { ...rest, timeoutMs: Math.min(timeoutMs, e2bMaxSandboxMs()) }),

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. */
@@ -46,8 +46,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/workflow-metadata.ts

@@ -9,7 +9,7 @@
  * `workflow-steps/workflow.ts` — it is the cycle-break point.
  */
 
-import type { SandboxNetworkPolicy } from "../sandbox.js";
+import type { SandboxNetworkPolicy, SandboxSize } from "../sandbox.js";
 import type { Processor } from "../processors/processor.js";
 
 /**
@@ -141,6 +141,16 @@ 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 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. */
+  size?: SandboxSize;
+}
+
 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 +171,8 @@ export interface WorkflowMetadata {
   outputSchema?: IOSchema;
   /** All snapshot config — boot source + capture mode. */
   snapshots?:     SnapshotConfig;
+  /** Sandbox machine resources (size). Optional; omit → small. */
+  resources?:     SandboxResources;
   processors?:    readonly Processor[];
   /** Connector requirements — providers whose APIs this workflow calls.
    *  Dispatch resolves an authorized grant per provider and injects a
@@ -198,6 +210,7 @@ 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 });

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. */
@@ -120,6 +120,13 @@ export interface WorkflowDefinition<
    * `invoke({ snapshots })` overrides this default.
    */
   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.
+   */
+  resources?: SandboxResources;
   /**
    * Outbound network policy for the runner sandbox.
    * Use "*": [] to allow all traffic while still injecting headers for specific domains.
@@ -239,7 +246,6 @@ function compileRunForm<TOutput, TInput extends Record<string, unknown>>(
         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,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 } })`. */
+  resources?: SandboxResources;
   workflowPlan: WorkflowPlan;
   /** Compact JSON-Schema-shaped description of the workflow's input
    *  type. Extracted from the workflow's declared `input` zod schema
@@ -334,6 +336,7 @@ 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 }        : {}),

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,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. */
+  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",
   });
 }