@agent-compose/sdk 0.6.0 → 0.8.0

package/src/runtimes/claude-code.ts

@@ -0,0 +1,246 @@
+/**
+ * Claude Code CLI runtime — drives the `claude` coding CLI headless INSIDE
+ * the sandbox (`claude -p --output-format stream-json`) and maps its JSONL
+ * event stream onto the AgentMessage contract.
+ *
+ * This is a different mechanism from `claudeRuntime` (claude.ts): that one
+ * drives the Anthropic Agent SDK in the CALLING process, which makes it
+ * unusable wherever the caller is the server (a cloud session's turns) —
+ * "never execute user-provided source in the server process". This runtime
+ * is a CLI-agent spec like codex/opencode: the agent loop runs entirely
+ * in-sandbox and we only stream-parse the events it prints, so the
+ * server→sandbox cloud-executor path can host it (CLOUD_SESSION_RUNTIMES).
+ *
+ * Transports, mirroring codexSpec exactly:
+ *   - ACP: the Zed adapter (`npx @zed-industries/claude-code-acp`) — the SAME
+ *     pinned adapter the local bridge daemon launches (cli/src/bridge/acp.ts
+ *     imports the pin from here). Engages only where the provider exposes
+ *     `commands.spawnDuplex` (the in-VM/local view); the server→sandbox
+ *     E2B/Vercel view has no duplex, so cloud-session turns always drive the
+ *     JSONL path below. Cold start: the adapter is npx-fetched on first
+ *     launch (~10-30s once per sandbox lifetime; node/npm are in the
+ *     agent-env image).
+ *   - JSONL: `claude -p --output-format stream-json --verbose`, resume via
+ *     `--resume <session_id>`. The `claude` binary is BAKED into the
+ *     `agent-env-<size>` E2B image at /usr/local/bin/claude
+ *     (infra/e2b-template/build.ts), so there is no install cold-start on the
+ *     platform path; the `install` below is the bare-sandbox fallback.
+ *
+ * Auth (in-sandbox env, in the CLI's own precedence order):
+ *   - `CLAUDE_CODE_OAUTH_TOKEN` — a user subscription (BYOS setup-token /
+ *     OAuth grant); rides the user's plan directly against Anthropic.
+ *   - `ANTHROPIC_API_KEY` (+ `ANTHROPIC_BASE_URL`) — an API key; for cloud
+ *     sessions this is the gateway-minted session virtual key pointed at the
+ *     token-metering gateway's Anthropic passthrough (ADR-0039).
+ */
+
+import type { AgentMessage } from "../index.js";
+import { createCliAgentRuntime, shellQuote, type CliAgentSpec, type CliReasoningEffort } from "./_cli-agent.js";
+import { formatError } from "../utils/errors.js";
+
+function now(): string { return new Date().toISOString(); }
+
+/** Pinned Claude Code ACP adapter (Zed's npm shim — `claude` has no native
+ *  ACP mode). Pinned EXACT, not a range: the adapter's README warns of
+ *  breaking changes; bump deliberately and re-verify a live turn. The local
+ *  bridge daemon (cli/src/bridge/acp.ts) imports this same pin so both
+ *  executors launch the identical adapter. Verified against 0.16.2. */
+export const CLAUDE_CODE_ACP_ADAPTER = "@zed-industries/claude-code-acp@0.16.2";
+
+/** One content block inside a `claude` stream-json assistant/user message. */
+interface ClaudeContentBlock {
+  type?: string;
+  text?: string;
+  thinking?: string;
+  id?: string;
+  name?: string;
+  input?: Record<string, unknown>;
+  tool_use_id?: string;
+  content?: unknown;
+  is_error?: boolean;
+}
+
+/** Flatten a tool_result's content (string, or an array of text blocks) into
+ *  the plain string the AgentMessage contract carries. */
+function toolResultText(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((b: ClaudeContentBlock) => (typeof b?.text === "string" ? b.text : ""))
+      .join("");
+  }
+  return content == null ? "" : JSON.stringify(content) ?? "";
+}
+
+/** Extended-thinking token budget per effort level — Claude Code's real knob
+ *  is the `MAX_THINKING_TOKENS` env var (its documented settings env), set
+ *  per invocation below. Values mirror the platform turn loop's
+ *  `EFFORT_BUDGET_TOKENS` (server model-client) so "high" means the same
+ *  thing in a channel and in a claude-code session. */
+export const CLAUDE_CODE_THINKING_TOKENS: Record<CliReasoningEffort, number> =
+  { low: 2_048, medium: 8_192, high: 16_384 };
+
+export const claudeCodeSpec: CliAgentSpec = {
+  kind: "claude-code",
+  authEnv: "ANTHROPIC_API_KEY",
+  bin: "claude",
+  // ACP-mode invocation — the same npx adapter shape as codexSpec (and the
+  // same launch the bridge daemon uses for local claude-code sessions).
+  acp: { command: "npx", args: ["--yes", CLAUDE_CODE_ACP_ADAPTER] },
+  // Bare-sandbox fallback only: the agent-env image bakes /usr/local/bin/claude
+  // (same recipe — infra/e2b-template/build.ts), so the probe short-circuits
+  // on the platform path. Anthropic's installer drops a versioned binary under
+  // $HOME with a ~/.local/bin/claude launcher; resolve the symlink and copy
+  // the self-contained binary to a world-executable system path.
+  install:
+    'curl -fsSL https://claude.ai/install.sh | bash && ' +
+    'REAL=$(readlink -f "$HOME/.local/bin/claude") && test -f "$REAL" && ' +
+    'sudo cp "$REAL" /usr/local/bin/claude && sudo chmod 0755 /usr/local/bin/claude',
+  // Claude reads the prompt from stdin in -p mode.
+  promptPayload: (prompt) => prompt,
+  buildCommand: ({ promptPath, sessionId, model, cwd, effort }) => {
+    const flags = [
+      "-p",
+      // stream-json is the JSONL event stream; -p requires --verbose with it.
+      "--output-format stream-json",
+      "--verbose",
+      // Raw API stream events ride along as `stream_event` lines — the
+      // text_delta source for progressive rendering (mapEvent below). The
+      // complete `assistant` message events still arrive; deltas are
+      // additive and live-only.
+      "--include-partial-messages",
+      // agent-compose already runs the CLI inside an isolated sandbox VM, so
+      // permission prompts must not block a headless turn. IS_SANDBOX=1 is
+      // claude's own attestation env for exactly this: it lifts the flag's
+      // root-user refusal (the E2B agent-env user is root).
+      "--dangerously-skip-permissions",
+      ...(model ? [`--model ${shellQuote(model)}`] : []),
+      ...(sessionId ? [`--resume ${shellQuote(sessionId)}`] : []),
+    ].join(" ");
+    // Reasoning effort rides as the CLI's own thinking-budget env, same
+    // per-invocation idiom as IS_SANDBOX (never persisted into settings).
+    const thinking = effort ? `MAX_THINKING_TOKENS=${CLAUDE_CODE_THINKING_TOKENS[effort]} ` : "";
+    return `${cwd ? `cd ${shellQuote(cwd)} && ` : ""}${thinking}IS_SANDBOX=1 claude ${flags} < ${shellQuote(promptPath)}`;
+  },
+  // Every stream-json event carries the session id; the init event is first.
+  extractSessionId: (p) => (typeof p.session_id === "string" ? p.session_id : undefined),
+  mapEvent: (p): AgentMessage[] => {
+    const ts = now();
+    switch (p.type) {
+      // Assistant API message: content blocks → text / thinking / tool_use.
+      case "assistant": {
+        const message = p.message as { content?: ClaudeContentBlock[] } | undefined;
+        const blocks = Array.isArray(message?.content) ? message.content : [];
+        return blocks.flatMap((b): AgentMessage[] => {
+          if (b.type === "text" && typeof b.text === "string" && b.text.length > 0) {
+            return [{ type: "text", text: b.text, timestamp: ts }];
+          }
+          if (b.type === "thinking" && typeof b.thinking === "string" && b.thinking.length > 0) {
+            return [{ type: "thinking", text: b.thinking, timestamp: ts }];
+          }
+          if (b.type === "tool_use") {
+            return [{
+              type: "tool_use", toolName: String(b.name ?? "tool"),
+              toolInput: b.input ?? {}, toolUseId: String(b.id ?? ""), timestamp: ts,
+            }];
+          }
+          return [];
+        });
+      }
+      // User API message: the CLI echoes tool results back as user content.
+      case "user": {
+        const message = p.message as { content?: ClaudeContentBlock[] } | undefined;
+        const blocks = Array.isArray(message?.content) ? message.content : [];
+        return blocks.flatMap((b): AgentMessage[] =>
+          b.type === "tool_result"
+            ? [{
+                type: "tool_result", toolUseId: String(b.tool_use_id ?? ""),
+                output: toolResultText(b.content), isError: b.is_error === true, timestamp: ts,
+              }]
+            : []);
+      }
+      // Raw API stream event (--include-partial-messages): text deltas of
+      // the in-progress block map to the live-only `text_delta` kind so a
+      // streaming consumer (the cloud executor's partial frames) can render
+      // progressively. Everything else under stream_event (message_start,
+      // content_block_start/stop, thinking/input_json deltas) is noise here —
+      // the complete `assistant` event above remains the durable source.
+      case "stream_event": {
+        const ev = p.event as {
+          type?: string;
+          delta?: { type?: string; text?: string };
+          message?: { usage?: Record<string, number> };
+          usage?: Record<string, number>;
+        } | undefined;
+        if (
+          ev?.type === "content_block_delta" &&
+          ev.delta?.type === "text_delta" &&
+          typeof ev.delta.text === "string" &&
+          ev.delta.text.length > 0
+        ) {
+          return [{ type: "text_delta", text: ev.delta.text, timestamp: ts }];
+        }
+        // Live-only incremental usage (the text_delta of token counts):
+        // message_start carries the model call's input-side finals;
+        // message_delta carries the call's CUMULATIVE output so far. The
+        // terminal `result` usage above stays the durable turn total.
+        if (ev?.type === "message_start" && ev.message?.usage) {
+          const u = ev.message.usage;
+          return [{
+            type: "usage_delta", boundary: "call_start",
+            inputTokens: u.input_tokens ?? 0,
+            outputTokens: u.output_tokens ?? 0,
+            cacheReadTokens: u.cache_read_input_tokens ?? 0,
+            cacheCreationTokens: u.cache_creation_input_tokens ?? 0,
+            timestamp: ts,
+          }];
+        }
+        if (ev?.type === "message_delta" && ev.usage && typeof ev.usage.output_tokens === "number") {
+          return [{
+            type: "usage_delta", boundary: "call_delta",
+            inputTokens: 0, outputTokens: ev.usage.output_tokens,
+            cacheReadTokens: 0, cacheCreationTokens: 0,
+            timestamp: ts,
+          }];
+        }
+        return [];
+      }
+      // Terminal result: usage on success (the text already streamed via the
+      // assistant events); an honest string error on failure.
+      case "result": {
+        if (p.is_error === true) {
+          return [{ type: "error", text: formatError(p.result ?? p.subtype ?? p), timestamp: ts }];
+        }
+        const u = p.usage as Record<string, number> | undefined;
+        if (!u) return [];
+        return [{
+          type: "usage",
+          inputTokens: u.input_tokens ?? 0,
+          outputTokens: u.output_tokens ?? 0,
+          cacheReadTokens: u.cache_read_input_tokens ?? 0,
+          cacheCreationTokens: u.cache_creation_input_tokens ?? 0,
+          durationMs: typeof p.duration_ms === "number" ? p.duration_ms : 0,
+          numTurns: typeof p.num_turns === "number" ? p.num_turns : 1,
+          timestamp: ts,
+        }];
+      }
+      // system/init carries the session id (extractSessionId); nothing to map.
+      default:
+        return [];
+    }
+  },
+};
+
+export interface ClaudeCodeRuntimeConfig {
+  /** Claude model id (`--model`). Omit to use the CLI's configured default. */
+  model?: string;
+  /** Extended-thinking effort (`MAX_THINKING_TOKENS`). Omit for the CLI's
+   *  default behaviour (no forced budget). */
+  effort?: CliReasoningEffort;
+}
+
+export function createClaudeCodeRuntime(config: ClaudeCodeRuntimeConfig = {}) {
+  return createCliAgentRuntime(claudeCodeSpec, config.model, config.effort);
+}
+
+export default createClaudeCodeRuntime();

