@metamask/device-mcp 0.3.2 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0]
+
+### Fixed
+
+- fix: make idb gestures scroll and report correct device geometry ([#27](https://github.com/MetaMask/device-mcp/pull/27))
+- fix: make simulator element extraction work across iOS 17-26 ([#25](https://github.com/MetaMask/device-mcp/pull/25))
+- fix: code scanner error for java files ([#26](https://github.com/MetaMask/device-mcp/pull/26))
+- fix: UI automator staleness issue ([#23](https://github.com/MetaMask/device-mcp/pull/23))
+
+## [0.3.3]
+
+### Changed
+
+- feat: add public `kind` discriminator to DeviceBackend ([#21](https://github.com/MetaMask/device-mcp/pull/21))
+
 ## [0.3.2]
 
 ### Changed
@@ -55,7 +70,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `.device-session` file for attaching to existing Appium sessions or creating new ones
 - 16 MCP tools: `device_snapshot`, `device_screenshot`, `device_info`, `device_tap_element`, `device_tap_coordinates`, `device_type`, `device_swipe`, `device_long_press`, `device_wait_for`, `device_app_state`, `device_open_app`, `device_close_app`, `device_press_button`, `device_dismiss_keyboard`, `device_dismiss_alert`, `device_logs`
 
-[Unreleased]: https://github.com/MetaMask/device-mcp/compare/v0.3.2...HEAD
+[Unreleased]: https://github.com/MetaMask/device-mcp/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/MetaMask/device-mcp/compare/v0.3.3...v0.4.0
+[0.3.3]: https://github.com/MetaMask/device-mcp/compare/v0.3.2...v0.3.3
 [0.3.2]: https://github.com/MetaMask/device-mcp/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/MetaMask/device-mcp/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/MetaMask/device-mcp/compare/v0.2.0...v0.3.0

package/README.md

@@ -15,7 +15,7 @@ Provides device interaction tools for LLM agents to inspect UI state, interact w
 ## Requirements
 
 - **Node.js** `^20 || ^22 || >=24`
-- **iOS local**: Xcode Command Line Tools (for `xcrun simctl`) + [IDB](https://fbidb.io/) for UI interaction (`brew tap facebook/fb && brew install idb-companion && pip3 install fb-idb`)
+- **iOS local**: Xcode Command Line Tools (for `xcrun simctl`) + [IDB](https://fbidb.io/) for UI interaction. Install the unified client (`brew tap facebook/fb && brew install idb`), which bundles the CLI and simulator companion. On iOS 17+ simulators, element extraction requires this modern `idb` (it uses `idb ui describe-all --api axbridge`); the legacy python `fb-idb` client does not support `--api` and will not read the UI hierarchy on newer runtimes.
 - **Android local**: ADB (Android SDK platform-tools) — auto-discovered from `$ANDROID_HOME`, `$ANDROID_SDK_ROOT`, or `~/Library/Android/sdk`
 - **Remote/BrowserStack**: No local tools needed — connects via Appium W3C WebDriver HTTP
 - **Hermes CDP** (debugging the React Native JS runtime): uses the global `WebSocket` API. Node 22+ works out of the box; **Node 20 requires launching with `NODE_OPTIONS="--experimental-websocket"`**.
@@ -174,26 +174,115 @@ Elements are identified by accessibility attributes — not internal refs. Match
 
 ### Backend Implementation
 
-| Tool                      | iOS (IDB)                            | Android (ADB)        | Appium (W3C WebDriver)        |
-| ------------------------- | ------------------------------------ | -------------------- | ----------------------------- |
-| `device_snapshot`         | `idb ui describe-all`                | `uiautomator dump`   | `mobile: source`              |
-| `device_screenshot`       | `idb screenshot`                     | `screencap` + `pull` | `mobile: getScreenshot`       |
-| `device_info`             | `idb describe`                       | `getprop`            | session capabilities          |
-| `device_tap_element`      | find + `idb ui tap`                  | find + `input tap`   | find + W3C Actions            |
-| `device_tap_coordinates`  | `idb ui tap x y`                     | `input tap x y`      | W3C Actions                   |
-| `device_type`             | `idb ui text`                        | `input text`         | `findElement` + `sendKeys`    |
-| `device_swipe`            | `idb ui swipe`                       | `input swipe`        | W3C Actions                   |
-| `device_long_press`       | `idb ui tap --duration`              | `input swipe` (hold) | W3C Actions (pause)           |
-| `device_wait_for`         | poll snapshot                        | poll snapshot        | poll snapshot                 |
-| `device_list_devices`     | `xcrun simctl list`                  | `adb devices`        | N/A                           |
-| `device_select_device`    | select by UDID                       | select by serial     | N/A                           |
-| `device_app_state`        | `idb list-apps` / `simctl listapps`  | `dumpsys activity`   | `mobile: queryAppState`       |
-| `device_open_app`         | `idb launch` / `simctl launch`       | `monkey -p`          | `mobile: activateApp`         |
-| `device_close_app`        | `idb terminate` / `simctl terminate` | `am force-stop`      | `mobile: terminateApp`        |
-| `device_press_button`     | `idb ui key`                         | `input keyevent`     | `mobile: pressButton/Key`     |
-| `device_dismiss_keyboard` | `idb ui key RETURN`                  | `input keyevent 111` | `mobile: hideKeyboard`        |
-| `device_dismiss_alert`    | find button + tap                    | find button + tap    | `mobile: accept/dismissAlert` |
-| `device_logs`             | `idb log`                            | `logcat`             | `mobile: getLog`              |
+| Tool                      | iOS (IDB)                            | Android (ADB)                               | Appium (W3C WebDriver)        |
+| ------------------------- | ------------------------------------ | ------------------------------------------- | ----------------------------- |
+| `device_snapshot`         | `idb ui describe-all`                | `uiautomator dump` + instrumentation helper | `mobile: source`              |
+| `device_screenshot`       | `idb screenshot`                     | `screencap` + `pull`                        | `mobile: getScreenshot`       |
+| `device_info`             | `idb describe`                       | `getprop`                                   | session capabilities          |
+| `device_tap_element`      | find + `idb ui tap`                  | find + `input tap`                          | find + W3C Actions            |
+| `device_tap_coordinates`  | `idb ui tap x y`                     | `input tap x y`                             | W3C Actions                   |
+| `device_type`             | `idb ui text`                        | `input text`                                | `findElement` + `sendKeys`    |
+| `device_swipe`            | `idb ui swipe`                       | `input swipe`                               | W3C Actions                   |
+| `device_long_press`       | `idb ui tap --duration`              | `input swipe` (hold)                        | W3C Actions (pause)           |
+| `device_wait_for`         | poll snapshot                        | poll snapshot                               | poll snapshot                 |
+| `device_list_devices`     | `xcrun simctl list`                  | `adb devices`                               | N/A                           |
+| `device_select_device`    | select by UDID                       | select by serial                            | N/A                           |
+| `device_app_state`        | `idb list-apps` / `simctl listapps`  | `dumpsys activity`                          | `mobile: queryAppState`       |
+| `device_open_app`         | `idb launch` / `simctl launch`       | `monkey -p`                                 | `mobile: activateApp`         |
+| `device_close_app`        | `idb terminate` / `simctl terminate` | `am force-stop`                             | `mobile: terminateApp`        |
+| `device_press_button`     | `idb ui key`                         | `input keyevent`                            | `mobile: pressButton/Key`     |
+| `device_dismiss_keyboard` | `idb ui key RETURN`                  | `input keyevent 111`                        | `mobile: hideKeyboard`        |
+| `device_dismiss_alert`    | find button + tap                    | find button + tap                           | `mobile: accept/dismissAlert` |
+| `device_logs`             | `idb log`                            | `logcat`                                    | `mobile: getLog`              |
+
+#### Android snapshot on continuously-redrawing screens
+
+`uiautomator dump` calls `UiAutomation.waitForIdle` internally, which never
+returns on a screen that emits a continuous accessibility-event stream (for
+example a React Native screen with polling or an animating skeleton loader). On
+those screens the stock dump fails with `ERROR: could not get idle state.`
+
+To handle this, the ADB backend ships a small self-instrumenting helper APK
+(`dist/android/device-mcp-android-snapshot-helper-*.apk`, built during
+`prepack`). The helper captures the accessibility hierarchy **without** waiting
+for idle: it skips `waitForIdle` and instead retries a cheap capture until the
+foreground window's root is present, then streams the hierarchy back over
+`am instrument` as chunked base64. It is installed on demand the first time it
+is needed and reused across snapshots in the session.
+
+The strategy is controlled by `DEVICE_MCP_ADB_SNAPSHOT`:
+
+- **`auto`** (default) — a single fast `uiautomator dump` first (wins instantly
+  on idle screens), then the instrumentation helper if that dump does not
+  produce a hierarchy, then the remaining dump retries as a last resort.
+- **`instrument`** — use the instrumentation helper only.
+- **`dump`** — use stock `uiautomator dump` only (the original behavior; no APK
+  is installed).
+
+The helper is a `testOnly` APK installed with `adb install -t`, so it only
+installs on developer emulators/attached devices, never on locked-down or
+managed profiles.
+
+##### Trust: the helper's signing certificate is verified before use
+
+Package names and version codes are attacker-controlled metadata, so before the
+backend runs `am instrument` it verifies that the installed helper is actually
+**ours**. It pulls the installed APK(s) and cryptographically verifies their APK
+Signature Scheme v2/v3 signature (a pure-JS check — no Android SDK required at
+runtime), then compares the signer certificate SHA-256 against the value pinned
+in the bundled build manifest. If a different app is squatting the helper's
+package name, the signer will not match: the snapshot **fails closed** with a
+trust error and does **not** silently fall back to `uiautomator dump`. Generic,
+non-trust failures (a churny screen, an `am` hiccup) still fall back to dump in
+`auto` mode. Use `DEVICE_MCP_ADB_SNAPSHOT=instrument` for a fully fail-closed
+mode, or `DEVICE_MCP_ADB_SNAPSHOT=dump` to skip the helper entirely.
+
+##### Building the Android snapshot helper locally
+
+The helper APK is normally built for you by `prepack` and (for releases) in CI.
+You only need this if you are developing the helper or want the helper-based
+snapshot path to work against a local build.
+
+Requirements: JDK 17, Android SDK with `platforms/android-36` and
+`build-tools;36.0.0` (auto-discovered from `$ANDROID_HOME` / `$ANDROID_SDK_ROOT`
+/ `~/Library/Android/sdk`).
+
+The helper is signed with a shared key so the on-device trust check accepts your
+local build. Obtain the keystore from the team vault, place it **outside** the
+repo, point the build at it, and build:
+
+```bash
+export DEVICE_MCP_HELPER_KEYSTORE=~/.device-mcp/helper.keystore
+export DEVICE_MCP_HELPER_KEYSTORE_PASSWORD=<from vault>
+export DEVICE_MCP_HELPER_KEY_ALIAS=device-mcp-helper
+yarn build:android-helper
+```
+
+The APK and its `.manifest.json` land in `dist/android/`. The MCP server
+installs the APK on demand and verifies its signing certificate before use.
+
+**Don't have the keystore?** You can still develop everything except the
+helper-signed path: the build script auto-generates a throwaway key when
+`DEVICE_MCP_HELPER_KEYSTORE` is unset. A throwaway-signed APK will **not** match
+the pinned signer, so the helper path rejects it by design — run snapshots via
+`DEVICE_MCP_ADB_SNAPSHOT=dump`.
+
+> Never commit a keystore. `*.keystore`, `*.jks`, `*.p12`, and `~/.device-mcp/`
+> are gitignored.
+
+##### Maintainers: one-time signing key generation
+
+```bash
+keytool -genkeypair -v -keystore device-mcp-helper.keystore \
+  -alias device-mcp-helper -keyalg RSA -keysize 2048 -validity 10000 \
+  -dname "CN=Device MCP Snapshot Helper, OU=device-mcp, O=MetaMask, C=US"
+```
+
+Store the keystore in the team vault for developers. For CI, add repository
+secrets `ANDROID_HELPER_KEYSTORE_B64` (`base64 -i device-mcp-helper.keystore`),
+`ANDROID_HELPER_KEYSTORE_PASSWORD`, and `ANDROID_HELPER_KEY_ALIAS`. Then pin the
+certificate SHA-256 that the build emits (`signerSha256` in the manifest) as the
+runtime trust anchor.
 
 ## Hermes CDP
 

package/dist/android/NOTICE.md

@@ -0,0 +1,65 @@
+# Third-party notices
+
+## agent-device (Callstack) — MIT
+
+Portions of the Android snapshot-helper host-side code are derived from the
+`agent-device` project by Callstack.
+
+- Upstream: https://github.com/callstackincubator/agent-device
+- License: MIT — Copyright (c) 2026 Callstack
+- Full license text: see the end of this file.
+
+### What is derived
+
+The structure and approach of the following host-side TypeScript modules were
+adapted from `agent-device`:
+
+- `src/backends/android-instrumentation/artifact.ts` — manifest parsing and
+  artifact SHA-256 verification.
+- `src/backends/android-instrumentation/errors.ts` — the `SnapshotHelperError`
+  shape (the `UntrustedHelperError` trust class is our addition).
+- `src/backends/android-instrumentation/adb.ts` — the device-scoped ADB
+  executor abstraction.
+- `src/backends/android-instrumentation/installer.ts` — the versionCode-based
+  install policy and signer-verification install flow.
+
+### What is NOT derived
+
+The following are original to this project and are not taken from
+`agent-device`:
+
+- The instrumentation helper APK and its Java source
+  (`android/snapshot-helper/`), including the `foregroundWindowObserved`
+  capture fix. This project builds its own APK from source; it does not
+  redistribute Callstack's prebuilt binary or use their package name.
+- `src/backends/android-instrumentation/signer.ts` — a pure-JS APK Signature
+  Scheme v2/v3 signature verifier implemented from the public AOSP
+  specification.
+- `src/backends/android-instrumentation/snapshot.ts` — the chunked
+  instrumentation output parser.
+
+### agent-device MIT license
+
+```
+MIT License
+
+Copyright (c) 2026 Callstack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/dist/android/device-mcp-android-snapshot-helper-0.4.0.manifest.json

@@ -0,0 +1,10 @@
+{
+  "version": "0.4.0",
+  "versionCode": 4000,
+  "packageName": "io.metamask.devicemcp.snapshothelper",
+  "instrumentationRunner": "io.metamask.devicemcp.snapshothelper/.SnapshotInstrumentation",
+  "assetName": "device-mcp-android-snapshot-helper-0.4.0.apk",
+  "sha256": "2cda32e70114c978ba9aafec74679d3ae9b137d7fd5f4312475858a380bf180e",
+  "signerSha256": "cefcaea256de",
+  "minSdk": 23
+}

package/dist/backends/adb-backend.cjs

@@ -10,25 +10,124 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _AdbBackend_instances, _AdbBackend_serial, _AdbBackend_recordingProcess, _AdbBackend_recordingPath, _AdbBackend_recordingRemotePath, _AdbBackend_adb, _AdbBackend_dumpUiHierarchy;
+var _AdbBackend_instances, _AdbBackend_serial, _AdbBackend_recordingProcess, _AdbBackend_recordingPath, _AdbBackend_recordingRemotePath, _AdbBackend_helperInstalled, _AdbBackend_captureQueue, _AdbBackend_adb, _AdbBackend_serializeCapture, _AdbBackend_dumpUiHierarchy, _AdbBackend_dumpViaInstrumentation, _AdbBackend_runInstrumentation, _AdbBackend_tryDumpViaUiautomator, _AdbBackend_dumpViaUiautomator, _AdbBackend_composeDumpFailure;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AdbBackend = void 0;
 exports.parseAndroidHierarchy = parseAndroidHierarchy;
 exports.parseNodeAttributes = parseNodeAttributes;
 const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
 const promises_1 = require("node:fs/promises");
+const errors_js_1 = require("./android-instrumentation/errors.cjs");
+const installer_js_1 = require("./android-instrumentation/installer.cjs");
+const snapshot_js_1 = require("./android-instrumentation/snapshot.cjs");
 const alert_labels_js_1 = require("../utils/alert-labels.cjs");
 const element_js_1 = require("../utils/element.cjs");
 const exec_js_1 = require("../utils/exec.cjs");
 const output_path_js_1 = require("../utils/output-path.cjs");
+// `uiautomator dump` exits 0 and prints its success banner even when it fails, so
+// the XML payload is the only trustworthy signal.
+const DUMP_ATTEMPTS = 3;
+const DUMP_RETRY_DELAY_MS = 750;
+// Healthy dumps take ~150ms-2s, and even a failing one returns in ~2s.
+const DUMP_TIMEOUT_MS = 15000;
+// Caps all attempts plus backoff, so worst case does not scale with retries.
+const DUMP_DEADLINE_MS = 25000;
+// Writable by the shell user without scoped-storage restrictions.
+const DUMP_REMOTE_DIR = '/data/local/tmp';
+// The instrumentation helper skips uiautomator's idle wait, so it must be
+// bounded by its own timeout rather than relying on "eventually idle".
+const INSTRUMENT_TIMEOUT_MS = 8000;
+// `am instrument` streams the whole hierarchy as base64 status records; a deep
+// tree can produce a few hundred KB, so raise the exec buffer above the default
+// 10MB guard to keep an overflow from masquerading as a helper crash.
+const INSTRUMENT_MAX_BUFFER = 16 * 1024 * 1024;
+// In `auto` mode, try a single fast uiautomator dump first (it wins instantly
+// on idle screens) before paying for the instrumentation path.
+const AUTO_PROBE_DUMP_ATTEMPTS = 1;
+/**
+ * Resolve the snapshot mode from the environment.
+ *
+ * @returns The configured mode, defaulting to `auto` for unset/unknown values.
+ */
+function resolveSnapshotMode() {
+    const raw = process.env.DEVICE_MCP_ADB_SNAPSHOT?.trim().toLowerCase();
+    if (raw === 'instrument' || raw === 'dump' || raw === 'auto') {
+        return raw;
+    }
+    return 'auto';
+}
+/**
+ * Check that a dump produced complete hierarchy XML.
+ *
+ * `<hierarchy` alone sits at the start of the file, so requiring the closing tag
+ * too is what rejects a truncated write before it reaches the tolerant regex
+ * parser. An empty screen still emits a complete root, keeping "no elements"
+ * distinguishable from a failed capture.
+ *
+ * @param xml - Raw stdout captured from the dumped file.
+ * @returns True when the payload is complete hierarchy XML.
+ */
+function isValidHierarchyXml(xml) {
+    return xml.includes('<hierarchy') && xml.includes('</hierarchy>');
+}
+/**
+ * Build a single-line diagnostic from a dump's output streams.
+ *
+ * @param stderr - Standard error captured from the dump.
+ * @param stdout - Standard output captured from the dump.
+ * @returns A description of why the dump was rejected.
+ */
+function summarizeDumpOutput(stderr, stdout) {
+    const detail = [stderr, stdout]
+        .map((stream) => stream.trim())
+        .filter(Boolean)
+        .join(' | ');
+    return detail
+        ? `uiautomator produced no usable hierarchy (${detail})`
+        : 'uiautomator produced no usable hierarchy';
+}
+/**
+ * Pick remediation advice that matches how the dump actually failed, so an
+ * unreachable device is not misreported as an animation problem.
+ *
+ * @param failures - The collected per-attempt failure details.
+ * @returns Actionable guidance for the caller.
+ */
+function describeDumpRemediation(failures) {
+    const detail = failures.toLowerCase();
+    if (detail.includes('not found') || detail.includes('device offline')) {
+        return ('The device was unreachable during the dump. Confirm it is still connected ' +
+            'with `adb devices` and that the serial is correct.');
+    }
+    return ('The most common cause is that uiautomator never observed an idle window ' +
+        '("ERROR: could not get idle state."), which means something on screen is ' +
+        'animating or redrawing continuously.\n' +
+        'Things to check:\n' +
+        '  - Disable animations: adb shell settings put global window_animation_scale 0 ' +
+        '(also transition_animation_scale and animator_duration_scale).\n' +
+        '  - Animation scales do NOT stop JS-driven React Native animations ' +
+        '(Animated.loop with useNativeDriver: false), indeterminate ProgressBars, ' +
+        'shimmer/skeleton loaders, or video/SurfaceView playback. Look for one of those ' +
+        'on the current screen and use device_screenshot to confirm what is on it.');
+}
 class AdbBackend {
     constructor(serial) {
         _AdbBackend_instances.add(this);
+        this.kind = 'adb';
         this.platform = 'android';
         _AdbBackend_serial.set(this, void 0);
         _AdbBackend_recordingProcess.set(this, null);
         _AdbBackend_recordingPath.set(this, null);
         _AdbBackend_recordingRemotePath.set(this, '/sdcard/device-mcp-recording.mp4');
+        // Optimistic per-process cache: once the helper is confirmed installed we
+        // skip the `pm list packages` probe on every snapshot. A mid-session
+        // uninstall/reboot is recovered reactively when `am instrument` reports the
+        // instrumentation is missing.
+        _AdbBackend_helperInstalled.set(this, false);
+        // Serializes snapshot captures so overlapping `am instrument` runs (e.g. a
+        // tap that triggers a nested snapshot) do not race on the single helper.
+        _AdbBackend_captureQueue.set(this, Promise.resolve());
         __classPrivateFieldSet(this, _AdbBackend_serial, serial, "f");
     }
     async ensureConnected() {
@@ -55,7 +154,7 @@ class AdbBackend {
         };
     }
     async snapshot() {
-        const raw = await __classPrivateFieldGet(this, _AdbBackend_instances, "m", _AdbBackend_dumpUiHierarchy).call(this);
+        const raw = await __classPrivateFieldGet(this, _AdbBackend_instances, "m", _AdbBackend_serializeCapture).call(this, async () => __classPrivateFieldGet(this, _AdbBackend_instances, "m", _AdbBackend_dumpUiHierarchy).call(this));
         const hierarchy = parseAndroidHierarchy(raw);
         return {
             platform: 'android',
@@ -162,15 +261,22 @@ class AdbBackend {
     }
     async screenshot(outputPath, options) {
         const localPath = (0, output_path_js_1.resolveArtifactPath)(outputPath, 'screenshot');
-        await __classPrivateFieldGet(this, _AdbBackend_instances, "m", _AdbBackend_adb).call(this, ['shell', 'screencap', '-p', '/sdcard/screenshot.png']);
-        await (0, exec_js_1.execStrict)('adb', [
-            '-s',
-            __classPrivateFieldGet(this, _AdbBackend_serial, "f"),
-            'pull',
-            '/sdcard/screenshot.png',
-            localPath,
-        ]);
-        await __classPrivateFieldGet(this, _AdbBackend_instances, "m", _AdbBackend_adb).call(this, ['shell', 'rm', '-f', '/sdcard/screenshot.png']);
+        // Unique per capture so a failed screencap can never be pulled as a stale
+        // image from an earlier call.
+        const remotePath = `${DUMP_REMOTE_DIR}/device-mcp-screenshot-${(0, node_crypto_1.randomUUID)()}.png`;
+        try {
+            await __classPrivateFieldGet(this, _AdbBackend_instances, "m", _AdbBackend_adb).call(this, ['shell', 'screencap', '-p', remotePath]);
+            await (0, exec_js_1.execStrict)('adb', [
+                '-s',
+                __classPrivateFieldGet(this, _AdbBackend_serial, "f"),
+                'pull',
+                remotePath,
+                localPath,
+            ]);
+        }
+        finally {
+            await __classPrivateFieldGet(this, _AdbBackend_instances, "m", _AdbBackend_adb).call(this, ['shell', 'rm', '-f', remotePath]).catch(() => undefined);
+        }
         (0, output_path_js_1.hardenArtifactFile)(localPath);
         if (options?.encode === false) {
             return { data: undefined, format: 'png', path: localPath };
@@ -361,14 +467,217 @@ class AdbBackend {
     }
 }
 exports.AdbBackend = AdbBackend;
-_AdbBackend_serial = new WeakMap(), _AdbBackend_recordingProcess = new WeakMap(), _AdbBackend_recordingPath = new WeakMap(), _AdbBackend_recordingRemotePath = new WeakMap(), _AdbBackend_instances = new WeakSet(), _AdbBackend_adb = async function _AdbBackend_adb(args) {
+_AdbBackend_serial = new WeakMap(), _AdbBackend_recordingProcess = new WeakMap(), _AdbBackend_recordingPath = new WeakMap(), _AdbBackend_recordingRemotePath = new WeakMap(), _AdbBackend_helperInstalled = new WeakMap(), _AdbBackend_captureQueue = new WeakMap(), _AdbBackend_instances = new WeakSet(), _AdbBackend_adb = async function _AdbBackend_adb(args) {
     return (0, exec_js_1.execStrict)('adb', ['-s', __classPrivateFieldGet(this, _AdbBackend_serial, "f"), ...args]);
+}, _AdbBackend_serializeCapture = 
+/**
+ * Run a capture after any in-flight capture completes, so concurrent
+ * snapshots never overlap an `am instrument` run on the shared helper.
+ *
+ * @param capture - The capture operation to serialize.
+ * @returns The capture result.
+ */
+async function _AdbBackend_serializeCapture(capture) {
+    const run = __classPrivateFieldGet(this, _AdbBackend_captureQueue, "f").then(capture, capture);
+    __classPrivateFieldSet(this, _AdbBackend_captureQueue, run.then(() => undefined, () => undefined), "f");
+    return run;
 }, _AdbBackend_dumpUiHierarchy = async function _AdbBackend_dumpUiHierarchy() {
-    const remotePath = '/sdcard/window_dump.xml';
-    await __classPrivateFieldGet(this, _AdbBackend_instances, "m", _AdbBackend_adb).call(this, ['shell', 'uiautomator', 'dump', remotePath]);
-    const xml = await __classPrivateFieldGet(this, _AdbBackend_instances, "m", _AdbBackend_adb).call(this, ['shell', 'cat', remotePath]);
-    await __classPrivateFieldGet(this, _AdbBackend_instances, "m", _AdbBackend_adb).call(this, ['shell', 'rm', '-f', remotePath]);
-    return xml;
+    const mode = resolveSnapshotMode();
+    const failures = [];
+    const deadline = Date.now() + DUMP_DEADLINE_MS;
+    if (mode === 'dump') {
+        const xml = await __classPrivateFieldGet(this, _AdbBackend_instances, "m", _AdbBackend_tryDumpViaUiautomator).call(this, deadline, DUMP_ATTEMPTS, failures);
+        if (xml !== null) {
+            return xml;
+        }
+        throw new Error(__classPrivateFieldGet(this, _AdbBackend_instances, "m", _AdbBackend_composeDumpFailure).call(this, failures));
+    }
+    if (mode === 'instrument') {
+        const xml = await __classPrivateFieldGet(this, _AdbBackend_instances, "m", _AdbBackend_dumpViaInstrumentation).call(this, deadline, failures);
+        if (xml !== null) {
+            return xml;
+        }
+        throw new Error(__classPrivateFieldGet(this, _AdbBackend_instances, "m", _AdbBackend_composeDumpFailure).call(this, failures));
+    }
+    // auto: a single fast dump wins instantly on idle screens; otherwise the
+    // instrumentation helper handles churn; the remaining dump retries are the
+    // last resort so a helper-side problem never leaves us worse than before.
+    const quick = await __classPrivateFieldGet(this, _AdbBackend_instances, "m", _AdbBackend_tryDumpViaUiautomator).call(this, deadline, AUTO_PROBE_DUMP_ATTEMPTS, failures);
+    if (quick !== null) {
+        return quick;
+    }
+    const instrumented = await __classPrivateFieldGet(this, _AdbBackend_instances, "m", _AdbBackend_dumpViaInstrumentation).call(this, deadline, failures);
+    if (instrumented !== null) {
+        return instrumented;
+    }
+    const fallback = await __classPrivateFieldGet(this, _AdbBackend_instances, "m", _AdbBackend_tryDumpViaUiautomator).call(this, deadline, DUMP_ATTEMPTS, failures);
+    if (fallback !== null) {
+        return fallback;
+    }
+    throw new Error(__classPrivateFieldGet(this, _AdbBackend_instances, "m", _AdbBackend_composeDumpFailure).call(this, failures));
+}, _AdbBackend_dumpViaInstrumentation = 
+/**
+ * Capture the hierarchy with the instrumentation helper, installing it first
+ * when needed.
+ *
+ * @param deadline - Absolute time (ms) the overall snapshot must finish by.
+ * @param failures - Accumulator for diagnostic messages across dump paths.
+ * @returns The hierarchy XML, or null when the helper path could not produce
+ * a valid capture (the caller then falls back to uiautomator dump).
+ */
+async function _AdbBackend_dumpViaInstrumentation(deadline, failures) {
+    try {
+        const xml = await __classPrivateFieldGet(this, _AdbBackend_instances, "m", _AdbBackend_runInstrumentation).call(this, deadline);
+        if (isValidHierarchyXml(xml)) {
+            return xml;
+        }
+        failures.push('instrument: output was not complete hierarchy XML');
+    }
+    catch (error) {
+        // A signer-trust failure means a possibly-malicious app squats the
+        // helper's package name. Fail closed: propagate, never fall back to dump.
+        if ((0, errors_js_1.isUntrustedHelperError)(error)) {
+            throw error;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        // A mid-session uninstall/reboot invalidates the optimistic cache. Retry
+        // once through the ensure-install path before giving up on this path.
+        if (__classPrivateFieldGet(this, _AdbBackend_helperInstalled, "f") &&
+            message.includes(installer_js_1.INSTRUMENTATION_NOT_FOUND_SIGNATURE)) {
+            __classPrivateFieldSet(this, _AdbBackend_helperInstalled, false, "f");
+            try {
+                const xml = await __classPrivateFieldGet(this, _AdbBackend_instances, "m", _AdbBackend_runInstrumentation).call(this, deadline);
+                if (isValidHierarchyXml(xml)) {
+                    return xml;
+                }
+                failures.push('instrument: output was not complete hierarchy XML after reinstall');
+            }
+            catch (retryError) {
+                if ((0, errors_js_1.isUntrustedHelperError)(retryError)) {
+                    throw retryError;
+                }
+                failures.push(`instrument: ${retryError instanceof Error ? retryError.message : String(retryError)}`);
+            }
+        }
+        else {
+            failures.push(`instrument: ${message}`);
+        }
+    }
+    return null;
+}, _AdbBackend_runInstrumentation = 
+/**
+ * Ensure the helper is installed, then run it and reassemble its output.
+ *
+ * @param deadline - Absolute time (ms) the overall snapshot must finish by.
+ * @returns The reassembled hierarchy XML.
+ */
+async function _AdbBackend_runInstrumentation(deadline) {
+    if (!__classPrivateFieldGet(this, _AdbBackend_helperInstalled, "f")) {
+        // Install/upgrade the helper by versionCode. Safe to cache per process:
+        // the install is idempotent and NOT a trust decision.
+        await (0, installer_js_1.ensureHelperInstalled)(__classPrivateFieldGet(this, _AdbBackend_serial, "f"));
+        __classPrivateFieldSet(this, _AdbBackend_helperInstalled, true, "f");
+    }
+    // Trust invariant: re-verify the installed signer BEFORE EVERY am instrument,
+    // never cached. Package name / versionCode are attacker-controlled, so an
+    // actor who can install packages could swap a previously-trusted helper for
+    // a malicious same-package instrumentation between snapshots. Caching this as
+    // a boolean would degrade the signature pin to a one-time check; verifying
+    // per use (pm path + pull + hash) keeps it a per-use invariant. Throws
+    // UntrustedHelperError on a signer mismatch (caller fails closed).
+    await (0, installer_js_1.assertInstalledHelperTrusted)(__classPrivateFieldGet(this, _AdbBackend_serial, "f"));
+    const remainingMs = deadline - Date.now();
+    const timeoutMs = Math.max(1000, Math.min(INSTRUMENT_TIMEOUT_MS, remainingMs));
+    const { stdout } = await (0, exec_js_1.exec)('adb', [
+        '-s',
+        __classPrivateFieldGet(this, _AdbBackend_serial, "f"),
+        'shell',
+        'am',
+        'instrument',
+        '-w',
+        '-e',
+        'waitForIdleTimeoutMs',
+        '0',
+        '-e',
+        'timeoutMs',
+        String(timeoutMs),
+        snapshot_js_1.HELPER_INSTRUMENTATION,
+    ], 
+    // Bound the exec above the helper's own timeout, and raise the buffer so
+    // a large tree is not misreported as a crash.
+    { timeoutMs: timeoutMs + 5000, maxBuffer: INSTRUMENT_MAX_BUFFER });
+    return (0, snapshot_js_1.reassembleInstrumentationXml)(stdout);
+}, _AdbBackend_tryDumpViaUiautomator = 
+/**
+ * Run the uiautomator dump retry loop, swallowing failure into null.
+ *
+ * @param deadline - Absolute time (ms) the overall snapshot must finish by.
+ * @param maxAttempts - How many dump attempts to make.
+ * @param failures - Accumulator for diagnostic messages across dump paths.
+ * @returns The hierarchy XML, or null when every attempt failed.
+ */
+async function _AdbBackend_tryDumpViaUiautomator(deadline, maxAttempts, failures) {
+    try {
+        return await __classPrivateFieldGet(this, _AdbBackend_instances, "m", _AdbBackend_dumpViaUiautomator).call(this, deadline, maxAttempts, failures);
+    }
+    catch {
+        // Failures are already recorded in the accumulator.
+        return null;
+    }
+}, _AdbBackend_dumpViaUiautomator = 
+/**
+ * The stock `uiautomator dump` capture with bounded retries.
+ *
+ * `uiautomator dump` exits 0 and prints its success banner even when it fails,
+ * so the XML payload is the only trustworthy signal.
+ *
+ * @param deadline - Absolute time (ms) the overall snapshot must finish by.
+ * @param maxAttempts - How many dump attempts to make.
+ * @param failures - Accumulator for diagnostic messages across dump paths.
+ * @returns The hierarchy XML.
+ * @throws If every attempt failed to produce complete hierarchy XML.
+ */
+async function _AdbBackend_dumpViaUiautomator(deadline, maxAttempts, failures) {
+    const startFailures = failures.length;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0) {
+            failures.push(`dump attempt ${attempt}: skipped, ${DUMP_DEADLINE_MS}ms budget exhausted`);
+            break;
+        }
+        // Unique per attempt: on a shared path a failed dump leaves the previous
+        // file behind, so `cat` silently returns an earlier screen's hierarchy.
+        const remotePath = `${DUMP_REMOTE_DIR}/device-mcp-dump-${(0, node_crypto_1.randomUUID)()}.xml`;
+        try {
+            const dump = await (0, exec_js_1.exec)('adb', ['-s', __classPrivateFieldGet(this, _AdbBackend_serial, "f"), 'shell', 'uiautomator', 'dump', remotePath], 
+            // Never outlive the overall deadline.
+            { timeoutMs: Math.min(DUMP_TIMEOUT_MS, remainingMs) });
+            const xml = await __classPrivateFieldGet(this, _AdbBackend_instances, "m", _AdbBackend_adb).call(this, ['shell', 'cat', remotePath]);
+            if (isValidHierarchyXml(xml)) {
+                return xml;
+            }
+            failures.push(`dump attempt ${attempt}: ${summarizeDumpOutput(dump.stderr, dump.stdout)}`);
+        }
+        catch (error) {
+            failures.push(`dump attempt ${attempt}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        finally {
+            // Never let cleanup mask the dump outcome.
+            await __classPrivateFieldGet(this, _AdbBackend_instances, "m", _AdbBackend_adb).call(this, ['shell', 'rm', '-f', remotePath]).catch(() => undefined);
+        }
+        const backoffMs = DUMP_RETRY_DELAY_MS * attempt;
+        if (attempt < maxAttempts && Date.now() + backoffMs < deadline) {
+            await new Promise((resolve) => {
+                setTimeout(resolve, backoffMs);
+            });
+        }
+    }
+    const attemptCount = failures.length - startFailures;
+    throw new Error(`uiautomator failed to capture the UI hierarchy after ${attemptCount} attempts.`);
+}, _AdbBackend_composeDumpFailure = function _AdbBackend_composeDumpFailure(failures) {
+    const detail = failures.join('\n');
+    const remediation = describeDumpRemediation(detail);
+    return `Failed to capture the UI hierarchy.\n${detail}\n${remediation}`;
 };
 function collectAndroidAlertTexts(elements) {
     const texts = [];