@agent-compose/sdk 0.5.9 → 0.7.0

package/src/processors/ask-human.ts

@@ -0,0 +1,136 @@
+/**
+ * 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, ProcessorContext, ToolCall } from "./processor.js";
+import { Verdict } from "./processor.js";
+import { requestPauseAndAwait } from "../agent/pause-client.js";
+import type { GatePauseConnection } from "./gate-pause.js";
+
+/** The Claude built-in tool an agent uses to ask the user a question. */
+export const ASK_USER_QUESTION_TOOL = "AskUserQuestion";
+
+/** One question in an `AskUserQuestion` call (only the fields we read). */
+interface AskQuestion { question?: unknown; header?: unknown; options?: unknown }
+
+/** Pull the human-facing question + its option labels out of an
+ *  `AskUserQuestion` tool input. We pause on the FIRST question (the common
+ *  case); any others are folded into the reason so nothing is lost. */
+function parseAsk(input: Record<string, unknown>): { reason: string; options: Array<{ id: string; label: string }> } {
+  const questions = Array.isArray(input.questions) ? (input.questions as AskQuestion[]) : [];
+  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 as Array<{ label?: unknown }>)
+        .map((o) => String(o?.label ?? "").trim())
+        .filter(Boolean)
+        .map((label) => ({ id: label, label }))
+    : [];
+  return { reason: head + extra, options };
+}
+
+/** Unwrap the dashboard's `{ decision }` resume payload to the raw answer text. */
+function answerText(decision: unknown): string {
+  const raw = decision !== null && typeof decision === "object" && "decision" in decision
+    ? (decision as { decision: unknown }).decision
+    : decision;
+  return typeof raw === "string" ? raw.trim() : raw == null ? "" : JSON.stringify(raw);
+}
+
+/** Recognise the agent shelling out to `agentc pause` and extract the same
+ *  {reason, options} we'd get from AskUserQuestion. We INTERCEPT it here — in the
+ *  tool gate, BEFORE the command runs — so the pause takes the DESIGNED path (the
+ *  answer returns as the tool result and the agent loop continues) instead of the
+ *  command actually blocking inside the sandbox shell, which froze the runner
+ *  mid-tool-exec and never resumed the loop. */
+function parseAgentcPause(command: string): { reason: string; options: Array<{ id: string; label: string }> } | null {
+  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 };
+}
+
+/** Pull the ask (reason + options) from either the `AskUserQuestion` tool OR a
+ *  `Bash` call running `agentc pause`. Null for anything else. */
+function extractAsk(call: ToolCall): { reason: string; options: Array<{ id: string; label: string }> } | null {
+  if (call.toolName === ASK_USER_QUESTION_TOOL) return parseAsk(call.toolInput);
+  if (call.toolName === "Bash") {
+    const cmd = (call.toolInput as { command?: unknown })?.command;
+    return typeof cmd === "string" ? parseAgentcPause(cmd) : null;
+  }
+  return null;
+}
+
+export function createAskHumanProcessor(opts: { connection?: GatePauseConnection } = {}): Processor {
+  return {
+    name: "ask-human",
+    async processToolCall(call: ToolCall, ctx: ProcessorContext) {
+      // Fires for AskUserQuestion OR a `Bash` call running `agentc pause` — both
+      // ask a human and must take the SAME processor path so the answer returns
+      // as the tool result and the agent loop continues.
+      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 ?? "",
+      };
+      // No run credential (local / non-sandbox) — can't pause; let the tool
+      // through rather than hard-failing a dev invocation.
+      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) {
+        // The pause could NOT be honored (server reject, non-E2B substrate, auth).
+        // Abort the loop — never let the agent proceed as if it had an answer.
+        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 = answerText(decision.decision);
+        return Verdict.deny(`The human answered: ${answer || "(no text returned)"}. Continue using this answer.`);
+      }
+      // Expired / cancelled — no answer. Do NOT let the agent assume one.
+      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.`);
+    },
+  };
+}

package/src/processors/gate-pause.ts

@@ -0,0 +1,94 @@
+/**
+ * Gate-pause processor (ADR-0028).
+ *
+ * A pre-tool gate that, when its `policy` flags a tool call as needing human
+ * approval, pauses the run as a SERVER operation (`requestPauseAndAwait`) and
+ * blocks until a human answers — then allows or denies the tool.
+ *
+ * It pauses through the server pause API (`requestPauseAndAwait`), so the pause
+ * is a server operation no `try/catch` can swallow. It does NOT use today's
+ * `ctx.pause`, which still throws `PauseSignal` — exactly the swallowable path
+ * ADR-0028 supersedes for agents. (Routing `ctx.pause` itself through this same
+ * server pause is the natural unification — ADR-0028 open question — at which
+ * point "the pause API" and "ctx.pause" become one thing.) Because it lives in
+ * the shared `gateToolCall` chain, one implementation covers every runtime — the
+ * Claude Agent SDK `PreToolUse` hook and the ACP `session/request_permission`
+ * path both route through it.
+ *
+ * Opt-in: the workflow/agent supplies the `policy` (which may be a heuristic or
+ * an async classifier agent). The connection defaults to the run credential in
+ * the sandbox env; absent it (local / non-sandbox), the gate is a no-op and
+ * tool calls pass through untouched.
+ */
+
+import type { Processor, ProcessorContext, ToolCall } from "./processor.js";
+import { Verdict } from "./processor.js";
+import { requestPauseAndAwait } from "../agent/pause-client.js";
+
+export interface GatePauseApproval {
+  /** Human-readable question shown on the approval UI. */
+  reason:   string;
+  /** Decision options the human picks from. Defaults to Approve / Deny. */
+  options?: Array<{ id: string; label: string }>;
+}
+
+/** Decide whether a tool call needs human approval. Return `false` to let it
+ *  through untouched, or an approval request to pause the run until a human
+ *  answers. May be async (e.g. a small classifier agent). */
+export type GatePausePolicy = (
+  call: ToolCall,
+  ctx:  ProcessorContext,
+) => (false | GatePauseApproval) | Promise<false | GatePauseApproval>;
+
+export interface GatePauseConnection { baseUrl: string; token: string; runId: string }
+
+const DENY_ANSWERS = new Set(["deny", "no", "reject", "decline", "block"]);
+
+/** Unwrap the dashboard's `{ decision }` resume payload to the raw answer text. */
+function answerText(decision: unknown): string {
+  const raw = decision !== null && typeof decision === "object" && "decision" in decision
+    ? (decision as { decision: unknown }).decision
+    : decision;
+  return typeof raw === "string" ? raw.trim() : raw == null ? "" : JSON.stringify(raw);
+}
+
+export function createGatePauseProcessor(opts: {
+  policy:      GatePausePolicy;
+  /** Override the server connection (defaults to the sandbox run-credential env). */
+  connection?: GatePauseConnection;
+}): Processor {
+  return {
+    name: "gate-pause",
+    async processToolCall(call: ToolCall, ctx: ProcessorContext) {
+      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 ?? "",
+      };
+      // No run credential (local / non-sandbox) — can't pause; let it through
+      // rather than hard-failing a dev invocation.
+      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);
+      // Approve unless the human explicitly denied (or no answer came back on
+      // expiry/cancel). A free-form answer that isn't a deny word lets the tool
+      // run, with the human's guidance available to the model on the next turn.
+      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.`);
+    },
+  };
+}

