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.

docs(cua-driver): clarify semantic clipboard and release labels (#2797)

Francesco Bonacci0c8a7449c4c0
diff --git a/.github/release-notes/cua-driver-rs.md b/.github/release-notes/cua-driver-rs.md
index b7685ae45a..6cebf9a393 100644
--- a/.github/release-notes/cua-driver-rs.md
+++ b/.github/release-notes/cua-driver-rs.md
@@ -15,3 +15,11 @@ irm https://cua.ai/driver/install.ps1 | iex
Cua Driver ships universal macOS binaries, x86_64 and arm64 Windows builds,
and Linux preview builds. Release assets also include tag-pinned installer and
uninstaller scripts.
+
+## Why GitHub says “Pre-release”
+
+GitHub's label is used only to keep this monorepo's repository-wide “Latest”
+pointer from switching between independently released products. A plain Cua
+Driver SemVer such as `0.17.0` is a stable release; npm and PyPI publish it on
+their normal stable channels, and the installers resolve the versioned
+`cua-driver-rs-v*` releases directly.
diff --git a/.github/scripts/tests/test_release_attribution.py b/.github/scripts/tests/test_release_attribution.py
index d15a0b7dad..e7702cd086 100644
--- a/.github/scripts/tests/test_release_attribution.py
+++ b/.github/scripts/tests/test_release_attribution.py
@@ -175,6 +175,33 @@ def test_release_notes_dedupe_contributors_across_roles_and_login_case():
assert "@GoldenFish123321" not in body
+def test_cua_driver_release_footer_explains_github_prerelease_label():
+ footer = (REPO_ROOT / ".github/release-notes/cua-driver-rs.md").read_text()
+ manifest = {
+ "displayName": "Cua Driver",
+ "version": "0.17.0",
+ "repository": "trycua/cua",
+ "tag": "cua-driver-rs-v0.17.0",
+ "compareUrl": (
+ "https://github.com/trycua/cua/compare/"
+ "cua-driver-rs-v0.16.0...cua-driver-rs-v0.17.0"
+ ),
+ "visualRequested": False,
+ "changes": [],
+ "contributors": [],
+ "assets": [],
+ }
+
+ body = render_body(manifest, footer)
+ normalized = " ".join(body.split())
+
+ assert "Why GitHub says “Pre-release”" in body
+ assert "repository-wide “Latest” pointer" in normalized
+ assert "plain Cua Driver SemVer" in normalized
+ assert "npm and PyPI" in normalized
+ assert "`cua-driver-rs-v*` releases directly" in normalized
+
+
def test_cross_repository_references_are_not_resolved_in_cua():
body = (
"Closes https://github.com/other/project/issues/7 and closes #8. "
diff --git a/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md b/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md
index 9f7f873274..59b4860660 100644
--- a/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md
+++ b/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md
@@ -31,6 +31,20 @@ Use one explicit `session` value throughout. Never substitute a raw CDP
target id, tab ordinal, URL match, or remembered ref for a capability returned
by `get_browser_state`.
+### Copy page content to the system clipboard
+
+If the requested outcome is exact page content on the system clipboard—not a
+literal text-selection gesture—read the content from a fresh semantic browser
+snapshot, call `clipboard_write` with the exact observed value, and verify it
+with `clipboard_read`. This path is background-safe and does not require a
+clickable ref: passive headings and text nodes are evidence sources, not
+controls that must be clicked before their value can be copied.
+
+Fall back to visual text selection and the platform copy hotkey only when the
+user explicitly requires that gesture or clipboard tools are unavailable.
+That fallback is native input, not a typed page mutation, and may require the
+foreground escalation rules in `SKILL.md`.
+
### Browser recording feedback
On macOS and Windows, ref- and coordinate-targeted browser mutations drive the
diff --git a/libs/cua-driver/rust/Skills/cua-driver/SKILL.md b/libs/cua-driver/rust/Skills/cua-driver/SKILL.md
index f47fc04328..f8856ff54f 100644
--- a/libs/cua-driver/rust/Skills/cua-driver/SKILL.md
+++ b/libs/cua-driver/rust/Skills/cua-driver/SKILL.md
@@ -123,6 +123,23 @@ and keep each claim narrow:
partial result, stop that GUI path and surface the unresolved state instead
of retrying blindly.
+### Clipboard outcomes and GUI fallbacks
+
+When the requested postcondition is an exact value on the system clipboard,
+rather than the literal gesture of selecting and copying it, keep the operation
+semantic. Read the value from the narrowest typed source, call
+`clipboard_write`, then prove the real clipboard state with `clipboard_read`.
+For browser content, this means reading the page with `get_browser_state` and
+writing the exact observed text; a passive page-text ref does not need to be
+clicked first.
+
+Use visual selection followed by the platform copy hotkey only when the user
+explicitly asks for that gesture, the source cannot expose the value
+semantically, or direct clipboard tools are unavailable. Treat that as a GUI
+fallback: re-snapshot before acting, verify the selected range when the
+application exposes it, and escalate only the delivery step that cannot land
+in the background.
+
## The no-foreground principle (window phase)
In a strict `window` session, and during the initial window phase of an
diff --git a/libs/cua-driver/rust/crates/cua-driver/src/skills.rs b/libs/cua-driver/rust/crates/cua-driver/src/skills.rs
index 017090405e..8294af3813 100644
--- a/libs/cua-driver/rust/crates/cua-driver/src/skills.rs
+++ b/libs/cua-driver/rust/crates/cua-driver/src/skills.rs
@@ -862,6 +862,37 @@ mod tests {
}
}
+ #[test]
+ fn bundled_skill_keeps_semantic_clipboard_outcome_ladder() {
+ let crate_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
+ let skill = std::fs::read_to_string(crate_dir.join("../../Skills/cua-driver/SKILL.md"))
+ .expect("canonical skill must be readable");
+ let browser = std::fs::read_to_string(crate_dir.join("../../Skills/cua-driver/BROWSER.md"))
+ .expect("canonical browser skill must be readable");
+
+ for required in [
+ "exact value on the system clipboard",
+ "`clipboard_write`",
+ "`clipboard_read`",
+ "passive page-text ref",
+ ] {
+ assert!(
+ skill.contains(required),
+ "skill lost required clipboard outcome guidance: {required}"
+ );
+ }
+ for required in [
+ "exact page content on the system clipboard",
+ "passive headings and text nodes are evidence sources",
+ "foreground escalation rules in `SKILL.md`",
+ ] {
+ assert!(
+ browser.contains(required),
+ "browser skill lost required clipboard outcome guidance: {required}"
+ );
+ }
+ }
+
#[test]
fn extract_flat_tarball_v_0_2_20_plus() {
// Post-fix shape: one wrapper dir, files directly under it.