mobile-debug-mcp 0.20.0 → 0.21.0

package/README.md

@@ -2,7 +2,10 @@
 
 A minimal, secure MCP server for AI-assisted mobile development. Build, install, and inspect Android/iOS apps from an MCP-compatible client.
 
-> **Note:** iOS support is limited currently, Please use with caution and report any issues.
+> **Note:**
+> * iOS only tested on simulator.
+> * Flutter iOS projects not fetching logs
+> * React native not tested
 
 ## Requirements
 
@@ -28,10 +31,9 @@ You will need to add ADB_PATH for Android and XCRUN_PATH and IDB_PATH for iOS.
 
 ## Usage
 
-Example: 
-After a crash tell the agent the following:
-
-I have a crash on the app, can you diagnose it, fix and validate using the mcp tools available
+Examples: 
+* I have a crash on the app, can you diagnose it, fix and validate using the mcp tools available
+* Add a button, hook into the repository and confirm API request successful
 
 ## Docs
 

package/dist/interact/index.js

@@ -3,7 +3,6 @@ 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';
@@ -259,167 +258,204 @@ export class ToolsInteract {
         }
         return { success: false, reason: 'timeout', lastFingerprint, elapsedMs: Date.now() - start };
     }
-    static async observeUntilHandler({ type, query, timeoutMs = 5000, pollIntervalMs = 200, platform, deviceId }) {
+    static async observeUntilHandler({ type = 'ui', query, timeoutMs = 30000, pollIntervalMs = 300, includeSnapshotOnFailure = true, match = 'present', stability_ms = 700, observationDelayMs = 0, platform, deviceId }) {
         const start = Date.now();
         const deadline = start + (timeoutMs || 0);
         const q = (query === null || query === undefined) ? '' : String(query);
-        // Baseline state
+        // Clamp polling interval to 250-500ms for consistent behavior
+        const pollInterval = Math.max(250, Math.min(pollIntervalMs || 300, 500));
+        // Baseline state (fetch in parallel but bound to short timeouts so observation starts promptly)
         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;
+            const fpPromise = ToolsObserve.getScreenFingerprintHandler({ platform, deviceId });
+            const logsPromise = ToolsObserve.getLogsHandler({ platform, deviceId, lines: 200 });
+            const withTimeout = (p, ms) => 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.fingerprint ?? null;
+            if (gl) {
+                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));
+                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) => 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 = null;
+        let matchedAt = null;
+        let lastObservedState = null;
+        let stableDuration = 0;
         let matchSource = null;
         while (Date.now() <= deadline) {
             pollCount++;
-            try {
-                if (type === 'ui') {
-                    // fast findElement with short timeout to avoid blocking
+            const now = Date.now();
+            // Evaluate condition per type
+            if (type === 'ui') {
+                try {
+                    // Lightweight UI check: fetch UI tree and perform a normalized substring match to reduce overhead
                     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 } };
+                        // Bound the UI tree fetch to avoid long blocking calls; prefer quick failure over hanging a poll
+                        const withTimeout = (p, ms) => Promise.race([p, new Promise(resolve => setTimeout(() => resolve(null), ms))]);
+                        const tree = await withTimeout(ToolsObserve.getUITreeHandler({ platform, deviceId }), Math.min(pollInterval, 500));
+                        const elems = Array.isArray(tree && tree.elements) ? tree.elements : [];
+                        const qnorm = q.toLowerCase();
+                        let matched = 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;
                             }
                         }
-                        // 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 } };
+                        const isPresent = !!matched;
+                        const conditionTrue = (match === 'present') ? isPresent : !isPresent;
+                        if (conditionTrue) {
+                            if (matchedAt === null)
+                                matchedAt = Date.now();
+                            stableDuration = Date.now() - matchedAt;
+                            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(log) error:', err);
+                        console.error('observeUntil(ui) tree 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(ui) find error:', err);
+                }
+            }
+            else if (type === 'log') {
+                try {
+                    // Logs: presence semantics only (match 'present'). Stability not applicable (immediate)
+                    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)) {
+                            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 };
                         }
                     }