package/src/processors/index.ts

@@ -14,3 +14,14 @@ export {
   requireScope,
   redactPattern,
 } from "./builtins.js";
+
+// ADR-0028 — server-driven human-approval gate. Pauses the run through the
+// server pause API and blocks until a human answers; covers every runtime
+// through the shared gateToolCall chain.
+export { createGatePauseProcessor } from "./gate-pause.js";
+export type { GatePausePolicy, GatePauseApproval, GatePauseConnection } from "./gate-pause.js";
+
+// ADR-0028 — first-class "ask a human": maps the agent's `AskUserQuestion` tool
+// to a server pause and returns the human's answer as the tool result. Added by
+// default to every agent (no-op unless the tool is granted + called).
+export { createAskHumanProcessor, ASK_USER_QUESTION_TOOL } from "./ask-human.js";

package/src/runtimes/_cli-agent.ts

@@ -56,6 +56,16 @@ const ACP_FALLBACK = Symbol("acp-fallback");
  *  ops tuning; defaults sane. */
 export const ACP_HANDSHAKE_TIMEOUT_MS = Number(process.env.AC_ACP_HANDSHAKE_TIMEOUT_MS) || 10_000;
 
+/** 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 const ACP_TURN_IDLE_TIMEOUT_MS = Number(process.env.AC_ACP_TURN_IDLE_TIMEOUT_MS) || 120_000;
+
 /** 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
@@ -448,7 +458,7 @@ export class CliAgentRunner implements ModelExecutionContract {
     let watchdog: ReturnType<typeof setTimeout> | undefined;
     const armWatchdog = () => {
       if (watchdog) clearTimeout(watchdog);
-      watchdog = setTimeout(() => { stalled = true; peer.cancel(); }, ACP_HANDSHAKE_TIMEOUT_MS);
+      watchdog = setTimeout(() => { stalled = true; peer.cancel(); }, ACP_TURN_IDLE_TIMEOUT_MS);
     };
     try {
       armWatchdog();
@@ -466,7 +476,7 @@ export class CliAgentRunner implements ModelExecutionContract {
       // and surface the stall as an error.
       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: now() };
+      yield { type: "error", text: `${this.spec.kind} prompt turn stalled (no activity for ${ACP_TURN_IDLE_TIMEOUT_MS}ms)`, timestamp: now() };
       return;
     }
 
@@ -502,9 +512,7 @@ export class CliAgentRunner implements ModelExecutionContract {
     }
 
     const cmd = `${acp.command} ${acp.args.map(shellQuote).join(" ")}`.trim();
-    // Expose this agent's id to the adapter (and the tool subprocesses it
-    // spawns) so `agentc pause` scopes its state-dir marker to this agent.
-    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 } : {}),

package/src/runtimes/claude.ts

@@ -265,6 +265,14 @@ export class ClaudeRunner implements ModelExecutionContract {
       else opts.signal.addEventListener("abort", onLoopAbort, { once: true });
     }
 
+    // System-prompt append: the platform manual (agentManual, threaded from
+    // agent()) + any caller-supplied claudeMdContent. The Agent SDK does NOT
+    // auto-load CLAUDE.md from cwd (no settingSources), so without this the
+    // agent never reliably sees the manual — including how to pause.
+    const systemPromptAppend = [this.config.claudeMdContent, this.options.agentManual]
+      .filter((s): s is string => Boolean(s && s.trim()))
+      .join("\n\n");
+
     try {
       let emittedAssistantText = false;
       for await (const message of query({
@@ -279,15 +287,11 @@ export class ClaudeRunner implements ModelExecutionContract {
           effort: this.config.effort,
           cwd: this.options.cwd,
           abortController: queryAbort,
-          // Expose this agent's id to its tool subprocesses so `agentc pause`
-          // can scope its state-dir pause-request marker to the right agent
-          // (concurrent agent() calls share one sandbox). The loop's agentId is
-          // authoritative, so it wins over a stale env / config value.
-          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" as const, preset: "claude_code" as const, append: this.config.claudeMdContent } } : {}),
+          ...(systemPromptAppend ? { systemPrompt: { type: "preset" as const, preset: "claude_code" as const, append: systemPromptAppend } } : {}),
           // Turn skills ON (and auto-add the `Skill` tool). The agent-env
           // bakes the `/ac:*` skills; without this the Agent SDK leaves
           // them un-enabled and the agent can't invoke them.

package/src/runtimes/cursor.ts

@@ -0,0 +1,59 @@
+/**
+ * Cursor CLI runtime — drives Cursor's `cursor-agent` inside the sandbox.
+ *
+ * ACP-native: `cursor-agent acp` is a protocolVersion-1 ACP server (verified
+ * live on E2B 2026-06-30), so the runner delegates the wire protocol to
+ * AcpClientPeer; the JSONL members below are the version-mismatch fallback.
+ *
+ * Auth: CURSOR_API_KEY — Cursor's OWN platform key, NOT OpenRouter. In ACP mode
+ * `cursor-agent acp` takes no model flag, so it runs the account's default model;
+ * the `--model` ids (auto, gpt-5.3-codex, composer-2.5,
+ * claude-opus-4-8-thinking-high; full list via `cursor-agent --list-models`)
+ * only apply to the JSONL `-p` fallback. cursor brings HARNESS diversity (a
+ * different agent scaffold) to a cross-functional / review panel.
+ *
+ * Verified live on E2B (2026-06-30): `curl https://cursor.com/install` →
+ * ~/.local/bin/cursor-agent (v2026.06.29); `cursor-agent acp` answered the ACP
+ * `initialize` with protocolVersion 1; CURSOR_API_KEY authenticated.
+ */
+import type { AgentMessage } from "../index.js";
+import { createCliAgentRuntime, shellQuote, type CliAgentSpec } from "./_cli-agent.js";
+
+function now(): string { return new Date().toISOString(); }
+
+export const cursorSpec: CliAgentSpec = {
+  kind: "cursor",
+  authEnv: "CURSOR_API_KEY",
+  bin: "cursor-agent",
+  // ACP runs the account default; "auto" is Cursor's own auto-routing label.
+  defaultModel: "auto",
+  // `cursor-agent acp` is a protocolVersion-1 ACP server — the runner delegates
+  // the whole wire protocol to AcpClientPeer. It takes no model flag, so the
+  // session runs Cursor's account-default model.
+  acp: { command: "cursor-agent", args: ["acp"] },
+  // Self-install on first use; symlink onto PATH for a non-login `sh -c`.
+  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)',
+  // ── JSONL fallback (only if the ACP handshake negotiates a non-1 version;
+  //    cursor is v1, so vestigial). `-p` needs `--force` to clear the
+  //    workspace-trust gate non-interactively.
+  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: () => undefined,
+  mapEvent: (p): AgentMessage[] => {
+    const ts = now();
+    const text = typeof p.text === "string" ? p.text : typeof p.content === "string" ? p.content : "";
+    return text ? [{ type: "text", text, timestamp: ts }] : [];
+  },
+};
+
+export interface CursorRuntimeConfig {
+  /** Cursor model id; ACP mode ignores it (account default) — applies to the `-p` fallback. */
+  model?: string;
+}
+
+export function createCursorRuntime(config: CursorRuntimeConfig = {}) {
+  return createCliAgentRuntime(cursorSpec, config.model ?? cursorSpec.defaultModel);
+}
+
+export default createCursorRuntime();

package/src/runtimes/droid.ts

@@ -0,0 +1,63 @@
+/**
+ * Factory `droid` runtime — drives `droid exec` headless inside the sandbox,
+ * JSONL via `--output-format json`.
+ *
+ * Driven PURELY via OpenRouter BYOK — NO Factory login (verified live on E2B
+ * 2026-06-30): a `~/.factory/settings.json` `customModels` entry points at
+ * OpenRouter, and the model id is `custom:<displayName>-<index>`. The workflow
+ * provisions settings.json (see the dynamic-task route step); this spec just
+ * builds the exec command. Auth env is OPENROUTER_API_KEY (the BYOK inference
+ * key shared with codex + opencode).
+ *
+ * NOT ACP: `droid exec` is JSONL. (Its stream-jsonrpc mode ignores --model and
+ * sets model/autonomy via JSON-RPC; the plain `--output-format json` mode honours
+ * --model, which is what we use.) So it always drives the JSONL path. droid adds
+ * Factory's agent HARNESS to a cross-functional / review panel.
+ *
+ * Verified live on E2B (2026-06-30): install via app.factory.ai/cli;
+ * `droid exec --auto low --model custom:GLM-5.2-OR-0 --output-format json`
+ * returned `{"type":"result","result":"…","session_id":"…","usage":{…}}` driven
+ * through OpenRouter with no Factory account.
+ */
+import type { AgentMessage } from "../index.js";
+import { createCliAgentRuntime, shellQuote, type CliAgentSpec } from "./_cli-agent.js";
+
+function now(): string { return new Date().toISOString(); }
+
+export const droidSpec: CliAgentSpec = {
+  kind: "droid",
+  // OpenRouter is the inference gateway (BYOK custom model). No FACTORY_API_KEY.
+  authEnv: "OPENROUTER_API_KEY",
+  bin: "droid",
+  // Matches the first customModels entry the workflow writes to settings.json.
+  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)',
+  // ── JSONL path (always — droid exec is not ACP). `--auto medium` lets the
+  //    agent create/edit files + run commands; `-f` reads the prompt from a file.
+  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): AgentMessage[] => {
+    const ts = now();
+    // `--output-format json` emits a single terminal result object.
+    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 }] : [];
+  },
+  // No `acp` → JSONL-only spec.
+};
+
+export interface DroidRuntimeConfig {
+  /** `custom:<displayName>-<index>` matching the provisioned settings.json. */
+  model?: string;
+}
+
+export function createDroidRuntime(config: DroidRuntimeConfig = {}) {
+  return createCliAgentRuntime(droidSpec, config.model ?? droidSpec.defaultModel);
+}
+
+export default createDroidRuntime();

