mobile-debug-mcp 0.32.4 → 0.33.0

package/test/unit/observe/conditional_snapshots.test.ts

@@ -0,0 +1,33 @@
+import assert from 'node:assert/strict'
+import { deriveSnapshotMetadata, hasSnapshotBaseline, resetSnapshotMetadataForTests } from '../../../src/observe/snapshot-metadata.js'
+
+const originalNow = Date.now
+try {
+  resetSnapshotMetadataForTests()
+  let now = originalNow()
+  Date.now = () => now
+  const body = { screen: '', resolution: { width: 100, height: 200 }, elements: Array.from({ length: 501 }, (_, index) => ({ text: `Item ${index}`, stable_id: `item-${index}`, visible: true, bounds: [0, index, 20, index + 1] })) }
+  const first = deriveSnapshotMetadata('android:fixture', body, 'ui_tree')
+  assert.equal(hasSnapshotBaseline('android:other', first.snapshot_revision), false)
+  assert.equal(hasSnapshotBaseline('android:fixture', first.snapshot_revision), true)
+  now += 9 * 60 * 1000
+  const repeat = deriveSnapshotMetadata('android:fixture', body, 'ui_tree')
+  assert.equal(repeat.snapshot_revision, first.snapshot_revision)
+  now += 2 * 60 * 1000
+  assert.equal(hasSnapshotBaseline('android:fixture', repeat.snapshot_revision), true, 'successful re-observation refreshes retention')
+  const changed = structuredClone(body)
+  changed.elements[500].text = 'Changed beyond delta history limit'
+  const second = deriveSnapshotMetadata('android:fixture', changed, 'ui_tree')
+  assert.notEqual(second.snapshot_revision, first.snapshot_revision, 'every element contributes to conditional revision')
+  assert.equal(second.snapshot_session_id, first.snapshot_session_id)
+  now += 11 * 60 * 1000
+  assert.equal(hasSnapshotBaseline('android:fixture', second.snapshot_revision), false)
+  const fresh = deriveSnapshotMetadata('android:fixture', changed, 'ui_tree')
+  assert.equal(hasSnapshotBaseline('android:fixture', fresh.snapshot_revision), true)
+  const failed = deriveSnapshotMetadata('android:empty', null, 'ui_tree')
+  assert.equal(hasSnapshotBaseline('android:empty', failed.snapshot_revision), false, 'error metadata never creates a baseline')
+  console.log('Conditional snapshot retention/session coverage: PASS')
+} finally {
+  Date.now = originalNow
+  resetSnapshotMetadataForTests()
+}

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

