mobile-debug-mcp 0.35.0 → 0.36.0

package/dist/debugger/sessions.js

@@ -1,11 +1,13 @@
 import { atStage, classify, diagnostic } from './diagnostics.js';
 import { registerDebuggerPauseProvider } from './guard.js';
+import { IOSDebugNative } from './ios.js';
+import { createIOSWorker, prepareIOSWorker, iosCapabilities, iosLimitations } from './ios-worker.js';
 import { randomUUID } from 'node:crypto';
 import { AndroidDebugNative } from './android.js';
 import { createWorker, prepareWorker, DebuggerError, withDebuggerBudget, debuggerRemaining } from './worker.js';
 export const debuggerCapabilities = { attach: true, breakpoints: true, stacks: true, locals: true, step: true, resume: true,
     evaluation: false, mutation: false, coroutines: false, native: false };
-const limitations = ['JAVA_KOTLIN_BYTECODE_ONLY', 'DEBUG_METADATA_REQUIRED', 'SHALLOW_LOCALS', 'ALL_THREADS_SUSPEND', 'DEVICE_WIDE_UI_GUARD'];
+export const androidLimitations = ['JAVA_KOTLIN_BYTECODE_ONLY', 'DEBUG_METADATA_REQUIRED', 'SHALLOW_LOCALS', 'ALL_THREADS_SUSPEND', 'DEVICE_WIDE_UI_GUARD'];
 export function debuggerExpiry(created, activity, pausedAt, now) {
     return pausedAt !== undefined && now - pausedAt >= 60000 ? 'pause_limit' : now - activity >= 300000 ? 'idle_limit' : now - created >= 1800000 ? 'session_limit' : null;
 }
