mobile-debug-mcp 0.24.1 → 0.24.3

package/src/server/common.ts

@@ -63,26 +63,32 @@ 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()
+  const timestampMs = Date.now()
+  const timestamp = new Date(timestampMs).toISOString()
   return {
-    action_id: nextActionId(actionType, timestamp),
+    action_id: nextActionId(actionType, timestampMs),
     timestamp,
     action_type: actionType,
+    ...(device ? { device } : {}),
     target: {
       selector,
       resolved: normalizeResolvedTarget(resolved)
@@ -90,6 +96,32 @@ 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 } : {})
+  }
+}
+
+export function wrapToolError(name: string, error: unknown) {
+  const message = error instanceof Error
+    ? error.message
+    : typeof error === 'object' && error !== null
+      ? (() => {
+          try {
+            return JSON.stringify(error, null, 2)
+          } catch {
+            return '[unserializable error object]'
+          }
+        })()
+      : String(error)
+  return {
+    content: [{
+      type: 'text' as const,
+      text: JSON.stringify({
+        error: {
+          tool: name,
+          message
+        }
+      }, null, 2)
+    }]
   }
 }

package/src/server/tool-definitions.ts

@@ -10,7 +10,7 @@ Inputs:
 - deviceId (optional)
 
 Output Structure:
-- action_id, timestamp, action_type
+ - action_id, timestamp (ISO 8601), action_type
 - target.selector = { appId }
 - success = true when launch was dispatched successfully
 - failure_code/retryable when launch dispatch fails
@@ -83,7 +83,7 @@ Inputs:
 - deviceId (optional)
 
 Output Structure:
-- action_id, timestamp, action_type
+ - action_id, timestamp (ISO 8601), action_type
 - target.selector = { appId }
 - success = true when the restart command completed
 - failure_code/retryable when restart dispatch fails
@@ -532,7 +532,7 @@ Inputs:
 - deviceId (optional)
 
 Output Structure:
-- action_id, timestamp, action_type
+ - action_id, timestamp (ISO 8601), action_type
 - target.selector = { x, y }
 - success = true when the tap was dispatched
 - failure_code/retryable when dispatch fails
@@ -587,7 +587,7 @@ Inputs:
 
 Output Structure:
 - action_id: unique timestamp-based action identifier
-- timestamp: epoch milliseconds for the action attempt
+- timestamp: ISO 8601 timestamp for the action attempt
 - action_type: "tap_element"
 - target.selector: original target handle ({ elementId })
 - target.resolved: minimal resolved element info used for the tap
@@ -640,7 +640,7 @@ Inputs:
 - platform/deviceId (optional)
 
 Output Structure:
-- action_id, timestamp, action_type
+- action_id, timestamp (ISO 8601), action_type
 - target.selector = { x1, y1, x2, y2, duration }
 - success = true when the swipe was dispatched
 - failure_code/retryable when dispatch fails
@@ -692,7 +692,7 @@ Inputs:
 - direction, maxScrolls, scrollAmount, deviceId (optional)
 
 Output Structure:
-- action_id, timestamp, action_type
+- action_id, timestamp (ISO 8601), action_type
 - target.selector = original selector
 - target.resolved = minimal resolved element info when found
 - success = true when scrolling produced a visible target element
@@ -746,7 +746,7 @@ Inputs:
 - platform/deviceId (optional)
 
 Output Structure:
-- action_id, timestamp, action_type
+- action_id, timestamp (ISO 8601), action_type
 - target.selector = { text }
 - success = true when text input was dispatched
 - failure_code/retryable when dispatch fails
@@ -795,7 +795,7 @@ Inputs:
 - platform/deviceId (optional)
 
 Output Structure:
-- action_id, timestamp, action_type
+- action_id, timestamp (ISO 8601), action_type
 - target.selector = { key: "back" }
 - success = true when the back action was dispatched
 - failure_code/retryable when dispatch fails

