mobile-debug-mcp 0.30.2 → 0.32.0

package/src/types.ts

@@ -162,6 +162,16 @@ export interface SnapshotDelta {
   total_elements: number;
 }
 
+export interface StateDelta {
+  base_snapshot_revision: number | null;
+  snapshot_revision: number;
+  added: UIElement[];
+  removed: Array<{ stable_id?: string; resourceId?: string; contentDescription?: string; text?: string; index: number }>;
+  changed: UIElement[];
+  truncated: boolean;
+  omitted_changes?: number;
+}
+
 export interface CaptureAndroidScreenResponse {
   device: DeviceInfo;
   screenshot: string; // base64 encoded string
@@ -282,6 +292,8 @@ export type ActionFailureCode =
   | 'ELEMENT_NOT_FOUND'
   | 'ELEMENT_NOT_INTERACTABLE'
   | 'TIMEOUT'
+  | 'ACTION_TIMEOUT'
+  | 'ASSERTION_TIMEOUT'
   | 'NAVIGATION_NO_CHANGE'
   | 'AMBIGUOUS_TARGET'
   | 'STALE_REFERENCE'
@@ -393,11 +405,23 @@ export interface FindElementResponse {
   error?: string;
 }
 
+export interface TimingBreakdown {
+  total_ms: number;
+  device_resolution_ms?: number;
+  pre_observation_ms?: number;
+  target_resolution_ms?: number;
+  dispatch_ms?: number;
+  post_observation_ms?: number;
+  verification_ms?: number;
+  screenshot_ms?: number;
+  serialization_ms?: number;
+}
+
 export interface ActionExecutionResult {
   action_id: string;
   timestamp: string;
   action_type: string;
-  lifecycle_state?: 'pending_verification' | 'failed';
+  lifecycle_state?: 'pending_verification' | 'verified' | 'failed';
   source_module?: 'server' | 'interact';
   device?: DeviceInfo;
   target: {
@@ -407,6 +431,11 @@ export interface ActionExecutionResult {
   success: boolean;
   failure_code?: ActionFailureCode;
   retryable?: boolean;
+  delivery_status?: 'delivered' | 'not_delivered' | 'unknown';
+  dispatch_started?: boolean;
+  verification?: { mode: 'none' | 'light' | 'full'; status: 'not_requested' | 'observed' | 'verified' | 'unavailable' | 'failed' };
+  state_delta?: StateDelta;
+  timing?: TimingBreakdown;
   recovery?: RecoveryState;
   trace: ActionTrace;
   ui_fingerprint_before?: string | null;
@@ -414,7 +443,7 @@ export interface ActionExecutionResult {
   details?: Record<string, unknown>;
 }
 
-export interface TapElementResponse extends ActionExecutionResult {}
+export interface TapElementResponse extends ActionExecutionResult { error?: string }
 
 export interface ExpectScreenResponse {
   success: boolean;

package/src/utils/android/utils.ts

@@ -20,8 +20,10 @@ function findInPath(cmd: string): string | null {
 }
 
 export function resolveAdbCmd(): string {
-  // Priority: explicit env ADB_PATH -> ANDROID_SDK_ROOT/platform-tools/adb -> ANDROID_HOME/platform-tools/adb -> ~/Library/Android/sdk/platform-tools/adb -> PATH discovery -> 'adb'
+  // Priority: explicit env ADB_PATH -> PATH -> known SDK locations -> fallback to 'adb'
   if (process.env.ADB_PATH && process.env.ADB_PATH.trim()) return process.env.ADB_PATH
+  const found = findInPath('adb')
+  if (found) return found
   const sdkRoot = process.env.ANDROID_SDK_ROOT || process.env.ANDROID_HOME
   if (sdkRoot) {
     const candidate = path.join(sdkRoot, 'platform-tools', process.platform === 'win32' ? 'adb.exe' : 'adb')
@@ -30,8 +32,6 @@ export function resolveAdbCmd(): string {
   // common macOS user SDK path
   const homeSdk = path.join(process.env.HOME || '', 'Library', 'Android', 'sdk', 'platform-tools', process.platform === 'win32' ? 'adb.exe' : 'adb')
   if (existsSync(homeSdk)) return homeSdk
-  const found = findInPath('adb')
-  if (found) return found
   return 'adb'
 }
 

package/src/utils/cli/idb/check-idb.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { execSync, spawnSync } from 'child_process'
 import { main as installMain } from './install-idb.js'
-import { getIdbCmd, isIDBInstalled } from './idb-helper.js'
+import { getIdbCmd, getIdbPackageVersion, isIDBInstalled } from './idb-helper.js'
 
 function which(cmd: string): string | null {
   try {
@@ -48,7 +48,16 @@ try {
   const idb = process.env.IDB_PATH || getIdbCmd()
   print('idb:', idb)
   if (idb && isIDBInstalled()) {
-    try { print('idb --version:', execSync(`${idb} --version`, { stdio: ['ignore','pipe','ignore'] }).toString().trim()) } catch (e) { print('idb --version: (failed)', e instanceof Error ? e.message : String(e)) }
+    const version = getIdbPackageVersion()
+    if (version) print('fb-idb version:', version)
+    try {
+      const output = execSync(`${idb} list-targets --json`, { stdio: ['ignore', 'pipe', 'pipe'], timeout: 5000 }).toString().trim()
+      print('idb list-targets --json: ok')
+      if (output) print(output)
+    } catch (e) {
+      print('idb list-targets --json: (failed)', e instanceof Error ? e.message : String(e))
+      process.exit(2)
+    }
     const companion = which('idb_companion')
     print('which idb_companion:', companion)
     if (companion) try { print('idb_companion --version:', execSync('idb_companion --version', { stdio: ['ignore','pipe','ignore'] }).toString().trim()) } catch (e) { print('idb_companion --version: (failed)', e instanceof Error ? e.message : String(e)) }

package/src/utils/cli/idb/idb-helper.ts

@@ -59,17 +59,54 @@ export function getIdbCmd(): string | null {
   return null
 }
 
-export function isIDBInstalled(): boolean {
-  const cmd = getIdbCmd()
-  if (!cmd) return false
-  try {
-    // command -v <cmd>
-    const r = spawnSync('command', ['-v', cmd], { stdio: ['ignore', 'pipe', 'ignore'] })
-    if (r && r.status === 0) return true
-  } catch {}
+export function getIdbPackageVersion(): string | null {
+  const runners = ['python3', 'python']
+  for (const runner of runners) {
+    try {
+      const result = spawnSync(runner, ['-m', 'pip', 'show', 'fb-idb'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe']
+      })
+      if (result.status !== 0) continue
+      const output = `${result.stdout || ''}\n${result.stderr || ''}`
+      const match = output.match(/^Version:\s*(.+)$/mi)
+      if (match?.[1]) return match[1].trim()
+    } catch {
+      continue
+    }
+  }
+  return null
+}
+
+export function probeIdb(cmd = getIdbCmd()): { ok: boolean; raw: string | null; parsedVersion: string | null } {
+  if (!cmd) return { ok: false, raw: null, parsedVersion: null }
+
   try {
-    execSync(`${cmd} list-targets --json`, { stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000 })
-    return true
-  } catch {}
-  return false
+    const result = spawnSync(cmd, ['list-targets', '--json'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 5000
+    })
+    if (result.status !== 0) {
+      return {
+        ok: false,
+        raw: `${result.stdout || ''}${result.stderr || ''}`.trim() || null,
+        parsedVersion: null
+      }
+    }
+
+    const version = getIdbPackageVersion()
+    const raw = version ? `fb-idb ${version}` : `${result.stdout || ''}${result.stderr || ''}`.trim() || null
+    return {
+      ok: true,
+      raw,
+      parsedVersion: version
+    }
+  } catch {
+    return { ok: false, raw: null, parsedVersion: null }
+  }
+}
+
+export function isIDBInstalled(): boolean {
+  return probeIdb().ok
 }

package/src/utils/exec.ts

@@ -1,9 +1,11 @@
+import { remainingBudget } from './operation-budget.js'
 import { spawn } from 'child_process'
 
 export type ExecOptions = { timeout?: number; env?: NodeJS.ProcessEnv; cwd?: string; shell?: boolean }
 
 export async function execCmd(cmd: string, args: string[], opts: ExecOptions = {}): Promise<{ exitCode: number | null, stdout: string, stderr: string }> {
-  const { timeout = 0, env, cwd, shell } = opts
+  const { env, cwd, shell } = opts
+  const timeout = remainingBudget(opts.timeout ?? 0)
   return new Promise((resolve, reject) => {
     const child = spawn(cmd, args, { env: { ...process.env, ...(env || {}) }, cwd, shell })
     let stdout = ''
@@ -15,7 +17,7 @@ export async function execCmd(cmd: string, args: string[], opts: ExecOptions = {
     const timer = timeout && timeout > 0 ? setTimeout(() => {
       timedOut = true
       try { child.kill() } catch { }
-      resolve({ exitCode: null, stdout: stdout.trim(), stderr: stderr.trim() })
+      resolve({ exitCode: null, stdout: stdout.trim(), stderr: 'ACTION_TIMEOUT' })
     }, timeout) : null
 
     child.on('close', (code) => {

package/src/utils/ios/utils.ts

@@ -1,3 +1,4 @@
+import { remainingBudget } from '../operation-budget.js'
 import { execFile, spawn, execSync, spawnSync } from "child_process"
 import { DeviceInfo } from "../../types.js"
 import { promises as fsPromises } from 'fs'
@@ -59,17 +60,13 @@ export function getIdbCmd() {
 
 export async function isIDBInstalled(): Promise<boolean> {
   const cmd = getIdbCmd()
+  if (!cmd) return false
   try {
-    execSync(`command -v ${cmd}`, { stdio: ['ignore','pipe','ignore'] })
+    execSync(`${cmd} list-targets --json`, { stdio: ['ignore','pipe','pipe'], timeout: 5000 })
     return true
   } catch (e: unknown) {
-    try {
-      execSync(`${cmd} list-targets --json`, { stdio: ['ignore','pipe','ignore'], timeout: 2000 })
-      return true
-    } catch (e2: unknown) {
-      console.debug(`[isIDBInstalled] idb presence check failed for '${cmd}': ${e instanceof Error ? e.message : String(e2)}`)
-      return false
-    }
+    console.debug(`[isIDBInstalled] idb probe failed for '${cmd}': ${e instanceof Error ? e.message : String(e)}`)
+    return false
   }
 }
 
@@ -90,6 +87,7 @@ export function validateBundleId(bundleId: string) {
 export function execCommand(args: string[], deviceId: string = "booted"): Promise<IOSResult> {
   return new Promise((resolve, reject) => {
     // Use spawn for better stream control and consistency with Android implementation
+    const budgetMs = remainingBudget()
     const child = spawn(getXcrunCmd(), args)
     
     let stdout = ''
@@ -109,7 +107,7 @@ export function execCommand(args: string[], deviceId: string = "booted"): Promis
 
     const DEFAULT_XCRUN_LOG_TIMEOUT = parseInt(process.env.MCP_XCRUN_LOG_TIMEOUT || '', 10) || 30000 // env (ms) or default 30s
   const DEFAULT_XCRUN_CMD_TIMEOUT = parseInt(process.env.MCP_XCRUN_TIMEOUT || '', 10) || 60000 // env (ms) or default 60s
-  const timeoutMs = args.includes('log') ? DEFAULT_XCRUN_LOG_TIMEOUT : DEFAULT_XCRUN_CMD_TIMEOUT // choose appropriate timeout
+  const timeoutMs = budgetMs || (args.includes('log') ? DEFAULT_XCRUN_LOG_TIMEOUT : DEFAULT_XCRUN_CMD_TIMEOUT) // choose appropriate timeout
     const timeout = setTimeout(() => {
       child.kill()
       reject(new Error(`Command timed out after ${timeoutMs}ms: ${getXcrunCmd()} ${args.join(' ')}`))
@@ -132,10 +130,11 @@ export function execCommand(args: string[], deviceId: string = "booted"): Promis
 }
 
 export function execCommandWithDiagnostics(args: string[], deviceId: string = "booted") {
+  const budgetMs = remainingBudget()
   // Run synchronously to capture stdout/stderr and exitCode reliably for diagnostics
   const DEFAULT_XCRUN_LOG_TIMEOUT = parseInt(process.env.MCP_XCRUN_LOG_TIMEOUT || '', 10) || 30000
   const DEFAULT_XCRUN_CMD_TIMEOUT = parseInt(process.env.MCP_XCRUN_TIMEOUT || '', 10) || 60000
-  const timeoutMs = args.includes('log') ? DEFAULT_XCRUN_LOG_TIMEOUT : DEFAULT_XCRUN_CMD_TIMEOUT
+  const timeoutMs = budgetMs || (args.includes('log') ? DEFAULT_XCRUN_LOG_TIMEOUT : DEFAULT_XCRUN_CMD_TIMEOUT)
   const res = spawnSync(getXcrunCmd(), args, { encoding: 'utf8', timeout: timeoutMs }) as any
   const runResult = {
     exitCode: typeof res.status === 'number' ? res.status : null,

package/src/utils/operation-budget.ts

@@ -0,0 +1,22 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+export interface OperationBudget { deadline: number; dispatchStarted: boolean; parent?: OperationBudget }
+const budgets = new AsyncLocalStorage<OperationBudget>()
+export function hasFiniteBudget() { return Number.isFinite(budgets.getStore()?.deadline) }
+export function runWithBudget<T>(timeoutMs: number, operation: (budget: OperationBudget) => Promise<T>) {
+  const parent = budgets.getStore()
+  const budget = { deadline: Math.min(parent?.deadline ?? Infinity, performance.now() + timeoutMs), dispatchStarted: false, parent }
+  return budgets.run(budget, () => operation(budget))
+}
+export function remainingBudget(fallback = 0): number {
+  const budget = budgets.getStore()
+  if (!budget || !Number.isFinite(budget.deadline)) return fallback
+  const remaining = Math.floor(budget.deadline - performance.now())
+  if (remaining <= 0) throw new Error('ACTION_TIMEOUT')
+  return fallback > 0 ? Math.min(fallback, remaining) : remaining
+}
+export function markDispatchStarted() {
+  remainingBudget()
+  let budget = budgets.getStore()
+  while (budget) { budget.dispatchStarted = true; budget = budget.parent }
+}

package/src/utils/resolve-device.ts

@@ -1,3 +1,6 @@
+import { retainConnectedDeviceSnapshots } from '../observe/snapshot-metadata.js'
+import { measure } from './timing.js'
+import { AsyncLocalStorage } from 'node:async_hooks'
 import { DeviceInfo } from "../types.js"
 import { listAndroidDevices } from "./android/utils.js"
 import { listIOSDevices } from "./ios/utils.js"
@@ -44,9 +47,18 @@ export async function listDevices(platform?: "android" | "ios", appId?: string):
   return iosDeviceLister(appId)
 }
 
+const deviceContext = new AsyncLocalStorage<DeviceInfo>()
+
+export function withResolvedDevice<T>(device: DeviceInfo, operation: () => Promise<T>): Promise<T> {
+  return deviceContext.run(device, operation)
+}
+
 export async function resolveTargetDevice(opts: ResolveOptions): Promise<DeviceInfo> {
   const { platform, appId, prefer, deviceId } = opts
-  const devices = await listDevices(platform, appId)
+  const current = deviceContext.getStore()
+  if (current && current.platform === platform && (!deviceId || current.id === deviceId)) return current
+  const devices = await measure('device_resolution_ms', () => listDevices(platform, appId))
+  retainConnectedDeviceSnapshots(platform, devices.map(device => device.id))
 
   // During unit tests (no adb/xcrun available), provide a lightweight mock device so
   // the observe/interact unit tests can run without real devices.

package/src/utils/timing.ts

@@ -0,0 +1,15 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+const timings = new AsyncLocalStorage<Record<string, number>>()
+export function withTiming<T>(values: Record<string, number>, operation: () => Promise<T>) { return timings.run(values, operation) }
+export function recordTiming(component: string, milliseconds: number) {
+  const values = timings.getStore()
+  if (values) values[component] = (values[component] ?? 0) + milliseconds
+}
+export async function measure<T>(component: string, operation: () => Promise<T>): Promise<T> {
+  const start = performance.now()
+  try { return await operation() }
+  finally {
+    const values = timings.getStore()
+    if (values) values[component] = (values[component] ?? 0) + performance.now() - start
+  }
+}

package/src/utils/ui/index.ts

@@ -1,3 +1,4 @@
+import { remainingBudget } from '../operation-budget.js'
 import crypto from 'crypto'
 import { GetUITreeResponse, GetCurrentScreenResponse, UIElement, SwipeResponse } from '../../types.js'
 
@@ -152,6 +153,7 @@ export async function scrollToElementShared(opts: {
   let scrollsPerformed = 0
 
   for (let i = 0; i < maxScrolls; i++) {
+    remainingBudget()
     const { x1, y1, x2, y2 } = computeCoords()
     try {
       await swipe(x1, y1, x2, y2, duration, deviceId)

package/test/device/automated/latency/benchmark.ts

@@ -0,0 +1,136 @@
+import { execFileSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+import { buildFixture } from '../../../fixtures/latency-journey-app/build.js'
+import { summarize } from './report.js'
+
+const appId = 'dev.mobiledebugmcp.latencyfixture'
+const stepTimeoutMs = 30000
+const targetWaitTimeoutMs = 10000
+const verificationTimeoutMs = 60000
+const deviceId = process.env.LATENCY_DEVICE_ID
+if (!deviceId) throw new Error('Set LATENCY_DEVICE_ID to the named Android emulator serial')
+const adb = (...args: string[]) => execFileSync('adb', ['-s', deviceId, ...args], { encoding: 'utf8', timeout: 30000 }).trim()
+const apk = buildFixture()
+const selectorMap = {
+  savedSession: 'saved-session', idleDetail: 'idle-detail', activeDetail: 'active-detail',
+  activate: 'activate', deactivate: 'deactivate', home: 'home', homeScreen: 'home-screen',
+  stop: 'stop', stopped: 'stopped'
+}
+const selector = (id: string) => ({ accessibility_id: id })
+const flow = [
+  [selectorMap.savedSession, selectorMap.idleDetail], [selectorMap.activate, selectorMap.activeDetail],
+  [selectorMap.home, selectorMap.homeScreen], [selectorMap.savedSession, selectorMap.activeDetail],
+  [selectorMap.deactivate, selectorMap.idleDetail], [selectorMap.stop, selectorMap.stopped]
+]
+const transport = new StdioClientTransport({ command: process.execPath, args: ['dist/server.js'], stderr: 'pipe' })
+transport.stderr?.on('data', chunk => process.stderr.write(`[server] ${chunk.toString()}`))
+const client = new Client({ name: 'latency-benchmark', version: '1.0' })
+const raw: any[] = []
+const requestSequence: Record<string, any[]> = {}
+let sequence: any[] = []
+let failedSelector: string | null = null
+let failedTool: string | null = null
+async function call(name: string, args: any) {
+  failedTool = name
+  sequence.push({ tool: name, ...args, appId: args.appId ? '[fixture]' : undefined, deviceId: undefined, steps: args.steps?.map((step: any) => ({ ...step, appId: step.appId ? '[fixture]' : undefined })) })
+  const start = performance.now()
+  let response
+  try {
+    response = await client.callTool({ name, arguments: { platform: 'android', deviceId, ...args } }, undefined, { timeout: 300_000 })
+  } catch (error) {
+    console.error(`MCP ${name} rejected: ${error instanceof Error ? error.stack : String(error)}`)
+    throw error
+  }
+  const elapsed = performance.now() - start
+  const text = (response.content as any[]).find(item => item.type === 'text')?.text
+  let data: any
+  try { data = JSON.parse(text) } catch { data = {} }
+  if (response.isError || data.success === false || data.status === 'timeout' || data.error) {
+    const failed = args.steps?.find((step: any) => step.id === data.stopped_at_step_id)
+    if (failed) { failedSelector = failed.selector?.accessibility_id ?? failed.assertion?.selector?.accessibility_id ?? null; failedTool = `run_journey:${failed.id}` }
+    throw new Error('Fixture step failed')
+  }
+  return { data, elapsed }
+}
+async function run(mode: string) {
+  sequence = []
+  failedSelector = null
+  failedTool = null
+  adb('shell', 'am', 'force-stop', appId)
+  try { adb('shell', 'pm', 'clear', appId) } catch { /* First install has no app data. */ }
+  adb('install', '-r', apk)
+  // Check the reset state outside the measured MCP flow, then force-stop once more.
+  failedTool = 'reset-state'
+  failedSelector = selectorMap.savedSession
+  adb('shell', 'am', 'start', '-n', `${appId}/.MainActivity`)
+  adb('shell', 'uiautomator', 'dump', '/sdcard/ui.xml')
+  if (!adb('shell', 'cat', '/sdcard/ui.xml').includes(`content-desc="${selectorMap.savedSession}"`)) throw new Error('Reset selector missing')
+  adb('shell', 'am', 'force-stop', appId)
+  sequence = []
+  const requestTimes: number[] = []
+  const componentTimes: Record<string, number[]> = {}
+  const record = (response: any) => {
+    requestTimes.push(response.elapsed)
+    const timing = response.data.timing ?? {}
+    const components = Object.entries(timing).filter(([key, value]) => key !== 'total_ms' && typeof value === 'number')
+    const stepTimings = (response.data.steps ?? []).flatMap((step: any) => Object.entries(step.result?.timing ?? {}))
+    const selected = components.length ? components : stepTimings
+    for (const [key, value] of selected) if (typeof value === 'number') (componentTimes[key] ??= []).push(value)
+  }
+  if (mode === 'baseline') {
+    record(await call('start_app', { appId, actionTimeoutMs: stepTimeoutMs, verificationTimeoutMs }))
+    for (const [target, expected] of flow) {
+      failedSelector = target
+      const found = await call('wait_for_ui', { selector: selector(target), condition: 'clickable', timeout_ms: targetWaitTimeoutMs, poll_interval_ms: 100 })
+      record(found)
+      record(await call('tap_element', { elementId: found.data.element.elementId, actionTimeoutMs: stepTimeoutMs, verificationTimeoutMs }))
+      failedSelector = expected
+      record(await call('expect_element_visible', { selector: selector(expected), timeout_ms: stepTimeoutMs, poll_interval_ms: 100 }))
+    }
+  } else {
+    const steps: any[] = [{ id: 'launch', type: 'start_app', appId }]
+    flow.forEach(([target, expected], index) => {
+      steps.push({ id: `tap-${index}`, type: 'tap', selector: selector(target), waitFor: { condition: 'clickable', timeoutMs: targetWaitTimeoutMs, pollIntervalMs: 100 } })
+      steps.push({ id: `assert-${index}`, type: 'assert', assertion: { kind: 'element_visible', selector: selector(expected) }, timeoutMs: stepTimeoutMs, pollIntervalMs: 100 })
+    })
+    record(await call('run_journey', { defaults: { verificationMode: mode === 'full' ? 'full' : 'light', actionTimeoutMs: stepTimeoutMs, verificationTimeoutMs }, responseMode: mode === 'full' ? 'debug' : 'compact', steps }))
+  }
+  requestSequence[mode] ??= sequence
+  const screenshot = await call('capture_screenshot', {})
+  const snapshot = await call('capture_debug_snapshot', { includeScreenshot: false, includeLogs: false })
+  return { total_ms: requestTimes.reduce((a, b) => a + b, 0), componentTimes, screenshot_ms: screenshot.elapsed, snapshot_ms: snapshot.elapsed }
+}
+async function main() {
+  await client.connect(transport)
+  try {
+    for (const mode of ['baseline', 'full', 'light']) {
+      for (let iteration = 0; iteration < 13; iteration++) {
+        console.log(`${mode} ${iteration + 1}/13`)
+        try { raw.push({ mode, warmup: iteration < 3, success: true, ...await run(mode) }) }
+        catch (error) { const message = error instanceof Error ? error.message : String(error); console.error(`${mode} run failed at ${failedTool}/${failedSelector}: ${message}`); raw.push({ mode, warmup: iteration < 3, success: false, failed_selector: failedSelector, failed_tool: failedTool, error: message }) }
+      }
+    }
+  } finally { await client.close() }
+  const modes = Object.fromEntries(['baseline', 'full', 'light'].map(mode => {
+    const samples = raw.filter(item => item.mode === mode && !item.warmup && item.success)
+    const failures = raw.filter(item => item.mode === mode && !item.success)
+    return [mode, { failures: failures.length, first_failure: failures[0] ? { selector: failures[0].failed_selector, tool_or_step: failures[0].failed_tool } : null, total_ms: summarize(samples.map(item => item.total_ms)), screenshot_ms: summarize(samples.map(item => item.screenshot_ms)), snapshot_ms: summarize(samples.map(item => item.snapshot_ms)), components: Object.fromEntries([...new Set(samples.flatMap(item => Object.keys(item.componentTimes)))].map(key => [key, summarize(samples.flatMap(item => item.componentTimes[key] ?? []))])) }]
+  })) as any
+  const report = {
+    commit: execFileSync('git', ['rev-parse', 'HEAD'], { encoding: 'utf8' }).trim(), working_tree: 'candidate',
+    server_version: JSON.parse(readFileSync('package.json', 'utf8')).version,
+    platform: 'android', model: adb('shell', 'getprop', 'ro.product.model'), os: adb('shell', 'getprop', 'ro.build.version.release'), api: adb('shell', 'getprop', 'ro.build.version.sdk'), emulator_image: adb('emu', 'avd', 'name').split('\n')[0].trim(), display_size: adb('shell', 'wm', 'size'), display_density: adb('shell', 'wm', 'density'), adb_timeout_ms: Number(process.env.MCP_ADB_TIMEOUT ?? 20000),
+    fixture_version: '1.0', fixture_sha256: createHash('sha256').update(readFileSync(apk)).digest('hex'), warmup_runs: 3, measured_runs: 10,
+    modes, requests: requestSequence, raw,
+    gates: { full_p95: !!modes.baseline.total_ms && !!modes.full.total_ms && modes.full.total_ms.p95 <= modes.baseline.total_ms.p95 * 1.1, light_p50: !!modes.full.total_ms && !!modes.light.total_ms && modes.light.total_ms.p50 <= modes.full.total_ms.p50 * .7 }
+  }
+  const root = 'docs/benchmarks/interaction-latency'
+  mkdirSync(root, { recursive: true })
+  writeFileSync(`${root}/final.json`, JSON.stringify(report, null, 2))
+  writeFileSync(`${root}/final.md`, `# Interaction latency benchmark\n\nCommit: ${report.commit} (working tree candidate). Fixture: ${report.fixture_version}, SHA-256 ${report.fixture_sha256}.\n\nEnvironment: ${report.emulator_image}, Android ${report.os}, API ${report.api}. Three warm-ups and ten measured runs per mode. Failed runs excluded.\n\n| Mode | p50 ms | p95 ms | Failures |\n|---|---:|---:|---:|\n${Object.entries(modes).map(([mode, value]: [string, any]) => `| ${mode} | ${value.total_ms?.p50 ?? 'n/a'} | ${value.total_ms?.p95 ?? 'n/a'} | ${value.failures} |`).join('\n')}\n\nFirst failure by mode: ${Object.entries(modes).map(([mode, value]: [string, any]) => `${mode}: ${value.first_failure ? `${value.first_failure.tool_or_step} / ${value.first_failure.selector ?? 'no selector'}` : 'none'}`).join('; ')}.\n\nFull p95 gate: ${report.gates.full_p95}. Light p50 gate: ${report.gates.light_p50}.\n\nSee final.json for requests, timing components, and failure selectors.\n`)
+  if (!report.gates.full_p95 || !report.gates.light_p50) process.exitCode = 1
+}
+main().catch(error => { console.error(error); process.exitCode = 1 })

package/test/device/automated/latency/report.ts

@@ -0,0 +1,6 @@
+export function summarize(samples: number[]) {
+  if (!samples.length) return null
+  const sorted = [...samples].sort((a, b) => a - b)
+  const percentile = (p: number) => sorted[Math.max(0, Math.ceil(p * sorted.length) - 1)]
+  return { count: samples.length, p50: percentile(.5), p95: percentile(.95), min: sorted[0], max: sorted[sorted.length - 1] }
+}

package/test/fixtures/latency-journey-app/AndroidManifest.xml

@@ -0,0 +1,6 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="dev.mobiledebugmcp.latencyfixture" android:versionCode="1" android:versionName="1.0">
+  <uses-sdk android:minSdkVersion="23" android:targetSdkVersion="35"/>
+  <application android:theme="@android:style/Theme.Material.Light.NoActionBar" android:label="Latency fixture" android:allowBackup="false">
+    <activity android:name=".MainActivity" android:exported="true"><intent-filter><action android:name="android.intent.action.MAIN"/><category android:name="android.intent.category.LAUNCHER"/></intent-filter></activity>
+  </application>
+</manifest>

package/test/fixtures/latency-journey-app/README.md

@@ -0,0 +1,10 @@
+# Interaction latency fixture
+
+An offline native Android fixture, version 1.0. It requires Android SDK platform 36,
+build-tools 36.0.0 and JDK 21. The harness builds and signs it using those installed
+tools; no Gradle dependency download is needed.
+
+Selectors are accessibility IDs: `saved-session`, `idle-detail`, `activate`,
+`active-detail`, `home`, `home-screen`, `deactivate`, `stop`, and `stopped`.
+The app keeps control state only in memory. Clearing data and relaunching restores
+Home with an inactive control. It requests no permissions and has no network code.

package/test/fixtures/latency-journey-app/build.ts

@@ -0,0 +1,26 @@
+import { execFileSync } from 'node:child_process'
+import { mkdirSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export function buildFixture() {
+  const root = path.dirname(fileURLToPath(import.meta.url))
+  const out = path.join(root, 'build')
+  const sdk = process.env.ANDROID_HOME ?? path.join(process.env.HOME!, 'Library/Android/sdk')
+  const buildTools = path.join(sdk, 'build-tools', '36.0.0')
+  const androidJar = path.join(sdk, 'platforms', 'android-36', 'android.jar')
+  const java = process.env.JAVA_HOME
+  const tool = (name: string) => java ? path.join(java, 'bin', name) : name
+  const run = (cmd: string, args: string[]) => execFileSync(cmd, args, { cwd: out, stdio: 'pipe' })
+  mkdirSync(path.join(out, 'classes'), { recursive: true })
+  run(tool('javac'), ['--release', '8', '-classpath', androidJar, '-d', 'classes', path.join(root, 'src/MainActivity.java')])
+  run(tool('jar'), ['cf', 'classes.jar', '-C', 'classes', '.'])
+  run(path.join(buildTools, 'd8'), ['--lib', androidJar, '--output', out, 'classes.jar'])
+  run(path.join(buildTools, 'aapt2'), ['link', '-I', androidJar, '--manifest', path.join(root, 'AndroidManifest.xml'), '-o', 'unsigned.apk'])
+  run('zip', ['-q', 'unsigned.apk', 'classes.dex'])
+  run(path.join(buildTools, 'zipalign'), ['-f', '4', 'unsigned.apk', 'aligned.apk'])
+  // Ephemeral signing material is generated outside version control.
+  try { run(tool('keytool'), ['-genkeypair', '-keystore', 'fixture.jks', '-storepass', 'android', '-keypass', 'android', '-alias', 'fixture', '-dname', 'CN=Latency Fixture', '-keyalg', 'RSA', '-validity', '3650']) } catch { /* Existing local fixture key. */ }
+  run(path.join(buildTools, 'apksigner'), ['sign', '--ks', 'fixture.jks', '--ks-pass', 'pass:android', '--out', 'fixture.apk', 'aligned.apk'])
+  return path.join(out, 'fixture.apk')
+}

package/test/fixtures/latency-journey-app/src/MainActivity.java

@@ -0,0 +1,48 @@
+package dev.mobiledebugmcp.latencyfixture;
+
+import android.app.Activity;
+import android.os.Bundle;
+import android.widget.Button;
+import android.widget.LinearLayout;
+import android.widget.TextView;
+
+public final class MainActivity extends Activity {
+    private static final class Selectors {
+        static final String SAVED_SESSION = "saved-session";
+        static final String IDLE_DETAIL = "idle-detail";
+        static final String ACTIVE_DETAIL = "active-detail";
+        static final String ACTIVATE = "activate";
+        static final String DEACTIVATE = "deactivate";
+        static final String HOME = "home";
+        static final String HOME_SCREEN = "home-screen";
+        static final String STOP = "stop";
+        static final String STOPPED = "stopped";
+    }
+    private boolean active = false;
+    private LinearLayout layout;
+    @Override public void onCreate(Bundle state) { super.onCreate(state); home(); }
+    private void screen(String id) {
+        layout = new LinearLayout(this);
+        layout.setOrientation(LinearLayout.VERTICAL);
+        layout.setPadding(32, 100, 32, 32);
+        setContentView(layout);
+        TextView title = new TextView(this);
+        title.setText(id);
+        title.setContentDescription(id);
+        layout.addView(title);
+    }
+    private void button(String id, Runnable action) {
+        Button button = new Button(this);
+        button.setText(id);
+        button.setContentDescription(id);
+        button.setOnClickListener(v -> action.run());
+        layout.addView(button, new LinearLayout.LayoutParams(-1, 120));
+    }
+    private void home() { screen(Selectors.HOME_SCREEN); button(Selectors.SAVED_SESSION, () -> detail()); }
+    private void detail() {
+        screen(active ? Selectors.ACTIVE_DETAIL : Selectors.IDLE_DETAIL);
+        button(active ? Selectors.DEACTIVATE : Selectors.ACTIVATE, () -> { active = !active; detail(); });
+        button(Selectors.HOME, () -> home());
+        button(Selectors.STOP, () -> { active = false; screen(Selectors.STOPPED); });
+    }
+}

package/test/unit/interact/tap_element.test.ts

@@ -226,7 +226,7 @@ async function run() {
       const result = await ToolsInteract.waitForUIHandler({
         selector: { text: `Button ${i}` },
         condition: 'exists',
-        timeout_ms: 200,
+        timeout_ms: 1000,
         poll_interval_ms: 50,
         platform: 'android'
       })

package/test/unit/manage/restart_budget.test.ts

@@ -0,0 +1,37 @@
+import assert from 'node:assert/strict'
+import { AndroidManage } from '../../../src/manage/android.js'
+import { iOSManage } from '../../../src/manage/ios.js'
+import { remainingBudget, runWithBudget } from '../../../src/utils/operation-budget.js'
+
+async function run() {
+  const androidTerminate = AndroidManage.prototype.terminateApp
+  const androidStart = AndroidManage.prototype.startApp
+  const iosTerminate = iOSManage.prototype.terminateApp
+  const iosStart = iOSManage.prototype.startApp
+  const device = { platform: 'android', id: 'fixture' } as any
+  let androidLaunchBudget = 0
+  let iosLaunchBudget = 0
+  try {
+    AndroidManage.prototype.terminateApp = async () => ({ device, appTerminated: true })
+    AndroidManage.prototype.startApp = async (_appId, _deviceId, timeoutMs) => {
+      androidLaunchBudget = timeoutMs ?? 0
+      return { device, appStarted: true } as any
+    }
+    iOSManage.prototype.terminateApp = async () => ({ device, appTerminated: true })
+    iOSManage.prototype.startApp = async () => {
+      iosLaunchBudget = remainingBudget()
+      return { device, appStarted: true } as any
+    }
+    await runWithBudget(30000, () => new AndroidManage().restartApp('fixture', 'fixture', true, 30000))
+    await runWithBudget(30000, () => new iOSManage().restartApp('fixture', 'fixture', false, true, 30000))
+    assert.ok(androidLaunchBudget > 15000, `Android launch received ${androidLaunchBudget}ms`)
+    assert.ok(iosLaunchBudget > 15000, `iOS launch received ${iosLaunchBudget}ms`)
+  } finally {
+    AndroidManage.prototype.terminateApp = androidTerminate
+    AndroidManage.prototype.startApp = androidStart
+    iOSManage.prototype.terminateApp = iosTerminate
+    iOSManage.prototype.startApp = iosStart
+  }
+}
+
+run().catch(error => { console.error(error); process.exitCode = 1 })