-                    catch (err) {
-                        console.error('observeUntil(screen) error:', err);
+                    const gl = await ToolsObserve.getLogsHandler({ platform, deviceId, lines: 200 });
+                    const logsArr = Array.isArray(gl && gl.logs) ? gl.logs : [];
+                    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)) {
+                            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 };
+                        }
                     }
                 }
-                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();
+                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) {
+                        // when screen changed, require stability_ms where fingerprint remains the same
+                        if (matchedAt === null)
+                            matchedAt = now;
+                        const confirmFp = (await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }))?.fingerprint ?? null;
+                        if (confirmFp === fp) {
+                            stableDuration = Date.now() - matchedAt;
+                            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 {
-                            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 } };
-                            }
+                            matchedAt = null;
+                            stableDuration = 0;
+                            lastObservedState = false;
                         }
                     }
-                    catch (err) {
-                        console.error('observeUntil(idle) error:', err);
-                    }
+                }
+                catch (err) {
+                    console.error('observeUntil(screen) error:', err);
                 }
             }
-            catch (err) {
-                console.error('observeUntil: unexpected 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();
+                        matchedAt = null;
+                        stableDuration = 0;
+                        lastObservedState = false;
+                    }
+                    else {
+                        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);
+                }
             }
             // 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 = 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/dist/manage/android.js

@@ -64,10 +64,13 @@ export class AndroidManage {
                 const spawnOpts = { cwd: apkPath, env };
                 if (useWrapper) {
                     await fs.chmod(wrapperPath, 0o755).catch(() => { });
+                    // Run wrapper directly to avoid shell splitting of args
+                    spawnOpts.shell = false;
+                }
+                else {
+                    // Execute gradle directly without a shell so paths with spaces are preserved
                     spawnOpts.shell = false;
                 }
-                else
-                    spawnOpts.shell = true;
                 const proc = spawn(execCmd, gradleArgs, spawnOpts);
                 let stderr = '';
                 await new Promise((resolve, reject) => {

package/dist/scripts/capture_ui_after_tap.mjs

@@ -0,0 +1,43 @@
+import { ToolsObserve } from '../observe/index.js'
+import { ToolsInteract } from '../interact/index.js'
+
+async function main() {
+  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
+
+  console.log('Tap then capture UI tree snapshots')
+  try {
+    // Tap generate
+    const found = await (await import('../interact/index.js')).ToolsInteract.findElementHandler({ query: 'Generate Session', platform, timeoutMs: 3000, exact: true, deviceId: device })
+    console.log('Found generate?', !!(found && found.found), JSON.stringify(found && found.element || {}))
+    if (found && found.found && found.element && found.element.tapCoordinates) {
+      await (await import('../interact/index.js')).ToolsInteract.tapHandler({ platform, x: found.element.tapCoordinates.x, y: found.element.tapCoordinates.y, deviceId: device })
+      console.log('Tapped Generate at', found.element.tapCoordinates)
+    } else {
+      console.log('Could not find generate element — aborting capture')
+      process.exit(2)
+    }
+
+    // Capture UI trees and screenshot repeatedly for 20s
+    const start = Date.now()
+    const outDir = '/tmp/mcp_ui_captures'
+    try { await import('fs').then(fs=>fs.promises.mkdir(outDir,{recursive:true})) } catch(e){}
+    let i = 0
+    while (Date.now() - start < 20000) {
+      const snap = await ToolsObserve.getUITreeHandler({ platform, deviceId: device })
+      const fname = `${outDir}/ui_${Date.now()}_${i}.json`
+      await import('fs').then(fs=>fs.promises.writeFile(fname, JSON.stringify(snap,null,2)))
+      console.log('Saved', fname)
+      i++
+      await new Promise(r=>setTimeout(r,500))
+    }
+
+    console.log('Capture complete')
+    process.exit(0)
+  } catch (e) {
+    console.error('Error during capture:', e)
+    process.exit(1)
+  }
+}
+
+main()

package/dist/scripts/check_play_observe.mjs

@@ -0,0 +1,18 @@
+import { ToolsInteract } from '../interact/index.js'
+
+async function main() {
+  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
+  const timeout = parseInt(process.argv.includes('--timeout') ? process.argv[process.argv.indexOf('--timeout')+1] : '120000')
+  console.log('Running observeUntil for Play session, platform=', platform, 'device=', device)
+  try {
+    const res = await ToolsInteract.observeUntilHandler({ type: 'ui', query: 'Play session', match: 'present', timeoutMs: timeout, pollIntervalMs: 300, stability_ms: 700, platform, deviceId: device })
+    console.log('observeUntil result:', JSON.stringify(res, null, 2))
+    process.exit(res && res.success ? 0 : 2)
+  } catch (e) {
+    console.error('Error running observeUntil:', e)
+    process.exit(1)
+  }
+}
+
+main()

package/dist/scripts/check_play_substring.mjs

@@ -0,0 +1,38 @@
+import { ToolsObserve } from '../observe/index.js'
+
+async function main() {
+  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
+  const timeout = parseInt(process.argv.includes('--timeout') ? process.argv[process.argv.indexOf('--timeout')+1] : '120000')
+  const start = Date.now()
+  const out = []
+  console.log('Searching UI trees for elements containing "play" (case-insensitive)')
+  while (Date.now() - start < timeout) {
+    try {
+      const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId: device })
+      const elements = Array.isArray((tree && tree.elements)) ? tree.elements : []
+      const matches = []
+      const norm = (s)=> s ? String(s).toLowerCase() : ''
+      for (const el of elements) {
+        const text = norm(el.text)
+        const content = norm(el.contentDescription || el.contentDesc || el.accessibilityLabel)
+        const rid = norm(el.resourceId || el.id)
+        const cls = norm(el.type || el.class)
+        if (text.includes('play') || content.includes('play') || rid.includes('play') || cls.includes('play') || text.includes('session') || content.includes('session')) {
+          matches.push({ el: el, foundIn: { text: text.includes('play')? 'text': text.includes('session')? 'text-session': null } })
+        }
+      }
+      if (matches.length) {
+        console.log('Matches found:', JSON.stringify(matches, null, 2))
+        out.push({ ts: Date.now(), matches })
+        break
+      }
+    } catch (e) { console.error('UITree fetch err:', e) }
+    await new Promise(r=>setTimeout(r, 500))
+  }
+  console.log('Search complete. Results count=', out.length)
+  if (out.length > 0) process.exit(0)
+  process.exit(2)
+}
+
+main()

package/dist/scripts/dump_ui_tree.mjs

@@ -0,0 +1,20 @@
+import { ToolsObserve } from '../observe/index.js'
+
+async function main() {
+  const argv = process.argv.slice(2)
+  const opts = {}
+  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]
+  }
+  try {
+    const tree = await ToolsObserve.getUITreeHandler({ platform: opts.platform || 'android', deviceId: opts.deviceId })
+    console.log(JSON.stringify(tree, null, 2))
+    process.exit(0)
+  } catch (e) {
+    console.error('failed to get ui tree:', e instanceof Error ? e.message : String(e))
+    process.exit(2)
+  }
+}
+
+main()

