mobile-debug-mcp 0.26.1 → 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

@@ -5,7 +5,7 @@ export { AndroidInteract, iOSInteract };
 import { resolveTargetDevice } from '../utils/resolve-device.js';
 import { ToolsObserve } from '../observe/index.js';
 import { computeSnapshotSignature } from '../observe/snapshot-metadata.js';
-import { nextActionId } from '../server/common.js';
+import { buildActionExecutionResult } from '../server/common.js';
 export class ToolsInteract {
     static _maxResolvedUiElements = 256;
     static _uiChangeKinds = ['hierarchy_diff', 'text_change', 'state_change'];
@@ -203,19 +203,34 @@ export class ToolsInteract {
             semantic: element.semantic ?? null
         };
     }
-    static _actionFailure(actionId, timestamp, actionType, selector, resolved, failureCode, retryable, uiFingerprintBefore, uiFingerprintAfter) {
+    static _summarizeResolutionCandidate(candidate) {
+        const bounds = ToolsInteract._normalizeBounds(candidate.el.bounds);
         return {
-            action_id: actionId,
-            timestamp,
-            action_type: actionType,
-            target: { selector, resolved },
-            success: false,
-            failure_code: failureCode,
-            retryable,
-            ui_fingerprint_before: uiFingerprintBefore,
-            ui_fingerprint_after: uiFingerprintAfter
+            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,
+            selector,
+            resolved,
+            success: false,
+            uiFingerprintBefore,
+            uiFingerprintAfter: uiFingerprintAfter ?? null,
+            failure: { failureCode, retryable },
+            sourceModule
+        });
+    }
     static _resetResolvedUiElementsForTests() {
         ToolsInteract._resolvedUiElements.clear();
     }
@@ -350,14 +365,11 @@ export class ToolsInteract {
         return await interact.tap(x, y, resolved.id);
     }
     static async tapElementHandler({ elementId }) {
-        const timestampMs = Date.now();
-        const timestamp = new Date(timestampMs).toISOString();
         const actionType = 'tap_element';
-        const actionId = nextActionId(actionType, timestampMs);
         const selector = { elementId };
         const resolved = ToolsInteract._resolvedUiElements.get(elementId);
         if (!resolved) {
-            return ToolsInteract._actionFailure(actionId, timestamp, actionType, selector, null, 'STALE_REFERENCE', true, null);
+            return ToolsInteract._actionFailure(actionType, selector, null, 'STALE_REFERENCE', true, null);
         }
         const fingerprintBefore = await ToolsInteract._captureFingerprint(resolved.platform, resolved.deviceId);
         const tree = await ToolsObserve.getUITreeHandler({ platform: resolved.platform, deviceId: resolved.deviceId });
@@ -366,40 +378,37 @@ export class ToolsInteract {
         const elements = Array.isArray(tree?.elements) ? tree.elements : [];
         const currentMatch = ToolsInteract._findCurrentResolvedElement(elements, treePlatform, treeDeviceId, resolved);
         if (!currentMatch) {
-            return ToolsInteract._actionFailure(actionId, timestamp, actionType, selector, null, 'STALE_REFERENCE', true, fingerprintBefore);
+            return ToolsInteract._actionFailure(actionType, selector, null, 'STALE_REFERENCE', true, fingerprintBefore);
         }
         const resolvedTarget = ToolsInteract._resolvedTargetFromElement(resolved.elementId, currentMatch.el, currentMatch.index);
         if (!ToolsInteract._isVisibleElement(currentMatch.el)) {
-            return ToolsInteract._actionFailure(actionId, timestamp, actionType, selector, resolvedTarget, 'ELEMENT_NOT_INTERACTABLE', true, fingerprintBefore);
+            return ToolsInteract._actionFailure(actionType, selector, resolvedTarget, 'ELEMENT_NOT_INTERACTABLE', true, fingerprintBefore);
         }
         if (currentMatch.el.enabled === false) {
-            return ToolsInteract._actionFailure(actionId, timestamp, actionType, selector, resolvedTarget, 'ELEMENT_NOT_INTERACTABLE', true, fingerprintBefore);
+            return ToolsInteract._actionFailure(actionType, selector, resolvedTarget, 'ELEMENT_NOT_INTERACTABLE', true, fingerprintBefore);
         }
         const bounds = ToolsInteract._normalizeBounds(currentMatch.el.bounds) ?? resolved.bounds;
         if (!bounds || bounds[2] <= bounds[0] || bounds[3] <= bounds[1]) {
-            return ToolsInteract._actionFailure(actionId, timestamp, actionType, selector, resolvedTarget, 'ELEMENT_NOT_INTERACTABLE', true, fingerprintBefore);
+            return ToolsInteract._actionFailure(actionType, selector, resolvedTarget, 'ELEMENT_NOT_INTERACTABLE', true, fingerprintBefore);
         }
         const x = Math.floor((bounds[0] + bounds[2]) / 2);
         const y = Math.floor((bounds[1] + bounds[3]) / 2);
         const tapResult = await ToolsInteract.tapHandler({ platform: resolved.platform, x, y, deviceId: resolved.deviceId });
         if (!tapResult.success) {
             const fingerprintAfterFailure = await ToolsInteract._captureFingerprint(resolved.platform, resolved.deviceId);
-            return ToolsInteract._actionFailure(actionId, timestamp, actionType, selector, resolvedTarget, 'UNKNOWN', false, fingerprintBefore, fingerprintAfterFailure);
+            return ToolsInteract._actionFailure(actionType, selector, resolvedTarget, 'UNKNOWN', false, fingerprintBefore, fingerprintAfterFailure);
         }
         const fingerprintAfter = await ToolsInteract._captureFingerprint(resolved.platform, resolved.deviceId);
-        return {
-            action_id: actionId,
-            timestamp,
-            action_type: actionType,
-            ...(tree?.device ? { device: tree.device } : {}),
-            target: {
-                selector,
-                resolved: resolvedTarget
-            },
+        return buildActionExecutionResult({
+            actionType,
+            device: tree?.device,
+            selector,
+            resolved: resolvedTarget,
             success: true,
-            ui_fingerprint_before: fingerprintBefore,
-            ui_fingerprint_after: fingerprintAfter
-        };
+            uiFingerprintBefore: fingerprintBefore,
+            uiFingerprintAfter: fingerprintAfter,
+            sourceModule: 'interact'
+        });
     }
     static async swipeHandler({ platform = 'android', x1, y1, x2, y2, duration, deviceId }) {
         const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId);
@@ -426,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 ?? '');
@@ -444,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));
         }
