@agent-compose/sdk 0.5.8 → 0.5.9

package/dist/index.js

@@ -330,6 +330,391 @@ class RequestContext {
   }
 }
 
+// src/pause/pause-core.ts
+import { createHash } from "node:crypto";
+
+// src/step-invocation/types.ts
+import { z as z3 } from "zod";
+var StepPauseRequestSchema = z3.object({
+  reason: z3.string().min(1),
+  kind: z3.enum(["decision", "sleep", "event", "custom"]),
+  payload: z3.record(z3.string(), z3.unknown()).optional(),
+  ttlMs: z3.number().int().positive().optional(),
+  correlationKey: z3.string().min(1).optional(),
+  snapshot: z3.boolean().optional()
+});
+
+class StepExecutionError extends Error {
+  kind;
+  exitCode;
+  constructor(error, stepLabel) {
+    super(`[${error.kind}] ${stepLabel}: ${error.message}`);
+    this.name = "StepExecutionError";
+    this.kind = error.kind;
+    this.exitCode = error.kind === "runner-exit" ? error.exitCode : undefined;
+  }
+}
+
+// src/active-step.ts
+import { AsyncLocalStorage } from "node:async_hooks";
+var activeStepStorage = new AsyncLocalStorage;
+var fallbackActive = null;
+var BRIDGE_KEY = Symbol.for("agent-compose.activeStep.bridge");
+function bridgeSlot() {
+  const g = globalThis;
+  return g[BRIDGE_KEY] ??= { state: null };
+}
+function makeState(step) {
+  return {
+    stepIndex: step.stepIndex,
+    nextAgentCallIndex: 0,
+    pauseOrdinalByScope: new Map
+  };
+}
+function currentState() {
+  return activeStepStorage.getStore() ?? bridgeSlot().state ?? fallbackActive;
+}
+async function runWithActiveStep(step, fn) {
+  return activeStepStorage.run(makeState(step), fn);
+}
+function setActiveStepBridge(step) {
+  const slot = bridgeSlot();
+  const prev = { state: slot.state };
+  slot.state = step ? makeState(step) : null;
+  return prev;
+}
+function restoreActiveStepBridge(prev) {
+  bridgeSlot().state = prev.state;
+}
+function getActiveStep() {
+  const state = currentState();
+  return state ? { stepIndex: state.stepIndex } : null;
+}
+function nextAgentCallInActiveStep() {
+  const state = currentState();
+  if (!state)
+    return null;
+  const callIndex = state.nextAgentCallIndex;
+  state.nextAgentCallIndex += 1;
+  return { stepIndex: state.stepIndex, callIndex };
+}
+function nextPauseOrdinalInActiveStep(scope) {
+  const state = currentState();
+  if (!state)
+    return null;
+  const next = state.pauseOrdinalByScope.get(scope) ?? 0;
+  state.pauseOrdinalByScope.set(scope, next + 1);
+  return next;
+}
+
+// src/pause/state-dir.ts
+import { promises as fs } from "node:fs";
+import { join as join2 } from "node:path";
+import { randomBytes } from "node:crypto";
+function getStateDir() {
+  return process.env.AGENT_COMPOSE_STATE_DIR ?? "/tmp/wf/state";
+}
+var checkpointsDir = () => join2(getStateDir(), "checkpoints");
+var pausesDir = () => join2(getStateDir(), "pauses");
+var agentStatePath = (agentInstanceId) => join2(getStateDir(), `agent-${agentInstanceId}.json`);
+var runtimeStatePath = (agentInstanceId) => join2(getStateDir(), `runtime-${agentInstanceId}.json`);
+var checkpointPath = (name) => join2(checkpointsDir(), `${name}.json`);
+var pausePath = (pauseId) => join2(pausesDir(), `${pauseId}.json`);
+var NAME_RE = /^[a-zA-Z0-9_][a-zA-Z0-9_.-]*$/;
+function assertSafeName(label, name) {
+  if (!NAME_RE.test(name)) {
+    throw new Error(`${label} name must match ${NAME_RE} (got ${JSON.stringify(name)})`);
+  }
+}
+function assertSafeCheckpointName(name) {
+  assertSafeName("checkpoint", name);
+}
+async function ensureDirs() {
+  await fs.mkdir(checkpointsDir(), { recursive: true });
+  await fs.mkdir(pausesDir(), { recursive: true });
+}
+async function atomicWriteJSON(path, value) {
+  await ensureDirs();
+  const tmp = `${path}.tmp.${randomBytes(6).toString("hex")}`;
+  const payload = JSON.stringify(value);
+  if (payload === undefined) {
+    throw new Error("pause state values must be JSON-serialisable");
+  }
+  const handle = await fs.open(tmp, "w");
+  try {
+    await handle.writeFile(payload, { encoding: "utf8" });
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  await fs.rename(tmp, path);
+}
+async function readJSON(path) {
+  try {
+    const raw = await fs.readFile(path, "utf8");
+    return JSON.parse(raw);
+  } catch (err) {
+    if (err.code === "ENOENT")
+      return null;
+    throw err;
+  }
+}
+async function readJSONWithPresence(path) {
+  try {
+    const raw = await fs.readFile(path, "utf8");
+    return { found: true, value: JSON.parse(raw) };
+  } catch (err) {
+    if (err.code === "ENOENT")
+      return { found: false };
+    throw err;
+  }
+}
+async function readAgentState(agentInstanceId) {
+  assertSafeName("agent", agentInstanceId);
+  return readJSON(agentStatePath(agentInstanceId));
+}
+async function writeAgentState(agentInstanceId, state) {
+  assertSafeName("agent", agentInstanceId);
+  await atomicWriteJSON(agentStatePath(agentInstanceId), state);
+}
+async function readRuntimeCheckpoint(agentInstanceId) {
+  assertSafeName("runtime", agentInstanceId);
+  return readJSON(runtimeStatePath(agentInstanceId));
+}
+async function writeRuntimeCheckpoint(agentInstanceId, blob) {
+  assertSafeName("runtime", agentInstanceId);
+  await atomicWriteJSON(runtimeStatePath(agentInstanceId), blob);
+}
+async function readCheckpoint(name) {
+  assertSafeCheckpointName(name);
+  return readJSONWithPresence(checkpointPath(name));
+}
+async function writeCheckpoint(name, value) {
+  assertSafeCheckpointName(name);
+  await atomicWriteJSON(checkpointPath(name), value);
+}
+function hasOwn(obj, key) {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+function validatePauseRecord(value, expectedPauseId) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`pause record ${expectedPauseId} is malformed: expected object`);
+  }
+  const record = value;
+  if (record.pauseId !== undefined && record.pauseId !== expectedPauseId) {
+    throw new Error(`pause record ${expectedPauseId} is malformed: pauseId mismatch`);
+  }
+  if (record.resolved === true) {
+    if (typeof record.expired !== "boolean") {
+      throw new Error(`pause record ${expectedPauseId} is malformed: resolved records require boolean expired`);
+    }
+    if (!hasOwn(record, "resumePayload") || record.resumePayload === undefined) {
+      throw new Error(`pause record ${expectedPauseId} is malformed: resolved records require resumePayload`);
+    }
+    return {
+      pauseId: expectedPauseId,
+      request: hasOwn(record, "request") ? record.request : null,
+      ...record
+    };
+  }
+  if (record.pauseId !== expectedPauseId) {
+    throw new Error(`pause record ${expectedPauseId} is malformed: unresolved records require matching pauseId`);
+  }
+  if (!hasOwn(record, "request") || record.request === undefined) {
+    throw new Error(`pause record ${expectedPauseId} is malformed: unresolved records require request`);
+  }
+  if (record.resolved !== undefined && record.resolved !== false) {
+    throw new Error(`pause record ${expectedPauseId} is malformed: resolved must be true, false, or absent`);
+  }
+  if (hasOwn(record, "expired") || hasOwn(record, "resumePayload")) {
+    throw new Error(`pause record ${expectedPauseId} is malformed: unresolved records must not include resolution fields`);
+  }
+  return record;
+}
+async function readPauseRecord(pauseId) {
+  assertSafeName("pause", pauseId);
+  const record = await readJSON(pausePath(pauseId));
+  return record === null ? null : validatePauseRecord(record, pauseId);
+}
+async function writePauseRecord(record) {
+  assertSafeName("pause", record.pauseId);
+  validatePauseRecord(record, record.pauseId);
+  await atomicWriteJSON(pausePath(record.pauseId), record);
+}
+
+// src/pause/errors.ts
+class PauseError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = new.target.name;
+  }
+}
+
+class PauseExpiredError extends PauseError {
+  code = "pause_expired";
+  constructor(message = "pause expired before it was resolved") {
+    super(message);
+  }
+}
+
+class PauseSchemaError extends PauseError {
+  code = "pause_schema";
+  issues;
+  constructor(message, issues) {
+    super(message);
+    this.issues = issues;
+  }
+}
+
+class PauseRequestError extends PauseError {
+  code = "pause_request";
+  constructor(message = "pause request is invalid") {
+    super(message);
+  }
+}
+
+// src/pause/pause-core.ts
+var PAUSE_SIGNAL_BRAND = Symbol.for("agent-compose.PauseSignal");
+
+class PauseSignal {
+  pauseId;
+  pauseRequest;
+  observability;
+  [PAUSE_SIGNAL_BRAND] = true;
+  constructor(pauseId, pauseRequest, observability) {
+    this.pauseId = pauseId;
+    this.pauseRequest = pauseRequest;
+    this.observability = observability;
+  }
+}
+function isPauseSignal(err) {
+  return typeof err === "object" && err !== null && err[PAUSE_SIGNAL_BRAND] === true;
+}
+function boundProcessorPause(boundary, scope) {
+  return (req) => {
+    if (!boundary) {
+      return Promise.reject(new PauseRequestError("ctx.pause is unavailable here: no pause boundary is wired (a processor can " + "only pause inside a sandboxed workflow step, not in a local/unit-test run)"));
+    }
+    return boundary(req, scope);
+  };
+}
+var PAUSE_NAMESPACE = "5f3e2b8a-0c41-4e9d-9a7b-6d2c1f8e3a40";
+function uuidToBytes(uuid) {
+  return Buffer.from(uuid.replace(/-/g, ""), "hex");
+}
+function bytesToUuid(b) {
+  const h = b.toString("hex");
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20, 32)}`;
+}
+function uuidv5(name, namespace) {
+  const hash = createHash("sha1").update(uuidToBytes(namespace)).update(Buffer.from(name, "utf8")).digest();
+  const bytes = Buffer.from(hash.subarray(0, 16));
+  bytes[6] = bytes[6] & 15 | 80;
+  bytes[8] = bytes[8] & 63 | 128;
+  return bytesToUuid(bytes);
+}
+function scopeOf(coord) {
+  return coord.agentScope ? `${coord.runId}:${coord.stepIndex}:${coord.agentScope.agentId}:${coord.agentScope.iteration}` : `${coord.runId}:${coord.stepIndex}:bare`;
+}
+var pauseOrdinalByScope = new Map;
+function nextPauseOrdinal(scope) {
+  const activeOrdinal = nextPauseOrdinalInActiveStep(scope);
+  if (activeOrdinal !== null)
+    return activeOrdinal;
+  const next = pauseOrdinalByScope.get(scope) ?? 0;
+  pauseOrdinalByScope.set(scope, next + 1);
+  return next;
+}
+function nextPauseId(coord) {
+  const scope = scopeOf(coord);
+  const ordinal = nextPauseOrdinal(scope);
+  return uuidv5(`${scope}:${ordinal}`, PAUSE_NAMESPACE);
+}
+function nonJsonPath(value, path = "$", seen = new Set) {
+  if (value === null)
+    return null;
+  const kind = typeof value;
+  if (kind === "string" || kind === "boolean")
+    return null;
+  if (kind === "number")
+    return Number.isFinite(value) ? null : path;
+  if (kind === "undefined" || kind === "bigint" || kind === "function" || kind === "symbol")
+    return path;
+  if (kind !== "object")
+    return path;
+  const obj = value;
+  if (seen.has(obj))
+    return path;
+  seen.add(obj);
+  if (Array.isArray(value)) {
+    for (let i = 0;i < value.length; i++) {
+      const child = nonJsonPath(value[i], `${path}[${i}]`, seen);
+      if (child)
+        return child;
+    }
+    seen.delete(obj);
+    return null;
+  }
+  const proto = Object.getPrototypeOf(obj);
+  if (proto !== Object.prototype && proto !== null)
+    return path;
+  for (const key of Reflect.ownKeys(obj)) {
+    if (typeof key !== "string")
+      return `${path}.${String(key)}`;
+    const desc = Object.getOwnPropertyDescriptor(obj, key);
+    if (!desc?.enumerable)
+      return `${path}.${key}`;
+    const child = nonJsonPath(value[key], `${path}.${key}`, seen);
+    if (child)
+      return child;
+  }
+  seen.delete(obj);
+  return null;
+}
+function toWireRequest(req, kind) {
+  const wire = {
+    reason: req.reason,
+    kind,
+    ...req.payload !== undefined ? { payload: req.payload } : {},
+    ...req.ttlMs !== undefined ? { ttlMs: req.ttlMs } : {},
+    ...req.correlationKey !== undefined ? { correlationKey: req.correlationKey } : {},
+    ...req.snapshot !== undefined ? { snapshot: req.snapshot } : {}
+  };
+  const parsed = StepPauseRequestSchema.safeParse(wire);
+  if (!parsed.success) {
+    throw new PauseRequestError(`pause request failed validation: ${parsed.error.message}`);
+  }
+  const badPath = nonJsonPath(parsed.data);
+  if (badPath) {
+    throw new PauseRequestError(`pause request must be JSON-serializable (invalid value at ${badPath})`);
+  }
+  return parsed.data;
+}
+async function corePause(req, coord, kind = "custom") {
+  const wire = toWireRequest(req, kind);
+  const pauseId = nextPauseId(coord);
+  const record = await readPauseRecord(pauseId);
+  if (record === null || record.resolved !== true) {
+    await writePauseRecord({ pauseId, request: wire });
+    throw new PauseSignal(pauseId, wire);
+  }
+  if (record.expired === true) {
+    const onExpiry = req.onExpiry ?? { mode: "throw" };
+    if (onExpiry.mode === "resolve")
+      return onExpiry.value;
+    throw new PauseExpiredError(`pause "${req.reason}" expired before it was resolved`);
+  }
+  const payload = record.resumePayload ?? null;
+  if (req.schema) {
+    const parsed = req.schema.safeParse(payload);
+    if (!parsed.success) {
+      throw new PauseSchemaError(`resume payload for pause "${req.reason}" failed schema validation: ${parsed.error.message}`, parsed.error.issues);
+    }
+    return parsed.data;
+  }
+  return payload;
+}
+
 // src/utils/errors.ts
 function formatError(err) {
   return err instanceof Error ? err.message : String(err);
@@ -441,12 +826,14 @@ class VercelRunner {
             apiKeyScopes: [],
             parentRunId: null
           });
+          const gateAgentId = this.options.agentId ?? "agent";
           const gate = await this.gateToolCall(call, {
             requestContext,
             abortSignal: execOpts.abortSignal ?? signal ?? new AbortController().signal,
             retryCount: 0,
-            agentId: this.options.agentId ?? "agent",
-            iteration
+            agentId: gateAgentId,
+            iteration,
+            pause: boundProcessorPause(this.options.pause, { agentId: gateAgentId, iteration })
           });
           if (gate.kind === "deny")
             return gate.reason;
@@ -520,7 +907,7 @@ async function listVercelRuntimeModels() {
   return models.filter((m) => m.modelType == null || m.modelType === "language").map((m) => ({ id: m.id, name: m.name })).sort((a, b) => a.id.localeCompare(b.id));
 }
 // src/types/workflow.ts
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 
 // src/workflow-steps/types.ts
 var WORKFLOW_BRAND = Symbol.for("@agent-compose/sdk.Workflow");
@@ -550,6 +937,8 @@ function extractMetadata(source) {
     out.connectorOperation = Object.freeze({ ...source.connectorOperation });
   if (source.invokePolicy !== undefined)
     out.invokePolicy = freezeMetadataValue(source.invokePolicy);
+  if (source.environmentBuild !== undefined)
+    out.environmentBuild = source.environmentBuild;
   return Object.freeze(out);
 }
 function freezeMetadataValue(value) {
@@ -601,7 +990,7 @@ function isWorkflow(value) {
 
 // src/types/workflow.ts
 function compileRunForm(def, metadata) {
-  const unknownSchema = z3.unknown();
+  const unknownSchema = z4.unknown();
   const inputSchema = def.input ?? unknownSchema;
   const outputSchema = def.output ?? unknownSchema;
   const step = {
@@ -617,7 +1006,6 @@ function compileRunForm(def, metadata) {
         setMetadata: stepCtx.setMetadata,
         step: stepCtx.step,
         agentEvents: stepCtx.agentEvents,
-        checkpoint: stepCtx.checkpoint,
         pause: stepCtx.pause,
         sleep: stepCtx.sleep,
         waitForEvent: stepCtx.waitForEvent,
@@ -651,7 +1039,9 @@ function defineSandboxEnvironment(env) {
   }
   return defineWorkflow({
     ...env.description !== undefined ? { description: env.description } : {},
+    ...env.resources !== undefined ? { resources: env.resources } : {},
     snapshots: env.snapshots ?? { saveLatest: true },
+    environmentBuild: true,
     run: async (_ctx, sandbox) => env.setup(sandbox)
   });
 }
@@ -662,6 +1052,7 @@ var Verdict = {
   abort: (reason) => ({ kind: "abort", reason })
 };
 // src/processors/builtins.ts
+import { z as z5 } from "zod";
 function denyTools(names) {
   const banned = new Set(names);
   return {
@@ -669,6 +1060,26 @@ function denyTools(names) {
     processToolCall: (call) => banned.has(call.toolName) ? Verdict.deny(`tool "${call.toolName}" is denied by policy`) : Verdict.continue(call)
   };
 }
+var ApprovalDecision = z5.object({
+  approved: z5.boolean(),
+  reason: z5.string().optional()
+});
+function humanApproval(opts) {
+  const gated = opts?.tools ? new Set(opts.tools) : null;
+  return {
+    name: "humanApproval",
+    async processToolCall(call, ctx) {
+      if (gated && !gated.has(call.toolName))
+        return Verdict.continue(call);
+      const decision = await ctx.pause({
+        reason: opts?.reason?.(call) ?? `Approve tool call: ${call.toolName}`,
+        payload: { tool: call.toolName, input: call.toolInput, toolUseId: call.toolUseId },
+        schema: ApprovalDecision
+      });
+      return decision.approved ? Verdict.continue(call) : Verdict.deny(decision.reason ?? `tool "${call.toolName}" denied by human reviewer`);
+    }
+  };
+}
 function requireScope(required) {
   return {
     name: "requireScope",
@@ -1063,6 +1474,22 @@ class AgentComposeClient {
     const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
     return this.fetch(templatePath(factorySlug, workflowName, "secrets", key), { method: "DELETE" });
   }
+  setFactorySecret(key, value, opts) {
+    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    return this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/secrets`, {
+      method: "POST",
+      body: { key, value }
+    });
+  }
+  async listFactorySecrets(opts) {
+    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    const body = await this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/secrets`);
+    return body.secrets.map((s) => ({ key: s.secretKey, createdAt: s.createdAt, updatedAt: s.updatedAt }));
+  }
+  deleteFactorySecret(key, opts) {
+    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    return this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/secrets/${encodeURIComponent(key)}`, { method: "DELETE" });
+  }
   createApiKey(input) {
     return this.fetch("/api-keys", { method: "POST", body: input });
   }
