mobile-debug-mcp 0.31.0 → 0.32.1

package/dist/utils/exec.js

@@ -1,6 +1,8 @@
+import { remainingBudget } from './operation-budget.js';
 import { spawn } from 'child_process';
 export async function execCmd(cmd, args, opts = {}) {
-    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 = '';
@@ -10,24 +12,35 @@ export async function execCmd(cmd, args, opts = {}) {
         if (child.stderr)
             child.stderr.on('data', (d) => { stderr += d.toString(); });
         let timedOut = false;
+        let forceKillTimer = 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/dist/utils/ios/utils.js

@@ -1,3 +1,4 @@
+import { remainingBudget } from '../operation-budget.js';
 import { execFile, spawn, execSync, spawnSync } from "child_process";
 import { promises as fsPromises } from 'fs';
 import path from 'path';
@@ -94,6 +95,7 @@ export function validateBundleId(bundleId) {
 export function execCommand(args, deviceId = "booted") {
     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 = '';
         let stderr = '';
@@ -109,7 +111,7 @@ export function execCommand(args, deviceId = "booted") {
         }
         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(' ')}`));
@@ -130,10 +132,11 @@ export function execCommand(args, deviceId = "booted") {
     });
 }
 export function execCommandWithDiagnostics(args, deviceId = "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 });
     const runResult = {
         exitCode: typeof res.status === 'number' ? res.status : null,

package/dist/utils/operation-budget.js

@@ -0,0 +1,25 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+const budgets = new AsyncLocalStorage();
+export function hasFiniteBudget() { return Number.isFinite(budgets.getStore()?.deadline); }
+export function runWithBudget(timeoutMs, operation) {
+    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) {
+    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/dist/utils/resolve-device.js

@@ -1,3 +1,6 @@
+import { retainConnectedDeviceSnapshots } from '../observe/snapshot-metadata.js';
+import { measure } from './timing.js';
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { listAndroidDevices } from "./android/utils.js";
 import { listIOSDevices } from "./ios/utils.js";
 function parseNumericVersion(v) {
@@ -32,9 +35,17 @@ export async function listDevices(platform, appId) {
     }
     return iosDeviceLister(appId);
 }
+const deviceContext = new AsyncLocalStorage();
+export function withResolvedDevice(device, operation) {
+    return deviceContext.run(device, operation);
+}
 export async function resolveTargetDevice(opts) {
     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.
     if ((!devices || devices.length === 0) && (process.env.NODE_ENV === 'test' || process.env.MCP_TEST_MOCK_DEVICES === '1')) {

package/dist/utils/timing.js

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

package/dist/utils/ui/index.js

@@ -1,3 +1,4 @@
+import { remainingBudget } from '../operation-budget.js';
 import crypto from 'crypto';
 const ANDROID_STRUCTURAL_TYPES = ['Window', 'Application', 'View', 'ViewGroup', 'LinearLayout', 'FrameLayout', 'RelativeLayout', 'ScrollView', 'RecyclerView', 'TextView', 'ImageView'];
 const IOS_STRUCTURAL_TYPES = ['Window', 'Application', 'View', 'ViewController', 'UITableView', 'UICollectionView', 'UILabel', 'UIImageView', 'UIView', 'UIWindow', 'UIStackView', 'UITextView', 'UITableViewCell'];
@@ -140,6 +141,7 @@ export async function scrollToElementShared(opts) {
     const duration = 300;
     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/docs/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.32.1]
+- Further performance enhancements
+
+## [0.32.0]
+- Added bounded interaction verification modes, compact responses, selector-based taps, and batched journeys to reduce MCP interaction latency.
+
 ## [0.31.0]
 - Added tool discovery/automation
 

package/docs/ROADMAP.md

@@ -11,6 +11,7 @@
 - Actionability Resolution
 - Environment Auto-Configuration and Toolchain Discovery
 - Adjustable Control Support
+- UI-Tree Observation Performance (Android implemented; iOS latency unmeasured)
 
 ## Todo
 
@@ -21,6 +22,14 @@
 - Pinch to Zoom
 - Advanced Trace Correlation and Analysis
 
+# UI-Tree Observation Performance
+
+**Status:** Android implemented and benchmarked; iOS latency remains unmeasured — [Specification 019](specs/019-ui-tree-observation-performance/spec.md)
+
+Measure physical hierarchy reads and their cost, then reduce the measured hot path while preserving fresh post-action and asynchronous UI evidence. Validate the change against the existing static journey and a controlled network-backed screen before claiming a speedup.
+
+Exit criteria and performance gates are defined in Specification 019.
+
 # Stronger State Verification
 
 ## Rationale

package/docs/benchmarks/interaction-latency/README.md

@@ -0,0 +1,26 @@
+# Interaction latency benchmark
+
+Run after `npm run verify`:
+
+```sh
+MCP_ADB_TIMEOUT=30000 LATENCY_DEVICE_ID=emulator-5554 npx tsx test/device/automated/latency/benchmark.ts
+```
+
+Use the named Pixel 9 Pro Android 16 emulator with SDK platform 36, build-tools
+36.0.0, and a Java installation capable of `javac --release 8`. Set its display
+to 720x1600 at density 240 to keep repeated UI hierarchy reads responsive; the
+report records the image, API, display size, density, and Android command timeout.
+The harness builds and signs its own offline fixture. It resets that fixture
+only; no other app data is cleared.
+
+The sequential protocol compares the legacy handle-based public tool flow with
+full/debug and light/compact journeys through a spawned stdio MCP server. Each
+mode has three warm-ups and ten measured runs. Screenshot and screenshot-free
+debug snapshot calls are measured separately. JSON and Markdown reports record
+fixture hash, environment, request sequence, failures, and percentiles. Failed
+runs do not enter percentiles. Raw observations and device serials are not saved.
+See [iOS simulator validation](ios-validation.md) for the interaction checks.
+
+The process exits unsuccessfully on >10% full p95 regression or <30% light p50
+improvement. A failed run is reported and excluded from percentiles as the spec
+requires; inspect its selector and tool or step before accepting the result.