mobile-debug-mcp 0.25.1 → 0.26.1

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

@@ -4,9 +4,11 @@ import { iOSInteract } from './ios.js';
 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';
 export class ToolsInteract {
     static _maxResolvedUiElements = 256;
+    static _uiChangeKinds = ['hierarchy_diff', 'text_change', 'state_change'];
     static _sliderSearchLookahead = 8;
     static _sliderNegativeGapTolerancePx = 32;
     static _sliderPositiveGapLimitPx = 640;
@@ -34,6 +36,9 @@ export class ToolsInteract {
             return null;
         return normalized;
     }
+    static _hash(value) {
+        return createHash('sha256').update(JSON.stringify(value)).digest('hex');
+    }
     static _matchesSelector(el, selector) {
         if (!selector)
             return false;
@@ -135,6 +140,52 @@ export class ToolsInteract {
             return null;
         }
     }
+    static _buildUiChangeSignatures(tree) {
+        const elements = Array.isArray(tree?.elements) ? tree.elements : [];
+        const textPayload = [];
+        const statePayload = [];
+        for (const el of elements) {
+            textPayload.push({
+                text: ToolsInteract._normalize(el?.text ?? el?.label ?? el?.value ?? ''),
+                contentDescription: ToolsInteract._normalize(el?.contentDescription ?? el?.contentDesc ?? el?.accessibilityLabel ?? ''),
+                resourceId: ToolsInteract._normalize(el?.resourceId ?? el?.resourceID ?? el?.id ?? '')
+            });
+            statePayload.push({
+                checked: el?.state?.checked ?? null,
+                selected: el?.state?.selected ?? null,
+                focused: el?.state?.focused ?? null,
+                expanded: el?.state?.expanded ?? null,
+                enabled: el?.state?.enabled ?? null,
+                text_value: el?.state?.text_value ?? null,
+                value: el?.state?.value ?? null,
+                raw_value: el?.state?.raw_value ?? null,
+                value_range: el?.state?.value_range ?? null
+            });
+        }
+        return {
+            hierarchy: computeSnapshotSignature(tree),
+            text: ToolsInteract._hash({
+                screen: ToolsInteract._normalize(tree?.screen),
+                elements: textPayload
+            }),
+            state: ToolsInteract._hash({
+                screen: ToolsInteract._normalize(tree?.screen),
+                elements: statePayload
+            })
+        };
+    }
+    static _matchesUiChange(expected, initial, current) {
+        const candidates = expected ? [expected] : ToolsInteract._uiChangeKinds;
+        for (const changeKind of candidates) {
+            if (changeKind === 'hierarchy_diff' && initial.hierarchy !== current.hierarchy)
+                return changeKind;
+            if (changeKind === 'text_change' && initial.text !== current.text)
+                return changeKind;
+            if (changeKind === 'state_change' && initial.state !== current.state)
+                return changeKind;
+        }
+        return null;
+    }
     static _resolvedTargetFromElement(elementId, element, index) {
         return {
             elementId,
@@ -876,6 +927,68 @@ export class ToolsInteract {
             }
         };
     }
+    static async waitForUIChangeHandler({ platform, deviceId, timeout_ms = 60000, stability_window_ms = 250, expected_change }) {
+        const start = Date.now();
+        const pollIntervalMs = 300;
+        const stabilityWindow = Math.max(0, typeof stability_window_ms === 'number' ? stability_window_ms : 250);
+        let baseline = null;
+        let lastObservedRevision = null;
+        let lastLoadingState = null;
+        while (Date.now() - start < timeout_ms) {
+            try {
+                const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId });
+                const signatures = ToolsInteract._buildUiChangeSignatures(tree);
+                lastObservedRevision = typeof tree?.snapshot_revision === 'number' ? tree.snapshot_revision : lastObservedRevision;
+                lastLoadingState = tree?.loading_state ?? lastLoadingState;
+                if (!baseline) {
+                    baseline = signatures;
+                }
+                else {
+                    const observedChange = ToolsInteract._matchesUiChange(expected_change, baseline, signatures);
+                    if (observedChange) {
+                        if (stabilityWindow > 0) {
+                            await new Promise(resolve => setTimeout(resolve, stabilityWindow));
+                            const confirmTree = await ToolsObserve.getUITreeHandler({ platform, deviceId });
+                            const confirmSignatures = ToolsInteract._buildUiChangeSignatures(confirmTree);
+                            const confirmChange = ToolsInteract._matchesUiChange(expected_change, baseline, confirmSignatures);
+                            if (!confirmChange || confirmSignatures.hierarchy !== signatures.hierarchy || confirmSignatures.text !== signatures.text || confirmSignatures.state !== signatures.state) {
+                                lastObservedRevision = typeof confirmTree?.snapshot_revision === 'number' ? confirmTree.snapshot_revision : lastObservedRevision;
+                                lastLoadingState = confirmTree?.loading_state ?? lastLoadingState;
+                                await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+                                continue;
+                            }
+                            lastObservedRevision = typeof confirmTree?.snapshot_revision === 'number' ? confirmTree.snapshot_revision : lastObservedRevision;
+                            lastLoadingState = confirmTree?.loading_state ?? lastLoadingState;
+                        }
+                        return {
+                            success: true,
+                            observed_change: observedChange,
+                            snapshot_revision: lastObservedRevision ?? undefined,
+                            timeout: false,
+                            elapsed_ms: Date.now() - start,
+                            expected_change,
+                            loading_state: lastLoadingState ?? null,
+                            reason: 'UI change observed'
+                        };
+                    }
+                }
+            }
+            catch {
+                // Keep polling until timeout; the observable surface should be best-effort.
+            }
+            await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+        }
+        return {
+            success: false,
+            observed_change: null,
+            snapshot_revision: lastObservedRevision ?? undefined,
+            timeout: true,
+            elapsed_ms: Date.now() - start,
+            expected_change,
+            loading_state: lastLoadingState ?? null,
+            reason: 'timeout'
+        };
+    }
     static async expectScreenHandler({ platform, fingerprint, screen, deviceId }) {
         const observedFingerprint = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId });
         const observedScreen = {

package/dist/observe/android.js

@@ -6,6 +6,7 @@ import { promises as fsPromises } from "fs";
 import path from "path";
 import { computeScreenFingerprint } from "../utils/ui/index.js";
 import { parsePngSize } from "../utils/image.js";
+import { deriveSnapshotMetadata } from "./snapshot-metadata.js";
 const activeLogStreams = new Map();
 export class AndroidObserve {
     async getDeviceMetadata(appId, deviceId) {
@@ -61,21 +62,29 @@ export class AndroidObserve {
                     traverseNode(result.hierarchy.node, elements);
                 }
             }
+            const snapshotMetadata = deriveSnapshotMetadata(`android:${deviceInfo.id}`, {
+                screen: "",
+                resolution,
+                elements
+            }, 'ui_tree');
             return {
                 device: deviceInfo,
                 screen: "",
                 resolution,
-                elements
+                elements,
+                ...snapshotMetadata
             };
         }
         catch (e) {
             const errorMessage = `Failed to get UI tree. ADB Path: '${getAdbCmd()}'. Error: ${e instanceof Error ? e.message : String(e)}`;
             console.error(errorMessage);
+            const snapshotMetadata = deriveSnapshotMetadata(`android:${deviceInfo.id}`, null, 'ui_tree');
             return {
                 device: deviceInfo,
                 screen: "",
                 resolution: { width: 0, height: 0 },
                 elements: [],
+                ...snapshotMetadata,
                 error: errorMessage
             };
         }

package/dist/observe/index.js

@@ -1,6 +1,7 @@
 import { resolveTargetDevice } from '../utils/resolve-device.js';
 import { AndroidObserve } from './android.js';
 import { iOSObserve } from './ios.js';
+import { deriveSnapshotMetadata } from './snapshot-metadata.js';
 export { AndroidObserve } from './android.js';
 export { iOSObserve } from './ios.js';
 function normalizeHint(value) {
@@ -200,7 +201,17 @@ export class ToolsObserve {
     }
     static async captureDebugSnapshotHandler({ reason, includeLogs = true, logLines = 200, platform, appId, deviceId, sessionId } = {}) {
         const timestamp = Date.now();
-        const raw = { timestamp, reason: reason || '', activity: null, fingerprint: null, screenshot: null, ui_tree: null, logs: [] };
+        const raw = {
+            timestamp,
+            snapshot_revision: 0,
+            captured_at_ms: timestamp,
+            reason: reason || '',
+            activity: null,
+            fingerprint: null,
+            screenshot: null,
+            ui_tree: null,
+            logs: []
+        };
         // Parallel fetches for performance: screenshot, current screen, fingerprint, ui tree, and log stream/get logs
         const sid = sessionId || 'default';
         const tasks = {
@@ -308,6 +319,13 @@ export class ToolsObserve {
                 raw.logs_error = e instanceof Error ? e.message : String(e);
             }
         }
+        const snapshotDeviceKey = raw.ui_tree?.device
+            ? `${raw.ui_tree.device.platform}:${raw.ui_tree.device.id}`
+            : `${platform || 'unknown'}:${deviceId || 'default'}`;
+        const snapshotMetadata = deriveSnapshotMetadata(snapshotDeviceKey, raw.ui_tree, 'snapshot', raw.ui_tree?.snapshot_revision ? null : (raw.fingerprint || raw.activity || null));
+        raw.snapshot_revision = raw.ui_tree?.snapshot_revision ?? snapshotMetadata.snapshot_revision;
+        raw.captured_at_ms = raw.ui_tree?.captured_at_ms ?? snapshotMetadata.captured_at_ms;
+        raw.loading_state = raw.ui_tree?.loading_state ?? snapshotMetadata.loading_state;
         const semantic = deriveSnapshotSemantic(raw);
         return semantic ? { raw, semantic } : { raw };
     }

package/dist/observe/ios.js

@@ -6,6 +6,7 @@ import path from 'path';
 import { parseLogLine } from '../utils/android/utils.js';
 import { computeScreenFingerprint } from '../utils/ui/index.js';
 import { parsePngSize } from '../utils/image.js';
+import { deriveSnapshotMetadata } from './snapshot-metadata.js';
 const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));
 let iosExecCommand = execCommand;
 export function _setIOSExecCommandForTests(fn) {
@@ -438,13 +439,16 @@ export class iOSObserve {
     }
     async getUITree(deviceId = "booted") {
         const device = await getIOSDeviceMetadata(deviceId);
+        const deviceKey = `ios:${device.id}`;
         const idbExists = await isIDBInstalled();
         if (!idbExists) {
+            const snapshotMetadata = deriveSnapshotMetadata(deviceKey, null, 'ui_tree');
             return {
                 device,
                 screen: "",
                 resolution: { width: 0, height: 0 },
                 elements: [],
+                ...snapshotMetadata,
                 error: "iOS UI tree retrieval requires 'idb' (iOS Device Bridge). Please install it via Homebrew: `brew tap facebook/fb && brew install idb-companion` and `pip3 install fb-idb`."
             };
         }
@@ -485,11 +489,13 @@ export class iOSObserve {
                 console.error(`Attempt ${attempts} failed: ${e}`);
             }
             if (attempts === maxAttempts) {
+                const snapshotMetadata = deriveSnapshotMetadata(deviceKey, null, 'ui_tree');
                 return {
                     device,
                     screen: "",
                     resolution: { width: 0, height: 0 },
                     elements: [],
+                    ...snapshotMetadata,
                     error: `Failed to retrieve valid UI dump after ${maxAttempts} attempts.`
                 };
             }
@@ -511,19 +517,27 @@ export class iOSObserve {
                 width = rootBounds[2] - rootBounds[0];
                 height = rootBounds[3] - rootBounds[1];
             }
+            const snapshotMetadata = deriveSnapshotMetadata(deviceKey, {
+                screen: "",
+                resolution: { width, height },
+                elements
+            }, 'ui_tree');
             return {
                 device,
                 screen: "",
                 resolution: { width, height },
-                elements
+                elements,
+                ...snapshotMetadata
             };
         }
         catch (e) {
+            const snapshotMetadata = deriveSnapshotMetadata(deviceKey, null, 'ui_tree');
             return {
                 device,
                 screen: "",
                 resolution: { width: 0, height: 0 },
                 elements: [],
+                ...snapshotMetadata,
                 error: `Failed to parse idb output: ${e instanceof Error ? e.message : String(e)}`
             };
         }

package/dist/observe/snapshot-metadata.js

@@ -0,0 +1,88 @@
+import crypto from 'crypto';
+const snapshotStateByDevice = new Map();
+function normalize(value) {
+    if (value === null || value === undefined)
+        return '';
+    return String(value).trim().toLowerCase();
+}
+function normalizeBounds(bounds) {
+    if (!Array.isArray(bounds) || bounds.length < 4)
+        return null;
+    const normalized = bounds.slice(0, 4).map((value) => Number(value));
+    if (normalized.some((value) => Number.isNaN(value)))
+        return null;
+    return normalized;
+}
+function stableElementSignature(element) {
+    return {
+        text: normalize(element.text),
+        contentDescription: normalize(element.contentDescription),
+        resourceId: normalize(element.resourceId),
+        type: normalize(element.type),
+        stable_id: normalize(element.stable_id),
+        role: normalize(element.role),
+        test_tag: normalize(element.test_tag),
+        selector: normalize(element.selector?.value),
+        clickable: !!element.clickable,
+        enabled: !!element.enabled,
+        visible: !!element.visible,
+        state: element.state ?? null,
+        bounds: normalizeBounds(element.bounds)
+    };
+}
+export function computeSnapshotSignature(tree) {
+    if (!tree || tree.error)
+        return null;
+    const payload = {
+        screen: normalize(tree.screen),
+        resolution: tree.resolution || { width: 0, height: 0 },
+        elements: Array.isArray(tree.elements) ? tree.elements.map((element) => stableElementSignature(element)) : []
+    };
+    return crypto.createHash('sha256').update(JSON.stringify(payload)).digest('hex');
+}
+export function detectLoadingState(tree, source) {
+    if (!tree || tree.error || !Array.isArray(tree.elements))
+        return null;
+    for (const element of tree.elements) {
+        if (!element?.visible)
+            continue;
+        const text = normalize(element?.text ?? element?.contentDescription ?? '');
+        const type = normalize(element?.type ?? '');
+        const combined = `${type} ${text}`;
+        if (/progress|spinner|loading|please wait|busy|loading indicator|skeleton|pending/.test(combined)) {
+            const signal = /progress/.test(combined)
+                ? 'progress_indicator'
+                : /spinner/.test(combined)
+                    ? 'spinner'
+                    : /busy/.test(combined)
+                        ? 'busy_indicator'
+                        : /skeleton/.test(combined)
+                            ? 'skeleton'
+                            : 'loading_indicator';
+            return { active: true, signal, source };
+        }
+    }
+    return null;
+}
+export function deriveSnapshotMetadata(deviceKey, tree, source, signatureOverride) {
+    const signature = signatureOverride ?? computeSnapshotSignature(tree);
+    const previous = snapshotStateByDevice.get(deviceKey);
+    let revision = 1;
+    if (previous) {
+        if (signature === null) {
+            revision = previous.revision;
+        }
+        else {
+            revision = previous.signature === signature ? previous.revision : previous.revision + 1;
+        }
+    }
+    snapshotStateByDevice.set(deviceKey, { revision, signature });
+    return {
+        snapshot_revision: revision,
+        captured_at_ms: Date.now(),
+        loading_state: detectLoadingState(tree, source)
+    };
+}
+export function resetSnapshotMetadataForTests() {
+    snapshotStateByDevice.clear();
+}

package/dist/server/tool-definitions.js

@@ -240,7 +240,7 @@ Failure Handling:
     },
     {
         name: 'capture_debug_snapshot',
-        description: 'Capture a complete debug snapshot (raw observation layer plus optional derived semantic layer). Returns structured JSON.',
+        description: 'Capture a complete debug snapshot (raw observation layer plus optional derived semantic layer). Returns structured JSON with snapshot_revision, captured_at_ms, and loading_state when detectable.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -291,7 +291,7 @@ Failure Handling:
     },
     {
         name: 'get_ui_tree',
-        description: 'Get the current UI hierarchy from an Android device or iOS simulator. Returns a structured JSON representation of the screen content.',
+        description: 'Get the current UI hierarchy from an Android device or iOS simulator. Returns a structured JSON representation of the screen content with snapshot metadata when available.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -344,7 +344,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
@@ -363,6 +363,34 @@ Recommended Usage:
             required: ['previousFingerprint']
         }
     },
