@swmansion/argent 0.15.1-next.7 → 0.15.1-next.8

package/dist/cli-cmds.mjs

@@ -6234,10 +6234,10 @@ var FAILURE_CODES = {
   ANDROID_UIAUTOMATOR_PARSE_FAILED: "ANDROID_UIAUTOMATOR_PARSE_FAILED",
   ANDROID_UIAUTOMATOR_CAPTURE_FAILED: "ANDROID_UIAUTOMATOR_CAPTURE_FAILED",
   DEBUGGER_METRO_NOT_RUNNING: "DEBUGGER_METRO_NOT_RUNNING",
-  DEBUGGER_METRO_PROJECT_ROOT_MISSING: "DEBUGGER_METRO_PROJECT_ROOT_MISSING",
   DEBUGGER_METRO_NO_TARGETS: "DEBUGGER_METRO_NO_TARGETS",
   DEBUGGER_CDP_RUNTIME_EXCEPTION: "DEBUGGER_CDP_RUNTIME_EXCEPTION",
   DEBUGGER_CDP_BINDING_TIMEOUT: "DEBUGGER_CDP_BINDING_TIMEOUT",
+  DEBUGGER_CDP_BINDING_UNAVAILABLE: "DEBUGGER_CDP_BINDING_UNAVAILABLE",
   DEBUGGER_CDP_PROTOCOL_ERROR: "DEBUGGER_CDP_PROTOCOL_ERROR",
   DEBUGGER_RELOAD_FAILED: "DEBUGGER_RELOAD_FAILED",
   JS_RUNTIME_CONSOLE_SERVER_BIND_FAILED: "JS_RUNTIME_CONSOLE_SERVER_BIND_FAILED",

package/dist/installer.mjs

@@ -16141,10 +16141,10 @@ var FAILURE_CODES = {
   ANDROID_UIAUTOMATOR_PARSE_FAILED: "ANDROID_UIAUTOMATOR_PARSE_FAILED",
   ANDROID_UIAUTOMATOR_CAPTURE_FAILED: "ANDROID_UIAUTOMATOR_CAPTURE_FAILED",
   DEBUGGER_METRO_NOT_RUNNING: "DEBUGGER_METRO_NOT_RUNNING",
-  DEBUGGER_METRO_PROJECT_ROOT_MISSING: "DEBUGGER_METRO_PROJECT_ROOT_MISSING",
   DEBUGGER_METRO_NO_TARGETS: "DEBUGGER_METRO_NO_TARGETS",
   DEBUGGER_CDP_RUNTIME_EXCEPTION: "DEBUGGER_CDP_RUNTIME_EXCEPTION",
   DEBUGGER_CDP_BINDING_TIMEOUT: "DEBUGGER_CDP_BINDING_TIMEOUT",
+  DEBUGGER_CDP_BINDING_UNAVAILABLE: "DEBUGGER_CDP_BINDING_UNAVAILABLE",
   DEBUGGER_CDP_PROTOCOL_ERROR: "DEBUGGER_CDP_PROTOCOL_ERROR",
   DEBUGGER_RELOAD_FAILED: "DEBUGGER_RELOAD_FAILED",
   JS_RUNTIME_CONSOLE_SERVER_BIND_FAILED: "JS_RUNTIME_CONSOLE_SERVER_BIND_FAILED",

package/dist/mcp-server.mjs

@@ -17660,10 +17660,10 @@ var FAILURE_CODES = {
   ANDROID_UIAUTOMATOR_PARSE_FAILED: "ANDROID_UIAUTOMATOR_PARSE_FAILED",
   ANDROID_UIAUTOMATOR_CAPTURE_FAILED: "ANDROID_UIAUTOMATOR_CAPTURE_FAILED",
   DEBUGGER_METRO_NOT_RUNNING: "DEBUGGER_METRO_NOT_RUNNING",
-  DEBUGGER_METRO_PROJECT_ROOT_MISSING: "DEBUGGER_METRO_PROJECT_ROOT_MISSING",
   DEBUGGER_METRO_NO_TARGETS: "DEBUGGER_METRO_NO_TARGETS",
   DEBUGGER_CDP_RUNTIME_EXCEPTION: "DEBUGGER_CDP_RUNTIME_EXCEPTION",
   DEBUGGER_CDP_BINDING_TIMEOUT: "DEBUGGER_CDP_BINDING_TIMEOUT",
+  DEBUGGER_CDP_BINDING_UNAVAILABLE: "DEBUGGER_CDP_BINDING_UNAVAILABLE",
   DEBUGGER_CDP_PROTOCOL_ERROR: "DEBUGGER_CDP_PROTOCOL_ERROR",
   DEBUGGER_RELOAD_FAILED: "DEBUGGER_RELOAD_FAILED",
   JS_RUNTIME_CONSOLE_SERVER_BIND_FAILED: "JS_RUNTIME_CONSOLE_SERVER_BIND_FAILED",

package/dist/tool-server.cjs

@@ -314,10 +314,10 @@ var init_failure_codes = __esm({
       ANDROID_UIAUTOMATOR_PARSE_FAILED: "ANDROID_UIAUTOMATOR_PARSE_FAILED",
       ANDROID_UIAUTOMATOR_CAPTURE_FAILED: "ANDROID_UIAUTOMATOR_CAPTURE_FAILED",
       DEBUGGER_METRO_NOT_RUNNING: "DEBUGGER_METRO_NOT_RUNNING",
-      DEBUGGER_METRO_PROJECT_ROOT_MISSING: "DEBUGGER_METRO_PROJECT_ROOT_MISSING",
       DEBUGGER_METRO_NO_TARGETS: "DEBUGGER_METRO_NO_TARGETS",
       DEBUGGER_CDP_RUNTIME_EXCEPTION: "DEBUGGER_CDP_RUNTIME_EXCEPTION",
       DEBUGGER_CDP_BINDING_TIMEOUT: "DEBUGGER_CDP_BINDING_TIMEOUT",
+      DEBUGGER_CDP_BINDING_UNAVAILABLE: "DEBUGGER_CDP_BINDING_UNAVAILABLE",
       DEBUGGER_CDP_PROTOCOL_ERROR: "DEBUGGER_CDP_PROTOCOL_ERROR",
       DEBUGGER_RELOAD_FAILED: "DEBUGGER_RELOAD_FAILED",
       JS_RUNTIME_CONSOLE_SERVER_BIND_FAILED: "JS_RUNTIME_CONSOLE_SERVER_BIND_FAILED",
@@ -114407,6 +114407,8 @@ var CDPClient = class {
   nextId = 1;
   pending = /* @__PURE__ */ new Map();
   pendingBindings = /* @__PURE__ */ new Map();
+  /** Set by addBinding when the runtime ACKs the command but installs nothing. */
+  bindingUnavailable = false;
   scripts = /* @__PURE__ */ new Map();
   enabledDomains = /* @__PURE__ */ new Set();
   wsUrl;
@@ -114539,6 +114541,8 @@ var CDPClient = class {
   }
   async addBinding(name) {
     await this.send("Runtime.addBinding", { name });
+    const probe3 = await this.evaluate(`typeof ${name}`).catch(() => void 0);
+    this.bindingUnavailable = probe3 === "undefined";
   }
   /**
    * Inject a script that will push a result via the binding using a unique requestId.
@@ -114547,6 +114551,19 @@ var CDPClient = class {
   evaluateWithBinding(expression, requestId, options) {
     const id = requestId ?? crypto3.randomUUID();
     const timeout = options?.timeout ?? DEFAULT_TIMEOUT_MS2;
+    if (this.bindingUnavailable) {
+      return Promise.reject(
+        new FailureError(
+          "This JS runtime acknowledges Runtime.addBinding but never installs the binding (legacy Hermes, React Native <= 0.72), so it cannot deliver a result over the binding channel. Tools that read the React tree this way are unavailable here; use `describe` to read on-screen structure.",
+          {
+            error_code: FAILURE_CODES.DEBUGGER_CDP_BINDING_UNAVAILABLE,
+            failure_stage: "debugger_cdp_binding",
+            failure_area: "tool_server",
+            error_kind: "unsupported"
+          }
+        )
+      );
+    }
     return new Promise((resolve7, reject) => {
       const timer = setTimeout(() => {
         this.pendingBindings.delete(id);
@@ -121983,12 +122000,14 @@ init_src();
 
 // ../tool-server/src/utils/debugger/discovery.ts
 init_src();
+var DECOY_VM = "don't use";
 async function discoverMetro(port) {
-  const statusRes = await fetch(`http://localhost:${port}/status`);
-  const statusText = await statusRes.text();
-  if (!statusText.includes("packager-status:running")) {
+  let statusRes;
+  try {
+    statusRes = await fetch(`http://localhost:${port}/status`);
+  } catch (err) {
     throw new FailureError(
-      `Metro at port ${port} is not running (got: ${statusText.slice(0, 100)})`,
+      `Metro at port ${port} is not running (got: ${err instanceof Error ? err.message : String(err)})`,
       {
         error_code: FAILURE_CODES.DEBUGGER_METRO_NOT_RUNNING,
         failure_stage: "debugger_discover_metro_status",
@@ -121997,21 +122016,25 @@ async function discoverMetro(port) {
       }
     );
   }
-  const projectRoot = statusRes.headers.get("X-React-Native-Project-Root") ?? "";
-  if (!projectRoot) {
+  const statusText = await statusRes.text();
+  if (!statusText.includes("packager-status:running")) {
     throw new FailureError(
-      `Metro at port ${port} did not return X-React-Native-Project-Root header`,
+      `Metro at port ${port} is not running (got: ${statusText.slice(0, 100)})`,
       {
-        error_code: FAILURE_CODES.DEBUGGER_METRO_PROJECT_ROOT_MISSING,
-        failure_stage: "debugger_discover_metro_project_root",
+        error_code: FAILURE_CODES.DEBUGGER_METRO_NOT_RUNNING,
+        failure_stage: "debugger_discover_metro_status",
         failure_area: "tool_server",
         error_kind: "network"
       }
     );
   }
+  const projectRoot = statusRes.headers.get("X-React-Native-Project-Root") ?? "";
   const listRes = await fetch(`http://localhost:${port}/json/list`);
-  const targets = await listRes.json();
-  if (!targets?.length) {
+  const parsed = await listRes.json().catch(() => null);
+  const targets = (Array.isArray(parsed) ? parsed : []).filter(
+    (t) => t?.vm !== DECOY_VM
+  );
+  if (!targets.length) {
     throw new FailureError(
       `Metro at port ${port} has no CDP targets \u2014 is a React Native app connected?`,
       {
@@ -122026,8 +122049,19 @@ async function discoverMetro(port) {
 }
 
 // ../tool-server/src/utils/debugger/target-selection.ts
+function deviceKey(target) {
+  const logicalId = target.reactNative?.logicalDeviceId;
+  if (logicalId) return logicalId;
+  try {
+    const device = new URL(target.webSocketDebuggerUrl).searchParams.get("device");
+    if (device) return `device=${device}`;
+  } catch {
+  }
+  return target.deviceName;
+}
 function selectTarget(targets, port, options) {
-  let candidates = targets;
+  const pool = targets;
+  let candidates = pool;
   if (typeof options?.deviceId === "string" && options.deviceId) {
     const deviceId = options.deviceId;
     const filtered = candidates.filter((t) => t.reactNative?.logicalDeviceId === deviceId);
@@ -122035,16 +122069,21 @@ function selectTarget(targets, port, options) {
       candidates = filtered;
     } else {
       const distinctDevices = /* @__PURE__ */ new Map();
-      for (const t of targets) {
-        const id = t.reactNative?.logicalDeviceId;
-        if (id !== void 0 && id !== "" && !distinctDevices.has(id)) {
-          distinctDevices.set(id, t.deviceName);
+      for (const t of pool) {
+        const key = deviceKey(t);
+        if (key && !distinctDevices.has(key)) {
+          distinctDevices.set(key, {
+            name: t.deviceName,
+            logicalId: t.reactNative?.logicalDeviceId
+          });
         }
       }
       if (distinctDevices.size > 1) {
-        const listed = [...distinctDevices.entries()].map(([id, name]) => name ? `${name} (${id})` : id).join(", ");
+        const listed = [...distinctDevices.values()].map(
+          (d) => d.logicalId ? `${d.name ?? "unknown"} (${d.logicalId})` : `${d.name ?? "unknown"} (legacy inspector \u2014 no logicalDeviceId)`
+        ).join(", ");
         throw new Error(
-          `No debugger target matches device_id "${deviceId}". ${distinctDevices.size} devices are connected to Metro on port ${port}: ${listed}. Pass the logicalDeviceId (in parentheses) of the desired device as device_id (the logicalDeviceId returned by debugger-connect).`
+          `No debugger target matches device_id "${deviceId}". ${distinctDevices.size} devices are connected to Metro on port ${port}: ${listed}. Re-target with the logicalDeviceId in parentheses \u2014 that is what debugger-connect returns and what subsequent debugger-* calls must pass. A legacy-inspector device (RN 0.72 / Vega) reports none and cannot be singled out of a shared Metro: give it its own Metro port.`
         );
       }
     }
@@ -122185,6 +122224,7 @@ function parseNode(line) {
 // ../tool-server/src/utils/debugger/source-resolver.ts
 var ALLOWED_SOURCE_EXTENSIONS = /* @__PURE__ */ new Set([".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs"]);
 function isInsideProject(absFile, projectRoot) {
+  if (!projectRoot) return false;
   const resolvedRoot = path17.resolve(projectRoot);
   const resolvedFile = path17.resolve(absFile);
   const rel = path17.relative(resolvedRoot, resolvedFile);
@@ -122227,7 +122267,7 @@ function createSourceResolver(port, projectRoot) {
       const frame = data.stack?.[0];
       if (!frame?.file) return null;
       if (/^https?:\/\//.test(frame.file)) return null;
-      const relFile = frame.file.replace(projectRoot + "/", "").replace(/^\/+/, "");
+      const relFile = projectRoot ? frame.file.replace(projectRoot + "/", "").replace(/^\/+/, "") : frame.file;
       return {
         file: relFile,
         line: frame.lineNumber ?? 0,
@@ -122246,6 +122286,7 @@ function createSourceResolver(port, projectRoot) {
     },
     symbolicate: symbolicateFrame,
     async readSourceFragment(location, contextLines = 3) {
+      if (!projectRoot) return null;
       try {
         const absPath = path17.isAbsolute(location.file) ? path17.resolve(location.file) : path17.resolve(projectRoot, location.file);
         const realRoot = await fs18.realpath(projectRoot);
@@ -133797,7 +133838,8 @@ var DEBUGGER_TOOL_CAPABILITY = {
   apple: { simulator: true, device: true },
   appleRemote: { simulator: true },
   android: { emulator: true, device: true, unknown: true },
-  chromium: { app: true }
+  chromium: { app: true },
+  vega: { vvd: true }
 };
 var RN_ONLY_TOOL_CAPABILITY = {
   apple: { simulator: true, device: true },
@@ -133816,14 +133858,14 @@ function debuggerServiceRef(params) {
 var zodSchema29 = external_exports.object({
   port: external_exports.coerce.number().default(8081).describe("Metro server port (ignored for Chromium \u2014 its CDP port is encoded in device_id)"),
   device_id: external_exports.string().describe(
-    "Device id: iOS simulator UDID, Android logicalDeviceId returned by Metro, or Chromium device id (chromium-cdp-<port>) from list-devices. The returned logicalDeviceId must be forwarded as device_id to all subsequent debugger-* calls to pin them to this device."
+    "Device id: iOS simulator UDID, Android logicalDeviceId returned by Metro, Vega serial (amazon-...), or Chromium device id (chromium-cdp-<port>) from list-devices. When a logicalDeviceId is returned, forward it as device_id to all subsequent debugger-* calls to pin them to this device; when none is returned (Vega), keep passing the id you connected with."
   )
 });
 var debuggerConnectTool = {
   id: "debugger-connect",
   description: `Connect to a JS runtime CDP debugger.
-iOS / Android: connects to Metro's CDP endpoint on the given port. Chromium: re-uses the page CDP session opened by boot-device \u2014 port is ignored.
-Returns connection info including port, projectRoot (empty on Chromium), deviceName, appName, logicalDeviceId, and isNewDebugger. If already connected, returns the existing connection.
+iOS / Android / Vega: connects to Metro's CDP endpoint on the given port. Chromium: re-uses the page CDP session opened by boot-device \u2014 port is ignored.
+Returns connection info including port, projectRoot (empty on Chromium and on legacy Metro, e.g. Vega), deviceName, appName, logicalDeviceId (absent on Vega), and isNewDebugger. If already connected, returns the existing connection.
 Use when starting a debug session or before calling other debugger-* tools. Fails if the runtime is unreachable (Metro down, or Chromium CDP terminated).`,
   zodSchema: zodSchema29,
   capability: DEBUGGER_TOOL_CAPABILITY,
@@ -133849,13 +133891,13 @@ init_zod();
 var zodSchema30 = external_exports.object({
   port: external_exports.coerce.number().default(8081).describe("Metro server port (ignored for Chromium)"),
   device_id: external_exports.string().describe(
-    "Device id from debugger-connect (iOS simulator UDID, Android logicalDeviceId, or Chromium device id)."
+    "Device id from debugger-connect (iOS simulator UDID, Android logicalDeviceId, Vega serial, or Chromium device id)."
   )
 });
 var debuggerStatusTool = {
   id: "debugger-status",
   description: `Get JS runtime debugger connection status and diagnostic info.
-Use when you need to verify connectivity before using other debugger tools. Returns port, projectRoot (empty on Chromium), deviceName, appName, logicalDeviceId, connected flag, loadedScripts count, and sourceMapReady (always true \u2014 waits for pending source maps before returning; no-op on Chromium). Fails if the runtime is unreachable.`,
+Use when you need to verify connectivity before using other debugger tools. Returns port, projectRoot (empty on Chromium and on legacy Metro, e.g. Vega), deviceName, appName, logicalDeviceId (absent on Vega), isNewDebugger (false on the legacy inspector), connected flag, loadedScripts count, and sourceMapReady (always true \u2014 waits for pending source maps before returning; no-op on Chromium). Fails if the runtime is unreachable.`,
   zodSchema: zodSchema30,
   capability: DEBUGGER_TOOL_CAPABILITY,
   services: (params) => ({
@@ -133884,13 +133926,13 @@ init_zod();
 var zodSchema31 = external_exports.object({
   port: external_exports.coerce.number().default(8081).describe("Metro server port (ignored for Chromium)"),
   device_id: external_exports.string().describe(
-    "Device id from debugger-connect (iOS simulator UDID, Android logicalDeviceId, or Chromium device id)."
+    "Device id from debugger-connect (iOS simulator UDID, Android logicalDeviceId, Vega serial, or Chromium device id)."
   ),
   expression: external_exports.string().describe("JavaScript expression to evaluate in the app runtime")
 });
 var debuggerEvaluateTool = {
   id: "debugger-evaluate",
-  description: `Execute arbitrary JavaScript in the app's JS runtime via CDP \u2014 Hermes on iOS / Android, V8 on Chromium.
+  description: `Execute arbitrary JavaScript in the app's JS runtime via CDP \u2014 Hermes on iOS / Android / Vega, V8 on Chromium.
 Returns the evaluation result as a JSON-serializable value, along with deviceName, appName, and logicalDeviceId for context. Use when you need to read app state, call app functions, or test logic at runtime. The result is serialized by value, so cyclic objects (many RN runtime values \u2014 fiber nodes, navigation refs, global \u2014 are cyclic) fail with a serialization error rather than returning silently. Fails if the expression throws or the runtime is not connected.`,
   zodSchema: zodSchema31,
   capability: DEBUGGER_TOOL_CAPABILITY,
@@ -135374,13 +135416,13 @@ init_zod();
 var zodSchema35 = external_exports.object({
   port: external_exports.coerce.number().default(8081).describe("Metro server port (ignored for Chromium)"),
   device_id: external_exports.string().describe(
-    "Device id from debugger-connect (iOS simulator UDID, Android logicalDeviceId, or Chromium device id)."
+    "Device id from debugger-connect (iOS simulator UDID, Android logicalDeviceId, Vega serial, or Chromium device id)."
   )
 });
 var debuggerLogRegistryTool = {
   id: "debugger-log-registry",
   description: `Get a summary of all console logs captured from the app's JS runtime.
-Returns the log file path, entry counts by level, and message clusters (grouped by similarity). Works against Hermes (iOS / Android) and V8 (Chromium).
+Returns the log file path, entry counts by level, and message clusters (grouped by similarity). Works against Hermes (iOS / Android / Vega) and V8 (Chromium).
 Use when investigating warnings, errors, or unexpected output \u2014 call this first for an overview, then read the returned file for details. Returns empty stats if no log data has been captured yet.`,
   zodSchema: zodSchema35,
   capability: DEBUGGER_TOOL_CAPABILITY,
@@ -135472,7 +135514,7 @@ var networkLogsTool = {
   description: `Retrieve captured network (HTTP) requests from the running app.
 Returns a paginated list of requests with method, URL, status, resource type, size, and duration.
 Each entry includes a requestId that can be passed to view-network-request-details for full details.
-On React Native (iOS/Android) interception is injected into the JS runtime \u2014 it captures fetch() calls. On Chromium it reads the browser's native CDP Network domain (the active tab; all request types).
+On React Native (iOS / Android / Vega) interception is injected into the JS runtime \u2014 it captures fetch() calls. On Chromium it reads the browser's native CDP Network domain (the active tab; all request types).
 Use when inspecting outbound HTTP traffic or debugging API calls in the running app.
 Fails if the app is not connected (RN) or the device is not reachable (Chromium).`,
   zodSchema: zodSchema36,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swmansion/argent",
-  "version": "0.15.1-next.7",
+  "version": "0.15.1-next.8",
   "description": "MCP server for iOS Simulator and Android Emulator control",
   "license": "Apache-2.0",
   "repository": {

package/rules/argent.md

@@ -119,7 +119,7 @@ Prompt keywords: permission, grant, deny, revoke, reset permission, privacy, cam
 
 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.
+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 + JS-runtime debugging (evaluate, console logs, network inspector).
 Prompt keywords: apple tv, tvos, android tv, leanback, vega, fire tv, vvd, d-pad
 
 SCREENSHOT DIFF & VISUAL REGRESSION

package/skills/argent-metro-debugger/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: argent-metro-debugger
-description: Debug a JS runtime via CDP using argent debugger tools. Primary path is React Native via Metro (iOS / Android); a subset of the tools (debugger-connect, debugger-status, debugger-evaluate, debugger-log-registry) also drive a Chromium (CDP) app's renderer (an Electron app, or any Chromium browser exposing CDP) through the same surface. Use when connecting to the runtime, inspecting React components, reading console logs, or evaluating JavaScript.
+description: Debug a JS runtime via CDP using argent debugger tools. Primary path is React Native via Metro (iOS / Android / Vega); a subset of the tools (debugger-connect, debugger-status, debugger-evaluate, debugger-log-registry) also drive a Chromium (CDP) app's renderer (an Electron app, or any Chromium browser exposing CDP) through the same surface. Use when connecting to the runtime, inspecting React components, reading console logs, or evaluating JavaScript.
 ---
 
 ## 1. Prerequisites
 
 For **React Native (iOS / Android)**: requires **Metro dev server running** (default `localhost:8081`) and **a React Native app connected to Metro** (at least one CDP target). Verify via `debugger-status`.
 
+For **Vega (Fire TV)**: requires a **Debug `.vpkg`** (a Release build never attaches) and **Metro reachable from the device** (`vega device start-port-forwarding --port 8081 --forward false`). Verify via `debugger-status`. `debugger-component-tree`, `debugger-inspect-element`, `debugger-reload-metro` and the `react-profiler-*` / `profiler-*` tools are unavailable there — see the `argent-tv-interact` skill.
+
 For **Chromium (CDP)**: requires a Chromium/CDP app already available — an Electron app booted via `boot-device` with `electronAppPath`, or any Chromium browser exposing a CDP port (auto-discovered by `list-devices` on `9222` / `ARGENT_CHROMIUM_PORTS`). The debugger re-uses the page CDP session — `port` is ignored, `device_id` is the `chromium-cdp-<port>` value from `list-devices` / `boot-device`. Only `debugger-connect`, `debugger-status`, `debugger-evaluate`, `debugger-log-registry`, `view-network-logs`, and `view-network-request-details` work on Chromium (the latter two read the browser's native CDP Network recording for the active tab instead of the Metro-injected `fetch` interceptor); `debugger-component-tree`, `debugger-reload-metro`, `debugger-inspect-element`, and the `react-profiler-*` / `profiler-*` tools are RN-only and reject Chromium at the capability gate with `Tool 'X' is not supported on chromium app`.
 
 ### Android: reverse port for Metro
@@ -21,16 +23,16 @@ adb -s <serial> reverse tcp:8081 tcp:8081
 
 ## 2. Tool Overview
 
-All tools accept `port` (default 8081) AND `device_id` (the iOS Simulator UDID or Android serial, a.k.a. `logicalDeviceId` — the CDP-reported id that matches the device). Always make sure you target the correct app on the correct device.
+All tools accept `port` (default 8081) AND `device_id` (the iOS Simulator UDID, Android serial, or Vega serial — a.k.a. `logicalDeviceId`, the CDP-reported id that matches the device). Vega's legacy inspector reports no `logicalDeviceId`, so there keep passing the serial. Always make sure you target the correct app on the correct device.
 
 One Metro port can serve multiple connected devices (e.g. two simulators on `localhost:8081`, or an iOS simulator alongside an Android emulator with `adb reverse` set up). `device_id` pins every debugger/network/profiler call to a specific device so sessions do not collide.
 
 ### Connect & diagnostics
 
-| Tool               | Purpose                                                                                                                                                                                                                                                                                            |
-| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `debugger-connect` | Connect to the JS runtime's CDP (Metro on iOS / Android; the page CDP session on Chromium). Returns port, projectRoot (empty on Chromium), deviceName, appName, `logicalDeviceId`, isNewDebugger, connected. The returned `logicalDeviceId` is the `device_id` for every subsequent debugger call. |
-| `debugger-status`  | Like connect + loadedScripts, enabledDomains, sourceMapReady (no-op on Chromium). **Use to diagnose.**                                                                                                                                                                                             |
+| Tool               | Purpose                                                                                                                                                                                                                                                                                                                                                                |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `debugger-connect` | Connect to the JS runtime's CDP (Metro on iOS / Android / Vega; the page CDP session on Chromium). Returns port, projectRoot (empty on Chromium and on legacy Metro, e.g. Vega), deviceName, appName, `logicalDeviceId` (absent on Vega), isNewDebugger, connected. When a `logicalDeviceId` comes back, use it as the `device_id` for every subsequent debugger call. |
+| `debugger-status`  | Like connect + loadedScripts, enabledDomains, sourceMapReady (no-op on Chromium). **Use to diagnose.**                                                                                                                                                                                                                                                                 |
 
 ### Reload & recovery
 

package/skills/argent-metro-debugger/references/failure-scenarios.md

@@ -2,9 +2,9 @@
 
 When a debugger tool fails, use **`debugger-status`** first to diagnose. Then match the error or situation below and act as specified. Do not retry the same failing tool repeatedly without following the recovery steps.
 
-| Scenario                           | Error or situation                                                                         | What to do                                                                                                                                                                                                                                                                                                                                                      |
-| ---------------------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Metro not running**              | Error contains: `Metro at port 8081 is not running (got: ...)`                             | **Start Metro yourself** unless the user asked you not to: scan the workspace configuration and run the appropriate command to start Metro in the background (by default `npx react-native start` or `npx expo start`). Wait for Metro to be ready, then retry `debugger-connect` or `debugger-status`. If you cannot determine the project root, ask the user. |
-| **Metro not standard**             | Error contains: `Metro at port 8081 did not return X-React-Native-Project-Root header`     | Something on that port is not the standard React Native Metro server. Try starting Metro yourself from the app's project root using the command resolution above. If you cannot determine the correct root or the problem persists, inform the user what you found and what you tried.                                                                          |
-| **App not connected**              | Error contains: `Metro at port 8081 has no CDP targets — is a React Native app connected?` | 1) Confirm the app is running on the device. 2) Use `restart-app` with the app's device id and bundleId to relaunch so it connects to Metro. 3) Wait a few seconds for the bundle to load. 4) Retry `debugger-status`. Do **not** use `debugger-reload-metro` to fix this — it also requires at least one target.                                               |
-| **Was connected, then tool fails** | Any debugger tool fails with a connection or disconnect error after it was working         | The app may have crashed or been closed. Use `restart-app` to relaunch the app, then call `debugger-connect` again to pick up the fresh `logicalDeviceId` (may change for booted-fresh simulators), and use that new `device_id` on all subsequent calls.                                                                                                       |
+| Scenario                           | Error or situation                                                                         | What to do                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ---------------------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Metro not running**              | Error contains: `Metro at port 8081 is not running (got: ...)`                             | **Start Metro yourself** unless the user asked you not to: scan the workspace configuration and run the appropriate command to start Metro in the background (by default `npx react-native start` or `npx expo start`). Wait for Metro to be ready, then retry `debugger-connect` or `debugger-status`. If you cannot determine the project root, ask the user. A non-Metro server occupying the port lands here too — the `got:` text shows what answered. |
+| **No source locations**            | `projectRoot` is `""` and source lookups report no file:line                               | Not a failure. Legacy Metro (RN 0.72 and older, e.g. Vega) sends no `X-React-Native-Project-Root` header, so paths cannot be resolved against a project root. `debugger-evaluate`, console logs and the network inspector work regardless — do not restart Metro to "fix" it.                                                                                                                                                                               |
+| **App not connected**              | Error contains: `Metro at port 8081 has no CDP targets — is a React Native app connected?` | 1) Confirm the app is running on the device. 2) Use `restart-app` with the app's device id and bundleId to relaunch so it connects to Metro. 3) Wait a few seconds for the bundle to load. 4) Retry `debugger-status`. Do **not** use `debugger-reload-metro` to fix this — it also requires at least one target.                                                                                                                                           |
+| **Was connected, then tool fails** | Any debugger tool fails with a connection or disconnect error after it was working         | The app may have crashed or been closed. Use `restart-app` to relaunch the app, then call `debugger-connect` again to pick up the fresh `logicalDeviceId` (may change for booted-fresh simulators), and use that new `device_id` on all subsequent calls.                                                                                                                                                                                                   |

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

@@ -1,6 +1,6 @@
 ---
 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.
+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, screenshot, and on Vega debug the JS runtime (evaluate, console logs, network inspector). 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)
@@ -58,3 +58,13 @@ Needs a Debug build + Metro running. argent only _connects_ to Metro — start M
 
 - **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.
+
+## Debugging the JS runtime (Vega)
+
+Once that same Debug build + Metro setup is in place, the JS-runtime tools work on a Vega VVD: `debugger-connect`, `debugger-status`, `debugger-evaluate`, `debugger-log-registry` (console logs), `view-network-logs`, and `view-network-request-details`. See the `argent-metro-debugger` skill.
+
+Vega's React Native forks RN 0.72 and serves the legacy Hermes inspector, so three things differ from iOS / Android:
+
+- `debugger-component-tree`, `debugger-inspect-element`, `debugger-reload-metro` and the `react-profiler-*` / `profiler-*` tools are **not supported**. Component-tree and inspect-element are hard-blocked: they need `Runtime.addBinding`, which this Hermes acknowledges but never installs. The rest are simply unverified on the legacy inspector. Use `describe` for on-screen structure; with both component tools gated off, component `file:line` tracing has no path on Vega.
+- `debugger-status` reports `isNewDebugger: false`.
+- `projectRoot` is empty (RN 0.72's Metro sends no project-root header), so lookups that resolve paths against the project root return no location.