@agent-compose/sdk 0.6.0 → 0.7.0

package/dist/agent/agent-context.d.ts

@@ -19,7 +19,7 @@ import type { SandboxProvider } from "../types/sandbox.js";
  * that credentials are network-injected (never in the env). The live
  * "Connectors & access" section is appended per-run by `buildAgentContextDoc`.
  */
-export declare const AGENT_COMPOSE_MANUAL = "# Working inside an Agent Compose sandbox\n\nYou are an agent running in a per-run sandbox on the Agent Compose platform.\nUse the **`agentc` CLI** and the **`@agent-compose/sdk`** for everything below \u2014\ndo NOT hand-roll raw HTTP/curl calls against the platform API. The CLI is on\nyour PATH and already authenticated from the environment\n(`AGENT_COMPOSE_URL` / `AGENT_COMPOSE_API_KEY` / `AGENT_COMPOSE_FACTORY` are\ninjected for this run), so commands just work \u2014 no login, no keys to manage.\n\nThe `/ac:*` skills are installed as Claude Code slash commands (`/ac:invoke`,\n`/ac:events`, `/ac:logs`, `/ac:register`, \u2026) \u2014 reach for them too.\n\n## Files \u2014 your outputs persist by default\n\nYour working directory defaults to **`$AGENT_COMPOSE_RUN_DIR`** \u2014 a per-run\ndirectory on the shared factory drive\n(`$AGENT_COMPOSE_FACTORY_DIR/<workflow>/<version>/<run-id>/`) the platform\ncreates and attributes to this run. **Files you write here persist by\ndefault** \u2014 they show up in the dashboard's Files tab and the run's Artifacts\ncard, with no API calls to save them. The dir already exists and is writable.\n\nNeed throwaway scratch \u2014 heavy build output, package caches, temp files?\n`cd /tmp` (or any path outside `/factory`): anything off the factory drive is\nephemeral and discarded when the sandbox ends. In short: **stay in your working\ndir to keep something, `cd` out to throw it away.**\n\nThe whole shared drive is POSIX-mounted at `/factory`; the dashboard-visible\nroot is `$AGENT_COMPOSE_FACTORY_DIR` (`/factory/files`). Earlier versions and\nruns live in sibling dirs under\n`$AGENT_COMPOSE_FACTORY_DIR/$AGENT_COMPOSE_WORKFLOW/` \u2014 read them for prior\ncontext. Other workflows' dirs are present but not your concern.\n\n## Events \u2014 the factory timeline\n\nRecord something on the run/factory timeline (the dashboard renders these)\nwith the CLI \u2014 your run id is `$RUN_ID`:\n\n    agentc events send \"$RUN_ID\" <name> --summary \"<one line>\" [--body '<json>']\n\nNames like `note.created` / `brief.posted` surface in the Workbench;\n`agentc events list` reads them back. `/ac:events` is the skill equivalent.\n\n## Runs\n\n    agentc list                          # registered workflows  (/ac:list)\n    agentc logs \"$RUN_ID\"                # a run's logs           (/ac:logs)\n    agentc invoke <workflow> -i '<json>' # dispatch a workflow    (/ac:invoke)\n\n## Writing workflow / agent code \u2014 the SDK\n\n`@agent-compose/sdk` is installed in `/workspace` \u2014 import it from any script\nyou write there:\n\n    import { defineWorkflow, agent, AgentComposeClient } from \"@agent-compose/sdk\";\n\nUse `/ac:generate-workflow` / `/ac:generate-agent` to scaffold, then\n`agentc register <file.ts>` (or `/ac:register`).\n\n## Pausing to ask the human \u2014 `agentc pause`\n\nWhen you can't or shouldn't proceed without a human, run `agentc pause`, then\n**END YOUR TURN**:\n\n    agentc pause --reason \"Notion returned 401 \u2014 connect Notion to continue\" \\\n                 --option retry --option skip\n\n`agentc pause` does NOT block and does NOT print the answer. It records your\nquestion and returns immediately. The moment you end your turn, the run pauses\n(your sandbox is snapshotted and compute stops while the human decides) and the\nhuman's answer is delivered to you as your **next message** \u2014 you pick up\nexactly where you left off, with the answer in hand. So: ask, end your turn,\nand wait. Do NOT keep working, do NOT call more tools, and do NOT mark the task\ncomplete after pausing.\n\nReach for it the moment you hit \u2014 or foresee \u2014 any of these:\n- **A wall only a human can clear:** a 401/403, a missing credential, an\n  unconnected provider, a host the network refuses. Do NOT retry blindly or try\n  to work around it \u2014 pause and say what needs enabling.\n- **A durable or outward-facing action that needs sign-off:** registering a\n  workflow, deploying, sending email/messages, deleting or overwriting shared\n  data, spending money. Prepare everything, then pause for approval BEFORE you\n  commit it.\n- **A judgment call only the human can settle:** an under-specified request,\n  several valid paths, a conflict with existing state, missing input only they have.\n\nYou compose the `--reason` (the ask) yourself; pass `--option` choices when\nthere are clear ones, omit them for a free-form answer. Each agent pauses\nindependently \u2014 pausing doesn't stop the others.\n\n## Credentials\n\nConnector credentials (Google, GitHub, \u2026) are NEVER in your environment.\nThey're injected at the network layer when you call an allowed host \u2014 make the\nrequest **without** an Authorization header and the platform adds it. Don't try\nto read or exfiltrate tokens; they aren't here. The \"Connectors & access\"\nsection below (when present) lists exactly which providers this run can reach.\n\n## Tools in this environment\n\n- `agentc` \u2014 Agent Compose CLI (your primary interface; authed from env)\n- `@agent-compose/sdk` \u2014 installed in /workspace for writing workflows\n- `/ac:*` Claude Code skills \u2014 slash commands for the above\n- `archil` (factory drive), `rtk`, `bun`\n- A world-writable `/workspace` working directory";
+export declare const AGENT_COMPOSE_MANUAL = "# Working inside an Agent Compose sandbox\n\nYou are an agent running in a per-run sandbox on the Agent Compose platform.\nUse the **`agentc` CLI** and the **`@agent-compose/sdk`** for everything below \u2014\ndo NOT hand-roll raw HTTP/curl calls against the platform API. The CLI is on\nyour PATH and already authenticated from the environment\n(`AGENT_COMPOSE_URL` / `AGENT_COMPOSE_API_KEY` / `AGENT_COMPOSE_FACTORY` are\ninjected for this run), so commands just work \u2014 no login, no keys to manage.\n\nThe `/ac:*` skills are installed as Claude Code slash commands (`/ac:invoke`,\n`/ac:events`, `/ac:logs`, `/ac:register`, \u2026) \u2014 reach for them too.\n\n## Files \u2014 your outputs persist by default\n\nYour working directory defaults to **`$AGENT_COMPOSE_RUN_DIR`** \u2014 a per-run\ndirectory on the shared factory drive\n(`$AGENT_COMPOSE_FACTORY_DIR/<workflow>/<version>/<run-id>/`) the platform\ncreates and attributes to this run. **Files you write here persist by\ndefault** \u2014 they show up in the dashboard's Files tab and the run's Artifacts\ncard, with no API calls to save them. The dir already exists and is writable.\n\nNeed throwaway scratch \u2014 heavy build output, package caches, temp files?\n`cd /tmp` (or any path outside `/factory`): anything off the factory drive is\nephemeral and discarded when the sandbox ends. In short: **stay in your working\ndir to keep something, `cd` out to throw it away.**\n\nThe whole shared drive is POSIX-mounted at `/factory`; the dashboard-visible\nroot is `$AGENT_COMPOSE_FACTORY_DIR` (`/factory/files`). Earlier versions and\nruns live in sibling dirs under\n`$AGENT_COMPOSE_FACTORY_DIR/$AGENT_COMPOSE_WORKFLOW/` \u2014 read them for prior\ncontext. Other workflows' dirs are present but not your concern.\n\n## Events \u2014 the factory timeline\n\nRecord something on the run/factory timeline (the dashboard renders these)\nwith the CLI \u2014 your run id is `$RUN_ID`:\n\n    agentc events send \"$RUN_ID\" <name> --summary \"<one line>\" [--body '<json>']\n\nNames like `note.created` / `brief.posted` surface in the Workbench;\n`agentc events list` reads them back. `/ac:events` is the skill equivalent.\n\n## Runs\n\n    agentc list                          # registered workflows  (/ac:list)\n    agentc logs \"$RUN_ID\"                # a run's logs           (/ac:logs)\n    agentc invoke <workflow> -i '<json>' # dispatch a workflow    (/ac:invoke)\n\n## Writing workflow / agent code \u2014 the SDK\n\n`@agent-compose/sdk` is installed in `/workspace`. **To author a workflow,\nALWAYS run `/ac:generate-workflow`** (and `/ac:generate-agent` for an agent\nstep) instead of writing source from memory \u2014 the skill scaffolds the correct,\ncurrent shape. Then `agentc register <file.ts>` (or `/ac:register`).\n\nThe skill writes **step-form** (a builder of discrete, durable `.step()`s).\nNever write the legacy run-form (`defineWorkflow({ run(ctx, sandbox) { \u2026 } })`):\nit is one opaque step, so any failure or resume re-runs the whole body \u2014 and\n**pause does not work in run-form**.\n\n## Pausing to ask the human\n\nTo ask a human and get an answer back, use the **`AskUserQuestion`** tool if\nyou have it; otherwise run **`agentc pause`**:\n\n    agentc pause --reason \"Notion returned 401 \u2014 connect Notion to continue\" \\\n                 --option retry --option skip\n\n**Both BLOCK and hand you the answer inline.** While you wait, the run is\nsuspended \u2014 your sandbox is frozen and compute stops, so a pause is free while\nthe human decides. When they answer, the call RETURNS with their decision: the\n`AskUserQuestion` tool result, or `agentc pause`'s output\n(`\u25B6 Resumed. The human answered: \u2026`), carries it.\n\n**Then USE that answer to finish your work \u2014 do NOT end your turn.** This is NOT\nfire-and-forget, and the answer does NOT arrive in a later message: it comes\nback right where you called it, on the SAME turn. The shape is: ask \u2192 the call\nblocks \u2192 it returns the human's answer \u2192 you act on it and produce your result.\nNever end your turn before the call returns, never guess an answer, and never\nproceed without one.\n\nReach for it the moment you hit \u2014 or foresee \u2014 any of these:\n- **A wall only a human can clear:** a 401/403, a missing credential, an\n  unconnected provider, a host the network refuses. Do NOT retry blindly or try\n  to work around it \u2014 pause and say what needs enabling.\n- **A durable or outward-facing action that needs sign-off:** registering a\n  workflow, deploying, sending email/messages, deleting or overwriting shared\n  data, spending money. Prepare everything, then pause for approval BEFORE you\n  commit it.\n- **A judgment call only the human can settle:** an under-specified request,\n  several valid paths, a conflict with existing state, missing input only they have.\n\nYou compose the `--reason` (the ask) yourself; pass `--option` choices when\nthere are clear ones, omit them for a free-form answer. Each agent pauses\nindependently \u2014 pausing doesn't stop the others.\n\n## Credentials\n\nConnector credentials (Google, GitHub, \u2026) are NEVER in your environment.\nThey're injected at the network layer when you call an allowed host \u2014 make the\nrequest **without** an Authorization header and the platform adds it. Don't try\nto read or exfiltrate tokens; they aren't here. The \"Connectors & access\"\nsection below (when present) lists exactly which providers this run can reach.\n\n## Tools in this environment\n\n- `agentc` \u2014 Agent Compose CLI (your primary interface; authed from env)\n- `@agent-compose/sdk` \u2014 installed in /workspace for writing workflows\n- `/ac:*` Claude Code skills \u2014 slash commands for the above\n- `archil` (factory drive), `rtk`, `bun`\n- A world-writable `/workspace` working directory";
 /**
  * One connector this run can reach, as the agent should see it. Strictly
  * NON-SECRET — hosts, methods, paths, identity only. The access token is

package/dist/index.d.ts

@@ -23,7 +23,7 @@ export type { WorkflowPlan, WorkflowStepPlan } from "./types/workflow-plan.js";
 export type { BaseExecutionContext, InvokeChild } from "./types/execution-context.js";
 export { RequestContext, ReservedKeyError, NonSerialisableValueError, AC_RESERVED_PREFIX, AC_TEAM_ID, AC_RUN_ID, AC_WORKFLOW_ID, AC_FACTORY_ID, AC_API_KEY_SCOPES, AC_PARENT_RUN_ID, AC_ABORT_SIGNAL, } from "./request-context/index.js";
 export type { RequestContextReserved, RequestContextWire, } from "./request-context/index.js";
-export { Verdict, runProcessorChain, denyTools, humanApproval, requireScope, redactPattern, createGatePauseProcessor, } from "./processors/index.js";
+export { Verdict, runProcessorChain, denyTools, humanApproval, requireScope, redactPattern, createGatePauseProcessor, createAskHumanProcessor, ASK_USER_QUESTION_TOOL, } from "./processors/index.js";
 export type { Processor, ProcessorContext, ProcessorVerdict, ToolCall, GatePausePolicy, GatePauseApproval, GatePauseConnection, } from "./processors/index.js";
 export type { AgentMessage, AgentMessageInit, AgentMessageText, AgentMessageThinking, AgentMessageToolUse, AgentMessageToolResult, AgentMessageDone, AgentMessageError, AgentMessageUsage, AgentStatus, } from "./types/protocol.js";
 export type { SandboxProvider, DesktopSandboxProvider, } from "./types/sandbox.js";
@@ -47,6 +47,15 @@ export { default as codexRuntime } from "./runtimes/codex.js";
 export { createAmpRuntime } from "./runtimes/amp.js";
 export type { AmpRuntimeConfig } from "./runtimes/amp.js";
 export { default as ampRuntime } from "./runtimes/amp.js";
+export { createOpencodeRuntime, opencodeSpec } from "./runtimes/opencode.js";
+export type { OpencodeRuntimeConfig } from "./runtimes/opencode.js";
+export { default as opencodeRuntime } from "./runtimes/opencode.js";
+export { createCursorRuntime, cursorSpec } from "./runtimes/cursor.js";
+export type { CursorRuntimeConfig } from "./runtimes/cursor.js";
+export { default as cursorRuntime } from "./runtimes/cursor.js";
+export { createDroidRuntime, droidSpec } from "./runtimes/droid.js";
+export type { DroidRuntimeConfig } from "./runtimes/droid.js";
+export { default as droidRuntime } from "./runtimes/droid.js";
 export { bashTool, codingTools, editTool, readTool, writeTool } from "./tools/index.js";
 export type { CodingTool } from "./tools/index.js";
 export type { RunEvent } from "./types/events.js";

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
@@ -1195,6 +1205,74 @@ function createGatePauseProcessor(opts) {
     }
   };
 }
+// 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";
 
@@ -2075,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({
@@ -2937,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;
@@ -3104,7 +3183,7 @@ class CliAgentRunner {
       watchdog = setTimeout(() => {
         stalled = true;
         peer.cancel();
-      }, ACP_HANDSHAKE_TIMEOUT_MS);
+      }, ACP_TURN_IDLE_TIMEOUT_MS);
     };
     try {
       armWatchdog();
@@ -3121,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)
@@ -3366,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";
@@ -3458,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() {
@@ -3805,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() {}
@@ -4505,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";
@@ -4617,8 +4780,9 @@ function makeStreamSplitters(opts, resultToken) {
   const isSentinel = (line) => line.startsWith(resultSentinel) || line.startsWith(pauseSentinel);
   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;
@@ -4627,6 +4791,7 @@ function makeStreamSplitters(opts, resultToken) {
 `)) !== -1) {
           const line = buf.slice(0, nl);
           buf = buf.slice(nl + 1);
+          consumed += line.length + 1;
           if (filterSentinel && isSentinel(line))
             continue;
           sink(line);
@@ -4637,10 +4802,12 @@ function makeStreamSplitters(opts, resultToken) {
           return;
         const line = buf;
         buf = "";
+        consumed += line.length;
         if (filterSentinel && isSentinel(line))
           return;
         sink(line);
-      }
+      },
+      consumed: () => consumed
     };
   };
   const stdout = make(opts?.onStdout, true);
@@ -4651,7 +4818,8 @@ function makeStreamSplitters(opts, resultToken) {
     flush: () => {
       stdout.flush();
       stderr.flush();
-    }
+    },
+    stdoutConsumedChars: () => stdout.consumed()
   };
 }
 async function classifyRunnerOutcome(sandbox, output, resultToken) {
@@ -4695,6 +4863,59 @@ ${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([
@@ -4713,7 +4934,8 @@ async function invokeStep(sandbox, request, opts) {
   let result;
   try {
     result = await sandbox.commands.run(RUNNER_COMMAND, {
-      envs,
+      envs: { ...envs, HOME: "/root", IS_SANDBOX: "1" },
+      sudo: true,
       timeoutMs: 0,
       ...splitters.onStdout ? { onStdout: splitters.onStdout } : {},
       ...splitters.onStderr ? { onStderr: splitters.onStderr } : {}
@@ -4737,8 +4959,9 @@ async function launchStep(sandbox, request, opts) {
   }
   const { resultToken, envs } = await prepareStepLaunch(sandbox, request, opts);
   const splitters = makeStreamSplitters(opts, resultToken);
-  const proc = await sandbox.commands.runBackground(RUNNER_COMMAND, {
-    envs,
+  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 } : {}
@@ -4747,9 +4970,16 @@ async function launchStep(sandbox, request, opts) {
     runnerPid: proc.pid,
     resultToken,
     async wait() {
-      const result = await proc.wait();
-      splitters.flush();
-      return classifyRunnerOutcome(sandbox, result, resultToken);
+      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);
+      }
     }
   };
 }
@@ -4759,9 +4989,10 @@ async function reconnectStep(sandbox, resume, opts) {
   }
   const { runnerPid, resultToken } = resume;
   const splitters = makeStreamSplitters(opts, resultToken);
-  let proc = null;
+  const signal = opts?.signal;
+  let attached = null;
   try {
-    proc = await sandbox.commands.connectProcess(runnerPid, {
+    attached = await sandbox.commands.connectProcess(runnerPid, {
       ...splitters.onStdout ? { onStdout: splitters.onStdout } : {},
       ...splitters.onStderr ? { onStderr: splitters.onStderr } : {}
     });
@@ -4769,22 +5000,17 @@ async function reconnectStep(sandbox, resume, opts) {
     if (e instanceof SandboxUnavailableError)
       throw e;
   }
-  const attached = proc;
   return {
     runnerPid,
     resultToken,
     async wait() {
-      let output = { stdout: "", stderr: "", exitCode: 0 };
-      if (attached) {
-        try {
-          output = await attached.wait();
-        } catch (e) {
-          if (e instanceof SandboxUnavailableError)
-            throw e;
-        }
+      try {
+        const result = await pollDurableResult(sandbox, runnerPid, resultToken, signal);
+        splitters.flush();
+        return result;
+      } finally {
+        await attached?.kill().catch(() => {});
       }
-      splitters.flush();
-      return classifyRunnerOutcome(sandbox, output, resultToken);
     }
   };
 }
@@ -4949,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:
+\`@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\`).
 
-    import { defineWorkflow, agent, AgentComposeClient } from "@agent-compose/sdk";
+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**.
 
-Use \`/ac:generate-workflow\` / \`/ac:generate-agent\` to scaffold, then
-\`agentc register <file.ts>\` (or \`/ac:register\`).
+## Pausing to ask the human
 
-## Pausing to ask the human — \`agentc pause\`
-
-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
@@ -5220,6 +5453,7 @@ 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, agentManual: buildAgentContextDoc(process.env) }),
@@ -5248,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: "",
@@ -5290,6 +5524,8 @@ export {
   parseNameVersion,
   parseAgentStatus,
   parseAgentResponse,
+  opencodeSpec,
+  opencode_default as opencodeRuntime,
   makeSandboxProvider,
   makeDesktopSandboxProvider,
   listVercelRuntimeModels,
@@ -5309,17 +5545,25 @@ 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,
   codingTools,
   codex_default as codexRuntime,
@@ -5369,6 +5613,7 @@ export {
   AgentMessageSchema,
   AgentComposeError,
   AgentComposeClient,
+  ASK_USER_QUESTION_TOOL,
   AGENT_COMPOSE_TAG,
   AGENT_COMPOSE_MANUAL,
   AC_WORKFLOW_ID,

package/dist/processors/ask-human.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Ask-human processor (ADR-0028).
+ *
+ * Makes "ask a human" a FIRST-CLASS agent affordance: when the agent calls the
+ * built-in `AskUserQuestion` tool, this short-circuits it into a SERVER pause
+ * (`requestPauseAndAwait`) — the run freezes (compute stops), the question +
+ * options land on the human's pause feed, and the human's answer comes back as
+ * the tool result. No `agentc pause` CLI for the model to remember, and no
+ * dependency on prompt discipline: the moment the agent asks, the run pauses.
+ *
+ * Loud by construction — the danger this fixes is a pause that SILENTLY doesn't
+ * happen (a stale in-sandbox CLI, a non-E2B substrate, an auth error) letting
+ * the agent proceed as if it had an answer:
+ *   - pause cannot be created (server reject) → `Verdict.abort` ENDS the agent
+ *     loop with a WorkflowError. The run fails loud; it never guesses an answer.
+ *   - pause expires / is cancelled → the tool result says NO answer came and to
+ *     not assume one.
+ *
+ * Lives in the shared `gateToolCall` chain, so one implementation covers every
+ * runtime (the Claude Agent SDK `PreToolUse` hook and the ACP permission path).
+ * No run credential in the env (local / non-sandbox) → no-op: `AskUserQuestion`
+ * passes through untouched so a dev invocation isn't hard-failed.
+ */
+import type { Processor } from "./processor.js";
+import type { GatePauseConnection } from "./gate-pause.js";
+/** The Claude built-in tool an agent uses to ask the user a question. */
+export declare const ASK_USER_QUESTION_TOOL = "AskUserQuestion";
+export declare function createAskHumanProcessor(opts?: {
+    connection?: GatePauseConnection;
+}): Processor;

