mobile-debug-mcp 0.34.0 → 0.36.0

package/dist/server/handlers/action-execution.js

@@ -0,0 +1,163 @@
+import { payloadOf } from './payload.js';
+import { correlatedHandler } from './correlation.js';
+import { interactionControls } from '../../contracts/execution-controls.js';
+import { currentEvidenceActionId, markEvidenceVerification } from '../../observe/evidence.js';
+import { measure, withTiming } from '../../utils/timing.js';
+import { randomUUID } from 'node:crypto';
+import { runWithBudget } from '../../utils/operation-budget.js';
+import { validateExpectedState } from '../schemas/condition-schema.js';
+import { conditionFailureCode, createConditionalAction, withConditionalAction } from '../../interact/conditional-action.js';
+import { resolveTargetDevice, withResolvedDevice } from '../../utils/resolve-device.js';
+import { ToolsObserve } from '../../observe/index.js';
+import { recordObservationEvent, withObservationContext } from '../../observe/performance-metrics.js';
+import { buildActionExecutionResult, wrapResponse, wrapToolError } from '../common.js';
+export 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 createAction(type, args, timing) {
+    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);
+    const unbounded = args._journey !== true && controls.verificationMode === 'full' && controls.responseMode === 'debug' && controls.actionTimeoutMs === undefined;
+    return {
+        type, args, timing, started, controls, condition, budgetMs, unbounded,
+        result: {}, dispatchStarted: false, blocked: false,
+        delta: undefined, observationAvailable: false
+    };
+}
+async function dispatchAction(s, execute) {
+    const { type, args, controls, condition, budgetMs } = s;
+    const dispatchWithBudget = (timeoutMs) => runWithBudget(timeoutMs, async (budget) => {
+        try {
+            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 {
+            s.dispatchStarted = budget.dispatchStarted;
+        }
+    });
+    try {
+        // Omitted controls retain the existing adapter budgets.
+        s.result = s.unbounded
+            ? await dispatchWithBudget(Infinity) : await dispatchWithBudget(budgetMs);
+        if (s.result.success)
+            s.dispatchStarted = true;
+    }
+    catch (error) {
+        if (!condition && controls.verificationMode === 'full' && controls.responseMode === 'debug' && controls.actionTimeoutMs === undefined && !/TIMEOUT|timed out/i.test(String(error)))
+            return wrapToolError(type, error);
+        s.result = { success: false, failure_code: /TIMEOUT|timed out/i.test(String(error)) ? 'ACTION_TIMEOUT' : 'UNKNOWN', error: String(error) };
+    }
+}
+function rejectCondition(s) {
+    const { condition, type } = s;
+    s.blocked = !!condition && ['mismatch', 'unavailable'].includes(condition.result.status);
+    if (s.blocked && condition) {
+        s.dispatchStarted = false;
+        s.result = buildActionExecutionResult({
+            actionType: type, sourceModule: 'server', device: condition.result.observed?.device,
+            selector: s.result?.target?.selector ?? null, resolved: s.result?.target?.resolved,
+            success: false, uiFingerprintBefore: s.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 } }]
+        });
+    }
+}
+function normalizeAction(s) {
+    const { type, args, timing, controls } = s;
+    rejectCondition(s);
+    if (s.result.failure_code === 'TIMEOUT' || /ACTION_TIMEOUT|timeout/i.test(String(s.result.error ?? s.result.reason ?? s.result.details?.error ?? '')))
+        s.result.failure_code = 'ACTION_TIMEOUT';
+    if (s.result.failure_code === 'ACTION_TIMEOUT')
+        s.result.retryable = !s.dispatchStarted;
+    if (!s.result.success && typeof s.result.retryable !== 'boolean')
+        s.result.retryable = !s.dispatchStarted;
+    s.result.action_id ??= currentEvidenceActionId() ?? randomUUID();
+    s.result.action_type ??= type;
+    recordObservationEvent({
+        step_id: args._stepId,
+        action_type: type,
+        dispatch_ms: timing.dispatch_ms,
+        verification_mode: controls.verificationMode,
+        dispatch_started: s.dispatchStarted
+    });
+}
+async function verifyAction(s) {
+    const { args, controls } = s;
+    if (s.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 ?? s.result.device?.platform, deviceId: args.deviceId ?? s.result.device?.id })))).catch(() => null);
+        markEvidenceVerification();
+        s.observationAvailable = !!tree && !tree.error;
+        recordObservationEvent({
+            verification_budget_ms: controls.verificationTimeoutMs,
+            verification_elapsed_ms: performance.now() - verificationStarted,
+            verification_outcome: s.observationAvailable ? 'observed' : 'unavailable',
+            verification_budget_expired: !s.observationAvailable && performance.now() - verificationStarted >= controls.verificationTimeoutMs
+        });
+        if (s.observationAvailable && tree?.device)
+            s.delta = ToolsObserve.getLatestStateDelta(tree.device.platform, tree.device.id) ?? undefined;
+    }
+    if (!s.blocked && controls.verificationMode === 'full' && s.dispatchStarted)
+        markEvidenceVerification();
+}
+function actionResponse(s) {
+    const { timing, started, controls, condition, budgetMs } = s;
+    const compact = compactAction(s.result, controls.verificationMode, s.dispatchStarted, s.delta, performance.now() - started);
+    if (s.blocked)
+        compact.verification.status = 'not_requested';
+    if (s.result.success && controls.verificationMode === 'light' && !s.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: !!s.delta } : {}),
+        ...(s.result.success && controls.verificationMode === 'light' && !s.observationAvailable ? { verification_diagnostic: { code: 'VERIFICATION_UNAVAILABLE', retryable: true } } : {})
+    };
+    return wrapResponse(controls.responseMode === 'compact' ? evidence : {
+        ...s.result, ...evidence, timing: { ...timing, total_ms: performance.now() - started },
+        effective_controls: { ...controls, actionTimeoutMs: s.unbounded ? null : budgetMs, timeout_bound: !(s.unbounded) }
+    }, controls.responseMode === 'debug');
+}
+export function actionHandler(type, execute) {
+    return correlatedHandler(type, async (args) => {
+        const timing = {};
+        return withTiming(timing, async () => {
+            const state = createAction(type, args, timing);
+            const error = await dispatchAction(state, execute);
+            if (error)
+                return error;
+            normalizeAction(state);
+            await verifyAction(state);
+            return actionResponse(state);
+        });
+    }, true);
+}
+export { interactionControls, correlatedHandler, payloadOf };

