@agent-compose/sdk 0.7.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/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];

package/src/sandbox/devbox.ts

@@ -0,0 +1,48 @@
+/**
+ * The devbox — ADR-0038's "Computer": one persistent E2B **desktop** machine per
+ * member, paused by default, resumed on attach (~100ms).
+ *
+ * This module is the SINGLE SOURCE for the machine's template identity: the
+ * recipe lives in `infra/e2b-template/devbox.ts`, `infra/e2b-template/build.ts`
+ * bakes it under the alias below, and the server imports the alias from here to
+ * provision a machine (exactly how `e2bBaseTemplate` reaches the E2B provider —
+ * a stable ALIAS, never a snapshot id, so the same string resolves in whichever
+ * E2B account a deployment uses).
+ *
+ * Interactive only. Workflow RUNS never execute on a devbox (ADR-0038 §2.6):
+ * runs boot the clean per-size `agent-compose-base-<size>` / `agent-env-<size>`
+ * templates so reproducibility never inherits hand-configured drift.
+ */
+
+/** Stable E2B template ALIAS for the per-member desktop machine. Baked by
+ *  `infra/e2b-template/build.ts` from `infra/e2b-template/devbox.ts`; CI rebakes
+ *  it on any master push that touches the recipe (.github/workflows/sandbox-images.yml).
+ *  Boot it with `@e2b/desktop`'s `Sandbox.create(E2B_DEVBOX_TEMPLATE, …)`. */
+export const E2B_DEVBOX_TEMPLATE = "agent-compose-devbox";
+
+/** Machine spec the devbox alias is stamped with. E2B sizing is TEMPLATE-baked
+ *  (no create-time cpu/mem knob), so this is the machine every member gets.
+ *
+ *  8 vCPU / 8192 MB matches E2B's stock `desktop` template — the exact shape the
+ *  ADR-0038 spike measured (pause 456ms / resume 99ms, RAM + desktop + dockerd
+ *  preserved). 8192 MB is also the E2B account's hard memory ceiling
+ *  (`Template.build` 400s above it), so this is the largest machine we can bake
+ *  today; raising it needs a plan change first. */
+export const E2B_DEVBOX_SPEC: { readonly cpuCount: number; readonly memoryMB: number } = {
+  cpuCount: 8,
+  memoryMB: 8192,
+};
+
+/** Recipe version of the baked devbox image. The alias is stable across
+ *  rebuilds (it re-points at the new build), so the alias alone can't tell you
+ *  WHICH recipe a machine was provisioned from — the server stamps
+ *  `dev_machines.template` with `e2bDevboxTemplateRef()` for that lineage.
+ *  BUMP whenever `infra/e2b-template/devbox.ts` changes what it bakes. */
+export const E2B_DEVBOX_RECIPE_VERSION = "1";
+
+/** Versioned, human-readable ref for the image a machine was provisioned from
+ *  (`agent-compose-devbox@1`) — what ADR-0038 §6's `dev_machines.template`
+ *  stores. NOT a boot target: boot from `E2B_DEVBOX_TEMPLATE`. */
+export function e2bDevboxTemplateRef(): string {
+  return `${E2B_DEVBOX_TEMPLATE}@${E2B_DEVBOX_RECIPE_VERSION}`;
+}

package/src/sandbox/exec-stream.ts

@@ -0,0 +1,48 @@
+/**
+ * SSE exec-stream parser — used by the agent sandbox broker clients in
+ * runner.ts to consume a streamed command execution.
+ */
+
+import type { SandboxCommandResult } from "../types/sandbox.js";
+
+type SseEvent = { type: string; data?: string; exitCode?: number };
+
+export interface ParseSseExecStreamOptions {
+  onStdout?: (data: string) => void;
+  onStderr?: (data: string) => void;
+}
+
+/**
+ * Parse an SSE exec stream from a ReadableStream.
+ * Used by the agent sandbox broker in runner.ts.
+ */
+export async function parseSseExecStream(
+  body: ReadableStream<Uint8Array>,
+  opts?: ParseSseExecStreamOptions,
+): Promise<SandboxCommandResult> {
+  let stdout = "", stderr = "", exitCode = 0, exited = false;
+  const reader = body.getReader(), decoder = new TextDecoder();
+  let buf = "";
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buf += decoder.decode(value, { stream: true });
+    const lines = buf.replace(/\r\n/g, "\n").split("\n");
+    buf = lines.pop() ?? "";
+    for (const line of lines) {
+      if (!line.startsWith("data: ")) continue;
+      let event: SseEvent;
+      try { event = JSON.parse(line.slice(6)) as SseEvent; }
+      catch (err) { throw new Error(`Malformed sandbox exec event: ${err instanceof Error ? err.message : String(err)}`); }
+      if (event.type === "stdout")       { stdout += event.data ?? ""; opts?.onStdout?.(event.data ?? ""); }
+      else if (event.type === "stderr")  { stderr += event.data ?? ""; opts?.onStderr?.(event.data ?? ""); }
+      else if (event.type === "exit")    { exitCode = event.exitCode ?? 0; exited = true; }
+      else if (event.type === "error")   { throw new Error(`Sandbox exec error: ${event.data}`); }
+    }
+    // Stop reading as soon as the exit event is received — don't wait for stream close.
+    // QUIC tunnels can delay the stream-end signal even after all data has arrived.
+    if (exited) break;
+  }
+  if (!exited) throw new Error("Sandbox exec stream ended without an exit event");
+  return { exitCode, stdout, stderr };
+}