mobile-debug-mcp 0.26.0 → 0.26.2

package/dist/interact/classify.js

@@ -1,35 +1,72 @@
+const ACTION_CATEGORY_BY_TYPE = {
+    tap: 'local_state',
+    tap_element: 'local_state',
+    swipe: 'local_state',
+    scroll_to_element: 'local_state',
+    type_text: 'local_state',
+    press_back: 'local_state',
+    start_app: 'side_effect',
+    restart_app: 'side_effect',
+    terminate_app: 'side_effect',
+    reset_app_data: 'side_effect',
+    install_app: 'side_effect',
+    build_app: 'side_effect',
+    build_and_install: 'side_effect'
+};
+function inferActionCategory(actionType) {
+    if (typeof actionType !== 'string')
+        return null;
+    const normalized = actionType.trim().toLowerCase();
+    if (!normalized)
+        return null;
+    return ACTION_CATEGORY_BY_TYPE[normalized] ?? 'side_effect';
+}
 /**
  * Pure deterministic classifier. Applies rules in fixed order.
  * Same inputs always produce the same output.
  */
 export function classifyActionOutcome(input) {
-    const { uiChanged, expectedElementVisible, networkRequests, hasLogErrors } = input;
+    const { uiChanged, expectedElementVisible, actionType, networkRequests, hasLogErrors } = input;
+    const actionCategory = inferActionCategory(actionType);
     // Step 1 — UI signal is positive
     if (uiChanged || expectedElementVisible === true) {
         return { outcome: 'success', reasoning: expectedElementVisible === true ? 'expected element is visible' : 'UI changed after action' };
     }
-    // Step 2 — UI did not change; network signal is required
-    if (networkRequests === null || networkRequests === undefined) {
+    // Step 2 — no action type means we cannot choose a safe routing path
+    if (actionCategory === null) {
         return {
             outcome: 'unknown',
-            reasoning: 'UI did not change; get_network_activity must be called before classification can proceed',
-            nextAction: 'call_get_network_activity'
+            reasoning: 'actionType was not supplied; pass the runtime action_type so the classifier can distinguish local-state and side-effect routing'
         };
     }
-    // Step 3 — any network failure
-    const failedRequest = networkRequests.find((r) => r.status === 'failure' || r.status === 'retryable');
+    const failedRequest = networkRequests?.find((r) => r.status === 'failure' || r.status === 'retryable');
     if (failedRequest) {
         return { outcome: 'backend_failure', reasoning: `network request ${failedRequest.endpoint} returned ${failedRequest.status}` };
     }
-    // Step 4 — no network requests at all
+    // Step 3 — local-state actions should be verified with state-specific signals first
+    if (actionCategory === 'local_state') {
+        const logNote = hasLogErrors ? ' (log errors present)' : '';
+        return {
+            outcome: 'no_op',
+            reasoning: `local-state action${logNote}; use expect_state, refreshed snapshot comparison, or expect_element_visible instead of defaulting to network inspection`
+        };
+    }
+    // Step 4 — side-effect actions may legitimately need network or log inspection
+    if (networkRequests === null || networkRequests === undefined) {
+        return {
+            outcome: 'unknown',
+            reasoning: 'side-effect action without network data; inspect network or log signals only if the outcome is still ambiguous'
+        };
+    }
+    // Step 5 — no network requests at all
     if (networkRequests.length === 0) {
         const logNote = hasLogErrors ? ' (log errors present)' : '';
-        return { outcome: 'no_op', reasoning: `no UI change and no network activity${logNote}` };
+        return { outcome: 'no_op', reasoning: `side-effect action and no network activity${logNote}` };
     }
-    // Step 5 — network requests exist and all succeeded
+    // Step 6 — network requests exist and all succeeded
     if (networkRequests.every((r) => r.status === 'success')) {
         return { outcome: 'ui_failure', reasoning: 'network requests succeeded but UI did not change' };
     }
-    // Step 6 — fallback
+    // Step 7 — fallback
     return { outcome: 'unknown', reasoning: 'signals are inconclusive' };
 }

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
@@ -344,7 +348,7 @@ Capabilities:
 Constraints:
 - Does not verify correctness of the resulting state
 - Must not be used alone to confirm action success when an applicable expect_* tool exists
-- Use classify_action_outcome + get_network_activity when the expected outcome is backend/API activity without a visible UI change
+- For backend/API activity without a visible UI change, pass the runtime action_type into classify_action_outcome and collect network evidence only if the result remains ambiguous
 
 Recommended Usage:
 1. Capture or define the expected outcome
@@ -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
@@ -918,26 +934,29 @@ Failure Handling:
         name: 'classify_action_outcome',
         description: `Classify the outcome of the most recent action into exactly one of: success, no_op, backend_failure, ui_failure, unknown.
 
-MUST be called after every action (tap, swipe, type_text, press_back, start_app, etc). Never skip.
-Use this with get_network_activity when the expected outcome is backend/API activity without a visible UI change.
-For backend/API activity, compare get_screen_fingerprint before and after the action and call get_network_activity immediately after the action instead of waiting for wait_for_screen_change.
+Use the runtime action result's \`action_type\` as \`actionType\` so the classifier can distinguish local-state actions from side-effect actions.
+Use this when the intended outcome is not already fully verified by the UI signal alone.
+For backend/API activity, compare get_screen_fingerprint before and after the action and call get_network_activity immediately after the action if the outcome is still ambiguous.
 
 HOW TO GATHER INPUTS before calling:
 1. Call wait_for_screen_change or compare get_screen_fingerprint before/after — set uiChanged accordingly.
 2. If you checked for a specific element with wait_for_ui, set expectedElementVisible.
-3. Do NOT call get_network_activity yet — omit networkRequests on the first call.
+3. Pass actionType from the action response when available.
+4. Only provide networkRequests if you already collected them or want to classify a side-effect action with backend evidence.
 
 RULES (applied in order — stop at first match):
 1. If uiChanged=true OR expectedElementVisible=true → outcome=success
-2. Otherwise this tool returns nextAction="call_get_network_activity" — you MUST call get_network_activity once, then call classify_action_outcome again with the results in networkRequests.
+2. If actionType is missing → outcome=unknown
 3. If any request has status=failure or retryable → outcome=backend_failure
-4. If no requests returned → outcome=no_op
-5. If all requests succeeded → outcome=ui_failure
-6. Otherwise → outcome=unknown
+4. If actionType maps to a local-state action → outcome=no_op; prefer state-based verification and avoid default network fallback
+5. If actionType maps to a side-effect action and no networkRequests were supplied → outcome=unknown
+6. If no requests returned → outcome=no_op
+7. If all requests succeeded → outcome=ui_failure
+8. Otherwise → outcome=unknown
 
 BEHAVIOUR after outcome:
 - success → continue
-- no_op → retry the action once or re-resolve the element
+- no_op → retry with richer state verification or re-resolve the element
 - backend_failure → stop and report the failing endpoint
 - ui_failure → stop and report failure
 - unknown → take one recovery step (e.g. capture_debug_snapshot), then stop`,
@@ -952,9 +971,13 @@ BEHAVIOUR after outcome:
                     type: 'boolean',
                     description: 'true if the element you expected to appear is now visible (from wait_for_ui). Omit if you did not check for a specific element.'
                 },
