mobile-debug-mcp 0.31.0 → 0.32.1

package/dist/server/tool-handlers.js

@@ -1,19 +1,140 @@
+import { measure, withTiming } from '../utils/timing.js';
+import { randomUUID } from 'node:crypto';
+import { runWithBudget } from '../utils/operation-budget.js';
+import { journeySchema, tapElementControlsSchema } from './journey-schema.js';
+import { resolveTargetDevice, withResolvedDevice } from '../utils/resolve-device.js';
 import { AndroidManage, iOSManage, ToolsManage } from '../manage/index.js';
 import { ToolsInteract } from '../interact/index.js';
 import { ToolsObserve } from '../observe/index.js';
 import { classifyActionOutcome } from '../interact/classify.js';
 import { ToolsNetwork } from '../network/index.js';
 import { getSystemStatus } from '../system/index.js';
+import { recordObservationConsumer, recordObservationEvent, withObservationContext } from '../observe/performance-metrics.js';
 import { buildActionExecutionResult, captureActionFingerprint, getArrayArg, getBooleanArg, getNumberArg, getObjectArg, getStringArg, inferGenericFailure, inferScrollFailure, requireBooleanArg, requireNumberArg, requireObjectArg, requireStringArg, wrapResponse, wrapToolError } from './common.js';
