mobile-debug-mcp 0.34.0 → 0.35.0

package/src/utils/ui/index.ts

@@ -2,8 +2,8 @@ import { remainingBudget } from '../operation-budget.js'
 import crypto from 'crypto'
 import { GetUITreeResponse, GetCurrentScreenResponse, UIElement, SwipeResponse } from '../../types.js'
 
-const ANDROID_STRUCTURAL_TYPES = ['Window','Application','View','ViewGroup','LinearLayout','FrameLayout','RelativeLayout','ScrollView','RecyclerView','TextView','ImageView']
-const IOS_STRUCTURAL_TYPES = ['Window','Application','View','ViewController','UITableView','UICollectionView','UILabel','UIImageView','UIView','UIWindow','UIStackView','UITextView','UITableViewCell']
+const ANDROID_STRUCTURAL_TYPES = ['Window', 'Application', 'View', 'ViewGroup', 'LinearLayout', 'FrameLayout', 'RelativeLayout', 'ScrollView', 'RecyclerView', 'TextView', 'ImageView']
+const IOS_STRUCTURAL_TYPES = ['Window', 'Application', 'View', 'ViewController', 'UITableView', 'UICollectionView', 'UILabel', 'UIImageView', 'UIView', 'UIWindow', 'UIStackView', 'UITextView', 'UITableViewCell']
 
 function isDynamicText(t?: string): boolean {
   if (!t) return false
@@ -23,15 +23,15 @@ function normalizeElement(e: UIElement) {
     resourceId: (e.resourceId || '').toString(),
     text: typeof e.text === 'string' ? (isDynamicText(e.text) ? '' : e.text.trim().toLowerCase()) : '',
     contentDesc: (e.contentDescription || '').toString(),
-    bounds: Array.isArray(e.bounds) ? e.bounds.slice(0,4).map((n:any)=>Number(n)||0) : [0,0,0,0]
+    bounds: Array.isArray(e.bounds) ? e.bounds.slice(0, 4).map((n: number) => Number(n) || 0) : [0, 0, 0, 0]
   }
 }
 
 export function computeScreenFingerprint(tree: GetUITreeResponse, current: GetCurrentScreenResponse | null, platform: 'android' | 'ios', limit: number = 50): { fingerprint: string | null; activity?: string; error?: string } {
   try {
-    if (!tree || (tree as any).error) return { fingerprint: null, error: (tree as any).error }
+    if (!tree || tree.error) return { fingerprint: null, error: tree.error }
 
-    const activity = current && (current.activity || (current as any).shortActivity) ? (current.activity || (current as any).shortActivity) : ''
+    const activity = current && (current.activity || current.shortActivity) ? (current.activity || current.shortActivity) : ''
 
     const candidates: UIElement[] = (tree.elements || []).filter(e => {
       if (!e) return false
@@ -48,7 +48,7 @@ export function computeScreenFingerprint(tree: GetUITreeResponse, current: GetCu
 
     const filteredNormalized = normalized.filter(e => (e.text && e.text.length > 0) || (e.resourceId && e.resourceId.length > 0) || (e.contentDesc && e.contentDesc.length > 0))
 
-    filteredNormalized.sort((a,b) => {
+    filteredNormalized.sort((a, b) => {
       const ay = (a.bounds && a.bounds[1]) || 0
       const by = (b.bounds && b.bounds[1]) || 0
       if (ay !== by) return ay - by
@@ -61,7 +61,7 @@ export function computeScreenFingerprint(tree: GetUITreeResponse, current: GetCu
 
     const payload = {
       activity: platform === 'android' ? (activity || '') : '',
-      resolution: (tree as any).resolution || { width: 0, height: 0 },
+      resolution: tree.resolution || { width: 0, height: 0 },
       elements: limited.map(e => ({ type: e.type, resourceId: e.resourceId, text: e.text, contentDesc: e.contentDesc }))
     }
 
@@ -87,29 +87,10 @@ export async function scrollToElementShared(opts: {
 }): Promise<{ success: boolean; reason?: string; element?: Partial<UIElement>; scrollsPerformed: number }> {
   const { selector, direction = 'down', maxScrolls = 10, scrollAmount = 0.7, deviceId, fetchTree, swipe, stabilizationDelayMs = 350 } = opts
 
-  const matchElement = (el?: UIElement) => {
-    if (!el) return false
-    if (selector.text !== undefined && selector.text !== el.text) return false
-    if (selector.resourceId !== undefined && selector.resourceId !== el.resourceId) return false
-    if (selector.contentDesc !== undefined && selector.contentDesc !== el.contentDescription) return false
-    if (selector.className !== undefined && selector.className !== el.type) return false
-    return true
-  }
-
-  const isVisible = (el?: UIElement, resolution?: GetUITreeResponse['resolution']) => {
-    if (!el) return false
-    if (el.visible === false) return false
-    if (!el.bounds || !resolution || !resolution.width || !resolution.height) return (el.visible === undefined ? true : !!el.visible)
-    const [left, top, right, bottom] = el.bounds
-    const withinY = bottom > 0 && top < resolution.height
-    const withinX = right > 0 && left < resolution.width
-    return withinX && withinY
-  }
-
   const findVisibleMatch = (elements?: UIElement[], resolution?: GetUITreeResponse['resolution']) => {
     if (!Array.isArray(elements)) return null
     for (const e of elements) {
-      if (matchElement(e) && isVisible(e, resolution)) return e
+      if (matchElement(selector, e) && isVisible(e, resolution)) return e
     }
     return null
   }
@@ -158,7 +139,7 @@ export async function scrollToElementShared(opts: {
     try {
       await swipe(x1, y1, x2, y2, duration, deviceId)
     } catch (e) {
-      try { console.warn(`scrollToElement swipe failed: ${e instanceof Error ? e.message : String(e)}`) } catch {}
+      try { console.warn(`scrollToElement swipe failed: ${e instanceof Error ? e.message : String(e)}`) } catch { }
     }
 
     scrollsPerformed++
@@ -181,3 +162,22 @@ export async function scrollToElementShared(opts: {
 
   return { success: false, reason: 'Element not found after scrolling', scrollsPerformed: scrollsPerformed }
 }
+
+function matchElement(selector: ScrollSelector, el?: UIElement) {
+  if (!el) return false
+  if (selector.text !== undefined && selector.text !== el.text) return false
+  if (selector.resourceId !== undefined && selector.resourceId !== el.resourceId) return false
+  if (selector.contentDesc !== undefined && selector.contentDesc !== el.contentDescription) return false
+  if (selector.className !== undefined && selector.className !== el.type) return false
+  return true
+}
+
+function isVisible(el?: UIElement, resolution?: GetUITreeResponse['resolution']) {
+  if (!el) return false
+  if (el.visible === false) return false
+  if (!el.bounds || !resolution || !resolution.width || !resolution.height) return (el.visible === undefined ? true : !!el.visible)
+  const [left, top, right, bottom] = el.bounds
+  const withinY = bottom > 0 && top < resolution.height
+  const withinX = right > 0 && left < resolution.width
+  return withinX && withinY
+}

package/test/device/automated/debugger/coroutine-lifecycle.ts

@@ -0,0 +1,27 @@
+/** ADB lists every device even with -s. Compare only this serial, independent of order. */
+export function deviceForwards(table: string, deviceId: string): string[] {
+  return table.split('\n').map(row => row.trim().split(/\s+/))
+    .filter(columns => columns[0] === deviceId)
+    .map(columns => columns.join(' ')).sort()
+}
+
+/** Cleanup is part of the assessment; a finally failure must never follow a PASS. */
+export async function reportAfterCleanup<T>(
+  work: () => Promise<T>,
+  cleanup: () => Promise<void>,
+  report: (status: 'PASS' | 'FAIL', evidence?: T, error?: unknown) => void,
+): Promise<void> {
+  let evidence: T | undefined
+  let failed = false
+  let failure: unknown
+  try { evidence = await work() } catch (error) { failed = true; failure = error }
+  try { await cleanup() } catch (error) {
+    failure = failed ? new AggregateError([failure, error], `${String(failure)}; cleanup: ${String(error)}`) : error
+    failed = true
+  }
+  if (failed) {
+    report('FAIL', undefined, failure)
+    throw failure
+  }
+  report('PASS', evidence)
+}

package/test/device/automated/debugger/coroutine-support.ts

@@ -0,0 +1,140 @@
+import assert from 'node:assert/strict'
+import { execFileSync, spawn } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { readFile, readdir } from 'node:fs/promises'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+import { coroutineAppId } from '../../../fixtures/coroutine-app/build.js'
+
+type Location = { line: number; method: string; source: string; class_name?: string }
+export type Stop = { stop_id: string; thread_id: string; stops: { location: Location }[] }
+type Frame = { frame_id: string; location: Location }
+type Reply = {
+  success: boolean; debug_session_id: string; supported: boolean; next_cursor: number; overflow: boolean
+  events: (Stop & { event: string })[]; error: { code: string }; failure_code: string; dispatch_started: boolean
+  result: { breakpoint_id: string; status: string; frames: Frame[]; locals: { name: string; value: unknown }[]; availability: string }
+  elements: { text?: string; bounds: number[] }[]
+  cleanup: { status: string; remaining_resources: unknown[] }
+}
+export class CoroutineJourney {
+  readonly client = new Client({ name: 'coroutine-validation', version: '1.0.0' })
+  readonly interruption = new AbortController()
+  session = ''
+  cursor = 0
+  observations: unknown[] = []
+  constructor(readonly device: string, readonly source: string) {}
+  adb(...args: string[]) {
+    return execFileSync(process.env.ADB_PATH ?? 'adb', ['-s', this.device, ...args], { encoding: 'utf8', timeout: 15000 })
+  }
+  async connect() {
+    await this.client.connect(new StdioClientTransport({ command: process.execPath, args: ['dist/server.js'], stderr: 'pipe' }))
+  }
+  async call(name: string, args: Record<string, unknown> = {}) {
+    console.log('Coroutine MCP', name)
+    const reply = await this.client.callTool({ name, arguments: { ...args, ...(this.session ? { debugSessionId: this.session } : {}) } }, undefined, { timeout: 45000, ...(name === 'detach_debugger' ? {} : { signal: this.interruption.signal }) })
+    const content = reply.content.find(item => item.type === 'text')
+    assert.ok(content?.type === 'text')
+    return JSON.parse(content.text) as Reply
+  }
+  line(marker: string) {
+    const index = this.source.split('\n').findIndex(row => row.includes('// ' + marker))
+    assert.ok(index >= 0, marker)
+    return index + 1
+  }
+  async attach() {
+    this.cursor = 0
+    const capabilities = await this.call('get_debugger_capabilities', { platform: 'android', deviceId: this.device, appId: coroutineAppId })
+    assert.equal(capabilities.supported, true, JSON.stringify(capabilities))
+    const result = await this.call('attach_debugger', { platform: 'android', deviceId: this.device, appId: coroutineAppId, timeoutMs: 30000 })
+    this.session = result.debug_session_id ?? ''
+    assert.equal(result.success, true, JSON.stringify(result))
+  }
+  async detach() {
+    if (!this.session) return
+    const result = await this.call('detach_debugger')
+    assert.equal(result.cleanup.status, 'complete', JSON.stringify(result))
+    assert.deepEqual(result.cleanup.remaining_resources, [])
+    this.session = ''
+  }
+  async breakpoint(marker: string, suffix = '') {
+    const result = await this.call('set_debugger_breakpoint', { className: coroutineAppId + '.MainActivity' + suffix, line: this.line(marker), responseMode: 'compact' })
+    assert.ok(['verified', 'pending'].includes(result.result.status), JSON.stringify(result))
+    return result.result.breakpoint_id
+  }
+  async remove(breakpointId: string) {
+    assert.equal((await this.call('remove_debugger_breakpoint', { breakpointId })).success, true)
+  }
+  async stop(marker?: string, attempts = 10): Promise<Stop | undefined> {
+    for (let index = 0; index < attempts; index++) {
+      const result = await this.call('wait_for_debugger_event', { afterSequence: this.cursor, timeoutMs: 1000, responseMode: 'compact' })
+      assert.equal(result.success, true, JSON.stringify(result))
+      assert.equal(result.overflow, false)
+      this.cursor = result.next_cursor
+      const stop = result.events.find(event => event.event === 'stopped')
+      if (!stop) continue
+      if (marker) {
+        assert.equal(stop.stops[0].location.line, this.line(marker), JSON.stringify(stop))
+        assert.equal(stop.stops[0].location.source, 'MainActivity.kt')
+      }
+      this.observations.push({ marker, stop })
+      return stop
+    }
+    if (marker) throw new Error('Expected source stop: ' + marker)
+  }
+  async inspect(stop: Stop, label: string) {
+    const stack = await this.call('get_debugger_stack', { stopId: stop.stop_id, threadId: stop.thread_id, responseMode: 'compact' })
+    assert.equal(stack.success, true, JSON.stringify(stack))
+    const frame = stack.result.frames[0]
+    const locals = await this.call('get_debugger_locals', { stopId: stop.stop_id, frameId: frame.frame_id, responseMode: 'compact' })
+    assert.equal(locals.success, true, JSON.stringify(locals))
+    this.observations.push({ label, frames: stack.result.frames, locals: locals.result })
+    return { frameId: frame.frame_id, locals: locals.result.locals }
+  }
+  async resume(stop: Stop) {
+    assert.equal((await this.call('resume_debugger', { stopId: stop.stop_id })).success, true)
+  }
+  async step(stop: Stop, kind: string) {
+    const result = await this.call('step_debugger', { stopId: stop.stop_id, threadId: stop.thread_id, kind })
+    assert.equal(result.success, true, JSON.stringify(result))
+  }
+  async tree() { return this.call('get_ui_tree', { platform: 'android', deviceId: this.device }) }
+  async visible(text: string) {
+    for (let index = 0; index < 10; index++) {
+      if ((await this.tree()).elements.some(element => element.text === text)) return
+    }
+    throw new Error('Fresh UI did not show ' + text + ': ' + JSON.stringify(await this.tree()))
+  }
+  async tap(text: string) {
+    const button = (await this.tree()).elements.find(element => element.text?.toLowerCase() === text.toLowerCase())
+    assert.ok(button, 'UI button ' + text)
+    const [left, top, right, bottom] = button.bounds
+    // Input stays asynchronous: its shell process may wait while the VM is paused.
+    const child = spawn(process.env.ADB_PATH ?? 'adb', ['-s', this.device, 'shell', 'input', 'tap', String(Math.floor((left + right) / 2)), String(Math.floor((top + bottom) / 2))], { stdio: 'ignore' })
+    const timer = setTimeout(() => child.kill(), 15000)
+    const done = new Promise<void>((resolve, reject) => {
+      child.once('error', reject)
+      child.once('exit', code => { clearTimeout(timer); code === 0 ? resolve() : reject(new Error('Fixture tap failed: ' + code)) })
+    })
+    void done.catch(() => {})
+    return { done }
+  }
+  async cancelledWait() {
+    const controller = new AbortController()
+    const waiting = this.client.callTool({ name: 'wait_for_debugger_event', arguments: { debugSessionId: this.session, afterSequence: this.cursor, timeoutMs: 1000 } }, undefined, { signal: controller.signal, timeout: 5000 })
+    const timer = setTimeout(() => controller.abort(), 100)
+    try { await assert.rejects(waiting) } finally { clearTimeout(timer) }
+    assert.equal((await this.call('get_debugger_state')).success, true)
+  }
+}
+export async function fingerprint(directory: string): Promise<string> {
+  const hash = createHash('sha256')
+  async function visit(folder: string): Promise<void> {
+    for (const entry of (await readdir(folder, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+      const file = folder + '/' + entry.name
+      if (entry.isDirectory()) await visit(file)
+      else hash.update(file).update(await readFile(file))
+    }
+  }
+  await visit(directory)
+  return hash.digest('hex')
+}

package/test/device/automated/debugger/coroutine.android.test.ts

@@ -0,0 +1,169 @@
+import assert from 'node:assert/strict'
+import { execFileSync, spawnSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { readFile, readdir, rm } from 'node:fs/promises'
+import { buildCoroutineFixture, coroutineAppId } from '../../../fixtures/coroutine-app/build.js'
+import { CoroutineJourney, fingerprint, type Stop } from './coroutine-support.js'
+import { deviceForwards, reportAfterCleanup } from './coroutine-lifecycle.js'
+
+const device = process.env.MCP_COROUTINE_DEVICE
+const source = await readFile(new URL('../../../fixtures/coroutine-app/MainActivity.kt', import.meta.url), 'utf8')
+const hash = (value: string | Uint8Array) => createHash('sha256').update(value).digest('hex')
+
+async function requiredStop(journey: CoroutineJourney, marker?: string) {
+  const stop = await journey.stop(marker)
+  assert.ok(stop, 'Expected debugger stop')
+  return stop
+}
+async function guards(journey: CoroutineJourney, stop: Stop, frameId: string) {
+  const blocked = await journey.call('tap', { platform: 'android', deviceId: journey.device, x: 5, y: 5 })
+  assert.equal(blocked.failure_code, 'DEBUGGER_PAUSED')
+  assert.equal(blocked.dispatch_started, false)
+  await journey.resume(stop)
+  const stale = await journey.call('get_debugger_locals', { stopId: stop.stop_id, frameId })
+  assert.equal(stale.error.code, 'DEBUGGER_STALE_REFERENCE')
+}
+async function completion(journey: CoroutineJourney) {
+  await journey.attach()
+  const beforeBp = await journey.breakpoint('BREAK_BEFORE')
+  const afterBp = await journey.breakpoint('BREAK_AFTER')
+  const dispatchBp = await journey.breakpoint('BREAK_DISPATCH', '$completeWork$3')
+  const helperBp = await journey.breakpoint('BREAK_HELPER')
+  const resultBp = await journey.breakpoint('BREAK_RESULT', '$completeWork$3')
+  const tap = await journey.tap('Complete run')
+  const before = await requiredStop(journey, 'BREAK_BEFORE')
+  const values = await journey.inspect(before, 'before suspension')
+  assert.equal(values.locals.find(value => value.name === 'known')?.value, '42')
+  assert.equal(values.locals.find(value => value.name === 'firstThread')?.value, 'fixture-first')
+  await journey.remove(beforeBp)
+  await guards(journey, before, values.frameId)
+  await tap.done
+  await journey.visible('Coroutine waiting')
+  await journey.cancelledWait()
+  const release = await journey.tap('Release gate')
+  const after = await requiredStop(journey, 'BREAK_AFTER')
+  const afterValues = await journey.inspect(after, 'after suspension')
+  // A spill may not be represented as a shallow local; retain that observation.
+  const known = afterValues.locals.find(value => value.name === 'known')
+  if (known) assert.equal(known.value, '42')
+  await journey.remove(afterBp)
+  await journey.resume(after)
+  const dispatched = await requiredStop(journey, 'BREAK_DISPATCH')
+  const dispatcherValues = await journey.inspect(dispatched, 'second dispatcher')
+  assert.equal(dispatcherValues.locals.find(value => value.name === 'dispatcherThread')?.value, 'fixture-second')
+  await journey.remove(dispatchBp)
+  await journey.resume(dispatched)
+  const helper = await requiredStop(journey, 'BREAK_HELPER')
+  await journey.inspect(helper, 'nested child helper')
+  await journey.remove(helperBp)
+  await journey.step(helper, 'into')
+  const into = await requiredStop(journey, 'BREAK_INCREMENT')
+  await journey.step(into, 'over')
+  const over = await requiredStop(journey, 'BREAK_INCREMENT_RETURN')
+  await journey.step(over, 'out')
+  const out = await requiredStop(journey)
+  assert.equal(out.stops[0].location.method, 'helper')
+  await journey.resume(out)
+  const result = await requiredStop(journey, 'BREAK_RESULT')
+  const resultValues = await journey.inspect(result, 'nested result')
+  assert.equal(resultValues.locals.find(value => value.name === 'answer')?.value, '44')
+  await journey.remove(resultBp)
+  await journey.resume(result)
+  await release.done
+  await journey.detach()
+  await journey.visible('Coroutine result 44')
+  journey.observations.push({ journey: 'completion, breakpoint workaround, synchronous steps, guards, cancelled wait', status: 'PASS' })
+}
+async function boundaryStep(journey: CoroutineJourney) {
+  await journey.attach()
+  const bp = await journey.breakpoint('BREAK_SUSPEND')
+  const tap = await journey.tap('Complete run')
+  const stop = await requiredStop(journey, 'BREAK_SUSPEND')
+  await journey.remove(bp)
+  await journey.step(stop, 'over')
+  const next = await journey.stop(undefined, 3)
+  if (next) await journey.inspect(next, 'suspension step observed stop')
+  journey.observations.push({ journey: 'suspension boundary step', status: 'PASS', observation: next ?? 'No stop within three one-second polls; no coroutine-following claim' })
+  await journey.detach()
+  await tap.done
+  await journey.visible('Coroutine waiting')
+  const release = await journey.tap('Release gate')
+  await release.done
+  await journey.visible('Coroutine result 44')
+}
+async function cancellation(journey: CoroutineJourney) {
+  await journey.attach()
+  const bp = await journey.breakpoint('BREAK_CANCEL', '$cancelWork$2$child$1')
+  const start = await journey.tap('Cancellation run')
+  await start.done
+  await journey.visible('Cancellation waiting')
+  const cancel = await journey.tap('Cancel job')
+  const stop = await requiredStop(journey, 'BREAK_CANCEL')
+  await journey.inspect(stop, 'cancelled child finally')
+  await journey.remove(bp)
+  await journey.resume(stop)
+  await cancel.done
+  await journey.detach()
+  await journey.visible('Coroutine cancelled')
+  journey.observations.push({ journey: 'job cancellation, child finally, cancelAndJoin and recovery', status: 'PASS' })
+}
+async function evidence(directory: string, artifact: string, journey: CoroutineJourney) {
+  const javap = process.env.JAVA_HOME ? process.env.JAVA_HOME + '/bin/javap' : 'javap'
+  const classes = (await readdir(directory + '/classes/dev/mobiledebugmcp/coroutinefixture')).filter(file => file.endsWith('.class')).sort()
+  const metadata = execFileSync(javap, ['-p', '-c', '-l', '-classpath', directory + '/classes', ...classes.map(file => coroutineAppId + '.' + file.slice(0, -6))], { encoding: 'utf8', timeout: 15000 })
+  for (const name of ['known', 'after', 'answer']) assert.ok(metadata.includes(name), 'Compiler variable metadata: ' + name)
+  for (const marker of ['BREAK_BEFORE', 'BREAK_AFTER', 'BREAK_DISPATCH', 'BREAK_CANCEL']) assert.ok(metadata.includes('line ' + journey.line(marker) + ':'), marker)
+  const version = spawnSync(process.env.MCP_KOTLINC ?? 'kotlinc', ['-version'], { encoding: 'utf8', timeout: 15000 })
+  assert.equal(version.status, 0, 'Kotlin compiler version probe')
+  const compiler = (version.stdout + version.stderr).trim()
+  const dependencies = []
+  for (const name of ['MCP_KOTLIN_STDLIB', 'MCP_COROUTINES_CORE']) dependencies.push({ name, file: process.env[name], sha256: hash(await readFile(process.env[name]!)) })
+  return { source_sha256: hash(source), apk_sha256: hash(await readFile(artifact)), dist_sha256: await fingerprint('dist'), worker_sha256: await fingerprint('src/debugger/java'), compiler, dependencies, metadata_sha256: hash(metadata), compiler_metadata: metadata }
+}
+async function run(deviceId: string) {
+  const journey = new CoroutineJourney(deviceId, source)
+  assert.equal(journey.adb('shell', 'pm', 'list', 'packages', coroutineAppId).trim(), '', 'Refusing to replace pre-existing fixture package')
+  let fixture: ReturnType<typeof buildCoroutineFixture> | undefined
+  let installed = false
+  const interrupt = () => journey.interruption.abort()
+  process.once('SIGINT', interrupt)
+  process.once('SIGTERM', interrupt)
+  const forwards = () => deviceForwards(journey.adb('forward', '--list'), deviceId)
+  const baselineForwards = forwards()
+  await reportAfterCleanup(async () => {
+    try { fixture = buildCoroutineFixture() } catch (error) {
+      console.error('BLOCKED coroutine fixture build: check documented local compiler, jars and SDK prerequisites')
+      throw error
+    }
+    const fingerprints = await evidence(fixture.directory, fixture.artifact, journey)
+    await journey.connect()
+    installed = true // A failed install may have left a partial owned package.
+    journey.adb('install', fixture.artifact)
+    journey.adb('shell', 'am', 'start', '-W', '-n', coroutineAppId + '/.MainActivity')
+    await journey.visible('Coroutine ready')
+    await completion(journey)
+    await boundaryStep(journey)
+    journey.adb('shell', 'am', 'force-stop', coroutineAppId)
+    journey.adb('shell', 'am', 'start', '-W', '-n', coroutineAppId + '/.MainActivity')
+    await journey.visible('Coroutine ready')
+    await cancellation(journey)
+    await journey.detach()
+    assert.deepEqual(forwards(), baselineForwards)
+    return { api: journey.adb('shell', 'getprop', 'ro.build.version.sdk').trim(), runtime: process.version, ...fingerprints }
+  }, async () => {
+    process.removeListener('SIGINT', interrupt)
+    process.removeListener('SIGTERM', interrupt)
+    try { await journey.detach() } finally {
+      try { await journey.client.close() } finally {
+        try { if (installed) journey.adb('uninstall', coroutineAppId) } finally { if (fixture) await rm(fixture.directory, { recursive: true, force: true }) }
+      }
+    }
+    assert.deepEqual(forwards(), baselineForwards, 'Owned forward cleanup')
+  }, (status, fingerprints, error) => {
+    const record = JSON.stringify({ status, device: deviceId, ...fingerprints, observations: journey.observations, ...(error ? { error: error instanceof Error ? error.message : String(error) } : {}) })
+    if (status === 'PASS') console.log(record)
+    else console.error(record)
+  })
+}
+if (!device) console.log('UNRUN coroutine debugger fixture: set MCP_COROUTINE_DEVICE, MCP_KOTLINC, MCP_KOTLIN_STDLIB and MCP_COROUTINES_CORE')
+else await run(device)

package/test/device/automated/debugger/kotlin.android.test.ts

@@ -0,0 +1,127 @@
+import assert from 'node:assert/strict'
+import { execFileSync, spawn, spawnSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { readFile, readdir, rm } from 'node:fs/promises'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+import { buildDebuggerFixture, debuggerAppId } from '../../../fixtures/debugger-app/build.js'
+
+const deviceId = process.env.MCP_KOTLIN_DEVICE
+if (!deviceId) {
+  console.log('UNRUN Kotlin debugger fixture: set MCP_KOTLIN_DEVICE, MCP_KOTLINC and MCP_KOTLIN_STDLIB')
+} else {
+  const fixture = buildDebuggerFixture(true)
+  const adbPath = process.env.ADB_PATH ?? 'adb'
+  const adb = (...args: string[]) => execFileSync(adbPath, ['-s', deviceId, ...args], { encoding: 'utf8', timeout: 15000 })
+  const client = new Client({ name: 'kotlin-locals-validation', version: '1.0.0' })
+  let debugSessionId = ''
+  let cursor = 0
+  const call = async (name: string, args: Record<string, unknown>) => {
+    const reply = await client.callTool({ name, arguments: args }, undefined, { timeout: 45000 })
+    const text = reply.content.find(item => item.type === 'text')
+    assert.ok(text?.type === 'text')
+    return JSON.parse(text.text)
+  }
+  const source = await readFile(new URL('../../../fixtures/debugger-app/MainActivity.kt', import.meta.url))
+  const line = (marker: string) => source.toString().split('\n').findIndex(row => row.includes(marker)) + 1
+  const hash = createHash('sha256')
+  const fingerprint = async (directory: string): Promise<void> => {
+    for (const entry of (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+      const file = directory + '/' + entry.name
+      if (entry.isDirectory()) await fingerprint(file)
+      else hash.update(file).update(await readFile(file))
+    }
+  }
+  const waitStop = async (expectedLine: number) => {
+    for (let i = 0; i < 10; i++) {
+      const response = await call('wait_for_debugger_event', { debugSessionId, afterSequence: cursor, timeoutMs: 1000, responseMode: 'compact' })
+      assert.equal(response.overflow, false)
+      cursor = response.next_cursor
+      const event = response.events.find((item: any) => item.event === 'stopped')
+      if (event) {
+        assert.equal(event.stops[0].location.line, expectedLine)
+        assert.equal(event.stops[0].location.method, 'calculate')
+        assert.equal(event.stops[0].location.source, 'MainActivity.kt')
+        return event
+      }
+    }
+    throw new Error('Expected Kotlin source stop not observed')
+  }
+  const inspect = async (stop: any) => {
+    const stack = await call('get_debugger_stack', { debugSessionId, stopId: stop.stop_id, threadId: stop.thread_id, responseMode: 'compact' })
+    const frameId = stack.result.frames[0].frame_id
+    const locals = await call('get_debugger_locals', { debugSessionId, stopId: stop.stop_id, frameId, responseMode: 'compact' })
+    assert.equal(locals.success, true)
+    return { locals: locals.result.locals as { name: string; value: string }[], frameId, availability: locals.result.availability }
+  }
+  try {
+    const forwardsBefore = adb('forward', '--list').trim()
+    const javap = process.env.JAVA_HOME ? process.env.JAVA_HOME + '/bin/javap' : 'javap'
+    const bytecode = execFileSync(javap, ['-p', '-c', '-l', '-classpath', fixture.directory + '/classes', `${debuggerAppId}.MainActivity`], { encoding: 'utf8' })
+    const scopes = Object.fromEntries(['seed', 'known', 'answer'].map(name => {
+      const match = bytecode.match(new RegExp('\\s+(\\d+)\\s+(\\d+)\\s+\\d+\\s+' + name + '\\s+I'))
+      assert.ok(match, 'Compiler emits a variable scope for ' + name)
+      return [name, { start: Number(match[1]), length: Number(match[2]) }]
+    }))
+    assert.equal(scopes.seed.start, 0)
+    assert.ok(scopes.known.start > 0 && scopes.answer.start > scopes.known.start)
+    await fingerprint('dist'); await fingerprint('src/debugger/java')
+    const version = spawnSync(process.env.MCP_KOTLINC ?? 'kotlinc', ['-version'], { encoding: 'utf8' })
+    assert.equal(version.status, 0)
+    const compiler = (version.stdout + version.stderr).match(/kotlinc-jvm [^\r\n]+/)?.[0]
+    assert.ok(compiler, 'Kotlin compiler identifies its version')
+    await client.connect(new StdioClientTransport({ command: process.execPath, args: ['dist/server.js'], stderr: 'pipe' }))
+    adb('install', '-r', fixture.artifact)
+    adb('shell', 'am', 'start', '-W', '-n', `${debuggerAppId}/.MainActivity`)
+    const ready = await call('get_ui_tree', { platform: 'android', deviceId })
+    const button = ready.elements.find((element: any) => /^kotlin calculate$/i.test(element.text ?? ''))
+    assert.ok(button, 'Fresh UI identifies the isolated Kotlin calculation: ' + JSON.stringify(ready))
+    const attached = await call('attach_debugger', { platform: 'android', deviceId, appId: debuggerAppId, timeoutMs: 30000 })
+    debugSessionId = attached.debug_session_id ?? ''
+    assert.equal(attached.success, true, JSON.stringify(attached))
+    const breakpoints = []
+    for (const marker of ['BREAK_KOTLIN_BEFORE', 'BREAK_KOTLIN_KNOWN', 'BREAK_KOTLIN_RESULT']) {
+      const breakpoint = await call('set_debugger_breakpoint', { debugSessionId, className: `${debuggerAppId}.MainActivity`, line: line(marker), responseMode: 'compact' })
+      assert.equal(breakpoint.result.status, 'verified', JSON.stringify(breakpoint))
+      breakpoints.push(breakpoint.result.breakpoint_id)
+    }
+    const bounds = button.bounds
+    const tap = spawn(adbPath, ['-s', deviceId, 'shell', 'input', 'tap', String(Math.floor((bounds[0] + bounds[2]) / 2)), String(Math.floor((bounds[1] + bounds[3]) / 2))], { stdio: 'ignore' })
+    const tapDone = new Promise<void>((resolve, reject) => { tap.on('error', reject); tap.on('exit', code => code === 0 ? resolve() : reject(new Error('Fixture tap failed'))) })
+    void tapDone.catch(() => {})
+    const before = await waitStop(line('BREAK_KOTLIN_BEFORE'))
+    const beforeValues = await inspect(before)
+    assert.equal(beforeValues.locals.find(value => value.name === 'seed')?.value, '7')
+    assert.equal(beforeValues.locals.find(value => value.name === 'known'), undefined, 'Local is not initialized/in scope at its assignment')
+    await call('resume_debugger', { debugSessionId, stopId: before.stop_id, responseMode: 'compact' })
+    const known = await waitStop(line('BREAK_KOTLIN_KNOWN'))
+    const knownValues = await inspect(known)
+    assert.equal(knownValues.locals.find(value => value.name === 'known')?.value, '42')
+    assert.equal(knownValues.locals.find(value => value.name === 'answer'), undefined)
+    const stale = await call('get_debugger_locals', { debugSessionId, stopId: before.stop_id, frameId: beforeValues.frameId, responseMode: 'compact' })
+    assert.equal(stale.error.code, 'DEBUGGER_STALE_REFERENCE')
+    await call('resume_debugger', { debugSessionId, stopId: known.stop_id, responseMode: 'compact' })
+    const result = await waitStop(line('BREAK_KOTLIN_RESULT'))
+    const resultValues = await inspect(result)
+    assert.equal(resultValues.locals.find(value => value.name === 'known')?.value, '42')
+    assert.equal(resultValues.locals.find(value => value.name === 'answer')?.value, '43')
+    for (const breakpointId of breakpoints) await call('remove_debugger_breakpoint', { debugSessionId, breakpointId, responseMode: 'compact' })
+    await call('resume_debugger', { debugSessionId, stopId: result.stop_id, responseMode: 'compact' })
+    await tapDone
+    const detached = await call('detach_debugger', { debugSessionId, responseMode: 'compact' })
+    assert.equal(detached.cleanup.status, 'complete')
+    assert.deepEqual(detached.cleanup.remaining_resources, [])
+    assert.equal(adb('forward', '--list').trim(), forwardsBefore)
+    const recovered = await call('get_ui_tree', { platform: 'android', deviceId })
+    assert.ok(recovered.elements.some((element: any) => element.text === 'Kotlin result 43'), 'Fresh hierarchy proves execution recovery')
+    console.log(JSON.stringify({ status: 'PASS', server_sha256: hash.digest('hex'), source_sha256: createHash('sha256').update(source).digest('hex'), apk_sha256: createHash('sha256').update(await readFile(fixture.artifact)).digest('hex'), compiler, bytecode_scopes: scopes, device: deviceId, api: adb('shell', 'getprop', 'ro.build.version.sdk').trim(), runtime: process.version, lines: [line('BREAK_KOTLIN_BEFORE'), line('BREAK_KOTLIN_KNOWN'), line('BREAK_KOTLIN_RESULT')], observations: ['seed=7; known absent before assignment', 'known=42; answer absent before assignment', 'known=42; answer=43', 'old frame rejected as stale', 'fresh UI Kotlin result 43 after detach'], cleanup: 'owned forwards removed; fixture package and temporary files removed in finally' }))
+  } finally {
+    if (debugSessionId) {
+      const cleanup = await call('detach_debugger', { debugSessionId }).catch(() => null)
+      if (cleanup?.cleanup.status !== 'complete') console.error('UNRESOLVED Kotlin debugger cleanup', JSON.stringify(cleanup?.cleanup ?? null))
+    }
+    try { await client.close() } finally {
+      try { adb('uninstall', debuggerAppId) } finally { await rm(fixture.directory, { recursive: true, force: true }) }
+    }
+  }
+}

package/test/device/automated/debugger/runtime.android.test.ts

@@ -1,3 +1,5 @@
+import { debuggerResponse } from '../../../../src/server/handlers/debugger-response.js'
+import { debuggerContracts } from '../../../../src/server/schemas/debugger-schema.js'
 import assert from 'node:assert/strict'
 import { execFileSync, spawn } from 'node:child_process'
 import { readFile, readdir, rm, writeFile } from 'node:fs/promises'
@@ -14,10 +16,23 @@ if (!process.env.MCP_DEBUGGER_DEVICE) {
   const adb = (...args: string[]) => execFileSync(process.env.ADB_PATH || 'adb', ['-s', deviceId, ...args], { encoding: 'utf8', timeout: 15000 })
   const client = new Client({ name: 'android-debugger-smoke', version: '1.0.0' })
   const transport = new StdioClientTransport({ command: process.execPath, args: ['dist/server.js'], stderr: 'pipe' })
+  const compactMode = process.env.MCP_DEBUGGER_RESPONSE_MODE === 'compact'
+  const measurements: { tool: string; debug_bytes: number; compact_bytes: number }[] = []
   const call = async (name: string, args: Record<string, unknown>) => {
-    const response = await client.callTool({ name, arguments: args }, undefined, { timeout: 45000 })
+    const response = await client.callTool({ name, arguments: { ...args, ...(debuggerContracts[name] && compactMode ? { responseMode: 'compact' } : {}) } }, undefined, { timeout: 45000 })
     const text = (response.content as any[]).find(c => c.type === 'text')!.text!
-    return JSON.parse(text)
+    const payload = JSON.parse(text)
+    if (debuggerContracts[name]) {
+      const command = debuggerContracts[name].command
+      if (compactMode && !['attach', 'state', 'capabilities'].includes(command) && payload.debug_session_id != null) {
+        for (const field of ['device', 'target', 'capabilities']) assert.ok(!Object.hasOwn(payload, field))
+      }
+      if (!compactMode) {
+        const compact = debuggerResponse(command, 'compact', payload)
+        measurements.push({ tool: name, debug_bytes: Buffer.byteLength(JSON.stringify(response)), compact_bytes: Buffer.byteLength(JSON.stringify({ ...response, content: [{ type: 'text', text: JSON.stringify(compact, null, 2) }] })) })
+      }
+    }
+    return payload
   }
   const hash = createHash('sha256')
   const fingerprint = async (directory: string): Promise<void> => {
@@ -27,7 +42,7 @@ if (!process.env.MCP_DEBUGGER_DEVICE) {
       else hash.update(file).update(await readFile(file))
     }
   }
-  await fingerprint('dist'); await fingerprint('worker')
+  await fingerprint('dist'); await fingerprint('src/debugger/java')
   const buildHash = hash.digest('hex')
   const fixture = buildDebuggerFixture()
   const source = await readFile(new URL('../../../fixtures/debugger-app/MainActivity.java', import.meta.url), 'utf8')
@@ -193,6 +208,7 @@ if (!process.env.MCP_DEBUGGER_DEVICE) {
       assert.ok(treeAfterShutdown.elements.some((e: any) => e.text === 'Result 43'), 'fresh UI proves paused fixture resumed after server shutdown')
     } finally { await verifier.close() }
     console.log(JSON.stringify({ status: 'PASS', build_sha256: buildHash, device: deviceId, api: adb('shell', 'getprop', 'ro.build.version.sdk').trim(), runtime: process.version, transport: 'MCP stdio', extended: process.env.MCP_DEBUGGER_EXTENDED === '1' }))
+    console.log('Debugger response measurement', JSON.stringify({ mode: compactMode ? 'compact' : 'debug', calls: measurements, debug_bytes: measurements.reduce((sum, row) => sum + row.debug_bytes, 0), compact_bytes: measurements.reduce((sum, row) => sum + row.compact_bytes, 0) }))
     console.log('PASS Android debugger: explicit attach, source stop, stack/known locals, pause guards, into/over/out, stale frame, resume UI, detach/forward ownership')
   } finally {
     if (debugSessionId) await call('detach_debugger', { debugSessionId }).catch(() => {})