mobile-debug-mcp 0.18.0 → 0.19.1

package/dist/interact/index.js

@@ -3,6 +3,7 @@ import { iOSInteract } from './ios.js';
 export { AndroidInteract, iOSInteract };
 import { resolveTargetDevice } from '../utils/resolve-device.js';
 import { ToolsObserve } from '../observe/index.js';
+const STABLE_IDLE_MS = 1000;
 export class ToolsInteract {
     static async getInteractionService(platform, deviceId) {
         const effectivePlatform = platform || 'android';
@@ -258,4 +259,167 @@ export class ToolsInteract {
         }
         return { success: false, reason: 'timeout', lastFingerprint, elapsedMs: Date.now() - start };
     }
+    static async observeUntilHandler({ type, query, timeoutMs = 5000, pollIntervalMs = 200, platform, deviceId }) {
+        const start = Date.now();
+        const deadline = start + (timeoutMs || 0);
+        const q = (query === null || query === undefined) ? '' : String(query);
+        // Baseline state
+        let initialFingerprint = null;
+        try {
+            const fpRes = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId });
+            initialFingerprint = fpRes?.fingerprint ?? null;
+        }
+        catch (err) {
+            console.error('observeUntil: error getting initial fingerprint', err);
+            initialFingerprint = null;
+        }
+        // For logs, capture a baseline snapshot (count or last line) to avoid matching historical lines
+        let baselineLastLine = null;
+        try {
+            const gl = await ToolsObserve.getLogsHandler({ platform, deviceId, lines: 200 });
+            const logsArr = Array.isArray(gl.logs) ? gl.logs : [];
+            baselineLastLine = logsArr.length ? logsArr[logsArr.length - 1] : null;
+        }
+        catch (err) {
+            // non-fatal but surface warning to aid debugging
+            try {
+                console.warn('observeUntil: failed to get baseline logs (non-fatal):', err instanceof Error ? err.message : String(err));
+            }
+            catch { }
+        }
+        let lastChangeAt = Date.now();
+        let prevFingerprint = initialFingerprint;
+        const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+        // Telemetry
+        let pollCount = 0;
+        let timeToMatch = null;
+        let matchSource = null;
+        while (Date.now() <= deadline) {
+            pollCount++;
+            try {
+                if (type === 'ui') {
+                    // fast findElement with short timeout to avoid blocking
+                    try {
+                        const found = await ToolsInteract.findElementHandler({ query: q, exact: false, timeoutMs: Math.min(500, timeoutMs || 500), platform, deviceId });
+                        if (found && found.found) {
+                            timeToMatch = Date.now() - start;
+                            // determine matchSource heuristics
+                            const el = found.element || {};
+                            if (el && el.resourceId && String(el.resourceId).toLowerCase().includes(q.toLowerCase()))
+                                matchSource = 'ui-resourceId';
+                            else if (el && el.text && String(el.text).toLowerCase() === q.toLowerCase())
+                                matchSource = 'ui-exact';
+                            else
+                                matchSource = 'ui-partial';
+                            return { success: true, type: 'ui', matched: true, details: `UI element matched '${q}'`, timestamp: Date.now(), element: found.element, telemetry: { pollCount, timeToMatch, elapsedMs: Date.now() - start, matchSource } };
+                        }
+                    }
+                    catch (err) {
+                        console.error('observeUntil(ui) find error:', err);
+                    }
+                }
+                else if (type === 'log') {
+                    try {
+                        // Try reading from active stream first
+                        const stream = await ToolsObserve.readLogStreamHandler({ platform, sessionId: 'default', limit: 200 });
+                        const entries = (stream && Array.isArray(stream.entries)) ? stream.entries : [];
+                        for (const ent of entries) {
+                            const msg = ent && (ent.message || ent.msg || ent) ? (ent.message || ent.msg || ent) : '';
+                            if (q && String(msg).includes(q)) {
+                                timeToMatch = Date.now() - start;
+                                matchSource = 'log-stream';
+                                return { success: true, type: 'log', matched: true, details: `Log matched '${q}'`, timestamp: Date.now(), log: { message: msg, raw: ent }, telemetry: { pollCount, timeToMatch, elapsedMs: Date.now() - start, matchSource } };
+                            }
+                        }
+                        // Fallback to snapshot logs
+                        const gl = await ToolsObserve.getLogsHandler({ platform, deviceId, lines: 200 });
+                        const logsArr = Array.isArray(gl && gl.logs) ? gl.logs : [];
+                        // Only consider new lines after baselineLastLine when possible
+                        let startIndex = 0;
+                        if (baselineLastLine) {
+                            const idx = logsArr.lastIndexOf(baselineLastLine);
+                            startIndex = idx >= 0 ? idx + 1 : 0;
+                        }
+                        for (let i = startIndex; i < logsArr.length; i++) {
+                            const line = logsArr[i];
+                            if (q && String(line).includes(q)) {
+                                timeToMatch = Date.now() - start;
+                                matchSource = 'log-snapshot';
+                                return { success: true, type: 'log', matched: true, details: `Log matched '${q}'`, timestamp: Date.now(), log: { message: line }, telemetry: { pollCount, timeToMatch, elapsedMs: Date.now() - start, matchSource } };
+                            }
+                        }
+                    }
+                    catch (err) {
+                        console.error('observeUntil(log) error:', err);
+                    }
+                }
+                else if (type === 'screen') {
+                    try {
+                        const fpRes = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId });
+                        const fp = fpRes?.fingerprint ?? null;
+                        if (fp !== null && fp !== undefined && fp !== initialFingerprint) {
+                            if (q) {
+                                // optionally validate query against new screen context
+                                try {
+                                    const found = await ToolsInteract.findElementHandler({ query: q, exact: false, timeoutMs: Math.min(500, timeoutMs || 500), platform, deviceId });
+                                    if (found && found.found) {
+                                        timeToMatch = Date.now() - start;
+                                        matchSource = 'screen-validated-ui';
+                                        return { success: true, type: 'screen', matched: true, details: `Screen changed and query matched on new screen`, timestamp: Date.now(), newFingerprint: fp, element: found.element, telemetry: { pollCount, timeToMatch, elapsedMs: Date.now() - start, matchSource } };
+                                    }
+                                }
+                                catch (err) {
+                                    console.error('observeUntil(screen) find error:', err);
+                                }
+                                // If query provided but not matched yet, continue polling until timeout
+                            }
+                            else {
+                                timeToMatch = Date.now() - start;
+                                matchSource = 'screen-fingerprint';
+                                return { success: true, type: 'screen', matched: true, details: 'Screen fingerprint changed', timestamp: Date.now(), newFingerprint: fp, telemetry: { pollCount, timeToMatch, elapsedMs: Date.now() - start, matchSource } };
+                            }
+                        }
+                    }
+                    catch (err) {
+                        console.error('observeUntil(screen) error:', err);
+                    }
+                }
+                else if (type === 'idle') {
+                    try {
+                        const fpRes = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId });
+                        const fp = fpRes?.fingerprint ?? null;
+                        if (fp !== prevFingerprint) {
+                            prevFingerprint = fp;
+                            lastChangeAt = Date.now();
+                        }
+                        else {
+                            if (Date.now() - lastChangeAt >= STABLE_IDLE_MS) {
+                                timeToMatch = Date.now() - start;
+                                matchSource = 'idle-stable';
+                                return { success: true, type: 'idle', matched: true, details: `UI stable for ${STABLE_IDLE_MS}ms`, timestamp: Date.now(), fingerprint: fp, telemetry: { pollCount, timeToMatch, elapsedMs: Date.now() - start, matchSource } };
+                            }
+                        }
+                    }
+                    catch (err) {
+                        console.error('observeUntil(idle) error:', err);
+                    }
+                }
+            }
+            catch (err) {
+                console.error('observeUntil: unexpected error', err);
+            }
+            // Respect poll interval and avoid tight loop
+            await sleep(pollIntervalMs || 200);
+        }
+        // On timeout, capture a failure snapshot to aid debugging (best-effort)
+        let snapshot = null;
+        try {
+            snapshot = await ToolsObserve.captureDebugSnapshotHandler({ reason: `observe_until timeout for ${type}`, includeLogs: true, platform, deviceId });
+        }
+        catch (err) {
+            snapshot = { error: err instanceof Error ? err.message : String(err) };
+        }
+        const elapsed = Date.now() - start;
+        return { success: false, error: 'Timeout waiting for condition', type, timeoutMs, telemetry: { pollCount, elapsedMs: elapsed, matchSource: null }, snapshot };
+    }
 }