package/src/runtimes/claude.ts

@@ -131,6 +131,30 @@ function resolveThinking(model: string, thinking: ThinkingConfig | undefined): T
   return thinking;
 }
 
+/** Bounded tail of the Claude Code process's stderr. The Agent SDK's
+ *  process-exit error carries ONLY the exit code ("Claude Code process
+ *  exited with code 1") — the CLI's actual complaint goes to stderr, which
+ *  query() surfaces exclusively through the `stderr` callback. Without
+ *  capturing it, a startup failure (bad flag, root refusal, dead config)
+ *  reaches the run card as an uninformative exit code. Same 2000-char cap
+ *  as the CLI-agent runtimes' exit-code tail (_cli-agent.ts). */
+export const STDERR_TAIL_CAP = 2_000;
+
+export class StderrTail {
+  private buf = "";
+  append(data: string): void {
+    this.buf = (this.buf + data).slice(-STDERR_TAIL_CAP);
+  }
+  /** The captured tail, trimmed — empty string when nothing was written. */
+  get text(): string {
+    return this.buf.trim();
+  }
+  /** Suffix an error message with the tail (no-op when stderr was silent). */
+  decorate(message: string): string {
+    return this.text ? `${message}\nstderr tail:\n${this.text}` : message;
+  }
+}
+
 /** Canonical install path for Claude Code inside a Vercel sandbox.
  *  Our `agent-env` setup copies the native binary here as a real file
  *  (not a symlink) so it survives snapshotting. The Anthropic installer
@@ -273,6 +297,8 @@ export class ClaudeRunner implements ModelExecutionContract {
       .filter((s): s is string => Boolean(s && s.trim()))
       .join("\n\n");
 
+    const stderrTail = new StderrTail();
+
     try {
       let emittedAssistantText = false;
       for await (const message of query({
@@ -287,6 +313,7 @@ export class ClaudeRunner implements ModelExecutionContract {
           effort: this.config.effort,
           cwd: this.options.cwd,
           abortController: queryAbort,
+          stderr: (data: string) => stderrTail.append(data),
           env: { ...process.env, ...(this.config.env ?? {}) },
           pathToClaudeCodeExecutable: this.config.pathToClaudeCodeExecutable
             ?? process.env.CLAUDE_CODE_EXECUTABLE
@@ -312,7 +339,7 @@ export class ClaudeRunner implements ModelExecutionContract {
           // arrived in the stream.
           if (raw.type === "result" && msg.type === "text" && emittedAssistantText) continue;
           if (msg.type === "text" && raw.type === "assistant") emittedAssistantText = true;
-          yield msg;
+          yield msg.type === "error" ? { ...msg, text: stderrTail.decorate(msg.text) } : msg;
         }
         // End-of-iteration signal: SDK emits a `result` message after the
         // assistant's turn completes. Close the queue so the AsyncIterable
@@ -333,7 +360,10 @@ export class ClaudeRunner implements ModelExecutionContract {
       if (/maximum number of turns/i.test(text)) {
         yield { type: "done", sessionId: opts.sessionId ?? "", timestamp: now() };
       } else {
-        yield { type: "error", text, timestamp: now() };
+        // The process-exit throw ("Claude Code process exited with code N")
+        // carries no detail — the CLI's complaint went to stderr. Attach the
+        // captured tail so the run card says WHY, not just the exit code.
+        yield { type: "error", text: stderrTail.decorate(text), timestamp: now() };
       }
     } finally {
       // Belt-and-braces — close on error/abort too so the dangling

package/src/runtimes/codex.ts

@@ -14,7 +14,7 @@
  */
 
 import type { AgentMessage } from "../index.js";