+                actionType: {
+                    type: 'string',
+                    description: 'The runtime action_type from the action response (for example tap, tap_element, swipe, type_text, press_back, start_app).'
+                },
                 networkRequests: {
                     type: 'array',
-                    description: 'Pass this only after calling get_network_activity as instructed by nextAction. Also use it when the expected outcome is backend/API activity without a visible UI change.',
+                    description: 'Optional network evidence collected after the action. Use it when the expected outcome is backend/API activity or when the UI signal is ambiguous.',
                     items: {
                         type: 'object',
                         properties: {
@@ -976,7 +999,7 @@ BEHAVIOUR after outcome:
         name: 'get_network_activity',
         description: `Returns structured network events captured from platform logs since the last action.
 
-Call this when classify_action_outcome returns nextAction="call_get_network_activity" or immediately after an action whose expected outcome is backend/API activity without a visible UI change.
+Call this immediately after an action when you want backend evidence for a side-effect flow, only if the result is still ambiguous.
 Do not call more than once per action.
 
 Events are filtered to significant (non-background) requests only.

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,
@@ -385,11 +392,13 @@ async function handleStopLogStream(args) {
 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
     });

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.0'
+    version: '0.26.2'
 };
 export function createServer() {
     const server = new Server(serverInfo, {

package/docs/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 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`
+
 ## [0.26.0]
 - RFC-003 wait/synchronization contract with `snapshot_revision`, `captured_at_ms`, and `loading_state`
 - Added `wait_for_ui_change` for stable in-place UI mutations