Skip to content

refactor(harmonyos): ship HarmonyOS as the managed platform plugin - #4857

Merged
thymikee merged 5 commits into
0.22from
refactor/0.22-harmonyos-platform-plugin
Nov 21, 2026
Merged

thymikee merged 5 commits into
0.22from
refactor/0.22-harmonyos-platform-plugin

Conversation

@thymikee

@thymikee thymikee commented Nov 20, 2026 •

Copy link
Copy Markdown
Member

Summary

Moves HarmonyOS from the packed core into the managed platform plugin @agent-device/harmonyos (packages/platform-harmonyos). Without the plugin, --platform harmonyos answers plugin-not-installed with its install command, and unscoped devices/doctor skip the family. Every spawn and diagnostic goes through the PlatformHost from setup; the plugin reads toolchain roots from the setup environment, not process.env. A layering rule bans runtime @agent-device/host-kit/command|diagnostics imports in managed platform packages. Part of #4317. The package stays private (#4866).

Value

metric base head
core installed size 6.20 MB 6.16 MB
core package download 1.89 MB 1.88 MB

Validation

Head rebased onto 0.22 at 62f24be4fd. Local: build, typecheck, lint, layering, command-docs, daemon-wire-compat, full vitest --project unit-core (20911 passed), check:package with the packed-plugin smoke (stub hdc via HDC_SDK_PATH). No live HarmonyOS target on this Mac: hdc list targets is empty and no emulator image exists; evidence in docs/evidence/harmonyos-managed-platform-2026-11-20.md. A live run or a maintainer waiver is required before merge.


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

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Size Report

Metric Base Current Diff
Installed (including dependencies) 6.20 MB 6.16 MB -36.3 kB
Package (unpacked) 6.20 MB 6.16 MB -36.3 kB
Package (download) 1.89 MB 1.88 MB -11.2 kB

Startup median (7 runs, lower is better):

Scenario Base Current Diff
CLI --version 20.1 ms 20.4 ms +0.3 ms
CLI --help 39.3 ms 39.6 ms +0.3 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: 1 new finding on ef1b664. The verdict and the full list are in the summary comment.

@thymikee

Copy link
Copy Markdown
Member Author

The packed HarmonyOS plugin at ef1b664 spawns hdc without the toolchain PATH, so it fails for users whose SDK root is not on PATH. Coverage is failing and its cause is not visible in the log that was retrieved, so CI is unclear. No conflicts were reported. Two things are needed before merge: the hdc fix below and a live run of the packed plugin.

