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.

ci(cua-driver): build exact MCP candidates for guest qualification (#3694)

Francesco Bonacci87bd0eced019
diff --git a/.github/workflows/ci-driver-mcp-candidate.yml b/.github/workflows/ci-driver-mcp-candidate.yml
new file mode 100644
index 0000000000..f41175cdf5
--- /dev/null
+++ b/.github/workflows/ci-driver-mcp-candidate.yml
@@ -0,0 +1,120 @@
+name: "CI: Driver MCP candidate"
+
+on:
+ pull_request:
+ paths:
+ - ".github/workflows/ci-driver-mcp-candidate.yml"
+ - "libs/cua-driver/rust/crates/cua-driver/src/mcp_envelope.rs"
+ - "libs/cua-driver/rust/crates/cua-driver/src/driver_service_http.rs"
+ - "libs/cua-driver/rust/crates/cua-driver/src/proxy.rs"
+ - "libs/cua-driver/rust/crates/cua-driver/src/serve.rs"
+ - "libs/python/cua-sandbox/cua_sandbox/interfaces/_driver_mcp.py"
+ - "libs/python/cua-sandbox/cua_sandbox/interfaces/driver.py"
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+concurrency:
+ group: driver-mcp-candidate-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ candidate:
+ name: MCP candidate (${{ matrix.os }})
+ runs-on: ${{ matrix.os }}
+ timeout-minutes: 40
+ strategy:
+ fail-fast: false
+ matrix:
+ os: [ubuntu-24.04, windows-latest]
+ defaults:
+ run:
+ shell: bash
+ env:
+ EXPECTED_SOURCE_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+ CARGO_PROFILE_DEV_DEBUG: "0"
+ CUA_TELEMETRY_ENABLED: "false"
+ steps:
+ - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+ with:
+ ref: ${{ github.event.pull_request.head.sha || github.sha }}
+ persist-credentials: false
+ - name: Verify exact source
+ run: |
+ set -euo pipefail
+ test "$(git rev-parse HEAD)" = "$EXPECTED_SOURCE_SHA"
+ test -z "$(git status --porcelain)"
+ - uses: dtolnay/rust-toolchain@stable
+ - uses: Swatinem/rust-cache@9d47c6ad4b02e050fd481d890b2ea34778fd09d6 # v2
+ with:
+ workspaces: "libs/cua-driver/rust -> target"
+ key: mcp-candidate
+ - name: Install Linux build dependencies
+ if: runner.os == 'Linux'
+ run: |
+ sudo apt-get update
+ sudo apt-get install -y --no-install-recommends \
+ clang pkg-config libdbus-1-dev libpipewire-0.3-dev libspa-0.2-dev \
+ libei-dev libxkbcommon-dev libx11-dev libxi-dev libxtst-dev libxext-dev
+ - name: Run envelope receiver and service tests
+ working-directory: libs/cua-driver/rust
+ run: |
+ set -euo pipefail
+ cargo test -p cua-driver --bin cua-driver mcp_envelope --locked
+ cargo test -p cua-driver --bin cua-driver driver_service_http --locked
+ - name: Build disposable-test binaries
+ working-directory: libs/cua-driver/rust
+ run: |
+ set -euo pipefail
+ if [[ "$RUNNER_OS" == Linux ]]; then
+ cargo build --locked -p cua-driver -p cursor-theme-cli --features cua-driver/portal-input
+ else
+ cargo build --locked -p cua-driver -p cursor-theme-cli -p cua-driver-uia
+ fi
+ - name: Bundle exact binaries and provenance
+ run: |
+ python - <<'PY'
+ import hashlib
+ import json
+ import os
+ from pathlib import Path
+ import subprocess
+ import tarfile
+
+ source = subprocess.check_output(["git", "rev-parse", "HEAD"], text=True).strip()
+ assert source == os.environ["EXPECTED_SOURCE_SHA"]
+ assert not subprocess.check_output(["git", "status", "--porcelain"], text=True).strip()
+ windows = os.environ["RUNNER_OS"] == "Windows"
+ names = ["cua-driver", "cua-cursor-theme"] + (["cua-driver-uia"] if windows else [])
+ binaries = [Path("libs/cua-driver/rust/target/debug") / (name + (".exe" if windows else "")) for name in names]
+ assert all(path.is_file() and path.stat().st_size > 0 for path in binaries)
+ bundle = Path("mcp-candidate")
+ bundle.mkdir()
+ metadata = {
+ "source_sha": source,
+ "runner_os": os.environ["RUNNER_OS"],
+ "profile": "dev, debug=0",
+ "features": ["cua-driver/portal-input"] if not windows else [],
+ "rustc": subprocess.check_output(["rustc", "--version"], text=True).strip(),
+ "version": subprocess.check_output([str(binaries[0].resolve()), "--version"], text=True).strip(),
+ "files": {path.name: hashlib.file_digest(path.open("rb"), "sha256").hexdigest() for path in binaries},
+ "qualification": "Test-only unsigned candidate; not a release or image qualification.",
+ }
+ provenance = bundle / "provenance.json"
+ provenance.write_text(json.dumps(metadata, indent=2) + "\n")
+ with tarfile.open(bundle / "candidate.tar.gz", "w:gz") as archive:
+ for path in binaries:
+ archive.add(path, arcname=path.name)
+ archive.add(provenance, arcname=provenance.name)
+ print(json.dumps(metadata, indent=2))
+ PY
+ - name: Upload candidate for separately authorized tests
+ uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08 # v4
+ with:
+ name: driver-mcp-candidate-${{ runner.os }}-${{ github.event.pull_request.head.sha || github.sha }}
+ if-no-files-found: error
+ retention-days: 7
+ path: |
+ mcp-candidate/candidate.tar.gz
+ mcp-candidate/provenance.json
diff --git a/libs/cua-driver/docs/mcp-candidate-qualification.md b/libs/cua-driver/docs/mcp-candidate-qualification.md
new file mode 100644
index 0000000000..f570ca68c4
--- /dev/null
+++ b/libs/cua-driver/docs/mcp-candidate-qualification.md
@@ -0,0 +1,42 @@
+# MCP candidate qualification
+
+The `CI: Driver MCP candidate` workflow builds the exact pull-request head
+on hosted Linux and Windows runners. It runs the envelope receiver and service
+tests, then uploads unsigned development binaries with their source SHA,
+toolchain, build profile, version, and SHA256 hashes. It has read-only repository
+permissions and no Fleet credentials. It does not publish a release, install a
+product, change an image, or connect to a Fleet computer.
+
+These artifacts support separately authorized disposable-guest tests. Check the
+workflow repository, source SHA, successful jobs, and every binary hash before
+using an artifact. Do not select an artifact by version alone: an unreleased
+source build can report the same package version as a released binary.
+
+## Live test gate
+
+For each selected Linux and Windows Fleet image:
+
+1. Record the immutable image reference and installed Driver, computer-server,
+ and MCP-wrapper versions. Use an owned disposable claim and namespace with
+ explicit resource limits and verified cleanup ownership.
+2. Stage the exact candidate separately. Preserve computer-server. Start Driver
+ in the guest's interactive desktop session through its existing socket or
+ named pipe. Enable the envelope opt-in in both the daemon and MCP proxy.
+3. Disable raw request/response logging before action-bearing tests. Reuse the
+ existing named MCP service and access boundary; do not introduce a new
+ network endpoint or substitute the operator's local desktop.
+4. Use matching generated bindings with
+ `sb.driver.connect(service="mcp", transport="mcp")`. Prove a useful guest
+ effect with fresh before/after Driver state and an independent guest
+ postcondition. A successful call alone is not the oracle.
+5. Verify independent sessions, cancellation without claiming rollback, stale
+ session rejection after replacement, access rejection, and continued
+ computer-server functionality. Verify receiver and MCP-session cleanup
+ independently from Fleet resource cleanup.
+6. Delete only the task-owned resources and confirm their absence. Preserve
+ failure and cleanup evidence, including any incomplete result.
+
+A staged development-binary result is not packaged-image certification or the
+full canonical desktop matrix. A release/image enablement decision still needs
+the applicable exact-candidate desktop harness evidence, packaged-image replay,
+and separate rollout approval. Keep existing defaults and images unchanged.