@@ -1101,7 +1528,7 @@ class AgentComposeClient {
   }
 }
 // src/utils/bundler.ts
-import { createHash } from "node:crypto";
+import { createHash as createHash2 } from "node:crypto";
 import { parse as babelParse } from "@babel/parser";
 
 // src/utils/source-loader.ts
@@ -1210,7 +1637,7 @@ function findDefaultExportExpression(body) {
   return null;
 }
 function sha256(text) {
-  return createHash("sha256").update(text, "utf8").digest("hex");
+  return createHash2("sha256").update(text, "utf8").digest("hex");
 }
 async function bundleWorkflow(workflowPath, overrides) {
   const label = `"${workflowPath}"`;
@@ -1242,16 +1669,17 @@ async function bundleWorkflow(workflowPath, overrides) {
     ...metadata.resources !== undefined ? { resources: metadata.resources } : {},
     ...metadata.connectors !== undefined ? { connectors: metadata.connectors } : {},
     ...metadata.connectorOperation !== undefined ? { connectorOperation: metadata.connectorOperation } : {},
-    ...metadata.invokePolicy !== undefined ? { invokePolicy: metadata.invokePolicy } : {}
+    ...metadata.invokePolicy !== undefined ? { invokePolicy: metadata.invokePolicy } : {},
+    ...metadata.environmentBuild !== undefined ? { environmentBuild: metadata.environmentBuild } : {}
   };
 }
 function extractIOSchema(zodSchema) {
   let json;
   try {
-    const z4 = __require("zod");
-    if (!z4.toJSONSchema)
+    const z6 = __require("zod");
+    if (!z6.toJSONSchema)
       return;
-    json = z4.toJSONSchema(zodSchema);
+    json = z6.toJSONSchema(zodSchema);
   } catch {
     return;
   }
@@ -1284,26 +1712,26 @@ function extractIOSchema(zodSchema) {
   return out;
 }
 // src/utils/schemas.ts
-import { z as z4 } from "zod";
-var AgentStatusSchema = z4.object({
-  summary: z4.string(),
-  completed: z4.array(z4.string()),
-  blockers: z4.array(z4.string()),
-  exit_signal: z4.boolean(),
-  needs_input: z4.boolean().optional(),
-  question: z4.string().optional()
+import { z as z6 } from "zod";
+var AgentStatusSchema = z6.object({
+  summary: z6.string(),
+  completed: z6.array(z6.string()),
+  blockers: z6.array(z6.string()),
+  exit_signal: z6.boolean(),
+  needs_input: z6.boolean().optional(),
+  question: z6.string().optional()
 });
 // src/runtimes/claude.ts
 import { query } from "@anthropic-ai/claude-agent-sdk";
 
 // src/agent/agent-loop.ts
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 
 // src/agent/protocol.ts
-import { z as z5 } from "zod";
-var AgentMessageSchema = z5.object({
-  type: z5.enum(["init", "text", "thinking", "tool_use", "tool_result", "done", "error", "usage"]),
-  timestamp: z5.string()
+import { z as z7 } from "zod";
+var AgentMessageSchema = z7.object({
+  type: z7.enum(["init", "text", "thinking", "tool_use", "tool_result", "done", "error", "usage"]),
+  timestamp: z7.string()
 }).passthrough();
 function parseAgentResponse(text) {
   const match = text.match(/<response>([\s\S]*?)<\/response>/);
@@ -1320,170 +1748,33 @@ function parseAgentResponse(text) {
 import { randomUUID } from "node:crypto";
 
 // src/pause/manager.ts
-import { z as z6 } from "zod";
-
-// src/pause/state-dir.ts
-import { promises as fs } from "node:fs";
-import { join as join2 } from "node:path";
-import { randomBytes } from "node:crypto";
-function getStateDir() {
-  return process.env.AGENT_COMPOSE_STATE_DIR ?? "/tmp/wf/state";
-}
-var checkpointsDir = () => join2(getStateDir(), "checkpoints");
-var pausesDir = () => join2(getStateDir(), "pauses");
-var agentStatePath = (agentInstanceId) => join2(getStateDir(), `agent-${agentInstanceId}.json`);
-var runtimeStatePath = (agentInstanceId) => join2(getStateDir(), `runtime-${agentInstanceId}.json`);
-var checkpointPath = (name) => join2(checkpointsDir(), `${name}.json`);
-var pausePath = (pauseId) => join2(pausesDir(), `${pauseId}.json`);
-var NAME_RE = /^[a-zA-Z0-9_][a-zA-Z0-9_.-]*$/;
-function assertSafeName(label, name) {
-  if (!NAME_RE.test(name)) {
-    throw new Error(`${label} name must match ${NAME_RE} (got ${JSON.stringify(name)})`);
-  }
-}
-function assertSafeCheckpointName(name) {
-  assertSafeName("checkpoint", name);
-}
-async function ensureDirs() {
-  await fs.mkdir(checkpointsDir(), { recursive: true });
-  await fs.mkdir(pausesDir(), { recursive: true });
-}
-async function atomicWriteJSON(path, value) {
-  await ensureDirs();
-  const tmp = `${path}.tmp.${randomBytes(6).toString("hex")}`;
-  const payload = JSON.stringify(value);
-  if (payload === undefined) {
-    throw new Error("pause state values must be JSON-serialisable");
-  }
-  const handle = await fs.open(tmp, "w");
-  try {
-    await handle.writeFile(payload, { encoding: "utf8" });
-    await handle.sync();
-  } finally {
-    await handle.close();
-  }
-  await fs.rename(tmp, path);
-}
-async function readJSON(path) {
-  try {
-    const raw = await fs.readFile(path, "utf8");
-    return JSON.parse(raw);
-  } catch (err) {
-    if (err.code === "ENOENT")
-      return null;
-    throw err;
-  }
-}
-async function readJSONWithPresence(path) {
-  try {
-    const raw = await fs.readFile(path, "utf8");
-    return { found: true, value: JSON.parse(raw) };
-  } catch (err) {
-    if (err.code === "ENOENT")
-      return { found: false };
-    throw err;
-  }
-}
-async function readAgentState(agentInstanceId) {
-  assertSafeName("agent", agentInstanceId);
-  return readJSON(agentStatePath(agentInstanceId));
-}
-async function writeAgentState(agentInstanceId, state) {
-  assertSafeName("agent", agentInstanceId);
-  await atomicWriteJSON(agentStatePath(agentInstanceId), state);
-}
-async function readRuntimeCheckpoint(agentInstanceId) {
-  assertSafeName("runtime", agentInstanceId);
-  return readJSON(runtimeStatePath(agentInstanceId));
-}
-async function writeRuntimeCheckpoint(agentInstanceId, blob) {
-  assertSafeName("runtime", agentInstanceId);
-  await atomicWriteJSON(runtimeStatePath(agentInstanceId), blob);
-}
-async function readCheckpoint(name) {
-  assertSafeCheckpointName(name);
-  return readJSONWithPresence(checkpointPath(name));
-}
-async function writeCheckpoint(name, value) {
-  assertSafeCheckpointName(name);
-  await atomicWriteJSON(checkpointPath(name), value);
-}
-function hasOwn(obj, key) {
-  return Object.prototype.hasOwnProperty.call(obj, key);
-}
-function validatePauseRecord(value, expectedPauseId) {
-  if (value === null || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error(`pause record ${expectedPauseId} is malformed: expected object`);
-  }
-  const record = value;
-  if (record.pauseId !== undefined && record.pauseId !== expectedPauseId) {
-    throw new Error(`pause record ${expectedPauseId} is malformed: pauseId mismatch`);
-  }
-  if (record.resolved === true) {
-    if (typeof record.expired !== "boolean") {
-      throw new Error(`pause record ${expectedPauseId} is malformed: resolved records require boolean expired`);
-    }
-    if (!hasOwn(record, "resumePayload") || record.resumePayload === undefined) {
-      throw new Error(`pause record ${expectedPauseId} is malformed: resolved records require resumePayload`);
-    }
-    return {
-      pauseId: expectedPauseId,
-      request: hasOwn(record, "request") ? record.request : null,
-      ...record
-    };
-  }
-  if (record.pauseId !== expectedPauseId) {
-    throw new Error(`pause record ${expectedPauseId} is malformed: unresolved records require matching pauseId`);
-  }
-  if (!hasOwn(record, "request") || record.request === undefined) {
-    throw new Error(`pause record ${expectedPauseId} is malformed: unresolved records require request`);
-  }
-  if (record.resolved !== undefined && record.resolved !== false) {
-    throw new Error(`pause record ${expectedPauseId} is malformed: resolved must be true, false, or absent`);
-  }
-  if (hasOwn(record, "expired") || hasOwn(record, "resumePayload")) {
-    throw new Error(`pause record ${expectedPauseId} is malformed: unresolved records must not include resolution fields`);
-  }
-  return record;
-}
-async function readPauseRecord(pauseId) {
-  assertSafeName("pause", pauseId);
-  const record = await readJSON(pausePath(pauseId));
-  return record === null ? null : validatePauseRecord(record, pauseId);
-}
-async function writePauseRecord(record) {
-  assertSafeName("pause", record.pauseId);
-  validatePauseRecord(record, record.pauseId);
-  await atomicWriteJSON(pausePath(record.pauseId), record);
-}
-
-// src/pause/manager.ts
+import { z as z8 } from "zod";
 var AGENT_LOOP_STATE_SCHEMA_VERSION = 2;
-var SUPPORTED_AGENT_LOOP_STATE_VERSIONS = z6.union([z6.literal(1), z6.literal(2)]);
-var RunningAgentLoopStateSchema = z6.object({
+var SUPPORTED_AGENT_LOOP_STATE_VERSIONS = z8.union([z8.literal(1), z8.literal(2)]);
+var RunningAgentLoopStateSchema = z8.object({
   schemaVersion: SUPPORTED_AGENT_LOOP_STATE_VERSIONS,
-  phase: z6.literal("running"),
-  iteration: z6.number().int().nonnegative(),
-  completedIterations: z6.number().int().nonnegative(),
-  lastSessionId: z6.string(),
+  phase: z8.literal("running"),
+  iteration: z8.number().int().nonnegative(),
+  completedIterations: z8.number().int().nonnegative(),
+  lastSessionId: z8.string(),
   lastStatus: AgentStatusSchema.nullable(),
-  lastResponseText: z6.string(),
-  lastResponseValidationError: z6.string(),
-  iterationsWithoutStatus: z6.number().int().nonnegative(),
-  blockerStreak: z6.object({ key: z6.string(), count: z6.number().int().nonnegative() }).nullable(),
-  pendingSteerPause: z6.object({ reason: z6.string(), correlationKey: z6.string().nullable(), at: z6.number().int() }).nullable().default(null)
+  lastResponseText: z8.string(),
+  lastResponseValidationError: z8.string(),
+  iterationsWithoutStatus: z8.number().int().nonnegative(),
+  blockerStreak: z8.object({ key: z8.string(), count: z8.number().int().nonnegative() }).nullable(),
+  pendingSteerPause: z8.object({ reason: z8.string(), correlationKey: z8.string().nullable(), at: z8.number().int(), payload: z8.record(z8.string(), z8.unknown()).optional() }).nullable().default(null)
 });
-var SettledAgentLoopStateSchema = z6.object({
+var SettledAgentLoopStateSchema = z8.object({
   schemaVersion: SUPPORTED_AGENT_LOOP_STATE_VERSIONS,
-  phase: z6.literal("settled"),
-  result: z6.object({
-    sessionId: z6.string(),
+  phase: z8.literal("settled"),
+  result: z8.object({
+    sessionId: z8.string(),
     lastStatus: AgentStatusSchema.nullable(),
-    iterations: z6.number().int().nonnegative(),
-    response: z6.unknown().optional()
+    iterations: z8.number().int().nonnegative(),
+    response: z8.unknown().optional()
   })
 });
-var AgentLoopStateSchema = z6.discriminatedUnion("phase", [
+var AgentLoopStateSchema = z8.discriminatedUnion("phase", [
   RunningAgentLoopStateSchema,
   SettledAgentLoopStateSchema
 ]);
@@ -1528,287 +1819,48 @@ class PauseManager {
     const runtimeBlob = await readRuntimeCheckpoint(this.agentId);
     if (runtimeBlob !== null && !runtime.restoreCheckpoint) {
       throw new Error(`runtime checkpoint exists for resumed agentId=${this.agentId}, but runtime cannot restore it`);
-    }
-    if (runtime.restoreCheckpoint && runtimeBlob === null) {
-      throw new Error(`missing runtime checkpoint for resumed agentId=${this.agentId}`);
-    }
-    if (runtimeBlob !== null)
-      runtime.restoreCheckpoint?.(runtimeBlob);
-    return { kind: "running", state: toProgressState(state) };
-  }
-  async saveRunningAgentLoop(state, runtime) {
-    await writeAgentState(this.agentId, {
-      schemaVersion: AGENT_LOOP_STATE_SCHEMA_VERSION,
-      phase: "running",
-      ...state
-    });
-    if (runtime.captureCheckpoint) {
-      const blob = runtime.captureCheckpoint();
-      if (blob !== undefined)
-        await writeRuntimeCheckpoint(this.agentId, blob);
-    }
-  }
-  async saveSettledAgentLoop(result) {
-    await writeAgentState(this.agentId, {
-      schemaVersion: AGENT_LOOP_STATE_SCHEMA_VERSION,
-      phase: "settled",
-      result: {
-        sessionId: result.sessionId,
-        lastStatus: result.lastStatus,
-        iterations: result.iterations,
-        ...result.response !== undefined ? { response: result.response } : {}
-      }
-    });
-  }
-}
-
-// src/pause/pause-core.ts
-import { createHash as createHash2 } from "node:crypto";
-
-// src/step-invocation/types.ts
-import { z as z7 } from "zod";
-var StepPauseRequestSchema = z7.object({
-  reason: z7.string().min(1),
-  kind: z7.enum(["decision", "sleep", "event", "custom"]),
-  payload: z7.record(z7.string(), z7.unknown()).optional(),
-  ttlMs: z7.number().int().positive().optional(),
-  correlationKey: z7.string().min(1).optional(),
-  snapshot: z7.boolean().optional()
-});
-
-class StepExecutionError extends Error {
-  kind;
-  exitCode;
-  constructor(error, stepLabel) {
-    super(`[${error.kind}] ${stepLabel}: ${error.message}`);
-    this.name = "StepExecutionError";
-    this.kind = error.kind;
-    this.exitCode = error.kind === "runner-exit" ? error.exitCode : undefined;
-  }
-}
-
-// src/active-step.ts
-import { AsyncLocalStorage } from "node:async_hooks";
-var activeStepStorage = new AsyncLocalStorage;
-var fallbackActive = null;
-var BRIDGE_KEY = Symbol.for("agent-compose.activeStep.bridge");
-function bridgeSlot() {
-  const g = globalThis;
-  return g[BRIDGE_KEY] ??= { state: null };
-}
-function makeState(step) {
-  return {
-    stepIndex: step.stepIndex,
-    nextAgentCallIndex: 0,
-    pauseOrdinalByScope: new Map
-  };
-}
-function currentState() {
-  return activeStepStorage.getStore() ?? bridgeSlot().state ?? fallbackActive;
-}
-async function runWithActiveStep(step, fn) {
-  return activeStepStorage.run(makeState(step), fn);
-}
-function setActiveStepBridge(step) {
-  const slot = bridgeSlot();
-  const prev = { state: slot.state };
-  slot.state = step ? makeState(step) : null;
-  return prev;
-}
-function restoreActiveStepBridge(prev) {
-  bridgeSlot().state = prev.state;
-}
-function getActiveStep() {
-  const state = currentState();
-  return state ? { stepIndex: state.stepIndex } : null;
-}
-function nextAgentCallInActiveStep() {
-  const state = currentState();
-  if (!state)
-    return null;
-  const callIndex = state.nextAgentCallIndex;
-  state.nextAgentCallIndex += 1;
-  return { stepIndex: state.stepIndex, callIndex };
-}
-function nextPauseOrdinalInActiveStep(scope) {
-  const state = currentState();
-  if (!state)
-    return null;
-  const next = state.pauseOrdinalByScope.get(scope) ?? 0;
-  state.pauseOrdinalByScope.set(scope, next + 1);
-  return next;
-}
-
-// src/pause/errors.ts
-class PauseError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = new.target.name;
-  }
-}
-
-class PauseExpiredError extends PauseError {
-  code = "pause_expired";
-  constructor(message = "pause expired before it was resolved") {
-    super(message);
-  }
-}
-
-class PauseSchemaError extends PauseError {
-  code = "pause_schema";
-  issues;
-  constructor(message, issues) {
-    super(message);
-    this.issues = issues;
-  }
-}
-
-class PauseRequestError extends PauseError {
-  code = "pause_request";
-  constructor(message = "pause request is invalid") {
-    super(message);
-  }
-}
-
-// src/pause/pause-core.ts
-var PAUSE_SIGNAL_BRAND = Symbol.for("agent-compose.PauseSignal");
-
-class PauseSignal {
-  pauseId;
-  pauseRequest;
-  observability;
-  [PAUSE_SIGNAL_BRAND] = true;
-  constructor(pauseId, pauseRequest, observability) {
-    this.pauseId = pauseId;
-    this.pauseRequest = pauseRequest;
-    this.observability = observability;
-  }
-}
-function isPauseSignal(err) {
-  return typeof err === "object" && err !== null && err[PAUSE_SIGNAL_BRAND] === true;
-}
-var PAUSE_NAMESPACE = "5f3e2b8a-0c41-4e9d-9a7b-6d2c1f8e3a40";
-function uuidToBytes(uuid) {
-  return Buffer.from(uuid.replace(/-/g, ""), "hex");
-}
-function bytesToUuid(b) {
-  const h = b.toString("hex");
-  return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20, 32)}`;
-}
-function uuidv5(name, namespace) {
-  const hash = createHash2("sha1").update(uuidToBytes(namespace)).update(Buffer.from(name, "utf8")).digest();
-  const bytes = Buffer.from(hash.subarray(0, 16));
-  bytes[6] = bytes[6] & 15 | 80;
-  bytes[8] = bytes[8] & 63 | 128;
-  return bytesToUuid(bytes);
-}
-function scopeOf(coord) {
-  return coord.agentScope ? `${coord.runId}:${coord.stepIndex}:${coord.agentScope.agentId}:${coord.agentScope.iteration}` : `${coord.runId}:${coord.stepIndex}:bare`;
-}
-var pauseOrdinalByScope = new Map;
-function nextPauseOrdinal(scope) {
-  const activeOrdinal = nextPauseOrdinalInActiveStep(scope);
-  if (activeOrdinal !== null)
-    return activeOrdinal;
-  const next = pauseOrdinalByScope.get(scope) ?? 0;
-  pauseOrdinalByScope.set(scope, next + 1);
-  return next;
-}
-function nextPauseId(coord) {
-  const scope = scopeOf(coord);
-  const ordinal = nextPauseOrdinal(scope);
-  return uuidv5(`${scope}:${ordinal}`, PAUSE_NAMESPACE);
-}
-function nonJsonPath(value, path = "$", seen = new Set) {
-  if (value === null)
-    return null;
-  const kind = typeof value;
-  if (kind === "string" || kind === "boolean")
-    return null;
-  if (kind === "number")
-    return Number.isFinite(value) ? null : path;
-  if (kind === "undefined" || kind === "bigint" || kind === "function" || kind === "symbol")
-    return path;
-  if (kind !== "object")
-    return path;
-  const obj = value;
-  if (seen.has(obj))
-    return path;
-  seen.add(obj);
-  if (Array.isArray(value)) {
-    for (let i = 0;i < value.length; i++) {
-      const child = nonJsonPath(value[i], `${path}[${i}]`, seen);
-      if (child)
-        return child;
-    }
-    seen.delete(obj);
-    return null;
-  }
-  const proto = Object.getPrototypeOf(obj);
-  if (proto !== Object.prototype && proto !== null)
-    return path;
-  for (const key of Reflect.ownKeys(obj)) {
-    if (typeof key !== "string")
-      return `${path}.${String(key)}`;
-    const desc = Object.getOwnPropertyDescriptor(obj, key);
-    if (!desc?.enumerable)
-      return `${path}.${key}`;
-    const child = nonJsonPath(value[key], `${path}.${key}`, seen);
-    if (child)
-      return child;
-  }
-  seen.delete(obj);
-  return null;
-}
-function toWireRequest(req, kind) {
-  const wire = {
-    reason: req.reason,
-    kind,
-    ...req.payload !== undefined ? { payload: req.payload } : {},
-    ...req.ttlMs !== undefined ? { ttlMs: req.ttlMs } : {},
-    ...req.correlationKey !== undefined ? { correlationKey: req.correlationKey } : {},
-    ...req.snapshot !== undefined ? { snapshot: req.snapshot } : {}
-  };
-  const parsed = StepPauseRequestSchema.safeParse(wire);
-  if (!parsed.success) {
-    throw new PauseRequestError(`pause request failed validation: ${parsed.error.message}`);
-  }
-  const badPath = nonJsonPath(parsed.data);
-  if (badPath) {
-    throw new PauseRequestError(`pause request must be JSON-serializable (invalid value at ${badPath})`);
-  }
-  return parsed.data;
-}
-async function corePause(req, coord, kind = "custom") {
-  const wire = toWireRequest(req, kind);
-  const pauseId = nextPauseId(coord);
-  const record = await readPauseRecord(pauseId);
-  if (record === null || record.resolved !== true) {
-    await writePauseRecord({ pauseId, request: wire });
-    throw new PauseSignal(pauseId, wire);
-  }
-  if (record.expired === true) {
-    const onExpiry = req.onExpiry ?? { mode: "throw" };
-    if (onExpiry.mode === "resolve")
-      return onExpiry.value;
-    throw new PauseExpiredError(`pause "${req.reason}" expired before it was resolved`);
+    }
+    if (runtime.restoreCheckpoint && runtimeBlob === null) {
+      throw new Error(`missing runtime checkpoint for resumed agentId=${this.agentId}`);
+    }
+    if (runtimeBlob !== null)
+      runtime.restoreCheckpoint?.(runtimeBlob);
+    return { kind: "running", state: toProgressState(state) };
   }
-  const payload = record.resumePayload ?? null;
-  if (req.schema) {
-    const parsed = req.schema.safeParse(payload);
-    if (!parsed.success) {
-      throw new PauseSchemaError(`resume payload for pause "${req.reason}" failed schema validation: ${parsed.error.message}`, parsed.error.issues);
+  async saveRunningAgentLoop(state, runtime) {
+    await writeAgentState(this.agentId, {
+      schemaVersion: AGENT_LOOP_STATE_SCHEMA_VERSION,
+      phase: "running",
+      ...state
+    });
+    if (runtime.captureCheckpoint) {
+      const blob = runtime.captureCheckpoint();
+      if (blob !== undefined)
+        await writeRuntimeCheckpoint(this.agentId, blob);
     }
-    return parsed.data;
   }
-  return payload;
+  async saveSettledAgentLoop(result) {
+    await writeAgentState(this.agentId, {
+      schemaVersion: AGENT_LOOP_STATE_SCHEMA_VERSION,
+      phase: "settled",
+      result: {
+        sessionId: result.sessionId,
+        lastStatus: result.lastStatus,
+        iterations: result.iterations,
+        ...result.response !== undefined ? { response: result.response } : {}
+      }
+    });
+  }
 }
 
 // src/agent/steer-control.ts
-import { z as z8 } from "zod";
-var SteerDecisionSchema = z8.object({
-  message: z8.string().min(1),
-  actor: z8.string().nullish()
+import { z as z9 } from "zod";
+var SteerDecisionSchema = z9.object({
+  message: z9.string().min(1).optional(),
+  decision: z9.string().min(1).optional(),
+  actor: z9.string().nullish()
+}).transform((d) => ({ message: (d.message ?? d.decision ?? "").trim(), actor: d.actor ?? null })).refine((d) => d.message.length > 0, {
+  message: "a steer/resume answer needs a non-empty `message` or `decision`"
 });
 var steerPending = new Map;
 function signalSteerPending(agentId, payload) {
@@ -1921,6 +1973,8 @@ function summarizeAgentMessage(msg) {
       return { type: "done", sessionId: msg.sessionId };
     case "error":
       return { type: "error", text: truncate(msg.text) };
+    case "plan":
+      return { type: "plan", entries: msg.entries };
   }
 }
 async function agentLoop(opts) {
@@ -1946,7 +2000,8 @@ async function agentLoop(opts) {
     abortSignal: loopAbort.signal,
     retryCount: 0,
     agentId,
-    iteration
+    iteration,
+    pause: boundProcessorPause(opts.pause, { agentId, iteration })
   });
   if (!opts.runtime)
     throw new Error("agentLoop: opts.runtime is required");
@@ -1958,7 +2013,8 @@ async function agentLoop(opts) {
     processors,
     requestContext,
     agentId,
-    ...opts.responseSchema ? { outputFormat: { type: "json_schema", schema: z9.toJSONSchema(opts.responseSchema) } } : {}
+    ...opts.pause ? { pause: opts.pause } : {},
+    ...opts.responseSchema ? { outputFormat: { type: "json_schema", schema: z10.toJSONSchema(opts.responseSchema) } } : {}
   });
   if (processors.some((p) => p.processToolCall) && !client.supportsToolCallProcessor) {
     process.stderr.write(`${logLabel} processToolCall registered but runtime does not support pre-tool-use gating — hook is dormant
@@ -2052,6 +2108,7 @@ async function agentLoop(opts) {
           steerDecision = await opts.pause({
             reason: pendingSteerPause.reason,
             ...pendingSteerPause.correlationKey !== null ? { correlationKey: pendingSteerPause.correlationKey } : {},
+            ...pendingSteerPause.payload !== undefined ? { payload: pendingSteerPause.payload } : {},
             schema: SteerDecisionSchema
           }, { agentId, iteration });
           pendingSteerPause = null;
@@ -2088,6 +2145,7 @@ Re-emit the COMPLETE corrected <response> JSON now: every required field present
         prompt,
         sessionId: lastSessionId ?? undefined,
         iteration: iteration + 1,
+        signal: loopAbort.signal,
         ...opts.inbox ? { inboxStream: opts.inbox } : {}
       })) {
         const outputVerdict = await runProcessorChain(processors, (p) => p.processOutput, rawMsg, procCtx);
@@ -2120,6 +2178,19 @@ Re-emit the COMPLETE corrected <response> JSON now: every required field present
       }
       lastResponseText = responseText;
       let status = parseAgentStatus(responseText);
+      if (opts.pause && pendingSteerPause === null) {
+        const localPause = opts.consumeLocalPauseRequest?.() ?? null;
+        if (localPause) {
+          pendingSteerPause = {
+            reason: localPause.reason,
+            correlationKey: null,
+            ...localPause.options && localPause.options.length > 0 ? { payload: { options: localPause.options } } : {},
+            at: Date.now()
+          };
+          blockerStreak = null;
+          continue;
+        }
+      }
       const rawResponse = opts.responseSchema ? parseAgentResponse(responseText) ?? parseRawJsonResponse(responseText) : null;
       const validateResponse = (target) => {
         const parsed = opts.responseSchema.safeParse(target);
@@ -2405,12 +2476,15 @@ class ClaudeRunner {
         toolInput: pre.tool_input ?? {},
         toolUseId: toolUseId ?? `${pre.tool_name}-${Date.now()}`
       };
+      const gateAgentId = this.options.agentId ?? "agent";
+      const gateIteration = opts.iteration ?? 1;
       const gate = await this.gateToolCall(call, {
         requestContext,
         abortSignal: signal ?? opts.signal ?? new AbortController().signal,
         retryCount: 0,
-        agentId: this.options.agentId ?? "agent",
-        iteration: opts.iteration ?? 1
+        agentId: gateAgentId,
+        iteration: gateIteration,
+        pause: boundProcessorPause(this.options.pause, { agentId: gateAgentId, iteration: gateIteration })
       });
       if (gate.kind === "allow")
         return { hookSpecificOutput: { hookEventName: pre.hook_event_name, permissionDecision: "allow", updatedInput: gate.call.toolInput } };
@@ -2441,6 +2515,14 @@ class ClaudeRunner {
       })();
     }
     const promptForQuery = inboxQueue ?? opts.prompt;
+    const queryAbort = new AbortController;
+    const onLoopAbort = () => queryAbort.abort();
+    if (opts.signal) {
+      if (opts.signal.aborted)
+        queryAbort.abort();
+      else
+        opts.signal.addEventListener("abort", onLoopAbort, { once: true });
+    }
     try {
       let emittedAssistantText = false;
       for await (const message of query({
@@ -2454,7 +2536,8 @@ class ClaudeRunner {
           thinking: resolveThinking(this.model, this.config.thinking),
           effort: this.config.effort,
           cwd: this.options.cwd,
-          env: { ...process.env, ...this.config.env ?? {} },
+          abortController: queryAbort,
+          env: { ...process.env, ...this.config.env ?? {}, ...this.options.agentId ? { AGENT_COMPOSE_AGENT_ID: this.options.agentId } : {} },
           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",
@@ -2485,6 +2568,7 @@ class ClaudeRunner {
       }
     } finally {
       inboxQueue?.close();
+      opts.signal?.removeEventListener("abort", onLoopAbort);
     }
   }
 }
@@ -2495,12 +2579,295 @@ function createClaudeRuntime(config = {}) {
 }
 var claude_default = createClaudeRuntime();
 // src/runtimes/_cli-agent.ts
+import { ndJsonStream } from "@agentclientprotocol/sdk";
+
+// src/runtimes/_acp-client.ts
+import {
+  ClientSideConnection,
+  RequestError
+} from "@agentclientprotocol/sdk";
 function now3() {
   return new Date().toISOString();
 }
+var ACP_PROTOCOL_VERSION = 1;
+var OPTION_KIND_FOR_VERDICT = {
+  allow: ["allow_once", "allow_always"],
+  deny: ["reject_once", "reject_always"]
+};
+function contentBlockText(block) {
+  if (!block)
+    return "";
+  return block.type === "text" ? block.text : "";
+}
+function renderToolContent(content) {
+  const parts = [];
+  const diffs = [];
+  for (const block of content ?? []) {
+    if (block.type === "content") {
+      parts.push(contentBlockText(block.content));
+    } else if (block.type === "diff") {
+      diffs.push({ path: block.path, oldText: block.oldText ?? null, newText: block.newText });
+      const header = block.oldText == null ? `--- (new file)
++++ ${block.path}` : `--- ${block.path}
++++ ${block.path}`;
+      parts.push(`${header}
+${block.newText}`);
+    } else if (block.type === "terminal") {
+      parts.push(`[terminal ${block.terminalId}]`);
+    }
+  }
+  return { output: parts.filter((p) => p !== "").join(`
+`), diffs };
+}
+function mapLocations(locations) {
+  if (!locations || locations.length === 0)
+    return;
+  return locations.map((l) => l.line != null ? { path: l.path, line: l.line } : { path: l.path });
+}
+function terminalToolResult(args) {
+  const { output, diffs } = renderToolContent(args.content);
+  const locations = mapLocations(args.locations);
+  return {
+    type: "tool_result",
+    toolUseId: args.toolCallId,
+    output,
+    isError: args.status === "failed",
+    timestamp: args.timestamp,
+    ...diffs.length > 0 ? { diffs } : {},
+    ...locations ? { locations } : {}
+  };
+}
+function normalizeSessionUpdate(update) {
+  const ts = now3();
+  switch (update.sessionUpdate) {
+    case "agent_message_chunk":
+      return [{ type: "text", text: contentBlockText(update.content), timestamp: ts }];
+    case "agent_thought_chunk":
+      return [{ type: "thinking", text: contentBlockText(update.content), timestamp: ts }];
+    case "tool_call": {
+      const messages = [{
+        type: "tool_use",
+        toolName: update.title || update.kind || "tool",
+        toolInput: update.rawInput ?? {},
+        toolUseId: update.toolCallId,
+        timestamp: ts
+      }];
+      if (update.status === "completed" || update.status === "failed") {
+        messages.push(terminalToolResult({
+          toolCallId: update.toolCallId,
+          status: update.status,
+          content: update.content,
+          locations: update.locations,
+          timestamp: ts
+        }));
+      }
+      return messages;
+    }
+    case "tool_call_update": {
+      if (update.status !== "completed" && update.status !== "failed")
+        return [];
+      return [terminalToolResult({
+        toolCallId: update.toolCallId,
+        status: update.status,
+        content: update.content,
+        locations: update.locations,
+        timestamp: ts
+      })];
+    }
+    case "plan":
+      return [{
+        type: "plan",
+        entries: update.entries.map((e) => ({ content: e.content, priority: e.priority, status: e.status })),
+        timestamp: ts
+      }];
+    case "user_message_chunk":
+    case "available_commands_update":
+    case "current_mode_update":
+    case "usage_update":
+    case "plan_update":
+    case "plan_removed":
+    case "config_option_update":
+    case "session_info_update":
+      return [];
+    default:
+      return [];
+  }
+}
+
+class AcpClientPeer {
+  deps;
+  conn;
+  updates = new AsyncQueue;
+  sessionId;
+  pendingPause = null;
+  cancelled = false;
+  abortPrompt = null;
+  constructor(deps) {
+    this.deps = deps;
+    const handler = {
+      sessionUpdate: (params) => {
+        for (const msg of normalizeSessionUpdate(params.update))
+          this.updates.push(msg);
+      },
+      requestPermission: (params) => this.onRequestPermission(params)
+    };
+    this.conn = new ClientSideConnection((_agent) => handler, this.deps.stream);
+    if (this.deps.signal) {
+      if (this.deps.signal.aborted)
+        this.cancel();
+      else
+        this.deps.signal.addEventListener("abort", () => this.cancel(), { once: true });
+    }
+  }
+  async initialize() {
+    const res = await this.conn.initialize({
+      protocolVersion: ACP_PROTOCOL_VERSION,
+      clientCapabilities: {
+        fs: { readTextFile: false, writeTextFile: false },
+        terminal: false
+      }
+    });
+    return { protocolVersion: res.protocolVersion };
+  }
+  async startSession(cwd) {
+    const res = await this.conn.newSession({ cwd, mcpServers: [] });
+    this.sessionId = res.sessionId;
+    return res.sessionId;
+  }
+  async* prompt(text) {
+    if (!this.sessionId)
+      throw new Error("AcpClientPeer.prompt called before startSession");
+    const updates = new AsyncQueue;
+    this.updates = updates;
+    const aborted = new Promise((resolve) => {
+      this.abortPrompt = () => {
+        resolve();
+        updates.close();
+      };
+    });
+    if (this.cancelled)
+      this.abortPrompt();
+    const promptPromise = this.conn.prompt({ sessionId: this.sessionId, prompt: [{ type: "text", text }] }).then((res) => {
+      updates.close();
+      return { ok: true, res };
+    }, (err) => {
+      updates.close();
+      return { ok: false, err };
+    });
+    for await (const msg of updates) {
+      yield msg;
+    }
+    if (this.pendingPause !== null) {
+      const pause = this.pendingPause;
+      this.pendingPause = null;
+      this.abortPrompt = null;
+      throw pause;
+    }
+    const settled = await Promise.race([
+      promptPromise.then((o) => ({ kind: "prompt", o })),
+      aborted.then(() => ({ kind: "aborted" }))
+    ]);
+    this.abortPrompt = null;
+    if (settled.kind === "aborted")
+      return;
+    const outcome = settled.o;
+    if (!outcome.ok) {
+      yield { type: "error", text: formatError(outcome.err), timestamp: now3() };
+      return;
+    }
+    const stopReason = outcome.res.stopReason;
+    if (stopReason === "refusal") {
+      yield { type: "error", text: "agent refused the request", timestamp: now3() };
+      return;
+    }
+    const usage = outcome.res.usage;
+    if (usage) {
+      yield {
+        type: "usage",
+        inputTokens: usage.inputTokens,
+        outputTokens: usage.outputTokens,
+        cacheReadTokens: usage.cachedReadTokens ?? 0,
+        cacheCreationTokens: usage.cachedWriteTokens ?? 0,
+        durationMs: 0,
+        numTurns: 1,
+        timestamp: now3()
+      };
+    }
+  }
+  get currentSessionId() {
+    return this.sessionId;
+  }
+  cancel() {
+    if (this.cancelled) {
+      this.abortPrompt?.();
+      return;
+    }
+    this.cancelled = true;
+    if (this.sessionId) {
+      this.conn.cancel({ sessionId: this.sessionId }).catch(() => {});
+    }
+    this.abortPrompt?.();
+  }
+  close() {
+    this.abortPrompt?.();
+    this.updates.close();
+  }
+  async onRequestPermission(params) {
+    if (this.cancelled || this.deps.signal?.aborted) {
+      return { outcome: { outcome: "cancelled" } };
+    }
+    const tc = params.toolCall;
+    const call = {
+      toolName: tc.title || tc.kind || "tool",
+      toolInput: tc.rawInput ?? {},
+      toolUseId: tc.toolCallId
+    };
+    let verdict;
+    try {
+      verdict = await this.deps.gateToolCall(call, this.deps.procCtx());
+    } catch (err) {
+      if (isPauseSignal(err)) {
+        this.pendingPause = err;
+        this.cancel();
+        return { outcome: { outcome: "cancelled" } };
+      }
+      throw err;
+    }
+    if (verdict.kind === "abort") {
+      this.cancel();
+      return { outcome: { outcome: "cancelled" } };
+    }
+    const wantedKinds = verdict.kind === "allow" ? OPTION_KIND_FOR_VERDICT.allow : OPTION_KIND_FOR_VERDICT.deny;
+    const option = params.options.find((o) => wantedKinds.includes(o.kind)) ?? params.options[0];
+    if (!option) {
+      return { outcome: { outcome: "cancelled" } };
+    }
+    return { outcome: { outcome: "selected", optionId: option.optionId } };
+  }
+}
+
+// src/runtimes/_cli-agent.ts
+function now4() {
+  return new Date().toISOString();
+}
 function shellQuote(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
+var ACP_FALLBACK = Symbol("acp-fallback");
+var ACP_HANDSHAKE_TIMEOUT_MS = Number(process.env.AC_ACP_HANDSHAKE_TIMEOUT_MS) || 1e4;
+var ACP_TRANSPORT_READY = true;
+async function withHandshakeTimeout(p, ms) {
+  let timer;
+  const timeout = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => reject(new Error(`ACP handshake timed out after ${ms}ms`)), ms);
+  });
+  try {
+    return await Promise.race([p, timeout]);
+  } finally {
+    if (timer)
+      clearTimeout(timer);
+  }
+}
 
 class CliAgentRunner {
   sandbox;
@@ -2508,6 +2875,16 @@ class CliAgentRunner {
   spec;
   configModel;
   kind;
+  get acpCapable() {
+    return this.spec.acp !== undefined && this.acpTransportReady && typeof this.sandbox.commands.spawnDuplex === "function";
+  }
+  get supportsToolCallProcessor() {
+    return this.acpCapable;
+  }
+  acpDecision;
+  acpSession;
+  currentAcpProcCtx;
+  acpTransportReady = ACP_TRANSPORT_READY;
   constructor(sandbox, options, spec, configModel) {
     this.sandbox = sandbox;
     this.options = options;
@@ -2515,9 +2892,37 @@ class CliAgentRunner {
     this.configModel = configModel;
     this.kind = spec.kind;
   }
+  enableAcpForTesting() {
+    this.acpTransportReady = true;
+  }
   get model() {
     return this.configModel ?? this.options.model ?? this.spec.defaultModel;
   }
+  async gateToolCall(call, ctx) {
+    const verdict = await runProcessorChain(this.options.processors ?? [], (p) => p.processToolCall, call, ctx);
+    if (verdict.kind === "continue")
+      return { kind: "allow", call: verdict.value };
+    return verdict;
+  }
+  buildProcCtx(signal, iteration) {
+    const agentId = this.options.agentId ?? "agent";
+    const iter = iteration ?? 1;
+    return {
+      requestContext: this.options.requestContext ?? RequestContext.fromReserved({
+        teamId: "",
+        runId: "",
+        workflowId: "",
+        factoryId: null,
+        apiKeyScopes: [],
+        parentRunId: null
+      }),
+      abortSignal: signal ?? new AbortController().signal,
+      retryCount: 0,
+      agentId,
+      iteration: iter,
+      pause: boundProcessorPause(this.options.pause, { agentId, iteration: iter })
+    };
+  }
   installed = false;
   async ensureInstalled() {
     if (this.installed)
@@ -2534,7 +2939,133 @@ class CliAgentRunner {
     this.installed = true;
   }
   async* sendMessage(opts) {
-    yield { type: "init", sessionId: opts.sessionId ?? "", timestamp: now3() };
+    yield { type: "init", sessionId: opts.sessionId ?? "", timestamp: now4() };
+    if (this.acpCapable && this.acpDecision !== "jsonl") {
+      let fellBack = false;
+      try {
+        for await (const ev of this.sendMessageAcp(opts)) {
+          if (ev === ACP_FALLBACK) {
+            fellBack = true;
+            break;
+          }
+          yield ev;
+        }
+      } catch (err) {
+        if (isPauseSignal(err))
+          throw err;
+        yield { type: "error", text: formatError(err), timestamp: now4() };
+        return;
+      }
+      if (!fellBack) {
+        this.acpDecision = "acp";
+        return;
+      }
+      this.acpDecision = "jsonl";
+    }
+    yield* this.sendMessageJsonl(opts);
+  }
+  async teardownAcp(proc, peer) {
+    peer.close();
+    try {
+      await proc.stream.writable.close();
+    } catch {}
+    proc.kill();
+    proc.exited.catch(() => {});
+  }
+  async ensureAcpSession(opts) {
+    if (this.acpSession)
+      return this.acpSession;
+    await this.ensureInstalled();
+    const acp = this.spec.acp;
+    const proc = this.spawnAcpProcess(acp, opts.signal);
+    const peer = new AcpClientPeer({
+      stream: proc.stream,
+      gateToolCall: (call, ctx) => this.gateToolCall(call, ctx),
+      procCtx: () => this.currentAcpProcCtx ?? this.buildProcCtx(opts.signal, opts.iteration),
+      ...opts.signal ? { signal: opts.signal } : {}
+    });
+    let negotiated;
+    try {
+      ({ protocolVersion: negotiated } = await withHandshakeTimeout(peer.initialize(), ACP_HANDSHAKE_TIMEOUT_MS));
+    } catch {
+      await this.teardownAcp(proc, peer);
+      return null;
+    }
+    if (negotiated !== ACP_PROTOCOL_VERSION) {
+      await this.teardownAcp(proc, peer);
+      return null;
+    }
+    let sessionId;
+    try {
+      sessionId = await withHandshakeTimeout(peer.startSession(this.options.cwd ?? "/"), ACP_HANDSHAKE_TIMEOUT_MS);
+    } catch {
+      await this.teardownAcp(proc, peer);
+      return null;
+    }
+    this.acpSession = { proc, peer, sessionId };
+    return this.acpSession;
+  }
+  async* sendMessageAcp(opts) {
+    this.currentAcpProcCtx = this.buildProcCtx(opts.signal, opts.iteration);
+    const session = await this.ensureAcpSession(opts);
+    if (!session) {
+      yield ACP_FALLBACK;
+      return;
+    }
+    const { proc, peer, sessionId } = session;
+    let sawError = false;
+    let stalled = false;
+    let watchdog;
+    const armWatchdog = () => {
+      if (watchdog)
+        clearTimeout(watchdog);
+      watchdog = setTimeout(() => {
+        stalled = true;
+        peer.cancel();
+      }, ACP_HANDSHAKE_TIMEOUT_MS);
+    };
+    try {
+      armWatchdog();
+      for await (const msg of peer.prompt(opts.prompt)) {
+        armWatchdog();
+        if (msg.type === "error")
+          sawError = true;
+        yield msg;
+      }
+    } finally {
+      if (watchdog)
+        clearTimeout(watchdog);
+    }
+    if (stalled && !sawError) {
+      await this.teardownAcp(proc, peer);
+      this.acpSession = undefined;
+      yield { type: "error", text: `${this.spec.kind} prompt turn stalled (no activity for ${ACP_HANDSHAKE_TIMEOUT_MS}ms)`, timestamp: now4() };
+      return;
+    }
+    if (!sawError)
+      yield { type: "done", sessionId: peer.currentSessionId ?? sessionId, timestamp: now4() };
+  }
+  spawnAcpProcess(acp, signal) {
+    const spawnDuplex = this.sandbox.commands.spawnDuplex;
+    if (!spawnDuplex) {
+      throw new Error("spawnAcpProcess called on a provider without commands.spawnDuplex");
+    }
+    const cmd = `${acp.command} ${acp.args.map(shellQuote).join(" ")}`.trim();
+    const agentEnv = { ...acp.env, ...this.options.agentId ? { AGENT_COMPOSE_AGENT_ID: this.options.agentId } : {} };
+    const proc = spawnDuplex.call(this.sandbox.commands, cmd, {
+      ...this.options.cwd ? { cwd: this.options.cwd } : {},
+      ...Object.keys(agentEnv).length > 0 ? { envs: agentEnv } : {}
+    });
+    const kill = () => proc.kill();
+    if (signal) {
+      if (signal.aborted)
+        kill();
+      else
+        signal.addEventListener("abort", kill, { once: true });
+    }
+    return { stream: ndJsonStream(proc.stdin, proc.stdout), exited: proc.exited, kill };
+  }
+  async* sendMessageJsonl(opts) {
     let sessionId = opts.sessionId;
     let sawError = false;
     try {
@@ -2592,13 +3123,13 @@ class CliAgentRunner {
       const res = await runPromise;
       if (res.exitCode !== 0 && !sawError) {
         const tail = (res.stderr ?? "").slice(-2000);
-        yield { type: "error", text: `${this.spec.kind} exited with code ${res.exitCode}${tail ? `: ${tail}` : ""}`, timestamp: now3() };
+        yield { type: "error", text: `${this.spec.kind} exited with code ${res.exitCode}${tail ? `: ${tail}` : ""}`, timestamp: now4() };
         return;
       }
       if (!sawError)
-        yield { type: "done", sessionId: sessionId ?? "", timestamp: now3() };
+        yield { type: "done", sessionId: sessionId ?? "", timestamp: now4() };
     } catch (err) {
-      yield { type: "error", text: formatError(err), timestamp: now3() };
+      yield { type: "error", text: formatError(err), timestamp: now4() };
     }
   }
 }
@@ -2609,13 +3140,19 @@ function createCliAgentRuntime(spec, configModel) {
 }
 
 // src/runtimes/codex.ts
-function now4() {
+function now5() {
   return new Date().toISOString();
 }
+var CODEX_ACP_ADAPTER = "@agentclientprotocol/codex-acp@0.1.0";
 var codexSpec = {
   kind: "codex",
   authEnv: "CODEX_API_KEY",
   bin: "codex",
+  acp: {
+    command: "npx",
+    args: ["-y", CODEX_ACP_ADAPTER],
+    ...process.env.CODEX_PATH ? { env: { CODEX_PATH: process.env.CODEX_PATH } } : {}
+  },
   install: 'sudo npm install -g @openai/codex && (command -v codex >/dev/null 2>&1 || sudo ln -sf "$(npm prefix -g)/bin/codex" /usr/local/bin/codex)',
   promptPayload: (prompt) => prompt,
   buildCommand: ({ promptPath, sessionId, model, cwd }) => {
@@ -2631,7 +3168,7 @@ var codexSpec = {
   },
   extractSessionId: (p) => p.type === "thread.started" && typeof p.thread_id === "string" ? p.thread_id : undefined,
   mapEvent: (p) => {
-    const ts = now4();
+    const ts = now5();
     switch (p.type) {
       case "item.started":
       case "item.completed": {
@@ -2686,7 +3223,7 @@ function createCodexRuntime(config = {}) {
 }
 var codex_default = createCodexRuntime();
 // src/runtimes/amp.ts
-function now5() {
+function now6() {
   return new Date().toISOString();
 }
 function blocks(msg) {
@@ -2706,7 +3243,7 @@ var ampSpec = {
   },
   extractSessionId: (p) => typeof p.session_id === "string" ? p.session_id : undefined,
   mapEvent: (p) => {
-    const ts = now5();
+    const ts = now6();
     if (p.type === "assistant") {
       return blocks(p).flatMap((b) => {
         if (b.type === "text")
@@ -2751,6 +3288,7 @@ 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 { Readable, Writable } from "node:stream";
 import { Sandbox, SandboxNotFoundError, RateLimitError } from "e2b";
 import { Sandbox as Desktop } from "@e2b/desktop";
 import pRetry from "p-retry";
@@ -2779,6 +3317,26 @@ var SANDBOX_VCPUS = {
   "32vcpu-64gb": 32
 };
 var DEFAULT_SANDBOX_SIZE = "2vcpu-4gb";
+var E2B_TEMPLATE_SIZES = [
+  "2vcpu-4gb",
+  "4vcpu-8gb"
+];
+function isE2bSupportedSize(size) {
+  return E2B_TEMPLATE_SIZES.includes(size);
+}
+function e2bMachineSpec(size) {
+  const cpuCount = SANDBOX_VCPUS[size];
+  return { cpuCount, memoryMB: cpuCount * 2048 };
+}
+function e2bBaseTemplate(size) {
+  return `agent-compose-base-${size}`;
+}
+function e2bAgentEnvTemplate(size) {
+  return `agent-env-${size}`;
+}
+function isPlatformE2bTemplateAlias(id) {
+  return E2B_TEMPLATE_SIZES.some((size) => id === e2bBaseTemplate(size) || id === e2bAgentEnvTemplate(size));
+}
 function makeSandboxProvider(sb) {
   const commands = sb.commands;
   return {
@@ -2786,18 +3344,33 @@ function makeSandboxProvider(sb) {
     commands: {
       async run(cmd, opts) {
         let stderr = "";
-        const result = await commands.run(cmd, {
-          ...opts,
+        const { sudo, ...rest } = opts ?? {};
+        const runOpts = {
+          ...rest,
+          ...sudo ? { user: "root" } : {},
           onStderr: (chunk) => {
             stderr += chunk;
             opts?.onStderr?.(chunk);
           }
-        });
-        return {
-          exitCode: result.exitCode,
-          stdout: result.stdout,
-          stderr: typeof result.stderr === "string" ? result.stderr : stderr
         };
+        try {
+          const result = await commands.run(cmd, runOpts);
+          return {
+            exitCode: result.exitCode,
+            stdout: result.stdout,
+            stderr: typeof result.stderr === "string" ? result.stderr : stderr
+          };
+        } catch (e) {
+          const ce = e;
+          if (typeof ce.exitCode === "number") {
+            return {
+              exitCode: ce.exitCode,
+              stdout: typeof ce.stdout === "string" ? ce.stdout : "",
+              stderr: typeof ce.stderr === "string" ? ce.stderr : stderr
+            };
+          }
+          throw e;
+        }
       }
     },
     files: {
@@ -2805,7 +3378,9 @@ function makeSandboxProvider(sb) {
         await sb.files.write(path, content);
       }
     },
-    kill: () => sb.kill()
+    async kill() {
+      await sb.kill();
+    }
   };
 }
 function e2bMaxSandboxMs() {
@@ -2832,6 +3407,9 @@ function makeE2bSandboxProvider(sb) {
     async snapshot() {
       const { snapshotId } = await sb.createSnapshot();
       return { snapshotId };
+    },
+    async updateNetworkPolicy(policy) {
+      await sb.updateNetwork(toE2bNetwork(policy));
     }
   };
 }
@@ -2923,6 +3501,31 @@ function toVercelNetworkPolicy(policy) {
   }
   return { ...policy, allow };
 }
+function toE2bNetwork(policy) {
+  if (policy === "allow-all")
+    return {};
+  if (policy === "deny-all")
+    return { denyOut: ({ allTraffic }) => [allTraffic] };
+  const allowHosts = Array.isArray(policy.allow) ? [...policy.allow] : Object.keys(policy.allow ?? {});
+  const subnetAllow = policy.subnets?.allow ?? [];
+  const allowOut = [...new Set([...allowHosts, ...subnetAllow])];
+  const network = {
+    denyOut: ({ allTraffic }) => [allTraffic]
+  };
+  if (allowOut.length > 0)
+    network.allowOut = allowOut;
+  if (!Array.isArray(policy.allow) && policy.allow) {
+    const rules = {};
+    for (const [host, hostRules] of Object.entries(policy.allow)) {
+      const hostTransforms = hostRules.flatMap((rule) => (rule.transform ?? []).filter((t) => t.headers && Object.keys(t.headers).length > 0).map((t) => ({ transform: { headers: t.headers } })));
+      if (hostTransforms.length > 0)
+        rules[host] = hostTransforms;
+    }
+    if (Object.keys(rules).length > 0)
+      network.rules = rules;
+  }
+  return network;
+}
 var VERCEL_MAX_TAGS = 5;
 function buildVercelTags(metadata) {
   const tags = { ...metadata, executor: AGENT_COMPOSE_TAG };
@@ -3031,6 +3634,38 @@ function makeLocalSandboxProvider() {
           proc.on("error", reject);
           proc.on("close", (code) => resolve({ exitCode: code ?? 0, stdout, stderr }));
         });
+      },
+      spawnDuplex(cmd, opts) {
+        const proc = spawn("sh", ["-c", cmd], {
+          ...opts?.cwd ? { cwd: opts.cwd } : {},
+          env: { ...process.env, ...opts?.envs ?? {} },
+          stdio: ["pipe", "pipe", "pipe"],
+          detached: true
+        });
+        let stderr = "";
+        proc.stderr.setEncoding("utf8");
+        proc.stderr.on("data", (chunk) => {
+          stderr += chunk;
+        });
+        const exited = new Promise((resolve, reject) => {
+          proc.on("error", reject);
+          proc.on("close", (code) => resolve({ exitCode: code ?? 0, stderr }));
+        });
+        return {
+          stdin: Writable.toWeb(proc.stdin),
+          stdout: Readable.toWeb(proc.stdout),
+          exited,
+          kill() {
+            if (proc.pid === undefined)
+              return;
+            try {
+              process.kill(-proc.pid, "SIGTERM");
+            } catch (err) {
+              if (err.code !== "ESRCH")
+                throw err;
+            }
+          }
+        };
       }
     },
     files: {
@@ -3098,17 +3733,36 @@ var SANDBOX_PROVIDERS = {
       const creds = { token: env.VERCEL_ACCESS_TOKEN, teamId: env.VERCEL_TEAM_ID, projectId: env.VERCEL_PROJECT_ID };
       const snap = await Snapshot.get({ snapshotId, ...creds });
       await snap.delete();
+    },
+    snapshotExists: async (snapshotId, env) => {
+      const { Snapshot } = await import("@vercel/sandbox");
+      const creds = { token: env.VERCEL_ACCESS_TOKEN, teamId: env.VERCEL_TEAM_ID, projectId: env.VERCEL_PROJECT_ID };
+      try {
+        await Snapshot.get({ snapshotId, ...creds });
+        return true;
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err ?? "");
+        const status = err?.status ?? err?.statusCode;
+        if (status === 404 || /\b404\b|not[\s_-]?found|no such snapshot/i.test(message))
+          return false;
+        throw err;
+      }
     }
   },
   e2b: {
     requiredEnv: { E2B_API_KEY: "E2B API key — e2b.dev/dashboard" },
-    create: async ({ template, timeoutMs, networkPolicy: _np, size: _size, ...rest }) => {
+    create: async ({ template, timeoutMs, networkPolicy, 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;
+      const sandboxOpts = {
+        ...rest,
+        timeoutMs: Math.min(timeoutMs, maxMs),
+        ...networkPolicy ? { network: toE2bNetwork(networkPolicy) } : {}
+      };
+      const resolvedSize = size ?? DEFAULT_SANDBOX_SIZE;
+      const tmpl = template ?? (isE2bSupportedSize(resolvedSize) ? e2bBaseTemplate(resolvedSize) : undefined) ?? process.env.E2B_DEFAULT_TEMPLATE;
       return makeE2bSandboxProvider(await (tmpl ? Sandbox.create(tmpl, sandboxOpts) : Sandbox.create(sandboxOpts)));
     },
     reconnect: async (sandboxId) => makeE2bSandboxProvider(await Sandbox.connect(sandboxId, { apiKey: process.env.E2B_API_KEY ?? "", timeoutMs: 3600000 })),
@@ -3144,10 +3798,16 @@ var SANDBOX_PROVIDERS = {
   },
   "e2b-desktop": {
     requiredEnv: { E2B_API_KEY: "E2B API key — e2b.dev/dashboard" },
-    create: async ({ template, timeoutMs, networkPolicy: _np, size: _size, ...rest }) => {
+    create: async ({ template, timeoutMs, networkPolicy, 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()) }));
+      if (networkPolicy && networkPolicy !== "allow-all") {
+        throw new Error("E2B Desktop provider cannot enforce an egress network policy — `@e2b/desktop` bundles an e2b version that predates the native firewall. " + "e2b-desktop is registry-only and must not run with a confined policy.");
+      }
+      return makeDesktopSandboxProvider(await Desktop.create(template, {
+        ...rest,
+        timeoutMs: Math.min(timeoutMs, e2bMaxSandboxMs())
+      }));
     }
   }
 };
@@ -3180,6 +3840,17 @@ ${missing.join(`
 `)}`);
   return def.deleteSnapshot(snapshotId, Object.fromEntries(Object.keys(def.requiredEnv).map((k) => [k, process.env[k]])));
 }
+async function snapshotResolves(provider, snapshotId) {
+  const def = SANDBOX_PROVIDERS[provider];
+  if (!def?.snapshotExists)
+    throw new Error(`Provider "${provider}" does not support snapshotExists`);
+  const missing = Object.entries(def.requiredEnv).filter(([k]) => !process.env[k]).map(([k, desc]) => `  ${k} — ${desc}`);
+  if (missing.length > 0)
+    throw new Error(`Sandbox provider "${provider}" requires env vars:
+${missing.join(`
+`)}`);
+  return def.snapshotExists(snapshotId, Object.fromEntries(Object.keys(def.requiredEnv).map((k) => [k, process.env[k]])));
+}
 async function getSandboxQuotas() {
   const out = {};
   await Promise.all(Object.entries(SANDBOX_PROVIDERS).map(async ([name, def]) => {
@@ -3235,17 +3906,34 @@ class StepObservabilityCollector {
   events = [];
   subSteps = [];
   liveEmitter;
+  memoize;
+  usedStepNames = new Set;
   ackedSeqs = new Set;
   inFlight = new Set;
   constructor(opts = {}) {
     this.liveEmitter = opts.liveEmitter;
+    this.memoize = opts.memoize;
   }
   setMetadata = async (data) => {
     Object.assign(this.metadata, data);
   };
   step = async (name, fn) => {
+    if (this.usedStepNames.has(name)) {
+      throw new Error(`ctx.step("${name}", …) reuses a step name already used in this step body. ` + `Durable step names must be unique — they key the resume-time memoise file.`);
+    }
+    this.usedStepNames.add(name);
     const startedAt = Date.now();
     try {
+      if (this.memoize) {
+        const { value, restored } = await this.memoize(name, fn);
+        this.subSteps.push({
+          name,
+          startedAt,
+          durationMs: restored ? 0 : Date.now() - startedAt,
+          status: restored ? "restored" : "completed"
+        });
+        return value;
+      }
       const result = await fn();
       this.subSteps.push({
         name,
@@ -3309,19 +3997,19 @@ class StepObservabilityCollector {
 }
 
 // src/pause/checkpoint.ts
-async function checkpoint(name, fn) {
+async function memoize(name, fn) {
   const existing = await readCheckpoint(name);
   if (existing.found)
-    return existing.value;
+    return { value: existing.value, restored: true };
   const value = await fn();
   await writeCheckpoint(name, value);
-  return value;
+  return { value, restored: false };
 }
-function scopedCheckpoint(scope) {
+function scopedMemoize(scope) {
   assertSafeCheckpointName(scope);
   return async (name, fn) => {
     assertSafeCheckpointName(name);
-    return checkpoint(`${scope}.${name}`, fn);
+    return memoize(`${scope}.${name}`, fn);
   };
 }
 
@@ -3389,7 +4077,10 @@ async function runWorkflowSingleStep(opts) {
   const parsedInput = step.input.safeParse(opts.input);
   if (!parsedInput.success)
     throw new StepValidationError(step.name, "input", parsedInput.error);
-  const collector = new StepObservabilityCollector({ liveEmitter: opts.liveAgentEventEmitter });
+  const collector = new StepObservabilityCollector({
+    liveEmitter: opts.liveAgentEventEmitter,
+    memoize: scopedMemoize(`step${opts.stepIndex}`)
+  });
   const coord = { runId: opts.run.id, stepIndex: opts.stepIndex };
   const pauseWithKind = function(req, kind) {
     return corePause(req, coord, kind);
@@ -3410,7 +4101,6 @@ async function runWorkflowSingleStep(opts) {
     setMetadata: collector.setMetadata,
     step: collector.step,
     agentEvents: collector.agentEvents,
-    checkpoint: scopedCheckpoint(`step${opts.stepIndex}`),
     pause,
     ...buildPauseWrappers(pauseWithKind)
   };
@@ -3466,7 +4156,10 @@ async function runWorkflowSteps(opts) {
       await opts.onStepFailed?.(i, step.name, err, 0);
       throw err;
     }
-    const collector = new StepObservabilityCollector({ liveEmitter: opts.liveAgentEventEmitter });
+    const collector = new StepObservabilityCollector({
+      liveEmitter: opts.liveAgentEventEmitter,
+      memoize: scopedMemoize(`step${i}`)
+    });
     const coord = { runId: run.id, stepIndex: i };
     const pauseWithKind = function(req, kind) {
       return corePause(req, coord, kind);
@@ -3485,7 +4178,6 @@ async function runWorkflowSteps(opts) {
       setMetadata: collector.setMetadata,
       step: collector.step,
       agentEvents: collector.agentEvents,
-      checkpoint: scopedCheckpoint(`step${i}`),
       pause,
       ...buildPauseWrappers(pauseWithKind)
     };
@@ -3682,32 +4374,32 @@ function stepResultFilePath(token) {
 }
 // src/step-invocation/invoker.ts
 import { randomBytes as randomBytes2 } from "node:crypto";
-import { z as z10 } from "zod";
-var StepObservabilitySchema = z10.object({
-  metadata: z10.record(z10.string(), z10.unknown()).optional(),
-  events: z10.array(z10.unknown()).optional(),
-  subSteps: z10.array(z10.object({
-    name: z10.string(),
-    startedAt: z10.number(),
-    durationMs: z10.number(),
-    status: z10.enum(["completed", "failed"]),
-    error: z10.string().optional()
+import { z as z11 } from "zod";
+var StepObservabilitySchema = z11.object({
+  metadata: z11.record(z11.string(), z11.unknown()).optional(),
+  events: z11.array(z11.unknown()).optional(),
+  subSteps: z11.array(z11.object({
+    name: z11.string(),
+    startedAt: z11.number(),
+    durationMs: z11.number(),
+    status: z11.enum(["completed", "failed"]),
+    error: z11.string().optional()
   })).optional()
 }).passthrough();
-var StepResultEnvelopeSchema = z10.discriminatedUnion("ok", [
-  z10.object({
-    ok: z10.literal(true),
-    output: z10.unknown().optional(),
+var StepResultEnvelopeSchema = z11.discriminatedUnion("ok", [
+  z11.object({
+    ok: z11.literal(true),
+    output: z11.unknown().optional(),
     observability: StepObservabilitySchema.optional()
   }),
-  z10.object({
-    ok: z10.literal(false),
-    kind: z10.enum(["protocol", "user-step"]),
-    error: z10.string().optional()
+  z11.object({
+    ok: z11.literal(false),
+    kind: z11.enum(["protocol", "user-step"]),
+    error: z11.string().optional()
   })
 ]);
-var StepPauseEnvelopeSchema = z10.object({
-  pauseId: z10.string().min(1),
+var StepPauseEnvelopeSchema = z11.object({
+  pauseId: z11.string().min(1),
   pauseRequest: StepPauseRequestSchema,
   observability: StepObservabilitySchema.optional()
 });
@@ -4000,8 +4692,43 @@ async function serveStep(handler) {
   await emitResult(token, payload);
   process.exit(exitCode);
 }
+// src/agent/local-pause-request.ts
+import { existsSync, mkdirSync as mkdirSync2, readFileSync as readFileSync2, renameSync, rmSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { join as join3 } from "node:path";
+import { randomBytes as randomBytes3 } from "node:crypto";
+var UNSCOPED = "_unscoped";
+var requestsDir = () => join3(getStateDir(), "pause-requests");
+var markerPath = (agentId) => join3(requestsDir(), `${slug(agentId) || UNSCOPED}.json`);
+function slug(agentId) {
+  return (agentId ?? "").replace(/[^a-zA-Z0-9_.-]/g, "_");
+}
+function writeLocalPauseRequest(agentId, req) {
+  mkdirSync2(requestsDir(), { recursive: true });
+  const final = markerPath(agentId);
+  const tmp = `${final}.${randomBytes3(6).toString("hex")}.tmp`;
+  writeFileSync2(tmp, JSON.stringify(req), "utf8");
+  renameSync(tmp, final);
+}
+function consumeLocalPauseRequest(agentId) {
+  const paths = [...new Set([markerPath(agentId), markerPath(null)])];
+  for (const path of paths) {
+    if (!existsSync(path))
+      continue;
+    try {
+      const raw = JSON.parse(readFileSync2(path, "utf8"));
+      rmSync(path, { force: true });
+      if (raw && typeof raw === "object" && typeof raw.reason === "string" && raw.reason.trim().length > 0) {
+        const r = raw;
+        return { reason: r.reason.trim(), ...Array.isArray(r.options) && r.options.length > 0 ? { options: r.options } : {} };
+      }
+    } catch {
+      rmSync(path, { force: true });
+    }
+  }
+  return null;
+}
 // src/agent/run-agent.ts
-import { z as z11 } from "zod";
+import { z as z12 } from "zod";
 import { randomUUID as randomUUID2 } from "node:crypto";
 
 // src/agent/agent-context.ts
@@ -4065,11 +4792,19 @@ Use \`/ac:generate-workflow\` / \`/ac:generate-agent\` to scaffold, then
 
 ## 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:
+When you can't or shouldn't proceed without a human, run \`agentc pause\`, then
+**END YOUR TURN**:
+
+    agentc pause --reason "Notion returned 401 — connect Notion to continue" \\
+                 --option retry --option skip
 
-    ANSWER=$(agentc pause --reason "Notion returned 401 — connect Notion to continue" \\
-                          --option retry --option skip)
+\`agentc pause\` does NOT block and does NOT print the answer. It records your
+question and returns immediately. The moment you end your turn, the run pauses
+(your sandbox is snapshotted and compute stops while the human decides) and the
+human's answer is delivered to you as your **next message** — you pick up
+exactly where you left off, with the answer in hand. So: ask, end your turn,
+and wait. Do NOT keep working, do NOT call more tools, and do NOT mark the task
+complete after pausing.
 
 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
@@ -4083,8 +4818,8 @@ Reach for it the moment you hit — or foresee — any of these:
   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.
+there are clear ones, omit them for a free-form answer. Each agent pauses
+independently — pausing doesn't stop the others.
 
 ## Credentials
 
@@ -4206,29 +4941,29 @@ function stripFrontmatter(content) {
   return end === -1 ? content : content.slice(end + 4).trimStart();
 }
 function zodTypeName(schema) {
-  if (schema instanceof z11.ZodString)
+  if (schema instanceof z12.ZodString)
     return "string";
-  if (schema instanceof z11.ZodNumber)
+  if (schema instanceof z12.ZodNumber)
     return "number";
-  if (schema instanceof z11.ZodBoolean)
+  if (schema instanceof z12.ZodBoolean)
     return "boolean";
-  if (schema instanceof z11.ZodArray)
+  if (schema instanceof z12.ZodArray)
     return `${zodTypeName(schema.element)}[]`;
-  if (schema instanceof z11.ZodEnum)
+  if (schema instanceof z12.ZodEnum)
     return schema.options.map((o) => `"${o}"`).join(" | ");
-  if (schema instanceof z11.ZodOptional)
+  if (schema instanceof z12.ZodOptional)
     return `${zodTypeName(schema.unwrap())} (optional)`;
-  if (schema instanceof z11.ZodNullable)
+  if (schema instanceof z12.ZodNullable)
     return `${zodTypeName(schema.unwrap())} | null`;
-  if (schema instanceof z11.ZodLiteral)
+  if (schema instanceof z12.ZodLiteral)
     return `"${String(schema.value)}"`;
-  if (schema instanceof z11.ZodObject)
+  if (schema instanceof z12.ZodObject)
     return "object";
   return "any";
 }
 function buildResponseFormatAppendix(schema) {
   const header = ["## Response Format", "", "When you emit `exit_signal: true` in your `<status>` block, also include a `<response>` block containing JSON immediately after `<status>`:", ""];
-  const shape = schema instanceof z11.ZodObject ? schema.shape : null;
+  const shape = schema instanceof z12.ZodObject ? schema.shape : null;
   const body = shape ? (() => {
     const entries = Object.entries(shape);
     const example = Object.fromEntries(entries.map(([k, v]) => [k, `<${zodTypeName(v)}>`]));
@@ -4358,6 +5093,7 @@ async function agent(opts) {
       ...inbox ? { inbox } : {},
       mode,
       consumeSteerPending: () => consumeSteerPending(agentId),
+      consumeLocalPauseRequest: () => consumeLocalPauseRequest(agentId),
       ...steerPause ? { pause: steerPause } : {}
     });
   } finally {
@@ -4367,8 +5103,10 @@ async function agent(opts) {
 }
 export {
   writeTool,
+  writeLocalPauseRequest,
   writeAgentContext,
   stepInputPath,
+  snapshotResolves,
   serveStep,
   runWorkflowSteps,
   runWorkflowSingleStep,
@@ -4392,11 +5130,17 @@ export {
   killSandboxById,
   killAllSandboxes,
   isWorkflow,
+  isPlatformE2bTemplateAlias,
+  isE2bSupportedSize,
   invokeStep,
   importSourceModule,
+  humanApproval,
   getSandboxQuotas,
   formatError,
   editTool,
+  e2bMachineSpec,
+  e2bBaseTemplate,
+  e2bAgentEnvTemplate,
   denyTools,
   deleteSandboxSnapshot,
   defineWorkflow,
@@ -4408,6 +5152,7 @@ export {
   createCodexRuntime,
   createClaudeRuntime,
   createAmpRuntime,
+  consumeLocalPauseRequest,
   codingTools,
   codex_default as codexRuntime,
   claude_default as claudeRuntime,
@@ -4434,6 +5179,7 @@ export {
   STEP_RESULT_PREFIX,
   STEP_PAUSE_PREFIX,
   STEP_ENV,
+  SANDBOX_VCPUS,
   SANDBOX_UNAVAILABLE_PREFIX,
   ReservedKeyError,
   RequestContext,
@@ -4446,6 +5192,8 @@ export {
   NonSerialisableValueError,
   LATEST_VERSION,
   EngineError,
+  E2B_TEMPLATE_SIZES,
+  DEFAULT_SANDBOX_SIZE,
   DEFAULT_CLAUDE_MODEL,
   ClaudeRunner,
   BUNDLER_VERSION,