-import { createCliAgentRuntime, shellQuote, type CliAgentSpec } from "./_cli-agent.js";
+import { createCliAgentRuntime, shellQuote, type CliAgentSpec, type CliReasoningEffort } from "./_cli-agent.js";
 import { formatError } from "../utils/errors.js";
 
 function now(): string { return new Date().toISOString(); }
@@ -24,6 +24,35 @@ function now(): string { return new Date().toISOString(); }
  *  overrides the bundled `@openai/codex` the adapter drives underneath. */
 const CODEX_ACP_ADAPTER = "@agentclientprotocol/codex-acp@0.1.0";
 
+/** Known-noise codex ADVISORY lines. codex emits these as `item.completed`
+ *  error items on the `--json` stream (exec maps every `Warning` notification
+ *  to an error item — verified against codex-cli 0.147.0), so without a filter
+ *  they render as conversation content. They are startup/turn advisories, not
+ *  turn failures: route them to the runner's logs and keep them out of the
+ *  transcript.
+ *
+ *  Deliberately a NARROW allowlist of known warning classes — never a blanket
+ *  stderr/error swallow; real errors must keep surfacing. Current classes:
+ *
+ *  - model-metadata fallback: fires whenever the model id is one codex's
+ *    bundled catalog cannot resolve — every gateway-prefixed session id
+ *    (`openrouter/openai/gpt-…`) trips it, because the catalog's namespaced
+ *    -suffix matcher strips at most ONE namespace segment. Benign on the
+ *    gateway lane: the fallback profile (272k context, plain chat wire) is
+ *    the correct one for a chat-completions gateway, and the only codex
+ *    config that could silence it at source (`model_catalog_json`) demands a
+ *    full authoritative catalog with per-model instruction templates and
+ *    hard-fails codex at startup on any shape drift. */
+const CODEX_ADVISORY_PATTERNS: readonly RegExp[] = [
+  /Model metadata for .+ not found\. Defaulting to fallback metadata/,
+];
+
+/** True when an error-item message is a known codex advisory (log-level
+ *  noise), not a real error. Exported for tests. */
+export function isCodexAdvisoryNoise(text: string): boolean {
+  return CODEX_ADVISORY_PATTERNS.some((re) => re.test(text));
+}
+
 /** Exported for the fixture-based parity tests (ADR-0020): the legacy JSONL
  *  `mapEvent` is the golden the ACP normaliser is asserted equal to. Not part
  *  of the public runtime surface — `createCodexRuntime` stays the entry point. */
