mobile-debug-mcp 0.31.0 → 0.32.1

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,
@@ -9,6 +14,7 @@ import { ToolsObserve } from '../observe/index.js'
 import { classifyActionOutcome } from '../interact/classify.js'
 import { ToolsNetwork } from '../network/index.js'
 import { getSystemStatus } from '../system/index.js'
+import { recordObservationConsumer, recordObservationEvent, withObservationContext } from '../observe/performance-metrics.js'
 import {
   buildActionExecutionResult,
   captureActionFingerprint,
@@ -24,6 +30,7 @@ import {
   requireObjectArg,
   requireStringArg,
   ToolCallArgs,
+  ToolCallResult,
   ToolHandler,
   wrapResponse,
   wrapToolError
@@ -36,16 +43,122 @@ 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
+    recordObservationEvent({
+      step_id: args._stepId as string | undefined,
+      action_type: type,
+      dispatch_ms: timing.dispatch_ms,
+      verification_mode: controls.verificationMode,
+      dispatch_started: dispatchStarted
+    })
+    let delta: unknown
+    let observationAvailable = false
+    if (result.success && controls.verificationMode === 'light') {
+      const verificationStarted = performance.now()
+      const tree = await withObservationContext({ stepId: args._stepId as string | undefined, purpose: 'verification' }, () =>
+        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
+      recordObservationEvent({
+        verification_budget_ms: controls.verificationTimeoutMs,
+        verification_elapsed_ms: performance.now() - verificationStarted,
+        verification_outcome: observationAvailable ? 'observed' : 'unavailable',
+        verification_budget_expired: !observationAvailable && performance.now() - verificationStarted >= controls.verificationTimeoutMs
+      })
+      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 +172,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 +188,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 +213,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 +304,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 +327,19 @@ 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 metricsStepId = process.env.MOBILE_DEBUG_MCP_UI_TREE_METRICS === '1' ? getStringArg(args, '_metricsStepId') : undefined
+  const res = await withObservationContext({ stepId: metricsStepId, purpose: metricsStepId?.includes('post-response') ? 'assertion' : 'debug' }, () =>
+    ToolsObserve.getUITreeHandler({ platform, deviceId, responseMode, sinceSnapshotRevision }))
   return wrapResponse(res)
 }
 
@@ -333,20 +459,23 @@ async function handleFindElement(args: ToolCallArgs) {
   const timeoutMs = getNumberArg(args, 'timeoutMs') ?? 3000
   const platform = getStringArg(args, 'platform') as PlatformArg | undefined
   const deviceId = getStringArg(args, 'deviceId')
-  const res = await ToolsInteract.findElementHandler({ query, exact, timeoutMs, platform, deviceId })
+  const targetStarted = performance.now()
+  const res = await withObservationContext({ purpose: 'target' }, () => ToolsInteract.findElementHandler({ query, exact, timeoutMs, platform, deviceId }))
+  recordObservationEvent({ target_resolution_ms: performance.now() - targetStarted, target_resolution_outcome: res.found ? 'found' : 'not_found', operation: 'find_element' })
   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 +483,158 @@ 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 targetStarted = performance.now()
+    const resolution = await withObservationContext({ stepId: args._stepId as string | undefined, purpose: 'target' }, () =>
+      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
+    recordObservationEvent({ step_id: args._stepId as string | undefined, purpose: 'target', target_resolution_ms: performance.now() - targetStarted, target_resolution_outcome: resolution.status })
+    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 })
+  if (freshTree) recordObservationConsumer(freshTree, 'target', args._stepId as string | undefined)
+  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, _stepId: step.id, verificationMode: lightCoveredByAssertion ? 'none' : requestedVerification }))
+    } else if (step.type === 'wait') {
+      result = await withObservationContext({ stepId: step.id, purpose: 'target' }, () => 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 withObservationContext({ stepId: step.id, purpose: 'assertion' }, () => 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, _stepId: step.id, 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 +642,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 +655,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 +688,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 +708,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 +727,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 +806,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 +822,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.1'
 }
 
 export function createServer() {