mobile-debug-mcp 0.36.0 → 0.37.0

package/src/server/handlers/interaction-diagnostics.ts

@@ -0,0 +1,50 @@
+import { randomUUID } from 'node:crypto'
+import { evidenceSessionId } from '../../observe/evidence.js'
+import { diagnosticsSchema } from '../schemas/interaction-diagnostics.js'
+import { wrapResponse, type ToolCallArgs } from '../common.js'
+
+type ExpiryScheduler = (expire: () => void) => () => void
+const scheduleExpiry: ExpiryScheduler = expire => {
+  const timer = setTimeout(expire, 600000)
+  timer.unref()
+  return () => clearTimeout(timer)
+}
+
+export class InteractionDiagnostics {
+  private readonly entries = new Map<string, { text: string; completed: number; bytes: number; cancel: () => void }>()
+  private bytes = 0
+  constructor(private readonly now = () => performance.now(), readonly sessionId = evidenceSessionId(), private readonly schedule: ExpiryScheduler = scheduleExpiry) {}
+
+  private remove(id: string) {
+    const entry = this.entries.get(id)
+    if (entry) { this.bytes -= entry.bytes; entry.cancel() }
+    this.entries.delete(id)
+  }
+  private prune() {
+    for (const [id, entry] of this.entries) if (this.now() - entry.completed >= 600000) this.remove(id)
+  }
+  retain(result: unknown) {
+    this.prune()
+    const resultId = randomUUID(), text = JSON.stringify(result), bytes = Buffer.byteLength(text)
+    const ref = { session_id: this.sessionId, result_id: resultId }
+    if (bytes > 1024 * 1024) return { ...ref, available: false, reason: 'RESULT_TOO_LARGE' }
+    while (this.entries.size >= 100 || this.bytes + bytes > 16 * 1024 * 1024) this.remove(this.entries.keys().next().value!)
+    this.entries.set(resultId, { text, completed: this.now(), bytes, cancel: this.schedule(() => this.remove(resultId)) })
+    this.bytes += bytes
+    return { ...ref, available: true }
+  }
+  lookup(sessionId: string, resultId: string) {
+    this.prune()
+    if (sessionId !== this.sessionId) return { success: false, error: { code: 'SESSION_MISMATCH', message: 'Use the session_id returned with this result.' } }
+    const entry = this.entries.get(resultId)
+    if (!entry) return { success: false, error: { code: 'RESULT_UNAVAILABLE', message: 'Result expired, was evicted, is unknown, or belongs to a previous server process. Do not replay input automatically.' } }
+    return { success: true, result: JSON.parse(entry.text) as unknown }
+  }
+}
+export const interactionDiagnostics = new InteractionDiagnostics()
+export async function handleInteractionDiagnostics(args: ToolCallArgs) {
+  const parsed = diagnosticsSchema.safeParse(args)
+  return wrapResponse(parsed.success ? interactionDiagnostics.lookup(parsed.data.sessionId, parsed.data.resultId) : {
+    success: false, error: { code: 'INVALID_ARGUMENT', message: 'Expected only sessionId and resultId UUID strings.' }
+  }, false)
+}

package/src/server/handlers/journey.ts

@@ -1,7 +1,9 @@
+import { observeDeviceReadiness } from '../../observe/device-readiness.js'
+import { benchmarkStage } from '../../utils/benchmark-metrics.js'
 import type { z } from 'zod'
 import { debuggerSessions } from '../../debugger/sessions.js'
 import { systemTraces } from '../../observe/system-trace.js'
-import { currentEvidenceCorrelationId, bindSystemTrace, refreshJourneyEvidence, completeJourneyVerification } from '../../observe/evidence.js'
+import { currentEvidenceCorrelationId, bindSystemTrace, withJourneyStepEvidence, refreshJourneyEvidence, completeJourneyVerification, JourneyStepError } from '../../observe/evidence.js'
 import { runWithBudget } from '../../utils/operation-budget.js'
 import { journeySchema } from '../schemas/journey-schema.js'
 import { resolveTargetDevice, withResolvedDevice } from '../../utils/resolve-device.js'
@@ -33,19 +35,22 @@ async function assertStep(step: AssertionStep, platform: Journey['platform'], de
   if (assertion.kind === 'state_equals') return ToolsInteract.expectStateHandler({ selector: assertion.selector, element_id: assertion.elementId, property: assertion.property, expected: assertion.expected, platform, deviceId, stabilization_window_ms: timeoutMs, poll_interval_ms: pollIntervalMs, exact_budget: true })
   return { success: false, failure_code: 'INVALID_ASSERTION' }
 }
