mobile-debug-mcp 0.34.0 → 0.35.0

package/docs/benchmarks/ui-tree-performance/README.md

@@ -1,5 +1,7 @@
 # UI tree observation performance benchmark
 
+[Benchmark index](../README.md) · [Documentation](../../README.md)
+
 This paired Android benchmark compares a clean, built instrumentation baseline
 with a clean, built candidate. It runs the Spec 018 static journey and a local
 network-backed loading-to-ready flow against the same fixture APK and emulator.
@@ -41,19 +43,25 @@ not gain timing fields. Events contain timings, platform, generated journey step
 IDs, and opaque acquisition IDs. They omit UI contents, app identifiers,
 screenshots, logs, payloads, and device serials. iOS latency remains unmeasured.
 
-The checked-in `initial-baseline.json` is the standalone capture taken before
-the optimization. The checked-in `baseline.json` is the baseline side of the
-paired run, so it shares the fixture APK hash with `candidate.json`.
-`comparison-attempt-1.json` retains an earlier paired run with two visible
-network failures; see `comparison.md` for the outcome and limitation.
-The report commit SHAs are available locally as `codex/spec-019-baseline` and
-`codex/spec-019-candidate`; create clean, built checkouts of those refs to
-reproduce the paired measurement.
-
-The historical `bridge-probe.json` compares ten bridge and legacy reads, checks a network
-update, and checks a timer that changes visually without emitting an
-accessibility event. The timer check catches a stale accessibility cache even
-when every bridge request calls `getRootInActiveWindow()`.
-The bridge APK source, generator, and build/install probe have been removed;
-this report is retained as historical evidence, not a runnable benchmark in
-the current checkout.
+## Recorded results
+
+Read the [comparison report](comparison.md) for measurements and limitations.
+The checked-in reports describe a historical run, not the current checkout's
+performance.
+
+| File | Purpose |
+| --- | --- |
+| [comparison.md](comparison.md) | Human-readable results and interpretation. |
+| [comparison.json](comparison.json) | Complete paired report, including both modes and per-attempt data. |
+| [baseline.json](baseline.json) | Baseline-only view of the paired run. |
+| [candidate.json](candidate.json) | Candidate-only view of the paired run. |
+| [comparison-attempt-1.json](comparison-attempt-1.json) | Earlier failed comparison, retained because the unexplained stalls remain a limitation. |
+
+The paired baseline and candidate use the same fixture APK hash. The separate
+views are generated outputs; use the complete comparison for the full record.
+Baseline-only runs also write `baseline.json`, so keep paired reports together
+when recording a new comparison.
+
+Use the commit identifiers in the JSON reports to identify the measured source.
+Reproducing the run requires clean, built checkouts of those commits and the
+fixture prerequisites described above.

package/docs/benchmarks/ui-tree-performance/comparison.md

@@ -1,5 +1,7 @@
 # UI tree observation performance
 
+[Benchmark index](../README.md) · [Documentation](../../README.md)
+
 Fixture SHA-256: be322549a4ba154c0b1c85876559157bb21a911673906d270a7ec26dc2fcfa89. Android 16, API 36. Three warm-ups and ten measured attempts per flow and mode. Failed attempts are visible in the JSON reports and excluded from percentiles.
 
 | Mode | Flow | p50 ms | p95 ms | Failures |
@@ -29,13 +31,12 @@ visible in the acquisition records. The candidate also lowers network p95 at
 both response delays. The fixture recorded no `VERIFICATION_UNAVAILABLE` in
 either mode, so this result does not establish its rate in other apps.
 
