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
ci-gate: wait only for the workflows of the changed areas; add urgent label (#5995)
cua-agents[bot]b85d1c37407d
diff --git a/.github/ci-areas.json b/.github/ci-areas.jsonnew file mode 100644index 0000000000..15a9dcea55--- /dev/null+++ b/.github/ci-areas.json@@ -0,0 +1,428 @@+{+ "shared": [+ ".github/**",+ "*",+ "**/Cargo.lock",+ "**/rust-toolchain.toml",+ "**/pnpm-lock.yaml",+ "**/pnpm-workspace.yaml",+ "**/package-lock.json",+ "**/uv.lock",+ "libs/cua/Cargo.toml",+ "libs/cua-driver/rust/Cargo.toml",+ "libs/cua-spacesd/Cargo.toml",+ "libs/cua-driver/rust/.cargo/**",+ "libs/cua/.cargo/**",+ "libs/cua/proto/**",+ "libs/cua/crates/cua-proto/**",+ "libs/cua-driver/rust/crates/cua-driver-core/**",+ "libs/cua-driver/rust/crates/cua-driver-contract/**",+ "libs/cua/crates/cua-sandbox-core/**",+ "scripts/ci/**",+ "flake.nix",+ "nix/**"+ ],+ "areas": {+ "relay": {+ "paths": [+ "libs/cua-spacesd/crates/cua-relay/**"+ ],+ "workflows": [+ "ci-cua-relay-image.yml",+ "ci-cua-spacesd.yml",+ "ci-lockfiles.yml",+ "ci-spdx-headers.yml",+ "license-check.yml"+ ],+ "narrowed": true+ },+ "spacesd": {+ "paths": [+ "libs/cua-spacesd/**"+ ],+ "workflows": [+ "cd-image-linux.yml",+ "ci-check-docs-image-refs.yml",+ "ci-check-docs-links.yml",+ "ci-cua-oci-spacesd.yml",+ "ci-cua-relay-image.yml",+ "ci-cua-sandbox-doctor.yml",+ "ci-cua-sdk.yml",+ "ci-cua-spacesd.yml",+ "ci-elastic.yml",+ "ci-images-spacesd-lag.yml",+ "ci-lockfiles.yml",+ "ci-openkoalabot-example-tauri.yml",+ "ci-release-spacesd-pin.yml",+ "ci-spdx-headers.yml",+ "ci-test-python.yml",+ "e2b-core-nightly.yml",+ "e2e-cua-sdk.yml",+ "license-check.yml",+ "perf-cua-channel.yml"+ ]+ },+ "driver-rust": {+ "paths": [+ "libs/cua-driver/rust/**"+ ],+ "workflows": [+ "cd-cua-perception.yml",+ "ci-check-docs-image-refs.yml",+ "ci-check-docs-links.yml",+ "ci-check-docs.yml",+ "ci-cua-driver-contract-clients.yml",+ "ci-cua-driver-preflight.yml",+ "ci-cua-driver-quick.yml",+ "ci-cua-driver-valgrind.yml",+ "ci-cua-perception-release.yml",+ "ci-cua-s1-weights.yml",+ "ci-cua-sandbox-doctor.yml",+ "ci-cua-spacesd.yml",+ "ci-driver-mcp-candidate.yml",+ "ci-lockfiles.yml",+ "ci-nix-linux.yml",+ "ci-platform-linux-portability.yml",+ "ci-rust-format.yml",+ "ci-rust-linux.yml",+ "ci-rust-macos.yml",+ "ci-rust-windows.yml",+ "ci-spdx-headers.yml",+ "ci-swift-linker.yml",+ "ci-test-scripts.yml",+ "ci-ts-cursor-motion.yml",+ "clawhub-cua-driver.yml",+ "e2e-cua-sdk.yml",+ "e2e-rust-linux.yml",+ "fuzz-cua-driver.yml",+ "license-check.yml",+ "smoke-cua-driver-live.yml"+ ]+ },+ "driver": {+ "paths": [+ "libs/cua-driver/**",+ "libs/cua-driver-bench/**"+ ],+ "workflows": [+ "cd-cua-perception.yml",+ "ci-check-docs-image-refs.yml",+ "ci-check-docs-links.yml",+ "ci-check-docs.yml",+ "ci-cua-driver-bench.yml",+ "ci-cua-driver-contract-clients.yml",+ "ci-cua-driver-preflight.yml",+ "ci-cua-driver-quick.yml",+ "ci-cua-driver-valgrind.yml",+ "ci-cua-perception-release.yml",+ "ci-cua-s1-weights.yml",+ "ci-cua-sandbox-doctor.yml",+ "ci-cua-spacesd.yml",+ "ci-driver-mcp-candidate.yml",+ "ci-hyprland-plugin.yml",+ "ci-jev-use.yml",+ "ci-lockfiles.yml",+ "ci-nix-linux.yml",+ "ci-platform-linux-portability.yml",+ "ci-rust-format.yml",+ "ci-rust-linux.yml",+ "ci-rust-macos.yml",+ "ci-rust-windows.yml",+ "ci-spdx-headers.yml",+ "ci-swift-linker.yml",+ "ci-test-scripts.yml",+ "ci-ts-cursor-motion.yml",+ "clawhub-cua-driver.yml",+ "docs-driver-first-run-smoke.yml",+ "e2e-cua-sdk.yml",+ "e2e-rust-linux.yml",+ "fuzz-cua-driver.yml",+ "license-check.yml",+ "nightly-hyprland-plugin-requalify.yml",+ "smoke-cua-driver-live.yml"+ ]+ },+ "cua": {+ "paths": [+ "libs/cua/**",+ "tests/e2e/**"+ ],+ "workflows": [+ "cd-image-linux.yml",+ "cd-image-omarchy.yml",+ "chaos-cua-compat.yml",+ "ci-check-docs-image-refs.yml",+ "ci-check-docs-links.yml",+ "ci-check-docs.yml",+ "ci-cua-byoc.yml",+ "ci-cua-compat-daytona.yml",+ "ci-cua-compat-modal.yml",+ "ci-cua-compat.yml",+ "ci-cua-contrib.yml",+ "ci-cua-microvm.yml",+ "ci-cua-oci-spacesd.yml",+ "ci-cua-proto.yml",+ "ci-cua-relay-image.yml",+ "ci-cua-sandbox-doctor.yml",+ "ci-cua-sdk.yml",+ "ci-cua-spaces-macos.yml",+ "ci-cua-spaces-web.yml",+ "ci-cua-spaces.yml",+ "ci-cua-spacesd-html5.yml",+ "ci-cua-spacesd.yml",+ "ci-elastic.yml",+ "ci-lockfiles.yml",+ "ci-openkoalabot-example-tauri.yml",+ "ci-pi-durable-crash.yml",+ "ci-spdx-headers.yml",+ "ci-test-python.yml",+ "ci-vm-density.yml",+ "docs-compile-lanes.yml",+ "docs-nightly.yml",+ "docs-page-tests.yml",+ "e2b-bindings.yml",+ "e2b-core-nightly.yml",+ "e2e-cua-sdk.yml",+ "license-check.yml",+ "nightly-build.yml",+ "nightly-e2b-rollouts.yml",+ "nightly-fork-batch.yml",+ "nightly-qemu-fork.yml",+ "nightly-qemu-ready.yml",+ "nightly-qemu-vmm.yml",+ "perf-cua-channel.yml",+ "space-egress-nightly.yml"+ ]+ },+ "images": {+ "paths": [+ "libs/images/**",+ "scripts/images/**"+ ],+ "workflows": [+ "cd-bench-images.yml",+ "cd-image-linux.yml",+ "cd-image-macos.yml",+ "cd-image-omarchy.yml",+ "cd-image-runtime-gvisor.yml",+ "ci-check-docs-image-refs.yml",+ "ci-check-docs-links.yml",+ "ci-check-docs.yml",+ "ci-cua-spaces-macos.yml",+ "ci-cua-spacesd.yml",+ "ci-images-chromium-pin.yml",+ "ci-images-spacesd-lag.yml",+ "ci-lockfiles.yml",+ "ci-spdx-headers.yml",+ "e2b-core-nightly.yml",+ "e2e-cua-sdk.yml",+ "license-check.yml",+ "nightly-qemu-ready.yml",+ "perf-cua-channel.yml"+ ]+ },+ "spaces-web": {+ "paths": [+ "apps/cua-spaces-web/**",+ "apps/cua-spaces-desktop/**"+ ],+ "workflows": [+ "ci-check-docs-links.yml",+ "ci-cua-spaces-macos.yml",+ "ci-cua-spaces-web.yml",+ "ci-lockfiles.yml",+ "ci-spdx-headers.yml",+ "ci-test-scripts.yml",+ "license-check.yml"+ ]+ },+ "spaces-app": {+ "paths": [+ "apps/cua-spaces/**"+ ],+ "workflows": [+ "ci-check-docs-links.yml",+ "ci-cua-spaces-web.yml",+ "ci-cua-spaces.yml",+ "ci-installers.yml",+ "ci-lockfiles.yml",+ "ci-spdx-headers.yml",+ "license-check.yml"+ ]+ },+ "spaces-macos": {+ "paths": [+ "apps/cua-spaces-macos/**"+ ],+ "workflows": [+ "ci-check-docs-links.yml",+ "ci-cua-spaces-macos.yml",+ "ci-cua-spaces-web.yml",+ "ci-lockfiles.yml",+ "ci-spdx-headers.yml",+ "ci-test-scripts.yml",+ "license-check.yml"+ ]+ },+ "python": {+ "paths": [+ "libs/python/**",+ "libs/cua-bench/**",+ "libs/cua-bench-rl/**",+ "libs/cua-s1/**"+ ],+ "workflows": [+ "ci-bench-ale-compat.yml",+ "ci-check-docs-image-refs.yml",+ "ci-check-docs-links.yml",+ "ci-check-docs.yml",+ "ci-cua-contrib.yml",+ "ci-cua-driver-contract-clients.yml",+ "ci-cua-s1-weights.yml",+ "ci-cua-s1.yml",+ "ci-cua-sdk.yml",+ "ci-driver-mcp-candidate.yml",+ "ci-lint-python.yml",+ "ci-lockfiles.yml",+ "ci-py-agent.yml",+ "ci-py-bench-ui.yml",+ "ci-py-bench.yml",+ "ci-py-core.yml",+ "ci-py-som.yml",+ "ci-spdx-headers.yml",+ "ci-test-python.yml",+ "ci-test-scripts.yml",+ "docs-page-tests.yml",+ "e2b-conformance.yml",+ "e2e-cua-sdk.yml",+ "license-check.yml"+ ]+ },+ "typescript": {+ "paths": [+ "libs/typescript/**",+ "libs/cuabot/**"+ ],+ "workflows": [+ "ci-check-docs-image-refs.yml",+ "ci-check-docs-links.yml",+ "ci-container-cuabot.yml",+ "ci-lint-typescript.yml",+ "ci-lockfiles.yml",+ "ci-spdx-headers.yml",+ "ci-ts-core.yml",+ "ci-ts-cursor-motion.yml",+ "license-check.yml"+ ]+ },+ "lume": {+ "paths": [+ "libs/lume/**",+ "libs/lumier/**",+ "libs/spaces-sdk-swift/**"+ ],+ "workflows": [+ "ci-check-docs-image-refs.yml",+ "ci-check-docs-links.yml",+ "ci-check-docs.yml",+ "ci-container-lumier.yml",+ "ci-cua-sdk.yml",+ "ci-cua-spaces-macos.yml",+ "ci-lockfiles.yml",+ "ci-spdx-headers.yml",+ "ci-swift-lume.yml",+ "ci-test-scripts.yml",+ "license-check.yml"+ ]+ },+ "containers": {+ "paths": [+ "libs/kasm/**",+ "libs/qemu-docker/**",+ "libs/xfce/**",+ "libs/xfce-cua/**"+ ],+ "workflows": [+ "ci-check-docs-image-refs.yml",+ "ci-check-docs-links.yml",+ "ci-container-kasm.yml",+ "ci-container-qemu-android.yml",+ "ci-container-qemu-linux.yml",+ "ci-container-qemu-windows.yml",+ "ci-container-xfce-cua.yml",+ "ci-container-xfce.yml",+ "ci-lockfiles.yml",+ "ci-spdx-headers.yml",+ "license-check.yml"+ ]+ },+ "docs": {+ "paths": [+ "docs/**",+ "skills/**"+ ],+ "workflows": [+ "ci-check-docs-image-refs.yml",+ "ci-check-docs-links.yml",+ "ci-check-docs.yml",+ "ci-cua-contrib.yml",+ "ci-cua-sandbox-action.yml",+ "ci-jev-use.yml",+ "ci-lockfiles.yml",+ "ci-public-containerdisk-refs.yml",+ "ci-spdx-headers.yml",+ "ci-test-scripts.yml",+ "docs-compile-lanes.yml",+ "docs-driver-first-run-smoke.yml",+ "docs-mcp-corpus-parity.yml",+ "docs-mcp-server-build-push.yml",+ "docs-page-tests.yml",+ "e2e-cua-sdk.yml",+ "license-check.yml"+ ]+ },+ "compat": {+ "paths": [+ "tests/compat/**"+ ],+ "workflows": [+ "chaos-cua-compat.yml",+ "ci-check-docs-links.yml",+ "ci-cua-compat-daytona.yml",+ "ci-cua-compat-e2b.yml",+ "ci-cua-compat-modal.yml",+ "ci-cua-compat.yml",+ "ci-lockfiles.yml",+ "ci-spdx-headers.yml",+ "compat-drift.yml",+ "e2e-compat-examples.yml",+ "license-check.yml"+ ]+ },+ "installers": {+ "paths": [+ "scripts/install/**"+ ],+ "workflows": [+ "ci-check-docs-links.yml",+ "ci-installers.yml",+ "ci-lockfiles.yml",+ "ci-spdx-headers.yml",+ "ci-test-scripts.yml",+ "license-check.yml"+ ]+ },+ "examples": {+ "paths": [+ "examples/**"+ ],+ "workflows": [+ "ci-check-docs-links.yml",+ "ci-lockfiles.yml",+ "ci-openkoalabot-example-tauri.yml",+ "ci-spdx-headers.yml",+ "license-check.yml"+ ]+ }+ }+}diff --git a/.github/scripts/ci_gate_scope.py b/.github/scripts/ci_gate_scope.pynew file mode 100644index 0000000000..25c0863173--- /dev/null+++ b/.github/scripts/ci_gate_scope.py@@ -0,0 +1,180 @@+#!/usr/bin/env python3+"""Decide which workflows `ci-gate` must wait for, from the paths a PR changes.++The area map lives in `.github/ci-areas.json` and is documented in+`docs/contributing/CI.md`. The rules, in order:++1. A changed file that matches `shared`, or matches no area, widens the gate to+ every workflow (the behaviour before path scoping).+2. Otherwise each changed file belongs to the first area whose globs match it.+3. A workflow listed under some area is required only when one of its areas+ changed. A workflow listed under no area is always required, so a new or+ unmapped workflow can never be skipped by accident.++The gate itself never decides what a workflow's own `paths:` filter runs; it+only decides which of the runs that exist it waits for.+"""+from __future__ import annotations++import argparse+import json+import os+import re+import sys+from pathlib import Path++ROOT = Path(__file__).resolve().parents[2]+MAP_PATH = ROOT / '.github/ci-areas.json'+WORKFLOWS = ROOT / '.github/workflows'++# An urgent PR must name the Linear issue or incident that justifies the lane: a Linear key+# of one of our teams (CUA-123, CLE-45), a Linear issue URL, or an incident reference.+URGENT_REFERENCE = re.compile(+ r'(?<![A-Za-z0-9])(?:CUA|CLE)-\d+\b'+ r'|linear\.app/[\w-]+/issue/[A-Za-z0-9-]+'+ r'|(?i:\bincident\b[^\n]{0,80}(?:#\d+|\d+|https?://\S+))'+)+++def load_map(path: Path = MAP_PATH) -> dict:+ return json.loads(path.read_text())+++def glob_to_regex(glob: str) -> re.Pattern:+ out, i = [], 0+ while i < len(glob):+ c = glob[i]+ if glob.startswith('**/', i):+ out.append('(?:.*/)?')+ i += 3+ elif glob.startswith('**', i):+ out.append('.*')+ i += 2+ elif c == '*':+ out.append('[^/]*')+ i += 1+ elif c == '?':+ out.append('[^/]')+ i += 1+ else:+ out.append(re.escape(c))+ i += 1+ return re.compile('^' + ''.join(out) + '$')+++def matches(path: str, globs: list[str]) -> bool:+ return any(glob_to_regex(g).match(path) for g in globs)+++def literal_prefix(glob: str) -> str:+ """The fixed leading part of a glob, cut at the last slash before a wildcard."""+ m = re.search(r'[*?\[]', glob)+ if not m:+ return glob+ return glob[:m.start()].rsplit('/', 1)[0] + '/' if '/' in glob[:m.start()] else ''+++def may_overlap(a: str, b: str) -> bool:+ """Conservative: true unless the two globs provably select disjoint files."""+ pa, pb = literal_prefix(a), literal_prefix(b)+ return pa.startswith(pb) or pb.startswith(pa)+++def area_of(path: str, cfg: dict) -> str | None:+ """The first area owning `path`, or None when it is shared or unknown."""+ if matches(path, cfg['shared']):+ return None+ for name, area in cfg['areas'].items():+ if matches(path, area['paths']):+ return name+ return None+++def scope(files: list[str], cfg: dict) -> tuple[list[str], set[str] | None]:+ """Return (changed areas, workflows to ignore). Ignore is None when nothing is."""+ areas: set[str] = set()+ for f in files:+ a = area_of(f, cfg)+ if a is None:+ return ['all'], set()+ areas.add(a)+ if not files:+ return ['all'], set()+ mapped = {w for a in cfg['areas'].values() for w in a['workflows']}+ needed = {w for name in areas for w in cfg['areas'][name]['workflows']}+ return sorted(areas), mapped - needed+++def ignore_regex(ignored: set[str]) -> str:+ """An anchored regex over workflow file names; empty when nothing is ignored."""+ if not ignored:+ return ''+ return '^(' + '|'.join(re.escape(w) for w in sorted(ignored)) + ')$'+++def urgent_reference_ok(body: str) -> bool:+ return bool(URGENT_REFERENCE.search(body or ''))+++def pr_triggers(workflow: Path) -> list[str] | None:+ """The `pull_request` path globs of a workflow, or None if it has no path filter."""+ import yaml+ on = yaml.safe_load(workflow.read_text()).get(True) or {}+ if not isinstance(on, dict):+ return None+ pr = on.get('pull_request') or {}+ paths = pr.get('paths') if isinstance(pr, dict) else None+ if not paths or 'paths-ignore' in pr:+ return None+ return [p for p in paths if not p.startswith('!')]+++def expected_areas(workflow: Path, cfg: dict) -> set[str]:+ """Every area a workflow's own trigger paths could touch (the superset the map must keep)."""+ paths = pr_triggers(workflow)+ if paths is None:+ return set()+ return {name for name, area in cfg['areas'].items()+ if any(may_overlap(p, g) for p in paths for g in area['paths'])}+++def main() -> int:+ ap = argparse.ArgumentParser()+ ap.add_argument('--map', type=Path, default=MAP_PATH)+ ap.add_argument('--labels', default='')+ ap.add_argument('--body-file', type=Path)+ args = ap.parse_args()+ cfg = load_map(args.map)+ files = [l.strip() for l in sys.stdin if l.strip()]+ areas, ignored = scope(files, cfg)+ regex = ignore_regex(ignored)+ urgent = 'urgent' in [l.strip() for l in args.labels.split(',')]+ lines = [+ f'changed files: {len(files)}',+ f'areas: {", ".join(areas)}',+ f'workflows the gate ignores: {", ".join(sorted(ignored)) or "none (waits for every run)"}',+ ]+ if urgent:+ body = args.body_file.read_text() if args.body_file else ''+ ok = urgent_reference_ok(body)+ lines.append('urgent lane: ' + ('Linear or incident reference found' if ok else+ 'MISSING Linear issue or incident reference in the PR description'))+ if not ok:+ print('\n'.join(lines))+ print('::error::The `urgent` label needs a Linear issue key (for example CUA-123) or '+ 'an incident reference in the PR description.')+ return 1+ print('\n'.join(lines))+ out = os.environ.get('GITHUB_OUTPUT')+ if out:+ with open(out, 'a') as fh:+ fh.write(f'areas={",".join(areas)}\nignore_re={regex}\n')+ summary = os.environ.get('GITHUB_STEP_SUMMARY')+ if summary:+ with open(summary, 'a') as fh:+ fh.write('### ci-gate scope\n\n' + '\n\n'.join(lines) + '\n')+ return 0+++if __name__ == '__main__':+ sys.exit(main())diff --git a/.github/scripts/tests/test_ci_gate_scope.py b/.github/scripts/tests/test_ci_gate_scope.pynew file mode 100644index 0000000000..b27adf6b0f--- /dev/null+++ b/.github/scripts/tests/test_ci_gate_scope.py@@ -0,0 +1,174 @@+import json+import os+import subprocess+import sys+from pathlib import Path++import pytest+import yaml++sys.path.insert(0, str(Path(__file__).resolve().parents[1]))++import ci_gate_scope as scope # noqa: E402++CFG = scope.load_map()+WORKFLOWS = sorted(scope.WORKFLOWS.glob('*.yml'))+MAPPED = {w for a in CFG['areas'].values() for w in a['workflows']}+++def ignored(*files):+ return scope.scope(list(files), CFG)[1]+++def test_relay_only_change_waits_on_relay_and_rust_jobs_only():+ areas, skip = scope.scope(['libs/cua-spacesd/crates/cua-relay/src/mesh.rs'], CFG)+ assert areas == ['relay']+ assert not skip & {'ci-cua-relay-image.yml', 'ci-cua-spacesd.yml'}+ # The slow image, SDK and doctor jobs belong to other areas and do not gate a relay change.+ assert skip >= {'cd-image-linux.yml', 'e2e-cua-sdk.yml', 'ci-cua-sandbox-doctor.yml',+ 'ci-cua-oci-spacesd.yml', 'ci-cua-spaces-web.yml', 'ci-cua-spaces-macos.yml'}+++def test_other_spacesd_change_still_waits_on_the_integration_jobs():+ skip = ignored('libs/cua-spacesd/crates/cua-spacesd/src/lib.rs')+ assert not skip & {'cd-image-linux.yml', 'e2e-cua-sdk.yml', 'ci-cua-sandbox-doctor.yml',+ 'ci-cua-oci-spacesd.yml', 'ci-cua-relay-image.yml'}+++def test_a_change_in_two_areas_needs_both_areas_jobs():+ skip = ignored('libs/cua-spacesd/crates/cua-relay/src/mesh.rs', 'docs/content/a.mdx')+ assert 'ci-check-docs-links.yml' not in skip+ assert 'ci-cua-relay-image.yml' not in skip+ assert 'ci-cua-spaces-web.yml' in skip++[email protected]('path', [+ 'Cargo.lock', 'libs/cua-driver/rust/Cargo.lock', 'README.md', 'package.json',+ '.github/workflows/ci-gate.yml', '.github/ci-areas.json', 'libs/cua/proto/a.proto',+ 'libs/cua-driver/rust/crates/cua-driver-core/src/lib.rs',+ 'libs/cua/crates/cua-proto/src/lib.rs', 'rust-toolchain.toml',+ 'some/unmapped/dir/file.txt',+])+def test_shared_and_unknown_files_wait_on_everything(path):+ areas, skip = scope.scope(['libs/cua-spacesd/crates/cua-relay/a.rs', path], CFG)+ assert areas == ['all']+ assert skip == set()+++def test_empty_change_list_waits_on_everything():+ assert scope.scope([], CFG) == (['all'], set())+++def test_unmapped_workflow_is_never_ignored():+ # A workflow absent from the map is required for every PR.+ for files in (['docs/content/a.mdx'], ['apps/cua-spaces-web/x.ts']):+ assert 'ci-check-emudhra-distrust.yml' not in ignored(*files)+ assert 'ci-check-emudhra-distrust.yml' not in MAPPED++[email protected](('glob', 'path', 'hit'), [+ ('libs/a/**', 'libs/a/b/c.rs', True),+ ('libs/a/**', 'libs/ab/c.rs', False),+ ('*', 'README.md', True),+ ('*', 'docs/README.md', False),+ ('**/Cargo.lock', 'Cargo.lock', True),+ ('**/Cargo.lock', 'a/b/Cargo.lock', True),+ ('libs/*/x.rs', 'libs/a/b/x.rs', False),+])+def test_glob_matching(glob, path, hit):+ assert bool(scope.glob_to_regex(glob).match(path)) is hit+++def test_every_mapped_workflow_exists_and_every_area_name_is_listed_once():+ names = {w.name for w in WORKFLOWS}+ for area in CFG['areas'].values():+ assert set(area['workflows']) <= names+ assert len(area['workflows']) == len(set(area['workflows']))++[email protected]('workflow', WORKFLOWS, ids=lambda w: w.name)+def test_map_covers_every_area_a_workflow_can_trigger_on(workflow):+ """The map may only narrow on purpose: a workflow whose own paths reach an area must+ be listed there, unless the area is marked `narrowed` (then its list is a subset)."""+ for name in scope.expected_areas(workflow, CFG):+ area = CFG['areas'][name]+ if area.get('narrowed'):+ continue+ assert workflow.name in area['workflows'], (+ f'{workflow.name} triggers on paths in area "{name}" but is not listed there; '+ f'add it to .github/ci-areas.json')+++def test_the_gate_and_its_scope_files_are_shared():+ for f in ('.github/workflows/ci-gate.yml', '.github/ci-areas.json',+ '.github/scripts/ci_gate_scope.py'):+ assert scope.area_of(f, CFG) is None++[email protected](('body', 'ok'), [+ ('Fixes CUA-2338', True),+ ('Linear: https://linear.app/trycua/issue/CUA-2338/urgent-fix-lane', True),+ ('Incident #482: relay down', True),+ ('incident 2026-10-25 relay outage', True),+ ('urgent please', False),+ ('', False),+ (None, False),+ ('Co-authored by UTF-8 and sha-256', False),+ ('Linear: CLE-45', True),+])+def test_urgent_reference(body, ok):+ assert scope.urgent_reference_ok(body) is ok+++def test_urgent_label_without_reference_fails_the_gate(tmp_path):+ body = tmp_path / 'body.txt'+ body.write_text('quick fix, no reference')+ done = subprocess.run(+ [sys.executable, str(scope.ROOT / '.github/scripts/ci_gate_scope.py'),+ '--labels', 'bug,urgent', '--body-file', str(body)],+ input='libs/cua-spacesd/crates/cua-relay/a.rs', capture_output=True, text=True)+ assert done.returncode == 1+ assert 'urgent' in done.stdout+++def test_urgent_label_with_reference_uses_the_same_path_scope(tmp_path):+ body = tmp_path / 'body.txt'+ body.write_text('Fixes CUA-2338')+ out = tmp_path / 'out'+ done = subprocess.run(+ [sys.executable, str(scope.ROOT / '.github/scripts/ci_gate_scope.py'),+ '--labels', 'urgent', '--body-file', str(body)],+ input='libs/cua-spacesd/crates/cua-relay/a.rs', capture_output=True, text=True,+ env={**os.environ, 'GITHUB_OUTPUT': str(out)})+ assert done.returncode == 0, done.stdout+ assert 'areas=relay' in out.read_text()+ plain = subprocess.run(+ [sys.executable, str(scope.ROOT / '.github/scripts/ci_gate_scope.py')],+ input='libs/cua-spacesd/crates/cua-relay/a.rs', capture_output=True, text=True,+ env={**os.environ, 'GITHUB_OUTPUT': str(tmp_path / 'out2')})+ assert (tmp_path / 'out2').read_text() == out.read_text()+++def test_gate_runs_the_scope_step_first_and_passes_its_output_to_the_wait_step():+ gate = yaml.safe_load((scope.WORKFLOWS / 'ci-gate.yml').read_text())+ steps = gate['jobs']['ci-gate']['steps']+ assert steps[1]['id'] == 'scope'+ assert steps[2]['env']['IGNORE_RE'] == '${{ steps.scope.outputs.ignore_re }}'+ assert 'labeled' in gate[True]['pull_request']['types']+ assert 'edited' in gate[True]['pull_request']['types']+ assert 'merge_group' in gate[True]+++def test_gate_run_filter_drops_only_ignored_workflows():+ script = yaml.safe_load((scope.WORKFLOWS / 'ci-gate.yml').read_text())['jobs']['ci-gate']['steps'][2]['run']+ jq_filter = next(line.split("='", 1)[1].rsplit("'", 1)[0]+ for line in script.splitlines() if line.strip().startswith('scope_jq='))+ runs = [{'path': '.github/workflows/cd-image-linux.yml@refs/pull/1/merge'},+ {'path': '.github/workflows/ci-cua-spacesd.yml'}]+ program = f'[.[] | select({jq_filter}) | .path] | length'+ def count(ignore):+ return int(subprocess.run(['jq', '-n', '--argjson', 'r', json.dumps(runs), f'$r | {program}'],+ capture_output=True, text=True,+ env={**os.environ, 'IGNORE_RE': ignore}).stdout)+ assert count('') == 2+ assert count('^(cd-image-linux\\.yml)$') == 1diff --git a/.github/scripts/tests/test_ci_gate_workflow.py b/.github/scripts/tests/test_ci_gate_workflow.pyindex 3d883fd8cd..fb0ee2c7e7 100644--- a/.github/scripts/tests/test_ci_gate_workflow.py+++ b/.github/scripts/tests/test_ci_gate_workflow.py@@ -9,7 +9,8 @@ import yamlROOT = Path(__file__).resolve().parents[3]WORKFLOWS = ROOT / '.github/workflows'GATE = yaml.safe_load((WORKFLOWS / 'ci-gate.yml').read_text())-SCRIPT = GATE['jobs']['ci-gate']['steps'][0]['run']+STEPS = {step.get('name'): step for step in GATE['jobs']['ci-gate']['steps']}+SCRIPT = STEPS['Wait for every other workflow on the pull request head']['run']@pytest.mark.parametrize('filename', [diff --git a/.github/scripts/tests/test_e2e_cua_sdk_scope.py b/.github/scripts/tests/test_e2e_cua_sdk_scope.pyindex 93d52faf5f..29e5d893ab 100644--- a/.github/scripts/tests/test_e2e_cua_sdk_scope.py+++ b/.github/scripts/tests/test_e2e_cua_sdk_scope.py@@ -474,7 +474,7 @@ def test_git_writes_github_output(repo, monkeypatch, tmp_path):# --- ci-gate counts a skipped run as passed -------------------------------------GATE_SCRIPT = GATE["jobs"]["ci-gate"]["steps"][0]["run"]+GATE_SCRIPT = next(s["run"] for s in GATE["jobs"]["ci-gate"]["steps"] if s.get("name", "").startswith("Wait for every other workflow"))def run_gate(rows, jobs):diff --git a/.github/workflows/ci-gate.yml b/.github/workflows/ci-gate.ymlindex 3a259a02d8..10bce4aa13 100644--- a/.github/workflows/ci-gate.yml+++ b/.github/workflows/ci-gate.yml@@ -16,11 +16,44 @@ jobs:runs-on: ubuntu-latesttimeout-minutes: 360steps:+ # Which workflows this gate may ignore, from the paths the PR changes (area map:+ # .github/ci-areas.json, docs/contributing/CI.md). The merge queue entry resolves the+ # same pull request and reads the same file list, so both events compute one set.+ # Any failure here fails the gate: nothing is skipped on error.+ - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4+ with:+ persist-credentials: false+ sparse-checkout: |+ .github/ci-areas.json+ .github/scripts/ci_gate_scope.py+ sparse-checkout-cone-mode: false+ - name: Scope the gate to the changed areas+ id: scope+ env:+ GH_TOKEN: ${{ github.token }}+ PR_NUMBER: ${{ github.event.pull_request.number }}+ QUEUE_REF: ${{ github.event.merge_group.head_ref }}+ run: |+ set -euo pipefail+ api() { local out; for _ in 1 2 3 4 5 6; do out=$(gh api "$@") && { printf '%s\n' "$out"; return; }; sleep 20; done; return 1; }+ pr=$PR_NUMBER+ if [[ -n "$QUEUE_REF" ]]; then+ [[ "$QUEUE_REF" =~ /pr-([0-9]+) ]] || { echo "::error::cannot read the pull request from $QUEUE_REF"; exit 1; }+ pr=${BASH_REMATCH[1]}+ fi+ api "repos/$GITHUB_REPOSITORY/pulls/$pr" --jq '.body // ""' > "$RUNNER_TEMP/pr-body.txt"+ labels=$(api "repos/$GITHUB_REPOSITORY/issues/$pr/labels" --jq '[.[].name] | join(",")')+ api --paginate "repos/$GITHUB_REPOSITORY/pulls/$pr/files?per_page=100" \+ --jq '.[] | .filename, (.previous_filename // empty)' > "$RUNNER_TEMP/files.txt"+ # The files API stops at 3000 entries; a PR that large waits on everything.+ if (( $(wc -l < "$RUNNER_TEMP/files.txt") >= 3000 )); then echo ".github/too-many-files" > "$RUNNER_TEMP/files.txt"; fi+ python3 .github/scripts/ci_gate_scope.py --labels "$labels" --body-file "$RUNNER_TEMP/pr-body.txt" < "$RUNNER_TEMP/files.txt"- name: Wait for every other workflow on the pull request headenv:GH_TOKEN: ${{ github.token }}PR_SHA: ${{ github.event.pull_request.head.sha }}QUEUE_REF: ${{ github.event.merge_group.head_ref }}+ IGNORE_RE: ${{ steps.scope.outputs.ignore_re }}run: |set -uo pipefailapi() { local out; for _ in 1 2 3 4 5 6; do out=$(gh api "$@") && { printf '%s\n' "$out"; return; }; sleep 120; done; return 1; }@@ -30,9 +63,12 @@ jobs:pr=${BASH_REMATCH[1]}sha=$(api "repos/$GITHUB_REPOSITORY/pulls/$pr" --jq .head.sha) || exit 1fi+ # IGNORE_RE (from the scope step) names workflow files that belong only to areas this PR+ # did not touch. Empty means wait for every run.+ scope_jq='(env.IGNORE_RE // "") == "" or ((.path | sub("@.*"; "") | split("/") | last) | test(env.IGNORE_RE) | not)'runs() {api --paginate "repos/$GITHUB_REPOSITORY/actions/runs?head_sha=$sha&per_page=100" \- --jq ".workflow_runs[] | select(.workflow_id != $GITHUB_WORKFLOW_ID and (.event == \"pull_request\" or .event == \"pull_request_target\") and (.path | test(\"claude-auto-fix|ci-release-reminder|review-cua-perception-candidates\") | not)) | [.workflow_id, .id, .name, .conclusion // \"\", .status] | @tsv"+ --jq ".workflow_runs[] | select(.workflow_id != $GITHUB_WORKFLOW_ID and (.event == \"pull_request\" or .event == \"pull_request_target\") and (.path | test(\"claude-auto-fix|ci-release-reminder|review-cua-perception-candidates\") | not) and ($scope_jq)) | [.workflow_id, .id, .name, .conclusion // \"\", .status] | @tsv"}GITHUB_WORKFLOW_ID=$(api "repos/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" --jq .workflow_id) || exit 1# Two identical listings cannot prove every run has appeared, so no verdict is alloweddiff --git a/docs/contributing/CI.md b/docs/contributing/CI.mdnew file mode 100644index 0000000000..1e37c4a340--- /dev/null+++ b/docs/contributing/CI.md@@ -0,0 +1,77 @@+# CI++Every pull request must pass one required check, **CI: gate** (`ci-gate`). The gate waits for the other+pull request workflows and passes when they pass. This page explains which of those workflows it waits for.++## Path-scoped gate++A workflow still starts on its own `paths:` filter. The gate then waits only for the workflows that belong+to the areas the pull request changed. Slow jobs for other areas (for example the Linux image build on a+relay-only change) still run, but they no longer hold up the merge.++The area map is [`.github/ci-areas.json`](../../.github/ci-areas.json). The scope step in+`.github/workflows/ci-gate.yml` runs [`.github/scripts/ci_gate_scope.py`](../../.github/scripts/ci_gate_scope.py)+on the pull request's file list.++Rules, in order:++1. A changed file that matches a **shared** glob, or matches no area at all, makes the gate wait for every run, as it did before scoping.+2. Any other changed file belongs to the first area (top to bottom in the table) whose globs match it.+3. A workflow listed under an area is required only when one of its areas changed.+4. A workflow listed under no area (for example the CLA, eMudhra and release-metadata checks) is always required. A new workflow is therefore required until someone maps it.++Merge-queue runs (`merge_group`) read the file list of the same pull request through the same API call, so+the queue and the pull request wait on the same set. If the scope step fails for any reason, the gate fails.+It never skips on error.++### Shared files (wait for everything)++`.github/**`, `*`, `**/Cargo.lock`, `**/rust-toolchain.toml`, `**/pnpm-lock.yaml`, `**/pnpm-workspace.yaml`, `**/package-lock.json`, `**/uv.lock`, `libs/cua/Cargo.toml`, `libs/cua-driver/rust/Cargo.toml`, `libs/cua-spacesd/Cargo.toml`, `libs/cua-driver/rust/.cargo/**`, `libs/cua/.cargo/**`, `libs/cua/proto/**`, `libs/cua/crates/cua-proto/**`, `libs/cua-driver/rust/crates/cua-driver-core/**`, `libs/cua-driver/rust/crates/cua-driver-contract/**`, `libs/cua/crates/cua-sandbox-core/**`, `scripts/ci/**`, `flake.nix`, `nix/**`++Any file outside every area below also counts as shared.++### Areas++| Area | Paths | Workflows mapped | Slow jobs that gate it |+|---|---|---|---|+| `relay` | `libs/cua-spacesd/crates/cua-relay/**` | 5 (narrowed by hand) | `ci-cua-relay-image`, `ci-cua-spacesd` |+| `spacesd` | `libs/cua-spacesd/**` | 19 | `cd-image-linux`, `ci-cua-oci-spacesd`, `ci-cua-relay-image`, `ci-cua-sandbox-doctor`, `ci-cua-sdk`, `ci-cua-spacesd`, `ci-openkoalabot-example-tauri`, `ci-test-python`, `e2e-cua-sdk` |+| `driver-rust` | `libs/cua-driver/rust/**` | 30 | `ci-check-docs`, `ci-cua-sandbox-doctor`, `ci-cua-spacesd`, `ci-rust-linux`, `ci-rust-macos`, `ci-rust-windows`, `e2e-cua-sdk`, `e2e-rust-linux` |+| `driver` | `libs/cua-driver/**`, `libs/cua-driver-bench/**` | 35 | `ci-check-docs`, `ci-cua-sandbox-doctor`, `ci-cua-spacesd`, `ci-rust-linux`, `ci-rust-macos`, `ci-rust-windows`, `e2e-cua-sdk`, `e2e-rust-linux` |+| `cua` | `libs/cua/**`, `tests/e2e/**` | 44 | `cd-image-linux`, `ci-check-docs`, `ci-cua-oci-spacesd`, `ci-cua-relay-image`, `ci-cua-sandbox-doctor`, `ci-cua-sdk`, `ci-cua-spaces-macos`, `ci-cua-spaces-web`, `ci-cua-spaces`, `ci-cua-spacesd`, `ci-openkoalabot-example-tauri`, `ci-test-python`, `e2b-bindings`, `e2e-cua-sdk` |+| `images` | `libs/images/**`, `scripts/images/**` | 19 | `cd-image-linux`, `ci-check-docs`, `ci-cua-spaces-macos`, `ci-cua-spacesd`, `e2e-cua-sdk` |+| `spaces-web` | `apps/cua-spaces-web/**`, `apps/cua-spaces-desktop/**` | 7 | `ci-cua-spaces-macos`, `ci-cua-spaces-web` |+| `spaces-app` | `apps/cua-spaces/**` | 7 | `ci-cua-spaces-web`, `ci-cua-spaces` |+| `spaces-macos` | `apps/cua-spaces-macos/**` | 7 | `ci-cua-spaces-macos`, `ci-cua-spaces-web` |+| `python` | `libs/python/**`, `libs/cua-bench/**`, `libs/cua-bench-rl/**`, `libs/cua-s1/**` | 24 | `ci-check-docs`, `ci-cua-sdk`, `ci-test-python`, `e2e-cua-sdk` |+| `typescript` | `libs/typescript/**`, `libs/cuabot/**` | 9 | none of the slow jobs |+| `lume` | `libs/lume/**`, `libs/lumier/**`, `libs/spaces-sdk-swift/**` | 11 | `ci-check-docs`, `ci-cua-sdk`, `ci-cua-spaces-macos`, `ci-swift-lume` |+| `containers` | `libs/kasm/**`, `libs/qemu-docker/**`, `libs/xfce/**`, `libs/xfce-cua/**` | 11 | none of the slow jobs |+| `docs` | `docs/**`, `skills/**` | 17 | `ci-check-docs`, `e2e-cua-sdk` |+| `compat` | `tests/compat/**` | 11 | none of the slow jobs |+| `installers` | `scripts/install/**` | 6 | none of the slow jobs |+| `examples` | `examples/**` | 5 | `ci-openkoalabot-example-tauri` |++The `relay` area is narrowed by hand: the relay is a standalone server, so a change under+`libs/cua-spacesd/crates/cua-relay/` waits for `ci-cua-relay-image`, `ci-cua-spacesd` (the Rust workspace+build, lint and tests) and the cheap repo checks, and not for the Linux image, SDK end-to-end, image doctor or OCI jobs.+Every other area lists every workflow whose own `paths:` reach it.++### Keeping the map correct++`.github/scripts/tests/test_ci_gate_scope.py` (run by `CI: Test Scripts`) fails when a workflow's+`pull_request` paths reach an area that does not list it. When you add a workflow with a `paths:` filter,+or add a path to one, add it to the matching areas in `.github/ci-areas.json`. Changing the map or the gate+is a `.github/**` change, so it waits for every workflow.++## Urgent-fix lane++Label a pull request `urgent` for a production fix that cannot wait for the full suite:++- The gate still scopes to the changed areas (the same logic as above). The lane skips nothing else.+- The pull request description must reference a Linear issue (`CUA-123`, `CLE-45` or a Linear issue URL) or an+ incident (`Incident #482`, `incident 2026-10-25 relay outage`). The gate fails the pull request without one,+ so it blocks the merge. Edit the description to fix it; the gate re-runs on `edited`.+- `trycua/cua` has no merge queue, so an urgent pull request merges with `gh pr merge --auto --squash` as soon+ as its scoped gate is green. Nothing is waiting in front of it.+- Do not use the lane to skip a failing check. A failing required check still blocks the merge.diff --git a/docs/contributing/TESTING.md b/docs/contributing/TESTING.mdindex 3620f8256a..dbfb50c824 100644--- a/docs/contributing/TESTING.md+++ b/docs/contributing/TESTING.md@@ -194,6 +194,9 @@ listed by `pnpm docs:list`); `pnpm docs:check` is the explicit full audit. See## Before Opening a Pull Request+The required `ci-gate` check waits only for the workflows of the areas your pull request changes; see+[CI](CI.md) for the area map and the `urgent` label.+1. Run focused tests while developing.2. Run the complete deterministic test owner for every component changed.3. Run the affected interactive E2E lane when desktop behavior or its contract changes.