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
docs: define contribution intake workflow (#3006)
Francesco Bonaccibf7ee4b44058
diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.ymlnew file mode 100644index 0000000000..4a6b88b7a2--- /dev/null+++ b/.github/ISSUE_TEMPLATE/bug.yml@@ -0,0 +1,106 @@+name: Bug report+description: Report reproducible incorrect behavior in Cua+title: "[Bug]: "+labels:+ - bug+body:+ - type: markdown+ attributes:+ value: |+ Search existing issues and pull requests before filing. Describe the observed+ behavior and evidence rather than only a proposed fix. Do not include credentials,+ private application data, sensitive screenshots, or vulnerability details. Use+ [private vulnerability reporting](https://github.com/trycua/cua/security/advisories/new)+ for suspected security issues. File one problem per issue; open separate+ issues for unrelated bugs.++ - type: dropdown+ id: area+ attributes:+ label: Primary area+ options:+ - Cua Driver+ - SDK or bindings+ - MCP or agent integration+ - CLI+ - Lume+ - Containers or images+ - Documentation+ - Build, packaging, or release+ - Other+ validations:+ required: true++ - type: textarea+ id: summary+ attributes:+ label: Summary+ description: Describe the incorrect behavior in one or two sentences.+ validations:+ required: true++ - type: textarea+ id: reproduction+ attributes:+ label: Reproduction+ description: Provide the smallest numbered steps or example that reproduces the behavior. If it is intermittent, say how often you observe it.+ placeholder: |+ 1. ...+ 2. ...+ 3. ...+ validations:+ required: true++ - type: textarea+ id: expected+ attributes:+ label: Expected behavior+ description: What observable result did you expect?+ validations:+ required: true++ - type: textarea+ id: actual+ attributes:+ label: Actual behavior+ description: What happened instead? Include exact structured errors when available. If you do not know the cause, say so rather than guessing a diagnosis.+ validations:+ required: true++ - type: textarea+ id: environment+ attributes:+ label: Environment+ description: Include the component/package and version or commit, operating system and architecture, plus the application, browser, window system, or container image when relevant.+ placeholder: |+ Cua component and version/commit:+ Operating system and architecture:+ Application/browser/window system/image:+ validations:+ required: true++ - type: textarea+ id: evidence+ attributes:+ label: Evidence+ description: Add redacted logs, error text, screenshots, recordings, or a minimal repository that help prove the behavior. Write "None available" when no additional artifact exists.+ validations:+ required: true++ - type: textarea+ id: workaround+ attributes:+ label: Workaround and additional context+ description: Describe any workaround, regression range, suspected area, or related issue or pull request.++ - type: checkboxes+ id: checks+ attributes:+ label: Submission checks+ options:+ - label: I searched for duplicate issues and active pull requests.+ required: true+ - label: This issue describes a single problem.+ required: true+ - label: I removed credentials, private data, sensitive screenshots, and vulnerability details from this public report.+ required: truediff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.ymlnew file mode 100644index 0000000000..e9db742518--- /dev/null+++ b/.github/ISSUE_TEMPLATE/config.yml@@ -0,0 +1,11 @@+blank_issues_enabled: false+contact_links:+ - name: Security vulnerability+ url: https://github.com/trycua/cua/security/advisories/new+ about: Report suspected vulnerabilities privately. Do not open a public issue.+ - name: Question or contributor help+ url: https://discord.com/invite/mVnXXpdE85+ about: Ask questions and get help from the Cua community.+ - name: RFC guidance+ url: https://github.com/trycua/cua/blob/main/rfcs/README.md+ about: Check whether a public contract or architecture change needs an RFC.diff --git a/.github/ISSUE_TEMPLATE/feature.yml b/.github/ISSUE_TEMPLATE/feature.ymlnew file mode 100644index 0000000000..d0c382fb0e--- /dev/null+++ b/.github/ISSUE_TEMPLATE/feature.yml@@ -0,0 +1,83 @@+name: Feature request+description: Describe a user problem or product improvement+title: "[Feature]: "+labels:+ - enhancement+body:+ - type: markdown+ attributes:+ value: |+ Describe the user problem and desired outcome before proposing an implementation.+ Use the **Request for comments** form when the change affects a public SDK, CLI,+ MCP, protocol, compatibility, permission, security, or cross-component+ architectural contract.++ - type: dropdown+ id: area+ attributes:+ label: Primary area+ options:+ - Cua Driver+ - SDK or bindings+ - MCP or agent integration+ - CLI+ - Lume+ - Containers or images+ - Documentation+ - Build, packaging, or release+ - Cross-component+ - Other+ validations:+ required: true++ - type: textarea+ id: problem+ attributes:+ label: User problem+ description: Who encounters the problem, in which workflow, and what is its impact?+ validations:+ required: true++ - type: textarea+ id: desired_outcome+ attributes:+ label: Desired outcome+ description: Describe the observable behavior or success condition you want.+ validations:+ required: true++ - type: textarea+ id: workaround+ attributes:+ label: Current workaround+ description: How do users handle this today, if at all?++ - type: textarea+ id: scope+ attributes:+ label: Affected components and platforms+ description: List known packages, applications, operating systems, compatibility boundaries, or integrations.++ - type: textarea+ id: alternatives+ attributes:+ label: Alternatives and prior art+ description: Link related issues, RFCs, tools, or standards and note why they do not solve the problem.++ - type: textarea+ id: implementation+ attributes:+ label: Implementation ideas+ description: Optional. Share implementation ideas only after describing the problem and outcome.++ - type: checkboxes+ id: checks+ attributes:+ label: Submission checks+ options:+ - label: I searched for existing issues, RFCs, and active pull requests.+ required: true+ - label: I reviewed the RFC criteria and used the RFC form instead when this requires a public contract or architectural decision.+ required: true+ - label: This public request contains no credentials, private data, sensitive screenshots, or vulnerability details.+ required: truediff --git a/.github/ISSUE_TEMPLATE/rfc.yml b/.github/ISSUE_TEMPLATE/rfc.ymlindex 914175e01d..4fd4251fdb 100644--- a/.github/ISSUE_TEMPLATE/rfc.yml+++ b/.github/ISSUE_TEMPLATE/rfc.yml@@ -9,8 +9,10 @@ body:value: |Use this form for public API, CLI, MCP, protocol, cross-platform architecture,permission, security, compatibility, or multi-component decisions. Search for- existing proposals first. Do not disclose vulnerabilities, credentials, private- user data, partner context, or sensitive screenshots in a public issue.+ existing proposals first. Report suspected vulnerabilities through+ [GitHub private vulnerability reporting](https://github.com/trycua/cua/security/advisories/new).+ Do not disclose vulnerabilities, credentials, private user data, partner context,+ or sensitive screenshots in a public issue.The issue is the discussion and decision record. If the proposal needs a longerspecification or diagrams, add a linked `rfcs/<issue>-<short-name>.md` pull request@@ -98,7 +100,7 @@ body:id: securityattributes:label: Security, privacy, permissions, and telemetry- description: Identify permission boundaries and data that must never be collected or exposed. Use private security reporting for vulnerabilities.+ description: Describe the intended permission and trust boundaries and data that must never be collected or exposed. Do not describe an exploitable defect in shipped code; report that privately instead.validations:required: truediff --git a/.github/pull_request_template.md b/.github/pull_request_template.mdnew file mode 100644index 0000000000..3dbc4ced6c--- /dev/null+++ b/.github/pull_request_template.md@@ -0,0 +1,43 @@+<!--+Keep this description current as scope and evidence change. Do not include+credentials, private user data, sensitive screenshots, or vulnerability details.+Preserve external contributor authorship when their code or design ships.+While this pull request is a draft, use this description as the live record of+scope, progress, blockers, and evidence rather than posting periodic status comments.+-->++## Summary++- Problem this solves:+- What changed:++<!-- Describe observable behavior. Do not narrate the diff file by file. -->++## Related work++<!-- Use Fixes only when this PR fully resolves the issue. Otherwise use Refs. -->++Refs #++RFC (required for a public SDK, CLI, MCP, protocol, compatibility, permission,+or cross-component contract change):++## Compatibility and risk++- User-visible, API/CLI/MCP, migration, permission, or platform impact:+- Risk and rollback:++## Validation++- Focused tests and checks:+- Manual or platform evidence:+- Known gaps or CI still required:++## Contributor and release checks++- [ ] The PR is focused and the description matches the final diff.+- [ ] This change does not require an RFC, or the accepted RFC is linked above.+- [ ] Tests, documentation, and platform evidence are included or the gap is explained.+- [ ] The PR title is a Conventional Commit describing the production change.+- [ ] External contributor authorship is preserved, or no external contribution is included.+- [ ] If release-tracked files changed but this is intentionally non-releasing, the `no-release` label is applied.diff --git a/AGENTS.md b/AGENTS.mdindex 484d63c405..b6a66f40b8 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -23,6 +23,39 @@ Preserve contributor credit when external code or design ships in Cua.Do not reimplement submitted work solely to remove its authorship history.+## Issue and pull request workflow++The human-facing contribution contract lives in [`CONTRIBUTING.md`](CONTRIBUTING.md),+the GitHub issue forms, [`rfcs/README.md`](rfcs/README.md), and+[`SECURITY.md`](SECURITY.md). Keep those files canonical instead of duplicating+their field lists or RFC lifecycle here.++Coding agents act as workers within that contract, not as a planning authority.+GitHub holds the durable record: the issue or RFC carries the problem and the+decision, and the pull request carries the execution. Local schedulers, queues,+and worktree tooling are private conveniences; a reviewer must not need them to+understand, reproduce, or continue the work.++- treat an open issue as intake, not evidence that the work is scheduled or+ ready to implement. Selection must be visible in GitHub through an issue+ assignment, a maintainer scope reply, or maintainer review of a linked draft+ pull request;+- before substantial edits, search for duplicates and active pull requests,+ establish a narrow scope and observable acceptance evidence, and open one+ linked draft pull request early. Do not start a second workstream for an issue+ with an active linked pull request; contribute there or state why it is being+ superseded;+- use one issue or RFC as the problem/decision record and one isolated branch+ or worktree per implementation workstream;+- keep the linked pull request description current with scope, progress,+ validation evidence, known gaps, and blockers instead of posting noisy+ periodic status comments;+- use `Refs #123` unless the pull request fully resolves the linked issue, in+ which case use an issue-closing keyword; and+- route suspected vulnerabilities through the private process in+ [`SECURITY.md`](SECURITY.md), never a public issue, RFC, pull request, log, or+ screenshot.+## Cross-platform Cua Driver behaviorTreat user-visible Cua Driver behavior as a cross-platform contract. Implement@@ -66,8 +99,7 @@ macOS: libs/cua-driver/tests/runners/macos-lume/run-all.sh```- Prefer the GitHub-hosted Windows workflow when its strict preflight proves an- interactive desktop. Do not assume that GitHub-hosted Windows runs in Session- 0. Azure RDP is an optional environment-parity replay, not the canonical gate.+ interactive desktop. Do not assume that GitHub-hosted Windows runs in Session 0. Azure RDP is an optional environment-parity replay, not the canonical gate.- Use the GitHub-hosted Linux X11 workflow for the supported Linux gate. KeepNix source checks and compositor-specific Wayland lanes as their documentedseparate gates.diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex ddd5ef6a85..86230fb498 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -5,9 +5,49 @@ SDKs, a Rust desktop driver, Swift virtualization tools, container images, andpublic documentation. Start with the component that owns the behavior you wantto change.+## Choose Where Work Starts++| You want to | Start with |+| ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |+| Report reproducible incorrect behavior | The **Bug report** issue form |+| Describe a user problem or product improvement | The **Feature request** issue form |+| Change a public contract, compatibility policy, permission boundary, or cross-component architecture | The **Request for comments** issue form and [`rfcs/README.md`](rfcs/README.md) |+| Report a suspected vulnerability | [GitHub private vulnerability reporting](https://github.com/trycua/cua/security/advisories/new), following [`SECURITY.md`](SECURITY.md) |+| Ask for contributor help | The [Cua Discord community](https://discord.com/invite/mVnXXpdE85) |++The issue tracker is an intake queue and historical record, not a promise that+every open item is scheduled or ready for implementation. An open issue means+the report was received. It does not mean anyone is working on it, and it does+not reserve the work.++Before substantial implementation:++1. Search open issues and pull requests for the same problem. If an active pull+ request already exists, contribute there or explain why your pull request+ supersedes it.+2. Comment on the issue with the scope you intend to implement and the+ acceptance evidence you will produce.+3. Open a draft pull request as soon as you have a branch and link it to the+ issue. The linked draft pull request is the visible claim marker that helps+ prevent duplicate work.++Selection must be visible in GitHub through an issue assignment, a maintainer+reply confirming the scope, or maintainer review of the linked draft pull+request. Small, self-contained fixes may go directly to a focused pull request+when the problem and evidence are clear; until reviewed, that work is an+unselected contribution. Work that needs an RFC waits for the recorded decision+in [`rfcs/README.md`](rfcs/README.md) before implementation begins.++Once implementation starts, keep the issue or RFC as the problem and decision+record and the pull request as the current execution record. Link them in both+directions and keep the pull request description current as scope, validation,+or known gaps change. Use `Refs #123` for related work. Use `Fixes #123` only+when merging the pull request will fully resolve that issue.+## Report a Bug-Before opening an issue, search the existing issue tracker. Include:+Before opening the **Bug report** issue form, search the existing issue tracker.+Include:- a concise description and reproducible steps;- expected and actual behavior;@@ -19,9 +59,9 @@ Do not include credentials or private application data.## Propose a Change-For feature requests, describe the user problem and the expected behavior-before prescribing an implementation. Mention affected platforms and existing-workarounds when known.+In the **Feature request** issue form, describe the user problem and the+expected behavior before prescribing an implementation. Mention affected+platforms and existing workarounds when known.Use the [RFC process](rfcs/README.md) before implementation when a proposalchanges a public SDK, CLI, MCP, protocol, compatibility, permission, or@@ -38,6 +78,14 @@ GitHub issue form. Longer proposals and diagrams remain in this repository under5. Run the formatters and linters owned by the changed component.6. Open a focused pull request that explains behavior, validation, and known gaps.+### Agent-Assisted Contributions++Agent-assisted pull requests are welcome and are held to the same standard as+any other contribution. The person who opens the pull request is accountable+for it: read and understand the diff, be able to explain why each change is+present, and run the checks claimed in the description. Generated output or a+successful tool response is not validation evidence by itself.+Use a Conventional Commit title because the squash-merge title becomes therelease entry. `fix(cua-driver): preserve input while reconnecting` produces apatch release, `feat(lume): add a VM readiness probe` produces a minor release,diff --git a/README.md b/README.mdindex aec3acb30e..673be50619 100644--- a/README.md+++ b/README.md@@ -174,6 +174,7 @@ of Setup Assistant on its first display boot; see [issue #2155](https://github.c- [Blog](https://cua.ai/blog) — Tutorials, updates, and research- [Discord](https://discord.com/invite/mVnXXpdE85) — Community support and discussions- [GitHub Issues](https://github.com/trycua/cua/issues) — Bug reports and feature requests+- [Security](SECURITY.md) — Private vulnerability reporting## Citationdiff --git a/SECURITY.md b/SECURITY.mdnew file mode 100644index 0000000000..8dc4313439--- /dev/null+++ b/SECURITY.md@@ -0,0 +1,35 @@+# Security Policy++## Report a Vulnerability++Do not open a public issue, RFC, discussion, or pull request for a suspected+vulnerability. Use [GitHub private vulnerability reporting](https://github.com/trycua/cua/security/advisories/new)+so the report reaches the maintainers without disclosing details publicly.++Include the smallest amount of information needed to investigate:++- the affected Cua component and version or commit;+- the operating system, environment, and configuration when relevant;+- a concise reproduction or proof of the behavior;+- the security impact and conditions required to trigger it; and+- any known mitigation or workaround.++Do not include credentials, tokens, private user or customer data, or unrelated+sensitive material. Redact logs and screenshots before attaching them. Please+avoid public disclosure until maintainers have coordinated remediation and an+appropriate disclosure timeline with you.++Maintainers will use the private report to acknowledge the finding, request any+missing evidence, coordinate remediation, and discuss attribution. Security+reporter attribution remains private until disclosure is permitted.++To propose or debate a security boundary—such as a permission model, trust+boundary, or public contract that does not disclose an exploitable defect—use+the **Request for comments** issue form and [`rfcs/README.md`](rfcs/README.md).+Use private reporting for a specific exploitable defect in shipped code or+configuration. When design and vulnerability details are entangled, report+privately first; maintainers can open or unblock the public RFC after remediation+is coordinated.++For incorrect behavior without a security impact, use the repository's **Bug+report** issue form instead.diff --git a/rfcs/README.md b/rfcs/README.mdindex 633a8d3797..aec9f997e5 100644--- a/rfcs/README.md+++ b/rfcs/README.md@@ -25,6 +25,19 @@ internal refactors that preserve public behavior, or urgent private securityresponse. Suspected vulnerabilities must use the repository's private securityreporting path instead of a public RFC.+### Security design versus vulnerability reports++A public RFC is the right place to decide what a security boundary should be:+which process holds a capability, what a permission prompt must state, which+data must not be collected or exposed, and how authorization appears in a+public contract. A vulnerability report describes a specific exploitable defect+in shipped Cua code or configuration. Design the boundary in public; report the+defect privately through [`SECURITY.md`](../SECURITY.md).++If a hardening proposal cannot be described without disclosing an exploitable+defect, report it privately first. Maintainers can open or unblock the public+RFC after remediation is coordinated.+## Repository structure```text@@ -68,15 +81,15 @@ shorter window, record the reason in the decision summary.## Status vocabulary-| Status | Meaning |-| --- | --- |-| `draft` | The author is still shaping the proposal. |-| `review` | The proposal is ready for technical and product feedback. |-| `accepted` | The decision is approved; implementation may still be pending. |-| `completed` | The accepted proposal's required implementation has shipped. |-| `declined` | Review concluded that Cua should not adopt the proposal. |-| `withdrawn` | The author stopped the proposal before a decision. |-| `superseded` | A linked later RFC replaces this decision. |+| Status | Meaning |+| ------------ | -------------------------------------------------------------- |+| `draft` | The author is still shaping the proposal. |+| `review` | The proposal is ready for technical and product feedback. |+| `accepted` | The decision is approved; implementation may still be pending. |+| `completed` | The accepted proposal's required implementation has shipped. |+| `declined` | Review concluded that Cua should not adopt the proposal. |+| `withdrawn` | The author stopped the proposal before a decision. |+| `superseded` | A linked later RFC replaces this decision. |## Review expectations