@agent-compose/sdk 0.5.1 → 0.5.2

package/dist/index.js

@@ -36,6 +36,17 @@ function q(value) {
 function resolvePath(path, cwd) {
   return cwd && !isAbsolute(path) ? join(cwd, path) : path;
 }
+function formatCommandFailure(command, result) {
+  const parts = [`Command failed with exit code ${result.exitCode}: ${command}`];
+  if (result.stderr.trim())
+    parts.push(`stderr:
+${result.stderr}`);
+  if (result.stdout.trim())
+    parts.push(`stdout:
+${result.stdout}`);
+  return parts.join(`
+`);
+}
 async function readFile(sandbox, path, opts) {
   const script = `
 const fs = require("fs");
@@ -49,13 +60,19 @@ const end = Math.min(lines.length, start + Math.max(0, limit) - 1);
 for (let i = start; i <= end; i++) console.log(String(i) + ": " + lines[i - 1]);
 `;
   const args = [q(path), opts?.offset !== undefined ? String(opts.offset) : "", opts?.limit !== undefined ? String(opts.limit) : ""].filter(Boolean).map(q).join(" ");
-  const { stdout } = await sandbox.commands.run(`node -e ${q(script)} ${args}`, { cwd: opts?.cwd, timeoutMs: 30000 });
-  return stdout;
+  const command = `node -e ${q(script)} ${args}`;
+  const result = await sandbox.commands.run(command, { cwd: opts?.cwd, timeoutMs: 30000 });
+  if (result.exitCode !== 0)
+    throw new Error(formatCommandFailure(command, result));
+  return result.stdout;
 }
 async function readRawFile(sandbox, path, cwd) {
   const script = `const fs = require("fs"); process.stdout.write(fs.readFileSync(process.argv[1], "utf8"));`;
-  const { stdout } = await sandbox.commands.run(`node -e ${q(script)} ${q(path)}`, { cwd, timeoutMs: 30000 });
-  return stdout;
+  const command = `node -e ${q(script)} ${q(path)}`;
+  const result = await sandbox.commands.run(command, { cwd, timeoutMs: 30000 });
+  if (result.exitCode !== 0)
+    throw new Error(formatCommandFailure(command, result));
+  return result.stdout;
 }
 var readTool = {
   name: "Read",
@@ -116,8 +133,7 @@ var bashTool = {
       timeoutMs: timeoutMs ?? 120000
     });
     if (result.exitCode !== 0)
-      throw new Error(`Command failed with exit code ${result.exitCode}${result.stdout ? `
-${result.stdout}` : ""}`);
+      throw new Error(formatCommandFailure(command, result));
     return result.stdout;
   }
 };
@@ -138,6 +154,7 @@ async function runProcessorChain(processors, selectHook, initial, ctx) {
 }
 
 // src/request-context/request-context.ts
+import { z as z2 } from "zod";
 var AC_RESERVED_PREFIX = "ac__";
 var AC_TEAM_ID = "ac__teamId";
 var AC_RUN_ID = "ac__runId";
@@ -163,6 +180,17 @@ var SERIALISABLE_RESERVED_KEYS = new Set([
   AC_API_KEY_SCOPES,
   AC_PARENT_RUN_ID
 ]);
