mobile-debug-mcp 0.31.0 → 0.32.1

package/README.md

@@ -1,4 +1,5 @@
 # Mobile Debug Tools
+[![npm version](https://img.shields.io/npm/v/mobile-debug-mcp.svg)](https://www.npmjs.com/package/mobile-debug-mcp)
 
 A minimal, secure MCP server for AI-assisted mobile development. Build, install, interact and inspect Android/iOS apps from an MCP-compatible client.
 

package/dist/interact/android.js

@@ -1,49 +1,54 @@
+import { markDispatchStarted } from '../utils/operation-budget.js';
 import { execAdb, getAndroidDeviceMetadata, getDeviceInfo } from "../utils/android/utils.js";
 import { AndroidObserve } from "../observe/index.js";
 import { scrollToElementShared } from "../utils/ui/index.js";
 export class AndroidInteract {
     observe = new AndroidObserve();
-    async tap(x, y, deviceId) {
+    async tap(x, y, deviceId, timeoutMs) {
         const metadata = await getAndroidDeviceMetadata("", deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
         try {
-            await execAdb(['shell', 'input', 'tap', x.toString(), y.toString()], deviceId);
+            markDispatchStarted();
+            await execAdb(['shell', 'input', 'tap', x.toString(), y.toString()], deviceId, { timeout: timeoutMs });
             return { device: deviceInfo, success: true, x, y };
         }
         catch (e) {
             return { device: deviceInfo, success: false, x, y, error: e instanceof Error ? e.message : String(e) };
         }
     }
-    async swipe(x1, y1, x2, y2, duration, deviceId) {
+    async swipe(x1, y1, x2, y2, duration, deviceId, timeoutMs) {
         const metadata = await getAndroidDeviceMetadata("", deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
         try {
-            await execAdb(['shell', 'input', 'swipe', x1.toString(), y1.toString(), x2.toString(), y2.toString(), duration.toString()], deviceId);
+            markDispatchStarted();
+            await execAdb(['shell', 'input', 'swipe', x1.toString(), y1.toString(), x2.toString(), y2.toString(), duration.toString()], deviceId, { timeout: timeoutMs });
             return { device: deviceInfo, success: true, start: [x1, y1], end: [x2, y2], duration };
         }
         catch (e) {
             return { device: deviceInfo, success: false, start: [x1, y1], end: [x2, y2], duration, error: e instanceof Error ? e.message : String(e) };
         }
     }
-    async typeText(text, deviceId) {
+    async typeText(text, deviceId, timeoutMs) {
         const metadata = await getAndroidDeviceMetadata("", deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
         try {
             // Encode spaces as %s to ensure proper input handling by adb shell input text
             const encodedText = text.replace(/\s/g, '%s');
             // Note: 'input text' might fail with some characters or if keyboard isn't ready, but it's the standard ADB way.
-            await execAdb(['shell', 'input', 'text', encodedText], deviceId);
+            markDispatchStarted();
+            await execAdb(['shell', 'input', 'text', encodedText], deviceId, { timeout: timeoutMs });
             return { device: deviceInfo, success: true, text };
         }
         catch (e) {
             return { device: deviceInfo, success: false, text, error: e instanceof Error ? e.message : String(e) };
         }
     }
-    async pressBack(deviceId) {
+    async pressBack(deviceId, timeoutMs) {
         const metadata = await getAndroidDeviceMetadata("", deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
         try {
-            await execAdb(['shell', 'input', 'keyevent', '4'], deviceId);
+            markDispatchStarted();
+            await execAdb(['shell', 'input', 'keyevent', '4'], deviceId, { timeout: timeoutMs });
             return { device: deviceInfo, success: true };
         }
         catch (e) {

package/dist/interact/index.js

@@ -1,3 +1,4 @@
+import { remainingBudget } from '../utils/operation-budget.js';
 import { createHash } from 'crypto';
 import { AndroidInteract } from './android.js';
 import { iOSInteract } from './ios.js';
@@ -950,19 +951,19 @@ export class ToolsInteract {
         const interact = effectivePlatform === 'android' ? new AndroidInteract() : new iOSInteract();
         return { interact: interact, resolved, platform: effectivePlatform };
     }
-    static async tapHandler({ platform, x, y, deviceId }) {
+    static async tapHandler({ platform, x, y, deviceId, timeoutMs }) {
         const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId);
-        return await interact.tap(x, y, resolved.id);
+        return await interact.tap(x, y, resolved.id, timeoutMs);
     }
-    static async tapElementHandler({ elementId }) {
+    static async tapElementHandler({ elementId, verificationMode = 'full', timeoutMs, platform, deviceId, freshTree }) {
         const actionType = 'tap_element';
         const selector = { elementId };
         const resolved = ToolsInteract._resolvedUiElements.get(elementId);
-        if (!resolved) {
+        if (!resolved || (platform && resolved.platform !== platform) || (deviceId && resolved.deviceId !== deviceId)) {
             return ToolsInteract._actionFailure(actionType, selector, null, 'STALE_REFERENCE', true, null);
         }
-        const fingerprintBefore = await ToolsInteract._captureFingerprint(resolved.platform, resolved.deviceId);
-        const tree = await ToolsObserve.getUITreeHandler({ platform: resolved.platform, deviceId: resolved.deviceId });
+        const fingerprintBefore = verificationMode === 'full' ? await ToolsInteract._captureFingerprint(resolved.platform, resolved.deviceId) : null;
+        const tree = freshTree ?? await ToolsObserve.getUITreeHandler({ platform: resolved.platform, deviceId: resolved.deviceId });
         const treePlatform = tree?.device?.platform === 'ios' ? 'ios' : resolved.platform;
         const treeDeviceId = tree?.device?.id || resolved.deviceId;
         const elements = Array.isArray(tree?.elements) ? tree.elements : [];
@@ -981,12 +982,12 @@ export class ToolsInteract {
         }
         const x = Math.floor((bounds[0] + bounds[2]) / 2);
         const y = Math.floor((bounds[1] + bounds[3]) / 2);
-        const tapResult = await ToolsInteract.tapHandler({ platform: resolved.platform, x, y, deviceId: resolved.deviceId });
+        const tapResult = await ToolsInteract.tapHandler({ platform: resolved.platform, x, y, deviceId: resolved.deviceId, timeoutMs });
         if (!tapResult.success) {
-            const fingerprintAfterFailure = await ToolsInteract._captureFingerprint(resolved.platform, resolved.deviceId);
-            return ToolsInteract._actionFailure(actionType, selector, resolvedTarget, 'UNKNOWN', false, fingerprintBefore, fingerprintAfterFailure);
+            const fingerprintAfterFailure = verificationMode === 'full' ? await ToolsInteract._captureFingerprint(resolved.platform, resolved.deviceId) : null;
+            return { ...ToolsInteract._actionFailure(actionType, selector, resolvedTarget, 'UNKNOWN', false, fingerprintBefore, fingerprintAfterFailure), error: tapResult.error };
         }
-        const fingerprintAfter = await ToolsInteract._captureFingerprint(resolved.platform, resolved.deviceId);
+        const fingerprintAfter = verificationMode === 'full' ? await ToolsInteract._captureFingerprint(resolved.platform, resolved.deviceId) : null;
         return buildActionExecutionResult({
             actionType,
             device: tree?.device,
@@ -1756,17 +1757,17 @@ export class ToolsInteract {
         const uiFingerprintAfter = await ToolsInteract._captureFingerprint(resolvedPlatform, resolvedDeviceId);
         return buildFailure('CONTROL_CONVERGENCE_FAILED', 'control did not converge within the allotted attempts', resolvedTarget, currentDevice, lastObservedState, attemptCount, lastAdjustmentMode, true, uiFingerprintAfter);
     }
-    static async swipeHandler({ platform = 'android', x1, y1, x2, y2, duration, deviceId }) {
+    static async swipeHandler({ platform = 'android', x1, y1, x2, y2, duration, deviceId, timeoutMs }) {
         const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId);
-        return await interact.swipe(x1, y1, x2, y2, duration, resolved.id);
+        return await interact.swipe(x1, y1, x2, y2, duration, resolved.id, timeoutMs);
     }
-    static async typeTextHandler({ text, deviceId }) {
+    static async typeTextHandler({ text, deviceId, timeoutMs }) {
         const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
-        return await new AndroidInteract().typeText(text, resolved.id);
+        return await new AndroidInteract().typeText(text, resolved.id, timeoutMs);
     }
-    static async pressBackHandler({ deviceId }) {
+    static async pressBackHandler({ deviceId, timeoutMs }) {
         const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
-        return await new AndroidInteract().pressBack(resolved.id);
+        return await new AndroidInteract().pressBack(resolved.id, timeoutMs);
     }
     static async scrollToElementHandler({ platform, selector, direction = 'down', maxScrolls = 10, scrollAmount = 0.7, deviceId }) {
         const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId);
@@ -2067,7 +2068,7 @@ export class ToolsInteract {
         };
         return { found: true, element: outEl, score: scoreVal, confidence: scoreVal, resolution };
     }
-    static async waitForUIHandler({ selector, condition = 'exists', timeout_ms = 60000, poll_interval_ms = 300, match, retry = { max_attempts: 1, backoff_ms: 0 }, platform, deviceId }) {
+    static async waitForUIHandler({ selector, condition = 'exists', timeout_ms = 60000, poll_interval_ms = 300, match, retry = { max_attempts: 1, backoff_ms: 0 }, platform, deviceId, singleObservation = false, singleAttempt = false, rejectAmbiguous = false }) {
         const overallStart = Date.now();
         const requestedIndex = typeof match?.index === 'number' ? match.index : null;
         const requested = {
@@ -2109,7 +2110,7 @@ export class ToolsInteract {
         let lastConditionSatisfied = false;
         let matchedAt = null;
         let stableMatchCount = 0;
-        const stableObservationCount = 2;
+        const stableObservationCount = singleObservation ? 1 : 2;
         const snapshotStaleThresholdMs = 500;
         // Precompute normalized selector values and helpers (constant across polls)
         const normalize = ToolsInteract._normalize;
@@ -2122,7 +2123,8 @@ export class ToolsInteract {
                 attempts++;
                 const attemptStart = Date.now();
                 const deadline = attemptStart + (timeout_ms || 0);
-                while (Date.now() <= deadline) {
+                while (Date.now() <= deadline || (singleAttempt && totalPollCount === 0)) {
+                    remainingBudget();
                     totalPollCount++;
                     try {
                         const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId });
@@ -2172,6 +2174,8 @@ export class ToolsInteract {
                         }
                         // Evaluate condition
                         const matchedCount = matches.length;
+                        if (rejectAmbiguous && matchedCount > 1 && match?.index === undefined)
+                            return { status: 'timeout', error: { code: 'AMBIGUOUS_TARGET' } };
                         const pickIndex = (typeof match?.index === 'number') ? match.index : undefined;
                         let chosen = null;
                         if (matches.length > 0) {
@@ -2237,6 +2241,7 @@ export class ToolsInteract {
                                 const outEl = lastMatchedElement;
                                 return {
                                     status: 'success',
+                                    ...(singleObservation ? { _tree: tree } : {}),
                                     matched: matchedCount,
                                     element: outEl,
                                     metrics: { latency_ms, poll_count: totalPollCount, attempts },
@@ -2256,9 +2261,13 @@ export class ToolsInteract {
                         }
                     }
                     catch (e) {
+                        if (e instanceof Error && e.message === 'ACTION_TIMEOUT')
+                            throw e;
                         // Non-fatal per-poll error; record and continue
                         console.warn('waitForUI: poll error (non-fatal):', e instanceof Error ? e.message : String(e));
                     }
+                    if (singleAttempt)
+                        break;
                     // Sleep until next poll
                     await new Promise(r => setTimeout(r, effectivePoll || 50));
                 }
@@ -2289,6 +2298,8 @@ export class ToolsInteract {
             }
         }
         catch (err) {
+            if (err instanceof Error && err.message === 'ACTION_TIMEOUT')
+                throw err;
             const elapsed = Date.now() - overallStart;
             return {
                 status: 'timeout',
@@ -2665,15 +2676,15 @@ export class ToolsInteract {
             })
         };
     }
-    static async expectStateHandler({ selector, element_id, property, expected, platform, deviceId, stabilization_window_ms = 1000, stable_observation_count = 2, snapshot_stale_threshold_ms = 500, poll_interval_ms = 150 }) {
+    static async expectStateHandler({ selector, element_id, property, expected, platform, deviceId, stabilization_window_ms = 1000, stable_observation_count = 2, snapshot_stale_threshold_ms = 500, poll_interval_ms = 150, exact_budget = false }) {
         const compareBoolean = (value) => typeof value === 'boolean' ? value : null;
         const compareString = (value) => typeof value === 'string' ? value : null;
         const compareNumber = (value) => typeof value === 'number' && Number.isFinite(value) ? value : null;
         const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
         const start = Date.now();
-        const deadline = start + Math.max(500, stabilization_window_ms);
+        const deadline = start + (exact_budget ? stabilization_window_ms : Math.max(500, stabilization_window_ms));
         const stableTarget = Math.max(1, Math.floor(stable_observation_count || 2));
-        const pollDelay = Math.max(100, Math.min(poll_interval_ms || 150, 200));
+        const pollDelay = exact_budget ? Math.max(50, Math.min(poll_interval_ms || 150, 1000)) : Math.max(100, Math.min(poll_interval_ms || 150, 200));
         const staleThreshold = Math.max(300, Math.min(snapshot_stale_threshold_ms || 500, 800));
         let attempts = 0;
         let stableCount = 0;

package/dist/interact/ios.js

@@ -1,3 +1,4 @@
+import { remainingBudget, markDispatchStarted } from '../utils/operation-budget.js';
 import { spawn } from "child_process";
 import { getIOSDeviceMetadata, getIdbCmd, isIDBInstalled } from "../utils/ios/utils.js";
 import { iOSObserve } from "../observe/index.js";
@@ -24,7 +25,8 @@ export class iOSInteract {
                 args.push('--udid', targetUdid);
             }
             await new Promise((resolve, reject) => {
-                const proc = spawn(getIdbCmd(), args);
+                markDispatchStarted();
+                const proc = spawn(getIdbCmd(), args, { timeout: remainingBudget() || undefined });
                 let stderr = '';
                 proc.stderr.on('data', d => stderr += d.toString());
                 proc.on('close', code => {
@@ -63,7 +65,8 @@ export class iOSInteract {
                 args.push('--udid', targetUdid);
             }
             await new Promise((resolve, reject) => {
-                const proc = spawn(getIdbCmd(), args);
+                markDispatchStarted();
+                const proc = spawn(getIdbCmd(), args, { timeout: remainingBudget() || undefined });
                 let stderr = '';
                 proc.stderr.on('data', d => stderr += d.toString());
                 proc.on('close', code => {

package/dist/manage/android.js

@@ -1,3 +1,4 @@
+import { hasFiniteBudget, markDispatchStarted, remainingBudget, runWithBudget } from '../utils/operation-budget.js';
 import { promises as fs } from 'fs';
 import { spawn } from 'child_process';
 import path from 'path';
@@ -145,16 +146,18 @@ export class AndroidManage {
             return { device: deviceInfo, installed: false, error: e instanceof Error ? e.message : String(e), diagnostics: { installDiag, pushDiag, pmDiag } };
         }
     }
-    async startApp(appId, deviceId) {
+    async startApp(appId, deviceId, timeoutMs) {
+        const started = performance.now();
         const metadata = await getAndroidDeviceMetadata(appId, deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
         try {
-            const output = await execAdb(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId);
+            markDispatchStarted();
+            const output = await execAdb(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId, { timeout: timeoutMs });
             const current = await new AndroidObserve().getCurrentScreen(deviceId).catch(() => null);
             return {
                 device: deviceInfo,
                 appStarted: true,
-                launchTimeMs: 1000,
+                launchTimeMs: performance.now() - started,
                 output,
                 observedApp: {
                     appId,
@@ -166,25 +169,31 @@ export class AndroidManage {
             };
         }
         catch (e) {
-            const diag = execAdbWithDiagnostics(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId);
-            return { device: deviceInfo, appStarted: false, launchTimeMs: 0, error: e instanceof Error ? e.message : String(e), diagnostics: diag };
+            const diagnostics = timeoutMs === undefined ? execAdbWithDiagnostics(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId) : undefined;
+            return { device: deviceInfo, appStarted: false, launchTimeMs: performance.now() - started, error: e instanceof Error ? e.message : String(e), ...(diagnostics ? { diagnostics } : {}) };
         }
     }
     async terminateApp(appId, deviceId) {
         const metadata = await getAndroidDeviceMetadata(appId, deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
         try {
+            markDispatchStarted();
             await execAdb(['shell', 'am', 'force-stop', appId], deviceId);
             return { device: deviceInfo, appTerminated: true };
         }
         catch (e) {
-            const diag = execAdbWithDiagnostics(['shell', 'am', 'force-stop', appId], deviceId);
-            return { device: deviceInfo, appTerminated: false, error: e instanceof Error ? e.message : String(e), diagnostics: diag };
+            const diagnostics = hasFiniteBudget() ? undefined : execAdbWithDiagnostics(['shell', 'am', 'force-stop', appId], deviceId);
+            return { device: deviceInfo, appTerminated: false, error: e instanceof Error ? e.message : String(e), ...(diagnostics ? { diagnostics } : {}) };
         }
     }
-    async restartApp(appId, deviceId) {
-        const terminateResult = await this.terminateApp(appId, deviceId);
-        const startResult = await this.startApp(appId, deviceId);
+    async restartApp(appId, deviceId, bounded = false, timeoutMs = 15000) {
+        const started = performance.now();
+        const terminateResult = bounded ? await runWithBudget(Math.min(5000, timeoutMs), () => this.terminateApp(appId, deviceId)) : await this.terminateApp(appId, deviceId);
+        const remaining = timeoutMs - (performance.now() - started);
+        if (bounded && remaining <= 0)
+            throw new Error('ACTION_TIMEOUT');
+        const launchBudget = remainingBudget(remaining);
+        const startResult = bounded ? await runWithBudget(launchBudget, () => this.startApp(appId, deviceId, remainingBudget(launchBudget))) : await this.startApp(appId, deviceId);
         return {
             device: startResult.device,
             appRestarted: startResult.appStarted,
@@ -201,6 +210,7 @@ export class AndroidManage {
         const metadata = await getAndroidDeviceMetadata(appId, deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
         try {
+            markDispatchStarted();
             const output = await execAdb(['shell', 'pm', 'clear', appId], deviceId);
             return { device: deviceInfo, dataCleared: output === 'Success' };
         }

package/dist/manage/ios.js

@@ -1,3 +1,4 @@
+import { hasFiniteBudget, markDispatchStarted, remainingBudget, runWithBudget } from '../utils/operation-budget.js';
 import { promises as fs } from "fs";
 import { spawn, spawnSync } from "child_process";
 import { execCommand, execCommandWithDiagnostics, getIOSDeviceMetadata, validateBundleId, getIdbCmd, findAppBundle } from "../utils/ios/utils.js";
@@ -287,17 +288,19 @@ export class iOSManage {
             return { device, installed: false, error: e instanceof Error ? e.message : String(e) };
         }
     }
-    async startApp(bundleId, deviceId = "booted") {
+    async startApp(bundleId, deviceId = "booted", observe = true) {
+        const started = performance.now();
         validateBundleId(bundleId);
         try {
+            markDispatchStarted();
             const result = await execCommand(['simctl', 'launch', deviceId, bundleId], deviceId);
             const device = await getIOSDeviceMetadata(deviceId);
-            const fingerprint = await new iOSObserve().getScreenFingerprint(deviceId).catch(() => null);
+            const fingerprint = observe ? await new iOSObserve().getScreenFingerprint(deviceId).catch(() => null) : null;
             const pidMatch = result.output.match(/:\s*(\d+)\s*$/);
             return {
                 device,
                 appStarted: !!result.output,
-                launchTimeMs: 1000,
+                launchTimeMs: performance.now() - started,
                 output: result.output,
                 observedApp: {
                     appId: bundleId,
@@ -308,27 +311,33 @@ export class iOSManage {
             };
         }
         catch (e) {
-            const diag = execCommandWithDiagnostics(['simctl', 'launch', deviceId, bundleId], deviceId);
             const device = await getIOSDeviceMetadata(deviceId);
-            return { device, appStarted: false, launchTimeMs: 0, error: e instanceof Error ? e.message : String(e), diagnostics: diag };
+            const diagnostics = hasFiniteBudget() ? undefined : execCommandWithDiagnostics(['simctl', 'launch', deviceId, bundleId], deviceId);
+            return { device, appStarted: false, launchTimeMs: performance.now() - started, error: e instanceof Error ? e.message : String(e), ...(diagnostics ? { diagnostics } : {}) };
         }
     }
     async terminateApp(bundleId, deviceId = "booted") {
         validateBundleId(bundleId);
         try {
+            markDispatchStarted();
             await execCommand(['simctl', 'terminate', deviceId, bundleId], deviceId);
             const device = await getIOSDeviceMetadata(deviceId);
             return { device, appTerminated: true };
         }
         catch (e) {
-            const diag = execCommandWithDiagnostics(['simctl', 'terminate', deviceId, bundleId], deviceId);
+            const diag = hasFiniteBudget() ? undefined : execCommandWithDiagnostics(['simctl', 'terminate', deviceId, bundleId], deviceId);
             const device = await getIOSDeviceMetadata(deviceId);
-            return { device, appTerminated: false, error: e instanceof Error ? e.message : String(e), diagnostics: diag };
+            return { device, appTerminated: false, error: e instanceof Error ? e.message : String(e), ...(diag ? { diagnostics: diag } : {}) };
         }
     }
-    async restartApp(bundleId, deviceId = "booted") {
-        const terminateResult = await this.terminateApp(bundleId, deviceId);
-        const startResult = await this.startApp(bundleId, deviceId);
+    async restartApp(bundleId, deviceId = "booted", observe = true, bounded = false, timeoutMs = 15000) {
+        const started = performance.now();
+        const terminateResult = bounded ? await runWithBudget(Math.min(5000, timeoutMs), () => this.terminateApp(bundleId, deviceId)) : await this.terminateApp(bundleId, deviceId);
+        const remaining = timeoutMs - (performance.now() - started);
+        if (bounded && remaining <= 0)
+            throw new Error('ACTION_TIMEOUT');
+        const launchBudget = remainingBudget(remaining);
+        const startResult = bounded ? await runWithBudget(launchBudget, () => this.startApp(bundleId, deviceId, observe)) : await this.startApp(bundleId, deviceId, observe);
         return {
             device: startResult.device,
             appRestarted: startResult.appStarted,

package/dist/observe/android-tree-bridge.js

@@ -0,0 +1,192 @@
+import { execFile, spawn, spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { connect } from 'node:net';
+import path from 'node:path';
+import { execAdb, getAdbCmd } from '../utils/android/utils.js';
+import { remainingBudget } from '../utils/operation-budget.js';
+const packageName = 'dev.mobiledebugmcp.treebridge';
+const component = `${packageName}/.TreeInstrumentation`;
+const devicePort = 39019;
+const active = new Map();
+const starting = new Map();
+const stopping = new Map();
+export function androidTreeBridgeEnabled() {
+    return Boolean(process.env.MOBILE_DEBUG_MCP_ANDROID_TREE_BRIDGE_APK);
+}
+function configuredApk() {
+    const configured = process.env.MOBILE_DEBUG_MCP_ANDROID_TREE_BRIDGE_APK;
+    if (!configured)
+        return null;
+    const apk = path.resolve(configured);
+    if (!existsSync(apk))
+        throw new Error(`Android UI tree bridge APK does not exist: ${apk}`);
+    return apk;
+}
+function unbudgetedAdb(deviceId, args) {
+    return new Promise((resolve, reject) => {
+        execFile(getAdbCmd(), ['-s', deviceId, ...args], { timeout: 5000 }, (error) => error ? reject(error) : resolve());
+    });
+}
+function request(bridge, command, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        let output = '';
+        const socket = connect(bridge.hostPort, '127.0.0.1', () => socket.write(`${command}\n`));
+        socket.setTimeout(timeoutMs, () => socket.destroy(new Error(`Android UI tree bridge ${command} timed out`)));
+        socket.on('data', (chunk) => {
+            output += chunk.toString();
+            if (command === 'STOP' && output.startsWith('OK\n')) {
+                resolve(output);
+                socket.destroy();
+            }
+        });
+        socket.on('error', reject);
+        socket.on('end', () => resolve(output));
+    });
+}
+function waitForChildClose(bridge, timeoutMs) {
+    if (bridge.childClosed)
+        return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        const onClose = () => { clearTimeout(timer); resolve(); };
+        const timer = setTimeout(() => {
+            bridge.child.off('close', onClose);
+            reject(new Error('Android UI tree bridge child did not exit'));
+        }, timeoutMs);
+        bridge.child.once('close', onClose);
+    });
+}
+async function stop(bridge) {
+    const pending = stopping.get(bridge.deviceId);
+    if (pending)
+        return pending;
+    bridge.closed = true;
+    const cleanup = (async () => {
+        await request(bridge, 'STOP', 1000).catch(() => '');
+        let forceStopError;
+        try {
+            await unbudgetedAdb(bridge.deviceId, ['shell', 'am', 'force-stop', packageName]);
+        }
+        catch (error) {
+            forceStopError = error;
+        }
+        try {
+            await waitForChildClose(bridge, 1000);
+        }
+        catch {
+            bridge.child.kill('SIGTERM');
+            try {
+                await waitForChildClose(bridge, 1000);
+            }
+            catch {
+                bridge.child.kill('SIGKILL');
+                await waitForChildClose(bridge, 2000).catch(() => { });
+            }
+        }
+        let forwardError;
+        try {
+            await unbudgetedAdb(bridge.deviceId, ['forward', '--remove', `tcp:${bridge.hostPort}`]);
+        }
+        catch (error) {
+            forwardError = error;
+        }
+        if (forceStopError || !bridge.childClosed || forwardError) {
+            const reason = forceStopError ?? (!bridge.childClosed ? 'instrumentation child did not close' : forwardError);
+            throw new Error(`BRIDGE_CLEANUP_UNCONFIRMED: ${reason instanceof Error ? reason.message : String(reason)}`);
+        }
+        if (active.get(bridge.deviceId) === bridge)
+            active.delete(bridge.deviceId);
+    })();
+    stopping.set(bridge.deviceId, cleanup);
+    try {
+        await cleanup;
+    }
+    finally {
+        stopping.delete(bridge.deviceId);
+    }
+}
+async function launch(deviceId, apk) {
+    await unbudgetedAdb(deviceId, ['shell', 'am', 'force-stop', packageName]);
+    try {
+        await execAdb(['install', '-r', apk], deviceId);
+    }
+    catch (error) {
+        if (!(error instanceof Error) || !error.message.includes('INSTALL_FAILED_UPDATE_INCOMPATIBLE'))
+            throw error;
+        await execAdb(['uninstall', packageName], deviceId);
+        await execAdb(['install', '-r', apk], deviceId);
+    }
+    const hostPort = Number(await execAdb(['forward', 'tcp:0', `tcp:${devicePort}`], deviceId));
+    if (!Number.isInteger(hostPort) || hostPort <= 0)
+        throw new Error('Android UI tree bridge could not obtain a host port');
+    const child = spawn(getAdbCmd(), ['-s', deviceId, 'shell', 'am', 'instrument', '-w', component], { stdio: 'ignore' });
+    const bridge = { deviceId, hostPort, child, closed: false, childClosed: false };
+    child.once('close', () => { bridge.childClosed = true; });
+    child.once('error', () => { });
+    active.set(deviceId, bridge);
+    try {
+        const deadline = Date.now() + Math.min(remainingBudget(3000), 3000);
+        while (Date.now() < deadline) {
+            if (bridge.childClosed || child.exitCode !== null || child.signalCode !== null)
+                throw new Error('Android UI tree bridge exited during startup');
+            try {
+                if ((await request(bridge, 'PING', 250)).startsWith('OK\n')) {
+                    return bridge;
+                }
+            }
+            catch { /* The instrumentation process may still be starting. */ }
+            await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+        throw new Error('Android UI tree bridge did not become ready');
+    }
+    catch (error) {
+        await stop(bridge);
+        throw error;
+    }
+}
+async function ensure(deviceId, apk) {
+    const pending = starting.get(deviceId);
+    if (pending)
+        return pending;
+    const ready = active.get(deviceId);
+    if (ready && !ready.closed && !ready.childClosed && ready.child.exitCode === null && ready.child.signalCode === null)
+        return ready;
+    if (ready)
+        await stop(ready);
+    const promise = launch(deviceId, apk);
+    starting.set(deviceId, promise);
+    try {
+        return await promise;
+    }
+    finally {
+        starting.delete(deviceId);
+    }
+}
+/** Returns null only after the bridge has been stopped, so legacy acquisition is safe. */
+export async function readAndroidTreeFromBridge(deviceId) {
+    const apk = configuredApk();
+    if (!apk)
+        return null;
+    let bridge;
+    try {
+        bridge = await ensure(deviceId, apk);
+        const output = await request(bridge, 'TREE', remainingBudget(10000));
+        if (!output.startsWith('OK\n') || !output.includes('<hierarchy'))
+            throw new Error('Android UI tree bridge returned invalid hierarchy output');
+        return output.slice(3);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith('BRIDGE_CLEANUP_UNCONFIRMED'))
+            throw error;
+        if (bridge)
+            await stop(bridge);
+        if (error instanceof Error && error.message === 'ACTION_TIMEOUT')
+            throw error;
+        return null;
+    }
+}
+process.once('exit', () => {
+    for (const bridge of active.values()) {
+        spawnSync(getAdbCmd(), ['-s', bridge.deviceId, 'shell', 'am', 'force-stop', packageName], { timeout: 2000, stdio: 'ignore' });
+        spawnSync(getAdbCmd(), ['-s', bridge.deviceId, 'forward', '--remove', `tcp:${bridge.hostPort}`], { timeout: 2000, stdio: 'ignore' });
+    }
+});