mobile-debug-mcp 0.20.1 → 0.21.0

package/dist/scripts/press_and_wait_ui.mjs

@@ -0,0 +1,85 @@
+import { ToolsObserve } from '../observe/index.js'
+import { ToolsInteract } from '../interact/index.js'
+
+async function main() {
+  const bundle = 'com.ideamechanics.modul8'
+  const sessionId = 'press-ui-test'
+  console.log('Starting log stream for', bundle)
+  try {
+    const platform = process.argv.includes('--platform') ? process.argv[process.argv.indexOf('--platform')+1] : 'android'
+    const pkg = bundle
+    const sessionOpts = { platform, packageName: pkg, sessionId }
+    const start = await ToolsObserve.startLogStreamHandler(sessionOpts)
+    console.log('startLogStream result:', JSON.stringify(start))
+  } catch (e) {
+    console.error('startLogStream failed:', e instanceof Error ? e.message : String(e))
+  }
+
+  console.log('\nAttempting to find and tap Generate Session...')
+  let el = null
+  try {
+    const platform = process.argv.includes('--platform') ? process.argv[process.argv.indexOf('--platform')+1] : 'android'
+    const found = await ToolsInteract.findElementHandler({ query: 'Generate Session', exact: platform === 'android', timeoutMs: 3000, platform })
+    const foundFlag = found && typeof (found).found !== 'undefined' ? found.found : false
+    console.log('findElementHandler:', foundFlag ? 'found' : 'not found')
+    if (foundFlag) {
+      el = found.element
+      console.log('Matched element:', JSON.stringify(el))
+    }
+  } catch (e) { console.error('findElementHandler err:', e) }
+
+  try {
+    const platform = process.argv.includes('--platform') ? process.argv[process.argv.indexOf('--platform')+1] : 'android'
+    const device = process.argv.includes('--device') ? process.argv[process.argv.indexOf('--device')+1] : undefined
+
+    // Strict foreground check: ensure the package is in foreground before tapping
+    try {
+      const fg = await ToolsInteract.get_current_activity ? await ToolsInteract.get_current_activity({ platform, deviceId: device }) : null
+      console.log('Foreground activity info:', fg)
+      if (fg && fg.activity && !String(fg.activity).includes('modul8')) {
+        console.error('App is not foreground. Aborting tap.')
+        process.exit(2)
+      }
+    } catch (e) { console.warn('Foreground check failed:', e) }
+
+    if (el && el.tapCoordinates) {
+      console.log('Tapping matched element at', JSON.stringify(el.tapCoordinates))
+      await ToolsInteract.tapHandler({ platform, x: el.tapCoordinates.x, y: el.tapCoordinates.y, deviceId: device })
+    } else {
+      console.log('Element not found, tapping center fallback')
+      await ToolsInteract.tapHandler({ platform, x: 200, y: 400, deviceId: device })
+    }
+  } catch (e) { console.error('Tap failed:', e) }
+
+  console.log('\nNow waiting for "Generating session" to disappear (timeout 30s)')
+  const start = Date.now()
+  const deadline = start + (parseInt(process.argv.includes('--timeout') ? process.argv[process.argv.indexOf('--timeout')+1] : '30000'))
+  let poll = 0
+  let disappeared = false
+  const platformArg = process.argv.includes('--platform') ? process.argv[process.argv.indexOf('--platform')+1] : 'android'
+  const deviceArg = process.argv.includes('--device') ? process.argv[process.argv.indexOf('--device')+1] : undefined
+  while (Date.now() <= deadline) {
+    poll++
+    try {
+      const f = await ToolsInteract.findElementHandler({ query: 'Generating session', exact: false, timeoutMs: 1000, platform: platformArg, deviceId: deviceArg })
+      const exists = f && typeof f.found !== 'undefined' ? f.found : false
+      console.log(`poll ${poll}: generating exists=${exists}`)
+      if (!exists) { disappeared = true; break }
+    } catch (e) { console.error('findElement err:', e) }
+    await new Promise(r => setTimeout(r, 500))
+  }
+
+  const elapsed = Date.now()-start
+  console.log('Result: disappeared=', disappeared, 'polls=', poll, 'elapsedMs=', elapsed)
+
+  // Platform-specific post-conditions
+
+
+  console.log('\nFinal Result: success=', disappeared)
+
+  console.log('\nStopping log stream')
+  try { const stop = await ToolsObserve.stopLogStreamHandler({ platform: 'ios', sessionId }); console.log('stopLogStream', stop) } catch (e) { console.error('stop failed', e) }
+  process.exit(disappeared ? 0 : 2)
+}
+
+main().catch(e=>{ console.error(e); process.exit(1) })

