Nico Albanese c88bd03028
Add sandbox timeout tracking and state persistence plan (#70)
* Add proactive sandbox timeout management

Sandboxes now track their timeout and proactively call stop() before
the SDK timeout, ensuring beforeStop hooks have time to run. This
prevents cloud sandboxes from silently disappearing without cleanup.

- Add expiresAt and timeout properties to Sandbox interface
- Add onTimeout hook to differentiate timeout-triggered stops
- VercelSandbox schedules proactive stop 30s before SDK timeout
- Make stop() idempotent with proper timer cleanup
- Add remainingTimeout option for sandbox reconnection

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Add timeout extension hook and method to interfaces

* Refactor timeout properties to private with getters

* Add sandbox state persistence planning document

* Fix sandbox timeout management edge cases

- Add error logging for hook failures (onTimeout, beforeStop)
- Add runtime check for sdk.extendTimeout existence
- Fix _timeout semantic: now represents initial value only
- Remove sdk.timeout fallback in connect() due to uncertain semantics
- Update documentation to clarify timeout vs expiresAt usage

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Fix startTime capture to occur after setup operations

The timeout tracking startTime was being captured before SDK creation
and git operations, causing users to get less actual usage time than
specified. Moved startTime capture to after all setup completes so
the full timeout duration is available for actual sandbox usage.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Enable timeout tracking by default for reconnected sandboxes

Reconnecting via connectVercelSandbox({ sandboxId }) previously disabled
timeout tracking when remainingTimeout wasn't provided, which prevented
beforeStop and onTimeout hooks from firing on timeout. This broke state
persistence features that depend on these hooks.

Now uses DEFAULT_RECONNECT_TIMEOUT_MS (5 minutes) as the default timeout
for reconnected sandboxes, ensuring hooks always fire properly.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Update packages/sandbox/vercel.ts

Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
2026-01-12 16:59:31 +00:00
..