mobile-debug-mcp 0.30.2 → 0.32.0

package/dist/utils/cli/idb/idb-helper.js

@@ -71,21 +71,55 @@ export function getIdbCmd() {
     }
     return null;
 }
-export function isIDBInstalled() {
-    const cmd = getIdbCmd();
+export function getIdbPackageVersion() {
+    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()) {
     if (!cmd)
-        return false;
+        return { ok: false, raw: null, parsedVersion: null };
     try {
-        // command -v <cmd>
-        const r = spawnSync('command', ['-v', cmd], { stdio: ['ignore', 'pipe', 'ignore'] });
-        if (r && r.status === 0)
-            return true;
+        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 { }
-    try {
-        execSync(`${cmd} list-targets --json`, { stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000 });
-        return true;
+    catch {
+        return { ok: false, raw: null, parsedVersion: null };
     }
-    catch { }
-    return false;
+}
+export function isIDBInstalled() {
+    return probeIdb().ok;
 }

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 = '';
@@ -16,7 +18,7 @@ export async function execCmd(cmd, args, opts = {}) {
                 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) => {
             if (timer)

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';
@@ -71,19 +72,15 @@ export function getIdbCmd() {
 }
 export async function isIDBInstalled() {
     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) {
-        try {
-            execSync(`${cmd} list-targets --json`, { stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000 });
-            return true;
-        }
-        catch (e2) {
-            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;
     }
 }
 // Validate bundle ID to prevent any potential injection or invalid characters
@@ -98,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 = '';
@@ -113,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(' ')}`));
@@ -134,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.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
+
 ## [0.30.2]
 - improved slider interaction
 

package/docs/ROADMAP.md

@@ -9,12 +9,12 @@
 - Action Trace and Execution Observability
 - Wait and Synchronization Reliability
 - Actionability Resolution
+- Environment Auto-Configuration and Toolchain Discovery
+- Adjustable Control Support
 
 ## Todo
 
-- Adjustable Control Support
 - Adjustable Control Precision Hardening
-- Environment Auto-Configuration and Toolchain Discovery
 - Signal-Oriented Diagnostic Filtering
 - Long Press Gesture
 - Runtime Debugger Introspection
@@ -205,7 +205,7 @@ Strengthens:
 ## Rationale
 Reduces failures caused by interacting with discoverable but non-actionable UI nodes.
 
-**Status:** Planned
+**Status:** Completed
 
 Addresses cases where:
 - visible text is not the true click target
@@ -251,7 +251,7 @@ Blocks or strengthens:
 ## Rationale
 High leverage improvement for sliders and parameterized controls.
 
-**Status:** Planned
+**Status:** Completed
 
 Addresses friction around:
 - coordinate-calibrated slider interaction

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.