mobile-debug-mcp 0.35.0 → 0.36.0

package/dist/observe/ios-trace/sessions.js

@@ -0,0 +1,244 @@
+import { classifyTraceFailure } from './process.js';
+import { TraceError } from '../system-trace-error.js';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { evidenceSessionId } from '../evidence.js';
+import { IosTraceNative } from './native.js';
+const reasonFor = (error, fallback) => {
+    const code = error instanceof Error ? error.message : '';
+    return ['STORAGE_LIMIT', 'APP_IDENTITY_CHANGED', 'ACTION_TIMEOUT', 'READINESS_TIMEOUT', 'RECORDER_EXITED', 'PROFILING_PERMISSION_REQUIRED', 'APP_NOT_RUNNING', 'TARGET_DISCONNECTED'].includes(code) ? code : fallback;
+};
+export class IosTraceSessions {
+    native;
+    time;
+    sessions = new Map();
+    closing = false;
+    constructor(native = new IosTraceNative(), time = {
+        wall: Date.now, mono: () => performance.now(), sleep: ms => new Promise(resolve => setTimeout(resolve, ms)),
+        schedule: (fn, ms) => { const timer = setTimeout(fn, ms); timer.unref(); return timer; }, clear: clearTimeout
+    }) {
+        this.native = native;
+        this.time = time;
+    }
+    get(id) {
+        this.prune();
+        const s = this.sessions.get(id);
+        if (!s)
+            throw new TraceError('TRACE_NOT_FOUND');
+        return s;
+    }
+    prune() {
+        const terminal = [...this.sessions.values()].filter(s => s.terminal !== undefined && s.result.cleanup.status === 'complete');
+        for (const [index, s] of terminal.entries())
+            if (this.time.mono() - s.terminal >= 600000 || index < terminal.length - 100)
+                this.sessions.delete(s.result.trace_id);
+    }
+    serial(s, fn) {
+        const promise = s.queue.then(fn);
+        s.queue = promise.catch(() => { });
+        return promise;
+    }
+    snapshot(s) { return structuredClone(s.result); }
+    fail(s, reason) {
+        s.result.state = 'failed';
+        s.result.reason = reason;
+        s.result.completion_reason = 'error';
+        s.result.recovery = reason === 'PROFILING_PERMISSION_REQUIRED' ? 'Grant the required profiling permission through the macOS or Xcode UI, then explicitly start a new capture.' : reason === 'TRACE_ARTIFACT_FAILED' ? 'Retry stop to validate the finalised owned artifact, or cancel to discard.' : 'Check target, app and profiling permissions; cancel the owned session before retrying start.';
+        for (const id of s.linked)
+            s.partial.add(id);
+    }
+    async start(device, appId, duration = 30000) {
+        this.prune();
+        const active = [...this.sessions.values()].filter(s => s.result.cleanup.status !== 'complete');
+        if (this.closing || active.length >= 4 || active.some(s => s.result.device.id === device.id))
+            throw new TraceError('TRACE_BUSY');
+        if (!Number.isInteger(duration) || duration < 1000 || duration > 120000)
+            throw new TraceError('INVALID_ARGUMENT');
+        const result = {
+            trace_id: randomUUID(), session_id: evidenceSessionId(), device: structuredClone(device), backend: 'xctrace', state: 'starting',
+            reason: null, recovery: null, completion_reason: null, capture_started_at_ms: null, capture_completed_at_ms: null,
+            recording_ready_at_ms: null, app_id: appId, pid: null, executable: null, template: 'Time Profiler', artifact: null,
+            cleanup: { status: 'pending', remaining_resources: [] }, warnings: [], correlation_ids: [], clock_alignment: 'unknown'
+        };
+        const s = { result, deadline: Infinity, discard: false, queue: Promise.resolve(), linked: new Set(), partial: new Set() };
+        this.sessions.set(result.trace_id, s);
+        return this.serial(s, async () => {
+            try {
+                s.directory = await fs.mkdtemp(path.join(os.tmpdir(), 'mobile-debug-ios-trace-'));
+                await fs.chmod(s.directory, 0o700);
+                s.result.cleanup.remaining_resources = [s.directory];
+                s.app = await this.native.resolve(device.id, appId);
+                s.result.pid = s.app.pid;
+                s.result.executable = s.app.executable;
+                if (this.closing)
+                    throw new TraceError('TRACE_BUSY');
+                s.result.capture_started_at_ms = this.time.wall();
+                s.deadline = Infinity;
+                s.recording = await this.native.start(device.id, s.app, s.directory, duration, recording => { s.recording = recording; if (this.closing)
+                    recording.recorder.signal('SIGINT'); });
+                if (this.closing)
+                    throw new Error('READINESS_TIMEOUT');
+                s.deadline = this.time.mono() + duration;
+                s.result.recording_ready_at_ms = s.recording.ready_at_ms;
+                s.result.state = 'recording';
+                this.schedule(s);
+                void s.recording.recorder.done.then(() => this.control(result.trace_id, 'status')).catch(() => { });
+            }
+            catch (error) {
+                this.fail(s, reasonFor(error, 'TRACE_START_FAILED'));
+                s.discard = true;
+                await this.finalise(s, 'cancel', true);
+            }
+            return this.snapshot(s);
+        });
+    }
+    schedule(s) {
+        if (s.result.state !== 'recording')
+            return;
+        s.timer = this.time.schedule(() => {
+            void this.serial(s, () => this.poll(s)).finally(() => this.schedule(s)).catch(() => { });
+        }, 1000);
+    }
+    async poll(s) {
+        if (s.result.state !== 'recording' || !s.recording || !s.app)
+            return;
+        try {
+            await this.native.monitor(s.result.device.id, s.app, s.recording);
+            s.monitorFailures = 0;
+        }
+        catch (error) {
+            const reason = error instanceof Error && error.message === 'COMMAND_FAILED'
+                ? 'COMMAND_FAILED' : reasonFor(error, 'TRACE_MONITOR_FAILED');
+            const definitive = ['STORAGE_LIMIT', 'APP_IDENTITY_CHANGED', 'APP_NOT_RUNNING'].includes(reason);
+            s.monitorFailures = (s.monitorFailures ?? 0) + 1;
+            if (definitive || s.monitorFailures >= 3) {
+                this.fail(s, reason);
+                s.discard = true;
+                await this.finalise(s, 'cancel', true);
+                return;
+            }
+        }
+        if (this.time.mono() >= s.deadline || !s.recording.recorder.alive())
+            await this.finalise(s, 'duration');
+    }
+    async control(id, op, timeout) {
+        const s = this.get(id);
+        return this.serial(s, async () => {
+            if (s.result.cleanup.status === 'complete')
+                return this.snapshot(s);
+            if (op === 'status' && s.result.state === 'recording' && s.recording?.recorder.alive() && this.time.mono() < s.deadline) {
+                await this.poll(s);
+                return this.snapshot(s);
+            }
+            await this.finalise(s, op === 'status' ? 'duration' : op, false, timeout);
+            return this.snapshot(s);
+        });
+    }
+    async finalise(s, op, preserveFailure = false, timeout) {
+        if (s.timer) {
+            this.time.clear(s.timer);
+            s.timer = undefined;
+        }
+        if (op === 'cancel')
+            s.discard = true;
+        if (!preserveFailure)
+            s.result.state = 'stopping';
+        for (const id of s.linked)
+            s.partial.add(id);
+        try {
+            await this.finishRecorder(s, op, timeout);
+            s.result.capture_completed_at_ms ??= this.time.wall();
+            await this.finishArtifact(s);
+            s.result.cleanup = { status: 'complete', remaining_resources: [] };
+            s.terminal = this.time.mono();
+            if (!preserveFailure) {
+                s.result.state = s.discard ? 'cancelled' : 'completed';
+                s.result.reason = s.discard ? 'TRACE_CANCELLED' : null;
+                s.result.recovery = null;
+                s.result.completion_reason = s.discard ? 'cancelled' : op === 'duration' ? 'duration_limit' : 'requested';
+            }
+        }
+        catch (error) {
+            this.fail(s, reasonFor(error, s.recording?.recorder.alive() ? 'TRACE_STOP_FAILED' : 'TRACE_ARTIFACT_FAILED'));
+            s.result.cleanup.status = 'failed';
+            if (s.result.reason === 'STORAGE_LIMIT' && !s.recording?.recorder.alive())
+                await this.discardOversized(s);
+        }
+    }
+    async discardOversized(s) {
+        try {
+            if (s.directory)
+                await fs.rm(s.directory, { recursive: true, force: true });
+            s.result.cleanup = { status: 'complete', remaining_resources: [] };
+            s.terminal = this.time.mono();
+        }
+        catch { /* retain failed cleanup and owned path for cancel retry */ }
+    }
+    async finishRecorder(s, op, timeout) {
+        if (!s.recording || s.recorderOk !== undefined)
+            return;
+        const ended = await this.native.stop(s.recording, timeout);
+        s.recorderOk = ended.code === 0 && !ended.timedOut;
+        if (ended.output.includes('[Warning]'))
+            s.result.warnings = ['INSTRUMENTS_RUN_WARNING: one or more Instruments warnings; coverage may be incomplete.'];
+        if (!s.recorderOk && !s.discard)
+            throw new Error(classifyTraceFailure(ended));
+        if (op === 'duration' && !ended.output.includes('Reached specified time limit') && this.time.mono() < s.deadline && !s.discard)
+            throw new Error('RECORDER_EXITED');
+    }
+    async finishArtifact(s) {
+        if (!s.discard && !s.result.artifact) {
+            if (!s.recording || !s.app || !s.recorderOk)
+                throw new Error('RECORDER_EXITED');
+            s.result.artifact = await this.native.validate(s.recording, s.result.device.id, s.app);
+        }
+        if (s.discard && s.directory)
+            await fs.rm(s.directory, { recursive: true, force: true });
+        else if (s.directory)
+            await Promise.all(['notification', 'notification.c'].map(p => fs.rm(path.join(s.directory, p), { force: true })));
+    }
+    async link(id, device, correlation) {
+        const s = this.get(id);
+        if (device.platform !== 'ios' || device.id !== s.result.device.id)
+            throw new TraceError('TRACE_NOT_FOUND');
+        const status = await this.control(id, 'status');
+        if (status.state !== 'recording')
+            throw new TraceError('TRACE_NOT_FOUND');
+        return this.serial(s, async () => {
+            if (s.result.state !== 'recording' || !s.recording?.recorder.alive() || this.time.mono() >= s.deadline)
+                throw new TraceError('TRACE_NOT_FOUND');
+            if (!s.result.correlation_ids.includes(correlation)) {
+                if (s.result.correlation_ids.length >= 1000)
+                    throw new TraceError('TRACE_BUSY');
+                s.result.correlation_ids.push(correlation);
+            }
+            s.linked.add(correlation);
+            let finished;
+            return () => finished ??= (async () => {
+                let active = false;
+                try {
+                    active = (await this.control(id, 'status')).state === 'recording';
+                }
+                catch { /* unknown is partial */ }
+                s.linked.delete(correlation);
+                return { trace_id: id, coverage: !active || s.partial.has(correlation) ? 'partial' : 'covered', clock_alignment: 'unknown' };
+            })();
+        });
+    }
+    async shutdown() {
+        this.closing = true;
+        this.native.shutdown();
+        const active = [...this.sessions.values()].filter(s => s.result.cleanup.status !== 'complete');
+        // Signal immediately even when an in-flight start/validation owns the serial queue.
+        for (const s of active)
+            s.recording?.recorder.signal('SIGINT');
+        let timer;
+        await Promise.race([Promise.allSettled(active.map(s => this.control(s.result.trace_id, 'cancel', 8000))),
+            new Promise(resolve => { timer = setTimeout(resolve, 9000); })]);
+        if (timer)
+            clearTimeout(timer);
+        return active.filter(s => s.result.cleanup.status !== 'complete').map(s => this.snapshot(s));
+    }
+}

