fix: mirror CLI VM sandbox guards in SDK

[DamianB-BitFlipper]

Summary

• mirror the CLI's VM sandbox guard behavior in the prime-sandboxes SDK for port exposure and SSH-related methods
• add public is_vm helpers to the sync and async sandbox clients so SDK consumers can branch on VM-backed sandboxes explicitly
• add focused unit coverage for the new VM guard paths and cache-backed is_vm behavior

Testing

• cd packages/prime-sandboxes && python -m pytest tests/test_vm_guards.py -x --no-header
• cd packages/prime-sandboxes && python -m pytest tests/test_command_transport_selection.py tests/test_models.py tests/test_client_retry.py tests/test_gateway_error_mapping.py tests/test_vm_guards.py --no-header
• cd packages/prime-sandboxes && python -m ruff check src/prime_sandboxes/sandbox.py tests/test_vm_guards.py

---

Note

Medium Risk
Changes runtime behavior for VM-backed sandboxes by turning previously-attempted operations into immediate APIErrors, which could break callers relying on prior (failing) gateway behavior. Scope is limited to expose/SSH paths and is covered by new unit tests.

Overview
Mirrors CLI behavior by failing fast on VM-backed sandboxes: SandboxClient/AsyncSandboxClient now guard port exposure and SSH operations (expose, unexpose, list_exposed_ports, create_ssh_session, close_ssh_session) and raise a clear APIError instead of issuing HTTP requests.

Adds public is_vm() helpers (sync + async) that delegate to the auth cache (with cold-cache fallback to GET /sandbox/<id>), and introduces test_vm_guards.py to assert guards prevent HTTP calls on VMs while container-backed sandboxes still proceed normally.

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

[DamianB-BitFlipper]

@cursoragent review

[DamianB-BitFlipper]

@codex review

[cursor]

Findings (ordered by severity)

No issues found.

I reviewed the VM-guard and is_vm changes in:

• packages/prime-sandboxes/src/prime_sandboxes/sandbox.py (notably around is_vm/guard methods at ~L544-562 and ~L1421-1438, and guarded call sites at ~L1251-1296 and ~L2156-2201)
• packages/prime-sandboxes/tests/test_vm_guards.py

The behavior aligns with CLI guard semantics (packages/prime/src/prime_cli/commands/sandbox.py around _guard_vm_unsupported and its call sites).

Open questions / assumptions

• Assumed backend GET /sandbox/<id> continues returning a shape compatible with Sandbox.model_validate(...) for is_vm fallback paths.
• Minor test gap (non-blocking): async cold-cache is_vm fallback/caching path is less directly covered than sync cold-cache behavior.

Change summary (secondary)

• No code changes were needed from this review pass.
• Validation run results:
  • python3 -m pytest tests/test_vm_guards.py -x --no-header ✅ (21 passed)
  • python3 -m pytest tests/test_command_transport_selection.py tests/test_models.py tests/test_client_retry.py tests/test_gateway_error_mapping.py tests/test_vm_guards.py --no-header ✅ (56 passed)
  • python3 -m ruff check src/prime_sandboxes/sandbox.py tests/test_vm_guards.py ✅

Optional environment optimization: since I installed prime-sandboxes dev deps to run checks, you could run an env setup agent with:
“Preinstall packages/prime-sandboxes test/lint deps (pip install -e .[dev]) in the cloud image so future agents can run pytest/ruff without bootstrap.”

  

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 43bd41a5ec

ℹ️ About Codex in GitHub

Codex has been enabled to automatically 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 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

The base branch was changed.