@@ -0,0 +1,128 @@
+import assert from 'node:assert/strict'
+import { withEvidence, captureEvidence, evidenceDispatch, currentEvidenceActionId, markEvidenceVerification, omitEvidence, validateActionRef, type EvidenceDevice } from '../../../src/observe/evidence.js'
+
+async function run() {
+  const android = { platform: 'android' as const, id: 'evidence-unit-android' }
+  const ios = { platform: 'ios' as const, id: 'evidence-unit-ios' }
+  const originalWall = Date.now
+  const originalMono = Object.getOwnPropertyDescriptor(performance, 'now')
+  let wall = 1000000
+  let mono = 0
+  Date.now = () => wall
+  Object.defineProperty(performance, 'now', { configurable: true, value: () => mono })
+  const tick = (n = 10) => { wall += n; mono += n }
+  const observe = (device: EvidenceDevice = android) => captureEvidence('ui_tree', device, async () => {
+    tick()
+    return { device, captured_at_ms: wall, snapshot_session_id: 'tree-session', snapshot_revision: 1 }
+  })
+  const act = async (device: EvidenceDevice = android) => withEvidence({ action: true }, async () => {
+    const id = currentEvidenceActionId()
+    await evidenceDispatch(device, async () => { tick() })
+    return id
+  })
+  try {
+    const a = await withEvidence({ action: true }, async () => {
+      await observe()
+      tick()
+      const id = currentEvidenceActionId()
+      await evidenceDispatch(android, async () => { tick() })
+      await observe()
+      markEvidenceVerification()
+      return id
+    })
+    assert.equal(a.evidence.action_id, a.result)
+    assert.equal(a.evidence.correlation_id, a.result)
+    assert.deepEqual(a.evidence.observations.map(v => v.freshness), ['stale', 'fresh'])
+    assert.deepEqual(a.evidence.observations[0].freshness_reasons, ['BEFORE_ACTION'])
+    assert.ok(a.evidence.dispatch_started_at_ms! < a.evidence.dispatch_completed_at_ms!)
+    assert.ok(a.evidence.verification_completed_at_ms! >= a.evidence.dispatch_completed_at_ms!)
+    assert.deepEqual(a.evidence.trace_context, { supported: false, trace_id: null, markers: [] })
+    const ref = { sessionId: a.evidence.session_id, actionId: a.evidence.action_id! }
+    const linked = await withEvidence({ ref }, () => observe())
+    assert.equal(linked.evidence.association, 'explicit')
+    assert.equal(linked.evidence.correlation_id, a.evidence.correlation_id)
+    assert.equal(linked.evidence.verification_completed_at_ms, a.evidence.verification_completed_at_ms)
+    assert.equal(linked.evidence.observations[0].snapshot_revision, 1)
+    assert.ok(linked.evidence.observations[0].age_ms! >= 0)
+    const mismatch = await withEvidence({ ref }, () => observe(ios))
+    assert.equal(mismatch.evidence.association_reason, 'DEVICE_MISMATCH')
+    assert.equal(mismatch.evidence.action_id, null)
+    assert.notEqual(mismatch.evidence.correlation_id, a.evidence.correlation_id)
+    const foreign = await withEvidence({ ref: { ...ref, sessionId: 'previous-process' } }, () => observe())
+    assert.equal(foreign.evidence.association_reason, 'SESSION_MISMATCH')
+    assert.equal(foreign.evidence.action_id, null)
+
+    const oldSource = wall - 100
+    const reused = await withEvidence({}, () => captureEvidence('ui_tree', ios, async () => ({ device: ios, captured_at_ms: oldSource })))
+    assert.equal(reused.evidence.observations[0].source_captured_at_ms, oldSource)
+    assert.deepEqual(reused.evidence.observations[0].freshness_reasons, ['REUSED_OBSERVATION'])
+    const cachedBeforeAction = await withEvidence({ ref }, () => captureEvidence('ui_tree', android, async () => ({ captured_at_ms: a.evidence.operation_started_at_ms - 10 })))
+    assert.deepEqual(cachedBeforeAction.evidence.observations[0].freshness_reasons, ['BEFORE_ACTION'])
+
+    let release!: () => void
+    let entered!: () => void
+    const ready = new Promise<void>(resolve => { entered = resolve })
+    const gate = new Promise<void>(resolve => { release = resolve })
+    const pending = withEvidence({ action: true }, () => evidenceDispatch(android, async () => { entered(); await gate; tick() }))
+    await ready
+    const overlap = await withEvidence({}, () => observe())
+    assert.deepEqual(overlap.evidence.observations[0].freshness_reasons, ['OVERLAPPING_ACTION'])
+    const separate = await withEvidence({}, () => observe(ios))
+    assert.equal(separate.evidence.observations[0].freshness, 'fresh')
+    release(); await pending
+    const superseded = await withEvidence({}, async () => { await observe(); tick(); await act() })
+    assert.deepEqual(superseded.evidence.observations[0].freshness_reasons, ['SUPERSEDED_BY_ACTION'])
+    const [one, two] = await Promise.all([act(), act(ios)])
+    assert.notEqual(one.evidence.action_id, two.evidence.action_id)
+    assert.equal(one.evidence.device?.platform, 'android')
+    assert.equal(two.evidence.device?.platform, 'ios')
+
+    const logs = await withEvidence({}, () => captureEvidence('logs', android, async () => ({ logs: [{ timestamp: null, message: 'untimed' }, { timestamp: 42 }, { timestamp: '2020-01-01T00:00:00Z' }] })))
+    const log = logs.evidence.observations[0]
+    assert.equal(log.freshness, 'unknown')
+    assert.equal(log.earliest_entry_at_ms, 42)
+    assert.equal(log.event_time_comparable, false)
+    assert.equal(log.age_ms, null)
+    const partial = await withEvidence({}, async () => {
+      omitEvidence('logs'); omitEvidence('screenshot')
+      await captureEvidence('ui_tree', android, async () => { throw new Error('offline') }).catch(() => null)
+    })
+    assert.deepEqual(partial.evidence.observations.map(v => v.status), ['omitted', 'omitted', 'failed'])
+    assert.equal(partial.evidence.observations[0].freshness, 'not_applicable')
+    assert.equal(partial.evidence.observations[2].error, 'offline')
+    const unknown = await withEvidence({}, () => captureEvidence('screenshot', null, async () => ({})))
+    assert.equal(unknown.evidence.observations[0].freshness, 'unknown')
+    const reversal = await withEvidence({}, async () => {
+      await observe(); wall -= 1000; mono += 10
+    })
+    assert.deepEqual(reversal.evidence.observations[0].freshness_reasons, ['CLOCK_DISCONTINUITY'])
+    assert.equal(reversal.evidence.observations[0].age_ms, null)
+
+    tick(600001)
+    const expired = await withEvidence({ ref }, () => observe())
+    assert.equal(expired.evidence.association_reason, 'ACTION_UNAVAILABLE')
+    const first = await act()
+    for (let i = 0; i < 1000; i++) await act()
+    const evicted = await withEvidence({ ref: { sessionId: first.evidence.session_id, actionId: first.evidence.action_id! } }, () => observe())
+    assert.equal(evicted.evidence.association_reason, 'ACTION_UNAVAILABLE')
+    const noDispatch = await withEvidence({ action: true }, async () => undefined)
+    assert.equal(noDispatch.evidence.dispatch_started_at_ms, null)
+    assert.equal(noDispatch.evidence.verification_completed_at_ms, null)
+    const multi = await withEvidence({ action: true }, async () => {
+      await evidenceDispatch(android, async () => tick())
+      tick()
+      await evidenceDispatch(android, async () => tick())
+    })
+    assert.equal(multi.evidence.dispatch_completed_at_ms! - multi.evidence.dispatch_started_at_ms!, 30)
+    for (const invalid of [null, [], {}, { sessionId: 'a', actionId: '' }, { sessionId: 'a', actionId: 'x'.repeat(129) }, { ...ref, extra: true }]) {
+      assert.throws(() => validateActionRef(invalid), /INVALID_ARGUMENT/)
+    }
+    assert.deepEqual(validateActionRef(ref), ref)
+  } finally {
+    Date.now = originalWall
+    if (originalMono) Object.defineProperty(performance, 'now', originalMono)
+    else delete (performance as any).now
+  }
+  console.log('Correlated evidence clocks, freshness, references, isolation and bounds: PASS')
+}
+run().catch(error => { console.error(error); process.exit(1) })

