mobile-debug-mcp 0.32.0 → 0.32.2

package/dist/server/tool-handlers.js

@@ -9,6 +9,7 @@ import { ToolsObserve } from '../observe/index.js';
 import { classifyActionOutcome } from '../interact/classify.js';
 import { ToolsNetwork } from '../network/index.js';
 import { getSystemStatus } from '../system/index.js';
+import { recordObservationConsumer, recordObservationEvent, withObservationContext } from '../observe/performance-metrics.js';
 import { buildActionExecutionResult, captureActionFingerprint, getArrayArg, getBooleanArg, getNumberArg, getObjectArg, getStringArg, inferGenericFailure, inferScrollFailure, requireBooleanArg, requireNumberArg, requireObjectArg, requireStringArg, wrapResponse, wrapToolError } from './common.js';
 function interactionControls(args) {
     const verificationMode = getStringArg(args, 'verificationMode') ?? 'full';
@@ -79,11 +80,25 @@ function actionHandler(type, execute) {
                 result.retryable = !dispatchStarted;
             result.action_id ??= randomUUID();
             result.action_type ??= type;
+            recordObservationEvent({
+                step_id: args._stepId,
+                action_type: type,
+                dispatch_ms: timing.dispatch_ms,
+                verification_mode: controls.verificationMode,
+                dispatch_started: dispatchStarted
+            });
             let delta;
             let observationAvailable = false;
             if (result.success && controls.verificationMode === 'light') {
-                const tree = await measure('post_observation_ms', () => runWithBudget(controls.verificationTimeoutMs, () => ToolsObserve.getUITreeHandler({ platform: args.platform ?? result.device?.platform, deviceId: args.deviceId ?? result.device?.id }))).catch(() => null);
+                const verificationStarted = performance.now();
+                const tree = await withObservationContext({ stepId: args._stepId, purpose: 'verification' }, () => measure('post_observation_ms', () => runWithBudget(controls.verificationTimeoutMs, () => ToolsObserve.getUITreeHandler({ platform: args.platform ?? result.device?.platform, deviceId: args.deviceId ?? result.device?.id })))).catch(() => null);
                 observationAvailable = !!tree && !tree.error;
+                recordObservationEvent({
+                    verification_budget_ms: controls.verificationTimeoutMs,
+                    verification_elapsed_ms: performance.now() - verificationStarted,
+                    verification_outcome: observationAvailable ? 'observed' : 'unavailable',
+                    verification_budget_expired: !observationAvailable && performance.now() - verificationStarted >= controls.verificationTimeoutMs
+                });
                 if (observationAvailable && tree.device)
                     delta = ToolsObserve.getLatestStateDelta(tree.device.platform, tree.device.id) ?? undefined;
             }
@@ -286,7 +301,8 @@ async function handleGetUITree(args) {
     const deviceId = getStringArg(args, 'deviceId');
     const responseMode = getStringArg(args, 'responseMode') ?? 'debug';
     const sinceSnapshotRevision = getNumberArg(args, 'sinceSnapshotRevision');
-    const res = await ToolsObserve.getUITreeHandler({ platform, deviceId, responseMode, sinceSnapshotRevision });
+    const metricsStepId = process.env.MOBILE_DEBUG_MCP_UI_TREE_METRICS === '1' ? getStringArg(args, '_metricsStepId') : undefined;
+    const res = await withObservationContext({ stepId: metricsStepId, purpose: metricsStepId?.includes('post-response') ? 'assertion' : 'debug' }, () => ToolsObserve.getUITreeHandler({ platform, deviceId, responseMode, sinceSnapshotRevision }));
     return wrapResponse(res);
 }
 async function handleGetCurrentScreen(args) {
@@ -396,7 +412,9 @@ async function handleFindElement(args) {
     const timeoutMs = getNumberArg(args, 'timeoutMs') ?? 3000;
     const platform = getStringArg(args, 'platform');
     const deviceId = getStringArg(args, 'deviceId');
-    const res = await ToolsInteract.findElementHandler({ query, exact, timeoutMs, platform, deviceId });
+    const targetStarted = performance.now();
+    const res = await withObservationContext({ purpose: 'target' }, () => ToolsInteract.findElementHandler({ query, exact, timeoutMs, platform, deviceId }));
+    recordObservationEvent({ target_resolution_ms: performance.now() - targetStarted, target_resolution_outcome: res.found ? 'found' : 'not_found', operation: 'find_element' });
     return wrapResponse(res);
 }
 async function executeTap(args) {
@@ -431,13 +449,17 @@ async function executeTapElement(args) {
     let freshTree;
     if (selector) {
         const waitFor = getObjectArg(args, 'waitFor');
-        const resolution = await measure('target_resolution_ms', () => runWithBudget(waitFor?.timeoutMs ?? 1500, () => ToolsInteract.waitForUIHandler({ selector, condition: waitFor?.condition ?? 'clickable', timeout_ms: waitFor?.timeoutMs ?? 1500, poll_interval_ms: waitFor?.pollIntervalMs ?? 100, match: waitFor?.match, singleObservation: true, singleAttempt: !waitFor, rejectAmbiguous: !waitFor, platform: getStringArg(args, 'platform'), deviceId: getStringArg(args, 'deviceId') })));
+        const targetStarted = performance.now();
+        const resolution = await withObservationContext({ stepId: args._stepId, purpose: 'target' }, () => measure('target_resolution_ms', () => runWithBudget(waitFor?.timeoutMs ?? 1500, () => ToolsInteract.waitForUIHandler({ selector, condition: waitFor?.condition ?? 'clickable', timeout_ms: waitFor?.timeoutMs ?? 1500, poll_interval_ms: waitFor?.pollIntervalMs ?? 100, match: waitFor?.match, singleObservation: true, singleAttempt: !waitFor, rejectAmbiguous: !waitFor, platform: getStringArg(args, 'platform'), deviceId: getStringArg(args, 'deviceId') }))));
+        recordObservationEvent({ step_id: args._stepId, purpose: 'target', target_resolution_ms: performance.now() - targetStarted, target_resolution_outcome: resolution.status });
         if (resolution.status !== 'success' || !resolution.element?.elementId)
             return wrapResponse({ success: false, action_type: 'tap_element', failure_code: resolution.error?.code ?? 'ELEMENT_NOT_FOUND', retryable: true });
         resolvedId = resolution.element.elementId;
         freshTree = resolution._tree;
     }
     ToolsNetwork.notifyActionStart();
+    if (freshTree)
+        recordObservationConsumer(freshTree, 'target', args._stepId);
     const res = await measure('dispatch_ms', () => ToolsInteract.tapElementHandler({ elementId: resolvedId, freshTree, verificationMode, timeoutMs: actionTimeoutMs, platform: getStringArg(args, 'platform'), deviceId: getStringArg(args, 'deviceId') }));
     return wrapResponse(res);
 }
@@ -505,14 +527,14 @@ async function handleRunJourney(args) {
             }
             try {
                 if (step.type === 'tap') {
-                    result = payloadOf(await handleTapElement({ ...defaults, ...step, platform, deviceId, responseMode, _journey: true, verificationMode: lightCoveredByAssertion ? 'none' : requestedVerification }));
+                    result = payloadOf(await handleTapElement({ ...defaults, ...step, platform, deviceId, responseMode, _journey: true, _stepId: step.id, verificationMode: lightCoveredByAssertion ? 'none' : requestedVerification }));
                 }
                 else if (step.type === 'wait') {
-                    result = await ToolsInteract.waitForUIHandler({ selector: step.selector, condition: step.condition ?? 'exists', timeout_ms: step.timeoutMs ?? 5000, poll_interval_ms: step.pollIntervalMs ?? 100, platform, deviceId });
+                    result = await withObservationContext({ stepId: step.id, purpose: 'target' }, () => ToolsInteract.waitForUIHandler({ selector: step.selector, condition: step.condition ?? 'exists', timeout_ms: step.timeoutMs ?? 5000, poll_interval_ms: step.pollIntervalMs ?? 100, platform, deviceId }));
                     result = { success: result.status === 'success', ...result };
                 }
                 else if (step.type === 'assert') {
-                    result = await runWithBudget(step.timeoutMs ?? 5000, async () => {
+                    result = await withObservationContext({ stepId: step.id, purpose: 'assertion' }, () => runWithBudget(step.timeoutMs ?? 5000, async () => {
                         const assertion = step.assertion;
                         if (assertion?.kind === 'element_visible')
                             result = await ToolsInteract.expectElementVisibleHandler({ selector: assertion.selector, timeout_ms: step.timeoutMs ?? 5000, poll_interval_ms: step.pollIntervalMs ?? 100, platform, deviceId });
@@ -525,10 +547,10 @@ async function handleRunJourney(args) {
                         else
                             result = { success: false, failure_code: 'INVALID_ASSERTION' };
                         return result;
-                    });
+                    }));
                 }
                 else if (step.type === 'start_app') {
-                    result = payloadOf(await handleStartApp({ ...defaults, platform, deviceId, appId: step.appId, responseMode, _journey: true, verificationMode: step.verificationMode ?? defaults?.verificationMode ?? 'full' }));
+                    result = payloadOf(await handleStartApp({ ...defaults, platform, deviceId, appId: step.appId, responseMode, _journey: true, _stepId: step.id, verificationMode: step.verificationMode ?? defaults?.verificationMode ?? 'full' }));
                 }
                 else {
                     result = { success: false, failure_code: 'UNSUPPORTED_JOURNEY_STEP' };

package/dist/server-core.js

@@ -6,7 +6,7 @@ import { handleToolCall } from './server/tool-handlers.js';
 export { wrapResponse, toolDefinitions, handleToolCall };
 export const serverInfo = {
     name: 'mobile-debug-mcp',
-    version: '0.32.0'
+    version: '0.32.2'
 };
 export function createServer() {
     const server = new Server(serverInfo, {

package/dist/utils/exec.js

@@ -12,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: 'ACTION_TIMEOUT' });
+            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/docs/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.32.2]
+- bug fix
+
+## [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.
 

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/ui-tree-performance/README.md

@@ -0,0 +1,58 @@
+# UI tree observation performance benchmark
+
+This paired Android benchmark compares a clean, built instrumentation baseline
+with a clean, built candidate. It runs the Spec 018 static journey and a local
+network-backed loading-to-ready flow against the same fixture APK and emulator.
+The network flow asserts a run-unique value from a physical tree read that
+started after the local server sent its response.
+
+Capture the instrumented baseline first from a clean, built baseline checkout:
+
+```sh
+UI_TREE_BASELINE_ROOT=/path/to/instrumented-baseline \
+LATENCY_DEVICE_ID=emulator-5554 \
+npx tsx test/device/automated/ui-tree-performance/benchmark.ts --baseline-only
+```
+
+This writes `baseline.json`. After measuring and implementing an optimization,
+run the paired comparison from the clean, built candidate checkout:
+
+```sh
+UI_TREE_BASELINE_ROOT=/path/to/instrumented-baseline \
+UI_TREE_CANDIDATE_ROOT=/path/to/optimized-candidate \
+LATENCY_DEVICE_ID=emulator-5554 \
+npx tsx test/device/automated/ui-tree-performance/benchmark.ts
+```
+
+Add `--smoke --baseline-only` for one attempt per flow while checking the
+fixture and emulator connection. Smoke mode writes no performance report and
+does not satisfy the sample-count or acceptance gates.
+
+Both input checkouts must contain `dist/server.js` and have clean Git working
+trees. The harness checks both before installing or resetting the fixture. It
+builds one APK from the candidate fixture and uses that exact APK in both modes.
+Each flow and mode receives three warm-ups and ten measured attempts; baseline
+and candidate order alternates by pair.
+
+The paired run writes `baseline.json`, `candidate.json`, `comparison.json`, and
+`comparison.md` here. Timing events are enabled only in the spawned benchmark
+servers through `MOBILE_DEBUG_MCP_UI_TREE_METRICS=1`; normal MCP responses do
+not gain timing fields. Events contain timings, platform, generated journey step
+IDs, and opaque acquisition IDs. They omit UI contents, app identifiers,
+screenshots, logs, payloads, and device serials. iOS latency remains unmeasured.
+
+The checked-in `initial-baseline.json` is the standalone capture taken before
+the optimization. The checked-in `baseline.json` is the baseline side of the
+paired run, so it shares the fixture APK hash with `candidate.json`.
+`comparison-attempt-1.json` retains an earlier paired run with two visible
+network failures; see `comparison.md` for the outcome and limitation.
+The report commit SHAs are available locally as `codex/spec-019-baseline` and
+`codex/spec-019-candidate`; create clean, built checkouts of those refs to
+reproduce the paired measurement.
+
+For the opt-in Android bridge, run
+`LATENCY_DEVICE_ID=emulator-5554 node --import tsx test/device/automated/ui-tree-performance/bridge-probe.ts`.
+Its `bridge-probe.json` compares ten bridge and legacy reads, checks a network
+update, and checks a timer that changes visually without emitting an
+accessibility event. The timer check catches a stale accessibility cache even
+when every bridge request calls `getRootInActiveWindow()`.