feat(cua-driver)!: standardize action results

[f-trycua]

Summary

• replace legacy action-specific structured outputs with one closed ActionResult across all 18 pointer, keyboard, value, and browser-input tools
• keep task postconditions separate in verify_state, while preserving diagnostic MCP text/images and an internal rich execution record
• expose typed action and verification views in Rust, Python, and TypeScript; intentionally reject legacy or missing action payloads
• advertise and validate the same action output schema at the live MCP boundary, and retain a deliberately lossy verified adapter only in computer-server compatibility output
• document the 0.14 → 0.15 migration and update the canonical agent skill for stop/retry/escalation ownership

Why

The old verified boolean and platform-specific request echoes mixed dispatch acknowledgement with evidence of effect. That made no-op or under-verified actions easy for harnesses to mistake for success. This cutover narrows the public contract to stable outcome facts (effect, route, optional delivery/evidence/escalation) and leaves visual interpretation and task completion to the multimodal agent harness.

Breaking impact

The outer MCP ToolResult envelope is unchanged. For the 18 action tools, structuredContent is intentionally breaking: legacy fields and action-specific output types are removed. SDK callers migrate from result.verified to result.action.effect; postcondition callers use result.verification.status. Daemon and SDK must be upgraded together because 0.15 clients fail closed on 0.14 action payloads.

This PR now targets main directly and includes the internal action-truth layer that previously lived in #2711. Its prerequisite verification work landed through #2705 before this branch was rebased.

Review

Claude Code Fable reviewed the complete design and implementation and returned safe after fixes. Its two release blockers are covered here:

• Windows PostMessage text is confirmed only when read-back changed and contains the complete requested text.
• browser refusal telemetry recognizes ActionResult.effect == refused and recovers only the closed refusal code from preserved diagnostic text, without retaining prose or widening the result schema.

Validation

Current head: 0d164592bdd003190a94e6d55c5d9c228eedfa80.

• all current GitHub checks pass at the exact head, including Linux and Windows Rust suites, Nix, portable contract parity on Ubuntu/macOS/Windows, generated SDK bindings, Python, TypeScript/packages, documentation, packaging, and release metadata
• cargo test -p cua-driver-core --lib (462 passed)
• cargo test -p cua-driver-contract (26 library tests plus generator test)
• cargo test --locked -p cua-driver-sdk (44 unit tests plus runtime coverage)
• cargo test --locked -p cua-driver-testkit (47 library tests plus report tests)
• cargo test --locked -p cua-driver-core --test contract_parity
• cargo test --locked -p cua-driver --all-targets --no-run
• generated manifest, UniFFI bindings, public C header, Python loader/package, TypeScript, computer-server, and generated documentation checks
• cargo fmt --all -- --check and git diff --check

macOS Lume certification

• Full canonical matrix at production head aae5cde0dfd1a6694a1991bcb78c842a10144339: 152/152 passed — 144 delivered outcomes, 8 expected fail-closed refusals, 0 failures, 0 skips.
• The only subsequent commit is a test-only correction aligning the standalone stale-ref assertion with the new narrow contract.
• Focused exact-current-head rerun on Chrome 150.0.7871.187: macos-chrome-standalone-browser_ref_stale passed with fixture-state, focus, z-order, cursor, leaked-input, video, and trajectory evidence.

The optional standalone-Chrome audit also exposed an inherited main issue unrelated to this contract change: current macOS Chrome includes the complete notification permission prompt in window capture while the capability still declares browser chrome unobservable. That pre-existing coverage contradiction is tracked in reopened #2589; it is not hidden or counted as a #2713 pass.

The Lume evidence used macOS 26.5.2 under Quartz/WindowServer. Requested source SHA, environment source SHA, browser provenance, and the focused exact-head result all match the revisions stated above.

[github-actions]

📦 Publishable packages changed

This comment is status-only. Editing it or adding task-list checkboxes cannot authorize a release.
Only owner-applied release:<service> labels can do that.

• ⏸️ pypi/computer-server — no owner-authorized release label

Ask the release owner to apply release:<service> labels to auto-release on merge (+ optional bump:minor or bump:major, default is patch).
Or add no-release to skip.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 62.50000% with 6 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...n/computer-server/tests/test_cua_driver_handler.py	58.33%	5 Missing ⚠️
...uter-server/computer_server/handlers/cua_driver.py	75.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[github-actions]

📦 Publishable packages changed

This comment is status-only. Editing it or adding task-list checkboxes cannot authorize a release.
Only owner-applied release:<service> labels can do that.

• ⏸️ pypi/computer-server — no owner-authorized release label

Ask the release owner to apply release:<service> labels to auto-release on merge (+ optional bump:minor or bump:major, default is patch).
Or add no-release to skip.

[f-trycua]

Exact-SHA macOS certification completed for 0a79ee20c9406146c6cd8f31d7ef46d07aee5406.

