mobile-debug-mcp 0.31.0 → 0.32.1

package/src/observe/android.ts

@@ -8,6 +8,9 @@ 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'
+import { createObservationMeasurement } from './performance-metrics.js'
+import { androidTreeBridgeEnabled, readAndroidTreeFromBridge } from './android-tree-bridge.js'
 
 const activeLogStreams: Map<string, { proc: any, file: string }> = new Map()
 
@@ -17,12 +20,20 @@ export class AndroidObserve {
   }
 
   async getUITree(deviceId?: string): Promise<GetUITreeResponse> {
-    const metadata = await getAndroidDeviceMetadata("", deviceId)
+    const measurement = createObservationMeasurement('android')
+    let metadata
+    try {
+      metadata = await measurement.timed('metadata_ms', () => getAndroidDeviceMetadata("", deviceId))
+    } catch (error) {
+      measurement.setOutcome('unavailable')
+      measurement.finish()
+      throw error
+    }
     const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
 
     try {
       // Get screen resolution first
-      const resolution = await getScreenResolution(deviceId);
+      const resolution = await measurement.timed('resolution_ms', () => getScreenResolution(deviceId));
       if (resolution.width === 0 && resolution.height === 0) {
           throw new Error("Failed to get screen resolution. Is the device connected and authorized?");
       }
@@ -33,22 +44,37 @@ export class AndroidObserve {
       const maxAttempts = 3;
 
       while (attempts < maxAttempts) {
+        remainingBudget()
         attempts++;
         try {
-           // Stabilization delay
-           await delay(300 + (attempts * 100)); // 300ms, 400ms, 500ms...
-
-           // Dump UI hierarchy
-           await execAdb(['shell', 'uiautomator', 'dump', '/sdcard/ui.xml'], deviceId);
-           
-           // Read the file
-           xmlContent = await execAdb(['shell', 'cat', '/sdcard/ui.xml'], deviceId);
-           
-           // Check validity
-           if (xmlContent && xmlContent.trim().length > 0 && !xmlContent.includes("ERROR:")) {
-              break; // Success
+           // The first read starts immediately so it remains fresh for in-place UI changes.
+           // Delay only a retry after a failed or invalid acquisition.
+           if (attempts > 1) {
+             await measurement.timed('observation_wait_ms', () => delay(Math.min(remainingBudget(300 + (attempts * 100)), 300 + (attempts * 100))));
+           }
+           remainingBudget()
+
+           let bridgeContent: string | null = null
+           if (androidTreeBridgeEnabled()) {
+             try {
+               bridgeContent = await measurement.physicalRead(async () => {
+                 const content = await readAndroidTreeFromBridge(deviceInfo.id)
+                 if (!content) throw new Error('Android UI tree bridge unavailable')
+                 return content
+               })
+             } catch (error) {
+               if (error instanceof Error && (error.message === 'ACTION_TIMEOUT' || error.message.startsWith('BRIDGE_CLEANUP_UNCONFIRMED'))) throw error
+             }
            }
+           xmlContent = bridgeContent ?? await measurement.physicalRead(async () => {
+             await execAdb(['shell', 'uiautomator', 'dump', '/sdcard/ui.xml'], deviceId)
+             const content = await execAdb(['shell', 'cat', '/sdcard/ui.xml'], deviceId)
+             if (!content || !content.trim() || content.includes('ERROR:')) throw new Error('Empty or invalid UI dump')
+             return content
+           })
+           break
         } catch (e) {
+           if (e instanceof Error && (e.message === 'ACTION_TIMEOUT' || e.message.startsWith('BRIDGE_CLEANUP_UNCONFIRMED'))) throw e
            console.error(`Attempt ${attempts} failed: ${e}`);
         }
         
@@ -61,7 +87,7 @@ export class AndroidObserve {
         ignoreAttributes: false,
         attributeNamePrefix: "@_"
       });
-      const result = parser.parse(xmlContent);
+      const result = await measurement.timed('parse_ms', async () => parser.parse(xmlContent));
       
       const elements: UIElement[] = [];
       
@@ -81,17 +107,22 @@ export class AndroidObserve {
         elements
       }, 'ui_tree')
 
-      return {
+      measurement.setOutcome('observed')
+      const response = measurement.bindObservation({
         device: deviceInfo,
         screen: "",
         resolution,
         elements,
         ...snapshotMetadata
-      };
+      })
+      measurement.finish()
+      return response
     } 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')
+      measurement.setOutcome('unavailable')
+      measurement.finish()
       return {
           device: deviceInfo,
           screen: "",

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,7 @@
 import { spawn } from "child_process"
+import { remainingBudget } from '../utils/operation-budget.js'
+import { execCmd } from '../utils/exec.js'
+import { createObservationMeasurement } from './performance-metrics.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"
@@ -524,12 +527,22 @@ export class iOSObserve {
   }
 
   async getUITree(deviceId: string = "booted"): Promise<GetUITreeResponse> {
-    const device = await getIOSDeviceMetadata(deviceId);
+    const measurement = createObservationMeasurement('ios')
+    let device
+    try {
+      device = await measurement.timed('metadata_ms', () => getIOSDeviceMetadata(deviceId))
+    } catch (error) {
+      measurement.setOutcome('unavailable')
+      measurement.finish()
+      throw error
+    }
     const deviceKey = `ios:${device.id}`
     
-    const idbExists = await isIDBInstalled();
+    const idbExists = await measurement.timed('capability_check_ms', () => isIDBInstalled());
     if (!idbExists) {
        const snapshotMetadata = deriveSnapshotMetadata(deviceKey, null, 'ui_tree')
+       measurement.setOutcome('unavailable')
+       measurement.finish()
        return {
           device,
           screen: "",
@@ -547,44 +560,38 @@ export class iOSObserve {
     const maxAttempts = 3;
 
     while (attempts < maxAttempts) {
+      remainingBudget()
       attempts++;
       try {
-         await delay(300 + (attempts * 100));
+         await measurement.timed('observation_wait_ms', () => 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<string>((resolve, reject) => {
-             const child = spawn(getIdbCmd(), args);
-             let stdout = '';
-             let stderr = '';
-
-             child.stdout.on('data', (data) => stdout += data.toString());
-             child.stderr.on('data', (data) => stderr += data.toString());
-
-             child.on('error', (err) => reject(new Error(`Failed to execute idb: ${err.message}`)));
-             
-             child.on('close', (code) => {
-                 if (code !== 0) {
-                     reject(new Error(`idb failed (code ${code}): ${stderr.trim()}`));
-                 } else {
-                     resolve(stdout);
-                 }
-             });
-         });
+         const output = await measurement.physicalRead(async () => {
+           const result = await execCmd(getIdbCmd(), args, { timeout: remainingBudget() })
+           if (result.stderr === 'ACTION_TIMEOUT') throw new Error('ACTION_TIMEOUT')
+           if (result.exitCode !== 0) throw new Error(`idb failed (code ${result.exitCode}): ${result.stderr}`)
+           if (!result.stdout.trim()) throw new Error('Empty idb UI tree output')
+           return result.stdout
+         })
 
          if (output && output.trim().length > 0) {
-             jsonContent = JSON.parse(output);
+             jsonContent = await measurement.timed('parse_ms', async () => JSON.parse(output));
              break; // Success
          }
       } catch (e) {
+         if (e instanceof Error && e.message === 'ACTION_TIMEOUT') throw e
          console.error(`Attempt ${attempts} failed: ${e}`);
       }
       
        if (attempts === maxAttempts) {
            const snapshotMetadata = deriveSnapshotMetadata(deviceKey, null, 'ui_tree')
+           measurement.setOutcome('unavailable')
+           measurement.finish()
            return {
                device,
                screen: "",
@@ -597,14 +604,15 @@ export class iOSObserve {
     }
 
     try {
-        const elements: UIElement[] = [];
-        if (Array.isArray(jsonContent)) {
-          for (const node of jsonContent) {
-            traverseIDBNode(node, elements);
+        const elements: UIElement[] = await measurement.timed('conversion_ms', async () => {
+          const parsed: UIElement[] = []
+          if (Array.isArray(jsonContent)) {
+            for (const node of jsonContent) traverseIDBNode(node, parsed)
+          } else {
+            traverseIDBNode(jsonContent, parsed)
           }
-        } else {
-          traverseIDBNode(jsonContent, elements);
-        }
+          return parsed
+        })
 
         let width = 0;
         let height = 0;
@@ -620,15 +628,20 @@ export class iOSObserve {
           elements
         }, 'ui_tree')
 
-        return {
-            device,
-            screen: "",
-            resolution: { width, height },
-            elements,
-            ...snapshotMetadata
-        };
+        measurement.setOutcome('observed')
+        const response = measurement.bindObservation({
+          device,
+          screen: "",
+          resolution: { width, height },
+          elements,
+          ...snapshotMetadata
+        })
+        measurement.finish()
+        return response
     } catch (e) {
          const snapshotMetadata = deriveSnapshotMetadata(deviceKey, null, 'ui_tree')
+         measurement.setOutcome('unavailable')
+         measurement.finish()
           return {
             device,
             screen: "",

package/src/observe/performance-metrics.ts

@@ -0,0 +1,125 @@
+import { randomUUID } from 'node:crypto'
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+export type ObservationPurpose = 'target' | 'verification' | 'assertion' | 'debug' | 'unspecified'
+
+interface ObservationContext {
+  stepId?: string
+  purpose: ObservationPurpose
+}
+
+const context = new AsyncLocalStorage<ObservationContext>()
+const observationIds = new WeakMap<object, string>()
+
+export function withObservationContext<T>(value: Partial<ObservationContext>, operation: () => Promise<T>): Promise<T> {
+  if (process.env.MOBILE_DEBUG_MCP_UI_TREE_METRICS !== '1') return operation()
+  return context.run({ purpose: value.purpose ?? context.getStore()?.purpose ?? 'unspecified', stepId: value.stepId ?? context.getStore()?.stepId }, operation)
+}
+
+export function recordObservationEvent(event: Record<string, unknown>) {
+  if (process.env.MOBILE_DEBUG_MCP_UI_TREE_METRICS !== '1') return
+  const current = context.getStore()
+  process.stderr.write(`${JSON.stringify({
+    event: 'ui_tree_metric',
+    host_monotonic_ns: process.hrtime.bigint().toString(),
+    type: 'action_observation',
+    step_id: current?.stepId,
+    purpose: current?.purpose ?? 'unspecified',
+    ...event
+  })}\n`)
+}
+
+export function recordObservationConsumer(observation: unknown, purpose: ObservationPurpose, stepId?: string) {
+  if (process.env.MOBILE_DEBUG_MCP_UI_TREE_METRICS !== '1' || !observation || typeof observation !== 'object') return
+  const acquisitionId = observationIds.get(observation)
+  if (!acquisitionId) return
+  const current = context.getStore()
+  process.stderr.write(`${JSON.stringify({
+    event: 'ui_tree_metric',
+    host_monotonic_ns: process.hrtime.bigint().toString(),
+    type: 'observation_consumer',
+    acquisition_id: acquisitionId,
+    consumer_step_id: stepId ?? current?.stepId,
+    consumer_purpose: purpose,
+    reused_observations: 1
+  })}\n`)
+}
+
+export function createObservationMeasurement(platform: 'android' | 'ios') {
+  const enabled = process.env.MOBILE_DEBUG_MCP_UI_TREE_METRICS === '1'
+  const startedAt = enabled ? performance.now() : 0
+  const id = enabled ? randomUUID() : undefined
+  const current = context.getStore()
+  const durations: Record<string, number> = {}
+  let successfulOutput = false
+  let outcome: 'observed' | 'unavailable' = 'unavailable'
+  let readAttempt = 0
+
+  const emit = (event: Record<string, unknown>) => {
+    if (!enabled) return
+    process.stderr.write(`${JSON.stringify({
+      event: 'ui_tree_metric',
+      host_monotonic_ns: process.hrtime.bigint().toString(),
+      acquisition_id: id,
+      platform,
+      step_id: current?.stepId,
+      purpose: current?.purpose ?? 'unspecified',
+      ...event
+    })}\n`)
+  }
+
+  return {
+    id,
+    bindObservation<T extends object>(observation: T): T {
+      if (enabled && id) observationIds.set(observation, id)
+      return observation
+    },
+    timed: async <T>(stage: string, operation: () => Promise<T>): Promise<T> => {
+      if (!enabled) return operation()
+      const start = performance.now()
+      let success = true
+      try {
+        return await operation()
+      } catch (error) {
+        success = false
+        throw error
+      } finally {
+        const elapsed = performance.now() - start
+        durations[stage] = (durations[stage] ?? 0) + elapsed
+        emit({ type: 'stage', stage, attempt_index: stage === 'parse_ms' ? readAttempt : undefined, elapsed_ms: elapsed, success })
+      }
+    },
+    physicalRead: async <T>(operation: () => Promise<T>): Promise<T> => {
+      if (!enabled) return operation()
+      const start = performance.now()
+      readAttempt++
+      emit({ type: 'physical_read_started', attempt_index: readAttempt })
+      try {
+        const result = await operation()
+        successfulOutput = true
+        emit({ type: 'physical_read_completed', attempt_index: readAttempt, elapsed_ms: performance.now() - start, success: true })
+        return result
+      } catch (error) {
+        emit({ type: 'physical_read_completed', attempt_index: readAttempt, elapsed_ms: performance.now() - start, success: false })
+        throw error
+      }
+    },
+    setOutcome(value: 'observed' | 'unavailable') { if (enabled) outcome = value },
+    finish() {
+      if (!enabled) return
+      emit({
+        type: 'observation_consumer',
+        consumer_step_id: current?.stepId,
+        consumer_purpose: current?.purpose ?? 'unspecified',
+        reused_observations: 0
+      })
+      emit({
+        type: 'acquisition_completed',
+        elapsed_ms: performance.now() - startedAt,
+        successful_output: successfulOutput,
+        outcome,
+        durations_ms: durations
+      })
+    }
+  }
+}

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
 }

package/src/server/common.ts

@@ -1,3 +1,4 @@
+import { recordTiming } from '../utils/timing.js'
 import type {
   ActionTrace,
   ActionExecutionResult,
@@ -14,13 +15,17 @@ import { ToolsObserve } from '../observe/index.js'
 export const DEFAULT_MAX_RECOVERY_ATTEMPTS = 3
 export const DEFAULT_MAX_RETRY_DEPTH = 3
 
-export function wrapResponse<T>(data: T) {
-  return {
-    content: [{
-      type: 'text' as const,
-      text: JSON.stringify(data, null, 2)
-    }]
+export function wrapResponse<T>(data: T, includeSerializationTiming = true) {
+  const start = performance.now()
+  let text = JSON.stringify(data, null, 2)
+  const elapsed = performance.now() - start
+  const value = data as any
+  if (includeSerializationTiming && value && typeof value === 'object' && value.timing && typeof value.timing === 'object') {
+    value.timing.serialization_ms = (value.timing.serialization_ms ?? 0) + elapsed
+    recordTiming('serialization_ms', elapsed)
+    text = JSON.stringify(value, null, 2)
   }
+  return { content: [{ type: 'text' as const, text }] }
 }
 
 export type ToolCallArgs = Record<string, unknown>
@@ -312,6 +317,7 @@ function mapFailureCodeToFailureClass(code: ActionFailureCode): FailureClass {
     case 'STALE_REFERENCE':
       return 'TargetResolutionFailure'
     case 'ELEMENT_NOT_INTERACTABLE':
+    case 'ACTION_TIMEOUT':
       return 'ExecutionFailure'
     case 'TIMEOUT':
     case 'ACTION_REJECTED':
@@ -320,6 +326,7 @@ function mapFailureCodeToFailureClass(code: ActionFailureCode): FailureClass {
       return 'ExecutionFailure'
     case 'VERIFICATION_FAILED':
     case 'EXPECT_STATE_MISMATCH':
+    case 'ASSERTION_TIMEOUT':
       return 'VerificationFailure'
     case 'CONTROL_CONVERGENCE_FAILED':
       return 'ControlConvergenceFailure'