mobile-debug-mcp 0.18.0 → 0.19.0

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/docs/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [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.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,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/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) }
+})()

package/test/interact/unit/observe_until.test.ts

@@ -0,0 +1,76 @@
+import { ToolsInteract } from '../../../src/interact/index.js'
+import * as Observe from '../../../src/observe/index.js'
+
+async function runTests() {
+  console.log('Starting observe_until unit tests...')
+
+  const origFind = (ToolsInteract as any).findElementHandler
+  const origReadLog = (Observe as any).ToolsObserve.readLogStreamHandler
+  const origGetLogs = (Observe as any).ToolsObserve.getLogsHandler
+  const origGetFp = (Observe as any).ToolsObserve.getScreenFingerprintHandler
+  const origResolveObserve = (Observe as any).ToolsObserve.resolveObserve
+  const origGetScreenFp = (Observe as any).ToolsObserve.getScreenFingerprintHandler
+
+  try {
+    // Timeout / snapshot case: ensure snapshot captured when condition not met
+    const origCapture = (Observe as any).ToolsObserve.captureDebugSnapshotHandler
+    ;(Observe as any).ToolsObserve.captureDebugSnapshotHandler = async ({ reason }: any) => ({ reason, fingerprint: 'snap-123', ui_tree: null, logs: [] })
+    // make findElement always fail
+    (ToolsInteract as any).findElementHandler = async () => ({ found: false })
+    const resTimeout = await ToolsInteract.observeUntilHandler({ type: 'ui', query: 'WillNeverExist', timeoutMs: 500, pollIntervalMs: 100, platform: 'android' })
+    const okTimeout = resTimeout && !(resTimeout as any).success && (resTimeout as any).snapshot && (resTimeout as any).snapshot.fingerprint === 'snap-123' && (resTimeout as any).telemetry && (resTimeout as any).telemetry.pollCount > 0
+    console.log('Timeout Snapshot Test:', okTimeout ? 'PASS' : 'FAIL', JSON.stringify((resTimeout as any).telemetry || {}, null, 2))
+    ;(Observe as any).ToolsObserve.captureDebugSnapshotHandler = origCapture
+
+    // UI condition: findElement returns found on 2nd call
+    let calls = 0
+    ;(ToolsInteract as any).findElementHandler = async (args) => {
+      calls++
+      const query = (args && (args.query || args)) || ''
+      if (calls >= 2) return { found: true, element: { text: query } }
+      return { found: false }
+    }
+
+    const resUi = await ToolsInteract.observeUntilHandler({ type: 'ui', query: 'Generate Session', timeoutMs: 3000, pollIntervalMs: 100, platform: 'android' })
+    const okUi = resUi && (resUi as any).success && (resUi as any).telemetry && (resUi as any).telemetry.pollCount > 0 && (resUi as any).telemetry.timeToMatch >= 0
+    console.log('UI Test:', okUi ? 'PASS' : 'FAIL', JSON.stringify((resUi as any).telemetry || {}, null, 2))
+
+    // Log condition: stream empty, snapshot contains matching line
+    ;(Observe as any).ToolsObserve.readLogStreamHandler = async () => ({ entries: [ { message: 'nothing' } ] })
+    let glCalls = 0
+    ;(Observe as any).ToolsObserve.getLogsHandler = async () => {
+      glCalls++
+      if (glCalls === 1) return { device: {}, logs: ['INFO start'] }
+      return { device: {}, logs: ['INFO start', 'ERROR Exception occurred', 'Server: Boom'] }
+    }
+
+    const resLog = await ToolsInteract.observeUntilHandler({ type: 'log', query: 'Server', timeoutMs: 3000, pollIntervalMs: 100, platform: 'android' })
+    const okLog = resLog && (resLog as any).success && (resLog as any).telemetry && (resLog as any).telemetry.pollCount > 0 && (resLog as any).telemetry.matchSource === 'log-snapshot'
+    console.log('Log Test:', okLog ? 'PASS' : 'FAIL', JSON.stringify((resLog as any).telemetry || {}, null, 2))
+
+    // Screen condition: fingerprint changes after a few polls
+    let seq = ['A', 'A', 'B']
+    ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = async () => ({ fingerprint: seq.length ? seq.shift() : null })
+    const resScreen = await ToolsInteract.observeUntilHandler({ type: 'screen', timeoutMs: 3000, pollIntervalMs: 100, platform: 'android' })
+    const okScreen = resScreen && (resScreen as any).success && (resScreen as any).telemetry && (resScreen as any).telemetry.matchSource === 'screen-fingerprint'
+    console.log('Screen Test:', okScreen ? 'PASS' : 'FAIL', JSON.stringify((resScreen as any).telemetry || {}, null, 2))
+
+    // Idle condition: stable fingerprints observed
+    let idleSeq = ['X', 'X', 'X']
+    ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = async () => ({ fingerprint: idleSeq.length ? idleSeq.shift() : 'X' })
+    const resIdle = await ToolsInteract.observeUntilHandler({ type: 'idle', timeoutMs: 3000, pollIntervalMs: 100, platform: 'android' })
+    const okIdle = resIdle && (resIdle as any).success && (resIdle as any).telemetry && (resIdle as any).telemetry.matchSource === 'idle-stable'
+    console.log('Idle Test:', okIdle ? 'PASS' : 'FAIL', JSON.stringify((resIdle as any).telemetry || {}, null, 2))
+
+  } finally {
+    ;(ToolsInteract as any).findElementHandler = origFind
+    ;(Observe as any).ToolsObserve.readLogStreamHandler = origReadLog
+    ;(Observe as any).ToolsObserve.getLogsHandler = origGetLogs
+    ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = origGetFp
+    ;(Observe as any).ToolsObserve.resolveObserve = origResolveObserve
+    ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = origGetScreenFp
+    ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = origGetScreenFp
+  }
+}
+
+runTests().catch(console.error)

package/test/unit/index.ts

@@ -13,5 +13,6 @@ import '../manage/unit/mcp_disable_autodetect.test.ts'
 import '../interact/unit/wait_for_screen_change.test.ts'
 import '../observe/unit/capture_debug_snapshot.test.ts'
 import '../observe/unit/find_element.test.ts'
+import '../interact/unit/observe_until.test.ts'
 
 console.log('Unit tests loaded.')