@agent-compose/sdk 0.5.7 → 0.5.8

package/dist/pause/wrappers.d.ts

@@ -1,12 +1,16 @@
 /**
- * The three opinionated pause wrappers (ADR-0006 §"SDK surface"), each a thin
+ * The two opinionated pause wrappers (ADR-0006 §"SDK surface"), each a thin
  * closure over `ctx.pause`:
  *
- *   - `requestDecision` — pause for a typed human/agent decision (schema required).
  *   - `sleep`           — a lightweight timed pause; resolves on its own TTL,
  *                         skips the snapshot, returns void.
  *   - `waitForEvent`    — pause until an event resumes by correlation key.
  *
+ * A typed human/agent decision is NOT a wrapper — it's a plain `ctx.pause`
+ * with a `schema` (and `payload.options` for the dashboard's answer UI). The
+ * pause primitive carries the reason (the ask) and the resume value (the
+ * resolution); there is no separate `requestDecision`.
+ *
  * Built from a `PauseFn` so the wrapper logic lives in one place and the step
  * runner just spreads them onto the context next to `pause`.
  */
@@ -16,16 +20,9 @@ import type { PauseRequest } from "./pause-core.js";
 /** The public `ctx.pause` callable (always `kind: "custom"`). */
 export type PauseFn = <T = unknown>(req: PauseRequest<T>) => Promise<T>;
 /** Internal: pause with an explicit wire `kind`. The wrappers stamp
- *  `decision`/`sleep`/`event` through this; the public `ctx.pause` is always
+ *  `sleep`/`event` through this; the public `ctx.pause` is always
  *  `custom` and never exposes it. */
 export type KindedPauseFn = <T = unknown>(req: PauseRequest<T>, kind: StepPauseRequest["kind"]) => Promise<T>;
