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..a500206b53 --- /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 +`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}} +{"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..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. @@ -179,7 +188,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/host-kit/src/process.ts b/packages/host-kit/src/process.ts index 9a8eedfae2..382c5c92fb 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, @@ -58,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/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/__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 0cb02577f1..081658b8dc 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'; @@ -34,13 +34,36 @@ 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 }; }, - // 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), + // Neither this family nor its devices are host processes: everything goes through HDC. + 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 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-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-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/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 }; 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) => { 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..9ad5dbda34 --- /dev/null +++ b/packages/platform-vega/src/command-host.fixtures.ts @@ -0,0 +1,178 @@ +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', + // 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(), + isFileExecutable: async (candidate: string) => executableFiles.has(candidate), + isExecutableOnPath: async (executable: string) => { + pathProbes += 1; + return onPath.has(executable); + }, + // Neither this family nor its devices are host processes: everything goes through the Vega CLI. + 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 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, + 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..1ac36651ce 100644 --- a/packages/platform-vega/src/doctor.ts +++ b/packages/platform-vega/src/doctor.ts @@ -2,30 +2,32 @@ 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 { - 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', diff --git a/packages/platform-vega/src/index.test.ts b/packages/platform-vega/src/index.test.ts index 6520777503..83d77c6d23 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,75 @@ 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', + // 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 }; + }, + // 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), + // Neither this family nor its devices are host processes: everything goes through the Vega CLI. + 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 Vega family never reaps host processes'); + }, + withLock: async () => { + throw new Error('the Vega family takes no host lock'); + }, + } satisfies PlatformHost['processes'], 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 +109,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 +148,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..e073ec46be --- /dev/null +++ b/packages/platform-vega/src/toolbox.ts @@ -0,0 +1,22 @@ +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 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<{ + /** The Vega CLI route: one resolver over the host, one spawn per call. */ + commands: VegaCommandRunner; +}>; + +export function createVegaToolbox(host: PlatformHost): VegaToolbox { + return Object.freeze({ + commands: createVegaCommandRunner(host), + }); +} diff --git a/packages/platform-vega/src/vega-executable.ts b/packages/platform-vega/src/vega-executable.ts index 64cd9db278..3b0fa86a5b 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. */ +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-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..9469d0634f --- /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, realHostMachineFacts, 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(), ...realHostMachineFacts() }, + }); + 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..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,31 +1,49 @@ import assert from 'node:assert/strict'; import { beforeEach, test, vi } from 'vitest'; -import type { OwnedProcessRecord } from '@agent-device/contracts/platform-runtime-host'; 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[], ), })); -vi.mock('@agent-device/host-kit/process', async (importOriginal) => ({ - ...(await importOriginal()), - readHostProcessIdentityObservationsAsync: observationsMock, - isProcessAlive: isProcessAliveMock, -})); +const mockJudge = vi.mocked(judgeMock); + +/** 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(), + 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'); + }, + withLock: async () => { + throw new Error('the record probe takes no host lock'); + }, + }; +} -const mockObservations = vi.mocked(observationsMock); -const mockIsProcessAlive = vi.mocked(isProcessAliveMock); +const processes = createProcessPort(); function record(pid: number, startTime = `start-${pid}`): OwnedProcessRecord { return { @@ -74,186 +92,120 @@ 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)])]), + processes, ), 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)])]), - ), - 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)])])), - 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)])])), + await managedWebBrowserProcessRecordIsLive( + storeReturning([daemonEntry([record(11)])]), + processes, + ), false, ); }); -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)])])), - 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 () => { - assert.equal(await managedWebBrowserProcessRecordIsLive(storeReturning([])), false); +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([])])), + 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)])])), + await managedWebBrowserProcessRecordIsLive( + storeReturning([sessionEntry([record(11)])]), + processes, + ), 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), false); - assert.equal(mockObservations.mock.calls.length, 0); + assert.equal(await managedWebBrowserProcessRecordIsLive(store, processes), false); + 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()])), - 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), false); - assert.equal(mockObservations.mock.calls.length, 0); + assert.equal(await managedWebBrowserProcessRecordIsLive(store, processes), false); + 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)])]), + processes, ), 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)])]), - ), - 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)])])), - 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([undecodableDaemonEntry()])), - 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), false); - assert.equal(await managedWebBrowserProcessRecordIsDead(store), false); - }, -); 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..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,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, realHostProcessReads } from '../toolbox.fixtures.ts'; bindTestCommandHost(); @@ -147,7 +148,13 @@ async function withFleetRecordStore( store.replace({ kind: 'daemon' }, [seed]); await runScenario({ provider: createAgentBrowserWebProvider({ - host: { env: process.env, cwd: process.cwd() }, + 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/__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-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 bfd3e77e66..68808ddcaa 100644 --- a/packages/platform-web/src/agent-browser-install.ts +++ b/packages/platform-web/src/agent-browser-install.ts @@ -1,18 +1,13 @@ 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, 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, @@ -23,12 +18,15 @@ export async function installManagedAgentBrowserPackage(params: { packageSpec: string; timeoutMs: number; env: Readonly; - runCommand?: PlatformHost['runCommand']; + /** 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, @@ -38,7 +36,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, }); @@ -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 2e69acd2f1..62bcd897b1 100644 --- a/packages/platform-web/src/agent-browser-lifecycle.test.ts +++ b/packages/platform-web/src/agent-browser-lifecycle.test.ts @@ -44,21 +44,9 @@ const identitiesMock = vi.hoisted(() => ), ); -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, - }; -}); +// 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 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, @@ -77,11 +65,79 @@ import { import { getManagedAgentBrowserStatus } from './agent-browser-tool.ts'; import { createOwnedProcessRecordStore, + expandProcessTree, + listHostProcesses, 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 + * 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]), + expandTree: (rootPids, processes) => expandProcessTree([...rootPids], [...processes]), + judgeRecordedLiveness: async (records) => + probe.unanswered + ? [...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), + reapOwnedRecords: async (store, options) => + await reapOwnedProcessRecordsAtStartup(store, options), + withLock: async () => { + throw new Error('the lifecycle suite takes no host lock'); + }, + }; +} + +/** 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 = { + ...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, + args: string[], + options: { env?: NodeJS.ProcessEnv; timeoutMs?: number; stdin?: string }, + ) => await runCmdMock(executable, args, options), + isFileExecutable: async () => false, + isExecutableOnPath: async () => false, + processes: createHostProcessPort(), + emitDiagnostic: () => {}, + withDiagnosticTimer: async (_phase: string, operation: () => Promise): Promise => + await operation(), + }; + return createWebToolbox(host as unknown as Parameters[0]); +} const mockRunCmd = vi.mocked(runCmdMock); @@ -104,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); @@ -143,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', () => { @@ -152,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( @@ -201,10 +257,12 @@ 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, + emitDiagnostic: () => {}, + processes: hostProcesses, openWebSessionNames: ['default-web'], }); @@ -246,10 +304,12 @@ 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, + emitDiagnostic: () => {}, + processes: hostProcesses, ownedProcessRecords, }); @@ -270,10 +330,12 @@ 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, + emitDiagnostic: () => {}, + processes: hostProcesses, ownedProcessRecords, startingSession: 'fleet-web', }); @@ -296,10 +358,12 @@ 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, + emitDiagnostic: () => {}, + processes: hostProcesses, ownedProcessRecords, }); @@ -323,10 +387,12 @@ 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, + emitDiagnostic: () => {}, + processes: hostProcesses, ownedProcessRecords, }); @@ -347,13 +413,15 @@ 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'), ''); const result = await cleanupManagedAgentBrowserOrphans(status, 'daemon-startup', { env: process.env, + emitDiagnostic: () => {}, + processes: hostProcesses, }); assert.equal(result.skipped?.reason, 'recent-browser-activity'); @@ -376,13 +444,15 @@ 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 }); const result = await cleanupManagedAgentBrowserOrphans(status, 'daemon-startup', { env: process.env, + emitDiagnostic: () => {}, + processes: hostProcesses, }); assert.equal(result.skipped, undefined); @@ -435,10 +505,12 @@ 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, + emitDiagnostic: () => {}, + processes: hostProcesses, ownedProcessRecords, }); @@ -462,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( @@ -472,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); @@ -544,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(); @@ -561,9 +634,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 }); } @@ -576,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); @@ -591,7 +665,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 }); @@ -604,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[] = [ @@ -619,7 +696,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', @@ -645,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( @@ -698,7 +779,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', @@ -723,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[] = [ @@ -761,7 +846,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 }); @@ -774,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 }]); @@ -783,7 +872,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 }); @@ -796,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 }, @@ -828,7 +920,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[] = []; @@ -880,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, @@ -894,10 +986,12 @@ 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 1338a4a7b2..01949fbfa0 100644 --- a/packages/platform-web/src/agent-browser-lifecycle.ts +++ b/packages/platform-web/src/agent-browser-lifecycle.ts @@ -1,12 +1,10 @@ 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 { 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 { OwnedProcessRecordStore } 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 +41,12 @@ 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; + /** The host that reads and stops the recorded processes: the plugin was set up with it. */ + processes: PlatformHost['processes']; 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; }; @@ -81,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, @@ -96,7 +102,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..9f2b17737c 100644 --- a/packages/platform-web/src/agent-browser-process-record.ts +++ b/packages/platform-web/src/agent-browser-process-record.ts @@ -1,29 +1,20 @@ -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 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 { withoutCommandExecutorOverride } from '@agent-device/host-kit/command'; -import { - expandProcessTree, - hostProcessId, - hostPlatform, - isProcessAlive, - processStartTimesDiffer, - listHostProcesses, - readHostProcessIdentityObservationsAsync, - readProcessIdentities, - readProcessExecutablePaths, - 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 { WebMachine, WebToolbox } from './toolbox.ts'; const HOST_PROCESS_LIST_TIMEOUT_MS = 1_500; const AGENT_DEVICE_BROWSER_MARKER_PREFIX = '--agent-device-managed-web='; @@ -66,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) && @@ -87,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; @@ -103,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 { @@ -132,21 +131,23 @@ 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, toolbox.host); } export async function recordManagedAgentBrowserProcesses( status: AgentBrowserToolStatus, store: OwnedProcessRecordStore, - host: HostEnvironment, + toolbox: WebToolbox, ): Promise { - const initial = await listRealHostProcesses(); + const { host } = toolbox; + 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 after = await readProcessIdentities(pids); + const before = await toolbox.host.processes.readIdentities(pids); + const scanned = await listRealHostProcesses(toolbox); + 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); @@ -162,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), @@ -177,6 +183,7 @@ export async function recordManagedAgentBrowserProcesses( processInfo, ownership, executablePaths.get(processInfo.pid), + host, )?.reason ?? 'descendant', })), }; @@ -203,8 +210,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'); } @@ -216,33 +224,24 @@ 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'); } -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 readHostProcessIdentityObservationsAsync( - 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); } /** @@ -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.processes.list({ timeoutMs: HOST_PROCESS_LIST_TIMEOUT_MS }))]; } function summarizeMatches( @@ -308,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]; @@ -358,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-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..38e7492430 100644 --- a/packages/platform-web/src/agent-browser-provider.ts +++ b/packages/platform-web/src/agent-browser-provider.ts @@ -1,10 +1,10 @@ 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'; +// 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, type DispatchDisclosure, discloseDispatchAfterSteps, } from '@agent-device/kernel/errors'; @@ -27,6 +27,7 @@ import { readStringProperty, type JsonObject, } from './json-utils.ts'; +import type { WebToolbox } from './toolbox.ts'; import type { WebProvider, WebSnapshotOptions, @@ -36,7 +37,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 +52,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 +614,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 +623,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 +688,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) }, @@ -735,31 +736,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( @@ -783,12 +782,14 @@ 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, + processes: host.processes, 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..d403704546 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, realHostMachineFacts } 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 }); } @@ -118,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); @@ -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, }); }, ); @@ -297,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 c4c6bb234c..1c392c9c2b 100644 --- a/packages/platform-web/src/agent-browser-tool.ts +++ b/packages/platform-web/src/agent-browser-tool.ts @@ -1,7 +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, ensureHostDirectorySync, @@ -12,16 +9,10 @@ import { readHostTextFileSync, removeHostFileSync, } from '@agent-device/host-kit/host-file'; -import { - hostNodeExecutablePath, - 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'; import type { ManagedWebBackendStatus } from '@agent-device/contracts/managed-web-backend'; +import type { WebCommandResult } from './command-host.ts'; import { installManagedAgentBrowserPackage, writeManagedAgentBrowserManifest, @@ -31,6 +22,7 @@ import { appendAgentDeviceChromeArgs, resolveAgentBrowserIdleTimeoutMs, } from './agent-browser-lifecycle.ts'; +import type { WebMachine, WebToolbox } from './toolbox.ts'; const MANAGED_AGENT_BROWSER_VERSION = '0.39.0'; @@ -40,12 +32,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,95 +52,120 @@ export type ManagedAgentBrowserRunOptions = { export async function runManagedAgentBrowser( args: readonly string[], options: ManagedAgentBrowserRunOptions, -): Promise { - const status = getManagedAgentBrowserStatus({ host: options.host, stateDir: options.stateDir }); - if (!status.installed) throw missingManagedToolError(status); +): Promise { + const status = getManagedAgentBrowserStatus({ + host: options.toolbox.host, + stateDir: options.stateDir, + }); + if (!status.installed) throw missingManagedToolError(status, options.toolbox.host); return await spawnManagedAgentBrowser(status, args, options); } export async function setupManagedAgentBrowser(options: { - host: ManagedBrowserHost; + toolbox: WebToolbox; stateDir?: string; }): Promise { - const status = getManagedAgentBrowserStatus(options); - assertWebNodeSupported(status.nodeMajor); - const processId = hostProcessId(); + const status = getManagedAgentBrowserStatus(managedStatusOptions(options)); + assertWebNodeSupported(status.nodeMajor, options.toolbox.host); - return await withProcessLock({ - acquire: () => - acquireProcessLock({ - lockDirPath: path.join(status.installDir, '..', '.agent-browser-install.lock'), - owner: { - pid: processId, - startTime: readProcessStartTime(processId), - 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(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, + machine: options.toolbox.host, + 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({ installDir: installedStatus.installDir, packageName: AGENT_BROWSER, version: MANAGED_AGENT_BROWSER_VERSION, + machine: options.toolbox.host, }); - 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); + throw missingManagedToolError(status, options.toolbox.host); } const result = await spawnManagedAgentBrowser(status, ['doctor', '--offline', '--quick'], { - host: options.host, + toolbox: options.toolbox, timeoutMs: DOCTOR_TIMEOUT_MS, allowFailure: true, }); return { status, ...result }; } +/** Reads a status for the host one of the toolbox-taking operations was set up with. */ +function managedStatusOptions(options: { toolbox: WebToolbox; stateDir?: string }): { + host: WebStatusHost; + stateDir?: string; +} { + return { + host: options.toolbox.host, + ...(options.stateDir === undefined ? {} : { stateDir: options.stateDir }), + }; +} + +/** + * 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 & WebMachine; + +/** + * 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: { - host: ManagedBrowserHost; + /** Either the calling runtime's host or the plugin's own host; both answer the same way. */ + 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, @@ -173,14 +188,14 @@ async function spawnManagedAgentBrowser( status: AgentBrowserToolStatus, args: readonly string[], options: Omit, -): Promise { - if (!status.entryScript) throw missingManagedToolError(status); - return await (options.host.runCommand ?? runCmd)( - hostNodeExecutablePath(), +): Promise { + if (!status.entryScript) throw missingManagedToolError(status, options.toolbox.host); + return await options.toolbox.commands.run( + options.toolbox.host.nodeExecutablePath, [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, @@ -271,18 +286,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.', }); } @@ -298,10 +313,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/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..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 { @@ -17,15 +18,34 @@ 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 } from '@agent-device/host-kit/command'; +import { runCmd, isExecutablePath, whichCmd } from '@agent-device/host-kit/command'; function cleanupWebBrowserOrphansForDaemonStartup(stateDir: string) { const host = { ...createLiveTestHostEnvironment(), + ...realHostMachineFacts(), stateDir, runCommand: runCmd, isFileExecutable: isExecutablePath, + isExecutableOnPath: async (executable: string) => await whichCmd(executable, process.env), + // 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(), + 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'); + }, + withLock: async () => { + throw new Error('this suite stands the install lock in for'); + }, + } satisfies PlatformHost['processes'], emitDiagnostic, withDiagnosticTimer, }; @@ -50,6 +70,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 a335feb46c..03b193e5f3 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,50 @@ 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, + processes: bound.host.processes, 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..eb7aefa832 --- /dev/null +++ b/packages/platform-web/src/toolbox.fixtures.ts @@ -0,0 +1,295 @@ +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 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. */ +export type WebHostStubCommand = Readonly<{ + executable: string; + args: readonly string[]; + env: Readonly> | undefined; + timeoutMs: number | undefined; + allowFailure: boolean | undefined; + signal: AbortSignal | undefined; + 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: 'executable-paths'; pids: readonly number[] } + | { kind: 'liveness'; pids: readonly number[] } + | { + kind: 'reap'; + pids: []; + 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. */ +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; + 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; +}>; + +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[]; + /** 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; +}>; + +/** + * 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. 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<{ + env?: Readonly>; + cwd?: string; + stateDir?: string; + /** Answers one process-table read; the plugin reads the table to derive its fleet record. */ + processes?: HostProcessInfo[]; + /** Answers the identity, liveness, executable-path and reap calls; defaults to nothing. */ + readProcesses?: (reads: WebHostStubProcessReads) => WebHostStubProcesses; + ownedProcessRecords?: PlatformHost['ownedProcessRecords']; + openWebSessionNames?: () => readonly string[]; + }> = {}, +): WebHostStub { + const commands: WebHostStubCommand[] = []; + const diagnostics: DiagnosticEventInput[] = []; + const processTable: HostProcessInfo[][] = []; + 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(); + }, + 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; + }, + // 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, + 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[], + 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, + processes, + 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, + processReads, + answerProcessTable: (reads: readonly HostProcessInfo[][]) => { + processTable.push(...reads.map((read) => [...read])); + 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), + 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, + inspectedPids: [], + terminated: 0, + terminatedPids: [], + missing: 0, + missingPids: [], + unconfirmed: 0, + unconfirmedPids: [], + survived: 0, + survivedPids: [], + skippedForOpenWebSession: false, +}; diff --git a/packages/platform-web/src/toolbox.ts b/packages/platform-web/src/toolbox.ts new file mode 100644 index 0000000000..a14ea35f14 --- /dev/null +++ b/packages/platform-web/src/toolbox.ts @@ -0,0 +1,42 @@ +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']; +}>; + +/** + * 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, + 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..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'; @@ -8,6 +8,99 @@ 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'); +} + +/** + * 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 + * 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 +126,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 +180,178 @@ 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); + + // 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); + + // 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 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'), + `the open request traced no process-table read out of ${openRecords.length} exec records: ${JSON.stringify( + 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'], + ['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..8482b59661 100644 --- a/packages/plugins/src/platform.test.ts +++ b/packages/plugins/src/platform.test.ts @@ -45,10 +45,29 @@ 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'); }, isFileExecutable: async () => false, + isExecutableOnPath: async () => false, + processes: { + list: async () => [], + readIdentities: 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'); + }, + 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 01a0abb16a..3090e501ae 100644 --- a/packages/plugins/src/platform.ts +++ b/packages/plugins/src/platform.ts @@ -13,10 +13,20 @@ 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 { OwnedProcessRecordStore } from '@agent-device/host-kit/process'; +import type { + HostProcessIdentityFacts, + HostProcessInfo, + OwnedProcessReapSummary, + OwnedProcessRecordStore, +} from '@agent-device/host-kit/process'; import type { HostEnvironment } from '@agent-device/kernel/source-value'; /** @@ -91,6 +101,39 @@ 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; + /** + * 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. + */ + 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 @@ -123,6 +166,88 @@ 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>; + /** + * 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 + * 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; + /** + * 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 ? Readonly<{ family: Family; 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 226a44c671..03c64c4c12 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', () => { @@ -503,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', @@ -560,7 +464,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 +489,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 +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()), [], family); + const found = checkPlatformPackagePolicy(allowed, declarations(), policyOptions()); + assert.deepEqual(found, [], family); for (const [file, source] of [ [ @@ -646,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' ? { @@ -679,7 +583,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 +602,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 +621,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 +630,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 +792,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 +802,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'/, @@ -924,9 +828,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', @@ -959,9 +864,137 @@ 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 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 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 { acquireProcessLock } from '@agent-device/host-kit/file';\nvoid acquireProcessLock;", + ); + assert.match(refused, /host-kit\/file' scope at runtime \(acquireProcessLock\)/); + const allowed = hostKitFindings( + 'web', + "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', () => { + 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, 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', + "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`, + ], + [ + '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', + "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 1b07364a8b..ed69a9e9b6 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, @@ -115,60 +126,74 @@ 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', -]; +/** + * 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. + */ -// 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': [], -}; - -function isManagedHostKitScope(spec: string): boolean { - return MANAGED_HOST_KIT_SCOPES.some((scope) => spec === scope || spec.startsWith(`${scope}/`)); -} +// 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. +// +// 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: 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 ' + + 'setup, which answers 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[]; + typeSymbols?: readonly string[]; + }, managedName: string, + reach: HostKitReachIndex, ): LayeringViolation[] { - if (site.typeOnly || !isManagedHostKitScope(site.spec)) return []; - if ((MANAGED_HOST_KIT_IMPORT_DEBT[managedName] ?? []).includes(file)) return []; + if (site.typeOnly) return []; + // 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: 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', + `${managedName} may not import the host-kit '${site.spec}' scope at runtime ` + + `(${[...reached].sort().join(', ')})` + + MANAGED_HOST_KIT_SCOPE_MESSAGE, ), ]; } @@ -364,7 +389,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 @@ -452,7 +481,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/') && @@ -542,8 +571,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( @@ -552,9 +600,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)), ]; } 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.test.ts b/src/platform-runtime/plugin-host.test.ts index f7d9c13f65..72b838e7c5 100644 --- a/src/platform-runtime/plugin-host.test.ts +++ b/src/platform-runtime/plugin-host.test.ts @@ -1,8 +1,16 @@ 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 type { OwnedProcessRecord } from '@agent-device/contracts/platform-runtime-host'; +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 +95,185 @@ 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 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 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 []; + 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 a0a1387216..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); @@ -44,6 +59,11 @@ 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); + }, + processes: createPlatformPluginProcessPort(host), startBackgroundCommand: async (request, signal) => { processes ??= await loadManagedAppLogProcesses(sessionsDir, host.env); return await processes.start( @@ -65,6 +85,108 @@ 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. + * + * 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); + }, + 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); + }, + // 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, + }); + }, + }); +} + async function loadManagedAppLogProcesses(sessionsDir: string, env: HostEnvironment['env']) { const { createManagedAppLogProcesses } = await import('../platform-runtime-app-log-process.ts'); return createManagedAppLogProcesses(sessionsDir, env); 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); }