Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
108 changes: 108 additions & 0 deletions docs/evidence/vega-managed-platform-2026-11-21.md
Original file line number Diff line number Diff line change
@@ -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.
139 changes: 139 additions & 0 deletions docs/evidence/web-managed-platform-2026-11-21.md
Original file line number Diff line number Diff line change
@@ -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 <entryScript>`, 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.
12 changes: 11 additions & 1 deletion packages/contracts/src/platform-runtime-host.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -179,7 +188,8 @@ export type DeviceInventoryHostByFamily = Readonly<{
android: Pick<DeviceInventoryHost, 'commands' | 'files' | 'homeDirectory' | 'toolchains'>;
/** The HarmonyOS plugin carries its own host, so its inventory asks the core for nothing. */
harmonyos: never;
vega: Pick<DeviceInventoryHost, 'commands' | 'files' | 'homeDirectory'>;
/** The Vega plugin carries its own host, so its inventory asks the core for nothing. */
vega: never;
linux: Pick<DeviceInventoryHost, 'hostName' | 'hostOs'>;
web: never;
}>;
Expand Down
6 changes: 4 additions & 2 deletions packages/contracts/src/vega-tool-provider.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
11 changes: 2 additions & 9 deletions packages/device-selection/src/composed-inventory-gateways.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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':
Expand All @@ -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 });
}
Expand Down
6 changes: 5 additions & 1 deletion packages/host-kit/src/process.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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. */
Expand Down
50 changes: 50 additions & 0 deletions packages/kernel/src/errors.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<string, unknown>,
): Record<string, unknown> {
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<R extends CommandFailureAnswer>(
answer: R,
message: string,
extra?: Record<string, unknown> | ((answer: R) => Record<string, unknown>),
): 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[];
Expand Down
Loading
Loading