+async function observeStep(s: Context, operation: () => Promise<ToolPayload>) {
+  return s.input.responseMode === 'compact' ? withJourneyStepEvidence(operation) : operation()
+}
 async function executeStep(s: Context, step: Step, covered: boolean): Promise<ToolPayload> {
   const { platform, responseMode, defaults } = s.input, deviceId = s.deviceId
   try {
     if (step.type === 'tap') return payloadOf(await handleTapElement({ ...defaults, ...step, platform, deviceId, responseMode, _journey: true, _stepId: step.id, verificationMode: covered ? 'none' : step.verificationMode ?? defaults?.verificationMode ?? 'full' }))
-    if (step.type === 'wait') {
+    if (step.type === 'wait') return await observeStep(s, async () => {
       const result = (await withObservationContext({ stepId: step.id, purpose: 'target' }, () => ToolsInteract.waitForUIHandler({ selector: step.selector, condition: step.condition ?? 'exists', timeout_ms: step.timeoutMs ?? 5000, poll_interval_ms: step.pollIntervalMs ?? 100, platform, deviceId })))!
       return { success: result.status === 'success', ...result }
-    }
-    if (step.type === 'assert') return await withObservationContext({ stepId: step.id, purpose: 'assertion' }, () => runWithBudget(step.timeoutMs ?? 5000, () => assertStep(step, platform, deviceId)))
+    })
+    if (step.type === 'assert') return await observeStep(s, () => withObservationContext({ stepId: step.id, purpose: 'assertion' }, () => runWithBudget(step.timeoutMs ?? 5000, () => assertStep(step, platform, deviceId))))
     if (step.type === 'start_app') return payloadOf(await handleStartApp({ ...defaults, platform, deviceId, appId: step.appId, responseMode, _journey: true, _stepId: step.id, verificationMode: step.verificationMode ?? defaults?.verificationMode ?? 'full' }))
     return { success: false, failure_code: 'UNSUPPORTED_JOURNEY_STEP' }
   } catch (error) {
-    return { success: false, failure_code: step.type === 'assert' ? 'ASSERTION_TIMEOUT' : 'STEP_FAILED', error: error instanceof Error ? error.message : String(error) }
+    return { success: false, failure_code: step.type === 'assert' ? 'ASSERTION_TIMEOUT' : 'STEP_FAILED', error: error instanceof Error ? error.message : String(error), ...(error instanceof JourneyStepError ? { evidence: error.evidence } : {}) }
   }
 }
 function lightVerification(s: Context, step: Step, result: ToolPayload, covered: boolean, success: boolean) {
@@ -68,24 +73,16 @@ function lightVerification(s: Context, step: Step, result: ToolPayload, covered:
   }
   s.pendingLightStep = null
 }
