The Open Framework for Building Agents
fix(eve): wait for a concurrent build's Vercel template instead of failing (#4707)
roboeve[bot]63b1daabc4ce
diff --git a/.changeset/vercel-template-name-conflict.md b/.changeset/vercel-template-name-conflict.mdnew file mode 100644index 000000000..25bef5f26--- /dev/null+++ b/.changeset/vercel-template-name-conflict.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Concurrent builds that need the same new Vercel sandbox template no longer fail with a 400 "sandbox with the name already exists" error. Each build now prepares its template in a private, non-persistent sandbox and records the finished snapshot under the shared template name only after the snapshot exists, so a build that fails, is killed, or times out never leaves half-prepared work where another build would reuse it.diff --git a/packages/eve/src/execution/sandbox/bindings/vercel-lookup.ts b/packages/eve/src/execution/sandbox/bindings/vercel-lookup.tsindex 906be19e6..a8d868192 100644--- a/packages/eve/src/execution/sandbox/bindings/vercel-lookup.ts+++ b/packages/eve/src/execution/sandbox/bindings/vercel-lookup.ts@@ -2,7 +2,10 @@ import {getVercelSandboxFetch,resolveVercelSandboxCredentials,} from "#execution/sandbox/bindings/vercel-credentials.js";-import { isVercelSandboxMissingError } from "#execution/sandbox/bindings/vercel-errors.js";+import {+ isVercelSandboxMissingError,+ isVercelSnapshotUnavailableError,+} from "#execution/sandbox/bindings/vercel-errors.js";import { errorMessage } from "#execution/sandbox/bindings/vercel-options.js";import type {VercelCreateOptions,@@ -32,6 +35,31 @@ export async function getNamedVercelSandbox(input: {}}+/** Whether a snapshot exists and finished, so a sandbox can still start from it. */+export async function isVercelSnapshotCreated(input: {+ readonly createOptions: VercelCreateOptions;+ readonly sandboxModule: VercelModule;+ readonly snapshotId: string;+}): Promise<boolean> {+ try {+ const snapshot = await input.sandboxModule.Snapshot.get({+ ...(await resolveVercelSandboxCredentials(input.createOptions)),+ fetch: getVercelSandboxFetch(input.createOptions),+ signal: input.createOptions.signal,+ snapshotId: input.snapshotId,+ });+ return snapshot.status === "created";+ } catch (error) {+ if (isVercelSandboxMissingError(error) || isVercelSnapshotUnavailableError(error)) {+ return false;+ }+ throw new Error(+ `Failed to look up Vercel snapshot "${input.snapshotId}": ${errorMessage(error)}`,+ { cause: error },+ );+ }+}+async function getVercelSandboxGetOptions(input: {readonly createOptions: VercelCreateOptions;readonly sandboxName: string;diff --git a/packages/eve/src/execution/sandbox/bindings/vercel.test.ts b/packages/eve/src/execution/sandbox/bindings/vercel.test.tsindex b24f568cc..368aaad38 100644--- a/packages/eve/src/execution/sandbox/bindings/vercel.test.ts+++ b/packages/eve/src/execution/sandbox/bindings/vercel.test.ts@@ -1,6 +1,6 @@import { Readable } from "node:stream";-import { afterEach, beforeEach, describe, expect, it, onTestFinished, vi } from "vitest";+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";import { SandboxTemplateNotProvisionedError } from "#shared/sandbox-template-error.js";import { VERCEL_EVE_SANDBOX_IMAGE } from "#execution/sandbox/bindings/eve-image.js";@@ -47,12 +47,13 @@ function createMockDetachedCommand(function createMockSandbox(input: {name: string;snapshotId?: string;+ sourceSnapshotId?: string;status?: string;tags?: Record<string, string>;}) {const files = new Map<string, Buffer>();let tags = input.tags;- return {+ const sandbox = {currentSnapshotId: input.snapshotId ?? "",delete: vi.fn().mockResolvedValue(undefined),fs: {@@ -60,6 +61,7 @@ function createMockSandbox(input: {unlink: vi.fn().mockResolvedValue(undefined),},name: input.name,+ sourceSnapshotId: input.sourceSnapshotId,readFile: vi.fn(async (file: { path: string }): Promise<object | null> => {const content = files.get(file.path);return content === undefined ? null : Readable.from([content]);@@ -74,7 +76,11 @@ function createMockSandbox(input: {}: createMockCommandResult(),),- snapshot: vi.fn().mockResolvedValue({ snapshotId: `${input.name}-snapshot` }),+ // Like the SDK, a snapshot becomes the sandbox's `currentSnapshotId`.+ snapshot: vi.fn(async () => {+ sandbox.currentSnapshotId = `${input.name}-snapshot`;+ return { snapshotId: sandbox.currentSnapshotId };+ }),status: input.status ?? "running",stop: vi.fn().mockResolvedValue(undefined),get tags() {@@ -93,6 +99,106 @@ function createMockSandbox(input: {},),};+ return sandbox;+}++/**+ * `Sandbox.create` returning `sandboxes` in order, except that a build's+ * template pointer (named exactly by the template key) gets a fresh mock.+ */+function createSandboxesInOrder(...sandboxes: ReadonlyArray<ReturnType<typeof createMockSandbox>>) {+ const queue = [...sandboxes];+ return vi.fn(async (options: MockCreateOptions) =>+ TEMPLATE_POINTER_NAME.test(options.name)+ ? createMockSandbox({ ...mockFromCreateOptions(options), status: "stopped" })+ : queue.shift(),+ );+}++interface MockCreateOptions {+ name: string;+ source?: { snapshotId?: string; type: string };+ tags?: Record<string, string>;+}++/** What a sandbox created with `options` reports, like the SDK: its name, tags and source snapshot. */+function mockFromCreateOptions(options: MockCreateOptions) {+ return {+ name: options.name,+ sourceSnapshotId: options.source?.type === "snapshot" ? options.source.snapshotId : undefined,+ tags: options.tags,+ };+}++const TEMPLATE_POINTER_NAME = /^eve-sbx-tpl-vercel-[0-9a-f]{32}$/u;++/**+ * A Sandbox API stand-in that keeps sandboxes by name and snapshots by ID the+ * way the real one does: a taken name rejects `create` with 400, `delete`+ * removes whatever holds the name, and a snapshot outlives its sandbox.+ * `create` hands out `presets` in order before making fresh mocks.+ */+function createFakeVercelProvider(...presets: ReadonlyArray<ReturnType<typeof createMockSandbox>>) {+ const sandboxes = new Map<string, ReturnType<typeof createMockSandbox>>();+ const snapshots = new Set<string>();+ const queue = [...presets];+ const missing = () => Object.assign(new Error("Not found"), { response: { status: 404 } });+ function add(sandbox: ReturnType<typeof createMockSandbox>) {+ const name = sandbox.name;+ sandboxes.set(name, sandbox);+ sandbox.delete.mockImplementation(async () => {+ if (!sandboxes.delete(name)) throw missing();+ });+ // Stopping a sandbox someone else deleted fails like the real API: 404.+ sandbox.stop.mockImplementation(async () => {+ if (sandboxes.get(name) !== sandbox) throw missing();+ });+ sandbox.snapshot.mockImplementation(async () => {+ snapshots.add(`${name}-snapshot`);+ return { snapshotId: `${name}-snapshot` };+ });+ return sandbox;+ }+ const sandboxModule = {+ Sandbox: {+ create: vi.fn(async (options: MockCreateOptions) => {+ if (sandboxes.has(options.name)) {+ throw Object.assign(+ new Error(`A sandbox with the name '${options.name}' already exists for this project.`),+ { response: { status: 400 } },+ );+ }+ const preset = TEMPLATE_POINTER_NAME.test(options.name) ? undefined : queue.shift();+ const sandbox = preset ?? createMockSandbox(mockFromCreateOptions(options));+ sandbox.name = options.name;+ return add(sandbox);+ }),+ get: vi.fn(async (options: { name: string }) => sandboxes.get(options.name) ?? null),+ },+ Snapshot: {+ get: vi.fn(async (options: { snapshotId: string }) => {+ if (!snapshots.has(options.snapshotId)) throw missing();+ return { snapshotId: options.snapshotId, status: "created" };+ }),+ },+ };+ /** Puts a sandbox under the template key before any build runs. */+ function seedTemplate(name: string, sandbox: ReturnType<typeof createMockSandbox>) {+ sandbox.name = name;+ add(sandbox);+ }+ const pointer = () =>+ [...sandboxes.values()].find((sandbox) => TEMPLATE_POINTER_NAME.test(sandbox.name));+ return { pointer, sandboxModule, sandboxes, seedTemplate, snapshots };+}++/** The template key a build of this provider configuration uses. */+async function templateKeyOf(build: (module: object) => Promise<unknown>): Promise<string> {+ const fake = createFakeVercelProvider();+ await build(fake.sandboxModule);+ const name = fake.pointer()?.name;+ if (name === undefined) throw new Error("build published no template");+ return name;}function createVercelSandbox(input: Parameters<typeof createVercelImplementation>[0] = {}) {@@ -112,7 +218,7 @@ async function createTestVercelSession() {const sessionSandbox = createMockSandbox({ name: "session" });const sandboxModule = {Sandbox: {- create: vi.fn().mockResolvedValueOnce(templateSandbox).mockResolvedValueOnce(sessionSandbox),+ create: createSandboxesInOrder(templateSandbox, sessionSandbox),get: vi.fn().mockResolvedValue(null),},};@@ -193,10 +299,10 @@ describe("createVercelSandbox", () => {vi.stubEnv("VERCEL_TOKEN", "token_env");const sandboxModule = {Sandbox: {- create: vi- .fn()- .mockResolvedValueOnce(createMockSandbox({ name: "template" }))- .mockResolvedValueOnce(createMockSandbox({ name: "session" })),+ create: createSandboxesInOrder(+ createMockSandbox({ name: "template" }),+ createMockSandbox({ name: "session" }),+ ),get: vi.fn().mockResolvedValue(null),},};@@ -214,6 +320,11 @@ describe("createVercelSandbox", () => {const credentials = { projectId: "prj_env", teamId: "team_env", token: "token_env" };expect(sandboxModule.Sandbox.create.mock.calls.map(([options]) => options)).toEqual([expect.objectContaining({ ...credentials, image: VERCEL_EVE_SANDBOX_IMAGE }),+ // The template pointer, then the session.+ expect.objectContaining({+ ...credentials,+ source: expect.objectContaining({ type: "snapshot" }),+ }),expect.objectContaining({...credentials,source: expect.objectContaining({ type: "snapshot" }),@@ -238,7 +349,8 @@ describe("createVercelSandbox", () => {({ Sandbox: { create, get: vi.fn().mockResolvedValue(null) } }) as never,});await provider.prepare({ appRoot: "/tmp/test-app-root", ...input });- return create.mock.calls[0]?.[0].name;+ return create.mock.calls.find(([options]) => TEMPLATE_POINTER_NAME.test(options.name))?.[0]+ .name;}const first = await prepareName({ sourceRevision: "revision-a" });@@ -263,7 +375,7 @@ describe("createVercelSandbox", () => {const templateSandbox = createMockSandbox({ name: "template-key" });const sandboxModule = {Sandbox: {- create: vi.fn().mockResolvedValueOnce(templateSandbox),+ create: createSandboxesInOrder(templateSandbox),get: vi.fn().mockResolvedValueOnce(null),},};@@ -287,7 +399,7 @@ describe("createVercelSandbox", () => {const templateSandbox = createMockSandbox({ name: "template-key" });const sandboxModule = {Sandbox: {- create: vi.fn().mockResolvedValueOnce(templateSandbox),+ create: createSandboxesInOrder(templateSandbox),get: vi.fn().mockResolvedValueOnce(null),},};@@ -378,19 +490,7 @@ describe("createVercelSandbox", () => {]) as never): createMockCommandResult(),);- const sandboxModule = {- Sandbox: {- create: vi- .fn()- .mockResolvedValueOnce(templateSandbox)- .mockResolvedValueOnce(sessionSandbox),- get: vi- .fn()- .mockResolvedValueOnce(null)- .mockResolvedValueOnce(templateSandbox)- .mockResolvedValueOnce(null),- },- };+ const { sandboxModule } = createFakeVercelProvider(templateSandbox, sessionSandbox);const provider = createTestVercelSandbox({loadSandboxModule: async () => sandboxModule as never,@@ -442,10 +542,7 @@ describe("createVercelSandbox", () => {const sessionSandbox = createMockSandbox({ name: "session" });const sandboxModule = {Sandbox: {- create: vi- .fn()- .mockResolvedValueOnce(templateSandbox)- .mockResolvedValueOnce(sessionSandbox),+ create: createSandboxesInOrder(templateSandbox, sessionSandbox),get: vi.fn().mockResolvedValue(null),},};@@ -477,10 +574,7 @@ describe("createVercelSandbox", () => {it("applies a 30-minute default timeout to Sandbox.create", async () => {const templateSandbox = createMockSandbox({ name: "template" });const sessionSandbox = createMockSandbox({ name: "session" });- const create = vi- .fn()- .mockResolvedValueOnce(templateSandbox)- .mockResolvedValueOnce(sessionSandbox);+ const create = createSandboxesInOrder(templateSandbox, sessionSandbox);const sandboxModule = {Sandbox: {create,@@ -502,8 +596,9 @@ describe("createVercelSandbox", () => {sandboxName: "session-key",});- expect(create).toHaveBeenCalledTimes(2);- const [templateArgs, sessionArgs] = create.mock.calls;+ // The template, its pointer, then the session.+ expect(create).toHaveBeenCalledTimes(3);+ const [templateArgs, , sessionArgs] = create.mock.calls;expect(templateArgs?.[0]).toMatchObject({ timeout: 30 * 60 * 1_000 });expect(sessionArgs?.[0]).toMatchObject({ timeout: 30 * 60 * 1_000 });});@@ -698,57 +793,251 @@ describe("createVercelSandbox", () => {});});- it.fails("shares the template a concurrent build creates under the same name", async () => {- vi.useFakeTimers();- onTestFinished(() => {- vi.useRealTimers();+ describe("shared templates", () => {+ const buildWith = (prepare?: () => Promise<void> | void) => async (sandboxModule: object) =>+ await createTestVercelSandbox({+ loadSandboxModule: async () => sandboxModule as never,+ prepare,+ }).prepare({ appRoot: "/tmp/test-app-root", seedFiles: [] });++ /** The build-private sandboxes: everything a build created except the template pointer. */+ const privateSandboxes = (fake: ReturnType<typeof createFakeVercelProvider>) =>+ fake.sandboxModule.Sandbox.create.mock.results+ .map((result) => result.value as Promise<ReturnType<typeof createMockSandbox>>)+ .filter((_, index) => {+ const name = fake.sandboxModule.Sandbox.create.mock.calls[index]?.[0].name ?? "";+ return !TEMPLATE_POINTER_NAME.test(name);+ });++ it("lets two builds that look the template up at once both succeed", async () => {+ const fake = createFakeVercelProvider();+ let lookups = 0;+ let releaseLookups!: () => void;+ const bothLookedUp = new Promise<void>((resolve) => {+ releaseLookups = resolve;+ });+ // Both builds look the template up before either one publishes it.+ fake.sandboxModule.Sandbox.get.mockImplementation(async (options: { name: string }) => {+ const found = fake.sandboxes.get(options.name) ?? null;+ if (++lookups === 2) releaseLookups();+ await bothLookedUp;+ return found;+ });+ const build = buildWith();++ const results = await Promise.allSettled([+ build(fake.sandboxModule),+ build(fake.sandboxModule),+ ]);++ expect(results.map((result) => result.status)).toEqual(["fulfilled", "fulfilled"]);+ for (const result of results) {+ if (result.status !== "fulfilled") continue;+ expect(fake.snapshots.has(result.value.snapshotId ?? "")).toBe(true);+ }+ for (const sandbox of await Promise.all(privateSandboxes(fake))) {+ expect(sandbox.snapshot).toHaveBeenCalledTimes(1);+ }+ // Only the pointer remains: each build deleted the sandbox it prepared in.+ expect([...fake.sandboxes.keys()]).toEqual([fake.pointer()?.name]);});- const sandboxes = new Map<string, ReturnType<typeof createMockSandbox>>();- let lookups = 0;- let releaseLookups!: () => void;- const bothLookedUp = new Promise<void>((resolve) => {- releaseLookups = resolve;++ it("never prepares one sandbox for two builds", async () => {+ const fake = createFakeVercelProvider();+ let finishFirst!: () => void;+ const firstFinished = new Promise<void>((resolve) => {+ finishFirst = resolve;+ });+ const prepare = vi+ .fn<() => Promise<void>>()+ .mockImplementationOnce(async () => await firstFinished)+ .mockResolvedValue(undefined);+ const build = buildWith(prepare);++ const first = build(fake.sandboxModule);+ await vi.waitFor(() => expect(prepare).toHaveBeenCalledTimes(1));+ // The second build starts while the first is still preparing, and doesn't wait for it.+ const second = await build(fake.sandboxModule);+ finishFirst();+ const firstResult = await first;++ const [firstSandbox, secondSandbox] = await Promise.all(privateSandboxes(fake));+ expect(firstResult).toEqual({ snapshotId: `${firstSandbox?.name}-snapshot` });+ expect(second).toEqual({ snapshotId: `${secondSandbox?.name}-snapshot` });+ expect(firstSandbox?.snapshot).toHaveBeenCalledTimes(1);+ expect(secondSandbox?.snapshot).toHaveBeenCalledTimes(1);+ // The first build to finish published the template; the other kept its own snapshot.+ expect(fake.pointer()?.sourceSnapshotId).toBe(second.snapshotId);+ });++ it("reuses a published template without preparing again", async () => {+ const fake = createFakeVercelProvider();+ const prepare = vi.fn();+ const build = buildWith(prepare);++ const first = await build(fake.sandboxModule);+ const creates = fake.sandboxModule.Sandbox.create.mock.calls.length;+ const second = await build(fake.sandboxModule);++ expect(second).toEqual(first);+ expect(prepare).toHaveBeenCalledTimes(1);+ expect(fake.sandboxModule.Sandbox.create).toHaveBeenCalledTimes(creates);+ });++ it("leaves no template behind when preparation fails, so the next build prepares", async () => {+ const fake = createFakeVercelProvider();+ const prepare = vi+ .fn<() => Promise<void>>()+ .mockRejectedValueOnce(new Error("prepare failed"))+ .mockResolvedValue(undefined);+ const build = buildWith(prepare);++ await expect(build(fake.sandboxModule)).rejects.toThrow(/prepare failed/);+ expect(fake.sandboxes.size).toBe(0);++ const next = await build(fake.sandboxModule);+ expect(prepare).toHaveBeenCalledTimes(2);+ expect(fake.pointer()?.sourceSnapshotId).toBe(next.snapshotId);+ });++ it("ignores the automatic snapshot of a template whose build was abandoned", async () => {+ const templateKey = await templateKeyOf(buildWith());+ const fake = createFakeVercelProvider();+ // A persistent template sandbox Vercel snapshotted when its timeout stopped it mid-preparation.+ const abandoned = createMockSandbox({+ name: templateKey,+ snapshotId: "abandoned-auto-snapshot",+ status: "stopped",+ });+ fake.seedTemplate(templateKey, abandoned);+ fake.snapshots.add("abandoned-auto-snapshot");+ const prepare = vi.fn();++ const result = await buildWith(prepare)(fake.sandboxModule);++ expect(result.snapshotId).not.toBe("abandoned-auto-snapshot");+ expect(fake.snapshots.has(result.snapshotId ?? "")).toBe(true);+ expect(prepare).toHaveBeenCalledTimes(1);+ expect(abandoned.snapshot).not.toHaveBeenCalled();+ expect(fake.pointer()?.sourceSnapshotId).toBe(result.snapshotId);+ });++ it("lets two builds replace the same stale template without deleting each other's work", async () => {+ const templateKey = await templateKeyOf(buildWith());+ const fake = createFakeVercelProvider();+ // A pointer to a snapshot that has since expired.+ fake.seedTemplate(+ templateKey,+ createMockSandbox({+ name: templateKey,+ sourceSnapshotId: "expired",+ status: "stopped",+ }),+ );+ let lookups = 0;+ let releaseLookups!: () => void;+ const bothLookedUp = new Promise<void>((resolve) => {+ releaseLookups = resolve;+ });+ fake.sandboxModule.Sandbox.get.mockImplementation(async (options: { name: string }) => {+ const found = fake.sandboxes.get(options.name) ?? null;+ if (++lookups === 2) releaseLookups();+ await bothLookedUp;+ return found;+ });+ const build = buildWith();++ const results = await Promise.all([build(fake.sandboxModule), build(fake.sandboxModule)]);++ const snapshotIds = results.map((result) => result.snapshotId ?? "");+ expect(new Set(snapshotIds).size).toBe(2);+ for (const snapshotId of snapshotIds) expect(fake.snapshots.has(snapshotId)).toBe(true);+ for (const sandbox of await Promise.all(privateSandboxes(fake))) {+ expect(sandbox.snapshot).toHaveBeenCalledTimes(1);+ expect(sandbox.delete).toHaveBeenCalledTimes(1);+ }+ expect(snapshotIds).toContain(fake.pointer()?.sourceSnapshotId);});- const sandboxModule = {- Sandbox: {- create: vi.fn(async (options: { name: string }) => {- if (sandboxes.has(options.name)) {- throw Object.assign(- new Error(- `A sandbox with the name '${options.name}' already exists for this project.`,- ),- { response: { status: 400 } },- );- }- const template = createMockSandbox({ name: options.name });- template.snapshot.mockImplementation(async () => {- template.currentSnapshotId = `${options.name}-snapshot`;- return { snapshotId: template.currentSnapshotId };++ it("keeps a build's snapshot when another build deletes its new pointer mid-publish", async () => {+ const templateKey = await templateKeyOf(buildWith());+ const fake = createFakeVercelProvider();+ const stale = createMockSandbox({+ name: templateKey,+ sourceSnapshotId: "expired",+ status: "stopped",+ });+ fake.seedTemplate(templateKey, stale);+ let lookups = 0;+ let releaseLookups!: () => void;+ const bothLookedUp = new Promise<void>((resolve) => {+ releaseLookups = resolve;+ });+ fake.sandboxModule.Sandbox.get.mockImplementation(async (options: { name: string }) => {+ const found = fake.sandboxes.get(options.name) ?? null;+ if (++lookups === 2) releaseLookups();+ await bothLookedUp;+ return found;+ });+ /*+ * A deletes the stale pointer and creates its own; before A stops it,+ * B's delete of the stale pointer it saw removes A's new one by name.+ */+ let pointerCreated!: () => void;+ const firstPointerCreated = new Promise<void>((resolve) => {+ pointerCreated = resolve;+ });+ let staleDeletedTwice!: () => void;+ const secondStaleDelete = new Promise<void>((resolve) => {+ staleDeletedTwice = resolve;+ });+ const deleteByName = stale.delete.getMockImplementation();+ stale.delete.mockImplementation(async () => {+ if (stale.delete.mock.calls.length === 1) return await deleteByName?.();+ await firstPointerCreated;+ await deleteByName?.();+ staleDeletedTwice();+ });+ const create = fake.sandboxModule.Sandbox.create.getMockImplementation();+ let pointers = 0;+ fake.sandboxModule.Sandbox.create.mockImplementation(async (options: MockCreateOptions) => {+ const sandbox = await create!(options);+ if (TEMPLATE_POINTER_NAME.test(options.name) && ++pointers === 1) {+ const stop = sandbox.stop.getMockImplementation();+ sandbox.stop.mockImplementation(async () => {+ pointerCreated();+ await secondStaleDelete;+ await stop?.();});- sandboxes.set(options.name, template);- return template;- }),- // Both builds look the template up before either one creates it.- get: vi.fn(async (options: { name: string }) => {- const found = sandboxes.get(options.name) ?? null;- if (++lookups === 2) releaseLookups();- await bothLookedUp;- return found;- }),- },- };- const build = async () =>+ }+ return sandbox;+ });+ const build = buildWith();++ const results = await Promise.allSettled([+ build(fake.sandboxModule),+ build(fake.sandboxModule),+ ]);++ expect(results.map((result) => result.status)).toEqual(["fulfilled", "fulfilled"]);+ for (const result of results) {+ if (result.status !== "fulfilled") continue;+ expect(fake.snapshots.has(result.value.snapshotId ?? "")).toBe(true);+ }+ // The second build's pointer replaced the one it deleted.+ expect(pointers).toBe(2);+ });++ it("keeps the author's tags on the published template", async () => {+ const fake = createFakeVercelProvider();+await createTestVercelSandbox({- loadSandboxModule: async () => sandboxModule as never,+ createOptions: { tags: { team: "x" } },+ loadSandboxModule: async () => fake.sandboxModule as never,}).prepare({ appRoot: "/tmp/test-app-root", seedFiles: [] });- const builds = Promise.allSettled([build(), build()]);- await vi.runAllTimersAsync();-- const [template] = sandboxes.values();- const shared = { status: "fulfilled", value: { snapshotId: `${template?.name}-snapshot` } };- expect(await builds).toEqual([shared, shared]);- expect(template?.snapshot).toHaveBeenCalledTimes(1);+ expect(fake.pointer()?.tags).toEqual({ team: "x" });+ });});it("forwards author source to template create as the base layer", async () => {@@ -768,10 +1057,7 @@ describe("createVercelSandbox", () => {snapshotId: "author-snap",});const sessionSandbox = createMockSandbox({ name: "session" });- const create = vi- .fn()- .mockResolvedValueOnce(templateSandbox)- .mockResolvedValueOnce(sessionSandbox);+ const create = createSandboxesInOrder(templateSandbox, sessionSandbox);const sandboxModule = {Sandbox: {create,@@ -794,8 +1080,9 @@ describe("createVercelSandbox", () => {sandboxName: "session-key",});- expect(create).toHaveBeenCalledTimes(2);- const [templateArgs, sessionArgs] = create.mock.calls;+ // The template, its pointer, then the session.+ expect(create).toHaveBeenCalledTimes(3);+ const [templateArgs, , sessionArgs] = create.mock.calls;expect(templateArgs?.[0]).toMatchObject({source: { snapshotId: "author-snap", type: "snapshot" },});@@ -878,10 +1165,7 @@ describe("createVercelSandbox", () => {});const sandboxModule = {Sandbox: {- create: vi- .fn()- .mockResolvedValueOnce(templateSandbox)- .mockResolvedValueOnce(sessionSandbox),+ create: createSandboxesInOrder(templateSandbox, sessionSandbox),get: vi.fn().mockResolvedValue(null),},};@@ -919,10 +1203,7 @@ describe("createVercelSandbox", () => {const sessionSandbox = createMockSandbox({ name: "session", status: "stopped" });const sandboxModule = {Sandbox: {- create: vi- .fn()- .mockResolvedValueOnce(templateSandbox)- .mockResolvedValueOnce(sessionSandbox),+ create: createSandboxesInOrder(templateSandbox, sessionSandbox),get: vi.fn().mockResolvedValue(null),},};@@ -1003,10 +1284,7 @@ describe("createVercelSandbox", () => {const sessionSandbox = createMockSandbox({ name: "session" });const sandboxModule = {Sandbox: {- create: vi- .fn()- .mockResolvedValueOnce(templateSandbox)- .mockResolvedValueOnce(sessionSandbox),+ create: createSandboxesInOrder(templateSandbox, sessionSandbox),get: vi.fn().mockResolvedValue(null),},};@@ -1050,10 +1328,7 @@ describe("createVercelSandbox", () => {const sessionSandbox = createMockSandbox({ name: "session" });const sandboxModule = {Sandbox: {- create: vi- .fn()- .mockResolvedValueOnce(templateSandbox)- .mockResolvedValueOnce(sessionSandbox),+ create: createSandboxesInOrder(templateSandbox, sessionSandbox),get: vi.fn().mockResolvedValue(null),},};@@ -1139,10 +1414,7 @@ describe("createVercelSandbox", () => {const sessionSandbox = createMockSandbox({ name: "session" });const sandboxModule = {Sandbox: {- create: vi- .fn()- .mockResolvedValueOnce(templateSandbox)- .mockResolvedValueOnce(sessionSandbox),+ create: createSandboxesInOrder(templateSandbox, sessionSandbox),get: vi.fn().mockResolvedValue(null),},};@@ -1183,10 +1455,7 @@ describe("createVercelSandbox", () => {const sessionSandbox = createMockSandbox({ name: "session" });const sandboxModule = {Sandbox: {- create: vi- .fn()- .mockResolvedValueOnce(templateSandbox)- .mockResolvedValueOnce(sessionSandbox),+ create: createSandboxesInOrder(templateSandbox, sessionSandbox),get: vi.fn().mockResolvedValue(null),},};@@ -1228,10 +1497,7 @@ describe("createVercelSandbox", () => {const sessionSandbox = createMockSandbox({ name: "session" });const sandboxModule = {Sandbox: {- create: vi- .fn()- .mockResolvedValueOnce(templateSandbox)- .mockResolvedValueOnce(sessionSandbox),+ create: createSandboxesInOrder(templateSandbox, sessionSandbox),get: vi.fn().mockResolvedValue(null),},};@@ -1289,7 +1555,7 @@ describe("createVercelSandbox", () => {const sandboxModule = {Sandbox: {- create: vi.fn().mockResolvedValueOnce(templateSandbox),+ create: createSandboxesInOrder(templateSandbox),get: vi.fn().mockResolvedValue(null),},};@@ -1331,7 +1597,7 @@ describe("createVercelSandbox", () => {const sandboxModule = {Sandbox: {- create: vi.fn().mockResolvedValueOnce(templateSandbox),+ create: createSandboxesInOrder(templateSandbox),get: vi.fn().mockResolvedValue(null),},};diff --git a/packages/eve/src/execution/sandbox/bindings/vercel.ts b/packages/eve/src/execution/sandbox/bindings/vercel.tsindex 68d7b29fe..dc899f2b5 100644--- a/packages/eve/src/execution/sandbox/bindings/vercel.ts+++ b/packages/eve/src/execution/sandbox/bindings/vercel.ts@@ -1,3 +1,5 @@+import { randomBytes } from "node:crypto";+import type { VercelSandboxSession } from "#public/sandbox/vercel.js";import { VERCEL_EVE_SANDBOX_IMAGE } from "#execution/sandbox/bindings/eve-image.js";import {@@ -54,7 +56,10 @@ import {import { withToolSessionRetention } from "#execution/sandbox/bindings/vercel-tool-sessions.js";import { isToolSessionId } from "#execution/tool-session/id.js";import { withToolSessionSandboxes } from "#execution/tool-session/sandbox.js";-import { getNamedVercelSandbox } from "#execution/sandbox/bindings/vercel-lookup.js";+import {+ getNamedVercelSandbox,+ isVercelSnapshotCreated,+} from "#execution/sandbox/bindings/vercel-lookup.js";import {deleteUnusableVercelSandbox,deleteVercelSandbox,@@ -115,9 +120,9 @@ export function createVercelSandbox(const loadDeleteSandboxModule =input.loadDeleteSandboxModule ??(async () => await import("#compiled/@vercel/sandbox/index.js"));- const createOptions: VercelCreateOptions = {- timeout: DEFAULT_SANDBOX_TIMEOUT_MS,+ const createOptions: ResolvedVercelCreateOptions = {...input.createOptions,+ timeout: input.createOptions?.timeout ?? DEFAULT_SANDBOX_TIMEOUT_MS,};const createSandbox = input.createSandbox ?? createVercelEveImageSandbox;@@ -218,10 +223,10 @@ export function createVercelSandbox(: undefined,resources: sandboxProviderResourceIdentity(context.resources),sourceRevision: context.sourceRevision,- version: 2,+ version: 3,}).slice(0, 32)}`;try {- const outcome = await ensureTemplateWithUnavailableRetry({+ const snapshotId = await ensureTemplate({createOptions,createSandbox,loadSandboxModule,@@ -230,7 +235,7 @@ export function createVercelSandbox(seedFiles,templateKey,});- return { snapshotId: outcome.template.snapshotId };+ return { snapshotId };} catch (error) {throw new Error(`Failed to prepare Vercel sandbox snapshot: ${errorMessage(error)}`, {cause: error,@@ -266,12 +271,6 @@ export function createVercelSandbox(return withToolSessionSandboxes(implementation);}-interface VercelSandboxTemplateRecord {- readonly sandboxName: string;- readonly snapshotId: string;- readonly templateKey: string;-}-function vercelSessionName(sessionId: string,options: Readonly<VercelSandboxRuntimeOptions> | undefined,@@ -317,126 +316,158 @@ function requirePreparedVercelTemplate(return artifact.snapshotId === undefined ? {} : { snapshotId: artifact.snapshotId };}-interface EnsureTemplateOutcome {- readonly template: VercelSandboxTemplateRecord;-}-type VercelSeedFile = { readonly content: string | Uint8Array; readonly path: string };+/** Create options with the default sandbox timeout applied once. */+type ResolvedVercelCreateOptions = VercelCreateOptions & { readonly timeout: number };+interface EnsureTemplateInput {readonly prepareSandbox?: (sandbox: SandboxSession) => void | Promise<void>;- readonly createOptions: VercelCreateOptions;+ readonly createOptions: ResolvedVercelCreateOptions;readonly createSandbox: CreateVercelSandbox;readonly loadSandboxModule: () => Promise<VercelModule>;readonly log?: (message: string) => void;readonly seedFiles: ReadonlyArray<VercelSeedFile>;- readonly tags?: Record<string, string>;readonly templateKey: string;}-async function ensureTemplateWithUnavailableRetry(- input: EnsureTemplateInput,-): Promise<EnsureTemplateOutcome> {- try {- return await ensureTemplate(input);- } catch (error) {- if (!isVercelSnapshotUnavailableError(error) && !isVercelSandboxMissingError(error)) {- throw error;- }- input.log?.("cached template disappeared; rebuilding sandbox template");- return await ensureTemplate(input);- }-}-/**- * Creates or refreshes one named Vercel sandbox template and returns the- * resulting snapshot metadata along with whether an existing snapshot- * was reused. This runs only from the provider's preparation phase.+ * Returns the prepared snapshot for one template key. Builds of the same+ * revision share it through a pointer: a stopped sandbox named by the key,+ * created from a snapshot that finished preparing. Preparation itself runs+ * in a private sandbox no other build can see, so nothing under the shared+ * name ever holds unfinished work, and deleting a stale pointer can never+ * remove another build's preparation.*/-async function ensureTemplate(input: EnsureTemplateInput): Promise<EnsureTemplateOutcome> {+async function ensureTemplate(input: EnsureTemplateInput): Promise<string> {const sandboxModule = await input.loadSandboxModule();- let sandbox = await getNamedVercelSandbox({+ const pointer = await getNamedVercelSandbox({createOptions: input.createOptions,sandboxModule,sandboxName: input.templateKey,});- const tags = resolveVercelSandboxTags(input.createOptions.tags, input.tags);- const authorSnapshotId = extractAuthorSnapshotId(input.createOptions);-- if (sandbox !== null && isUnprovisionedTerminalTemplateSandbox(sandbox, authorSnapshotId)) {- await sandbox.delete();- sandbox = null;- }-- if (sandbox === null) {- sandbox = await input.createSandbox({+ const publishedSnapshotId = pointer?.sourceSnapshotId;+ if (+ publishedSnapshotId !== undefined &&+ (await isVercelSnapshotCreated({+ createOptions: input.createOptions,sandboxModule,- createOptions: withBaseSetupNetworkPolicy({- ...input.createOptions,- name: input.templateKey,- persistent: true,- tags: tags,- }),- });- } else {- await ensureVercelSandboxTags(sandbox, tags);+ snapshotId: publishedSnapshotId,+ }))+ ) {+ input.log?.("reusing prepared sandbox template");+ return publishedSnapshotId;}+ const snapshotId = await prepareTemplateSnapshot(input, sandboxModule);/*- * A non-empty `currentSnapshotId` normally means "this template was- * prewarmed in a previous run — reuse it." But with an author-supplied- * `source: snapshot`, the SDK pre-populates `currentSnapshotId` with- * the *author's* snapshotId both on a fresh create and on every- * subsequent `getNamedSandbox` reuse until we run our own snapshot.- * So we ignore that exact value: it's the author's base layer, not a- * framework snapshot, and we still owe `ensureSandboxWorkingDirectory`,- * preparation, seed file writes, and `sandbox.snapshot()` on top.+ * The pointer only saves later builds a preparation; this build's snapshot+ * is already valid. So publishing never fails the build, including when a+ * build replacing the same stale pointer deletes this one mid-publish.*/- const frameworkSnapshotId =- typeof sandbox.currentSnapshotId === "string" &&- sandbox.currentSnapshotId.length > 0 &&- sandbox.currentSnapshotId !== authorSnapshotId- ? sandbox.currentSnapshotId- : null;-- if (frameworkSnapshotId !== null) {- return {- template: {- sandboxName: sandbox.name,- snapshotId: frameworkSnapshotId,- templateKey: input.templateKey,- },- };- }-- input.log?.("preparing base runtime inside sandbox");- await ensureVercelSandboxBaseRuntime(sandbox);- await applyInitialVercelNetworkPolicy(sandbox, input.createOptions.networkPolicy);-- const templateSession = buildSandboxSession(- createVercelInternalSandboxSession(sandbox, input.createOptions.env),- createVercelNetworkPolicySetter(sandbox),+ await publishTemplatePointer(input, sandboxModule, pointer, snapshotId).catch(+ (error: unknown) => {+ input.log?.(`could not publish sandbox template: ${errorMessage(error)}`);+ },);+ return snapshotId;+}- await writeVercelSandboxSeedFiles({- sandbox,- seedFiles: input.seedFiles,- session: templateSession,+/** Prepares the template in a sandbox only this build knows, and returns its snapshot. */+async function prepareTemplateSnapshot(+ input: EnsureTemplateInput,+ sandboxModule: VercelModule,+): Promise<string> {+ /*+ * Not persistent: a sandbox this build abandons (killed, timed out) is+ * discarded without an automatic snapshot, and its name is unique, so no+ * other build ever finds it.+ */+ const sandbox = await input.createSandbox({+ sandboxModule,+ createOptions: withBaseSetupNetworkPolicy({+ ...input.createOptions,+ name: `${input.templateKey}-${randomBytes(4).toString("hex")}`,+ persistent: false,+ }),});+ try {+ input.log?.("preparing base runtime inside sandbox");+ await ensureVercelSandboxBaseRuntime(sandbox);+ await applyInitialVercelNetworkPolicy(sandbox, input.createOptions.networkPolicy);++ const templateSession = buildSandboxSession(+ createVercelInternalSandboxSession(sandbox, input.createOptions.env),+ createVercelNetworkPolicySetter(sandbox),+ );++ await writeVercelSandboxSeedFiles({+ sandbox,+ seedFiles: input.seedFiles,+ session: templateSession,+ });- input.log?.("running sandbox preparation");- await input.prepareSandbox?.(- createLoggingSandboxSession({ log: input.log, session: templateSession }),- );+ input.log?.("running sandbox preparation");+ await input.prepareSandbox?.(+ createLoggingSandboxSession({ log: input.log, session: templateSession }),+ );++ // The returned snapshot, not the handle's cached `currentSnapshotId`, which the SDK may not refresh.+ return (await sandbox.snapshot()).snapshotId;+ } finally {+ /*+ * A snapshot outlives its source sandbox, so the private sandbox is never+ * needed again. Failing to delete it doesn't change this build's result:+ * it's not persistent, and no other build looks it up.+ */+ await sandbox.delete().catch((error: unknown) => {+ input.log?.(`could not delete sandbox ${sandbox.name}: ${errorMessage(error)}`);+ });+ }+}- const snapshot = await sandbox.snapshot();- return {- template: {- sandboxName: sandbox.name,- snapshotId: snapshot.snapshotId,- templateKey: input.templateKey,- },- };+/**+ * Records a finished snapshot under the template key, replacing a stale+ * pointer. When another build published first, its snapshot is as valid as+ * this one, and this build keeps its own: there is nothing to read back.+ */+async function publishTemplatePointer(+ input: EnsureTemplateInput,+ sandboxModule: VercelModule,+ stalePointer: VercelSandbox | null,+ snapshotId: string,+): Promise<void> {+ if (stalePointer !== null) {+ try {+ await stalePointer.delete();+ } catch (error) {+ // Another build that saw the same stale pointer deleted it first.+ if (!isVercelSandboxMissingError(error)) throw error;+ }+ }+ // A snapshot source excludes `image`, `runtime`, and any authored source.+ const {+ image: _image,+ runtime: _runtime,+ source: _source,+ ...createOptions+ } = input.createOptions;+ let pointer: VercelSandbox;+ try {+ pointer = await input.createSandbox({+ sandboxModule,+ createOptions: {+ ...createOptions,+ name: input.templateKey,+ persistent: false,+ source: { snapshotId, type: "snapshot" },+ },+ });+ } catch (error) {+ if (isVercelSandboxNameConflictError(error)) return;+ throw error;+ }+ await stopVercelSandbox(pointer);}interface EnsureSessionInput {@@ -680,38 +711,6 @@ async function resolveVercelWritePath(return resolved;}-function isUnprovisionedTerminalTemplateSandbox(- sandbox: VercelSandbox,- authorSnapshotId: string | undefined,-): boolean {- const currentSnapshotId = sandbox.currentSnapshotId;- if (- typeof currentSnapshotId === "string" &&- currentSnapshotId.length > 0 &&- currentSnapshotId !== authorSnapshotId- ) {- return false;- }-- return (- sandbox.status === "aborted" || sandbox.status === "failed" || sandbox.status === "stopped"- );-}--/**- * Pulls the snapshotId out of an author-supplied `source: { type:- * "snapshot", ... }`. Returns undefined for git/tarball sources or when- * no source was supplied — those don't seed `currentSnapshotId` with a- * pre-existing value the way snapshot sources do.- */-function extractAuthorSnapshotId(createOptions: VercelCreateOptions): string | undefined {- const source = createOptions.source;- if (source?.type === "snapshot" && typeof source.snapshotId === "string") {- return source.snapshotId;- }- return undefined;-}-/*** 30 minutes. The `@vercel/sandbox` SDK defaults to 5 minutes which is* too short for multi-step workflows — the VM expires between steps.