package/dist/observe/readiness-service.js

@@ -43,7 +43,7 @@ export async function getAppReadiness(args, wait = false) {
                 let count = 0;
                 while (wait || count < 2) {
                     remainingBudget();
-                    debugPause = device.platform === 'android' ? pausedReadiness(device.id) : null;
+                    debugPause = pausedReadiness(device.id, device.platform);
                     if (debugPause) {
                         failureCode = wait ? 'DEBUGGER_PAUSED' : undefined;
                         return;

package/dist/observe/readiness.js

@@ -21,14 +21,14 @@ export class ReadinessTracker {
         this.summary = {
             state: 'unknown', scope: 'device_ui', basis: 'insufficient', captured_at_ms: null,
             sample_count: 0, stable_for_ms: 0, snapshot_session_id: null, snapshot_revision: null,
-            evidence: [], limitations: [...baselineLimitations, this.platform === 'android' ? 'MANAGED_DEBUGGER_ONLY' : 'DEBUGGER_SIGNAL_UNSUPPORTED', 'INSUFFICIENT_SAMPLES'], capabilities: { ...capabilities, debugger_paused: this.platform === 'android' }
+            evidence: [], limitations: [...baselineLimitations, ['android', 'ios'].includes(this.platform) ? 'MANAGED_DEBUGGER_ONLY' : 'DEBUGGER_SIGNAL_UNSUPPORTED', 'INSUFFICIENT_SAMPLES'], capabilities: { ...capabilities, debugger_paused: ['android', 'ios'].includes(this.platform) }
         };
     }
     unavailable(code = 'OBSERVATION_FAILED') {
         this.signature = null;
         this.summary = {
             ...this.summary, state: 'unknown', basis: 'insufficient', stable_for_ms: 0,
-            sample_count: this.summary.sample_count + 1, limitations: [...baselineLimitations, this.platform === 'android' ? 'MANAGED_DEBUGGER_ONLY' : 'DEBUGGER_SIGNAL_UNSUPPORTED', code],
+            sample_count: this.summary.sample_count + 1, limitations: [...baselineLimitations, ['android', 'ios'].includes(this.platform) ? 'MANAGED_DEBUGGER_ONLY' : 'DEBUGGER_SIGNAL_UNSUPPORTED', code],
             evidence: [...this.summary.evidence, { code, source: 'ui_tree', captured_at_ms: null, snapshot_revision: null }].slice(-8)
         };
         return this.summary;
@@ -38,7 +38,7 @@ export class ReadinessTracker {
         return this.summary;
     }
     observe(sample, acquisitionStartedAtMs, now = performance.now()) {
-        const paused = this.platform === 'android' ? pausedReadiness(this.deviceId) : null;
+        const paused = pausedReadiness(this.deviceId, this.platform);
         if (paused) {
             this.summary = paused;
             return this.summary;
@@ -66,7 +66,7 @@ export class ReadinessTracker {
             captured_at_ms: tree.captured_at_ms, snapshot_session_id: tree.snapshot_session_id, snapshot_revision: tree.snapshot_revision,
             sample_count: this.summary.sample_count + 1, stable_for_ms: stableFor,
             evidence: [...this.summary.evidence, { code, source: 'ui_tree', captured_at_ms: tree.captured_at_ms, snapshot_revision: tree.snapshot_revision }].slice(-8),
-            limitations: [...baselineLimitations, this.platform === 'android' ? 'MANAGED_DEBUGGER_ONLY' : 'DEBUGGER_SIGNAL_UNSUPPORTED', ...(state === 'unknown' ? ['INSUFFICIENT_SAMPLES'] : [])], capabilities: { ...capabilities, debugger_paused: this.platform === 'android' }
+            limitations: [...baselineLimitations, ['android', 'ios'].includes(this.platform) ? 'MANAGED_DEBUGGER_ONLY' : 'DEBUGGER_SIGNAL_UNSUPPORTED', ...(state === 'unknown' ? ['INSUFFICIENT_SAMPLES'] : [])], capabilities: { ...capabilities, debugger_paused: ['android', 'ios'].includes(this.platform) }
         };
         return this.summary;
     }

package/dist/observe/system-trace-error.js

@@ -0,0 +1,7 @@
+export class TraceError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}

package/dist/observe/system-trace-router.js

@@ -0,0 +1,81 @@
+import { TraceError } from './system-trace-error.js';
+import { IosTraceSessions } from './ios-trace/sessions.js';
+import { IosTraceNative } from './ios-trace/native.js';
+export class SystemTraceRouter {
+    android;
+    ios;
+    native;
+    routes = new Map();
+    pending = new Set();
+    closing = false;
+    constructor(android, ios = new IosTraceSessions(), native = new IosTraceNative()) {
+        this.android = android;
+        this.ios = ios;
+        this.native = native;
+    }
+    capabilities(device) { return this.android.capabilities(device); }
+    iosCapabilities(device, appId, template) { return this.native.capabilities(device, appId, template); }
+    backend(platform) { return platform === 'ios' ? this.ios : this.android; }
+    track(result) {
+        this.routes.set(result.trace_id, { platform: result.device.platform, device: result.device.id,
+            active: result.cleanup.status !== 'complete', touched: performance.now() });
+        const terminal = [...this.routes.entries()].filter(([, r]) => !r.active);
+        for (const [index, [id, r]] of terminal.entries())
+            if (performance.now() - r.touched > 600000 || index < terminal.length - 100)
+                this.routes.delete(id);
+        return result;
+    }
+    async start(device, duration, ios) {
+        if (this.closing)
+            throw new TraceError('TRACE_BUSY');
+        // Refresh automatically finalised reservations without trusting cached state.
+        await Promise.all([...this.routes.entries()].filter(([, r]) => r.active).map(async ([id, r]) => {
+            try {
+                this.track(await this.backend(r.platform).control(id, 'status'));
+            }
+            catch { /* uncertain cleanup continues to reserve capacity */ }
+        }));
+        const key = (ios ? 'ios:' : 'android:') + device;
+        const active = [...this.routes.values()].filter(r => r.active);
+        if (this.closing || this.pending.has(key) || active.some(r => r.platform + ':' + r.device === key) || active.length + this.pending.size >= 4)
+            throw new TraceError('TRACE_BUSY');
+        this.pending.add(key);
+        try {
+            if (!ios)
+                return this.track(await this.android.start(device, duration));
+            const cap = await this.native.capabilities(device, ios.appId, ios.template);
+            if (!cap.supported || !cap.device)
+                throw new TraceError('TRACE_UNSUPPORTED');
+            if (this.closing)
+                throw new TraceError('TRACE_BUSY');
+            return this.track(await this.ios.start(cap.device, ios.appId, duration));
+        }
+        finally {
+            this.pending.delete(key);
+        }
+    }
+    async control(id, operation) {
+        const route = this.routes.get(id);
+        if (!route)
+            throw new TraceError('TRACE_NOT_FOUND');
+        return this.track(await this.backend(route.platform).control(id, operation));
+    }
+    async link(id, device, correlation) {
+        const route = this.routes.get(id);
+        if (!route || route.platform !== device.platform || route.device !== device.id)
+            throw new TraceError('TRACE_NOT_FOUND');
+        return this.backend(route.platform).link(id, device, correlation);
+    }
+    async shutdown() {
+        this.closing = true;
+        this.native.shutdown();
+        const results = await Promise.allSettled([this.android.shutdown(), this.ios.shutdown()]);
+        if (results.some(result => result.status === 'rejected'))
+            throw new TraceError('TRACE_STOP_FAILED');
+        const remaining = [];
+        for (const result of results)
+            if (result.status === 'fulfilled')
+                remaining.push(...result.value);
+        return remaining;
+    }
+}

package/dist/observe/system-trace.js

@@ -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';
@@ -5,13 +6,8 @@ import path from 'node:path';
 import { AndroidTraceNative, TRACE_MAX_BYTES } from './system-trace-android.js';
 import { evidenceSessionId } from './evidence.js';
 import { runWithBudget, remainingBudget } from '../utils/operation-budget.js';
-export class TraceError extends Error {
-    code;
-    constructor(code) {
-        super(code);
-        this.code = code;
-    }
-}
+export { TraceError } from './system-trace-error.js';
+import { TraceError } from './system-trace-error.js';
 const clock = {
     wall: Date.now, mono: () => performance.now(), sleep: ms => new Promise(resolve => setTimeout(resolve, ms)),
     schedule: (fn, ms) => { const t = setTimeout(fn, ms); t.unref(); return t; }, clear: clearTimeout
@@ -291,4 +287,4 @@ export class SystemTraceSessions {
         });
     }
 }
-export const systemTraces = new SystemTraceSessions();
+export const systemTraces = new SystemTraceRouter(new SystemTraceSessions());

package/dist/server/handlers/debugger-handlers.js

@@ -1,7 +1,8 @@
+import { iosCapabilities } from '../../debugger/ios-worker.js';
 import { debuggerResponse } from './debugger-response.js';
 import { classify } 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 } from '../common.js';
 function failure(code, summary = {}, diagnostic, command = '', mode = 'debug') {
@@ -20,15 +21,17 @@ export async function handleDebugger(name, args, signal) {
     const { responseMode, ...input } = parsed.data;
     const a = input;
     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');
@@ -36,13 +39,29 @@ export async function handleDebugger(name, args, signal) {
         let summary = {};
         if (a.debugSessionId) {
             try {
-                summary = debuggerSessions.summary(a.debugSessionId);
+                summary = sessions.summary(a.debugSessionId);
             }
             catch { /* Unknown session */ }
         }
-        return failure(code, {
+        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) {
+    return a.platform === 'ios' || (a.debugSessionId && iosDebuggerSessions.owns(a.debugSessionId)) ? iosDebuggerSessions : debuggerSessions;
+}
+function iosRecovery(d) {
+    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(value) {
+    const result = { ...value };
+    const error = value.error;
+    return { ...result, ...(error?.diagnostic ? { error: { ...error, diagnostic: iosRecovery(error.diagnostic) } } : {}),
+        ...(Array.isArray(value.diagnostics) ? { diagnostics: value.diagnostics.map(iosRecovery) } : {}) };
+}

package/dist/server/handlers/diagnostic.js

@@ -44,10 +44,10 @@ export async function handleSystemTrace(name, args) {
         throw new TraceError('INVALID_ARGUMENT');
     if (name === 'get_system_trace_capabilities' || name === 'start_system_trace') {
         const target = parsed.data;
-        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'] });
+        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 {
@@ -67,3 +67,11 @@ export async function handleSystemTrace(name, args) {
     const result = await systemTraces.control(parsed.data.traceId, operation);
     return { ...wrapResponse(result), ...(['failed', 'cancelled'].includes(result.state) ? { isError: true } : {}) };
 }
+async function handleIosTrace(name, target) {
+    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/dist/server/handlers/tool-handlers.js

@@ -1,6 +1,7 @@
+import { ToolsInteract } from '../../interact/index.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';
@@ -71,9 +72,17 @@ export const toolHandlers = {
 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');
 }
+function resolveGuardDevice(name, args) {
+    const platform = args.platform;
+    const deviceId = args.deviceId;
+    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, args, handler, addTiming) {
-    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;
@@ -81,11 +90,11 @@ async function dispatchGuarded(device, args, handler, addTiming) {
             response = await handler(args);
         }
         catch (error) {
-            if (!debuggerSessions.paused(device.id))
+            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) {
@@ -100,14 +109,15 @@ async function dispatchGuarded(device, args, handler, addTiming) {
     }));
 }
 function attachPausedObservation(name, args, response) {
-    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 });
             }
@@ -142,8 +152,8 @@ export async function handleToolCall(name, args = {}, signal) {
             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 });
+            if (guarded && (debuggerSessions.hasActiveSessions() || iosDebuggerSessions.hasActiveSessions())) {
+                const device = await resolveGuardDevice(name, args);
                 return dispatchGuarded(device, args, handler, addTiming);
             }
             const response = await handler(args);

package/dist/server/schemas/debugger-schema.js

@@ -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) {
@@ -35,12 +36,14 @@ function jsonField(schema) {
     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', 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 } }
     }