mobile-debug-mcp 0.30.0 → 0.30.2

package/dist/observe/index.js

@@ -325,6 +325,7 @@ export class ToolsObserve {
         const snapshotMetadata = deriveSnapshotMetadata(snapshotDeviceKey, raw.ui_tree, 'snapshot', raw.ui_tree?.snapshot_revision ? null : (raw.fingerprint || raw.activity || null));
         raw.snapshot_revision = raw.ui_tree?.snapshot_revision ?? snapshotMetadata.snapshot_revision;
         raw.captured_at_ms = raw.ui_tree?.captured_at_ms ?? snapshotMetadata.captured_at_ms;
+        raw.snapshot_delta = raw.ui_tree?.snapshot_delta ?? snapshotMetadata.snapshot_delta ?? null;
         raw.loading_state = raw.ui_tree?.loading_state ?? snapshotMetadata.loading_state;
         const semantic = deriveSnapshotSemantic(raw);
         return semantic ? { raw, semantic } : { raw };

package/dist/observe/snapshot-metadata.js

@@ -30,6 +30,58 @@ function stableElementSignature(element) {
         bounds: normalizeBounds(element.bounds)
     };
 }
+function stableElementIdentity(element, index) {
+    const stableId = normalize(element.stable_id);
+    if (stableId)
+        return `stable:${stableId}`;
+    return `fallback:${crypto.createHash('sha1').update(JSON.stringify({
+        text: normalize(element.text),
+        contentDescription: normalize(element.contentDescription),
+        resourceId: normalize(element.resourceId),
+        type: normalize(element.type),
+        bounds: normalizeBounds(element.bounds),
+        index
+    })).digest('hex')}`;
+}
+function buildElementSignatures(tree) {
+    const signatures = new Map();
+    const elements = Array.isArray(tree?.elements) ? tree.elements : [];
+    for (let index = 0; index < elements.length; index++) {
+        const element = elements[index];
+        if (!element)
+            continue;
+        const identity = stableElementIdentity(element, index);
+        signatures.set(identity, crypto.createHash('sha1').update(JSON.stringify(stableElementSignature(element))).digest('hex'));
+    }
+    return signatures;
+}
+function summarizeSnapshotDelta(previous, currentElements) {
+    if (!previous)
+        return null;
+    let added = 0;
+    let removed = 0;
+    let mutated = 0;
+    for (const [identity, signature] of currentElements.entries()) {
+        const previousSignature = previous.elementSignatures.get(identity);
+        if (previousSignature === undefined) {
+            added++;
+        }
+        else if (previousSignature !== signature) {
+            mutated++;
+        }
+    }
+    for (const identity of previous.elementSignatures.keys()) {
+        if (!currentElements.has(identity))
+            removed++;
+    }
+    return {
+        previous_snapshot_revision: previous.revision,
+        added_elements: added,
+        removed_elements: removed,
+        mutated_elements: mutated,
+        total_elements: currentElements.size
+    };
+}
 export function computeSnapshotSignature(tree) {
     if (!tree || tree.error)
         return null;
@@ -67,6 +119,10 @@ export function detectLoadingState(tree, source) {
 export function deriveSnapshotMetadata(deviceKey, tree, source, signatureOverride) {
     const signature = signatureOverride ?? computeSnapshotSignature(tree);
     const previous = snapshotStateByDevice.get(deviceKey);
+    const hasValidTree = !!tree && !tree.error;
+    const currentElementSignatures = hasValidTree
+        ? buildElementSignatures(tree)
+        : previous?.elementSignatures ?? new Map();
     let revision = 1;
     if (previous) {
         if (signature === null) {
@@ -76,10 +132,15 @@ export function deriveSnapshotMetadata(deviceKey, tree, source, signatureOverrid
             revision = previous.signature === signature ? previous.revision : previous.revision + 1;
         }
     }
-    snapshotStateByDevice.set(deviceKey, { revision, signature });
+    snapshotStateByDevice.set(deviceKey, {
+        revision,
+        signature,
+        elementSignatures: currentElementSignatures
+    });
     return {
         snapshot_revision: revision,
         captured_at_ms: Date.now(),
+        snapshot_delta: hasValidTree ? summarizeSnapshotDelta(previous, currentElementSignatures) : null,
         loading_state: detectLoadingState(tree, source)
     };
 }

package/dist/server/tool-definitions.js

@@ -244,7 +244,7 @@ Failure Handling:
     },
     {
         name: 'capture_debug_snapshot',
-        description: 'Capture a complete debug snapshot (raw observation layer plus optional derived semantic layer). Returns structured JSON with snapshot_revision, captured_at_ms, and loading_state when detectable.',
+        description: 'Capture a complete debug snapshot (raw observation layer plus optional derived semantic layer). Returns structured JSON with snapshot_revision, captured_at_ms, snapshot_delta, and loading_state when detectable.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -295,7 +295,7 @@ Failure Handling:
     },
     {
         name: 'get_ui_tree',
-        description: 'Get the current UI hierarchy from an Android device or iOS simulator. Returns a structured JSON representation of the screen content with snapshot metadata when available.',
+        description: 'Get the current UI hierarchy from an Android device or iOS simulator. Returns a structured JSON representation of the screen content with snapshot metadata and incremental delta signals when available.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -376,11 +376,14 @@ Inputs:
 - expected_change (optional): hierarchy_diff, text_change, or state_change
 - timeout_ms (optional)
 - stability_window_ms (optional)
+- scope (optional): screen or subtree
+- target (optional): element_id when scope=subtree
 
 Guidance:
 - Prefer wait_for_screen_change for navigation transitions.
 - Prefer wait_for_ui_change for in-place mutations and non-navigation updates.
 - Use the returned snapshot_revision as the observed synchronization point when available.
+- Scoped waits return scope-aware stability metadata and a lightweight change summary.
 
 Failure Handling:
 - TIMEOUT means the UI did not change in a stable way within the allotted time.`,
@@ -390,6 +393,8 @@ Failure Handling:
                 platform: { type: 'string', enum: ['android', 'ios'], description: 'Optional platform override (android|ios)' },
                 deviceId: { type: 'string', description: 'Optional device id/udid to target' },
                 expected_change: { type: 'string', enum: ['hierarchy_diff', 'text_change', 'state_change'], description: 'Optional type of UI change to wait for' },
+                scope: { type: 'string', enum: ['screen', 'subtree'], default: 'screen', description: 'Synchronization scope for the wait' },
+                target: { type: 'string', description: 'Target element_id when scope is subtree' },
                 timeout_ms: { type: 'number', description: 'Timeout in ms to wait for change (default 60000)', default: 60000 },
                 stability_window_ms: { type: 'number', description: 'How long the change must remain stable before success (default 300)', default: 300 }
             }
@@ -563,11 +568,11 @@ Adjust a numeric control value with verification.
 This is the initial adjustable-control surface for slider-like controls and other controls that expose a numeric value or value_range.
 
 Inputs:
-- selector or element_id
+- exactly one of selector or element_id
 - property (defaults to "value")
 - targetValue
-- tolerance (optional)
-- maxAttempts (optional)
+- tolerance (optional; discrete default is 0, continuous default is max(step / 2, 1% of range) when omitted)
+- maxAttempts (optional; defaults to 5)
 - platform/deviceId (optional)
 
 Output Structure:
@@ -579,14 +584,14 @@ Output Structure:
 - success = true when the control converges within tolerance
 
 Verification Guidance:
-- Prefer direct target placement when value_range is available; fall back to a drag only if the direct tap does not converge
+- Prefer direct platform adjustment when the runtime exposes it; then verified increment/decrement actions; use coordinate fallback only as degraded mode
 - Use expect_state for the control value readback
-- Treat coordinate fallback as degraded mode
+- Do not use derived semantic metadata as proof of success
 
 Failure Handling:
 - ELEMENT_NOT_FOUND → re-resolve the control
 - ELEMENT_NOT_INTERACTABLE → the control cannot be adjusted through the current runtime
-- TIMEOUT → the control did not converge within bounded retries
+- CONTROL_CONVERGENCE_FAILED → the control did not converge within bounded retries or the requested value is out of range
 - UNKNOWN → capture a snapshot and stop`,
         inputSchema: {
             type: 'object',
@@ -603,12 +608,16 @@ Failure Handling:
                 element_id: { type: 'string', description: 'Optional previously resolved element identifier.' },
                 property: { type: 'string', description: 'Readable numeric state property to adjust.', default: 'value' },
                 targetValue: { type: 'number', description: 'Target numeric value.' },
-                tolerance: { type: 'number', description: 'Accepted numeric tolerance around the target value.', default: 0 },
-                maxAttempts: { type: 'number', description: 'Maximum adjustment attempts.', default: 3 },
+                tolerance: { type: 'number', description: 'Accepted numeric tolerance around the target value. Defaults are derived from the readable control domain.' },
+                maxAttempts: { type: 'number', description: 'Maximum adjustment attempts.', default: 5 },
                 platform: { type: 'string', enum: ['android', 'ios'], description: 'Optional platform override' },
                 deviceId: { type: 'string', description: 'Optional device serial/udid' }
             },
-            required: ['targetValue']
+            required: ['targetValue'],
+            oneOf: [
+                { required: ['selector'] },
+                { required: ['element_id'] }
+            ]
         }
     },
     {

package/dist/server/tool-handlers.js

@@ -231,12 +231,12 @@ async function handleAdjustControl(args) {
     const element_id = getStringArg(args, 'element_id');
     const property = getStringArg(args, 'property') ?? 'value';
     const targetValue = requireNumberArg(args, 'targetValue');
-    const tolerance = getNumberArg(args, 'tolerance') ?? 0;
-    const maxAttempts = getNumberArg(args, 'maxAttempts') ?? 3;
+    const tolerance = getNumberArg(args, 'tolerance');
+    const maxAttempts = getNumberArg(args, 'maxAttempts');
     const platform = getStringArg(args, 'platform');
     const deviceId = getStringArg(args, 'deviceId');
-    if (!selector && !element_id) {
-        throw new Error('Missing selector or element_id argument');
+    if ((!selector && !element_id) || (selector && element_id)) {
+        throw new Error('Exactly one of selector or element_id argument is required');
     }
     const res = await ToolsInteract.adjustControlHandler({
         selector: selector ?? undefined,
@@ -268,7 +268,9 @@ async function handleWaitForUIChange(args) {
     const timeout_ms = getNumberArg(args, 'timeout_ms') ?? 60000;
     const stability_window_ms = getNumberArg(args, 'stability_window_ms') ?? 300;
     const expected_change = getStringArg(args, 'expected_change');
-    const res = await ToolsInteract.waitForUIChangeHandler({ platform, deviceId, timeout_ms, stability_window_ms, expected_change });
+    const scope = getStringArg(args, 'scope');
+    const target = getStringArg(args, 'target');
+    const res = await ToolsInteract.waitForUIChangeHandler({ platform, deviceId, timeout_ms, stability_window_ms, expected_change, scope, target });
     return wrapResponse(res);
 }
 async function handleFindElement(args) {

package/dist/server-core.js

@@ -6,7 +6,7 @@ import { handleToolCall } from './server/tool-handlers.js';
 export { wrapResponse, toolDefinitions, handleToolCall };
 export const serverInfo = {
     name: 'mobile-debug-mcp',
-    version: '0.30.0'
+    version: '0.30.2'
 };
 export function createServer() {
     const server = new Server(serverInfo, {

package/docs/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.30.2]
+- improved slider interaction
+
+## [0.30.1]
+- Synced the server-reported version in `src/server-core.ts` with `package.json` so contract checks pass.
+- Completed the RFC 013 wait/synchronization implementation, including scoped waits and freshness metadata.
+- Completed the RFC 014 actionability implementation for taps and adjustable controls.
+- Added regression coverage for subtree collection, scoped waits, snapshot deltas, and stale actionability checks.
+
 ## [0.30.0]
 - Folded RFC 013 synchronization semantics into the main spec and aligned the interact docs with the shipped `wait_for_ui_change` behavior.
 - Updated `wait_for_ui_change` to use a 300ms stabilization default and to reset stabilization on new in-place mutations.

package/docs/ROADMAP.md

@@ -1,124 +1,26 @@
 # Mobile Debug MCP Roadmap
 
-## Planning Principles
-
-Ordered by:
-
-
-1. Impact on agent reliability  
-2. Reduction in retries / brittleness  
-3. Breadth of app coverage improved  
-4. Implementation complexity vs payoff
-
-## Capability Status Definitions
-
-- **Completed**  
-  Capability implemented and considered part of the baseline platform.
-
-- **Spec Ready**  
-  Capability design or RFC is mature and implementation-ready, but not yet delivered.
-
-- **Planned**  
-  Capability is prioritized on the roadmap, but detailed specification and/or implementation work remains ahead.
-
-## Program-Level Success Metrics
-Track roadmap impact across releases using:
-
-- Retry reduction rate (% fewer action retries per task)
-- Element match success rate (% successful element targeting)
-- Verification success rate (% expect_* checks passing first attempt)
-- Wait success rate for asynchronous UI flows
-- Custom control interaction success rate
-- Gesture success rate
-- Mean time to root cause during debugging
-- Overall agent task completion rate
-- Reduced sequencing errors in multi-step interaction flows
-
-Primary KPI:
-Higher task success with fewer retries.
-
----
-
-# Roadmap Status Overview
-
-## Completed Capabilities
-
-- Stronger State Verification — Complete (Foundational verification layer shipped)
-- Richer Element Identity — Complete (Identity and selector confidence foundations shipped)
-- Better Compose / Custom Control Semantics — Complete (Semantic role enrichment and custom-adjustable inference shipped)
-- Verification Stabilization and Temporal Convergence — Complete (Temporal verification and convergence logic shipped)
-- Action Trace and Execution Observability — Complete (Structured execution trace model shipped)
-- Wait and Synchronization Reliability — Complete (RFC 013 folded into the main spec and shipped behavior verified on emulator)
-
-## Current Focus
+## Done
 
+- Stronger State Verification
+- Richer Element Identity
+- Better Compose / Custom Control Semantics
+- Verification Stabilization and Temporal Convergence
+- Action Trace and Execution Observability
+- Wait and Synchronization Reliability
 - Actionability Resolution
-- Adjustable Control Precision Hardening
 
-## Upcoming Work
+## Todo
 
+- Adjustable Control Support
 - Adjustable Control Precision Hardening
 - Environment Auto-Configuration and Toolchain Discovery
-- Adjustable Control Support
 - Signal-Oriented Diagnostic Filtering
 - Long Press Gesture
-
-## Rationale
-Reduce onboarding friction and improve developer experience by minimizing manual setup dependencies.
-
-**Status:** Planned
-
-Addresses friction around:
-- manual idb installation
-- manual adb path configuration
-- manual xcrun path configuration
-- environment drift across machines
-- setup failures blocking first use
-
-- Automatic discovery of adb
-- Automatic discovery of xcrun
-- idb detection and guided bootstrap support
-- Startup toolchain validation
-- Environment health diagnostics / doctor-style checks
-- Minimal-manual-configuration defaults
-- Runtime device/emulator health signals (crash detection, process lifecycle awareness)
-- App stability monitoring during active sessions
-
-## Expected Impact
-High.
-
-## Exit Criteria
-- adb and xcrun auto-discovery implemented
-- Missing dependencies surfaced with guided remediation
-- Startup environment validation available
-- Manual path configuration eliminated or minimized for standard setups
-- First-run setup validated on representative developer environments
-
-## Success Metrics
-- Reduced setup friction during onboarding
-- Lower environment configuration failures
-- Faster time-to-first-successful-session
-- Reduced support/debugging caused by local setup issues
-- Reduced unknown-failure sessions caused by app or emulator instability
-
-## Dependencies
-Depends on:
-- Stronger State Verification
-- Richer Element Identity
-
-Strengthens:
-- Actionability Resolution
-- Broader user adoption readiness
-
----
-
-## Later Horizon
-
+- Runtime Debugger Introspection
 - Pinch to Zoom
 - Advanced Trace Correlation and Analysis
 
----
-
 # Stronger State Verification
 
 ## Rationale
@@ -577,6 +479,81 @@ Depends on:
 
 ---
 
+# Runtime Debugger Introspection
+
+## Rationale
+Enables agents to move from symptom observation to runtime causal analysis by inspecting paused application state during debugging sessions.
+
+**Status:** Planned
+
+Addresses limitations where agents:
+- observe UI failures but cannot determine runtime cause
+- cannot inspect ViewModel or controller state
+- lack access to local variables and stack context
+- cannot reason about async execution state
+
+## Scope
+Debugger-assisted runtime inspection primitives:
+
+```javascript
+debugger.pause_state()
+debugger.stack_trace()
+debugger.locals()
+debugger.inspect_object(object_id)
+debugger.evaluate(expression)
+debugger.threads()
+```
+
+Includes:
+- stack frame inspection
+- local variable inspection
+- object graph traversal
+- thread inspection
+- expression evaluation
+- platform abstraction over JDWP / LLDB
+- bounded object expansion and summarization
+- coroutine/task inspection support
+
+Future exploration:
+- controlled stepping support
+- debugger-assisted recovery workflows
+
+## Expected Impact
+Very high.
+
+Transforms debugging from:
+- surface-level symptom detection
+
+toward:
+- root-cause-oriented runtime reasoning
+
+## Exit Criteria
+- Paused runtime state accessible through MCP
+- Local variable inspection implemented
+- Stack trace inspection implemented
+- Object inspection primitives implemented
+- Runtime inspection validated on representative Android flows
+- Object expansion safeguards implemented
+- Expression evaluation available with safety limits
+
+## Success Metrics
+- Lower mean time-to-root-cause
+- Higher causal diagnosis accuracy
+- Reduced debugging iteration loops
+- Faster identification of state-management failures
+- Improved async/concurrency failure diagnosis
+
+## Dependencies
+Depends on:
+- Action Trace and Execution Observability
+- Stronger State Verification
+- Wait and Synchronization Reliability
+- Signal-Oriented Diagnostic Filtering
+
+Strengthens:
+- Advanced Trace Correlation and Analysis
+- Future autonomous recovery systems
+
 # Pinch to Zoom
 
 ## Rationale
@@ -658,104 +635,3 @@ Depends on:
 - Stronger State Verification
 - Richer Element Identity
 - Wait and Synchronization Reliability
-
----
-
-# Roadmap Sequence
-
-## Dependency Summary
-
-Foundation
-- Stronger State Verification
-- Richer Element Identity
-
-Synchronization & Actionability
-- Environment Auto-Configuration and Toolchain Discovery
-- Wait and Synchronization Reliability
-- Actionability Resolution
-
-Control Precision & Observability
-- Adjustable Control Support
-- Adjustable Control Precision Hardening
-- Better Compose / Custom Control Semantics
-- Signal-Oriented Diagnostic Filtering
-- Verification Stabilization and Temporal Convergence
-
-Interaction Expansion
-- Long Press Gesture
-- Pinch to Zoom
-
-Deep Observability
-- Advanced Trace Correlation and Analysis
-
-## Wave 1 (Current Focus)
-- Stronger State Verification
-- Richer Element Identity
-- Wait and Synchronization Reliability
-- Actionability Resolution
-- Environment Auto-Configuration and Toolchain Discovery
-
-Focus:
-Make core loop reliable and reduce onboarding friction.
-
----
-
-## Wave 2 (Control Precision + Diagnostics)
-- Adjustable Control Support
-- Adjustable Control Precision Hardening
-- Better Compose / Custom Control Semantics
-- Signal-Oriented Diagnostic Filtering
-
-Focus:
-Improve control precision, verification convergence, custom control reliability, and signal observability.
-
----
-
-## Wave 3 (Interaction Expansion)
-- Long Press Gesture
-
-Focus:
-Expand interaction capability after core control reliability is improved.
-
----
-
-## Wave 4 (Advanced Gestures + Deep Observability)
-- Pinch to Zoom
-- Advanced Trace Correlation and Analysis
-
-Focus:
-Advanced gestures + deep observability.
-
----
-
-# Roadmap Ordering
-
-Roadmap Ordering:
-1. Stronger State Verification
-2. Richer Element Identity
-3. Wait and Synchronization Reliability
-4. Actionability Resolution
-5. Adjustable Control Support
-6. Adjustable Control Precision Hardening
-7. Environment Auto-Configuration and Toolchain Discovery
-8. Better Compose / Custom Control Semantics
-9. Signal-Oriented Diagnostic Filtering
-10. Long Press Gesture
-11. Pinch to Zoom
-12. Advanced Trace Correlation and Analysis
-
-Rationale:
-- Early roadmap items harden state, targeting, synchronization, environment readiness, and action execution.
-- Mid roadmap items improve control precision and signal observability.
-- Later interaction-focused items expand interaction coverage.
-- Final observability work deepens debugging observability.
-
----
-
-## Future Considerations
-Still out of scope:
-
-- Full autonomous recovery planning (deferred until after verification stabilization)
-- Autonomous retry strategy
-- MCP-level agent orchestration
-- Autonomous recovery hinting (future consideration only)

package/docs/{rfcs → specs-deltas}/013-wait-and-synchronization-reliability.md

@@ -283,26 +283,13 @@ wait_for_ui_change({
   deviceId?: string,
   timeout_ms?: number,
   stability_window_ms?: number,
-  expected_change?: string
+  expected_change?: string,
+  scope?: "screen" | "subtree",
+  target?: string
 })
 ```
 
-### Proposed Future Extensions
-
-The following fields are proposed extensions and are not currently part of the shipped contract:
-
-```json
-{
-  "scope": "screen" | "subtree",
-  "target": "element_id"
-}
-```
-
-These extensions are illustrative and intended to support:
-
-- subtree synchronization
-- scoped convergence
-- token-efficient synchronization
+`scope=subtree` requires a target `element_id` and narrows synchronization to the resolved element subtree.
 
 ### Semantics
 
@@ -512,17 +499,12 @@ The current implementation exposes:
  - `snapshot_revision`
  - `captured_at_ms`
  - advisory `loading_state`
+ - `scope` and `target` on wait responses
+ - `stability_state` and scoped `change_summary` on wait responses
 
 The `loading_state` field is currently an advisory structured object rather than a simple enum value.
 
-The implementation does not currently expose explicit freshness states such as:
-
-- `fresh`
-- `stale`
-- `transient`
-- `stable`
-
-Those concepts in this RFC describe synchronization semantics rather than currently shipped payload fields.
+Wait responses also include a `snapshot_freshness_ms` age value so callers can reason about freshness without inferring it from revision numbers alone.
 
 ### Requirements
 
@@ -533,15 +515,7 @@ Those concepts in this RFC describe synchronization semantics rather than curren
 
 ### Proposed Stability States
 
-Future implementations may expose explicit synchronization stability states.
-
-Potential states include:
-
-- `transient`
-- `stabilizing`
-- `stable`
-
-These are not currently emitted by the shipped implementation.
+The shipped implementation emits `transient` while a wait is still converging and `stable` once the stabilization window has completed.
 
 ---
 
@@ -586,6 +560,8 @@ Examples:
 - improve synchronization latency
 - improve Compose hierarchy handling
 
+The shipped runtime exposes scope-aware waits and snapshot delta summaries on UI tree and debug snapshot responses to keep this signal lightweight.
+
 ---
 
 ## 7.5 Incremental Snapshot Delivery
@@ -599,6 +575,8 @@ Example capabilities:
 - partial hierarchy refreshes
 - revision patch delivery
 
+The shipped runtime currently exposes revision-aware `snapshot_delta` metadata rather than transport-level patch payloads.
+
 ### Dependency
 
 Incremental synchronization depends on stable element identity semantics.
@@ -826,6 +804,8 @@ Introduce:
 - diff-based synchronization
 - subtree invalidation
 
+The runtime now exposes scoped diff summaries for waits, but full partial-hierarchy patch delivery remains a future protocol extension.
+
 ---
 
 ## Phase 4
@@ -887,4 +867,4 @@ This RFC introduces explicit synchronization semantics that:
 - establish consistent sequencing expectations
 - create a foundation for incremental synchronization capabilities
 
-These changes are intended to improve reliability, reduce retries, and make agent behavior substantially more predictable across asynchronous mobile UI frameworks.
+These changes are intended to improve reliability, reduce retries, and make agent behavior substantially more predictable across asynchronous mobile UI frameworks.