package/dist/scripts/test_generate_and_wait.mjs

@@ -0,0 +1,123 @@
+import fs from 'fs'
+import path from 'path'
+import { ToolsObserve } from '../observe/index.js'
+import { ToolsInteract } from '../interact/index.js'
+
+const argv = process.argv.slice(2)
+const opts = { platform: 'android', deviceId: undefined, timeoutMs: 180000, stabilityMs: 1000, pollIntervalMs: 500, saveDir: '/tmp' }
+for (let i = 0; i < argv.length; i++) {
+  if (argv[i] === '--platform') opts.platform = argv[++i]
+  else if (argv[i] === '--deviceId') opts.deviceId = argv[++i]
+  else if (argv[i] === '--timeout') opts.timeoutMs = Number(argv[++i])
+  else if (argv[i] === '--stabilityMs') opts.stabilityMs = Number(argv[++i])
+  else if (argv[i] === '--poll') opts.pollIntervalMs = Number(argv[++i])
+  else if (argv[i] === '--saveDir') opts.saveDir = argv[++i]
+}
+
+const platform = opts.platform
+const deviceId = opts.deviceId
+const timeoutMs = opts.timeoutMs
+const stabilityMs = opts.stabilityMs
+const poll = opts.pollIntervalMs
+const saveDir = opts.saveDir
+
+const ts = () => Date.now()
+
+async function findAndTapGenerate() {
+  try {
+    const found = await ToolsInteract.findElementHandler({ query: 'Generate Session', exact: false, timeoutMs: 3000, platform, deviceId })
+    const foundFlag = found && typeof found.found !== 'undefined' ? found.found : false
+    console.log('find Generate Session:', foundFlag)
+    if (foundFlag) {
+      const el = found.element
+      if (el && el.tapCoordinates) {
+        console.log('Tapping at', JSON.stringify(el.tapCoordinates))
+        await ToolsInteract.tapHandler({ platform, x: el.tapCoordinates.x, y: el.tapCoordinates.y, deviceId })
+        return true
+      } else {
+        // tap center of parent bounds if available
+        if (el && el.bounds) {
+          const b = el.bounds
+          const cx = Math.floor((b.left + b.right)/2)
+          const cy = Math.floor((b.top + b.bottom)/2)
+          console.log('Tapping parent center', cx, cy)
+          await ToolsInteract.tapHandler({ platform, x: cx, y: cy, deviceId })
+          return true
+        }
+      }
+    }
+  } catch (e) { console.error('error finding/tapping generate:', e) }
+  return false
+}
+
+async function captureUITree(savePrefix) {
+  try {
+    const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId })
+    const p = path.join(saveDir, `${savePrefix}_ui_${Date.now()}.json`)
+    fs.writeFileSync(p, JSON.stringify(tree, null, 2))
+    console.log('Wrote UI tree', p)
+    return tree
+  } catch (e) { console.error('failed getUITree:', e); return null }
+}
+
+async function tryCaptureScreenshot(savePrefix) {
+  try {
+    const res = await ToolsObserve.captureScreenshotHandler({ platform, deviceId })
+    // handler may return { image: 'data:image/png;base64,...' } or blocks; try to extract base64
+    let b64 = null
+    if (res && res.image && typeof res.image === 'string') b64 = res.image.replace(/^data:image\/png;base64,/, '')
+    else if (Array.isArray(res) && res.length) {
+      for (const blk of res) { if (blk && blk.mime === 'image/png' && blk.data) { b64 = blk.data; break } }
+    } else if (res && res.blocks) {
+      for (const blk of res.blocks) { if (blk && blk.mime === 'image/png' && blk.data) { b64 = blk.data; break } }
+    }
+    if (b64) {
+      const p = path.join(saveDir, `${savePrefix}_shot_${Date.now()}.png`)
+      fs.writeFileSync(p, Buffer.from(b64, 'base64'))
+      console.log('Wrote screenshot', p)
+      return p
+    }
+    console.log('No image returned from captureScreenshotHandler')
+  } catch (e) { console.error('screenshot error:', e) }
+  return null
+}
+
+async function main() {
+  console.log('Starting test: tap Generate Session and wait for Play session to appear stably')
+  const tapped = await findAndTapGenerate()
+  if (!tapped) console.log('Warning: generate tap not performed')
+
+  const start = ts()
+  const deadline = start + timeoutMs
+  let matchedAt = null
+  let pollCount = 0
+
+  while (Date.now() <= deadline) {
+    pollCount++
+    const savePrefix = `gen_wait_p${pollCount}`
+    const tree = await captureUITree(savePrefix)
+    try {
+      const f = await ToolsInteract.findElementHandler({ query: 'Play session', exact: false, timeoutMs: 500, platform, deviceId })
+      const exists = f && typeof f.found !== 'undefined' ? f.found : false
+      console.log(`poll ${pollCount}: play exists=${exists}`)
+      await tryCaptureScreenshot(savePrefix)
+      if (exists) {
+        if (matchedAt === null) matchedAt = Date.now()
+        const stable = Date.now() - matchedAt
+        if (stable >= stabilityMs) {
+          console.log('SUCCESS: Play session present and stable for', stable, 'ms after', Date.now()-start, 'ms and', pollCount, 'polls')
+          process.exit(0)
+        }
+      } else {
+        matchedAt = null
+      }
+    } catch (e) { console.error('error during poll:', e) }
+
+    await new Promise(r => setTimeout(r, poll))
+  }
+
+  console.error('FAIL: timeout waiting for Play session (polls=', pollCount, ')')
+  process.exit(2)
+}
+
+main().catch(e=>{ console.error('fatal', e); process.exit(1) })

