@agent-compose/sdk 0.8.5 → 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/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

@@ -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

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

package/src/sandbox.ts

@@ -5,8 +5,9 @@
  *   - `sandbox/network-policy.ts` — egress policy shape + per-provider translators
  *   - `sandbox/sizes.ts`          — machine sizes + E2B template aliases
  *   - `sandbox/devbox.ts`         — the ADR-0038 per-member desktop machine alias
+ *   - `sandbox/baked-clis.ts`     — harness CLI versions the session image bakes
  *   - `sandbox/provider-def.ts`   — provider contract, create opts, fleet tag
- *   - `sandbox/exec-stream.ts`    — SSE exec-stream parser (broker clients)
+ *   - `sandbox/exec-stream.ts`    — SSE exec-stream parser
  *   - `sandbox/providers/*`       — vercel / e2b / e2b-desktop / local providers
  *   - `sandbox/registry.ts`       — provider registry + fleet management
  */
@@ -19,7 +20,7 @@ export type {
   SandboxNetworkSubnetPolicy,
   SandboxNetworkPolicy,
 } from "./sandbox/network-policy.js";
-export { DOT_SEGMENT_PATH_RE2, toVercelNetworkPolicy, toE2bNetwork } from "./sandbox/network-policy.js";
+export { DOT_SEGMENT_PATH_RE2, openEgressExcept, toVercelNetworkPolicy, toE2bNetwork } from "./sandbox/network-policy.js";
 
 export type { SandboxSize } from "./sandbox/sizes.js";
 export {
@@ -48,6 +49,11 @@ export {
   e2bDevboxTemplateRef,
 } from "./sandbox/devbox.js";
 
+export {
+  CLAUDE_CODE_VERSION, CODEX_CLI_VERSION, OPENCODE_CLI_VERSION, RTK_VERSION,
+  CLAUDE_CODE_NO_SELF_UPDATE_ENV, CODEX_NO_SELF_UPDATE_CONFIG_LINE, OPENCODE_NO_SELF_UPDATE_CONFIG,
+} from "./sandbox/baked-clis.js";
+
 export { AGENT_COMPOSE_TAG } from "./sandbox/provider-def.js";
 export type { SandboxCreateOpts, OwnedSandbox } from "./sandbox/provider-def.js";
 

package/src/step-invocation/invoker.ts

@@ -526,12 +526,8 @@ export async function invokeStep<TOutput = unknown>(
 
   let result: { stdout: string; stderr: string; exitCode: number };
   try {
-    // Run the agent as ROOT (ADR-0019 follow-up). The factory drive (Archil)
-    // presents its S3-synced files root-owned and exposes no uid-mapped mount,
-    // so a non-root agent EACCESes on every shared file — the reason for the
-    // expensive boot-time `chmod -R` walk. As root the agent writes them
-    // directly: the walk disappears entirely. Egress is edge-enforced with NO
-    // root exemption (see sandbox.ts), so root is confined exactly like the
+    // Run the agent as ROOT (ADR-0019 follow-up). Egress is edge-enforced with
+    // NO root exemption (see sandbox.ts), so root is confined exactly like the
     // non-root user. `HOME=/root` so the spawned `claude` finds root's skills.
     //
     // Same pipeline pattern as `launchStep`: tee the runner's stdout to the

package/src/step-invocation/protocol.ts

@@ -38,12 +38,11 @@ export function stepPauseLinePrefix(token: string): string {
   return `${STEP_PAUSE_PREFIX}${token}:`;
 }
 
-/** Sandbox-side path where dispatch writes the compiled runner bundle.
- *  Both modes (full-mode `dispatch.ts` and step-mode `invokeStep`) spawn
- *  the runner from this path; single source of truth. */
+/** Sandbox-side path where the sandbox bootstrap writes the compiled runner
+ *  bundle; `invokeStep` spawns the runner from this path. */
 export const RUNNER_BUNDLE_PATH = "/tmp/runner.bundle.js";
 
-/** Command the invoker (and dispatch) spawns inside the sandbox. */
+/** Command the invoker spawns inside the sandbox. */
 export const RUNNER_COMMAND = `node ${RUNNER_BUNDLE_PATH}`;
 
 /** Names of the env vars the invoker stamps onto the runner subprocess.

package/src/step-invocation/server.ts

@@ -153,8 +153,8 @@ function scrubProtocolEnvs(): void {
  * from process.env so user code (including any workflow module imported
  * inside the handler) cannot read AC_STEP_RESULT_TOKEN — that keeps the
  * result channel uncorruptible by stdout output from anywhere in the
- * workflow's dep tree. RUN_ID remains available to match full-mode
- * runner behaviour.
+ * workflow's dep tree. RUN_ID remains available: SDK code inside the step
+ * (`agent()`, the client's parent-run link) reads it.
  */
 export async function serveStep<TInput, TOutput>(
   handler: StepHandler<TInput, TOutput>,