Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

feat(sandbox): connect typed Driver through explicit MCP carrier (#3693)

Francesco Bonaccidc3d35cb40ca
diff --git a/.github/workflows/ci-cua-driver-contract-clients.yml b/.github/workflows/ci-cua-driver-contract-clients.yml
index 0c6782ea65..c139291644 100644
--- a/.github/workflows/ci-cua-driver-contract-clients.yml
+++ b/.github/workflows/ci-cua-driver-contract-clients.yml
@@ -297,6 +297,8 @@ jobs:
python -m pytest \
libs/python/cua-sandbox/tests/test_typed_driver_native.py \
libs/python/cua-sandbox/tests/test_typed_driver.py \
+ libs/python/cua-sandbox/tests/test_driver_mcp.py \
+ libs/python/cua-sandbox/tests/test_driver_mcp_native.py \
libs/python/cua-sandbox/tests/test_pool.py \
libs/python/cua-sandbox/tests/test_fleet_transport.py \
libs/python/cua-sandbox/tests/test_fleet_cloud_transport.py \
diff --git a/libs/python/cua-sandbox/README.md b/libs/python/cua-sandbox/README.md
index ab213e834f..b85358b120 100644
--- a/libs/python/cua-sandbox/README.md
+++ b/libs/python/cua-sandbox/README.md
@@ -24,6 +24,44 @@ The `driver` extra pins `cua-driver==0.25.0`, which provides the compatible remo
channel bridge. It requires that version to be published for your platform.
The sandbox image must also run a compatible Driver service.
+### Optional MCP envelope carrier (unreleased candidate)
+
+The candidate SDK can carry the same typed Driver interface through a named
+MCP service. This requires the guest's explicit typed-envelope extension, not
+just an ordinary MCP tools endpoint:
+
+```python
+from cua_driver import GetScreenSizeInput
+
+
+async def observe_guest(pool):
+ async with pool.claim() as sb:
+ async with sb.driver.connect(service="mcp", transport="mcp") as driver:
+ # This is the generated cua_driver.CuaDriver, not an MCP facade.
+ result = await driver.get_screen_size(GetScreenSizeInput(session=None))
+ return result
+```
+
+`sb.driver.connect()` and `sb.driver.connect(service="driver")` keep the existing
+envelope HTTP path. `CuaDriver.connect(socket_path)` is unchanged. Shell, files,
+terminals, existing Sandbox desktop calls, and claim/pool lifecycle still use
+their existing interfaces; this option affects only `sb.driver`.
+
+MCP selection performs initialization and verifies
+`capabilities.experimental["ai.cua.driver.envelopes"].version == 1` before
+opening a receiver. An old tools-only image fails before a desktop action.
+The connection preserves the receiver's generation, host-selected permissions,
+and cancellation. It does not reconnect, replay actions, or fall back to the
+local desktop. On exit, the SDK attempts bounded receiver and MCP-session
+cleanup. An unconfirmed cleanup warns; it is not proof of rollback or guest
+deletion.
+
+See the [candidate wire and launcher contract](../../cua-driver/docs/mcp-envelope-carrier.md)
+for the opt-in and limits. No existing Fleet image is qualified by this example.
+Test the exact image and matching bindings/native library before advertising
+support. The newer typed-window API on this source branch is not in released
+Driver 0.25.0; it requires its matching release independently of this carrier.
+
## Ephemeral sandbox
Created on enter, destroyed on exit.
@@ -100,7 +138,6 @@ async with Localhost.connect() as host:
await host.screenshot()
```
-
## Cloud sandbox
Fleet is the OAuth cloud backend. Configure OAuth credentials once; Fleet uses `https://run.cua.ai` by default and can be overridden with `configure(fleet_base_url=...)` or `CUA_FLEET_BASE_URL`. The legacy API-key VM API continues to use `https://api.cua.ai`. Cloud images must use a registry reference; `expose()` declares additional Fleet services.
diff --git a/libs/python/cua-sandbox/cua_sandbox/interfaces/_driver_mcp.py b/libs/python/cua-sandbox/cua_sandbox/interfaces/_driver_mcp.py
new file mode 100644
index 0000000000..a74b1205ff
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/interfaces/_driver_mcp.py
@@ -0,0 +1,236 @@
+"""Explicit, non-reconnecting MCP carrier for the canonical Driver envelopes."""
+
+from __future__ import annotations
+
+import json
+import re
+import uuid
+from typing import Any
+
+import httpx
+
+_PROTOCOL = "2025-06-18"
+_CAPABILITY = "ai.cua.driver.envelopes"
+_PREFIX = "cua/driver/v1/"
+_REQUEST_LIMIT = 1024 * 1024
+_RESPONSE_LIMIT = 16 * 1024 * 1024
+_SESSION = re.compile(r"[\x21-\x7e]{1,256}\Z")
+
+
+class McpCarrierError(RuntimeError):
+ """A bounded reason, never a remote body or transport exception."""
+
+
+def _json(text: str) -> Any:
+ def pairs(items):
+ result = {}
+ for key, value in items:
+ if key in result:
+ raise ValueError("duplicate JSON member")
+ result[key] = value
+ return result
+
+ def constant(_):
+ raise ValueError("non-finite JSON value")
+
+ return json.loads(text, object_pairs_hook=pairs, parse_constant=constant)
+
+
+def _response(response: httpx.Response, request_id: str) -> Any:
+ """Decode one bounded JSON or buffered SSE response with exact correlation."""
+ try:
+ if len(response.content) > _RESPONSE_LIMIT:
+ raise ValueError
+ text = response.content.decode("utf-8", errors="strict")
+ media = response.headers.get("content-type", "").split(";", 1)[0].strip().lower()
+ if media == "application/json":
+ messages = [_json(text)]
+ elif media == "text/event-stream":
+ messages = []
+ blocks = text.replace("\r\n", "\n").replace("\r", "\n").split("\n\n")
+ if blocks[-1].strip() or len(blocks) > 128:
+ raise ValueError
+ for block in blocks[:-1]:
+ data = []
+ for line in block.split("\n"):
+ if not line or line.startswith(":"):
+ continue
+ field, _, value = line.partition(":")
+ value = value.removeprefix(" ")
+ if field == "data":
+ data.append(value)
+ elif field == "event" and value not in ("message", ""):
+ raise ValueError
+ elif field not in ("event", "id", "retry"):
+ raise ValueError
+ if data:
+ messages.append(_json("\n".join(data)))
+ else:
+ raise ValueError
+ # This carrier has no unsolicited event stream and never follows SSE
+ # reconnect instructions. More than one RPC response is ambiguous.
+ if len(messages) != 1:
+ raise ValueError
+ message = messages[0]
+ if (
+ not isinstance(message, dict)
+ or message.get("jsonrpc") != "2.0"
+ or type(message.get("id")) is not str
+ or message["id"] != request_id
+ or ("result" in message) == ("error" in message)
+ ):
+ raise ValueError
+ if "error" in message:
+ error = message["error"]
+ if not isinstance(error, dict) or type(error.get("code")) is not int:
+ raise ValueError
+ code = error["code"]
+ if code in (-32404, -32409):
+ raise McpCarrierError("MCP Driver connection is stale or unavailable")
+ if code == -32601:
+ raise McpCarrierError("MCP endpoint does not support typed Driver envelopes")
+ raise McpCarrierError("MCP Driver request failed; completion is unknown")
+ return message["result"]
+ except (ValueError, KeyError, TypeError, UnicodeError, RecursionError):
+ raise McpCarrierError("MCP Driver response is malformed; completion is unknown") from None
+
+
+class McpCarrier:
+ """One stateful MCP session owned by one typed channel, with no retry."""
+
+ def __init__(self, transport: Any, service: str):
+ self.transport = transport
+ self.service = service
+ self.session: str | None = None
+ self.ready = False
+ self.broken = False
+ self.session_closed = False
+
+ async def _http(self, method: str, body=None, *, timeout=None, initializing=False):
+ headers = {"Accept": "application/json, text/event-stream"}
+ if self.session is not None:
+ headers["Mcp-Session-Id"] = self.session
+ headers["MCP-Protocol-Version"] = _PROTOCOL
+ try:
+ if (
+ body is not None
+ and len(json.dumps(body, allow_nan=False).encode()) > _REQUEST_LIMIT
+ ):
+ raise McpCarrierError("MCP Driver request exceeds the size limit")
+ response = await self.transport.request_service(
+ self.service,
+ method=method,
+ path="/mcp",
+ json_body=body,
+ headers=headers,
+ **({"timeout": timeout} if timeout is not None else {}),
+ )
+ except McpCarrierError:
+ raise
+ except Exception as error:
+ self.broken = True
+ if getattr(error, "status", None) in (401, 403):
+ raise McpCarrierError("Driver service authorization denied") from None
+ raise McpCarrierError("MCP Driver transport failed; completion is unknown") from None
+ if response.status_code in (401, 403):
+ self.broken = True
+ raise McpCarrierError("Driver service authorization denied")
+ if not 200 <= response.status_code < 300:
+ self.broken = True
+ if response.status_code in (404, 409):
+ raise McpCarrierError("MCP Driver session is stale or unavailable")
+ raise McpCarrierError("MCP Driver request failed; completion is unknown")
+ sessions = response.headers.get_list("mcp-session-id")
+ if initializing:
+ if len(sessions) != 1 or not _SESSION.fullmatch(sessions[0]):
+ self.broken = True
+ raise McpCarrierError("MCP Driver session negotiation is malformed")
+ # Retain an allocated session before parsing the body, so malformed
+ # negotiation can still perform bounded HTTP-session cleanup.
+ self.session = sessions[0]
+ elif sessions and sessions != [self.session]:
+ self.broken = True
+ raise McpCarrierError("MCP Driver session changed unexpectedly")
+ if len(response.content) > _RESPONSE_LIMIT:
+ self.broken = True
+ raise McpCarrierError("MCP Driver response exceeds the size limit")
+ return response
+
+ async def _rpc(self, method: str, params: Any, *, timeout=None, initializing=False):
+ if self.broken or self.session_closed:
+ raise McpCarrierError("MCP Driver carrier is closed")
+ request_id = uuid.uuid4().hex
+ body = {"jsonrpc": "2.0", "id": request_id, "method": method, "params": params}
+ response = await self._http("POST", body, timeout=timeout, initializing=initializing)
+ try:
+ return _response(response, request_id)
+ except McpCarrierError:
+ self.broken = True
+ raise
+
+ async def initialize(self):
+ if self.session is not None or self.ready:
+ raise McpCarrierError("MCP Driver carrier cannot reconnect")
+ result = await self._rpc(
+ "initialize",
+ {
+ "protocolVersion": _PROTOCOL,
+ "capabilities": {},
+ "clientInfo": {"name": "cua-sandbox-driver", "version": "1"},
+ },
+ initializing=True,
+ )
+ try:
+ extension = result["capabilities"]["experimental"][_CAPABILITY]
+ if (
+ result["protocolVersion"] != _PROTOCOL
+ or type(extension["version"]) is not int
+ or extension["version"] != 1
+ ):
+ raise ValueError
+ except (ValueError, KeyError, TypeError):
+ self.broken = True
+ raise McpCarrierError(
+ "MCP endpoint does not support typed Driver envelopes v1"
+ ) from None
+ response = await self._http(
+ "POST", {"jsonrpc": "2.0", "method": "notifications/initialized"}
+ )
+ if response.status_code not in (202, 204) or response.content:
+ self.broken = True
+ raise McpCarrierError("MCP Driver initialization acknowledgement is incompatible")
+ self.ready = True
+
+ async def request(self, method, suffix, body, connection_id, generation, *, timeout=None):
+ if not self.ready:
+ raise McpCarrierError("MCP Driver carrier is not initialized")
+ if connection_id is None:
+ operation, params = "open", {}
+ else:
+ params = {"connection_id": connection_id, "generation": generation}
+ if method == "DELETE":
+ operation = "close"
+ elif suffix == "/exchange":
+ operation = "exchange"
+ params["envelope"] = body
+ elif suffix == "/cancel":
+ operation = "cancel"
+ params["request_id"] = body["request_id"]
+ else:
+ raise McpCarrierError("Invalid MCP Driver operation")
+ result = await self._rpc(_PREFIX + operation, params, timeout=timeout)
+ if operation in ("close", "cancel") and (
+ not isinstance(result, dict) or set(result) != {"ok"} or result["ok"] is not True
+ ):
+ self.broken = True
+ raise McpCarrierError("MCP Driver cleanup acknowledgement is malformed")
+ return httpx.Response(200, json=result)
+
+ async def close_session(self):
+ if self.session is None or self.session_closed:
+ return
+ # DELETE is teardown, not action replay. It remains available when a
+ # failed exchange has made the carrier unusable for further requests.
+ await self._http("DELETE")
+ self.session_closed = True
+ self.ready = False
diff --git a/libs/python/cua-sandbox/cua_sandbox/interfaces/driver.py b/libs/python/cua-sandbox/cua_sandbox/interfaces/driver.py
index fd723fece5..c788deca90 100644
--- a/libs/python/cua-sandbox/cua_sandbox/interfaces/driver.py
+++ b/libs/python/cua-sandbox/cua_sandbox/interfaces/driver.py
@@ -10,7 +10,7 @@ import re
import time
import uuid
from contextlib import asynccontextmanager
-from typing import TYPE_CHECKING, Any, AsyncIterator
+from typing import TYPE_CHECKING, Any, AsyncIterator, Literal
from cua_sandbox.transport.fleet import FleetTransport
@@ -102,9 +102,18 @@ class Driver:
raise DriverConnectionError("Driver connection is inactive or belongs to another sandbox")
@asynccontextmanager
- async def connect(self, *, service: str = "driver") -> AsyncIterator[CuaDriver]:
- """Yield the canonical ``cua_driver.CuaDriver`` and close its session on exit."""
+ async def connect(
+ self, *, service: str = "driver", transport: Literal["envelope", "mcp"] = "envelope"
+ ) -> AsyncIterator[CuaDriver]:
+ """Yield the canonical Driver; MCP requires an explicitly enabled receiver.
+
+ The default preserves the existing private envelope HTTP carrier.
+ ``service="mcp", transport="mcp"`` uses the existing named MCP service,
+ provided it advertises the typed envelope extension. No fallback occurs.
+ """
self._check_loop()
+ if transport not in ("envelope", "mcp"):
+ raise DriverConnectionError("Driver transport must be 'envelope' or 'mcp'")
self._loop = asyncio.get_running_loop()
async with self._lock:
if self._closed:
@@ -118,7 +127,7 @@ class Driver:
"Fleet sandbox does not expose the requested Driver service"
)
sdk = _sdk()
- channel = _channel(sdk, self._transport, service, self._principal)
+ channel = _channel(sdk, self._transport, service, self._principal, mode=transport)
async def open_channel():
try:
@@ -185,7 +194,11 @@ class Driver:
)
-def _channel(sdk: Any, transport: FleetTransport, service: str, principal: str) -> Any:
+def _channel(
+ sdk: Any, transport: FleetTransport, service: str, principal: str, *, mode="envelope"
+) -> Any:
+ from cua_sandbox.interfaces._driver_mcp import McpCarrier, McpCarrierError
+
class Channel(sdk.ForeignDriverEnvelopeChannel):
def __init__(self):
self.connection_id = None
@@ -196,6 +209,7 @@ def _channel(sdk: Any, transport: FleetTransport, service: str, principal: str)
self.cleanup_confirmed = False
self._close_task = None
self.cancelled: set[str] = set()
+ self.carrier = McpCarrier(transport, service) if mode == "mcp" else None
def fail(self, reason: str):
return sdk.ForeignDriverChannelError.Failed(reason)
@@ -207,14 +221,22 @@ def _channel(sdk: Any, transport: FleetTransport, service: str, principal: str)
path += "/" + self.connection_id + suffix
headers = {"X-Cua-Driver-Generation": self.generation}
try:
- response = await transport.request_service(
- service,
- method=method,
- path=path,
- json_body=body,
- headers=headers,
- **({"timeout": timeout} if timeout is not None else {}),
- )
+ if self.carrier is not None:
+ response = await self.carrier.request(
+ method, suffix, body, self.connection_id, self.generation, timeout=timeout
+ )
+ else:
+ response = await transport.request_service(
+ service,
+ method=method,
+ path=path,
+ json_body=body,
+ headers=headers,
+ **({"timeout": timeout} if timeout is not None else {}),
+ )
+ except McpCarrierError as error:
+ self.closed = True
+ raise self.fail(str(error)) from None
except Exception as error:
if getattr(error, "status", None) in (401, 403):
raise self.fail("Driver service authorization denied") from None
@@ -240,6 +262,13 @@ def _channel(sdk: Any, transport: FleetTransport, service: str, principal: str)
return response
async def open(self):
+ if self.carrier is not None:
+ try:
+ await self.carrier.initialize()
+ except McpCarrierError as error:
+ raise self.fail(str(error)) from None
+ if self.closed:
+ raise self.fail("Driver connection was closed during initialization")
response = await self.request("POST", body={})
try:
data = response.json()
@@ -382,13 +411,21 @@ def _channel(sdk: Any, transport: FleetTransport, service: str, principal: str)
async def close(self):
self.closed = True
# Do not memoize a no-op before an in-flight open reveals its ID.
- if self.connection_id is None:
+ if self.connection_id is None and (
+ self.carrier is None or self.carrier.session is None
+ ):
return
if self._close_task is None:
async def cleanup():
+ receiver_closed = self.connection_id is None
if self.connection_id is not None:
- self.cleanup_confirmed = await _bounded_cleanup(self.request("DELETE"))
+ receiver_closed = await _bounded_cleanup(self.request("DELETE"))
+ if self.carrier is not None:
+ session_closed = await _bounded_cleanup(self.carrier.close_session())
+ self.cleanup_confirmed = receiver_closed and session_closed
+ else:
+ self.cleanup_confirmed = receiver_closed
self._close_task = asyncio.create_task(cleanup())
await asyncio.shield(self._close_task)
diff --git a/libs/python/cua-sandbox/tests/test_driver_mcp.py b/libs/python/cua-sandbox/tests/test_driver_mcp.py
new file mode 100644
index 0000000000..6896c5ea3a
--- /dev/null
+++ b/libs/python/cua-sandbox/tests/test_driver_mcp.py
@@ -0,0 +1,281 @@
+"""MCP session/wire tests; not proof of a guest desktop or native effects."""
+
+import asyncio
+import json
+
+import httpx
+import pytest
+from cua_sandbox.interfaces._driver_mcp import McpCarrierError, _response
+from cua_sandbox.interfaces.driver import DriverConnectionError
+from cua_sandbox.sandbox import Sandbox
+
+from .test_typed_driver import ChannelError, Transport, envelope
+from .test_typed_driver import native as _native_fixture
+
+native = _native_fixture
+
+
+class McpTransport(Transport):
+ def __init__(self, *, sse=False, supported=True):
+ super().__init__()
+ self._bound.services.append("mcp")
+ self.sse = sse
+ self.supported = supported
+ self.sessions = set()
+ self.sequence = 0
+ self.mutate = None
+ self.fail_exchange = False
+ self.exchange_started = asyncio.Event()
+ self.exchange_wait = None
+
+ async def request_service(
+ self, name, *, method, path, json_body=None, headers=None, timeout=None
+ ):
+ self.events.append((name, method, path, json_body, headers))
+ assert name == "mcp" and path == "/mcp"
+ assert headers["Accept"] == "application/json, text/event-stream"
+ rpc = json_body.get("method") if json_body else None
+ response_headers = {}
+ if rpc == "initialize":
+ assert "Mcp-Session-Id" not in headers
+ self.sequence += 1
+ session = f"http-session-{self.sequence}"
+ self.sessions.add(session)
+ response_headers["Mcp-Session-Id"] = session
+ result = {
+ "protocolVersion": "2025-06-18",
+ "capabilities": {
+ "experimental": (
+ {"ai.cua.driver.envelopes": {"version": 1}} if self.supported else {}
+ )
+ },
+ }
+ else:
+ session = headers["Mcp-Session-Id"]
+ assert headers["MCP-Protocol-Version"] == "2025-06-18"
+ if session not in self.sessions:
+ return httpx.Response(404)
+ if method == "DELETE":
+ self.sessions.remove(session)
+ return httpx.Response(200)
+ if rpc == "notifications/initialized":
+ assert "id" not in json_body
+ return httpx.Response(202)
+ if rpc == "cua/driver/v1/open":
+ result = dict(self.open_data, connection_id=session, generation=f"gen-{session}")
+ else:
+ assert json_body["params"]["connection_id"] == session
+ assert json_body["params"]["generation"] == f"gen-{session}"
+ if rpc == "cua/driver/v1/exchange":
+ self.exchange_started.set()
+ if self.exchange_wait is not None:
+ await self.exchange_wait.wait()
+ if self.fail_exchange:
+ raise RuntimeError("sensitive transport diagnostic")
+ request = json_body["params"]["envelope"]
+ result = dict(self.response_data, request_id=request["request_id"])
+ else:
+ assert rpc in ("cua/driver/v1/cancel", "cua/driver/v1/close")
+ result = {"ok": True}
+ response = {"jsonrpc": "2.0", "id": json_body["id"], "result": result}
+ if self.mutate:
+ response = self.mutate(rpc, response)
+ if self.sse:
+ response_headers["Content-Type"] = "text/event-stream"
+ return httpx.Response(
+ 200,
+ content=("event: message\r\ndata: " + json.dumps(response) + "\r\n\r\n"),
+ headers=response_headers,
+ )
+ return httpx.Response(200, json=response, headers=response_headers)
+
+
+async def sandbox(transport):
+ sb = Sandbox(transport, _telemetry_enabled=False)
+ await sb._connect()
+ return sb
+
+
[email protected]("sse", [False, True])
+async def test_explicit_mcp_preserves_canonical_driver_and_computer_server(native, sse):
+ transport = McpTransport(sse=sse)
+ sb = await sandbox(transport)
+ try:
+ async with sb.driver.connect(service="mcp", transport="mcp") as driver:
+ assert isinstance(driver, native.CuaDriver)
+ assert all(interface._t is transport for interface in (sb.shell, sb.files, sb.mouse))
+ assert transport._service_name == "server"
+ channel = driver.channel
+ result = await channel.exchange(envelope())
+ assert json.loads(result.result_json) == {"width": 1280}
+ assert channel.identity().connection_generation == "gen-http-session-1"
+ assert (await channel.negotiate()).supports_cancellation is True
+ assert sb.driver.session_name(driver) == "session-1"
+ assert channel.cleanup_confirmed
+ assert driver.shutdowns == 1
+ assert not transport.sessions
+ assert transport.events[-2][3]["method"] == "cua/driver/v1/close"
+ assert transport.events[-1][1] == "DELETE"
+ assert transport._connected
+ finally:
+ await sb.disconnect()
+
+
+async def test_old_tools_only_endpoint_fails_before_open_and_cleans_http_session(native):
+ transport = McpTransport(supported=False)
+ sb = await sandbox(transport)
+ with pytest.raises(ChannelError, match="does not support typed"):
+ async with sb.driver.connect(service="mcp", transport="mcp"):
+ pytest.fail("must not yield a facade")
+ assert [event[3]["method"] for event in transport.events if event[3]] == ["initialize"]
+ assert not transport.sessions
+ await sb.disconnect()
+
+
+async def test_two_channels_keep_distinct_mcp_sessions_and_close_independently(native):
+ transport = McpTransport()
+ sb = await sandbox(transport)
+ async with sb.driver.connect(service="mcp", transport="mcp") as first:
+ async with sb.driver.connect(service="mcp", transport="mcp") as second:
+ assert first.channel.generation != second.channel.generation
+ assert len(transport.sessions) == 2
+ assert len(transport.sessions) == 1
+ assert (await first.channel.exchange(envelope())).ok
+ assert not transport.sessions
+ await sb.disconnect()
+
+
+async def test_unknown_transport_rejected_before_any_service_request(native):
+ transport = McpTransport()
+ sb = await sandbox(transport)
+ with pytest.raises(DriverConnectionError, match="transport must"):
+ async with sb.driver.connect(service="mcp", transport="guess"):
+ pass
+ assert not transport.events
+ await sb.disconnect()
+
+
+async def test_lost_exchange_never_retries_or_reinitializes(native, caplog):
+ transport = McpTransport()
+ sb = await sandbox(transport)
+ async with sb.driver.connect(service="mcp", transport="mcp") as driver:
+ transport.fail_exchange = True
+ with pytest.raises(ChannelError, match="completion is unknown"):
+ await driver.channel.exchange(envelope())
+ with pytest.raises(ChannelError, match="closed"):
+ await driver.channel.exchange(envelope(request_id="second"))
+ assert driver.channel.closed
+ assert not driver.channel.cleanup_confirmed
+ methods = [event[3]["method"] for event in transport.events if event[3]]
+ assert methods.count("initialize") == 1
+ assert methods.count("cua/driver/v1/exchange") == 1
+ assert not transport.sessions
+ assert "sensitive" not in caplog.text
+ await sb.disconnect()
+
+
[email protected]("mutation", ["wrong-id", "bad-version", "rpc-error", "wrong-inner-id"])
+async def test_malformed_or_failed_response_closes_without_replay(native, mutation):
+ transport = McpTransport()
+ sb = await sandbox(transport)
+
+ def mutate(method, response):
+ if method != "cua/driver/v1/exchange":
+ return response
+ if mutation == "wrong-id":
+ response["id"] = "other"
+ elif mutation == "bad-version":
+ response["jsonrpc"] = "1.0"
+ elif mutation == "rpc-error":
+ response.pop("result")
+ response["error"] = {"code": -32409, "message": "private diagnostic"}
+ else:
+ response["result"]["request_id"] = "wrong-inner-id"
+ return response
+
+ async with sb.driver.connect(service="mcp", transport="mcp") as driver:
+ transport.mutate = mutate
+ with pytest.raises(ChannelError) as error:
+ await driver.channel.exchange(envelope())
+ assert "private" not in str(error.value)
+ assert not transport.sessions
+ await sb.disconnect()
+
+
+async def test_cancel_can_overtake_exchange_and_prevents_late_result(native):
+ transport = McpTransport()
+ transport.exchange_wait = asyncio.Event()
+ sb = await sandbox(transport)
+ async with sb.driver.connect(service="mcp", transport="mcp") as driver:
+ task = asyncio.create_task(driver.channel.exchange(envelope()))
+ await asyncio.wait_for(transport.exchange_started.wait(), 1)
+ await asyncio.wait_for(driver.channel.cancel("request-1"), 1)
+ transport.exchange_wait.set()
+ with pytest.raises(ChannelError, match="after close or cancellation"):
+ await task
+ assert not transport.sessions
+ methods = [event[3]["method"] for event in transport.events if event[3]]
+ assert methods.index("cua/driver/v1/cancel") < methods.index("cua/driver/v1/close")
+ await sb.disconnect()
+
+
+ "body,media",
+ [
+ ('{"jsonrpc":"2.0","id":"expected","id":"expected","result":{}}', "application/json"),
+ ('{"jsonrpc":"2.0","id":"expected","result":NaN}', "application/json"),
+ ('data: {"jsonrpc":"2.0","id":"expected","result":{}}\n', "text/event-stream"),
+ (
+ 'data: {"jsonrpc":"2.0","id":"expected","result":{}}\n\ndata: {}\n\n',
+ "text/event-stream",
+ ),
+ ("{}", "text/html"),
+ ('{"jsonrpc":"2.0","id":true,"result":{}}', "application/json"),
+ ],
+)
+def test_decoder_refuses_ambiguous_incomplete_or_non_json_responses(body, media):
+ with pytest.raises(McpCarrierError, match="malformed"):
+ _response(httpx.Response(200, content=body, headers={"Content-Type": media}), "expected")
+
+
+async def test_malformed_initialize_still_deletes_allocated_session(native):
+ transport = McpTransport()
+ transport.mutate = lambda method, response: dict(response, id="wrong")
+ sb = await sandbox(transport)
+ with pytest.raises(ChannelError, match="malformed"):
+ async with sb.driver.connect(service="mcp", transport="mcp"):
+ pass
+ assert not transport.sessions
+ assert transport.events[-1][1] == "DELETE"
+ await sb.disconnect()
+
+
+async def test_disconnect_during_initialization_cleans_late_session(native, monkeypatch):
+ transport = McpTransport()
+ entered, released = asyncio.Event(), asyncio.Event()
+ original = transport.request_service
+
+ async def delayed(*args, **kwargs):
+ if (kwargs.get("json_body") or {}).get("method") == "initialize":
+ entered.set()
+ await released.wait()
+ return await original(*args, **kwargs)
+
+ monkeypatch.setattr(transport, "request_service", delayed)
+ sb = await sandbox(transport)
+
+ async def connect():
+ async with sb.driver.connect(service="mcp", transport="mcp"):
+ pytest.fail("disconnected accessor must not yield")
+
+ opening = asyncio.create_task(connect())
+ await entered.wait()
+ closing = asyncio.create_task(sb.driver.close())
+ await asyncio.sleep(0)
+ released.set()
+ await closing
+ with pytest.raises(ChannelError, match="closed during"):
+ await opening
+ assert not transport.sessions
+ assert all((event[3] or {}).get("method") != "cua/driver/v1/open" for event in transport.events)
+ await sb.disconnect()
diff --git a/libs/python/cua-sandbox/tests/test_driver_mcp_native.py b/libs/python/cua-sandbox/tests/test_driver_mcp_native.py
new file mode 100644
index 0000000000..9b0ee74f9d
--- /dev/null
+++ b/libs/python/cua-sandbox/tests/test_driver_mcp_native.py
@@ -0,0 +1,116 @@
+"""Real generated Driver binding over a synthetic MCP/Fleet carrier."""
+
+import asyncio
+
+import pytest
+
+from .test_driver_mcp import McpTransport, sandbox
+from .test_typed_driver_native import sdk as _sdk_fixture
+
+sdk = _sdk_fixture
+
+
[email protected]("sse", [False, True])
+async def test_actual_generated_driver_and_typed_records_over_mcp(sdk, sse):
+ transport = McpTransport(sse=sse)
+ transport.response_data["result"] = {
+ "content": [{"type": "text", "text": "typed-mcp-fixture"}],
+ "isError": False,
+ }
+ sb = await sandbox(transport)
+ try:
+ async with sb.driver.connect(service="mcp", transport="mcp") as driver:
+ assert type(driver) is sdk.CuaDriver
+ result = await driver.get_screen_size(sdk.GetScreenSizeInput(session=None))
+ assert result.text == "typed-mcp-fixture"
+ request = transport.events[-1][3]
+ assert request["method"] == "cua/driver/v1/exchange"
+ assert request["params"]["envelope"]["name"] == "get_screen_size"
+ assert request["params"]["envelope"]["arguments"] == {}
+ session = sb.driver.session_name(driver)
+ await driver.get_agent_cursor_state(sdk.GetAgentCursorStateInput(session=session))
+ assert transport.events[-1][3]["params"]["envelope"]["arguments"] == {
+ "session": session
+ }
+ before = len(transport.events)
+ with pytest.raises(TypeError):
+ await driver.get_screen_size(sdk.GetScreenSizeInput(session=123))
+ assert len(transport.events) == before
+ assert not transport.sessions
+ before = len(transport.events)
+ with pytest.raises(sdk.DriverError.Remote, match="closed"):
+ await driver.get_screen_size(sdk.GetScreenSizeInput(session=None))
+ assert len(transport.events) == before
+ finally:
+ await sb.disconnect()
+
+
+async def test_actual_driver_refuses_noncanonical_metadata(sdk):
+ transport = McpTransport()
+ sb = await sandbox(transport)
+ try:
+ async with sb.driver.connect(service="mcp", transport="mcp") as driver:
+ # Metadata still uses the canonical envelope instead of disguising
+ # an ordinary MCP tools/list result as generated Driver metadata.
+ transport.response_data["result"] = {"not": "driver metadata"}
+ with pytest.raises(sdk.DriverError.Protocol, match="invalid metadata"):
+ await driver.metadata()
+ finally:
+ await sb.disconnect()
+
+
+async def test_actual_driver_does_not_gain_trusted_session_binding(sdk):
+ transport = McpTransport()
+ sb = await sandbox(transport)
+ try:
+ async with sb.driver.connect(service="mcp", transport="mcp") as driver:
+ options = sdk.TrustedSessionOptions(
+ public_session="another-session",
+ mode=sdk.SessionPermissionMode.STANDARD,
+ ttl_seconds=60,
+ idle_ttl_seconds=30,
+ capability_manifest_path=None,
+ bounded_manifest_path=None,
+ )
+ before = len(transport.events)
+ with pytest.raises(sdk.DriverError.Remote, match="rebinding is unsupported"):
+ await sdk.create_remote_trusted_session(driver, options)
+ assert len(transport.events) == before
+ finally:
+ await sb.disconnect()
+
+
+async def test_actual_native_future_cancellation_reaches_mcp_receiver(sdk):
+ transport = McpTransport()
+ transport.exchange_wait = asyncio.Event()
+ sb = await sandbox(transport)
+ try:
+ async with sb.driver.connect(service="mcp", transport="mcp") as driver:
+ task = asyncio.create_task(driver.get_screen_size(sdk.GetScreenSizeInput(session=None)))
+ await asyncio.wait_for(transport.exchange_started.wait(), 2)
+ task.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await task
+
+ async def cancellation_received():
+ while True:
+ methods = [event[3] for event in transport.events if event[3]]
+ cancel = next(
+ (m for m in methods if m["method"] == "cua/driver/v1/cancel"), None
+ )
+ if cancel:
+ exchange = next(
+ m for m in methods if m["method"] == "cua/driver/v1/exchange"
+ )
+ assert (
+ cancel["params"]["request_id"]
+ == exchange["params"]["envelope"]["request_id"]
+ )
+ return
+ await asyncio.sleep(0.01)
+
+ await asyncio.wait_for(cancellation_received(), 2)
+ assert not transport.sessions
+ finally:
+ transport.exchange_wait.set()
+ await sb.disconnect()