package/dist/scripts/observe-test.mjs

@@ -0,0 +1,32 @@
+import { ToolsObserve } from '../observe/index.js'
+import { ToolsInteract } from '../interact/index.js'
+
+async function main() {
+  console.log('Starting log stream for com.ideamechanics.modul8')
+  try {
+    const start = await ToolsObserve.startLogStreamHandler({ platform: 'ios', packageName: 'com.ideamechanics.modul8', sessionId: 'test-session' })
+    console.log('startLogStream result:', JSON.stringify(start))
+  } catch (e) {
+    console.error('startLogStream failed:', e instanceof Error ? e.message : String(e))
+  }
+
+  console.log('\nPlease press the Generate Session button in the app now. Observing for network idle (15s timeout)...')
+
+  try {
+    const res = await ToolsInteract.observeUntilHandler({ type: 'network_idle', timeoutMs: 15000, pollIntervalMs: 300, platform: 'ios' })
+    console.log('observeUntil result:')
+    console.log(JSON.stringify(res, null, 2))
+  } catch (e) {
+    console.error('observeUntil failed:', e instanceof Error ? e.message : String(e))
+  }
+
+  console.log('\nStopping log stream (best-effort)')
+  try {
+    const stop = await ToolsObserve.stopLogStreamHandler({ platform: 'ios', sessionId: 'test-session' })
+    console.log('stopLogStream result:', JSON.stringify(stop))
+  } catch (e) { console.error('stopLogStream failed:', e) }
+
+  process.exit(0)
+}
+
+main().catch(err => { console.error(err); process.exit(1) })

