@agent-compose/sdk 0.8.4 → 0.8.6

package/src/runtimes/opencode.ts

@@ -1,25 +1,143 @@
 /**
  * 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.
+ * Two transports share this spec:
+ *   - the SDK runner (createCliAgentRuntime) speaks ACP: `opencode acp` is a
+ *     protocolVersion-1 ACP server (verified live on E2B, 2026-06-30) on a
+ *     provider with a duplex-stdin command primitive, and the JSONL members
+ *     below are its version-mismatch fallback;
+ *   - the platform's cloud lane (server turn-workflow/tailer.ts) never speaks
+ *     ACP: it launches `buildCommand` detached, tails the CLI's stdout file
+ *     line by line, JSON-parses every line and maps it through `mapEvent`.
+ *     The dispatch constitution's `fast` lane (google/gemini-3.7-flash on
+ *     opencode) runs there, so the JSONL members are the LIVE path for it.
  *
- * 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.
+ * The 2026-10-02 fast-lane failure (prod: 5 of 5 opencode turns settled
+ * `harness_no_output` over ten days) — `opencode run` without `--format json`
+ * prints the reply as human-formatted prose and its tool narration on stderr,
+ * so the tailer parsed zero JSON lines and the turn settled empty while the
+ * work itself had completed (reproduced locally, 2026-10-03). `--format json`
+ * makes `run` print one JSON event per line — `{type, timestamp, sessionID,
+ * part}` for step_start / step_finish / text / reasoning / tool_use, and
+ * `{type: "error", timestamp, sessionID, error}` for a session error
+ * (packages/opencode/src/cli/cmd/run.ts, v1.18.34: text and reasoning parts
+ * fire once, when the part's `time.end` lands; a tool part fires once, at
+ * `state.status` completed or error). Captured real streams:
+ * `__fixtures__/jsonl/opencode`.
+ *
+ * Auth + model: the platform routes opencode through its gateway as the
+ * custom provider `gw` — server session-runtime-config.ts writes
+ * ~/.config/opencode/opencode.json with the gateway base URL and
+ * `{env:OPENROUTER_API_KEY}`, and the model flag is `gw/openrouter/<provider>/
+ * <model>`. Stand-alone SDK use sets OPENROUTER_API_KEY (a factory/workflow
+ * secret) and an `openrouter/<provider>/<model>` id.
+ *
+ * Resume (owner, 2026-10-03: "resume like other workers"): every event
+ * carries the CLI's `sessionID`; `extractSessionId` reads it, the tailer
+ * records it, and a follow-up turn on the same machine launches `run
+ * --session <id>` with only the new messages (renderCloudPrompt). The store
+ * is SQLite under the guest's ~/.local/share/opencode, so a resume target
+ * can be gone (a stale binding, a wiped store): `run --session` then exits 1
+ * with `Error: Session not found` on stderr and nothing on stdout — the
+ * classifier's `resume_target_missing` (turn-failure-class.ts), which the
+ * cloud turn workflow heals by dropping the binding and relaunching the turn
+ * fresh. Verified live on 1.18.34 (fixtures `resume-turn-1/2.jsonl`,
+ * `session-not-found.stderr`).
  */
 
 import type { AgentMessage } from "../index.js";
+import type { AgentMessagePlan } from "../types/protocol.js";
+import { OPENCODE_CLI_VERSION } from "../sandbox/baked-clis.js";
+import { formatError } from "../utils/errors.js";
 import { createCliAgentRuntime, shellQuote, type CliAgentSpec } from "./_cli-agent.js";
 
 function now(): string { return new Date().toISOString(); }
 