package/src/runtimes/opencode.ts

@@ -0,0 +1,61 @@
+/**
+ * OpenCode CLI runtime — drives sst's `opencode` agentic CLI inside the sandbox.
+ * OpenCode speaks ACP natively (`opencode acp`, protocolVersion 1 — verified
+ * live on E2B), so the runner drives it over ACP; the JSONL members below are
+ * only the version-mismatch fallback (vestigial for a v1 agent).
+ *
+ * Auth + model via OpenRouter: set OPENROUTER_API_KEY (a factory/workflow
+ * secret) and use a model id like `openrouter/z-ai/glm-5.2`. The runtime
+ * installs the `opencode-ai` CLI on demand; pair with
+ * `snapshots: { bootFrom: "reuse" }` to install once and boot from the capture.
+ *
+ * Verified live on E2B (2026-06-30): `npm i -g opencode-ai` (v1.17.12);
+ * `opencode run --model openrouter/z-ai/glm-5.2` drove a GLM-5.2 turn through
+ * OpenRouter; `opencode acp` answered the ACP `initialize` handshake with
+ * protocolVersion 1.
+ */
+
+import type { AgentMessage } from "../index.js";
+import { createCliAgentRuntime, shellQuote, type CliAgentSpec } from "./_cli-agent.js";
+
+function now(): string { return new Date().toISOString(); }
+
+export const opencodeSpec: CliAgentSpec = {
+  kind: "opencode",
+  // OpenRouter is the gateway: opencode reads OPENROUTER_API_KEY from the env
+  // and serves any `openrouter/<provider>/<model>` id (e.g. z-ai/glm-5.2).
+  authEnv: "OPENROUTER_API_KEY",
+  bin: "opencode",
+  defaultModel: "openrouter/z-ai/glm-5.2",
+  // ACP-mode invocation — `opencode acp` is a protocolVersion-1 ACP server, so
+  // the runner delegates the whole wire protocol to AcpClientPeer. The model is
+  // resolved from opencode's config / the `--model` it was started with; the
+  // run provisioning writes the OpenRouter default so ACP turns use GLM-5.2.
+  acp: { command: "opencode", args: ["acp"] },
+  // Global npm install; symlink onto PATH only if the global bin dir isn't
+  // already there (so a non-login `sh -c` can find it).
+  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)',
+  // ── JSONL fallback (only reached if the ACP handshake negotiates a non-1
+  //    version; opencode is v1, so this is vestigial). `opencode run` prints
+  //    human-formatted text, so we capture the prompt round-trip as one message.
+  promptPayload: (prompt) => prompt,
+  buildCommand: ({ promptPath, model, cwd }) =>
+    `${cwd ? `cd ${shellQuote(cwd)} && ` : ""}opencode run ${model ? `--model ${shellQuote(model)} ` : ""}"$(cat ${shellQuote(promptPath)})"`,
+  extractSessionId: () => undefined,
+  mapEvent: (p): AgentMessage[] => {
+    const ts = now();
+    const text = typeof p.text === "string" ? p.text : typeof p.content === "string" ? p.content : "";
+    return text ? [{ type: "text", text, timestamp: ts }] : [];
+  },
+};
+
+export interface OpencodeRuntimeConfig {
+  /** OpenRouter-prefixed model id (default `openrouter/z-ai/glm-5.2`). */
+  model?: string;
+}
+
+export function createOpencodeRuntime(config: OpencodeRuntimeConfig = {}) {
+  return createCliAgentRuntime(opencodeSpec, config.model ?? opencodeSpec.defaultModel);
+}
+
+export default createOpencodeRuntime();

