mobile-debug-mcp 0.32.4 → 0.34.0

package/dist/debugger/android.js

@@ -0,0 +1,78 @@
+import { resolveAdbCmd } from '../utils/android/utils.js';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { DebuggerError, debuggerRemaining, debuggerSignal, nativeError } from './worker.js';
+const exec = promisify(execFile);
+export class AndroidDebugNative {
+    async adb(device, args) {
+        try {
+            return (await exec(resolveAdbCmd(), ['-s', device, ...args], { timeout: debuggerRemaining(5000), signal: debuggerSignal(), maxBuffer: 1024 * 1024 })).stdout.trim();
+        }
+        catch (e) {
+            throw nativeError(e, 'DEVICE_UNAVAILABLE');
+        }
+    }
+    async identity(device, target) {
+        try {
+            const stat = await this.adb(device, ['shell', 'cat', `/proc/${target.pid}/stat`]);
+            const fields = stat.slice(stat.lastIndexOf(')') + 2).split(/\s+/);
+            const status = await this.adb(device, ['shell', 'cat', `/proc/${target.pid}/status`]);
+            const uid = Number(/^Uid:\s+(\d+)/m.exec(status)?.[1]);
+            const name = (await this.adb(device, ['shell', 'cat', `/proc/${target.pid}/cmdline`])).split('\0')[0];
+            if (!/^\d+$/.test(fields[19] ?? '') || uid !== target.uid || name !== target.process_name || (target.start_identity && fields[19] !== target.start_identity))
+                throw new Error('identity');
+            return { ...target, start_identity: fields[19] };
+        }
+        catch (e) {
+            if (e instanceof DebuggerError && ['DEBUGGER_TIMEOUT', 'DEBUGGER_CANCELLED', 'DEVICE_UNAVAILABLE'].includes(e.code))
+                throw e;
+            throw new DebuggerError('PROCESS_CHANGED');
+        }
+    }
+    async candidates(device, app) {
+        if (!/^[A-Za-z][\w]*(?:\.[A-Za-z][\w]*)+$/.test(app))
+            throw new DebuggerError('INVALID_ARGUMENT');
+        const packages = await this.adb(device, ['shell', 'cmd', 'package', 'list', 'packages', '-U', app]);
+        const uid = Number(new RegExp(`^package:${app.replaceAll('.', '\\.')} uid:(\\d+)$`, 'm').exec(packages)?.[1]);
+        if (!Number.isSafeInteger(uid))
+            throw new DebuggerError('PROCESS_NOT_FOUND');
+        // `adb jdwp` is a subscription, not a one-shot command. Bound the sample.
+        let jdwpOutput;
+        try {
+            jdwpOutput = (await exec(resolveAdbCmd(), ['-s', device, 'jdwp'], { timeout: debuggerRemaining(500), signal: debuggerSignal(), maxBuffer: 1024 * 1024 })).stdout;
+        }
+        catch (e) {
+            if (debuggerSignal()?.aborted)
+                throw new DebuggerError('DEBUGGER_CANCELLED');
+            debuggerRemaining(1);
+            if (!e.killed || e.stderr?.trim())
+                throw nativeError(e, 'DEVICE_UNAVAILABLE');
+            jdwpOutput = e.stdout ?? '';
+        }
+        const jdwp = new Set(jdwpOutput.split(/\s+/).filter(id => /^\d+$/.test(id)));
+        const ps = await this.adb(device, ['shell', 'ps', '-A', '-o', 'PID,NAME']);
+        const result = [];
+        for (const line of ps.split('\n').slice(1)) {
+            const [pid, name] = line.trim().split(/\s+/);
+            if (jdwp.has(pid) && (name === app || name.startsWith(app + ':')))
+                result.push(await this.identity(device, { app_id: app, pid: Number(pid), process_name: name, start_identity: '', uid }));
+        }
+        return result;
+    }
+    async forward(device, pid) {
+        const port = Number(await this.adb(device, ['forward', '--no-rebind', 'tcp:0', `jdwp:${pid}`]));
+        if (!Number.isInteger(port) || port <= 0 || port > 65535)
+            throw new DebuggerError('DEBUGGER_ATTACH_FAILED');
+        return port;
+    }
+    async removeForward(device, port, pid) {
+        const list = await this.adb(device, ['forward', '--list']);
+        const entry = list.split('\n').find(line => line.trim().split(/\s+/)[1] === `tcp:${port}`);
+        if (!entry)
+            return;
+        const [serial, local, remote] = entry.trim().split(/\s+/);
+        if (serial !== device || local !== `tcp:${port}` || remote !== `jdwp:${pid}`)
+            throw new DebuggerError('DEBUGGER_CLEANUP_FAILED');
+        await this.adb(device, ['forward', '--remove', `tcp:${port}`]);
+    }
+}

