mobile-debug-mcp 0.34.0 → 0.36.0

package/dist/debugger/sessions.js

@@ -1,10 +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;
 }
@@ -12,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)
@@ -28,21 +35,30 @@ export class DebuggerSessions {
         for (const s of remaining.slice(0, Math.max(0, remaining.length - 100)))
             this.sessions.delete(s.id);
     }
-    get(id) { this.prune(); const s = this.sessions.get(id); if (!s)
-        throw new DebuggerError('DEBUGGER_NOT_FOUND'); s.activity = Date.now(); return s; }
+    get(id) {
+        this.prune();
+        const s = this.sessions.get(id);
+        if (!s)
+            throw new DebuggerError('DEBUGGER_NOT_FOUND');
+        s.activity = Date.now();
+        return s;
+    }
     serial(s, fn) { const out = s.queue.then(fn); s.queue = out.catch(() => { }); return out; }
     result(s, payload = {}) {
         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 } } : {}), 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 });
+        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: 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; }
-    assertRunning(device) { if (this.paused(device))
-        throw new DebuggerError('DEBUGGER_PAUSED'); }
+    assertRunning(device) {
+        if (this.paused(device))
+            throw new DebuggerError('DEBUGGER_PAUSED');
+    }
     event(s, event) {
         if (s.cleanup.status === 'complete')
             return;
@@ -52,6 +68,8 @@ export class DebuggerSessions {
             s.pausedAt ??= Date.now();
         }
         if (event.event === 'terminated' || event.event === 'worker_failed') {
+            if (!s.cleaning)
+                s.diagnostic ??= event.diagnostic ?? diagnostic(event.event === 'worker_failed' ? 'ipc' : 'transport', event.reason === 'transport_lost' ? 'transport_lost' : 'unknown');
             if (!s.cleaning && s.state !== 'failed')
                 s.reason = event.reason ?? 'worker_failed';
             if (!s.cleaning) {
@@ -66,33 +84,38 @@ 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 this.prerequisite();
-            prerequisites.jdk = true;
+            await atStage('prerequisite', 'DEBUGGER_UNSUPPORTED', () => this.prerequisite());
+            prerequisites[this.platform === 'ios' ? 'lldb' : 'jdk'] = true;
         }
         catch (e) {
             if (e instanceof DebuggerError && ['DEBUGGER_TIMEOUT', 'DEBUGGER_CANCELLED'].includes(e.code))
                 throw e;
             reasons.push('DEBUGGER_UNSUPPORTED');
+            diagnostics.push(classify(e, 'prerequisite', 'DEBUGGER_UNSUPPORTED').diagnostic ?? diagnostic('prerequisite', 'unknown'));
         }
         try {
-            candidates = await this.native.candidates(device, app);
+            candidates = await atStage('target_resolution', 'DEVICE_UNAVAILABLE', () => this.native.candidates(device, app));
             prerequisites.device = true;
             prerequisites.process = candidates.some(t => pid === undefined || pid === t.pid);
-            if (!prerequisites.process)
+            if (!prerequisites.process) {
                 reasons.push('PROCESS_NOT_FOUND');
+                diagnostics.push(diagnostic('target_resolution', 'unavailable'));
+            }
         }
         catch (e) {
             if (e instanceof DebuggerError && ['DEBUGGER_TIMEOUT', 'DEBUGGER_CANCELLED'].includes(e.code))
                 throw e;
             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,
-            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();
@@ -103,27 +126,47 @@ export class DebuggerSessions {
             queue: Promise.resolve(), events: [], sequence: 0, cleanup: { status: 'pending', remaining_resources: [] }, created: Date.now(), activity: Date.now() };
         this.sessions.set(s.id, s);
         return this.serial(s, async () => {
+            let stage = 'prerequisite';
             const deadline = Date.now() + timeout;
-            const remaining = () => { debuggerRemaining(timeout); const ms = deadline - Date.now(); if (ms <= 0)
-                throw new DebuggerError('DEBUGGER_TIMEOUT'); return ms; };
+            const remaining = () => {
+                try {
+                    debuggerRemaining(timeout);
+                    const ms = deadline - Date.now();
+                    if (ms <= 0)
+                        throw new DebuggerError('DEBUGGER_TIMEOUT');
+                    return ms;
+                }
+                catch (e) {
+                    throw classify(e, stage, 'DEBUGGER_ATTACH_FAILED');
+                }
+            };
             try {
-                await this.prerequisite();
+                await atStage('prerequisite', 'DEBUGGER_ATTACH_FAILED', () => this.prerequisite());
                 remaining();
-                const candidates = (await this.native.candidates(device, app)).filter(t => pid === undefined || t.pid === pid);
+                stage = 'target_resolution';
+                const candidates = (await atStage('target_resolution', 'DEBUGGER_ATTACH_FAILED', () => this.native.candidates(device, app))).filter(t => pid === undefined || t.pid === pid);
                 remaining();
                 if (!candidates.length)
-                    throw new DebuggerError('PROCESS_NOT_FOUND');
+                    throw new DebuggerError('PROCESS_NOT_FOUND', diagnostic('target_resolution', 'unavailable'));
                 if (candidates.length > 1)
                     throw new DebuggerError('PROCESS_AMBIGUOUS');
                 s.target = candidates[0];
-                s.port = await this.native.forward(device, s.target.pid);
-                remaining();
-                s.cleanup.remaining_resources.push(`forward:tcp:${s.port}`);
-                s.worker = await this.workerFactory(event => this.event(s, event));
+                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');
-                await s.worker.call('attach', { port: s.port, timeoutMs: remaining() }, remaining());
-                await this.native.identity(device, s.target);
+                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, ...(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();
                 if (s.state === 'attaching')
                     s.state = 'running';
@@ -140,10 +183,11 @@ export class DebuggerSessions {
                 s.timer.unref();
             }
             catch (e) {
+                s.diagnostic ??= classify(e, stage, 'DEBUGGER_ATTACH_FAILED').diagnostic;
                 s.state = 'failed';
                 s.reason = e instanceof DebuggerError ? e.code : 'DEBUGGER_ATTACH_FAILED';
                 await this.cleanup(s, true);
-                return this.result(s, { success: false, error: { code: s.reason, message: s.reason, retryable: false } });
+                return this.result(s, { success: false, error: { code: s.reason, message: s.reason, retryable: false, diagnostic: s.diagnostic } });
             }
             return this.result(s);
         });
@@ -171,7 +215,7 @@ export class DebuggerSessions {
                     s.worker = undefined;
                 }
                 catch {
-                    remaining.push('jdi_worker');
+                    remaining.push(this.workerResource);
                 }
             }
             if (s.port !== undefined && s.target) {
@@ -203,60 +247,75 @@ export class DebuggerSessions {
             if (after > s.sequence)
                 throw new DebuggerError('INVALID_ARGUMENT');
             if (args.signal?.aborted)
-                throw new DebuggerError('DEBUGGER_CANCELLED');
+                throw new DebuggerError('DEBUGGER_CANCELLED', diagnostic('command', 'cancelled'));
             if (s.worker && ['running', 'paused'].includes(s.state))
-                await s.worker.call('heartbeat', {}, Math.min(timeout, 1000));
+                await atStage('command', 'DEBUGGER_WORKER_FAILED', () => s.worker.call('heartbeat', {}, Math.min(timeout, 1000)));
             while (Date.now() < deadline && !s.events.some(e => e.sequence > after) && s.cleanup.status === 'pending') {
                 if (args.signal?.aborted)
-                    throw new DebuggerError('DEBUGGER_CANCELLED');
+                    throw new DebuggerError('DEBUGGER_CANCELLED', diagnostic('command', 'cancelled'));
                 await new Promise(resolve => setTimeout(resolve, Math.min(50, deadline - Date.now())));
             }
             const events = s.events.filter(e => e.sequence > after).slice(0, 100);
             return this.result(s, { events, next_cursor: events.at(-1)?.sequence ?? s.sequence, overflow: after < (s.events[0]?.sequence ?? s.sequence + 1) - 1, timed_out: events.length === 0 });
         }
-        return this.serial(s, async () => {
-            if (command === 'detach') {
-                if (s.cleanup.status !== 'complete')
-                    await this.cleanup(s, true);
-                return this.result(s, { success: s.cleanup.status === 'complete', execution_state: 'unknown' });
-            }
-            if (command === 'state' && (s.cleanup.status === 'complete' || ['detaching', 'detached', 'disconnected', 'failed'].includes(s.state)))
+        return this.serial(s, () => this.executeCommand(s, command, args, timeout));
+    }
+    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');
+            if (s.state !== 'paused')
+                throw new DebuggerError('DEBUGGER_NOT_PAUSED');
+        }
+    }
+    async executeCommand(s, command, args, timeout) {
+        if (command === 'detach') {
+            if (s.cleanup.status !== 'complete')
+                await this.cleanup(s, true);
+            return this.result(s, { success: s.cleanup.status === 'complete', execution_state: 'unknown' });
+        }
+        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;
+            s.pausedAt = undefined;
+        }
+        try {
+            const data = await s.worker.call(command, args, timeout);
+            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'));
+        }
+    }
+    async handleCommandError(s, command, e) {
+        if (e instanceof DebuggerError && e.code === 'DEBUGGER_DISCONNECTED') {
+            s.diagnostic ??= e.diagnostic ?? diagnostic('transport', 'transport_lost');
+            s.state = 'disconnected';
+            s.reason = 'transport_lost';
+            await this.cleanup(s, false);
+            if (command === 'state')
                 return this.result(s);
-            if (!s.worker || ['detaching', 'detached', 'disconnected', 'failed'].includes(s.state))
-                throw new DebuggerError('DEBUGGER_DISCONNECTED');
-            if (['stack', 'locals', 'step', 'resume'].includes(command)) {
-                if (args.stopId !== s.stop?.stop_id)
-                    throw new DebuggerError('DEBUGGER_STALE_REFERENCE');
-                if (s.state !== 'paused')
-                    throw new DebuggerError('DEBUGGER_NOT_PAUSED');
-            }
-            if (command === 'step' || command === 'resume') {
-                s.state = 'running';
-                s.stop = null;
-                s.pausedAt = undefined;
-            }
-            try {
-                const data = await s.worker.call(command, args, timeout);
-                return this.result(s, command === 'state' ? { breakpoints: data.breakpoints } : { result: data });
-            }
-            catch (e) {
-                if (e instanceof DebuggerError && e.code === 'DEBUGGER_DISCONNECTED') {
-                    s.state = 'disconnected';
-                    s.reason = 'transport_lost';
-                    await this.cleanup(s, false);
-                    if (command === 'state')
-                        return this.result(s);
-                }
-                if ((command === 'step' || command === 'resume' || command === 'set' || command === 'remove') && e instanceof DebuggerError && ['DEBUGGER_TIMEOUT', 'DEBUGGER_CANCELLED', 'DEBUGGER_WORKER_FAILED'].includes(e.code)) {
-                    s.state = 'failed';
-                    s.reason = e.code;
-                    await this.cleanup(s, true);
-                }
-                throw e;
-            }
-        });
+        }
+        if ((command === 'step' || command === 'resume' || command === 'set' || command === 'remove') && e instanceof DebuggerError && ['DEBUGGER_TIMEOUT', 'DEBUGGER_CANCELLED', 'DEBUGGER_WORKER_FAILED'].includes(e.code)) {
+            s.diagnostic ??= e.diagnostic;
+            s.state = 'failed';
+            s.reason = e.code;
+            await this.cleanup(s, true);
+        }
+        throw e;
     }
     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

@@ -1,3 +1,6 @@
+import { DebuggerError, classify, diagnostic, atStage } from './diagnostics.js';
+export { DebuggerError } from './diagnostics.js';
+import { parseWorkerMessage } from './protocol.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { execFile, spawn } from 'node:child_process';
 import { promisify } from 'node:util';
@@ -27,71 +30,60 @@ export function nativeError(error, fallback) {
         return error;
     if (debuggerSignal()?.aborted)
         return new DebuggerError('DEBUGGER_CANCELLED');
-    if (error?.killed)
+    if (typeof error === 'object' && error !== null && 'killed' in error && error.killed)
         return new DebuggerError('DEBUGGER_TIMEOUT');
     return new DebuggerError(fallback);
 }
-export class DebuggerError extends Error {
-    code;
-    constructor(code) {
-        super(code);
-        this.code = code;
-    }
-}
-export const workerSource = fileURLToPath(new URL('../../worker/DebuggerWorker.java', import.meta.url));
+export const workerSource = fileURLToPath(new URL('../../src/debugger/java/DebuggerWorker.java', import.meta.url));
 let compiled;
 export async function prepareWorker() {
+    let stage = 'prerequisite';
     compiled ??= (async () => {
-        const home = await detectJavaHome({ quiet: true });
+        const home = await detectJavaHome({ quiet: true }).catch(e => { throw classify(e, 'prerequisite', 'DEBUGGER_ATTACH_FAILED', 'unavailable'); });
         const java = home ? path.join(home, 'bin', 'java') : 'java';
         const javac = home ? path.join(home, 'bin', 'javac') : 'javac';
-        const version = await exec(java, ['-version'], { timeout: debuggerRemaining(5000), signal: debuggerSignal() });
+        const version = await exec(java, ['-version'], { timeout: debuggerRemaining(5000), signal: debuggerSignal() }).catch(e => { throw classify(e, 'prerequisite', 'DEBUGGER_ATTACH_FAILED', debuggerSignal()?.aborted ? 'cancelled' : typeof e === 'object' && e !== null && 'killed' in e && e.killed ? 'timeout' : 'unavailable'); });
         const major = Number(/version "(\d+)/.exec(version.stderr)?.[1]);
         if (!(major >= 17))
-            throw new DebuggerError('DEBUGGER_UNSUPPORTED');
-        const source = await readFile(workerSource);
+            throw new DebuggerError('DEBUGGER_UNSUPPORTED', diagnostic('prerequisite', 'unsupported'));
+        stage = 'compilation';
+        const source = await readFile(workerSource).catch(e => { throw classify(e, 'compilation', 'DEBUGGER_ATTACH_FAILED', 'unavailable'); });
         const key = createHash('sha256').update(source).update(version.stderr).digest('hex').slice(0, 16);
-        const directory = await mkdtemp(path.join(os.tmpdir(), `mobile-debug-jdi-${key}-`));
-        await chmod(directory, 0o700);
+        const directory = await atStage('compilation', 'DEBUGGER_ATTACH_FAILED', () => mkdtemp(path.join(os.tmpdir(), `mobile-debug-jdi-${key}-`)));
         try {
+            await atStage('compilation', 'DEBUGGER_ATTACH_FAILED', () => chmod(directory, 0o700));
             await exec(javac, ['--release', '17', '--add-modules', 'jdk.jdi', '-d', directory, workerSource], { timeout: debuggerRemaining(15000), signal: debuggerSignal(), maxBuffer: 1024 * 1024 });
         }
         catch (e) {
             await rm(directory, { recursive: true, force: true });
-            throw nativeError(e, 'DEBUGGER_UNSUPPORTED');
+            throw classify(nativeError(e, 'DEBUGGER_UNSUPPORTED'), 'compilation', 'DEBUGGER_UNSUPPORTED', 'operation_failed');
         }
         return { java, directory };
-    })().catch(error => { compiled = undefined; throw error; });
+    })().catch(error => { compiled = undefined; throw classify(error, stage, 'DEBUGGER_ATTACH_FAILED'); });
     return compiled;
 }
