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-perception): publish releases from the Release Please tag (#4174)

Francesco Bonacci74e7fa92f997
diff --git a/.github/releases/README.md b/.github/releases/README.md
index 4d151244b1..0e0ddf6890 100644
--- a/.github/releases/README.md
+++ b/.github/releases/README.md
@@ -6,24 +6,37 @@ tag namespaces, build-time version sites, builder workflow, and change paths.
It intentionally does not describe signing, packaging, or registry publishing;
those remain owned by each component workflow.
-## cua-perception candidates
+## cua-perception releases
`cua-perception` has an independent version and changelog beside its Rust crate
in `libs/cua-driver/rust/crates/cua-perception`. Keeping the Release Please root
at that crate scopes its commits without unsupported path traversal. The
`.github/releases/cua-perception` directory remains the authority for schemas,
-trust, and candidate controls. Release Please may open version PRs for the
-component, while `skip-github-release` keeps the stream candidate-only and does
-not create GitHub releases. The workflow creates an idempotent lightweight
-`cua-perception-v<semver>` git tag on the exact main commit carrying each version
-so later candidate changelogs have an immutable range anchor.
+trust, and candidate controls. Release Please opens version PRs for the
+component with `skip-github-release`, so it creates no GitHub release itself.
+On each merged version, `release-please.yml` creates an idempotent lightweight
+`cua-perception-v<semver>` tag on the exact main commit, using the release app
+token so the tag push starts other workflows.
+
+That tag push runs `cd-cua-perception.yml`. It builds the release input on each
+target, passes it to the reviewed candidate workflow
+(`cd-cua-perception-candidate.yml`) for verification, packaging, and signing,
+installs every signed catalog with the published Cua Driver, and then publishes
+the verified catalogs, archives, SBOMs, provenance, and install evidence as the
+`cua-perception-v<semver>` GitHub release. The release is never marked Latest.
+Nobody dispatches anything to publish. The signing job still runs in the
+`cua-perception-candidate-signing` environment, so any protection rules on that
+environment apply to each release.
The candidate workflow accepts prebuilt payloads. It does not download model
weights or compile product code. Every supplied worker, runtime, model, notice,
and source file must be declared with its exact size, SHA-256, license source,
target, and protocol version as applicable. Models and bundled source also need
complete ledgers. The workflow emits a deterministic archive, SPDX SBOM, signed
-catalog, redacted provenance, and checksums as retained CI artifacts only.
+catalog, redacted provenance, and checksums as retained CI artifacts; only the
+release workflow publishes them. `cd-cua-perception-candidate-manual.yml`
+remains for staging candidates from a reviewed pull request head and never
+publishes.
Candidate catalogs use the same Ed25519 envelope consumed by Cua Driver's
extension manager: `{ "payload": <compact catalog payload>,
diff --git a/.github/releases/components.json b/.github/releases/components.json
index 1fd20b1d98..0ec8fbc24a 100644
--- a/.github/releases/components.json
+++ b/.github/releases/components.json
@@ -16,12 +16,13 @@
"nightlyTagPrefix": "nightly-cua-perception-v",
"versionAuthorityFile": "libs/cua-driver/rust/crates/cua-perception/VERSION",
"changelog": "libs/cua-driver/rust/crates/cua-perception/CHANGELOG.md",
- "builderWorkflow": ".github/workflows/cd-cua-perception-candidate.yml",
+ "builderWorkflow": ".github/workflows/cd-cua-perception.yml",
"changeDetectionPaths": [
"libs/cua-driver/rust/crates/cua-perception",
".github/releases/cua-perception",
".github/scripts/perception_release.py",
- ".github/workflows/cd-cua-perception-candidate.yml"
+ ".github/workflows/cd-cua-perception-candidate.yml",
+ ".github/workflows/cd-cua-perception.yml"
],
"buildVersionSites": [
{
diff --git a/.github/scripts/perception_release_install_check.py b/.github/scripts/perception_release_install_check.py
new file mode 100644
index 0000000000..4da47d9363
--- /dev/null
+++ b/.github/scripts/perception_release_install_check.py
@@ -0,0 +1,290 @@
+#!/usr/bin/env python3
+"""Exercise a Cua Perception release artifact through an installed Cua Driver.
+
+The release gate runs this script on each target runner with the Driver that
+the canonical installer resolves. It proves the user path end to end:
+
+1. the extension is absent and ``perception parse`` refuses with ``not_installed``;
+2. ``extension inspect`` verifies the artifact without mutating state;
+3. ``extension install`` activates it and ``extension status --self-test`` is healthy;
+4. ``perception parse`` runs the installed worker on a real PNG; and
+5. ``extension remove`` restores the absent state.
+
+A signed catalog must verify as production publisher evidence. The
+developer-only ``--unsigned-archive`` mode exists for pull request dry runs of
+the unsigned candidate and can never report publisher-verified trust.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any, Sequence
+
+EXTENSION_ID = "cua-perception"
+PRODUCTION_TRUST = "publisher-verified"
+PRODUCTION_EVIDENCE = "production-publisher-verified"
+PRODUCTION_PUBLISHER = "cua"
+DEVELOPER_TRUST = "developer-unsigned-local"
+DEVELOPER_EVIDENCE = "developer-local-not-publisher-evidence"
+VISUAL_REGIONS_SCHEMA = "cua.visual_regions_v1"
+
+
+class InstallCheckError(RuntimeError):
+ """Raised when the installed Driver does not honor the release contract."""
+
+
+def require(condition: bool, message: str) -> None:
+ if not condition:
+ raise InstallCheckError(message)
+
+
+def file_sha256(path: Path) -> str:
+ digest = hashlib.sha256()
+ with path.open("rb") as handle:
+ for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+ digest.update(chunk)
+ return digest.hexdigest()
+
+
+class Driver:
+ def __init__(self, executable: Path, home: Path) -> None:
+ # Resolve so a relative path never falls back to a Driver on PATH.
+ self.executable = executable.resolve(strict=True)
+ self.environment = dict(os.environ)
+ self.environment.update({
+ "CUA_DRIVER_RS_HOME": str(home),
+ "CUA_DRIVER_RS_TELEMETRY_ENABLED": "false",
+ "CUA_TELEMETRY_ENABLED": "false",
+ })
+
+ def run(self, arguments: Sequence[str], *, expect_success: bool = True) -> subprocess.CompletedProcess[str]:
+ completed = subprocess.run(
+ [str(self.executable), *arguments],
+ capture_output=True,
+ text=True,
+ env=self.environment,
+ timeout=900,
+ check=False,
+ )
+ if expect_success and completed.returncode != 0:
+ raise InstallCheckError(
+ f"cua-driver {' '.join(arguments)} exited {completed.returncode}: "
+ f"{completed.stderr.strip()[-2000:]}"
+ )
+ return completed
+
+ def json(self, arguments: Sequence[str], *, expect_success: bool = True) -> dict[str, Any]:
+ completed = self.run(arguments, expect_success=expect_success)
+ try:
+ value = json.loads(completed.stdout)
+ except json.JSONDecodeError as error:
+ raise InstallCheckError(
+ f"cua-driver {' '.join(arguments)} did not print one JSON document: {error}"
+ ) from error
+ require(isinstance(value, dict), f"cua-driver {' '.join(arguments)} JSON is not an object")
+ return value
+
+
+def source_arguments(catalog: Path | None, archive: Path | None) -> list[str]:
+ if catalog is not None:
+ return ["--catalog", str(catalog)]
+ assert archive is not None
+ return ["--archive", str(archive), "--allow-unsigned-local"]
+
+
+def check_absent(driver: Driver, image: Path, capture: Path) -> None:
+ status = driver.json(["extension", "status", EXTENSION_ID, "--json"])
+ require(status.get("id") == EXTENSION_ID, "status reported a different extension")
+ require(status.get("installed") is False, "extension is already installed in the isolated home")
+ refusal = driver.json(
+ ["perception", "parse", "--image", str(image), "--capture", str(capture), "--json"],
+ expect_success=False,
+ )
+ require(refusal.get("ok") is False, "parse without the extension did not fail closed")
+ require(
+ refusal.get("error", {}).get("code") == "not_installed",
+ f"parse without the extension returned {refusal.get('error')!r}, not not_installed",
+ )
+
+
+def check_inspect(
+ preview: dict[str, Any], *, signed: bool, version: str, target: str, source_sha: str,
+ payload: dict[str, Any] | None,
+) -> None:
+ require(preview.get("id") == EXTENSION_ID, "inspect reported a different extension")
+ require(preview.get("version") == version, f"inspect version {preview.get('version')!r} != {version}")
+ require(preview.get("target") == target, f"inspect target {preview.get('target')!r} != {target}")
+ require(preview.get("installed") is False, "inspect reported an installed extension")
+ require(preview.get("mutation_performed") is False, "inspect mutated extension state")
+ require(preview.get("ran") is False, "inspect ran the extension")
+ require(
+ preview.get("corresponding_source_revision") == source_sha,
+ "inspect corresponding-source revision differs from the release commit",
+ )
+ require(bool(preview.get("models")), "inspect listed no models")
+ require(bool(preview.get("license_notices")), "inspect listed no license notices")
+ require(bool(preview.get("corresponding_source")), "inspect listed no corresponding source")
+ if signed:
+ assert payload is not None
+ require(preview.get("trust") == PRODUCTION_TRUST, f"inspect trust is {preview.get('trust')!r}")
+ require(
+ preview.get("evidence_class") == PRODUCTION_EVIDENCE,
+ f"inspect evidence class is {preview.get('evidence_class')!r}",
+ )
+ require(preview.get("publisher_signature_verified") is True, "publisher signature not verified")
+ require(preview.get("publisher_id") == PRODUCTION_PUBLISHER, "inspect publisher is not cua")
+ require(preview.get("publisher_key_id") == payload["key_id"], "inspect key differs from catalog")
+ require(
+ preview.get("catalog_version") == payload["catalog_version"],
+ "inspect catalog version differs from the signed payload",
+ )
+ require(
+ preview.get("archive_sha256") == payload["archive_sha256"],
+ "inspect archive digest differs from the signed payload",
+ )
+ else:
+ require(preview.get("trust") == DEVELOPER_TRUST, f"unsigned inspect trust is {preview.get('trust')!r}")
+ require(
+ preview.get("evidence_class") == DEVELOPER_EVIDENCE,
+ "unsigned inspect claimed publisher evidence",
+ )
+
+
+def check_status(status: dict[str, Any], *, signed: bool, version: str) -> None:
+ require(status.get("id") == EXTENSION_ID, "status reported a different extension")
+ require(status.get("installed") is True, "extension is not installed after install")
+ require(status.get("healthy") is True, f"installed extension is unhealthy: {status.get('detail')!r}")
+ require(status.get("active_version") == version, f"active version {status.get('active_version')!r} != {version}")
+ expected_trust = PRODUCTION_TRUST if signed else DEVELOPER_TRUST
+ expected_evidence = PRODUCTION_EVIDENCE if signed else DEVELOPER_EVIDENCE
+ require(status.get("trust") == expected_trust, f"installed trust is {status.get('trust')!r}")
+ require(status.get("evidence_class") == expected_evidence, "installed evidence class differs")
+
+
+def check_parse(result: dict[str, Any], *, version: str, image_sha256: str) -> None:
+ require(result.get("schema") == VISUAL_REGIONS_SCHEMA, f"parse schema is {result.get('schema')!r}")
+ parser = result.get("parser", {})
+ require(parser.get("extension_id") == EXTENSION_ID, "parse came from a different extension")
+ require(parser.get("extension_version") == version, "parse came from a different extension version")
+ local_input = result.get("local_input", {})
+ require(local_input.get("action_eligible") is False, "local image parse claimed action eligibility")
+ require(local_input.get("action_authority") == "none", "local image parse claimed action authority")
+ require(local_input.get("sha256") == image_sha256, "parse hashed a different image")
+ regions = result.get("regions")
+ require(isinstance(regions, list) and regions, "parse returned no regions for the fixture")
+ for region in regions:
+ bounds = region.get("bounds", {})
+ require(
+ all(isinstance(bounds.get(key), int) and bounds[key] >= 0 for key in ("x", "y", "width", "height")),
+ f"region {region.get('id')!r} has invalid bounds",
+ )
+ confidence = region.get("confidence")
+ require(
+ isinstance(confidence, (int, float)) and 0 <= confidence <= 1,
+ f"region {region.get('id')!r} has invalid confidence",
+ )
+
+
+def run_check(arguments: argparse.Namespace) -> dict[str, Any]:
+ signed = arguments.catalog is not None
+ payload = None
+ if signed:
+ payload = json.loads(arguments.catalog.read_text(encoding="utf-8"))["payload"]
+ require(payload["version"] == arguments.version, "catalog version differs from the release")
+ require(payload["target"] == arguments.target, "catalog target differs from the runner target")
+ require(
+ payload["corresponding_source_revision"] == arguments.source_sha,
+ "catalog source revision differs from the release commit",
+ )
+ archive = arguments.catalog.parent / payload["archive"]
+ require(archive.is_file(), f"catalog archive is missing beside the catalog: {payload['archive']}")
+ require(file_sha256(archive) == payload["archive_sha256"], "catalog archive digest differs")
+ require(not arguments.home.exists(), f"isolated Driver home already exists: {arguments.home}")
+ arguments.home.mkdir(parents=True)
+ capture = arguments.home.parent / f"{arguments.home.name}-capture.json"
+ capture.write_text(
+ json.dumps({"source": {"kind": "primary_desktop", "display_id": "primary"}}) + "\n",
+ encoding="utf-8",
+ )
+ driver = Driver(arguments.driver, arguments.home)
+ source = source_arguments(arguments.catalog, arguments.unsigned_archive)
+ image_sha256 = file_sha256(arguments.image)
+
+ version_output = driver.run(["--version"]).stdout.strip()
+ check_absent(driver, arguments.image, capture)
+ preview = driver.json(["extension", "inspect", EXTENSION_ID, *source, "--json"])
+ check_inspect(
+ preview, signed=signed, version=arguments.version, target=arguments.target,
+ source_sha=arguments.source_sha, payload=payload,
+ )
+ driver.run(["extension", "install", EXTENSION_ID, *source])
+ status = driver.json(["extension", "status", EXTENSION_ID, "--self-test", "--json"])
+ check_status(status, signed=signed, version=arguments.version)
+ parse = driver.json([
+ "perception", "parse", "--image", str(arguments.image), "--capture", str(capture), "--json",
+ ])
+ check_parse(parse, version=arguments.version, image_sha256=image_sha256)
+ driver.run(["extension", "remove", EXTENSION_ID])
+ removed = driver.json(["extension", "status", EXTENSION_ID, "--json"])
+ require(removed.get("installed") is False, "extension is still installed after remove")
+
+ return {
+ "driver_version": version_output,
+ "extension_version": arguments.version,
+ "target": arguments.target,
+ "source_sha": arguments.source_sha,
+ "trust": status["trust"],
+ "evidence_class": status["evidence_class"],
+ "catalog_version": preview.get("catalog_version"),
+ "archive_sha256": preview.get("archive_sha256"),
+ "parse_region_count": len(parse["regions"]),
+ "parse_timing": parse.get("timing"),
+ "checks": [
+ "absent-not-installed",
+ "inspect-without-mutation",
+ "install",
+ "status-self-test-healthy",
+ "real-parse",
+ "remove",
+ ],
+ }
+
+
+def parse_arguments(argv: Sequence[str]) -> argparse.Namespace:
+ parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+ parser.add_argument("--driver", required=True, type=Path)
+ source = parser.add_mutually_exclusive_group(required=True)
+ source.add_argument("--catalog", type=Path, help="signed catalog beside its archive")
+ source.add_argument(
+ "--unsigned-archive", type=Path,
+ help="developer-only unsigned archive for pull request dry runs",
+ )
+ parser.add_argument("--version", required=True)
+ parser.add_argument("--target", required=True)
+ parser.add_argument("--source-sha", required=True)
+ parser.add_argument("--image", required=True, type=Path)
+ parser.add_argument("--home", required=True, type=Path)
+ parser.add_argument("--evidence", required=True, type=Path)
+ return parser.parse_args(argv)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+ arguments = parse_arguments(sys.argv[1:] if argv is None else argv)
+ try:
+ evidence = run_check(arguments)
+ except InstallCheckError as error:
+ print(f"::error title=Cua Perception install check::{error}", file=sys.stderr)
+ return 1
+ arguments.evidence.write_text(json.dumps(evidence, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+ print(json.dumps(evidence, indent=2, sort_keys=True))
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/.github/scripts/tests/test_cua_perception_release_workflow.py b/.github/scripts/tests/test_cua_perception_release_workflow.py
new file mode 100644
index 0000000000..ad1469bdb0
--- /dev/null
+++ b/.github/scripts/tests/test_cua_perception_release_workflow.py
@@ -0,0 +1,191 @@
+"""Contract tests for the tag-triggered Cua Perception release workflow."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+ROOT = Path(__file__).resolve().parents[3]
+WORKFLOW_PATH = ROOT / ".github/workflows/cd-cua-perception.yml"
+TARGETS = {"x86_64-unknown-linux-gnu", "aarch64-apple-darwin", "x86_64-pc-windows-msvc"}
+
+
+def workflow() -> dict[str, Any]:
+ return yaml.safe_load(WORKFLOW_PATH.read_text(encoding="utf-8"))
+
+
+def triggers() -> dict[str, Any]:
+ parsed = workflow()
+ # PyYAML reads the bare `on` key as boolean True.
+ return parsed.get("on", parsed.get(True))
+
+
+def run_text(job: dict[str, Any]) -> str:
+ return "\n".join(step.get("run", "") for step in job.get("steps", []))
+
+
+def needs(job: dict[str, Any]) -> set[str]:
+ value = job.get("needs", [])
+ return {value} if isinstance(value, str) else set(value)
+
+
+def test_publication_starts_only_from_the_release_please_tag() -> None:
+ on = triggers()
+ assert set(on) == {"push", "pull_request"}
+ assert on["push"] == {"tags": ["cua-perception-v*"]}
+ # No manual dispatch or reusable entry point can reach publication.
+ assert "workflow_dispatch" not in on and "workflow_call" not in on
+ assert ".github/workflows/cd-cua-perception.yml" in on["pull_request"]["paths"]
+
+
+def test_release_please_keeps_creating_the_lightweight_anchor_tag() -> None:
+ config = json.loads((ROOT / "release-please-config.json").read_text())
+ package = config["packages"]["libs/cua-driver/rust/crates/cua-perception"]
+ assert package["skip-github-release"] is True
+ release_please = (ROOT / ".github/workflows/release-please.yml").read_text()
+ assert 'TAG="cua-perception-v$VERSION"' in release_please
+ # The anchor uses the release app token so the tag push triggers this workflow.
+ assert "GH_TOKEN: ${{ steps.app-token.outputs.token }}" in release_please
+
+
+def test_permissions_are_read_only_except_the_release_job() -> None:
+ parsed = workflow()
+ assert parsed["permissions"] == {"actions": "read", "contents": "read"}
+ for name, job in parsed["jobs"].items():
+ permissions = job.get("permissions", {})
+ if name == "release":
+ assert permissions == {"actions": "read", "contents": "write"}
+ elif name == "reviewed-model":
+ # Draft release assets are visible only to tokens with push access.
+ assert permissions == {"contents": "write"}
+ script = run_text(job)
+ assert "python" not in script and "cargo" not in script and "bash " not in script
+ assert all(
+ step.get("with", {}).get("persist-credentials") is False
+ for step in job["steps"]
+ if "actions/checkout" in step.get("uses", "")
+ )
+ else:
+ assert "write" not in json.dumps(permissions), name
+
+
+def test_resolve_binds_tag_version_commit_and_main_history() -> None:
+ resolve = workflow()["jobs"]["resolve"]
+ script = run_text(resolve)
+ assert "github.repository == 'trycua/cua'" in resolve["if"]
+ assert "head.repo.full_name == github.repository" in resolve["if"]
+ assert '[[ "$TAG" == "cua-perception-v$VERSION" ]]' in script
+ assert '[[ "$TAG_TYPE" == commit && "$TAG_SHA" == "$SOURCE_SHA" ]]' in script
+ assert 'git merge-base --is-ancestor "$SOURCE_SHA" origin/main' in script
+ assert "validate_release_versions.py --product perception" in script
+ assert 'SOURCE_SHA="$GITHUB_SHA"' in script
+ assert "PUBLISH=true" in script and "PUBLISH=false" in script
+ assert "KEY_VALID_UNTIL" in script and "+%y%m%d%H%M" in script
+
+
+def test_reviewed_model_is_verified_against_the_artifact_lock() -> None:
+ script = run_text(workflow()["jobs"]["reviewed-model"])
+ assert 'select(.role == "icon-detect")' in script
+ assert "artifacts.lock.json" in script
+ assert '[[ "$ACTUAL_SIZE" == "$SIZE" && "$ACTUAL_SHA256" == "$SHA256" ]]' in script
+
+
+def test_inputs_cover_every_target_and_publish_only_on_tag_runs() -> None:
+ job = workflow()["jobs"]["input"]
+ assert {entry["target"] for entry in job["strategy"]["matrix"]["include"]} == TARGETS
+ assert needs(job) == {"resolve", "reviewed-model"}
+ steps = {step["name"]: step for step in job["steps"] if "name" in step}
+ upload = steps["Preserve exact candidate packaging input"]
+ assert upload["if"] == "needs.resolve.outputs.publish == 'true'"
+ dry_run = steps["Developer-only install check of the unsigned package"]
+ assert dry_run["if"] == "needs.resolve.outputs.publish != 'true'"
+ assert "--unsigned-archive" in dry_run["run"] and "--catalog" not in dry_run["run"]
+ assert "bind-source" in run_text(job) and "perception_release.py validate" in run_text(job)
+ assert "--require-hashes" in run_text(job)
+
+
+def test_candidate_reuses_the_reviewed_signing_workflow_for_the_tag() -> None:
+ job = workflow()["jobs"]["candidate"]
+ assert job["uses"] == "./.github/workflows/cd-cua-perception-candidate.yml"
+ assert job["if"] == "needs.resolve.outputs.publish == 'true'"
+ assert needs(job) == {"resolve", "input"}
+ inputs = job["with"]
+ assert inputs["payload_run_id"] == "${{ fromJSON(github.run_id) }}"
+ assert inputs["source_ref"] == "${{ needs.resolve.outputs.source_sha }}"
+ assert inputs["reviewed_ref"] == "${{ needs.resolve.outputs.reviewed_ref }}"
+ assert set(job["secrets"]) == {"PERCEPTION_ED25519_PRIVATE_KEY_BASE64"}
+ assert {entry["target_triple"] for entry in job["strategy"]["matrix"]["include"]} == TARGETS
+ # Only the candidate job receives the signing secret.
+ for name, other in workflow()["jobs"].items():
+ if name != "candidate":
+ assert "PERCEPTION_ED25519_PRIVATE_KEY_BASE64" not in json.dumps(other), name
+ candidate = yaml.safe_load(
+ (ROOT / ".github/workflows/cd-cua-perception-candidate.yml").read_text()
+ )
+ assert candidate["jobs"]["sign"]["environment"] == "cua-perception-candidate-signing"
+
+
+def test_verify_installs_each_signed_catalog_with_the_published_driver() -> None:
+ job = workflow()["jobs"]["verify"]
+ assert needs(job) == {"resolve", "candidate"}
+ assert job["if"] == "needs.resolve.outputs.publish == 'true'"
+ assert {entry["target"] for entry in job["strategy"]["matrix"]["include"]} == TARGETS
+ script = run_text(job)
+ assert "libs/cua-driver/scripts/install.sh" in script
+ assert "libs/cua-driver/scripts/install.ps1" in script
+ assert "perception_release_install_check.py" in script
+ assert "--catalog signed/signed-catalog.json" in script
+ assert "--unsigned-archive" not in script
+ assert "crypto.verify(null, payloadBytes, key" in script
+ assert "trust-root.json" in script
+ assert "verify-checksums signed/signed-candidate-checksums.txt" in script
+
+
+def test_release_requires_every_gate_and_the_verified_tag_commit() -> None:
+ job = workflow()["jobs"]["release"]
+ assert needs(job) == {"resolve", "input", "candidate", "verify"}
+ condition = job["if"]
+ assert "github.event_name == 'push'" in condition
+ assert "startsWith(github.ref, 'refs/tags/cua-perception-v')" in condition
+ assert "always()" not in condition and "failure()" not in condition
+ script = run_text(job)
+ assert '"$HEAD_SHA" != "$GITHUB_SHA"' in script
+ assert '"$TAG_SHA" != "$GITHUB_SHA"' in script
+ assert '"$SOURCE_SHA" != "$GITHUB_SHA"' in script
+ assert "--latest=false" in script
+ assert "--verify-tag" in script and "--draft" in script
+ assert "--clobber" in script
+ # Published releases are immutable: a re-run only accepts identical assets.
+ assert "diff -u expected.txt published.txt" in script
+ # The archive keeps its signed name so the Driver resolves it beside the catalog.
+ assert 'cp "$DIR/$ARCHIVE" "release-upload/$ARCHIVE"' in script
+ assert '"release-upload/$BASE.catalog.json"' in script
+ assert '.trust == "publisher-verified"' in script
+ downloads = [
+ step["with"]["pattern"]
+ for step in job["steps"]
+ if "download-artifact" in step.get("uses", "")
+ ]
+ assert downloads == [
+ "STAGING-cua-perception-candidate-*-${{ needs.resolve.outputs.source_sha }}",
+ "cua-perception-install-evidence-*",
+ ]
+
+
+def test_actions_are_pinned_to_commits() -> None:
+ for job in workflow()["jobs"].values():
+ for step in job.get("steps", []):
+ uses = step.get("uses")
+ if uses:
+ reference = uses.split("@", 1)[1]
+ assert len(reference) == 40 and all(c in "0123456789abcdef" for c in reference), uses
+
+
+def test_component_registry_points_at_the_release_workflow() -> None:
+ registry = json.loads((ROOT / ".github/releases/components.json").read_text())
+ component = registry["components"]["cua-perception"]
+ assert component["builderWorkflow"] == ".github/workflows/cd-cua-perception.yml"
+ assert ".github/workflows/cd-cua-perception.yml" in component["changeDetectionPaths"]
diff --git a/.github/scripts/tests/test_perception_release_install_check.py b/.github/scripts/tests/test_perception_release_install_check.py
new file mode 100644
index 0000000000..86c09241b0
--- /dev/null
+++ b/.github/scripts/tests/test_perception_release_install_check.py
@@ -0,0 +1,238 @@
+"""Tests for the Cua Perception release install check."""
+
+from __future__ import annotations
+
+import hashlib
+import importlib.util
+import json
+import os
+import stat
+import sys
+import textwrap
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[3]
+SPEC = importlib.util.spec_from_file_location(
+ "perception_release_install_check",
+ ROOT / ".github/scripts/perception_release_install_check.py",
+)
+check = importlib.util.module_from_spec(SPEC)
+assert SPEC.loader is not None
+SPEC.loader.exec_module(check)
+
+SOURCE_SHA = "a" * 40
+TARGET = "x86_64-unknown-linux-gnu"
+VERSION = "0.2.1"
+
+FAKE_DRIVER = textwrap.dedent(
+ """\
+ #!{python}
+ import json, os, pathlib, sys
+
+ home = pathlib.Path(os.environ["CUA_DRIVER_RS_HOME"])
+ mode = os.environ.get("FAKE_MODE", "")
+ state = home / "installed.json"
+ args = sys.argv[1:]
+ log = home.parent / (home.name + "-calls.jsonl")
+ with log.open("a") as handle:
+ handle.write(json.dumps(args) + "\\n")
+
+ def emit(value, code=0):
+ print(json.dumps(value))
+ raise SystemExit(code)
+
+ def source_trust():
+ if "--catalog" in args:
+ if mode == "signed-reports-developer":
+ return "developer-unsigned-local", "developer-local-not-publisher-evidence"
+ return "publisher-verified", "production-publisher-verified"
+ assert "--allow-unsigned-local" in args
+ return "developer-unsigned-local", "developer-local-not-publisher-evidence"
+
+ if args == ["--version"]:
+ print("cua-driver 0.29.1")
+ raise SystemExit(0)
+ if args[:2] == ["extension", "status"]:
+ if state.exists():
+ record = json.loads(state.read_text())
+ emit({{"id": "cua-perception", "installed": True, "healthy": mode != "unhealthy",
+ "active_version": record["version"], "trust": record["trust"],
+ "evidence_class": record["evidence"], "detail": "ok"}})
+ emit({{"id": "cua-perception", "installed": False, "healthy": True, "detail": "not installed"}})
+ if args[:2] == ["perception", "parse"]:
+ if not state.exists():
+ if mode == "parse-without-extension-succeeds":
+ emit({{"schema": "cua.visual_regions_v1"}})
+ emit({{"ok": False, "error": {{"code": "not_installed", "message": "absent"}}}}, 1)
+ image = pathlib.Path(args[args.index("--image") + 1])
+ import hashlib
+ digest = hashlib.sha256(image.read_bytes()).hexdigest()
+ regions = [] if mode == "no-regions" else [
+ {{"id": "text-1", "kind": "text", "confidence": 0.65,
+ "bounds": {{"x": 7, "y": 17, "width": 5, "height": 6}}}}
+ ]
+ emit({{"schema": "cua.visual_regions_v1",
+ "parser": {{"extension_id": "cua-perception",
+ "extension_version": json.loads(state.read_text())["version"]}},
+ "local_input": {{"action_eligible": False, "action_authority": "none", "sha256": digest}},
+ "regions": regions, "timing": {{"duration_ms": 12}}}})
+ if args[:2] == ["extension", "inspect"]:
+ trust, evidence = source_trust()
+ payload = {{}}
+ if "--catalog" in args:
+ payload = json.loads(pathlib.Path(args[args.index("--catalog") + 1]).read_text())["payload"]
+ emit({{"id": "cua-perception", "version": os.environ["FAKE_VERSION"],
+ "target": os.environ["FAKE_TARGET"], "installed": False,
+ "mutation_performed": mode == "inspect-mutates", "ran": False,
+ "corresponding_source_revision": os.environ["FAKE_SOURCE_SHA"],
+ "models": [{{"path": "models/a.onnx"}}], "license_notices": [{{"component": "a"}}],
+ "corresponding_source": {{"uri": "source/cua-perception-source.tar.gz"}},
+ "trust": trust, "evidence_class": evidence,
+ "publisher_signature_verified": "--catalog" in args,
+ "publisher_id": "cua" if "--catalog" in args else None,
+ "publisher_key_id": payload.get("key_id"),
+ "catalog_version": payload.get("catalog_version"),
+ "archive_sha256": payload.get("archive_sha256")}})
+ if args[:2] == ["extension", "install"]:
+ trust, evidence = source_trust()
+ state.write_text(json.dumps({{"version": os.environ["FAKE_VERSION"], "trust": trust,
+ "evidence": evidence}}))
+ print("Installed")
+ raise SystemExit(0)
+ if args[:2] == ["extension", "remove"]:
+ if mode != "remove-noop":
+ state.unlink()
+ print("Removed")
+ raise SystemExit(0)
+ print("unexpected arguments: " + " ".join(args), file=sys.stderr)
+ raise SystemExit(2)
+ """
+)
+
+
+def layout(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> dict[str, Path]:
+ driver = tmp_path / "bin" / "cua-driver"
+ driver.parent.mkdir()
+ driver.write_text(FAKE_DRIVER.format(python=sys.executable), encoding="utf-8")
+ driver.chmod(driver.stat().st_mode | stat.S_IEXEC)
+ release = tmp_path / "release"
+ release.mkdir()
+ archive = release / f"cua-perception-{VERSION}-{TARGET}.tar.gz"
+ archive.write_bytes(b"archive bytes")
+ catalog = release / "signed-catalog.json"
+ catalog.write_text(json.dumps({
+ "payload": {
+ "version": VERSION,
+ "target": TARGET,
+ "corresponding_source_revision": SOURCE_SHA,
+ "archive": archive.name,
+ "archive_sha256": hashlib.sha256(archive.read_bytes()).hexdigest(),
+ "key_id": "cua-extension-ed25519-2026-09",
+ "catalog_version": 2609260612,
+ },
+ "signature_algorithm": "ed25519",
+ "signature": "AA==",
+ }), encoding="utf-8")
+ image = tmp_path / "fixture.png"
+ image.write_bytes(b"\x89PNG\r\n\x1a\nfixture")
+ monkeypatch.setenv("FAKE_VERSION", VERSION)
+ monkeypatch.setenv("FAKE_TARGET", TARGET)
+ monkeypatch.setenv("FAKE_SOURCE_SHA", SOURCE_SHA)
+ monkeypatch.delenv("FAKE_MODE", raising=False)
+ return {"driver": driver, "catalog": catalog, "archive": archive, "image": image, "root": tmp_path}
+
+
+def arguments(layout: dict[str, Path], *, signed: bool = True, version: str = VERSION) -> list[str]:
+ source = ["--catalog", str(layout["catalog"])] if signed else [
+ "--unsigned-archive", str(layout["archive"])
+ ]
+ return [
+ "--driver", str(layout["driver"]),
+ *source,
+ "--version", version,
+ "--target", TARGET,
+ "--source-sha", SOURCE_SHA,
+ "--image", str(layout["image"]),
+ "--home", str(layout["root"] / "home"),
+ "--evidence", str(layout["root"] / "evidence.json"),
+ ]
+
+
+def test_signed_catalog_passes_the_full_lifecycle(layout: dict[str, Path]) -> None:
+ assert check.main(arguments(layout)) == 0
+ evidence = json.loads((layout["root"] / "evidence.json").read_text())
+ assert evidence["trust"] == "publisher-verified"
+ assert evidence["evidence_class"] == "production-publisher-verified"
+ assert evidence["catalog_version"] == 2609260612
+ assert evidence["driver_version"] == "cua-driver 0.29.1"
+ assert evidence["checks"] == [
+ "absent-not-installed",
+ "inspect-without-mutation",
+ "install",
+ "status-self-test-healthy",
+ "real-parse",
+ "remove",
+ ]
+ calls = [
+ json.loads(line)
+ for line in (layout["root"] / "home-calls.jsonl").read_text().splitlines()
+ ]
+ commands = [call[:2] for call in calls]
+ assert commands.index(["extension", "inspect"]) < commands.index(["extension", "install"])
+ assert ["extension", "status", "cua-perception", "--self-test", "--json"] in calls
+ assert all("--allow-unsigned-local" not in call for call in calls)
+
+
+def test_unsigned_dry_run_reports_developer_trust_only(layout: dict[str, Path]) -> None:
+ assert check.main(arguments(layout, signed=False)) == 0
+ evidence = json.loads((layout["root"] / "evidence.json").read_text())
+ assert evidence["trust"] == "developer-unsigned-local"
+ assert evidence["evidence_class"] == "developer-local-not-publisher-evidence"
+
+
+ "mode",
+ [
+ "signed-reports-developer",
+ "parse-without-extension-succeeds",
+ "inspect-mutates",
+ "unhealthy",
+ "no-regions",
+ "remove-noop",
+ ],
+)
+def test_contract_violations_fail_closed(
+ layout: dict[str, Path], monkeypatch: pytest.MonkeyPatch, mode: str,
+) -> None:
+ monkeypatch.setenv("FAKE_MODE", mode)
+ assert check.main(arguments(layout)) == 1
+ assert not (layout["root"] / "evidence.json").exists()
+
+
+def test_catalog_must_match_the_release_identity(layout: dict[str, Path]) -> None:
+ assert check.main(arguments(layout, version="0.2.2")) == 1
+
+
+def test_catalog_archive_digest_is_checked_before_the_driver_runs(layout: dict[str, Path]) -> None:
+ layout["archive"].write_bytes(b"tampered")
+ assert check.main(arguments(layout)) == 1
+ assert not (layout["root"] / "home-calls.jsonl").exists()
+
+
+def test_refuses_a_reused_driver_home(layout: dict[str, Path]) -> None:
+ (layout["root"] / "home").mkdir()
+ assert check.main(arguments(layout)) == 1
+
+
+def test_relative_driver_path_never_resolves_through_path(
+ layout: dict[str, Path], monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.chdir(layout["driver"].parent)
+ monkeypatch.setenv("PATH", "/nonexistent")
+ args = arguments(layout)
+ args[args.index("--driver") + 1] = "./cua-driver"
+ assert check.main(args) == 0
+ assert os.path.isabs(str(check.Driver(Path("./cua-driver"), layout["root"] / "x").executable))
diff --git a/.github/workflows/cd-cua-perception.yml b/.github/workflows/cd-cua-perception.yml
new file mode 100644
index 0000000000..b05f6ce4c3
--- /dev/null
+++ b/.github/workflows/cd-cua-perception.yml
@@ -0,0 +1,684 @@
+name: "CD: Cua Perception release"
+
+# Cua Perception releases follow Release Please with no manual publish step.
+#
+# Merging the Release Please pull request bumps
+# libs/cua-driver/rust/crates/cua-perception/VERSION. The main push then runs
+# release-please.yml, which anchors the merged commit with the lightweight
+# `cua-perception-vX.Y.Z` tag (Perception keeps `skip-github-release`, so
+# Release Please itself creates no GitHub release). That tag push runs this
+# workflow:
+#
+# 1. resolve: prove the tag is a lightweight tag on main at github.sha and
+# matches VERSION.
+# 2. reviewed-model: fetch the reviewed OmniParser ONNX conversion and verify
+# it against artifacts.lock.json.
+# 3. input: build the native worker and assemble, bind, and validate the
+# release input on macOS arm64, Linux x64, and Windows x64.
+# 4. candidate: the existing reviewed candidate workflow re-verifies the input
+# at the exact tag, executes the worker release gates, packages, and signs
+# each catalog in the cua-perception-candidate-signing environment.
+# 5. verify: on each target, install the published Cua Driver with its
+# canonical installer and prove inspect, install, self-test, a real parse,
+# and remove against the signed catalog.
+# 6. release: publish the verified catalogs, archives, SBOMs, and provenance
+# as the `cua-perception-vX.Y.Z` GitHub release, never marked Latest.
+#
+# Pull requests that change this pipeline run steps 1-3 plus an unsigned
+# package and developer-only install check. They never sign or publish.
+
+on:
+ push:
+ tags:
+ - "cua-perception-v*"
+ pull_request:
+ paths:
+ - ".github/workflows/cd-cua-perception.yml"
+ - ".github/scripts/perception_release.py"
+ - ".github/scripts/perception_release_install_check.py"
+ - ".github/releases/cua-perception/**"
+ - "libs/cua-driver/rust/crates/cua-perception/scripts/**"
+
+permissions:
+ actions: read
+ contents: read
+
+concurrency:
+ group: cd-cua-perception-${{ github.event_name == 'pull_request' && github.ref || github.sha }}
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+env:
+ # Reviewed OmniParser icon-detect ONNX conversion. The bytes are verified
+ # against the icon-detect entry in artifacts.lock.json before use.
+ REVIEWED_MODEL_ASSET_ID: "571471639"
+
+jobs:
+ resolve:
+ name: Resolve the release identity
+ if: >-
+ github.repository == 'trycua/cua' &&
+ (github.event_name == 'push' ||
+ github.event.pull_request.head.repo.full_name == github.repository)
+ runs-on: ubuntu-latest
+ timeout-minutes: 10
+ outputs:
+ version: ${{ steps.resolve.outputs.version }}
+ tag: ${{ steps.resolve.outputs.tag }}
+ source_sha: ${{ steps.resolve.outputs.source_sha }}
+ reviewed_ref: ${{ steps.resolve.outputs.reviewed_ref }}
+ catalog_version: ${{ steps.resolve.outputs.catalog_version }}
+ expires_unix: ${{ steps.resolve.outputs.expires_unix }}
+ publish: ${{ steps.resolve.outputs.publish }}
+ steps:
+ - name: Check out the exact source
+ uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+ with:
+ ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
+ fetch-depth: 0
+ persist-credentials: false
+ - id: resolve
+ name: Bind version, tag, and commit
+ shell: bash
+ env:
+ GH_TOKEN: ${{ github.token }}
+ PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+ run: |
+ set -euo pipefail
+ VERSION_PATH=libs/cua-driver/rust/crates/cua-perception/VERSION
+ VERSION=$(tr -d '[:space:]' < "$VERSION_PATH")
+ [[ "$VERSION" =~ ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ ]] || {
+ echo "::error::Perception VERSION is not a stable SemVer: $VERSION"; exit 1; }
+ python3 .github/scripts/validate_release_versions.py --product perception
+
+ if [[ "$GITHUB_EVENT_NAME" == push ]]; then
+ [[ "$GITHUB_REF" == refs/tags/cua-perception-v* ]] || {
+ echo "::error::Publication requires a cua-perception-v* tag push, got $GITHUB_REF"; exit 1; }
+ TAG="${GITHUB_REF#refs/tags/}"
+ [[ "$TAG" == "cua-perception-v$VERSION" ]] || {
+ echo "::error::$TAG does not match VERSION $VERSION"; exit 1; }
+ SOURCE_SHA="$GITHUB_SHA"
+ [[ "$(git rev-parse HEAD)" == "$SOURCE_SHA" ]]
+ # release-please.yml anchors each merged version with a
+ # lightweight tag; refuse annotated or moved tags.
+ IFS=$'\t' read -r TAG_TYPE TAG_SHA < <(
+ gh api "repos/$GITHUB_REPOSITORY/git/ref/tags/$TAG" \
+ --jq '[.object.type, .object.sha] | @tsv')
+ [[ "$TAG_TYPE" == commit && "$TAG_SHA" == "$SOURCE_SHA" ]] || {
+ echo "::error::$TAG is not a lightweight tag at $SOURCE_SHA"; exit 1; }
+ git fetch --no-tags origin "+refs/heads/main:refs/remotes/origin/main"
+ git merge-base --is-ancestor "$SOURCE_SHA" origin/main || {
+ echo "::error::$TAG points outside main history"; exit 1; }
+ REVIEWED_REF="refs/tags/$TAG"
+ PUBLISH=true
+ else
+ TAG="cua-perception-v$VERSION"
+ SOURCE_SHA="$PR_HEAD_SHA"
+ [[ "$(git rev-parse HEAD)" == "$SOURCE_SHA" ]]
+ REVIEWED_REF=""
+ PUBLISH=false
+ fi
+ [[ "$SOURCE_SHA" =~ ^[0-9a-f]{40}$ ]]
+
+ # Deterministic across re-runs of the same tag and monotonic across
+ # releases: UTC commit minute as YYMMDDHHMM. It exceeds the
+ # date-based staging catalog versions (YYYYMMDDNN) already issued,
+ # so the Driver's rollback check accepts release catalogs.
+ COMMIT_UNIX=$(git show -s --format=%ct "$SOURCE_SHA")
+ CATALOG_VERSION=$(date -u -d "@$COMMIT_UNIX" +%y%m%d%H%M)
+ CATALOG_VERSION=$((10#$CATALOG_VERSION))
+ # Catalogs expire one year after the release commit and never after
+ # the active signing key.
+ KEY_VALID_UNTIL=$(jq -r '.activeKeyId as $id | .keys[] | select(.keyId == $id) | .validUntilUnix' \
+ .github/releases/cua-perception/trust-root.json)
+ EXPIRES_UNIX=$((COMMIT_UNIX + 365 * 86400))
+ if (( EXPIRES_UNIX > KEY_VALID_UNTIL - 86400 )); then
+ EXPIRES_UNIX=$((KEY_VALID_UNTIL - 86400))
+ fi
+ (( EXPIRES_UNIX > $(date +%s) + 7 * 86400 )) || {
+ echo "::error::Catalog would expire within a week; cut a new release instead"; exit 1; }
+
+ {
+ echo "version=$VERSION"
+ echo "tag=$TAG"
+ echo "source_sha=$SOURCE_SHA"
+ echo "reviewed_ref=$REVIEWED_REF"
+ echo "catalog_version=$CATALOG_VERSION"
+ echo "expires_unix=$EXPIRES_UNIX"
+ echo "publish=$PUBLISH"
+ } >> "$GITHUB_OUTPUT"
+ echo "Cua Perception $VERSION at $SOURCE_SHA (catalog $CATALOG_VERSION, expires $EXPIRES_UNIX, publish=$PUBLISH)"
+
+ reviewed-model:
+ name: Fetch the reviewed detector conversion
+ needs: resolve
+ runs-on: ubuntu-latest
+ timeout-minutes: 15
+ # The reviewed conversion is an asset of an unpublished (draft) release,
+ # and GitHub lists draft release assets only to tokens with push access.
+ # This job only reads that asset and hashes it; it runs no checked-out
+ # code and keeps no credentials in the checkout.
+ permissions:
+ contents: write
+ steps:
+ - name: Check out the exact source
+ uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+ with:
+ ref: ${{ needs.resolve.outputs.source_sha }}
+ persist-credentials: false
+ - name: Download and verify the reviewed model
+ shell: bash
+ env:
+ GH_TOKEN: ${{ github.token }}
+ run: |
+ set -euo pipefail
+ read -r FILENAME SIZE SHA256 < <(jq -r '.artifacts[] | select(.role == "icon-detect") | "\(.filename) \(.size) \(.sha256)"' \
+ libs/cua-driver/rust/crates/cua-perception/scripts/artifacts.lock.json)
+ [[ -n "$FILENAME" && "$FILENAME" != */* ]]
+ ASSET_NAME=$(gh api "repos/$GITHUB_REPOSITORY/releases/assets/$REVIEWED_MODEL_ASSET_ID" --jq .name)
+ [[ "$ASSET_NAME" == "$FILENAME" ]] || {
+ echo "::error::reviewed asset is $ASSET_NAME, expected $FILENAME"; exit 1; }
+ mkdir reviewed-inputs
+ gh api -H "Accept: application/octet-stream" \
+ "repos/$GITHUB_REPOSITORY/releases/assets/$REVIEWED_MODEL_ASSET_ID" > "reviewed-inputs/$FILENAME"
+ ACTUAL_SIZE=$(stat -c %s "reviewed-inputs/$FILENAME")
+ ACTUAL_SHA256=$(sha256sum "reviewed-inputs/$FILENAME" | cut -d' ' -f1)
+ [[ "$ACTUAL_SIZE" == "$SIZE" && "$ACTUAL_SHA256" == "$SHA256" ]] || {
+ echo "::error::reviewed model bytes differ from artifacts.lock.json"; exit 1; }
+ echo "Verified $FILENAME ($SIZE bytes, sha256 $SHA256)"
+ - name: Hand off the verified model
+ uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+ with:
+ name: reviewed-cua-perception-model
+ path: reviewed-inputs/
+ if-no-files-found: error
+ retention-days: 1
+
+ input:
+ name: release input (${{ matrix.target }})
+ needs: [resolve, reviewed-model]
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - runner: ubuntu-latest
+ target: x86_64-unknown-linux-gnu
+ input_artifact: cua-perception-input-linux-x86_64
+ worker: cua-perception
+ # Match the production Driver build and hosted desktop E2E image.
+ - runner: macos-26
+ target: aarch64-apple-darwin
+ input_artifact: cua-perception-input-macos-aarch64
+ worker: cua-perception
+ - runner: windows-latest
+ target: x86_64-pc-windows-msvc
+ input_artifact: cua-perception-input-windows-x86_64
+ worker: cua-perception.exe
+ runs-on: ${{ matrix.runner }}
+ timeout-minutes: 90
+ steps:
+ - name: Check out the exact source
+ uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+ with:
+ ref: ${{ needs.resolve.outputs.source_sha }}
+ fetch-depth: 0
+ persist-credentials: false
+ - uses: dtolnay/rust-toolchain@4716b85f2fac3e324e64fa2810f6b5c3905760a5 # 1.97.1
+ - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+ with:
+ python-version: "3.12"
+ - name: Install release validators
+ shell: bash
+ run: python -m pip install --disable-pip-version-check --require-hashes -r .github/releases/cua-perception/test-requirements.lock
+ - name: Download the verified model
+ uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
+ with:
+ name: reviewed-cua-perception-model
+ path: reviewed-inputs
+ - name: Build the native worker
+ shell: bash
+ run: |
+ set -euo pipefail
+ cargo build --manifest-path libs/cua-driver/rust/Cargo.toml \
+ -p cua-perception --release --locked
+ - name: Assemble and execute native health, self-test, and real parse
+ shell: bash
+ env:
+ SOURCE_SHA: ${{ needs.resolve.outputs.source_sha }}
+ TARGET: ${{ matrix.target }}
+ VERSION: ${{ needs.resolve.outputs.version }}
+ WORKER: ${{ matrix.worker }}
+ run: |
+ set -euo pipefail
+ python libs/cua-driver/rust/crates/cua-perception/scripts/assemble_bundle.py \
+ --target "$TARGET" \
+ --worker "libs/cua-driver/rust/target/release/$WORKER" \
+ --inputs reviewed-inputs \
+ --cache "$RUNNER_TEMP/cua-perception-cache" \
+ --real-parse-fixture libs/cua-driver/tests/fixtures/apps/cross-platform/tauri/src-tauri/icons/icon.png \
+ --source-sha "$SOURCE_SHA" \
+ --version "$VERSION" \
+ --output perception-input
+ - name: Convert sealed assembler evidence to candidate input
+ shell: bash
+ run: |
+ set -euo pipefail
+ python - <<'PY'
+ import json, pathlib
+
+ root = pathlib.Path("perception-input")
+ manifest = json.loads((root / "artifact-manifest.json").read_text())
+ (root / "release-input.json").write_text(
+ json.dumps(manifest, indent=2, sort_keys=True) + "\n"
+ )
+ PY
+ python .github/scripts/perception_release.py bind-source \
+ --manifest perception-input/release-input.json \
+ --payload-root perception-input \
+ --repository-root .
+ python .github/scripts/perception_release.py validate \
+ --manifest perception-input/release-input.json \
+ --payload-root perception-input
+ rm perception-input/artifact-manifest.json perception-input/SHA256SUMS
+ - name: Preserve exact candidate packaging input
+ if: needs.resolve.outputs.publish == 'true'
+ uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+ with:
+ name: ${{ matrix.input_artifact }}
+ path: perception-input/
+ if-no-files-found: error
+ retention-days: 7
+ - name: Dry run the unsigned package
+ if: needs.resolve.outputs.publish != 'true'
+ shell: bash
+ env:
+ CATALOG_VERSION: ${{ needs.resolve.outputs.catalog_version }}
+ EXPIRES_UNIX: ${{ needs.resolve.outputs.expires_unix }}
+ run: |
+ set -euo pipefail
+ python .github/scripts/perception_release.py run-gates \
+ --manifest perception-input/release-input.json \
+ --payload-root perception-input \
+ --evidence executed-verification.json
+ python .github/scripts/perception_release.py package \
+ --manifest perception-input/release-input.json \
+ --payload-root perception-input \
+ --executed-evidence executed-verification.json \
+ --output perception-candidate \
+ --key-id cua-extension-ed25519-2026-09 \
+ --catalog-version "$CATALOG_VERSION" \
+ --expires-unix "$EXPIRES_UNIX"
+ python .github/scripts/perception_release.py \
+ verify-checksums perception-candidate/checksums.txt
+ - name: Install the published Cua Driver (macOS and Linux)
+ if: needs.resolve.outputs.publish != 'true' && runner.os != 'Windows'
+ shell: bash
+ env:
+ CUA_DRIVER_RS_HOME: ${{ runner.temp }}/cua-driver-installer-home
+ CUA_DRIVER_RS_INSTALL_DIR: ${{ runner.temp }}/cua-driver-bin
+ CUA_DRIVER_RS_NO_MODIFY_PATH: "1"
+ CUA_DRIVER_RS_TELEMETRY_ENABLED: "false"
+ CUA_TELEMETRY_ENABLED: "false"
+ run: |
+ set -euo pipefail
+ if [[ "$RUNNER_OS" == Linux ]]; then
+ sudo apt-get update
+ sudo apt-get install -y --no-install-recommends \
+ libx11-6 libxi6 libxtst6 libxext6 libwayland-client0 libxkbcommon0
+ fi
+ bash libs/cua-driver/scripts/install.sh --no-modify-path
+ echo "CUA_DRIVER_BINARY=$CUA_DRIVER_RS_INSTALL_DIR/cua-driver" >> "$GITHUB_ENV"
+ - name: Install the published Cua Driver (Windows)
+ if: needs.resolve.outputs.publish != 'true' && runner.os == 'Windows'
+ shell: pwsh
+ run: |
+ $root = Join-Path $env:RUNNER_TEMP "cua-driver-installer"
+ $env:CUA_DRIVER_RS_HOME = Join-Path $root "home"
+ $env:CUA_DRIVER_RS_INSTALL_DIR = Join-Path $root "bin"
+ $env:CUA_DRIVER_RS_TELEMETRY_ENABLED = "false"
+ & ./libs/cua-driver/scripts/install.ps1 -NoAutoStart -NoPathUpdate
+ $binary = Join-Path $env:CUA_DRIVER_RS_INSTALL_DIR "cua-driver.exe"
+ if (-not (Test-Path -LiteralPath $binary)) { throw "installer did not create $binary" }
+ # The installer can leave a nonzero $LASTEXITCODE from an optional
+ # probe; the step result must reflect the installed binary instead.
+ & $binary --version
+ if ($LASTEXITCODE -ne 0) { throw "installed binary exited with $LASTEXITCODE" }
+ "CUA_DRIVER_BINARY=$binary" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+ exit 0
+ - name: Developer-only install check of the unsigned package
+ if: needs.resolve.outputs.publish != 'true'
+ shell: bash
+ env:
+ SOURCE_SHA: ${{ needs.resolve.outputs.source_sha }}
+ TARGET: ${{ matrix.target }}
+ VERSION: ${{ needs.resolve.outputs.version }}
+ run: |
+ set -euo pipefail
+ python .github/scripts/perception_release_install_check.py \
+ --driver "$CUA_DRIVER_BINARY" \
+ --unsigned-archive "perception-candidate/cua-perception-$VERSION-$TARGET.tar.gz" \
+ --version "$VERSION" \
+ --target "$TARGET" \
+ --source-sha "$SOURCE_SHA" \
+ --image libs/cua-driver/tests/fixtures/apps/cross-platform/tauri/src-tauri/icons/icon.png \
+ --home "$RUNNER_TEMP/cua-perception-dry-run-home" \
+ --evidence dry-run-install-check.json
+
+ candidate:
+ name: candidate ${{ matrix.target_triple }}
+ needs: [resolve, input]
+ if: needs.resolve.outputs.publish == 'true'
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - target_os: linux
+ target_triple: x86_64-unknown-linux-gnu
+ payload_artifact: cua-perception-input-linux-x86_64
+ - target_os: macos
+ target_triple: aarch64-apple-darwin
+ payload_artifact: cua-perception-input-macos-aarch64
+ - target_os: windows
+ target_triple: x86_64-pc-windows-msvc
+ payload_artifact: cua-perception-input-windows-x86_64
+ uses: ./.github/workflows/cd-cua-perception-candidate.yml
+ with:
+ payload_artifact: ${{ matrix.payload_artifact }}
+ payload_run_id: ${{ fromJSON(github.run_id) }}
+ source_ref: ${{ needs.resolve.outputs.source_sha }}
+ reviewed_ref: ${{ needs.resolve.outputs.reviewed_ref }}
+ target_os: ${{ matrix.target_os }}
+ target_triple: ${{ matrix.target_triple }}
+ catalog_version: ${{ fromJSON(needs.resolve.outputs.catalog_version) }}
+ expires_unix: ${{ fromJSON(needs.resolve.outputs.expires_unix) }}
+ secrets:
+ PERCEPTION_ED25519_PRIVATE_KEY_BASE64: ${{ secrets.PERCEPTION_ED25519_PRIVATE_KEY_BASE64 }}
+
+ verify:
+ name: verify signed release (${{ matrix.target }})
+ needs: [resolve, candidate]
+ if: needs.resolve.outputs.publish == 'true'
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - runner: ubuntu-latest
+ target: x86_64-unknown-linux-gnu
+ - runner: macos-26
+ target: aarch64-apple-darwin
+ - runner: windows-latest
+ target: x86_64-pc-windows-msvc
+ runs-on: ${{ matrix.runner }}
+ timeout-minutes: 45
+ steps:
+ - name: Check out the exact release source
+ uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+ with:
+ ref: ${{ needs.resolve.outputs.source_sha }}
+ persist-credentials: false
+ - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+ with:
+ python-version: "3.12"
+ - name: Download the signed candidate
+ uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
+ with:
+ name: STAGING-cua-perception-candidate-${{ matrix.target }}-${{ needs.resolve.outputs.source_sha }}
+ path: signed
+ - name: Verify checksums and the publisher signature against the trust root
+ shell: bash
+ env:
+ SOURCE_SHA: ${{ needs.resolve.outputs.source_sha }}
+ TARGET: ${{ matrix.target }}
+ VERSION: ${{ needs.resolve.outputs.version }}
+ CATALOG_VERSION: ${{ needs.resolve.outputs.catalog_version }}
+ EXPIRES_UNIX: ${{ needs.resolve.outputs.expires_unix }}
+ run: |
+ set -euo pipefail
+ python .github/scripts/perception_release.py verify-checksums signed/checksums.txt
+ python .github/scripts/perception_release.py verify-checksums signed/signed-candidate-checksums.txt
+ node <<'JS'
+ const crypto = require("node:crypto");
+ const fs = require("node:fs");
+ const trust = JSON.parse(fs.readFileSync(".github/releases/cua-perception/trust-root.json"));
+ const active = trust.keys.filter((key) =>
+ key.keyId === trust.activeKeyId && key.algorithm === "Ed25519" && key.status === "active");
+ if (active.length !== 1) throw new Error("active trust root is missing or ambiguous");
+ const catalog = JSON.parse(fs.readFileSync("signed/signed-catalog.json"));
+ const payloadBytes = fs.readFileSync("signed/catalog-payload.json");
+ if (JSON.stringify(catalog.payload) !== payloadBytes.toString()) {
+ throw new Error("signed catalog payload differs from catalog-payload.json");
+ }
+ const spki = Buffer.concat([
+ Buffer.from("302a300506032b6570032100", "hex"),
+ Buffer.from(active[0].publicKeyBase64, "base64"),
+ ]);
+ const key = crypto.createPublicKey({key: spki, format: "der", type: "spki"});
+ if (catalog.signature_algorithm !== "ed25519" ||
+ !crypto.verify(null, payloadBytes, key, Buffer.from(catalog.signature, "base64"))) {
+ throw new Error("catalog signature does not verify against the active trust root");
+ }
+ const payload = catalog.payload;
+ const expected = {
+ publisher_id: "cua",
+ key_id: trust.activeKeyId,
+ extension_id: "cua-perception",
+ version: process.env.VERSION,
+ target: process.env.TARGET,
+ corresponding_source_revision: process.env.SOURCE_SHA,
+ catalog_version: Number(process.env.CATALOG_VERSION),
+ expires_unix: Number(process.env.EXPIRES_UNIX),
+ archive: `cua-perception-${process.env.VERSION}-${process.env.TARGET}.tar.gz`,
+ };
+ for (const [field, value] of Object.entries(expected)) {
+ if (payload[field] !== value) throw new Error(`catalog ${field} is ${payload[field]}, expected ${value}`);
+ }
+ const archive = fs.readFileSync(`signed/${payload.archive}`);
+ if (archive.length !== payload.archive_size ||
+ crypto.createHash("sha256").update(archive).digest("hex") !== payload.archive_sha256) {
+ throw new Error("catalog archive binding is invalid");
+ }
+ console.log(`verified ${payload.archive} for ${payload.target} (catalog ${payload.catalog_version})`);
+ JS
+ - name: Install the published Cua Driver (macOS and Linux)
+ if: runner.os != 'Windows'
+ shell: bash
+ env:
+ CUA_DRIVER_RS_HOME: ${{ runner.temp }}/cua-driver-installer-home
+ CUA_DRIVER_RS_INSTALL_DIR: ${{ runner.temp }}/cua-driver-bin
+ CUA_DRIVER_RS_NO_MODIFY_PATH: "1"
+ CUA_DRIVER_RS_TELEMETRY_ENABLED: "false"
+ CUA_TELEMETRY_ENABLED: "false"
+ run: |
+ set -euo pipefail
+ if [[ "$RUNNER_OS" == Linux ]]; then
+ sudo apt-get update
+ sudo apt-get install -y --no-install-recommends \
+ libx11-6 libxi6 libxtst6 libxext6 libwayland-client0 libxkbcommon0
+ fi
+ bash libs/cua-driver/scripts/install.sh --no-modify-path
+ echo "CUA_DRIVER_BINARY=$CUA_DRIVER_RS_INSTALL_DIR/cua-driver" >> "$GITHUB_ENV"
+ - name: Install the published Cua Driver (Windows)
+ if: runner.os == 'Windows'
+ shell: pwsh
+ run: |
+ $root = Join-Path $env:RUNNER_TEMP "cua-driver-installer"
+ $env:CUA_DRIVER_RS_HOME = Join-Path $root "home"
+ $env:CUA_DRIVER_RS_INSTALL_DIR = Join-Path $root "bin"
+ $env:CUA_DRIVER_RS_TELEMETRY_ENABLED = "false"
+ & ./libs/cua-driver/scripts/install.ps1 -NoAutoStart -NoPathUpdate
+ $binary = Join-Path $env:CUA_DRIVER_RS_INSTALL_DIR "cua-driver.exe"
+ if (-not (Test-Path -LiteralPath $binary)) { throw "installer did not create $binary" }
+ # The installer can leave a nonzero $LASTEXITCODE from an optional
+ # probe; the step result must reflect the installed binary instead.
+ & $binary --version
+ if ($LASTEXITCODE -ne 0) { throw "installed binary exited with $LASTEXITCODE" }
+ "CUA_DRIVER_BINARY=$binary" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+ exit 0
+ - name: Inspect, install, self-test, parse, and remove with the published Driver
+ shell: bash
+ env:
+ SOURCE_SHA: ${{ needs.resolve.outputs.source_sha }}
+ TARGET: ${{ matrix.target }}
+ VERSION: ${{ needs.resolve.outputs.version }}
+ run: |
+ set -euo pipefail
+ python .github/scripts/perception_release_install_check.py \
+ --driver "$CUA_DRIVER_BINARY" \
+ --catalog signed/signed-catalog.json \
+ --version "$VERSION" \
+ --target "$TARGET" \
+ --source-sha "$SOURCE_SHA" \
+ --image libs/cua-driver/tests/fixtures/apps/cross-platform/tauri/src-tauri/icons/icon.png \
+ --home "$RUNNER_TEMP/cua-perception-release-home" \
+ --evidence "install-check-$TARGET.json"
+ - name: Preserve install evidence
+ uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+ with:
+ name: cua-perception-install-evidence-${{ matrix.target }}
+ path: install-check-${{ matrix.target }}.json
+ if-no-files-found: error
+ retention-days: 90
+
+ release:
+ name: Publish the verified release
+ needs: [resolve, input, candidate, verify]
+ if: >-
+ github.event_name == 'push' &&
+ startsWith(github.ref, 'refs/tags/cua-perception-v') &&
+ needs.resolve.outputs.publish == 'true'
+ runs-on: ubuntu-latest
+ timeout-minutes: 30
+ permissions:
+ actions: read
+ contents: write
+ steps:
+ - name: Check out the tag
+ uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+ with:
+ ref: ${{ github.ref }}
+ fetch-depth: 0
+ persist-credentials: false
+ - name: Refuse anything but the verified tag commit
+ shell: bash
+ env:
+ SOURCE_SHA: ${{ needs.resolve.outputs.source_sha }}
+ TAG: ${{ needs.resolve.outputs.tag }}
+ run: |
+ set -euo pipefail
+ [[ "$GITHUB_REF" == "refs/tags/$TAG" ]]
+ HEAD_SHA=$(git rev-parse HEAD)
+ TAG_SHA=$(git rev-list -n 1 "$TAG")
+ # Every job above built, signed, and verified github.sha.
+ if [[ "$HEAD_SHA" != "$GITHUB_SHA" || "$TAG_SHA" != "$GITHUB_SHA" || "$SOURCE_SHA" != "$GITHUB_SHA" ]]; then
+ echo "::error::$TAG ($TAG_SHA) is not the verified commit ($GITHUB_SHA)"
+ exit 1
+ fi
+ - name: Download signed candidates
+ uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
+ with:
+ pattern: STAGING-cua-perception-candidate-*-${{ needs.resolve.outputs.source_sha }}
+ path: signed
+ - name: Download install evidence
+ uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
+ with:
+ pattern: cua-perception-install-evidence-*
+ path: evidence
+ merge-multiple: true
+ - name: Stage release assets
+ shell: bash
+ env:
+ SOURCE_SHA: ${{ needs.resolve.outputs.source_sha }}
+ VERSION: ${{ needs.resolve.outputs.version }}
+ run: |
+ set -euo pipefail
+ mkdir release-upload
+ for TARGET in aarch64-apple-darwin x86_64-unknown-linux-gnu x86_64-pc-windows-msvc; do
+ DIR="signed/STAGING-cua-perception-candidate-$TARGET-$SOURCE_SHA"
+ BASE="cua-perception-$VERSION-$TARGET"
+ python3 .github/scripts/perception_release.py verify-checksums "$DIR/signed-candidate-checksums.txt"
+ python3 .github/scripts/perception_release.py verify-checksums "$DIR/checksums.txt"
+ ARCHIVE=$(jq -r .payload.archive "$DIR/signed-catalog.json")
+ [[ "$ARCHIVE" == "$BASE.tar.gz" ]]
+ [[ "$(jq -r .payload.target "$DIR/signed-catalog.json")" == "$TARGET" ]]
+ [[ "$(jq -r .payload.corresponding_source_revision "$DIR/signed-catalog.json")" == "$SOURCE_SHA" ]]
+ jq -e --arg target "$TARGET" --arg version "$VERSION" \
+ '.target == $target and .extension_version == $version and .trust == "publisher-verified"' \
+ "evidence/install-check-$TARGET.json" >/dev/null
+ # The Driver resolves the archive beside the catalog, so the
+ # archive keeps its signed name and the catalog gets a unique one.
+ cp "$DIR/$ARCHIVE" "release-upload/$ARCHIVE"
+ cp "$DIR/signed-catalog.json" "release-upload/$BASE.catalog.json"
+ cp "$DIR/sbom.spdx.json" "release-upload/$BASE.sbom.spdx.json"
+ cp "$DIR/provenance.redacted.json" "release-upload/$BASE.provenance.json"
+ cp "$DIR/runtime-contract.json" "release-upload/$BASE.runtime-contract.json"
+ cp "evidence/install-check-$TARGET.json" "release-upload/$BASE.install-check.json"
+ done
+ (cd release-upload && sha256sum -- * > SHA256SUMS)
+ cat release-upload/SHA256SUMS
+ - name: Write release notes
+ shell: bash
+ env:
+ SOURCE_SHA: ${{ needs.resolve.outputs.source_sha }}
+ VERSION: ${{ needs.resolve.outputs.version }}
+ run: |
+ set -euo pipefail
+ DRIVER_VERSION=$(jq -r .driver_version "release-upload/cua-perception-$VERSION-x86_64-unknown-linux-gnu.install-check.json")
+ {
+ awk -v version="$VERSION" '
+ /^## / { if (found) exit; if (index($0, "[" version "]") || $0 == "## " version) { found = 1; next } }
+ found { print }
+ ' libs/cua-driver/rust/crates/cua-perception/CHANGELOG.md
+ cat <<EOF
+
+ ## Install
+
+ Cua Perception is an optional, separately licensed extension for Cua Driver. Download the catalog and the archive for your platform into the same directory, then inspect before installing:
+
+ | Platform | Catalog | Archive |
+ | --- | --- | --- |
+ | macOS arm64 | \`cua-perception-$VERSION-aarch64-apple-darwin.catalog.json\` | \`cua-perception-$VERSION-aarch64-apple-darwin.tar.gz\` |
+ | Linux x64 | \`cua-perception-$VERSION-x86_64-unknown-linux-gnu.catalog.json\` | \`cua-perception-$VERSION-x86_64-unknown-linux-gnu.tar.gz\` |
+ | Windows x64 | \`cua-perception-$VERSION-x86_64-pc-windows-msvc.catalog.json\` | \`cua-perception-$VERSION-x86_64-pc-windows-msvc.tar.gz\` |
+
+ \`\`\`bash
+ cua-driver extension inspect cua-perception --catalog cua-perception-$VERSION-<target>.catalog.json
+ cua-driver extension install cua-perception --catalog cua-perception-$VERSION-<target>.catalog.json
+ cua-driver extension status cua-perception --self-test
+ \`\`\`
+
+ Each catalog is signed with the \`cua\` publisher key pinned in Cua Driver. The release gate installed, self-tested, and parsed with every catalog using $DRIVER_VERSION from the canonical installer. Source: \`$SOURCE_SHA\`.
+
+ The archive bundles the OmniParser detector (AGPL-3.0-only) and its corresponding source; see the included notices and \`libs/cua-driver/docs/perception-third-party-notices.md\`.
+ EOF
+ } > release-notes.md
+ cat release-notes.md
+ - name: Publish the GitHub release
+ shell: bash
+ env:
+ GH_REPO: ${{ github.repository }}
+ GH_TOKEN: ${{ github.token }}
+ TAG: ${{ needs.resolve.outputs.tag }}
+ VERSION: ${{ needs.resolve.outputs.version }}
+ run: |
+ set -euo pipefail
+ if gh release view "$TAG" --json isDraft --jq .isDraft > release-state.txt 2>/dev/null; then
+ if [[ "$(cat release-state.txt)" == "false" ]]; then
+ # A published release is immutable. Accept a re-run only when
+ # every asset already matches the verified bytes.
+ gh api "repos/$GITHUB_REPOSITORY/releases/tags/$TAG" \
+ --jq '.assets[] | "\((.digest // "") | ltrimstr("sha256:")) \(.name)"' | sort > published.txt
+ (cd release-upload && sha256sum -- * | sort) > expected.txt
+ diff -u expected.txt published.txt
+ echo "$TAG is already published with the verified assets."
+ exit 0
+ fi
+ gh release upload "$TAG" release-upload/* --clobber
+ else
+ gh release create "$TAG" release-upload/* \
+ --draft \
+ --verify-tag \
+ --title "cua-perception: v$VERSION" \
+ --notes-file release-notes.md
+ fi
+ gh release edit "$TAG" --notes-file release-notes.md --draft=false --latest=false
+ gh release view "$TAG" --json isDraft,assets \
+ --jq '"draft=\(.isDraft) assets=\(.assets | length)"'
diff --git a/.github/workflows/ci-cua-perception-release.yml b/.github/workflows/ci-cua-perception-release.yml
index 57987574b5..c6644a5ab2 100644
--- a/.github/workflows/ci-cua-perception-release.yml
+++ b/.github/workflows/ci-cua-perception-release.yml
@@ -5,11 +5,15 @@ on:
paths:
- ".github/releases/**"
- ".github/scripts/perception_release.py"
+ - ".github/scripts/perception_release_install_check.py"
+ - ".github/scripts/tests/test_cua_perception_release_workflow.py"
+ - ".github/scripts/tests/test_perception_release_install_check.py"
- ".github/scripts/verify_cua_driver_release_archives.py"
- ".github/scripts/tests/test_cua_driver_default_distribution.py"
- ".github/scripts/tests/test_cua_perception_release_topology.py"
- ".github/scripts/tests/test_verify_cua_driver_release_archives.py"
- ".github/workflows/cd-cua-perception-candidate.yml"
+ - ".github/workflows/cd-cua-perception.yml"
- ".github/workflows/cd-rust-cua-driver.yml"
- ".github/workflows/ci-cua-perception-release.yml"
- ".github/workflows/release-please.yml"
@@ -23,10 +27,14 @@ on:
paths:
- ".github/releases/**"
- ".github/scripts/perception_release.py"
+ - ".github/scripts/perception_release_install_check.py"
+ - ".github/scripts/tests/test_cua_perception_release_workflow.py"
+ - ".github/scripts/tests/test_perception_release_install_check.py"
- ".github/scripts/verify_cua_driver_release_archives.py"
- ".github/scripts/tests/test_cua_driver_default_distribution.py"
- ".github/scripts/tests/test_verify_cua_driver_release_archives.py"
- ".github/workflows/cd-cua-perception-candidate.yml"
+ - ".github/workflows/cd-cua-perception.yml"
- ".github/workflows/cd-rust-cua-driver.yml"
- ".github/workflows/ci-cua-perception-release.yml"
- "libs/cua-driver/rust/crates/cua-perception/**"
@@ -84,6 +92,8 @@ jobs:
python3 -m pytest \
.github/scripts/tests/test_cua_driver_default_distribution.py \
.github/scripts/tests/test_cua_perception_release_topology.py \
+ .github/scripts/tests/test_cua_perception_release_workflow.py \
+ .github/scripts/tests/test_perception_release_install_check.py \
.github/scripts/tests/test_verify_cua_driver_release_archives.py \
.github/scripts/tests/test_release_channels.py \
.github/scripts/tests/test_resolve_release_please_request.py \
diff --git a/libs/cua-driver/docs/perception-extension.md b/libs/cua-driver/docs/perception-extension.md
index f54b458ef6..e014deb1b8 100644
--- a/libs/cua-driver/docs/perception-extension.md
+++ b/libs/cua-driver/docs/perception-extension.md
@@ -68,8 +68,21 @@ diagnostic context and must not be parsed as a stable field.
## Explicit lifecycle
-Use the signed catalog distributed with the reviewed candidate and inspect the
-exact target before changing local state:
+Each Cua Perception release is published as the `cua-perception-v<version>`
+GitHub release. It carries one signed catalog and one archive per target:
+
+| Target | Catalog | Archive |
+| --- | --- | --- |
+| macOS arm64 | `cua-perception-<version>-aarch64-apple-darwin.catalog.json` | `cua-perception-<version>-aarch64-apple-darwin.tar.gz` |
+| Linux x64 | `cua-perception-<version>-x86_64-unknown-linux-gnu.catalog.json` | `cua-perception-<version>-x86_64-unknown-linux-gnu.tar.gz` |
+| Windows x64 | `cua-perception-<version>-x86_64-pc-windows-msvc.catalog.json` | `cua-perception-<version>-x86_64-pc-windows-msvc.tar.gz` |
+
+The release also carries each target's SBOM, redacted provenance, runtime
+contract, the release gate's install evidence, and a `SHA256SUMS` file. The
+Driver resolves the archive named in the catalog relative to the catalog file,
+so download both into the same directory. Select the release by its
+`cua-perception-v*` tag; it is never marked as the repository's Latest release.
+Inspect the exact target before changing local state:
```bash
cua-driver extension inspect cua-perception --catalog <catalog.json>
@@ -82,6 +95,33 @@ range, capabilities, artifact sizes and hashes, publisher, licenses, notices,
and provenance. Do not substitute an unsigned archive or infer component
availability from the repository-wide latest release.
+Each catalog expires one year after its release commit. After that, install
+from a newer `cua-perception-v*` release.
+
+## Release publication
+
+Cua Perception follows Release Please with no manual publish step. Merging its
+release pull request bumps `VERSION`, and the release workflow anchors the
+merged commit with a lightweight `cua-perception-v<version>` tag. That tag push
+runs `.github/workflows/cd-cua-perception.yml`, which:
+
+1. requires the tag to be a lightweight tag on `main` that matches `VERSION`;
+2. verifies the reviewed OmniParser ONNX conversion against
+ `scripts/artifacts.lock.json`;
+3. builds the worker on each target, assembles the bundle, and runs its health
+ check, self-test, and real parse;
+4. re-verifies, packages, and signs each target in the reviewed candidate
+ workflow, whose signing job runs in the `cua-perception-candidate-signing`
+ environment;
+5. installs the published Cua Driver with its canonical installer on each
+ target and runs `extension inspect`, `install`, `status --self-test`,
+ `perception parse`, and `remove` against the signed catalog; and
+6. publishes the verified assets only when every job passed for the exact tag
+ commit.
+
+Pull requests that change this pipeline run steps 1 through 3 plus an unsigned
+package and a developer-only install check. They never sign or publish.
+
Inspect a replacement before running `extension update`. Remove only the
extension-owned installation with `extension remove cua-perception`. Neither
operation changes the default Driver or an external `cua-som` installation.