Skip to content

refactor(linux): close the Linux plugin review follow-ups - #4948

Merged
thymikee merged 4 commits into
0.22from
refactor/0.22-linux-followups
Nov 22, 2026
Merged

thymikee merged 4 commits into
0.22from
refactor/0.22-linux-followups

Conversation

@thymikee

@thymikee thymikee commented Nov 22, 2026 •

Copy link
Copy Markdown
Member

Summary

Part of #4878.

The composition is the only producer of PlatformHost, and it always provides the managed process
service and the detached launcher. Both were optional, so Linux refused open with
host-launch-unavailable and HarmonyOS refused to stream hilog on a facet no request can produce.
Both are required now; both refusals are gone.

The detached-exit shape was declared three times and had drifted on signal. One declaration in
@agent-device/contracts/platform-runtime-host now serves the plugin contract, the Linux provider
contract and the host's exec module.

Every Linux provider part a plain request reads is mandatory, so the family stops dereferencing
optional parts with !. which answers through the host's PATH probe and the shipped AT-SPI helper
through a new isFilePresent. The runtime resolves the request's provider once per binding. Linux no
longer claims React Native helpers are unavailable. Left open: the request-scoped provider has no
producer, which needs its own decision.

Value

Measure base head
exit declarations / refusals 3 / 2 1 / 0
optional parts / ! uses 3 / 5 0 / 0
reads off PlatformHost 1 0
command-runner.ts lines 116 83

Validation

Tested at e8a0af4272 on base 64f963ab45: typecheck, lint, format, test:unit (22151 tests),
provider scenarios (318, Linux desktop included), and the layering, DI-seam, fallow, package, docs and
capability-matrix checks pass. No device lane applies — nothing drives a live device — and the packaged
Linux smoke proves the helper resolves.

Risk: apiVersion stays 3 while PlatformHost gained a required member, so a third-party plugin that
built its own host stops compiling; 0.22 has no shim.


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

View guided diff Turn on auto-fix

…lpers

The Linux command boundary listed React Native helpers as unavailable. The command runs wherever
tapping runs and answers `detected: false` on a surface with no overlay, which the React Native
overlays section and the capability matrix already state. The section now says that instead, and
drops the `host-launch-unavailable` refusal its host no longer makes.

The package homepage anchored a heading the page no longer has.
…lare their exit once

The plugin host the composition builds always provides the managed process service and the detached
launcher, so `PlatformHost` makes both required and the families stop carrying refusal branches for a
host facet they can never meet: Linux refused `open` with `host-launch-unavailable` and HarmonyOS
refused to stream `hilog`. A host that cannot start a process is a composition bug, not an answer a
plugin serves.

How a detached process ended was declared three times: by the plugin contract, by the Linux provider
contract, and by the host's own exec module, the last two drifting on `signal`. It is declared once in
`@agent-device/contracts/platform-runtime-host`, which all three read. The published plugin
declarations still inline it, so writing a plugin needs no Node type packages.

A plugin that ships a helper beside its own code had no host probe for it: the executable probe is the
wrong question for a non-executable resource, so `isFilePresent` is the right one, and the Linux
family reads its AT-SPI helper through it rather than through its bundle's copy of the host kit.

`which` now answers through the host's own PATH probe instead of walking `PATH` over the executable
probe, so a probe and the spawn it authorizes read one host primitive.
The Linux interactor reads the capture, clipboard and screenshot parts on a plain request, so
optional ones only moved the failure from a caller's type error to a `TypeError` at the family's
`!` dereference. Each part the interactor reads is now required, and `input` stays optional because
the family's own synthesis answers for it.

The runtime resolved the request's provider and passed it to the surface capture, which resolved the
same question again. The binding resolves it once and the capture takes the answer.
@github-actions

github-actions Bot commented Nov 22, 2026 •

Copy link
Copy Markdown
Contributor

Size Report

Metric Base Current Diff
Installed (including dependencies) 6.08 MB 6.08 MB +1.1 kB
Package (unpacked) 6.08 MB 6.08 MB +1.1 kB
Package (download) 1.86 MB 1.86 MB +420 B

Startup median (7 runs, lower is better):

Scenario Base Current Diff
CLI --version 19.5 ms 19.3 ms -0.2 ms
CLI --help 39.1 ms 38.7 ms -0.4 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 e8a0af4. The verdict and the full list are in the summary comment.

@apex-sentinel-staging

Copy link
Copy Markdown

Apex Sentinel · ✅ Approve · review of 099d418

Since the review of e8a0af4: 0 new · 0 still open · 2 no longer raised (2 marked fixed)

No open findings.

1 new finding away from what changed since e8a0af4 not shown. Comment @apex-sentinel-staging review for a full review.

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

💬 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

The code at 099d418 is ready. CI is green, with 19 checks and none failing, and there are no conflicts.

Not blocking, and they can be taken or left: the absent-helper probe keeps a present: false answer for the life of the setup, so a helper that appears later is still reported as TOOL_MISSING until restart; the PATH fake accepts any directory, while production checks the exact absolute path; and the React Native overlays text still says dismiss-overlay works only on iOS and Android, while the new Linux section says it runs on Linux and answers detected:false. These fit a follow-up issue.

Both earlier high-priority threads are fixed at this commit, so the author can resolve them: TOOL_MISSING carries details.path again and a rejected probe clears the cache. No lower-priority threads still apply.

Not verified here: the tests and the packaged Linux smoke were not run locally, the built plugin .d.ts output was not checked for the DetachedCommandExit and DetachedCommandLaunch claim, and no live Linux desktop run was done. The touched helper probe, PATH probe and detached launch paths were compared with base by reading the code and look equivalent.

@thymikee thymikee added the ready-for-human Valid work that needs human implementation, judgment, or maintainer merge label Nov 22, 2026
@thymikee
thymikee merged commit e8adbb8 into 0.22 Nov 22, 2026
19 checks passed
@thymikee
thymikee deleted the refactor/0.22-linux-followups branch November 22, 2026 09:17
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