Skip to content

fix(cua-driver): answer a typed app_not_found refusal when launch_app finds no application on Linux - #8405

Draft
JMLX42 wants to merge 1 commit into
trycua:mainfrom
JMLX42:fix/launch-app-app-not-found-refusal
Draft

JMLX42 wants to merge 1 commit into
trycua:mainfrom
JMLX42:fix/launch-app-app-not-found-refusal

Conversation

@JMLX42

@JMLX42 JMLX42 commented Nov 20, 2026 •

Copy link
Copy Markdown

Summary

Problem this solves

On Linux, five launch_app failures leave as plain text, with no code. Three of them share one message prefix:

launch_app { name | launch_path }
 ├─ remote-debugging flag refused         → "Chromium remote-debugging flags moved …"   text only
 ├─ matched .desktop launcher fails       → "Failed to launch: …"   text only
 ├─ nothing by that name exists           → "Failed to launch: …"   text only   ◀ this PR
 ├─ xdg-open could not open               → "Failed to launch: …"   text only
 └─ task panic                            → "Task error: …"         text only

A caller cannot tell "nothing by that name exists" from "something was found and failed" without parsing the message. In the first case no process started, so it is a refusal.

What changed

That one case now answers a typed refusal. The text is unchanged; structuredContent is new:

launch_app { "name": "cua-no-such-application" }

isError:           true
text:              Failed to launch: 'cua-no-such-application' is not an executable on PATH and
                   matches no installed .desktop application. Call list_apps and round-trip its launch_path.
structuredContent: { "code": "app_not_found", "effect": "refused",
                     "name": "cua-no-such-application", "pid": null, "running": null }
  • Shape. launch_handoff_timeout_result in the same file already answers effect: "refused" plus a code, so this follows it. The {"status": "refused", "refusal": {...}} shape of other Linux tools does not appear in launch_app.rs.
  • Inputs. name and launch_path share one launch path, so both get the refusal. name in the structured content is the requested command.
  • Other failures. The four other rows of the tree above are unchanged.

When the refusal is given

Pseudocode of the new path, after the existing checks (no .desktop match, not a URL, not an existing path):

Pseudocode
unlaunchable_command_error(spawn_error, cmd, $PATH, installed):
    program = first whitespace token of cmd
    if  spawn_error.kind == NotFound              # direct spawn of cmd only
    and not names_installed_app(installed, cmd)
    and not program_may_exist(program, $PATH):
        return AppNotFound(cmd)                    # → launch_failure_result → typed refusal
    else:
        return plain error, same text              # → "Failed to launch: …" as today
Predicate Answers "may exist" (plain text kept) Answers "absent"
program_may_exist, program has a / the path exists, or try_exists fails with another error try_exists is Ok(false), NotFound or NotADirectory
program_may_exist, bare name a $PATH directory holds it, a probe fails with another error, or $PATH is unset no $PATH directory holds it (an entry that is a file holds nothing)
names_installed_app an entry's display name contains cmd, its desktop-file id or Exec basename equals cmd (these three ignore ASCII case), or its launch_path starts with the same program no entry matches

names_installed_app uses the criteria of match_installed_app without its uniqueness rule, so an ambiguous name keeps the plain text.

Results by case. Each row is a case of the new integration test:

Request Direct spawn error Result
absent name NotFound app_not_found
absent launch_path NotFound app_not_found
absent program with arguments: cua-definitely-absent --flag NotFound app_not_found
program on $PATH whose script interpreter is missing (as name, and as a multi-token launch_path) NotFound plain: the probe finds the program
program on $PATH without execute permission PermissionDenied plain
absent program, NUL byte in additional_arguments InvalidInput plain
URL, no xdg-open on $PATH NotFound from xdg-open, not from the direct spawn plain
name that two installed entries match — plain: may name an installed app
installed entry whose launcher program is missing: by name, by its list_apps launch_path, and by that launcher with other arguments NotFound plain: may name an installed app

Size of the change

libs/cua-driver/rust/
├── Cargo.lock                                     +1    cua-driver-testkit
└── crates/platform-linux/
    ├── Cargo.toml                                 +1    cua-driver-testkit (dev-dependency)
    ├── src/tools/launch_app.rs                    +167 −7
    │     invoke                       binds spawn_error; replaces the bail!; maps the Ok(Err(e)) arm
    │     AppNotFound                  error type; Display is the old text
    │     program_may_exist            the path / $PATH probe
    │     names_installed_app          the installed-application check
    │     unlaunchable_command_error   the classification above
    │     launch_failure_result        AppNotFound → typed refusal, else plain text
    │     app_not_found_result         the refusal
    │     unit test                    a_program_may_exist_by_path_or_in_a_search_path_directory
    └── tests/launch_app_missing_application.rs    +363  new test binary, 2 tests

Known limits