package/dist/server.js

@@ -314,6 +314,24 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: ["previousFingerprint"]
             }
         },
+        {
+            name: "observe_until",
+            description: "Wait for a UI condition (element present/absent) and require a stability window before returning success. Network-based waiting is not required; UI-only synchronization is the default and primary mode.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    type: { type: "string", enum: ["ui", "log", "screen", "idle"], description: "Condition type to observe", default: "ui" },
+                    query: { type: "string", description: "Optional query string for ui/log/screen types" },
+                    timeoutMs: { type: "number", description: "Timeout in ms to wait for condition (default 30000)", default: 30000 },
+                    pollIntervalMs: { type: "number", description: "Polling interval in ms (default 300, clamped to 250-500)", default: 300 },
+                    match: { type: "string", enum: ["present", "absent"], description: "Match mode for UI checks: 'present' or 'absent' (default 'present')", default: "present" },
+                    stability_ms: { type: "number", description: "Stability window in ms that the condition must hold before returning success (default 700)", default: 700 },
+                    includeSnapshotOnFailure: { type: "boolean", description: "Whether to include a debug snapshot on timeout (default true)", default: true },
+                    platform: { type: "string", enum: ["android", "ios"], description: "Optional platform override" },
+                    deviceId: { type: "string", description: "Optional device serial/udid" }
+                }
+            }
+        },
         {
             name: "wait_for_element",
             description: "Wait until a UI element with matching text appears on screen or timeout is reached.",

package/dist/system/gradle.js

@@ -19,7 +19,7 @@ function readPropertiesFile(p) {
         }
         return out;
     }
-    catch (e) {
+    catch {
         return {};
     }
 }
@@ -35,7 +35,7 @@ function javaBinExists(p) {
             return true;
         return false;
     }
-    catch (e) {
+    catch {
         return false;
     }
 }
@@ -67,7 +67,7 @@ export async function checkGradle() {
             }
         }
     }
-    catch (e) { /* ignore */ }
+    catch { }
     // 3) system gradle.properties
     const systemProps = '/etc/gradle/gradle.properties';
     filesChecked.push(systemProps);
@@ -82,7 +82,7 @@ export async function checkGradle() {
             }
         }
     }