package/dist/server/handlers/correlation.js

@@ -0,0 +1,23 @@
+import { TraceError } from '../../observe/system-trace.js';
+import { withEvidence, validateActionRef } from '../../observe/evidence.js';
+import { wrapResponse, wrapToolError } from '../common.js';
+export 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;
+    };
+}

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

@@ -0,0 +1,67 @@
+import { iosCapabilities } from '../../debugger/ios-worker.js';
+import { debuggerResponse } from './debugger-response.js';
+import { classify } from '../../debugger/diagnostics.js';
+import { debuggerContracts } from '../schemas/debugger-schema.js';
+import { debuggerSessions, iosDebuggerSessions, debuggerCapabilities } from '../../debugger/sessions.js';
+import { DebuggerError, withDebuggerBudget } from '../../debugger/worker.js';
+import { wrapResponse } from '../common.js';
+function failure(code, summary = {}, diagnostic, command = '', mode = 'debug') {
+    return {
+        ...wrapResponse(debuggerResponse(command, mode, {
+            debug_session_id: null, device: null, target: null, state: null,
+            captured_at_ms: Date.now(), capabilities: debuggerCapabilities, limitations: [], cleanup: null,
+            ...summary, success: false, error: { code, message: code, retryable: false, ...(diagnostic ? { diagnostic } : {}) }
+        })), isError: true
+    };
+}
+export async function handleDebugger(name, args, signal) {
+    const parsed = debuggerContracts[name].schema.safeParse(args);
+    if (!parsed.success)
+        return failure('INVALID_ARGUMENT');
+    const { responseMode, ...input } = parsed.data;
+    const a = input;
+    const command = debuggerContracts[name].command;
+    const sessions = selectSessions(a);
+    try {
+        if (signal?.aborted)
+            throw new DebuggerError('DEBUGGER_CANCELLED');
+        const result = await withDebuggerBudget(a.timeoutMs, signal, async () => command === 'capabilities' ? await sessions.capabilities(a.deviceId, a.appId, a.processId) :
+            command === 'attach' ? await sessions.attach(a.deviceId, a.appId, a.processId, a.timeoutMs) :
+                await sessions.command(a.debugSessionId, command, { ...a, signal: command === 'events' ? signal : undefined }, a.timeoutMs));
+        if (signal?.aborted && command === 'capabilities')
+            throw new DebuggerError('DEBUGGER_CANCELLED');
+        const payload = sessions === iosDebuggerSessions ? iosDiagnostics(result) : result;
+        return { ...wrapResponse(debuggerResponse(command, responseMode, payload)), ...(!result.success ? { isError: true } : {}) };
+    }
+    catch (e) {
+        const error = classify(e, 'unknown', 'DEBUGGER_WORKER_FAILED');
+        const code = error.code;
+        let summary = {};
+        if (a.debugSessionId) {
+            try {
+                summary = sessions.summary(a.debugSessionId);
+            }
+            catch { /* Unknown session */ }
+        }
+        const response = failure(code, {
+            ...(sessions === iosDebuggerSessions ? { capabilities: iosCapabilities } : {}),
+            debug_session_id: a.debugSessionId ?? null,
+            device: a.deviceId ? { platform: a.platform ?? 'android', id: a.deviceId } : null, ...summary
+        }, code === 'DEBUGGER_CLEANUP_FAILED' ? summary.error?.diagnostic : error.diagnostic, command, responseMode);
+        if (sessions === iosDebuggerSessions)
+            response.content[0].text = JSON.stringify(iosDiagnostics(JSON.parse(response.content[0].text)));
+        return response;
+    }
+}
+function selectSessions(a) {
+    return a.platform === 'ios' || (a.debugSessionId && iosDebuggerSessions.owns(a.debugSessionId)) ? iosDebuggerSessions : debuggerSessions;
+}
+function iosRecovery(d) {
+    return { ...d, recovery: d.recovery.replace('JDK 17+ availability, including java, javac and jdk.jdi.', 'Xcode and its Swift-enabled LLDB/Python availability.').replace('JDK compiler and worker source/cache', 'LLDB worker source').replace('Java worker', 'LLDB worker').replace('ADB server', 'simulator') };
+}
+function iosDiagnostics(value) {
+    const result = { ...value };
+    const error = value.error;
+    return { ...result, ...(error?.diagnostic ? { error: { ...error, diagnostic: iosRecovery(error.diagnostic) } } : {}),
+        ...(Array.isArray(value.diagnostics) ? { diagnostics: value.diagnostics.map(iosRecovery) } : {}) };
+}