+    {
+        name: 'wait_for_ui_change',
+        description: `Purpose:
+Wait for a non-navigation UI mutation or in-place update to become stable.
+
+Inputs:
+- expected_change (optional): hierarchy_diff, text_change, or state_change
+- timeout_ms (optional)
+- stability_window_ms (optional)
+
+Guidance:
+- Prefer wait_for_screen_change for navigation transitions.
+- Prefer wait_for_ui_change for in-place mutations and non-navigation updates.
+- Use the returned snapshot_revision as the observed synchronization point when available.
+
+Failure Handling:
+- TIMEOUT means the UI did not change in a stable way within the allotted time.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                platform: { type: 'string', enum: ['android', 'ios'], description: 'Optional platform override (android|ios)' },
+                deviceId: { type: 'string', description: 'Optional device id/udid to target' },
+                expected_change: { type: 'string', enum: ['hierarchy_diff', 'text_change', 'state_change'], description: 'Optional type of UI change to wait for' },
+                timeout_ms: { type: 'number', description: 'Timeout in ms to wait for change (default 60000)', default: 60000 },
+                stability_window_ms: { type: 'number', description: 'How long the change must remain stable before success (default 250)', default: 250 }
+            }
+        }
+    },
     {
         name: 'expect_screen',
         description: `Purpose:
@@ -890,26 +918,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`,
@@ -924,9 +955,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: {
@@ -948,7 +983,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

@@ -236,6 +236,15 @@ async function handleWaitForUI(args) {
     const res = await ToolsInteract.waitForUIHandler({ selector, condition, timeout_ms, poll_interval_ms, match, retry, platform, deviceId });
     return wrapResponse(res);
 }
+async function handleWaitForUIChange(args) {
+    const platform = getStringArg(args, 'platform');
+    const deviceId = getStringArg(args, 'deviceId');
+    const timeout_ms = getNumberArg(args, 'timeout_ms') ?? 60000;
+    const stability_window_ms = getNumberArg(args, 'stability_window_ms') ?? 250;
+    const expected_change = getStringArg(args, 'expected_change');
+    const res = await ToolsInteract.waitForUIChangeHandler({ platform, deviceId, timeout_ms, stability_window_ms, expected_change });
+    return wrapResponse(res);
+}
 async function handleFindElement(args) {
     const query = requireStringArg(args, 'query');
     const exact = getBooleanArg(args, 'exact') ?? false;
@@ -376,11 +385,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
     });
@@ -409,6 +420,7 @@ export const toolHandlers = {
     get_current_screen: handleGetCurrentScreen,
     get_screen_fingerprint: handleGetScreenFingerprint,
     wait_for_screen_change: handleWaitForScreenChange,
+    wait_for_ui_change: handleWaitForUIChange,
     expect_screen: handleExpectScreen,
     expect_element_visible: handleExpectElementVisible,
     expect_state: handleExpectState,

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

package/docs/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [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
+- Updated `get_ui_tree` and `capture_debug_snapshot` to surface snapshot metadata
+- Emulator-validated the new UI-change flow against the Modul8 app
+
 ## [0.25.1]
 - Platform-native element identity metadata for UI targeting
 - Hierarchy-independent element references