fix(eve)!: make the Upstash Box sandbox backend actually usable (#6)

* refactor(eve)!: sandbox config is Box's BoxConfig (drop vcpus/networkPolicy knobs)

The `upstash()` sandbox backend invented Vercel-shaped config (`resources.vcpus`,
runtime strings like "node24", an Eve-shaped `networkPolicy`) that didn't match
Upstash Box. Take the real `@upstash/box` `BoxConfig` verbatim instead.

- `UpstashBackendConfig = Omit<BoxConfig, "networkPolicy">` — pass `runtime`,
  `size`, `apiKey`, `keepAlive`, `initCommand`, `env`, `skills`, `mcpServers`,
  `timeout`, … exactly as you would to `Box.create({...})`. Removed the
  `resources.vcpus`→size mapping and the runtime-string coercion (use Box's
  `Runtime`/`BoxSize` directly).
- `networkPolicy` is no longer a config knob: egress is enforced deny-all
  atomically at creation (folded into `boxConfig()`, dropping the extra
  post-create `updateNetworkPolicy` round-trips) and opened only per-session via
  Eve's `use({ networkPolicy })`. Reworked the live egress test to open via the
  session `use()` flow.
- Updated the eve README, eve-demo sandbox, and docstring examples; folded into
  the pending harden-tenant-isolation changeset.

* fix(eve): reuse prewarmed Box snapshots via Redis; bridge /workspace path

Two sandbox bugs surfaced running an agent against Upstash Box.

1. Two boxes were created and the first (prewarmed) one was unused — its seed
   files never reached the session. `prewarm` (build/startup) recorded the
   template snapshot only in an in-memory map, which `create` (a different
   process, per request) can't see; Box has no static snapshot lookup, so create
   always fell back to a fresh, empty `Box.create`. Store `templateKey → snapshotId`
   in a durable Redis registry (`agentkit:sandbox:template:<name>:<templateKey>`,
   `redis` defaults to `Redis.fromEnv()`) so create restores the prewarmed
   snapshot. `prewarm` also no longer builds a throwaway box when there's nothing
   to bake (no seed files / bootstrap), and stale-snapshot restores fall back to
   a fresh box.

2. The agent ran `find /workspace …` but Box sessions live in `/workspace/home`
   (`/workspace` is off-limits). Eve hardcodes `/workspace` as its tool root, so
   the backend now bridges it to `/workspace/home` in both `resolvePath` (file
   ops) and raw commands (exported `toBoxPath` / `rewriteWorkspacePaths`).

Config gains optional `redis`/`templatePrefix` (stripped before `Box.create`).
Added offline path-bridge tests and a live Box+Redis test proving a second
backend instance reuses the prewarmed snapshot. Updated README, docstrings,
CLAUDE.md, and the changeset.

* fix(eve): reuse one Box per session; fix dispose/keepAlive; URL-safe path rewrite

Running an agent against Box created a new box on every session open (the logs
showed three "opening sandbox session" per turn).

- `create` now reattaches to the box from `input.existingMetadata.boxId`
  (`Box.get`) before falling back to the template snapshot or a fresh box. Eve
  re-opens a session many times per turn and hands back the box id we record in
  `captureState`, so without this every open spun a new box.
- `dispose` is now a no-op (matching Eve's Vercel backend): the box must survive
  for the next open to reattach. The old `dispose` called `box.pause()`, which
  THROWS for keep-alive boxes ("Keep-alive boxes cannot be paused"), so it both
  failed and defeated reuse.
- `keepAlive` now defaults to `false` (Box's pause-based idle lifecycle): idle
  boxes auto-pause and are reaped, so a no-op dispose doesn't leak. `true` opts
  into an always-running box the caller manages.
- `rewriteWorkspacePaths` is now URL-safe: a lookbehind stops it rewriting
  `/workspace` inside URLs/relative paths (e.g. `curl host/workspace/x`), while
  still mapping genuine `/workspace` path tokens to `/workspace/home`.

Added live tests for box reuse across opens and for the URL-safe rewrite; live
tests now delete boxes explicitly since dispose no longer does. Updated README,
docstrings, CLAUDE.md, and the changeset.

Author: CahidArda

.changeset/harden-tenant-isolation.md

@@ -12,7 +12,9 @@ Tenant-isolation hardening, a type-safe reactive search index, and a consistent
 - `AgentMemory` requires a non-empty `userId` on every call (no silent shared bucket) and rejects a `:` in `userId`; `add`/`recall` take a single object param.
 - `ToolCache` keys are `<prefix>:<userId>:<toolName>:<hash>` — scoped per user, then per tool; `userId`/`toolName` are rejected if they contain `:`.
 - `createRateLimit`/`createRateLimitAuth` require an explicit `limiter` (removed `limit`/`window`); eve's `createRateLimitAuth` requires `identifier` (no implicit global bucket) and counts only `POST` requests, so a turn (a message `POST` plus its follow-up stream `GET`) is charged once, not twice.
-- The eve sandbox denies network egress by default.
+- The eve sandbox denies network egress by default. Its `upstash()` backend config is now the `@upstash/box` `BoxConfig` passed through verbatim (`runtime`/`size`/`apiKey`/`keepAlive`/`initCommand`/`env`/`skills`/…) plus an optional `redis`/`templatePrefix` — the invented `resources.vcpus` hint and runtime-string coercion (`"node24"`) are removed (use `runtime`/`size` as Box expects), and `networkPolicy` is no longer a config knob (egress is governed by the deny-all default plus per-session `use({ networkPolicy })`).
+- The eve sandbox now reuses prewarmed Box snapshots correctly: the `templateKey → snapshotId` map is stored in a durable Redis registry (Box has no static snapshot lookup, and `prewarm`/`create` run in different processes), so `create` restores the prewarmed template instead of spinning a fresh, empty box. `prewarm` builds no box when there's nothing to bake. It also bridges Eve's `/workspace` root to Box's `/workspace/home` working directory in both file ops and raw commands, so the agent's `find`/`grep`/file tools hit the right directory.
+- The eve sandbox now reuses one box per conversation instead of creating a new box on every session open: `create` reattaches to the box from `existingMetadata` (Eve re-opens a session many times per turn) and `dispose` no longer tears the box down. `keepAlive` defaults to `false` (Box's pause-based idle lifecycle), so idle boxes are auto-paused/reaped rather than leaked.
 
 **Reactive search index**
 

CLAUDE.md

@@ -232,6 +232,22 @@ pnpm -r --filter "./examples/*" build   # build both demo apps
   `create`→`Box.fromSnapshot` (or fresh `Box.create`), returning a `SandboxBackendHandle` whose
   `session` is a full `SandboxSession` built over Box (run/spawn/read*/write*/setNetworkPolicy/removePath).
   Typechecks against eve and the offline + live-Box `sandbox.test.ts` pass. `spawn` runs to completion
-  then replays output as streams (Box has no detached-process primitive). Not exercised by `eve-demo`.
+  then replays output as streams (Box has no detached-process primitive). Config is **`UpstashBackendConfig
+  = Omit<BoxConfig, "networkPolicy"> & { redis?, templatePrefix? }`** — the real `@upstash/box` `BoxConfig`
+  passed through verbatim (`runtime`/`size`/`apiKey`/`keepAlive`/`initCommand`/`env`/`skills`/…), **no**
+  invented `resources.vcpus` hint or runtime-string coercion. `networkPolicy` is intentionally excluded:
+  egress is enforced deny-all at creation (in `boxConfig()`) and opened only per-session via Eve's
+  `use({ networkPolicy })`. **Template registry:** `prewarm` (build/startup) and `create` (per request)
+  run in different processes, so the `templateKey → snapshotId` map lives in a **durable Redis registry**
+  (`agentkit:sandbox:template:<name>:<templateKey>`, `redis` defaults to `Redis.fromEnv()`) — an in-memory
+  map orphaned the prewarmed box (the old "two boxes, first unused" bug) and Box has no static snapshot
+  lookup. `prewarm` builds **no** box when there's nothing to bake (no seed files/bootstrap). **Session
+  reuse:** `create` reattaches to the box from `input.existingMetadata.boxId` (`Box.get`) — Eve re-opens a
+  session many times and hands our captured `boxId` back, so without this every open spun a fresh box (the
+  "3 boxes per turn" bug). `dispose` is a **no-op** (the box persists for reuse; Box's idle lifecycle reaps
+  it), and `keepAlive` defaults to **false** (pause-based idle; `true` can't be paused and runs until
+  deleted). **Path bridge:** Eve roots its tools at `/workspace` but Box sessions live in `/workspace/home`,
+  so the backend remaps both `resolvePath` (file ops) and raw commands (`find /workspace …` →
+  `/workspace/home`, URL-safe via lookbehind) through the exported `toBoxPath`/`rewriteWorkspacePaths`.
 - `gpt-5.4-mini` (demo model) may not exist → demos build fine but can 404 at runtime. Swap if needed.
 - The `19.2.17` `@types/react` may linger as an unpruned orphan in `.pnpm`; harmless (nothing links it).

examples/eve-demo/agent/sandbox/sandbox.ts

@@ -14,10 +14,12 @@ import { upstash } from "@upstash/agentkit-eve/sandbox";
 export default defineSandbox({
   // `upstash()` is a drop-in replacement for eve's `vercel()` backend.
   backend: upstash({
-    runtime: "node24", // optional: Box runtime; eve-style strings ("node24") map to Box's "node"
-    resources: { vcpus: 2 }, // optional: vcpu hint mapped to a Box size (2 -> small)
-    // optional: name, apiKey (defaults to UPSTASH_BOX_API_KEY), size, keepAlive,
-    // initCommand, env, networkPolicy
+    // The Upstash Box `BoxConfig`, verbatim (whatever you'd pass to `Box.create({...})`):
+    runtime: "node", // optional: Box runtime (node | python | golang | ruby | rust)
+    size: "small", // optional: Box resource size (small | medium | large)
+    // optional: name, apiKey (defaults to UPSTASH_BOX_API_KEY), keepAlive,
+    // initCommand, env, skills, mcpServers, timeout, … — all BoxConfig fields.
+    // (networkPolicy is not a config knob — egress is deny-all by default, set per-session below.)
   }),
   // optional: durable-session-scoped, runs once per session. A good place to lock
   // down the network before the agent runs any commands. (Add a `bootstrap` hook

packages/eve/README.md

@@ -131,9 +131,12 @@ import { upstash } from "@upstash/agentkit-eve/sandbox"; // was: import { vercel
 
 export default defineSandbox({
   backend: upstash({
-    runtime: "node24", // the Upstash Box runtime (node | python | golang | ruby | rust)
-    resources: { vcpus: 2 }, // optional: requested resources
+    // The Upstash Box `BoxConfig`, verbatim — whatever you'd pass to `Box.create({...})`:
+    runtime: "node", // the Box runtime (node | python | golang | ruby | rust)
+    size: "medium", // optional: Box resource size (small | medium | large)
+    // env: { ... }, initCommand, keepAlive, skills, mcpServers, timeout, … — all BoxConfig fields
     // apiKey, // optional: Upstash Box API key (defaults to UPSTASH_BOX_API_KEY)
+    // (networkPolicy is NOT a config knob — egress is deny-all by default, opened per-session below)
   }),
   revalidationKey: () => "repo-bootstrap-v1",
   async bootstrap({ use }) {
@@ -149,13 +152,27 @@ export default defineSandbox({
 
 > **Network egress is denied by default.** The sandbox runs untrusted, model-generated code, so open
 > egress would mean SSRF / data exfiltration / reaching your own infrastructure from inside the box.
-> Pass a `networkPolicy` (on the backend, in `bootstrap`'s `use(...)`, or in the session `use(...)`)
-> to allow it. Note that `env` passed to `upstash({ env })` is readable by code running in the box —
-> don't pass secrets you wouldn't want that code to see.
+> Open it per-session — in `bootstrap`'s `use(...)` or the session `use(...)` — never as a config knob.
+> Note that `env` passed to `upstash({ env })` is readable by code running in the box — don't pass
+> secrets you wouldn't want that code to see.
 
 Set `UPSTASH_BOX_API_KEY` (or pass `apiKey`). `@upstash/box` is an optional peer dependency — only
 needed when you import `@upstash/agentkit-eve/sandbox`.
 
+> **Template registry uses Redis.** Eve builds your sandbox template (seed files + `bootstrap`) at
+> build/startup via `prewarm`, but `create` runs per request in a different process — so the built
+> snapshot's id is stored in a durable Redis registry (`redis` defaults to `Redis.fromEnv()`; override
+> with `upstash({ redis })`). Without it, `create` couldn't find the prewarmed snapshot and would spin a
+> fresh, empty box every time (Box has no cross-process snapshot lookup). Eve roots its file/`find`/`grep`
+> tools at `/workspace`; a Box session lives at `/workspace/home`, and the backend bridges the two
+> automatically.
+
+> **One box per conversation.** Eve re-opens a sandbox session several times per turn; the backend
+> reattaches to the same Box (via the box id it captured) instead of creating a new one each time. Boxes
+> default to Box's pause-based idle lifecycle (`keepAlive: false`) — auto-paused when idle, resumed on
+> reattach, reaped by Box — so nothing leaks. Pass `upstash({ keepAlive: true })` only if you want an
+> always-running box you manage yourself.
+
 ## Cached tools (`agent/tools/*.ts`)
 
 `defineCachedTool` is like Eve's `defineTool`, but its result is memoized — pass a `toolName` and a

packages/eve/src/sandbox.test.ts

@@ -1,6 +1,8 @@
 import { config } from "dotenv";
 import { describe, expect, it } from "vitest";
-import { upstash } from "./sandbox.js";
+import { Box } from "@upstash/box";
+import { rewriteWorkspacePaths, toBoxPath, upstash } from "./sandbox.js";
+import { hasRedisCreds, testRedis, uniquePrefix } from "./test-support.js";
 
 config(); // load repo-root .env for UPSTASH_BOX_API_KEY
 const hasBoxCreds = Boolean(process.env.UPSTASH_BOX_API_KEY);
@@ -13,52 +15,149 @@ const createInput = {
 
 describe("upstash() backend (offline)", () => {
   it("implements Eve's two-phase SandboxBackend", () => {
-    const backend = upstash({ runtime: "node24", resources: { vcpus: 2 } });
+    const backend = upstash({ runtime: "node", size: "small" });
     expect(backend.name).toBe("upstash");
     expect(typeof backend.create).toBe("function");
     expect(typeof backend.prewarm).toBe("function");
   });
+
+  // Eve roots its tools at /workspace; a Box session lives in /workspace/home.
+  it("bridges Eve's /workspace paths to Box's /workspace/home", () => {
+    expect(toBoxPath("note.txt")).toBe("/workspace/home/note.txt"); // relative → under home
+    expect(toBoxPath("/workspace")).toBe("/workspace/home"); // the root itself
+    expect(toBoxPath("/workspace/sub/a.js")).toBe("/workspace/home/sub/a.js"); // nested
+    expect(toBoxPath("/workspace/home/x")).toBe("/workspace/home/x"); // already box-rooted (no double-map)
+    expect(toBoxPath("/tmp/x")).toBe("/tmp/x"); // unrelated absolute → untouched
+  });
+
+  it("rewrites /workspace inside raw commands (Eve's find/grep tools)", () => {
+    expect(rewriteWorkspacePaths("find /workspace -type f")).toBe("find /workspace/home -type f");
+    expect(rewriteWorkspacePaths("node /workspace/app.js")).toBe("node /workspace/home/app.js");
+    expect(rewriteWorkspacePaths("D=/workspace/x; echo $D")).toBe("D=/workspace/home/x; echo $D");
+    expect(rewriteWorkspacePaths("ls /workspace/home")).toBe("ls /workspace/home"); // no double-map
+    expect(rewriteWorkspacePaths("echo /workspaces")).toBe("echo /workspaces"); // word boundary respected
+  });
+
+  it("does NOT rewrite /workspace mid-token (URLs, relative paths)", () => {
+    // A `/workspace` inside a URL must be left alone — it's not a filesystem path.
+    expect(rewriteWorkspacePaths("curl https://api.example.com/workspace/items")).toBe(
+      "curl https://api.example.com/workspace/items",
+    );
+    expect(rewriteWorkspacePaths("cat ./workspace/x")).toBe("cat ./workspace/x"); // relative, untouched
+  });
 });
 
 describe.skipIf(!hasBoxCreds)("upstash() backend (live Upstash Box)", () => {
-  it("creates a session, runs a command, round-trips a file, and disposes it", async () => {
-    // keepAlive: false so dispose() deletes the box and cleans up after the test.
-    const backend = upstash({ runtime: "node", resources: { vcpus: 2 }, keepAlive: false });
+  it("creates a session, runs a command, round-trips a file", async () => {
+    const backend = upstash({ runtime: "node", size: "small" });
     const handle = await backend.create(createInput);
     const session = handle.session;
     try {
       const result = await session.run({ command: "echo hello-box" });
       expect(result.exitCode).toBe(0);
       expect(result.stdout).toContain("hello-box");
 
+      // Bare commands run in Box's working dir, /workspace/home (not the off-limits /workspace).
+      const pwd = await session.run({ command: "pwd" });
+      expect(pwd.stdout.trim()).toBe("/workspace/home");
+
+      // A relative write lands under /workspace/home, and Eve's `find /workspace …` (rewritten to
+      // /workspace/home) finds it — the end-to-end path bridge.
       await session.writeTextFile({ path: "note.txt", content: "agentkit" });
       expect(await session.readTextFile({ path: "note.txt" })).toContain("agentkit");
+      const found = await session.run({ command: "find /workspace -name note.txt" });
+      expect(found.stdout).toContain("/workspace/home/note.txt");
     } finally {
-      await handle.dispose();
+      // dispose() is a no-op (boxes persist for reuse), so delete explicitly to clean up the test.
+      await Box.delete({ boxIds: handle.session.id }).catch(() => {});
     }
   }, 120_000);
 
-  // With no networkPolicy configured, egress is denied by default — model-generated code in the box
-  // can't reach the network. Opening it explicitly (allow-all) lets the same call through.
-  it("denies network egress by default, allows it when opened", async () => {
-    const fetchCmd = `node -e "fetch('https://example.com').then(r=>process.exit(r.ok?0:9)).catch(()=>process.exit(7))"`;
-
-    const denied = upstash({ runtime: "node", keepAlive: false }); // no networkPolicy → deny-all
-    const deniedHandle = await denied.create(createInput);
+  // Eve re-opens a session several times per turn and hands back the box id we captured; `create` must
+  // REATTACH to it, not spin a fresh box each time (the "three boxes per turn" bug).
+  it("reuses the same box across opens via existingMetadata", async () => {
+    const backend = upstash({ runtime: "node" });
+    const first = await backend.create(createInput);
+    const boxId = first.session.id;
+    const state = await first.captureState();
+    await first.dispose(); // no-op — the box persists for reuse
     try {
-      const r = await deniedHandle.session.run({ command: fetchCmd });
-      expect(r.exitCode).not.toBe(0); // egress blocked → fetch rejects
+      const second = await backend.create({
+        ...createInput,
+        existingMetadata: state.metadata,
+      } as never);
+      expect(second.session.id).toBe(boxId); // reattached to the SAME box, not a new one
+      expect((await second.session.run({ command: "echo reused" })).stdout).toContain("reused");
     } finally {
-      await deniedHandle.dispose();
+      await Box.delete({ boxIds: boxId }).catch(() => {});
     }
+  }, 120_000);
 
-    const open = upstash({ runtime: "node", keepAlive: false, networkPolicy: "allow-all" });
-    const openHandle = await open.create(createInput);
+  // Egress is denied by default — model-generated code in the box can't reach the network. Opening it
+  // per-session via `use({ networkPolicy })` (Eve's flow) lets the same call through on the same box.
+  it("denies network egress by default, allows it when opened", async () => {
+    const fetchCmd = `node -e "fetch('https://example.com').then(r=>process.exit(r.ok?0:9)).catch(()=>process.exit(7))"`;
+
+    const backend = upstash({ runtime: "node" });
+    const handle = await backend.create(createInput);
     try {
-      const r = await openHandle.session.run({ command: fetchCmd });
-      expect(r.exitCode).toBe(0); // egress allowed → fetch resolves
+      const denied = await handle.session.run({ command: fetchCmd });
+      expect(denied.exitCode).not.toBe(0); // egress blocked by default → fetch rejects
+
+      await handle.useSessionFn({ networkPolicy: "allow-all" }); // open egress for this session
+      const allowed = await handle.session.run({ command: fetchCmd });
+      expect(allowed.exitCode).toBe(0); // egress allowed → fetch resolves
     } finally {
-      await openHandle.dispose();
+      await Box.delete({ boxIds: handle.session.id }).catch(() => {});
     }
   }, 180_000);
 });
+
+// Bug fix: prewarm (build/startup) and create (per request) run in different processes, so the
+// template snapshot is recorded in a durable Redis registry — a second backend INSTANCE must reuse it
+// rather than building a fresh, empty box (the "two boxes, first unused" + "missing seed files" bug).
+describe.skipIf(!hasBoxCreds || !hasRedisCreds)(
+  "upstash() template registry (live Box + Redis)",
+  () => {
+    it("create reuses the snapshot prewarm stored in Redis, across instances", async () => {
+      const redis = testRedis();
+      const templatePrefix = uniquePrefix("sandboxtpl"); // unique so reruns don't collide
+      const templateKey = "tmpl-1";
+      const cfg = { runtime: "node" as const, redis, templatePrefix };
+      const prewarmInput = {
+        templateKey,
+        seedFiles: [{ path: "seeded.txt", content: "from-template" }],
+        runtimeContext: { appRoot: process.cwd() },
+      };
+      const regKey = `${templatePrefix}:upstash:${templateKey}`;
+
+      // One instance "prewarms" the template (bakes the seed file into a snapshot).
+      const built = await upstash(cfg).prewarm(prewarmInput as never);
+      expect(built.reused).toBe(false);
+      const snapshotId = await redis.get<string>(regKey);
+      expect(snapshotId).toBeTruthy();
+
+      const runner = upstash(cfg); // a SEPARATE instance — mimics the per-request process
+      try {
+        // It must find the snapshot via Redis (not rebuild, not start empty).
+        expect((await runner.prewarm(prewarmInput as never)).reused).toBe(true);
+
+        const handle = await runner.create({
+          templateKey,
+          sessionKey: "s1",
+          runtimeContext: { appRoot: process.cwd() },
+        } as never);
+        try {
+          expect(await handle.session.readTextFile({ path: "seeded.txt" })).toContain(
+            "from-template",
+          );
+        } finally {
+          await Box.delete({ boxIds: handle.session.id }).catch(() => {});
+        }
+      } finally {
+        if (snapshotId) await Box.deleteSnapshots({ snapshotIds: snapshotId }).catch(() => {});
+        await redis.del(regKey).catch(() => {});
+      }
+    }, 240_000);
+  },
+);