package/dist/server/handlers/debugger-response.js

@@ -0,0 +1,9 @@
+/** Omit only repeated target metadata; preserve all execution and failure evidence. */
+export function debuggerResponse(command, mode, payload) {
+    if (mode !== 'compact' || ['capabilities', 'attach', 'state'].includes(command) || payload.debug_session_id == null)
+        return payload;
+    const result = { ...payload };
+    for (const field of ['device', 'target', 'capabilities'])
+        delete result[field];
+    return result;
+}

package/dist/server/handlers/diagnostic.js

@@ -0,0 +1,77 @@
+import { systemTraces, TraceError } from '../../observe/system-trace.js';
+import { traceTargetSchema, traceStartSchema, traceControlSchema } from '../schemas/system-trace-schema.js';
+import { resolveTargetDevice } from '../../utils/resolve-device.js';
+import { ToolsManage } from '../../manage/index.js';
+import { classifyActionOutcome } from '../../interact/classify.js';
+import { ToolsNetwork } from '../../observe/network/index.js';
+import { getSystemStatus } from '../../system/index.js';
+import { getArrayArg, getBooleanArg, getStringArg, requireBooleanArg, requireStringArg, wrapResponse } from '../common.js';
+export async function handleListDevices(args) {
+    const platform = getStringArg(args, 'platform');
+    const appId = getStringArg(args, 'appId');
+    const res = await ToolsManage.listDevicesHandler({ platform, appId });
+    return wrapResponse(res);
+}
+export async function handleGetSystemStatus() {
+    const result = await getSystemStatus();
+    return wrapResponse(result);
+}
+export function handleClassifyActionOutcome(args) {
+    const uiChanged = requireBooleanArg(args, 'uiChanged');
+    const expectedElementVisible = getBooleanArg(args, 'expectedElementVisible');
+    const actionType = getStringArg(args, 'actionType');
+    const networkRequests = getArrayArg(args, 'networkRequests');
+    const hasLogErrors = getBooleanArg(args, 'hasLogErrors');
+    const result = classifyActionOutcome({
+        uiChanged,
+        expectedElementVisible: expectedElementVisible ?? null,
+        actionType: actionType ?? null,
+        networkRequests: networkRequests ?? null,
+        hasLogErrors: hasLogErrors ?? null
+    });
+    return Promise.resolve(wrapResponse(result));
+}
+export async function handleGetNetworkActivity(args) {
+    const platform = requireStringArg(args, 'platform');
+    const deviceId = getStringArg(args, 'deviceId');
+    const result = await ToolsNetwork.getNetworkActivity({ platform, deviceId });
+    return wrapResponse(result);
+}
+export 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' && (target.appId !== undefined || target.template !== undefined))
+            throw new TraceError('INVALID_ARGUMENT');
+        if (target.platform === 'ios') {
+            return handleIosTrace(name, target);
+        }
+        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 } : {}) };
+}
+async function handleIosTrace(name, target) {
+    if (!target.deviceId || (name === 'start_system_trace' && !target.appId))
+        throw new TraceError('INVALID_ARGUMENT');
+    if (name === 'get_system_trace_capabilities')
+        return wrapResponse(await systemTraces.iosCapabilities(target.deviceId, target.appId, target.template));
+    const result = await systemTraces.start(target.deviceId, target.durationMs, { appId: target.appId, template: target.template });
+    return { ...wrapResponse(result), ...(result.state === 'failed' ? { isError: true } : {}) };
+}