-`initial-baseline.json` preserves the standalone instrumentation-only capture
-made before the acquisition change. The paired `baseline.json`,
-`candidate.json`, and `comparison.json` use one APK SHA-256 and the same
-emulator settings. An earlier paired attempt is retained as
-`comparison-attempt-1.json`: one measured baseline 100 ms network read failed
-after a 181.97 s physical acquisition, and one candidate 1,500 ms warm-up
-failed before an observation event. That attempt failed the zero-failure gate.
-The unchanged repeat above had no failures. The cause of the first attempt's
-stalls was not established, so the repeat supports the latency result but does
-not prove the stall cannot recur. iOS latency was not measured.
+The paired [baseline](baseline.json), [candidate](candidate.json), and
+[complete comparison](comparison.json) use one APK SHA-256 and the same emulator
+settings. An [earlier paired attempt](comparison-attempt-1.json) recorded one
+measured baseline 100 ms network read failing after a 181.97 s physical
+acquisition and one candidate 1,500 ms warm-up failing before an observation
+event. That attempt failed the zero-failure gate. The unchanged repeat above had
+no failures. The cause of the first attempt's stalls was not established, so the
+repeat supports the latency result but does not prove the stall cannot recur.
+iOS latency was not measured.

package/docs/code-structure.md

@@ -0,0 +1,118 @@
+# Code structure and quality checks
+
+[Documentation](README.md) · [Contributing](../CONTRIBUTING.md)
+
+Run `npm run lint` before submitting a change. It runs the existing ESLint rules
+and `npm run check:quality` plus `npm run check:architecture`. These checks also run in `npm run verify` and the
+unit CI job; quality failures exit nonzero even with ESLint's `--quiet` option.
+
+## Limits
+
+Production TypeScript is checked against these defaults:
+
+| Metric | Limit |
+| --- | ---: |
+| File length | 500 lines |
+| Class length | 300 lines |
+| Function or method length | 80 lines |
+| Cyclomatic complexity | 20 |
+| Control-flow nesting | 4 |
+| New explicit `any` | 0 |
+
+Line counts exclude blank and comment-only lines. Java source has the file-length
+limit; TypeScript class/function/type metrics do not apply to Java. Existing
+ESLint rules still apply to tests, but the production size gates do not apply to
+fixture tables or self-running test scripts.
+
+Prefer cohesive responsibilities and typed boundaries. Avoid compressing code,
+adding trivial wrappers, or disabling rules to meet a number. The checks help
+identify risk; passing them does not replace a design or correctness review.
+
+## Architecture checks
+
+`npm run check:architecture` uses pinned ArchUnitTS (`archunit`) to enforce four
+rules over the production dependency graph:
+
+- Shared contracts cannot import application implementations outside `contracts/`.
+- Capability and shared modules cannot import the MCP server layer.
+- The listed pure interaction calculations cannot import native I/O or service
+  facades. Their exact scope is defined in
+  [the rules](../scripts/check-architecture.mjs).
+- Production runtime dependencies must be cycle-free. Type-only dependencies
+  count for boundary rules, but type-only cycles do not count as runtime cycles.
+
+ArchUnitTS 2.5.4 extracts static imports. A small
+[TypeScript resolution adapter](../scripts/architecture-graph.mjs) adds re-exports,
+import types, literal dynamic imports, `require` calls and Node builtins. It uses
+the repository's `tsconfig.json`, including NodeNext `.js` imports. Nonliteral
+loads and unresolved dependencies fail the check instead of silently disappearing.
+Boundary rules check direct dependencies; cycle detection checks the internal
+runtime graph. This does not analyse Java worker dependencies or reflective loads.
+
+[Negative-control tests](../test/unit/quality/architecture.test.ts) prove that
+broken boundaries, cycles, aliases, and dynamic/re-export dependencies are caught,
+and empty or incomplete graphs fail. The current graph needs no cycle exceptions.
+Keep new rules aligned with the module ownership below; changing architecture
+requires reviewing the rule alongside the implementation.
+
+## Baseline policy
+
+The [reviewed baseline](../scripts/code-quality-baseline.json) is empty: all
+production source currently meets the default limits, including zero explicit
+`any` occurrences. If an exception is explicitly approved, its entry records the
+file, rule and symbol. Each entry is a ceiling, not a target.
+An existing exception cannot grow, and an improvement must lower or remove its
+entry. New files and renamed symbols do not inherit exceptions. Unrelated
+improvements cannot compensate for a regression elsewhere.
+
+Lint and CI never regenerate the baseline. When reducing debt, edit the affected
+entries explicitly and include that diff in review. New debt or raised ceilings
+require a design decision and review; there is no blanket suppression mechanism.
+Inline suppression of these gates is rejected. Anonymous callbacks have identities
+based on their enclosing scope and body, so changing an exceptional callback
+requires reviewing its exception rather than silently transferring it.
+
+## Module ownership
+
+- `src/server/` is the MCP boundary: `definitions/` publishes tools,
+  `schemas/` validates MCP requests, and `handlers/` dispatches them.
+  `tool-definitions.ts` assembles the public definitions; `common.ts` provides
+  argument readers and response serialization. Capability handlers live in
+  `manage.ts`, `observe.ts`, `interact.ts`, `input.ts`, `journey.ts`, and
+  `diagnostic.ts`. `action-execution.ts` owns dispatch, condition handling,
+  verification and response phases; the central handler retains registration,
+  timing and debugger guards.
+- `src/contracts/` holds shared input shapes and validation used across
+  capabilities. These contracts do not depend on MCP dispatch.
+- `src/runtime/` currently holds action-result and trace construction shared by
+  dispatch and interactions, plus a small injectable wall-clock/delay interface
+  for polling services. Production clocks retain existing timer and readiness
+  budget semantics. It is separate from MCP response serialization;
+  interaction and runtime modules cannot import server-layer code.
+- `src/interact/` owns actions and their supporting services. `index.ts` is the
+  composition facade; `android.ts` and `ios.ts` implement native input.
+  `adjustment/` contains adjustable-control strategies and calculations;
+  `targeting/` contains candidate ranking, element handles and target resolution;
+  `waits/` contains synchronization and legacy waits; `assertions/` contains
+  screen, visibility and state checks. Shared observation and input interfaces
+  remain at the interaction root. `ToolsInteract` must meet the 300-line class
+  budget without exceptions.
+- `src/observe/` owns evidence acquisition and snapshots. Android and iOS facades
+  delegate to platform folders for trees, logs, screenshots, fingerprints and log
+  streams. Snapshot collection, log normalization and semantic summaries are
+  separate modules; screenshot encoding retains platform-specific alpha policies.
+- `src/manage/ios/` owns Xcode project and scheme discovery, build preparation,
+  execution, watchdogs and diagnostics behind the existing iOS facade.
+- `src/system/` separates probes, platform capability policies and status summaries.
+  `src/utils/android/` separates commands, Gradle preparation, logs and UI parsing;
+  `utils.ts` retains compatibility exports and device discovery.
+- `src/observe/network/` infers HTTP activity from Android logcat and iOS
+  simulator logs. It supports `get_network_activity` and action classification;
+  it is not packet capture or a proxy. Results depend on the app logging requests,
+  and the current implementation does not measure request duration.
+- `src/debugger/protocol.ts` validates worker messages. The session manager owns
+  serialized transitions and cleanup; the Java worker owns JDI operations.
+
+The [refactoring plan](specs/026-code-structure-and-quality-gates/plan.md) records
+progress and verification. The [follow-on health cleanup](specs/026-code-structure-and-quality-gates/health-plan.md)
+records removal of the legacy baseline and the Node 22 dependency updates.

package/docs/specs/001-state-verification/spec.md

@@ -1,12 +1,14 @@
 # RFC-001: Stronger State Verification
 
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md)
+
 Priority: 1
 Depends on: Snapshot v1
 Related Roadmap Item: Priority 1 — Stronger State Verification
 
 ---
 
-# 1. Problem
+## 1. Problem
 
 Agents currently infer UI control state too often from surrounding text or visual clues instead of reading authoritative control state.
 
@@ -35,7 +37,7 @@ Shift from visual inference to explicit state introspection.
 
 ---
 
-# 2. Goals
+## 2. Goals
 
 This RFC introduces:
 
@@ -52,7 +54,7 @@ Success goals:
 
 ---
 
-# 3. Non-Goals
+## 3. Non-Goals
 
 This RFC does not:
 
@@ -64,7 +66,7 @@ This RFC does not:
 
 ---
 
-# 4. Proposed Model
+## 4. Proposed Model
 
 ## 4.1 State Model Additions
 
@@ -209,7 +211,7 @@ Rules:
 
 ---
 
-# 5. Guardrails and Conflict Semantics
+## 5. Guardrails and Conflict Semantics
 
 Required invariants:
 
@@ -242,7 +244,7 @@ Observation and verification stay distinct.
 
 ---
 
