mobile-debug-mcp 0.27.0 → 0.29.0

package/docs/ROADMAP.md

@@ -45,25 +45,22 @@ Higher task success with fewer retries.
 - 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)
 
 ## Current Focus
 
-- Wait and Synchronization Reliability
+- Wait and Synchronization Reliability (implementation + tuning)
 - Actionability Resolution
-- Verification Stabilization and Temporal Convergence
+- Adjustable Control Precision Hardening
 
 ## Upcoming Work
 
 - Adjustable Control Precision Hardening
 - Environment Auto-Configuration and Toolchain Discovery
 - Adjustable Control Support
-- Verification Stabilization and Temporal Convergence
 - Signal-Oriented Diagnostic Filtering
 - Long Press Gesture
-# Stronger State Verification
-# Richer Element Identity
-# Wait and Synchronization Reliability
-# Environment Auto-Configuration and Toolchain Discovery
 
 ## Rationale
 Reduce onboarding friction and improve developer experience by minimizing manual setup dependencies.
@@ -115,7 +112,7 @@ Strengthens:
 ## Later Horizon
 
 - Pinch to Zoom
-- Action Trace Correlation
+- Advanced Trace Correlation and Analysis
 
 ---
 
@@ -251,7 +248,7 @@ Blocks or strengthens:
 ## Rationale
 Real-world feedback exposed false-negative readiness failures caused by transient UI timing, even when target state had actually converged.
 
-**Status:** Planned
+**Status:** Completed
 
 Addresses friction where agents:
 - fail readiness checks on transient timing races
@@ -615,12 +612,14 @@ Depends on:
 
 ---
 
-# Action Trace Correlation
+# Advanced Trace Correlation
 
 ## Rationale
 Very valuable for debugging,
 but less critical than improving control success first.
 
+Builds on the foundational Action Trace and Execution Observability capability by linking traces across UI, network, and logs.
+
 **Status:** Planned
 
 Improves diagnosis more than task completion.
@@ -695,7 +694,6 @@ Make core loop reliable and reduce onboarding friction.
 - Adjustable Control Precision Hardening
 - Better Compose / Custom Control Semantics
 - Signal-Oriented Diagnostic Filtering
-- Verification Stabilization and Temporal Convergence
 
 Focus:
 Improve control precision, verification convergence, custom control reliability, and signal observability.
@@ -712,7 +710,7 @@ Expand interaction capability after core control reliability is improved.
 
 ## Wave 4 (Advanced Gestures + Deep Observability)
 - Pinch to Zoom
-- Action Trace Correlation
+- Advanced Trace Correlation and Analysis
 
 Focus:
 Advanced gestures + deep observability.
@@ -725,16 +723,15 @@ Roadmap Ordering:
 1. Stronger State Verification
 2. Richer Element Identity
 3. Wait and Synchronization Reliability
-4. Verification Stabilization and Temporal Convergence
-5. Environment Auto-Configuration and Toolchain Discovery
-6. Actionability Resolution
-7. Adjustable Control Support
-8. Adjustable Control Precision Hardening
-9. Better Compose / Custom Control Semantics
-10. Signal-Oriented Diagnostic Filtering
-11. Long Press Gesture
-12. Pinch to Zoom
-13. Action Trace Correlation
+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.

package/docs/rfcs/{012.md → 012-action-trace-and-xecution-observability.md}

@@ -68,7 +68,7 @@ interface ActionTrace {
   action_id: string;
   steps: TraceStep[];
   final_outcome: "success" | "failure";
-  attempts: number;
+  attempts: number; // total execution attempts including recovery-triggered retries
 }
 ```
 
@@ -79,10 +79,25 @@ interface TraceStep {
   stage: "resolve" | "execute" | "verify" | "stabilize" | "recover";
   timestamp: number;
   result: "success" | "failure" | "retry";
+  attempt_index: number; // monotonic per action execution
+  cycle_id?: number; // groups steps within a recovery cycle
   metadata?: Record<string, any>;
 }
 ```
 
+### 6.3 Partial Trace Requirements
+
+For actions that do not traverse the full lifecycle (resolve → execute → verify → stabilize → recover), implementations MUST emit a partial trace.
+
+A partial trace MUST:
+- include a valid action_id
+- include final_outcome
+- include at least one TraceStep with a valid stage and timestamp
+
+Partial traces MUST still respect attempt_index semantics.
+
+This ensures observability coverage even for legacy or bypass execution paths.
+
 ---
 
 ## 7. Stage Emission Rules
@@ -158,13 +173,32 @@ Metadata MUST remain lightweight.
 - RFC 010: stabilization emits stabilize stage
 - RFC 011: recovery emits recover stage
 
