mobile-debug-mcp 0.32.2 → 0.33.0

package/test/unit/server/conditional_schema.test.ts

@@ -0,0 +1,59 @@
+import assert from 'node:assert/strict'
+import { AjvJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/ajv'
+import { toolDefinitions } from '../../../src/server/tool-definitions.js'
+import { conditionalTools, validateExpectedState } from '../../../src/server/condition-schema.js'
+import { journeySchema } from '../../../src/server/journey-schema.js'
+
+const provider = new AjvJsonSchemaValidator()
+const expectedState = { snapshotSessionId: 'session-fixture', snapshotRevision: 1 }
+for (const name of conditionalTools) {
+  const schema = toolDefinitions.find(tool => tool.name === name)!.inputSchema
+  const validate = provider.getValidator(schema)
+  const args = { platform: 'android', deviceId: 'emulator-5554', expectedState,
+    ...({ tap: { x: 1, y: 1 }, tap_element: { selector: { text: 'Go' } }, swipe: { x1: 1, y1: 1, x2: 2, y2: 2, duration: 100 }, type_text: { text: 'hello' }, press_back: {} }[name]) }
+  assert.equal(validate(args).valid, true, `${name} schema accepts valid guarded input`)
+  assert.deepEqual(validateExpectedState(name, args), expectedState)
+  for (const extra of [
+    { expectedState: null }, { expectedState: {} }, { expectedState: { ...expectedState, extra: true } },
+    { expectedState: { ...expectedState, snapshotRevision: 0 } }, { expectedState: { ...expectedState, snapshotRevision: 1.5 } },
+    { expectedState: { ...expectedState, snapshotRevision: Number.MAX_SAFE_INTEGER + 1 } },
+    { expectedState: { ...expectedState, snapshotSessionId: '' } }, { expectedState: { ...expectedState, timeoutMs: 99 } },
+    { expectedState: { ...expectedState, timeoutMs: 60001 } }, { expectedState: { ...expectedState, timeoutMs: '15000' } },
+    { platform: null }, { deviceId: 'booted' }, { deviceId: 'default' }, { deviceId: '' }, { deviceId: ' ' }
+  ]) {
+    const input = { ...args, ...extra }
+    assert.equal(validate(input).valid, false, JSON.stringify(input))
+    assert.throws(() => validateExpectedState(name, input), /INVALID_ARGUMENT/)
+  }
+  const withoutDevice: any = { ...args }; delete withoutDevice.deviceId
+  assert.equal(validate(withoutDevice).valid, false)
+  assert.throws(() => validateExpectedState(name, withoutDevice), /INVALID_ARGUMENT/)
+  const ios = { ...args, platform: 'ios', deviceId: 'concrete-udid' }
+  const supported = !['type_text', 'press_back'].includes(name)
+  assert.equal(validate(ios).valid, supported)
+  if (supported) assert.deepEqual(validateExpectedState(name, ios), expectedState)
+  else assert.throws(() => validateExpectedState(name, ios), /INVALID_ARGUMENT/)
+}
+for (const name of ['start_app', 'restart_app', 'terminate_app', 'reset_app_data', 'scroll_to_element', 'adjust_control', 'get_ui_tree']) {
+  const schema = toolDefinitions.find(tool => tool.name === name)!.inputSchema
+  const args = { platform: 'android', deviceId: 'emulator-5554', appId: 'example.app', selector: { text: 'Go' }, targetValue: 1, expectedState }
+  assert.equal(provider.getValidator(schema)(args).valid, false)
+  assert.throws(() => validateExpectedState(name, args), /INVALID_ARGUMENT/)
+}
+const validateJourney = provider.getValidator(toolDefinitions.find(tool => tool.name === 'run_journey')!.inputSchema)
+const step = { id: 'tap', type: 'tap', selector: { text: 'Go' }, expectedState }
+const journey = { platform: 'android', steps: [step] }
+assert.equal(validateJourney(journey).valid, true)
+assert.equal(journeySchema.safeParse(journey).success, true)
+for (const input of [
+  { ...journey, expectedState },
+  { ...journey, defaults: { expectedState } },
+  { ...journey, steps: [{ id: 'wait', type: 'wait', selector: { text: 'Go' }, expectedState }] },
+  { ...journey, steps: [{ id: 'launch', type: 'start_app', appId: 'example.app', expectedState }] },
+  { ...journey, steps: [{ id: 'assert', type: 'assert', assertion: { kind: 'element_visible', selector: { text: 'Go' } }, expectedState }] },
+  { ...journey, steps: [{ ...step, expectedState: { ...expectedState, timeoutMs: 0 } }] }
+]) {
+  assert.equal(validateJourney(input).valid, false)
+  assert.equal(journeySchema.safeParse(input).success, false)
+}
+console.log('Conditional JSON schema/runtime parity: PASS')

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,74 +0,0 @@
----
-name: mobile-debug-mcp
-description: Verify Android app behaviour efficiently with mobile-debug MCP, especially session playback, background work, and notifications. Use for emulator/device QA; do not use for implementation-only checks.
-metadata:
-  author: modul8-team
-  version: "1.0"
----
-
-# Mobile-debug MCP verification
-
-Use mobile-debug MCP to make a product claim observable on a real device or emulator. A successful tap proves only that the input was delivered; verify the resulting UI, notification, or persisted state before reporting success.
-
-## Choose the lightest evidence that proves the claim
-
-- Use an accessibility assertion such as `expect_element_visible` or
-  `wait_for_ui` for an accessible label, enabled state, or changed control.
-- Use a screenshot when visual layout, system UI, or notification content matters.
-- Use a debug snapshot only when the screen does not explain a failed action or an accessibility-tree assertion is needed.
-- Use Android shell commands only for device navigation or system surfaces that MCP cannot expose. Do not treat shell output as proof of user-visible behaviour.
-
-Avoid repeated screenshots and snapshots when a targeted accessibility assertion is enough.
-
-## Keep interaction fast
-
-Treat each MCP call as a round trip and use the fastest path that still proves
-the behaviour. Prefer the following sequence:
-
-1. Wait for one stable, uniquely identifiable control.
-2. Tap its returned element id.
-3. Wait for the specific resulting state.
-
-Do not wait before every tap when the current screen and element id are already known. Do not poll unchanged screens. Use short timeouts for ordinary controls; reserve longer waits for known asynchronous work such as model initialisation or network calls.
-
-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 the accessibility tree exposes one. Use
-coordinates only when needed, and take a fresh screenshot immediately before a
-coordinate tap on system UI, notifications, or any screen where layout may have
-changed. Never reuse coordinates after expanding/collapsing a notification,
-changing orientation, or switching screens.
-
-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.
-
-## Session playback checks
-
-For a claimed playback start, observe a running timer or Pause state after Play. For a claimed pause, observe Resume and unchanged elapsed time. For a claimed stop, observe that playback ends and the notification disappears.
-
-For background playback, press Home, open the notification shade, and verify
-the notification title, progress/status, and available actions. Expand the
-session notification if necessary, then capture its current layout before
-tapping an action. Exercise each action needed for the change and observe its
-result: Pause becomes Resume; Resume returns to active playback; Stop ends
-playback and clears the notification. After each action, reacquire the current
-screen state before using another coordinate.
-
-Do not claim spoken guidance was verified unless audio output was actually inspected. A running timer or active notification verifies playback state, not audible wording.
-
-## Report evidence precisely
-
-State the device journey, observed result, and any untested scope. Mention whether evidence came from an accessibility assertion, screenshot, or system notification. Do not say a feature works solely because the build compiled or an MCP action returned success.