Close sandbox API parity gaps: network policy, image builds, snapshot get/delete, list pagination

[shrisukhani]

Summary

The Node SDK lagged the API (and the Python SDK) on several sandbox surfaces. This closes the gaps found in a full API/SDK parity audit.

Changes

• Sandbox create (CreateSandboxParams): new allowInternetAccess, allowOut, denyOut fields, serialized on both image and snapshot launches (the API and Python SDK already supported these).
• New sandboxes.updateNetwork(id, patch) (PUT /sandbox/:id/network) plus SandboxHandle.updateNetwork() / clearNetwork(); Sandbox now carries network: SandboxNetworkPolicy and timeoutMinutes.
• Image build API parity with Python: createImageBuild, getImageBuild, listImageBuilds, completeImageBuild, cancelImageBuild + SandboxImageBuild* types (status enum matches the server's FirecrackerImageBuildStatus).
• Snapshot getSnapshot(key) / deleteSnapshot(key) (GET/DELETE /snapshots/:key).
• List parity: listImages now accepts source/search/page/limit; listSnapshots adds search/page; volumes.list adds search/page/limit; image/snapshot/volume list responses now include totalCount/page/perPage (replacing the TODO comments) — all matching the server's query schemas.
• Contract tests updated/added for network-policy serialization, updateNetwork/clearNetwork, and the new list call shapes.

Validation

• yarn lint
• yarn build
• yarn vitest run tests/sandbox/e2e/{sandbox-contract,list-contract,volumes-contract,process-api,runtime-transport}.test.ts tests/integration — 31 passed

Link to Devin session: https://app.devin.ai/sessions/96909fa41fe54593b992ff11bc7b6074
Requested by: @shrisukhani

---

Note

Medium Risk
Adds new API surface and makes Sandbox.network required on typed responses; callers must supply network in mocks/tests, but changes are additive SDK wrappers over existing endpoints.

Overview
Brings the Node SDK in line with the control API and Python SDK on sandbox management surfaces.

Network policy: CreateSandboxParams now serializes allowInternetAccess, allowOut, and denyOut on image and snapshot launches. Sandbox includes network and optional timeoutMinutes. SandboxesService.updateNetwork (PUT /sandbox/:id/network) plus SandboxHandle.updateNetwork / clearNetwork update cached handle state.

Image builds & snapshots: Adds createImageBuild, getImageBuild, listImageBuilds, completeImageBuild, and cancelImageBuild with matching types. Adds getSnapshot and deleteSnapshot for individual snapshot keys.

Listing: listImages, listSnapshots, and volumes.list accept search/page/limit (and source for images); image, snapshot, and volume list responses now expose totalCount, page, and perPage. Contract tests cover network serialization, network updates, and list query forwarding.

^{Reviewed by Cursor Bugbot for commit d57a912. Bugbot is set up for automated code reviews on this repo. Configure here.}

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring