mobile-debug-mcp 0.34.0 → 0.36.0

package/src/server/definitions/target.ts

@@ -0,0 +1,140 @@
+import type { Tool } from '@modelcontextprotocol/sdk/types.js'
+
+export const targetTools: Tool[] = [
+{
+    name: 'adjust_control',
+    description: `Purpose:
+Adjust a numeric control value with verification.
+
+This is the initial adjustable-control surface for slider-like controls and other controls that expose a numeric value or value_range.
+
+Inputs:
+- exactly one of selector or element_id
+- property (defaults to "value")
+- targetValue
+- tolerance (optional; discrete default is 0, continuous default is max(step / 2, 1% of range) when omitted)
+- maxAttempts (optional; defaults to 5)
+- platform/deviceId (optional)
+
+Output Structure:
+- action_id, timestamp (ISO 8601), action_type
+- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
+- source_module: runtime source of the action envelope
+- target_state / actual_state / within_tolerance / converged / attempts / adjustment_mode
+- target.selector = original selector or element handle
+- success = true when the control converges within tolerance
+
+Verification Guidance:
+- Prefer direct platform adjustment when the runtime exposes it; then verified increment/decrement actions; use coordinate fallback only as degraded mode
+- Use expect_state for the control value readback
+- Do not use derived semantic metadata as proof of success
+
+Failure Handling:
+- ELEMENT_NOT_FOUND → re-resolve the control
+- ELEMENT_NOT_INTERACTABLE → the control cannot be adjusted through the current runtime
+- CONTROL_CONVERGENCE_FAILED → the control did not converge within bounded retries or the requested value is out of range
+- UNKNOWN → capture a snapshot and stop`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        selector: {
+          type: 'object',
+          properties: {
+            text: { type: 'string' },
+            resource_id: { type: 'string' },
+            accessibility_id: { type: 'string' },
+            contains: { type: 'boolean', default: false }
+          }
+        },
+        element_id: { type: 'string', description: 'Optional previously resolved element identifier.' },
+        property: { type: 'string', description: 'Readable numeric state property to adjust.', default: 'value' },
+        targetValue: { type: 'number', description: 'Target numeric value.' },
+        tolerance: { type: 'number', description: 'Accepted numeric tolerance around the target value. Defaults are derived from the readable control domain.' },
+        maxAttempts: { type: 'number', description: 'Maximum adjustment attempts.', default: 5 },
+        platform: { type: 'string', enum: ['android', 'ios'], description: 'Optional platform override' },
+        deviceId: { type: 'string', description: 'Optional device serial/udid' }
+      },
+      required: ['targetValue'],
+      oneOf: [
+        { required: ['selector'] },
+        { required: ['element_id'] }
+      ]
+    }
+  },
+{
+    name: 'find_element',
+    description: `Find a UI element by semantic query (text, content-desc, resource-id, class).
+
+Returns the best match plus resolution metadata when available, including confidence, selection reason, and fallback alternates.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Search query (text or label)' },
+        exact: { type: 'boolean', description: 'Require exact match (true/false)', default: false },
+        timeoutMs: { type: 'number', description: 'Timeout in ms to keep searching', default: 3000 },
+        platform: { type: 'string', enum: ['android', 'ios'], description: 'Optional platform override' },
+        deviceId: { type: 'string', description: 'Optional device serial/udid' }
+      },
+      required: ['query']
+    }
+  },
+{
+    name: 'tap_element',
+    description: `Purpose:
+Tap a previously resolved UI element using its elementId.
+
+Inputs:
+- elementId: a resolved UI element identifier returned by wait_for_ui
+
+Output Structure:
+- action_id: unique timestamp-based action identifier
+- timestamp: ISO 8601 timestamp for the action attempt
+- action_type: "tap_element"
+- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
+- source_module: runtime source of the action envelope
+- target.selector: original target handle ({ elementId })
+- target.resolved: minimal resolved element info used for the tap
+- success: true when the tap was dispatched
+- failure_code: present when success=false
+- retryable: present when failure_code exists
+- ui_fingerprint_before/ui_fingerprint_after: optional fingerprints captured around the action
+
+Recommended Usage:
+1. Resolve the target with wait_for_ui or another deterministic resolver
+2. Call tap_element
+3. If needed, wait for transition using wait_for_*
+4. Verify outcome using expect_*
+   - use expect_screen when navigation is expected
+   - use expect_element_visible when the UI change is local
+5. If verification fails, inspect failure_code and follow the retry strategy below
+
+Verification Guidance:
+- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT
+- Prefer expect_screen for navigation or modal transitions
+- Prefer expect_element_visible when the tap should reveal or update a specific element
+- wait_for_* may be used for resolution and synchronization, but not as the final verification step when an applicable expect_* tool exists
+- Do not treat tap_element.success as outcome success; it only means the tap was executed
+
+Failure Handling:
+- STALE_REFERENCE → re-resolve the element, then retry
+- ELEMENT_NOT_INTERACTABLE → wait or refine the target, then retry
+- UNKNOWN → capture a snapshot and stop
+
+This tool reports execution success only. Verification must be done with a separate expect_* tool.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        elementId: {
+          type: 'string',
+          description: 'A unique element identifier returned by wait_for_ui'
+        },
+        selector: { type: 'object', properties: { text: { type: 'string' }, resource_id: { type: 'string' }, accessibility_id: { type: 'string' }, contains: { type: 'boolean' } } },
+        waitFor: { type: 'object', properties: { condition: { type: 'string', enum: ['exists', 'visible', 'clickable'] }, timeoutMs: { type: 'number', minimum: 100, maximum: 10000 }, pollIntervalMs: { type: 'number', minimum: 50, maximum: 1000 }, match: { type: 'object', properties: { index: { type: 'number' } } } } },
+        platform: { type: 'string', enum: ['android', 'ios'] },
+        deviceId: { type: 'string' },
+        verificationMode: { type: 'string', enum: ['none', 'light', 'full'], default: 'full' },
+        responseMode: { type: 'string', enum: ['compact', 'debug'], default: 'debug' }
+      }
+    }
+  }
+]

