mobile-debug-mcp 0.36.0 → 0.37.0

package/dist/server/definitions/manage.js

@@ -183,11 +183,12 @@ Failure Handling:
     },
     {
         name: 'list_devices',
-        description: 'List connected devices and their metadata (android + ios).',
+        description: 'List Android devices and iOS simulators. Supply appId for device-specific installation status; unknown checks do not imply absence.',
         inputSchema: {
             type: 'object',
             properties: {
-                platform: { type: 'string', enum: ['android', 'ios'] }
+                platform: { type: 'string', enum: ['android', 'ios'] },
+                appId: { type: 'string', pattern: '^[A-Za-z0-9_-]+(\\.[A-Za-z0-9_-]+)*$', description: 'Optional package or bundle identifier to check on each device.' }
             }
         }
     }

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

@@ -1,3 +1,4 @@
+import { observeDeviceReadiness, unknownDeviceReadiness } from '../../observe/device-readiness.js';
 import { payloadOf } from './payload.js';
 import { correlatedHandler } from './correlation.js';
 import { interactionControls } from '../../contracts/execution-controls.js';
@@ -7,13 +8,14 @@ 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 { resolveTargetDevice, withResolvedDevice, currentResolvedDevice } 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,
+        ...(result.device_readiness ? { device_readiness: result.device_readiness } : {}),
         action_type: result.action_type,
         success: !!result.success,
         lifecycle_state: result.success ? (verificationMode === 'full' ? result.lifecycle_state : 'pending_verification') : 'failed',
@@ -39,15 +41,27 @@ function createAction(type, args, timing) {
         delta: undefined, observationAvailable: false
     };
 }
+async function executeWithDeviceState(args, execute) {
+    const result = payloadOf(await execute(args));
+    result.device_readiness = await observeDeviceReadiness(result.device ?? currentResolvedDevice());
+    return result;
+}
+function actionError(type, error) {
+    const response = wrapToolError(type, error);
+    const item = response.content.find(item => item.type === 'text');
+    if (item?.text)
+        item.text = JSON.stringify({ ...JSON.parse(item.text), device_readiness: unknownDeviceReadiness('DEVICE_TARGET_UNAVAILABLE') });
+    return response;
+}
 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 executeWithDeviceState(args, execute);
             return await withConditionalAction(condition, async () => {
                 const device = await resolveTargetDevice({ platform: condition.platform, deviceId: condition.deviceId });
-                return withResolvedDevice(device, async () => payloadOf(await execute(args)));
+                return withResolvedDevice(device, async () => executeWithDeviceState(args, execute));
             });
         }
         finally {
@@ -63,8 +77,8 @@ async function dispatchAction(s, execute) {
     }
     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) };
