mobile-debug-mcp 0.32.4 → 0.34.0

package/dist/interact/index.js

@@ -1,3 +1,7 @@
+import { checkDebuggerGuard } from '../debugger/guard.js';
+import { currentReadinessWait, observeReadinessWait, isDeviceUnavailable } from '../observe/readiness.js';
+import { readinessDelay } from '../observe/readiness-service.js';
+import { isConditionBlocked } from './conditional-action.js';
 import { remainingBudget } from '../utils/operation-budget.js';
 import { createHash } from 'crypto';
 import { AndroidInteract } from './android.js';
@@ -419,6 +423,8 @@ export class ToolsInteract {
         }
     }
     static async _captureFingerprint(platform, deviceId) {
+        if (isConditionBlocked())
+            return null;
         try {
             const fingerprint = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId });
             return fingerprint?.fingerprint ?? null;
@@ -1907,6 +1913,7 @@ export class ToolsInteract {
                             }
                         }
                         catch (e) {
+                            checkDebuggerGuard();
                             console.error('Error scoring element:', e);
                         }
                     }
@@ -1916,6 +1923,7 @@ export class ToolsInteract {
                 }
             }
             catch (e) {
+                checkDebuggerGuard();
                 console.error('Error fetching UI tree:', e);
             }
             if (shouldStop || Date.now() > deadline)
@@ -2018,6 +2026,7 @@ export class ToolsInteract {
             }
         }
         catch (e) {
+            checkDebuggerGuard();
             console.error('Error resolving ancestor:', e);
         }
         if (!best)
@@ -2068,7 +2077,8 @@ export class ToolsInteract {
         };
         return { found: true, element: outEl, score: scoreVal, confidence: scoreVal, resolution };
     }
