fix(cua-driver): background refusals recommend unavailable foreground on Hyprland

Open
#7,900 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
1-2 days
Newbie friendliness
56/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
rust

Research direction

Read libs/cua-driver/rust/crates/platform-linux/src/tools/press_key.rs and trace the refusal paths into platform-linux/src/input/delivery.rs, cua-driver-core/src/delivery.rs, and cua-driver-core/src/recovery_hint.rs. Check how Hyprland plugin availability is determined in platform-linux/src/wayland/hyprland_input.rs; then compare background refusal guidance when the plugin is absent with foreground guidance when a supported route exists. Done means the unavailable case no longer recommends foreground retry while valid consent conditioned recovery guidance remains.

Written by the indexing model from the issue text.

Description

Summary

On a native Hyprland session without the optional input plugin, a window-targeted background key refusal recommends foreground delivery even though that retry immediately refuses because the plugin is unavailable. This sends agents through a recovery step that cannot work in the current configuration, and can prompt unnecessary requests for permission to bring the window forward.

Primary area

Cua Driver

Steps to reproduce

These are the supplied runtime case, corroborated by tracing the same branches in the current source; the current release binary was not rerun.

  1. Use a Hyprland Wayland session without the Cua input plugin, with CUA_DRIVER_RS_ENABLE_WAYLAND=1. Leave CUA_DRIVER_EXPERIMENTAL_HYPRLAND_INPUT and CUA_INJECT_SOCKET unset so neither the experimental input protocol nor a nested compositor substitutes another route.
  2. Open a small native PyGObject GTK 3 window with an entry containing abc, leaving the window on a hidden workspace. Launch it with env -u NO_AT_BRIDGE if necessary so its accessibility tree is available. Through an authorized Driver session, use list_windows and get_window_state to obtain and read its actual pid and window_id.
  3. Call press_key with that session, pid, window_id, and key:"x", omitting delivery_mode, element tokens, and coordinates. Observe the background refusal and foreground recommendation. The supplied MCP run also observed this with hotkey and keys:["ctrl","a"].
  4. Repeat the same press_key call with delivery_mode:"foreground". Observe the plugin-unavailable refusal instead of the promised recovery.

Expected behavior

Recovery advice should name only routes supported in the current situation. When foreground input is unavailable because the Hyprland plugin is absent, the background refusal should explain that limitation rather than recommend an immediate foreground retry. Keep the action refused and preserve the user's focus; this report does not ask to add a new input backend or bypass authorization.

Actual behavior

The supplied CLI run exited 1 on each call. Selected fields from the background result:

{
  "code": "background_unavailable",
  "detail": "the requested target has no focus-free input backend; the remaining input route can only deliver to the globally focused widget",
  "escalation": {
    "reason": "background input is unavailable on this surface; retry this action with delivery_mode:\"foreground\".",
    "recommended": "foreground"
  },
  "suggestion": "Retry this action with delivery_mode:\"foreground\"."
}

The MCP result was isError:true; its final recovery hint also advised Retry with delivery_mode:"foreground" only if the user allows the window to come forward. The foreground CLI result contained:

{
  "code": "foreground_unavailable",
  "reason": "unsupported_operation",
  "detail": "production Hyprland input plugin is unavailable",
  "effect": "refused"
}

The MCP retry likewise returned isError:true with foreground_unavailable (unsupported_operation): production Hyprland input plugin is unavailable. The supplied verification recorded no focus or workspace change and the entry still contained abc.

Runtime or environment

  • Supplied executed baseline: checksum-verified Linux x86_64 Cua Driver 0.49.11, Omarchy/Arch Linux, kernel 7.2.15, Hyprland 0.56.2 on Wayland, native PyGObject GTK 3 fixture; hyprctl plugin list returned no plugins loaded.
  • Current default branch inspected in a fresh clone: main at 3f1661d00f382145720dea568ccde58b993fc0f0.
  • Latest published non-nightly Driver release inspected: cua-driver-rs-v0.52.3, release target e7d713b28f7a8f7102cf7b15f567efb46f300beb. The relevant Linux key routing, refusal builder, shared escalation builder, and recovery-hint files have no differences from the inspected default branch. Current-source verification was static; no current binary runtime reproduction is claimed.