+var RequestContextWireSchema = z2.object({
+  reserved: z2.object({
+    teamId: z2.string(),
+    runId: z2.string(),
+    workflowId: z2.string(),
+    factoryId: z2.string().nullable(),
+    apiKeyScopes: z2.array(z2.string()).readonly(),
+    parentRunId: z2.string().nullable()
+  }),
+  user: z2.record(z2.string(), z2.unknown())
+});
 
 class ReservedKeyError extends Error {
   key;
@@ -224,7 +252,8 @@ class RequestContext {
     return new RequestContext(reserved, new Map);
   }
   static deserialise(wire) {
-    const ctx = new RequestContext({ ...wire.reserved, abortSignal: undefined }, new Map(Object.entries(wire.user)));
+    const parsed = RequestContextWireSchema.parse(wire);
+    const ctx = new RequestContext({ ...parsed.reserved, abortSignal: undefined }, new Map(Object.entries(parsed.user)));
     return ctx;
   }
   withAbortSignal(signal) {
@@ -372,6 +401,20 @@ class VercelRunner {
       return { kind: "allow", call: verdict.value };
     return verdict;
   }
+  captureCheckpoint() {
+    return { messages: [...this.messages] };
+  }
+  restoreCheckpoint(blob) {
+    if (!blob || typeof blob !== "object") {
+      throw new Error("Vercel runtime checkpoint is invalid: expected an object with messages[]");
+    }
+    const incoming = blob.messages;
+    if (!Array.isArray(incoming)) {
+      throw new Error("Vercel runtime checkpoint is invalid: expected messages[]");
+    }
+    this.messages.length = 0;
+    this.messages.push(...incoming);
+  }
   buildTools(iteration, signal) {
     const set = {};
     for (const t of this.tools) {
@@ -469,7 +512,7 @@ function createVercelRuntime(config) {
   });
 }
 // src/types/workflow.ts
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 
 // src/workflow-steps/types.ts
 var WORKFLOW_BRAND = Symbol.for("@agent-compose/sdk.Workflow");
@@ -546,7 +589,7 @@ function isWorkflow(value) {
 
 // src/types/workflow.ts
 function compileRunForm(def, metadata) {
-  const unknownSchema = z2.unknown();
+  const unknownSchema = z3.unknown();
   const inputSchema = def.input ?? unknownSchema;
   const outputSchema = def.output ?? unknownSchema;
   const step = {
@@ -562,6 +605,11 @@ function compileRunForm(def, metadata) {
         setMetadata: stepCtx.setMetadata,
         step: stepCtx.step,
         agentEvents: stepCtx.agentEvents,
+        checkpoint: stepCtx.checkpoint,
+        pause: stepCtx.pause,
+        requestDecision: stepCtx.requestDecision,
+        sleep: stepCtx.sleep,
+        waitForEvent: stepCtx.waitForEvent,
         processors: metadata.processors ?? []
       };
       const sandbox = stepCtx.sandbox;
@@ -678,11 +726,14 @@ async function* parseSseStream(body) {
           continue;
         }
         if (line === "" && dataLines.length > 0) {
+          let data;
           try {
-            const data = JSON.parse(dataLines.join(`
+            data = JSON.parse(dataLines.join(`
 `));
-            yield { id: seq, event, data };
-          } catch {}
+          } catch (err) {
+            throw new Error(`Malformed SSE JSON payload for event "${event || "message"}": ${err instanceof Error ? err.message : String(err)}`);
+          }
+          yield { id: seq, event, data };
           event = "";
           seq = 0;
           dataLines = [];
@@ -706,6 +757,12 @@ function templatePath(factorySlug, ...rest) {
   return `/api/v1/factories/${encodeURIComponent(factorySlug)}/templates${tail}`;
 }
 var PUBLIC_API_HOST = "https://api.agentcompose.ai";
+function steerAnswerPayload(message, actor) {
+  if (typeof message !== "string" || message.trim().length === 0) {
+    throw new Error("answerSteer: `message` must be a non-empty string");
+  }
+  return { message, ...actor !== undefined ? { actor } : {} };
+}
 
 class AgentComposeClient {
   fetch;
@@ -791,6 +848,56 @@ class AgentComposeClient {
   getStatus(runId) {
     return this.fetch(`/api/v1/workflows/${runId}/status`);
   }
+  async resumePause(runId, pauseId, payload, opts) {
+    const headers = {};
+    if (opts?.idempotencyKey)
+      headers["Idempotency-Key"] = opts.idempotencyKey;
+    return this.fetch(`/api/v1/runs/${encodeURIComponent(runId)}/pauses/${encodeURIComponent(pauseId)}/resume`, {
+      method: "POST",
+      body: { resumePayload: payload },
+      ...Object.keys(headers).length ? { headers } : {},
+      ...opts?.signal ? { signal: opts.signal } : {}
+    });
+  }
+  async resumePauseByKey(runId, correlationKey, payload, opts) {
+    const headers = {};
+    if (opts?.idempotencyKey)
+      headers["Idempotency-Key"] = opts.idempotencyKey;
+    return this.fetch(`/api/v1/runs/${encodeURIComponent(runId)}/pauses/by-key/${encodeURIComponent(correlationKey)}/resume`, {
+      method: "POST",
+      body: { resumePayload: payload },
+      ...Object.keys(headers).length ? { headers } : {},
+      ...opts?.signal ? { signal: opts.signal } : {}
+    });
+  }
+  async answerSteerByKey(runId, correlationKey, message, opts) {
+    return this.resumePauseByKey(runId, correlationKey, steerAnswerPayload(message, opts?.actor), opts);
+  }
+  async answerSteer(runId, pauseId, message, opts) {
+    return this.resumePause(runId, pauseId, steerAnswerPayload(message, opts?.actor), opts);
+  }
+  async requestAgentPause(runId, agentId, opts) {
+    const body = {};
+    if (opts?.reason !== undefined)
+      body.reason = opts.reason;
+    if (opts?.correlationKey !== undefined)
+      body.correlationKey = opts.correlationKey;
+    return this.fetch(`/api/v1/runs/${encodeURIComponent(runId)}/agents/${encodeURIComponent(agentId)}/pause`, {
+      method: "POST",
+      body,
+      ...opts?.signal ? { signal: opts.signal } : {}
+    });
+  }
+  async sendAgentMessage(runId, agentId, message, opts) {
+    const body = { message };
+    if (opts?.senderName !== undefined)
+      body.senderName = opts.senderName;
+    return this.fetch(`/api/v1/runs/${encodeURIComponent(runId)}/agents/${encodeURIComponent(agentId)}/messages`, {
+      method: "POST",
+      body,
+      ...opts?.signal ? { signal: opts.signal } : {}
+    });
+  }
   getRun(runId) {
     return this.fetch(`/api/v1/workflows/${encodeURIComponent(runId)}`);
   }
@@ -930,10 +1037,6 @@ class AgentComposeClient {
     }
   }
 }
-// src/utils/discovery.ts
-function discoverRuntimeName(source) {
-  return source.match(/runtime:\s*["']([^"']+)["']/)?.[1] ?? null;
-}
 // src/utils/bundler.ts
 import { createHash } from "node:crypto";
 import { parse as babelParse } from "@babel/parser";
@@ -986,8 +1089,8 @@ async function extractFromBundle(source, label, pick) {
     } finally {
       await loaded.cleanup();
     }
-  } catch {
-    return;
+  } catch (err) {
+    throw new WorkflowSourceValidationError(`Bundled ${label} could not be evaluated: ${err instanceof Error ? err.message : String(err)}`);
   }
 }
 var DEFINE_WORKFLOW_CALLEE = /^(?:defineWorkflow|defineSandboxEnvironment)\d*$/;
@@ -1080,10 +1183,10 @@ async function bundleWorkflow(workflowPath, overrides) {
 function extractIOSchema(zodSchema) {
   let json;
   try {
-    const z3 = __require("zod");
-    if (!z3.toJSONSchema)
+    const z4 = __require("zod");
+    if (!z4.toJSONSchema)
       return;
-    json = z3.toJSONSchema(zodSchema);
+    json = z4.toJSONSchema(zodSchema);
   } catch {
     return;
   }
@@ -1116,24 +1219,26 @@ function extractIOSchema(zodSchema) {
   return out;
 }
 // src/utils/schemas.ts
-import { z as z3 } from "zod";
-var AgentStatusSchema = z3.object({
-  summary: z3.string(),
-  completed: z3.array(z3.string()),
-  blockers: z3.array(z3.string()),
-  exit_signal: z3.boolean()
+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()
 });
 // src/runtimes/claude.ts
 import { query } from "@anthropic-ai/claude-agent-sdk";
 
 // src/agent/agent-loop.ts
-import { z as z5 } from "zod";
+import { z as z9 } from "zod";
 
 // src/agent/protocol.ts
-import { z as z4 } from "zod";
-var AgentMessageSchema = z4.object({
-  type: z4.enum(["init", "text", "thinking", "tool_use", "tool_result", "done", "error", "usage"]),
-  timestamp: z4.string()
+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()
 }).passthrough();
 function parseAgentResponse(text) {
   const match = text.match(/<response>([\s\S]*?)<\/response>/);
@@ -1148,6 +1253,557 @@ function parseAgentResponse(text) {
 
 // src/agent/agent-loop.ts
 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
+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({
+  schemaVersion: SUPPORTED_AGENT_LOOP_STATE_VERSIONS,
+  phase: z6.literal("running"),
+  iteration: z6.number().int().nonnegative(),
+  completedIterations: z6.number().int().nonnegative(),
+  lastSessionId: z6.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)
+});
+var SettledAgentLoopStateSchema = z6.object({
+  schemaVersion: SUPPORTED_AGENT_LOOP_STATE_VERSIONS,
+  phase: z6.literal("settled"),
+  result: z6.object({
+    sessionId: z6.string(),
+    lastStatus: AgentStatusSchema.nullable(),
+    iterations: z6.number().int().nonnegative(),
+    response: z6.unknown().optional()
+  })
+});
+var AgentLoopStateSchema = z6.discriminatedUnion("phase", [
+  RunningAgentLoopStateSchema,
+  SettledAgentLoopStateSchema
+]);
+function toProgressState(state) {
+  return {
+    iteration: state.iteration,
+    completedIterations: state.completedIterations,
+    lastSessionId: state.lastSessionId,
+    lastStatus: state.lastStatus,
+    lastResponseText: state.lastResponseText,
+    lastResponseValidationError: state.lastResponseValidationError,
+    iterationsWithoutStatus: state.iterationsWithoutStatus,
+    blockerStreak: state.blockerStreak,
+    pendingSteerPause: state.pendingSteerPause
+  };
+}
+
+class PauseManager {
+  agentId;
+  constructor(agentId) {
+    this.agentId = agentId;
+  }
+  async restoreAgentLoop(runtime) {
+    const priorState = await readAgentState(this.agentId);
+    if (priorState === null)
+      return { kind: "fresh" };
+    const parsed = AgentLoopStateSchema.safeParse(priorState);
+    if (!parsed.success)
+      return { kind: "invalid", error: parsed.error.message };
+    const state = parsed.data;
+    if (state.phase === "settled") {
+      return {
+        kind: "settled",
+        result: {
+          sessionId: state.result.sessionId,
+          lastStatus: state.result.lastStatus,
+          iterations: state.result.iterations,
+          ...Object.prototype.hasOwnProperty.call(state.result, "response") ? { response: state.result.response } : {}
+        }
+      };
+    }
+    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`);
+  }
+  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/agent/steer-control.ts
+import { z as z8 } from "zod";
+var SteerDecisionSchema = z8.object({
+  message: z8.string().min(1),
+  actor: z8.string().nullish()
+});
+var steerPending = new Map;
+function signalSteerPending(agentId, payload) {
+  const queue = steerPending.get(agentId) ?? [];
+  const existing = queue.findIndex((p) => p.correlationKey === payload.correlationKey);
+  if (existing >= 0)
+    queue[existing] = payload;
+  else
+    queue.push(payload);
+  steerPending.set(agentId, queue);
+}
+function consumeSteerPending(agentId) {
+  const queue = steerPending.get(agentId);
+  if (queue === undefined || queue.length === 0)
+    return null;
+  const next = queue.shift();
+  if (queue.length === 0)
+    steerPending.delete(agentId);
+  return next;
+}
+async function runControlPoller(opts) {
+  const headers = { authorization: `Bearer ${opts.token}`, accept: "application/json" };
+  const url = `${opts.baseUrl.replace(/\/+$/, "")}/api/v1/internal/runs/${opts.runId}/control`;
+  let backoffMs = 0;
+  while (!opts.signal.aborted) {
+    if (backoffMs > 0) {
+      await new Promise((resolve) => setTimeout(resolve, backoffMs));
+      if (opts.signal.aborted)
+        return;
+    }
+    try {
+      const res = await fetch(url, { method: "GET", headers, signal: opts.signal });
+      if (!res.ok) {
+        if (res.status === 401 || res.status === 403)
+          return;
+        backoffMs = Math.min(8000, (backoffMs || 500) * 2);
+        continue;
+      }
+      backoffMs = 0;
+      const body = await res.json();
+      const ctrl = body.control;
+      if (ctrl && ctrl.kind === "steer_pause" && (ctrl.agentId == null || ctrl.agentId === opts.agentId)) {
+        signalSteerPending(opts.agentId, {
+          reason: ctrl.reason ?? null,
+          correlationKey: ctrl.correlationKey ?? null
+        });
+      }
+    } catch (err) {
+      if (opts.signal.aborted)
+        return;
+      backoffMs = Math.min(8000, (backoffMs || 500) * 2);
+      if (backoffMs >= 4000) {
+        process.stderr.write(`[control-poller] poll failed, backing off ${backoffMs}ms: ${err instanceof Error ? err.message : String(err)}
+`);
+      }
+    }
+  }
+}
+
+// src/agent/agent-loop.ts
 var DEFAULT_CLAUDE_MODEL = "claude-opus-4-7";
 var SAME_BLOCKER_ITERATIONS = 3;
 var STALL_ITERATIONS = 3;
@@ -1183,7 +1839,7 @@ function summarizeAgentMessage(msg) {
     case "thinking":
       return { type: "thinking", text: msg.text };
     case "tool_use":
-      return { type: "tool_use", toolName: msg.toolName, toolUseId: msg.toolUseId, toolInputPreview: preview(msg.toolInput) };
+      return { type: "tool_use", toolName: msg.toolName, toolUseId: msg.toolUseId, toolInput: msg.toolInput, toolInputPreview: preview(msg.toolInput) };
     case "tool_result":
       return { type: "tool_result", toolUseId: msg.toolUseId, output: truncate(msg.output), isError: msg.isError };
     case "usage":
@@ -1236,7 +1892,7 @@ async function agentLoop(opts) {
     processors,
     requestContext,
     agentId,
-    ...opts.responseSchema ? { outputFormat: { type: "json_schema", schema: z5.toJSONSchema(opts.responseSchema) } } : {}
+    ...opts.responseSchema ? { outputFormat: { type: "json_schema", schema: z9.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
@@ -1249,11 +1905,101 @@ async function agentLoop(opts) {
   let completedIterations = 0;
   let lastResponseText = "";
   let lastResponseValidationError = "";
-  opts.onAgentLifecycleEvent?.({ event: "agent.spawned", at: startedAt, agentId, label, allowedTools: opts.allowedTools ?? DEFAULT_ALLOWED_TOOLS });
+  let startIteration = 0;
+  let resumed = false;
+  let pendingSteerPause = null;
+  const pauseManager = new PauseManager(agentId);
+  const restore = await pauseManager.restoreAgentLoop(client);
+  if (restore.kind === "settled") {
+    process.stdout.write(`${logLabel} restored settled agent result from checkpoint after ${restore.result.iterations} iterations
+`);
+    return { agentId, label, ...restore.result };
+  }
+  if (restore.kind === "running") {
+    const s = restore.state;
+    startIteration = s.iteration;
+    completedIterations = s.completedIterations;
+    lastSessionId = s.lastSessionId;
+    lastStatus = s.lastStatus;
+    lastResponseText = s.lastResponseText;
+    lastResponseValidationError = s.lastResponseValidationError;
+    iterationsWithoutStatus = s.iterationsWithoutStatus;
+    blockerStreak = s.blockerStreak;
+    pendingSteerPause = s.pendingSteerPause ?? null;
+    resumed = true;
+    process.stdout.write(`${logLabel} resumed from agent-state checkpoint at iteration ${startIteration}/${maxIterations}
+`);
+  }
+  if (restore.kind === "invalid") {
+    process.stderr.write(`${logLabel} agent-state checkpoint at agentId=${agentId} is unrecognised — starting fresh. ` + `Schema version mismatch or corrupt file: ${restore.error}
+`);
+  }
+  if (!resumed) {
+    opts.onAgentLifecycleEvent?.({
+      event: "agent.spawned",
+      at: startedAt,
+      agentId,
+      label,
+      allowedTools: opts.allowedTools ?? DEFAULT_ALLOWED_TOOLS,
+      ...client.model != null ? { model: client.model } : {},
+      ...client.kind != null ? { runtimeKind: client.kind } : {}
+    });
+  }
+  const flushState = async (currentIteration) => {
+    await pauseManager.saveRunningAgentLoop({
+      iteration: currentIteration,
+      completedIterations,
+      lastSessionId,
+      lastStatus,
+      lastResponseText,
+      lastResponseValidationError,
+      iterationsWithoutStatus,
+      blockerStreak,
+      pendingSteerPause
+    }, client);
+  };
+  const writeSettledState = async (result) => {
+    await pauseManager.saveSettledAgentLoop({
+      sessionId: result.sessionId,
+      lastStatus: result.lastStatus,
+      iterations: result.iterations,
+      ...result.response !== undefined ? { response: result.response } : {}
+    });
+  };
   try {
-    for (let iteration = 0;iteration < maxIterations; iteration++) {
+    for (let iteration = startIteration;iteration < maxIterations || !!opts.pause && pendingSteerPause !== null; iteration++) {
+      await flushState(iteration);
+      let steerDecision = null;
+      if (opts.pause) {
+        if (pendingSteerPause === null) {
+          const steer = opts.consumeSteerPending?.() ?? null;
+          if (steer) {
+            pendingSteerPause = {
+              reason: steer.reason ?? "human steer",
+              correlationKey: steer.correlationKey,
+              at: Date.now()
+            };
+          }
+        }
+        if (pendingSteerPause !== null) {
+          await flushState(iteration);
+          steerDecision = await opts.pause({
+            reason: pendingSteerPause.reason,
+            ...pendingSteerPause.correlationKey !== null ? { correlationKey: pendingSteerPause.correlationKey } : {},
+            schema: SteerDecisionSchema
+          }, { agentId, iteration });
+          pendingSteerPause = null;
+          await flushState(iteration);
+        }
+      }
       const procCtx = buildProcCtx(iteration + 1);
-      const initialPrompt = opts.buildPrompt(lastStatus, iteration);
+      let initialPrompt = opts.buildPrompt(lastStatus, iteration);
+      if (steerDecision) {
+        const who = steerDecision.actor ? ` from ${steerDecision.actor}` : "";
+        initialPrompt = `${initialPrompt}
+
+[human steer${who}]: ${steerDecision.message}`;
+      }
       const inputVerdict = await runProcessorChain(processors, (p) => p.processInput, initialPrompt, procCtx);
       if (inputVerdict.kind !== "continue") {
         loopAbort.abort();
@@ -1263,7 +2009,12 @@ async function agentLoop(opts) {
       process.stdout.write(`${logLabel} iteration ${iteration + 1}/${maxIterations} · ${turnsPerIteration} turns
 `);
       let responseText = "";
-      for await (const rawMsg of client.sendMessage({ prompt, sessionId: iteration > 0 ? lastSessionId : undefined, iteration: iteration + 1 })) {
+      for await (const rawMsg of client.sendMessage({
+        prompt,
+        sessionId: iteration > 0 ? lastSessionId : undefined,
+        iteration: iteration + 1,
+        ...opts.inbox ? { inboxStream: opts.inbox } : {}
+      })) {
         const outputVerdict = await runProcessorChain(processors, (p) => p.processOutput, rawMsg, procCtx);
         if (outputVerdict.kind === "abort") {
           loopAbort.abort();
@@ -1287,16 +2038,23 @@ async function agentLoop(opts) {
       lastResponseText = responseText;
       let status = parseAgentStatus(responseText);
       const rawResponse = opts.responseSchema ? parseAgentResponse(responseText) ?? parseRawJsonResponse(responseText) : null;
+      const validateResponse = (target) => {
+        const parsed = opts.responseSchema.safeParse(target);
+        if (!parsed.success)
+          lastResponseValidationError = parsed.error.message;
+        return parsed;
+      };
       if (opts.responseSchema && rawResponse !== null) {
-        const parsed = opts.responseSchema.safeParse(rawResponse);
+        const parsed = validateResponse(rawResponse);
         if (parsed.success) {
           const successStatus = status ?? { summary: "structured response completed", completed: [], blockers: [], exit_signal: true };
           process.stdout.write(`${logLabel} structured response validated after ${iteration + 1}/${maxIterations} iterations
 `);
+          const result2 = { agentId, label, sessionId: lastSessionId, lastStatus: successStatus, iterations: iteration + 1, response: parsed.data };
+          await writeSettledState(result2);
           opts.onAgentLifecycleEvent?.({ event: "agent.settled", at: Date.now(), agentId, label, outcome: "success", iterations: iteration + 1, durationMs: Date.now() - startedAt });
-          return { agentId, label, sessionId: lastSessionId, lastStatus: successStatus, iterations: iteration + 1, response: parsed.data };
+          return result2;
         }
-        lastResponseValidationError = parsed.error.message;
       }
       completedIterations = iteration + 1;
       process.stdout.write(`${logLabel} iteration ${iteration + 1} status: exit_signal=${status?.exit_signal ?? "(no status)"} blockers=${JSON.stringify(status?.blockers ?? [])}
@@ -1314,9 +2072,8 @@ async function agentLoop(opts) {
             opts.onIteration?.(iteration + 1, status);
             continue;
           }
-          const parsed = opts.responseSchema.safeParse({ ...status, ...rawResponse });
+          const parsed = validateResponse({ ...status, ...rawResponse });
           if (!parsed.success) {
-            lastResponseValidationError = parsed.error.message;
             process.stderr.write(`${logLabel} <response> SCHEMA FAILED: ${parsed.error.message}
 raw: ${JSON.stringify(rawResponse).slice(0, 400)}
 `);
@@ -1328,8 +2085,19 @@ raw: ${JSON.stringify(rawResponse).slice(0, 400)}
         }
         process.stdout.write(`${logLabel} done after ${iteration + 1}/${maxIterations} iterations
 `);
+        const result2 = { agentId, label, sessionId: lastSessionId, lastStatus: status, iterations: iteration + 1, response };
+        await writeSettledState(result2);
         opts.onAgentLifecycleEvent?.({ event: "agent.settled", at: Date.now(), agentId, label, outcome: "success", iterations: iteration + 1, durationMs: Date.now() - startedAt });
-        return { agentId, label, sessionId: lastSessionId, lastStatus: status, iterations: iteration + 1, response };
+        return result2;
+      }
+      if (opts.pause && opts.mode === "hitl" && status?.needs_input && pendingSteerPause === null) {
+        pendingSteerPause = {
+          reason: status.question?.trim() || "the agent requested human input",
+          correlationKey: null,
+          at: Date.now()
+        };
+        blockerStreak = null;
+        continue;
       }
       if (!status) {
         if (++iterationsWithoutStatus >= STALL_ITERATIONS)
@@ -1356,9 +2124,13 @@ raw: ${JSON.stringify(rawResponse).slice(0, 400)}
       throw new Error(`${logLabel} did not produce a valid <response> after ${maxIterations} iterations${lastResponseValidationError ? `: ${lastResponseValidationError}` : ""}. Response tail: ${lastResponseText.slice(-600)}`);
     process.stderr.write(`${logLabel} exhausted ${maxIterations} iterations, proceeding with available work
 `);
+    const result = { agentId, label, sessionId: lastSessionId, lastStatus, iterations: maxIterations };
+    await writeSettledState(result);
     opts.onAgentLifecycleEvent?.({ event: "agent.settled", at: Date.now(), agentId, label, outcome: "success", iterations: maxIterations, durationMs: Date.now() - startedAt });
-    return { agentId, label, sessionId: lastSessionId, lastStatus, iterations: maxIterations };
+    return result;
   } catch (err) {
+    if (isPauseSignal(err))
+      throw err;
     opts.onAgentLifecycleEvent?.({ event: "agent.settled", at: Date.now(), agentId, label, outcome: "failed", iterations: completedIterations, durationMs: Date.now() - startedAt, failureReason: err instanceof Error ? err.message : String(err) });
     throw err;
   }
@@ -1374,6 +2146,50 @@ function parseRawJsonResponse(text) {
   }
 }
 
+// src/agent/async-queue.ts
+class AsyncQueue {
+  buffer = [];
+  resolvers = [];
+  done = false;
+  push(value) {
+    if (this.done)
+      return;
+    const resolve = this.resolvers.shift();
+    if (resolve) {
+      resolve({ value, done: false });
+    } else {
+      this.buffer.push(value);
+    }
+  }
+  close() {
+    if (this.done)
+      return;
+    this.done = true;
+    while (this.resolvers.length > 0) {
+      const resolve = this.resolvers.shift();
+      resolve({ value: undefined, done: true });
+    }
+  }
+  [Symbol.asyncIterator]() {
+    return {
+      next: () => {
+        const buffered = this.buffer.shift();
+        if (buffered !== undefined)
+          return Promise.resolve({ value: buffered, done: false });
+        if (this.done)
+          return Promise.resolve({ value: undefined, done: true });
+        return new Promise((resolve) => {
+          this.resolvers.push(resolve);
+        });
+      },
+      return: () => {
+        this.close();
+        return Promise.resolve({ value: undefined, done: true });
+      }
+    };
+  }
+}
+
 // src/runtimes/claude.ts
 function now2() {
   return new Date().toISOString();
@@ -1393,6 +2209,8 @@ function translateMessage(message) {
         msgs.push({ type: "text", text: String(b.text ?? ""), timestamp: ts });
       if (b.type === "thinking")
         msgs.push({ type: "thinking", text: String(b.thinking ?? ""), timestamp: ts });
+      if (b.type === "redacted_thinking")
+        msgs.push({ type: "thinking", text: "(redacted)", timestamp: ts });
       if (b.type === "tool_use")
         msgs.push({ type: "tool_use", toolName: String(b.name ?? ""), toolInput: b.input ?? {}, toolUseId: String(b.id ?? ""), timestamp: ts });
     }
@@ -1431,15 +2249,20 @@ function translateMessage(message) {
   }
   return msgs;
 }
+var DEFAULT_CLAUDE_PATH = "/usr/local/bin/claude";
 
 class ClaudeRunner {
   options;
   config;
   supportsToolCallProcessor = true;
+  kind = "claude";
   constructor(_sandbox, options = {}, config = {}) {
     this.options = options;
     this.config = config;
   }
+  get model() {
+    return this.config.model ?? this.options.model ?? DEFAULT_CLAUDE_MODEL;
+  }
   async gateToolCall(call, ctx) {
     const verdict = await runProcessorChain(this.options.processors ?? [], (p) => p.processToolCall, call, ctx);
     if (verdict.kind === "continue")
@@ -1475,10 +2298,33 @@ class ClaudeRunner {
         return { hookSpecificOutput: { hookEventName: pre.hook_event_name, permissionDecision: "deny", permissionDecisionReason: gate.reason } };
       return { continue: false, systemMessage: gate.reason };
     };
+    const inboxQueue = opts.inboxStream ? new AsyncQueue : null;
+    if (inboxQueue) {
+      inboxQueue.push({
+        type: "user",
+        message: { role: "user", content: opts.prompt },
+        parent_tool_use_id: null
+      });
+      (async () => {
+        try {
+          for await (const ev of opts.inboxStream) {
+            const tag = ev.senderName ? `[message from ${ev.senderName}]
+` : `[user message]
+`;
+            inboxQueue.push({
+              type: "user",
+              message: { role: "user", content: tag + ev.text },
+              parent_tool_use_id: null
+            });
+          }
+        } catch {}
+      })();
+    }
+    const promptForQuery = inboxQueue ?? opts.prompt;
     try {
       let emittedAssistantText = false;
       for await (const message of query({
-        prompt: opts.prompt,
+        prompt: promptForQuery,
         options: {
           tools: this.options.allowedTools,
           allowedTools: this.options.allowedTools,
@@ -1489,7 +2335,7 @@ class ClaudeRunner {
           effort: this.config.effort,
           cwd: this.options.cwd,
           env: { ...process.env, ...this.config.env ?? {} },
-          pathToClaudeCodeExecutable: this.config.pathToClaudeCodeExecutable ?? process.env.CLAUDE_CODE_EXECUTABLE ?? "claude",
+          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 } } : {},
           resume: opts.sessionId,
           mcpServers: this.config.mcpServers,
@@ -1506,9 +2352,13 @@ class ClaudeRunner {
             emittedAssistantText = true;
           yield msg;
         }
+        if (raw.type === "result" && inboxQueue)
+          inboxQueue.close();
       }
     } catch (err) {
       yield { type: "error", text: formatError(err), timestamp: now2() };
+    } finally {
+      inboxQueue?.close();
     }
   }
 }
@@ -1519,7 +2369,7 @@ function createClaudeRuntime(config = {}) {
 }
 var claude_default = createClaudeRuntime();
 // src/sandbox.ts
-import { promises as fs } from "node:fs";
+import { promises as fs2 } from "node:fs";
 import { dirname as dirname2 } from "node:path";
 import { spawn } from "node:child_process";
 import { Sandbox } from "e2b";
@@ -1528,9 +2378,26 @@ import pRetry from "p-retry";
 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;
 function makeSandboxProvider(sb) {
+  const commands = sb.commands;
   return {
     sandboxId: sb.sandboxId,
-    commands: sb.commands,
+    commands: {
+      async run(cmd, opts) {
+        let stderr = "";
+        const result = await commands.run(cmd, {
+          ...opts,
+          onStderr: (chunk) => {
+            stderr += chunk;
+            opts?.onStderr?.(chunk);
+          }
+        });
+        return {
+          exitCode: result.exitCode,
+          stdout: result.stdout,
+          stderr: typeof result.stderr === "string" ? result.stderr : stderr
+        };
+      }
+    },
     files: {
       async write(path, content) {
         await sb.files.write(path, content);
@@ -1555,7 +2422,7 @@ function makeDesktopSandboxProvider(sb) {
   };
 }
 async function parseSseExecStream(body, opts) {
-  let stdout = "", exitCode = 0, exited = false;
+  let stdout = "", stderr = "", exitCode = 0, exited = false;
   const reader = body.getReader(), decoder = new TextDecoder;
   let buf = "";
   while (true) {
@@ -1573,13 +2440,14 @@ async function parseSseExecStream(body, opts) {
       let event;
       try {
         event = JSON.parse(line.slice(6));
-      } catch {
-        continue;
+      } catch (err) {
+        throw new Error(`Malformed sandbox exec event: ${err instanceof Error ? err.message : String(err)}`);
       }
       if (event.type === "stdout") {
         stdout += event.data ?? "";
         opts?.onStdout?.(event.data ?? "");
       } else if (event.type === "stderr") {
+        stderr += event.data ?? "";
         opts?.onStderr?.(event.data ?? "");
       } else if (event.type === "exit") {
         exitCode = event.exitCode ?? 0;
@@ -1591,7 +2459,9 @@ async function parseSseExecStream(body, opts) {
     if (exited)
       break;
   }
-  return { exitCode, stdout };
+  if (!exited)
+    throw new Error("Sandbox exec stream ended without an exit event");
+  return { exitCode, stdout, stderr };
 }
 function makeVercelSandboxProvider(sb, globalEnvs) {
   const mergeEnvs = (cmdEnvs) => globalEnvs ? { ...globalEnvs, ...cmdEnvs } : cmdEnvs;
@@ -1599,27 +2469,28 @@ function makeVercelSandboxProvider(sb, globalEnvs) {
     sandboxId: sb.sandboxId,
     commands: {
       async run(cmd, opts) {
-        const sudo = opts?.sudo === true;
-        if (opts?.background) {
-          sb.runCommand({ cmd: "sh", args: ["-c", cmd], cwd: opts.cwd, env: mergeEnvs(opts.envs), detached: true, ...sudo ? { sudo: true } : {} }).catch((err) => console.error(`[sandbox] background command failed: ${err instanceof Error ? err.message : String(err)}`));
-          return { exitCode: 0, stdout: "" };
-        }
         const signal = opts?.timeoutMs ? AbortSignal.timeout(opts.timeoutMs) : undefined;
         let stdout = "";
-        const handle = await sb.runCommand({ cmd: "sh", args: ["-c", cmd], cwd: opts?.cwd, env: mergeEnvs(opts?.envs), detached: true, signal, ...sudo ? { sudo: true } : {} });
+        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);
             }
           }
         }, { retries: 3, minTimeout: 1000, factor: 2 });
         const finished = await handle.wait();
-        return { exitCode: finished.exitCode, stdout };
+        return { exitCode: finished.exitCode, stdout, stderr };
       }
     },
     files: {
@@ -1653,6 +2524,7 @@ function makeLocalSandboxProvider() {
             stdio: ["ignore", "pipe", "pipe"]
           });
           let stdout = "";
+          let stderr = "";
           proc.stdout?.setEncoding("utf8");
           proc.stderr?.setEncoding("utf8");
           proc.stdout?.on("data", (chunk) => {
@@ -1660,17 +2532,18 @@ function makeLocalSandboxProvider() {
             opts?.onStdout?.(chunk);
           });
           proc.stderr?.on("data", (chunk) => {
+            stderr += chunk;
             opts?.onStderr?.(chunk);
           });
           proc.on("error", reject);
-          proc.on("close", (code) => resolve({ exitCode: code ?? 0, stdout }));
+          proc.on("close", (code) => resolve({ exitCode: code ?? 0, stdout, stderr }));
         });
       }
     },
     files: {
       async write(path, content) {
-        await fs.mkdir(dirname2(path), { recursive: true });
-        await fs.writeFile(path, content);
+        await fs2.mkdir(dirname2(path), { recursive: true });
+        await fs2.writeFile(path, content);
       }
     },
     async kill() {}
@@ -1845,10 +2718,18 @@ async function killAllSandboxes(onError) {
   }));
 }
 // src/workflow-steps/observability.ts
+var LIVE_EMIT_DRAIN_TIMEOUT_MS = 1500;
+
 class StepObservabilityCollector {
   metadata = {};
   events = [];
   subSteps = [];
+  liveEmitter;
+  ackedSeqs = new Set;
+  inFlight = new Set;
+  constructor(opts = {}) {
+    this.liveEmitter = opts.liveEmitter;
+  }
   setMetadata = async (data) => {
     Object.assign(this.metadata, data);
   };
@@ -1864,6 +2745,8 @@ class StepObservabilityCollector {
       });
       return result;
     } catch (err) {
+      if (isPauseSignal(err))
+        throw err;
       this.subSteps.push({
         name,
         startedAt,
@@ -1876,26 +2759,92 @@ class StepObservabilityCollector {
   };
   agentEvents = {
     emit: (event) => {
+      const seq = this.events.length;
       this.events.push(event);
+      if (this.liveEmitter) {
+        const tracked = this.liveEmitter(event, seq).then((ok) => {
+          if (ok)
+            this.ackedSeqs.add(seq);
+        }).catch(() => {});
+        this.inFlight.add(tracked);
+        tracked.finally(() => this.inFlight.delete(tracked));
+      }
     }
   };
-  snapshot() {
+  async drainInFlight(timeoutMs = LIVE_EMIT_DRAIN_TIMEOUT_MS) {
+    if (this.inFlight.size === 0)
+      return;
+    await Promise.race([
+      Promise.allSettled([...this.inFlight]),
+      new Promise((resolve) => setTimeout(resolve, timeoutMs))
+    ]);
+  }
+  async snapshot() {
+    await this.drainInFlight();
     const hasMetadata = Object.keys(this.metadata).length > 0;
-    const hasEvents = this.events.length > 0;
     const hasSubSteps = this.subSteps.length > 0;
+    const remainingEvents = this.events.filter((_, idx) => !this.ackedSeqs.has(idx));
+    const hasEvents = remainingEvents.length > 0;
     if (!hasMetadata && !hasEvents && !hasSubSteps)
       return;
     const result = {};
     if (hasMetadata)
       result.metadata = { ...this.metadata };
     if (hasEvents)
-      result.events = [...this.events];
+      result.events = remainingEvents;
     if (hasSubSteps)
       result.subSteps = [...this.subSteps];
     return result;
   }
 }
 
+// src/pause/checkpoint.ts
+async function checkpoint(name, fn) {
+  const existing = await readCheckpoint(name);
+  if (existing.found)
+    return existing.value;
+  const value = await fn();
+  await writeCheckpoint(name, value);
+  return value;
+}
+function scopedCheckpoint(scope) {
+  assertSafeCheckpointName(scope);
+  return async (name, fn) => {
+    assertSafeCheckpointName(name);
+    return checkpoint(`${scope}.${name}`, fn);
+  };
+}
+
+// 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`,
+        ttlMs: durationMs,
+        snapshot: false,
+        onExpiry: { mode: "resolve", value: undefined }
+      }, "sleep");
+    },
+    waitForEvent(req) {
+      return pause({
+        reason: req.reason,
+        correlationKey: req.correlationKey,
+        ...req.schema !== undefined ? { schema: req.schema } : {},
+        ...req.ttlMs !== undefined ? { ttlMs: req.ttlMs } : {}
+      }, "event");
+    }
+  };
+}
+
 // src/workflow-steps/runner.ts
 class StepValidationError extends Error {
   stepName;
@@ -1938,7 +2887,14 @@ 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;
+  const collector = new StepObservabilityCollector({ liveEmitter: opts.liveAgentEventEmitter });
+  const coord = { runId: opts.run.id, stepIndex: opts.stepIndex };
+  const pauseWithKind = function(req, kind) {
+    return corePause(req, coord, kind);
+  };
+  const pause = function(req) {
+    return corePause(req, coord);
+  };
   const stepCtx = {
     input: parsedInput.data,
     requestContext: opts.requestContext,
@@ -1951,13 +2907,30 @@ async function runWorkflowSingleStep(opts) {
     }),
     setMetadata: collector.setMetadata,
     step: collector.step,
-    agentEvents: collector.agentEvents
+    agentEvents: collector.agentEvents,
+    checkpoint: scopedCheckpoint(`step${opts.stepIndex}`),
+    pause,
+    ...buildPauseWrappers(pauseWithKind)
   };
-  const output = await step.run(stepCtx);
+  let output;
+  try {
+    const bridged = setActiveStepBridge({ stepIndex: opts.stepIndex });
+    try {
+      output = await runWithActiveStep({ stepIndex: opts.stepIndex }, () => Promise.resolve(step.run(stepCtx)));
+    } finally {
+      restoreActiveStepBridge(bridged);
+    }
+  } catch (err) {
+    if (isPauseSignal(err)) {
+      const observability2 = await collector.snapshot();
+      throw new PauseSignal(err.pauseId, err.pauseRequest, observability2);
+    }
+    throw err;
+  }
   const parsedOutput = step.output.safeParse(output);
   if (!parsedOutput.success)
     throw new StepValidationError(step.name, "output", parsedOutput.error);
-  const observability = collector.snapshot();
+  const observability = await collector.snapshot();
   return observability === undefined ? { output: parsedOutput.data } : { output: parsedOutput.data, observability };
 }
 async function runWorkflowSteps(opts) {
@@ -1991,7 +2964,14 @@ async function runWorkflowSteps(opts) {
       await opts.onStepFailed?.(i, step.name, err, 0);
       throw err;
     }
-    const collector = new StepObservabilityCollector;
+    const collector = new StepObservabilityCollector({ liveEmitter: opts.liveAgentEventEmitter });
+    const coord = { runId: run.id, stepIndex: i };
+    const pauseWithKind = function(req, kind) {
+      return corePause(req, coord, kind);
+    };
+    const pause = function(req) {
+      return corePause(req, coord);
+    };
     const stepCtx = {
       input: parsedStepInput.data,
       requestContext,
@@ -2002,16 +2982,23 @@ async function runWorkflowSteps(opts) {
       invokeChild,
       setMetadata: collector.setMetadata,
       step: collector.step,
-      agentEvents: collector.agentEvents
+      agentEvents: collector.agentEvents,
+      checkpoint: scopedCheckpoint(`step${i}`),
+      pause,
+      ...buildPauseWrappers(pauseWithKind)
     };
     const startedAt = Date.now();
     let output;
     try {
-      output = await step.run(stepCtx);
+      output = await runWithActiveStep({ stepIndex: i }, () => Promise.resolve(step.run(stepCtx)));
     } catch (err) {
+      if (isPauseSignal(err)) {
+        const observability3 = await collector.snapshot();
+        throw new PauseSignal(err.pauseId, err.pauseRequest, observability3);
+      }
       const wrapped = err instanceof Error ? err : new Error(String(err));
       const durationMs2 = Date.now() - startedAt;
-      const observability2 = collector.snapshot();
+      const observability2 = await collector.snapshot();
       stepResults.push({
         name: step.name,
         status: "failed",
@@ -2026,7 +3013,7 @@ async function runWorkflowSteps(opts) {
     if (!parsedOutput.success) {
       const err = new StepValidationError(step.name, "output", parsedOutput.error);
       const durationMs2 = Date.now() - startedAt;
-      const observability2 = collector.snapshot();
+      const observability2 = await collector.snapshot();
       stepResults.push({
         name: step.name,
         status: "failed",
@@ -2039,7 +3026,7 @@ async function runWorkflowSteps(opts) {
     }
     const durationMs = Date.now() - startedAt;
     current = parsedOutput.data;
-    const observability = collector.snapshot();
+    const observability = await collector.snapshot();
     stepResults.push({
       name: step.name,
       status: "completed",
@@ -2164,9 +3151,13 @@ function defineStep(opts) {
 }
 // src/step-invocation/protocol.ts
 var STEP_RESULT_PREFIX = "__AC_STEP_RESULT__";
+var STEP_PAUSE_PREFIX = "__AC_STEP_PAUSE__";
 function stepResultLinePrefix(token) {
   return `${STEP_RESULT_PREFIX}${token}:`;
 }
+function stepPauseLinePrefix(token) {
+  return `${STEP_PAUSE_PREFIX}${token}:`;
+}
 var RUNNER_BUNDLE_PATH = "/tmp/runner.bundle.js";
 var RUNNER_COMMAND = `node ${RUNNER_BUNDLE_PATH}`;
 var STEP_ENV = {
@@ -2175,7 +3166,8 @@ var STEP_ENV = {
   STEP_INDEX: "AC_STEP_INDEX",
   STEP_INPUT_PATH: "AC_STEP_INPUT_PATH",
   REQUEST_CONTEXT_PATH: "AC_REQUEST_CONTEXT_PATH",
-  STEP_RESULT_TOKEN: "AC_STEP_RESULT_TOKEN"
+  STEP_RESULT_TOKEN: "AC_STEP_RESULT_TOKEN",
+  STEP_RESUME: "AC_STEP_RESUME"
 };
 function stepInputPath(stepIndex) {
   return `/tmp/wf/step-input-${stepIndex}.json`;
@@ -2184,7 +3176,36 @@ function requestContextPath(stepIndex) {
   return `/tmp/wf/request-context-${stepIndex}.json`;
 }
 // src/step-invocation/invoker.ts
-import { randomBytes } from "node:crypto";
+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()
+  })).optional()
+}).passthrough();
+var StepResultEnvelopeSchema = z10.discriminatedUnion("ok", [
+  z10.object({
+    ok: z10.literal(true),
+    output: z10.unknown().optional(),
+    observability: StepObservabilitySchema.optional()
+  }),
+  z10.object({
+    ok: z10.literal(false),
+    kind: z10.enum(["protocol", "user-step"]),
+    error: z10.string().optional()
+  })
+]);
+var StepPauseEnvelopeSchema = z10.object({
+  pauseId: z10.string().min(1),
+  pauseRequest: StepPauseRequestSchema,
+  observability: StepObservabilitySchema.optional()
+});
 function buildStepEnvs(args) {
   return {
     [STEP_ENV.RUN_ID]: args.runId,
@@ -2192,30 +3213,64 @@ function buildStepEnvs(args) {
     [STEP_ENV.STEP_INDEX]: String(args.stepIndex),
     [STEP_ENV.STEP_INPUT_PATH]: stepInputPath(args.stepIndex),
     [STEP_ENV.REQUEST_CONTEXT_PATH]: requestContextPath(args.stepIndex),
-    [STEP_ENV.STEP_RESULT_TOKEN]: args.resultToken
+    [STEP_ENV.STEP_RESULT_TOKEN]: args.resultToken,
+    [STEP_ENV.STEP_RESUME]: args.isResume ? "1" : "0"
   };
 }
 function parseStepResult(stdout, resultToken) {
-  const prefix = stepResultLinePrefix(resultToken);
-  const line = stdout.split(/\r?\n/).find((l) => l.startsWith(prefix));
-  if (!line)
+  const resultPrefix = stepResultLinePrefix(resultToken);
+  const pausePrefix = stepPauseLinePrefix(resultToken);
+  let resultLine;
+  let pauseLine;
+  for (const line of stdout.split(/\r?\n/)) {
+    if (!pauseLine && line.startsWith(pausePrefix))
+      pauseLine = line;
+    if (!resultLine && line.startsWith(resultPrefix))
+      resultLine = line;
+    if (pauseLine && resultLine)
+      break;
+  }
+  if (pauseLine) {
+    try {
+      const raw = JSON.parse(pauseLine.slice(pausePrefix.length));
+      const parsed2 = StepPauseEnvelopeSchema.safeParse(raw);
+      if (!parsed2.success) {
+        return { ok: false, error: { kind: "protocol", message: `step pause schema validation failed: ${parsed2.error.message}` } };
+      }
+      return {
+        ok: "paused",
+        pauseId: parsed2.data.pauseId,
+        pauseRequest: parsed2.data.pauseRequest,
+        ...parsed2.data.observability ? { observability: parsed2.data.observability } : {}
+      };
+    } catch {
+      return { ok: false, error: { kind: "protocol", message: "step pause JSON parse failed" } };
+    }
+  }
+  if (!resultLine)
     return null;
   let parsed;
   try {
-    parsed = JSON.parse(line.slice(prefix.length));
+    const raw = JSON.parse(resultLine.slice(resultPrefix.length));
+    const result = StepResultEnvelopeSchema.safeParse(raw);
+    if (!result.success) {
+      const kind2 = raw && typeof raw === "object" && typeof raw.kind === "string" ? ` (kind=${raw.kind})` : "";
+      return { ok: false, error: { kind: "protocol", message: `step result schema validation failed${kind2}: ${result.error.message}` } };
+    }
+    parsed = result.data;
   } catch {
     return { ok: false, error: { kind: "protocol", message: "step result JSON parse failed" } };
   }
   if (parsed.ok) {
     return parsed.observability ? { ok: true, output: parsed.output, observability: parsed.observability } : { ok: true, output: parsed.output };
   }
-  const kind = parsed.kind === "user-step" ? "user-step" : "protocol";
+  const kind = parsed.kind;
   const baseMessage = parsed.error ?? "step body failed without a message";
-  const message = parsed.kind && parsed.kind !== "user-step" && parsed.kind !== "protocol" ? `(unknown kind "${parsed.kind}") ${baseMessage}` : baseMessage;
+  const message = baseMessage;
   return { ok: false, error: { kind, message } };
 }
 async function invokeStep(sandbox, request, opts) {
-  const resultToken = randomBytes(16).toString("hex");
+  const resultToken = randomBytes2(16).toString("hex");
   await Promise.all([
     sandbox.files.write(stepInputPath(request.stepIndex), JSON.stringify(request.input)),
     sandbox.files.write(requestContextPath(request.stepIndex), JSON.stringify(request.requestContext))
@@ -2225,10 +3280,13 @@ async function invokeStep(sandbox, request, opts) {
     ...buildStepEnvs({
       runId: request.runId,
       stepIndex: request.stepIndex,
-      resultToken
+      resultToken,
+      isResume: opts?.isResume
     })
   };
-  const sentinelPrefix = stepResultLinePrefix(resultToken);
+  const resultSentinel = stepResultLinePrefix(resultToken);
+  const pauseSentinel = stepPauseLinePrefix(resultToken);
+  const isSentinel = (line) => line.startsWith(resultSentinel) || line.startsWith(pauseSentinel);
   const makeLineSplitter = (sink, filterSentinel) => {
     if (!sink)
       return { onChunk: undefined, flush: () => {} };
@@ -2241,7 +3299,7 @@ async function invokeStep(sandbox, request, opts) {
 `)) !== -1) {
           const line = buf.slice(0, nl);
           buf = buf.slice(nl + 1);
-          if (filterSentinel && line.startsWith(sentinelPrefix))
+          if (filterSentinel && isSentinel(line))
             continue;
           sink(line);
         }
@@ -2251,7 +3309,7 @@ async function invokeStep(sandbox, request, opts) {
           return;
         const line = buf;
         buf = "";
-        if (filterSentinel && line.startsWith(sentinelPrefix))
+        if (filterSentinel && isSentinel(line))
           return;
         sink(line);
       }
@@ -2271,11 +3329,21 @@ async function invokeStep(sandbox, request, opts) {
   if (parsed)
     return parsed;
   if (result.exitCode !== 0) {
+    const stderrTail = result.stderr.trim().slice(-2000);
+    const stdoutTail = result.stdout.trim().slice(-2000);
+    const details = [
+      stderrTail ? `stderr:
+${stderrTail}` : "",
+      stdoutTail ? `stdout:
+${stdoutTail}` : ""
+    ].filter(Boolean).join(`
+`);
     return {
       ok: false,
       error: {
         kind: "runner-exit",
-        message: `runner subprocess exited ${result.exitCode} before emitting a step result`,
+        message: `runner subprocess exited ${result.exitCode} before emitting a step result${details ? `
+${details}` : ""}`,
         exitCode: result.exitCode
       }
     };
@@ -2287,10 +3355,8 @@ async function invokeStep(sandbox, request, opts) {
 }
 // src/step-invocation/server.ts
 import { readFileSync } from "node:fs";
-function emitResult(token, payload) {
+function writeSentinelLine(line) {
   return new Promise((resolve, reject) => {
-    const line = `${STEP_RESULT_PREFIX}${token}:${JSON.stringify(payload)}
-`;
     process.stdout.write(line, (err) => {
       if (err)
         reject(err);
@@ -2299,13 +3365,27 @@ function emitResult(token, payload) {
     });
   });
 }
+function emitResult(token, payload) {
+  return writeSentinelLine(`${STEP_RESULT_PREFIX}${token}:${JSON.stringify(payload)}
+`);
+}
+function emitPause(token, signal) {
+  const body = JSON.stringify({
+    pauseId: signal.pauseId,
+    pauseRequest: signal.pauseRequest,
+    ...signal.observability ? { observability: signal.observability } : {}
+  });
+  return writeSentinelLine(`${STEP_PAUSE_PREFIX}${token}:${body}
+`);
+}
 function scrubProtocolEnvs() {
   for (const key of [
     STEP_ENV.STEP_MODE,
     STEP_ENV.STEP_INDEX,
     STEP_ENV.STEP_INPUT_PATH,
     STEP_ENV.REQUEST_CONTEXT_PATH,
-    STEP_ENV.STEP_RESULT_TOKEN
+    STEP_ENV.STEP_RESULT_TOKEN,
+    STEP_ENV.STEP_RESUME
   ]) {
     delete process.env[key];
   }
@@ -2319,12 +3399,14 @@ async function serveStep(handler) {
   }
   let exitCode = 0;
   let payload;
+  let pauseSignal;
   let setupResult;
   try {
     const runId = process.env[STEP_ENV.RUN_ID];
     const stepIndexEnv = process.env[STEP_ENV.STEP_INDEX];
     const inputPath = process.env[STEP_ENV.STEP_INPUT_PATH];
     const ctxPath = process.env[STEP_ENV.REQUEST_CONTEXT_PATH];
+    const isResume = process.env[STEP_ENV.STEP_RESUME] === "1";
     const stepIndex = stepIndexEnv === undefined ? Number.NaN : Number(stepIndexEnv);
     if (!runId || !inputPath || !ctxPath || !Number.isFinite(stepIndex)) {
       throw new Error(`step-server missing required env: ${[
@@ -2335,8 +3417,8 @@ async function serveStep(handler) {
       ].filter(Boolean).join(", ")}`);
     }
     const input = JSON.parse(readFileSync(inputPath, "utf8"));
-    const requestContext = JSON.parse(readFileSync(ctxPath, "utf8"));
-    setupResult = { runId, stepIndex, input, requestContext };
+    const requestContext = RequestContextWireSchema.parse(JSON.parse(readFileSync(ctxPath, "utf8")));
+    setupResult = { runId, stepIndex, isResume, input, requestContext };
   } catch (err) {
     exitCode = 1;
     payload = { ok: false, kind: "protocol", error: err instanceof Error ? err.message : String(err) };
@@ -2347,32 +3429,76 @@ async function serveStep(handler) {
       const { output, observability } = await handler(setupResult);
       payload = observability ? { ok: true, output, observability } : { ok: true, output };
     } catch (err) {
-      exitCode = 1;
-      payload = { ok: false, kind: "user-step", error: err instanceof Error ? err.message : String(err) };
+      if (isPauseSignal(err)) {
+        pauseSignal = err;
+      } else {
+        exitCode = 1;
+        payload = { ok: false, kind: "user-step", error: err instanceof Error ? err.message : String(err) };
+      }
     }
   }
+  if (pauseSignal) {
+    await emitPause(token, pauseSignal);
+    process.exit(0);
+  }
   await emitResult(token, payload);
   process.exit(exitCode);
 }
-// src/step-invocation/types.ts
-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/agent/run-agent.ts
-import { z as z6 } from "zod";
+import { z as z11 } from "zod";
+import { randomUUID as randomUUID2 } from "node:crypto";
 
 // 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';
 
 // src/agent/run-agent.ts
+async function runInboxPoller(opts) {
+  let afterSeq = 0;
+  const headers = {
+    authorization: `Bearer ${opts.token}`,
+    accept: "application/json"
+  };
+  let backoffMs = 0;
+  while (!opts.signal.aborted) {
+    if (backoffMs > 0) {
+      await new Promise((resolve) => setTimeout(resolve, backoffMs));
+      if (opts.signal.aborted)
+        return;
+    }
+    const url = `${opts.baseUrl.replace(/\/+$/, "")}` + `/api/v1/internal/runs/${opts.runId}/agents/${encodeURIComponent(opts.agentId)}/inbox?afterSeq=${afterSeq}`;
+    try {
+      const res = await fetch(url, { method: "GET", headers, signal: opts.signal });
+      if (!res.ok) {
+        if (res.status === 401 || res.status === 403)
+          return;
+        backoffMs = Math.min(8000, (backoffMs || 500) * 2);
+        continue;
+      }
+      backoffMs = 0;
+      const body = await res.json();
+      for (const m of body.messages ?? []) {
+        opts.inbox.push({ text: m.body, senderName: m.senderName });
+        if (m.seq > afterSeq)
+          afterSeq = m.seq;
+      }
+    } catch (err) {
+      if (opts.signal.aborted)
+        return;
+      backoffMs = Math.min(8000, (backoffMs || 500) * 2);
+      if (backoffMs >= 4000) {
+        process.stderr.write(`[inbox-poller] poll failed, backing off ${backoffMs}ms: ${err instanceof Error ? err.message : String(err)}
+`);
+      }
+    }
+  }
+}
 var PROTOCOL_SUFFIX = stripFrontmatter(protocol_suffix_default);
+var HITL_ASK_INSTRUCTION = [
+  "## Asking a human",
+  "",
+  "If you hit a decision or need information only a human can provide, set " + '`"needs_input": true` in your `<status>` block, put your question in a ' + '`"question"` field, set `"exit_signal": false`, and stop. The workflow ' + "pauses and a human answers; their reply arrives as your next message. Use " + "this only when you genuinely cannot proceed on your own — prefer making a " + "reasonable decision and continuing."
+].join(`
+`);
 function stripFrontmatter(content) {
   if (!content.startsWith("---"))
     return content;
@@ -2381,29 +3507,29 @@ function stripFrontmatter(content) {
   return end === -1 ? content : content.slice(end + 4).trimStart();
 }
 function zodTypeName(schema) {
-  if (schema instanceof z6.ZodString)
+  if (schema instanceof z11.ZodString)
     return "string";
-  if (schema instanceof z6.ZodNumber)
+  if (schema instanceof z11.ZodNumber)
     return "number";
-  if (schema instanceof z6.ZodBoolean)
+  if (schema instanceof z11.ZodBoolean)
     return "boolean";
-  if (schema instanceof z6.ZodArray)
+  if (schema instanceof z11.ZodArray)
     return `${zodTypeName(schema.element)}[]`;
-  if (schema instanceof z6.ZodEnum)
+  if (schema instanceof z11.ZodEnum)
     return schema.options.map((o) => `"${o}"`).join(" | ");
-  if (schema instanceof z6.ZodOptional)
+  if (schema instanceof z11.ZodOptional)
     return `${zodTypeName(schema.unwrap())} (optional)`;
-  if (schema instanceof z6.ZodNullable)
+  if (schema instanceof z11.ZodNullable)
     return `${zodTypeName(schema.unwrap())} | null`;
-  if (schema instanceof z6.ZodLiteral)
+  if (schema instanceof z11.ZodLiteral)
     return `"${String(schema.value)}"`;
-  if (schema instanceof z6.ZodObject)
+  if (schema instanceof z11.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 z6.ZodObject ? schema.shape : null;
+  const shape = schema instanceof z11.ZodObject ? schema.shape : null;
   const body = shape ? (() => {
     const entries = Object.entries(shape);
     const example = Object.fromEntries(entries.map(([k, v]) => [k, `<${zodTypeName(v)}>`]));
@@ -2428,44 +3554,96 @@ function buildResponseFormatAppendix(schema) {
   return [...header, ...body].join(`
 `);
 }
+function resolveAgentId(explicitId) {
+  if (explicitId)
+    return explicitId;
+  const activeCall = nextAgentCallInActiveStep();
+  if (activeCall === null)
+    return randomUUID2();
+  return `step${activeCall.stepIndex}-agent-${activeCall.callIndex}`;
+}
 async function agent(opts) {
   const workingDir = opts.workingDir ?? "";
-  return agentLoop({
-    runtime: (runtimeOpts) => opts.runtime.create(opts.sandbox, runtimeOpts),
-    ...opts.agentId !== undefined ? { agentId: opts.agentId } : {},
-    ...opts.label !== undefined ? { label: opts.label } : {},
-    ...opts.budget?.turnsPerIteration !== undefined ? { turnsPerIteration: opts.budget.turnsPerIteration } : {},
-    ...opts.budget?.maxIterations !== undefined ? { maxIterations: opts.budget.maxIterations } : {},
-    ...opts.tools !== undefined ? { allowedTools: opts.tools } : {},
-    ...opts.responseSchema !== undefined ? { responseSchema: opts.responseSchema } : {},
-    ...workingDir ? { cwd: workingDir } : {},
-    buildPrompt: (_lastStatus, iteration) => {
-      if (iteration > 0)
-        return PROTOCOL_SUFFIX;
-      const base = stripFrontmatter(opts.prompt);
-      return opts.responseSchema ? `${base}
-
-${PROTOCOL_SUFFIX}
-
-${buildResponseFormatAppendix(opts.responseSchema)}` : `${base}
+  const agentId = resolveAgentId(opts.agentId);
+  const callbackUrl = process.env.AGENT_COMPOSE_URL;
+  const callbackToken = process.env.AGENT_COMPOSE_RUN_TOKEN;
+  const runId = process.env.RUN_ID;
+  const inbox = callbackUrl && callbackToken && runId ? new AsyncQueue : undefined;
+  const inboxAbort = new AbortController;
+  if (inbox && callbackUrl && callbackToken && runId) {
+    runInboxPoller({
+      baseUrl: callbackUrl,
+      token: callbackToken,
+      runId,
+      agentId,
+      inbox,
+      signal: inboxAbort.signal
+    });
+  }
+  if (callbackUrl && callbackToken && runId) {
+    runControlPoller({
+      baseUrl: callbackUrl,
+      token: callbackToken,
+      runId,
+      agentId,
+      signal: inboxAbort.signal
+    });
+  }
+  const activeStepForPause = getActiveStep();
+  const steerPause = activeStepForPause && runId ? function steerPauseFn(req, agentScope) {
+    return corePause(req, {
+      runId,
+      stepIndex: activeStepForPause.stepIndex,
+      agentScope
+    });
+  } : undefined;
+  const mode = opts.mode ?? "auto";
+  try {
+    return await agentLoop({
+      runtime: (runtimeOpts) => opts.runtime.create(opts.sandbox, runtimeOpts),
+      agentId,
+      ...opts.label !== undefined ? { label: opts.label } : {},
+      ...opts.budget?.turnsPerIteration !== undefined ? { turnsPerIteration: opts.budget.turnsPerIteration } : {},
+      ...opts.budget?.maxIterations !== undefined ? { maxIterations: opts.budget.maxIterations } : {},
+      ...opts.tools !== undefined ? { allowedTools: opts.tools } : {},
+      ...opts.responseSchema !== undefined ? { responseSchema: opts.responseSchema } : {},
+      ...workingDir ? { cwd: workingDir } : {},
+      buildPrompt: (_lastStatus, iteration) => {
+        if (iteration > 0)
+          return PROTOCOL_SUFFIX;
+        const base = stripFrontmatter(opts.prompt);
+        const parts = [base, PROTOCOL_SUFFIX];
+        if (mode === "hitl")
+          parts.push(HITL_ASK_INSTRUCTION);
+        if (opts.responseSchema)
+          parts.push(buildResponseFormatAppendix(opts.responseSchema));
+        return parts.join(`
 
-${PROTOCOL_SUFFIX}`;
-    },
-    ...opts.events ? { onAgentLifecycleEvent: (event) => {
-      opts.events?.emit(event);
-    } } : {},
-    ...opts.onAgentEvent ? { onAgentEvent: opts.onAgentEvent } : {},
-    ...opts.onIteration ? { onIteration: opts.onIteration } : {},
-    ...opts.processors?.length ? { processors: opts.processors } : {},
-    requestContext: opts.requestContext ?? RequestContext.fromReserved({
-      teamId: "",
-      runId: "",
-      workflowId: "",
-      factoryId: null,
-      apiKeyScopes: [],
-      parentRunId: null
-    })
-  });
+`);
+      },
+      ...opts.events ? { onAgentLifecycleEvent: (event) => {
+        opts.events?.emit(event);
+      } } : {},
+      ...opts.onAgentEvent ? { onAgentEvent: opts.onAgentEvent } : {},
+      ...opts.onIteration ? { onIteration: opts.onIteration } : {},
+      ...opts.processors?.length ? { processors: opts.processors } : {},
+      requestContext: opts.requestContext ?? RequestContext.fromReserved({
+        teamId: "",
+        runId: "",
+        workflowId: "",
+        factoryId: null,
+        apiKeyScopes: [],
+        parentRunId: null
+      }),
+      ...inbox ? { inbox } : {},
+      mode,
+      consumeSteerPending: () => consumeSteerPending(agentId),
+      ...steerPause ? { pause: steerPause } : {}
+    });
+  } finally {
+    inbox?.close();
+    inboxAbort.abort();
+  }
 }
 export {
   writeTool,
@@ -2497,7 +3675,6 @@ export {
   getSandboxQuotas,
   formatError,
   editTool,
-  discoverRuntimeName,
   denyTools,
   deleteSandboxSnapshot,
   defineWorkflow,
@@ -2527,11 +3704,16 @@ export {
   StepValidationError,
   StepExecutionError,
   STEP_RESULT_PREFIX,
+  STEP_PAUSE_PREFIX,
   STEP_ENV,
   ReservedKeyError,
   RequestContext,
   RUNNER_COMMAND,
   RUNNER_BUNDLE_PATH,
+  PauseSchemaError,
+  PauseRequestError,
+  PauseExpiredError,
+  PauseError,
   NonSerialisableValueError,
   LATEST_VERSION,
   EngineError,