mobile-debug-mcp 0.26.3 → 0.26.5

package/src/observe/ios.ts

@@ -73,6 +73,9 @@ function normalizeIOSType(value: unknown): string {
 
 function inferIOSRole(type: string, traits: string[]): string | null {
   if (/slider|adjustable/.test(type) || traits.some((trait) => /adjustable|slider/.test(trait))) return 'slider'
+  if (/stepper/.test(type)) return 'stepper'
+  if (/picker|pop up button|dropdown/.test(type)) return 'dropdown'
+  if (/segmented control/.test(type)) return 'segmented_control'
   if (/button/.test(type) || traits.some((trait) => /button/.test(trait))) return 'button'
   if (/cell/.test(type)) return 'cell'
   if (/switch/.test(type)) return 'switch'
@@ -113,15 +116,51 @@ function buildIOSSelector(type: string, label: string | null, value: string | nu
   return null
 }
 
-function buildIOSSemantic(type: string, traits: string[]): UIElementSemanticMetadata {
-  return {
+function buildIOSSemantic(type: string, traits: string[], role: string | null, value: string | null): UIElementSemanticMetadata {
+  const semantic: UIElementSemanticMetadata = {
     is_clickable: traits.includes("UIAccessibilityTraitButton") || /adjustable|slider/.test(type) || type === "Button" || type === "Cell",
     is_container: /window|application|group|scroll view|collection view/.test(type)
   }
+
+  if (role === 'slider') {
+    semantic.semantic_role = 'slider'
+    semantic.adjustable = true
+    semantic.supported_actions = ['adjust']
+    semantic.state_shape = 'continuous'
+  } else if (role === 'stepper') {
+    semantic.semantic_role = 'stepper'
+    semantic.adjustable = true
+    semantic.supported_actions = ['increment', 'decrement']
+    semantic.state_shape = 'discrete'
+  } else if (role === 'dropdown') {
+    semantic.semantic_role = 'dropdown'
+    semantic.supported_actions = ['tap', 'expand']
+    semantic.state_shape = 'semantic'
+  } else if (role === 'segmented_control') {
+    semantic.semantic_role = 'segmented_control'
+    semantic.supported_actions = ['tap']
+    semantic.state_shape = 'discrete'
+  } else if (traits.some((trait) => /adjustable|slider/i.test(trait)) || /adjustable|slider/.test(type)) {
+    semantic.semantic_role = 'custom_adjustable'
+    semantic.adjustable = true
+    semantic.supported_actions = ['adjust']
+    semantic.state_shape = 'continuous'
+  } else if (semantic.is_clickable) {
+    semantic.supported_actions = ['tap']
+  }
+
+  if (semantic.state_shape === undefined && semantic.adjustable && value !== null) {
+    const numericValue = parseIOSNumber(value)
+    if (numericValue !== null && numericValue >= 0 && numericValue <= 1) {
+      semantic.state_shape = 'continuous'
+    }
+  }
+
+  return semantic
 }
 
 function isIOSAdjustable(node: IDBElement, type: string, traits: string[]): boolean {
-  return /slider|adjustable|stepper|progress/i.test(type) || traits.some((trait) => /adjustable|slider|progress/i.test(trait))
+  return /slider|adjustable|stepper/i.test(type) || traits.some((trait) => /adjustable|slider/i.test(trait))
 }
 
 function extractIOSState(node: IDBElement, type: string, label: string | null, value: string | null, traits: string[]): UIElementState | null {
@@ -184,8 +223,8 @@ export function traverseIDBNode(node: IDBElement, elements: UIElement[], parentI
   const normalizedType = normalizeIOSType(type)
   const stableId = getIOSStableId(node)
   const selector = buildIOSSelector(type, label, value, stableId)
-  const semantic = buildIOSSemantic(normalizedType, traits)
   const role = inferIOSRole(normalizedType, traits)
+  const semantic = buildIOSSemantic(normalizedType, traits, role, value)
   
   const clickable = traits.includes("UIAccessibilityTraitButton") || type === "Button" || type === "Cell";
   

package/src/server/tool-definitions.ts

@@ -555,6 +555,62 @@ Failure Handling:
       required: ['property', 'expected']
     }
   },
+  {
+    name: 'adjust_control',
+    description: `Purpose:
+Adjust a numeric control value with verification.
+
+This is the initial adjustable-control surface for slider-like controls and other controls that expose a numeric value or value_range.
+
+Inputs:
+- selector or element_id
+- property (defaults to "value")
+- targetValue
+- tolerance (optional)
+- maxAttempts (optional)
+- platform/deviceId (optional)
+
+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_state / actual_state / within_tolerance / converged / attempts / adjustment_mode
+- target.selector = original selector or element handle
+- success = true when the control converges within tolerance
+
+Verification Guidance:
+- Prefer direct target placement when value_range is available; fall back to a drag only if the direct tap does not converge
+- Use expect_state for the control value readback
+- Treat coordinate fallback as degraded mode
+
+Failure Handling:
+- ELEMENT_NOT_FOUND → re-resolve the control
+- ELEMENT_NOT_INTERACTABLE → the control cannot be adjusted through the current runtime
+- TIMEOUT → the control did not converge within bounded retries
+- UNKNOWN → capture a snapshot and stop`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        selector: {
+          type: 'object',
+          properties: {
+            text: { type: 'string' },
+            resource_id: { type: 'string' },
+            accessibility_id: { type: 'string' },
+            contains: { type: 'boolean', default: false }
+          }
+        },
+        element_id: { type: 'string', description: 'Optional previously resolved element identifier.' },
+        property: { type: 'string', description: 'Readable numeric state property to adjust.', default: 'value' },
+        targetValue: { type: 'number', description: 'Target numeric value.' },
+        tolerance: { type: 'number', description: 'Accepted numeric tolerance around the target value.', default: 0 },
+        maxAttempts: { type: 'number', description: 'Maximum adjustment attempts.', default: 3 },
+        platform: { type: 'string', enum: ['android', 'ios'], description: 'Optional platform override' },
+        deviceId: { type: 'string', description: 'Optional device serial/udid' }
+      },
+      required: ['targetValue']
+    }
+  },
   {
     name: 'wait_for_ui',
     description: `Purpose:

package/src/server/tool-handlers.ts

@@ -277,6 +277,31 @@ async function handleExpectState(args: ToolCallArgs) {
   return wrapResponse(res)
 }
 
+async function handleAdjustControl(args: ToolCallArgs) {
+  const selector = getObjectArg<ExpectElementSelectorArg>(args, 'selector')
+  const element_id = getStringArg(args, 'element_id')
+  const property = getStringArg(args, 'property') ?? 'value'
+  const targetValue = requireNumberArg(args, 'targetValue')
+  const tolerance = getNumberArg(args, 'tolerance') ?? 0
+  const maxAttempts = getNumberArg(args, 'maxAttempts') ?? 3
+  const platform = getStringArg(args, 'platform') as PlatformArg | undefined
+  const deviceId = getStringArg(args, 'deviceId')
+  if (!selector && !element_id) {
+    throw new Error('Missing selector or element_id argument')
+  }
+  const res = await ToolsInteract.adjustControlHandler({
+    selector: selector ?? undefined,
+    element_id: element_id ?? undefined,
+    property,
+    targetValue,
+    tolerance,
+    maxAttempts,
+    platform,
+    deviceId
+  })
+  return wrapResponse(res)
+}
+
 async function handleWaitForUI(args: ToolCallArgs) {
   const selector = getObjectArg<ExpectElementSelectorArg>(args, 'selector')
   const condition = (getStringArg(args, 'condition') as 'exists' | 'not_exists' | 'visible' | 'clickable' | undefined) ?? 'exists'
@@ -496,6 +521,7 @@ export const toolHandlers: Record<string, ToolHandler> = {
   expect_screen: handleExpectScreen,
   expect_element_visible: handleExpectElementVisible,
   expect_state: handleExpectState,
+  adjust_control: handleAdjustControl,
   wait_for_ui: handleWaitForUI,
   find_element: handleFindElement,
   tap: handleTap,

package/src/server-core.ts

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

package/src/types.ts

@@ -107,6 +107,10 @@ export interface UIResolutionSelector {
 export interface UIElementSemanticMetadata {
   is_clickable: boolean;
   is_container: boolean;
+  semantic_role?: 'slider' | 'stepper' | 'dropdown' | 'segmented_control' | 'custom_adjustable' | 'composite_control' | null;
+  supported_actions?: string[] | null;
+  adjustable?: boolean | null;
+  state_shape?: 'continuous' | 'discrete' | 'semantic' | null;
 }
 
 export interface LoadingState {
@@ -413,6 +417,23 @@ export interface ExpectStateResponse {
   retryable?: boolean;
 }
 
+export interface AdjustControlResponse extends ActionExecutionResult {
+  target_state: {
+    property: string;
+    target_value: number;
+    tolerance: number;
+  };
+  actual_state: {
+    property: string;
+    value: number | null;
+    raw_value?: number | null;
+  } | null;
+  within_tolerance: boolean;
+  converged: boolean;
+  attempts: number;
+  adjustment_mode: 'semantic' | 'gesture' | 'coordinate';
+}
+
 export interface WaitForUIChangeResponse {
   success: boolean;
   observed_change: 'hierarchy_diff' | 'text_change' | 'state_change' | null;

package/src/utils/android/utils.ts

@@ -341,7 +341,10 @@ function normalizeClassName(value: unknown): string {
 }
 
 function inferAndroidRole(className: string): string | null {
-  if (/seekbar|slider|progress/.test(className)) return 'slider'
+  if (/seekbar|slider/.test(className)) return 'slider'
+  if (/stepper|numberpicker/.test(className)) return 'stepper'
+  if (/spinner|dropdown/.test(className)) return 'dropdown'
+  if (/segment|tablayout/.test(className)) return 'segmented_control'
   if (/switch|toggle/.test(className)) return 'switch'
   if (/checkbox/.test(className)) return 'checkbox'
   if (/radiobutton|radio/.test(className)) return 'radio'
@@ -375,16 +378,40 @@ function buildAndroidSelector(text: string | null, contentDescription: string |
   return null
 }
 
-function buildAndroidSemantic(clickable: boolean, className: string): UIElementSemanticMetadata {
-  return {
+function buildAndroidSemantic(clickable: boolean, className: string, role: string | null): UIElementSemanticMetadata {
+  const semantic: UIElementSemanticMetadata = {
     is_clickable: clickable,
     is_container: /recyclerview|scroll|layout|viewgroup|frame/.test(className)
   }
+
+  if (role === 'slider') {
+    semantic.semantic_role = 'slider'
+    semantic.adjustable = true
+    semantic.supported_actions = ['adjust']
+    semantic.state_shape = 'continuous'
+  } else if (role === 'stepper') {
+    semantic.semantic_role = 'stepper'
+    semantic.adjustable = true
+    semantic.supported_actions = ['increment', 'decrement']
+    semantic.state_shape = 'discrete'
+  } else if (role === 'dropdown') {
+    semantic.semantic_role = 'dropdown'
+    semantic.supported_actions = ['tap', 'expand']
+    semantic.state_shape = 'semantic'
+  } else if (role === 'segmented_control') {
+    semantic.semantic_role = 'segmented_control'
+    semantic.supported_actions = ['tap']
+    semantic.state_shape = 'discrete'
+  } else if (clickable) {
+    semantic.supported_actions = ['tap']
+  }
+
+  return semantic
 }
 
 function isSliderLikeAndroid(node: any): boolean {
   const className = String(node['@_class'] || '').toLowerCase()
-  return /seekbar|slider|range|progress/i.test(className)
+  return /seekbar|slider|range/i.test(className)
 }
 
 function extractAndroidState(node: any): UIElementState | null {
@@ -459,7 +486,7 @@ export function traverseNode(node: any, elements: UIElement[], parentIndex: numb
     const stableId = resourceId ?? (typeof contentDescription === 'string' && contentDescription.trim().length > 0 ? contentDescription : null)
     const testTag = stableId
     const selector = buildAndroidSelector(text, contentDescription, resourceId, normalizeClassName(className))
-    const semantic = buildAndroidSemantic(clickable, normalizeClassName(className))
+    const semantic = buildAndroidSemantic(clickable, normalizeClassName(className), role)
 
     const isUseful = clickable || (text && text.length > 0) || (contentDescription && contentDescription.length > 0);
 

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

@@ -0,0 +1,365 @@
+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 adjust_control unit tests...')
+
+    const originalGetUITreeHandler = (Observe as any).ToolsObserve.getUITreeHandler
+    const originalGetScreenFingerprintHandler = (Observe as any).ToolsObserve.getScreenFingerprintHandler
+    const originalTapHandler = (ToolsInteract as any).tapHandler
+    const originalSwipeHandler = (ToolsInteract as any).swipeHandler
+    const originalExpectStateHandler = (ToolsInteract as any).expectStateHandler
+
+  try {
+    ;(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: 100 }
+          }
+        }
+      ]
+    })
+
+    ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = async () => ({ fingerprint: 'fp_slider', activity: 'MainActivity' })
+
+    const wait = await ToolsInteract.waitForUIHandler({
+      selector: { text: 'Duration' },
+      condition: 'clickable',
+      timeout_ms: 200,
+      poll_interval_ms: 50,
+      platform: 'android'
+    })
+    assert.strictEqual(wait.status, 'success')
+    assert.ok(wait.element?.elementId)
+
+    const tapCalls: Array<{ platform?: string, x: number, y: number, deviceId?: string }> = []
+    const swipeCalls: Array<{ platform?: string, x1: number, y1: number, x2: number, y2: number, duration: number, deviceId?: string }> = []
+    ;(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).swipeHandler = async ({ platform, x1, y1, x2, y2, duration, deviceId }: any) => {
+      swipeCalls.push({ platform, x1, y1, x2, y2, duration, deviceId })
+      return {
+        device: { platform: platform || 'android', id: deviceId || 'mock-device', osVersion: '14', model: 'Pixel', simulator: true },
+        success: true,
+        start: [x1, y1],
+        end: [x2, y2],
+        duration
+      }
+    }
+
+    ;(ToolsInteract as any).expectStateHandler = async () => ({
+      success: true,
+      selector: { text: 'Duration' },
+      element_id: wait.element.elementId,
+      expected_state: { property: 'value', expected: 30 },
+      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: 30, raw_value: 30, value_range: { min: 0, max: 100 } }
+      },
+      observed_state: { property: 'value', value: 30, raw_value: 30 },
+      reason: 'value matches expected value'
+    })
+
+    const adjust = await ToolsInteract.adjustControlHandler({
+      element_id: wait.element.elementId,
+      property: 'value',
+      targetValue: 30,
+      tolerance: 0.5,
+      maxAttempts: 2,
+      platform: 'android'
+    })
+
+    assert.strictEqual(adjust.success, true)
+    assert.strictEqual(adjust.converged, true)
+    assert.strictEqual(adjust.within_tolerance, true)
+    assert.strictEqual(adjust.adjustment_mode, 'coordinate')
+    assert.strictEqual(adjust.target_state.target_value, 30)
+    assert.strictEqual(adjust.attempts, 1)
+    assert.strictEqual(tapCalls.length, 1)
+    assert.strictEqual(swipeCalls.length, 0)
+    assert.ok(tapCalls[0].x <= 66, 'tap should bias inward from the exact target point')
+    assert.strictEqual(adjust.action_type, 'adjust_control')
+    assert.strictEqual(adjust.target.selector.elementId, wait.element.elementId)
+
+    ;(ToolsInteract as any).expectStateHandler = async () => ({
+      success: true,
+      selector: { text: 'Duration' },
+      element_id: wait.element.elementId,
+      expected_state: { property: 'value', expected: 2 },
+      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: 2, raw_value: 2, value_range: { min: 0, max: 100 } }
+      },
+      observed_state: { property: 'value', value: 2, raw_value: 2 },
+      reason: 'value matches expected value'
+    })
+
+    const lowEndAdjust = await ToolsInteract.adjustControlHandler({
+      element_id: wait.element.elementId,
+      property: 'value',
+      targetValue: 2,
+      tolerance: 0.5,
+      maxAttempts: 2,
+      platform: 'android'
+    })
+
+    assert.strictEqual(lowEndAdjust.success, true)
+    assert.strictEqual(lowEndAdjust.converged, true)
+    assert.strictEqual(lowEndAdjust.within_tolerance, true)
+    assert.strictEqual(lowEndAdjust.attempts, 1)
+    assert.strictEqual(tapCalls.length, 2)
+    assert.strictEqual(swipeCalls.length, 0)
+    assert.ok(tapCalls[1].x >= 22, 'low-end tap should stay inside the first step instead of hugging the edge')
+
+    ;(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: 18,
+            raw_value: 18,
+            value_range: { min: 0, max: 20 }
+          }
+        }
+      ]
+    })
+
+    ;(ToolsInteract as any).expectStateHandler = async () => ({
+      success: true,
+      selector: { text: 'Duration' },
+      element_id: wait.element.elementId,
+      expected_state: { property: 'value', expected: 20 },
+      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: 20, raw_value: 20, value_range: { min: 0, max: 20 } }
+      },
+      observed_state: { property: 'value', value: 20, raw_value: 20 },
+      reason: 'value matches expected value'
+    })
+
+    const highEndAdjust = await ToolsInteract.adjustControlHandler({
+      element_id: wait.element.elementId,
+      property: 'value',
+      targetValue: 20,
+      tolerance: 0.5,
+      maxAttempts: 2,
+      platform: 'android'
+    })
+
+    assert.strictEqual(highEndAdjust.success, true)
+    assert.strictEqual(highEndAdjust.converged, true)
+    assert.strictEqual(highEndAdjust.within_tolerance, true)
+    assert.strictEqual(highEndAdjust.attempts, 1)
+    assert.strictEqual(tapCalls.length, 3)
+    assert.strictEqual(swipeCalls.length, 0)
+    assert.ok(tapCalls[2].x >= 180, 'high-end tap should bias into the last step without hitting the edge')
+
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => ({
+      device: { platform: 'android', id: 'mock-device', osVersion: '14', model: 'Pixel', simulator: true },
+      screen: '',
+      resolution: { width: 1440, height: 3200 },
+      elements: [
+        {
+          text: 'Precision',
+          type: 'android.widget.SeekBar',
+          contentDescription: null,
+          clickable: true,
+          enabled: true,
+          visible: true,
+          bounds: [0, 0, 3000, 40],
+          resourceId: 'seek_precision',
+          state: {
+            value: 9000,
+            raw_value: 9000,
+            value_range: { min: 0, max: 10000 }
+          }
+        }
+      ]
+    })
+
+    ;(ToolsInteract as any).expectStateHandler = async () => ({
+      success: true,
+      selector: { text: 'Precision' },
+      element_id: wait.element.elementId,
+      expected_state: { property: 'value', expected: 9999 },
+      element: {
+        elementId: wait.element.elementId,
+        text: 'Precision',
+        resource_id: 'seek_precision',
+        accessibility_id: null,
+        class: 'android.widget.SeekBar',
+        bounds: [0, 0, 3000, 40],
+        index: 0,
+        state: { value: 9999, raw_value: 9999, value_range: { min: 0, max: 10000 } }
+      },
+      observed_state: { property: 'value', value: 9999, raw_value: 9999 },
+      reason: 'value matches expected value'
+    })
+
+    const precisionAdjust = await ToolsInteract.adjustControlHandler({
+      selector: { text: 'Precision' },
+      property: 'value',
+      targetValue: 9999,
+      tolerance: 0.5,
+      maxAttempts: 2,
+      platform: 'android'
+    })
+
+    assert.strictEqual(precisionAdjust.success, true)
+    assert.strictEqual(precisionAdjust.converged, true)
+    assert.strictEqual(precisionAdjust.within_tolerance, true)
+    assert.strictEqual(precisionAdjust.attempts, 1)
+    assert.strictEqual(tapCalls.length, 4)
+    assert.strictEqual(swipeCalls.length, 0)
+    assert.ok(tapCalls[3].x > 2750, 'wide, high-range control should not be clamped to a 3% endpoint margin')
+
+    let treeFetches = 0
+    let retryVerificationCount = 0
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => {
+      treeFetches++
+      return {
+        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: false,
+        error: 'tap failed'
+      }
+    }
+
+    ;(ToolsInteract as any).swipeHandler = async ({ platform, x1, y1, x2, y2, duration, deviceId }: any) => {
+      swipeCalls.push({ platform, x1, y1, x2, y2, duration, deviceId })
+      return {
+        device: { platform: platform || 'android', id: deviceId || 'mock-device', osVersion: '14', model: 'Pixel', simulator: true },
+        success: true,
+        start: [x1, y1],
+        end: [x2, y2],
+        duration
+      }
+    }
+
+    ;(ToolsInteract as any).expectStateHandler = async () => {
+      retryVerificationCount++
+      const value = retryVerificationCount === 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 cachedResolveAdjust = await ToolsInteract.adjustControlHandler({
+      element_id: wait.element.elementId,
+      property: 'value',
+      targetValue: 12,
+      tolerance: 0.5,
+      maxAttempts: 2,
+      platform: 'android'
+    })
+
+    assert.strictEqual(cachedResolveAdjust.success, true)
+    assert.strictEqual(cachedResolveAdjust.converged, true)
+    assert.strictEqual(cachedResolveAdjust.within_tolerance, true)
+    assert.strictEqual(cachedResolveAdjust.attempts, 3)
+    assert.strictEqual(treeFetches, 1, 'second attempt should reuse the resolved element instead of refetching the UI tree')
+
+    console.log('adjust_control unit tests passed')
+  } finally {
+    ;(Observe as any).ToolsObserve.getUITreeHandler = originalGetUITreeHandler
+    ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = originalGetScreenFingerprintHandler
+    ;(ToolsInteract as any).tapHandler = originalTapHandler
+    ;(ToolsInteract as any).swipeHandler = originalSwipeHandler
+    ;(ToolsInteract as any).expectStateHandler = originalExpectStateHandler
+  }
+}
+
+run().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})