+            return actionError(type, error);
+        s.result = { device_readiness: unknownDeviceReadiness('DEVICE_OBSERVATION_UNAVAILABLE'), success: false, failure_code: /TIMEOUT|timed out/i.test(String(error)) ? 'ACTION_TIMEOUT' : 'UNKNOWN', error: String(error) };
     }
 }
 function rejectCondition(s) {
@@ -72,6 +86,7 @@ function rejectCondition(s) {
     s.blocked = !!condition && ['mismatch', 'unavailable'].includes(condition.result.status);
     if (s.blocked && condition) {
         s.dispatchStarted = false;
+        const deviceReadiness = s.result.device_readiness;
         s.result = buildActionExecutionResult({
             actionType: type, sourceModule: 'server', device: condition.result.observed?.device,
             selector: s.result?.target?.selector ?? null, resolved: s.result?.target?.resolved,
@@ -79,6 +94,7 @@ function rejectCondition(s) {
             failure: { failureCode: conditionFailureCode(condition), retryable: false },
             traceSteps: [{ stage: 'verify', timestamp: Date.now(), result: 'failure', attempt_index: 0, metadata: { phase: 'precondition', dispatch_started: false } }]
         });
+        s.result.device_readiness = deviceReadiness;
     }
 }
 function normalizeAction(s) {
@@ -129,19 +145,12 @@ function actionResponse(s) {
     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
+            condition: 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 : {
+    return wrapResponse({
         ...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');

package/dist/server/handlers/compact-interaction.js

@@ -0,0 +1,106 @@
+import { evidenceSessionId } from '../../observe/evidence.js';
+import { interactionDiagnostics } from './interaction-diagnostics.js';
+import { object, pick, boundedValue, boundedState, observedState, deltaSummary } from './compact-state.js';
+export const compactInteractionTools = new Set(['start_app', 'restart_app', 'tap', 'tap_element', 'swipe', 'scroll_to_element', 'type_text', 'press_back', 'run_journey']);
+const bytes = (value) => Buffer.byteLength(JSON.stringify(value));
+// IDs are preserved verbatim; their allowance counts the UTF-8 wire encoding.
+const idBytes = (value) => bytes(String(value ?? '')) - 2;
+const deviceBytes = (evidence) => idBytes(object(object(evidence).device).id);
+function compactEvidence(value) {
+    const e = object(value);
+    return { ...pick(e, ['session_id', 'correlation_id', 'action_id', 'device']),
+        ...(e.association_reason ? pick(e, ['association', 'association_reason']) : {}),
+        ...(object(e.trace_context).trace_id ? { trace_id: object(e.trace_context).trace_id } : {}) };
+}
+function conditionSummary(value) {
+    const c = object(value);
+    return { ...pick(c, ['status', 'reason']), observed: c.observed == null ? null : pick(c.observed, ['snapshot_session_id', 'snapshot_revision', 'captured_at_ms']) };
+}
+function addCompactError(result, error, name) {
+    const message = typeof error === 'string' ? error : object(error).message;
+    result.error = { ...pick(error, ['code']), message: boundedValue(message) };
+    result.action_type ??= name;
+    result.verification ??= { status: 'unavailable' };
+    if (object(result.error).message !== message)
+        result.truncated = true;
+}
+function compactResult(source, name, limit = 1280) {
+    const evidence = object(source.evidence);
+    const result = {
+        ...pick(source, ['action_id', 'action_type', 'success', 'lifecycle_state', 'failure_code', 'retryable', 'delivery_status', 'dispatch_started', 'verification', 'verification_diagnostic', 'state_delta_available']),
+        observed_state: !['wait', 'assert'].includes(name) && source.dispatch_started !== true
+            ? { status: 'unknown', reason: 'NO_POST_ACTION_OBSERVATION' } : observedState(evidence, source.dispatch_started === true),
+        evidence: compactEvidence(evidence), diagnostics: interactionDiagnostics.retain(source)
+    };
+    result.success ??= false;
+    result.verification ??= { status: source.dispatch_started === false ? 'not_requested' : 'unavailable' };
+    if (source.error)
+        addCompactError(result, source.error, name);
+    if (source.device_readiness)
+        result.device_readiness = pick(source.device_readiness, ['wakefulness', 'lock_state', 'input_ready', 'blockers', 'limitations']);
+    if (source.condition)
+        result.condition = conditionSummary(source.condition);
+    if (source.state_delta)
+        result.state_delta = deltaSummary(source.state_delta);
+    if (source.timing)
+        result.timing = pick(source.timing, ['total_ms']);
+    if (object(source.observed).matched_count !== undefined)
+        result.matched_count = object(source.observed).matched_count;
+    if (source.observed_fingerprint !== undefined)
+        result.matched = !!source.success;
+    const state = source.actual_state !== undefined ? source.actual_state : source.observed_state;
+    if (state !== undefined) {
+        result.observed = boundedState(state);
+        if (JSON.stringify(result.observed) !== JSON.stringify(state))
+            result.truncated = true;
+    }
+    result.evidence = { session_id: evidenceSessionId(), ...object(result.evidence) };
+    enforceBudget(result, limit + deviceBytes(evidence));
+    return result;
+}
+function enforceBudget(result, limit) {
+    if (bytes(result) <= limit)
+        return;
+    result.truncated = true;
+    for (const key of ['state_delta', 'observed', 'matched_count', 'matched', 'state_delta_available', 'timing']) {
+        delete result[key];
+        if (bytes(result) <= limit)
+            return;
+    }
+    if (result.condition)
+        result.condition = pick(result.condition, ['status', 'reason']);
+    result.observed_state = { status: 'unknown', reason: 'OMITTED' };
+    if (result.failure_code)
+        delete result.error;
+    else if (result.error)
+        result.error = pick(result.error, ['code']);
+}
+function compactJourney(source) {
+    const steps = Array.isArray(source.steps) ? source.steps.map(object) : [];
+    const result = { ...pick(source, ['stopped_at_step_id']), success: source.success === true,
+        evidence: compactEvidence(source.evidence), diagnostics: interactionDiagnostics.retain(source),
+        observed_state: observedState(source.evidence), timing: pick(source.timing, ['total_ms']),
+        steps: steps.map(step => ({ ...pick(step, ['id', 'type', 'status', 'success', 'reason']),
+            result: step.result ? compactResult(object(step.result), String(step.type), 1080) : null })) };
+    if (source.error) {
+        const message = object(source.error).message;
+        const bounded = boundedValue(message);
+        result.error = { ...pick(source.error, ['code']), message: bounded };
+        if (bounded !== message)
+            result.truncated = true;
+    }
+    if (source.system_trace)
+        result.system_trace = pick(source.system_trace, ['trace_id', 'state', 'coverage', 'clock_alignment']);
+    enforceBudget(result, 1280 + 1280 * steps.length + steps.reduce((sum, s) => sum + idBytes(s.id) + deviceBytes(object(s.result).evidence), 0) + idBytes(source.stopped_at_step_id) + deviceBytes(source.evidence));
+    return result;
+}
+export function finalizeCompactInteraction(name, args, response) {
+    if (!compactInteractionTools.has(name) || (args.responseMode ?? (name === 'run_journey' ? 'compact' : 'debug')) !== 'compact')
+        return response;
+    const item = response.content.find(item => item.type === 'text');
+    if (item?.text) {
+        const source = object(JSON.parse(item.text));
+        item.text = JSON.stringify(name === 'run_journey' ? compactJourney(source) : compactResult(source, name));
+    }
+    return response;
+}

package/dist/server/handlers/compact-state.js

@@ -0,0 +1,47 @@
+export function object(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+export function pick(value, keys) {
+    const source = object(value);
+    return Object.fromEntries(keys.filter(key => source[key] !== undefined).map(key => [key, source[key]]));
+}
+export function boundedValue(value) {
+    if (typeof value !== 'string')
+        return ['number', 'boolean'].includes(typeof value) || value === null ? value : undefined;
+    let text = '';
+    for (const char of value) {
+        if (Buffer.byteLength(text + char) > 128)
+            break;
+        text += char;
+    }
+    return text;
+}
+export function observedState(evidence, dispatchStarted = false) {
+    const e = object(evidence), device = object(e.device);
+    const observations = Array.isArray(e.observations) ? e.observations.map(object) : [];
+    const candidates = observations.filter(o => ['ui_tree', 'fingerprint', 'screenshot'].includes(String(o.kind)));
+    const last = candidates.at(-1);
+    if (!last)
+        return { status: 'unknown', reason: 'NO_POST_ACTION_OBSERVATION' };
+    const summary = pick(last, ['kind', 'source_captured_at_ms', 'freshness', 'snapshot_session_id', 'snapshot_revision']);
+    summary.captured_at_ms = summary.source_captured_at_ms ?? null;
+    delete summary.source_captured_at_ms;
+    const same = object(last.device).id === device.id && object(last.device).platform === device.platform && !!device.id;
+    const post = typeof e.dispatch_completed_at_ms === 'number' && typeof last.capture_started_at_ms === 'number' && last.capture_started_at_ms >= e.dispatch_completed_at_ms;
+    if (typeof last.source_captured_at_ms !== 'number' || last.source_captured_at_ms <= 0)
+        return { status: 'unknown', reason: 'CAPTURE_TIME_UNKNOWN', ...summary };
+    if (last.status === 'captured' && last.freshness === 'fresh' && same && (!dispatchStarted || post))
+        return { status: 'observed', ...summary };
+    return { status: 'unknown', reason: !same ? 'DEVICE_MISMATCH' : !post && dispatchStarted ? 'NO_POST_ACTION_OBSERVATION' : 'OBSERVATION_UNAVAILABLE', ...summary };
+}
+export function deltaSummary(value) {
+    const delta = object(value);
+    return { ...pick(delta, ['base_snapshot_revision', 'snapshot_revision', 'truncated', 'omitted_changes']),
+        ...Object.fromEntries(['added', 'removed', 'changed'].map(key => [key, Array.isArray(delta[key]) ? delta[key].length : 0])) };
+}
+export function boundedState(value) {
+    if (!value || typeof value !== 'object')
+        return boundedValue(value);
+    const fields = pick(value, ['property', 'value', 'raw_value', 'checked', 'selected', 'expanded', 'enabled', 'text_value']);
+    return Object.fromEntries(Object.entries(fields).map(([key, item]) => [key, boundedValue(item)]).filter(([, item]) => item !== undefined));
+}

package/dist/server/handlers/input.js

@@ -18,6 +18,7 @@ export async function executeTap(args) {
     const uiFingerprintAfter = verificationMode === 'full' ? await measure('post_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null;
     const result = buildActionExecutionResult({
         actionType: 'tap',
+        device: res.device,
         sourceModule: 'server',
         selector: { x, y },
         success: !!res.success,
@@ -68,6 +69,7 @@ export async function executeSwipe(args) {
     const uiFingerprintAfter = verificationMode === 'full' ? await measure('post_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null;
     const result = buildActionExecutionResult({
         actionType: 'swipe',
+        device: res.device,
         sourceModule: 'server',
         selector: { x1, y1, x2, y2, duration },
         success: !!res.success,

package/dist/server/handlers/interact.js

@@ -1,3 +1,4 @@
+import { observeDeviceReadiness } from '../../observe/device-readiness.js';
 import { markEvidenceVerification } from '../../observe/evidence.js';
 import { withReadyWait } from '../../observe/readiness-service.js';
 import { ToolsInteract } from '../../interact/index.js';
@@ -68,6 +69,7 @@ export async function handleAdjustControl(args) {
         platform,
         deviceId
     });
+    res.device_readiness = await observeDeviceReadiness(res.device);
     markEvidenceVerification();
     return wrapResponse(res);
 }

package/dist/server/handlers/interaction-diagnostics.js

@@ -0,0 +1,62 @@
+import { randomUUID } from 'node:crypto';
+import { evidenceSessionId } from '../../observe/evidence.js';
+import { diagnosticsSchema } from '../schemas/interaction-diagnostics.js';
+import { wrapResponse } from '../common.js';
+const scheduleExpiry = expire => {
+    const timer = setTimeout(expire, 600000);
+    timer.unref();
+    return () => clearTimeout(timer);
+};
+export class InteractionDiagnostics {
+    now;
+    sessionId;
+    schedule;
+    entries = new Map();
+    bytes = 0;
+    constructor(now = () => performance.now(), sessionId = evidenceSessionId(), schedule = scheduleExpiry) {
+        this.now = now;
+        this.sessionId = sessionId;
+        this.schedule = schedule;
+    }
+    remove(id) {
+        const entry = this.entries.get(id);
+        if (entry) {
+            this.bytes -= entry.bytes;
+            entry.cancel();
+        }
+        this.entries.delete(id);
+    }
+    prune() {
+        for (const [id, entry] of this.entries)
+            if (this.now() - entry.completed >= 600000)
+                this.remove(id);
+    }
+    retain(result) {
+        this.prune();
+        const resultId = randomUUID(), text = JSON.stringify(result), bytes = Buffer.byteLength(text);
+        const ref = { session_id: this.sessionId, result_id: resultId };
+        if (bytes > 1024 * 1024)
+            return { ...ref, available: false, reason: 'RESULT_TOO_LARGE' };
+        while (this.entries.size >= 100 || this.bytes + bytes > 16 * 1024 * 1024)
+            this.remove(this.entries.keys().next().value);
+        this.entries.set(resultId, { text, completed: this.now(), bytes, cancel: this.schedule(() => this.remove(resultId)) });
+        this.bytes += bytes;
+        return { ...ref, available: true };
+    }
+    lookup(sessionId, resultId) {
+        this.prune();
+        if (sessionId !== this.sessionId)
+            return { success: false, error: { code: 'SESSION_MISMATCH', message: 'Use the session_id returned with this result.' } };
+        const entry = this.entries.get(resultId);
+        if (!entry)
+            return { success: false, error: { code: 'RESULT_UNAVAILABLE', message: 'Result expired, was evicted, is unknown, or belongs to a previous server process. Do not replay input automatically.' } };
+        return { success: true, result: JSON.parse(entry.text) };
+    }
+}
+export const interactionDiagnostics = new InteractionDiagnostics();
+export async function handleInteractionDiagnostics(args) {
+    const parsed = diagnosticsSchema.safeParse(args);
+    return wrapResponse(parsed.success ? interactionDiagnostics.lookup(parsed.data.sessionId, parsed.data.resultId) : {
+        success: false, error: { code: 'INVALID_ARGUMENT', message: 'Expected only sessionId and resultId UUID strings.' }
+    }, false);
+}

package/dist/server/handlers/journey.js

@@ -1,6 +1,8 @@
+import { observeDeviceReadiness } from '../../observe/device-readiness.js';
+import { benchmarkStage } from '../../utils/benchmark-metrics.js';
 import { debuggerSessions } from '../../debugger/sessions.js';
 import { systemTraces } from '../../observe/system-trace.js';
-import { currentEvidenceCorrelationId, bindSystemTrace, refreshJourneyEvidence, completeJourneyVerification } from '../../observe/evidence.js';
+import { currentEvidenceCorrelationId, bindSystemTrace, withJourneyStepEvidence, refreshJourneyEvidence, completeJourneyVerification, JourneyStepError } from '../../observe/evidence.js';
 import { runWithBudget } from '../../utils/operation-budget.js';
 import { journeySchema } from '../schemas/journey-schema.js';
 import { resolveTargetDevice, withResolvedDevice } from '../../utils/resolve-device.js';
@@ -25,23 +27,27 @@ async function assertStep(step, platform, deviceId) {
         return ToolsInteract.expectStateHandler({ selector: assertion.selector, element_id: assertion.elementId, property: assertion.property, expected: assertion.expected, platform, deviceId, stabilization_window_ms: timeoutMs, poll_interval_ms: pollIntervalMs, exact_budget: true });
     return { success: false, failure_code: 'INVALID_ASSERTION' };
 }
+async function observeStep(s, operation) {
+    return s.input.responseMode === 'compact' ? withJourneyStepEvidence(operation) : operation();
+}
 async function executeStep(s, step, covered) {
     const { platform, responseMode, defaults } = s.input, deviceId = s.deviceId;
     try {
         if (step.type === 'tap')
             return payloadOf(await handleTapElement({ ...defaults, ...step, platform, deviceId, responseMode, _journey: true, _stepId: step.id, verificationMode: covered ? 'none' : step.verificationMode ?? defaults?.verificationMode ?? 'full' }));
-        if (step.type === 'wait') {
-            const result = (await withObservationContext({ stepId: step.id, purpose: 'target' }, () => ToolsInteract.waitForUIHandler({ selector: step.selector, condition: step.condition ?? 'exists', timeout_ms: step.timeoutMs ?? 5000, poll_interval_ms: step.pollIntervalMs ?? 100, platform, deviceId })));
-            return { success: result.status === 'success', ...result };
-        }
+        if (step.type === 'wait')
+            return await observeStep(s, async () => {
+                const result = (await withObservationContext({ stepId: step.id, purpose: 'target' }, () => ToolsInteract.waitForUIHandler({ selector: step.selector, condition: step.condition ?? 'exists', timeout_ms: step.timeoutMs ?? 5000, poll_interval_ms: step.pollIntervalMs ?? 100, platform, deviceId })));
+                return { success: result.status === 'success', ...result };
+            });
         if (step.type === 'assert')
-            return await withObservationContext({ stepId: step.id, purpose: 'assertion' }, () => runWithBudget(step.timeoutMs ?? 5000, () => assertStep(step, platform, deviceId)));
+            return await observeStep(s, () => withObservationContext({ stepId: step.id, purpose: 'assertion' }, () => runWithBudget(step.timeoutMs ?? 5000, () => assertStep(step, platform, deviceId))));
         if (step.type === 'start_app')
             return payloadOf(await handleStartApp({ ...defaults, platform, deviceId, appId: step.appId, responseMode, _journey: true, _stepId: step.id, verificationMode: step.verificationMode ?? defaults?.verificationMode ?? 'full' }));
         return { success: false, failure_code: 'UNSUPPORTED_JOURNEY_STEP' };
     }
     catch (error) {
-        return { success: false, failure_code: step.type === 'assert' ? 'ASSERTION_TIMEOUT' : 'STEP_FAILED', error: error instanceof Error ? error.message : String(error) };
+        return { success: false, failure_code: step.type === 'assert' ? 'ASSERTION_TIMEOUT' : 'STEP_FAILED', error: error instanceof Error ? error.message : String(error), ...(error instanceof JourneyStepError ? { evidence: error.evidence } : {}) };
     }
 }
 function lightVerification(s, step, result, covered, success) {
@@ -69,24 +75,16 @@ function lightVerification(s, step, result, covered, success) {
     }
     s.pendingLightStep = null;
 }
-function compactAssertion(result, success) {
-    const errorCode = typeof result.error === 'object' ? result.error?.code : undefined;
-    return { success, ...(result.failure_code ? { failure_code: result.failure_code } : {}),
-        ...(errorCode ? { failure_code: errorCode } : {}),
-        ...(result.observed?.matched_count !== undefined ? { matched_count: result.observed.matched_count } : {}),
-        ...(result.observed_fingerprint !== undefined ? { matched: success } : {}),
-        ...(result.actual_state ? { observed: result.actual_state } : {}) };
-}
 function coveredByAssertion(s, step, next) {
     const verification = ('verificationMode' in step ? step.verificationMode : undefined) ?? s.input.defaults?.verificationMode ?? 'full';
     return step.type === 'tap' && s.input.responseMode === 'compact' && verification === 'light' && next?.type === 'assert' && next.assertion.kind === 'element_visible';
 }
 async function runSteps(s) {
-    const { platform, responseMode, steps } = s.input;
+    const { platform, steps } = s.input;
     for (let index = 0; index < steps.length; index++) {
         const step = steps[index];
         if (platform === 'android' && debuggerSessions.paused(s.deviceId)) {
-            s.results.push({ id: step.id, type: step.type, status: 'failed', success: false, result: { success: false, failure_code: 'DEBUGGER_PAUSED', dispatch_started: false, delivery_status: 'not_delivered' } });
+            s.results.push({ id: step.id, type: step.type, status: 'failed', success: false, result: { device_readiness: await observeDeviceReadiness({ platform, id: s.deviceId }), success: false, failure_code: 'DEBUGGER_PAUSED', dispatch_started: false, delivery_status: 'not_delivered' } });
             s.stoppedAt = step.id;
             break;
         }
@@ -95,7 +93,9 @@ async function runSteps(s) {
             s.results.push({ id: step.id, type: step.type, status: 'not_run', success: false, reason: 'PREVIOUS_STEP_FAILED', result: null, timing: { total_ms: 0 } });
             continue;
         }
-        let result = await executeStep(s, step, covered);
+        const result = await (step.type === 'assert' || step.type === 'wait'
+            ? benchmarkStage(step.type === 'assert' ? 'assertion_ms' : 'wait_ms', () => executeStep(s, step, covered))
+            : executeStep(s, step, covered));
         if (platform === 'android' && debuggerSessions.paused(s.deviceId)) {
             result.success = false;
             result.failure_code = 'DEBUGGER_PAUSED';
@@ -105,8 +105,6 @@ async function runSteps(s) {
             result.failure_code = 'ASSERTION_TIMEOUT';
         const success = !!result?.success;
         lightVerification(s, step, result, covered, success);
-        if (responseMode === 'compact' && ['wait', 'assert'].includes(step.type))
-            result = compactAssertion(result, success);
         s.results.push({ id: step.id, type: step.type, status: success ? 'passed' : 'failed', success, result, timing: { total_ms: performance.now() - started } });
         if (!success)
             s.stoppedAt = step.id;

package/dist/server/handlers/observe.js

@@ -1,4 +1,5 @@
 import { ToolsObserve } from '../../observe/index.js';
+import { benchmarkStage } from '../../utils/benchmark-metrics.js';
 import { withObservationContext } from '../../observe/performance-metrics.js';
 import { getBooleanArg, getNumberArg, getStringArg, requireStringArg, wrapResponse } from '../common.js';
 export async function handleGetLogs(args) {
@@ -25,7 +26,7 @@ export async function handleCaptureScreenshot(args) {
     const platform = requireStringArg(args, 'platform');
     const deviceId = getStringArg(args, 'deviceId');
     const started = performance.now();
-    const res = await ToolsObserve.captureScreenshotHandler({ platform, deviceId });
+    const res = await benchmarkStage('screenshot_capture_ms', () => ToolsObserve.captureScreenshotHandler({ platform, deviceId }));
     const screenshotMs = performance.now() - started;
     const mime = res.screenshot_mime || 'image/png';
     const content = [

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

@@ -1,3 +1,6 @@
+import { finalizeCompactInteraction } from './compact-interaction.js';
+import { handleInteractionDiagnostics } from './interaction-diagnostics.js';
+import { observeDeviceReadiness } from '../../observe/device-readiness.js';
 import { ToolsInteract } from '../../interact/index.js';
 import { handleDebugger } from './debugger-handlers.js';
 import { debuggerContracts } from '../schemas/debugger-schema.js';
@@ -33,6 +36,7 @@ export const toolHandlers = {
             throw new Error('INVALID_ARGUMENT: invalid readiness arguments');
         return wrapResponse(await getAppReadiness(parsed.data, true));
     },
+    get_interaction_diagnostics: handleInteractionDiagnostics,
     start_app: handleStartApp,
     terminate_app: handleTerminateApp,
     restart_app: handleRestartApp,
@@ -84,7 +88,7 @@ async function dispatchGuarded(device, args, handler, addTiming) {
     return withResolvedDevice(device, () => withDebuggerGuard(device.platform, device.id, async () => {
         const before = sessions.paused(device.id);
         if (before)
-            return wrapResponse({ success: false, failure_code: 'DEBUGGER_PAUSED', delivery_status: 'not_delivered', dispatch_started: false, debugger: before });
+            return addTiming(wrapResponse({ device_readiness: await observeDeviceReadiness(device), success: false, failure_code: 'DEBUGGER_PAUSED', delivery_status: 'not_delivered', dispatch_started: false, debugger: before }));
         let response;
         try {
             response = await handler(args);
@@ -101,7 +105,7 @@ async function dispatchGuarded(device, args, handler, addTiming) {
                 const payload = JSON.parse(item.text);
                 Object.assign(payload, { success: false, failure_code: 'DEBUGGER_PAUSED', retryable: false,
                     dispatch_started: guardDispatched(), delivery_status: payload.success ? 'delivered' : guardDispatched() ? 'unknown' : 'not_delivered',
-                    verification: { status: 'blocked', reason: 'DEBUGGER_PAUSED' }, debugger: pause });
+                    verification: { status: 'blocked', reason: 'DEBUGGER_PAUSED' }, device_readiness: await observeDeviceReadiness(device), debugger: pause });
                 item.text = JSON.stringify(payload);
             }
         }
@@ -135,7 +139,7 @@ export async function handleToolCall(name, args = {}, signal) {
     const measured = {};
     const addTiming = (response) => {
         if (!['start_app', 'restart_app', 'tap', 'tap_element', 'swipe', 'scroll_to_element', 'type_text', 'press_back', 'wait_for_ui', 'get_ui_tree', 'capture_screenshot', 'capture_debug_snapshot'].includes(name))
-            return response;
+            return finalizeCompactInteraction(name, args, response);
         const item = response.content.find(item => item.type === 'text');
         if (item?.text) {
             try {
@@ -145,7 +149,7 @@ export async function handleToolCall(name, args = {}, signal) {
             }
             catch { /* Non-JSON text responses retain their original content. */ }
         }
-        return response;
+        return finalizeCompactInteraction(name, args, response);
     };
     return withTiming(measured, async () => {
         try {
@@ -162,7 +166,7 @@ export async function handleToolCall(name, args = {}, signal) {
         }
         catch (error) {
             if (error instanceof TraceError)
-                return { ...wrapResponse({ error: { tool: name, code: error.code, message: error.message } }), isError: true };
+                return addTiming({ ...wrapResponse({ error: { tool: name, code: error.code, message: error.message } }), isError: true });
             console.error(`Error executing tool ${name}:`, error);
             return addTiming(wrapToolError(name, error));
         }

package/dist/server/schemas/interaction-diagnostics.js

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+export const diagnosticsSchema = z.object({ sessionId: z.string().uuid(), resultId: z.string().uuid() }).strict();
+export const interactionDiagnosticsTool = {
+    name: 'get_interaction_diagnostics',
+    description: 'Read the retained original interaction or journey result without replaying input or observing the device. Pass diagnostics.session_id/result_id as sessionId/resultId. Session-local memory: ten minutes, 100 results, 16 MiB total, 1 MiB per result. Expired, evicted or restarted results are unavailable. May contain private UI text and errors; compact output is not redaction.',
+    inputSchema: { type: 'object', additionalProperties: false, required: ['sessionId', 'resultId'], properties: {
+            sessionId: { type: 'string', format: 'uuid' }, resultId: { type: 'string', format: 'uuid' }
+        } }
+};

package/dist/server/tool-definitions.js

@@ -1,3 +1,4 @@
+import { interactionDiagnosticsTool } from './schemas/interaction-diagnostics.js';
 import { verificationModeJson, responseModeJson } from '../contracts/execution-controls.js';
 import { manageTools } from './definitions/manage.js';
 import { observeTools } from './definitions/observe.js';
@@ -51,9 +52,10 @@ const baseOrder = [
 export const toolDefinitions = [
     ...debuggerTools,
     ...systemTraceTools,
+    interactionDiagnosticsTool,
     ...['get_app_readiness', 'wait_for_app_ready'].map(name => ({
         name,
-        description: `${name === 'get_app_readiness' ? 'Observe readiness with at most two fresh UI-tree samples.' : 'Wait within a single bounded budget for settled UI evidence.'} Reports loading, transitioning, settled or unknown with evidence and limitations. Managed Android debugger pauses are reported from debugger evidence; unresponsive detection remains unsupported. Settled normalized foreground UI is not proof of app identity, responsiveness or backend completion.`,
+        description: `${name === 'get_app_readiness' ? 'Observe readiness with at most two fresh UI-tree samples.' : 'Wait within a single bounded budget for settled UI evidence.'} Reports loading, transitioning, settled or unknown with evidence and limitations. Managed Android and supported iOS simulator debugger pauses are reported from debugger evidence; unresponsive detection remains unsupported. Settled normalized foreground UI is not proof of app identity, responsiveness or backend completion.`,
         inputSchema: { type: 'object', additionalProperties: false, required: ['platform'], properties: {
                 ...readinessPropertiesJson,
                 timeoutMs: { ...readinessPropertiesJson.timeoutMs, default: name === 'get_app_readiness' ? 15000 : 30000 },
@@ -67,12 +69,12 @@ for (const tool of toolDefinitions) {
     tool.inputSchema.properties ??= {};
     if (['wait_for_ui', 'wait_for_ui_change'].includes(tool.name)) {
         tool.inputSchema.properties.requireReady = { type: 'boolean', default: false };
-        tool.description += '\nSet requireReady=true to require both the existing predicate and settled UI readiness, using the same fresh samples and one timeout budget. The readiness summary explains uncertainty. Default predicate semantics are unchanged.';
+        tool.description += '\nDevice-readiness blockers prevent readiness success; unknown/unsupported device signals remain explicit.\nSet requireReady=true to require both the existing predicate and settled UI readiness, using the same fresh samples and one timeout budget. The readiness summary explains uncertainty. Default predicate semantics are unchanged.';
     }
     if (tool.name === 'get_ui_tree')
         tool.description += '\nSuccessful observations include snapshot_session_id and snapshot_revision for same-device conditional input. Compact errors preserve the error and cannot authorize an expectation.';
     if (tool.name === 'run_journey')
-        tool.description += '\nTap steps may include expectedState from a successful same-device get_ui_tree. A failed condition blocks that input, retains fresh condition evidence even in compact mode, and stops subsequent steps. Conditions are not journey defaults or supported on other step types.';
+        tool.description += '\nTap steps may include expectedState from a successful same-device get_ui_tree. A failed condition blocks that input, retains fresh condition evidence through a diagnostics reference in compact mode, and stops subsequent steps. Conditions are not journey defaults or supported on other step types.';
     if (conditionalTools.has(tool.name)) {
         tool.inputSchema.properties.expectedState = expectedStateJson;
         tool.inputSchema.properties.platform ??= { type: 'string', enum: ['android'] };
@@ -83,12 +85,13 @@ for (const tool of toolDefinitions) {
                         deviceId: { type: 'string', minLength: 1, pattern: '\\S', not: { enum: ['booted', 'default'] } }
                     } }
             }];
-        tool.description += '\n\nConditional input: optionally supply expectedState { snapshotSessionId, snapshotRevision, timeoutMs? } from a successful get_ui_tree on the same explicit platform/deviceId. A fresh normalized UI-tree check runs immediately before input, even with verification disabled. PRECONDITION_FAILED or PRECONDITION_UNAVAILABLE means no input was dispatched; inspect condition evidence and re-observe before deciding what to do next. Compact failures include the fresh UI tree. This is not atomic with OS input delivery.';
+        tool.description += '\n\nConditional input: optionally supply expectedState { snapshotSessionId, snapshotRevision, timeoutMs? } from a successful get_ui_tree on the same explicit platform/deviceId. A fresh normalized UI-tree check runs immediately before input, even with verification disabled. PRECONDITION_FAILED or PRECONDITION_UNAVAILABLE means no input was dispatched; inspect condition evidence and re-observe before deciding what to do next. Compact failures summarize the fresh condition evidence; use get_interaction_diagnostics with the returned diagnostics reference for the retained UI tree. This is not atomic with OS input delivery.';
     }
     else {
         tool.inputSchema.allOf = [...(Array.isArray(tool.inputSchema.allOf) ? tool.inputSchema.allOf : []), { not: { required: ['expectedState'] } }];
     }
     if (['start_app', 'restart_app', 'tap', 'tap_element', 'swipe', 'scroll_to_element', 'type_text', 'press_back'].includes(tool.name)) {
+        tool.description += '\nCompact results summarize observations, condition trees, state deltas and readiness probe evidence within a byte budget. Use get_interaction_diagnostics with the returned diagnostics session_id/result_id to retrieve the original result without replaying input. Debug output is unchanged.';
         Object.assign(tool.inputSchema.properties, {
             verificationMode: { ...verificationModeJson, default: 'full' },
             responseMode: { ...responseModeJson, default: 'debug' },
@@ -112,6 +115,8 @@ for (const tool of toolDefinitions) {
 // Correlation is explicit; an omitted reference creates an independent observation.
 for (const tool of toolDefinitions) {
     tool.inputSchema.properties ??= {};
+    if (['start_app', 'restart_app', 'tap', 'tap_element', 'swipe', 'scroll_to_element', 'type_text', 'press_back', 'adjust_control', 'get_app_readiness', 'wait_for_app_ready'].includes(tool.name))
+        tool.description += '\nResults include device_readiness with timestamped device blocker evidence. Android reports supported power/keyguard signals; iOS signals may be unknown or explicitly unsupported. Launch/input dispatch success does not establish app visibility or input readiness. No automatic unlock or wake is performed.';
     if (['capture_screenshot', 'get_ui_tree', 'get_screen_fingerprint', 'capture_debug_snapshot', 'get_logs', 'read_log_stream'].includes(tool.name)) {
         Object.assign(tool.inputSchema.properties, { actionRef: {
                 type: 'object', additionalProperties: false, required: ['sessionId', 'actionId'], properties: {

package/dist/server-core.js

@@ -3,10 +3,11 @@ import { ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ReadRes
 import { wrapResponse } from './server/common.js';
 import { toolDefinitions } from './server/tool-definitions.js';
 import { handleToolCall } from './server/handlers/tool-handlers.js';
+import { withBenchmarkRequest, benchmarkStage } from './utils/benchmark-metrics.js';
 export { wrapResponse, toolDefinitions, handleToolCall };
 export const serverInfo = {
     name: 'mobile-debug-mcp',
-    version: '0.36.0'
+    version: '0.37.0'
 };
 export function createServer() {
     const server = new Server(serverInfo, {
@@ -29,7 +30,9 @@ export function createServer() {
     }));
     server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
         const { name, arguments: args } = request.params;
-        return handleToolCall(name, args, extra.signal);
+        const operation = () => handleToolCall(name, args, extra.signal);
+        return withBenchmarkRequest(name, () => name.startsWith('expect_') || name.startsWith('wait_for_')
+            ? benchmarkStage(name.startsWith('expect_') ? 'assertion_ms' : 'wait_ms', operation) : operation());
     });
     return server;
 }