package/dist/server/handlers/handler-types.js

@@ -0,0 +1 @@
+export {};

package/dist/server/handlers/input.js

@@ -0,0 +1,154 @@
+import { measure } from '../../utils/timing.js';
+import { runWithBudget } from '../../utils/operation-budget.js';
+import { tapElementControlsSchema } from '../schemas/journey-schema.js';
+import { notifyActionStart } from '../../interact/conditional-action.js';
+import { ToolsInteract } from '../../interact/index.js';
+import { recordObservationConsumer, recordObservationEvent, withObservationContext } from '../../observe/performance-metrics.js';
+import { buildActionExecutionResult, captureActionFingerprint, getNumberArg, getStringArg, inferGenericFailure, inferScrollFailure, requireNumberArg, requireObjectArg, requireStringArg, wrapResponse } from '../common.js';
+import { interactionControls, actionHandler } from './action-execution.js';
+export 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 { verificationMode, actionTimeoutMs } = interactionControls(args);
+    const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null;
+    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({
+        actionType: 'tap',
+        sourceModule: 'server',
+        selector: { x, y },
+        success: !!res.success,
+        uiFingerprintBefore,
+        uiFingerprintAfter,
+        failure: res.success ? undefined : inferGenericFailure(res.error)
+    });
+    return wrapResponse(result);
+}
+export 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 = controls.data.waitFor;
+        const targetStarted = performance.now();
+        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;
+    }
+    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') }));
+    return wrapResponse(res);
+}
+export async function executeSwipe(args) {
+    const platform = getStringArg(args, 'platform') ?? 'android';
+    const x1 = requireNumberArg(args, 'x1');
+    const y1 = requireNumberArg(args, 'y1');
+    const x2 = requireNumberArg(args, 'x2');
+    const y2 = requireNumberArg(args, 'y2');
+    const duration = requireNumberArg(args, 'duration');
+    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', () => 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 },
+        success: !!res.success,
+        uiFingerprintBefore,
+        uiFingerprintAfter,
+        failure: res.success ? undefined : inferGenericFailure(res.error)
+    });
+    return wrapResponse(result);
+}
+export 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 { verificationMode } = interactionControls(args);
+    const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null;
+    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({
+        actionType: 'scroll_to_element',
+        sourceModule: 'server',
+        selector: selector ?? null,
+        resolved: res?.success && res?.element ? {
+            elementId: null,
+            text: res.element.text ?? null,
+            resource_id: res.element.resourceId ?? null,
+            accessibility_id: res.element.contentDesc ?? null,
+            class: res.element.className ?? null,
+            bounds: res.element.bounds ?? null,
+            index: null
+        } : null,
+        success: !!res.success,
+        uiFingerprintBefore,
+        uiFingerprintAfter,
+        failure: res.success ? undefined : inferScrollFailure(res.reason)
+    });
+    return wrapResponse(result);
+}
+export async function executeTypeText(args) {
+    const text = requireStringArg(args, 'text');
+    const deviceId = getStringArg(args, 'deviceId');
+    const { verificationMode, actionTimeoutMs } = interactionControls(args);
+    const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint('android', deviceId)) : null;
+    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({
+        actionType: 'type_text',
+        sourceModule: 'server',
+        selector: { text },
+        success: !!res.success,
+        uiFingerprintBefore,
+        uiFingerprintAfter,
+        failure: res.success ? undefined : inferGenericFailure(res.error)
+    });
+    return wrapResponse(result);
+}
+export 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;
+    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({
+        actionType: 'press_back',
+        sourceModule: 'server',
+        selector: { key: 'back' },
+        success: !!res.success,
+        uiFingerprintBefore,
+        uiFingerprintAfter,
+        failure: res.success ? undefined : inferGenericFailure(res.error)
+    });
+    return wrapResponse(result);
+}
+export const handleTap = actionHandler('tap', executeTap);
+export const handleTapElement = actionHandler('tap_element', executeTapElement);
+export const handleSwipe = actionHandler('swipe', executeSwipe);
+export const handleScrollToElement = actionHandler('scroll_to_element', executeScrollToElement);
+export const handleTypeText = actionHandler('type_text', executeTypeText);
+export const handlePressBack = actionHandler('press_back', executePressBack);

