mobile-debug-mcp 0.32.4 → 0.34.0

package/src/server/tool-definitions.ts

@@ -1,6 +1,21 @@
+import { debuggerTools } from './debugger-schema.js'
+import { systemTraceTools } from './system-trace-schema.js'
 import { journeyStepsJson } from './journey-schema.js'
+import { conditionalTools, expectedStateJson } from './condition-schema.js'
+import { readinessPropertiesJson } from './readiness-schema.js'
 
 export const toolDefinitions: any[] = [
+  ...debuggerTools,
+  ...systemTraceTools,
+  ...['get_app_readiness', 'wait_for_app_ready'].map(name => ({
+    name,
+    description: `${name === 'get_app_readiness' ? 'Observe readiness with at most two fresh UI-tree samples.' : 'Wait within a single bounded budget for settled UI evidence.'} Reports loading, transitioning, settled or unknown with evidence and limitations. Managed Android debugger pauses are reported from debugger evidence; unresponsive detection remains unsupported. Settled normalized foreground UI is not proof of app identity, responsiveness or backend completion.`,
+    inputSchema: { type: 'object', additionalProperties: false, required: ['platform'], properties: {
+      ...readinessPropertiesJson,
+      timeoutMs: { ...readinessPropertiesJson.timeoutMs, default: name === 'get_app_readiness' ? 15000 : 30000 },
+      ...(name === 'wait_for_app_ready' ? { pollIntervalMs: { type: 'integer', minimum: 100, maximum: 1000, default: 500 } } : {})
+    } }
+  })),
   {
     name: 'start_app',
     description: `Purpose:
@@ -1130,6 +1145,26 @@ Returns { requests: [], count: 0 } when no credible network signals are found.`,
 
 // Keep the additive execution controls consistent across all action tools.
 for (const tool of toolDefinitions) {
+  if (['wait_for_ui', 'wait_for_ui_change'].includes(tool.name)) {
+    tool.inputSchema.properties.requireReady = { type: 'boolean', default: false }
+    tool.description += '\nSet requireReady=true to require both the existing predicate and settled UI readiness, using the same fresh samples and one timeout budget. The readiness summary explains uncertainty. Default predicate semantics are unchanged.'
+  }
+  if (tool.name === 'get_ui_tree') tool.description += '\nSuccessful observations include snapshot_session_id and snapshot_revision for same-device conditional input. Compact errors preserve the error and cannot authorize an expectation.'
+  if (tool.name === 'run_journey') tool.description += '\nTap steps may include expectedState from a successful same-device get_ui_tree. A failed condition blocks that input, retains fresh condition evidence even in compact mode, and stops subsequent steps. Conditions are not journey defaults or supported on other step types.'
+  if (conditionalTools.has(tool.name)) {
+    tool.inputSchema.properties.expectedState = expectedStateJson
+    tool.inputSchema.properties.platform ??= { type: 'string', enum: ['android'] }
+    tool.inputSchema.allOf = [...(tool.inputSchema.allOf ?? []), {
+      if: { required: ['expectedState'] },
+      then: { required: ['platform', 'deviceId'], properties: {
+        platform: { enum: ['type_text', 'press_back'].includes(tool.name) ? ['android'] : ['android', 'ios'] },
+        deviceId: { type: 'string', minLength: 1, pattern: '\\S', not: { enum: ['booted', 'default'] } }
+      } }
+    }]
+    tool.description += '\n\nConditional input: optionally supply expectedState { snapshotSessionId, snapshotRevision, timeoutMs? } from a successful get_ui_tree on the same explicit platform/deviceId. A fresh normalized UI-tree check runs immediately before input, even with verification disabled. PRECONDITION_FAILED or PRECONDITION_UNAVAILABLE means no input was dispatched; inspect condition evidence and re-observe before deciding what to do next. Compact failures include the fresh UI tree. This is not atomic with OS input delivery.'
+  } else {
+    tool.inputSchema.allOf = [...(tool.inputSchema.allOf ?? []), { not: { required: ['expectedState'] } }]
+  }
   if (['start_app', 'restart_app', 'tap', 'tap_element', 'swipe', 'scroll_to_element', 'type_text', 'press_back'].includes(tool.name)) {
     Object.assign(tool.inputSchema.properties, {
       verificationMode: { type: 'string', enum: ['none', 'light', 'full'], default: 'full' },
@@ -1141,6 +1176,7 @@ for (const tool of toolDefinitions) {
   if (tool.name === 'tap_element') Object.assign(tool.inputSchema, { oneOf: [{ required: ['elementId'], not: { required: ['selector'] } }, { required: ['selector'], not: { required: ['elementId'] } }] })
   if (tool.name === 'run_journey') Object.assign(tool.inputSchema.properties, {
     steps: journeyStepsJson,
+    systemTraceId: { type: 'string', format: 'uuid', description: 'Explicit active same-device system trace. Invalid references prevent all journey input. Capture lifetime is controlled separately.' },
     captureOnFailure: { type: 'boolean', default: false },
     defaults: { type: 'object', additionalProperties: false, properties: {
       verificationMode: { type: 'string', enum: ['none', 'light', 'full'] },
@@ -1148,3 +1184,16 @@ for (const tool of toolDefinitions) {
     } }
   })
 }
+
+// Correlation is explicit; an omitted reference creates an independent observation.
+for (const tool of toolDefinitions) {
+  if (['capture_screenshot', 'get_ui_tree', 'get_screen_fingerprint', 'capture_debug_snapshot', 'get_logs', 'read_log_stream'].includes(tool.name)) {
+    Object.assign(tool.inputSchema.properties, { actionRef: {
+      type: 'object', additionalProperties: false, required: ['sessionId', 'actionId'], properties: {
+        sessionId: { type: 'string', minLength: 1, maxLength: 128 },
+        actionId: { type: 'string', minLength: 1, maxLength: 128 }
+      }
+    } })
+    tool.description += '\nReturns evidence metadata with acquisition intervals and conservative freshness. Optional actionRef links a known same-session/device action; unavailable references collect independently. Device log times are not comparable with host dispatch times.'
+  }
+}

package/src/server/tool-handlers.ts

@@ -1,7 +1,18 @@
+import { handleDebugger } from './debugger-handlers.js'
+import { debuggerContracts } from './debugger-schema.js'
+import { debuggerSessions } from '../debugger/sessions.js'
+import { withDebuggerGuard, guardDispatched } from '../debugger/guard.js'
+import { systemTraces, TraceError } from '../observe/system-trace.js'
+import { systemTraceTools, traceTargetSchema, traceStartSchema, traceControlSchema } from './system-trace-schema.js'
+import { currentEvidenceCorrelationId, bindSystemTrace, withEvidence, currentEvidenceActionId, validateActionRef, markEvidenceVerification, refreshJourneyEvidence, completeJourneyVerification } from '../observe/evidence.js'
 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 { readinessSchema, readinessWaitSchema } from './readiness-schema.js'
+import { getAppReadiness, withReadyWait } from '../observe/readiness-service.js'
+import { validateExpectedState } from './condition-schema.js'
+import { conditionFailureCode, createConditionalAction, notifyActionStart, withConditionalAction } from '../interact/conditional-action.js'
 import { resolveTargetDevice, withResolvedDevice } from '../utils/resolve-device.js'
 import type {
   InstallAppResponse,
@@ -36,6 +47,8 @@ import {
   wrapToolError
 } from './common.js'
 
+const systemTraceToolNames = new Set(systemTraceTools.map(tool => tool.name))
+
 type PlatformArg = 'android' | 'ios'
 type ProjectTypeArg = 'native' | 'kmp' | 'react-native' | 'flutter'
 type ExpectElementSelectorArg = { text?: string, resource_id?: string, accessibility_id?: string, contains?: boolean }
@@ -76,17 +89,42 @@ function compactAction(result: any, verificationMode: VerificationMode, started
   }
 }
 
+function correlatedHandler(name: string, handler: ToolHandler, action = false, journey = false): ToolHandler {
+  return async args => {
+    const ref = validateActionRef(args.actionRef)
+    const { result, evidence } = await withEvidence({ action, journey, ref }, async () => {
+      try { return await handler(args) }
+      catch (error) { return error instanceof TraceError ? { ...wrapResponse({ error: { tool: name, code: error.code, message: error.message } }), isError: true } : wrapToolError(name, error) }
+    })
+    const item = result.content.find(item => item.type === 'text')
+    if (item?.text) {
+      const payload = JSON.parse(item.text)
+      payload.evidence = evidence
+      item.text = JSON.stringify(payload)
+    }
+    return result
+  }
+}
+
 function actionHandler(type: string, execute: ToolHandler): ToolHandler {
-  return async (args) => {
+  return correlatedHandler(type, async (args) => {
     const timing: Record<string, number> = {}
     return withTiming(timing, async () => {
     const started = performance.now()
     const controls = interactionControls(args)
+    const expected = validateExpectedState(type, args)
+    const condition = expected ? createConditionalAction(args.platform as PlatformArg, args.deviceId as string, expected) : undefined
     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)) }
+      try {
+        if (!condition) return payloadOf(await execute(args))
+        return await withConditionalAction(condition, async () => {
+          const device = await resolveTargetDevice({ platform: condition.platform, deviceId: condition.deviceId })
+          return withResolvedDevice(device, async () => payloadOf(await execute(args)))
+        })
+      }
       finally { dispatchStarted = budget.dispatchStarted }
     })
     try {
@@ -95,13 +133,24 @@ function actionHandler(type: string, execute: ToolHandler): ToolHandler {
         ? 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)
+      if (!condition && 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) }
     }
+    const blocked = condition && ['mismatch', 'unavailable'].includes(condition.result.status)
+    if (blocked) {
+      dispatchStarted = false
+      result = buildActionExecutionResult({
+        actionType: type, sourceModule: 'server', device: condition.result.observed?.device,
+        selector: result?.target?.selector ?? null, resolved: result?.target?.resolved,
+        success: false, uiFingerprintBefore: result?.ui_fingerprint_before ?? null, uiFingerprintAfter: null,
+        failure: { failureCode: conditionFailureCode(condition), retryable: false },
+        traceSteps: [{ stage: 'verify', timestamp: Date.now(), result: 'failure', attempt_index: 0, metadata: { phase: 'precondition', dispatch_started: false } }]
+      })
+    }
     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_id ??= currentEvidenceActionId() ?? randomUUID()
     result.action_type ??= type
     recordObservationEvent({
       step_id: args._stepId as string | undefined,
@@ -117,6 +166,7 @@ function actionHandler(type: string, execute: ToolHandler): ToolHandler {
       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
+      markEvidenceVerification()
       observationAvailable = !!tree && !tree.error
       recordObservationEvent({
         verification_budget_ms: controls.verificationTimeoutMs,
@@ -126,10 +176,18 @@ function actionHandler(type: string, execute: ToolHandler): ToolHandler {
       })
       if (observationAvailable && tree.device) delta = ToolsObserve.getLatestStateDelta(tree.device.platform, tree.device.id) ?? undefined
     }
+    if (!blocked && controls.verificationMode === 'full' && dispatchStarted) markEvidenceVerification()
     const compact = compactAction(result, controls.verificationMode, dispatchStarted, delta, performance.now() - started)
+    if (blocked) compact.verification.status = 'not_requested'
     if (result.success && controls.verificationMode === 'light' && !observationAvailable) compact.verification.status = 'unavailable'
     const evidence = {
       ...compact,
+      ...(condition ? { condition: controls.responseMode === 'compact' && condition.result.status === 'matched'
+        ? { ...condition.result, observed: condition.result.observed ? {
+          snapshot_session_id: condition.result.observed.snapshot_session_id,
+          snapshot_revision: condition.result.observed.snapshot_revision,
+          captured_at_ms: condition.result.observed.captured_at_ms
+        } : null } : condition.result } : {}),
       ...(controls.verificationMode === 'light' ? { state_delta_available: !!delta } : {}),
       ...(result.success && controls.verificationMode === 'light' && !observationAvailable ? { verification_diagnostic: { code: 'VERIFICATION_UNAVAILABLE', retryable: true } } : {})
     }
@@ -138,7 +196,7 @@ function actionHandler(type: string, execute: ToolHandler): ToolHandler {
       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')
     })
-  }
+  }, true)
 }
 const handleStartApp = actionHandler('start_app', executeStartApp)
 const handleRestartApp = actionHandler('restart_app', executeRestartApp)
@@ -155,7 +213,7 @@ async function executeStartApp(args: ToolCallArgs) {
   const deviceId = getStringArg(args, 'deviceId')
   const { verificationMode, actionTimeoutMs } = interactionControls(args)
   const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null
-  ToolsNetwork.notifyActionStart()
+  notifyActionStart()
   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({
@@ -194,7 +252,7 @@ async function executeRestartApp(args: ToolCallArgs) {
   const deviceId = getStringArg(args, 'deviceId')
   const { verificationMode, actionTimeoutMs } = interactionControls(args)
   const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null
-  ToolsNetwork.notifyActionStart()
+  notifyActionStart()
   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
@@ -425,10 +483,12 @@ async function handleAdjustControl(args: ToolCallArgs) {
     platform,
     deviceId
   })
+  markEvidenceVerification()
   return wrapResponse(res)
 }
 
 async function handleWaitForUI(args: ToolCallArgs) {
+  if (args.requireReady !== undefined && typeof args.requireReady !== 'boolean') throw new Error('INVALID_ARGUMENT: requireReady must be boolean')
   const selector = getObjectArg<ExpectElementSelectorArg>(args, 'selector')
   const condition = (getStringArg(args, 'condition') as 'exists' | 'not_exists' | 'visible' | 'clickable' | undefined) ?? 'exists'
   const timeout_ms = getNumberArg(args, 'timeout_ms') ?? 60000
@@ -437,11 +497,14 @@ async function handleWaitForUI(args: ToolCallArgs) {
   const retry = getObjectArg<WaitForUiRetryArg>(args, 'retry')
   const platform = getStringArg(args, 'platform') as PlatformArg | undefined
   const deviceId = getStringArg(args, 'deviceId')
-  const res = await ToolsInteract.waitForUIHandler({ selector, condition, timeout_ms, poll_interval_ms, match, retry, platform, deviceId })
+  const execute = (targetPlatform = platform, targetId = deviceId) => ToolsInteract.waitForUIHandler({ selector, condition, timeout_ms, poll_interval_ms, match, retry, platform: targetPlatform, deviceId: targetId })
+  const res = args.requireReady === true ? await withReadyWait({ platform, deviceId }, timeout_ms,
+    device => execute(device.platform as PlatformArg, device.id), (code, elapsed, samples) => ({ status: 'timeout', error: { code, message: 'Readiness wait could not complete' }, metrics: { latency_ms: elapsed, poll_count: samples, attempts: samples ? 1 : 0 }, requested: { selector, condition, match }, observed: { matched_count: 0, condition_satisfied: false, selected_index: null, last_matched_element: null } })) : await execute()
   return wrapResponse(res)
 }
 
 async function handleWaitForUIChange(args: ToolCallArgs) {
+  if (args.requireReady !== undefined && typeof args.requireReady !== 'boolean') throw new Error('INVALID_ARGUMENT: requireReady must be boolean')
   const platform = getStringArg(args, 'platform') as PlatformArg | undefined
   const deviceId = getStringArg(args, 'deviceId')
   const timeout_ms = getNumberArg(args, 'timeout_ms') ?? 60000
@@ -449,7 +512,9 @@ async function handleWaitForUIChange(args: ToolCallArgs) {
   const expected_change = getStringArg(args, 'expected_change') as 'hierarchy_diff' | 'text_change' | 'state_change' | undefined
   const scope = getStringArg(args, 'scope') as 'screen' | 'subtree' | undefined
   const target = getStringArg(args, 'target')
-  const res = await ToolsInteract.waitForUIChangeHandler({ platform, deviceId, timeout_ms, stability_window_ms, expected_change, scope, target })
+  const execute = (targetPlatform = platform, targetId = deviceId) => ToolsInteract.waitForUIChangeHandler({ platform: targetPlatform, deviceId: targetId, timeout_ms, stability_window_ms, expected_change, scope, target })
+  const res = args.requireReady === true ? await withReadyWait({ platform, deviceId }, timeout_ms,
+    device => execute(device.platform as PlatformArg, device.id), (code, elapsed) => ({ success: false, timeout: true, observed_change: null, elapsed_ms: elapsed, reason: code, error: { code, message: 'Readiness wait could not complete' } })) : await execute()
   return wrapResponse(res)
 }
 
@@ -472,7 +537,7 @@ async function executeTap(args: ToolCallArgs) {
   const deviceId = getStringArg(args, 'deviceId')
   const { verificationMode, actionTimeoutMs } = interactionControls(args)
   const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null
-  ToolsNetwork.notifyActionStart()
+  notifyActionStart()
   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({
@@ -498,14 +563,15 @@ async function executeTapElement(args: ToolCallArgs) {
   if (selector) {
     const waitFor = getObjectArg<WaitForUiMatchArg>(args, 'waitFor') as any
     const targetStarted = performance.now()
+    const resolutionTimeoutMs = waitFor?.timeoutMs ?? actionTimeoutMs ?? 5000
     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
+      measure('target_resolution_ms', () => runWithBudget(resolutionTimeoutMs, () => ToolsInteract.waitForUIHandler({ selector, condition: waitFor?.condition ?? 'clickable', timeout_ms: resolutionTimeoutMs, poll_interval_ms: waitFor?.pollIntervalMs ?? 100, match: waitFor?.match, singleObservation: true, singleAttempt: !waitFor, rejectAmbiguous: !waitFor, resolveTapTarget: true, 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()
+  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)
@@ -554,13 +620,22 @@ async function handleRunJourney(args: ToolCallArgs) {
   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 finishTrace = parsed.data.systemTraceId
+    ? await systemTraces.link(parsed.data.systemTraceId, device, currentEvidenceCorrelationId()!) : undefined
+  if (parsed.data.systemTraceId) bindSystemTrace(parsed.data.systemTraceId)
+  try {
+  return await 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]
+    if (platform === 'android' && debuggerSessions.paused(deviceId)) {
+      results.push({ id: step.id, type: step.type, status: 'failed', success: false, result: { success: false, failure_code: 'DEBUGGER_PAUSED', dispatch_started: false, delivery_status: 'not_delivered' } })
+      stoppedAt = step.id as string
+      break
+    }
     const requestedVerification = step.verificationMode ?? defaults?.verificationMode ?? 'full'
     const next = steps[index + 1]
     const lightCoveredByAssertion = step.type === 'tap' && responseMode === 'compact' && requestedVerification === 'light' && next?.type === 'assert' &&
@@ -595,10 +670,12 @@ async function handleRunJourney(args: ToolCallArgs) {
     } catch (error) {
       result = { success: false, failure_code: step.type === 'assert' ? 'ASSERTION_TIMEOUT' : 'STEP_FAILED', error: error instanceof Error ? error.message : String(error) }
     }
+    if (platform === 'android' && debuggerSessions.paused(deviceId)) { result.success = false; result.failure_code = 'DEBUGGER_PAUSED'; result.retryable = false }
     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' }
+      result.verification = { mode: 'light', status: success ? 'unavailable' :
+        (['mismatch', 'unavailable'].includes(result.condition?.status) ? 'not_requested' : 'failed') }
       if (success) {
         result.verification_diagnostic = { code: 'VERIFICATION_UNAVAILABLE', retryable: true }
         pendingLightStep = results.length
@@ -608,6 +685,7 @@ async function handleRunJourney(args: ToolCallArgs) {
       const pending = results[pendingLightStep].result
       if (typeof result?.observed?.matched_count === 'number') {
         pending.verification.status = 'observed'
+        if (pending.evidence) completeJourneyVerification(pending.evidence.action_id)
         delete pending.verification_diagnostic
         const delta = ToolsObserve.getLatestStateDelta(platform, deviceId)
         if (delta) { pending.state_delta = delta; pending.state_delta_available = true }
@@ -630,8 +708,10 @@ async function handleRunJourney(args: ToolCallArgs) {
   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')
+  refreshJourneyEvidence(results)
+  return wrapResponse({ ...(finishTrace ? { system_trace: await finishTrace() } : {}), 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')
   })
+  } finally { await finishTrace?.() }
 }
 
 async function executeSwipe(args: ToolCallArgs) {
@@ -644,7 +724,7 @@ async function executeSwipe(args: ToolCallArgs) {
   const deviceId = getStringArg(args, 'deviceId')
   const { verificationMode, actionTimeoutMs } = interactionControls(args)
   const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null
-  ToolsNetwork.notifyActionStart()
+  notifyActionStart()
   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({
@@ -668,7 +748,7 @@ async function executeScrollToElement(args: ToolCallArgs) {
   const deviceId = getStringArg(args, 'deviceId')
   const { verificationMode } = interactionControls(args)
   const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null
-  ToolsNetwork.notifyActionStart()
+  notifyActionStart()
   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({
@@ -697,7 +777,7 @@ async function executeTypeText(args: ToolCallArgs) {
   const deviceId = getStringArg(args, 'deviceId')
   const { verificationMode, actionTimeoutMs } = interactionControls(args)
   const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint('android', deviceId)) : null
-  ToolsNetwork.notifyActionStart()
+  notifyActionStart()
   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({
@@ -716,7 +796,7 @@ async function executePressBack(args: ToolCallArgs) {
   const deviceId = getStringArg(args, 'deviceId')
   const { verificationMode, actionTimeoutMs } = interactionControls(args)
   const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint('android', deviceId)) : null
-  ToolsNetwork.notifyActionStart()
+  notifyActionStart()
   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({
@@ -780,7 +860,43 @@ async function handleGetNetworkActivity(args: ToolCallArgs) {
   return wrapResponse(result)
 }
 
+async function handleSystemTrace(name: string, args: ToolCallArgs) {
+  const schema = name === 'start_system_trace' ? traceStartSchema : name === 'get_system_trace_capabilities' ? traceTargetSchema : traceControlSchema
+  const parsed = schema.safeParse(args)
+  if (!parsed.success) throw new TraceError('INVALID_ARGUMENT')
+  if (name === 'get_system_trace_capabilities' || name === 'start_system_trace') {
+    const target = parsed.data as { platform: PlatformArg; deviceId?: string; durationMs?: number }
+    if (target.platform !== 'android') {
+      if (name === 'start_system_trace') throw new TraceError('UNSUPPORTED_PLATFORM')
+      return wrapResponse({ supported: false, backend: 'perfetto', device: null, prerequisites: {}, reasons: ['UNSUPPORTED_PLATFORM'], enabled_sources: [], unavailable_categories: [], limitations: ['Android only'] })
+    }
+    let device
+    try { device = await resolveTargetDevice(target) }
+    catch {
+      if (name === 'start_system_trace') throw new TraceError('TRACE_UNSUPPORTED')
+      return wrapResponse({ supported: false, backend: 'perfetto', device: null, prerequisites: { device: false }, reasons: ['DEVICE_UNAVAILABLE'], enabled_sources: [], unavailable_categories: [], limitations: ['An authorised Android device is required'] })
+    }
+    if (name === 'get_system_trace_capabilities') return wrapResponse(await systemTraces.capabilities(device.id))
+    const result = await systemTraces.start(device.id, target.durationMs)
+    return { ...wrapResponse(result), ...(result.state === 'failed' ? { isError: true } : {}) }
+  }
+  const operation = name === 'stop_system_trace' ? 'stop' : name === 'cancel_system_trace' ? 'cancel' : 'status'
+  const result = await systemTraces.control((parsed.data as { traceId: string }).traceId, operation)
+  return { ...wrapResponse(result), ...(['failed', 'cancelled'].includes(result.state) ? { isError: true } : {}) }
+}
+
 export const toolHandlers: Record<string, ToolHandler> = {
+  ...Object.fromEntries(systemTraceTools.map(({ name }) => [name, (args: ToolCallArgs) => handleSystemTrace(name, args)])),
+  get_app_readiness: async args => {
+    const parsed = readinessSchema.safeParse(args)
+    if (!parsed.success) throw new Error('INVALID_ARGUMENT: invalid readiness arguments')
+    return wrapResponse(await getAppReadiness(parsed.data))
+  },
+  wait_for_app_ready: async args => {
+    const parsed = readinessWaitSchema.safeParse(args)
+    if (!parsed.success) throw new Error('INVALID_ARGUMENT: invalid readiness arguments')
+    return wrapResponse(await getAppReadiness(parsed.data, true))
+  },
   start_app: handleStartApp,
   terminate_app: handleTerminateApp,
   restart_app: handleRestartApp,
@@ -818,7 +934,12 @@ export const toolHandlers: Record<string, ToolHandler> = {
   get_network_activity: handleGetNetworkActivity
 }
 
-export async function handleToolCall(name: string, args: ToolCallArgs = {}) {
+for (const name of ['capture_screenshot', 'get_ui_tree', 'get_screen_fingerprint', 'capture_debug_snapshot', 'get_logs', 'read_log_stream', 'run_journey', 'adjust_control']) {
+  toolHandlers[name] = correlatedHandler(name, toolHandlers[name], name === 'adjust_control', name === 'run_journey')
+}
+
+export async function handleToolCall(name: string, args: ToolCallArgs = {}, signal?: AbortSignal) {
+  if (Object.hasOwn(debuggerContracts, name)) return handleDebugger(name, args, signal)
   const handler = toolHandlers[name]
   if (!handler) throw new Error(`Unknown tool: ${name}`)
 
@@ -838,8 +959,48 @@ export async function handleToolCall(name: string, args: ToolCallArgs = {}) {
   }
   return withTiming(measured, async () => {
     try {
-      return addTiming(await handler(args))
+      if (!systemTraceToolNames.has(name)) validateExpectedState(name, args)
+      const guarded = ['start_app', 'terminate_app', 'restart_app', 'reset_app_data', 'install_app', 'build_and_install', 'tap', 'tap_element', 'swipe', 'scroll_to_element', 'type_text', 'press_back', 'adjust_control', 'run_journey', 'wait_for_ui', 'wait_for_ui_change', 'wait_for_screen_change', 'expect_screen', 'expect_element_visible', 'expect_state'].includes(name)
+      if (guarded && args.platform !== 'ios' && debuggerSessions.hasActiveSessions()) {
+        const device = await resolveTargetDevice({ platform: 'android', deviceId: args.deviceId as string | undefined })
+        return withResolvedDevice(device, () => withDebuggerGuard('android', device.id, async () => {
+          const before = debuggerSessions.paused(device.id)
+          if (before) return wrapResponse({ success: false, failure_code: 'DEBUGGER_PAUSED', delivery_status: 'not_delivered', dispatch_started: false, debugger: before })
+          let response: ToolCallResult
+          try { response = await handler(args) } catch (error) {
+            if (!debuggerSessions.paused(device.id)) throw error
+            response = wrapResponse({ success: false })
+          }
+          const pause = debuggerSessions.paused(device.id)
+          if (pause) {
+            const item = response.content.find(item => item.type === 'text')
+            if (item?.text) {
+              const payload = JSON.parse(item.text)
+              Object.assign(payload, { success: false, failure_code: 'DEBUGGER_PAUSED', retryable: false,
+                dispatch_started: guardDispatched(), delivery_status: payload.success ? 'delivered' : guardDispatched() ? 'unknown' : 'not_delivered',
+                verification: { status: 'blocked', reason: 'DEBUGGER_PAUSED' }, debugger: pause })
+              item.text = JSON.stringify(payload)
+            }
+          }
+          return addTiming(response)
+        }))
+      }
+      const response = await handler(args)
+      if (['capture_screenshot', 'get_ui_tree', 'get_screen_fingerprint', 'capture_debug_snapshot', 'get_logs', 'get_current_screen', 'read_log_stream'].includes(name) && args.platform !== 'ios') {
+        const item = response.content.find(item => item.type === 'text')
+        if (item?.text) {
+          try {
+            const payload = JSON.parse(item.text)
+            const device = payload.device ?? payload.evidence?.device
+            const id = device?.id ?? args.deviceId
+            const pause = id && device?.platform !== 'ios' ? debuggerSessions.paused(String(id)) : null
+            if (pause) item.text = JSON.stringify({ ...payload, debugger: pause })
+          } catch { /* Non-JSON observation */ }
+        }
+      }
+      return addTiming(response)
     } catch (error) {
+      if (error instanceof TraceError) return { ...wrapResponse({ error: { tool: name, code: error.code, message: error.message } }), isError: true }
       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.32.4'
+  version: '0.34.0'
 }
 
 export function createServer() {
@@ -46,9 +46,9 @@ export function createServer() {
     tools: toolDefinitions
   }))
 
-  server.setRequestHandler(CallToolRequestSchema, async (request: SchemaOutput<typeof CallToolRequestSchema>) => {
+  server.setRequestHandler(CallToolRequestSchema, async (request: SchemaOutput<typeof CallToolRequestSchema>, extra) => {
     const { name, arguments: args } = request.params
-    return handleToolCall(name, args as Record<string, unknown>)
+    return handleToolCall(name, args as Record<string, unknown>, extra.signal)
   })
 
   return server

package/src/server.ts

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import { debuggerSessions } from './debugger/sessions.js'
+import { systemTraces } from './observe/system-trace.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { createServer } from './server-core.js'
 import { getSystemStatus } from './system/index.js'
@@ -13,6 +15,28 @@ if (process.env.MOBILE_DEBUG_MCP_STARTUP_HEALTHCHECK === '1') {
 
 const transport = new StdioServerTransport()
 
+let shuttingDown = false
+async function shutdown() {
+  if (shuttingDown) return
+  shuttingDown = true
+  const deadline = setTimeout(() => { console.error('System trace shutdown cleanup timed out; owned device captures remain duration-bounded.'); process.exit(1) }, 10000)
+  let exitCode = 0
+  try {
+    const [remaining, debuggers] = await Promise.all([systemTraces.shutdown(), debuggerSessions.shutdown()])
+    if (debuggers.length) { exitCode = 1; console.error('Debugger shutdown cleanup incomplete', debuggers.map(s => s.cleanup)) }
+    if (remaining.length) {
+      exitCode = 1
+      console.error('System trace shutdown cleanup incomplete:', remaining.map(s => ({ trace_id: s.trace_id, device: s.device, cleanup: s.cleanup })))
+    }
+    await server.close()
+  } catch { exitCode = 1; console.error('Server shutdown cleanup failed.') }
+  finally { clearTimeout(deadline); process.exit(exitCode) }
+}
+server.onclose = () => { void shutdown() }
+process.stdin.on('end', () => { void shutdown() })
+process.on('SIGINT', () => { void shutdown() })
+process.on('SIGTERM', () => { void shutdown() })
+
 async function main() {
   await (server as any).connect(transport)
 }

package/src/system/index.ts

@@ -33,6 +33,7 @@ interface ToolEntry {
 }
 
 interface CapabilityEntry {
+  probeRequired?: string
   availability: boolean
   selectedProvider: string | null
   blockingFailure: DiagnosticFailure | null
@@ -41,7 +42,7 @@ interface CapabilityEntry {
 interface PlatformEntry {
   status: PlatformStatus
   tools: Record<string, ToolEntry>
-  providers: Record<string, { available: boolean; selected: boolean; tool: string | null }>
+  providers: Record<string, { available: boolean; selected: boolean; tool: string | null; probeRequired?: string }>
   capabilities: Record<string, CapabilityEntry>
   devices: Array<Record<string, unknown>>
   failures: DiagnosticFailure[]
@@ -289,7 +290,7 @@ function buildAndroidPlatform(android: Awaited<ReturnType<typeof checkAndroid>>,
     },
     providers: {
       adb: { available: adbAvailable, selected: true, tool: 'adb' },
-      jdwp: { available: adbAvailable && android.devices > 0, selected: false, tool: 'adb' }
+      jdwp: { available: false, selected: false, tool: 'adb', probeRequired: 'get_debugger_capabilities' }
     },
     capabilities: {
       device_discovery: {
@@ -323,9 +324,10 @@ function buildAndroidPlatform(android: Awaited<ReturnType<typeof checkAndroid>>,
         blockingFailure: logAvailable ? null : adbFailure ?? envFailure
       },
       debug: {
-        availability: adbAvailable && android.devices > 0,
-        selectedProvider: adbAvailable && android.devices > 0 ? 'JDWP' : null,
-        blockingFailure: adbAvailable && android.devices > 0 ? null : deviceFailure ?? adbFailure ?? envFailure
+        probeRequired: 'get_debugger_capabilities',
+        availability: false,
+        selectedProvider: null,
+        blockingFailure: deviceFailure ?? adbFailure ?? envFailure
       }
     },
     devices: deviceEntries,