mobile-debug-mcp 0.32.4 → 0.34.0

package/dist/server/tool-handlers.js

@@ -1,7 +1,18 @@
+import { handleDebugger } from './debugger-handlers.js';
+import { debuggerContracts } from './debugger-schema.js';
+import { debuggerSessions } from '../debugger/sessions.js';
+import { withDebuggerGuard, guardDispatched } from '../debugger/guard.js';
+import { systemTraces, TraceError } from '../observe/system-trace.js';
+import { systemTraceTools, traceTargetSchema, traceStartSchema, traceControlSchema } from './system-trace-schema.js';
+import { currentEvidenceCorrelationId, bindSystemTrace, withEvidence, currentEvidenceActionId, validateActionRef, markEvidenceVerification, refreshJourneyEvidence, completeJourneyVerification } from '../observe/evidence.js';
 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 { readinessSchema, readinessWaitSchema } from './readiness-schema.js';
+import { getAppReadiness, withReadyWait } from '../observe/readiness-service.js';
+import { validateExpectedState } from './condition-schema.js';
+import { conditionFailureCode, createConditionalAction, notifyActionStart, withConditionalAction } from '../interact/conditional-action.js';
 import { resolveTargetDevice, withResolvedDevice } from '../utils/resolve-device.js';
 import { AndroidManage, iOSManage, ToolsManage } from '../manage/index.js';
 import { ToolsInteract } from '../interact/index.js';
@@ -11,6 +22,7 @@ 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';
+const systemTraceToolNames = new Set(systemTraceTools.map(tool => tool.name));
 function interactionControls(args) {
     const verificationMode = getStringArg(args, 'verificationMode') ?? 'full';
     const responseMode = getStringArg(args, 'responseMode') ?? 'debug';
@@ -43,18 +55,45 @@ function compactAction(result, verificationMode, started = true, stateDelta, tot
         timing: { total_ms: totalMs }
     };
 }
