mobile-debug-mcp 0.32.4 → 0.33.0

package/test/unit/server/correlated-evidence.test.ts

@@ -0,0 +1,194 @@
+import assert from 'node:assert/strict'
+import { chmodSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { handleToolCall, toolDefinitions } from '../../../src/server-core.js'
+import { AndroidObserve } from '../../../src/observe/android.js'
+import { iOSObserve, _setIOSActiveLogStream, _clearIOSActiveLogStream } from '../../../src/observe/ios.js'
+import { _setDeviceListersForTests, _resetDeviceListersForTests } from '../../../src/utils/resolve-device.js'
+import { deriveSnapshotMetadata } from '../../../src/observe/snapshot-metadata.js'
+
+async function run() {
+  const directory = mkdtempSync(path.join(tmpdir(), 'mcp-evidence-'))
+  const binary = path.join(directory, 'native')
+  const events = path.join(directory, 'events')
+  const keys = ['ADB_PATH', 'IDB_PATH', 'MCP_IDB_PATH', 'XCRUN_PATH', 'EVIDENCE_FAIL_INPUT', 'EVIDENCE_INPUT_SLOW']
+  const env = Object.fromEntries(keys.map(key => [key, process.env[key]]))
+  writeFileSync(events, '')
+  writeFileSync(binary, `#!/usr/bin/env node
+const fs = require('fs')
+const args = process.argv.slice(2).join(' ')
+fs.appendFileSync(${JSON.stringify(events)}, args + '\\n')
+if (args.includes('ro.build.version.release')) console.log('16')
+else if (args.includes('ro.product.model')) console.log('Fixture')
+else if (args.includes('ro.kernel.qemu')) console.log('1')
+else if (args.includes('simctl list devices')) console.log(JSON.stringify({devices:{'iOS-18':[{udid:'fixture-ios',name:'Fixture',state:'Booted'}]}}))
+else if (args.includes('list-targets')) console.log('[]')
+else if (args.includes('shell input') || args.includes('ui tap') || args.includes('ui swipe')) { if (process.env.EVIDENCE_FAIL_INPUT) process.exit(1); if (process.env.EVIDENCE_INPUT_SLOW) setTimeout(() => process.exit(0), 2000) }
+else if (args.includes('pidof')) console.log('123')
+else if (args.includes('logcat')) { console.log('2026-10-30 10:00:00.000 123 123 I Fixture: stream-owned'); setInterval(() => {}, 1000) }
+else if (args.includes('monkey') || args.includes('simctl launch')) console.log('launched: 123')
+else process.exit(1)
+`)
+  chmodSync(binary, 0o755)
+  for (const key of keys.slice(0, 4)) process.env[key] = binary
+  const device = (platform: 'android' | 'ios', id?: string) => ({ platform, id: id ?? `fixture-${platform}`, osVersion: '16', model: 'Fixture', simulator: true })
+  _setDeviceListersForTests({ listAndroidDevices: async () => [device('android'), device('android', 'other')], listIOSDevices: async () => [device('ios')] })
+  const originals: Array<() => void> = []
+  let captureCount = 0
+  let failScreenshot = false
+  for (const [platform, klass] of [['android', AndroidObserve], ['ios', iOSObserve]] as const) {
+    const prototype = klass.prototype as any
+    const replace = (name: string, fn: (...args: any[]) => any) => {
+      const original = prototype[name]; originals.push(() => { prototype[name] = original }); prototype[name] = fn
+    }
+    replace('collectGetUITree', async (id: string) => {
+      captureCount++
+      const body = { device: device(platform, id), elements: [{ text: 'Ready', resourceId: 'target', contentDescription: 'target', type: 'Button', clickable: true, enabled: true, visible: true, bounds: [0, 0, 50, 50] }], resolution: { width: 100, height: 200 }, screen: 'Ready' }
+      return { ...body, ...deriveSnapshotMetadata(`${platform}:${id}`, body as any, 'ui_tree') }
+    })
+    replace(platform === 'android' ? 'collectCaptureScreen' : 'collectCaptureScreenshot', async (id: string) => {
+      captureCount++
+      if (failScreenshot) throw new Error('screenshot offline')
+      return { device: device(platform, id), screenshot: 'fixture-image', screenshot_mime: 'image/png', resolution: { width: 100, height: 200 } }
+    })
+    replace('collectGetLogs', async (filters: any) => {
+      captureCount++
+      return { device: device(platform, filters.deviceId), logs: [{ timestamp: '2020-01-01T00:00:00Z', level: 'INFO', message: 'preserved' }], logCount: 1 }
+    })
+    if (platform === 'android') replace('collectGetCurrentScreen', async (id: string) => ({ device: device(platform, id), activity: 'FixtureActivity', package: 'fixture.app' }))
+  }
+  const payload = (r: any) => JSON.parse(r.content[0].text)
+  const call = async (name: string, args: Record<string, unknown>) => payload(await handleToolCall(name, args))
+  const refFor = (value: any) => ({ sessionId: value.evidence.session_id, actionId: value.evidence.action_id })
+  try {
+    for (const platform of ['android', 'ios'] as const) {
+      const target = { platform, deviceId: `fixture-${platform}` }
+      for (const responseMode of ['compact', 'debug']) {
+        const a = await call('tap', { ...target, responseMode, verificationMode: 'none', x: 10, y: 10 })
+        assert.equal(a.success, true)
+        assert.equal(a.action_id, a.evidence.action_id)
+        assert.equal(a.evidence.action_id, a.evidence.correlation_id)
+        assert.ok(a.evidence.dispatch_started_at_ms)
+        assert.ok(a.evidence.dispatch_completed_at_ms >= a.evidence.dispatch_started_at_ms)
+        assert.equal(a.evidence.verification_completed_at_ms, null)
+        if (responseMode === 'debug') assert.equal(a.trace.action_id, a.action_id)
+        const actionRef = refFor(a)
+        const image = await handleToolCall('capture_screenshot', { ...target, actionRef })
+        const imageMeta = payload(image)
+        assert.equal(imageMeta.evidence.action_id, a.action_id)
+        assert.equal(imageMeta.evidence.correlation_id, a.evidence.correlation_id)
+        assert.equal(image.content[1].data, 'fixture-image')
+        assert.equal(imageMeta.evidence.observations[0].freshness, 'fresh')
+        const logs = await handleToolCall('get_logs', { ...target, actionRef })
+        assert.equal(payload(logs).evidence.action_id, a.action_id)
+        assert.equal(JSON.parse(logs.content[1].text!).logs[0].message, 'preserved')
+        assert.equal(payload(logs).evidence.observations[0].event_time_comparable, false)
+        const tree = await call('get_ui_tree', { ...target, responseMode, actionRef })
+        assert.equal(tree.evidence.action_id, a.action_id)
+        assert.ok(tree.evidence.observations[0].snapshot_revision)
+        const verified = await call('tap', { ...target, responseMode, verificationMode: 'full', x: 10, y: 10 })
+        assert.ok(verified.evidence.verification_completed_at_ms >= verified.evidence.dispatch_completed_at_ms)
+        assert.ok(verified.evidence.observations.some((v: any) => v.freshness_reasons.includes('BEFORE_ACTION')))
+        assert.ok(verified.evidence.observations.some((v: any) => v.freshness === 'fresh'))
+        process.env.EVIDENCE_FAIL_INPUT = '1'
+        const failed = await call('tap', { ...target, responseMode, verificationMode: 'none', x: 10, y: 10 })
+        assert.equal(failed.success, false)
+        assert.ok(failed.evidence.dispatch_started_at_ms)
+        assert.equal(failed.evidence.verification_completed_at_ms, null)
+        delete process.env.EVIDENCE_FAIL_INPUT
+        const blocked = await call('tap', { ...target, responseMode, verificationMode: 'none', x: 10, y: 10,
+          expectedState: { snapshotSessionId: 'expired-session', snapshotRevision: 1 } })
+        assert.equal(blocked.failure_code, 'PRECONDITION_UNAVAILABLE')
+        assert.equal(blocked.evidence.dispatch_started_at_ms, null)
+        assert.equal(blocked.evidence.verification_completed_at_ms, null)
+      }
+      failScreenshot = true
+      const partial = await call('capture_debug_snapshot', { ...target, includeLogs: false })
+      assert.equal(partial.raw.screenshot_error, 'screenshot offline')
+      assert.equal(partial.evidence.observations.find((v: any) => v.kind === 'screenshot').status, 'failed')
+      assert.equal(partial.evidence.observations.find((v: any) => v.kind === 'logs').status, 'omitted')
+      failScreenshot = false
+      const disabled = await call('capture_debug_snapshot', { ...target, includeScreenshot: false, includeLogs: false })
+      assert.equal(disabled.raw.screenshot, null)
+      assert.equal(disabled.evidence.observations.find((v: any) => v.kind === 'screenshot').status, 'omitted')
+      const snapshot = await call('capture_debug_snapshot', target)
+      assert.equal(snapshot.raw.screenshot, 'fixture-image')
+      assert.equal(snapshot.raw.logs[0].message, 'preserved')
+      assert.ok(snapshot.evidence.observations.every((v: any) => !v.device || v.device.id === target.deviceId))
+    }
+    process.env.EVIDENCE_INPUT_SLOW = '1'
+    const timeout = await call('tap', { platform: 'android', deviceId: 'fixture-android', x: 1, y: 1,
+      verificationMode: 'none', responseMode: 'compact', actionTimeoutMs: 500 })
+    delete process.env.EVIDENCE_INPUT_SLOW
+    assert.equal(timeout.failure_code, 'ACTION_TIMEOUT')
+    assert.ok(timeout.evidence.dispatch_started_at_ms)
+    assert.ok(timeout.evidence.dispatch_completed_at_ms)
+    assert.equal(timeout.evidence.verification_completed_at_ms, null)
+    const before = captureCount
+    const malformed = await call('capture_screenshot', { platform: 'android', actionRef: { actionId: '' } })
+    assert.match(malformed.error.message, /INVALID_ARGUMENT/)
+    assert.equal(captureCount, before)
+    const a = await call('tap', { platform: 'android', deviceId: 'fixture-android', x: 1, y: 1, verificationMode: 'none' })
+    const mismatch = await call('capture_screenshot', { platform: 'android', deviceId: 'other', actionRef: refFor(a) })
+    assert.equal(mismatch.evidence.association_reason, 'DEVICE_MISMATCH')
+    assert.notEqual(mismatch.evidence.correlation_id, a.evidence.correlation_id)
+    const journey = await call('run_journey', { platform: 'android', deviceId: 'fixture-android', responseMode: 'debug',
+      defaults: { verificationMode: 'full' }, steps: [{ id: 'one', type: 'start_app', appId: 'fixture.app' }, { id: 'two', type: 'start_app', appId: 'fixture.app' }] })
+    assert.equal(journey.success, true)
+    assert.equal(journey.steps[0].result.evidence.correlation_id, journey.evidence.correlation_id)
+    assert.equal(journey.steps[1].result.evidence.correlation_id, journey.evidence.correlation_id)
+    assert.notEqual(journey.steps[0].result.evidence.action_id, journey.steps[1].result.evidence.action_id)
+    assert.ok(journey.steps[0].result.evidence.observations.some((v: any) => v.freshness === 'stale'))
+
+    assert.ok(journey.steps[0].result.evidence.operation_completed_at_ms <= journey.steps[1].result.evidence.operation_started_at_ms)
+    const light = await call('run_journey', { platform: 'android', deviceId: 'fixture-android', responseMode: 'compact',
+      defaults: { verificationMode: 'light' }, steps: [
+        { id: 'tap', type: 'tap', selector: { accessibility_id: 'target' } },
+        { id: 'verify', type: 'assert', assertion: { kind: 'element_visible', selector: { accessibility_id: 'target' } } }
+      ] })
+    assert.equal(light.success, true)
+    const lightStep = light.steps[0].result
+    assert.ok(lightStep.evidence.verification_completed_at_ms)
+    const afterLight = await call('capture_screenshot', { platform: 'android', deviceId: 'fixture-android', actionRef: refFor(lightStep) })
+    assert.equal(afterLight.evidence.verification_completed_at_ms, lightStep.evidence.verification_completed_at_ms)
+
+    const started = await call('start_log_stream', { platform: 'android', deviceId: 'other', sessionId: 'evidence-owned', packageName: 'fixture.app' })
+    assert.equal(started.success, true)
+    let androidStream: any
+    for (let i = 0; i < 100; i++) {
+      androidStream = await call('read_log_stream', { platform: 'android', sessionId: 'evidence-owned', actionRef: refFor(a) })
+      if (androidStream.entries.length) break
+      await new Promise(resolve => setTimeout(resolve, 10))
+    }
+    assert.ok(androidStream.entries.length)
+    assert.equal(androidStream.evidence.device.id, 'other')
+    assert.equal(androidStream.evidence.association_reason, 'DEVICE_MISMATCH')
+    assert.match(readFileSync(events, 'utf8'), /-s other logcat/)
+    assert.equal((await call('stop_log_stream', { platform: 'android', sessionId: 'evidence-owned' })).success, true)
+    const streamFile = path.join(directory, 'stream.ndjson')
+    writeFileSync(streamFile, JSON.stringify({ message: 'stream-owned', _iso: '2020-01-01T00:00:00Z' }) + '\n')
+    _setIOSActiveLogStream('owned', streamFile, { platform: 'ios', id: 'fixture-ios' })
+    // Discovery returning a different device must not retarget this stream read.
+    _setDeviceListersForTests({ listIOSDevices: async () => { throw new Error('discovery must not run') } })
+    const stream = await call('read_log_stream', { platform: 'ios', sessionId: 'owned' })
+    assert.equal(stream.entries[0].message, 'stream-owned')
+    assert.equal(stream.evidence.device.id, 'fixture-ios')
+    assert.equal(stream.evidence.observations[0].device.id, 'fixture-ios')
+    for (const name of ['capture_screenshot', 'get_ui_tree', 'get_screen_fingerprint', 'capture_debug_snapshot', 'get_logs', 'read_log_stream']) {
+      assert.ok((toolDefinitions.find(v => v.name === name)!.inputSchema.properties as any).actionRef)
+    }
+    assert.match(readFileSync(events, 'utf8'), /shell input tap/)
+    assert.match(readFileSync(events, 'utf8'), /ui tap/)
+  } finally {
+    await new AndroidObserve().stopLogStream('evidence-owned')
+    rmSync(path.join(tmpdir(), 'mobile-debug-log-evidence-owned.ndjson'), { force: true })
+    _clearIOSActiveLogStream('owned')
+    for (const restore of originals) restore()
+    _resetDeviceListersForTests()
+    for (const [key, value] of Object.entries(env)) { if (value === undefined) delete process.env[key]; else process.env[key] = value }
+    rmSync(directory, { recursive: true, force: true })
+  }
+  console.log('Correlated MCP response, native dispatch, snapshot, journey and stream contracts: PASS')
+}
+run().catch(error => { console.error(error); process.exit(1) })

package/test/unit/server/readiness.test.ts

@@ -0,0 +1,170 @@
+import assert from 'node:assert/strict'
+import { AjvJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/ajv'
+import { handleToolCall, toolDefinitions } from '../../../src/server-core.js'
+import { ToolsObserve, AndroidObserve } from '../../../src/observe/index.js'
+import { deriveSnapshotMetadata, resetSnapshotMetadataForTests } from '../../../src/observe/snapshot-metadata.js'
+import { _setDeviceListersForTests, _resetDeviceListersForTests, withResolvedDevice } from '../../../src/utils/resolve-device.js'
+import { runWithBudget } from '../../../src/utils/operation-budget.js'
+
+async function run() {
+  const originalTree = ToolsObserve.getUITreeHandler
+  const originalNative = AndroidObserve.prototype.getUITree
+  const device = { platform: 'android', id: 'fixture', model: 'Fixture', osVersion: '16', simulator: true }
+  let reads = 0
+  let mode = 'stable'
+  let delayed = 0
+  let expireDuringRead: (() => void) | undefined
+  const tree = () => {
+    const label = mode === 'changing' ? `Item ${reads}` : mode === 'changeThenStable' && reads === 1 ? 'Before' : 'Ready'
+    const elements = [{ type: 'Button', text: label, contentDescription: 'target', visible: true, enabled: true, clickable: true, bounds: [0, 0, 50, 50] }]
+    if (mode === 'loading' || mode === 'loadingThenTimeout' || (mode === 'loaderThenReady' && reads <= 2)) elements.push({ type: 'android.widget.ProgressBar', text: '', contentDescription: '', visible: true, enabled: true, clickable: false, bounds: [0, 60, 20, 80] })
+    const body = { device, elements, screen: '', resolution: { width: 100, height: 200 } }
+    return { ...body, ...deriveSnapshotMetadata('android:fixture', body, 'ui_tree') }
+  }
+  ToolsObserve.getUITreeHandler = async () => {
+    reads++
+    if (delayed) await new Promise(resolve => setTimeout(resolve, delayed))
+    if (mode === 'loadingThenTimeout' && reads === 2) { expireDuringRead?.(); throw new Error('ACTION_TIMEOUT') }
+    if (mode === 'error') throw new Error('observation failed')
+    if (mode === 'disconnect') return { ...tree(), error: 'device fixture offline' } as any
+    return tree()
+  }
+  _setDeviceListersForTests({ listAndroidDevices: async () => [device] })
+  // Sample counts depend on elapsed time, not the host timer's wakeup precision.
+  // Advance both clocks exactly when a fixture/poll timer completes.
+  const originalDateNow = Date.now
+  const originalPerformanceNow = Object.getOwnPropertyDescriptor(performance, 'now')
+  const originalSetTimeout = globalThis.setTimeout
+  const epoch = originalDateNow()
+  let elapsed = 0
+  Date.now = () => epoch + elapsed
+  Object.defineProperty(performance, 'now', { configurable: true, value: () => elapsed })
+  globalThis.setTimeout = ((callback: (...args: any[]) => void, delay = 0, ...args: any[]) => {
+    queueMicrotask(() => { elapsed += Math.max(0, Number(delay) || 0); callback(...args) })
+    return {} as ReturnType<typeof setTimeout>
+  }) as typeof setTimeout
+  const call = async (name: string, args: any = {}) => JSON.parse((await handleToolCall(name, { platform: 'android', deviceId: 'fixture', ...args })).content[0].text!)
+  try {
+    let result = await call('get_app_readiness', { stabilityMs: 100 })
+    assert.equal(result.readiness.state, 'settled')
+    assert.equal(result.success, true)
+    assert.equal(reads, 2)
+    mode = 'loading'; reads = 0
+    result = await call('get_app_readiness')
+    assert.equal(result.readiness.state, 'loading')
+    assert.equal(reads, 1)
+    mode = 'changing'; reads = 0
+    result = await call('get_app_readiness', { stabilityMs: 100 })
+    assert.equal(result.readiness.state, 'transitioning')
+    assert.equal(result.success, true)
+    mode = 'loaderThenReady'; reads = 0
+    result = await call('wait_for_app_ready', { stabilityMs: 100, pollIntervalMs: 100, timeoutMs: 1500 })
+    assert.equal(result.readiness.state, 'settled')
+    assert.equal(result.success, true)
+    assert.equal(reads, 4)
+    mode = 'loading'; reads = 0
+    result = await call('wait_for_app_ready', { timeoutMs: 200, pollIntervalMs: 100 })
+    assert.equal(result.failure_code, 'READINESS_TIMEOUT')
+    assert.equal(result.readiness.state, 'loading')
+    assert.ok(result.readiness.limitations.includes('DEADLINE_EXCEEDED'))
+    assert.equal(result.readiness.capabilities.unresponsive, false)
+    mode = 'stable'; reads = 0; delayed = 150
+    result = await call('get_app_readiness', { timeoutMs: 100 })
+    assert.equal(result.success, false, 'late physical read cannot produce success')
+    assert.equal(result.readiness.state, 'unknown')
+    delayed = 0
+    mode = 'disconnect'; reads = 0
+    result = await call('wait_for_app_ready')
+    assert.equal(result.failure_code, 'DEVICE_UNAVAILABLE')
+    assert.equal(reads, 1)
+    mode = 'loading'; reads = 0
+    const ordinary = await call('wait_for_ui', { selector: { text: 'Ready' }, timeout_ms: 1500, poll_interval_ms: 100 })
+    assert.equal(ordinary.status, 'success', 'default wait keeps predicate-only semantics')
+    assert.equal(ordinary.readiness, undefined)
+    assert.equal(reads, 2)
+    reads = 0
+    const blocked = await call('wait_for_ui', { selector: { text: 'Ready' }, requireReady: true, timeout_ms: 650, poll_interval_ms: 100 })
+    assert.equal(blocked.status, 'timeout')
+    assert.equal(blocked.readiness.state, 'loading')
+    assert.equal(blocked.observed.condition_satisfied, true, 'a readiness timeout must not pretend the visible target was absent')
+    assert.ok(blocked.readiness.limitations.includes('DEADLINE_EXCEEDED'))
+    // Force expiry inside a later acquisition rather than depending on timer rounding.
+    for (const tool of ['wait_for_ui', 'wait_for_app_ready']) {
+      const originalNow = Object.getOwnPropertyDescriptor(performance, 'now')
+      const nativeNow = performance.now.bind(performance)
+      let advance = 0
+      Object.defineProperty(performance, 'now', { configurable: true, value: () => nativeNow() + advance })
+      expireDuringRead = () => { advance += 2000 }
+      mode = 'loadingThenTimeout'; reads = 0
+      try {
+        const timedOut = await call(tool, tool === 'wait_for_ui'
+          ? { selector: { text: 'Ready' }, requireReady: true, timeout_ms: 1000, poll_interval_ms: 100 }
+          : { timeoutMs: 1000, pollIntervalMs: 100 })
+        assert.equal(reads, 2)
+        assert.equal(timedOut.readiness.state, 'loading', 'expiry retains the last valid loading evidence')
+        assert.ok(timedOut.readiness.limitations.includes('DEADLINE_EXCEEDED'))
+        assert.equal(timedOut.readiness.evidence.at(-1).code, 'NATIVE_LOADING_INDICATOR')
+        if (tool === 'wait_for_ui') assert.equal(timedOut.observed.condition_satisfied, true)
+        else assert.equal(timedOut.failure_code, 'READINESS_TIMEOUT')
+      } finally {
+        expireDuringRead = undefined
+        if (originalNow) Object.defineProperty(performance, 'now', originalNow)
+        else delete (performance as any).now
+      }
+    }
+    mode = 'loaderThenReady'; reads = 0
+    const ready = await call('wait_for_ui', { selector: { text: 'Ready' }, requireReady: true, timeout_ms: 2000, poll_interval_ms: 100 })
+    assert.equal(ready.status, 'success')
+    assert.equal(ready.readiness.state, 'settled')
+    assert.equal(reads, ready.readiness.sample_count, 'predicate and readiness share samples')
+    mode = 'changeThenStable'; reads = 0
+    const changed = await call('wait_for_ui_change', { requireReady: true, timeout_ms: 2500, stability_window_ms: 0 })
+    assert.equal(changed.success, true, JSON.stringify(changed))
+    assert.equal(changed.readiness.state, 'settled')
+    assert.equal(reads, changed.readiness.sample_count)
+    mode = 'stable'; reads = 0
+    result = await runWithBudget(100, () => call('wait_for_app_ready', { timeoutMs: 2000, stabilityMs: 500 }))
+    assert.equal(result.success, false, 'outer budget bounds the wait')
+    assert.ok(result.readiness.limitations.includes('DEADLINE_EXCEEDED'))
+    _setDeviceListersForTests({ listAndroidDevices: async () => { await new Promise(resolve => setTimeout(resolve, 140)); return [] } })
+    const discoveryTimeout = await call('wait_for_app_ready', { timeoutMs: 100 })
+    assert.equal(discoveryTimeout.failure_code, 'READINESS_TIMEOUT', 'discovery deadline is not proof of a missing device')
+    assert.ok(discoveryTimeout.readiness.limitations.includes('DEADLINE_EXCEEDED'))
+    _setDeviceListersForTests({ listAndroidDevices: async () => [device] })
+    // The ordinary tree path adds single-sample metadata without extra acquisition.
+    ToolsObserve.getUITreeHandler = originalTree
+    let nativeReads = 0
+    AndroidObserve.prototype.getUITree = async () => { nativeReads++; return tree() as any }
+    for (const responseMode of ['debug', 'compact'] as const) {
+      const observed: any = await withResolvedDevice(device, () => ToolsObserve.getUITreeHandler({ platform: 'android', deviceId: 'fixture', responseMode }))
+      assert.equal(observed.readiness.state, 'unknown')
+      assert.equal(observed.readiness.sample_count, 1)
+    }
+    assert.equal(nativeReads, 2, 'one native read per public tree response')
+    const validator = new AjvJsonSchemaValidator()
+    for (const name of ['get_app_readiness', 'wait_for_app_ready']) {
+      const schema = validator.getValidator(toolDefinitions.find(tool => tool.name === name)!.inputSchema)
+      assert.equal(schema({ platform: 'android' }).valid, true)
+      for (const args of [{ platform: 'other' }, { platform: 'android', timeoutMs: 99 }, { platform: 'android', stabilityMs: 10001 }, { platform: 'android', extra: true }, { platform: 'android', deviceId: '' }]) {
+        assert.equal(schema(args).valid, false)
+        const result = JSON.parse((await handleToolCall(name, args)).content[0].text!)
+        assert.match(result.error.message, /INVALID_ARGUMENT/)
+      }
+    }
+    for (const name of ['wait_for_ui', 'wait_for_ui_change']) {
+      const bad = await call(name, { requireReady: 'yes' })
+      assert.match(bad.error.message, /INVALID_ARGUMENT/)
+    }
+    console.log('Readiness tools, schemas and opt-in waits: PASS')
+  } finally {
+    globalThis.setTimeout = originalSetTimeout
+    Date.now = originalDateNow
+    if (originalPerformanceNow) Object.defineProperty(performance, 'now', originalPerformanceNow)
+    else delete (performance as any).now
+    ToolsObserve.getUITreeHandler = originalTree
+    AndroidObserve.prototype.getUITree = originalNative
+    _resetDeviceListersForTests()
+    resetSnapshotMetadataForTests()
+  }
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

package/test/unit/server/selector_tap_target.test.ts

@@ -0,0 +1,79 @@
+import assert from 'node:assert/strict'
+import { handleToolCall } from '../../../src/server-core.js'
+import { ToolsInteract } from '../../../src/interact/index.js'
+import { ToolsObserve } from '../../../src/observe/index.js'
+import { remainingBudget } from '../../../src/utils/operation-budget.js'
+
+async function run() {
+  const originalTree = ToolsObserve.getUITreeHandler
+  const originalTap = ToolsInteract.tapHandler
+  const tab = () => ({ bounds: [244, 1408, 476, 1528], clickable: true, visible: true, enabled: true, children: [1] })
+  const label = () => ({ text: 'GENER8', bounds: [330, 1489, 391, 1513], clickable: false, visible: true, enabled: true, parentId: 0 })
+  let elements: any[] = [tab(), label()]
+  let error: string | undefined
+  let observedBudget = 0
+  let reads = 0
+  const taps: Array<{ x: number; y: number }> = []
+  ToolsObserve.getUITreeHandler = async () => {
+    observedBudget = remainingBudget()
+    reads++
+    return { device: { platform: 'android', id: 'fixture' }, elements, captured_at_ms: Date.now(), error } as any
+  }
+  ToolsInteract.tapHandler = async args => {
+    taps.push({ x: args.x, y: args.y })
+    return { device: { platform: 'android', id: 'fixture' }, success: true } as any
+  }
+  const call = async (args: Record<string, unknown> = {}) => JSON.parse((await handleToolCall('tap_element', {
+    platform: 'android', deviceId: 'fixture', selector: { text: 'GENER8' }, responseMode: 'compact', verificationMode: 'none', ...args
+  })).content[0].text!)
+  try {
+    for (const waitFor of [undefined, {}, { condition: 'exists' }, { condition: 'visible' }, { condition: 'clickable' }]) {
+      reads = 0
+      const result = await call(waitFor ? { waitFor } : {})
+      assert.equal(result.success, true)
+      assert.deepEqual(taps.at(-1), { x: 360, y: 1468 })
+      assert.equal(reads, 1, 'Reuse the selector acquisition for dispatch resolution')
+      assert.ok(observedBudget > 1500 && observedBudget <= 5000, `One acquisition should use the action budget: ${observedBudget}`)
+    }
+    await call({ actionTimeoutMs: 12000 })
+    assert.ok(observedBudget > 10000 && observedBudget <= 12000)
+    await call({ actionTimeoutMs: 12000, waitFor: { condition: 'exists', timeoutMs: 700 } })
+    assert.ok(observedBudget > 0 && observedBudget <= 700)
+    const tapCount = taps.length
+    error = 'Failed to get UI tree: ACTION_TIMEOUT'
+    const timeout = await call()
+    assert.equal(timeout.failure_code, 'ACTION_TIMEOUT', 'Observation timeout must not claim that the label is missing')
+    assert.equal(timeout.evidence.dispatch_started_at_ms, null)
+    assert.equal(taps.length, tapCount)
+    error = undefined
+
+    for (const patch of [{ enabled: false }, { visible: false }]) {
+      for (const condition of ['exists', 'visible', 'clickable']) {
+        elements = [tab(), { ...label(), ...patch }]
+        // A short explicit wait bounds unsatisfied visible/clickable conditions.
+        const result = await call({ waitFor: { condition, timeoutMs: 100 } })
+        assert.equal(result.success, false)
+        assert.equal(taps.length, tapCount, 'Never bypass hidden/disabled labels through an enabled parent')
+      }
+    }
+    elements = [{ ...tab(), enabled: false }, label()]
+    assert.equal((await call({ waitFor: { condition: 'exists' } })).failure_code, 'ELEMENT_NOT_INTERACTABLE')
+    assert.equal(taps.length, tapCount)
+    elements = [label()]
+    assert.equal((await call({ waitFor: { condition: 'exists' } })).failure_code, 'ELEMENT_NOT_INTERACTABLE')
+    assert.equal(taps.length, tapCount, 'A plain label without an actionable container remains untappable')
+    elements = [tab(), label(), { ...label(), parentId: 0 }]
+    assert.equal((await call()).failure_code, 'AMBIGUOUS_TARGET')
+    assert.equal(taps.length, tapCount)
+    // Standalone waits keep returning the matched leaf for exists; promotion is tap-only.
+    elements = [tab(), label()]
+    const wait = await ToolsInteract.waitForUIHandler({ selector: { text: 'GENER8' }, condition: 'exists', platform: 'android', singleObservation: true })
+    assert.equal(wait.element.index, 1)
+  } finally {
+    ToolsObserve.getUITreeHandler = originalTree
+    ToolsInteract.tapHandler = originalTap
+    ToolsInteract._resetResolvedUiElementsForTests()
+  }
+  console.log('Selector tap acquisition budget, executable ancestor, and rejection guards: PASS')
+}
+run().catch(error => { console.error(error); process.exit(1) })

package/test/unit/server/tap_selector.test.ts

@@ -24,6 +24,8 @@ async function run() {
     assert.equal(success.success, true)
     assert.equal(tapCount, 1)
     assert.equal(lastWait.condition, 'clickable')
+    assert.equal(lastWait.timeout_ms, 5000)
+    assert.equal(lastWait.resolveTapTarget, true)
     assert.equal(lastWait.singleObservation, true)
     assert.equal(lastWait.singleAttempt, true)
     assert.equal(lastWait.rejectAmbiguous, true)

package/skills/mobile-debug-tools-usage/SKILL.md

@@ -1,96 +0,0 @@
----
-name: mobile-debug-mcp
-description: Use mobile-debug MCP to inspect, interact with, and verify any Android or iOS app on a device or emulator.
-metadata:
-  author: mobile-debug-mcp contributors
-  version: "1.1"
----
-
-# Mobile-debug MCP usage
-
-Use mobile-debug MCP when a task needs evidence from a running Android or iOS app. Identify the device and the state or behaviour to check, then choose the smallest observation or action that can establish it. A successful tool call confirms only what that tool reports; check the resulting app state before claiming an outcome.
-
-## Choose the lightest evidence that proves the claim
-
-- Prefer a screenshot for routine visual navigation, layout checks, and visible
-  outcomes that can be established from the image.
-- Use UI-tree reads and accessibility assertions such as `expect_element_visible`,
-  `expect_state`, or `wait_for_ui` when reliable element selection or a structured
-  property check is required. An image alone does not establish accessibility
-  properties such as enabled state.
-- Use a debug snapshot when an ordinary observation does not explain a failure or multiple kinds of evidence are needed together.
-- Use logs or network activity for claims about errors or requests. Correlate them with the relevant action and time window; they do not establish what the user saw.
-- Use platform shell commands only for device or system operations that the MCP tools cannot expose. Treat shell output as evidence of that operation, not of the app's visible state.
-
-Choose one observation that proves the required outcome. Avoid automatically
-reading the UI tree after a screenshot or taking a screenshot after a sufficient
-structured assertion.
-
-## Keep Android inspection APK-free
-
-Use the standard ADB path for Android inspection. It requires no helper APK.
-The normal hierarchy dump
-can take several seconds; account for this rather than treating it as a fast
-poll. Compressed dumps can omit nodes and should not be assumed faster.
-
-## Keep interaction fast
-
-Treat each MCP call as a round trip and use the fastest path that still proves
-the behaviour. For an interaction, prefer this sequence:
-
-1. Observe the current screen or wait for a uniquely identifiable target if its presence is uncertain.
-2. Perform the requested action using a stable selector or element id when available.
-3. Check the specific resulting state once it has had time to occur.
-
-Do not wait before every action when its target and current state are already
-known. Do not poll unchanged screens. Set bounded assertion timeouts that cover
-the expected app transition plus a complete fresh observation and a margin.
-For Android ADB tree reads taking 2–3 seconds, start with a 5-second timeout for
-a simple assertion; allow more when loading or repeated observations are
-required. A 2-second timeout cannot reliably accommodate a 3-second tree read.
-Adjust to measured device latency and supported tool limits. Report an
-observation timeout separately from evidence that a control is absent.
-
-Use compact responses for routine actions. If action dispatch is reliable but
-verification is slow or unavailable, dispatch with verification disabled and
-verify at meaningful checkpoints with one focused accessibility assertion or
-screenshot. Do not assume `light` verification is faster: use it only when it
-has returned useful results reliably on the current MCP version and device.
-
-Prefer a stable element selector when it is already known and valid. For a
-clearly identifiable visual target, use coordinates from a fresh screenshot
-without requiring a tree read solely to rediscover it. If the target is
-ambiguous or a semantic check is required, resolve it from the hierarchy.
-Reacquire coordinates after scrolling,
-changing orientation, switching screens, or opening a system surface.
-
-Element discovery can be the slowest part of a journey. Avoid repeated
-`find_element` calls for the same screen: resolve a control once, use the
-returned selector or coordinates while that screen is unchanged, and verify
-the resulting state before continuing. If a query fails, inspect the current
-screen once before retrying; controls represented only by icons may not have a
-matching visible text label.
-
-When the MCP offers a journey or batch action, use it only when its steps can
-express the needed observable checks and it returns enough evidence to report
-the outcome. Measure the whole journey and compare equivalent steps on the same
-device; do not infer a performance improvement from a single fast action.
-
-## Match the evidence to the claim
-
-For a state change, check the state after the action rather than inferring it
-from successful dispatch. For an asynchronous update, start a fresh observation
-after the relevant event and wait for the expected condition within a bounded
-timeout. If an accessibility tree appears stale or incomplete, use another
-appropriate observation such as a screenshot and report the discrepancy.
-
-For behaviour outside the app's foreground screen, inspect the relevant system
-surface or device state. For content that cannot be established visually, such
-as audio output, use a suitable direct check or state that it was not verified.
-
-## Report evidence precisely
-
-State the device, actions taken, observed result, evidence source, and any
-untested scope. Distinguish an observed outcome from an inference. Do not say
-a feature works solely because the build compiled or an MCP action returned
-success.