mobile-debug-mcp 0.33.0 → 0.35.0

package/dist/server/handlers/journey.js

@@ -0,0 +1,147 @@
+import { debuggerSessions } from '../../debugger/sessions.js';
+import { systemTraces } from '../../observe/system-trace.js';
+import { currentEvidenceCorrelationId, bindSystemTrace, refreshJourneyEvidence, completeJourneyVerification } 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';
+import { ToolsInteract } from '../../interact/index.js';
+import { ToolsObserve } from '../../observe/index.js';
+import { withObservationContext } from '../../observe/performance-metrics.js';
+import { wrapResponse } from '../common.js';
+import { payloadOf } from './payload.js';
+import { handleStartApp } from './manage.js';
+import { handleTapElement } from './input.js';
+import { expectElementAbsent, expectFingerprint } from './journey-assertions.js';
+async function assertStep(step, platform, deviceId) {
+    const assertion = step.assertion;
+    const timeoutMs = step.timeoutMs ?? 5000, pollIntervalMs = step.pollIntervalMs ?? 100;
+    if (assertion.kind === 'element_visible')
+        return ToolsInteract.expectElementVisibleHandler({ selector: assertion.selector, timeout_ms: timeoutMs, poll_interval_ms: pollIntervalMs, platform, deviceId });
+    if (assertion.kind === 'element_absent')
+        return expectElementAbsent({ selector: assertion.selector, timeoutMs, pollIntervalMs, platform, deviceId });
+    if (assertion.kind === 'screen_fingerprint')
+        return expectFingerprint({ fingerprint: assertion.fingerprint, timeoutMs, platform, deviceId });
+    if (assertion.kind === 'state_equals')
+        return ToolsInteract.expectStateHandler({ selector: assertion.selector, element_id: assertion.elementId, property: assertion.property, expected: assertion.expected, platform, deviceId, stabilization_window_ms: timeoutMs, poll_interval_ms: pollIntervalMs, exact_budget: true });
+    return { success: false, failure_code: 'INVALID_ASSERTION' };
+}
+async function 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 === 'assert')
+            return await 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) };
+    }
+}
+function lightVerification(s, step, result, covered, success) {
+    if (covered) {
+        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 };
+            s.pendingLightStep = s.results.length;
+        }
+    }
+    if (step.type !== 'assert' || s.pendingLightStep === null)
+        return;
+    const pending = s.results[s.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(s.input.platform, s.deviceId);
+        if (delta) {
+            pending.state_delta = delta;
+            pending.state_delta_available = true;
+        }
+    }
+    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;
+    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.stoppedAt = step.id;
+            break;
+        }
+        const covered = coveredByAssertion(s, step, steps[index + 1]), started = performance.now();
+        if (s.stoppedAt) {
+            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);
+        if (platform === 'android' && debuggerSessions.paused(s.deviceId)) {
+            result.success = false;
+            result.failure_code = 'DEBUGGER_PAUSED';
+            result.retryable = false;
+        }
+        if (step.type === 'assert' && !result?.success && /TIMEOUT/.test(result?.failure_code ?? ''))
+            result.failure_code = 'ASSERTION_TIMEOUT';
+        const success = !!result?.success;
+        lightVerification(s, step, result, covered, success);
+        if (responseMode === 'compact' && ['wait', 'assert'].includes(step.type))
+            result = compactAssertion(result, success);
+        s.results.push({ id: step.id, type: step.type, status: success ? 'passed' : 'failed', success, result, timing: { total_ms: performance.now() - started } });
+        if (!success)
+            s.stoppedAt = step.id;
+    }
+}
+async function journeyResponse(s, started, finishTrace) {
+    const { platform, captureOnFailure, responseMode } = s.input;
+    const failureSnapshot = s.stoppedAt && captureOnFailure && responseMode === 'debug'
+        ? await ToolsObserve.captureDebugSnapshotHandler({ platform, deviceId: s.deviceId, includeScreenshot: false }).catch(() => null) : undefined;
+    const timing = {};
+    for (const step of s.results)
+        for (const [key, value] of Object.entries(step.result?.timing ?? {})) {
+            if (key !== 'total_ms' && typeof value === 'number')
+                timing[key] = (timing[key] ?? 0) + value;
+        }
+    refreshJourneyEvidence(s.results);
+    return wrapResponse({ ...(finishTrace ? { system_trace: await finishTrace() } : {}), success: s.stoppedAt === null, stopped_at_step_id: s.stoppedAt, steps: s.results, ...(failureSnapshot ? { failure_snapshot: failureSnapshot } : {}), timing: responseMode === 'compact' ? { total_ms: performance.now() - started } : { ...timing, total_ms: performance.now() - started } }, responseMode === 'debug');
+}
+export async function handleRunJourney(args) {
+    const parsed = journeySchema.safeParse(args);
+    if (!parsed.success)
+        throw new Error(`INVALID_ARGUMENT: ${parsed.error.message}`);
+    const device = await resolveTargetDevice({ platform: parsed.data.platform, deviceId: parsed.data.deviceId });
+    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 state = { input: parsed.data, deviceId: device.id, results: [], stoppedAt: null, pendingLightStep: null };
+            await runSteps(state);
+            return journeyResponse(state, started, finishTrace);
+        });
+    }
+    finally {
+        await finishTrace?.();
+    }
+}

package/dist/server/handlers/manage.js

@@ -0,0 +1,119 @@
+import { measure } from '../../utils/timing.js';
+import { notifyActionStart } from '../../interact/conditional-action.js';
+import { AndroidManage, iOSManage, ToolsManage } from '../../manage/index.js';
+import { buildActionExecutionResult, captureActionFingerprint, getNumberArg, getStringArg, inferGenericFailure, requireStringArg, wrapResponse } from '../common.js';
+import { interactionControls, actionHandler } from './action-execution.js';
+export async function executeStartApp(args) {
+    const platform = requireStringArg(args, 'platform');
+    const appId = requireStringArg(args, 'appId');
+    const deviceId = getStringArg(args, 'deviceId');
+    const { verificationMode, actionTimeoutMs } = interactionControls(args);
+    const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null;
+    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({
+        actionType: 'start_app',
+        sourceModule: 'server',
+        device: res.device,
+        selector: { appId },
+        success: !!res.appStarted,
+        uiFingerprintBefore,
+        uiFingerprintAfter,
+        failure: res.appStarted ? undefined : inferGenericFailure(res.error),
+        details: {
+            launch_time_ms: res.launchTimeMs,
+            ...(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);
+}
+export async function handleTerminateApp(args) {
+    const platform = requireStringArg(args, 'platform');
+    const appId = requireStringArg(args, 'appId');
+    const deviceId = getStringArg(args, 'deviceId');
+    const res = await (platform === 'android' ? new AndroidManage().terminateApp(appId, deviceId) : new iOSManage().terminateApp(appId, deviceId));
+    const response = { device: res.device, appTerminated: res.appTerminated };
+    return wrapResponse(response);
+}
+export async function executeRestartApp(args) {
+    const platform = requireStringArg(args, 'platform');
+    const appId = requireStringArg(args, 'appId');
+    const deviceId = getStringArg(args, 'deviceId');
+    const { verificationMode, actionTimeoutMs } = interactionControls(args);
+    const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null;
+    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;
+    const result = buildActionExecutionResult({
+        actionType: 'restart_app',
+        sourceModule: 'server',
+        device: res.device,
+        selector: { appId },
+        success: !!res.appRestarted,
+        uiFingerprintBefore,
+        uiFingerprintAfter,
+        failure: res.appRestarted ? undefined : inferGenericFailure(res.error),
+        details: {
+            launch_time_ms: res.launchTimeMs,
+            ...(typeof res.output === 'string' ? { output: res.output } : {}),
+            ...(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);
+}
+export async function handleResetAppData(args) {
+    const platform = requireStringArg(args, 'platform');
+    const appId = requireStringArg(args, 'appId');
+    const deviceId = getStringArg(args, 'deviceId');
+    const res = await (platform === 'android' ? new AndroidManage().resetAppData(appId, deviceId) : new iOSManage().resetAppData(appId, deviceId));
+    const response = { device: res.device, dataCleared: res.dataCleared };
+    return wrapResponse(response);
+}
+export async function handleInstallApp(args) {
+    const platform = requireStringArg(args, 'platform');
+    const projectType = requireStringArg(args, 'projectType');
+    const appPath = requireStringArg(args, 'appPath');
+    const deviceId = getStringArg(args, 'deviceId');
+    const res = await ToolsManage.installAppHandler({ platform, appPath, deviceId, projectType });
+    const response = {
+        device: res.device,
+        installed: res.installed,
+        output: res.output,
+        error: res.error
+    };
+    return wrapResponse(response);
+}
+export async function handleBuildApp(args) {
+    const platform = requireStringArg(args, 'platform');
+    const projectType = requireStringArg(args, 'projectType');
+    const projectPath = requireStringArg(args, 'projectPath');
+    const variant = getStringArg(args, 'variant');
+    const res = await ToolsManage.buildAppHandler({ platform, projectPath, variant, projectType });
+    return wrapResponse(res);
+}
+export async function handleBuildAndInstall(args) {
+    const platform = requireStringArg(args, 'platform');
+    const projectType = requireStringArg(args, 'projectType');
+    const projectPath = requireStringArg(args, 'projectPath');
+    const deviceId = getStringArg(args, 'deviceId');
+    const timeout = getNumberArg(args, 'timeout');
+    const res = await ToolsManage.buildAndInstallHandler({ platform, projectPath, deviceId, timeout, projectType });
+    return {
+        content: [
+            { type: 'text', text: res.ndjson },
+            { type: 'text', text: JSON.stringify(res.result, null, 2) }
+        ]
+    };
+}
+export const handleStartApp = actionHandler('start_app', executeStartApp);
+export const handleRestartApp = actionHandler('restart_app', executeRestartApp);

package/dist/server/handlers/observe.js

@@ -0,0 +1,95 @@
+import { ToolsObserve } from '../../observe/index.js';
+import { withObservationContext } from '../../observe/performance-metrics.js';
+import { getBooleanArg, getNumberArg, getStringArg, requireStringArg, wrapResponse } from '../common.js';
+export async function handleGetLogs(args) {
+    const platform = requireStringArg(args, 'platform');
+    const appId = getStringArg(args, 'appId');
+    const deviceId = getStringArg(args, 'deviceId');
+    const pid = getNumberArg(args, 'pid');
+    const tag = getStringArg(args, 'tag');
+    const level = getStringArg(args, 'level');
+    const contains = getStringArg(args, 'contains');
+    const since_seconds = getNumberArg(args, 'since_seconds');
+    const limit = getNumberArg(args, 'limit');
+    const lines = getNumberArg(args, 'lines');
+    const res = await ToolsObserve.getLogsHandler({ platform, appId, deviceId, pid, tag, level, contains, since_seconds, limit, lines });
+    const filtered = !!(pid || tag || level || contains || since_seconds || appId);
+    return {
+        content: [
+            { type: 'text', text: JSON.stringify({ device: res.device, result: { count: res.logCount, filtered, crashLines: (res.crashLines || []), source: res.source, meta: res.meta || {} } }, null, 2) },
+            { type: 'text', text: JSON.stringify({ logs: res.logs }, null, 2) }
+        ]
+    };
+}
+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 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 }, timing: { total_ms: screenshotMs, screenshot_ms: screenshotMs } }, null, 2) },
+        { type: 'image', data: res.screenshot, mimeType: mime }
+    ];
+    if (res.screenshot_fallback) {
+        content.push({ type: 'text', text: JSON.stringify({ note: 'JPEG fallback included for compatibility', mimeType: res.screenshot_fallback_mime || 'image/jpeg' }) });
+        content.push({ type: 'image', data: res.screenshot_fallback, mimeType: res.screenshot_fallback_mime || 'image/jpeg' });
+    }
+    return { content };
+}
+export async function handleCaptureDebugSnapshot(args) {
+    const reason = getStringArg(args, 'reason');
+    const includeLogs = getBooleanArg(args, 'includeLogs');
+    const logLines = getNumberArg(args, 'logLines');
+    const platform = getStringArg(args, 'platform');
+    const appId = getStringArg(args, 'appId');
+    const deviceId = getStringArg(args, 'deviceId');
+    const sessionId = getStringArg(args, 'sessionId');
+    const includeScreenshot = getBooleanArg(args, 'includeScreenshot');
+    const res = await ToolsObserve.captureDebugSnapshotHandler({ reason, includeLogs, includeScreenshot, logLines, platform, appId, deviceId, sessionId });
+    return wrapResponse(res);
+}
+export async function handleGetUITree(args) {
+    const platform = requireStringArg(args, 'platform');
+    const deviceId = getStringArg(args, '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);
+}
+export async function handleGetCurrentScreen(args) {
+    const deviceId = getStringArg(args, 'deviceId');
+    const res = await ToolsObserve.getCurrentScreenHandler({ deviceId });
+    return wrapResponse(res);
+}
+export async function handleGetScreenFingerprint(args) {
+    const platform = getStringArg(args, 'platform');
+    const deviceId = getStringArg(args, 'deviceId');
+    const res = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId });
+    return wrapResponse(res);
+}
+export async function handleStartLogStream(args) {
+    const platform = getStringArg(args, 'platform') ?? 'android';
+    const packageName = requireStringArg(args, 'packageName');
+    const level = getStringArg(args, 'level') ?? 'error';
+    const sessionId = getStringArg(args, 'sessionId');
+    const deviceId = getStringArg(args, 'deviceId');
+    const res = await ToolsObserve.startLogStreamHandler({ platform, packageName, level, sessionId, deviceId });
+    return wrapResponse(res);
+}
+export async function handleReadLogStream(args) {
+    const platform = getStringArg(args, 'platform');
+    const sessionId = getStringArg(args, 'sessionId');
+    const limit = getNumberArg(args, 'limit');
+    const since = getStringArg(args, 'since');
+    const res = await ToolsObserve.readLogStreamHandler({ platform, sessionId, limit, since });
+    return wrapResponse(res);
+}
+export async function handleStopLogStream(args) {
+    const platform = getStringArg(args, 'platform');
+    const sessionId = getStringArg(args, 'sessionId');
+    const res = await ToolsObserve.stopLogStreamHandler({ platform, sessionId });
+    return wrapResponse(res);
+}

