feat(vercel): Vercel Sandbox provider adapter

[khaliqgant]

Adds VercelSandboxRuntime against the shared SandboxRuntime / WorkflowRuntime ports, following the Freestyle adapter's structure (76cc7463).

Review status: review-ready, pending live evidence. Vercel is not yet in the team's 1Password, so the n=1 canary and n=7 benchmark have not run — zero sandboxes created, zero spend. Every behavioral capability ships false, and docs/vercel.md dates the block explicitly so no cell can be misread as measured. The live run will only flip capability cells and add an economics-doc row; it does not change the code under review here.

Provider-specific decisions

• Identity is the sandbox name, not an opaque id. RuntimeHandle.id carries the name, which makes the configured prefix a real ownership boundary rather than a labelling convention — stop/start/destroy throw VercelForeignSandboxError outside it, even for a handle attached owned: true.
• getById goes through list, not Sandbox.get. get resumes the session as a side effect: it boots a VM and starts billing. A crash-recovery scan over a hundred handles must not be able to wake every one of them.
• Label lookup is a real server-side search (Sandbox.list takes namePrefix and tags), unlike Freestyle's degraded []. Rows are still re-checked against the requested tags in process — a server filter that were ever ignored would hand back a foreign sandbox as a warm lease, which is worse than no lease at all.
• Delete verification handles name reuse. Vercel has no soft-delete flag, so absence is the only proof; a same-name row with a different createdAt counts as proof ours is gone rather than as a survivor. Failed verification retains the registration so cleanup stays retryable.
• Commands run as sh -c with cwd/env passed through provider fields, so no caller value is spliced into a command string.
• One deadline per logical operation, shared across its round trips, under an absolute retryDeadlineMs ceiling that spans the SDK's internal async-retry. Errors name which cap fired.
• launchDetached is omitted, not faked — create resolves only once the sandbox is running, so there is no mid-boot handle to hand back.
• acquire() returns an AsyncDisposable for await using scopes (harvested from the opencoredev/sandbox-sdk eval).

Capabilities

All behavioral cells are false pending live evidence, including cleanupVerified — implemented and unit-tested, but not promoted without a dated live-canary comment, matching the discipline Freestyle used. neverIdle is false for a different reason: it is settled false, because every Vercel sandbox carries a termination deadline.

Construction-time reconciliation walks all three registries and throws on any true claim lacking its implementation. reconcileVercelCapabilities is exported and takes a structural surface so its failure paths are unit-tested with broken fakes.

Economics correction

The premise that active-CPU billing makes Vercel dramatically cheapest for I/O-heavy agents needed a correction, documented in docs/vercel.md: Active CPU genuinely excludes I/O wait, but Provisioned Memory is billed on wall clock, not active time. At the default 2 vCPU / 4 GB shape, one wall-clock hour costs $0.341 at 100% CPU, $0.110 at 10%, and $0.085 at 0% — a ~3.1x spread with a $0.0848/h floor set by memory. Cross-provider comparison has to be made against that floor. Active-CPU billing makes the CPU line small for I/O-bound agents; wall-clock memory sets the floor, and stopping the sandbox promptly — not merely leaving it idle — is what removes it.

Testing

46 mocked contract tests (charter minimum was 20). Suite 202 -> 250, 0 failures, 3 pre-existing skips. npm run build and tsc --noEmit clean.

Because the tests were written alongside the implementation, a red-baseline claim would have been fiction. Instead, six invariants were mutation-tested one at a time — client-side tag re-verification, the ownership guard in destroy, the createdAt reuse guard, the sh -c wrapping, registration retention on unverified destroy, and upload verification. Each was caught by the suite, and the file restored byte-identical.

Dependency provenance

@vercel/sandbox@3.0.1, exact optional peer + dev dependency, Apache-2.0. The packument carries no gitHead (monorepo release-bot publish), so the upstream commit d7c3bf55d520c6e5b5381ed87285967b30ecc083 is taken from the package's SLSA v1 provenance attestation rather than fabricated. Integrity hash, shasum, and attestation URL are all in docs/vercel.md. The SDK is imported in exactly one dynamically-imported module and assigned through a structural interface, so vendor drift breaks the build rather than a live sandbox.

🤖 Generated with Claude Code

---

Summary by cubic

Adds a Vercel Sandbox adapter behind the SandboxRuntime/WorkflowRuntime ports and a live-benchmark harness; previously Vercel was unsupported. Recent updates withdraw non‑idempotent async exec APIs, enforce provider limits, improve pagination/verification, and harden cleanup and reporting.

