@agent-compose/sdk 0.6.0 → 0.7.0

package/dist/runtimes/cursor.d.ts

@@ -0,0 +1,9 @@
+import { type CliAgentSpec } from "./_cli-agent.js";
+export declare const cursorSpec: CliAgentSpec;
+export interface CursorRuntimeConfig {
+    /** Cursor model id; ACP mode ignores it (account default) — applies to the `-p` fallback. */
+    model?: string;
+}
+export declare function createCursorRuntime(config?: CursorRuntimeConfig): import("../index.js").AgentRuntime<import("../index.js").SandboxProvider>;
+declare const _default: import("../index.js").AgentRuntime<import("../index.js").SandboxProvider>;
+export default _default;

package/dist/runtimes/droid.d.ts

@@ -0,0 +1,9 @@
+import { type CliAgentSpec } from "./_cli-agent.js";
+export declare const droidSpec: CliAgentSpec;
+export interface DroidRuntimeConfig {
+    /** `custom:<displayName>-<index>` matching the provisioned settings.json. */
+    model?: string;
+}
+export declare function createDroidRuntime(config?: DroidRuntimeConfig): import("../index.js").AgentRuntime<import("../index.js").SandboxProvider>;
+declare const _default: import("../index.js").AgentRuntime<import("../index.js").SandboxProvider>;
+export default _default;

package/dist/runtimes/openai-desktop.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: "",

package/dist/runtimes/opencode.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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 CliAgentSpec } from "./_cli-agent.js";
+export declare const opencodeSpec: CliAgentSpec;
+export interface OpencodeRuntimeConfig {
+    /** OpenRouter-prefixed model id (default `openrouter/z-ai/glm-5.2`). */
+    model?: string;
+}
+export declare function createOpencodeRuntime(config?: OpencodeRuntimeConfig): import("../index.js").AgentRuntime<import("../index.js").SandboxProvider>;
+declare const _default: import("../index.js").AgentRuntime<import("../index.js").SandboxProvider>;
+export default _default;

package/dist/runtimes/vercel.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

package/dist/step-invocation/invoker.d.ts

@@ -64,6 +64,17 @@ export interface InvokeStepOptions {
      *  the caller's job; the activity batches and inserts at step completion. */
     onStdout?: (line: string) => void;
     onStderr?: (line: string) => void;
+    /** Called when the LIVE output stream fails mid-run (e.g. E2B's connect-web
+     *  transport throws `received unsupported compressed output` on a large
+     *  compressed frame) and the invoker falls back to recovering the result +
+     *  full logs from the durable token-keyed files. The run is NOT failed — this
+     *  is the hook to emit a structured alert so the degradation is visible/paged.
+     *  Best-effort: keep it cheap and non-throwing. */
+    onStreamDegraded?: (info: {
+        error: unknown;
+        runnerPid: number;
+        resultToken: string;
+    }) => void;
 }
 /** A step running as a background command (ADR-0028). The activity races its
  *  `wait()` against a server pause request; on a pause it freezes the VM
@@ -101,4 +112,6 @@ export declare function reconnectStep<TOutput = unknown>(sandbox: SandboxProvide
     runnerPid: number;
     resultToken: string;
     stepIndex: number;
-}, opts?: Pick<InvokeStepOptions, "onStdout" | "onStderr">): Promise<RunningStep<TOutput>>;
+}, opts?: Pick<InvokeStepOptions, "onStdout" | "onStderr"> & {
+    signal?: AbortSignal;
+}): Promise<RunningStep<TOutput>>;

package/dist/step-invocation/protocol.d.ts

@@ -60,3 +60,11 @@ export declare function requestContextPath(stepIndex: number): string;
  *  drop the tail of a heavy stdout stream — the invoker falls back to
  *  reading this file when no sentinel is found on stdout. */
 export declare function stepResultFilePath(token: string): string;