-# 6. Protocol Delta (Draft)
+## 6. Protocol Delta (Draft)
 
 Snapshot schema extension:
 
@@ -278,7 +280,7 @@ capabilities: {
 
 ---
 
-# 7. Failure Modes
+## 7. Failure Modes
 
 Must define behavior for:
 
@@ -310,7 +312,7 @@ If snapshot freshness is uncertain, no assumptions of real-time synchronization.
 
 ---
 
-# 8. Acceptance Test Vectors
+## 8. Acceptance Test Vectors
 
 Representative benchmark flows:
 
@@ -366,7 +368,7 @@ Then:
 
 ---
 
-# 9. Acceptance Criteria
+## 9. Acceptance Criteria
 
 RFC considered complete when:
 
@@ -378,7 +380,7 @@ RFC considered complete when:
 
 ---
 
-# 10. Success Metrics
+## 10. Success Metrics
 
 Target outcomes:
 
@@ -390,7 +392,7 @@ Measured against roadmap KPIs.
 
 ---
 
-# 11. Normative Requirements (v1)
+## 11. Normative Requirements (v1)
 
 Implementations conforming to RFC-001:
 
@@ -415,7 +417,7 @@ MAY:
 
 ---
 
-# 12. Resolved Design Decisions
+## 12. Resolved Design Decisions
 
 Former open questions resolved for RFC-001:
 
@@ -441,7 +443,7 @@ No unresolved design blockers remain for RFC-001 draft scope.
 
 ---
 
-# 13. Deferred To Later RFCs
+## 13. Deferred To Later RFCs
 
 Deferred to later RFCs:
 
@@ -449,4 +451,4 @@ Deferred to later RFCs:
 - Compose semantic enrichment extensions
 - Wait/synchronization improvements
 - Action trace correlation
-- Gesture support
+- Gesture support

package/docs/specs/002-richer-element-identity/spec.md

@@ -1,11 +1,13 @@
 # RFC-002: Platform-Native Element Metadata and Resolution Hints
 
-Priority: 2  
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md)
+
+Priority: 2
 Depends on: RFC-001 (Stronger State Verification)
 
 ---
 
-# 1. Problem
+## 1. Problem
 
 Agents currently rely on brittle or inconsistent selectors when identifying UI elements.
 
@@ -28,7 +30,7 @@ This RFC does not assume that a universal or guaranteed stable_id exists across
 
 ---
 
-# 2. Goals
+## 2. Goals
 
 This RFC introduces:
 
@@ -45,7 +47,7 @@ Success goals:
 
 ---
 
-# 3. Non-Goals
+## 3. Non-Goals
 
 This RFC does not:
 
@@ -56,7 +58,7 @@ This RFC does not:
 
 ---
 
-# 4. Proposed Model
+## 4. Proposed Model
 
 ## 4.1 Stable Element Identity
 
@@ -336,7 +338,7 @@ Notes:
 
 ---
 
-# 5. Failure Modes
+## 5. Failure Modes
 
 ## 5.1 Ambiguous match
 
@@ -369,7 +371,7 @@ If UI structure changes:
 
 ---
 
