feat(eve): expose userspace sandbox drives

.changeset/swift-drives-mount.md

@@ -0,0 +1,5 @@
+---
+"eve": minor
+---
+
+Expose Vercel Sandbox Drives and allow authors to mount them when creating live session sandboxes.

packages/eve/package.json

@@ -346,6 +346,7 @@
     "@vercel/oidc": "3.8.0",
     "@vercel/otel": "catalog:",
     "@vercel/sandbox": "catalog:",
+    "@vercel/sandbox-drives": "catalog:",
     "@vercel/sdk": "1.28.8",
     "@workflow/core": "5.0.0-beta.41",
     "@workflow/errors": "5.0.0-beta.16",

packages/eve/scripts/vendor-compiled/@vercel/sandbox-stable.mjs

@@ -0,0 +1,9 @@
+import vercelSandbox from "./sandbox.mjs";
+
+/** Preserve extension contract declarations while Drives uses the beta runtime. */
+export default {
+  ...vercelSandbox,
+  packageName: "@vercel/sandbox",
+  compiledPath: "@vercel/sandbox-stable",
+  typeOnly: true,
+};

packages/eve/scripts/vendor-compiled/@vercel/sandbox.mjs

@@ -23,7 +23,8 @@ async function discoverDeclarationFiles({ distDir }) {
  * or local stubs, while Node built-ins remain external.
  */
 export default {
-  packageName: "@vercel/sandbox",
+  packageName: "@vercel/sandbox-drives",
+  packageJsonName: "@vercel/sandbox",
   compiledPath: "@vercel/sandbox",
   plugins: [createOptionalNativeStubPlugin(["fsevents"])],
   copyDeclarations: createDeclarationCopier({

packages/eve/scripts/vendor-compiled/_shared.mjs

@@ -10,6 +10,7 @@
  * ```
  * {
  *   packageName: string,           // npm package to resolve via require
+ *   packageJsonName?: string,      // original npm name when packageName is an alias
  *   compiledPath: string,          // subdir under compiledRoot to write into
  *
  *   // Declaration emission (pick one)
@@ -513,7 +514,7 @@ async function pathExists(path) {
   }
 }
 
-async function findPackageJson(packageName, packageRoot) {
+async function findPackageJson(packageName, packageRoot, packageJsonName = packageName) {
   let currentPath;
   try {
     currentPath = dirname(require.resolve(packageName, { paths: [packageRoot] }));
@@ -527,7 +528,7 @@ async function findPackageJson(packageName, packageRoot) {
 
     if (await pathExists(packageJsonPath)) {
       const packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
-      if (packageJson.name === packageName) {
+      if (packageJson.name === packageJsonName) {
         return {
           packageJson,
           packageJsonPath,
@@ -542,7 +543,7 @@ async function findPackageJson(packageName, packageRoot) {
     const packageJsonPath = join(currentPath, "package.json");
     if (await pathExists(packageJsonPath)) {
       const packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
-      if (packageJson.name === packageName) {
+      if (packageJson.name === packageJsonName) {
         return {
           packageJson,
           packageJsonPath,
@@ -567,7 +568,11 @@ async function copyLicense(sourceRoot, destinationRoot) {
 
 async function prepareCompiledModule({ module, compiledRoot, packageRoot }) {
   const destinationRoot = join(compiledRoot, module.compiledPath);
-  const packageInfo = await findPackageJson(module.packageName, packageRoot);
+  const packageInfo = await findPackageJson(
+    module.packageName,
+    packageRoot,
+    module.packageJsonName,
+  );
 
   await rm(destinationRoot, { recursive: true, force: true });
   await mkdir(destinationRoot, { recursive: true });
@@ -809,7 +814,11 @@ async function computeStamp({ scriptFiles, modules, packageRoot }) {
 
   const moduleVersions = {};
   for (const module of modules) {
-    const { packageJson } = await findPackageJson(module.packageName, packageRoot);
+    const { packageJson } = await findPackageJson(
+      module.packageName,
+      packageRoot,
+      module.packageJsonName,
+    );
     moduleVersions[module.packageName] = packageJson.version ?? "0.0.0";
   }
 

packages/eve/scripts/vendor-compiled/index.mjs

@@ -24,6 +24,7 @@ import vercelDetectAgent from "./@vercel/detect-agent.mjs";
 import vercelOidc from "./@vercel/oidc.mjs";
 import vercelOtel from "./@vercel/otel.mjs";
 import vercelSandbox from "./@vercel/sandbox.mjs";
+import vercelSandboxStable from "./@vercel/sandbox-stable.mjs";
 import workflowCore from "./@workflow/core.mjs";
 import workflowErrors from "./@workflow/errors.mjs";
 import workflowSerde from "./@workflow/serde.mjs";
@@ -84,6 +85,7 @@ export const MODULES = [
   vercelOidc,
   vercelOtel,
   vercelSandbox,
+  vercelSandboxStable,
   workflowCore,
   workflowErrors,
   workflowSerde,

packages/eve/src/execution/sandbox/bindings/vercel.test.ts

@@ -748,6 +748,63 @@ describe("createVercelSandbox", () => {
     expect(templateSandbox.update).toHaveBeenCalledWith({ networkPolicy: "deny-all" });
   });
 
+  it("resolves mounts only for a fresh live session sandbox", async () => {
+    const templateSandbox = createMockSandbox({ name: "template" });
+    const sessionSandbox = createMockSandbox({ name: "session" });
+    const create = vi
+      .fn()
+      .mockResolvedValueOnce(templateSandbox)
+      .mockResolvedValueOnce(sessionSandbox);
+    const resolveSessionCreateOptions = vi.fn(({ session }) => ({
+      mounts: { "/workspace/repos": { drive: `e0-${session.id}` } },
+    }));
+    const backend = createTestVercelSandbox({
+      loadSandboxModule: async () =>
+        ({ Sandbox: { create, get: vi.fn().mockResolvedValue(null) } }) as never,
+      resolveSessionCreateOptions,
+    });
+
+    await backend.prewarm({
+      runtimeContext: { appRoot: "/tmp/test-app-root" },
+      seedFiles: [],
+      templateKey: "template-key",
+    });
+    await backend.create({
+      runtimeContext: { appRoot: "/tmp/test-app-root" },
+      sessionKey: "session-key",
+      tags: { sessionId: "parent-session" },
+      templateKey: "template-key",
+    });
+
+    expect(resolveSessionCreateOptions).toHaveBeenCalledWith({
+      session: { id: "parent-session" },
+    });
+    expect(create.mock.calls[0]?.[0]).not.toHaveProperty("mounts");
+    expect(create.mock.calls[1]?.[0]).toMatchObject({
+      mounts: { "/workspace/repos": { drive: "e0-parent-session" } },
+    });
+  });
+
+  it("does not resolve session create options when resuming a sandbox", async () => {
+    const existing = createMockSandbox({ name: "session-key" });
+    const create = vi.fn();
+    const resolveSessionCreateOptions = vi.fn();
+    const backend = createTestVercelSandbox({
+      loadSandboxModule: async () =>
+        ({ Sandbox: { create, get: vi.fn().mockResolvedValue(existing) } }) as never,
+      resolveSessionCreateOptions,
+    });
+
+    await backend.create({
+      runtimeContext: { appRoot: "/tmp/test-app-root" },
+      sessionKey: "session-key",
+      templateKey: null,
+    });
+
+    expect(resolveSessionCreateOptions).not.toHaveBeenCalled();
+    expect(create).not.toHaveBeenCalled();
+  });
+
   it("forwards author source to template create as the base layer", async () => {
     /*
      * The real Vercel SDK pre-populates `currentSnapshotId` on a

packages/eve/src/execution/sandbox/bindings/vercel.ts

@@ -25,6 +25,8 @@ import type {
 import { SandboxTemplateNotProvisionedError } from "#public/definitions/sandbox-backend.js";
 import type {
   VercelSandboxBootstrapUseOptions,
+  VercelSandboxSessionCreateContext,
+  VercelSandboxSessionCreateOptions,
   VercelSandboxSessionUseOptions,
 } from "#public/sandbox/vercel-sandbox.js";
 import { WORKSPACE_ROOT } from "#runtime/workspace/types.js";
@@ -54,6 +56,9 @@ export interface CreateVercelSandboxInput {
   readonly createSandbox?: CreateVercelSandbox;
   readonly createOptions?: VercelCreateOptions;
   readonly loadSandboxModule?: () => Promise<VercelModule>;
+  readonly resolveSessionCreateOptions?: (
+    context: VercelSandboxSessionCreateContext,
+  ) => Promise<VercelSandboxSessionCreateOptions> | VercelSandboxSessionCreateOptions;
 }
 /**
  * Creates the Vercel-backed sandbox backend.
@@ -101,7 +106,9 @@ export function createVercelSandbox(
           createOptions,
           createSandbox,
           existingMetadata: createInput.existingMetadata,
+          resolveSessionCreateOptions: input.resolveSessionCreateOptions,
           sandboxModule,
+          sessionId: createInput.tags?.sessionId ?? createInput.sessionKey,
           sessionKey: createInput.sessionKey,
           snapshotId: template?.snapshotId,
           tags,
@@ -357,7 +364,9 @@ interface EnsureSessionInput {
   readonly createOptions: VercelCreateOptions;
   readonly createSandbox: CreateVercelSandbox;
   readonly existingMetadata?: Record<string, unknown>;
+  readonly resolveSessionCreateOptions?: CreateVercelSandboxInput["resolveSessionCreateOptions"];
   readonly sandboxModule: VercelModule;
+  readonly sessionId: string;
   readonly sessionKey: string;
   readonly snapshotId?: string;
   readonly tags: Record<string, string> | undefined;
@@ -381,7 +390,10 @@ async function ensureSession(input: EnsureSessionInput): Promise<VercelSandboxSe
     return { created: false, sandbox: existing };
   }
 
-  const createParams = createSessionCreateParams(input, sandboxName);
+  const sessionCreateOptions = await input.resolveSessionCreateOptions?.({
+    session: { id: input.sessionId },
+  });
+  const createParams = createSessionCreateParams(input, sandboxName, sessionCreateOptions);
   if (input.tags !== undefined) {
     createParams.tags = input.tags;
   }
@@ -398,10 +410,12 @@ async function ensureSession(input: EnsureSessionInput): Promise<VercelSandboxSe
 function createSessionCreateParams(
   input: EnsureSessionInput,
   sandboxName: string,
+  sessionCreateOptions: VercelSandboxSessionCreateOptions = {},
 ): VercelSandboxCreateParams {
+  const createOptions = { ...input.createOptions, ...sessionCreateOptions } as VercelCreateOptions;
   if (input.snapshotId === undefined) {
     return withBaseSetupNetworkPolicy({
-      ...input.createOptions,
+      ...createOptions,
       name: sandboxName,
       persistent: true,
     });
@@ -417,12 +431,12 @@ function createSessionCreateParams(
     image: _image,
     runtime: _runtime,
     source: _source,
-    ...sessionCreateOptions
-  } = input.createOptions as VercelCreateOptions &
+    ...baseSessionCreateOptions
+  } = createOptions as VercelCreateOptions &
     Partial<Record<"image" | "runtime" | "source", unknown>>;
 
   return {
-    ...sessionCreateOptions,
+    ...baseSessionCreateOptions,
     name: sandboxName,
     persistent: true,
     source: { snapshotId: input.snapshotId, type: "snapshot" as const },

packages/eve/src/public/sandbox/backends/vercel.ts

@@ -2,7 +2,7 @@ import { createVercelSandbox } from "#execution/sandbox/bindings/vercel.js";
 import type { SandboxBackend } from "#public/definitions/sandbox-backend.js";
 import type {
   VercelSandboxBootstrapUseOptions,
-  VercelSandboxCreateOptions,
+  VercelSandboxOptions,
   VercelSandboxSessionUseOptions,
 } from "#public/sandbox/vercel-sandbox.js";
 
@@ -12,7 +12,7 @@ import type {
  * including for local development, where it creates real hosted
  * sandboxes (requires Vercel credentials).
  *
- * The optional `opts` parameter is forwarded to Vercel Sandbox creation
+ * The optional provider creation fields are forwarded to Vercel Sandbox creation
  * for every fresh sandbox the framework creates (template at prewarm,
  * session at first-time create). On resume (`Sandbox.get`), no create
  * happens, so opts are not re-applied. `networkPolicy` is applied after
@@ -30,10 +30,15 @@ import type {
  * `sandbox.update(...)`; those settings persist into the snapshot.
  * `onSession({ use })` applies its options to the live session via the
  * SDK's `update` under the hood, overriding any overlapping field
- * from `opts`.
+ * from `opts`. `sessionCreateOptions`, when provided, is resolved only
+ * when creating a fresh live session and can attach session-specific Drives.
  */
 export function vercel(
-  opts?: VercelSandboxCreateOptions,
+  opts?: VercelSandboxOptions,
 ): SandboxBackend<VercelSandboxBootstrapUseOptions, VercelSandboxSessionUseOptions> {
-  return createVercelSandbox({ createOptions: opts });
+  const { sessionCreateOptions, ...createOptions } = opts ?? {};
+  return createVercelSandbox({
+    createOptions,
+    resolveSessionCreateOptions: sessionCreateOptions,
+  });
 }

packages/eve/src/public/sandbox/vercel-sandbox.ts

@@ -9,7 +9,7 @@ type VercelSandboxInternalCreateOptions = {
 };
 
 type VercelSandboxAuthorCreateOptions<T> = T extends unknown
-  ? Omit<T, "name" | "onResume" | "persistent" | "runtime" | "signal"> &
+  ? Omit<T, "mounts" | "name" | "onResume" | "persistent" | "runtime" | "signal"> &
       VercelSandboxInternalCreateOptions
   : never;
 
@@ -44,6 +44,36 @@ type VercelSandboxAuthorCreateOptions<T> = T extends unknown
  */
 export type VercelSandboxCreateOptions = VercelSandboxAuthorCreateOptions<VercelCreateOptions>;
 
+/** Access mode for a Drive mounted into a Vercel Sandbox. */
+export type VercelSandboxMountMode = Vercel.SandboxMountMode;
+
+/** A Drive mounted at one absolute path in a Vercel Sandbox. */
+export type VercelSandboxMount = Vercel.SandboxMounts[string];
+
+/** Drive mounts keyed by absolute sandbox path. */
+export type VercelSandboxMounts = Vercel.SandboxMounts;
+
+/** Options resolved when eve creates a fresh live session sandbox. */
+export interface VercelSandboxSessionCreateOptions {
+  readonly mounts?: VercelSandboxMounts;
+}
+
+/** Context available while resolving fresh live-session creation options. */
+export interface VercelSandboxSessionCreateContext {
+  readonly session: { readonly id: string };
+}
+
+/** Options accepted by `vercel(opts)`. */
+export type VercelSandboxOptions = VercelSandboxCreateOptions & {
+  /**
+   * Resolves options that apply only to fresh live sessions. It is not called
+   * while prewarming templates or resuming an existing sandbox.
+   */
+  readonly sessionCreateOptions?: (
+    context: VercelSandboxSessionCreateContext,
+  ) => Promise<VercelSandboxSessionCreateOptions> | VercelSandboxSessionCreateOptions;
+};
+
 /**
  * Options accepted by the Vercel backend's `bootstrap({ use })` hook.
  * Tracks the Vercel SDK's `Sandbox.update(...)` parameter because bootstrap

packages/eve/src/public/sandbox/vercel.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, expectTypeOf, it } from "vitest";
+
+import {
+  Drive,
+  vercel,
+  type VercelSandboxOptions,
+  type VercelSandboxSessionCreateOptions,
+} from "#public/sandbox/vercel.js";
+
+describe("vercel", () => {
+  it("exposes Drive and accepts session-scoped mounts", () => {
+    const options = {
+      sessionCreateOptions: ({ session }) => ({
+        mounts: {
+          "/workspace": { drive: `repo-${session.id}`, mode: "read-write" },
+        },
+      }),
+    } satisfies VercelSandboxOptions;
+
+    expect(vercel(options).name).toBe("vercel");
+    expectTypeOf(Drive.getOrCreate).toBeFunction();
+    expectTypeOf(
+      options.sessionCreateOptions({ session: { id: "acme" } }),
+    ).toMatchTypeOf<VercelSandboxSessionCreateOptions>();
+    expectTypeOf<VercelSandboxOptions>().not.toHaveProperty("mounts");
+  });
+});

packages/eve/src/public/sandbox/vercel.ts

@@ -1,6 +1,13 @@
 export { vercel } from "#public/sandbox/backends/vercel.js";
+export { Drive } from "#compiled/@vercel/sandbox/index.js";
 export type {
   VercelSandboxBootstrapUseOptions,
   VercelSandboxCreateOptions,
+  VercelSandboxMount,
+  VercelSandboxMountMode,
+  VercelSandboxMounts,
+  VercelSandboxOptions,
+  VercelSandboxSessionCreateContext,
+  VercelSandboxSessionCreateOptions,
   VercelSandboxSessionUseOptions,
 } from "#public/sandbox/vercel-sandbox.js";

packages/eve/src/shared/sandbox-network-policy.ts

@@ -1,4 +1,4 @@
-import type * as Vercel from "#compiled/@vercel/sandbox/index.js";
+import type * as Vercel from "#compiled/@vercel/sandbox-stable/index.js";
 
 /**
  * Firewall network policy applied to a live sandbox session.