mobile-debug-mcp 0.26.1 → 0.26.2

package/dist/interact/index.js

@@ -5,7 +5,7 @@ export { AndroidInteract, iOSInteract };
 import { resolveTargetDevice } from '../utils/resolve-device.js';
 import { ToolsObserve } from '../observe/index.js';
 import { computeSnapshotSignature } from '../observe/snapshot-metadata.js';
-import { nextActionId } from '../server/common.js';
+import { buildActionExecutionResult } from '../server/common.js';
 export class ToolsInteract {
     static _maxResolvedUiElements = 256;
     static _uiChangeKinds = ['hierarchy_diff', 'text_change', 'state_change'];
@@ -203,18 +203,17 @@ export class ToolsInteract {
             semantic: element.semantic ?? null
         };
     }
-    static _actionFailure(actionId, timestamp, actionType, selector, resolved, failureCode, retryable, uiFingerprintBefore, uiFingerprintAfter) {
-        return {
-            action_id: actionId,
-            timestamp,
-            action_type: actionType,
-            target: { selector, resolved },
+    static _actionFailure(actionType, selector, resolved, failureCode, retryable, uiFingerprintBefore, uiFingerprintAfter, sourceModule = 'interact') {
+        return buildActionExecutionResult({
+            actionType,
+            selector,
+            resolved,
             success: false,
-            failure_code: failureCode,
-            retryable,
-            ui_fingerprint_before: uiFingerprintBefore,
-            ui_fingerprint_after: uiFingerprintAfter
-        };
+            uiFingerprintBefore,
+            uiFingerprintAfter: uiFingerprintAfter ?? null,
+            failure: { failureCode, retryable },
+            sourceModule
+        });
     }
     static _resetResolvedUiElementsForTests() {
         ToolsInteract._resolvedUiElements.clear();
@@ -350,14 +349,11 @@ export class ToolsInteract {
         return await interact.tap(x, y, resolved.id);
     }
     static async tapElementHandler({ elementId }) {
-        const timestampMs = Date.now();
-        const timestamp = new Date(timestampMs).toISOString();
         const actionType = 'tap_element';
-        const actionId = nextActionId(actionType, timestampMs);
         const selector = { elementId };
         const resolved = ToolsInteract._resolvedUiElements.get(elementId);
         if (!resolved) {
-            return ToolsInteract._actionFailure(actionId, timestamp, actionType, selector, null, 'STALE_REFERENCE', true, null);
+            return ToolsInteract._actionFailure(actionType, selector, null, 'STALE_REFERENCE', true, null);
         }
         const fingerprintBefore = await ToolsInteract._captureFingerprint(resolved.platform, resolved.deviceId);
         const tree = await ToolsObserve.getUITreeHandler({ platform: resolved.platform, deviceId: resolved.deviceId });
@@ -366,40 +362,37 @@ export class ToolsInteract {
         const elements = Array.isArray(tree?.elements) ? tree.elements : [];
         const currentMatch = ToolsInteract._findCurrentResolvedElement(elements, treePlatform, treeDeviceId, resolved);
         if (!currentMatch) {
-            return ToolsInteract._actionFailure(actionId, timestamp, actionType, selector, null, 'STALE_REFERENCE', true, fingerprintBefore);
+            return ToolsInteract._actionFailure(actionType, selector, null, 'STALE_REFERENCE', true, fingerprintBefore);
         }
         const resolvedTarget = ToolsInteract._resolvedTargetFromElement(resolved.elementId, currentMatch.el, currentMatch.index);
         if (!ToolsInteract._isVisibleElement(currentMatch.el)) {
-            return ToolsInteract._actionFailure(actionId, timestamp, actionType, selector, resolvedTarget, 'ELEMENT_NOT_INTERACTABLE', true, fingerprintBefore);
+            return ToolsInteract._actionFailure(actionType, selector, resolvedTarget, 'ELEMENT_NOT_INTERACTABLE', true, fingerprintBefore);
         }
         if (currentMatch.el.enabled === false) {
-            return ToolsInteract._actionFailure(actionId, timestamp, actionType, selector, resolvedTarget, 'ELEMENT_NOT_INTERACTABLE', true, fingerprintBefore);
+            return ToolsInteract._actionFailure(actionType, selector, resolvedTarget, 'ELEMENT_NOT_INTERACTABLE', true, fingerprintBefore);
         }
         const bounds = ToolsInteract._normalizeBounds(currentMatch.el.bounds) ?? resolved.bounds;
         if (!bounds || bounds[2] <= bounds[0] || bounds[3] <= bounds[1]) {
-            return ToolsInteract._actionFailure(actionId, timestamp, actionType, selector, resolvedTarget, 'ELEMENT_NOT_INTERACTABLE', true, fingerprintBefore);
+            return ToolsInteract._actionFailure(actionType, selector, resolvedTarget, 'ELEMENT_NOT_INTERACTABLE', true, fingerprintBefore);
         }
         const x = Math.floor((bounds[0] + bounds[2]) / 2);
         const y = Math.floor((bounds[1] + bounds[3]) / 2);
         const tapResult = await ToolsInteract.tapHandler({ platform: resolved.platform, x, y, deviceId: resolved.deviceId });
         if (!tapResult.success) {
             const fingerprintAfterFailure = await ToolsInteract._captureFingerprint(resolved.platform, resolved.deviceId);
-            return ToolsInteract._actionFailure(actionId, timestamp, actionType, selector, resolvedTarget, 'UNKNOWN', false, fingerprintBefore, fingerprintAfterFailure);
+            return ToolsInteract._actionFailure(actionType, selector, resolvedTarget, 'UNKNOWN', false, fingerprintBefore, fingerprintAfterFailure);
         }
         const fingerprintAfter = await ToolsInteract._captureFingerprint(resolved.platform, resolved.deviceId);
-        return {
-            action_id: actionId,
-            timestamp,
-            action_type: actionType,
-            ...(tree?.device ? { device: tree.device } : {}),
-            target: {
-                selector,
-                resolved: resolvedTarget
-            },
+        return buildActionExecutionResult({
+            actionType,
+            device: tree?.device,
+            selector,
+            resolved: resolvedTarget,
             success: true,
-            ui_fingerprint_before: fingerprintBefore,
-            ui_fingerprint_after: fingerprintAfter
-        };
+            uiFingerprintBefore: fingerprintBefore,
+            uiFingerprintAfter: fingerprintAfter,
+            sourceModule: 'interact'
+        });
     }
     static async swipeHandler({ platform = 'android', x1, y1, x2, y2, duration, deviceId }) {
         const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId);

package/dist/server/common.js

@@ -95,13 +95,26 @@ export function inferScrollFailure(message) {
         return { failureCode: 'TIMEOUT', retryable: true };
     return { failureCode: 'UNKNOWN', retryable: false };
 }
-export function buildActionExecutionResult({ actionType, device, selector, resolved, success, uiFingerprintBefore, uiFingerprintAfter, failure, details }) {
+const ACTION_LIFECYCLE_STATE_BY_OUTCOME = {
+    success: 'pending_verification',
+    failure: 'failed'
+};
+export function determineActionLifecycleState({ success, failure }) {
+    if (failure)
+        return ACTION_LIFECYCLE_STATE_BY_OUTCOME.failure;
+    if (success)
+        return ACTION_LIFECYCLE_STATE_BY_OUTCOME.success;
+    return ACTION_LIFECYCLE_STATE_BY_OUTCOME.success;
+}
+export function buildActionExecutionResult({ actionType, device, selector, resolved, success, uiFingerprintBefore, uiFingerprintAfter, failure, details, sourceModule }) {
     const timestampMs = Date.now();
     const timestamp = new Date(timestampMs).toISOString();
     return {
         action_id: nextActionId(actionType, timestampMs),
         timestamp,
         action_type: actionType,
+        lifecycle_state: determineActionLifecycleState({ success, failure }),
+        source_module: sourceModule,
         ...(device ? { device } : {}),
         target: {
             selector,

package/dist/server/tool-definitions.js

@@ -11,7 +11,9 @@ Inputs:
 
 Output Structure:
  - action_id, timestamp (ISO 8601), action_type
-- target.selector = { appId }
+ - lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
+ - source_module: runtime source of the action envelope
+ - target.selector = { appId }
 - success = true when launch was dispatched successfully
 - failure_code/retryable when launch dispatch fails
 - ui_fingerprint_before/ui_fingerprint_after when available
@@ -84,7 +86,9 @@ Inputs:
 
 Output Structure:
  - action_id, timestamp (ISO 8601), action_type
-- target.selector = { appId }
+ - lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
+ - source_module: runtime source of the action envelope
+ - target.selector = { appId }
 - success = true when the restart command completed
 - failure_code/retryable when restart dispatch fails
 - ui_fingerprint_before/ui_fingerprint_after when available
@@ -617,7 +621,9 @@ Inputs:
 
 Output Structure:
  - action_id, timestamp (ISO 8601), action_type
-- target.selector = { x, y }
+ - lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
+ - source_module: runtime source of the action envelope
+ - target.selector = { x, y }
 - success = true when the tap was dispatched
 - failure_code/retryable when dispatch fails
 - ui_fingerprint_before/ui_fingerprint_after when available
@@ -673,6 +679,8 @@ Output Structure:
 - action_id: unique timestamp-based action identifier
 - timestamp: ISO 8601 timestamp for the action attempt
 - action_type: "tap_element"
+- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
+- source_module: runtime source of the action envelope
 - target.selector: original target handle ({ elementId })
 - target.resolved: minimal resolved element info used for the tap
 - success: true when the tap was dispatched
@@ -725,6 +733,8 @@ Inputs:
 
 Output Structure:
 - action_id, timestamp (ISO 8601), action_type
+- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
+- source_module: runtime source of the action envelope
 - target.selector = { x1, y1, x2, y2, duration }
 - success = true when the swipe was dispatched
 - failure_code/retryable when dispatch fails
@@ -777,6 +787,8 @@ Inputs:
 
 Output Structure:
 - action_id, timestamp (ISO 8601), action_type
+- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
+- source_module: runtime source of the action envelope
 - target.selector = original selector
 - target.resolved = minimal resolved element info when found
 - success = true when scrolling produced a visible target element
@@ -831,6 +843,8 @@ Inputs:
 
 Output Structure:
 - action_id, timestamp (ISO 8601), action_type
+- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
+- source_module: runtime source of the action envelope
 - target.selector = { text }
 - success = true when text input was dispatched
 - failure_code/retryable when dispatch fails
@@ -880,6 +894,8 @@ Inputs:
 
 Output Structure:
 - action_id, timestamp (ISO 8601), action_type
+- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
+- source_module: runtime source of the action envelope
 - target.selector = { key: "back" }
 - success = true when the back action was dispatched
 - failure_code/retryable when dispatch fails

package/dist/server/tool-handlers.js

@@ -15,6 +15,7 @@ async function handleStartApp(args) {
     const uiFingerprintAfter = await captureActionFingerprint(platform, deviceId);
     return wrapResponse(buildActionExecutionResult({
         actionType: 'start_app',
+        sourceModule: 'server',
         device: res.device,
         selector: { appId },
         success: !!res.appStarted,
@@ -48,6 +49,7 @@ async function handleRestartApp(args) {
     const uiFingerprintAfter = await captureActionFingerprint(platform, deviceId);
     return wrapResponse(buildActionExecutionResult({
         actionType: 'restart_app',
+        sourceModule: 'server',
         device: res.device,
         selector: { appId },
         success: !!res.appRestarted,
@@ -265,6 +267,7 @@ async function handleTap(args) {
     const uiFingerprintAfter = await captureActionFingerprint(platform, deviceId);
     return wrapResponse(buildActionExecutionResult({
         actionType: 'tap',
+        sourceModule: 'server',
         selector: { x, y },
         success: !!res.success,
         uiFingerprintBefore,
@@ -292,6 +295,7 @@ async function handleSwipe(args) {
     const uiFingerprintAfter = await captureActionFingerprint(platform, deviceId);
     return wrapResponse(buildActionExecutionResult({
         actionType: 'swipe',
+        sourceModule: 'server',
         selector: { x1, y1, x2, y2, duration },
         success: !!res.success,
         uiFingerprintBefore,
@@ -312,6 +316,7 @@ async function handleScrollToElement(args) {
     const uiFingerprintAfter = await captureActionFingerprint(platform, deviceId);
     return wrapResponse(buildActionExecutionResult({
         actionType: 'scroll_to_element',
+        sourceModule: 'server',
         selector: selector ?? null,
         resolved: res?.success && res?.element ? {
             elementId: null,
@@ -337,6 +342,7 @@ async function handleTypeText(args) {
     const uiFingerprintAfter = await captureActionFingerprint('android', deviceId);
     return wrapResponse(buildActionExecutionResult({
         actionType: 'type_text',
+        sourceModule: 'server',
         selector: { text },
         success: !!res.success,
         uiFingerprintBefore,
@@ -352,6 +358,7 @@ async function handlePressBack(args) {
     const uiFingerprintAfter = await captureActionFingerprint('android', deviceId);
     return wrapResponse(buildActionExecutionResult({
         actionType: 'press_back',
+        sourceModule: 'server',
         selector: { key: 'back' },
         success: !!res.success,
         uiFingerprintBefore,

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.26.1'
+    version: '0.26.2'
 };
 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.26.2]
+- unified action execution and verification model 
+
 ## [0.26.1]
 - Fixed overuse of `get_network_activity`