mobile-debug-mcp 0.24.0 → 0.24.2

package/src/server/common.ts

@@ -63,26 +63,31 @@ export function inferScrollFailure(message: string | undefined): { failureCode:
 
 export function buildActionExecutionResult({
   actionType,
+  device,
   selector,
   resolved,
   success,
   uiFingerprintBefore,
   uiFingerprintAfter,
-  failure
+  failure,
+  details
 }: {
   actionType: string
+  device?: ActionExecutionResult['device']
   selector: Record<string, unknown> | null
   resolved?: Partial<ActionTargetResolved> | null
   success: boolean
   uiFingerprintBefore: string | null
   uiFingerprintAfter: string | null
   failure?: { failureCode: ActionFailureCode; retryable: boolean }
+  details?: Record<string, unknown>
 }): ActionExecutionResult {
   const timestamp = Date.now()
   return {
     action_id: nextActionId(actionType, timestamp),
     timestamp,
     action_type: actionType,
+    ...(device ? { device } : {}),
     target: {
       selector,
       resolved: normalizeResolvedTarget(resolved)
@@ -90,6 +95,7 @@ export function buildActionExecutionResult({
     success,
     ...(failure ? { failure_code: failure.failureCode, retryable: failure.retryable } : {}),
     ui_fingerprint_before: uiFingerprintBefore,
-    ui_fingerprint_after: uiFingerprintAfter
+    ui_fingerprint_after: uiFingerprintAfter,
+    ...(details ? { details } : {})
   }
 }

package/src/server/tool-handlers.ts

@@ -27,11 +27,19 @@ async function handleStartApp(args: ToolCallArgs) {
   const uiFingerprintAfter = await captureActionFingerprint(platform, deviceId)
   return wrapResponse(buildActionExecutionResult({
     actionType: 'start_app',
+    device: res.device,
     selector: { appId },
     success: !!res.appStarted,
     uiFingerprintBefore,
     uiFingerprintAfter,
-    failure: res.appStarted ? undefined : inferGenericFailure((res as any).error)
+    failure: res.appStarted ? undefined : inferGenericFailure(res.error),
+    details: {
+      launch_time_ms: res.launchTimeMs,
+      ...(typeof res.output === 'string' ? { output: res.output } : {}),
+      ...(res.device ? { device_id: res.device.id } : {}),
+      ...(typeof res.error === 'string' ? { error: res.error } : {}),
+      ...(res.observedApp ? { observed_app: res.observedApp } : {})
+    }
   }))
 }
 
@@ -50,11 +58,20 @@ async function handleRestartApp(args: ToolCallArgs) {
   const uiFingerprintAfter = await captureActionFingerprint(platform, deviceId)
   return wrapResponse(buildActionExecutionResult({
     actionType: 'restart_app',
+    device: res.device,
     selector: { appId },
     success: !!res.appRestarted,
     uiFingerprintBefore,
     uiFingerprintAfter,
-    failure: res.appRestarted ? undefined : inferGenericFailure((res as any).error)
+    failure: res.appRestarted ? undefined : inferGenericFailure(res.error),
+    details: {
+      launch_time_ms: res.launchTimeMs,
+      ...(typeof res.output === 'string' ? { output: res.output } : {}),
+      ...(typeof res.terminatedBeforeRestart === 'boolean' ? { terminated_before_restart: res.terminatedBeforeRestart } : {}),
+      ...(typeof res.terminateError === 'string' ? { terminate_error: res.terminateError } : {}),
+      ...(typeof res.error === 'string' ? { error: res.error } : {}),
+      ...(res.observedApp ? { observed_app: res.observedApp } : {})
+    }
   }))
 }
 

package/src/system/index.ts

@@ -10,8 +10,34 @@ export async function getSystemStatus() {
     const issues = [...android.issues, ...ios.issues, ...(gradle.issues || [])]
 
     const success = issues.length === 0
+    const androidReady = android.adbAvailable && android.devices > 0 && !android.issues.some((issue) => /unauthorized|offline/i.test(issue))
+    const iosReady = ios.iosAvailable && ios.iosDevices > 0
+    const gradleReady = (gradle.issues || []).length === 0
+    const overallStatus = success ? 'ready' : (androidReady || iosReady ? 'degraded' : 'blocked')
+
+    const androidSummary = !android.adbAvailable
+      ? 'ADB unavailable'
+      : android.devices === 0
+        ? 'ADB available but no Android devices connected'
+        : android.logsAvailable
+          ? `${android.devices} Android device(s) connected; log access available`
+          : `${android.devices} Android device(s) connected; log access unavailable`
+
+    const iosSummary = !ios.iosAvailable
+      ? 'xcrun unavailable'
+      : ios.iosDevices === 0
+        ? 'xcrun available but no iOS simulators booted'
+        : `${ios.iosDevices} iOS simulator(s) booted`
+
+    const gradleSummary = !gradle.gradleJavaHome
+      ? 'No explicit Gradle JDK override detected'
+      : gradleReady
+        ? `Gradle JDK configured at ${gradle.gradleJavaHome}`
+        : `Gradle JDK override invalid: ${gradle.gradleJavaHome}`
+
     return {
       success,
+      status: overallStatus,
       adbAvailable: android.adbAvailable,
       adbVersion: android.adbVersion,
       devices: android.devices,
@@ -25,9 +51,38 @@ export async function getSystemStatus() {
       gradleJavaHome: gradle.gradleJavaHome,
       gradleValid: gradle.gradleValid,
       gradleFilesChecked: gradle.filesChecked,
-      gradleSuggestedFixes: gradle.suggestedFixes
+      gradleSuggestedFixes: gradle.suggestedFixes,
+      summary: {
+        overall: overallStatus,
+        android: {
+          ready: androidReady,
+          summary: androidSummary,
+          blockers: android.issues
+        },
+        ios: {
+          ready: iosReady,
+          summary: iosSummary,
+          blockers: ios.issues
+        },
+        gradle: {
+          ready: gradleReady,
+          summary: gradleSummary,
+          blockers: gradle.issues || [],
+          suggestedFixes: gradle.suggestedFixes || []
+        }
+      }
     }
   } catch (e: unknown) {
-    return { success: false, issues: ['Internal error: ' + (e instanceof Error ? e.message : String(e))] }
+    return {
+      success: false,
+      status: 'blocked',
+      issues: ['Internal error: ' + (e instanceof Error ? e.message : String(e))],
+      summary: {
+        overall: 'blocked',
+        android: { ready: false, summary: 'Android status unavailable', blockers: [] },
+        ios: { ready: false, summary: 'iOS status unavailable', blockers: [] },
+        gradle: { ready: false, summary: 'Gradle status unavailable', blockers: [], suggestedFixes: [] }
+      }
+    }
   }
 }

package/src/types.ts

@@ -10,6 +10,15 @@ export interface StartAppResponse {
   device: DeviceInfo;
   appStarted: boolean;
   launchTimeMs: number;
+  output?: string;
+  observedApp?: {
+    appId: string;
+    package?: string | null;
+    activity?: string | null;
+    screen?: string | null;
+    pid?: number | null;
+    matchedTarget?: boolean | null;
+  };
   error?: string;
   diagnostics?: any;
 }
@@ -25,6 +34,17 @@ export interface RestartAppResponse {
   device: DeviceInfo;
   appRestarted: boolean;
   launchTimeMs: number;
+  output?: string;
+  observedApp?: {
+    appId: string;
+    package?: string | null;
+    activity?: string | null;
+    screen?: string | null;
+    pid?: number | null;
+    matchedTarget?: boolean | null;
+  };
+  terminatedBeforeRestart?: boolean;
+  terminateError?: string;
   error?: string;
   diagnostics?: any;
 }
@@ -155,6 +175,7 @@ export interface ActionExecutionResult {
   action_id: string;
   timestamp: number;
   action_type: string;
+  device?: DeviceInfo;
   target: {
     selector: Record<string, unknown> | null;
     resolved: ActionTargetResolved | null;
@@ -164,6 +185,7 @@ export interface ActionExecutionResult {
   retryable?: boolean;
   ui_fingerprint_before?: string | null;
   ui_fingerprint_after?: string | null;
+  details?: Record<string, unknown>;
 }
 
 export interface TapElementResponse extends ActionExecutionResult {}
@@ -179,6 +201,11 @@ export interface ExpectScreenResponse {
     screen: string | null;
   };
   confidence: number;
+  comparison: {
+    basis: 'fingerprint' | 'screen' | 'none';
+    matched: boolean;
+    reason: string;
+  };
 }
 
 export interface ExpectElementVisibleResponse {
@@ -190,7 +217,16 @@ export interface ExpectElementVisibleResponse {
     contains?: boolean;
   };
   element_id: string | null;
+  expected_condition?: 'visible';
   element?: ActionTargetResolved | null;
+  observed?: {
+    status?: string;
+    matched_count?: number;
+    condition_satisfied?: boolean;
+    selected_index?: number | null;
+    last_matched_element?: ActionTargetResolved | null;
+  };
+  reason?: string;
   failure_code?: 'TIMEOUT' | 'ELEMENT_NOT_FOUND' | 'UNKNOWN';
   retryable?: boolean;
 }

package/test/unit/interact/expect_tools.test.ts

@@ -15,7 +15,12 @@ async function run() {
       success: true,
       observed_screen: { fingerprint: 'fp_home', screen: 'com.example.HomeActivity' },
       expected_screen: { fingerprint: 'fp_home', screen: null },
-      confidence: 1
+      confidence: 1,
+      comparison: {
+        basis: 'fingerprint',
+        matched: true,
+        reason: 'observed fingerprint matches expected fingerprint fp_home'
+      }
     })
 
     ;(Observe as any).ToolsObserve.getCurrentScreenHandler = async () => ({
@@ -26,6 +31,11 @@ async function run() {
     assert.strictEqual(expectScreen.success, true)
     assert.strictEqual(expectScreen.observed_screen.screen, 'HomeActivity')
     assert.strictEqual(expectScreen.confidence, 1)
+    assert.deepStrictEqual(expectScreen.comparison, {
+      basis: 'screen',
+      matched: true,
+      reason: 'observed screen matches expected screen HomeActivity'
+    })
 
     ;(ToolsInteract as any).waitForUIHandler = async () => ({
       status: 'success',
@@ -46,10 +56,18 @@ async function run() {
     assert.strictEqual(expectElementVisible.success, true)
     assert.strictEqual(expectElementVisible.element_id, 'el_ready')
     assert.strictEqual(expectElementVisible.element?.resource_id, 'rid_ready')
+    assert.strictEqual(expectElementVisible.expected_condition, 'visible')
+    assert.strictEqual(expectElementVisible.reason, 'selector is visible')
 
     ;(ToolsInteract as any).waitForUIHandler = async () => ({
       status: 'timeout',
-      error: { code: 'ELEMENT_NOT_FOUND', message: 'Condition visible not satisfied within timeout' }
+      error: { code: 'ELEMENT_NOT_FOUND', message: 'Condition visible not satisfied within timeout; observed 0 match(es)' },
+      observed: {
+        matched_count: 0,
+        condition_satisfied: false,
+        selected_index: null,
+        last_matched_element: null
+      }
     })
     const timeoutResult = await ToolsInteract.expectElementVisibleHandler({
       selector: { text: 'Missing' },
@@ -59,6 +77,15 @@ async function run() {
       success: false,
       selector: { text: 'Missing' },
       element_id: null,
+      expected_condition: 'visible',
+      observed: {
+        status: 'timeout',
+        matched_count: 0,
+        condition_satisfied: false,
+        selected_index: null,
+        last_matched_element: null
+      },
+      reason: 'Condition visible not satisfied within timeout; observed 0 match(es)',
       failure_code: 'TIMEOUT',
       retryable: true
     })

package/test/unit/interact/wait_for_screen_change.test.ts

@@ -9,22 +9,26 @@ async function runTests() {
 
   try {
     let seq1: Array<string | null> = ['B', 'B']
-    ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = async () => ({ fingerprint: seq1.length ? seq1.shift() : null })
+    ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = async () => ({ fingerprint: seq1.length ? seq1.shift() : null, activity: 'MainActivity' })
     const start1 = Date.now()
     const res1 = await ToolsInteract.waitForScreenChangeHandler({ platform: 'android', previousFingerprint: 'A', timeoutMs: 2000, pollIntervalMs: 50 })
     const elapsed1 = Date.now() - start1
     assert.ok(res1 && (res1 as any).success === true && (res1 as any).newFingerprint === 'B', 'Immediate fingerprint change should succeed')
+    assert.strictEqual((res1 as any).previousFingerprint, 'A')
+    assert.strictEqual((res1 as any).observed_screen.activity, 'MainActivity')
     console.log('Test 1: Immediate change -> PASS', 'Elapsed:', elapsed1, 'ms')
 
     let seq2: Array<string | null> = [null, null, 'B', 'B']
-    ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = async () => ({ fingerprint: seq2.length ? seq2.shift() : 'B' })
+    ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = async () => ({ fingerprint: seq2.length ? seq2.shift() : 'B', activity: 'NextActivity' })
     const res2 = await ToolsInteract.waitForScreenChangeHandler({ platform: 'android', previousFingerprint: 'A', timeoutMs: 3000, pollIntervalMs: 50 })
     assert.ok(res2 && (res2 as any).success === true && (res2 as any).newFingerprint === 'B', 'Transient nulls should not prevent success')
     console.log('Test 2: Transient nulls -> PASS')
 
-    ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = async () => ({ fingerprint: 'A' })
+    ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = async () => ({ fingerprint: 'A', activity: 'HomeActivity' })
     const res3 = await ToolsInteract.waitForScreenChangeHandler({ platform: 'android', previousFingerprint: 'A', timeoutMs: 300, pollIntervalMs: 50 })
     assert.ok(res3 && (res3 as any).success === false && (res3 as any).reason === 'timeout', 'Unchanged fingerprint should time out')
+    assert.strictEqual((res3 as any).previousFingerprint, 'A')
+    assert.strictEqual((res3 as any).observed_screen.activity, 'HomeActivity')
     console.log('Test 3: Timeout -> PASS')
   } finally {
     ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = original

package/test/unit/interact/wait_for_ui_selector_matching.test.ts

@@ -12,6 +12,12 @@ async function run() {
     const r1 = await ToolsInteract.waitForUIHandler({ selector: { text: 'Hello' }, condition: 'exists', timeout_ms: 1000, poll_interval_ms: 50, platform: 'android' })
     const ok1 = r1 && r1.status === 'success' && r1.matched === 1 && r1.element && r1.element.text === 'Hello' && typeof r1.element.elementId === 'string'
     assert.ok(ok1, 'Exact match should satisfy exists condition')
+    assert.deepStrictEqual((r1 as any).requested, {
+      selector: { text: 'Hello' },
+      condition: 'exists',
+      match: null
+    })
+    assert.strictEqual((r1 as any).observed.matched_count, 1)
     console.log('Exact match exists:', ok1 ? 'PASS' : 'FAIL', JSON.stringify(r1, null, 2))
 
     // Test 2: contains matching
@@ -26,6 +32,9 @@ async function run() {
     const r3 = await ToolsInteract.waitForUIHandler({ selector: { text: 'Hidden' }, condition: 'visible', timeout_ms: 300, poll_interval_ms: 50, platform: 'android' })
     const ok3 = r3 && r3.status === 'timeout' && r3.error && r3.error.code === 'ELEMENT_NOT_FOUND'
     assert.ok(ok3, 'Hidden element should fail visible condition')
+    assert.strictEqual((r3 as any).observed.matched_count, 1)
+    assert.strictEqual((r3 as any).observed.condition_satisfied, false)
+    assert.match((r3 as any).error.message, /observed 1 match/)
     console.log('Visible negative (hidden element):', ok3 ? 'PASS' : 'FAIL', JSON.stringify(r3, null, 2))
 
     // Test 4: clickable condition
@@ -66,8 +75,18 @@ async function run() {
     const r7 = await ToolsInteract.waitForUIHandler({ selector: { text: 'Nope' }, condition: 'exists', timeout_ms: 300, poll_interval_ms: 50, retry: { max_attempts: 1 }, platform: 'android' })
     const ok7 = r7 && r7.status === 'timeout' && r7.error && r7.error.code === 'ELEMENT_NOT_FOUND'
     assert.ok(ok7, 'Missing selector should time out with ELEMENT_NOT_FOUND')
+    assert.strictEqual((r7 as any).observed.selected_index, null)
     console.log('Timeout no match:', ok7 ? 'PASS' : 'FAIL', JSON.stringify(r7, null, 2))
 
+    // Test 8: requested match index out of range should not report a selected index
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => ({ elements: [ { text: 'OnlyOne', resourceId: 'rid8', bounds: [0,0,10,10], visible: true } ] })
+    const r8 = await ToolsInteract.waitForUIHandler({ selector: { text: 'OnlyOne' }, condition: 'exists', timeout_ms: 300, poll_interval_ms: 50, match: { index: 1 }, platform: 'android' })
+    const ok8 = r8 && r8.status === 'timeout' && r8.error && r8.error.code === 'ELEMENT_NOT_FOUND'
+    assert.ok(ok8, 'Out-of-range match index should time out deterministically')
+    assert.strictEqual((r8 as any).observed.matched_count, 1)
+    assert.strictEqual((r8 as any).observed.selected_index, null)
+    console.log('Out-of-range match index:', ok8 ? 'PASS' : 'FAIL', JSON.stringify(r8, null, 2))
+
   } finally {
     ;(Observe as any).ToolsObserve.getUITreeHandler = origGetUITree
   }

package/test/unit/manage/install.test.ts

@@ -69,8 +69,101 @@ exit 0
       assert.ok(res2.output && typeof res2.output === 'string', 'Project dir install succeeded with output')
     }
 
+    const testOnlyAdbPath = path.join(binDir, 'adb-test-only')
+    const testOnlyAdbScript = `#!/bin/sh
+if [ "$1" = "-s" ]; then
+  shift 2
+fi
+
+if [ "$1" = "shell" ] && [ "$2" = "getprop" ]; then
+  case "$3" in
+    ro.build.version.release) echo '16' ;;
+    ro.product.model) echo 'sdk_gphone64_arm64' ;;
+    ro.kernel.qemu) echo '1' ;;
+  esac
+  exit 0
+fi
+
+if [ "$1" = "install" ]; then
+  if [ "$2" = "-r" ] && [ "$3" = "-t" ]; then
+    echo 'Performing Streamed Install'
+    echo 'Success'
+    exit 0
+  fi
+  echo 'Performing Streamed Install'
+  echo 'adb: failed to install test.apk: Failure [INSTALL_FAILED_TEST_ONLY: Failed to install test-only apk. Did you forget to add -t?]' 1>&2
+  exit 1
+fi
+
+echo 'Success'
+exit 0
+`
+    await fs.writeFile(testOnlyAdbPath, testOnlyAdbScript, { mode: 0o755 })
+    process.env.ADB_PATH = testOnlyAdbPath
+
+    const { dir: d2, file: testOnlyApk } = await makeTempFile('.apk')
+    const testOnlyRes = await ai.installApp(testOnlyApk, 'emulator-5554')
+    console.log('testOnlyRes', testOnlyRes)
+    assert.strictEqual(testOnlyRes.installed, true, 'Test-only APK should retry with -t and install successfully')
+
+    const cleanupLog = path.join(binDir, 'pm-cleanup.log')
+    const pmFallbackAdbPath = path.join(binDir, 'adb-pm-fallback')
+    const pmFallbackAdbScript = `#!/bin/sh
+if [ "$1" = "-s" ]; then
+  shift 2
+fi
+
+if [ "$1" = "shell" ] && [ "$2" = "getprop" ]; then
+  case "$3" in
+    ro.build.version.release) echo '16' ;;
+    ro.product.model) echo 'sdk_gphone64_arm64' ;;
+    ro.kernel.qemu) echo '1' ;;
+  esac
+  exit 0
+fi
+
+if [ "$1" = "install" ]; then
+  echo 'adb install failed' 1>&2
+  exit 1
+fi
+
+if [ "$1" = "push" ]; then
+  echo 'pushed'
+  exit 0
+fi
+
+if [ "$1" = "shell" ] && [ "$2" = "pm" ] && [ "$3" = "install" ]; then
+  if [ "$4" = "-r" ] && [ "$5" = "-t" ]; then
+    echo 'Failure [INSTALL_FAILED_VERSION_DOWNGRADE]'
+    exit 1
+  fi
+  echo 'Failure [INSTALL_FAILED_TEST_ONLY: Failed to install test-only apk. Did you forget to add -t?]'
+  exit 1
+fi
+
+if [ "$1" = "shell" ] && [ "$2" = "rm" ]; then
+  echo cleanup >> "${cleanupLog}"
+  exit 0
+fi
+
+echo 'unexpected args:' "$@" 1>&2
+exit 1
+`
+    await fs.writeFile(pmFallbackAdbPath, pmFallbackAdbScript, { mode: 0o755 })
+    process.env.ADB_PATH = pmFallbackAdbPath
+
+    const { dir: d3, file: pmFallbackApk } = await makeTempFile('.apk')
+    const pmFallbackRes = await ai.installApp(pmFallbackApk, 'emulator-5554')
+    console.log('pmFallbackRes', pmFallbackRes)
+    assert.strictEqual(pmFallbackRes.installed, false, 'Failed pm fallback should surface as install failure')
+    assert.match(pmFallbackRes.error || '', /INSTALL_FAILED_VERSION_DOWNGRADE/, 'Final pm retry failure should be reported')
+    const cleanupCount = (await fs.readFile(cleanupLog, 'utf8')).trim().split('\n').filter(Boolean).length
+    assert.strictEqual(cleanupCount, 1, 'pm fallback cleanup should run once')
+
     // cleanup
     await fs.rm(d1, { recursive: true, force: true }).catch(() => {})
+    await fs.rm(d2, { recursive: true, force: true }).catch(() => {})
+    await fs.rm(d3, { recursive: true, force: true }).catch(() => {})
     await fs.rm(dirGradle, { recursive: true, force: true }).catch(() => {})
 
     // restore PATH and ADB_PATH
@@ -87,4 +180,4 @@ exit 0
   }
 }
 
-run().catch((e) => { console.error(e); process.exit(1) })
+run().catch((e) => { console.error(e); process.exit(1) })

package/test/unit/server/response_shapes.test.ts

@@ -78,38 +78,55 @@ async function run() {
       return {
         device: { platform: 'android', id: 'emulator-5554', osVersion: '14', model: 'Pixel', simulator: true },
         appStarted: true,
-        launchTimeMs: 123
+        launchTimeMs: 123,
+        output: 'Events injected: 1',
+        observedApp: {
+          appId: 'com.example.app',
+          package: 'com.example.app',
+          activity: 'com.example.MainActivity',
+          screen: 'MainActivity',
+          matchedTarget: true
+        }
       } as any
     }
     const startAppResponse = await handleToolCall('start_app', { platform: 'android', appId: 'com.example.app' })
     const startAppPayload = JSON.parse((startAppResponse as any).content[0].text)
     assert.strictEqual(startAppPayload.success, true)
     assert.strictEqual(startAppPayload.action_type, 'start_app')
+    assert.strictEqual(startAppPayload.device.id, 'emulator-5554')
     assert.deepStrictEqual(startAppPayload.target.selector, { appId: 'com.example.app' })
+    assert.strictEqual(startAppPayload.details.launch_time_ms, 123)
+    assert.strictEqual(startAppPayload.details.observed_app.matchedTarget, true)
 
     ;(ToolsInteract as any).expectScreenHandler = async () => ({
       success: true,
       observed_screen: { fingerprint: 'fp_after', screen: 'MainActivity' },
       expected_screen: { fingerprint: 'fp_after', screen: null },
-      confidence: 1
+      confidence: 1,
+      comparison: { basis: 'fingerprint', matched: true, reason: 'observed fingerprint matches expected fingerprint fp_after' }
     })
 
     const expectScreenResponse = await handleToolCall('expect_screen', { fingerprint: 'fp_after' })
     const expectScreenPayload = JSON.parse((expectScreenResponse as any).content[0].text)
     assert.strictEqual(expectScreenPayload.success, true)
     assert.strictEqual(expectScreenPayload.confidence, 1)
+    assert.strictEqual(expectScreenPayload.comparison.basis, 'fingerprint')
 
     ;(ToolsInteract as any).expectElementVisibleHandler = async () => ({
       success: true,
       selector: { text: 'Ready' },
       element_id: 'el_ready',
-      element: { elementId: 'el_ready', text: 'Ready', resource_id: null, accessibility_id: null, class: 'TextView', bounds: [0, 0, 10, 10], index: 0 }
+      expected_condition: 'visible',
+      element: { elementId: 'el_ready', text: 'Ready', resource_id: null, accessibility_id: null, class: 'TextView', bounds: [0, 0, 10, 10], index: 0 },
+      observed: { status: 'success', matched_count: 1, condition_satisfied: true, selected_index: 0, last_matched_element: { elementId: 'el_ready', text: 'Ready', resource_id: null, accessibility_id: null, class: 'TextView', bounds: [0, 0, 10, 10], index: 0 } },
+      reason: 'selector is visible'
     })
 
     const expectElementResponse = await handleToolCall('expect_element_visible', { selector: { text: 'Ready' } })
     const expectElementPayload = JSON.parse((expectElementResponse as any).content[0].text)
     assert.strictEqual(expectElementPayload.success, true)
     assert.strictEqual(expectElementPayload.element_id, 'el_ready')
+    assert.strictEqual(expectElementPayload.expected_condition, 'visible')
 
     ;(ToolsObserve as any).captureScreenshotHandler = async () => ({
       device: { platform: 'ios', id: 'booted', osVersion: '18.0', model: 'Simulator', simulator: true },

package/test/unit/system/get_system_status.test.ts

@@ -6,7 +6,9 @@ import { getSystemStatus } from '../../../src/system/index.js'
 async function run() {
   const payload = await getSystemStatus()
   assert(typeof payload.success === 'boolean')
+  assert(typeof (payload as any).status === 'string')
   assert(Array.isArray(payload.issues))
+  assert((payload as any).summary && typeof (payload as any).summary.overall === 'string')
 
   const adb = ensureAdbAvailable()
   assert(adb && typeof adb.ok === 'boolean')

package/test/unit/system/system_status.test.ts

@@ -93,8 +93,11 @@ async function run() {
 
     const healthy = await systemStatus.getSystemStatus()
     assert.strictEqual(healthy.success, true)
+    assert.strictEqual((healthy as any).status, 'ready')
     assert.strictEqual(healthy.adbAvailable, true)
     assert.strictEqual(typeof healthy.adbVersion, 'string')
+    assert.strictEqual((healthy as any).summary.android.ready, true)
+    assert.strictEqual(typeof (healthy as any).summary.ios.summary, 'string')
 
     setScenario({
       ADB_VERSION_STATUS: '1',
@@ -105,6 +108,7 @@ async function run() {
     })
     const missingAdb = await systemStatus.getSystemStatus()
     assert.strictEqual(missingAdb.success, false)
+    assert.strictEqual((missingAdb as any).summary.android.ready, false)
     assert(missingAdb.issues.some((issue: string) => issue.includes('ADB')))
 
     setScenario({
@@ -116,6 +120,7 @@ async function run() {
     })
     const unauthorized = await systemStatus.getSystemStatus()
     assert.strictEqual(unauthorized.success, false)
+    assert.strictEqual((unauthorized as any).summary.android.ready, false)
     assert(unauthorized.issues.some((issue: string) => issue.includes('unauthorized')))
     assert(unauthorized.issues.some((issue: string) => issue.includes('offline')))
 
@@ -130,6 +135,7 @@ async function run() {
     assert.strictEqual(missingXcrun.iosAvailable, false)
     assert.strictEqual(missingXcrun.adbAvailable, true)
     assert.strictEqual(Array.isArray(missingXcrun.issues), true)
+    assert.strictEqual((missingXcrun as any).summary.ios.ready, false)
 
     console.log('system_status checks passed')
   } finally {