package/dist/debugger/guard.js

@@ -0,0 +1,30 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { DebuggerError } from './worker.js';
+let pauseProvider = () => null;
+export function registerDebuggerPauseProvider(provider) { pauseProvider = provider; }
+const context = new AsyncLocalStorage();
+export function withDebuggerGuard(platform, device, operation) {
+    return context.run({ platform, device, dispatched: false }, operation);
+}
+// Synchronous checks and native submission share a JS turn with pause updates.
+export function checkDebuggerGuard(dispatch = false) {
+    const current = context.getStore();
+    if (!current || current.platform !== 'android')
+        return;
+    if (pauseProvider(current.device))
+        throw new DebuggerError('DEBUGGER_PAUSED');
+    if (dispatch)
+        current.dispatched = true;
+}
+export function guardDispatched() { return context.getStore()?.dispatched ?? false; }
+export function pausedReadiness(device) {
+    const paused = pauseProvider(device);
+    if (!paused)
+        return null;
+    return { state: 'debugger_paused', scope: 'device_ui', basis: 'observed',
+        captured_at_ms: paused.captured_at_ms, sample_count: 0, stable_for_ms: 0, snapshot_session_id: null, snapshot_revision: null,
+        evidence: [{ code: 'DEBUGGER_PAUSED', source: 'debugger', captured_at_ms: paused.captured_at_ms, snapshot_revision: null }],
+        limitations: ['FOREGROUND_APP_UNVERIFIED', 'DEVICE_WIDE_UI_GUARD'],
+        capabilities: { loading: true, transitioning: true, settled: true, unresponsive: false, debugger_paused: true },
+        debug_session_id: paused.debug_session_id, target: paused.target };
+}

package/dist/debugger/sessions.js

