mobile-debug-mcp 0.31.0 → 0.32.0

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] }
+}

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/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 })

package/test/unit/observe/capture_debug_snapshot.test.ts

@@ -83,6 +83,12 @@ async function run() {
     assert.ok(pass3, 'captureDebugSnapshot should return an empty logs array when includeLogs is false')
     console.log('Test 3:', pass3 ? 'PASS' : 'FAIL')
 
+    let screenshotCalls = 0
+    ;(ToolsObserve as any).captureScreenshotHandler = async function() { screenshotCalls++; return { screenshot: 'unexpected' } }
+    const res4: any = await ToolsObserve.captureDebugSnapshotHandler({ platform: 'android', includeLogs: false, includeScreenshot: false })
+    assert.strictEqual(screenshotCalls, 0, 'includeScreenshot=false must not invoke screenshot capture')
+    assert.strictEqual(res4.raw.screenshot, null)
+
   } finally {
     ;(ToolsObserve as any).captureScreenshotHandler = origCaptureHandler
     ;(ToolsObserve as any).getCurrentScreenHandler = origGetCurrentHandler

package/test/unit/observe/snapshot_metadata.test.ts

@@ -1,5 +1,5 @@
 import assert from 'assert'
-import { deriveSnapshotMetadata, resetSnapshotMetadataForTests } from '../../../src/observe/snapshot-metadata.js'
+import { deriveSnapshotMetadata, getStateDelta, resetSnapshotMetadataForTests } from '../../../src/observe/snapshot-metadata.js'
 
 async function run() {
   console.log('Starting snapshot_metadata unit tests...')
@@ -57,6 +57,25 @@ async function run() {
     total_elements: 1
   })
 
+  const delta = getStateDelta(deviceKey, 1, 2)
+  assert.ok(delta)
+  assert.strictEqual(delta!.added.length, 0)
+  assert.strictEqual(delta!.removed.length, 0)
+  assert.strictEqual(delta!.changed.length, 1)
+  assert.strictEqual(delta!.changed[0].text, 'Beta')
+  assert.strictEqual(delta!.truncated, false)
+  assert.strictEqual(getStateDelta(deviceKey, 99, 2), null)
+
+  for (let index = 3; index <= 10; index++) {
+    deriveSnapshotMetadata(deviceKey, {
+      screen: 'Home',
+      resolution: { width: 100, height: 200 },
+      elements: [{ text: `Revision ${index}`, stable_id: 'stable-row', visible: true }]
+    }, 'ui_tree')
+  }
+  assert.ok(getStateDelta(deviceKey, 3, 10), 'recent revisions remain available after pruning')
+  assert.strictEqual(getStateDelta(deviceKey, 2, 10), null, 'only the oldest revision is pruned')
+
   resetSnapshotMetadataForTests()
   console.log('snapshot_metadata unit tests passed')
 }

package/test/unit/observe/state_delta.test.ts

@@ -0,0 +1,15 @@
+import assert from 'node:assert/strict'
+import { deriveSnapshotMetadata, getStateDelta, getLatestStateDelta, resetSnapshotMetadataForTests } from '../../../src/observe/snapshot-metadata.js'
+resetSnapshotMetadataForTests()
+const tree = (text: string) => ({ elements: [{ stable_id: 'one', text }, { stable_id: 'unchanged', text: 'fixed' }] }) as any
+const first = deriveSnapshotMetadata('android:test', tree('before'), 'test')
+const second = deriveSnapshotMetadata('android:test', tree('after'), 'test')
+const delta = getStateDelta('android:test', first.snapshot_revision, second.snapshot_revision)!
+assert.equal(delta.changed.length, 1)
+assert.equal(delta.changed[0].text, 'after')
+deriveSnapshotMetadata('android:test', tree('after'), 'test')
+assert.equal(getLatestStateDelta('android:test')!.changed.length, 0)
+const large = { elements: Array.from({ length: 501 }, (_, i) => ({ stable_id: String(i), text: String(i) })) } as any
+const third = deriveSnapshotMetadata('android:test', large, 'test')
+assert.equal(getStateDelta('android:test', second.snapshot_revision, third.snapshot_revision)!.truncated, true)
+assert.equal(getStateDelta('android:test', -1, third.snapshot_revision), null)

package/test/unit/server/benchmark_report.test.ts

