mobile-debug-mcp 0.31.0 → 0.32.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"
@@ -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
 }

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'

package/src/server/journey-schema.ts

@@ -0,0 +1,63 @@
+import { z } from 'zod'
+
+const selector = z.object({
+  text: z.string().min(1).optional(), resource_id: z.string().min(1).optional(),
+  accessibility_id: z.string().min(1).optional(), contains: z.boolean().optional()
+}).strict().refine(value => !!(value.text || value.resource_id || value.accessibility_id), 'Selector requires a target')
+const verificationMode = z.enum(['none', 'light', 'full'])
+const timeoutMs = z.number().int().min(100).max(60000).optional()
+const pollIntervalMs = z.number().int().min(50).max(1000).optional()
+const waitFor = z.object({
+  condition: z.enum(['exists', 'visible', 'clickable']).optional(),
+  timeoutMs: z.number().int().min(100).max(10000).optional(), pollIntervalMs,
+  match: z.object({ index: z.number().int().nonnegative().optional() }).strict().optional()
+}).strict()
+const target = { selector: selector.optional(), elementId: z.string().min(1).optional() }
+const exactlyOneTarget = (value: { selector?: unknown, elementId?: string }) => Number(!!value.selector) + Number(!!value.elementId) === 1
+const assertion = z.union([
+  z.object({ kind: z.literal('element_visible'), selector }).strict(),
+  z.object({ kind: z.literal('element_absent'), selector }).strict(),
+  z.object({ kind: z.literal('screen_fingerprint'), fingerprint: z.string().min(1) }).strict(),
+  z.object({ kind: z.literal('state_equals'), property: z.string().min(1), expected: z.union([z.boolean(), z.number().finite(), z.string()]), ...target }).strict().refine(exactlyOneTarget)
+])
+const id = z.string().min(1)
+const step = z.union([
+  z.object({ id, type: z.literal('start_app'), appId: z.string().min(1), verificationMode: verificationMode.optional() }).strict(),
+  z.object({ id, type: z.literal('tap'), ...target, waitFor: waitFor.optional(), verificationMode: verificationMode.optional() }).strict().refine(exactlyOneTarget),
+  z.object({ id, type: z.literal('wait'), selector, condition: z.enum(['exists', 'not_exists', 'visible', 'clickable']).optional(), timeoutMs, pollIntervalMs }).strict(),
+  z.object({ id, type: z.literal('assert'), assertion, timeoutMs, pollIntervalMs }).strict()
+])
+export const tapElementControlsSchema = z.object({
+  elementId: z.string().min(1).optional(), selector: selector.optional(), waitFor: waitFor.optional()
+}).strict().refine(value => Number(!!value.elementId) + Number(!!value.selector) === 1 && (!value.elementId || !value.waitFor))
+
+export const journeySchema = z.object({
+  platform: z.enum(['android', 'ios']), deviceId: z.string().min(1).optional(),
+  responseMode: z.enum(['compact', 'debug']).default('compact'), captureOnFailure: z.boolean().default(false),
+  defaults: z.object({ verificationMode: verificationMode.optional(), actionTimeoutMs: z.number().int().finite().optional(), verificationTimeoutMs: z.number().int().finite().optional() }).strict().optional(),
+  steps: z.array(step).min(1).max(50)
+}).strict().refine(value => new Set(value.steps.map(step => step.id)).size === value.steps.length, 'Step IDs must be unique')
+
+const selectorJson = { type: 'object', additionalProperties: false, properties: {
+  text: { type: 'string', minLength: 1 }, resource_id: { type: 'string', minLength: 1 }, accessibility_id: { type: 'string', minLength: 1 }, contains: { type: 'boolean' }
+}, anyOf: ['text', 'resource_id', 'accessibility_id'].map(key => ({ required: [key] })) }
+const targetJson = { selector: selectorJson, elementId: { type: 'string', minLength: 1 } }
+const oneTargetJson = [{ required: ['selector'], not: { required: ['elementId'] } }, { required: ['elementId'], not: { required: ['selector'] } }]
+const intervalJson = { timeoutMs: { type: 'integer', minimum: 100, maximum: 60000 }, pollIntervalMs: { type: 'integer', minimum: 50, maximum: 1000 } }
+const modeJson = { type: 'string', enum: ['none', 'light', 'full'] }
+const objectJson = (properties: Record<string, unknown>, required: string[], extra = {}) => ({ type: 'object', additionalProperties: false, properties, required, ...extra })
+export const journeyStepsJson = {
+  type: 'array', minItems: 1, maxItems: 50, items: { oneOf: [
+    objectJson({ id: { type: 'string', minLength: 1 }, type: { const: 'start_app' }, appId: { type: 'string', minLength: 1 }, verificationMode: modeJson }, ['id', 'type', 'appId']),
+    objectJson({ id: { type: 'string', minLength: 1 }, type: { const: 'tap' }, ...targetJson, verificationMode: modeJson,
+      waitFor: objectJson({ ...intervalJson, timeoutMs: { type: 'integer', minimum: 100, maximum: 10000 }, condition: { enum: ['exists', 'visible', 'clickable'] }, match: objectJson({ index: { type: 'integer', minimum: 0 } }, []) }, [])
+    }, ['id', 'type'], { oneOf: oneTargetJson }),
+    objectJson({ id: { type: 'string', minLength: 1 }, type: { const: 'wait' }, selector: selectorJson, condition: { enum: ['exists', 'not_exists', 'visible', 'clickable'] }, ...intervalJson }, ['id', 'type', 'selector']),
+    objectJson({ id: { type: 'string', minLength: 1 }, type: { const: 'assert' }, ...intervalJson, assertion: { oneOf: [
+      objectJson({ kind: { const: 'element_visible' }, selector: selectorJson }, ['kind', 'selector']),
+      objectJson({ kind: { const: 'element_absent' }, selector: selectorJson }, ['kind', 'selector']),
+      objectJson({ kind: { const: 'screen_fingerprint' }, fingerprint: { type: 'string', minLength: 1 } }, ['kind', 'fingerprint']),
+      objectJson({ kind: { const: 'state_equals' }, ...targetJson, property: { type: 'string', minLength: 1 }, expected: { type: ['boolean', 'number', 'string'] } }, ['kind', 'property', 'expected'], { oneOf: oneTargetJson })
+    ] } }, ['id', 'type', 'assertion'])
+  ] }
+}