feat(vega): Amazon Vega (Fire TV) platform support

[finloop]

Summary

Adds Vega (Amazon Fire TV) as a third Argent platform alongside iOS and Android. Vega apps are React Native 0.72 + Hermes running on a QEMU Virtual Device (VVD), driven by a D-pad tv-remote rather than touch. This PR extends Argent's platform abstraction so the existing tool surface gates correctly on vega, and adds the Vega-specific tools needed to actually drive a Fire TV app end to end.

Platform abstraction

• Platform gains vega; DeviceKind gains vvd (the QEMU VVD); ToolCapability gains a vega { vvd, device } block; ToolDependency gains vega.
• assertSupported() selects the vega capability matrix for Vega devices; dispatchByPlatform() gains an optional vega branch, and a Vega dispatch with no branch throws NotImplementedOnPlatformError (501).
• New vega-cli util (modeled on adb.ts) resolves vega/kepler from PATH or ~/vega/bin with the same hardened exec/quoting; check-deps resolves and hints the vega dependency.
• The simulator-server blueprint is never wired for vega (Vega uses adb + the vega/kepler CLI, not the proprietary binary).

How Vega is wired

• Input / screenshot / describe go over adb (input via inputd-cli, screenshots host-side via the Android emulator console, element tree via the on-device automation toolkit).
• App lifecycle goes over the vega/kepler CLI.
• v1 is Virtual-Device-only: every Vega capability is declared vvd (physical Fire TV is unverified — declaring device would advertise support that silently returns empty results, so the capability gate rejects hardware up front).
• Vega runs React Native 0.72, which predates the new React Native DevTools. The CDP/Hermes debugger surface (debugger-*, React/native profilers) depends on integration points the new DevTools provides, so debugging and profiling are out of scope for this PR — Vega profiling/crash analysis is handled by the amazon-devices-buildertools-mcp server instead.

Also includes

• argent-vega skill documenting the full Vega workflow (target discovery, the describe → compute-path → tv-remote navigation loop, text injection).
• Vega VVD end-to-end CI workflow.

Feature support by platform

Legend: ✅ supported · ❌ not supported · ⚠️ degraded / conditional · — not applicable

Feature (tool)	iOS	Android	Chromium	Vega (VVD)	Vega notes
Device discovery (list-devices)	✅	✅	✅	✅	Tagged platform:"vega", kind:"vvd"; pass serial as udid
Boot / start device	✅	✅	—	✅
Launch app (launch-app)	✅	✅	✅	✅	bundleId = interactive-component app id from manifest.toml
Restart app (restart-app)	✅	✅	✅	✅	Terminate + relaunch
Reinstall app (reinstall-app)	✅	✅	❌	✅	Uninstall + install a .vpkg
Screenshot (screenshot)	✅	✅	✅	✅	Host-side via emulator console (needs adb); rotation ignored (fixed landscape)
Describe / element tree (describe)	✅	✅	✅	✅	On-device automation toolkit; surfaces [focused]/[selected] + normalized frames
Touch gestures (gesture-tap/swipe/scroll/drag/custom)	✅	✅	✅	❌	Vega is tv-remote-driven; gestures error — use tv-remote
Pinch / rotate gesture (gesture-pinch/gesture-rotate)	✅	❌	⚠️	❌	N/A on a TV
Remote / D-pad (tv-remote)	—	—	—	✅	Vega-only tool; single key, repeat, or a whole path in one call
Hardware buttons (button)	✅	✅	—	❌	Remote keys live in remote instead
Text input (keyboard)	✅	✅	✅	✅	Whole-string injection via inputd-cli send_text
Rotate orientation (rotate)	✅	✅	—	❌	TV framebuffer is fixed landscape
Open URL / deep link (open-url)	✅	✅	✅	❌	Not wired on Vega
JS debugger (debugger-*)	✅	✅	✅	❌	RN 0.72 predates the new RN DevTools — out of scope for this PR
Native devtools / AX (native-describe-screen, etc.)	✅	❌	—	❌	iOS-only
Native profiler (native-profiler-*)	✅	✅	—	❌	Use amazon-devices-buildertools-mcp (Perfetto) instead
React profiler (react-profiler-*)	✅	✅	—	❌	Out of scope; RN 0.72 / new RN DevTools not supported
Screenshot diff (screenshot-diff)	✅	✅	✅	✅	Host-side image comparison; platform-agnostic
Flows record/replay (flow-*)	✅	✅	✅	✅	Records any tool-call sequence

Test plan

• list-devices surfaces connected Vega devices (platform:"vega", kind:"vvd")
• launch-app, restart-app, reinstall-app, list-installed-apps work on Vega
• tv-remote drives focus (single key, repeat, and multi-key path) and keyboard injects whole strings
• screenshot returns a frame via the host-side VVD path
• describe returns the on-screen element tree with [focused] state and normalized coordinates
• Vega VVD e2e CI workflow passes
• Test multiple platforms being driven at the same time
  • Android + Vega
  • iOS + Vega
  • chrome + Vega

