@agent-compose/sdk 0.6.0 → 0.8.0

package/src/runtimes/opencode.ts

@@ -0,0 +1,61 @@
+/**
+ * OpenCode CLI runtime — drives sst's `opencode` agentic CLI inside the sandbox.
+ * OpenCode speaks ACP natively (`opencode acp`, protocolVersion 1 — verified
+ * live on E2B), so the runner drives it over ACP; the JSONL members below are
+ * only the version-mismatch fallback (vestigial for a v1 agent).
+ *
+ * Auth + model via OpenRouter: set OPENROUTER_API_KEY (a factory/workflow
+ * secret) and use a model id like `openrouter/z-ai/glm-5.2`. The runtime
+ * installs the `opencode-ai` CLI on demand; pair with
+ * `snapshots: { bootFrom: "reuse" }` to install once and boot from the capture.
+ *
+ * Verified live on E2B (2026-06-30): `npm i -g opencode-ai` (v1.17.12);
+ * `opencode run --model openrouter/z-ai/glm-5.2` drove a GLM-5.2 turn through
+ * OpenRouter; `opencode acp` answered the ACP `initialize` handshake with
+ * protocolVersion 1.
+ */
+
+import type { AgentMessage } from "../index.js";
+import { createCliAgentRuntime, shellQuote, type CliAgentSpec } from "./_cli-agent.js";
+
+function now(): string { return new Date().toISOString(); }
+
+export const opencodeSpec: CliAgentSpec = {
+  kind: "opencode",
+  // OpenRouter is the gateway: opencode reads OPENROUTER_API_KEY from the env
+  // and serves any `openrouter/<provider>/<model>` id (e.g. z-ai/glm-5.2).
+  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: { 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.
+  promptPayload: (prompt) => prompt,
+  buildCommand: ({ promptPath, model, cwd }) =>
+    `${cwd ? `cd ${shellQuote(cwd)} && ` : ""}opencode run ${model ? `--model ${shellQuote(model)} ` : ""}"$(cat ${shellQuote(promptPath)})"`,
+  extractSessionId: () => undefined,
+  mapEvent: (p): AgentMessage[] => {
+    const ts = now();
+    const text = typeof p.text === "string" ? p.text : typeof p.content === "string" ? p.content : "";
+    return text ? [{ type: "text", text, timestamp: ts }] : [];
+  },
+};
+
+export interface OpencodeRuntimeConfig {
+  /** OpenRouter-prefixed model id (default `openrouter/z-ai/glm-5.2`). */
+  model?: string;
+}
+
+export function createOpencodeRuntime(config: OpencodeRuntimeConfig = {}) {
+  return createCliAgentRuntime(opencodeSpec, config.model ?? opencodeSpec.defaultModel);
+}
+
+export default createOpencodeRuntime();

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 };
+}

package/src/sandbox/network-policy.ts

@@ -0,0 +1,181 @@
+/**
+ * Sandbox egress network policy — ONE shape for every provider, plus the
+ * translators into each provider's native enforcement config
+ * (`toVercelNetworkPolicy` / `toE2bNetwork`) and the dot-segment path guards.
+ */
+
+import type { SandboxNetworkOpts as E2bNetworkOpts, SandboxNetworkRule as E2bNetworkRule } from "e2b";
+import type { ConnectorRequestRules } from "../types/workflow-metadata.js";
+// Type-only — erased at compile time, so @vercel/sandbox stays out of
+// runner.bundle.js (the provider's value imports are dynamic for the same reason).
+import type { NetworkPolicy as VercelNetworkPolicy, NetworkPolicyRule as VercelNetworkPolicyRule } from "@vercel/sandbox";
+
+/**
+ * Network policy for outbound HTTPS requests — ONE shape for every provider;
+ * only the enforcement point differs. When a sandbox makes a request matching
+ * a domain in `allow`, the egress layer injects the specified headers before
+ * forwarding — credentials never exist inside the VM. Both providers enforce
+ * this natively at the platform edge from the resolved policy passed at
+ * create: Vercel via its firewall (`requestRules` translate to native `match`
+ * rules), E2B via its native network firewall (`toE2bNetwork` →
+ * `allowOut`/`denyOut`/`rules`). See `toVercelNetworkPolicy` / `toE2bNetwork`.
+ */
+export interface SandboxNetworkHeaderTransform {
+  headers?: Record<string, string>;
+}
+
+export interface SandboxNetworkAllowRule {
+  transform?: SandboxNetworkHeaderTransform[];
+  /** Tier-2 request gate (method/path) — the transform only applies when the
+   *  request matches. Honoured on Vercel (translated to native `match` rules).
+   *  NOT honoured on E2B: its native rules carry only a `transform`, no
+   *  method/path matcher, so a brokered credential rides ALL requests to an
+   *  allowed host there (see `toE2bNetwork`). Present on connector-auth rules;
+   *  see `ConnectorRequestRules`. */
+  requestRules?: ConnectorRequestRules;
+}
+
+export interface SandboxNetworkSubnetPolicy {
+  allow?: string[];
+  deny?: string[];
+}
+
+export type SandboxNetworkPolicy =
+  | "allow-all"
+  | "deny-all"
+  | {
+      allow?: string[] | Record<string, SandboxNetworkAllowRule[]>;
+      subnets?: SandboxNetworkSubnetPolicy;
+    };
+
+/** 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
+ *  identically under search and full-match semantics (RE2 has no lookaround,
+ *  so the guard is a positive match on the traversal pattern, used as a
+ *  credential-stripping first rule). `DOT_SEGMENT_RE` is the local JS twin
+ *  used to validate DECLARED prefixes. */
+export const DOT_SEGMENT_PATH_RE2 = ".*(?:^|/|%2[fF])(?:\\.|%2[eE]){2}(?:/|%2[fF]|$).*";
+const DOT_SEGMENT_RE = /(?:^|\/|%2f)(?:\.|%2e){2}(?:\/|%2f|$)/i;
+
+/** A Tier-2 path gate decides where a brokered credential may ride, so a
+ *  malformed declared prefix is a config bug that must fail closed, not a
+ *  string we forward verbatim to a third-party matcher. */
+function assertSafePathPrefix(domain: string, prefix: string): void {
+  if (!prefix.startsWith("/") || DOT_SEGMENT_RE.test(prefix)) {
+    throw new Error(
+      `Invalid Tier-2 pathPrefix ${JSON.stringify(prefix)} for "${domain}": prefixes must start with "/" and contain no dot-segments`,
+    );
+  }
+}
+
+/**
+ * Translate our policy shape into Vercel's native `NetworkPolicy`.
+ *
+ * The shapes are identical except for Tier-2: our `requestRules`
+ * (`{ methods, pathPrefixes }`) become Vercel `match` rules
+ * (`{ method, path: { startsWith } }`) — one rule per path prefix, since a
+ * Vercel matcher carries a single path.
+ *
+ * Dot-segment defense: prefix matching is raw — `/repos/acme/../../user`
+ * starts with `/repos/acme/` but the origin normalizes it to `/user`, riding
+ * the credential outside its declared scope. We don't get to assume the
+ * enforcer RFC-3986-normalizes before matching, so every domain with a path
+ * gate gets a transform-free FIRST rule matching dot-segment paths
+ * (first-match-wins ⇒ such requests go out credential-free), and declared
+ * prefixes themselves are validated (must start with "/", no dot-segments).
+ *
+ * Accepted divergence from iron-proxy (E2B): off-gate requests to an allowed
+ * domain pass WITHOUT the transform (Vercel terminates TLS only for
+ * transform-bearing domains and applies first-match-wins) — iron-proxy
+ * REFUSES them instead. Reachability differs; the property that matters is
+ * preserved on both substrates: the brokered credential rides only declared
+ * method/path combinations. Pinned by vercel-network-policy.test.ts.
+ */
+export function toVercelNetworkPolicy(policy: SandboxNetworkPolicy): VercelNetworkPolicy {
+  if (typeof policy === "string" || !policy.allow || Array.isArray(policy.allow)) {
+    return policy as VercelNetworkPolicy;
+  }
+  const allow: Record<string, VercelNetworkPolicyRule[]> = {};
+  for (const [domain, rules] of Object.entries(policy.allow)) {
+    const translated = rules.flatMap((rule): VercelNetworkPolicyRule[] => {
+      const { requestRules, ...rest } = rule;
+      const methods = requestRules?.methods ?? [];
+      const prefixes = requestRules?.pathPrefixes ?? [];
+      if (methods.length === 0 && prefixes.length === 0) return [rest];
+      const methodMatch = methods.length > 0 ? { method: methods } : {};
+      if (prefixes.length === 0) return [{ ...rest, match: methodMatch }];
+      for (const prefix of prefixes) assertSafePathPrefix(domain, prefix);
+      return prefixes.map((prefix) => ({ ...rest, match: { ...methodMatch, path: { startsWith: prefix } } }));
+    });
+    const hasPathGate = rules.some((rule) => (rule.requestRules?.pathPrefixes?.length ?? 0) > 0);
+    allow[domain] = hasPathGate
+      ? [{ match: { path: { regex: DOT_SEGMENT_PATH_RE2 } } }, ...translated]
+      : translated;
+  }
+  return { ...policy, allow };
+}
+
+/**
+ * Translate our policy shape into E2B's native `network` config
+ * (`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).
+ *   - `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.
+ *   - `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`).
+ *
+ * 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
+ * Tier-2 `requestRules` (`{ methods, pathPrefixes }`) cannot be enforced here:
+ * a brokered credential rides EVERY request to an allowed host on E2B, whereas
+ * Vercel (native `match`) and the old iron-proxy gated it to the declared
+ * method+path. The host allowlist still confines WHICH hosts the credential
+ * can reach; it just can't narrow to a method/path within an allowed host.
+ *
+ * String policies map straight through: "allow-all" → no restriction (omit
+ * `allowOut`/`denyOut`), "deny-all" → block all egress.
+ */
+export function toE2bNetwork(policy: SandboxNetworkPolicy): E2bNetworkOpts {
+  if (policy === "allow-all") return {};
+  if (policy === "deny-all") return { denyOut: ({ allTraffic }) => [allTraffic] };
+
+  // List-form allow (no transforms): allowlist the hosts, default-deny the rest.
+  const allowHosts: string[] = Array.isArray(policy.allow)
+    ? [...policy.allow]
+    : Object.keys(policy.allow ?? {});
+  const subnetAllow = policy.subnets?.allow ?? [];
+  const allowOut = [...new Set([...allowHosts, ...subnetAllow])];
+
+  const network: E2bNetworkOpts = {
+    // Default-deny: only `allowOut` passes (E2B applies allow before deny).
+    denyOut: ({ allTraffic }) => [allTraffic],
+  };
+  if (allowOut.length > 0) network.allowOut = allowOut;
+
+  // Per-host header injection. Each of our `transform` entries (a
+  // `{ headers }` bag) becomes one E2B rule. `requestRules` is intentionally
+  // dropped — see the divergence note above.
+  if (!Array.isArray(policy.allow) && policy.allow) {
+    const rules: Record<string, E2bNetworkRule[]> = {};
+    for (const [host, hostRules] of Object.entries(policy.allow)) {
+      const hostTransforms = hostRules.flatMap((rule) =>
+        (rule.transform ?? [])
+          .filter((t) => t.headers && Object.keys(t.headers).length > 0)
+          .map((t): E2bNetworkRule => ({ transform: { headers: t.headers } })),
+      );
+      if (hostTransforms.length > 0) rules[host] = hostTransforms;
+    }
+    if (Object.keys(rules).length > 0) network.rules = rules;
+  }
+
+  return network;
+}

package/src/sandbox/provider-def.ts

@@ -0,0 +1,94 @@
+/**
+ * The contract a sandbox provider implements (`SandboxProviderDef`), the
+ * create-time options every provider receives, and the fleet tag that scopes
+ * a deployment's sandboxes on the provider side. Providers implement this;
+ * the registry consumes it.
+ */
+
+import type { SandboxProvider } from "../types/sandbox.js";
+import type { SandboxNetworkPolicy } from "./network-policy.js";
+import type { SandboxSize } from "./sizes.js";
+
+// Fleet-wide tag, NOT machine-scoped. Previously we embedded FLY_MACHINE_ID
+// so each replica scoped its own E2B sandboxes at boot, but that made
+// cross-replica orphan reconciliation impossible: when a replica hard-died,
+// its E2B sandboxes became invisible to every surviving replica and stayed
+// running until E2B's own lifetime cap. With a fleet-wide tag the provider
+// reconciler (`listOwned` + DB cross-ref) handles cleanup correctly across
+// all replicas. Boot-time `killAllSandboxes` was deliberately removed when
+// this changed — killing at boot with a shared tag would nuke live sandboxes
+// owned by other replicas.
+export const AGENT_COMPOSE_TAG = process.env.AGENT_COMPOSE_TAG ??
+  `agent-compose-${process.env.AGENT_COMPOSE_ENV ?? "dev"}`;
+
+export interface SandboxCreateOpts {
+  envs:           Record<string, string>;
+  metadata:       Record<string, string>;
+  timeoutMs:      number;
+  /** Provider-specific template/snapshot identifier. E2B: template id or
+   *  snapshot id (omit → E2B's default base). Vercel: snapshot id (omit → node24). */
+  template?:      string;
+  /** Machine size. Vercel maps it to `resources.vcpus`; E2B ignores it
+   *  (size is template-defined). Omit → `DEFAULT_SANDBOX_SIZE`. */
+  size?:          SandboxSize;
+  /** Outbound request policy with header transforms — ONE shape for every
+   *  provider; only the enforcement point differs. Both providers enforce +
+   *  inject natively at create from this value: Vercel via its firewall
+   *  (`toVercelNetworkPolicy`), E2B via its native network firewall
+   *  (`toE2bNetwork` → `network: { allowOut, denyOut, rules }`). */
+  networkPolicy?: SandboxNetworkPolicy;
+}
+
+/**
+ * What the provider reports as "currently alive" — the single input to orphan
+ * reconciliation. `metadata` is best-effort: E2B populates it from sandbox
+ * labels, Vercel from sandbox tags (max 5, stamped at create). Callers
+ * that need runId correlation cross-reference `sandboxId` against their own
+ * state (server: `workflow_runs.sandbox_id` + `run_agent_sandboxes.provider_sandbox_id`).
+ */
+export interface OwnedSandbox {
+  sandboxId: string;
+  createdAt: Date;
+  metadata:  Record<string, string>;
+}
+
+export interface SandboxProviderDef {
+  requiredEnv: Record<string, string>;
+  create:      (opts: SandboxCreateOpts, env: Record<string, string>) => Promise<SandboxProvider>;
+  reconnect?:  (sandboxId: string) => Promise<SandboxProvider>;
+  killAll?:    (env: Record<string, string>) => Promise<void>;
+  /**
+   * Returns the number of sandboxes currently running against this provider.
+   * Used for quota observability — account-wide, not per-instance.
+   *
+   * Both providers scope by our AGENT_COMPOSE_TAG (E2B metadata labels,
+   * Vercel tags) so each fleet only reports its own sandboxes; DD aggregates
+   * across instances with `sum by {provider}`.
+   */
+  getActiveCount?: (env: Record<string, string>) => Promise<number>;
+  /**
+   * Provider's view of what's currently alive for our account/fleet.
+   * The reconciliation SoT — a sandbox missing from this list IS dead,
+   * regardless of what our DB says. Implemented by listing the provider's
+   * running sandboxes; E2B filters by metadata tag, Vercel by the `executor`
+   * sandbox tag.
+   */
+  listOwned?: (env: Record<string, string>) => Promise<OwnedSandbox[]>;
+  /**
+   * Delete a snapshot by id. Called from the customer-initiated
+   * `DELETE /workflows/:runId/snapshot` route. Best-effort — the DB is
+   * source of truth; an orphan on the provider side is benign and cleaned
+   * up eventually by the provider's own retention.
+   */
+  deleteSnapshot?: (snapshotId: string, env: Record<string, string>) => Promise<void>;
+  /**
+   * Does this snapshot id resolve on the provider for this account? A cheap
+   * metadata lookup — NEVER provisions a sandbox. Used at server boot to
+   * validate that the platform base snapshots the default templates boot from
+   * actually exist for this deployment (catching e.g. a dev-account snapshot
+   * baked into prod). Returns true if it resolves, false if the provider
+   * reports it does not exist. Transport/credential errors PROPAGATE — an
+   * indeterminate result must not be reported as "missing".
+   */
+  snapshotExists?: (snapshotId: string, env: Record<string, string>) => Promise<boolean>;
+}

package/src/sandbox/providers/desktop.ts

@@ -0,0 +1,57 @@
+/**
+ * E2B Desktop sandbox provider — the base E2B wrapper plus mouse/keyboard/
+ * screenshot control, and the "e2b-desktop" registry entry. Registry-only:
+ * never a workflow's runtime (see `workflow-metadata.ts`).
+ */
+
+import { Sandbox as Desktop } from "@e2b/desktop";
+import type { DesktopSandboxProvider } from "../../types/sandbox.js";
+import type { SandboxProviderDef } from "../provider-def.js";
+import { makeSandboxProvider, e2bMaxSandboxMs } from "./e2b.js";
+
+export function makeDesktopSandboxProvider(sb: Desktop): DesktopSandboxProvider {
+  return {
+    ...makeSandboxProvider(sb),
+    screenshot:  ()           => sb.screenshot() as Promise<Buffer>,
+    leftClick:   (x, y)       => sb.leftClick(x, y),
+    doubleClick: (x, y)       => sb.doubleClick(x, y),
+    rightClick:  (x, y)       => sb.rightClick(x, y),
+    middleClick: (x, y)       => sb.middleClick(x, y),
+    moveMouse:   (x, y)       => sb.moveMouse(x, y),
+    write:       (text)       => sb.write(text),
+    press:       (key)        => sb.press(key),
+    scroll:      (dir, ticks) => sb.scroll(dir, ticks),
+    drag:        (from, to)   => sb.drag(from, to),
+  };
+}
+
+export const e2bDesktopProviderDef: SandboxProviderDef = {
+  requiredEnv: { E2B_API_KEY: "E2B API key — e2b.dev/dashboard" },
+  // `size` dropped here: E2B has no create-time resource knob (specs are
+  // baked into the template/snapshot), so sizing on E2B = a pre-sized
+  // template, not this field. Honoured only on Vercel.
+  //
+  // NO native firewall on this path: `@e2b/desktop` bundles its own (older)
+  // `e2b` whose `SandboxOpts` predates the `network` field, so there is no
+  // way to enforce an egress policy natively here — unlike the "e2b" and
+  // "vercel" providers. Rather than SILENTLY dropping a policy (fail-open —
+  // the exact leak the native-firewall migration closed), we refuse to create
+  // a desktop sandbox under any non-empty policy. In practice this never
+  // fires: e2b-desktop is registry-only, never a workflow's runtime (see
+  // `workflow-metadata.ts`), so it is only ever provisioned with no policy.
+  create: async ({ template, timeoutMs, networkPolicy, size: _size, ...rest }) => {
+    if (!template) throw new Error("E2B Desktop provider requires an explicit `template` (Dockerfile-based — no default base image)");
+    if (networkPolicy && networkPolicy !== "allow-all") {
+      throw new Error(
+        "E2B Desktop provider cannot enforce an egress network policy — `@e2b/desktop` bundles an e2b version that predates the native firewall. " +
+        "e2b-desktop is registry-only and must not run with a confined policy.",
+      );
+    }
+    return makeDesktopSandboxProvider(
+      await Desktop.create(template, {
+        ...rest,
+        timeoutMs: Math.min(timeoutMs, e2bMaxSandboxMs()),
+      }),
+    );
+  },
+};