package/dist/server.js

@@ -7,6 +7,7 @@ import { ToolsInteract } from './interact/index.js';
 import { ToolsObserve } from './observe/index.js';
 import { AndroidManage } from './manage/index.js';
 import { iOSManage } from './manage/index.js';
+import { ensureAdbAvailable } from './utils/android/utils.js';
 const server = new Server({
     name: "mobile-debug-mcp",
     version: "0.7.0"
@@ -15,6 +16,24 @@ const server = new Server({
         tools: {}
     }
 });
+// Startup healthchecks (non-fatal) — verify adb availability and log chosen command
+(async () => {
+    try {
+        const adbCheck = ensureAdbAvailable();
+        if (adbCheck.ok)
+            console.debug('[startup] adb available:', adbCheck.adbCmd, adbCheck.version);
+        else
+            console.warn('[startup] adb not available or failed to run:', adbCheck.adbCmd, adbCheck.error);
+    }
+    catch (e) {
+        if (e instanceof Error) {
+            console.warn('[startup] error during adb healthcheck:', e.message);
+        }
+        else {
+            console.warn('[startup] error during adb healthcheck:', String(e));
+        }
+    }
+})();
 function wrapResponse(data) {
     return {
         content: [{

package/dist/utils/android/utils.js

@@ -2,7 +2,60 @@ import { promises as fsPromises, existsSync } from 'fs';
 import path from 'path';
 import { detectJavaHome } from '../java.js';
 import { execCmd } from '../exec.js';
-export function getAdbCmd() { return process.env.ADB_PATH || 'adb'; }
+import { spawnSync } from 'child_process';
+function findInPath(cmd) {
+    try {
+        // prefer command -v for POSIX
+        const res = spawnSync('command', ['-v', cmd], { encoding: 'utf8' });
+        if (res.status === 0 && res.stdout)
+            return res.stdout.trim();
+    }
+    catch (e) {
+        console.debug(`[findInPath] command -v ${cmd} failed: ${String(e)}`);
+    }
+    try {
+        const res = spawnSync('which', [cmd], { encoding: 'utf8' });
+        if (res.status === 0 && res.stdout)
+            return res.stdout.trim();
+    }
+    catch (e) {
+        console.debug(`[findInPath] which ${cmd} failed: ${String(e)}`);
+    }
+    return null;
+}
+export function resolveAdbCmd() {
+    // Priority: explicit env ADB_PATH -> ANDROID_SDK_ROOT/platform-tools/adb -> ANDROID_HOME/platform-tools/adb -> ~/Library/Android/sdk/platform-tools/adb -> PATH discovery -> 'adb'
+    if (process.env.ADB_PATH && process.env.ADB_PATH.trim())
+        return process.env.ADB_PATH;
+    const sdkRoot = process.env.ANDROID_SDK_ROOT || process.env.ANDROID_HOME;
+    if (sdkRoot) {
+        const candidate = path.join(sdkRoot, 'platform-tools', process.platform === 'win32' ? 'adb.exe' : 'adb');
+        if (existsSync(candidate))
+            return candidate;
+    }
+    // common macOS user SDK path
+    const homeSdk = path.join(process.env.HOME || '', 'Library', 'Android', 'sdk', 'platform-tools', process.platform === 'win32' ? 'adb.exe' : 'adb');
+    if (existsSync(homeSdk))
+        return homeSdk;
+    const found = findInPath('adb');
+    if (found)
+        return found;
+    return 'adb';
+}
+export function getAdbCmd() { return resolveAdbCmd(); }
+export function ensureAdbAvailable() {
+    const adb = resolveAdbCmd();
+    try {
+        const res = spawnSync(adb, ['--version'], { encoding: 'utf8' });
+        if (res.status === 0) {
+            return { adbCmd: adb, ok: true, version: (res.stdout || res.stderr || '').trim() };
+        }
+        return { adbCmd: adb, ok: false, error: (res.stderr || res.stdout || '').trim() };
+    }
+    catch (err) {
+        return { adbCmd: adb, ok: false, error: String(err) };
+    }
+}
 /**
  * Prepare Gradle execution options for building an Android project.
  * Returns execCmd (wrapper or gradle), base gradleArgs array, and spawn options including env.
@@ -24,26 +77,67 @@ export async function prepareGradle(projectPath) {
     }
     const detectedJavaHome = await detectJavaHome().catch(() => undefined);
     const env = Object.assign({}, process.env);
+    // Ensure child processes can find Android platform-tools (adb, etc.) by
+    // prepending the platform-tools directory to PATH for spawned processes.
+    const adbPath = resolveAdbCmd();
+    let platformToolsDir = undefined;
+    try {
+        if (adbPath && adbPath !== 'adb' && existsSync(adbPath)) {
+            platformToolsDir = path.dirname(adbPath);
+        }
+    }
+    catch (e) {
+        console.debug(`[prepareGradle] error resolving adbPath: ${String(e)}`);
+    }
+    const pathParts = [];
     if (detectedJavaHome) {
         if (env.JAVA_HOME !== detectedJavaHome) {
             env.JAVA_HOME = detectedJavaHome;
-            env.PATH = `${path.join(detectedJavaHome, 'bin')}${path.delimiter}${env.PATH || ''}`;
         }
+        const javaBin = path.join(detectedJavaHome, 'bin');
+        pathParts.push(javaBin);
         gradleArgs.push(`-Dorg.gradle.java.home=${detectedJavaHome}`);
         gradleArgs.push('--no-daemon');
         env.GRADLE_JAVA_HOME = detectedJavaHome;
     }
+    if (platformToolsDir) {
+        // Prepend platform-tools so gradle and child tools find adb without modifying global env
+        if (!env.PATH || !env.PATH.includes(platformToolsDir)) {
+            pathParts.push(platformToolsDir);
+        }
+    }
+    else if (process.env.ANDROID_SDK_ROOT || process.env.ANDROID_HOME) {
+        const sdkRoot = process.env.ANDROID_SDK_ROOT || process.env.ANDROID_HOME || '';
+        const candidate = path.join(sdkRoot, 'platform-tools');
+        if (existsSync(candidate) && (!env.PATH || !env.PATH.includes(candidate))) {
+            pathParts.push(candidate);
+        }
+    }
+    else {
+        // also try common user sdk location
+        const homeSdkTools = path.join(process.env.HOME || '', 'Library', 'Android', 'sdk', 'platform-tools');
+        if (existsSync(homeSdkTools) && (!env.PATH || !env.PATH.includes(homeSdkTools))) {
+            pathParts.push(homeSdkTools);
+        }
+    }
+    if (pathParts.length > 0) {
+        env.PATH = `${pathParts.join(path.delimiter)}${path.delimiter}${env.PATH || ''}`;
+    }
     try {
         delete env.SHELL;
     }
-    catch { }
+    catch (e) {
+        console.debug('[prepareGradle] failed to delete SHELL from env:', String(e));
+    }
     const useWrapper = existsSync(gradlewPath);
     const spawnOpts = { cwd: projectPath, env };
     if (useWrapper) {
         try {
             await fsPromises.chmod(gradlewPath, 0o755);
         }
-        catch { }
+        catch (e) {
+            console.debug('[prepareGradle] chmod failed for gradlew:', String(e));
+        }
         spawnOpts.shell = false;
     }
     else {
@@ -117,8 +211,8 @@ export async function getAndroidDeviceMetadata(appId, deviceId) {
                     resolvedDeviceId = deviceLines[0];
                 }
             }
-            catch {
-                // ignore and continue without resolvedDeviceId
+            catch (e) {
+                console.debug('[getAndroidDeviceMetadata] error detecting single device: ' + String(e));
             }
         }
         // Run these in parallel to avoid sequential timeouts
@@ -130,7 +224,8 @@ export async function getAndroidDeviceMetadata(appId, deviceId) {
         const simulator = simOutput === '1';
         return { platform: 'android', id: resolvedDeviceId || 'default', osVersion, model, simulator };
     }
-    catch {
+    catch (e) {
+        console.debug('[getAndroidDeviceMetadata] failed to gather metadata: ' + String(e));
         return { platform: 'android', id: deviceId || 'default', osVersion: '', model: '', simulator: false };
     }
 }
@@ -170,19 +265,22 @@ export async function listAndroidDevices(appId) {
                         const pm = await execAdb(['shell', 'pm', 'path', appId], serial);
                         appInstalled = !!(pm && pm.includes('package:'));
                     }
-                    catch {
+                    catch (e) {
+                        console.debug(`[listAndroidDevices] pm check failed for ${serial}: ${String(e)}`);
                         appInstalled = false;
                     }
                 }
                 return { platform: 'android', id: serial, osVersion, model, simulator, appInstalled };
             }
-            catch {
+            catch (e) {
+                console.debug(`[listAndroidDevices] failed gathering metadata for ${serial}: ${String(e)}`);
                 return { platform: 'android', id: serial, osVersion: '', model: '', simulator: false, appInstalled: false };
             }
         }));
         return infos;
     }
-    catch {
+    catch (e) {
+        console.debug('[listAndroidDevices] failed to list devices: ' + String(e));
         return [];
     }
 }
@@ -207,8 +305,8 @@ export async function getScreenResolution(deviceId) {
             return { width: parseInt(match[1]), height: parseInt(match[2]) };
         }
     }
-    catch {
-        // ignore
+    catch (e) {
+        console.debug('[getScreenResolution] failed to detect screen resolution: ' + String(e));
     }
     return { width: 0, height: 0 };
 }

package/dist/utils/cli/ios/preflight-ios.js

@@ -48,7 +48,7 @@ function startCompanionIfNeeded(companionPath, udid) {
         return { started: true };
     }
     catch (e) {
-        return { started: false, error: e.message };
+        return { started: false, error: e instanceof Error ? e.message : String(e) };
     }
 }
 async function main() {

package/dist/utils/java.js

@@ -1,76 +1,133 @@
 import { execSync } from 'child_process';
 import { existsSync } from 'fs';
 import path from 'path';
+function isJavaVersionAcceptable(output) {
+    if (!output)
+        return false;
+    const s = String(output);
+    // Accept Java 17 or 21 (common supported LTS for Android builds)
+    if (/\b17\b/.test(s) || /17\./.test(s))
+        return true;
+    if (/\b21\b/.test(s) || /21\./.test(s))
+        return true;
+    return false;
+}
+import { spawnSync } from 'child_process';
+function javaVersionOf(javaBin) {
+    try {
+        const res = spawnSync(javaBin, ['-version'], { encoding: 'utf8' });
+        // Java prints version to stderr traditionally
+        const out = (res.stdout || '') + (res.stderr || '');
+        return out || undefined;
+    }
+    catch (e) {
+        console.debug('[javaVersionOf] java -version failed: ' + String(e));
+        return undefined;
+    }
+}
 export async function detectJavaHome() {
     try {
-        // If JAVA_HOME is set, validate it's Java 17
-        if (process.env.JAVA_HOME) {
-            try {
-                const javaBin = path.join(process.env.JAVA_HOME, 'bin', 'java');
-                const v = execSync(`"${javaBin}" -version`, { stdio: ['ignore', 'pipe', 'pipe'] }).toString();
-                if (/\b17\b/.test(v) || /17\./.test(v))
-                    return process.env.JAVA_HOME;
-                console.debug('[java.detect] Existing JAVA_HOME does not appear to be Java 17, will search for JDK17');
-            }
-            catch {
-                console.debug('[java.detect] Failed to validate existing JAVA_HOME, searching for JDK17');
+        // 1) Honor explicit ANDROID_STUDIO_JDK env (highest priority)
+        const envStudio = process.env.ANDROID_STUDIO_JDK || process.env.ANDROID_STUDIO_JBR;
+        if (envStudio && existsSync(path.join(envStudio, 'bin', 'java'))) {
+            const v = javaVersionOf(path.join(envStudio, 'bin', 'java'));
+            if (isJavaVersionAcceptable(v)) {
+                console.debug('[java.detect] Using ANDROID_STUDIO_JDK from env:', envStudio);
+                return envStudio;
             }
+            console.debug('[java.detect] ANDROID_STUDIO_JDK present but java -version did not match expected versions');
         }
-        // macOS explicit path
-        const explicit = '/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home';
-        if (existsSync(explicit))
-            return explicit;
-        // Android Studio JBR candidates
+        // 2) Android Studio JBR candidates (prefer these over JAVA_HOME)
         const jbrCandidates = [
             '/Applications/Android Studio.app/Contents/jbr',
+            '/Applications/Android Studio.app/Contents/jbr/Contents/Home',
             '/Applications/Android Studio Preview.app/Contents/jbr',
+            '/Applications/Android Studio Preview.app/Contents/jbr/Contents/Home',
             '/Applications/Android Studio Preview 2022.3.app/Contents/jbr',
-            '/Applications/Android Studio Preview 2023.1.app/Contents/jbr'
+            '/Applications/Android Studio Preview 2022.3.app/Contents/jbr/Contents/Home',
+            '/Applications/Android Studio Preview 2023.1.app/Contents/jbr',
+            '/Applications/Android Studio Preview 2023.1.app/Contents/jbr/Contents/Home'
         ];
         for (const p of jbrCandidates) {
             const javaBin = path.join(p, 'bin', 'java');
             if (existsSync(javaBin)) {
-                try {
-                    const v = execSync(`"${javaBin}" -version`, { stdio: ['ignore', 'pipe', 'pipe'] }).toString();
-                    if (/\b17\b/.test(v) || /17\./.test(v))
-                        return p;
+                const v = javaVersionOf(javaBin);
+                if (isJavaVersionAcceptable(v)) {
+                    console.debug('[java.detect] Found Android Studio JBR at:', p);
+                    return p;
+                }
+            }
+        }
+        // 3) If JAVA_HOME set, validate it (accept 17 or 21)
+        if (process.env.JAVA_HOME) {
+            try {
+                const javaBin = path.join(process.env.JAVA_HOME, 'bin', 'java');
+                const v = javaVersionOf(javaBin);
+                if (isJavaVersionAcceptable(v)) {
+                    console.debug('[java.detect] Using JAVA_HOME from env:', process.env.JAVA_HOME);
+                    return process.env.JAVA_HOME;
                 }
-                catch { }
+                console.debug('[java.detect] Existing JAVA_HOME does not appear to be acceptable Java (17/21), will search');
+            }
+            catch {
+                console.debug('[java.detect] Failed to validate existing JAVA_HOME, searching for JDK');
             }
         }
-        // macOS /usr/libexec/java_home
+        // 4) macOS explicit path for JDK 17
+        const explicit = '/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home';
+        if (existsSync(explicit))
+            return explicit;
+        // 5) macOS /usr/libexec/java_home try supported versions
+        try {
+            const out17 = execSync('/usr/libexec/java_home -v 17', { stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim();
+            if (out17)
+                return out17;
+        }
+        catch (e) {
+            console.debug('[java.detect] /usr/libexec/java_home -v 17 failed: ' + String(e));
+        }
         try {
-            const out = execSync('/usr/libexec/java_home -v 17', { stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim();
-            if (out)
-                return out;
+            const out21 = execSync('/usr/libexec/java_home -v 21', { stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim();
+            if (out21)
+                return out21;
         }
-        catch { }
-        // macOS common JDK locations
+        catch (e) {
+            console.debug('[java.detect] /usr/libexec/java_home -v 21 failed: ' + String(e));
+        }
+        // 6) macOS common JDK locations
         try {
             const homes = execSync('ls -1 /Library/Java/JavaVirtualMachines || true', { stdio: ['ignore', 'pipe', 'inherit'] }).toString().split(/\r?\n/).filter(Boolean);
             for (const h of homes) {
-                if (h.toLowerCase().includes('17') || h.toLowerCase().includes('jdk-17')) {
+                if (h.toLowerCase().includes('17') || h.toLowerCase().includes('jdk-17') || h.toLowerCase().includes('21') || h.toLowerCase().includes('jdk-21')) {
                     const candidate = `/Library/Java/JavaVirtualMachines/${h}/Contents/Home`;
                     return candidate;
                 }
             }
         }
-        catch { }
-        // Linux locations
+        catch (e) {
+            console.debug('[java.detect] listing /Library/Java/JavaVirtualMachines failed: ' + String(e));
+        }
+        // 7) Linux locations
         const linuxCandidates = [
             '/usr/lib/jvm/java-17-openjdk-amd64',
             '/usr/lib/jvm/java-17-openjdk',
             '/usr/lib/jvm/zulu17',
-            '/usr/lib/jvm/temurin-17-jdk'
+            '/usr/lib/jvm/temurin-17-jdk',
+            '/usr/lib/jvm/temurin-21-jdk',
+            '/usr/lib/jvm/java-21-openjdk-amd64'
         ];
         for (const p of linuxCandidates) {
             try {
                 if (existsSync(p))
                     return p;
             }
-            catch { }
+            catch (e) {
+                console.debug(`[java.detect] checking linux candidate ${p} failed: ${String(e)}`);
+            }
         }
     }
-    catch { }
+    catch (e) {
+        console.debug('[java.detect] error detecting java home:', e instanceof Error ? e.message : String(e));
+    }
     return undefined;
 }

package/docs/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.19.1]
+
+- Fixed Android install issues
+
+## [0.19.0]
+
+- Added `observe_until` interaction tool: waits for UI, log, screen fingerprint or idle conditions with configurable polling and timeout. Returns rich details on match (element info, log line, new fingerprint).
+
+
 ## [0.18.0]
 - Added `find_element` interact tool: semantic UI element search with actionable tap coordinates and lightweight telemetry. The tool searches the UI tree for the best match by text, content description, resource-id, and class, scores candidates (exact, partial, resource-id), and returns the most relevant visible element. When a matching node is non-interactable (e.g., Compose Text child), the tool locates a clickable ancestor (parent or containing element) and returns actionable tapCoordinates (x,y). The handler also returns a `confidence` value and `telemetry` metadata (matchedIndex, matchedInteractable) to aid agent decision-making and logging. Implemented as `ToolsInteract.findElementHandler` and covered by unit tests.
 

package/docs/tools/interact.md

@@ -151,3 +151,55 @@ Notes:
 - The tool favours actionable (clickable/focusable) targets; when a matching node is not directly actionable, it finds the smallest containing clickable ancestor.
 - Unit tests for edge cases (parent-clickable child-text, resource-id matches, fuzzy matching) are under `test/observe/unit/find_element.test.ts`.
 
+---
+
+## observe_until
+
+Purpose:
+- Wait for a condition to occur on the device: UI element appearance, a log line, a screen fingerprint change, or an idle/stable screen state.
+
+Supported types and behavior:
+- ui: Delegates to `find_element` to perform a semantic search of the UI tree. Returns the matched element descriptor (including tapCoordinates) when found.
+- log: Reads the active log stream (via `start_log_stream`/`readLogStreamHandler`) and falls back to a snapshot of recent logs (`getLogsHandler`). Matches when the query substring appears in a new log line after a captured baseline.
+- screen: Compares screen fingerprints (visual checks) against an initial baseline and returns when fingerprint changes. If `query` is provided it will attempt a `find_element` on the new screen to validate the expected content.
+- idle: Waits until the screen fingerprint remains stable for a short stability window (default 1000ms).
+
+Input (ToolsInteract.observeUntilHandler):
+```
+{ "type": "ui|log|screen|idle", "query": "optional string", "timeoutMs": 5000, "pollIntervalMs": 200, "platform": "android|ios", "deviceId": "optional device id" }
+```
+
+Success response highlights:
+- success: true
+- type: requested type
+- matched: true
+- details: human-friendly explanation
+- timestamp: epoch ms
+- element: (for ui/screen when matched) actionable element metadata with tapCoordinates
+- log: (for log) matched log message and raw entry
+- newFingerprint: (for screen) new fingerprint value
+
+Failure/timeout response:
+- success: false
+- error or reason: explanation
+- type: requested type
+- timeoutMs: value used
+
+Notes & tips:
+- Defaults (timeoutMs=5000, pollIntervalMs=200) balance responsiveness with device query overhead; adjust in tests or scripts as needed.
+- For UI-sensitive flows prefer type='ui' rather than relying solely on visual fingerprint changes, as some UI updates don't alter the fingerprint.
+
+Tests:
+- Unit: `test/interact/unit/observe_until.test.ts`
+- Device runner: `test/interact/device/observe_until_device.ts` (requires devices/emulators and adb/xcrun in PATH)
+
+Example:
+```
+// Wait up to 5s for a button labeled "Generate Session" on Android
+ToolsInteract.observeUntilHandler({ type: 'ui', query: 'Generate Session', timeoutMs: 5000, platform: 'android' })
+```
+
+Troubleshooting:
+- If observe_until(log) never matches, ensure log streaming is started for the target package and baseline logs captured correctly.
+- If observe_until(screen) times out despite visible UI change, try type='ui' to validate content-level changes.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-mcp",
-  "version": "0.18.0",
+  "version": "0.19.1",
   "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {