mobile-debug-mcp 0.26.1 → 0.26.3

package/src/interact/index.ts

@@ -6,10 +6,11 @@ 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'
 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,28 +317,43 @@ 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(
-    actionId: string,
-    timestamp: string,
     actionType: string,
     selector: Record<string, unknown> | null,
     resolved: ActionTargetResolved | null,
     failureCode: ActionFailureCode,
     retryable: boolean,
     uiFingerprintBefore: string | null,
-    uiFingerprintAfter?: string | null
+    uiFingerprintAfter?: string | null,
+    sourceModule: 'server' | 'interact' = 'interact'
   ): TapElementResponse {
-    return {
-      action_id: actionId,
-      timestamp,
-      action_type: actionType,
-      target: { selector, resolved },
+    return buildActionExecutionResult({
+      actionType,
+      selector,
+      resolved,
       success: false,
-      failure_code: failureCode,
-      retryable,
-      ui_fingerprint_before: uiFingerprintBefore,
-      ui_fingerprint_after: uiFingerprintAfter
-    }
+      uiFingerprintBefore,
+      uiFingerprintAfter: uiFingerprintAfter ?? null,
+      failure: { failureCode, retryable },
+      sourceModule
+    })
   }
 
   static _resetResolvedUiElementsForTests() {
@@ -472,14 +514,11 @@ export class ToolsInteract {
   }
 
   static async tapElementHandler({ elementId }: { elementId: string }): Promise<TapElementResponse> {
-    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)
@@ -491,22 +530,22 @@ export class ToolsInteract {
     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)
@@ -515,23 +554,20 @@ export class ToolsInteract {
 
     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 }: { platform?: 'android' | 'ios', x1: number, y1: number, x2: number, y2: number, duration: number, deviceId?: string }) {
@@ -554,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
@@ -563,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)
 
@@ -582,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))
     }
 
@@ -627,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
@@ -667,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',
@@ -731,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/common.ts

@@ -112,6 +112,23 @@ export function inferScrollFailure(message: string | undefined): { failureCode:
   return { failureCode: 'UNKNOWN', retryable: false }
 }
 
+const ACTION_LIFECYCLE_STATE_BY_OUTCOME = {
+  success: 'pending_verification',
+  failure: 'failed'
+} as const
+
+export function determineActionLifecycleState({
+  success,
+  failure
+}: {
+  success: boolean
+  failure?: { failureCode: ActionFailureCode; retryable: boolean }
+}): NonNullable<ActionExecutionResult['lifecycle_state']> {
+  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,
@@ -121,7 +138,8 @@ export function buildActionExecutionResult({
   uiFingerprintBefore,
   uiFingerprintAfter,
   failure,
-  details
+  details,
+  sourceModule
 }: {
   actionType: string
   device?: ActionExecutionResult['device']
@@ -132,6 +150,7 @@ export function buildActionExecutionResult({
   uiFingerprintAfter: string | null
   failure?: { failureCode: ActionFailureCode; retryable: boolean }
   details?: Record<string, unknown>
+  sourceModule: 'server' | 'interact'
 }): ActionExecutionResult {
   const timestampMs = Date.now()
   const timestamp = new Date(timestampMs).toISOString()
@@ -139,6 +158,8 @@ export function buildActionExecutionResult({
     action_id: nextActionId(actionType, timestampMs),
     timestamp,
     action_type: actionType,
+    lifecycle_state: determineActionLifecycleState({ success, failure }),
+    source_module: sourceModule,
     ...(device ? { device } : {}),
     target: {
       selector,

package/src/server/tool-definitions.ts

@@ -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