mobile-debug-mcp 0.26.2 → 0.26.3

package/AGENTS.md

@@ -41,11 +41,14 @@ Portable agent skills live under `skills/`.
 - `skills/README.md` — repo-wide skill convention
 - `skills/mcp-builder/` — build/install/toolchain guidance
 - `skills/test-authoring/` — test creation and placement guidance
+- `skills/rfc-review/` — RFC review rubric and response template
 
 If the task is about **creating or updating tests**, load `skills/test-authoring/SKILL.md` first.
 
 If the task is about **building, installing, or diagnosing native tooling**, load `skills/mcp-builder/SKILL.md` first.
 
+If the task is about **reviewing an RFC or spec draft**, load `skills/rfc-review/SKILL.md` first.
+
 ### Repository docs
 
 - `README.md` — high-level repo overview and commands

package/dist/interact/index.js

@@ -203,6 +203,22 @@ export class ToolsInteract {
             semantic: element.semantic ?? null
         };
     }
+    static _summarizeResolutionCandidate(candidate) {
+        const bounds = ToolsInteract._normalizeBounds(candidate.el.bounds);
+        return {
+            text: candidate.el.text ?? null,
+            resource_id: candidate.el.resourceId ?? candidate.el.resourceID ?? candidate.el.id ?? null,
+            accessibility_id: candidate.el.contentDescription ?? candidate.el.contentDesc ?? candidate.el.accessibilityLabel ?? candidate.el.label ?? null,
+            class: candidate.el.type ?? candidate.el.class ?? null,
+            bounds: bounds
+                ? { left: bounds[0], top: bounds[1], right: bounds[2], bottom: bounds[3] }
+                : null,
+            clickable: !!candidate.el.clickable,
+            enabled: !!candidate.el.enabled,
+            score: candidate.score,
+            reason: candidate.reason
+        };
+    }
     static _actionFailure(actionType, selector, resolved, failureCode, retryable, uiFingerprintBefore, uiFingerprintAfter, sourceModule = 'interact') {
         return buildActionExecutionResult({
             actionType,
@@ -419,17 +435,18 @@ export class ToolsInteract {
         if (!q)
             return { found: false, error: 'Empty query' };
         let best = null;
-        let bestScore = 0;
-        let lastTree = null;
-        const scoreElement = (el) => {
+        let bestTree = null;
+        let bestIterationCandidates = [];
+        let shouldStop = false;
+        const scoreElement = (el, idx) => {
             if (!el || !el.visible)
-                return 0;
+                return null;
             const bounds = el.bounds || [0, 0, 0, 0];
             if (!Array.isArray(bounds) || bounds.length < 4)
-                return 0;
+                return null;
             const [l, t, r, b] = bounds;
             if (r <= l || b <= t)
-                return 0;
+                return null;
             // Do not early-return on non-interactable elements — score them so we can locate their clickable ancestor later
             const interactable = !!(el.clickable || el.enabled || el.focusable);
             const text = normalize(el.text ?? el.label ?? el.value ?? '');
@@ -437,64 +454,98 @@ export class ToolsInteract {
             const resourceId = normalize(el.resourceId ?? el.resourceID ?? el.id ?? '');
             const className = normalize(el.type ?? el.class ?? '');
             let score = 0;
+            let reason = 'best_scoring_candidate';
             if (exact) {
-                if (text && text === q)
+                if (text && text === q) {
                     score = 1.0;
-                else if (content && content === q)
+                    reason = 'exact_text_match';
+                }
+                else if (content && content === q) {
                     score = 0.95;
+                    reason = 'exact_content_desc_match';
+                }
+                else if (resourceId && resourceId === q) {
+                    score = 0.92;
+                    reason = 'exact_resource_id_match';
+                }
+                else if (className && className === q) {
+                    score = 0.3;
+                    reason = 'exact_class_match';
+                }
             }
             else {
-                if (text && text === q)
+                if (text && text === q) {
                     score = 1.0;
-                else if (content && content === q)
+                    reason = 'exact_text_match';
+                }
+                else if (content && content === q) {
                     score = 0.95;
-                else if (text && text.includes(q))
+                    reason = 'exact_content_desc_match';
+                }
+                else if (resourceId && resourceId === q) {
+                    score = 0.92;
+                    reason = 'exact_resource_id_match';
+                }
+                else if (text && text.includes(q)) {
                     score = 0.6;
-                else if (content && content.includes(q))
+                    reason = 'partial_text_match';
+                }
+                else if (content && content.includes(q)) {
                     score = 0.55;
-                else if (resourceId && resourceId.includes(q))
+                    reason = 'partial_content_desc_match';
+                }
+                else if (resourceId && resourceId.includes(q)) {
                     score = 0.7;
-                else if (className && className.includes(q))
+                    reason = 'partial_resource_id_match';
+                }
+                else if (className && className.includes(q)) {
                     score = 0.3;
+                    reason = 'partial_class_match';
+                }
             }
             if (score > 0 && interactable)
                 score += 0.05;
-            return score;
+            if (score <= 0)
+                return null;
+            return { el, idx, score, reason, interactable };
         };
         while (Date.now() <= deadline) {
             try {
                 const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId });
-                lastTree = tree;
                 if (tree && Array.isArray(tree.elements)) {
                     const elements = tree.elements;
+                    const iterationCandidates = [];
+                    let iterationImprovedBest = false;
                     for (let i = 0; i < elements.length; i++) {
                         const el = elements[i];
                         try {
-                            const s = scoreElement(el);
-                            const interactable = !!(el.clickable || el.enabled || el.focusable);
-                            if (s > bestScore) {
-                                bestScore = s;
-                                best = el;
-                                if (best) {
-                                    best._index = i;
-                                    best._interactable = interactable;
+                            const candidate = scoreElement(el, i);
+                            if (!candidate)
+                                continue;
+                            iterationCandidates.push(candidate);
+                            if (!best || candidate.score > best.score) {
+                                best = candidate;
+                                bestTree = tree;
+                                iterationImprovedBest = true;
+                                if (best.score >= 0.95) {
+                                    shouldStop = true;
+                                    break;
                                 }
                             }
-                            if (bestScore >= 0.95)
-                                break;
                         }
                         catch (e) {
                             console.error('Error scoring element:', e);
                         }
                     }
-                    if (bestScore >= 0.95)
-                        break;
+                    if (iterationImprovedBest) {
+                        bestIterationCandidates = iterationCandidates.slice();
+                    }
                 }
             }
             catch (e) {
                 console.error('Error fetching UI tree:', e);
             }
-            if (Date.now() > deadline)
+            if (shouldStop || Date.now() > deadline)
                 break;
             await new Promise(r => setTimeout(r, 100));
         }
@@ -502,17 +553,17 @@ export class ToolsInteract {
             return { found: false, error: 'Element not found' };
         // If the best match is not interactable, try to resolve an actionable ancestor.
         try {
-            const elements = (lastTree && Array.isArray(lastTree.elements)) ? lastTree.elements : [];
-            const screen = lastTree?.resolution && typeof lastTree.resolution === 'object' ? lastTree.resolution : null;
+            const elements = (bestTree && Array.isArray(bestTree.elements)) ? bestTree.elements : [];
+            const screen = bestTree?.resolution && typeof bestTree.resolution === 'object' ? bestTree.resolution : null;
             let chosen = best;
-            const childBounds = Array.isArray(chosen?.bounds) ? chosen.bounds : null;
+            const childBounds = Array.isArray(chosen?.el?.bounds) ? chosen.el.bounds : null;
             // Strategy 1: if parentId references an index, climb that chain
             let resolvedAncestor = null;
-            if (childBounds && (chosen.parentId !== undefined && chosen.parentId !== null)) {
+            if (childBounds && (chosen.el.parentId !== undefined && chosen.el.parentId !== null)) {
                 let cur = chosen;
                 let safety = 0;
-                while (cur && safety < 20 && !(cur.clickable || cur.focusable) && (cur.parentId !== undefined && cur.parentId !== null)) {
-                    let pid = cur.parentId;
+                while (cur && safety < 20 && !(cur.el.clickable || cur.el.focusable) && (cur.el.parentId !== undefined && cur.el.parentId !== null)) {
+                    let pid = cur.el.parentId;
                     let idx = null;
                     if (typeof pid === 'number')
                         idx = pid;
@@ -520,18 +571,19 @@ export class ToolsInteract {
                         idx = Number(pid);
                     // If parentId is not an index, try to find by matching resourceId or id field
                     if (idx !== null && elements[idx]) {
-                        cur = elements[idx];
-                        if (cur && (cur.clickable || cur.enabled || cur.focusable)) {
+                        cur = { el: elements[idx], idx };
+                        if (cur && (cur.el.clickable || cur.el.enabled || cur.el.focusable)) {
                             resolvedAncestor = cur;
                             break;
                         }
                     }
                     else if (typeof pid === 'string') {
                         // fallback: search elements for matching resourceId or id
-                        const found = elements.find((el) => (el.resourceId === pid || el.id === pid));
+                        const foundIndex = elements.findIndex((el) => (el.resourceId === pid || el.id === pid));
+                        const found = foundIndex >= 0 ? elements[foundIndex] : null;
                         if (found) {
-                            cur = found;
-                            if (cur && (cur.clickable || cur.enabled || cur.focusable)) {
+                            cur = { el: found, idx: foundIndex };
+                            if (cur && (cur.el.clickable || cur.el.enabled || cur.el.focusable)) {
                                 resolvedAncestor = cur;
                                 break;
                             }
@@ -551,16 +603,19 @@ export class ToolsInteract {
             if (!resolvedAncestor && childBounds) {
                 const [cl, ct, cr, cb] = childBounds;
                 // find candidates that are clickable and contain the child bounds
-                const candidates = elements.filter((el) => el && (el.clickable || el.focusable) && Array.isArray(el.bounds) && el.bounds.length >= 4).map((el) => ({ el, bounds: el.bounds }));
+                const candidates = elements
+                    .map((el, idx) => ({ el, idx }))
+                    .filter(({ el }) => el && (el.clickable || el.focusable) && Array.isArray(el.bounds) && el.bounds.length >= 4);
                 let bestCandidate = null;
                 let bestCandidateArea = Infinity;
                 for (const c of candidates) {
-                    const [pl, pt, pr, pb] = c.bounds;
+                    const bounds = c.el.bounds;
+                    const [pl, pt, pr, pb] = bounds;
                     if (pl <= cl && pt <= ct && pr >= cr && pb >= cb) {
                         const area = (pr - pl) * (pb - pt);
                         if (area < bestCandidateArea) {
                             bestCandidateArea = area;
-                            bestCandidate = c.el;
+                            bestCandidate = c;
                         }
                     }
                 }
@@ -568,17 +623,24 @@ export class ToolsInteract {
                     resolvedAncestor = bestCandidate;
             }
             if (resolvedAncestor) {
-                best = resolvedAncestor;
-                // small score bump to reflect actionability
-                bestScore = Math.min(1, bestScore + 0.02);
+                best = {
+                    el: resolvedAncestor.el,
+                    idx: resolvedAncestor.idx,
+                    score: Math.min(1, best.score + 0.02),
+                    reason: 'clickable_parent_preferred',
+                    interactable: true
+                };
             }
-            if (best && !(best.clickable || best.focusable)) {
-                const nearbyActionable = ToolsInteract._resolveNearbyActionableControl(elements, { el: best, idx: best._index ?? elements.indexOf(best) }, screen);
+            if (best && !(best.el.clickable || best.el.focusable)) {
+                const nearbyActionable = ToolsInteract._resolveNearbyActionableControl(elements, { el: best.el, idx: best.idx }, screen);
                 if (nearbyActionable) {
-                    best = nearbyActionable.el;
-                    best._index = nearbyActionable.idx;
-                    best._interactable = true;
-                    best._sliderLike = nearbyActionable.sliderLike;
+                    best = {
+                        el: nearbyActionable.el,
+                        idx: nearbyActionable.idx,
+                        score: Math.min(1, best.score + 0.02),
+                        reason: nearbyActionable.sliderLike ? 'slider_track_preferred' : 'nearby_actionable_control',
+                        interactable: true
+                    };
                 }
             }
         }
@@ -587,29 +649,34 @@ export class ToolsInteract {
         }
         if (!best)
             return { found: false, error: 'Element not found' };
-        const boundsObj = Array.isArray(best.bounds) ? { left: best.bounds[0], top: best.bounds[1], right: best.bounds[2], bottom: best.bounds[3] } : null;
+        const boundsObj = Array.isArray(best.el.bounds) ? { left: best.el.bounds[0], top: best.el.bounds[1], right: best.el.bounds[2], bottom: best.el.bounds[3] } : null;
         const tapCoordinates = boundsObj ? { x: Math.floor((boundsObj.left + boundsObj.right) / 2), y: Math.floor((boundsObj.top + boundsObj.bottom) / 2) } : null;
+        const uniqueRanked = bestIterationCandidates.filter((candidate, index, array) => index === array.findIndex((other) => other.idx === candidate.idx && other.el === candidate.el));
+        const alternateCandidates = uniqueRanked
+            .filter((candidate) => candidate.idx !== best.idx || candidate.el !== best.el)
+            .slice(0, 3)
+            .map((candidate) => ToolsInteract._summarizeResolutionCandidate(candidate));
         const outEl = {
-            text: best.text ?? null,
-            resourceId: best.resourceId ?? null,
-            contentDesc: best.contentDescription ?? best.contentDesc ?? null,
-            class: best.type ?? best.class ?? null,
+            text: best.el.text ?? null,
+            resourceId: best.el.resourceId ?? null,
+            contentDesc: best.el.contentDescription ?? best.el.contentDesc ?? null,
+            class: best.el.type ?? best.el.class ?? null,
             bounds: boundsObj,
-            clickable: !!best.clickable,
-            enabled: !!best.enabled,
-            stable_id: best.stable_id ?? null,
-            role: best.role ?? null,
-            test_tag: best.test_tag ?? null,
-            selector: best.selector ?? null,
-            semantic: best.semantic ?? null,
+            clickable: !!best.el.clickable,
+            enabled: !!best.el.enabled,
+            stable_id: best.el.stable_id ?? null,
+            role: best.el.role ?? null,
+            test_tag: best.el.test_tag ?? null,
+            selector: best.el.selector ?? null,
+            semantic: best.el.semantic ?? null,
             tapCoordinates,
             telemetry: {
-                matchedIndex: best?._index ?? null,
-                matchedInteractable: !!best?._interactable,
-                sliderLike: !!best?._sliderLike
+                matchedIndex: best.idx ?? null,
+                matchedInteractable: !!best.interactable,
+                sliderLike: best.reason === 'slider_track_preferred'
             }
         };
-        if (best?._sliderLike) {
+        if (best.reason === 'slider_track_preferred') {
             const isVertical = !!boundsObj && (boundsObj.bottom - boundsObj.top) > (boundsObj.right - boundsObj.left);
             const interactionHint = {
                 kind: 'slider',
@@ -618,8 +685,15 @@ export class ToolsInteract {
             };
             outEl.interactionHint = interactionHint;
         }
-        const scoreVal = Math.min(1, Number(bestScore.toFixed(3)));
-        return { found: true, element: outEl, score: scoreVal, confidence: scoreVal };
+        const scoreVal = Math.min(1, Number(best.score.toFixed(3)));
+        const resolution = {
+            confidence: scoreVal,
+            reason: best.reason,
+            fallback_available: alternateCandidates.length > 0,
+            matched_count: uniqueRanked.length,
+            alternates: alternateCandidates
+        };
+        return { found: true, element: outEl, score: scoreVal, confidence: scoreVal, resolution };
     }
     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();

package/dist/server/tool-definitions.js

@@ -596,7 +596,9 @@ Recommended Usage:
     },
     {
         name: 'find_element',
-        description: 'Find a UI element by semantic query (text, content-desc, resource-id, class). Returns best match.',
+        description: `Find a UI element by semantic query (text, content-desc, resource-id, class).
+
+Returns the best match plus resolution metadata when available, including confidence, selection reason, and fallback alternates.`,
         inputSchema: {
             type: 'object',
             properties: {

package/dist/server-core.js

@@ -6,7 +6,7 @@ import { handleToolCall } from './server/tool-handlers.js';
 export { wrapResponse, toolDefinitions, handleToolCall };
 export const serverInfo = {
     name: 'mobile-debug-mcp',
-    version: '0.26.2'
+    version: '0.26.3'
 };
 export function createServer() {
     const server = new Server(serverInfo, {

package/docs/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.26.3]
+- updates the `find_element` tool to return detailed resolution metadata, including confidence scores,
+
 ## [0.26.2]
 - unified action execution and verification model 
 

package/docs/ROADMAP.md

@@ -53,9 +53,9 @@ Higher task success with fewer retries.
 ## Upcoming Work
 
 - Adjustable Control Support
+- Better Compose / Custom Control Semantics
 - Signal-Oriented Diagnostic Filtering
 - Long Press Gesture
-- Better Compose / Custom Control Semantics
 
 ## Later Horizon
 
@@ -160,6 +160,7 @@ Addresses failures where agents:
 - wait_for_ui_change (hierarchy diff based waiting)
 - Structured loading state detection
 - Snapshot revision / staleness metadata
+- Focused snapshot views / incremental snapshot diffs
 - Compose-aware wait robustness improvements
 
 ## Expected Impact
@@ -169,6 +170,7 @@ Very high.
 - wait_for_ui_change implemented
 - Loading state detection available for representative controls
 - Snapshot revision or staleness metadata exposed
+- Focused or diff-oriented snapshots validated in benchmark flows
 - UI-first sync guidance added to spec guardrails
 - In-place update waits validated on benchmark flows
 
@@ -379,9 +381,9 @@ Strengthens:
 # Better Compose / Custom Control Semantics
 
 ## Rationale
-Important, but strengthened by earlier capabilities first.
+Higher priority after agent feedback exposed custom control semantics as a core reliability gap, not a later optimization.
 
-**Status:** Planned
+**Status:** Spec Ready
 
 Semantics become more useful once:
 - identity is stronger
@@ -419,7 +421,6 @@ Depends on:
 - Wait and Synchronization Reliability
 - Actionability Resolution
 - Adjustable Control Support
-- Signal-Oriented Diagnostic Filtering
 - Long Press Gesture
 
 ---
@@ -543,19 +544,19 @@ Make core loop more reliable.
 
 ## Wave 2 (Control Precision + Diagnostics)
 - Adjustable Control Support
+- Better Compose / Custom Control Semantics
 - Signal-Oriented Diagnostic Filtering
 
 Focus:
-Improve control precision and signal observability.
+Improve control precision, custom control semantics, and signal observability.
 
 ---
 
 ## Wave 3 (Interaction Expansion)
 - Long Press Gesture
-- Better Compose / Custom Control Semantics
 
 Focus:
-Expand interaction capability.
+Expand interaction capability after core control reliability is improved.
 
 ---
 
@@ -576,9 +577,9 @@ Roadmap Ordering:
 3. Wait and Synchronization Reliability
 4. Actionability Resolution
 5. Adjustable Control Support
-6. Signal-Oriented Diagnostic Filtering
-7. Long Press Gesture
-8. Better Compose / Custom Control Semantics
+6. Better Compose / Custom Control Semantics
+7. Signal-Oriented Diagnostic Filtering
+8. Long Press Gesture
 9. Pinch to Zoom
 10. Action Trace Correlation
 

package/docs/rfcs/007-actionability-resolution-and-executable-target-selection.md

@@ -0,0 +1,277 @@
+# RFC 007 — Actionability Resolution and Executable Target Selection
+
+## 1. Summary
+
+This RFC defines how the system resolves which discovered UI element should receive an action before dispatch.
+
+It addresses ambiguity between:
+- visible elements vs actionable elements
+- leaf nodes vs clickable containers
+- semantic targets vs coordinate fallbacks
+- multiple candidate targets with uncertain executability
+
+Goal:
+Improve first-attempt action correctness by resolving the best executable target prior to action dispatch.
+
+This RFC defines the `Resolved` stage semantics referenced in RFC 005 and operationalized by RFC 006.
+It is grounded in the existing element-resolution flow and extends current resolution behavior rather than assuming a wholly new resolver architecture.
+
+---
+
+## 2. Problem Statement
+
+Current interaction failures often arise before execution.
+
+The agent may discover the intended UI concept, but not the correct executable target.
+
+Examples:
+- tapping label text instead of clickable container
+- sliders not surfacing semantic handles
+- generic Compose containers hiding true affordances
+- multiple matching targets without ranking logic
+
+Observed failure modes:
+- false taps
+- submit ambiguity
+- coordinate guessing
+- retry loops
+- brittle fallback behavior
+
+This is a target-resolution problem, not an execution problem.
+
+---
+
+## 3. Design Goals
+
+Resolution MUST:
+- Prefer executable targets over merely visible matches
+- Reduce ambiguous target selection
+- Support confidence-based ranking
+- Build on existing runtime resolution surfaces before introducing new resolution metadata
+- Use structural and semantic resolution signals
+- Minimize coordinate fallback usage
+- Integrate with verification expectations from RFC 005
+
+---
+
+## 4. Actionability Model
+
+Candidate targets are evaluated using actionability signals.
+
+### Structural signals
+- clickable
+- enabled
+- focusable
+- bounds
+- parent action ownership
+
+### Semantic signals
+- control role
+- label association
+- affordance hints
+- selectable or adjustable semantics
+
+### Interaction signals
+- reliable target patterns
+- control-specific heuristics
+- gesture compatibility
+
+---
+
+## 4.1 Current Runtime Resolution Surfaces
+
+This RFC builds on current runtime resolution paths, including:
+- `findElementHandler` for candidate discovery
+- `_resolveActionableAncestor` for executable ancestor promotion
+- `tapElementHandler` for resolved element dispatch
+- `scrollToElementHandler` for scroll-mediated target acquisition
+
+These existing handlers are the current implementation substrate for the Resolved stage.
+This RFC extends and systematizes those behaviors; it does not assume replacement of those paths.
+
+---
+
+## 5. Target Candidate Ranking
+
+When multiple targets match, candidates are ranked.
+
+Illustrative confidence model:
+
+resolution_confidence =
+ interactability_score
+ + semantic_match_score
+ + structural_reliability_score
+
+Highest-confidence executable target is preferred.
+
+The confidence model is illustrative and normative only at the rule-precedence level; implementations may use simpler heuristics while preserving resolution ordering guarantees. Any scoring mechanism is implementation-defined and may not be externally surfaced.
+
+---
+
+## 6. Resolution Rules
+
+### Rule A — Prefer actionable containers over passive leaf nodes
+
+Prefer:
+- clickable container
+
+Over:
+- passive child text nodes
+
+Example:
+Prefer button container over "Generate Session" label node.
+
+---
+
+### Rule B — Prefer semantic controls over coordinate fallbacks
+
+Use semantic control targets whenever possible.
+
+Coordinate fallback only when:
+- no semantic target exists
+- adjustable control semantics absent
+- fallback confidence acceptable
+
+---
+
+### Rule C — Prefer explicit affordance ownership
+
+If child and parent differ:
+prefer the node owning the action handler.
+
+---
+
+## 7. Ambiguity Handling
+
+When multiple plausible targets remain:
+
+System SHOULD:
+- rank candidates
+- expose confidence
+- preserve alternates for fallback reasoning
+
+Low-confidence targets may trigger:
+- guarded execution
+- alternate resolution attempt
+- explicit recovery path
+
+---
+
+## 8. Adjustable Control Resolution
+
+Special handling for:
+- sliders
+- steppers
+- drag controls
+
+Support:
+- adjustable-role recognition
+- control-bound discovery
+- value-aware interaction targeting
+
+This RFC defines target resolution.
+Value-setting behavior remains governed by Adjustable Control Support.
+
+---
+
+## 9. Compose / Custom Control Resolution
+
+Support derived actionability for:
+- merged Compose semantics
+- composite controls
+- inferred interaction contracts
+
+This RFC depends on and strengthens Better Compose / Custom Control Semantics.
+
+---
+
+## 10. Resolution Output Model (Current + Future Extension)
+
+This model is non-normative and represents a progressive enrichment direction rather than a required runtime contract.
+
+Resolution may evolve toward the following enriched output shape. Current runtime implementations may expose only resolved-target output plus limited supporting metadata.
+
+At minimum, current implementations are expected to produce a resolved target. Confidence, alternates, fallback metadata, and reason codes may be introduced incrementally.
+
+Illustrative future-complete shape:
+
+{
+  "resolved_target": "...",
+  "confidence": 0.92,
+  "fallback_available": true,
+  "resolution_reason": "clickable_parent_preferred"
+}
+
+---
+
+## 11. Verification Integration
+
+Resolution is incomplete without verification expectations.
+
+Resolved output should be derived directly from the existing element-resolution flow before adding richer metadata layers.
+
+Resolved target should carry expected post-action signal.
+
+Examples:
+- navigation transition expected
+- menu expected
+- control value change expected
+
+This feeds RFC 005 verification.
+
+---
+
+## 12. Success Metrics
+
+Track:
+- reduced false-tap failures
+- lower retarget retries
+- higher first-attempt action success
+- reduced coordinate fallback usage
+- improved custom control interaction success
+
+---
+
+## 13. Dependencies
+
+Depends on:
+- Stronger State Verification
+- Richer Element Identity
+- Wait and Synchronization Reliability
+
+Strengthens:
+- Adjustable Control Support
+- Better Compose / Custom Control Semantics
+
+---
+
+## 14. Relationship to Other RFCs
+
+RFC 005
+Defines what Resolved means in lifecycle semantics.
+
+RFC 006
+Defines how runtime interprets action execution.
+
+RFC 007
+Defines how a target becomes Resolved.
+Specifically, it formalizes the current discovery → actionable ancestor resolution → dispatch preparation flow already present in runtime handlers.
+
+Together:
+- RFC 005 — action correctness
+- RFC 006 — runtime execution binding
+- RFC 007 — executable target resolution
+
+---
+
+## 15. Summary
+
+This RFC reduces failures caused by acting on the wrong thing, even when the right thing was discovered.
+
+It improves:
+- action precision
+- control reliability
+- Compose interaction robustness
+- agent success with fewer retries
+
+It addresses one of the largest remaining sources of interaction brittleness.

package/docs/tools/interact.md

@@ -199,7 +199,14 @@ Output:
     "telemetry": { "matchedIndex": 3, "matchedInteractable": true }
   },
   "score": 1.0,
-  "confidence": 1.0
+  "confidence": 1.0,
+  "resolution": {
+    "confidence": 1.0,
+    "reason": "exact_text_match",
+    "fallback_available": false,
+    "matched_count": 1,
+    "alternates": []
+  }
 }
 ```
 
@@ -207,6 +214,7 @@ Notes:
 
 - Best used when no precise selector is available yet.
 - `tapCoordinates` are suitable for `tap` calls.
+- `resolution` explains why the element was selected and may include fallback alternates when the runtime had to promote a parent or nearby control.
 - Prefer `wait_for_ui` when you already know a deterministic selector and want a stable `elementId`.
 
 ---

package/package.json

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

package/src/interact/index.ts

@@ -10,6 +10,7 @@ import { buildActionExecutionResult } from '../server/common.js'
 import type {
   ActionFailureCode,
   ActionTargetResolved,
+  FindElementResponse,
   ExpectElementVisibleResponse,
   ExpectStateResponse,
   ExpectScreenResponse,
@@ -68,6 +69,32 @@ interface UiChangeSignatureSet {
   state: string | null
 }
 
+interface RankedResolutionCandidate {
+  el: UiElement
+  idx: number
+  score: number
+  reason: string
+  interactable: boolean
+}
+
+interface FindElementResolutionSummary {
+  confidence: number
+  reason: string
+  fallback_available: boolean
+  matched_count: number
+  alternates: Array<{
+    text: string | null
+    resource_id: string | null
+    accessibility_id: string | null
+    class: string | null
+    bounds: { left: number; top: number; right: number; bottom: number } | null
+    clickable: boolean
+    enabled: boolean
+    score: number
+    reason: string
+  }>
+}
+
 
 export class ToolsInteract {
   private static readonly _maxResolvedUiElements = 256
@@ -290,6 +317,23 @@ export class ToolsInteract {
     }
   }
 
+  private static _summarizeResolutionCandidate(candidate: RankedResolutionCandidate): FindElementResolutionSummary['alternates'][number] {
+    const bounds = ToolsInteract._normalizeBounds(candidate.el.bounds)
+    return {
+      text: candidate.el.text ?? null,
+      resource_id: candidate.el.resourceId ?? candidate.el.resourceID ?? candidate.el.id ?? null,
+      accessibility_id: candidate.el.contentDescription ?? candidate.el.contentDesc ?? candidate.el.accessibilityLabel ?? candidate.el.label ?? null,
+      class: candidate.el.type ?? candidate.el.class ?? null,
+      bounds: bounds
+        ? { left: bounds[0], top: bounds[1], right: bounds[2], bottom: bounds[3] }
+        : null,
+      clickable: !!candidate.el.clickable,
+      enabled: !!candidate.el.enabled,
+      score: candidate.score,
+      reason: candidate.reason
+    }
+  }
+
   private static _actionFailure(
     actionType: string,
     selector: Record<string, unknown> | null,
@@ -546,7 +590,7 @@ export class ToolsInteract {
     return await interact.scrollToElement(selector, direction, maxScrolls, scrollAmount, resolved.id)
   }
 
-  static async findElementHandler({ query, exact = false, timeoutMs = 3000, platform, deviceId }: { query: string, exact?: boolean, timeoutMs?: number, platform?: 'android' | 'ios', deviceId?: string }) {
+  static async findElementHandler({ query, exact = false, timeoutMs = 3000, platform, deviceId }: { query: string, exact?: boolean, timeoutMs?: number, platform?: 'android' | 'ios', deviceId?: string }): Promise<FindElementResponse> {
     // 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
@@ -555,16 +599,17 @@ export class ToolsInteract {
     const q = normalize(query)
     if (!q) return { found: false, error: 'Empty query' }
 
-    let best: UiElement | null = null
-    let bestScore = 0
-    let lastTree: any = null
+    let best: RankedResolutionCandidate | null = null
+    let bestTree: any = null
+    let bestIterationCandidates: RankedResolutionCandidate[] = []
+    let shouldStop = false
 
-    const scoreElement = (el: UiElement | null) => {
-      if (!el || !el.visible) return 0
+    const scoreElement = (el: UiElement | null, idx: number): RankedResolutionCandidate | null => {
+      if (!el || !el.visible) return null
       const bounds = el.bounds || [0,0,0,0]
-      if (!Array.isArray(bounds) || bounds.length < 4) return 0
+      if (!Array.isArray(bounds) || bounds.length < 4) return null
       const [l,t,r,b] = bounds
-      if (r <= l || b <= t) return 0
+      if (r <= l || b <= t) return null
       // Do not early-return on non-interactable elements — score them so we can locate their clickable ancestor later
       const interactable = !!(el.clickable || el.enabled || el.focusable)
 
@@ -574,44 +619,80 @@ export class ToolsInteract {
       const className = normalize(el.type ?? el.class ?? '')
 
       let score = 0
+      let reason = 'best_scoring_candidate'
       if (exact) {
-        if (text && text === q) score = 1.0
-        else if (content && content === q) score = 0.95
+        if (text && text === q) {
+          score = 1.0
+          reason = 'exact_text_match'
+        } else if (content && content === q) {
+          score = 0.95
+          reason = 'exact_content_desc_match'
+        } else if (resourceId && resourceId === q) {
+          score = 0.92
+          reason = 'exact_resource_id_match'
+        } else if (className && className === q) {
+          score = 0.3
+          reason = 'exact_class_match'
+        }
       } else {
-        if (text && text === q) score = 1.0
-        else if (content && content === q) score = 0.95
-        else if (text && text.includes(q)) score = 0.6
-        else if (content && content.includes(q)) score = 0.55
-        else if (resourceId && resourceId.includes(q)) score = 0.7
-        else if (className && className.includes(q)) score = 0.3
+        if (text && text === q) {
+          score = 1.0
+          reason = 'exact_text_match'
+        } else if (content && content === q) {
+          score = 0.95
+          reason = 'exact_content_desc_match'
+        } else if (resourceId && resourceId === q) {
+          score = 0.92
+          reason = 'exact_resource_id_match'
+        } else if (text && text.includes(q)) {
+          score = 0.6
+          reason = 'partial_text_match'
+        } else if (content && content.includes(q)) {
+          score = 0.55
+          reason = 'partial_content_desc_match'
+        } else if (resourceId && resourceId.includes(q)) {
+          score = 0.7
+          reason = 'partial_resource_id_match'
+        } else if (className && className.includes(q)) {
+          score = 0.3
+          reason = 'partial_class_match'
+        }
       }
       if (score > 0 && interactable) score += 0.05
-      return score
+      if (score <= 0) return null
+      return { el, idx, score, reason, interactable }
     }
 
     while (Date.now() <= deadline) {
       try {
-      const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId })
-      lastTree = tree
+        const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId })
         if (tree && Array.isArray((tree as any).elements)) {
           const elements = ((tree as any).elements as UiElement[])
+          const iterationCandidates: RankedResolutionCandidate[] = []
+          let iterationImprovedBest = false
           for (let i = 0; i < elements.length; i++) {
             const el = elements[i]
             try {
-              const s = scoreElement(el)
-              const interactable = !!(el.clickable || el.enabled || (el as any).focusable)
-              if (s > bestScore) {
-                bestScore = s
-                best = el as UiElement
-                if (best) { best._index = i; best._interactable = interactable }
+              const candidate = scoreElement(el, i)
+              if (!candidate) continue
+              iterationCandidates.push(candidate)
+              if (!best || candidate.score > best.score) {
+                best = candidate
+                bestTree = tree
+                iterationImprovedBest = true
+                if (best.score >= 0.95) {
+                  shouldStop = true
+                  break
+                }
               }
-              if (bestScore >= 0.95) break
             } catch (e) { console.error('Error scoring element:', e) }
           }
-          if (bestScore >= 0.95) break
+          if (iterationImprovedBest) {
+            bestIterationCandidates = iterationCandidates.slice()
+          }
         }
       } catch (e) { console.error('Error fetching UI tree:', e) }
-      if (Date.now() > deadline) break
+      if (shouldStop || Date.now() > deadline) break
       await new Promise(r => setTimeout(r, 100))
     }
 
@@ -619,31 +700,32 @@ export class ToolsInteract {
 
     // If the best match is not interactable, try to resolve an actionable ancestor.
     try {
-      const elements = (lastTree && Array.isArray(lastTree.elements)) ? (lastTree.elements as UiElement[]) : []
-      const screen = lastTree?.resolution && typeof lastTree.resolution === 'object' ? lastTree.resolution as UiResolution : null
-      let chosen = best as any
-      const childBounds = Array.isArray(chosen?.bounds) ? chosen.bounds : null
+      const elements = (bestTree && Array.isArray(bestTree.elements)) ? (bestTree.elements as UiElement[]) : []
+      const screen = bestTree?.resolution && typeof bestTree.resolution === 'object' ? bestTree.resolution as UiResolution : null
+      let chosen = best as { el: UiElement, idx: number }
+      const childBounds = Array.isArray(chosen?.el?.bounds) ? chosen.el.bounds : null
 
       // Strategy 1: if parentId references an index, climb that chain
-      let resolvedAncestor: any = null
-      if (childBounds && (chosen.parentId !== undefined && chosen.parentId !== null)) {
+      let resolvedAncestor: { el: UiElement, idx: number } | null = null
+      if (childBounds && (chosen.el.parentId !== undefined && chosen.el.parentId !== null)) {
         let cur = chosen
         let safety = 0
-        while (cur && safety < 20 && !(cur.clickable || cur.focusable) && (cur.parentId !== undefined && cur.parentId !== null)) {
-          let pid = cur.parentId
+        while (cur && safety < 20 && !(cur.el.clickable || cur.el.focusable) && (cur.el.parentId !== undefined && cur.el.parentId !== null)) {
+          let pid = cur.el.parentId
           let idx: number | null = null
           if (typeof pid === 'number') idx = pid
           else if (typeof pid === 'string' && /^\d+$/.test(pid)) idx = Number(pid)
           // If parentId is not an index, try to find by matching resourceId or id field
           if (idx !== null && elements[idx]) {
-            cur = elements[idx]
-            if (cur && (cur.clickable || cur.enabled || cur.focusable)) { resolvedAncestor = cur; break }
+            cur = { el: elements[idx], idx }
+            if (cur && (cur.el.clickable || cur.el.enabled || cur.el.focusable)) { resolvedAncestor = cur; break }
           } else if (typeof pid === 'string') {
             // fallback: search elements for matching resourceId or id
-            const found = elements.find((el: UiElement)=> (el.resourceId === pid || el.id === pid))
+            const foundIndex = elements.findIndex((el: UiElement)=> (el.resourceId === pid || el.id === pid))
+            const found = foundIndex >= 0 ? elements[foundIndex] : null
             if (found) {
-              cur = found
-              if (cur && (cur.clickable || cur.enabled || cur.focusable)) { resolvedAncestor = cur; break }
+              cur = { el: found, idx: foundIndex }
+              if (cur && (cur.el.clickable || cur.el.enabled || cur.el.focusable)) { resolvedAncestor = cur; break }
               // otherwise continue climbing if this found element has its own parentId
             } else {
               break
@@ -659,62 +741,77 @@ export class ToolsInteract {
       if (!resolvedAncestor && childBounds) {
         const [cl,ct,cr,cb] = childBounds
         // find candidates that are clickable and contain the child bounds
-        const candidates = elements.filter((el: UiElement)=> el && (el.clickable || el.focusable) && Array.isArray(el.bounds) && el.bounds!.length>=4).map((el: UiElement)=>({el, bounds: el.bounds! as number[]}))
-        let bestCandidate: any = null
+        const candidates = elements
+          .map((el: UiElement, idx: number) => ({ el, idx }))
+          .filter(({ el }) => el && (el.clickable || el.focusable) && Array.isArray(el.bounds) && el.bounds!.length >= 4)
+        let bestCandidate: { el: UiElement, idx: number } | null = null
         let bestCandidateArea = Infinity
         for (const c of candidates) {
-          const [pl,pt,pr,pb] = c.bounds
+          const bounds = c.el.bounds as number[]
+          const [pl,pt,pr,pb] = bounds
           if (pl <= cl && pt <= ct && pr >= cr && pb >= cb) {
             const area = (pr-pl) * (pb-pt)
-            if (area < bestCandidateArea) { bestCandidateArea = area; bestCandidate = c.el }
+            if (area < bestCandidateArea) { bestCandidateArea = area; bestCandidate = c }
           }
         }
         if (bestCandidate) resolvedAncestor = bestCandidate
       }
 
       if (resolvedAncestor) {
-        best = resolvedAncestor
-        // small score bump to reflect actionability
-        bestScore = Math.min(1, bestScore + 0.02)
+        best = {
+          el: resolvedAncestor.el,
+          idx: resolvedAncestor.idx,
+          score: Math.min(1, best.score + 0.02),
+          reason: 'clickable_parent_preferred',
+          interactable: true
+        }
       }
 
-      if (best && !(best.clickable || best.focusable)) {
-        const nearbyActionable = ToolsInteract._resolveNearbyActionableControl(elements, { el: best, idx: best._index ?? elements.indexOf(best) }, screen)
+      if (best && !(best.el.clickable || best.el.focusable)) {
+        const nearbyActionable = ToolsInteract._resolveNearbyActionableControl(elements, { el: best.el, idx: best.idx }, screen)
         if (nearbyActionable) {
-          best = nearbyActionable.el
-          best._index = nearbyActionable.idx
-          best._interactable = true
-          best._sliderLike = nearbyActionable.sliderLike
+          best = {
+            el: nearbyActionable.el,
+            idx: nearbyActionable.idx,
+            score: Math.min(1, best.score + 0.02),
+            reason: nearbyActionable.sliderLike ? 'slider_track_preferred' : 'nearby_actionable_control',
+            interactable: true
+          }
         }
       }
     } catch (e) { console.error('Error resolving ancestor:', e) }
 
     if (!best) return { found: false, error: 'Element not found' }
 
-    const boundsObj = Array.isArray(best.bounds) ? { left: best.bounds[0], top: best.bounds[1], right: best.bounds[2], bottom: best.bounds[3] } : null
+    const boundsObj = Array.isArray(best.el.bounds) ? { left: best.el.bounds[0], top: best.el.bounds[1], right: best.el.bounds[2], bottom: best.el.bounds[3] } : null
     const tapCoordinates = boundsObj ? { x: Math.floor((boundsObj.left + boundsObj.right) / 2), y: Math.floor((boundsObj.top + boundsObj.bottom) / 2) } : null
+    const uniqueRanked = bestIterationCandidates.filter((candidate, index, array) => index === array.findIndex((other) => other.idx === candidate.idx && other.el === candidate.el))
+    const alternateCandidates = uniqueRanked
+      .filter((candidate) => candidate.idx !== best.idx || candidate.el !== best.el)
+      .slice(0, 3)
+      .map((candidate) => ToolsInteract._summarizeResolutionCandidate(candidate))
 
     const outEl = {
-      text: best.text ?? null,
-      resourceId: best.resourceId ?? null,
-      contentDesc: best.contentDescription ?? best.contentDesc ?? null,
-      class: best.type ?? best.class ?? null,
+      text: best.el.text ?? null,
+      resourceId: best.el.resourceId ?? null,
+      contentDesc: best.el.contentDescription ?? best.el.contentDesc ?? null,
+      class: best.el.type ?? best.el.class ?? null,
       bounds: boundsObj,
-      clickable: !!best.clickable,
-      enabled: !!best.enabled,
-      stable_id: best.stable_id ?? null,
-      role: best.role ?? null,
-      test_tag: best.test_tag ?? null,
-      selector: best.selector ?? null,
-      semantic: best.semantic ?? null,
+      clickable: !!best.el.clickable,
+      enabled: !!best.el.enabled,
+      stable_id: best.el.stable_id ?? null,
+      role: best.el.role ?? null,
+      test_tag: best.el.test_tag ?? null,
+      selector: best.el.selector ?? null,
+      semantic: best.el.semantic ?? null,
       tapCoordinates,
       telemetry: {
-        matchedIndex: best?._index ?? null,
-        matchedInteractable: !!best?._interactable,
-        sliderLike: !!best?._sliderLike
+        matchedIndex: best.idx ?? null,
+        matchedInteractable: !!best.interactable,
+        sliderLike: best.reason === 'slider_track_preferred'
       }
     }
-    if (best?._sliderLike) {
+    if (best.reason === 'slider_track_preferred') {
       const isVertical = !!boundsObj && (boundsObj.bottom - boundsObj.top) > (boundsObj.right - boundsObj.left)
       const interactionHint = {
         kind: 'slider',
@@ -723,8 +820,15 @@ export class ToolsInteract {
       }
       ;(outEl as any).interactionHint = interactionHint
     }
-    const scoreVal = Math.min(1, Number(bestScore.toFixed(3)))
-    return { found: true, element: outEl, score: scoreVal, confidence: scoreVal }
+    const scoreVal = Math.min(1, Number(best.score.toFixed(3)))
+    const resolution: FindElementResolutionSummary = {
+      confidence: scoreVal,
+      reason: best.reason,
+      fallback_available: alternateCandidates.length > 0,
+      matched_count: uniqueRanked.length,
+      alternates: alternateCandidates
+    }
+    return { found: true, element: outEl, score: scoreVal, confidence: scoreVal, resolution }
   }
 
   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 }) {

package/src/server/tool-definitions.ts

@@ -596,7 +596,9 @@ Recommended Usage:
   },
   {
     name: 'find_element',
-    description: 'Find a UI element by semantic query (text, content-desc, resource-id, class). Returns best match.',
+    description: `Find a UI element by semantic query (text, content-desc, resource-id, class).
+
+Returns the best match plus resolution metadata when available, including confidence, selection reason, and fallback alternates.`,
     inputSchema: {
       type: 'object',
       properties: {

package/src/server-core.ts

@@ -13,7 +13,7 @@ export { wrapResponse, toolDefinitions, handleToolCall }
 
 export const serverInfo = {
   name: 'mobile-debug-mcp',
-  version: '0.26.2'
+  version: '0.26.3'
 }
 
 export function createServer() {

package/src/types.ts

@@ -254,6 +254,79 @@ export interface ActionTargetResolved {
   semantic?: UIElementSemanticMetadata | null;
 }
 
+export interface ResolutionAlternate {
+  text: string | null;
+  resource_id: string | null;
+  accessibility_id: string | null;
+  class: string | null;
+  bounds: {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+  } | null;
+  clickable: boolean;
+  enabled: boolean;
+  score: number;
+  reason: string;
+}
+
+export interface ResolutionSummary {
+  confidence: number;
+  reason: string;
+  fallback_available: boolean;
+  matched_count: number;
+  alternates: ResolutionAlternate[];
+}
+
+export interface FindElementElement {
+  text: string | null;
+  resourceId: string | null;
+  contentDesc: string | null;
+  class: string | null;
+  bounds: {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+  } | null;
+  clickable: boolean;
+  enabled: boolean;
+  stable_id?: string | null;
+  role?: string | null;
+  test_tag?: string | null;
+  selector?: UIResolutionSelector | null;
+  semantic?: UIElementSemanticMetadata | null;
+  tapCoordinates: {
+    x: number;
+    y: number;
+  } | null;
+  telemetry: {
+    matchedIndex: number | null;
+    matchedInteractable: boolean;
+    sliderLike: boolean;
+  };
+  interactionHint?: {
+    kind: 'slider';
+    axis: 'horizontal' | 'vertical';
+    trackBounds: {
+      left: number;
+      top: number;
+      right: number;
+      bottom: number;
+    } | null;
+  };
+}
+
+export interface FindElementResponse {
+  found: boolean;
+  element?: FindElementElement | null;
+  score?: number;
+  confidence?: number;
+  resolution?: ResolutionSummary | null;
+  error?: string;
+}
+
 export interface ActionExecutionResult {
   action_id: string;
   timestamp: string;

package/test/unit/observe/find_element.test.ts

@@ -73,6 +73,9 @@ async function run() {
     process.stdout.write('res4 ' + JSON.stringify(res4, null, 2) + '\n');
     const pass4 = res4.found === true && res4.element && res4.element.clickable === true && res4.element.resourceId === 'btn_generate' && res4.element.tapCoordinates && typeof res4.element.tapCoordinates.x === 'number' && typeof res4.element.tapCoordinates.y === 'number' && typeof res4.confidence === 'number'
     assert.ok(pass4, 'Child text should resolve to a clickable parent ancestor')
+    assert.strictEqual(res4.resolution?.reason, 'clickable_parent_preferred')
+    assert.strictEqual(res4.resolution?.fallback_available, true)
+    assert.ok((res4.resolution?.alternates || []).length >= 1, 'Parent promotion should preserve alternates')
     process.stdout.write('Test 4: ' + (pass4 ? 'PASS' : 'FAIL') + '\n');
 
     // Test 5: duration label should resolve to the nearby slider control
@@ -111,6 +114,8 @@ async function run() {
     process.stdout.write('Test 6: ' + (pass6 ? 'PASS' : 'FAIL') + '\n');
     const pass6b = res6.element && res6.element.telemetry && res6.element.telemetry.sliderLike === true && res6.element.interactionHint && res6.element.interactionHint.kind === 'slider'
     assert.ok(pass6b, 'Duration lookup should include slider-specific telemetry')
+    assert.strictEqual(res6.resolution?.reason, 'slider_track_preferred')
+    assert.strictEqual(res6.resolution?.fallback_available, true)
     process.stdout.write('Test 6b: ' + (pass6b ? 'PASS' : 'FAIL') + '\n');
 
     // Test 7: prefer vertical track-like control over a closer text button