Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

fix(eve): preserve bootstrap sandbox keys without seed files (#3170)

Ruidc73dee2b52d
diff --git a/.changeset/stable-empty-sandbox-seeds.md b/.changeset/stable-empty-sandbox-seeds.md
new file mode 100644
index 000000000..9a61289e8
--- /dev/null
+++ b/.changeset/stable-empty-sandbox-seeds.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Keep sandbox template and session keys stable across unrelated agent changes when bootstrap has no skill or workspace seed files. Existing affected sandboxes switch to the corrected key on first use after upgrading.
diff --git a/docs/sandbox.mdx b/docs/sandbox.mdx
index 88de347a5..7dca8b56a 100644
--- a/docs/sandbox.mdx
+++ b/docs/sandbox.mdx
@@ -289,6 +289,8 @@ Custom backend handles implement the same boundary in `delete()`: remove the ses
Session sandboxes are keyed per durable session, not per deployment, so redeploying your app does not by itself discard them. A definition change to the authored sandbox source, workspace seed content, or `revalidationKey` replaces the sandbox on the next turn and runs `onSession` again.
+For sandboxes with `bootstrap`, unrelated agent changes preserve the template and session sandbox keys even when there are no skill or workspace seed files. You do not need to add a seed file or `revalidationKey` solely to preserve reuse across those changes.
+
Reattachment still depends on the backend retaining its physical sandbox state. If a persisted Vercel sandbox is no longer available, eve creates a replacement, using the current template when one is configured. Files and other changes made after the original sandbox was created are not restored automatically. Because the durable session still has the same sandbox key, `onSession` does not run again for this replacement. Persist important artifacts outside the sandbox, and do not rely on `onSession` as the only place that applies security-critical configuration.
When the eve server stops, no sandbox compute outlives it. `eve dev` stops the sandboxes it started when the dev server closes, and a self-hosted production server stops every open sandbox on shutdown (`SIGTERM`/`SIGINT`). Session state persists across the stop — the next server start reattaches each durable session from its stopped container, VM, or snapshot. Custom `SandboxBackend` adapters implement `stop()` for authored runtime calls and `shutdown()` for server teardown. Both stop the underlying compute while keeping the session reattachable from persisted state where the backend supports it; authored `stop()` failures reject, while process-wide shutdown collects and logs failures without blocking teardown.
diff --git a/packages/eve/src/execution/sandbox/prewarm.scenario.test.ts b/packages/eve/src/execution/sandbox/prewarm.scenario.test.ts
index 779c6acef..ca714cb1c 100644
--- a/packages/eve/src/execution/sandbox/prewarm.scenario.test.ts
+++ b/packages/eve/src/execution/sandbox/prewarm.scenario.test.ts
@@ -348,6 +348,44 @@ describe("prewarmAppSandboxes", () => {
expect(firstEvents.bootstrapCommands).toEqual(["echo bootstrap-revalidation-key"]);
});
+ it("keeps unseeded bootstrap templates stable across deploy roots and instruction changes", async () => {
+ vi.stubEnv("VERCEL", "1");
+ vi.stubEnv("VERCEL_PROJECT_ID", "prj_bootstrap_templates");
+ vi.stubEnv("VERCEL_DEPLOYMENT_ID", "dpl_bootstrap_empty_one");
+
+ const firstAppRoot = await createBootstrapRevalidationKeyAppRoot({
+ revalidationKeyExpression: undefined,
+ });
+ const firstEvents = createPrewarmEvents();
+ const first = await compileAgent({ startPath: firstAppRoot });
+ await prewarmAppSandboxes({
+ appRoot: firstAppRoot,
+ dispatch: createRecordingDispatch(firstEvents),
+ });
+
+ vi.stubEnv("VERCEL_DEPLOYMENT_ID", "dpl_bootstrap_empty_two");
+ const secondAppRoot = await createBootstrapRevalidationKeyAppRoot({
+ revalidationKeyExpression: undefined,
+ });
+ await writeFile(join(secondAppRoot, "agent", "instructions.md"), "Changed system prompt.\n");
+ const secondEvents = createPrewarmEvents();
+ const second = await compileAgent({ startPath: secondAppRoot });
+ await prewarmAppSandboxes({
+ appRoot: secondAppRoot,
+ dispatch: createRecordingDispatch(secondEvents),
+ });
+
+ expect(first.manifest.workspaceResourceRoot.contentHash).toBeUndefined();
+ expect(second.manifest.workspaceResourceRoot.contentHash).toBeUndefined();
+ expect(second.metadata.discovery.sourceGraphHash).not.toBe(
+ first.metadata.discovery.sourceGraphHash,
+ );
+ expect(firstEvents.templateKeys).toHaveLength(1);
+ expect(secondEvents.templateKeys).toEqual(firstEvents.templateKeys);
+ expect(firstEvents.seededFilePaths).toEqual([]);
+ expect(secondEvents.seededFilePaths).toEqual([]);
+ });
+
it("uses authored sandbox source when bootstrap omits revalidationKey", async () => {
vi.stubEnv("VERCEL", "1");
vi.stubEnv("VERCEL_PROJECT_ID", "prj_bootstrap_templates");
@@ -752,7 +790,7 @@ async function createSkillOnlyAppRoot(input: { readonly skillBody: string }): Pr
async function createBootstrapRevalidationKeyAppRoot(input: {
readonly bootstrapCommand?: string;
readonly revalidationKeyExpression: string | undefined;
- readonly skillBody: string;
+ readonly skillBody?: string;
}): Promise<string> {
const appRoot = await createScratchDirectory("eve-prewarm-bootstrap-revalidation-key-");
const agentRoot = join(appRoot, "agent");
@@ -760,9 +798,6 @@ async function createBootstrapRevalidationKeyAppRoot(input: {
await mkdir(join(agentRoot, "sandbox"), {
recursive: true,
});
- await mkdir(join(agentRoot, "skills"), {
- recursive: true,
- });
await writeFile(
join(appRoot, "package.json"),
JSON.stringify(
@@ -776,10 +811,13 @@ async function createBootstrapRevalidationKeyAppRoot(input: {
);
await writeFile(join(agentRoot, "agent.ts"), 'export default { model: "openai/gpt-5.4" };\n');
await writeFile(join(agentRoot, "instructions.md"), "Root system prompt.\n");
- await writeFile(
- join(agentRoot, "skills", "route-weather.md"),
- ["---", "description: Route weather requests.", "---", input.skillBody].join("\n"),
- );
+ if (input.skillBody !== undefined) {
+ await mkdir(join(agentRoot, "skills"), { recursive: true });
+ await writeFile(
+ join(agentRoot, "skills", "route-weather.md"),
+ ["---", "description: Route weather requests.", "---", input.skillBody].join("\n"),
+ );
+ }
await writeBootstrapRevalidationKeySandbox({
appRoot,
bootstrapCommand: input.bootstrapCommand,
diff --git a/packages/eve/src/runtime/sandbox/keys.test.ts b/packages/eve/src/runtime/sandbox/keys.test.ts
index 2621ad785..b030a8bbd 100644
--- a/packages/eve/src/runtime/sandbox/keys.test.ts
+++ b/packages/eve/src/runtime/sandbox/keys.test.ts
@@ -15,6 +15,7 @@ import {
createRuntimeSandboxKeys,
createRuntimeSandboxTemplateKey,
} from "#runtime/sandbox/keys.js";
+import type { RuntimeSandboxTemplatePlan } from "#runtime/sandbox/template-plan.js";
const RUNTIME_SANDBOX_CONTRACT_VERSION = 7;
@@ -94,6 +95,22 @@ async function deriveSessionKey(input?: {
return keys.sessionKey;
}
+async function deriveBootstrapKeys(
+ templatePlan: Extract<RuntimeSandboxTemplatePlan, { kind: "bootstrap" }> = {
+ kind: "bootstrap",
+ sourceHash: "sandbox-source-v1",
+ },
+) {
+ return await createRuntimeSandboxKeys({
+ backendName: "vercel",
+ compiledArtifactsSource: createBundledRuntimeCompiledArtifactsSource(),
+ nodeId: "__root__",
+ sessionId: "session_1",
+ sourceId: "sandbox.ts",
+ templatePlan,
+ });
+}
+
/**
* Derives one vercel-backed session key under exactly the given env.
* Unlisted project and deployment variables are stubbed empty so ambient
@@ -178,6 +195,50 @@ describe("createRuntimeSandboxKeys", () => {
expect(first).not.toBe(second);
});
+
+ it("keeps unseeded bootstrap template and session keys stable across unrelated source changes", async () => {
+ vi.stubEnv("VERCEL_PROJECT_ID", "prj_123");
+ const metadata = createMetadataFixture("1.0.0");
+ const first = await withBundledMetadata(metadata, () => deriveBootstrapKeys());
+ const second = await withBundledMetadata(
+ {
+ ...metadata,
+ discovery: { ...metadata.discovery, sourceGraphHash: "f".repeat(64) },
+ },
+ () => deriveBootstrapKeys(),
+ );
+
+ expect(first.templateKey).not.toBeNull();
+ expect(second).toEqual(first);
+ });
+
+ it("does not use missing compile metadata as unseeded bootstrap content", async () => {
+ vi.stubEnv("VERCEL_PROJECT_ID", "prj_123");
+ const metadata = createMetadataFixture(resolveInstalledPackageInfo().version);
+ const withMetadata = await withBundledMetadata(metadata, () => deriveBootstrapKeys());
+ const withoutMetadata = await withBundledMetadata(undefined, () => deriveBootstrapKeys());
+
+ expect(withoutMetadata).toEqual(withMetadata);
+ });
+
+ it.each([
+ { sourceHash: "sandbox-source-v2" },
+ { revalidationKey: "bootstrap-v2" },
+ { contentHash: CONTENT_HASH },
+ ])("rotates both bootstrap keys when sandbox inputs change: %j", async (change) => {
+ vi.stubEnv("VERCEL_PROJECT_ID", "prj_123");
+ await withBundledMetadata(createMetadataFixture("1.0.0"), async () => {
+ const first = await deriveBootstrapKeys();
+ const second = await deriveBootstrapKeys({
+ kind: "bootstrap",
+ sourceHash: "sandbox-source-v1",
+ ...change,
+ });
+
+ expect(second.templateKey).not.toBe(first.templateKey);
+ expect(second.sessionKey).not.toBe(first.sessionKey);
+ });
+ });
});
describe("createRuntimeSandboxTemplateKey", () => {
diff --git a/packages/eve/src/runtime/sandbox/keys.ts b/packages/eve/src/runtime/sandbox/keys.ts
index df77074a9..1333cee13 100644
--- a/packages/eve/src/runtime/sandbox/keys.ts
+++ b/packages/eve/src/runtime/sandbox/keys.ts
@@ -92,8 +92,6 @@ async function deriveRuntimeSandboxKeyParts(input: {
input.templatePlan.kind === "none"
? null
: resolveRuntimeSandboxVersionHash({
- compiledArtifactsSource: input.compiledArtifactsSource,
- metadata,
nodeId: input.nodeId,
sourceId: input.sourceId,
templatePlan: input.templatePlan,
@@ -206,15 +204,12 @@ async function resolveRuntimeSandboxScope(input: {
}
function resolveRuntimeSandboxVersionHash(input: {
- readonly compiledArtifactsSource: RuntimeCompiledArtifactsSource;
- readonly metadata: CompileMetadata | null;
readonly nodeId: string;
readonly sourceId: string;
readonly templatePlan: Exclude<RuntimeSandboxTemplatePlan, { readonly kind: "none" }>;
}): string {
- const contentHash =
- input.templatePlan.contentHash ??
- resolveSourceGraphHash(input.metadata, input.compiledArtifactsSource);
+ // No seed files means empty content, independent of unrelated application source.
+ const contentHash = input.templatePlan.contentHash ?? "";
if (input.templatePlan.kind === "bootstrap") {
const revalidationKey = input.templatePlan.revalidationKey ?? "";
@@ -226,16 +221,6 @@ function resolveRuntimeSandboxVersionHash(input: {
return createStableHash(`workspace-content:${contentHash}:${input.nodeId}:${input.sourceId}`);
}
-function resolveSourceGraphHash(
- metadata: CompileMetadata | null,
- compiledArtifactsSource: RuntimeCompiledArtifactsSource,
-): string {
- return (
- metadata?.discovery.sourceGraphHash ??
- getRuntimeCompiledArtifactsCacheKey(compiledArtifactsSource)
- );
-}
-
function createStableHash(value: string): string {
return createHash("sha256").update(value).digest("hex");
}