@agent-compose/sdk 0.5.6 → 0.5.8

package/dist/index.js

@@ -540,12 +540,16 @@ 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.memory !== undefined)
-    out.memory = source.memory;
-  if (source.postRunHooks !== undefined)
-    out.postRunHooks = Object.freeze([...source.postRunHooks]);
+  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);
   return Object.freeze(out);
 }
 function freezeMetadataValue(value) {
@@ -615,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 ?? []
@@ -649,7 +652,6 @@ function defineSandboxEnvironment(env) {
   return defineWorkflow({
     ...env.description !== undefined ? { description: env.description } : {},
     snapshots: env.snapshots ?? { saveLatest: true },
-    memory: env.memory ?? false,
     run: async (_ctx, sandbox) => env.setup(sandbox)
   });
 }
@@ -800,15 +802,18 @@ class AgentComposeClient {
   invoke(name, input, opts) {
     const parentRunId = opts?.parentRunId === undefined ? detectAmbientParentRunId() : opts.parentRunId;
     const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    const headers = {};
+    if (opts?.idempotencyKey)
+      headers["Idempotency-Key"] = opts.idempotencyKey;
     return this.fetch(templatePath(factorySlug, name, "invoke"), {
       method: "POST",
+      ...opts?.idempotencyKey ? { headers } : {},
       body: {
         input,
         ...opts?.snapshots !== undefined ? { snapshots: opts.snapshots } : {},
         ...opts?.networkPolicy !== undefined ? { networkPolicy: opts.networkPolicy } : {},
         ...opts?.placeholders !== undefined ? { placeholders: opts.placeholders } : {},
-        ...opts?.memory !== undefined ? { memory: opts.memory } : {},
-        ...opts?.postRunHooks !== undefined ? { postRunHooks: opts.postRunHooks } : {},
+        ...opts?.size !== undefined ? { size: opts.size } : {},
         ...parentRunId ? { parentRunId } : {},
         ...opts?.agentId ? { agentId: opts.agentId } : {}
       }
@@ -933,6 +938,56 @@ class AgentComposeClient {
     const body = await this.fetch(`/api/v1/workflows/${encodeURIComponent(runId)}/events`);
     return body.events;
   }
+  async listRunArtifacts(runId) {
+    const body = await this.fetch(`/api/v1/workflows/${encodeURIComponent(runId)}/artifacts`);
+    return body.artifacts.map((a) => ({
+      path: a.path,
+      factorySlug: a.factory_slug,
+      sizeBytes: a.size_bytes,
+      lastWriteAt: a.last_write_at,
+      preview: a.preview
+    }));
+  }
+  async putFactoryFile(path, content, opts) {
+    const factorySlug = opts?.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 wire = await this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/files/content?path=${encodeURIComponent(path)}`, {
+      method: "PUT",
+      body: content,
+      headers: {
+        "content-type": opts?.contentType ?? "text/plain; charset=utf-8",
+        ...runToken ? { "x-run-token": runToken } : {}
+      }
+    });
+    return {
+      path: wire.path,
+      contentHash: wire.content_hash,
+      sizeBytes: wire.size_bytes,
+      created: wire.created
+    };
+  }
+  async getFactoryFile(path, opts) {
+    const factorySlug = opts?.factorySlug ?? (typeof process !== "undefined" ? process.env?.AGENT_COMPOSE_FACTORY : undefined) ?? DEFAULT_FACTORY;
+    const q2 = new URLSearchParams({ path });
+    if (opts?.revision !== undefined)
+      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;
@@ -1068,7 +1123,7 @@ function workflowPlan(steps) {
 }
 
 // src/utils/bundler.ts
-var BUNDLER_VERSION = 1;
+var BUNDLER_VERSION = 2;
 
 class WorkflowSourceValidationError extends Error {
   constructor(message) {
@@ -1184,8 +1239,10 @@ async function bundleWorkflow(workflowPath, overrides) {
     ...inputSchema !== undefined ? { inputSchema } : {},
     ...outputSchema !== undefined ? { outputSchema } : {},
     ...metadata.snapshots !== undefined ? { snapshots: metadata.snapshots } : {},
-    ...metadata.memory !== undefined ? { memory: metadata.memory } : {},
-    ...metadata.postRunHooks !== undefined ? { postRunHooks: metadata.postRunHooks } : {}
+    ...metadata.resources !== undefined ? { resources: metadata.resources } : {},
+    ...metadata.connectors !== undefined ? { connectors: metadata.connectors } : {},
+    ...metadata.connectorOperation !== undefined ? { connectorOperation: metadata.connectorOperation } : {},
+    ...metadata.invokePolicy !== undefined ? { invokePolicy: metadata.invokePolicy } : {}
   };
 }
 function extractIOSchema(zodSchema) {
@@ -1812,9 +1869,9 @@ async function runControlPoller(opts) {
 }
 
 // src/agent/agent-loop.ts
-var DEFAULT_CLAUDE_MODEL = "claude-opus-4-7";
+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>/);
@@ -1871,8 +1928,9 @@ async function agentLoop(opts) {
   const label = opts.label ?? "agent";
   const logLabel = opts.label ?? "[Agent Loop]";
   const startedAt = Date.now();
-  const turnsPerIteration = opts.turnsPerIteration ?? 40;
-  const maxIterations = opts.maxIterations ?? 8;
+  const turnsPerIteration = opts.turnsPerIteration;
+  const maxIterations = opts.maxIterations ?? (turnsPerIteration === undefined ? 1 : 8);
+  let schemaRetriesLeft = 10;
   const processors = opts.processors ?? [];
   const requestContext = opts.requestContext ?? RequestContext.fromReserved({
     teamId: "",
@@ -1893,7 +1951,7 @@ async function agentLoop(opts) {
   if (!opts.runtime)
     throw new Error("agentLoop: opts.runtime is required");
   const client = opts.runtime({
-    maxTurns: turnsPerIteration,
+    ...turnsPerIteration !== undefined ? { maxTurns: turnsPerIteration } : {},
     allowedTools: opts.allowedTools ?? DEFAULT_ALLOWED_TOOLS,
     label: logLabel,
     cwd: opts.cwd,
@@ -2002,6 +2060,15 @@ async function agentLoop(opts) {
       }
       const procCtx = buildProcCtx(iteration + 1);
       let initialPrompt = opts.buildPrompt(lastStatus, iteration);
+      if (lastResponseValidationError) {
+        initialPrompt = `${initialPrompt}
+
+[response contract violation — fix and re-emit]
+Your previous <response> failed schema validation with these errors:
+${lastResponseValidationError.slice(0, 2000)}
+Re-emit the COMPLETE corrected <response> JSON now: every required field present, correctly named and typed (no omissions, no renames).`;
+        lastResponseValidationError = "";
+      }
       if (steerDecision) {
         const who = steerDecision.actor ? ` from ${steerDecision.actor}` : "";
         initialPrompt = `${initialPrompt}
@@ -2014,12 +2081,12 @@ async function agentLoop(opts) {
         throw new Error(`${logLabel} input ${inputVerdict.kind === "deny" ? "rejected" : "aborted"}: ${inputVerdict.reason}`);
       }
       const prompt = inputVerdict.value;
-      process.stdout.write(`${logLabel} iteration ${iteration + 1}/${maxIterations} · ${turnsPerIteration} turns
+      process.stdout.write(`${logLabel} iteration ${iteration + 1}/${maxIterations} · ${turnsPerIteration !== undefined ? `${turnsPerIteration} turns` : "harness-decided turns"}
 `);
       let responseText = "";
       for await (const rawMsg of client.sendMessage({
         prompt,
-        sessionId: iteration > 0 ? lastSessionId : undefined,
+        sessionId: lastSessionId ?? undefined,
         iteration: iteration + 1,
         ...opts.inbox ? { inboxStream: opts.inbox } : {}
       })) {
@@ -2035,7 +2102,15 @@ async function agentLoop(opts) {
         }
         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")
@@ -2078,6 +2153,8 @@ async function agentLoop(opts) {
 `);
             status = { ...status, exit_signal: false, blockers: ["No <response> block found — emit a <response> block with the required JSON fields before setting exit_signal: true"] };
             opts.onIteration?.(iteration + 1, status);
+            if (schemaRetriesLeft-- > 0)
+              iteration--;
             continue;
           }
           const parsed = validateResponse({ ...status, ...rawResponse });
@@ -2087,6 +2164,8 @@ raw: ${JSON.stringify(rawResponse).slice(0, 400)}
 `);
             status = { ...status, exit_signal: false, blockers: [`<response> schema validation failed: ${parsed.error.message}`] };
             opts.onIteration?.(iteration + 1, status);
+            if (schemaRetriesLeft-- > 0)
+              iteration--;
             continue;
           }
           response = parsed.data;
@@ -2107,9 +2186,16 @@ raw: ${JSON.stringify(rawResponse).slice(0, 400)}
         blockerStreak = null;
         continue;
       }
-      if (!status) {
+      if (!status && rawResponse === null) {
         if (++iterationsWithoutStatus >= STALL_ITERATIONS)
           throw new Error(`${logLabel} stalled: no <status> block after ${iterationsWithoutStatus} iterations`);
+        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;
+        }
       } else {
         iterationsWithoutStatus = 0;
       }
@@ -2124,6 +2210,12 @@ raw: ${JSON.stringify(rawResponse).slice(0, 400)}
       } else {
         blockerStreak = null;
       }
+      if (opts.responseSchema && rawResponse !== null && lastResponseValidationError !== "" && status?.exit_signal !== false && schemaRetriesLeft-- > 0) {
+        process.stdout.write(`${logLabel} response contract not yet satisfied — corrective re-prompt (${schemaRetriesLeft} retries left)
+`);
+        iteration--;
+        continue;
+      }
       if (iteration + 1 < maxIterations)
         process.stdout.write(`${logLabel} continuing to iteration ${iteration + 2}/${maxIterations}
 `);
@@ -2249,14 +2341,34 @@ function translateMessage(message) {
         numTurns: Number(message.num_turns ?? 0),
         timestamp: ts
       });
-    if (message.is_error || message.subtype === "error_during_execution") {
-      msgs.push({ type: "error", text: formatError(message.error ?? message.result ?? message.message), timestamp: ts });
+    if (message.subtype === "error_max_turns") {
+      msgs.push({ type: "done", sessionId: String(message.session_id ?? ""), timestamp: ts });
+    } else if (message.is_error || message.subtype === "error_during_execution") {
+      const detail = message.error ?? message.result ?? message.message;
+      const text = detail !== undefined ? formatError(detail) : `${String(message.subtype ?? "unknown_error")} — raw result: ${JSON.stringify({ ...message, usage: undefined }).slice(0, 600)}`;
+      msgs.push({ type: "error", text, timestamp: ts });
     } else {
       msgs.push({ type: "done", sessionId: String(message.session_id ?? ""), timestamp: ts });
     }
   }
   return msgs;
 }
+var MODEL_TIERS = {
+  fable: "claude-fable-5",
+  opus: "claude-opus-4-8",
+  sonnet: "claude-sonnet-4-6",
+  haiku: "claude-haiku-4-5"
+};
+function resolveClaudeModel(model) {
+  if (!model)
+    return DEFAULT_CLAUDE_MODEL;
+  return MODEL_TIERS[model.toLowerCase()] ?? model;
+}
+function resolveThinking(model, thinking) {
+  if (model.startsWith("claude-fable") && thinking && thinking.type === "disabled")
+    return;
+  return thinking;
+}
 var DEFAULT_CLAUDE_PATH = "/usr/local/bin/claude";
 
 class ClaudeRunner {
@@ -2269,7 +2381,7 @@ class ClaudeRunner {
     this.config = config;
   }
   get model() {
-    return this.config.model ?? this.options.model ?? DEFAULT_CLAUDE_MODEL;
+    return resolveClaudeModel(this.config.model ?? this.options.model);
   }
   async gateToolCall(call, ctx) {
     const verdict = await runProcessorChain(this.options.processors ?? [], (p) => p.processToolCall, call, ctx);
@@ -2337,14 +2449,15 @@ class ClaudeRunner {
           tools: this.options.allowedTools,
           allowedTools: this.options.allowedTools,
           maxTurns: this.options.maxTurns,
-          model: this.config.model ?? this.options.model ?? DEFAULT_CLAUDE_MODEL,
+          model: this.model,
           outputFormat: this.options.outputFormat,
-          thinking: this.config.thinking,
+          thinking: resolveThinking(this.model, this.config.thinking),
           effort: this.config.effort,
           cwd: this.options.cwd,
           env: { ...process.env, ...this.config.env ?? {} },
           pathToClaudeCodeExecutable: this.config.pathToClaudeCodeExecutable ?? process.env.CLAUDE_CODE_EXECUTABLE ?? DEFAULT_CLAUDE_PATH,
           ...this.config.claudeMdContent ? { systemPrompt: { type: "preset", preset: "claude_code", append: this.config.claudeMdContent } } : {},
+          skills: this.config.skills ?? "all",
           resume: opts.sessionId,
           mcpServers: this.config.mcpServers,
           permissionMode: "acceptEdits",
@@ -2364,7 +2477,12 @@ class ClaudeRunner {
           inboxQueue.close();
       }
     } catch (err) {
-      yield { type: "error", text: formatError(err), timestamp: now2() };
+      const text = formatError(err);
+      if (/maximum number of turns/i.test(text)) {
+        yield { type: "done", sessionId: opts.sessionId ?? "", timestamp: now2() };
+      } else {
+        yield { type: "error", text, timestamp: now2() };
+      }
     } finally {
       inboxQueue?.close();
     }
@@ -2633,11 +2751,34 @@ var amp_default = createAmpRuntime();
 import { promises as fs2 } from "node:fs";
 import { dirname as dirname2 } from "node:path";
 import { spawn } from "node:child_process";
-import { Sandbox } from "e2b";
+import { Sandbox, SandboxNotFoundError, RateLimitError } from "e2b";
 import { Sandbox as Desktop } from "@e2b/desktop";
 import pRetry from "p-retry";
+
+// src/sandbox-errors.ts
+var SANDBOX_UNAVAILABLE_PREFIX = "[sandbox-unavailable";
+
+class SandboxUnavailableError extends Error {
+  retryable;
+  sandboxId;
+  constructor(detail, opts) {
+    super(`${SANDBOX_UNAVAILABLE_PREFIX}:${opts.retryable ? "retryable" : "terminal"}] ${detail}`);
+    this.name = "SandboxUnavailableError";
+    this.retryable = opts.retryable;
+    this.sandboxId = opts.sandboxId;
+  }
+}
+
+// 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 {
@@ -2667,6 +2808,33 @@ function makeSandboxProvider(sb) {
     kill: () => sb.kill()
   };
 }
+function e2bMaxSandboxMs() {
+  return Number(process.env.E2B_MAX_SANDBOX_MS) || 60 * 60 * 1000;
+}
+function isTransientSandboxError(error) {
+  if (error instanceof SandboxNotFoundError || error instanceof RateLimitError)
+    return true;
+  const message = error instanceof Error ? error.message : String(error ?? "");
+  return /paus|stopp|resum|transition|status(?:\s+code)?[:\s]+5\d\d\b|\b5\d\d\s+(?:internal|bad gateway|service|gateway)|\b429\b|ECONNRESET|ECONNREFUSED|ETIMEDOUT|socket hang up|fetch failed/i.test(message);
+}
+function withSandboxRetry(fn, shouldRetry = isTransientSandboxError) {
+  return pRetry(fn, { retries: 4, minTimeout: 400, factor: 2, shouldRetry });
+}
+function withSnapshotRetry(p) {
+  if (!p.snapshot)
+    return p;
+  const snapshot = p.snapshot.bind(p);
+  return { ...p, snapshot: () => withSandboxRetry(snapshot) };
+}
+function makeE2bSandboxProvider(sb) {
+  return {
+    ...makeSandboxProvider(sb),
+    async snapshot() {
+      const { snapshotId } = await sb.createSnapshot();
+      return { snapshotId };
+    }
+  };
+}
 function makeDesktopSandboxProvider(sb) {
   return {
     ...makeSandboxProvider(sb),
@@ -2724,43 +2892,104 @@ async function parseSseExecStream(body, opts) {
     throw new Error("Sandbox exec stream ended without an exit event");
   return { exitCode, stdout, stderr };
 }
+var DOT_SEGMENT_PATH_RE2 = ".*(?:^|/|%2[fF])(?:\\.|%2[eE]){2}(?:/|%2[fF]|$).*";
+var DOT_SEGMENT_RE = /(?:^|\/|%2f)(?:\.|%2e){2}(?:\/|%2f|$)/i;
+function assertSafePathPrefix(domain, prefix) {
+  if (!prefix.startsWith("/") || DOT_SEGMENT_RE.test(prefix)) {
+    throw new Error(`Invalid Tier-2 pathPrefix ${JSON.stringify(prefix)} for "${domain}": prefixes must start with "/" and contain no dot-segments`);
+  }
+}
+function toVercelNetworkPolicy(policy) {
+  if (typeof policy === "string" || !policy.allow || Array.isArray(policy.allow)) {
+    return policy;
+  }
+  const allow = {};
+  for (const [domain, rules] of Object.entries(policy.allow)) {
+    const translated = rules.flatMap((rule) => {
+      const { requestRules, ...rest } = rule;
+      const methods = requestRules?.methods ?? [];
+      const prefixes = requestRules?.pathPrefixes ?? [];
+      if (methods.length === 0 && prefixes.length === 0)
+        return [rest];
+      const methodMatch = methods.length > 0 ? { method: methods } : {};
+      if (prefixes.length === 0)
+        return [{ ...rest, match: methodMatch }];
+      for (const prefix of prefixes)
+        assertSafePathPrefix(domain, prefix);
+      return prefixes.map((prefix) => ({ ...rest, match: { ...methodMatch, path: { startsWith: prefix } } }));
+    });
+    const hasPathGate = rules.some((rule) => (rule.requestRules?.pathPrefixes?.length ?? 0) > 0);
+    allow[domain] = hasPathGate ? [{ match: { path: { regex: DOT_SEGMENT_PATH_RE2 } } }, ...translated] : translated;
+  }
+  return { ...policy, allow };
+}
+var VERCEL_MAX_TAGS = 5;
+function buildVercelTags(metadata) {
+  const tags = { ...metadata, executor: AGENT_COMPOSE_TAG };
+  const extras = Object.keys(tags).filter((k) => k !== "executor").sort();
+  for (const key of extras.slice(VERCEL_MAX_TAGS - 1))
+    delete tags[key];
+  return tags;
+}
 function makeVercelSandboxProvider(sb, globalEnvs) {
   const mergeEnvs = (cmdEnvs) => globalEnvs ? { ...globalEnvs, ...cmdEnvs } : cmdEnvs;
+  const asUnavailable = (err, retryable) => {
+    throw new SandboxUnavailableError(err instanceof Error ? err.message : String(err), { retryable, sandboxId: sb.name });
+  };
   return {
-    sandboxId: sb.sandboxId,
+    sandboxId: sb.name,
     commands: {
       async run(cmd, opts) {
         const signal = opts?.timeoutMs ? AbortSignal.timeout(opts.timeoutMs) : undefined;
         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 } : {} });
-        await pRetry(async (attempt) => {
-          const h = attempt === 1 ? handle : await sb.getCommand(handle.cmdId);
-          if (attempt > 1) {
-            stdout = "";
-            stderr = "";
-          }
-          for await (const log of h.logs()) {
-            if (log.stream === "stdout") {
-              stdout += log.data;
-              opts?.onStdout?.(log.data);
-            } else {
-              stderr += log.data;
-              opts?.onStderr?.(log.data);
+        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));
+        const collect = async () => {
+          await pRetry(async (attempt) => {
+            const h = attempt === 1 ? handle : await sb.getCommand(handle.cmdId);
+            if (attempt > 1) {
+              stdout = "";
+              stderr = "";
             }
-          }
-        }, { retries: 3, minTimeout: 1000, factor: 2 });
-        const finished = await handle.wait();
-        return { exitCode: finished.exitCode, stdout, stderr };
+            for await (const log of h.logs()) {
+              if (log.stream === "stdout") {
+                stdout += log.data;
+                opts?.onStdout?.(log.data);
+              } else {
+                stderr += log.data;
+                opts?.onStderr?.(log.data);
+              }
+            }
+          }, { 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 (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);
+        }
       }
     },
     files: {
       async write(path, content) {
-        await sb.writeFiles([{ path, content }]);
+        await sb.writeFiles([{ path, content }]).catch((err) => asUnavailable(err, true));
       }
     },
     async kill() {
       await sb.stop();
+      await sb.delete();
     },
     async snapshot() {
       const res = await sb.snapshot({ expiration: 0 });
@@ -2769,6 +2998,9 @@ function makeVercelSandboxProvider(sb, globalEnvs) {
         snapshotId: res.snapshotId,
         ...sizeBytes !== undefined ? { sizeBytes } : {}
       };
+    },
+    async updateNetworkPolicy(policy) {
+      await sb.update({ networkPolicy: toVercelNetworkPolicy(policy) });
     }
   };
 }
@@ -2820,8 +3052,11 @@ var SANDBOX_PROVIDERS = {
     create: async (opts, env) => {
       const { Sandbox: VercelSandbox } = await import("@vercel/sandbox");
       const creds = { token: env.VERCEL_ACCESS_TOKEN, teamId: env.VERCEL_TEAM_ID, projectId: env.VERCEL_PROJECT_ID };
-      const np = opts.networkPolicy;
-      const sb = await VercelSandbox.create(opts.template ? { source: { type: "snapshot", snapshotId: opts.template }, timeout: opts.timeoutMs, env: opts.envs, ...np ? { networkPolicy: np } : {}, ...creds } : { runtime: "node24", timeout: opts.timeoutMs, env: opts.envs, ...np ? { networkPolicy: np } : {}, ...creds });
+      const np = opts.networkPolicy ? { networkPolicy: toVercelNetworkPolicy(opts.networkPolicy) } : {};
+      const tags = buildVercelTags(opts.metadata);
+      const tmpl = opts.template ?? process.env.VERCEL_DEFAULT_SNAPSHOT;
+      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) => {
@@ -2831,7 +3066,10 @@ var SANDBOX_PROVIDERS = {
         teamId: process.env.VERCEL_TEAM_ID ?? "",
         projectId: process.env.VERCEL_PROJECT_ID ?? ""
       };
-      return makeVercelSandboxProvider(await VercelSandbox.get({ sandboxId, ...creds }));
+      const sb = await VercelSandbox.get({ name: sandboxId, ...creds }).catch((err) => {
+        throw new SandboxUnavailableError(err instanceof Error ? err.message : String(err), { retryable: true, sandboxId });
+      });
+      return makeVercelSandboxProvider(sb);
     },
     getActiveCount: async (env) => (await SANDBOX_PROVIDERS.vercel.listOwned(env)).length,
     listOwned: async (env) => {
@@ -2839,18 +3077,21 @@ var SANDBOX_PROVIDERS = {
       const creds = { token: env.VERCEL_ACCESS_TOKEN, teamId: env.VERCEL_TEAM_ID, projectId: env.VERCEL_PROJECT_ID };
       const since = Date.now() - VERCEL_VM_LIFETIME_WINDOW_MS;
       const out = [];
-      let until;
-      for (let page = 0;page < 50; page++) {
-        const { json } = await pRetry(() => VercelSandbox.list({ ...creds, limit: 200, since, ...until !== undefined ? { until } : {} }), { retries: 3, minTimeout: 500, factor: 2 });
-        for (const sb of json.sandboxes)
+      let cursor;
+      for (let page = 0;page < 200; page++) {
+        const result = await pRetry(() => VercelSandbox.list({ ...creds, limit: 50, sortBy: "createdAt", sortOrder: "desc", tags: { executor: AGENT_COMPOSE_TAG }, ...cursor !== undefined ? { cursor } : {} }), { retries: 3, minTimeout: 500, factor: 2 });
+        for (const sb of result.sandboxes) {
+          if (sb.createdAt < since)
+            return out;
           if (sb.status === "running") {
-            out.push({ sandboxId: sb.id, createdAt: new Date(sb.createdAt), metadata: {} });
+            out.push({ sandboxId: sb.name, createdAt: new Date(sb.createdAt), metadata: sb.tags ?? {} });
           }
-        if (json.pagination.next === null)
+        }
+        if (result.pagination.next === null)
           return out;
-        until = json.pagination.next;
+        cursor = result.pagination.next;
       }
-      throw new Error("Vercel listSandboxes exceeded 50 pages within the lifetime window — refuse to silently truncate");
+      throw new Error("Vercel listSandboxes exceeded 200 pages (10k sandboxes) within the lifetime window — refuse to silently truncate");
     },
     deleteSnapshot: async (snapshotId, env) => {
       const { Snapshot } = await import("@vercel/sandbox");
@@ -2861,12 +3102,16 @@ var SANDBOX_PROVIDERS = {
   },
   e2b: {
     requiredEnv: { E2B_API_KEY: "E2B API key — e2b.dev/dashboard" },
-    create: async ({ template, ...sandboxOpts }) => {
-      if (!template)
-        throw new Error("E2B provider requires an explicit `template` (Dockerfile-based — no default base image)");
-      return makeSandboxProvider(await Sandbox.create(template, sandboxOpts));
+    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.`);
+      }
+      const sandboxOpts = { ...rest, timeoutMs: Math.min(timeoutMs, maxMs) };
+      const tmpl = template ?? process.env.E2B_DEFAULT_TEMPLATE;
+      return makeE2bSandboxProvider(await (tmpl ? Sandbox.create(tmpl, sandboxOpts) : Sandbox.create(sandboxOpts)));
     },
-    reconnect: async (sandboxId) => makeSandboxProvider(await Sandbox.connect(sandboxId, { apiKey: process.env.E2B_API_KEY ?? "", timeoutMs: 3600000 })),
+    reconnect: async (sandboxId) => makeE2bSandboxProvider(await Sandbox.connect(sandboxId, { apiKey: process.env.E2B_API_KEY ?? "", timeoutMs: 3600000 })),
     killAll: async () => {
       const paginator = Sandbox.list({ query: { metadata: { executor: AGENT_COMPOSE_TAG } } });
       const sandboxes = [];
@@ -2892,14 +3137,17 @@ var SANDBOX_PROVIDERS = {
         }
       }
       return out;
+    },
+    deleteSnapshot: async (snapshotId, env) => {
+      await Sandbox.deleteSnapshot(snapshotId, { apiKey: env.E2B_API_KEY });
     }
   },
   "e2b-desktop": {
     requiredEnv: { E2B_API_KEY: "E2B API key — e2b.dev/dashboard" },
-    create: async ({ template, ...sandboxOpts }) => {
+    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, sandboxOpts));
+      return makeDesktopSandboxProvider(await Desktop.create(template, { ...rest, timeoutMs: Math.min(timeoutMs, e2bMaxSandboxMs()) }));
     }
   }
 };