+const asRecord = (v: unknown): Record<string, unknown> | null =>
+  typeof v === "object" && v !== null && !Array.isArray(v) ? v as Record<string, unknown> : null;
+
+const asCount = (v: unknown): number => (typeof v === "number" && Number.isFinite(v) ? v : 0);
+
+/** The text of an opencode session error — `{name, data: {message, statusCode?}}`
+ *  (ProviderAuthError / APIError / UnknownError / … in the opencode SDK
+ *  types): name and HTTP status first so the settle's classifier reads the
+ *  cause, then the provider's own words. Captured shapes: a 401 from the
+ *  gateway is `APIError` with statusCode 401; an unknown model id is
+ *  `UnknownError` with the gateway's "Unexpected server error". */
+export function opencodeErrorText(error: unknown): string {
+  const e = asRecord(error);
+  if (!e) return formatError(error);
+  const data = asRecord(e.data);
+  const name = typeof e.name === "string" && e.name.trim().length > 0 ? e.name.trim() : "";
+  const message = typeof data?.message === "string" ? data.message.trim() : "";
+  const status = typeof data?.statusCode === "number" ? ` (HTTP ${data.statusCode})` : "";
+  if (message) return name ? `${name}${status}: ${message}` : `${message}${status}`;
+  if (name) return `${name}${status}`;
+  return formatError(error);
+}
+
+/** opencode's `todowrite` input (`{todos: [{content, status, priority}]}`),
+ *  as the platform's whole-plan message — the codex `todo_list` idiom. A
+ *  cancelled todo is off the plan; the ACP plan has no such state. */
+function opencodePlanMessages(input: Record<string, unknown>, timestamp: string): AgentMessage[] {
+  const todos = Array.isArray(input.todos) ? input.todos : [];
+  const entries: AgentMessagePlan["entries"] = [];
+  for (const todo of todos) {
+    const t = asRecord(todo);
+    if (!t || typeof t.content !== "string" || t.content.trim().length === 0) continue;
+    const status = t.status === "completed" || t.status === "in_progress" || t.status === "pending" ? t.status : null;
+    if (status === null) continue;
+    const priority = t.priority === "high" || t.priority === "medium" || t.priority === "low" ? t.priority : undefined;
+    entries.push({ content: t.content.trim(), status, ...(priority ? { priority } : {}) });
+  }
+  return entries.length > 0 ? [{ type: "plan", entries, timestamp }] : [];
+}
+
+/** One `tool_use` event: the part's `state` is the whole call — input, and
+ *  the output (completed) or the error text (error). Both land in one
+ *  event, so the tool_use/tool_result pair is emitted together; a pending or
+ *  running state (not emitted by 1.18.34's `run`, kept for a later CLI) is
+ *  skipped so the pair is never duplicated. */
+function opencodeToolMessages(part: Record<string, unknown>, timestamp: string): AgentMessage[] {
+  const state = asRecord(part.state);
+  if (!state || (state.status !== "completed" && state.status !== "error")) return [];
+  const tool = typeof part.tool === "string" && part.tool.length > 0 ? part.tool : "tool";
+  const id = typeof part.callID === "string" && part.callID.length > 0 ? part.callID : String(part.id ?? "");
+  const input = asRecord(state.input) ?? {};
+  if (tool === "todowrite") return opencodePlanMessages(input, timestamp);
+  const result: AgentMessage = state.status === "error"
+    ? { type: "tool_result", toolUseId: id, output: typeof state.error === "string" ? state.error : "tool error", isError: true, timestamp }
+    : { type: "tool_result", toolUseId: id, output: typeof state.output === "string" ? state.output : "", isError: false, timestamp };
+  return [{ type: "tool_use", toolName: tool, toolInput: input, toolUseId: id, timestamp }, result];
+}
+
+/** One `step_finish` event: opencode reports tokens per MODEL CALL
+ *  (`tokens: {input, output, reasoning, cache: {read, write}}`; `input`
+ *  excludes the cached prefix, `reasoning` is separate from `output`) and
+ *  never a turn total, so each step rides the live counter as one call —
+ *  call_start with the input-side classes, call_delta with the call's
+ *  output (reasoning folded in, the platform's "inside outputTokens"
+ *  convention). The counter's running totals are the turn's durable stamp. */
+function opencodeStepUsage(part: Record<string, unknown>, timestamp: string): AgentMessage[] {
+  const tokens = asRecord(part.tokens);
+  if (!tokens) return [];
+  const cache = asRecord(tokens.cache);
+  return [
+    {
+      type: "usage_delta", boundary: "call_start",
+      inputTokens: asCount(tokens.input), outputTokens: 0,
+      cacheReadTokens: asCount(cache?.read), cacheCreationTokens: asCount(cache?.write),
+      timestamp,
+    },
+    {
+      type: "usage_delta", boundary: "call_delta",
+      inputTokens: 0, outputTokens: asCount(tokens.output) + asCount(tokens.reasoning),
+      cacheReadTokens: 0, cacheCreationTokens: 0,
+      timestamp,
+    },
+  ];
+}
+
 export const opencodeSpec: CliAgentSpec = {
   kind: "opencode",
   // OpenRouter is the gateway: opencode reads OPENROUTER_API_KEY from the env
@@ -27,25 +145,76 @@ export const opencodeSpec: CliAgentSpec = {
   authEnv: "OPENROUTER_API_KEY",
   bin: "opencode",
   defaultModel: "openrouter/z-ai/glm-5.2",
-  // ACP-mode invocation — `opencode acp` is a protocolVersion-1 ACP server, so
-  // the runner delegates the whole wire protocol to AcpClientPeer. The model is
-  // resolved from opencode's config / the `--model` it was started with; the
-  // run provisioning writes the OpenRouter default so ACP turns use GLM-5.2.
+  // ACP-mode invocation (the SDK runner's path — see the header).
   acp: { command: "opencode", args: ["acp"] },
-  // Global npm install; symlink onto PATH only if the global bin dir isn't
-  // already there (so a non-login `sh -c` can find it).
-  install: 'sudo npm install -g opencode-ai && (command -v opencode >/dev/null 2>&1 || sudo ln -sf "$(npm prefix -g)/bin/opencode" /usr/local/bin/opencode)',
-  // ── JSONL fallback (only reached if the ACP handshake negotiates a non-1
-  //    version; opencode is v1, so this is vestigial). `opencode run` prints
-  //    human-formatted text, so we capture the prompt round-trip as one message.
+  // One live writer per session: the store is one SQLite database, and a
+  // superseded turn's process left alive beside its successor's `--session`
+  // resume would interleave two writers in one thread (codex's flock makes
+  // the same rule explicit). A supersede kills the predecessor first
+  // (server runner-kill.ts teardownDisposition).
+  exclusiveSessionWriter: true,
+  // Pinned to the SDK's OPENCODE_CLI_VERSION: the version the image bakes
+  // (infra/e2b-template parts.ts OPENCODE_INSTALL) and the one every flag
+  // and event shape in this file was verified against. Global npm install;
+  // symlink onto PATH only if the global bin dir isn't already there (so a
+  // non-login `sh -c` can find it).
+  install: `sudo npm install -g opencode-ai@${OPENCODE_CLI_VERSION} && (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: () => undefined,
+  // One turn: `opencode run --format json --auto --thinking [--model m] < prompt`.
+  //   --format json  one JSON event per stdout line (the header's whole point).
+  //   --auto         approve the permission asks no rule denies. `run` is
+  //                  non-interactive: without it every ask — opencode's
+  //                  defaults ask for a path outside the project directory
+  //                  and for a tool repeating itself — is auto-REJECTED and
+  //                  the model works on blind. The platform's sandbox is the
+  //                  isolation boundary, the same reasoning as codex's
+  //                  --dangerously-bypass-approvals-and-sandbox; explicit
+  //                  `deny` rules still hold.
+  //   --thinking     emit reasoning parts (the json format emits them only
+  //                  under this flag); they arrive whole, as thinking blocks.
+  //   --session id   continue the recorded session (a follow-up turn on the
+  //                  same machine); absent on a fresh thread.
+  //   < prompt       the message on stdin — `run` reads piped stdin as the
+  //                  message when no positional text is given (verified
+  //                  1.18.34, with and without --session), the idiom codex
+  //                  uses. A `"$(cat prompt)"` argument would meet Linux's
+  //                  128 KiB single-argument limit on a long rendered prompt.
+  buildCommand: ({ promptPath, sessionId, model, cwd }) => {
+    const cd = cwd ? `cd ${shellQuote(cwd)} && ` : "";
+    const flags = [
+      "--format json", "--auto", "--thinking",
+      ...(sessionId ? [`--session ${shellQuote(sessionId)}`] : []),
+      ...(model ? [`--model ${shellQuote(model)}`] : []),
+    ].join(" ");
+    return `${cd}opencode run ${flags} < ${shellQuote(promptPath)}`;
+  },
+  // The resume identity: every `run --format json` event carries the CLI's
+  // `sessionID` (the same id on every line of a turn, and on every line of
+  // a `--session` continuation of it).
+  extractSessionId: (p) =>
+    typeof p.sessionID === "string" && p.sessionID.length > 0 ? p.sessionID : 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 }] : [];
+    const part = asRecord(p.part);
+    switch (p.type) {
+      case "text": {
+        const text = typeof part?.text === "string" ? part.text : "";
+        return text.trim().length > 0 ? [{ type: "text", text, timestamp: ts }] : [];
+      }
+      case "reasoning": {
+        const text = typeof part?.text === "string" ? part.text : "";
+        return text.trim().length > 0 ? [{ type: "thinking", text, timestamp: ts }] : [];
+      }
+      case "tool_use":
+        return part ? opencodeToolMessages(part, ts) : [];
+      case "step_finish":
+        return part ? opencodeStepUsage(part, ts) : [];
+      case "error":
+        return [{ type: "error", text: opencodeErrorText(p.error), timestamp: ts }];
+      default:
+        // step_start, and whatever a later opencode adds: lifecycle, no content.
+        return [];
+    }
   },
 };
 

package/src/sandbox/baked-clis.ts

@@ -0,0 +1,86 @@
+/**
+ * Harness CLIs the E2B session image bakes, pinned: the SINGLE SOURCE for
+ * each version. `infra/e2b-template/parts.ts` installs exactly this version
+ * into every `agent-env-<size>`, and the runtime spec's on-demand install
+ * fetches the same one on a machine whose image predates the bake. It lives
+ * under `sdk/src/sandbox/` so a bump rebuilds the images: sandbox-images.yml
+ * watches this directory.
+ *
+ * The ruling (owner, 2026-10-02): workers run the NEWEST CLIs, baked and
+ * pinned so every machine runs the same tested version, with no per-machine
+ * self-update — prod workers were running claude 2.1.287 on an image that
+ * baked 2.1.283, because the CLI updated itself inside the machines. Each
+ * release bumps the pins here; the two constants below turn the CLIs' own
+ * updaters off wherever the platform runs them.
+ */
+
+/** Anthropic's claude CLI (the native installer's versioned binary, copied
+ *  to /usr/local/bin/claude). The floor is the worker model: Opus 5.5 needs
+ *  2.1.280 or newer. 2.1.287 is current on npm (2026-10-02) and is the build
+ *  the rtk `--settings` hook, the `[1m]` window behind a gateway base URL and
+ *  the prompt-cache TTL env were verified against. */
+export const CLAUDE_CODE_VERSION = "2.1.287";
+
+/** OpenAI's codex CLI (`@openai/codex`). 0.160.0 is current on npm
+ *  (2026-10-02); codex.ts's event mapping (command_execution / agent_message
+ *  / turn.completed usage) and the hook trust-hash recipe were re-verified
+ *  live against it, and its plan-tool and hook sources are byte-identical to
+ *  rust-v0.159.2, where the `todo_list` shape was captured. Unbaked, every
+ *  session's first codex turn waited ~13 s in prod for the npm install
+ *  before its launch (2026-09-30), and each machine got whichever version
+ *  npm served that minute. Bump deliberately. */
+export const CODEX_CLI_VERSION = "0.160.0";
+
+/** sst's opencode CLI (`opencode-ai`) — the harness behind the dispatch
+ *  constitution's `fast` lane. 1.18.34 is current on npm (2026-09-30) and
+ *  is the build the cloud lane (runtimes/opencode.ts) was verified against,
+ *  live through the gateway on google/gemini-3.7-flash (2026-10-03): the
+ *  `run --format json` event shapes (runtimes/__fixtures__/jsonl/opencode),
+ *  the prompt on stdin, and the `--auto` permission flag — which 1.15.13
+ *  still spelled `--dangerously-skip-permissions`, the kind of flag drift
+ *  an unpinned install ships straight into prod. Until this pin the spec
+ *  installed whatever npm served that minute, on each machine's first
+ *  opencode turn. Bump deliberately. */
+export const OPENCODE_CLI_VERSION = "1.18.34";
+
+/** rtk (rtk-ai/rtk), the shell-output compressor behind the Bash PreToolUse
+ *  hook every claude and codex session carries (runtimes/claude-code.ts
+ *  RTK_BASH_HOOK_COMMAND, runtimes/codex.ts RTK_CODEX_HOOK_COMMAND). The
+ *  floor is `rtk hook codex`, added in 0.50.0 (2026-09-24); 0.51.0 is the
+ *  current release (2026-10-02) and the build both hooks' exact smoke
+ *  payloads were run against (2026-10-04). Until this pin the image ran
+ *  rtk's installer unpinned, so it baked whatever release the installer
+ *  served on the day its layer was last built — and E2B served that layer
+ *  from cache for six weeks: every 2026-10 image carried rtk 0.45.0, whose
+ *  `rtk hook` had no `codex`, so the codex hook exited 2 with clap's usage
+ *  on stderr and Codex blocked every shell command of every codex session
+ *  from the hook's 2026-10-03 deploy on. The image recipe downloads exactly
+ *  this release (infra parts.ts RTK_INSTALL, sha256-verified); its verify
+ *  layer and the smoke gate assert the baked version. Bump deliberately,
+ *  re-running both hooks' payloads against the new build. */
+export const RTK_VERSION = "0.51.0";
+
+/** Env that turns the claude CLI's updater off — the admin-grade switch
+ *  (verified in the 2.1.287 binary): it disables the background self-update
+ *  AND `claude update`, so a machine runs the baked version until the image
+ *  is rebuilt; `DISABLE_AUTOUPDATER` would stop only the background updater.
+ *  The `autoUpdates: false` config does nothing for the native installer.
+ *  Sessions get it from the session env file, runs from the runner env. */
+export const CLAUDE_CODE_NO_SELF_UPDATE_ENV: Readonly<Record<string, string>> = {
+  DISABLE_UPDATES: "1",
+};
+
+/** The config.toml line that turns codex's startup update check off
+ *  (`check_for_update_on_startup`, codex-rs config: "set to false only if
+ *  your Codex updates are centrally managed" — they are: the image). A
+ *  top-level key, so it must come before any `[table]` in the file.
+ *  Accepted by 0.160.0 under `--strict-config` (live, 2026-10-02). */
+export const CODEX_NO_SELF_UPDATE_CONFIG_LINE = "check_for_update_on_startup = false\n";
+
+/** The opencode.json keys that turn opencode's updater off (`autoupdate`
+ *  takes true | false | "notify" in 1.18.34's config schema). Spread into
+ *  the session config the server writes (session-runtime-config.ts), so a
+ *  machine runs the baked version until the image is rebuilt. */
+export const OPENCODE_NO_SELF_UPDATE_CONFIG: Readonly<Record<string, boolean>> = {
+  autoupdate: false,
+};

package/src/sandbox/devbox.ts

@@ -5,13 +5,13 @@
  * 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).
+ * provision a machine (exactly how `e2bAgentEnvTemplate` 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.
+ * runs boot the clean per-size `agent-env-<size>` template (the same image
+ * sessions boot) so reproducibility never inherits hand-configured drift.
  */
 
 /** Stable E2B template ALIAS for the per-member desktop machine. Baked by

package/src/sandbox/exec-stream.ts

@@ -1,6 +1,5 @@
 /**
- * SSE exec-stream parser — used by the agent sandbox broker clients in
- * runner.ts to consume a streamed command execution.
+ * SSE exec-stream parser — consumes a streamed command execution.
  */
 
 import type { SandboxCommandResult } from "../types/sandbox.js";

package/src/sandbox/network-policy.ts

@@ -48,6 +48,37 @@ export type SandboxNetworkPolicy =
       subnets?: SandboxNetworkSubnetPolicy;
     };
 
+/** Every IPv4 destination, as a `subnets.allow` entry — the lever that
+ *  admits raw TCP. A domain allow (`"*"` included) is matched by TLS SNI /
+ *  HTTP Host, so it cannot carry an ssh, database or other non-HTTP
+ *  connection. */
+const ALL_IPV4 = "0.0.0.0/0";
+
+/**
+ * OPEN egress save the given CIDRs: every domain and every IPv4 destination,
+ * with `deny` applied ahead of both — "allow-all" spelled out so it can carry
+ * a deny (the server stamps its metadata-endpoint deny on every open policy).
+ * Vercel enforces this shape natively (its subnet denies take precedence
+ * over allowed domains and CIDRs). E2B lets an allow entry win over a deny,
+ * so `toE2bNetwork` recognizes the shape and emits a bare deny list instead.
+ */
+export function openEgressExcept(deny: readonly string[]): SandboxNetworkPolicy {
+  return { allow: { "*": [] }, subnets: { allow: [ALL_IPV4], deny: [...deny] } };
+}
+
+/** The deny list of an `openEgressExcept` policy — the `"*"` wildcard alone,
+ *  with no per-host rules, plus every IPv4 destination — or null for any
+ *  other policy. */
+function openEgressDeny(policy: SandboxNetworkPolicy): string[] | null {
+  if (typeof policy === "string" || !policy.allow) return null;
+  const hosts = Array.isArray(policy.allow) ? policy.allow : Object.keys(policy.allow);
+  const ruled = !Array.isArray(policy.allow) && Object.values(policy.allow).some((rules) => rules.length > 0);
+  const subnetAllow = policy.subnets?.allow ?? [];
+  if (ruled || hosts.length !== 1 || hosts[0] !== "*") return null;
+  if (subnetAllow.length !== 1 || subnetAllow[0] !== ALL_IPV4) return null;
+  return [...(policy.subnets?.deny ?? [])];
+}
+
 /** Matches a path containing a dot-dot segment — literal (`/../`) or
  *  percent-encoded (`%2e%2e`, `%2f` boundaries). `DOT_SEGMENT_PATH_RE2` is
  *  the RE2 form handed to Vercel's matcher: wrapped in `.*` so it behaves
@@ -121,17 +152,26 @@ export function toVercelNetworkPolicy(policy: SandboxNetworkPolicy): VercelNetwo
  * (`SandboxNetworkOpts`) — the E2B analogue of `toVercelNetworkPolicy`.
  *
  *   - `allowOut`: the set of allowed egress targets — every host named in
- *     `allow` PLUS every CIDR in `subnets.allow`. The Archil raw-TCP
- *     data-plane CIDRs ride here as FIRST-CLASS allow entries (E2B has no
- *     root-exemption to lean on, unlike the old in-VM iptables model).
+ *     `allow` PLUS every CIDR in `subnets.allow`.
  *   - `denyOut`: the all-traffic sentinel (`0.0.0.0/0`) so the policy is
- *     DEFAULT-DENY — only `allowOut` targets pass. E2B applies allow before
- *     deny, so a host in both lists is allowed.
+ *     DEFAULT-DENY — only `allowOut` targets pass — plus every CIDR in
+ *     `subnets.deny`. E2B applies allow before deny, so a host in both lists
+ *     is allowed: a `subnets.deny` CIDR bites on E2B only where no allow
+ *     entry covers the destination (E2B's documented precedence; Vercel
+ *     applies its `subnets.deny` ahead of every allow). Whether E2B's `"*"`
+ *     domain wildcard also covers a request addressed to a bare IP is E2B's
+ *     call, so a deny under a `"*"`-plus-rules policy is not relied on here.
  *   - `rules`: per-host header injection. For each host carrying transform(s),
  *     emit one rule per transform with `{ transform: { headers } }`. A host
  *     with a rule MUST also be in `allowOut` (registering a rule does not
  *     grant egress on its own — E2B's API requires the host in `allowOut`).
  *
+ * OPEN egress save some CIDRs (`openEgressExcept`) is the one shape E2B's
+ * allow precedence cannot express as allow + deny lists — its "every IPv4
+ * destination" allow would win over the deny. It becomes a bare `denyOut`
+ * of those CIDRs: no allow list and no domain filtering (so raw TCP keeps
+ * flowing, as under "allow-all"), only the denied destinations refused.
+ *
  * BEHAVIOURAL DIVERGENCE FROM iron-proxy / Vercel — path/method gating is NOT
  * available on E2B native rules. An `SandboxNetworkRule` carries only a
  * `transform` (header injection); there is no method/path matcher. So our
@@ -147,6 +187,8 @@ export function toVercelNetworkPolicy(policy: SandboxNetworkPolicy): VercelNetwo
 export function toE2bNetwork(policy: SandboxNetworkPolicy): E2bNetworkOpts {
   if (policy === "allow-all") return {};
   if (policy === "deny-all") return { denyOut: ({ allTraffic }) => [allTraffic] };
+  const openDeny = openEgressDeny(policy);
+  if (openDeny) return openDeny.length > 0 ? { denyOut: openDeny } : {};
 
   // List-form allow (no transforms): allowlist the hosts, default-deny the rest.
   const allowHosts: string[] = Array.isArray(policy.allow)
@@ -155,9 +197,11 @@ export function toE2bNetwork(policy: SandboxNetworkPolicy): E2bNetworkOpts {
   const subnetAllow = policy.subnets?.allow ?? [];
   const allowOut = [...new Set([...allowHosts, ...subnetAllow])];
 
+  const subnetDeny = policy.subnets?.deny ?? [];
   const network: E2bNetworkOpts = {
-    // Default-deny: only `allowOut` passes (E2B applies allow before deny).
-    denyOut: ({ allTraffic }) => [allTraffic],
+    // Default-deny: only `allowOut` passes (E2B applies allow before deny),
+    // with the policy's own denied CIDRs stated alongside.
+    denyOut: ({ allTraffic }) => [allTraffic, ...subnetDeny],
   };
   if (allowOut.length > 0) network.allowOut = allowOut;
 

package/src/sandbox/providers/e2b.ts

@@ -5,7 +5,7 @@
  * registry entry.
  */
 
-import { Sandbox } from "e2b";
+import { Sandbox, Template } from "e2b";
 import type { CommandHandle } from "e2b";
 import type { Sandbox as Desktop } from "@e2b/desktop";
 import pRetry from "p-retry";
@@ -13,7 +13,7 @@ import type {
   SandboxProvider, SandboxCommandRunOptions, SandboxBackgroundProcess, SandboxPtyHandle,
 } from "../../types/sandbox.js";
 import { toE2bNetwork } from "../network-policy.js";
-import { DEFAULT_SANDBOX_SIZE, e2bBaseTemplate, isE2bSupportedSize } from "../sizes.js";
+import { DEFAULT_SANDBOX_SIZE, e2bAgentEnvTemplate, isE2bSupportedSize } from "../sizes.js";
 import { AGENT_COMPOSE_TAG } from "../provider-def.js";
 import type { OwnedSandbox, SandboxProviderDef } from "../provider-def.js";
 
@@ -27,8 +27,8 @@ export function makeSandboxProvider(sb: Sandbox | Desktop): SandboxProvider {
         // SandboxProvider exposes `sudo: true`; E2B has no `sudo` flag — it runs
         // a command as root via `user: "root"` (Vercel/local map sudo to their own
         // mechanism). Passing `sudo` straight through means E2B ignores it and runs
-        // as the non-root default user, so a root-only command (e.g. `archil mount`,
-        // which REQUIRES root) silently fails. Translate sudo → user:"root".
+        // as the non-root default user, so a root-only command (e.g. `agentc files
+        // mount`, which REQUIRES root) silently fails. Translate sudo → user:"root".
         const { sudo, ...rest } = (opts ?? {}) as { sudo?: boolean } & Record<string, unknown>;
         const runOpts = {
           ...rest,
@@ -40,7 +40,7 @@ export function makeSandboxProvider(sb: Sandbox | Desktop): SandboxProvider {
         };
         // E2B's commands.run THROWS CommandExitError on a non-zero exit, but the
         // SandboxProvider contract (and the Vercel provider) RETURNS a result with
-        // `exitCode` so callers can branch on it (e.g. the archil-mount degrade
+        // `exitCode` so callers can branch on it (e.g. the factory-drive mount
         // path inspects res.exitCode/res.stderr; a thrown bare "exit status N"
         // loses the command's stderr). Normalize the throw back into a result;
         // only a genuine failure (spawn error, timeout, dead sandbox — no numeric
@@ -297,18 +297,24 @@ export const e2bProviderDef: SandboxProviderDef = {
   // E2B has no create-time resource knob (specs are baked into the
   // template/snapshot), so honouring `size` on E2B = picking a PRE-SIZED
   // template, not passing the field through. We resolve the boot template
-  // from `size` below (`e2bBaseTemplate(size)`) when the caller gave no
+  // from `size` below (`e2bAgentEnvTemplate(size)`) when the caller gave no
   // explicit template/bootFrom; the field itself is never forwarded to E2B.
   create: async ({ template, timeoutMs, networkPolicy, size, ...rest }) => {
     // `template` is an E2B template id/alias, a snapshot id (a valid create
     // source that persists beyond its origin sandbox — bootFrom parity), or
-    // absent. When absent we pick the SIZE-MATCHED platform base alias
-    // (`agent-compose-base-<size>`) so `resources.size` gives the same
-    // machine spec on E2B as on Vercel — the cross-provider parity this whole
-    // change exists for. Only when no size is resolvable at all do we fall
-    // back to E2B_DEFAULT_TEMPLATE if set (a prebuilt base — e.g. one with the claude CLI
-    // + chromium baked in and more RAM than the stock 482MB base), the
-    // per-deployment analogue of Vercel's node24; else E2B's stock base.
+    // absent. When absent we pick the SIZE-MATCHED platform agent-env alias
+    // (`agent-env-<size>`) — the SAME image every cloud session boots
+    // (server/src/sandbox/persistent.ts resolves the identical
+    // `e2bAgentEnvTemplate(size)`), so a template-less workflow run gets the
+    // full session toolchain (claude runtime, dev toolbelt, agentc, fsgw
+    // client) instead of a thinner image. One seam, both lanes: the
+    // session/run divergence that caused fleet-wide `exit 127`s (missing
+    // harness CLIs, fixed by on-demand install in v0.10.73) is structurally
+    // gone — there is no separate run-lane template to drift. The per-size
+    // aliasing also keeps `resources.size` giving the same machine spec on
+    // E2B as on Vercel (cross-provider parity). Only when no size is
+    // resolvable at all do we fall back to E2B_DEFAULT_TEMPLATE if set (the
+    // per-deployment analogue of Vercel's node24); else E2B's stock base.
     // Self-provisioning runtimes (claude/codex/amp via bootFrom:"reuse") install
     // their CLI on the base and cache it in the captured snapshot, so a
     // template-less first run boots, installs, snapshots. Clamp the lifetime to
@@ -346,18 +352,19 @@ export const e2bProviderDef: SandboxProviderDef = {
     };
     // Boot template resolution, in priority order:
     //   1. explicit `template`/bootFrom (a pinned snapshot or alias),
-    //   2. else the SIZE-MATCHED base alias `agent-compose-base-<size>`
-    //      (`size` resolved to DEFAULT_SANDBOX_SIZE when unset) — this is the
-    //      cross-provider parity path,
+    //   2. else the SIZE-MATCHED agent-env alias `agent-env-<size>` — the
+    //      session-identical image (`size` resolved to DEFAULT_SANDBOX_SIZE
+    //      when unset). NEVER the legacy `agent-compose-base-<size>` — that
+    //      family remains a valid EXPLICIT bootFrom target only,
     //   3. else E2B_DEFAULT_TEMPLATE as an ultimate per-deployment fallback,
     //   4. else E2B's stock base.
-    // `32vcpu-64gb` has no base-<size> template (Pro caps ~8 vCPU); the
+    // `32vcpu-64gb` has no per-size template (Pro caps ~8 vCPU); the
     // register + invoke guards reject it before a run reaches here, so we
-    // never synthesize a non-existent `agent-compose-base-32vcpu-64gb` alias.
+    // never synthesize a non-existent `agent-env-32vcpu-64gb` alias.
     const resolvedSize = size ?? DEFAULT_SANDBOX_SIZE;
     const tmpl =
       template ??
-      (isE2bSupportedSize(resolvedSize) ? e2bBaseTemplate(resolvedSize) : undefined) ??
+      (isE2bSupportedSize(resolvedSize) ? e2bAgentEnvTemplate(resolvedSize) : undefined) ??
       process.env.E2B_DEFAULT_TEMPLATE;
     return makeE2bSandboxProvider(
       await (tmpl ? Sandbox.create(tmpl, sandboxOpts) : Sandbox.create(sandboxOpts)),
@@ -383,4 +390,41 @@ export const e2bProviderDef: SandboxProviderDef = {
     // E2B snapshots are team-scoped; delete by id. Best-effort like Vercel's.
     await Sandbox.deleteSnapshot(snapshotId, { apiKey: env.E2B_API_KEY });
   },
+  snapshotExists: async (snapshotId, env) => {
+    // Existence probe for a CREATE SOURCE (the `snapshotResolves` contract:
+    // `true` = resolves, `false` = the provider definitively says it does not
+    // exist, anything indeterminate PROPAGATES — never reported as missing).
+    //
+    // e2b 2.30.5 has no GET-snapshot-by-id, so this composes the two
+    // documented lookups, cheapest first:
+    //   1. `Template.exists` — ONE round-trip to the template-existence
+    //      endpoint (`GET /templates/aliases/{alias}`), with DOCUMENTED
+    //      not-found semantics: 404 → false, 403 → exists but owned by
+    //      another team → true (the SDK's own mapping). Snapshots are
+    //      templates provider-side, and this probe also resolves the
+    //      `agent-env-*` template ALIASES that E2B-pinned default templates
+    //      register as their bootFrom — boot-time platform validation
+    //      (validatePlatformSnapshots) probes those through this same seam,
+    //      so a snapshots-only lookup would falsely alert "unresolvable" on
+    //      every alias.
+    //   2. A paged scan of the team's snapshot list (`Sandbox.listSnapshots`)
+    //      — authoritative for `createSnapshot` artifacts whatever their id
+    //      shape, reached only when the template probe answered not-found.
+    //      Bounded by the team's snapshot count (session rings are GC'd to a
+    //      fixed retain depth), and this is rare-path code: machine-loss
+    //      recovery and boot validation, never a hot loop.
+    // `false` therefore means BOTH documented lookups answered not-found.
+    // (`Sandbox.listSnapshots({ sandboxId })` — source-filtered — was
+    // rejected as the primary: callers hold only the snapshot id, and a
+    // filtered miss would still need the full scan before "absent" is
+    // honest.) Transport/auth faults from either call throw — indeterminate.
+    const opts = { apiKey: env.E2B_API_KEY };
+    if (await Template.exists(snapshotId, opts)) return true;
+    const paginator = Sandbox.listSnapshots(opts);
+    while (paginator.hasNext) {
+      const items = await pRetry(() => paginator.nextItems(), { retries: 3, minTimeout: 500, factor: 2 });
+      if (items.some((s) => s.snapshotId === snapshotId || s.names.includes(snapshotId))) return true;
+    }
+    return false;
+  },
 };

package/src/sandbox/providers/vercel.ts

@@ -117,8 +117,8 @@ function makeVercelSandboxProvider(sb: VercelSandbox, globalEnvs?: Record<string
           return { exitCode: finished.exitCode, stdout, stderr };
         };
         // `timeoutMs` MUST be authoritative. The AbortSignal alone is not: a
-        // command that RUNS but emits nothing (e.g. a wedged `archil checkout`
-        // on a blocked data plane) leaves `logs()`/`wait()` pending and the
+        // command that RUNS but emits nothing (e.g. a mount wedged on a
+        // blocked data plane) leaves `logs()`/`wait()` pending and the
         // abort never interrupts the await — the call hangs for the activity's
         // whole multi-hour ceiling. Race a hard client-side deadline so a hung
         // command fails fast and the caller's degrade/retry policy takes over.
@@ -164,9 +164,9 @@ function makeVercelSandboxProvider(sb: VercelSandbox, globalEnvs?: Record<string
         return buf.toString("utf8");
       },
     },
-    // Propagate errors — `killAllRunSandboxes` relies on kill failures being
-    // observable so it can leave `sandbox_id` set for `findOrphanedSandboxes`
-    // to retry on next boot. Swallowing here makes the orphan retry loop blind.
+    // Propagate errors — a failed kill must stay observable to its caller;
+    // the server's provider reconciler (`listOwned` + DB cross-ref) sweeps
+    // any sandbox that survives.
     //
     // kill must DESTROY: in @vercel/sandbox 2.x stop() only halts the VM — the
     // name-keyed sandbox record persists (reserving the name; commands against
@@ -260,7 +260,7 @@ export const vercelProviderDef: SandboxProviderDef = {
     // guarantees executor wins over metadata and survives the 5-tag cap.
     const tags = buildVercelTags(opts.metadata);
     // No explicit template/bootFrom → VERCEL_DEFAULT_SNAPSHOT if set (the
-    // platform agent-env base: claude, archil, rtk, bun, agentc CLI, the
+    // platform agent-env base: claude, rtk, bun, agentc CLI, the
     // SDK in /workspace/node_modules, /ac:* skills, AGENTS.md — built by
     // .agentc/environments/agent-env.ts), else raw node24. The E2B
     // analogue is E2B_DEFAULT_TEMPLATE (see providers/e2b.ts). Because