Skip to content

refactor(linux): move Linux desktop automation into the managed platform plugin - #4872

Merged
thymikee merged 12 commits into
refactor/0.22-harmonyos-platform-pluginfrom
refactor/0.22-linux-platform-plugin
Nov 21, 2026
Merged

thymikee merged 12 commits into
refactor/0.22-harmonyos-platform-pluginfrom
refactor/0.22-linux-platform-plugin

Conversation

@thymikee

@thymikee thymikee commented Nov 21, 2026 •

Copy link
Copy Markdown
Member

Summary

Moves Linux desktop automation and the AT-SPI helper from the packed core into the managed platform plugin @agent-device/linux (packages/platform-linux). Without the plugin, --platform linux answers plugin-not-installed with its install command; unscoped devices and doctor skip the family, and doctor --platform linux reports a failing toolchain row. Commands, process launches and environment reads go through the PlatformHost from setup; atspi-bridge.ts still reads process.platform and the filesystem directly (#4878). Part of #4676. Stacked on #4857. The package stays private (#4866).

Value

metric base head
core files importing the Linux package 4 0
AT-SPI helper files in the packed core 1 0

Validation

Head rebased onto #4857 at de014dd8fb (on 0.22 62f24be4fd). Local: build, typecheck, lint, layering, command-docs, daemon-wire-compat, full vitest --project unit-core (20937 passed), check:package with the packed-plugin smoke. Live evidence is the hosted Smoke Tests (linux) lane (X11), which installs the plugin from a packed tarball. Not run: Wayland tools, registry install. Review follow-ups: #4878.


Autofix with [code]smith
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.

View guided diff Turn on auto-fix

@thymikee
thymikee marked this pull request as draft November 21, 2026 01:33
@github-actions

github-actions Bot commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Size Report

Metric Base Current Diff
Installed (including dependencies) 6.16 MB 6.13 MB -28.8 kB
Package (unpacked) 6.16 MB 6.13 MB -28.8 kB
Package (download) 1.88 MB 1.87 MB -9.5 kB

Startup median (7 runs, lower is better):

Scenario Base Current Diff
CLI --version 23.0 ms 23.4 ms +0.4 ms
CLI --help 41.5 ms 43.6 ms +2.1 ms

@apex-sentinel-staging

This comment has been minimized.

@apex-sentinel-staging apex-sentinel-staging Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apex Sentinel: 2 new findings on a2965fc. The verdict and the full list are in the summary comment.

@apex-sentinel-staging

This comment has been minimized.

@apex-sentinel-staging apex-sentinel-staging Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apex Sentinel: 2 findings moved to a new line on 87b50ae. The verdict and the full list are in the summary comment.

Comment thread packages/platform-linux/src/doctor.ts Resolved
@apex-sentinel-staging

This comment has been minimized.

@thymikee
thymikee marked this pull request as ready for review November 21, 2026 02:32
@thymikee

Copy link
Copy Markdown
Member Author

The change at 7711c47 is ready. All 38 checks pass on that commit, including the hosted Linux run that installed the packed plugin and ran the replay-linux and linux-command-evidence gates, and there are no conflicts. Nothing else must happen before merge.

Not blocking, and each can be taken or left: the doctor row in doctor.ts:49 should check the same any-of tool tables the provider uses, so a host with xsel and import is not warned; the PR body should say the base had no Linux toolchain row, because the installed-plugin row is new; the request-scoped Linux provider in linux-tool-provider.ts:56 has no production producer, so a follow-up could drive provider scenarios through a fake PlatformHost and keep the provider plugin-internal; the command lookup in command-runner.ts:88 could become one PlatformHost primitive built on host-kit whichCmd; the detached-exit shape is declared three times; launchDetached could be required, which removes a refusal the daemon never reaches; atspi-bridge.ts still reads process.platform and the filesystem directly, which the PR body says the plugin does not do; commands.md lists React Native helpers as unavailable although dismiss-overlay runs and answers detected:false; the package homepage anchor should be #linux-command-boundary; the provider is resolved twice in runtime.ts and surface-snapshot.ts; and the PR body could add core tarball packed and unpacked byte deltas for #4676.

The two open inline threads on the optional scoped provider (#4872 (comment)) and the doctor tool list (#4872 (comment)) still apply, and both are non-blocking.

Not verified here: any local check, the Wayland route (ydotool, wl-clipboard, grim), and install from the registry, because the package is private (#4866). Only the X11 hosted lane and the local-tarball install ran.

@thymikee thymikee mentioned this pull request Nov 21, 2026
1 of 10 tasks
@thymikee

Copy link
Copy Markdown
Member Author

Thanks. The non-blocking items and both open inline threads (r4649955241, r4649955244) are filed as #4878 (milestone 0.22); the PR keeps head 7711c47 so its green checks and review stay valid. The PR body now names the remaining direct process.platform/filesystem read in atspi-bridge.ts and drops the stale draft note. This PR merges after #4857, retargeted to 0.22.

@thymikee thymikee added the ready-for-human Valid work that needs human implementation, judgment, or maintainer merge label Nov 21, 2026
@thymikee
thymikee added this pull request to stack #4889 November 21, 2026 10:25
@thymikee
thymikee force-pushed the refactor/0.22-linux-platform-plugin branch from 7711c47 to 1c53cbd Compare November 21, 2026 11:39
@thymikee thymikee removed the ready-for-human Valid work that needs human implementation, judgment, or maintainer merge label Nov 21, 2026
@apex-sentinel-staging

This comment has been minimized.

@apex-sentinel-staging apex-sentinel-staging Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apex Sentinel: 2 new findings on 1c53cbd. The verdict and the full list are in the summary comment.

Comment thread packages/platform-linux/src/display.ts Resolved
@blacksmith-sh

This comment has been minimized.

@apex-sentinel-staging

This comment has been minimized.

@apex-sentinel-staging

This comment has been minimized.

@thymikee

Copy link
Copy Markdown
Member Author

This PR is ready. The code at 9e03d03 fixes the relative-target regression from the earlier review (#4872 (comment)), and the doctor row now reads the provider's tool tables. All 33 reported checks pass, and no conflicts are known.

Not blocking: on Wayland the doctor clipboard slot now needs only wl-paste, so a host without wl-copy passes the row and then fails clipboard write with a spawn error; listing the commands each candidate needs in LOCAL_CLIPBOARD_TOOLS would give the provider probe and the doctor one table. BARE_COMMAND_NAME in the Linux runner also repeats host-kit's bare-command rule, so one exported name-normalization helper could serve both. These can be taken or left.

Of the earlier inline threads, the optional-part ! dereferences (#4872 (comment)) are deferred to #4878 and still open. The other three are fixed at this commit and can be resolved: the doctor tool table (#4872 (comment)), the runner's NUL and bare-name check (#4872 (comment)), and the display env comment (#4872 (comment)).

Not verified here: a live Linux run. The unit tests through setupLinuxPlatform cover the changed lookup guard and doctor row, and CI including the Linux lanes is green. The earlier commits are unchanged apart from a context line in commands.md, so they were not re-reviewed.

@thymikee thymikee added the ready-for-human Valid work that needs human implementation, judgment, or maintainer merge label Nov 21, 2026
…orm plugin

The packed core no longer answers for the Linux family. `@agent-device/linux` is a
managed optional platform plugin like the web, Vega and HarmonyOS plugins: the
composition resolves it through the same one-shot module selection, and a request
that names `--platform linux` without it answers `plugin-not-installed` with its
install command, while unfiltered discovery and doctor skip the family.

The family's mechanics move with it. AT-SPI2 discovery and snapshotting, the X11 and
Wayland input, clipboard and screenshot primitives, app lifecycle, the toolchain
probe and the Python AT-SPI helper all live in the package now. Every command goes
through the `PlatformHost` the composition hands to `setup`, so the plugin reads no
process globals and starts no process on its own. Core keeps only the canonical
platform vocabulary and the request-provider gate for the family's selection.
The display detector, the desktop, clipboard and screenshot factories, and the AT-SPI
tree shape have no consumer outside the bundle that builds them, so they stop being
exported. The host-launch refusal reason is named by a typed table beside the refusal
rather than at the call site, and the host stub's recorder and answer queue are
extracted so the Linux and HarmonyOS stubs cannot read as one clone.
Both Linux device gates now stage the plugin into the shared validation store through
the additive workspace-plugin selection, so a lane drives the family the way a user
installs it. The smoke job packs the plugin and installs it through `plugins add`,
then prints the visible devices, doctor, open, snapshot, press, screenshot and close
replies of that install, and the helper path it verifies follows the file into the
package.
jscpd's native scan root named the helper's old top-level directory, which the move
removed, so the gate failed on a missing path instead of measuring the helper. The
Python clone probe follows it into the package.
The first hosted run of the plugin lanes reported three real problems:

- The plugin contract published the host exec module's detached-exit type
  into the bundle's declarations, so a consumer type-checking a plugin
  against `agent-device/plugins` needed Node's own type packages. The
  contract now declares that shape itself.
- The packed-plugin smoke asserted the plugin was `active` from a daemon
  record written before `plugins add` ran, and its Linux-only half
  asserted a tool-call transcript the implementation never produces. The
  activation check now follows a scoped doctor that starts the daemon,
  and the transcript is derived from the routes the family selects:
  xdg-open, the shipped AT-SPI helper with the bridge's limits, scrot,
  the probed X11 pointer sequence, and the wmctrl close. The helper's
  recorded argv must name the copy inside the installed package.
- Both Linux gates now share one plugin store: the smoke job installs the
  packed plugin into the store the gate action stages the replay pair
  into, whose selections merge, so the daemon each gate starts carries
  all three packages, and no lane needs the workspace staging script to
  learn a new package.
The packed-plugin smoke ran its Linux half on the Ubuntu job for the
first time at 87b50ae. Every command reply it asserts matched; the
captured transcript shows the snapshot reads the frontmost app after an
open bound that session, not the whole desktop. The clipboard evidence
row kept the retired test name when the suite moved onto the host-bound
stub, so the Linux coverage lane could not find its owner file's test.
@thymikee
thymikee force-pushed the refactor/0.22-linux-platform-plugin branch from 9e03d03 to d8921e2 Compare November 21, 2026 13:35
@apex-sentinel-staging

This comment has been minimized.

@apex-sentinel-staging apex-sentinel-staging Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apex Sentinel: 1 new finding on d8921e2. The verdict and the full list are in the summary comment.

Comment thread scripts/check-package.ts Resolved
@thymikee thymikee removed the ready-for-human Valid work that needs human implementation, judgment, or maintainer merge label Nov 21, 2026
@apex-sentinel-staging

This comment has been minimized.

@thymikee

Copy link
Copy Markdown
Member Author

The dead linux-provider-host-unbound marker is now removed at check-package.ts:75 in ced6020, so that inline thread can be resolved: #4872 (comment).

One docs promise is still wrong at commands.md:628. With the Linux plugin absent and an existing Android session named android-check, agent-device doctor --session android-check --platform linux is admitted, because doctor skips session selector validation. The inventory honors --platform linux and records the missing plugin in the device row. But session-doctor.ts:89-91 lets the existing session pick the toolchain platform, so the toolchain row comes from Android and the promised Linux row is missing. An in-memory probe of the head handler confirmed the platform passed to the toolchain check. An agent that follows the new Linux instructions can get Android diagnostics when it asked for the Linux plugin check. Please limit the promise to a sessionless doctor call and state that a bound session supplies the toolchain platform.

The nightly build (run 44910604175) is still running, so CI is pending and not failed. Its pack and verify step covers @agent-device/linux and scripts/check-package.ts, but the change since the earlier review is only a JSDoc restore and a marker deletion, and no failure log exists to attribute. Not verified here: the build outcome, and the author's pnpm run check:package pass, because it was not rebuilt or re-run. No conflicts are known. The next step is to fix the docs line and wait for the build to finish green.

@thymikee

Copy link
Copy Markdown
Member Author

Fixed at 20877d4 (reply to #4872 (comment)). commands.md now reads: "Commands that name no platform, such as devices and a doctor call with no --platform and no session, skip Linux. A doctor call bound to a session takes the toolchain platform from that session's device." Thread r4652812409 is resolved. check:command-docs and check:doc-prose pass.

@apex-sentinel-staging

This comment has been minimized.

@thymikee

Copy link
Copy Markdown
Member Author

The earlier docs finding on session-bound doctor in commands.md is fixed at 20877d4, but one docs claim is still wrong. The installation page says a command that names --platform linux fails with details.reason=plugin-not-installed. With the plugin absent and no session bound, agent-device doctor --platform linux --json instead returns ok=true and exit 0. The typed reason sits in data.checks[].evidence.reason on a failing toolchain row (session-doctor.ts, platform-runtime-host-diagnostics.ts), and package-smoke.mjs already tells it apart from devices and open. Automation that follows installation.md and checks the exit code or error.details.reason will miss the missing-plugin diagnosis from doctor; commands.md repeats the same blanket claim. Please scope the command error to commands such as devices and open, and state in both pages that doctor reports the reason in its toolchain row when the effective toolchain platform is Linux.

The inline thread on the session-bound doctor rule in commands.md is fixed at this commit and can be resolved: #4872 (comment)

The latest change is docs-only, so the rest of the PR was not re-reviewed. All 33 checks pass, and there are no conflicts. Nothing else is needed before merge once the docs are corrected.

@thymikee

Copy link
Copy Markdown
Member Author

Fixed at ffb147d (reply to #4872 (comment)). installation.md and commands.md now scope the plugin-not-installed error to commands such as devices and open, and state that doctor does not fail: when its toolchain platform is Linux, the toolchain row in data.checks carries evidence.reason: plugin-not-installed. check:command-docs and check:doc-prose pass.

@apex-sentinel-staging

Copy link
Copy Markdown

Apex Sentinel · ✅ Approve · review of ffb147d

Since the review of 20877d4: 0 new · 0 still open · 0 no longer raised

No open findings.

Not in the reviewers' prompt (13 files)
  • .github/workflows/linux.yml: left out as an asset or for its size; reviewers could still search it
  • .jscpd-native.json: left out as an asset or for its size; reviewers could still search it
  • package.json: left out as an asset or for its size; reviewers could still search it
  • packages/contracts/package.json: left out as an asset or for its size; reviewers could still search it
  • packages/platform-linux/package.json: left out as an asset or for its size; reviewers could still search it
  • packages/platform-linux/src/__tests__/interactor-host-isolation.test.ts: left out as an asset or for its size; reviewers could still search it
  • packages/platform-linux/src/accessibility-types.ts: left out as an asset or for its size; reviewers could still search it
  • packages/platform-linux/src/input-tool.ts: left out as an asset or for its size; reviewers could still search it
  • packages/platform-linux/src/interactor-facade.ts: left out as an asset or for its size; reviewers could still search it
  • packages/platform-linux/tsconfig.json: left out as an asset or for its size; reviewers could still search it
  • pnpm-lock.yaml: generated or a lockfile, so its lines were left out
  • scripts/layering/contracts-exports.snapshot.json: left out as an asset or for its size; reviewers could still search it
  • website/docs/docs/commands.md: left out as an asset or for its size; reviewers could still search it

2 findings below minor hidden (user_settings.min_severity).

Reviewed with this repository's own Sentinel configuration (721adbc6985f).

💬 Talking to Sentinel

In a finding's thread, reply with:

Command What it does
@apex-sentinel-staging note <context> Adds context; Sentinel re-checks the cited code
@apex-sentinel-staging pivot <why> Says the finding is wrong; Sentinel re-checks the cited code
@apex-sentinel-staging like Marks the finding as useful
@apex-sentinel-staging dislike <why> Marks it as not useful, so it is not raised again

On this conversation, comment @apex-sentinel-staging review to run a full review once again.

@thymikee

Copy link
Copy Markdown
Member Author

Commit ffb147d has no remaining problems in the code. The findings from the earlier review at 20877d4 (#4872 (comment)) are fixed, and the change since then is docs only. All 33 checks pass. No conflicts. Nothing else must happen before merge. Not verified here: check:command-docs and doc-prose were not run, so the docs rely on the author's statement and green CI. Not verified here: a live doctor --platform linux run without the plugin, so that path was only traced in the code.

@thymikee thymikee added the ready-for-human Valid work that needs human implementation, judgment, or maintainer merge label Nov 21, 2026
@thymikee
thymikee merged commit 9a12ab0 into 0.22 Nov 21, 2026
33 checks passed
@thymikee
thymikee deleted the refactor/0.22-linux-platform-plugin branch November 21, 2026 16:32
thymikee added a commit that referenced this pull request Nov 21, 2026
…orm plugin (#4872)

* refactor(linux): move Linux desktop automation into the managed platform plugin

The packed core no longer answers for the Linux family. `@agent-device/linux` is a
managed optional platform plugin like the web, Vega and HarmonyOS plugins: the
composition resolves it through the same one-shot module selection, and a request
that names `--platform linux` without it answers `plugin-not-installed` with its
install command, while unfiltered discovery and doctor skip the family.

The family's mechanics move with it. AT-SPI2 discovery and snapshotting, the X11 and
Wayland input, clipboard and screenshot primitives, app lifecycle, the toolchain
probe and the Python AT-SPI helper all live in the package now. Every command goes
through the `PlatformHost` the composition hands to `setup`, so the plugin reads no
process globals and starts no process on its own. Core keeps only the canonical
platform vocabulary and the request-provider gate for the family's selection.

* refactor(linux): keep the plugin's internals inside the package

The display detector, the desktop, clipboard and screenshot factories, and the AT-SPI
tree shape have no consumer outside the bundle that builds them, so they stop being
exported. The host-launch refusal reason is named by a typed table beside the refusal
rather than at the call site, and the host stub's recorder and answer queue are
extracted so the Linux and HarmonyOS stubs cannot read as one clone.

* ci(linux): serve both Linux lanes from the installed platform plugin

Both Linux device gates now stage the plugin into the shared validation store through
the additive workspace-plugin selection, so a lane drives the family the way a user
installs it. The smoke job packs the plugin and installs it through `plugins add`,
then prints the visible devices, doctor, open, snapshot, press, screenshot and close
replies of that install, and the helper path it verifies follows the file into the
package.

* chore(gates): scan the AT-SPI helper where the plugin now keeps it

jscpd's native scan root named the helper's old top-level directory, which the move
removed, so the gate failed on a missing path instead of measuring the helper. The
Python clone probe follows it into the package.

* fix(linux): answer the hosted lanes the plugin actually gives them

The first hosted run of the plugin lanes reported three real problems:

- The plugin contract published the host exec module's detached-exit type
  into the bundle's declarations, so a consumer type-checking a plugin
  against `agent-device/plugins` needed Node's own type packages. The
  contract now declares that shape itself.
- The packed-plugin smoke asserted the plugin was `active` from a daemon
  record written before `plugins add` ran, and its Linux-only half
  asserted a tool-call transcript the implementation never produces. The
  activation check now follows a scoped doctor that starts the daemon,
  and the transcript is derived from the routes the family selects:
  xdg-open, the shipped AT-SPI helper with the bridge's limits, scrot,
  the probed X11 pointer sequence, and the wmctrl close. The helper's
  recorded argv must name the copy inside the installed package.
- Both Linux gates now share one plugin store: the smoke job installs the
  packed plugin into the store the gate action stages the replay pair
  into, whose selections merge, so the daemon each gate starts carries
  all three packages, and no lane needs the workspace staging script to
  learn a new package.

* test(linux): name the routes the Ubuntu package lane shows

The packed-plugin smoke ran its Linux half on the Ubuntu job for the
first time at 87b50ae. Every command reply it asserts matched; the
captured transcript shows the snapshot reads the frontmost app after an
open bound that session, not the whole desktop. The clipboard evidence
row kept the retired test name when the suite moved onto the host-bound
stub, so the Linux coverage lane could not find its owner file's test.

* fix(linux): look up only bare command names in the host PATH

* fix(linux): accept the provider's fallback tools in the doctor toolchain row

* fix(plugins): restore the launchDetached doc comment after the rebase

* chore(package): drop a Linux marker the plugin never emits

* docs(linux): scope the unscoped doctor note to a call with no session

* docs(linux): scope the plugin-not-installed error to commands that fail, and name doctor's evidence
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ready-for-human Valid work that needs human implementation, judgment, or maintainer merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant