mobile-debug-mcp 0.21.3 → 0.21.5

package/dist/interact/index.js

@@ -4,6 +4,16 @@ export { AndroidInteract, iOSInteract };
 import { resolveTargetDevice } from '../utils/resolve-device.js';
 import { ToolsObserve } from '../observe/index.js';
 export class ToolsInteract {
+    static _normalize(s) {
+        if (s === null || s === undefined)
+            return '';
+        try {
+            return String(s).toLowerCase().trim();
+        }
+        catch {
+            return '';
+        }
+    }
     static async getInteractionService(platform, deviceId) {
         const effectivePlatform = platform || 'android';
         const resolved = await resolveTargetDevice({ platform: effectivePlatform, deviceId });
@@ -34,7 +44,7 @@ export class ToolsInteract {
         // Try to use observe layer to fetch the current UI tree and perform a fast semantic search
         const start = Date.now();
         const deadline = start + timeoutMs;
-        const normalize = (s) => (s === null || s === undefined) ? '' : String(s).toLowerCase().trim();
+        const normalize = ToolsInteract._normalize;
         const q = normalize(query);
         if (!q)
             return { found: false, error: 'Empty query' };
@@ -215,9 +225,188 @@ export class ToolsInteract {
         const scoreVal = Math.min(1, Number(bestScore.toFixed(3)));
         return { found: true, element: outEl, score: scoreVal, confidence: scoreVal };
     }
-    static async waitForUIHandler({ type = 'ui', query, timeoutMs = 30000, pollIntervalMs = 300, includeSnapshotOnFailure = true, match = 'present', stability_ms = 700, observationDelayMs = 0, platform, deviceId }) {
-        // Backwards-compatible wrapper that delegates to the core waitForUICore implementation
-        return await ToolsInteract.waitForUICore({ type, query, timeoutMs, pollIntervalMs, includeSnapshotOnFailure, match, stability_ms, observationDelayMs, platform, deviceId });
+    static async waitForUIHandler({ selector, condition = 'exists', timeout_ms = 60000, poll_interval_ms = 300, match, retry = { max_attempts: 1, backoff_ms: 0 }, platform, deviceId }) {
+        const overallStart = Date.now();
+        // Validate selector: require at least one non-empty field (text, resource_id, or accessibility_id)
+        const hasText = typeof selector?.text === 'string' && selector.text.trim().length > 0;
+        const hasResId = typeof selector?.resource_id === 'string' && selector.resource_id.trim().length > 0;
+        const hasAccId = typeof selector?.accessibility_id === 'string' && selector.accessibility_id.trim().length > 0;
+        if (!hasText && !hasResId && !hasAccId) {
+            return {
+                status: 'timeout',
+                error: {
+                    code: 'INVALID_SELECTOR',
+                    message: 'Selector must include at least one non-empty field: text, resource_id, or accessibility_id'
+                },
+                metrics: { latency_ms: Date.now() - overallStart, poll_count: 0, attempts: 0 }
+            };
+        }
+        // Validate condition
+        if (!['exists', 'not_exists', 'visible', 'clickable'].includes(condition)) {
+            return { status: 'timeout', error: { code: 'INVALID_CONDITION', message: `Unsupported condition: ${condition}` }, metrics: { latency_ms: Date.now() - overallStart, poll_count: 0, attempts: 0 } };
+        }
+        // Platform check
+        if (platform && !['android', 'ios'].includes(platform)) {
+            return { status: 'timeout', error: { code: 'PLATFORM_NOT_SUPPORTED', message: `Unsupported platform: ${platform}` }, metrics: { latency_ms: Date.now() - overallStart, poll_count: 0, attempts: 0 } };
+        }
+        const effectivePoll = Math.max(50, Math.min(poll_interval_ms || 300, 2000));
+        const maxAttempts = (retry && retry.max_attempts) ? Math.max(1, retry.max_attempts) : 1;
+        const backoff = (retry && retry.backoff_ms) ? Math.max(0, retry.backoff_ms) : 0;
+        let attempts = 0;
+        let totalPollCount = 0;
+        // Precompute normalized selector values and helpers (constant across polls)
+        const normalize = ToolsInteract._normalize;
+        const containsFlag = !!selector?.contains;
+        const selText = normalize(selector?.text);
+        const selRid = normalize(selector?.resource_id);
+        const selAid = normalize(selector?.accessibility_id);
+        try {
+            while (attempts < maxAttempts) {
+                attempts++;
+                const attemptStart = Date.now();
+                const deadline = attemptStart + (timeout_ms || 0);
+                while (Date.now() <= deadline) {
+                    totalPollCount++;
+                    try {
+                        const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId });
+                        const elements = (tree && Array.isArray(tree.elements)) ? tree.elements : [];
+                        const matches = [];
+                        for (let i = 0; i < elements.length; i++) {
+                            const el = elements[i];
+                            let ok = true;
+                            // text
+                            if (selector.text !== undefined && selector.text !== null) {
+                                const val = normalize(el.text || el.label || el.value || '');
+                                if (containsFlag) {
+                                    if (!val.includes(selText))
+                                        ok = false;
+                                }
+                                else {
+                                    if (val !== selText)
+                                        ok = false;
+                                }
+                            }
+                            // resource_id
+                            if (ok && selector.resource_id !== undefined && selector.resource_id !== null) {
+                                const rid = normalize(el.resourceId || el.resourceID || el.id || '');
+                                if (containsFlag) {
+                                    if (!rid.includes(selRid))
+                                        ok = false;
+                                }
+                                else {
+                                    if (rid !== selRid)
+                                        ok = false;
+                                }
+                            }
+                            // accessibility_id
+                            if (ok && selector.accessibility_id !== undefined && selector.accessibility_id !== null) {
+                                const aid = normalize(el.contentDescription || el.contentDesc || el.accessibilityLabel || el.label || '');
+                                if (containsFlag) {
+                                    if (!aid.includes(selAid))
+                                        ok = false;
+                                }
+                                else {
+                                    if (aid !== selAid)
+                                        ok = false;
+                                }
+                            }
+                            if (ok)
+                                matches.push({ el, idx: i });
+                        }
+                        // Evaluate condition
+                        const matchedCount = matches.length;
+                        const pickIndex = (typeof match?.index === 'number') ? match.index : undefined;
+                        let chosen = null;
+                        if (matches.length > 0) {
+                            if (pickIndex !== undefined) {
+                                // If a specific index is requested but out of bounds, treat as not matched for this poll (deterministic)
+                                if (pickIndex >= 0 && pickIndex < matches.length)
+                                    chosen = matches[pickIndex];
+                                else
+                                    chosen = null;
+                            }
+                            else {
+                                chosen = matches[0];
+                            }
+                        }
+                        else {
+                            chosen = null;
+                        }
+                        let conditionMet = false;
+                        if (condition === 'exists') {
+                            // when an index is specified, existence requires that specific index be present
+                            conditionMet = (pickIndex !== undefined) ? (chosen !== null) : (matchedCount >= 1);
+                        }
+                        else if (condition === 'not_exists') {
+                            // when an index is specified, not_exists is true if that index is absent
+                            conditionMet = (pickIndex !== undefined) ? (chosen === null) : (matchedCount === 0);
+                        }
+                        else if (condition === 'visible') {
+                            if (chosen) {
+                                const b = chosen.el.bounds;
+                                const visibleFlag = !!chosen.el.visible && Array.isArray(b) && b.length >= 4 && (b[2] > b[0] && b[3] > b[1]);
+                                conditionMet = visibleFlag;
+                            }
+                            else
+                                conditionMet = false;
+                        }
+                        else if (condition === 'clickable') {
+                            if (chosen) {
+                                const b = chosen.el.bounds;
+                                const visibleFlag = !!chosen.el.visible && Array.isArray(b) && b.length >= 4 && (b[2] > b[0] && b[3] > b[1]);
+                                const enabled = !!chosen.el.enabled;
+                                const clickable = !!chosen.el.clickable || !!chosen.el._interactable;
+                                conditionMet = visibleFlag && enabled && clickable;
+                            }
+                            else
+                                conditionMet = false;
+                        }
+                        if (conditionMet) {
+                            const now = Date.now();
+                            const latency_ms = now - overallStart;
+                            // Build element output per spec
+                            const outEl = chosen ? {
+                                text: chosen.el.text ?? null,
+                                resource_id: chosen.el.resourceId ?? chosen.el.resourceID ?? chosen.el.id ?? null,
+                                accessibility_id: chosen.el.contentDescription ?? chosen.el.contentDesc ?? chosen.el.accessibilityLabel ?? chosen.el.label ?? null,
+                                class: chosen.el.type ?? chosen.el.class ?? null,
+                                bounds: Array.isArray(chosen.el.bounds) && chosen.el.bounds.length >= 4 ? chosen.el.bounds : null,
+                                index: chosen.idx
+                            } : null;
+                            return {
+                                status: 'success',
+                                matched: matchedCount,
+                                element: outEl,
+                                metrics: { latency_ms, poll_count: totalPollCount, attempts }
+                            };
+                        }
+                    }
+                    catch (e) {
+                        // Non-fatal per-poll error; record and continue
+                        console.warn('waitForUI: poll error (non-fatal):', e instanceof Error ? e.message : String(e));
+                    }
+                    // Sleep until next poll
+                    await new Promise(r => setTimeout(r, effectivePoll || 50));
+                }
+                // Attempt timed out; if more attempts allowed, backoff then retry
+                if (attempts < maxAttempts) {
+                    if (backoff > 0)
+                        await new Promise(r => setTimeout(r, backoff));
+                    continue;
+                }
+                // Final failure for this call
+                const elapsed = Date.now() - overallStart;
+                return {
+                    status: 'timeout',
+                    error: { code: 'ELEMENT_NOT_FOUND', message: `Condition ${condition} not satisfied within timeout` },
+                    metrics: { latency_ms: elapsed, poll_count: totalPollCount, attempts }
+                };
+            }
+        }
+        catch (err) {
+            const elapsed = Date.now() - overallStart;
+            return { status: 'timeout', error: { code: 'INTERNAL_ERROR', message: err instanceof Error ? err.message : String(err) }, metrics: { latency_ms: elapsed, poll_count: totalPollCount, attempts } };
+        }
     }
     // Helper: normalize various log objects into plain message strings for comparison
     static _logsToMessages(logsArr) {

package/dist/observe/android.js

@@ -171,11 +171,13 @@ export class AndroidObserve {
                 return ta - tb;
             });
             const limited = filtered.slice(-Math.max(0, effectiveLimit));
-            return { device: deviceInfo, logs: limited, logCount: limited.length };
+            const source = pidArg ? 'pid' : (appId ? 'package' : 'broad');
+            const meta = { pidArg, appIdProvided: !!appId, filters: { tag, level, contains, since_seconds, limit: effectiveLimit }, pidExplicit: !!pid };
+            return { device: deviceInfo, logs: limited, logCount: limited.length, source, meta };
         }
         catch (e) {
             console.error("Error fetching logs:", e);
-            return { device: deviceInfo, logs: [], logCount: 0 };
+            return { device: deviceInfo, logs: [], logCount: 0, source: 'broad', meta: { error: e instanceof Error ? e.message : String(e) } };
         }
     }
     async captureScreen(deviceId) {

package/dist/observe/index.js

@@ -46,8 +46,8 @@ export class ToolsObserve {
             const crashLines = logs.filter(entry => /FATAL EXCEPTION/i.test(entry.message));
             const anyFilterApplied = !!(appId || pid || tag || level || contains || since_seconds);
             if (anyFilterApplied && logs.length === 0)
-                return { device: response.device, logs: [], crashLines: [], logCount: 0, error: { code: 'LOGS_UNAVAILABLE', message: 'No logs match filters' } };
-            return { device: response.device, logs, crashLines, logCount: response.logCount };
+                return { device: response.device, logs: [], crashLines: [], logCount: 0, source: response.source, meta: response.meta, error: { code: 'LOGS_UNAVAILABLE', message: 'No logs match filters' } };
+            return { device: response.device, logs, crashLines, logCount: response.logCount, source: response.source, meta: response.meta };
         }
         else {
             const resp = await observe.getLogs(filters);
@@ -55,8 +55,8 @@ export class ToolsObserve {
             const crashLines = logs.filter(entry => /FATAL EXCEPTION/i.test(entry.message));
             const anyFilterApplied = !!(appId || pid || tag || level || contains || since_seconds);
             if (anyFilterApplied && logs.length === 0)
-                return { device: resp.device, logs: [], crashLines: [], logCount: 0, error: { code: 'LOGS_UNAVAILABLE', message: 'No logs match filters' } };
-            return { device: resp.device, logs, crashLines, logCount: resp.logCount };
+                return { device: resp.device, logs: [], crashLines: [], logCount: 0, source: resp.source, meta: resp.meta, error: { code: 'LOGS_UNAVAILABLE', message: 'No logs match filters' } };
+            return { device: resp.device, logs, crashLines, logCount: resp.logCount, source: resp.source, meta: resp.meta };
         }
     }
     static async startLogStreamHandler({ platform, packageName, level, sessionId, deviceId }) {

package/dist/observe/ios.js

@@ -101,16 +101,41 @@ export class iOSObserve {
             // default to last 60s to keep quick
             args.push('--last', '60s');
         }
+        let processNameUsed = undefined;
         if (appId) {
             validateBundleId(appId);
-            // constrain to subsystem or process matching appId
-            args.push('--predicate', `subsystem contains "${appId}" or process == "${appId}"`);
+            // prefer matching the simple process name (last segment of bundle id), but also match full bundle id in subsystem
+            const parts = appId.split('.');
+            const simpleName = parts[parts.length - 1];
+            processNameUsed = simpleName;
+            // predicate: match process by simple name or full bundle id, or subsystem contains bundle id
+            args.push('--predicate', `process == "${simpleName}" or process == "${appId}" or subsystem contains "${appId}"`);
         }
         else if (tag) {
             // predicate by subsystem/category
             args.push('--predicate', `subsystem contains "${tag}"`);
         }
         try {
+            // Attempt pid detection if appId provided and no explicit pid supplied — prefer process name derived from bundle id
+            let detectedPid = null;
+            if (appId && !pid) {
+                const parts = appId.split('.');
+                const simpleName = parts[parts.length - 1];
+                try {
+                    const pgrepRes = await execCommand(['simctl', 'spawn', deviceId, 'pgrep', '-f', simpleName], deviceId);
+                    const out = pgrepRes && pgrepRes.output ? pgrepRes.output.trim() : '';
+                    const firstLine = out.split(/\r?\n/).find(Boolean);
+                    if (firstLine) {
+                        const n = Number(firstLine.trim());
+                        if (!isNaN(n) && n > 0)
+                            detectedPid = n;
+                    }
+                }
+                catch {
+                    // ignore pgrep failures — we'll fall back to process/bundle matching
+                }
+            }
+            const effectivePid = pid || detectedPid || null;
             const result = await execCommand(args, deviceId);
             const device = await getIOSDeviceMetadata(deviceId);
             const rawLines = result.output ? result.output.split(/\r?\n/).filter(Boolean) : [];
@@ -187,12 +212,13 @@ export class iOSObserve {
             // tag filter
             if (tag)
                 filtered = filtered.filter(e => e.tag && e.tag.includes(tag));
-            // pid filter
-            if (pid)
-                filtered = filtered.filter(e => e.pid === pid);
+            // pid filter (use detected/effective pid if available)
+            const pidToFilter = effectivePid;
+            if (pidToFilter)
+                filtered = filtered.filter(e => e.pid === pidToFilter);
             // If appId present but no predicate returned lines, try substring match
             if (appId && filtered.length === 0) {
-                const matched = parsed.filter(e => (e.message && e.message.includes(appId)) || (e.tag && e.tag.includes(appId)));
+                const matched = parsed.filter(e => (e.message && e.message.includes(appId)) || (e.tag && e.tag.includes(appId)) || (e.message && processNameUsed && e.message.includes(processNameUsed)));
                 if (matched.length > 0)
                     filtered = matched;
             }
@@ -202,13 +228,15 @@ export class iOSObserve {
                 const tb = b.timestamp ? new Date(b.timestamp).getTime() : 0;
                 return ta - tb;
             });
+            const source = pidToFilter ? 'pid' : (appId ? 'process' : 'broad');
+            const meta = { appIdProvided: !!appId, processNameUsed: processNameUsed || null, detectedPid: detectedPid || null, filters: { tag, level, contains, since_seconds, limit: effectiveLimit }, pidExplicit: !!pid };
             const limited = filtered.slice(-Math.max(0, effectiveLimit));
-            return { device, logs: limited, logCount: limited.length };
+            return { device, logs: limited, logCount: limited.length, source, meta };
         }
         catch (err) {
             console.error('iOS getLogs failed:', err);
             const device = await getIOSDeviceMetadata(deviceId);
-            return { device, logs: [], logCount: 0 };
+            return { device, logs: [], logCount: 0, source: 'broad', meta: { error: err instanceof Error ? err.message : String(err) } };
         }
     }
     async captureScreenshot(deviceId = "booted") {
@@ -383,7 +411,8 @@ export class iOSObserve {
     }
     async startLogStream(bundleId, deviceId = 'booted', sessionId = 'default') {
         try {
-            const predicate = `process == "${bundleId}" or subsystem contains "${bundleId}"`;
+            const simple = bundleId.split('.').pop() || bundleId;
+            const predicate = `process == "${simple}" or process == "${bundleId}" or subsystem contains "${bundleId}"`;
             if (iosActiveLogStreams.has(sessionId)) {
                 try {
                     iosActiveLogStreams.get(sessionId).proc.kill();

package/dist/server.js

@@ -322,17 +322,24 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: "wait_for_ui",
-            description: "Wait for a UI/log/screen/idle condition with a stability window before returning success.",
+            description: "Deterministic UI wait primitive. Waits for selector condition with retries and backoff.",
             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 },
+                    selector: {
+                        type: "object",
+                        properties: {
+                            text: { type: "string" },
+                            resource_id: { type: "string" },
+                            accessibility_id: { type: "string" },
+                            contains: { type: "boolean", description: "When true, perform substring matching", default: false }
+                        }
+                    },
+                    condition: { type: "string", enum: ["exists", "not_exists", "visible", "clickable"], default: "exists" },
+                    timeout_ms: { type: "number", default: 60000 },
+                    poll_interval_ms: { type: "number", default: 300 },
+                    match: { type: "object", properties: { index: { type: "number" } } },
+                    retry: { type: "object", properties: { max_attempts: { type: "number", default: 1 }, backoff_ms: { type: "number", default: 0 } } },
                     platform: { type: "string", enum: ["android", "ios"], description: "Optional platform override" },
                     deviceId: { type: "string", description: "Optional device serial/udid" }
                 }
@@ -574,7 +581,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const filtered = !!(pid || tag || level || contains || since_seconds || appId);
             return {
                 content: [
-                    { type: 'text', text: JSON.stringify({ device: res.device, result: { count: res.logCount, filtered, crashLines: (res.crashLines || []) } }, null, 2) },
+                    { type: 'text', text: JSON.stringify({ device: res.device, result: { count: res.logCount, filtered, crashLines: (res.crashLines || []), source: res.source, meta: res.meta || {} } }, null, 2) },
                     { type: 'text', text: JSON.stringify({ logs: res.logs }, null, 2) }
                 ]
             };
@@ -629,8 +636,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             return wrapResponse(res);
         }
         if (name === "wait_for_ui") {
-            const { type = 'ui', query, timeoutMs = 30000, pollIntervalMs = 300, includeSnapshotOnFailure = true, match = 'present', stability_ms = 700, observationDelayMs = 0, platform, deviceId } = (args || {});
-            const res = await ToolsInteract.waitForUIHandler({ type, query, timeoutMs, pollIntervalMs, includeSnapshotOnFailure, match, stability_ms, observationDelayMs, platform, deviceId });
+            const { selector, condition = 'exists', timeout_ms = 60000, poll_interval_ms = 300, match, retry, platform, deviceId } = (args || {});
+            const res = await ToolsInteract.waitForUIHandler({ selector, condition, timeout_ms, poll_interval_ms, match, retry, platform, deviceId });
             return wrapResponse(res);
         }
         if (name === "find_element") {

package/docs/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.21.5]
+- Fixed incorrect timeout
+
+## [0.21.4]
+- updated `wait_for_ui` with better contract and observability
+- update `get_logs` to get better output
+
 ## [0.21.3]
 - Added structured logs
 

package/docs/tools/observe.md

@@ -4,7 +4,7 @@ Tools that retrieve device state, logs, screenshots and UI hierarchies.
 
 ## get_logs
 
-Fetch recent logs as structured entries optimized for AI agents.
+Fetch recent logs as structured entries optimized for AI agents. Use logs as a debugging aid only — prefer UI validation (wait_for_ui) first.
 
 Input (example):
 
@@ -16,16 +16,26 @@ Defaults:
 
 - No filters → return the most recent 50 log entries (app-scoped if appId provided), across all levels.
 
+When to use get_logs:
+
+- After a UI validation (wait_for_ui) fails to confirm the expected outcome.
+- When you suspect a crash, error, or silent failure that the UI doesn't expose.
+- To provide additional debugging context correlated with an action.
+
+Do NOT use get_logs as the primary signal for success/failure, or call it repeatedly without new actions.
+
 Response (structured):
 
 ```json
-{ "device": { "platform": "android", "id": "emulator-5554" }, "logs": [ { "timestamp": "2026-03-30T16:00:00.000Z", "level": "ERROR", "tag": "MyTag", "pid": 1234, "message": "Something failed" } ], "count": 1, "filtered": true }
+{ "device": { "platform": "android", "id": "emulator-5554" }, "logs": [ { "timestamp": "2026-03-30T16:00:00.000Z", "level": "ERROR", "tag": "MyTag", "pid": 1234, "message": "Something failed" } ], "logCount": 1, "source": "pid|package|process|broad", "meta": { "filters": { "tag": "MyTag", "level": "ERROR" }, "pidArg": 1234 } }
 ```
 
 Notes:
 
 - Each log entry: timestamp (ISO), level (VERBOSE|DEBUG|INFO|WARN|ERROR), tag (string), pid (number|null), message (string).
-- Logs ordered oldest → newest. count equals number of entries returned. filtered is true if any filter was applied.
+- Logs ordered oldest → newest. logCount equals number of entries returned.
+- `source`: indicates how logs were filtered at collection time. Values: `pid` (filtered by process id), `package` / `process` (filtered by app/package/bundle), or `broad` (unfiltered system logs).
+- `meta`: debugging information about filters and collection method (e.g., pid detection, effective limit).
 - Supported filters: pid, tag, level, contains, since_seconds, limit.
 - Platform behaviour: Android uses `adb logcat` with source-side filters where possible; iOS uses unified logging (`log show`/simctl) and maps subsystem/category → tag.
 - Errors are returned as structured objects with `error.code` and `error.message`. Possible codes: LOGS_UNAVAILABLE, INVALID_FILTER, PLATFORM_NOT_SUPPORTED, INTERNAL_ERROR.

package/package.json

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

package/src/interact/index.ts

@@ -32,6 +32,12 @@ interface UiElement {
 
 export class ToolsInteract {
 
+  private static _normalize(s: any): string {
+    if (s === null || s === undefined) return ''
+    try { return String(s).toLowerCase().trim() } catch { return '' }
+  }
+
+
   private static async getInteractionService(platform?: 'android' | 'ios', deviceId?: string) {
     const effectivePlatform = platform || 'android'
     const resolved = await resolveTargetDevice({ platform: effectivePlatform as 'android' | 'ios', deviceId })
@@ -68,7 +74,7 @@ export class ToolsInteract {
     // Try to use observe layer to fetch the current UI tree and perform a fast semantic search
     const start = Date.now()
     const deadline = start + timeoutMs
-    const normalize = (s: any) => (s === null || s === undefined) ? '' : String(s).toLowerCase().trim()
+    const normalize = ToolsInteract._normalize
 
     const q = normalize(query)
     if (!q) return { found: false, error: 'Empty query' }
@@ -218,9 +224,188 @@ export class ToolsInteract {
     return { found: true, element: outEl, score: scoreVal, confidence: scoreVal }
   }
 
-  static async waitForUIHandler({ 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 }) {
-    // Backwards-compatible wrapper that delegates to the core waitForUICore implementation
-    return await ToolsInteract.waitForUICore({ type, query, timeoutMs, pollIntervalMs, includeSnapshotOnFailure, match, stability_ms, observationDelayMs, platform, deviceId })
+  static async waitForUIHandler({ selector, condition = 'exists', timeout_ms = 60000, poll_interval_ms = 300, match, retry = { max_attempts: 1, backoff_ms: 0 }, platform, deviceId }: { selector?: { text?: string, resource_id?: string, accessibility_id?: string, contains?: boolean }, condition?: 'exists'|'not_exists'|'visible'|'clickable', timeout_ms?: number, poll_interval_ms?: number, match?: { index?: number }, retry?: { max_attempts?: number, backoff_ms?: number }, platform?: 'android'|'ios', deviceId?: string }) {
+    const overallStart = Date.now()
+
+    // Validate selector: require at least one non-empty field (text, resource_id, or accessibility_id)
+    const hasText = typeof selector?.text === 'string' && selector.text.trim().length > 0;
+    const hasResId = typeof selector?.resource_id === 'string' && selector.resource_id.trim().length > 0;
+    const hasAccId = typeof selector?.accessibility_id === 'string' && selector.accessibility_id.trim().length > 0;
+
+    if (!hasText && !hasResId && !hasAccId) {
+      return {
+        status: 'timeout',
+        error: {
+          code: 'INVALID_SELECTOR',
+          message: 'Selector must include at least one non-empty field: text, resource_id, or accessibility_id'
+        },
+        metrics: { latency_ms: Date.now() - overallStart, poll_count: 0, attempts: 0 }
+      };
+    }
+
+    // Validate condition
+    if (!['exists','not_exists','visible','clickable'].includes(condition)) {
+      return { status: 'timeout', error: { code: 'INVALID_CONDITION', message: `Unsupported condition: ${condition}` }, metrics: { latency_ms: Date.now() - overallStart, poll_count: 0, attempts: 0 } }
+    }
+
+    // Platform check
+    if (platform && !['android','ios'].includes(platform)) {
+      return { status: 'timeout', error: { code: 'PLATFORM_NOT_SUPPORTED', message: `Unsupported platform: ${platform}` }, metrics: { latency_ms: Date.now() - overallStart, poll_count: 0, attempts: 0 } }
+    }
+
+    const effectivePoll = Math.max(50, Math.min(poll_interval_ms || 300, 2000))
+    const maxAttempts = (retry && retry.max_attempts) ? Math.max(1, retry.max_attempts) : 1
+    const backoff = (retry && retry.backoff_ms) ? Math.max(0, retry.backoff_ms) : 0
+
+    let attempts = 0
+    let totalPollCount = 0
+
+    // Precompute normalized selector values and helpers (constant across polls)
+    const normalize = ToolsInteract._normalize
+    const containsFlag = !!selector?.contains
+    const selText = normalize(selector?.text)
+    const selRid = normalize(selector?.resource_id)
+    const selAid = normalize(selector?.accessibility_id)
+
+    try {
+      while (attempts < maxAttempts) {
+        attempts++
+        const attemptStart = Date.now()
+        const deadline = attemptStart + (timeout_ms || 0)
+
+        while (Date.now() <= deadline) {
+          totalPollCount++
+          try {
+            const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId }) as any
+            const elements = (tree && Array.isArray(tree.elements)) ? tree.elements as any[] : []
+
+            const matches: { el: any, idx: number }[] = []
+
+            for (let i = 0; i < elements.length; i++) {
+              const el = elements[i]
+              let ok = true
+
+              // text
+              if (selector.text !== undefined && selector.text !== null) {
+                const val = normalize(el.text || el.label || el.value || '')
+                if (containsFlag) {
+                  if (!val.includes(selText)) ok = false
+                } else {
+                  if (val !== selText) ok = false
+                }
+              }
+
+              // resource_id
+              if (ok && selector.resource_id !== undefined && selector.resource_id !== null) {
+                const rid = normalize(el.resourceId || el.resourceID || el.id || '')
+                if (containsFlag) {
+                  if (!rid.includes(selRid)) ok = false
+                } else {
+                  if (rid !== selRid) ok = false
+                }
+              }
+
+              // accessibility_id
+              if (ok && selector.accessibility_id !== undefined && selector.accessibility_id !== null) {
+                const aid = normalize(el.contentDescription || el.contentDesc || el.accessibilityLabel || el.label || '')
+                if (containsFlag) {
+                  if (!aid.includes(selAid)) ok = false
+                } else {
+                  if (aid !== selAid) ok = false
+                }
+              }
+
+              if (ok) matches.push({ el, idx: i })
+            }
+
+            // Evaluate condition
+            const matchedCount = matches.length
+            const pickIndex = (typeof match?.index === 'number') ? match!.index as number : undefined
+            let chosen: { el: any, idx: number } | null = null
+            if (matches.length > 0) {
+              if (pickIndex !== undefined) {
+                // If a specific index is requested but out of bounds, treat as not matched for this poll (deterministic)
+                if (pickIndex >= 0 && pickIndex < matches.length) chosen = matches[pickIndex]
+                else chosen = null
+              } else {
+                chosen = matches[0]
+              }
+            } else {
+              chosen = null
+            }
+
+            let conditionMet = false
+            if (condition === 'exists') {
+              // when an index is specified, existence requires that specific index be present
+              conditionMet = (pickIndex !== undefined) ? (chosen !== null) : (matchedCount >= 1)
+            } else if (condition === 'not_exists') {
+              // when an index is specified, not_exists is true if that index is absent
+              conditionMet = (pickIndex !== undefined) ? (chosen === null) : (matchedCount === 0)
+            } else if (condition === 'visible') {
+              if (chosen) {
+                const b = chosen.el.bounds
+                const visibleFlag = !!chosen.el.visible && Array.isArray(b) && b.length >= 4 && (b[2] > b[0] && b[3] > b[1])
+                conditionMet = visibleFlag
+              } else conditionMet = false
+            } else if (condition === 'clickable') {
+              if (chosen) {
+                const b = chosen.el.bounds
+                const visibleFlag = !!chosen.el.visible && Array.isArray(b) && b.length >= 4 && (b[2] > b[0] && b[3] > b[1])
+                const enabled = !!chosen.el.enabled
+                const clickable = !!chosen.el.clickable || !!chosen.el._interactable
+                conditionMet = visibleFlag && enabled && clickable
+              } else conditionMet = false
+            }
+
+            if (conditionMet) {
+              const now = Date.now()
+              const latency_ms = now - overallStart
+              // Build element output per spec
+              const outEl = chosen ? {
+                text: chosen.el.text ?? null,
+                resource_id: chosen.el.resourceId ?? chosen.el.resourceID ?? chosen.el.id ?? null,
+                accessibility_id: chosen.el.contentDescription ?? chosen.el.contentDesc ?? chosen.el.accessibilityLabel ?? chosen.el.label ?? null,
+                class: chosen.el.type ?? chosen.el.class ?? null,
+                bounds: Array.isArray(chosen.el.bounds) && chosen.el.bounds.length >= 4 ? chosen.el.bounds : null,
+                index: chosen.idx
+              } : null
+
+              return {
+                status: 'success',
+                matched: matchedCount,
+                element: outEl,
+                metrics: { latency_ms, poll_count: totalPollCount, attempts }
+              }
+            }
+
+          } catch (e) {
+            // Non-fatal per-poll error; record and continue
+            console.warn('waitForUI: poll error (non-fatal):', e instanceof Error ? e.message : String(e))
+          }
+
+          // Sleep until next poll
+          await new Promise(r => setTimeout(r, effectivePoll || 50))
+        }
+
+        // Attempt timed out; if more attempts allowed, backoff then retry
+        if (attempts < maxAttempts) {
+          if (backoff > 0) await new Promise(r => setTimeout(r, backoff))
+          continue
+        }
+
+        // Final failure for this call
+        const elapsed = Date.now() - overallStart
+        return {
+          status: 'timeout',
+          error: { code: 'ELEMENT_NOT_FOUND', message: `Condition ${condition} not satisfied within timeout` },
+          metrics: { latency_ms: elapsed, poll_count: totalPollCount, attempts }
+        }
+      }
+
+    } catch (err) {
+      const elapsed = Date.now() - overallStart
+      return { status: 'timeout', error: { code: 'INTERNAL_ERROR', message: err instanceof Error ? err.message : String(err) }, metrics: { latency_ms: elapsed, poll_count: totalPollCount, attempts } }
+    }
   }
 
   // Helper: normalize various log objects into plain message strings for comparison

package/src/observe/android.ts

@@ -183,10 +183,12 @@ export class AndroidObserve {
 
       const limited = filtered.slice(-Math.max(0, effectiveLimit))
 
-      return { device: deviceInfo, logs: limited, logCount: limited.length }
+      const source = pidArg ? 'pid' : (appId ? 'package' : 'broad')
+      const meta = { pidArg, appIdProvided: !!appId, filters: { tag, level, contains, since_seconds, limit: effectiveLimit }, pidExplicit: !!pid }
+      return { device: deviceInfo, logs: limited, logCount: limited.length, source, meta }
     } catch (e) {
       console.error("Error fetching logs:", e)
-      return { device: deviceInfo, logs: [], logCount: 0 }
+      return { device: deviceInfo, logs: [], logCount: 0, source: 'broad', meta: { error: e instanceof Error ? e.message : String(e) } }
     }
   }
 

package/src/observe/index.ts

@@ -52,15 +52,15 @@ export class ToolsObserve {
       const logs = Array.isArray(response.logs) ? response.logs : []
       const crashLines = logs.filter(entry => /FATAL EXCEPTION/i.test(entry.message))
       const anyFilterApplied = !!(appId || pid || tag || level || contains || since_seconds)
-      if (anyFilterApplied && logs.length === 0) return { device: response.device, logs: [], crashLines: [], logCount: 0, error: { code: 'LOGS_UNAVAILABLE', message: 'No logs match filters' } } as any
-      return { device: response.device, logs, crashLines, logCount: response.logCount }
+      if (anyFilterApplied && logs.length === 0) return { device: response.device, logs: [], crashLines: [], logCount: 0, source: response.source, meta: response.meta, error: { code: 'LOGS_UNAVAILABLE', message: 'No logs match filters' } } as any
+      return { device: response.device, logs, crashLines, logCount: response.logCount, source: response.source, meta: response.meta }
     } else {
       const resp = await (observe as iOSObserve).getLogs(filters)
       const logs = Array.isArray(resp.logs) ? resp.logs : []
       const crashLines = logs.filter(entry => /FATAL EXCEPTION/i.test(entry.message))
       const anyFilterApplied = !!(appId || pid || tag || level || contains || since_seconds)
-      if (anyFilterApplied && logs.length === 0) return { device: resp.device, logs: [], crashLines: [], logCount: 0, error: { code: 'LOGS_UNAVAILABLE', message: 'No logs match filters' } } as any
-      return { device: resp.device, logs, crashLines, logCount: resp.logCount }
+      if (anyFilterApplied && logs.length === 0) return { device: resp.device, logs: [], crashLines: [], logCount: 0, source: resp.source, meta: resp.meta, error: { code: 'LOGS_UNAVAILABLE', message: 'No logs match filters' } } as any
+      return { device: resp.device, logs, crashLines, logCount: resp.logCount, source: resp.source, meta: resp.meta }
     }
   }
 

package/src/observe/ios.ts

@@ -136,16 +136,39 @@ export class iOSObserve {
       args.push('--last', '60s')
     }
 
+    let processNameUsed: string | undefined = undefined
     if (appId) {
       validateBundleId(appId)
-      // constrain to subsystem or process matching appId
-      args.push('--predicate', `subsystem contains "${appId}" or process == "${appId}"`)
+      // prefer matching the simple process name (last segment of bundle id), but also match full bundle id in subsystem
+      const parts = appId.split('.')
+      const simpleName = parts[parts.length - 1]
+      processNameUsed = simpleName
+      // predicate: match process by simple name or full bundle id, or subsystem contains bundle id
+      args.push('--predicate', `process == "${simpleName}" or process == "${appId}" or subsystem contains "${appId}"`)
     } else if (tag) {
       // predicate by subsystem/category
       args.push('--predicate', `subsystem contains "${tag}"`)
     }
 
     try {
+      // Attempt pid detection if appId provided and no explicit pid supplied — prefer process name derived from bundle id
+      let detectedPid: number | null = null
+      if (appId && !pid) {
+        const parts = appId.split('.')
+        const simpleName = parts[parts.length - 1]
+        try {
+          const pgrepRes = await execCommand(['simctl','spawn', deviceId, 'pgrep', '-f', simpleName], deviceId)
+          const out = pgrepRes && pgrepRes.output ? pgrepRes.output.trim() : ''
+          const firstLine = out.split(/\r?\n/).find(Boolean)
+          if (firstLine) {
+            const n = Number(firstLine.trim())
+            if (!isNaN(n) && n > 0) detectedPid = n
+          }
+        } catch {
+          // ignore pgrep failures — we'll fall back to process/bundle matching
+        }
+      }
+      const effectivePid = pid || detectedPid || null
       const result = await execCommand(args, deviceId)
       const device = await getIOSDeviceMetadata(deviceId)
       const rawLines = result.output ? result.output.split(/\r?\n/).filter(Boolean) : []
@@ -225,12 +248,13 @@ export class iOSObserve {
       // tag filter
       if (tag) filtered = filtered.filter(e => e.tag && e.tag.includes(tag))
 
-      // pid filter
-      if (pid) filtered = filtered.filter(e => e.pid === pid)
+      // pid filter (use detected/effective pid if available)
+      const pidToFilter = effectivePid
+      if (pidToFilter) filtered = filtered.filter(e => e.pid === pidToFilter)
 
       // If appId present but no predicate returned lines, try substring match
       if (appId && filtered.length === 0) {
-        const matched = parsed.filter(e => (e.message && e.message.includes(appId)) || (e.tag && e.tag.includes(appId)))
+        const matched = parsed.filter(e => (e.message && e.message.includes(appId)) || (e.tag && e.tag.includes(appId)) || (e.message && processNameUsed && e.message.includes(processNameUsed)))
         if (matched.length > 0) filtered = matched
       }
 
@@ -241,12 +265,14 @@ export class iOSObserve {
         return ta - tb
       })
 
+      const source = pidToFilter ? 'pid' : (appId ? 'process' : 'broad')
+      const meta = { appIdProvided: !!appId, processNameUsed: processNameUsed || null, detectedPid: detectedPid || null, filters: { tag, level, contains, since_seconds, limit: effectiveLimit }, pidExplicit: !!pid }
       const limited = filtered.slice(-Math.max(0, effectiveLimit))
-      return { device, logs: limited, logCount: limited.length }
+      return { device, logs: limited, logCount: limited.length, source, meta }
     } catch (err) {
       console.error('iOS getLogs failed:', err)
       const device = await getIOSDeviceMetadata(deviceId)
-      return { device, logs: [], logCount: 0 }
+      return { device, logs: [], logCount: 0, source: 'broad', meta: { error: err instanceof Error ? err.message : String(err) } }
     }
   }
 
@@ -439,7 +465,8 @@ export class iOSObserve {
 
   async startLogStream(bundleId: string, deviceId: string = 'booted', sessionId: string = 'default') : Promise<{ success: boolean; stream_started?: boolean; error?: string }> {
     try {
-      const predicate = `process == "${bundleId}" or subsystem contains "${bundleId}"`
+      const simple = bundleId.split('.').pop() || bundleId
+      const predicate = `process == "${simple}" or process == "${bundleId}" or subsystem contains "${bundleId}"`
 
       if (iosActiveLogStreams.has(sessionId)) {
         try { iosActiveLogStreams.get(sessionId)!.proc.kill() } catch {}

package/src/server.ts

@@ -347,17 +347,24 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: "wait_for_ui",
-      description: "Wait for a UI/log/screen/idle condition with a stability window before returning success.",
+      description: "Deterministic UI wait primitive. Waits for selector condition with retries and backoff.",
       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 },
+          selector: {
+            type: "object",
+            properties: {
+              text: { type: "string" },
+              resource_id: { type: "string" },
+              accessibility_id: { type: "string" },
+              contains: { type: "boolean", description: "When true, perform substring matching", default: false }
+            }
+          },
+          condition: { type: "string", enum: ["exists","not_exists","visible","clickable"], default: "exists" },
+          timeout_ms: { type: "number", default: 60000 },
+          poll_interval_ms: { type: "number", default: 300 },
+          match: { type: "object", properties: { index: { type: "number" } } },
+          retry: { type: "object", properties: { max_attempts: { type: "number", default: 1 }, backoff_ms: { type: "number", default: 0 } } },
           platform: { type: "string", enum: ["android","ios"], description: "Optional platform override" },
           deviceId: { type: "string", description: "Optional device serial/udid" }
         }
@@ -365,6 +372,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
 
 
+
     {
       name: "find_element",
       description: "Find a UI element by semantic query (text, content-desc, resource-id, class). Returns best match.",
@@ -614,7 +622,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request: SchemaOutput<typ
       const filtered = !!(pid || tag || level || contains || since_seconds || appId)
       return {
         content: [
-          { type: 'text', text: JSON.stringify({ device: res.device, result: { count: res.logCount, filtered, crashLines: (res.crashLines || []) } }, null, 2) },
+          { type: 'text', text: JSON.stringify({ device: res.device, result: { count: res.logCount, filtered, crashLines: (res.crashLines || []), source: res.source, meta: res.meta || {} } }, null, 2) },
           { type: 'text', text: JSON.stringify({ logs: res.logs }, null, 2) }
         ]
       }
@@ -680,8 +688,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request: SchemaOutput<typ
 
 
     if (name === "wait_for_ui") {
-      const { type = 'ui', query, timeoutMs = 30000, pollIntervalMs = 300, includeSnapshotOnFailure = true, match = 'present', stability_ms = 700, observationDelayMs = 0, platform, deviceId } = (args || {}) as any
-      const res = await ToolsInteract.waitForUIHandler({ type, query, timeoutMs, pollIntervalMs, includeSnapshotOnFailure, match, stability_ms, observationDelayMs, platform, deviceId })
+      const { selector, condition = 'exists', timeout_ms = 60000, poll_interval_ms = 300, match, retry, platform, deviceId } = (args || {}) as any
+      const res = await ToolsInteract.waitForUIHandler({ selector, condition, timeout_ms, poll_interval_ms, match, retry, platform, deviceId })
       return wrapResponse(res)
     }
 

package/src/types.ts

@@ -48,6 +48,10 @@ export interface GetLogsResponse {
   device: DeviceInfo;
   logs: StructuredLogEntry[];
   logCount: number;
+  // Source indicates the filtering method used: 'pid', 'package'/'process', or 'broad'
+  source?: string;
+  // Meta contains debugging information about how logs were collected and filters applied
+  meta?: Record<string, any>;
 }
 
 export interface GetCrashResponse {

package/test/interact/unit/wait_for_ui_contract.test.ts

@@ -0,0 +1,33 @@
+import { ToolsInteract } from '../../../src/interact/index.js'
+import * as Observe from '../../../src/observe/index.js'
+import assert from 'assert'
+
+async function run() {
+  console.log('Starting wait_for_ui contract tests...')
+  const orig = (Observe as any).ToolsObserve.getUITreeHandler
+
+  try {
+    // success shape
+    (Observe as any).ToolsObserve.getUITreeHandler = async () => ({ elements: [ { text: 'OK', resourceId: 'rid', contentDescription: 'acc', type: 'TextView', bounds: [0,0,10,10], visible: true, clickable: false, enabled: true } ] })
+    const s = await ToolsInteract.waitForUIHandler({ selector: { text: 'OK' }, condition: 'exists', timeout_ms: 500, poll_interval_ms: 50, platform: 'android' })
+    // Assert contract fields for success
+    assert.strictEqual(s.status, 'success', 'status must be success')
+    assert.strictEqual(typeof s.matched, 'number', 'matched must be number')
+    assert.ok(s.element, 'element must be present')
+    assert.ok(s.metrics && typeof s.metrics.latency_ms === 'number' && typeof s.metrics.poll_count === 'number' && typeof s.metrics.attempts === 'number', 'metrics must include latency_ms, poll_count, attempts')
+    assert.ok(['string','object'].includes(typeof s.element.bounds) || Array.isArray(s.element.bounds), 'element.bounds must be present')
+
+    // timeout shape
+    (Observe as any).ToolsObserve.getUITreeHandler = async () => ({ elements: [] })
+    const t = await ToolsInteract.waitForUIHandler({ selector: { text: 'Nope' }, condition: 'exists', timeout_ms: 200, poll_interval_ms: 50, platform: 'android' })
+    assert.strictEqual(t.status, 'timeout', 'status must be timeout on no match')
+    assert.ok(t.error && t.error.code && t.error.message, 'timeout must include error with code and message')
+    assert.ok(t.metrics && typeof t.metrics.latency_ms === 'number', 'timeout metrics must include latency_ms')
+
+    console.log('wait_for_ui contract tests: PASS')
+  } finally {
+    ;(Observe as any).ToolsObserve.getUITreeHandler = orig
+  }
+}
+
+run().catch(err => { console.error('wait_for_ui_contract tests failed:', err); process.exit(1) })

package/test/interact/unit/wait_for_ui_new.test.ts

@@ -0,0 +1,57 @@
+import { ToolsInteract } from '../../../src/interact/index.js'
+import * as Observe from '../../../src/observe/index.js'
+
+async function run() {
+  console.log('Starting new wait_for_ui unit tests...')
+  const origGetUITree = (Observe as any).ToolsObserve.getUITreeHandler
+
+  try {
+    // Test 1: exact text match -> exists
+    (Observe as any).ToolsObserve.getUITreeHandler = async () => ({ elements: [ { text: 'Hello', resourceId: 'rid1', contentDescription: 'acc1', type: 'Button', bounds: [0,0,10,10], visible: true, clickable: false, enabled: true } ] })
+    const r1 = await ToolsInteract.waitForUIHandler({ selector: { text: 'Hello' }, condition: 'exists', timeout_ms: 1000, poll_interval_ms: 50, platform: 'android' })
+    const ok1 = r1 && r1.status === 'success' && r1.matched === 1 && r1.element && r1.element.text === 'Hello'
+    console.log('Exact match exists:', ok1 ? 'PASS' : 'FAIL', JSON.stringify(r1, null, 2))
+
+    // Test 2: contains matching
+    (Observe as any).ToolsObserve.getUITreeHandler = async () => ({ elements: [ { text: 'Welcome User', resourceId: 'rid2', contentDescription: 'acc2', type: 'TextView', bounds: [0,0,50,10], visible: true } ] })
+    const r2 = await ToolsInteract.waitForUIHandler({ selector: { text: 'User', contains: true }, condition: 'exists', timeout_ms: 1000, poll_interval_ms: 50, platform: 'android' })
+    const ok2 = r2 && r2.status === 'success' && r2.matched === 1 && r2.element && r2.element.text && r2.element.text.includes('Welcome')
+    console.log('Contains match:', ok2 ? 'PASS' : 'FAIL', JSON.stringify(r2, null, 2))
+
+    // Test 3: visible condition
+    (Observe as any).ToolsObserve.getUITreeHandler = async () => ({ elements: [ { text: 'Hidden', resourceId: 'rid3', bounds: [0,0,0,0], visible: false } ] })
+    const r3 = await ToolsInteract.waitForUIHandler({ selector: { text: 'Hidden' }, condition: 'visible', timeout_ms: 300, poll_interval_ms: 50, platform: 'android' })
+    const ok3 = r3 && r3.status === 'timeout' && r3.error && r3.error.code === 'ELEMENT_NOT_FOUND'
+    console.log('Visible negative (hidden element):', ok3 ? 'PASS' : 'FAIL', JSON.stringify(r3, null, 2))
+
+    // Test 4: clickable condition
+    (Observe as any).ToolsObserve.getUITreeHandler = async () => ({ elements: [ { text: 'TapMe', resourceId: 'rid4', bounds: [0,0,20,20], visible: true, clickable: true, enabled: true } ] })
+    const r4 = await ToolsInteract.waitForUIHandler({ selector: { text: 'TapMe' }, condition: 'clickable', timeout_ms: 1000, poll_interval_ms: 50, platform: 'android' })
+    const ok4 = r4 && r4.status === 'success' && r4.matched === 1 && r4.element && r4.element.index === 0
+    console.log('Clickable match:', ok4 ? 'PASS' : 'FAIL', JSON.stringify(r4, null, 2))
+
+    // Test 5: retry behavior - first attempt times out, second attempt succeeds
+    const start = Date.now()
+    let seqTree = async () => {
+      const now = Date.now()
+      // for first ~400ms return no elements, afterwards return match
+      if (now - start < 400) return { elements: [] }
+      return { elements: [ { text: 'Retried', resourceId: 'rid5', bounds: [0,0,10,10], visible: true } ] }
+    }
+    ;(Observe as any).ToolsObserve.getUITreeHandler = seqTree
+    const r5 = await ToolsInteract.waitForUIHandler({ selector: { text: 'Retried' }, condition: 'exists', timeout_ms: 200, poll_interval_ms: 50, match: undefined, retry: { max_attempts: 3, backoff_ms: 150 }, platform: 'android' })
+    const ok5 = r5 && r5.status === 'success' && r5.metrics && r5.metrics.attempts >= 2
+    console.log('Retry behavior:', ok5 ? 'PASS' : 'FAIL', JSON.stringify(r5, null, 2))
+
+    // Test 6: timeout with no selector match -> correct error code
+    (Observe as any).ToolsObserve.getUITreeHandler = async () => ({ elements: [] })
+    const r6 = await ToolsInteract.waitForUIHandler({ selector: { text: 'Nope' }, condition: 'exists', timeout_ms: 300, poll_interval_ms: 50, retry: { max_attempts: 1 }, platform: 'android' })
+    const ok6 = r6 && r6.status === 'timeout' && r6.error && r6.error.code === 'ELEMENT_NOT_FOUND'
+    console.log('Timeout no match:', ok6 ? 'PASS' : 'FAIL', JSON.stringify(r6, null, 2))
+
+  } finally {
+    (Observe as any).ToolsObserve.getUITreeHandler = origGetUITree
+  }
+}
+
+run().catch(err => { console.error('wait_for_ui_new tests failed:', err); process.exit(1) })

package/test/observe/unit/ios-getlogs.test.ts

@@ -0,0 +1,67 @@
+import { iOSObserve } from '../../../src/observe/ios'
+import assert from 'assert'
+
+// Lightweight unit tests: verify predicate construction and meta extraction logic using internal functions
+// Since getLogs executes xcrun, run tests in SKIP_DEVICE_TESTS=1 environment by stubbing execCommand where possible.
+
+import * as iosUtils from '../../../src/utils/ios/utils'
+
+function stubExecCommand(original: any, expectedArgsChecker: (args: string[]) => boolean, output: string) {
+  return async function (args: string[], deviceId?: string) {
+    if (!expectedArgsChecker(args)) throw new Error('Unexpected args: ' + JSON.stringify(args))
+    return { output, device: { platform: 'ios', id: deviceId || 'booted' } }
+  }
+}
+
+describe('iOS getLogs predicate and meta', () => {
+  let obs: iOSObserve
+  beforeEach(() => {
+    obs = new iOSObserve()
+  })
+
+  it('uses simple process name predicate when appId provided', async () => {
+    const bundle = 'com.ideamechanics.modul8'
+    // stub execCommand twice: first for pgrep, second for log show
+    const pgrepOutput = '12345\n'
+    const logOutput = '2026-03-31 09:21:20.085 Module[12345:678] <Info> Modul8: Test message'
+
+    const orig = (iosUtils as any).execCommand
+    try {
+      (iosUtils as any).execCommand = stubExecCommand(orig, (args) => args.includes('pgrep'), pgrepOutput)
+      // second replacement for the log show call
+      let called = false
+      (iosUtils as any).execCommand = async function (args: string[]) {
+        if (args.includes('pgrep')) return { output: pgrepOutput, device: { platform: 'ios', id: 'booted' } }
+        if (args.includes('log') && args.includes('show')) { called = true; return { output: logOutput, device: { platform: 'ios', id: 'booted' } } }
+        throw new Error('Unexpected args: ' + JSON.stringify(args))
+      }
+
+      const res = await obs.getLogs({ appId: bundle, deviceId: 'booted' })
+      assert(res.meta.processNameUsed === 'modul8' || res.meta.processNameUsed === 'Modul8' || !!res.meta.processNameUsed)
+      assert(res.meta.detectedPid === 12345)
+      assert(res.source === 'pid')
+      assert(res.logCount === 1)
+      assert(res.logs[0].message.includes('Test message'))
+      assert(called, 'log show must have been called')
+    } finally {
+      (iosUtils as any).execCommand = orig
+    }
+  })
+
+  it('falls back to broad when no appId', async () => {
+    const logOutput = '2026-03-31 09:21:20.085 SomeOther[222:333] <Info> Other: Hello'
+    const orig = (iosUtils as any).execCommand
+    try {
+      (iosUtils as any).execCommand = async function (args: string[]) {
+        if (args.includes('log') && args.includes('show')) return { output: logOutput, device: { platform: 'ios', id: 'booted' } }
+        throw new Error('Unexpected args: ' + JSON.stringify(args))
+      }
+      const obs = new iOSObserve()
+      const res = await obs.getLogs({ deviceId: 'booted' })
+      assert(res.source === 'broad')
+      assert(res.logCount === 1)
+    } finally {
+      (iosUtils as any).execCommand = orig
+    }
+  })
+})

package/test/manage/device/run-install-kmp.ts

@@ -1,18 +0,0 @@
-#!/usr/bin/env node
-import { ToolsManage } from '../../../dist/manage/index.js'
-import path from 'path'
-
-async function main() {
-  // Prefer a repo-local sample modul8 project if present, otherwise allow overriding via KMP_PROJECT env var
-  const defaultRelative = path.join(process.cwd(), '..', '..', '..', '..', 'test-fixtures', 'modul8')
-  const project = process.env.KMP_PROJECT || defaultRelative
-  console.log('Running KMP build+install for project', project)
-  // Use projectType=kmp and let handler pick android by default for KMP
-  // Request iOS explicitly for this run to test iOS build path
-  const res = await ToolsManage.buildAndInstallHandler({ platform: 'ios', projectPath: project, projectType: 'kmp', timeout: 600000, deviceId: undefined })
-  console.log(JSON.stringify(res, null, 2))
-  if (res.result && res.result.success) process.exit(0)
-  process.exit(1)
-}
-
-main().catch(e => { console.error(e); process.exit(2) })