Repository navigation
refactor(macos): ship macOS desktop automation as the managed platform plugin - #4933
Conversation
A platform claim key gains an optional leaf part, so a managed package can hold
`{ kind: 'platform', family: 'apple', appleOs: 'macos' }` while the bundled Apple
owner keeps the `apple` family claim for iOS and tvOS. Only `apple` narrows, and
only to macOS. The registry keeps a leaf setup apart from the family setups, and
the platform composition answers for the leaf through its own selection: an
absent package raises `plugin-not-installed` with the `@agent-device/macos`
install command.
Part of #4675
…rface
`@agent-device/macos` is a managed platform plugin that contributes the leaf
`{ kind: 'platform', family: 'apple', appleOs: 'macos' }`. Its `setup(host)`
registers `bind(tools)`, which returns every macOS operation the bundled Apple
owner delegates.
The Apple owner keeps the `apple` claim and gains a leaf port. The composition
binds the process's leaf selection to it, and the owner asks the port at its
macOS branches. An absent package answers typed `plugin-not-installed` with the
`@agent-device/macos` install command.
The owner hands the leaf two capabilities per call: the Apple tool routes of the
calling request, so a scoped request reaches the leaf and no command starts from
the plugin's bundled host kit, and the XCTest runner bound to one macOS device
for the runner's macOS wire cases.
Part of #4675
…nto the plugin The published core no longer contains the macOS desktop implementation. The `os/macos` sources (both app backends' macOS code, the desktop surfaces, the LaunchServices probe, the host routes and the helper client) and the `apple/macos-helper` Swift package move to `packages/platform-macos`, and the `@agent-device/platform-apple/macos` facade is removed. Every macOS branch of the bundled Apple owner now calls the installed leaf. The owner still assembles the native backend's interactor and still owns the one XCTest runner; the leaf maps a desktop scroll and an alternate click onto the runner's `desktopScroll` and `mouseClick` wire cases through the device-bound capability the owner hands it. The runner scroll normalization both share moves beside the scroll plan in contracts. The plugin runs each command through the Apple tools the owner resolved for the request, and takes the screen-capture lock, machine facts and diagnostics from the host its setup received. `PlatformHost.processes.withLock` gains a `signal` so a cancelled request stops waiting for a held lock, as it did in core. Unfiltered discovery lists this Mac only when the package is installed, and a macOS request without it answers `plugin-not-installed`. Host system audio sampling is the helper's, so the audio probe needs the package for every family. Part of #4675
The layering policy learns a managed leaf package: `packages/platform-macos`
holds `{ platform: 'apple', appleOs: 'macos' }` and obeys every rule a managed
family package obeys. The packed-core check refuses any macOS desktop path or
helper marker, and `check:package` gains the macOS package smoke.
The helper pack rules leave the core size report for a plugin-owned check, so
the core guard now refuses a helper path outright and exempts no test path.
Lane ownership, the native-dupes scan root, the eager-closure facade list and
the Fallow facade entry follow the files. The macOS smoke lane installs the
packed plugin before the replay gate, and the provider scenarios compose it.
Part of #4675
…tract with a total table
…described The `help macos` topic, the website command and installation pages, CONTRIBUTING and the device verification guide state that macOS desktop automation is the `@agent-device/macos` plugin and how a request without it answers. ADR 0034 records the leaf claim, the owner delegation and the two rejected alternatives. Part of #4675
… the extraction measurements `plugins list` prints `(apple macos)` for a package that holds the macOS leaf, so the listing does not read as a claim on the whole Apple family. The evidence note records the packed-core size against the 0.22 base and the live check. Part of #4675
…election Every platform composition bound the Apple owner's macOS leaf port, including the selection narrowed to the web family. That selection names no leaf, so it unbound an installed macOS leaf in the same process. The daemon composition and an unnarrowed installed-platform selection now bind explicitly, and composing a selection has no side effect on the owner. Part of #4675
Live check transcript (macOS host, Xcode 27.1, head
|
Size Report
Startup median (7 runs, lower is better):
|
This comment has been minimized.
This comment has been minimized.
There was a problem hiding this comment.
Apex Sentinel: 4 new findings on 68d339f. The verdict and the full list are in the summary comment.
|
Review of 68d339f: two problems must be fixed before merge. The release install-hint guard does not list Host audio capture for every family now goes through the macOS plugin (src/platform-runtime-audio-probe-host.ts:50). On a darwin host, The Ownership and context budgets check fails: docs/agents is 40143 bytes against the 40000 limit. It was 39940 bytes at the merge base, and the only change is the two lines added in docs/agents/device-verification.md:62-63 (+203 bytes). Trimming at least 143 bytes makes it pass. The two Body rules jobs show as cancelled by newer runs, not as failures. No conflicts are known. Not blocking, and fine to take or leave: the versioned help Audio block (cli-help-workflows.ts:110) and website/docs/docs/debugging-profiling.md:250 do not say the macOS plugin is now required, and The inline thread on the audio probe (discussion_r4654911495) still stands. Two lower-priority threads still apply. One thread does not apply and can be resolved: runtime.ts:236 throws only for a macOS device, and without the plugin no macOS device is discoverable, so the typed plugin-not-installed outcome is intended (discussion_r4654911484). Not verified here: packing of core or the plugin (the size numbers in the PR body were measured at 4dc93c9, not at this head), a local test run, a file-by-file comparison of the moved and deleted tests against their replacements, and the desktop, frontmost-app and menubar helper surfaces in a live run. The XCTest backend rests on the passing macOS smoke job. |
Under AGENT_DEVICE_MACOS_APP_BACKEND=native the admission-facts spread asked the macOS leaf for its native refusals, so a capability read raised plugin-not-installed for a Mac the process cannot drive. The backend is a daemon setting and listing facts is not a macOS call: ask the leaf only when it is installed, and keep the typed install outcome with the commands that need it.
The two readers that describe a slot whose load failed read the declared `appleOs` with the
leaf-tolerant reader, so `{ kind: 'platform', family: 'apple', appleOs: 'ios' }` came back as the
whole `apple` claim. The registry reserved that widened claim, and the next package that really
holds the family lost it as a duplicate. Both readers now refuse an un-narrowable leaf through the
one helper the validating path uses, and a refused slot records the refusal instead of a claim.
The ScreenCaptureKit sampler moved with the Swift helper, so a macOS session, iOS simulator, or Android emulator probe answers plugin-not-installed with no package installed. Say so in the audio help topic, the audio-probe and client API docs, and the capabilities generator, and pin the typed outcome with a host test.
|
The maintainer sign-off recorded on #4675 settles the audio probe item: the sampler stays in |
…dget The plugin note took docs/agents past its 40 000-byte total. State the instruction once and leave the install command to the user docs that own it.
…n the docs budget
|
Reply to #4933 (comment), head a938263:
|
Apex Sentinel · ✅ Approve · review of
|
| 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.
|
This PR is ready at a938263. The install-hint guard now covers the macOS declaration with a publishable package, and the docs/agents size check passes at exactly 40000 bytes. The earlier findings are fixed, and all 38 checks pass at this commit. No conflicts. Not blocking: the bare catch around readableClaimsOfValue in registry.ts drops every error and every readable claim of that value, so a failed plugin with a valid provider claim loses it in the inventory. It could catch only the typed invalid_plugin error, or drop only the refused claim. Take it or leave it. Not verified here: the release pack or pnpm pack of @agent-device/macos, and the npm placeholder and trusted-publisher setup for that package. Tests were not run locally; CI results are taken from the checks at this commit. The inline threads on the absent-leaf guard (#4933 (comment)), the readable-reader leaf check (#4933 (comment)) and the plugin requirement docs (#4933 (comment)) are fixed at this commit and can be resolved. The audio probe thread (#4933 (comment)) does not apply: the maintainer signed off that the sampler stays in the plugin, so it can be resolved too. |
|
Cleanup after merge: the worktree and the local branches |
Summary
Part of #4675. macOS desktop automation and its Swift helper leave the core for the managed plugin
@agent-device/macos(still"private": true).{ kind: 'platform', family: 'apple', appleOs: 'macos' }. The bundled Apple owner keepsappleand calls the installed leaf at its macOS branches.macos-helper. Core keeps the XCTest runner and gives the leaf a device-bound runner capability.--platform macosanswersplugin-not-installedwith the install hint, and unfiltered discovery omits the Mac.audio probeneeds the plugin: the sampler is the helper's.Size: 163 files, +3462 −1472. It exceeds the cap because the claim key, the leaf port, the move and its gates cannot merge separately, as in the Linux precedent.
Value
Clean builds,
npm pack --ignore-scripts, base80c44fe45eagainst4dc93c9ff8:macos-helperfiles in core: 11 to 0. Plugin tarball: 70,157 B.Validation
At
68d339fd2d, passing:pnpm lint,pnpm typecheck,pnpm format,pnpm check:layering,fallow audit --base origin/0.22,pnpm run check:package(13 smokes),pnpm check:command-docs,pnpm check:daemon-wire-compat, unit-core (21,099 tests), provider-integration (318 tests), Swift helper tests.Live check on a Mac (transcript in the first comment): the native backend flow passed. The default XCTest backend is blocked there: XCUITest Automation Mode is not authorized.
CI must still prove the macOS smoke lane, which now installs the packed plugin.
Open in [code]smith · Need help on this PR? Tag
@codesmith-botwith what you need.