mobile-debug-mcp 0.31.0 → 0.32.1

package/src/interact/android.ts

@@ -1,3 +1,4 @@
+import { markDispatchStarted } from '../utils/operation-budget.js'
 import { TapResponse, SwipeResponse, TypeTextResponse, PressBackResponse } from "../types.js"
 import { execAdb, getAndroidDeviceMetadata, getDeviceInfo } from "../utils/android/utils.js"
 import { AndroidObserve } from "../observe/index.js"
@@ -7,31 +8,33 @@ import { scrollToElementShared } from "../utils/ui/index.js"
 export class AndroidInteract {
   private observe = new AndroidObserve();
 
-  async tap(x: number, y: number, deviceId?: string): Promise<TapResponse> {
+  async tap(x: number, y: number, deviceId?: string, timeoutMs?: number): Promise<TapResponse> {
     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: number, y1: number, x2: number, y2: number, duration: number, deviceId?: string): Promise<SwipeResponse> {
+  async swipe(x1: number, y1: number, x2: number, y2: number, duration: number, deviceId?: string, timeoutMs?: number): Promise<SwipeResponse> {
     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: string, deviceId?: string): Promise<TypeTextResponse> {
+  async typeText(text: string, deviceId?: string, timeoutMs?: number): Promise<TypeTextResponse> {
     const metadata = await getAndroidDeviceMetadata("", deviceId)
     const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
 
@@ -39,19 +42,21 @@ export class AndroidInteract {
       // 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?: string): Promise<PressBackResponse> {
+  async pressBack(deviceId?: string, timeoutMs?: number): Promise<PressBackResponse> {
     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) {
       return { device: deviceInfo, success: false, error: e instanceof Error ? e.message : String(e) }

package/src/interact/index.ts

@@ -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';
@@ -1226,22 +1227,22 @@ export class ToolsInteract {
     return { interact: interact as any, resolved, platform: effectivePlatform }
   }
 
-  static async tapHandler({ platform, x, y, deviceId }: { platform?: 'android' | 'ios', x: number, y: number, deviceId?: string }) {
+  static async tapHandler({ platform, x, y, deviceId, timeoutMs }: { platform?: 'android' | 'ios', x: number, y: number, deviceId?: string, timeoutMs?: number }) {
     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 }: { elementId: string }): Promise<TapElementResponse> {
+  static async tapElementHandler({ elementId, verificationMode = 'full', timeoutMs, platform, deviceId, freshTree }: { elementId: string, verificationMode?: 'none' | 'light' | 'full', timeoutMs?: number, platform?: 'android' | 'ios', deviceId?: string, freshTree?: any }): Promise<TapElementResponse> {
     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 fingerprintBefore = verificationMode === 'full' ? await ToolsInteract._captureFingerprint(resolved.platform, resolved.deviceId) : null
 
-    const tree = await ToolsObserve.getUITreeHandler({ platform: resolved.platform, deviceId: resolved.deviceId }) as any
+    const tree = freshTree ?? await ToolsObserve.getUITreeHandler({ platform: resolved.platform, deviceId: resolved.deviceId }) as any
     const treePlatform = tree?.device?.platform === 'ios' ? 'ios' : resolved.platform
     const treeDeviceId = tree?.device?.id || resolved.deviceId
     const elements = Array.isArray(tree?.elements) ? tree.elements as UiElement[] : []
@@ -1272,14 +1273,14 @@ 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,
@@ -2204,19 +2205,19 @@ export class ToolsInteract {
     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 }: { platform?: 'android' | 'ios', x1: number, y1: number, x2: number, y2: number, duration: number, deviceId?: string }) {
+  static async swipeHandler({ platform = 'android', x1, y1, x2, y2, duration, deviceId, timeoutMs }: { platform?: 'android' | 'ios', x1: number, y1: number, x2: number, y2: number, duration: number, deviceId?: string, timeoutMs?: number }) {
     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 }: { text: string, deviceId?: string }) {
+  static async typeTextHandler({ text, deviceId, timeoutMs }: { text: string, deviceId?: string, timeoutMs?: number }) {
     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 }: { deviceId?: string }) {
+  static async pressBackHandler({ deviceId, timeoutMs }: { deviceId?: string, timeoutMs?: number }) {
     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 }: { platform: 'android' | 'ios', selector: { text?: string, resourceId?: string, contentDesc?: string, className?: string }, direction?: 'down' | 'up', maxScrolls?: number, scrollAmount?: number, deviceId?: string }) {
@@ -2490,7 +2491,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 }: { selector?: { text?: string, resource_id?: string, accessibility_id?: string, contains?: boolean }, condition?: 'exists'|'not_exists'|'visible'|'clickable', timeout_ms?: number, poll_interval_ms?: number, match?: { index?: number }, retry?: { max_attempts?: number, backoff_ms?: number }, platform?: 'android'|'ios', deviceId?: string }) {
+  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 }: { selector?: { text?: string, resource_id?: string, accessibility_id?: string, contains?: boolean }, condition?: 'exists'|'not_exists'|'visible'|'clickable', timeout_ms?: number, poll_interval_ms?: number, match?: { index?: number }, retry?: { max_attempts?: number, backoff_ms?: number }, platform?: 'android'|'ios', deviceId?: string, singleObservation?: boolean, singleAttempt?: boolean, rejectAmbiguous?: boolean }) {
     const overallStart = Date.now()
     const requestedIndex = typeof match?.index === 'number' ? match.index : null
     const requested = {
@@ -2538,7 +2539,7 @@ export class ToolsInteract {
     let lastConditionSatisfied = false
     let matchedAt: number | null = null
     let stableMatchCount = 0
-    const stableObservationCount = 2
+    const stableObservationCount = singleObservation ? 1 : 2
     const snapshotStaleThresholdMs = 500
 
     // Precompute normalized selector values and helpers (constant across polls)
@@ -2554,7 +2555,8 @@ export class ToolsInteract {
         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 }) as any
@@ -2601,6 +2603,7 @@ 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 as number : undefined
             let chosen: { el: any, idx: number } | null = null
             if (matches.length > 0) {
@@ -2659,6 +2662,7 @@ export class ToolsInteract {
 
                 return {
                   status: 'success',
+                  ...(singleObservation ? { _tree: tree } : {}),
                   matched: matchedCount,
                   element: outEl,
                   metrics: { latency_ms, poll_count: totalPollCount, attempts },
@@ -2677,10 +2681,12 @@ 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))
         }
@@ -2712,6 +2718,7 @@ export class ToolsInteract {
       }
 
     } catch (err) {
+      if (err instanceof Error && err.message === 'ACTION_TIMEOUT') throw err
       const elapsed = Date.now() - overallStart
       return {
         status: 'timeout',
@@ -3139,7 +3146,8 @@ export class ToolsInteract {
     stabilization_window_ms = 1000,
     stable_observation_count = 2,
     snapshot_stale_threshold_ms = 500,
-    poll_interval_ms = 150
+    poll_interval_ms = 150,
+    exact_budget = false
   }: {
     selector?: { text?: string, resource_id?: string, accessibility_id?: string, contains?: boolean },
     element_id?: string,
@@ -3150,16 +3158,17 @@ export class ToolsInteract {
     stabilization_window_ms?: number,
     stable_observation_count?: number,
     snapshot_stale_threshold_ms?: number,
-    poll_interval_ms?: number
+    poll_interval_ms?: number,
+    exact_budget?: boolean
   }): Promise<ExpectStateResponse> {
     const compareBoolean = (value: unknown) => typeof value === 'boolean' ? value : null
     const compareString = (value: unknown) => typeof value === 'string' ? value : null
     const compareNumber = (value: unknown) => typeof value === 'number' && Number.isFinite(value) ? value : null
     const sleep = (ms: number) => 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

package/src/interact/ios.ts

@@ -1,3 +1,4 @@
+import { remainingBudget, markDispatchStarted } from '../utils/operation-budget.js'
 import { spawn } from "child_process"
 import { TapResponse, SwipeResponse } from "../types.js"
 import { getIOSDeviceMetadata, getIdbCmd, isIDBInstalled } from "../utils/ios/utils.js"
@@ -31,7 +32,8 @@ export class iOSInteract {
       }
 
       await new Promise<void>((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 => {
@@ -72,7 +74,8 @@ export class iOSInteract {
       }
 
       await new Promise<void>((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/src/manage/android.ts

@@ -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'
@@ -149,16 +150,18 @@ export class AndroidManage {
     }
   }
 
-  async startApp(appId: string, deviceId?: string): Promise<StartAppResponse> {
+  async startApp(appId: string, deviceId?: string, timeoutMs?: number): Promise<StartAppResponse> {
+    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,
@@ -169,8 +172,8 @@ export class AndroidManage {
         }
       }
     } catch (e: unknown) {
-      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 } : {}) }
     }
   }
 
@@ -178,17 +181,22 @@ export class AndroidManage {
     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: unknown) {
-      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: string, deviceId?: string): Promise<RestartAppResponse> {
-    const terminateResult = await this.terminateApp(appId, deviceId)
-    const startResult = await this.startApp(appId, deviceId)
+  async restartApp(appId: string, deviceId?: string, bounded = false, timeoutMs = 15000): Promise<RestartAppResponse> {
+    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,
@@ -206,6 +214,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' }
     } catch (e: unknown) {

package/src/manage/ios.ts

@@ -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 { StartAppResponse, TerminateAppResponse, RestartAppResponse, ResetAppDataResponse, InstallAppResponse } from "../types.js"
@@ -310,17 +311,19 @@ export class iOSManage {
     }
   }
 
-  async startApp(bundleId: string, deviceId: string = "booted"): Promise<StartAppResponse> {
+  async startApp(bundleId: string, deviceId: string = "booted", observe = true): Promise<StartAppResponse> {
+    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,
@@ -330,28 +333,33 @@ export class iOSManage {
         }
       }
     } catch (e: unknown) {
-      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 } as any
+      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 } : {}) } as any
     }
   }
 
   async terminateApp(bundleId: string, deviceId: string = "booted"): Promise<TerminateAppResponse> {
     validateBundleId(bundleId)
     try {
+      markDispatchStarted()
       await execCommand(['simctl', 'terminate', deviceId, bundleId], deviceId)
       const device = await getIOSDeviceMetadata(deviceId)
       return { device, appTerminated: true }
     } catch (e: unknown) {
-      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 } as any
+      return { device, appTerminated: false, error: e instanceof Error ? e.message : String(e), ...(diag ? { diagnostics: diag } : {}) } as any
     }
   }
 
-  async restartApp(bundleId: string, deviceId: string = "booted"): Promise<RestartAppResponse> {
-    const terminateResult = await this.terminateApp(bundleId, deviceId)
-    const startResult = await this.startApp(bundleId, deviceId)
+  async restartApp(bundleId: string, deviceId: string = "booted", observe = true, bounded = false, timeoutMs = 15000): Promise<RestartAppResponse> {
+    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/src/observe/android-tree-bridge.ts

@@ -0,0 +1,170 @@
+import { execFile, spawn, spawnSync, type ChildProcess } 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
+
+interface Bridge {
+  deviceId: string
+  hostPort: number
+  child: ChildProcess
+  closed: boolean
+  childClosed: boolean
+}
+
+const active = new Map<string, Bridge>()
+const starting = new Map<string, Promise<Bridge>>()
+const stopping = new Map<string, Promise<void>>()
+
+export function androidTreeBridgeEnabled(): boolean {
+  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: string, args: string[]): Promise<void> {
+  return new Promise((resolve, reject) => {
+    execFile(getAdbCmd(), ['-s', deviceId, ...args], { timeout: 5000 }, (error) => error ? reject(error) : resolve())
+  })
+}
+
+function request(bridge: Bridge, command: 'PING' | 'TREE' | 'STOP', timeoutMs: number): Promise<string> {
+  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: Bridge, timeoutMs: number): Promise<void> {
+  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: Bridge): Promise<void> {
+  const pending = stopping.get(bridge.deviceId)
+  if (pending) return pending
+  bridge.closed = true
+  const cleanup = (async () => {
+    await request(bridge, 'STOP', 1000).catch(() => '')
+    let forceStopError: unknown
+    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: unknown
+    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: string, apk: string): Promise<Bridge> {
+  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: Bridge = { deviceId, hostPort, child, closed: false, childClosed: false }
+  child.once('close', () => { bridge.childClosed = true })
+  child.once('error', () => { /* Startup detects the failed child before a tree read. */ })
+  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: string, apk: string): Promise<Bridge> {
+  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: string): Promise<string | null> {
+  const apk = configuredApk()
+  if (!apk) return null
+  let bridge: Bridge | undefined
+  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' })
+  }
+})