package/dist/processors/ask-human.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/processors/index.d.ts

@@ -4,3 +4,4 @@ export { runProcessorChain } from "./runner.js";
 export { denyTools, humanApproval, requireScope, redactPattern, } from "./builtins.js";
 export { createGatePauseProcessor } from "./gate-pause.js";
 export type { GatePausePolicy, GatePauseApproval, GatePauseConnection } from "./gate-pause.js";
+export { createAskHumanProcessor, ASK_USER_QUESTION_TOOL } from "./ask-human.js";

package/dist/runtimes/_cli-agent.d.ts

@@ -34,6 +34,15 @@ export declare function shellQuote(value: string): string;
  *  route to JSONL exactly like a handshake error. Overridable via the env for
  *  ops tuning; defaults sane. */
 export declare const ACP_HANDSHAKE_TIMEOUT_MS: number;
+/** Idle deadline for a PROMPT TURN (distinct from the handshake gate above). A
+ *  turn is killed only if it goes fully SILENT for this long — the deadline is
+ *  re-armed on every streamed message, so a long, *streaming* turn never trips
+ *  it. This must be generous: a reasoning model (GLM, gpt-5-codex) can think for
+ *  tens of seconds between tool calls with no wire activity, which is NOT a hang.
+ *  The 10s handshake timeout was far too tight here and killed live GLM turns
+ *  mid-report. Only a genuinely wedged CLI (the Gemini-style hang) should trip
+ *  this. Overridable via the env for ops tuning. */
+export declare const ACP_TURN_IDLE_TIMEOUT_MS: number;
 /** Readiness gate for the LIVE ACP attempt. The duplex-stdin transport in
  *  `spawnAcpProcess` is now real (`commands.spawnDuplex` on the local provider),
  *  so the agent's `initialize` request bytes are delivered and the handshake can