@@ -0,0 +1,262 @@
+import { registerDebuggerPauseProvider } from './guard.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 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;
+}
+export class DebuggerSessions {
+    native;
+    workerFactory;
+    prerequisite;
+    sessions = new Map();
+    closing = false;
+    constructor(native = new AndroidDebugNative(), workerFactory = createWorker, prerequisite = prepareWorker) {
+        this.native = native;
+        this.workerFactory = workerFactory;
+        this.prerequisite = prerequisite;
+    }
+    prune() {
+        const terminal = [...this.sessions.values()].filter(s => s.terminalAt !== undefined && s.cleanup.status === 'complete');
+        for (const s of terminal)
+            if (Date.now() - s.terminalAt >= 600000)
+                this.sessions.delete(s.id);
+        const remaining = terminal.filter(s => this.sessions.has(s.id));
+        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; }
+    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 });
+    }
+    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'); }
+    event(s, event) {
+        if (s.cleanup.status === 'complete')
+            return;
+        if (event.event === 'stopped' && !s.cleaning) {
+            s.state = 'paused';
+            s.stop = event;
+            s.pausedAt ??= Date.now();
+        }
+        if (event.event === 'terminated' || event.event === 'worker_failed') {
+            if (!s.cleaning && s.state !== 'failed')
+                s.reason = event.reason ?? 'worker_failed';
+            if (!s.cleaning) {
+                s.state = event.event === 'worker_failed' ? 'failed' : event.reason === 'process_exit' || event.reason === 'transport_lost' ? 'disconnected' : 'detached';
+                s.stop = null;
+                // The worker has disposed or lost its transport. Cleanup remains pending until host resources are checked.
+                void this.serial(s, () => this.cleanup(s, false));
+            }
+        }
+        s.events.push({ ...event, sequence: ++s.sequence, received_at_ms: Date.now() });
+        if (s.events.length > 256)
+            s.events.shift();
+    }
+    async capabilities(device, app, pid) {
+        const prerequisites = { jdk: false, device: false, process: false };
+        let candidates = [];
+        const reasons = [];
+        try {
+            await this.prerequisite();
+            prerequisites.jdk = true;
+        }
+        catch (e) {
+            if (e instanceof DebuggerError && ['DEBUGGER_TIMEOUT', 'DEBUGGER_CANCELLED'].includes(e.code))
+                throw e;
+            reasons.push('DEBUGGER_UNSUPPORTED');
+        }
+        try {
+            candidates = await this.native.candidates(device, app);
+            prerequisites.device = true;
+            prerequisites.process = candidates.some(t => pid === undefined || pid === t.pid);
+            if (!prerequisites.process)
+                reasons.push('PROCESS_NOT_FOUND');
+        }
+        catch (e) {
+            if (e instanceof DebuggerError && ['DEBUGGER_TIMEOUT', 'DEBUGGER_CANCELLED'].includes(e.code))
+                throw e;
+            reasons.push(e instanceof DebuggerError ? e.code : 'DEVICE_UNAVAILABLE');
+        }
+        return { success: true, debug_session_id: null, device: { platform: 'android', 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: [] } };
+    }
+    async attach(device, app, pid, timeout = 10000) {
+        this.prune();
+        const owned = [...this.sessions.values()].filter(s => s.cleanup.status !== 'complete');
+        if (this.closing || owned.length >= 4 || owned.some(s => s.device === device))
+            throw new DebuggerError('DEBUGGER_BUSY');
+        const s = { id: randomUUID(), device, target: null, state: 'attaching', stop: null, reason: null,
+            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 () => {
+            const deadline = Date.now() + timeout;
+            const remaining = () => { debuggerRemaining(timeout); const ms = deadline - Date.now(); if (ms <= 0)
+                throw new DebuggerError('DEBUGGER_TIMEOUT'); return ms; };
+            try {
+                await this.prerequisite();
+                remaining();
+                const candidates = (await this.native.candidates(device, app)).filter(t => pid === undefined || t.pid === pid);
+                remaining();
+                if (!candidates.length)
+                    throw new DebuggerError('PROCESS_NOT_FOUND');
+                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));
+                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);
+                remaining();
+                if (s.state === 'attaching')
+                    s.state = 'running';
+                if (['failed', 'disconnected', 'detached'].includes(s.state))
+                    throw new DebuggerError('DEBUGGER_ATTACH_FAILED');
+                s.timer = setInterval(() => {
+                    const now = Date.now();
+                    const reason = debuggerExpiry(s.created, s.activity, s.pausedAt, now);
+                    if (reason) {
+                        s.reason = reason;
+                        void this.serial(s, () => this.cleanup(s, true));
+                    }
+                }, 1000);
+                s.timer.unref();
+            }
+            catch (e) {
+                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);
+        });
+    }
+    async cleanup(s, requestDetach) {
+        if (s.cleaning)
+            return s.cleaning;
+        s.cleaning = withDebuggerBudget(10000, undefined, async () => {
+            if (s.timer)
+                clearInterval(s.timer);
+            const terminal = ['failed', 'disconnected'].includes(s.state) ? s.state : 'detached';
+            s.state = 'detaching';
+            s.stop = null;
+            s.pausedAt = undefined;
+            const remaining = [];
+            if (s.worker) {
+                if (requestDetach) {
+                    try {
+                        await s.worker.call('detach', {}, 3000);
+                    }
+                    catch { /* EOF/transport closure is the fallback; execution remains unknown. */ }
+                }
+                try {
+                    await s.worker.close();
+                    s.worker = undefined;
+                }
+                catch {
+                    remaining.push('jdi_worker');
+                }
+            }
+            if (s.port !== undefined && s.target) {
+                try {
+                    await this.native.removeForward(s.device, s.port, s.target.pid);
+                    s.port = undefined;
+                }
+                catch {
+                    remaining.push(`forward:tcp:${s.port}`);
+                }
+            }
+            s.events = [];
+            s.cleanup = { status: remaining.length ? 'failed' : 'complete', remaining_resources: remaining };
+            s.state = terminal;
+            s.terminalAt = Date.now();
+        });
+        try {
+            await s.cleaning;
+        }
+        finally {
+            s.cleaning = undefined;
+        }
+    }
+    async command(id, command, args = {}, timeout = 10000) {
+        const s = this.get(id);
+        if (command === 'events') {
+            const deadline = Date.now() + timeout;
+            const after = args.afterSequence ?? 0;
+            if (after > s.sequence)
+                throw new DebuggerError('INVALID_ARGUMENT');
+            if (args.signal?.aborted)
+                throw new DebuggerError('DEBUGGER_CANCELLED');
+            if (s.worker && ['running', 'paused'].includes(s.state))
+                await 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');
+                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.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;
+            }
+        });
+    }
+    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));

