mobile-debug-mcp 0.18.0 → 0.19.1

package/src/interact/index.ts

@@ -29,6 +29,8 @@ interface UiElement {
   _interactable?: boolean
 }
 
+const STABLE_IDLE_MS = 1000
+
 export class ToolsInteract {
 
   private static async getInteractionService(platform?: 'android' | 'ios', deviceId?: string) {
@@ -260,4 +262,147 @@ export class ToolsInteract {
     return { success: false, reason: 'timeout', lastFingerprint, elapsedMs: Date.now() - start }
   }
 
+  static async observeUntilHandler({ type, query, timeoutMs = 5000, pollIntervalMs = 200, platform, deviceId }: { type: 'ui' | 'log' | 'screen' | 'idle', query?: string, timeoutMs?: number, pollIntervalMs?: number, platform?: 'android' | 'ios', deviceId?: string }) {
+    const start = Date.now()
+    const deadline = start + (timeoutMs || 0)
+    const q = (query === null || query === undefined) ? '' : String(query)
+
+    // Baseline state
+    let initialFingerprint: string | null = null
+    try {
+      const fpRes = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }) as ScreenFingerprintResponse | null
+      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: string | null = null
+    try {
+      const gl = await ToolsObserve.getLogsHandler({ platform, deviceId, lines: 200 })
+      const logsArr = Array.isArray((gl as any).logs) ? (gl as any).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: number) => new Promise(r => setTimeout(r, ms))
+
+    // Telemetry
+    let pollCount = 0
+    let timeToMatch: number | null = null
+    let matchSource: string | null = 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 as any).found) {
+              timeToMatch = Date.now() - start
+              // determine matchSource heuristics
+              const el = (found as any).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 as any).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 }) as any
+            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 }) as any
+            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 }) as ScreenFingerprintResponse | null
+            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 as any).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 as any).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 }) as ScreenFingerprintResponse | null
+            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: any = 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/src/manage/android.ts