-# 6. Acceptance Criteria
+## 6. Acceptance Criteria
 
 RFC-002 is complete when:
 
@@ -381,7 +383,7 @@ RFC-002 is complete when:
 
 ---
 
-# 7. Success Metrics
+## 7. Success Metrics
 
 - Higher element resolution match rate using platform-native metadata + confidence hints
 - Reduced selector retries
@@ -390,11 +392,11 @@ RFC-002 is complete when:
 
 ---
 
-# 8. Out of Scope
+## 8. Out of Scope
 
 - State verification (RFC-001)
 - Wait/synchronization (RFC-003)
 - Gestures (future RFCs)
 - Action tracing
 
-This RFC is scoped as a metadata and resolution hint layer. It does not guarantee stable identity across all platforms, but standardises how identity signals are exposed and consumed.
+This RFC is scoped as a metadata and resolution hint layer. It does not guarantee stable identity across all platforms, but standardises how identity signals are exposed and consumed.

package/docs/specs/003-wait-and-synchronization-reliability/spec.md

@@ -1,11 +1,13 @@
 # RFC-003: Wait and Synchronization Reliability
 
-Priority: 3  
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md)
+
+Priority: 3
 Depends on: RFC-001 (Stronger State Verification), RFC-002 (Platform-Native Element Metadata and Resolution Hints)
 
 ---
 
-# 1. Problem
+## 1. Problem
 
 Agents can often identify the right element (RFC-002) and verify the right state (RFC-001), but still fail because they act before the UI has reached the intended post-action state.
 
@@ -26,7 +28,7 @@ Current system limitations:
 
 ---
 
-# 2. Goals
+## 2. Goals
 
 This RFC introduces:
 
@@ -45,7 +47,7 @@ Success goals:
 
 ---
 
-# 3. Non-Goals
+## 3. Non-Goals
 
 This RFC does not:
 
@@ -56,7 +58,7 @@ This RFC does not:
 
 ---
 
-# 4. Proposed Model
+## 4. Proposed Model
 
 ## 4.1 UI-First Synchronization Contract (v1)
 
@@ -219,7 +221,7 @@ These are synchronization hints layered on top of standard wait behaviour.
 
 ---
 
-# 5. Failure Modes
+## 5. Failure Modes
 
 ## 5.1 Premature Action Progression
 
@@ -257,7 +259,7 @@ If unrelated UI churn triggers early wait completion:
 
 ---
 
-# 6. Acceptance Criteria
+## 6. Acceptance Criteria
 
 RFC-003 specification is complete when:
 
@@ -275,7 +277,7 @@ Implementation readiness success is measured when:
 
 ---
 
-# 7. Success Metrics
+## 7. Success Metrics
 
 - Fewer retries caused by timing/synchronization errors
 - Higher post-action verification success rate
@@ -284,7 +286,7 @@ Implementation readiness success is measured when:
 
 ---
 
-# 8. Deferred To Later RFCs
+## 8. Deferred To Later RFCs
 
 - Advanced subscriptions / notify-when-element-appears APIs
 - Full action-to-ui trace correlation (Priority 7)
@@ -293,4 +295,4 @@ Implementation readiness success is measured when:
 
 ---
 
-This RFC standardises temporal reliability and synchronization signals layered on top of state verification and element identity guarantees from RFC-001 and RFC-002.
+This RFC standardises temporal reliability and synchronization signals layered on top of state verification and element identity guarantees from RFC-001 and RFC-002.

package/docs/specs/004-action-verification-routing/spec.md

@@ -1,7 +1,7 @@
-
-
 # RFC 004: Verification Routing for Local and Side-Effect Actions
 
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md)
+
 ## Status
 Draft
 
@@ -339,4 +339,4 @@ Questions for review:
 
 ## Decision Requested
 
-Adopt verification routing based on action type and remove implicit default escalation from missing UI diffs to network inspection.
+Adopt verification routing based on action type and remove implicit default escalation from missing UI diffs to network inspection.