-function compactAssertion(result: ToolPayload, success: boolean) {
-  const errorCode = typeof result.error === 'object' ? result.error?.code : undefined
-  return { success, ...(result.failure_code ? { failure_code: result.failure_code } : {}),
-    ...(errorCode ? { failure_code: errorCode } : {}),
-    ...(result.observed?.matched_count !== undefined ? { matched_count: result.observed.matched_count } : {}),
-    ...(result.observed_fingerprint !== undefined ? { matched: success } : {}),
-    ...(result.actual_state ? { observed: result.actual_state } : {}) }
-}
 function coveredByAssertion(s: Context, step: Step, next?: Step) {
   const verification = ('verificationMode' in step ? step.verificationMode : undefined) ?? s.input.defaults?.verificationMode ?? 'full'
   return step.type === 'tap' && s.input.responseMode === 'compact' && verification === 'light' && next?.type === 'assert' && next.assertion.kind === 'element_visible'
 }
 async function runSteps(s: Context) {
-  const { platform, responseMode, steps } = s.input
+  const { platform, steps } = s.input
   for (let index = 0; index < steps.length; index++) {
     const step = steps[index]
     if (platform === 'android' && debuggerSessions.paused(s.deviceId)) {
-      s.results.push({ id: step.id, type: step.type, status: 'failed', success: false, result: { success: false, failure_code: 'DEBUGGER_PAUSED', dispatch_started: false, delivery_status: 'not_delivered' } })
+      s.results.push({ id: step.id, type: step.type, status: 'failed', success: false, result: { device_readiness: await observeDeviceReadiness({ platform, id: s.deviceId }), success: false, failure_code: 'DEBUGGER_PAUSED', dispatch_started: false, delivery_status: 'not_delivered' } })
       s.stoppedAt = step.id
       break
     }
@@ -94,12 +91,13 @@ async function runSteps(s: Context) {
       s.results.push({ id: step.id, type: step.type, status: 'not_run', success: false, reason: 'PREVIOUS_STEP_FAILED', result: null, timing: { total_ms: 0 } })
       continue
     }
-    let result = await executeStep(s, step, covered)
+    const result = await (step.type === 'assert' || step.type === 'wait'
+      ? benchmarkStage(step.type === 'assert' ? 'assertion_ms' : 'wait_ms', () => executeStep(s, step, covered))
+      : executeStep(s, step, covered))
     if (platform === 'android' && debuggerSessions.paused(s.deviceId)) { result.success = false; result.failure_code = 'DEBUGGER_PAUSED'; result.retryable = false }
     if (step.type === 'assert' && !result?.success && /TIMEOUT/.test(result?.failure_code ?? '')) result.failure_code = 'ASSERTION_TIMEOUT'
     const success = !!result?.success
     lightVerification(s, step, result, covered, success)
-    if (responseMode === 'compact' && ['wait', 'assert'].includes(step.type)) result = compactAssertion(result, success)
     s.results.push({ id: step.id, type: step.type, status: success ? 'passed' : 'failed', success, result, timing: { total_ms: performance.now() - started } })
     if (!success) s.stoppedAt = step.id
   }

package/src/server/handlers/observe.ts

@@ -1,6 +1,7 @@
 
 
 import { ToolsObserve } from '../../observe/index.js'
+import { benchmarkStage } from '../../utils/benchmark-metrics.js'
 import { withObservationContext } from '../../observe/performance-metrics.js'
 import {
   getBooleanArg,
@@ -37,7 +38,7 @@ export async function handleCaptureScreenshot(args: ToolCallArgs) {
   const platform = requireStringArg(args, 'platform') as PlatformArg
   const deviceId = getStringArg(args, 'deviceId')
   const started = performance.now()
-  const res = await ToolsObserve.captureScreenshotHandler({ platform, deviceId })
+  const res = await benchmarkStage('screenshot_capture_ms', () => ToolsObserve.captureScreenshotHandler({ platform, deviceId }))
   const screenshotMs = performance.now() - started
   const mime = res.screenshot_mime || 'image/png'
   const content: Array<{ type: 'text' | 'image'; text?: string; data?: string; mimeType?: string }> = [

package/src/server/handlers/payload.ts

@@ -4,6 +4,7 @@ import type { ToolCallResult } from '../common.js'
 // Internal decoded MCP payloads vary by capability. Keep the fields inspected by
 // orchestration explicit while preserving untouched capability-specific fields.
 export interface ToolPayload {
+  device_readiness?: import('../../contracts/device-readiness.js').DeviceReadiness
   success?: boolean
   action_id?: string
   action_type?: string
@@ -25,7 +26,7 @@ export interface ToolPayload {
   status?: string
   condition?: ActionConditionResult
   verification?: { mode?: string; status: string }
-  evidence?: { action_id?: string }
+  evidence?: { action_id?: string | null }
   verification_diagnostic?: { code: string; retryable: boolean }
   observed?: { matched_count?: number | null }
   timing?: TimingBreakdown

package/src/server/handlers/tool-handlers.ts

@@ -1,3 +1,6 @@
+import { finalizeCompactInteraction } from './compact-interaction.js'
+import { handleInteractionDiagnostics } from './interaction-diagnostics.js'
+import { observeDeviceReadiness } from '../../observe/device-readiness.js'
 import { ToolsInteract } from '../../interact/index.js'
 import type { DeviceInfo } from '../../types.js'
 import { handleDebugger } from './debugger-handlers.js'
@@ -41,6 +44,7 @@ export const toolHandlers: Record<string, ToolHandler> = {
     if (!parsed.success) throw new Error('INVALID_ARGUMENT: invalid readiness arguments')
     return wrapResponse(await getAppReadiness(parsed.data, true))
   },
+  get_interaction_diagnostics: handleInteractionDiagnostics,
   start_app: handleStartApp,
   terminate_app: handleTerminateApp,
   restart_app: handleRestartApp,
@@ -94,7 +98,7 @@ async function dispatchGuarded(device: DeviceInfo, args: ToolCallArgs, handler:
   const sessions = device.platform === 'ios' ? iosDebuggerSessions : debuggerSessions
   return withResolvedDevice(device, () => withDebuggerGuard(device.platform, device.id, async () => {
     const before = sessions.paused(device.id)
-    if (before) return wrapResponse({ success: false, failure_code: 'DEBUGGER_PAUSED', delivery_status: 'not_delivered', dispatch_started: false, debugger: before })
+    if (before) return addTiming(wrapResponse({ device_readiness: await observeDeviceReadiness(device), success: false, failure_code: 'DEBUGGER_PAUSED', delivery_status: 'not_delivered', dispatch_started: false, debugger: before }))
     let response: ToolCallResult
     try { response = await handler(args) } catch (error) {
       if (!sessions.paused(device.id)) throw error
@@ -107,7 +111,7 @@ async function dispatchGuarded(device: DeviceInfo, args: ToolCallArgs, handler:
         const payload = JSON.parse(item.text)
         Object.assign(payload, { success: false, failure_code: 'DEBUGGER_PAUSED', retryable: false,
           dispatch_started: guardDispatched(), delivery_status: payload.success ? 'delivered' : guardDispatched() ? 'unknown' : 'not_delivered',
-          verification: { status: 'blocked', reason: 'DEBUGGER_PAUSED' }, debugger: pause })
+          verification: { status: 'blocked', reason: 'DEBUGGER_PAUSED' }, device_readiness: await observeDeviceReadiness(device), debugger: pause })
         item.text = JSON.stringify(payload)
       }
     }
@@ -139,7 +143,7 @@ export async function handleToolCall(name: string, args: ToolCallArgs = {}, sign
   const started = performance.now()
   const measured: Record<string, number> = {}
   const addTiming = (response: ToolCallResult) => {
-    if (!['start_app', 'restart_app', 'tap', 'tap_element', 'swipe', 'scroll_to_element', 'type_text', 'press_back', 'wait_for_ui', 'get_ui_tree', 'capture_screenshot', 'capture_debug_snapshot'].includes(name)) return response
+    if (!['start_app', 'restart_app', 'tap', 'tap_element', 'swipe', 'scroll_to_element', 'type_text', 'press_back', 'wait_for_ui', 'get_ui_tree', 'capture_screenshot', 'capture_debug_snapshot'].includes(name)) return finalizeCompactInteraction(name, args, response)
     const item = response.content.find(item => item.type === 'text')
     if (item?.text) {
       try {
@@ -148,7 +152,7 @@ export async function handleToolCall(name: string, args: ToolCallArgs = {}, sign
         item.text = JSON.stringify(value)
       } catch { /* Non-JSON text responses retain their original content. */ }
     }
-    return response
+    return finalizeCompactInteraction(name, args, response)
   }
   return withTiming(measured, async () => {
     try {
@@ -162,7 +166,7 @@ export async function handleToolCall(name: string, args: ToolCallArgs = {}, sign
       attachPausedObservation(name, args, response)
       return addTiming(response)
     } catch (error) {
-      if (error instanceof TraceError) return { ...wrapResponse({ error: { tool: name, code: error.code, message: error.message } }), isError: true }
+      if (error instanceof TraceError) return addTiming({ ...wrapResponse({ error: { tool: name, code: error.code, message: error.message } }), isError: true })
       console.error(`Error executing tool ${name}:`, error)
       return addTiming(wrapToolError(name, error))
     }

package/src/server/schemas/interaction-diagnostics.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod'
+import type { Tool } from '@modelcontextprotocol/sdk/types.js'
+export const diagnosticsSchema = z.object({ sessionId: z.string().uuid(), resultId: z.string().uuid() }).strict()
+export const interactionDiagnosticsTool: Tool = {
+  name: 'get_interaction_diagnostics',
+  description: 'Read the retained original interaction or journey result without replaying input or observing the device. Pass diagnostics.session_id/result_id as sessionId/resultId. Session-local memory: ten minutes, 100 results, 16 MiB total, 1 MiB per result. Expired, evicted or restarted results are unavailable. May contain private UI text and errors; compact output is not redaction.',
+  inputSchema: { type: 'object', additionalProperties: false, required: ['sessionId', 'resultId'], properties: {
+    sessionId: { type: 'string', format: 'uuid' }, resultId: { type: 'string', format: 'uuid' }
+  } }
+}

package/src/server/tool-definitions.ts

@@ -1,3 +1,4 @@
+import { interactionDiagnosticsTool } from './schemas/interaction-diagnostics.js'
 import { verificationModeJson, responseModeJson } from '../contracts/execution-controls.js'
 import type { Tool } from '@modelcontextprotocol/sdk/types.js'
 import { manageTools } from './definitions/manage.js'
@@ -53,9 +54,10 @@ const baseOrder = [
 export const toolDefinitions: Tool[] = [
 ...debuggerTools,
 ...systemTraceTools,
+interactionDiagnosticsTool,
 ...['get_app_readiness', 'wait_for_app_ready'].map(name => ({
     name,
-    description: `${name === 'get_app_readiness' ? 'Observe readiness with at most two fresh UI-tree samples.' : 'Wait within a single bounded budget for settled UI evidence.'} Reports loading, transitioning, settled or unknown with evidence and limitations. Managed Android debugger pauses are reported from debugger evidence; unresponsive detection remains unsupported. Settled normalized foreground UI is not proof of app identity, responsiveness or backend completion.`,
+    description: `${name === 'get_app_readiness' ? 'Observe readiness with at most two fresh UI-tree samples.' : 'Wait within a single bounded budget for settled UI evidence.'} Reports loading, transitioning, settled or unknown with evidence and limitations. Managed Android and supported iOS simulator debugger pauses are reported from debugger evidence; unresponsive detection remains unsupported. Settled normalized foreground UI is not proof of app identity, responsiveness or backend completion.`,
     inputSchema: { type: 'object' as const, additionalProperties: false, required: ['platform'], properties: {
       ...readinessPropertiesJson,
       timeoutMs: { ...readinessPropertiesJson.timeoutMs, default: name === 'get_app_readiness' ? 15000 : 30000 },
@@ -70,10 +72,10 @@ for (const tool of toolDefinitions) {
   tool.inputSchema.properties ??= {}
   if (['wait_for_ui', 'wait_for_ui_change'].includes(tool.name)) {
     tool.inputSchema.properties.requireReady = { type: 'boolean', default: false }
-    tool.description += '\nSet requireReady=true to require both the existing predicate and settled UI readiness, using the same fresh samples and one timeout budget. The readiness summary explains uncertainty. Default predicate semantics are unchanged.'
+    tool.description += '\nDevice-readiness blockers prevent readiness success; unknown/unsupported device signals remain explicit.\nSet requireReady=true to require both the existing predicate and settled UI readiness, using the same fresh samples and one timeout budget. The readiness summary explains uncertainty. Default predicate semantics are unchanged.'
   }
   if (tool.name === 'get_ui_tree') tool.description += '\nSuccessful observations include snapshot_session_id and snapshot_revision for same-device conditional input. Compact errors preserve the error and cannot authorize an expectation.'
-  if (tool.name === 'run_journey') tool.description += '\nTap steps may include expectedState from a successful same-device get_ui_tree. A failed condition blocks that input, retains fresh condition evidence even in compact mode, and stops subsequent steps. Conditions are not journey defaults or supported on other step types.'
+  if (tool.name === 'run_journey') tool.description += '\nTap steps may include expectedState from a successful same-device get_ui_tree. A failed condition blocks that input, retains fresh condition evidence through a diagnostics reference in compact mode, and stops subsequent steps. Conditions are not journey defaults or supported on other step types.'
   if (conditionalTools.has(tool.name)) {
     tool.inputSchema.properties.expectedState = expectedStateJson
     tool.inputSchema.properties.platform ??= { type: 'string', enum: ['android'] }
@@ -84,11 +86,12 @@ for (const tool of toolDefinitions) {
         deviceId: { type: 'string', minLength: 1, pattern: '\\S', not: { enum: ['booted', 'default'] } }
       } }
     }]
-    tool.description += '\n\nConditional input: optionally supply expectedState { snapshotSessionId, snapshotRevision, timeoutMs? } from a successful get_ui_tree on the same explicit platform/deviceId. A fresh normalized UI-tree check runs immediately before input, even with verification disabled. PRECONDITION_FAILED or PRECONDITION_UNAVAILABLE means no input was dispatched; inspect condition evidence and re-observe before deciding what to do next. Compact failures include the fresh UI tree. This is not atomic with OS input delivery.'
+    tool.description += '\n\nConditional input: optionally supply expectedState { snapshotSessionId, snapshotRevision, timeoutMs? } from a successful get_ui_tree on the same explicit platform/deviceId. A fresh normalized UI-tree check runs immediately before input, even with verification disabled. PRECONDITION_FAILED or PRECONDITION_UNAVAILABLE means no input was dispatched; inspect condition evidence and re-observe before deciding what to do next. Compact failures summarize the fresh condition evidence; use get_interaction_diagnostics with the returned diagnostics reference for the retained UI tree. This is not atomic with OS input delivery.'
   } else {
     tool.inputSchema.allOf = [...(Array.isArray(tool.inputSchema.allOf) ? tool.inputSchema.allOf : []), { not: { required: ['expectedState'] } }]
   }
   if (['start_app', 'restart_app', 'tap', 'tap_element', 'swipe', 'scroll_to_element', 'type_text', 'press_back'].includes(tool.name)) {
+    tool.description += '\nCompact results summarize observations, condition trees, state deltas and readiness probe evidence within a byte budget. Use get_interaction_diagnostics with the returned diagnostics session_id/result_id to retrieve the original result without replaying input. Debug output is unchanged.'
     Object.assign(tool.inputSchema.properties, {
       verificationMode: { ...verificationModeJson, default: 'full' },
       responseMode: { ...responseModeJson, default: 'debug' },
@@ -111,6 +114,7 @@ for (const tool of toolDefinitions) {
 // Correlation is explicit; an omitted reference creates an independent observation.
 for (const tool of toolDefinitions) {
   tool.inputSchema.properties ??= {}
+  if (['start_app', 'restart_app', 'tap', 'tap_element', 'swipe', 'scroll_to_element', 'type_text', 'press_back', 'adjust_control', 'get_app_readiness', 'wait_for_app_ready'].includes(tool.name)) tool.description += '\nResults include device_readiness with timestamped device blocker evidence. Android reports supported power/keyguard signals; iOS signals may be unknown or explicitly unsupported. Launch/input dispatch success does not establish app visibility or input readiness. No automatic unlock or wake is performed.'
   if (['capture_screenshot', 'get_ui_tree', 'get_screen_fingerprint', 'capture_debug_snapshot', 'get_logs', 'read_log_stream'].includes(tool.name)) {
     Object.assign(tool.inputSchema.properties, { actionRef: {
       type: 'object' as const, additionalProperties: false, required: ['sessionId', 'actionId'], properties: {

package/src/server-core.ts

@@ -11,12 +11,13 @@ import {
 import { wrapResponse } from './server/common.js'
 import { toolDefinitions } from './server/tool-definitions.js'
 import { handleToolCall } from './server/handlers/tool-handlers.js'
+import { withBenchmarkRequest, benchmarkStage } from './utils/benchmark-metrics.js'
 
 export { wrapResponse, toolDefinitions, handleToolCall }
 
 export const serverInfo = {
   name: 'mobile-debug-mcp',
-  version: '0.36.0'
+  version: '0.37.0'
 }
 
 export function createServer() {
@@ -48,7 +49,9 @@ export function createServer() {
 
   server.setRequestHandler(CallToolRequestSchema, async (request: SchemaOutput<typeof CallToolRequestSchema>, extra) => {
     const { name, arguments: args } = request.params
-    return handleToolCall(name, args as Record<string, unknown>, extra.signal)
+    const operation = () => handleToolCall(name, args as Record<string, unknown>, extra.signal)
+    return withBenchmarkRequest(name, () => name.startsWith('expect_') || name.startsWith('wait_for_')
+      ? benchmarkStage(name.startsWith('expect_') ? 'assertion_ms' : 'wait_ms', operation) : operation())
   })
 
   return server

package/src/server.ts

@@ -9,7 +9,7 @@ const server = createServer()
 
 if (process.env.MOBILE_DEBUG_MCP_STARTUP_HEALTHCHECK === '1') {
   getSystemStatus().then((res) => {
-    console.info('[startup] system status summary:', { adb: res.adbAvailable, ios: res.iosAvailable, devices: res.devices, iosDevices: res.iosDevices })
+    console.info('[startup] system status summary:', { adb: 'adbAvailable' in res ? res.adbAvailable : false, ios: 'iosAvailable' in res ? res.iosAvailable : false, devices: 'devices' in res ? res.devices : 0, iosDevices: 'iosDevices' in res ? res.iosDevices : 0 })
   }).catch((e) => console.warn('[startup] healthcheck failed:', e instanceof Error ? e.message : String(e)))
 }
 

package/src/system/android.ts

@@ -1,3 +1,4 @@
+import { probeInstallation, validAppId, type AppInstallation } from '../utils/app-installation.js'
 import { execSync } from 'child_process'
 import { ensureAdbAvailable } from '../utils/android/utils.js'
 
@@ -10,6 +11,8 @@ export async function checkAndroid() {
   let logsAvailable = false
   let envValid = false
   let appInstalled: boolean | undefined = undefined
+  let appInstallations: AppInstallation[] = []
+  let targets: { id: string; available: boolean }[] = []
 
   try {
     const adbCheck = ensureAdbAvailable()
@@ -21,6 +24,7 @@ export async function checkAndroid() {
     try {
       const out = execSync(`${adbCmd} devices -l`, { encoding: 'utf8', timeout: 1500, stdio: ['ignore', 'pipe', 'ignore'] }).toString()
       const state = parseDevices(out, issues)
+      targets = out.split('\n').map(line => line.trim().split(/\s+/)).filter(parts => parts[0] && !['List', '*'].includes(parts[0])).map(parts => ({ id: parts[0], available: parts[1] === 'device' }))
       devices = state.devices; deviceStates = state.deviceStates
 
     } catch (e: unknown) { console.debug('[get_system_status] adb devices failed: ' + String(e)); issues.push('Failed to list Android devices') }
@@ -38,12 +42,12 @@ export async function checkAndroid() {
     if (!envValid) issues.push('ANDROID_SDK_ROOT/ANDROID_HOME missing and adb not found in PATH')
 
     const pkg = process.env.MCP_TARGET_PACKAGE || process.env.MCP_TARGET_APP_ID
-    if (pkg && adbAvailable && devices > 0) {
-      appInstalled = probeAppInstalled(adbCmd, pkg, issues)
-    }
+    appInstallations = await Promise.all(targets.map(target => probeInstallation(adbCmd, target.id, pkg, 'android-current-user', adbAvailable && target.available)))
+    reportInstallations(appInstallations, pkg, issues)
+    appInstalled = installationSummary(appInstallations)
   } catch (e: unknown) { console.debug('[get_system_status] adb availability check failed: ' + String(e)); issues.push('ADB check failed') }
 
-  return { adbAvailable, adbVersion, devices, deviceStates, logsAvailable, envValid, appInstalled, issues }
+  return { adbAvailable, adbVersion, devices, deviceStates, logsAvailable, envValid, appInstalled, appInstallations, issues }
 }
 
 function parseDevices(out: string, issues: string[]) {
@@ -64,11 +68,14 @@ function parseDevices(out: string, issues: string[]) {
   return { devices, deviceStates }
 }
 
-function probeAppInstalled(adbCmd: string, pkg: string, issues: string[]) {
-  try {
-    const pm = execSync(`${adbCmd} shell pm path ${pkg}`, { encoding: 'utf8', timeout: 1500, stdio: ['ignore', 'pipe', 'ignore'] }).toString()
-    const appInstalled = (pm || '').includes('package:')
-    if (!appInstalled) issues.push(`App ${pkg} not installed on devices`)
-    return appInstalled
-  } catch (e: unknown) { console.debug('[get_system_status] pm check failed: ' + String(e)); return false }
+
+function installationSummary(checks: AppInstallation[]) {
+  return checks.length === 1 && checks[0].status !== 'unknown' ? checks[0].status === 'installed' : undefined
+}
+function reportInstallations(checks: AppInstallation[], pkg: string | undefined, issues: string[]) {
+  if (pkg !== undefined && !validAppId(pkg)) issues.push('Invalid target app identifier')
+  for (const check of checks) {
+    if (check.status === 'absent') issues.push(`App ${check.appId} not installed on device ${check.deviceId}`)
+    if (check.status === 'unknown' && check.reason !== 'APP_ID_NOT_PROVIDED') issues.push(`Installation check unavailable on device ${check.deviceId}: ${check.reason}`)
+  }
 }

package/src/system/index.ts

@@ -47,7 +47,8 @@ export async function getSystemStatus() {
       logsAvailable: androidRaw.logsAvailable,
       envValid: androidRaw.envValid,
       issues,
-      appInstalled: androidRaw.appInstalled,
+      ...(androidRaw.appInstalled === undefined ? {} : { appInstalled: androidRaw.appInstalled }),
+      appInstallations: androidRaw.appInstallations,
       iosAvailable: iosRaw.iosAvailable,
       iosDevices: iosRaw.iosDevices,
       gradleJavaHome: gradle.gradleJavaHome,

package/src/types.ts

@@ -7,6 +7,7 @@ export interface DeviceInfo {
   model: string;
   simulator: boolean;
   appInstalled?: boolean;
+  appInstallation?: import('./utils/app-installation.js').AppInstallation;
   booted?: boolean;
 }
 
@@ -355,6 +356,7 @@ export interface ActionConditionResult {
 }
 
 export interface ActionExecutionResult {
+  device_readiness?: import('./contracts/device-readiness.js').DeviceReadiness;
   action_id: string;
   timestamp: string;
   action_type: string;

package/src/utils/android/utils.ts

@@ -2,7 +2,8 @@ import { DeviceInfo } from "../../types.js"
 import { promises as fsPromises } from 'fs'
 import path from 'path'
 export { findInPath, resolveAdbCmd, getAdbCmd, ensureAdbAvailable, getAdbArgs, getAdbTimeout, type SpawnOptionsWithTimeout, execAdb, spawnAdb } from './commands.js'
-import { execAdb } from './commands.js'
+import { execAdb, getAdbCmd } from './commands.js'
+import { installationFields, probeInstallation } from '../app-installation.js'
 export { type GradleEnvOverrides, mergeEnv, prepareGradle } from './gradle.js'
 export { parseBounds, getCenter, parseBooleanAttr, parseNumberAttr, normalizeClassName, inferAndroidRole, buildAndroidSelectorConfidence, buildAndroidSelector, buildAndroidSemantic, isSliderLikeAndroid, extractAndroidState, traverseNode } from './ui-tree.js'
 export { parseLogLine } from './logs.js'
@@ -82,15 +83,12 @@ export async function listAndroidDevices(appId?: string): Promise<DeviceInfo[]>
           execAdb(['shell', 'getprop', 'ro.kernel.qemu'], serial).catch(() => '0')
         ])
         const simulator = simOutput === '1'
-        let appInstalled = false
-        if (appId) {
-          try {
-            const pm = await execAdb(['shell', 'pm', 'path', appId], serial)
-            appInstalled = !!(pm && pm.includes('package:'))
-          } catch (e: unknown) { console.debug(`[listAndroidDevices] pm check failed for ${serial}: ${String(e)}`); appInstalled = false }
-        }
-        return { platform: 'android', id: serial, osVersion, model, simulator, appInstalled } as DeviceInfo & { appInstalled?: boolean }
-      } catch (e: unknown) { console.debug(`[listAndroidDevices] failed gathering metadata for ${serial}: ${String(e)}`); return { platform: 'android', id: serial, osVersion: '', model: '', simulator: false, appInstalled: false } as DeviceInfo & { appInstalled?: boolean } }
+        const check = await probeInstallation(getAdbCmd(), serial, appId, 'android-current-user', deviceLines.find(line => line.split(/\s+/)[0] === serial)?.split(/\s+/)[1] === 'device')
+        return { platform: 'android', id: serial, osVersion, model, simulator, ...installationFields(check) } as DeviceInfo
+      } catch {
+        const check = await probeInstallation(getAdbCmd(), serial, appId, 'android-current-user', false)
+        return { platform: 'android', id: serial, osVersion: '', model: '', simulator: false, ...installationFields(check) } as DeviceInfo
+      }
     }))
 
     return infos

package/src/utils/app-installation.ts

@@ -0,0 +1,73 @@
+import { execFile } from 'node:child_process'
+import { execCmd } from './exec.js'
+import { remainingBudget } from './operation-budget.js'
+
+export interface AppInstallation {
+  status: 'installed' | 'absent' | 'unknown'
+  appId: string | null
+  deviceId: string
+  scope: 'android-current-user' | 'ios-simulator'
+  checkedAt: string | null
+  reason?: 'APP_ID_NOT_PROVIDED' | 'DEVICE_UNAVAILABLE' | 'CHECK_FAILED' | 'UNRECOGNIZED_RESPONSE'
+}
+export function validAppId(appId: string) { return /^[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*$/.test(appId) }
+export function installationContext(deviceId: string, appId: string | undefined, scope: AppInstallation['scope']): AppInstallation {
+  return { status: 'unknown', appId: appId ?? null, deviceId, scope, checkedAt: null, reason: appId === undefined ? 'APP_ID_NOT_PROVIDED' : 'CHECK_FAILED' }
+}
+export function installationFields(appInstallation: AppInstallation) {
+  return { appInstallation, ...(appInstallation.status === 'unknown' ? {} : { appInstalled: appInstallation.status === 'installed' }) }
+}
+export async function probeInstallation(command: string, deviceId: string, appId: string | undefined, scope: AppInstallation['scope'], available = true): Promise<AppInstallation> {
+  const result = installationContext(deviceId, appId, scope)
+  if (appId === undefined || !validAppId(appId)) return result
+  if (!available) return { ...result, reason: 'DEVICE_UNAVAILABLE' }
+  try {
+    return await runProbe(command, result)
+  } catch {
+    return { ...result, checkedAt: new Date().toISOString(), reason: 'CHECK_FAILED' }
+  }
+}
+async function runProbe(command: string, context: AppInstallation): Promise<AppInstallation> {
+  const android = context.scope === 'android-current-user'
+  const started = performance.now()
+  const timeout = remainingBudget(5000)
+  const args = android ? ['-s', context.deviceId, 'shell', 'pm', 'path', context.appId!] : ['simctl', 'listapps', context.deviceId]
+  const output = await execCmd(command, args, { timeout })
+  const result = { ...context, checkedAt: new Date().toISOString() }
+  if (output.exitCode !== 0) {
+    if (android && !output.stdout && !output.stderr) return confirmAndroidAbsence(command, result, Math.max(1, timeout - (performance.now() - started)))
+    return { ...result, reason: 'CHECK_FAILED' }
+  }
+  let status: AppInstallation['status']
+  if (android) {
+    const lines = output.stdout.trim().split('\n').filter(Boolean)
+    if (lines.some(line => !/^package:\/\S+$/.test(line.trim()))) return { ...result, reason: 'UNRECOGNIZED_RESPONSE' }
+    status = lines.length ? 'installed' : 'absent'
+  } else {
+    try {
+      const budget = remainingBudget(Math.max(1, Math.floor(timeout - (performance.now() - started))))
+      if (performance.now() - started >= timeout) return { ...result, reason: 'CHECK_FAILED' }
+      const json = await new Promise<string>((resolve, reject) => {
+        const child = execFile('/usr/bin/plutil', ['-convert', 'json', '-o', '-', '--', '-'], { timeout: budget, killSignal: 'SIGKILL', maxBuffer: 16 * 1024 * 1024 }, (error, stdout) => error ? reject(error) : resolve(stdout))
+        child.stdin?.on('error', reject)
+        child.stdin?.end(output.stdout)
+      })
+      const apps: unknown = JSON.parse(json)
+      if (!apps || typeof apps !== 'object' || Array.isArray(apps)) return { ...result, reason: 'UNRECOGNIZED_RESPONSE' }
+      if (Object.values(apps).some(value => !value || typeof value !== 'object' || Array.isArray(value))) return { ...result, reason: 'UNRECOGNIZED_RESPONSE' }
+      status = Object.hasOwn(apps, context.appId!) ? 'installed' : 'absent'
+    } catch { return { ...result, reason: 'UNRECOGNIZED_RESPONSE' } }
+  }
+  const { reason: _reason, ...confirmed } = result
+  return { ...confirmed, status }
+}
+
+async function confirmAndroidAbsence(command: string, context: AppInstallation, timeout: number): Promise<AppInstallation> {
+  const output = await execCmd(command, ['-s', context.deviceId, 'shell', 'pm', 'list', 'packages', context.appId!], { timeout })
+  const result = { ...context, checkedAt: new Date().toISOString() }
+  if (output.exitCode !== 0) return { ...result, reason: 'CHECK_FAILED' }
+  const lines = output.stdout.split('\n').map(line => line.trim()).filter(Boolean)
+  if (lines.some(line => !/^package:[A-Za-z0-9_.-]+$/.test(line))) return { ...result, reason: 'UNRECOGNIZED_RESPONSE' }
+  const { reason: _reason, ...confirmed } = result
+  return { ...confirmed, status: lines.includes(`package:${context.appId}`) ? 'installed' : 'absent' }
+}

package/src/utils/benchmark-metrics.ts

@@ -0,0 +1,42 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { randomUUID } from 'node:crypto'
+
+interface Span { stage: string; start_ms: number; end_ms: number }
+interface Measurement { id: string; started: number; spans: Span[] }
+const measurement = new AsyncLocalStorage<Measurement>()
+
+// Private benchmark diagnostics: no arguments, device IDs or response contents.
+export function recordBenchmarkSpan(stage: string, duration: number) {
+  const current = measurement.getStore()
+  if (!current) return
+  const end = performance.now() - current.started
+  current.spans.push({ stage, start_ms: Math.max(0, end - duration), end_ms: end })
+}
+
+export async function benchmarkSubprocess<T>(operation: () => Promise<T>): Promise<T> {
+  return benchmarkStage('subprocess_ms', operation)
+}
+
+export async function benchmarkStage<T>(stage: string, operation: () => Promise<T>): Promise<T> {
+  if (!measurement.getStore()) return operation()
+  const started = performance.now()
+  try { return await operation() }
+  finally { recordBenchmarkSpan(stage, performance.now() - started) }
+}
+
+export async function withBenchmarkRequest<T>(tool: string, operation: () => Promise<T>): Promise<T> {
+  if (process.env.MOBILE_DEBUG_MCP_LATENCY_METRICS !== '1') return operation()
+  const current: Measurement = { id: randomUUID(), started: performance.now(), spans: [] }
+  return measurement.run(current, async () => {
+    let completed = false
+    try {
+      const result = await operation()
+      completed = true
+      return result
+    } finally {
+      process.stderr.write(`${JSON.stringify({ event: 'latency_metric', request_id: current.id,
+        tool, handler_completed: completed, elapsed_ms: performance.now() - current.started,
+        spans: current.spans })}\n`)
+    }
+  })
+}

package/src/utils/exec.ts

@@ -1,10 +1,15 @@
 import { checkDebuggerGuard } from '../debugger/guard.js'
 import { remainingBudget } from './operation-budget.js'
 import { spawn } from 'child_process'
+import { benchmarkSubprocess } from './benchmark-metrics.js'
 
 export type ExecOptions = { timeout?: number; env?: NodeJS.ProcessEnv; cwd?: string; shell?: boolean }
 
 export async function execCmd(cmd: string, args: string[], opts: ExecOptions = {}): Promise<{ exitCode: number | null, stdout: string, stderr: string }> {
+  return benchmarkSubprocess(() => execute(cmd, args, opts))
+}
+
+async function execute(cmd: string, args: string[], opts: ExecOptions): Promise<{ exitCode: number | null, stdout: string, stderr: string }> {
   const { env, cwd, shell } = opts
   const timeout = remainingBudget(opts.timeout ?? 0)
   return new Promise((resolve, reject) => {

package/src/utils/ios/utils.ts

@@ -1,3 +1,4 @@
+import { installationFields, probeInstallation } from '../app-installation.js'
 import { checkDebuggerGuard } from '../../debugger/guard.js'
 import { remainingBudget } from '../operation-budget.js'
 import { execFile, spawn, execSync, spawnSync } from "child_process"
@@ -282,16 +283,9 @@ export async function listIOSDevices(appId?: string): Promise<DeviceInfo[]> {
                 booted: bootedSet.has(device.udid)
               }
 
-              if (appId) {
-                // check if installed
-                const p = execCommand(['simctl', 'get_app_container', device.udid, appId, 'data'], device.udid)
-                  .then(() => { info.appInstalled = true })
-                  .catch(() => { info.appInstalled = false })
-                  .then(() => { out.push(info) })
-                checks.push(p)
-              } else {
-                out.push(info)
-              }
+              out.push(info)
+              checks.push(probeInstallation(getXcrunCmd(), device.udid, appId, 'ios-simulator', info.booted === true)
+                .then(check => { Object.assign(info, installationFields(check)) }))
             }
           }