package/src/sandbox.ts

@@ -10,12 +10,12 @@ import { dirname } from "node:path";
 import { spawn } from "node:child_process";
 import { Readable, Writable } from "node:stream";
 import { Sandbox, SandboxNotFoundError, RateLimitError } from "e2b";
-import type { SandboxNetworkOpts as E2bNetworkOpts, SandboxNetworkRule as E2bNetworkRule } from "e2b";
+import type { SandboxNetworkOpts as E2bNetworkOpts, SandboxNetworkRule as E2bNetworkRule, CommandHandle } from "e2b";
 import { Sandbox as Desktop } from "@e2b/desktop";
 import pRetry from "p-retry";
 import type { FailedAttemptError } from "p-retry";
 import { SandboxUnavailableError } from "./sandbox-errors.js";
-import type { SandboxProvider, DesktopSandboxProvider, SandboxCommandResult } from "./types/sandbox.js";
+import type { SandboxProvider, DesktopSandboxProvider, SandboxCommandResult, SandboxCommandRunOptions, SandboxBackgroundProcess } from "./types/sandbox.js";
 import type { ConnectorRequestRules } from "./types/workflow-metadata.js";
 import type { NetworkPolicy as VercelNetworkPolicy, NetworkPolicyRule as VercelNetworkPolicyRule } from "@vercel/sandbox";
 