packages/platform-harmonyos/src/hdc.ts:31: The plugin bundles its own copy of @agent-device/host-kit (deps.alwaysBundle matches /^@agent-device\//). runHarmonyHdc and runHarmonyShell call that copy's runCmd. Its commandHostScope and diagnosticsStorage are separate AsyncLocalStorage instances that the daemon's withCommandHost(...) never enters. So hdc inherits process.env instead of the captured host.env, which ensureHarmonyToolchainPathConfigured prepended the HDC_SDK_PATH, DEVECO_SDK_HOME and HARMONYOS_COMMAND_LINE_TOOLS roots to. Hdc exec traces and interactor timers also go to the plugin's own diagnostics store, not the request's. Impact: with hdc reachable only through an SDK root, devices --platform harmonyos works through the core inventory runner, but open, snapshot, press, screenshot, record and perf fail with a missing hdc. Base handled this, and installation.md:981 says it works. --debug logs also lose every HarmonyOS exec trace. Workspace tests resolve the plugin from src, where host-kit is one instance, and package-smoke only reaches TOOL_MISSING through core discovery, so no test covers this route. The rule to satisfy: every process the plugin spawns and every diagnostic it emits goes through the PlatformHost passed to setup(), never through a bundled host-kit scope. The 12 plugin modules that import @agent-device/host-kit/command or /diagnostics are the sites to cover, and the host already carries runCommand, emitDiagnostic and withDiagnosticTimer for this (plugin-host.ts:14). Enforce it in scripts/layering/platform-package-policy.ts for every MANAGED_PLATFORMS package. Validate with a packed-plugin test that runs an interaction command with a stub hdc reachable only through HDC_SDK_PATH.

Could the plugin own its toolchain PATH end to end? In setup(host), one HDC runner over host.runCommand could apply ensureHarmonyToolchainPathConfigured to a per-command env derived from host.env. That runner and host.withDiagnosticTimer would go to the inventory, runtime, interactor and recorder. Then HarmonyPlatformOperations.prepareToolchain, the core 'harmonyos' arm in createHostToolchainPreparer, and the harmony parameter threaded through createDeviceInventoryHost, createPlatformRuntimeHost and createHostToolchainPreparer could be deleted. HarmonyPlatformOperations would shrink to toolchainCheck, the same shape as Vega. That fixes the finding above and removes about 4 of the 6 core marker sites. Nothing has to change first for the HarmonyOS part. Merging web, vega and harmony into one family-keyed selection waits on #4597.

The one lower-priority open inline thread (the process.env restore in index.test.ts) still applies and is covered in the notes below.

Not blocking, and each can be taken or left: the two recorder tests were deleted rather than moved with recorder.ts (removal reported only after a confirmed HDC success, and stat -c %s size parsing), so moving them next to the recorder with ../hdc.ts mocked would keep that coverage; index.test.ts:473 assigns undefined back into process.env for unset roots, which Node stores as the string 'undefined', so deleting those keys instead would be safer; the 'nothing before the plugin is installed' test in platform-runtime-toolchain-host.test.ts:754 passes no selection, which production never does, so it could be dropped or rebuilt with composePlatformPlugins([], []).harmony asserting the typed plugin-not-installed rejection; the optional sampleMemory parameter of createHarmonyPerfOperations at perf/runtime.ts:850 is only used by a test, which could mock ../perf.ts instead; and the harmonyos entry in validate.ts:377 repeats the web and Vega operations scan, so one requireOperations(value, keys, message) helper could serve all three.

Also required before merge, as live evidence for a device-facing move: index.ts:643 moves all HarmonyOS device dispatch, interaction, lifecycle and capture into a separately bundled plugin, and no live run is attached. Install the packed plugin with agent-device plugins add ./harmonyos.tgz on a host where hdc is reachable only through HDC_SDK_PATH or DEVECO_SDK_HOME. Run devices --platform harmonyos, open <bundle>, snapshot -i, press @<ref>, screenshot and close, and capture each --json output plus one --debug log showing the hdc exec diagnostics under the request id. Commit the evidence under docs/evidence/ per #4317. An emulator is fine for every step except record.

Not verified here: the packed plugin was not built or run against a stub hdc, so the first finding is likely rather than confirmed. Not verified here: the unit and package-smoke tests were not run locally, and no HarmonyOS device was available.

@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 8ba31dc. The verdict and the full list are in the summary comment.

@thymikee
thymikee force-pushed the refactor/0.22-harmonyos-platform-plugin branch from 8ba31dc to 0c2188a Compare November 20, 2026 21:48
@thymikee

Copy link
Copy Markdown
Member Author

Rule: every process the plugin spawns and every diagnostic it emits goes through the PlatformHost passed to setup(), never through a bundled host-kit scope — fixed at 0c2188a.

The plugin now has one command route: src/command-host.ts builds createHarmonyCommandRunner(host) over host.runCommand, and each spawn carries an environment derived from host.env with the documented roots prepended to PATH (HDC_SDK_PATH, then DEVECO_SDK_HOME/default/openharmony/toolchains, then HARMONYOS_COMMAND_LINE_TOOLS/sdk/...). Diagnostics and timers go through host.emitDiagnostic / host.withDiagnosticTimer. All 12 sites are converted: screenshot, app-state, settings, input-actions, snapshot, keyboard band, app lifecycle, perf (and perf runtime), recording (recorder + runtime), logs runtime, deployment runtime, interactor, doctor, runtime and index. The bundle imports host-kit types only.

Two host ports had to be minted rather than reached for: resolveHdc/toolchainHdc on the command runner (so host-minted commands such as the hilog stream get an absolute HDC path), and PlatformHost.isFileExecutable (packages/plugins/src/platform.ts, implemented in src/platform-runtime/plugin-host.ts over host-kit isExecutablePath), because the root probe may not read the filesystem or process from inside the bundle.

Enforcement: scripts/layering/platform-package-policy.ts rejects a runtime (non-type) import of @agent-device/host-kit/command or @agent-device/host-kit/diagnostics from every MANAGED_PLATFORMS package, plus a stale-entry check on the register. Report, not fixed, as they were outside this change: web runtime sites agent-browser-install.ts, agent-browser-lifecycle.ts, agent-browser-process-record.ts, agent-browser-provider.ts, agent-browser-tool.ts, interactor.ts; Vega runtime sites app-lifecycle.ts, input-actions.ts, inventory.ts, tool-provider.ts, vega-executable.ts. Same bundled-copy fault, so they need the same host threading when their family is next touched.

Validation: packages/platform-harmonyos/test/package-smoke.mjs now installs the packed plugin, writes a stub hdc into a scratch HDC_SDK_PATH root asserted off PATH, restarts the daemon with that env, and runs devices → open → press 100 200 → close, asserting each reply plus the argv and PATH the stub recorded for every call (pnpm run check:package runs it). A --debug trace with the exec_command record under the request id is in docs/evidence/harmonyos-managed-platform-2026-11-20.md.

@thymikee

Copy link
Copy Markdown
Member Author

Simplification question (could the plugin own its toolchain PATH end to end?) — taken, at 0c2188a.

setup(host) now owns it: one HDC runner over host.runCommand applies the root overlay to a per-command env derived from host.env, and host.withDiagnosticTimer plus that runner go to the inventory, runtime, interactor and recorder. Deleted along the way: HarmonyPlatformOperations.prepareToolchain, the 'harmonyos' arm in createHostToolchainPreparer (the preparer is android-only now, with src/platform-runtime-toolchain-host.test.ts asserting it), the harmony parameter threaded through createDeviceInventoryHost / createPlatformRuntimeHost / createHostToolchainPreparer, and HarmonyInventoryHost — DeviceInventoryHostByFamily.harmonyos is never and the plugin loads with no core host, the web shape. HarmonyPlatformOperations shrank to { toolchainCheck }, the Vega shape.

What is deliberately not here: merging web, Vega and HarmonyOS into one family-keyed selection, which waits on #4597 as you said. And the harmonyos literals that remain in packages/kernel are canonical vocabulary/selection messages, listed under "Not in this PR" rather than replaced by a new open registry.

@thymikee

Copy link
Copy Markdown
Member Author

Validation with a packed-plugin test driving an interaction through a stub hdc — done at 0c2188a.

packages/platform-harmonyos/test/package-smoke.mjs packs the core, installs @agent-device/harmonyos into a scratch AGENT_DEVICE_HOME, and runs two scenarios:

  1. Plugin absent. devices and doctor skip the family silently; devices --platform harmonyos, open --platform harmonyos and doctor --platform harmonyos answer the typed plugin-not-installed outcome with its install command, and help still renders the family. Reasons are compared against the typed constants, not message text.
  2. Plugin installed, toolchain reachable only through a documented root. A stub hdc is written into a scratch HDC_SDK_PATH root; the test asserts no PATH entry carries an hdc, restarts the daemon with that environment, and runs devices → open com.example.app → press 100 200 → close. It asserts each CLI reply (discovered id/name, Opened: …, targetKind: 'point') and every call the stub recorded: the argv each ran with, that every post-discovery call is target-scoped with -t stub-target, and that each spawn carried PATH: <root>:…. That is an interaction command, which is what the finding said no test covered. It runs inside pnpm run check:package (~13s) and on a machine with a real SDK installed, because every CLI run strips HDC_SDK_PATH, DEVECO_SDK_HOME, HARMONYOS_COMMAND_LINE_TOOLS and AGENT_DEVICE_* from the host.

Live evidence — blocker, not skipped. docs/evidence/harmonyos-managed-platform-2026-11-20.md carries what this machine can prove: the full packed-plugin sequence above with its --json replies, and a --debug log showing the hdc exec_command record nested under the request id, which is the trace the finding said was lost. It cannot carry a run against a real target: hdc is installed here and hdc list targets answers [Empty], and there is no startable image (no ~/.Huawei, no ~/Library/Huawei — only the DevEco IDE settings directory). devices/open/snapshot/press/screenshot/close against a device or emulator, and record, are not verified here; the evidence file says so in its own words rather than implying otherwise.

Non-blocking notes: taken — the two recorder behaviours are back as packages/platform-harmonyos/src/recording/recorder.test.ts (confirmed-removal semantics, stat -c %s parsing, plus the media-uri and ability-argv reads) driving the real recorder against the recorded HDC stub; the index.test.ts env restore now goes through vi.stubEnv with the suite's unstubEnvs isolation. Left — sampleMemory stays a parameter of createHarmonyPerfOperations (it is the seam the memory cell is tested through; mocking ../perf.ts would test the module graph instead of the operation), the no-selection toolchain-preparer case stays as a direct assertion on the android-only preparer, and the per-family operations scan in validate.ts stays as three visible checks rather than a shared helper, since the three messages and operation sets differ.

@thymikee

Copy link
Copy Markdown
Member Author

The web and Vega runtime import sites listed in the reply above are tracked in #4862 (same bundled host-kit fault in the two platform plugins already merged). Not changed in this PR.

@apex-sentinel-staging

This comment has been minimized.

@thymikee

Copy link
Copy Markdown
Member Author

This follow-up on the earlier review covers 0c2188a: the code findings from ef1b664 are fixed, but the live HarmonyOS run that #4317 requires is still missing.

The evidence file shows only a stub-hdc run, and it says no device or emulator was reachable. This PR moves all HarmonyOS dispatch, interaction, lifecycle and capture into a separately bundled plugin, so it is a device-facing change. The stub proves routing, PATH and request-scoped tracing. It cannot catch real-device differences such as layout shape, aa start output or capture encoding. The argv is unchanged from base and pinned by tests, so the residual risk is low. Before merge, please run the packed plugin (agent-device plugins add ./harmonyos.tgz, with hdc reachable only through HDC_SDK_PATH or DEVECO_SDK_HOME) on a real device or emulator. Append devices --platform harmonyos, open <bundle>, snapshot -i, press @<ref>, screenshot and close, each with --json, to that file. The maintainer can instead accept the stub evidence for "Part of #4317" and defer the live run to the issue's closure.

Not blocking, and fine to take or leave: the evidence file says the same sequence runs as a gate in package-smoke.mjs, but the smoke runs only devices, open, press and close, so either add snapshot -i and screenshot to it or name the four commands in the text; the comment at index.ts:40 says the toolbox binds on first use, yet setup() starts it immediately, so memoize it lazily or fix the comment; and command-host.ts:58 has await await, and each spawn probes the SDK roots twice, so drop the second await and probe once per spawn.

Both open inline threads no longer apply at this head and can be resolved: the test no longer assigns into process.env (thread), and the missing-hdc rewrap now carries the roots hint (thread). No other open threads still apply.

Smoke Tests (macos) and Build 0.22.0-nightly are still running, one more check is queued, and none has failed. The smoke job runs the package-smoke.mjs that this update rewrote, so a failure there would likely be related. There are no conflicts.

Not verified here: the packed bundle contents, the unit, smoke and layering tests (judged from reading them), the stub run and --debug trace, and assertion-by-assertion coverage of the roughly 1,530 rewritten test lines. Before merge, the PR needs the live device evidence (or the maintainer waiver), then green Smoke Tests (macos) and Build.

@thymikee

Copy link
Copy Markdown
Member Author

Optional items from the 0c2188a follow-up, applied at 327e188 (fast-forward, no other changes):

  1. Lazy toolbox — taken. harmonyToolbox(host) in packages/platform-harmonyos/src/index.ts now returns a resolver that builds the toolbox on first use and reuses it, so the comment and the code agree: a setup that never runs a command imports and builds nothing, and one setup still binds exactly one toolbox.
  2. await await — taken. resolveHdc in src/command-host.ts:58 awaits once. The per-spawn root probe stays as it is: the doubled await was the second probe, so a spawn now probes the documented roots once while tooling installed after the daemon started is still picked up without a restart.
  3. Smoke sequence — extended rather than reworded. test/package-smoke.mjs now runs snapshot -i and screenshot against the stub hdc too, asserting each CLI reply, the JPEG bytes the stub wrote, and the recorded uitest dumpLayout -p … and snapshot_display -f … argv. docs/evidence/harmonyos-managed-platform-2026-11-20.md:18 names all six commands the gate covers.

The live-run requirement is untouched and left for the maintainer as the waiver question it is. Verified at this head: pnpm lint, pnpm typecheck, pnpm format, pnpm check:layering, full pnpm exec vitest run --project unit-core (2161 files / 20859 tests), pnpm run check:package (the extended packed smoke included), fallow audit --base origin/0.22 with no findings introduced by the changeset.

@apex-sentinel-staging

This comment has been minimized.

@thymikee

Copy link
Copy Markdown
Member Author

At 327e188, the earlier findings from the first review are fixed. One high-priority defect remains in the release path.

packages/platform-harmonyos/package.json still declares private: true. The release workflow only stamps and packs public manifests (scripts/release-workspace.mjs), and scripts/release-publish.mjs rejects private tarballs. The base shipped HarmonyOS inside core. At this head, a normal release removes that built-in code and does not publish @agent-device/harmonyos, so users cannot install the replacement with the documented registry command. The smoke test packs the private workspace directly, so it bypasses these checks. Please remove private: true so the existing release workflow publishes the plugin with core.

Could packages/kernel/src/errors.ts own a pure constructor for process-exit details, used by both host-kit's execFailureDetails and the HarmonyOS deployment code? The plugin would then not need to reproduce the processExitError marker that error normalization reads.

CI is green: 31 checks, none failing. No conflicts.

Not verified here: package-smoke and the tests were not run locally, and no real HarmonyOS device or hdc was reachable. The stub fixture proves argv and reply shape only. Before merge, a live run of the changed device path through the managed plugin is required, using real hdc: devices, open, snapshot -i, screenshot, press, close. The maintainer can waive it or accept real-device output. After the manifest fix, that decision is the next step before merge.

@thymikee

Copy link
Copy Markdown
Member Author

On "private": true in packages/platform-harmonyos/package.json (round-three review at 327e188):

Yes, it is the intended 0.22 staging, and it is the same for the other managed plugins. On 0.22 today @agent-device/web and @agent-device/vega are also private; @agent-device/limrun (#4846) and @agent-device/maestro are too. docs/agents/pull-requests.md sets the order: the maintainer publishes a placeholder and configures the trusted publisher first, and only then a PR removes the flag. @agent-device/browserstack and @agent-device/aws-device-farm went through that and are public.

The review's concern is right as a release risk: a 0.22 release cut before the flip removes the built-in family and publishes no plugin. That is now tracked as a release gate in #4866, for all of these packages together, with a check so the release cannot name an install package it does not publish.

The flag is not changed in this PR. Waiting for the maintainer on this and on the live-run waiver.

@thymikee

Copy link
Copy Markdown
Member Author

The staging answer settles the manifest point from the review at 327e188: private: true is the intended 0.22 state for every managed plugin, and #4866 now tracks the flip as a release gate for all of them together. Nothing changes in this PR for that.

The one remaining item before merge is the live HarmonyOS run of the packed plugin, or a maintainer waiver for it.

The packed core no longer answers for the HarmonyOS family. `@agent-device/harmonyos`
is a managed optional platform plugin like the web and Vega plugins: the composition
resolves it through the same one-shot module selection, and a request that names
`--platform harmonyos` 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. HDC device discovery, the ArkUI interactor,
interaction handlers, app lifecycle and logs, the toolchain probe, the plugin-owned
HDC screen recorder and the RSS memory sampler all live in the package now; the
plugin reads the documented toolchain roots from the host environment the
composition hands it and never touches `process.env`. Core keeps only the canonical
platform vocabulary.
The HarmonyOS plugin rebuilt the live recording snapshot field for field, so the
shape now comes from capture-kit and the plugin names only its recorder.
Every process spawn and diagnostic in @agent-device/harmonyos now goes through the
PlatformHost the core hands setup(): one command runner and one HDC route are built there
and handed to inventory, runtime, interactor, recorder and doctor, so the packed bundle
carries no separate host-kit command or diagnostics scope. The layering policy bans those
two runtime scopes for every managed platform package, with the web and Vega files that
still import them registered as their own migration slices. The HarmonyOS facade stays
metadata-eager, the core's toolchain preparer is android-only, and the packed-plugin smoke
test drives discovery, launch, snapshot, a press, capture and close against a stub HDC
reachable only through HDC_SDK_PATH.
The facade said the toolbox binds on first use while `setup` built it
immediately, so the resolution is now lazy and memoized per setup: a
setup that never runs a command imports and builds nothing, and the
operations of one setup still share the one toolbox that binds its host.

One toolchain root probe per spawn instead of two: `resolveHdc` read a
Promise of the resolved HDC through a doubled await.

The packed-plugin smoke now also runs `snapshot -i` and `screenshot`
against the stub `hdc`, asserting each CLI reply, the JPEG the stub
wrote, and the layout-dump and frame-capture argv the stub recorded, so
the evidence file names the six commands the gate covers.
@thymikee
thymikee force-pushed the refactor/0.22-harmonyos-platform-plugin branch from 327e188 to de014dd Compare November 21, 2026 11:34
@apex-sentinel-staging

This comment has been minimized.

@thymikee

Copy link
Copy Markdown
Member Author

The earlier review at 327e188 asked for live device evidence. That is still missing, and this update at de014dd is a pure rebase that adds none. One code defect also remains.

For an open HarmonyOS session, logs start resolves the app PID and starts hilog outside the setup-bound host (logs/runtime.ts:36). PID lookup goes through AppLogRuntimeHost.commands.run (app-log-pid-runtime.ts:92). The hilog request at line 52 uses the runtime host's local process transport, which starts through runCmdBackground (platform-runtime-operation-host.ts:70 and :99, platform-runtime-app-log-process.ts:174). Both paths skip the PlatformHost given at setup. With HDC_SDK_PATH set, they get an absolute HDC path but not the SDK PATH preparation in command-host.ts:69. A toolchain that needs a sibling executable on PATH can then work for discovery and interaction, and fail on logs start. Every HDC command, one-shot or streamed, should run through the setup-bound HDC runner. Please run pidof through it. Please also give the setup host a managed background command entry, backed by the existing app-log process service, and pass hilog through the same HDC command and environment preparation.

Could the HarmonyOS command runner in command-host.ts own the executable and PATH for both one-shot and streamed HDC commands, using the existing managed app-log process service through the setup host for streaming?

Before merge, this PR needs a live run of the managed plugin on a real hdc target, installed from the packed tarball through agent-device plugins add. The run should show real output for devices --platform harmonyos listing the target, then open <app>, snapshot -i, screenshot, press @ref and close. A maintainer waiver would also settle this. Not verified here: any behavior on a HarmonyOS device, since no device or hdc was reachable, and the tests and package smoke were not run.

The only failing check is Body rules. That job grades the PR title and body, not the code. Its script and workflow came from the 0.22 base, so this diff does not touch its route. The current body has Summary, Value and Validation and stays under the word limit, so the run probably graded an earlier body. Not verified here: the job log, since no failure excerpt was captured. A re-run, or a body edit that re-triggers the job, should clear it.

No conflicts. The two earlier review threads were resolved before 327e188. After the logs fix and the device run, the Body rules re-run is the last open item.

`logs start` ran both of its HDC commands outside the host the plugin was
set up with: the PID lookup went through the runtime host's command port and
the hilog stream through its local process transport, so neither got the
family's documented toolchain roots on `PATH`. A toolchain that needs a
sibling executable there served discovery and interaction and failed the
stream.

The plugin's command runner now owns both routes. The one-shot `pidof` takes
`toolbox.hdc.runShell`, and the plan names its own process route: the setup
host's new managed background command entry, backed by the same app-log
process service the core's own transport uses, so the stream keeps its
ownership marker, stop, and cleanup and spawns with the same prepared
environment.
@apex-sentinel-staging

Copy link
Copy Markdown

Apex Sentinel · ✅ Approve · review of 2edb39e

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

No open findings.

Not in the reviewers' prompt (18 files)
  • docs/evidence/harmonyos-managed-platform-2026-11-20.md: 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/build-config/package.json: left out as an asset or for its size; reviewers could still search it
  • packages/build-config/tsconfig.json: left out as an asset or for its size; reviewers could still search it
  • packages/platform-harmonyos/package.json: left out as an asset or for its size; reviewers could still search it
  • packages/platform-harmonyos/src/__tests__/app-lifecycle.test.ts: left out as an asset or for its size; reviewers could still search it
  • packages/platform-harmonyos/src/__tests__/hdc-shell.test.ts: left out as an asset or for its size; reviewers could still search it
  • packages/platform-harmonyos/src/__tests__/tmp-dir.ts: left out as an asset or for its size; reviewers could still search it
  • packages/platform-harmonyos/src/interactor-facade.ts: left out as an asset or for its size; reviewers could still search it
  • packages/platform-harmonyos/src/inventory-config.ts: left out as an asset or for its size; reviewers could still search it
  • packages/platform-harmonyos/src/logs/runtime.test.ts: left out as an asset or for its size; reviewers could still search it
  • packages/platform-harmonyos/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
  • src/platform-runtime-screen-recording-harmony-host.test.ts: left out as an asset or for its size; reviewers could still search it
  • src/platform-runtime-screen-recording-harmony-host.ts: 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
  • website/docs/docs/installation.md: left out as an asset or for its size; reviewers could still search it
  • website/docs/docs/quick-start.md: left out as an asset or for its size; reviewers could still search it

1 finding below minor hidden (user_settings.min_severity).

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

💬 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

Fixed in 2edb39e3d0 — reply to the logs defect.

Both HDC commands logs start runs now go through the plugin's setup-bound HDC runner.

  • PID lookup: toolbox.hdc.runShell(device, ['pidof', …]) replaces AppLogRuntimeHost.commands.run, so it gets the runner's default timeout, its typed TOOL_MISSING report, and its prepared PATH. The shared numeric-pid parse moved to firstNumericAppLogPid(stdout) so both routes judge a blank or error-text answer the same way.
  • Stream: PlatformHost gained an optional startBackgroundCommand({ command, output, markerPath }, signal) (packages/plugins/src/platform.ts), answered by createPlatformPluginHost (src/platform-runtime/plugin-host.ts) on top of createManagedAppLogProcesses — the same app-log process service the runtime host's own transport uses. It confines the marker to the sessions dir (the daemon composition passes sessionsDir) and loads that service lazily, so a plugin host built at process start pulls nothing from the operation-host zone.
  • HarmonyCommandRunner now owns the executable and the PATH preparation for both one-shot and streamed HDC: its start() hands the host the same harmonySpawnEnvironment() result run() does, plus the resolved HDC path.
  • The capture-kit PID-scoped plan can now name its own process route (start?) and mint its command per start, so the executable resolves on the same route it spawns on. Availability still comes from the selected transport — the plan replaces only the route.

Tests:

  • Full vitest run --project unit-core: 2163 files, 20916 passed, 10 skipped, 0 failed.
  • packages/platform-harmonyos/src/logs/runtime.test.ts asserts both argvs, that each spawn was handed a PATH led by the configured HDC_SDK_PATH root, that the stream carried the marker path and a request-cancellable signal, and that the runtime host's local transport and command port were never used.
  • src/platform-runtime/plugin-host.test.ts proves the managed start publishes the core's ownership marker, forwards output into the opened sink, clears the marker on exit, and refuses a marker outside the sessions dir.
  • __tests__/hdc.test.ts pins the streamed command to the same toolchain PATH and the refusal when a host has no managed process service.
  • packages/platform-harmonyos/test/package-smoke.mjs now runs logs start and logs stop against the packed plugin and asserts shell pidof com.example.app and shell hilog -P 4242 reached the stub hdc that is reachable only through HDC_SDK_PATH, with that root leading every recorded PATH.

Local gates on this SHA: build, pnpm lint, pnpm typecheck, pnpm format, pnpm check:layering (R13 harmonyos debt list still empty), pnpm check:fallow, pnpm check:package, command-docs, daemon-wire-compat.

Still open and not touched here: the live hdc device run (or a maintainer waiver). Body rules re-ran on this push and pass.

@thymikee

Copy link
Copy Markdown
Member Author

The earlier findings from de014dd (#4857 (comment)) are addressed in the code at 2edb39e, except the missing live-device evidence, which still stands. The managed plugin has still not run on a real hdc target, and the new logs route (logs start through startBackgroundCommand) is now part of what is unproven.

Before merge, install the packed tarball with agent-device plugins add and run it on a real hdc target. Show real output for devices --platform harmonyos listing the target, then open , snapshot -i, screenshot, press @ref, logs start (the log file receives hilog lines and the app-log.pid marker exists under the session dir), logs stop, and close. A maintainer waiver is the alternative. The only evidence today is unit tests and a packed-plugin smoke against a stub hdc, and the PR body says no hdc target is available. See https://github.com/callstack/agent-device/blob/2edb39e/docs/evidence/harmonyos-managed-platform-2026-11-20.md#L1.

Not blocking, take or leave: the startBackgroundCommand doc in packages/plugins/src/platform.ts#L72 says it is absent when the composing process owns no session artifacts, but createPlatformPluginHost always defines it, so the UNSUPPORTED_OPERATION branch in command-host.ts cannot fire today. Either make it required on PlatformHost and delete that branch, or drop the "absent when" sentence.

The Body rules check was cancelled, not failed. It grades the PR title and body, and this change does not touch what it exercises, so a re-run should clear it. No conflicts were reported. Not verified here: the tests, the package smoke and the Body rules log were not run or read, and no HarmonyOS device or hdc was reachable. After the live run or a waiver, re-run the cancelled check.

@thymikee

Copy link
Copy Markdown
Member Author

Reply to #4857 (comment). Body rules passes at 2edb39e (re-run requested anyway). The optional startBackgroundCommand cleanup (required member vs. the "absent when" sentence) is left out of this PR so the two stacked PRs (#4872, #4874) keep a stable base; it goes with the PlatformHost follow-ups in #4878. The live hdc run needs a real target this Mac does not have; the maintainer waiver decision is requested.

@thymikee

thymikee commented Nov 21, 2026 •

Copy link
Copy Markdown
Member Author

Live run of the packed plugin on a real HarmonyOS device, head 2edb39e. This answers the device-evidence item from #4857 (comment).

Setup: Huawei nova 14, OpenHarmony-6.1.1.120, USB, hdc 3.1.0e. Core packed with npm pack (agent-device-0.22.0-dev.tgz) and installed into an empty scratch project. The plugin was packed from packages/platform-harmonyos and installed with agent-device plugins add ./harmonyos.tgz into an isolated AGENT_DEVICE_HOME and AGENT_DEVICE_STATE_DIR. No checkout code ran.

$ agent-device plugins add ./harmonyos.tgz --json
{"success":true,"data":{"artifact":{"name":"@agent-device/harmonyos","version":"0.22.0-dev",...},"restartRequired":true}}

$ agent-device devices --platform harmonyos --json
{"success":true,"data":{"devices":[{"platform":"harmonyos","id":"4UQ9K25710015363","name":"nova 14","kind":"device","target":"mobile","booted":true}]}}

$ agent-device open com.huawei.hmos.settings --platform harmonyos --session hmos-live --json
{"success":true,"data":{"session":"hmos-live","appBundleId":"com.huawei.hmos.settings","selection":{"reason":"single-booted-local",...},"startup":{"durationMs":814,...},"platform":"harmonyos","device":"nova 14","message":"Opened: com.huawei.hmos.settings"}}

$ agent-device snapshot -i --session hmos-live
Page: com.huawei.hmos.settings
Snapshot: 20 nodes
@e1 [button]
@e2 [flex] "SwitchMenuComponent" [focused]
@e3 [toggle] "entry_toggle_development_personnel_option" [focused]
...
@e10 [toggle] "entry_toggle_usb_debug"
...

$ agent-device screenshot <scratch>/screen.png --session hmos-live --json
{"success":true,"data":{"path":"<scratch>/screen.png"}}        # Settings > Developer options, 1084x2412

$ agent-device press @e1 --session hmos-live --json
{"success":true,"data":{"x":108,"y":189,"message":"Tapped @e1 (108, 189)","referenceWidth":1084,"referenceHeight":2412,"targetKind":"ref","resolution":{"source":"ref","phase":"pre-action","kind":"exact"}}}

$ agent-device logs start --session hmos-live --json
{"success":true,"data":{"path":"<state>/sessions/hmos-live/app.log","started":true}}

$ agent-device logs path --session hmos-live --json        # while streaming
{"success":true,"data":{"active":true,"state":"active","backend":"harmonyos","sizeBytes":13032,...}}
$ ls <state>/sessions/hmos-live
app-log.pid  app-log.resource.json  app.log  events.ndjson

$ agent-device logs stop --session hmos-live --json
{"success":true,"data":{"stopped":true}}
$ ls <state>/sessions/hmos-live        # app-log.pid removed after the stop
app-log.resource.json  app.log  events.ndjson
$ wc -l app.log ; head -1 app.log
93
11-21 16:37:09.221 20463 20463 W A00500/com.huawei.hmos.settings/Settings: SearchDataLoadingUtil: --> resetLoadingStatus: ...
# app-log.resource.json: transport "harmony-hilog", lifecycle "completed"

$ agent-device close --session hmos-live --json
{"success":true,"data":{"session":"hmos-live","message":"Closed: hmos-live"}}

All 93 lines in app.log are hilog lines for com.huawei.hmos.settings, the session app's PID. The stream started through the setup host's managed background command, pidof ran through the plugin's HDC runner, and the ownership marker existed only while the stream ran.

Observations, not blockers for this PR:

  • The snapshot labels on this build are ArkUI resource IDs, such as entry_toggle_usb_debug, not the visible text "USB debugging".
  • press @e1 reports refLabel: "StatusBarBridgeView" for a node the snapshot lists as an unlabeled [button]. The tap landed on the back button at (108, 189).

Filed as #4906 and #4907.

@thymikee

Copy link
Copy Markdown
Member Author

The live run at 2edb39e (#4857 (comment)) covers every step the review asked for: the packed plugin installed with plugins add on a real hdc target, devices, open, snapshot -i, screenshot, press @ref, logs start with hilog lines for the session app and the app-log.pid marker present only while streaming, logs stop and close. That settles the device-evidence item, and nothing from review blocks this head. The two observations (ArkUI resource-id labels and the press refLabel) are tracked in #4906 and #4907.

@thymikee
thymikee merged commit b758908 into 0.22 Nov 21, 2026
34 of 35 checks passed
@thymikee
thymikee deleted the refactor/0.22-harmonyos-platform-plugin branch November 21, 2026 16:32
thymikee added a commit that referenced this pull request Nov 21, 2026
Every process spawn, process-table read and diagnostic in @agent-device/web and
@agent-device/vega now goes through the PlatformHost the core hands setup(): one command route per
family is built there and handed to inventory, runtime, interactor, recorder and doctor, so neither
packed bundle carries a separate host-kit command or diagnostics scope. Each family gets a
`command-host.ts` that owns its argv and a `toolbox.ts` that binds the host, lazily and once per
setup, matching the shape the HarmonyOS plugin set in #4857.

Two host-kit reads the web and Vega plugins made directly became host ports rather than plugin code:
`isExecutableOnPath`, which is how Vega prefers a CLI from the host `PATH` before its home install,
and `listHostProcesses`, which is how the web provider derives the owned-process record for the fleet
it starts. The latter answers through the host's own executable resolution and apart from any command
override one request carries. The web plugin's `ManagedBrowserHost` and its optional-command and
optional-diagnostic fallbacks are gone: a toolbox is required, so a plugin surface can no longer run
a command nobody asked it to run.

Vega's inventory now loads with no core host at all, as HarmonyOS's already does, and its tool
provider takes the family's command runner instead of building ambient ones. The kernel gained
`commandFailureDetails` and `requireCommandSuccess` for a caller that holds a command answer and no
host, which is what a plugin on `PlatformHost.runCommand` holds; the exec-wrap guard accepts either
pair so neither family spreads the stdout/stderr/exitCode trio by hand.

With both families converted, the layering policy's per-file debt list is deleted rather than
emptied: a managed platform package is bound to its host from its first commit, and a file that
wants a host-kit command or diagnostic helper is a bug at that file.
thymikee added a commit that referenced this pull request Nov 21, 2026
Every process spawn, process-table read and diagnostic in @agent-device/web and
@agent-device/vega now goes through the PlatformHost the core hands setup(): one command route per
family is built there and handed to inventory, runtime, interactor, recorder and doctor, so neither
packed bundle carries a separate host-kit command or diagnostics scope. Each family gets a
`command-host.ts` that owns its argv and a `toolbox.ts` that binds the host, lazily and once per
setup, matching the shape the HarmonyOS plugin set in #4857.

Two host-kit reads the web and Vega plugins made directly became host ports rather than plugin code:
`isExecutableOnPath`, which is how Vega prefers a CLI from the host `PATH` before its home install,
and `listHostProcesses`, which is how the web provider derives the owned-process record for the fleet
it starts. The latter answers through the host's own executable resolution and apart from any command
override one request carries. The web plugin's `ManagedBrowserHost` and its optional-command and
optional-diagnostic fallbacks are gone: a toolbox is required, so a plugin surface can no longer run
a command nobody asked it to run.

Vega's inventory now loads with no core host at all, as HarmonyOS's already does, and its tool
provider takes the family's command runner instead of building ambient ones. The kernel gained
`commandFailureDetails` and `requireCommandSuccess` for a caller that holds a command answer and no
host, which is what a plugin on `PlatformHost.runCommand` holds; the exec-wrap guard accepts either
pair so neither family spreads the stdout/stderr/exitCode trio by hand.

With both families converted, the layering policy's per-file debt list is deleted rather than
emptied: a managed platform package is bound to its host from its first commit, and a file that
wants a host-kit command or diagnostic helper is a bug at that file.
thymikee added a commit that referenced this pull request Nov 21, 2026
* refactor(web,vega): run each plugin's commands on its setup host

Every process spawn, process-table read and diagnostic in @agent-device/web and
@agent-device/vega now goes through the PlatformHost the core hands setup(): one command route per
family is built there and handed to inventory, runtime, interactor, recorder and doctor, so neither
packed bundle carries a separate host-kit command or diagnostics scope. Each family gets a
`command-host.ts` that owns its argv and a `toolbox.ts` that binds the host, lazily and once per
setup, matching the shape the HarmonyOS plugin set in #4857.

Two host-kit reads the web and Vega plugins made directly became host ports rather than plugin code:
`isExecutableOnPath`, which is how Vega prefers a CLI from the host `PATH` before its home install,
and `listHostProcesses`, which is how the web provider derives the owned-process record for the fleet
it starts. The latter answers through the host's own executable resolution and apart from any command
override one request carries. The web plugin's `ManagedBrowserHost` and its optional-command and
optional-diagnostic fallbacks are gone: a toolbox is required, so a plugin surface can no longer run
a command nobody asked it to run.

Vega's inventory now loads with no core host at all, as HarmonyOS's already does, and its tool
provider takes the family's command runner instead of building ambient ones. The kernel gained
`commandFailureDetails` and `requireCommandSuccess` for a caller that holds a command answer and no
host, which is what a plugin on `PlatformHost.runCommand` holds; the exec-wrap guard accepts either
pair so neither family spreads the stdout/stderr/exitCode trio by hand.

With both families converted, the layering policy's per-file debt list is deleted rather than
emptied: a managed platform package is bound to its host from its first commit, and a file that
wants a host-kit command or diagnostic helper is a bug at that file.

* refactor(web): read the browser fleet's processes through its host

The web fleet record still read processes through the plugin's own copy of the host kit:
`readProcessIdentities`, `readProcessExecutablePaths`, `readHostProcessIdentityObservationsAsync`, and
the startup reaper's `reapOwnedProcessRecordsAtStartup`. A managed plugin is bundled with its own copy
of that kit, and a request's command-host and diagnostic scopes never enter it, so each of those reads
answered with the daemon process environment and traced into the plugin's own store instead of the
request's. `--debug` for a web `open` that refreshed the record showed the backend spawn and nothing of
the reads that derived the record.

`PlatformHost` now answers these through a `processes` facet: the host's process table, per-pid identity
facts and observations, executable paths, and the reap of an owned-process record. It is served by the
core's own copy of the kit in `src/platform-runtime/plugin-host.ts`, where the request's scopes live, so
the read is in the environment and exec trace the request opened. `listHostProcesses` became
`processes.list`, and the fleet scan, the record's liveness probe, the install lock's claim on this
process's start time, and both orphan reapers now ask the host. The facet is reads plus that one reap: a
plugin never signals a pid it merely saw, only the ones a record it owns names.

The layering policy polices `host-kit/process` export by export now. Its 16 exports that reach the exec
layer join the ban for every managed family; the ones that read this process's own globals or compute
from what the caller holds (`hostPlatform`, `hostProcessId`, `isProcessAlive`, `expandProcessTree`,
`processStartTimesDiffer`) stay reachable, because they cannot leave the request's scope. A runtime edge
that names no export could reach any of them, so a namespace or bare import of the scope is refused.

Proof, in both directions: the core's host answers a table read, an identity read and a real reap of a
spawned child inside a `--debug` request's exec trace (`src/platform-runtime/plugin-host.test.ts`), and
the web fleet scan and startup reap make no process tool of their own — `spawn` and `spawnSync` are
refused for that module graph, and the reads it acts on are the ones its host answered
(`agent-browser-process-record-host-routing.test.ts`).

Also drops what the route made dead or wrong: `VegaToolbox` carried a host and a timer nothing read; the
HarmonyOS test host answered "on PATH" for every name because `whichCmd` returns a boolean; and an
orphaned JSDoc block sat above `managedStatusOptions` rather than the status reader it describes.

The packed-plugin gate names the reads too. It refused an `open` request that traced no process-table
read already; on macOS the scan also asks the host for each candidate's executable, which answers
through `osascript` (through a CIM query on Windows). A live packed run on this head traced six `ps`
reads and one `osascript` read under the one `open` request, so both kinds are asserted per request
rather than kept only in the evidence file.

* refactor(web): take the managed install lock through its host

Claiming the install lock reads this process's identity with `ps`, and every
poll of a held or stale lock re-proves the recorded owner and the guard holder
with another read. The plugin took the lock from its bundled host-kit copy, so
those reads ran with the daemon environment and traced into the bundle's own
store: a request that waited out another process's install showed no wait.

The host answers `processes.withLock`, and names its own identity there rather
than being told it. The async identity read is the one the request sees: it runs
`ps` through the command host, where the synchronous probe's `spawnSync` never
appears in the exec trace.

The packed web gate now asserts the plugin bundle carries no process tool, and
that a `web setup --debug` on a clean state dir traces both the lock's `ps` read
and the managed-backend install into the request that asked for it.

* refactor(scripts): derive the host-kit exports a managed plugin may load

The platform package policy refused a managed platform's runtime import of a
host-kit export by looking the name up in a hand-kept per-scope list. A new
export that reached the exec layer escaped until someone added it, which is the
same failure the rule exists to catch.

The rule now reads the host-kit module graph: an export is refused unless the
graph proves its declaring module loads neither `internal/exec.ts` nor the
diagnostic store, and the allowed set is the same derivation. Namespace and bare
imports are refused, an unknown subpath is refused, and a missing exec root is
reported as stale instead of quietly widening the permission. Per-specifier
`type` markers are erased at runtime, so `ImportEdge` carries `typeSymbols` and
the reach rule judges only the value names an import binds.

`internal/host-process-facts.ts` and `internal/sleep.ts` split out of
`internal/host-process.ts` and `internal/retry.ts`: the pid arithmetic and the
timer import nothing, so those exports stay on the clean side of the line, and
the process tool's reads stay where they were.

* refactor(plugins): answer every machine and process fact on the host

Splitting `internal/host-process-facts.ts` and `internal/sleep.ts` out of the
host kit moved two eager modules into the closure of every entry that imports
them, which is what the eager-closure budget refuses: a clean leaf is not free,
it costs one evaluated module per closure that already evaluated the parent.
Both modules are merged back, so the process scope has no pure export left and
the derived rule refuses it wholesale — which is the sound verdict anyway: a
re-export of `isProcessAlive` still evaluates the module that loads the exec
layer, so no per-name permission for that scope could be honest.

The three managed plugins now ask their host instead of their bundled copy:

- `PlatformHost` carries the machine its commands run on — `hostOs`,
  `nodeExecutablePath`, `nodeVersion`, `temporaryDirectory`, `processId` — read
  once when the core builds the host. The web family builds its managed install
  layout, its npm argv, its launch executable, its Node capability read and the
  pid its fleet scan must skip from these.
- `PlatformHost.processes` answers two more questions the plugin cannot derive
  from rows it was given: `expandTree`, because only the host knows which
  parent-child relation its own table records, and `judgeRecordedLiveness`,
  because the fail-closed reading of a written record depends on the host's own
  start-time format and its own liveness probe. The host answers both from the
  core's copy, inside the request's exec trace.
- Pacing uses `node:timers/promises`, the timer the core's host waits on too.
  The retry scope of the bundled copy carries that scope's diagnostic store, and
  a wait between two backend sends belongs to no scope.

`readIdentityObservations` leaves the contract with no caller left: the record
probe asks the host to judge the records rather than reading observations it
would have to compare itself.

The policy tests now assert the merged truth: the file scope is still judged
name by name (the pure path helper imports, the lock helper does not), and the
process and retry scopes are refused for every managed family.

* refactor(web): name the host's machine facts at its own type

`WebStatusHost` restated the five machine facts the host answers instead of
naming the type the family already gives them to, so the list had two owners.

* test(linux): answer the host's machine and process facts in the plugin test host

* test(layering): fit the policy test within its line cap

* refactor(linux): read the host OS and pace input without the bundled host kit

* style(layering): format the policy test within its line cap

* fix(vega): print the doctor install hint with POSIX separators on every host
thymikee added a commit that referenced this pull request Nov 21, 2026
…4857)

* refactor(harmonyos): move HarmonyOS into the managed platform plugin

The packed core no longer answers for the HarmonyOS family. `@agent-device/harmonyos`
is a managed optional platform plugin like the web and Vega plugins: the composition
resolves it through the same one-shot module selection, and a request that names
`--platform harmonyos` 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. HDC device discovery, the ArkUI interactor,
interaction handlers, app lifecycle and logs, the toolchain probe, the plugin-owned
HDC screen recorder and the RSS memory sampler all live in the package now; the
plugin reads the documented toolchain roots from the host environment the
composition hands it and never touches `process.env`. Core keeps only the canonical
platform vocabulary.

* refactor(recording): share the transport recording snapshot builder

The HarmonyOS plugin rebuilt the live recording snapshot field for field, so the
shape now comes from capture-kit and the plugin names only its recorder.

* refactor(harmonyos): run the plugin's commands on its setup host

Every process spawn and diagnostic in @agent-device/harmonyos now goes through the
PlatformHost the core hands setup(): one command runner and one HDC route are built there
and handed to inventory, runtime, interactor, recorder and doctor, so the packed bundle
carries no separate host-kit command or diagnostics scope. The layering policy bans those
two runtime scopes for every managed platform package, with the web and Vega files that
still import them registered as their own migration slices. The HarmonyOS facade stays
metadata-eager, the core's toolchain preparer is android-only, and the packed-plugin smoke
test drives discovery, launch, snapshot, a press, capture and close against a stub HDC
reachable only through HDC_SDK_PATH.

* refactor(harmonyos): bind the plugin's toolbox on first command

The facade said the toolbox binds on first use while `setup` built it
immediately, so the resolution is now lazy and memoized per setup: a
setup that never runs a command imports and builds nothing, and the
operations of one setup still share the one toolbox that binds its host.

One toolchain root probe per spawn instead of two: `resolveHdc` read a
Promise of the resolved HDC through a doubled await.

The packed-plugin smoke now also runs `snapshot -i` and `screenshot`
against the stub `hdc`, asserting each CLI reply, the JPEG the stub
wrote, and the layout-dump and frame-capture argv the stub recorded, so
the evidence file names the six commands the gate covers.

* fix(harmonyos): stream hilog through the plugin's setup host

`logs start` ran both of its HDC commands outside the host the plugin was
set up with: the PID lookup went through the runtime host's command port and
the hilog stream through its local process transport, so neither got the
family's documented toolchain roots on `PATH`. A toolchain that needs a
sibling executable there served discovery and interaction and failed the
stream.

The plugin's command runner now owns both routes. The one-shot `pidof` takes
`toolbox.hdc.runShell`, and the plan names its own process route: the setup
host's new managed background command entry, backed by the same app-log
process service the core's own transport uses, so the stream keeps its
ownership marker, stop, and cleanup and spawns with the same prepared
environment.
thymikee added a commit that referenced this pull request Nov 21, 2026
* refactor(web,vega): run each plugin's commands on its setup host

Every process spawn, process-table read and diagnostic in @agent-device/web and
@agent-device/vega now goes through the PlatformHost the core hands setup(): one command route per
family is built there and handed to inventory, runtime, interactor, recorder and doctor, so neither
packed bundle carries a separate host-kit command or diagnostics scope. Each family gets a
`command-host.ts` that owns its argv and a `toolbox.ts` that binds the host, lazily and once per
setup, matching the shape the HarmonyOS plugin set in #4857.

Two host-kit reads the web and Vega plugins made directly became host ports rather than plugin code:
`isExecutableOnPath`, which is how Vega prefers a CLI from the host `PATH` before its home install,
and `listHostProcesses`, which is how the web provider derives the owned-process record for the fleet
it starts. The latter answers through the host's own executable resolution and apart from any command
override one request carries. The web plugin's `ManagedBrowserHost` and its optional-command and
optional-diagnostic fallbacks are gone: a toolbox is required, so a plugin surface can no longer run
a command nobody asked it to run.

Vega's inventory now loads with no core host at all, as HarmonyOS's already does, and its tool
provider takes the family's command runner instead of building ambient ones. The kernel gained
`commandFailureDetails` and `requireCommandSuccess` for a caller that holds a command answer and no
host, which is what a plugin on `PlatformHost.runCommand` holds; the exec-wrap guard accepts either
pair so neither family spreads the stdout/stderr/exitCode trio by hand.

With both families converted, the layering policy's per-file debt list is deleted rather than
emptied: a managed platform package is bound to its host from its first commit, and a file that
wants a host-kit command or diagnostic helper is a bug at that file.

* refactor(web): read the browser fleet's processes through its host

The web fleet record still read processes through the plugin's own copy of the host kit:
`readProcessIdentities`, `readProcessExecutablePaths`, `readHostProcessIdentityObservationsAsync`, and
the startup reaper's `reapOwnedProcessRecordsAtStartup`. A managed plugin is bundled with its own copy
of that kit, and a request's command-host and diagnostic scopes never enter it, so each of those reads
answered with the daemon process environment and traced into the plugin's own store instead of the
request's. `--debug` for a web `open` that refreshed the record showed the backend spawn and nothing of
the reads that derived the record.

`PlatformHost` now answers these through a `processes` facet: the host's process table, per-pid identity
facts and observations, executable paths, and the reap of an owned-process record. It is served by the
core's own copy of the kit in `src/platform-runtime/plugin-host.ts`, where the request's scopes live, so
the read is in the environment and exec trace the request opened. `listHostProcesses` became
`processes.list`, and the fleet scan, the record's liveness probe, the install lock's claim on this
process's start time, and both orphan reapers now ask the host. The facet is reads plus that one reap: a
plugin never signals a pid it merely saw, only the ones a record it owns names.

The layering policy polices `host-kit/process` export by export now. Its 16 exports that reach the exec
layer join the ban for every managed family; the ones that read this process's own globals or compute
from what the caller holds (`hostPlatform`, `hostProcessId`, `isProcessAlive`, `expandProcessTree`,
`processStartTimesDiffer`) stay reachable, because they cannot leave the request's scope. A runtime edge
that names no export could reach any of them, so a namespace or bare import of the scope is refused.

Proof, in both directions: the core's host answers a table read, an identity read and a real reap of a
spawned child inside a `--debug` request's exec trace (`src/platform-runtime/plugin-host.test.ts`), and
the web fleet scan and startup reap make no process tool of their own — `spawn` and `spawnSync` are
refused for that module graph, and the reads it acts on are the ones its host answered
(`agent-browser-process-record-host-routing.test.ts`).

Also drops what the route made dead or wrong: `VegaToolbox` carried a host and a timer nothing read; the
HarmonyOS test host answered "on PATH" for every name because `whichCmd` returns a boolean; and an
orphaned JSDoc block sat above `managedStatusOptions` rather than the status reader it describes.

The packed-plugin gate names the reads too. It refused an `open` request that traced no process-table
read already; on macOS the scan also asks the host for each candidate's executable, which answers
through `osascript` (through a CIM query on Windows). A live packed run on this head traced six `ps`
reads and one `osascript` read under the one `open` request, so both kinds are asserted per request
rather than kept only in the evidence file.

* refactor(web): take the managed install lock through its host

Claiming the install lock reads this process's identity with `ps`, and every
poll of a held or stale lock re-proves the recorded owner and the guard holder
with another read. The plugin took the lock from its bundled host-kit copy, so
those reads ran with the daemon environment and traced into the bundle's own
store: a request that waited out another process's install showed no wait.

The host answers `processes.withLock`, and names its own identity there rather
than being told it. The async identity read is the one the request sees: it runs
`ps` through the command host, where the synchronous probe's `spawnSync` never
appears in the exec trace.

The packed web gate now asserts the plugin bundle carries no process tool, and
that a `web setup --debug` on a clean state dir traces both the lock's `ps` read
and the managed-backend install into the request that asked for it.

* refactor(scripts): derive the host-kit exports a managed plugin may load

The platform package policy refused a managed platform's runtime import of a
host-kit export by looking the name up in a hand-kept per-scope list. A new
export that reached the exec layer escaped until someone added it, which is the
same failure the rule exists to catch.

The rule now reads the host-kit module graph: an export is refused unless the
graph proves its declaring module loads neither `internal/exec.ts` nor the
diagnostic store, and the allowed set is the same derivation. Namespace and bare
imports are refused, an unknown subpath is refused, and a missing exec root is
reported as stale instead of quietly widening the permission. Per-specifier
`type` markers are erased at runtime, so `ImportEdge` carries `typeSymbols` and
the reach rule judges only the value names an import binds.

`internal/host-process-facts.ts` and `internal/sleep.ts` split out of
`internal/host-process.ts` and `internal/retry.ts`: the pid arithmetic and the
timer import nothing, so those exports stay on the clean side of the line, and
the process tool's reads stay where they were.

* refactor(plugins): answer every machine and process fact on the host

Splitting `internal/host-process-facts.ts` and `internal/sleep.ts` out of the
host kit moved two eager modules into the closure of every entry that imports
them, which is what the eager-closure budget refuses: a clean leaf is not free,
it costs one evaluated module per closure that already evaluated the parent.
Both modules are merged back, so the process scope has no pure export left and
the derived rule refuses it wholesale — which is the sound verdict anyway: a
re-export of `isProcessAlive` still evaluates the module that loads the exec
layer, so no per-name permission for that scope could be honest.

The three managed plugins now ask their host instead of their bundled copy:

- `PlatformHost` carries the machine its commands run on — `hostOs`,
  `nodeExecutablePath`, `nodeVersion`, `temporaryDirectory`, `processId` — read
  once when the core builds the host. The web family builds its managed install
  layout, its npm argv, its launch executable, its Node capability read and the
  pid its fleet scan must skip from these.
- `PlatformHost.processes` answers two more questions the plugin cannot derive
  from rows it was given: `expandTree`, because only the host knows which
  parent-child relation its own table records, and `judgeRecordedLiveness`,
  because the fail-closed reading of a written record depends on the host's own
  start-time format and its own liveness probe. The host answers both from the
  core's copy, inside the request's exec trace.
- Pacing uses `node:timers/promises`, the timer the core's host waits on too.
  The retry scope of the bundled copy carries that scope's diagnostic store, and
  a wait between two backend sends belongs to no scope.

`readIdentityObservations` leaves the contract with no caller left: the record
probe asks the host to judge the records rather than reading observations it
would have to compare itself.

The policy tests now assert the merged truth: the file scope is still judged
name by name (the pure path helper imports, the lock helper does not), and the
process and retry scopes are refused for every managed family.

* refactor(web): name the host's machine facts at its own type

`WebStatusHost` restated the five machine facts the host answers instead of
naming the type the family already gives them to, so the list had two owners.

* test(linux): answer the host's machine and process facts in the plugin test host

* test(layering): fit the policy test within its line cap

* refactor(linux): read the host OS and pace input without the bundled host kit

* style(layering): format the policy test within its line cap

* fix(vega): print the doctor install hint with POSIX separators on every host
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.

1 participant