V48 (impl-only): Load @vercel/sandbox via pure ESM to fix ERR_REQUIRE_ESM

Production deposit synthesis failed after sandbox auth when Next/CJS resolved
dist/index.cjs → command.cjs require(@workflow/serde). Force the dist/index.js
ESM entry with webpackIgnore, externalize sandbox/serde/oidc, and pin
@vercel/sandbox to 2.6.0.

Author: geraldarthurdavis

packages/generic-hosts/VercelSandbox/package.json

@@ -15,7 +15,7 @@
   },
   "dependencies": {
     "@bitcode/host-generics": "workspace:*",
-    "@vercel/sandbox": "^1.10.2"
+    "@vercel/sandbox": "2.6.0"
   },
   "devDependencies": {
     "@types/jest": "^29.5.12",

packages/generic-hosts/VercelSandbox/src/__tests__/vercel-sandbox-host.test.ts

@@ -1,6 +1,11 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
 import { buildAssetPackSandboxHostPlan } from '@bitcode/pipeline-hosts';
 import {
+  assertVercelSandboxAuthAvailable,
   normalizeCreateOptions,
+  resolveVercelSandboxEsmEntryHref,
   VercelSandboxPipelineHost,
 } from '../vercel-sandbox-host';
 import type {
@@ -388,6 +393,44 @@ describe('VercelSandboxPipelineHost', () => {
       'Vercel Sandbox create did not complete within 5ms.'
     );
   });
+
+  it('resolves the pure-ESM @vercel/sandbox entry (not dist/index.cjs)', () => {
+    const href = resolveVercelSandboxEsmEntryHref((id) => {
+      if (id === '@vercel/sandbox/package.json') {
+        return path.join('/virtual/node_modules/@vercel/sandbox', 'package.json');
+      }
+      throw new Error(`unexpected resolve: ${id}`);
+    });
+    expect(href).toBe(
+      pathToFileURL(path.join('/virtual/node_modules/@vercel/sandbox/dist/index.js')).href,
+    );
+    expect(href.endsWith('/dist/index.js')).toBe(true);
+    expect(href.includes('index.cjs')).toBe(false);
+  });
+
+  it('accepts access-token auth when OIDC is absent', () => {
+    const previous = {
+      VERCEL_TOKEN: process.env.VERCEL_TOKEN,
+      VERCEL_TEAM_ID: process.env.VERCEL_TEAM_ID,
+      VERCEL_PROJECT_ID: process.env.VERCEL_PROJECT_ID,
+      VERCEL_OIDC_TOKEN: process.env.VERCEL_OIDC_TOKEN,
+    };
+    try {
+      delete process.env.VERCEL_OIDC_TOKEN;
+      process.env.VERCEL_TOKEN = 'tok';
+      process.env.VERCEL_TEAM_ID = 'team';
+      process.env.VERCEL_PROJECT_ID = 'prj';
+      expect(() => assertVercelSandboxAuthAvailable()).not.toThrow();
+
+      delete process.env.VERCEL_TOKEN;
+      expect(() => assertVercelSandboxAuthAvailable()).toThrow(/Sandbox auth is not configured/);
+    } finally {
+      restoreEnv('VERCEL_TOKEN', previous.VERCEL_TOKEN);
+      restoreEnv('VERCEL_TEAM_ID', previous.VERCEL_TEAM_ID);
+      restoreEnv('VERCEL_PROJECT_ID', previous.VERCEL_PROJECT_ID);
+      restoreEnv('VERCEL_OIDC_TOKEN', previous.VERCEL_OIDC_TOKEN);
+    }
+  });
 });
 
 function restoreEnv(key: string, value: string | undefined): void {

packages/generic-hosts/VercelSandbox/src/vercel-sandbox-host.ts

@@ -1,3 +1,8 @@
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
 import type {
   PipelineHostCommand,
   PipelineHostEvent,
@@ -487,12 +492,76 @@ export function assertVercelSandboxAuthAvailable(
   );
 }
 
+/**
+ * Resolve the pure-ESM entry of `@vercel/sandbox` as a file:// URL.
+ *
+ * Package root resolution under Next/CJS serverless can load `dist/index.cjs`
+ * → `command.cjs`, which does `require('@workflow/serde')`. That package is
+ * pure ESM, so Node throws ERR_REQUIRE_ESM on Vercel `/var/task`. The ESM
+ * graph (`dist/index.js`) imports serde correctly.
+ */
+export function resolveVercelSandboxEsmEntryHref(
+  resolveId: (id: string) => string = defaultResolvePackageId,
+): string {
+  const root = resolveVercelSandboxPackageRoot(resolveId);
+  const esmIndex = path.join(root, 'dist', 'index.js');
+  return pathToFileURL(esmIndex).href;
+}
+
+export function resolveVercelSandboxPackageRoot(
+  resolveId: (id: string) => string = defaultResolvePackageId,
+): string {
+  try {
+    return path.dirname(resolveId('@vercel/sandbox/package.json'));
+  } catch {
+    // Incomplete exports / hoisting: resolve a runtime file and walk up until
+    // package.json name is @vercel/sandbox.
+    let dir = path.dirname(resolveId('@vercel/sandbox'));
+    for (let i = 0; i < 8; i++) {
+      const candidate = path.join(dir, 'package.json');
+      try {
+        const pkg = JSON.parse(fs.readFileSync(candidate, 'utf8')) as { name?: string };
+        if (pkg.name === '@vercel/sandbox') return dir;
+      } catch {
+        // keep walking
+      }
+      const parent = path.dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+    throw new Error('Could not resolve @vercel/sandbox package root for ESM load.');
+  }
+}
+
+function defaultResolvePackageId(id: string): string {
+  // createRequire needs a filepath anchor; cwd package.json works under Next,
+  // Jest, and monorepo package tests without import.meta.
+  const req = createRequire(path.join(process.cwd(), 'package.json'));
+  return req.resolve(id);
+}
+
 export async function loadVercelSandboxFactory(): Promise<SandboxFactory> {
-  const module = await import('@vercel/sandbox') as { Sandbox?: SandboxFactory };
-  if (!module.Sandbox?.create) {
-    throw new Error('@vercel/sandbox did not expose Sandbox.create().');
+  const esmHref = resolveVercelSandboxEsmEntryHref();
+  // webpackIgnore: do not rewrite to a CJS interop chunk; load Node-native ESM.
+  const module = (await import(
+    /* webpackIgnore: true */
+    esmHref
+  )) as {
+    Sandbox?: SandboxFactory;
+    default?: SandboxFactory | { Sandbox?: SandboxFactory };
+  };
+
+  const fromDefault =
+    module.default && typeof module.default === 'object'
+      ? module.default.Sandbox
+      : undefined;
+  const Sandbox = module.Sandbox ?? fromDefault;
+  if (!Sandbox?.create) {
+    throw new Error(
+      `@vercel/sandbox did not expose Sandbox.create() (ESM entry ${esmHref}).`,
+    );
   }
-  return module.Sandbox;
+  return Sandbox;
 }
 
 async function readCommandOutput(

packages/pipeline-hosts/package.json

@@ -23,7 +23,7 @@
     "type-check": "pnpm run typecheck"
   },
   "dependencies": {
-    "@vercel/sandbox": "^1.10.2",
+    "@vercel/sandbox": "2.6.0",
     "@bitcode/host-generics": "workspace:*",
     "@bitcode/generic-hosts-local": "workspace:*",
     "@bitcode/generic-hosts-vercel-sandbox": "workspace:*"