mobile-debug-mcp 0.26.5 → 0.27.0

package/src/server/common.ts

@@ -1,10 +1,15 @@
 import type {
   ActionExecutionResult,
   ActionFailureCode,
-  ActionTargetResolved
+  ActionTargetResolved,
+  FailureClass,
+  RecoveryState
 } from '../types.js'
 import { ToolsObserve } from '../observe/index.js'
 
+export const DEFAULT_MAX_RECOVERY_ATTEMPTS = 3
+export const DEFAULT_MAX_RETRY_DEPTH = 3
+
 export function wrapResponse<T>(data: T) {
   return {
     content: [{
@@ -103,6 +108,7 @@ export function normalizeResolvedTarget(value: Partial<ActionTargetResolved> | n
 
 export function inferGenericFailure(message: string | undefined): { failureCode: ActionFailureCode; retryable: boolean } {
   if (message && /timeout/i.test(message)) return { failureCode: 'TIMEOUT', retryable: true }
+  if (message && /semantic mismatch/i.test(message)) return { failureCode: 'SEMANTIC_MISMATCH', retryable: false }
   return { failureCode: 'UNKNOWN', retryable: false }
 }
 
@@ -129,6 +135,42 @@ export function determineActionLifecycleState({
   return ACTION_LIFECYCLE_STATE_BY_OUTCOME.success
 }
 
+function mapFailureCodeToFailureClass(code: ActionFailureCode): FailureClass {
+  switch (code) {
+    case 'ELEMENT_NOT_FOUND':
+    case 'AMBIGUOUS_TARGET':
+    case 'STALE_REFERENCE':
+      return 'TargetResolutionFailure'
+    case 'ELEMENT_NOT_INTERACTABLE':
+      return 'ExecutionFailure'
+    case 'TIMEOUT':
+    case 'ACTION_REJECTED':
+    case 'NAVIGATION_NO_CHANGE':
+    case 'UNKNOWN':
+      return 'ExecutionFailure'
+    case 'VERIFICATION_FAILED':
+    case 'EXPECT_STATE_MISMATCH':
+      return 'VerificationFailure'
+    case 'CONTROL_CONVERGENCE_FAILED':
+      return 'ControlConvergenceFailure'
+    case 'SEMANTIC_MISMATCH':
+      return 'SemanticMismatchFailure'
+  }
+}
+
+function buildRecoveryState(failureCode: ActionFailureCode, retryable: boolean): RecoveryState {
+  return {
+    failure_class: mapFailureCodeToFailureClass(failureCode),
+    runtime_code: failureCode,
+    recovery_attempts: 0,
+    max_recovery_attempts: DEFAULT_MAX_RECOVERY_ATTEMPTS,
+    retry_depth: 0,
+    max_retry_depth: DEFAULT_MAX_RETRY_DEPTH,
+    is_terminal: false,
+    retry_allowed: retryable
+  }
+}
+
 export function buildActionExecutionResult({
   actionType,
   device,
@@ -167,6 +209,7 @@ export function buildActionExecutionResult({
     },
     success,
     ...(failure ? { failure_code: failure.failureCode, retryable: failure.retryable } : {}),
+    ...(failure ? { recovery: buildRecoveryState(failure.failureCode, failure.retryable) } : {}),
     ui_fingerprint_before: uiFingerprintBefore,
     ui_fingerprint_after: uiFingerprintAfter,
     ...(details ? { details } : {})

package/src/server-core.ts

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

package/src/types.ts

@@ -113,6 +113,20 @@ export interface UIElementSemanticMetadata {
   state_shape?: 'continuous' | 'discrete' | 'semantic' | null;
 }
 
+export type FailureClass =
+  | 'TargetResolutionFailure'
+  | 'ExecutionFailure'
+  | 'VerificationFailure'
+  | 'ControlConvergenceFailure'
+  | 'SemanticMismatchFailure';
+
+export type RecoveryStrategy =
+  | 're_resolve'
+  | 'alternate_candidate'
+  | 'state_refresh'
+  | 'retry_adjustment'
+  | 'step_back';
+
 export interface LoadingState {
   active: boolean;
   signal: string;
@@ -240,8 +254,25 @@ export type ActionFailureCode =
   | 'NAVIGATION_NO_CHANGE'
   | 'AMBIGUOUS_TARGET'
   | 'STALE_REFERENCE'
+  | 'ACTION_REJECTED'
+  | 'VERIFICATION_FAILED'
+  | 'EXPECT_STATE_MISMATCH'
+  | 'CONTROL_CONVERGENCE_FAILED'
+  | 'SEMANTIC_MISMATCH'
   | 'UNKNOWN'
 
+export interface RecoveryState {
+  failure_class: FailureClass;
+  runtime_code: ActionFailureCode;
+  recovery_strategy?: RecoveryStrategy;
+  recovery_attempts: number;
+  max_recovery_attempts: number;
+  retry_depth: number;
+  max_retry_depth: number;
+  is_terminal: boolean;
+  retry_allowed?: boolean;
+}
+
 export interface ActionTargetResolved {
   elementId: string | null;
   text: string | null;
@@ -345,6 +376,7 @@ export interface ActionExecutionResult {
   success: boolean;
   failure_code?: ActionFailureCode;
   retryable?: boolean;
+  recovery?: RecoveryState;
   ui_fingerprint_before?: string | null;
   ui_fingerprint_after?: string | null;
   details?: Record<string, unknown>;
@@ -415,6 +447,10 @@ export interface ExpectStateResponse {
   reason?: string;
   failure_code?: 'ELEMENT_NOT_FOUND' | 'UNKNOWN';
   retryable?: boolean;
+  stabilization_attempts?: number;
+  stabilization_window_ms?: number;
+  stable_observation_count?: number;
+  snapshot_freshness_ms?: number;
 }
 
 export interface AdjustControlResponse extends ActionExecutionResult {

package/test/unit/interact/adjust_control.test.ts

@@ -346,9 +346,85 @@ async function run() {
     assert.strictEqual(cachedResolveAdjust.success, true)
     assert.strictEqual(cachedResolveAdjust.converged, true)
     assert.strictEqual(cachedResolveAdjust.within_tolerance, true)
-    assert.strictEqual(cachedResolveAdjust.attempts, 3)
+    assert.ok(cachedResolveAdjust.attempts >= 3)
     assert.strictEqual(treeFetches, 1, 'second attempt should reuse the resolved element instead of refetching the UI tree')
 
+    const probeTapStart = tapCalls.length
+    const probeSwipeStart = swipeCalls.length
+    let probeVerificationCount = 0
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => ({
+      device: { platform: 'android', id: 'mock-device', osVersion: '14', model: 'Pixel', simulator: true },
+      screen: '',
+      resolution: { width: 1080, height: 2400 },
+      elements: [
+        {
+          text: 'Duration',
+          type: 'android.widget.SeekBar',
+          contentDescription: null,
+          clickable: true,
+          enabled: true,
+          visible: true,
+          bounds: [0, 0, 200, 40],
+          resourceId: 'seek_duration',
+          state: {
+            value: 10,
+            raw_value: 10,
+            value_range: { min: 0, max: 20 }
+          }
+        }
+      ]
+    })
+
+    ;(ToolsInteract as any).tapHandler = async ({ platform, x, y, deviceId }: any) => {
+      tapCalls.push({ platform, x, y, deviceId })
+      return {
+        device: { platform: platform || 'android', id: deviceId || 'mock-device', osVersion: '14', model: 'Pixel', simulator: true },
+        success: true,
+        x,
+        y
+      }
+    }
+
+    ;(ToolsInteract as any).expectStateHandler = async () => {
+      probeVerificationCount++
+      const value = probeVerificationCount === 1 ? 11 : 12
+      return {
+        success: true,
+        selector: { text: 'Duration' },
+        element_id: wait.element.elementId,
+        expected_state: { property: 'value', expected: 12 },
+        element: {
+          elementId: wait.element.elementId,
+          text: 'Duration',
+          resource_id: 'seek_duration',
+          accessibility_id: null,
+          class: 'android.widget.SeekBar',
+          bounds: [0, 0, 200, 40],
+          index: 0,
+          state: { value, raw_value: value, value_range: { min: 0, max: 20 } }
+        },
+        observed_state: { property: 'value', value, raw_value: value },
+        reason: value === 12 ? 'value matches expected value' : 'value still below target'
+      }
+    }
+
+    const probeAdjust = await ToolsInteract.adjustControlHandler({
+      element_id: wait.element.elementId,
+      property: 'value',
+      targetValue: 12,
+      tolerance: 0.5,
+      maxAttempts: 3,
+      platform: 'android'
+    })
+
+    assert.strictEqual(probeAdjust.success, true)
+    assert.strictEqual(probeAdjust.converged, true)
+    assert.strictEqual(probeAdjust.within_tolerance, true)
+    assert.strictEqual(probeAdjust.adjustment_mode, 'coordinate')
+    assert.strictEqual(probeAdjust.attempts, 2)
+    assert.strictEqual(tapCalls.length, probeTapStart + 2)
+    assert.strictEqual(swipeCalls.length, probeSwipeStart)
+
     console.log('adjust_control unit tests passed')
   } finally {
     ;(Observe as any).ToolsObserve.getUITreeHandler = originalGetUITreeHandler

package/test/unit/interact/verification_stabilization.test.ts

@@ -0,0 +1,94 @@
+import assert from 'assert'
+import { ToolsInteract } from '../../../src/interact/index.js'
+import * as Observe from '../../../src/observe/index.js'
+
+async function run() {
+  console.log('Starting verification stabilization unit tests...')
+
+  const originalGetUITreeHandler = (Observe as any).ToolsObserve.getUITreeHandler
+
+  try {
+    let visibilityCalls = 0
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => {
+      visibilityCalls++
+      const visible = visibilityCalls >= 3
+      return {
+        device: { platform: 'android', id: 'mock-device', osVersion: '14', model: 'Pixel', simulator: true },
+        captured_at_ms: Date.now(),
+        resolution: { width: 1080, height: 2400 },
+        elements: [
+          {
+            text: visible ? 'Ready' : 'Loading',
+            contentDescription: null,
+            type: 'android.widget.TextView',
+            resourceId: 'ready_label',
+            clickable: false,
+            enabled: true,
+            visible,
+            bounds: [0, 0, 120, 40]
+          }
+        ]
+      }
+    }
+
+    const visibleResult = await ToolsInteract.waitForUIHandler({
+      selector: { text: 'Ready' },
+      condition: 'visible',
+      timeout_ms: 600,
+      poll_interval_ms: 50,
+      platform: 'android'
+    })
+
+    assert.strictEqual(visibleResult.status, 'success')
+    assert.ok(visibilityCalls >= 4, 'visibility should be confirmed across consecutive reads')
+
+    let stateCalls = 0
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => {
+      stateCalls++
+      const value = stateCalls >= 3 ? 30 : 10
+      const stale = stateCalls === 2
+      return {
+        device: { platform: 'android', id: 'mock-device', osVersion: '14', model: 'Pixel', simulator: true },
+        captured_at_ms: stale ? Date.now() - 1000 : Date.now(),
+        resolution: { width: 1080, height: 2400 },
+        elements: [
+          {
+            text: 'Volume',
+            contentDescription: null,
+            type: 'android.widget.SeekBar',
+            resourceId: 'volume_slider',
+            clickable: true,
+            enabled: true,
+            visible: true,
+            bounds: [0, 0, 240, 40],
+            state: {
+              value,
+              raw_value: value,
+              value_range: { min: 0, max: 100 }
+            }
+          }
+        ]
+      }
+    }
+
+    const stateResult = await ToolsInteract.expectStateHandler({
+      selector: { text: 'Volume' },
+      property: 'value',
+      expected: 30,
+      platform: 'android'
+    })
+
+    assert.strictEqual(stateResult.success, true)
+    assert.strictEqual(stateResult.reason, 'value matches expected value')
+    assert.ok(stateCalls >= 4, 'state verification should require stable fresh reads')
+
+    console.log('verification stabilization unit tests passed')
+  } finally {
+    ;(Observe as any).ToolsObserve.getUITreeHandler = originalGetUITreeHandler
+  }
+}
+
+run().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

package/test/unit/server/common.test.ts

@@ -1,5 +1,5 @@
 import assert from 'assert'
-import { requireBooleanArg } from '../../../src/server/common.js'
+import { buildActionExecutionResult, inferGenericFailure, requireBooleanArg } from '../../../src/server/common.js'
 
 function run() {
   assert.strictEqual(requireBooleanArg({ exact: true }, 'exact'), true)
@@ -7,6 +7,41 @@ function run() {
   assert.throws(() => requireBooleanArg({}, 'exact'), /Missing or invalid boolean argument: exact/)
   assert.throws(() => requireBooleanArg({ exact: 'true' as unknown as boolean }, 'exact'), /Missing or invalid boolean argument: exact/)
 
+  assert.deepStrictEqual(inferGenericFailure('semantic mismatch between inferred and raw state'), {
+    failureCode: 'SEMANTIC_MISMATCH',
+    retryable: false
+  })
+
+  const recoveryResult = buildActionExecutionResult({
+    actionType: 'tap',
+    sourceModule: 'server',
+    selector: { x: 10, y: 20 },
+    success: false,
+    uiFingerprintBefore: 'fp_before',
+    uiFingerprintAfter: 'fp_after',
+    failure: { failureCode: 'SEMANTIC_MISMATCH', retryable: false }
+  })
+  assert.strictEqual(recoveryResult.failure_code, 'SEMANTIC_MISMATCH')
+  assert.strictEqual(recoveryResult.recovery?.failure_class, 'SemanticMismatchFailure')
+  assert.strictEqual(recoveryResult.recovery?.runtime_code, 'SEMANTIC_MISMATCH')
+  assert.strictEqual(recoveryResult.recovery?.retry_allowed, false)
+  assert.strictEqual(recoveryResult.recovery?.max_recovery_attempts, 3)
+  assert.strictEqual(recoveryResult.recovery?.max_retry_depth, 3)
+
+  const notInteractableResult = buildActionExecutionResult({
+    actionType: 'tap',
+    sourceModule: 'server',
+    selector: { x: 5, y: 5 },
+    success: false,
+    uiFingerprintBefore: 'fp_before',
+    uiFingerprintAfter: 'fp_after',
+    failure: { failureCode: 'ELEMENT_NOT_INTERACTABLE', retryable: true }
+  })
+  assert.strictEqual(notInteractableResult.failure_code, 'ELEMENT_NOT_INTERACTABLE')
+  assert.strictEqual(notInteractableResult.recovery?.failure_class, 'ExecutionFailure')
+  assert.strictEqual(notInteractableResult.recovery?.runtime_code, 'ELEMENT_NOT_INTERACTABLE')
+  assert.strictEqual(notInteractableResult.recovery?.retry_allowed, true)
+
   console.log('server common tests passed')
 }