@houwert/conductor 0.22.0 → 0.24.0

package/dist/drivers/vega/page-source-parser.js

@@ -0,0 +1,229 @@
+"use strict";
+/**
+ * Converts the Vega automation toolkit's `getPageSource` XML into the
+ * uiautomator-style `<node>` XML that conductor's Android element resolver
+ * (`parseAndroidHierarchy`, `findAndroidElement`, `inspectAndroidToText`)
+ * already understands. This lets Vega reuse the entire Android inspection and
+ * element-resolution path unchanged.
+ *
+ * Toolkit shape: `<root><app appName><window x/y/width/height><child role test_id
+ * focusable selectable clickable focused selected>…<text>label</text></child>
+ * </window></app></root>`. `<traits>` subtrees are metadata (dropped); bare
+ * structural wrappers (no role, interactivity, or text) are flattened; the
+ * persistent Kepler launcher app is filtered so only the foreground app shows.
+ * Coordinates are absolute device pixels — emitted as `[x,y][x+w,y+h]`, exactly
+ * like the Android adapter (no normalization).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseVegaPageSource = parseVegaPageSource;
+const LAUNCHER_APP = 'com.amazon.keplerlauncherapp';
+/** Parse Vega toolkit XML and re-emit it as uiautomator `<node>` XML. */
+function parseVegaPageSource(xml) {
+    const root = parseXml(xml);
+    if (!root)
+        return '<?xml version="1.0" encoding="UTF-8"?>\n<hierarchy />';
+    const lines = ['<?xml version="1.0" encoding="UTF-8"?>', '<hierarchy>'];
+    for (const scope of foregroundScopes(root)) {
+        for (const child of scope.children) {
+            emitNode(child, lines, 1);
+        }
+    }
+    lines.push('</hierarchy>');
+    return lines.join('\n');
+}
+/** The `<app>` subtrees to render: foreground apps, excluding the launcher. */
+function foregroundScopes(root) {
+    const apps = root.children.filter((c) => c.tag === 'app');
+    if (apps.length === 0)
+        return [root];
+    const foreground = apps.filter((a) => a.attrs['appName'] !== LAUNCHER_APP);
+    return foreground.length > 0 ? foreground : apps;
+}
+function emitNode(node, lines, depth) {
+    if (node.tag === 'traits' || node.tag === 'text')
+        return;
+    const meaningful = isMeaningful(node);
+    const rendered = node.children.filter((c) => c.tag !== 'traits' && c.tag !== 'text');
+    if (!meaningful) {
+        // Flatten structural wrapper — emit its children in its place.
+        for (const child of rendered)
+            emitNode(child, lines, depth);
+        return;
+    }
+    const attrs = [];
+    const role = node.attrs['role'];
+    if (role)
+        attrs.push(`class="${xmlEscape(role)}"`);
+    const testId = node.attrs['test_id'];
+    if (testId)
+        attrs.push(`resource-id="${xmlEscape(testId)}"`);
+    const label = labelOf(node);
+    if (label)
+        attrs.push(`text="${xmlEscape(label)}"`);
+    attrs.push(`bounds="${boundsOf(node)}"`);
+    const interactive = isInteractive(node);
+    attrs.push(`clickable="${interactive ? 'true' : 'false'}"`);
+    if (node.attrs['focused'] !== undefined) {
+        attrs.push(`focused="${boolAttr(node, 'focused')}"`);
+    }
+    if (node.attrs['selected'] !== undefined) {
+        attrs.push(`selected="${boolAttr(node, 'selected')}"`);
+    }
+    attrs.push('enabled="true"');
+    const indent = '  '.repeat(depth);
+    if (rendered.length === 0) {
+        lines.push(`${indent}<node ${attrs.join(' ')} />`);
+        return;
+    }
+    lines.push(`${indent}<node ${attrs.join(' ')}>`);
+    for (const child of rendered)
+        emitNode(child, lines, depth + 1);
+    lines.push(`${indent}</node>`);
+}
+// A node earns a line when it carries meaning: an explicit role, interactivity,
+// or its own text. Bare structural wrappers are flattened.
+function isMeaningful(node) {
+    return !!node.attrs['role'] || isInteractive(node) || labelOf(node).length > 0;
+}
+function isInteractive(node) {
+    return boolAttr(node, 'focusable') || boolAttr(node, 'selectable') || boolAttr(node, 'clickable');
+}
+/** Label = this node's direct text plus the text of its direct `<text>` children. */
+function labelOf(node) {
+    const parts = [];
+    if (node.text.trim())
+        parts.push(node.text.trim());
+    for (const child of node.children) {
+        if (child.tag === 'text' && child.text.trim())
+            parts.push(child.text.trim());
+    }
+    return parts.join(' ').trim();
+}
+function boundsOf(node) {
+    const x = intAttr(node, 'x');
+    const y = intAttr(node, 'y');
+    const w = intAttr(node, 'width');
+    const h = intAttr(node, 'height');
+    return `[${x},${y}][${x + w},${y + h}]`;
+}
+function boolAttr(node, name) {
+    const v = (node.attrs[name] ?? '').trim().toLowerCase();
+    return v === 'true' || v === '1';
+}
+function intAttr(node, name) {
+    return parseInt(node.attrs[name] ?? '', 10) || 0;
+}
+function xmlEscape(s) {
+    return s
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+// ── Minimal XML parser ────────────────────────────────────────────────────────
+// Handles elements, attributes, text nodes, self-closing tags, and skips the XML
+// declaration / comments. Sufficient for the well-formed toolkit output.
+function parseXml(xml) {
+    let i = 0;
+    const n = xml.length;
+    function skipWhitespace() {
+        while (i < n && /\s/.test(xml[i]))
+            i++;
+    }
+    function parseNode() {
+        // Skip declarations, comments, and processing instructions before the tag.
+        while (i < n) {
+            skipWhitespace();
+            if (xml.startsWith('<?', i)) {
+                i = xml.indexOf('?>', i);
+                i = i === -1 ? n : i + 2;
+                continue;
+            }
+            if (xml.startsWith('<!--', i)) {
+                i = xml.indexOf('-->', i);
+                i = i === -1 ? n : i + 3;
+                continue;
+            }
+            if (xml.startsWith('<!', i)) {
+                i = xml.indexOf('>', i);
+                i = i === -1 ? n : i + 1;
+                continue;
+            }
+            break;
+        }
+        if (i >= n || xml[i] !== '<')
+            return null;
+        i++; // consume '<'
+        // Read tag name
+        const nameStart = i;
+        while (i < n && !/[\s/>]/.test(xml[i]))
+            i++;
+        const tag = xml.slice(nameStart, i);
+        const attrs = {};
+        // Read attributes
+        while (i < n) {
+            skipWhitespace();
+            if (xml[i] === '/' || xml[i] === '>')
+                break;
+            const attrNameStart = i;
+            while (i < n && !/[\s=/>]/.test(xml[i]))
+                i++;
+            const attrName = xml.slice(attrNameStart, i);
+            skipWhitespace();
+            let attrValue = '';
+            if (xml[i] === '=') {
+                i++; // consume '='
+                skipWhitespace();
+                const quote = xml[i];
+                if (quote === '"' || quote === "'") {
+                    i++;
+                    const valStart = i;
+                    while (i < n && xml[i] !== quote)
+                        i++;
+                    attrValue = xmlUnescape(xml.slice(valStart, i));
+                    i++; // consume closing quote
+                }
+            }
+            if (attrName)
+                attrs[attrName] = attrValue;
+        }
+        const node = { tag, attrs, children: [], text: '' };
+        if (xml[i] === '/') {
+            // self-closing
+            i = xml.indexOf('>', i);
+            i = i === -1 ? n : i + 1;
+            return node;
+        }
+        i++; // consume '>'
+        // Read children / text until closing tag
+        while (i < n) {
+            if (xml.startsWith('</', i)) {
+                i = xml.indexOf('>', i);
+                i = i === -1 ? n : i + 1;
+                break;
+            }
+            if (xml[i] === '<') {
+                const child = parseNode();
+                if (child)
+                    node.children.push(child);
+            }
+            else {
+                const textStart = i;
+                while (i < n && xml[i] !== '<')
+                    i++;
+                node.text += xmlUnescape(xml.slice(textStart, i));
+            }
+        }
+        return node;
+    }
+    return parseNode();
+}
+function xmlUnescape(s) {
+    return s
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&apos;/g, "'")
+        .replace(/&amp;/g, '&');
+}