-This RFC unifies these into a single trace model.
+### 10.1 Compatibility with RFC 006 Observability Model
+
+RFC 006 defines traceability as being assembled from distributed signals rather than a centralized event system.
+
+This RFC does NOT replace that model; it standardizes a unified projection layer over those signals.
+
+- Existing emitters (server, interact, stabilization, recovery) remain the source of truth
+- RFC 012 defines how those signals are composed into a single ActionTrace
+- Actions that bypass parts of the lifecycle MUST still emit partial traces reflecting the stages they execute
+
+This ensures backward compatibility while enabling a coherent trace surface.
 
 ---
 
 ## 11. Output Behavior
 
-Trace MAY be returned as part of action results or stored internally.
+Trace MUST be produced for all action flows (full or partial, depending on runtime capability).
+
+Canonical contract:
+- Trace SHOULD be included in ActionExecutionResult when the runtime path supports full trace emission
+- Trace MAY also be stored internally for diagnostics
+
+If a runtime path cannot yet emit a full trace (e.g. legacy or bypass actions), it MUST emit a partial trace containing at least:
+- action_id
+- final_outcome
+- at least one TraceStep representing the executed stage
 
 Example:
 
@@ -172,10 +206,15 @@ Example:
 interface ActionExecutionResult {
   success: boolean;
   failure_code?: string;
-  trace?: ActionTrace;
+  trace?: ActionTrace; // optional in type, required by RFC behavior (full or partial)
 }
 ```
 
+
+Implementations MUST treat the absence of `trace` in the runtime type as a temporary compatibility constraint, not as an absence of trace generation. All execution paths MUST still generate a trace internally, even if only a partial trace is returned externally.
+
+The optionality of `trace` in ActionExecutionResult is transitional. Implementations MUST treat the absence of `trace` as a compatibility constraint rather than a valid steady-state. Future versions of the runtime MAY require `trace` to be present on all ActionExecutionResult values once all execution paths support full trace emission.
+
 ---
 
 ## 12. Failure Analysis

package/docs/specs/mcp-tooling-spec-v1.md

@@ -80,6 +80,19 @@ MUST be returned in this structure:
   ui_fingerprint_after: string | null,
   failure_code?: string,
   retryable?: boolean,
+  trace: {
+    action_id: string,
+    steps: Array<{
+      stage: 'resolve' | 'execute' | 'verify' | 'stabilize' | 'recover',
+      timestamp: number,
+      result: 'success' | 'failure' | 'retry',
+      attempt_index: number,
+      cycle_id?: number,
+      metadata?: Record<string, unknown>
+    }>,
+    final_outcome: 'success' | 'failure',
+    attempts: number
+  },
   recovery?: {
     failure_class: string,
     runtime_code: string,
@@ -104,6 +117,7 @@ Rules:
 - `source_module` identifies where the envelope was produced
 - fingerprints represent observed pre/post UI state on a best-effort basis
 - `failure_code` is optional but MUST be used when a structured mapping exists
+- `trace` is required and carries the observable execution path
 - `recovery` MAY be attached to failed actions to carry typed recovery metadata
 
 ### 4.4 Allowed Deviations

package/docs/tools/interact.md

@@ -40,6 +40,25 @@ Example response:
   "source_module": "server",
   "target": { "selector": { "x": 100, "y": 200 }, "resolved": null },
   "success": true,
+  "trace": {
+    "action_id": "tap_element_1710000000002_3",
+    "steps": [
+      {
+        "stage": "resolve",
+        "timestamp": 1710000000002,
+        "result": "success",
+        "attempt_index": 0
+      },
+      {
+        "stage": "execute",
+        "timestamp": 1710000000003,
+        "result": "success",
+        "attempt_index": 1
+      }
+    ],
+    "final_outcome": "success",
+    "attempts": 1
+  },
   "ui_fingerprint_before": "fp_before",
   "ui_fingerprint_after": "fp_after"
 }
@@ -395,6 +414,31 @@ Failure response:
   "success": false,
   "failure_code": "STALE_REFERENCE",
   "retryable": true,
+  "trace": {
+    "action_id": "tap_element_1710000000003_4",
+    "steps": [
+      {
+        "stage": "resolve",
+        "timestamp": 1710000000003,
+        "result": "failure",
+        "attempt_index": 0
+      },
+      {
+        "stage": "execute",
+        "timestamp": 1710000000004,
+        "result": "failure",
+        "attempt_index": 1
+      },
+      {
+        "stage": "recover",
+        "timestamp": 1710000000005,
+        "result": "retry",
+        "attempt_index": 2
+      }
+    ],
+    "final_outcome": "failure",
+    "attempts": 1
+  },
   "recovery": {
     "failure_class": "TargetResolutionFailure",
     "runtime_code": "STALE_REFERENCE",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-mcp",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {