mobile-debug-mcp 0.32.0 → 0.32.2

package/src/observe/ios.ts

@@ -1,5 +1,7 @@
 import { spawn } from "child_process"
 import { remainingBudget } from '../utils/operation-budget.js'
+import { execCmd } from '../utils/exec.js'
+import { createObservationMeasurement } from './performance-metrics.js'
 import { promises as fs } from "fs"
 import { GetLogsResponse, CaptureIOSScreenshotResponse, GetUITreeResponse, UIElement, DeviceInfo, UIElementSemanticMetadata, UIElementState, UIResolutionSelector, SelectorConfidence } from "../types.js"
 import { execCommand, getIOSDeviceMetadata, validateBundleId, getIdbCmd, getXcrunCmd, isIDBInstalled } from "../utils/ios/utils.js"
@@ -525,12 +527,22 @@ export class iOSObserve {
   }
 
   async getUITree(deviceId: string = "booted"): Promise<GetUITreeResponse> {
-    const device = await getIOSDeviceMetadata(deviceId);
+    const measurement = createObservationMeasurement('ios')
+    let device
+    try {
+      device = await measurement.timed('metadata_ms', () => getIOSDeviceMetadata(deviceId))
+    } catch (error) {
+      measurement.setOutcome('unavailable')
+      measurement.finish()
+      throw error
+    }
     const deviceKey = `ios:${device.id}`
     
-    const idbExists = await isIDBInstalled();
+    const idbExists = await measurement.timed('capability_check_ms', () => isIDBInstalled());
     if (!idbExists) {
        const snapshotMetadata = deriveSnapshotMetadata(deviceKey, null, 'ui_tree')
+       measurement.setOutcome('unavailable')
+       measurement.finish()
        return {
           device,
           screen: "",
@@ -551,7 +563,7 @@ export class iOSObserve {
       remainingBudget()
       attempts++;
       try {
-         await delay(Math.min(remainingBudget(300 + (attempts * 100)), 300 + (attempts * 100)));
+         await measurement.timed('observation_wait_ms', () => delay(Math.min(remainingBudget(300 + (attempts * 100)), 300 + (attempts * 100))));
          remainingBudget()
 
          const args = ['ui', 'describe-all', '--json'];
@@ -559,27 +571,16 @@ export class iOSObserve {
             args.push('--udid', targetUdid);
          }
 
-         const output = await new Promise<string>((resolve, reject) => {
-             const child = spawn(getIdbCmd(), args, { timeout: remainingBudget() || undefined });
-             let stdout = '';
-             let stderr = '';
-
-             child.stdout.on('data', (data) => stdout += data.toString());
-             child.stderr.on('data', (data) => stderr += data.toString());
-
-             child.on('error', (err) => reject(new Error(`Failed to execute idb: ${err.message}`)));
-             
-             child.on('close', (code) => {
-                 if (code !== 0) {
-                     reject(new Error(`idb failed (code ${code}): ${stderr.trim()}`));
-                 } else {
-                     resolve(stdout);
-                 }
-             });
-         });
+         const output = await measurement.physicalRead(async () => {
+           const result = await execCmd(getIdbCmd(), args, { timeout: remainingBudget() })
+           if (result.stderr === 'ACTION_TIMEOUT') throw new Error('ACTION_TIMEOUT')
+           if (result.exitCode !== 0) throw new Error(`idb failed (code ${result.exitCode}): ${result.stderr}`)
+           if (!result.stdout.trim()) throw new Error('Empty idb UI tree output')
+           return result.stdout
+         })
 
          if (output && output.trim().length > 0) {
-             jsonContent = JSON.parse(output);
+             jsonContent = await measurement.timed('parse_ms', async () => JSON.parse(output));
              break; // Success
          }
       } catch (e) {
@@ -589,6 +590,8 @@ export class iOSObserve {
       
        if (attempts === maxAttempts) {
            const snapshotMetadata = deriveSnapshotMetadata(deviceKey, null, 'ui_tree')
+           measurement.setOutcome('unavailable')
+           measurement.finish()
            return {
                device,
                screen: "",
@@ -601,14 +604,15 @@ export class iOSObserve {
     }
 
     try {
-        const elements: UIElement[] = [];
-        if (Array.isArray(jsonContent)) {
-          for (const node of jsonContent) {
-            traverseIDBNode(node, elements);
+        const elements: UIElement[] = await measurement.timed('conversion_ms', async () => {
+          const parsed: UIElement[] = []
+          if (Array.isArray(jsonContent)) {
+            for (const node of jsonContent) traverseIDBNode(node, parsed)
+          } else {
+            traverseIDBNode(jsonContent, parsed)
           }
-        } else {
-          traverseIDBNode(jsonContent, elements);
-        }
+          return parsed
+        })
 
         let width = 0;
         let height = 0;
@@ -624,15 +628,20 @@ export class iOSObserve {
           elements
         }, 'ui_tree')
 
-        return {
-            device,
-            screen: "",
-            resolution: { width, height },
-            elements,
-            ...snapshotMetadata
-        };
+        measurement.setOutcome('observed')
+        const response = measurement.bindObservation({
+          device,
+          screen: "",
+          resolution: { width, height },
+          elements,
+          ...snapshotMetadata
+        })
+        measurement.finish()
+        return response
     } catch (e) {
          const snapshotMetadata = deriveSnapshotMetadata(deviceKey, null, 'ui_tree')
+         measurement.setOutcome('unavailable')
+         measurement.finish()
           return {
             device,
             screen: "",

package/src/observe/performance-metrics.ts

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

package/src/server/tool-handlers.ts

@@ -14,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,
@@ -102,12 +103,27 @@ function actionHandler(type: string, execute: ToolHandler): ToolHandler {
     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 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
+      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)
@@ -321,7 +337,9 @@ async function handleGetUITree(args: ToolCallArgs) {
   const deviceId = getStringArg(args, 'deviceId')
   const responseMode = (getStringArg(args, 'responseMode') as ResponseMode | undefined) ?? 'debug'
   const sinceSnapshotRevision = getNumberArg(args, 'sinceSnapshotRevision')
-  const res = await ToolsObserve.getUITreeHandler({ platform, deviceId, responseMode, 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)
 }
 
@@ -441,7 +459,9 @@ 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)
 }
 
@@ -477,12 +497,16 @@ async function executeTapElement(args: ToolCallArgs) {
   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
+    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()
+  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)
 }
@@ -549,12 +573,12 @@ async function handleRunJourney(args: ToolCallArgs) {
     }
     try {
     if (step.type === 'tap') {
-      result = payloadOf(await handleTapElement({ ...defaults, ...step, platform, deviceId, responseMode, _journey: true, verificationMode: lightCoveredByAssertion ? 'none' : requestedVerification }))
+      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 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 = 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 runWithBudget((step.timeoutMs as number | undefined) ?? 5000, async () => {
+      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 })
@@ -562,9 +586,9 @@ async function handleRunJourney(args: ToolCallArgs) {
       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' }))
+      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' }
     }

package/src/server-core.ts

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

package/src/utils/exec.ts

@@ -14,22 +14,28 @@ export async function execCmd(cmd: string, args: string[], opts: ExecOptions = {
     if (child.stderr) child.stderr.on('data', (d) => { stderr += d.toString() })
 
     let timedOut = false
+    let forceKillTimer: NodeJS.Timeout | null = null
     const timer = timeout && timeout > 0 ? setTimeout(() => {
       timedOut = true
       try { child.kill() } catch { }
-      resolve({ exitCode: null, stdout: stdout.trim(), stderr: 'ACTION_TIMEOUT' })
+      forceKillTimer = setTimeout(() => {
+        try { child.kill('SIGKILL') } catch { }
+      }, 1000)
+      forceKillTimer.unref()
     }, timeout) : null
 
     child.on('close', (code) => {
       if (timer) clearTimeout(timer)
-      if (timedOut) return
-      resolve({ exitCode: code, stdout: stdout.trim(), stderr: stderr.trim() })
+      if (forceKillTimer) clearTimeout(forceKillTimer)
+      resolve(timedOut
+        ? { exitCode: null, stdout: stdout.trim(), stderr: 'ACTION_TIMEOUT' }
+        : { exitCode: code, stdout: stdout.trim(), stderr: stderr.trim() })
     })
 
     child.on('error', (err) => {
       if (timer) clearTimeout(timer)
+      if (forceKillTimer) clearTimeout(forceKillTimer)
       reject(err)
     })
   })
 }
-