@swmansion/argent 0.13.0 → 0.13.1-next.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swmansion/argent",
-  "version": "0.13.0",
+  "version": "0.13.1-next.0",
   "description": "MCP server for iOS Simulator and Android Emulator control",
   "license": "Apache-2.0",
   "repository": {
@@ -41,12 +41,14 @@
     "scripts/postinstall.cjs"
   ],
   "dependencies": {
+    "@fails-components/webtransport": "^1.6.3",
+    "@fails-components/webtransport-transport-http3-quiche": "^1.6.3",
     "@modelcontextprotocol/sdk": "^1.20.0",
     "tree-sitter": "^0.21.1",
     "tree-sitter-typescript": "^0.23.2"
   },
   "optionalDependencies": {
-    "electron": "^42.4.1"
+    "electron": "^42.5.0"
   },
   "devDependencies": {
     "@argent/cli": "file:../argent-cli",
@@ -54,14 +56,14 @@
     "@argent/mcp": "file:../argent-mcp",
     "@argent/telemetry": "file:../telemetry",
     "@argent/tools-client": "file:../argent-tools-client",
-    "@clack/prompts": "^1.5.1",
-    "@types/node": "^25.9.3",
+    "@clack/prompts": "^1.6.0",
+    "@types/node": "^26.0.1",
     "@types/semver": "^7.7.1",
     "esbuild": "^0.28.1",
     "picocolors": "^1.1.1",
-    "posthog-node": "5.35.0",
-    "semver": "^7.8.4",
-    "smol-toml": "^1.6.1",
+    "posthog-node": "5.38.6",
+    "semver": "^7.8.5",
+    "smol-toml": "^1.7.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9",
     "yaml": "^2.8.3"

package/rules/argent.md

@@ -98,7 +98,7 @@ Load the matching skill before starting work and executing tools from argent-mcp
 procedure and edge-case handling for each workflow.
 
 PLATFORM DETECTION
-If the user did not specify a platform, call `list-devices` first and pick the booted target — do not default to iOS. Vega (Amazon Fire TV) devices appear as `platform:"vega"`, when present load `argent-vega`
+If the user did not specify a platform, call `list-devices` first and pick the booted target — do not default to iOS. Vega (Amazon Fire TV) devices appear as `platform:"vega"`, when present load `argent-tv-interact`
 
 iOS SIMULATOR SETUP
 Skill: `argent-ios-simulator-setup`
@@ -108,14 +108,14 @@ ANDROID EMULATOR SETUP
 Skill: `argent-android-emulator-setup`
 When: Beginning a task that involves the Android emulator, no emulator running yet, need an adb serial, or about to install an APK.
 
-VEGA / AMAZON FIRE TV APP CONTROL
-Skill: `argent-vega`
-When: Any task involving a Vega / Amazon Fire TV device (a `platform:"vega"` / `kind:"vvd"` entry in `list-devices`, or the user mentions Vega / Fire TV / VVD). Covers list/launch/restart/reinstall apps, on-screen element discovery via `describe`, D-pad navigation with the `tv-remote` tool (Vega is remote-driven, not touch), typing, screenshots, Fast Refresh setup, and VVD lifecycle (start/stop via the `vega` CLI — argent has no Vega stop tool).
-Prompt keywords: vega, fire tv, vvd, virtual device, d-pad
-
 TAPPING, SWIPING, TYPING, GESTURES, SCREENSHOTS, SCROLLING
 Skill: `argent-device-interact`
-When: Performing touch interactions, typing, pressing hardware buttons, launching/restarting apps, opening URLs, rotating device, taking standalone screenshots, or verifying a visible UI code change.
+When: Performing touch interactions, typing, pressing hardware buttons, launching/restarting apps, opening URLs, rotating device, taking standalone screenshots, or verifying a visible UI code change. Phone/tablet iOS and Android only — for any TV target use the TV skill below.
+
+TV INTERACTION (APPLE TV / ANDROID TV / FIRE TV)
+Skill: `argent-tv-interact`
+When: Any TV target — a `list-devices` entry with `runtimeKind: "tv"` (Apple TV simulator or Android TV emulator) or `platform:"vega"` / `kind:"vvd"` (Amazon Fire TV / VVD), or the user mentions Apple TV / tvOS / Android TV / leanback / Vega / Fire TV. A TV UI is focus-driven, not touch-driven: drive it with `describe` (read focus) + `tv-remote` (D-pad presses) + `keyboard` (type); `gesture-*` tools do NOT apply. Covers booting the target, app lifecycle, focus navigation, typing, screenshots, and (Vega) VVD lifecycle + Fast Refresh.
+Prompt keywords: apple tv, tvos, android tv, leanback, vega, fire tv, vvd, d-pad
 
 SCREENSHOT DIFF & VISUAL REGRESSION
 Skill: `argent-screenshot-diff`

package/skills/argent-android-emulator-setup/SKILL.md

@@ -23,6 +23,7 @@ Pass the Android serial as `udid` to the unified interaction tools — `gesture-
 
 ## 4. Notes
 
+- **Android TV / leanback AVDs** boot through this exact flow (same `boot-device` + `avdName`), but they are **focus-driven, not touch-driven** — do not use `gesture-tap`/`gesture-swipe` on them. `list-devices` tags a leanback device with `runtimeKind: "tv"` (detected via the system feature list, not the serial — a TV AVD's serial looks just like a phone's). When you see `runtimeKind: "tv"`, drive it with the focus-driven tools (`describe` / `tv-remote` / `keyboard`) and the `argent-tv-interact` skill (it covers Android TV as well as Apple TV, including the full TV setup flow).
 - Serials are the adb device id. iOS UDIDs and Android serials are not interchangeable, but you do NOT need to tell the tools which platform — dispatch is automatic.
 - `describe` on Android returns a shallower tree than iOS (no accessibility-service equivalent), but covers most tap-target discovery.
 - `reinstall-app` on Android always installs with `-g` so first-launch runtime permissions are pre-granted.

package/skills/argent-device-interact/SKILL.md

@@ -13,6 +13,8 @@ All interaction tools below accept a `udid` parameter and auto-dispatch iOS vs A
 
 **Cookies & storage (Chromium only):** `chromium-cookies` reads/writes cookies via the Network domain (so HttpOnly cookies are visible): `action=get` (optionally scoped by `url`), `set` (`name`, `value`, + `url`/`domain`, optional `secure`/`httpOnly`/`sameSite`/`expires`), `delete` (`name`), `clear` (all). `chromium-storage` reads/writes Web Storage for the active page: `store=local|session`, `action=get` (one `key` or all entries), `set`, `remove`, `clear`. Both are per-origin / active-tab. Handy for seeding auth before a flow or asserting app state after one.
 
+> **TV targets (Apple TV / Android TV) are not covered by this skill.** A TV target is **focus-driven, not touch-driven** — the `gesture-*` tools are the wrong tools for it. This applies to both Apple TV simulators (UUID-shaped, identical to iOS) and Android TV / leanback devices (serial-shaped, identical to a phone emulator). If `list-devices` tags your target `runtimeKind: "tv"`, stop and use the `argent-tv-interact` skill: `describe` to read focus, `tv-remote` for remote / D-pad presses, and `keyboard` to type.
+
 For platform-specific caveats (Metro `adb reverse`, locked-screen describe errors, etc.), see § 9 Platform-specific notes at the bottom.
 
 ## 1. Before You Start

package/skills/argent-tv-interact/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: argent-tv-interact
+description: Control and inspect TV apps via argent — Apple TV (tvOS), Android TV (leanback), and Amazon Fire TV (Vega). Boot the target, read focus, navigate with the D-pad remote, type, and screenshot. Use when a task targets a TV (runtimeKind "tv", or platform "vega"), or mentions Apple TV / tvOS / Android TV / leanback / Vega / Fire TV / VVD.
+---
+
+# Argent TV (Apple TV + Android TV + Fire TV)
+
+## Critical
+
+- A TV is **focus-driven, not touch-driven.** Drive every interaction with `describe` + `tv-remote` + `keyboard`; never use `gesture-*` / coordinate taps — they don't apply on any TV platform.
+- **Always `describe` before navigating** to find the live cursor and your target — never guess focus from a screenshot. The cursor is the focused element; on **Vega** the toolkit often leaves `focused` false and marks the highlighted item `[selected]`, so treat `[selected]` as the cursor when nothing reports `[focused]`.
+- Pass the `udid` from `list-devices` — an Apple TV simulator UDID or an Android TV / Vega `serial`. Dispatch is automatic from the id; the same tools drive all three.
+
+## The navigation loop
+
+1. `describe` — find the cursor and your target (returns the focused element + all focusable ones, not a tap tree).
+2. `tv-remote` — move focus toward the target. Prefer **one** call with a path ending in `select`, e.g. `{button:["down","right","select"]}`; count rows/columns from the frames to build the path.
+3. `describe` again to confirm. On a miss, repeat.
+
+## Tools
+
+- `describe {udid}` — focus view: the focused / `[selected]` element + focusable elements with labels and normalized frames. The discovery tool — call before and after navigating. Empty tree → see the per-platform notes.
+- `tv-remote {udid, button}` — D-pad / remote. `button` is one key **or a whole path** (run in one call). Keys: `up`/`down`/`left`/`right`, `select`, `back`, `menu`, `home`, `playPause`, plus media keys `rewind`/`fastForward`/`next`/`previous`/`volumeUp`/`volumeDown`/`mute`. Single: `{button:"down"}`; repeat: `{button:"down", repeat:3}`; path: `{button:["up","right","select"]}`.
+- `keyboard {udid, text}` — type into the focused field (focus it with `tv-remote` first). Named `key` presses (e.g. `{key:"enter"}`) work on Vega; on Apple TV / Android TV move focus with `tv-remote` instead.
+- `launch-app` / `restart-app` / `reinstall-app {udid, bundleId}` — `bundleId` from the app manifest. Vega `reinstall-app` takes `appPath` = a `.vpkg`.
+- `screenshot {udid, scale?}` — Apple TV via `xcrun simctl io` (downscaled); Android TV / Vega host-side via `adb` / `screencap`.
+
+## Per-platform
+
+### Apple TV (tvOS simulator)
+
+- Boot like any iOS sim (`boot-device`); the AX + HID daemons auto-start on the first `describe` / `tv-remote` (first call may take a few seconds). Give the RN bundle a few seconds to render before the first `describe`.
+- Media-transport / volume keys are **rejected** — the sim's HID stack ignores them (they work on Android TV / Vega).
+- Dev build: `open-url {udid, url:"<scheme>://expo-development-client/?url=http%3A%2F%2F<HOST_IP>%3A8081"}` (`<HOST_IP>` = your Mac's LAN IP, shown on the launcher).
+
+### Android TV (leanback emulator)
+
+- Boot the leanback AVD like any emulator — see `argent-android-emulator-setup`.
+- **`describe` may report zero focusables on a screen with visible tiles**: many `react-native-tvos` screens use RN's own focus engine, invisible to the OS accessibility tree. `describe` auto-falls-back to the full UI tree (and says so in the hint); `tv-remote` still moves focus, so drive blind + `screenshot` to confirm.
+- Dev build: `adb -s <serial> reverse tcp:8081 tcp:8081`, deep-link `<pkg>://expo-development-client/?url=http%3A%2F%2F10.0.2.2%3A8081`, dismiss the first dev-menu with `adb shell input keyevent KEYCODE_DPAD_CENTER` (not Back — Back exits the app).
+
+### Fire TV (Vega / VVD)
+
+- `list-devices` shows a `serial` (use as `udid`) and a `vvdImage`. `boot-device {vvdImage}` (e.g. `"tv"`) starts the single SDK-managed VVD; skip if one already runs.
+- **Stop the VVD** with `vega virtual-device stop` in your shell. The CLI only tracks VVDs it started in the foreground, so it may report "not running" for one started via `boot-device`; to restart that one use `boot-device {vvdImage, force:true}` (stops then re-boots).
+- Empty `describe` tree → `restart-app` (the automation toolkit attaches at launch), then retry. Input ignored → enable developer mode in the VVD: `vsm developer-mode enable`.
+- Editing `node_modules` has no effect on a Release build — only Debug `.vpkg` builds load patchable JS.
+- Profiling / crashes → `amazon-devices-buildertools-mcp` server (`analyze_perfetto_traces`, `get_app_hot_functions`, `symbolicate_acr`); docs via its `search_documentation` tool.
+
+## Common gotchas
+
+- **Empty focus right after `launch-app` / `restart-app`** is the splash / loading window — `describe` retries internally; wait ~2-3s and retry on a cold start.
+- Passing a phone/tablet (`runtimeKind: "mobile"`) udid to `tv-remote` fails with a clear "tvOS-only" / "Android-TV-only" error — pick a TV target from `list-devices`.
+
+## Fast Refresh (dev builds)
+
+Needs a Debug build + Metro running. argent only _connects_ to Metro — start Metro and port-forward yourself (any platform). Metro is fixed on **:8081**.
+
+- **Apple TV / Android TV:** use the dev-build deep-links above; `npm start` for Metro.
+- **Vega:** build/install a Debug `.vpkg` (`vega device install-app -p <path>`), `npm start`, `vega device start-port-forwarding --port 8081 --forward false`, then `vega device launch-app -a <appId>`. Confirm `http://localhost:8081/json/list` shows a `Hermes React Native` target; `.tsx` edits then hot-reload.

package/skills/argent-vega/SKILL.md

@@ -1,76 +0,0 @@
----
-name: argent-vega
-description: Control and inspect Amazon Fire TV (Vega) apps via argent — launch/restart/reinstall apps, read the on-screen element tree, navigate with the D-pad remote, type, and screenshot. Use when the task mentions Vega, Fire TV, or VVD, or involves driving a Vega virtual device.
----
-
-# Argent Vega (Amazon Fire TV)
-
-## Critical
-
-- Vega is a TV platform
-- **D-pad only.** Drive every interaction with `tv-remote`. Never use `gesture-*` / touch — they are unsupported on Vega.
-- **Always `describe` before navigating.** Find the live cursor from the tree — the `[focused]` element, or `[selected]` when nothing reports `[focused]` (the toolkit often marks the highlighted item `[selected]` while `focused` stays false). Never guess focus position from a screenshot.
-- All tools take the Vega `serial` (from `list-devices`) as `udid`.
-
-## The navigation loop
-
-Per screen, two calls:
-
-1. `describe` — find the cursor (`[focused]`, or `[selected]` if no `[focused]`) and your target.
-2. Compute the full D-pad path from focus → target (count rows/columns from the frames) and fire it as **one** `tv-remote {button:[...]}` ending in `select`.
-
-Then `describe` again to confirm. On a miss, run the loop again.
-
-## Tools
-
-### Device lifecycle
-
-- `list-devices` → Vega devices appear with a `serial` (use as `udid`) and a `vvdImage`. Start here to get both.
-- `boot-device {vvdImage}` — starts the single SDK-managed VVD (e.g. `vvdImage:"tv"`) and returns its `serial`. Skip if `list-devices` already shows a running device.
-- **Stopping the VVD** — run `vega virtual-device stop` in your shell.
-
-### App lifecycle
-
-- `launch-app {udid, bundleId}` — `bundleId` = interactive component app id from manifest.toml (e.g. `com.example.app.main`)
-- `restart-app {udid, bundleId}` — terminate + launch
-- `reinstall-app {udid, bundleId, appPath}` — uninstall + install; `appPath` = a `.vpkg`
-- `describe {udid}` → on-screen element tree. The discovery tool — call before navigating
-- `tv-remote {udid, button}` — D-pad; single key, path array, or `repeat`
-- `keyboard {udid, text}` or `{udid, key:"enter"}` — focus the field with the D-pad first
-- `screenshot {udid, scale?}` — captured host-side via `adb`
-
-### `describe`
-
-Nested element tree from the on-device automation toolkit — each line is a `button`/`text`/`image` with its label, `id` (test_id), `[clickable]`, and **`[focused]`/`[selected]`** + a normalized [0,1] frame. `[focused]` is the live D-pad cursor when present; in practice the toolkit usually leaves `focused` false and marks the highlighted item `[selected]`, so treat `[selected]` as the cursor whenever no element reports `[focused]`. Navigate on the tree alone. If the tree comes back empty → `restart-app` and retry.
-
-### `tv-remote`
-
-`button` is a single key **or a whole path**. Keys: `up`/`down`/`left`/`right`, `select`, `back`, `home`, `menu`, `playPause`, `rewind`, `fastForward`. Single: `{button:"down"}`. Repeat one key: `{button:"down", repeat:3}`. Whole path in one call: `{button:["up","right","right","select"]}` — strongly prefer this for any multi-step move.
-
-## Fast Refresh
-
-Needs a Debug build + Metro running. argent only connects to Metro — it does not start Metro or port-forward (any platform); do these in your shell.
-
-1. Build a **Debug** `.vpkg` and install it: `vega device install-app -p <path/to/debug.vpkg>`
-2. `npm start` (Metro on :8081; use `npm start`, not `npx react-native start`)
-3. `vega device start-port-forwarding --port 8081 --forward false` (reverse)
-4. `vega device launch-app -a <appId>`
-
-Metro must be up before launch; confirm `http://localhost:8081/json/list` lists a `Hermes React Native` target. Then `.tsx` edits hot-reload live.
-
-## Troubleshooting
-
-- **`describe` returns an empty tree** → `restart-app` (the automation toolkit attaches at launch), then retry.
-- **Keyboard / D-pad input is ignored** → enable developer mode inside the VVD: `vsm developer-mode enable`.
-- **Editing `node_modules` has no effect** → you are on a Release build. Release Vega apps load JavaScript and native code split and stored on device, so patching `node_modules` only works in Debug builds.
-
-## Platform notes
-
-- Metro connects only on port **8081** — fixed, cannot be changed.
-- Profiling / crashes → use the `amazon-devices-buildertools-mcp` server (`analyze_perfetto_traces`, `get_app_hot_functions`, `symbolicate_acr`).
-- Unsupported tools, with the Vega equivalent: `gesture-*` → use `tv-remote`; `open-url` → not wired; `debugger-*` → JS debugger not supported on Vega. These fail with `Tool '<id>' is not supported on vega vvd.` (or `... is not yet implemented on vega.`).
-
-## Knowledgebase
-
-- Search Vega docs with the `search_documentation` tool (`amazon-devices-buildertools-mcp` server).
-- Community Q&A at community.amazondeveloper.com.