@@ -0,0 +1,4 @@
+import assert from 'node:assert/strict'
+import { summarize } from '../../device/automated/latency/report.js'
+assert.equal(summarize([]), null)
+assert.deepEqual(summarize([10, 1, 8, 2, 9, 3, 7, 4, 6, 5]), { count: 10, p50: 5, p95: 10, min: 1, max: 10 })

package/test/unit/server/contract.test.ts

@@ -49,7 +49,7 @@ async function run() {
 
   const tapElement = toolDefinitions.find((tool) => tool.name === 'tap_element')
   assert(tapElement, 'tap_element should be registered')
-  assert.deepStrictEqual((tapElement as any).inputSchema.required, ['elementId'])
+  assert.deepStrictEqual((tapElement as any).inputSchema.oneOf, [{ required: ['elementId'], not: { required: ['selector'] } }, { required: ['selector'], not: { required: ['elementId'] } }])
   assert.match((tapElement as any).description, /RESOLVE → ACT → WAIT \(if needed\) → EXPECT/)
   assert.match((tapElement as any).description, /If needed, wait for transition using wait_for_\*/)
   assert.match((tapElement as any).description, /Verify outcome using expect_\*/)

package/test/unit/server/interaction_modes.test.ts

@@ -0,0 +1,60 @@
+import assert from 'node:assert/strict'
+import { handleToolCall } from '../../../src/server-core.js'
+import { ToolsInteract } from '../../../src/interact/index.js'
+import { ToolsObserve } from '../../../src/observe/index.js'
+import { AndroidManage } from '../../../src/manage/android.js'
+import { markDispatchStarted } from '../../../src/utils/operation-budget.js'
+
+async function run() {
+  const treeOriginal = ToolsObserve.getUITreeHandler
+  const fingerprintOriginal = ToolsObserve.getScreenFingerprintHandler
+  const tapOriginal = ToolsInteract.tapHandler
+  const launchOriginal = AndroidManage.prototype.startApp
+  const device: any = { platform: 'android', id: 'fixture' }
+  let dispatched = false
+  let postReads = 0
+  let fingerprints = 0
+  ToolsObserve.getUITreeHandler = async () => {
+    if (dispatched) postReads++
+    return { device, elements: [{ text: 'Go', stable_id: 'go', bounds: [0, 0, 40, 40], visible: true, enabled: true, clickable: true }] } as any
+  }
+  ToolsObserve.getScreenFingerprintHandler = async () => { fingerprints++; return { fingerprint: 'fixture' } as any }
+  ToolsInteract.tapHandler = async () => { dispatched = true; return { success: true, device } as any }
+  AndroidManage.prototype.startApp = async () => { dispatched = true; return { appStarted: true, device } as any }
+  try {
+    for (const tool of ['tap_element', 'start_app']) {
+      for (const mode of ['none', 'light', 'full']) {
+        dispatched = false; postReads = 0; fingerprints = 0
+        const response = await handleToolCall(tool, { platform: 'android', deviceId: 'fixture', ...(tool === 'tap_element' ? { selector: { text: 'Go' } } : { appId: 'fixture' }), verificationMode: mode, responseMode: 'compact' })
+        const result = JSON.parse(response.content[0].text!)
+        assert.equal(result.success, true, JSON.stringify(result))
+        assert.equal(postReads, mode === 'light' ? 1 : 0)
+        assert.equal(fingerprints, mode === 'full' ? 2 : 0)
+        assert.equal(result.device, undefined)
+        assert.equal(result.trace, undefined)
+        assert.equal(result.dispatch_started, true)
+        assert.deepEqual(Object.keys(result.timing), ['total_ms'])
+        if (mode !== 'full') assert.equal(result.lifecycle_state, 'pending_verification')
+      }
+    }
+    ToolsObserve.getUITreeHandler = async () => { throw new Error('offline') }
+    const result = JSON.parse((await handleToolCall('start_app', { platform: 'android', appId: 'fixture', verificationMode: 'light', responseMode: 'compact' })).content[0].text!)
+    assert.equal(result.success, true)
+    assert.equal(result.verification.status, 'unavailable')
+    assert.equal(result.verification_diagnostic.retryable, true)
+    ToolsInteract.tapHandler = async () => { markDispatchStarted(); dispatched = true; return { success: false, error: 'ACTION_TIMEOUT', device } as any }
+    const timedOut = JSON.parse((await handleToolCall('tap', { platform: 'android', deviceId: 'fixture', x: 1, y: 1, verificationMode: 'none', responseMode: 'compact' })).content[0].text!)
+    assert.equal(timedOut.failure_code, 'ACTION_TIMEOUT')
+    assert.equal(timedOut.delivery_status, 'unknown')
+    assert.equal(timedOut.retryable, false)
+    AndroidManage.prototype.startApp = async () => ({ appStarted: false, device, error: 'launch failed', diagnostics: { runResult: { exitCode: 1, stdout: '', stderr: 'launch failed' } } } as any)
+    const failedLaunch = JSON.parse((await handleToolCall('start_app', { platform: 'android', appId: 'fixture' })).content[0].text!)
+    assert.equal(failedLaunch.details.diagnostics.runResult.exitCode, 1)
+  } finally {
+    ToolsObserve.getUITreeHandler = treeOriginal
+    ToolsObserve.getScreenFingerprintHandler = fingerprintOriginal
+    ToolsInteract.tapHandler = tapOriginal
+    AndroidManage.prototype.startApp = launchOriginal
+  }
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

package/test/unit/server/operation_budget.test.ts

@@ -0,0 +1,32 @@
+import assert from 'node:assert/strict'
+import { runWithBudget, remainingBudget, markDispatchStarted } from '../../../src/utils/operation-budget.js'
+import { execCmd } from '../../../src/utils/exec.js'
+import { ToolsInteract } from '../../../src/interact/index.js'
+import { ToolsObserve } from '../../../src/observe/index.js'
+
+async function run() {
+  await runWithBudget(100, async budget => {
+    assert.equal(budget.dispatchStarted, false)
+    markDispatchStarted()
+    assert.equal(budget.dispatchStarted, true)
+    const response = await execCmd(process.execPath, ['-e', 'setTimeout(() => {}, 10000)'])
+    assert.equal(response.stderr, 'ACTION_TIMEOUT')
+    assert.throws(() => remainingBudget(), /ACTION_TIMEOUT/)
+  })
+  await runWithBudget(1, async budget => {
+    await new Promise(resolve => setTimeout(resolve, 5))
+    assert.throws(() => markDispatchStarted(), /ACTION_TIMEOUT/)
+    assert.equal(budget.dispatchStarted, false)
+  })
+  const originalTree = ToolsObserve.getUITreeHandler
+  ToolsObserve.getUITreeHandler = async () => { throw new Error('transient observation error') }
+  try {
+    await assert.rejects(
+      () => runWithBudget(30, () => ToolsInteract.waitForUIHandler({ selector: { text: 'missing' }, timeout_ms: 1000, poll_interval_ms: 5, platform: 'android', deviceId: 'fixture' })),
+      /ACTION_TIMEOUT/
+    )
+  } finally {
+    ToolsObserve.getUITreeHandler = originalTree
+  }
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

package/test/unit/server/response_shapes.test.ts

@@ -37,7 +37,7 @@ async function run() {
 
     const missingBuildResponse = await handleToolCall('build_app', { projectPath: '/tmp/project' })
     const missingBuildPayload = JSON.parse((missingBuildResponse as any).content[0].text)
-    assert.deepStrictEqual(missingBuildPayload, {
+    assert.deepStrictEqual({ error: missingBuildPayload.error }, {
       error: {
         tool: 'build_app',
         message: 'Missing or invalid string argument: platform'
@@ -236,7 +236,7 @@ async function run() {
     const failingTapResponse = await handleToolCall('tap', { platform: 'android', x: 1, y: 2 })
     assert.strictEqual((failingTapResponse as any).content.length, 1)
     const failingTapPayload = JSON.parse((failingTapResponse as any).content[0].text)
-    assert.deepStrictEqual(failingTapPayload, {
+    assert.deepStrictEqual({ error: failingTapPayload.error }, {
       error: {
         tool: 'tap',
         message: 'boom'
@@ -255,7 +255,7 @@ async function run() {
 
     const missingArgResponse = await handleToolCall('tap', { platform: 'android', x: 1 })
     const missingArgPayload = JSON.parse((missingArgResponse as any).content[0].text)
-    assert.deepStrictEqual(missingArgPayload, {
+    assert.deepStrictEqual({ error: missingArgPayload.error }, {
       error: {
         tool: 'tap',
         message: 'Missing or invalid number argument: y'