mobile-debug-mcp 0.31.0 → 0.32.0

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,9 @@
 
 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
 

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.