package/src/server/definitions/wait.ts

@@ -0,0 +1,107 @@
+import type { Tool } from '@modelcontextprotocol/sdk/types.js'
+
+export const waitTools: Tool[] = [
+{
+    name: 'wait_for_screen_change',
+    description: `Purpose:
+Detect that a screen transition has occurred by waiting for the current fingerprint to differ from a previous fingerprint.
+
+Capabilities:
+- Synchronization for uncertain navigation timing
+- Detection that something changed on screen
+
+Constraints:
+- Does not verify correctness of the resulting state
+- Must not be used alone to confirm action success when an applicable expect_* tool exists
+- For backend/API activity without a visible UI change, pass the runtime action_type into classify_action_outcome and collect network evidence only if the result remains ambiguous
+
+Recommended Usage:
+1. Capture or define the expected outcome
+2. Call an action tool
+3. Use wait_for_screen_change when transition timing is uncertain
+4. Follow with expect_screen when the expected destination is known`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        platform: { type: 'string', enum: ['android', 'ios'], description: 'Optional platform override (android|ios)' },
+        previousFingerprint: { type: 'string', description: 'The fingerprint to compare against (required)' },
+        timeoutMs: { type: 'number', description: 'Timeout in ms to wait for change (default 5000)', default: 5000 },
+        pollIntervalMs: { type: 'number', description: 'Polling interval in ms (default 300)', default: 300 },
+        deviceId: { type: 'string', description: 'Optional device id/udid to target' }
+      },
+      required: ['previousFingerprint']
+    }
+  },
+{
+    name: 'wait_for_ui_change',
+    description: `Purpose:
+Wait for a non-navigation UI mutation or in-place update to become stable.
+
+Inputs:
+- expected_change (optional): hierarchy_diff, text_change, or state_change
+- timeout_ms (optional)
+- stability_window_ms (optional)
+- scope (optional): screen or subtree
+- target (optional): element_id when scope=subtree
+
+Guidance:
+- Prefer wait_for_screen_change for navigation transitions.
+- Prefer wait_for_ui_change for in-place mutations and non-navigation updates.
+- Use the returned snapshot_revision as the observed synchronization point when available.
+- Scoped waits return scope-aware stability metadata and a lightweight change summary.
+
+Failure Handling:
+- TIMEOUT means the UI did not change in a stable way within the allotted time.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        platform: { type: 'string', enum: ['android', 'ios'], description: 'Optional platform override (android|ios)' },
+        deviceId: { type: 'string', description: 'Optional device id/udid to target' },
+        expected_change: { type: 'string', enum: ['hierarchy_diff', 'text_change', 'state_change'], description: 'Optional type of UI change to wait for' },
+        scope: { type: 'string', enum: ['screen', 'subtree'], default: 'screen', description: 'Synchronization scope for the wait' },
+        target: { type: 'string', description: 'Target element_id when scope is subtree' },
+        timeout_ms: { type: 'number', description: 'Timeout in ms to wait for change (default 60000)', default: 60000 },
+        stability_window_ms: { type: 'number', description: 'How long the change must remain stable before success (default 300)', default: 300 }
+      }
+    }
+  },
+{
+    name: 'wait_for_ui',
+    description: `Purpose:
+Resolve elements and/or detect that a UI transition or availability condition has occurred.
+
+Capabilities:
+- Deterministic element resolution
+- Synchronization when element timing or availability is uncertain
+
+Constraints:
+- Does not verify correctness of the resulting state
+- Must not be used alone to confirm action success when an applicable expect_* tool exists
+
+Recommended Usage:
+1. Use wait_for_ui to resolve an element before acting or to wait for UI readiness
+2. Call the action tool
+3. If the expected outcome is known, follow with expect_* as final verification`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        selector: {
+          type: 'object',
+          properties: {
+            text: { type: 'string' },
+            resource_id: { type: 'string' },
+            accessibility_id: { type: 'string' },
+            contains: { type: 'boolean', description: 'When true, perform substring matching', default: false }
+          }
+        },
+        condition: { type: 'string', enum: ['exists', 'not_exists', 'visible', 'clickable'], default: 'exists' },
+        timeout_ms: { type: 'number', default: 60000 },
+        poll_interval_ms: { type: 'number', default: 300 },
+        match: { type: 'object', properties: { index: { type: 'number' } } },
+        retry: { type: 'object', properties: { max_attempts: { type: 'number', default: 1 }, backoff_ms: { type: 'number', default: 0 } } },
+        platform: { type: 'string', enum: ['android', 'ios'], description: 'Optional platform override' },
+        deviceId: { type: 'string', description: 'Optional device serial/udid' }
+      }
+    }
+  }
+]

package/src/server/handlers/action-execution.ts

@@ -0,0 +1,164 @@
+import type { ToolPayload } from './payload.js'
+import { payloadOf } from './payload.js'
+import { correlatedHandler } from './correlation.js'
+import { interactionControls } from '../../contracts/execution-controls.js'
+import { currentEvidenceActionId, markEvidenceVerification } from '../../observe/evidence.js'
+import { measure, withTiming } from '../../utils/timing.js'
+import { randomUUID } from 'node:crypto'
+import { runWithBudget } from '../../utils/operation-budget.js'
+import { validateExpectedState } from '../schemas/condition-schema.js'
+import { conditionFailureCode, createConditionalAction, withConditionalAction } from '../../interact/conditional-action.js'
+import { resolveTargetDevice, withResolvedDevice } from '../../utils/resolve-device.js'
+
+import { ToolsObserve } from '../../observe/index.js'
+import { recordObservationEvent, withObservationContext } from '../../observe/performance-metrics.js'
+import {
+  buildActionExecutionResult,
+  ToolCallArgs,
+  ToolHandler,
+  wrapResponse,
+  wrapToolError
+} from '../common.js'
+import type { PlatformArg, VerificationMode } from './handler-types.js'
+
+export function compactAction(result: ToolPayload, 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 createAction(type: string, args: ToolCallArgs, timing: Record<string, number>) {
+  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)
+  const unbounded = args._journey !== true && controls.verificationMode === 'full' && controls.responseMode === 'debug' && controls.actionTimeoutMs === undefined
+  return {
+    type, args, timing, started, controls, condition, budgetMs, unbounded,
+    result: {} as ToolPayload, dispatchStarted: false, blocked: false,
+    delta: undefined as unknown, observationAvailable: false
+  }
+}
+type Action = ReturnType<typeof createAction>
+async function dispatchAction(s: Action, execute: ToolHandler) {
+  const { type, args, controls, condition, budgetMs } = s
+  const dispatchWithBudget = (timeoutMs: number) => runWithBudget(timeoutMs, async (budget) => {
+    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 { s.dispatchStarted = budget.dispatchStarted }
+  })
+  try {
+    // Omitted controls retain the existing adapter budgets.
+    s.result = s.unbounded
+      ? await dispatchWithBudget(Infinity) : await dispatchWithBudget(budgetMs)
+    if (s.result.success) s.dispatchStarted = true
+  } catch (error) {
+    if (!condition && controls.verificationMode === 'full' && controls.responseMode === 'debug' && controls.actionTimeoutMs === undefined && !/TIMEOUT|timed out/i.test(String(error))) return wrapToolError(type, error)
+    s.result = { success: false, failure_code: /TIMEOUT|timed out/i.test(String(error)) ? 'ACTION_TIMEOUT' : 'UNKNOWN', error: String(error) }
+  }
+}
+function rejectCondition(s: Action) {
+  const { condition, type } = s
+  s.blocked = !!condition && ['mismatch', 'unavailable'].includes(condition.result.status)
+  if (s.blocked && condition) {
+    s.dispatchStarted = false
+    s.result = buildActionExecutionResult({
+      actionType: type, sourceModule: 'server', device: condition.result.observed?.device,
+      selector: s.result?.target?.selector ?? null, resolved: s.result?.target?.resolved,
+      success: false, uiFingerprintBefore: s.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 } }]
+    })
+  }
+}
+function normalizeAction(s: Action) {
+  const { type, args, timing, controls } = s
+  rejectCondition(s)
+  if (s.result.failure_code === 'TIMEOUT' || /ACTION_TIMEOUT|timeout/i.test(String(s.result.error ?? s.result.reason ?? s.result.details?.error ?? ''))) s.result.failure_code = 'ACTION_TIMEOUT'
+  if (s.result.failure_code === 'ACTION_TIMEOUT') s.result.retryable = !s.dispatchStarted
+  if (!s.result.success && typeof s.result.retryable !== 'boolean') s.result.retryable = !s.dispatchStarted
+  s.result.action_id ??= currentEvidenceActionId() ?? randomUUID()
+  s.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: s.dispatchStarted
+  })
+}
+async function verifyAction(s: Action) {
+  const { args, controls } = s
+  if (s.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) ?? (s.result.device?.platform as PlatformArg | undefined), deviceId: (args.deviceId as string | undefined) ?? s.result.device?.id })))).catch(() => null)
+    markEvidenceVerification()
+    s.observationAvailable = !!tree && !tree.error
+    recordObservationEvent({
+      verification_budget_ms: controls.verificationTimeoutMs,
+      verification_elapsed_ms: performance.now() - verificationStarted,
+      verification_outcome: s.observationAvailable ? 'observed' : 'unavailable',
+      verification_budget_expired: !s.observationAvailable && performance.now() - verificationStarted >= controls.verificationTimeoutMs
+    })
+    if (s.observationAvailable && tree?.device) s.delta = ToolsObserve.getLatestStateDelta(tree.device.platform as PlatformArg, tree.device.id) ?? undefined
+  }
+  if (!s.blocked && controls.verificationMode === 'full' && s.dispatchStarted) markEvidenceVerification()
+}
+function actionResponse(s: Action) {
+  const { timing, started, controls, condition, budgetMs } = s
+  const compact = compactAction(s.result, controls.verificationMode, s.dispatchStarted, s.delta, performance.now() - started)
+  if (s.blocked) compact.verification.status = 'not_requested'
+  if (s.result.success && controls.verificationMode === 'light' && !s.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: !!s.delta } : {}),
+    ...(s.result.success && controls.verificationMode === 'light' && !s.observationAvailable ? { verification_diagnostic: { code: 'VERIFICATION_UNAVAILABLE', retryable: true } } : {})
+  }
+  return wrapResponse(controls.responseMode === 'compact' ? evidence : {
+    ...s.result, ...evidence, timing: { ...timing, total_ms: performance.now() - started },
+    effective_controls: { ...controls, actionTimeoutMs: s.unbounded ? null : budgetMs, timeout_bound: !(s.unbounded) }
+  }, controls.responseMode === 'debug')
+}
+
+export function actionHandler(type: string, execute: ToolHandler): ToolHandler {
+  return correlatedHandler(type, async args => {
+    const timing: Record<string, number> = {}
+    return withTiming(timing, async () => {
+      const state = createAction(type, args, timing)
+      const error = await dispatchAction(state, execute)
+      if (error) return error
+      normalizeAction(state)
+      await verifyAction(state)
+      return actionResponse(state)
+    })
+  }, true)
+}
+export { interactionControls, correlatedHandler, payloadOf }

package/src/server/handlers/correlation.ts

@@ -0,0 +1,20 @@
+import { TraceError } from '../../observe/system-trace.js'
+import { withEvidence, validateActionRef } from '../../observe/evidence.js'
+import { wrapResponse, wrapToolError, type ToolHandler } from '../common.js'
+export 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
+  }
+}
+

package/src/server/handlers/debugger-handlers.ts

@@ -0,0 +1,58 @@
+import { iosCapabilities } from '../../debugger/ios-worker.js'
+import { debuggerResponse } from './debugger-response.js'
+import { classify, type DebuggerDiagnostic } from '../../debugger/diagnostics.js'
+import { debuggerContracts } from '../schemas/debugger-schema.js'
+import { debuggerSessions, iosDebuggerSessions, debuggerCapabilities } from '../../debugger/sessions.js'
+import { DebuggerError, withDebuggerBudget } from '../../debugger/worker.js'
+import { wrapResponse, type ToolCallArgs } from '../common.js'
+function failure(code: string, summary: Record<string, unknown> = {}, diagnostic?: DebuggerDiagnostic, command = '', mode: 'compact' | 'debug' = 'debug') {
+  return {
+    ...wrapResponse(debuggerResponse(command, mode, {
+      debug_session_id: null, device: null, target: null, state: null,
+      captured_at_ms: Date.now(), capabilities: debuggerCapabilities, limitations: [], cleanup: null,
+      ...summary, success: false, error: { code, message: code, retryable: false, ...(diagnostic ? { diagnostic } : {}) }
+    })), isError: true
+  }
+}
+export async function handleDebugger(name: string, args: ToolCallArgs, signal?: AbortSignal) {
+  const parsed = debuggerContracts[name].schema.safeParse(args)
+  if (!parsed.success) return failure('INVALID_ARGUMENT')
+  const { responseMode, ...input } = parsed.data
+  const a = input as { platform?: 'android' | 'ios'; timeoutMs: number; deviceId?: string; appId?: string; processId?: number; debugSessionId?: string }
+  const command = debuggerContracts[name].command
+  const sessions = selectSessions(a)
+  try {
+    if (signal?.aborted) throw new DebuggerError('DEBUGGER_CANCELLED')
+    const result = await withDebuggerBudget(a.timeoutMs, signal, async () => command === 'capabilities' ? await sessions.capabilities(a.deviceId!, a.appId!, a.processId) :
+      command === 'attach' ? await sessions.attach(a.deviceId!, a.appId!, a.processId, a.timeoutMs) :
+        await sessions.command(a.debugSessionId!, command, { ...a, signal: command === 'events' ? signal : undefined }, a.timeoutMs))
+    if (signal?.aborted && command === 'capabilities') throw new DebuggerError('DEBUGGER_CANCELLED')
+    const payload = sessions === iosDebuggerSessions ? iosDiagnostics(result) : result
+    return { ...wrapResponse(debuggerResponse(command, responseMode, payload)), ...(!result.success ? { isError: true } : {}) }
+  } catch (e) {
+    const error = classify(e, 'unknown', 'DEBUGGER_WORKER_FAILED')
+    const code = error.code
+    let summary: Partial<ReturnType<typeof debuggerSessions.summary>> = {}
+    if (a.debugSessionId) { try { summary = sessions.summary(a.debugSessionId) } catch { /* Unknown session */ } }
+    const response = failure(code, {
+      ...(sessions === iosDebuggerSessions ? { capabilities: iosCapabilities } : {}),
+      debug_session_id: a.debugSessionId ?? null,
+      device: a.deviceId ? { platform: a.platform ?? 'android', id: a.deviceId } : null, ...summary
+    }, code === 'DEBUGGER_CLEANUP_FAILED' ? summary.error?.diagnostic : error.diagnostic, command, responseMode)
+    if (sessions === iosDebuggerSessions) response.content[0].text = JSON.stringify(iosDiagnostics(JSON.parse(response.content[0].text)))
+    return response
+  }
+}
+
+function selectSessions(a: { platform?: string; debugSessionId?: string }) {
+  return a.platform === 'ios' || (a.debugSessionId && iosDebuggerSessions.owns(a.debugSessionId)) ? iosDebuggerSessions : debuggerSessions
+}
+function iosRecovery(d: DebuggerDiagnostic) {
+  return { ...d, recovery: d.recovery.replace('JDK 17+ availability, including java, javac and jdk.jdi.', 'Xcode and its Swift-enabled LLDB/Python availability.').replace('JDK compiler and worker source/cache', 'LLDB worker source').replace('Java worker', 'LLDB worker').replace('ADB server', 'simulator') }
+}
+function iosDiagnostics<T extends Record<string, unknown>>(value: T) {
+  const result = { ...value }
+  const error = value.error as { diagnostic?: DebuggerDiagnostic } | undefined
+  return { ...result, ...(error?.diagnostic ? { error: { ...error, diagnostic: iosRecovery(error.diagnostic) } } : {}),
+    ...(Array.isArray(value.diagnostics) ? { diagnostics: (value.diagnostics as DebuggerDiagnostic[]).map(iosRecovery) } : {}) }
+}

package/src/server/handlers/debugger-response.ts

@@ -0,0 +1,7 @@
+/** Omit only repeated target metadata; preserve all execution and failure evidence. */
+export function debuggerResponse(command: string, mode: 'compact' | 'debug', payload: Record<string, unknown>) {
+  if (mode !== 'compact' || ['capabilities', 'attach', 'state'].includes(command) || payload.debug_session_id == null) return payload
+  const result = { ...payload }
+  for (const field of ['device', 'target', 'capabilities']) delete result[field]
+  return result
+}

package/src/server/handlers/diagnostic.ts

@@ -0,0 +1,86 @@
+import type { IosTemplate } from '../../observe/ios-trace/capabilities.js'
+import { systemTraces, TraceError } from '../../observe/system-trace.js'
+import { traceTargetSchema, traceStartSchema, traceControlSchema } from '../schemas/system-trace-schema.js'
+import { resolveTargetDevice } from '../../utils/resolve-device.js'
+
+import { ToolsManage } from '../../manage/index.js'
+import { classifyActionOutcome } from '../../interact/classify.js'
+import { ToolsNetwork } from '../../observe/network/index.js'
+import { getSystemStatus } from '../../system/index.js'
+import {
+  getArrayArg,
+  getBooleanArg,
+  getStringArg,
+  requireBooleanArg,
+  requireStringArg,
+  ToolCallArgs,
+  wrapResponse
+} from '../common.js'
+import type { PlatformArg, ClassifyNetworkRequestArg } from './handler-types.js'
+
+export async function handleListDevices(args: ToolCallArgs) {
+  const platform = getStringArg(args, 'platform') as PlatformArg | undefined
+  const appId = getStringArg(args, 'appId')
+  const res = await ToolsManage.listDevicesHandler({ platform, appId })
+  return wrapResponse(res)
+}
+
+export async function handleGetSystemStatus() {
+  const result = await getSystemStatus()
+  return wrapResponse(result)
+}
+
+export function handleClassifyActionOutcome(args: ToolCallArgs) {
+  const uiChanged = requireBooleanArg(args, 'uiChanged')
+  const expectedElementVisible = getBooleanArg(args, 'expectedElementVisible')
+  const actionType = getStringArg(args, 'actionType')
+  const networkRequests = getArrayArg<ClassifyNetworkRequestArg>(args, 'networkRequests')
+  const hasLogErrors = getBooleanArg(args, 'hasLogErrors')
+  const result = classifyActionOutcome({
+    uiChanged,
+    expectedElementVisible: expectedElementVisible ?? null,
+    actionType: actionType ?? null,
+    networkRequests: networkRequests ?? null,
+    hasLogErrors: hasLogErrors ?? null
+  })
+  return Promise.resolve(wrapResponse(result))
+}
+
+export async function handleGetNetworkActivity(args: ToolCallArgs) {
+  const platform = requireStringArg(args, 'platform') as PlatformArg
+  const deviceId = getStringArg(args, 'deviceId')
+  const result = await ToolsNetwork.getNetworkActivity({ platform, deviceId })
+  return wrapResponse(result)
+}
+
+export 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; appId?: string; template?: IosTemplate }
+    if (target.platform === 'android' && (target.appId !== undefined || target.template !== undefined)) throw new TraceError('INVALID_ARGUMENT')
+    if (target.platform === 'ios') {
+      return handleIosTrace(name, target)
+    }
+    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 } : {}) }
+}
+
+async function handleIosTrace(name: string, target: { deviceId?: string; appId?: string; durationMs?: number; template?: IosTemplate }) {
+  if (!target.deviceId || (name === 'start_system_trace' && !target.appId)) throw new TraceError('INVALID_ARGUMENT')
+  if (name === 'get_system_trace_capabilities') return wrapResponse(await systemTraces.iosCapabilities(target.deviceId, target.appId, target.template))
+  const result = await systemTraces.start(target.deviceId, target.durationMs, { appId: target.appId!, template: target.template })
+  return { ...wrapResponse(result), ...(result.state === 'failed' ? { isError: true } : {}) }
+}

package/src/server/handlers/handler-types.ts

@@ -0,0 +1,7 @@
+export type PlatformArg = 'android' | 'ios'
+export type ProjectTypeArg = 'native' | 'kmp' | 'react-native' | 'flutter'
+export type WaitForUiMatchArg = { index?: number }
+export type WaitForUiRetryArg = { max_attempts?: number, backoff_ms?: number }
+export type { ScrollSelector as ScrollSelectorArg } from '../../contracts/target.js'
+export type ClassifyNetworkRequestArg = { endpoint: string, status: 'success' | 'failure' | 'retryable' }
+export type { VerificationMode, ResponseMode } from '../../contracts/execution-controls.js'