package/dist/scripts/press_and_observe.mjs

@@ -0,0 +1,90 @@
+import { ToolsObserve } from '../observe/index.js'
+import { ToolsInteract } from '../interact/index.js'
+
+async function main() {
+  const bundle = 'com.ideamechanics.modul8'
+  const sessionId = 'press-test'
+  console.log('Starting log stream for', bundle)
+  try {
+    const start = await ToolsObserve.startLogStreamHandler({ platform: 'ios', packageName: bundle, sessionId })
+    console.log('startLogStream result:', JSON.stringify(start))
+  } catch (e) {
+    console.error('startLogStream failed:', e instanceof Error ? e.message : String(e))
+  }
+
+  // Try to find the Generate Session element
+  console.log('\nSearching for "Generate Session" UI element...')
+  let el = null
+  try {
+    const found = await ToolsInteract.findElementHandler({ query: 'Generate Session', exact: false, timeoutMs: 3000, platform: 'ios' })
+    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 error:', e instanceof Error ? e.message : String(e))
+  }
+
+  // If found, tap it. Otherwise, try tapping a best-effort coordinate in center of screen
+  try {
+    if (el && el.tapCoordinates) {
+      console.log('Tapping matched element at', JSON.stringify(el.tapCoordinates))
+      await ToolsInteract.tapHandler({ platform: 'ios', x: el.tapCoordinates.x, y: el.tapCoordinates.y })
+    } else {
+      console.log('Element not found; attempting center tap as fallback')
+      // attempt a center tap (may be harmless)
+      await ToolsInteract.tapHandler({ platform: 'ios', x: 200, y: 400 })
+    }
+  } catch (e) {
+    console.error('Tap failed:', e instanceof Error ? e.message : String(e))
+  }
+
+  console.log('\nObserving until network_idle (30s timeout)')
+  // Start a parallel log monitor to print network-like lines as they appear
+  // Print all log lines originating from the app bundle for inspection
+  let seenIds = new Set()
+  let monitorActive = true
+  const monitor = (async () => {
+    while (monitorActive) {
+      try {
+        const stream = await ToolsObserve.readLogStreamHandler({ platform: 'ios', sessionId, limit: 200 })
+        const entries = (stream && Array.isArray(stream.entries)) ? stream.entries : []
+        for (const ent of entries) {
+          const id = JSON.stringify(ent).slice(0,200)
+          if (seenIds.has(id)) continue
+          seenIds.add(id)
+          const msg = ent && (ent.message || ent.msg || ent) ? (ent.message || ent.msg || ent) : ''
+          // Print only lines that reference the app bundle
+          if (String(msg).includes('Modul8') || String(msg).includes('modul8') || (ent && ent.process && String(ent.process).toLowerCase().includes('modul8'))) {
+            console.log('[APP LOG]', new Date().toISOString(), JSON.stringify({ message: msg }))
+          }
+        }
+      } catch (e) { console.error('log monitor error:', e instanceof Error ? e.message : String(e)) }
+      await new Promise(r => setTimeout(r, 300))
+    }
+  })()
+
+  let observeResult = null
+  try {
+    observeResult = await ToolsInteract.observeUntilHandler({ type: 'network_idle', timeoutMs: 30000, pollIntervalMs: 300, platform: 'ios', includeSnapshotOnFailure: true })
+    console.log('observeUntil result:')
+    console.log(JSON.stringify(observeResult, null, 2))
+  } catch (e) {
+    console.error('observeUntil failed:', e instanceof Error ? e.message : String(e))
+  }
+
+  // Stop monitor
+  monitorActive = false
+
+  console.log('\nStopping log stream (best-effort)')
+  try {
+    const stop = await ToolsObserve.stopLogStreamHandler({ platform: 'ios', sessionId })
+    console.log('stopLogStream result:', JSON.stringify(stop))
+  } catch (e) { console.error('stopLogStream failed:', e) }
+
+  process.exit(0)
+}
+
+main().catch(err => { console.error(err); process.exit(1) })