mobile-debug-mcp 0.26.4 → 0.27.0

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

@@ -0,0 +1,253 @@
+# RFC 011.1 — Recovery Contract Types & Runtime Wiring Spec
+
+## 1. Purpose
+
+This document defines the typed runtime contract required to implement RFC 011 safely and consistently across:
+
+- src/server
+- src/interact
+- shared action/result boundaries
+
+It removes ambiguity from RFC 011 by formalising:
+- enums
+- state schemas
+- execution payloads
+- failure propagation format
+
+---
+
+## 2. Design Principle
+
+Recovery is not a behaviour description.
+
+It is a typed state machine over execution results.
+
+All recovery decisions MUST be derivable from structured runtime data.
+
+---
+
+## 3. Core Runtime Types
+
+### 3.1 Failure Class
+
+```ts
+type FailureClass =
+  | "TargetResolutionFailure"
+  | "ExecutionFailure"
+  | "VerificationFailure"
+  | "ControlConvergenceFailure"
+  | "SemanticMismatchFailure";
+```
+
+---
+
+### 3.2 Recovery Strategy
+
+```ts
+type RecoveryStrategy =
+  | "re_resolve"
+  | "alternate_candidate"
+  | "state_refresh"
+  | "retry_adjustment"
+  | "step_back";
+```
+
+---
+
+### 3.3 Runtime Failure Code
+
+```ts
+type RuntimeFailureCode =
+  | "ELEMENT_NOT_FOUND"
+  | "STALE_REFERENCE"
+  | "AMBIGUOUS_TARGET"
+  | "TIMEOUT"
+  | "ACTION_REJECTED"
+  | "VERIFICATION_FAILED"
+  | "EXPECT_STATE_MISMATCH"
+  | "CONTROL_CONVERGENCE_FAILED"
+  | "SEMANTIC_MISMATCH"
+  | "UNKNOWN";
+```
+
+---
+
+### 3.4 Recovery State
+
+```ts
+interface RecoveryState {
+  failure_class: FailureClass;
+  runtime_code: RuntimeFailureCode;
+
+  recovery_strategy?: RecoveryStrategy;
+
+  recovery_attempts: number;
+  max_recovery_attempts: number;
+
+  retry_depth: number;
+  max_retry_depth: number;
+
+  is_terminal: boolean;
+
+  // derived from runtime retryable signal
+  retry_allowed?: boolean;
+}
+```
+
+---
+
+## 4. Execution Result Integration (ActionExecutionResult)
+
+This RFC does NOT introduce a new execution result type. Instead, it extends the existing runtime ActionExecutionResult / tool response envelope.
+
+The recovery contract MUST be attached as an extension field.
+
+```ts
+type ActionExecutionResult = {
+  success: boolean;
+
+  action_type: string;
+  target_id?: string;
+
+  // existing runtime error representation (already present in system)
+  failure_code?: RuntimeFailureCode;
+
+  // existing runtime retry signal
+  retryable?: boolean;
+
+  // RFC 011.1 extension
+  recovery?: RecoveryState;
+};
+```
+
+The recovery extension MUST NOT replace or duplicate existing failure_code semantics. Instead, failure_code remains the source input for deriving FailureClass and RecoveryState. RecoveryState is a structured interpretation layer built on top of existing execution results.
+
+Existing retryable semantics remain authoritative for whether an action may be directly retried.
+
+- retryable answers whether an execution may be retried.
+- RecoveryState defines how recovery proceeds when failure occurs.
+
+RecoveryState augments retryability; it does not replace it.
+
+---
+
+## 5. Server → Interact Contract
+
+### 5.1 Server responsibilities
+- map raw runtime errors → RuntimeFailureCode
+- attach initial FailureClass
+- initialise recovery state defaults
+
+### 5.2 Interact responsibilities
+- consume RecoveryState
+- mutate recovery_attempts and retry_depth
+- select RecoveryStrategy
+- enforce bounds
+
+Interact is the only layer allowed to mutate recovery state.
+
+---
+
+## 6. Deterministic Mapping Function
+
+```ts
+function mapRuntimeCodeToFailureClass(code: RuntimeFailureCode): FailureClass {
+  switch (code) {
+    case "ELEMENT_NOT_FOUND":
+    case "STALE_REFERENCE":
+    case "AMBIGUOUS_TARGET":
+      return "TargetResolutionFailure";
+
+    case "TIMEOUT":
+    case "ACTION_REJECTED":
+    case "UNKNOWN":
+      return "ExecutionFailure";
+
+    case "VERIFICATION_FAILED":
+    case "EXPECT_STATE_MISMATCH":
+      return "VerificationFailure";
+
+    case "CONTROL_CONVERGENCE_FAILED":
+      return "ControlConvergenceFailure";
+
+    case "SEMANTIC_MISMATCH":
+      return "SemanticMismatchFailure";
+  }
+}
+```
+
+---
+
+## 7. Step-back Semantics
+
+Step-back MUST be implemented as re-entry into resolution + execution pipeline, NOT state rollback.
+
+---
+
+## 8. Budget Enforcement Rules
+
+```ts
+const RECOVERY_LIMITS = {
+  max_recovery_attempts: 3,
+  max_retry_depth: 3
+};
+```
+
+- MUST increment recovery_attempts per recovery cycle
+- MUST increment retry_depth per re-resolution loop
+- MUST terminate when limits exceeded
+
+### Retryability Gating Rules
+
+Recovery strategies MUST honor existing retryable semantics.
+
+If retryable=false:
+- direct identical-action retry MUST NOT be selected
+- retry_adjustment MUST NOT be selected
+- re_resolve or alternate_candidate SHOULD be preferred
+
+If retryable=true:
+- retry_adjustment MAY be selected subject to recovery budgets
+
+This prevents contradiction between runtime execution constraints and recovery policy.
+
+---
+
+## 9. Failure Output Contract
+
+```ts
+interface TerminalFailure {
+  failure_class: FailureClass;
+  runtime_code: RuntimeFailureCode;
+
+  resolved_target?: string;
+
+  recovery_attempts: number;
+
+  attempted_recovery_strategies: RecoveryStrategy[];
+
+  final_state: "failed";
+}
+```
+
+---
+
+## 10. Integration Summary
+
+This spec defines the typed contract required for implementing RFC 011 across server and interact layers.
+
+### 10.1 Runtime Wiring Constraint
+
+This specification MUST be implemented by extending existing ActionExecutionResult objects in both src/server and src/interact.
+
+No new parallel execution envelope is permitted.
+
+RecoveryState is an additive field only.
+
+Failure interpretation MUST continue to use existing failure_code fields as the source of truth.
+
+---
+
+## 11. Summary
+
+This document formalises recovery as a deterministic, typed execution subsystem.

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
 
