mobile-debug-mcp 0.27.0 → 0.28.0

package/dist/interact/index.js

@@ -5,7 +5,26 @@ export { AndroidInteract, iOSInteract };
 import { resolveTargetDevice } from '../utils/resolve-device.js';
 import { ToolsObserve } from '../observe/index.js';
 import { computeSnapshotSignature } from '../observe/snapshot-metadata.js';
-import { buildActionExecutionResult } from '../server/common.js';
+import { buildActionExecutionResult, createTraceStep, nextActionId } from '../server/common.js';
+function buildObservationTrace({ actionType, stage, success, attempts, metadata }) {
+    const now = Date.now();
+    const actionId = nextActionId(actionType, now);
+    const steps = [
+        createTraceStep({
+            stage,
+            timestamp: now,
+            result: success ? 'success' : 'failure',
+            attemptIndex: 0,
+            metadata
+        })
+    ];
+    return {
+        action_id: actionId,
+        steps,
+        final_outcome: success ? 'success' : 'failure',
+        attempts: Math.max(1, Math.floor(attempts || 1))
+    };
+}
 export class ToolsInteract {
     static _maxResolvedUiElements = 256;
     static _uiChangeKinds = ['hierarchy_diff', 'text_change', 'state_change'];
@@ -533,7 +552,33 @@ export class ToolsInteract {
         let resolvedDeviceId = deviceId;
         const fingerprintBefore = await ToolsInteract._captureFingerprint(resolvedPlatform, resolvedDeviceId);
         let semanticFallbackElement = null;
+        const traceSteps = [];
+        let traceAttemptIndex = 0;
+        const recordTraceStep = (stage, result, metadata) => {
+            traceSteps.push(createTraceStep({
+                stage,
+                timestamp: Date.now(),
+                result,
+                attemptIndex: traceAttemptIndex++,
+                metadata
+            }));
+        };
         const buildFailure = (failureCode, reason, resolved, device, actualState, attempts, adjustmentMode = 'gesture', retryable = false, uiFingerprintAfter = null) => {
+            if (!traceSteps.some((step) => step.stage === 'resolve')) {
+                recordTraceStep('resolve', 'failure', {
+                    reason,
+                    failure_code: failureCode
+                });
+            }
+            if (!traceSteps.some((step) => step.stage === 'recover')) {
+                recordTraceStep('recover', retryable ? 'retry' : 'failure', {
+                    reason,
+                    failure_code: failureCode,
+                    retry_allowed: retryable,
+                    recovery_attempts: attempts,
+                    retry_depth: attempts
+                });
+            }
             const base = buildActionExecutionResult({
                 actionType,
                 sourceModule: 'interact',
@@ -554,7 +599,8 @@ export class ToolsInteract {
                     converged: false,
                     within_tolerance: false,
                     reason
-                }
+                },
+                traceSteps
             });
             return {
                 ...base,
@@ -716,10 +762,23 @@ export class ToolsInteract {
                 ? { property, value: currentValue, raw_value: typeof currentEl.state?.raw_value === 'number' ? currentEl.state.raw_value : undefined }
                 : null;
             lastObservedState = actualState;
+            if (!traceSteps.some((step) => step.stage === 'resolve')) {
+                recordTraceStep('resolve', 'success', {
+                    resolved_target: resolvedTarget,
+                    current_value: currentValue,
+                    adjustment_mode: lastAdjustmentMode
+                });
+            }
             if (property !== 'value' && property !== 'raw_value') {
                 return buildFailure('ELEMENT_NOT_INTERACTABLE', 'adjust_control currently supports numeric value and raw_value properties only', resolvedTarget, currentDevice, actualState, attemptCount, lastAdjustmentMode, false);
             }
             if (currentValue !== null && Math.abs(currentValue - targetValue) <= normalizedTolerance) {
+                recordTraceStep('verify', 'success', {
+                    property,
+                    target_value: targetValue,
+                    actual_state: actualState,
+                    reason: 'control already within tolerance'
+                });
                 const uiFingerprintAfter = await ToolsInteract._captureFingerprint(resolvedPlatform, resolvedDeviceId);
                 const base = buildActionExecutionResult({
                     actionType,
@@ -740,7 +799,8 @@ export class ToolsInteract {
                         converged: true,
                         within_tolerance: true,
                         reason: 'control already within tolerance'
-                    }
+                    },
+                    traceSteps
                 });
                 return {
                     ...base,
@@ -810,6 +870,11 @@ export class ToolsInteract {
             for (let i = 0; i < probePoints.length; i++) {
                 const probePoint = probePoints[i];
                 lastAdjustmentMode = 'coordinate';
+                recordTraceStep('execute', 'retry', {
+                    attempt: attemptCount + 1,
+                    mode: 'coordinate',
+                    point: probePoint
+                });
                 const actionResult = await ToolsInteract.tapHandler({
                     platform: resolvedPlatform,
                     x: probePoint.x,
@@ -819,11 +884,24 @@ export class ToolsInteract {
                 attemptCount++;
                 actionDevice = actionResult.device ?? actionDevice;
                 if (!actionResult.success) {
+                    recordTraceStep('execute', 'retry', {
+                        attempt: attemptCount,
+                        mode: 'coordinate',
+                        point: probePoint,
+                        success: false
+                    });
                     continue;
                 }
                 verificationResult = await runVerification();
                 observedState = verificationResult.observedState;
                 lastObservedState = observedState;
+                recordTraceStep('verify', verificationResult.withinTolerance ? 'success' : 'retry', {
+                    attempt: attemptCount,
+                    property,
+                    target_value: targetValue,
+                    actual_state: observedState,
+                    reason: verificationResult.verification?.reason ?? 'control did not converge yet'
+                });
                 if (verificationResult.withinTolerance) {
                     const uiFingerprintAfter = await ToolsInteract._captureFingerprint(resolvedPlatform, resolvedDeviceId);
                     const base = buildActionExecutionResult({
@@ -845,7 +923,8 @@ export class ToolsInteract {
                             converged: true,
                             within_tolerance: true,
                             reason: verificationResult.verification?.reason ?? 'control converged to target value'
-                        }
+                        },
+                        traceSteps
                     });
                     return {
                         ...base,
@@ -864,6 +943,12 @@ export class ToolsInteract {
             }
             if (currentValue !== null) {
                 lastAdjustmentMode = 'gesture';
+                recordTraceStep('execute', 'retry', {
+                    attempt: attemptCount + 1,
+                    mode: 'gesture',
+                    start: currentPoint,
+                    end: targetPoint
+                });
                 const fallbackActionResult = await ToolsInteract.swipeHandler({
                     platform: resolvedPlatform,
                     x1: currentPoint.x,
@@ -875,12 +960,26 @@ export class ToolsInteract {
                 });
                 attemptCount++;
                 if (!fallbackActionResult.success) {
+                    recordTraceStep('execute', 'failure', {
+                        attempt: attemptCount,
+                        mode: 'gesture',
+                        start: currentPoint,
+                        end: targetPoint,
+                        success: false
+                    });
                     return buildFailure('UNKNOWN', fallbackActionResult.error ?? 'adjustment gesture failed', resolvedTarget, fallbackActionResult.device ?? actionDevice, observedState ?? actualState, attemptCount, lastAdjustmentMode, false);
                 }
                 actionDevice = fallbackActionResult.device ?? actionDevice;
                 verificationResult = await runVerification();
                 observedState = verificationResult.observedState;
                 lastObservedState = observedState;
+                recordTraceStep('verify', verificationResult.withinTolerance ? 'success' : 'retry', {
+                    attempt: attemptCount,
+                    property,
+                    target_value: targetValue,
+                    actual_state: observedState,
+                    reason: verificationResult.verification?.reason ?? 'gesture adjustment did not converge yet'
+                });
                 if (verificationResult.withinTolerance) {
                     const uiFingerprintAfter = await ToolsInteract._captureFingerprint(resolvedPlatform, resolvedDeviceId);
                     const base = buildActionExecutionResult({
@@ -902,7 +1001,8 @@ export class ToolsInteract {
                             converged: true,
                             within_tolerance: true,
                             reason: verificationResult.verification?.reason ?? 'control converged to target value'
-                        }
+                        },
+                        traceSteps
                     });
                     return {
                         ...base,
@@ -922,6 +1022,13 @@ export class ToolsInteract {
             verification = verificationResult.verification;
             lastObservedState = observedState;
             if (verificationResult.withinTolerance) {
+                recordTraceStep('verify', 'success', {
+                    attempt: attemptCount,
+                    property,
+                    target_value: targetValue,
+                    actual_state: observedState,
+                    reason: verification?.reason ?? 'control converged to target value'
+                });
                 const uiFingerprintAfter = await ToolsInteract._captureFingerprint(resolvedPlatform, resolvedDeviceId);
                 const base = buildActionExecutionResult({
                     actionType,
@@ -942,7 +1049,8 @@ export class ToolsInteract {
                         converged: true,
                         within_tolerance: true,
                         reason: verification?.reason ?? 'control converged to target value'
-                    }
+                    },
+                    traceSteps
                 });
                 return {
                     ...base,
@@ -1716,7 +1824,24 @@ export class ToolsInteract {
                 basis,
                 matched: success,
                 reason
-            }
+            },
+            trace: buildObservationTrace({
+                actionType: 'expect_screen',
+                stage: 'verify',
+                success,
+                attempts: 1,
+                metadata: {
+                    expected_screen: expectedScreen,
+                    observed_screen: {
+                        fingerprint: observedScreen.fingerprint,
+                        screen: observedScreenLabel
+                    },
+                    comparison: {
+                        basis,
+                        matched: success
+                    }
+                }
+            })
         };
     }
     static async expectElementVisibleHandler({ selector, element_id, timeout_ms = 5000, poll_interval_ms = 300, platform, deviceId }) {
@@ -1770,7 +1895,18 @@ export class ToolsInteract {
                         semantic: result.element.semantic ?? null
                     }
                 },
-                reason: 'selector is visible'
+                reason: 'selector is visible',
+                trace: buildObservationTrace({
+                    actionType: 'expect_element_visible',
+                    stage: 'verify',
+                    success: true,
+                    attempts: 1,
+                    metadata: {
+                        selector,
+                        element_id: result.element.elementId ?? element_id ?? null,
+                        status: result.status
+                    }
+                })
             };
         }
         const errorCode = result?.error?.code === 'INTERNAL_ERROR' ? 'UNKNOWN' : 'TIMEOUT';
@@ -1788,7 +1924,19 @@ export class ToolsInteract {
             },
             reason: result?.error?.message ?? 'selector is not visible',
             failure_code: errorCode,
-            retryable: errorCode === 'TIMEOUT'
+            retryable: errorCode === 'TIMEOUT',
+            trace: buildObservationTrace({
+                actionType: 'expect_element_visible',
+                stage: 'verify',
+                success: false,
+                attempts: 1,
+                metadata: {
+                    selector,
+                    element_id: element_id ?? null,
+                    status: result?.status ?? null,
+                    reason: result?.error?.message ?? 'selector is not visible'
+                }
+            })
         };
     }
     static async expectStateHandler({ selector, element_id, property, expected, platform, deviceId, stabilization_window_ms = 1000, stable_observation_count = 2, snapshot_stale_threshold_ms = 500, poll_interval_ms = 150 }) {
@@ -1809,6 +1957,24 @@ export class ToolsInteract {
         let lastObservedValue = null;
         let lastRawValue = null;
         let lastResolvedElementId = element_id ?? null;
+        const traceSteps = [];
+        let traceAttemptIndex = 0;
+        let resolveRecorded = false;
+        const recordTraceStep = (stage, result, metadata) => {
+            traceSteps.push(createTraceStep({
+                stage,
+                timestamp: Date.now(),
+                result,
+                attemptIndex: traceAttemptIndex++,
+                metadata
+            }));
+        };
+        const buildStateTrace = (outcome) => ({
+            action_id: nextActionId('expect_state', Date.now()),
+            steps: traceSteps,
+            final_outcome: outcome,
+            attempts
+        });
         while (Date.now() <= deadline) {
             attempts++;
             const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId });
@@ -1832,6 +1998,19 @@ export class ToolsInteract {
                 lastReason = 'element not found';
                 lastFailureCode = 'ELEMENT_NOT_FOUND';
                 stableCount = 0;
+                recordTraceStep('resolve', 'retry', {
+                    selector: selector ?? null,
+                    element_id: lastResolvedElementId,
+                    matched: false,
+                    reason: lastReason,
+                    attempt: attempts
+                });
+                recordTraceStep('stabilize', 'retry', {
+                    stabilization_attempts: attempts,
+                    stable_observation_count: stableCount,
+                    snapshot_freshness_ms: treeAgeMs,
+                    reason: lastReason
+                });
                 await sleep(pollDelay);
                 continue;
             }
@@ -1842,9 +2021,31 @@ export class ToolsInteract {
                 lastReason = 'stale snapshot';
                 lastFailureCode = 'UNKNOWN';
                 stableCount = 0;
+                recordTraceStep('resolve', 'retry', {
+                    selector: selector ?? null,
+                    element_id: lastResolvedElementId,
+                    matched: true,
+                    reason: lastReason,
+                    attempt: attempts
+                });
+                recordTraceStep('stabilize', 'retry', {
+                    stabilization_attempts: attempts,
+                    stable_observation_count: stableCount,
+                    snapshot_freshness_ms: treeAgeMs,
+                    reason: lastReason
+                });
                 await sleep(pollDelay);
                 continue;
             }
+            if (!resolveRecorded) {
+                recordTraceStep('resolve', 'success', {
+                    selector: selector ?? null,
+                    element_id: lastResolvedElementId,
+                    matched: true,
+                    reason: 'element resolved'
+                });
+                resolveRecorded = true;
+            }
             const observedState = matched.el.state ?? null;
             const actual = observedState?.[property] ?? null;
             let success = false;
@@ -1964,6 +2165,18 @@ export class ToolsInteract {
             }
             if (success) {
                 stableCount++;
+                recordTraceStep('stabilize', 'success', {
+                    stabilization_attempts: attempts,
+                    stable_observation_count: stableCount,
+                    snapshot_freshness_ms: treeAgeMs,
+                    reason
+                });
+                recordTraceStep('verify', 'success', {
+                    property,
+                    expected,
+                    observed_value: observedValue,
+                    reason
+                });
                 if (stableCount >= stableTarget) {
                     return {
                         success: true,
@@ -1980,7 +2193,8 @@ export class ToolsInteract {
                         stabilization_attempts: attempts,
                         stabilization_window_ms: Date.now() - start,
                         stable_observation_count: stableCount,
-                        snapshot_freshness_ms: treeAgeMs ?? undefined
+                        snapshot_freshness_ms: treeAgeMs ?? undefined,
+                        trace: buildStateTrace('success')
                     };
                 }
             }
@@ -1988,6 +2202,18 @@ export class ToolsInteract {
                 stableCount = 0;
                 lastReason = reason || lastReason;
                 lastFailureCode = 'UNKNOWN';
+                recordTraceStep('stabilize', 'retry', {
+                    stabilization_attempts: attempts,
+                    stable_observation_count: stableCount,
+                    snapshot_freshness_ms: treeAgeMs,
+                    reason: lastReason
+                });
+                recordTraceStep('verify', 'retry', {
+                    property,
+                    expected,
+                    observed_value: observedValue,
+                    reason: lastReason
+                });
             }
             if (!success) {
                 lastObservedValue = observedValue;
@@ -2008,7 +2234,8 @@ export class ToolsInteract {
             },
             reason: lastReason,
             failure_code: lastFailureCode,
-            retryable: true
+            retryable: true,
+            trace: buildStateTrace('failure')
         };
     }
     static async waitForUICore({ type = 'ui', query, timeoutMs = 30000, pollIntervalMs = 300, includeSnapshotOnFailure = true, match = 'present', stability_ms = 700, observationDelayMs = 0, platform, deviceId }) {

package/dist/server/common.js

@@ -71,6 +71,119 @@ export async function captureActionFingerprint(platform, deviceId) {
         return null;
     }
 }
+export function createTraceStep({ stage, timestamp, result, attemptIndex, cycleId, metadata }) {
+    return {
+        stage,
+        timestamp,
+        result,
+        attempt_index: attemptIndex,
+        ...(cycleId !== undefined ? { cycle_id: cycleId } : {}),
+        ...(metadata ? { metadata } : {})
+    };
+}
+export function buildActionTrace({ actionId, actionType, sourceModule, selector, resolved, success, failure, details, recovery, attempts = 1, steps }) {
+    if (steps && steps.length > 0) {
+        return {
+            action_id: actionId,
+            steps,
+            final_outcome: success ? 'success' : 'failure',
+            attempts: Math.max(1, Math.floor(attempts || steps.length))
+        };
+    }
+    const start = Date.now();
+    const builtSteps = [];
+    let attemptIndex = 0;
+    const totalAttempts = Math.max(1, Math.floor(attempts || 1));
+    if (selector || resolved) {
+        const stageResult = resolved ? 'success' : 'failure';
+        builtSteps.push(createTraceStep({
+            stage: 'resolve',
+            timestamp: start,
+            result: stageResult,
+            attemptIndex: attemptIndex++,
+            metadata: {
+                action_type: actionType,
+                source_module: sourceModule,
+                selector: selector ?? null,
+                resolved: resolved ? normalizeResolvedTarget(resolved) : null
+            }
+        }));
+    }
+    builtSteps.push(createTraceStep({
+        stage: 'execute',
+        timestamp: Date.now(),
+        result: success ? 'success' : 'failure',
+        attemptIndex: attemptIndex++,
+        metadata: {
+            action_type: actionType,
+            source_module: sourceModule,
+            ...(failure ? { failure_code: failure.failureCode, retryable: failure.retryable } : {})
+        }
+    }));
+    const hasStabilizeDetails = Boolean(details && (Object.prototype.hasOwnProperty.call(details, 'stabilization_attempts') ||
+        Object.prototype.hasOwnProperty.call(details, 'stable_observation_count') ||
+        Object.prototype.hasOwnProperty.call(details, 'snapshot_freshness_ms')));
+    const hasVerifyDetails = Boolean(details && (Object.prototype.hasOwnProperty.call(details, 'within_tolerance') ||
+        Object.prototype.hasOwnProperty.call(details, 'converged') ||
+        Object.prototype.hasOwnProperty.call(details, 'observed_state')));
+    if (hasStabilizeDetails) {
+        builtSteps.push(createTraceStep({
+            stage: 'stabilize',
+            timestamp: Date.now(),
+            result: success ? 'success' : 'failure',
+            attemptIndex: attemptIndex++,
+            metadata: {
+                stabilization_attempts: details?.stabilization_attempts ?? null,
+                stable_observation_count: details?.stable_observation_count ?? null,
+                snapshot_freshness_ms: details?.snapshot_freshness_ms ?? null
+            }
+        }));
+    }
+    if (hasVerifyDetails) {
+        builtSteps.push(createTraceStep({
+            stage: 'verify',
+            timestamp: Date.now(),
+            result: success ? 'success' : 'failure',
+            attemptIndex: attemptIndex++,
+            metadata: {
+                within_tolerance: details?.within_tolerance ?? null,
+                converged: details?.converged ?? null,
+                actual_state: details?.actual_state ?? null,
+                reason: details?.reason ?? null
+            }
+        }));
+    }
+    if (failure) {
+        builtSteps.push(createTraceStep({
+            stage: 'recover',
+            timestamp: Date.now(),
+            result: failure.retryable ? 'retry' : 'failure',
+            attemptIndex: attemptIndex++,
+            metadata: {
+                failure_class: recovery?.failure_class ?? mapFailureCodeToFailureClass(failure.failureCode),
+                runtime_code: failure.failureCode,
+                retry_allowed: failure.retryable,
+                recovery_attempts: recovery?.recovery_attempts ?? 0,
+                retry_depth: recovery?.retry_depth ?? 0
+            }
+        }));
+    }
+    if (!builtSteps.length) {
+        builtSteps.push(createTraceStep({
+            stage: 'execute',
+            timestamp: start,
+            result: success ? 'success' : 'failure',
+            attemptIndex: 0,
+            metadata: { action_type: actionType, source_module: sourceModule }
+        }));
+    }
+    return {
+        action_id: actionId,
+        steps: builtSteps,
+        final_outcome: success ? 'success' : 'failure',
+        attempts: totalAttempts
+    };
+}
 export function normalizeResolvedTarget(value = null) {
     if (!value)
         return null;
@@ -144,11 +257,16 @@ function buildRecoveryState(failureCode, retryable) {
         retry_allowed: retryable
     };
 }
-export function buildActionExecutionResult({ actionType, device, selector, resolved, success, uiFingerprintBefore, uiFingerprintAfter, failure, details, sourceModule }) {
+export function buildActionExecutionResult({ actionType, device, selector, resolved, success, uiFingerprintBefore, uiFingerprintAfter, failure, details, sourceModule, traceSteps }) {
     const timestampMs = Date.now();
     const timestamp = new Date(timestampMs).toISOString();
+    const actionId = nextActionId(actionType, timestampMs);
+    const recoveryState = failure ? buildRecoveryState(failure.failureCode, failure.retryable) : undefined;
+    const attempts = typeof details?.attempts === 'number' && Number.isFinite(details.attempts)
+        ? Math.max(1, Math.floor(details.attempts))
+        : 1;
     return {
-        action_id: nextActionId(actionType, timestampMs),
+        action_id: actionId,
         timestamp,
         action_type: actionType,
         lifecycle_state: determineActionLifecycleState({ success, failure }),
@@ -160,7 +278,20 @@ export function buildActionExecutionResult({ actionType, device, selector, resol
         },
         success,
         ...(failure ? { failure_code: failure.failureCode, retryable: failure.retryable } : {}),
-        ...(failure ? { recovery: buildRecoveryState(failure.failureCode, failure.retryable) } : {}),
+        ...(recoveryState ? { recovery: recoveryState } : {}),
+        trace: buildActionTrace({
+            actionId,
+            actionType,
+            sourceModule,
+            selector,
+            resolved,
+            success,
+            failure,
+            details,
+            recovery: recoveryState,
+            attempts,
+            steps: traceSteps
+        }),
         ui_fingerprint_before: uiFingerprintBefore,
         ui_fingerprint_after: uiFingerprintAfter,
         ...(details ? { details } : {})

package/dist/server-core.js

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

package/docs/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.28.0]
+- Added structured execution trace model for all actions within the MCP runtime. It provides visibility into resolution, execution, verification, stabilization, and recovery stages.
+
 ## [0.27.0]
 - defines a structured recovery and replanning model for UI interaction failures, enabling the system to respond to execution uncertainty with bounded, deterministic recovery strategies.