mobile-debug-mcp 0.27.0 → 0.28.0

package/src/server/common.ts

@@ -1,9 +1,13 @@
 import type {
+  ActionTrace,
   ActionExecutionResult,
   ActionFailureCode,
   ActionTargetResolved,
   FailureClass,
-  RecoveryState
+  RecoveryState,
+  TraceResult,
+  TraceStage,
+  TraceStep
 } from '../types.js'
 import { ToolsObserve } from '../observe/index.js'
 
@@ -92,6 +96,172 @@ export async function captureActionFingerprint(platform?: 'android' | 'ios', dev
   }
 }
 
+export function createTraceStep({
+  stage,
+  timestamp,
+  result,
+  attemptIndex,
+  cycleId,
+  metadata
+}: {
+  stage: TraceStage
+  timestamp: number
+  result: TraceResult
+  attemptIndex: number
+  cycleId?: number
+  metadata?: Record<string, unknown>
+}): TraceStep {
+  return {
+    stage,
+    timestamp,
+    result,
+    attempt_index: attemptIndex,
+    ...(cycleId !== undefined ? { cycle_id: cycleId } : {}),
+    ...(metadata ? { metadata } : {})
+  }
+}
+
+export function buildActionTrace({
+  actionId,
+  actionType,
+  sourceModule,
+  selector,
+  resolved,
+  success,
+  failure,
+  details,
+  recovery,
+  attempts = 1,
+  steps
+}: {
+  actionId: string
+  actionType: string
+  sourceModule: 'server' | 'interact'
+  selector: Record<string, unknown> | null
+  resolved?: Partial<ActionTargetResolved> | null
+  success: boolean
+  failure?: { failureCode: ActionFailureCode; retryable: boolean }
+  details?: Record<string, unknown>
+  recovery?: RecoveryState
+  attempts?: number
+  steps?: TraceStep[]
+}): ActionTrace {
+  if (steps && steps.length > 0) {
+    return {
+      action_id: actionId,
+      steps,
+      final_outcome: success ? 'success' : 'failure',
+      attempts: Math.max(1, Math.floor(attempts || steps.length))
+    }
+  }
+
+  const start = Date.now()
+  const builtSteps: TraceStep[] = []
+  let attemptIndex = 0
+  const totalAttempts = Math.max(1, Math.floor(attempts || 1))
+
+  if (selector || resolved) {
+    const stageResult: TraceResult = resolved ? 'success' : 'failure'
+    builtSteps.push(createTraceStep({
+      stage: 'resolve',
+      timestamp: start,
+      result: stageResult,
+      attemptIndex: attemptIndex++,
+      metadata: {
+        action_type: actionType,
+        source_module: sourceModule,
+        selector: selector ?? null,
+        resolved: resolved ? normalizeResolvedTarget(resolved) : null
+      }
+    }))
+  }
+
+  builtSteps.push(createTraceStep({
+    stage: 'execute',
+    timestamp: Date.now(),
+    result: success ? 'success' : 'failure',
+    attemptIndex: attemptIndex++,
+    metadata: {
+      action_type: actionType,
+      source_module: sourceModule,
+      ...(failure ? { failure_code: failure.failureCode, retryable: failure.retryable } : {})
+    }
+  }))
+
+  const hasStabilizeDetails = Boolean(details && (
+    Object.prototype.hasOwnProperty.call(details, 'stabilization_attempts') ||
+    Object.prototype.hasOwnProperty.call(details, 'stable_observation_count') ||
+    Object.prototype.hasOwnProperty.call(details, 'snapshot_freshness_ms')
+  ))
+  const hasVerifyDetails = Boolean(details && (
+    Object.prototype.hasOwnProperty.call(details, 'within_tolerance') ||
+    Object.prototype.hasOwnProperty.call(details, 'converged') ||
+    Object.prototype.hasOwnProperty.call(details, 'observed_state')
+  ))
+
+  if (hasStabilizeDetails) {
+    builtSteps.push(createTraceStep({
+      stage: 'stabilize',
+      timestamp: Date.now(),
+      result: success ? 'success' : 'failure',
+      attemptIndex: attemptIndex++,
+      metadata: {
+        stabilization_attempts: (details?.stabilization_attempts as number | undefined) ?? null,
+        stable_observation_count: (details?.stable_observation_count as number | undefined) ?? null,
+        snapshot_freshness_ms: (details?.snapshot_freshness_ms as number | undefined) ?? null
+      }
+    }))
+  }
+
+  if (hasVerifyDetails) {
+    builtSteps.push(createTraceStep({
+      stage: 'verify',
+      timestamp: Date.now(),
+      result: success ? 'success' : 'failure',
+      attemptIndex: attemptIndex++,
+      metadata: {
+        within_tolerance: details?.within_tolerance ?? null,
+        converged: details?.converged ?? null,
+        actual_state: details?.actual_state ?? null,
+        reason: details?.reason ?? null
+      }
+    }))
+  }
+
+  if (failure) {
+    builtSteps.push(createTraceStep({
+      stage: 'recover',
+      timestamp: Date.now(),
+      result: failure.retryable ? 'retry' : 'failure',
+      attemptIndex: attemptIndex++,
+      metadata: {
+        failure_class: recovery?.failure_class ?? mapFailureCodeToFailureClass(failure.failureCode),
+        runtime_code: failure.failureCode,
+        retry_allowed: failure.retryable,
+        recovery_attempts: recovery?.recovery_attempts ?? 0,
+        retry_depth: recovery?.retry_depth ?? 0
+      }
+    }))
+  }
+
+  if (!builtSteps.length) {
+    builtSteps.push(createTraceStep({
+      stage: 'execute',
+      timestamp: start,
+      result: success ? 'success' : 'failure',
+      attemptIndex: 0,
+      metadata: { action_type: actionType, source_module: sourceModule }
+    }))
+  }
+
+  return {
+    action_id: actionId,
+    steps: builtSteps,
+    final_outcome: success ? 'success' : 'failure',
+    attempts: totalAttempts
+  }
+}
+
 export function normalizeResolvedTarget(value: Partial<ActionTargetResolved> | null = null): ActionTargetResolved | null {
   if (!value) return null
   return {
@@ -181,7 +351,8 @@ export function buildActionExecutionResult({
   uiFingerprintAfter,
   failure,
   details,
-  sourceModule
+  sourceModule,
+  traceSteps
 }: {
   actionType: string
   device?: ActionExecutionResult['device']
@@ -193,11 +364,17 @@ export function buildActionExecutionResult({
   failure?: { failureCode: ActionFailureCode; retryable: boolean }
   details?: Record<string, unknown>
   sourceModule: 'server' | 'interact'
+  traceSteps?: TraceStep[]
 }): ActionExecutionResult {
   const timestampMs = Date.now()
   const timestamp = new Date(timestampMs).toISOString()
+  const actionId = nextActionId(actionType, timestampMs)
+  const recoveryState = failure ? buildRecoveryState(failure.failureCode, failure.retryable) : undefined
+  const attempts = typeof details?.attempts === 'number' && Number.isFinite(details.attempts)
+    ? Math.max(1, Math.floor(details.attempts))
+    : 1
   return {
-    action_id: nextActionId(actionType, timestampMs),
+    action_id: actionId,
     timestamp,
     action_type: actionType,
     lifecycle_state: determineActionLifecycleState({ success, failure }),
@@ -209,7 +386,20 @@ export function buildActionExecutionResult({
     },
     success,
     ...(failure ? { failure_code: failure.failureCode, retryable: failure.retryable } : {}),
-    ...(failure ? { recovery: buildRecoveryState(failure.failureCode, failure.retryable) } : {}),
+    ...(recoveryState ? { recovery: recoveryState } : {}),
+    trace: buildActionTrace({
+      actionId,
+      actionType,
+      sourceModule,
+      selector,
+      resolved,
+      success,
+      failure,
+      details,
+      recovery: recoveryState,
+      attempts,
+      steps: traceSteps
+    }),
     ui_fingerprint_before: uiFingerprintBefore,
     ui_fingerprint_after: uiFingerprintAfter,
     ...(details ? { details } : {})

package/src/server-core.ts

@@ -13,7 +13,7 @@ export { wrapResponse, toolDefinitions, handleToolCall }
 
 export const serverInfo = {
   name: 'mobile-debug-mcp',
-  version: '0.27.0'
+  version: '0.28.0'
 }
 
 export function createServer() {

package/src/types.ts

@@ -113,6 +113,25 @@ export interface UIElementSemanticMetadata {
   state_shape?: 'continuous' | 'discrete' | 'semantic' | null;
 }
 
+export type TraceStage = 'resolve' | 'execute' | 'verify' | 'stabilize' | 'recover';
+export type TraceResult = 'success' | 'failure' | 'retry';
+
+export interface TraceStep {
+  stage: TraceStage;
+  timestamp: number;
+  result: TraceResult;
+  attempt_index: number;
+  cycle_id?: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface ActionTrace {
+  action_id: string;
+  steps: TraceStep[];
+  final_outcome: 'success' | 'failure';
+  attempts: number;
+}
+
 export type FailureClass =
   | 'TargetResolutionFailure'
   | 'ExecutionFailure'
@@ -377,6 +396,7 @@ export interface ActionExecutionResult {
   failure_code?: ActionFailureCode;
   retryable?: boolean;
   recovery?: RecoveryState;
+  trace: ActionTrace;
   ui_fingerprint_before?: string | null;
   ui_fingerprint_after?: string | null;
   details?: Record<string, unknown>;
@@ -400,6 +420,7 @@ export interface ExpectScreenResponse {
     matched: boolean;
     reason: string;
   };
+  trace: ActionTrace;
 }
 
 export interface ExpectElementVisibleResponse {
@@ -423,6 +444,7 @@ export interface ExpectElementVisibleResponse {
   reason?: string;
   failure_code?: 'TIMEOUT' | 'ELEMENT_NOT_FOUND' | 'UNKNOWN';
   retryable?: boolean;
+  trace: ActionTrace;
 }
 
 export interface ExpectStateResponse {
@@ -451,6 +473,7 @@ export interface ExpectStateResponse {
   stabilization_window_ms?: number;
   stable_observation_count?: number;
   snapshot_freshness_ms?: number;
+  trace: ActionTrace;
 }
 
 export interface AdjustControlResponse extends ActionExecutionResult {

package/test/device/manual/observe/rfc012_trace.manual.ts

@@ -0,0 +1,51 @@
+import assert from 'assert'
+import { ToolsInteract } from '../../../../src/interact/index.js'
+import { ToolsObserve } from '../../../../src/observe/index.js'
+
+async function verifyTrace(platform: 'android' | 'ios', deviceId?: string) {
+  const fingerprint = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }) as any
+  assert.ok(fingerprint, `${platform}: missing fingerprint response`)
+  assert.ok(fingerprint.fingerprint || fingerprint.activity, `${platform}: missing fingerprint or activity`)
+
+  const expected = fingerprint.fingerprint
+    ? { fingerprint: fingerprint.fingerprint }
+    : { screen: fingerprint.activity }
+
+  const response = await ToolsInteract.expectScreenHandler({
+    platform,
+    deviceId,
+    ...expected
+  })
+
+  assert.strictEqual(response.success, true, `${platform}: expect_screen did not succeed`)
+  assert.ok(response.trace, `${platform}: trace missing`)
+  assert.strictEqual(response.trace.final_outcome, 'success', `${platform}: trace outcome mismatch`)
+  assert.ok(Array.isArray(response.trace.steps) && response.trace.steps.length > 0, `${platform}: trace steps missing`)
+  assert.strictEqual(response.trace.steps[0].stage, 'verify', `${platform}: expected verify stage`)
+
+  console.log(`${platform}: RFC 012 trace verified`)
+}
+
+async function main() {
+  const args = process.argv.slice(2)
+  const platform = args[0] as 'android' | 'ios' | undefined
+  const deviceId = args[1]
+
+  if (platform === 'android') {
+    await verifyTrace('android', deviceId)
+    return
+  }
+
+  if (platform === 'ios') {
+    await verifyTrace('ios', deviceId)
+    return
+  }
+
+  await verifyTrace('android')
+  await verifyTrace('ios')
+}
+
+main().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

package/test/unit/interact/expect_tools.test.ts

@@ -6,22 +6,23 @@ async function run() {
   console.log('Starting expect_* unit tests...')
   const originalGetScreenFingerprintHandler = (Observe as any).ToolsObserve.getScreenFingerprintHandler
   const originalGetCurrentScreenHandler = (Observe as any).ToolsObserve.getCurrentScreenHandler
+  const originalGetUITreeHandler = (Observe as any).ToolsObserve.getUITreeHandler
   const originalWaitForUIHandler = (ToolsInteract as any).waitForUIHandler
 
   try {
     ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = async () => ({ fingerprint: 'fp_home', activity: 'com.example.HomeActivity' })
     let expectScreen = await ToolsInteract.expectScreenHandler({ platform: 'android', fingerprint: 'fp_home' })
-    assert.deepStrictEqual(expectScreen, {
-      success: true,
-      observed_screen: { fingerprint: 'fp_home', screen: 'com.example.HomeActivity' },
-      expected_screen: { fingerprint: 'fp_home', screen: null },
-      confidence: 1,
-      comparison: {
-        basis: 'fingerprint',
-        matched: true,
-        reason: 'observed fingerprint matches expected fingerprint fp_home'
-      }
+    assert.strictEqual(expectScreen.success, true)
+    assert.deepStrictEqual(expectScreen.observed_screen, { fingerprint: 'fp_home', screen: 'com.example.HomeActivity' })
+    assert.deepStrictEqual(expectScreen.expected_screen, { fingerprint: 'fp_home', screen: null })
+    assert.strictEqual(expectScreen.confidence, 1)
+    assert.deepStrictEqual(expectScreen.comparison, {
+      basis: 'fingerprint',
+      matched: true,
+      reason: 'observed fingerprint matches expected fingerprint fp_home'
     })
+    assert.strictEqual(expectScreen.trace.final_outcome, 'success')
+    assert.strictEqual(expectScreen.trace.steps[0].stage, 'verify')
 
     ;(Observe as any).ToolsObserve.getCurrentScreenHandler = async () => ({
       activity: 'com.example.HomeActivity',
@@ -58,6 +59,8 @@ async function run() {
     assert.strictEqual(expectElementVisible.element?.resource_id, 'rid_ready')
     assert.strictEqual(expectElementVisible.expected_condition, 'visible')
     assert.strictEqual(expectElementVisible.reason, 'selector is visible')
+    assert.strictEqual(expectElementVisible.trace.final_outcome, 'success')
+    assert.strictEqual(expectElementVisible.trace.steps[0].stage, 'verify')
 
     ;(ToolsInteract as any).waitForUIHandler = async () => ({
       status: 'timeout',
@@ -73,27 +76,56 @@ async function run() {
       selector: { text: 'Missing' },
       platform: 'android'
     })
-    assert.deepStrictEqual(timeoutResult, {
-      success: false,
-      selector: { text: 'Missing' },
-      element_id: null,
-      expected_condition: 'visible',
-      observed: {
-        status: 'timeout',
-        matched_count: 0,
-        condition_satisfied: false,
-        selected_index: null,
-        last_matched_element: null
-      },
-      reason: 'Condition visible not satisfied within timeout; observed 0 match(es)',
-      failure_code: 'TIMEOUT',
-      retryable: true
+    assert.strictEqual(timeoutResult.success, false)
+    assert.deepStrictEqual(timeoutResult.selector, { text: 'Missing' })
+    assert.strictEqual(timeoutResult.element_id, null)
+    assert.strictEqual(timeoutResult.expected_condition, 'visible')
+    assert.deepStrictEqual(timeoutResult.observed, {
+      status: 'timeout',
+      matched_count: 0,
+      condition_satisfied: false,
+      selected_index: null,
+      last_matched_element: null
+    })
+    assert.strictEqual(timeoutResult.reason, 'Condition visible not satisfied within timeout; observed 0 match(es)')
+    assert.strictEqual(timeoutResult.failure_code, 'TIMEOUT')
+    assert.strictEqual(timeoutResult.retryable, true)
+    assert.strictEqual(timeoutResult.trace.final_outcome, 'failure')
+
+    let uiTreeCallCount = 0
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => {
+      uiTreeCallCount++
+      return {
+        device: { platform: 'android', id: 'emulator-5554' },
+        captured_at_ms: Date.now(),
+        elements: [{
+          elementId: 'el_state',
+          text: 'Stateful',
+          resource_id: 'rid_state',
+          accessibility_id: null,
+          class: 'TextView',
+          bounds: [0, 0, 10, 10],
+          index: 0,
+          state: { enabled: true, value: 7 }
+        }]
+      }
+    }
+    const expectState = await ToolsInteract.expectStateHandler({
+      selector: { text: 'Stateful' },
+      property: 'value',
+      expected: 7,
+      platform: 'android'
     })
+    assert.strictEqual(expectState.success, true)
+    assert.strictEqual(uiTreeCallCount >= 2, true)
+    assert.ok(expectState.trace.steps.filter((step) => step.stage === 'stabilize').length >= 2)
+    assert.ok(expectState.trace.steps.filter((step) => step.stage === 'verify').length >= 2)
 
     console.log('expect_* unit tests passed')
   } finally {
     ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = originalGetScreenFingerprintHandler
     ;(Observe as any).ToolsObserve.getCurrentScreenHandler = originalGetCurrentScreenHandler
+    ;(Observe as any).ToolsObserve.getUITreeHandler = originalGetUITreeHandler
     ;(ToolsInteract as any).waitForUIHandler = originalWaitForUIHandler
   }
 }

package/test/unit/server/common.test.ts

@@ -1,4 +1,5 @@
 import assert from 'assert'
+import { createTraceStep } from '../../../src/server/common.js'
 import { buildActionExecutionResult, inferGenericFailure, requireBooleanArg } from '../../../src/server/common.js'
 
 function run() {
@@ -27,6 +28,8 @@ function run() {
   assert.strictEqual(recoveryResult.recovery?.retry_allowed, false)
   assert.strictEqual(recoveryResult.recovery?.max_recovery_attempts, 3)
   assert.strictEqual(recoveryResult.recovery?.max_retry_depth, 3)
+  assert.strictEqual(recoveryResult.trace.final_outcome, 'failure')
+  assert.strictEqual(recoveryResult.trace.steps.at(-1)?.stage, 'recover')
 
   const notInteractableResult = buildActionExecutionResult({
     actionType: 'tap',
@@ -41,6 +44,27 @@ function run() {
   assert.strictEqual(notInteractableResult.recovery?.failure_class, 'ExecutionFailure')
   assert.strictEqual(notInteractableResult.recovery?.runtime_code, 'ELEMENT_NOT_INTERACTABLE')
   assert.strictEqual(notInteractableResult.recovery?.retry_allowed, true)
+  assert.strictEqual(notInteractableResult.trace.steps[0].stage, 'resolve')
+  assert.strictEqual(notInteractableResult.trace.steps[0].result, 'failure')
+  assert.strictEqual(notInteractableResult.trace.steps.at(-1)?.stage, 'recover')
+
+  const traceSteps = [
+    createTraceStep({ stage: 'resolve', timestamp: 100, result: 'success', attemptIndex: 0 }),
+    createTraceStep({ stage: 'execute', timestamp: 200, result: 'retry', attemptIndex: 1 }),
+    createTraceStep({ stage: 'verify', timestamp: 300, result: 'success', attemptIndex: 2 })
+  ]
+  const tracedResult = buildActionExecutionResult({
+    actionType: 'tap',
+    sourceModule: 'server',
+    selector: { x: 1, y: 1 },
+    success: true,
+    uiFingerprintBefore: 'before',
+    uiFingerprintAfter: 'after',
+    details: { attempts: 3 },
+    traceSteps
+  })
+  assert.deepStrictEqual(tracedResult.trace.steps, traceSteps)
+  assert.strictEqual(tracedResult.trace.attempts, 3)
 
   console.log('server common tests passed')
 }