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-driver): carry typed envelopes through opt-in MCP streams (#3692)
Francesco Bonacci1138b9bd1ed9
diff --git a/libs/cua-driver/docs/mcp-envelope-carrier.md b/libs/cua-driver/docs/mcp-envelope-carrier.mdnew file mode 100644index 0000000000..224e2fff7e--- /dev/null+++ b/libs/cua-driver/docs/mcp-envelope-carrier.md@@ -0,0 +1,102 @@+# Typed Driver envelopes over MCP++This opt-in candidate implements the [accepted RFC 2512 transport addendum](../../../rfcs/2512-mcp-envelope-carrier.md).+It is not a released SDK feature or a qualification of an existing Fleet image.+The extension carries the canonical Driver envelopes through an existing MCP+transport. It does not replace computer-server, add agent tools, or open a port.++## Runtime ownership and opt-in++Set `CUA_DRIVER_MCP_ENVELOPES=1` in the trusted launcher. An absent value or `0`+keeps the existing MCP implementation. Other values fail startup.++For direct stdio, the MCP process owns the runtime. For an explicitly selected+daemon, both the proxy and daemon must opt in. The proxy requests an envelope+stream on the existing authenticated local socket or named pipe. The daemon+creates and owns the typed sessions. The proxy gains no trusted-session binding+authority. An old or disabled daemon refuses the upgrade; the proxy does not+fall back to another protocol or runtime.++The receiver uses `CUA_DRIVER_ENVELOPE_PERMISSION_MODE`, with Standard as the+default. Unrestricted requires the existing explicit unrestricted host+acknowledgement as well as launcher selection. Capability-manifest hosts remain+unsupported by this first receiver slice. A request cannot select permissions,+an endpoint path, or an independent trusted session.++The same stateful MCP HTTP wrapper can carry the stdio stream. A deployment+still needs its existing authentication boundary and a verified wrapper logging+policy. Do not log raw action arguments or results. This change does not enable+the extension in any image, expose a public unauthenticated listener, or require+the separate private HTTP receiver listener.++## Wire contract for this candidate++`initialize` adds the following capability without changing the ordinary tools:++```json+{+ "capabilities": {+ "experimental": {+ "ai.cua.driver.envelopes": { "version": 1 }+ }+ }+}+```++Clients must verify this exact extension before opening a typed receiver. The+namespaced methods are JSON-RPC requests with acknowledged responses, not+`tools/call` names or cancellation notifications.++| Method | Parameters | Result |+| ------------------------ | ------------------------------------------- | -------------------------------------------------------------------------------------- |+| `cua/driver/v1/open` | `{}` | Existing receiver open result: connection ID, generation, public session, capabilities |+| `cua/driver/v1/exchange` | `connection_id`, `generation`, `envelope` | Existing `DriverResponseEnvelope` |+| `cua/driver/v1/cancel` | `connection_id`, `generation`, `request_id` | `{"ok":true}` after recording cancellation |+| `cua/driver/v1/close` | `connection_id`, `generation` | `{"ok":true}` after invalidating the receiver |++IDs and generations are receiver-generated UUIDs, not credentials. Parameters+reject unknown fields. Requests use JSON-RPC 2.0 with string or integer IDs.+An active outer ID must not be reused: ambiguity ends the stream. The receiver+also refuses duplicate inner action IDs without replaying the action.++Malformed parameters return `-32602`. Receiver service failures map to+`-32000 - status`, such as `-32404` for a foreign/missing connection and+`-32409` for a stale generation. Transport saturation returns `-32029`.+Messages contain bounded reasons, not raw request bodies.++## Lifecycle and limits++Each accepted transport owns a separate receiver registry. Another transport+cannot use its connection IDs. The existing receiver supplies real generations,+deadlines, request ledgers, cancellation, session binding, and permission checks.+There is no action replay or reconnect after a replaced daemon or guest.++Open, cancel, and close do not wait behind pending exchanges. The stream limits+pending action requests to 32 and input lines to 1 MiB. The receiver limits+connections to 64, exchanges to 32, and serialized envelope results to 16 MiB.+Writes have a 10-second bound including lock wait. Idle receiver entries expire+after five minutes without active work, checked at least every 30 seconds.++EOF, output failure, or task cancellation invalidates owned receivers before+aborting transport work. Closing a proxy stream does not shut down a shared+daemon. Direct stdio still shuts down its owned runtime. Interrupted native+effects can outlive the request: cancellation is not rollback, and unknown+completion remains unknown. Closing the MCP HTTP session is not Fleet claim or+pool cleanup.++## Verification and release gate++Run the focused deterministic tests from `libs/cua-driver/rust`:++```sh+cargo test -p cua-driver --bin cua-driver mcp_envelope --locked+cargo test -p cua-driver --bin cua-driver driver_service_http --locked+cargo test -p cua-driver --bin cua-driver proxy --locked+```++Before image enablement, separately prove the generated SDK carrier, real+Linux/Windows guest effects, concurrent session isolation, cancellation,+replacement, computer-server compatibility, and owned-resource cleanup. A+successful wrapper handshake or these headless tests do not prove desktop+behavior. Keep existing images and connection defaults unchanged until that+qualification and the separate rollout approval are complete.diff --git a/libs/cua-driver/rust/crates/cua-driver/src/driver_service_http.rs b/libs/cua-driver/rust/crates/cua-driver/src/driver_service_http.rsindex 9b57a5b84c..5f616aea23 100644--- a/libs/cua-driver/rust/crates/cua-driver/src/driver_service_http.rs+++ b/libs/cua-driver/rust/crates/cua-driver/src/driver_service_http.rs@@ -35,7 +35,7 @@ struct Entry {active: usize,}-struct Service {+pub(crate) struct Service {entries: Mutex<HashMap<String, Entry>>,factory: Arc<Factory>,exchanges: tokio::sync::Semaphore,@@ -65,7 +65,31 @@ impl Drop for Service {}impl Service {- fn reap(&self) {+ #[cfg(test)]+ pub(crate) fn for_test(factory: Arc<Factory>) -> Arc<Self> {+ Arc::new(Self {+ entries: Mutex::new(HashMap::new()),+ factory,+ exchanges: tokio::sync::Semaphore::new(MAX_EXCHANGES),+ })+ }++ pub(crate) fn for_sdk(sdk: Arc<crate::sdk_adapter::SdkAdapter>) -> anyhow::Result<Arc<Self>> {+ let mode = configured_session_mode()?;+ Ok(Arc::new(Self {+ entries: Mutex::new(HashMap::new()),+ factory: Arc::new(move || sdk.create_envelope_receiver(mode)),+ exchanges: tokio::sync::Semaphore::new(MAX_EXCHANGES),+ }))+ }++ pub(crate) fn close_all(&self) {+ for entry in self.entries.lock().unwrap().values() {+ entry.receiver.close();+ }+ }++ pub(crate) fn reap(&self) {self.entries.lock().unwrap().retain(|_, entry| {if entry.active == 0 && entry.touched.elapsed() >= IDLE {entry.receiver.close();@@ -91,7 +115,7 @@ impl Service {})}- async fn route(self: &Arc<Self>, request: Request) -> HttpResult<Value> {+ pub(crate) async fn route(self: &Arc<Self>, request: Request) -> HttpResult<Value> {self.reap();if request.method == "POST" && request.path == "/v1/connections" {let _: Empty = decode(&request.body)?;@@ -214,11 +238,11 @@ fn decode<T: serde::de::DeserializeOwned>(body: &[u8]) -> HttpResult<T> {}#[derive(Debug)]-struct Request {- method: String,- path: String,- generation: Option<String>,- body: Vec<u8>,+pub(crate) struct Request {+ pub(crate) method: String,+ pub(crate) path: String,+ pub(crate) generation: Option<String>,+ pub(crate) body: Vec<u8>,}fn parse_headers(bytes: &[u8]) -> HttpResult<(Request, usize)> {@@ -390,13 +414,8 @@ fn configured_session_mode() -> anyhow::Result<cua_driver_sdk::SessionPermission}pub async fn start(sdk: Arc<crate::sdk_adapter::SdkAdapter>, port: u16) -> anyhow::Result<Server> {- let mode = configured_session_mode()?;+ let service = Service::for_sdk(sdk)?;let listener = TcpListener::bind((std::net::Ipv4Addr::LOCALHOST, port)).await?;- let service = Arc::new(Service {- entries: Mutex::new(HashMap::new()),- factory: Arc::new(move || sdk.create_envelope_receiver(mode)),- exchanges: tokio::sync::Semaphore::new(MAX_EXCHANGES),- });let task = tokio::spawn(async move {let permits = Arc::new(tokio::sync::Semaphore::new(64));let mut tasks = tokio::task::JoinSet::new();diff --git a/libs/cua-driver/rust/crates/cua-driver/src/main.rs b/libs/cua-driver/rust/crates/cua-driver/src/main.rsindex bd836f49e6..7939402c6a 100644--- a/libs/cua-driver/rust/crates/cua-driver/src/main.rs+++ b/libs/cua-driver/rust/crates/cua-driver/src/main.rs@@ -24,6 +24,7 @@ mod cli;mod doctor;mod driver_service_http;mod history_runtime;+mod mcp_envelope;mod mcp_http;mod private_worker;mod proxy;diff --git a/libs/cua-driver/rust/crates/cua-driver/src/mcp_envelope.rs b/libs/cua-driver/rust/crates/cua-driver/src/mcp_envelope.rsnew file mode 100644index 0000000000..fb9d11b803--- /dev/null+++ b/libs/cua-driver/rust/crates/cua-driver/src/mcp_envelope.rs@@ -0,0 +1,879 @@+//! Opt-in typed envelopes over an existing MCP transport, never an agent tool.+//!+//! One service registry belongs to one accepted transport. The existing receiver+//! owns generations, request ledgers, cancellation, permissions and session close.+//! No listener, credential issuer, action replay or runtime fallback is added.++use crate::driver_service_http::{Request as ServiceRequest, Service};+use cua_driver_core::protocol::{initialize_result, Request, Response};+use cua_driver_core::server::{+ observe_proxy_session_started, observe_proxy_tool_completed, tool_observation_timer,+ StdioExecutionPath,+};+use serde::Deserialize;+use serde_json::{json, Value};+use std::collections::HashSet;+use std::sync::Arc;+use std::time::Duration;+use tokio::io::{+ AsyncBufRead, AsyncBufReadExt, AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt, BufReader,+};++pub(crate) const CAPABILITY: &str = "ai.cua.driver.envelopes";+const PREFIX: &str = "cua/driver/v1/";+const MAX_LINE: usize = 1024 * 1024;+const MAX_PENDING: usize = 32;++pub(crate) fn configured() -> anyhow::Result<bool> {+ match std::env::var("CUA_DRIVER_MCP_ENVELOPES") {+ Err(std::env::VarError::NotPresent) => Ok(false),+ Ok(value) if value == "0" => Ok(false),+ Ok(value) if value == "1" => Ok(true),+ _ => anyhow::bail!("CUA_DRIVER_MCP_ENVELOPES must be 0 or 1"),+ }+}++#[derive(Deserialize)]+#[serde(deny_unknown_fields)]+struct Binding {+ connection_id: String,+ generation: String,+ #[serde(default)]+ envelope: Option<Value>,+ #[serde(default)]+ request_id: Option<String>,+}++fn service_request(request: &Request) -> Result<ServiceRequest, &'static str> {+ let params = request.params.clone().ok_or("parameters_required")?;+ if request.method == format!("{PREFIX}open") {+ if params != json!({}) {+ return Err("invalid_open_parameters");+ }+ return Ok(ServiceRequest {+ method: "POST".into(),+ path: "/v1/connections".into(),+ generation: None,+ body: b"{}".to_vec(),+ });+ }+ let fields = params.as_object().ok_or("invalid_binding")?;+ let allowed = match request.method.strip_prefix(PREFIX) {+ Some("exchange") => &["connection_id", "generation", "envelope"][..],+ Some("cancel") => &["connection_id", "generation", "request_id"][..],+ Some("close") => &["connection_id", "generation"][..],+ _ => return Err("unknown_operation"),+ };+ if fields+ .keys()+ .any(|field| !allowed.contains(&field.as_str()))+ {+ return Err("invalid_operation_parameters");+ }+ let binding: Binding = serde_json::from_value(params).map_err(|_| "invalid_binding")?;+ if uuid::Uuid::parse_str(&binding.connection_id).is_err()+ || uuid::Uuid::parse_str(&binding.generation).is_err()+ {+ return Err("invalid_binding");+ }+ let base = format!("/v1/connections/{}", binding.connection_id);+ let (method, path, body) = match request.method.strip_prefix(PREFIX) {+ Some("exchange") if binding.request_id.is_none() => (+ "POST",+ format!("{base}/exchange"),+ binding.envelope.ok_or("envelope_required")?,+ ),+ Some("cancel") if binding.envelope.is_none() => (+ "POST",+ format!("{base}/cancel"),+ json!({"request_id": binding.request_id.ok_or("request_id_required")?}),+ ),+ Some("close") if binding.envelope.is_none() && binding.request_id.is_none() => {+ ("DELETE", base, json!({}))+ }+ _ => return Err("invalid_operation_parameters"),+ };+ Ok(ServiceRequest {+ method: method.into(),+ path,+ generation: Some(binding.generation),+ body: body.to_string().into_bytes(),+ })+}++async fn typed_request(service: Arc<Service>, request: Request) -> Response {+ let id = request.id.clone().unwrap_or(Value::Null);+ let route = match service_request(&request) {+ Ok(route) => route,+ Err(reason) => return Response::error(id, -32602, reason),+ };+ match service.route(route).await {+ Ok(result) => Response::ok(id, result),+ Err((status, reason)) => Response::error(id, -32000 - i64::from(status), reason),+ }+}++struct Cleanup {+ service: Arc<Service>,+ sdk: Arc<crate::sdk_adapter::SdkAdapter>,+ session: String,+}+impl Drop for Cleanup {+ fn drop(&mut self) {+ self.service.close_all();+ self.sdk.end_transport_sessions(&self.session);+ }+}++/// Shared direct-stdio / daemon-hosted stream. EOF closes owned sessions only.+pub(crate) async fn run<R, W>(+ sdk: Arc<crate::sdk_adapter::SdkAdapter>,+ mut reader: R,+ writer: W,+) -> anyhow::Result<()>+where+ R: AsyncBufRead + Unpin,+ W: AsyncWrite + Unpin + Send + 'static,+{+ let service = Service::for_sdk(sdk.clone())?;+ run_with_service(sdk, service, &mut reader, writer).await+}++async fn run_with_service<R, W>(+ sdk: Arc<crate::sdk_adapter::SdkAdapter>,+ service: Arc<Service>,+ reader: &mut R,+ writer: W,+) -> anyhow::Result<()>+where+ R: AsyncBufRead + Unpin,+ W: AsyncWrite + Unpin + Send + 'static,+{+ let session = format!("mcp-typed-{}", uuid::Uuid::new_v4());+ // Declared first so receiver invalidation precedes task abort on every exit,+ // including cancellation of the enclosing transport future.+ let mut tasks = tokio::task::JoinSet::new();+ let cleanup = Cleanup {+ service: service.clone(),+ sdk: sdk.clone(),+ session: session.clone(),+ };+ let writer = Arc::new(tokio::sync::Mutex::new(writer));+ let mut line = Vec::new();+ let legacy_serial = Arc::new(tokio::sync::Mutex::new(()));+ let mut pending = HashSet::new();+ let mut reaper = tokio::time::interval(Duration::from_secs(30));+ let mut session_observed = false;+ loop {+ // read_until is cancellation-safe. Keep partial bytes across task and+ // reaper wakeups, and retain the original total line budget.+ let mut bounded_reader = (&mut *reader).take((MAX_LINE + 1 - line.len()) as u64);+ let n = tokio::select! {+ read = bounded_reader.read_until(b'\n', &mut line) => read?,+ done = tasks.join_next(), if !tasks.is_empty() => {+ let id = done.expect("nonempty task set")??;+ pending.remove(&id);+ continue;+ }+ _ = reaper.tick() => {+ service.reap();+ continue;+ }+ };+ if n == 0 {+ break;+ }+ anyhow::ensure!(+ line.len() <= MAX_LINE,+ "MCP envelope request exceeds size limit"+ );+ let raw: Value = match serde_json::from_slice(&line) {+ Ok(raw) => raw,+ Err(_) => {+ line.clear();+ write_response(&writer, Response::parse_error()).await?;+ continue;+ }+ };+ line.clear();+ let valid_id = raw+ .get("id")+ .is_none_or(|id| id.is_string() || id.as_i64().is_some() || id.as_u64().is_some());+ let request: Request = match serde_json::from_value::<Request>(raw) {+ Ok(request) if valid_id && request.jsonrpc == "2.0" => request,+ _ => {+ write_response(+ &writer,+ Response::error(Value::Null, -32600, "invalid_request"),+ )+ .await?;+ continue;+ }+ };+ // Typed control methods require acknowledged requests. Ordinary MCP+ // notifications retain the legacy behavior; no cancellation is invented.+ if request.is_notification() {+ continue;+ }+ let id = request.id.clone().unwrap_or(Value::Null);+ let key = id.to_string();+ // Responding to a duplicate active ID would itself be ambiguous. End+ // this transport rather than miscorrelating an action or replaying it.+ anyhow::ensure!(!pending.contains(&key), "duplicate active MCP request ID");+ if request.method == "initialize" {+ let mut result = initialize_result();+ result["capabilities"]["experimental"][CAPABILITY] = json!({"version": 1});+ if !session_observed {+ if let Some(metadata) = request.initialize_metadata() {+ observe_proxy_session_started(metadata);+ session_observed = true;+ }+ }+ write_response(&writer, Response::ok(id, result)).await?;+ continue;+ }+ if request.method.starts_with(PREFIX) {+ // Open/cancel/close never wait behind a native action. The receiver+ // bounds exchange concurrency independently from these controls.+ if request.method != format!("{PREFIX}exchange") {+ write_response(&writer, typed_request(service.clone(), request).await).await?;+ continue;+ }+ }+ if tasks.len() >= MAX_PENDING {+ write_response(&writer, Response::error(id, -32029, "in_flight_limit")).await?;+ continue;+ }+ let service = service.clone();+ let writer = writer.clone();+ let sdk = sdk.clone();+ let session = session.clone();+ let serial = legacy_serial.clone();+ pending.insert(key.clone());+ tasks.spawn(async move {+ let response = if request.method.starts_with(PREFIX) {+ typed_request(service, request).await+ } else {+ let _guard = serial.lock().await;+ let mut request = request;+ crate::proxy::apply_direct_session_identity(&mut request, &session);+ let context = request.tool_call().ok().and_then(|call| {+ sdk.begin_tool_call(+ &call.name,+ &call.args,+ cua_driver_core::session::SessionTransport::McpStdio,+ cua_driver_core::session::SessionClientKind::Mcp,+ )+ });+ let timer = tool_observation_timer(+ &request,+ |name| sdk.is_known_tool(name),+ StdioExecutionPath::DirectDaemon,+ );+ let response = cua_driver_core::server::handle_request_with_transport_session(+ request,+ id,+ sdk.as_ref(),+ &session,+ )+ .await;+ if let Some(timer) = timer {+ let outcome = timer.finish(&response);+ if let Some(context) = context {+ context.complete(&outcome);+ }+ observe_proxy_tool_completed(outcome);+ }+ response+ };+ write_response(&writer, response).await?;+ Ok::<_, anyhow::Error>(key)+ });+ }+ // Close before abort: the receiver invalidates in-flight and queued work.+ // Dropping JoinSet also aborts on malformed input or broken output.+ drop(cleanup);+ tasks.abort_all();+ while tasks.join_next().await.is_some() {}+ Ok(())+}++async fn write_response<W: AsyncWrite + Unpin>(+ writer: &Arc<tokio::sync::Mutex<W>>,+ response: Response,+) -> anyhow::Result<()> {+ let mut bytes = serde_json::to_vec(&response)?;+ bytes.push(b'\n');+ tokio::time::timeout(Duration::from_secs(10), async {+ let mut writer = writer.lock().await;+ writer.write_all(&bytes).await?;+ writer.flush().await+ })+ .await??;+ Ok(())+}++/// Called only after the daemon's existing local-peer authentication succeeds.+pub(crate) async fn accept<R, W>(+ sdk: Arc<crate::sdk_adapter::SdkAdapter>,+ reader: R,+ mut writer: W,+) -> anyhow::Result<()>+where+ R: AsyncBufRead + Unpin,+ W: AsyncWrite + Unpin + Send + 'static,+{+ let service = Service::for_sdk(sdk.clone());+ let enabled = configured()?;+ let acknowledgement = if enabled && service.is_ok() {+ crate::serve::DaemonResponse::ok(json!({"mcp_envelope_stream": 1}))+ } else {+ crate::serve::DaemonResponse::err("MCP envelope stream unavailable", 77)+ };+ writer+ .write_all((serde_json::to_string(&acknowledgement)? + "\n").as_bytes())+ .await?;+ writer.flush().await?;+ anyhow::ensure!(enabled, "MCP envelope stream is disabled");+ run_with_service(sdk, service?, &mut { reader }, writer).await+}++pub(crate) async fn proxy(socket_path: &str) -> anyhow::Result<()> {+ #[cfg(unix)]+ let stream = tokio::net::UnixStream::connect(socket_path).await?;+ #[cfg(windows)]+ let stream = tokio::net::windows::named_pipe::ClientOptions::new().open(socket_path)?;+ relay(stream).await+}++async fn relay<S: AsyncRead + AsyncWrite + Unpin>(stream: S) -> anyhow::Result<()> {+ relay_io(stream, tokio::io::stdin(), tokio::io::stdout()).await+}++async fn relay_io<S, I, O>(stream: S, mut stdin: I, mut stdout: O) -> anyhow::Result<()>+where+ S: AsyncRead + AsyncWrite + Unpin,+ I: AsyncRead + Unpin,+ O: AsyncWrite + Unpin,+{+ let (reader, mut writer) = tokio::io::split(stream);+ let mut reader = BufReader::new(reader);+ writer+ .write_all(b"{\"method\":\"mcp_envelope_stream\"}\n")+ .await?;+ writer.flush().await?;+ let mut ack = Vec::new();+ tokio::time::timeout(+ Duration::from_secs(4),+ (&mut reader).take(16385).read_until(b'\n', &mut ack),+ )+ .await??;+ anyhow::ensure!(ack.len() <= 16384, "MCP envelope handshake exceeds limit");+ let ack: Value = serde_json::from_slice(&ack)+ .map_err(|_| anyhow::anyhow!("Invalid MCP envelope handshake"))?;+ anyhow::ensure!(+ ack["ok"] == true && ack["result"]["mcp_envelope_stream"] == 1,+ "Selected daemon does not support MCP envelopes"+ );+ // No reconnect: daemon replacement closes this transport and its handles.+ tokio::select! {+ result = tokio::io::copy(&mut stdin, &mut writer) => { result?; writer.shutdown().await?; }+ result = tokio::io::copy(&mut reader, &mut stdout) => { result?; anyhow::bail!("MCP envelope daemon connection ended"); }+ }+ Ok(())+}++#[cfg(test)]+mod tests {+ use super::*;+ use cua_driver_sdk::remote_receiver::{DriverEnvelopeExecutor, DriverEnvelopeReceiver};+ use cua_driver_sdk::DriverError;+ use std::sync::atomic::{AtomicUsize, Ordering};+ use tokio::io::{DuplexStream, ReadHalf, WriteHalf};++ fn request(method: &str, params: Value) -> Request {+ serde_json::from_value(+ json!({"jsonrpc":"2.0","id":1,"method":format!("{PREFIX}{method}"),"params":params}),+ )+ .unwrap()+ }++ fn binding() -> Value {+ json!({"connection_id":uuid::Uuid::new_v4().to_string(),"generation":uuid::Uuid::new_v4().to_string()})+ }++ #[test]+ fn strict_operation_parameters_never_accept_authority_or_paths() {+ assert!(service_request(&request("open", json!({}))).is_ok());+ for invalid in [+ Value::Null,+ json!([]),+ json!({"permission_mode":"unrestricted"}),+ json!({"session":"other"}),+ ] {+ assert!(service_request(&request("open", invalid)).is_err());+ }+ for operation in ["exchange", "cancel", "close"] {+ let mut valid = binding();+ if operation == "exchange" {+ valid["envelope"] = json!({});+ }+ if operation == "cancel" {+ valid["request_id"] = json!("r1");+ }+ assert!(service_request(&request(operation, valid.clone())).is_ok());+ for field in ["path", "session", "permission_mode", "extra"] {+ let mut invalid = valid.clone();+ invalid[field] = Value::Null;+ assert!(service_request(&request(operation, invalid)).is_err());+ }+ valid["connection_id"] = json!("../other");+ assert!(service_request(&request(operation, valid)).is_err());+ }+ let mut invalid = binding();+ invalid["envelope"] = Value::Null;+ assert!(service_request(&request("close", invalid)).is_err());+ assert!(service_request(&request("unknown", binding())).is_err());+ }++ #[test]+ fn extension_requires_explicit_launcher_opt_in() {+ const CHILD: &str = "CUA_TEST_MCP_ENVELOPE_OPT_IN";+ if let Ok(expected) = std::env::var(CHILD) {+ match expected.as_str() {+ "on" => assert!(configured().unwrap()),+ "off" => assert!(!configured().unwrap()),+ "error" => assert!(configured().is_err()),+ _ => panic!("invalid synthetic expectation"),+ }+ return;+ }+ for (value, expected) in [+ (None, "off"),+ (Some("0"), "off"),+ (Some("1"), "on"),+ (Some("true"), "error"),+ (Some(""), "error"),+ ] {+ let mut child = std::process::Command::new(std::env::current_exe().unwrap());+ child+ .args([+ "--exact",+ "mcp_envelope::tests::extension_requires_explicit_launcher_opt_in",+ ])+ .env(CHILD, expected)+ .env_remove("CUA_DRIVER_MCP_ENVELOPES");+ if let Some(value) = value {+ child.env("CUA_DRIVER_MCP_ENVELOPES", value);+ }+ assert!(child.output().unwrap().status.success());+ }+ }++ struct Fake {+ closed: Arc<AtomicUsize>,+ dispatched: Arc<AtomicUsize>,+ slow: bool,+ }+ #[async_trait::async_trait]+ impl DriverEnvelopeExecutor for Fake {+ async fn metadata(&self) -> Result<Value, DriverError> {+ self.dispatched.fetch_add(1, Ordering::SeqCst);+ if self.slow {+ std::future::pending().await+ } else {+ Ok(json!({"probe":true}))+ }+ }+ async fn list_tools(&self) -> Result<Value, DriverError> {+ Ok(json!({"tools":[]}))+ }+ async fn call(&self, _: String, _: Value) -> Result<Value, DriverError> {+ unreachable!()+ }+ fn close(&self) {+ self.closed.fetch_add(1, Ordering::SeqCst);+ }+ }++ fn service(slow: bool) -> (Arc<Service>, Arc<AtomicUsize>, Arc<AtomicUsize>) {+ let closed = Arc::new(AtomicUsize::new(0));+ let dispatched = Arc::new(AtomicUsize::new(0));+ let c = closed.clone();+ let d = dispatched.clone();+ (+ Service::for_test(Arc::new(move || {+ Ok((+ DriverEnvelopeReceiver::new(Arc::new(Fake {+ closed: c.clone(),+ dispatched: d.clone(),+ slow,+ })),+ "synthetic-session".into(),+ ))+ })),+ closed,+ dispatched,+ )+ }++ fn envelope(id: &str) -> Value {+ json!({"envelope_version":1,"request_id":id,"operation":"metadata","deadline_unix_ms":std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_millis()+60000})+ }++ #[tokio::test]+ async fn real_receiver_rejects_foreign_generation_and_duplicate_action() {+ let (first, closed, dispatched) = service(false);+ let (second, _, _) = service(false);+ let opened =+ serde_json::to_value(typed_request(first.clone(), request("open", json!({}))).await)+ .unwrap();+ let mut params = opened["result"].clone();+ params+ .as_object_mut()+ .unwrap()+ .retain(|key, _| key == "connection_id" || key == "generation");+ let foreign =+ serde_json::to_value(typed_request(second, request("close", params.clone())).await)+ .unwrap();+ assert_eq!(foreign["error"]["code"], -32404);+ let mut stale = params.clone();+ stale["generation"] = json!(uuid::Uuid::new_v4().to_string());+ let stale =+ serde_json::to_value(typed_request(first.clone(), request("close", stale)).await)+ .unwrap();+ assert_eq!(stale["error"]["code"], -32409);+ params["envelope"] = envelope("same-action");+ let success = serde_json::to_value(+ typed_request(first.clone(), request("exchange", params.clone())).await,+ )+ .unwrap();+ assert_eq!(success["result"]["ok"], true);+ let duplicate =+ serde_json::to_value(typed_request(first.clone(), request("exchange", params)).await)+ .unwrap();+ assert_eq!(duplicate["result"]["ok"], false);+ assert_eq!(dispatched.load(Ordering::SeqCst), 1);+ first.close_all();+ assert_eq!(closed.load(Ordering::SeqCst), 1);+ }++ #[tokio::test]+ async fn early_cancel_and_connection_limit_use_the_receiver_ledger() {+ let (service, _, dispatched) = service(false);+ let opened =+ serde_json::to_value(typed_request(service.clone(), request("open", json!({}))).await)+ .unwrap();+ let mut params = opened["result"].clone();+ params+ .as_object_mut()+ .unwrap()+ .retain(|key, _| key == "connection_id" || key == "generation");+ let mut cancel = params.clone();+ cancel["request_id"] = json!("late-arrival");+ let response =+ serde_json::to_value(typed_request(service.clone(), request("cancel", cancel)).await)+ .unwrap();+ assert_eq!(response["result"]["ok"], true);+ params["envelope"] = envelope("late-arrival");+ let response =+ serde_json::to_value(typed_request(service.clone(), request("exchange", params)).await)+ .unwrap();+ assert_eq!(response["result"]["ok"], false);+ assert_eq!(dispatched.load(Ordering::SeqCst), 0);+ for _ in 1..64 {+ let response = serde_json::to_value(+ typed_request(service.clone(), request("open", json!({}))).await,+ )+ .unwrap();+ assert!(response.get("result").is_some());+ }+ let response =+ serde_json::to_value(typed_request(service.clone(), request("open", json!({}))).await)+ .unwrap();+ assert_eq!(response["error"]["code"], -32503);+ }++ async fn sdk() -> Arc<crate::sdk_adapter::SdkAdapter> {+ crate::sdk_adapter::SdkAdapter::load(cua_driver_sdk::CuaDriver::create_for_host(+ cua_driver_sdk::DriverHostOptions {+ cursor: cursor_overlay::CursorConfig {+ enabled: false,+ ..Default::default()+ },+ host_owns_permission_ux: false,+ host_bundle_id: None,+ claude_code_compatibility: false,+ prepare_desktop_environment: false,+ register_host_tools: None,+ authorization_host: None,+ activity_observer: None,+ },+ ))+ .await+ .unwrap()+ }++ struct Client {+ read: BufReader<ReadHalf<DuplexStream>>,+ write: WriteHalf<DuplexStream>,+ }+ impl Client {+ async fn send(&mut self, id: u64, method: &str, params: Value) {+ self.write+ .write_all(+ (json!({"jsonrpc":"2.0","id":id,"method":method,"params":params}).to_string()+ + "\n")+ .as_bytes(),+ )+ .await+ .unwrap();+ }+ async fn receive(&mut self) -> Value {+ let mut line = String::new();+ let n = tokio::time::timeout(Duration::from_secs(2), self.read.read_line(&mut line))+ .await+ .unwrap()+ .unwrap();+ assert_ne!(n, 0, "unexpected EOF");+ serde_json::from_str(&line).unwrap()+ }+ async fn open(&mut self) -> Value {+ self.send(1, &format!("{PREFIX}open"), json!({})).await;+ let mut result = self.receive().await["result"].clone();+ result+ .as_object_mut()+ .unwrap()+ .retain(|key, _| key == "connection_id" || key == "generation");+ result+ }+ }+ fn start(+ sdk: Arc<crate::sdk_adapter::SdkAdapter>,+ service: Arc<Service>,+ ) -> (Client, tokio::task::JoinHandle<anyhow::Result<()>>) {+ let (client, server) = tokio::io::duplex(1024 * 1024);+ let (read, write) = tokio::io::split(client);+ let task = tokio::spawn(async move {+ let (read, write) = tokio::io::split(server);+ run_with_service(sdk, service, &mut BufReader::new(read), write).await+ });+ (+ Client {+ read: BufReader::new(read),+ write,+ },+ task,+ )+ }++ #[tokio::test]+ async fn stream_preserves_legacy_tools_and_closes_on_eof() {+ let _guard = crate::test_runtime_lock().lock().await;+ let sdk = sdk().await;+ let (service, closed, _) = service(false);+ let (mut client, task) = start(sdk.clone(), service);+ client.send(1, "initialize", json!({})).await;+ assert_eq!(+ client.receive().await["result"]["capabilities"]["experimental"][CAPABILITY]["version"],+ 1+ );+ client.send(2, "tools/list", json!({})).await;+ let listed = client.receive().await;+ assert!(listed["result"]["tools"]+ .as_array()+ .is_some_and(|tools| !tools.is_empty()));+ assert!(!listed["result"]["tools"]+ .as_array()+ .unwrap()+ .iter()+ .any(|tool| tool["name"].as_str().unwrap().starts_with(PREFIX)));+ client.open().await;+ client.write.shutdown().await.unwrap();+ tokio::time::timeout(Duration::from_secs(2), task)+ .await+ .unwrap()+ .unwrap()+ .unwrap();+ assert_eq!(closed.load(Ordering::SeqCst), 1);+ sdk.shutdown().await.unwrap();+ }++ #[tokio::test]+ async fn saturated_stream_keeps_acknowledged_cancel_and_close_responsive() {+ let _guard = crate::test_runtime_lock().lock().await;+ let sdk = sdk().await;+ let (service, closed, dispatched) = service(true);+ let (mut client, task) = start(sdk.clone(), service);+ let connection = client.open().await;+ for i in 0..MAX_PENDING {+ let mut params = connection.clone();+ params["envelope"] = envelope(&format!("action-{i}"));+ client+ .send(100 + i as u64, &format!("{PREFIX}exchange"), params)+ .await;+ }+ tokio::time::timeout(Duration::from_secs(2), async {+ while dispatched.load(Ordering::SeqCst) == 0 {+ tokio::task::yield_now().await;+ }+ })+ .await+ .unwrap();+ let mut params = connection.clone();+ params["envelope"] = envelope("overflow");+ client.send(200, &format!("{PREFIX}exchange"), params).await;+ let limit = client.receive().await;+ assert_eq!(limit["id"], 200);+ assert_eq!(limit["error"]["code"], -32029);+ let mut cancel = connection.clone();+ cancel["request_id"] = json!("action-0");+ client.send(201, &format!("{PREFIX}cancel"), cancel).await;+ client+ .send(202, &format!("{PREFIX}close"), connection)+ .await;+ let mut responses = Vec::new();+ for _ in 0..MAX_PENDING + 2 {+ responses.push(client.receive().await);+ }+ for id in [201, 202] {+ assert_eq!(+ responses.iter().find(|r| r["id"] == id).unwrap()["result"]["ok"],+ true+ );+ }+ assert_eq!(+ dispatched.load(Ordering::SeqCst),+ 1,+ "queued actions must not execute"+ );+ assert_eq!(closed.load(Ordering::SeqCst), 1);+ client.write.shutdown().await.unwrap();+ task.await.unwrap().unwrap();+ sdk.shutdown().await.unwrap();+ }++ #[tokio::test]+ async fn duplicate_active_rpc_id_ends_stream_without_replay() {+ let _guard = crate::test_runtime_lock().lock().await;+ let sdk = sdk().await;+ let (service, closed, dispatched) = service(true);+ let (mut client, task) = start(sdk.clone(), service);+ let mut params = client.open().await;+ params["envelope"] = envelope("pending");+ client.send(2, &format!("{PREFIX}exchange"), params).await;+ client.send(2, "ping", json!({})).await;+ assert!(tokio::time::timeout(Duration::from_secs(2), task)+ .await+ .unwrap()+ .unwrap()+ .is_err());+ assert_eq!(closed.load(Ordering::SeqCst), 1);+ assert!(dispatched.load(Ordering::SeqCst) <= 1);+ sdk.shutdown().await.unwrap();+ }++ #[tokio::test]+ async fn abort_and_oversized_input_close_owned_receivers() {+ let _guard = crate::test_runtime_lock().lock().await;+ let sdk = sdk().await;+ for abort in [true, false] {+ let (service, closed, _) = service(true);+ let (mut client, task) = start(sdk.clone(), service);+ let mut params = client.open().await;+ params["envelope"] = envelope("in-flight");+ client.send(2, &format!("{PREFIX}exchange"), params).await;+ if abort {+ task.abort();+ assert!(task.await.unwrap_err().is_cancelled());+ } else {+ let _ = client.write.write_all(&vec![b'x'; MAX_LINE + 1]).await;+ assert!(tokio::time::timeout(Duration::from_secs(2), task)+ .await+ .unwrap()+ .unwrap()+ .is_err());+ }+ assert_eq!(closed.load(Ordering::SeqCst), 1);+ }+ sdk.shutdown().await.unwrap();+ }++ #[tokio::test]+ async fn invalid_jsonrpc_shape_never_allocates_a_receiver() {+ let _guard = crate::test_runtime_lock().lock().await;+ let sdk = sdk().await;+ let (service, closed, _) = service(false);+ let (mut client, task) = start(sdk.clone(), service);+ for invalid in [+ json!({"jsonrpc":"1.0","id":1,"method":format!("{PREFIX}open")}),+ json!({"jsonrpc":"2.0","id":[],"method":format!("{PREFIX}open")}),+ json!({"jsonrpc":"2.0","id":null,"method":format!("{PREFIX}open")}),+ ] {+ client+ .write+ .write_all((invalid.to_string() + "\n").as_bytes())+ .await+ .unwrap();+ assert_eq!(client.receive().await["error"]["code"], -32600);+ }+ client.write.shutdown().await.unwrap();+ task.await.unwrap().unwrap();+ assert_eq!(closed.load(Ordering::SeqCst), 0);+ sdk.shutdown().await.unwrap();+ }++ #[tokio::test]+ async fn relay_refuses_old_daemon_without_forwarding_actions() {+ let (client, server) = tokio::io::duplex(4096);+ let daemon = tokio::spawn(async move {+ let (read, mut write) = tokio::io::split(server);+ let mut read = BufReader::new(read);+ let mut line = String::new();+ read.read_line(&mut line).await.unwrap();+ assert_eq!(+ serde_json::from_str::<Value>(&line).unwrap()["method"],+ "mcp_envelope_stream"+ );+ write.write_all(b"{\"ok\":false}\n").await.unwrap();+ line.clear();+ assert_eq!(read.read_line(&mut line).await.unwrap(), 0);+ });+ assert!(+ relay_io(client, &b"must-not-forward\n"[..], tokio::io::sink())+ .await+ .is_err()+ );+ daemon.await.unwrap();+ }++ #[tokio::test]+ async fn relay_forwards_only_after_ack_and_fails_when_daemon_disappears() {+ let (client, server) = tokio::io::duplex(4096);+ let (mut input, source) = tokio::io::duplex(4096);+ input.write_all(b"synthetic-request\n").await.unwrap();+ let (output, sink) = tokio::io::duplex(4096);+ let daemon = tokio::spawn(async move {+ let (read, mut write) = tokio::io::split(server);+ let mut read = BufReader::new(read);+ let mut line = String::new();+ read.read_line(&mut line).await.unwrap();+ write+ .write_all(b"{\"ok\":true,\"result\":{\"mcp_envelope_stream\":1}}\n")+ .await+ .unwrap();+ line.clear();+ read.read_line(&mut line).await.unwrap();+ assert_eq!(line, "synthetic-request\n");+ write.write_all(b"synthetic-response\n").await.unwrap();+ });+ assert!(relay_io(client, source, sink).await.is_err());+ daemon.await.unwrap();+ let mut response = String::new();+ BufReader::new(output)+ .read_to_string(&mut response)+ .await+ .unwrap();+ assert_eq!(response, "synthetic-response\n");+ }+}diff --git a/libs/cua-driver/rust/crates/cua-driver/src/proxy.rs b/libs/cua-driver/rust/crates/cua-driver/src/proxy.rsindex aec77d80b9..195e63d1c4 100644--- a/libs/cua-driver/rust/crates/cua-driver/src/proxy.rs+++ b/libs/cua-driver/rust/crates/cua-driver/src/proxy.rs@@ -42,6 +42,16 @@ pub async fn run_direct(driver: Arc<cua_driver_sdk::CuaDriver>) -> anyhow::Resulcua_driver_core::authorization::validate_startup_authorization()?;validate_configured_policy()?;let sdk = crate::sdk_adapter::SdkAdapter::load(driver.clone()).await?;+ if crate::mcp_envelope::configured()? {+ let result = crate::mcp_envelope::run(+ sdk.clone(),+ BufReader::new(tokio::io::stdin()),+ tokio::io::stdout(),+ )+ .await;+ sdk.shutdown().await.map_err(anyhow::Error::msg)?;+ return result;+ }let stdin = tokio::io::stdin();let stdout = tokio::io::stdout();let mut reader = BufReader::new(stdin);@@ -131,7 +141,7 @@ pub async fn run_direct(driver: Arc<cua_driver_sdk::CuaDriver>) -> anyhow::Resulsdk.shutdown().await.map_err(anyhow::Error::msg)}-fn apply_direct_session_identity(request: &mut Request, transport_session: &str) {+pub(crate) fn apply_direct_session_identity(request: &mut Request, transport_session: &str) {let Some(arguments) = request.params.as_mut()@@ -178,6 +188,9 @@ pub async fn run_proxy(socket_path: String) -> anyhow::Result<()> {// binding or forwarding any action.let compatibility_client = cua_driver_sdk::CuaDriver::connect(Some(socket_path.clone()))?;compatibility_client.metadata().await?;+ if crate::mcp_envelope::configured()? {+ return crate::mcp_envelope::proxy(&socket_path).await;+ }// Mint this MCP session's identity once at proxy startup. One proxy process// == one MCP session; the daemon outlives it. We stamp this id on everydiff --git a/libs/cua-driver/rust/crates/cua-driver/src/serve.rs b/libs/cua-driver/rust/crates/cua-driver/src/serve.rsindex 738427804c..67e123bc78 100644--- a/libs/cua-driver/rust/crates/cua-driver/src/serve.rs+++ b/libs/cua-driver/rust/crates/cua-driver/src/serve.rs@@ -1072,6 +1072,12 @@ pub async fn run_serve().await;match req.method.as_str() {+ "mcp_envelope_stream" if control_session_id.is_none() && trusted_session.is_none() => {+ // Existing local-peer authentication already passed.+ // Registry and session lifetime belong to this stream.+ let _ = crate::mcp_envelope::accept(reg.clone(), lines.into_inner(), writer).await;+ return;+ }"metadata" => {let resp = daemon_metadata_response();let _ = writer.write_all(@@ -1825,6 +1831,11 @@ pub async fn run_serve().await;match req.method.as_str() {+ "mcp_envelope_stream" if control_session_id.is_none() && trusted_session.is_none() => {+ // Same transport-owned receiver as the Unix branch.+ let _ = crate::mcp_envelope::accept(reg.clone(), lines.into_inner(), writer).await;+ return;+ }"metadata" => {let resp = daemon_metadata_response();let _ = writer.write_all(