mobile-debug-mcp 0.35.0 → 0.37.0

package/dist/utils/app-installation.js

@@ -0,0 +1,77 @@
+import { execFile } from 'node:child_process';
+import { execCmd } from './exec.js';
+import { remainingBudget } from './operation-budget.js';
+export function validAppId(appId) { return /^[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*$/.test(appId); }
+export function installationContext(deviceId, appId, scope) {
+    return { status: 'unknown', appId: appId ?? null, deviceId, scope, checkedAt: null, reason: appId === undefined ? 'APP_ID_NOT_PROVIDED' : 'CHECK_FAILED' };
+}
+export function installationFields(appInstallation) {
+    return { appInstallation, ...(appInstallation.status === 'unknown' ? {} : { appInstalled: appInstallation.status === 'installed' }) };
+}
+export async function probeInstallation(command, deviceId, appId, scope, available = true) {
+    const result = installationContext(deviceId, appId, scope);
+    if (appId === undefined || !validAppId(appId))
+        return result;
+    if (!available)
+        return { ...result, reason: 'DEVICE_UNAVAILABLE' };
+    try {
+        return await runProbe(command, result);
+    }
+    catch {
+        return { ...result, checkedAt: new Date().toISOString(), reason: 'CHECK_FAILED' };
+    }
+}
+async function runProbe(command, context) {
+    const android = context.scope === 'android-current-user';
+    const started = performance.now();
+    const timeout = remainingBudget(5000);
+    const args = android ? ['-s', context.deviceId, 'shell', 'pm', 'path', context.appId] : ['simctl', 'listapps', context.deviceId];
+    const output = await execCmd(command, args, { timeout });
+    const result = { ...context, checkedAt: new Date().toISOString() };
+    if (output.exitCode !== 0) {
+        if (android && !output.stdout && !output.stderr)
+            return confirmAndroidAbsence(command, result, Math.max(1, timeout - (performance.now() - started)));
+        return { ...result, reason: 'CHECK_FAILED' };
+    }
+    let status;
+    if (android) {
+        const lines = output.stdout.trim().split('\n').filter(Boolean);
+        if (lines.some(line => !/^package:\/\S+$/.test(line.trim())))
+            return { ...result, reason: 'UNRECOGNIZED_RESPONSE' };
+        status = lines.length ? 'installed' : 'absent';
+    }
+    else {
+        try {
+            const budget = remainingBudget(Math.max(1, Math.floor(timeout - (performance.now() - started))));
+            if (performance.now() - started >= timeout)
+                return { ...result, reason: 'CHECK_FAILED' };
+            const json = await new Promise((resolve, reject) => {
+                const child = execFile('/usr/bin/plutil', ['-convert', 'json', '-o', '-', '--', '-'], { timeout: budget, killSignal: 'SIGKILL', maxBuffer: 16 * 1024 * 1024 }, (error, stdout) => error ? reject(error) : resolve(stdout));
+                child.stdin?.on('error', reject);
+                child.stdin?.end(output.stdout);
+            });
+            const apps = JSON.parse(json);
+            if (!apps || typeof apps !== 'object' || Array.isArray(apps))
+                return { ...result, reason: 'UNRECOGNIZED_RESPONSE' };
+            if (Object.values(apps).some(value => !value || typeof value !== 'object' || Array.isArray(value)))
+                return { ...result, reason: 'UNRECOGNIZED_RESPONSE' };
+            status = Object.hasOwn(apps, context.appId) ? 'installed' : 'absent';
+        }
+        catch {
+            return { ...result, reason: 'UNRECOGNIZED_RESPONSE' };
+        }
+    }
+    const { reason: _reason, ...confirmed } = result;
+    return { ...confirmed, status };
+}
+async function confirmAndroidAbsence(command, context, timeout) {
+    const output = await execCmd(command, ['-s', context.deviceId, 'shell', 'pm', 'list', 'packages', context.appId], { timeout });
+    const result = { ...context, checkedAt: new Date().toISOString() };
+    if (output.exitCode !== 0)
+        return { ...result, reason: 'CHECK_FAILED' };
+    const lines = output.stdout.split('\n').map(line => line.trim()).filter(Boolean);
+    if (lines.some(line => !/^package:[A-Za-z0-9_.-]+$/.test(line)))
+        return { ...result, reason: 'UNRECOGNIZED_RESPONSE' };
+    const { reason: _reason, ...confirmed } = result;
+    return { ...confirmed, status: lines.includes(`package:${context.appId}`) ? 'installed' : 'absent' };
+}

package/dist/utils/benchmark-metrics.js

@@ -0,0 +1,43 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+const measurement = new AsyncLocalStorage();
+// Private benchmark diagnostics: no arguments, device IDs or response contents.
+export function recordBenchmarkSpan(stage, duration) {
+    const current = measurement.getStore();
+    if (!current)
+        return;
+    const end = performance.now() - current.started;
+    current.spans.push({ stage, start_ms: Math.max(0, end - duration), end_ms: end });
+}
+export async function benchmarkSubprocess(operation) {
+    return benchmarkStage('subprocess_ms', operation);
+}
+export async function benchmarkStage(stage, operation) {
+    if (!measurement.getStore())
+        return operation();
+    const started = performance.now();
+    try {
+        return await operation();
+    }
+    finally {
+        recordBenchmarkSpan(stage, performance.now() - started);
+    }
+}
+export async function withBenchmarkRequest(tool, operation) {
+    if (process.env.MOBILE_DEBUG_MCP_LATENCY_METRICS !== '1')
+        return operation();
+    const current = { id: randomUUID(), started: performance.now(), spans: [] };
+    return measurement.run(current, async () => {
+        let completed = false;
+        try {
+            const result = await operation();
+            completed = true;
+            return result;
+        }
+        finally {
+            process.stderr.write(`${JSON.stringify({ event: 'latency_metric', request_id: current.id,
+                tool, handler_completed: completed, elapsed_ms: performance.now() - current.started,
+                spans: current.spans })}\n`);
+        }
+    });
+}

package/dist/utils/exec.js

@@ -1,7 +1,11 @@
 import { checkDebuggerGuard } from '../debugger/guard.js';
 import { remainingBudget } from './operation-budget.js';
 import { spawn } from 'child_process';
+import { benchmarkSubprocess } from './benchmark-metrics.js';
 export async function execCmd(cmd, args, opts = {}) {
+    return benchmarkSubprocess(() => execute(cmd, args, opts));
+}
+async function execute(cmd, args, opts) {
     const { env, cwd, shell } = opts;
     const timeout = remainingBudget(opts.timeout ?? 0);
     return new Promise((resolve, reject) => {

package/dist/utils/ios/utils.js

@@ -1,3 +1,5 @@
+import { installationFields, probeInstallation } from '../app-installation.js';
+import { checkDebuggerGuard } from '../../debugger/guard.js';
 import { remainingBudget } from '../operation-budget.js';
 import { execFile, spawn, execSync, spawnSync } from "child_process";
 import { promises as fsPromises } from 'fs';
@@ -94,6 +96,7 @@ export function execCommand(args, deviceId = "booted") {
     return new Promise((resolve, reject) => {
         // Use spawn for better stream control and consistency with Android implementation
         const budgetMs = remainingBudget();
+        checkDebuggerGuard();
         const child = spawn(getXcrunCmd(), args);
         let stdout = '';
         let stderr = '';
@@ -135,6 +138,7 @@ export function execCommandWithDiagnostics(args, deviceId = "booted") {
     const DEFAULT_XCRUN_LOG_TIMEOUT = parseInt(process.env.MCP_XCRUN_LOG_TIMEOUT || '', 10) || 30000;
     const DEFAULT_XCRUN_CMD_TIMEOUT = parseInt(process.env.MCP_XCRUN_TIMEOUT || '', 10) || 60000;
     const timeoutMs = budgetMs || (args.includes('log') ? DEFAULT_XCRUN_LOG_TIMEOUT : DEFAULT_XCRUN_CMD_TIMEOUT);
+    checkDebuggerGuard();
     const res = spawnSync(getXcrunCmd(), args, { encoding: 'utf8', timeout: timeoutMs });
     const runResult = {
         exitCode: typeof res.status === 'number' ? res.status : null,
@@ -276,17 +280,9 @@ export async function listIOSDevices(appId) {
                                 simulator: true,
                                 booted: bootedSet.has(device.udid)
                             };
-                            if (appId) {
-                                // check if installed
-                                const p = execCommand(['simctl', 'get_app_container', device.udid, appId, 'data'], device.udid)
-                                    .then(() => { info.appInstalled = true; })
-                                    .catch(() => { info.appInstalled = false; })
-                                    .then(() => { out.push(info); });
-                                checks.push(p);
-                            }
-                            else {
-                                out.push(info);
-                            }
+                            out.push(info);
+                            checks.push(probeInstallation(getXcrunCmd(), device.udid, appId, 'ios-simulator', info.booted === true)
+                                .then(check => { Object.assign(info, installationFields(check)); }));
                         }
                     }
                     Promise.all(checks).then(() => resolve(out)).catch(() => resolve(out));

package/dist/utils/resolve-device.js

@@ -38,6 +38,7 @@ export async function listDevices(platform, appId) {
     return iosDeviceLister(appId);
 }
 const deviceContext = new AsyncLocalStorage();
+export function currentResolvedDevice() { return deviceContext.getStore(); }
 export function withResolvedDevice(device, operation) {
     bindEvidenceDevice(device);
     return deviceContext.run(device, operation);
@@ -75,7 +76,7 @@ function selectDevice(devices, platform, appId, prefer) {
     if (prefer === "emulator")
         candidates = candidates.filter(d => d.simulator);
     if (appId) {
-        const installed = candidates.filter(d => d.appInstalled);
+        const installed = candidates.filter(d => d.appInstallation ? d.appInstallation.status === 'installed' && d.appInstallation.appId === appId && d.appInstallation.deviceId === d.id : d.appInstalled === true);
         if (installed.length > 0)
             candidates = installed;
     }
@@ -101,7 +102,7 @@ function selectDevice(devices, platform, appId, prefer) {
         if (candidates.length > 1 && parseNumericVersion(candidates[0].osVersion) > parseNumericVersion(candidates[1].osVersion)) {
             return candidates[0];
         }
-        const list = candidates.map(d => ({ id: d.id, platform: d.platform, osVersion: d.osVersion, model: d.model, simulator: d.simulator, appInstalled: d.appInstalled }));
+        const list = candidates.map(d => ({ id: d.id, platform: d.platform, osVersion: d.osVersion, model: d.model, simulator: d.simulator, appInstalled: d.appInstalled, appInstallation: d.appInstallation }));
         const err = Object.assign(new Error(`Multiple matching devices found: ${JSON.stringify(list, null, 2)}`), { devices: list });
         throw err;
     }

package/dist/utils/timing.js

@@ -1,7 +1,9 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
+import { recordBenchmarkSpan } from './benchmark-metrics.js';
 const timings = new AsyncLocalStorage();
 export function withTiming(values, operation) { return timings.run(values, operation); }
 export function recordTiming(component, milliseconds) {
+    recordBenchmarkSpan(component, milliseconds);
     const values = timings.getStore();
     if (values)
         values[component] = (values[component] ?? 0) + milliseconds;
@@ -12,8 +14,6 @@ export async function measure(component, operation) {
         return await operation();
     }
     finally {
-        const values = timings.getStore();
-        if (values)
-            values[component] = (values[component] ?? 0) + performance.now() - start;
+        recordTiming(component, performance.now() - start);
     }
 }

package/docs/CHANGELOG.md

@@ -8,7 +8,54 @@ and [tool reference](tools/TOOLS.md) for the current checkout.
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
-## Unreleased
+## [0.37.0]
+
+- Updated the agent plugin to `0.0.7`, pinned to MCP `0.37.0`.
+
+- Android debug snapshots use one fresh UI tree for the returned hierarchy and
+  screen fingerprint, removing a duplicate acquisition.
+
+- Add an end-to-end latency benchmark with repeated mode comparisons, visible
+  failed attempts, source/build identity, and opt-in timing-only request and
+  subprocess diagnostics. Public tool contracts and verification are unchanged.
+
+- Compact interaction/journey results now summarize observations, readiness, conditions and state deltas within explicit byte budgets. Detailed original results are available through session-local `get_interaction_diagnostics` references without replaying input. Debug output and response-mode defaults are unchanged.
+
+- Report device-scoped app installation as installed, absent or unknown. Publish
+  `list_devices.appId`; omit legacy installation booleans for inconclusive or
+  multi-device system checks instead of reporting false absence.
+
+- Clean up discarded iOS trace files after a recorder-stop failure when process
+  exit is confirmed, while retaining the failure and protecting live recordings.
+
+- Add timestamped device-readiness evidence to launch/interaction results and
+  readiness waits, preserving dispatch outcomes and compact/journey evidence.
+  Android power/keyguard blockers prevent readiness success; iOS reports
+  per-signal unknown/unsupported evidence. No automatic wake or unlock.
+
+## [0.36.0]
+
+- Updated the agent plugin to `0.0.6`, pinned to MCP `0.36.0`.
+
+- Add an optional iOS simulator LLDB backend to the existing debugger tools,
+  including exact source-file breakpoints, bounded static inspection, stepping,
+  platform-scoped pause guards and owned cleanup. A separate Swift concurrency
+  fixture checks inspection around await, cancellation and recovery; verification
+  coverage is recorded in specification 032. Physical iOS devices remain unsupported.
+
+- Preserve iOS trace capture through isolated monitoring command failures; require
+  three consecutive non-definitive failures before discarding, while identity and
+  storage failures remain immediate and capture expiry still reconciles.
+
+- Add optional iOS simulator Time Profiler capture through Instruments, with explicit
+  device/app targeting, recording-start notification, local `.trace` validation,
+  journey evidence linkage and owned cleanup. Physical devices and other templates
+  remain unsupported in the initial matrix. Android tracing retains its preset.
+
+
+- Added plugin `0.0.5` Antigravity compatibility and a standalone distribution
+  export. Generated a Cursor-native package for its supported path variables,
+  and checked/refined installation instructions for all four clients.
 
 ## [0.35.0]
 

package/docs/agent-plugin-installation-verification.md

@@ -0,0 +1,39 @@
+# Agent plugin installation verification
+
+Checked 2026-11-02 for plugin 0.0.5 and published MCP 0.35.0. This record separates
+command/schema checks from installation and live device evidence.
+
+| Client | Evidence | Limit |
+| --- | --- | --- |
+| Codex CLI 0.166.0-alpha.5.1 | Marketplace-add and plugin-add syntax confirmed with installed CLI help and official docs; catalog paths checked by repository verification | No new Codex installation or agent journey performed |
+| Claude Code 2.1.285 | Native strict validation passes for the marketplace, compatibility manifest and complete plugin folder; shell command syntax confirmed | No new Claude Code installation or agent journey performed |
+| Cursor | Native package and catalog generated from the canonical skill; uses documented CURSOR_PLUGIN_ROOT; local-copy instructions preserve hidden files | Host loading in Cursor is unrun |
+| Antigravity CLI 1.4.12 | Standalone export passes strict validation with zero warnings; local install discovers one skill and one MCP server | An agent print-mode attempt was denied by plan-mode MCP policy; a narrowly permitted read-only attempt timed out, so no agent tool-call success is claimed |
+
+The Antigravity export contains native `plugin.json`, `mcp_config.json`, README,
+license, logo and the shared skill. It excludes foreign client manifests and
+Finder metadata. Export destinations must be new directories. Regression coverage
+checks inventory, canonical skill/license bytes and refusal to overwrite existing
+files. Cursor's generated skill/license are checked against their canonical
+sources by `npm run check:agent-plugin`.
+
+A separate SDK test launched the exact exported npx command from an expanded
+PLUGIN_DATA working directory. It connected to published MCP 0.35.0, discovered
+52 tools, selected emulator-5554 (Android 16/API 36), launched Settings and asserted
+a fresh UI tree contained a visible Settings-owned resource. **PASS**; this is an
+exported-config/device check, not an Antigravity agent interaction. Log:
+`/tmp/antigravity-published-mcp-check.log`. The emulator remains running.
+
+`npm run verify` **PASS**, all 91 unit files, including the exporter regression,
+lint/quality/architecture, build and plugin consistency. Native Antigravity strict
+validation and Claude strict validation also **PASS**. Markdown links and diff
+whitespace were checked. No production server code or dependencies changed.
+GitHub/local distribution does not require the optional Marketplace intake form;
+no application was submitted.
+
+## Primary documentation
+
+- [OpenAI plugin packaging](https://developers.openai.com/plugins/build/plugins)
+- [Claude Code installation](https://code.claude.com/docs/en/discover-plugins)
+- [Cursor plugins and local testing](https://cursor.com/docs/plugins)
+- [Antigravity plugin building and validation](https://antigravity.google/docs/build-plugins)

package/docs/benchmarks/README.md

@@ -14,5 +14,6 @@ iOS latency.
 | --- | --- | --- | --- |
 | Interaction latency | [Run the benchmark](interaction-latency/README.md) | [Android measurements](interaction-latency/final.md), [iOS interaction validation](interaction-latency/ios-validation.md) | [018](../specs/018-interaction-latency-and-batched-journeys/spec.md) |
 | UI-tree observation | [Run the paired benchmark](ui-tree-performance/README.md) | [Comparison and limitations](ui-tree-performance/comparison.md) | [019](../specs/019-ui-tree-observation-performance/spec.md) |
+| End-to-end interaction latency | [Run the benchmarks](end-to-end-latency/README.md) | [Provisional Android results and iOS blocker](end-to-end-latency/investigation.md) | [036](../specs/036-end-to-end-interaction-latency/spec.md) |
 
 Fixture instructions: [latency journey app](../../test/fixtures/latency-journey-app/README.md).

package/docs/benchmarks/end-to-end-latency/README.md

@@ -0,0 +1,98 @@
+# End-to-end interaction latency
+
+[Benchmark index](../README.md) · [Specification](../../specs/036-end-to-end-interaction-latency/spec.md)
+
+This investigation reuses the Spec 018 Android fixture and Spec 019 tree metrics.
+It does not replace their historical results or optimization acceptance gates.
+Requires Node >=22, Java supporting `--release 8`, Android platform 36 and
+build-tools 36.0.0. Start an Android emulator, then run from the repository root:
+
+```sh
+npm run verify
+LATENCY_DEVICE_ID=emulator-5554 MCP_ADB_TIMEOUT=30000 npx tsx test/device/automated/latency/end-to-end.ts --smoke
+LATENCY_DEVICE_ID=emulator-5554 MCP_ADB_TIMEOUT=30000 npx tsx test/device/automated/latency/end-to-end.ts
+```
+
+Only explicitly named Android emulators are accepted; physical phones are not
+selected. Existing device resolution can enumerate other attached devices;
+the report records discovery counts without serials. No display configuration is changed. The dedicated fixture is built,
+installed, and reset; an installation created by this run is removed on exit.
+A pre-existing fixture installation is left installed, with reset fixture data.
+The harness owns isolated POSIX server process groups, closes them on exit and
+interrupt, and verifies their termination. An unsafe timeout stops the run;
+semantic failures are retained before the next explicitly recorded reset.
+
+The smoke uses one attempt per case and writes `smoke.json`/`smoke.md`; it is not
+performance evidence. The full run writes `baseline.json`/`baseline.md` after
+each attempt, preserving partial results on failure/interruption. It performs
+three warm-ups and ten measured attempts per case, reversing mode order every
+round. Do not run other device workloads concurrently.
+
+`baseline-attempt-1.json`/`.md` retain the first failed warm-up run: the emulator
+disappeared, the next reset failed, and fixture cleanup could not be confirmed.
+No measured samples were produced. Both owned server groups exited. The retry
+restores the same AVD headlessly using `emulator -avd Pixel_9_Pro -port 5554
+-no-window -no-snapshot-save`; it does not wipe data. This startup configuration
+is distinct from the earlier development smoke and failed attempt.
+
+Cases compare the original standalone handle flow and four full/light ×
+debug/compact journeys, retaining all six destination assertions. Screenshot,
+UI tree and screenshot/log-free snapshot calls are separate cases on the known
+fixture home screen, with instrumentation on and off. Light/compact has existing
+assertion-based observation sharing; mode differences can therefore include
+acquisition counts as well as response construction costs. They are not a pure
+serialization microbenchmark.
+
+Raw reports include source/build/harness/fixture hashes, dirty paths, environment,
+request order, byte counts, timing-only events, setup/startup durations and
+cleanup. Device serials, raw responses and unrestricted stderr are not retained.
+Source/build/harness changes during measurement invalidate the run. Externally
+run builds and validation suites are separate from MCP request time. This fixture
+uses offline SDK tools rather than Gradle. Device application work inside requests
+is included; it is not established as pure MCP overhead.
+
+Percentiles use nearest rank and successful attempts only; failures remain in
+raw records and fail the run. Warm-up failures are counted separately. Ten samples
+provide a preliminary p95, not a robust tail estimate. Inclusive component spans
+overlap and must not be summed. Handler residual subtracts their interval union;
+client-minus-handler includes scheduling, transport and uninstrumented work.
+Existing serialization spans cover selected response construction, not all SDK
+wire serialization. Tree event stages expose acquisition, retry and parse costs.
+Subprocess spans cover `execCmd`; direct platform spawns can remain in residuals.
+
+Compare observation `on`/`off` results to assess probe overhead; these include
+normal device variability and are not automatically a causal overhead estimate.
+`missing_request_metrics` is expected for `off` cases only. Instrumentation uses
+`MOBILE_DEBUG_MCP_LATENCY_METRICS=1` and the existing
+`MOBILE_DEBUG_MCP_UI_TREE_METRICS=1` only in instrumented benchmark servers.
+Normal MCP contracts and diagnostic output are unchanged.
+
+For standalone iOS observations, use an isolated booted simulator with working
+idb discovery and English Settings. The runner confirms the Settings root
+before each timed request and records preparation time separately.
+
+```sh
+IOS_LATENCY_DEVICE_ID=YOUR_SIMULATOR_ID npx tsx test/device/automated/latency-ios/benchmark.ts --smoke
+IOS_LATENCY_DEVICE_ID=YOUR_SIMULATOR_ID npx tsx test/device/automated/latency-ios/benchmark.ts
+```
+
+Equivalent iOS fixture journeys depend on [#89](https://github.com/clivejefferies/mobile-debug-tools/issues/89).
+See the [investigation report](investigation.md) for the Android measurements
+and the observed iOS setup blocker.
+
+For a focused [Android snapshot comparison](android-snapshot-pair.md), build
+the pre-change checkout and preserve its emitted `dist` directory and source
+hash. The preserved build needs its ESM `package.json` and the same installed
+dependencies. Build the candidate in the current checkout, then run:
+
+```sh
+LATENCY_DEVICE_ID=emulator-5554 \
+SNAPSHOT_BASELINE_SERVER=/absolute/path/to/baseline/dist/server.js \
+SNAPSHOT_BASELINE_SOURCE_SHA=BASELINE_SOURCE_SHA256 \
+MCP_ADB_TIMEOUT=30000 \
+node --import tsx test/device/automated/latency/snapshot-pair.ts
+```
+
+Use the `treeHash` helper in `end-to-end-environment.ts` to hash baseline `src`
+before editing it. This command writes `android-snapshot-pair.json` with the
+attempts and acceptance result.