-    static async waitForUIHandler({ selector, condition = 'exists', timeout_ms = 60000, poll_interval_ms = 300, match, retry = { max_attempts: 1, backoff_ms: 0 }, platform, deviceId, singleObservation = false, singleAttempt = false, rejectAmbiguous = false }) {
+    static async waitForUIHandler({ selector, condition = 'exists', timeout_ms = 60000, poll_interval_ms = 300, match, retry = { max_attempts: 1, backoff_ms: 0 }, platform, deviceId, singleObservation = false, singleAttempt = false, rejectAmbiguous = false, resolveTapTarget = false }) {
+        const readinessTracker = currentReadinessWait();
         const overallStart = Date.now();
         const requestedIndex = typeof match?.index === 'number' ? match.index : null;
         const requested = {
@@ -2127,7 +2137,12 @@ export class ToolsInteract {
                     remainingBudget();
                     totalPollCount++;
                     try {
+                        const acquisitionStarted = Date.now();
                         const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId });
+                        observeReadinessWait(tree, acquisitionStarted);
+                        // A failed acquisition cannot establish that the requested tap target is absent.
+                        if (resolveTapTarget && tree?.error && /ACTION_TIMEOUT|timed out/i.test(String(tree.error)))
+                            throw new Error('ACTION_TIMEOUT');
                         const elements = (tree && Array.isArray(tree.elements)) ? tree.elements : [];
                         const matches = [];
                         for (let i = 0; i < elements.length; i++) {
@@ -2213,7 +2228,8 @@ export class ToolsInteract {
                                 conditionMet = false;
                         }
                         else if (condition === 'clickable') {
-                            matchedElement = chosen ? (ToolsInteract._resolveActionableAncestor(elements, chosen) || chosen) : null;
+                            matchedElement = chosen ? (resolveTapTarget && (!ToolsInteract._isVisibleElement(chosen.el) || chosen.el.enabled === false)
+                                ? chosen : ToolsInteract._resolveActionableAncestor(elements, chosen) || chosen) : null;
                             if (matchedElement) {
                                 const b = matchedElement.el.bounds;
                                 const visibleFlag = !!matchedElement.el.visible && Array.isArray(b) && b.length >= 4 && (b[2] > b[0] && b[3] > b[1]);
@@ -2224,6 +2240,13 @@ export class ToolsInteract {
                             else
                                 conditionMet = false;
                         }
+                        // Waiting for a label to exist/be visible is distinct from resolving its
+                        // executable control. Reuse the clickable-wait ancestor policy without
+                        // promoting hidden or disabled labels into an unrelated enabled target.
+                        if (resolveTapTarget && conditionMet && matchedElement &&
+                            ToolsInteract._isVisibleElement(matchedElement.el) && matchedElement.el.enabled !== false) {
+                            matchedElement = ToolsInteract._resolveActionableAncestor(elements, matchedElement) ?? matchedElement;
+                        }
                         const resolvedPlatform = tree?.device?.platform === 'ios' ? 'ios' : (platform || 'android');
                         const resolvedDeviceId = tree?.device?.id || deviceId;
                         lastMatchedCount = matchedCount;
@@ -2236,7 +2259,7 @@ export class ToolsInteract {
                             if (matchedAt === null)
                                 matchedAt = now;
                             stableMatchCount++;
-                            if (stableMatchCount >= stableObservationCount) {
+                            if (stableMatchCount >= stableObservationCount && (!readinessTracker || readinessTracker.summary.state === 'settled')) {
                                 const latency_ms = now - overallStart;
                                 const outEl = lastMatchedElement;
                                 return {
@@ -2261,20 +2284,27 @@ export class ToolsInteract {
                         }
                     }
                     catch (e) {
+                        checkDebuggerGuard();
+                        // Deadline expiry does not invalidate the last successfully observed state.
                         if (e instanceof Error && e.message === 'ACTION_TIMEOUT')
                             throw e;
+                        if (readinessTracker && !String(e).includes('READINESS_'))
+                            readinessTracker.unavailable();
+                        if (readinessTracker && isDeviceUnavailable(e))
+                            throw e;
                         // Non-fatal per-poll error; record and continue
-                        console.warn('waitForUI: poll error (non-fatal):', e instanceof Error ? e.message : String(e));
+                        if (!readinessTracker)
+                            console.warn('waitForUI: poll error (non-fatal):', e instanceof Error ? e.message : String(e));
                     }
                     if (singleAttempt)
                         break;
                     // Sleep until next poll
-                    await new Promise(r => setTimeout(r, effectivePoll || 50));
+                    await (readinessTracker ? readinessDelay(effectivePoll || 50) : new Promise(r => setTimeout(r, effectivePoll || 50)));
                 }
                 // Attempt timed out; if more attempts allowed, backoff then retry
                 if (attempts < maxAttempts) {
                     if (backoff > 0)
-                        await new Promise(r => setTimeout(r, backoff));
+                        await (readinessTracker ? readinessDelay(backoff) : new Promise(r => setTimeout(r, backoff)));
                     continue;
                 }
                 // Final failure for this call
@@ -2290,7 +2320,7 @@ export class ToolsInteract {
                     : ` observed ${lastMatchedCount} match(es)`;
                 return {
                     status: 'timeout',
-                    error: { code: 'ELEMENT_NOT_FOUND', message: `Condition ${condition} not satisfied within timeout;${matchNote}` },
+                    error: { code: readinessTracker ? 'TIMEOUT' : 'ELEMENT_NOT_FOUND', message: `Condition ${condition} not satisfied within timeout;${matchNote}` },
                     metrics: { latency_ms: elapsed, poll_count: totalPollCount, attempts },
                     requested,
                     observed
@@ -2298,17 +2328,20 @@ export class ToolsInteract {
             }
         }
         catch (err) {
-            if (err instanceof Error && err.message === 'ACTION_TIMEOUT')
+            checkDebuggerGuard();
+            if (!readinessTracker && err instanceof Error && err.message === 'ACTION_TIMEOUT')
+                throw err;
+            if (readinessTracker && isDeviceUnavailable(err))
                 throw err;
             const elapsed = Date.now() - overallStart;
             return {
                 status: 'timeout',
-                error: { code: 'INTERNAL_ERROR', message: err instanceof Error ? err.message : String(err) },
+                error: { code: readinessTracker && String(err).includes('ACTION_TIMEOUT') ? 'TIMEOUT' : 'INTERNAL_ERROR', message: readinessTracker ? 'Readiness predicate wait did not complete' : err instanceof Error ? err.message : String(err) },
                 metrics: { latency_ms: elapsed, poll_count: totalPollCount, attempts },
                 requested,
                 observed: {
                     matched_count: lastMatchedCount,
-                    condition_satisfied: false,
+                    condition_satisfied: readinessTracker ? lastConditionSatisfied : false,
                     selected_index: lastMatchedElement?.index ?? null,
                     last_matched_element: lastMatchedElement
                 }
@@ -2370,12 +2403,14 @@ export class ToolsInteract {
                         continue;
                     }
                     catch (e) {
+                        checkDebuggerGuard();
                         console.error('Error confirming fingerprint:', e);
                         continue;
                     }
                 }
             }
             catch (e) {
+                checkDebuggerGuard();
                 console.error('Error getting screen fingerprint:', e);
             }
             await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
@@ -2393,6 +2428,7 @@ export class ToolsInteract {
         };
     }
     static async waitForUIChangeHandler({ platform, deviceId, timeout_ms = 60000, stability_window_ms = 300, expected_change, scope = 'screen', target = null }) {
+        const readinessTracker = currentReadinessWait();
         const start = Date.now();
         const pollIntervalMs = 300;
         const stabilityWindow = Math.max(0, typeof stability_window_ms === 'number' ? stability_window_ms : 300);
@@ -2415,7 +2451,11 @@ export class ToolsInteract {
         };
         while (Date.now() - start < timeout_ms) {
             try {
+                if (readinessTracker)
+                    remainingBudget();
+                const acquisitionStarted = Date.now();
                 const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId });
+                observeReadinessWait(tree, acquisitionStarted);
                 const scopedTree = ToolsInteract._resolveUiChangeScope(tree, scope, target);
                 if (scopedTree.error) {
                     lastScopeResolution = scopedTree.resolution;
@@ -2461,7 +2501,7 @@ export class ToolsInteract {
                             candidateSinceMs = Date.now();
                         }
                         const stableForMs = candidateSinceMs === null ? 0 : Date.now() - candidateSinceMs;
-                        if (stabilityWindow === 0 || stableForMs >= stabilityWindow) {
+                        if ((stabilityWindow === 0 || stableForMs >= stabilityWindow) && (!readinessTracker || readinessTracker.summary.state === 'settled')) {
                             return {
                                 success: true,
                                 observed_change: candidateObservedChange ?? observedChange,
@@ -2486,10 +2526,19 @@ export class ToolsInteract {
                     }
                 }
             }
-            catch {
-                // Keep polling until timeout; the observable surface should be best-effort.
+            catch (error) {
+                checkDebuggerGuard();
+                if (readinessTracker && !String(error).includes('READINESS_'))
+                    readinessTracker.unavailable();
+                if (readinessTracker && isDeviceUnavailable(error))
+                    throw error;
+                if (readinessTracker && String(error).includes('ACTION_TIMEOUT')) {
+                    readinessTracker.deadline();
+                    break;
+                }
+                // Default waits retain best-effort polling.
             }
-            await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+            await (readinessTracker ? readinessDelay(pollIntervalMs) : new Promise(resolve => setTimeout(resolve, pollIntervalMs)));
         }
         return {
             success: false,
@@ -2999,6 +3048,7 @@ export class ToolsInteract {
             }
         }
         catch (err) {
+            checkDebuggerGuard();
             try {
                 console.warn('waitForUI: failed to get baseline data (non-fatal):', err instanceof Error ? err.message : String(err));
             }
@@ -3053,10 +3103,12 @@ export class ToolsInteract {
                         }
                     }
                     catch (err) {
+                        checkDebuggerGuard();
                         console.error('waitForUI(ui) find error:', err);
                     }
                 }
                 catch (err) {
+                    checkDebuggerGuard();
                     console.error('waitForUI(ui) outer error:', err);
                 }
             }
@@ -3090,6 +3142,7 @@ export class ToolsInteract {
                     }
                 }
                 catch (err) {
+                    checkDebuggerGuard();
                     console.error('waitForUI(log) error:', err);
                 }
             }
@@ -3118,6 +3171,7 @@ export class ToolsInteract {
                     }
                 }
                 catch (err) {
+                    checkDebuggerGuard();
                     console.error('waitForUI(screen) error:', err);
                 }
             }
@@ -3142,6 +3196,7 @@ export class ToolsInteract {
                     }
                 }
                 catch (err) {
+                    checkDebuggerGuard();
                     console.error('waitForUI(idle) error:', err);
                 }
             }
@@ -3159,6 +3214,7 @@ export class ToolsInteract {
                 snapshot = await Obs.ToolsObserve.captureDebugSnapshotHandler({ reason: `wait_for_ui timeout for ${type}`, includeLogs: true, platform, deviceId });
             }
             catch (err) {
+                checkDebuggerGuard();
                 snapshot = { error: err instanceof Error ? err.message : String(err) };
             }
         }

package/dist/interact/ios.js

@@ -1,3 +1,5 @@
+import { evidenceDispatch } from '../observe/evidence.js';
+import { beforeInputDispatch } from './conditional-action.js';
 import { remainingBudget, markDispatchStarted } from '../utils/operation-budget.js';
 import { spawn } from "child_process";
 import { getIOSDeviceMetadata, getIdbCmd, isIDBInstalled } from "../utils/ios/utils.js";
@@ -24,9 +26,11 @@ export class iOSInteract {
             if (targetUdid) {
                 args.push('--udid', targetUdid);
             }
-            await new Promise((resolve, reject) => {
-                markDispatchStarted();
-                const proc = spawn(getIdbCmd(), args, { timeout: remainingBudget() || undefined });
+            await beforeInputDispatch('ios', device.id);
+            const timeout = remainingBudget() || undefined;
+            markDispatchStarted();
+            await evidenceDispatch({ platform: 'ios', id: device.id }, () => new Promise((resolve, reject) => {
+                const proc = spawn(getIdbCmd(), args, { timeout });
                 let stderr = '';
                 proc.stderr.on('data', d => stderr += d.toString());
                 proc.on('close', code => {
@@ -36,7 +40,7 @@ export class iOSInteract {
                         reject(new Error(`idb ui tap failed: ${stderr}`));
                 });
                 proc.on('error', err => reject(err));
-            });
+            }));
             return { device, success: true, x, y };
         }
         catch (e) {
@@ -64,9 +68,11 @@ export class iOSInteract {
             if (targetUdid) {
                 args.push('--udid', targetUdid);
             }
-            await new Promise((resolve, reject) => {
-                markDispatchStarted();
-                const proc = spawn(getIdbCmd(), args, { timeout: remainingBudget() || undefined });
+            await beforeInputDispatch('ios', device.id);
+            const timeout = remainingBudget() || undefined;
+            markDispatchStarted();
+            await evidenceDispatch({ platform: 'ios', id: device.id }, () => new Promise((resolve, reject) => {
+                const proc = spawn(getIdbCmd(), args, { timeout });
                 let stderr = '';
                 proc.stderr.on('data', d => stderr += d.toString());
                 proc.on('close', code => {
@@ -76,7 +82,7 @@ export class iOSInteract {
                         reject(new Error(`idb ui swipe failed: ${stderr}`));
                 });
                 proc.on('error', err => reject(err));
-            });
+            }));
             return { device, success: true, start: [x1, y1], end: [x2, y2], duration };
         }
         catch (e) {

package/dist/manage/android.js

@@ -1,3 +1,4 @@
+import { evidenceDispatch } from '../observe/evidence.js';
 import { hasFiniteBudget, markDispatchStarted, remainingBudget, runWithBudget } from '../utils/operation-budget.js';
 import { promises as fs } from 'fs';
 import { spawn } from 'child_process';
@@ -152,7 +153,7 @@ export class AndroidManage {
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
         try {
             markDispatchStarted();
-            const output = await execAdb(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId, { timeout: timeoutMs });
+            const output = await evidenceDispatch({ platform: 'android', id: deviceInfo.id }, () => execAdb(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId, { timeout: timeoutMs }));
             const current = await new AndroidObserve().getCurrentScreen(deviceId).catch(() => null);
             return {
                 device: deviceInfo,
@@ -178,7 +179,7 @@ export class AndroidManage {
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
         try {
             markDispatchStarted();
-            await execAdb(['shell', 'am', 'force-stop', appId], deviceId);
+            await evidenceDispatch({ platform: 'android', id: deviceInfo.id }, () => execAdb(['shell', 'am', 'force-stop', appId], deviceId));
             return { device: deviceInfo, appTerminated: true };
         }
         catch (e) {
@@ -211,7 +212,7 @@ export class AndroidManage {
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
         try {
             markDispatchStarted();
-            const output = await execAdb(['shell', 'pm', 'clear', appId], deviceId);
+            const output = await evidenceDispatch({ platform: 'android', id: deviceInfo.id }, () => execAdb(['shell', 'pm', 'clear', appId], deviceId));
             return { device: deviceInfo, dataCleared: output === 'Success' };
         }
         catch (e) {

package/dist/manage/ios.js

@@ -1,3 +1,4 @@
+import { evidenceDispatch } from '../observe/evidence.js';
 import { hasFiniteBudget, markDispatchStarted, remainingBudget, runWithBudget } from '../utils/operation-budget.js';
 import { promises as fs } from "fs";
 import { spawn, spawnSync } from "child_process";
@@ -293,7 +294,7 @@ export class iOSManage {
         validateBundleId(bundleId);
         try {
             markDispatchStarted();
-            const result = await execCommand(['simctl', 'launch', deviceId, bundleId], deviceId);
+            const result = await evidenceDispatch({ platform: 'ios', id: deviceId }, () => execCommand(['simctl', 'launch', deviceId, bundleId], deviceId));
             const device = await getIOSDeviceMetadata(deviceId);
             const fingerprint = observe ? await new iOSObserve().getScreenFingerprint(deviceId).catch(() => null) : null;
             const pidMatch = result.output.match(/:\s*(\d+)\s*$/);
@@ -320,7 +321,7 @@ export class iOSManage {
         validateBundleId(bundleId);
         try {
             markDispatchStarted();
-            await execCommand(['simctl', 'terminate', deviceId, bundleId], deviceId);
+            await evidenceDispatch({ platform: 'ios', id: deviceId }, () => execCommand(['simctl', 'terminate', deviceId, bundleId], deviceId));
             const device = await getIOSDeviceMetadata(deviceId);
             return { device, appTerminated: true };
         }

package/dist/observe/android.js

@@ -1,3 +1,4 @@
+import { captureEvidence } from './evidence.js';
 import { spawn } from "child_process";
 import { XMLParser } from "fast-xml-parser";
 import { getAdbCmd, execAdb, getAndroidDeviceMetadata, getDeviceInfo, delay, getScreenResolution, traverseNode, parseLogLine } from "../utils/android/utils.js";
@@ -11,10 +12,14 @@ import { remainingBudget } from '../utils/operation-budget.js';
 import { createObservationMeasurement } from './performance-metrics.js';
 const activeLogStreams = new Map();
 export class AndroidObserve {
+    getLogStreamDevice(sessionId = 'default') { return activeLogStreams.get(sessionId)?.device ?? null; }
     async getDeviceMetadata(appId, deviceId) {
         return getAndroidDeviceMetadata(appId, deviceId);
     }
     async getUITree(deviceId) {
+        return captureEvidence('ui_tree', { platform: 'android', id: deviceId ?? '' }, () => this.collectGetUITree(deviceId));
+    }
+    async collectGetUITree(deviceId) {
         const measurement = createObservationMeasurement('android');
         let metadata;
         try {
@@ -113,6 +118,9 @@ export class AndroidObserve {
         }
     }
     async getLogs(filters = {}) {
+        return captureEvidence('logs', { platform: 'android', id: filters.deviceId ?? '' }, () => this.collectGetLogs(filters));
+    }
+    async collectGetLogs(filters = {}) {
         const { appId, deviceId, pid, tag, level, contains, since_seconds, limit } = filters;
         const metadata = await getAndroidDeviceMetadata(appId || "", deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
@@ -213,6 +221,9 @@ export class AndroidObserve {
         }
     }
     async captureScreen(deviceId) {
+        return captureEvidence('screenshot', { platform: 'android', id: deviceId ?? '' }, () => this.collectCaptureScreen(deviceId));
+    }
+    async collectCaptureScreen(deviceId) {
         const metadata = await getAndroidDeviceMetadata("", deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
         return new Promise((resolve, reject) => {
@@ -331,6 +342,9 @@ export class AndroidObserve {
         });
     }
     async getCurrentScreen(deviceId) {
+        return captureEvidence('activity', { platform: 'android', id: deviceId ?? '' }, () => this.collectGetCurrentScreen(deviceId));
+    }
+    async collectGetCurrentScreen(deviceId) {
         const metadata = await getAndroidDeviceMetadata("", deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
         try {
@@ -385,12 +399,15 @@ export class AndroidObserve {
         }
     }
     async getScreenFingerprint(deviceId) {
+        return captureEvidence('fingerprint', { platform: 'android', id: deviceId ?? '' }, () => this.collectGetScreenFingerprint(deviceId));
+    }
+    async collectGetScreenFingerprint(deviceId) {
         try {
             const tree = await this.getUITree(deviceId);
             if (!tree || tree.error)
                 return { fingerprint: null, error: tree.error };
             const current = await this.getCurrentScreen(deviceId).catch(() => null);
-            return computeScreenFingerprint(tree, current, 'android', 50);
+            return { ...computeScreenFingerprint(tree, current, 'android', 50), captured_at_ms: tree.captured_at_ms };
         }
         catch (e) {
             return { fingerprint: null, error: e instanceof Error ? e.message : String(e) };
@@ -411,7 +428,7 @@ export class AndroidObserve {
                 catch { }
                 activeLogStreams.delete(sessionId);
             }
-            const args = ['logcat', `--pid=${pid}`, filter];
+            const args = [...(deviceId ? ['-s', deviceId] : []), 'logcat', `--pid=${pid}`, filter];
             const proc = spawn(getAdbCmd(), args);
             const tmpDir = process.env.TMPDIR || '/tmp';
             const file = path.join(tmpDir, `mobile-debug-log-${sessionId}.ndjson`);
@@ -434,9 +451,10 @@ export class AndroidObserve {
             });
             proc.on('close', () => {
                 stream.end();
-                activeLogStreams.delete(sessionId);
+                if (activeLogStreams.get(sessionId)?.proc === proc)
+                    activeLogStreams.delete(sessionId);
             });
-            activeLogStreams.set(sessionId, { proc, file });
+            activeLogStreams.set(sessionId, { proc, file, device: { platform: 'android', id: deviceId ?? '' } });
             return { success: true, stream_started: true };
         }
         catch (e) {
@@ -455,6 +473,9 @@ export class AndroidObserve {
         return { success: true };
     }
     async readLogStream(sessionId = 'default', limit = 100, since) {
+        return captureEvidence('logs', this.getLogStreamDevice(sessionId), () => this.collectReadLogStream(sessionId, limit, since));
+    }
+    async collectReadLogStream(sessionId = 'default', limit = 100, since) {
         const entry = activeLogStreams.get(sessionId);
         let file;
         if (entry && entry.file)