@@ -2912,13 +3160,14 @@ async function createSandbox(provider, opts) {
     throw new Error(`Sandbox provider "${provider}" requires env vars:
 ${missing.join(`
 `)}`);
-  return def.create(opts, Object.fromEntries(Object.keys(def.requiredEnv).map((k) => [k, process.env[k]])));
+  const env = Object.fromEntries(Object.keys(def.requiredEnv).map((k) => [k, process.env[k]]));
+  return withSnapshotRetry(await def.create(opts, env));
 }
 async function reconnectSandbox(provider, sandboxId) {
   const def = SANDBOX_PROVIDERS[provider];
   if (!def?.reconnect)
     throw new Error(`Provider "${provider}" does not support reconnect`);
-  return def.reconnect(sandboxId);
+  return withSnapshotRetry(await withSandboxRetry(() => def.reconnect(sandboxId), (error) => error instanceof SandboxNotFoundError ? error.attemptNumber <= 1 : isTransientSandboxError(error)));
 }
 async function deleteSandboxSnapshot(provider, snapshotId) {
   const def = SANDBOX_PROVIDERS[provider];
@@ -3079,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`,
@@ -3396,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
@@ -3436,6 +3677,9 @@ function stepInputPath(stepIndex) {
 function requestContextPath(stepIndex) {
   return `/tmp/wf/request-context-${stepIndex}.json`;
 }
+function stepResultFilePath(token) {
+  return `/tmp/wf/step-result-${token}.json`;
+}
 // src/step-invocation/invoker.ts
 import { randomBytes as randomBytes2 } from "node:crypto";
 import { z as z10 } from "zod";
@@ -3491,6 +3735,18 @@ function parseStepResult(stdout, resultToken) {
     if (pauseLine && resultLine)
       break;
   }
+  const midLine = (prefix) => {
+    const at = stdout.indexOf(prefix);
+    if (at === -1)
+      return;
+    const end = stdout.indexOf(`
+`, at);
+    return stdout.slice(at, end === -1 ? undefined : end);
+  };
+  if (!pauseLine)
+    pauseLine = midLine(pausePrefix);
+  if (!resultLine)
+    resultLine = midLine(resultPrefix);
   if (pauseLine) {
     try {
       const raw = JSON.parse(pauseLine.slice(pausePrefix.length));
@@ -3578,17 +3834,35 @@ async function invokeStep(sandbox, request, opts) {
   };
   const stdoutSplitter = makeLineSplitter(opts?.onStdout, true);
   const stderrSplitter = makeLineSplitter(opts?.onStderr, false);
-  const result = await sandbox.commands.run(RUNNER_COMMAND, {
-    envs,
-    timeoutMs: 0,
-    ...stdoutSplitter.onChunk ? { onStdout: stdoutSplitter.onChunk } : {},
-    ...stderrSplitter.onChunk ? { onStderr: stderrSplitter.onChunk } : {}
-  });
+  let result;
+  try {
+    result = await sandbox.commands.run(RUNNER_COMMAND, {
+      envs,
+      timeoutMs: 0,
+      ...stdoutSplitter.onChunk ? { onStdout: stdoutSplitter.onChunk } : {},
+      ...stderrSplitter.onChunk ? { onStderr: stderrSplitter.onChunk } : {}
+    });
+  } catch (e) {
+    if (e instanceof SandboxUnavailableError)
+      throw e;
+    const ce = e;
+    result = {
+      stdout: ce.stdout ?? ce.result?.stdout ?? "",
+      stderr: ce.stderr ?? ce.result?.stderr ?? (e instanceof Error ? e.message : String(e)),
+      exitCode: ce.exitCode ?? ce.result?.exitCode ?? 1
+    };
+  }
   stdoutSplitter.flush();
   stderrSplitter.flush();
   const parsed = parseStepResult(result.stdout, resultToken);
   if (parsed)
     return parsed;
+  const fileRead = await sandbox.commands.run(`cat ${stepResultFilePath(resultToken)} 2>/dev/null || true`).catch(() => null);
+  if (fileRead?.stdout) {
+    const fromFile = parseStepResult(fileRead.stdout, resultToken);
+    if (fromFile)
+      return fromFile;
+  }
   if (result.exitCode !== 0) {
     const stderrTail = result.stderr.trim().slice(-2000);
     const stdoutTail = result.stdout.trim().slice(-2000);
@@ -3609,13 +3883,19 @@ ${details}` : ""}`,
       }
     };
   }
+  const tail = result.stdout.trim().slice(-500);
   return {
     ok: false,
-    error: { kind: "protocol", message: "no tokenised step result found on stdout" }
+    error: {
+      kind: "protocol",
+      message: `no tokenised step result on stdout or in the result file (runner exited 0 without emitting)${tail ? `
+stdout tail:
+${tail}` : ""}`
+    }
   };
 }
 // src/step-invocation/server.ts
-import { readFileSync } from "node:fs";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 function writeSentinelLine(line) {
   return new Promise((resolve, reject) => {
     process.stdout.write(line, (err) => {
@@ -3626,9 +3906,21 @@ function writeSentinelLine(line) {
     });
   });
 }
-function emitResult(token, payload) {
-  return writeSentinelLine(`${STEP_RESULT_PREFIX}${token}:${JSON.stringify(payload)}
+function persistSentinelFile(token, line) {
+  try {
+    mkdirSync("/tmp/wf", { recursive: true });
+    writeFileSync(stepResultFilePath(token), line);
+  } catch (err) {
+    process.stderr.write(`[step-server] result-file persist failed: ${err instanceof Error ? err.message : String(err)}
 `);
+  }
+}
+function emitResult(token, payload) {
+  const line = `${STEP_RESULT_PREFIX}${token}:${JSON.stringify(payload)}
+`;
+  persistSentinelFile(token, line);
+  return writeSentinelLine(`
+${line}`);
 }
 function emitPause(token, signal) {
   const body = JSON.stringify({
@@ -3636,8 +3928,11 @@ function emitPause(token, signal) {
     pauseRequest: signal.pauseRequest,
     ...signal.observability ? { observability: signal.observability } : {}
   });
-  return writeSentinelLine(`${STEP_PAUSE_PREFIX}${token}:${body}
-`);
+  const line = `${STEP_PAUSE_PREFIX}${token}:${body}
+`;
+  persistSentinelFile(token, line);
+  return writeSentinelLine(`
+${line}`);
 }
 function scrubProtocolEnvs() {
   for (const key of [
@@ -3709,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';
 
@@ -3824,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;
@@ -3908,6 +4367,7 @@ async function agent(opts) {
 }
 export {
   writeTool,
+  writeAgentContext,
   stepInputPath,
   serveStep,
   runWorkflowSteps,
@@ -3955,6 +4415,7 @@ export {
   bundleWorkflow,
   buildStepEnvs,
   buildInvokeChild,
+  buildAgentContextDoc,
   bashTool,
   assertDefaultExportIsDefineWorkflow,
   amp_default as ampRuntime,
@@ -3969,9 +4430,11 @@ export {
   TMP_DIR,
   StepValidationError,
   StepExecutionError,
+  SandboxUnavailableError,
   STEP_RESULT_PREFIX,
   STEP_PAUSE_PREFIX,
   STEP_ENV,
+  SANDBOX_UNAVAILABLE_PREFIX,
   ReservedKeyError,
   RequestContext,
   RUNNER_COMMAND,
@@ -3991,6 +4454,7 @@ export {
   AgentComposeError,
   AgentComposeClient,
   AGENT_COMPOSE_TAG,
+  AGENT_COMPOSE_MANUAL,
   AC_WORKFLOW_ID,
   AC_TEAM_ID,
   AC_RUN_ID,