package/dist/server/handlers/interact.js

@@ -0,0 +1,113 @@
+import { markEvidenceVerification } from '../../observe/evidence.js';
+import { withReadyWait } from '../../observe/readiness-service.js';
+import { ToolsInteract } from '../../interact/index.js';
+import { recordObservationEvent, withObservationContext } from '../../observe/performance-metrics.js';
+import { getBooleanArg, getNumberArg, getObjectArg, getStringArg, requireNumberArg, requireObjectArg, requireStringArg, wrapResponse } from '../common.js';
+export async function handleWaitForScreenChange(args) {
+    const platform = getStringArg(args, 'platform');
+    const previousFingerprint = requireStringArg(args, 'previousFingerprint');
+    const timeoutMs = getNumberArg(args, 'timeoutMs');
+    const pollIntervalMs = getNumberArg(args, 'pollIntervalMs');
+    const deviceId = getStringArg(args, 'deviceId');
+    const res = await ToolsInteract.waitForScreenChangeHandler({ platform, previousFingerprint, timeoutMs, pollIntervalMs, deviceId });
+    return wrapResponse(res);
+}
+export async function handleExpectScreen(args) {
+    const platform = getStringArg(args, 'platform');
+    const fingerprint = getStringArg(args, 'fingerprint');
+    const screen = getStringArg(args, 'screen');
+    const deviceId = getStringArg(args, 'deviceId');
+    const res = await ToolsInteract.expectScreenHandler({ platform, fingerprint, screen, deviceId });
+    return wrapResponse(res);
+}
+export async function handleExpectElementVisible(args) {
+    const selector = requireObjectArg(args, 'selector');
+    const element_id = getStringArg(args, 'element_id');
+    const timeout_ms = getNumberArg(args, 'timeout_ms');
+    const poll_interval_ms = getNumberArg(args, 'poll_interval_ms');
+    const platform = getStringArg(args, 'platform');
+    const deviceId = getStringArg(args, 'deviceId');
+    const res = await ToolsInteract.expectElementVisibleHandler({ selector, element_id, timeout_ms, poll_interval_ms, platform, deviceId });
+    return wrapResponse(res);
+}
+export async function handleExpectState(args) {
+    const selector = getObjectArg(args, 'selector');
+    const element_id = getStringArg(args, 'element_id');
+    const property = requireStringArg(args, 'property');
+    const platform = getStringArg(args, 'platform');
+    const deviceId = getStringArg(args, 'deviceId');
+    if (!selector && !element_id) {
+        throw new Error('Missing selector or element_id argument');
+    }
+    if (!Object.prototype.hasOwnProperty.call(args, 'expected')) {
+        throw new Error('Missing expected argument');
+    }
+    const expected = args.expected;
+    const res = await ToolsInteract.expectStateHandler({ selector: selector ?? undefined, element_id: element_id ?? undefined, property, expected, platform, deviceId });
+    return wrapResponse(res);
+}
+export async function handleAdjustControl(args) {
+    const selector = getObjectArg(args, 'selector');
+    const element_id = getStringArg(args, 'element_id');
+    const property = getStringArg(args, 'property') ?? 'value';
+    const targetValue = requireNumberArg(args, 'targetValue');
+    const tolerance = getNumberArg(args, 'tolerance');
+    const maxAttempts = getNumberArg(args, 'maxAttempts');
+    const platform = getStringArg(args, 'platform');
+    const deviceId = getStringArg(args, 'deviceId');
+    if ((!selector && !element_id) || (selector && element_id)) {
+        throw new Error('Exactly one of selector or element_id argument is required');
+    }
+    const res = await ToolsInteract.adjustControlHandler({
+        selector: selector ?? undefined,
+        element_id: element_id ?? undefined,
+        property,
+        targetValue,
+        tolerance,
+        maxAttempts,
+        platform,
+        deviceId
+    });
+    markEvidenceVerification();
+    return wrapResponse(res);
+}
+export 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;
+    const poll_interval_ms = getNumberArg(args, 'poll_interval_ms') ?? 300;
+    const match = getObjectArg(args, 'match');
+    const retry = getObjectArg(args, 'retry');
+    const platform = getStringArg(args, 'platform');
+    const deviceId = getStringArg(args, '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);
+}
+export 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;
+    const stability_window_ms = getNumberArg(args, 'stability_window_ms') ?? 300;
+    const expected_change = getStringArg(args, 'expected_change');
+    const scope = getStringArg(args, 'scope');
+    const target = getStringArg(args, '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);
+}
+export async function handleFindElement(args) {
+    const query = requireStringArg(args, 'query');
+    const exact = getBooleanArg(args, 'exact') ?? false;
+    const timeoutMs = getNumberArg(args, 'timeoutMs') ?? 3000;
+    const platform = getStringArg(args, 'platform');
+    const deviceId = getStringArg(args, '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);
+}

package/dist/server/handlers/journey-assertions.js

@@ -0,0 +1,35 @@
+import { ToolsInteract } from '../../interact/index.js';
+import { ToolsObserve } from '../../observe/index.js';
+export 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 };
+}
+export 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 };
+}