-    catch (e) { /* ignore */ }
+    catch { }
     // 4) GRADLE_HOME fallback
     if (!gradleJavaHome && process.env.GRADLE_HOME) {
         filesChecked.push(process.env.GRADLE_HOME);

package/dist/utils/android/utils.js

@@ -82,7 +82,7 @@ export async function prepareGradle(projectPath) {
     try {
         gradleCheck = await checkGradle();
     }
-    catch (e) {
+    catch {
         gradleCheck = { gradleJavaHome: undefined, gradleValid: false, filesChecked: [], issues: [] };
     }
     const env = Object.assign({}, process.env);
@@ -127,7 +127,7 @@ export async function prepareGradle(projectPath) {
             try {
                 delete env.GRADLE_JAVA_HOME;
             }
-            catch (e) { }
+            catch { }
         }
     }
     if (platformToolsDir) {

package/docs/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.21.0]
+- Added `observe_until` as a tool for agents to wait for things like API requests
+
 ## [0.20.1]
 - Fixes gradle home issue for android
 

package/package.json

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

package/src/interact/index.ts

@@ -29,7 +29,6 @@ interface UiElement {
   _interactable?: boolean
 }
 
-const STABLE_IDLE_MS = 1000
 
 export class ToolsInteract {
 
@@ -262,76 +261,105 @@ 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 }) {
+  static async observeUntilHandler({ type = 'ui', query, timeoutMs = 30000, pollIntervalMs = 300, includeSnapshotOnFailure = true, match = 'present', stability_ms = 700, observationDelayMs = 0, platform, deviceId }: { type?: 'ui' | 'log' | 'screen' | 'idle', query?: string, timeoutMs?: number, pollIntervalMs?: number, includeSnapshotOnFailure?: boolean, match?: 'present'|'absent', stability_ms?: number, observationDelayMs?: 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 }
+    // Clamp polling interval to 250-500ms for consistent behavior
+    const pollInterval = Math.max(250, Math.min(pollIntervalMs || 300, 500))
 
-    // For logs, capture a baseline snapshot (count or last line) to avoid matching historical lines
+    // Baseline state (fetch in parallel but bound to short timeouts so observation starts promptly)
+    let initialFingerprint: string | null = null
     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
+      const fpPromise = ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }) as Promise<ScreenFingerprintResponse | null>
+      const logsPromise = ToolsObserve.getLogsHandler({ platform, deviceId, lines: 200 }) as Promise<any>
+      const withTimeout = (p: Promise<any>, ms: number) => Promise.race([p, new Promise(resolve => setTimeout(() => resolve(null), ms))])
+      const [fpRes, gl] = await Promise.all([withTimeout(fpPromise, 300), withTimeout(logsPromise, 500)])
+      if (fpRes && typeof fpRes === 'object') initialFingerprint = (fpRes as ScreenFingerprintResponse).fingerprint ?? null
+      if (gl) {
+        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 { }
+      try { console.warn('observeUntil: failed to get baseline data (non-fatal):', err instanceof Error ? err.message : String(err)) } catch { }
     }
 
-    
+    // Network-based waiting removed. Rely on UI and screen fingerprints for determinism.
     let lastChangeAt = Date.now()
     let prevFingerprint = initialFingerprint
 
     const sleep = (ms: number) => new Promise(r => setTimeout(r, ms))
 
+    // Optional initial observation delay requested by caller
+    if (typeof observationDelayMs === 'number' && observationDelayMs > 0) {
+      try { console.log(`observeUntil: delaying observation for ${observationDelayMs}ms`) } catch { }
+      await sleep(observationDelayMs)
+    }
+
     // Telemetry
     let pollCount = 0
-    let timeToMatch: number | null = null
+    let matchedAt: number | null = null
+    let lastObservedState: boolean | null = null
+    let stableDuration = 0
     let matchSource: string | null = null
 
     while (Date.now() <= deadline) {
       pollCount++
-      try {
+        const now = Date.now()
+        // Evaluate condition per type
         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 } }
-            }
+                // Lightweight UI check: fetch UI tree and perform a normalized substring match to reduce overhead
+            try {
+              // Bound the UI tree fetch to avoid long blocking calls; prefer quick failure over hanging a poll
+              const withTimeout = (p: Promise<any>, ms: number) => Promise.race([p, new Promise(resolve => setTimeout(()=>resolve(null), ms))])
+              const tree = await withTimeout(ToolsObserve.getUITreeHandler({ platform, deviceId }), Math.min(pollInterval, 500)) as any
+              const elems = Array.isArray(tree && tree.elements) ? tree.elements : []
+              const qnorm = q.toLowerCase()
+              let matched: any = null
+              for (const el of elems) {
+                try {
+                  const txt = ((el && (el.text || el.label || el.value || el.contentDescription || el.accessibilityLabel)) || '')
+                  if (!txt) continue
+                  if (String(txt).toLowerCase().includes(qnorm)) { matched = el; break }
+                } catch { continue }
+              }
+              const isPresent = !!matched
+              const conditionTrue = (match === 'present') ? isPresent : !isPresent
+              if (conditionTrue) {
+                if (matchedAt === null) matchedAt = Date.now()
+                stableDuration = Date.now() - (matchedAt as number)
+                lastObservedState = true
+                if (stableDuration >= stability_ms) {
+                  matchSource = 'ui-tree-' + (match === 'present' ? 'present' : 'absent')
+                  const element = isPresent ? matched : null
+                  const now2 = Date.now()
+                  return { success: true, condition: match, query: q, poll_count: pollCount, duration_ms: now2 - start, stable_duration_ms: stableDuration, matchedElement: element, matchSource, timestamp: now2, type: 'ui', observed_state: lastObservedState ?? null }
+                }
+              } else {
+                matchedAt = null
+                stableDuration = 0
+                lastObservedState = false
+              }
+            } catch (err) { console.error('observeUntil(ui) tree error:', err) }
           } catch (err) { console.error('observeUntil(ui) find error:', err) }
         } else if (type === 'log') {
           try {
-            // Try reading from active stream first
+            // Logs: presence semantics only (match 'present'). Stability not applicable (immediate)
             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 } }
