mobile-debug-mcp 0.30.2 → 0.32.0

package/README.md

@@ -16,11 +16,36 @@ A minimal, secure MCP server for AI-assisted mobile development. Build, install,
 - Xcode command-line tools for iOS support
 - [idb](https://github.com/facebook/idb) for iOS device support
 
+## Environment Setup
+
+The server discovers Android and iOS tools automatically from standard locations by default. Manual environment setup is still supported, but it should be treated as the fallback for non-standard installs, overrides, or reproducible pinned toolchains.
+
+Use explicit paths when:
+- you have multiple SDKs installed
+- the tools live outside standard locations
+- you want deterministic setup across machines
+- automatic discovery does not find the expected binary
+
+Leave the variables unset when:
+- the tools are already on `PATH`
+- the standard Android and Xcode locations are enough
+
+Common environment variables:
+- `ADB_PATH`: explicit path to `adb`
+- `ANDROID_SDK_ROOT` or `ANDROID_HOME`: Android SDK root
+- `XCRUN_PATH`: explicit path to `xcrun`
+- `MCP_IDB_PATH` or `IDB_PATH`: explicit path to `idb`
+- `GRADLE_JAVA_HOME` or `JAVA_HOME`: Java home for Gradle-backed operations
+
+For normal use, call `get_system_status` first. It reports the detected host, Android, and iOS toolchain state so the client can decide whether automatic discovery is sufficient or whether explicit overrides are needed.
+
 ## Configuration
 
 <details>
 
-<summary>Android Studio</summary>
+<summary>Android setup</summary>
+
+Recommended when you want Android only, or when you want to make the Android toolchain explicit.
 
 ```json
 {
@@ -28,17 +53,25 @@ A minimal, secure MCP server for AI-assisted mobile development. Build, install,
     "mobile-debug": {
       "command": "npx",
       "args": ["--yes","mobile-debug-mcp","server"],
-      "env": { "ADB_PATH": "/path/to/adb", "XCRUN_PATH": "/usr/bin/xcrun", "IDB_PATH": "/path/to/idb" }
+      "env": {
+        "ADB_PATH": "/path/to/adb",
+        "ANDROID_SDK_ROOT": "/path/to/android/sdk",
+        "GRADLE_JAVA_HOME": "/path/to/jdk"
+      }
     }
   }
 }
 ```
 
+For Android-only setups, `XCRUN_PATH` and `IDB_PATH` are not required unless you want to pin them explicitly.
+
 </details>
 
 <details>
 
-<summary>Copilot</summary>
+<summary>iOS setup</summary>
+
+Recommended when you want iOS simulator or device support, or when `idb` lives in a non-standard location.
 
 ```json
 {
@@ -46,12 +79,18 @@ A minimal, secure MCP server for AI-assisted mobile development. Build, install,
     "mobile-debug": {
       "command": "npx",
       "args": ["--yes","mobile-debug-mcp","server"],
-      "env": { "ADB_PATH": "/path/to/adb", "XCRUN_PATH": "/usr/bin/xcrun", "IDB_PATH": "/path/to/idb" }
+      "env": {
+        "XCRUN_PATH": "/usr/bin/xcrun",
+        "MCP_IDB_PATH": "/path/to/idb",
+        "IDB_PATH": "/path/to/idb"
+      }
     }
   }
 }
 ```
 
+For iOS-only setups, `ADB_PATH` and `ANDROID_SDK_ROOT` are not required unless you want to pin them explicitly.
+
 </details>
 
 <details>
@@ -69,7 +108,13 @@ args:
 environment variables:
 * ADB_PATH: /path/to/adb
 * XCRUN_PATH: /usr/bin/xcrun
-* IDC_PATH: /path/to/idb"
+* IDB_PATH: /path/to/idb
+* MCP_IDB_PATH: /path/to/idb
+* ANDROID_SDK_ROOT: /path/to/android/sdk
+* GRADLE_JAVA_HOME: /path/to/jdk
+* JAVA_HOME: /path/to/jdk
+
+If you are unsure whether the environment is configured correctly, run `get_system_status` first. It reports the detected host, Android, and iOS toolchain state in a structured form.
 
 </details>
 

package/dist/interact/android.js

@@ -1,49 +1,54 @@
+import { markDispatchStarted } from '../utils/operation-budget.js';
 import { execAdb, getAndroidDeviceMetadata, getDeviceInfo } from "../utils/android/utils.js";
 import { AndroidObserve } from "../observe/index.js";
 import { scrollToElementShared } from "../utils/ui/index.js";
 export class AndroidInteract {
     observe = new AndroidObserve();
-    async tap(x, y, deviceId) {
+    async tap(x, y, deviceId, timeoutMs) {
         const metadata = await getAndroidDeviceMetadata("", deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
         try {
-            await execAdb(['shell', 'input', 'tap', x.toString(), y.toString()], deviceId);
+            markDispatchStarted();
+            await execAdb(['shell', 'input', 'tap', x.toString(), y.toString()], deviceId, { timeout: timeoutMs });
             return { device: deviceInfo, success: true, x, y };
         }
         catch (e) {
             return { device: deviceInfo, success: false, x, y, error: e instanceof Error ? e.message : String(e) };
         }
     }
-    async swipe(x1, y1, x2, y2, duration, deviceId) {
+    async swipe(x1, y1, x2, y2, duration, deviceId, timeoutMs) {
         const metadata = await getAndroidDeviceMetadata("", deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
         try {
-            await execAdb(['shell', 'input', 'swipe', x1.toString(), y1.toString(), x2.toString(), y2.toString(), duration.toString()], deviceId);
+            markDispatchStarted();
+            await execAdb(['shell', 'input', 'swipe', x1.toString(), y1.toString(), x2.toString(), y2.toString(), duration.toString()], deviceId, { timeout: timeoutMs });
             return { device: deviceInfo, success: true, start: [x1, y1], end: [x2, y2], duration };
         }
         catch (e) {
             return { device: deviceInfo, success: false, start: [x1, y1], end: [x2, y2], duration, error: e instanceof Error ? e.message : String(e) };
         }
     }
-    async typeText(text, deviceId) {
+    async typeText(text, deviceId, timeoutMs) {
         const metadata = await getAndroidDeviceMetadata("", deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
         try {
             // Encode spaces as %s to ensure proper input handling by adb shell input text
             const encodedText = text.replace(/\s/g, '%s');
             // Note: 'input text' might fail with some characters or if keyboard isn't ready, but it's the standard ADB way.
-            await execAdb(['shell', 'input', 'text', encodedText], deviceId);
+            markDispatchStarted();
+            await execAdb(['shell', 'input', 'text', encodedText], deviceId, { timeout: timeoutMs });
             return { device: deviceInfo, success: true, text };
         }
         catch (e) {
             return { device: deviceInfo, success: false, text, error: e instanceof Error ? e.message : String(e) };
         }
     }
-    async pressBack(deviceId) {
+    async pressBack(deviceId, timeoutMs) {
         const metadata = await getAndroidDeviceMetadata("", deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
         try {
-            await execAdb(['shell', 'input', 'keyevent', '4'], deviceId);
+            markDispatchStarted();
+            await execAdb(['shell', 'input', 'keyevent', '4'], deviceId, { timeout: timeoutMs });
             return { device: deviceInfo, success: true };
         }
         catch (e) {

package/dist/interact/index.js

@@ -1,3 +1,4 @@
+import { remainingBudget } from '../utils/operation-budget.js';
 import { createHash } from 'crypto';
 import { AndroidInteract } from './android.js';
 import { iOSInteract } from './ios.js';
@@ -950,19 +951,19 @@ export class ToolsInteract {
         const interact = effectivePlatform === 'android' ? new AndroidInteract() : new iOSInteract();
         return { interact: interact, resolved, platform: effectivePlatform };
     }
-    static async tapHandler({ platform, x, y, deviceId }) {
+    static async tapHandler({ platform, x, y, deviceId, timeoutMs }) {
         const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId);
-        return await interact.tap(x, y, resolved.id);
+        return await interact.tap(x, y, resolved.id, timeoutMs);
     }
-    static async tapElementHandler({ elementId }) {
+    static async tapElementHandler({ elementId, verificationMode = 'full', timeoutMs, platform, deviceId, freshTree }) {
         const actionType = 'tap_element';
         const selector = { elementId };
         const resolved = ToolsInteract._resolvedUiElements.get(elementId);
-        if (!resolved) {
+        if (!resolved || (platform && resolved.platform !== platform) || (deviceId && resolved.deviceId !== deviceId)) {
             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 });
+        const fingerprintBefore = verificationMode === 'full' ? await ToolsInteract._captureFingerprint(resolved.platform, resolved.deviceId) : null;
+        const tree = freshTree ?? await ToolsObserve.getUITreeHandler({ platform: resolved.platform, deviceId: resolved.deviceId });
         const treePlatform = tree?.device?.platform === 'ios' ? 'ios' : resolved.platform;
         const treeDeviceId = tree?.device?.id || resolved.deviceId;
         const elements = Array.isArray(tree?.elements) ? tree.elements : [];
@@ -981,12 +982,12 @@ export class ToolsInteract {
         }
         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 });
+        const tapResult = await ToolsInteract.tapHandler({ platform: resolved.platform, x, y, deviceId: resolved.deviceId, timeoutMs });
         if (!tapResult.success) {
-            const fingerprintAfterFailure = await ToolsInteract._captureFingerprint(resolved.platform, resolved.deviceId);
-            return ToolsInteract._actionFailure(actionType, selector, resolvedTarget, 'UNKNOWN', false, fingerprintBefore, fingerprintAfterFailure);
+            const fingerprintAfterFailure = verificationMode === 'full' ? await ToolsInteract._captureFingerprint(resolved.platform, resolved.deviceId) : null;
+            return { ...ToolsInteract._actionFailure(actionType, selector, resolvedTarget, 'UNKNOWN', false, fingerprintBefore, fingerprintAfterFailure), error: tapResult.error };
         }
-        const fingerprintAfter = await ToolsInteract._captureFingerprint(resolved.platform, resolved.deviceId);
+        const fingerprintAfter = verificationMode === 'full' ? await ToolsInteract._captureFingerprint(resolved.platform, resolved.deviceId) : null;
         return buildActionExecutionResult({
             actionType,
             device: tree?.device,
@@ -1756,17 +1757,17 @@ export class ToolsInteract {
         const uiFingerprintAfter = await ToolsInteract._captureFingerprint(resolvedPlatform, resolvedDeviceId);
         return buildFailure('CONTROL_CONVERGENCE_FAILED', 'control did not converge within the allotted attempts', resolvedTarget, currentDevice, lastObservedState, attemptCount, lastAdjustmentMode, true, uiFingerprintAfter);
     }
-    static async swipeHandler({ platform = 'android', x1, y1, x2, y2, duration, deviceId }) {
+    static async swipeHandler({ platform = 'android', x1, y1, x2, y2, duration, deviceId, timeoutMs }) {
         const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId);
-        return await interact.swipe(x1, y1, x2, y2, duration, resolved.id);
+        return await interact.swipe(x1, y1, x2, y2, duration, resolved.id, timeoutMs);
     }
-    static async typeTextHandler({ text, deviceId }) {
+    static async typeTextHandler({ text, deviceId, timeoutMs }) {
         const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
-        return await new AndroidInteract().typeText(text, resolved.id);
+        return await new AndroidInteract().typeText(text, resolved.id, timeoutMs);
     }
-    static async pressBackHandler({ deviceId }) {
+    static async pressBackHandler({ deviceId, timeoutMs }) {
         const resolved = await resolveTargetDevice({ platform: 'android', deviceId });
-        return await new AndroidInteract().pressBack(resolved.id);
+        return await new AndroidInteract().pressBack(resolved.id, timeoutMs);
     }
     static async scrollToElementHandler({ platform, selector, direction = 'down', maxScrolls = 10, scrollAmount = 0.7, deviceId }) {
         const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId);
@@ -2067,7 +2068,7 @@ export class ToolsInteract {
         };
         return { found: true, element: outEl, score: scoreVal, confidence: scoreVal, resolution };
     }
-    static async waitForUIHandler({ selector, condition = 'exists', timeout_ms = 60000, poll_interval_ms = 300, match, retry = { max_attempts: 1, backoff_ms: 0 }, platform, deviceId }) {
+    static async waitForUIHandler({ selector, condition = 'exists', timeout_ms = 60000, poll_interval_ms = 300, match, retry = { max_attempts: 1, backoff_ms: 0 }, platform, deviceId, singleObservation = false, singleAttempt = false, rejectAmbiguous = false }) {
         const overallStart = Date.now();
         const requestedIndex = typeof match?.index === 'number' ? match.index : null;
         const requested = {
@@ -2109,7 +2110,7 @@ export class ToolsInteract {
         let lastConditionSatisfied = false;
         let matchedAt = null;
         let stableMatchCount = 0;
-        const stableObservationCount = 2;
+        const stableObservationCount = singleObservation ? 1 : 2;
         const snapshotStaleThresholdMs = 500;
         // Precompute normalized selector values and helpers (constant across polls)
         const normalize = ToolsInteract._normalize;
@@ -2122,7 +2123,8 @@ export class ToolsInteract {
                 attempts++;
                 const attemptStart = Date.now();
                 const deadline = attemptStart + (timeout_ms || 0);
-                while (Date.now() <= deadline) {
+                while (Date.now() <= deadline || (singleAttempt && totalPollCount === 0)) {
+                    remainingBudget();
                     totalPollCount++;
                     try {
                         const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId });
@@ -2172,6 +2174,8 @@ export class ToolsInteract {
                         }
                         // Evaluate condition
                         const matchedCount = matches.length;
+                        if (rejectAmbiguous && matchedCount > 1 && match?.index === undefined)
+                            return { status: 'timeout', error: { code: 'AMBIGUOUS_TARGET' } };
                         const pickIndex = (typeof match?.index === 'number') ? match.index : undefined;
                         let chosen = null;
                         if (matches.length > 0) {
@@ -2237,6 +2241,7 @@ export class ToolsInteract {
                                 const outEl = lastMatchedElement;
                                 return {
                                     status: 'success',
+                                    ...(singleObservation ? { _tree: tree } : {}),
                                     matched: matchedCount,
                                     element: outEl,
                                     metrics: { latency_ms, poll_count: totalPollCount, attempts },
@@ -2256,9 +2261,13 @@ export class ToolsInteract {
                         }
                     }
                     catch (e) {
+                        if (e instanceof Error && e.message === 'ACTION_TIMEOUT')
+                            throw e;
                         // Non-fatal per-poll error; record and continue
                         console.warn('waitForUI: poll error (non-fatal):', e instanceof Error ? e.message : String(e));
                     }
+                    if (singleAttempt)
+                        break;
                     // Sleep until next poll
                     await new Promise(r => setTimeout(r, effectivePoll || 50));
                 }
@@ -2289,6 +2298,8 @@ export class ToolsInteract {
             }
         }
         catch (err) {
+            if (err instanceof Error && err.message === 'ACTION_TIMEOUT')
+                throw err;
             const elapsed = Date.now() - overallStart;
             return {
                 status: 'timeout',
@@ -2665,15 +2676,15 @@ export class ToolsInteract {
             })
         };
     }
-    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 }) {
+    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, exact_budget = false }) {
         const compareBoolean = (value) => typeof value === 'boolean' ? value : null;
         const compareString = (value) => typeof value === 'string' ? value : null;
         const compareNumber = (value) => typeof value === 'number' && Number.isFinite(value) ? value : null;
         const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
         const start = Date.now();
-        const deadline = start + Math.max(500, stabilization_window_ms);
+        const deadline = start + (exact_budget ? stabilization_window_ms : Math.max(500, stabilization_window_ms));
         const stableTarget = Math.max(1, Math.floor(stable_observation_count || 2));
-        const pollDelay = Math.max(100, Math.min(poll_interval_ms || 150, 200));
+        const pollDelay = exact_budget ? Math.max(50, Math.min(poll_interval_ms || 150, 1000)) : Math.max(100, Math.min(poll_interval_ms || 150, 200));
         const staleThreshold = Math.max(300, Math.min(snapshot_stale_threshold_ms || 500, 800));
         let attempts = 0;
         let stableCount = 0;

package/dist/interact/ios.js

@@ -1,3 +1,4 @@
+import { remainingBudget, markDispatchStarted } from '../utils/operation-budget.js';
 import { spawn } from "child_process";
 import { getIOSDeviceMetadata, getIdbCmd, isIDBInstalled } from "../utils/ios/utils.js";
 import { iOSObserve } from "../observe/index.js";
@@ -24,7 +25,8 @@ export class iOSInteract {
                 args.push('--udid', targetUdid);
             }
             await new Promise((resolve, reject) => {
-                const proc = spawn(getIdbCmd(), args);
+                markDispatchStarted();
+                const proc = spawn(getIdbCmd(), args, { timeout: remainingBudget() || undefined });
                 let stderr = '';
                 proc.stderr.on('data', d => stderr += d.toString());
                 proc.on('close', code => {
@@ -63,7 +65,8 @@ export class iOSInteract {
                 args.push('--udid', targetUdid);
             }
             await new Promise((resolve, reject) => {
-                const proc = spawn(getIdbCmd(), args);
+                markDispatchStarted();
+                const proc = spawn(getIdbCmd(), args, { timeout: remainingBudget() || undefined });
                 let stderr = '';
                 proc.stderr.on('data', d => stderr += d.toString());
                 proc.on('close', code => {

package/dist/manage/android.js

@@ -1,3 +1,4 @@
+import { hasFiniteBudget, markDispatchStarted, remainingBudget, runWithBudget } from '../utils/operation-budget.js';
 import { promises as fs } from 'fs';
 import { spawn } from 'child_process';
 import path from 'path';
@@ -145,16 +146,18 @@ export class AndroidManage {
             return { device: deviceInfo, installed: false, error: e instanceof Error ? e.message : String(e), diagnostics: { installDiag, pushDiag, pmDiag } };
         }
     }
-    async startApp(appId, deviceId) {
+    async startApp(appId, deviceId, timeoutMs) {
+        const started = performance.now();
         const metadata = await getAndroidDeviceMetadata(appId, deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
         try {
-            const output = await execAdb(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId);
+            markDispatchStarted();
+            const output = await execAdb(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId, { timeout: timeoutMs });
             const current = await new AndroidObserve().getCurrentScreen(deviceId).catch(() => null);
             return {
                 device: deviceInfo,
                 appStarted: true,
-                launchTimeMs: 1000,
+                launchTimeMs: performance.now() - started,
                 output,
                 observedApp: {
                     appId,
@@ -166,25 +169,31 @@ export class AndroidManage {
             };
         }
         catch (e) {
-            const diag = execAdbWithDiagnostics(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId);
-            return { device: deviceInfo, appStarted: false, launchTimeMs: 0, error: e instanceof Error ? e.message : String(e), diagnostics: diag };
+            const diagnostics = timeoutMs === undefined ? execAdbWithDiagnostics(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId) : undefined;
+            return { device: deviceInfo, appStarted: false, launchTimeMs: performance.now() - started, error: e instanceof Error ? e.message : String(e), ...(diagnostics ? { diagnostics } : {}) };
         }
     }
     async terminateApp(appId, deviceId) {
         const metadata = await getAndroidDeviceMetadata(appId, deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
         try {
+            markDispatchStarted();
             await execAdb(['shell', 'am', 'force-stop', appId], deviceId);
             return { device: deviceInfo, appTerminated: true };
         }
         catch (e) {
-            const diag = execAdbWithDiagnostics(['shell', 'am', 'force-stop', appId], deviceId);
-            return { device: deviceInfo, appTerminated: false, error: e instanceof Error ? e.message : String(e), diagnostics: diag };
+            const diagnostics = hasFiniteBudget() ? undefined : execAdbWithDiagnostics(['shell', 'am', 'force-stop', appId], deviceId);
+            return { device: deviceInfo, appTerminated: false, error: e instanceof Error ? e.message : String(e), ...(diagnostics ? { diagnostics } : {}) };
         }
     }
-    async restartApp(appId, deviceId) {
-        const terminateResult = await this.terminateApp(appId, deviceId);
-        const startResult = await this.startApp(appId, deviceId);
+    async restartApp(appId, deviceId, bounded = false, timeoutMs = 15000) {
+        const started = performance.now();
+        const terminateResult = bounded ? await runWithBudget(Math.min(5000, timeoutMs), () => this.terminateApp(appId, deviceId)) : await this.terminateApp(appId, deviceId);
+        const remaining = timeoutMs - (performance.now() - started);
+        if (bounded && remaining <= 0)
+            throw new Error('ACTION_TIMEOUT');
+        const launchBudget = remainingBudget(remaining);
+        const startResult = bounded ? await runWithBudget(launchBudget, () => this.startApp(appId, deviceId, remainingBudget(launchBudget))) : await this.startApp(appId, deviceId);
         return {
             device: startResult.device,
             appRestarted: startResult.appStarted,
@@ -201,6 +210,7 @@ export class AndroidManage {
         const metadata = await getAndroidDeviceMetadata(appId, deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
         try {
+            markDispatchStarted();
             const output = await execAdb(['shell', 'pm', 'clear', appId], deviceId);
             return { device: deviceInfo, dataCleared: output === 'Success' };
         }

package/dist/manage/ios.js

@@ -1,3 +1,4 @@
+import { hasFiniteBudget, markDispatchStarted, remainingBudget, runWithBudget } from '../utils/operation-budget.js';
 import { promises as fs } from "fs";
 import { spawn, spawnSync } from "child_process";
 import { execCommand, execCommandWithDiagnostics, getIOSDeviceMetadata, validateBundleId, getIdbCmd, findAppBundle } from "../utils/ios/utils.js";
@@ -257,7 +258,7 @@ export class iOSManage {
                 // Gather diagnostics for simctl failure
                 const diag = execCommandWithDiagnostics(['simctl', 'install', deviceId, toInstall], deviceId);
                 try {
-                    const child = spawn(getIdbCmd(), ['--version']);
+                    const child = spawn(getIdbCmd(), ['list-targets', '--json']);
                     const idbExists = await new Promise((resolve) => {
                         child.on('error', () => resolve(false));
                         child.on('close', (code) => resolve(code === 0));
@@ -287,17 +288,19 @@ export class iOSManage {
             return { device, installed: false, error: e instanceof Error ? e.message : String(e) };
         }
     }
-    async startApp(bundleId, deviceId = "booted") {
+    async startApp(bundleId, deviceId = "booted", observe = true) {
+        const started = performance.now();
         validateBundleId(bundleId);
         try {
+            markDispatchStarted();
             const result = await execCommand(['simctl', 'launch', deviceId, bundleId], deviceId);
             const device = await getIOSDeviceMetadata(deviceId);
-            const fingerprint = await new iOSObserve().getScreenFingerprint(deviceId).catch(() => null);
+            const fingerprint = observe ? await new iOSObserve().getScreenFingerprint(deviceId).catch(() => null) : null;
             const pidMatch = result.output.match(/:\s*(\d+)\s*$/);
             return {
                 device,
                 appStarted: !!result.output,
-                launchTimeMs: 1000,
+                launchTimeMs: performance.now() - started,
                 output: result.output,
                 observedApp: {
                     appId: bundleId,
@@ -308,27 +311,33 @@ export class iOSManage {
             };
         }
         catch (e) {
-            const diag = execCommandWithDiagnostics(['simctl', 'launch', deviceId, bundleId], deviceId);
             const device = await getIOSDeviceMetadata(deviceId);
-            return { device, appStarted: false, launchTimeMs: 0, error: e instanceof Error ? e.message : String(e), diagnostics: diag };
+            const diagnostics = hasFiniteBudget() ? undefined : execCommandWithDiagnostics(['simctl', 'launch', deviceId, bundleId], deviceId);
+            return { device, appStarted: false, launchTimeMs: performance.now() - started, error: e instanceof Error ? e.message : String(e), ...(diagnostics ? { diagnostics } : {}) };
         }
     }
     async terminateApp(bundleId, deviceId = "booted") {
         validateBundleId(bundleId);
         try {
+            markDispatchStarted();
             await execCommand(['simctl', 'terminate', deviceId, bundleId], deviceId);
             const device = await getIOSDeviceMetadata(deviceId);
             return { device, appTerminated: true };
         }
         catch (e) {
-            const diag = execCommandWithDiagnostics(['simctl', 'terminate', deviceId, bundleId], deviceId);
+            const diag = hasFiniteBudget() ? undefined : execCommandWithDiagnostics(['simctl', 'terminate', deviceId, bundleId], deviceId);
             const device = await getIOSDeviceMetadata(deviceId);
-            return { device, appTerminated: false, error: e instanceof Error ? e.message : String(e), diagnostics: diag };
+            return { device, appTerminated: false, error: e instanceof Error ? e.message : String(e), ...(diag ? { diagnostics: diag } : {}) };
         }
     }
-    async restartApp(bundleId, deviceId = "booted") {
-        const terminateResult = await this.terminateApp(bundleId, deviceId);
-        const startResult = await this.startApp(bundleId, deviceId);
+    async restartApp(bundleId, deviceId = "booted", observe = true, bounded = false, timeoutMs = 15000) {
+        const started = performance.now();
+        const terminateResult = bounded ? await runWithBudget(Math.min(5000, timeoutMs), () => this.terminateApp(bundleId, deviceId)) : await this.terminateApp(bundleId, deviceId);
+        const remaining = timeoutMs - (performance.now() - started);
+        if (bounded && remaining <= 0)
+            throw new Error('ACTION_TIMEOUT');
+        const launchBudget = remainingBudget(remaining);
+        const startResult = bounded ? await runWithBudget(launchBudget, () => this.startApp(bundleId, deviceId, observe)) : await this.startApp(bundleId, deviceId, observe);
         return {
             device: startResult.device,
             appRestarted: startResult.appStarted,

package/dist/observe/android.js

@@ -7,6 +7,7 @@ import path from "path";
 import { computeScreenFingerprint } from "../utils/ui/index.js";
 import { parsePngSize } from "../utils/image.js";
 import { deriveSnapshotMetadata } from "./snapshot-metadata.js";
+import { remainingBudget } from '../utils/operation-budget.js';
 const activeLogStreams = new Map();
 export class AndroidObserve {
     async getDeviceMetadata(appId, deviceId) {
@@ -26,10 +27,12 @@ export class AndroidObserve {
             let attempts = 0;
             const maxAttempts = 3;
             while (attempts < maxAttempts) {
+                remainingBudget();
                 attempts++;
                 try {
                     // Stabilization delay
-                    await delay(300 + (attempts * 100)); // 300ms, 400ms, 500ms...
+                    await delay(Math.min(remainingBudget(300 + (attempts * 100)), 300 + (attempts * 100))); // 300ms, 400ms, 500ms...
+                    remainingBudget();
                     // Dump UI hierarchy
                     await execAdb(['shell', 'uiautomator', 'dump', '/sdcard/ui.xml'], deviceId);
                     // Read the file
@@ -40,6 +43,8 @@ export class AndroidObserve {
                     }
                 }
                 catch (e) {
+                    if (e instanceof Error && e.message === 'ACTION_TIMEOUT')
+                        throw e;
                     console.error(`Attempt ${attempts} failed: ${e}`);
                 }
                 if (attempts === maxAttempts) {

package/dist/observe/index.js

@@ -1,7 +1,8 @@
+import { measure } from '../utils/timing.js';
 import { resolveTargetDevice } from '../utils/resolve-device.js';
 import { AndroidObserve } from './android.js';
 import { iOSObserve } from './ios.js';
-import { deriveSnapshotMetadata } from './snapshot-metadata.js';
+import { deriveSnapshotMetadata, getLatestStateDelta, getStateDelta } from './snapshot-metadata.js';
 export { AndroidObserve } from './android.js';
 export { iOSObserve } from './ios.js';
 function normalizeHint(value) {
@@ -110,6 +111,9 @@ function deriveSnapshotSemantic(raw) {
     };
 }
 export class ToolsObserve {
+    static getLatestStateDelta(platform, deviceId) {
+        return getLatestStateDelta(`${platform}:${deviceId}`);
+    }
     // Resolve a target device and return the appropriate observe instance and resolved info.
     static async resolveObserve(platform, deviceId, appId) {
         if (platform === 'android') {
@@ -130,9 +134,22 @@ export class ToolsObserve {
             return { observe: new iOSObserve(), resolved };
         }
     }
-    static async getUITreeHandler({ platform, deviceId }) {
+    static async getUITreeHandler({ platform, deviceId, responseMode = 'debug', sinceSnapshotRevision }) {
         const { observe, resolved } = await ToolsObserve.resolveObserve(platform, deviceId);
-        return await observe.getUITree(resolved.id);
+        const tree = await observe.getUITree(resolved.id);
+        if (responseMode !== 'compact')
+            return tree;
+        const revision = tree?.snapshot_revision ?? null;
+        const baseRevision = sinceSnapshotRevision;
+        if (!Number.isInteger(baseRevision) || revision === null) {
+            return { delta_available: false, snapshot_revision: revision };
+        }
+        const delta = getStateDelta(`${resolved.platform}:${resolved.id}`, baseRevision, revision);
+        return delta ? { delta_available: true, state_delta: delta, snapshot_revision: revision } : {
+            delta_available: false,
+            snapshot_revision: revision,
+            reason: 'BASE_REVISION_UNAVAILABLE'
+        };
     }
     static async getCurrentScreenHandler({ deviceId }) {
         const { observe, resolved } = await ToolsObserve.resolveObserve('android', deviceId);
@@ -199,7 +216,7 @@ export class ToolsObserve {
         // Both observes implement getScreenFingerprint
         return await observe.getScreenFingerprint(resolved.id);
     }
-    static async captureDebugSnapshotHandler({ reason, includeLogs = true, logLines = 200, platform, appId, deviceId, sessionId } = {}) {
+    static async captureDebugSnapshotHandler({ reason, includeLogs = true, includeScreenshot = true, logLines = 200, platform, appId, deviceId, sessionId } = {}) {
         const timestamp = Date.now();
         const raw = {
             timestamp,
@@ -215,7 +232,7 @@ export class ToolsObserve {
         // Parallel fetches for performance: screenshot, current screen, fingerprint, ui tree, and log stream/get logs
         const sid = sessionId || 'default';
         const tasks = {
-            screenshot: ToolsObserve.captureScreenshotHandler({ platform, deviceId }),
+            screenshot: includeScreenshot ? measure('screenshot_ms', () => ToolsObserve.captureScreenshotHandler({ platform, deviceId })) : Promise.resolve(null),
             currentScreen: (!platform || platform === 'android') ? ToolsObserve.getCurrentScreenHandler({ deviceId }) : Promise.resolve(null),
             fingerprint: ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }),
             uiTree: ToolsObserve.getUITreeHandler({ platform, deviceId }),

package/dist/observe/ios.js

@@ -1,4 +1,5 @@
 import { spawn } from "child_process";
+import { remainingBudget } from '../utils/operation-budget.js';
 import { promises as fs } from "fs";
 import { execCommand, getIOSDeviceMetadata, validateBundleId, getIdbCmd, getXcrunCmd, isIDBInstalled } from "../utils/ios/utils.js";
 import { createWriteStream, promises as fsPromises } from 'fs';
@@ -501,15 +502,17 @@ export class iOSObserve {
         let attempts = 0;
         const maxAttempts = 3;
         while (attempts < maxAttempts) {
+            remainingBudget();
             attempts++;
             try {
-                await delay(300 + (attempts * 100));
+                await delay(Math.min(remainingBudget(300 + (attempts * 100)), 300 + (attempts * 100)));
+                remainingBudget();
                 const args = ['ui', 'describe-all', '--json'];
                 if (targetUdid) {
                     args.push('--udid', targetUdid);
                 }
                 const output = await new Promise((resolve, reject) => {
-                    const child = spawn(getIdbCmd(), args);
+                    const child = spawn(getIdbCmd(), args, { timeout: remainingBudget() || undefined });
                     let stdout = '';
                     let stderr = '';
                     child.stdout.on('data', (data) => stdout += data.toString());
@@ -530,6 +533,8 @@ export class iOSObserve {
                 }
             }
             catch (e) {
+                if (e instanceof Error && e.message === 'ACTION_TIMEOUT')
+                    throw e;
                 console.error(`Attempt ${attempts} failed: ${e}`);
             }
             if (attempts === maxAttempts) {