mobile-debug-mcp 0.32.4 → 0.34.0

package/src/observe/snapshot-metadata.ts

@@ -14,8 +14,18 @@ interface SnapshotState {
 }
 
 let nextRevision = 1
+const snapshotSessionId = crypto.randomUUID()
 const snapshotStateByDevice = new Map<string, SnapshotState>()
 
+export function getSnapshotSessionId() { return snapshotSessionId }
+
+export function hasSnapshotBaseline(deviceKey: string, revision: number) {
+  const state = snapshotStateByDevice.get(deviceKey)
+  const capturedAt = state?.historyTimes.get(revision)
+  return !!state && capturedAt !== undefined && state.history.has(revision) &&
+    Date.now() - capturedAt <= 10 * 60 * 1000 && Date.now() - state.updatedAt <= 10 * 60 * 1000
+}
+
 function normalize(value: unknown): string {
   if (value === null || value === undefined) return ''
   return String(value).trim().toLowerCase()
@@ -163,7 +173,7 @@ export function deriveSnapshotMetadata(
   const oversized = previous?.oversized ?? new Map<number, number>()
   if (hasValidTree) {
     history.set(revision, currentElements)
-    if (!historyTimes.has(revision)) historyTimes.set(revision, Date.now())
+    historyTimes.set(revision, Date.now())
     if ((tree.elements?.length ?? 0) > 500) oversized.set(revision, (tree.elements?.length ?? 0) - 500)
   }
   for (const [id, timestamp] of historyTimes) {
@@ -191,6 +201,7 @@ export function deriveSnapshotMetadata(
   })
 
   return {
+    snapshot_session_id: snapshotSessionId,
     snapshot_revision: revision,
     captured_at_ms: Date.now(),
     snapshot_delta: hasValidTree ? summarizeSnapshotDelta(previous, currentElementSignatures) : null,

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,218 @@
+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) }
+      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'
+      }
+      return this.snapshot(s)
+    })
+  }
+  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()

package/src/server/common.ts

