feat(vercel-sandbox,sandbox): introduce snapshot tree

[marc-vercel]

This is based on the closed PR #165, which was rebasing to named-sandbox. We are now rebasing to main.

---

Required #163 to be merged first, so that we can rebase and reuse the same methods.

Introduce a new sandbox snapshots tree command (CLI) and Snapshot.tree method (SDK), so that customers and agents can visualize and walk the ancestry of snapshots, backed by the new GET /v2/sandboxes/snapshots/tree API.

CLI

A new subcommand renders the lineage of a sandbox's current snapshot, with ancestors (older) and descendants (newer) on a single tree. Pagination follows the same shape as #163:

• --limit (1–10, default 10): per-direction page size. Validated client-side; server enforces a max of 10.
• --cursor + --direction asc|desc: continue walking from a previous "More …" hint. --direction defaults to desc (ancestors).

> sandbox snapshots tree my-sandbox --limit 3
│
● snap_8f3a2b1c   expires: 5d
│
● snap_7d2c9a4b   expires: 3d
│   ├── sbx_sibling_1
│   ╰── sbx_sibling_2
│
● snap_5a0d7e2c   expires: 12h  ◂ current
│
● snap_4c9b6d1e   expires: 8h
│
● snap_3b8a5c0f   expires: 2h
More ancestors:   sandbox snapshots tree my-sandbox --direction desc --limit 3 --cursor snap_3b8a5c0f
More descendants: sandbox snapshots tree my-sandbox --direction asc --limit 3 --cursor snap_8f3a2b1c

Following a hint renders a single-direction continuation (no "current" marker, no other side).

SDK

A new Snapshot.tree method exposes the tree endpoint:

const ancestors = await Snapshot.tree({
  snapshotId: "snap_5a0d7e2c",
  sortOrder: "desc", // "desc" = ancestors, "asc" = descendants
  limit: 10,
});

if (ancestors.pagination.next) {
  const more = await Snapshot.tree({
    snapshotId: ancestors.pagination.next,
    sortOrder: "desc",
    limit: 10,
  });
}

Parameters:

• snapshotId (required): anchor for the walk.
• sortOrder: "desc" walks ancestors, "asc" walks descendants. Server default is "desc".
• limit: page size. Max is 10 (server-enforced).

Each response includes per-node siblings and count (e.g. "3", or "10+" when truncated) so callers can render branching, plus pagination.next (a snapshot id) to continue walking in the same direction.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
sandbox	Ready	Preview, Comment, Open in v0	May 15, 2026 1:49pm
sandbox-cli	Ready	Preview, Comment, Open in v0	May 15, 2026 1:49pm
sandbox-sdk	Ready	Preview, Comment, Open in v0	May 15, 2026 1:49pm
sandbox-sdk-ai-example	Ready	Preview, Comment, Open in v0	May 15, 2026 1:49pm
workflow-code-runner	Ready	Preview, Comment, Open in v0	May 15, 2026 1:49pm