Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
feat(cua-sandbox): add Fleet pool API (#2742)
r33drichards5812670617ba
diff --git a/libs/python/cua-sandbox/README.md b/libs/python/cua-sandbox/README.mdindex 0a54a313bb..16b214dfcd 100644--- a/libs/python/cua-sandbox/README.md+++ b/libs/python/cua-sandbox/README.md@@ -93,6 +93,33 @@ Fleet is the OAuth cloud backend. Configure OAuth credentials once; Fleet uses `Fleet does not support snapshots or custom disks, and currently supports only `us-east-1`. `await sb.tunnel.forward(3000)` returns the authenticated Fleet service URL for an exposed port; it does not open a local SSH tunnel.+## Fleet pools++Use a pool to keep reusable registry-image sandboxes warm. Reconciliation is idempotent: it creates a missing pool or updates the existing pool with the same name. Each claim is released when the context exits, including when the block raises.++```python+from cua_sandbox import Image, Pool++pool = await Pool.reconcile({+ "name": "foo",+ "image": Image.from_registry("registry.example/workspace:latest"),+})++async with pool.claim() as sb:+ result = await sb.shell.run("echo hello")+```++For scripts that use the synchronous facade:++```python+from cua_sandbox import Image+from cua_sandbox.sync import Pool++pool = Pool.reconcile({"name": "foo", "image": Image.from_registry("example:latest")})+with pool.claim() as sb:+ result = sb.shell.run("echo hello")+```+```pythonimport osdiff --git a/libs/python/cua-sandbox/cua_sandbox/__init__.py b/libs/python/cua-sandbox/cua_sandbox/__init__.pyindex d6196448e8..eb92197982 100644--- a/libs/python/cua-sandbox/cua_sandbox/__init__.py+++ b/libs/python/cua-sandbox/cua_sandbox/__init__.py@@ -22,6 +22,7 @@ from cua_sandbox._auth import login, whoamifrom cua_sandbox._config import configurefrom cua_sandbox.image import Imagefrom cua_sandbox.localhost import Localhost, localhost+from cua_sandbox.pool import Poolfrom cua_sandbox.runtime.compat import (RuntimeSupport,check_local_support,@@ -35,6 +36,7 @@ __all__ = ["login","whoami","Image",+ "Pool","Sandbox","SandboxInfo","sandbox",diff --git a/libs/python/cua-sandbox/cua_sandbox/pool.py b/libs/python/cua-sandbox/cua_sandbox/pool.pynew file mode 100644index 0000000000..9b4584d955--- /dev/null+++ b/libs/python/cua-sandbox/cua_sandbox/pool.py@@ -0,0 +1,137 @@+"""Fleet pool API for reusable cloud sandboxes."""++from __future__ import annotations++import logging+from collections.abc import AsyncIterator, Mapping+from contextlib import asynccontextmanager+from typing import Any, cast++from cua_sandbox.image import Image+from cua_sandbox.sandbox import Sandbox+from cua_sandbox.transport.fleet import FleetTransport+from cua_sandbox.transport.fleet_cloud import FleetCloudTransport, _FleetClient+from cyclops_sdk import CreateClaimRequest++logger = logging.getLogger(__name__)+++class Pool:+ """A reconciled Fleet pool that can lease cloud sandboxes.++ ``reconcile`` creates a pool when it is absent and updates its desired+ configuration when it already exists. The supplied ``image`` must be an+ :meth:`Image.from_registry` image; Fleet does not support locally-built+ images, layers, snapshots, or custom disks.++ Pool instances retain only Fleet resource metadata. Each call to+ :meth:`claim` creates and closes its own Fleet client, so a Pool may be+ reused for sequential claims without the caller managing client lifetime.+ """++ def __init__(self, resource: Any) -> None:+ self._resource = resource++ @property+ def name(self) -> str:+ """The pool name."""+ return cast(str, self._resource.metadata.name)++ @property+ def resource(self) -> Any:+ """The underlying Fleet SDK pool resource."""+ return self._resource++ @classmethod+ async def reconcile(cls, config: Mapping[str, Any]) -> "Pool":+ """Create or update a Fleet pool from its desired configuration.++ Repeated calls with the same configuration are idempotent: an existing+ pool is updated in place rather than creating another pool. ``config``+ requires a non-empty ``name`` and an ``image`` created with+ :meth:`Image.from_registry`.++ The Fleet client used to reconcile is closed before this method returns.+ """+ name, image = cls._validate_config(config)+ desired = FleetCloudTransport(image=image, name=name)._pool_request()+ client = _FleetClient()+ try:+ try:+ resource = await client.get_pool(name)+ except LookupError:+ resource = await client.create_pool(desired)+ else:+ resource.spec = desired.spec+ resource = await client.update_pool(resource)+ return cls(resource)+ finally:+ await client.close()++ @asynccontextmanager+ async def claim(self) -> AsyncIterator[Sandbox]:+ """Lease a sandbox and release its Fleet claim when the block exits.++ A claim is released after both normal and exceptional block exits. If+ release fails while the block is already raising, the original block+ exception is preserved and the release failure is logged. Otherwise,+ the release failure is raised to the caller.+ """+ client = _FleetClient()+ claim: Any = None+ sandbox: Sandbox | None = None+ primary_error: BaseException | None = None+ cleanup_error: Exception | None = None++ try:+ claim = await client.create_claim(CreateClaimRequest(pool=self._resource, spec=None))+ bound = await client.wait_claim(claim)+ sandbox = Sandbox(+ FleetTransport(sdk=client, bound=bound, service_name="server"), name=bound.name+ )+ await sandbox._connect()+ yield sandbox+ except BaseException as error:+ primary_error = error+ raise+ finally:+ if sandbox is not None:+ try:+ await sandbox.disconnect()+ except Exception:+ logger.exception("Failed to disconnect claimed sandbox %r", sandbox.name)++ if claim is not None:+ try:+ await client.delete_claim(claim)+ except Exception as error:+ if primary_error is not None:+ logger.exception("Failed to release Fleet claim after an earlier error")+ else:+ cleanup_error = error++ try:+ await client.close()+ except Exception:+ if primary_error is not None or cleanup_error is not None:+ logger.exception("Failed to close Fleet client")+ else:+ raise++ if cleanup_error is not None:+ raise cleanup_error++ @staticmethod+ def _validate_config(config: Mapping[str, Any]) -> tuple[str, Image]:+ if not isinstance(config, Mapping):+ raise TypeError("Pool configuration must be a mapping")++ name = config.get("name")+ if not isinstance(name, str) or not name:+ raise ValueError("Pool configuration requires a non-empty string 'name'")++ image = config.get("image")+ if not isinstance(image, Image):+ raise TypeError("Pool configuration 'image' must be an Image.from_registry(...) value")+ FleetCloudTransport._validate_image(image)+ return name, imagediff --git a/libs/python/cua-sandbox/cua_sandbox/sync/__init__.py b/libs/python/cua-sandbox/cua_sandbox/sync/__init__.pyindex 8d38d77b68..9a473f8ad8 100644--- a/libs/python/cua-sandbox/cua_sandbox/sync/__init__.py+++ b/libs/python/cua-sandbox/cua_sandbox/sync/__init__.py@@ -18,10 +18,11 @@ from __future__ import annotationsimport asynciofrom contextlib import contextmanager-from typing import Any, Iterator, Optional+from typing import Any, Iterator, Mapping, Optionalfrom cua_sandbox.image import Imagefrom cua_sandbox.localhost import Localhost as _AsyncLocalhost+from cua_sandbox.pool import Pool as _AsyncPoolfrom cua_sandbox.sandbox import Sandbox as _AsyncSandbox@@ -72,6 +73,40 @@ class _SyncProxy:return f"Sync({self._async_obj!r})"+class Pool:+ """Blocking facade for :class:`cua_sandbox.Pool`.++ ``Pool.reconcile`` and ``pool.claim`` use the same Fleet lifecycle as the+ async API, but yield synchronous sandbox interface methods for scripts and+ notebooks.+ """++ def __init__(self, async_pool: _AsyncPool) -> None:+ self._async_pool = async_pool++ @property+ def name(self) -> str:+ return self._async_pool.name++ @classmethod+ def reconcile(cls, config: Mapping[str, Any]) -> "Pool":+ """Synchronously create or update a Fleet pool."""+ return cls(_run(_AsyncPool.reconcile(config)))++ @contextmanager+ def claim(self) -> Iterator[_SyncProxy]:+ """Synchronously lease a sandbox and release the claim on exit."""+ context = self._async_pool.claim()+ sandbox = _run(context.__aenter__())+ try:+ yield _SyncProxy(sandbox)+ except BaseException as error:+ _run(context.__aexit__(type(error), error, error.__traceback__))+ raise+ else:+ _run(context.__aexit__(None, None, None))++@contextmanagerdef sandbox(*,diff --git a/libs/python/cua-sandbox/cua_sandbox/transport/fleet_cloud.py b/libs/python/cua-sandbox/cua_sandbox/transport/fleet_cloud.pyindex f3c92001df..663bb526c7 100644--- a/libs/python/cua-sandbox/cua_sandbox/transport/fleet_cloud.py+++ b/libs/python/cua-sandbox/cua_sandbox/transport/fleet_cloud.py@@ -95,6 +95,9 @@ class _FleetClient:async def delete_pool(self, pool: Any) -> None:await self._client.delete_pool(pool)+ async def update_pool(self, pool: Any) -> Any:+ return await self._client.update_pool(pool)+async def service_request(self, sandbox: Any, service: str, path: str, request: HttpRequest) -> Any:diff --git a/libs/python/cua-sandbox/tests/test_pool.py b/libs/python/cua-sandbox/tests/test_pool.pynew file mode 100644index 0000000000..326fa6f9ad--- /dev/null+++ b/libs/python/cua-sandbox/tests/test_pool.py@@ -0,0 +1,194 @@+from __future__ import annotations++from types import SimpleNamespace++import pytest+from cua_sandbox import Image, Pool+from cua_sandbox.sync import Pool as SyncPool+from cyclops_sdk import Sandbox as FleetSandbox+++def fleet_pool(name: str = "foo") -> SimpleNamespace:+ return SimpleNamespace(+ metadata=SimpleNamespace(name=name, namespace=name),+ spec=SimpleNamespace(services=[]),+ )+++class FakeFleetClient:+ def __init__(+ self,+ *,+ existing: object | None = None,+ create_error: Exception | None = None,+ release_error: Exception | None = None,+ ):+ self.existing = existing+ self.create_error = create_error+ self.release_error = release_error+ self.created: list[object] = []+ self.updated: list[object] = []+ self.claims: list[object] = []+ self.released: list[object] = []+ self.closed = False++ async def get_pool(self, name: str) -> object:+ if self.existing is None:+ raise LookupError(name)+ return self.existing++ async def create_pool(self, request: object) -> object:+ self.created.append(request)+ if self.create_error:+ raise self.create_error+ return fleet_pool(request.namespace)++ async def update_pool(self, pool: object) -> object:+ self.updated.append(pool)+ return pool++ async def create_claim(self, request: object) -> object:+ self.claims.append(request)+ return "claim-1"++ async def wait_claim(self, claim: object) -> FleetSandbox:+ assert claim == "claim-1"+ return FleetSandbox(namespace="foo", claim="claim-1", name="sandbox-1", services=["server"])++ async def delete_claim(self, claim: object) -> None:+ self.released.append(claim)+ if self.release_error:+ raise self.release_error++ async def close(self) -> None:+ self.closed = True+++async def test_reconcile_creates_pool_from_registry_image(monkeypatch):+ client = FakeFleetClient()+ monkeypatch.setattr("cua_sandbox.pool._FleetClient", lambda: client)++ pool = await Pool.reconcile(+ {+ "name": "foo",+ "image": Image.from_registry("registry.example/workspace:latest").expose(3000),+ }+ )++ assert pool.name == "foo"+ assert pool.resource.metadata.name == "foo"+ assert client.closed is True+ assert len(client.created) == 1+ request = client.created[0]+ assert request.namespace == "foo"+ assert request.spec.template.container_disk_image == "registry.example/workspace:latest"+ assert [(service.name, service.target_port) for service in request.spec.services] == [+ ("server", 8000),+ ("port-3000", 3000),+ ]+++async def test_reconcile_closes_temporary_client_when_creation_fails(monkeypatch):+ client = FakeFleetClient(create_error=RuntimeError("create failed"))+ monkeypatch.setattr("cua_sandbox.pool._FleetClient", lambda: client)++ with pytest.raises(RuntimeError, match="create failed"):+ await Pool.reconcile({"name": "foo", "image": Image.from_registry("example:latest")})++ assert client.closed is True+++async def test_reconcile_updates_existing_pool_idempotently(monkeypatch):+ existing = fleet_pool()+ client = FakeFleetClient(existing=existing)+ monkeypatch.setattr("cua_sandbox.pool._FleetClient", lambda: client)++ pool = await Pool.reconcile({"name": "foo", "image": Image.from_registry("example:latest")})++ assert pool.resource is existing+ assert client.created == []+ assert client.updated == [existing]+ assert existing.spec.template.container_disk_image == "example:latest"+ assert client.closed is True+++async def test_claim_releases_claim_and_client_after_block_exception(monkeypatch):+ reconcile_client = FakeFleetClient()+ claim_client = FakeFleetClient()+ clients = iter([reconcile_client, claim_client])+ monkeypatch.setattr("cua_sandbox.pool._FleetClient", lambda: next(clients))+ pool = await Pool.reconcile({"name": "foo", "image": Image.from_registry("example:latest")})++ with pytest.raises(RuntimeError, match="body failed"):+ async with pool.claim() as sandbox:+ assert sandbox.name == "sandbox-1"+ raise RuntimeError("body failed")++ assert claim_client.claims[0].pool is pool.resource+ assert claim_client.claims[0].spec is None+ assert claim_client.released == ["claim-1"]+ assert claim_client.closed is True+++async def test_claim_preserves_block_exception_when_release_fails(monkeypatch):+ reconcile_client = FakeFleetClient()+ claim_client = FakeFleetClient(release_error=RuntimeError("release failed"))+ clients = iter([reconcile_client, claim_client])+ monkeypatch.setattr("cua_sandbox.pool._FleetClient", lambda: next(clients))+ pool = await Pool.reconcile({"name": "foo", "image": Image.from_registry("example:latest")})++ with pytest.raises(ValueError, match="body failed"):+ async with pool.claim():+ raise ValueError("body failed")++ assert claim_client.released == ["claim-1"]+ assert claim_client.closed is True+++async def test_claim_raises_release_failure_without_block_exception(monkeypatch):+ reconcile_client = FakeFleetClient()+ claim_client = FakeFleetClient(release_error=RuntimeError("release failed"))+ clients = iter([reconcile_client, claim_client])+ monkeypatch.setattr("cua_sandbox.pool._FleetClient", lambda: next(clients))+ pool = await Pool.reconcile({"name": "foo", "image": Image.from_registry("example:latest")})++ with pytest.raises(RuntimeError, match="release failed"):+ async with pool.claim():+ pass++ assert claim_client.closed is True+++ "config, message",+ [+ ({"image": Image.from_registry("example:latest")}, "name"),+ ({"name": "foo"}, "image"),+ ({"name": "foo", "image": "example:latest"}, "Image.from_registry"),+ ({"name": "foo", "image": Image.linux()}, "Image.from_registry"),+ ],+)+async def test_reconcile_rejects_invalid_config(config, message):+ with pytest.raises((TypeError, ValueError), match=message):+ await Pool.reconcile(config)+++def test_sync_pool_matches_blocking_context_manager(monkeypatch):+ reconcile_client = FakeFleetClient()+ claim_client = FakeFleetClient()+ clients = iter([reconcile_client, claim_client])+ monkeypatch.setattr("cua_sandbox.pool._FleetClient", lambda: next(clients))++ pool = SyncPool.reconcile({"name": "foo", "image": Image.from_registry("example:latest")})+ with pool.claim() as sandbox:+ assert sandbox.name == "sandbox-1"++ assert claim_client.released == ["claim-1"]+ assert claim_client.closed is True