package/dist/server/handlers/payload.js

@@ -0,0 +1,4 @@
+export function payloadOf(response) {
+    const text = response.content.find(item => item.type === 'text')?.text;
+    return text ? JSON.parse(text) : null;
+}

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

@@ -0,0 +1,160 @@
+import { handleDebugger } from './debugger-handlers.js';
+import { debuggerContracts } from '../schemas/debugger-schema.js';
+import { debuggerSessions } 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';
+import { withTiming } from '../../utils/timing.js';
+import { readinessSchema, readinessWaitSchema } from '../schemas/readiness-schema.js';
+import { getAppReadiness } from '../../observe/readiness-service.js';
+import { validateExpectedState } from '../schemas/condition-schema.js';
+import { resolveTargetDevice, withResolvedDevice } from '../../utils/resolve-device.js';
+import { wrapResponse, wrapToolError } from '../common.js';
+import { handleTerminateApp, handleResetAppData, handleInstallApp, handleBuildApp, handleBuildAndInstall, handleStartApp, handleRestartApp } from './manage.js';
+import { handleGetLogs, handleCaptureScreenshot, handleCaptureDebugSnapshot, handleGetUITree, handleGetCurrentScreen, handleGetScreenFingerprint, handleStartLogStream, handleReadLogStream, handleStopLogStream } from './observe.js';
+import { handleWaitForScreenChange, handleExpectScreen, handleExpectElementVisible, handleExpectState, handleAdjustControl, handleWaitForUI, handleWaitForUIChange, handleFindElement } from './interact.js';
+import { handleTap, handleTapElement, handleSwipe, handleScrollToElement, handleTypeText, handlePressBack } from './input.js';
+import { handleRunJourney } from './journey.js';
+import { handleListDevices, handleGetSystemStatus, handleClassifyActionOutcome, handleGetNetworkActivity, handleSystemTrace } from './diagnostic.js';
+import { correlatedHandler } from './action-execution.js';
+const systemTraceToolNames = new Set(systemTraceTools.map(tool => tool.name));
+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,
+    reset_app_data: handleResetAppData,
+    install_app: handleInstallApp,
+    build_app: handleBuildApp,
+    build_and_install: handleBuildAndInstall,
+    get_logs: handleGetLogs,
+    list_devices: handleListDevices,
+    get_system_status: handleGetSystemStatus,
+    capture_screenshot: handleCaptureScreenshot,
+    capture_debug_snapshot: handleCaptureDebugSnapshot,
+    get_ui_tree: handleGetUITree,
+    get_current_screen: handleGetCurrentScreen,
+    get_screen_fingerprint: handleGetScreenFingerprint,
+    wait_for_screen_change: handleWaitForScreenChange,
+    wait_for_ui_change: handleWaitForUIChange,
+    expect_screen: handleExpectScreen,
+    expect_element_visible: handleExpectElementVisible,
+    expect_state: handleExpectState,
+    adjust_control: handleAdjustControl,
+    wait_for_ui: handleWaitForUI,
+    find_element: handleFindElement,
+    tap: handleTap,
+    tap_element: handleTapElement,
+    run_journey: handleRunJourney,
+    swipe: handleSwipe,
+    scroll_to_element: handleScrollToElement,
+    type_text: handleTypeText,
+    press_back: handlePressBack,
+    start_log_stream: handleStartLogStream,
+    read_log_stream: handleReadLogStream,
+    stop_log_stream: handleStopLogStream,
+    classify_action_outcome: handleClassifyActionOutcome,
+    get_network_activity: handleGetNetworkActivity
+};
+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');
+}
+async function dispatchGuarded(device, args, handler, addTiming) {
+    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);
+    }));
+}
+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') {
+        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 */ }
+        }
+    }
+}
+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}`);
+    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 {
+            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 dispatchGuarded(device, args, handler, addTiming);
+            }
+            const response = await handler(args);
+            attachPausedObservation(name, args, response);
+            return addTiming(response);
+        }
+        catch (error) {
+            if (error instanceof TraceError)
+                return { ...wrapResponse({ error: { tool: name, code: error.code, message: error.message } }), isError: true };
+            console.error(`Error executing tool ${name}:`, error);
+            return addTiming(wrapToolError(name, error));
+        }
+    });
+}

package/dist/server/schemas/condition-schema.js

@@ -0,0 +1,2 @@
+// Compatibility export for existing server consumers.
+export * from '../../contracts/condition.js';

package/dist/server/schemas/debugger-schema.js

@@ -0,0 +1,47 @@
+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 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_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.' },
+    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.' },
+    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.' }
+};
+// Derive JSON schemas and runtime validation from the same small Zod field vocabulary.
+function jsonField(schema) {
+    if (schema instanceof z.ZodOptional)
+        return jsonField(schema.unwrap());
+    if (schema instanceof z.ZodLiteral)
+        return { type: 'string', enum: [schema.value] };
+    if (schema instanceof z.ZodEnum)
+        return { type: 'string', enum: schema.options };
+    if (schema instanceof z.ZodString) {
+        const json = z.toJSONSchema(schema);
+        return { type: 'string', minLength: 1, maxLength: 512, ...(json.pattern ? { pattern: json.pattern } : {}) };
+    }
+    if (schema instanceof z.ZodNumber)
+        return { type: 'integer', minimum: schema.minValue, maximum: schema.maxValue };
+    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()
+    }]));
+export const debuggerTools = Object.entries(debuggerContracts).map(([name, spec]) => ({
+    name, description: spec.description,
+    inputSchema: {
+        type: 'object', additionalProperties: false,
+        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/{journey-schema.js → schemas/journey-schema.js}

@@ -1,19 +1,12 @@
+import { verificationModeSchema, responseModeSchema, verificationModeJson } from '../../contracts/execution-controls.js';
+import { waitForSchema as waitFor, targetFields as target, exactlyOneTarget, targetJson, oneTargetJson } from '../../contracts/target.js';
+export { tapElementControlsSchema } from '../../contracts/target.js';
+import { selectorSchema as selector, selectorJson } from '../../contracts/selector.js';
 import { z } from 'zod';
 import { expectedStateSchema, expectedStateJson } from './condition-schema.js';
-const selector = z.object({
-    text: z.string().min(1).optional(), resource_id: z.string().min(1).optional(),
-    accessibility_id: z.string().min(1).optional(), contains: z.boolean().optional()
-}).strict().refine(value => !!(value.text || value.resource_id || value.accessibility_id), 'Selector requires a target');
-const verificationMode = z.enum(['none', 'light', 'full']);
+const verificationMode = verificationModeSchema;
 const timeoutMs = z.number().int().min(100).max(60000).optional();
 const pollIntervalMs = z.number().int().min(50).max(1000).optional();
-const waitFor = z.object({
-    condition: z.enum(['exists', 'visible', 'clickable']).optional(),
-    timeoutMs: z.number().int().min(100).max(10000).optional(), pollIntervalMs,
-    match: z.object({ index: z.number().int().nonnegative().optional() }).strict().optional()
-}).strict();
-const target = { selector: selector.optional(), elementId: z.string().min(1).optional() };
-const exactlyOneTarget = (value) => Number(!!value.selector) + Number(!!value.elementId) === 1;
 const assertion = z.union([
     z.object({ kind: z.literal('element_visible'), selector }).strict(),
     z.object({ kind: z.literal('element_absent'), selector }).strict(),
@@ -27,22 +20,15 @@ const step = z.union([
     z.object({ id, type: z.literal('wait'), selector, condition: z.enum(['exists', 'not_exists', 'visible', 'clickable']).optional(), timeoutMs, pollIntervalMs }).strict(),
     z.object({ id, type: z.literal('assert'), assertion, timeoutMs, pollIntervalMs }).strict()
 ]);
-export const tapElementControlsSchema = z.object({
-    elementId: z.string().min(1).optional(), selector: selector.optional(), waitFor: waitFor.optional()
-}).strict().refine(value => Number(!!value.elementId) + Number(!!value.selector) === 1 && (!value.elementId || !value.waitFor));
 export const journeySchema = z.object({
     platform: z.enum(['android', 'ios']), deviceId: z.string().min(1).optional(),
-    responseMode: z.enum(['compact', 'debug']).default('compact'), captureOnFailure: z.boolean().default(false),
+    systemTraceId: z.string().uuid().optional(),
+    responseMode: responseModeSchema.default('compact'), captureOnFailure: z.boolean().default(false),
     defaults: z.object({ verificationMode: verificationMode.optional(), actionTimeoutMs: z.number().int().finite().optional(), verificationTimeoutMs: z.number().int().finite().optional() }).strict().optional(),
     steps: z.array(step).min(1).max(50)
 }).strict().refine(value => new Set(value.steps.map(step => step.id)).size === value.steps.length, 'Step IDs must be unique');
-const selectorJson = { type: 'object', additionalProperties: false, properties: {
-        text: { type: 'string', minLength: 1 }, resource_id: { type: 'string', minLength: 1 }, accessibility_id: { type: 'string', minLength: 1 }, contains: { type: 'boolean' }
-    }, anyOf: ['text', 'resource_id', 'accessibility_id'].map(key => ({ required: [key] })) };
-const targetJson = { selector: selectorJson, elementId: { type: 'string', minLength: 1 } };
-const oneTargetJson = [{ required: ['selector'], not: { required: ['elementId'] } }, { required: ['elementId'], not: { required: ['selector'] } }];
 const intervalJson = { timeoutMs: { type: 'integer', minimum: 100, maximum: 60000 }, pollIntervalMs: { type: 'integer', minimum: 50, maximum: 1000 } };
-const modeJson = { type: 'string', enum: ['none', 'light', 'full'] };
+const modeJson = verificationModeJson;
 const objectJson = (properties, required, extra = {}) => ({ type: 'object', additionalProperties: false, properties, required, ...extra });
 export const journeyStepsJson = {
     type: 'array', minItems: 1, maxItems: 50, items: { oneOf: [