• environment: macOS 26.5.2 (25F84), Quartz/WindowServer, logged-in Lume worker
• source provenance: requested SHA, environment source SHA, and SHA-derived Cargo namespace all match the PR head
• result: 152/152 cases passed
• outcomes: 144 delivered, 8 expected fail-closed refusals, 0 failed, 0 skipped
• coverage: AppKit, SwiftUI, Electron, Tauri, WKWebView, TextEdit, desktop scope, browser page route, AX/pixel targeting, background/foreground delivery, verify_state, and installed-app launch
• external oracles: fixture state, AX state, pixels, focus, z-order, real cursor, no leaked input, protocol checks, and per-case video/trajectory evidence
• permissions: source-built com.trycua.driver.local identity had Accessibility and Screen Recording grants
• environment preflight, report generation, and video capture all passed

GitHub CI is also fully green at this SHA across Linux, Windows, portable contract parity, generated SDK bindings, packaging, documentation, and Nix jobs. The PR remains draft until the prerequisite stack lands and is rebased for final release-SHA recertification.

[f-trycua]

Stack-rebase checkpoint: the two ActionResult commits were replayed cleanly onto #2711 head 68b6e7b776ffec5fd8302ff77b585437f28a6ac2. New PR head: f381c29999f6f0bfcce5570d33bd9c91568f09c9.

Fresh local validation on the rewritten head:

• cua-driver-core: 462 passed
• cua-driver-contract: 26 passed plus generator test
• cua-driver-sdk: 44 passed plus runtime-configuration coverage
• cua-driver-testkit: 47 passed plus report tests
• generated manifest check passed
• generated Python UniFFI binding check passed
• release-version parity, Rust formatting, and git diff --check passed

The PR remains draft. Its prior 152/152 Lume result is retained as historical evidence for the same patch before the stack rebase; exact-head recertification remains required after #2705 and #2711 land.

[github-actions]

📦 Publishable packages changed

This comment is status-only. Editing it or adding task-list checkboxes cannot authorize a release.
Only owner-applied release:<service> labels can do that.

• ⏸️ pypi/computer-server — no owner-authorized release label

Ask the release owner to apply release:<service> labels to auto-release on merge (+ optional bump:minor or bump:major, default is patch).
Or add no-release to skip.

[f-trycua]

Fresh stacked-head CI completed for f381c29999f6f0bfcce5570d33bd9c91568f09c9: all 37 checks completed with 35 successes, 2 intentional skips, and 0 failures. This includes Linux/Windows Rust builds, portable contract parity on Linux/macOS/Windows, generated bindings, Python consumers, docs, release metadata, packaging, and the full Nix matrix. The earlier 152/152 Lume result remains historical evidence only; after #2705 and #2711 land, this PR will be rebased to main and the canonical macOS Lume matrix rerun at the final exact SHA before review/merge.

[github-actions]

📦 Publishable packages changed

This comment is status-only. Editing it or adding task-list checkboxes cannot authorize a release.
Only owner-applied release:<service> labels can do that.

• ⏸️ pypi/computer-server — no owner-authorized release label

Ask the release owner to apply release:<service> labels to auto-release on merge (+ optional bump:minor or bump:major, default is patch).
Or add no-release to skip.

[github-actions]

📦 Publishable packages changed

This comment is status-only. Editing it or adding task-list checkboxes cannot authorize a release.
Only owner-applied release:<service> labels can do that.

• ⏸️ pypi/computer-server — no owner-authorized release label

Ask the release owner to apply release:<service> labels to auto-release on merge (+ optional bump:minor or bump:major, default is patch).
Or add no-release to skip.

[github-actions]

📦 Publishable packages changed

This comment is status-only. Editing it or adding task-list checkboxes cannot authorize a release.
Only owner-applied release:<service> labels can do that.

• ⏸️ pypi/computer-server — no owner-authorized release label

Ask the release owner to apply release:<service> labels to auto-release on merge (+ optional bump:minor or bump:major, default is patch).
Or add no-release to skip.

[f-trycua]

Recertification update for exact current head 0d164592bdd003190a94e6d55c5d9c228eedfa80:

• All required GitHub checks are green after the final push and PR-body refresh, including release metadata and contributor attribution.
• The full canonical Lume matrix at the production-equivalent parent aae5cde0dfd1a6694a1991bcb78c842a10144339 passed 152/152 (144 delivered, 8 expected refusals, 0 failures, 0 skips).
• The final commit changes only the stale-ref standalone assertion from the removed legacy refusal.code object to the narrow ActionResult contract plus retained diagnostic text.
• The exact-current-head focused Lume rerun passed macos-chrome-standalone-browser_ref_stale on Chrome 150.0.7871.187 with all declared oracles and video/trajectory evidence.

The broader standalone audit was intentionally not reported as fully green: it exposed a pre-existing macOS browser-chrome coverage contradiction in current main, now documented on reopened #2589 and assigned to @injaneity. That finding does not touch #2713's production paths, but it remains explicit release follow-up rather than being waived silently.