mobile-debug-mcp 0.34.0 → 0.36.0

package/src/observe/system-trace.ts

@@ -1,3 +1,4 @@
+import { SystemTraceRouter } from './system-trace-router.js'
 import { randomUUID } from 'node:crypto'
 import { promises as fs } from 'node:fs'
 import os from 'node:os'
@@ -6,9 +7,8 @@ import { AndroidTraceNative, TRACE_MAX_BYTES, type TraceCapabilities, type Trace
 import { evidenceSessionId } from './evidence.js'
 import { runWithBudget, remainingBudget } from '../utils/operation-budget.js'
 
-export class TraceError extends Error {
-  constructor(public code: string) { super(code) }
-}
+export { TraceError } from './system-trace-error.js'
+import { TraceError } from './system-trace-error.js'
 type State = 'starting' | 'recording' | 'stopping' | 'completed' | 'cancelled' | 'failed'
 type Completion = 'requested' | 'duration_limit' | 'cancelled' | 'error'
 export interface TraceResult {
@@ -37,7 +37,7 @@ const clock: TraceClock = {
 export class SystemTraceSessions {
   private sessions = new Map<string, Session>()
   private closing = false
-  constructor(private native: TraceNative = new AndroidTraceNative(), private time: TraceClock = clock) {}
+  constructor(private native: TraceNative = new AndroidTraceNative(), private time: TraceClock = clock) { }
   private prune() {
     const terminal = [...this.sessions.values()].filter(s => s.terminalAt !== undefined && s.result.cleanup.status === 'complete')
     for (const s of terminal) if (this.time.mono() - s.terminalAt! >= 600000) this.sessions.delete(s.result.trace_id)
@@ -49,7 +49,7 @@ export class SystemTraceSessions {
   private snapshot(s: Session): TraceResult { return structuredClone(s.result) }
   private serial<T>(s: Session, fn: () => Promise<T>): Promise<T> {
     const result = s.queue.then(fn)
-    s.queue = result.catch(() => {})
+    s.queue = result.catch(() => { })
     return result
   }
   async capabilities(device: string) { return this.native.capabilities(device) }
@@ -59,11 +59,15 @@ export class SystemTraceSessions {
     const reserved = [...this.sessions.values()].filter(s => s.result.cleanup.status !== 'complete')
     if (this.closing || reserved.length >= 4 || reserved.some(s => s.result.device.id === device)) throw new TraceError('TRACE_BUSY')
     const id = randomUUID()
-    const result: TraceResult = { trace_id: id, session_id: evidenceSessionId(), device: { platform: 'android', id: device }, backend: 'perfetto',
+    const result: TraceResult = {
+      trace_id: id, session_id: evidenceSessionId(), device: { platform: 'android', id: device }, backend: 'perfetto',
       state: 'starting', reason: null, completion_reason: null, capture_started_at_ms: null, capture_completed_at_ms: null,
-      artifact: null, cleanup: { status: 'pending', remaining_resources: [] }, correlation_ids: [], enabled_sources: [], unavailable_categories: [] }
-    const s: Session = { result, remote: `/data/misc/perfetto-traces/mcp-${id}.perfetto-trace`, owner: null, stopped: true,
-      discard: false, deadline: Infinity, queue: Promise.resolve(), linked: new Set(), partial: new Set() }
+      artifact: null, cleanup: { status: 'pending', remaining_resources: [] }, correlation_ids: [], enabled_sources: [], unavailable_categories: []
+    }
+    const s: Session = {
+      result, remote: `/data/misc/perfetto-traces/mcp-${id}.perfetto-trace`, owner: null, stopped: true,
+      discard: false, deadline: Infinity, queue: Promise.resolve(), linked: new Set(), partial: new Set()
+    }
     this.sessions.set(id, s)
     return this.serial(s, async () => {
       let cap: TraceCapabilities
@@ -81,7 +85,7 @@ export class SystemTraceSessions {
         await this.native.start(device, s.remote, duration, cap.enabled_sources)
         s.owner = await this.native.find(device, s.remote)
         s.result.state = 'recording'
-        s.timer = this.time.schedule(() => { void this.control(id, 'duration').catch(() => {}) }, Math.max(0, s.deadline - this.time.mono()))
+        s.timer = this.time.schedule(() => { void this.control(id, 'duration').catch(() => { }) }, Math.max(0, s.deadline - this.time.mono()))
       } catch (error) {
         s.discard = true
         this.fail(s, this.code(error, 'TRACE_START_FAILED'))
@@ -173,15 +177,18 @@ export class SystemTraceSessions {
       }
       try { await this.remove(s) }
       catch { this.fail(s, 'TRACE_STOP_FAILED'); s.result.cleanup.status = 'failed'; return this.snapshot(s) }
-      if (hadStartFailure) s.result.state = 'failed'
-      else {
-        s.result.state = s.discard ? 'cancelled' : 'completed'
-        s.result.reason = s.discard ? 'TRACE_CANCELLED' : null
-        s.result.completion_reason = s.discard ? 'cancelled' : operation === 'duration' || this.time.mono() >= s.deadline ? 'duration_limit' : 'requested'
-      }
+      this.complete(s, hadStartFailure, operation)
       return this.snapshot(s)
     })
   }
+  private complete(s: Session, hadStartFailure: boolean, operation: string) {
+    if (hadStartFailure) s.result.state = 'failed'
+    else {
+      s.result.state = s.discard ? 'cancelled' : 'completed'
+      s.result.reason = s.discard ? 'TRACE_CANCELLED' : null
+      s.result.completion_reason = s.discard ? 'cancelled' : operation === 'duration' || this.time.mono() >= s.deadline ? 'duration_limit' : 'requested'
+    }
+  }
   async link(id: string, device: { platform: string; id: string }, correlation: string) {
     const s = this.get(id)
     if (device.platform !== 'android' || device.id !== s.result.device.id) throw new TraceError('TRACE_NOT_FOUND')
@@ -201,8 +208,10 @@ export class SystemTraceSessions {
         try { recording = (await this.control(id, 'status')).state === 'recording' }
         catch { /* Unavailable state cannot establish complete coverage. */ }
         s.linked.delete(correlation)
-        return { trace_id: id, coverage: !recording || s.partial.has(correlation) || this.time.mono() >= s.deadline ? 'partial' : 'covered',
-          clock_alignment: 'unknown' }
+        return {
+          trace_id: id, coverage: !recording || s.partial.has(correlation) || this.time.mono() >= s.deadline ? 'partial' : 'covered',
+          clock_alignment: 'unknown'
+        }
       })()
     })
   }
@@ -215,4 +224,4 @@ export class SystemTraceSessions {
     })
   }
 }
-export const systemTraces = new SystemTraceSessions()
+export const systemTraces = new SystemTraceRouter(new SystemTraceSessions())

package/src/runtime/action-results.ts

@@ -0,0 +1,376 @@
+import { currentEvidenceActionId } from '../observe/evidence.js'
+import type {
+  ActionTrace,
+  ActionExecutionResult,
+  ActionFailureCode,
+  ActionTargetResolved,
+  FailureClass,
+  RecoveryState,
+  TraceResult,
+  TraceStage,
+  TraceStep
+} from '../types.js'
+import { ToolsObserve } from '../observe/index.js'
+import { isConditionBlocked } from '../interact/conditional-action.js'
+
+export const DEFAULT_MAX_RECOVERY_ATTEMPTS = 3
+export const DEFAULT_MAX_RETRY_DEPTH = 3
+
+let actionSequence = 0
+
+export function nextActionId(actionType: string, timestamp: number) {
+  const current = currentEvidenceActionId()
+  if (current) return current
+  actionSequence += 1
+  return `${actionType}_${timestamp}_${actionSequence}`
+}
+
+export async function captureActionFingerprint(platform?: 'android' | 'ios', deviceId?: string): Promise<string | null> {
+  if (isConditionBlocked()) return null
+  if (!platform) return null
+  try {
+    const result = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId })
+    return result?.fingerprint ?? null
+  } catch {
+    return null
+  }
+}
+
+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 } : {})
+    }
+  }))
+
+  appendObservationAndRecoverySteps({ builtSteps, attemptIndex, details, success, failure, recovery })
+
+  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 {
+    elementId: value.elementId ?? null,
+    text: value.text ?? null,
+    resource_id: value.resource_id ?? null,
+    accessibility_id: value.accessibility_id ?? null,
+    class: value.class ?? null,
+    bounds: value.bounds ?? null,
+    index: value.index ?? null,
+    state: value.state ?? null
+  }
+}
+
+export function inferGenericFailure(message: string | undefined): { failureCode: ActionFailureCode; retryable: boolean } {
+  if (message && /timeout/i.test(message)) return { failureCode: 'TIMEOUT', retryable: true }
+  if (message && /semantic mismatch/i.test(message)) return { failureCode: 'SEMANTIC_MISMATCH', retryable: false }
+  return { failureCode: 'UNKNOWN', retryable: false }
+}
+
+export function inferScrollFailure(message: string | undefined): { failureCode: ActionFailureCode; retryable: boolean } {
+  if (message && /unchanged|no change|end of list/i.test(message)) return { failureCode: 'NAVIGATION_NO_CHANGE', retryable: true }
+  if (message && /timeout/i.test(message)) return { failureCode: 'TIMEOUT', retryable: true }
+  return { failureCode: 'UNKNOWN', retryable: false }
+}
+
+const ACTION_LIFECYCLE_STATE_BY_OUTCOME = {
+  success: 'pending_verification',
+  failure: 'failed'
+} as const
+
+export function determineActionLifecycleState({
+  success,
+  failure
+}: {
+  success: boolean
+  failure?: { failureCode: ActionFailureCode; retryable: boolean }
+}): NonNullable<ActionExecutionResult['lifecycle_state']> {
+  if (failure) return ACTION_LIFECYCLE_STATE_BY_OUTCOME.failure
+  if (success) return ACTION_LIFECYCLE_STATE_BY_OUTCOME.success
+  return ACTION_LIFECYCLE_STATE_BY_OUTCOME.success
+}
+
+function mapFailureCodeToFailureClass(code: ActionFailureCode): FailureClass {
+  switch (code) {
+    case 'ELEMENT_NOT_FOUND':
+    case 'AMBIGUOUS_TARGET':
+    case 'STALE_REFERENCE':
+      return 'TargetResolutionFailure'
+    case 'ELEMENT_NOT_INTERACTABLE':
+    case 'PRECONDITION_FAILED':
+    case 'PRECONDITION_UNAVAILABLE':
+    case 'ACTION_TIMEOUT':
+      return 'ExecutionFailure'
+    case 'TIMEOUT':
+    case 'ACTION_REJECTED':
+    case 'NAVIGATION_NO_CHANGE':
+    case 'UNKNOWN':
+      return 'ExecutionFailure'
+    case 'VERIFICATION_FAILED':
+    case 'EXPECT_STATE_MISMATCH':
+    case 'ASSERTION_TIMEOUT':
+      return 'VerificationFailure'
+    case 'CONTROL_CONVERGENCE_FAILED':
+      return 'ControlConvergenceFailure'
+    case 'SEMANTIC_MISMATCH':
+      return 'SemanticMismatchFailure'
+  }
+}
+
+function buildRecoveryState(failureCode: ActionFailureCode, retryable: boolean): RecoveryState {
+  return {
+    failure_class: mapFailureCodeToFailureClass(failureCode),
+    runtime_code: failureCode,
+    recovery_attempts: 0,
+    max_recovery_attempts: DEFAULT_MAX_RECOVERY_ATTEMPTS,
+    retry_depth: 0,
+    max_retry_depth: DEFAULT_MAX_RETRY_DEPTH,
+    is_terminal: false,
+    retry_allowed: retryable
+  }
+}
+
+export function buildActionExecutionResult({
+  actionType,
+  device,
+  selector,
+  resolved,
+  success,
+  uiFingerprintBefore,
+  uiFingerprintAfter,
+  failure,
+  details,
+  sourceModule,
+  traceSteps
+}: {
+  actionType: string
+  device?: ActionExecutionResult['device']
+  selector: Record<string, unknown> | null
+  resolved?: Partial<ActionTargetResolved> | null
+  success: boolean
+  uiFingerprintBefore: string | null
+  uiFingerprintAfter: string | null
+  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: actionId,
+    timestamp,
+    action_type: actionType,
+    lifecycle_state: determineActionLifecycleState({ success, failure }),
+    source_module: sourceModule,
+    ...(device ? { device } : {}),
+    target: {
+      selector,
+      resolved: normalizeResolvedTarget(resolved)
+    },
+    success,
+    ...(failure ? { failure_code: failure.failureCode, retryable: 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 } : {})
+  }
+}
+
+
+interface TraceStageContext {
+  builtSteps: TraceStep[]
+  attemptIndex: number
+  details?: Record<string, unknown>
+  success: boolean
+  failure?: { failureCode: ActionFailureCode; retryable: boolean }
+  recovery?: RecoveryState
+}
+function appendObservationAndRecoverySteps(context: TraceStageContext) {
+  const attemptIndex = appendStabilizationStep(context)
+  const nextIndex = appendVerificationStep({ ...context, attemptIndex })
+  appendRecoveryStep({ ...context, attemptIndex: nextIndex })
+}
+function appendStabilizationStep({ builtSteps, attemptIndex, details, success }: TraceStageContext) {
+  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')
+  ))
+  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
+      }
+    }))
+  }
+
+  return attemptIndex
+}
+function appendVerificationStep({ builtSteps, attemptIndex, details, success }: TraceStageContext) {
+  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 (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
+      }
+    }))
+  }
+
+  return attemptIndex
+}
+function appendRecoveryStep({ builtSteps, attemptIndex, failure, recovery }: TraceStageContext) {
+  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
+      }
+    }))
+  }
+
+}

package/src/runtime/clock.ts

@@ -0,0 +1,9 @@
+/** Wall-clock timestamps and delays used by interaction polling services. */
+export interface Clock {
+  now(): number
+  sleep(ms: number): Promise<void>
+}
+export const systemClock: Clock = {
+  now: () => Date.now(),
+  sleep: ms => new Promise(resolve => setTimeout(resolve, ms))
+}