mobile-debug-mcp 0.35.0 → 0.37.0

package/dist/server/handlers/journey.js

@@ -1,6 +1,8 @@
+import { observeDeviceReadiness } from '../../observe/device-readiness.js';
+import { benchmarkStage } from '../../utils/benchmark-metrics.js';
 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';
@@ -25,23 +27,27 @@ async function assertStep(step, platform, deviceId) {
         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, operation) {
+    return s.input.responseMode === 'compact' ? withJourneyStepEvidence(operation) : operation();
+}
 async function executeStep(s, step, covered) {
     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') {
-            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 === '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)));
+            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, step, result, covered, success) {
@@ -69,24 +75,16 @@ function lightVerification(s, step, result, covered, success) {
     }
     s.pendingLightStep = null;
 }
-function compactAssertion(result, success) {
-    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, step, next) {
     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) {
-    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;
         }
@@ -95,7 +93,9 @@ async function runSteps(s) {
             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';
@@ -105,8 +105,6 @@ async function runSteps(s) {
             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/dist/server/handlers/observe.js

@@ -1,4 +1,5 @@
 import { ToolsObserve } from '../../observe/index.js';
+import { benchmarkStage } from '../../utils/benchmark-metrics.js';
 import { withObservationContext } from '../../observe/performance-metrics.js';
 import { getBooleanArg, getNumberArg, getStringArg, requireStringArg, wrapResponse } from '../common.js';
 export async function handleGetLogs(args) {
@@ -25,7 +26,7 @@ export async function handleCaptureScreenshot(args) {
     const platform = requireStringArg(args, 'platform');
     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 = [

package/dist/server/handlers/tool-handlers.js

@@ -1,6 +1,10 @@
+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 { 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';
@@ -32,6 +36,7 @@ export const toolHandlers = {
             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,
@@ -71,28 +76,36 @@ export const toolHandlers = {
 for (const name of ['capture_screenshot', 'get_ui_tree', 'get_screen_fingerprint', 'capture_debug_snapshot', 'get_logs', 'read_log_stream', 'run_journey', 'adjust_control']) {
     toolHandlers[name] = correlatedHandler(name, toolHandlers[name], name === 'adjust_control', name === 'run_journey');
 }
+function resolveGuardDevice(name, args) {
+    const platform = args.platform;
+    const deviceId = args.deviceId;
+    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, args, handler, addTiming) {
-    return withResolvedDevice(device, () => withDebuggerGuard('android', device.id, async () => {
-        const before = debuggerSessions.paused(device.id);
+    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 });
+            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;
         try {
             response = await handler(args);
         }
         catch (error) {
-            if (!debuggerSessions.paused(device.id))
+            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);
             }
         }
@@ -100,14 +113,15 @@ async function dispatchGuarded(device, args, handler, addTiming) {
     }));
 }
 function attachPausedObservation(name, args, response) {
-    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 });
             }
@@ -125,7 +139,7 @@ export async function handleToolCall(name, args = {}, signal) {
     const measured = {};
     const addTiming = (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 response;
+            return finalizeCompactInteraction(name, args, response);
         const item = response.content.find(item => item.type === 'text');
         if (item?.text) {
             try {
@@ -135,15 +149,15 @@ export async function handleToolCall(name, args = {}, signal) {
             }
             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 });
+            if (guarded && (debuggerSessions.hasActiveSessions() || iosDebuggerSessions.hasActiveSessions())) {
+                const device = await resolveGuardDevice(name, args);
                 return dispatchGuarded(device, args, handler, addTiming);
             }
             const response = await handler(args);
@@ -152,7 +166,7 @@ export async function handleToolCall(name, args = {}, signal) {
         }
         catch (error) {
             if (error instanceof TraceError)
-                return { ...wrapResponse({ error: { tool: name, code: error.code, message: error.message } }), isError: true };
+                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/dist/server/schemas/debugger-schema.js

@@ -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) {
@@ -35,12 +36,14 @@ function jsonField(schema) {
     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', 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/dist/server/schemas/interaction-diagnostics.js

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+export const diagnosticsSchema = z.object({ sessionId: z.string().uuid(), resultId: z.string().uuid() }).strict();
+export const interactionDiagnosticsTool = {
+    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/dist/server/schemas/system-trace-schema.js

@@ -1,17 +1,22 @@
 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) => 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) => ({ 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', 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', 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', 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', 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', additionalProperties: false, required: ['traceId'], properties: { traceId: { type: 'string', format: 'uuid' } } }
     }))
 ];

package/dist/server/tool-definitions.js

@@ -1,3 +1,4 @@
+import { interactionDiagnosticsTool } from './schemas/interaction-diagnostics.js';
 import { verificationModeJson, responseModeJson } from '../contracts/execution-controls.js';
 import { manageTools } from './definitions/manage.js';
 import { observeTools } from './definitions/observe.js';
@@ -51,9 +52,10 @@ const baseOrder = [
 export const toolDefinitions = [
     ...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', additionalProperties: false, required: ['platform'], properties: {
                 ...readinessPropertiesJson,
                 timeoutMs: { ...readinessPropertiesJson.timeoutMs, default: name === 'get_app_readiness' ? 15000 : 30000 },
@@ -67,12 +69,12 @@ 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.';
+        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'] };
@@ -83,12 +85,13 @@ 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' },
@@ -112,6 +115,8 @@ 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', additionalProperties: false, required: ['sessionId', 'actionId'], properties: {

package/dist/server-core.js

@@ -3,10 +3,11 @@ import { ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ReadRes
 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() {
     const server = new Server(serverInfo, {
@@ -29,7 +30,9 @@ export function createServer() {
     }));
     server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
         const { name, arguments: args } = request.params;
-        return handleToolCall(name, args, extra.signal);
+        const operation = () => handleToolCall(name, args, 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/dist/server.js

@@ -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';
@@ -7,7 +7,7 @@ import { getSystemStatus } from './system/index.js';
 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)));
 }
 const transport = new StdioServerTransport();
@@ -19,10 +19,10 @@ 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) {
+        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.map(s => s.cleanup));
+            console.error('Debugger shutdown cleanup incomplete', [...debuggers, ...iosDebuggers].map(s => s.cleanup));
         }
         if (remaining.length) {
             exitCode = 1;

package/dist/system/android.js

@@ -1,3 +1,4 @@
+import { probeInstallation, validAppId } from '../utils/app-installation.js';
 import { execSync } from 'child_process';
 import { ensureAdbAvailable } from '../utils/android/utils.js';
 export async function checkAndroid() {
@@ -9,6 +10,8 @@ export async function checkAndroid() {
     let logsAvailable = false;
     let envValid = false;
     let appInstalled = undefined;
+    let appInstallations = [];
+    let targets = [];
     try {
         const adbCheck = ensureAdbAvailable();
         const adbCmd = adbCheck.adbCmd || 'adb';
@@ -19,6 +22,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;
         }
@@ -43,15 +47,15 @@ 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) {
         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, issues) {
     const lines = out.split('\n').map(l => l.trim()).filter(Boolean);
@@ -73,16 +77,16 @@ function parseDevices(out, issues) {
         issues.push(`${stateCounts['offline']} device(s) offline`);
     return { devices, deviceStates };
 }
-function probeAppInstalled(adbCmd, pkg, issues) {
-    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) {
-        console.debug('[get_system_status] pm check failed: ' + String(e));
-        return false;
+function installationSummary(checks) {
+    return checks.length === 1 && checks[0].status !== 'unknown' ? checks[0].status === 'installed' : undefined;
+}
+function reportInstallations(checks, pkg, issues) {
+    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/dist/system/index.js

@@ -40,7 +40,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/dist/utils/android/utils.js

@@ -1,7 +1,8 @@
 import { promises as fsPromises } from 'fs';
 import path from 'path';
 export { findInPath, resolveAdbCmd, getAdbCmd, ensureAdbAvailable, getAdbArgs, getAdbTimeout, execAdb, spawnAdb } from './commands.js';
-import { execAdb } from './commands.js';
+import { execAdb, getAdbCmd } from './commands.js';
+import { installationFields, probeInstallation } from '../app-installation.js';
 export { 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';
@@ -79,22 +80,12 @@ export async function listAndroidDevices(appId) {
                     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) {
-                        console.debug(`[listAndroidDevices] pm check failed for ${serial}: ${String(e)}`);
-                        appInstalled = false;
-                    }
-                }
-                return { platform: 'android', id: serial, osVersion, model, simulator, appInstalled };
+                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) };
             }
-            catch (e) {
-                console.debug(`[listAndroidDevices] failed gathering metadata for ${serial}: ${String(e)}`);
-                return { platform: 'android', id: serial, osVersion: '', model: '', simulator: false, appInstalled: false };
+            catch {
+                const check = await probeInstallation(getAdbCmd(), serial, appId, 'android-current-user', false);
+                return { platform: 'android', id: serial, osVersion: '', model: '', simulator: false, ...installationFields(check) };
             }
         }));
         return infos;