[latekvo]

Solid PR, we are really thankful as a team for you contribution :)

I only really dislike that this PR changes some unrelated things that are out of scope.

It also seems to me that remote could potentially map its gestures clearly onto tools we already expose, but i could be wrong.

[latekvo]

Static review of the Vega (Fire TV) platform support — no devices booted. Findings inline.

[finloop]

Review of the Vega (Fire TV) platform support. Findings below are inline, ordered roughly by severity — a few correctness issues around boot image selection, VVD/adb device correlation, describe parsing and dedup, plus some CI-guard and consistency notes.

[finloop]

bootVegaImpl resolves and validates image from vvdImage, but image.path is then never used and startVvd() is called without it — it runs vega virtual-device start -t <n> with no -p <path>. Combined with isVvdRunning() matching any virtual device, the vvdImage selector isn't actually honored:

• With tv already running, boot-device {vvdImage:"tablet"} returns early with tv's serial but labeled vvdImage:"tablet", so every later tool drives tv while the caller believes it's on tablet.
• With nothing running, startVvd boots the SDK default rather than the requested image.

Invisible on a single-image SDK, wrong for multi-image setups. vega-sdk.ts resolves VvdImage.path specifically to feed start -p, so either thread image.path into startVvd (and make the already-running check image-aware), or drop the per-image selector and document boot as 'the single SDK VVD'.

[finloop]

filterLiveSockets keeps a QMP socket whenever emulator-<port> is a live adb device, but never verifies that device is the VVD rather than a real Android emulator. If a prior VVD crashed leaving /tmp/qmp-socket-5554.sock while an Android emulator runs as emulator-5554, the stale socket is treated as live, discoverVegaConsolePort() returns 5554, and screenshot/tv-remote/keyboard/describe all drive the Android emulator instead of the VVD.

Separately, if (!connected) return names (line 44) fails open — a transient adb error returns every socket unfiltered, which can spuriously trip MultipleVegaDevicesError. Consider confirming the port maps to a VVD (cross-check vega device list / the running-VVD serial) before accepting the socket.

[finloop]

parseVegaPageSource(xml) runs outside the try/catch above, so a parse failure escapes as an unhandled error instead of the graceful empty-tree + relaunch hint. This is reachable: fetchVegaPageSource returns JSON.stringify(result ?? "") when the toolkit result isn't a string (vega-inspect.ts:54), and postJson never checks res.statusCode. So a toolkit HTTP error / structured body becomes non-XML JSON — if it's >50 chars, parseVegaXml returns null and throw new Error('Failed to parse Vega page source') crashes describe; if it's "", the screen is silently reported as empty. Suggest wrapping the parse in the same empty-tree fallback and checking the HTTP status in postJson.

[finloop]

/success/i.test(output) matches any substring success, including unsuccessful / was not successful. A failed install-app whose output contains those phrases is reported as { reinstalled: true }. Anchor the match to the actual success line (e.g. /\.\.\.\s*success\b/i) so a failure can't read as success.

[finloop]

const info = rows.length === 1 ? await readVegaInfo() : null plus the resolveVvdImageName fallback means that when vega device info fails or omits profile and ≥2 images are installed, the running VVD gets vvdImage:null. connectedImages is then empty, so the stopped-image loop re-emits that same running image as a state:"stopped" row — the device shows up twice (once running with vvdImage:null, once stopped with the image name). The existing test only covers the single-installed-image case, where the installedImages.length === 1 fallback happens to mask this.

[finloop]

This header tells the agent to count rows/columns from 'the [focused] element', but per the contract.ts note the toolkit usually reports the highlighted item via selected while focused stays false (the fixture has two [selected] and zero [focused]). As written the agent is told to anchor on a flag that's frequently absent, breaking the navigation instruction. Mention [selected] as the cursor fallback here so the guidance matches the data.

[finloop]

Each press is ... >/dev/null 2>&1 || true, and the only liveness gate is get_screen_size — which (per the TODO above) still succeeds when developer mode is off, even though button_press/send_text then silently fail. So tv-remote/keyboard return { pressed/typed, count } as if the input landed while nothing actually happened. Flagging since the false success is user-visible; gating on a dev-mode-only probe (or checking vsm developer-mode) would make it fail loudly as the TODO already notes.

[finloop]

Two paths: entries don't match the files they're meant to guard:

