mobile-debug-mcp 0.35.0 → 0.36.0

package/src/observe/system-trace.ts

@@ -1,3 +1,4 @@
+import { SystemTraceRouter } from './system-trace-router.js'
 import { randomUUID } from 'node:crypto'
 import { promises as fs } from 'node:fs'
 import os from 'node:os'
@@ -6,9 +7,8 @@ import { AndroidTraceNative, TRACE_MAX_BYTES, type TraceCapabilities, type Trace
 import { evidenceSessionId } from './evidence.js'
 import { runWithBudget, remainingBudget } from '../utils/operation-budget.js'
 
-export class TraceError extends Error {
-  constructor(public code: string) { super(code) }
-}
+export { TraceError } from './system-trace-error.js'
+import { TraceError } from './system-trace-error.js'
 type State = 'starting' | 'recording' | 'stopping' | 'completed' | 'cancelled' | 'failed'
 type Completion = 'requested' | 'duration_limit' | 'cancelled' | 'error'
 export interface TraceResult {
@@ -224,4 +224,4 @@ export class SystemTraceSessions {
     })
   }
 }
-export const systemTraces = new SystemTraceSessions()
+export const systemTraces = new SystemTraceRouter(new SystemTraceSessions())

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

@@ -1,7 +1,8 @@
+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, debuggerCapabilities } from '../../debugger/sessions.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') {
@@ -17,23 +18,41 @@ export async function handleDebugger(name: string, args: ToolCallArgs, signal?:
   const parsed = debuggerContracts[name].schema.safeParse(args)
   if (!parsed.success) return failure('INVALID_ARGUMENT')
   const { responseMode, ...input } = parsed.data
-  const a = input as { timeoutMs: number; deviceId?: string; appId?: string; processId?: number; debugSessionId?: string }
+  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 debuggerSessions.capabilities(a.deviceId!, a.appId!, a.processId) :
-      command === 'attach' ? await debuggerSessions.attach(a.deviceId!, a.appId!, a.processId, a.timeoutMs) :
-        await debuggerSessions.command(a.debugSessionId!, command, { ...a, signal: command === 'events' ? signal : undefined }, a.timeoutMs))
+    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')
-    return { ...wrapResponse(debuggerResponse(command, responseMode, result)), ...(!result.success ? { isError: true } : {}) }
+    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 = debuggerSessions.summary(a.debugSessionId) } catch { /* Unknown session */ } }
-    return failure(code, {
+    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: 'android', id: a.deviceId } : null, ...summary
+      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/diagnostic.ts

@@ -1,3 +1,4 @@
+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'
@@ -57,10 +58,10 @@ export async function handleSystemTrace(name: string, args: ToolCallArgs) {
   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'] })
+    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) }
@@ -77,3 +78,9 @@ export async function handleSystemTrace(name: string, args: ToolCallArgs) {
   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/tool-handlers.ts

@@ -1,7 +1,8 @@
+import { ToolsInteract } from '../../interact/index.js'
 import type { DeviceInfo } from '../../types.js'
 import { handleDebugger } from './debugger-handlers.js'
 import { debuggerContracts } from '../schemas/debugger-schema.js'
-import { debuggerSessions } from '../../debugger/sessions.js'
+import { debuggerSessions, iosDebuggerSessions } from '../../debugger/sessions.js'
 import { withDebuggerGuard, guardDispatched } from '../../debugger/guard.js'
 import { TraceError } from '../../observe/system-trace.js'
 import { systemTraceTools } from '../schemas/system-trace-schema.js'
@@ -81,16 +82,25 @@ for (const name of ['capture_screenshot', 'get_ui_tree', 'get_screen_fingerprint
   toolHandlers[name] = correlatedHandler(name, toolHandlers[name], name === 'adjust_control', name === 'run_journey')
 }
 
+function resolveGuardDevice(name: string, args: ToolCallArgs) {
+  const platform = args.platform as 'android' | 'ios' | undefined
+  const deviceId = args.deviceId as string | undefined
+  const stored = name === 'tap_element' && typeof args.elementId === 'string'
+    ? ToolsInteract.getResolvedElementTarget(args.elementId, platform, deviceId) : null
+  return resolveTargetDevice(stored ?? { platform: platform === 'ios' ? 'ios' : 'android', deviceId })
+}
+
 async function dispatchGuarded(device: DeviceInfo, args: ToolCallArgs, handler: ToolHandler, addTiming: (response: ToolCallResult) => ToolCallResult) {
-  return withResolvedDevice(device, () => withDebuggerGuard('android', device.id, async () => {
-    const before = debuggerSessions.paused(device.id)
+  const sessions = device.platform === 'ios' ? iosDebuggerSessions : debuggerSessions
+  return withResolvedDevice(device, () => withDebuggerGuard(device.platform, device.id, async () => {
+    const before = sessions.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
+      if (!sessions.paused(device.id)) throw error
       response = wrapResponse({ success: false })
     }
-    const pause = debuggerSessions.paused(device.id)
+    const pause = sessions.paused(device.id)
     if (pause) {
       const item = response.content.find(item => item.type === 'text')
       if (item?.text) {
@@ -106,14 +116,15 @@ async function dispatchGuarded(device: DeviceInfo, args: ToolCallArgs, handler:
 }
 
 function attachPausedObservation(name: string, args: ToolCallArgs, response: ToolCallResult) {
-  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') {
+  if (['capture_screenshot', 'get_ui_tree', 'get_screen_fingerprint', 'capture_debug_snapshot', 'get_logs', 'get_current_screen', 'read_log_stream'].includes(name)) {
     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
+        const sessions = (device?.platform ?? args.platform) === 'ios' ? iosDebuggerSessions : debuggerSessions
+        const pause = id ? sessions.paused(String(id)) : null
         if (pause) item.text = JSON.stringify({ ...payload, debugger: pause })
       } catch { /* Non-JSON observation */ }
     }
@@ -143,8 +154,8 @@ export async function handleToolCall(name: string, args: ToolCallArgs = {}, sign
     try {
       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 })
+      if (guarded && (debuggerSessions.hasActiveSessions() || iosDebuggerSessions.hasActiveSessions())) {
+        const device = await resolveGuardDevice(name, args)
         return dispatchGuarded(device, args, handler, addTiming)
       }
       const response = await handler(args)

package/src/server/schemas/debugger-schema.ts

@@ -2,21 +2,22 @@ import { z } from 'zod'
 const text = z.string().min(1).max(512)
 const integer = z.number().int().safe().positive()
 const timeout = z.number().int().min(100).max(30000)
-const target = { platform: z.literal('android'), deviceId: text, appId: text.regex(/^[A-Za-z][\w]*(?:\.[A-Za-z][\w]*)+$/), processId: integer.optional() }
+const iosUdid = /^[A-Fa-f0-9]{8}(?:-[A-Fa-f0-9]{4}){3}-[A-Fa-f0-9]{12}$/
+const target = { platform: z.enum(['android', 'ios']), deviceId: text, appId: text.regex(/^[A-Za-z][\w-]*(?:\.[A-Za-z][\w-]*)+$/), processId: integer.optional() }
 const session = { debugSessionId: text }
 const stop = { ...session, stopId: text }
 const specs = {
-  get_debugger_capabilities: { fields: target, command: 'capabilities', description: 'Probe optional Android JDK/JDWP prerequisites and matching running debuggable processes; does not attach.' },
-  attach_debugger: { fields: target, command: 'attach', description: 'Attach an owned Android JDI session. Requires an explicit device and debuggable app; choose processId when ambiguous. Stops suspend all app threads. Auto-detach: 60s paused, 5m idle, 30m total.' },
+  get_debugger_capabilities: { fields: target, command: 'capabilities', description: 'Probe optional platform debugger prerequisites and matching running debuggable processes; does not attach.' },
+  attach_debugger: { fields: target, command: 'attach', description: 'Attach an owned Android JDI or iOS simulator LLDB session. Requires an explicit device and debuggable app; choose processId when ambiguous. Stops suspend all app threads. Auto-detach: 60s paused, 5m idle, 30m total.' },
   get_debugger_state: { fields: session, command: 'state', description: 'Read debugger state, current stop and breakpoint/cleanup status.' },
-  set_debugger_breakpoint: { fields: { ...session, className: text.regex(/^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/), line: integer }, command: 'set', description: 'Set an exact binary-class and executable-source-line breakpoint; unloaded classes remain pending. No silent line relocation.' },
+  set_debugger_breakpoint: { fields: { ...session, className: text.regex(/^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/).optional(), sourceFile: text.regex(/^\/[^\0\r\n]+$/).optional(), line: integer }, command: 'set', description: 'Set an exact source breakpoint: Android className or iOS absolute sourceFile (exactly one), plus line; unloaded classes/images remain pending. No silent line relocation.' },
   remove_debugger_breakpoint: { fields: { ...session, breakpointId: text }, command: 'remove', description: 'Remove an owned breakpoint; repeated removal succeeds.' },
   wait_for_debugger_event: { fields: { ...session, afterSequence: z.number().int().safe().min(0).optional() }, command: 'events', description: 'Wait for bounded debugger events after a sequence cursor. Empty timeout does not affect execution; overflow is explicit.' },
   get_debugger_stack: { fields: { ...stop, threadId: text, offset: z.number().int().min(0).max(999).optional(), limit: z.number().int().min(1).max(100).optional() }, command: 'stack', description: 'Read bounded stack frames for a stopped thread; IDs expire on resume.' },
-  get_debugger_locals: { fields: { ...stop, frameId: text }, command: 'locals', description: 'Read at most 100 shallow locals. Sensitive values returned only on request; strings truncate at 256 characters. No evaluation or field traversal.' },
+  get_debugger_locals: { fields: { ...stop, frameId: text }, command: 'locals', description: 'Read at most 100 shallow locals. Sensitive values returned only on request; strings truncate at 256 characters; iOS aggregates return type summaries. No evaluation or field traversal.' },
   step_debugger: { fields: { ...stop, threadId: text, kind: z.enum(['into', 'over', 'out']) }, command: 'step', description: 'Acknowledge one-shot line stepping and resume. Wait for a subsequent stop event separately.' },
   resume_debugger: { fields: stop, command: 'resume', description: 'Resume owned debugger suspension and immediately expire stopped references.' },
-  detach_debugger: { fields: session, command: 'detach', description: 'Dispose the owned debugger connection, release owned suspension and remove its exact forward. Idempotent; retries incomplete cleanup.' }
+  detach_debugger: { fields: session, command: 'detach', description: 'Dispose the owned debugger connection, release owned suspension and remove its owned transport. Idempotent; retries incomplete cleanup.' }
 }
 // Derive JSON schemas and runtime validation from the same small Zod field vocabulary.
 function jsonField(schema: z.ZodType): Record<string, unknown> {
@@ -31,12 +32,14 @@ function jsonField(schema: z.ZodType): Record<string, unknown> {
   throw new Error('Unsupported debugger field schema')
 }
 export const debuggerContracts = Object.fromEntries(Object.entries(specs).map(([name, spec]) => [name, {
-  ...spec, schema: z.object({ ...spec.fields, responseMode: z.enum(['compact', 'debug']).default('debug'), timeoutMs: timeout.default(name === 'wait_for_debugger_event' ? 1000 : 10000) }).strict()
+  ...spec, schema: z.object({ ...spec.fields, responseMode: z.enum(['compact', 'debug']).default('debug'), timeoutMs: timeout.default(name === 'wait_for_debugger_event' ? 1000 : 10000) }).strict().refine(a => name !== 'set_debugger_breakpoint' || (('className' in a && a.className !== undefined) !== ('sourceFile' in a && a.sourceFile !== undefined)), { message: 'Exactly one breakpoint source selector is required' }).refine(a => !('platform' in a) || a.platform !== 'ios' || ('deviceId' in a && typeof a.deviceId === 'string' && iosUdid.test(a.deviceId)), { message: 'iOS requires an explicit simulator UDID' })
 }]))
 export const debuggerTools = Object.entries(debuggerContracts).map(([name, spec]) => ({
   name, description: spec.description,
   inputSchema: {
     type: 'object' as const, additionalProperties: false,
+    ...(['get_debugger_capabilities', 'attach_debugger'].includes(name) ? { allOf: [{ if: { properties: { platform: { const: 'ios' } } }, then: { properties: { deviceId: { pattern: iosUdid.source } } } }] } : {}),
+    ...(name === 'set_debugger_breakpoint' ? { oneOf: [{ required: ['className'], not: { required: ['sourceFile'] } }, { required: ['sourceFile'], not: { required: ['className'] } }] } : {}),
     required: Object.entries(spec.fields).filter(([, field]) => !field.isOptional()).map(([key]) => key),
     properties: { responseMode: { type: 'string', enum: ['compact', 'debug'], default: 'debug' }, ...Object.fromEntries(Object.entries(spec.fields).map(([key, field]) => [key, jsonField(field)])), timeoutMs: { type: 'integer', minimum: 100, maximum: 30000, default: name === 'wait_for_debugger_event' ? 1000 : 10000 } }
   }

package/src/server/schemas/system-trace-schema.ts

@@ -1,17 +1,23 @@
 import { z } from 'zod'
-const target = { platform: z.enum(['android', 'ios']), deviceId: z.string().min(1).optional() }
-export const traceTargetSchema = z.object(target).strict()
-export const traceStartSchema = z.object({ ...target, durationMs: z.number().int().min(1000).max(120000).default(30000) }).strict()
+const target = { platform: z.enum(['android', 'ios']), deviceId: z.string().min(1).optional(), appId: z.string().regex(/^[a-zA-Z0-9._-]+$/).optional(), template: z.enum(['System Trace', 'Time Profiler', 'Animation Hitches', 'Hangs']).optional() }
+const validTarget = (value: { platform: string; deviceId?: string; appId?: string; template?: string }) =>
+  value.platform === 'ios' ? !!value.deviceId : value.appId === undefined && value.template === undefined
+export const traceTargetSchema = z.object(target).strict().refine(validTarget)
+export const traceStartSchema = z.object({ ...target, durationMs: z.number().int().min(1000).max(120000).default(30000) }).strict().refine(validTarget).refine(value => value.platform !== 'ios' || !!value.appId)
 export const traceControlSchema = z.object({ traceId: z.string().uuid() }).strict()
-const properties = { platform: { type: 'string', enum: ['android', 'ios'] }, deviceId: { type: 'string', minLength: 1 } }
+const properties = { platform: { type: 'string', enum: ['android', 'ios'] }, deviceId: { type: 'string', minLength: 1 }, appId: { type: 'string', minLength: 1, pattern: '^[a-zA-Z0-9._-]+$', description: 'iOS only: running development app bundle identifier; required for iOS start.' }, template: { type: 'string', enum: ['System Trace', 'Time Profiler', 'Animation Hitches', 'Hangs'], description: 'iOS only. Default Time Profiler; initial simulator support is Time Profiler only.' } }
+const platformRules = (start: boolean) => ({ oneOf: [
+  { properties: { platform: { const: 'android' } }, not: { anyOf: [{ required: ['appId'] }, { required: ['template'] }] } },
+  { properties: { platform: { const: 'ios' } }, required: start ? ['deviceId', 'appId'] : ['deviceId'] }
+] })
 export const systemTraceTools = [
-  { name: 'get_system_trace_capabilities', description: 'Probe Android Perfetto prerequisites without recording. Device-wide system tracing is optional; iOS is unsupported.',
-    inputSchema: { type: 'object' as const, additionalProperties: false, required: ['platform'], properties } },
-  { name: 'start_system_trace', description: 'Start bounded Android Perfetto recording, returning an owned trace_id. Run an existing journey with systemTraceId, then stop to retrieve a local artifact or cancel to discard. Device-wide traces may contain sensitive system annotations; no upload.',
-    inputSchema: { type: 'object' as const, additionalProperties: false, required: ['platform'], properties: { ...properties, durationMs: { type: 'integer', minimum: 1000, maximum: 120000, default: 30000 } } } },
+  { name: 'get_system_trace_capabilities', description: 'Probe Android Perfetto or iOS Instruments prerequisites without recording. iOS requires explicit booted simulator deviceId; reports template matrix and unknown profiling permissions.',
+    inputSchema: { type: 'object' as const, additionalProperties: false, required: ['platform'], properties, ...platformRules(false) } },
+  { name: 'start_system_trace', description: 'Start bounded Android Perfetto or iOS simulator Time Profiler recording, returning an owned trace_id after readiness. iOS requires explicit deviceId and running appId. Run an existing journey with systemTraceId, then stop to retrieve a local artifact or cancel to discard. Traces can contain sensitive system metadata, logs and paths; local user-managed retention, no upload.',
+    inputSchema: { type: 'object' as const, additionalProperties: false, required: ['platform'], properties: { ...properties, durationMs: { type: 'integer', minimum: 1000, maximum: 120000, default: 30000 } }, ...platformRules(true) } },
   ...['get_system_trace_status', 'stop_system_trace', 'cancel_system_trace'].map(name => ({ name,
     description: name === 'get_system_trace_status' ? 'Reconcile an owned trace and retrieve its state; finalise duration-completed capture.' :
-      name === 'stop_system_trace' ? 'Stop owned capture gracefully and retrieve a local Perfetto artifact. Retry after a transfer/cleanup failure.' : 'Stop owned capture and discard partial files. Already completed local artifacts are retained.',
+      name === 'stop_system_trace' ? 'Stop owned capture gracefully and retrieve a local Perfetto file or validated Instruments .trace bundle. Retry after a transfer/cleanup failure.' : 'Stop owned capture and discard partial files. Already completed local artifacts are retained.',
     inputSchema: { type: 'object' as const, additionalProperties: false, required: ['traceId'], properties: { traceId: { type: 'string', format: 'uuid' } } }
   }))
 ]

package/src/server-core.ts

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

package/src/server.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { debuggerSessions } from './debugger/sessions.js'
+import { debuggerSessions, iosDebuggerSessions } 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'
@@ -22,8 +22,8 @@ async function shutdown() {
   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)) }
+    const [remaining, debuggers, iosDebuggers] = await Promise.all([systemTraces.shutdown(), debuggerSessions.shutdown(), iosDebuggerSessions.shutdown()])
+    if ((debuggers.length + iosDebuggers.length)) { exitCode = 1; console.error('Debugger shutdown cleanup incomplete', [...debuggers, ...iosDebuggers].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 })))

package/src/utils/ios/utils.ts

@@ -1,3 +1,4 @@
+import { checkDebuggerGuard } from '../../debugger/guard.js'
 import { remainingBudget } from '../operation-budget.js'
 import { execFile, spawn, execSync, spawnSync } from "child_process"
 import { DeviceInfo } from "../../types.js"
@@ -85,6 +86,7 @@ export function execCommand(args: string[], deviceId: string = "booted"): Promis
   return new Promise((resolve, reject) => {
     // Use spawn for better stream control and consistency with Android implementation
     const budgetMs = remainingBudget()
+    checkDebuggerGuard()
     const child = spawn(getXcrunCmd(), args)
 
     let stdout = ''
@@ -132,6 +134,7 @@ export function execCommandWithDiagnostics(args: string[], deviceId: string = "b
   const DEFAULT_XCRUN_LOG_TIMEOUT = parseInt(process.env.MCP_XCRUN_LOG_TIMEOUT || '', 10) || 30000
   const DEFAULT_XCRUN_CMD_TIMEOUT = parseInt(process.env.MCP_XCRUN_TIMEOUT || '', 10) || 60000
   const timeoutMs = budgetMs || (args.includes('log') ? DEFAULT_XCRUN_LOG_TIMEOUT : DEFAULT_XCRUN_CMD_TIMEOUT)
+  checkDebuggerGuard()
   const res = spawnSync(getXcrunCmd(), args, { encoding: 'utf8', timeout: timeoutMs })
   const runResult = {
     exitCode: typeof res.status === 'number' ? res.status : null,

package/test/device/automated/debugger/runtime.ios.test.ts

@@ -0,0 +1,221 @@
+import assert from 'node:assert/strict'
+import { execFileSync } from 'node:child_process'
+import { readFile, rm, readdir, writeFile, rename } from 'node:fs/promises'
+import { createHash } from 'node:crypto'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+import { buildIOSDebuggerFixture, iosDebuggerAppId, iosDebuggerSource } from '../../../fixtures/ios-debugger-app/build.js'
+
+if (!process.env.MCP_IOS_DEBUGGER_DEVICE) {
+  console.log('UNRUN iOS debugger: select a booted simulator with MCP_IOS_DEBUGGER_DEVICE')
+} else {
+  const deviceId = process.env.MCP_IOS_DEBUGGER_DEVICE
+  const sim = (...args: string[]) => execFileSync('xcrun', ['simctl', ...args], { encoding: 'utf8', timeout: 30000 }).trim()
+  console.log('Building disposable iOS fixture')
+  const fixture = buildIOSDebuggerFixture()
+  console.log('Fixture built')
+  const source = await readFile(iosDebuggerSource, 'utf8')
+  const line = (marker: string) => source.split('\n').findIndex(row => row.includes('// ' + marker)) + 1
+  const client = new Client({ name: 'ios-debugger-smoke', version: '1.0.0' })
+  const transport = new StdioClientTransport({ command: process.execPath, args: ['dist/server.js'], stderr: 'pipe' })
+  transport.stderr?.on('data', data => process.stderr.write(data))
+  const call = async (name: string, args: Record<string, unknown> = {}, signal?: AbortSignal) => {
+    const response = await client.callTool({ name, arguments: args }, undefined, { timeout: 45000, signal })
+    return JSON.parse((response.content as { type: string; text: string }[]).find(item => item.type === 'text')!.text)
+  }
+  const hash = createHash('sha256')
+  const fingerprint = async (directory: string): Promise<void> => {
+    for (const entry of (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+      const file = directory + '/' + entry.name
+      if (entry.isDirectory()) await fingerprint(file)
+      else if (!file.includes('__pycache__')) hash.update(file).update(await readFile(file))
+    }
+  }
+  await fingerprint('dist'); await fingerprint('src/debugger/lldb')
+  const serverHash = hash.digest('hex')
+  const target = { platform: 'ios', deviceId, appId: iosDebuggerAppId }
+  let debugSessionId = '', cursor = 0
+  const session = () => ({ debugSessionId })
+  const attach = async () => {
+    const response = await call('attach_debugger', { ...target, timeoutMs: 30000 })
+    assert.equal(response.success, true, JSON.stringify(response))
+    assert.equal(response.device.platform, 'ios')
+    debugSessionId = response.debug_session_id; cursor = 0
+  }
+  const breakpoint = async (marker: string) => {
+    const response = await call('set_debugger_breakpoint', { ...session(), sourceFile: iosDebuggerSource, line: line(marker) })
+    assert.equal(response.success, true, JSON.stringify(response))
+    assert.equal(response.result.status, 'resolved', JSON.stringify(response))
+    assert.ok(response.result.locations.every((loc: any) => loc.line === line(marker)))
+    return response.result.breakpoint_id
+  }
+  const remove = (breakpointId: string) => call('remove_debugger_breakpoint', { ...session(), breakpointId })
+  const stop = async () => {
+    for (let i = 0; i < 15; i++) {
+      const response = await call('wait_for_debugger_event', { ...session(), afterSequence: cursor, timeoutMs: 1000 })
+      assert.equal(response.success, true, JSON.stringify(response)); cursor = response.next_cursor
+      const found = response.events.find((event: any) => event.event === 'stopped')
+      if (found) { console.log('STOP', JSON.stringify(found)); return found }
+    }
+    throw new Error('No iOS debugger stop observed')
+  }
+  const resume = (event: any) => call('resume_debugger', { ...session(), stopId: event.stop_id })
+  const locals = async (event: any) => {
+    const stack = await call('get_debugger_stack', { ...session(), stopId: event.stop_id, threadId: event.thread_id })
+    assert.equal(stack.success, true, JSON.stringify(stack))
+    const frame = stack.result.frames.find((f: any) => f.source_file === iosDebuggerSource)
+    assert.ok(frame, JSON.stringify(stack))
+    const result = await call('get_debugger_locals', { ...session(), stopId: event.stop_id, frameId: frame.frame_id })
+    assert.equal(result.success, true, JSON.stringify(result)); console.log('LOCALS', JSON.stringify(result.result))
+    return { result: result.result, frame }
+  }
+  const expectLocal = (result: any, name: string, value: string) => assert.equal(result.locals.find((v: any) => v.name === name)?.value, value, JSON.stringify(result))
+  let commandFile = ''
+  const trigger = async (command: string) => {
+    console.log('TRIGGER', command)
+    await writeFile(commandFile + '.next', command)
+    await rename(commandFile + '.next', commandFile)
+  }
+  const tap = async (text: string) => {
+    const tree = await call('get_ui_tree', { platform: 'ios', deviceId })
+    assert.ok(tree.elements.some((e: any) => e.text === text), JSON.stringify(tree))
+    const commands: Record<string, string> = { Calculate: 'calculate', 'Run async': 'async', 'Start cancellation': 'start-cancellation', 'Cancel task': 'cancel' }
+    // The installed idb HID backend is unavailable. A fixture-only main-loop
+    // command file invokes the same button actions without debugger evaluation.
+    await trigger(commands[text])
+  }
+  const expectUI = async (text: string) => {
+    for (let i = 0; i < 15; i++) {
+      const tree = await call('get_ui_tree', { platform: 'ios', deviceId })
+      if (tree.elements.some((e: any) => e.text === text)) return
+      await new Promise(resolve => setTimeout(resolve, 200))
+    }
+    throw new Error('Missing independent UI state: ' + text)
+  }
+  const detach = async () => {
+    const response = await call('detach_debugger', session())
+    assert.equal(response.cleanup.status, 'complete', JSON.stringify(response))
+    assert.deepEqual(response.cleanup.remaining_resources, [])
+    assert.equal((await call('detach_debugger', session())).cleanup.status, 'complete')
+  }
+  try {
+    sim('install', deviceId, fixture.app)
+    sim('launch', deviceId, iosDebuggerAppId)
+    commandFile = sim('get_app_container', deviceId, iosDebuggerAppId, 'data') + '/Documents/debugger-command'
+    await client.connect(transport)
+    const shortProbe = await call('get_debugger_capabilities', { ...target, timeoutMs: 100 })
+    assert.equal(shortProbe.error?.code, 'DEBUGGER_TIMEOUT')
+    const absent = await call('get_debugger_capabilities', { ...target, appId: 'dev.mobiledebug.absentfixture' })
+    assert.equal(absent.supported, false); assert.ok(absent.reasons.includes('PROCESS_NOT_FOUND'))
+    const cap = await call('get_debugger_capabilities', target)
+    assert.equal(cap.supported, true, JSON.stringify(cap))
+    assert.equal(cap.capabilities.async_execution_inspection, true)
+    assert.equal(cap.capabilities.async_stepping, true)
+    const foreign = await call('attach_debugger', { ...target, processId: process.pid })
+    assert.equal(foreign.success, false); assert.equal(foreign.error.code, 'PROCESS_NOT_FOUND')
+    await attach()
+    const bp = await breakpoint('BREAK_CALCULATE')
+    const pending = await call('set_debugger_breakpoint', { ...session(), sourceFile: '/tmp/nonexistent-ios-debugger-source.swift', line: 1 })
+    assert.equal(pending.result.status, 'pending'); await remove(pending.result.breakpoint_id)
+    const noncode = await call('set_debugger_breakpoint', { ...session(), sourceFile: iosDebuggerSource, line: 9999 })
+    assert.equal(noncode.result.status, 'rejected'); await remove(noncode.result.breakpoint_id)
+    const storedHandle = await call('wait_for_ui', { platform: 'ios', deviceId, selector: { text: 'Calculate' }, condition: 'exists', timeout_ms: 10000 })
+    assert.equal(storedHandle.status, 'success', JSON.stringify(storedHandle))
+    assert.ok(storedHandle.element.elementId)
+    await tap('Calculate')
+    let event = await stop()
+    const originalStop = event
+    assert.equal(event.location.line, line('BREAK_CALCULATE'))
+    const inspected = await locals(event); expectLocal(inspected.result, 'known', '41')
+    const guarded = await call('tap', { platform: 'ios', deviceId, x: 10, y: 10 })
+    assert.equal(guarded.failure_code, 'DEBUGGER_PAUSED'); assert.equal(guarded.delivery_status, 'not_delivered')
+    const storedTap = await call('tap_element', { elementId: storedHandle.element.elementId, verificationMode: 'none', responseMode: 'compact' })
+    assert.equal(storedTap.failure_code, 'DEBUGGER_PAUSED', JSON.stringify(storedTap))
+    assert.equal(storedTap.delivery_status, 'not_delivered'); assert.equal(storedTap.dispatch_started, false)
+    assert.deepEqual(storedTap.debugger.device, { platform: 'ios', id: deviceId })
+    console.log('PASS paused stored iOS handle without platform/device hints rejected before dispatch')
+    assert.equal((await call('get_app_readiness', { platform: 'ios', deviceId })).readiness.state, 'debugger_paused')
+    await remove(bp)
+    for (const kind of ['into', 'over', 'out']) {
+      const response = await call('step_debugger', { ...session(), stopId: event.stop_id, threadId: event.thread_id, kind })
+      assert.equal(response.success, true, JSON.stringify(response)); event = await stop()
+    }
+    const stale = await call('get_debugger_locals', { ...session(), stopId: originalStop.stop_id, frameId: inspected.frame.frame_id })
+    assert.equal(stale.error.code, 'DEBUGGER_STALE_REFERENCE')
+    await resume(event)
+    await expectUI('Debugger result 42')
+    const controller = new AbortController()
+    const waiting = call('wait_for_debugger_event', { ...session(), afterSequence: cursor, timeoutMs: 30000 }, controller.signal)
+    setTimeout(() => controller.abort(), 100)
+    await assert.rejects(waiting)
+    assert.equal((await call('get_debugger_state', session())).state, 'running')
+    await detach()
+
+    await attach()
+    const before = await breakpoint('BEFORE_AWAIT'), after = await breakpoint('AFTER_AWAIT')
+    await tap('Run async')
+    event = await stop(); assert.equal(event.location.line, line('BEFORE_AWAIT'))
+    expectLocal((await locals(event)).result, 'known', '42')
+    await remove(before)
+    await resume(event)
+    event = await stop(); assert.equal(event.location.line, line('AFTER_AWAIT'))
+    expectLocal((await locals(event)).result, 'after', '43')
+    await remove(after); await resume(event)
+    await expectUI('Async result 44')
+    await detach()
+
+    // Boundary stepping has a distinct evidence result, independent of breakpoint coverage.
+    await attach()
+    const boundary = await breakpoint('BEFORE_AWAIT')
+    await tap('Run async'); event = await stop(); await remove(boundary)
+    assert.equal((await call('step_debugger', { ...session(), stopId: event.stop_id, threadId: event.thread_id, kind: 'over' })).success, true)
+    event = await stop()
+    assert.equal(event.location.source_file, iosDebuggerSource)
+    assert.equal(event.location.line, line('AFTER_AWAIT'), 'Advertised async stepping must follow the continuation')
+    console.log('ASYNC_BOUNDARY_STEP', JSON.stringify({ expected_line: line('AFTER_AWAIT'), observed: event.location }))
+    await detach(); await expectUI('Async result 44')
+
+    await attach()
+    const cancel = await breakpoint('CANCELLED')
+    await tap('Start cancellation'); await expectUI('Task running'); await tap('Cancel task')
+    event = await stop(); expectLocal((await locals(event)).result, 'cancelled', 'true')
+    await remove(cancel); await resume(event); await detach(); await expectUI('Task cancelled')
+
+    if (process.env.MCP_IOS_DEBUGGER_EXTENDED === '1') {
+      await attach(); await breakpoint('BREAK_CALCULATE'); await tap('Calculate'); await stop()
+      const deadline = Date.now() + 75000
+      let state: any
+      do { await new Promise(resolve => setTimeout(resolve, 1000)); state = await call('get_debugger_state', session()) } while (state.state === 'paused' && Date.now() < deadline)
+      assert.equal(state.reason, 'pause_limit'); assert.equal(state.cleanup.status, 'complete')
+      await expectUI('Debugger result 42')
+    }
+    await attach()
+    await trigger('exit')
+    let exited: any
+    for (let i = 0; i < 100; i++) {
+      exited = await call('get_debugger_state', session())
+      if (exited.state === 'disconnected' && exited.cleanup.status === 'complete') break
+      await new Promise(resolve => setTimeout(resolve, 100))
+    }
+    assert.equal(exited.state, 'disconnected'); assert.equal(exited.cleanup.status, 'complete')
+    sim('launch', deviceId, iosDebuggerAppId); await expectUI('Debugger ready')
+    // Clear the earlier calculate result before proving shutdown recovery.
+    await tap('Start cancellation'); await expectUI('Task running'); await tap('Cancel task'); await expectUI('Task cancelled')
+    // Closing the server while paused must release its owned suspension.
+    await attach(); await breakpoint('BREAK_CALCULATE'); await tap('Calculate'); await stop()
+    await client.close()
+    const verifier = new Client({ name: 'ios-cleanup-verifier', version: '1.0.0' })
+    await verifier.connect(new StdioClientTransport({ command: process.execPath, args: ['dist/server.js'], stderr: 'pipe' }))
+    try {
+      const response = await verifier.callTool({ name: 'get_ui_tree', arguments: { platform: 'ios', deviceId } })
+      const tree = JSON.parse((response.content as any[])[0].text)
+      assert.ok(tree.elements.some((e: any) => e.text === 'Debugger result 42'), JSON.stringify(tree))
+    } finally { await verifier.close() }
+    console.log('PASS iOS MCP debugger core/async/cancellation/cleanup', JSON.stringify({ deviceId, server_sha256: serverHash, source_sha256: createHash('sha256').update(source).digest('hex'), xcode: execFileSync('xcodebuild', ['-version'], { encoding: 'utf8' }).trim(), lldb: execFileSync('xcrun', ['lldb', '--version'], { encoding: 'utf8' }).trim() }))
+  } finally {
+    if (debugSessionId) { try { await call('detach_debugger', session()) } catch {} }
+    await client.close().catch(() => {})
+    sim('uninstall', deviceId, iosDebuggerAppId)
+    await rm(fixture.directory, { recursive: true, force: true })
+  }
+}