-async function handleStartApp(args) {
+function interactionControls(args) {
+    const verificationMode = getStringArg(args, 'verificationMode') ?? 'full';
+    const responseMode = getStringArg(args, 'responseMode') ?? 'debug';
+    if (!['none', 'light', 'full'].includes(verificationMode) || !['compact', 'debug'].includes(responseMode))
+        throw new Error('INVALID_ARGUMENT');
+    for (const key of ['verificationMode', 'responseMode'])
+        if (args[key] !== undefined && typeof args[key] !== 'string')
+            throw new Error('INVALID_ARGUMENT');
+    for (const key of ['actionTimeoutMs', 'verificationTimeoutMs'])
+        if (args[key] !== undefined && (typeof args[key] !== 'number' || !Number.isInteger(args[key])))
+            throw new Error('INVALID_ARGUMENT');
+    const actionTimeoutMs = getNumberArg(args, 'actionTimeoutMs');
+    const verificationTimeoutMs = getNumberArg(args, 'verificationTimeoutMs');
+    return { verificationMode, responseMode,
+        actionTimeoutMs: actionTimeoutMs === undefined ? undefined : Math.max(100, Math.min(30000, actionTimeoutMs)),
+        verificationTimeoutMs: verificationTimeoutMs === undefined ? 3000 : Math.max(100, Math.min(60000, verificationTimeoutMs)) };
+}
+function compactAction(result, verificationMode, started = true, stateDelta, totalMs = 0) {
+    return {
+        action_id: result.action_id,
+        action_type: result.action_type,
+        success: !!result.success,
+        lifecycle_state: result.success ? (verificationMode === 'full' ? result.lifecycle_state : 'pending_verification') : 'failed',
+        ...(result.failure_code ? { failure_code: result.failure_code } : {}),
+        ...(typeof result.retryable === 'boolean' ? { retryable: result.retryable } : {}),
+        delivery_status: result.success ? 'delivered' : (started ? 'unknown' : 'not_delivered'),
+        dispatch_started: started,
+        verification: { mode: verificationMode, status: result.success ? (verificationMode === 'none' ? 'not_requested' : verificationMode === 'light' ? 'observed' : (result.lifecycle_state === 'verified' ? 'verified' : 'observed')) : 'failed' },
+        ...(stateDelta ? { state_delta: stateDelta } : {}),
+        timing: { total_ms: totalMs }
+    };
+}
+function actionHandler(type, execute) {
+    return async (args) => {
+        const timing = {};
+        return withTiming(timing, async () => {
+            const started = performance.now();
+            const controls = interactionControls(args);
+            const budgetMs = controls.actionTimeoutMs ?? ({ start_app: 10000, restart_app: 15000, scroll_to_element: 10000 }[type] ?? 5000);
+            let dispatchStarted = false;
+            let result;
+            const dispatchWithBudget = (timeoutMs) => runWithBudget(timeoutMs, async (budget) => {
+                try {
+                    return payloadOf(await execute(args));
+                }
+                finally {
+                    dispatchStarted = budget.dispatchStarted;
+                }
+            });
+            try {
+                // Omitted controls retain the existing adapter budgets.
+                result = args._journey !== true && controls.verificationMode === 'full' && controls.responseMode === 'debug' && controls.actionTimeoutMs === undefined
+                    ? await dispatchWithBudget(Infinity) : await dispatchWithBudget(budgetMs);
+                if (result.success)
+                    dispatchStarted = true;
+            }
+            catch (error) {
+                if (controls.verificationMode === 'full' && controls.responseMode === 'debug' && controls.actionTimeoutMs === undefined && !/TIMEOUT|timed out/i.test(String(error)))
+                    return wrapToolError(type, error);
+                result = { success: false, failure_code: /TIMEOUT|timed out/i.test(String(error)) ? 'ACTION_TIMEOUT' : 'UNKNOWN', error: String(error) };
+            }
+            if (result.failure_code === 'TIMEOUT' || /ACTION_TIMEOUT|timeout/i.test(result.error ?? result.reason ?? result.details?.error ?? ''))
+                result.failure_code = 'ACTION_TIMEOUT';
+            if (result.failure_code === 'ACTION_TIMEOUT')
+                result.retryable = !dispatchStarted;
+            if (!result.success && typeof result.retryable !== 'boolean')
+                result.retryable = !dispatchStarted;
+            result.action_id ??= randomUUID();
+            result.action_type ??= type;
+            recordObservationEvent({
+                step_id: args._stepId,
+                action_type: type,
+                dispatch_ms: timing.dispatch_ms,
+                verification_mode: controls.verificationMode,
+                dispatch_started: dispatchStarted
+            });
+            let delta;
+            let observationAvailable = false;
+            if (result.success && controls.verificationMode === 'light') {
+                const verificationStarted = performance.now();
+                const tree = await withObservationContext({ stepId: args._stepId, purpose: 'verification' }, () => measure('post_observation_ms', () => runWithBudget(controls.verificationTimeoutMs, () => ToolsObserve.getUITreeHandler({ platform: args.platform ?? result.device?.platform, deviceId: args.deviceId ?? result.device?.id })))).catch(() => null);
+                observationAvailable = !!tree && !tree.error;
+                recordObservationEvent({
+                    verification_budget_ms: controls.verificationTimeoutMs,
+                    verification_elapsed_ms: performance.now() - verificationStarted,
+                    verification_outcome: observationAvailable ? 'observed' : 'unavailable',
+                    verification_budget_expired: !observationAvailable && performance.now() - verificationStarted >= controls.verificationTimeoutMs
+                });
+                if (observationAvailable && tree.device)
+                    delta = ToolsObserve.getLatestStateDelta(tree.device.platform, tree.device.id) ?? undefined;
+            }
+            const compact = compactAction(result, controls.verificationMode, dispatchStarted, delta, performance.now() - started);
+            if (result.success && controls.verificationMode === 'light' && !observationAvailable)
+                compact.verification.status = 'unavailable';
+            const evidence = {
+                ...compact,
+                ...(controls.verificationMode === 'light' ? { state_delta_available: !!delta } : {}),
+                ...(result.success && controls.verificationMode === 'light' && !observationAvailable ? { verification_diagnostic: { code: 'VERIFICATION_UNAVAILABLE', retryable: true } } : {})
+            };
+            return wrapResponse(controls.responseMode === 'compact' ? evidence : {
+                ...result, ...evidence, timing: { ...timing, total_ms: performance.now() - started },
+                effective_controls: { ...controls, actionTimeoutMs: args._journey !== true && controls.verificationMode === 'full' && controls.responseMode === 'debug' && controls.actionTimeoutMs === undefined ? null : budgetMs, timeout_bound: !(args._journey !== true && controls.verificationMode === 'full' && controls.responseMode === 'debug' && controls.actionTimeoutMs === undefined) }
+            }, controls.responseMode === 'debug');
+        });
+    };
+}
+const handleStartApp = actionHandler('start_app', executeStartApp);
+const handleRestartApp = actionHandler('restart_app', executeRestartApp);
+const handleTap = actionHandler('tap', executeTap);
+const handleTapElement = actionHandler('tap_element', executeTapElement);
+const handleSwipe = actionHandler('swipe', executeSwipe);
+const handleScrollToElement = actionHandler('scroll_to_element', executeScrollToElement);
+const handleTypeText = actionHandler('type_text', executeTypeText);
+const handlePressBack = actionHandler('press_back', executePressBack);
+async function executeStartApp(args) {
     const platform = requireStringArg(args, 'platform');
     const appId = requireStringArg(args, 'appId');
     const deviceId = getStringArg(args, 'deviceId');
-    const uiFingerprintBefore = await captureActionFingerprint(platform, deviceId);
+    const { verificationMode, actionTimeoutMs } = interactionControls(args);
+    const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null;
     ToolsNetwork.notifyActionStart();
-    const res = await (platform === 'android' ? new AndroidManage().startApp(appId, deviceId) : new iOSManage().startApp(appId, deviceId));
-    const uiFingerprintAfter = await captureActionFingerprint(platform, deviceId);
-    return wrapResponse(buildActionExecutionResult({
+    const res = await measure('dispatch_ms', () => (platform === 'android' ? new AndroidManage().startApp(appId, deviceId, actionTimeoutMs ?? (verificationMode === 'full' && getStringArg(args, 'responseMode') === undefined && args._journey !== true ? undefined : 10000)) : new iOSManage().startApp(appId, deviceId, verificationMode === 'full')));
+    const uiFingerprintAfter = verificationMode === 'full' ? await measure('post_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null;
+    const result = buildActionExecutionResult({
         actionType: 'start_app',
         sourceModule: 'server',
         device: res.device,
@@ -27,9 +148,11 @@ async function handleStartApp(args) {
             ...(typeof res.output === 'string' ? { output: res.output } : {}),
             ...(res.device ? { device_id: res.device.id } : {}),
             ...(typeof res.error === 'string' ? { error: res.error } : {}),
+            ...(res.diagnostics ? { diagnostics: res.diagnostics } : {}),
             ...(res.observedApp ? { observed_app: res.observedApp } : {})
         }
-    }));
+    });
+    return wrapResponse(result);
 }
 async function handleTerminateApp(args) {
     const platform = requireStringArg(args, 'platform');
@@ -39,15 +162,17 @@ async function handleTerminateApp(args) {
     const response = { device: res.device, appTerminated: res.appTerminated };
     return wrapResponse(response);
 }
-async function handleRestartApp(args) {
+async function executeRestartApp(args) {
     const platform = requireStringArg(args, 'platform');
     const appId = requireStringArg(args, 'appId');
     const deviceId = getStringArg(args, 'deviceId');
-    const uiFingerprintBefore = await captureActionFingerprint(platform, deviceId);
+    const { verificationMode, actionTimeoutMs } = interactionControls(args);
+    const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null;
     ToolsNetwork.notifyActionStart();
-    const res = await (platform === 'android' ? new AndroidManage().restartApp(appId, deviceId) : new iOSManage().restartApp(appId, deviceId));
-    const uiFingerprintAfter = await captureActionFingerprint(platform, deviceId);
-    return wrapResponse(buildActionExecutionResult({
+    const bounded = args._journey === true || verificationMode !== 'full' || args.responseMode !== undefined || actionTimeoutMs !== undefined;
+    const res = await measure('dispatch_ms', () => (platform === 'android' ? new AndroidManage().restartApp(appId, deviceId, bounded, actionTimeoutMs ?? 15000) : new iOSManage().restartApp(appId, deviceId, verificationMode === 'full', bounded, actionTimeoutMs ?? 15000)));
+    const uiFingerprintAfter = verificationMode === 'full' ? await measure('post_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null;
+    const result = buildActionExecutionResult({
         actionType: 'restart_app',
         sourceModule: 'server',
         device: res.device,
@@ -62,9 +187,11 @@ async function handleRestartApp(args) {
             ...(typeof res.terminatedBeforeRestart === 'boolean' ? { terminated_before_restart: res.terminatedBeforeRestart } : {}),
             ...(typeof res.terminateError === 'string' ? { terminate_error: res.terminateError } : {}),
             ...(typeof res.error === 'string' ? { error: res.error } : {}),
+            ...(res.diagnostics ? { diagnostics: res.diagnostics } : {}),
             ...(res.observedApp ? { observed_app: res.observedApp } : {})
         }
-    }));
+    });
+    return wrapResponse(result);
 }
 async function handleResetAppData(args) {
     const platform = requireStringArg(args, 'platform');
@@ -143,10 +270,12 @@ async function handleGetSystemStatus() {
 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 screenshotMs = performance.now() - started;
     const mime = res.screenshot_mime || 'image/png';
     const content = [
-        { type: 'text', text: JSON.stringify({ device: res.device, result: { resolution: res.resolution, mimeType: mime } }, null, 2) },
+        { type: 'text', text: JSON.stringify({ device: res.device, result: { resolution: res.resolution, mimeType: mime }, timing: { total_ms: screenshotMs, screenshot_ms: screenshotMs } }, null, 2) },
         { type: 'image', data: res.screenshot, mimeType: mime }
     ];
     if (res.screenshot_fallback) {
@@ -163,13 +292,17 @@ async function handleCaptureDebugSnapshot(args) {
     const appId = getStringArg(args, 'appId');
     const deviceId = getStringArg(args, 'deviceId');
     const sessionId = getStringArg(args, 'sessionId');
-    const res = await ToolsObserve.captureDebugSnapshotHandler({ reason, includeLogs, logLines, platform, appId, deviceId, sessionId });
+    const includeScreenshot = getBooleanArg(args, 'includeScreenshot');
+    const res = await ToolsObserve.captureDebugSnapshotHandler({ reason, includeLogs, includeScreenshot, logLines, platform, appId, deviceId, sessionId });
     return wrapResponse(res);
 }
 async function handleGetUITree(args) {
     const platform = requireStringArg(args, 'platform');
     const deviceId = getStringArg(args, 'deviceId');
-    const res = await ToolsObserve.getUITreeHandler({ platform, deviceId });
+    const responseMode = getStringArg(args, 'responseMode') ?? 'debug';
+    const sinceSnapshotRevision = getNumberArg(args, 'sinceSnapshotRevision');
+    const metricsStepId = process.env.MOBILE_DEBUG_MCP_UI_TREE_METRICS === '1' ? getStringArg(args, '_metricsStepId') : undefined;
+    const res = await withObservationContext({ stepId: metricsStepId, purpose: metricsStepId?.includes('post-response') ? 'assertion' : 'debug' }, () => ToolsObserve.getUITreeHandler({ platform, deviceId, responseMode, sinceSnapshotRevision }));
     return wrapResponse(res);
 }
 async function handleGetCurrentScreen(args) {
@@ -279,19 +412,22 @@ async function handleFindElement(args) {
     const timeoutMs = getNumberArg(args, 'timeoutMs') ?? 3000;
     const platform = getStringArg(args, 'platform');
     const deviceId = getStringArg(args, 'deviceId');
-    const res = await ToolsInteract.findElementHandler({ query, exact, timeoutMs, platform, deviceId });
+    const targetStarted = performance.now();
+    const res = await withObservationContext({ purpose: 'target' }, () => ToolsInteract.findElementHandler({ query, exact, timeoutMs, platform, deviceId }));
+    recordObservationEvent({ target_resolution_ms: performance.now() - targetStarted, target_resolution_outcome: res.found ? 'found' : 'not_found', operation: 'find_element' });
     return wrapResponse(res);
 }
-async function handleTap(args) {
+async function executeTap(args) {
     const platform = getStringArg(args, 'platform');
     const x = requireNumberArg(args, 'x');
     const y = requireNumberArg(args, 'y');
     const deviceId = getStringArg(args, 'deviceId');
-    const uiFingerprintBefore = await captureActionFingerprint(platform, deviceId);
+    const { verificationMode, actionTimeoutMs } = interactionControls(args);
+    const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null;
     ToolsNetwork.notifyActionStart();
-    const res = await ToolsInteract.tapHandler({ platform, x, y, deviceId });
-    const uiFingerprintAfter = await captureActionFingerprint(platform, deviceId);
-    return wrapResponse(buildActionExecutionResult({
+    const res = await measure('dispatch_ms', () => ToolsInteract.tapHandler({ platform, x, y, deviceId, timeoutMs: actionTimeoutMs }));
+    const uiFingerprintAfter = verificationMode === 'full' ? await measure('post_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null;
+    const result = buildActionExecutionResult({
         actionType: 'tap',
         sourceModule: 'server',
         selector: { x, y },
@@ -299,15 +435,177 @@ async function handleTap(args) {
         uiFingerprintBefore,
         uiFingerprintAfter,
         failure: res.success ? undefined : inferGenericFailure(res.error)
-    }));
+    });
+    return wrapResponse(result);
 }
-async function handleTapElement(args) {
-    const elementId = requireStringArg(args, 'elementId');
+async function executeTapElement(args) {
+    const controls = tapElementControlsSchema.safeParse({ elementId: args.elementId, selector: args.selector, waitFor: args.waitFor });
+    if (!controls.success)
+        throw new Error(`INVALID_ARGUMENT: ${controls.error.message}`);
+    const elementId = controls.data.elementId;
+    const selector = controls.data.selector;
+    const { verificationMode, actionTimeoutMs } = interactionControls(args);
+    let resolvedId = elementId;
+    let freshTree;
+    if (selector) {
+        const waitFor = getObjectArg(args, 'waitFor');
+        const targetStarted = performance.now();
+        const resolution = await withObservationContext({ stepId: args._stepId, purpose: 'target' }, () => measure('target_resolution_ms', () => runWithBudget(waitFor?.timeoutMs ?? 1500, () => ToolsInteract.waitForUIHandler({ selector, condition: waitFor?.condition ?? 'clickable', timeout_ms: waitFor?.timeoutMs ?? 1500, poll_interval_ms: waitFor?.pollIntervalMs ?? 100, match: waitFor?.match, singleObservation: true, singleAttempt: !waitFor, rejectAmbiguous: !waitFor, platform: getStringArg(args, 'platform'), deviceId: getStringArg(args, 'deviceId') }))));
+        recordObservationEvent({ step_id: args._stepId, purpose: 'target', target_resolution_ms: performance.now() - targetStarted, target_resolution_outcome: resolution.status });
+        if (resolution.status !== 'success' || !resolution.element?.elementId)
+            return wrapResponse({ success: false, action_type: 'tap_element', failure_code: resolution.error?.code ?? 'ELEMENT_NOT_FOUND', retryable: true });
+        resolvedId = resolution.element.elementId;
+        freshTree = resolution._tree;
+    }
     ToolsNetwork.notifyActionStart();
-    const res = await ToolsInteract.tapElementHandler({ elementId });
+    if (freshTree)
+        recordObservationConsumer(freshTree, 'target', args._stepId);
+    const res = await measure('dispatch_ms', () => ToolsInteract.tapElementHandler({ elementId: resolvedId, freshTree, verificationMode, timeoutMs: actionTimeoutMs, platform: getStringArg(args, 'platform'), deviceId: getStringArg(args, 'deviceId') }));
     return wrapResponse(res);
 }
-async function handleSwipe(args) {
+function payloadOf(response) {
+    const text = response.content.find((item) => item.type === 'text')?.text;
+    return text ? JSON.parse(text) : null;
+}
+async function expectElementAbsent({ selector, timeoutMs, pollIntervalMs, platform, deviceId }) {
+    const deadline = performance.now() + timeoutMs;
+    let consecutive = 0;
+    let observed;
+    while (performance.now() < deadline) {
+        const result = await ToolsInteract.waitForUIHandler({ selector, condition: 'not_exists', timeout_ms: 0, singleObservation: true, singleAttempt: true, platform, deviceId });
+        observed = result.observed;
+        consecutive = result.status === 'success' ? consecutive + 1 : 0;
+        if (consecutive === 2 && performance.now() <= deadline)
+            return { success: true, observed };
+        const delay = Math.max(100, pollIntervalMs);
+        if (performance.now() + delay >= deadline)
+            break;
+        await new Promise(resolve => setTimeout(resolve, delay));
+    }
+    return { success: false, failure_code: 'ASSERTION_TIMEOUT', observed };
+}
+async function expectFingerprint({ fingerprint, timeoutMs, platform, deviceId }) {
+    const deadline = performance.now() + timeoutMs;
+    let consecutive = 0;
+    let observed = null;
+    while (performance.now() < deadline) {
+        const result = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId });
+        observed = result?.fingerprint ?? null;
+        consecutive = observed === fingerprint ? consecutive + 1 : 0;
+        if (consecutive === 2 && performance.now() <= deadline)
+            return { success: true, observed_fingerprint: observed };
+        if (performance.now() + 100 >= deadline)
+            break;
+        await new Promise(resolve => setTimeout(resolve, 100));
+    }
+    return { success: false, failure_code: 'ASSERTION_TIMEOUT', observed_fingerprint: observed };
+}
+async function handleRunJourney(args) {
+    const parsed = journeySchema.safeParse(args);
+    if (!parsed.success)
+        throw new Error(`INVALID_ARGUMENT: ${parsed.error.message}`);
+    const { platform, responseMode, defaults, captureOnFailure } = parsed.data;
+    const steps = parsed.data.steps;
+    const device = await resolveTargetDevice({ platform, deviceId: parsed.data.deviceId });
+    const deviceId = device.id;
+    return withResolvedDevice(device, async () => {
+        const started = performance.now();
+        const results = [];
+        let stoppedAt = null;
+        let pendingLightStep = null;
+        for (let index = 0; index < steps.length; index++) {
+            const step = steps[index];
+            const requestedVerification = step.verificationMode ?? defaults?.verificationMode ?? 'full';
+            const next = steps[index + 1];
+            const lightCoveredByAssertion = step.type === 'tap' && responseMode === 'compact' && requestedVerification === 'light' && next?.type === 'assert' &&
+                next.assertion?.kind === 'element_visible';
+            const stepStart = performance.now();
+            let result;
+            if (stoppedAt) {
+                results.push({ id: step.id, type: step.type, status: 'not_run', success: false, reason: 'PREVIOUS_STEP_FAILED', result: null, timing: { total_ms: 0 } });
+                continue;
+            }
+            try {
+                if (step.type === 'tap') {
+                    result = payloadOf(await handleTapElement({ ...defaults, ...step, platform, deviceId, responseMode, _journey: true, _stepId: step.id, verificationMode: lightCoveredByAssertion ? 'none' : requestedVerification }));
+                }
+                else if (step.type === 'wait') {
+                    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 }));
+                    result = { success: result.status === 'success', ...result };
+                }
+                else if (step.type === 'assert') {
+                    result = await withObservationContext({ stepId: step.id, purpose: 'assertion' }, () => runWithBudget(step.timeoutMs ?? 5000, async () => {
+                        const assertion = step.assertion;
+                        if (assertion?.kind === 'element_visible')
+                            result = await ToolsInteract.expectElementVisibleHandler({ selector: assertion.selector, timeout_ms: step.timeoutMs ?? 5000, poll_interval_ms: step.pollIntervalMs ?? 100, platform, deviceId });
+                        else if (assertion?.kind === 'element_absent')
+                            result = await expectElementAbsent({ selector: assertion.selector, timeoutMs: step.timeoutMs ?? 5000, pollIntervalMs: step.pollIntervalMs ?? 100, platform, deviceId });
+                        else if (assertion?.kind === 'screen_fingerprint')
+                            result = await expectFingerprint({ fingerprint: assertion.fingerprint, timeoutMs: step.timeoutMs ?? 5000, platform, deviceId });
+                        else if (assertion?.kind === 'state_equals')
+                            result = await ToolsInteract.expectStateHandler({ selector: assertion.selector, element_id: assertion.elementId, property: assertion.property, expected: assertion.expected, platform, deviceId, stabilization_window_ms: step.timeoutMs ?? 5000, poll_interval_ms: step.pollIntervalMs ?? 100, exact_budget: true });
+                        else
+                            result = { success: false, failure_code: 'INVALID_ASSERTION' };
+                        return result;
+                    }));
+                }
+                else if (step.type === 'start_app') {
+                    result = payloadOf(await handleStartApp({ ...defaults, platform, deviceId, appId: step.appId, responseMode, _journey: true, _stepId: step.id, verificationMode: step.verificationMode ?? defaults?.verificationMode ?? 'full' }));
+                }
+                else {
+                    result = { success: false, failure_code: 'UNSUPPORTED_JOURNEY_STEP' };
+                }
+            }
+            catch (error) {
+                result = { success: false, failure_code: step.type === 'assert' ? 'ASSERTION_TIMEOUT' : 'STEP_FAILED', error: error instanceof Error ? error.message : String(error) };
+            }
+            if (step.type === 'assert' && !result?.success && /TIMEOUT/.test(result?.failure_code ?? ''))
+                result.failure_code = 'ASSERTION_TIMEOUT';
+            const success = !!result?.success;
+            if (lightCoveredByAssertion) {
+                result.verification = { mode: 'light', status: success ? 'unavailable' : 'failed' };
+                if (success) {
+                    result.verification_diagnostic = { code: 'VERIFICATION_UNAVAILABLE', retryable: true };
+                    pendingLightStep = results.length;
+                }
+            }
+            if (step.type === 'assert' && pendingLightStep !== null) {
+                const pending = results[pendingLightStep].result;
+                if (typeof result?.observed?.matched_count === 'number') {
+                    pending.verification.status = 'observed';
+                    delete pending.verification_diagnostic;
+                    const delta = ToolsObserve.getLatestStateDelta(platform, deviceId);
+                    if (delta) {
+                        pending.state_delta = delta;
+                        pending.state_delta_available = true;
+                    }
+                }
+                pendingLightStep = null;
+            }
+            if (responseMode === 'compact' && ['wait', 'assert'].includes(step.type))
+                result = {
+                    success, ...(result.failure_code ? { failure_code: result.failure_code } : {}),
+                    ...(result.error?.code ? { failure_code: result.error.code } : {}),
+                    ...(result.observed?.matched_count !== undefined ? { matched_count: result.observed.matched_count } : {}),
+                    ...(result.observed_fingerprint !== undefined ? { matched: success } : {}),
+                    ...(result.actual_state ? { observed: result.actual_state } : {})
+                };
+            results.push({ id: step.id, type: step.type, status: success ? 'passed' : 'failed', success, result, timing: { total_ms: performance.now() - stepStart } });
+            if (!success)
+                stoppedAt = step.id;
+        }
+        const failureSnapshot = stoppedAt && captureOnFailure && responseMode === 'debug'
+            ? await ToolsObserve.captureDebugSnapshotHandler({ platform, deviceId, includeScreenshot: false }).catch(() => null) : undefined;
+        const componentTiming = {};
+        for (const step of results)
+            for (const [key, value] of Object.entries(step.result?.timing ?? {})) {
+                if (key !== 'total_ms' && typeof value === 'number')
+                    componentTiming[key] = (componentTiming[key] ?? 0) + value;
+            }
+        return wrapResponse({ success: stoppedAt === null, stopped_at_step_id: stoppedAt, steps: results, ...(failureSnapshot ? { failure_snapshot: failureSnapshot } : {}), timing: responseMode === 'compact' ? { total_ms: performance.now() - started } : { ...componentTiming, total_ms: performance.now() - started } }, responseMode === 'debug');
+    });
+}
+async function executeSwipe(args) {
     const platform = getStringArg(args, 'platform') ?? 'android';
     const x1 = requireNumberArg(args, 'x1');
     const y1 = requireNumberArg(args, 'y1');
@@ -315,11 +613,12 @@ async function handleSwipe(args) {
     const y2 = requireNumberArg(args, 'y2');
     const duration = requireNumberArg(args, 'duration');
     const deviceId = getStringArg(args, 'deviceId');
-    const uiFingerprintBefore = await captureActionFingerprint(platform, deviceId);
+    const { verificationMode, actionTimeoutMs } = interactionControls(args);
+    const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null;
     ToolsNetwork.notifyActionStart();
-    const res = await ToolsInteract.swipeHandler({ platform, x1, y1, x2, y2, duration, deviceId });
-    const uiFingerprintAfter = await captureActionFingerprint(platform, deviceId);
-    return wrapResponse(buildActionExecutionResult({
+    const res = await measure('dispatch_ms', () => ToolsInteract.swipeHandler({ platform, x1, y1, x2, y2, duration, deviceId, timeoutMs: actionTimeoutMs }));
+    const uiFingerprintAfter = verificationMode === 'full' ? await measure('post_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null;
+    const result = buildActionExecutionResult({
         actionType: 'swipe',
         sourceModule: 'server',
         selector: { x1, y1, x2, y2, duration },
@@ -327,20 +626,22 @@ async function handleSwipe(args) {
         uiFingerprintBefore,
         uiFingerprintAfter,
         failure: res.success ? undefined : inferGenericFailure(res.error)
-    }));
+    });
+    return wrapResponse(result);
 }
-async function handleScrollToElement(args) {
+async function executeScrollToElement(args) {
     const platform = requireStringArg(args, 'platform');
     const selector = requireObjectArg(args, 'selector');
     const direction = getStringArg(args, 'direction');
     const maxScrolls = getNumberArg(args, 'maxScrolls');
     const scrollAmount = getNumberArg(args, 'scrollAmount');
     const deviceId = getStringArg(args, 'deviceId');
-    const uiFingerprintBefore = await captureActionFingerprint(platform, deviceId);
+    const { verificationMode } = interactionControls(args);
+    const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null;
     ToolsNetwork.notifyActionStart();
-    const res = await ToolsInteract.scrollToElementHandler({ platform, selector, direction, maxScrolls, scrollAmount, deviceId });
-    const uiFingerprintAfter = await captureActionFingerprint(platform, deviceId);
-    return wrapResponse(buildActionExecutionResult({
+    const res = await measure('dispatch_ms', () => ToolsInteract.scrollToElementHandler({ platform, selector, direction, maxScrolls, scrollAmount, deviceId }));
+    const uiFingerprintAfter = verificationMode === 'full' ? await measure('post_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null;
+    const result = buildActionExecutionResult({
         actionType: 'scroll_to_element',
         sourceModule: 'server',
         selector: selector ?? null,
@@ -357,16 +658,18 @@ async function handleScrollToElement(args) {
         uiFingerprintBefore,
         uiFingerprintAfter,
         failure: res.success ? undefined : inferScrollFailure(res.reason)
-    }));
+    });
+    return wrapResponse(result);
 }
-async function handleTypeText(args) {
+async function executeTypeText(args) {
     const text = requireStringArg(args, 'text');
     const deviceId = getStringArg(args, 'deviceId');
-    const uiFingerprintBefore = await captureActionFingerprint('android', deviceId);
+    const { verificationMode, actionTimeoutMs } = interactionControls(args);
+    const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint('android', deviceId)) : null;
     ToolsNetwork.notifyActionStart();
-    const res = await ToolsInteract.typeTextHandler({ text, deviceId });
-    const uiFingerprintAfter = await captureActionFingerprint('android', deviceId);
-    return wrapResponse(buildActionExecutionResult({
+    const res = await measure('dispatch_ms', () => ToolsInteract.typeTextHandler({ text, deviceId, timeoutMs: actionTimeoutMs }));
+    const uiFingerprintAfter = verificationMode === 'full' ? await measure('post_observation_ms', () => captureActionFingerprint('android', deviceId)) : null;
+    const result = buildActionExecutionResult({
         actionType: 'type_text',
         sourceModule: 'server',
         selector: { text },
@@ -374,15 +677,17 @@ async function handleTypeText(args) {
         uiFingerprintBefore,
         uiFingerprintAfter,
         failure: res.success ? undefined : inferGenericFailure(res.error)
-    }));
+    });
+    return wrapResponse(result);
 }
-async function handlePressBack(args) {
+async function executePressBack(args) {
     const deviceId = getStringArg(args, 'deviceId');
-    const uiFingerprintBefore = await captureActionFingerprint('android', deviceId);
+    const { verificationMode, actionTimeoutMs } = interactionControls(args);
+    const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint('android', deviceId)) : null;
     ToolsNetwork.notifyActionStart();
-    const res = await ToolsInteract.pressBackHandler({ deviceId });
-    const uiFingerprintAfter = await captureActionFingerprint('android', deviceId);
-    return wrapResponse(buildActionExecutionResult({
+    const res = await measure('dispatch_ms', () => ToolsInteract.pressBackHandler({ deviceId, timeoutMs: actionTimeoutMs }));
+    const uiFingerprintAfter = verificationMode === 'full' ? await measure('post_observation_ms', () => captureActionFingerprint('android', deviceId)) : null;
+    const result = buildActionExecutionResult({
         actionType: 'press_back',
         sourceModule: 'server',
         selector: { key: 'back' },
@@ -390,7 +695,8 @@ async function handlePressBack(args) {
         uiFingerprintBefore,
         uiFingerprintAfter,
         failure: res.success ? undefined : inferGenericFailure(res.error)
-    }));
+    });
+    return wrapResponse(result);
 }
 async function handleStartLogStream(args) {
     const platform = getStringArg(args, 'platform') ?? 'android';
@@ -462,6 +768,7 @@ export const toolHandlers = {
     find_element: handleFindElement,
     tap: handleTap,
     tap_element: handleTapElement,
+    run_journey: handleRunJourney,
     swipe: handleSwipe,
     scroll_to_element: handleScrollToElement,
     type_text: handleTypeText,
@@ -476,11 +783,29 @@ export async function handleToolCall(name, args = {}) {
     const handler = toolHandlers[name];
     if (!handler)
         throw new Error(`Unknown tool: ${name}`);
-    try {
-        return await handler(args);
-    }
-    catch (error) {
-        console.error(`Error executing tool ${name}:`, error);
-        return wrapToolError(name, error);
-    }
+    const started = performance.now();
+    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;
+        const item = response.content.find(item => item.type === 'text');
+        if (item?.text) {
+            try {
+                const value = JSON.parse(item.text);
+                value.timing = { ...measured, ...value.timing, total_ms: performance.now() - started };
+                item.text = JSON.stringify(value);
+            }
+            catch { /* Non-JSON text responses retain their original content. */ }
+        }
+        return response;
+    };
+    return withTiming(measured, async () => {
+        try {
+            return addTiming(await handler(args));
+        }
+        catch (error) {
+            console.error(`Error executing tool ${name}:`, error);
+            return addTiming(wrapToolError(name, error));
+        }
+    });
 }

package/dist/server-core.js

@@ -6,7 +6,7 @@ import { handleToolCall } from './server/tool-handlers.js';
 export { wrapResponse, toolDefinitions, handleToolCall };
 export const serverInfo = {
     name: 'mobile-debug-mcp',
-    version: '0.31.0'
+    version: '0.32.1'
 };
 export function createServer() {
     const server = new Server(serverInfo, {