• Identity is the sandbox name; start/stop/destroy refuse names outside the configured prefix. getById uses list to avoid waking/billing stopped sandboxes; tag lookup uses server filters plus in‑process rechecks. Delete verification treats same‑name/different‑createdAt as “ours is gone” and retains registrations when absence can’t be proven. Commands run via sh -c with explicit cwd/env. One deadline is shared across each logical operation; errors name whether the op budget or the SDK retry ceiling fired. launchDetached is omitted; acquire() returns an AsyncDisposable. Async exec is now declared false and startScript/getScriptStatus/getScriptLogs are removed. Enforces the 15‑port ceiling and reserves 17 chars for the generated name suffix; findAllByLabels paginates incrementally and short‑circuits on limit≤0; countByLabels short‑circuits on maxCount≤0; uploadBundle verification runs within the shared bundle deadline. The SDK sits behind one dynamic import with checked structural typing; capability reconciliation throws on any true claim without an implementation. All behavioral capabilities remain false pending live evidence.

• Benchmark harness: sweep runs in the outer finally; destroy failures are classified (only verified‑delete errors count as unverified); cleanup.created includes burst admits; readiness probe fails fast on nonzero/null exit; CLI persists a labeled failure report; sweepError surfaces and marks clean=false. Internal tooling; not exported.

• Install optional peer @vercel/sandbox (>=3.0.1 <4.0.0).

• Provide token, teamId, projectId, namePrefix, and defaultHomeDir; ambient VERCEL_* and on‑disk OAuth are ignored.

• Do not rely on async exec or detached launch; use runScript and acquire() disposal. Orchestrators must read declared capabilities; behavioral flags stay false until live evidence promotes them (no code change required).

^{Written for commit 3356fca. Summary will update on new commits.}

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: ae944cd4-271f-4486-a816-a3a2c393d163

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 883daefd16

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[cubic-dev-ai]

All reported issues were addressed across 11 files

_{You’re at about 90% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.}

<sub>Tip: cubic can generate docs of your entire codebase and keep them up to date. Try it here.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 4 files (changes from recent commits).

_{You’re at about 93% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.}

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[kjgbot]

Review backlog cleared — merge-ready

Threads resolved: 19 / 19 (16 previously unresolved + 3 already resolved).
Threads remaining: 0.
Merge-ready: yes, from my seat. Final call is Khaliq's per lane policy.

Fixes landed in 3356fca

P1

• Withdrew startScript / getScriptStatus / getScriptLogs; port now reports asyncExec: false. Vercel's runCommand has no admission key, and the port capability is all-or-nothing — exposing the trio without durable dedup would let a lost-response retry submit a duplicate command. Trio will return when the SDK offers idempotent submission (or this adapter builds reconciliation on top of it).
• sweep() now runs in the outer finally of runBenchmark; the run-end ledger write is wrapped so its failure cannot preempt the audit. Sweep errors surface on report.cleanup.sweepError; clean is false whenever the sweep did not certify itself.

P2

• findAllByLabels paginates incrementally through a new listPages async generator and returns as soon as limit matches accrue — single-result lookups stop on page one instead of tripping the page cap on projects that happened to match on page one.
• countByLabels / findAllByLabels short-circuit on non-positive maxCount / limit before any lookup.
• Destroy failures in the benchmark are classified: only VercelDestroyVerificationError counts as destroyed-but-unverified; any other error is a submission failure and leaves sample.destroyed = false so cleanup counts stay honest.
• validateNamePrefix reserves the full 17 characters the generated suffix uses (GENERATED_SUFFIX_LENGTH) instead of 10.
• validatePorts enforces the documented 15-port ceiling.
• uploadBundle verification now runs through the shared bundle Deadline via a new runScriptWithDeadline, instead of starting a fresh runScript budget after mkdirs and writes have already consumed most of fileTimeoutMs.
• CLI wraps runBenchmark in try/catch and always persists a report (labelled with the error on rejection), so ledger, JSON, and exit code stay in sync.
• cleanup.created adds burst?.admitted, matching destroyed and verifiedGone.
• measureOne fails fast on a nonzero or null readiness-probe exit rather than publishing a green-looking latency for a broken sandbox.

P3

• @vercel/sandbox peer relaxed to >=3.0.1 <4.0.0 for parity with the other providers and the structural-interface drift-tolerance design.
• VercelSandboxSource doc corrected to "three forms".
• Flaky wall-clock assertion in runtime.test.ts replaced with error.timeoutMs === 40 + outputCalls === 1 — the shared-budget invariant those already prove.

CI

Green per-workflow (single CI workflow, verified via gh run list --branch agent/vercel-adapter-0821, not the rollup):

• 32515725265 (head 3356fca): completed / success.

Coverage grew from 260 to 267 tests: added port-limit, prefix-length, sweep-failure, readiness-probe (nonzero + null), destroy-submit-vs-verification, and burst-admits-in-cleanup.created assertions.