• tools/remote/** — the tool lives at tools/tv-remote/, so there is no tools/remote/ directory; edits to tv-remote/index.ts never trigger this workflow.
• describe/platforms/vega.ts (line 30) matches only that file, not the parser at describe/platforms/vega/source-parser.ts.

So the regression guard won't run on changes to its two headline subjects — the tv-remote tool and the describe XML parser.

Suggested change

	- "packages/tool-server/src/tools/remote/**"
	- "packages/tool-server/src/tools/tv-remote/**"

(and broaden the describe glob to describe/platforms/vega/**).

[finloop]

This gate can't detect a broken describe. describeVega returns source:"vega-automation" even in the empty/unreachable case, and format-tree always emits a non-empty header (Source:/Mode:/ROOT ...), so both src == "vega-automation" and -n "$desc" hold even when the toolkit never attached and the tree is empty. Assert on real tree content instead — e.g. a known label like Search/Home, or that the body has element lines beyond the header.

[finloop]

keyboard and screenshot resolve Vega by hand — services() returns {} and ensureDep("adb") is called imperatively inside execute — while launch/restart/reinstall use the declarative PlatformImpl.requires path through dispatchByPlatform. Two dispatch styles for one platform invites drift, and the dep matrix is already inconsistent: tv-remote requires adb; launch/restart/reinstall require only vega (though they also shell to adb via ensureAutomationToolkitEnabled); keyboard/screenshot require only adb. Routing Vega through the same dispatchByPlatform/requires mechanism (or a small Vega blueprint) would keep gating in one place.

[latekvo]

Review of the Vega (Fire TV) platform addition. Specific findings inline.

[latekvo]

resolveDevice forces kind: "vvd" for every amazon- serial, so a Vega device's kind is derived purely from serial shape. A physical Fire TV is surfaced by listVegaDevices/classifyKind in vega-devices.ts as kind: "device", but the capability gate goes through resolveDevice and therefore only ever sees "vvd". assertSupported checks matrix[device.kind], so the vega: { vvd: true } declarations (which deliberately omit device) never reject hardware — a physical Fire TV is accepted and driven by the VVD-only adb paths. The v1 "Virtual-Device-only, reject hardware up front" guarantee from the PR description is not actually enforced at the gate.

[latekvo]

The resolved image (line 1063) is only used for the existence check above — it is never passed to startVvd, and startVvd (vega-vvd.ts) runs vega virtual-device start -t <secs> with no image argument. The returned payload echoes vvdImage: params.vvdImage (lines 1078 and 1092) regardless of which image is actually running, and isVvdRunning() is image-agnostic. So requesting image B while image A is running returns A's serial labelled B, and force re-starts the SDK default rather than B. On a multi-image host the requested image is silently ignored.

[latekvo]

parseVegaPageSource(xml) is outside the try/catch that wraps fetchVegaPageSource above, and it throws on unparseable input. A non-empty but malformed/truncated page source (length ≥ 50, so it passes the empty-length check) makes the whole describe call fail with a raw parse error, instead of degrading to the EMPTY_TREE + hint path used for every other failure in this function.

[latekvo]

button accepts up to 64 entries and repeat up to 50, so one schema-valid call flattens to 3200 presses here. injectViaInputd (vega-input.ts) settles 0.3s between each press, so this runs ~16 min on-device with an adb timeout budgeted to ~27 min, holding the connection open the whole time. The tool isn't marked long-running, so the request can also collide with the idle-shutdown timer.

[latekvo]

This path glob points at tools/remote/**, but the tool lives in tools/tv-remote/, so it matches nothing. With the rest of this list, changes to tv-remote/index.ts, describe/platforms/vega/source-parser.ts, boot-device.ts, list-devices.ts, and device-info.ts do not trigger this workflow — so the "remote + screenshot" regression guard never runs when the remote tool or the source-parser change.

[latekvo]

isTrue only accepts the exact literal "true", so focused/selected/focusable/clickable arriving as "True" or "1" are silently treated as false. The fixture only uses lowercase, so any casing variance in real toolkit output would silently drop these state flags with no error.

[latekvo]

This export is the only change to this file, and decodeXmlEntities has no importers outside this module (the new Vega parser uses fast-xml-parser). The widening to export adds an unused public symbol — looks like a leftover from an earlier approach.

[latekvo]

This comment states that no Android adb serial starts with amazon-, but ro.serialno is vendor-defined and not constrained by adb. No known shipping device collides, so this is informational, but the claim is more absolute than is guaranteed — an Android device with such a serial would be misrouted to the Vega paths.

[latekvo]

This tells the agent to navigate by the [focused] cursor and to treat [selected] as "just an active-tab/highlight state", but the only captured page source has zero focused="true" nodes and uses selected="true" for the active item. Following this verbatim, an agent would find no [focused] line and stall. The guidance and the parser's focus handling don't agree.

[latekvo]

This says unsupported tools return "unsupported on vega", but the actual error text is Tool '<id>' is not supported on vega vvd. (UnsupportedOperationError) or ... is not yet implemented on vega. An agent matching on the documented literal would never match.