vercel-sandbox

Investigate Vercel Sandbox using current official docs, installed SDK contracts, and only then any consumer-specific integration code. ## Step 1: Classify the request Pick the narrowest reference set before answering: | Request type | Read first | | ----------------------------------------------------------------------------- | ------------------------------------------- | | SDK/API behavior, lifecycle semantics, snapshots, stable vs beta persistence | `references/api-surface.md` | | Product-level usage patterns and architectural choices | `references/common-use-cases.md` | | Broken behavior, confusing docs, missing files, or suspected persistence bugs | `references/troubleshooting-workarounds.md` | If the task spans categories, load only the relevant files above. ## Step 2: Establish which sandbox model applies 1. Inspect the installed `@vercel/sandbox` version and local types before trusting any doc page or changelog. 2. If local types only expose `sandboxId`, `Sandbox.get({ sandboxId })`, `extendTimeout`, and snapshot-backed `source`, treat the runtime as stable 1.x ephemeral sandboxes. 3. If local code and types expose named sandboxes, `name`, `persistent`, session updates, or automatic resume after stop, treat the runtime as the persistent beta model. 4. Qualify time-sensitive claims with a date or retrieval note. ## Step 3: Apply core guardrails 1. Distinguish three separate clocks before diagnosing workspace loss: - Vercel function/runtime timeout - Application/request timeout in the embedding system - Sandbox timeout 2. On stable 1.x, `Sandbox.get({ sandboxId })` only helps while the sandbox is still alive. 3. On stable 1.x, once the sandbox stops, its filesystem is gone. Do not describe that as resumable persistence. 4. `sandbox.snapshot()` is not workspace durability. It creates a new snapshot artifact and stops the source sandbox. 5. Snapshots and persistent beta solve different problems: - snapshots create new starting points - persistent beta preserves named workspace state across sessions 6. In embedded systems, inspect the consumer's persistence wiring before concluding that Vercel destroyed the workspace immediately. 7. Do not infer persistent-beta behavior from a changelog alone. Confirm the installed SDK and local call sites. ## Step 4: Investigate the Vercel surface first 1. Check the installed SDK surface first: - installed `@vercel/sandbox` types - official stable docs for concepts, snapshots, SDK reference, and limits - persistent-beta changelog only if named persistence is relevant 2. Determine whether the question is about: - active sandbox reuse - stopped sandbox recovery - snapshot-based warm starts - persistent named workspaces 3. Establish which timeout fired first and whether the sandbox should still have been active. ## Step 5: Inspect consumer code only when the task is app-specific For repo-local debugging in Junior, inspect: 1. timeout budget alignment: - `packages/junior/src/chat/config.ts` - `packages/junior/src/chat/app/production.ts` 2. sandbox identity persistence and reuse: - `packages/junior/src/chat/runtime/thread-state.ts` - `packages/junior/src/chat/runtime/turn-preparation.ts` - `packages/junior/src/chat/sandbox/session.ts` 3. whether timeout paths actually resume: - `packages/junior/src/chat/agent/index.ts` - `packages/junior/src/chat/agent/resume.ts` - `packages/junior/src/chat/runtime/agent-continue-runner.ts` 4. where sandbox metadata is persisted: - `packages/junior/src/chat/runtime/reply-executor.ts` 5. whether consumer-specific snapshots are being confused with Vercel product persistence: - `packages/junior/src/chat/sandbox/README.md` ## Step 6: Recommend the smallest correct fix Choose the narrowest fix that matches the diagnosed failure mode: 1. Sandbox still alive but next turn started fresh: - Persist sandbox identity earlier. - Resume from the active sandbox instead of recreating it. 2. Sandbox actually stopped: - Increase sandbox timeout or extend it while work is active. - Externalize intermediate outputs if they must survive stop. 3. Confusion caused by docs drift: - Align implementation advice to the installed SDK, not the newest beta docs. 4. Need true durability across stop/timeout boundaries: - Use external storage or migrate intentionally to the persistent beta model after confirming API availability. ## Step 7: Return a concrete diagnosis Default report structure: 1. Active sandbox model: `stable-ephemeral` or `persistent-beta` 2. What likely timed out first 3. Whether the sandbox probably still existed after the failed turn 4. Whether workspace loss came from Vercel stop/destruction or consumer state handling 5. Smallest next fix, with the exact file(s) or SDK change required