-export class JdiWorker {
+function commandStage(command) { return command === 'attach' ? 'attach' : command === 'detach' ? 'cleanup' : 'command'; }
+export class DebuggerProcess {
+    onEvent;
     child;
     pending = new Map();
     sequence = 0;
     dead = false;
+    failure;
+    replied = false;
     exited;
-    constructor(java, directory, onEvent) {
-        this.child = spawn(java, ['-Xmx128m', '--add-modules', 'jdk.jdi', '-cp', directory, 'DebuggerWorker'], { stdio: ['pipe', 'pipe', 'pipe'] });
+    constructor(java, directory, onEvent, launch) {
+        this.onEvent = onEvent;
+        this.child = spawn(java, launch?.args ?? ['-Xmx128m', '--add-modules', 'jdk.jdi', '-cp', directory, 'DebuggerWorker'], { stdio: ['pipe', 'pipe', 'pipe'], ...(launch ? { env: launch.env } : {}) });
         let buffer = '';
-        const fail = () => {
-            if (this.dead)
-                return;
-            this.dead = true;
-            for (const request of this.pending.values()) {
-                clearTimeout(request.timer);
-                request.reject(new DebuggerError('DEBUGGER_WORKER_FAILED'));
-            }
-            this.pending.clear();
-            onEvent({ event: 'worker_failed' });
-        };
-        this.exited = new Promise(resolve => { this.child.once('exit', () => { fail(); resolve(); }); this.child.once('error', () => { fail(); resolve(); }); });
-        this.child.stdin.on('error', fail);
+        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'));
         this.child.stderr.resume(); // Never copy worker data or VM diagnostics into MCP stdout/logs.
         this.child.stdout.setEncoding('utf8');
         this.child.stdout.on('data', (chunk) => {
             buffer += chunk;
             if (Buffer.byteLength(buffer) > 2 * 1024 * 1024) {
-                fail();
+                this.fail('message_limit');
                 this.child.kill('SIGKILL');
                 return;
             }
@@ -102,37 +94,51 @@ export class JdiWorker {
                 try {
                     if (Buffer.byteLength(line) > 1024 * 1024)
                         throw new Error('IPC_LIMIT');
-                    const msg = JSON.parse(line);
-                    if (msg.event)
-                        onEvent(msg);
+                    const msg = parseWorkerMessage(JSON.parse(line));
+                    if (msg.kind === 'event')
+                        onEvent(msg.value);
                     else {
+                        this.replied = true;
                         const request = this.pending.get(msg.id);
                         if (!request)
                             continue;
                         clearTimeout(request.timer);
                         this.pending.delete(msg.id);
                         if (msg.error)
-                            request.reject(new DebuggerError(msg.error.code ?? 'DEBUGGER_WORKER_FAILED'));
+                            request.reject(classify(new DebuggerError(msg.error.code ?? 'DEBUGGER_WORKER_FAILED', msg.error.diagnostic), commandStage(request.command), 'DEBUGGER_WORKER_FAILED'));
                         else
                             request.resolve(msg.result);
                     }
                 }
                 catch {
-                    fail();
+                    this.fail(Buffer.byteLength(line) > 1024 * 1024 ? 'message_limit' : 'invalid_message');
                     this.child.kill('SIGKILL');
                     return;
                 }
             }
         });
     }
+    fail(reason) {
+        if (this.dead)
+            return;
+        this.dead = true;
+        const stage = reason === 'spawn_failed' || (reason === 'process_exited' && !this.replied) ? 'worker_start' : 'ipc';
+        this.failure = new DebuggerError('DEBUGGER_WORKER_FAILED', diagnostic(stage, reason));
+        for (const request of this.pending.values()) {
+            clearTimeout(request.timer);
+            request.reject(this.failure);
+        }
+        this.pending.clear();
+        this.onEvent({ event: 'worker_failed', diagnostic: this.failure.diagnostic });
+    }
     call(command, args = {}, timeout = 10000) {
         if (this.dead)
-            return Promise.reject(new DebuggerError('DEBUGGER_WORKER_FAILED'));
+            return Promise.reject(this.failure ?? new DebuggerError('DEBUGGER_WORKER_FAILED', diagnostic('ipc', 'unknown')));
         try {
             timeout = Math.min(timeout, debuggerRemaining(timeout));
         }
         catch (e) {
-            return Promise.reject(e);
+            return Promise.reject(classify(e, commandStage(command), 'DEBUGGER_WORKER_FAILED'));
         }
         const id = ++this.sequence;
         const message = JSON.stringify({ ...args, command, id }) + '\n';
@@ -140,12 +146,17 @@ export class JdiWorker {
             return Promise.reject(new DebuggerError('INVALID_ARGUMENT'));
         return new Promise((resolve, reject) => {
             const signal = debuggerSignal();
-            const abort = () => { this.pending.delete(id); clearTimeout(timer); reject(new DebuggerError('DEBUGGER_CANCELLED')); };
+            const abort = () => { this.pending.delete(id); clearTimeout(timer); done(); reject(new DebuggerError('DEBUGGER_CANCELLED', diagnostic(commandStage(command), 'cancelled'))); };
             const done = () => signal?.removeEventListener('abort', abort);
-            const timer = setTimeout(() => { this.pending.delete(id); done(); reject(new DebuggerError('DEBUGGER_TIMEOUT')); }, timeout);
-            this.pending.set(id, { resolve: value => { done(); resolve(value); }, reject: error => { done(); reject(error); }, timer });
+            const timer = setTimeout(() => { this.pending.delete(id); done(); reject(new DebuggerError('DEBUGGER_TIMEOUT', diagnostic(commandStage(command), 'timeout'))); }, timeout);
+            this.pending.set(id, { command, resolve: value => { done(); resolve(value); }, reject: error => { done(); reject(error); }, timer });
             signal?.addEventListener('abort', abort, { once: true });
-            this.child.stdin.write(message);
+            try {
+                this.child.stdin.write(message);
+            }
+            catch {
+                this.fail('write_failed');
+            }
         });
     }
     async close() {
@@ -161,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/adjustment/adjustment-context.js

@@ -0,0 +1,41 @@
+import { systemClock } from '../../runtime/clock.js';
+import { createTraceStep, buildActionExecutionResult } from '../../runtime/action-results.js';
+import { completeAdjustment } from './adjustment-result.js';
+export async function createAdjustment(input, deps) {
+    const platform = input.platform || 'android';
+    const tolerance = typeof input.tolerance === 'number' && Number.isFinite(input.tolerance) ? Math.max(0, input.tolerance) : null;
+    const limit = input.maxAttempts == null ? 5 : Math.max(1, Math.floor(Number(input.maxAttempts) || 1));
+    const stored = input.element_id ? deps.getHandle(input.element_id) ?? null : null;
+    const before = await deps.fingerprint(platform, input.deviceId);
+    return { clock: deps.clock ?? systemClock, input: { ...input, property: input.property === undefined ? 'value' : input.property }, platform, deviceId: input.deviceId, stored,
+        selector: input.selector ?? (input.element_id ? { elementId: input.element_id } : null), tolerance, limit, before,
+        fallback: null, trace: [], sequence: 0, observed: null, mode: 'gesture', target: null,
+        attempts: 0, cached: null, coordinatePending: false };
+}
+export function recordAdjustment(s, stage, result, metadata) {
+    s.trace.push(createTraceStep({ stage, timestamp: s.clock.now(), result, attemptIndex: s.sequence++, metadata }));
+}
+export function failAdjustment(s, code, reason, retryable = false, target = s.target, device = s.device, observed = s.observed, attempts = s.attempts, mode = s.mode, after = null) {
+    if (!s.trace.some(step => step.stage === 'resolve'))
+        recordAdjustment(s, 'resolve', 'failure', { reason, failure_code: code });
+    if (!s.trace.some(step => step.stage === 'recover'))
+        recordAdjustment(s, 'recover', retryable ? 'retry' : 'failure', {
+            reason, failure_code: code, retry_allowed: retryable, recovery_attempts: attempts, retry_depth: attempts
+        });
+    const tolerance = s.tolerance ?? 0;
+    const base = buildActionExecutionResult({ actionType: 'adjust_control', sourceModule: 'interact', device,
+        selector: s.selector, resolved: target, success: false, uiFingerprintBefore: s.before, uiFingerprintAfter: after,
+        failure: { failureCode: code, retryable }, traceSteps: s.trace,
+        details: { target_value: s.input.targetValue, tolerance, property: s.input.property, attempts,
+            adjustment_mode: mode, actual_state: observed, converged: false, within_tolerance: false, reason } });
+    return { ...base, target_state: { property: s.input.property, target_value: s.input.targetValue, tolerance },
+        actual_state: observed, within_tolerance: false, converged: false, attempts, adjustment_mode: mode };
+}
+export async function succeedAdjustment(s, p, deps, reason = 'control converged to target value', mode = s.mode, device = p.actionDevice ?? s.device) {
+    const after = await deps.fingerprint(s.platform, s.deviceId);
+    return completeAdjustment({ actionType: 'adjust_control', sourceModule: 'interact', device,
+        selector: s.selector, resolved: s.target, success: true, uiFingerprintBefore: s.before, uiFingerprintAfter: after,
+        traceSteps: s.trace, details: { target_value: p.normalizedTargetValue, tolerance: p.effectiveTolerance,
+            property: s.input.property, attempts: s.attempts, adjustment_mode: mode, actual_state: p.observed,
+            converged: true, within_tolerance: true, reason } });
+}

package/dist/interact/adjustment/adjustment-gestures.js

@@ -0,0 +1,55 @@
+import { _controlAxis, _buildConservativeControlPoint, _buildControlPoint, _buildAdjustmentProbePoints } from './control-geometry.js';
+import { recordAdjustment, succeedAdjustment, failAdjustment } from './adjustment-context.js';
+import { verifyControl } from './adjustment-semantic.js';
+function points(p) {
+    const bounds = p.bounds, range = p.valueRange, value = p.currentValue;
+    const axis = _controlAxis(p.element, bounds);
+    return { axis, target: _buildConservativeControlPoint(bounds, p.normalizedTargetValue, value, range.min, range.max, axis),
+        current: _buildControlPoint(bounds, (value - range.min) / (range.max - range.min), axis) };
+}
+export async function coordinateAdjustment(s, p, deps) {
+    if (s.coordinatePending)
+        return 'next';
+    const geometry = points(p);
+    const probes = p.inferredSliderState ? [geometry.target] : _buildAdjustmentProbePoints(p.bounds, p.normalizedTargetValue, p.currentValue, p.valueRange.min, p.valueRange.max, geometry.axis);
+    for (let i = 0; i < probes.length && s.attempts < s.limit; i++) {
+        const point = probes[i];
+        s.mode = 'coordinate';
+        recordAdjustment(s, 'execute', 'retry', { attempt: s.attempts + 1, mode: 'coordinate', point });
+        const action = await deps.tap({ platform: s.platform, x: point.x, y: point.y, deviceId: s.deviceId });
+        s.attempts++;
+        p.actionDevice = action.device ?? p.actionDevice;
+        if (!action.success) {
+            recordAdjustment(s, 'execute', 'retry', { attempt: s.attempts, mode: 'coordinate', point, success: false });
+            continue;
+        }
+        await verifyControl(s, p, deps, 'control did not converge yet');
+        if (p.verification.withinTolerance)
+            return succeedAdjustment(s, p, deps, p.verification.verification?.reason ?? 'control converged to target value');
+        s.coordinatePending = true;
+        s.cached = null;
+        if (s.attempts < s.limit)
+            return 'retry';
+    }
+    return 'next';
+}
+export async function gestureAdjustment(s, p, deps) {
+    if (s.attempts >= s.limit)
+        return 'next';
+    const geometry = points(p);
+    s.coordinatePending = false;
+    s.mode = 'gesture';
+    recordAdjustment(s, 'execute', 'retry', { attempt: s.attempts + 1, mode: 'gesture', start: geometry.current, end: geometry.target });
+    const action = await deps.swipe({ platform: s.platform, x1: geometry.current.x, y1: geometry.current.y,
+        x2: geometry.target.x, y2: geometry.target.y, duration: p.inferredSliderState ? 520 : 220, deviceId: s.deviceId });
+    s.attempts++;
+    if (!action.success) {
+        recordAdjustment(s, 'execute', 'failure', { attempt: s.attempts, mode: 'gesture', start: geometry.current, end: geometry.target, success: false });
+        return failAdjustment(s, 'UNKNOWN', action.error ?? 'adjustment gesture failed', false, s.target, action.device ?? p.actionDevice, p.observed ?? p.actualState);
+    }
+    p.actionDevice = action.device ?? p.actionDevice;
+    await verifyControl(s, p, deps, 'gesture adjustment did not converge yet');
+    if (p.verification.withinTolerance)
+        return succeedAdjustment(s, p, deps, p.verification.verification?.reason ?? 'control converged to target value');
+    return 'next';
+}