@agent-compose/sdk 0.5.9 → 0.7.0

package/dist/index.js

@@ -717,7 +717,17 @@ async function corePause(req, coord, kind = "custom") {
 
 // src/utils/errors.ts
 function formatError(err) {
-  return err instanceof Error ? err.message : String(err);
+  if (!(err instanceof Error))
+    return String(err);
+  const parts = [err.message];
+  const seen = new Set([err]);
+  let cause = err.cause;
+  while (cause != null && !seen.has(cause)) {
+    seen.add(cause);
+    parts.push(cause instanceof Error ? cause.message : String(cause));
+    cause = cause instanceof Error ? cause.cause : undefined;
+  }
+  return parts.join(": ");
 }
 
 // src/runtimes/vercel.ts
@@ -1103,6 +1113,166 @@ function redactPattern(pattern, replacement = "[REDACTED]") {
     }
   };
 }
+// src/agent/pause-client.ts
+var isAbort = (signal) => Boolean(signal?.aborted);
+async function requestPauseAndAwait(opts, fetchImpl = fetch) {
+  const base = opts.baseUrl.replace(/\/+$/, "");
+  const headers = {
+    authorization: `Bearer ${opts.token}`,
+    "content-type": "application/json",
+    accept: "application/json"
+  };
+  const createRes = await fetchImpl(`${base}/api/v1/runs/${opts.runId}/pauses`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      reason: opts.reason,
+      ...opts.ttlMs !== undefined ? { ttlMs: opts.ttlMs } : {},
+      ...opts.options ? { options: opts.options } : {},
+      ...opts.action ? { action: opts.action } : {},
+      ...opts.correlationKey ? { correlationKey: opts.correlationKey } : {}
+    }),
+    ...opts.signal ? { signal: opts.signal } : {}
+  });
+  if (!createRes.ok) {
+    const text = await createRes.text().catch(() => "");
+    throw new Error(`pause create failed (${createRes.status}): ${text.slice(0, 300)}`);
+  }
+  const { pauseId } = await createRes.json();
+  const pollUrl = `${base}/api/v1/runs/${opts.runId}/pauses/${pauseId}`;
+  let backoffMs = 0;
+  for (;; ) {
+    if (isAbort(opts.signal))
+      throw new Error("pause wait aborted");
+    if (backoffMs > 0)
+      await new Promise((r) => setTimeout(r, backoffMs));
+    let res;
+    try {
+      res = await fetchImpl(pollUrl, { method: "GET", headers, ...opts.signal ? { signal: opts.signal } : {} });
+    } catch (err) {
+      if (isAbort(opts.signal))
+        throw err;
+      backoffMs = Math.min(8000, (backoffMs || 500) * 2);
+      continue;
+    }
+    if (!res.ok) {
+      backoffMs = Math.min(8000, (backoffMs || 500) * 2);
+      continue;
+    }
+    backoffMs = 0;
+    const body = await res.json();
+    if (body.status === "pending")
+      continue;
+    return { status: body.status, decision: body.resumePayload ?? null };
+  }
+}
+
+// src/processors/gate-pause.ts
+var DENY_ANSWERS = new Set(["deny", "no", "reject", "decline", "block"]);
+function answerText(decision) {
+  const raw = decision !== null && typeof decision === "object" && "decision" in decision ? decision.decision : decision;
+  return typeof raw === "string" ? raw.trim() : raw == null ? "" : JSON.stringify(raw);
+}
+function createGatePauseProcessor(opts) {
+  return {
+    name: "gate-pause",
+    async processToolCall(call, ctx) {
+      const approval = await opts.policy(call, ctx);
+      if (!approval)
+        return Verdict.continue(call);
+      const conn = opts.connection ?? {
+        baseUrl: process.env.AGENT_COMPOSE_URL ?? "",
+        token: process.env.AGENT_COMPOSE_RUN_TOKEN ?? "",
+        runId: process.env.RUN_ID ?? ""
+      };
+      if (!conn.baseUrl || !conn.token || !conn.runId)
+        return Verdict.continue(call);
+      const decision = await requestPauseAndAwait({
+        baseUrl: conn.baseUrl,
+        token: conn.token,
+        runId: conn.runId,
+        reason: approval.reason,
+        action: { tool: call.toolName, input: call.toolInput },
+        options: approval.options ?? [{ id: "approve", label: "Approve" }, { id: "deny", label: "Deny" }],
+        signal: ctx.abortSignal
+      });
+      const answer = answerText(decision.decision);
+      if (decision.status === "resolved" && !DENY_ANSWERS.has(answer.toLowerCase())) {
+        return Verdict.continue(call);
+      }
+      const why = decision.status === "resolved" ? `denied: ${answer}` : `${decision.status} with no approval`;
+      return Verdict.deny(`Human ${why}. Tool "${call.toolName}" was not run — adjust course or ask again.`);
+    }
+  };
+}
+// src/processors/ask-human.ts
+var ASK_USER_QUESTION_TOOL = "AskUserQuestion";
+function parseAsk(input) {
+  const questions = Array.isArray(input.questions) ? input.questions : [];
+  const first = questions[0] ?? {};
+  const head = typeof first.question === "string" && first.question.trim() ? first.question.trim() : "The agent needs your input to continue.";
+  const extra = questions.length > 1 ? ` (+${questions.length - 1} more question${questions.length > 2 ? "s" : ""})` : "";
+  const options = Array.isArray(first.options) ? first.options.map((o) => String(o?.label ?? "").trim()).filter(Boolean).map((label) => ({ id: label, label })) : [];
+  return { reason: head + extra, options };
+}
+function answerText2(decision) {
+  const raw = decision !== null && typeof decision === "object" && "decision" in decision ? decision.decision : decision;
+  return typeof raw === "string" ? raw.trim() : raw == null ? "" : JSON.stringify(raw);
+}
+function parseAgentcPause(command) {
+  if (!/(^|\s|&&|;|\|)\s*agentc\s+pause(\s|$)/.test(command))
+    return null;
+  const r = command.match(/--reason(?:=|\s+)(?:"([^"]*)"|'([^']*)'|(\S+))/);
+  const reason = (r?.[1] ?? r?.[2] ?? r?.[3] ?? "The agent needs your input to continue.").trim();
+  const options = [...command.matchAll(/--option(?:=|\s+)(?:"([^"]*)"|'([^']*)'|(\S+))/g)].map((m) => (m[1] ?? m[2] ?? m[3] ?? "").trim()).filter(Boolean).map((label) => ({ id: label, label }));
+  return { reason, options };
+}
+function extractAsk(call) {
+  if (call.toolName === ASK_USER_QUESTION_TOOL)
+    return parseAsk(call.toolInput);
+  if (call.toolName === "Bash") {
+    const cmd = call.toolInput?.command;
+    return typeof cmd === "string" ? parseAgentcPause(cmd) : null;
+  }
+  return null;
+}
+function createAskHumanProcessor(opts = {}) {
+  return {
+    name: "ask-human",
+    async processToolCall(call, ctx) {
+      const ask = extractAsk(call);
+      if (!ask)
+        return Verdict.continue(call);
+      const conn = opts.connection ?? {
+        baseUrl: process.env.AGENT_COMPOSE_URL ?? "",
+        token: process.env.AGENT_COMPOSE_RUN_TOKEN ?? "",
+        runId: process.env.RUN_ID ?? ""
+      };
+      if (!conn.baseUrl || !conn.token || !conn.runId)
+        return Verdict.continue(call);
+      let decision;
+      try {
+        decision = await requestPauseAndAwait({
+          baseUrl: conn.baseUrl,
+          token: conn.token,
+          runId: conn.runId,
+          reason: ask.reason,
+          ...ask.options.length ? { options: ask.options } : {},
+          action: { tool: call.toolName, input: call.toolInput },
+          signal: ctx.abortSignal
+        });
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return Verdict.abort(`Could not ask the human — the run could not be paused (${msg}). Stopping rather than guessing an answer.`);
+      }
+      if (decision.status === "resolved") {
+        const answer = answerText2(decision.decision);
+        return Verdict.deny(`The human answered: ${answer || "(no text returned)"}. Continue using this answer.`);
+      }
+      return Verdict.deny(`No answer came back (${decision.status}). Do NOT assume an answer — ask again, or stop and report exactly what you need from a human.`);
+    }
+  };
+}
 // src/client.ts
 import { ofetch } from "ofetch";
 
@@ -1983,7 +2153,7 @@ async function agentLoop(opts) {
   const logLabel = opts.label ?? "[Agent Loop]";
   const startedAt = Date.now();
   const turnsPerIteration = opts.turnsPerIteration;
-  const maxIterations = opts.maxIterations ?? (turnsPerIteration === undefined ? 1 : 8);
+  const maxIterations = opts.maxIterations ?? (turnsPerIteration === undefined ? 3 : 8);
   let schemaRetriesLeft = 10;
   const processors = opts.processors ?? [];
   const requestContext = opts.requestContext ?? RequestContext.fromReserved({
@@ -2178,19 +2348,6 @@ 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);
@@ -2523,6 +2680,9 @@ class ClaudeRunner {
       else
         opts.signal.addEventListener("abort", onLoopAbort, { once: true });
     }
+    const systemPromptAppend = [this.config.claudeMdContent, this.options.agentManual].filter((s) => Boolean(s && s.trim())).join(`
+
+`);
     try {
       let emittedAssistantText = false;
       for await (const message of query({
@@ -2537,9 +2697,9 @@ class ClaudeRunner {
           effort: this.config.effort,
           cwd: this.options.cwd,
           abortController: queryAbort,
-          env: { ...process.env, ...this.config.env ?? {}, ...this.options.agentId ? { AGENT_COMPOSE_AGENT_ID: this.options.agentId } : {} },
+          env: { ...process.env, ...this.config.env ?? {} },
           pathToClaudeCodeExecutable: this.config.pathToClaudeCodeExecutable ?? process.env.CLAUDE_CODE_EXECUTABLE ?? DEFAULT_CLAUDE_PATH,
-          ...this.config.claudeMdContent ? { systemPrompt: { type: "preset", preset: "claude_code", append: this.config.claudeMdContent } } : {},
+          ...systemPromptAppend ? { systemPrompt: { type: "preset", preset: "claude_code", append: systemPromptAppend } } : {},
           skills: this.config.skills ?? "all",
           resume: opts.sessionId,
           mcpServers: this.config.mcpServers,
@@ -2855,6 +3015,7 @@ function shellQuote(value) {
 }
 var ACP_FALLBACK = Symbol("acp-fallback");
 var ACP_HANDSHAKE_TIMEOUT_MS = Number(process.env.AC_ACP_HANDSHAKE_TIMEOUT_MS) || 1e4;
+var ACP_TURN_IDLE_TIMEOUT_MS = Number(process.env.AC_ACP_TURN_IDLE_TIMEOUT_MS) || 120000;
 var ACP_TRANSPORT_READY = true;
 async function withHandshakeTimeout(p, ms) {
   let timer;
@@ -3022,7 +3183,7 @@ class CliAgentRunner {
       watchdog = setTimeout(() => {
         stalled = true;
         peer.cancel();
-      }, ACP_HANDSHAKE_TIMEOUT_MS);
+      }, ACP_TURN_IDLE_TIMEOUT_MS);
     };
     try {
       armWatchdog();
@@ -3039,7 +3200,7 @@ class CliAgentRunner {
     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() };
+      yield { type: "error", text: `${this.spec.kind} prompt turn stalled (no activity for ${ACP_TURN_IDLE_TIMEOUT_MS}ms)`, timestamp: now4() };
       return;
     }
     if (!sawError)
@@ -3051,7 +3212,7 @@ class CliAgentRunner {
       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 agentEnv = { ...acp.env };
     const proc = spawnDuplex.call(this.sandbox.commands, cmd, {
       ...this.options.cwd ? { cwd: this.options.cwd } : {},
       ...Object.keys(agentEnv).length > 0 ? { envs: agentEnv } : {}
@@ -3284,6 +3445,81 @@ function createAmpRuntime(config = {}) {
   return createCliAgentRuntime(ampSpec, config.model);
 }
 var amp_default = createAmpRuntime();
+// src/runtimes/opencode.ts
+function now7() {
+  return new Date().toISOString();
+}
+var opencodeSpec = {
+  kind: "opencode",
+  authEnv: "OPENROUTER_API_KEY",
+  bin: "opencode",
+  defaultModel: "openrouter/z-ai/glm-5.2",
+  acp: { command: "opencode", args: ["acp"] },
+  install: 'sudo npm install -g opencode-ai && (command -v opencode >/dev/null 2>&1 || sudo ln -sf "$(npm prefix -g)/bin/opencode" /usr/local/bin/opencode)',
+  promptPayload: (prompt) => prompt,
+  buildCommand: ({ promptPath, model, cwd }) => `${cwd ? `cd ${shellQuote(cwd)} && ` : ""}opencode run ${model ? `--model ${shellQuote(model)} ` : ""}"$(cat ${shellQuote(promptPath)})"`,
+  extractSessionId: () => {
+    return;
+  },
+  mapEvent: (p) => {
+    const ts = now7();
+    const text = typeof p.text === "string" ? p.text : typeof p.content === "string" ? p.content : "";
+    return text ? [{ type: "text", text, timestamp: ts }] : [];
+  }
+};
+function createOpencodeRuntime(config = {}) {
+  return createCliAgentRuntime(opencodeSpec, config.model ?? opencodeSpec.defaultModel);
+}
+var opencode_default = createOpencodeRuntime();
+// src/runtimes/cursor.ts
+function now8() {
+  return new Date().toISOString();
+}
+var cursorSpec = {
+  kind: "cursor",
+  authEnv: "CURSOR_API_KEY",
+  bin: "cursor-agent",
+  defaultModel: "auto",
+  acp: { command: "cursor-agent", args: ["acp"] },
+  install: 'curl https://cursor.com/install -fsS | bash && (command -v cursor-agent >/dev/null 2>&1 || sudo ln -sf "$HOME/.local/bin/cursor-agent" /usr/local/bin/cursor-agent)',
+  promptPayload: (prompt) => prompt,
+  buildCommand: ({ promptPath, model, cwd }) => `${cwd ? `cd ${shellQuote(cwd)} && ` : ""}cursor-agent -p --force ${model ? `--model ${shellQuote(model)} ` : ""}--output-format text "$(cat ${shellQuote(promptPath)})"`,
+  extractSessionId: () => {
+    return;
+  },
+  mapEvent: (p) => {
+    const ts = now8();
+    const text = typeof p.text === "string" ? p.text : typeof p.content === "string" ? p.content : "";
+    return text ? [{ type: "text", text, timestamp: ts }] : [];
+  }
+};
+function createCursorRuntime(config = {}) {
+  return createCliAgentRuntime(cursorSpec, config.model ?? cursorSpec.defaultModel);
+}
+var cursor_default = createCursorRuntime();
+// src/runtimes/droid.ts
+function now9() {
+  return new Date().toISOString();
+}
+var droidSpec = {
+  kind: "droid",
+  authEnv: "OPENROUTER_API_KEY",
+  bin: "droid",
+  defaultModel: "custom:GLM-5.2-OR-0",
+  install: 'curl -fsSL https://app.factory.ai/cli | sh && (command -v droid >/dev/null 2>&1 || sudo ln -sf "$HOME/.local/bin/droid" /usr/local/bin/droid)',
+  promptPayload: (prompt) => prompt,
+  buildCommand: ({ promptPath, model, cwd }) => `${cwd ? `cd ${shellQuote(cwd)} && ` : ""}droid exec --auto medium ${model ? `--model ${shellQuote(model)} ` : ""}--output-format json -f ${shellQuote(promptPath)}`,
+  extractSessionId: (p) => typeof p.session_id === "string" ? p.session_id : undefined,
+  mapEvent: (p) => {
+    const ts = now9();
+    const text = p.type === "result" && typeof p.result === "string" ? p.result : typeof p.text === "string" ? p.text : typeof p.content === "string" ? p.content : "";
+    return text ? [{ type: "text", text, timestamp: ts }] : [];
+  }
+};
+function createDroidRuntime(config = {}) {
+  return createCliAgentRuntime(droidSpec, config.model ?? droidSpec.defaultModel);
+}
+var droid_default = createDroidRuntime();
 // src/sandbox.ts
 import { promises as fs2 } from "node:fs";
 import { dirname as dirname2 } from "node:path";
@@ -3376,6 +3612,9 @@ function makeSandboxProvider(sb) {
     files: {
       async write(path, content) {
         await sb.files.write(path, content);
+      },
+      async read(path) {
+        return await sb.files.read(path);
       }
     },
     async kill() {
@@ -3401,13 +3640,64 @@ function withSnapshotRetry(p) {
   const snapshot = p.snapshot.bind(p);
   return { ...p, snapshot: () => withSandboxRetry(snapshot) };
 }
+function wrapE2bBackgroundProcess(handle) {
+  return {
+    pid: handle.pid,
+    async wait() {
+      try {
+        const r = await handle.wait();
+        return { exitCode: r.exitCode ?? 0, stdout: r.stdout, stderr: r.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 : ""
+          };
+        }
+        throw e;
+      }
+    },
+    async kill() {
+      await handle.kill();
+    }
+  };
+}
 function makeE2bSandboxProvider(sb) {
+  const base = makeSandboxProvider(sb);
   return {
-    ...makeSandboxProvider(sb),
+    ...base,
+    commands: {
+      ...base.commands,
+      async runBackground(cmd, opts) {
+        const { sudo, onStdout, onStderr, ...rest } = opts ?? {};
+        const handle = await sb.commands.run(cmd, {
+          ...rest,
+          background: true,
+          ...sudo ? { user: "root" } : {},
+          ...onStdout ? { onStdout } : {},
+          ...onStderr ? { onStderr } : {}
+        });
+        return wrapE2bBackgroundProcess(handle);
+      },
+      async connectProcess(pid, opts) {
+        const handle = await sb.commands.connect(pid, {
+          ...opts?.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {},
+          ...opts?.onStdout ? { onStdout: opts.onStdout } : {},
+          ...opts?.onStderr ? { onStderr: opts.onStderr } : {}
+        });
+        return wrapE2bBackgroundProcess(handle);
+      }
+    },
     async snapshot() {
       const { snapshotId } = await sb.createSnapshot();
       return { snapshotId };
     },
+    async pauseProcess() {
+      await sb.pause();
+      return { resumeHandle: sb.sandboxId };
+    },
     async updateNetworkPolicy(policy) {
       await sb.updateNetwork(toE2bNetwork(policy));
     }
@@ -3672,6 +3962,9 @@ function makeLocalSandboxProvider() {
       async write(path, content) {
         await fs2.mkdir(dirname2(path), { recursive: true });
         await fs2.writeFile(path, content);
+      },
+      async read(path) {
+        return await fs2.readFile(path, "utf8");
       }
     },
     async kill() {}
@@ -4372,6 +4665,9 @@ function requestContextPath(stepIndex) {
 function stepResultFilePath(token) {
   return `/tmp/wf/step-result-${token}.json`;
 }
+function stepLogFilePath(token) {
+  return `/tmp/wf/step-log-${token}.log`;
+}
 // src/step-invocation/invoker.ts
 import { randomBytes as randomBytes2 } from "node:crypto";
 import { z as z11 } from "zod";
@@ -4478,28 +4774,15 @@ function parseStepResult(stdout, resultToken) {
   const message = baseMessage;
   return { ok: false, error: { kind, message } };
 }
-async function invokeStep(sandbox, request, opts) {
-  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))
-  ]);
-  const envs = {
-    ...opts?.envs ?? {},
-    ...buildStepEnvs({
-      runId: request.runId,
-      stepIndex: request.stepIndex,
-      resultToken,
-      isResume: opts?.isResume
-    })
-  };
+function makeStreamSplitters(opts, resultToken) {
   const resultSentinel = stepResultLinePrefix(resultToken);
   const pauseSentinel = stepPauseLinePrefix(resultToken);
   const isSentinel = (line) => line.startsWith(resultSentinel) || line.startsWith(pauseSentinel);
-  const makeLineSplitter = (sink, filterSentinel) => {
+  const make = (sink, filterSentinel) => {
     if (!sink)
-      return { onChunk: undefined, flush: () => {} };
+      return { onChunk: undefined, flush: () => {}, consumed: () => 0 };
     let buf = "";
+    let consumed = 0;
     return {
       onChunk: (chunk) => {
         buf += chunk;
@@ -4508,6 +4791,7 @@ async function invokeStep(sandbox, request, opts) {
 `)) !== -1) {
           const line = buf.slice(0, nl);
           buf = buf.slice(nl + 1);
+          consumed += line.length + 1;
           if (filterSentinel && isSentinel(line))
             continue;
           sink(line);
@@ -4518,35 +4802,28 @@ async function invokeStep(sandbox, request, opts) {
           return;
         const line = buf;
         buf = "";
+        consumed += line.length;
         if (filterSentinel && isSentinel(line))
           return;
         sink(line);
-      }
+      },
+      consumed: () => consumed
     };
   };
-  const stdoutSplitter = makeLineSplitter(opts?.onStdout, true);
-  const stderrSplitter = makeLineSplitter(opts?.onStderr, false);
-  let result;
-  try {
-    result = await sandbox.commands.run(RUNNER_COMMAND, {
-      envs,
-      timeoutMs: 0,
-      ...stdoutSplitter.onChunk ? { onStdout: stdoutSplitter.onChunk } : {},
-      ...stderrSplitter.onChunk ? { onStderr: stderrSplitter.onChunk } : {}
-    });
-  } catch (e) {
-    if (e instanceof SandboxUnavailableError)
-      throw e;
-    const ce = e;
-    result = {
-      stdout: ce.stdout ?? ce.result?.stdout ?? "",
-      stderr: ce.stderr ?? ce.result?.stderr ?? (e instanceof Error ? e.message : String(e)),
-      exitCode: ce.exitCode ?? ce.result?.exitCode ?? 1
-    };
-  }
-  stdoutSplitter.flush();
-  stderrSplitter.flush();
-  const parsed = parseStepResult(result.stdout, resultToken);
+  const stdout = make(opts?.onStdout, true);
+  const stderr = make(opts?.onStderr, false);
+  return {
+    ...stdout.onChunk ? { onStdout: stdout.onChunk } : {},
+    ...stderr.onChunk ? { onStderr: stderr.onChunk } : {},
+    flush: () => {
+      stdout.flush();
+      stderr.flush();
+    },
+    stdoutConsumedChars: () => stdout.consumed()
+  };
+}
+async function classifyRunnerOutcome(sandbox, output, resultToken) {
+  const parsed = parseStepResult(output.stdout, resultToken);
   if (parsed)
     return parsed;
   const fileRead = await sandbox.commands.run(`cat ${stepResultFilePath(resultToken)} 2>/dev/null || true`).catch(() => null);
@@ -4555,9 +4832,9 @@ async function invokeStep(sandbox, request, opts) {
     if (fromFile)
       return fromFile;
   }
-  if (result.exitCode !== 0) {
-    const stderrTail = result.stderr.trim().slice(-2000);
-    const stdoutTail = result.stdout.trim().slice(-2000);
+  if (output.exitCode !== 0) {
+    const stderrTail = output.stderr.trim().slice(-2000);
+    const stdoutTail = output.stdout.trim().slice(-2000);
     const details = [
       stderrTail ? `stderr:
 ${stderrTail}` : "",
@@ -4569,13 +4846,13 @@ ${stdoutTail}` : ""
       ok: false,
       error: {
         kind: "runner-exit",
-        message: `runner subprocess exited ${result.exitCode} before emitting a step result${details ? `
+        message: `runner subprocess exited ${output.exitCode} before emitting a step result${details ? `
 ${details}` : ""}`,
-        exitCode: result.exitCode
+        exitCode: output.exitCode
       }
     };
   }
-  const tail = result.stdout.trim().slice(-500);
+  const tail = output.stdout.trim().slice(-500);
   return {
     ok: false,
     error: {
@@ -4586,6 +4863,157 @@ ${tail}` : ""}`
     }
   };
 }
+async function pollDurableResult(sandbox, runnerPid, resultToken, signal) {
+  const resultFile = stepResultFilePath(resultToken);
+  const POLL_MS = 1000;
+  const DEADLINE = Date.now() + 45 * 60000;
+  const readResult = async () => {
+    const r = await sandbox.commands.run(`cat ${resultFile} 2>/dev/null || true`).catch(() => null);
+    return r?.stdout ? parseStepResult(r.stdout, resultToken) ?? null : null;
+  };
+  for (let attempt = 1;; attempt++) {
+    if (signal?.aborted) {
+      return { ok: false, error: { kind: "runner-exit", message: "reconnectStep aborted (run re-paused)", exitCode: 1 } };
+    }
+    const fromFile = await readResult();
+    if (fromFile)
+      return fromFile;
+    const probe = await sandbox.commands.run(`test -d /proc/${runnerPid} && echo alive || echo dead`).catch(() => null);
+    const dead = (probe?.stdout ?? "").includes("dead");
+    process.stderr.write(`[recover] poll ${attempt}: result-file=absent runner=${dead ? "dead" : "alive"} pid=${runnerPid}
+`);
+    if (dead) {
+      const finalRead = await readResult();
+      if (finalRead)
+        return finalRead;
+      return {
+        ok: false,
+        error: { kind: "runner-exit", message: `runner pid ${runnerPid} exited without writing a result file`, exitCode: 1 }
+      };
+    }
+    if (Date.now() > DEADLINE) {
+      return {
+        ok: false,
+        error: { kind: "runner-exit", message: `timed out after 45m waiting for runner pid ${runnerPid} to emit a result`, exitCode: 1 }
+      };
+    }
+    await new Promise((r) => setTimeout(r, POLL_MS));
+  }
+}
+async function recoverLogsAndResult(sandbox, runnerPid, resultToken, liveSplitters, opts) {
+  const result = await pollDurableResult(sandbox, runnerPid, resultToken);
+  if (sandbox.files.read && opts?.onStdout) {
+    const fullLog = await sandbox.files.read(stepLogFilePath(resultToken)).catch(() => null);
+    if (fullLog != null) {
+      const already = liveSplitters.stdoutConsumedChars();
+      const tail = fullLog.length > already ? fullLog.slice(already) : "";
+      if (tail.length > 0) {
+        const backfill = makeStreamSplitters(opts, resultToken);
+        backfill.onStdout?.(tail);
+        backfill.flush();
+      }
+    }
+  }
+  return result;
+}
+async function prepareStepLaunch(sandbox, request, opts) {
+  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))
+  ]);
+  const envs = {
+    ...opts?.envs ?? {},
+    ...buildStepEnvs({ runId: request.runId, stepIndex: request.stepIndex, resultToken, isResume: opts?.isResume })
+  };
+  return { resultToken, envs };
+}
+async function invokeStep(sandbox, request, opts) {
+  const { resultToken, envs } = await prepareStepLaunch(sandbox, request, opts);
+  const splitters = makeStreamSplitters(opts, resultToken);
+  let result;
+  try {
+    result = await sandbox.commands.run(RUNNER_COMMAND, {
+      envs: { ...envs, HOME: "/root", IS_SANDBOX: "1" },
+      sudo: true,
+      timeoutMs: 0,
+      ...splitters.onStdout ? { onStdout: splitters.onStdout } : {},
+      ...splitters.onStderr ? { onStderr: splitters.onStderr } : {}
+    });
+  } catch (e) {
+    if (e instanceof SandboxUnavailableError)
+      throw e;
+    const ce = e;
+    result = {
+      stdout: ce.stdout ?? ce.result?.stdout ?? "",
+      stderr: ce.stderr ?? ce.result?.stderr ?? (e instanceof Error ? e.message : String(e)),
+      exitCode: ce.exitCode ?? ce.result?.exitCode ?? 1
+    };
+  }
+  splitters.flush();
+  return classifyRunnerOutcome(sandbox, result, resultToken);
+}
+async function launchStep(sandbox, request, opts) {
+  if (!sandbox.commands.runBackground) {
+    throw new Error("launchStep requires a provider with background-command support (commands.runBackground)");
+  }
+  const { resultToken, envs } = await prepareStepLaunch(sandbox, request, opts);
+  const splitters = makeStreamSplitters(opts, resultToken);
+  const proc = await sandbox.commands.runBackground(`set -o pipefail; ${RUNNER_COMMAND} | tee ${stepLogFilePath(resultToken)}`, {
+    envs: { ...envs, HOME: "/root", IS_SANDBOX: "1" },
+    sudo: true,
+    timeoutMs: 0,
+    ...splitters.onStdout ? { onStdout: splitters.onStdout } : {},
+    ...splitters.onStderr ? { onStderr: splitters.onStderr } : {}
+  });
+  return {
+    runnerPid: proc.pid,
+    resultToken,
+    async wait() {
+      try {
+        const result = await proc.wait();
+        splitters.flush();
+        return classifyRunnerOutcome(sandbox, result, resultToken);
+      } catch (e) {
+        if (e instanceof SandboxUnavailableError)
+          throw e;
+        opts?.onStreamDegraded?.({ error: e, runnerPid: proc.pid, resultToken });
+        return recoverLogsAndResult(sandbox, proc.pid, resultToken, splitters, opts);
+      }
+    }
+  };
+}
+async function reconnectStep(sandbox, resume, opts) {
+  if (!sandbox.commands.connectProcess) {
+    throw new Error("reconnectStep requires a provider with background-command support (commands.connectProcess)");
+  }
+  const { runnerPid, resultToken } = resume;
+  const splitters = makeStreamSplitters(opts, resultToken);
+  const signal = opts?.signal;
+  let attached = null;
+  try {
+    attached = await sandbox.commands.connectProcess(runnerPid, {
+      ...splitters.onStdout ? { onStdout: splitters.onStdout } : {},
+      ...splitters.onStderr ? { onStderr: splitters.onStderr } : {}
+    });
+  } catch (e) {
+    if (e instanceof SandboxUnavailableError)
+      throw e;
+  }
+  return {
+    runnerPid,
+    resultToken,
+    async wait() {
+      try {
+        const result = await pollDurableResult(sandbox, runnerPid, resultToken, signal);
+        splitters.flush();
+        return result;
+      } finally {
+        await attached?.kill().catch(() => {});
+      }
+    }
+  };
+}
 // src/step-invocation/server.ts
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 function writeSentinelLine(line) {
@@ -4692,41 +5120,6 @@ 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 z12 } from "zod";
 import { randomUUID as randomUUID2 } from "node:crypto";
@@ -4782,29 +5175,36 @@ Names like \`note.created\` / \`brief.posted\` surface in the Workbench;
 
 ## Writing workflow / agent code — the SDK
 
-\`@agent-compose/sdk\` is installed in \`/workspace\` — import it from any script
-you write there:
-
-    import { defineWorkflow, agent, AgentComposeClient } from "@agent-compose/sdk";
+\`@agent-compose/sdk\` is installed in \`/workspace\`. **To author a workflow,
+ALWAYS run \`/ac:generate-workflow\`** (and \`/ac:generate-agent\` for an agent
+step) instead of writing source from memory — the skill scaffolds the correct,
+current shape. Then \`agentc register <file.ts>\` (or \`/ac:register\`).
 
-Use \`/ac:generate-workflow\` / \`/ac:generate-agent\` to scaffold, then
-\`agentc register <file.ts>\` (or \`/ac:register\`).
+The skill writes **step-form** (a builder of discrete, durable \`.step()\`s).
+Never write the legacy run-form (\`defineWorkflow({ run(ctx, sandbox) { … } })\`):
+it is one opaque step, so any failure or resume re-runs the whole body — and
+**pause does not work in run-form**.
 
-## Pausing to ask the human — \`agentc pause\`
+## Pausing to ask the human
 
-When you can't or shouldn't proceed without a human, run \`agentc pause\`, then
-**END YOUR TURN**:
+To ask a human and get an answer back, use the **\`AskUserQuestion\`** tool if
+you have it; otherwise run **\`agentc pause\`**:
 
     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.
+**Both BLOCK and hand you the answer inline.** While you wait, the run is
+suspended — your sandbox is frozen and compute stops, so a pause is free while
+the human decides. When they answer, the call RETURNS with their decision: the
+\`AskUserQuestion\` tool result, or \`agentc pause\`'s output
+(\`▶ Resumed. The human answered: …\`), carries it.
+
+**Then USE that answer to finish your work — do NOT end your turn.** This is NOT
+fire-and-forget, and the answer does NOT arrive in a later message: it comes
+back right where you called it, on the SAME turn. The shape is: ask → the call
+blocks → it returns the human's answer → you act on it and produce your result.
+Never end your turn before the call returns, never guess an answer, and never
+proceed without one.
 
 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
@@ -5053,9 +5453,10 @@ async function agent(opts) {
     });
   } : undefined;
   const mode = opts.mode ?? "auto";
+  const processors = [createAskHumanProcessor(), ...opts.processors ?? []];
   try {
     return await agentLoop({
-      runtime: (runtimeOpts) => opts.runtime.create(opts.sandbox, runtimeOpts),
+      runtime: (runtimeOpts) => opts.runtime.create(opts.sandbox, { ...runtimeOpts, agentManual: buildAgentContextDoc(process.env) }),
       agentId,
       ...opts.label !== undefined ? { label: opts.label } : {},
       ...opts.budget?.turnsPerIteration !== undefined ? { turnsPerIteration: opts.budget.turnsPerIteration } : {},
@@ -5081,7 +5482,7 @@ async function agent(opts) {
       } } : {},
       ...opts.onAgentEvent ? { onAgentEvent: opts.onAgentEvent } : {},
       ...opts.onIteration ? { onIteration: opts.onIteration } : {},
-      ...opts.processors?.length ? { processors: opts.processors } : {},
+      ...processors.length ? { processors } : {},
       requestContext: opts.requestContext ?? RequestContext.fromReserved({
         teamId: "",
         runId: "",
@@ -5093,7 +5494,6 @@ async function agent(opts) {
       ...inbox ? { inbox } : {},
       mode,
       consumeSteerPending: () => consumeSteerPending(agentId),
-      consumeLocalPauseRequest: () => consumeLocalPauseRequest(agentId),
       ...steerPause ? { pause: steerPause } : {}
     });
   } finally {
@@ -5103,7 +5503,6 @@ async function agent(opts) {
 }
 export {
   writeTool,
-  writeLocalPauseRequest,
   writeAgentContext,
   stepInputPath,
   snapshotResolves,
@@ -5113,8 +5512,10 @@ export {
   runWorkflow,
   runProcessorChain,
   requireScope,
+  requestPauseAndAwait,
   requestContextPath,
   redactPattern,
+  reconnectStep,
   reconnectSandbox,
   readTool,
   parseStepResult,
@@ -5123,10 +5524,13 @@ export {
   parseNameVersion,
   parseAgentStatus,
   parseAgentResponse,
+  opencodeSpec,
+  opencode_default as opencodeRuntime,
   makeSandboxProvider,
   makeDesktopSandboxProvider,
   listVercelRuntimeModels,
   listOwnedSandboxes,
+  launchStep,
   killSandboxById,
   killAllSandboxes,
   isWorkflow,
@@ -5141,18 +5545,26 @@ export {
   e2bMachineSpec,
   e2bBaseTemplate,
   e2bAgentEnvTemplate,
+  droidSpec,
+  droid_default as droidRuntime,
   denyTools,
   deleteSandboxSnapshot,
   defineWorkflow,
   defineStep,
   defineSandboxEnvironment,
   defineRuntime,
+  cursorSpec,
+  cursor_default as cursorRuntime,
   createVercelRuntime,
   createSandbox,
+  createOpencodeRuntime,
+  createGatePauseProcessor,
+  createDroidRuntime,
+  createCursorRuntime,
   createCodexRuntime,
   createClaudeRuntime,
+  createAskHumanProcessor,
   createAmpRuntime,
-  consumeLocalPauseRequest,
   codingTools,
   codex_default as codexRuntime,
   claude_default as claudeRuntime,
@@ -5201,6 +5613,7 @@ export {
   AgentMessageSchema,
   AgentComposeError,
   AgentComposeClient,
+  ASK_USER_QUESTION_TOOL,
   AGENT_COMPOSE_TAG,
   AGENT_COMPOSE_MANUAL,
   AC_WORKFLOW_ID,