-function actionHandler(type, execute) {
+function correlatedHandler(name, handler, action = false, journey = false) {
     return async (args) => {
+        const ref = validateActionRef(args.actionRef);
+        const { result, evidence } = await withEvidence({ action, journey, ref }, async () => {
+            try {
+                return await handler(args);
+            }
+            catch (error) {
+                return error instanceof TraceError ? { ...wrapResponse({ error: { tool: name, code: error.code, message: error.message } }), isError: true } : wrapToolError(name, error);
+            }
+        });
+        const item = result.content.find(item => item.type === 'text');
+        if (item?.text) {
+            const payload = JSON.parse(item.text);
+            payload.evidence = evidence;
+            item.text = JSON.stringify(payload);
+        }
+        return result;
+    };
+}
+function actionHandler(type, execute) {
+    return correlatedHandler(type, async (args) => {
         const timing = {};
         return withTiming(timing, async () => {
             const started = performance.now();
             const controls = interactionControls(args);
+            const expected = validateExpectedState(type, args);
+            const condition = expected ? createConditionalAction(args.platform, args.deviceId, expected) : undefined;
             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));
+                    if (!condition)
+                        return payloadOf(await execute(args));
+                    return await withConditionalAction(condition, async () => {
+                        const device = await resolveTargetDevice({ platform: condition.platform, deviceId: condition.deviceId });
+                        return withResolvedDevice(device, async () => payloadOf(await execute(args)));
+                    });
                 }
                 finally {
                     dispatchStarted = budget.dispatchStarted;
@@ -68,17 +107,28 @@ function actionHandler(type, execute) {
                     dispatchStarted = true;
             }
             catch (error) {
-                if (controls.verificationMode === 'full' && controls.responseMode === 'debug' && controls.actionTimeoutMs === undefined && !/TIMEOUT|timed out/i.test(String(error)))
+                if (!condition && 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) };
             }
+            const blocked = condition && ['mismatch', 'unavailable'].includes(condition.result.status);
+            if (blocked) {
+                dispatchStarted = false;
+                result = buildActionExecutionResult({
+                    actionType: type, sourceModule: 'server', device: condition.result.observed?.device,
+                    selector: result?.target?.selector ?? null, resolved: result?.target?.resolved,
+                    success: false, uiFingerprintBefore: result?.ui_fingerprint_before ?? null, uiFingerprintAfter: null,
+                    failure: { failureCode: conditionFailureCode(condition), retryable: false },
+                    traceSteps: [{ stage: 'verify', timestamp: Date.now(), result: 'failure', attempt_index: 0, metadata: { phase: 'precondition', dispatch_started: false } }]
+                });
+            }
             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_id ??= currentEvidenceActionId() ?? randomUUID();
             result.action_type ??= type;
             recordObservationEvent({
                 step_id: args._stepId,
@@ -92,6 +142,7 @@ function actionHandler(type, execute) {
             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);
+                markEvidenceVerification();
                 observationAvailable = !!tree && !tree.error;
                 recordObservationEvent({
                     verification_budget_ms: controls.verificationTimeoutMs,
@@ -102,11 +153,21 @@ function actionHandler(type, execute) {
                 if (observationAvailable && tree.device)
                     delta = ToolsObserve.getLatestStateDelta(tree.device.platform, tree.device.id) ?? undefined;
             }
+            if (!blocked && controls.verificationMode === 'full' && dispatchStarted)
+                markEvidenceVerification();
             const compact = compactAction(result, controls.verificationMode, dispatchStarted, delta, performance.now() - started);
+            if (blocked)
+                compact.verification.status = 'not_requested';
             if (result.success && controls.verificationMode === 'light' && !observationAvailable)
                 compact.verification.status = 'unavailable';
             const evidence = {
                 ...compact,
+                ...(condition ? { condition: controls.responseMode === 'compact' && condition.result.status === 'matched'
+                        ? { ...condition.result, observed: condition.result.observed ? {
+                                snapshot_session_id: condition.result.observed.snapshot_session_id,
+                                snapshot_revision: condition.result.observed.snapshot_revision,
+                                captured_at_ms: condition.result.observed.captured_at_ms
+                            } : null } : condition.result } : {}),
                 ...(controls.verificationMode === 'light' ? { state_delta_available: !!delta } : {}),
                 ...(result.success && controls.verificationMode === 'light' && !observationAvailable ? { verification_diagnostic: { code: 'VERIFICATION_UNAVAILABLE', retryable: true } } : {})
             };
@@ -115,7 +176,7 @@ function actionHandler(type, execute) {
                 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');
         });
-    };
+    }, true);
 }
 const handleStartApp = actionHandler('start_app', executeStartApp);
 const handleRestartApp = actionHandler('restart_app', executeRestartApp);
@@ -131,7 +192,7 @@ async function executeStartApp(args) {
     const deviceId = getStringArg(args, 'deviceId');
     const { verificationMode, actionTimeoutMs } = interactionControls(args);
     const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null;
-    ToolsNetwork.notifyActionStart();
+    notifyActionStart();
     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({
@@ -168,7 +229,7 @@ async function executeRestartApp(args) {
     const deviceId = getStringArg(args, 'deviceId');
     const { verificationMode, actionTimeoutMs } = interactionControls(args);
     const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null;
-    ToolsNetwork.notifyActionStart();
+    notifyActionStart();
     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;
@@ -381,9 +442,12 @@ async function handleAdjustControl(args) {
         platform,
         deviceId
     });
+    markEvidenceVerification();
     return wrapResponse(res);
 }
 async function handleWaitForUI(args) {
+    if (args.requireReady !== undefined && typeof args.requireReady !== 'boolean')
+        throw new Error('INVALID_ARGUMENT: requireReady must be boolean');
     const selector = getObjectArg(args, 'selector');
     const condition = getStringArg(args, 'condition') ?? 'exists';
     const timeout_ms = getNumberArg(args, 'timeout_ms') ?? 60000;
@@ -392,10 +456,13 @@ async function handleWaitForUI(args) {
     const retry = getObjectArg(args, 'retry');
     const platform = getStringArg(args, 'platform');
     const deviceId = getStringArg(args, 'deviceId');
-    const res = await ToolsInteract.waitForUIHandler({ selector, condition, timeout_ms, poll_interval_ms, match, retry, platform, deviceId });
+    const execute = (targetPlatform = platform, targetId = deviceId) => ToolsInteract.waitForUIHandler({ selector, condition, timeout_ms, poll_interval_ms, match, retry, platform: targetPlatform, deviceId: targetId });
+    const res = args.requireReady === true ? await withReadyWait({ platform, deviceId }, timeout_ms, device => execute(device.platform, device.id), (code, elapsed, samples) => ({ status: 'timeout', error: { code, message: 'Readiness wait could not complete' }, metrics: { latency_ms: elapsed, poll_count: samples, attempts: samples ? 1 : 0 }, requested: { selector, condition, match }, observed: { matched_count: 0, condition_satisfied: false, selected_index: null, last_matched_element: null } })) : await execute();
     return wrapResponse(res);
 }
 async function handleWaitForUIChange(args) {
+    if (args.requireReady !== undefined && typeof args.requireReady !== 'boolean')
+        throw new Error('INVALID_ARGUMENT: requireReady must be boolean');
     const platform = getStringArg(args, 'platform');
     const deviceId = getStringArg(args, 'deviceId');
     const timeout_ms = getNumberArg(args, 'timeout_ms') ?? 60000;
@@ -403,7 +470,8 @@ async function handleWaitForUIChange(args) {
     const expected_change = getStringArg(args, 'expected_change');
     const scope = getStringArg(args, 'scope');
     const target = getStringArg(args, 'target');
-    const res = await ToolsInteract.waitForUIChangeHandler({ platform, deviceId, timeout_ms, stability_window_ms, expected_change, scope, target });
+    const execute = (targetPlatform = platform, targetId = deviceId) => ToolsInteract.waitForUIChangeHandler({ platform: targetPlatform, deviceId: targetId, timeout_ms, stability_window_ms, expected_change, scope, target });
+    const res = args.requireReady === true ? await withReadyWait({ platform, deviceId }, timeout_ms, device => execute(device.platform, device.id), (code, elapsed) => ({ success: false, timeout: true, observed_change: null, elapsed_ms: elapsed, reason: code, error: { code, message: 'Readiness wait could not complete' } })) : await execute();
     return wrapResponse(res);
 }
 async function handleFindElement(args) {
@@ -424,7 +492,7 @@ async function executeTap(args) {
     const deviceId = getStringArg(args, 'deviceId');
     const { verificationMode, actionTimeoutMs } = interactionControls(args);
     const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null;
-    ToolsNetwork.notifyActionStart();
+    notifyActionStart();
     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({
@@ -450,14 +518,15 @@ async function executeTapElement(args) {
     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') }))));
+        const resolutionTimeoutMs = waitFor?.timeoutMs ?? actionTimeoutMs ?? 5000;
+        const resolution = await withObservationContext({ stepId: args._stepId, purpose: 'target' }, () => measure('target_resolution_ms', () => runWithBudget(resolutionTimeoutMs, () => ToolsInteract.waitForUIHandler({ selector, condition: waitFor?.condition ?? 'clickable', timeout_ms: resolutionTimeoutMs, poll_interval_ms: waitFor?.pollIntervalMs ?? 100, match: waitFor?.match, singleObservation: true, singleAttempt: !waitFor, rejectAmbiguous: !waitFor, resolveTapTarget: true, 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();
+    notifyActionStart();
     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') }));
@@ -508,102 +577,125 @@ async function handleRunJourney(args) {
     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 }));
+    const finishTrace = parsed.data.systemTraceId
+        ? await systemTraces.link(parsed.data.systemTraceId, device, currentEvidenceCorrelationId()) : undefined;
+    if (parsed.data.systemTraceId)
+        bindSystemTrace(parsed.data.systemTraceId);
+    try {
+        return await 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];
+                if (platform === 'android' && debuggerSessions.paused(deviceId)) {
+                    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' } });
+                    stoppedAt = step.id;
+                    break;
                 }
-                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 };
+                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;
                 }
-                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;
-                    }));
+                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' };
+                    }
                 }
-                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' }));
+                catch (error) {
+                    result = { success: false, failure_code: step.type === 'assert' ? 'ASSERTION_TIMEOUT' : 'STEP_FAILED', error: error instanceof Error ? error.message : String(error) };
                 }
-                else {
-                    result = { success: false, failure_code: 'UNSUPPORTED_JOURNEY_STEP' };
+                if (platform === 'android' && debuggerSessions.paused(deviceId)) {
+                    result.success = false;
+                    result.failure_code = 'DEBUGGER_PAUSED';
+                    result.retryable = false;
                 }
-            }
-            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' && !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' :
+                            (['mismatch', 'unavailable'].includes(result.condition?.status) ? 'not_requested' : '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;
+                if (step.type === 'assert' && pendingLightStep !== null) {
+                    const pending = results[pendingLightStep].result;
+                    if (typeof result?.observed?.matched_count === 'number') {
+                        pending.verification.status = 'observed';
+                        if (pending.evidence)
+                            completeJourneyVerification(pending.evidence.action_id);
+                        delete pending.verification_diagnostic;
+                        const delta = ToolsObserve.getLatestStateDelta(platform, deviceId);
+                        if (delta) {
+                            pending.state_delta = delta;
+                            pending.state_delta_available = true;
+                        }
                     }
+                    pendingLightStep = null;
                 }
-                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;
             }
-            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');
-    });
+            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;
+                }
+            refreshJourneyEvidence(results);
+            return wrapResponse({ ...(finishTrace ? { system_trace: await finishTrace() } : {}), 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');
+        });
+    }
+    finally {
+        await finishTrace?.();
+    }
 }
 async function executeSwipe(args) {
     const platform = getStringArg(args, 'platform') ?? 'android';
@@ -615,7 +707,7 @@ async function executeSwipe(args) {
     const deviceId = getStringArg(args, 'deviceId');
     const { verificationMode, actionTimeoutMs } = interactionControls(args);
     const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null;
-    ToolsNetwork.notifyActionStart();
+    notifyActionStart();
     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({
@@ -638,7 +730,7 @@ async function executeScrollToElement(args) {
     const deviceId = getStringArg(args, 'deviceId');
     const { verificationMode } = interactionControls(args);
     const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null;
-    ToolsNetwork.notifyActionStart();
+    notifyActionStart();
     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({
@@ -666,7 +758,7 @@ async function executeTypeText(args) {
     const deviceId = getStringArg(args, 'deviceId');
     const { verificationMode, actionTimeoutMs } = interactionControls(args);
     const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint('android', deviceId)) : null;
-    ToolsNetwork.notifyActionStart();
+    notifyActionStart();
     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({
@@ -684,7 +776,7 @@ async function executePressBack(args) {
     const deviceId = getStringArg(args, 'deviceId');
     const { verificationMode, actionTimeoutMs } = interactionControls(args);
     const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint('android', deviceId)) : null;
-    ToolsNetwork.notifyActionStart();
+    notifyActionStart();
     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({
@@ -742,7 +834,50 @@ async function handleGetNetworkActivity(args) {
     const result = await ToolsNetwork.getNetworkActivity({ platform, deviceId });
     return wrapResponse(result);
 }
+async function handleSystemTrace(name, args) {
+    const schema = name === 'start_system_trace' ? traceStartSchema : name === 'get_system_trace_capabilities' ? traceTargetSchema : traceControlSchema;
+    const parsed = schema.safeParse(args);
+    if (!parsed.success)
+        throw new TraceError('INVALID_ARGUMENT');
+    if (name === 'get_system_trace_capabilities' || name === 'start_system_trace') {
+        const target = parsed.data;
+        if (target.platform !== 'android') {
+            if (name === 'start_system_trace')
+                throw new TraceError('UNSUPPORTED_PLATFORM');
+            return wrapResponse({ supported: false, backend: 'perfetto', device: null, prerequisites: {}, reasons: ['UNSUPPORTED_PLATFORM'], enabled_sources: [], unavailable_categories: [], limitations: ['Android only'] });
+        }
+        let device;
+        try {
+            device = await resolveTargetDevice(target);
+        }
+        catch {
+            if (name === 'start_system_trace')
+                throw new TraceError('TRACE_UNSUPPORTED');
+            return wrapResponse({ supported: false, backend: 'perfetto', device: null, prerequisites: { device: false }, reasons: ['DEVICE_UNAVAILABLE'], enabled_sources: [], unavailable_categories: [], limitations: ['An authorised Android device is required'] });
+        }
+        if (name === 'get_system_trace_capabilities')
+            return wrapResponse(await systemTraces.capabilities(device.id));
+        const result = await systemTraces.start(device.id, target.durationMs);
+        return { ...wrapResponse(result), ...(result.state === 'failed' ? { isError: true } : {}) };
+    }
+    const operation = name === 'stop_system_trace' ? 'stop' : name === 'cancel_system_trace' ? 'cancel' : 'status';
+    const result = await systemTraces.control(parsed.data.traceId, operation);
+    return { ...wrapResponse(result), ...(['failed', 'cancelled'].includes(result.state) ? { isError: true } : {}) };
+}
 export const toolHandlers = {
+    ...Object.fromEntries(systemTraceTools.map(({ name }) => [name, (args) => handleSystemTrace(name, args)])),
+    get_app_readiness: async (args) => {
+        const parsed = readinessSchema.safeParse(args);
+        if (!parsed.success)
+            throw new Error('INVALID_ARGUMENT: invalid readiness arguments');
+        return wrapResponse(await getAppReadiness(parsed.data));
+    },
+    wait_for_app_ready: async (args) => {
+        const parsed = readinessWaitSchema.safeParse(args);
+        if (!parsed.success)
+            throw new Error('INVALID_ARGUMENT: invalid readiness arguments');
+        return wrapResponse(await getAppReadiness(parsed.data, true));
+    },
     start_app: handleStartApp,
     terminate_app: handleTerminateApp,
     restart_app: handleRestartApp,
@@ -779,7 +914,12 @@ export const toolHandlers = {
     classify_action_outcome: handleClassifyActionOutcome,
     get_network_activity: handleGetNetworkActivity
 };
-export async function handleToolCall(name, args = {}) {
+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');
+}
+export async function handleToolCall(name, args = {}, signal) {
+    if (Object.hasOwn(debuggerContracts, name))
+        return handleDebugger(name, args, signal);
     const handler = toolHandlers[name];
     if (!handler)
         throw new Error(`Unknown tool: ${name}`);
@@ -801,9 +941,58 @@ export async function handleToolCall(name, args = {}) {
     };
     return withTiming(measured, async () => {
         try {
-            return addTiming(await handler(args));
+            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 });
+                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 });
+                    let response;
+                    try {
+                        response = await handler(args);
+                    }
+                    catch (error) {
+                        if (!debuggerSessions.paused(device.id))
+                            throw error;
+                        response = wrapResponse({ success: false });
+                    }
+                    const pause = debuggerSessions.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 });
+                            item.text = JSON.stringify(payload);
+                        }
+                    }
+                    return addTiming(response);
+                }));
+            }
+            const response = await handler(args);
+            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') {
+                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;
+                        if (pause)
+                            item.text = JSON.stringify({ ...payload, debugger: pause });
+                    }
+                    catch { /* Non-JSON observation */ }
+                }
+            }
+            return addTiming(response);
         }
         catch (error) {
+            if (error instanceof TraceError)
+                return { ...wrapResponse({ error: { tool: name, code: error.code, message: error.message } }), isError: true };
             console.error(`Error executing tool ${name}:`, error);
             return addTiming(wrapToolError(name, error));
         }