@@ -13,13 +15,17 @@ export class DebuggerSessions {
     native;
     workerFactory;
     prerequisite;
+    options;
     sessions = new Map();
     closing = false;
-    constructor(native = new AndroidDebugNative(), workerFactory = createWorker, prerequisite = prepareWorker) {
+    constructor(native = new AndroidDebugNative(), workerFactory = createWorker, prerequisite = prepareWorker, options = {}) {
         this.native = native;
         this.workerFactory = workerFactory;
         this.prerequisite = prerequisite;
+        this.options = options;
     }
+    get platform() { return this.options.platform ?? 'android'; }
+    get workerResource() { return this.platform === 'ios' ? 'lldb_worker' : 'jdi_worker'; }
     prune() {
         const terminal = [...this.sessions.values()].filter(s => s.terminalAt !== undefined && s.cleanup.status === 'complete');
         for (const s of terminal)
@@ -42,9 +48,10 @@ export class DebuggerSessions {
         const success = payload.success ?? (!['failed', 'disconnected'].includes(s.state) && s.cleanup.status !== 'failed');
         const code = s.cleanup.status === 'failed' ? 'DEBUGGER_CLEANUP_FAILED' : s.state === 'disconnected' ? 'DEBUGGER_DISCONNECTED' : s.reason?.match(/^[A-Z_]+$/) ? s.reason : 'DEBUGGER_WORKER_FAILED';
         return structuredClone({ success, ...(!success ? { error: { code, message: code, retryable: false, diagnostic: s.cleanup.status === 'failed' ? diagnostic('cleanup', 'operation_failed') : s.diagnostic ?? diagnostic('unknown', 'unknown') } } : {}), debug_session_id: s.id,
-            device: { platform: 'android', id: s.device }, target: s.target, state: s.state, captured_at_ms: Date.now(),
-            capabilities: debuggerCapabilities, limitations, cleanup: s.cleanup, reason: s.reason, stop: s.stop, ...payload });
+            device: { platform: this.platform, id: s.device }, target: s.target, state: s.state, captured_at_ms: Date.now(),
+            capabilities: this.options.capabilities ?? debuggerCapabilities, limitations: this.options.limitations ?? androidLimitations, cleanup: s.cleanup, reason: s.reason, stop: s.stop, ...payload });
     }
+    owns(id) { return this.sessions.has(id); }
     summary(id) { return this.result(this.get(id)); }
     hasActiveSessions() { return [...this.sessions.values()].some(s => s.cleanup.status !== 'complete'); }
     paused(device) { const s = [...this.sessions.values()].find(s => s.device === device && s.state === 'paused'); return s ? this.result(s) : null; }
@@ -77,13 +84,13 @@ export class DebuggerSessions {
             s.events.shift();
     }
     async capabilities(device, app, pid) {
-        const prerequisites = { jdk: false, device: false, process: false };
+        const prerequisites = { [this.platform === 'ios' ? 'lldb' : 'jdk']: false, device: false, process: false };
         let candidates = [];
         const reasons = [];
         const diagnostics = [];
         try {
             await atStage('prerequisite', 'DEBUGGER_UNSUPPORTED', () => this.prerequisite());
-            prerequisites.jdk = true;
+            prerequisites[this.platform === 'ios' ? 'lldb' : 'jdk'] = true;
         }
         catch (e) {
             if (e instanceof DebuggerError && ['DEBUGGER_TIMEOUT', 'DEBUGGER_CANCELLED'].includes(e.code))
@@ -106,9 +113,9 @@ export class DebuggerSessions {
             reasons.push(e instanceof DebuggerError ? e.code : 'DEVICE_UNAVAILABLE');
             diagnostics.push(classify(e, 'target_resolution', 'DEVICE_UNAVAILABLE').diagnostic ?? diagnostic('target_resolution', 'unknown'));
         }
-        return { success: true, debug_session_id: null, device: { platform: 'android', id: device }, target: null, state: null,
+        return { success: true, debug_session_id: null, device: { platform: this.platform, id: device }, target: null, state: null,
             captured_at_ms: Date.now(), supported: Object.values(prerequisites).every(Boolean), prerequisites, candidates,
-            ...(diagnostics.length ? { diagnostics } : {}), capabilities: debuggerCapabilities, reasons, limitations, cleanup: { status: 'complete', remaining_resources: [] } };
+            ...(diagnostics.length ? { diagnostics } : {}), capabilities: this.options.capabilities ?? debuggerCapabilities, reasons, limitations: this.options.limitations ?? androidLimitations, cleanup: { status: 'complete', remaining_resources: [] } };
     }
     async attach(device, app, pid, timeout = 10000) {
         this.prune();
@@ -144,16 +151,20 @@ export class DebuggerSessions {
                 if (candidates.length > 1)
                     throw new DebuggerError('PROCESS_AMBIGUOUS');
                 s.target = candidates[0];
-                stage = 'forwarding';
-                s.port = await atStage('forwarding', 'DEBUGGER_ATTACH_FAILED', () => this.native.forward(device, s.target.pid));
-                remaining();
-                s.cleanup.remaining_resources.push(`forward:tcp:${s.port}`);
+                if (this.platform === 'android') {
+                    stage = 'forwarding';
+                    s.port = await atStage('forwarding', 'DEBUGGER_ATTACH_FAILED', () => this.native.forward(device, s.target.pid));
+                    remaining();
+                    s.cleanup.remaining_resources.push(`forward:tcp:${s.port}`);
+                }
                 stage = 'worker_start';
                 s.worker = await atStage('worker_start', 'DEBUGGER_ATTACH_FAILED', () => this.workerFactory(event => this.event(s, event)));
                 remaining();
-                s.cleanup.remaining_resources.push('jdi_worker');
+                s.cleanup.remaining_resources.push(this.workerResource);
+                if (this.platform === 'ios')
+                    await atStage('target_resolution', 'DEBUGGER_ATTACH_FAILED', () => this.native.identity(device, s.target));
                 stage = 'attach';
-                await atStage('attach', 'DEBUGGER_ATTACH_FAILED', () => s.worker.call('attach', { port: s.port, timeoutMs: remaining() }, remaining()));
+                await atStage('attach', 'DEBUGGER_ATTACH_FAILED', () => s.worker.call('attach', { port: s.port, ...(this.platform === 'ios' ? { pid: s.target.pid, executablePath: s.target.executable_path } : {}), timeoutMs: remaining() }, remaining()));
                 stage = 'target_resolution';
                 await atStage('target_resolution', 'DEBUGGER_ATTACH_FAILED', () => this.native.identity(device, s.target));
                 remaining();
@@ -204,7 +215,7 @@ export class DebuggerSessions {
                     s.worker = undefined;
                 }
                 catch {
-                    remaining.push('jdi_worker');
+                    remaining.push(this.workerResource);
                 }
             }
             if (s.port !== undefined && s.target) {
@@ -252,6 +263,8 @@ export class DebuggerSessions {
     assertCommandTarget(s, command, args) {
         if (!s.worker || ['detaching', 'detached', 'disconnected', 'failed'].includes(s.state))
             throw new DebuggerError('DEBUGGER_DISCONNECTED', s.diagnostic ?? diagnostic('command', 'unavailable'));
+        if (command === 'set' && (this.platform === 'ios' ? typeof args.sourceFile !== 'string' || args.className !== undefined : typeof args.className !== 'string' || args.sourceFile !== undefined))
+            throw new DebuggerError('INVALID_ARGUMENT');
         if (['stack', 'locals', 'step', 'resume'].includes(command)) {
             if (args.stopId !== s.stop?.stop_id)
                 throw new DebuggerError('DEBUGGER_STALE_REFERENCE');
@@ -268,6 +281,7 @@ export class DebuggerSessions {
         if (command === 'state' && (s.cleanup.status === 'complete' || ['detaching', 'detached', 'disconnected', 'failed'].includes(s.state)))
             return this.result(s);
         this.assertCommandTarget(s, command, args);
+        const previous = { state: s.state, stop: s.stop, pausedAt: s.pausedAt };
         if (command === 'step' || command === 'resume') {
             s.state = 'running';
             s.stop = null;
@@ -278,6 +292,8 @@ export class DebuggerSessions {
             return this.result(s, command === 'state' ? { breakpoints: data.breakpoints } : { result: data });
         }
         catch (e) {
+            if (['step', 'resume'].includes(command) && s.state === 'running' && s.stop === null && e instanceof DebuggerError && ['INVALID_ARGUMENT', 'DEBUGGER_STALE_REFERENCE'].includes(e.code))
+                Object.assign(s, previous);
             return this.handleCommandError(s, command, classify(e, 'command', 'DEBUGGER_WORKER_FAILED'));
         }
     }
@@ -301,4 +317,5 @@ export class DebuggerSessions {
     async shutdown() { this.closing = true; await Promise.allSettled([...this.sessions.values()].filter(s => s.cleanup.status !== 'complete').map(s => this.serial(s, () => this.cleanup(s, true)))); return [...this.sessions.values()].filter(s => s.cleanup.status !== 'complete').map(s => this.result(s)); }
 }
 export const debuggerSessions = new DebuggerSessions();
-registerDebuggerPauseProvider(device => debuggerSessions.paused(device));
+export const iosDebuggerSessions = new DebuggerSessions(new IOSDebugNative(), createIOSWorker, prepareIOSWorker, { platform: 'ios', capabilities: iosCapabilities, limitations: iosLimitations });
+registerDebuggerPauseProvider((device, platform = 'android') => (platform === 'ios' ? iosDebuggerSessions : debuggerSessions).paused(device));

package/dist/debugger/worker.js

@@ -63,7 +63,7 @@ export async function prepareWorker() {
     return compiled;
 }
 function commandStage(command) { return command === 'attach' ? 'attach' : command === 'detach' ? 'cleanup' : 'command'; }
-export class JdiWorker {
+export class DebuggerProcess {
     onEvent;
     child;
     pending = new Map();
@@ -72,9 +72,9 @@ export class JdiWorker {
     failure;
     replied = false;
     exited;
-    constructor(java, directory, onEvent) {
+    constructor(java, directory, onEvent, launch) {
         this.onEvent = onEvent;
-        this.child = spawn(java, ['-Xmx128m', '--add-modules', 'jdk.jdi', '-cp', directory, 'DebuggerWorker'], { stdio: ['pipe', 'pipe', 'pipe'] });
+        this.child = spawn(java, launch?.args ?? ['-Xmx128m', '--add-modules', 'jdk.jdi', '-cp', directory, 'DebuggerWorker'], { stdio: ['pipe', 'pipe', 'pipe'], ...(launch ? { env: launch.env } : {}) });
         let buffer = '';
         this.exited = new Promise(resolve => { this.child.once('exit', () => { this.fail('process_exited'); resolve(); }); this.child.once('error', () => { this.fail('spawn_failed'); resolve(); }); });
         this.child.stdin.on('error', () => this.fail('write_failed'));
@@ -172,5 +172,7 @@ export class JdiWorker {
 }
 export async function createWorker(onEvent) {
     const { java, directory } = await prepareWorker();
-    return new JdiWorker(java, directory, onEvent);
+    return new DebuggerProcess(java, directory, onEvent);
 }
+// Compatibility export for existing JDI transport callers/tests.
+export { DebuggerProcess as JdiWorker };

package/dist/interact/index.js

@@ -105,11 +105,21 @@ export class ToolsInteract {
         const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId);
         return await interact.tap(x, y, resolved.id, timeoutMs);
     }
+    static _getResolvedElement(elementId, platform, deviceId) {
+        const resolved = ToolsInteract._resolvedUiElements.get(elementId);
+        if (!resolved || (platform && resolved.platform !== platform) || (deviceId && resolved.deviceId !== deviceId))
+            return null;
+        return resolved;
+    }
+    static getResolvedElementTarget(elementId, platform, deviceId) {
+        const resolved = ToolsInteract._getResolvedElement(elementId, platform, deviceId);
+        return resolved ? { platform: resolved.platform, deviceId: resolved.deviceId } : null;
+    }
     static async tapElementHandler({ elementId, verificationMode = 'full', timeoutMs, platform, deviceId, freshTree }) {
         const actionType = 'tap_element';
         const selector = { elementId };
-        const resolved = ToolsInteract._resolvedUiElements.get(elementId);
-        if (!resolved || (platform && resolved.platform !== platform) || (deviceId && resolved.deviceId !== deviceId)) {
+        const resolved = ToolsInteract._getResolvedElement(elementId, platform, deviceId);
+        if (!resolved) {
             return ToolsInteract._actionFailure(actionType, selector, null, 'STALE_REFERENCE', true, null);
         }
         const fingerprintBefore = verificationMode === 'full' ? await ToolsInteract._captureFingerprint(resolved.platform, resolved.deviceId) : null;

package/dist/manage/ios.js

@@ -1,3 +1,4 @@
+import { checkDebuggerGuard } from '../debugger/guard.js';
 import { buildIOS } from './ios/build.js';
 import { evidenceDispatch } from '../observe/evidence.js';
 import { hasFiniteBudget, markDispatchStarted, remainingBudget, runWithBudget } from '../utils/operation-budget.js';
@@ -156,6 +157,7 @@ export class iOSManage {
 }
 async function installWithIdb(toInstall, deviceId) {
     await new Promise((resolve, reject) => {
+        checkDebuggerGuard(true);
         const proc = spawn(getIdbCmd(), ['install', toInstall, '--udid', deviceId]);
         let stderr = '';
         proc.stderr.on('data', d => stderr += d.toString());

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

@@ -0,0 +1,63 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { XMLParser, XMLValidator } from 'fast-xml-parser';
+import { getXcrunCmd } from '../../utils/ios/utils.js';
+import { traceCommand, spawnTrace } from './process.js';
+export const IOS_TRACE_MAX_BYTES = 256 * 1024 * 1024;
+export async function traceSize(root, secure = false) {
+    const stat = await fs.lstat(root);
+    if (stat.isSymbolicLink() || (!stat.isFile() && !stat.isDirectory()))
+        throw new Error('UNSAFE_ARTIFACT');
+    if (secure)
+        await fs.chmod(root, stat.isDirectory() ? 0o700 : 0o600);
+    if (stat.isFile())
+        return stat.size;
+    let size = 0;
+    for (const name of await fs.readdir(root)) {
+        size += await traceSize(path.join(root, name), secure);
+        if (size > IOS_TRACE_MAX_BYTES)
+            throw new Error('STORAGE_LIMIT');
+    }
+    return size;
+}
+export function validateToc(xml, device, app) {
+    if (XMLValidator.validate(xml) !== true)
+        throw new Error('INVALID_TOC');
+    const parsed = new XMLParser({ ignoreAttributes: false }).parse(xml);
+    const raw = parsed['trace-toc']?.run;
+    if (!raw || Array.isArray(raw))
+        throw new Error('INVALID_TOC');
+    const target = raw.info?.target;
+    if (target?.device?.['@_uuid'] !== device || Number(target.process?.['@_pid']) !== app.pid || raw.info?.summary?.['template-name'] !== 'Time Profiler')
+        throw new Error('ARTIFACT_TARGET_MISMATCH');
+    const processes = raw.processes?.process;
+    if (!(Array.isArray(processes) ? processes : [processes]).some(p => Number(p?.['@_pid']) === app.pid && p?.['@_path'] === app.executable))
+        throw new Error('ARTIFACT_APP_MISMATCH');
+    const tables = raw.data?.table;
+    if (!(Array.isArray(tables) ? tables : [tables]).some(t => t?.['@_schema'] === 'time-sample'))
+        throw new Error('SAMPLE_SCHEMA_MISSING');
+}
+export async function validateArtifact(file, device, app, spawn = spawnTrace) {
+    const size = await traceSize(file, true);
+    if (size <= 0 || size > IOS_TRACE_MAX_BYTES)
+        throw new Error('STORAGE_LIMIT');
+    const toc = path.join(path.dirname(file), 'toc.xml'), samples = path.join(path.dirname(file), 'samples.xml');
+    try {
+        await traceCommand(getXcrunCmd(), ['xctrace', 'export', '--input', file, '--toc', '--output', toc], 15000, spawn);
+        if ((await fs.stat(toc)).size > 1024 * 1024)
+            throw new Error('INVALID_TOC');
+        validateToc(await fs.readFile(toc, 'utf8'), device, app);
+        await traceCommand(getXcrunCmd(), ['xctrace', 'export', '--input', file, '--xpath', '/trace-toc/run[@number="1"]/data/table[@schema="time-sample"]', '--output', samples], 15000, spawn);
+        if ((await fs.stat(samples)).size > IOS_TRACE_MAX_BYTES)
+            throw new Error('STORAGE_LIMIT');
+        const xml = await fs.readFile(samples, 'utf8');
+        if (XMLValidator.validate(xml) !== true || !xml.includes('<trace-query-result>'))
+            throw new Error('INVALID_SAMPLES');
+        const sample_rows = (xml.match(/<row(?:\s|>)/g) ?? []).length;
+        return { path: file, format: 'instruments', kind: (await fs.stat(file)).isDirectory() ? 'directory' : 'file',
+            size_bytes: size, validation: { readable: true, schema: 'time-sample', sample_rows } };
+    }
+    finally {
+        await Promise.all([toc, samples].map(p => fs.rm(p, { force: true })));
+    }
+}

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

@@ -0,0 +1,86 @@
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { getXcrunCmd } from '../../utils/ios/utils.js';
+import { traceCommand, spawnTrace } from './process.js';
+import { prepareNotification } from './notification.js';
+export const IOS_TEMPLATES = ['System Trace', 'Time Profiler', 'Animation Hitches', 'Hangs'];
+export async function resolveIosApp(device, appId, spawn = spawnTrace) {
+    const run = (args) => traceCommand(getXcrunCmd(), args, 10000, spawn);
+    const container = await run(['simctl', 'get_app_container', device, appId, 'app']);
+    if (!path.isAbsolute(container) || !container.endsWith('.app'))
+        throw new Error('APP_IDENTITY_UNAVAILABLE');
+    const output = await run(['simctl', 'spawn', device, 'launchctl', 'list']);
+    const ids = output.split('\n').filter(line => line.includes(`UIKitApplication:${appId}[`))
+        .map(line => Number(line.trim().split(/\s+/)[0])).filter(pid => Number.isSafeInteger(pid) && pid > 1);
+    if (ids.length !== 1)
+        throw new Error('APP_NOT_RUNNING');
+    const executable = await traceCommand('/bin/ps', ['-p', String(ids[0]), '-o', 'comm='], 10000, spawn);
+    if (!executable.startsWith(container + '/') || executable.includes('\n'))
+        throw new Error('APP_IDENTITY_UNAVAILABLE');
+    const started_at = await traceCommand('/bin/ps', ['-p', String(ids[0]), '-o', 'lstart='], 10000, spawn);
+    if (!started_at || started_at.includes('\n'))
+        throw new Error('APP_IDENTITY_UNAVAILABLE');
+    return { app_id: appId, pid: ids[0], executable, started_at };
+}
+export async function iosCapabilities(device, appId, template = 'Time Profiler', spawn = spawnTrace, host = process.platform) {
+    const result = {
+        supported: false, backend: 'xctrace', device: null, xcode_version: null,
+        prerequisites: { host: host === 'darwin' ? 'available' : 'missing', permissions: 'unknown', symbols: 'unknown' },
+        reasons: [], recovery: [], discovered_templates: [], templates: [], app: null,
+        limitations: ['App attachment may include sensitive system metadata, paths, logs and signposts.', 'Permissions and symbolication are not established by discovery.', 'Physical iOS capture is not supported in the initial matrix.']
+    };
+    if (host !== 'darwin') {
+        result.reasons.push('MACOS_REQUIRED');
+        return result;
+    }
+    const probe = async (key, fn, recovery) => {
+        try {
+            await fn();
+            result.prerequisites[key] = 'available';
+        }
+        catch (error) {
+            result.prerequisites[key] = 'missing';
+            result.reasons.push(error instanceof Error && ['APP_NOT_RUNNING', 'APP_IDENTITY_UNAVAILABLE'].includes(error.message) ? error.message : key.toUpperCase() + '_UNAVAILABLE');
+            result.recovery.push(recovery);
+        }
+    };
+    await probe('xcode', async () => { result.xcode_version = await traceCommand(getXcrunCmd(), ['xcodebuild', '-version'], 10000, spawn); }, 'Select a full Xcode installation with xcode-select.');
+    await probe('templates', async () => {
+        const output = await traceCommand(getXcrunCmd(), ['xctrace', 'list', 'templates'], 10000, spawn);
+        result.discovered_templates = output.split('\n').map(s => s.trim()).filter(s => s && !s.startsWith('=='));
+    }, 'Install/select Xcode with Instruments and run xcrun xctrace list templates.');
+    await probe('instruments_targets', async () => {
+        const targets = await traceCommand(getXcrunCmd(), ['xctrace', 'list', 'devices'], 15000, spawn);
+        if (!targets.includes(`(${device})`))
+            throw new Error('TARGET_UNAVAILABLE');
+    }, 'Check xcrun xctrace list devices; use a simulator visible to Instruments.');
+    await probe('target', async () => {
+        const data = JSON.parse(await traceCommand(getXcrunCmd(), ['simctl', 'list', 'devices', '--json'], 10000, spawn));
+        const entries = Object.entries(data.devices).flatMap(([runtime, values]) => values.map(value => ({ ...value, runtime })));
+        const target = entries.find(d => d.udid === device);
+        if (!target || !target.isAvailable || target.state !== 'Booted')
+            throw new Error('TARGET_UNAVAILABLE');
+        result.device = { platform: 'ios', id: target.udid, simulator: true, model: target.name, osVersion: target.runtime.split('iOS-')[1]?.replaceAll('-', '.') ?? target.runtime };
+    }, 'Use an explicit booted simulator UDID. Physical devices and the Mac host are unsupported.');
+    await probe('notification_helper', async () => {
+        const directory = await fs.mkdtemp(path.join(os.tmpdir(), 'mcp-trace-probe-'));
+        try {
+            await prepareNotification(directory, spawn);
+        }
+        finally {
+            await fs.rm(directory, { recursive: true, force: true });
+        }
+    }, 'Allow Xcode clang to compile the local Darwin-notification listener.');
+    if (appId && result.device)
+        await probe('app', async () => { result.app = await resolveIosApp(device, appId, spawn); }, 'Start the requested development app on the selected simulator before tracing.');
+    result.templates = IOS_TEMPLATES.map(name => ({ name,
+        supported: name === 'Time Profiler' && result.discovered_templates.includes(name) && result.device !== null,
+        coverage: name === 'Time Profiler' ? 'CPU samples; bundled Hangs instrument is not independently verified' : name === 'System Trace' ? 'Scheduling coverage unverified' : name === 'Hangs' ? 'Not a standalone template here' : 'Unsupported on tested simulator',
+        reason: name === 'Time Profiler' ? null : 'TEMPLATE_TARGET_UNSUPPORTED'
+    }));
+    if (!result.templates.find(t => t.name === template)?.supported)
+        result.reasons.push('TEMPLATE_TARGET_UNSUPPORTED');
+    result.supported = result.reasons.length === 0;
+    return result;
+}

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

@@ -0,0 +1,93 @@
+import { promises as fs } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { getXcrunCmd } from '../../utils/ios/utils.js';
+import { iosCapabilities, resolveIosApp } from './capabilities.js';
+import { prepareNotification, listenNotification } from './notification.js';
+import { spawnTrace, stopTraceChild, classifyTraceFailure } from './process.js';
+import { traceSize, validateArtifact, IOS_TRACE_MAX_BYTES } from './artifact.js';
+export class IosTraceNative {
+    spawn;
+    children = new Set();
+    recorders = new Set();
+    closing = false;
+    constructor(spawn = spawnTrace) {
+        this.spawn = (command, args, timeout) => {
+            if (this.closing)
+                throw new Error('TRACE_BUSY');
+            const child = spawn(command, args, timeout);
+            this.children.add(child);
+            if (args.includes('xctrace') && args.includes('record'))
+                this.recorders.add(child);
+            void child.done.then(() => { this.children.delete(child); this.recorders.delete(child); });
+            return child;
+        };
+    }
+    shutdown() {
+        this.closing = true;
+        for (const child of this.children)
+            child.signal('SIGINT');
+        const helpers = setTimeout(() => { for (const child of this.children)
+            if (!this.recorders.has(child))
+                child.signal('SIGKILL'); }, 1000);
+        const recorders = setTimeout(() => { for (const child of this.recorders)
+            child.signal('SIGKILL'); }, 8000);
+        helpers.unref();
+        recorders.unref();
+    }
+    capabilities(device, appId, template) { return iosCapabilities(device, appId, template, this.spawn); }
+    resolve(device, app) { return resolveIosApp(device, app, this.spawn); }
+    async storage(directory) {
+        const stat = await fs.statfs(directory);
+        if (stat.bavail * stat.bsize < 1024 * 1024 * 1024)
+            throw new Error('STORAGE_LIMIT');
+    }
+    async start(device, app, directory, duration, own) {
+        await this.storage(directory);
+        const binary = await prepareNotification(directory, this.spawn);
+        return this.startRecorder(device, app, directory, duration, binary, own);
+    }
+    async startRecorder(device, app, directory, duration, binary, own) {
+        const name = 'tools.mobiledebug.trace.' + randomUUID();
+        const listener = await listenNotification(binary, name, this.spawn);
+        let recording;
+        try {
+            const current = await this.resolve(device, app.app_id);
+            if (current.pid !== app.pid || current.executable !== app.executable || current.started_at !== app.started_at)
+                throw new Error('APP_IDENTITY_CHANGED');
+            const file = path.join(directory, 'capture.trace');
+            const recorder = this.spawn(getXcrunCmd(), ['xctrace', 'record', '--template', 'Time Profiler', '--device', device,
+                '--attach', String(app.pid), '--time-limit', `${duration}ms`, '--output', file, '--notify-tracing-started', name], duration + 65000);
+            recording = { recorder, file, ready_at_ms: 0 };
+            own(recording);
+            await Promise.race([listener.line('READY', 35000), recorder.done.then(result => { throw new Error(classifyTraceFailure(result)); })]);
+            if (!recorder.alive())
+                throw new Error('RECORDER_EXITED');
+            recording.ready_at_ms = Date.now();
+            return recording;
+        }
+        catch (error) {
+            if (recording)
+                await stopTraceChild(recording.recorder).catch(() => { });
+            throw error;
+        }
+        finally {
+            await stopTraceChild(listener, 1000).catch(() => { });
+        }
+    }
+    stop(recording, timeout) { return stopTraceChild(recording.recorder, timeout); }
+    async monitor(device, app, recording) {
+        const current = await this.resolve(device, app.app_id);
+        if (current.pid !== app.pid || current.executable !== app.executable || current.started_at !== app.started_at)
+            throw new Error('APP_IDENTITY_CHANGED');
+        try {
+            if (await traceSize(recording.file) > IOS_TRACE_MAX_BYTES)
+                throw new Error('STORAGE_LIMIT');
+        }
+        catch (error) {
+            if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT'))
+                throw error;
+        }
+    }
+    validate(recording, device, app) { return validateArtifact(recording.file, device, app, this.spawn); }
+}

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

@@ -0,0 +1,35 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { getXcrunCmd } from '../../utils/ios/utils.js';
+import { traceCommand, spawnTrace, stopTraceChild } from './process.js';
+// A private per-session listener avoids requiring a third-party notification utility.
+const source = `#include <notify.h>
+#include <dispatch/dispatch.h>
+#include <stdio.h>
+#include <stdlib.h>
+int main(int argc, char **argv) {
+  if (argc != 2) return 2;
+  int token;
+  if (notify_register_dispatch(argv[1], &token, dispatch_get_main_queue(), ^(int t) {
+    puts("READY"); fflush(stdout); notify_cancel(t); exit(0);
+  }) != NOTIFY_STATUS_OK) return 3;
+  puts("ARMED"); fflush(stdout); dispatch_main();
+}`;
+export async function prepareNotification(directory, spawn = spawnTrace) {
+    const file = path.join(directory, 'notification.c'), binary = path.join(directory, 'notification');
+    await fs.writeFile(file, source, { mode: 0o600 });
+    await traceCommand(getXcrunCmd(), ['clang', '-fblocks', file, '-o', binary], 30000, spawn);
+    await fs.chmod(binary, 0o700);
+    return binary;
+}
+export async function listenNotification(binary, name, spawn = spawnTrace) {
+    const listener = spawn(binary, [name], 40000);
+    try {
+        await listener.line('ARMED', 5000);
+        return listener;
+    }
+    catch (error) {
+        await stopTraceChild(listener, 1000).catch(() => { });
+        throw error;
+    }
+}

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

@@ -0,0 +1,98 @@
+import { spawn } from 'node:child_process';
+const MAX_OUTPUT = 64 * 1024;
+export const spawnTrace = (command, args, timeout) => {
+    const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let output = '', settled = false, timedOut = false;
+    const waiters = new Set();
+    let force;
+    const terminate = () => {
+        if (settled)
+            return;
+        child.kill('SIGTERM');
+        force ??= setTimeout(() => { if (!settled)
+            child.kill('SIGKILL'); }, 1000);
+        force.unref();
+    };
+    const timer = setTimeout(() => { timedOut = true; terminate(); }, timeout);
+    timer.unref();
+    const done = new Promise(resolve => {
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (force)
+                clearTimeout(force);
+            for (const wake of waiters)
+                wake();
+            resolve({ code, output, timedOut });
+        };
+        child.on('error', () => finish(null));
+        child.on('close', finish);
+        const data = (chunk) => {
+            output = (output + chunk.toString()).slice(-MAX_OUTPUT);
+            for (const wake of waiters)
+                wake();
+        };
+        child.stdout?.on('data', data);
+        child.stderr?.on('data', data);
+    });
+    return {
+        done, alive: () => !settled && child.exitCode === null && child.signalCode === null,
+        signal: signal => { if (!settled)
+            child.kill(signal); },
+        line: (text, ms) => new Promise((resolve, reject) => {
+            const deadline = setTimeout(() => { waiters.delete(check); reject(new Error('READINESS_TIMEOUT')); }, ms);
+            const check = () => {
+                if (output.split(/\r?\n/).includes(text)) {
+                    clearTimeout(deadline);
+                    waiters.delete(check);
+                    resolve();
+                }
+                else if (settled) {
+                    clearTimeout(deadline);
+                    waiters.delete(check);
+                    reject(new Error('RECORDER_EXITED'));
+                }
+            };
+            waiters.add(check);
+            check();
+        })
+    };
+};
+export async function traceCommand(command, args, timeout = 10000, spawn = spawnTrace) {
+    const result = await spawn(command, args, timeout).done;
+    if (result.code !== 0 || result.timedOut)
+        throw new Error(result.timedOut ? 'ACTION_TIMEOUT' : 'COMMAND_FAILED');
+    return result.output.trim();
+}
+export async function stopTraceChild(child, timeout = 30000) {
+    if (child.alive())
+        child.signal('SIGINT');
+    let timer;
+    const result = await Promise.race([
+        child.done,
+        new Promise(resolve => { timer = setTimeout(() => resolve(null), timeout); })
+    ]);
+    if (timer)
+        clearTimeout(timer);
+    if (result)
+        return result;
+    child.signal('SIGKILL');
+    let forceTimer;
+    await Promise.race([child.done, new Promise(resolve => { forceTimer = setTimeout(resolve, 1000); })]);
+    if (forceTimer)
+        clearTimeout(forceTimer);
+    throw new Error('ACTION_TIMEOUT');
+}
+export function classifyTraceFailure(result) {
+    if (result.timedOut)
+        return 'ACTION_TIMEOUT';
+    if (/permission|not permitted|authoriz|privacy|access denied/i.test(result.output))
+        return 'PROFILING_PERMISSION_REQUIRED';
+    if (/cannot find process|process.*not.*found/i.test(result.output))
+        return 'APP_NOT_RUNNING';
+    if (/disconnect|device.*unavailable/i.test(result.output))
+        return 'TARGET_DISCONNECTED';
+    return 'RECORDER_EXITED';
+}