package/src/server/tool-handlers.ts

@@ -16,7 +16,8 @@ import {
   inferScrollFailure,
   ToolCallArgs,
   ToolHandler,
-  wrapResponse
+  wrapResponse,
+  wrapToolError
 } from './common.js'
 
 async function handleStartApp(args: ToolCallArgs) {
@@ -27,11 +28,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 +59,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 } : {})
+    }
   }))
 }
 
@@ -358,8 +376,7 @@ export async function handleToolCall(name: string, args: ToolCallArgs = {}) {
   try {
     return await handler(args)
   } catch (error) {
-    return {
-      content: [{ type: 'text' as const, text: `Error executing tool ${name}: ${error instanceof Error ? error.message : String(error)}` }]
-    }
+    console.error(`Error executing tool ${name}:`, error)
+    return wrapToolError(name, error)
   }
 }

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;
 }
@@ -153,8 +173,9 @@ export interface ActionTargetResolved {
 
 export interface ActionExecutionResult {
   action_id: string;
-  timestamp: number;
+  timestamp: string;
   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/server/response_shapes.test.ts

@@ -47,7 +47,7 @@ async function run() {
 
     ;(ToolsInteract as any).tapElementHandler = async () => ({
       action_id: 'tap_element_1',
-      timestamp: 1234567890,
+      timestamp: '2026-04-23T08:00:00.000Z',
       action_type: 'tap_element',
       target: {
         selector: { elementId: 'el_ready' },
@@ -62,6 +62,7 @@ async function run() {
     const tapElementPayload = JSON.parse((tapElementResponse as any).content[0].text)
     assert.strictEqual(tapElementPayload.success, true)
     assert.strictEqual(tapElementPayload.action_type, 'tap_element')
+    assert.match(tapElementPayload.timestamp, /^\d{4}-\d{2}-\d{2}T/)
     assert.strictEqual(tapElementPayload.target.resolved.elementId, 'el_ready')
     assert.strictEqual(tapElementPayload.ui_fingerprint_before, 'fp_before')
 
@@ -71,6 +72,7 @@ async function run() {
     const tapPayload = JSON.parse((tapResponse as any).content[0].text)
     assert.strictEqual(tapPayload.success, true)
     assert.strictEqual(tapPayload.action_type, 'tap')
+    assert.match(tapPayload.timestamp, /^\d{4}-\d{2}-\d{2}T/)
     assert.deepStrictEqual(tapPayload.target.selector, { x: 1, y: 2 })
     assert.strictEqual(tapPayload.ui_fingerprint_before, 'fp_mock')
 
@@ -78,38 +80,80 @@ 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.match(startAppPayload.timestamp, /^\d{4}-\d{2}-\d{2}T/)
+    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')
+
+    ;(ToolsInteract as any).tapHandler = async () => {
+      throw new Error('boom')
+    }
+
+    const failingTapResponse = await handleToolCall('tap', { platform: 'android', x: 1, y: 2 })
+    assert.strictEqual((failingTapResponse as any).content.length, 1)
+    const failingTapPayload = JSON.parse((failingTapResponse as any).content[0].text)
+    assert.deepStrictEqual(failingTapPayload, {
+      error: {
+        tool: 'tap',
+        message: 'boom'
+      }
+    })
+
+    ;(ToolsInteract as any).tapHandler = async () => {
+      throw { code: 'E_CUSTOM', detail: { field: 'value' } }
+    }
+
+    const objectTapResponse = await handleToolCall('tap', { platform: 'android', x: 1, y: 2 })
+    const objectTapPayload = JSON.parse((objectTapResponse as any).content[0].text)
+    assert.strictEqual(objectTapPayload.error.tool, 'tap')
+    assert.match(objectTapPayload.error.message, /"code": "E_CUSTOM"/)
+    assert.match(objectTapPayload.error.message, /"field": "value"/)
 
     ;(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 {