@agent-compose/sdk 0.6.0 → 0.7.0

package/src/agent/agent-context.ts

@@ -71,29 +71,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

package/src/agent/agent-loop.ts

@@ -164,9 +164,16 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
   const logLabel           = opts.label ?? "[Agent Loop]";
   const startedAt          = Date.now();
   // No budget ⇒ no turn cap: the harness runtime (Claude Code) decides when it's
-  // done. A numeric budget is an explicit caller choice, not a default we impose.
+  // done in one unbounded session. A numeric budget is an explicit caller choice.
+  // Default to a SMALL allowance (not 1) so the loop can RE-PROMPT for the closing
+  // <status>/<response> when a session ends EARLY — e.g. a human pause (agentc
+  // pause / AskUserQuestion) freezes the VM mid-tool and the resumed session can
+  // drop its final turn after doing the work. The re-prompt (PROTOCOL_SUFFIX)
+  // only fires when an iteration produced no exit_signal, so a clean run still
+  // settles in ONE iteration — these extra iterations are a recovery path, not
+  // the norm.
   const turnsPerIteration  = opts.turnsPerIteration;
-  const maxIterations      = opts.maxIterations ?? (turnsPerIteration === undefined ? 1 : 8);
+  const maxIterations      = opts.maxIterations ?? (turnsPerIteration === undefined ? 3 : 8);
   // A responseSchema is a CONTRACT, not a hope: when the agent's <response> fails
   // validation, the loop re-prompts with the exact errors until it conforms —
   // without consuming the caller's iteration budget. The backstop below only

package/src/agent/run-agent.ts

@@ -14,6 +14,7 @@ import { z } from "zod";
 import { randomUUID } from "node:crypto";
 import { getActiveStep, nextAgentCallInActiveStep } from "../active-step.js";
 import { corePause, type PauseRequest } from "../pause/pause-core.js";
+import { createAskHumanProcessor } from "../processors/ask-human.js";
 import { agentLoop } from "./agent-loop.js";
 import { consumeSteerPending, runControlPoller } from "./steer-control.js";
 import type { AgentLifecycleEvent, AgentLoopResult } from "./agent-loop.js";
@@ -330,6 +331,13 @@ export async function agent<T = unknown>(opts: AgentOpts<T>): Promise<AgentLoopR
   // (the boundary self-pause trigger + the prompt instruction above). Human
   // steering works regardless — see the ungated control poller.
   const mode = opts.mode ?? "auto";
+  // Ask-a-human is TOOLS-driven, not a separate mode: the ask-human processor is
+  // a chain default that maps the `AskUserQuestion` tool to a server pause (the
+  // run freezes, the human answers, the answer returns as the tool result). It's
+  // a no-op for any agent that doesn't have / call `AskUserQuestion`, so granting
+  // that tool to an agent IS its "can ask a human" switch — withhold it and the
+  // agent simply can't (it reports blockers up instead).
+  const processors = [createAskHumanProcessor(), ...(opts.processors ?? [])];
 
   try {
   return await agentLoop({
@@ -361,7 +369,7 @@ export async function agent<T = unknown>(opts: AgentOpts<T>): Promise<AgentLoopR
     ...(opts.events ? { onAgentLifecycleEvent: (event: AgentLifecycleEvent) => { void opts.events?.emit(event); } } : {}),
     ...(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: "", workflowId: "",
       factoryId: null, apiKeyScopes: [], parentRunId: null,

package/src/index.ts

@@ -77,6 +77,8 @@ export {
   requireScope,
   redactPattern,
   createGatePauseProcessor,
+  createAskHumanProcessor,
+  ASK_USER_QUESTION_TOOL,
 } from "./processors/index.js";
 export type {
   Processor,
@@ -174,6 +176,17 @@ 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";
 
 // Built-in coding tools for Vercel AI SDK runtime.
 export { bashTool, codingTools, editTool, readTool, writeTool } from "./tools/index.js";

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/index.ts

@@ -20,3 +20,8 @@ export {
 // 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;
     }
 

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

@@ -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.
@@ -877,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 */ },
   };