From 644fe5bc61e5cc430d7939145bc4122070ab8e7f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 21 Nov 2026 02:33:01 +0100 Subject: [PATCH 01/11] 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. --- .../vega-managed-platform-2026-11-21.md | 108 ++++++++++ .../web-managed-platform-2026-11-21.md | 139 ++++++++++++ .../contracts/src/platform-runtime-host.ts | 3 +- packages/contracts/src/vega-tool-provider.ts | 6 +- .../src/composed-inventory-gateways.ts | 11 +- packages/kernel/src/errors.ts | 50 +++++ packages/platform-harmonyos/src/index.test.ts | 4 +- .../src/__tests__/app-lifecycle.test.ts | 27 ++- .../src/__tests__/doctor.test.ts | 20 +- .../src/__tests__/input-actions.test.ts | 44 ++-- .../tool-provider-host-isolation.test.ts | 105 --------- .../src/__tests__/tool-provider.test.ts | 42 ++-- packages/platform-vega/src/app-lifecycle.ts | 11 +- .../src/command-host.fixtures.ts | 157 ++++++++++++++ .../platform-vega/src/command-host.test.ts | 87 ++++++++ packages/platform-vega/src/command-host.ts | 70 ++++++ packages/platform-vega/src/doctor.ts | 23 +- packages/platform-vega/src/index.test.ts | 200 +++++++++--------- packages/platform-vega/src/index.ts | 103 +++++---- packages/platform-vega/src/input-actions.ts | 4 +- packages/platform-vega/src/inventory.test.ts | 85 ++++---- packages/platform-vega/src/inventory.ts | 56 ++--- packages/platform-vega/src/tool-provider.ts | 99 ++++----- packages/platform-vega/src/toolbox.ts | 27 +++ packages/platform-vega/src/vega-executable.ts | 31 +-- packages/platform-vega/test/package-smoke.mjs | 189 ++++++++++++++++- ...t-browser-provider-boundary-faults.test.ts | 3 +- ...owser-provider-dispatch-disclosure.test.ts | 3 +- ...gent-browser-provider-fleet-record.test.ts | 3 +- ...-browser-provider-record-retention.test.ts | 3 +- .../platform-web/src/__tests__/doctor.test.ts | 11 +- .../provider-composition-fallback.test.ts | 15 +- .../platform-web/src/__tests__/test-utils.ts | 7 +- .../platform-web/src/agent-browser-install.ts | 8 +- .../src/agent-browser-lifecycle.test.ts | 72 ++++++- .../src/agent-browser-lifecycle.ts | 7 +- .../src/agent-browser-process-record.ts | 22 +- .../src/agent-browser-provider-rects.test.ts | 3 +- .../src/agent-browser-provider.test.ts | 25 ++- .../src/agent-browser-provider.ts | 29 +-- .../src/agent-browser-tool.test.ts | 23 +- .../platform-web/src/agent-browser-tool.ts | 65 +++--- packages/platform-web/src/command-host.ts | 45 ++++ packages/platform-web/src/doctor.ts | 8 +- .../src/index-startup-cleanup.test.ts | 4 +- packages/platform-web/src/index.ts | 68 ++++-- packages/platform-web/src/interactor.test.ts | 9 +- packages/platform-web/src/interactor.ts | 15 +- packages/platform-web/src/resolve-provider.ts | 15 +- packages/platform-web/src/toolbox.fixtures.ts | 99 +++++++++ packages/platform-web/src/toolbox.ts | 30 +++ packages/platform-web/test/package-smoke.mjs | 158 +++++++++++++- packages/plugins/src/platform.test.ts | 2 + packages/plugins/src/platform.ts | 14 +- .../layering/platform-package-policy.test.ts | 5 +- scripts/layering/platform-package-policy.ts | 30 +-- src/platform-runtime-host.test.ts | 10 +- src/platform-runtime/plugin-host.ts | 13 ++ test/repo-guards/exec-wrap-guard.test.ts | 15 +- 59 files changed, 1834 insertions(+), 706 deletions(-) create mode 100644 docs/evidence/vega-managed-platform-2026-11-21.md create mode 100644 docs/evidence/web-managed-platform-2026-11-21.md delete mode 100644 packages/platform-vega/src/__tests__/tool-provider-host-isolation.test.ts create mode 100644 packages/platform-vega/src/command-host.fixtures.ts create mode 100644 packages/platform-vega/src/command-host.test.ts create mode 100644 packages/platform-vega/src/command-host.ts create mode 100644 packages/platform-vega/src/toolbox.ts create mode 100644 packages/platform-web/src/command-host.ts create mode 100644 packages/platform-web/src/toolbox.fixtures.ts create mode 100644 packages/platform-web/src/toolbox.ts diff --git a/docs/evidence/vega-managed-platform-2026-11-21.md b/docs/evidence/vega-managed-platform-2026-11-21.md new file mode 100644 index 0000000000..28a65fc1cb --- /dev/null +++ b/docs/evidence/vega-managed-platform-2026-11-21.md @@ -0,0 +1,108 @@ +# Vega managed platform plugin — packed-plugin evidence (2026-11-21) + +Head: `fix/0.22-web-vega-plugin-host-routing`. Issue #4862. Stacked on #4857. + +## Live Vega Virtual Device on this host + +The device-facing family was driven on a real Vega Virtual Device, not a stub, with the packed +plugin: SDK `0.23.9221`, Vega CLI `1.3.2` at `/Users/thymikee/vega/bin/vega`. + +| Check | Result | +| --- | --- | +| `vega virtual-device status` before the run | `{"running":false,"process_ids":{"qemu":-1}}` | +| `vega virtual-device start` | `Virtual device ready.` / `{"running":true,"process_ids":{"qemu":65432}}` | +| `vega device list` | `VirtualDevice : tv - aarch64 - OS - amazon-f38d6e237d275dd5` | +| Target app | `com.amazondeveloper.keplersampleapp.main` (Kepler sample app, from `vega device installed-apps`) | +| `vega virtual-device status` after the run | `{"running":false,"process_ids":{"qemu":-1}}` | + +Setup: a scratch project, an isolated store (`AGENT_DEVICE_HOME`, `AGENT_DEVICE_STATE_DIR`, +`AGENT_DEVICE_CLAIMS_DIR` under scratch), and the core packed and installed, followed by +`agent-device plugins add ./vega.tgz`. The Vega CLI was reachable through the host `PATH` only — the +plugin resolved it with the `isExecutableOnPath` port of the host it was set up with. Every CLI call +ran with `--debug`, so each request wrote its own exec trace. + +``` +########## agent-device devices --platform vega --json +{ + "success": true, + "data": { + "devices": [ + { "platform": "vega", "id": "VirtualDevice", "name": "Vega Virtual Device (VirtualDevice)", + "kind": "emulator", "target": "tv", "booted": true } + ] + } +} + +########## agent-device open com.amazondeveloper.keplersampleapp.main --platform vega --target tv --json +{ + "success": true, + "data": { + "session": "default", + "appName": "com.amazondeveloper.keplersampleapp.main", + "selection": { "reason": "single-booted-local", "source": "local", + "candidateCount": 1, "bootOccurred": false }, + "startup": { "durationMs": 1321, "method": "open-command-roundtrip", + "appTarget": "com.amazondeveloper.keplersampleapp.main" }, + "platform": "vega", "target": "tv", + "device": "Vega Virtual Device (VirtualDevice)", "id": "VirtualDevice", + "kind": "emulator", "serial": "VirtualDevice", + "message": "Opened: com.amazondeveloper.keplersampleapp.main" + } +} + +########## agent-device tv-remote press down --platform vega --target tv --json +{ "success": true, "data": { "action": "tv-remote", "button": "down", + "message": "Pressed TV remote down" } } + +########## agent-device close com.amazondeveloper.keplersampleapp.main --platform vega --target tv --json +{ "success": true, "data": { "session": "default", "message": "Closed: default" } } +``` + +Each CLI reply was then corroborated against the device with the SDK itself, on the same store and +the same packed plugin, in a second pass over the same four steps. `agent-device open`, then a direct +SDK read, then a direct injection, then `agent-device close`, then a direct read again: + +``` +$ agent-device open com.amazondeveloper.keplersampleapp.main --platform vega --target tv +$ vega device is-app-running --device VirtualDevice --appName com.amazondeveloper.keplersampleapp.main +com.amazondeveloper.keplersampleapp.main is running on VirtualDevice +$ vega device run-cmd --device VirtualDevice --command "inputd-cli button_press KEY_DOWN" +Injecting Button Press As Driver: KEY_DOWN State: short +$ agent-device close com.amazondeveloper.keplersampleapp.main --platform vega --target tv +$ vega device is-app-running --device VirtualDevice --appName com.amazondeveloper.keplersampleapp.main +com.amazondeveloper.keplersampleapp.main is not running on VirtualDevice +``` + +The two `is-app-running` answers are the device-side claim: the packed plugin's `open` put the app on +screen and its `close` took it off, as read by the SDK rather than by the plugin that did it. + +The exec trace of the same four requests, as `--debug` wrote them. Every `vega` call the packed +bundle made is recorded under the request that asked for it, which is what binding to the setup host +buys — a plugin that spawned through its bundled host-kit copy would trace nothing here: + +``` +{"phase":"exec_command","requestId":"2f356971c3034976","command":"devices","data":{"execId":"70141990-…","command":"vega","event":"spawn","pid":85720,"timeoutMs":10000}} +{"phase":"exec_command","requestId":"2f356971c3034976","command":"devices","data":{"execId":"70141990-…","command":"vega","event":"exit","pid":85720,"timeoutMs":10000,"exitCode":0}} +{"phase":"exec_command","requestId":"c6d9c65e55209661","command":"open","data":{"execId":"12d8c00e-…","command":"vega","event":"spawn","pid":86023,"timeoutMs":10000}} +{"phase":"exec_command","requestId":"c6d9c65e55209661","command":"open","data":{"execId":"e66c8496-…","command":"vega","event":"spawn","pid":86182,"timeoutMs":30000}} +{"phase":"exec_command","requestId":"c6d9c65e55209661","command":"open","data":{"execId":"e66c8496-…","command":"vega","event":"exit","pid":86182,"timeoutMs":30000,"exitCode":0}} +{"phase":"exec_command","requestId":"30e92cbe08c4582a","command":"tv-remote","data":{"execId":"fb8d3455-…","command":"vega","event":"spawn","pid":86755,"timeoutMs":10000}} +{"phase":"exec_command","requestId":"30e92cbe08c4582a","command":"tv-remote","data":{"execId":"fb8d3455-…","command":"vega","event":"exit","pid":86755,"timeoutMs":10000,"exitCode":0}} +{"phase":"exec_command","requestId":"ecedebbd06e541fd","command":"close","data":{"execId":"6f9bac6a-…","command":"vega","event":"spawn","pid":87108,"timeoutMs":30000}} +{"phase":"exec_command","requestId":"ecedebbd06e541fd","command":"close","data":{"execId":"6f9bac6a-…","command":"vega","event":"exit","pid":87108,"timeoutMs":30000,"exitCode":0}} +``` + +## Packed plugin, one stub Vega CLI, and what the live run does not cover + +`packages/platform-vega/test/package-smoke.mjs` runs this as a gate inside `pnpm run check:package`: +discovery, `open`, a remote press, and `close`, each asserted on the argv a stub Vega CLI recorded and +on the `PATH` and `HOME` that reached it, plus the per-request exec trace above. The stub is written +into a directory that is on the launched host `PATH` and nowhere else, so every call that reaches it +came through the plugin's own resolution. The gate was confirmed to fail on the pre-fix base: the +interactor's own calls answered the replies but left the request with zero exec records. + +The live run above covers what a stub cannot: real `vega device list` and `launch-app` output shapes, +real `inputd-cli button_press KEY_DOWN` injection on a booted image, and the daemon adopting a device +it did not start. What it does not cover is the failure paths — a CLI that is not on `PATH`, a CLI +that exits non-zero, a device that disappears mid-interaction — which stay covered by the plugin's +unit tests and the packed stub, where each is asserted on its recorded argv. diff --git a/docs/evidence/web-managed-platform-2026-11-21.md b/docs/evidence/web-managed-platform-2026-11-21.md new file mode 100644 index 0000000000..eea3d2ac09 --- /dev/null +++ b/docs/evidence/web-managed-platform-2026-11-21.md @@ -0,0 +1,139 @@ +# Web managed platform plugin — packed-plugin evidence (2026-11-21) + +Head: `fix/0.22-web-vega-plugin-host-routing`. Issue #4862. Stacked on #4857. + +## No real browser involved, by design + +The web family's tool is the managed `agent-browser` backend the plugin installs under the store. A +real browser install needs a network fetch and a Chrome download, and its replies are not stable +enough to assert on, so both the gate and this manual run answer with a stub over the fixture install +the test kit already writes (`packages/test-kit/src/web-managed-agent-browser.ts`): the same entry +script path, the same console shim, and the same runtime home and socket directories the plugin builds +for a real install. Nothing about the route under test depends on what answers behind that entry. + +What follows is a manual run of the packed plugin against that stub on this host, kept because it +shows the raw replies, the environment that reached the backend, and the exec trace — none of which +the gate prints. + +Setup: a scratch project, an isolated store (`AGENT_DEVICE_HOME`, `AGENT_DEVICE_STATE_DIR`, +`AGENT_DEVICE_CLAIMS_DIR` under scratch), `PATH` reduced to the Node directory, `/usr/bin` and `/bin`, +the core packed and installed, then `agent-device plugins add ./web.tgz`. The stub entry records every +invocation with the `HOME` and `AGENT_BROWSER_SOCKET_DIR` it was handed. Every CLI call ran with +`--debug`. + +``` +########## agent-device devices --platform web --json +{ + "success": true, + "data": { + "devices": [ + { "platform": "web", "id": "agent-browser-chrome", "name": "Agent Browser Chrome", + "kind": "device", "target": "desktop", "booted": true } + ] + } +} + +########## agent-device web doctor --json +{ + "success": true, + "data": { + "status": { + "version": "0.39.0", + "installed": true, "nodeMajor": 26, "nodeSupported": true, + "entryScript": "/tmp/weblive/state/tools/agent-browser/0.39.0/package/node_modules/agent-browser/dist/cli.js" + }, + "stdout": "{\"success\":true,\"data\":{}}\n", "stderr": "", "exitCode": 0 + } +} + +########## agent-device open https://example.test --platform web --json +{ + "success": true, + "data": { + "session": "web-evidence", + "appName": "https://example.test", + "selection": { "reason": "single-booted-local", "source": "local", + "candidateCount": 1, "bootOccurred": false }, + "startup": { "durationMs": 506, "method": "open-command-roundtrip", + "appTarget": "https://example.test" }, + "platform": "web", "target": "desktop", "device": "Agent Browser Chrome", + "id": "agent-browser-chrome:session:p_web-evidence", "kind": "device", + "message": "Opened: https://example.test" + } +} + +########## agent-device press 100 200 --platform web --json +{ "success": true, "data": { "x": 100, "y": 200, "message": "Tapped (100, 200)", "targetKind": "point" } } + +########## agent-device screenshot /tmp/weblive/shot.png --platform web --json +{ "success": true, "data": { "path": "/tmp/weblive/shot.png" } } + +########## agent-device snapshot --platform web --json +{ + "success": true, + "data": { + "nodes": [], "truncated": false, "appName": "https://example.test", + "snapshotDiagnostics": { + "stats": { "count": 1, "p50Ms": 433, "p95Ms": 433, "maxMs": 433, + "slowThresholdMs": 1500, "platform": "web", + "backends": { "agent-browser": 1 } } + } + } +} + +########## agent-device close --platform web --json +{ "success": true, "data": { "session": "web-evidence", "message": "Closed: web-evidence" } } +``` + +Every managed-backend call the packed bundle made, with the environment it was handed (the stub's own +record). Each call was spawned as `node `, so the record shows argv plus the managed home +and socket dir the plugin built — both reached the child, on every call: + +``` +ARGS: doctor --offline --quick +ARGS: open https://example.test --json --session p_web-evidence +ARGS: mouse move 100 200 --json --session p_web-evidence +ARGS: mouse down --json --session p_web-evidence +ARGS: mouse up --json --session p_web-evidence +ARGS: screenshot /tmp/weblive/shot.png --json --session p_web-evidence +ARGS: snapshot --json --session p_web-evidence +ARGS: close --json --session p_web-evidence + +HOME: /var/folders/…/T/agent-device-web/76dbf75458e3 (every call) +SOCKET: /var/folders/…/T/adw/76dbf75458e3 (every call) +``` + +The exec trace of those requests, as `--debug` wrote them. Two commands matter here for different +reasons. `open` shows the backend spawn plus the process-table read that derives the owned-process +record — that read is the call no backend reply can show, and it goes through the host's +`listHostProcesses` port. `press` shows the three-spawn pointer sequence attributed to one request: + +``` +{"phase":"exec_command","requestId":"f178ac3051b20133","command":"open","data":{"execId":"cd318f35-…","command":"node","event":"spawn","pid":13307,"timeoutMs":30000}} +{"phase":"exec_command","requestId":"f178ac3051b20133","command":"open","data":{"execId":"23873a98-…","command":"ps","event":"spawn","pid":13309,"timeoutMs":1500}} +{"phase":"exec_command","requestId":"5fc832773ef73f6e","command":"press","data":{"execId":"23d67b87-…","command":"node","event":"spawn","pid":13368,"timeoutMs":30000}} +{"phase":"exec_command","requestId":"5fc832773ef73f6e","command":"press","data":{"execId":"79ff9a96-…","command":"node","event":"spawn","pid":13391,"timeoutMs":30000}} +{"phase":"exec_command","requestId":"5fc832773ef73f6e","command":"press","data":{"execId":"c8a3a2e3-…","command":"node","event":"spawn","pid":13417,"timeoutMs":30000}} +``` + +The interactor's capture timer reports through the host as well, so one timing record is attributed to +the request that asked for the capture: + +``` +{"phase":"snapshot_capture","requestId":"abc60ce021b914f9","command":"snapshot","durationMs":433,"data":{"backend":"web"}} +``` + +## Packed gate and what this does not cover + +`packages/platform-web/test/package-smoke.mjs` runs the same interaction as a gate inside +`pnpm run check:package`, asserting the recorded argv, the managed home and socket dir on every call, +the per-request exec records, and the capture timing. The gate was confirmed to fail on the pre-fix +base on the one call no backend reply can show: the `open` request traced its backend spawn but no +process-table read, because the fleet-record scan went to the bundle's own copy of the store. + +Proves: the packed plugin spawns the managed backend, builds its managed environment, reads the host +process table, and times a capture — all on the host it was set up with, all attributable to the +request that asked for it. + +Does not prove anything about a real browser: page content, real DOM snapshot shape, real capture +encoding, ref rects, and network interception are unchanged by this refactor and unverified by it. diff --git a/packages/contracts/src/platform-runtime-host.ts b/packages/contracts/src/platform-runtime-host.ts index 1a2d51b01e..2426588aba 100644 --- a/packages/contracts/src/platform-runtime-host.ts +++ b/packages/contracts/src/platform-runtime-host.ts @@ -179,7 +179,8 @@ export type DeviceInventoryHostByFamily = Readonly<{ android: Pick; /** The HarmonyOS plugin carries its own host, so its inventory asks the core for nothing. */ harmonyos: never; - vega: Pick; + /** The Vega plugin carries its own host, so its inventory asks the core for nothing. */ + vega: never; linux: Pick; web: never; }>; diff --git a/packages/contracts/src/vega-tool-provider.ts b/packages/contracts/src/vega-tool-provider.ts index e87e191f8b..522afe9a7a 100644 --- a/packages/contracts/src/vega-tool-provider.ts +++ b/packages/contracts/src/vega-tool-provider.ts @@ -7,9 +7,11 @@ export type VegaCommandResult = Readonly<{ exitCode: number; }>; -/** How one Vega CLI call runs. */ +/** + * How one Vega CLI call runs. The environment and the working directory are not among them: the host + * the plugin was set up with owns both, so a Vega call never inherits a directory no host named. + */ export type VegaCommandOptions = Readonly<{ - cwd?: string; allowFailure?: boolean; timeoutMs?: number; signal?: AbortSignal; diff --git a/packages/device-selection/src/composed-inventory-gateways.ts b/packages/device-selection/src/composed-inventory-gateways.ts index 156e05bed2..7d839d13cd 100644 --- a/packages/device-selection/src/composed-inventory-gateways.ts +++ b/packages/device-selection/src/composed-inventory-gateways.ts @@ -159,7 +159,8 @@ async function loadFamilyInventory( // The HarmonyOS plugin holds the host it was set up with, so it loads with nothing. return await module.loadInventory(); case 'vega': - return await module.loadInventory(vegaInventoryHost(await requiredHost())); + // The Vega plugin holds the host it was set up with, so it loads with nothing. + return await module.loadInventory(); case 'linux': return await module.loadInventory(linuxInventoryHost(await requiredHost())); case 'web': @@ -186,14 +187,6 @@ function androidInventoryHost(host: DeviceInventoryHost): DeviceInventoryHostFor }); } -function vegaInventoryHost(host: DeviceInventoryHost): DeviceInventoryHostFor<'vega'> { - return Object.freeze({ - commands: host.commands, - files: host.files, - homeDirectory: host.homeDirectory, - }); -} - function linuxInventoryHost(host: DeviceInventoryHost): DeviceInventoryHostFor<'linux'> { return Object.freeze({ hostName: host.hostName, hostOs: host.hostOs }); } diff --git a/packages/kernel/src/errors.ts b/packages/kernel/src/errors.ts index fafb16082d..c8660b2bf1 100644 --- a/packages/kernel/src/errors.ts +++ b/packages/kernel/src/errors.ts @@ -453,6 +453,56 @@ export function errorMessage(error: unknown): string { return error instanceof Error ? error.message : String(error); } +/** + * What a process answered, which is what an exec failure has to report: the two streams and how the + * process exited. `exitCode` is null for a process ended by a signal, mirroring `child_process`. + */ +export type CommandFailureAnswer = Readonly<{ + stdout: string; + stderr: string; + exitCode: number | null; +}>; + +/** + * Details for a command that ran and exited badly, so `normalizeError` can surface the stderr + * excerpt. Build every wrap of a real process exit from here (or from `requireCommandSuccess`) + * rather than by spreading the trio, which is how a wrap ends up reporting only an exit code. + * + * `@agent-device/host-kit/command`'s `execFailureDetails` and `requireExecSuccess` add the host's own + * toolchain reading on top of these details. A caller that holds only a command result and no host — + * a platform plugin whose commands answer through its `PlatformHost` — uses this, since the trio and + * its flag belong to the error, not to the module that ran the process. + */ +export function commandFailureDetails( + answer: CommandFailureAnswer, + extra?: Record, +): Record { + return { + stdout: answer.stdout, + stderr: answer.stderr, + exitCode: answer.exitCode, + processExitError: true, + ...extra, + }; +} + +/** + * Raises `COMMAND_FAILED` for a non-zero answer, keeping the streams for `normalizeError`, and + * passes a zero answer through unchanged. A functional `extra` is evaluated only on failure. + */ +export function requireCommandSuccess( + answer: R, + message: string, + extra?: Record | ((answer: R) => Record), +): R { + if (answer.exitCode === 0) return answer; + throw new AppError( + 'COMMAND_FAILED', + message, + commandFailureDetails(answer, typeof extra === 'function' ? extra(answer) : extra), + ); +} + /** One command a retry loop ran and could not make succeed, kept in the tool's own terms. */ export type CommandAttemptFailure = { args: readonly string[]; diff --git a/packages/platform-harmonyos/src/index.test.ts b/packages/platform-harmonyos/src/index.test.ts index 0cb02577f1..1da09f10d4 100644 --- a/packages/platform-harmonyos/src/index.test.ts +++ b/packages/platform-harmonyos/src/index.test.ts @@ -4,7 +4,7 @@ import type { DeviceInfo } from '@agent-device/kernel/device'; import type { HarmonyPlatformRegistration } from '@agent-device/contracts/platform-plugin'; import type { PlatformHost } from 'agent-device/plugins'; import { emitDiagnostic, withDiagnosticTimer } from '@agent-device/host-kit/diagnostics'; -import { isExecutablePath } from '@agent-device/host-kit/command'; +import { isExecutablePath, whichCmd } from '@agent-device/host-kit/command'; import path from 'node:path'; import harmonyPlatformPlugin from './index.ts'; import { createHarmonyToolchainRoot } from './toolbox.fixtures.ts'; @@ -41,6 +41,8 @@ function createPluginHost( // The real host probe: a test that names a toolchain root proves the plugin resolves HDC from // a file on disk, not from a verdict this fixture hands it. isFileExecutable: isExecutablePath, + isExecutableOnPath: async (executable) => (await whichCmd(executable, env)) !== undefined, + listHostProcesses: async () => [], emitDiagnostic, withDiagnosticTimer, }; diff --git a/packages/platform-vega/src/__tests__/app-lifecycle.test.ts b/packages/platform-vega/src/__tests__/app-lifecycle.test.ts index 8ba2bc24f2..5a0320b356 100644 --- a/packages/platform-vega/src/__tests__/app-lifecycle.test.ts +++ b/packages/platform-vega/src/__tests__/app-lifecycle.test.ts @@ -1,27 +1,24 @@ import assert from 'node:assert/strict'; import { test } from 'vitest'; +import { createVegaCommandRunnerStub } from '../command-host.fixtures.ts'; import { closeVegaApp, openVegaApp, openVegaDevice } from '../app-lifecycle.ts'; -import { createLocalVegaToolProvider, withVegaToolProvider } from '../tool-provider.ts'; +import { createVegaToolProvider, withVegaToolProvider } from '../tool-provider.ts'; test('Vega app lifecycle uses the SDK device commands with an explicit serial', async () => { - const commands: string[][] = []; - const provider = createLocalVegaToolProvider({ - isAvailable: async () => true, - run: async (args) => { - commands.push(args); - return { exitCode: 0, stdout: '', stderr: '' }; - }, - }); + const commands = createVegaCommandRunnerStub(); - await withVegaToolProvider(provider, async () => { + await withVegaToolProvider(createVegaToolProvider(commands), async () => { await openVegaDevice({ id: 'amazon-vvd' }); await openVegaApp({ id: 'amazon-vvd' }, 'com.example.app.main'); await closeVegaApp({ id: 'amazon-vvd' }, 'com.example.app.main'); }); - assert.deepEqual(commands, [ - ['device', 'is-connected', '--device', 'amazon-vvd'], - ['device', 'launch-app', '--device', 'amazon-vvd', '--appName', 'com.example.app.main'], - ['device', 'terminate-app', '--device', 'amazon-vvd', '--appName', 'com.example.app.main'], - ]); + assert.deepEqual( + commands.calls.map(({ args }) => args), + [ + ['device', 'is-connected', '--device', 'amazon-vvd'], + ['device', 'launch-app', '--device', 'amazon-vvd', '--appName', 'com.example.app.main'], + ['device', 'terminate-app', '--device', 'amazon-vvd', '--appName', 'com.example.app.main'], + ], + ); }); diff --git a/packages/platform-vega/src/__tests__/doctor.test.ts b/packages/platform-vega/src/__tests__/doctor.test.ts index c460fef116..88a8a823ac 100644 --- a/packages/platform-vega/src/__tests__/doctor.test.ts +++ b/packages/platform-vega/src/__tests__/doctor.test.ts @@ -4,13 +4,15 @@ import type { DeviceInfo } from '@agent-device/kernel/device'; import { AppError, isRequestCanceledError } from '@agent-device/kernel/errors'; import type { DoctorCheck } from '@agent-device/contracts/observability'; import type { HostDiagnosticsContext } from '@agent-device/contracts/host-diagnostics'; -import type { HostEnvironment } from '@agent-device/kernel/source-value'; import type { VegaToolProvider } from '@agent-device/contracts/vega-tool-provider'; +import { createVegaCommandRunnerStub } from '../command-host.fixtures.ts'; import { withVegaToolProvider } from '../tool-provider.ts'; import { vegaToolchainCheck } from '../doctor.ts'; -// Doctor resolves against the host it is handed; a scoped test provider still wins. -const DOCTOR_HOST: HostEnvironment = { env: process.env, cwd: process.cwd() }; +// Doctor runs on the plugin's command route; a scoped test provider still wins. +function doctorCommands() { + return createVegaCommandRunnerStub(); +} function contextWith(local: () => Promise): HostDiagnosticsContext { return Object.freeze({ @@ -41,7 +43,7 @@ test('Vega doctor reports CLI version and connected-device readiness through sem const check = await withVegaToolProvider(makeVegaProvider(), async () => vegaToolchainCheck( contextWith(async () => [VEGA_VVD]), - DOCTOR_HOST, + doctorCommands(), ), ); @@ -67,7 +69,7 @@ test('Vega doctor does not report an unvalidated physical TV as supported readin { listedSerials: ['G071R20720350DT6'] }, ); }), - DOCTOR_HOST, + doctorCommands(), ), ); @@ -86,7 +88,7 @@ test('Vega doctor propagates canonical request cancellation', async () => { contextWith(async () => { throw new AppError('COMMAND_FAILED', 'request canceled'); }), - DOCTOR_HOST, + doctorCommands(), ), ), (error: unknown) => error instanceof AppError && error.message === 'request canceled', @@ -102,7 +104,7 @@ test('Vega doctor propagates missing request inventory context', async () => { reason: 'device_inventory_context_unavailable', }); }), - DOCTOR_HOST, + doctorCommands(), ), ), (error: unknown) => @@ -120,7 +122,7 @@ test('Vega doctor preserves the missing-tool diagnostic without probing inventor contextWith(async () => { throw new Error('inventory must not be probed'); }), - DOCTOR_HOST, + doctorCommands(), ), ); @@ -143,7 +145,7 @@ test('Vega doctor keeps version failures diagnostic when neutral inventory fails contextWith(async () => { throw new Error('inventory failed'); }), - DOCTOR_HOST, + doctorCommands(), ), ); diff --git a/packages/platform-vega/src/__tests__/input-actions.test.ts b/packages/platform-vega/src/__tests__/input-actions.test.ts index bf77a91e7a..60647c7fd9 100644 --- a/packages/platform-vega/src/__tests__/input-actions.test.ts +++ b/packages/platform-vega/src/__tests__/input-actions.test.ts @@ -2,19 +2,13 @@ import assert from 'node:assert/strict'; import { test } from 'vitest'; import { AppError } from '@agent-device/kernel/errors'; import { pressVegaTvRemote } from '../input-actions.ts'; -import { createLocalVegaToolProvider, withVegaToolProvider } from '../tool-provider.ts'; +import { createVegaCommandRunnerStub } from '../command-host.fixtures.ts'; +import { createVegaToolProvider, withVegaToolProvider } from '../tool-provider.ts'; test('pressVegaTvRemote maps every shared button without leaking key names to callers', async () => { - const commands: string[][] = []; - const provider = createLocalVegaToolProvider({ - isAvailable: async () => true, - run: async (args) => { - commands.push(args); - return { exitCode: 0, stdout: '', stderr: '' }; - }, - }); + const commands = createVegaCommandRunnerStub(); - await withVegaToolProvider(provider, async () => { + await withVegaToolProvider(createVegaToolProvider(commands), async () => { for (const button of [ 'up', 'down', @@ -30,7 +24,7 @@ test('pressVegaTvRemote maps every shared button without leaking key names to ca }); assert.deepEqual( - commands.map((args) => args.at(-1)), + commands.calls.map(({ args }) => args.at(-1)), [ 'inputd-cli button_press KEY_UP', 'inputd-cli button_press KEY_DOWN', @@ -45,21 +39,14 @@ test('pressVegaTvRemote maps every shared button without leaking key names to ca }); test('pressVegaTvRemote passes exact hold duration boundaries to inputd', async () => { - const calls: Array<{ args: string[]; timeoutMs?: number }> = []; - const provider = createLocalVegaToolProvider({ - isAvailable: async () => true, - run: async (args, options) => { - calls.push({ args, timeoutMs: options?.timeoutMs }); - return { exitCode: 0, stdout: '', stderr: '' }; - }, - }); + const commands = createVegaCommandRunnerStub(); - await withVegaToolProvider(provider, async () => { + await withVegaToolProvider(createVegaToolProvider(commands), async () => { await pressVegaTvRemote({ id: 'VirtualDevice' }, 'select', 0); await pressVegaTvRemote({ id: 'VirtualDevice' }, 'select', 10_000); }); - assert.deepEqual(calls, [ + assert.deepEqual(commands.calls, [ { args: [ 'device', @@ -70,6 +57,7 @@ test('pressVegaTvRemote passes exact hold duration boundaries to inputd', async 'inputd-cli button_press KEY_ENTER --holdDuration 0', ], timeoutMs: 10_000, + allowFailure: true, }, { args: [ @@ -81,22 +69,18 @@ test('pressVegaTvRemote passes exact hold duration boundaries to inputd', async 'inputd-cli button_press KEY_ENTER --holdDuration 10000', ], timeoutMs: 20_000, + allowFailure: true, }, ]); }); test('pressVegaTvRemote surfaces unsupported inputd controls as command failures', async () => { - const provider = createLocalVegaToolProvider({ - isAvailable: async () => true, - run: async () => ({ - exitCode: 2, - stdout: '', - stderr: 'Unsupported key', - }), - }); + const commands = createVegaCommandRunnerStub([ + { exitCode: 2, stdout: '', stderr: 'Unsupported key' }, + ]); await assert.rejects( - withVegaToolProvider(provider, async () => { + withVegaToolProvider(createVegaToolProvider(commands), async () => { await pressVegaTvRemote({ id: 'VirtualDevice' }, 'menu'); }), (error: unknown) => diff --git a/packages/platform-vega/src/__tests__/tool-provider-host-isolation.test.ts b/packages/platform-vega/src/__tests__/tool-provider-host-isolation.test.ts deleted file mode 100644 index 0ba4af0221..0000000000 --- a/packages/platform-vega/src/__tests__/tool-provider-host-isolation.test.ts +++ /dev/null @@ -1,105 +0,0 @@ -import assert from 'node:assert/strict'; -import { mkdirSync, rmSync, writeFileSync, chmodSync } from 'node:fs'; -import path from 'node:path'; -import { afterAll, beforeEach, test, vi } from 'vitest'; -import type { HostEnvironment } from '@agent-device/kernel/source-value'; -import { mkdtempForTestSync } from './tmp-dir.ts'; - -vi.mock('@agent-device/host-kit/command', async (importOriginal) => { - const actual = await importOriginal(); - return { ...actual, runCmd: vi.fn(), whichCmd: vi.fn() }; -}); - -import { runCmd, whichCmd } from '@agent-device/host-kit/command'; -import { createLocalVegaCliAdapter, createLocalVegaToolProvider } from '../tool-provider.ts'; - -const mockRunCmd = vi.mocked(runCmd); -const mockWhichCmd = vi.mocked(whichCmd); - -const scratch = mkdtempForTestSync('vega-host-isolation-'); -afterAll(() => { - rmSync(scratch, { recursive: true, force: true }); -}); - -/** A real executable file so the default-install probe answers on the filesystem, not on mocks. */ -function makeExecutable(filePath: string): void { - mkdirSync(path.dirname(filePath), { recursive: true }); - writeFileSync(filePath, '#!/bin/sh\nexit 0\n'); - chmodSync(filePath, 0o755); -} - -const hostAPathDir = path.join(scratch, 'host-a', 'bin'); -const hostBHome = path.join(scratch, 'host-b', 'home'); -makeExecutable(path.join(hostAPathDir, 'vega')); -makeExecutable(path.join(hostBHome, 'vega', 'bin', 'vega')); - -// Two independent hosts. Runtime A carries vega on its PATH; runtime B carries it only under -// its own HOME default install. Neither host sees the other's location, and the process PATH -// and HOME name a third location with no vega at all, so any answer read from the process -// instead of the runtime host is wrong here. -const hostA: HostEnvironment = { - env: { PATH: hostAPathDir, HOME: path.join(scratch, 'host-a', 'home') }, - cwd: scratch, -}; -const hostB: HostEnvironment = { - env: { PATH: path.join(scratch, 'empty-bin'), HOME: hostBHome }, - cwd: scratch, -}; - -beforeEach(() => { - mockRunCmd.mockReset(); - mockWhichCmd.mockReset(); - // PATH lookups answer from the environment passed in, like the real whichCmd: only host A's - // PATH carries vega. - mockWhichCmd.mockImplementation(async (cmd: string, env: NodeJS.ProcessEnv) => - Boolean(cmd === 'vega' && env?.PATH?.includes(hostAPathDir)), - ); - mockRunCmd.mockResolvedValue({ exitCode: 0, stdout: '', stderr: '' }); -}); - -test('two hosts sharing the process resolve the vega executable from their own host', async () => { - const providerA = createLocalVegaToolProvider(createLocalVegaCliAdapter(hostA)); - const providerB = createLocalVegaToolProvider(createLocalVegaCliAdapter(hostB)); - - assert.equal(await providerA.isAvailable(), true); - assert.equal(await providerB.isAvailable(), true); - - // Resolve B first through a run, then A: each must invoke the executable named by its own - // host — A the PATH entry, B the HOME default-install path. Under a shared module cache the - // second resolution would reuse the first host's answer. - await providerB.version(); - await providerA.version(); - - const executables = mockRunCmd.mock.calls.map(([executable]) => executable); - assert.deepEqual(executables, [path.join(hostBHome, 'vega', 'bin', 'vega'), 'vega']); - - // The memo lives on each adapter instance: a later call never re-probes and never reads the - // other host's answer. - mockWhichCmd.mockReset(); - await providerA.version(); - await providerB.version(); - assert.equal(mockWhichCmd.mock.calls.length, 0); - assert.deepEqual( - mockRunCmd.mock.calls.slice(2).map(([executable]) => executable), - ['vega', path.join(hostBHome, 'vega', 'bin', 'vega')], - ); -}); - -test('a host without the vega executable refuses, and the refusal is not memoized', async () => { - // Host C names no home at all; host D names a HOME with no default install. Neither PATH - // carries vega, so both report unavailable — and each later call re-probes, so a tool - // installed after the miss is still found. - const hostC: HostEnvironment = { env: { PATH: path.join(scratch, 'empty-bin') }, cwd: scratch }; - const hostD: HostEnvironment = { - env: { PATH: path.join(scratch, 'empty-bin'), HOME: path.join(scratch, 'host-d', 'home') }, - cwd: scratch, - }; - const providerC = createLocalVegaToolProvider(createLocalVegaCliAdapter(hostC)); - const providerD = createLocalVegaToolProvider(createLocalVegaCliAdapter(hostD)); - - assert.equal(await providerC.isAvailable(), false); - assert.equal(await providerD.isAvailable(), false); - assert.equal(await providerD.isAvailable(), false); - // One PATH probe per call: the second miss on D re-probed instead of trusting a memo. - assert.equal(mockWhichCmd.mock.calls.length, 3); -}); diff --git a/packages/platform-vega/src/__tests__/tool-provider.test.ts b/packages/platform-vega/src/__tests__/tool-provider.test.ts index f5f2db01b7..39a3426454 100644 --- a/packages/platform-vega/src/__tests__/tool-provider.test.ts +++ b/packages/platform-vega/src/__tests__/tool-provider.test.ts @@ -1,16 +1,11 @@ import assert from 'node:assert/strict'; import { test } from 'vitest'; -import { createLocalVegaToolProvider } from '../tool-provider.ts'; +import { createVegaCommandRunnerStub } from '../command-host.fixtures.ts'; +import { createVegaToolProvider } from '../tool-provider.ts'; test('local Vega provider owns CLI argv for each semantic operation', async () => { - const commands: string[][] = []; - const provider = createLocalVegaToolProvider({ - isAvailable: async () => true, - run: async (args) => { - commands.push(args); - return { exitCode: 0, stdout: '', stderr: '' }; - }, - }); + const commands = createVegaCommandRunnerStub(); + const provider = createVegaToolProvider(commands); await provider.version(); await provider.listDevices(); @@ -19,19 +14,22 @@ test('local Vega provider owns CLI argv for each semantic operation', async () = await provider.pressRemote('VirtualDevice', 'KEY_ENTER', 800); await provider.terminateApp('VirtualDevice', 'com.example.main'); - assert.deepEqual(commands, [ - ['--version'], - ['device', 'list'], - ['device', 'is-connected', '--device', 'VirtualDevice'], - ['device', 'launch-app', '--device', 'VirtualDevice', '--appName', 'com.example.main'], + assert.deepEqual( + commands.calls.map(({ args }) => args), [ - 'device', - 'run-cmd', - '--device', - 'VirtualDevice', - '--command', - 'inputd-cli button_press KEY_ENTER --holdDuration 800', + ['--version'], + ['device', 'list'], + ['device', 'is-connected', '--device', 'VirtualDevice'], + ['device', 'launch-app', '--device', 'VirtualDevice', '--appName', 'com.example.main'], + [ + 'device', + 'run-cmd', + '--device', + 'VirtualDevice', + '--command', + 'inputd-cli button_press KEY_ENTER --holdDuration 800', + ], + ['device', 'terminate-app', '--device', 'VirtualDevice', '--appName', 'com.example.main'], ], - ['device', 'terminate-app', '--device', 'VirtualDevice', '--appName', 'com.example.main'], - ]); + ); }); diff --git a/packages/platform-vega/src/app-lifecycle.ts b/packages/platform-vega/src/app-lifecycle.ts index 1b8595260d..42d05e2908 100644 --- a/packages/platform-vega/src/app-lifecycle.ts +++ b/packages/platform-vega/src/app-lifecycle.ts @@ -1,15 +1,16 @@ import type { DeviceInfo } from '@agent-device/kernel/device'; -import { requireExecSuccess, type ExecOptions } from '@agent-device/host-kit/command'; +import { requireCommandSuccess } from '@agent-device/kernel/errors'; import { resolveVegaToolProvider } from './tool-provider.ts'; +import type { VegaCommandOptions } from '@agent-device/contracts/vega-tool-provider'; const VEGA_APP_COMMAND_TIMEOUT_MS = 30_000; const VEGA_APP_COMMAND_OPTIONS = { allowFailure: true, timeoutMs: VEGA_APP_COMMAND_TIMEOUT_MS, -} satisfies ExecOptions; +} satisfies VegaCommandOptions; export async function openVegaApp(device: Pick, appName: string): Promise { - requireExecSuccess( + requireCommandSuccess( await resolveVegaToolProvider().launchApp(device.id, appName, VEGA_APP_COMMAND_OPTIONS), `Failed to launch Vega app ${appName}`, { appName, deviceId: device.id }, @@ -17,7 +18,7 @@ export async function openVegaApp(device: Pick, appName: strin } export async function openVegaDevice(device: Pick): Promise { - requireExecSuccess( + requireCommandSuccess( await resolveVegaToolProvider().checkConnected(device.id, VEGA_APP_COMMAND_OPTIONS), 'Vega device is not connected', { deviceId: device.id }, @@ -25,7 +26,7 @@ export async function openVegaDevice(device: Pick): Promise, appName: string): Promise { - requireExecSuccess( + requireCommandSuccess( await resolveVegaToolProvider().terminateApp(device.id, appName, VEGA_APP_COMMAND_OPTIONS), `Failed to terminate Vega app ${appName}`, { appName, deviceId: device.id }, diff --git a/packages/platform-vega/src/command-host.fixtures.ts b/packages/platform-vega/src/command-host.fixtures.ts new file mode 100644 index 0000000000..eadfdd387e --- /dev/null +++ b/packages/platform-vega/src/command-host.fixtures.ts @@ -0,0 +1,157 @@ +import fs from 'node:fs'; +import path from 'node:path'; +import { mkdtempForTestSync } from './__tests__/tmp-dir.ts'; +import type { PlatformHost } from 'agent-device/plugins'; +import type { VegaCommandOptions, VegaCommandResult, VegaCommandRunner } from './command-host.ts'; +import { createVegaToolbox, type VegaToolbox } from './toolbox.ts'; + +/** One command the plugin asked its host to run, plus what the host was told about it. */ +export type VegaHostStubCommand = Readonly<{ + executable: string; + args: readonly string[]; + timeoutMs: number | undefined; + allowFailure: boolean | undefined; + signal: AbortSignal | undefined; +}>; + +export type VegaHostStub = Readonly<{ + toolbox: VegaToolbox; + host: PlatformHost; + /** Every command the plugin asked the host to run, in order. */ + commands: VegaHostStubCommand[]; + /** How many times the plugin asked the host to resolve an executable on its PATH. */ + pathProbes(): number; + /** Queues one answer for the next command; exit code 0 is the common case. */ + answer(answer?: Partial & Readonly<{ stdout?: string }>): void; +}>; + +const NO_ANSWER: VegaCommandResult = Object.freeze({ + stdout: '', + stderr: 'vega-host-stub: no answer queued', + exitCode: 1, +}); + +/** + * Binds the plugin's toolbox to an in-memory host for colocated unit tests: nothing spawns, and + * every command the plugin asks for is recorded with the executable and argv the plugin built. Tests + * assert on those, which is what this family's CLI contract is. + */ +export function createVegaHostStub( + input: Readonly<{ + env?: Readonly>; + /** The executables the host's `PATH` resolves; `['vega']` is the common case. */ + onPath?: readonly string[]; + /** Absolute paths the host finds executable, for the home's default-install probe. */ + executableFiles?: readonly string[]; + /** The stdout every command answers with, for a test about an answer rather than about argv. */ + stdout?: string; + /** Answers one command. Takes precedence over `stdout` and the queued answers. */ + respond?: ( + executable: string, + args: readonly string[], + ) => Partial & Readonly<{ stdout?: string }>; + /** Rejected one command, the way the host rejects a spawn it cannot start. */ + reject?: (executable: string, args: readonly string[]) => Error; + }> = {}, +): VegaHostStub { + const onPath = new Set(input.onPath ?? ['vega']); + const executableFiles = new Set(input.executableFiles ?? []); + const commands: VegaHostStubCommand[] = []; + const answers: VegaCommandResult[] = []; + let pathProbes = 0; + const host = Object.freeze({ + env: input.env ?? { PATH: '/usr/bin', HOME: '/host-home' }, + cwd: '/host-cwd', + stateDir: '/host-state', + emitDiagnostic: () => {}, + withDiagnosticTimer: async (_phase: string, operation: () => Promise) => + await operation(), + isFileExecutable: async (candidate: string) => executableFiles.has(candidate), + isExecutableOnPath: async (executable: string) => { + pathProbes += 1; + return onPath.has(executable); + }, + listHostProcesses: async () => [], + runCommand: async ( + executable: string, + args: string[], + options: { timeoutMs?: number; allowFailure?: boolean; signal?: AbortSignal }, + ): Promise => { + commands.push({ + executable, + args, + timeoutMs: options.timeoutMs, + allowFailure: options.allowFailure, + signal: options.signal, + }); + if (input.reject) throw input.reject(executable, args); + if (input.respond) return toResult(input.respond(executable, args)); + if (input.stdout !== undefined) return toResult({ stdout: input.stdout }); + return answers.shift() ?? NO_ANSWER; + }, + }) as unknown as PlatformHost; + return Object.freeze({ + toolbox: createVegaToolbox(host), + host, + commands, + pathProbes: () => pathProbes, + answer: (answer) => { + answers.push(toResult(answer)); + }, + }); +} + +/** One CLI call a module made through the family's command route. */ +export type VegaCommandRunnerStubCall = Readonly<{ + args: readonly string[]; + timeoutMs: number | undefined; + allowFailure: boolean | undefined; +}>; + +export type VegaCommandRunnerStub = VegaCommandRunner & + Readonly<{ calls: VegaCommandRunnerStubCall[] }>; + +/** + * The plugin's command route with recorded argv, for a test about one module's CLI calls rather than + * about the host seam. It answers queued results and nothing spawns. + */ +export function createVegaCommandRunnerStub( + answers: readonly (Partial & Readonly<{ stdout?: string }>)[] = [], +): VegaCommandRunnerStub { + const queued = answers.map(toResult); + const calls: VegaCommandRunnerStubCall[] = []; + return { + calls, + resolveExecutable: async () => 'vega', + run: async (args: readonly string[], options?: VegaCommandOptions) => { + calls.push({ args, timeoutMs: options?.timeoutMs, allowFailure: options?.allowFailure }); + return queued.shift() ?? { stdout: '', stderr: '', exitCode: 0 }; + }, + }; +} + +/** + * A Vega CLI the plugin can find: a scratch directory holding an executable `vega`, so a test that + * names a home proves the resolver answers from a file on disk rather than from a stubbed verdict. + */ +export function createVegaDefaultInstall(homeDirectory: string): string { + const install = path.join(homeDirectory, 'vega', 'bin', 'vega'); + fs.mkdirSync(path.dirname(install), { recursive: true }); + fs.writeFileSync(install, '#!/bin/sh\nexit 0\n', { mode: 0o755 }); + return install; +} + +/** A scratch host home, for a resolver test that must not read the process home. */ +export function createVegaHostHome(): string { + return mkdtempForTestSync('vega-host-home-'); +} + +function toResult( + answer?: Partial & Readonly<{ stdout?: string }>, +): VegaCommandResult { + return { + stdout: answer?.stdout ?? '', + stderr: answer?.stderr ?? '', + exitCode: answer?.exitCode ?? 0, + }; +} diff --git a/packages/platform-vega/src/command-host.test.ts b/packages/platform-vega/src/command-host.test.ts new file mode 100644 index 0000000000..d8f405bc04 --- /dev/null +++ b/packages/platform-vega/src/command-host.test.ts @@ -0,0 +1,87 @@ +import assert from 'node:assert/strict'; +import { test } from 'vitest'; +import { createVegaHostStub } from './command-host.fixtures.ts'; + +test('the command route prefers the CLI the host resolves on its PATH', async () => { + const stub = createVegaHostStub({ onPath: ['vega'], stdout: 'ok\n' }); + + assert.equal(await stub.toolbox.commands.resolveExecutable(), 'vega'); + const result = await stub.toolbox.commands.run(['--version']); + + assert.equal(result.stdout, 'ok\n'); + assert.deepEqual(stub.commands, [ + { + executable: 'vega', + args: ['--version'], + timeoutMs: undefined, + allowFailure: undefined, + signal: undefined, + }, + ]); +}); + +test('the command route falls back to the host home default install', async () => { + // The home is the one the host names, never the process's: a resolver that read `os.homedir()` + // would miss this file and report the CLI missing. + const stub = createVegaHostStub({ + env: { PATH: '/usr/bin', HOME: '/host-home' }, + onPath: [], + executableFiles: ['/host-home/vega/bin/vega'], + stdout: 'Vega CLI 1.3.2\n', + }); + + assert.equal(await stub.toolbox.commands.resolveExecutable(), '/host-home/vega/bin/vega'); + await stub.toolbox.commands.run(['--version']); + assert.equal(stub.commands[0]?.executable, '/host-home/vega/bin/vega'); +}); + +test('the command route skips the default-install probe when the host names no home', async () => { + const stub = createVegaHostStub({ env: { PATH: '/usr/bin' }, onPath: [], executableFiles: [] }); + + assert.equal(await stub.toolbox.commands.resolveExecutable(), undefined); +}); + +test('the command route memoizes a found CLI and re-probes a miss', async () => { + // A CLI installed after a miss is still found on the next call; a CLI once found is not looked up + // again, so a long-lived daemon does not pay a PATH scan per command. + const missing = createVegaHostStub({ onPath: [], executableFiles: [] }); + assert.equal(await missing.toolbox.commands.resolveExecutable(), undefined); + assert.equal(await missing.toolbox.commands.resolveExecutable(), undefined); + assert.equal(missing.pathProbes(), 2); + + const found = createVegaHostStub({ onPath: ['vega'], stdout: '' }); + await found.toolbox.commands.run(['--version']); + await found.toolbox.commands.run(['device', 'list']); + assert.equal(found.pathProbes(), 1); +}); + +test("the command route hands the host the caller's timeout, failure and cancellation terms", async () => { + const stub = createVegaHostStub({ stdout: '' }); + const signal = new AbortController().signal; + + await stub.toolbox.commands.run(['device', 'list'], { + allowFailure: true, + timeoutMs: 4_000, + signal, + }); + + assert.deepEqual(stub.commands[0], { + executable: 'vega', + args: ['device', 'list'], + timeoutMs: 4_000, + allowFailure: true, + signal, + }); +}); + +test("the command route keeps the host's answer for the caller to read", async () => { + const stub = createVegaHostStub({ + respond: () => ({ exitCode: 2, stdout: '', stderr: 'device offline' }), + }); + + const result = await stub.toolbox.commands.run(['device', 'is-connected', '--device', 'vd'], { + allowFailure: true, + }); + + assert.deepEqual(result, { exitCode: 2, stdout: '', stderr: 'device offline' }); +}); diff --git a/packages/platform-vega/src/command-host.ts b/packages/platform-vega/src/command-host.ts new file mode 100644 index 0000000000..3333df35af --- /dev/null +++ b/packages/platform-vega/src/command-host.ts @@ -0,0 +1,70 @@ +import type { PlatformHost } from 'agent-device/plugins'; +import { hostHomeDirectoryFromEnv } from '@agent-device/host-kit/host-file'; +import { resolveVegaExecutable, type VegaExecutableHost } from './vega-executable.ts'; +import type { + VegaCommandOptions, + VegaCommandResult, +} from '@agent-device/contracts/vega-tool-provider'; + +export type { + VegaCommandOptions, + VegaCommandResult, +} from '@agent-device/contracts/vega-tool-provider'; + +/** + * The plugin's route to the Vega CLI, bound to the `PlatformHost` the core handed `setup()`. The + * core owns resolving the CLI against the request environment, the spawn environment, and the exec + * trace, so a `--debug` log shows this family's CLI calls under its request id. + * + * Every call goes through that host rather than this bundle's own copy of the host kit: the daemon's + * command scope never enters the bundled copy, so a spawn made from it would run with the daemon + * process environment instead of the host environment captured for the request, and would drop this + * family's traces. + */ +export type VegaCommandRunner = Readonly<{ + /** The CLI to run: `vega` when the host's `PATH` resolves it, else the host home's default install. */ + resolveExecutable(): Promise; + /** + * Runs one CLI call through the host. A CLI the host cannot start arrives as the host's typed + * `TOOL_MISSING` rejection; {@link VegaCommandRunner.resolveExecutable} is how a caller predicts + * that before it asks for a spawn. + */ + run(args: readonly string[], options?: VegaCommandOptions): Promise; +}>; + +/** + * Binds the host the plugin was set up with. The CLI is resolved per call, so a CLI installed while a + * daemon runs is picked up without a restart. + */ +export function createVegaCommandRunner(host: PlatformHost): VegaCommandRunner { + const executableHost = vegaExecutableHost(host); + let resolved: string | undefined; + const resolveExecutable = async () => { + // Only a found CLI is memoized: a refusal is not, so a CLI installed after a miss still resolves. + if (resolved) return resolved; + resolved = await resolveVegaExecutable(executableHost); + return resolved; + }; + return Object.freeze({ + resolveExecutable, + run: async (args, options) => + await host.runCommand((await resolveExecutable()) ?? 'vega', [...args], { + ...(options?.allowFailure === undefined ? {} : { allowFailure: options.allowFailure }), + ...(options?.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }), + ...(options?.signal ? { signal: options.signal } : {}), + }), + }); +} + +/** + * The two host ports one Vega lookup needs — the host `PATH` and the host's own home — so no part of + * this family searches `PATH` or reads the process home by itself (ADR 0019). + */ +function vegaExecutableHost(host: PlatformHost): VegaExecutableHost { + return Object.freeze({ + which: async (executable: string) => + (await host.isExecutableOnPath(executable)) ? executable : undefined, + isExecutableFile: (candidate: string) => host.isFileExecutable(candidate), + homeDirectory: hostHomeDirectoryFromEnv(host.env), + }); +} diff --git a/packages/platform-vega/src/doctor.ts b/packages/platform-vega/src/doctor.ts index 2823cfdc0e..9c5246c8ed 100644 --- a/packages/platform-vega/src/doctor.ts +++ b/packages/platform-vega/src/doctor.ts @@ -2,36 +2,39 @@ import type { DeviceInfo } from '@agent-device/kernel/device'; import { AppError } from '@agent-device/kernel/errors'; import type { DoctorCheck } from '@agent-device/contracts/observability'; import type { HostDiagnosticsContext } from '@agent-device/contracts/host-diagnostics'; -import type { HostEnvironment } from '@agent-device/kernel/source-value'; import { firstOutputLine, TOOLCHAIN_TIMEOUT_MS } from '@agent-device/provision-kit/toolchain-probe'; +import { vegaDefaultInstallPath } from './vega-executable.ts'; import { - createLocalVegaCliAdapter, - createLocalVegaToolProvider, + createVegaToolProvider, hasScopedVegaToolProvider, resolveVegaToolProvider, } from './tool-provider.ts'; +import type { VegaCommandRunner } from './command-host.ts'; +import type { VegaToolProvider } from '@agent-device/contracts/vega-tool-provider'; type VegaInventoryProbe = Readonly<{ devices: readonly DeviceInfo[]; listedSerials: readonly string[]; }>; +/** + * The toolchain row `doctor --platform vega` reports. The probe runs over the plugin's own command + * route, so the version it reads is the CLI the plugin would spawn, and a CLI outside the host `PATH` + * still answers its own version. A provider the request scoped wins, as it does everywhere else. + */ export async function vegaToolchainCheck( context: HostDiagnosticsContext, - host: HostEnvironment, + commands: VegaCommandRunner, ): Promise { - // Doctor answers for the host `createHostDiagnostics` was composed with: it builds the same - // host-bound adapter the interactor route binds, so CLI resolution agrees with every other - // lookup of this runtime (#3794). A test-scoped provider still wins. - const provider = hasScopedVegaToolProvider() + const provider: VegaToolProvider = hasScopedVegaToolProvider() ? resolveVegaToolProvider() - : createLocalVegaToolProvider(createLocalVegaCliAdapter(host)); + : createVegaToolProvider(commands); if (!(await provider.isAvailable())) { return { id: 'toolchain', status: 'info', summary: 'Vega toolchain: Vega CLI not found.', - hint: 'Install Vega Developer Tools or ensure ~/vega/bin/vega is executable.', + hint: `Install Vega Developer Tools or ensure ${vegaDefaultInstallPath('~')} is executable.`, command: 'vega --version', }; } diff --git a/packages/platform-vega/src/index.test.ts b/packages/platform-vega/src/index.test.ts index 6520777503..752571e261 100644 --- a/packages/platform-vega/src/index.test.ts +++ b/packages/platform-vega/src/index.test.ts @@ -1,26 +1,12 @@ import assert from 'node:assert/strict'; -import { mkdirSync, rmSync, writeFileSync, chmodSync } from 'node:fs'; -import path from 'node:path'; -import { afterAll, beforeEach, test, vi } from 'vitest'; +import { test } from 'vitest'; import type { DeviceInfo } from '@agent-device/kernel/device'; -import type { HostEnvironment } from '@agent-device/kernel/source-value'; import type { VegaPlatformRegistration } from '@agent-device/contracts/platform-plugin'; import type { PlatformHost } from 'agent-device/plugins'; -import { mkdtempForTestSync } from './__tests__/tmp-dir.ts'; - -vi.mock('@agent-device/host-kit/command', async (importOriginal) => { - const actual = await importOriginal(); - return { ...actual, runCmd: vi.fn(), whichCmd: vi.fn() }; -}); - -import { - runCmd, - whichCmd, - withCommandHost, - isExecutablePath, -} from '@agent-device/host-kit/command'; import { emitDiagnostic, withDiagnosticTimer } from '@agent-device/host-kit/diagnostics'; +import { isExecutablePath } from '@agent-device/host-kit/command'; import vegaPlatformPlugin from './index.ts'; +import { createVegaDefaultInstall, createVegaHostHome } from './command-host.fixtures.ts'; const VEGA_VVD = { platform: 'vega', @@ -31,82 +17,54 @@ const VEGA_VVD = { booted: true, } satisfies DeviceInfo; -const mockRunCmd = vi.mocked(runCmd); -const mockWhichCmd = vi.mocked(whichCmd); - -const scratch = mkdtempForTestSync('vega-plugin-host-binding-'); -const hostAPathDir = path.join(scratch, 'host-a', 'bin'); -const hostBHome = path.join(scratch, 'host-b', 'home'); -const processHome = path.join(scratch, 'process-home'); -for (const dir of [hostAPathDir, path.join(hostBHome, 'vega', 'bin'), processHome]) { - mkdirSync(dir, { recursive: true }); -} -for (const file of [path.join(hostAPathDir, 'vega'), path.join(hostBHome, 'vega', 'bin', 'vega')]) { - writeFileSync(file, '#!/bin/sh\nexit 0\n'); - chmodSync(file, 0o755); -} - -const originalEnv = { ...process.env }; -// The bound test command host — and with it the process environment — names a third location -// where no vega exists, so an answer read from the process instead of the per-call host is -// wrong here. -process.env['PATH'] = path.join(scratch, 'process-bin'); -process.env['HOME'] = processHome; - -const hostA: HostEnvironment = { - env: { PATH: hostAPathDir, HOME: processHome }, - cwd: scratch, -}; -const hostB: HostEnvironment = { - env: { PATH: path.join(scratch, 'empty-bin'), HOME: hostBHome }, - cwd: scratch, -}; - -afterAll(() => { - rmSync(scratch, { recursive: true, force: true }); - for (const key of Object.keys(process.env)) { - if (!(key in originalEnv)) delete process.env[key]; - } - Object.assign(process.env, originalEnv); -}); - -beforeEach(() => { - mockRunCmd.mockReset(); - mockWhichCmd.mockReset(); - mockWhichCmd.mockImplementation(async (cmd: string, env: NodeJS.ProcessEnv) => - Boolean(cmd === 'vega' && env?.PATH?.includes(hostAPathDir)), - ); - mockRunCmd.mockResolvedValue({ exitCode: 0, stdout: '', stderr: '' }); -}); - -function createPluginHost(): PlatformHost { +/** One command the plugin asked the host to run. */ +type HostCommand = Readonly<{ + executable: string; + args: readonly string[]; +}>; + +/** + * The host the composition hands the plugin: one captured environment, no device authority. The PATH + * lookup is the host's own reading of the environment it was given, so a plugin that searched the + * process environment instead of this host gets a different answer here. + */ +function createPluginHost( + input: Readonly<{ + env?: PlatformHost['env']; + onPath?: readonly string[]; + commands?: HostCommand[]; + }> = {}, +): PlatformHost { + const onPath = new Set(input.onPath ?? ['vega']); return { - env: process.env, - cwd: scratch, - stateDir: path.join(scratch, 'state'), - runCommand: runCmd, + env: input.env ?? {}, + cwd: '/host-cwd', + stateDir: '/host-state', + runCommand: async (executable, args) => { + input.commands?.push({ executable, args }); + return { stdout: '', stderr: '', exitCode: 0 }; + }, + // The real host probe: a test that names a home proves the plugin resolves the CLI from a file + // on disk, not from a verdict this fixture hands it. isFileExecutable: isExecutablePath, + isExecutableOnPath: async (executable) => onPath.has(executable), + listHostProcesses: async () => [], emitDiagnostic, withDiagnosticTimer, }; } -/** `setup` answers the platform family's registration; the cast names what the host stores. */ -function setupVegaPlatform(): VegaPlatformRegistration { - return vegaPlatformPlugin().contributes[0].setup(createPluginHost()) as VegaPlatformRegistration; -} - -function runExecutables(): string[] { - return mockRunCmd.mock.calls.map(([executable]) => executable); +function setupVegaPlatform(host?: PlatformHost): VegaPlatformRegistration { + return vegaPlatformPlugin().contributes[0].setup( + host ?? createPluginHost(), + ) as VegaPlatformRegistration; } -function withProcessCommandHost(run: () => Promise): Promise { - // The process command host names a third location; the per-call hosts below must win (#3794). - return withCommandHost( - { host: { env: process.env, cwd: process.cwd() }, requestEnv: undefined }, - run, - ); -} +const scope = { + signal: new AbortController().signal, + diagnostics: { emit: () => undefined }, + progress: { report: () => undefined }, +}; test('the Vega package contributes the Vega platform family', () => { const plugin = vegaPlatformPlugin(); @@ -130,16 +88,38 @@ test('setup registers the Vega modules, request scoping and operations', () => { assert.equal(typeof registration.operations.toolchainCheck, 'function'); }); -test('setup creates the Vega interactor lazily', async () => { +test('the Vega inventory loads with no host from the core', async () => { + // The family owns its host: discovery runs over the setup host, so the core hands the inventory + // module nothing. A signature that still demanded a core host would fail here. const registration = setupVegaPlatform(); + const source = await registration.inventoryModule.loadInventory(); + assert.equal(typeof source.discover, 'function'); +}); + +test('setup runs discovery on the host it was set up with, not on the process environment', async () => { + // The plugin never reads `process.env`: the CLI's default install reaches discovery through the + // setup host only. The process home has no `vega/bin/vega`, so an implementation that read it + // instead of the host reports the CLI missing on any machine. + const home = createVegaHostHome(); + const install = createVegaDefaultInstall(home); + const commands: HostCommand[] = []; + const registration = setupVegaPlatform( + createPluginHost({ env: { HOME: home, PATH: '/bin' }, onPath: [], commands }), + ); + + const source = await registration.inventoryModule.loadInventory(); + await source.discover({}, scope); + + assert.equal(commands[0]?.executable, install); + assert.deepEqual(commands[0]?.args, ['device', 'list']); +}); +test('setup creates the Vega interactor lazily', async () => { + const registration = setupVegaPlatform(); const interactor = await registration.createInteractor( VEGA_VVD, {}, - { - env: process.env, - cwd: process.cwd(), - }, + { env: {}, cwd: '/host-cwd' }, ); assert.equal(typeof interactor.tvRemote, 'function'); @@ -147,20 +127,30 @@ test('setup creates the Vega interactor lazily', async () => { assert.equal(typeof interactor.home, 'function'); }); -test('setup binds each caller host into the interactor it returns', async () => { - // Removing the host-binding wrap in the contribution's createInteractor makes both calls fall - // through to the unbound scope default and refuse with `vega-adapter-host-unbound` (#3794). - await withProcessCommandHost(async () => { - const registration = setupVegaPlatform(); - - const interactorA = await registration.createInteractor(VEGA_VVD, {}, hostA); - const interactorB = await registration.createInteractor(VEGA_VVD, {}, hostB); - - await interactorA.back(); - assert.deepEqual(runExecutables(), ['vega']); - - mockRunCmd.mockClear(); - await interactorB.back(); - assert.deepEqual(runExecutables(), [path.join(hostBHome, 'vega', 'bin', 'vega')]); - }); +test('setup binds its own host into every interactor it returns', async () => { + // Two setups, two hosts: one carries the CLI on its host PATH, the other only under its host home. + // Each interactor must spawn the CLI its own setup host resolved, so a second runtime never runs + // the first runtime's binary (#3794). + const home = createVegaHostHome(); + const install = createVegaDefaultInstall(home); + const pathCommands: HostCommand[] = []; + const homeCommands: HostCommand[] = []; + const pathInteractor = await setupVegaPlatform( + createPluginHost({ env: { PATH: '/bin' }, onPath: ['vega'], commands: pathCommands }), + ).createInteractor(VEGA_VVD, {}, { env: {}, cwd: '/host-cwd' }); + const homeInteractor = await setupVegaPlatform( + createPluginHost({ env: { HOME: home, PATH: '/bin' }, onPath: [], commands: homeCommands }), + ).createInteractor(VEGA_VVD, {}, { env: {}, cwd: '/host-cwd' }); + + await pathInteractor.back(); + await homeInteractor.back(); + + assert.deepEqual( + pathCommands.map(({ executable }) => executable), + ['vega'], + ); + assert.deepEqual( + homeCommands.map(({ executable }) => executable), + [install], + ); }); diff --git a/packages/platform-vega/src/index.ts b/packages/platform-vega/src/index.ts index 50d5118831..f5436b9a7c 100644 --- a/packages/platform-vega/src/index.ts +++ b/packages/platform-vega/src/index.ts @@ -1,32 +1,34 @@ -import type { PlatformContribution, PlatformSetup } from 'agent-device/plugins'; +import type { PlatformContribution, PlatformHost } from 'agent-device/plugins'; +import type { VegaToolbox } from './toolbox.ts'; import type { InventoryPlatformModule, PlatformModuleMetadata, } from '@agent-device/contracts/platform-module'; import type { PlatformRuntimeModule } from '@agent-device/contracts/platform-runtime-operations'; -import type { Interactor, RunnerContext } from '@agent-device/contracts/interactor-types'; -import type { DeviceInfo } from '@agent-device/kernel/device'; -import type { HostEnvironment } from '@agent-device/kernel/source-value'; +import type { VegaPlatformRegistration } from '@agent-device/contracts/platform-plugin'; const metadata = Object.freeze({ family: 'vega', } satisfies PlatformModuleMetadata); -const runtimeModule = Object.freeze({ - ...metadata, - loadRuntime: async (host) => { - const { createVegaPlatformRuntime } = await import('./runtime.ts'); - return createVegaPlatformRuntime(host); - }, -} satisfies PlatformRuntimeModule); +/** + * The toolbox module, resolved exactly once per process. The façade must stay metadata-eager + * (ADR-0019), so the module that binds a host's command port enters with the first operation that + * needs it rather than above it. Only the module is memoized: each `setup` call binds its own host. + */ +let toolboxModule: Promise | undefined; -const inventoryModule: InventoryPlatformModule<'vega'> = Object.freeze({ - ...metadata, - loadInventory: async (host) => { - const { createVegaInventory } = await import('./inventory.ts'); - return createVegaInventory(host); - }, -}); +/** + * A bound toolbox, made on first use and then reused: a `setup` that never runs a command imports + * and builds nothing, and the operations of one setup share the one toolbox it binds its host to. + */ +function vegaToolbox(host: PlatformHost) { + let toolbox: Promise | undefined; + return async () => + (toolbox ??= (toolboxModule ??= import('./toolbox.ts')).then(({ createVegaToolbox }) => + createVegaToolbox(host), + )); +} function vegaPlatformPlugin() { return { @@ -35,37 +37,50 @@ function vegaPlatformPlugin() { { kind: 'platform', family: 'vega', - setup(host): PlatformSetup<'vega'> { + // Importing this package evaluates nothing but itself, and the host is bound to a toolbox + // only when an operation first needs one. Every operation below asks the same lazy + // resolution, so one setup builds exactly one toolbox for the whole family. + setup(host: PlatformHost): VegaPlatformRegistration { + const toolbox = vegaToolbox(host); + const inventoryModule: InventoryPlatformModule<'vega'> = Object.freeze({ + ...metadata, + // The family's inventory asks the core for no host: the CLI it resolves comes from the + // host `setup` received, so the plugin neither searches `PATH` nor reads the process home + // by itself (ADR 0019). + loadInventory: async () => { + const [{ createVegaInventory }, { commands }] = await Promise.all([ + import('./inventory.ts'), + toolbox(), + ]); + return createVegaInventory(commands); + }, + }); + const runtimeModule = Object.freeze({ + ...metadata, + loadRuntime: async (host) => { + const { createVegaPlatformRuntime } = await import('./runtime.ts'); + return createVegaPlatformRuntime(host); + }, + } satisfies PlatformRuntimeModule & { readonly family: 'vega' }); return { family: 'vega', inventoryModule, runtimeModule, - createInteractor: async ( - device: DeviceInfo, - runnerContext: RunnerContext, - host: HostEnvironment, - ): Promise => { - const [{ createVegaInteractor }, toolProvider] = await Promise.all([ + createInteractor: async (device, runnerContext) => { + const [{ createVegaInteractor }, { commands }, toolProvider] = await Promise.all([ import('./interactor.ts'), + toolbox(), import('./tool-provider.ts'), ]); - // The interactor binds the CLI adapter to the composing runtime's host: executable - // resolution reads that host's PATH and HOME and memoizes on this instance (#3794). A + const { withMethodScope } = await import('@agent-device/kernel/scoped-provider'); + // The interactor binds the CLI provider to the host this plugin was set up with. A // request-scoped provider still wins: this one enters only when the request scopes none. - // The entry stays eager-free, so the scope helper arrives with its module, not above it. - const { - createLocalVegaCliAdapter, - createLocalVegaToolProvider, - hasScopedVegaToolProvider, - withVegaToolProvider, - } = toolProvider; - const provider = createLocalVegaToolProvider(createLocalVegaCliAdapter(host)); + const provider = toolProvider.createVegaToolProvider(commands); const interactor = createVegaInteractor(device, runnerContext); - const { withMethodScope } = await import('@agent-device/kernel/scoped-provider'); return withMethodScope(interactor, async (task) => - hasScopedVegaToolProvider() + toolProvider.hasScopedVegaToolProvider() ? await task() - : await withVegaToolProvider(provider, task), + : await toolProvider.withVegaToolProvider(provider, task), ); }, withRequestProvider: async (provider, task) => { @@ -74,15 +89,21 @@ function vegaPlatformPlugin() { }, operations: { toolchainCheck: async (context) => { - const { vegaToolchainCheck } = await import('./doctor.ts'); - return await vegaToolchainCheck(context, host); + const [{ vegaToolchainCheck }, { commands }] = await Promise.all([ + import('./doctor.ts'), + toolbox(), + ]); + return await vegaToolchainCheck(context, commands); }, }, }; }, }, ], - } satisfies { apiVersion: 3; contributes: [Extract] }; + } satisfies { + apiVersion: 3; + contributes: [Extract]; + }; } export { vegaPlatformPlugin as default }; diff --git a/packages/platform-vega/src/input-actions.ts b/packages/platform-vega/src/input-actions.ts index dcae051927..517f545fa7 100644 --- a/packages/platform-vega/src/input-actions.ts +++ b/packages/platform-vega/src/input-actions.ts @@ -1,6 +1,6 @@ import { type TvRemoteButton, toVegaTvRemoteKey } from '@agent-device/contracts/tv-remote'; import type { DeviceInfo } from '@agent-device/kernel/device'; -import { requireExecSuccess } from '@agent-device/host-kit/command'; +import { requireCommandSuccess } from '@agent-device/kernel/errors'; import { resolveVegaToolProvider } from './tool-provider.ts'; const VEGA_INPUT_TRANSPORT_OVERHEAD_MS = 10_000; @@ -11,7 +11,7 @@ export async function pressVegaTvRemote( durationMs?: number, ): Promise { const key = toVegaTvRemoteKey(button); - requireExecSuccess( + requireCommandSuccess( await resolveVegaToolProvider().pressRemote(device.id, key, durationMs, { allowFailure: true, timeoutMs: VEGA_INPUT_TRANSPORT_OVERHEAD_MS + (durationMs ?? 0), diff --git a/packages/platform-vega/src/inventory.test.ts b/packages/platform-vega/src/inventory.test.ts index db77a1e997..1e32e1431c 100644 --- a/packages/platform-vega/src/inventory.test.ts +++ b/packages/platform-vega/src/inventory.test.ts @@ -1,10 +1,8 @@ import assert from 'node:assert/strict'; import { test } from 'vitest'; import { AppError } from '@agent-device/kernel/errors'; -import type { - DeviceInventoryHostFor, - PlatformRequestScope, -} from '@agent-device/contracts/platform-runtime-host'; +import type { PlatformRequestScope } from '@agent-device/contracts/platform-runtime-host'; +import { createVegaHostStub } from './command-host.fixtures.ts'; import { createVegaInventory } from './inventory.ts'; const scope: PlatformRequestScope = { @@ -13,20 +11,19 @@ const scope: PlatformRequestScope = { progress: { report: () => undefined }, }; -test('Vega inventory resolves the default CLI lazily and accepts only its virtual device', async () => { - const host = createHost({ - which: async () => undefined, - isExecutable: async (path) => path === '/Users/test/vega/bin/vega', - run: async (request) => { - assert.equal(request.executable, '/Users/test/vega/bin/vega'); - assert.deepEqual(request.args, ['device', 'list']); - assert.equal(request.timeoutMs, 10_000); - return result('physical : tv\nVirtualDevice : tv - aarch64 - VegaOS\n'); - }, +test('Vega inventory resolves the CLI through its host and accepts only its virtual device', async () => { + const stub = createVegaHostStub({ + env: { PATH: '/usr/bin', HOME: '/host-home' }, + onPath: [], + executableFiles: ['/host-home/vega/bin/vega'], }); + stub.answer({ stdout: 'physical : tv\nVirtualDevice : tv - aarch64 - VegaOS\n' }); - const devices = await createVegaInventory(host).discover({}, scope); + const devices = await createVegaInventory(stub.toolbox.commands).discover({}, scope); + assert.deepEqual(stub.commands[0]?.executable, '/host-home/vega/bin/vega'); + assert.deepEqual(stub.commands[0]?.args, ['device', 'list']); + assert.equal(stub.commands[0]?.timeoutMs, 10_000); // Spelled out rather than compared against `parseVegaDeviceList(...)`: using the parser as the // expected value lets both sides move together, which is exactly how a dropped `physical` row or // a wrong `kind`/`booted` mapping would stay invisible. @@ -42,31 +39,45 @@ test('Vega inventory resolves the default CLI lazily and accepts only its virtua ]); }); +test('Vega inventory prefers the CLI the host PATH resolves', async () => { + const stub = createVegaHostStub({ + onPath: ['vega'], + stdout: 'VirtualDevice : tv - aarch64 - VegaOS\n', + }); + + await createVegaInventory(stub.toolbox.commands).discover({}, scope); + + assert.equal(stub.commands[0]?.executable, 'vega'); +}); + +test('Vega inventory reports a missing CLI before it spawns anything', async () => { + const stub = createVegaHostStub({ onPath: [], executableFiles: [] }); + + await assert.rejects( + createVegaInventory(stub.toolbox.commands).discover({}, scope), + (error: unknown) => error instanceof AppError && error.code === 'TOOL_MISSING', + ); + assert.deepEqual(stub.commands, []); +}); + test('Vega inventory fails closed when only an unsupported physical target is present', async () => { - const host = createHost({ run: async () => result('physical : tv\n') }); + const stub = createVegaHostStub({ stdout: 'physical : tv\n' }); await assert.rejects( - createVegaInventory(host).discover({}, scope), + createVegaInventory(stub.toolbox.commands).discover({}, scope), (error: unknown) => error instanceof AppError && error.code === 'DEVICE_NOT_FOUND', ); }); -function createHost(options: { - which?: DeviceInventoryHostFor<'vega'>['commands']['which']; - isExecutable?: DeviceInventoryHostFor<'vega'>['files']['isExecutable']; - run: DeviceInventoryHostFor<'vega'>['commands']['run']; -}): DeviceInventoryHostFor<'vega'> { - return { - commands: { which: options.which ?? (async () => 'vega'), run: options.run }, - files: { - isExecutable: options.isExecutable ?? (async () => false), - createTemporaryTextFile: async () => { - throw new Error('unused'); - }, - }, - homeDirectory: '/Users/test', - }; -} - -function result(stdout: string, stderr = '', exitCode = 0) { - return { stdout, stderr, exitCode }; -} +test('Vega inventory reports a failing CLI as a command failure carrying its stderr', async () => { + const stub = createVegaHostStub({ + respond: () => ({ exitCode: 3, stderr: 'daemon unreachable' }), + }); + await assert.rejects( + createVegaInventory(stub.toolbox.commands).discover({}, scope), + (error: unknown) => + error instanceof AppError && + error.code === 'COMMAND_FAILED' && + error.details?.processExitError === true && + error.details?.stderr === 'daemon unreachable', + ); +}); diff --git a/packages/platform-vega/src/inventory.ts b/packages/platform-vega/src/inventory.ts index 0f5e367042..48a2fcad5d 100644 --- a/packages/platform-vega/src/inventory.ts +++ b/packages/platform-vega/src/inventory.ts @@ -1,20 +1,20 @@ import type { DeviceInfo } from '@agent-device/kernel/device'; -import { requireExecSuccess } from '@agent-device/host-kit/command'; -import { AppError } from '@agent-device/kernel/errors'; -import { resolveVegaExecutable } from './vega-executable.ts'; -import type { - DeviceInventoryHostFor, - HostCommandResult, - PlatformRequestScope, -} from '@agent-device/contracts/platform-runtime-host'; +import { AppError, requireCommandSuccess } from '@agent-device/kernel/errors'; +import type { VegaCommandRunner } from './command-host.ts'; +import type { PlatformRequestScope } from '@agent-device/contracts/platform-runtime-host'; import type { DeviceInventorySource } from '@agent-device/contracts/platform-module'; const DISCOVERY_TIMEOUT_MS = 10_000; const VVD_SERIAL = 'VirtualDevice'; -export function createVegaInventory(host: DeviceInventoryHostFor<'vega'>): DeviceInventorySource { +/** + * Vega's inventory, answering from the plugin's own command route. The family asks the core for no + * host: the CLI it resolves comes from the `PlatformHost` its `setup` received (#4862), so discovery + * and every later command of a request agree on one executable and one environment. + */ +export function createVegaInventory(commands: VegaCommandRunner): DeviceInventorySource { return { - discover: async (_request, scope) => await discoverVegaDevices(host, scope), + discover: async (_request, scope) => await discoverVegaDevices(commands, scope), }; } @@ -33,25 +33,21 @@ function parseVegaDeviceList(rawOutput: string): DeviceInfo[] { } async function discoverVegaDevices( - host: DeviceInventoryHostFor<'vega'>, + commands: VegaCommandRunner, scope: PlatformRequestScope, ): Promise { - const executable = await resolveVegaExecutableForInventory(host); + const executable = await commands.resolveExecutable(); if (!executable) { throw new AppError('TOOL_MISSING', 'Vega CLI not found in PATH', { hint: 'Install Vega Developer Tools, source ~/vega/env, and retry devices.', }); } - const result = await host.commands.run( - { - executable, - args: ['device', 'list'], - allowFailure: true, - timeoutMs: DISCOVERY_TIMEOUT_MS, - }, - scope.signal, - ); - assertCommandSuccess(result); + const result = await commands.run(['device', 'list'], { + allowFailure: true, + timeoutMs: DISCOVERY_TIMEOUT_MS, + signal: scope.signal, + }); + requireCommandSuccess(result, 'Failed to list Vega devices'); const devices = parseVegaDeviceList(result.stdout); const listedSerials = parseListedVegaSerials(result.stdout); if (devices.length === 0 && listedSerials.length > 0) { @@ -67,22 +63,6 @@ async function discoverVegaDevices( return devices; } -async function resolveVegaExecutableForInventory( - host: DeviceInventoryHostFor<'vega'>, -): Promise { - // The one Vega lookup shared with the CLI adapter and doctor: PATH, then the runtime host's - // home default install (#3794). - return await resolveVegaExecutable({ - which: (executable) => host.commands.which(executable), - isExecutableFile: (candidate) => host.files.isExecutable(candidate), - homeDirectory: host.homeDirectory, - }); -} - -function assertCommandSuccess(result: HostCommandResult): void { - requireExecSuccess(result, 'Failed to list Vega devices'); -} - function isVegaVirtualDevice(serial: string): boolean { return serial.toLowerCase() === VVD_SERIAL.toLowerCase(); } diff --git a/packages/platform-vega/src/tool-provider.ts b/packages/platform-vega/src/tool-provider.ts index 0c288ccaf8..6255e7b085 100644 --- a/packages/platform-vega/src/tool-provider.ts +++ b/packages/platform-vega/src/tool-provider.ts @@ -1,74 +1,24 @@ import type { VegaToolProvider } from '@agent-device/contracts/vega-tool-provider'; import { AppError } from '@agent-device/kernel/errors'; -import { runCmd, type ExecOptions, type ExecResult } from '@agent-device/host-kit/command'; -import type { HostEnvironment } from '@agent-device/kernel/source-value'; import { createScopedProvider } from '@agent-device/kernel/scoped-provider'; -import { createVegaExecutableHostFromEnv, resolveVegaExecutable } from './vega-executable.ts'; +import type { VegaCommandOptions, VegaCommandRunner } from './command-host.ts'; -export type VegaCliAdapter = { - run(args: string[], options?: ExecOptions): Promise; - isAvailable(): Promise; -}; - -/** - * Builds the local CLI adapter for one host. It resolves the vega executable through the one - * resolver (#3794), deriving PATH and home from that host's environment, and memoizes the answer - * on this adapter instance, so a second runtime with a different host never runs the first - * runtime's binary. A refusal is not memoized; only a found executable is, so a later install - * still resolves. - */ -export function createLocalVegaCliAdapter(host: HostEnvironment): VegaCliAdapter { - const executableHost = createVegaExecutableHostFromEnv(host.env); - let resolvedExecutable: string | undefined; - const resolveCliExecutable = async (): Promise => { - if (resolvedExecutable) return resolvedExecutable; - resolvedExecutable = await resolveVegaExecutable(executableHost); - return resolvedExecutable; - }; - return { - run: async (args, options) => - await runCmd((await resolveCliExecutable()) ?? 'vega', args, options), - isAvailable: async () => Boolean(await resolveCliExecutable()), - }; -} - -/** - * The scope default for callers that name no host. Every composed route (the plugin interactor - * wrapper, doctor's host-bound adapter) enters its own host-bound provider before a command - * runs, so reaching this default means the caller forgot to bind one — refuse instead of reading - * an ambient environment (#3794). - */ -function unboundVegaCliAdapter(): VegaCliAdapter { - const refuse = async (): Promise => { - throw new AppError('COMMAND_FAILED', 'The Vega CLI adapter is not bound to a host.', { - reason: 'vega-adapter-host-unbound', - }); - }; - return { run: refuse, isAvailable: refuse }; -} - -const localVegaToolProvider = createLocalVegaToolProvider(unboundVegaCliAdapter()); -const vegaToolProviderScope = createScopedProvider(localVegaToolProvider); - -export function createLocalVegaToolProvider(adapter: VegaCliAdapter): VegaToolProvider { +/** Every Vega CLI call one request makes, shaped the way the Vega family asks for it. */ +export function createVegaToolProvider(commands: VegaCommandRunner): VegaToolProvider { + const run = async (args: string[], options?: VegaCommandOptions) => + await commands.run(args, options); return { - isAvailable: async () => await adapter.isAvailable(), - version: async (options) => await adapter.run(['--version'], options), - listDevices: async (options) => await adapter.run(['device', 'list'], options), + isAvailable: async () => Boolean(await commands.resolveExecutable()), + version: async (options) => await run(['--version'], options), + listDevices: async (options) => await run(['device', 'list'], options), checkConnected: async (deviceId, options) => - await adapter.run(['device', 'is-connected', '--device', deviceId], options), + await run(['device', 'is-connected', '--device', deviceId], options), launchApp: async (deviceId, appName, options) => - await adapter.run( - ['device', 'launch-app', '--device', deviceId, '--appName', appName], - options, - ), + await run(['device', 'launch-app', '--device', deviceId, '--appName', appName], options), terminateApp: async (deviceId, appName, options) => - await adapter.run( - ['device', 'terminate-app', '--device', deviceId, '--appName', appName], - options, - ), + await run(['device', 'terminate-app', '--device', deviceId, '--appName', appName], options), pressRemote: async (deviceId, key, durationMs, options) => - await adapter.run( + await run( [ 'device', 'run-cmd', @@ -87,6 +37,31 @@ export function createLocalVegaToolProvider(adapter: VegaCliAdapter): VegaToolPr }; } +/** + * The scope default for callers that name no provider. Every composed route (the plugin interactor + * wrapper, doctor's toolbox-bound provider) enters its own provider before a command runs, so + * reaching this default means the caller forgot to bind one — refuse instead of spawning a CLI no + * host was asked about (#3794). + */ +function unboundVegaToolProvider(): VegaToolProvider { + const refuse = async (): Promise => { + throw new AppError('COMMAND_FAILED', 'The Vega CLI provider is not bound to a host.', { + reason: 'vega-adapter-host-unbound', + }); + }; + return { + isAvailable: refuse, + version: refuse, + listDevices: refuse, + checkConnected: refuse, + launchApp: refuse, + terminateApp: refuse, + pressRemote: refuse, + }; +} + +const vegaToolProviderScope = createScopedProvider(unboundVegaToolProvider()); + export function resolveVegaToolProvider(provider?: VegaToolProvider): VegaToolProvider { return vegaToolProviderScope.resolve(provider); } diff --git a/packages/platform-vega/src/toolbox.ts b/packages/platform-vega/src/toolbox.ts new file mode 100644 index 0000000000..7b499e7f92 --- /dev/null +++ b/packages/platform-vega/src/toolbox.ts @@ -0,0 +1,27 @@ +import type { PlatformHost } from 'agent-device/plugins'; +import { createVegaCommandRunner, type VegaCommandRunner } from './command-host.ts'; + +/** + * Everything the Vega family needs from the machine it runs on, built once from the `PlatformHost` + * the core hands `setup()`, and shared by inventory, the runtime, the interactor and doctor. + * + * It exists so the plugin never reaches for process globals of its own. The package is bundled with + * its own copy of the host kit, and the daemon's command scope never enters that copy, so a spawn + * made through it would run with the daemon's environment and outside the request's exec trace. + * Going through the host keeps CLI resolution, environment and diagnostics where the core put them. + */ +export type VegaToolbox = Readonly<{ + host: PlatformHost; + /** The Vega CLI route: one resolver over the host, one spawn per call. */ + commands: VegaCommandRunner; + /** Timings and traces for this family's operations, in the request's diagnostic store. */ + withDiagnosticTimer: PlatformHost['withDiagnosticTimer']; +}>; + +export function createVegaToolbox(host: PlatformHost): VegaToolbox { + return Object.freeze({ + host, + commands: createVegaCommandRunner(host), + withDiagnosticTimer: host.withDiagnosticTimer, + }); +} diff --git a/packages/platform-vega/src/vega-executable.ts b/packages/platform-vega/src/vega-executable.ts index 64cd9db278..969852ecc2 100644 --- a/packages/platform-vega/src/vega-executable.ts +++ b/packages/platform-vega/src/vega-executable.ts @@ -1,14 +1,10 @@ import path from 'node:path'; -import { isExecutablePath, whichCmd } from '@agent-device/host-kit/command'; -import { hostHomeDirectoryFromEnv } from '@agent-device/host-kit/host-file'; -import type { EnvMap } from '@agent-device/kernel/source-value'; /** - * The host ports one Vega executable lookup needs — the same three the device-inventory host - * exposes (`commands.which`, `files.isExecutable`, `homeDirectory`) — so inventory, doctor and - * the CLI adapter all resolve through one resolver over their runtime host (#3794). A host that - * names no home omits `homeDirectory`; then the default-install probe is skipped, never guessed - * from the process (#3753). + * The two ports one Vega executable lookup needs — the host `PATH`, and a host home to probe — so + * inventory, doctor and the CLI adapter all resolve through one resolver over the host they were + * bound to (#3794). A host that names no home omits `homeDirectory`; then the default-install probe + * is skipped, never guessed from the process (#3753). */ export type VegaExecutableHost = Readonly<{ which: (executable: string) => Promise; @@ -24,22 +20,11 @@ export function resolveVegaExecutable(host: VegaExecutableHost): Promise { if (await host.which('vega')) return 'vega'; if (host.homeDirectory === undefined) return undefined; - const defaultInstall = path.join(host.homeDirectory, 'vega', 'bin', 'vega'); + const defaultInstall = vegaDefaultInstallPath(host.homeDirectory); return (await host.isExecutableFile(defaultInstall)) ? defaultInstall : undefined; } -/** - * Derives the resolver's ports from a runtime host environment: PATH through the host env, the - * home through the host env's own HOME/USERPROFILE, never the process home. A host env that names - * no home yields no `homeDirectory`, and the resolver then skips the default-install probe. - * `createDeviceInventoryHost` derives its `homeDirectory` with the same helper, so the inventory - * route and this one agree. - */ -export function createVegaExecutableHostFromEnv(env: EnvMap): VegaExecutableHost { - return Object.freeze({ - which: async (executable: string) => - (await whichCmd(executable, env)) ? executable : undefined, - isExecutableFile: async (candidate: string) => await isExecutablePath(candidate), - homeDirectory: hostHomeDirectoryFromEnv(env), - }); +/** The default install the resolver probes, in the order the plugin's own guidance names it. */ +export function vegaDefaultInstallPath(homeDirectory: string): string { + return path.join(homeDirectory, 'vega', 'bin', 'vega'); } diff --git a/packages/platform-vega/test/package-smoke.mjs b/packages/platform-vega/test/package-smoke.mjs index 4594f05ca6..2e3cb27abf 100644 --- a/packages/platform-vega/test/package-smoke.mjs +++ b/packages/platform-vega/test/package-smoke.mjs @@ -7,8 +7,64 @@ import { test } from 'node:test'; const repo = path.resolve(import.meta.dirname, '../../..'); +/** + * A stand-in for the Vega SDK CLI, written into a directory that is on the host `PATH` the CLI and + * the daemon are launched with and nowhere else. It answers the calls this family asks a Vega + * Virtual Device, and appends every invocation to `logFile` so the test can prove which argv and + * which environment reached the tool. The log path is baked into the stub rather than passed by + * environment: the plugin spawns with the host environment it was set up with, so nothing this + * fixture needs travels through it. + */ +function vegaStubSource(logFile) { + return [ + '#!/usr/bin/env node', + "const fs = require('node:fs');", + 'const args = process.argv.slice(2);', + 'const joined = args.join(" ");', + 'fs.appendFileSync(' + + JSON.stringify(logFile) + + String.raw`, "ARGS: " + joined + "\nPATH: " + process.env.PATH + "\nHOME: " + process.env.HOME + "\n");`, + String.raw`const answer = (text) => process.stdout.write(text + "\n");`, + 'if (joined === "--version") answer("0.2.0");', + 'else if (joined.includes("device list")) answer("VirtualDevice : running");', + 'else if (joined.includes("is-connected")) answer("VirtualDevice is connected");', + 'else if (joined.includes("launch-app")) answer("Launched");', + 'else if (joined.includes("terminate-app")) answer("Terminated");', + 'else answer("ok");', + ].join('\n'); +} + +/** + * The exec records a `--debug` request wrote, from the request records the daemon keeps under its + * session dirs. Records are matched by the CLI command they belong to, so an empty answer means the + * request traced no spawn at all rather than that its file was not found. + */ +function execRecordsOf(storeRoot, command) { + const sessionsDir = path.join(storeRoot, 'sessions'); + if (!fs.existsSync(sessionsDir)) return []; + const requestFiles = fs + .readdirSync(sessionsDir) + .flatMap((session) => { + const requestsDir = path.join(sessionsDir, session, 'requests'); + return fs.existsSync(requestsDir) + ? fs.readdirSync(requestsDir).map((request) => path.join(requestsDir, request)) + : []; + }) + .filter((file) => file.endsWith('.ndjson')); + return requestFiles + .flatMap((file) => fs.readFileSync(file, 'utf8').split('\n')) + .filter((line) => line.includes('"phase":"exec_command"')) + .map((line) => JSON.parse(line)) + .filter((record) => record.command === command); +} + test('packed core discovers vega only after the managed platform is installed', () => { const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-vega-pack-')); + // The Vega CLI is a host tool the plugin reads through PATH and through the home's default + // install. A machine that has it installed would answer its own device list, so every CLI run + // names a host that carries neither: the installed plugin then always answers its toolchain + // report, on any machine. + const stubBin = path.join(scratch, 'stub-bin'); const env = { ...Object.fromEntries( Object.entries(process.env).filter(([name]) => !name.startsWith('AGENT_DEVICE_')), @@ -18,25 +74,21 @@ test('packed core discovers vega only after the managed platform is installed', AGENT_DEVICE_CLAIMS_DIR: path.join(scratch, 'claims'), AGENT_DEVICE_NO_UPDATE_NOTIFIER: '1', }; - // The Vega CLI is a host tool the plugin reads through PATH and through the home's default - // install. A machine that has it installed would answer its own device list, so every CLI run - // names a host that carries neither: the installed plugin then always answers its toolchain - // report, on any machine. const cliEnv = { ...env, PATH: [path.dirname(process.execPath), '/usr/bin', '/bin'].join(path.delimiter), HOME: scratch, }; - const exec = (command, args, cwd = scratch) => - execFileSync(command, args, { cwd, env, encoding: 'utf8', timeout: 120_000 }); + const exec = (command, args, cwd = scratch, environment = env) => + execFileSync(command, args, { cwd, env: environment, encoding: 'utf8', timeout: 120_000 }); const cli = (...args) => exec(process.execPath, ['node_modules/agent-device/bin/agent-device.mjs', ...args]); - const runCli = (expectedExit, ...args) => { + const runCliWith = (environment, expectedExit, ...args) => { const invoke = () => execFileSync( process.execPath, ['node_modules/agent-device/bin/agent-device.mjs', ...args, '--json'], - { cwd: scratch, env: cliEnv, encoding: 'utf8', timeout: 120_000 }, + { cwd: scratch, env: environment, encoding: 'utf8', timeout: 120_000 }, ); try { const reply = JSON.parse(invoke()); @@ -47,6 +99,19 @@ test('packed core discovers vega only after the managed platform is installed', throw error; } }; + const runCli = (expectedExit, ...args) => runCliWith(cliEnv, expectedExit, ...args); + // The daemon environment is captured when the CLI starts it, so the stub directory has to be on + // the PATH of the process that launches it. + const stubEnv = () => ({ ...cliEnv, PATH: [stubBin, cliEnv.PATH].join(path.delimiter) }); + // A `--debug` request writes its own exec records to the daemon log: the route proof below reads + // them back, which is what a spawn through the bundle's own host-kit copy cannot produce. + const debugCli = (...args) => + execFileSync( + process.execPath, + ['node_modules/agent-device/bin/agent-device.mjs', ...args, '--json', '--debug'], + { cwd: scratch, env: stubEnv(), encoding: 'utf8', timeout: 120_000 }, + ); + const storeRoot = env.AGENT_DEVICE_STATE_DIR; try { const [packed] = JSON.parse( exec('npm', ['pack', '--ignore-scripts', '--json', '--pack-destination', scratch], repo), @@ -80,6 +145,114 @@ test('packed core discovers vega only after the managed platform is installed', assert.equal(installed.error.code, 'TOOL_MISSING'); const plugins = runCli(0, 'daemon', 'status').data.plugins; assert.ok(plugins.some((plugin) => plugin.platform === 'vega' && plugin.state === 'active')); + + // Now the same store with the Vega CLI present on the host `PATH`: the packed plugin must run a + // whole interaction on calls it resolved and spawned through the host it was set up with. A + // bundle that spawned through its own copy of the host kit would answer these replies too — and + // leave the request's log without one exec record, which is what the trace check below refuses. + fs.mkdirSync(stubBin, { recursive: true }); + const vegaCalls = path.join(scratch, 'vega-calls.log'); + const stub = path.join(stubBin, process.platform === 'win32' ? 'vega.cmd' : 'vega'); + fs.writeFileSync(stub, vegaStubSource(vegaCalls), 'utf8'); + fs.chmodSync(stub, 0o755); + // The running daemon was launched without the stub directory, so the CLI that starts its daemon + // must carry it, and the stub has to be off the plain host PATH before this point. + assert.ok( + !(cliEnv.PATH ?? '') + .split(path.delimiter) + .filter(Boolean) + .some((dir) => fs.existsSync(path.join(dir, 'vega'))), + 'the fixture Vega CLI must not be reachable before the scenario adds it', + ); + runCli(0, 'daemon', 'stop'); + const found = runCliWith(stubEnv(), 0, 'devices', '--platform', 'vega'); + assert.deepEqual( + found.data.devices.map(({ id, platform }) => ({ id, platform })), + [{ id: 'VirtualDevice', platform: 'vega' }], + ); + debugCli('open', 'com.example.app.main', '--platform', 'vega', '--target', 'tv'); + debugCli( + 'tv-remote', + 'press', + 'down', + '--platform', + 'vega', + '--target', + 'tv', + '--duration-ms', + '120', + ); + debugCli('close', 'com.example.app.main', '--platform', 'vega'); + + const recorded = fs.readFileSync(vegaCalls, 'utf8').split('\n').filter(Boolean); + const invoked = recorded.filter((line) => line.startsWith('ARGS: ')); + const homes = recorded.filter((line) => line.startsWith('HOME: ')); + assert.equal(homes.length, invoked.length, 'each recorded call names the home it ran with'); + assert.ok( + invoked.some((line) => line === 'ARGS: device list'), + `discovery never asked the CLI for devices: ${invoked.join(' | ')}`, + ); + assert.ok( + invoked.some((line) => + /^ARGS: device launch-app --device VirtualDevice --appName com\.example\.app\.main$/.test( + line, + ), + ), + `open never launched an app through the CLI: ${invoked.join(' | ')}`, + ); + assert.ok( + invoked.some( + (line) => + line === + 'ARGS: device run-cmd --device VirtualDevice --command inputd-cli button_press KEY_DOWN --holdDuration 120', + ), + `the remote press never reached the CLI: ${invoked.join(' | ')}`, + ); + assert.ok( + invoked.some((line) => + /^ARGS: device terminate-app --device VirtualDevice --appName /.test(line), + ), + `close never terminated the app: ${invoked.join(' | ')}`, + ); + // Each spawn got the host home the plugin was set up with, not the daemon user's home. + assert.ok( + homes.every((line) => line === `HOME: ${scratch}`), + `the CLI ran with homes the plugin did not build: ${homes.join(' | ')}`, + ); + + // The route proof: every CLI call of a `--debug` request is recorded in that request's exec + // trace. Spawned through the bundle's own host-kit copy instead, the trace is empty — the calls + // would be unattributable to the request that asked for them. + // Each call names itself by its timeout: discovery asks 10s, an app command 30s, and the remote + // press above 10s plus its hold duration. Discovery runs on the core's own route on any build, + // so a bare "the request traced a `vega` spawn" would pass while the interactor's own call went + // untraced; naming the timeout is what pins the call the plugin itself made. + for (const [command, timeoutMs, expected] of [ + ['open', 30_000, 'device launch-app'], + ['tv-remote', 10_120, 'button_press'], + ['close', 30_000, 'device terminate-app'], + ]) { + const records = execRecordsOf(storeRoot, command); + const spawns = records.filter( + (record) => record.data?.event === 'spawn' && record.data.timeoutMs === timeoutMs, + ); + const exits = records.filter( + (record) => record.data?.event === 'exit' && record.data.timeoutMs === timeoutMs, + ); + assert.equal( + spawns.length, + 1, + `the ${command} request traced ${spawns.length} '${expected}' spawns out of ${records.length} exec records`, + ); + assert.equal( + exits.length, + 1, + `the ${command} request never saw its '${expected}' call exit: ${JSON.stringify(exits)}`, + ); + assert.equal(spawns[0].data.command, 'vega'); + assert.equal(exits[0].data.execId, spawns[0].data.execId); + assert.equal(exits[0].data.exitCode, 0); + } } finally { try { if (fs.existsSync(path.join(scratch, 'node_modules/agent-device'))) diff --git a/packages/platform-web/src/__tests__/agent-browser-provider-boundary-faults.test.ts b/packages/platform-web/src/__tests__/agent-browser-provider-boundary-faults.test.ts index ee5722f8b7..ae746bf9e2 100644 --- a/packages/platform-web/src/__tests__/agent-browser-provider-boundary-faults.test.ts +++ b/packages/platform-web/src/__tests__/agent-browser-provider-boundary-faults.test.ts @@ -6,6 +6,7 @@ import { AppError } from '@agent-device/kernel/errors'; import { createFailNthCommandExecutor, mkdtempForTestSync } from './test-utils.ts'; import { withCommandExecutorOverride } from '@agent-device/host-kit/command'; import { createAgentBrowserWebProvider } from '../agent-browser-provider.ts'; +import { createWebHostStub } from '../toolbox.fixtures.ts'; bindTestCommandHost(); @@ -26,7 +27,7 @@ for (const [commandClass, runOperation] of Object.entries(COMMAND_CLASS_OPERATIO try { installFakeManagedAgentBrowser(stateDir); const provider = createAgentBrowserWebProvider({ - host: { env: process.env, cwd: process.cwd() }, + toolbox: createWebHostStub({ stateDir }).toolbox, stateDir, session: 'boundary', }); diff --git a/packages/platform-web/src/__tests__/agent-browser-provider-dispatch-disclosure.test.ts b/packages/platform-web/src/__tests__/agent-browser-provider-dispatch-disclosure.test.ts index 3e660d0e58..b9324759e4 100644 --- a/packages/platform-web/src/__tests__/agent-browser-provider-dispatch-disclosure.test.ts +++ b/packages/platform-web/src/__tests__/agent-browser-provider-dispatch-disclosure.test.ts @@ -21,6 +21,7 @@ import { } from './test-utils.ts'; import { createAgentBrowserWebProvider } from '../agent-browser-provider.ts'; import type { WebProvider } from '@agent-device/contracts/web-provider'; +import { createWebHostStub } from '../toolbox.fixtures.ts'; bindTestCommandHost(); @@ -153,7 +154,7 @@ async function scrollRefusedOnThirdStep(): Promise { /** The managed backend is not installed, so the CLI is never spawned. */ async function openWithMissingBackend(): Promise { const provider = createAgentBrowserWebProvider({ - host: { env: process.env, cwd: process.cwd() }, + toolbox: createWebHostStub().toolbox, stateDir: mkdtempForTestSync('agent-device-web-disclosure-missing-'), }); await provider.open('https://example.test'); diff --git a/packages/platform-web/src/__tests__/agent-browser-provider-fleet-record.test.ts b/packages/platform-web/src/__tests__/agent-browser-provider-fleet-record.test.ts index e1be6476d0..41d3671451 100644 --- a/packages/platform-web/src/__tests__/agent-browser-provider-fleet-record.test.ts +++ b/packages/platform-web/src/__tests__/agent-browser-provider-fleet-record.test.ts @@ -9,6 +9,7 @@ import { type CommandExecutorOverride, } from '@agent-device/host-kit/command'; import { createAgentBrowserWebProvider } from '../agent-browser-provider.ts'; +import { createWebHostStub } from '../toolbox.fixtures.ts'; import { agentBrowserJsonResult, managedAgentBrowserCliArgs, @@ -54,7 +55,7 @@ function createTwoSessionDaemon() { let published = ['session-a']; const providerOf = (session: string) => createAgentBrowserWebProvider({ - host: { env: process.env, cwd: process.cwd() }, + toolbox: createWebHostStub({ stateDir, ownedProcessRecords: store }).toolbox, session, stateDir, openWebSessionNames: () => published, diff --git a/packages/platform-web/src/__tests__/agent-browser-provider-record-retention.test.ts b/packages/platform-web/src/__tests__/agent-browser-provider-record-retention.test.ts index 589b213184..df0922129b 100644 --- a/packages/platform-web/src/__tests__/agent-browser-provider-record-retention.test.ts +++ b/packages/platform-web/src/__tests__/agent-browser-provider-record-retention.test.ts @@ -21,6 +21,7 @@ import { MANAGED_WEB_BROWSER_PROCESS_PURPOSE } from '../agent-browser-process-re import { createAgentBrowserWebProvider } from '../agent-browser-provider.ts'; import type { WebProvider } from '@agent-device/contracts/web-provider'; import { agentBrowserJsonResult, mkdtempForTestSync } from './test-utils.ts'; +import { createWebHostStub } from '../toolbox.fixtures.ts'; bindTestCommandHost(); @@ -147,7 +148,7 @@ async function withFleetRecordStore( store.replace({ kind: 'daemon' }, [seed]); await runScenario({ provider: createAgentBrowserWebProvider({ - host: { env: process.env, cwd: process.cwd() }, + toolbox: createWebHostStub({ stateDir, ownedProcessRecords: store }).toolbox, session: 'web-session', stateDir, openWebSessionNames: () => ['web-session'], diff --git a/packages/platform-web/src/__tests__/doctor.test.ts b/packages/platform-web/src/__tests__/doctor.test.ts index dc6c98acd8..8b3c199b97 100644 --- a/packages/platform-web/src/__tests__/doctor.test.ts +++ b/packages/platform-web/src/__tests__/doctor.test.ts @@ -4,6 +4,7 @@ import fs from 'node:fs'; import { beforeEach, test, vi } from 'vitest'; import type { AgentBrowserProcessSummary } from '../agent-browser-lifecycle.ts'; import { mkdtempForTestSync } from './test-utils.ts'; +import { createWebHostStub } from '../toolbox.fixtures.ts'; vi.mock('../agent-browser-lifecycle.ts', async () => { const actual = await vi.importActual( @@ -43,10 +44,7 @@ test('web doctor lifecycle check reports live managed Chrome process count', asy ], } satisfies AgentBrowserProcessSummary); - const check = await webBrowserLifecycleCheck(stateDir, { - env: process.env, - cwd: process.cwd(), - }); + const check = await webBrowserLifecycleCheck(stateDir, createWebHostStub({ stateDir }).toolbox); assert.equal(check.id, 'web-agent-browser-processes'); assert.equal(check.status, 'info'); @@ -61,10 +59,7 @@ test('web doctor lifecycle check reports live managed Chrome process count', asy test('web doctor lifecycle check stays informational when managed backend is missing', async () => { const stateDir = mkdtempForTestSync('agent-device-web-doctor-missing-'); try { - const check = await webBrowserLifecycleCheck(stateDir, { - env: process.env, - cwd: process.cwd(), - }); + const check = await webBrowserLifecycleCheck(stateDir, createWebHostStub({ stateDir }).toolbox); assert.equal(check.status, 'info'); assert.match(check.summary ?? '', /not installed/); diff --git a/packages/platform-web/src/__tests__/provider-composition-fallback.test.ts b/packages/platform-web/src/__tests__/provider-composition-fallback.test.ts index 9f0d5fba01..b6e1f781e1 100644 --- a/packages/platform-web/src/__tests__/provider-composition-fallback.test.ts +++ b/packages/platform-web/src/__tests__/provider-composition-fallback.test.ts @@ -2,7 +2,11 @@ import { test } from 'vitest'; import assert from 'node:assert/strict'; import { AppError } from '@agent-device/kernel/errors'; import { createTestHostEnvironment } from '@agent-device/test-kit'; -import { resolveRequestScopedWebProvider, resolveWebProviderForHost } from '../resolve-provider.ts'; +import { + resolveRequestScopedWebProvider, + resolveWebProviderForToolbox, +} from '../resolve-provider.ts'; +import { createWebHostStub } from '../toolbox.fixtures.ts'; import { resolveWebProvider, withWebProvider } from '../provider.ts'; import { makeWebProvider } from './test-utils.ts'; @@ -47,12 +51,13 @@ test('a composed request provider answers instead of the fallback refusal', asyn test('the request-scoped resolver answers only inside a composed request, and the host resolver falls back', async () => { const provider = makeWebProvider(); - const host = createTestHostEnvironment(); + createTestHostEnvironment(); + const toolbox = createWebHostStub().toolbox; assert.equal(await resolveRequestScopedWebProvider(), undefined); - assert.notEqual(await resolveWebProviderForHost(host), provider); + assert.notEqual(await resolveWebProviderForToolbox(toolbox), provider); await withWebProvider(provider, async () => { assert.equal(await resolveRequestScopedWebProvider(), provider); - assert.equal(await resolveWebProviderForHost(host), provider); + assert.equal(await resolveWebProviderForToolbox(toolbox), provider); }); - assert.equal(await resolveWebProviderForHost(host, provider), provider); + assert.equal(await resolveWebProviderForToolbox(toolbox, provider), provider); }); diff --git a/packages/platform-web/src/__tests__/test-utils.ts b/packages/platform-web/src/__tests__/test-utils.ts index 240bc5ace3..56d9684513 100644 --- a/packages/platform-web/src/__tests__/test-utils.ts +++ b/packages/platform-web/src/__tests__/test-utils.ts @@ -11,6 +11,7 @@ import type { OwnedProcessRecordStore } from '@agent-device/host-kit/process'; import { installFakeManagedAgentBrowser } from '@agent-device/test-kit'; import { vi } from 'vitest'; import { createAgentBrowserWebProvider } from '../agent-browser-provider.ts'; +import { createWebHostStub, type WebHostStub } from '../toolbox.fixtures.ts'; import type { WebProvider } from '@agent-device/contracts/web-provider'; export function mkdtempForTestSync(prefix: string): string { @@ -60,16 +61,18 @@ export async function withManagedAgentBrowserProvider( openWebSessionNames?: () => readonly string[]; ownedProcessRecords?: OwnedProcessRecordStore; }, - testFn: (provider: WebProvider) => void | Promise, + testFn: (provider: WebProvider, toolbox: WebHostStub) => void | Promise, ): Promise { const stateDir = mkdtempForTestSync('agent device web provider '); installFakeManagedAgentBrowser(stateDir); + const stub = createWebHostStub({ stateDir, ...options }); await testFn( createAgentBrowserWebProvider({ - host: { env: process.env, cwd: process.cwd() }, + toolbox: stub.toolbox, ...options, stateDir, }), + stub, ); } diff --git a/packages/platform-web/src/agent-browser-install.ts b/packages/platform-web/src/agent-browser-install.ts index bfd3e77e66..e638d14c82 100644 --- a/packages/platform-web/src/agent-browser-install.ts +++ b/packages/platform-web/src/agent-browser-install.ts @@ -1,7 +1,5 @@ import path from 'node:path'; import { AppError } from '@agent-device/kernel/errors'; -import { runCmd } from '@agent-device/host-kit/command'; -import type { PlatformHost } from 'agent-device/plugins'; import type { EnvMap } from '@agent-device/kernel/source-value'; import { ensureHostDirectorySync, @@ -13,6 +11,7 @@ import { hostNodeVersion, hostPlatform, } from '@agent-device/host-kit/process'; +import type { WebCommandRunner } from './command-host.ts'; /** * How the managed backend gets onto disk. Kept apart from the tool module, @@ -23,7 +22,8 @@ export async function installManagedAgentBrowserPackage(params: { packageSpec: string; timeoutMs: number; env: Readonly; - runCommand?: PlatformHost['runCommand']; + /** The plugin's command route: npm is the host's to spawn, like every other command. */ + commands: WebCommandRunner; }): Promise { ensureHostDirectorySync(params.packageRoot); // `--no-global` keeps an ambient `npm_config_global` from redirecting the @@ -38,7 +38,7 @@ export async function installManagedAgentBrowserPackage(params: { '--no-save', params.packageSpec, ]); - await (params.runCommand ?? runCmd)(npm.command, npm.args, { + await params.commands.run(npm.command, npm.args, { env: params.env, timeoutMs: params.timeoutMs, }); diff --git a/packages/platform-web/src/agent-browser-lifecycle.test.ts b/packages/platform-web/src/agent-browser-lifecycle.test.ts index 2e69acd2f1..c69f8cf20a 100644 --- a/packages/platform-web/src/agent-browser-lifecycle.test.ts +++ b/packages/platform-web/src/agent-browser-lifecycle.test.ts @@ -77,12 +77,38 @@ import { import { getManagedAgentBrowserStatus } from './agent-browser-tool.ts'; import { createOwnedProcessRecordStore, + listHostProcesses, reapOwnedProcessRecordsAtStartup, } from '@agent-device/host-kit/process'; +import { createWebToolbox, type WebToolbox } from './toolbox.ts'; bindTestCommandHost(); const testHost = createLiveTestHostEnvironment(); +/** + * The plugin's toolbox over an in-memory host: commands and process-table reads are recorded, and + * the reads go through the module-level `listHostProcesses` this suite fakes, so a scenario's + * `observeProcesses(...)` fixture still answers them. + */ +function createLifecycleToolbox(stateDir: string): WebToolbox { + const host = { + ...testHost, + stateDir, + runCommand: async ( + executable: string, + args: string[], + options: { env?: NodeJS.ProcessEnv; timeoutMs?: number; stdin?: string }, + ) => await runCmdMock(executable, args, options), + isFileExecutable: async () => false, + isExecutableOnPath: async () => false, + listHostProcesses: async (options: { timeoutMs: number }) => await listHostProcesses(options), + emitDiagnostic: () => {}, + withDiagnosticTimer: async (_phase: string, operation: () => Promise): Promise => + await operation(), + }; + return createWebToolbox(host as unknown as Parameters[0]); +} + const mockRunCmd = vi.mocked(runCmdMock); beforeEach(() => { @@ -205,6 +231,7 @@ test('cleanup skips reaping when the daemon reports open web sessions', async () }); const result = await cleanupManagedAgentBrowserOrphans(status, 'daemon-startup', { env: process.env, + emitDiagnostic: () => {}, openWebSessionNames: ['default-web'], }); @@ -250,6 +277,7 @@ test('cleanup skips reaping while the browser fleet holds an opening session', a }); const result = await cleanupManagedAgentBrowserOrphans(status, 'provider-startup', { env: process.env, + emitDiagnostic: () => {}, ownedProcessRecords, }); @@ -274,6 +302,7 @@ test('cleanup reaps when the only fleet session is the one whose open runs it', }); const result = await cleanupManagedAgentBrowserOrphans(status, 'provider-startup', { env: process.env, + emitDiagnostic: () => {}, ownedProcessRecords, startingSession: 'fleet-web', }); @@ -300,6 +329,7 @@ test('cleanup evicts a launched session whose recorded browser exited, then reap }); const result = await cleanupManagedAgentBrowserOrphans(status, 'provider-startup', { env: process.env, + emitDiagnostic: () => {}, ownedProcessRecords, }); @@ -327,6 +357,7 @@ test('cleanup keeps a launched session when the process probe does not answer', }); const result = await cleanupManagedAgentBrowserOrphans(status, 'provider-startup', { env: process.env, + emitDiagnostic: () => {}, ownedProcessRecords, }); @@ -354,6 +385,7 @@ test('cleanup skips reaping when managed browser socket activity is recent', asy const result = await cleanupManagedAgentBrowserOrphans(status, 'daemon-startup', { env: process.env, + emitDiagnostic: () => {}, }); assert.equal(result.skipped?.reason, 'recent-browser-activity'); @@ -383,6 +415,7 @@ test('cleanup does not treat the shared socket directory mtime as browser activi const result = await cleanupManagedAgentBrowserOrphans(status, 'daemon-startup', { env: process.env, + emitDiagnostic: () => {}, }); assert.equal(result.skipped, undefined); @@ -439,6 +472,7 @@ test('cleanup reads recorded browser identities without reconstructing a process }); const result = await cleanupManagedAgentBrowserOrphans(status, 'provider-startup', { env: process.env, + emitDiagnostic: () => {}, ownedProcessRecords, }); @@ -561,9 +595,10 @@ test.each([ }); observeProcesses([{ pid: 101, command: `${binary} daemon`, executable: observed }]); const store = { replace: vi.fn(), clear: vi.fn(), read: vi.fn(() => []) }; - expect((await recordManagedAgentBrowserProcesses(status, store, testHost)).pids).toEqual( - expected, - ); + expect( + (await recordManagedAgentBrowserProcesses(status, store, createLifecycleToolbox(stateDir))) + .pids, + ).toEqual(expected); } finally { fs.rmSync(stateDir, { recursive: true, force: true }); } @@ -591,7 +626,10 @@ test('a managed binary symlink cannot confer ownership on an executable outside ]); const store = { replace: vi.fn(), clear: vi.fn(), read: vi.fn(() => []) }; - expect((await recordManagedAgentBrowserProcesses(status, store, testHost)).pids).toEqual([101]); + expect( + (await recordManagedAgentBrowserProcesses(status, store, createLifecycleToolbox(stateDir))) + .pids, + ).toEqual([101]); expect(store.replace.mock.calls[0]?.[1].map(({ pid }: { pid: number }) => pid)).toEqual([101]); } finally { fs.rmSync(stateDir, { recursive: true, force: true }); @@ -619,7 +657,11 @@ test('records verified current and retained native roots and stable descendants' ]; observeProcesses(rows); const store = { replace: vi.fn(), clear: vi.fn(), read: vi.fn(() => []) }; - const summary = await recordManagedAgentBrowserProcesses(status, store, testHost); + const summary = await recordManagedAgentBrowserProcesses( + status, + store, + createLifecycleToolbox(stateDir), + ); expect(summary.pids).toEqual([101, 102, 201, 301]); expect(summary.processes.map(({ reason }) => reason)).toEqual([ 'agent-browser-daemon', @@ -698,7 +740,11 @@ test('browser home roots require executable containment and marker roots require ]; observeProcesses(rows); const store = { replace: vi.fn(), clear: vi.fn(), read: vi.fn(() => []) }; - const summary = await recordManagedAgentBrowserProcesses(status, store, testHost); + const summary = await recordManagedAgentBrowserProcesses( + status, + store, + createLifecycleToolbox(stateDir), + ); expect(summary.pids).toEqual([201, 202, 209, 210, 213]); expect(summary.processes.map(({ reason }) => reason)).toEqual([ 'launch-marker', @@ -761,7 +807,11 @@ test('an unstable root or intermediate process cannot authorize its descendants' ), ); const store = { replace: vi.fn(), clear: vi.fn(), read: vi.fn(() => []) }; - const summary = await recordManagedAgentBrowserProcesses(status, store, testHost); + const summary = await recordManagedAgentBrowserProcesses( + status, + store, + createLifecycleToolbox(stateDir), + ); expect(summary.pids).toEqual([101]); } finally { fs.rmSync(stateDir, { recursive: true, force: true }); @@ -783,7 +833,10 @@ test('recording refuses a scanned command that differs from the bracketed identi new Map([[101, { startTime: 'start-101', command: 'different command', zombie: false }]]), ); const store = { replace: vi.fn(), clear: vi.fn(), read: vi.fn(() => []) }; - expect((await recordManagedAgentBrowserProcesses(status, store, testHost)).pids).toEqual([]); + expect( + (await recordManagedAgentBrowserProcesses(status, store, createLifecycleToolbox(stateDir))) + .pids, + ).toEqual([]); expect(store.replace).not.toHaveBeenCalled(); } finally { fs.rmSync(stateDir, { recursive: true, force: true }); @@ -828,7 +881,7 @@ test('recording and reaping require executable provenance and matching identity' sessionsDir: path.join(stateDir, 'sessions'), resolveSessionDir: (id) => path.join(stateDir, 'sessions', id), }); - await recordManagedAgentBrowserProcesses(status, store, testHost); + await recordManagedAgentBrowserProcesses(status, store, createLifecycleToolbox(stateDir)); const recordedPids = store.read()[0]?.records.map(({ pid }) => pid); const alive = new Set(rows.map(({ pid }) => pid)); const signals: number[] = []; @@ -894,6 +947,7 @@ test('cleanup retains legacy records without signaling or treating them as verif }); const result = await cleanupManagedAgentBrowserOrphans(status, 'daemon-startup', { env: process.env, + emitDiagnostic: () => {}, ownedProcessRecords: store, }); expect(result.pids).toEqual([]); diff --git a/packages/platform-web/src/agent-browser-lifecycle.ts b/packages/platform-web/src/agent-browser-lifecycle.ts index 1338a4a7b2..e7d9823942 100644 --- a/packages/platform-web/src/agent-browser-lifecycle.ts +++ b/packages/platform-web/src/agent-browser-lifecycle.ts @@ -1,12 +1,12 @@ import path from 'node:path'; import type { EnvMap } from '@agent-device/kernel/source-value'; import { uniqueStrings } from '@agent-device/kernel/collections'; -import { emitDiagnostic, type DiagnosticEventInput } from '@agent-device/host-kit/diagnostics'; import { hostFileStatSync, readHostDirectorySync } from '@agent-device/host-kit/host-file'; import { type OwnedProcessRecordStore, reapOwnedProcessRecordsAtStartup, } from '@agent-device/host-kit/process'; +import type { DiagnosticEventInput } from '@agent-device/host-kit/diagnostics'; import { agentBrowserFleetOf } from './agent-browser-fleet.ts'; import type { AgentBrowserToolStatus } from './agent-browser-tool.ts'; @@ -43,9 +43,10 @@ export type AgentBrowserCleanupResult = AgentBrowserProcessSummary & { export type AgentBrowserCleanupOptions = { /** The caller's host: its environment carries the idle-timeout overrides. */ env: Readonly; + /** Where the reap is reported: the host the plugin was set up with. */ + emitDiagnostic(event: DiagnosticEventInput): void; openWebSessionNames?: readonly string[]; ownedProcessRecords?: OwnedProcessRecordStore; - emitDiagnostic?(event: DiagnosticEventInput): void; /** The fleet session whose open runs this cleanup: it has spawned nothing yet, so it never blocks the reap. */ startingSession?: string; }; @@ -96,7 +97,7 @@ export async function cleanupManagedAgentBrowserOrphans( }); const signalPids = [...reaped.terminatedPids]; if (reaped.inspected > 0) { - (options.emitDiagnostic ?? emitDiagnostic)({ + options.emitDiagnostic({ level: 'warn', phase: 'web_agent_browser_orphan_cleanup', data: { diff --git a/packages/platform-web/src/agent-browser-process-record.ts b/packages/platform-web/src/agent-browser-process-record.ts index 58b885275e..e2ef2b7209 100644 --- a/packages/platform-web/src/agent-browser-process-record.ts +++ b/packages/platform-web/src/agent-browser-process-record.ts @@ -1,17 +1,14 @@ -import type { HostEnvironment } from '@agent-device/kernel/source-value'; import crypto from 'node:crypto'; import path from 'node:path'; import type { OwnedProcessRecord } from '@agent-device/contracts/platform-runtime-host'; import { uniqueStrings } from '@agent-device/kernel/collections'; import { hostFileStatSync, realHostPathSync } from '@agent-device/host-kit/host-file'; -import { withoutCommandExecutorOverride } from '@agent-device/host-kit/command'; import { expandProcessTree, hostProcessId, hostPlatform, isProcessAlive, processStartTimesDiffer, - listHostProcesses, readHostProcessIdentityObservationsAsync, readProcessIdentities, readProcessExecutablePaths, @@ -24,6 +21,7 @@ import { type ManagedInstallPaths, } from './agent-browser-install-paths.ts'; import type { AgentBrowserToolStatus } from './agent-browser-tool.ts'; +import type { WebToolbox } from './toolbox.ts'; const HOST_PROCESS_LIST_TIMEOUT_MS = 1_500; const AGENT_DEVICE_BROWSER_MARKER_PREFIX = '--agent-device-managed-web='; @@ -132,20 +130,21 @@ function isChromeExecutable(executable: string): boolean { export async function inspectManagedAgentBrowserProcesses( status: AgentBrowserToolStatus, + toolbox: WebToolbox, ): Promise { - return summarizeAgentBrowserProcesses(await listRealHostProcesses(), status); + return summarizeAgentBrowserProcesses(await listRealHostProcesses(toolbox), status); } export async function recordManagedAgentBrowserProcesses( status: AgentBrowserToolStatus, store: OwnedProcessRecordStore, - host: HostEnvironment, + toolbox: WebToolbox, ): Promise { - const initial = await listRealHostProcesses(); + const initial = await listRealHostProcesses(toolbox); const pids = initial.map(({ pid }) => pid); const before = await readProcessIdentities(pids); - const scanned = await listRealHostProcesses(); - const executablePaths = await readProcessExecutablePaths(pids, host); + const scanned = await listRealHostProcesses(toolbox); + const executablePaths = await readProcessExecutablePaths(pids, toolbox.host); const after = await readProcessIdentities(pids); const initialPids = new Set(pids); const processes = scanned.filter(({ pid, command }) => { @@ -262,10 +261,9 @@ function readDaemonManagedWebBrowserRecords(store: OwnedProcessRecordStore): Own .filter((record) => record.purpose === MANAGED_WEB_BROWSER_PROCESS_PURPOSE); } -async function listRealHostProcesses(): Promise { - return await withoutCommandExecutorOverride( - async () => await listHostProcesses({ timeoutMs: HOST_PROCESS_LIST_TIMEOUT_MS }), - ); +async function listRealHostProcesses(toolbox: WebToolbox): Promise { + // The host reports the table; the fleet matchers below work on their own copies. + return [...(await toolbox.host.listHostProcesses({ timeoutMs: HOST_PROCESS_LIST_TIMEOUT_MS }))]; } function summarizeMatches( diff --git a/packages/platform-web/src/agent-browser-provider-rects.test.ts b/packages/platform-web/src/agent-browser-provider-rects.test.ts index 6faf16b0c3..de49a61748 100644 --- a/packages/platform-web/src/agent-browser-provider-rects.test.ts +++ b/packages/platform-web/src/agent-browser-provider-rects.test.ts @@ -22,6 +22,7 @@ import { createAgentBrowserWebProvider } from './agent-browser-provider.ts'; import type { WebSnapshotResult } from '@agent-device/contracts/web-provider'; import { withCommandExecutorOverride, type ExecResult } from '@agent-device/host-kit/command'; import { AppError } from '@agent-device/kernel/errors'; +import { createWebHostStub } from './toolbox.fixtures.ts'; bindTestCommandHost(); @@ -539,7 +540,7 @@ async function withWebProvider( installFakeManagedAgentBrowser(stateDir); await testFn( createAgentBrowserWebProvider({ - host: { env: process.env, cwd: process.cwd() }, + toolbox: createWebHostStub({ stateDir }).toolbox, stateDir, session: 'web-session', }), diff --git a/packages/platform-web/src/agent-browser-provider.test.ts b/packages/platform-web/src/agent-browser-provider.test.ts index 7f883aa828..f36f832a82 100644 --- a/packages/platform-web/src/agent-browser-provider.test.ts +++ b/packages/platform-web/src/agent-browser-provider.test.ts @@ -28,6 +28,7 @@ import { withCommandExecutorOverride, type ExecResult } from '@agent-device/host import { AppError, createRequestCanceledError } from '@agent-device/kernel/errors'; import { buildSelectorChainForNode, resolveRecordedTarget } from '@agent-device/selectors'; import { attachRefs } from '@agent-device/kernel/snapshot'; +import { createWebHostStub } from './toolbox.fixtures.ts'; bindTestCommandHost(); @@ -292,11 +293,21 @@ test('agent-browser provider runs provider-startup cleanup before the first mana assert.deepEqual(events, ['provider-startup-cleanup', 'agent-browser open']); assert.equal(mockProviderStartupCleanup.mock.calls.length, 1); - assert.deepEqual(mockProviderStartupCleanup.mock.calls[0]?.[1], { - env: process.env, - openWebSessionNames: [], - startingSession: 'web-session', - }); + const cleanupOptions = mockProviderStartupCleanup.mock.calls[0]?.[1] as Record; + // The cleanup is reported through the host the plugin was set up with, so the stub shows it here. + assert.equal(typeof cleanupOptions.emitDiagnostic, 'function'); + assert.deepEqual( + { + env: cleanupOptions.env, + openWebSessionNames: cleanupOptions.openWebSessionNames, + startingSession: cleanupOptions.startingSession, + }, + { + env: process.env, + openWebSessionNames: [], + startingSession: 'web-session', + }, + ); }); test('agent-browser provider ignores provider-startup cleanup failures', async () => { @@ -556,7 +567,7 @@ test('agent-browser provider adds doctor guidance for missing binary and invalid const missingStateDir = mkdtempForTestSync('agent-device-web-provider-missing-'); try { const provider = createAgentBrowserWebProvider({ - host: { env: process.env, cwd: process.cwd() }, + toolbox: createWebHostStub({ stateDir: missingStateDir }).toolbox, stateDir: missingStateDir, }); await assert.rejects( @@ -593,7 +604,7 @@ test('agent-browser provider preserves Node version guidance for missing managed const missingStateDir = mkdtempForTestSync('agent-device-web-provider-node-'); try { const provider = createAgentBrowserWebProvider({ - host: { env: process.env, cwd: process.cwd() }, + toolbox: createWebHostStub({ stateDir: missingStateDir }).toolbox, stateDir: missingStateDir, }); await assert.rejects( diff --git a/packages/platform-web/src/agent-browser-provider.ts b/packages/platform-web/src/agent-browser-provider.ts index 098d5cf6dd..701681f6cf 100644 --- a/packages/platform-web/src/agent-browser-provider.ts +++ b/packages/platform-web/src/agent-browser-provider.ts @@ -1,10 +1,9 @@ import { AGENT_BROWSER_TIMEOUT_MS } from '@agent-device/contracts/managed-web-backend'; -import { execFailureDetails } from '@agent-device/host-kit/command'; -import { emitDiagnostic } from '@agent-device/host-kit/diagnostics'; import type { OwnedProcessRecordStore } from '@agent-device/host-kit/process'; import { sleep } from '@agent-device/host-kit/retry'; import { AppError, + commandFailureDetails, type DispatchDisclosure, discloseDispatchAfterSteps, } from '@agent-device/kernel/errors'; @@ -27,6 +26,7 @@ import { readStringProperty, type JsonObject, } from './json-utils.ts'; +import type { WebToolbox } from './toolbox.ts'; import type { WebProvider, WebSnapshotOptions, @@ -36,7 +36,6 @@ import { getManagedAgentBrowserStatus, mapManagedAgentBrowserError, runManagedAgentBrowser, - type ManagedBrowserHost, } from './agent-browser-tool.ts'; import { agentBrowserFleetOf, type AgentBrowserFleet } from './agent-browser-fleet.ts'; import { cleanupManagedAgentBrowserOrphansForProviderStartup } from './agent-browser-lifecycle.ts'; @@ -52,8 +51,8 @@ const AGENT_BROWSER_DOCTOR_HINT = 'Run `agent-device web setup` to install the managed web backend.'; type AgentBrowserProviderOptions = { - /** The composing runtime's host; every backend spawn and status read uses it. */ - host: ManagedBrowserHost; + /** The plugin's toolbox; every backend spawn, process read and diagnostic uses its host. */ + toolbox: WebToolbox; /** The backend session key, read from the session device id; omitted for no session. */ session?: string; stateDir?: string; @@ -614,7 +613,8 @@ async function runAgentBrowserCommand( let exitCode = 0; let commandCompleted = false; let semanticSuccess = false; - const status = getManagedAgentBrowserStatus({ host: options.host, stateDir: options.stateDir }); + const { host } = options.toolbox; + const status = getManagedAgentBrowserStatus({ host, stateDir: options.stateDir }); try { const startingSession = cliArgs[0] === 'open' ? fleetSessionOf(options) : undefined; if (options.ownedProcessRecords && startingSession !== undefined) { @@ -622,7 +622,7 @@ async function runAgentBrowserCommand( } await cleanupProviderStartupOrphans(options, startingSession); const result = await runManagedAgentBrowser(cliArgs, { - host: options.host, + toolbox: options.toolbox, stateDir: options.stateDir, allowFailure: true, timeoutMs: AGENT_BROWSER_TIMEOUT_MS, @@ -687,10 +687,10 @@ async function finalizeAgentBrowserProcessRecord(params: { return; } if (await shouldRefreshAgentBrowserProcessRecord(params, store)) { - await recordManagedAgentBrowserProcesses(params.status, store, params.options.host); + await recordManagedAgentBrowserProcesses(params.status, store, params.options.toolbox); } } catch (error) { - (params.options.host.emitDiagnostic ?? emitDiagnostic)({ + params.options.toolbox.host.emitDiagnostic({ level: 'warn', phase: 'web_agent_browser_process_record_failed', data: { error: error instanceof Error ? error.message : String(error) }, @@ -783,12 +783,13 @@ async function cleanupProviderStartupOrphans( startingSession: string | undefined, ): Promise { if (!options.openWebSessionNames) return; - const status = getManagedAgentBrowserStatus({ host: options.host, stateDir: options.stateDir }); + const { host } = options.toolbox; + const status = getManagedAgentBrowserStatus({ host, stateDir: options.stateDir }); if (!status.installed) return; try { await cleanupManagedAgentBrowserOrphansForProviderStartup(status, { - env: options.host.env, - ...(options.host.emitDiagnostic ? { emitDiagnostic: options.host.emitDiagnostic } : {}), + env: host.env, + emitDiagnostic: host.emitDiagnostic, openWebSessionNames: options.openWebSessionNames(), ...(startingSession === undefined ? {} : { startingSession }), ...(options.ownedProcessRecords === undefined @@ -796,7 +797,7 @@ async function cleanupProviderStartupOrphans( : { ownedProcessRecords: options.ownedProcessRecords }), }); } catch (error) { - (options.host.emitDiagnostic ?? emitDiagnostic)({ + host.emitDiagnostic({ level: 'warn', phase: 'web_agent_browser_provider_orphan_cleanup_failed', data: { error: error instanceof Error ? error.message : String(error) }, @@ -825,7 +826,7 @@ function unwrapAgentBrowserJson( throw new AppError( 'COMMAND_FAILED', 'agent-browser command failed', - execFailureDetails(result, { + commandFailureDetails(result, { cmd: AGENT_BROWSER, args: cliArgs, stdout: result.stdout.slice(0, 500), diff --git a/packages/platform-web/src/agent-browser-tool.test.ts b/packages/platform-web/src/agent-browser-tool.test.ts index 96892f1290..a277c2ca39 100644 --- a/packages/platform-web/src/agent-browser-tool.test.ts +++ b/packages/platform-web/src/agent-browser-tool.test.ts @@ -14,6 +14,7 @@ import { setupManagedAgentBrowser, } from './agent-browser-tool.ts'; import { mkdtempForTestSync, writeFakeNpmCliScript } from './__tests__/test-utils.ts'; +import { createWebHostStub } from './toolbox.fixtures.ts'; import { AppError } from '@agent-device/kernel/errors'; import { withCommandExecutorOverride } from '@agent-device/host-kit/command'; @@ -27,7 +28,7 @@ test('managed agent-browser reports actionable guidance when install is missing' await assert.rejects( () => runManagedAgentBrowser(['doctor'], { - host: { env: process.env, cwd: process.cwd() }, + toolbox: createWebHostStub({ stateDir }).toolbox, stateDir, timeoutMs: 1_000, }), @@ -59,7 +60,7 @@ test('managed agent-browser runs its JS entry with the current Node runtime, not }, async () => await runManagedAgentBrowser(['snapshot', '--json'], { - host: { env: process.env, cwd: process.cwd() }, + toolbox: createWebHostStub({ stateDir }).toolbox, stateDir, timeoutMs: 1_000, }), @@ -80,6 +81,9 @@ test('managed agent-browser passes the managed runtime home and socket dir to th try { const install = installFakeManagedAgentBrowser(stateDir); let env: NodeJS.ProcessEnv | undefined; + // The plugin asks its own host to run the entry; the stub records that and hands the answer + // back through the command host this suite answers on. + const stub = createWebHostStub({ stateDir }); await withCommandExecutorOverride( async (_cmd, _args, options) => { @@ -88,7 +92,7 @@ test('managed agent-browser passes the managed runtime home and socket dir to th }, async () => await runManagedAgentBrowser(['doctor'], { - host: { env: process.env, cwd: process.cwd() }, + toolbox: stub.toolbox, stateDir, timeoutMs: 1_000, }), @@ -101,6 +105,11 @@ test('managed agent-browser passes the managed runtime home and socket dir to th assert.notEqual(install.runtimeHomeDir, install.homeDir); assert.ok(fs.existsSync(install.runtimeHomeDir)); assert.ok(fs.existsSync(install.socketDir)); + // The host the plugin was set up with ran the backend, with the managed environment it built. + assert.deepEqual( + stub.commands.map(({ executable, args }) => ({ executable, args })), + [{ executable: process.execPath, args: [install.entryScript, 'doctor'] }], + ); } finally { fs.rmSync(stateDir, { recursive: true, force: true }); } @@ -189,7 +198,7 @@ for (const scenario of [ async () => await setupManagedAgentBrowser({ stateDir, - host: { env: process.env, cwd: process.cwd() }, + toolbox: createWebHostStub({ stateDir }).toolbox, }), ); if (scenario.expected === 'missing') { @@ -251,7 +260,7 @@ test('managed agent-browser setup reports an install that produced no entry', as () => setupManagedAgentBrowser({ stateDir, - host: { env: process.env, cwd: process.cwd() }, + toolbox: createWebHostStub({ stateDir }).toolbox, }), (error: unknown) => error instanceof AppError && @@ -280,13 +289,13 @@ test('managed agent-browser setup gives the install lock back on every path out' async () => { await setupManagedAgentBrowser({ stateDir, - host: { env: process.env, cwd: process.cwd() }, + toolbox: createWebHostStub({ stateDir }).toolbox, }); // The package exists by now, so this second call returns from *inside* the lock // rather than running to the end of it. await setupManagedAgentBrowser({ stateDir, - host: { env: process.env, cwd: process.cwd() }, + toolbox: createWebHostStub({ stateDir }).toolbox, }); }, ); diff --git a/packages/platform-web/src/agent-browser-tool.ts b/packages/platform-web/src/agent-browser-tool.ts index c4c6bb234c..654cd609a4 100644 --- a/packages/platform-web/src/agent-browser-tool.ts +++ b/packages/platform-web/src/agent-browser-tool.ts @@ -1,6 +1,4 @@ -import type { PlatformHost } from 'agent-device/plugins'; import path from 'node:path'; -import { runCmd, type ExecResult } from '@agent-device/host-kit/command'; import { acquireProcessLock, withProcessLock } from '@agent-device/host-kit/file'; import { createHostDirectoryLinkSync, @@ -22,6 +20,7 @@ import { import { AppError, asAppError } from '@agent-device/kernel/errors'; import type { HostEnvironment } from '@agent-device/kernel/source-value'; import type { ManagedWebBackendStatus } from '@agent-device/contracts/managed-web-backend'; +import type { WebCommandResult } from './command-host.ts'; import { installManagedAgentBrowserPackage, writeManagedAgentBrowserManifest, @@ -31,6 +30,7 @@ import { appendAgentDeviceChromeArgs, resolveAgentBrowserIdleTimeoutMs, } from './agent-browser-lifecycle.ts'; +import type { WebToolbox } from './toolbox.ts'; const MANAGED_AGENT_BROWSER_VERSION = '0.39.0'; @@ -40,12 +40,10 @@ const SETUP_TIMEOUT_MS = 5 * 60_000; const DOCTOR_TIMEOUT_MS = 60_000; export type AgentBrowserToolStatus = ManagedWebBackendStatus; -export type ManagedBrowserHost = HostEnvironment & - Partial>; export type ManagedAgentBrowserRunOptions = { - /** The caller's host: its environment selects the state dir and seeds the backend env. */ - host: ManagedBrowserHost; + /** The plugin's toolbox: its host selects the state dir and seeds the backend env. */ + toolbox: WebToolbox; stateDir?: string; timeoutMs: number; allowFailure?: boolean; @@ -62,17 +60,20 @@ export type ManagedAgentBrowserRunOptions = { export async function runManagedAgentBrowser( args: readonly string[], options: ManagedAgentBrowserRunOptions, -): Promise { - const status = getManagedAgentBrowserStatus({ host: options.host, stateDir: options.stateDir }); +): Promise { + const status = getManagedAgentBrowserStatus({ + host: options.toolbox.host, + stateDir: options.stateDir, + }); if (!status.installed) throw missingManagedToolError(status); return await spawnManagedAgentBrowser(status, args, options); } export async function setupManagedAgentBrowser(options: { - host: ManagedBrowserHost; + toolbox: WebToolbox; stateDir?: string; }): Promise { - const status = getManagedAgentBrowserStatus(options); + const status = getManagedAgentBrowserStatus(managedStatusOptions(options)); assertWebNodeSupported(status.nodeMajor); const processId = hostProcessId(); @@ -89,25 +90,25 @@ export async function setupManagedAgentBrowser(options: { description: 'managed agent-browser setup', }), task: async () => { - const freshStatus = getManagedAgentBrowserStatus(options); + const freshStatus = getManagedAgentBrowserStatus(managedStatusOptions(options)); if (freshStatus.installed) return freshStatus; ensureHostDirectorySync(freshStatus.installDir); await installManagedAgentBrowserPackage({ packageRoot: path.join(freshStatus.installDir, 'package'), packageSpec: `${AGENT_BROWSER}@${MANAGED_AGENT_BROWSER_VERSION}`, timeoutMs: SETUP_TIMEOUT_MS, - env: options.host.env, - runCommand: options.host.runCommand, + env: options.toolbox.host.env, + commands: options.toolbox.commands, }); // The backend entry only exists once npm has written the package. - const installedStatus = getManagedAgentBrowserStatus(options); + const installedStatus = getManagedAgentBrowserStatus(managedStatusOptions(options)); if (!installedStatus.entryScript) throw unusableInstallError(installedStatus); await spawnManagedAgentBrowser(installedStatus, ['install'], { - host: options.host, + toolbox: options.toolbox, timeoutMs: SETUP_TIMEOUT_MS, }); await spawnManagedAgentBrowser(installedStatus, ['doctor', '--offline', '--quick'], { - host: options.host, + toolbox: options.toolbox, timeoutMs: DOCTOR_TIMEOUT_MS, }); writeManagedAgentBrowserManifest({ @@ -115,29 +116,45 @@ export async function setupManagedAgentBrowser(options: { packageName: AGENT_BROWSER, version: MANAGED_AGENT_BROWSER_VERSION, }); - return await getManagedAgentBrowserStatus(options); + return await getManagedAgentBrowserStatus(managedStatusOptions(options)); }, }); } export async function doctorManagedAgentBrowser(options: { - host: ManagedBrowserHost; + toolbox: WebToolbox; stateDir?: string; }): Promise<{ status: AgentBrowserToolStatus; stdout: string; stderr: string; exitCode: number }> { - const status = getManagedAgentBrowserStatus(options); + const status = getManagedAgentBrowserStatus(managedStatusOptions(options)); if (!status.installed) { throw missingManagedToolError(status); } const result = await spawnManagedAgentBrowser(status, ['doctor', '--offline', '--quick'], { - host: options.host, + toolbox: options.toolbox, timeoutMs: DOCTOR_TIMEOUT_MS, allowFailure: true, }); return { status, ...result }; } +/** + * Where the managed backend is on disk, and whether it is there. Reads only the host's environment + * and the filesystem, so it answers the same way whether or not anything is installed. + */ +/** Reads a status for the host one of the toolbox-taking operations was set up with. */ +function managedStatusOptions(options: { toolbox: WebToolbox; stateDir?: string }): { + host: HostEnvironment; + stateDir?: string; +} { + return { + host: options.toolbox.host, + ...(options.stateDir === undefined ? {} : { stateDir: options.stateDir }), + }; +} + export function getManagedAgentBrowserStatus(options: { - host: ManagedBrowserHost; + /** Either the calling runtime's host or the plugin's own host; both answer the same way. */ + host: HostEnvironment; stateDir?: string; }): AgentBrowserToolStatus { const stateDir = @@ -173,14 +190,14 @@ async function spawnManagedAgentBrowser( status: AgentBrowserToolStatus, args: readonly string[], options: Omit, -): Promise { +): Promise { if (!status.entryScript) throw missingManagedToolError(status); - return await (options.host.runCommand ?? runCmd)( + return await options.toolbox.commands.run( hostNodeExecutablePath(), [status.entryScript, ...args], { allowFailure: options.allowFailure, - env: managedAgentBrowserEnv(status, options.host.env), + env: managedAgentBrowserEnv(status, options.toolbox.host.env), timeoutMs: options.timeoutMs, signal: options.signal, stdin: options.stdin, diff --git a/packages/platform-web/src/command-host.ts b/packages/platform-web/src/command-host.ts new file mode 100644 index 0000000000..9356e1ff5e --- /dev/null +++ b/packages/platform-web/src/command-host.ts @@ -0,0 +1,45 @@ +import type { PlatformHost } from 'agent-device/plugins'; + +/** What the host answered a command: its streams and its exit code. */ +export type WebCommandResult = Awaited>; + +/** + * How one managed-backend call runs. The environment arrives whole: the backend needs its own + * `HOME`, socket dir and launch marker per command, so the caller builds that environment from the + * host it was given rather than letting a spawn inherit a bare one. + */ +export type WebRunOptions = Readonly<{ + env?: PlatformHost['env']; + allowFailure?: boolean; + timeoutMs?: number; + signal?: AbortSignal; + /** Written to the child's stdin, for the command that reads its work from it (`batch`). */ + stdin?: string; +}>; + +/** + * The plugin's route to host commands, bound to the `PlatformHost` the core handed `setup()`. The + * core owns the spawn and the exec trace, so a `--debug` log shows this family's backend calls under + * its request id. + * + * Every spawn, executable probe and process-table read goes through that host rather than this + * bundle's own copy of the host kit: the daemon's command scope never enters the bundled copy, so a + * spawn made from it would run with the daemon process environment instead of the host environment + * captured for the request, and would drop the family's traces. Only host-kit *types* are imported + * here, which cost the bundle nothing. + */ +export type WebCommandRunner = Readonly<{ + run( + executable: string, + args: readonly string[], + options?: WebRunOptions, + ): Promise; +}>; + +/** Binds the host the plugin was set up with. Nothing is read from it until a command runs. */ +export function createWebCommandRunner(host: PlatformHost): WebCommandRunner { + return Object.freeze({ + run: async (executable, args, options) => + await host.runCommand(executable, [...args], { ...options }), + }); +} diff --git a/packages/platform-web/src/doctor.ts b/packages/platform-web/src/doctor.ts index 7de9290ab3..a3b9591dd4 100644 --- a/packages/platform-web/src/doctor.ts +++ b/packages/platform-web/src/doctor.ts @@ -1,13 +1,13 @@ import type { DoctorCheck } from '@agent-device/contracts/observability'; -import type { HostEnvironment } from '@agent-device/kernel/source-value'; import { inspectManagedAgentBrowserProcesses } from './agent-browser-lifecycle.ts'; import { getManagedAgentBrowserStatus } from './agent-browser-tool.ts'; +import type { WebToolbox } from './toolbox.ts'; export async function webBrowserLifecycleCheck( stateDir: string, - host: HostEnvironment, + toolbox: WebToolbox, ): Promise { - const status = getManagedAgentBrowserStatus({ stateDir, host }); + const status = getManagedAgentBrowserStatus({ stateDir, host: toolbox.host }); if (!status.installed) { return { id: 'web-agent-browser-processes', @@ -18,7 +18,7 @@ export async function webBrowserLifecycleCheck( }; } try { - const summary = await inspectManagedAgentBrowserProcesses(status); + const summary = await inspectManagedAgentBrowserProcesses(status, toolbox); return { id: 'web-agent-browser-processes', status: summary.count > 0 ? 'info' : 'pass', diff --git a/packages/platform-web/src/index-startup-cleanup.test.ts b/packages/platform-web/src/index-startup-cleanup.test.ts index 2b835ca1a6..1ff91a49cf 100644 --- a/packages/platform-web/src/index-startup-cleanup.test.ts +++ b/packages/platform-web/src/index-startup-cleanup.test.ts @@ -18,7 +18,7 @@ vi.mock('./agent-browser-lifecycle.ts', async (importOriginal) => ({ import webPlatformPlugin from './index.ts'; import { emitDiagnostic, withDiagnosticTimer } from '@agent-device/host-kit/diagnostics'; -import { runCmd, isExecutablePath } from '@agent-device/host-kit/command'; +import { runCmd, isExecutablePath, whichCmd } from '@agent-device/host-kit/command'; function cleanupWebBrowserOrphansForDaemonStartup(stateDir: string) { const host = { @@ -26,6 +26,8 @@ function cleanupWebBrowserOrphansForDaemonStartup(stateDir: string) { stateDir, runCommand: runCmd, isFileExecutable: isExecutablePath, + isExecutableOnPath: async (executable: string) => await whichCmd(executable, process.env), + listHostProcesses: async () => [], emitDiagnostic, withDiagnosticTimer, }; diff --git a/packages/platform-web/src/index.ts b/packages/platform-web/src/index.ts index a335feb46c..31a6903b4d 100644 --- a/packages/platform-web/src/index.ts +++ b/packages/platform-web/src/index.ts @@ -1,4 +1,5 @@ -import type { PlatformContribution, PlatformSetup } from 'agent-device/plugins'; +import type { PlatformContribution, PlatformHost, PlatformSetup } from 'agent-device/plugins'; +import type { WebToolbox } from './toolbox.ts'; import type { InventoryPlatformModule, PlatformModuleMetadata, @@ -9,6 +10,25 @@ const metadata = Object.freeze({ family: 'web', } satisfies PlatformModuleMetadata); +/** + * The toolbox module, resolved exactly once per process. The façade must stay metadata-eager + * (ADR-0019), so the module that binds a host's command port enters with the first operation that + * needs it rather than above it. Only the module is memoized: each `setup` call binds its own host. + */ +let toolboxModule: Promise | undefined; + +/** + * A bound toolbox, made on first use and then reused: a `setup` that never runs a command imports + * and builds nothing, and the operations of one setup share the one toolbox it binds its host to. + */ +function webToolbox(host: PlatformHost) { + let toolbox: Promise | undefined; + return async () => + (toolbox ??= (toolboxModule ??= import('./toolbox.ts')).then(({ createWebToolbox }) => + createWebToolbox(host), + )); +} + const runtimeModule = Object.freeze({ ...metadata, loadRuntime: async (host) => { @@ -32,15 +52,22 @@ function webPlatformPlugin() { { kind: 'platform', family: 'web', - setup(host): PlatformSetup<'web'> { - const { stateDir, openWebSessionNames, ownedProcessRecords } = host; + // Importing this package evaluates nothing but itself, and the host is bound to a toolbox + // only when an operation first needs one. Every operation below asks the same lazy + // resolution, so one setup builds exactly one toolbox for the whole family. + setup(host: PlatformHost): PlatformSetup<'web'> { + const { stateDir } = host; + const toolbox = webToolbox(host); return { family: 'web', inventoryModule, runtimeModule, createInteractor: async () => { - const { createWebInteractor } = await import('./interactor.ts'); - return await createWebInteractor(host, undefined, stateDir); + const [{ createWebInteractor }, bound] = await Promise.all([ + import('./interactor.ts'), + toolbox(), + ]); + return await createWebInteractor(bound, undefined, stateDir); }, withRequestProvider: async (provider, task) => { const { withWebProvider } = await import('./provider.ts'); @@ -51,42 +78,49 @@ function webPlatformPlugin() { const { setupManagedAgentBrowser } = await import('./agent-browser-tool.ts'); return await setupManagedAgentBrowser({ stateDir: options.stateDir ?? stateDir, - host, + toolbox: await toolbox(), }); }, doctor: async (options) => { const { doctorManagedAgentBrowser } = await import('./agent-browser-tool.ts'); return await doctorManagedAgentBrowser({ stateDir: options.stateDir ?? stateDir, - host, + toolbox: await toolbox(), }); }, browserLifecycleCheck: async (dir) => { - const { webBrowserLifecycleCheck } = await import('./doctor.ts'); - return await webBrowserLifecycleCheck(dir, host); + const [{ webBrowserLifecycleCheck }, bound] = await Promise.all([ + import('./doctor.ts'), + toolbox(), + ]); + return await webBrowserLifecycleCheck(dir, bound); }, cleanupOrphans: async (openSessions) => { - const { getManagedAgentBrowserStatus } = await import('./agent-browser-tool.ts'); - const status = getManagedAgentBrowserStatus({ stateDir, host }); + const [{ getManagedAgentBrowserStatus }, bound] = await Promise.all([ + import('./agent-browser-tool.ts'), + toolbox(), + ]); + const status = getManagedAgentBrowserStatus({ stateDir, host: bound.host }); if (!status.installed) return; const { cleanupManagedAgentBrowserOrphans } = await import('./agent-browser-lifecycle.ts'); await cleanupManagedAgentBrowserOrphans(status, 'daemon-startup', { - env: host.env, + env: bound.host.env, + emitDiagnostic: bound.host.emitDiagnostic, openWebSessionNames: openSessions, - ownedProcessRecords, - emitDiagnostic: host.emitDiagnostic, + ownedProcessRecords: bound.host.ownedProcessRecords, }); }, createProvider: async (session) => { const { createAgentBrowserWebProvider } = await import('./agent-browser-provider.ts'); + const bound = await toolbox(); return await createAgentBrowserWebProvider({ - host, + toolbox: bound, stateDir, session, - openWebSessionNames, - ownedProcessRecords, + openWebSessionNames: bound.host.openWebSessionNames, + ownedProcessRecords: bound.host.ownedProcessRecords, }); }, resolveRequestProvider: async () => { diff --git a/packages/platform-web/src/interactor.test.ts b/packages/platform-web/src/interactor.test.ts index d03b4dcd93..3c2786f472 100644 --- a/packages/platform-web/src/interactor.test.ts +++ b/packages/platform-web/src/interactor.test.ts @@ -4,6 +4,7 @@ import { createWebInteractor } from './interactor.ts'; import { AppError } from '@agent-device/kernel/errors'; import { withWebProvider } from './provider.ts'; import { makeWebProvider } from './__tests__/test-utils.ts'; +import { createWebHostStub } from './toolbox.fixtures.ts'; test('web interactor delegates first-slice operations to the scoped provider', async () => { const calls: string[] = []; @@ -45,7 +46,7 @@ test('web interactor delegates first-slice operations to the scoped provider', a }); const snapshot = await withWebProvider(provider, async () => { - const interactor = await createWebInteractor({ env: process.env, cwd: process.cwd() }); + const interactor = await createWebInteractor(createWebHostStub().toolbox); await interactor.open('https://example.test'); await interactor.open('app-shell', { url: 'https://example.test/deep' }); await interactor.close('app-shell'); @@ -82,7 +83,7 @@ test('web interactor delegates first-slice operations to the scoped provider', a test('web interactor reports hover unsupported when the provider lacks it', async () => { await withWebProvider(makeWebProvider(), async () => { - const interactor = await createWebInteractor({ env: process.env, cwd: process.cwd() }); + const interactor = await createWebInteractor(createWebHostStub().toolbox); assert.equal(interactor.tapRef, undefined); assert.equal(interactor.hover, undefined); assert.equal(interactor.hoverRef, undefined); @@ -94,14 +95,14 @@ test('web interactor reports hover unsupported when the provider lacks it', asyn // web session must carry no fused double-click of its own. test('web interactor carries no fused double-click mechanic', async () => { await withWebProvider(makeWebProvider(), async () => { - const interactor = await createWebInteractor({ env: process.env, cwd: process.cwd() }); + const interactor = await createWebInteractor(createWebHostStub().toolbox); assert.equal(interactor.doubleTap, undefined); }); }); test('web interactor reports unsupported operations explicitly', async () => { - const interactor = await createWebInteractor({ env: process.env, cwd: process.cwd() }); + const interactor = await createWebInteractor(createWebHostStub().toolbox); await assert.rejects( () => interactor.back(), diff --git a/packages/platform-web/src/interactor.ts b/packages/platform-web/src/interactor.ts index 6e5bbe017e..706556c1ae 100644 --- a/packages/platform-web/src/interactor.ts +++ b/packages/platform-web/src/interactor.ts @@ -3,19 +3,18 @@ import type { Interactor } from '@agent-device/contracts/interactor-types'; import { createUnsupportedInteractor } from '@agent-device/contracts/unsupported-interactor'; import { AppError } from '@agent-device/kernel/errors'; import { stripAtPrefix } from '@agent-device/selectors/interaction-positionals'; -import { withDiagnosticTimer } from '@agent-device/host-kit/diagnostics'; -import { resolveWebProviderForHost } from './resolve-provider.ts'; +import { resolveWebProviderForToolbox } from './resolve-provider.ts'; import type { WebProvider } from '@agent-device/contracts/web-provider'; -import type { ManagedBrowserHost } from './agent-browser-tool.ts'; +import type { WebToolbox } from './toolbox.ts'; export async function createWebInteractor( - host: ManagedBrowserHost, + toolbox: WebToolbox, provider?: WebProvider, stateDir?: string, ): Promise { - // A request's scoped provider wins; an out-of-request local path binds the composing root's - // host into its own default provider instead of reading an ambient one (#3794). - const resolvedProvider = await resolveWebProviderForHost(host, provider, stateDir); + // A request's scoped provider wins; an out-of-request local path binds the plugin's own host + // into its default provider instead of reading an ambient one (#3794). + const resolvedProvider = await resolveWebProviderForToolbox(toolbox, provider, stateDir); const clickRef = resolvedProvider.clickRef; const hover = resolvedProvider.hover; const hoverRef = resolvedProvider.hoverRef; @@ -58,7 +57,7 @@ export async function createWebInteractor( screenshot: (outPath, options) => resolvedProvider.screenshot(outPath, options), setViewport: (width, height) => resolvedProvider.setViewport(width, height), snapshot: async (options) => { - const result = await (host.withDiagnosticTimer ?? withDiagnosticTimer)( + const result = await toolbox.withDiagnosticTimer( 'snapshot_capture', async () => await resolvedProvider.snapshot(options), { backend: 'web' }, diff --git a/packages/platform-web/src/resolve-provider.ts b/packages/platform-web/src/resolve-provider.ts index 111e786256..6de1e7cdd6 100644 --- a/packages/platform-web/src/resolve-provider.ts +++ b/packages/platform-web/src/resolve-provider.ts @@ -1,5 +1,5 @@ -import type { HostEnvironment } from '@agent-device/kernel/source-value'; import type { WebProvider } from '@agent-device/contracts/web-provider'; +import type { WebToolbox } from './toolbox.ts'; /** * The provider a web request composed for itself, or `undefined` outside one. A reader that must @@ -14,12 +14,13 @@ export async function resolveRequestScopedWebProvider(): Promise { @@ -27,5 +28,5 @@ export async function resolveWebProviderForHost( const scoped = await resolveRequestScopedWebProvider(); if (scoped) return scoped; const { createAgentBrowserWebProvider } = await import('./agent-browser-provider.ts'); - return await createAgentBrowserWebProvider({ host, stateDir }); + return await createAgentBrowserWebProvider({ toolbox, stateDir }); } diff --git a/packages/platform-web/src/toolbox.fixtures.ts b/packages/platform-web/src/toolbox.fixtures.ts new file mode 100644 index 0000000000..1693fc14b2 --- /dev/null +++ b/packages/platform-web/src/toolbox.fixtures.ts @@ -0,0 +1,99 @@ +import type { PlatformHost } from 'agent-device/plugins'; +import { runCmd, type ExecOptions } from '@agent-device/host-kit/command'; +import type { DiagnosticEventInput } from '@agent-device/host-kit/diagnostics'; +import type { HostProcessInfo } from '@agent-device/host-kit/process'; +import { createWebToolbox, type WebToolbox } from './toolbox.ts'; + +/** One command the plugin asked its host to run, plus what the host was told about it. */ +export type WebHostStubCommand = Readonly<{ + executable: string; + args: readonly string[]; + env: Readonly> | undefined; + timeoutMs: number | undefined; + allowFailure: boolean | undefined; + signal: AbortSignal | undefined; + stdin: string | undefined; +}>; + +export type WebHostStub = Readonly<{ + toolbox: WebToolbox; + host: PlatformHost; + /** Every command the plugin asked the host to run, in order. */ + commands: WebHostStubCommand[]; + /** Every diagnostic the plugin emitted through its host, in order. */ + diagnostics: DiagnosticEventInput[]; + /** Answers the next process-table reads in order; the last one is reused once they run out. */ + answerProcessTable(reads: readonly HostProcessInfo[][]): void; +}>; + +/** + * Binds the plugin's toolbox to an in-memory host for colocated unit tests. Nothing spawns of its + * own: each command is recorded with the argv and environment the plugin built, and then handed to + * `runCmd`, so a test that answers through `withCommandExecutorOverride` keeps working while still + * proving the command travelled through the plugin's host rather than around it. + */ +export function createWebHostStub( + input: Readonly<{ + env?: Readonly>; + cwd?: string; + stateDir?: string; + /** Answers one process-table read; the plugin reads the table to derive its fleet record. */ + processes?: HostProcessInfo[]; + ownedProcessRecords?: PlatformHost['ownedProcessRecords']; + openWebSessionNames?: () => readonly string[]; + }> = {}, +): WebHostStub { + const commands: WebHostStubCommand[] = []; + const diagnostics: DiagnosticEventInput[] = []; + const processTable: HostProcessInfo[][] = []; + let processReads = 0; + const host = Object.freeze({ + env: input.env ?? process.env, + cwd: input.cwd ?? process.cwd(), + stateDir: input.stateDir ?? '/host-state', + runCommand: async ( + executable: string, + args: string[], + options: ExecOptions & { stdin?: string }, + ) => { + commands.push({ + executable, + args, + env: options.env, + timeoutMs: options.timeoutMs, + allowFailure: options.allowFailure, + signal: options.signal, + stdin: typeof options.stdin === 'string' ? options.stdin : undefined, + }); + return await runCmd(executable, args, options); + }, + isFileExecutable: async () => false, + isExecutableOnPath: async () => false, + listHostProcesses: async () => { + const answer = processTable[processReads] ?? input.processes ?? processTable.at(-1) ?? []; + processReads += 1; + return answer; + }, + emitDiagnostic: (event: DiagnosticEventInput) => { + diagnostics.push(event); + }, + withDiagnosticTimer: async (_phase: string, operation: () => Promise): Promise => + await operation(), + ...(input.ownedProcessRecords === undefined + ? {} + : { ownedProcessRecords: input.ownedProcessRecords }), + ...(input.openWebSessionNames === undefined + ? {} + : { openWebSessionNames: input.openWebSessionNames }), + }) as unknown as PlatformHost; + return Object.freeze({ + toolbox: createWebToolbox(host), + host, + commands, + diagnostics, + answerProcessTable: (reads: readonly HostProcessInfo[][]) => { + processTable.push(...reads.map((read) => [...read])); + processReads = 0; + }, + }); +} diff --git a/packages/platform-web/src/toolbox.ts b/packages/platform-web/src/toolbox.ts new file mode 100644 index 0000000000..07f2f35492 --- /dev/null +++ b/packages/platform-web/src/toolbox.ts @@ -0,0 +1,30 @@ +import type { PlatformHost } from 'agent-device/plugins'; +import { createWebCommandRunner, type WebCommandRunner } from './command-host.ts'; + +/** + * Everything the web family needs from the machine it runs on, built once from the `PlatformHost` the + * core hands `setup()`, and shared by the backend tool, the provider, the fleet record, the + * interactor and doctor. + * + * It exists so the plugin never reaches for process globals of its own. The package is bundled with + * its own copy of the host kit, and the daemon's command scope never enters that copy, so a spawn + * made through it would run with the daemon's environment and outside the request's exec trace. + * Going through the host keeps spawning, executable probes, process reads and diagnostics where the + * core put them. + */ +export type WebToolbox = Readonly<{ + /** The host this plugin was set up with: environment, state dir, diagnostics, process resources. */ + host: PlatformHost; + /** Host commands, run with the environment the caller builds for the managed backend. */ + commands: WebCommandRunner; + /** Timings and traces for this family's operations, in the request's diagnostic store. */ + withDiagnosticTimer: PlatformHost['withDiagnosticTimer']; +}>; + +export function createWebToolbox(host: PlatformHost): WebToolbox { + return Object.freeze({ + host, + commands: createWebCommandRunner(host), + withDiagnosticTimer: host.withDiagnosticTimer, + }); +} diff --git a/packages/platform-web/test/package-smoke.mjs b/packages/platform-web/test/package-smoke.mjs index 0ee58ac60d..38240f913a 100644 --- a/packages/platform-web/test/package-smoke.mjs +++ b/packages/platform-web/test/package-smoke.mjs @@ -8,6 +8,55 @@ import { installFakeManagedAgentBrowser } from '@agent-device/test-kit'; const repo = path.resolve(import.meta.dirname, '../../..'); +/** + * A stand-in for the managed web backend, written over the fixture install's own entry script. It + * answers the envelopes this family's provider reads, appends every invocation to `logFile`, and + * writes a PNG when asked for a screenshot, so a whole interaction runs without a real browser. The + * log path is baked into the entry rather than passed by environment: the plugin builds each spawn + * environment from the host it was set up with, so nothing this fixture needs travels through it. + */ +function managedBackendEntrySource(logFile) { + return [ + "const fs = require('node:fs');", + 'const args = process.argv.slice(2);', + 'const joined = args.join(" ");', + 'fs.appendFileSync(' + + JSON.stringify(logFile) + + String.raw`, "ARGS: " + joined + "\nHOME: " + process.env.HOME + "\nSOCKET: " + process.env.AGENT_BROWSER_SOCKET_DIR + "\n");`, + // The provider puts the output path right after the verb, ahead of the envelope flags. + 'if (args[0] === "screenshot") {', + ' const out = args[1];', + ' fs.mkdirSync(require("node:path").dirname(out), { recursive: true });', + ' fs.writeFileSync(out, Buffer.from([0x89, 0x50, 0x4e, 0x47]));', + '}', + String.raw`process.stdout.write(JSON.stringify({ success: true, data: {} }) + "\n");`, + ].join('\n'); +} + +/** + * The records one `--debug` request wrote, read back from the request records the daemon keeps under + * its session dirs. Matched by the CLI command they belong to, so an empty answer means the request + * traced nothing rather than that a file was missed. + */ +function requestRecordsOf(storeRoot, phase, command) { + const sessionsDir = path.join(storeRoot, 'sessions'); + if (!fs.existsSync(sessionsDir)) return []; + const requestFiles = fs + .readdirSync(sessionsDir) + .flatMap((session) => { + const requestsDir = path.join(sessionsDir, session, 'requests'); + return fs.existsSync(requestsDir) + ? fs.readdirSync(requestsDir).map((request) => path.join(requestsDir, request)) + : []; + }) + .filter((file) => file.endsWith('.ndjson')); + return requestFiles + .flatMap((file) => fs.readFileSync(file, 'utf8').split('\n')) + .filter((line) => line.includes(`"phase":"${phase}"`)) + .map((line) => JSON.parse(line)) + .filter((record) => record.command === command); +} + test('packed core discovers web only after the managed platform is installed', () => { const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-web-pack-')); const env = { @@ -33,6 +82,16 @@ test('packed core discovers web only after the managed platform is installed', ( throw error; } }; + // A `--debug` request writes its exec and timing records where the caller can read them back, + // which is the route proof below: a plugin that spawned or timed through its own copy of the host + // kit leaves the request without any. + const debugCli = (...args) => + execFileSync( + process.execPath, + ['node_modules/agent-device/bin/agent-device.mjs', ...args, '--json', '--debug'], + { cwd: scratch, env, encoding: 'utf8', timeout: 120_000 }, + ); + const storeRoot = env.AGENT_DEVICE_STATE_DIR; try { const [packed] = JSON.parse( exec('npm', ['pack', '--ignore-scripts', '--json', '--pack-destination', scratch], repo), @@ -77,8 +136,105 @@ test('packed core discovers web only after the managed platform is installed', ( ); const plugins = runCli(0, 'daemon', 'status').data.plugins; assert.ok(plugins.some((plugin) => plugin.platform === 'web' && plugin.state === 'active')); - installFakeManagedAgentBrowser(env.AGENT_DEVICE_STATE_DIR); + const install = installFakeManagedAgentBrowser(storeRoot); assert.equal(runCli(0, 'web', 'doctor').data.status.installed, true); + + // Now the backend answers: the packed plugin must run a whole interaction on the managed entry, + // with the managed environment it builds, on commands and timings the request can account for. + const backendCalls = path.join(scratch, 'backend-calls.log'); + fs.writeFileSync(install.entryScript, managedBackendEntrySource(backendCalls), 'utf8'); + runCli(0, 'daemon', 'stop'); + + // One named session for the whole interaction: the backend is told which session each call + // belongs to, so the recorded argv names it too. + const session = 'web-pack'; + debugCli('open', 'https://example.test', '--platform', 'web', '--session', session); + debugCli('press', '100', '200', '--platform', 'web', '--session', session); + const shot = path.join(scratch, 'screen.png'); + debugCli('screenshot', shot, '--platform', 'web', '--session', session); + debugCli('snapshot', '--platform', 'web', '--session', session); + debugCli('close', '--platform', 'web', '--session', session); + + const recorded = fs.readFileSync(backendCalls, 'utf8').split('\n').filter(Boolean); + const invoked = recorded.filter((line) => line.startsWith('ARGS: ')); + const homes = recorded.filter((line) => line.startsWith('HOME: ')); + const sockets = recorded.filter((line) => line.startsWith('SOCKET: ')); + assert.equal(homes.length, invoked.length, 'each call names the home it ran with'); + // Each call carries the JSON envelope flag and the backend key of the caller's session, so a + // call can only be attributed to this interaction's own browser session. + const sent = (argv) => + invoked.some((line) => line.startsWith(`ARGS: ${argv} --json --session `)); + assert.ok( + sent('open https://example.test'), + `open never reached the backend: ${invoked.join(' | ')}`, + ); + assert.ok( + ['mouse move 100 200', 'mouse down', 'mouse up'].every((argv) => sent(argv)), + `the press never sent its pointer sequence: ${invoked.join(' | ')}`, + ); + assert.ok( + sent(`screenshot ${shot}`), + `the screenshot never asked for a frame: ${invoked.join(' | ')}`, + ); + assert.ok(sent('close'), `close never reached the backend: ${invoked.join(' | ')}`); + assert.ok(fs.existsSync(shot), 'the screenshot file the backend wrote is missing'); + // The managed environment the plugin builds — its own home and socket dir — reached the child. + assert.ok( + homes.every((line) => line === `HOME: ${install.runtimeHomeDir}`), + `the backend ran with homes the plugin did not build: ${homes.join(' | ')}`, + ); + assert.ok( + sockets.every((line) => line === `SOCKET: ${install.socketDir}`), + `the backend ran with socket dirs the plugin did not build: ${sockets.join(' | ')}`, + ); + + // The route proof. Each spawn is recorded in the exec trace of the request that asked for it, + // and the snapshot's timing lands in that request's diagnostic store. Both live in the core's + // copies of those stores, which a bundled host-kit copy never enters: spawned or timed through + // it, these requests would carry no exec record and no capture timing at all. + // + // The fleet-record read is the one call no backend reply can show. `open` starts a fleet, so the + // provider derives its owned-process record from a process-table read, which the host answers. + // Read through a bundled host-kit copy instead, the read still succeeds — and the request that + // owed it traces nothing, which is what the `ps` assertion below refuses to accept. + const openRecords = requestRecordsOf(storeRoot, 'exec_command', 'open'); + assert.ok( + openRecords.some((record) => record.data?.event === 'spawn' && record.data.command === 'ps'), + `the open request traced no process-table read out of ${openRecords.length} exec records: ${JSON.stringify( + openRecords.map((record) => record.data), + )}`, + ); + const nodeBasenames = new Set(['node', 'node.exe']); + for (const [command, expected] of [ + ['open', 'open https://example.test'], + ['press', 'mouse down'], + ['screenshot', 'a screenshot call'], + ['close', 'close'], + ]) { + const records = requestRecordsOf(storeRoot, 'exec_command', command); + const spawns = records.filter((record) => record.data?.event === 'spawn'); + const exits = records.filter((record) => record.data?.event === 'exit'); + assert.ok( + spawns.some((record) => nodeBasenames.has(record.data.command)), + `the ${command} request traced no managed-backend spawn (${expected}) out of ${records.length} exec records`, + ); + assert.ok( + exits.every( + (record) => + spawns.some((spawn) => spawn.data.execId === record.data.execId) && + record.data.exitCode === 0, + ), + `the ${command} request traced a backend call that did not exit cleanly: ${JSON.stringify(exits)}`, + ); + } + // The interactor's snapshot timer reports through the host too, so one capture timing is + // attributed to the request that asked for the capture. + assert.ok( + requestRecordsOf(storeRoot, 'snapshot_capture', 'snapshot').some( + (record) => record.data?.backend === 'web' && record.durationMs > 0, + ), + 'the snapshot request carried no web capture timing', + ); } finally { try { if (fs.existsSync(path.join(scratch, 'node_modules/agent-device'))) diff --git a/packages/plugins/src/platform.test.ts b/packages/plugins/src/platform.test.ts index ce9375b53d..b7e5a1cd11 100644 --- a/packages/plugins/src/platform.test.ts +++ b/packages/plugins/src/platform.test.ts @@ -49,6 +49,8 @@ async function startStore(env: HostEnvironment['env']) { throw new Error('setup must not start a process'); }, isFileExecutable: async () => false, + isExecutableOnPath: async () => false, + listHostProcesses: async () => [], emitDiagnostic: () => {}, withDiagnosticTimer: async (_phase, run) => await run(), }, diff --git a/packages/plugins/src/platform.ts b/packages/plugins/src/platform.ts index 01a0abb16a..c18d3c5063 100644 --- a/packages/plugins/src/platform.ts +++ b/packages/plugins/src/platform.ts @@ -16,7 +16,7 @@ import type { LinuxToolProvider } from '@agent-device/contracts/linux-tool-provi import type { VegaToolProvider } from '@agent-device/contracts/vega-tool-provider'; import type { WebProvider } from '@agent-device/contracts/web-provider'; import type { DiagnosticEventInput, withDiagnosticTimer } from '@agent-device/host-kit/diagnostics'; -import type { OwnedProcessRecordStore } from '@agent-device/host-kit/process'; +import type { HostProcessInfo, OwnedProcessRecordStore } from '@agent-device/host-kit/process'; import type { HostEnvironment } from '@agent-device/kernel/source-value'; /** @@ -91,6 +91,18 @@ export type PlatformHost = HostEnvironment & * the probe uses the same host authority as the spawn it authorizes. */ isFileExecutable(path: string): Promise; + /** + * Whether the host resolves `executable` on its `PATH`, answered against the host environment + * the plugin was set up with. A plugin that prefers a tool from `PATH` asks this rather than + * searching `PATH` itself, so the lookup and the spawn it authorizes read one environment. + */ + isExecutableOnPath(executable: string): Promise; + /** + * The host's process table. A plugin that accounts for a fleet it started asks the host instead + * of running a process tool itself, so the read uses the host's own executable resolution and + * stays apart from whatever command override one request of this daemon carries. + */ + listHostProcesses(options: { timeoutMs: number }): Promise; /** * Starts one streamed command as a managed process: the host publishes an ownership marker at * `markerPath` while the process lives, clears it when the process ends, and stops the process on diff --git a/scripts/layering/platform-package-policy.test.ts b/scripts/layering/platform-package-policy.test.ts index 226a44c671..51a0a63674 100644 --- a/scripts/layering/platform-package-policy.test.ts +++ b/scripts/layering/platform-package-policy.test.ts @@ -924,9 +924,10 @@ test('managed platform code enters core only through the registry', () => { // A managed plugin ships its own copy of host-kit, so the daemon's command scope and request // diagnostic store never enter it: a runtime import of either runs outside the request the plugin was -// asked to serve. The plugin binds to the host its `setup` receives instead. +// asked to serve. The plugin binds to the host its `setup` receives instead. No managed package +// carries an entry: every one of them is on the host. for (const family of ['web', 'vega', 'harmonyos'] as const) { - test(`a managed platform package reaches the host-kit command or diagnostics scope only in its listed migration files (${family})`, () => { + test(`a managed platform package may not reach the host-kit command or diagnostics scope (${family})`, () => { const file = `packages/platform-${family}/src/new-surface.ts`; for (const specifier of [ '@agent-device/host-kit/command', diff --git a/scripts/layering/platform-package-policy.ts b/scripts/layering/platform-package-policy.ts index 1b07364a8b..3c7e7421ce 100644 --- a/scripts/layering/platform-package-policy.ts +++ b/scripts/layering/platform-package-policy.ts @@ -126,31 +126,10 @@ const MANAGED_HOST_KIT_SCOPES = [ '@agent-device/host-kit/diagnostics', ]; -// The web and Vega files that still import one of those scopes, as of the HarmonyOS plugin (#4317). -// Each entry is that package's own migration slice, not an exception to this rule: no file joins the -// list, and an entry leaves it when its file binds to the host its plugin was set up with. HarmonyOS -// and Linux carry no entry: each builds one command runner from `host.runCommand` in `setup`, so its -// packed bundle carries no separate host-kit command or diagnostics scope. -const MANAGED_HOST_KIT_IMPORT_DEBT: Readonly> = { - '@agent-device/web': [ - 'packages/platform-web/src/agent-browser-install.ts', - 'packages/platform-web/src/agent-browser-lifecycle.ts', - 'packages/platform-web/src/agent-browser-process-record.ts', - 'packages/platform-web/src/agent-browser-provider.ts', - 'packages/platform-web/src/agent-browser-tool.ts', - 'packages/platform-web/src/interactor.ts', - ], - '@agent-device/vega': [ - 'packages/platform-vega/src/app-lifecycle.ts', - 'packages/platform-vega/src/input-actions.ts', - 'packages/platform-vega/src/inventory.ts', - 'packages/platform-vega/src/tool-provider.ts', - 'packages/platform-vega/src/vega-executable.ts', - ], - '@agent-device/harmonyos': [], - '@agent-device/linux': [], -}; - +// Every managed platform package is on the host: the web and Vega plugins joined HarmonyOS, and no +// file of any of them imports these scopes at runtime. A new managed family is therefore bound from +// its first commit, and a file that wants a host-kit command or diagnostic helper is a bug to fix at +// that file, not an entry to add here. function isManagedHostKitScope(spec: string): boolean { return MANAGED_HOST_KIT_SCOPES.some((scope) => spec === scope || spec.startsWith(`${scope}/`)); } @@ -161,7 +140,6 @@ function managedHostKitScopeViolations( managedName: string, ): LayeringViolation[] { if (site.typeOnly || !isManagedHostKitScope(site.spec)) return []; - if ((MANAGED_HOST_KIT_IMPORT_DEBT[managedName] ?? []).includes(file)) return []; return [ violation( file, diff --git a/src/platform-runtime-host.test.ts b/src/platform-runtime-host.test.ts index 4a4bf8be07..d698a9367b 100644 --- a/src/platform-runtime-host.test.ts +++ b/src/platform-runtime-host.test.ts @@ -77,8 +77,8 @@ test('vega inventory resolves the CLI from the host home, not the process home', // The rule: every Vega executable lookup in one runtime resolves from that runtime host's // PATH and home. This host's HOME differs from the process HOME and names a default-install // vega the process home does not have, so `devices --platform vega` must list the device - // instead of TOOL_MISSING (#3794). Reverting `homeDirectory` to `os.homedir()` in - // createDeviceInventoryHost makes the lookup miss and this test go red. + // instead of TOOL_MISSING (#3794). The plugin reads them through the PlatformHost its `setup` + // received, so the fixture hands the same environment to `setup` and nothing to `loadInventory`. const scratch = mkdtempForTestSync('vega-inventory-host-home-'); const hostHome = path.join(scratch, 'host-home'); mkdirSync(path.join(hostHome, 'vega', 'bin'), { recursive: true }); @@ -86,10 +86,6 @@ test('vega inventory resolves the CLI from the host home, not the process home', writeFileSync(vega, '#!/bin/sh\necho "VirtualDevice : running"\n'); chmodSync(vega, 0o755); - const inventoryHost = createDeviceInventoryHost({ - env: { PATH: path.join(scratch, 'empty-path'), HOME: hostHome }, - cwd: scratch, - }); const scope: PlatformRequestScope = Object.freeze({ signal: new AbortController().signal, diagnostics: Object.freeze({ emit: () => {} }), @@ -102,7 +98,7 @@ test('vega inventory resolves the CLI from the host home, not the process home', env: { PATH: path.join(scratch, 'empty-path'), HOME: hostHome }, cwd: scratch, }); - const inventory = await selection.active!.inventoryModule.loadInventory(inventoryHost); + const inventory = await selection.active!.inventoryModule.loadInventory(); const devices = await inventory.discover({ platform: 'vega', target: 'tv' }, scope); expect(devices).toEqual([ diff --git a/src/platform-runtime/plugin-host.ts b/src/platform-runtime/plugin-host.ts index a0a1387216..7272bf7fa4 100644 --- a/src/platform-runtime/plugin-host.ts +++ b/src/platform-runtime/plugin-host.ts @@ -44,6 +44,19 @@ export function createPlatformPluginHost( const { isExecutablePath } = await import('@agent-device/host-kit/command'); return await isExecutablePath(path); }, + isExecutableOnPath: async (executable) => { + const { whichCmd } = await import('@agent-device/host-kit/command'); + return await whichCmd(executable, host.env); + }, + listHostProcesses: async (options) => { + const [{ listHostProcesses }, { withoutCommandExecutorOverride }] = await Promise.all([ + import('@agent-device/host-kit/process'), + import('@agent-device/host-kit/command'), + ]); + // Reading the process table is a host read: a command override one request carries (an adb + // executor, say) must not answer for it. + return await withoutCommandExecutorOverride(async () => await listHostProcesses(options)); + }, startBackgroundCommand: async (request, signal) => { processes ??= await loadManagedAppLogProcesses(sessionsDir, host.env); return await processes.start( diff --git a/test/repo-guards/exec-wrap-guard.test.ts b/test/repo-guards/exec-wrap-guard.test.ts index 364c4d0468..471324b526 100644 --- a/test/repo-guards/exec-wrap-guard.test.ts +++ b/test/repo-guards/exec-wrap-guard.test.ts @@ -12,8 +12,11 @@ import { test } from 'vitest'; // whose details carry `processExitError: true`. Before PR #1072 ~49 call sites // spread the trio by hand and silently missed the flag, so users saw // " exited with code N" with no cause. The fix is centralized in -// `execFailureDetails` / `requireExecSuccess` (@agent-device/host-kit/command); this guard -// keeps new call sites from drifting back to inline spreads. +// `execFailureDetails` / `requireExecSuccess` (@agent-device/host-kit/command) and, for a +// caller that holds only a command answer and no host (a platform plugin running its commands +// through its `PlatformHost`), `commandFailureDetails` / `requireCommandSuccess` +// (@agent-device/kernel/errors); this guard keeps new call sites from drifting back to inline +// spreads. // // A site that intentionally rebuilds the trio WITHOUT the flag (reachable at // exit 0, timeout errors where the message beats the excerpt, nested tool @@ -83,7 +86,13 @@ function isInlineTrioViolation(source: string, callStart: number): boolean { // expressions, which are runner/daemon pass-throughs, not exec wraps). if (!/^\(\s*'COMMAND_FAILED'/.test(window)) return false; if (!TRIO_KEYS.every((key) => key.test(window))) return false; - if (window.includes('execFailureDetails') || window.includes('requireExecSuccess')) return false; + if ( + window.includes('execFailureDetails') || + window.includes('requireExecSuccess') || + window.includes('commandFailureDetails') || + window.includes('requireCommandSuccess') + ) + return false; return !hasAllowMarker(source, callStart); } From 73cfbed817c081d13a042a624709d84d4e1e895c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 21 Nov 2026 10:26:44 +0100 Subject: [PATCH 02/11] refactor(web): read the browser fleet's processes through its host MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- .../web-managed-platform-2026-11-21.md | 2 +- packages/host-kit/src/process.ts | 5 +- packages/platform-harmonyos/src/index.test.ts | 17 +- .../src/command-host.fixtures.ts | 11 +- packages/platform-vega/src/index.test.ts | 11 +- packages/platform-vega/src/toolbox.ts | 7 +- ...rowser-process-record-host-routing.test.ts | 192 ++++++++++++++++++ .../agent-browser-process-record.test.ts | 75 +++++-- ...-browser-provider-record-retention.test.ts | 10 +- .../src/agent-browser-lifecycle.test.ts | 56 +++-- .../src/agent-browser-lifecycle.ts | 17 +- .../src/agent-browser-process-record.ts | 21 +- .../src/agent-browser-provider.ts | 27 ++- .../platform-web/src/agent-browser-tool.ts | 19 +- .../src/index-startup-cleanup.test.ts | 14 +- packages/platform-web/src/index.ts | 1 + packages/platform-web/src/toolbox.fixtures.ts | 128 +++++++++++- packages/platform-web/test/package-smoke.mjs | 17 +- packages/plugins/src/platform.test.ts | 10 +- packages/plugins/src/platform.ts | 67 +++++- .../layering/platform-package-policy.test.ts | 39 ++++ scripts/layering/platform-package-policy.ts | 106 +++++++--- src/platform-runtime/plugin-host.test.ts | 109 +++++++++- src/platform-runtime/plugin-host.ts | 50 ++++- 24 files changed, 875 insertions(+), 136 deletions(-) create mode 100644 packages/platform-web/src/__tests__/agent-browser-process-record-host-routing.test.ts diff --git a/docs/evidence/web-managed-platform-2026-11-21.md b/docs/evidence/web-managed-platform-2026-11-21.md index eea3d2ac09..a500206b53 100644 --- a/docs/evidence/web-managed-platform-2026-11-21.md +++ b/docs/evidence/web-managed-platform-2026-11-21.md @@ -106,7 +106,7 @@ SOCKET: /var/folders/…/T/adw/76dbf75458e3 (every call) The exec trace of those requests, as `--debug` wrote them. Two commands matter here for different reasons. `open` shows the backend spawn plus the process-table read that derives the owned-process record — that read is the call no backend reply can show, and it goes through the host's -`listHostProcesses` port. `press` shows the three-spawn pointer sequence attributed to one request: +`processes.list` port. `press` shows the three-spawn pointer sequence attributed to one request: ``` {"phase":"exec_command","requestId":"f178ac3051b20133","command":"open","data":{"execId":"cd318f35-…","command":"node","event":"spawn","pid":13307,"timeoutMs":30000}} diff --git a/packages/host-kit/src/process.ts b/packages/host-kit/src/process.ts index 9a8eedfae2..69654eb7d0 100644 --- a/packages/host-kit/src/process.ts +++ b/packages/host-kit/src/process.ts @@ -42,7 +42,10 @@ export { writeHostStderr, } from './internal/host-process.ts'; export { signalProcessGroupBestEffort } from './internal/exec.ts'; -export { reapOwnedProcessRecordsAtStartup } from './internal/owned-process-reaper.ts'; +export { + reapOwnedProcessRecordsAtStartup, + type OwnedProcessReapSummary, +} from './internal/owned-process-reaper.ts'; export { createOwnedProcessRecordStore, type OwnedProcessRecordStore, diff --git a/packages/platform-harmonyos/src/index.test.ts b/packages/platform-harmonyos/src/index.test.ts index 1da09f10d4..71066e1ab7 100644 --- a/packages/platform-harmonyos/src/index.test.ts +++ b/packages/platform-harmonyos/src/index.test.ts @@ -38,11 +38,20 @@ function createPluginHost( commands.push({ executable, args, env: options.env }); return { stdout: '', stderr: '', exitCode: 0 }; }, - // The real host probe: a test that names a toolchain root proves the plugin resolves HDC from - // a file on disk, not from a verdict this fixture hands it. + // The host probe the real one is: a test that names a toolchain root proves the plugin resolves + // HDC from a file on disk, not from a verdict this fixture hands it. isFileExecutable: isExecutablePath, - isExecutableOnPath: async (executable) => (await whichCmd(executable, env)) !== undefined, - listHostProcesses: async () => [], + isExecutableOnPath: async (executable) => await whichCmd(executable, env), + // Neither this family nor its devices are host processes: everything goes through HDC. + processes: { + list: async () => [], + readIdentities: async () => new Map(), + readIdentityObservations: async () => new Map(), + readExecutablePaths: async () => new Map(), + reapOwnedRecords: async () => { + throw new Error('the HarmonyOS family never reaps host processes'); + }, + } satisfies PlatformHost['processes'], emitDiagnostic, withDiagnosticTimer, }; diff --git a/packages/platform-vega/src/command-host.fixtures.ts b/packages/platform-vega/src/command-host.fixtures.ts index eadfdd387e..cf81228e2b 100644 --- a/packages/platform-vega/src/command-host.fixtures.ts +++ b/packages/platform-vega/src/command-host.fixtures.ts @@ -71,7 +71,16 @@ export function createVegaHostStub( pathProbes += 1; return onPath.has(executable); }, - listHostProcesses: async () => [], + // Neither this family nor its devices are host processes: everything goes through the Vega CLI. + processes: { + list: async () => [], + readIdentities: async () => new Map(), + readIdentityObservations: async () => new Map(), + readExecutablePaths: async () => new Map(), + reapOwnedRecords: async () => { + throw new Error('the Vega family never reaps host processes'); + }, + } satisfies PlatformHost['processes'], runCommand: async ( executable: string, args: string[], diff --git a/packages/platform-vega/src/index.test.ts b/packages/platform-vega/src/index.test.ts index 752571e261..d1cc551426 100644 --- a/packages/platform-vega/src/index.test.ts +++ b/packages/platform-vega/src/index.test.ts @@ -48,7 +48,16 @@ function createPluginHost( // on disk, not from a verdict this fixture hands it. isFileExecutable: isExecutablePath, isExecutableOnPath: async (executable) => onPath.has(executable), - listHostProcesses: async () => [], + // Neither this family nor its devices are host processes: everything goes through the Vega CLI. + processes: { + list: async () => [], + readIdentities: async () => new Map(), + readIdentityObservations: async () => new Map(), + readExecutablePaths: async () => new Map(), + reapOwnedRecords: async () => { + throw new Error('the Vega family never reaps host processes'); + }, + } satisfies PlatformHost['processes'], emitDiagnostic, withDiagnosticTimer, }; diff --git a/packages/platform-vega/src/toolbox.ts b/packages/platform-vega/src/toolbox.ts index 7b499e7f92..e073ec46be 100644 --- a/packages/platform-vega/src/toolbox.ts +++ b/packages/platform-vega/src/toolbox.ts @@ -6,22 +6,17 @@ import { createVegaCommandRunner, type VegaCommandRunner } from './command-host. * the core hands `setup()`, and shared by inventory, the runtime, the interactor and doctor. * * It exists so the plugin never reaches for process globals of its own. The package is bundled with - * its own copy of the host kit, and the daemon's command scope never enters that copy, so a spawn + * its own copy of the host kit, and the request's command scope never enters that copy, so a spawn * made through it would run with the daemon's environment and outside the request's exec trace. * Going through the host keeps CLI resolution, environment and diagnostics where the core put them. */ export type VegaToolbox = Readonly<{ - host: PlatformHost; /** The Vega CLI route: one resolver over the host, one spawn per call. */ commands: VegaCommandRunner; - /** Timings and traces for this family's operations, in the request's diagnostic store. */ - withDiagnosticTimer: PlatformHost['withDiagnosticTimer']; }>; export function createVegaToolbox(host: PlatformHost): VegaToolbox { return Object.freeze({ - host, commands: createVegaCommandRunner(host), - withDiagnosticTimer: host.withDiagnosticTimer, }); } diff --git a/packages/platform-web/src/__tests__/agent-browser-process-record-host-routing.test.ts b/packages/platform-web/src/__tests__/agent-browser-process-record-host-routing.test.ts new file mode 100644 index 0000000000..59ecb0d763 --- /dev/null +++ b/packages/platform-web/src/__tests__/agent-browser-process-record-host-routing.test.ts @@ -0,0 +1,192 @@ +import { installFakeManagedAgentBrowser } from '@agent-device/test-kit'; +// The two routes this family has for learning about processes it does not own: the fleet-record scan +// and the startup orphan reap. A managed plugin ships its own copy of the host kit, and the request's +// command-host and diagnostic scopes never enter that copy, so every one of these reads and every stop +// has to be asked of the host the plugin was set up with (`PlatformHost.processes`) rather than run +// through the bundled copy (R13). `spawn` is refused for the whole module graph below, so a read that +// reached the bundle's exec layer fails here instead of quietly running with the daemon's environment. +import assert from 'node:assert/strict'; +import fs from 'node:fs'; +import path from 'node:path'; +import { beforeEach, test, vi } from 'vitest'; +import type { OwnedProcessRecord } from '@agent-device/contracts/platform-runtime-host'; +import { + createOwnedProcessRecordStore, + type HostProcessInfo, + type OwnedProcessRecordStore, +} from '@agent-device/host-kit/process'; +import { + MANAGED_WEB_BROWSER_PROCESS_PURPOSE, + recordManagedAgentBrowserProcesses, +} from '../agent-browser-process-record.ts'; +import { + cleanupManagedAgentBrowserOrphans, + type AgentBrowserCleanupOptions, +} from '../agent-browser-lifecycle.ts'; +import { getManagedAgentBrowserStatus } from '../agent-browser-tool.ts'; +import { createWebHostStub, type WebHostStub } from '../toolbox.fixtures.ts'; +import { mkdtempForTestSync } from './test-utils.ts'; + +const { spawnMock } = vi.hoisted(() => ({ spawnMock: vi.fn() })); + +vi.mock('node:child_process', async (importOriginal) => ({ + ...(await importOriginal()), + spawn: () => { + spawnMock(); + throw new Error('a managed plugin may not spawn a process tool of its own'); + }, + spawnSync: () => { + spawnMock(); + throw new Error('a managed plugin may not run a process tool of its own'); + }, +})); + +const mockSpawn = vi.mocked(spawnMock); + +/** A managed install, a real record store, and the status both are read from. */ +function createFleetState() { + const stateDir = mkdtempForTestSync('agent-device-web-host-routing-'); + installFakeManagedAgentBrowser(stateDir); + const store = createOwnedProcessRecordStore({ + stateDir, + sessionsDir: path.join(stateDir, 'sessions'), + resolveSessionDir: (sessionId) => path.join(stateDir, 'sessions', sessionId), + }); + const status = getManagedAgentBrowserStatus({ + stateDir, + host: { env: process.env, cwd: process.cwd() }, + }); + return { stateDir, store, status }; +} + +/** + * The host the plugin reads through, answering the identity read with the command its own table + * already showed for each pid — what a same-pid re-read of an unchanged process answers with. + */ +function createProcessAnsweringHost( + stateDir: string, + store: OwnedProcessRecordStore, + processes: readonly HostProcessInfo[], + executablePaths: ReadonlyMap, +): WebHostStub { + const commands = new Map(processes.map(({ pid, command }) => [pid, command])); + return createWebHostStub({ + stateDir, + processes: [...processes], + ownedProcessRecords: store, + readProcesses: () => ({ + identities: (pids) => + new Map( + pids.flatMap((pid) => { + const command = commands.get(pid); + return command === undefined + ? [] + : [[pid, { startTime: `start-${pid}`, command, zombie: false }]]; + }), + ), + executablePaths: (pids) => + new Map( + pids.flatMap((pid) => { + const executable = executablePaths.get(pid); + return executable === undefined ? [] : [[pid, executable]]; + }), + ), + }), + }); +} + +function nativeBinary(installDir: string): string { + const binary = path.join( + installDir, + 'package', + 'node_modules', + 'agent-browser', + 'bin', + 'agent-browser-darwin-arm64', + ); + fs.mkdirSync(path.dirname(binary), { recursive: true }); + fs.writeFileSync(binary, 'fixture'); + return fs.realpathSync.native(binary); +} + +function recordedFleetPids(store: OwnedProcessRecordStore): number[] { + return store + .read() + .filter((entry) => entry.scope.kind === 'daemon' && entry.status === 'decoded') + .flatMap((entry) => entry.records) + .filter((record) => record.purpose === MANAGED_WEB_BROWSER_PROCESS_PURPOSE) + .map((record) => record.pid); +} + +beforeEach(() => { + mockSpawn.mockReset(); +}); + +test('the fleet scan asks the host for every identity and executable path it acts on', async () => { + const fleet = createFleetState(); + const daemon = nativeBinary(fleet.status.installDir); + const stub = createProcessAnsweringHost( + fleet.stateDir, + fleet.store, + [{ pid: 101, ppid: 1, command: `${daemon} daemon` }], + new Map([[101, daemon]]), + ); + try { + const summary = await recordManagedAgentBrowserProcesses( + fleet.status, + fleet.store, + stub.toolbox, + ); + + // The scan still owns the process it was shown, so the host's answers were the ones it acted on. + assert.deepEqual(summary.pids, [101]); + assert.deepEqual(recordedFleetPids(fleet.store), [101]); + assert.deepEqual( + stub.processReads.map((read) => read.kind), + ['table', 'identities', 'table', 'executable-paths', 'identities'], + ); + assert.deepEqual(stub.processReads[1]!.pids, [101]); + assert.deepEqual(stub.processReads[3]!.pids, [101]); + assert.equal(mockSpawn.mock.calls.length, 0); + } finally { + fs.rmSync(fleet.stateDir, { recursive: true, force: true }); + } +}); + +test('the startup reap stops the recorded fleet through the host that owns the record', async () => { + const fleet = createFleetState(); + const stub = createProcessAnsweringHost(fleet.stateDir, fleet.store, [], new Map()); + const record: OwnedProcessRecord = { + pid: 101, + startTime: 'start-101', + command: 'agent-browser daemon', + purpose: MANAGED_WEB_BROWSER_PROCESS_PURPOSE, + }; + fleet.store.replace({ kind: 'daemon' }, [record]); + const options: AgentBrowserCleanupOptions = { + env: process.env, + emitDiagnostic: () => {}, + processes: stub.host.processes, + ownedProcessRecords: fleet.store, + }; + try { + const cleanup = await cleanupManagedAgentBrowserOrphans( + fleet.status, + 'daemon-startup', + options, + ); + + assert.deepEqual(cleanup.pids, []); + const reaps = stub.processReads.filter((read) => read.kind === 'reap'); + assert.equal(reaps.length, 1); + // The reap is handed the host's own store and this family's purpose, so the record it rewrites is + // the one the daemon reads, and it stops nothing the plugin did not record as its own fleet. + assert.equal(reaps[0]!.kind === 'reap' && reaps[0]!.store, fleet.store); + assert.deepEqual(reaps[0]!.kind === 'reap' && reaps[0]!.options?.purposes, [ + MANAGED_WEB_BROWSER_PROCESS_PURPOSE, + ]); + assert.equal(mockSpawn.mock.calls.length, 0); + } finally { + fs.rmSync(fleet.stateDir, { recursive: true, force: true }); + } +}); diff --git a/packages/platform-web/src/__tests__/agent-browser-process-record.test.ts b/packages/platform-web/src/__tests__/agent-browser-process-record.test.ts index 965553cfe2..43f1dde27c 100644 --- a/packages/platform-web/src/__tests__/agent-browser-process-record.test.ts +++ b/packages/platform-web/src/__tests__/agent-browser-process-record.test.ts @@ -1,6 +1,7 @@ import assert from 'node:assert/strict'; import { beforeEach, test, vi } from 'vitest'; import type { OwnedProcessRecord } from '@agent-device/contracts/platform-runtime-host'; +import type { PlatformHost } from 'agent-device/plugins'; import type { HostProcessIdentityObservation, OwnedProcessRecordStore, @@ -18,15 +19,34 @@ const { observationsMock, isProcessAliveMock } = vi.hoisted(() => ({ ), })); +// Only the signal probe is faked: it is the one host read this module still answers from its own +// process globals. Everything the host must answer goes through the `processes` port below. vi.mock('@agent-device/host-kit/process', async (importOriginal) => ({ ...(await importOriginal()), - readHostProcessIdentityObservationsAsync: observationsMock, isProcessAlive: isProcessAliveMock, })); const mockObservations = vi.mocked(observationsMock); const mockIsProcessAlive = vi.mocked(isProcessAliveMock); +/** + * The process facet the record probe is asked to use. Only `readIdentityObservations` is reached: the + * probe is one batched same-pid snapshot, never a table scan. + */ +function createProcessPort(): PlatformHost['processes'] { + return { + list: async () => [], + readIdentities: async () => new Map(), + readIdentityObservations: (pids) => mockObservations(pids), + readExecutablePaths: async () => new Map(), + reapOwnedRecords: async () => { + throw new Error('the record probe never reaps'); + }, + }; +} + +const processes = createProcessPort(); + function record(pid: number, startTime = `start-${pid}`): OwnedProcessRecord { return { pid, @@ -99,6 +119,7 @@ test('a record whose every managed process is alive under its recorded identity assert.equal( await managedWebBrowserProcessRecordIsLive( storeReturning([daemonEntry([record(11), record(12)])]), + processes, ), true, ); @@ -116,6 +137,7 @@ test('a process the host cannot name makes the record not-live', async () => { assert.equal( await managedWebBrowserProcessRecordIsLive( storeReturning([daemonEntry([record(11), record(12)])]), + processes, ), false, ); @@ -128,7 +150,10 @@ test('a pid answering under a different start time is pid reuse, not the recorde ]), ); assert.equal( - await managedWebBrowserProcessRecordIsLive(storeReturning([daemonEntry([record(11)])])), + await managedWebBrowserProcessRecordIsLive( + storeReturning([daemonEntry([record(11)])]), + processes, + ), false, ); }); @@ -140,7 +165,10 @@ test('a recorded zombie is not a live fleet even with its start time intact', as ]), ); assert.equal( - await managedWebBrowserProcessRecordIsLive(storeReturning([daemonEntry([record(11)])])), + await managedWebBrowserProcessRecordIsLive( + storeReturning([daemonEntry([record(11)])]), + processes, + ), false, ); }); @@ -148,15 +176,18 @@ test('a recorded zombie is not a live fleet even with its start time intact', as test('a probe that answers nothing is unknown evidence, which reads as not-live', async () => { hostAnswers(new Map()); assert.equal( - await managedWebBrowserProcessRecordIsLive(storeReturning([daemonEntry([record(11)])])), + await managedWebBrowserProcessRecordIsLive( + storeReturning([daemonEntry([record(11)])]), + processes, + ), false, ); }); test('an empty record is not a live fleet and needs no probe', async () => { - assert.equal(await managedWebBrowserProcessRecordIsLive(storeReturning([])), false); + assert.equal(await managedWebBrowserProcessRecordIsLive(storeReturning([]), processes), false); assert.equal( - await managedWebBrowserProcessRecordIsLive(storeReturning([daemonEntry([])])), + await managedWebBrowserProcessRecordIsLive(storeReturning([daemonEntry([])]), processes), false, ); assert.equal(mockObservations.mock.calls.length, 0); @@ -164,7 +195,10 @@ test('an empty record is not a live fleet and needs no probe', async () => { test('a session-scoped record is not the daemon-scoped managed fleet', async () => { assert.equal( - await managedWebBrowserProcessRecordIsLive(storeReturning([sessionEntry([record(11)])])), + await managedWebBrowserProcessRecordIsLive( + storeReturning([sessionEntry([record(11)])]), + processes, + ), false, ); assert.equal(mockObservations.mock.calls.length, 0); @@ -176,13 +210,16 @@ test('a record of another purpose is not the managed fleet', async () => { { pid: 11, startTime: 'start-11', command: 'command-11', purpose: 'simctl-screen-recording' }, ]), ]); - assert.equal(await managedWebBrowserProcessRecordIsLive(store), false); + assert.equal(await managedWebBrowserProcessRecordIsLive(store, processes), false); assert.equal(mockObservations.mock.calls.length, 0); }); test('an undecodable record is not a live fleet and needs no probe', async () => { assert.equal( - await managedWebBrowserProcessRecordIsLive(storeReturning([undecodableDaemonEntry()])), + await managedWebBrowserProcessRecordIsLive( + storeReturning([undecodableDaemonEntry()]), + processes, + ), false, ); assert.equal(mockObservations.mock.calls.length, 0); @@ -192,7 +229,7 @@ test('a store that cannot answer reads as not-live, which sends the caller back const store = storeReturning(() => { throw new Error('record file unreadable'); }); - assert.equal(await managedWebBrowserProcessRecordIsLive(store), false); + assert.equal(await managedWebBrowserProcessRecordIsLive(store, processes), false); assert.equal(mockObservations.mock.calls.length, 0); }); @@ -206,6 +243,7 @@ test('a record is dead only when every recorded process was observed not alive', assert.equal( await managedWebBrowserProcessRecordIsDead( storeReturning([daemonEntry([record(11), record(12), record(13)])]), + processes, ), true, ); @@ -221,6 +259,7 @@ test('a recorded process still answering alive keeps the record from being dead' assert.equal( await managedWebBrowserProcessRecordIsDead( storeReturning([daemonEntry([record(11), record(12)])]), + processes, ), false, ); @@ -230,15 +269,21 @@ test('an unanswered probe is unknown evidence, not a dead record', async () => { hostAnswers(new Map()); mockIsProcessAlive.mockReturnValue(true); assert.equal( - await managedWebBrowserProcessRecordIsDead(storeReturning([daemonEntry([record(11)])])), + await managedWebBrowserProcessRecordIsDead( + storeReturning([daemonEntry([record(11)])]), + processes, + ), false, ); }); test('an empty or undecodable record is not dead and needs no probe', async () => { - assert.equal(await managedWebBrowserProcessRecordIsDead(storeReturning([])), false); + assert.equal(await managedWebBrowserProcessRecordIsDead(storeReturning([]), processes), false); assert.equal( - await managedWebBrowserProcessRecordIsDead(storeReturning([undecodableDaemonEntry()])), + await managedWebBrowserProcessRecordIsDead( + storeReturning([undecodableDaemonEntry()]), + processes, + ), false, ); assert.equal(mockObservations.mock.calls.length, 0); @@ -253,7 +298,7 @@ test.each([ mockIsProcessAlive.mockReturnValue(true); mockObservations.mockResolvedValue(new Map([[11, { state: 'Ss', startTime: observed }]])); const store = storeReturning([daemonEntry([record(11, recorded)])]); - assert.equal(await managedWebBrowserProcessRecordIsLive(store), false); - assert.equal(await managedWebBrowserProcessRecordIsDead(store), false); + assert.equal(await managedWebBrowserProcessRecordIsLive(store, processes), false); + assert.equal(await managedWebBrowserProcessRecordIsDead(store, processes), false); }, ); diff --git a/packages/platform-web/src/__tests__/agent-browser-provider-record-retention.test.ts b/packages/platform-web/src/__tests__/agent-browser-provider-record-retention.test.ts index df0922129b..b6e8e0621c 100644 --- a/packages/platform-web/src/__tests__/agent-browser-provider-record-retention.test.ts +++ b/packages/platform-web/src/__tests__/agent-browser-provider-record-retention.test.ts @@ -21,7 +21,7 @@ import { MANAGED_WEB_BROWSER_PROCESS_PURPOSE } from '../agent-browser-process-re import { createAgentBrowserWebProvider } from '../agent-browser-provider.ts'; import type { WebProvider } from '@agent-device/contracts/web-provider'; import { agentBrowserJsonResult, mkdtempForTestSync } from './test-utils.ts'; -import { createWebHostStub } from '../toolbox.fixtures.ts'; +import { createWebHostStub, realHostProcessReads } from '../toolbox.fixtures.ts'; bindTestCommandHost(); @@ -148,7 +148,13 @@ async function withFleetRecordStore( store.replace({ kind: 'daemon' }, [seed]); await runScenario({ provider: createAgentBrowserWebProvider({ - toolbox: createWebHostStub({ stateDir, ownedProcessRecords: store }).toolbox, + toolbox: createWebHostStub({ + stateDir, + ownedProcessRecords: store, + // The host answers the identity probe for the machine it really runs on: the case owns a real + // process and asks whether the gate reads it as alive. + readProcesses: () => realHostProcessReads(), + }).toolbox, session: 'web-session', stateDir, openWebSessionNames: () => ['web-session'], diff --git a/packages/platform-web/src/agent-browser-lifecycle.test.ts b/packages/platform-web/src/agent-browser-lifecycle.test.ts index c69f8cf20a..724d57e6bb 100644 --- a/packages/platform-web/src/agent-browser-lifecycle.test.ts +++ b/packages/platform-web/src/agent-browser-lifecycle.test.ts @@ -44,19 +44,14 @@ const identitiesMock = vi.hoisted(() => ), ); +// The subject reads processes only through its host, so the suite controls those reads in the host +// port below rather than by faking the host-kit module. The one module fake left is the platform the +// fleet matchers branch on. vi.mock('@agent-device/host-kit/process', async (importOriginal) => { const actual = await importOriginal(); return { ...actual, hostPlatform: () => probe.platform ?? actual.hostPlatform(), - listHostProcesses: async (options: Parameters[0]) => - await actual.listHostProcesses({ ...options, runCommand: runCmdMock }), - readHostProcessIdentityObservationsAsync: async (pids: Iterable) => - probe.unanswered - ? new Map() - : await actual.readHostProcessIdentityObservationsAsync(pids), - readProcessIdentities: identitiesMock, - readProcessExecutablePaths: executablePathsMock, }; }); @@ -78,17 +73,43 @@ import { getManagedAgentBrowserStatus } from './agent-browser-tool.ts'; import { createOwnedProcessRecordStore, listHostProcesses, + readHostProcessIdentityObservationsAsync, reapOwnedProcessRecordsAtStartup, } from '@agent-device/host-kit/process'; +import type { PlatformHost } from 'agent-device/plugins'; import { createWebToolbox, type WebToolbox } from './toolbox.ts'; bindTestCommandHost(); const testHost = createLiveTestHostEnvironment(); /** - * The plugin's toolbox over an in-memory host: commands and process-table reads are recorded, and - * the reads go through the module-level `listHostProcesses` this suite fakes, so a scenario's - * `observeProcesses(...)` fixture still answers them. + * The process port of a host that reads the machine the way the core's host does: the process table + * through a `ps` the recorded command mock answers, and the identity and executable-path facts from + * the answers this suite's `observeProcesses(...)` fixture set up. + */ +function createHostProcessPort(): PlatformHost['processes'] { + return { + list: async (options) => await listHostProcesses({ ...options, runCommand: mockRunCmd }), + readIdentities: async (pids) => await identitiesMock([...pids]), + readIdentityObservations: async (pids) => + probe.unanswered + ? new Map() + : await readHostProcessIdentityObservationsAsync(pids), + // The host answers this read with the environment it was set up with, the way the real host port + // does; the suite's answer is the same fixture either way. + readExecutablePaths: async (pids) => await executablePathsMock([...pids], testHost), + reapOwnedRecords: async (store, options) => + await reapOwnedProcessRecordsAtStartup(store, options), + }; +} + +/** The process port every cleanup and record call of this suite is handed. */ +const hostProcesses = createHostProcessPort(); + +/** + * The plugin's toolbox over an in-memory host: commands and every process read are asked of this + * host, so the suite proves the fleet scan and the reap go through it rather than through the host-kit + * copy the plugin ships with. */ function createLifecycleToolbox(stateDir: string): WebToolbox { const host = { @@ -101,7 +122,7 @@ function createLifecycleToolbox(stateDir: string): WebToolbox { ) => await runCmdMock(executable, args, options), isFileExecutable: async () => false, isExecutableOnPath: async () => false, - listHostProcesses: async (options: { timeoutMs: number }) => await listHostProcesses(options), + processes: createHostProcessPort(), emitDiagnostic: () => {}, withDiagnosticTimer: async (_phase: string, operation: () => Promise): Promise => await operation(), @@ -232,6 +253,7 @@ test('cleanup skips reaping when the daemon reports open web sessions', async () const result = await cleanupManagedAgentBrowserOrphans(status, 'daemon-startup', { env: process.env, emitDiagnostic: () => {}, + processes: hostProcesses, openWebSessionNames: ['default-web'], }); @@ -278,6 +300,7 @@ test('cleanup skips reaping while the browser fleet holds an opening session', a const result = await cleanupManagedAgentBrowserOrphans(status, 'provider-startup', { env: process.env, emitDiagnostic: () => {}, + processes: hostProcesses, ownedProcessRecords, }); @@ -303,6 +326,7 @@ test('cleanup reaps when the only fleet session is the one whose open runs it', const result = await cleanupManagedAgentBrowserOrphans(status, 'provider-startup', { env: process.env, emitDiagnostic: () => {}, + processes: hostProcesses, ownedProcessRecords, startingSession: 'fleet-web', }); @@ -330,6 +354,7 @@ test('cleanup evicts a launched session whose recorded browser exited, then reap const result = await cleanupManagedAgentBrowserOrphans(status, 'provider-startup', { env: process.env, emitDiagnostic: () => {}, + processes: hostProcesses, ownedProcessRecords, }); @@ -358,6 +383,7 @@ test('cleanup keeps a launched session when the process probe does not answer', const result = await cleanupManagedAgentBrowserOrphans(status, 'provider-startup', { env: process.env, emitDiagnostic: () => {}, + processes: hostProcesses, ownedProcessRecords, }); @@ -386,6 +412,7 @@ test('cleanup skips reaping when managed browser socket activity is recent', asy const result = await cleanupManagedAgentBrowserOrphans(status, 'daemon-startup', { env: process.env, emitDiagnostic: () => {}, + processes: hostProcesses, }); assert.equal(result.skipped?.reason, 'recent-browser-activity'); @@ -416,6 +443,7 @@ test('cleanup does not treat the shared socket directory mtime as browser activi const result = await cleanupManagedAgentBrowserOrphans(status, 'daemon-startup', { env: process.env, emitDiagnostic: () => {}, + processes: hostProcesses, }); assert.equal(result.skipped, undefined); @@ -473,6 +501,7 @@ test('cleanup reads recorded browser identities without reconstructing a process const result = await cleanupManagedAgentBrowserOrphans(status, 'provider-startup', { env: process.env, emitDiagnostic: () => {}, + processes: hostProcesses, ownedProcessRecords, }); @@ -948,10 +977,11 @@ test('cleanup retains legacy records without signaling or treating them as verif const result = await cleanupManagedAgentBrowserOrphans(status, 'daemon-startup', { env: process.env, emitDiagnostic: () => {}, + processes: hostProcesses, ownedProcessRecords: store, }); expect(result.pids).toEqual([]); - expect(await managedWebBrowserProcessRecordIsLive(store)).toBe(false); + expect(await managedWebBrowserProcessRecordIsLive(store, hostProcesses)).toBe(false); expect(store.read()[0]?.records).toEqual([legacy]); expect(kill).not.toHaveBeenCalled(); } finally { diff --git a/packages/platform-web/src/agent-browser-lifecycle.ts b/packages/platform-web/src/agent-browser-lifecycle.ts index e7d9823942..01949fbfa0 100644 --- a/packages/platform-web/src/agent-browser-lifecycle.ts +++ b/packages/platform-web/src/agent-browser-lifecycle.ts @@ -1,11 +1,9 @@ import path from 'node:path'; +import type { PlatformHost } from 'agent-device/plugins'; import type { EnvMap } from '@agent-device/kernel/source-value'; import { uniqueStrings } from '@agent-device/kernel/collections'; import { hostFileStatSync, readHostDirectorySync } from '@agent-device/host-kit/host-file'; -import { - type OwnedProcessRecordStore, - reapOwnedProcessRecordsAtStartup, -} from '@agent-device/host-kit/process'; +import type { OwnedProcessRecordStore } from '@agent-device/host-kit/process'; import type { DiagnosticEventInput } from '@agent-device/host-kit/diagnostics'; import { agentBrowserFleetOf } from './agent-browser-fleet.ts'; @@ -45,6 +43,8 @@ export type AgentBrowserCleanupOptions = { env: Readonly; /** Where the reap is reported: the host the plugin was set up with. */ emitDiagnostic(event: DiagnosticEventInput): void; + /** The host that reads and stops the recorded processes: the plugin was set up with it. */ + processes: PlatformHost['processes']; openWebSessionNames?: readonly string[]; ownedProcessRecords?: OwnedProcessRecordStore; /** The fleet session whose open runs this cleanup: it has spawned nothing yet, so it never blocks the reap. */ @@ -82,14 +82,19 @@ export async function cleanupManagedAgentBrowserOrphans( if (!store) return emptyCleanupResult(); const fleet = agentBrowserFleetOf(store); return await fleet.updateRecord(async () => { - if (fleet.sessions().length > 0 && (await managedWebBrowserProcessRecordIsDead(store))) { + if ( + fleet.sessions().length > 0 && + (await managedWebBrowserProcessRecordIsDead(store, options.processes)) + ) { fleet.evictLaunched(); } const fleetSessions = fleet.sessions().filter((name) => name !== options.startingSession); if (fleetSessions.length > 0) { return skippedCleanupResult('open-web-session', { openWebSessionNames: fleetSessions }); } - const reaped = await reapOwnedProcessRecordsAtStartup(store, { + // The host reaps: it owns the record store, and the identity reads and signals the stop makes + // have to answer for the request's environment and exec trace, not the plugin bundle's. + const reaped = await options.processes.reapOwnedRecords(store, { openWebSessionNames, purposes: [MANAGED_WEB_BROWSER_PROCESS_PURPOSE], termTimeoutMs: WEB_BROWSER_REAP_TERM_TIMEOUT_MS, diff --git a/packages/platform-web/src/agent-browser-process-record.ts b/packages/platform-web/src/agent-browser-process-record.ts index e2ef2b7209..c0ffe73063 100644 --- a/packages/platform-web/src/agent-browser-process-record.ts +++ b/packages/platform-web/src/agent-browser-process-record.ts @@ -1,6 +1,7 @@ import crypto from 'node:crypto'; import path from 'node:path'; import type { OwnedProcessRecord } from '@agent-device/contracts/platform-runtime-host'; +import type { PlatformHost } from 'agent-device/plugins'; import { uniqueStrings } from '@agent-device/kernel/collections'; import { hostFileStatSync, realHostPathSync } from '@agent-device/host-kit/host-file'; import { @@ -9,9 +10,6 @@ import { hostPlatform, isProcessAlive, processStartTimesDiffer, - readHostProcessIdentityObservationsAsync, - readProcessIdentities, - readProcessExecutablePaths, type HostProcessInfo, type OwnedProcessRecordStore, } from '@agent-device/host-kit/process'; @@ -142,10 +140,10 @@ export async function recordManagedAgentBrowserProcesses( ): Promise { const initial = await listRealHostProcesses(toolbox); const pids = initial.map(({ pid }) => pid); - const before = await readProcessIdentities(pids); + const before = await toolbox.host.processes.readIdentities(pids); const scanned = await listRealHostProcesses(toolbox); - const executablePaths = await readProcessExecutablePaths(pids, toolbox.host); - const after = await readProcessIdentities(pids); + const executablePaths = await toolbox.host.processes.readExecutablePaths(pids); + const after = await toolbox.host.processes.readIdentities(pids); const initialPids = new Set(pids); const processes = scanned.filter(({ pid, command }) => { const first = before.get(pid); @@ -202,8 +200,9 @@ export async function recordManagedAgentBrowserProcesses( */ export async function managedWebBrowserProcessRecordIsLive( store: OwnedProcessRecordStore, + processes: PlatformHost['processes'], ): Promise { - const liveness = await readRecordedProcessLiveness(store); + const liveness = await readRecordedProcessLiveness(store, processes); return liveness.length > 0 && liveness.every((state) => state === 'alive'); } @@ -215,8 +214,9 @@ export async function managedWebBrowserProcessRecordIsLive( */ export async function managedWebBrowserProcessRecordIsDead( store: OwnedProcessRecordStore, + processes: PlatformHost['processes'], ): Promise { - const liveness = await readRecordedProcessLiveness(store); + const liveness = await readRecordedProcessLiveness(store, processes); return liveness.length > 0 && liveness.every((state) => state === 'not-alive'); } @@ -224,10 +224,11 @@ type RecordedProcessLiveness = 'alive' | 'not-alive' | 'unobserved'; async function readRecordedProcessLiveness( store: OwnedProcessRecordStore, + processes: PlatformHost['processes'], ): Promise { const records = readDaemonManagedWebBrowserRecords(store); if (records.length === 0) return []; - const observations = await readHostProcessIdentityObservationsAsync( + const observations = await processes.readIdentityObservations( records.map((record) => record.pid), ); return records.map((record) => { @@ -263,7 +264,7 @@ function readDaemonManagedWebBrowserRecords(store: OwnedProcessRecordStore): Own async function listRealHostProcesses(toolbox: WebToolbox): Promise { // The host reports the table; the fleet matchers below work on their own copies. - return [...(await toolbox.host.listHostProcesses({ timeoutMs: HOST_PROCESS_LIST_TIMEOUT_MS }))]; + return [...(await toolbox.host.processes.list({ timeoutMs: HOST_PROCESS_LIST_TIMEOUT_MS }))]; } function summarizeMatches( diff --git a/packages/platform-web/src/agent-browser-provider.ts b/packages/platform-web/src/agent-browser-provider.ts index 701681f6cf..49ade54f82 100644 --- a/packages/platform-web/src/agent-browser-provider.ts +++ b/packages/platform-web/src/agent-browser-provider.ts @@ -735,31 +735,29 @@ const AGENT_BROWSER_FLEET_LIFECYCLE_COMMANDS: ReadonlySet = new Set([ ]); /** - * Whether the process-table scan that rewrites the owned-process record has to run for one - * agent-browser call. + * Whether the process-table scan that rewrites the owned-process record has to run for one call. * - * Any failure may be the first command that finds the fleet died or restarted between calls, so - * it refreshes; so do the {@link AGENT_BROWSER_FLEET_LIFECYCLE_COMMANDS} members, which launch, - * end, and extend the fleet. A plain successful call - * acts on a fleet the record already describes, and re-deriving that fleet means a process-tool - * snapshot of every host process, which is the cost this seam exists to avoid. - * {@link managedWebBrowserProcessRecordIsLive} answers for the recorded pids from one same-pid - * probe instead. It is fail-closed: an empty, undecodable, or unanswered probe falls back to the - * scan, so a live fleet this daemon adopted from a predecessor becomes owned through the record - * again, and a fleet that died or restarted outside a lifecycle boundary is caught by the next - * command that can no longer name every process the record still claims is alive. + * Any failure may be the first command that finds the fleet died or restarted, so it refreshes; so + * do the {@link AGENT_BROWSER_FLEET_LIFECYCLE_COMMANDS} members, which launch, end, and extend the + * fleet. A plain successful call acts on the fleet the record already describes, and re-deriving it + * costs a process-tool snapshot of every host process: the cost this seam avoids. + * {@link managedWebBrowserProcessRecordIsLive} answers for the recorded pids from one same-pid probe, + * asked of the host. It is fail-closed: an empty, undecodable, or unanswered probe falls back to the + * scan, so a fleet this daemon adopted from a predecessor is owned again, and one that died or + * restarted outside a lifecycle boundary is caught by the next command. */ async function shouldRefreshAgentBrowserProcessRecord( params: Pick< Parameters[0], - 'cliArgs' | 'commandCompleted' | 'semanticSuccess' + 'cliArgs' | 'commandCompleted' | 'semanticSuccess' | 'options' >, store: OwnedProcessRecordStore, ): Promise { if (!params.commandCompleted || !params.semanticSuccess) return true; const command = params.cliArgs[0]; if (command !== undefined && AGENT_BROWSER_FLEET_LIFECYCLE_COMMANDS.has(command)) return true; - return !(await managedWebBrowserProcessRecordIsLive(store)); + const { host } = params.options.toolbox; + return !(await managedWebBrowserProcessRecordIsLive(store, host.processes)); } function canClearAgentBrowserRecord( @@ -790,6 +788,7 @@ async function cleanupProviderStartupOrphans( await cleanupManagedAgentBrowserOrphansForProviderStartup(status, { env: host.env, emitDiagnostic: host.emitDiagnostic, + processes: host.processes, openWebSessionNames: options.openWebSessionNames(), ...(startingSession === undefined ? {} : { startingSession }), ...(options.ownedProcessRecords === undefined diff --git a/packages/platform-web/src/agent-browser-tool.ts b/packages/platform-web/src/agent-browser-tool.ts index 654cd609a4..b1d2d94b96 100644 --- a/packages/platform-web/src/agent-browser-tool.ts +++ b/packages/platform-web/src/agent-browser-tool.ts @@ -15,7 +15,6 @@ import { hostNodeVersion, hostPlatform, hostProcessId, - readProcessStartTime, } from '@agent-device/host-kit/process'; import { AppError, asAppError } from '@agent-device/kernel/errors'; import type { HostEnvironment } from '@agent-device/kernel/source-value'; @@ -78,12 +77,18 @@ export async function setupManagedAgentBrowser(options: { const processId = hostProcessId(); return await withProcessLock({ - acquire: () => + acquire: async () => acquireProcessLock({ lockDirPath: path.join(status.installDir, '..', '.agent-browser-install.lock'), owner: { pid: processId, - startTime: readProcessStartTime(processId), + // The host names this process's start time: the plugin's own copy of the process tool would + // read it outside the request's exec trace. A host that will not answer leaves `null`, which + // is the same unproven claim a failed local probe always left. + startTime: + (await options.toolbox.host.processes.readIdentityObservations([processId])).get( + processId, + )?.startTime ?? null, acquiredAtMs: Date.now(), }, timeoutMs: SETUP_TIMEOUT_MS, @@ -137,10 +142,6 @@ export async function doctorManagedAgentBrowser(options: { return { status, ...result }; } -/** - * Where the managed backend is on disk, and whether it is there. Reads only the host's environment - * and the filesystem, so it answers the same way whether or not anything is installed. - */ /** Reads a status for the host one of the toolbox-taking operations was set up with. */ function managedStatusOptions(options: { toolbox: WebToolbox; stateDir?: string }): { host: HostEnvironment; @@ -152,6 +153,10 @@ function managedStatusOptions(options: { toolbox: WebToolbox; stateDir?: string }; } +/** + * Where the managed backend is on disk, and whether it is there. Reads only the host's environment + * and the filesystem, so it answers the same way whether or not anything is installed. + */ export function getManagedAgentBrowserStatus(options: { /** Either the calling runtime's host or the plugin's own host; both answer the same way. */ host: HostEnvironment; diff --git a/packages/platform-web/src/index-startup-cleanup.test.ts b/packages/platform-web/src/index-startup-cleanup.test.ts index 1ff91a49cf..fbf84ecb98 100644 --- a/packages/platform-web/src/index-startup-cleanup.test.ts +++ b/packages/platform-web/src/index-startup-cleanup.test.ts @@ -17,6 +17,7 @@ vi.mock('./agent-browser-lifecycle.ts', async (importOriginal) => ({ })); import webPlatformPlugin from './index.ts'; +import type { PlatformHost } from 'agent-device/plugins'; import { emitDiagnostic, withDiagnosticTimer } from '@agent-device/host-kit/diagnostics'; import { runCmd, isExecutablePath, whichCmd } from '@agent-device/host-kit/command'; @@ -27,7 +28,17 @@ function cleanupWebBrowserOrphansForDaemonStartup(stateDir: string) { runCommand: runCmd, isFileExecutable: isExecutablePath, isExecutableOnPath: async (executable: string) => await whichCmd(executable, process.env), - listHostProcesses: async () => [], + // The reaper and the record probe are the only host process reads this family makes, and both are + // stood in for below, so the port itself has nothing to answer. + processes: { + list: async () => [], + readIdentities: async () => new Map(), + readIdentityObservations: async () => new Map(), + readExecutablePaths: async () => new Map(), + reapOwnedRecords: async () => { + throw new Error('this suite stands the reap in for'); + }, + } satisfies PlatformHost['processes'], emitDiagnostic, withDiagnosticTimer, }; @@ -52,6 +63,7 @@ test('daemon-startup web cleanup passes open web sessions to the reaper', async env: process.env, ownedProcessRecords: undefined, emitDiagnostic: expect.any(Function), + processes: expect.any(Object), openWebSessionNames: ['web-session'], }); } finally { diff --git a/packages/platform-web/src/index.ts b/packages/platform-web/src/index.ts index 31a6903b4d..03b193e5f3 100644 --- a/packages/platform-web/src/index.ts +++ b/packages/platform-web/src/index.ts @@ -107,6 +107,7 @@ function webPlatformPlugin() { await cleanupManagedAgentBrowserOrphans(status, 'daemon-startup', { env: bound.host.env, emitDiagnostic: bound.host.emitDiagnostic, + processes: bound.host.processes, openWebSessionNames: openSessions, ownedProcessRecords: bound.host.ownedProcessRecords, }); diff --git a/packages/platform-web/src/toolbox.fixtures.ts b/packages/platform-web/src/toolbox.fixtures.ts index 1693fc14b2..b4f4da80a0 100644 --- a/packages/platform-web/src/toolbox.fixtures.ts +++ b/packages/platform-web/src/toolbox.fixtures.ts @@ -1,7 +1,16 @@ import type { PlatformHost } from 'agent-device/plugins'; import { runCmd, type ExecOptions } from '@agent-device/host-kit/command'; import type { DiagnosticEventInput } from '@agent-device/host-kit/diagnostics'; -import type { HostProcessInfo } from '@agent-device/host-kit/process'; +import { + readHostProcessIdentityObservationsAsync, + readProcessExecutablePaths, + readProcessIdentities, + type HostProcessIdentityFacts, + type HostProcessIdentityObservation, + type HostProcessInfo, + type OwnedProcessRecordStore, + type OwnedProcessReapSummary, +} from '@agent-device/host-kit/process'; import { createWebToolbox, type WebToolbox } from './toolbox.ts'; /** One command the plugin asked its host to run, plus what the host was told about it. */ @@ -15,6 +24,44 @@ export type WebHostStubCommand = Readonly<{ stdin: string | undefined; }>; +/** One process read the plugin asked its host to make, with the pids it named. */ +export type WebHostStubProcessRead = Readonly< + | { kind: 'table'; pids: [] } + | { kind: 'identities'; pids: readonly number[] } + | { kind: 'observations'; pids: readonly number[] } + | { kind: 'executable-paths'; pids: readonly number[] } + | { + kind: 'reap'; + pids: []; + store: OwnedProcessRecordStore; + options: Parameters[1]; + } +>; + +/** Every process read the plugin asked its host to make, in order. */ +export type WebHostStubProcessReads = WebHostStubProcessRead[]; + +/** + * What a host stub answers a process read with; absent fields read as the host not answering. Each + * answer is awaited, so a fixture can hand back a real host-kit read instead of a table. + */ +export type WebHostStubProcesses = Readonly<{ + identities?: ( + pids: readonly number[], + ) => + | Promise> + | ReadonlyMap; + observations?: ( + pids: readonly number[], + ) => + | Promise> + | ReadonlyMap; + executablePaths?: ( + pids: readonly number[], + ) => Promise> | ReadonlyMap; + reap?: OwnedProcessReapSummary; +}>; + export type WebHostStub = Readonly<{ toolbox: WebToolbox; host: PlatformHost; @@ -22,6 +69,8 @@ export type WebHostStub = Readonly<{ commands: WebHostStubCommand[]; /** Every diagnostic the plugin emitted through its host, in order. */ diagnostics: DiagnosticEventInput[]; + /** Every process read the plugin asked the host to make, in order. */ + processReads: WebHostStubProcessReads; /** Answers the next process-table reads in order; the last one is reused once they run out. */ answerProcessTable(reads: readonly HostProcessInfo[][]): void; }>; @@ -30,7 +79,9 @@ export type WebHostStub = Readonly<{ * Binds the plugin's toolbox to an in-memory host for colocated unit tests. Nothing spawns of its * own: each command is recorded with the argv and environment the plugin built, and then handed to * `runCmd`, so a test that answers through `withCommandExecutorOverride` keeps working while still - * proving the command travelled through the plugin's host rather than around it. + * proving the command travelled through the plugin's host rather than around it. Every process read is + * recorded and answered the same way, so a test proves the fleet scan and the orphan reap asked the + * host instead of running a process tool through the host-kit copy the plugin ships with. */ export function createWebHostStub( input: Readonly<{ @@ -39,6 +90,8 @@ export function createWebHostStub( stateDir?: string; /** Answers one process-table read; the plugin reads the table to derive its fleet record. */ processes?: HostProcessInfo[]; + /** Answers the identity, observation, executable-path and reap calls; defaults to nothing. */ + readProcesses?: (reads: WebHostStubProcessReads) => WebHostStubProcesses; ownedProcessRecords?: PlatformHost['ownedProcessRecords']; openWebSessionNames?: () => readonly string[]; }> = {}, @@ -46,7 +99,38 @@ export function createWebHostStub( const commands: WebHostStubCommand[] = []; const diagnostics: DiagnosticEventInput[] = []; const processTable: HostProcessInfo[][] = []; - let processReads = 0; + const processReads: WebHostStubProcessReads = []; + const answered = input.readProcesses?.(processReads) ?? {}; + let nextProcessTableRead = 0; + // Typed as the real port, so a change to the facet is a type error here rather than a missing cast. + const processes: PlatformHost['processes'] = { + list: async () => { + processReads.push({ kind: 'table', pids: [] }); + const answer = + processTable[nextProcessTableRead] ?? input.processes ?? processTable.at(-1) ?? []; + nextProcessTableRead += 1; + return answer; + }, + readIdentities: async (pids) => { + const named = [...pids]; + processReads.push({ kind: 'identities', pids: named }); + return answered.identities?.(named) ?? new Map(); + }, + readIdentityObservations: async (pids) => { + const named = [...pids]; + processReads.push({ kind: 'observations', pids: named }); + return answered.observations?.(named) ?? new Map(); + }, + readExecutablePaths: async (pids) => { + const named = [...pids]; + processReads.push({ kind: 'executable-paths', pids: named }); + return answered.executablePaths?.(named) ?? new Map(); + }, + reapOwnedRecords: async (store, options) => { + processReads.push({ kind: 'reap', pids: [], store, options }); + return answered.reap ?? EMPTY_REAP_SUMMARY; + }, + }; const host = Object.freeze({ env: input.env ?? process.env, cwd: input.cwd ?? process.cwd(), @@ -69,11 +153,7 @@ export function createWebHostStub( }, isFileExecutable: async () => false, isExecutableOnPath: async () => false, - listHostProcesses: async () => { - const answer = processTable[processReads] ?? input.processes ?? processTable.at(-1) ?? []; - processReads += 1; - return answer; - }, + processes, emitDiagnostic: (event: DiagnosticEventInput) => { diagnostics.push(event); }, @@ -91,9 +171,39 @@ export function createWebHostStub( host, commands, diagnostics, + processReads, answerProcessTable: (reads: readonly HostProcessInfo[][]) => { processTable.push(...reads.map((read) => [...read])); - processReads = 0; + nextProcessTableRead = 0; }, }); } + +/** + * Answers the process reads with the real host-kit reads, for a test that wants the host to answer for + * the machine it actually runs on rather than from a fixture. `@agent-device/host-kit/process` is + * runtime-importable here: a `*.fixtures.*` file never ships in a plugin bundle. + */ +export function realHostProcessReads(): WebHostStubProcesses { + return { + identities: async (pids) => await readProcessIdentities(pids), + observations: async (pids) => await readHostProcessIdentityObservationsAsync(pids), + executablePaths: async (pids) => + await readProcessExecutablePaths(pids, { env: process.env, cwd: process.cwd() }), + }; +} + +/** A reap that inspected nothing: a stub test asserts the reap was asked, not what it stopped. */ +const EMPTY_REAP_SUMMARY: OwnedProcessReapSummary = { + inspected: 0, + inspectedPids: [], + terminated: 0, + terminatedPids: [], + missing: 0, + missingPids: [], + unconfirmed: 0, + unconfirmedPids: [], + survived: 0, + survivedPids: [], + skippedForOpenWebSession: false, +}; diff --git a/packages/platform-web/test/package-smoke.mjs b/packages/platform-web/test/package-smoke.mjs index 38240f913a..9a48e66d9a 100644 --- a/packages/platform-web/test/package-smoke.mjs +++ b/packages/platform-web/test/package-smoke.mjs @@ -193,10 +193,11 @@ test('packed core discovers web only after the managed platform is installed', ( // copies of those stores, which a bundled host-kit copy never enters: spawned or timed through // it, these requests would carry no exec record and no capture timing at all. // - // The fleet-record read is the one call no backend reply can show. `open` starts a fleet, so the - // provider derives its owned-process record from a process-table read, which the host answers. - // Read through a bundled host-kit copy instead, the read still succeeds — and the request that - // owed it traces nothing, which is what the `ps` assertion below refuses to accept. + // The fleet-record reads are the ones no backend reply can show. `open` starts a fleet, so the + // provider derives its owned-process record from the host's process table, its per-pid identity + // reads, and the executable path of each candidate — on macOS one `osascript`, on Windows one CIM + // query. Read through a bundled host-kit copy instead, each read still succeeds — and the request + // that owed it traces nothing, which is what the two assertions below refuse to accept. const openRecords = requestRecordsOf(storeRoot, 'exec_command', 'open'); assert.ok( openRecords.some((record) => record.data?.event === 'spawn' && record.data.command === 'ps'), @@ -204,6 +205,14 @@ test('packed core discovers web only after the managed platform is installed', ( openRecords.map((record) => record.data), )}`, ); + if (process.platform === 'darwin') { + assert.ok( + openRecords.some( + (record) => record.data?.event === 'spawn' && record.data.command === 'osascript', + ), + `the open request traced no executable-path read out of ${openRecords.length} exec records`, + ); + } const nodeBasenames = new Set(['node', 'node.exe']); for (const [command, expected] of [ ['open', 'open https://example.test'], diff --git a/packages/plugins/src/platform.test.ts b/packages/plugins/src/platform.test.ts index b7e5a1cd11..02504e3281 100644 --- a/packages/plugins/src/platform.test.ts +++ b/packages/plugins/src/platform.test.ts @@ -50,7 +50,15 @@ async function startStore(env: HostEnvironment['env']) { }, isFileExecutable: async () => false, isExecutableOnPath: async () => false, - listHostProcesses: async () => [], + processes: { + list: async () => [], + readIdentities: async () => new Map(), + readIdentityObservations: async () => new Map(), + readExecutablePaths: async () => new Map(), + reapOwnedRecords: async () => { + throw new Error('setup must not reap host processes'); + }, + }, emitDiagnostic: () => {}, withDiagnosticTimer: async (_phase, run) => await run(), }, diff --git a/packages/plugins/src/platform.ts b/packages/plugins/src/platform.ts index c18d3c5063..c794e31017 100644 --- a/packages/plugins/src/platform.ts +++ b/packages/plugins/src/platform.ts @@ -16,7 +16,13 @@ import type { LinuxToolProvider } from '@agent-device/contracts/linux-tool-provi import type { VegaToolProvider } from '@agent-device/contracts/vega-tool-provider'; import type { WebProvider } from '@agent-device/contracts/web-provider'; import type { DiagnosticEventInput, withDiagnosticTimer } from '@agent-device/host-kit/diagnostics'; -import type { HostProcessInfo, OwnedProcessRecordStore } from '@agent-device/host-kit/process'; +import type { + HostProcessIdentityFacts, + HostProcessIdentityObservation, + HostProcessInfo, + OwnedProcessReapSummary, + OwnedProcessRecordStore, +} from '@agent-device/host-kit/process'; import type { HostEnvironment } from '@agent-device/kernel/source-value'; /** @@ -98,11 +104,16 @@ export type PlatformHost = HostEnvironment & */ isExecutableOnPath(executable: string): Promise; /** - * The host's process table. A plugin that accounts for a fleet it started asks the host instead - * of running a process tool itself, so the read uses the host's own executable resolution and - * stays apart from whatever command override one request of this daemon carries. + * What the host answers about processes the plugin already has pids for. + * + * A plugin is bundled with its own copy of the host kit, and the request's command-host and + * diagnostic scopes never enter that copy, so a process tool run from there answers with the + * daemon process environment and traces into the plugin's own store instead of the request's. + * Every process read a plugin makes therefore goes through this facet. Each read keeps its + * fail-closed answer: a pid the host did not answer for is unknown evidence, never proof a + * process is gone. */ - listHostProcesses(options: { timeoutMs: number }): Promise; + processes: PlatformHostProcesses; /** * Starts one streamed command as a managed process: the host publishes an ownership marker at * `markerPath` while the process lives, clears it when the process ends, and stops the process on @@ -135,6 +146,52 @@ export type PlatformHost = HostEnvironment & withDiagnosticTimer: typeof withDiagnosticTimer; }>; +/** + * The process facet of {@link PlatformHost}: reads a plugin may make about pids it already knows, + * and the stop that acts on one. Named apart from the host so a plugin can pass just what a fleet + * scan needs. + */ +export type PlatformHostProcesses = Readonly<{ + /** The host's process table. A plugin accounts for a fleet it started from this one read. */ + list(options: { timeoutMs: number }): Promise; + /** + * What the host says about each pid named, as the facts a caller acts on before it signals: + * start time, command, and whether the pid is a zombie. A pid the host did not answer for maps to + * all-`null` facts. + */ + readIdentities( + pids: Iterable, + options?: { timeoutMs?: number }, + ): Promise>; + /** + * State and start time per pid from one process-tool snapshot. Unlike {@link readIdentities}, a + * pid the snapshot did not list is absent from the answer rather than answered with nothing. + */ + readIdentityObservations( + pids: Iterable, + ): Promise>; + /** + * The executable each pid is running, for a caller that must prove provenance rather than match a + * command line. A pid the host cannot name is absent, which is unknown evidence, not absence of + * the process. + */ + readExecutablePaths(pids: Iterable): Promise>; + /** + * Stops every process an owned-process record names, and forgets only the ones it watched leave. + * The store is the host's own, so the record the reaper rewrites is the one the daemon reads. The + * reaper's own identity reads and signals run under the host, exactly as a stop does. + */ + reapOwnedRecords( + store: OwnedProcessRecordStore, + options?: { + openWebSessionNames?: readonly string[]; + purposes?: readonly string[]; + termTimeoutMs?: number; + killTimeoutMs?: number; + }, + ): Promise; +}>; + export type PlatformSetup = Family extends Platform ? Readonly<{ family: Family; diff --git a/scripts/layering/platform-package-policy.test.ts b/scripts/layering/platform-package-policy.test.ts index 51a0a63674..192372d553 100644 --- a/scripts/layering/platform-package-policy.test.ts +++ b/scripts/layering/platform-package-policy.test.ts @@ -966,3 +966,42 @@ test('a type-only host-kit import stays legal in a managed platform package', () [], ); }); + +/** The host-kit findings one managed family's new file earns, as one string to match against. */ +function hostKitFindings(family: string, source: string): string { + const file = `packages/platform-${family}/src/new-surface.ts`; + const found = messages(new Map([...validSources(), [file, source]])); + return found.filter((message) => message.includes('host-kit')).join('\n'); +} + +// `host-kit/process` is policed export by export: an export that spawns a process tool escapes the +// request's exec trace from a bundled plugin, and one that reads only this process's globals cannot. +// `PlatformHost.processes` answers the first kind on the core's own copy. An edge naming no export +// could reach any of them, so a namespace import is refused rather than assumed harmless. Every case +// is asserted for every managed family: all three are on the host by the same rule. +const PROCESS_SCOPE_CASES = [ + [ + 'may not run a process tool through its own host-kit copy', + "import { listHostProcesses, readProcessIdentities } from '@agent-device/host-kit/process';\nvoid listHostProcesses; void readProcessIdentities;", + String.raw`@agent-device/%FAMILY% may not import the host-kit '@agent-device/host-kit/process' scope at runtime \(listHostProcesses, readProcessIdentities\): .*PlatformHost given to setup`, + ], + [ + 'keeps the process exports that read no process tool', + "import { expandProcessTree, hostPlatform, isProcessAlive } from '@agent-device/host-kit/process';\nvoid expandProcessTree; void hostPlatform; void isProcessAlive;", + '^$', + ], + [ + 'may not namespace-import the process scope', + "import * as hostProcess from '@agent-device/host-kit/process';\nvoid hostProcess;", + String.raw`@agent-device/%FAMILY% may not import the host-kit '@agent-device/host-kit/process' scope at runtime \(.*readProcessIdentities.*\)`, + ], +] as const; + +for (const family of MANAGED_FAMILIES) { + for (const [label, source, refusal] of PROCESS_SCOPE_CASES) { + test(`a managed platform package ${label} (${family})`, () => { + const named = new RegExp(refusal.replaceAll('%FAMILY%', family)); + assert.match(hostKitFindings(family, source), named); + }); + } +} diff --git a/scripts/layering/platform-package-policy.ts b/scripts/layering/platform-package-policy.ts index 3c7e7421ce..412524e503 100644 --- a/scripts/layering/platform-package-policy.ts +++ b/scripts/layering/platform-package-policy.ts @@ -115,40 +115,96 @@ const MANAGED_PLATFORMS: Readonly>> = { linux: '@agent-device/linux', }; -// The host-kit scopes a managed platform package must never reach at runtime. `command` reads the -// daemon's ambient command scope and `diagnostics` reads its request diagnostic store, and a managed -// plugin is bundled with its own copy of host-kit, so the daemon's scope never enters that copy: a -// spawn or trace made through it runs with the daemon process environment, outside the request's -// captured environment and exec trace. A managed plugin therefore binds to the `PlatformHost` its -// `setup` receives. Type-only edges are allowed — they cost the bundle nothing. -const MANAGED_HOST_KIT_SCOPES = [ - '@agent-device/host-kit/command', - '@agent-device/host-kit/diagnostics', +/** + * One host-kit surface a managed platform package may not reach at runtime, with the exports that + * make it dangerous. `execExports` absent means every runtime export of the scope is; a scope with + * them is policed export by export, because most of its exports read no process at all. + */ +type ManagedHostKitScope = Readonly<{ + specifier: string; + execExports?: readonly string[]; +}>; + +// The host-kit scopes a managed platform package must never reach at runtime, and the +// `host-kit/process` exports among them that spawn a process tool. Each of those answers through the +// exec layer — `ps`, PowerShell, `osascript`, `sysctl` — and a managed plugin is bundled with its own +// copy of host-kit, so the daemon's command-host and diagnostic scopes never enter that copy: a spawn +// or trace made through it runs with the daemon process environment, outside the request's captured +// environment and exec trace. A managed plugin therefore binds to the `PlatformHost` its `setup` +// receives, whose `processes` facet answers these same reads on the core's own copy. +// +// The rest of `host-kit/process` stays reachable: `hostPlatform`, `hostProcessId`, +// `hostNodeExecutablePath`, `isProcessAlive`, `expandProcessTree` and `processStartTimesDiffer` read +// this process's own globals or compute from what the caller already holds, so they cannot escape the +// request's scope. Type-only edges are allowed anywhere — they cost the bundle nothing. +const MANAGED_HOST_KIT_SCOPES: readonly ManagedHostKitScope[] = [ + { specifier: '@agent-device/host-kit/command' }, + { specifier: '@agent-device/host-kit/diagnostics' }, + { + specifier: '@agent-device/host-kit/process', + // Every export of the scope that runs a process tool, directly or through one of these. Listed in + // source order so a violation names what the file reached for in the order it reads. + execExports: [ + 'readCurrentOwnerIdentity', + 'readProcessStartTime', + 'readProcessCommand', + 'isProcessZombie', + 'readHostCpuArch', + 'readHostCpuArchSync', + 'listHostProcesses', + 'readProcessIdentities', + 'readProcessIdentityFacts', + 'readHostProcessIdentityObservations', + 'readHostProcessIdentityObservationsAsync', + 'readProcessExecutablePaths', + 'stopProcessAndConfirmExit', + 'reapOwnedProcessRecordsAtStartup', + 'classifyOwnerLiveness', + 'classifyOwnerLivenessAsync', + ], + }, ]; // Every managed platform package is on the host: the web and Vega plugins joined HarmonyOS, and no -// file of any of them imports these scopes at runtime. A new managed family is therefore bound from -// its first commit, and a file that wants a host-kit command or diagnostic helper is a bug to fix at -// that file, not an entry to add here. -function isManagedHostKitScope(spec: string): boolean { - return MANAGED_HOST_KIT_SCOPES.some((scope) => spec === scope || spec.startsWith(`${scope}/`)); +// file of any of them reaches one of these surfaces at runtime. A new managed family is therefore +// bound from its first commit, and a file that wants a host-kit command, diagnostic or process helper +// is a bug to fix at that file, not an entry to add here. +function managedHostKitScopeViolationMessage( + spec: string, + symbols: readonly string[], + managedName: string, +): string | undefined { + const scope = MANAGED_HOST_KIT_SCOPES.find( + (entry) => spec === entry.specifier || spec.startsWith(`${entry.specifier}/`), + ); + if (!scope) return undefined; + let reachedExports: string | undefined; + if (scope.execExports) { + // A runtime edge that names no export — a namespace or bare import — could reach any of them, + // so it is refused rather than assumed harmless. + const reached = + symbols.length === 0 + ? [...scope.execExports] + : scope.execExports.filter((name) => symbols.includes(name)); + if (reached.length === 0) return undefined; + reachedExports = reached.join(', '); + } + return ( + `${managedName} may not import the host-kit '${scope.specifier}' scope at runtime` + + (reachedExports === undefined ? '' : ` (${reachedExports})`) + + ': run the command, emit the diagnostic, or read processes through the PlatformHost given to ' + + 'setup, so the packed plugin stays inside the request environment and exec trace' + ); } function managedHostKitScopeViolations( file: string, - site: { spec: string; line: number; typeOnly: boolean }, + site: { spec: string; line: number; typeOnly: boolean; symbols: readonly string[] }, managedName: string, ): LayeringViolation[] { - if (site.typeOnly || !isManagedHostKitScope(site.spec)) return []; - return [ - violation( - file, - site.line, - `${managedName} may not import the host-kit '${site.spec}' scope at runtime: run the command ` + - 'or emit the diagnostic through the PlatformHost given to setup, so the packed plugin stays ' + - 'inside the request environment and exec trace', - ), - ]; + if (site.typeOnly) return []; + const message = managedHostKitScopeViolationMessage(site.spec, site.symbols, managedName); + return message === undefined ? [] : [violation(file, site.line, message)]; } const INTERACTOR_COMPOSITION_FILE = 'src/core/interactors/register-builtins.ts'; diff --git a/src/platform-runtime/plugin-host.test.ts b/src/platform-runtime/plugin-host.test.ts index f7d9c13f65..7d4e6bcc84 100644 --- a/src/platform-runtime/plugin-host.test.ts +++ b/src/platform-runtime/plugin-host.test.ts @@ -1,8 +1,15 @@ import { createLiveTestHostEnvironment, mkdtempForTestSync } from '@agent-device/test-kit'; import { expect, test } from 'vitest'; -import { createPlatformPluginHost } from './plugin-host.ts'; +import { spawn } from 'node:child_process'; import fs from 'node:fs'; import path from 'node:path'; +import { withDiagnosticsScope } from '@agent-device/host-kit/diagnostics'; +import { + createOwnedProcessRecordStore, + readProcessCommand, + readProcessStartTime, +} from '@agent-device/host-kit/process'; +import { createPlatformPluginHost } from './plugin-host.ts'; // The managed HarmonyOS plugin resolves HDC from the toolchain roots its host names, and it asks // this host whether a candidate is executable rather than reading the filesystem itself (R13). A @@ -87,3 +94,103 @@ test('the platform plugin host refuses a background command marker outside its s ), ).rejects.toThrow('sessions directory'); }); + +// A managed plugin is bundled with its own copy of the host kit and the request's scopes never enter +// that copy, so the plugin must ask this host for its process reads (R13). Answering here is what puts +// a read in the request's exec trace: the `ps` the host ran shows up under `--debug`, which is the +// evidence a read made through the bundle cannot produce. +test('the platform plugin host answers a process read inside the request exec trace', async () => { + const root = mkdtempForTestSync('plugin-host-process-trace-'); + const logPath = path.join(root, 'events.ndjson'); + const host = createPlatformPluginHost(createLiveTestHostEnvironment(), root); + + await withDiagnosticsScope({ command: 'open', debug: true, logPath }, async () => { + const table = await host.processes.list({ timeoutMs: 5_000 }); + // This process is on the table the host just read, so the read reached the real machine. + expect(table.map(({ pid }) => pid)).toContain(process.pid); + }); + + expect(tracedCommands(logPath)).toContain('ps'); +}); + +test('the platform plugin host answers identity facts for a pid it names', async () => { + const root = mkdtempForTestSync('plugin-host-identity-'); + const host = createPlatformPluginHost(createLiveTestHostEnvironment(), root); + + const facts = await host.processes.readIdentities([process.pid]); + + // The host is this process's own host, so it must name the one pid it cannot miss. + expect(facts.get(process.pid)?.startTime).toBeTruthy(); + expect(facts.get(process.pid)?.zombie).toBe(false); +}); + +// The reap a managed web plugin asks for is the one place the port signals a process, and it proves +// the recorded identity with a process-tool read before it does. Answered here, that stop is the +// core's own: it uses the store, environment and trace of the daemon that owns the record. +test('the platform plugin host stops a recorded process it is asked to reap', async () => { + const root = mkdtempForTestSync('plugin-host-reap-'); + const logPath = path.join(root, 'events.ndjson'); + const child = spawn(process.execPath, ['-e', 'setTimeout(() => {}, 120_000)'], { + stdio: 'ignore', + }); + const pid = child.pid; + if (pid === undefined) throw new Error('no pid for the process to reap'); + let watchedExit = false; + const exited = new Promise((resolve) => + child.once('exit', () => { + watchedExit = true; + resolve(); + }), + ); + const startTime = readProcessStartTime(pid); + const command = readProcessCommand(pid); + if (startTime === null || command === null) { + child.kill('SIGKILL'); + throw new Error(`the host named no identity for the live pid ${pid}`); + } + const store = createOwnedProcessRecordStore({ + stateDir: root, + sessionsDir: path.join(root, 'sessions'), + resolveSessionDir: (sessionId) => path.join(root, 'sessions', sessionId), + }); + store.replace({ kind: 'daemon' }, [ + { pid, startTime, command, purpose: 'verified-managed-web-browser' }, + ]); + const host = createPlatformPluginHost(createLiveTestHostEnvironment(), root); + + let reaped; + try { + reaped = await withDiagnosticsScope( + { command: 'open', debug: true, logPath }, + async () => + await host.processes.reapOwnedRecords(store, { + purposes: ['verified-managed-web-browser'], + termTimeoutMs: 2_000, + killTimeoutMs: 2_000, + }), + ); + await exited; + } finally { + if (!watchedExit) { + // Only a process this test still owns: the reap's own SIGTERM is the expected way out. + child.kill('SIGKILL'); + } + } + + expect(reaped.terminatedPids).toEqual([pid]); + expect(store.read()).toEqual([]); + expect(tracedCommands(logPath)).toContain('ps'); +}); + +/** The commands one debug run traced, in the order the request saw them. */ +function tracedCommands(logPath: string): string[] { + if (!fs.existsSync(logPath)) return []; + return fs + .readFileSync(logPath, 'utf8') + .trim() + .split('\n') + .filter(Boolean) + .map((line) => JSON.parse(line) as { phase?: string; data?: { command?: string } }) + .filter(({ phase }) => phase === 'exec_command') + .flatMap(({ data }) => (typeof data?.command === 'string' ? [data.command] : [])); +} diff --git a/src/platform-runtime/plugin-host.ts b/src/platform-runtime/plugin-host.ts index 7272bf7fa4..35c8d166ea 100644 --- a/src/platform-runtime/plugin-host.ts +++ b/src/platform-runtime/plugin-host.ts @@ -48,15 +48,7 @@ export function createPlatformPluginHost( const { whichCmd } = await import('@agent-device/host-kit/command'); return await whichCmd(executable, host.env); }, - listHostProcesses: async (options) => { - const [{ listHostProcesses }, { withoutCommandExecutorOverride }] = await Promise.all([ - import('@agent-device/host-kit/process'), - import('@agent-device/host-kit/command'), - ]); - // Reading the process table is a host read: a command override one request carries (an adb - // executor, say) must not answer for it. - return await withoutCommandExecutorOverride(async () => await listHostProcesses(options)); - }, + processes: createPlatformPluginProcessPort(host), startBackgroundCommand: async (request, signal) => { processes ??= await loadManagedAppLogProcesses(sessionsDir, host.env); return await processes.start( @@ -78,6 +70,46 @@ export function createPlatformPluginHost( } satisfies PlatformHost); } +/** + * The host's process answers, served by the core's own copy of the host kit. + * + * A managed plugin is bundled with its own copy of that kit, and the request's command-host and + * diagnostic scopes never enter the bundled copy, so a process tool spawned from there runs with the + * daemon process environment and traces into the plugin's own store. Answering here puts every + * process read in the scope the request was opened with, which is where `--debug` shows it. + */ +function createPlatformPluginProcessPort(host: HostEnvironment): PlatformHost['processes'] { + return Object.freeze({ + // The only read that does not leave the command-executor scope on its own: what a host says + // about its processes is a host read, never a toolchain command one request carries an override + // for (an adb executor, say). The reads below drop that scope themselves. + list: async (options) => { + const [{ listHostProcesses }, { withoutCommandExecutorOverride }] = await Promise.all([ + import('@agent-device/host-kit/process'), + import('@agent-device/host-kit/command'), + ]); + return await withoutCommandExecutorOverride(async () => await listHostProcesses(options)); + }, + readIdentities: async (pids, options) => { + const { readProcessIdentities } = await import('@agent-device/host-kit/process'); + return await readProcessIdentities(pids, options?.timeoutMs); + }, + readIdentityObservations: async (pids) => { + const { readHostProcessIdentityObservationsAsync } = + await import('@agent-device/host-kit/process'); + return await readHostProcessIdentityObservationsAsync(pids); + }, + readExecutablePaths: async (pids) => { + const { readProcessExecutablePaths } = await import('@agent-device/host-kit/process'); + return await readProcessExecutablePaths(pids, host); + }, + reapOwnedRecords: async (store, options) => { + const { reapOwnedProcessRecordsAtStartup } = await import('@agent-device/host-kit/process'); + return await reapOwnedProcessRecordsAtStartup(store, options); + }, + }); +} + async function loadManagedAppLogProcesses(sessionsDir: string, env: HostEnvironment['env']) { const { createManagedAppLogProcesses } = await import('../platform-runtime-app-log-process.ts'); return createManagedAppLogProcesses(sessionsDir, env); From eeafd3d5176da0cc94957acda3e01b894ce2fb37 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 21 Nov 2026 13:47:28 +0100 Subject: [PATCH 03/11] 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. --- packages/host-kit/src/process.ts | 1 + packages/platform-harmonyos/src/index.test.ts | 3 + .../src/command-host.fixtures.ts | 3 + packages/platform-vega/src/index.test.ts | 3 + .../agent-browser-process-record.test.ts | 3 + .../src/agent-browser-lifecycle.test.ts | 3 + .../src/agent-browser-tool.test.ts | 38 ++++++ .../platform-web/src/agent-browser-tool.ts | 29 ++--- .../src/index-startup-cleanup.test.ts | 3 + packages/platform-web/src/toolbox.fixtures.ts | 19 +++ packages/platform-web/test/package-smoke.mjs | 110 +++++++++++++++++- packages/plugins/src/platform.test.ts | 1 + packages/plugins/src/platform.ts | 20 ++++ src/platform-runtime/plugin-host.test.ts | 37 ++++++ src/platform-runtime/plugin-host.ts | 19 +++ 15 files changed, 270 insertions(+), 22 deletions(-) diff --git a/packages/host-kit/src/process.ts b/packages/host-kit/src/process.ts index 69654eb7d0..382c5c92fb 100644 --- a/packages/host-kit/src/process.ts +++ b/packages/host-kit/src/process.ts @@ -61,6 +61,7 @@ export { ownerIdentityMatches, type OwnerLiveness, readCurrentOwnerIdentity, + readCurrentOwnerIdentityAsync, } from './internal/owner-identity.ts'; /** Observes actual executable paths. Missing entries are unknown, not proof of exit. */ diff --git a/packages/platform-harmonyos/src/index.test.ts b/packages/platform-harmonyos/src/index.test.ts index 71066e1ab7..eb1fae1777 100644 --- a/packages/platform-harmonyos/src/index.test.ts +++ b/packages/platform-harmonyos/src/index.test.ts @@ -51,6 +51,9 @@ function createPluginHost( reapOwnedRecords: async () => { throw new Error('the HarmonyOS family never reaps host processes'); }, + withLock: async () => { + throw new Error('the HarmonyOS family takes no host lock'); + }, } satisfies PlatformHost['processes'], emitDiagnostic, withDiagnosticTimer, diff --git a/packages/platform-vega/src/command-host.fixtures.ts b/packages/platform-vega/src/command-host.fixtures.ts index cf81228e2b..dc77d2c1da 100644 --- a/packages/platform-vega/src/command-host.fixtures.ts +++ b/packages/platform-vega/src/command-host.fixtures.ts @@ -80,6 +80,9 @@ export function createVegaHostStub( reapOwnedRecords: async () => { throw new Error('the Vega family never reaps host processes'); }, + withLock: async () => { + throw new Error('the Vega family takes no host lock'); + }, } satisfies PlatformHost['processes'], runCommand: async ( executable: string, diff --git a/packages/platform-vega/src/index.test.ts b/packages/platform-vega/src/index.test.ts index d1cc551426..aae6ceab25 100644 --- a/packages/platform-vega/src/index.test.ts +++ b/packages/platform-vega/src/index.test.ts @@ -57,6 +57,9 @@ function createPluginHost( reapOwnedRecords: async () => { throw new Error('the Vega family never reaps host processes'); }, + withLock: async () => { + throw new Error('the Vega family takes no host lock'); + }, } satisfies PlatformHost['processes'], emitDiagnostic, withDiagnosticTimer, diff --git a/packages/platform-web/src/__tests__/agent-browser-process-record.test.ts b/packages/platform-web/src/__tests__/agent-browser-process-record.test.ts index 43f1dde27c..2355ed03f3 100644 --- a/packages/platform-web/src/__tests__/agent-browser-process-record.test.ts +++ b/packages/platform-web/src/__tests__/agent-browser-process-record.test.ts @@ -42,6 +42,9 @@ function createProcessPort(): PlatformHost['processes'] { reapOwnedRecords: async () => { throw new Error('the record probe never reaps'); }, + withLock: async () => { + throw new Error('the record probe takes no host lock'); + }, }; } diff --git a/packages/platform-web/src/agent-browser-lifecycle.test.ts b/packages/platform-web/src/agent-browser-lifecycle.test.ts index 724d57e6bb..6d60f09d09 100644 --- a/packages/platform-web/src/agent-browser-lifecycle.test.ts +++ b/packages/platform-web/src/agent-browser-lifecycle.test.ts @@ -100,6 +100,9 @@ function createHostProcessPort(): PlatformHost['processes'] { readExecutablePaths: async (pids) => await executablePathsMock([...pids], testHost), reapOwnedRecords: async (store, options) => await reapOwnedProcessRecordsAtStartup(store, options), + withLock: async () => { + throw new Error('the lifecycle suite takes no host lock'); + }, }; } diff --git a/packages/platform-web/src/agent-browser-tool.test.ts b/packages/platform-web/src/agent-browser-tool.test.ts index a277c2ca39..4780a2f363 100644 --- a/packages/platform-web/src/agent-browser-tool.test.ts +++ b/packages/platform-web/src/agent-browser-tool.test.ts @@ -306,6 +306,44 @@ test('managed agent-browser setup gives the install lock back on every path out' } }); +test('managed agent-browser setup asks its host to hold the install lock', async () => { + const stateDir = mkdtempForTestSync('agent-device-web-setup-host-lock-'); + vi.stubEnv('npm_execpath', writeFakeNpmCliScript(stateDir)); + try { + await withNodeRuntime({ version: '24.13.0' }, async () => { + const stub = createWebHostStub({ stateDir }); + await withCommandExecutorOverride( + async (_cmd: string, args: readonly string[]) => { + if (args.includes('install') && args.includes('--prefix')) { + writeFakeManagedAgentBrowserPackage(stateDir); + } + return { stdout: '', stderr: '', exitCode: 0 }; + }, + async () => + await setupManagedAgentBrowser({ + stateDir, + toolbox: stub.toolbox, + }), + ); + + // One lock request, naming the install lock beside the managed package. Nothing here proves a + // `ps` was spawned: the plugin carries no process tool at all, so the only identity read a + // claim can make is the one the host answers inside the request. + const lockReads = stub.processReads.filter((read) => read.kind === 'lock'); + assert.equal(lockReads.length, 1); + assert.deepEqual(lockReads[0], { + kind: 'lock', + pids: [], + lockDirPath: path.join(stateDir, 'tools', 'agent-browser', '.agent-browser-install.lock'), + timeoutMs: 5 * 60_000, + description: 'managed agent-browser setup', + }); + }); + } finally { + fs.rmSync(stateDir, { recursive: true, force: true }); + } +}); + function lockPathsUnder(directory: string): string[] { return fs.readdirSync(directory, { withFileTypes: true }).flatMap((entry) => { const entryPath = path.join(directory, entry.name); diff --git a/packages/platform-web/src/agent-browser-tool.ts b/packages/platform-web/src/agent-browser-tool.ts index b1d2d94b96..649f3b0866 100644 --- a/packages/platform-web/src/agent-browser-tool.ts +++ b/packages/platform-web/src/agent-browser-tool.ts @@ -1,5 +1,4 @@ import path from 'node:path'; -import { acquireProcessLock, withProcessLock } from '@agent-device/host-kit/file'; import { createHostDirectoryLinkSync, ensureHostDirectorySync, @@ -14,7 +13,6 @@ import { hostNodeExecutablePath, hostNodeVersion, hostPlatform, - hostProcessId, } from '@agent-device/host-kit/process'; import { AppError, asAppError } from '@agent-device/kernel/errors'; import type { HostEnvironment } from '@agent-device/kernel/source-value'; @@ -74,26 +72,15 @@ export async function setupManagedAgentBrowser(options: { }): Promise { const status = getManagedAgentBrowserStatus(managedStatusOptions(options)); assertWebNodeSupported(status.nodeMajor); - const processId = hostProcessId(); - return await withProcessLock({ - acquire: async () => - acquireProcessLock({ - lockDirPath: path.join(status.installDir, '..', '.agent-browser-install.lock'), - owner: { - pid: processId, - // The host names this process's start time: the plugin's own copy of the process tool would - // read it outside the request's exec trace. A host that will not answer leaves `null`, which - // is the same unproven claim a failed local probe always left. - startTime: - (await options.toolbox.host.processes.readIdentityObservations([processId])).get( - processId, - )?.startTime ?? null, - acquiredAtMs: Date.now(), - }, - timeoutMs: SETUP_TIMEOUT_MS, - description: 'managed agent-browser setup', - }), + // The install lock goes through the host: claiming it names this process's identity with a `ps` + // read, and every poll of a held or stale lock re-proves the recorded owner and the guard holder + // with another. Answered from the plugin's bundled copy those reads run with the daemon + // environment and trace into the bundle's own store, so the request that waited shows no wait. + return await options.toolbox.host.processes.withLock({ + lockDirPath: path.join(status.installDir, '..', '.agent-browser-install.lock'), + timeoutMs: SETUP_TIMEOUT_MS, + description: 'managed agent-browser setup', task: async () => { const freshStatus = getManagedAgentBrowserStatus(managedStatusOptions(options)); if (freshStatus.installed) return freshStatus; diff --git a/packages/platform-web/src/index-startup-cleanup.test.ts b/packages/platform-web/src/index-startup-cleanup.test.ts index fbf84ecb98..ac39651f72 100644 --- a/packages/platform-web/src/index-startup-cleanup.test.ts +++ b/packages/platform-web/src/index-startup-cleanup.test.ts @@ -38,6 +38,9 @@ function cleanupWebBrowserOrphansForDaemonStartup(stateDir: string) { reapOwnedRecords: async () => { throw new Error('this suite stands the reap in for'); }, + withLock: async () => { + throw new Error('this suite stands the install lock in for'); + }, } satisfies PlatformHost['processes'], emitDiagnostic, withDiagnosticTimer, diff --git a/packages/platform-web/src/toolbox.fixtures.ts b/packages/platform-web/src/toolbox.fixtures.ts index b4f4da80a0..701688a4a2 100644 --- a/packages/platform-web/src/toolbox.fixtures.ts +++ b/packages/platform-web/src/toolbox.fixtures.ts @@ -36,6 +36,13 @@ export type WebHostStubProcessRead = Readonly< store: OwnedProcessRecordStore; options: Parameters[1]; } + | { + kind: 'lock'; + pids: []; + lockDirPath: string; + timeoutMs: number; + description: string | undefined; + } >; /** Every process read the plugin asked its host to make, in order. */ @@ -130,6 +137,18 @@ export function createWebHostStub( processReads.push({ kind: 'reap', pids: [], store, options }); return answered.reap ?? EMPTY_REAP_SUMMARY; }, + // The stub runs the task inline: one test process cannot contend with itself for a lock, and what a + // test needs to see is that the plugin asked its host to hold it. + withLock: async (params) => { + processReads.push({ + kind: 'lock', + pids: [], + lockDirPath: params.lockDirPath, + timeoutMs: params.timeoutMs, + description: params.description, + }); + return await params.task(); + }, }; const host = Object.freeze({ env: input.env ?? process.env, diff --git a/packages/platform-web/test/package-smoke.mjs b/packages/platform-web/test/package-smoke.mjs index 9a48e66d9a..70b0efcb9a 100644 --- a/packages/platform-web/test/package-smoke.mjs +++ b/packages/platform-web/test/package-smoke.mjs @@ -1,5 +1,5 @@ import assert from 'node:assert/strict'; -import { execFileSync } from 'node:child_process'; +import { execFileSync, spawnSync } from 'node:child_process'; import fs from 'node:fs'; import os from 'node:os'; import path from 'node:path'; @@ -33,6 +33,50 @@ function managedBackendEntrySource(logFile) { ].join('\n'); } +/** + * A stand-in for npm on `PATH`. It answers only the managed-backend install — the plugin's own + * `npm install --prefix agent-browser@` — by writing the package tree that install + * leaves behind, and defers every other npm call to the real npm, so installing the packed plugin + * through the CLI keeps working. + */ +function npmFixtureSource(realNpm) { + return [ + '#!/bin/sh', + 'managed=0', + 'for a in "$@"; do', + ' case "$a" in agent-browser@*) managed=1 ;; esac', + 'done', + `if [ "$managed" != 1 ]; then exec ${JSON.stringify(realNpm)} "$@"; fi`, + 'prefix=""', + 'next=0', + 'for a in "$@"; do', + ' if [ "$next" = 1 ]; then prefix="$a"; next=0; fi', + ' if [ "$a" = "--prefix" ]; then next=1; fi', + 'done', + 'if [ -z "$prefix" ]; then exit 1; fi', + 'mkdir -p "$prefix/node_modules/agent-browser/dist" "$prefix/node_modules/.bin"', + String.raw`printf 'process.exit(0)\n' > "$prefix/node_modules/agent-browser/dist/cli.js"`, + String.raw`printf '#!/bin/sh\nexit 0\n' > "$prefix/node_modules/.bin/agent-browser"`, + 'chmod 755 "$prefix/node_modules/.bin/agent-browser"', + 'printf \'{"name":"agent-browser","version":"0.39.0","bin":{"agent-browser":"./dist/cli.js"}}\' > "$prefix/node_modules/agent-browser/package.json"', + 'exit 0', + ].join('\n'); +} + +/** + * The `--debug` records one CLI run printed to its own stderr: `--json` keeps stdout as the reply + * alone. A run the CLI answers in process never reaches the daemon's request files, so this stream is + * that request's whole trace. + */ +function debugRecordsOf(stderr) { + return stderr + .split('\n') + .filter((line) => line.startsWith(DEBUG_RECORD_PREFIX)) + .map((line) => JSON.parse(line.slice(DEBUG_RECORD_PREFIX.length))); +} + +const DEBUG_RECORD_PREFIX = '[agent-device][diag] '; + /** * The records one `--debug` request wrote, read back from the request records the daemon keeps under * its session dirs. Matched by the CLI command they belong to, so an empty answer means the request @@ -136,6 +180,70 @@ test('packed core discovers web only after the managed platform is installed', ( ); const plugins = runCli(0, 'daemon', 'status').data.plugins; assert.ok(plugins.some((plugin) => plugin.platform === 'web' && plugin.state === 'active')); + + // The install lock, on the state dir a managed install has not yet touched. Claiming the lock + // names this process's identity with a process-tool read, and the packed plugin carries no + // process tool to make that read with (asserted below), so the host has to answer it — and the + // `--debug` reply proves the host traced it into the request that asked for the install. + // POSIX only: the npm stand-in below is a shell script. + if (process.platform !== 'win32') { + const bundleDir = path.join( + env.AGENT_DEVICE_HOME, + 'plugins', + runCli(0, 'plugins', 'list').data.plugins[0].installation, + 'node_modules', + '@agent-device', + 'web', + 'dist', + ); + const bundle = fs + .readdirSync(bundleDir) + .filter((file) => file.endsWith('.mjs')) + .map((file) => [file, fs.readFileSync(path.join(bundleDir, file), 'utf8')]); + assert.ok(bundle.length > 0, `no packed plugin chunks under ${bundleDir}`); + assert.deepEqual( + bundle.filter(([, source]) => source.includes('node:child_process')).map(([file]) => file), + [], + 'the packed web plugin must carry no process tool of its own', + ); + + const binDir = path.join(scratch, 'bin'); + fs.mkdirSync(binDir, { recursive: true }); + fs.writeFileSync( + path.join(binDir, 'npm'), + npmFixtureSource(execFileSync('which', ['npm'], { env, encoding: 'utf8' }).trim()), + { mode: 0o755 }, + ); + // `--debug` with no log file streams the request's records to stderr, `--json` keeping stdout + // as the reply alone. A managed install is answered in the CLI's own process, so this stream is + // that request's whole exec trace. + const setup = spawnSync( + process.execPath, + ['node_modules/agent-device/bin/agent-device.mjs', 'web', 'setup', '--json', '--debug'], + { + cwd: scratch, + env: { ...env, PATH: `${binDir}:${env.PATH}` }, + encoding: 'utf8', + timeout: 300_000, + }, + ); + const setupRecords = debugRecordsOf(String(setup.stderr ?? '')); + assert.equal(setup.status, 0, `web setup failed: ${String(setup.stdout).slice(0, 400)}`); + const setupSpawns = setupRecords + .filter((record) => record.phase === 'exec_command' && record.data?.event === 'spawn') + .map((record) => record.data.command); + assert.ok( + setupSpawns.includes('ps'), + `the setup request traced no process-tool read out of ${setupRecords.length} records: ${JSON.stringify( + setupSpawns, + )}`, + ); + assert.ok( + setupSpawns.some((command) => command === 'npm' || command === 'node'), + `the setup request traced no managed-backend install: ${JSON.stringify(setupSpawns)}`, + ); + } + const install = installFakeManagedAgentBrowser(storeRoot); assert.equal(runCli(0, 'web', 'doctor').data.status.installed, true); diff --git a/packages/plugins/src/platform.test.ts b/packages/plugins/src/platform.test.ts index 02504e3281..3f2524c485 100644 --- a/packages/plugins/src/platform.test.ts +++ b/packages/plugins/src/platform.test.ts @@ -58,6 +58,7 @@ async function startStore(env: HostEnvironment['env']) { reapOwnedRecords: async () => { throw new Error('setup must not reap host processes'); }, + withLock: async (params) => await params.task(), }, emitDiagnostic: () => {}, withDiagnosticTimer: async (_phase, run) => await run(), diff --git a/packages/plugins/src/platform.ts b/packages/plugins/src/platform.ts index c794e31017..979345586d 100644 --- a/packages/plugins/src/platform.ts +++ b/packages/plugins/src/platform.ts @@ -190,6 +190,26 @@ export type PlatformHostProcesses = Readonly<{ killTimeoutMs?: number; }, ): Promise; + /** + * Runs `task` while the host holds the process lock at `lockDirPath`, and answers the lock's own + * questions — which process owns the claim, and whether that owner is still that process — from the + * host's copy of the lock mechanics. + * + * A lock is not a file write: claiming one names this process's identity with a process-tool read, + * and every poll of a held or stale lock re-proves the recorded owner and the guard holder with + * another. Run from the plugin's bundled copy, those reads answer with the daemon process + * environment and trace into the bundle's own store, so the request that waited shows no wait. The + * host is the process that takes the claim, so it names its own identity rather than being told it. + */ + withLock(params: { + /** The lock directory the host creates, holds and removes. */ + lockDirPath: string; + /** How long the plugin will wait for a claim it cannot take; the host owns the poll. */ + timeoutMs: number; + /** Names this lock in a timeout or an unverified release, in the request's log. */ + description?: string; + task: () => Promise; + }): Promise; }>; export type PlatformSetup = Family extends Platform diff --git a/src/platform-runtime/plugin-host.test.ts b/src/platform-runtime/plugin-host.test.ts index 7d4e6bcc84..14dee13470 100644 --- a/src/platform-runtime/plugin-host.test.ts +++ b/src/platform-runtime/plugin-host.test.ts @@ -182,6 +182,43 @@ test('the platform plugin host stops a recorded process it is asked to reap', as expect(tracedCommands(logPath)).toContain('ps'); }); +// The managed web install lock is the other place a plugin would otherwise take a claim with its own +// copy of the lock mechanics: naming an owner reads this process's birth time through the process tool, +// and every poll of a held lock re-proves the recorded owner and the guard holder with another. Answered +// here, both the claim and the wait land in the request's exec trace. +test('the platform plugin host holds a lock and names this process as its owner', async () => { + const root = mkdtempForTestSync('plugin-host-lock-'); + const logPath = path.join(root, 'events.ndjson'); + const lockDirPath = path.join(root, 'install', '.agent-browser-install.lock'); + const host = createPlatformPluginHost(createLiveTestHostEnvironment(), root); + + let ownerWhileHeld: { pid: number; startTime: string | null } | undefined; + const result = await withDiagnosticsScope( + { command: 'open', debug: true, logPath }, + async () => + await host.processes.withLock({ + lockDirPath, + timeoutMs: 5_000, + description: 'managed agent-browser setup', + task: async () => { + // The claim is standing, and it names this process by the identity only a host read gives. + ownerWhileHeld = JSON.parse( + fs.readFileSync(path.join(lockDirPath, 'owner.json'), 'utf8'), + ) as { pid: number; startTime: string | null }; + return 'task result'; + }, + }), + ); + + expect(result).toBe('task result'); + expect(ownerWhileHeld?.pid).toBe(process.pid); + expect(ownerWhileHeld?.startTime).toBeTruthy(); + // A released lock leaves no claim standing for the next caller to wait on. + expect(fs.existsSync(lockDirPath)).toBe(false); + // The owner identity read is a `ps`, traced by the host that took the claim. + expect(tracedCommands(logPath)).toContain('ps'); +}); + /** The commands one debug run traced, in the order the request saw them. */ function tracedCommands(logPath: string): string[] { if (!fs.existsSync(logPath)) return []; diff --git a/src/platform-runtime/plugin-host.ts b/src/platform-runtime/plugin-host.ts index 35c8d166ea..e1f671f1df 100644 --- a/src/platform-runtime/plugin-host.ts +++ b/src/platform-runtime/plugin-host.ts @@ -107,6 +107,25 @@ function createPlatformPluginProcessPort(host: HostEnvironment): PlatformHost['p const { reapOwnedProcessRecordsAtStartup } = await import('@agent-device/host-kit/process'); return await reapOwnedProcessRecordsAtStartup(store, options); }, + // The claim is this process's own, so the lock names this process's identity itself: a plugin + // that brought its own copy would read that identity with its own process tool and trace the + // wait into its own store, which is where a held install lock goes missing from `--debug`. + // The async form is the one the request sees: it runs `ps` through the command host, which is + // what traces the identity read, where the synchronous probe's `spawnSync` never appears. + withLock: async (params) => { + const { acquireProcessLock, withProcessLock } = await import('@agent-device/host-kit/file'); + const { readCurrentOwnerIdentityAsync } = await import('@agent-device/host-kit/process'); + return await withProcessLock({ + acquire: async () => + await acquireProcessLock({ + lockDirPath: params.lockDirPath, + owner: { ...(await readCurrentOwnerIdentityAsync()), acquiredAtMs: Date.now() }, + timeoutMs: params.timeoutMs, + ...(params.description === undefined ? {} : { description: params.description }), + }), + task: params.task, + }); + }, }); } From 1fa486b56415709c3175cde921202a403c963f86 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 21 Nov 2026 13:47:33 +0100 Subject: [PATCH 04/11] 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. --- .../src/internal/exec-kill-settle.test.ts | 2 +- .../src/internal/host-process-facts.ts | 147 ++++++++ .../host-kit/src/internal/host-process.ts | 154 ++------ .../host-kit/src/internal/process-lock.ts | 2 +- packages/host-kit/src/internal/retry.ts | 29 +- packages/host-kit/src/internal/sleep.ts | 39 ++ packages/host-kit/src/retry.ts | 4 +- scripts/layering/host-kit-runtime-reach.ts | 346 ++++++++++++++++++ scripts/layering/model.test.ts | 39 ++ scripts/layering/model.ts | 49 ++- .../platform-package-policy.fixtures.ts | 159 ++++++++ .../layering/platform-package-policy.test.ts | 245 ++++++------- scripts/layering/platform-package-policy.ts | 190 +++++----- 13 files changed, 1016 insertions(+), 389 deletions(-) create mode 100644 packages/host-kit/src/internal/host-process-facts.ts create mode 100644 packages/host-kit/src/internal/sleep.ts create mode 100644 scripts/layering/host-kit-runtime-reach.ts create mode 100644 scripts/layering/platform-package-policy.fixtures.ts diff --git a/packages/host-kit/src/internal/exec-kill-settle.test.ts b/packages/host-kit/src/internal/exec-kill-settle.test.ts index 8d19624b6f..dc41d067d1 100644 --- a/packages/host-kit/src/internal/exec-kill-settle.test.ts +++ b/packages/host-kit/src/internal/exec-kill-settle.test.ts @@ -13,7 +13,7 @@ import { type ExecStreamOptions, } from './exec.ts'; import { shellQuote } from '@agent-device/kernel/device-shell'; -import { sleep } from './retry.ts'; +import { sleep } from './sleep.ts'; import { mkdtempForTestSync } from './tmp-dir.fixtures.ts'; // A direct child can hand our stdout/stderr pipes to a descendant, and `close` waits diff --git a/packages/host-kit/src/internal/host-process-facts.ts b/packages/host-kit/src/internal/host-process-facts.ts new file mode 100644 index 0000000000..beb5d606f9 --- /dev/null +++ b/packages/host-kit/src/internal/host-process-facts.ts @@ -0,0 +1,147 @@ +import type { EnvMap, HostEnvironment } from '@agent-device/kernel/source-value'; + +/** + * What one process knows about itself and its machine without asking the host for anything: the + * platform, the Node it runs, its own pid, whether another pid is still there, and the pid arithmetic + * that works over rows the caller already holds. This module runs no command, reads no process table + * and emits no diagnostic, so it is the clean leaf of the process surface. `internal/host-process.ts` + * is the read side: it runs `ps`, PowerShell and `sysctl`, and takes these facts from here. + * + * The line matters because a managed platform package is bundled with its own copy of host-kit. A + * runtime import of a module that reaches `internal/exec.ts` or `internal/diagnostics.ts` answers with + * the daemon's process environment and traces into the bundle's own store, outside the request's + * captured environment and exec trace. The platform package policy derives which host-kit exports a + * managed package may import from that graph, so what is declared here stays importable and what is + * not stays with the reads. + */ + +/** The process-shaped object an entry point captures: Node's `process` satisfies it. */ +export type HostEnvironmentSource = Readonly<{ + env: EnvMap; + cwd(): string; +}>; + +/** + * Snapshots the environment and working directory of `source`, which an entry point passes as + * `process`. The environment is copied, so later changes to the source never reach the capture. + */ +export function captureHostEnvironment(source: HostEnvironmentSource): HostEnvironment { + return { env: { ...source.env }, cwd: source.cwd() }; +} + +/** One host answer about one pid: what the process table calls its state and birth time. */ +export type HostProcessIdentityObservation = Readonly<{ + state: string; + startTime: string; +}>; + +/** One row of a host process table: the pid, its parent when the host named one, and its command. */ +export type HostProcessInfo = { + pid: number; + ppid?: number; + command: string; +}; + +/** Positive proof of different lifetimes; unreadable or mixed-format records prove nothing. */ +export function processStartTimesDiffer( + left: string | null | undefined, + right: string | null | undefined, +): boolean { + if (!left || !right) return false; + if (left.startsWith('linux:') !== right.startsWith('linux:')) return false; + return left !== right; +} + +/** Whether the host still has this pid. A refused probe means the process is there. */ +export function isProcessAlive(pid: number): boolean { + if (!Number.isInteger(pid) || pid <= 0) return false; + try { + process.kill(pid, 0); + return true; + } catch (error) { + return (error as NodeJS.ErrnoException).code === 'EPERM'; + } +} + +/** Whether the process group of `pid` still exists, on the same refusal rule as a pid probe. */ +export function isProcessGroupAlive(pid: number): boolean { + if (!Number.isInteger(pid) || pid <= 0) return false; + try { + process.kill(-pid, 0); + return true; + } catch (error) { + return (error as NodeJS.ErrnoException).code === 'EPERM'; + } +} + +export function writeHostStderr(value: string): void { + process.stderr.write(value); +} + +export function hostNodeExecutablePath(): string { + return process.execPath; +} + +export function hostNodeVersion(): string { + return process.version; +} + +export function hostPlatform(): NodeJS.Platform { + return process.platform; +} + +/** Whether this host runs Windows, where identity facts come from the CIM table instead of `ps`. */ +export function isWindowsHostPlatform(): boolean { + return process.platform === 'win32'; +} + +export function hostProcessId(): number { + return process.pid; +} + +/** The pids to act on: integral, positive, deduplicated, and never the excluded one. */ +export function uniquePositivePids( + values: Iterable, + options: { excludePid?: number } = {}, +): number[] { + return [...new Set(values)].filter( + (pid) => Number.isInteger(pid) && pid > 0 && pid !== options.excludePid, + ); +} + +/** Every row of `processes` that descends from `rootPids`, together with those roots. */ +export function expandProcessTree( + rootPids: readonly number[], + processes: readonly HostProcessInfo[], +): HostProcessInfo[] { + const selected = new Set(uniquePositivePids(rootPids)); + let changed = true; + while (changed) { + changed = false; + for (const processInfo of processes) { + if (processInfo.ppid === undefined || !selected.has(processInfo.ppid)) continue; + if (selected.has(processInfo.pid)) continue; + selected.add(processInfo.pid); + changed = true; + } + } + return processes.filter((processInfo) => selected.has(processInfo.pid)); +} + +/** Signals every pid named except this process's own, and counts the ones the host accepted. */ +export function signalPidsBestEffort( + pidsToSignal: readonly number[], + signal: NodeJS.Signals, +): number { + const pids = uniquePositivePids(pidsToSignal, { excludePid: process.pid }); + let signaled = 0; + for (const pid of pids) { + try { + process.kill(pid, signal); + signaled += 1; + } catch { + // Process already exited or cannot be signaled; cleanup remains best-effort. + } + } + return signaled; +} diff --git a/packages/host-kit/src/internal/host-process.ts b/packages/host-kit/src/internal/host-process.ts index f7533107ae..57f88b1e9e 100644 --- a/packages/host-kit/src/internal/host-process.ts +++ b/packages/host-kit/src/internal/host-process.ts @@ -1,8 +1,35 @@ import fs from 'node:fs'; import type { ExecOptions, ExecResult } from './exec.ts'; import { runCmd, runCmdSync, withoutCommandExecutorOverride } from './exec.ts'; -import { sleep } from './retry.ts'; -import type { EnvMap, HostEnvironment } from '@agent-device/kernel/source-value'; +import { sleep } from './sleep.ts'; +import { + isProcessAlive, + isWindowsHostPlatform, + processStartTimesDiffer, + uniquePositivePids, + type HostProcessIdentityObservation, + type HostProcessInfo, +} from './host-process-facts.ts'; +// Everything this module reads with a process tool lives here; what a process knows about itself lives +// in `host-process-facts.ts` and is forwarded so consumers of either module see one set of names. +export { + captureHostEnvironment, + expandProcessTree, + hostNodeExecutablePath, + hostNodeVersion, + hostPlatform, + hostProcessId, + type HostEnvironmentSource, + type HostProcessIdentityObservation, + type HostProcessInfo, + isProcessAlive, + isProcessGroupAlive, + isWindowsHostPlatform, + processStartTimesDiffer, + signalPidsBestEffort, + uniquePositivePids, + writeHostStderr, +} from './host-process-facts.ts'; const PS_TIMEOUT_MS = 1_000; // Every POSIX probe runs the first of these that exists, never a PATH lookup, so a hostile PATH @@ -14,17 +41,6 @@ const HOST_PS_COMMANDS = ['/bin/ps', '/run/current-system/sw/bin/ps'] as const; const WINDOWS_PS_TIMEOUT_MS = 2_000; const WINDOWS_PROCESS_TOOL = 'powershell.exe'; -export type HostProcessInfo = { - pid: number; - ppid?: number; - command: string; -}; - -export type HostProcessIdentityObservation = Readonly<{ - state: string; - startTime: string; -}>; - /** * What the host says about one pid when a caller is about to signal it. Each field is `null` * when the host did not answer, which is unknown evidence rather than absence: only a `ps` @@ -44,40 +60,6 @@ type HostProcessRunCommand = ( options: ExecOptions, ) => Promise; -/** The process-shaped object an entry point captures: Node's `process` satisfies it. */ -export type HostEnvironmentSource = Readonly<{ - env: EnvMap; - cwd(): string; -}>; - -/** - * Snapshots the environment and working directory of `source`, which an entry point passes as - * `process`. The environment is copied, so later changes to the source never reach the capture. - */ -export function captureHostEnvironment(source: HostEnvironmentSource): HostEnvironment { - return { env: { ...source.env }, cwd: source.cwd() }; -} - -export function writeHostStderr(value: string): void { - process.stderr.write(value); -} - -export function hostNodeExecutablePath(): string { - return process.execPath; -} - -export function hostNodeVersion(): string { - return process.version; -} - -export function hostPlatform(): NodeJS.Platform { - return process.platform; -} - -export function hostProcessId(): number { - return process.pid; -} - function hostPsCommand(): string { for (const candidate of HOST_PS_COMMANDS) { try { @@ -93,26 +75,6 @@ export type ListHostProcessesOptions = { runCommand?: HostProcessRunCommand; }; -export function isProcessAlive(pid: number): boolean { - if (!Number.isInteger(pid) || pid <= 0) return false; - try { - process.kill(pid, 0); - return true; - } catch (error) { - return (error as NodeJS.ErrnoException).code === 'EPERM'; - } -} - -export function isProcessGroupAlive(pid: number): boolean { - if (!Number.isInteger(pid) || pid <= 0) return false; - try { - process.kill(-pid, 0); - return true; - } catch (error) { - return (error as NodeJS.ErrnoException).code === 'EPERM'; - } -} - /** * Reads who owns a pid, off the event loop, with a budget the caller names. Use this rather than * the synchronous probes when the answer decides whether a process is signaled: waiting is @@ -240,16 +202,6 @@ function readLinuxProcessStat(pid: number): { state: string; startTime: string } } } -/** Positive proof of different lifetimes; unreadable or mixed-format records prove nothing. */ -export function processStartTimesDiffer( - left: string | null | undefined, - right: string | null | undefined, -): boolean { - if (!left || !right) return false; - if (left.startsWith('linux:') !== right.startsWith('linux:')) return false; - return left !== right; -} - export function readProcessStartTime(pid: number): string | null { return readProcessField(pid, 'lstart='); } @@ -458,10 +410,6 @@ type WindowsProcessRow = Readonly<{ command: string | null; }>; -function isWindowsHostPlatform(): boolean { - return hostPlatform() === 'win32'; -} - // Rows are `pid|ppid|creation|command`. The creation stamp is formatted with // the invariant culture, so the value recorded in daemon.json compares equal // on every read of the same process lifetime regardless of host locale. The @@ -587,50 +535,6 @@ export async function listHostProcesses( return parseHostProcessList(result.stdout); } -export function expandProcessTree( - rootPids: readonly number[], - processes: readonly HostProcessInfo[], -): HostProcessInfo[] { - const selected = new Set(uniquePositivePids(rootPids)); - let changed = true; - while (changed) { - changed = false; - for (const processInfo of processes) { - if (processInfo.ppid === undefined || !selected.has(processInfo.ppid)) continue; - if (selected.has(processInfo.pid)) continue; - selected.add(processInfo.pid); - changed = true; - } - } - return processes.filter((processInfo) => selected.has(processInfo.pid)); -} - -export function uniquePositivePids( - values: Iterable, - options: { excludePid?: number } = {}, -): number[] { - return [...new Set(values)].filter( - (pid) => Number.isInteger(pid) && pid > 0 && pid !== options.excludePid, - ); -} - -export function signalPidsBestEffort( - pidsToSignal: readonly number[], - signal: NodeJS.Signals, -): number { - const pids = uniquePositivePids(pidsToSignal, { excludePid: process.pid }); - let signaled = 0; - for (const pid of pids) { - try { - process.kill(pid, signal); - signaled += 1; - } catch { - // Process already exited or cannot be signaled; cleanup remains best-effort. - } - } - return signaled; -} - export async function waitForProcessExit(pid: number, timeoutMs: number): Promise { if (!isProcessAlive(pid)) return true; const start = Date.now(); diff --git a/packages/host-kit/src/internal/process-lock.ts b/packages/host-kit/src/internal/process-lock.ts index 3b5282fb13..9eb244a9da 100644 --- a/packages/host-kit/src/internal/process-lock.ts +++ b/packages/host-kit/src/internal/process-lock.ts @@ -20,7 +20,7 @@ import { readCurrentOwnerIdentityAsync, type OwnerLiveness, } from './owner-identity.ts'; -import { sleep } from './retry.ts'; +import { sleep } from './sleep.ts'; const OWNER_FILE_NAME = 'owner.json'; const DEFAULT_LOCK_TIMEOUT_MS = 30_000; diff --git a/packages/host-kit/src/internal/retry.ts b/packages/host-kit/src/internal/retry.ts index 47208f6b07..d4782b1b56 100644 --- a/packages/host-kit/src/internal/retry.ts +++ b/packages/host-kit/src/internal/retry.ts @@ -1,5 +1,6 @@ import { AppError, createRequestCanceledError } from '@agent-device/kernel/errors'; import { emitDiagnostic } from './diagnostics.ts'; +import { sleep } from './sleep.ts'; type RetryPolicy = { maxAttempts: number; @@ -253,34 +254,6 @@ function computeDelay(base: number, max: number, jitter: number, attempt: number return Math.max(0, exp + (Math.random() * 2 - 1) * jitterAmount); } -export function sleep(ms: number, signal?: AbortSignal): Promise { - return new Promise((resolve) => { - if (signal?.aborted) { - resolve(); - return; - } - let settled = false; - const finish = () => { - if (settled) return; - settled = true; - if (signal) { - signal.removeEventListener('abort', onAbort); - } - resolve(); - }; - const timer = setTimeout(finish, ms); - - function onAbort(): void { - clearTimeout(timer); - finish(); - } - - if (signal) { - signal.addEventListener('abort', onAbort, { once: true }); - } - }); -} - function publishRetryEvent(event: RetryTelemetryEvent): void { emitDiagnostic({ level: event.event === 'attempt_failed' || event.event === 'exhausted' ? 'warn' : 'debug', diff --git a/packages/host-kit/src/internal/sleep.ts b/packages/host-kit/src/internal/sleep.ts new file mode 100644 index 0000000000..6a7a672619 --- /dev/null +++ b/packages/host-kit/src/internal/sleep.ts @@ -0,0 +1,39 @@ +/** + * Waits without naming what it is waiting for. This module imports nothing, so a caller that only + * paces itself never evaluates the retry policy, its diagnostic telemetry, or the error vocabulary + * `internal/retry.ts` carries. + * + * The leaf matters twice over. `settle-within.ts` states the same reason for the deadline primitive: + * the eager-closure gate measures the difference. And the platform package policy reads the host-kit + * module graph to decide which exports a managed platform package may import at runtime, because a + * managed plugin is bundled with its own copy of host-kit: a module that reaches the exec layer or the + * diagnostic store from that copy answers with the daemon's environment, outside the request's captured + * environment and exec trace. Pacing stays on the clean side of that line. + */ +export function sleep(ms: number, signal?: AbortSignal): Promise { + return new Promise((resolve) => { + if (signal?.aborted) { + resolve(); + return; + } + let settled = false; + const finish = () => { + if (settled) return; + settled = true; + if (signal) { + signal.removeEventListener('abort', onAbort); + } + resolve(); + }; + const timer = setTimeout(finish, ms); + + function onAbort(): void { + clearTimeout(timer); + finish(); + } + + if (signal) { + signal.addEventListener('abort', onAbort, { once: true }); + } + }); +} diff --git a/packages/host-kit/src/retry.ts b/packages/host-kit/src/retry.ts index 92737e9547..d280b2a89d 100644 --- a/packages/host-kit/src/retry.ts +++ b/packages/host-kit/src/retry.ts @@ -6,7 +6,9 @@ export { openScope, pollUntilSettled, retryWithPolicy, - sleep, RETRY_PHASE, type Scope, } from './internal/retry.ts'; +// The timer is published beside the policy and stays a dependency-free leaf: pacing itself reads no +// command host and emits no diagnostic, and the platform policy reads that difference. +export { sleep } from './internal/sleep.ts'; diff --git a/scripts/layering/host-kit-runtime-reach.ts b/scripts/layering/host-kit-runtime-reach.ts new file mode 100644 index 0000000000..02a4229f00 --- /dev/null +++ b/scripts/layering/host-kit-runtime-reach.ts @@ -0,0 +1,346 @@ +import path from 'node:path'; +import { parseSync } from 'oxc-parser'; +import { nodeList, propertyName, type AstNode } from './layering-ast.ts'; +import { parseImports } from './model.ts'; + +/** + * The reach rule for a host-kit export a managed platform package imports at runtime. + * + * A managed plugin is bundled with its own copy of host-kit, and the daemon's command-host and + * diagnostic scopes never enter that copy. So a runtime import of a host-kit module that reaches + * `internal/exec.ts` or `internal/diagnostics.ts` runs its `ps`, PowerShell or `sysctl` probe with the + * daemon process environment, and writes its diagnostics to the bundle's own store: the request that + * made the call shows neither. Such a read belongs on the `PlatformHost` the core hands to `setup`, + * which answers from the core's own copy inside the request scope. + * + * Which exports those are is a property of the host-kit module graph, not of a name list, so this + * derives it from the runtime import edges and the re-export chains of each public subpath. A new + * export that starts loading the exec layer through a new import is caught by the graph, with no list + * to edit. + */ + +/** The host-kit internals a managed plugin's bundled copy must never load. */ +export const HOST_KIT_EXEC_ROOTS: readonly string[] = [ + 'packages/host-kit/src/internal/exec.ts', + 'packages/host-kit/src/internal/diagnostics.ts', +]; + +/** Where host-kit's sources live: its public subpaths are the top-level modules below this. */ +export const HOST_KIT_SOURCE_ROOT = 'packages/host-kit/src/'; + +/** The workspace specifier prefix every host-kit subpath is published under. */ +export const HOST_KIT_SPECIFIER_PREFIX = '@agent-device/host-kit/'; + +/** One host-kit public subpath, as the module graph says it behaves. */ +export type HostKitScopeSurface = Readonly<{ + /** The workspace specifier of the subpath, e.g. `@agent-device/host-kit/process`. */ + specifier: string; + /** The host-kit source the subpath points at. */ + entry: string; + /** Exported names whose declaration loads neither exec root. */ + pureExports: ReadonlySet; + /** Exported names whose declaration loads an exec root, directly or through the graph. */ + execExports: ReadonlySet; + /** Whether a re-export of a whole namespace means no name list can bound the subpath. */ + unbounded: boolean; +}>; + +export type HostKitReachIndex = Readonly<{ + /** One surface per subpath whose entry is an indexed source, keyed by specifier. */ + surfaces: ReadonlyMap; +}>; + +/** What one module says about itself: what it loads at runtime, and what it exports. */ +type ModuleSurface = Readonly<{ + /** Specifiers this module loads at runtime, static or dynamic; unresolvable ones load outside. */ + imports: readonly string[]; + /** Names this module exports that it declares itself, as values. */ + declared: ReadonlySet; + /** Names this module exports as types only: a runtime import never binds one. */ + typeExports: ReadonlySet; + /** Exported name to the specifier and name it forwards. */ + forwarded: ReadonlyMap>; + /** Whether this module re-exports a whole namespace. */ + starReexport: boolean; +}>; + +/** + * Indexes the host-kit module graph and answers for each public subpath which exported names load the + * exec layer. `entries` maps a subpath specifier to its source file; a specifier whose entry is not an + * indexed source is reported as stale rather than answered as an empty surface, so a rename or a move + * cannot turn the rule green. `resolve` answers which indexed module a specifier from a given file + * loads, or `undefined` for a module this index does not contain. + */ +export function indexHostKitReach(params: { + /** The host-kit production sources to derive over, keyed by repo-root-relative path. */ + sources: ReadonlyMap; + entries: ReadonlyMap; + resolve: (fromFile: string, spec: string) => string | undefined; +}): HostKitReachIndex { + const surfaces = new Map(); + for (const [file, source] of params.sources) surfaces.set(file, readModuleSurface(source)); + const loadsExecRoot = (file: string, seen: Set): boolean => { + if (HOST_KIT_EXEC_ROOTS.includes(file)) return true; + if (seen.has(file)) return false; + seen.add(file); + const surface = surfaces.get(file); + if (!surface) return false; + return surface.imports.some((spec) => { + const target = params.resolve(file, spec); + return target !== undefined && loadsExecRoot(target, seen); + }); + }; + const escapeMemo = new Map(); + const escapes = (file: string): boolean => { + const known = escapeMemo.get(file); + if (known !== undefined) return known; + const answer = loadsExecRoot(file, new Set()); + escapeMemo.set(file, answer); + return answer; + }; + const bySpecifier = new Map(); + for (const [specifier, entry] of params.entries) { + // A specifier whose entry is not an indexed source is answered by no surface at all, so the caller + // refuses an import of it rather than treating an unlocatable subpath as proven pure. + if (!surfaces.has(entry)) continue; + bySpecifier.set(specifier, scopeSurface(specifier, entry, surfaces, escapes, params.resolve)); + } + return { surfaces: bySpecifier }; +} + +function scopeSurface( + specifier: string, + entry: string, + surfaces: ReadonlyMap, + escapes: (file: string) => boolean, + resolve: (fromFile: string, spec: string) => string | undefined, +): HostKitScopeSurface { + const pureExports = new Set(); + const execExports = new Set(); + let unbounded = false; + const seen = new Set(); + const queue: Readonly<{ file: string; name: string }>[] = []; + const push = (step: Readonly<{ file: string; name: string }>): void => { + queue.push(step); + }; + /** Follows one forwarded name to the module that declares it, or records it as unbounded proof. */ + const forward = (fromFile: string, exported: string, target: string): void => { + const spec = surfaces.get(fromFile)?.forwarded.get(exported)?.spec; + if (spec === undefined) { + execExports.add(exported); + return; + } + const resolved = resolve(fromFile, spec); + if (resolved === undefined || !surfaces.has(resolved)) { + // A forwarded name whose source the index cannot follow: nothing proves it loads no exec root. + execExports.add(exported); + return; + } + push({ file: resolved, name: target }); + }; + const start = surfaces.get(entry); + if (start?.starReexport) unbounded = true; + for (const name of start?.declared ?? []) push({ file: entry, name }); + for (const [exported, forwarded] of start?.forwarded ?? []) + forward(entry, exported, forwarded.name); + for (let head = 0; head < queue.length; head += 1) { + const step = queue[head]!; + const key = `${step.file}#${step.name}`; + if (seen.has(key)) continue; + seen.add(key); + const surface = surfaces.get(step.file); + if (!surface) { + execExports.add(step.name); + continue; + } + if (surface.starReexport) unbounded = true; + if (surface.declared.has(step.name)) { + (escapes(step.file) ? execExports : pureExports).add(step.name); + continue; + } + // A type export costs the bundle nothing at runtime, so it belongs to neither set. + if (surface.typeExports.has(step.name)) continue; + const forwarded = surface.forwarded.get(step.name); + if (!forwarded) { + // The subpath publishes a name this module neither declares nor forwards: its declaration site + // is outside the index, so nothing proves it loads no exec root. + execExports.add(step.name); + continue; + } + forward(step.file, step.name, forwarded.name); + } + return { specifier, entry, pureExports, execExports, unbounded }; +} + +/** + * The names of a runtime import that the subpath's derived allowlist does not vouch for: each one loads + * the exec or diagnostic layer through the plugin's bundled copy, or is not an export at all and so has + * no declaration the graph could vouch for. + */ +export function hostKitSymbolsReachingExec( + surface: HostKitScopeSurface, + symbols: readonly string[], +): readonly string[] { + // An import that names no export — a namespace import, a bare import, or a dynamic import that does + // not destructure — binds every export of the subpath, so it is refused when any export is not on the + // allowlist, and refused outright when the subpath re-exports a namespace the index cannot bound. + if (symbols.length === 0) { + const unvouched = [...surface.execExports]; + if (unvouched.length > 0 || surface.unbounded) return unvouched.sort().concat('*'); + return []; + } + // A named import is safe only when the graph proves that name's declaration loads neither root. + return symbols.filter((name) => !surface.pureExports.has(name)); +} + +/** The host-kit production sources of a scan input. */ +export function hostKitSources(sources: ReadonlyMap): ReadonlyMap { + const subset = new Map(); + for (const [file, source] of sources) { + if (isHostKitProductionSource(file)) subset.set(file, source); + } + return subset; +} + +/** + * The public subpath entries of host-kit, read from the sources: every top-level module of + * `packages/host-kit/src` is published under its own name. The scan input is the source of truth, so + * the rule keeps no second list of subpaths. + */ +export function hostKitPublicEntries( + sources: ReadonlyMap, +): ReadonlyMap { + const entries = new Map(); + for (const file of sources.keys()) { + if (!isHostKitProductionSource(file)) continue; + const subpath = file.slice(HOST_KIT_SOURCE_ROOT.length); + if (subpath.includes('/')) continue; + entries.set(`${HOST_KIT_SPECIFIER_PREFIX}${subpath.slice(0, -'.ts'.length)}`, file); + } + return entries; +} + +function isHostKitProductionSource(file: string): boolean { + if (!file.startsWith(HOST_KIT_SOURCE_ROOT) || !file.endsWith('.ts')) return false; + const relative = file.slice(HOST_KIT_SOURCE_ROOT.length); + return ( + !relative.includes('__tests__') && + !relative.endsWith('.test.ts') && + !relative.includes('.fixtures.') && + !relative.endsWith('fixtures.ts') + ); +} + +/** Reads one module's runtime imports and its exported value, type and forwarded names. */ +function readModuleSurface(source: string): ModuleSurface { + const parsed = parseSync('host-kit-surface.ts', source); + if (parsed.errors.length > 0) { + throw new SyntaxError( + `Cannot parse host-kit surface: ${parsed.errors.map(({ message }) => message).join('; ')}`, + ); + } + const edges = parseImports(source); + const imports = edges.filter((edge) => !edge.typeOnly).map((edge) => edge.spec); + // A name this module imported and then re-exports was declared elsewhere; its declaration site is + // the specifier of that import. + const importedFrom = new Map>(); + for (const edge of edges) { + for (const name of edge.symbols) importedFrom.set(name, { spec: edge.spec, name }); + } + const declared = new Set(); + const typeExports = new Set(); + const forwarded = new Map>(); + let starReexport = false; + for (const statement of nodeList(asNode(parsed.program)?.body)) { + const node = asNode(statement); + if (!node) continue; + if (node.type === 'ExportAllDeclaration') { + if (node.exportKind !== 'type') starReexport = true; + continue; + } + if (node.type !== 'ExportNamedDeclaration') continue; + const spec = stringLiteral(node.source); + const specifiers = nodeList(node.specifiers); + if (spec !== undefined) { + for (const name of exportedNames(specifiers, 'local')) { + forwarded.set(name.exported, { spec, name: name.local }); + } + continue; + } + const declaration = asNode(node.declaration); + if (!declaration) { + for (const name of exportedNames(specifiers, 'local')) { + const binding = importedFrom.get(name.local); + if (binding) forwarded.set(name.exported, binding); + else declared.add(name.exported); + } + continue; + } + const isTypeOnly = + declaration.type === 'TSTypeAliasDeclaration' || + declaration.type === 'TSInterfaceDeclaration' || + declaration.type === 'TSEnumDeclaration' || + declaration.type === 'TSModuleDeclaration'; + for (const name of declaredNames(declaration)) (isTypeOnly ? typeExports : declared).add(name); + continue; + } + return { imports, declared, typeExports, forwarded, starReexport }; +} + +function exportedNames( + specifiers: readonly unknown[], + localField: 'local', +): Readonly<{ exported: string; local: string }>[] { + return specifiers.flatMap((value) => { + const specifier = asNode(value); + if (!specifier || specifier.exportKind === 'type') return []; + const local = propertyName(specifier[localField]); + const exported = propertyName(specifier.exported) ?? local; + return local === undefined || exported === undefined ? [] : [{ exported, local }]; + }); +} + +function declaredNames(declaration: AstNode): string[] { + if (declaration.type === 'VariableDeclaration') { + return nodeList(declaration.declarations).flatMap((value) => patternNames(asNode(value)?.id)); + } + const name = propertyName(declaration.id); + return name === undefined ? [] : [name]; +} + +function patternNames(node: unknown): string[] { + const pattern = asNode(node); + if (!pattern) return []; + if (pattern.type === 'Identifier') { + const name = propertyName(pattern.name); + return name === undefined ? [] : [name]; + } + if (pattern.type === 'ObjectPattern') { + return nodeList(pattern.properties).flatMap((value) => { + const property = asNode(value); + if (!property) return []; + return patternNames(property.type === 'RestElement' ? property.argument : property.value); + }); + } + if (pattern.type === 'ArrayPattern') return nodeList(pattern.elements).flatMap(patternNames); + if (pattern.type === 'AssignmentPattern') return patternNames(pattern.left); + if (pattern.type === 'RestElement') return patternNames(pattern.argument); + return []; +} + +function asNode(value: unknown): AstNode | undefined { + if (value === null || typeof value !== 'object') return undefined; + const record = value as Record; + return typeof record.type === 'string' ? (record as AstNode) : undefined; +} + +function stringLiteral(node: unknown): string | undefined { + const source = asNode(node); + return typeof source?.value === 'string' ? source.value : undefined; +} + +/** Joins a relative specifier with the file that wrote it, in repo-root-relative posix form. */ +export function resolveRelativeSource(fromFile: string, spec: string): string | undefined { + if (!spec.startsWith('.')) return undefined; + return path.posix.normalize(path.posix.join(path.posix.dirname(fromFile), spec)); +} diff --git a/scripts/layering/model.test.ts b/scripts/layering/model.test.ts index 7eac66c39f..8070b5b0fe 100644 --- a/scripts/layering/model.test.ts +++ b/scripts/layering/model.test.ts @@ -76,6 +76,43 @@ test('parseImports distinguishes value, type-only, dynamic, and value re-export ); }); +test('parseImports marks the names written with a per-specifier type marker', () => { + const edges = parseImports( + [ + "import { type HostProcessInfo, readProcessIdentities } from './host-process.ts';", + "import type { OwnedProcessRecordStore } from './store.ts';", + "import * as hostProcess from './namespace.ts';", + ].join('\n'), + ); + + assert.deepEqual( + edges.map(({ spec, typeOnly, symbols, typeSymbols }) => ({ + spec, + typeOnly, + symbols, + typeSymbols, + })), + [ + // One erased name and one real one: what the import loads is the real one alone. + { + spec: './host-process.ts', + typeOnly: false, + symbols: ['HostProcessInfo', 'readProcessIdentities'], + typeSymbols: ['HostProcessInfo'], + }, + // Every name erased: the edge is type-only, and `symbols` still names them. + { + spec: './store.ts', + typeOnly: true, + symbols: ['OwnedProcessRecordStore'], + typeSymbols: [], + }, + // A namespace import binds whatever the module exports, marked or not. + { spec: './namespace.ts', typeOnly: false, symbols: [], typeSymbols: [] }, + ], + ); +}); + test('parseImports records TSImportType edges separately from dynamic imports', () => { const edges = parseImports( [ @@ -293,6 +330,7 @@ test('parseImports detects multiline dynamic imports', () => { typeOnly: false, line: 1, symbols: [], + typeSymbols: [], }, ]); }); @@ -307,6 +345,7 @@ test('parseImports resolves constant-template dynamic imports', () => { typeOnly: false, line: 1, symbols: [], + typeSymbols: [], }, ]); }); diff --git a/scripts/layering/model.ts b/scripts/layering/model.ts index 70d83714e6..16ad65329e 100644 --- a/scripts/layering/model.ts +++ b/scripts/layering/model.ts @@ -29,6 +29,14 @@ export type ImportEdge = { * dynamic imports that do not destructure named bindings. */ symbols: readonly string[]; + /** + * The `symbols` written with a per-specifier `type` marker (`import { type A, b } from …`). Those + * names are erased at runtime, so a rule that polices what an import loads judges the rest. An edge + * whose every name is like this is reported as `typeOnly`, and `symbols` still lists them: that list + * is what the name is called, not what is loaded. A caller that builds an edge by hand leaves it + * empty. + */ + typeSymbols?: readonly string[]; }; export type ResolvedImportEdge = ImportEdge & { @@ -191,18 +199,25 @@ function importedName(node: unknown): string | undefined { return record.type === 'Identifier' && typeof record.name === 'string' ? record.name : undefined; } +/** The named symbols of an import or re-export, and the subset marked `type` per specifier. */ function namedSymbols( specifiers: readonly Record[], importedField: 'imported' | 'local', -): string[] { - const symbols = specifiers.flatMap((specifier) => { +): Readonly<{ symbols: string[]; typeSymbols: string[] }> { + const kindField = importedField === 'imported' ? 'importKind' : 'exportKind'; + const names = specifiers.flatMap((specifier) => { const name = importedName(specifier[importedField]); - return specifier.type === - (importedField === 'imported' ? 'ImportSpecifier' : 'ExportSpecifier') && name !== undefined - ? [name] + const isNamed = + specifier.type === (importedField === 'imported' ? 'ImportSpecifier' : 'ExportSpecifier'); + return isNamed && name !== undefined + ? [{ name, typeOnly: specifier[kindField] === 'type' }] : []; }); - return [...new Set(symbols)]; + const unique = [...new Map(names.map((entry) => [entry.name, entry])).values()]; + return { + symbols: unique.map(({ name }) => name), + typeSymbols: unique.filter(({ typeOnly }) => typeOnly).map(({ name }) => name), + }; } function importTypeSourceName(qualifier: unknown): string | undefined { @@ -226,7 +241,7 @@ function staticImportEdge( node: Record, specifierNode: unknown, typeOnly: boolean, - symbols: string[], + names: Readonly<{ symbols: string[]; typeSymbols: string[] }>, ): ImportEdge | null { const spec = literalSpecifier(specifierNode); if (spec === undefined) return null; @@ -236,7 +251,8 @@ function staticImportEdge( dynamic: false, typeOnly, line: sourceLine(source, start), - symbols, + symbols: names.symbols, + typeSymbols: names.typeSymbols, }; } @@ -264,6 +280,7 @@ export function parseImports(source: string): ImportEdge[] { typeOnly: false, line: sourceLine(source, start), symbols: capture ? [...capture.symbols] : [], + typeSymbols: [], }, }); return; @@ -293,16 +310,16 @@ export function parseImports(source: string): ImportEdge[] { namedSymbols(specifiers, 'local'), ); } else if (node.type === 'ExportAllDeclaration') { - edge = staticImportEdge(source, node, node.source, node.exportKind === 'type', []); + edge = staticImportEdge(source, node, node.source, node.exportKind === 'type', { + symbols: [], + typeSymbols: [], + }); } else if (node.type === 'TSImportType') { const sourceName = importTypeSourceName(node.qualifier); - edge = staticImportEdge( - source, - node, - node.source, - true, - sourceName === undefined ? [] : [sourceName], - ); + edge = staticImportEdge(source, node, node.source, true, { + symbols: sourceName === undefined ? [] : [sourceName], + typeSymbols: sourceName === undefined ? [] : [sourceName], + }); } if (edge) located.push({ edge, start }); }); diff --git a/scripts/layering/platform-package-policy.fixtures.ts b/scripts/layering/platform-package-policy.fixtures.ts new file mode 100644 index 0000000000..006c391cee --- /dev/null +++ b/scripts/layering/platform-package-policy.fixtures.ts @@ -0,0 +1,159 @@ +// The scan input the managed-platform rules are judged against: package declarations and platform +// sources a compliant tree produces, plus the host-kit sources of this checkout. Both the package +// policy and the exec-reachability derivation need one fixture set, so a fixture that stops being +// compliant fails the same way in either test. + +import fs from 'node:fs'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { + CANONICAL_PLATFORM_FAMILIES, + checkPlatformPackagePolicy, + type PlatformPackageDeclaration, +} from './platform-package-policy.ts'; +import { hostKitSources } from './host-kit-runtime-reach.ts'; + +const inventoryModuleNames = { + apple: 'appleInventoryModule', + android: 'androidInventoryModule', + harmonyos: 'harmonyosInventoryModule', + vega: 'vegaInventoryModule', + linux: 'linuxInventoryModule', + web: 'webInventoryModule', +} as const; + +export const MANAGED_FAMILIES = ['web', 'vega', 'harmonyos', 'linux'] as const; + +export function isManagedFamily(family: string): boolean { + return (MANAGED_FAMILIES as readonly string[]).includes(family); +} + +function managedPackageName(family: string): string { + return `@agent-device/${family}`; +} + +export function declarations(): PlatformPackageDeclaration[] { + return CANONICAL_PLATFORM_FAMILIES.map((family) => ({ + dir: `packages/platform-${family}`, + family, + name: isManagedFamily(family) ? managedPackageName(family) : `@agent-device/platform-${family}`, + ...(isManagedFamily(family) + ? { + managedClaim: { platform: family, apiVersion: 3 }, + publishedSubpaths: ['./agent-device'], + } + : {}), + private: true, + exportedSubpaths: + family === 'apple' + ? [ + '@agent-device/platform-apple', + '@agent-device/platform-apple/app-lifecycle', + '@agent-device/platform-apple/app-resolution', + '@agent-device/platform-apple/debug-symbols', + '@agent-device/platform-apple/doctor', + '@agent-device/platform-apple/install-artifact', + '@agent-device/platform-apple/macos', + '@agent-device/platform-apple/perf', + '@agent-device/platform-apple/physical-device', + '@agent-device/platform-apple/runner/operations', + '@agent-device/platform-apple/runner-owner', + '@agent-device/platform-apple/session-observation', + '@agent-device/platform-apple/simctl', + '@agent-device/platform-apple/snapshot-source', + '@agent-device/platform-apple/simulator', + '@agent-device/platform-apple/simulator-boot', + '@agent-device/platform-apple/tool-provider', + ] + : family === 'android' + ? [ + '@agent-device/platform-android', + '@agent-device/platform-android/adb-host', + '@agent-device/platform-android/device-boot', + '@agent-device/platform-android/mechanics', + '@agent-device/platform-android/snapshot-capture-fixtures', + '@agent-device/platform-android/ui-hierarchy-fixtures', + ] + : isManagedFamily(family) + ? [`${managedPackageName(family)}/agent-device`] + : [`@agent-device/platform-${family}`], + })); +} + +export function facade(family: (typeof CANONICAL_PLATFORM_FAMILIES)[number]): string { + return [ + "import type { DeviceInventoryHost, InventoryPlatformModule, PlatformModuleMetadata } from '@agent-device/contracts/platform';", + 'const metadata = Object.freeze({', + ` family: '${family}',`, + '} satisfies PlatformModuleMetadata);', + 'export const inventoryModule = Object.freeze({', + ' ...metadata,', + ' loadInventory: async (host: DeviceInventoryHost) => {', + " const { createInventory } = await import('./inventory.ts');", + ' return createInventory(host);', + ' },', + '} satisfies InventoryPlatformModule);', + ].join('\n'); +} + +export function composition(families = CANONICAL_PLATFORM_FAMILIES): string { + return [ + "import { createPlatformModuleRegistry } from '@agent-device/contracts/platform';", + ...families.map( + (family) => + `import { inventoryModule as ${inventoryModuleNames[family]} } from '@agent-device/platform-${family}';`, + ), + 'export const platformModuleRegistry = createPlatformModuleRegistry([', + ...families.map((family) => ` ${inventoryModuleNames[family]},`), + ']);', + ].join('\n'); +} + +/** The sources a compliant tree of every canonical family produces. */ +export function validSources(): Map { + return new Map([ + ['src/platform-runtime.ts', composition()], + ...CANONICAL_PLATFORM_FAMILIES.map( + (family) => [`packages/platform-${family}/src/index.ts`, facade(family)] as const, + ), + ]); +} + +/** + * Every host-kit source of this checkout, so the exec-reachability rule is derived from the graph that + * decides it rather than assumed. A managed package's host-kit import is only answerable when the scan + * can see what host-kit loads. + */ +export function checkoutHostKitSources(): ReadonlyMap { + const root = fileURLToPath(new URL('../../packages/host-kit/src', import.meta.url)); + const all = new Map(); + for (const relative of fs.readdirSync(root, { recursive: true })) { + const name = String(relative); + if (!name.endsWith('.ts')) continue; + all.set( + `packages/host-kit/src/${name.split(path.sep).join('/')}`, + fs.readFileSync(path.join(root, name), 'utf8'), + ); + } + return hostKitSources(all); +} + +const HOST_KIT = checkoutHostKitSources(); + +/** Options that let the reach rule answer: the scan sees the host-kit graph it derives from. */ +export function policyOptions(): { hostKitSources: ReadonlyMap } { + return { hostKitSources: HOST_KIT }; +} + +/** The host-kit findings one managed family's new file earns, as one string to match against. */ +export function hostKitFindings(family: string, source: string): string { + const file = `packages/platform-${family}/src/new-surface.ts`; + return checkPlatformPackagePolicy( + new Map([...validSources(), [file, source]]), + declarations(), + policyOptions(), + ) + .map((violation) => violation.message) + .filter((message) => message.includes('host-kit')) + .join('\n'); +} diff --git a/scripts/layering/platform-package-policy.test.ts b/scripts/layering/platform-package-policy.test.ts index 192372d553..50bc3b7032 100644 --- a/scripts/layering/platform-package-policy.test.ts +++ b/scripts/layering/platform-package-policy.test.ts @@ -5,123 +5,27 @@ import { CANONICAL_PLATFORM_FAMILIES, checkPlatformPackagePolicy, checkRetiredPlatformsZone, - type PlatformPackageDeclaration, } from './platform-package-policy.ts'; +import { + MANAGED_FAMILIES, + composition, + declarations, + facade, + hostKitFindings, + isManagedFamily, + policyOptions, + validSources, +} from './platform-package-policy.fixtures.ts'; import { classifyZone } from './model.ts'; -const inventoryModuleNames = { - apple: 'appleInventoryModule', - android: 'androidInventoryModule', - harmonyos: 'harmonyosInventoryModule', - vega: 'vegaInventoryModule', - linux: 'linuxInventoryModule', - web: 'webInventoryModule', -} as const; - -const MANAGED_FAMILIES = ['web', 'vega', 'harmonyos', 'linux'] as const; - -function isManagedFamily(family: string): boolean { - return (MANAGED_FAMILIES as readonly string[]).includes(family); -} - -function managedPackageName(family: string): string { - return `@agent-device/${family}`; -} - -function declarations(): PlatformPackageDeclaration[] { - return CANONICAL_PLATFORM_FAMILIES.map((family) => ({ - dir: `packages/platform-${family}`, - family, - name: isManagedFamily(family) ? managedPackageName(family) : `@agent-device/platform-${family}`, - ...(isManagedFamily(family) - ? { - managedClaim: { platform: family, apiVersion: 3 }, - publishedSubpaths: ['./agent-device'], - } - : {}), - private: true, - exportedSubpaths: - family === 'apple' - ? [ - '@agent-device/platform-apple', - '@agent-device/platform-apple/app-lifecycle', - '@agent-device/platform-apple/app-resolution', - '@agent-device/platform-apple/debug-symbols', - '@agent-device/platform-apple/doctor', - '@agent-device/platform-apple/install-artifact', - '@agent-device/platform-apple/macos', - '@agent-device/platform-apple/perf', - '@agent-device/platform-apple/physical-device', - '@agent-device/platform-apple/runner/operations', - '@agent-device/platform-apple/runner-owner', - '@agent-device/platform-apple/session-observation', - '@agent-device/platform-apple/simctl', - '@agent-device/platform-apple/snapshot-source', - '@agent-device/platform-apple/simulator', - '@agent-device/platform-apple/simulator-boot', - '@agent-device/platform-apple/tool-provider', - ] - : family === 'android' - ? [ - '@agent-device/platform-android', - '@agent-device/platform-android/adb-host', - '@agent-device/platform-android/device-boot', - '@agent-device/platform-android/mechanics', - '@agent-device/platform-android/snapshot-capture-fixtures', - '@agent-device/platform-android/ui-hierarchy-fixtures', - ] - : isManagedFamily(family) - ? [`${managedPackageName(family)}/agent-device`] - : family === 'linux' - ? [`@agent-device/platform-${family}`, `@agent-device/platform-${family}/interactor`] - : [`@agent-device/platform-${family}`], - })); -} - -function facade(family: (typeof CANONICAL_PLATFORM_FAMILIES)[number]): string { - return [ - "import type { DeviceInventoryHost, InventoryPlatformModule, PlatformModuleMetadata } from '@agent-device/contracts/platform';", - 'const metadata = Object.freeze({', - ` family: '${family}',`, - '} satisfies PlatformModuleMetadata);', - 'export const inventoryModule = Object.freeze({', - ' ...metadata,', - ' loadInventory: async (host: DeviceInventoryHost) => {', - " const { createInventory } = await import('./inventory.ts');", - ' return createInventory(host);', - ' },', - '} satisfies InventoryPlatformModule);', - ].join('\n'); -} - -function composition(families = CANONICAL_PLATFORM_FAMILIES): string { - return [ - "import { createPlatformModuleRegistry } from '@agent-device/contracts/platform';", - ...families.map( - (family) => - `import { inventoryModule as ${inventoryModuleNames[family]} } from '@agent-device/platform-${family}';`, - ), - 'export const platformModuleRegistry = createPlatformModuleRegistry([', - ...families.map((family) => ` ${inventoryModuleNames[family]},`), - ']);', - ].join('\n'); -} - -function validSources(): Map { - return new Map([ - ['src/platform-runtime.ts', composition()], - ...CANONICAL_PLATFORM_FAMILIES.map( - (family) => [`packages/platform-${family}/src/index.ts`, facade(family)] as const, - ), - ]); -} - function messages(sources: ReadonlyMap, packages = declarations()): string[] { - return checkPlatformPackagePolicy(sources, packages).map((violation) => violation.message); + return checkPlatformPackagePolicy(sources, packages, policyOptions()).map( + (violation) => violation.message, + ); } test('the inventory substrate has six private lazy packages and one exact composition root', () => { - assert.deepEqual(checkPlatformPackagePolicy(validSources(), declarations()), []); + assert.deepEqual(checkPlatformPackagePolicy(validSources(), declarations(), policyOptions()), []); }); test('retired platform family implementations are rejected from src/platforms', () => { @@ -154,6 +58,7 @@ test('capture-kit and platform workspace packages are R11-owned unranked zones', test('untracked production TypeScript makes committed-state evidence fail closed', () => { const found = checkPlatformPackagePolicy(validSources(), declarations(), { + ...policyOptions(), untrackedProductionFiles: ['packages/platform-apple/src/mechanics.ts'], }); assert.match(found.map(({ message }) => message).join('\n'), /untracked production source/); @@ -190,7 +95,7 @@ test('composition policy does not pin local platform-module identifier spelling' 'src/platform-runtime.ts', composition().replaceAll('appleInventoryModule', 'selectedAppleModule'), ); - assert.deepEqual(checkPlatformPackagePolicy(sources, declarations()), []); + assert.deepEqual(checkPlatformPackagePolicy(sources, declarations(), policyOptions()), []); }); test('external consumers use root facades with static imports only at the interactor seam', () => { @@ -279,7 +184,7 @@ test('external consumers use root facades with static imports only at the intera 'src/platform-runtime/request-providers.ts', "void import('@agent-device/platform-web');", ); - assert.deepEqual(checkPlatformPackagePolicy(governed, declarations()), []); + assert.deepEqual(checkPlatformPackagePolicy(governed, declarations(), policyOptions()), []); }); test('only the canonical composition root may import the private provider composition submodule', () => { @@ -289,7 +194,7 @@ test('only the canonical composition root may import the private provider compos composition() + "\nvoid import('./platform-runtime/request-providers.ts');", ); sources.set('src/platform-runtime/request-providers.ts', 'export const providerScope = true;'); - assert.deepEqual(checkPlatformPackagePolicy(sources, declarations()), []); + assert.deepEqual(checkPlatformPackagePolicy(sources, declarations(), policyOptions()), []); sources.set( 'packages/daemon/src/server/request-router.ts', @@ -321,7 +226,7 @@ test('the apple runner mechanics facet subpaths are the enumerated exception', ( 'packages/daemon/src/execution/__tests__/selector-runtime.test.ts', "import { withAppleRunnerProvider } from '@agent-device/apple-runner';", ); - assert.deepEqual(checkPlatformPackagePolicy(sources, declarations()), []); + assert.deepEqual(checkPlatformPackagePolicy(sources, declarations(), policyOptions()), []); // Any other production file, or a named root consumer that evaluates it, is refused. const refused = validSources(); @@ -388,7 +293,7 @@ test('the Apple domain facades preserve synchronous helpers without widening the '@agent-device/platform-apple/tool-provider', ]) { sources.set('src/platform-runtime-domain-facade.ts', `import '${specifier}';`); - assert.deepEqual(checkPlatformPackagePolicy(sources, declarations()), []); + assert.deepEqual(checkPlatformPackagePolicy(sources, declarations(), policyOptions()), []); sources.delete('src/platform-runtime-domain-facade.ts'); } @@ -413,7 +318,7 @@ test('the runner mechanics facet is exempt from ambient-host and raw-process rul '\n', ), ); - assert.deepEqual(checkPlatformPackagePolicy(sources, declarations()), []); + assert.deepEqual(checkPlatformPackagePolicy(sources, declarations(), policyOptions()), []); // ...but spawning stays banned: process execution goes through the host port. sources.set( @@ -432,7 +337,7 @@ test('the runner mechanics facet is exempt from ambient-host and raw-process rul 'packages/apple-runner/src/__tests__/runner-xctestrun.test.ts', "import { execFileSync } from 'node:child_process';", ); - assert.deepEqual(checkPlatformPackagePolicy(allowed, declarations()), []); + assert.deepEqual(checkPlatformPackagePolicy(allowed, declarations(), policyOptions()), []); }); test('platform packages may import the xml vocabulary package', () => { @@ -441,7 +346,7 @@ test('platform packages may import the xml vocabulary package', () => { 'packages/apple-runner/src/runner-usbmux.ts', "import { parseXml } from '@agent-device/xml';", ); - assert.deepEqual(checkPlatformPackagePolicy(sources, declarations()), []); + assert.deepEqual(checkPlatformPackagePolicy(sources, declarations(), policyOptions()), []); }); test('the Android mechanics facet is the named consumer seam and adb host wiring is limited to the root binding and daemon composition', () => { @@ -560,7 +465,7 @@ test('platform packages may use capture-kit but no unrelated workspace implement 'packages/platform-apple/src/probe.test.ts', "import { createAppLogLiveHandle } from '@agent-device/capture-kit';", ); - assert.deepEqual(checkPlatformPackagePolicy(allowed, declarations()), []); + assert.deepEqual(checkPlatformPackagePolicy(allowed, declarations(), policyOptions()), []); for (const specifier of [ '@agent-device/selectors', @@ -585,7 +490,7 @@ test('platform-web production source may use only the canonical positional-ref s 'packages/platform-web/src/interactor.ts', "import { stripAtPrefix } from '@agent-device/selectors/interaction-positionals';", ); - assert.deepEqual(checkPlatformPackagePolicy(allowed, declarations()), []); + assert.deepEqual(checkPlatformPackagePolicy(allowed, declarations(), policyOptions()), []); for (const [file, specifier] of [ ['packages/platform-web/src/interactor.ts', '@agent-device/selectors'], @@ -623,7 +528,7 @@ test('the web interactor subpath is loaded only by the builtin registry, dynamic 'src/core/interactors/register-builtins.ts', `const load = () => import('@agent-device/platform-${family}/interactor');`, ); - assert.deepEqual(checkPlatformPackagePolicy(allowed, declarations()), [], family); + assert.deepEqual(checkPlatformPackagePolicy(allowed, declarations(), policyOptions()), [], family); for (const [file, source] of [ [ @@ -679,7 +584,7 @@ test('platform package tests may import test-kit, production source may not', () 'packages/platform-apple/src/probe.spec.ts', "import { mkdtempForTest } from '@agent-device/test-kit';", ); - assert.deepEqual(checkPlatformPackagePolicy(tests, declarations()), []); + assert.deepEqual(checkPlatformPackagePolicy(tests, declarations(), policyOptions()), []); const production = validSources(); production.set( @@ -698,7 +603,7 @@ test('package-owned tests may import their own public facade', () => { 'packages/platform-apple/src/index.test.ts', "import { inventoryModule } from '@agent-device/platform-apple';", ); - assert.deepEqual(checkPlatformPackagePolicy(sources, declarations()), []); + assert.deepEqual(checkPlatformPackagePolicy(sources, declarations(), policyOptions()), []); }); test('platform facades cannot evaluate mechanics eagerly', () => { @@ -717,7 +622,7 @@ test('platform facades cannot evaluate mechanics eagerly', () => { 'packages/platform-apple/src/index.ts', `${facade('apple')}\nexport const loadApple = () => import('./implementation.ts');`, ); - assert.deepEqual(checkPlatformPackagePolicy(sources, declarations()), []); + assert.deepEqual(checkPlatformPackagePolicy(sources, declarations(), policyOptions()), []); }); test('composition policy does not infer host authority from function or class names', () => { @@ -726,7 +631,7 @@ test('composition policy does not infer host authority from function or class na 'src/platform-runtime.ts', `${composition()}\nclass AppleHelperManager {}\nnew AppleHelperManager();\nprobeAndroidSdk();`, ); - assert.deepEqual(checkPlatformPackagePolicy(sources, declarations()), []); + assert.deepEqual(checkPlatformPackagePolicy(sources, declarations(), policyOptions()), []); }); test('composition keeps platform implementation loaders behind selected use', () => { @@ -888,7 +793,7 @@ test('platform packages may import the provision-kit substrate', () => { 'packages/platform-apple/src/install.ts', "import { resolveInstallSource } from '@agent-device/provision-kit/install-source';", ); - assert.deepEqual(checkPlatformPackagePolicy(sources, declarations()), []); + assert.deepEqual(checkPlatformPackagePolicy(sources, declarations(), policyOptions()), []); }); test('a provision-kit import of a concrete platform package fails closed', () => { @@ -898,7 +803,7 @@ test('a provision-kit import of a concrete platform package fails closed', () => "import { runtimeModule } from '@agent-device/platform-android';", ); assert.match( - checkPlatformPackagePolicy(sources, declarations()) + checkPlatformPackagePolicy(sources, declarations(), policyOptions()) .map(({ message }) => message) .join('\n'), /may import '@agent-device\/platform-android'/, @@ -960,20 +865,94 @@ test('a type-only host-kit import stays legal in a managed platform package', () ], ]); assert.deepEqual( - checkPlatformPackagePolicy(sources, declarations()).filter((violation) => + checkPlatformPackagePolicy(sources, declarations(), policyOptions()).filter((violation) => violation.message.includes('host-kit'), ), [], ); }); -/** The host-kit findings one managed family's new file earns, as one string to match against. */ -function hostKitFindings(family: string, source: string): string { - const file = `packages/platform-${family}/src/new-surface.ts`; - const found = messages(new Map([...validSources(), [file, source]])); - return found.filter((message) => message.includes('host-kit')).join('\n'); +// The same rule covers the scopes the hand-kept list never enumerated, with no second list: the file +// scope's lock mechanics are refused for the same reason the process scope's probes are, because the +// host-kit graph shows they reach `internal/exec.ts` through the bundled copy. +for (const family of ['web', 'vega', 'harmonyos'] as const) { + test(`a managed platform package may not take the process lock through its own host-kit copy (${family})`, () => { + const found = hostKitFindings( + family, + "import { acquireProcessLock, withProcessLock } from '@agent-device/host-kit/file';\nvoid acquireProcessLock; void withProcessLock;", + ); + assert.match( + found, + new RegExp( + String.raw`@agent-device/${family} may not import the host-kit '@agent-device/host-kit/file' scope at runtime \(acquireProcessLock, withProcessLock\): .*PlatformHost given to setup`, + ), + ); + }); } +// One name's verdict follows its own declaration: the liveness classifier reaches the exec layer and +// is refused, while the pid arithmetic declared beside it in the same module graph does not. +test('the host-kit process scope is judged name by name, not per subpath', () => { + const refused = hostKitFindings( + 'web', + "import { classifyOwnerLivenessFromObservation } from '@agent-device/host-kit/process';\nvoid classifyOwnerLivenessFromObservation;", + ); + assert.match( + refused, + /host-kit\/process' scope at runtime \(classifyOwnerLivenessFromObservation\)/, + ); + const allowed = hostKitFindings( + 'web', + "import { uniquePositivePids } from '@agent-device/host-kit/process';\nvoid uniquePositivePids;", + ); + assert.equal(allowed, ''); +}); + +// Nothing about an export's name is consulted, so a new export that starts loading the exec layer is +// caught without anyone editing a list: the same import turns from allowed to refused on the edit. +test('the exec reachability of a host-kit export is derived, not declared', () => { + const entryPath = 'packages/host-kit/src/alpha.ts'; + const helperPath = 'packages/host-kit/src/internal/alpha-helper.ts'; + const execPath = 'packages/host-kit/src/internal/exec.ts'; + const importSource = "import { pureProbe } from '@agent-device/host-kit/alpha';\nvoid pureProbe;"; + const scan = (helperSource: string) => { + const sources = new Map([ + [entryPath, "export { pureProbe } from './internal/alpha-helper.ts';"], + [helperPath, helperSource], + [execPath, 'export function runCmd(): void {}\n'], + ['packages/platform-web/src/new-surface.ts', importSource], + ]); + return checkPlatformPackagePolicy(sources, declarations(), { hostKitSources: sources }).filter( + (violation) => violation.message.includes('may not import the host-kit'), + ); + }; + + assert.deepEqual(scan('export function pureProbe(): number {\n return 1;\n}\n'), []); + + // The same export name, now declared by a module that loads the exec layer. + const flagged = scan( + "import { runCmd } from './exec.ts';\nexport function pureProbe(): void {\n runCmd();\n}\n", + ); + assert.equal(flagged.length, 1); + assert.match( + flagged[0]!.message, + /host-kit\/alpha' scope at runtime \(pureProbe\): .*PlatformHost given to setup/, + ); +}); + +// A root the derivation walks has to be in the scan: a move of either would otherwise answer +// "no export reaches the exec layer" for every managed plugin at once. +test('a missing exec-root source makes the derivation fail closed', () => { + const sources = new Map([ + ['packages/host-kit/src/alpha.ts', 'export function pureProbe(): number {\n return 1;\n}\n'], + ]); + const found = checkPlatformPackagePolicy(sources, declarations(), { hostKitSources: sources }); + assert.match( + found.map(({ message }) => message).join('\n'), + /stale module: packages\/host-kit\/src\/internal\/exec\.ts is not a tracked source/, + ); +}); + // `host-kit/process` is policed export by export: an export that spawns a process tool escapes the // request's exec trace from a bundled plugin, and one that reads only this process's globals cannot. // `PlatformHost.processes` answers the first kind on the core's own copy. An edge naming no export diff --git a/scripts/layering/platform-package-policy.ts b/scripts/layering/platform-package-policy.ts index 412524e503..84c368353d 100644 --- a/scripts/layering/platform-package-policy.ts +++ b/scripts/layering/platform-package-policy.ts @@ -18,6 +18,17 @@ import path from 'node:path'; import { DAEMON_SOURCE_ROOT, isProductionSourceFile } from './tracked-sources.ts'; import { PLATFORMS } from '@agent-device/kernel/device'; import { parseImports, type LayeringViolation } from './model.ts'; +import { + HOST_KIT_EXEC_ROOTS, + HOST_KIT_SPECIFIER_PREFIX, + hostKitSources, + hostKitPublicEntries, + hostKitSymbolsReachingExec, + indexHostKitReach, + resolveRelativeSource, + type HostKitReachIndex, +} from './host-kit-runtime-reach.ts'; +import { staleReachModules } from './process-reach.ts'; import { APPLE_RUNNER_DIR, APPLE_RUNNER_PACKAGE, @@ -116,95 +127,72 @@ const MANAGED_PLATFORMS: Readonly>> = { }; /** - * One host-kit surface a managed platform package may not reach at runtime, with the exports that - * make it dangerous. `execExports` absent means every runtime export of the scope is; a scope with - * them is policed export by export, because most of its exports read no process at all. + * The host-kit surfaces a managed platform package may not reach at runtime. Which exported names of a + * subpath are dangerous is not listed here: it is derived from the host-kit module graph by + * `host-kit-runtime-reach.ts`, so an export that starts loading `internal/exec.ts` or + * `internal/diagnostics.ts` — through its own import or through a new one added to a module it already + * used — is caught without an entry being edited here. */ -type ManagedHostKitScope = Readonly<{ - specifier: string; - execExports?: readonly string[]; -}>; -// The host-kit scopes a managed platform package must never reach at runtime, and the -// `host-kit/process` exports among them that spawn a process tool. Each of those answers through the -// exec layer — `ps`, PowerShell, `osascript`, `sysctl` — and a managed plugin is bundled with its own -// copy of host-kit, so the daemon's command-host and diagnostic scopes never enter that copy: a spawn -// or trace made through it runs with the daemon process environment, outside the request's captured -// environment and exec trace. A managed plugin therefore binds to the `PlatformHost` its `setup` -// receives, whose `processes` facet answers these same reads on the core's own copy. +// No host-kit scope is listed: the rule is derived, so every scope is policed, `process`, `file`, +// `command`, `diagnostics`, `retry` and any scope added later. // -// The rest of `host-kit/process` stays reachable: `hostPlatform`, `hostProcessId`, -// `hostNodeExecutablePath`, `isProcessAlive`, `expandProcessTree` and `processStartTimesDiffer` read -// this process's own globals or compute from what the caller already holds, so they cannot escape the -// request's scope. Type-only edges are allowed anywhere — they cost the bundle nothing. -const MANAGED_HOST_KIT_SCOPES: readonly ManagedHostKitScope[] = [ - { specifier: '@agent-device/host-kit/command' }, - { specifier: '@agent-device/host-kit/diagnostics' }, - { - specifier: '@agent-device/host-kit/process', - // Every export of the scope that runs a process tool, directly or through one of these. Listed in - // source order so a violation names what the file reached for in the order it reads. - execExports: [ - 'readCurrentOwnerIdentity', - 'readProcessStartTime', - 'readProcessCommand', - 'isProcessZombie', - 'readHostCpuArch', - 'readHostCpuArchSync', - 'listHostProcesses', - 'readProcessIdentities', - 'readProcessIdentityFacts', - 'readHostProcessIdentityObservations', - 'readHostProcessIdentityObservationsAsync', - 'readProcessExecutablePaths', - 'stopProcessAndConfirmExit', - 'reapOwnedProcessRecordsAtStartup', - 'classifyOwnerLiveness', - 'classifyOwnerLivenessAsync', - ], - }, -]; - -// Every managed platform package is on the host: the web and Vega plugins joined HarmonyOS, and no -// file of any of them reaches one of these surfaces at runtime. A new managed family is therefore -// bound from its first commit, and a file that wants a host-kit command, diagnostic or process helper -// is a bug to fix at that file, not an entry to add here. -function managedHostKitScopeViolationMessage( - spec: string, - symbols: readonly string[], - managedName: string, -): string | undefined { - const scope = MANAGED_HOST_KIT_SCOPES.find( - (entry) => spec === entry.specifier || spec.startsWith(`${entry.specifier}/`), - ); - if (!scope) return undefined; - let reachedExports: string | undefined; - if (scope.execExports) { - // A runtime edge that names no export — a namespace or bare import — could reach any of them, - // so it is refused rather than assumed harmless. - const reached = - symbols.length === 0 - ? [...scope.execExports] - : scope.execExports.filter((name) => symbols.includes(name)); - if (reached.length === 0) return undefined; - reachedExports = reached.join(', '); - } - return ( - `${managedName} may not import the host-kit '${scope.specifier}' scope at runtime` + - (reachedExports === undefined ? '' : ` (${reachedExports})`) + - ': run the command, emit the diagnostic, or read processes through the PlatformHost given to ' + - 'setup, so the packed plugin stays inside the request environment and exec trace' - ); -} +// Why the graph decides this: a managed plugin is bundled with its own copy of host-kit, and the +// daemon's command-host and diagnostic scopes never enter that copy. A runtime import of a host-kit +// module that reaches the exec layer therefore answers with the daemon process environment, outside the +// request's captured environment and exec trace, and its diagnostics land in the bundle's own store +// rather than the request's log. A managed plugin binds to the `PlatformHost` its `setup` receives +// instead, whose `processes` facet answers those reads on the core's own copy. +// +// What stays importable is what the graph proves loads neither root: `hostPlatform`, `hostProcessId`, +// `hostNodeExecutablePath`, `isProcessAlive`, `expandProcessTree`, `processStartTimesDiffer`, +// `uniquePositivePids`, the retry timer, and every file helper. Type-only edges are allowed anywhere — +// they cost the bundle nothing. +const MANAGED_HOST_KIT_SCOPE_MESSAGE = + ': those exports load internal/exec.ts or internal/diagnostics.ts through the bundled copy, so run ' + + 'the command, emit the diagnostic, read processes, or take the lock through the PlatformHost given to ' + + 'setup, which answers inside the request environment and exec trace'; function managedHostKitScopeViolations( file: string, - site: { spec: string; line: number; typeOnly: boolean; symbols: readonly string[] }, + site: { + spec: string; + line: number; + typeOnly: boolean; + symbols: readonly string[]; + typeSymbols?: readonly string[]; + }, managedName: string, + reach: HostKitReachIndex, ): LayeringViolation[] { if (site.typeOnly) return []; - const message = managedHostKitScopeViolationMessage(site.spec, site.symbols, managedName); - return message === undefined ? [] : [violation(file, site.line, message)]; + // A name written as `type` is erased, so it is not part of what the import loads. + const bound = site.symbols.filter((name) => !(site.typeSymbols ?? []).includes(name)); + if (!site.spec.startsWith(HOST_KIT_SPECIFIER_PREFIX)) return []; + const surface = reach.surfaces.get(site.spec); + if (!surface) { + // A host-kit subpath the host-kit sources do not contain resolves outside this repository, so the + // bundled copy is unknown and the edge is refused rather than assumed pure. + return [ + violation( + file, + site.line, + `${managedName} may not import the host-kit '${site.spec}' scope at runtime: no such ` + + `host-kit subpath exists to derive its exec reachability from${MANAGED_HOST_KIT_SCOPE_MESSAGE}`, + ), + ]; + } + const reached = hostKitSymbolsReachingExec(surface, bound); + if (reached.length === 0) return []; + return [ + violation( + file, + site.line, + `${managedName} may not import the host-kit '${site.spec}' scope at runtime ` + + `(${[...reached].sort().join(', ')})` + + MANAGED_HOST_KIT_SCOPE_MESSAGE, + ), + ]; } const INTERACTOR_COMPOSITION_FILE = 'src/core/interactors/register-builtins.ts'; @@ -398,7 +386,11 @@ function checkDeclarations(packages: readonly PlatformPackageDeclaration[]): Lay return violations; } -function checkSource(file: string, source: string): LayeringViolation[] { +function checkSource( + file: string, + source: string, + hostKitReach: HostKitReachIndex, +): LayeringViolation[] { const violations: LayeringViolation[] = []; const ownerFamily = familyForPackageFile(file); // The Apple runner package is not a platform family: it owns its cache/lease files and usbmux @@ -486,7 +478,7 @@ function checkSource(file: string, source: string): LayeringViolation[] { if (!ownerFamily) continue; const managedName = MANAGED_PLATFORMS[ownerFamily as PlatformFamily]; if (managedName && isProductionSourceFile(file)) { - violations.push(...managedHostKitScopeViolations(file, site, managedName)); + violations.push(...managedHostKitScopeViolations(file, site, managedName, hostKitReach)); } if ( site.spec.startsWith('@agent-device/') && @@ -576,8 +568,27 @@ function isAllowedPlatformRootImport( export function checkPlatformPackagePolicy( sources: ReadonlyMap, packages: readonly PlatformPackageDeclaration[], - options: { untrackedProductionFiles?: readonly string[] } = {}, + options: { + untrackedProductionFiles?: readonly string[]; + /** + * The host-kit sources to derive exec reachability from. Defaults to the host-kit files `sources` + * contains, which is what the gate passes; a caller that scans a slice injects its own. + */ + hostKitSources?: ReadonlyMap; + } = {}, ): LayeringViolation[] { + // The host-kit files in the scan input are what the derivation walks. A scan slice without them + // answers that no subpath can be proved pure, which refuses a managed plugin's host-kit import rather + // than letting an absent graph pass it; the gate scan carries every host-kit source. + const hostKit = options.hostKitSources ?? hostKitSources(sources); + const hostKitReach = indexHostKitReach({ + sources: hostKit, + entries: hostKitPublicEntries(hostKit), + resolve: (fromFile, spec) => { + const target = resolveRelativeSource(fromFile, spec); + return target !== undefined && hostKit.has(target) ? target : undefined; + }, + }); return [ ...(options.untrackedProductionFiles ?? []).map((file) => violation( @@ -586,9 +597,20 @@ export function checkPlatformPackagePolicy( 'untracked production source is not committed-state layering evidence; commit the complete slice before running the gate', ), ), + // The roots the derivation walks are declared paths: a move of either would otherwise answer + // "no export reaches the exec layer" for every managed plugin at once. + ...(hostKit.size === 0 + ? [] + : staleReachModules( + RULE, + 'packages/host-kit/package.json', + HOST_KIT_EXEC_ROOTS, + [...hostKit.keys()], + 'HOST_KIT_EXEC_ROOTS', + )), ...checkDeclarations(packages), ...checkPlatformComposition(sources.get(COMPOSITION_FILE)), - ...[...sources].flatMap(([file, source]) => checkSource(file, source)), + ...[...sources].flatMap(([file, source]) => checkSource(file, source, hostKitReach)), ]; } From 94ea8e2e3e0716ce4a41d4e1a6860fed6d57edcc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 21 Nov 2026 17:23:00 +0100 Subject: [PATCH 05/11] refactor(plugins): answer every machine and process fact on the host MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- .../contracts/src/platform-runtime-host.ts | 9 + .../src/internal/exec-kill-settle.test.ts | 2 +- .../src/internal/host-process-facts.ts | 147 ------------ .../host-kit/src/internal/host-process.ts | 154 +++++++++--- .../host-kit/src/internal/process-lock.ts | 2 +- packages/host-kit/src/internal/retry.ts | 29 ++- packages/host-kit/src/internal/sleep.ts | 39 --- packages/host-kit/src/retry.ts | 4 +- .../src/__tests__/input-actions.test.ts | 7 +- packages/platform-harmonyos/src/index.test.ts | 11 +- .../platform-harmonyos/src/input-actions.ts | 2 +- .../src/command-host.fixtures.ts | 11 +- packages/platform-vega/src/index.test.ts | 11 +- ...rowser-process-record-host-routing.test.ts | 4 +- .../agent-browser-process-record.test.ts | 224 +++++------------- .../src/agent-browser-install-paths.test.ts | 52 +++- .../src/agent-browser-install-paths.ts | 42 ++-- .../platform-web/src/agent-browser-install.ts | 35 +-- .../src/agent-browser-lifecycle.test.ts | 83 ++++--- .../src/agent-browser-process-record.ts | 85 +++---- .../src/agent-browser-provider.ts | 3 +- .../src/agent-browser-tool.test.ts | 4 +- .../platform-web/src/agent-browser-tool.ts | 55 +++-- .../src/index-startup-cleanup.test.ts | 6 +- packages/platform-web/src/toolbox.fixtures.ts | 95 ++++++-- packages/platform-web/src/toolbox.ts | 12 + packages/plugins/src/platform.test.ts | 10 +- packages/plugins/src/platform.ts | 52 +++- .../layering/platform-package-policy.test.ts | 47 ++-- scripts/layering/platform-package-policy.ts | 11 +- src/platform-runtime/plugin-host.test.ts | 46 ++++ src/platform-runtime/plugin-host.ts | 68 +++++- 32 files changed, 780 insertions(+), 582 deletions(-) delete mode 100644 packages/host-kit/src/internal/host-process-facts.ts delete mode 100644 packages/host-kit/src/internal/sleep.ts diff --git a/packages/contracts/src/platform-runtime-host.ts b/packages/contracts/src/platform-runtime-host.ts index 2426588aba..9ff69073a6 100644 --- a/packages/contracts/src/platform-runtime-host.ts +++ b/packages/contracts/src/platform-runtime-host.ts @@ -31,6 +31,15 @@ export type ManagedProcessIdentity = Readonly<{ export type ManagedProcessOwnership = 'missing' | 'owned-alive' | 'ownership-lost'; +/** + * Whether a durable process record still names the live process it recorded, as the process that owns + * process reads answers. {@link ManagedProcessOwnership} asks a caller's own marker for a process it + * started; this asks a record an earlier run wrote. A process the host's table did not list stays + * `unobserved` rather than becoming proof it exited, so a caller never acts on a process-tool read + * that simply failed. + */ +export type RecordedProcessLiveness = 'alive' | 'not-alive' | 'unobserved'; + /** * A daemon-owned process identity that may outlive the request which spawned * it. The purpose is bounded recovery metadata, not a command selector. diff --git a/packages/host-kit/src/internal/exec-kill-settle.test.ts b/packages/host-kit/src/internal/exec-kill-settle.test.ts index dc41d067d1..8d19624b6f 100644 --- a/packages/host-kit/src/internal/exec-kill-settle.test.ts +++ b/packages/host-kit/src/internal/exec-kill-settle.test.ts @@ -13,7 +13,7 @@ import { type ExecStreamOptions, } from './exec.ts'; import { shellQuote } from '@agent-device/kernel/device-shell'; -import { sleep } from './sleep.ts'; +import { sleep } from './retry.ts'; import { mkdtempForTestSync } from './tmp-dir.fixtures.ts'; // A direct child can hand our stdout/stderr pipes to a descendant, and `close` waits diff --git a/packages/host-kit/src/internal/host-process-facts.ts b/packages/host-kit/src/internal/host-process-facts.ts deleted file mode 100644 index beb5d606f9..0000000000 --- a/packages/host-kit/src/internal/host-process-facts.ts +++ /dev/null @@ -1,147 +0,0 @@ -import type { EnvMap, HostEnvironment } from '@agent-device/kernel/source-value'; - -/** - * What one process knows about itself and its machine without asking the host for anything: the - * platform, the Node it runs, its own pid, whether another pid is still there, and the pid arithmetic - * that works over rows the caller already holds. This module runs no command, reads no process table - * and emits no diagnostic, so it is the clean leaf of the process surface. `internal/host-process.ts` - * is the read side: it runs `ps`, PowerShell and `sysctl`, and takes these facts from here. - * - * The line matters because a managed platform package is bundled with its own copy of host-kit. A - * runtime import of a module that reaches `internal/exec.ts` or `internal/diagnostics.ts` answers with - * the daemon's process environment and traces into the bundle's own store, outside the request's - * captured environment and exec trace. The platform package policy derives which host-kit exports a - * managed package may import from that graph, so what is declared here stays importable and what is - * not stays with the reads. - */ - -/** The process-shaped object an entry point captures: Node's `process` satisfies it. */ -export type HostEnvironmentSource = Readonly<{ - env: EnvMap; - cwd(): string; -}>; - -/** - * Snapshots the environment and working directory of `source`, which an entry point passes as - * `process`. The environment is copied, so later changes to the source never reach the capture. - */ -export function captureHostEnvironment(source: HostEnvironmentSource): HostEnvironment { - return { env: { ...source.env }, cwd: source.cwd() }; -} - -/** One host answer about one pid: what the process table calls its state and birth time. */ -export type HostProcessIdentityObservation = Readonly<{ - state: string; - startTime: string; -}>; - -/** One row of a host process table: the pid, its parent when the host named one, and its command. */ -export type HostProcessInfo = { - pid: number; - ppid?: number; - command: string; -}; - -/** Positive proof of different lifetimes; unreadable or mixed-format records prove nothing. */ -export function processStartTimesDiffer( - left: string | null | undefined, - right: string | null | undefined, -): boolean { - if (!left || !right) return false; - if (left.startsWith('linux:') !== right.startsWith('linux:')) return false; - return left !== right; -} - -/** Whether the host still has this pid. A refused probe means the process is there. */ -export function isProcessAlive(pid: number): boolean { - if (!Number.isInteger(pid) || pid <= 0) return false; - try { - process.kill(pid, 0); - return true; - } catch (error) { - return (error as NodeJS.ErrnoException).code === 'EPERM'; - } -} - -/** Whether the process group of `pid` still exists, on the same refusal rule as a pid probe. */ -export function isProcessGroupAlive(pid: number): boolean { - if (!Number.isInteger(pid) || pid <= 0) return false; - try { - process.kill(-pid, 0); - return true; - } catch (error) { - return (error as NodeJS.ErrnoException).code === 'EPERM'; - } -} - -export function writeHostStderr(value: string): void { - process.stderr.write(value); -} - -export function hostNodeExecutablePath(): string { - return process.execPath; -} - -export function hostNodeVersion(): string { - return process.version; -} - -export function hostPlatform(): NodeJS.Platform { - return process.platform; -} - -/** Whether this host runs Windows, where identity facts come from the CIM table instead of `ps`. */ -export function isWindowsHostPlatform(): boolean { - return process.platform === 'win32'; -} - -export function hostProcessId(): number { - return process.pid; -} - -/** The pids to act on: integral, positive, deduplicated, and never the excluded one. */ -export function uniquePositivePids( - values: Iterable, - options: { excludePid?: number } = {}, -): number[] { - return [...new Set(values)].filter( - (pid) => Number.isInteger(pid) && pid > 0 && pid !== options.excludePid, - ); -} - -/** Every row of `processes` that descends from `rootPids`, together with those roots. */ -export function expandProcessTree( - rootPids: readonly number[], - processes: readonly HostProcessInfo[], -): HostProcessInfo[] { - const selected = new Set(uniquePositivePids(rootPids)); - let changed = true; - while (changed) { - changed = false; - for (const processInfo of processes) { - if (processInfo.ppid === undefined || !selected.has(processInfo.ppid)) continue; - if (selected.has(processInfo.pid)) continue; - selected.add(processInfo.pid); - changed = true; - } - } - return processes.filter((processInfo) => selected.has(processInfo.pid)); -} - -/** Signals every pid named except this process's own, and counts the ones the host accepted. */ -export function signalPidsBestEffort( - pidsToSignal: readonly number[], - signal: NodeJS.Signals, -): number { - const pids = uniquePositivePids(pidsToSignal, { excludePid: process.pid }); - let signaled = 0; - for (const pid of pids) { - try { - process.kill(pid, signal); - signaled += 1; - } catch { - // Process already exited or cannot be signaled; cleanup remains best-effort. - } - } - return signaled; -} diff --git a/packages/host-kit/src/internal/host-process.ts b/packages/host-kit/src/internal/host-process.ts index 57f88b1e9e..f7533107ae 100644 --- a/packages/host-kit/src/internal/host-process.ts +++ b/packages/host-kit/src/internal/host-process.ts @@ -1,35 +1,8 @@ import fs from 'node:fs'; import type { ExecOptions, ExecResult } from './exec.ts'; import { runCmd, runCmdSync, withoutCommandExecutorOverride } from './exec.ts'; -import { sleep } from './sleep.ts'; -import { - isProcessAlive, - isWindowsHostPlatform, - processStartTimesDiffer, - uniquePositivePids, - type HostProcessIdentityObservation, - type HostProcessInfo, -} from './host-process-facts.ts'; -// Everything this module reads with a process tool lives here; what a process knows about itself lives -// in `host-process-facts.ts` and is forwarded so consumers of either module see one set of names. -export { - captureHostEnvironment, - expandProcessTree, - hostNodeExecutablePath, - hostNodeVersion, - hostPlatform, - hostProcessId, - type HostEnvironmentSource, - type HostProcessIdentityObservation, - type HostProcessInfo, - isProcessAlive, - isProcessGroupAlive, - isWindowsHostPlatform, - processStartTimesDiffer, - signalPidsBestEffort, - uniquePositivePids, - writeHostStderr, -} from './host-process-facts.ts'; +import { sleep } from './retry.ts'; +import type { EnvMap, HostEnvironment } from '@agent-device/kernel/source-value'; const PS_TIMEOUT_MS = 1_000; // Every POSIX probe runs the first of these that exists, never a PATH lookup, so a hostile PATH @@ -41,6 +14,17 @@ const HOST_PS_COMMANDS = ['/bin/ps', '/run/current-system/sw/bin/ps'] as const; const WINDOWS_PS_TIMEOUT_MS = 2_000; const WINDOWS_PROCESS_TOOL = 'powershell.exe'; +export type HostProcessInfo = { + pid: number; + ppid?: number; + command: string; +}; + +export type HostProcessIdentityObservation = Readonly<{ + state: string; + startTime: string; +}>; + /** * What the host says about one pid when a caller is about to signal it. Each field is `null` * when the host did not answer, which is unknown evidence rather than absence: only a `ps` @@ -60,6 +44,40 @@ type HostProcessRunCommand = ( options: ExecOptions, ) => Promise; +/** The process-shaped object an entry point captures: Node's `process` satisfies it. */ +export type HostEnvironmentSource = Readonly<{ + env: EnvMap; + cwd(): string; +}>; + +/** + * Snapshots the environment and working directory of `source`, which an entry point passes as + * `process`. The environment is copied, so later changes to the source never reach the capture. + */ +export function captureHostEnvironment(source: HostEnvironmentSource): HostEnvironment { + return { env: { ...source.env }, cwd: source.cwd() }; +} + +export function writeHostStderr(value: string): void { + process.stderr.write(value); +} + +export function hostNodeExecutablePath(): string { + return process.execPath; +} + +export function hostNodeVersion(): string { + return process.version; +} + +export function hostPlatform(): NodeJS.Platform { + return process.platform; +} + +export function hostProcessId(): number { + return process.pid; +} + function hostPsCommand(): string { for (const candidate of HOST_PS_COMMANDS) { try { @@ -75,6 +93,26 @@ export type ListHostProcessesOptions = { runCommand?: HostProcessRunCommand; }; +export function isProcessAlive(pid: number): boolean { + if (!Number.isInteger(pid) || pid <= 0) return false; + try { + process.kill(pid, 0); + return true; + } catch (error) { + return (error as NodeJS.ErrnoException).code === 'EPERM'; + } +} + +export function isProcessGroupAlive(pid: number): boolean { + if (!Number.isInteger(pid) || pid <= 0) return false; + try { + process.kill(-pid, 0); + return true; + } catch (error) { + return (error as NodeJS.ErrnoException).code === 'EPERM'; + } +} + /** * Reads who owns a pid, off the event loop, with a budget the caller names. Use this rather than * the synchronous probes when the answer decides whether a process is signaled: waiting is @@ -202,6 +240,16 @@ function readLinuxProcessStat(pid: number): { state: string; startTime: string } } } +/** Positive proof of different lifetimes; unreadable or mixed-format records prove nothing. */ +export function processStartTimesDiffer( + left: string | null | undefined, + right: string | null | undefined, +): boolean { + if (!left || !right) return false; + if (left.startsWith('linux:') !== right.startsWith('linux:')) return false; + return left !== right; +} + export function readProcessStartTime(pid: number): string | null { return readProcessField(pid, 'lstart='); } @@ -410,6 +458,10 @@ type WindowsProcessRow = Readonly<{ command: string | null; }>; +function isWindowsHostPlatform(): boolean { + return hostPlatform() === 'win32'; +} + // Rows are `pid|ppid|creation|command`. The creation stamp is formatted with // the invariant culture, so the value recorded in daemon.json compares equal // on every read of the same process lifetime regardless of host locale. The @@ -535,6 +587,50 @@ export async function listHostProcesses( return parseHostProcessList(result.stdout); } +export function expandProcessTree( + rootPids: readonly number[], + processes: readonly HostProcessInfo[], +): HostProcessInfo[] { + const selected = new Set(uniquePositivePids(rootPids)); + let changed = true; + while (changed) { + changed = false; + for (const processInfo of processes) { + if (processInfo.ppid === undefined || !selected.has(processInfo.ppid)) continue; + if (selected.has(processInfo.pid)) continue; + selected.add(processInfo.pid); + changed = true; + } + } + return processes.filter((processInfo) => selected.has(processInfo.pid)); +} + +export function uniquePositivePids( + values: Iterable, + options: { excludePid?: number } = {}, +): number[] { + return [...new Set(values)].filter( + (pid) => Number.isInteger(pid) && pid > 0 && pid !== options.excludePid, + ); +} + +export function signalPidsBestEffort( + pidsToSignal: readonly number[], + signal: NodeJS.Signals, +): number { + const pids = uniquePositivePids(pidsToSignal, { excludePid: process.pid }); + let signaled = 0; + for (const pid of pids) { + try { + process.kill(pid, signal); + signaled += 1; + } catch { + // Process already exited or cannot be signaled; cleanup remains best-effort. + } + } + return signaled; +} + export async function waitForProcessExit(pid: number, timeoutMs: number): Promise { if (!isProcessAlive(pid)) return true; const start = Date.now(); diff --git a/packages/host-kit/src/internal/process-lock.ts b/packages/host-kit/src/internal/process-lock.ts index 9eb244a9da..3b5282fb13 100644 --- a/packages/host-kit/src/internal/process-lock.ts +++ b/packages/host-kit/src/internal/process-lock.ts @@ -20,7 +20,7 @@ import { readCurrentOwnerIdentityAsync, type OwnerLiveness, } from './owner-identity.ts'; -import { sleep } from './sleep.ts'; +import { sleep } from './retry.ts'; const OWNER_FILE_NAME = 'owner.json'; const DEFAULT_LOCK_TIMEOUT_MS = 30_000; diff --git a/packages/host-kit/src/internal/retry.ts b/packages/host-kit/src/internal/retry.ts index d4782b1b56..47208f6b07 100644 --- a/packages/host-kit/src/internal/retry.ts +++ b/packages/host-kit/src/internal/retry.ts @@ -1,6 +1,5 @@ import { AppError, createRequestCanceledError } from '@agent-device/kernel/errors'; import { emitDiagnostic } from './diagnostics.ts'; -import { sleep } from './sleep.ts'; type RetryPolicy = { maxAttempts: number; @@ -254,6 +253,34 @@ function computeDelay(base: number, max: number, jitter: number, attempt: number return Math.max(0, exp + (Math.random() * 2 - 1) * jitterAmount); } +export function sleep(ms: number, signal?: AbortSignal): Promise { + return new Promise((resolve) => { + if (signal?.aborted) { + resolve(); + return; + } + let settled = false; + const finish = () => { + if (settled) return; + settled = true; + if (signal) { + signal.removeEventListener('abort', onAbort); + } + resolve(); + }; + const timer = setTimeout(finish, ms); + + function onAbort(): void { + clearTimeout(timer); + finish(); + } + + if (signal) { + signal.addEventListener('abort', onAbort, { once: true }); + } + }); +} + function publishRetryEvent(event: RetryTelemetryEvent): void { emitDiagnostic({ level: event.event === 'attempt_failed' || event.event === 'exhausted' ? 'warn' : 'debug', diff --git a/packages/host-kit/src/internal/sleep.ts b/packages/host-kit/src/internal/sleep.ts deleted file mode 100644 index 6a7a672619..0000000000 --- a/packages/host-kit/src/internal/sleep.ts +++ /dev/null @@ -1,39 +0,0 @@ -/** - * Waits without naming what it is waiting for. This module imports nothing, so a caller that only - * paces itself never evaluates the retry policy, its diagnostic telemetry, or the error vocabulary - * `internal/retry.ts` carries. - * - * The leaf matters twice over. `settle-within.ts` states the same reason for the deadline primitive: - * the eager-closure gate measures the difference. And the platform package policy reads the host-kit - * module graph to decide which exports a managed platform package may import at runtime, because a - * managed plugin is bundled with its own copy of host-kit: a module that reaches the exec layer or the - * diagnostic store from that copy answers with the daemon's environment, outside the request's captured - * environment and exec trace. Pacing stays on the clean side of that line. - */ -export function sleep(ms: number, signal?: AbortSignal): Promise { - return new Promise((resolve) => { - if (signal?.aborted) { - resolve(); - return; - } - let settled = false; - const finish = () => { - if (settled) return; - settled = true; - if (signal) { - signal.removeEventListener('abort', onAbort); - } - resolve(); - }; - const timer = setTimeout(finish, ms); - - function onAbort(): void { - clearTimeout(timer); - finish(); - } - - if (signal) { - signal.addEventListener('abort', onAbort, { once: true }); - } - }); -} diff --git a/packages/host-kit/src/retry.ts b/packages/host-kit/src/retry.ts index d280b2a89d..92737e9547 100644 --- a/packages/host-kit/src/retry.ts +++ b/packages/host-kit/src/retry.ts @@ -6,9 +6,7 @@ export { openScope, pollUntilSettled, retryWithPolicy, + sleep, RETRY_PHASE, type Scope, } from './internal/retry.ts'; -// The timer is published beside the policy and stays a dependency-free leaf: pacing itself reads no -// command host and emits no diagnostic, and the platform policy reads that difference. -export { sleep } from './internal/sleep.ts'; diff --git a/packages/platform-harmonyos/src/__tests__/input-actions.test.ts b/packages/platform-harmonyos/src/__tests__/input-actions.test.ts index 3b7e6d186e..d39c71cecd 100644 --- a/packages/platform-harmonyos/src/__tests__/input-actions.test.ts +++ b/packages/platform-harmonyos/src/__tests__/input-actions.test.ts @@ -5,12 +5,15 @@ import type { DeviceInfo } from '@agent-device/kernel/device'; import { createHarmonyHdcRunnerStub } from '../toolbox.fixtures.ts'; const { sleep, readHarmonyGestureViewport, invalidateHarmonyGestureViewport } = vi.hoisted(() => ({ - sleep: vi.fn(), + sleep: vi.fn(async (_milliseconds: number) => undefined), readHarmonyGestureViewport: vi.fn(), invalidateHarmonyGestureViewport: vi.fn(), })); -vi.mock('@agent-device/host-kit/retry', () => ({ sleep })); +// The one timer this family owns paces one HDC write after another. It is the plain Node timer rather +// than the host-kit retry scope's, whose module the plugin would bundle with its own diagnostic store, +// so the suite stands it in here. +vi.mock('node:timers/promises', () => ({ setTimeout: sleep })); vi.mock('../snapshot.ts', () => ({ readHarmonyGestureViewport, invalidateHarmonyGestureViewport, diff --git a/packages/platform-harmonyos/src/index.test.ts b/packages/platform-harmonyos/src/index.test.ts index eb1fae1777..081658b8dc 100644 --- a/packages/platform-harmonyos/src/index.test.ts +++ b/packages/platform-harmonyos/src/index.test.ts @@ -34,6 +34,13 @@ function createPluginHost( env, cwd: '/host-cwd', stateDir: '/host-state', + // What the host says about the machine its commands run on. This family never reads these: its + // devices are reached over HDC, and no install layout or launch argv is derived from them. + hostOs: 'linux', + nodeExecutablePath: '/usr/bin/node', + nodeVersion: 'v24.0.0', + temporaryDirectory: '/tmp', + processId: 4242, runCommand: async (executable, args, options) => { commands.push({ executable, args, env: options.env }); return { stdout: '', stderr: '', exitCode: 0 }; @@ -46,7 +53,9 @@ function createPluginHost( processes: { list: async () => [], readIdentities: async () => new Map(), - readIdentityObservations: async () => new Map(), + expandTree: (rootPids, processes) => + [...processes].filter((processInfo) => [...rootPids].includes(processInfo.pid)), + judgeRecordedLiveness: async (records) => [...records].map(() => 'unobserved' as const), readExecutablePaths: async () => new Map(), reapOwnedRecords: async () => { throw new Error('the HarmonyOS family never reaps host processes'); diff --git a/packages/platform-harmonyos/src/input-actions.ts b/packages/platform-harmonyos/src/input-actions.ts index f6287be1ec..e184474d25 100644 --- a/packages/platform-harmonyos/src/input-actions.ts +++ b/packages/platform-harmonyos/src/input-actions.ts @@ -7,7 +7,7 @@ import { } from '@agent-device/contracts/scroll-gesture'; import type { DeviceInfo } from '@agent-device/kernel/device'; import { AppError } from '@agent-device/kernel/errors'; -import { sleep } from '@agent-device/host-kit/retry'; +import { setTimeout as sleep } from 'node:timers/promises'; import type { HarmonyHdcRunner } from './hdc.ts'; import { invalidateHarmonyGestureViewport, readHarmonyGestureViewport } from './snapshot.ts'; diff --git a/packages/platform-vega/src/command-host.fixtures.ts b/packages/platform-vega/src/command-host.fixtures.ts index dc77d2c1da..9ad5dbda34 100644 --- a/packages/platform-vega/src/command-host.fixtures.ts +++ b/packages/platform-vega/src/command-host.fixtures.ts @@ -63,6 +63,13 @@ export function createVegaHostStub( env: input.env ?? { PATH: '/usr/bin', HOME: '/host-home' }, cwd: '/host-cwd', stateDir: '/host-state', + // What the host says about the machine its commands run on. This family never reads these: its + // devices are reached through the Vega CLI, and no install layout or launch argv is derived. + hostOs: 'linux', + nodeExecutablePath: '/usr/bin/node', + nodeVersion: 'v24.0.0', + temporaryDirectory: '/tmp', + processId: 4242, emitDiagnostic: () => {}, withDiagnosticTimer: async (_phase: string, operation: () => Promise) => await operation(), @@ -75,7 +82,9 @@ export function createVegaHostStub( processes: { list: async () => [], readIdentities: async () => new Map(), - readIdentityObservations: async () => new Map(), + expandTree: (rootPids, processes) => + [...processes].filter((processInfo) => [...rootPids].includes(processInfo.pid)), + judgeRecordedLiveness: async (records) => [...records].map(() => 'unobserved' as const), readExecutablePaths: async () => new Map(), reapOwnedRecords: async () => { throw new Error('the Vega family never reaps host processes'); diff --git a/packages/platform-vega/src/index.test.ts b/packages/platform-vega/src/index.test.ts index aae6ceab25..83d77c6d23 100644 --- a/packages/platform-vega/src/index.test.ts +++ b/packages/platform-vega/src/index.test.ts @@ -40,6 +40,13 @@ function createPluginHost( env: input.env ?? {}, cwd: '/host-cwd', stateDir: '/host-state', + // What the host says about the machine its commands run on. This family never reads these: its + // devices are reached over HDC, and no install layout or launch argv is derived from them. + hostOs: 'linux', + nodeExecutablePath: '/usr/bin/node', + nodeVersion: 'v24.0.0', + temporaryDirectory: '/tmp', + processId: 4242, runCommand: async (executable, args) => { input.commands?.push({ executable, args }); return { stdout: '', stderr: '', exitCode: 0 }; @@ -52,7 +59,9 @@ function createPluginHost( processes: { list: async () => [], readIdentities: async () => new Map(), - readIdentityObservations: async () => new Map(), + expandTree: (rootPids, processes) => + [...processes].filter((processInfo) => [...rootPids].includes(processInfo.pid)), + judgeRecordedLiveness: async (records) => [...records].map(() => 'unobserved' as const), readExecutablePaths: async () => new Map(), reapOwnedRecords: async () => { throw new Error('the Vega family never reaps host processes'); diff --git a/packages/platform-web/src/__tests__/agent-browser-process-record-host-routing.test.ts b/packages/platform-web/src/__tests__/agent-browser-process-record-host-routing.test.ts index 59ecb0d763..9469d0634f 100644 --- a/packages/platform-web/src/__tests__/agent-browser-process-record-host-routing.test.ts +++ b/packages/platform-web/src/__tests__/agent-browser-process-record-host-routing.test.ts @@ -24,7 +24,7 @@ import { type AgentBrowserCleanupOptions, } from '../agent-browser-lifecycle.ts'; import { getManagedAgentBrowserStatus } from '../agent-browser-tool.ts'; -import { createWebHostStub, type WebHostStub } from '../toolbox.fixtures.ts'; +import { createWebHostStub, realHostMachineFacts, type WebHostStub } from '../toolbox.fixtures.ts'; import { mkdtempForTestSync } from './test-utils.ts'; const { spawnMock } = vi.hoisted(() => ({ spawnMock: vi.fn() })); @@ -54,7 +54,7 @@ function createFleetState() { }); const status = getManagedAgentBrowserStatus({ stateDir, - host: { env: process.env, cwd: process.cwd() }, + host: { env: process.env, cwd: process.cwd(), ...realHostMachineFacts() }, }); return { stateDir, store, status }; } diff --git a/packages/platform-web/src/__tests__/agent-browser-process-record.test.ts b/packages/platform-web/src/__tests__/agent-browser-process-record.test.ts index 2355ed03f3..e2ccbf5a74 100644 --- a/packages/platform-web/src/__tests__/agent-browser-process-record.test.ts +++ b/packages/platform-web/src/__tests__/agent-browser-process-record.test.ts @@ -1,43 +1,38 @@ import assert from 'node:assert/strict'; import { beforeEach, test, vi } from 'vitest'; -import type { OwnedProcessRecord } from '@agent-device/contracts/platform-runtime-host'; -import type { PlatformHost } from 'agent-device/plugins'; import type { - HostProcessIdentityObservation, - OwnedProcessRecordStore, -} from '@agent-device/host-kit/process'; + OwnedProcessRecord, + RecordedProcessLiveness, +} from '@agent-device/contracts/platform-runtime-host'; +import type { PlatformHost } from 'agent-device/plugins'; +import type { OwnedProcessRecordStore } from '@agent-device/host-kit/process'; import { MANAGED_WEB_BROWSER_PROCESS_PURPOSE, managedWebBrowserProcessRecordIsDead, managedWebBrowserProcessRecordIsLive, } from '../agent-browser-process-record.ts'; -const { observationsMock, isProcessAliveMock } = vi.hoisted(() => ({ - isProcessAliveMock: vi.fn((_pid: number) => false), - observationsMock: vi.fn( - async (_pids: Iterable) => new Map(), +// Whether a recorded process is still the one the record names is the host's rule, not this family's: +// the start-time format, the zombie state and the signal probe all belong to the process that owns +// process reads. So the probes below are asked of the `processes` port and nothing else — the plugin +// carries a host-kit copy of its own, and reading a record with that copy would judge a machine it does +// not run its commands on (R13). +const { judgeMock } = vi.hoisted(() => ({ + judgeMock: vi.fn( + async (_records: readonly OwnedProcessRecord[]) => [] as readonly RecordedProcessLiveness[], ), })); -// Only the signal probe is faked: it is the one host read this module still answers from its own -// process globals. Everything the host must answer goes through the `processes` port below. -vi.mock('@agent-device/host-kit/process', async (importOriginal) => ({ - ...(await importOriginal()), - isProcessAlive: isProcessAliveMock, -})); +const mockJudge = vi.mocked(judgeMock); -const mockObservations = vi.mocked(observationsMock); -const mockIsProcessAlive = vi.mocked(isProcessAliveMock); - -/** - * The process facet the record probe is asked to use. Only `readIdentityObservations` is reached: the - * probe is one batched same-pid snapshot, never a table scan. - */ +/** The process facet the two record probes are asked to use. Only the judgement is reached. */ function createProcessPort(): PlatformHost['processes'] { return { list: async () => [], readIdentities: async () => new Map(), - readIdentityObservations: (pids) => mockObservations(pids), + expandTree: (rootPids, processes) => + [...processes].filter((processInfo) => [...rootPids].includes(processInfo.pid)), + judgeRecordedLiveness: (records) => mockJudge(records), readExecutablePaths: async () => new Map(), reapOwnedRecords: async () => { throw new Error('the record probe never reaps'); @@ -97,28 +92,18 @@ function undecodableDaemonEntry() { }; } -/** The host names every requested pid, alive under the start time the record carries. */ -function hostNamesEveryRequestedPid(): void { - mockObservations.mockImplementation(async (pidsArg: Iterable) => { - const observations = new Map(); - for (const pid of pidsArg) observations.set(pid, { state: 'Ss', startTime: `start-${pid}` }); - return observations; - }); -} - -function hostAnswers(observations: Map): void { - mockObservations.mockResolvedValue(observations); +/** The host answers each record it was handed with `state`, in the order it received them. */ +function hostJudges(state: RecordedProcessLiveness): void { + mockJudge.mockImplementation(async (records) => records.map(() => state)); } beforeEach(() => { - mockObservations.mockReset(); - mockObservations.mockResolvedValue(new Map()); - mockIsProcessAlive.mockReset(); - mockIsProcessAlive.mockReturnValue(false); + mockJudge.mockReset(); + mockJudge.mockResolvedValue([]); }); -test('a record whose every managed process is alive under its recorded identity is live', async () => { - hostNamesEveryRequestedPid(); +test('a record whose every managed process the host vouches for is live', async () => { + hostJudges('alive'); assert.equal( await managedWebBrowserProcessRecordIsLive( storeReturning([daemonEntry([record(11), record(12)])]), @@ -126,47 +111,26 @@ test('a record whose every managed process is alive under its recorded identity ), true, ); - // The probe is one batched same-pid snapshot, not a scan of every host process. - assert.equal(mockObservations.mock.calls.length, 1); - assert.deepEqual([...mockObservations.mock.calls[0]![0]], [11, 12]); -}); - -test('a process the host cannot name makes the record not-live', async () => { - hostAnswers( - new Map([ - [11, { state: 'Ss', startTime: 'start-11' } satisfies HostProcessIdentityObservation], - ]), - ); - assert.equal( - await managedWebBrowserProcessRecordIsLive( - storeReturning([daemonEntry([record(11), record(12)])]), - processes, - ), - false, + // One judgement for the whole record, handed the recorded pids and their start times together. + assert.equal(mockJudge.mock.calls.length, 1); + assert.deepEqual( + mockJudge.mock.calls[0]![0].map(({ pid, startTime }) => [pid, startTime]), + [ + [11, 'start-11'], + [12, 'start-12'], + ], ); }); -test('a pid answering under a different start time is pid reuse, not the recorded fleet', async () => { - hostAnswers( - new Map([ - [11, { state: 'Ss', startTime: 'a-later-boot' } satisfies HostProcessIdentityObservation], - ]), - ); - assert.equal( - await managedWebBrowserProcessRecordIsLive( - storeReturning([daemonEntry([record(11)])]), - processes, - ), - false, - ); +test('a record the host judges partly alive is neither live nor dead', async () => { + mockJudge.mockResolvedValue(['alive', 'not-alive']); + const store = storeReturning([daemonEntry([record(11), record(12)])]); + assert.equal(await managedWebBrowserProcessRecordIsLive(store, processes), false); + assert.equal(await managedWebBrowserProcessRecordIsDead(store, processes), false); }); -test('a recorded zombie is not a live fleet even with its start time intact', async () => { - hostAnswers( - new Map([ - [11, { state: 'ZN', startTime: 'start-11' } satisfies HostProcessIdentityObservation], - ]), - ); +test('a process under a reused pid makes the record not-live', async () => { + mockJudge.mockResolvedValue(['not-alive']); assert.equal( await managedWebBrowserProcessRecordIsLive( storeReturning([daemonEntry([record(11)])]), @@ -176,27 +140,27 @@ test('a recorded zombie is not a live fleet even with its start time intact', as ); }); -test('a probe that answers nothing is unknown evidence, which reads as not-live', async () => { - hostAnswers(new Map()); - assert.equal( - await managedWebBrowserProcessRecordIsLive( - storeReturning([daemonEntry([record(11)])]), - processes, - ), - false, - ); +test('a host that observed nothing keeps the record from reading as live or dead', async () => { + // Unknown evidence is what the host answers for a process table that failed, or for a start time + // recorded in another machine's format: the caller rescans rather than acting on either verdict. + hostJudges('unobserved'); + const store = storeReturning([daemonEntry([record(11)])]); + assert.equal(await managedWebBrowserProcessRecordIsLive(store, processes), false); + assert.equal(await managedWebBrowserProcessRecordIsDead(store, processes), false); }); -test('an empty record is not a live fleet and needs no probe', async () => { +test('an empty record is neither live nor dead and needs no judgement', async () => { assert.equal(await managedWebBrowserProcessRecordIsLive(storeReturning([]), processes), false); assert.equal( await managedWebBrowserProcessRecordIsLive(storeReturning([daemonEntry([])]), processes), false, ); - assert.equal(mockObservations.mock.calls.length, 0); + assert.equal(await managedWebBrowserProcessRecordIsDead(storeReturning([]), processes), false); + assert.equal(mockJudge.mock.calls.length, 0); }); test('a session-scoped record is not the daemon-scoped managed fleet', async () => { + hostJudges('alive'); assert.equal( await managedWebBrowserProcessRecordIsLive( storeReturning([sessionEntry([record(11)])]), @@ -204,45 +168,39 @@ test('a session-scoped record is not the daemon-scoped managed fleet', async () ), false, ); - assert.equal(mockObservations.mock.calls.length, 0); + assert.equal(mockJudge.mock.calls.length, 0); }); test('a record of another purpose is not the managed fleet', async () => { + hostJudges('alive'); const store = storeReturning([ daemonEntry([ { pid: 11, startTime: 'start-11', command: 'command-11', purpose: 'simctl-screen-recording' }, ]), ]); assert.equal(await managedWebBrowserProcessRecordIsLive(store, processes), false); - assert.equal(mockObservations.mock.calls.length, 0); + assert.equal(mockJudge.mock.calls.length, 0); }); -test('an undecodable record is not a live fleet and needs no probe', async () => { - assert.equal( - await managedWebBrowserProcessRecordIsLive( - storeReturning([undecodableDaemonEntry()]), - processes, - ), - false, - ); - assert.equal(mockObservations.mock.calls.length, 0); +test('an undecodable record is neither live nor dead and needs no judgement', async () => { + hostJudges('alive'); + const store = storeReturning([undecodableDaemonEntry()]); + assert.equal(await managedWebBrowserProcessRecordIsLive(store, processes), false); + assert.equal(await managedWebBrowserProcessRecordIsDead(store, processes), false); + assert.equal(mockJudge.mock.calls.length, 0); }); test('a store that cannot answer reads as not-live, which sends the caller back to the scan', async () => { + hostJudges('alive'); const store = storeReturning(() => { throw new Error('record file unreadable'); }); assert.equal(await managedWebBrowserProcessRecordIsLive(store, processes), false); - assert.equal(mockObservations.mock.calls.length, 0); + assert.equal(mockJudge.mock.calls.length, 0); }); -test('a record is dead only when every recorded process was observed not alive', async () => { - hostAnswers( - new Map([ - [11, { state: 'ZN', startTime: 'start-11' } satisfies HostProcessIdentityObservation], - [12, { state: 'Ss', startTime: 'a-later-boot' } satisfies HostProcessIdentityObservation], - ]), - ); +test('a record is dead only when the host judges every recorded process gone', async () => { + hostJudges('not-alive'); assert.equal( await managedWebBrowserProcessRecordIsDead( storeReturning([daemonEntry([record(11), record(12), record(13)])]), @@ -251,57 +209,3 @@ test('a record is dead only when every recorded process was observed not alive', true, ); }); - -test('a recorded process still answering alive keeps the record from being dead', async () => { - hostAnswers( - new Map([ - [11, { state: 'ZN', startTime: 'start-11' } satisfies HostProcessIdentityObservation], - [12, { state: 'Ss', startTime: 'start-12' } satisfies HostProcessIdentityObservation], - ]), - ); - assert.equal( - await managedWebBrowserProcessRecordIsDead( - storeReturning([daemonEntry([record(11), record(12)])]), - processes, - ), - false, - ); -}); - -test('an unanswered probe is unknown evidence, not a dead record', async () => { - hostAnswers(new Map()); - mockIsProcessAlive.mockReturnValue(true); - assert.equal( - await managedWebBrowserProcessRecordIsDead( - storeReturning([daemonEntry([record(11)])]), - processes, - ), - false, - ); -}); - -test('an empty or undecodable record is not dead and needs no probe', async () => { - assert.equal(await managedWebBrowserProcessRecordIsDead(storeReturning([]), processes), false); - assert.equal( - await managedWebBrowserProcessRecordIsDead( - storeReturning([undecodableDaemonEntry()]), - processes, - ), - false, - ); - assert.equal(mockObservations.mock.calls.length, 0); -}); - -test.each([ - ['Mon Aug 10 20:00:00 2026', 'linux:11111111-1111-4111-8111-111111111111:12345'], - ['linux:11111111-1111-4111-8111-111111111111:12345', 'Mon Aug 10 20:00:00 2026'], -])( - 'incomparable process lifetimes (recorded %s, observed %s) prove neither a live nor a dead browser fleet', - async (recorded, observed) => { - mockIsProcessAlive.mockReturnValue(true); - mockObservations.mockResolvedValue(new Map([[11, { state: 'Ss', startTime: observed }]])); - const store = storeReturning([daemonEntry([record(11, recorded)])]); - assert.equal(await managedWebBrowserProcessRecordIsLive(store, processes), false); - assert.equal(await managedWebBrowserProcessRecordIsDead(store, processes), false); - }, -); diff --git a/packages/platform-web/src/agent-browser-install-paths.test.ts b/packages/platform-web/src/agent-browser-install-paths.test.ts index 5c8a0ff1fd..97fc00d4ab 100644 --- a/packages/platform-web/src/agent-browser-install-paths.test.ts +++ b/packages/platform-web/src/agent-browser-install-paths.test.ts @@ -1,30 +1,62 @@ import fs from 'node:fs'; +import { realHostMachineFacts } from './toolbox.fixtures.ts'; import path from 'node:path'; import { expect, test } from 'vitest'; import { mkdtempForTestSync } from './__tests__/test-utils.ts'; import { listManagedInstallPaths, managedInstallPaths } from './agent-browser-install-paths.ts'; +const machine = realHostMachineFacts(); + test('install paths are keyed by state dir and version', () => { const stateDir = path.join(path.sep, 'state'); - const current = managedInstallPaths(stateDir, '0.39.0'); + const current = managedInstallPaths(stateDir, '0.39.0', machine); expect(current.installDir).toBe(path.join(stateDir, 'tools', 'agent-browser', '0.39.0')); expect(current.homeDir).toBe(path.join(current.installDir, 'home')); - expect(managedInstallPaths(stateDir, '0.27.1').socketDir).not.toBe(current.socketDir); - expect(managedInstallPaths(stateDir, '0.39.0')).toEqual(current); + expect(managedInstallPaths(stateDir, '0.27.1', machine).socketDir).not.toBe(current.socketDir); + expect(managedInstallPaths(stateDir, '0.39.0', machine)).toEqual(current); +}); + +test('the runtime home and socket dir come from the host that runs the backend', () => { + const stateDir = path.join(path.sep, 'state'); + const current = managedInstallPaths(stateDir, '0.39.0', machine); + + // POSIX shortens the home to the host's temporary directory: a socket path over the macOS + // 104-character limit is unusable, and the host names the short directory that is not. + expect( + current.runtimeHomeDir.startsWith(path.join(machine.temporaryDirectory, 'agent-device-web')), + ).toBe(true); + expect(current.socketDir.startsWith(path.join(machine.temporaryDirectory, 'adw'))).toBe(true); + + // The answers are the host's, not this process's: another temporary directory moves both, so a + // backend spawned for that host finds its own home and socket rather than the bundle's. + const elsewhere = { + ...machine, + temporaryDirectory: path.join(machine.temporaryDirectory, 'other'), + }; + const moved = managedInstallPaths(stateDir, '0.39.0', elsewhere); + expect(moved.runtimeHomeDir).not.toBe(current.runtimeHomeDir); + expect(moved.socketDir).not.toBe(current.socketDir); + expect( + moved.runtimeHomeDir.startsWith(path.join(elsewhere.temporaryDirectory, 'agent-device-web')), + ).toBe(true); + + // Windows keeps the home inside the install, so the backend's paths stay under one root. + const windows = managedInstallPaths(stateDir, '0.39.0', { ...machine, hostOs: 'win32' }); + expect(windows.runtimeHomeDir).toBe(path.join(windows.installDir, 'home')); }); test('listing finds every installed version and tolerates a missing tools root', () => { const stateDir = mkdtempForTestSync('agent-device-web-installs-'); try { - expect(listManagedInstallPaths(stateDir)).toEqual([]); + expect(listManagedInstallPaths(stateDir, machine)).toEqual([]); for (const version of ['0.27.1', '0.39.0']) { - fs.mkdirSync(managedInstallPaths(stateDir, version).installDir, { recursive: true }); + fs.mkdirSync(managedInstallPaths(stateDir, version, machine).installDir, { recursive: true }); } expect( - listManagedInstallPaths(stateDir) + listManagedInstallPaths(stateDir, machine) .map(({ installDir }) => path.basename(installDir)) .sort(), ).toEqual(['0.27.1', '0.39.0']); @@ -36,13 +68,13 @@ test('listing finds every installed version and tolerates a missing tools root', test('listing skips the install lock file beside the version directories', () => { const stateDir = mkdtempForTestSync('agent-device-web-installs-'); try { - const { installDir } = managedInstallPaths(stateDir, '0.39.0'); + const { installDir } = managedInstallPaths(stateDir, '0.39.0', machine); fs.mkdirSync(installDir, { recursive: true }); fs.writeFileSync(path.join(installDir, '..', '.agent-browser-install.lock'), ''); - expect(listManagedInstallPaths(stateDir).map((install) => install.installDir)).toEqual([ - installDir, - ]); + expect(listManagedInstallPaths(stateDir, machine).map((install) => install.installDir)).toEqual( + [installDir], + ); } finally { fs.rmSync(stateDir, { recursive: true, force: true }); } diff --git a/packages/platform-web/src/agent-browser-install-paths.ts b/packages/platform-web/src/agent-browser-install-paths.ts index bd4234f2b8..aa9c5e3a61 100644 --- a/packages/platform-web/src/agent-browser-install-paths.ts +++ b/packages/platform-web/src/agent-browser-install-paths.ts @@ -1,11 +1,7 @@ import crypto from 'node:crypto'; import path from 'node:path'; -import { - hostFileStatSync, - hostTemporaryDirectory, - readHostDirectorySync, -} from '@agent-device/host-kit/host-file'; -import { hostPlatform } from '@agent-device/host-kit/process'; +import { hostFileStatSync, readHostDirectorySync } from '@agent-device/host-kit/host-file'; +import type { WebMachine } from './toolbox.ts'; /** Everything that locates one version's managed install, its home, and its sockets. */ export type ManagedInstallPaths = { @@ -16,14 +12,25 @@ export type ManagedInstallPaths = { socketDir: string; }; -export function managedInstallPaths(stateDir: string, version: string): ManagedInstallPaths { +/** + * The host's own machine answers, which every path below is built from. Each of these paths has to be + * one the spawned backend can use, so the operating system and the temporary directory named by them + * are the ones that process sees: the host the commands run on, not the bundle that built the argv. + */ +export type WebInstallMachine = Pick; + +export function managedInstallPaths( + stateDir: string, + version: string, + machine: WebInstallMachine, +): ManagedInstallPaths { const installDir = path.join(managedToolsRoot(stateDir), version); return { stateDir, installDir, homeDir: path.join(installDir, 'home'), - runtimeHomeDir: resolveManagedRuntimeHomeDir(installDir), - socketDir: resolveManagedSocketDir(installDir), + runtimeHomeDir: resolveManagedRuntimeHomeDir(installDir, machine), + socketDir: resolveManagedSocketDir(installDir, machine), }; } @@ -32,7 +39,10 @@ export function managedInstallPaths(stateDir: string, version: string): ManagedI * previous version lives in a sibling of the current install, so ownership of the fleet spans all of * them rather than the one the running pin names. */ -export function listManagedInstallPaths(stateDir: string): ManagedInstallPaths[] { +export function listManagedInstallPaths( + stateDir: string, + machine: WebInstallMachine, +): ManagedInstallPaths[] { const root = managedToolsRoot(stateDir); let entries: string[]; try { @@ -43,20 +53,20 @@ export function listManagedInstallPaths(stateDir: string): ManagedInstallPaths[] } return entries .filter((entry) => isDirectory(path.join(root, entry))) - .map((version) => managedInstallPaths(stateDir, version)); + .map((version) => managedInstallPaths(stateDir, version, machine)); } function managedToolsRoot(stateDir: string): string { return path.join(stateDir, 'tools', 'agent-browser'); } -function resolveManagedRuntimeHomeDir(installDir: string): string { - if (hostPlatform() === 'win32') return path.join(installDir, 'home'); - return path.join(hostTemporaryDirectory(), 'agent-device-web', installHash(installDir)); +function resolveManagedRuntimeHomeDir(installDir: string, machine: WebInstallMachine): string { + if (machine.hostOs === 'win32') return path.join(installDir, 'home'); + return path.join(machine.temporaryDirectory, 'agent-device-web', installHash(installDir)); } -function resolveManagedSocketDir(installDir: string): string { - return path.join(hostTemporaryDirectory(), 'adw', installHash(installDir)); +function resolveManagedSocketDir(installDir: string, machine: WebInstallMachine): string { + return path.join(machine.temporaryDirectory, 'adw', installHash(installDir)); } function installHash(installDir: string): string { diff --git a/packages/platform-web/src/agent-browser-install.ts b/packages/platform-web/src/agent-browser-install.ts index e638d14c82..68808ddcaa 100644 --- a/packages/platform-web/src/agent-browser-install.ts +++ b/packages/platform-web/src/agent-browser-install.ts @@ -6,12 +6,8 @@ import { hostFileStatSync, writeHostTextFileSync, } from '@agent-device/host-kit/host-file'; -import { - hostNodeExecutablePath, - hostNodeVersion, - hostPlatform, -} from '@agent-device/host-kit/process'; import type { WebCommandRunner } from './command-host.ts'; +import type { WebMachine } from './toolbox.ts'; /** * How the managed backend gets onto disk. Kept apart from the tool module, @@ -22,13 +18,15 @@ export async function installManagedAgentBrowserPackage(params: { packageSpec: string; timeoutMs: number; env: Readonly; + /** The host's Node and operating system: the runtime npm has to install for. */ + machine: WebMachine; /** The plugin's command route: npm is the host's to spawn, like every other command. */ commands: WebCommandRunner; }): Promise { ensureHostDirectorySync(params.packageRoot); // `--no-global` keeps an ambient `npm_config_global` from redirecting the // install out of the managed prefix, where the backend entry would be missed. - const npm = npmCommand(params.env, [ + const npm = npmCommand(params.env, params.machine, [ 'install', '--prefix', params.packageRoot, @@ -48,6 +46,8 @@ export function writeManagedAgentBrowserManifest(params: { installDir: string; packageName: string; version: string; + /** The Node the manifest records this install as built for. */ + machine: WebMachine; }): void { writeHostTextFileSync( path.join(params.installDir, 'manifest.json'), @@ -55,7 +55,7 @@ export function writeManagedAgentBrowserManifest(params: { { package: params.packageName, version: params.version, - node: hostNodeVersion(), + node: params.machine.nodeVersion, installedAt: new Date().toISOString(), }, null, @@ -70,19 +70,26 @@ export function writeManagedAgentBrowserManifest(params: { * without a shell since the CVE-2024-27980 fix, so its JS entry runs under the * current Node runtime instead (#2022). */ -function npmCommand(env: Readonly, args: string[]): { command: string; args: string[] } { - if (hostPlatform() !== 'win32') return { command: 'npm', args }; - const npmCliScript = resolveWindowsNpmCliScript(env); +function npmCommand( + env: Readonly, + machine: WebMachine, + args: string[], +): { command: string; args: string[] } { + if (machine.hostOs !== 'win32') return { command: 'npm', args }; + const npmCliScript = resolveWindowsNpmCliScript(env, machine); if (!npmCliScript) { throw new AppError('TOOL_MISSING', 'npm not found in PATH', { - nodeExecPath: hostNodeExecutablePath(), + nodeExecPath: machine.nodeExecutablePath, hint: 'Install Node.js with npm, or add npm to PATH, and run `agent-device web setup` again.', }); } - return { command: hostNodeExecutablePath(), args: [npmCliScript, ...args] }; + return { command: machine.nodeExecutablePath, args: [npmCliScript, ...args] }; } -function resolveWindowsNpmCliScript(env: NodeJS.ProcessEnv): string | undefined { +function resolveWindowsNpmCliScript( + env: NodeJS.ProcessEnv, + machine: WebMachine, +): string | undefined { const advertised = env.npm_execpath?.trim(); if (advertised) { const scriptPath = path.resolve(advertised); @@ -90,7 +97,7 @@ function resolveWindowsNpmCliScript(env: NodeJS.ProcessEnv): string | undefined if (path.basename(scriptPath) === 'npm-cli.js' && isFile(scriptPath)) return scriptPath; } const bundled = path.join( - path.dirname(hostNodeExecutablePath()), + path.dirname(machine.nodeExecutablePath), 'node_modules', 'npm', 'bin', diff --git a/packages/platform-web/src/agent-browser-lifecycle.test.ts b/packages/platform-web/src/agent-browser-lifecycle.test.ts index 6d60f09d09..62bcd897b1 100644 --- a/packages/platform-web/src/agent-browser-lifecycle.test.ts +++ b/packages/platform-web/src/agent-browser-lifecycle.test.ts @@ -45,15 +45,8 @@ const identitiesMock = vi.hoisted(() => ); // The subject reads processes only through its host, so the suite controls those reads in the host -// port below rather than by faking the host-kit module. The one module fake left is the platform the -// fleet matchers branch on. -vi.mock('@agent-device/host-kit/process', async (importOriginal) => { - const actual = await importOriginal(); - return { - ...actual, - hostPlatform: () => probe.platform ?? actual.hostPlatform(), - }; -}); +// port below rather than by faking the host-kit module. The machine it branches on is answered by the +// same host, so a case that wants another operating system sets `probe.platform` and the port obliges. import { DEFAULT_AGENT_BROWSER_IDLE_TIMEOUT_MS, @@ -72,15 +65,23 @@ import { import { getManagedAgentBrowserStatus } from './agent-browser-tool.ts'; import { createOwnedProcessRecordStore, + expandProcessTree, listHostProcesses, - readHostProcessIdentityObservationsAsync, reapOwnedProcessRecordsAtStartup, } from '@agent-device/host-kit/process'; import type { PlatformHost } from 'agent-device/plugins'; +import { judgeRecordedLivenessLikeTheHost, realHostMachineFacts } from './toolbox.fixtures.ts'; import { createWebToolbox, type WebToolbox } from './toolbox.ts'; bindTestCommandHost(); const testHost = createLiveTestHostEnvironment(); +/** The host answers the install layout is built from, read from this process. */ +const machine = realHostMachineFacts(); + +/** The host answer a `Node.Platform` maps to, which is the one shape `PlatformHost.hostOs` allows. */ +function hostOperatingSystem(platform: NodeJS.Platform): 'darwin' | 'linux' | 'win32' | 'other' { + return platform === 'darwin' || platform === 'linux' || platform === 'win32' ? platform : 'other'; +} /** * The process port of a host that reads the machine the way the core's host does: the process table @@ -91,10 +92,11 @@ function createHostProcessPort(): PlatformHost['processes'] { return { list: async (options) => await listHostProcesses({ ...options, runCommand: mockRunCmd }), readIdentities: async (pids) => await identitiesMock([...pids]), - readIdentityObservations: async (pids) => + expandTree: (rootPids, processes) => expandProcessTree([...rootPids], [...processes]), + judgeRecordedLiveness: async (records) => probe.unanswered - ? new Map() - : await readHostProcessIdentityObservationsAsync(pids), + ? [...records].map(() => 'unobserved' as const) + : await judgeRecordedLivenessLikeTheHost([...records]), // The host answers this read with the environment it was set up with, the way the real host port // does; the suite's answer is the same fixture either way. readExecutablePaths: async (pids) => await executablePathsMock([...pids], testHost), @@ -117,6 +119,10 @@ const hostProcesses = createHostProcessPort(); function createLifecycleToolbox(stateDir: string): WebToolbox { const host = { ...testHost, + ...realHostMachineFacts(), + // The one platform branch the fleet matchers have: they ask the host which machine it is on + // rather than reading the process's own, so the suite's `probe.platform` fixture is answered here. + ...(probe.platform === undefined ? {} : { hostOs: hostOperatingSystem(probe.platform) }), stateDir, runCommand: async ( executable: string, @@ -154,7 +160,7 @@ test('managed Chrome launch args include a stable agent-device ownership marker installFakeManagedAgentBrowser(stateDir); const status = getManagedAgentBrowserStatus({ stateDir, - host: { env: process.env, cwd: process.cwd() }, + host: { env: process.env, cwd: process.cwd(), ...realHostMachineFacts() }, }); const marker = agentBrowserChromeLaunchMarker(status); @@ -193,7 +199,7 @@ function matchChrome( processInfo: { pid: number; command: string }, status: ReturnType, ) { - return summarizeAgentBrowserProcesses([processInfo], status).processes[0]; + return summarizeAgentBrowserProcesses([processInfo], status, machine).processes[0]; } test('ownership detection accepts only Chrome-like processes with managed markers', () => { @@ -202,7 +208,7 @@ test('ownership detection accepts only Chrome-like processes with managed marker installFakeManagedAgentBrowser(stateDir); const status = getManagedAgentBrowserStatus({ stateDir, - host: { env: process.env, cwd: process.cwd() }, + host: { env: process.env, cwd: process.cwd(), ...realHostMachineFacts() }, }); const marker = agentBrowserChromeLaunchMarker(status); const managedChrome = path.join( @@ -251,7 +257,7 @@ test('cleanup skips reaping when the daemon reports open web sessions', async () installFakeManagedAgentBrowser(stateDir); const status = getManagedAgentBrowserStatus({ stateDir, - host: { env: process.env, cwd: process.cwd() }, + host: { env: process.env, cwd: process.cwd(), ...realHostMachineFacts() }, }); const result = await cleanupManagedAgentBrowserOrphans(status, 'daemon-startup', { env: process.env, @@ -298,7 +304,7 @@ test('cleanup skips reaping while the browser fleet holds an opening session', a installFakeManagedAgentBrowser(stateDir); const status = getManagedAgentBrowserStatus({ stateDir, - host: { env: process.env, cwd: process.cwd() }, + host: { env: process.env, cwd: process.cwd(), ...realHostMachineFacts() }, }); const result = await cleanupManagedAgentBrowserOrphans(status, 'provider-startup', { env: process.env, @@ -324,7 +330,7 @@ test('cleanup reaps when the only fleet session is the one whose open runs it', installFakeManagedAgentBrowser(stateDir); const status = getManagedAgentBrowserStatus({ stateDir, - host: { env: process.env, cwd: process.cwd() }, + host: { env: process.env, cwd: process.cwd(), ...realHostMachineFacts() }, }); const result = await cleanupManagedAgentBrowserOrphans(status, 'provider-startup', { env: process.env, @@ -352,7 +358,7 @@ test('cleanup evicts a launched session whose recorded browser exited, then reap installFakeManagedAgentBrowser(stateDir); const status = getManagedAgentBrowserStatus({ stateDir, - host: { env: process.env, cwd: process.cwd() }, + host: { env: process.env, cwd: process.cwd(), ...realHostMachineFacts() }, }); const result = await cleanupManagedAgentBrowserOrphans(status, 'provider-startup', { env: process.env, @@ -381,7 +387,7 @@ test('cleanup keeps a launched session when the process probe does not answer', installFakeManagedAgentBrowser(stateDir); const status = getManagedAgentBrowserStatus({ stateDir, - host: { env: process.env, cwd: process.cwd() }, + host: { env: process.env, cwd: process.cwd(), ...realHostMachineFacts() }, }); const result = await cleanupManagedAgentBrowserOrphans(status, 'provider-startup', { env: process.env, @@ -407,7 +413,7 @@ test('cleanup skips reaping when managed browser socket activity is recent', asy installFakeManagedAgentBrowser(stateDir); const status = getManagedAgentBrowserStatus({ stateDir, - host: { env: process.env, cwd: process.cwd() }, + host: { env: process.env, cwd: process.cwd(), ...realHostMachineFacts() }, }); fs.mkdirSync(status.socketDir, { recursive: true }); fs.writeFileSync(path.join(status.socketDir, 'agent-browser.sock'), ''); @@ -438,7 +444,7 @@ test('cleanup does not treat the shared socket directory mtime as browser activi installFakeManagedAgentBrowser(stateDir); const status = getManagedAgentBrowserStatus({ stateDir, - host: { env: process.env, cwd: process.cwd() }, + host: { env: process.env, cwd: process.cwd(), ...realHostMachineFacts() }, }); fs.mkdirSync(status.socketDir, { recursive: true }); mockRunCmd.mockResolvedValue({ stdout: '', stderr: '', exitCode: 0 }); @@ -499,7 +505,7 @@ test('cleanup reads recorded browser identities without reconstructing a process installFakeManagedAgentBrowser(stateDir); const status = getManagedAgentBrowserStatus({ stateDir, - host: { env: process.env, cwd: process.cwd() }, + host: { env: process.env, cwd: process.cwd(), ...realHostMachineFacts() }, }); const result = await cleanupManagedAgentBrowserOrphans(status, 'provider-startup', { env: process.env, @@ -528,7 +534,7 @@ test('process summary reports only conservatively owned managed Chrome processes installFakeManagedAgentBrowser(stateDir); const status = getManagedAgentBrowserStatus({ stateDir, - host: { env: process.env, cwd: process.cwd() }, + host: { env: process.env, cwd: process.cwd(), ...realHostMachineFacts() }, }); const marker = agentBrowserChromeLaunchMarker(status); const summary = summarizeAgentBrowserProcesses( @@ -538,6 +544,7 @@ test('process summary reports only conservatively owned managed Chrome processes { pid: 103, command: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome' }, ], status, + machine, ); assert.equal(summary.count, 2); @@ -610,7 +617,7 @@ test.each([ installFakeManagedAgentBrowser(stateDir); const status = getManagedAgentBrowserStatus({ stateDir, - host: { env: process.env, cwd: process.cwd() }, + host: { env: process.env, cwd: process.cwd(), ...realHostMachineFacts() }, }); const binary = nativeBinary(status.installDir); const observed = binary.replaceAll('\\', '/').toUpperCase(); @@ -643,10 +650,10 @@ test('a managed binary symlink cannot confer ownership on an executable outside installFakeManagedAgentBrowser(stateDir); const status = getManagedAgentBrowserStatus({ stateDir, - host: { env: process.env, cwd: process.cwd() }, + host: { env: process.env, cwd: process.cwd(), ...realHostMachineFacts() }, }); const binary = nativeBinary(status.installDir); - const linkedBinary = nativeBinary(managedInstallPaths(stateDir, '0.27.1').installDir); + const linkedBinary = nativeBinary(managedInstallPaths(stateDir, '0.27.1', machine).installDir); const linkedBin = path.dirname(linkedBinary); const outsideBin = path.join(stateDir, 'unrelated-bin'); fs.renameSync(linkedBin, outsideBin); @@ -674,10 +681,10 @@ test('records verified current and retained native roots and stable descendants' installFakeManagedAgentBrowser(stateDir); const status = getManagedAgentBrowserStatus({ stateDir, - host: { env: process.env, cwd: process.cwd() }, + host: { env: process.env, cwd: process.cwd(), ...realHostMachineFacts() }, }); const current = nativeBinary(status.installDir); - const previous = managedInstallPaths(stateDir, '0.27.1'); + const previous = managedInstallPaths(stateDir, '0.27.1', machine); const retained = nativeBinary(previous.installDir); const marker = agentBrowserChromeLaunchMarker(status); const rows: ProcessFixture[] = [ @@ -719,14 +726,14 @@ test('records verified current and retained native roots and stable descendants' test('browser home roots require executable containment and marker roots require Chrome', async () => { const stateDir = mkdtempForTestSync('agent-device-web-life-'); const otherStateDir = mkdtempForTestSync('agent-device-web-other-'); - const previous = managedInstallPaths(stateDir, '0.27.1'); + const previous = managedInstallPaths(stateDir, '0.27.1', machine); try { installFakeManagedAgentBrowser(stateDir); const status = getManagedAgentBrowserStatus({ stateDir, - host: { env: process.env, cwd: process.cwd() }, + host: { env: process.env, cwd: process.cwd(), ...realHostMachineFacts() }, }); - const other = managedInstallPaths(otherStateDir, '0.27.1'); + const other = managedInstallPaths(otherStateDir, '0.27.1', machine); fs.mkdirSync(previous.installDir, { recursive: true }); const otherBinary = nativeBinary(other.installDir); const home = path.join( @@ -801,7 +808,7 @@ test('an unstable root or intermediate process cannot authorize its descendants' installFakeManagedAgentBrowser(stateDir); const status = getManagedAgentBrowserStatus({ stateDir, - host: { env: process.env, cwd: process.cwd() }, + host: { env: process.env, cwd: process.cwd(), ...realHostMachineFacts() }, }); const binary = nativeBinary(status.installDir); const rows: ProcessFixture[] = [ @@ -856,7 +863,7 @@ test('recording refuses a scanned command that differs from the bracketed identi installFakeManagedAgentBrowser(stateDir); const status = getManagedAgentBrowserStatus({ stateDir, - host: { env: process.env, cwd: process.cwd() }, + host: { env: process.env, cwd: process.cwd(), ...realHostMachineFacts() }, }); const binary = nativeBinary(status.installDir); observeProcesses([{ pid: 101, command: `${binary} daemon`, executable: binary }]); @@ -881,10 +888,10 @@ test('recording and reaping require executable provenance and matching identity' installFakeManagedAgentBrowser(stateDir); const status = getManagedAgentBrowserStatus({ stateDir, - host: { env: process.env, cwd: process.cwd() }, + host: { env: process.env, cwd: process.cwd(), ...realHostMachineFacts() }, }); const binary = nativeBinary(status.installDir); - const previous = nativeBinary(managedInstallPaths(stateDir, '0.27.1').installDir); + const previous = nativeBinary(managedInstallPaths(stateDir, '0.27.1', machine).installDir); const rows: ProcessFixture[] = [ { pid: 11001, command: `${binary} daemon`, executable: binary }, { pid: 11002, command: `${previous} daemon`, executable: previous }, @@ -965,7 +972,7 @@ test('cleanup retains legacy records without signaling or treating them as verif installFakeManagedAgentBrowser(stateDir); const status = getManagedAgentBrowserStatus({ stateDir, - host: { env: process.env, cwd: process.cwd() }, + host: { env: process.env, cwd: process.cwd(), ...realHostMachineFacts() }, }); const store = createOwnedProcessRecordStore({ stateDir, diff --git a/packages/platform-web/src/agent-browser-process-record.ts b/packages/platform-web/src/agent-browser-process-record.ts index c0ffe73063..9f2b17737c 100644 --- a/packages/platform-web/src/agent-browser-process-record.ts +++ b/packages/platform-web/src/agent-browser-process-record.ts @@ -1,25 +1,20 @@ import crypto from 'node:crypto'; import path from 'node:path'; -import type { OwnedProcessRecord } from '@agent-device/contracts/platform-runtime-host'; +import type { + OwnedProcessRecord, + RecordedProcessLiveness, +} from '@agent-device/contracts/platform-runtime-host'; import type { PlatformHost } from 'agent-device/plugins'; import { uniqueStrings } from '@agent-device/kernel/collections'; import { hostFileStatSync, realHostPathSync } from '@agent-device/host-kit/host-file'; -import { - expandProcessTree, - hostProcessId, - hostPlatform, - isProcessAlive, - processStartTimesDiffer, - type HostProcessInfo, - type OwnedProcessRecordStore, -} from '@agent-device/host-kit/process'; +import type { HostProcessInfo, OwnedProcessRecordStore } from '@agent-device/host-kit/process'; import { listManagedInstallPaths, type ManagedInstallPaths, } from './agent-browser-install-paths.ts'; import type { AgentBrowserToolStatus } from './agent-browser-tool.ts'; -import type { WebToolbox } from './toolbox.ts'; +import type { WebMachine, WebToolbox } from './toolbox.ts'; const HOST_PROCESS_LIST_TIMEOUT_MS = 1_500; const AGENT_DEVICE_BROWSER_MARKER_PREFIX = '--agent-device-managed-web='; @@ -62,17 +57,21 @@ export function appendAgentDeviceChromeArgs( export function summarizeAgentBrowserProcesses( processes: HostProcessInfo[], status: AgentBrowserToolStatus, + machine: WebMachine, ): AgentBrowserProcessSummary { - const ownership = managedFleetOwnership(status); - return summarizeMatches(processes, (processInfo) => matchChromeProcess(processInfo, ownership)); + const ownership = managedFleetOwnership(status, machine); + return summarizeMatches(processes, (processInfo) => + matchChromeProcess(processInfo, ownership, machine), + ); } function matchManagedAgentBrowserProcess( processInfo: HostProcessInfo, ownership: ManagedFleetOwnership, executablePath: string | undefined, + machine: WebMachine, ): AgentBrowserProcessMatch | undefined { - if (!executablePath || processInfo.pid === hostProcessId()) return undefined; + if (!executablePath || processInfo.pid === machine.processId) return undefined; const executable = normalizePathSeparators(executablePath); if ( isChromeExecutable(executable) && @@ -83,7 +82,7 @@ function matchManagedAgentBrowserProcess( if (isManagedBrowserExecutable(executable, ownership.browserExecutableRoots)) { return { process: processInfo, reason: 'managed-browser-home' }; } - if (matchesManagedDaemonExecutable(executable, ownership.daemonEntries)) { + if (matchesManagedDaemonExecutable(executable, ownership.daemonEntries, machine)) { return { process: processInfo, reason: 'agent-browser-daemon' }; } return undefined; @@ -99,9 +98,13 @@ function isManagedBrowserExecutable(executable: string, roots: readonly string[] return roots.some((root) => resolvedExecutable.startsWith(`${root}/`)); } -function matchesManagedDaemonExecutable(executable: string, entries: readonly string[]): boolean { +function matchesManagedDaemonExecutable( + executable: string, + entries: readonly string[], + machine: WebMachine, +): boolean { if (entries.includes(executable)) return true; - if (hostPlatform() !== 'win32') return false; + if (machine.hostOs !== 'win32') return false; const entry = entries.find((candidate) => candidate.toLowerCase() === executable.toLowerCase()); if (!entry) return false; try { @@ -130,7 +133,7 @@ export async function inspectManagedAgentBrowserProcesses( status: AgentBrowserToolStatus, toolbox: WebToolbox, ): Promise { - return summarizeAgentBrowserProcesses(await listRealHostProcesses(toolbox), status); + return summarizeAgentBrowserProcesses(await listRealHostProcesses(toolbox), status, toolbox.host); } export async function recordManagedAgentBrowserProcesses( @@ -138,6 +141,7 @@ export async function recordManagedAgentBrowserProcesses( store: OwnedProcessRecordStore, toolbox: WebToolbox, ): Promise { + const { host } = toolbox; const initial = await listRealHostProcesses(toolbox); const pids = initial.map(({ pid }) => pid); const before = await toolbox.host.processes.readIdentities(pids); @@ -159,11 +163,16 @@ export async function recordManagedAgentBrowserProcesses( command === first.command ); }); - const ownership = managedFleetOwnership(status); + const ownership = managedFleetOwnership(status, host); const roots = summarizeMatches(processes, (processInfo) => - matchManagedAgentBrowserProcess(processInfo, ownership, executablePaths.get(processInfo.pid)), + matchManagedAgentBrowserProcess( + processInfo, + ownership, + executablePaths.get(processInfo.pid), + host, + ), ); - const ownedProcesses = expandProcessTree(roots.pids, processes); + const ownedProcesses = host.processes.expandTree(roots.pids, processes); const summary: AgentBrowserProcessSummary = { count: ownedProcesses.length, pids: ownedProcesses.map(({ pid }) => pid), @@ -174,6 +183,7 @@ export async function recordManagedAgentBrowserProcesses( processInfo, ownership, executablePaths.get(processInfo.pid), + host, )?.reason ?? 'descendant', })), }; @@ -220,29 +230,18 @@ export async function managedWebBrowserProcessRecordIsDead( return liveness.length > 0 && liveness.every((state) => state === 'not-alive'); } -type RecordedProcessLiveness = 'alive' | 'not-alive' | 'unobserved'; - +/** + * The host's judgement of this plugin's own fleet records: it takes the fail-closed reading, the + * process-tool snapshot, and the liveness probe apart from the start-time format, which is the host's + * rather than something a caller compares itself. + */ async function readRecordedProcessLiveness( store: OwnedProcessRecordStore, processes: PlatformHost['processes'], ): Promise { const records = readDaemonManagedWebBrowserRecords(store); if (records.length === 0) return []; - const observations = await processes.readIdentityObservations( - records.map((record) => record.pid), - ); - return records.map((record) => { - const observation = observations.get(record.pid); - // A pid the process table does not name is gone only when the signal probe agrees; a table - // that answered nothing (a failed `ps`) leaves it unobserved. - if (observation === undefined) return isProcessAlive(record.pid) ? 'unobserved' : 'not-alive'; - if ( - observation.state.startsWith('Z') || - processStartTimesDiffer(observation.startTime, record.startTime) - ) - return 'not-alive'; - return observation.startTime === record.startTime ? 'alive' : 'unobserved'; - }); + return await processes.judgeRecordedLiveness(records); } /** @@ -307,8 +306,11 @@ type ManagedFleetOwnership = { daemonEntries: string[]; }; -function managedFleetOwnership(status: AgentBrowserToolStatus): ManagedFleetOwnership { - const siblings = listManagedInstallPaths(status.stateDir).filter( +function managedFleetOwnership( + status: AgentBrowserToolStatus, + machine: WebMachine, +): ManagedFleetOwnership { + const siblings = listManagedInstallPaths(status.stateDir, machine).filter( (install) => path.resolve(install.installDir) !== path.resolve(status.installDir), ); const installs: ManagedInstallPaths[] = [status, ...siblings]; @@ -357,8 +359,9 @@ function managedFleetOwnership(status: AgentBrowserToolStatus): ManagedFleetOwne function matchChromeProcess( processInfo: HostProcessInfo, ownership: ManagedFleetOwnership, + machine: WebMachine, ): AgentBrowserProcessMatch | undefined { - if (processInfo.pid === hostProcessId() || !isChromeLikeCommand(processInfo.command)) + if (processInfo.pid === machine.processId || !isChromeLikeCommand(processInfo.command)) return undefined; if (ownership.launchMarkers.some((marker) => processInfo.command.includes(marker))) { return { process: processInfo, reason: 'launch-marker' }; diff --git a/packages/platform-web/src/agent-browser-provider.ts b/packages/platform-web/src/agent-browser-provider.ts index 49ade54f82..38e7492430 100644 --- a/packages/platform-web/src/agent-browser-provider.ts +++ b/packages/platform-web/src/agent-browser-provider.ts @@ -1,6 +1,7 @@ import { AGENT_BROWSER_TIMEOUT_MS } from '@agent-device/contracts/managed-web-backend'; import type { OwnedProcessRecordStore } from '@agent-device/host-kit/process'; -import { sleep } from '@agent-device/host-kit/retry'; +// Pacing between two backend sends, on the timer the host itself waits with (`node:timers/promises`). +import { setTimeout as sleep } from 'node:timers/promises'; import { AppError, commandFailureDetails, diff --git a/packages/platform-web/src/agent-browser-tool.test.ts b/packages/platform-web/src/agent-browser-tool.test.ts index 4780a2f363..d403704546 100644 --- a/packages/platform-web/src/agent-browser-tool.test.ts +++ b/packages/platform-web/src/agent-browser-tool.test.ts @@ -14,7 +14,7 @@ import { setupManagedAgentBrowser, } from './agent-browser-tool.ts'; import { mkdtempForTestSync, writeFakeNpmCliScript } from './__tests__/test-utils.ts'; -import { createWebHostStub } from './toolbox.fixtures.ts'; +import { createWebHostStub, realHostMachineFacts } from './toolbox.fixtures.ts'; import { AppError } from '@agent-device/kernel/errors'; import { withCommandExecutorOverride } from '@agent-device/host-kit/command'; @@ -127,7 +127,7 @@ test('managed agent-browser status ignores a bin shim without the backend packag const status = getManagedAgentBrowserStatus({ stateDir, - host: { env: process.env, cwd: process.cwd() }, + host: { env: process.env, cwd: process.cwd(), ...realHostMachineFacts() }, }); assert.equal(status.entryScript, undefined); diff --git a/packages/platform-web/src/agent-browser-tool.ts b/packages/platform-web/src/agent-browser-tool.ts index 649f3b0866..c118599137 100644 --- a/packages/platform-web/src/agent-browser-tool.ts +++ b/packages/platform-web/src/agent-browser-tool.ts @@ -9,13 +9,9 @@ import { readHostTextFileSync, removeHostFileSync, } from '@agent-device/host-kit/host-file'; -import { - hostNodeExecutablePath, - hostNodeVersion, - hostPlatform, -} from '@agent-device/host-kit/process'; import { AppError, asAppError } from '@agent-device/kernel/errors'; import type { HostEnvironment } from '@agent-device/kernel/source-value'; +import type { PlatformHost } from 'agent-device/plugins'; import type { ManagedWebBackendStatus } from '@agent-device/contracts/managed-web-backend'; import type { WebCommandResult } from './command-host.ts'; import { @@ -62,7 +58,7 @@ export async function runManagedAgentBrowser( host: options.toolbox.host, stateDir: options.stateDir, }); - if (!status.installed) throw missingManagedToolError(status); + if (!status.installed) throw missingManagedToolError(status, options.toolbox.host); return await spawnManagedAgentBrowser(status, args, options); } @@ -71,7 +67,7 @@ export async function setupManagedAgentBrowser(options: { stateDir?: string; }): Promise { const status = getManagedAgentBrowserStatus(managedStatusOptions(options)); - assertWebNodeSupported(status.nodeMajor); + assertWebNodeSupported(status.nodeMajor, options.toolbox.host); // The install lock goes through the host: claiming it names this process's identity with a `ps` // read, and every poll of a held or stale lock re-proves the recorded owner and the guard holder @@ -90,6 +86,7 @@ export async function setupManagedAgentBrowser(options: { packageSpec: `${AGENT_BROWSER}@${MANAGED_AGENT_BROWSER_VERSION}`, timeoutMs: SETUP_TIMEOUT_MS, env: options.toolbox.host.env, + machine: options.toolbox.host, commands: options.toolbox.commands, }); // The backend entry only exists once npm has written the package. @@ -107,6 +104,7 @@ export async function setupManagedAgentBrowser(options: { installDir: installedStatus.installDir, packageName: AGENT_BROWSER, version: MANAGED_AGENT_BROWSER_VERSION, + machine: options.toolbox.host, }); return await getManagedAgentBrowserStatus(managedStatusOptions(options)); }, @@ -119,7 +117,7 @@ export async function doctorManagedAgentBrowser(options: { }): Promise<{ status: AgentBrowserToolStatus; stdout: string; stderr: string; exitCode: number }> { const status = getManagedAgentBrowserStatus(managedStatusOptions(options)); if (!status.installed) { - throw missingManagedToolError(status); + throw missingManagedToolError(status, options.toolbox.host); } const result = await spawnManagedAgentBrowser(status, ['doctor', '--offline', '--quick'], { toolbox: options.toolbox, @@ -131,7 +129,7 @@ export async function doctorManagedAgentBrowser(options: { /** Reads a status for the host one of the toolbox-taking operations was set up with. */ function managedStatusOptions(options: { toolbox: WebToolbox; stateDir?: string }): { - host: HostEnvironment; + host: WebStatusHost; stateDir?: string; } { return { @@ -140,26 +138,39 @@ function managedStatusOptions(options: { toolbox: WebToolbox; stateDir?: string }; } +/** + * The host whose answers describe one managed install: the environment and working directory the + * caller captured, plus what the host says about the machine those commands run on. Every field is + * asked of the host so the status names paths, and a Node, the process that spawns the backend can + * actually use. + */ +export type WebStatusHost = HostEnvironment & + Pick< + PlatformHost, + 'hostOs' | 'nodeExecutablePath' | 'nodeVersion' | 'temporaryDirectory' | 'processId' + >; + /** * Where the managed backend is on disk, and whether it is there. Reads only the host's environment * and the filesystem, so it answers the same way whether or not anything is installed. */ export function getManagedAgentBrowserStatus(options: { /** Either the calling runtime's host or the plugin's own host; both answer the same way. */ - host: HostEnvironment; + host: WebStatusHost; stateDir?: string; }): AgentBrowserToolStatus { - const stateDir = - options.stateDir ?? options.host.env.AGENT_DEVICE_STATE_DIR ?? defaultStateDir(options.host); + const { host } = options; + const stateDir = options.stateDir ?? host.env.AGENT_DEVICE_STATE_DIR ?? defaultStateDir(host); const { installDir, homeDir, runtimeHomeDir, socketDir } = managedInstallPaths( stateDir, MANAGED_AGENT_BROWSER_VERSION, + host, ); const packageDir = resolveManagedPackageDir(installDir); - const binaryPath = resolveManagedBinaryPath(installDir); + const binaryPath = resolveManagedBinaryPath(installDir, host); const entryScript = resolveManagedEntryScript(packageDir); const installed = entryScript !== undefined && hasManifest(installDir); - const nodeMajor = Number.parseInt(hostNodeVersion().replace(/^v/, '').split('.')[0] ?? '0', 10); + const nodeMajor = Number.parseInt(host.nodeVersion.replace(/^v/, '').split('.')[0] ?? '0', 10); return { version: MANAGED_AGENT_BROWSER_VERSION, stateDir, @@ -183,9 +194,9 @@ async function spawnManagedAgentBrowser( args: readonly string[], options: Omit, ): Promise { - if (!status.entryScript) throw missingManagedToolError(status); + if (!status.entryScript) throw missingManagedToolError(status, options.toolbox.host); return await options.toolbox.commands.run( - hostNodeExecutablePath(), + options.toolbox.host.nodeExecutablePath, [status.entryScript, ...args], { allowFailure: options.allowFailure, @@ -280,18 +291,18 @@ function resolveManagedPackageDir(installDir: string): string { return path.join(installDir, 'package', 'node_modules', AGENT_BROWSER); } -function resolveManagedBinaryPath(installDir: string): string { - const shim = hostPlatform() === 'win32' ? `${AGENT_BROWSER}.cmd` : AGENT_BROWSER; +function resolveManagedBinaryPath(installDir: string, host: WebStatusHost): string { + const shim = host.hostOs === 'win32' ? `${AGENT_BROWSER}.cmd` : AGENT_BROWSER; return path.join(installDir, 'package', 'node_modules', '.bin', shim); } -function missingManagedToolError(status: AgentBrowserToolStatus): AppError { +function missingManagedToolError(status: AgentBrowserToolStatus, host: WebStatusHost): AppError { return new AppError('TOOL_MISSING', 'Managed web browser backend is not installed.', { version: MANAGED_AGENT_BROWSER_VERSION, installDir: status.installDir, hint: status.nodeSupported === false - ? `Web automation requires Node ${MINIMUM_WEB_NODE_MAJOR}+; current Node is ${hostNodeVersion()}.` + ? `Web automation requires Node ${MINIMUM_WEB_NODE_MAJOR}+; current Node is ${host.nodeVersion}.` : 'Run `agent-device web setup` to install the managed web backend.', }); } @@ -307,10 +318,10 @@ function unusableInstallError(status: AgentBrowserToolStatus): AppError { }); } -function assertWebNodeSupported(nodeMajor: number): void { +function assertWebNodeSupported(nodeMajor: number, host: WebStatusHost): void { if (nodeMajor >= MINIMUM_WEB_NODE_MAJOR) return; throw new AppError('UNSUPPORTED_OPERATION', 'Web automation requires Node 24 or newer.', { - currentNode: hostNodeVersion(), + currentNode: host.nodeVersion, requiredNodeMajor: MINIMUM_WEB_NODE_MAJOR, hint: 'Run agent-device with Node 24+ for web setup and web automation.', }); diff --git a/packages/platform-web/src/index-startup-cleanup.test.ts b/packages/platform-web/src/index-startup-cleanup.test.ts index ac39651f72..19bbf12849 100644 --- a/packages/platform-web/src/index-startup-cleanup.test.ts +++ b/packages/platform-web/src/index-startup-cleanup.test.ts @@ -1,4 +1,5 @@ import assert from 'node:assert/strict'; +import { realHostMachineFacts } from './toolbox.fixtures.ts'; import fs from 'node:fs'; import { beforeEach, expect, test, vi } from 'vitest'; import { @@ -24,6 +25,7 @@ import { runCmd, isExecutablePath, whichCmd } from '@agent-device/host-kit/comma function cleanupWebBrowserOrphansForDaemonStartup(stateDir: string) { const host = { ...createLiveTestHostEnvironment(), + ...realHostMachineFacts(), stateDir, runCommand: runCmd, isFileExecutable: isExecutablePath, @@ -33,7 +35,9 @@ function cleanupWebBrowserOrphansForDaemonStartup(stateDir: string) { processes: { list: async () => [], readIdentities: async () => new Map(), - readIdentityObservations: async () => new Map(), + expandTree: (rootPids, processes) => + [...processes].filter((processInfo) => [...rootPids].includes(processInfo.pid)), + judgeRecordedLiveness: async (records) => [...records].map(() => 'unobserved' as const), readExecutablePaths: async () => new Map(), reapOwnedRecords: async () => { throw new Error('this suite stands the reap in for'); diff --git a/packages/platform-web/src/toolbox.fixtures.ts b/packages/platform-web/src/toolbox.fixtures.ts index 701688a4a2..eb7aefa832 100644 --- a/packages/platform-web/src/toolbox.fixtures.ts +++ b/packages/platform-web/src/toolbox.fixtures.ts @@ -1,16 +1,27 @@ import type { PlatformHost } from 'agent-device/plugins'; import { runCmd, type ExecOptions } from '@agent-device/host-kit/command'; import type { DiagnosticEventInput } from '@agent-device/host-kit/diagnostics'; +import { hostTemporaryDirectory } from '@agent-device/host-kit/host-file'; import { + expandProcessTree, + hostNodeExecutablePath, + hostNodeVersion, + hostPlatform, + hostProcessId, + isProcessAlive, + processStartTimesDiffer, readHostProcessIdentityObservationsAsync, readProcessExecutablePaths, readProcessIdentities, type HostProcessIdentityFacts, - type HostProcessIdentityObservation, type HostProcessInfo, type OwnedProcessRecordStore, type OwnedProcessReapSummary, } from '@agent-device/host-kit/process'; +import type { + OwnedProcessRecord, + RecordedProcessLiveness, +} from '@agent-device/contracts/platform-runtime-host'; import { createWebToolbox, type WebToolbox } from './toolbox.ts'; /** One command the plugin asked its host to run, plus what the host was told about it. */ @@ -28,8 +39,8 @@ export type WebHostStubCommand = Readonly<{ export type WebHostStubProcessRead = Readonly< | { kind: 'table'; pids: [] } | { kind: 'identities'; pids: readonly number[] } - | { kind: 'observations'; pids: readonly number[] } | { kind: 'executable-paths'; pids: readonly number[] } + | { kind: 'liveness'; pids: readonly number[] } | { kind: 'reap'; pids: []; @@ -58,14 +69,16 @@ export type WebHostStubProcesses = Readonly<{ ) => | Promise> | ReadonlyMap; - observations?: ( - pids: readonly number[], - ) => - | Promise> - | ReadonlyMap; executablePaths?: ( pids: readonly number[], ) => Promise> | ReadonlyMap; + /** + * The host's judgement of the records the plugin asked about. Absent, the stub answers the way a + * host that could read nothing does: every record stays unknown evidence. + */ + liveness?: ( + records: readonly OwnedProcessRecord[], + ) => Promise | readonly RecordedProcessLiveness[]; reap?: OwnedProcessReapSummary; }>; @@ -97,7 +110,7 @@ export function createWebHostStub( stateDir?: string; /** Answers one process-table read; the plugin reads the table to derive its fleet record. */ processes?: HostProcessInfo[]; - /** Answers the identity, observation, executable-path and reap calls; defaults to nothing. */ + /** Answers the identity, liveness, executable-path and reap calls; defaults to nothing. */ readProcesses?: (reads: WebHostStubProcessReads) => WebHostStubProcesses; ownedProcessRecords?: PlatformHost['ownedProcessRecords']; openWebSessionNames?: () => readonly string[]; @@ -123,16 +136,20 @@ export function createWebHostStub( processReads.push({ kind: 'identities', pids: named }); return answered.identities?.(named) ?? new Map(); }, - readIdentityObservations: async (pids) => { - const named = [...pids]; - processReads.push({ kind: 'observations', pids: named }); - return answered.observations?.(named) ?? new Map(); - }, readExecutablePaths: async (pids) => { const named = [...pids]; processReads.push({ kind: 'executable-paths', pids: named }); return answered.executablePaths?.(named) ?? new Map(); }, + // The stub expands with the host kit's own rule, so the scan is answered the way the host answers + // it, while the plugin still has to ask rather than run the expansion of its own bundled copy. + expandTree: (rootPids, processes) => + expandProcessTree([...rootPids], [...processes]).map((processInfo) => ({ ...processInfo })), + judgeRecordedLiveness: async (records) => { + const named = [...records]; + processReads.push({ kind: 'liveness', pids: named.map((record) => record.pid) }); + return (await answered.liveness?.(named)) ?? named.map(() => 'unobserved' as const); + }, reapOwnedRecords: async (store, options) => { processReads.push({ kind: 'reap', pids: [], store, options }); return answered.reap ?? EMPTY_REAP_SUMMARY; @@ -154,6 +171,9 @@ export function createWebHostStub( env: input.env ?? process.env, cwd: input.cwd ?? process.cwd(), stateDir: input.stateDir ?? '/host-state', + // The machine the stub's commands would really run on: the same one the test process runs on, so + // the plugin's install layout, launch argv and self-pid exclusion are the production ones. + ...realHostMachineFacts(), runCommand: async ( executable: string, args: string[], @@ -206,12 +226,59 @@ export function createWebHostStub( export function realHostProcessReads(): WebHostStubProcesses { return { identities: async (pids) => await readProcessIdentities(pids), - observations: async (pids) => await readHostProcessIdentityObservationsAsync(pids), executablePaths: async (pids) => await readProcessExecutablePaths(pids, { env: process.env, cwd: process.cwd() }), + liveness: async (records) => await judgeRecordedLivenessLikeTheHost(records), + }; +} + +/** + * The machine answers a host stub gives, read from the process the test runs in. + * + * A plugin builds its managed install layout, the argv it launches, and the pid a fleet scan must not + * match as its own from these, and asks its host for them rather than reading process globals of its + * own (R13). A stub therefore has to answer them, and reading them here keeps a fixture from + * re-implementing what the core's own plugin host answers. A `*.fixtures.*` file may not be imported + * by another test, so this one small answer lives beside the toolbox the host stub stands in for. + */ +export function realHostMachineFacts(): Pick< + PlatformHost, + 'hostOs' | 'nodeExecutablePath' | 'nodeVersion' | 'temporaryDirectory' | 'processId' +> { + const platform = hostPlatform(); + return { + hostOs: + platform === 'darwin' || platform === 'linux' || platform === 'win32' ? platform : 'other', + nodeExecutablePath: hostNodeExecutablePath(), + nodeVersion: hostNodeVersion(), + temporaryDirectory: hostTemporaryDirectory(), + processId: hostProcessId(), }; } +/** + * The host's own fail-closed record judgement, answered with this process's reads. A test that wants + * the gate to decide for the machine it runs on asks for this rather than re-implementing the rule. + */ +export async function judgeRecordedLivenessLikeTheHost( + records: readonly OwnedProcessRecord[], +): Promise { + if (records.length === 0) return []; + const observations = await readHostProcessIdentityObservationsAsync( + records.map((record) => record.pid), + ); + return records.map((record) => { + const observation = observations.get(record.pid); + if (observation === undefined) return isProcessAlive(record.pid) ? 'unobserved' : 'not-alive'; + if ( + observation.state.startsWith('Z') || + processStartTimesDiffer(observation.startTime, record.startTime) + ) + return 'not-alive'; + return observation.startTime === record.startTime ? 'alive' : 'unobserved'; + }); +} + /** A reap that inspected nothing: a stub test asserts the reap was asked, not what it stopped. */ const EMPTY_REAP_SUMMARY: OwnedProcessReapSummary = { inspected: 0, diff --git a/packages/platform-web/src/toolbox.ts b/packages/platform-web/src/toolbox.ts index 07f2f35492..a14ea35f14 100644 --- a/packages/platform-web/src/toolbox.ts +++ b/packages/platform-web/src/toolbox.ts @@ -21,6 +21,18 @@ export type WebToolbox = Readonly<{ withDiagnosticTimer: PlatformHost['withDiagnosticTimer']; }>; +/** + * What the web family asks its host about the machine its commands run on. The managed install layout, + * the Node that launches the backend, and the pid a fleet scan must not match as its own are all + * answers about the process that spawns the plugin's commands, so the plugin takes them from its host + * rather than from the host-kit copy it ships with: that copy answers with the bundle's own process + * globals, and its reads run outside the request's environment and exec trace (R13). + */ +export type WebMachine = Pick< + PlatformHost, + 'hostOs' | 'nodeExecutablePath' | 'nodeVersion' | 'temporaryDirectory' | 'processId' +>; + export function createWebToolbox(host: PlatformHost): WebToolbox { return Object.freeze({ host, diff --git a/packages/plugins/src/platform.test.ts b/packages/plugins/src/platform.test.ts index 3f2524c485..8482b59661 100644 --- a/packages/plugins/src/platform.test.ts +++ b/packages/plugins/src/platform.test.ts @@ -45,6 +45,13 @@ async function startStore(env: HostEnvironment['env']) { platformHost: { ...host, stateDir, + // What the host says about the machine its commands run on. No family in this test reads them: + // the plugin under test only names its state dir. + hostOs: 'linux', + nodeExecutablePath: '/usr/bin/node', + nodeVersion: 'v24.0.0', + temporaryDirectory: '/tmp', + processId: 4242, runCommand: async () => { throw new Error('setup must not start a process'); }, @@ -53,7 +60,8 @@ async function startStore(env: HostEnvironment['env']) { processes: { list: async () => [], readIdentities: async () => new Map(), - readIdentityObservations: async () => new Map(), + expandTree: (_rootPids, processes) => [...processes], + judgeRecordedLiveness: async (records) => [...records].map(() => 'unobserved' as const), readExecutablePaths: async () => new Map(), reapOwnedRecords: async () => { throw new Error('setup must not reap host processes'); diff --git a/packages/plugins/src/platform.ts b/packages/plugins/src/platform.ts index 979345586d..3090e501ae 100644 --- a/packages/plugins/src/platform.ts +++ b/packages/plugins/src/platform.ts @@ -13,12 +13,16 @@ import type { } from '@agent-device/contracts/platform-plugin'; import type { PlatformRuntimeModule } from '@agent-device/contracts/platform-runtime-operations'; import type { LinuxToolProvider } from '@agent-device/contracts/linux-tool-provider'; +import type { + HostOperatingSystem, + OwnedProcessRecord, + RecordedProcessLiveness, +} from '@agent-device/contracts/platform-runtime-host'; import type { VegaToolProvider } from '@agent-device/contracts/vega-tool-provider'; import type { WebProvider } from '@agent-device/contracts/web-provider'; import type { DiagnosticEventInput, withDiagnosticTimer } from '@agent-device/host-kit/diagnostics'; import type { HostProcessIdentityFacts, - HostProcessIdentityObservation, HostProcessInfo, OwnedProcessReapSummary, OwnedProcessRecordStore, @@ -114,6 +118,22 @@ export type PlatformHost = HostEnvironment & * process is gone. */ processes: PlatformHostProcesses; + /** The operating system the host runs, narrowed to the three it ships backends for. */ + hostOs: HostOperatingSystem; + /** + * The Node running the host: its executable, for a launch that must not depend on a `PATH` + * lookup, and its version, for a capability read off the major number. The plugin launches + * commands through this host, so the Node that answers is the Node those commands run under. + */ + nodeExecutablePath: string; + nodeVersion: string; + /** The host's temporary directory, which a per-install runtime home and socket dir derive from. */ + temporaryDirectory: string; + /** + * This process's own pid, which a process scan must never match as one of its targets. A plugin + * reads it here rather than from its bundle's process globals, which name the bundle's process. + */ + processId: number; /** * Starts one streamed command as a managed process: the host publishes an ownership marker at * `markerPath` while the process lives, clears it when the process ends, and stops the process on @@ -163,19 +183,35 @@ export type PlatformHostProcesses = Readonly<{ pids: Iterable, options?: { timeoutMs?: number }, ): Promise>; - /** - * State and start time per pid from one process-tool snapshot. Unlike {@link readIdentities}, a - * pid the snapshot did not list is absent from the answer rather than answered with nothing. - */ - readIdentityObservations( - pids: Iterable, - ): Promise>; /** * The executable each pid is running, for a caller that must prove provenance rather than match a * command line. A pid the host cannot name is absent, which is unknown evidence, not absence of * the process. */ readExecutablePaths(pids: Iterable): Promise>; + /** + * The descendants of `rootPids` among `processes`, following parentage through to the whole subtree. + * + * A fleet scan matches the processes it owns and then has to include what they parented, which is a + * question about the host's process table rather than about the caller's matchers: only the host + * knows which parent-child relation its own table records. The rows are the caller's, so no second + * snapshot is taken and the answer cannot drift from the scan that produced them. + */ + expandTree(rootPids: readonly number[], processes: readonly HostProcessInfo[]): HostProcessInfo[]; + /** + * Whether each owned-process record still names the live process it recorded, judging all of them + * from one process-tool snapshot the host took. + * + * The fail-closed reading is the host's rule rather than the caller's. A pid the table did not list + * is unknown evidence unless the host's own liveness probe refuses it too, because a process tool + * that answered nothing is not proof a process exited; and only a start time the host can compare + * with the recorded one, in the host's own format, proves the pid changed hands. A plugin that + * applied this rule itself would have to know the start-time formats of a machine it does not run + * commands on, and would read them with a process tool outside the request's exec trace. + */ + judgeRecordedLiveness( + records: readonly OwnedProcessRecord[], + ): Promise; /** * Stops every process an owned-process record names, and forgets only the ones it watched leave. * The store is the host's own, so the record the reaper rewrites is the one the daemon reads. The diff --git a/scripts/layering/platform-package-policy.test.ts b/scripts/layering/platform-package-policy.test.ts index 50bc3b7032..ccb5c3b5f9 100644 --- a/scripts/layering/platform-package-policy.test.ts +++ b/scripts/layering/platform-package-policy.test.ts @@ -890,24 +890,39 @@ for (const family of ['web', 'vega', 'harmonyos'] as const) { }); } -// One name's verdict follows its own declaration: the liveness classifier reaches the exec layer and -// is refused, while the pid arithmetic declared beside it in the same module graph does not. -test('the host-kit process scope is judged name by name, not per subpath', () => { +// One name's verdict follows its own declaration rather than its scope's worst export: in the file +// scope, the path helper the graph proves pure stays importable while the lock helper beside it is +// refused. Nothing about an export's name is consulted, so an export that starts loading the exec layer +// is caught without anyone editing a list here. +test('a host-kit scope is judged name by name, not per subpath', () => { const refused = hostKitFindings( 'web', - "import { classifyOwnerLivenessFromObservation } from '@agent-device/host-kit/process';\nvoid classifyOwnerLivenessFromObservation;", - ); - assert.match( - refused, - /host-kit\/process' scope at runtime \(classifyOwnerLivenessFromObservation\)/, + "import { acquireProcessLock } from '@agent-device/host-kit/file';\nvoid acquireProcessLock;", ); + assert.match(refused, /host-kit\/file' scope at runtime \(acquireProcessLock\)/); const allowed = hostKitFindings( 'web', - "import { uniquePositivePids } from '@agent-device/host-kit/process';\nvoid uniquePositivePids;", + "import { expandUserHomePath } from '@agent-device/host-kit/file';\nvoid expandUserHomePath;", ); assert.equal(allowed, ''); }); +// The process and retry scopes have no pure export left: every one of them is declared by a module that +// also runs a process tool or carries the retry diagnostic store, so importing one drags that into the +// bundle, where it answers with the daemon's environment. A plugin asks its host for each of these, +// including the ones that look like arithmetic on a number it already has, and paces itself with +// `node:timers/promises`, the timer the core's own host waits on. +for (const family of ['web', 'vega', 'harmonyos'] as const) { + test(`a managed platform package may not pace itself through the host-kit retry scope (${family})`, () => { + assert.match( + hostKitFindings(family, "import { sleep } from '@agent-device/host-kit/retry';\nvoid sleep;"), + new RegExp( + `@agent-device/${family} .* host-kit '@agent-device/host-kit/retry' scope at runtime`, + ), + ); + }); +} + // Nothing about an export's name is consulted, so a new export that starts loading the exec layer is // caught without anyone editing a list: the same import turns from allowed to refused on the edit. test('the exec reachability of a host-kit export is derived, not declared', () => { @@ -953,11 +968,11 @@ test('a missing exec-root source makes the derivation fail closed', () => { ); }); -// `host-kit/process` is policed export by export: an export that spawns a process tool escapes the -// request's exec trace from a bundled plugin, and one that reads only this process's globals cannot. -// `PlatformHost.processes` answers the first kind on the core's own copy. An edge naming no export -// could reach any of them, so a namespace import is refused rather than assumed harmless. Every case -// is asserted for every managed family: all three are on the host by the same rule. +// `host-kit/process` is policed export by export, and every export of it now loads a process tool from +// some module the subpath evaluates, so none of them survives the bundling that puts a plugin's copy +// outside the request's exec trace. `PlatformHost.processes` answers all of them on the core's own copy. +// An edge naming no export could reach any of them, so a namespace import is refused rather than assumed +// harmless. Every case is asserted for every managed family: all three are on the host by the same rule. const PROCESS_SCOPE_CASES = [ [ 'may not run a process tool through its own host-kit copy', @@ -965,9 +980,9 @@ const PROCESS_SCOPE_CASES = [ String.raw`@agent-device/%FAMILY% may not import the host-kit '@agent-device/host-kit/process' scope at runtime \(listHostProcesses, readProcessIdentities\): .*PlatformHost given to setup`, ], [ - 'keeps the process exports that read no process tool', + 'may not read a machine fact or expand a process tree through its own host-kit copy', "import { expandProcessTree, hostPlatform, isProcessAlive } from '@agent-device/host-kit/process';\nvoid expandProcessTree; void hostPlatform; void isProcessAlive;", - '^$', + String.raw`@agent-device/%FAMILY% may not import the host-kit '@agent-device/host-kit/process' scope at runtime \(expandProcessTree, hostPlatform, isProcessAlive\): .*PlatformHost given to setup`, ], [ 'may not namespace-import the process scope', diff --git a/scripts/layering/platform-package-policy.ts b/scripts/layering/platform-package-policy.ts index 84c368353d..ed69a9e9b6 100644 --- a/scripts/layering/platform-package-policy.ts +++ b/scripts/layering/platform-package-policy.ts @@ -144,10 +144,13 @@ const MANAGED_PLATFORMS: Readonly>> = { // rather than the request's log. A managed plugin binds to the `PlatformHost` its `setup` receives // instead, whose `processes` facet answers those reads on the core's own copy. // -// What stays importable is what the graph proves loads neither root: `hostPlatform`, `hostProcessId`, -// `hostNodeExecutablePath`, `isProcessAlive`, `expandProcessTree`, `processStartTimesDiffer`, -// `uniquePositivePids`, the retry timer, and every file helper. Type-only edges are allowed anywhere — -// they cost the bundle nothing. +// What stays importable is what the graph proves loads neither root: the path helpers and the plain +// filesystem helpers. Type-only edges are allowed anywhere — they cost the bundle nothing. The process +// scope, the retry scope, the command scope, the diagnostics scope and the lock helpers are all +// refused, including the ones that only answer `os.platform()` or wait on a timer: they are declared by +// a module that also declares a process tool, so the bundle loads the tool with them. A plugin asks its +// host what machine its commands run on, and paces itself with `node:timers/promises` the way the +// core's own host does. const MANAGED_HOST_KIT_SCOPE_MESSAGE = ': those exports load internal/exec.ts or internal/diagnostics.ts through the bundled copy, so run ' + 'the command, emit the diagnostic, read processes, or take the lock through the PlatformHost given to ' + diff --git a/src/platform-runtime/plugin-host.test.ts b/src/platform-runtime/plugin-host.test.ts index 14dee13470..72b838e7c5 100644 --- a/src/platform-runtime/plugin-host.test.ts +++ b/src/platform-runtime/plugin-host.test.ts @@ -3,6 +3,7 @@ import { expect, test } from 'vitest'; import { spawn } from 'node:child_process'; import fs from 'node:fs'; import path from 'node:path'; +import type { OwnedProcessRecord } from '@agent-device/contracts/platform-runtime-host'; import { withDiagnosticsScope } from '@agent-device/host-kit/diagnostics'; import { createOwnedProcessRecordStore, @@ -219,6 +220,51 @@ test('the platform plugin host holds a lock and names this process as its owner' expect(tracedCommands(logPath)).toContain('ps'); }); +// The managed web plugin asks this host whether a record an earlier run wrote still names its fleet, +// because the answer depends on facts the plugin cannot read: the start-time format its own `ps` emits, +// the zombie state, and the signal probe for a pid the table did not list. The fail-closed rule lives +// here so one host's verdict is what every plugin gets. +test('the platform plugin host judges a recorded fleet from its own process reads', async () => { + const root = mkdtempForTestSync('plugin-host-liveness-'); + const host = createPlatformPluginHost(createLiveTestHostEnvironment(), root); + const processes = host.processes; + const recorded = (pid: number, startTime: string): OwnedProcessRecord => ({ + pid, + startTime, + command: `command-${pid}`, + purpose: 'verified-managed-web-browser', + }); + + // This process is alive under the identity a host read of it answers with, so a record carrying that + // identity is judged alive. + const startTime = readProcessStartTime(process.pid); + if (startTime === null) throw new Error(`the host named no start time for ${process.pid}`); + expect(await processes.judgeRecordedLiveness([recorded(process.pid, startTime)])).toEqual([ + 'alive', + ]); + + // A record written by a host that stamps start times another way cannot be compared at all: the + // answer is unknown evidence, not a verdict that the recorded fleet exited. + const otherLifetime = startTime.startsWith('linux:') + ? 'Fri Jan 01 00:00:00 2026' + : 'linux:11111111-1111-4111-8111-111111111111:12345'; + expect(await processes.judgeRecordedLiveness([recorded(process.pid, otherLifetime)])).toEqual([ + 'unobserved', + ]); + + // A pid this process started and reaped is gone: the table does not name it and the probe agrees. + const child = spawn(process.execPath, ['-e', ''], { stdio: 'ignore' }); + const childPid = child.pid; + if (childPid === undefined) throw new Error('no pid for the short-lived process'); + await new Promise((resolve) => child.once('exit', () => resolve())); + expect(await processes.judgeRecordedLiveness([recorded(childPid, startTime)])).toEqual([ + 'not-alive', + ]); + + // Nothing asked, nothing judged. + expect(await processes.judgeRecordedLiveness([])).toEqual([]); +}); + /** The commands one debug run traced, in the order the request saw them. */ function tracedCommands(logPath: string): string[] { if (!fs.existsSync(logPath)) return []; diff --git a/src/platform-runtime/plugin-host.ts b/src/platform-runtime/plugin-host.ts index e1f671f1df..bdc46ba814 100644 --- a/src/platform-runtime/plugin-host.ts +++ b/src/platform-runtime/plugin-host.ts @@ -1,6 +1,16 @@ import type { PlatformHost } from '@agent-device/plugins/contract'; import type { HostEnvironment } from '@agent-device/kernel/source-value'; +import { hostTemporaryDirectory } from '@agent-device/host-kit/host-file'; import { emitDiagnostic, withDiagnosticTimer } from '@agent-device/host-kit/diagnostics'; +import { + expandProcessTree, + hostNodeExecutablePath, + hostNodeVersion, + hostPlatform, + hostProcessId, + isProcessAlive, + processStartTimesDiffer, +} from '@agent-device/host-kit/process'; import { resolveDaemonPaths } from '@agent-device/daemon-contracts/daemon-resolution'; /** @@ -11,6 +21,10 @@ import { resolveDaemonPaths } from '@agent-device/daemon-contracts/daemon-resolu * cleanup. The command's own `env` is what the plugin prepared, so a family that resolves its tool * chain from roots the core does not name streams with the same `PATH` it runs one-shot commands with. * + * Every machine and process fact the host answers comes from the core's own copy of the host kit, so + * a plugin that derives an install layout, a launch argv or a fleet verdict from them describes the + * process that runs its commands rather than its own bundle. + * * That process service belongs to the operation-host zone, which the daemon itself reaches only * through a lazy seam. A plugin host is built when a process starts, so it loads the service with the * first streamed command rather than statically, exactly as this file's command port does. @@ -36,6 +50,7 @@ export function createPlatformPluginHost( ...pluginResources, emitDiagnostic, withDiagnosticTimer, + ...createPlatformPluginMachineFacts(), runCommand: async (executable, args, options) => { const { runCmd } = await import('@agent-device/host-kit/command'); return await runCmd(executable, args, options); @@ -70,6 +85,27 @@ export function createPlatformPluginHost( } satisfies PlatformHost); } +/** + * The machine the host runs on, read once. A plugin derives its install layout, its launch argv and + * its runtime home from these, so they answer for the process that runs the plugin's commands rather + * than for the plugin's own bundle: the environment, toolchain and temporary directory that process + * sees are the ones its commands have to work under. + */ +function createPlatformPluginMachineFacts(): Pick< + PlatformHost, + 'hostOs' | 'nodeExecutablePath' | 'nodeVersion' | 'temporaryDirectory' | 'processId' +> { + const platform = hostPlatform(); + return { + hostOs: + platform === 'darwin' || platform === 'linux' || platform === 'win32' ? platform : 'other', + nodeExecutablePath: hostNodeExecutablePath(), + nodeVersion: hostNodeVersion(), + temporaryDirectory: hostTemporaryDirectory(), + processId: hostProcessId(), + }; +} + /** * The host's process answers, served by the core's own copy of the host kit. * @@ -94,15 +130,37 @@ function createPlatformPluginProcessPort(host: HostEnvironment): PlatformHost['p const { readProcessIdentities } = await import('@agent-device/host-kit/process'); return await readProcessIdentities(pids, options?.timeoutMs); }, - readIdentityObservations: async (pids) => { - const { readHostProcessIdentityObservationsAsync } = - await import('@agent-device/host-kit/process'); - return await readHostProcessIdentityObservationsAsync(pids); - }, readExecutablePaths: async (pids) => { const { readProcessExecutablePaths } = await import('@agent-device/host-kit/process'); return await readProcessExecutablePaths(pids, host); }, + // The two answers a plugin cannot derive from rows it was given: the parentage relation and the + // start-time formats are the host's, and judging them from the bundle would read them with a + // process tool of a machine the plugin does not run its commands on. + expandTree: (rootPids, processes) => + expandProcessTree([...rootPids], [...processes]).map((processInfo) => ({ ...processInfo })), + judgeRecordedLiveness: async (records) => { + const rows = [...records]; + if (rows.length === 0) return []; + const { readHostProcessIdentityObservationsAsync } = + await import('@agent-device/host-kit/process'); + const observations = await readHostProcessIdentityObservationsAsync( + rows.map((record) => record.pid), + ); + return rows.map((record) => { + const observation = observations.get(record.pid); + // A pid the process table does not name is gone only when the signal probe agrees; a table + // that answered nothing (a failed `ps`) leaves it unobserved. + if (observation === undefined) + return isProcessAlive(record.pid) ? 'unobserved' : 'not-alive'; + if ( + observation.state.startsWith('Z') || + processStartTimesDiffer(observation.startTime, record.startTime) + ) + return 'not-alive'; + return observation.startTime === record.startTime ? 'alive' : 'unobserved'; + }); + }, reapOwnedRecords: async (store, options) => { const { reapOwnedProcessRecordsAtStartup } = await import('@agent-device/host-kit/process'); return await reapOwnedProcessRecordsAtStartup(store, options); From e51a07edf467bf6d84eec7e195baa95c4ba0960d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 21 Nov 2026 17:24:32 +0100 Subject: [PATCH 06/11] 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. --- packages/platform-web/src/agent-browser-tool.ts | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/packages/platform-web/src/agent-browser-tool.ts b/packages/platform-web/src/agent-browser-tool.ts index c118599137..1c392c9c2b 100644 --- a/packages/platform-web/src/agent-browser-tool.ts +++ b/packages/platform-web/src/agent-browser-tool.ts @@ -11,7 +11,6 @@ import { } from '@agent-device/host-kit/host-file'; import { AppError, asAppError } from '@agent-device/kernel/errors'; import type { HostEnvironment } from '@agent-device/kernel/source-value'; -import type { PlatformHost } from 'agent-device/plugins'; import type { ManagedWebBackendStatus } from '@agent-device/contracts/managed-web-backend'; import type { WebCommandResult } from './command-host.ts'; import { @@ -23,7 +22,7 @@ import { appendAgentDeviceChromeArgs, resolveAgentBrowserIdleTimeoutMs, } from './agent-browser-lifecycle.ts'; -import type { WebToolbox } from './toolbox.ts'; +import type { WebMachine, WebToolbox } from './toolbox.ts'; const MANAGED_AGENT_BROWSER_VERSION = '0.39.0'; @@ -144,11 +143,7 @@ function managedStatusOptions(options: { toolbox: WebToolbox; stateDir?: string * asked of the host so the status names paths, and a Node, the process that spawns the backend can * actually use. */ -export type WebStatusHost = HostEnvironment & - Pick< - PlatformHost, - 'hostOs' | 'nodeExecutablePath' | 'nodeVersion' | 'temporaryDirectory' | 'processId' - >; +export type WebStatusHost = HostEnvironment & WebMachine; /** * Where the managed backend is on disk, and whether it is there. Reads only the host's environment From 5a1b378a7f63f442aacf1bfd95e425440ab4fa48 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 21 Nov 2026 17:44:39 +0100 Subject: [PATCH 07/11] test(linux): answer the host's machine and process facts in the plugin test host --- packages/platform-linux/src/index.test.ts | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/packages/platform-linux/src/index.test.ts b/packages/platform-linux/src/index.test.ts index d4bc99af38..f3ef830749 100644 --- a/packages/platform-linux/src/index.test.ts +++ b/packages/platform-linux/src/index.test.ts @@ -29,6 +29,29 @@ function createPluginHost( env: input.env ?? { PATH: '/usr/bin', XDG_SESSION_TYPE: 'x11' }, cwd: '/host-cwd', stateDir: '/host-state', + // What the host says about the machine its commands run on. This family reads none of it: the + // desktop tools it drives are probed and spawned through the host. + hostOs: 'linux', + nodeExecutablePath: '/usr/bin/node', + nodeVersion: 'v24.0.0', + temporaryDirectory: '/tmp', + processId: 4242, + isExecutableOnPath: async (executable) => (tools === undefined ? false : tools.has(executable)), + // The family tracks no host process records: `close` ends an app through the desktop tools. + processes: { + list: async () => [], + readIdentities: async () => new Map(), + expandTree: (rootPids, processes) => + [...processes].filter((processInfo) => [...rootPids].includes(processInfo.pid)), + judgeRecordedLiveness: async (records) => [...records].map(() => 'unobserved' as const), + readExecutablePaths: async () => new Map(), + reapOwnedRecords: async () => { + throw new Error('the Linux family never reaps host processes'); + }, + withLock: async () => { + throw new Error('the Linux family takes no host lock'); + }, + } satisfies PlatformHost['processes'], runCommand: async (executable, args, options) => { commands.push({ executable, args, env: options.env }); return { stdout: '', stderr: '', exitCode: 0 }; From 37ef7fa857abc7089c662333ab5876932de665d3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 21 Nov 2026 17:45:08 +0100 Subject: [PATCH 08/11] test(layering): fit the policy test within its line cap --- scripts/layering/platform-package-policy.test.ts | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/scripts/layering/platform-package-policy.test.ts b/scripts/layering/platform-package-policy.test.ts index ccb5c3b5f9..5bc5ef2b9e 100644 --- a/scripts/layering/platform-package-policy.test.ts +++ b/scripts/layering/platform-package-policy.test.ts @@ -551,8 +551,7 @@ test('the web interactor subpath is loaded only by the builtin registry, dynamic assert.notDeepEqual(messages(sources), [], `${family} ${file} ${source}`); } - // A built-in package that declares a subpath nobody enumerated is rejected: the only declared - // exceptions are the Apple and Android facets, and a new seam has to be named here first. + // A built-in package that declares an unenumerated subpath is rejected (only Apple/Android facets). const undeclared = declarations().map((declaration) => declaration.family === 'android' ? { From bde31446a0131e341d86be355a58c60fe51c8812 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 21 Nov 2026 17:48:25 +0100 Subject: [PATCH 09/11] refactor(linux): read the host OS and pace input without the bundled host kit --- .../src/__tests__/atspi-bridge.test.ts | 29 ++++++++----------- packages/platform-linux/src/atspi-bridge.ts | 3 +- packages/platform-linux/src/command-runner.ts | 6 +++- packages/platform-linux/src/tool-provider.ts | 1 + .../platform-linux/src/toolbox.fixtures.ts | 3 ++ 5 files changed, 22 insertions(+), 20 deletions(-) diff --git a/packages/platform-linux/src/__tests__/atspi-bridge.test.ts b/packages/platform-linux/src/__tests__/atspi-bridge.test.ts index ae490e2353..f347cb28b7 100644 --- a/packages/platform-linux/src/__tests__/atspi-bridge.test.ts +++ b/packages/platform-linux/src/__tests__/atspi-bridge.test.ts @@ -1,7 +1,6 @@ import { test } from 'vitest'; import assert from 'node:assert/strict'; import path from 'node:path'; -import { withMockedPlatform } from '@agent-device/test-kit'; import { createLinuxHostStub, type LinuxHostStub } from '../toolbox.fixtures.ts'; import { createLinuxToolProvider } from '../tool-provider.ts'; import { resolveLinuxAtspiScriptPath } from '../atspi-script.ts'; @@ -52,7 +51,7 @@ const TREE = JSON.stringify({ test('the AT-SPI capture runs the helper shipped with the plugin', async () => { const stub = stubPython(TREE); - await withMockedPlatform('linux', () => captureAtspi(stub)); + await captureAtspi(stub); const command = stub.commands[0]!; assert.equal(command.executable, 'python3'); @@ -65,9 +64,7 @@ test('the AT-SPI capture runs the helper shipped with the plugin', async () => { test('the AT-SPI capture passes the surface and traversal limits', async () => { const stub = stubPython(TREE); - await withMockedPlatform('linux', () => - captureAtspi(stub, 'frontmost-app', { maxNodes: 10, maxDepth: 3, maxApps: 2 }), - ); + await captureAtspi(stub, 'frontmost-app', { maxNodes: 10, maxDepth: 3, maxApps: 2 }); assert.deepEqual(stub.commands[0]!.args.slice(1), [ '--surface', @@ -84,7 +81,7 @@ test('the AT-SPI capture passes the surface and traversal limits', async () => { test('the AT-SPI capture falls back to the helper defaults and tolerates a non-zero probe answer', async () => { const stub = stubPython(TREE); - await withMockedPlatform('linux', () => captureAtspi(stub)); + await captureAtspi(stub); const command = stub.commands[0]!; assert.deepEqual(command.args.slice(3), [ @@ -102,7 +99,7 @@ test('the AT-SPI capture falls back to the helper defaults and tolerates a non-z test('the AT-SPI capture maps helper roles through the family role map', async () => { const stub = stubPython(TREE); - const result = await withMockedPlatform('linux', () => captureAtspi(stub)); + const result = await captureAtspi(stub); assert.deepEqual(result.nodes, [ { @@ -133,7 +130,7 @@ test('the AT-SPI capture reports the missing PyGObject bindings as a missing too }); await assert.rejects( - () => withMockedPlatform('linux', () => captureAtspi(stub)), + () => captureAtspi(stub), (error: unknown) => { assert.ok(error instanceof AppError); assert.equal(error.code, 'TOOL_MISSING'); @@ -147,7 +144,7 @@ test('the AT-SPI capture reports a helper that failed for another reason', async const stub = stubPython('', { exitCode: 2, stderr: 'Display :0 not found' }); await assert.rejects( - () => withMockedPlatform('linux', () => captureAtspi(stub)), + () => captureAtspi(stub), (error: unknown) => { assert.ok(error instanceof AppError); assert.equal(error.code, 'COMMAND_FAILED'); @@ -161,7 +158,7 @@ test('the AT-SPI capture reports output it cannot parse', async () => { const stub = stubPython('not json'); await assert.rejects( - () => withMockedPlatform('linux', () => captureAtspi(stub)), + () => captureAtspi(stub), (error: unknown) => { assert.ok(error instanceof AppError); assert.equal(error.code, 'COMMAND_FAILED'); @@ -177,7 +174,7 @@ test('the AT-SPI capture reports the helper own error answer', async () => { ); await assert.rejects( - () => withMockedPlatform('linux', () => captureAtspi(stub)), + () => captureAtspi(stub), (error: unknown) => { assert.ok(error instanceof AppError); assert.equal(error.code, 'COMMAND_FAILED'); @@ -194,7 +191,7 @@ test('the AT-SPI capture asks before spawning when the host has no python3', asy }); await assert.rejects( - () => withMockedPlatform('linux', () => captureAtspi(stub)), + () => captureAtspi(stub), (error: unknown) => { assert.ok(error instanceof AppError); assert.equal(error.code, 'TOOL_MISSING'); @@ -206,12 +203,10 @@ test('the AT-SPI capture asks before spawning when the host has no python3', asy }); test('the AT-SPI capture refuses off a Linux host without touching it', async () => { - const stub = stubPython(TREE); - - // The check is the host's own platform, so the run has to mock it: the Linux lanes this suite also - // runs on would otherwise be on a Linux host and the capture would go on to spawn. + // The check is the operating system the setup host reports, not the machine running the test. + const stub = createLinuxHostStub({ hostOs: 'darwin', tools: ['python3'] }); await assert.rejects( - () => withMockedPlatform('darwin', () => captureAtspi(stub)), + () => captureAtspi(stub), (error: unknown) => { assert.ok(error instanceof AppError); assert.equal(error.code, 'UNSUPPORTED_PLATFORM'); diff --git a/packages/platform-linux/src/atspi-bridge.ts b/packages/platform-linux/src/atspi-bridge.ts index 6fbc6ba548..09c7bda3d4 100644 --- a/packages/platform-linux/src/atspi-bridge.ts +++ b/packages/platform-linux/src/atspi-bridge.ts @@ -10,7 +10,6 @@ import { AppError } from '@agent-device/kernel/errors'; import type { RawSnapshotNode, Rect } from '@agent-device/kernel/snapshot'; -import { hostPlatform } from '@agent-device/host-kit/process'; import type { LinuxAccessibilityProvider } from '@agent-device/contracts/linux-tool-provider'; import { normalizeAtspiRole } from './role-map.ts'; import type { LinuxCommandRunner } from './command-runner.ts'; @@ -50,7 +49,7 @@ export function createLinuxAccessibilityProvider( ): LinuxAccessibilityProvider { return { async captureTree(surface, options = {}) { - if (hostPlatform() !== 'linux') { + if (commands.hostOs !== 'linux') { throw new AppError('UNSUPPORTED_PLATFORM', 'AT-SPI2 bridge is only available on Linux'); } diff --git a/packages/platform-linux/src/command-runner.ts b/packages/platform-linux/src/command-runner.ts index 014c4072cd..b87246a3df 100644 --- a/packages/platform-linux/src/command-runner.ts +++ b/packages/platform-linux/src/command-runner.ts @@ -1,7 +1,8 @@ import path from 'node:path'; import type { PlatformHost } from 'agent-device/plugins'; import { AppError, normalizeError } from '@agent-device/kernel/errors'; -import { sleep } from '@agent-device/host-kit/retry'; +import { setTimeout as sleep } from 'node:timers/promises'; +import type { HostOperatingSystem } from '@agent-device/contracts/platform-runtime-host'; import type { LinuxCommandOptions, LinuxCommandResult, @@ -25,6 +26,8 @@ export type LinuxCommandRunner = Readonly<{ args: readonly string[], options?: LinuxCommandOptions, ): Promise; + /** The operating system of the host the family was set up with. */ + hostOs: HostOperatingSystem; /** True when the host resolves `cmd` on its `PATH`, or when `cmd` names an executable path. */ which(cmd: string): Promise; /** @@ -59,6 +62,7 @@ export function createLinuxCommandRunner(host: PlatformHost): LinuxCommandRunner const env = host.env; return Object.freeze({ run: async (cmd, args, options) => await host.runCommand(cmd, [...args], { ...options, env }), + hostOs: host.hostOs, which: async (cmd) => await hostResolvesExecutable(host, env, cmd), launchDetached: (cmd, args) => { // A host that cannot start a process outliving the request cannot open a desktop app: waiting diff --git a/packages/platform-linux/src/tool-provider.ts b/packages/platform-linux/src/tool-provider.ts index bb1c34b329..0f76c4b799 100644 --- a/packages/platform-linux/src/tool-provider.ts +++ b/packages/platform-linux/src/tool-provider.ts @@ -50,6 +50,7 @@ function withCommandOverrides( overrides: LinuxToolProviderOverrides, ): LinuxToolbox['commands'] { return Object.freeze({ + hostOs: commands.hostOs, run: overrides.runCommand ?? commands.run, which: overrides.whichCommand ?? commands.which, launchDetached: overrides.launchDetached ?? commands.launchDetached, diff --git a/packages/platform-linux/src/toolbox.fixtures.ts b/packages/platform-linux/src/toolbox.fixtures.ts index 5f4e459267..24c0dfe532 100644 --- a/packages/platform-linux/src/toolbox.fixtures.ts +++ b/packages/platform-linux/src/toolbox.fixtures.ts @@ -64,6 +64,8 @@ const NO_ANSWER: LinuxCommandResult = Object.freeze({ export function createLinuxHostStub( input: Readonly<{ env?: Readonly>; + /** The operating system the host reports; Linux unless a test needs another. */ + hostOs?: 'darwin' | 'linux' | 'win32' | 'other'; /** Tools the host can execute. When set, `isFileExecutable` answers from it alone. */ tools?: Iterable; /** Answers one command. Takes precedence over the queued answers. */ @@ -112,6 +114,7 @@ export function createLinuxHostStub( } const host = Object.freeze({ env, + hostOs: input.hostOs ?? 'linux', cwd: '/host-cwd', stateDir: '/host-state', emitDiagnostic: (event: LinuxHostDiagnostic) => { From 1b94a434a04569a101af3f6e6909c4bdf52046c2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 21 Nov 2026 17:56:22 +0100 Subject: [PATCH 10/11] style(layering): format the policy test within its line cap --- scripts/layering/platform-package-policy.test.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/scripts/layering/platform-package-policy.test.ts b/scripts/layering/platform-package-policy.test.ts index 5bc5ef2b9e..03c64c4c12 100644 --- a/scripts/layering/platform-package-policy.test.ts +++ b/scripts/layering/platform-package-policy.test.ts @@ -408,8 +408,7 @@ test('R13 leaves the Android test-only fixture subpaths to R83 for every consume allowed.set('test/integration/provider-scenarios/android.test.ts', fixtureImport); assert.deepEqual(messages(allowed), []); - // Production importers of a fixture are R83's to refuse (package-export-surface.test.ts); - // R13 holds no second list of them. + // Production importers of a fixture are R83's to refuse (package-export-surface.test.ts), not R13's. for (const file of [ 'packages/command-surface/src/replay/index.ts', 'src/core/interactors/android.ts', @@ -528,7 +527,8 @@ test('the web interactor subpath is loaded only by the builtin registry, dynamic 'src/core/interactors/register-builtins.ts', `const load = () => import('@agent-device/platform-${family}/interactor');`, ); - assert.deepEqual(checkPlatformPackagePolicy(allowed, declarations(), policyOptions()), [], family); + const found = checkPlatformPackagePolicy(allowed, declarations(), policyOptions()); + assert.deepEqual(found, [], family); for (const [file, source] of [ [ From b2834683a94e7c9392242fc2e58821eb7a47b651 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 21 Nov 2026 18:22:52 +0100 Subject: [PATCH 11/11] fix(vega): print the doctor install hint with POSIX separators on every host --- packages/platform-vega/src/doctor.ts | 3 +-- packages/platform-vega/src/vega-executable.ts | 2 +- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/packages/platform-vega/src/doctor.ts b/packages/platform-vega/src/doctor.ts index 9c5246c8ed..1ac36651ce 100644 --- a/packages/platform-vega/src/doctor.ts +++ b/packages/platform-vega/src/doctor.ts @@ -3,7 +3,6 @@ import { AppError } from '@agent-device/kernel/errors'; import type { DoctorCheck } from '@agent-device/contracts/observability'; import type { HostDiagnosticsContext } from '@agent-device/contracts/host-diagnostics'; import { firstOutputLine, TOOLCHAIN_TIMEOUT_MS } from '@agent-device/provision-kit/toolchain-probe'; -import { vegaDefaultInstallPath } from './vega-executable.ts'; import { createVegaToolProvider, hasScopedVegaToolProvider, @@ -34,7 +33,7 @@ export async function vegaToolchainCheck( id: 'toolchain', status: 'info', summary: 'Vega toolchain: Vega CLI not found.', - hint: `Install Vega Developer Tools or ensure ${vegaDefaultInstallPath('~')} is executable.`, + hint: 'Install Vega Developer Tools or ensure ~/vega/bin/vega is executable.', command: 'vega --version', }; } diff --git a/packages/platform-vega/src/vega-executable.ts b/packages/platform-vega/src/vega-executable.ts index 969852ecc2..3b0fa86a5b 100644 --- a/packages/platform-vega/src/vega-executable.ts +++ b/packages/platform-vega/src/vega-executable.ts @@ -25,6 +25,6 @@ async function lookupVegaExecutable(host: VegaExecutableHost): Promise