mobile-debug-mcp 0.30.2 → 0.32.0

package/src/interact/index.ts

@@ -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';
@@ -1226,22 +1227,22 @@ export class ToolsInteract {
     return { interact: interact as any, resolved, platform: effectivePlatform }
   }
 
-  static async tapHandler({ platform, x, y, deviceId }: { platform?: 'android' | 'ios', x: number, y: number, deviceId?: string }) {
+  static async tapHandler({ platform, x, y, deviceId, timeoutMs }: { platform?: 'android' | 'ios', x: number, y: number, deviceId?: string, timeoutMs?: number }) {
     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 }: { elementId: string }): Promise<TapElementResponse> {
+  static async tapElementHandler({ elementId, verificationMode = 'full', timeoutMs, platform, deviceId, freshTree }: { elementId: string, verificationMode?: 'none' | 'light' | 'full', timeoutMs?: number, platform?: 'android' | 'ios', deviceId?: string, freshTree?: any }): Promise<TapElementResponse> {
     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 fingerprintBefore = verificationMode === 'full' ? await ToolsInteract._captureFingerprint(resolved.platform, resolved.deviceId) : null
 
-    const tree = await ToolsObserve.getUITreeHandler({ platform: resolved.platform, deviceId: resolved.deviceId }) as any
+    const tree = freshTree ?? await ToolsObserve.getUITreeHandler({ platform: resolved.platform, deviceId: resolved.deviceId }) as any
     const treePlatform = tree?.device?.platform === 'ios' ? 'ios' : resolved.platform
     const treeDeviceId = tree?.device?.id || resolved.deviceId
     const elements = Array.isArray(tree?.elements) ? tree.elements as UiElement[] : []
@@ -1272,14 +1273,14 @@ 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,
@@ -2204,19 +2205,19 @@ export class ToolsInteract {
     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 }: { platform?: 'android' | 'ios', x1: number, y1: number, x2: number, y2: number, duration: number, deviceId?: string }) {
+  static async swipeHandler({ platform = 'android', x1, y1, x2, y2, duration, deviceId, timeoutMs }: { platform?: 'android' | 'ios', x1: number, y1: number, x2: number, y2: number, duration: number, deviceId?: string, timeoutMs?: number }) {
     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 }: { text: string, deviceId?: string }) {
+  static async typeTextHandler({ text, deviceId, timeoutMs }: { text: string, deviceId?: string, timeoutMs?: number }) {
     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 }: { deviceId?: string }) {
+  static async pressBackHandler({ deviceId, timeoutMs }: { deviceId?: string, timeoutMs?: number }) {
     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 }: { platform: 'android' | 'ios', selector: { text?: string, resourceId?: string, contentDesc?: string, className?: string }, direction?: 'down' | 'up', maxScrolls?: number, scrollAmount?: number, deviceId?: string }) {
@@ -2490,7 +2491,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 }: { selector?: { text?: string, resource_id?: string, accessibility_id?: string, contains?: boolean }, condition?: 'exists'|'not_exists'|'visible'|'clickable', timeout_ms?: number, poll_interval_ms?: number, match?: { index?: number }, retry?: { max_attempts?: number, backoff_ms?: number }, platform?: 'android'|'ios', deviceId?: string }) {
+  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 }: { selector?: { text?: string, resource_id?: string, accessibility_id?: string, contains?: boolean }, condition?: 'exists'|'not_exists'|'visible'|'clickable', timeout_ms?: number, poll_interval_ms?: number, match?: { index?: number }, retry?: { max_attempts?: number, backoff_ms?: number }, platform?: 'android'|'ios', deviceId?: string, singleObservation?: boolean, singleAttempt?: boolean, rejectAmbiguous?: boolean }) {
     const overallStart = Date.now()
     const requestedIndex = typeof match?.index === 'number' ? match.index : null
     const requested = {
@@ -2538,7 +2539,7 @@ export class ToolsInteract {
     let lastConditionSatisfied = false
     let matchedAt: number | null = null
     let stableMatchCount = 0
-    const stableObservationCount = 2
+    const stableObservationCount = singleObservation ? 1 : 2
     const snapshotStaleThresholdMs = 500
 
     // Precompute normalized selector values and helpers (constant across polls)
@@ -2554,7 +2555,8 @@ export class ToolsInteract {
         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 }) as any
@@ -2601,6 +2603,7 @@ 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 as number : undefined
             let chosen: { el: any, idx: number } | null = null
             if (matches.length > 0) {
@@ -2659,6 +2662,7 @@ export class ToolsInteract {
 
                 return {
                   status: 'success',
+                  ...(singleObservation ? { _tree: tree } : {}),
                   matched: matchedCount,
                   element: outEl,
                   metrics: { latency_ms, poll_count: totalPollCount, attempts },
@@ -2677,10 +2681,12 @@ 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))
         }
@@ -2712,6 +2718,7 @@ export class ToolsInteract {
       }
 
     } catch (err) {
+      if (err instanceof Error && err.message === 'ACTION_TIMEOUT') throw err
       const elapsed = Date.now() - overallStart
       return {
         status: 'timeout',
@@ -3139,7 +3146,8 @@ export class ToolsInteract {
     stabilization_window_ms = 1000,
     stable_observation_count = 2,
     snapshot_stale_threshold_ms = 500,
-    poll_interval_ms = 150
+    poll_interval_ms = 150,
+    exact_budget = false
   }: {
     selector?: { text?: string, resource_id?: string, accessibility_id?: string, contains?: boolean },
     element_id?: string,
@@ -3150,16 +3158,17 @@ export class ToolsInteract {
     stabilization_window_ms?: number,
     stable_observation_count?: number,
     snapshot_stale_threshold_ms?: number,
-    poll_interval_ms?: number
+    poll_interval_ms?: number,
+    exact_budget?: boolean
   }): Promise<ExpectStateResponse> {
     const compareBoolean = (value: unknown) => typeof value === 'boolean' ? value : null
     const compareString = (value: unknown) => typeof value === 'string' ? value : null
     const compareNumber = (value: unknown) => typeof value === 'number' && Number.isFinite(value) ? value : null
     const sleep = (ms: number) => 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

package/src/interact/ios.ts

@@ -1,3 +1,4 @@
+import { remainingBudget, markDispatchStarted } from '../utils/operation-budget.js'
 import { spawn } from "child_process"
 import { TapResponse, SwipeResponse } from "../types.js"
 import { getIOSDeviceMetadata, getIdbCmd, isIDBInstalled } from "../utils/ios/utils.js"
@@ -31,7 +32,8 @@ export class iOSInteract {
       }
 
       await new Promise<void>((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 => {
@@ -72,7 +74,8 @@ export class iOSInteract {
       }
 
       await new Promise<void>((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/src/manage/android.ts

@@ -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'
@@ -149,16 +150,18 @@ export class AndroidManage {
     }
   }
 
-  async startApp(appId: string, deviceId?: string): Promise<StartAppResponse> {
+  async startApp(appId: string, deviceId?: string, timeoutMs?: number): Promise<StartAppResponse> {
+    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,
@@ -169,8 +172,8 @@ export class AndroidManage {
         }
       }
     } catch (e: unknown) {
-      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 } : {}) }
     }
   }
 
@@ -178,17 +181,22 @@ export class AndroidManage {
     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: unknown) {
-      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: string, deviceId?: string): Promise<RestartAppResponse> {
-    const terminateResult = await this.terminateApp(appId, deviceId)
-    const startResult = await this.startApp(appId, deviceId)
+  async restartApp(appId: string, deviceId?: string, bounded = false, timeoutMs = 15000): Promise<RestartAppResponse> {
+    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,
@@ -206,6 +214,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' }
     } catch (e: unknown) {

package/src/manage/ios.ts

@@ -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 { StartAppResponse, TerminateAppResponse, RestartAppResponse, ResetAppDataResponse, InstallAppResponse } from "../types.js"
@@ -283,7 +284,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<boolean>((resolve) => {
               child.on('error', () => resolve(false));
               child.on('close', (code) => resolve(code === 0));
@@ -310,17 +311,19 @@ export class iOSManage {
     }
   }
 
-  async startApp(bundleId: string, deviceId: string = "booted"): Promise<StartAppResponse> {
+  async startApp(bundleId: string, deviceId: string = "booted", observe = true): Promise<StartAppResponse> {
+    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,
@@ -330,28 +333,33 @@ export class iOSManage {
         }
       }
     } catch (e: unknown) {
-      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 } as any
+      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 } : {}) } as any
     }
   }
 
   async terminateApp(bundleId: string, deviceId: string = "booted"): Promise<TerminateAppResponse> {
     validateBundleId(bundleId)
     try {
+      markDispatchStarted()
       await execCommand(['simctl', 'terminate', deviceId, bundleId], deviceId)
       const device = await getIOSDeviceMetadata(deviceId)
       return { device, appTerminated: true }
     } catch (e: unknown) {
-      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 } as any
+      return { device, appTerminated: false, error: e instanceof Error ? e.message : String(e), ...(diag ? { diagnostics: diag } : {}) } as any
     }
   }
 
-  async restartApp(bundleId: string, deviceId: string = "booted"): Promise<RestartAppResponse> {
-    const terminateResult = await this.terminateApp(bundleId, deviceId)
-    const startResult = await this.startApp(bundleId, deviceId)
+  async restartApp(bundleId: string, deviceId: string = "booted", observe = true, bounded = false, timeoutMs = 15000): Promise<RestartAppResponse> {
+    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/src/observe/android.ts

@@ -8,6 +8,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: Map<string, { proc: any, file: string }> = new Map()
 
@@ -33,10 +34,12 @@ export class AndroidObserve {
       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);
@@ -49,6 +52,7 @@ export class AndroidObserve {
               break; // Success
            }
         } catch (e) {
+           if (e instanceof Error && e.message === 'ACTION_TIMEOUT') throw e
            console.error(`Attempt ${attempts} failed: ${e}`);
         }
         

package/src/observe/index.ts

@@ -1,3 +1,4 @@
+import { measure } from '../utils/timing.js'
 import { resolveTargetDevice } from '../utils/resolve-device.js'
 import { AndroidObserve } from './android.js'
 import { iOSObserve } from './ios.js'
@@ -5,7 +6,7 @@ import type {
   CaptureDebugSnapshotRawResponse,
   SnapshotSemanticResponse
 } from '../types.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'
@@ -149,6 +150,9 @@ function deriveSnapshotSemantic(raw: CaptureDebugSnapshotRawResponse): SnapshotS
 }
 
 export class ToolsObserve {
+  static getLatestStateDelta(platform: 'android' | 'ios', deviceId: string) {
+    return getLatestStateDelta(`${platform}:${deviceId}`)
+  }
   // Resolve a target device and return the appropriate observe instance and resolved info.
   private static async resolveObserve(platform?: 'android' | 'ios', deviceId?: string, appId?: string) {
     if (platform === 'android') {
@@ -170,9 +174,21 @@ export class ToolsObserve {
     }
   }
 
-  static async getUITreeHandler({ platform, deviceId }: { platform?: 'android' | 'ios', deviceId?: string }) {
+  static async getUITreeHandler({ platform, deviceId, responseMode = 'debug', sinceSnapshotRevision }: { platform?: 'android' | 'ios', deviceId?: string, responseMode?: 'compact' | 'debug', sinceSnapshotRevision?: number }) {
     const { observe, resolved } = await ToolsObserve.resolveObserve(platform, deviceId)
-    return await observe.getUITree(resolved.id)
+    const tree = await observe.getUITree(resolved.id) as any
+    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 as number, 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 }: { deviceId?: string }) {
@@ -244,7 +260,7 @@ export class ToolsObserve {
     return await (observe as any).getScreenFingerprint(resolved.id)
   }
 
-  static async captureDebugSnapshotHandler({ reason, includeLogs = true, logLines = 200, platform, appId, deviceId, sessionId }: { reason?: string; includeLogs?: boolean; logLines?: number; platform?: 'android' | 'ios'; appId?: string; deviceId?: string; sessionId?: string } = {}) {
+  static async captureDebugSnapshotHandler({ reason, includeLogs = true, includeScreenshot = true, logLines = 200, platform, appId, deviceId, sessionId }: { reason?: string; includeLogs?: boolean; includeScreenshot?: boolean; logLines?: number; platform?: 'android' | 'ios'; appId?: string; deviceId?: string; sessionId?: string } = {}) {
     const timestamp = Date.now()
     const raw: CaptureDebugSnapshotRawResponse = {
       timestamp,
@@ -261,7 +277,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: Record<string, Promise<any>> = {
-      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/src/observe/ios.ts

@@ -1,4 +1,5 @@
 import { spawn } from "child_process"
+import { remainingBudget } from '../utils/operation-budget.js'
 import { promises as fs } from "fs"
 import { GetLogsResponse, CaptureIOSScreenshotResponse, GetUITreeResponse, UIElement, DeviceInfo, UIElementSemanticMetadata, UIElementState, UIResolutionSelector, SelectorConfidence } from "../types.js"
 import { execCommand, getIOSDeviceMetadata, validateBundleId, getIdbCmd, getXcrunCmd, isIDBInstalled } from "../utils/ios/utils.js"
@@ -547,9 +548,11 @@ export class iOSObserve {
     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) {
@@ -557,7 +560,7 @@ export class iOSObserve {
          }
 
          const output = await new Promise<string>((resolve, reject) => {
-             const child = spawn(getIdbCmd(), args);
+             const child = spawn(getIdbCmd(), args, { timeout: remainingBudget() || undefined });
              let stdout = '';
              let stderr = '';
 
@@ -580,6 +583,7 @@ export class iOSObserve {
              break; // Success
          }
       } catch (e) {
+         if (e instanceof Error && e.message === 'ACTION_TIMEOUT') throw e
          console.error(`Attempt ${attempts} failed: ${e}`);
       }
       

package/src/observe/snapshot-metadata.ts

@@ -5,8 +5,15 @@ interface SnapshotState {
   revision: number
   signature: string | null
   elementSignatures: Map<string, string>
+  elements: Map<string, UIElement>
+  history: Map<number, Map<string, UIElement>>
+  historyTimes: Map<number, number>
+  oversized: Map<number, number>
+  previousRevision: number | null
+  updatedAt: number
 }
 
+let nextRevision = 1
 const snapshotStateByDevice = new Map<string, SnapshotState>()
 
 function normalize(value: unknown): string {
@@ -53,18 +60,20 @@ function stableElementIdentity(element: UIElement, index: number) {
   })).digest('hex')}`
 }
 
-function buildElementSignatures(tree: Pick<GetUITreeResponse, 'elements'> | null | undefined) {
+function buildElementRecords(tree: Pick<GetUITreeResponse, 'elements'> | null | undefined) {
   const signatures = new Map<string, string>()
+  const elementsByIdentity = new Map<string, UIElement>()
   const elements = Array.isArray(tree?.elements) ? tree!.elements! : []
 
-  for (let index = 0; index < elements.length; index++) {
+  for (let index = 0; index < Math.min(elements.length, 500); index++) {
     const element = elements[index]
     if (!element) continue
     const identity = stableElementIdentity(element, index)
     signatures.set(identity, crypto.createHash('sha1').update(JSON.stringify(stableElementSignature(element))).digest('hex'))
+    elementsByIdentity.set(identity, structuredClone(element))
   }
 
-  return signatures
+  return { signatures, elementsByIdentity }
 }
 
 function summarizeSnapshotDelta(previous: SnapshotState | undefined, currentElements: Map<string, string>): SnapshotDelta | null {
@@ -140,25 +149,45 @@ export function deriveSnapshotMetadata(
   signatureOverride?: string | null
 ) {
   const signature = signatureOverride ?? computeSnapshotSignature(tree)
-  const previous = snapshotStateByDevice.get(deviceKey)
+  const existing = snapshotStateByDevice.get(deviceKey)
+  const previous = existing && Date.now() - existing.updatedAt <= 10 * 60 * 1000 ? existing : undefined
+  if (!previous && existing) snapshotStateByDevice.delete(deviceKey)
   const hasValidTree = !!tree && !tree.error
-  const currentElementSignatures = hasValidTree
-    ? buildElementSignatures(tree)
-    : previous?.elementSignatures ?? new Map<string, string>()
-
-  let revision = 1
-  if (previous) {
-    if (signature === null) {
-      revision = previous.revision
-    } else {
-      revision = previous.signature === signature ? previous.revision : previous.revision + 1
+  const records = hasValidTree ? buildElementRecords(tree) : null
+  const currentElementSignatures = records?.signatures ?? previous?.elementSignatures ?? new Map<string, string>()
+  const currentElements = records?.elementsByIdentity ?? previous?.elements ?? new Map<string, UIElement>()
+
+  const revision = previous && (signature === null || previous.signature === signature) ? previous.revision : nextRevision++
+  const history = previous?.history ?? new Map<number, Map<string, UIElement>>()
+  const historyTimes = previous?.historyTimes ?? new Map<number, number>()
+  const oversized = previous?.oversized ?? new Map<number, number>()
+  if (hasValidTree) {
+    history.set(revision, currentElements)
+    if (!historyTimes.has(revision)) historyTimes.set(revision, Date.now())
+    if ((tree.elements?.length ?? 0) > 500) oversized.set(revision, (tree.elements?.length ?? 0) - 500)
+  }
+  for (const [id, timestamp] of historyTimes) {
+    if (Date.now() - timestamp > 10 * 60 * 1000) {
+      history.delete(id)
+      historyTimes.delete(id)
+      oversized.delete(id)
     }
   }
+  while (history.size > 8) {
+    const oldest = history.keys().next().value
+    if (oldest === undefined) break
+    history.delete(oldest)
+    historyTimes.delete(oldest)
+    oversized.delete(oldest)
+  }
 
   snapshotStateByDevice.set(deviceKey, {
     revision,
     signature,
-    elementSignatures: currentElementSignatures
+    elementSignatures: currentElementSignatures,
+    elements: currentElements,
+    history, historyTimes, oversized, previousRevision: previous?.revision ?? null,
+    updatedAt: Date.now()
   })
 
   return {
@@ -169,6 +198,56 @@ export function deriveSnapshotMetadata(
   }
 }
 
+export function getStateDelta(deviceKey: string, baseRevision: number, currentRevision: number) {
+  const state = snapshotStateByDevice.get(deviceKey)
+  if (!state || Date.now() - (state.historyTimes.get(baseRevision) ?? 0) > 10 * 60 * 1000 || Date.now() - state.updatedAt > 10 * 60 * 1000) return null
+  const base = state.history.get(baseRevision)
+  const current = state?.history.get(currentRevision)
+  if (!base || !current) return null
+
+  const added: UIElement[] = []
+  const changed: UIElement[] = []
+  const removed: Array<{ stable_id?: string, resourceId?: string, contentDescription?: string, text?: string, index: number }> = []
+  for (const [identity, element] of current) {
+    const before = base.get(identity)
+    if (!before) added.push(element)
+    else if (JSON.stringify(stableElementSignature(before)) !== JSON.stringify(stableElementSignature(element))) changed.push(element)
+  }
+  let index = 0
+  for (const [identity, element] of base) {
+    if (!current.has(identity)) removed.push({ stable_id: element.stable_id ?? undefined, resourceId: element.resourceId ?? undefined, contentDescription: element.contentDescription ?? undefined, text: element.text ?? undefined, index })
+    index++
+  }
+  const all = added.length + changed.length + removed.length
+  const limit = 200
+  return {
+    base_snapshot_revision: baseRevision,
+    snapshot_revision: currentRevision,
+    added: added.slice(0, limit),
+    changed: changed.slice(0, Math.max(0, limit - added.length)),
+    removed: removed.slice(0, Math.max(0, limit - added.length - changed.length)),
+    truncated: all > limit || state.oversized.has(baseRevision) || state.oversized.has(currentRevision),
+    ...((all > limit || state.oversized.has(baseRevision) || state.oversized.has(currentRevision))
+      ? { omitted_changes: Math.max(all - limit, state.oversized.get(baseRevision) ?? 0, state.oversized.get(currentRevision) ?? 0) } : {})
+  }
+}
+
+export function getLatestStateDelta(deviceKey: string) {
+  const state = snapshotStateByDevice.get(deviceKey)
+  if (!state || state.previousRevision === null) return null
+  return getStateDelta(deviceKey, state.previousRevision, state.revision)
+}
+
+export function retainConnectedDeviceSnapshots(platform: string, deviceIds: string[]) {
+  const keys = new Set(deviceIds.map(id => `${platform}:${id}`))
+  for (const key of snapshotStateByDevice.keys()) if (key.startsWith(`${platform}:`) && !keys.has(key)) snapshotStateByDevice.delete(key)
+}
+
+export function clearDeviceSnapshots(deviceKey: string) {
+  snapshotStateByDevice.delete(deviceKey)
+}
+
 export function resetSnapshotMetadataForTests() {
   snapshotStateByDevice.clear()
+  nextRevision = 1
 }