@@ -301,6 +301,15 @@ export function makeSandboxProvider(sb: Sandbox | Desktop): SandboxProvider {
       async write(path, content) {
         await (sb.files.write as (p: string, d: string) => Promise<unknown>)(path, content);
       },
+      // Read over the envd HTTP API (`Sandbox.files.read` → `GET /files`), a
+      // DIFFERENT transport from `commands` (the connect-web gRPC stream). A large
+      // readback over HTTP is decoded by `fetch`'s native `Content-Encoding`
+      // handling, so it is immune to the connect-web "received unsupported
+      // compressed output" failure that can abort `commands.run` output on a big
+      // frame — the property `launchStep` relies on to recover full logs.
+      async read(path) {
+        return await (sb.files.read as (p: string) => Promise<string>)(path);
+      },
     },
     // e2b 2.30 `kill()` returns Promise<boolean>; our provider contract is
     // Promise<void>, so discard the result.
@@ -363,14 +372,69 @@ function withSnapshotRetry(p: SandboxProvider): SandboxProvider {
   return { ...p, snapshot: () => withSandboxRetry(snapshot) };
 }
 
+/** Wrap an E2B `CommandHandle` as a provider-agnostic background process.
+ *  `wait()` is normalised NOT to throw on a non-zero exit (mirroring the
+ *  `commands.run` contract in `makeSandboxProvider`) so callers branch on
+ *  `exitCode` instead of catching. */
+function wrapE2bBackgroundProcess(handle: CommandHandle): SandboxBackgroundProcess {
+  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 as { exitCode?: unknown; stdout?: unknown; stderr?: unknown };
+        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(); },
+  };
+}
+
 /** E2B base provider + live-filesystem snapshot. E2B's `createSnapshot()` captures
  *  the running sandbox as a persistent snapshot whose id is usable as a
  *  `Sandbox.create()` source and outlives the origin sandbox — so E2B reaches
  *  snapshot / `bootFrom` parity with Vercel, and snapshot-backed `ctx.pause` works
  *  on E2B. (Desktop intentionally omits this — it is registry-only, not selectable.) */
 function makeE2bSandboxProvider(sb: Sandbox): SandboxProvider {
+  const base = makeSandboxProvider(sb);
   return {
-    ...makeSandboxProvider(sb),
+    ...base,
+    commands: {
+      ...base.commands,
+      // ADR-0028: background launch + reconnect-by-pid. The step runner runs as
+      // a background command so a server-driven pause can freeze it mid-turn
+      // (pauseProcess) and the resume activity can re-attach by pid and await
+      // its exit — continuing the SAME process, no re-run. E2B-only; Vercel's
+      // provider omits these and pauses via snapshot + re-run.
+      async runBackground(cmd, opts) {
+        const { sudo, onStdout, onStderr, ...rest } = (opts ?? {}) as SandboxCommandRunOptions;
+        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() {
       // Raw capture — the transient pause/reclaim race is retried centrally:
       // createSandbox/reconnectSandbox wrap every provider's snapshot() in
@@ -379,6 +443,14 @@ function makeE2bSandboxProvider(sb: Sandbox): SandboxProvider {
       const { snapshotId } = await sb.createSnapshot();
       return { snapshotId };
     },
+    // ADR-0027: native VM-suspend. Freezes the live process in place (zero
+    // compute) and returns the sandbox id as the resume handle — resume is
+    // `reconnectSandbox(...)` (Sandbox.connect), which auto-resumes a paused VM.
+    // Distinct from snapshot(): no FS image, no kill, no re-run from the top.
+    async pauseProcess() {
+      await sb.pause();
+      return { resumeHandle: sb.sandboxId };
+    },
     // Push a freshly-resolved egress policy onto the live sandbox via E2B's
     // native `updateNetwork` — the E2B analogue of Vercel's `update({
     // networkPolicy })`. Lets the server re-resolve the run policy (re-minting
@@ -814,6 +886,9 @@ export function makeLocalSandboxProvider(): SandboxProvider {
         await fs.mkdir(dirname(path), { recursive: true });
         await fs.writeFile(path, content);
       },
+      async read(path) {
+        return await fs.readFile(path, "utf8");
+      },
     },
     async kill() { /* caller IS the sandbox — killing it is the server's job */ },
   };

package/src/step-invocation/index.ts

@@ -27,7 +27,8 @@ export {
   stepInputPath,
   requestContextPath,
 } from "./protocol.js";
-export { invokeStep, parseStepResult, buildStepEnvs } from "./invoker.js";
+export { invokeStep, launchStep, reconnectStep, parseStepResult, buildStepEnvs } from "./invoker.js";
+export type { RunningStep, InvokeStepOptions } from "./invoker.js";
 export { serveStep } from "./server.js";
 export type { StepHandler, ServeStepRequest, StepHandlerResult } from "./server.js";
 export { StepExecutionError } from "./types.js";