mobile-debug-mcp 0.33.0 → 0.35.0

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

@@ -0,0 +1,135 @@
+import { execCmd } from '../utils/exec.js';
+import { getAdbCmd } from '../utils/android/utils.js';
+export const TRACE_MAX_BYTES = 32 * 1024 * 1024;
+export const TRACE_CATEGORIES = ['sched', 'freq', 'idle', 'am', 'wm', 'gfx', 'view', 'input'];
+// Encode only this fixed preset using the public Perfetto proto field numbers:
+// https://github.com/google/perfetto/tree/main/protos/perfetto/config
+// Avoid --txt (explicitly unstable), arbitrary configuration and extra tooling.
+function varint(n) {
+    const bytes = [];
+    do {
+        const byte = n % 128;
+        n = Math.floor(n / 128);
+        bytes.push(byte | (n ? 128 : 0));
+    } while (n);
+    return Buffer.from(bytes);
+}
+const uint = (field, n) => Buffer.concat([varint(field * 8), varint(n)]);
+const message = (field, value) => {
+    const bytes = Buffer.isBuffer(value) ? value : Buffer.from(value);
+    return Buffer.concat([varint(field * 8 + 2), varint(bytes.length), bytes]);
+};
+export function traceConfig(duration, categories) {
+    const ftrace = Buffer.concat(categories.map(cat => message(2, cat)));
+    const source = Buffer.concat([message(1, 'linux.ftrace'), message(100, ftrace)]);
+    return Buffer.concat([
+        message(1, Buffer.concat([uint(1, 16384), uint(4, 1)])),
+        message(2, message(1, source)), uint(3, duration), uint(8, 1), uint(10, TRACE_MAX_BYTES)
+    ]);
+}
+const quote = (value) => `'${value.replace(/'/g, `'"'"'`)}'`;
+function ownedPath(remote) {
+    if (!/^\/data\/misc\/perfetto-traces\/mcp-[0-9a-f-]{36}\.perfetto-trace$/.test(remote))
+        throw new Error('Invalid owned trace path');
+}
+export class AndroidTraceNative {
+    execute;
+    constructor(execute = execCmd) {
+        this.execute = execute;
+    }
+    async command(device, args, timeout = 10000) {
+        const result = await this.execute(getAdbCmd(), ['-s', device, ...args], { timeout });
+        if (result.exitCode !== 0)
+            throw new Error(result.stderr === 'ACTION_TIMEOUT' ? 'ACTION_TIMEOUT' : 'ADB_TRACE_COMMAND_FAILED');
+        return result.stdout;
+    }
+    shell(device, script, timeout) {
+        return this.command(device, ['shell', 'sh', '-c', quote(script)], timeout);
+    }
+    async capabilities(deviceId) {
+        const checks = {};
+        const probe = async (name, fn) => { try {
+            checks[name] = await fn();
+        }
+        catch {
+            checks[name] = false;
+        } };
+        let help = '', categories = '';
+        await probe('android_api_29', async () => Number(await this.command(deviceId, ['shell', 'getprop', 'ro.build.version.sdk'])) >= 29);
+        await probe('perfetto', async () => { const result = await this.execute(getAdbCmd(), ['-s', deviceId, 'shell', 'perfetto', '--help'], { timeout: 10000 }); help = result.stdout + result.stderr; return [0, 1].includes(result.exitCode) && help.includes('Usage: perfetto') && help.includes('--background-wait') && help.includes('--config'); });
+        await probe('tracing_service', async () => { await this.command(deviceId, ['shell', 'perfetto', '--query']); return true; });
+        await probe('writable_storage', async () => { await this.shell(deviceId, 'test -w /data/misc/perfetto-traces'); return true; });
+        await probe('process_identity', async () => { await this.shell(deviceId, 'command -v pidof >/dev/null && test -r /proc/self/stat && test -r /proc/self/cmdline'); return true; });
+        await probe('base64', async () => (await this.shell(deviceId, "printf YQ== | base64 -d")) === 'a');
+        await probe('required_categories', async () => {
+            categories = await this.command(deviceId, ['shell', 'atrace', '--list_categories']);
+            return ['sched', 'input'].every(c => new RegExp(`^\\s*${c}\\s+-`, 'm').test(categories));
+        });
+        const enabled = TRACE_CATEGORIES.filter(c => new RegExp(`^\\s*${c}\\s+-`, 'm').test(categories));
+        return { supported: Object.values(checks).every(Boolean), backend: 'perfetto', device: { platform: 'android', id: deviceId },
+            prerequisites: checks, reasons: Object.keys(checks).filter(k => !checks[k]), enabled_sources: enabled,
+            unavailable_categories: TRACE_CATEGORIES.filter(c => !enabled.includes(c)), limitations: [
+                'Device-wide scheduling and system annotations may contain sensitive information.',
+                'Host times are not aligned with device trace clocks; source availability varies.',
+                'A server crash can leave a bounded trace file on the device for manual removal.'
+            ] };
+    }
+    async start(device, remote, duration, categories) {
+        ownedPath(remote);
+        const encoded = traceConfig(duration, categories).toString('base64');
+        await this.shell(device, `umask 077; printf %s ${quote(encoded)} | base64 -d | perfetto --background-wait -c - -o ${quote(remote)}`, 35000);
+    }
+    // Scan only shell-owned readable processes. Exact output argv + executable name
+    // binds ownership even if start acknowledgement/PID output was lost.
+    async find(device, remote) {
+        ownedPath(remote);
+        const output = await this.shell(device, `pids=$(pidof perfetto); rc=$?
+      [ "$rc" -le 1 ] || exit 1
+      for pid in $pids; do
+      p=/proc/$pid
+      [ -d "$p" ] || continue
+      [ -r "$p/cmdline" ] || { [ ! -d "$p" ] && continue; exit 1; }
+      cmd=$(tr '\\000' '\\n' < "$p/cmdline" 2>/dev/null) || { [ ! -d "$p" ] && continue; exit 1; }
+      printf '%s\\n' "$cmd" | grep -Fx ${quote(remote)} >/dev/null || continue
+      first=$(printf '%s\\n' "$cmd" | head -n 1)
+      case "$first" in perfetto|/system/bin/perfetto) ;; *) continue ;; esac
+      stat=$(cat "$p/stat" 2>/dev/null) || { [ ! -d "$p" ] && continue; exit 1; }
+      rest=\${stat##*) }
+      state=$(printf '%s\\n' "$rest" | awk '{print $1}')
+      [ "$state" = Z ] && continue
+      start=$(printf '%s\\n' "$rest" | awk '{print $20}')
+      printf '%s %s\\n' "\${p##*/}" "$start"
+    done`);
+        if (!output)
+            return null;
+        const match = /^(\d+) (\d+)$/.exec(output);
+        if (!match)
+            throw new Error('TRACE_PROCESS_IDENTITY_UNAVAILABLE');
+        return { pid: Number(match[1]), startTime: match[2] };
+    }
+    async stop(device, remote, owner) {
+        ownedPath(remote);
+        if (!Number.isSafeInteger(owner.pid) || owner.pid <= 1 || !/^\d+$/.test(owner.startTime))
+            throw new Error('TRACE_PROCESS_IDENTITY_UNAVAILABLE');
+        // Recheck start time and argv in the same shell immediately before signal.
+        await this.shell(device, `p=/proc/${owner.pid}
+      [ -d "$p" ] || exit 0
+      stat=$(cat "$p/stat") || exit 1
+      rest=\${stat##*) }
+      [ "$(printf '%s\\n' "$rest" | awk '{print $20}')" = ${quote(owner.startTime)} ] || exit 1
+      cmd=$(tr '\\000' '\\n' < "$p/cmdline") || exit 1
+      first=$(printf '%s\\n' "$cmd" | head -n 1)
+      case "$first" in perfetto|/system/bin/perfetto) ;; *) exit 1 ;; esac
+      printf '%s\\n' "$cmd" | grep -Fx ${quote(remote)} >/dev/null || exit 1
+      kill -TERM ${owner.pid}`);
+    }
+    async pull(device, remote, local) {
+        ownedPath(remote);
+        // Reject oversized output before initiating transfer as well as afterwards.
+        const size = Number(await this.command(device, ['shell', 'stat', '-c', '%s', remote]));
+        if (!Number.isSafeInteger(size) || size <= 0 || size > TRACE_MAX_BYTES)
+            throw new Error('TRACE_ARTIFACT_SIZE_INVALID');
+        await this.command(device, ['pull', remote, local], 30000);
+    }
+    async remove(device, remote) { ownedPath(remote); await this.command(device, ['shell', 'rm', '-f', remote]); }
+}