+                const now2 = Date.now()
+                return { success: true, condition: 'present', query: q, poll_count: pollCount, duration_ms: now2 - start, stable_duration_ms: 0, matchedLog: { message: msg, raw: ent }, matchSource: 'log-stream', timestamp: now2, type: 'log', observed_state: true }
               }
             }
 
-            // 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)
@@ -340,9 +368,8 @@ export class ToolsInteract {
             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 } }
+                const now2 = Date.now()
+                return { success: true, condition: 'present', query: q, poll_count: pollCount, duration_ms: now2 - start, stable_duration_ms: 0, matchedLog: { message: line }, matchSource: 'log-snapshot', timestamp: now2, type: 'log', observed_state: true }
               }
             }
           } catch (err) { console.error('observeUntil(log) error:', err) }
@@ -351,21 +378,20 @@ export class ToolsInteract {
             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
+              // when screen changed, require stability_ms where fingerprint remains the same
+              if (matchedAt === null) matchedAt = now
+              const confirmFp = (await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }) as ScreenFingerprintResponse | null)?.fingerprint ?? null
+              if (confirmFp === fp) {
+                stableDuration = Date.now() - (matchedAt as number)
+                lastObservedState = true
+                if (stableDuration >= stability_ms) {
+                  const now2 = Date.now()
+                  return { success: true, condition: 'present', query: q, poll_count: pollCount, duration_ms: now2 - start, stable_duration_ms: stableDuration, newFingerprint: fp, matchSource: 'screen-fingerprint', timestamp: now2, type: 'screen', observed_state: lastObservedState ?? null }
+                }
               } 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 } }
+                matchedAt = null
+                stableDuration = 0
+                lastObservedState = false
               }
             }
           } catch (err) { console.error('observeUntil(screen) error:', err) }
@@ -376,33 +402,35 @@ export class ToolsInteract {
             if (fp !== prevFingerprint) {
               prevFingerprint = fp
               lastChangeAt = Date.now()
+              matchedAt = null
+              stableDuration = 0
+              lastObservedState = false
             } 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 } }
+              const idleMs = Date.now() - lastChangeAt
+              lastObservedState = true
+              if (idleMs >= stability_ms) {
+                const now2 = Date.now()
+                return { success: true, condition: 'present', query: q, poll_count: pollCount, duration_ms: now2 - start, stable_duration_ms: idleMs, matchSource: 'idle-stable', timestamp: now2, type: 'idle', observed_state: lastObservedState ?? null }
               }
             }
           } 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)
+      await sleep(pollInterval)
     }
 