@@ -509,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;
@@ -527,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;
                             }
@@ -558,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;
                         }
                     }
                 }
@@ -575,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
+                    };
                 }
             }
         }
@@ -594,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',
@@ -625,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/common.js

@@ -95,13 +95,26 @@ export function inferScrollFailure(message) {
         return { failureCode: 'TIMEOUT', retryable: true };
     return { failureCode: 'UNKNOWN', retryable: false };
 }
-export function buildActionExecutionResult({ actionType, device, selector, resolved, success, uiFingerprintBefore, uiFingerprintAfter, failure, details }) {
+const ACTION_LIFECYCLE_STATE_BY_OUTCOME = {
+    success: 'pending_verification',
+    failure: 'failed'
+};
+export function determineActionLifecycleState({ success, failure }) {
+    if (failure)
+        return ACTION_LIFECYCLE_STATE_BY_OUTCOME.failure;
+    if (success)
+        return ACTION_LIFECYCLE_STATE_BY_OUTCOME.success;
+    return ACTION_LIFECYCLE_STATE_BY_OUTCOME.success;
+}
+export function buildActionExecutionResult({ actionType, device, selector, resolved, success, uiFingerprintBefore, uiFingerprintAfter, failure, details, sourceModule }) {
     const timestampMs = Date.now();
     const timestamp = new Date(timestampMs).toISOString();
     return {
         action_id: nextActionId(actionType, timestampMs),
         timestamp,
         action_type: actionType,
+        lifecycle_state: determineActionLifecycleState({ success, failure }),
+        source_module: sourceModule,
         ...(device ? { device } : {}),
         target: {
             selector,

package/dist/server/tool-definitions.js

@@ -11,7 +11,9 @@ Inputs:
 
 Output Structure:
  - action_id, timestamp (ISO 8601), action_type
-- target.selector = { appId }
+ - lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
+ - source_module: runtime source of the action envelope
+ - target.selector = { appId }
 - success = true when launch was dispatched successfully
 - failure_code/retryable when launch dispatch fails
 - ui_fingerprint_before/ui_fingerprint_after when available
@@ -84,7 +86,9 @@ Inputs:
 
 Output Structure:
  - action_id, timestamp (ISO 8601), action_type
-- target.selector = { appId }
+ - lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
+ - source_module: runtime source of the action envelope
+ - target.selector = { appId }
 - success = true when the restart command completed
 - failure_code/retryable when restart dispatch fails
 - ui_fingerprint_before/ui_fingerprint_after when available
@@ -592,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: {
@@ -617,7 +623,9 @@ Inputs:
 
 Output Structure:
  - action_id, timestamp (ISO 8601), action_type
-- target.selector = { x, y }
+ - lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
+ - source_module: runtime source of the action envelope
+ - target.selector = { x, y }
 - success = true when the tap was dispatched
 - failure_code/retryable when dispatch fails
 - ui_fingerprint_before/ui_fingerprint_after when available
@@ -673,6 +681,8 @@ Output Structure:
 - action_id: unique timestamp-based action identifier
 - timestamp: ISO 8601 timestamp for the action attempt
 - action_type: "tap_element"
+- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
+- source_module: runtime source of the action envelope
 - target.selector: original target handle ({ elementId })
 - target.resolved: minimal resolved element info used for the tap
 - success: true when the tap was dispatched
@@ -725,6 +735,8 @@ Inputs:
 
 Output Structure:
 - action_id, timestamp (ISO 8601), action_type
+- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
+- source_module: runtime source of the action envelope
 - target.selector = { x1, y1, x2, y2, duration }
 - success = true when the swipe was dispatched
 - failure_code/retryable when dispatch fails
@@ -777,6 +789,8 @@ Inputs:
 
 Output Structure:
 - action_id, timestamp (ISO 8601), action_type
+- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
+- source_module: runtime source of the action envelope
 - target.selector = original selector
 - target.resolved = minimal resolved element info when found
 - success = true when scrolling produced a visible target element
@@ -831,6 +845,8 @@ Inputs:
 
 Output Structure:
 - action_id, timestamp (ISO 8601), action_type
+- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
+- source_module: runtime source of the action envelope
 - target.selector = { text }
 - success = true when text input was dispatched
 - failure_code/retryable when dispatch fails
@@ -880,6 +896,8 @@ Inputs:
 
 Output Structure:
 - action_id, timestamp (ISO 8601), action_type
+- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
+- source_module: runtime source of the action envelope
 - target.selector = { key: "back" }
 - success = true when the back action was dispatched
 - failure_code/retryable when dispatch fails

package/dist/server/tool-handlers.js

@@ -15,6 +15,7 @@ async function handleStartApp(args) {
     const uiFingerprintAfter = await captureActionFingerprint(platform, deviceId);
     return wrapResponse(buildActionExecutionResult({
         actionType: 'start_app',
+        sourceModule: 'server',
         device: res.device,
         selector: { appId },
         success: !!res.appStarted,
@@ -48,6 +49,7 @@ async function handleRestartApp(args) {
     const uiFingerprintAfter = await captureActionFingerprint(platform, deviceId);
     return wrapResponse(buildActionExecutionResult({
         actionType: 'restart_app',
+        sourceModule: 'server',
         device: res.device,
         selector: { appId },
         success: !!res.appRestarted,
@@ -265,6 +267,7 @@ async function handleTap(args) {
     const uiFingerprintAfter = await captureActionFingerprint(platform, deviceId);
     return wrapResponse(buildActionExecutionResult({
         actionType: 'tap',
+        sourceModule: 'server',
         selector: { x, y },
         success: !!res.success,
         uiFingerprintBefore,
@@ -292,6 +295,7 @@ async function handleSwipe(args) {
     const uiFingerprintAfter = await captureActionFingerprint(platform, deviceId);
     return wrapResponse(buildActionExecutionResult({
         actionType: 'swipe',
+        sourceModule: 'server',
         selector: { x1, y1, x2, y2, duration },
         success: !!res.success,
         uiFingerprintBefore,
@@ -312,6 +316,7 @@ async function handleScrollToElement(args) {
     const uiFingerprintAfter = await captureActionFingerprint(platform, deviceId);
     return wrapResponse(buildActionExecutionResult({
         actionType: 'scroll_to_element',
+        sourceModule: 'server',
         selector: selector ?? null,
         resolved: res?.success && res?.element ? {
             elementId: null,
@@ -337,6 +342,7 @@ async function handleTypeText(args) {
     const uiFingerprintAfter = await captureActionFingerprint('android', deviceId);
     return wrapResponse(buildActionExecutionResult({
         actionType: 'type_text',
+        sourceModule: 'server',
         selector: { text },
         success: !!res.success,
         uiFingerprintBefore,
@@ -352,6 +358,7 @@ async function handlePressBack(args) {
     const uiFingerprintAfter = await captureActionFingerprint('android', deviceId);
     return wrapResponse(buildActionExecutionResult({
         actionType: 'press_back',
+        sourceModule: 'server',
         selector: { key: 'back' },
         success: !!res.success,
         uiFingerprintBefore,

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.1'
+    version: '0.26.3'
 };
 export function createServer() {
     const server = new Server(serverInfo, {

package/docs/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 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 
+
 ## [0.26.1]
 - Fixed overuse of `get_network_activity`