@@ -115,7 +115,7 @@ export class AndroidManage {
     try {
       await execAdb(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId)
       return { device: deviceInfo, appStarted: true, launchTimeMs: 1000 }
-    } catch (e:any) {
+    } catch (e: unknown) {
       const diag = execAdbWithDiagnostics(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId)
       return { device: deviceInfo, appStarted: false, launchTimeMs: 0, error: e instanceof Error ? e.message : String(e), diagnostics: diag }
     }
@@ -127,7 +127,7 @@ export class AndroidManage {
     try {
       await execAdb(['shell', 'am', 'force-stop', appId], deviceId)
       return { device: deviceInfo, appTerminated: true }
-    } catch (e:any) {
+    } catch (e: unknown) {
       const diag = execAdbWithDiagnostics(['shell', 'am', 'force-stop', appId], deviceId)
       return { device: deviceInfo, appTerminated: false, error: e instanceof Error ? e.message : String(e), diagnostics: diag }
     }
@@ -149,7 +149,7 @@ export class AndroidManage {
     try {
       const output = await execAdb(['shell', 'pm', 'clear', appId], deviceId)
       return { device: deviceInfo, dataCleared: output === 'Success' }
-    } catch (e:any) {
+    } catch (e: unknown) {
       const diag = execAdbWithDiagnostics(['shell', 'pm', 'clear', appId], deviceId)
       return { device: deviceInfo, dataCleared: false, error: e instanceof Error ? e.message : String(e), diagnostics: diag }
     }

package/src/manage/ios.ts

@@ -302,7 +302,7 @@ export class iOSManage {
       const result = await execCommand(['simctl', 'launch', deviceId, bundleId], deviceId)
       const device = await getIOSDeviceMetadata(deviceId)
       return { device, appStarted: !!result.output, launchTimeMs: 1000 }
-    } catch (e:any) {
+    } catch (e: unknown) {
       const diag = execCommandWithDiagnostics(['simctl', 'launch', deviceId, bundleId], deviceId)
       const device = await getIOSDeviceMetadata(deviceId)
       return { device, appStarted: false, launchTimeMs: 0, error: e instanceof Error ? e.message : String(e), diagnostics: diag } as any
@@ -315,7 +315,7 @@ export class iOSManage {
       await execCommand(['simctl', 'terminate', deviceId, bundleId], deviceId)
       const device = await getIOSDeviceMetadata(deviceId)
       return { device, appTerminated: true }
-    } catch (e:any) {
+    } catch (e: unknown) {
       const diag = execCommandWithDiagnostics(['simctl', 'terminate', deviceId, bundleId], deviceId)
       const device = await getIOSDeviceMetadata(deviceId)
       return { device, appTerminated: false, error: e instanceof Error ? e.message : String(e), diagnostics: diag } as any
@@ -351,7 +351,7 @@ export class iOSManage {
       } catch (e) {
         throw new Error(`Failed to clear data for ${bundleId}: ${e instanceof Error ? e.message : String(e)}`)
       }
-    } catch (e:any) {
+    } catch (e: unknown) {
       const diag = execCommandWithDiagnostics(['simctl', 'get_app_container', deviceId, bundleId, 'data'], deviceId)
       return { device, dataCleared: false, error: e instanceof Error ? e.message : String(e), diagnostics: diag } as any
     }

package/src/server.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { Server } from "@modelcontextprotocol/sdk/server/index.js"
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
+import type { SchemaOutput } from "@modelcontextprotocol/sdk/server/zod-compat.js"
 import {
   ListToolsRequestSchema,
   CallToolRequestSchema
@@ -19,6 +20,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(
@@ -31,7 +33,22 @@ 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: unknown) {
+    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<T>(data: T) {
   return {
@@ -487,9 +504,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       }
     }
   ]
-}))
+}));
 
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
+server.setRequestHandler(CallToolRequestSchema, async (request: SchemaOutput<typeof CallToolRequestSchema>) => {
   const { name, arguments: args } = request.params
 
   try {

package/src/utils/android/utils.ts

@@ -3,8 +3,51 @@ import { promises as fsPromises, existsSync } from 'fs'
 import path from 'path'
 import { detectJavaHome } from '../java.js'
 import { execCmd } from '../exec.js'
+import { spawnSync } from 'child_process'
 
-export function getAdbCmd() { return process.env.ADB_PATH || 'adb' }
+function findInPath(cmd: string): string | null {
+  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: unknown) { 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: unknown) { console.debug(`[findInPath] which ${cmd} failed: ${String(e)}`) }
+  return null
+}
+
+export function resolveAdbCmd(): string {
+  // 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: unknown) {
+    return { adbCmd: adb, ok: false, error: String(err) }
+  }
+}
 
 /**
  * Prepare Gradle execution options for building an Android project.
@@ -31,22 +74,58 @@ export async function prepareGradle(projectPath: string): Promise<{ execCmd: str
 
   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: string | undefined = undefined
+  try {
+    if (adbPath && adbPath !== 'adb' && existsSync(adbPath)) {
+      platformToolsDir = path.dirname(adbPath)
+    }
+  } catch (e: unknown) { console.debug(`[prepareGradle] error resolving adbPath: ${String(e)}`) }
+
+  const pathParts: string[] = []
   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
   }
 
-  try { delete env.SHELL } catch {}
+  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 (e: unknown) { console.debug('[prepareGradle] failed to delete SHELL from env:', String(e)) }
 
   const useWrapper = existsSync(gradlewPath)
   const spawnOpts: any = { cwd: projectPath, env }
   if (useWrapper) {
-    try { await fsPromises.chmod(gradlewPath, 0o755) } catch {}
+    try { await fsPromises.chmod(gradlewPath, 0o755) } catch (e: unknown) { console.debug('[prepareGradle] chmod failed for gradlew:', String(e)) }
     spawnOpts.shell = false
   } else {
     spawnOpts.shell = true
@@ -125,8 +204,7 @@ export async function getAndroidDeviceMetadata(appId: string, deviceId?: string)
         if (deviceLines.length === 1) {
           resolvedDeviceId = deviceLines[0];
         }
-      } catch {
-        // ignore and continue without resolvedDeviceId
+      } catch (e: unknown) { console.debug('[getAndroidDeviceMetadata] error detecting single device: ' + String(e))
       }
     }
 
@@ -139,7 +217,8 @@ export async function getAndroidDeviceMetadata(appId: string, deviceId?: string)
     
     const simulator = simOutput === '1'
     return { platform: 'android', id: resolvedDeviceId || 'default', osVersion, model, simulator }
-  } catch {
+  } catch (e: unknown) {
+    console.debug('[getAndroidDeviceMetadata] failed to gather metadata: ' + String(e))
     return { platform: 'android', id: deviceId || 'default', osVersion: '', model: '', simulator: false }
   }
 }
@@ -180,20 +259,14 @@ export async function listAndroidDevices(appId?: string): Promise<DeviceInfo[]>
           try {
             const pm = await execAdb(['shell', 'pm', 'path', appId], serial)
             appInstalled = !!(pm && pm.includes('package:'))
-          } catch {
-            appInstalled = false
-          }
+          } catch (e: unknown) { console.debug(`[listAndroidDevices] pm check failed for ${serial}: ${String(e)}`); appInstalled = false }
         }
         return { platform: 'android', id: serial, osVersion, model, simulator, appInstalled } as DeviceInfo & { appInstalled?: boolean }
-      } catch {
-        return { platform: 'android', id: serial, osVersion: '', model: '', simulator: false, appInstalled: false } as DeviceInfo & { appInstalled?: boolean }
-      }
+      } catch (e: unknown) { console.debug(`[listAndroidDevices] failed gathering metadata for ${serial}: ${String(e)}`); return { platform: 'android', id: serial, osVersion: '', model: '', simulator: false, appInstalled: false } as DeviceInfo & { appInstalled?: boolean } }
     }))
 
     return infos
-  } catch {
-    return []
-  }
+  } catch (e: unknown) { console.debug('[listAndroidDevices] failed to list devices: ' + String(e)); return [] }
 }
 
 // UI helper utilities shared by observe/interact
@@ -219,9 +292,7 @@ export async function getScreenResolution(deviceId?: string): Promise<{ width: n
     if (match) {
       return { width: parseInt(match[1]), height: parseInt(match[2]) };
     }
-  } catch {
-    // ignore
-  }
+  } catch (e: unknown) { console.debug('[getScreenResolution] failed to detect screen resolution: ' + String(e)) }
   return { width: 0, height: 0 };
 }
 

package/src/utils/cli/ios/preflight-ios.ts

@@ -40,8 +40,8 @@ function startCompanionIfNeeded(companionPath: string | null, udid: string | nul
     const child = spawn(companionPath, ['--udid', udid], { detached: true, stdio: 'ignore' })
     child.unref()
     return { started: true }
-  } catch (e:any) {
-    return { started: false, error: e.message }
+  } catch (e: unknown) {
+    return { started: false, error: e instanceof Error ? e.message : String(e) }
   }
 }
 

package/src/utils/java.ts

@@ -2,68 +2,114 @@ import { execSync } from 'child_process'
 import { existsSync } from 'fs'
 import path from 'path'
 
+function isJavaVersionAcceptable(output?: string | null): boolean {
+  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: string): string | undefined {
+  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: unknown) { console.debug('[javaVersionOf] java -version failed: ' + String(e)); return undefined }
+}
+
 export async function detectJavaHome(): Promise<string | undefined> {
   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
-        } catch {}
+        const v = javaVersionOf(javaBin)
+        if (isJavaVersionAcceptable(v)) {
+          console.debug('[java.detect] Found Android Studio JBR at:', p)
+          return p
+        }
       }
     }
 
-    // macOS /usr/libexec/java_home
+    // 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
+        }
+        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')
+      }
+    }
+
+    // 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: unknown) { 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
-    } catch {}
+      const out21 = execSync('/usr/libexec/java_home -v 21', { stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim()
+      if (out21) return out21
+    } catch (e: unknown) { console.debug('[java.detect] /usr/libexec/java_home -v 21 failed: ' + String(e)) }
 
-    // macOS common JDK locations
+    // 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 {}
+    } catch (e: unknown) { console.debug('[java.detect] listing /Library/Java/JavaVirtualMachines failed: ' + String(e)) }
 
-    // Linux locations
+    // 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 {}
+      try { if (existsSync(p)) return p } catch (e: unknown) { console.debug(`[java.detect] checking linux candidate ${p} failed: ${String(e)}`) }
     }
-  } catch {}
+  } catch (e: unknown) {
+    console.debug('[java.detect] error detecting java home:', e instanceof Error ? e.message : String(e))
+  }
   return undefined
 }

package/test/interact/device/observe_until_device.ts

@@ -0,0 +1,24 @@
+(async function main(){
+  try{
+    const inter = await import('../../src/interact/index.ts')
+    const manage = await import('../../src/manage/index.ts')
+    const ToolsInteract = (inter as any).ToolsInteract
+    const ToolsManage = (manage as any).ToolsManage
+
+    const ANDROID_ID = process.env.ANDROID_DEVICE || 'emulator-5554'
+    const IOS_UDID = process.env.IOS_DEVICE || '2EFFD8FD-5D09-47CC-95F8-28BBE30AF7ED'
+    console.log('Device test starting. Android:', ANDROID_ID, 'iOS:', IOS_UDID)
+
+    // Start modul8 on both platforms if present
+    try { await ToolsManage.startAppHandler({ platform: 'android', appId: 'com.ideamechanics.modul8', deviceId: ANDROID_ID }); console.log('Started android app (if installed)') } catch(e){ console.error('Android start skipped:', e.message || e) }
+    try { await ToolsManage.startAppHandler({ platform: 'ios', appId: 'com.ideamechanics.modul8.Modul8', deviceId: IOS_UDID }); console.log('Started ios app (if installed)') } catch(e){ console.error('iOS start skipped:', e.message || e) }
+
+    // Observe UI for Generate Session on both devices (will timeout if not present)
+    const aRes = await ToolsInteract.observeUntilHandler({ type: 'ui', query: 'Generate Session', timeoutMs: 20000, pollIntervalMs: 500, platform: 'android', deviceId: ANDROID_ID })
+    console.log('Android observe result:', JSON.stringify(aRes, null, 2))
+
+    const iRes = await ToolsInteract.observeUntilHandler({ type: 'ui', query: 'Generate Session', timeoutMs: 20000, pollIntervalMs: 500, platform: 'ios', deviceId: IOS_UDID })
+    console.log('iOS observe result:', JSON.stringify(iRes, null, 2))
+
+  } catch (e) { console.error('ERR', e); process.exit(1) }
+})()