package/docs/specs/005-unified-action-execution-and-verification-model/spec.md

@@ -1,5 +1,7 @@
 # RFC 005 — Unified Action Execution and Verification Model
 
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md)
+
 ## 1. Summary
 
 This RFC defines a unified execution and verification model for all agent-driven UI actions.

package/docs/specs/006-runtime-action-instrumentation-and-binding-layer/spec.md

@@ -1,5 +1,7 @@
 # RFC 006 — Runtime Action Instrumentation & Binding Layer
 
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md)
+
 ## 1. Summary
 
 This RFC defines how the execution model in RFC 005 is mapped onto the current runtime behaviour of the system.

package/docs/specs/007-actionability-resolution-and-executable-target-selection/spec.md

@@ -1,5 +1,7 @@
 # RFC 007 — Actionability Resolution and Executable Target Selection
 
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md)
+
 ## 1. Summary
 
 This RFC defines how the system resolves which discovered UI element should receive an action before dispatch.
@@ -274,4 +276,4 @@ It improves:
 - Compose interaction robustness
 - agent success with fewer retries
 
-It addresses one of the largest remaining sources of interaction brittleness.
+It addresses one of the largest remaining sources of interaction brittleness.

package/docs/specs/008-adjustable-control-support-and-semantic-value-manipulation/spec.md

@@ -1,8 +1,7 @@
-
-
-
 # RFC 008 — Adjustable Control Support and Semantic Value Manipulation
 
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md)
+
 ## 1. Summary
 
 This RFC defines semantic interaction support for adjustable controls whose primary interaction changes a value rather than triggering a discrete action.
@@ -270,4 +269,4 @@ It does not commit in this RFC to:
 - arbitrary drag or canvas manipulation
 - pinch-to-zoom or broader gesture semantics
 
-This RFC specifies the behavioral model adjustable-control support should satisfy as implementations mature.
+This RFC specifies the behavioral model adjustable-control support should satisfy as implementations mature.

package/docs/specs/009-semantic-control-modeling-for-custom-and-composite-controls/spec.md

@@ -1,5 +1,7 @@
 # RFC 009 — Semantic Control Modeling for Custom and Composite Controls
 
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md)
+
 ## 1. Summary
 
 This RFC defines a semantic control model for identifying, exposing, and interacting with custom and composite controls that are poorly represented through raw accessibility or platform UI trees.

package/docs/specs/010-verification-stabilization-and-temporal-convergence/spec.md

@@ -1,7 +1,7 @@
-
-
 # RFC 010 — Verification Stabilization and Temporal Convergence
 
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md)
+
 ## 1. Summary
 
 This RFC defines a verification stabilization layer that ensures UI state transitions are not misclassified due to timing instability, transient UI states, or stale snapshots.

package/docs/specs/011-recovery-and-replanning-for-failed-or-ambiguous-interaction-flows/spec.md

@@ -1,7 +1,7 @@
-
-
 # RFC 011 — Recovery and Replanning for Failed or Ambiguous Interaction Flows
 
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md)
+
 ## 1. Summary
 
 This RFC defines a structured recovery and replanning model for UI interaction failures, enabling the system to respond to execution uncertainty with bounded, deterministic recovery strategies.

package/docs/specs/011.1-recovery-contract-types-and-runtime-wiring-spec/spec.md

@@ -1,5 +1,7 @@
 # RFC 011.1 — Recovery Contract Types & Runtime Wiring Spec
 
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md)
+
 ## 1. Purpose
 
 This document defines the typed runtime contract required to implement RFC 011 safely and consistently across:

package/docs/specs/012-action-trace-and-xecution-observability/spec.md

@@ -1,8 +1,7 @@
-
-
-
 # RFC 012 — Action Trace and Execution Observability
 
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md)
+
 ## 1. Summary
 
 This RFC defines a structured execution trace model for all actions within the MCP runtime. It provides visibility into resolution, execution, verification, stabilization, and recovery stages.