package/dist/drivers/vega.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VegaDriver = void 0;
+/**
+ * Driver client for Amazon Vega (Fire TV) devices. Vega is a Linux/React Native
+ * OS (not Android), reached through Amazon's `vega`/`kepler` CLI — there is no
+ * XCTest/gRPC driver process and no local control port. This class is a
+ * standalone, stateless client that shells out to the CLI plus the on-device
+ * automation toolkit:
+ *  - view hierarchy from the toolkit (JSON-RPC on device port 8383), re-emitted
+ *    as uiautomator XML so the Android element resolver handles it,
+ *  - input via the stock `inputd-cli` (D-pad button_press, touch, swipe, send_text),
+ *  - screenshots via the toolkit's `takeScreenshot`,
+ *  - app lifecycle via `vega device …`.
+ *
+ * v1 targets the Vega Virtual Device (VVD); physical Fire TV sticks reuse the
+ * same path.
+ */
+const cli_js_1 = require("./vega/cli.js");
+const connection_js_1 = require("./vega/connection.js");
+const automation_client_js_1 = require("./vega/automation-client.js");
+const input_js_1 = require("./vega/input.js");
+const page_source_parser_js_1 = require("./vega/page-source-parser.js");
+const UNSUPPORTED = (op) => new Error(`${op} is not supported on vega (Amazon Fire TV)`);
+class VegaDriver {
+    /** `serial` is the bare Vega selector (e.g. `VirtualDevice`), not the `vega:` id. */
+    constructor(serial) {
+        this.serial = serial;
+        this.platform = 'vega';
+        this.screenSize = null;
+        this.cli = new cli_js_1.VegaCli(serial);
+        this.connection = new connection_js_1.VegaDeviceConnection(serial, this.cli);
+        this.automation = new automation_client_js_1.VegaAutomationClient(this.connection);
+        this.input = new input_js_1.VegaInput(this.connection);
+    }
+    async isAlive() {
+        const devices = await this.cli.listDevices().catch(() => []);
+        return devices.some((d) => d.serial === this.serial);
+    }
+    async deviceInfo() {
+        const size = await this.resolveScreenSize();
+        return { widthPixels: size.width, heightPixels: size.height };
+    }
+    async resolveScreenSize() {
+        if (this.screenSize)
+            return this.screenSize;
+        const size = (await this.connection.screenSize().catch(() => null)) ?? {
+            width: 1920,
+            height: 1080,
+        };
+        this.screenSize = size;
+        return size;
+    }
+    // ── Input ──────────────────────────────────────────────────────────────────
+    async tap(x, y, duration) {
+        if (duration && duration >= 0.5) {
+            await this.input.longPress(x, y);
+        }
+        else {
+            await this.input.tap(x, y);
+        }
+    }
+    async longPress(x, y) {
+        await this.input.longPress(x, y);
+    }
+    async swipe(startX, startY, endX, endY, durationMs) {
+        await this.input.swipe(startX, startY, endX, endY, durationMs);
+    }
+    async pressButton(button) {
+        await this.input.pressButton(button);
+    }
+    async back() {
+        await this.input.pressButton('back');
+    }
+    async inputText(text) {
+        await this.input.inputText(text);
+    }
+    async eraseAllText(charactersToErase = 50) {
+        await this.input.eraseText(charactersToErase);
+    }
+    // ── Inspection ───────────────────────────────────────────────────────────────
+    /** Returns uiautomator-style XML (consumed by the Android element resolver). */
+    async viewHierarchy() {
+        const xml = await this.automation.getPageSource();
+        return (0, page_source_parser_js_1.parseVegaPageSource)(xml);
+    }
+    async screenshot(_opts = {}) {
+        return this.automation.getScreenshot();
+    }
+    // ── App lifecycle ────────────────────────────────────────────────────────────
+    async launchApp(appId, _args) {
+        // Cold launch: terminate first so a singleton app restarts from initial state.
+        await this.cli.terminateApp(appId);
+        // The toolkit reads the enable flag at launch, so set it before (re)launching.
+        await this.connection.ensureToolkitEnabled();
+        await this.cli.launchApp(appId);
+    }
+    async terminateApp(appId) {
+        await this.cli.terminateApp(appId);
+    }
+    async stopApp(appId) {
+        await this.cli.terminateApp(appId);
+    }
+    async installApp(vpkgPath) {
+        await this.cli.installApp(vpkgPath);
+    }
+    async listInstalledApps() {
+        return this.cli.listInstalledApps();
+    }
+    async getForegroundApp() {
+        // The toolkit page source names the foreground (non-launcher) app.
+        const xml = await this.automation.getPageSource();
+        const match = /<app[^>]*\bappName="([^"]+)"/.exec(xml);
+        if (!match)
+            throw new Error('Could not determine foreground app');
+        return match[1];
+    }
+    // ── Unsupported on vega (gated with clear errors) ────────────────────────────
+    async clearAppState(_appId) {
+        throw UNSUPPORTED('clear-state');
+    }
+    async clearKeychain() {
+        // Not applicable on Vega — no-op.
+    }
+    async uninstallApp(_appId) {
+        throw UNSUPPORTED('uninstall-app');
+    }
+    async openLink(_url) {
+        throw UNSUPPORTED('open-link');
+    }
+    async setLocation(_latitude, _longitude) {
+        throw UNSUPPORTED('set-location');
+    }
+    async setOrientation(_orientation) {
+        // No-op: Vega/Fire TV is landscape-only.
+    }
+    async setPermissions(_appId, _permissions) {
+        // No runtime-permission grant primitive on Vega in v1 — no-op.
+    }
+    async addMedia(_filePath) {
+        throw UNSUPPORTED('add-media');
+    }
+    async setAirplaneMode(_enabled) {
+        throw UNSUPPORTED('airplane mode');
+    }
+    async getAirplaneMode() {
+        throw UNSUPPORTED('airplane mode');
+    }
+    async gesturePath(_paths) {
+        throw UNSUPPORTED('multi-finger gestures');
+    }
+    async startRecording(_outputPath) {
+        throw UNSUPPORTED('screen recording');
+    }
+    async stopRecording() {
+        throw UNSUPPORTED('screen recording');
+    }
+    async clipboardRead() {
+        throw UNSUPPORTED('clipboard');
+    }
+    async clipboardWrite(_text) {
+        throw UNSUPPORTED('clipboard');
+    }
+}
+exports.VegaDriver = VegaDriver;