@@ -244,6 +256,7 @@ Raw layer contents include:
 - UI hierarchy or accessibility tree
 - normalized readable element state where exposed by the platform
 - platform-native identity hints such as stable identifiers, roles, and test tags
+- semantic control metadata when derivable from the raw tree, including `semantic_role`, `supported_actions`, `adjustable`, and `state_shape`
 - snapshot metadata such as `snapshot_revision` and `captured_at_ms`
 - `loading_state` when a reliable loading signal is detectable
 - screenshot when available
@@ -292,6 +305,27 @@ Semantic output MUST NOT replace classification or verification.
 
 Classification remains a supplementary, post-action interpretation mechanism.
 
+### 9.4 Semantic Control Metadata
+
+When present, semantic control metadata MAY include:
+
+```ts
+{
+  semantic_role?: 'slider' | 'stepper' | 'dropdown' | 'segmented_control' | 'custom_adjustable' | 'composite_control' | null,
+  supported_actions?: string[] | null,
+  adjustable?: boolean | null,
+  state_shape?: 'continuous' | 'discrete' | 'semantic' | null
+}
+```
+
+Rules:
+
+- semantic control metadata is derived and best-effort
+- raw platform roles and state remain authoritative on conflict
+- `adjustable` MAY be inferred from platform traits when no known role matches
+- `state_shape` MUST respect known control roles before value-based heuristics
+- `supported_actions` are hints only and MUST NOT be treated as guaranteed executable actions
+
 ## 10. Classification
 
 Tool: `classify_action_outcome`

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.4",
+  "version": "0.27.0",
   "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {