@agent-compose/sdk 0.7.0 → 0.8.0

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()),
+      }),
+    );
+  },
+};