package/test/unit/observe/ios_tree_acquisition.test.ts

@@ -43,6 +43,8 @@ console.log(JSON.stringify({ devices: { 'com.apple.CoreSimulator.SimRuntime.iOS-
     const first = await observe.getUITree('fake-a')
     const second = await observe.getUITree('fake-b')
     assert.equal(first.error, undefined)
+    assert.equal(typeof first.snapshot_session_id, 'string')
+    assert.equal(first.snapshot_session_id, second.snapshot_session_id)
     assert.equal(second.error, undefined)
     assert.equal(first.elements[0].text, 'Ready')
     assert.equal(second.snapshot_delta, null, 'different simulators keep independent delta history')

package/test/unit/observe/readiness.test.ts

@@ -0,0 +1,39 @@
+import assert from 'node:assert/strict'
+import { ReadinessTracker } from '../../../src/observe/readiness.js'
+import { getSnapshotSessionId } from '../../../src/observe/snapshot-metadata.js'
+
+const device = { platform: 'android', id: 'fixture' }
+const sample = (label = 'Ready', extra: any = {}) => ({ device, snapshot_session_id: getSnapshotSessionId(), snapshot_revision: 1,
+  captured_at_ms: 10000, screen: '', resolution: { width: 100, height: 200 },
+  elements: [{ type: 'Button', text: label, visible: true, enabled: true, bounds: [0, 0, 50, 50] }], ...extra })
+const tracker = new ReadinessTracker('android', 'fixture')
+assert.equal(tracker.observe(sample(), 10000, 0).state, 'unknown')
+assert.equal(tracker.observe(sample(), 10000, 499).state, 'unknown')
+assert.equal(tracker.observe(sample(), 10000, 500).state, 'settled')
+assert.equal(tracker.observe(sample('Changed'), 10000, 1000).state, 'transitioning')
+assert.equal(tracker.observe(sample('Changed'), 10000, 1500).state, 'settled')
+for (const label of [' Loading… ', 'Please wait...', 'please   wait']) {
+  const state = tracker.observe(sample(label), 10000, 2000)
+  assert.equal(state.state, 'loading')
+  assert.equal(state.basis, 'heuristic')
+  assert.equal(tracker.observe(sample(label), 10000, 3000).state, 'loading', 'identical loaders never settle')
+}
+for (const type of ['android.widget.ProgressBar', 'ActivityIndicator', 'ProgressIndicator']) {
+  const tree = sample('Progress', { elements: [{ type, visible: true }] })
+  assert.equal(tracker.observe(tree, 10000, 4000).state, 'loading')
+  assert.equal(tracker.summary.basis, 'observed')
+}
+assert.notEqual(tracker.observe(sample('Progress'), 10000, 5000).state, 'loading', 'legacy broad keywords are not loaders')
+for (const extra of [{ error: 'offline' }, { elements: [] }, { captured_at_ms: 9999 }, { snapshot_session_id: 'old' }, { device: { ...device, id: 'other' } }, { resolution: { width: Infinity, height: 2 } }]) {
+  assert.equal(tracker.observe(sample('Ready', extra), 10000, 6000).state, 'unknown')
+  assert.equal(tracker.observe(sample(), 10000, 7000).state, 'unknown', 'failure breaks continuity')
+  assert.equal(tracker.observe(sample(), 10000, 7500).state, 'settled')
+}
+for (let index = 0; index < 20; index++) tracker.observe(sample(), 10000, 8000 + index)
+assert.equal(tracker.summary.evidence.length, 8)
+assert.equal(tracker.summary.capabilities.unresponsive, false)
+assert.equal(tracker.summary.capabilities.debugger_paused, false)
+assert.ok(tracker.deadline().limitations.includes('DEADLINE_EXCEEDED'))
+assert.equal(new ReadinessTracker('android', 'fixture').observe(sample(), 10000, 9000).state, 'unknown', 'no cross-request history')
+assert.ok(!JSON.stringify(tracker.summary).includes('Ready'), 'evidence contains codes rather than private labels')
+console.log('Readiness classifier: PASS')

package/test/unit/observe/readiness_native.test.ts

@@ -0,0 +1,68 @@
+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 } from '../../../src/server-core.js'
+import { _setDeviceListersForTests, _resetDeviceListersForTests } from '../../../src/utils/resolve-device.js'
+
+async function run() {
+  const directory = mkdtempSync(path.join(tmpdir(), 'mcp-ready-native-'))
+  const binary = path.join(directory, 'native')
+  const marker = path.join(directory, 'closed')
+  const keys = ['ADB_PATH', 'IDB_PATH', 'MCP_IDB_PATH', 'XCRUN_PATH', 'READY_SLOW', 'READY_LOADER', 'READY_SLOW_META']
+  const previous = Object.fromEntries(keys.map(key => [key, process.env[key]]))
+  writeFileSync(binary, `#!/usr/bin/env node
+const fs = require('fs'); const a = process.argv.slice(2).join(' ')
+function slow() { process.on('SIGTERM', () => setTimeout(() => { fs.writeFileSync(${JSON.stringify(marker)}, 'closed'); process.exit(0) }, 40)); setInterval(() => {}, 1000) }
+if (a.includes('ro.build.version.release')) console.log('16')
+else if (a.includes('ro.product.model')) console.log('Fixture')
+else if (a.includes('ro.kernel.qemu')) console.log('1')
+else if (a.includes('wm size')) console.log('Physical size: 100x200')
+else if (a.includes('uiautomator dump')) { if (process.env.READY_SLOW) slow(); else console.log('dumped') }
+else if (a.includes('cat /sdcard/ui.xml')) console.log('<hierarchy><node class="' + (process.env.READY_LOADER ? 'android.widget.ProgressBar' : 'android.widget.Button') + '" text="Ready" visible-to-user="true" enabled="true" bounds="[0,0][100,200]" /></hierarchy>')
+else if (a.includes('simctl list devices')) { if (process.env.READY_SLOW_META) { fs.writeFileSync(${JSON.stringify(marker)}, String(process.pid)); setInterval(() => {}, 1000) } else console.log(JSON.stringify({ devices: { 'iOS-18': [{ udid: 'fixture', name: 'Fixture', state: 'Booted' }] } })) }
+else if (a.includes('list-targets')) console.log('[]')
+else if (a.includes('ui describe-all')) { if (process.env.READY_SLOW) slow(); else console.log(JSON.stringify({ AXElementType: process.env.READY_LOADER ? 'ActivityIndicator' : 'Button', AXLabel: 'Ready', AXFrame: { x: 0, y: 0, width: 100, height: 200 } })) }
+else process.exit(1)
+`)
+  chmodSync(binary, 0o755)
+  for (const key of ['ADB_PATH', 'IDB_PATH', 'MCP_IDB_PATH', 'XCRUN_PATH']) process.env[key] = binary
+  const device = (platform: string) => ({ platform, id: 'fixture', model: 'Fixture', simulator: true, osVersion: '16' })
+  _setDeviceListersForTests({ listAndroidDevices: async () => [device('android')], listIOSDevices: async () => [device('ios')] })
+  const call = async (platform: string, args: any) => JSON.parse((await handleToolCall('get_app_readiness', { platform, deviceId: 'fixture', ...args })).content[0].text!)
+  try {
+    for (const platform of ['android', 'ios']) {
+      const stable = await call(platform, { stabilityMs: 100 })
+      assert.equal(stable.readiness.state, 'settled', JSON.stringify(stable))
+      assert.equal(stable.readiness.sample_count, 2)
+      process.env.READY_LOADER = '1'
+      const loader = await call(platform, {})
+      assert.equal(loader.readiness.state, 'loading')
+      assert.equal(loader.readiness.basis, 'observed')
+      delete process.env.READY_LOADER
+      process.env.READY_SLOW = '1'
+      writeFileSync(marker, '')
+      const timed = await call(platform, { timeoutMs: 1500 })
+      assert.equal(timed.success, false)
+      assert.equal(timed.readiness.state, 'unknown')
+      assert.ok(timed.readiness.limitations.includes('DEADLINE_EXCEEDED'))
+      assert.equal(readFileSync(marker, 'utf8'), 'closed', 'timed-out native acquisition closes its child before responding')
+      delete process.env.READY_SLOW
+    }
+    process.env.READY_SLOW_META = '1'
+    writeFileSync(marker, '')
+    const metadataTimeout = await call('ios', { timeoutMs: 300 })
+    assert.equal(metadataTimeout.success, false)
+    assert.ok(metadataTimeout.readiness.limitations.includes('DEADLINE_EXCEEDED'))
+    const pid = Number(readFileSync(marker, 'utf8'))
+    assert.ok(pid > 0)
+    assert.throws(() => process.kill(pid, 0), (error: any) => error.code === 'ESRCH', 'metadata child must be closed after its deadline')
+    delete process.env.READY_SLOW_META
+    console.log('Readiness native Android/iOS acquisition and timeout cleanup: PASS')
+  } finally {
+    _resetDeviceListersForTests()
+    for (const key of keys) { if (previous[key] === undefined) delete process.env[key]; else process.env[key] = previous[key] }
+    rmSync(directory, { recursive: true, force: true })
+  }
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

package/test/unit/server/conditional_actions.test.ts

@@ -0,0 +1,299 @@
+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 { ToolsObserve } from '../../../src/observe/index.js'
+import { ToolsNetwork } from '../../../src/network/index.js'
+import { deriveSnapshotMetadata, getSnapshotSessionId, resetSnapshotMetadataForTests } from '../../../src/observe/snapshot-metadata.js'
+import { _setDeviceListersForTests, _resetDeviceListersForTests } from '../../../src/utils/resolve-device.js'
+import { runWithBudget } from '../../../src/utils/operation-budget.js'
+
+async function run() {
+  const directory = mkdtempSync(path.join(tmpdir(), 'mcp-conditional-'))
+  const eventsPath = path.join(directory, 'events')
+  const native = path.join(directory, 'native')
+  const changedPath = path.join(directory, 'prepared')
+  const envKeys = ['ADB_PATH', 'IDB_PATH', 'MCP_IDB_PATH', 'XCRUN_PATH', 'MCP_CONDITION_PREPARE', 'MCP_CONDITION_INPUT_FAIL', 'MCP_CONDITION_TREE_TEXT', 'MCP_CONDITION_SLOW']
+  const originalEnv = Object.fromEntries(envKeys.map(key => [key, process.env[key]]))
+  writeFileSync(eventsPath, '')
+  writeFileSync(native, `#!/usr/bin/env node
+const fs = require('fs')
+const args = process.argv.slice(2).join(' ')
+function slow() {
+  process.on('SIGTERM', () => setTimeout(() => { fs.writeFileSync(${JSON.stringify(changedPath)}, 'closed'); process.exit(0) }, 40))
+  setInterval(() => {}, 1000)
+}
+fs.appendFileSync(${JSON.stringify(eventsPath)}, args + '\\n')
+if (args.includes('ro.build.version.release')) console.log('16')
+else if (args.includes('ro.product.model')) { if (process.env.MCP_CONDITION_PREPARE) fs.writeFileSync(${JSON.stringify(changedPath)}, 'changed'); 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', name: 'Fixture', state: 'Booted' }] } }))
+else if (args.includes('list-targets')) { if (process.env.MCP_CONDITION_PREPARE) fs.writeFileSync(${JSON.stringify(changedPath)}, 'changed'); console.log('[]') }
+else if (args.includes('wm size')) console.log('Physical size: 100x200')
+else if (args.includes('uiautomator dump')) { if (process.env.MCP_CONDITION_SLOW) slow(); else console.log('dumped') }
+else if (args.includes('cat /sdcard/ui.xml')) console.log('<hierarchy><node class="android.widget.Button" resource-id="target" text="' + (process.env.MCP_CONDITION_TREE_TEXT || 'Ready') + '" clickable="true" enabled="true" visible-to-user="true" bounds="[0,0][50,50]" /></hierarchy>')
+else if (args.includes('ui describe-all')) { if (process.env.MCP_CONDITION_SLOW) slow(); else console.log(JSON.stringify({ AXElementType: 'Button', AXLabel: process.env.MCP_CONDITION_TREE_TEXT || 'Ready', AXUniqueId: 'target', AXFrame: { x: 0, y: 0, width: 100, height: 200 } })) }
+else if (args.includes('shell input') || args.includes('ui tap') || args.includes('ui swipe')) { if (process.env.MCP_CONDITION_INPUT_FAIL) process.exit(1) }
+else process.exit(1)
+`)
+  chmodSync(native, 0o755)
+  for (const key of ['ADB_PATH', 'IDB_PATH', 'MCP_IDB_PATH', 'XCRUN_PATH']) process.env[key] = native
+  const originalTree = ToolsObserve.getUITreeHandler
+  const originalFingerprint = ToolsObserve.getScreenFingerprintHandler
+  const originalNotify = ToolsNetwork.notifyActionStart
+  let networkStarts = 0
+  let reads = 0
+  let observationMode = 'normal'
+  let readDelay = 0
+  let uiState = 'Ready'
+  let propertyChange: Record<string, unknown> = {}
+  let platform: 'android' | 'ios' = 'android'
+  const device = () => ({ platform, id: 'fixture', osVersion: '16', model: 'Fixture', simulator: true })
+  const tree = () => {
+    const elements = [{ text: uiState, contentDescription: 'target', type: 'Button', stable_id: 'target', resourceId: 'target', bounds: [0, 0, 50, 50], enabled: true, visible: true, clickable: true, state: { checked: false }, ...propertyChange }]
+    const body = { device: device(), screen: '', resolution: { width: 100, height: 200 }, elements }
+    return { ...body, ...deriveSnapshotMetadata(`${platform}:fixture`, body, 'ui_tree') }
+  }
+  ToolsObserve.getUITreeHandler = async () => {
+    reads++
+    if (readDelay) await new Promise(resolve => setTimeout(resolve, readDelay))
+    if (process.env.MCP_CONDITION_PREPARE && readFileSync(changedPath, 'utf8') === 'changed') uiState = 'Changed during preparation'
+    if (observationMode === 'throw') throw new Error('offline')
+    const fresh = tree()
+    if (observationMode === 'error') return { ...fresh, error: 'offline' } as any
+    if (observationMode === 'invalid') return { ...fresh, snapshot_session_id: undefined } as any
+    if (observationMode === 'device') return { ...fresh, device: { ...device(), id: 'other' } } as any
+    return fresh
+  }
+  ToolsObserve.getScreenFingerprintHandler = async () => ({ fingerprint: 'unchanged-screen' }) as any
+  ToolsNetwork.notifyActionStart = () => { networkStarts++ }
+  _setDeviceListersForTests({ listAndroidDevices: async () => [device()], listIOSDevices: async () => [device()] })
+  const payload = (response: any) => JSON.parse(response.content[0].text)
+  const nativeInputs = () => readFileSync(eventsPath, 'utf8').split('\n').filter(line => /shell input|ui tap|ui swipe/.test(line))
+  const baseline = () => {
+    uiState = 'Ready'; propertyChange = {}; observationMode = 'normal'; readDelay = 0
+    const value = tree()
+    return { snapshotSessionId: value.snapshot_session_id, snapshotRevision: value.snapshot_revision }
+  }
+  const argsFor = (tool: string) => ({
+    platform, deviceId: 'fixture', verificationMode: 'none', responseMode: 'compact',
+    ...({ tap: { x: 10, y: 10 }, tap_element: { selector: { accessibility_id: 'target' } }, swipe: { x1: 10, y1: 10, x2: 20, y2: 20, duration: 100 }, type_text: { text: 'hello' }, press_back: {} }[tool])
+  })
+  const call = async (tool: string, extra: Record<string, unknown> = {}) => payload(await handleToolCall(tool, { ...argsFor(tool), ...extra }))
+  try {
+    resetSnapshotMetadataForTests()
+    // Exercise production dispatch adapters, not mocked ToolsInteract input handlers.
+    for (platform of ['android', 'ios'] as const) {
+      const tools = platform === 'android' ? ['tap', 'tap_element', 'swipe', 'type_text', 'press_back'] : ['tap', 'tap_element', 'swipe']
+      for (const tool of tools) {
+        const expectedState = baseline()
+        const inputs = nativeInputs().length
+        const starts = networkStarts
+        const result = await call(tool, { expectedState })
+        assert.equal(result.success, true, JSON.stringify(result))
+        assert.equal(result.condition.status, 'matched')
+        assert.equal(result.condition.observed.elements, undefined, 'compact matching conditions omit tree')
+        assert.equal(result.condition.observed.snapshot_revision, expectedState.snapshotRevision)
+        assert.equal(nativeInputs().length, inputs + 1, `${platform} ${tool} dispatches once`)
+        assert.equal(networkStarts, starts + 1)
+      }
+      // Change happens after ordinary resolution and metadata/capability preparation.
+      for (const tool of ['tap', 'tap_element', 'swipe']) {
+        const expectedState = baseline()
+        writeFileSync(changedPath, '')
+        process.env.MCP_CONDITION_PREPARE = '1'
+        const inputs = nativeInputs().length
+        const starts = networkStarts
+        const result = await call(tool, { expectedState, responseMode: 'debug' })
+        delete process.env.MCP_CONDITION_PREPARE
+        assert.equal(result.failure_code, 'PRECONDITION_FAILED', JSON.stringify(result))
+        assert.equal(result.dispatch_started, false)
+        assert.equal(result.condition.observed.elements[0].text, 'Changed during preparation')
+        assert.equal(nativeInputs().length, inputs)
+        assert.equal(networkStarts, starts)
+        assert.ok(!result.trace.steps.some((step: any) => step.stage === 'execute'))
+      }
+    }
+    platform = 'android'
+    for (const verificationMode of ['none', 'light', 'full']) for (const responseMode of ['compact', 'debug']) {
+      for (const changed of [{ text: 'Changed' }, { bounds: [1, 1, 51, 51] }, { enabled: false }, { state: { checked: true } }]) {
+        const expectedState = baseline()
+        propertyChange = changed
+        const inputs = nativeInputs().length
+        const starts = networkStarts
+        reads = 0
+        const result = await call('tap', { expectedState, verificationMode, responseMode })
+        assert.equal(result.failure_code, 'PRECONDITION_FAILED')
+        assert.equal(result.condition.status, 'mismatch')
+        assert.equal(result.retryable, false)
+        assert.equal(result.delivery_status, 'not_delivered')
+        assert.equal(result.verification.status, 'not_requested')
+        assert.deepEqual(result.condition.observed.elements[0], tree().elements[0])
+        assert.equal(reads, 1, 'no post-dispatch tree read after guard failure')
+        assert.equal(nativeInputs().length, inputs)
+        assert.equal(networkStarts, starts)
+      }
+      const expectedState = baseline()
+      const matched = await call('tap', { expectedState, verificationMode, responseMode })
+      assert.equal(matched.success, true)
+      assert.equal(matched.condition.status, 'matched')
+      assert.equal(Array.isArray(matched.condition.observed.elements), responseMode === 'debug')
+    }
+    for (const [mode, reason] of [['error', 'OBSERVATION_FAILED'], ['throw', 'OBSERVATION_FAILED'], ['invalid', 'OBSERVATION_INVALID'], ['device', 'DEVICE_MISMATCH']]) {
+      const expectedState = baseline()
+      observationMode = mode
+      const inputs = nativeInputs().length
+      const result = await call('tap', { expectedState })
+      assert.equal(result.failure_code, 'PRECONDITION_UNAVAILABLE')
+      assert.equal(result.condition.reason, reason)
+      assert.equal(result.condition.observed, null)
+      assert.equal(nativeInputs().length, inputs)
+    }
+    for (const expectation of [
+      { ...baseline(), snapshotSessionId: 'previous-process' },
+      { ...baseline(), snapshotRevision: 999999 }
+    ]) {
+      reads = 0
+      const result = await call('tap', { expectedState: expectation })
+      assert.equal(result.failure_code, 'PRECONDITION_UNAVAILABLE')
+      assert.equal(reads, 0, 'unknown expectations cannot authorize a read/input')
+    }
+    const foreign = baseline()
+    platform = 'ios'
+    const foreignResult = await call('tap', { expectedState: foreign })
+    assert.equal(foreignResult.condition.reason, 'BASELINE_UNAVAILABLE')
+    platform = 'android'
+    const expired = baseline()
+    const originalNow = Date.now
+    try {
+      Date.now = () => originalNow() + 11 * 60 * 1000
+      const result = await call('tap', { expectedState: expired })
+      assert.equal(result.condition.reason, 'BASELINE_UNAVAILABLE')
+    } finally { Date.now = originalNow }
+    const evicted = baseline()
+    for (let index = 0; index < 9; index++) { uiState = `screen-${index}`; tree() }
+    assert.equal((await call('tap', { expectedState: evicted })).condition.reason, 'BASELINE_UNAVAILABLE')
+
+    const timed = baseline()
+    readDelay = 180
+    const inputs = nativeInputs().length
+    const timedResult = await call('tap', { expectedState: { ...timed, timeoutMs: 100 } })
+    assert.equal(timedResult.condition.reason, 'CONDITION_TIMEOUT')
+    assert.equal(timedResult.dispatch_started, false)
+    assert.equal(nativeInputs().length, inputs, 'late observation never dispatches')
+    const budgeted = baseline()
+    readDelay = 180
+    const separate = await call('tap', { expectedState: budgeted, actionTimeoutMs: 150 })
+    assert.equal(separate.success, true, 'condition read does not consume the action budget')
+    const outerExpected = baseline()
+    readDelay = 180
+    const outerInputs = nativeInputs().length
+    const outer = await runWithBudget(150, () => call('tap', { expectedState: outerExpected, actionTimeoutMs: 5000 }))
+    assert.equal(outer.success, false)
+    assert.equal(nativeInputs().length, outerInputs, 'outer budget still prevents dispatch')
+
+    // A matched condition cannot turn a native dispatch failure into success.
+    const nativeFailure = baseline()
+    process.env.MCP_CONDITION_INPUT_FAIL = '1'
+    const failedInput = await call('tap', { expectedState: nativeFailure })
+    delete process.env.MCP_CONDITION_INPUT_FAIL
+    assert.equal(failedInput.success, false)
+    assert.equal(failedInput.condition.status, 'matched')
+    assert.equal(failedInput.dispatch_started, true)
+    assert.equal(failedInput.delivery_status, 'unknown')
+
+    const targetFailure = baseline()
+    const notChecked = await call('tap_element', { expectedState: targetFailure, selector: undefined, elementId: 'missing' })
+    assert.equal(notChecked.condition.status, 'not_checked')
+    assert.equal(notChecked.condition.reason, 'ACTION_NOT_REACHED')
+
+    const valid = baseline()
+    const badConditions: unknown[] = [null, {}, { ...valid, extra: true }, { ...valid, snapshotRevision: 0 }, { ...valid, snapshotRevision: Number.MAX_SAFE_INTEGER + 1 }, { ...valid, timeoutMs: 99 }, { ...valid, timeoutMs: '100' }, { ...valid, snapshotSessionId: '' }]
+    for (const expectedState of badConditions) {
+      const count = readFileSync(eventsPath, 'utf8').length
+      const result = await call('tap', { expectedState })
+      assert.match(result.error.message, /INVALID_ARGUMENT/)
+      assert.equal(readFileSync(eventsPath, 'utf8').length, count)
+    }
+    for (const extra of [{ platform: undefined }, { deviceId: 'booted' }, { deviceId: 'default' }, { deviceId: ' ' }, { platform: ['android'] }]) {
+      const result = await call('tap', { ...extra, expectedState: valid })
+      assert.match(result.error.message, /INVALID_ARGUMENT/)
+    }
+    for (const name of ['start_app', 'restart_app', 'terminate_app', 'reset_app_data', 'scroll_to_element', 'adjust_control', 'get_ui_tree']) {
+      const result = payload(await handleToolCall(name, { platform, deviceId: 'fixture', expectedState: valid }))
+      assert.match(result.error.message, /INVALID_ARGUMENT/)
+    }
+    for (const tool of toolDefinitions) {
+      assert.equal(!!tool.inputSchema.properties.expectedState, ['tap', 'tap_element', 'swipe', 'type_text', 'press_back'].includes(tool.name))
+    }
+    for (const responseMode of ['compact', 'debug']) {
+      const expectedState = baseline()
+      uiState = 'Changed'
+      const before = nativeInputs().length
+      const journey = payload(await handleToolCall('run_journey', { platform, deviceId: 'fixture', responseMode, defaults: { verificationMode: 'light' }, steps: [
+        { id: 'ready', type: 'wait', selector: { accessibility_id: 'target' }, timeoutMs: 500 },
+        { id: 'guarded', type: 'tap', selector: { accessibility_id: 'target' }, expectedState },
+        { id: 'later', type: 'assert', assertion: { kind: 'element_visible', selector: { accessibility_id: 'target' } } }
+      ] }))
+      assert.equal(journey.stopped_at_step_id, 'guarded')
+      assert.equal(journey.steps[0].status, 'passed')
+      assert.equal(journey.steps[1].result.failure_code, 'PRECONDITION_FAILED')
+      assert.equal(journey.steps[1].result.condition.observed.elements[0].text, 'Changed')
+      assert.equal(journey.steps[1].result.verification.status, 'not_requested')
+      assert.equal(journey.steps[2].status, 'not_run')
+      assert.equal(nativeInputs().length, before)
+    }
+    // Calls overlap, but only the request with its own expectation is rejected.
+    const overlapping = baseline()
+    uiState = 'Changed'
+    const before = nativeInputs().length
+    const [guarded, unguarded] = await Promise.all([call('tap', { expectedState: overlapping }), call('tap')])
+    assert.equal(guarded.failure_code, 'PRECONDITION_FAILED')
+    assert.equal(unguarded.success, true)
+    assert.equal(unguarded.condition, undefined)
+    assert.equal(nativeInputs().length, before + 1)
+    assert.equal(getSnapshotSessionId(), valid.snapshotSessionId)
+    // Complete native observation + input paths with fake platform tools, including
+    // subprocess timeout cleanup. No mocked tree or adapter is used in these checks.
+    ToolsObserve.getUITreeHandler = originalTree
+    for (platform of ['android', 'ios'] as const) {
+      delete process.env.MCP_CONDITION_TREE_TEXT
+      const observed: any = await ToolsObserve.getUITreeHandler({ platform, deviceId: 'fixture' })
+      assert.equal(observed.error, undefined)
+      const expectedState = { snapshotSessionId: observed.snapshot_session_id, snapshotRevision: observed.snapshot_revision }
+      const matched = await call('tap', { expectedState })
+      assert.equal(matched.success, true, JSON.stringify(matched))
+      process.env.MCP_CONDITION_TREE_TEXT = 'Changed through native hierarchy'
+      const before = nativeInputs().length
+      const mismatch = await call('tap', { expectedState })
+      assert.equal(mismatch.failure_code, 'PRECONDITION_FAILED', JSON.stringify(mismatch))
+      assert.equal(mismatch.condition.observed.elements[0].text, 'Changed through native hierarchy')
+      assert.equal(nativeInputs().length, before)
+      const compact: any = await ToolsObserve.getUITreeHandler({ platform, deviceId: 'fixture', responseMode: 'compact' })
+      assert.equal(compact.snapshot_session_id, expectedState.snapshotSessionId)
+      const current: any = await ToolsObserve.getUITreeHandler({ platform, deviceId: 'fixture' })
+      process.env.MCP_CONDITION_SLOW = '1'
+      writeFileSync(changedPath, '')
+      const unavailable = await call('tap', { expectedState: { snapshotSessionId: current.snapshot_session_id, snapshotRevision: current.snapshot_revision, timeoutMs: 1200 } })
+      delete process.env.MCP_CONDITION_SLOW
+      assert.equal(unavailable.condition.reason, 'CONDITION_TIMEOUT', JSON.stringify(unavailable))
+      assert.equal(unavailable.dispatch_started, false)
+      assert.equal(readFileSync(changedPath, 'utf8'), 'closed', 'timed-out hierarchy subprocess closed before response')
+      assert.equal(nativeInputs().length, before)
+    }
+    console.log('Conditional actions: PASS (production Android/iOS input adapters with fake native tools)')
+  } finally {
+    ToolsObserve.getUITreeHandler = originalTree
+    ToolsObserve.getScreenFingerprintHandler = originalFingerprint
+    ToolsNetwork.notifyActionStart = originalNotify
+    _resetDeviceListersForTests()
+    resetSnapshotMetadataForTests()
+    for (const key of envKeys) {
+      if (originalEnv[key] === undefined) delete process.env[key]
+      else process.env[key] = originalEnv[key]
+    }
+    rmSync(directory, { recursive: true, force: true })
+  }
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

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')