mobile-debug-mcp 0.31.0 → 0.32.0

package/src/server/tool-handlers.ts

@@ -1,3 +1,8 @@
+import { measure, withTiming } from '../utils/timing.js'
+import { randomUUID } from 'node:crypto'
+import { runWithBudget } from '../utils/operation-budget.js'
+import { journeySchema, tapElementControlsSchema } from './journey-schema.js'
+import { resolveTargetDevice, withResolvedDevice } from '../utils/resolve-device.js'
 import type {
   InstallAppResponse,
   ResetAppDataResponse,
@@ -24,6 +29,7 @@ import {
   requireObjectArg,
   requireStringArg,
   ToolCallArgs,
+  ToolCallResult,
   ToolHandler,
   wrapResponse,
   wrapToolError
@@ -36,16 +42,107 @@ type WaitForUiMatchArg = { index?: number }
 type WaitForUiRetryArg = { max_attempts?: number, backoff_ms?: number }
 type ScrollSelectorArg = { text?: string, resourceId?: string, contentDesc?: string, className?: string }
 type ClassifyNetworkRequestArg = { endpoint: string, status: 'success' | 'failure' | 'retryable' }
+type VerificationMode = 'none' | 'light' | 'full'
+type ResponseMode = 'compact' | 'debug'
 
-async function handleStartApp(args: ToolCallArgs) {
+function interactionControls(args: ToolCallArgs) {
+  const verificationMode = (getStringArg(args, 'verificationMode') as VerificationMode | undefined) ?? 'full'
+  const responseMode = (getStringArg(args, 'responseMode') as ResponseMode | undefined) ?? 'debug'
+  if (!['none', 'light', 'full'].includes(verificationMode) || !['compact', 'debug'].includes(responseMode)) throw new Error('INVALID_ARGUMENT')
+  for (const key of ['verificationMode', 'responseMode']) if (args[key] !== undefined && typeof args[key] !== 'string') throw new Error('INVALID_ARGUMENT')
+  for (const key of ['actionTimeoutMs', 'verificationTimeoutMs']) if (args[key] !== undefined && (typeof args[key] !== 'number' || !Number.isInteger(args[key]))) throw new Error('INVALID_ARGUMENT')
+  const actionTimeoutMs = getNumberArg(args, 'actionTimeoutMs')
+  const verificationTimeoutMs = getNumberArg(args, 'verificationTimeoutMs')
+  return { verificationMode, responseMode,
+    actionTimeoutMs: actionTimeoutMs === undefined ? undefined : Math.max(100, Math.min(30000, actionTimeoutMs)),
+    verificationTimeoutMs: verificationTimeoutMs === undefined ? 3000 : Math.max(100, Math.min(60000, verificationTimeoutMs)) }
+
+}
+
+function compactAction(result: any, verificationMode: VerificationMode, started = true, stateDelta?: unknown, totalMs = 0) {
+  return {
+    action_id: result.action_id,
+    action_type: result.action_type,
+    success: !!result.success,
+    lifecycle_state: result.success ? (verificationMode === 'full' ? result.lifecycle_state : 'pending_verification') : 'failed',
+    ...(result.failure_code ? { failure_code: result.failure_code } : {}),
+    ...(typeof result.retryable === 'boolean' ? { retryable: result.retryable } : {}),
+    delivery_status: result.success ? 'delivered' : (started ? 'unknown' : 'not_delivered'),
+    dispatch_started: started,
+    verification: { mode: verificationMode, status: result.success ? (verificationMode === 'none' ? 'not_requested' : verificationMode === 'light' ? 'observed' : (result.lifecycle_state === 'verified' ? 'verified' : 'observed')) : 'failed' },
+    ...(stateDelta ? { state_delta: stateDelta } : {}),
+    timing: { total_ms: totalMs }
+  }
+}
+
+function actionHandler(type: string, execute: ToolHandler): ToolHandler {
+  return async (args) => {
+    const timing: Record<string, number> = {}
+    return withTiming(timing, async () => {
+    const started = performance.now()
+    const controls = interactionControls(args)
+    const budgetMs = controls.actionTimeoutMs ?? ({ start_app: 10000, restart_app: 15000, scroll_to_element: 10000 }[type] ?? 5000)
+    let dispatchStarted = false
+    let result: any
+    const dispatchWithBudget = (timeoutMs: number) => runWithBudget(timeoutMs, async (budget) => {
+      try { return payloadOf(await execute(args)) }
+      finally { dispatchStarted = budget.dispatchStarted }
+    })
+    try {
+      // Omitted controls retain the existing adapter budgets.
+      result = args._journey !== true && controls.verificationMode === 'full' && controls.responseMode === 'debug' && controls.actionTimeoutMs === undefined
+        ? await dispatchWithBudget(Infinity) : await dispatchWithBudget(budgetMs)
+      if (result.success) dispatchStarted = true
+    } catch (error) {
+      if (controls.verificationMode === 'full' && controls.responseMode === 'debug' && controls.actionTimeoutMs === undefined && !/TIMEOUT|timed out/i.test(String(error))) return wrapToolError(type, error)
+      result = { success: false, failure_code: /TIMEOUT|timed out/i.test(String(error)) ? 'ACTION_TIMEOUT' : 'UNKNOWN', error: String(error) }
+    }
+    if (result.failure_code === 'TIMEOUT' || /ACTION_TIMEOUT|timeout/i.test(result.error ?? result.reason ?? result.details?.error ?? '')) result.failure_code = 'ACTION_TIMEOUT'
+    if (result.failure_code === 'ACTION_TIMEOUT') result.retryable = !dispatchStarted
+    if (!result.success && typeof result.retryable !== 'boolean') result.retryable = !dispatchStarted
+    result.action_id ??= randomUUID()
+    result.action_type ??= type
+    let delta: unknown
+    let observationAvailable = false
+    if (result.success && controls.verificationMode === 'light') {
+      const tree = await measure('post_observation_ms', () => runWithBudget(controls.verificationTimeoutMs, () =>
+        ToolsObserve.getUITreeHandler({ platform: (args.platform as PlatformArg | undefined) ?? result.device?.platform, deviceId: (args.deviceId as string | undefined) ?? result.device?.id }))).catch(() => null) as any
+      observationAvailable = !!tree && !tree.error
+      if (observationAvailable && tree.device) delta = ToolsObserve.getLatestStateDelta(tree.device.platform, tree.device.id) ?? undefined
+    }
+    const compact = compactAction(result, controls.verificationMode, dispatchStarted, delta, performance.now() - started)
+    if (result.success && controls.verificationMode === 'light' && !observationAvailable) compact.verification.status = 'unavailable'
+    const evidence = {
+      ...compact,
+      ...(controls.verificationMode === 'light' ? { state_delta_available: !!delta } : {}),
+      ...(result.success && controls.verificationMode === 'light' && !observationAvailable ? { verification_diagnostic: { code: 'VERIFICATION_UNAVAILABLE', retryable: true } } : {})
+    }
+    return wrapResponse(controls.responseMode === 'compact' ? evidence : {
+      ...result, ...evidence, timing: { ...timing, total_ms: performance.now() - started },
+      effective_controls: { ...controls, actionTimeoutMs: args._journey !== true && controls.verificationMode === 'full' && controls.responseMode === 'debug' && controls.actionTimeoutMs === undefined ? null : budgetMs, timeout_bound: !(args._journey !== true && controls.verificationMode === 'full' && controls.responseMode === 'debug' && controls.actionTimeoutMs === undefined) }
+    }, controls.responseMode === 'debug')
+    })
+  }
+}
+const handleStartApp = actionHandler('start_app', executeStartApp)
+const handleRestartApp = actionHandler('restart_app', executeRestartApp)
+const handleTap = actionHandler('tap', executeTap)
+const handleTapElement = actionHandler('tap_element', executeTapElement)
+const handleSwipe = actionHandler('swipe', executeSwipe)
+const handleScrollToElement = actionHandler('scroll_to_element', executeScrollToElement)
+const handleTypeText = actionHandler('type_text', executeTypeText)
+const handlePressBack = actionHandler('press_back', executePressBack)
+
+async function executeStartApp(args: ToolCallArgs) {
   const platform = requireStringArg(args, 'platform') as PlatformArg
   const appId = requireStringArg(args, 'appId')
   const deviceId = getStringArg(args, 'deviceId')
-  const uiFingerprintBefore = await captureActionFingerprint(platform, deviceId)
+  const { verificationMode, actionTimeoutMs } = interactionControls(args)
+  const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null
   ToolsNetwork.notifyActionStart()
-  const res = await (platform === 'android' ? new AndroidManage().startApp(appId, deviceId) : new iOSManage().startApp(appId, deviceId))
-  const uiFingerprintAfter = await captureActionFingerprint(platform, deviceId)
-  return wrapResponse(buildActionExecutionResult({
+  const res = await measure('dispatch_ms', () => (platform === 'android' ? new AndroidManage().startApp(appId, deviceId, actionTimeoutMs ?? (verificationMode === 'full' && getStringArg(args, 'responseMode') === undefined && args._journey !== true ? undefined : 10000)) : new iOSManage().startApp(appId, deviceId, verificationMode === 'full')))
+  const uiFingerprintAfter = verificationMode === 'full' ? await measure('post_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null
+  const result = buildActionExecutionResult({
     actionType: 'start_app',
     sourceModule: 'server',
     device: res.device,
@@ -59,9 +156,11 @@ async function handleStartApp(args: ToolCallArgs) {
       ...(typeof res.output === 'string' ? { output: res.output } : {}),
       ...(res.device ? { device_id: res.device.id } : {}),
       ...(typeof res.error === 'string' ? { error: res.error } : {}),
+      ...(res.diagnostics ? { diagnostics: res.diagnostics } : {}),
       ...(res.observedApp ? { observed_app: res.observedApp } : {})
     }
-  }))
+  })
+  return wrapResponse(result)
 }
 
 async function handleTerminateApp(args: ToolCallArgs) {
@@ -73,15 +172,17 @@ async function handleTerminateApp(args: ToolCallArgs) {
   return wrapResponse(response)
 }
 
-async function handleRestartApp(args: ToolCallArgs) {
+async function executeRestartApp(args: ToolCallArgs) {
   const platform = requireStringArg(args, 'platform') as PlatformArg
   const appId = requireStringArg(args, 'appId')
   const deviceId = getStringArg(args, 'deviceId')
-  const uiFingerprintBefore = await captureActionFingerprint(platform, deviceId)
+  const { verificationMode, actionTimeoutMs } = interactionControls(args)
+  const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null
   ToolsNetwork.notifyActionStart()
-  const res = await (platform === 'android' ? new AndroidManage().restartApp(appId, deviceId) : new iOSManage().restartApp(appId, deviceId))
-  const uiFingerprintAfter = await captureActionFingerprint(platform, deviceId)
-  return wrapResponse(buildActionExecutionResult({
+  const bounded = args._journey === true || verificationMode !== 'full' || args.responseMode !== undefined || actionTimeoutMs !== undefined
+  const res = await measure('dispatch_ms', () => (platform === 'android' ? new AndroidManage().restartApp(appId, deviceId, bounded, actionTimeoutMs ?? 15000) : new iOSManage().restartApp(appId, deviceId, verificationMode === 'full', bounded, actionTimeoutMs ?? 15000)))
+  const uiFingerprintAfter = verificationMode === 'full' ? await measure('post_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null
+  const result = buildActionExecutionResult({
     actionType: 'restart_app',
     sourceModule: 'server',
     device: res.device,
@@ -96,9 +197,11 @@ async function handleRestartApp(args: ToolCallArgs) {
       ...(typeof res.terminatedBeforeRestart === 'boolean' ? { terminated_before_restart: res.terminatedBeforeRestart } : {}),
       ...(typeof res.terminateError === 'string' ? { terminate_error: res.terminateError } : {}),
       ...(typeof res.error === 'string' ? { error: res.error } : {}),
+      ...(res.diagnostics ? { diagnostics: res.diagnostics } : {}),
       ...(res.observedApp ? { observed_app: res.observedApp } : {})
     }
-  }))
+  })
+  return wrapResponse(result)
 }
 
 async function handleResetAppData(args: ToolCallArgs) {
@@ -185,10 +288,12 @@ async function handleGetSystemStatus() {
 async function handleCaptureScreenshot(args: ToolCallArgs) {
   const platform = requireStringArg(args, 'platform') as PlatformArg
   const deviceId = getStringArg(args, 'deviceId')
+  const started = performance.now()
   const res = await ToolsObserve.captureScreenshotHandler({ platform, deviceId })
+  const screenshotMs = performance.now() - started
   const mime = (res as any).screenshot_mime || 'image/png'
   const content: Array<{ type: 'text' | 'image'; text?: string; data?: string; mimeType?: string }> = [
-    { type: 'text', text: JSON.stringify({ device: res.device, result: { resolution: (res as any).resolution, mimeType: mime } }, null, 2) },
+    { type: 'text', text: JSON.stringify({ device: res.device, result: { resolution: (res as any).resolution, mimeType: mime }, timing: { total_ms: screenshotMs, screenshot_ms: screenshotMs } }, null, 2) },
     { type: 'image', data: (res as any).screenshot, mimeType: mime }
   ]
   if ((res as any).screenshot_fallback) {
@@ -206,14 +311,17 @@ async function handleCaptureDebugSnapshot(args: ToolCallArgs) {
   const appId = getStringArg(args, 'appId')
   const deviceId = getStringArg(args, 'deviceId')
   const sessionId = getStringArg(args, 'sessionId')
-  const res = await ToolsObserve.captureDebugSnapshotHandler({ reason, includeLogs, logLines, platform, appId, deviceId, sessionId })
+  const includeScreenshot = getBooleanArg(args, 'includeScreenshot')
+  const res = await ToolsObserve.captureDebugSnapshotHandler({ reason, includeLogs, includeScreenshot, logLines, platform, appId, deviceId, sessionId })
   return wrapResponse(res)
 }
 
 async function handleGetUITree(args: ToolCallArgs) {
   const platform = requireStringArg(args, 'platform') as PlatformArg
   const deviceId = getStringArg(args, 'deviceId')
-  const res = await ToolsObserve.getUITreeHandler({ platform, deviceId })
+  const responseMode = (getStringArg(args, 'responseMode') as ResponseMode | undefined) ?? 'debug'
+  const sinceSnapshotRevision = getNumberArg(args, 'sinceSnapshotRevision')
+  const res = await ToolsObserve.getUITreeHandler({ platform, deviceId, responseMode, sinceSnapshotRevision })
   return wrapResponse(res)
 }
 
@@ -337,16 +445,17 @@ async function handleFindElement(args: ToolCallArgs) {
   return wrapResponse(res)
 }
 
-async function handleTap(args: ToolCallArgs) {
+async function executeTap(args: ToolCallArgs) {
   const platform = getStringArg(args, 'platform') as PlatformArg | undefined
   const x = requireNumberArg(args, 'x')
   const y = requireNumberArg(args, 'y')
   const deviceId = getStringArg(args, 'deviceId')
-  const uiFingerprintBefore = await captureActionFingerprint(platform, deviceId)
+  const { verificationMode, actionTimeoutMs } = interactionControls(args)
+  const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null
   ToolsNetwork.notifyActionStart()
-  const res = await ToolsInteract.tapHandler({ platform, x, y, deviceId })
-  const uiFingerprintAfter = await captureActionFingerprint(platform, deviceId)
-  return wrapResponse(buildActionExecutionResult({
+  const res = await measure('dispatch_ms', () => ToolsInteract.tapHandler({ platform, x, y, deviceId, timeoutMs: actionTimeoutMs }))
+  const uiFingerprintAfter = verificationMode === 'full' ? await measure('post_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null
+  const result = buildActionExecutionResult({
     actionType: 'tap',
     sourceModule: 'server',
     selector: { x, y },
@@ -354,17 +463,154 @@ async function handleTap(args: ToolCallArgs) {
     uiFingerprintBefore,
     uiFingerprintAfter,
     failure: res.success ? undefined : inferGenericFailure((res as any).error)
-  }))
+  })
+  return wrapResponse(result)
 }
 
-async function handleTapElement(args: ToolCallArgs) {
-  const elementId = requireStringArg(args, 'elementId')
+async function executeTapElement(args: ToolCallArgs) {
+  const controls = tapElementControlsSchema.safeParse({ elementId: args.elementId, selector: args.selector, waitFor: args.waitFor })
+  if (!controls.success) throw new Error(`INVALID_ARGUMENT: ${controls.error.message}`)
+  const elementId = controls.data.elementId
+  const selector = controls.data.selector as ExpectElementSelectorArg | undefined
+  const { verificationMode, actionTimeoutMs } = interactionControls(args)
+  let resolvedId = elementId
+  let freshTree: any
+  if (selector) {
+    const waitFor = getObjectArg<WaitForUiMatchArg>(args, 'waitFor') as any
+    const resolution = await measure('target_resolution_ms', () => runWithBudget(waitFor?.timeoutMs ?? 1500, () => ToolsInteract.waitForUIHandler({ selector, condition: waitFor?.condition ?? 'clickable', timeout_ms: waitFor?.timeoutMs ?? 1500, poll_interval_ms: waitFor?.pollIntervalMs ?? 100, match: waitFor?.match, singleObservation: true, singleAttempt: !waitFor, rejectAmbiguous: !waitFor, platform: getStringArg(args, 'platform') as PlatformArg | undefined, deviceId: getStringArg(args, 'deviceId') }))) as any
+    if (resolution.status !== 'success' || !resolution.element?.elementId) return wrapResponse({ success: false, action_type: 'tap_element', failure_code: resolution.error?.code ?? 'ELEMENT_NOT_FOUND', retryable: true })
+    resolvedId = resolution.element.elementId
+    freshTree = resolution._tree
+  }
   ToolsNetwork.notifyActionStart()
-  const res = await ToolsInteract.tapElementHandler({ elementId })
+  const res = await measure('dispatch_ms', () => ToolsInteract.tapElementHandler({ elementId: resolvedId!, freshTree, verificationMode, timeoutMs: actionTimeoutMs, platform: getStringArg(args, 'platform') as PlatformArg | undefined, deviceId: getStringArg(args, 'deviceId') })) as any
   return wrapResponse(res)
 }
 
-async function handleSwipe(args: ToolCallArgs) {
+function payloadOf(response: ToolCallResult) {
+  const text = response.content.find((item: any) => item.type === 'text')?.text
+  return text ? JSON.parse(text) : null
+}
+
+async function expectElementAbsent({ selector, timeoutMs, pollIntervalMs, platform, deviceId }: { selector: ExpectElementSelectorArg, timeoutMs: number, pollIntervalMs: number, platform: PlatformArg, deviceId?: string }) {
+  const deadline = performance.now() + timeoutMs
+  let consecutive = 0
+  let observed: unknown
+  while (performance.now() < deadline) {
+    const result = await ToolsInteract.waitForUIHandler({ selector, condition: 'not_exists', timeout_ms: 0, singleObservation: true, singleAttempt: true, platform, deviceId }) as any
+    observed = result.observed
+    consecutive = result.status === 'success' ? consecutive + 1 : 0
+    if (consecutive === 2 && performance.now() <= deadline) return { success: true, observed }
+    const delay = Math.max(100, pollIntervalMs)
+    if (performance.now() + delay >= deadline) break
+    await new Promise(resolve => setTimeout(resolve, delay))
+  }
+  return { success: false, failure_code: 'ASSERTION_TIMEOUT', observed }
+}
+
+async function expectFingerprint({ fingerprint, timeoutMs, platform, deviceId }: { fingerprint: string, timeoutMs: number, platform: PlatformArg, deviceId?: string }) {
+  const deadline = performance.now() + timeoutMs
+  let consecutive = 0
+  let observed: string | null = null
+  while (performance.now() < deadline) {
+    const result = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }) as any
+    observed = result?.fingerprint ?? null
+    consecutive = observed === fingerprint ? consecutive + 1 : 0
+    if (consecutive === 2 && performance.now() <= deadline) return { success: true, observed_fingerprint: observed }
+    if (performance.now() + 100 >= deadline) break
+    await new Promise(resolve => setTimeout(resolve, 100))
+  }
+  return { success: false, failure_code: 'ASSERTION_TIMEOUT', observed_fingerprint: observed }
+}
+
+async function handleRunJourney(args: ToolCallArgs) {
+  const parsed = journeySchema.safeParse(args)
+  if (!parsed.success) throw new Error(`INVALID_ARGUMENT: ${parsed.error.message}`)
+  const { platform, responseMode, defaults, captureOnFailure } = parsed.data
+  const steps = parsed.data.steps as Array<Record<string, any>>
+  const device = await resolveTargetDevice({ platform, deviceId: parsed.data.deviceId })
+  const deviceId = device.id
+  return withResolvedDevice(device, async () => {
+  const started = performance.now()
+  const results: any[] = []
+  let stoppedAt: string | null = null
+  let pendingLightStep: number | null = null
+  for (let index = 0; index < steps.length; index++) {
+    const step = steps[index]
+    const requestedVerification = step.verificationMode ?? defaults?.verificationMode ?? 'full'
+    const next = steps[index + 1]
+    const lightCoveredByAssertion = step.type === 'tap' && responseMode === 'compact' && requestedVerification === 'light' && next?.type === 'assert' &&
+      next.assertion?.kind === 'element_visible'
+    const stepStart = performance.now()
+    let result: any
+    if (stoppedAt) {
+      results.push({ id: step.id, type: step.type, status: 'not_run', success: false, reason: 'PREVIOUS_STEP_FAILED', result: null, timing: { total_ms: 0 } })
+      continue
+    }
+    try {
+    if (step.type === 'tap') {
+      result = payloadOf(await handleTapElement({ ...defaults, ...step, platform, deviceId, responseMode, _journey: true, verificationMode: lightCoveredByAssertion ? 'none' : requestedVerification }))
+    } else if (step.type === 'wait') {
+      result = await ToolsInteract.waitForUIHandler({ selector: step.selector as ExpectElementSelectorArg, condition: (step.condition as any) ?? 'exists', timeout_ms: (step.timeoutMs as number | undefined) ?? 5000, poll_interval_ms: (step.pollIntervalMs as number | undefined) ?? 100, platform, deviceId })
+      result = { success: result.status === 'success', ...result }
+    } else if (step.type === 'assert') {
+      result = await runWithBudget((step.timeoutMs as number | undefined) ?? 5000, async () => {
+      const assertion = step.assertion as any
+      if (assertion?.kind === 'element_visible') result = await ToolsInteract.expectElementVisibleHandler({ selector: assertion.selector, timeout_ms: (step.timeoutMs as number | undefined) ?? 5000, poll_interval_ms: (step.pollIntervalMs as number | undefined) ?? 100, platform, deviceId })
+      else if (assertion?.kind === 'element_absent') result = await expectElementAbsent({ selector: assertion.selector, timeoutMs: (step.timeoutMs as number | undefined) ?? 5000, pollIntervalMs: (step.pollIntervalMs as number | undefined) ?? 100, platform, deviceId })
+      else if (assertion?.kind === 'screen_fingerprint') result = await expectFingerprint({ fingerprint: assertion.fingerprint, timeoutMs: (step.timeoutMs as number | undefined) ?? 5000, platform, deviceId })
+      else if (assertion?.kind === 'state_equals') result = await ToolsInteract.expectStateHandler({ selector: assertion.selector, element_id: assertion.elementId, property: assertion.property, expected: assertion.expected, platform, deviceId, stabilization_window_ms: step.timeoutMs ?? 5000, poll_interval_ms: step.pollIntervalMs ?? 100, exact_budget: true })
+      else result = { success: false, failure_code: 'INVALID_ASSERTION' }
+      return result
+      })
+    } else if (step.type === 'start_app') {
+      result = payloadOf(await handleStartApp({ ...defaults, platform, deviceId, appId: step.appId, responseMode, _journey: true, verificationMode: step.verificationMode ?? defaults?.verificationMode ?? 'full' }))
+    } else {
+      result = { success: false, failure_code: 'UNSUPPORTED_JOURNEY_STEP' }
+    }
+    } catch (error) {
+      result = { success: false, failure_code: step.type === 'assert' ? 'ASSERTION_TIMEOUT' : 'STEP_FAILED', error: error instanceof Error ? error.message : String(error) }
+    }
+    if (step.type === 'assert' && !result?.success && /TIMEOUT/.test(result?.failure_code ?? '')) result.failure_code = 'ASSERTION_TIMEOUT'
+    const success = !!result?.success
+    if (lightCoveredByAssertion) {
+      result.verification = { mode: 'light', status: success ? 'unavailable' : 'failed' }
+      if (success) {
+        result.verification_diagnostic = { code: 'VERIFICATION_UNAVAILABLE', retryable: true }
+        pendingLightStep = results.length
+      }
+    }
+    if (step.type === 'assert' && pendingLightStep !== null) {
+      const pending = results[pendingLightStep].result
+      if (typeof result?.observed?.matched_count === 'number') {
+        pending.verification.status = 'observed'
+        delete pending.verification_diagnostic
+        const delta = ToolsObserve.getLatestStateDelta(platform, deviceId)
+        if (delta) { pending.state_delta = delta; pending.state_delta_available = true }
+      }
+      pendingLightStep = null
+    }
+    if (responseMode === 'compact' && ['wait', 'assert'].includes(step.type)) result = {
+      success, ...(result.failure_code ? { failure_code: result.failure_code } : {}),
+      ...(result.error?.code ? { failure_code: result.error.code } : {}),
+      ...(result.observed?.matched_count !== undefined ? { matched_count: result.observed.matched_count } : {}),
+      ...(result.observed_fingerprint !== undefined ? { matched: success } : {}),
+      ...(result.actual_state ? { observed: result.actual_state } : {})
+    }
+    results.push({ id: step.id, type: step.type, status: success ? 'passed' : 'failed', success, result, timing: { total_ms: performance.now() - stepStart } })
+    if (!success) stoppedAt = step.id as string
+  }
+  const failureSnapshot = stoppedAt && captureOnFailure && responseMode === 'debug'
+    ? await ToolsObserve.captureDebugSnapshotHandler({ platform, deviceId, includeScreenshot: false }).catch(() => null) : undefined
+  const componentTiming: Record<string, number> = {}
+  for (const step of results) for (const [key, value] of Object.entries(step.result?.timing ?? {})) {
+    if (key !== 'total_ms' && typeof value === 'number') componentTiming[key] = (componentTiming[key] ?? 0) + value
+  }
+  return wrapResponse({ success: stoppedAt === null, stopped_at_step_id: stoppedAt, steps: results, ...(failureSnapshot ? { failure_snapshot: failureSnapshot } : {}), timing: responseMode === 'compact' ? { total_ms: performance.now() - started } : { ...componentTiming, total_ms: performance.now() - started } }, responseMode === 'debug')
+  })
+}
+
+async function executeSwipe(args: ToolCallArgs) {
   const platform = (getStringArg(args, 'platform') as PlatformArg | undefined) ?? 'android'
   const x1 = requireNumberArg(args, 'x1')
   const y1 = requireNumberArg(args, 'y1')
@@ -372,11 +618,12 @@ async function handleSwipe(args: ToolCallArgs) {
   const y2 = requireNumberArg(args, 'y2')
   const duration = requireNumberArg(args, 'duration')
   const deviceId = getStringArg(args, 'deviceId')
-  const uiFingerprintBefore = await captureActionFingerprint(platform, deviceId)
+  const { verificationMode, actionTimeoutMs } = interactionControls(args)
+  const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null
   ToolsNetwork.notifyActionStart()
-  const res = await ToolsInteract.swipeHandler({ platform, x1, y1, x2, y2, duration, deviceId })
-  const uiFingerprintAfter = await captureActionFingerprint(platform, deviceId)
-  return wrapResponse(buildActionExecutionResult({
+  const res = await measure('dispatch_ms', () => ToolsInteract.swipeHandler({ platform, x1, y1, x2, y2, duration, deviceId, timeoutMs: actionTimeoutMs }))
+  const uiFingerprintAfter = verificationMode === 'full' ? await measure('post_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null
+  const result = buildActionExecutionResult({
     actionType: 'swipe',
     sourceModule: 'server',
     selector: { x1, y1, x2, y2, duration },
@@ -384,21 +631,23 @@ async function handleSwipe(args: ToolCallArgs) {
     uiFingerprintBefore,
     uiFingerprintAfter,
     failure: res.success ? undefined : inferGenericFailure((res as any).error)
-  }))
+  })
+  return wrapResponse(result)
 }
 
-async function handleScrollToElement(args: ToolCallArgs) {
+async function executeScrollToElement(args: ToolCallArgs) {
   const platform = requireStringArg(args, 'platform') as PlatformArg
   const selector = requireObjectArg<ScrollSelectorArg>(args, 'selector')
   const direction = getStringArg(args, 'direction') as 'down' | 'up' | undefined
   const maxScrolls = getNumberArg(args, 'maxScrolls')
   const scrollAmount = getNumberArg(args, 'scrollAmount')
   const deviceId = getStringArg(args, 'deviceId')
-  const uiFingerprintBefore = await captureActionFingerprint(platform, deviceId)
+  const { verificationMode } = interactionControls(args)
+  const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null
   ToolsNetwork.notifyActionStart()
-  const res = await ToolsInteract.scrollToElementHandler({ platform, selector, direction, maxScrolls, scrollAmount, deviceId })
-  const uiFingerprintAfter = await captureActionFingerprint(platform, deviceId)
-  return wrapResponse(buildActionExecutionResult({
+  const res = await measure('dispatch_ms', () => ToolsInteract.scrollToElementHandler({ platform, selector, direction, maxScrolls, scrollAmount, deviceId }))
+  const uiFingerprintAfter = verificationMode === 'full' ? await measure('post_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null
+  const result = buildActionExecutionResult({
     actionType: 'scroll_to_element',
     sourceModule: 'server',
     selector: selector ?? null,
@@ -415,17 +664,19 @@ async function handleScrollToElement(args: ToolCallArgs) {
     uiFingerprintBefore,
     uiFingerprintAfter,
     failure: res.success ? undefined : inferScrollFailure((res as any).reason)
-  }))
+  })
+  return wrapResponse(result)
 }
 
-async function handleTypeText(args: ToolCallArgs) {
+async function executeTypeText(args: ToolCallArgs) {
   const text = requireStringArg(args, 'text')
   const deviceId = getStringArg(args, 'deviceId')
-  const uiFingerprintBefore = await captureActionFingerprint('android', deviceId)
+  const { verificationMode, actionTimeoutMs } = interactionControls(args)
+  const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint('android', deviceId)) : null
   ToolsNetwork.notifyActionStart()
-  const res = await ToolsInteract.typeTextHandler({ text, deviceId })
-  const uiFingerprintAfter = await captureActionFingerprint('android', deviceId)
-  return wrapResponse(buildActionExecutionResult({
+  const res = await measure('dispatch_ms', () => ToolsInteract.typeTextHandler({ text, deviceId, timeoutMs: actionTimeoutMs }))
+  const uiFingerprintAfter = verificationMode === 'full' ? await measure('post_observation_ms', () => captureActionFingerprint('android', deviceId)) : null
+  const result = buildActionExecutionResult({
     actionType: 'type_text',
     sourceModule: 'server',
     selector: { text },
@@ -433,16 +684,18 @@ async function handleTypeText(args: ToolCallArgs) {
     uiFingerprintBefore,
     uiFingerprintAfter,
     failure: res.success ? undefined : inferGenericFailure((res as any).error)
-  }))
+  })
+  return wrapResponse(result)
 }
 
-async function handlePressBack(args: ToolCallArgs) {
+async function executePressBack(args: ToolCallArgs) {
   const deviceId = getStringArg(args, 'deviceId')
-  const uiFingerprintBefore = await captureActionFingerprint('android', deviceId)
+  const { verificationMode, actionTimeoutMs } = interactionControls(args)
+  const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint('android', deviceId)) : null
   ToolsNetwork.notifyActionStart()
-  const res = await ToolsInteract.pressBackHandler({ deviceId })
-  const uiFingerprintAfter = await captureActionFingerprint('android', deviceId)
-  return wrapResponse(buildActionExecutionResult({
+  const res = await measure('dispatch_ms', () => ToolsInteract.pressBackHandler({ deviceId, timeoutMs: actionTimeoutMs }))
+  const uiFingerprintAfter = verificationMode === 'full' ? await measure('post_observation_ms', () => captureActionFingerprint('android', deviceId)) : null
+  const result = buildActionExecutionResult({
     actionType: 'press_back',
     sourceModule: 'server',
     selector: { key: 'back' },
@@ -450,7 +703,8 @@ async function handlePressBack(args: ToolCallArgs) {
     uiFingerprintBefore,
     uiFingerprintAfter,
     failure: res.success ? undefined : inferGenericFailure((res as any).error)
-  }))
+  })
+  return wrapResponse(result)
 }
 
 async function handleStartLogStream(args: ToolCallArgs) {
@@ -528,6 +782,7 @@ export const toolHandlers: Record<string, ToolHandler> = {
   find_element: handleFindElement,
   tap: handleTap,
   tap_element: handleTapElement,
+  run_journey: handleRunJourney,
   swipe: handleSwipe,
   scroll_to_element: handleScrollToElement,
   type_text: handleTypeText,
@@ -543,10 +798,26 @@ export async function handleToolCall(name: string, args: ToolCallArgs = {}) {
   const handler = toolHandlers[name]
   if (!handler) throw new Error(`Unknown tool: ${name}`)
 
-  try {
-    return await handler(args)
-  } catch (error) {
-    console.error(`Error executing tool ${name}:`, error)
-    return wrapToolError(name, error)
+  const started = performance.now()
+  const measured: Record<string, number> = {}
+  const addTiming = (response: ToolCallResult) => {
+    if (!['start_app', 'restart_app', 'tap', 'tap_element', 'swipe', 'scroll_to_element', 'type_text', 'press_back', 'wait_for_ui', 'get_ui_tree', 'capture_screenshot', 'capture_debug_snapshot'].includes(name)) return response
+    const item = response.content.find(item => item.type === 'text')
+    if (item?.text) {
+      try {
+        const value = JSON.parse(item.text)
+        value.timing = { ...measured, ...value.timing, total_ms: performance.now() - started }
+        item.text = JSON.stringify(value)
+      } catch { /* Non-JSON text responses retain their original content. */ }
+    }
+    return response
   }
+  return withTiming(measured, async () => {
+    try {
+      return addTiming(await handler(args))
+    } catch (error) {
+      console.error(`Error executing tool ${name}:`, error)
+      return addTiming(wrapToolError(name, error))
+    }
+  })
 }

package/src/server-core.ts

@@ -16,7 +16,7 @@ export { wrapResponse, toolDefinitions, handleToolCall }
 
 export const serverInfo = {
   name: 'mobile-debug-mcp',
-  version: '0.31.0'
+  version: '0.32.0'
 }
 
 export function createServer() {

package/src/types.ts

@@ -162,6 +162,16 @@ export interface SnapshotDelta {
   total_elements: number;
 }
 
+export interface StateDelta {
+  base_snapshot_revision: number | null;
+  snapshot_revision: number;
+  added: UIElement[];
+  removed: Array<{ stable_id?: string; resourceId?: string; contentDescription?: string; text?: string; index: number }>;
+  changed: UIElement[];
+  truncated: boolean;
+  omitted_changes?: number;
+}
+
 export interface CaptureAndroidScreenResponse {
   device: DeviceInfo;
   screenshot: string; // base64 encoded string
@@ -282,6 +292,8 @@ export type ActionFailureCode =
   | 'ELEMENT_NOT_FOUND'
   | 'ELEMENT_NOT_INTERACTABLE'
   | 'TIMEOUT'
+  | 'ACTION_TIMEOUT'
+  | 'ASSERTION_TIMEOUT'
   | 'NAVIGATION_NO_CHANGE'
   | 'AMBIGUOUS_TARGET'
   | 'STALE_REFERENCE'
@@ -393,11 +405,23 @@ export interface FindElementResponse {
   error?: string;
 }
 
+export interface TimingBreakdown {
+  total_ms: number;
+  device_resolution_ms?: number;
+  pre_observation_ms?: number;
+  target_resolution_ms?: number;
+  dispatch_ms?: number;
+  post_observation_ms?: number;
+  verification_ms?: number;
+  screenshot_ms?: number;
+  serialization_ms?: number;
+}
+
 export interface ActionExecutionResult {
   action_id: string;
   timestamp: string;
   action_type: string;
-  lifecycle_state?: 'pending_verification' | 'failed';
+  lifecycle_state?: 'pending_verification' | 'verified' | 'failed';
   source_module?: 'server' | 'interact';
   device?: DeviceInfo;
   target: {
@@ -407,6 +431,11 @@ export interface ActionExecutionResult {
   success: boolean;
   failure_code?: ActionFailureCode;
   retryable?: boolean;
+  delivery_status?: 'delivered' | 'not_delivered' | 'unknown';
+  dispatch_started?: boolean;
+  verification?: { mode: 'none' | 'light' | 'full'; status: 'not_requested' | 'observed' | 'verified' | 'unavailable' | 'failed' };
+  state_delta?: StateDelta;
+  timing?: TimingBreakdown;
   recovery?: RecoveryState;
   trace: ActionTrace;
   ui_fingerprint_before?: string | null;
@@ -414,7 +443,7 @@ export interface ActionExecutionResult {
   details?: Record<string, unknown>;
 }
 
-export interface TapElementResponse extends ActionExecutionResult {}
+export interface TapElementResponse extends ActionExecutionResult { error?: string }
 
 export interface ExpectScreenResponse {
   success: boolean;

package/src/utils/exec.ts

@@ -1,9 +1,11 @@
+import { remainingBudget } from './operation-budget.js'
 import { spawn } from 'child_process'
 
 export type ExecOptions = { timeout?: number; env?: NodeJS.ProcessEnv; cwd?: string; shell?: boolean }
 
 export async function execCmd(cmd: string, args: string[], opts: ExecOptions = {}): Promise<{ exitCode: number | null, stdout: string, stderr: string }> {
-  const { timeout = 0, env, cwd, shell } = opts
+  const { env, cwd, shell } = opts
+  const timeout = remainingBudget(opts.timeout ?? 0)
   return new Promise((resolve, reject) => {
     const child = spawn(cmd, args, { env: { ...process.env, ...(env || {}) }, cwd, shell })
     let stdout = ''
@@ -15,7 +17,7 @@ export async function execCmd(cmd: string, args: string[], opts: ExecOptions = {
     const timer = timeout && timeout > 0 ? setTimeout(() => {
       timedOut = true
       try { child.kill() } catch { }
-      resolve({ exitCode: null, stdout: stdout.trim(), stderr: stderr.trim() })
+      resolve({ exitCode: null, stdout: stdout.trim(), stderr: 'ACTION_TIMEOUT' })
     }, timeout) : null
 
     child.on('close', (code) => {