CUA capability dispatch

Use the stock computer-use skill and driver for fresh observations and execution. This skill adds selection guidance, not an alternative driver or expanded action permission.

Read setup first to locate or install the runtime and configure providers. Read the bundled sketch for request semantics and policy. These references travel with npx skills installs; do not assume the runtime repository is next to the installed skill. The runtime checkout’s sketch is authoritative when available.

Use the installed task tools first

Prefer the registered cua-task MCP tools for supported Mac work. Start with cua_windows(title=...) when the window title is known, then cua_observe; use cua_read for requested fields from nonoverlapping observed record roots, cua_choose for contextual or genuinely exact selection, cua_act for its opaque selection handle, and cua_verify for a fresh postcondition check. End with cua_finish to release task workers; cua_trace exposes actual routes and bypass reasons.

The tool server owns Driver observations and arguments. Do not write temporary Python wrappers, construct synthetic singleton “exact” candidates, or instantiate an empty dispatcher to wrap a decision already made by the controlling LLM. Exact mode takes an observed name/role and checks uniqueness across the whole observed scope. The facade marks alias_of only for complete matching row/column table projections (all paired cell subtrees and frames must agree); these representations count once. Other duplicate controls stay ambiguous. Prefer canonical IDs when forming alternatives. When passing a NuExtract reading to selection, preserve all eligible records; use record_actions to associate each record root with a control inside that record when it has multiple controls. A reading stores its schema; additional predicates on cua_choose filter that cached evidence without another model read. candidate_ids may be the eligible record roots or mapped controls; omit it when record_actions supplies the mapping. Money fields require explicit currency: USD; use text for other price formats. Unknown or incomplete records cannot be silently dropped. Offer contextual alternatives to the configured chooser before choosing one yourself. Semantic singletons require a complete filtered reading; do not retry an ambiguous exact match by offering the chooser just your preferred control. Exact mode is for literal named controls, not disguising contextual reasoning as a lookup.

Raw Driver remains the explicit fallback for unsupported operations (currently keyboard shortcuts, browser-specific navigation, and canvas coordinates) or unavailable MCP transport. State the bypass reason, keep fresh binding and independent verification, and report actionable friction as an issue. Library recipes below support integrations; they are not the normal agent workflow when these tools are available. Setup and tool contract: docs/FACADE.md in the runtime checkout.

Before acting, keep the user's requested steps and prerequisites in order and identify the next unmet step. Preserve those constraints in contextual choice goals instead of reducing the task to whichever button seems convenient. Verify an observable result, not an assumed screen layout or an invisible intent. A status message may establish a functional outcome; explicitly require a modal or separate view only when the task needs one. The screenshot verifier checks every constraint against the relevant view rather than accepting text that merely appears elsewhere. cua_verify returns its fresh screenshot and element IDs: reconcile unknown results there before deciding whether a retry is justified. Do not repeat completed actions just because a later step failed.

Active stack

The default runtime profile is local-mac: Julia-1 contextual finite choice with no hosted fallback. The fleet profile opts into NuExtract3 page reading, Jev choice with configured Qwen escalation, GLiNER2 spans, and screenshot-capable SystemOne/Qwen. Local NuExtract3 and screenshot workers are not yet bundled; check local Mac support and treat unavailable capabilities as blockers. Create providers through generic_from_config(), never hardcode FleetGeneric() for the normal path. The factory and observation helpers automatically read ~/.config/computer-use/runtime.json; select {"profile":"fleet"} for the homelab setup. Preserve runtime credentials outside observations and source.