@@ -48,7 +77,7 @@ export const codexSpec: CliAgentSpec = {
   install: 'sudo npm install -g @openai/codex && (command -v codex >/dev/null 2>&1 || sudo ln -sf "$(npm prefix -g)/bin/codex" /usr/local/bin/codex)',
   // Codex reads the prompt from stdin when invoked as `codex exec ... -`.
   promptPayload: (prompt) => prompt,
-  buildCommand: ({ promptPath, sessionId, model, cwd }) => {
+  buildCommand: ({ promptPath, sessionId, model, cwd, effort }) => {
     const flags = [
       "--json",
       "--skip-git-repo-check",
@@ -58,6 +87,10 @@ export const codexSpec: CliAgentSpec = {
       // for running in environments that are externally sandboxed".
       "--dangerously-bypass-approvals-and-sandbox",
       ...(model ? ["-m", shellQuote(model)] : []),
+      // codex's own reasoning knob — a config override, valid values
+      // low|medium|high (plus "minimal", unused here). The value comes from
+      // the closed CliReasoningEffort set, so it is shell-safe unquoted.
+      ...(effort ? ["-c", `model_reasoning_effort=${effort}`] : []),
       ...(cwd ? ["-C", shellQuote(cwd)] : []),
     ].join(" ");
     // Fresh turn: `codex exec <flags> - < prompt`. Continue a thread:
@@ -93,6 +126,22 @@ export const codexSpec: CliAgentSpec = {
           const failed = item.status === "failed" || (typeof item.exit_code === "number" && item.exit_code !== 0);
           return [{ type: "tool_result", toolUseId: id, output: String(item.aggregated_output ?? item.output ?? ""), isError: failed, timestamp: ts }];
         }
+        // Error ITEMS (`{"item":{"type":"error","message":…}}` — e.g. codex's
+        // "Falling back…" notices) are errors, not tool calls: the generic
+        // branch below used to surface them as a tool named "error" with the
+        // raw item as input. Normalise to the error AgentMessage with a
+        // STRING text, extracting `.message`.
+        if (itype === "error") {
+          if (p.type !== "item.completed") return [];
+          const text = formatError(item.message ?? item);
+          // Known advisory classes go to the runner's logs, never the
+          // transcript (see CODEX_ADVISORY_PATTERNS).
+          if (isCodexAdvisoryNoise(text)) {
+            console.warn(`[codex] advisory (kept out of transcript): ${text}`);
+            return [];
+          }
+          return [{ type: "error", text, timestamp: ts }];
+        }
         // file_change / mcp_tool_call / web_search / todo: surface once, on completion.
         if (p.type === "item.completed") {
           return [{ type: "tool_use", toolName: itype || "item", toolInput: item, toolUseId: String(item.id ?? ""), timestamp: ts }];
@@ -125,10 +174,13 @@ export const codexSpec: CliAgentSpec = {
 export interface CodexRuntimeConfig {
   /** Codex model id (`-m`). Omit to use the codex CLI's configured default. */
   model?: string;
+  /** Reasoning effort (`-c model_reasoning_effort=<level>`). Omit to use the
+   *  codex CLI's configured default. */
+  effort?: CliReasoningEffort;
 }
 
 export function createCodexRuntime(config: CodexRuntimeConfig = {}) {
-  return createCliAgentRuntime(codexSpec, config.model);
+  return createCliAgentRuntime(codexSpec, config.model, config.effort);
 }
 
 export default createCodexRuntime();

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/openai-desktop.ts

@@ -20,6 +20,52 @@ export interface OpenAIDesktopRunnerOptions extends RuntimeOptions {
   openaiKey: string;
 }
 
+// ── computer-use-preview wire types ─────────────────────────────────────────
+// The narrow slice of the Responses API this loop exchanges, typed locally:
+// the OpenAI SDK's published types pin computer-use actions to the stable
+// x/y shape, while this preview runner speaks the coordinate-tuple wire —
+// so the exchange is described here instead of with SDK types.
+
+/** One model-emitted desktop action. Coordinates arrive in DISPLAY (model)
+ *  space and are rescaled to the real desktop before dispatch. */
+interface ComputerAction {
+  type: string;
+  coordinate?: [number, number];
+  startCoordinate?: [number, number];
+  endCoordinate?: [number, number];
+  text?: string;
+  key?: string;
+  direction?: string;
+  ticks?: number;
+}
+
+/** Response output blocks this loop consumes — anything else is ignored. */
+type ResponseBlock =
+  | { type: "computer_call"; call_id: string; action: ComputerAction }
+  | { type: "text"; text: string };
+
+/** User-turn content parts this loop sends. */
+type InputPart =
+  | { type: "input_image"; image_url: string }
+  | { type: "input_text"; text: string }
+  | { type: "computer_call_output"; call_id: string; output: { type: "input_image"; image_url: string } };
+
+interface InputMessage {
+  role: "user";
+  content: InputPart[];
+}
+
+/** The one `responses.create` call shape this runner makes. */
+interface ComputerUseResponsesApi {
+  create(params: {
+    model: string;
+    tools: Array<{ type: "computer_use_preview"; name: string; display_width: number; display_height: number; environment: "linux" }>;
+    input: InputMessage[];
+    truncation: "auto";
+    previous_response_id?: string;
+  }): Promise<{ id: string; output?: ResponseBlock[] }>;
+}
+
 export class OpenAIDesktopRunner implements ModelExecutionContract {
   readonly kind = "openai-desktop";
   readonly model = "computer-use-preview";
@@ -55,8 +101,7 @@ export class OpenAIDesktopRunner implements ModelExecutionContract {
 
     const screenshot = await captureScaledScreenshot(sandbox);
 
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const messages: any[] = [{
+    const messages: InputMessage[] = [{
       role: "user",
       content: [
         { type: "input_image", image_url: `data:image/png;base64,${screenshot}` },
@@ -64,11 +109,14 @@ export class OpenAIDesktopRunner implements ModelExecutionContract {
       ],
     }];
 
+    // The SDK's typed `responses.create` rejects this preview exchange (see
+    // the wire-types block above), so cast the resource once to the local
+    // narrow interface.
+    const responses = this.openai.responses as unknown as ComputerUseResponsesApi;
     let previousResponseId: string | undefined;
 
     for (let turn = 0; turn < MAX_TURNS; turn++) {
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      const response = await (this.openai as any).responses.create({
+      const response = await responses.create({
         model: "computer-use-preview",
         tools: [{ type: "computer_use_preview", name: "computer", display_width: DISPLAY_WIDTH, display_height: DISPLAY_HEIGHT, environment: "linux" }],
         input: messages,
@@ -77,14 +125,13 @@ export class OpenAIDesktopRunner implements ModelExecutionContract {
       });
       previousResponseId = response.id;
 
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      const computerCalls: any[] = response.output?.filter((b: any) => b.type === "computer_call") ?? [];
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      const textBlocks: any[] = response.output?.filter((b: any) => b.type === "text") ?? [];
+      const computerCalls = response.output?.filter(
+        (b): b is Extract<ResponseBlock, { type: "computer_call" }> => b.type === "computer_call") ?? [];
+      const textBlocks = response.output?.filter(
+        (b): b is Extract<ResponseBlock, { type: "text" }> => b.type === "text") ?? [];
 
       if (textBlocks.length > 0) {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        yield { type: "text", text: textBlocks.map((b: any) => b.text).join("\n"), timestamp: ts() };
+        yield { type: "text", text: textBlocks.map((b) => b.text).join("\n"), timestamp: ts() };
         break;
       }
 
@@ -98,8 +145,7 @@ export class OpenAIDesktopRunner implements ModelExecutionContract {
       if (computerCalls.length === 0) break;
 
       const next = await captureScaledScreenshot(sandbox);
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      messages.push({ role: "user", content: computerCalls.map((call: any) => ({
+      messages.push({ role: "user", content: computerCalls.map((call): InputPart => ({
         type: "computer_call_output",
         call_id: call.call_id,
         output: { type: "input_image", image_url: `data:image/png;base64,${next}` },
@@ -126,8 +172,7 @@ async function captureScaledScreenshot(sandbox: DesktopSandboxProvider): Promise
 function scaleX(x: number): number { return Math.round(x * DESKTOP_WIDTH / DISPLAY_WIDTH); }
 function scaleY(y: number): number { return Math.round(y * DESKTOP_HEIGHT / DISPLAY_HEIGHT); }
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-async function executeAction(sandbox: DesktopSandboxProvider, action: Record<string, any>): Promise<void> {
+async function executeAction(sandbox: DesktopSandboxProvider, action: ComputerAction): Promise<void> {
   const [x, y] = action.coordinate
     ? [scaleX(action.coordinate[0]), scaleY(action.coordinate[1])]
     : [0, 0];