package/dist/enum-options.js

@@ -24,7 +24,7 @@ exports.ENUM_PARAMS = [
         param: '<key>',
         description: 'Key, hardware button, or remote button to press',
         values: press_key_js_1.VALID_KEYS.map((value) => ({ value })),
-        note: 'Matched case-insensitively. Availability varies by platform: "Remote …" / "TV …" keys target tvOS and Android TV; hardware buttons (Home, Lock, Power, Volume…) target iOS/Android.',
+        note: 'Matched case-insensitively. Availability varies by platform: "Remote …" / "TV …" keys target tvOS, Android TV, and vega (Amazon Fire TV); hardware buttons (Home, Lock, Power, Volume…) target iOS/Android.',
     },
     {
         command: 'scroll',
@@ -56,7 +56,13 @@ exports.ENUM_PARAMS = [
         param: '--platform',
         description: 'Platform of the device to start',
         // Source: switch in commands/start-device.ts
-        values: [{ value: 'ios' }, { value: 'android' }, { value: 'tvos' }, { value: 'web' }],
+        values: [
+            { value: 'ios' },
+            { value: 'android' },
+            { value: 'tvos' },
+            { value: 'web' },
+            { value: 'vega' },
+        ],
     },
     {
         command: 'install-web',
@@ -98,7 +104,13 @@ exports.ENUM_PARAMS = [
         command: 'list-devices',
         param: '--platform',
         description: 'Filter listed devices by platform (also a global filter on most commands)',
-        values: [{ value: 'ios' }, { value: 'android' }, { value: 'tvos' }, { value: 'web' }],
+        values: [
+            { value: 'ios' },
+            { value: 'android' },
+            { value: 'tvos' },
+            { value: 'web' },
+            { value: 'vega' },
+        ],
     },
 ];
 /** All distinct command names that have at least one enumerated parameter. */

package/dist/index.js

@@ -64,6 +64,7 @@ const options_js_1 = require("./commands/options.js");
 const web_targets_js_1 = require("./commands/web-targets.js");
 const session_js_2 = require("./session.js");
 const device_picker_js_1 = require("./device-picker.js");
+const cdp_discovery_js_1 = require("./drivers/cdp-discovery.js");
 const update_check_js_1 = require("./update-check.js");
 const pkg_root_js_1 = require("./pkg-root.js");
 const fs_1 = __importDefault(require("fs"));
@@ -130,7 +131,7 @@ const COMMAND_HELP = {
 const OPTIONS_HELP = `Options:
   --device <id>     Target device ID (also keys the session and daemon)
   --device-name <n> Target a booted device by name (resolved to ID from booted devices)
-  --platform <p>    Filter to devices of this platform (ios, android, tvos, web)
+  --platform <p>    Filter to devices of this platform (ios, android, tvos, web, vega)
   --cdp-url <url>   Attach the web driver to an existing browser over CDP (e.g. an
                     Electron app started with --remote-debugging-port). Remembered per session.
   --cdp-target <id> Pick which CDP page target to control (see \`conductor web-targets\`)
@@ -238,6 +239,7 @@ async function main() {
             'color-scheme',
             'cdp-url',
             'cdp-target',
+            'duration',
         ],
         alias: { h: 'help', v: 'verbose', V: 'version', o: 'output', y: 'yes' },
     });
@@ -325,6 +327,9 @@ async function main() {
     if (isWebSession && !NO_DEVICE_COMMANDS.has(command)) {
         const cdpUrlFlag = argv['cdp-url'];
         const cdpTargetFlag = argv['cdp-target'];
+        // A discovered `web:cdp:<port>:<target>` device id is self-describing —
+        // derive the CDP url/target from it so it's drivable with no --cdp-* flags.
+        const fromDeviceId = (0, cdp_discovery_js_1.parseCdpDeviceId)(sessionName);
         if (cdpUrlFlag || cdpTargetFlag) {
             if (cdpUrlFlag)
                 process.env.CONDUCTOR_CDP_URL = cdpUrlFlag;
@@ -335,6 +340,13 @@ async function main() {
                 cdpTargetId: process.env.CONDUCTOR_CDP_TARGET_ID,
             }, sessionName);
         }
+        else if (fromDeviceId) {
+            if (!process.env.CONDUCTOR_CDP_URL)
+                process.env.CONDUCTOR_CDP_URL = fromDeviceId.cdpUrl;
+            if (!process.env.CONDUCTOR_CDP_TARGET_ID) {
+                process.env.CONDUCTOR_CDP_TARGET_ID = fromDeviceId.targetId;
+            }
+        }
         else {
             const saved = await (0, session_js_2.getSession)(sessionName);
             if (saved.cdpUrl && !process.env.CONDUCTOR_CDP_URL) {
@@ -471,7 +483,11 @@ async function main() {
             break;
         case 'press-key': {
             const key = rest[0] ?? '';
-            exitCode = await (0, press_key_js_1.pressKey)(key, opts, sessionName);
+            const durationArg = argv['duration'];
+            exitCode = await (0, press_key_js_1.pressKey)(key, opts, sessionName, {
+                longPress: argv['long-press'],
+                duration: durationArg !== undefined ? Number(durationArg) : undefined,
+            });
             break;
         }
         case 'list-options': {

package/dist/runner.js

@@ -14,6 +14,8 @@ const verbose_js_1 = require("./verbose.js");
 const ios_js_1 = require("./drivers/ios.js");
 const android_js_1 = require("./drivers/android.js");
 const web_js_1 = require("./drivers/web.js");
+const vega_js_1 = require("./drivers/vega.js");
+const cli_js_1 = require("./drivers/vega/cli.js");
 const bootstrap_js_1 = require("./drivers/bootstrap.js");
 const client_js_1 = require("./daemon/client.js");
 /**
@@ -75,9 +77,27 @@ async function detectFirstDevice() {
             return session;
         }
     }
+    // Vega (Amazon Fire TV): query the vega CLI for a booted device. Best-effort —
+    // the CLI is absent unless the Vega SDK is installed.
+    try {
+        const devices = await new cli_js_1.VegaCli().listDevices();
+        const device = devices[0];
+        if (device) {
+            (0, verbose_js_1.log)(`detectFirstDevice: found Vega device "${device.serial}"`);
+            _cachedDeviceId = `vega:${device.serial}`;
+            return _cachedDeviceId;
+        }
+    }
+    catch {
+        /* vega CLI not installed */
+    }
     _cachedDeviceId = null;
     return undefined;
 }
+/** Strip the `vega:` prefix to recover the bare Vega selector. */
+function vegaSerial(deviceId) {
+    return deviceId.startsWith('vega:') ? deviceId.slice('vega:'.length) : deviceId;
+}
 /** Per-session driver cache (process lifetime). */
 const _driverCache = new Map();
 /**
@@ -166,6 +186,17 @@ async function getDriver(sessionName = 'default') {
         }
         driver = webDriver;
     }
+    else if (platform === 'vega') {
+        // Vega has no driver process/port — control is host-side via the vega CLI.
+        // Start the daemon best-effort for log collection, but never block control on it.
+        (0, client_js_1.startDaemon)(deviceId).catch(() => { });
+        const vegaDriver = new vega_js_1.VegaDriver(vegaSerial(deviceId));
+        if (!(await vegaDriver.isAlive())) {
+            throw new Error(`No running Vega device matches "${vegaSerial(deviceId)}".\n` +
+                `Boot a VVD and check \`vega device list\`, or install the Vega SDK (\`vega\`/\`kepler\`).`);
+        }
+        driver = vegaDriver;
+    }
     else {
         // Ensure the daemon is running — it handles APK install and driver startup.
         await (0, client_js_1.startDaemon)(deviceId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@houwert/conductor",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "CLI tool for mobile app interactions — optimized for AI agents",
   "license": "MIT",
   "repository": {

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

@@ -1,6 +1,6 @@
 ---
 name: conductor-device-interact
-description: Drive a running iOS simulator, Android emulator, tvOS simulator, or Playwright web app with the conductor CLI. Use when launching apps, tapping UI elements, typing text, scrolling/swiping, performing gestures, pressing hardware/keyboard keys, opening URLs or deep links, navigating back, or verifying an app change in the real running app.
+description: Drive a running iOS simulator, Android emulator, tvOS simulator, Vega (Amazon Fire TV) virtual device, or Playwright web app with the conductor CLI. Use when launching apps, tapping UI elements, typing text, scrolling/swiping, performing gestures, pressing hardware/keyboard/remote keys, opening URLs or deep links, navigating back, or verifying an app change in the real running app.
 ---
 
 # Conductor — device interaction
@@ -39,7 +39,7 @@ conductor assert-visible "Dashboard"
 | `conductor tap-on <element>` | Tap by text, id, or `@eN`. `--long-press`, `--double-tap`, `--optional`, `--index <n>` |
 | `conductor input-text <text>` | Type into the focused field |
 | `conductor erase-text [n]` | Erase n characters (default 50) |
-| `conductor press-key <key>` | Press a key (Enter, Backspace, Home, …) |
+| `conductor press-key <key>` | Press a key (Enter, Backspace, Home, …) or a remote button (`Remote Dpad Up/Down/Left/Right/Center`, `Remote Menu`) for tvOS / Android TV / vega. `--long-press` / `--duration <seconds>` holds it |
 | `conductor hide-keyboard` | Dismiss the on-screen keyboard |
 | `conductor back` | Press back |
 | `conductor scroll [--direction down\|up\|left\|right]` | Scroll |
@@ -90,7 +90,8 @@ relaunch without the flag. (See `conductor-device-setup`.)
 
 ## Tips
 
-- `--device <id>` / `--device-name <name>` targets a device; `--platform <ios|android|tvos|web>` scopes by platform.
+- `--device <id>` / `--device-name <name>` targets a device; `--platform <ios|android|tvos|web|vega>` scopes by platform.
+- Vega (Amazon Fire TV) is D-pad driven: navigate with `press-key "Remote Dpad …"`; coordinate `tap-on` also works. `open-link`, `set-location`, gestures, and clipboard are unsupported. See `conductor-device-setup`.
 - Add `--json` for machine-readable output; failed assertions exit non-zero.
 - Run a per-session daemon for many commands (see `conductor-device-setup`).
 - `conductor <command> --help` for exact flags.

package/skills/conductor-device-setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: conductor-device-setup
-description: Boot, list, and manage devices and app installs for the conductor CLI — iOS simulators, Android emulators, tvOS simulators, and Playwright web browsers — plus sessions, the warm-driver daemon, and the parallel device pool. Use when starting or stopping a simulator/emulator/browser, installing or launching an app, setting up the web driver, attaching to an already-running browser over CDP (e.g. an Electron app / its webviews), keeping the driver warm, or coordinating multiple devices for parallel agents.
+description: Boot, list, and manage devices and app installs for the conductor CLI — iOS simulators, Android emulators, tvOS simulators, Vega (Amazon Fire TV) virtual devices, and Playwright web browsers — plus sessions, the warm-driver daemon, and the parallel device pool. Use when starting or stopping a simulator/emulator/browser, attaching to a Vega VVD, installing or launching an app, setting up the web driver, attaching to an already-running browser over CDP (e.g. an Electron app / its webviews), keeping the driver warm, or coordinating multiple devices for parallel agents.
 ---
 
 # Conductor — device & app setup
@@ -21,7 +21,7 @@ conductor list-apps          # installed app ids / package names
 
 | Command                                                               | Purpose                                                                    |
 | --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
-| `conductor start-device --platform <ios\|android\|tvos\|web>`         | Boot a simulator/emulator or start the web driver                          |
+| `conductor start-device --platform <ios\|android\|tvos\|web\|vega>`   | Boot a simulator/emulator, start the web driver, or attach to a Vega VVD    |
 | `conductor start-device --os-version <n> --device-type <name>`        | Pick OS version + device type (creates if needed)                          |
 | `conductor stop-device [<name-or-id>] [--all]`                        | Shut down device(s)                                                        |
 | `conductor delete-device <name-or-id> [--all]`                        | Delete simulator(s)/AVD(s)/web session(s)                                  |
@@ -47,6 +47,27 @@ Use a distinct fully-qualified `--device web:chromium:<label>` per target (a bar
 several webviews can be driven concurrently. Only `type=page` targets are
 controllable. See [Web testing → Attaching to an existing browser](../../../docs/web.md).
 
+**Discovery:** endpoints on the conventional debugging ports (9222–9229 on
+localhost) are found automatically — `list-devices` shows each webview as a
+booted `web:cdp:<port>:<targetId>` device. That id is self-describing, so you can
+drive it directly (`conductor --device web:cdp:9222:<targetId> <cmd>`) without
+`--cdp-url`/`--cdp-target`. Use `web-targets --cdp-url <url>` for endpoints on a
+non-default port, or to list targets before binding.
+
+### Vega (Amazon Fire TV)
+
+Vega is a React Native OS driven through Amazon's own `vega`/`kepler` CLI (not
+adb/simctl) — install the Vega SDK and put the CLI on `PATH` (or set
+`CONDUCTOR_VEGA_CLI`). `conductor start-device --platform vega` boots a Vega
+Virtual Device (VVD) via `vega virtual-device start` (or attaches if one is
+already running); pass `--name <vvd>` to pick a specific one. Devices show up in
+`list-devices` as `vega:<serial>`. The VVD's
+**developer mode** must be on for input, and the automation toolkit attaches at
+app launch — so launch the app under test via conductor. Navigate with the D-pad
+(`press-key "Remote Dpad …"` / `"Remote Dpad Center"`); coordinate `tap-on` also
+works. Unsupported on Vega: deep links (`open-link`), `set-location`, gestures,
+screen recording, clipboard, `clear-state`/`uninstall-app`.
+
 ## App lifecycle
 
 | Command                                               | Purpose                                                                |