Evidence

  • Expected source: The Recovery hints contract states that every hint names only routes supported in that situation and explains when nothing will work.
  • Failure source: Supplied saved CLI/MCP transcripts, excerpted above, plus the current-source reachability trace below.
  • Evidence provenance: supplied
  • Local verification: static-proof
  • Reproduction completeness: complete

The executed background/foreground refusal pair came from the supplied saved verification run; the current branch and release-tag comparison were independently inspected. Runtime reproduction was not run for either current artifact. The concrete static trigger is a previously read native GTK window on opted-in Hyprland, no input-plugin socket, no experimental protocol, no nested injection, and a window-targeted press_key with a valid single key.

For that trigger, platform-linux/src/tools/press_key.rs:212-299 skips isolated input because hyprland_input::enabled() is false, then returns a background refusal through the GTK guard or unavailable_wayland_focused_input_background. Both paths use platform-linux/src/input/delivery.rs:149-168, which unconditionally promises a foreground retry. cua-driver-core/src/delivery.rs:118-140 unconditionally sets escalation.recommended:"foreground", and cua-driver-core/src/recovery_hint.rs:872-954 adds the generic foreground advice. All paths are relative to libs/cua-driver/rust/crates/.

On the foreground retry, the background guards are skipped. platform-linux/src/tools/impl_.rs:3066-3070 selects the Hyprland foreground branch based on delivery mode and compositor; focus_hyprland_foreground at :3623-3635 then checks the same plugin availability and returns the observed refusal before activation. platform-linux/src/wayland/hyprland_input.rs:244-260 defines availability from the opted-in session, selected protocol, and owned input sockets. The failure is the recovery recommendation, not the intentional refusal to inject without a supported backend.

Restoration check

Repeat the window-targeted background key call with the plugin unavailable. It must still refuse without changing focus, workspace, or entry contents, but its structured escalation, suggestion, and MCP text/hint must no longer recommend an immediate foreground retry that the same configuration cannot execute. As a control, when a supported foreground route is available, legitimate foreground recovery guidance should remain available under its existing consent condition.

Workaround and additional context

Treat this key step as blocked rather than following the foreground recommendation. Element actions and menu/browser routes may serve other tasks, but were not verified as equivalents for this arbitrary keypress. No new input capability is requested.

References

  • https://github.com/trycua/cua/issues/2617 — closed guidance work established direct foreground retries instead of persistent activation; the remaining case here is when foreground itself is unavailable.
  • https://github.com/trycua/cua/issues/6711 — related refusal sequence on generic wlroots/labwc, but that report seeks foreground input support there; this report concerns incorrect recovery guidance on plugin-less Hyprland.

Submission checks

  • I searched for duplicate issues and active pull requests.
  • This issue describes a single problem.
  • I removed credentials, private data, sensitive screenshots, and vulnerability details from this public report.

Triage assessment

  • Impact level: P2
  • Assessment status: provisional
  • Impact basis: The saved runtime case and unchanged current routing show unusable recovery advice for affected Hyprland key calls. Wasted retries and unnecessary foreground-consent requests are consequential for agents; aggregate frequency and automation impact have not been measured.
  • Workaround status: available
  • Workaround basis: An agent can recognize the missing-plugin condition and report the key step as blocked without retrying or disturbing the user. This avoids the misleading recovery step; it does not provide otherwise unavailable key delivery.
Dominant language
Rust
Stars
32.3k
Forks
2.4k
Avg merge
4h 47m
Merged PRs (30d)
711

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from trycua/cua

All issues in trycua/cua

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.