@@ -1,3 +1,4 @@
+import { currentEvidenceActionId } from '../observe/evidence.js'
 import { recordTiming } from '../utils/timing.js'
 import type {
   ActionTrace,
@@ -11,6 +12,7 @@ import type {
   TraceStep
 } from '../types.js'
 import { ToolsObserve } from '../observe/index.js'
+import { isConditionBlocked } from '../interact/conditional-action.js'
 
 export const DEFAULT_MAX_RECOVERY_ATTEMPTS = 3
 export const DEFAULT_MAX_RETRY_DEPTH = 3
@@ -87,11 +89,14 @@ export function getArrayArg<T>(args: ToolCallArgs, key: string): T[] | undefined
 let actionSequence = 0
 
 export function nextActionId(actionType: string, timestamp: number) {
+  const current = currentEvidenceActionId()
+  if (current) return current
   actionSequence += 1
   return `${actionType}_${timestamp}_${actionSequence}`
 }
 
 export async function captureActionFingerprint(platform?: 'android' | 'ios', deviceId?: string): Promise<string | null> {
+  if (isConditionBlocked()) return null
   if (!platform) return null
   try {
     const result = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }) as any
@@ -317,6 +322,8 @@ function mapFailureCodeToFailureClass(code: ActionFailureCode): FailureClass {
     case 'STALE_REFERENCE':
       return 'TargetResolutionFailure'
     case 'ELEMENT_NOT_INTERACTABLE':
+    case 'PRECONDITION_FAILED':
+    case 'PRECONDITION_UNAVAILABLE':
     case 'ACTION_TIMEOUT':
       return 'ExecutionFailure'
     case 'TIMEOUT':

package/src/server/condition-schema.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod'
+
+export const conditionalTools = new Set(['tap', 'tap_element', 'swipe', 'type_text', 'press_back'])
+export const expectedStateSchema = z.object({
+  snapshotSessionId: z.string().min(1),
+  snapshotRevision: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+  timeoutMs: z.number().int().min(100).max(60000).optional()
+}).strict()
+
+export type ExpectedState = z.infer<typeof expectedStateSchema>
+
+export const expectedStateJson = {
+  type: 'object', additionalProperties: false,
+  properties: {
+    snapshotSessionId: { type: 'string', minLength: 1 },
+    snapshotRevision: { type: 'integer', minimum: 1, maximum: Number.MAX_SAFE_INTEGER },
+    timeoutMs: { type: 'integer', minimum: 100, maximum: 60000, default: 15000 }
+  },
+  required: ['snapshotSessionId', 'snapshotRevision']
+}
+
+export function validateExpectedState(name: string, args: Record<string, unknown>): ExpectedState | undefined {
+  if (args.expectedState === undefined) return undefined
+  if (!conditionalTools.has(name)) throw new Error('INVALID_ARGUMENT: expectedState is not supported on this tool')
+  const parsed = expectedStateSchema.safeParse(args.expectedState)
+  if (!parsed.success) throw new Error('INVALID_ARGUMENT: invalid expectedState')
+  if ((args.platform !== 'android' && args.platform !== 'ios') ||
+      typeof args.deviceId !== 'string' || !args.deviceId.trim() ||
+      ['booted', 'default'].includes(args.deviceId)) throw new Error('INVALID_ARGUMENT: expectedState requires an explicit platform and concrete deviceId')
+  if (['type_text', 'press_back'].includes(name) && args.platform !== 'android') throw new Error('INVALID_ARGUMENT: this action supports only Android')
+  return parsed.data
+}

package/src/server/debugger-handlers.ts

@@ -0,0 +1,29 @@
+import { debuggerContracts } from './debugger-schema.js'
+import { debuggerSessions, debuggerCapabilities } from '../debugger/sessions.js'
+import { DebuggerError, withDebuggerBudget } from '../debugger/worker.js'
+import { wrapResponse, type ToolCallArgs } from './common.js'
+function failure(code: string, summary: Record<string, unknown> = {}) {
+  return { ...wrapResponse({ debug_session_id: null, device: null, target: null, state: null,
+    captured_at_ms: Date.now(), capabilities: debuggerCapabilities, limitations: [], cleanup: null,
+    ...summary, success: false, error: { code, message: code, retryable: false } }), isError: true }
+}
+export async function handleDebugger(name: string, args: ToolCallArgs, signal?: AbortSignal) {
+  const parsed = debuggerContracts[name].schema.safeParse(args)
+  if (!parsed.success) return failure('INVALID_ARGUMENT')
+  const a = parsed.data as Record<string, any>
+  const command = debuggerContracts[name].command
+  try {
+    if (signal?.aborted) throw new DebuggerError('DEBUGGER_CANCELLED')
+    const result = await withDebuggerBudget(a.timeoutMs, signal, async () => command === 'capabilities' ? await debuggerSessions.capabilities(a.deviceId, a.appId, a.processId) :
+      command === 'attach' ? await debuggerSessions.attach(a.deviceId, a.appId, a.processId, a.timeoutMs) :
+      await debuggerSessions.command(a.debugSessionId, command, { ...a, signal: command === 'events' ? signal : undefined }, a.timeoutMs))
+    if (signal?.aborted && command === 'capabilities') throw new DebuggerError('DEBUGGER_CANCELLED')
+    return { ...wrapResponse(result), ...(!result.success ? { isError: true } : {}) }
+  } catch (e) {
+    const code = e instanceof DebuggerError ? e.code : 'DEBUGGER_WORKER_FAILED'
+    let summary: any = {}
+    if (a.debugSessionId) { try { summary = debuggerSessions.summary(a.debugSessionId) } catch { /* Unknown session */ } }
+    return failure(code, { debug_session_id: a.debugSessionId ?? null,
+      device: a.deviceId ? { platform: 'android', id: a.deviceId } : null, ...summary })
+  }
+}

package/src/server/debugger-schema.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod'
+const text = z.string().min(1).max(512)
+const integer = z.number().int().safe().positive()
+const timeout = z.number().int().min(100).max(30000)
+const target = { platform: z.literal('android'), deviceId: text, appId: text.regex(/^[A-Za-z][\w]*(?:\.[A-Za-z][\w]*)+$/), processId: integer.optional() }
+const session = { debugSessionId: text }
+const stop = { ...session, stopId: text }
+const specs = {
+  get_debugger_capabilities: { fields: target, command: 'capabilities', description: 'Probe optional Android JDK/JDWP prerequisites and matching running debuggable processes; does not attach.' },
+  attach_debugger: { fields: target, command: 'attach', description: 'Attach an owned Android JDI session. Requires an explicit device and debuggable app; choose processId when ambiguous. Stops suspend all app threads. Auto-detach: 60s paused, 5m idle, 30m total.' },
+  get_debugger_state: { fields: session, command: 'state', description: 'Read debugger state, current stop and breakpoint/cleanup status.' },
+  set_debugger_breakpoint: { fields: { ...session, className: text.regex(/^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/), line: integer }, command: 'set', description: 'Set an exact binary-class and executable-source-line breakpoint; unloaded classes remain pending. No silent line relocation.' },
+  remove_debugger_breakpoint: { fields: { ...session, breakpointId: text }, command: 'remove', description: 'Remove an owned breakpoint; repeated removal succeeds.' },
+  wait_for_debugger_event: { fields: { ...session, afterSequence: z.number().int().safe().min(0).optional() }, command: 'events', description: 'Wait for bounded debugger events after a sequence cursor. Empty timeout does not affect execution; overflow is explicit.' },
+  get_debugger_stack: { fields: { ...stop, threadId: text, offset: z.number().int().min(0).max(999).optional(), limit: z.number().int().min(1).max(100).optional() }, command: 'stack', description: 'Read bounded stack frames for a stopped thread; IDs expire on resume.' },
+  get_debugger_locals: { fields: { ...stop, frameId: text }, command: 'locals', description: 'Read at most 100 shallow locals. Sensitive values returned only on request; strings truncate at 256 characters. No evaluation or field traversal.' },
+  step_debugger: { fields: { ...stop, threadId: text, kind: z.enum(['into', 'over', 'out']) }, command: 'step', description: 'Acknowledge one-shot line stepping and resume. Wait for a subsequent stop event separately.' },
+  resume_debugger: { fields: stop, command: 'resume', description: 'Resume owned debugger suspension and immediately expire stopped references.' },
+  detach_debugger: { fields: session, command: 'detach', description: 'Dispose the owned debugger connection, release owned suspension and remove its exact forward. Idempotent; retries incomplete cleanup.' }
+}
+// Derive JSON schemas and runtime validation from the same small Zod field vocabulary.
+function jsonField(schema: z.ZodTypeAny): any {
+  if (schema instanceof z.ZodOptional) return jsonField(schema.unwrap())
+  if (schema instanceof z.ZodLiteral) return { type: 'string', enum: [schema.value] }
+  if (schema instanceof z.ZodEnum) return { type: 'string', enum: schema.options }
+  if (schema instanceof z.ZodString) return { type: 'string', minLength: 1, maxLength: 512, ...Object.assign({}, ...schema._def.checks.filter(c => c.kind === 'regex').map(c => ({ pattern: (c as any).regex.source }))) }
+  if (schema instanceof z.ZodNumber) return { type: 'integer', minimum: schema.minValue, maximum: schema.maxValue }
+  throw new Error('Unsupported debugger field schema')
+}
+export const debuggerContracts = Object.fromEntries(Object.entries(specs).map(([name, spec]) => [name, {
+  ...spec, schema: z.object({ ...spec.fields, timeoutMs: timeout.default(name === 'wait_for_debugger_event' ? 1000 : 10000) }).strict()
+}]))
+export const debuggerTools = Object.entries(debuggerContracts).map(([name, spec]) => ({ name, description: spec.description,
+  inputSchema: { type: 'object', additionalProperties: false,
+    required: Object.entries(spec.fields).filter(([, field]) => !field.isOptional()).map(([key]) => key),
+    properties: { ...Object.fromEntries(Object.entries(spec.fields).map(([key, field]) => [key, jsonField(field)])), timeoutMs: { type: 'integer', minimum: 100, maximum: 30000, default: name === 'wait_for_debugger_event' ? 1000 : 10000 } } }
+}))

package/src/server/journey-schema.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import { expectedStateSchema, expectedStateJson } from './condition-schema.js'
 
 const selector = z.object({
   text: z.string().min(1).optional(), resource_id: z.string().min(1).optional(),
@@ -23,7 +24,7 @@ const assertion = z.union([
 const id = z.string().min(1)
 const step = z.union([
   z.object({ id, type: z.literal('start_app'), appId: z.string().min(1), verificationMode: verificationMode.optional() }).strict(),
-  z.object({ id, type: z.literal('tap'), ...target, waitFor: waitFor.optional(), verificationMode: verificationMode.optional() }).strict().refine(exactlyOneTarget),
+  z.object({ id, type: z.literal('tap'), ...target, waitFor: waitFor.optional(), verificationMode: verificationMode.optional(), expectedState: expectedStateSchema.optional() }).strict().refine(exactlyOneTarget),
   z.object({ id, type: z.literal('wait'), selector, condition: z.enum(['exists', 'not_exists', 'visible', 'clickable']).optional(), timeoutMs, pollIntervalMs }).strict(),
   z.object({ id, type: z.literal('assert'), assertion, timeoutMs, pollIntervalMs }).strict()
 ])
@@ -33,6 +34,7 @@ export const tapElementControlsSchema = z.object({
 
 export const journeySchema = z.object({
   platform: z.enum(['android', 'ios']), deviceId: z.string().min(1).optional(),
+  systemTraceId: z.string().uuid().optional(),
   responseMode: z.enum(['compact', 'debug']).default('compact'), captureOnFailure: z.boolean().default(false),
   defaults: z.object({ verificationMode: verificationMode.optional(), actionTimeoutMs: z.number().int().finite().optional(), verificationTimeoutMs: z.number().int().finite().optional() }).strict().optional(),
   steps: z.array(step).min(1).max(50)
@@ -49,7 +51,7 @@ const objectJson = (properties: Record<string, unknown>, required: string[], ext
 export const journeyStepsJson = {
   type: 'array', minItems: 1, maxItems: 50, items: { oneOf: [
     objectJson({ id: { type: 'string', minLength: 1 }, type: { const: 'start_app' }, appId: { type: 'string', minLength: 1 }, verificationMode: modeJson }, ['id', 'type', 'appId']),
-    objectJson({ id: { type: 'string', minLength: 1 }, type: { const: 'tap' }, ...targetJson, verificationMode: modeJson,
+    objectJson({ id: { type: 'string', minLength: 1 }, type: { const: 'tap' }, ...targetJson, verificationMode: modeJson, expectedState: expectedStateJson,
       waitFor: objectJson({ ...intervalJson, timeoutMs: { type: 'integer', minimum: 100, maximum: 10000 }, condition: { enum: ['exists', 'visible', 'clickable'] }, match: objectJson({ index: { type: 'integer', minimum: 0 } }, []) }, [])
     }, ['id', 'type'], { oneOf: oneTargetJson }),
     objectJson({ id: { type: 'string', minLength: 1 }, type: { const: 'wait' }, selector: selectorJson, condition: { enum: ['exists', 'not_exists', 'visible', 'clickable'] }, ...intervalJson }, ['id', 'type', 'selector']),

package/src/server/readiness-schema.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod'
+const timeout = z.number().int().min(100).max(60000)
+export const readinessSchema = z.object({
+  platform: z.enum(['android', 'ios']), deviceId: z.string().min(1).optional(),
+  timeoutMs: timeout.optional(), stabilityMs: z.number().int().min(100).max(10000).optional()
+}).strict()
+export const readinessWaitSchema = readinessSchema.extend({ pollIntervalMs: z.number().int().min(100).max(1000).optional() }).strict()
+export const readinessPropertiesJson = {
+  platform: { type: 'string', enum: ['android', 'ios'] }, deviceId: { type: 'string', minLength: 1 },
+  timeoutMs: { type: 'integer', minimum: 100, maximum: 60000 },
+  stabilityMs: { type: 'integer', minimum: 100, maximum: 10000, default: 500 }
+}

package/src/server/system-trace-schema.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod'
+const target = { platform: z.enum(['android', 'ios']), deviceId: z.string().min(1).optional() }
+export const traceTargetSchema = z.object(target).strict()
+export const traceStartSchema = z.object({ ...target, durationMs: z.number().int().min(1000).max(120000).default(30000) }).strict()
+export const traceControlSchema = z.object({ traceId: z.string().uuid() }).strict()
+const properties = { platform: { type: 'string', enum: ['android', 'ios'] }, deviceId: { type: 'string', minLength: 1 } }
+export const systemTraceTools = [
+  { name: 'get_system_trace_capabilities', description: 'Probe Android Perfetto prerequisites without recording. Device-wide system tracing is optional; iOS is unsupported.',
+    inputSchema: { type: 'object', additionalProperties: false, required: ['platform'], properties } },
+  { name: 'start_system_trace', description: 'Start bounded Android Perfetto recording, returning an owned trace_id. Run an existing journey with systemTraceId, then stop to retrieve a local artifact or cancel to discard. Device-wide traces may contain sensitive system annotations; no upload.',
+    inputSchema: { type: 'object', additionalProperties: false, required: ['platform'], properties: { ...properties, durationMs: { type: 'integer', minimum: 1000, maximum: 120000, default: 30000 } } } },
+  ...['get_system_trace_status', 'stop_system_trace', 'cancel_system_trace'].map(name => ({ name,
+    description: name === 'get_system_trace_status' ? 'Reconcile an owned trace and retrieve its state; finalise duration-completed capture.' :
+      name === 'stop_system_trace' ? 'Stop owned capture gracefully and retrieve a local Perfetto artifact. Retry after a transfer/cleanup failure.' : 'Stop owned capture and discard partial files. Already completed local artifacts are retained.',
+    inputSchema: { type: 'object', additionalProperties: false, required: ['traceId'], properties: { traceId: { type: 'string', format: 'uuid' } } }
+  }))
+]