+/** Sandbox-side path where the runner's stdout is tee'd as a durable LOG file,
+ *  keyed by the per-invocation token. The live output rides E2B's connect-web
+ *  command stream, which THROWS on a compressed large frame (gRPC-web cannot
+ *  decode message compression) and kills the feed mid-run. This file, read back
+ *  over the envd HTTP file transport (compression-immune), lets the invoker
+ *  recover the FULL logs after such a fault instead of losing the tail — the
+ *  log-side analogue of `stepResultFilePath` for the result. */
+export declare function stepLogFilePath(token: string): string;

package/dist/types/sandbox.d.ts

@@ -114,6 +114,15 @@ export interface SandboxProvider {
     };
     files: {
         write(path: string, content: string): Promise<void>;
+        /** Read a file's text content over the provider's FILE transport. On E2B this
+         *  is the envd HTTP API (`Sandbox.files.read`), a DIFFERENT transport from
+         *  `commands` — so a large readback is immune to the connect-web gRPC
+         *  message-compression that can abort `commands.run` output on a big frame
+         *  ("received unsupported compressed output"). This is what lets `launchStep`
+         *  recover the full logs + result after a live-stream fault. OPTIONAL —
+         *  implemented where durable file-readback is needed (E2B, local); providers
+         *  that never drive the recovery path (Vercel — foreground only) may omit it. */
+        read?(path: string): Promise<string>;
     };
     kill(): Promise<void>;
     /** Capture the running sandbox's state as a reusable snapshot. Vercel and E2B

package/dist/types/workflow.d.ts

@@ -90,6 +90,12 @@ export interface WorkflowDefinition<TOutput = unknown, TInput extends Record<str
     /** Same as `input`, for the workflow's return value. Captured into
      *  `outputSchema` metadata and rendered in the IO panel. */
     output?: z.ZodType<TOutput>;
+    /**
+     * @deprecated Legacy run-form. Prefer step-form — the
+     * `.step(defineStep(...))` builder — for per-step durability/replay and
+     * working pause. A run-form body compiles to one opaque step
+     * (`compileRunForm`), so any failure/resume re-runs the whole body.
+     */
     run: WorkflowFn<TOutput, TInput>;
     /**
      * All snapshot config — boot source plus capture mode.
@@ -210,6 +216,12 @@ export interface WorkflowDefinition<TOutput = unknown, TInput extends Record<str
  * stores the step plan; runner subprocesses execute one step at a time
  * via the StepInvocation seam.
  */
+/**
+ * @deprecated Run-form is legacy. Use the step-form overload —
+ * `defineWorkflow({ id, input, output }).step(defineStep(...)).build()` — for
+ * durable, replayable steps and working pause. Run-form compiles to a single
+ * opaque step (`compileRunForm`); there is no per-step replay.
+ */
 export declare function defineWorkflow<TOutput = unknown, TInput extends Record<string, unknown> = Record<string, unknown>>(def: WorkflowDefinition<TOutput, TInput>): Workflow<TInput, TOutput>;
 export declare function defineWorkflow<TInput, TOutput>(def: StepWorkflowDefinition<TInput, TOutput>): import("../workflow-steps/workflow.js").WorkflowBuilder<TInput, TInput>;
 /** Observability-only lifecycle hooks — passed to the workflow engine, not workflow authors. */

package/dist/utils/errors.d.ts

@@ -1,2 +1,10 @@
-/** Convert any thrown value to a string message. */
+/** Convert any thrown value to a string message, INCLUDING its `.cause` chain.
+ *
+ *  Many wrapped errors carry the real reason on `.cause` and only a generic
+ *  summary on `.message` — the Temporal SDK's "Failed to start Workflow" is the
+ *  canonical example (its `.cause` is the actual gRPC rejection, e.g. "search
+ *  attribute X is not defined"). Returning `.message` alone swallowed that, so
+ *  failures surfaced as opaque one-liners. Walk the chain and join the messages
+ *  so the root cause is always visible. Cycle-guarded against self-referential
+ *  `cause` links. */
 export declare function formatError(err: unknown): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-compose/sdk",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Client library for agent-compose — define agents, runtimes, and workflows, and invoke them against an agent-compose server.",
   "license": "MIT",
   "repository": {