package/dist/debugger/worker.js

@@ -0,0 +1,165 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+import { readFile, mkdtemp, chmod, rm } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { detectJavaHome } from '../utils/java.js';
+const exec = promisify(execFile);
+const operations = new AsyncLocalStorage();
+export function withDebuggerBudget(timeout, signal, operation) {
+    return operations.run({ deadline: performance.now() + timeout, signal }, operation);
+}
+export function debuggerRemaining(fallback) {
+    const context = operations.getStore();
+    if (context?.signal?.aborted)
+        throw new DebuggerError('DEBUGGER_CANCELLED');
+    const remaining = Math.floor((context?.deadline ?? Infinity) - performance.now());
+    if (remaining <= 0)
+        throw new DebuggerError('DEBUGGER_TIMEOUT');
+    return Math.min(fallback, remaining);
+}
+export function debuggerSignal() { return operations.getStore()?.signal; }
+export function nativeError(error, fallback) {
+    if (error instanceof DebuggerError)
+        return error;
+    if (debuggerSignal()?.aborted)
+        return new DebuggerError('DEBUGGER_CANCELLED');
+    if (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));
+let compiled;
+export async function prepareWorker() {
+    compiled ??= (async () => {
+        const home = await detectJavaHome({ quiet: true });
+        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 major = Number(/version "(\d+)/.exec(version.stderr)?.[1]);
+        if (!(major >= 17))
+            throw new DebuggerError('DEBUGGER_UNSUPPORTED');
+        const source = await readFile(workerSource);
+        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);
+        try {
+            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');
+        }
+        return { java, directory };
+    })().catch(error => { compiled = undefined; throw error; });
+    return compiled;
+}
+export class JdiWorker {
+    child;
+    pending = new Map();
+    sequence = 0;
+    dead = false;
+    exited;
+    constructor(java, directory, onEvent) {
+        this.child = spawn(java, ['-Xmx128m', '--add-modules', 'jdk.jdi', '-cp', directory, 'DebuggerWorker'], { stdio: ['pipe', 'pipe', 'pipe'] });
+        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.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.child.kill('SIGKILL');
+                return;
+            }
+            let end;
+            while ((end = buffer.indexOf('\n')) >= 0) {
+                const line = buffer.slice(0, end);
+                buffer = buffer.slice(end + 1);
+                try {
+                    if (Buffer.byteLength(line) > 1024 * 1024)
+                        throw new Error('IPC_LIMIT');
+                    const msg = JSON.parse(line);
+                    if (msg.event)
+                        onEvent(msg);
+                    else {
+                        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'));
+                        else
+                            request.resolve(msg.result);
+                    }
+                }
+                catch {
+                    fail();
+                    this.child.kill('SIGKILL');
+                    return;
+                }
+            }
+        });
+    }
+    call(command, args = {}, timeout = 10000) {
+        if (this.dead)
+            return Promise.reject(new DebuggerError('DEBUGGER_WORKER_FAILED'));
+        try {
+            timeout = Math.min(timeout, debuggerRemaining(timeout));
+        }
+        catch (e) {
+            return Promise.reject(e);
+        }
+        const id = ++this.sequence;
+        const message = JSON.stringify({ ...args, command, id }) + '\n';
+        if (Buffer.byteLength(message) > 1024 * 1024)
+            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 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 });
+            signal?.addEventListener('abort', abort, { once: true });
+            this.child.stdin.write(message);
+        });
+    }
+    async close() {
+        this.child.stdin.end();
+        const kill = setTimeout(() => this.child.kill('SIGKILL'), 2000);
+        try {
+            await this.exited;
+        }
+        finally {
+            clearTimeout(kill);
+        }
+    }
+}
+export async function createWorker(onEvent) {
+    const { java, directory } = await prepareWorker();
+    return new JdiWorker(java, directory, onEvent);
+}

package/dist/interact/android.js

@@ -1,3 +1,5 @@
+import { evidenceDispatch } from '../observe/evidence.js';
+import { beforeInputDispatch } from './conditional-action.js';
 import { markDispatchStarted } from '../utils/operation-budget.js';
 import { execAdb, getAndroidDeviceMetadata, getDeviceInfo } from "../utils/android/utils.js";
 import { AndroidObserve } from "../observe/index.js";
@@ -8,8 +10,9 @@ export class AndroidInteract {
         const metadata = await getAndroidDeviceMetadata("", deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
         try {
+            await beforeInputDispatch('android', deviceInfo.id);
             markDispatchStarted();
-            await execAdb(['shell', 'input', 'tap', x.toString(), y.toString()], deviceId, { timeout: timeoutMs });
+            await evidenceDispatch({ platform: 'android', id: deviceInfo.id }, () => execAdb(['shell', 'input', 'tap', x.toString(), y.toString()], deviceId, { timeout: timeoutMs }));
             return { device: deviceInfo, success: true, x, y };
         }
         catch (e) {
@@ -20,8 +23,9 @@ export class AndroidInteract {
         const metadata = await getAndroidDeviceMetadata("", deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
         try {
+            await beforeInputDispatch('android', deviceInfo.id);
             markDispatchStarted();
-            await execAdb(['shell', 'input', 'swipe', x1.toString(), y1.toString(), x2.toString(), y2.toString(), duration.toString()], deviceId, { timeout: timeoutMs });
+            await evidenceDispatch({ platform: 'android', id: deviceInfo.id }, () => execAdb(['shell', 'input', 'swipe', x1.toString(), y1.toString(), x2.toString(), y2.toString(), duration.toString()], deviceId, { timeout: timeoutMs }));
             return { device: deviceInfo, success: true, start: [x1, y1], end: [x2, y2], duration };
         }
         catch (e) {
@@ -35,8 +39,9 @@ export class AndroidInteract {
             // Encode spaces as %s to ensure proper input handling by adb shell input text
             const encodedText = text.replace(/\s/g, '%s');
             // Note: 'input text' might fail with some characters or if keyboard isn't ready, but it's the standard ADB way.
+            await beforeInputDispatch('android', deviceInfo.id);
             markDispatchStarted();
-            await execAdb(['shell', 'input', 'text', encodedText], deviceId, { timeout: timeoutMs });
+            await evidenceDispatch({ platform: 'android', id: deviceInfo.id }, () => execAdb(['shell', 'input', 'text', encodedText], deviceId, { timeout: timeoutMs }));
             return { device: deviceInfo, success: true, text };
         }
         catch (e) {
@@ -47,8 +52,9 @@ export class AndroidInteract {
         const metadata = await getAndroidDeviceMetadata("", deviceId);
         const deviceInfo = getDeviceInfo(deviceId || 'default', metadata);
         try {
+            await beforeInputDispatch('android', deviceInfo.id);
             markDispatchStarted();
-            await execAdb(['shell', 'input', 'keyevent', '4'], deviceId, { timeout: timeoutMs });
+            await evidenceDispatch({ platform: 'android', id: deviceInfo.id }, () => execAdb(['shell', 'input', 'keyevent', '4'], deviceId, { timeout: timeoutMs }));
             return { device: deviceInfo, success: true };
         }
         catch (e) {

package/dist/interact/conditional-action.js

@@ -0,0 +1,68 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { ToolsObserve } from '../observe/index.js';
+import { getSnapshotSessionId, hasSnapshotBaseline } from '../observe/snapshot-metadata.js';
+import { runWithSeparateBudget } from '../utils/operation-budget.js';
+import { ToolsNetwork } from '../network/index.js';
+const context = new AsyncLocalStorage();
+export function createConditionalAction(platform, deviceId, expected) {
+    return { platform, deviceId, expected, result: {
+            status: 'not_checked',
+            expected: { snapshot_session_id: expected.snapshotSessionId, snapshot_revision: expected.snapshotRevision },
+            observed: null, elapsed_ms: 0, reason: 'ACTION_NOT_REACHED'
+        } };
+}
+export function withConditionalAction(condition, operation) {
+    return context.run(condition, operation);
+}
+export function isConditionBlocked() {
+    const status = context.getStore()?.result.status;
+    return status === 'mismatch' || status === 'unavailable';
+}
+// Guarded calls reset the observation window only when input is about to spawn.
+export function notifyActionStart() {
+    if (!context.getStore())
+        ToolsNetwork.notifyActionStart();
+}
+export function conditionFailureCode(condition) {
+    return condition.result.status === 'mismatch' ? 'PRECONDITION_FAILED' : 'PRECONDITION_UNAVAILABLE';
+}
+export async function beforeInputDispatch(platform, deviceId) {
+    const condition = context.getStore();
+    if (!condition)
+        return;
+    const started = performance.now();
+    const result = condition.result;
+    result.status = 'unavailable';
+    delete result.reason;
+    try {
+        if (platform !== condition.platform || deviceId !== condition.deviceId)
+            result.reason = 'DEVICE_MISMATCH';
+        else if (condition.expected.snapshotSessionId !== getSnapshotSessionId())
+            result.reason = 'SESSION_MISMATCH';
+        else if (!hasSnapshotBaseline(`${platform}:${deviceId}`, condition.expected.snapshotRevision))
+            result.reason = 'BASELINE_UNAVAILABLE';
+        else {
+            const tree = await runWithSeparateBudget(condition.expected.timeoutMs ?? 15000, () => ToolsObserve.getUITreeHandler({ platform, deviceId }));
+            if (tree?.error)
+                result.reason = 'OBSERVATION_FAILED';
+            else if (!tree || !Array.isArray(tree.elements) || !Number.isSafeInteger(tree.snapshot_revision) || tree.snapshot_revision < 1 ||
+                tree.snapshot_session_id !== getSnapshotSessionId() || !Number.isFinite(tree.captured_at_ms) || tree.captured_at_ms <= 0 ||
+                !tree.resolution || !Number.isFinite(tree.resolution.width) || !Number.isFinite(tree.resolution.height) ||
+                !(tree.resolution.width > 0) || !(tree.resolution.height > 0))
+                result.reason = 'OBSERVATION_INVALID';
+            else if (tree.device?.platform !== platform || tree.device?.id !== deviceId)
+                result.reason = 'DEVICE_MISMATCH';
+            else {
+                result.observed = tree;
+                result.status = tree.snapshot_revision === condition.expected.snapshotRevision ? 'matched' : 'mismatch';
+            }
+        }
+    }
+    catch (error) {
+        result.reason = /TIMEOUT|timed out/i.test(String(error)) ? 'CONDITION_TIMEOUT' : 'OBSERVATION_FAILED';
+    }
+    result.elapsed_ms = performance.now() - started;
+    if (result.status !== 'matched')
+        throw new Error(conditionFailureCode(condition));
+    ToolsNetwork.notifyActionStart();
+}