mobile-debug-mcp 0.26.5 → 0.27.0

package/docs/rfcs/012.md

@@ -0,0 +1,203 @@
+
+
+
+# RFC 012 — Action Trace and Execution Observability
+
+## 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.
+
+The goal is to make system behavior explainable, debuggable, and measurable without altering execution semantics.
+
+---
+
+## 2. Problem Statement
+
+As the system has evolved (RFC 005–011), execution has become more reliable but also more opaque due to:
+
+- stabilization loops masking transient failures
+- recovery logic retrying actions without visibility
+- multiple execution stages (resolve → execute → verify → stabilize → recover)
+
+Current outputs provide final results but lack a structured explanation of how those results were reached.
+
+---
+
+## 3. Goals
+
+This RFC introduces an execution trace model that MUST:
+
+- provide a step-by-step record of action execution
+- expose resolution, execution, verification, stabilization, and recovery stages
+- remain deterministic and low-overhead
+- be consistent across all tools and handlers
+
+---
+
+## 4. Non-Goals
+
+This RFC does NOT define:
+
+- external logging systems
+- UI visualization layers
+- distributed tracing infrastructure
+
+It is strictly an in-process observability model.
+
+---
+
+## 5. Runtime Surfaces
+
+Trace data MUST be emitted from:
+
+- src/server (resolution)
+- src/interact (execution and verification)
+- stabilization layer (RFC 010)
+- recovery layer (RFC 011)
+
+All action flows MUST produce a trace.
+
+---
+
+## 6. Trace Model
+
+### 6.1 ActionTrace
+
+```ts
+interface ActionTrace {
+  action_id: string;
+  steps: TraceStep[];
+  final_outcome: "success" | "failure";
+  attempts: number;
+}
+```
+
+### 6.2 TraceStep
+
+```ts
+interface TraceStep {
+  stage: "resolve" | "execute" | "verify" | "stabilize" | "recover";
+  timestamp: number;
+  result: "success" | "failure" | "retry";
+  metadata?: Record<string, any>;
+}
+```
+
+---
+
+## 7. Stage Emission Rules
+
+### 7.1 Resolve Stage
+
+- emitted by findElementHandler and related resolution logic
+- includes selector, matched element, and confidence (if available)
+
+### 7.2 Execute Stage
+
+- emitted by action handlers (tap, type_text, scroll_to_element, etc.)
+- represents the execution attempt
+
+### 7.3 Verify Stage
+
+- emitted by expect_* handlers
+- reflects state validation results
+
+### 7.4 Stabilize Stage
+
+- emitted by RFC 010 stabilization logic
+- includes stabilization attempts and convergence status
+
+### 7.5 Recover Stage
+
+- emitted by RFC 011 recovery logic
+- includes strategy used and retry attempts
+
+### 7.6 Step Emission Timing
+
+Each stage MUST emit a TraceStep at the point where its outcome is determined:
+
+- resolve: after target selection is finalized
+- execute: after action handler completes (success or failure)
+- verify: after verification result is computed
+- stabilize: after stabilization loop completes (success or failure)
+- recover: after a recovery attempt is decided and executed
+
+Each retry or re-attempt MUST emit a separate step.
+
+---
+
+## 8. Deterministic Behavior
+
+Trace emission MUST NOT:
+
+- alter execution flow
+- introduce timing side effects
+- affect success/failure outcomes
+
+It is strictly observational.
+
+---
+
+## 9. Minimal Metadata Contract
+
+Implementations SHOULD include where available:
+
+- selector or target identifier
+- snapshot identifiers
+- stabilization attempt counts
+- recovery strategy name
+
+Metadata MUST remain lightweight.
+
+---
+
+## 10. Integration with Existing RFCs
+
+- RFC 006: execution emits execute stage
+- RFC 007: resolution emits resolve stage
+- RFC 010: stabilization emits stabilize stage
+- RFC 011: recovery emits recover stage
+
+This RFC unifies these into a single trace model.
+
+---
+
+## 11. Output Behavior
+
+Trace MAY be returned as part of action results or stored internally.
+
+Example:
+
+```ts
+interface ActionExecutionResult {
+  success: boolean;
+  failure_code?: string;
+  trace?: ActionTrace;
+}
+```
+
+---
+
+## 12. Failure Analysis
+
+Trace data MUST allow identification of:
+
+- resolution failures
+- execution failures
+- verification mismatches
+- stabilization convergence issues
+- recovery attempts and outcomes
+
+---
+
+## 13. Success Metrics
+
+- improved debuggability of failures
+- reduced need for manual log inspection
+- clearer differentiation between failure types
+
+---
+
+## 14. Summary
+
+This RFC introduces a structured trace model that makes action execution transparent and debuggable. It builds on existing RFCs without changing behavior, enabling better diagnostics and future analytics capabilities.

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

@@ -80,6 +80,17 @@ MUST be returned in this structure:
   ui_fingerprint_after: string | null,
   failure_code?: string,
   retryable?: boolean,
+  recovery?: {
+    failure_class: string,
+    runtime_code: string,
+    recovery_strategy?: string,
+    recovery_attempts: number,
+    max_recovery_attempts: number,
+    retry_depth: number,
+    max_retry_depth: number,
+    is_terminal: boolean,
+    retry_allowed?: boolean
+  },
   device?: DeviceInfo,
   details?: object
 }
@@ -93,6 +104,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
+- `recovery` MAY be attached to failed actions to carry typed recovery metadata
 
 ### 4.4 Allowed Deviations
 

package/docs/tools/interact.md

@@ -395,6 +395,16 @@ Failure response:
   "success": false,
   "failure_code": "STALE_REFERENCE",
   "retryable": true,
+  "recovery": {
+    "failure_class": "TargetResolutionFailure",
+    "runtime_code": "STALE_REFERENCE",
+    "recovery_attempts": 0,
+    "max_recovery_attempts": 3,
+    "retry_depth": 0,
+    "max_retry_depth": 3,
+    "is_terminal": false,
+    "retry_allowed": true
+  },
   "ui_fingerprint_before": "fp_before",
   "ui_fingerprint_after": "fp_before"
 }

package/package.json

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