package/dist/observe/system-trace.js

@@ -0,0 +1,294 @@
+import { randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { AndroidTraceNative, TRACE_MAX_BYTES } from './system-trace-android.js';
+import { evidenceSessionId } from './evidence.js';
+import { runWithBudget, remainingBudget } from '../utils/operation-budget.js';
+export class TraceError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+const clock = {
+    wall: Date.now, mono: () => performance.now(), sleep: ms => new Promise(resolve => setTimeout(resolve, ms)),
+    schedule: (fn, ms) => { const t = setTimeout(fn, ms); t.unref(); return t; }, clear: clearTimeout
+};
+export class SystemTraceSessions {
+    native;
+    time;
+    sessions = new Map();
+    closing = false;
+    constructor(native = new AndroidTraceNative(), time = clock) {
+        this.native = native;
+        this.time = time;
+    }
+    prune() {
+        const terminal = [...this.sessions.values()].filter(s => s.terminalAt !== undefined && s.result.cleanup.status === 'complete');
+        for (const s of terminal)
+            if (this.time.mono() - s.terminalAt >= 600000)
+                this.sessions.delete(s.result.trace_id);
+        const remaining = terminal.filter(s => this.sessions.has(s.result.trace_id));
+        for (const s of remaining.slice(0, Math.max(0, remaining.length - 100)))
+            this.sessions.delete(s.result.trace_id);
+    }
+    get(id) { this.prune(); const s = this.sessions.get(id); if (!s)
+        throw new TraceError('TRACE_NOT_FOUND'); return s; }
+    snapshot(s) { return structuredClone(s.result); }
+    serial(s, fn) {
+        const result = s.queue.then(fn);
+        s.queue = result.catch(() => { });
+        return result;
+    }
+    async capabilities(device) { return this.native.capabilities(device); }
+    async start(device, duration = 30000) {
+        if (!Number.isInteger(duration) || duration < 1000 || duration > 120000)
+            throw new TraceError('INVALID_ARGUMENT');
+        this.prune();
+        const reserved = [...this.sessions.values()].filter(s => s.result.cleanup.status !== 'complete');
+        if (this.closing || reserved.length >= 4 || reserved.some(s => s.result.device.id === device))
+            throw new TraceError('TRACE_BUSY');
+        const id = randomUUID();
+        const result = {
+            trace_id: id, session_id: evidenceSessionId(), device: { platform: 'android', id: device }, backend: 'perfetto',
+            state: 'starting', reason: null, completion_reason: null, capture_started_at_ms: null, capture_completed_at_ms: null,
+            artifact: null, cleanup: { status: 'pending', remaining_resources: [] }, correlation_ids: [], enabled_sources: [], unavailable_categories: []
+        };
+        const s = {
+            result, remote: `/data/misc/perfetto-traces/mcp-${id}.perfetto-trace`, owner: null, stopped: true,
+            discard: false, deadline: Infinity, queue: Promise.resolve(), linked: new Set(), partial: new Set()
+        };
+        this.sessions.set(id, s);
+        return this.serial(s, async () => {
+            let cap;
+            try {
+                cap = await this.native.capabilities(device);
+            }
+            catch {
+                this.fail(s, 'TRACE_UNSUPPORTED');
+                this.clean(s);
+                return this.snapshot(s);
+            }
+            s.result.enabled_sources = cap.enabled_sources;
+            s.result.unavailable_categories = cap.unavailable_categories;
+            if (!cap.supported || this.closing) {
+                this.fail(s, this.closing ? 'TRACE_BUSY' : 'TRACE_UNSUPPORTED');
+                this.clean(s);
+                return this.snapshot(s);
+            }
+            s.stopped = false;
+            s.result.cleanup.remaining_resources = [s.remote, 'device_capture'];
+            // Conservative host bounds include acknowledgement latency, not exact device start.
+            s.result.capture_started_at_ms = this.time.wall();
+            s.deadline = this.time.mono() + duration;
+            try {
+                await this.native.start(device, s.remote, duration, cap.enabled_sources);
+                s.owner = await this.native.find(device, s.remote);
+                s.result.state = 'recording';
+                s.timer = this.time.schedule(() => { void this.control(id, 'duration').catch(() => { }); }, Math.max(0, s.deadline - this.time.mono()));
+            }
+            catch (error) {
+                s.discard = true;
+                this.fail(s, this.code(error, 'TRACE_START_FAILED'));
+                try {
+                    await this.halt(s);
+                    await this.remove(s);
+                }
+                catch {
+                    s.result.cleanup.status = 'failed';
+                }
+            }
+            return this.snapshot(s);
+        });
+    }
+    code(error, fallback) { return error instanceof Error && error.message === 'ACTION_TIMEOUT' ? 'ACTION_TIMEOUT' : fallback; }
+    fail(s, reason) {
+        s.result.state = 'failed';
+        s.result.reason = reason;
+        s.result.completion_reason = 'error';
+        s.terminalAt = this.time.mono();
+    }
+    clean(s) {
+        s.result.cleanup = { status: 'complete', remaining_resources: [] };
+        s.terminalAt = this.time.mono();
+        this.prune();
+    }
+    async halt(s) {
+        if (s.stopped)
+            return;
+        const deadline = this.time.mono() + 10000;
+        await runWithBudget(10000, async () => {
+            const found = await this.native.find(s.result.device.id, s.remote);
+            if (found) {
+                if (s.owner && (s.owner.pid !== found.pid || s.owner.startTime !== found.startTime))
+                    throw new TraceError('TRACE_STOP_FAILED');
+                s.owner ??= found;
+                try {
+                    await this.native.stop(s.result.device.id, s.remote, s.owner);
+                }
+                catch (error) {
+                    // Natural expiry can win between identity lookup and SIGTERM. Only
+                    // confirmed absence permits finalisation; unreadable/reused identity fails.
+                    if (await this.native.find(s.result.device.id, s.remote))
+                        throw error;
+                }
+                while (await this.native.find(s.result.device.id, s.remote)) {
+                    if (this.time.mono() >= deadline)
+                        throw new TraceError('ACTION_TIMEOUT');
+                    remainingBudget();
+                    await this.time.sleep(100);
+                }
+            }
+        });
+        s.stopped = true;
+        s.result.capture_completed_at_ms = this.time.wall();
+        s.result.cleanup.remaining_resources = [s.remote];
+        for (const linked of s.linked)
+            s.partial.add(linked);
+    }
+    async remove(s) {
+        if (!s.stopped)
+            throw new TraceError('TRACE_STOP_FAILED');
+        await this.native.remove(s.result.device.id, s.remote);
+        if (s.local && !s.result.artifact) {
+            await fs.rm(s.local, { recursive: true, force: true });
+            s.local = undefined;
+        }
+        this.clean(s);
+    }
+    async artifact(s) {
+        if (s.result.artifact)
+            return;
+        s.local ??= await fs.mkdtemp(path.join(os.tmpdir(), 'mobile-debug-trace-'));
+        const local = s.local;
+        const partial = path.join(local, 'capture.partial');
+        try {
+            await fs.chmod(s.local, 0o700);
+            await this.native.pull(s.result.device.id, s.remote, partial);
+            const stat = await fs.stat(partial);
+            if (!stat.isFile() || stat.size <= 0 || stat.size > TRACE_MAX_BYTES)
+                throw new TraceError('TRACE_ARTIFACT_FAILED');
+            await fs.chmod(partial, 0o600);
+            const target = path.join(s.local, `${s.result.trace_id}.perfetto-trace`);
+            await fs.rename(partial, target);
+            s.result.artifact = { path: target, format: 'perfetto', size_bytes: stat.size };
+        }
+        catch (error) {
+            try {
+                await fs.rm(local, { recursive: true, force: true });
+                s.local = undefined;
+            }
+            catch {
+                s.result.cleanup.remaining_resources = [s.remote, local];
+            }
+            throw error;
+        }
+    }
+    async control(id, operation) {
+        const s = this.get(id);
+        return this.serial(s, async () => {
+            if (s.result.cleanup.status === 'complete')
+                return this.snapshot(s);
+            if (operation === 'status' && s.result.state === 'recording') {
+                try {
+                    if (await this.native.find(s.result.device.id, s.remote) && this.time.mono() < s.deadline)
+                        return this.snapshot(s);
+                }
+                catch (error) {
+                    this.fail(s, this.code(error, 'TRACE_STOP_FAILED'));
+                    s.result.cleanup.status = 'failed';
+                    return this.snapshot(s);
+                }
+            }
+            if (s.timer) {
+                this.time.clear(s.timer);
+                s.timer = undefined;
+            }
+            if (operation === 'cancel')
+                s.discard = true;
+            const hadStartFailure = s.discard && s.result.state === 'failed' && operation !== 'cancel';
+            s.result.state = 'stopping';
+            s.result.cleanup.status = 'pending';
+            try {
+                await this.halt(s);
+            }
+            catch (error) {
+                this.fail(s, this.code(error, 'TRACE_STOP_FAILED'));
+                s.result.cleanup.status = 'failed';
+                return this.snapshot(s);
+            }
+            if (!s.discard) {
+                try {
+                    await this.artifact(s);
+                }
+                catch (error) {
+                    this.fail(s, this.code(error, 'TRACE_ARTIFACT_FAILED'));
+                    s.result.cleanup.status = 'failed';
+                    return this.snapshot(s);
+                }
+            }
+            try {
+                await this.remove(s);
+            }
+            catch {
+                this.fail(s, 'TRACE_STOP_FAILED');
+                s.result.cleanup.status = 'failed';
+                return this.snapshot(s);
+            }
+            this.complete(s, hadStartFailure, operation);
+            return this.snapshot(s);
+        });
+    }
+    complete(s, hadStartFailure, operation) {
+        if (hadStartFailure)
+            s.result.state = 'failed';
+        else {
+            s.result.state = s.discard ? 'cancelled' : 'completed';
+            s.result.reason = s.discard ? 'TRACE_CANCELLED' : null;
+            s.result.completion_reason = s.discard ? 'cancelled' : operation === 'duration' || this.time.mono() >= s.deadline ? 'duration_limit' : 'requested';
+        }
+    }
+    async link(id, device, correlation) {
+        const s = this.get(id);
+        if (device.platform !== 'android' || device.id !== s.result.device.id)
+            throw new TraceError('TRACE_NOT_FOUND');
+        const status = await this.control(id, 'status');
+        if (device.platform !== 'android' || device.id !== status.device.id || status.state !== 'recording')
+            throw new TraceError('TRACE_NOT_FOUND');
+        // Validate again after the asynchronous status call: stop/cancel may have won.
+        return this.serial(s, async () => {
+            if (s.result.state !== 'recording' || this.time.mono() >= s.deadline)
+                throw new TraceError('TRACE_NOT_FOUND');
+            if (!s.result.correlation_ids.includes(correlation)) {
+                if (s.result.correlation_ids.length >= 1000)
+                    throw new TraceError('TRACE_BUSY');
+                s.result.correlation_ids.push(correlation);
+            }
+            s.linked.add(correlation);
+            let finish;
+            return () => finish ??= (async () => {
+                let recording = false;
+                try {
+                    recording = (await this.control(id, 'status')).state === 'recording';
+                }
+                catch { /* Unavailable state cannot establish complete coverage. */ }
+                s.linked.delete(correlation);
+                return {
+                    trace_id: id, coverage: !recording || s.partial.has(correlation) || this.time.mono() >= s.deadline ? 'partial' : 'covered',
+                    clock_alignment: 'unknown'
+                };
+            })();
+        });
+    }
+    async shutdown() {
+        this.closing = true;
+        // Independent device cleanup in parallel under one overall deadline.
+        return runWithBudget(10000, async () => {
+            await Promise.allSettled([...this.sessions.values()].filter(s => s.result.cleanup.status !== 'complete').map(s => this.control(s.result.trace_id, 'cancel')));
+            return [...this.sessions.values()].filter(s => s.result.cleanup.status !== 'complete').map(s => this.snapshot(s));
+        });
+    }
+}
+export const systemTraces = new SystemTraceSessions();