-export interface RequestDecisionRequest<T> {
-    reason: string;
-    payload?: Record<string, unknown>;
-    /** Required — a decision is always validated against a shape. */
-    schema: z.ZodType<T>;
-    ttlMs?: number;
-}
 export interface WaitForEventRequest<T> {
     reason: string;
     /** Required — the by-key resume route targets this. */
@@ -34,7 +31,6 @@ export interface WaitForEventRequest<T> {
     ttlMs?: number;
 }
 export interface PauseWrappers {
-    requestDecision<T>(req: RequestDecisionRequest<T>): Promise<T>;
     sleep(durationMs: number): Promise<void>;
     waitForEvent<T = unknown>(req: WaitForEventRequest<T>): Promise<T>;
 }

package/dist/runtimes/openai-desktop.js

@@ -540,6 +540,8 @@ function extractMetadata(source) {
     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)
@@ -617,7 +619,6 @@ function compileRunForm(def, metadata) {
         agentEvents: stepCtx.agentEvents,
         checkpoint: stepCtx.checkpoint,
         pause: stepCtx.pause,
-        requestDecision: stepCtx.requestDecision,
         sleep: stepCtx.sleep,
         waitForEvent: stepCtx.waitForEvent,
         processors: metadata.processors ?? []
@@ -812,6 +813,7 @@ class AgentComposeClient {
         ...opts?.snapshots !== undefined ? { snapshots: opts.snapshots } : {},
         ...opts?.networkPolicy !== undefined ? { networkPolicy: opts.networkPolicy } : {},
         ...opts?.placeholders !== undefined ? { placeholders: opts.placeholders } : {},
+        ...opts?.size !== undefined ? { size: opts.size } : {},
         ...parentRunId ? { parentRunId } : {},
         ...opts?.agentId ? { agentId: opts.agentId } : {}
       }
@@ -971,6 +973,21 @@ class AgentComposeClient {
       q2.set("revision", String(opts.revision));
     return this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/files/content?${q2}`, { responseType: "text" });
   }
+  async listMembers() {
+    const body = await this.fetch("/api/v1/team/members");
+    return body.members;
+  }
+  async createMentions(input) {
+    const factorySlug = input.factorySlug ?? (typeof process !== "undefined" ? process.env?.AGENT_COMPOSE_FACTORY : undefined) ?? DEFAULT_FACTORY;
+    const runToken = typeof process !== "undefined" ? process.env?.AGENT_COMPOSE_RUN_TOKEN : undefined;
+    const { factorySlug: _omit, ...payload } = input;
+    const body = await this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/mentions`, {
+      method: "POST",
+      body: payload,
+      ...runToken ? { headers: { "x-run-token": runToken } } : {}
+    });
+    return body.mentions;
+  }
   async listFactoryEvents(opts) {
     const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
     const q2 = new URLSearchParams;
@@ -1222,6 +1239,7 @@ async function bundleWorkflow(workflowPath, overrides) {
     ...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 } : {}
@@ -1853,7 +1871,7 @@ async function runControlPoller(opts) {
 // src/agent/agent-loop.ts
 var DEFAULT_CLAUDE_MODEL = "claude-fable-5";
 var SAME_BLOCKER_ITERATIONS = 3;
-var STALL_ITERATIONS = 3;
+var STALL_ITERATIONS = 6;
 var MESSAGE_PREVIEW_CHARS = 400;
 function parseAgentStatus(text) {
   const match = text.match(/<status>([\s\S]*?)<\/status>/);
@@ -2084,7 +2102,15 @@ Re-emit the COMPLETE corrected <response> JSON now: every required field present
         }
         const msg = outputVerdict.value;
         opts.onAgentEvent?.(iteration, msg);
-        opts.onAgentLifecycleEvent?.({ event: "agent.message", at: Date.now(), agentId, label, iteration: iteration + 1, message: summarizeAgentMessage(msg) });
+        const summary = summarizeAgentMessage(msg);
+        opts.onAgentLifecycleEvent?.({
+          event: "agent.message",
+          at: Date.now(),
+          agentId,
+          label,
+          iteration: iteration + 1,
+          message: summary.type === "usage" && client.model != null ? { ...summary, model: client.model } : summary
+        });
         if (msg.type === "init")
           lastSessionId = msg.sessionId;
         if (msg.type === "text")
@@ -2163,9 +2189,9 @@ raw: ${JSON.stringify(rawResponse).slice(0, 400)}
       if (!status && rawResponse === null) {
         if (++iterationsWithoutStatus >= STALL_ITERATIONS)
           throw new Error(`${logLabel} stalled: no <status> block after ${iterationsWithoutStatus} iterations`);
-        if (opts.responseSchema && schemaRetriesLeft-- > 0) {
-          lastResponseValidationError = "no <response> block found — the turn ended with neither a <status> nor a <response> block; emit the complete <response> JSON";
-          process.stdout.write(`${logLabel} no <status>/<response> emitted — corrective re-prompt (${schemaRetriesLeft} retries left)
+        if (schemaRetriesLeft-- > 0) {
+          lastResponseValidationError = "Your turn ended with no <status> block" + (opts.responseSchema ? " (and no <response> block)" : "") + ". " + "If you launched a background job (`… &`) and are waiting to be notified when it finishes — STOP: nothing will notify you here. " + "Poll it NOW (read its output / wait for it synchronously to completion), then emit your <status>" + (opts.responseSchema ? " and the complete <response> JSON." : ".");
+          process.stdout.write(`${logLabel} empty turn (no <status>) — corrective re-prompt (${schemaRetriesLeft} retries left)
 `);
           iteration--;
           continue;
@@ -2746,6 +2772,13 @@ class SandboxUnavailableError extends Error {
 // src/sandbox.ts
 var AGENT_COMPOSE_TAG = process.env.AGENT_COMPOSE_TAG ?? `agent-compose-${process.env.AGENT_COMPOSE_ENV ?? "dev"}`;
 var VERCEL_VM_LIFETIME_WINDOW_MS = 6 * 60 * 60 * 1000;
+var SANDBOX_VCPUS = {
+  "2vcpu-4gb": 2,
+  "4vcpu-8gb": 4,
+  "8vcpu-16gb": 8,
+  "32vcpu-64gb": 32
+};
+var DEFAULT_SANDBOX_SIZE = "2vcpu-4gb";
 function makeSandboxProvider(sb) {
   const commands = sb.commands;
   return {
@@ -2911,7 +2944,7 @@ function makeVercelSandboxProvider(sb, globalEnvs) {
         let stdout = "";
         let stderr = "";
         const handle = await sb.runCommand({ cmd: "sh", args: ["-c", cmd], cwd: opts?.cwd, env: mergeEnvs(opts?.envs), detached: true, signal, ...opts?.sudo ? { sudo: true } : {} }).catch((err) => asUnavailable(err, true));
-        try {
+        const collect = async () => {
           await pRetry(async (attempt) => {
             const h = attempt === 1 ? handle : await sb.getCommand(handle.cmdId);
             if (attempt > 1) {
@@ -2930,11 +2963,22 @@ function makeVercelSandboxProvider(sb, globalEnvs) {
           }, { retries: 3, minTimeout: 1000, factor: 2 });
           const finished = await handle.wait();
           return { exitCode: finished.exitCode, stdout, stderr };
+        };
+        let timer;
+        const deadline = opts?.timeoutMs ? new Promise((_, 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) {
-          if (signal?.aborted) {
+          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);
         }
       }
     },
@@ -3011,7 +3055,8 @@ var SANDBOX_PROVIDERS = {
       const np = opts.networkPolicy ? { networkPolicy: toVercelNetworkPolicy(opts.networkPolicy) } : {};
       const tags = buildVercelTags(opts.metadata);
       const tmpl = opts.template ?? process.env.VERCEL_DEFAULT_SNAPSHOT;
-      const sb = await VercelSandbox.create(tmpl ? { source: { type: "snapshot", snapshotId: tmpl }, timeout: opts.timeoutMs, env: opts.envs, tags, persistent: false, ...np, ...creds } : { runtime: "node24", timeout: opts.timeoutMs, env: opts.envs, tags, persistent: false, ...np, ...creds });
+      const resources = { vcpus: SANDBOX_VCPUS[opts.size ?? DEFAULT_SANDBOX_SIZE] };
+      const sb = await VercelSandbox.create(tmpl ? { source: { type: "snapshot", snapshotId: tmpl }, timeout: opts.timeoutMs, env: opts.envs, tags, persistent: false, resources, ...np, ...creds } : { runtime: "node24", timeout: opts.timeoutMs, env: opts.envs, tags, persistent: false, resources, ...np, ...creds });
       return makeVercelSandboxProvider(sb, opts.envs);
     },
     reconnect: async (sandboxId) => {
@@ -3057,7 +3102,7 @@ var SANDBOX_PROVIDERS = {
   },
   e2b: {
     requiredEnv: { E2B_API_KEY: "E2B API key — e2b.dev/dashboard" },
-    create: async ({ template, timeoutMs, networkPolicy: _np, ...rest }) => {
+    create: async ({ template, timeoutMs, networkPolicy: _np, size: _size, ...rest }) => {
       const maxMs = e2bMaxSandboxMs();
       if (timeoutMs > maxMs) {
         console.warn(`[sandbox] e2b create timeout clamped: requested ${timeoutMs}ms exceeds the plan cap ${maxMs}ms — ` + `the sandbox dies at the cap, not the requested deadline. Raise E2B_MAX_SANDBOX_MS on plans that allow more.`);
@@ -3099,7 +3144,7 @@ var SANDBOX_PROVIDERS = {
   },
   "e2b-desktop": {
     requiredEnv: { E2B_API_KEY: "E2B API key — e2b.dev/dashboard" },
-    create: async ({ template, timeoutMs, networkPolicy: _np, ...rest }) => {
+    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()) }));
@@ -3283,14 +3328,6 @@ function scopedCheckpoint(scope) {
 // src/pause/wrappers.ts
 function buildPauseWrappers(pause) {
   return {
-    requestDecision(req) {
-      return pause({
-        reason: req.reason,
-        schema: req.schema,
-        ...req.payload !== undefined ? { payload: req.payload } : {},
-        ...req.ttlMs !== undefined ? { ttlMs: req.ttlMs } : {}
-      }, "decision");
-    },
     sleep(durationMs) {
       return pause({
         reason: `sleep ${durationMs}ms`,
@@ -3600,7 +3637,7 @@ function buildInvokeChild(runId, opts = {}) {
   return (name, input, childOpts) => getChildClient().invokeAndWait(name, input, {
     ...childOpts,
     parentRunId: runId,
-    factorySlug: childOpts?.factorySlug ?? opts.defaultFactorySlug ?? process.env.AGENT_COMPOSE_FACTORY_SLUG ?? "default"
+    factorySlug: childOpts?.factorySlug ?? opts.defaultFactorySlug ?? process.env.AGENT_COMPOSE_FACTORY ?? process.env.AGENT_COMPOSE_FACTORY_SLUG ?? "default"
   });
 }
 // src/workflow-steps/step.ts
@@ -3967,6 +4004,149 @@ async function serveStep(handler) {
 import { z as z11 } from "zod";
 import { randomUUID as randomUUID2 } from "node:crypto";
 
+// src/agent/agent-context.ts
+var AGENT_COMPOSE_MANUAL = `# Working inside an Agent Compose sandbox
+
+You are an agent running in a per-run sandbox on the Agent Compose platform.
+Use the **\`agentc\` CLI** and the **\`@agent-compose/sdk\`** for everything below —
+do NOT hand-roll raw HTTP/curl calls against the platform API. The CLI is on
+your PATH and already authenticated from the environment
+(\`AGENT_COMPOSE_URL\` / \`AGENT_COMPOSE_API_KEY\` / \`AGENT_COMPOSE_FACTORY\` are
+injected for this run), so commands just work — no login, no keys to manage.
+
+The \`/ac:*\` skills are installed as Claude Code slash commands (\`/ac:invoke\`,
+\`/ac:events\`, \`/ac:logs\`, \`/ac:register\`, …) — reach for them too.
+
+## Files — your outputs persist by default
+
+Your working directory defaults to **\`$AGENT_COMPOSE_RUN_DIR\`** — a per-run
+directory on the shared factory drive
+(\`$AGENT_COMPOSE_FACTORY_DIR/<workflow>/<version>/<run-id>/\`) the platform
+creates and attributes to this run. **Files you write here persist by
+default** — they show up in the dashboard's Files tab and the run's Artifacts
+card, with no API calls to save them. The dir already exists and is writable.
+
+Need throwaway scratch — heavy build output, package caches, temp files?
+\`cd /tmp\` (or any path outside \`/factory\`): anything off the factory drive is
+ephemeral and discarded when the sandbox ends. In short: **stay in your working
+dir to keep something, \`cd\` out to throw it away.**
+
+The whole shared drive is POSIX-mounted at \`/factory\`; the dashboard-visible
+root is \`$AGENT_COMPOSE_FACTORY_DIR\` (\`/factory/files\`). Earlier versions and
+runs live in sibling dirs under
+\`$AGENT_COMPOSE_FACTORY_DIR/$AGENT_COMPOSE_WORKFLOW/\` — read them for prior
+context. Other workflows' dirs are present but not your concern.
+
+## Events — the factory timeline
+
+Record something on the run/factory timeline (the dashboard renders these)
+with the CLI — your run id is \`$RUN_ID\`:
+
+    agentc events send "$RUN_ID" <name> --summary "<one line>" [--body '<json>']
+
+Names like \`note.created\` / \`brief.posted\` surface in the Workbench;
+\`agentc events list\` reads them back. \`/ac:events\` is the skill equivalent.
+
+## Runs
+
+    agentc list                          # registered workflows  (/ac:list)
+    agentc logs "$RUN_ID"                # a run's logs           (/ac:logs)
+    agentc invoke <workflow> -i '<json>' # dispatch a workflow    (/ac:invoke)
+
+## Writing workflow / agent code — the SDK
+
+\`@agent-compose/sdk\` is installed in \`/workspace\` — import it from any script
+you write there:
+
+    import { defineWorkflow, agent, AgentComposeClient } from "@agent-compose/sdk";
+
+Use \`/ac:generate-workflow\` / \`/ac:generate-agent\` to scaffold, then
+\`agentc register <file.ts>\` (or \`/ac:register\`).
+
+## Pausing to ask the human — \`agentc pause\`
+
+When you can't or shouldn't proceed without a human, run \`agentc pause\`. It
+blocks until they answer on the dashboard, then prints their answer to stdout:
+
+    ANSWER=$(agentc pause --reason "Notion returned 401 — connect Notion to continue" \\
+                          --option retry --option skip)
+
+Reach for it the moment you hit — or foresee — any of these:
+- **A wall only a human can clear:** a 401/403, a missing credential, an
+  unconnected provider, a host the network refuses. Do NOT retry blindly or try
+  to work around it — pause and say what needs enabling.
+- **A durable or outward-facing action that needs sign-off:** registering a
+  workflow, deploying, sending email/messages, deleting or overwriting shared
+  data, spending money. Prepare everything, then pause for approval BEFORE you
+  commit it.
+- **A judgment call only the human can settle:** an under-specified request,
+  several valid paths, a conflict with existing state, missing input only they have.
+
+You compose the \`--reason\` (the ask) yourself; pass \`--option\` choices when
+there are clear ones, omit them for a free-form answer. Read the printed answer
+and act on it. Each agent pauses independently — pausing doesn't stop the others.
+
+## Credentials
+
+Connector credentials (Google, GitHub, …) are NEVER in your environment.
+They're injected at the network layer when you call an allowed host — make the
+request **without** an Authorization header and the platform adds it. Don't try
+to read or exfiltrate tokens; they aren't here. The "Connectors & access"
+section below (when present) lists exactly which providers this run can reach.
+
+## Tools in this environment
+
+- \`agentc\` — Agent Compose CLI (your primary interface; authed from env)
+- \`@agent-compose/sdk\` — installed in /workspace for writing workflows
+- \`/ac:*\` Claude Code skills — slash commands for the above
+- \`archil\` (factory drive), \`rtk\`, \`bun\`
+- A world-writable \`/workspace\` working directory`;
+function renderConnectorsSection(connectors) {
+  if (connectors.length === 0)
+    return "";
+  const rows = connectors.map((c) => {
+    const host = c.hosts?.length ? c.hosts.join(", ") : "(host set by the platform)";
+    const verbs = c.methods?.length ? c.methods.join("/") : "any method";
+    const paths = c.pathPrefixes?.length ? ` under ${c.pathPrefixes.join(", ")}` : "";
+    const repo = c.repository ? ` — repo \`${c.repository}\` (${c.access ?? "read"})` : "";
+    const why = c.scopes?.length ? `  
+  _scopes: ${c.scopes.join(", ")}_` : "";
+    return `- **${c.name ?? c.provider}** → \`${host}\` — ${verbs}${paths}${repo}${why}`;
+  });
+  return `
+
+## Connectors & access — what this run can reach
+
+These providers are connected for this run. Call their APIs with plain
+fetch/SDKs and **no Authorization header** — the platform injects the
+credential at the network layer. Requests outside the listed method/path are
+refused (403) and the token withheld. Anything NOT listed is unreachable; if
+you need it, \`agentc pause\` and ask for it to be connected.
+
+${rows.join(`
+`)}
+`;
+}
+function buildAgentContextDoc(env) {
+  let connectors = [];
+  const raw = env.AGENT_COMPOSE_CONNECTORS;
+  if (raw) {
+    try {
+      const parsed = JSON.parse(raw);
+      if (Array.isArray(parsed))
+        connectors = parsed;
+    } catch {}
+  }
+  return AGENT_COMPOSE_MANUAL + renderConnectorsSection(connectors);
+}
+async function writeAgentContext(args) {
+  const doc = buildAgentContextDoc(args.env);
+  const dir = args.cwd.replace(/\/+$/, "") || "/workspace";
+  for (const name of ["AGENTS.md", "CLAUDE.md", "GEMINI.md"]) {
+    await args.sandbox.files.write(`${dir}/${name}`, doc);
+  }
+}
+
 // src/agent/protocol-suffix.md
 var protocol_suffix_default = '## Status Signal\n\nWhen you have finished your work or are blocked, emit a `<status>` block at the end of your response:\n\n```json\n<status>\n{\n  "summary": "one sentence describing what was done or what is blocking",\n  "completed": ["each acceptance criterion that is now fully met"],\n  "blockers": [],\n  "changed_files": ["relative/path/to/file"],\n  "tests_run": true,\n  "exit_signal": true\n}\n</status>\n```\n\n**Field semantics:**\n- `summary`: one sentence — what was accomplished or what is blocking\n- `completed`: acceptance criteria items that are fully done — be specific\n- `blockers`: non-empty when `exit_signal: false` — describe the exact obstacle\n- `changed_files`: relative paths of files you created or modified\n- `tests_run`: `true` if you ran any test suite (pass or fail); `false` if no tests exist or you skipped them\n- `exit_signal: true` — set when ALL acceptance criteria are met and no blockers remain\n- `exit_signal: false` — set when blocked or unfinished; `blockers` must be non-empty\n\n**If you are still actively working** and have not reached a natural stopping point, do NOT emit a `<status>` block — just keep working.\n\n**Example (done):**\n\n```json\n<status>\n{\n  "summary": "Added input validation middleware to /api/tasks with tests",\n  "completed": ["POST /api/tasks validates required fields", "Returns 400 with details on invalid input", "Unit tests passing"],\n  "blockers": [],\n  "changed_files": ["src/middleware/validate.ts", "src/routes/tasks.ts", "tests/validate.test.ts"],\n  "tests_run": true,\n  "exit_signal": true\n}\n</status>\n```\n\n**Example (blocked):**\n\n```json\n<status>\n{\n  "summary": "Implemented middleware but tests are failing due to module resolution",\n  "completed": ["Middleware created and wired into route"],\n  "blockers": ["Tests fail: cannot resolve import \'./validate\' — module resolution config unclear"],\n  "changed_files": ["src/middleware/validate.ts"],\n  "tests_run": true,\n  "exit_signal": false\n}\n</status>\n```\n';
 
@@ -4082,7 +4262,28 @@ function resolveAgentId(explicitId) {
   return `step${activeCall.stepIndex}-agent-${activeCall.callIndex}`;
 }
 async function agent(opts) {
-  const workingDir = opts.workingDir ?? "";
+  let workingDir = opts.workingDir || process.env.AGENT_COMPOSE_RUN_DIR || "/workspace";
+  const CONTEXT_WRITE_DEADLINE_MS = 15000;
+  const tryWriteContext = (cwd) => {
+    let timer;
+    return Promise.race([
+      writeAgentContext({ sandbox: opts.sandbox, cwd, env: process.env }).then(() => true),
+      new Promise((resolve) => {
+        timer = setTimeout(() => resolve(false), CONTEXT_WRITE_DEADLINE_MS);
+      })
+    ]).catch((err) => {
+      console.error(`[agent] writeAgentContext(${cwd}) failed: ${err instanceof Error ? err.message : String(err)}`);
+      return false;
+    }).finally(() => {
+      if (timer)
+        clearTimeout(timer);
+    });
+  };
+  if (!await tryWriteContext(workingDir) && workingDir !== "/workspace") {
+    console.error(`[agent] working dir ${workingDir} not writable within ${CONTEXT_WRITE_DEADLINE_MS}ms ` + `(factory drive degraded?) — falling back to /workspace so the agent can run`);
+    workingDir = "/workspace";
+    await tryWriteContext(workingDir);
+  }
   const agentId = resolveAgentId(opts.agentId);
   const callbackUrl = process.env.AGENT_COMPOSE_URL;
   const callbackToken = process.env.AGENT_COMPOSE_RUN_TOKEN;

package/dist/sandbox.d.ts

@@ -39,6 +39,27 @@ export type SandboxNetworkPolicy = "allow-all" | "deny-all" | {
     allow?: string[] | Record<string, SandboxNetworkAllowRule[]>;
     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 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. */
+export declare const DEFAULT_SANDBOX_SIZE: SandboxSize;
 export interface SandboxCreateOpts {
     envs: Record<string, string>;
     metadata: Record<string, string>;
@@ -46,6 +67,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

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

@@ -48,7 +48,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 declare const StepPauseRequestSchema: z.ZodObject<{

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

@@ -2,7 +2,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. */
 export interface WorkflowRun {
@@ -38,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/dist/types/workflow-metadata.d.ts

@@ -8,7 +8,7 @@
  * Keep this module free of value imports from `types/workflow.ts` or
  * `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";
 /**
  * Workflow-level metadata read by the server at registration. Lives on
@@ -134,6 +134,15 @@ export interface InvokePolicy {
     apiKeys?: string[];
     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
@@ -154,6 +163,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

package/dist/types/workflow.d.ts

@@ -27,8 +27,8 @@ export type { WorkflowMetadata } from "./workflow-metadata.js";
 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. */
 export interface AgentBudget {
@@ -100,6 +100,13 @@ export interface WorkflowDefinition<TOutput = unknown, TInput extends Record<str
      * `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.

package/dist/utils/bundler.d.ts

@@ -20,7 +20,7 @@
  * manifest's `sourceHash` against the source it received.
  */
 import type { SnapshotConfig } from "../types/workflow.js";
-import type { IOSchema, ConnectorRequirements, ConnectorOperationTag, InvokePolicy } from "../types/workflow-metadata.js";
+import type { IOSchema, ConnectorRequirements, ConnectorOperationTag, InvokePolicy, SandboxResources } from "../types/workflow-metadata.js";
 import type { SandboxNetworkPolicy } from "../sandbox.js";
 import { type WorkflowPlan } from "../types/workflow-plan.js";
 /** Bumped when the manifest contract changes in a way the server should
@@ -84,6 +84,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

package/dist/workflow-steps/workflow.d.ts

@@ -20,7 +20,7 @@
  */
 import type { z } from "zod";
 import type { Step, Workflow } from "./types.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";
 export interface WorkflowBuilder<TInput, TCurrent> {
@@ -46,6 +46,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[];
 }
 export declare function createStepWorkflow<TInput, TOutput>(opts: StepWorkflowDefinition<TInput, TOutput>): WorkflowBuilder<TInput, TInput>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-compose/sdk",
-  "version": "0.5.7",
+  "version": "0.5.8",
   "description": "Client library for agent-compose — define agents, runtimes, and workflows, and invoke them against an agent-compose server.",
   "license": "MIT",
   "repository": {