mobile-debug-mcp 0.33.0 → 0.35.0

package/src/observe/system-trace-android.ts

@@ -0,0 +1,133 @@
+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']
+export interface TraceCapabilities {
+  supported: boolean; backend: 'perfetto'; device: { platform: string; id: string } | null
+  prerequisites: Record<string, boolean>; reasons: string[]; enabled_sources: string[]; unavailable_categories: string[]; limitations: string[]
+}
+export interface TraceProcess { pid: number; startTime: string }
+export interface TraceNative {
+  capabilities(deviceId: string): Promise<TraceCapabilities>
+  start(deviceId: string, remote: string, duration: number, categories: string[]): Promise<void>
+  find(deviceId: string, remote: string): Promise<TraceProcess | null>
+  stop(deviceId: string, remote: string, owner: TraceProcess): Promise<void>
+  pull(deviceId: string, remote: string, local: string): Promise<void>
+  remove(deviceId: string, remote: string): Promise<void>
+}
+
+// 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: number): Buffer {
+  const bytes: number[] = []
+  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: number, n: number) => Buffer.concat([varint(field * 8), varint(n)])
+const message = (field: number, value: Buffer | string) => {
+  const bytes = Buffer.isBuffer(value) ? value : Buffer.from(value)
+  return Buffer.concat([varint(field * 8 + 2), varint(bytes.length), bytes])
+}
+export function traceConfig(duration: number, categories: string[]): Buffer {
+  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: string) => `'${value.replace(/'/g, `'"'"'`)}'`
+function ownedPath(remote: string) {
+  if (!/^\/data\/misc\/perfetto-traces\/mcp-[0-9a-f-]{36}\.perfetto-trace$/.test(remote)) throw new Error('Invalid owned trace path')
+}
+
+export class AndroidTraceNative implements TraceNative {
+  constructor(private execute: typeof execCmd = execCmd) {}
+  private async command(device: string, args: string[], 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
+  }
+  private shell(device: string, script: string, timeout?: number) {
+    return this.command(device, ['shell', 'sh', '-c', quote(script)], timeout)
+  }
+  async capabilities(deviceId: string): Promise<TraceCapabilities> {
+    const checks: Record<string, boolean> = {}
+    const probe = async (name: string, fn: () => Promise<boolean>) => { 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: string, remote: string, duration: number, categories: string[]) {
+    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: string, remote: string): Promise<TraceProcess | null> {
+    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: string, remote: string, owner: TraceProcess) {
+    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: string, remote: string, local: string) {
+    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: string, remote: string) { ownedPath(remote); await this.command(device, ['shell', 'rm', '-f', remote]) }
+}

package/src/observe/system-trace.ts

@@ -0,0 +1,227 @@
+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, type TraceCapabilities, type TraceNative, type TraceProcess } from './system-trace-android.js'
+import { evidenceSessionId } from './evidence.js'
+import { runWithBudget, remainingBudget } from '../utils/operation-budget.js'
+
+export class TraceError extends Error {
+  constructor(public code: string) { super(code) }
+}
+type State = 'starting' | 'recording' | 'stopping' | 'completed' | 'cancelled' | 'failed'
+type Completion = 'requested' | 'duration_limit' | 'cancelled' | 'error'
+export interface TraceResult {
+  trace_id: string; session_id: string; device: { platform: 'android'; id: string }; backend: 'perfetto'
+  state: State; reason: string | null; completion_reason: Completion | null
+  capture_started_at_ms: number | null; capture_completed_at_ms: number | null
+  artifact: { path: string; format: 'perfetto'; size_bytes: number } | null
+  cleanup: { status: 'pending' | 'complete' | 'failed'; remaining_resources: string[] }
+  correlation_ids: string[]; enabled_sources: string[]; unavailable_categories: string[]
+}
+interface Session {
+  result: TraceResult; remote: string; owner: TraceProcess | null; stopped: boolean; discard: boolean
+  timer?: ReturnType<typeof setTimeout>; terminalAt?: number; deadline: number; local?: string
+  queue: Promise<unknown>; linked: Set<string>; partial: Set<string>
+}
+export interface TraceClock {
+  wall(): number; mono(): number; sleep(ms: number): Promise<void>
+  schedule(fn: () => void, ms: number): ReturnType<typeof setTimeout>
+  clear(timer: ReturnType<typeof setTimeout>): void
+}
+const clock: TraceClock = {
+  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 {
+  private sessions = new Map<string, Session>()
+  private closing = false
+  constructor(private native: TraceNative = new AndroidTraceNative(), private time: TraceClock = clock) { }
+  private 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)
+  }
+
+  private get(id: string) { this.prune(); const s = this.sessions.get(id); if (!s) throw new TraceError('TRACE_NOT_FOUND'); return s }
+  private snapshot(s: Session): TraceResult { return structuredClone(s.result) }
+  private serial<T>(s: Session, fn: () => Promise<T>): Promise<T> {
+    const result = s.queue.then(fn)
+    s.queue = result.catch(() => { })
+    return result
+  }
+  async capabilities(device: string) { return this.native.capabilities(device) }
+  async start(device: string, duration = 30000): Promise<TraceResult> {
+    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: TraceResult = {
+      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: Session = {
+      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: TraceCapabilities
+      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)
+    })
+  }
+  private code(error: unknown, fallback: string) { return error instanceof Error && error.message === 'ACTION_TIMEOUT' ? 'ACTION_TIMEOUT' : fallback }
+  private fail(s: Session, reason: string) {
+    s.result.state = 'failed'; s.result.reason = reason; s.result.completion_reason = 'error'
+    s.terminalAt = this.time.mono()
+  }
+  private clean(s: Session) {
+    s.result.cleanup = { status: 'complete', remaining_resources: [] }
+    s.terminalAt = this.time.mono()
+    this.prune()
+  }
+  private async halt(s: Session) {
+    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)
+  }
+  private async remove(s: Session) {
+    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)
+  }
+  private async artifact(s: Session) {
+    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: string, operation: 'status' | 'stop' | 'cancel' | 'duration'): Promise<TraceResult> {
+    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)
+    })
+  }
+  private complete(s: Session, hadStartFailure: boolean, operation: string) {
+    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: string, device: { platform: string; id: string }, correlation: string) {
+    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: Promise<{ trace_id: string; coverage: string; clock_alignment: string }> | undefined
+      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()