app_not_found means "the driver's own resolution found nothing", not a proof of absence. What remains:

  • The installed-application check compares launcher paths as strings, so /opt/acme/./editor is not recognized as /opt/acme/editor.
  • The first token stands for the program, so a runner command such as flatpak run org.acme.Editor is judged by flatpak.
  • Desktop-entry discovery reads only the direct children of applications/, and skips a .desktop file or directory it cannot read without saying so (existing behavior in installed_apps.rs, unchanged here); a match there can be missed.
  • Names are tokenized on whitespace, so a name such as My Editor is judged by My.
  • With no PATH set, a bare program is never classified (the default search path then differs between C libraries).
  • The probe runs after the spawn, so a file that appears or disappears in between can misclassify one launch.

Related work

RFC: not opened

.github/CONTRIBUTING.md asks for an RFC when a change affects a public MCP contract. This PR adds a code to the structured content of an existing error result: no new tool, parameter or input schema, and no change to a successful result. Precedents:

PR Change RFC
#3882 added launch_handoff_timeout "RFC: not opened yet"; merged with none linked (a reviewer asked)
#4856 added the browser_field_needs_keystrokes refusal no RFC line
#8377 added an existing optional field to more results "RFC: not needed"

Questions for the maintainers:

  1. Should app_not_found mean "the driver's resolution found nothing" (this PR, with the limits above), or a stronger guarantee of absence that would need a different resolution?
  2. Do you want an RFC for this new caller-visible code? I will write one if so.

Compatibility and risk

  • User-visible, API/CLI/MCP, migration, permission, or platform impact: Linux only. launch_app for an unknown name now also carries structuredContent with a code; isError and the text are as before.
  • Risk and rollback: low; a single revert restores the plain-text error.

Validation

Focused tests and checks

tests/launch_app_missing_application.rs  on the unpatched launch_app.rs  → FAIL  (no structuredContent)
                                         after the change                → PASS

The integration test drives launch_app through the tool registry. It asserts the whole structured object for the three app_not_found rows of the table above. For the other rows, it asserts the exact previous text and no structured content.

What the fixture isolates from the host:

Host input In the test
desktop entries XDG_DATA_HOME, XDG_DATA_DIRS → a private data/
programs PATH → a private bin/
home and state directories the testkit's IsolatedStateRoot
working directory a private work/; PATH, the XDG directories and each launcher command are relative to it, so the test also passes with a space and a colon in TMPDIR
display DISPLAY, WAYLAND_DISPLAY unset
authorization permission mode, capability manifest and policy file variables unset

The fixture restores the environment and the working directory on drop. Before each case, the test spawns the program directly and asserts the spawn error kind that the case relies on. If the filesystem cannot produce it (for example a noexec mount), the test fails with a message that names the filesystem. The missing-interpreter case is its own test, so such a mount fails only that test.

The unit test of program_may_exist covers, with temporary directories: a present and an absent program, by name and by path; a $PATH entry that is a file; a directory without search permission (asserted only where the platform makes try_exists fail there); and no search path.

Commands:

Environment Command Result
rust:1.97.1 + the packages of linux-rust-prep cargo test --locked -p platform-linux --lib 1120 passed, 16 ignored
same cargo test --locked -p platform-linux --tests passed
same cargo fmt --all -- --check passed
same cargo clippy --locked -p platform-linux --all-targets -- -D warnings passed
full checkout + Node + pnpm bin/ci (affected mode, not --quick) 10/10 selected checks passed on the previous revision¹
— bin/ci --signoff not run

¹ SPDX headers, rustfmt, image refs, cargo lockfiles, Windows cfg grep, clippy with the reverse dependencies it selects, platform-linux unit tests, the generated docs reference, the UniFFI bindings check. The last revision changes only the fixture of the integration test; on it, only the four cargo commands above ran.

Manual or platform evidence

None beyond the tests.

Known gaps or CI still required

No local-ci sign-off. The GitHub CI jobs (the X11/Wayland desktop lanes, the Windows and macOS builds) have not run.

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. (Left to the maintainers; see the RFC note 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. (Not applicable: this is a fix.)
  • bin/ci is green and signed off (bin/ci --signoff). (bin/ci was green on the previous revision; not rerun on the last, and the sign-off is not done.)

🤖 Written by Claude Code (2.1.317) using model claude-opus-5-5

… finds no application on Linux

When the name is neither an executable on PATH nor an installed .desktop
application, the Linux launch_app ended as a plain-text error with no
code, on the same path as a remote-debugging flag, a launcher that does
not start, an xdg-open failure and a task panic. Answer a refusal with
code app_not_found and effect refused instead, in the shape of
launch_handoff_timeout. The message text is unchanged and the other
failures are untouched.

🤖 Written by Claude Code (2.1.317) using model claude-opus-5-5
@f-trycua

Copy link
Copy Markdown
Collaborator

Thanks for the fix. We'll review it. The CI checks on fork PRs need a maintainer to start them, so they may show as waiting until then.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants