mobile-debug-mcp 0.35.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,7 +1,11 @@
+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'
 import { debuggerContracts } from '../schemas/debugger-schema.js'
-import { debuggerSessions } from '../../debugger/sessions.js'
+import { debuggerSessions, iosDebuggerSessions } from '../../debugger/sessions.js'
 import { withDebuggerGuard, guardDispatched } from '../../debugger/guard.js'
 import { TraceError } from '../../observe/system-trace.js'
 import { systemTraceTools } from '../schemas/system-trace-schema.js'
@@ -40,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,
@@ -81,23 +86,32 @@ for (const name of ['capture_screenshot', 'get_ui_tree', 'get_screen_fingerprint
   toolHandlers[name] = correlatedHandler(name, toolHandlers[name], name === 'adjust_control', name === 'run_journey')
 }
 
+function resolveGuardDevice(name: string, args: ToolCallArgs) {
+  const platform = args.platform as 'android' | 'ios' | undefined
+  const deviceId = args.deviceId as string | undefined
+  const stored = name === 'tap_element' && typeof args.elementId === 'string'
+    ? ToolsInteract.getResolvedElementTarget(args.elementId, platform, deviceId) : null
+  return resolveTargetDevice(stored ?? { platform: platform === 'ios' ? 'ios' : 'android', deviceId })
+}
+
 async function dispatchGuarded(device: DeviceInfo, args: ToolCallArgs, handler: ToolHandler, addTiming: (response: ToolCallResult) => ToolCallResult) {
-  return withResolvedDevice(device, () => withDebuggerGuard('android', device.id, async () => {
-    const before = debuggerSessions.paused(device.id)
-    if (before) return wrapResponse({ success: false, failure_code: 'DEBUGGER_PAUSED', delivery_status: 'not_delivered', dispatch_started: false, debugger: before })
+  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 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 (!debuggerSessions.paused(device.id)) throw error
+      if (!sessions.paused(device.id)) throw error
       response = wrapResponse({ success: false })
     }
-    const pause = debuggerSessions.paused(device.id)
+    const pause = sessions.paused(device.id)
     if (pause) {
       const item = response.content.find(item => item.type === 'text')
       if (item?.text) {
         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)
       }
     }
@@ -106,14 +120,15 @@ async function dispatchGuarded(device: DeviceInfo, args: ToolCallArgs, handler:
 }
 
 function attachPausedObservation(name: string, args: ToolCallArgs, response: ToolCallResult) {
-  if (['capture_screenshot', 'get_ui_tree', 'get_screen_fingerprint', 'capture_debug_snapshot', 'get_logs', 'get_current_screen', 'read_log_stream'].includes(name) && args.platform !== 'ios') {
+  if (['capture_screenshot', 'get_ui_tree', 'get_screen_fingerprint', 'capture_debug_snapshot', 'get_logs', 'get_current_screen', 'read_log_stream'].includes(name)) {
     const item = response.content.find(item => item.type === 'text')
     if (item?.text) {
       try {
         const payload = JSON.parse(item.text)
         const device = payload.device ?? payload.evidence?.device
         const id = device?.id ?? args.deviceId
-        const pause = id && device?.platform !== 'ios' ? debuggerSessions.paused(String(id)) : null
+        const sessions = (device?.platform ?? args.platform) === 'ios' ? iosDebuggerSessions : debuggerSessions
+        const pause = id ? sessions.paused(String(id)) : null
         if (pause) item.text = JSON.stringify({ ...payload, debugger: pause })
       } catch { /* Non-JSON observation */ }
     }
@@ -128,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 {
@@ -137,21 +152,21 @@ 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 {
       if (!systemTraceToolNames.has(name)) validateExpectedState(name, args)
       const guarded = ['start_app', 'terminate_app', 'restart_app', 'reset_app_data', 'install_app', 'build_and_install', 'tap', 'tap_element', 'swipe', 'scroll_to_element', 'type_text', 'press_back', 'adjust_control', 'run_journey', 'wait_for_ui', 'wait_for_ui_change', 'wait_for_screen_change', 'expect_screen', 'expect_element_visible', 'expect_state'].includes(name)
-      if (guarded && args.platform !== 'ios' && debuggerSessions.hasActiveSessions()) {
-        const device = await resolveTargetDevice({ platform: 'android', deviceId: args.deviceId as string | undefined })
+      if (guarded && (debuggerSessions.hasActiveSessions() || iosDebuggerSessions.hasActiveSessions())) {
+        const device = await resolveGuardDevice(name, args)
         return dispatchGuarded(device, args, handler, addTiming)
       }
       const response = await handler(args)
       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/debugger-schema.ts

@@ -2,21 +2,22 @@ import { z } from 'zod'
 const text = z.string().min(1).max(512)
 const integer = z.number().int().safe().positive()
 const timeout = z.number().int().min(100).max(30000)
-const target = { platform: z.literal('android'), deviceId: text, appId: text.regex(/^[A-Za-z][\w]*(?:\.[A-Za-z][\w]*)+$/), processId: integer.optional() }
+const iosUdid = /^[A-Fa-f0-9]{8}(?:-[A-Fa-f0-9]{4}){3}-[A-Fa-f0-9]{12}$/
+const target = { platform: z.enum(['android', 'ios']), deviceId: text, appId: text.regex(/^[A-Za-z][\w-]*(?:\.[A-Za-z][\w-]*)+$/), processId: integer.optional() }
 const session = { debugSessionId: text }
 const stop = { ...session, stopId: text }
 const specs = {
-  get_debugger_capabilities: { fields: target, command: 'capabilities', description: 'Probe optional Android JDK/JDWP prerequisites and matching running debuggable processes; does not attach.' },
-  attach_debugger: { fields: target, command: 'attach', description: 'Attach an owned Android JDI session. Requires an explicit device and debuggable app; choose processId when ambiguous. Stops suspend all app threads. Auto-detach: 60s paused, 5m idle, 30m total.' },
+  get_debugger_capabilities: { fields: target, command: 'capabilities', description: 'Probe optional platform debugger prerequisites and matching running debuggable processes; does not attach.' },
+  attach_debugger: { fields: target, command: 'attach', description: 'Attach an owned Android JDI or iOS simulator LLDB session. Requires an explicit device and debuggable app; choose processId when ambiguous. Stops suspend all app threads. Auto-detach: 60s paused, 5m idle, 30m total.' },
   get_debugger_state: { fields: session, command: 'state', description: 'Read debugger state, current stop and breakpoint/cleanup status.' },
-  set_debugger_breakpoint: { fields: { ...session, className: text.regex(/^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/), line: integer }, command: 'set', description: 'Set an exact binary-class and executable-source-line breakpoint; unloaded classes remain pending. No silent line relocation.' },
+  set_debugger_breakpoint: { fields: { ...session, className: text.regex(/^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/).optional(), sourceFile: text.regex(/^\/[^\0\r\n]+$/).optional(), line: integer }, command: 'set', description: 'Set an exact source breakpoint: Android className or iOS absolute sourceFile (exactly one), plus line; unloaded classes/images remain pending. No silent line relocation.' },
   remove_debugger_breakpoint: { fields: { ...session, breakpointId: text }, command: 'remove', description: 'Remove an owned breakpoint; repeated removal succeeds.' },
   wait_for_debugger_event: { fields: { ...session, afterSequence: z.number().int().safe().min(0).optional() }, command: 'events', description: 'Wait for bounded debugger events after a sequence cursor. Empty timeout does not affect execution; overflow is explicit.' },
   get_debugger_stack: { fields: { ...stop, threadId: text, offset: z.number().int().min(0).max(999).optional(), limit: z.number().int().min(1).max(100).optional() }, command: 'stack', description: 'Read bounded stack frames for a stopped thread; IDs expire on resume.' },
-  get_debugger_locals: { fields: { ...stop, frameId: text }, command: 'locals', description: 'Read at most 100 shallow locals. Sensitive values returned only on request; strings truncate at 256 characters. No evaluation or field traversal.' },
+  get_debugger_locals: { fields: { ...stop, frameId: text }, command: 'locals', description: 'Read at most 100 shallow locals. Sensitive values returned only on request; strings truncate at 256 characters; iOS aggregates return type summaries. No evaluation or field traversal.' },
   step_debugger: { fields: { ...stop, threadId: text, kind: z.enum(['into', 'over', 'out']) }, command: 'step', description: 'Acknowledge one-shot line stepping and resume. Wait for a subsequent stop event separately.' },
   resume_debugger: { fields: stop, command: 'resume', description: 'Resume owned debugger suspension and immediately expire stopped references.' },
-  detach_debugger: { fields: session, command: 'detach', description: 'Dispose the owned debugger connection, release owned suspension and remove its exact forward. Idempotent; retries incomplete cleanup.' }
+  detach_debugger: { fields: session, command: 'detach', description: 'Dispose the owned debugger connection, release owned suspension and remove its owned transport. Idempotent; retries incomplete cleanup.' }
 }
 // Derive JSON schemas and runtime validation from the same small Zod field vocabulary.
 function jsonField(schema: z.ZodType): Record<string, unknown> {
@@ -31,12 +32,14 @@ function jsonField(schema: z.ZodType): Record<string, unknown> {
   throw new Error('Unsupported debugger field schema')
 }
 export const debuggerContracts = Object.fromEntries(Object.entries(specs).map(([name, spec]) => [name, {
-  ...spec, schema: z.object({ ...spec.fields, responseMode: z.enum(['compact', 'debug']).default('debug'), timeoutMs: timeout.default(name === 'wait_for_debugger_event' ? 1000 : 10000) }).strict()
+  ...spec, schema: z.object({ ...spec.fields, responseMode: z.enum(['compact', 'debug']).default('debug'), timeoutMs: timeout.default(name === 'wait_for_debugger_event' ? 1000 : 10000) }).strict().refine(a => name !== 'set_debugger_breakpoint' || (('className' in a && a.className !== undefined) !== ('sourceFile' in a && a.sourceFile !== undefined)), { message: 'Exactly one breakpoint source selector is required' }).refine(a => !('platform' in a) || a.platform !== 'ios' || ('deviceId' in a && typeof a.deviceId === 'string' && iosUdid.test(a.deviceId)), { message: 'iOS requires an explicit simulator UDID' })
 }]))
 export const debuggerTools = Object.entries(debuggerContracts).map(([name, spec]) => ({
   name, description: spec.description,
   inputSchema: {
     type: 'object' as const, additionalProperties: false,
+    ...(['get_debugger_capabilities', 'attach_debugger'].includes(name) ? { allOf: [{ if: { properties: { platform: { const: 'ios' } } }, then: { properties: { deviceId: { pattern: iosUdid.source } } } }] } : {}),
+    ...(name === 'set_debugger_breakpoint' ? { oneOf: [{ required: ['className'], not: { required: ['sourceFile'] } }, { required: ['sourceFile'], not: { required: ['className'] } }] } : {}),
     required: Object.entries(spec.fields).filter(([, field]) => !field.isOptional()).map(([key]) => key),
     properties: { responseMode: { type: 'string', enum: ['compact', 'debug'], default: 'debug' }, ...Object.fromEntries(Object.entries(spec.fields).map(([key, field]) => [key, jsonField(field)])), timeoutMs: { type: 'integer', minimum: 100, maximum: 30000, default: name === 'wait_for_debugger_event' ? 1000 : 10000 } }
   }

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/schemas/system-trace-schema.ts

@@ -1,17 +1,23 @@
 import { z } from 'zod'
-const target = { platform: z.enum(['android', 'ios']), deviceId: z.string().min(1).optional() }
-export const traceTargetSchema = z.object(target).strict()
-export const traceStartSchema = z.object({ ...target, durationMs: z.number().int().min(1000).max(120000).default(30000) }).strict()
+const target = { platform: z.enum(['android', 'ios']), deviceId: z.string().min(1).optional(), appId: z.string().regex(/^[a-zA-Z0-9._-]+$/).optional(), template: z.enum(['System Trace', 'Time Profiler', 'Animation Hitches', 'Hangs']).optional() }
+const validTarget = (value: { platform: string; deviceId?: string; appId?: string; template?: string }) =>
+  value.platform === 'ios' ? !!value.deviceId : value.appId === undefined && value.template === undefined
+export const traceTargetSchema = z.object(target).strict().refine(validTarget)
+export const traceStartSchema = z.object({ ...target, durationMs: z.number().int().min(1000).max(120000).default(30000) }).strict().refine(validTarget).refine(value => value.platform !== 'ios' || !!value.appId)
 export const traceControlSchema = z.object({ traceId: z.string().uuid() }).strict()
-const properties = { platform: { type: 'string', enum: ['android', 'ios'] }, deviceId: { type: 'string', minLength: 1 } }
+const properties = { platform: { type: 'string', enum: ['android', 'ios'] }, deviceId: { type: 'string', minLength: 1 }, appId: { type: 'string', minLength: 1, pattern: '^[a-zA-Z0-9._-]+$', description: 'iOS only: running development app bundle identifier; required for iOS start.' }, template: { type: 'string', enum: ['System Trace', 'Time Profiler', 'Animation Hitches', 'Hangs'], description: 'iOS only. Default Time Profiler; initial simulator support is Time Profiler only.' } }
+const platformRules = (start: boolean) => ({ oneOf: [
+  { properties: { platform: { const: 'android' } }, not: { anyOf: [{ required: ['appId'] }, { required: ['template'] }] } },
+  { properties: { platform: { const: 'ios' } }, required: start ? ['deviceId', 'appId'] : ['deviceId'] }
+] })
 export const systemTraceTools = [
-  { name: 'get_system_trace_capabilities', description: 'Probe Android Perfetto prerequisites without recording. Device-wide system tracing is optional; iOS is unsupported.',
-    inputSchema: { type: 'object' as const, additionalProperties: false, required: ['platform'], properties } },
-  { name: 'start_system_trace', description: 'Start bounded Android Perfetto recording, returning an owned trace_id. Run an existing journey with systemTraceId, then stop to retrieve a local artifact or cancel to discard. Device-wide traces may contain sensitive system annotations; no upload.',
-    inputSchema: { type: 'object' as const, additionalProperties: false, required: ['platform'], properties: { ...properties, durationMs: { type: 'integer', minimum: 1000, maximum: 120000, default: 30000 } } } },
+  { name: 'get_system_trace_capabilities', description: 'Probe Android Perfetto or iOS Instruments prerequisites without recording. iOS requires explicit booted simulator deviceId; reports template matrix and unknown profiling permissions.',
+    inputSchema: { type: 'object' as const, additionalProperties: false, required: ['platform'], properties, ...platformRules(false) } },
+  { name: 'start_system_trace', description: 'Start bounded Android Perfetto or iOS simulator Time Profiler recording, returning an owned trace_id after readiness. iOS requires explicit deviceId and running appId. Run an existing journey with systemTraceId, then stop to retrieve a local artifact or cancel to discard. Traces can contain sensitive system metadata, logs and paths; local user-managed retention, no upload.',
+    inputSchema: { type: 'object' as const, additionalProperties: false, required: ['platform'], properties: { ...properties, durationMs: { type: 'integer', minimum: 1000, maximum: 120000, default: 30000 } }, ...platformRules(true) } },
   ...['get_system_trace_status', 'stop_system_trace', 'cancel_system_trace'].map(name => ({ name,
     description: name === 'get_system_trace_status' ? 'Reconcile an owned trace and retrieve its state; finalise duration-completed capture.' :
-      name === 'stop_system_trace' ? 'Stop owned capture gracefully and retrieve a local Perfetto artifact. Retry after a transfer/cleanup failure.' : 'Stop owned capture and discard partial files. Already completed local artifacts are retained.',
+      name === 'stop_system_trace' ? 'Stop owned capture gracefully and retrieve a local Perfetto file or validated Instruments .trace bundle. Retry after a transfer/cleanup failure.' : 'Stop owned capture and discard partial files. Already completed local artifacts are retained.',
     inputSchema: { type: 'object' as const, additionalProperties: false, required: ['traceId'], properties: { traceId: { 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.35.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

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { debuggerSessions } from './debugger/sessions.js'
+import { debuggerSessions, iosDebuggerSessions } from './debugger/sessions.js'
 import { systemTraces } from './observe/system-trace.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { createServer } from './server-core.js'
@@ -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)))
 }
 
@@ -22,8 +22,8 @@ async function shutdown() {
   const deadline = setTimeout(() => { console.error('System trace shutdown cleanup timed out; owned device captures remain duration-bounded.'); process.exit(1) }, 10000)
   let exitCode = 0
   try {
-    const [remaining, debuggers] = await Promise.all([systemTraces.shutdown(), debuggerSessions.shutdown()])
-    if (debuggers.length) { exitCode = 1; console.error('Debugger shutdown cleanup incomplete', debuggers.map(s => s.cleanup)) }
+    const [remaining, debuggers, iosDebuggers] = await Promise.all([systemTraces.shutdown(), debuggerSessions.shutdown(), iosDebuggerSessions.shutdown()])
+    if ((debuggers.length + iosDebuggers.length)) { exitCode = 1; console.error('Debugger shutdown cleanup incomplete', [...debuggers, ...iosDebuggers].map(s => s.cleanup)) }
     if (remaining.length) {
       exitCode = 1
       console.error('System trace shutdown cleanup incomplete:', remaining.map(s => ({ trace_id: s.trace_id, device: s.device, cleanup: s.cleanup })))

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;