-    // On timeout, capture a failure snapshot to aid debugging (best-effort)
+    // On timeout, optionally 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) }
+    if (includeSnapshotOnFailure) {
+      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 }
-  }
-
+    return { success: false, condition: match, query: q, poll_count: pollCount, duration_ms: elapsed, stable_duration_ms: stableDuration, error: 'Timeout waiting for condition', snapshot, observed_state: lastObservedState ?? null }
+  }  
 }

package/src/server.ts

@@ -339,6 +339,26 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ["previousFingerprint"]
       }
     },
+    {
+      name: "observe_until",
+      description: "Wait for a UI condition (element present/absent) and require a stability window before returning success. Network-based waiting is not required; UI-only synchronization is the default and primary mode.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          type: { type: "string", enum: ["ui","log","screen","idle"], description: "Condition type to observe", default: "ui" },
+          query: { type: "string", description: "Optional query string for ui/log/screen types" },
+          timeoutMs: { type: "number", description: "Timeout in ms to wait for condition (default 30000)", default: 30000 },
+          pollIntervalMs: { type: "number", description: "Polling interval in ms (default 300, clamped to 250-500)", default: 300 },
+          match: { type: "string", enum: ["present","absent"], description: "Match mode for UI checks: 'present' or 'absent' (default 'present')", default: "present" },
+          stability_ms: { type: "number", description: "Stability window in ms that the condition must hold before returning success (default 700)", default: 700 },
+          includeSnapshotOnFailure: { type: "boolean", description: "Whether to include a debug snapshot on timeout (default true)", default: true },
+          platform: { type: "string", enum: ["android","ios"], description: "Optional platform override" },
+          deviceId: { type: "string", description: "Optional device serial/udid" }
+        }
+      }
+    },
+
+
     {
       name: "wait_for_element",
       description: "Wait until a UI element with matching text appears on screen or timeout is reached.",

package/src/system/gradle.ts

@@ -17,7 +17,7 @@ function readPropertiesFile(p: string): Record<string,string> {
       out[k] = v
     }
     return out
-  } catch (e: unknown) {
+  } catch {
     return {}
   }
 }
@@ -30,7 +30,7 @@ function javaBinExists(p?: string): boolean {
     const alt = path.join(p, 'Contents', 'Home', 'bin', 'java')
     if (existsSync(alt)) return true
     return false
-  } catch (e: unknown) { return false }
+  } catch { return false }
 }
 
 export async function checkGradle(): Promise<{ gradleJavaHome?: string; gradleValid: boolean; filesChecked: string[]; issues: string[]; suggestedFixes?: string[] }> {
@@ -62,7 +62,7 @@ export async function checkGradle(): Promise<{ gradleJavaHome?: string; gradleVa
         suggestedFixes.push(`Edit ${userProps} to remove or correct org.gradle.java.home`)
       }
     }
-  } catch (e: unknown) { /* ignore */ }
+  } catch { }
 
   // 3) system gradle.properties
   const systemProps = '/etc/gradle/gradle.properties'
@@ -77,7 +77,7 @@ export async function checkGradle(): Promise<{ gradleJavaHome?: string; gradleVa
         suggestedFixes.push(`Edit ${systemProps} to remove or correct org.gradle.java.home`)
       }
     }
-  } catch (e: unknown) { /* ignore */ }
+  } catch { }
 
   // 4) GRADLE_HOME fallback
   if (!gradleJavaHome && process.env.GRADLE_HOME) {

package/src/utils/android/utils.ts

@@ -78,7 +78,7 @@ export async function prepareGradle(projectPath: string): Promise<{ execCmd: str
   let gradleCheck
   try {
     gradleCheck = await checkGradle()
-  } catch (e: unknown) {
+  } catch {
     gradleCheck = { gradleJavaHome: undefined, gradleValid: false, filesChecked: [], issues: [] }
   }
 
@@ -117,7 +117,7 @@ export async function prepareGradle(projectPath: string): Promise<{ execCmd: str
     } else {
       // Invalid gradle java home detected: avoid passing it to Gradle and remove from spawn env
       console.debug(`[prepareGradle] Invalid org.gradle.java.home detected (${gradleCheck.gradleJavaHome}); removing from spawn env to avoid Gradle error.`)
-      try { delete env.GRADLE_JAVA_HOME } catch (e: unknown) { }
+      try { delete env.GRADLE_JAVA_HOME } catch { }
     }
   }