mobile-debug-mcp 0.31.0 → 0.32.1

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/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 = ''
@@ -12,22 +14,28 @@ export async function execCmd(cmd: string, args: string[], opts: ExecOptions = {
     if (child.stderr) child.stderr.on('data', (d) => { stderr += d.toString() })
 
     let timedOut = false
+    let forceKillTimer: NodeJS.Timeout | null = null
     const timer = timeout && timeout > 0 ? setTimeout(() => {
       timedOut = true
       try { child.kill() } catch { }
-      resolve({ exitCode: null, stdout: stdout.trim(), stderr: stderr.trim() })
+      forceKillTimer = setTimeout(() => {
+        try { child.kill('SIGKILL') } catch { }
+      }, 1000)
+      forceKillTimer.unref()
     }, timeout) : null
 
     child.on('close', (code) => {
       if (timer) clearTimeout(timer)
-      if (timedOut) return
-      resolve({ exitCode: code, stdout: stdout.trim(), stderr: stderr.trim() })
+      if (forceKillTimer) clearTimeout(forceKillTimer)
+      resolve(timedOut
+        ? { exitCode: null, stdout: stdout.trim(), stderr: 'ACTION_TIMEOUT' }
+        : { exitCode: code, stdout: stdout.trim(), stderr: stderr.trim() })
     })
 
     child.on('error', (err) => {
       if (timer) clearTimeout(timer)
+      if (forceKillTimer) clearTimeout(forceKillTimer)
       reject(err)
     })
   })
 }
-

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'
@@ -86,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 = ''
@@ -105,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(' ')}`))
@@ -128,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] }
+}