mobile-debug-mcp 0.34.0 → 0.35.0

package/src/contracts/execution-controls.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod'
+
+export const verificationModes = ['none', 'light', 'full'] as const
+export const responseModes = ['compact', 'debug'] as const
+export const verificationModeSchema = z.enum(verificationModes)
+export const responseModeSchema = z.enum(responseModes)
+export type VerificationMode = z.infer<typeof verificationModeSchema>
+export type ResponseMode = z.infer<typeof responseModeSchema>
+
+export const verificationModeJson = { type: 'string', enum: [...verificationModes] }
+export const responseModeJson = { type: 'string', enum: [...responseModes] }
+
+export function interactionControls(args: Record<string, unknown>) {
+  const verificationMode = ((typeof args.verificationMode === 'string' ? args.verificationMode : undefined) as VerificationMode | undefined) ?? 'full'
+  const responseMode = ((typeof args.responseMode === 'string' ? args.responseMode : undefined) as ResponseMode | undefined) ?? 'debug'
+  if (!verificationModes.includes(verificationMode) || !responseModes.includes(responseMode)) throw new Error('INVALID_ARGUMENT')
+  for (const key of ['verificationMode', 'responseMode']) if (args[key] !== undefined && typeof args[key] !== 'string') throw new Error('INVALID_ARGUMENT')
+  for (const key of ['actionTimeoutMs', 'verificationTimeoutMs']) if (args[key] !== undefined && (typeof args[key] !== 'number' || !Number.isInteger(args[key]))) throw new Error('INVALID_ARGUMENT')
+  const actionTimeoutMs = (typeof args.actionTimeoutMs === 'number' && Number.isFinite(args.actionTimeoutMs) ? args.actionTimeoutMs : undefined)
+  const verificationTimeoutMs = (typeof args.verificationTimeoutMs === 'number' && Number.isFinite(args.verificationTimeoutMs) ? args.verificationTimeoutMs : undefined)
+  return { verificationMode, responseMode,
+    actionTimeoutMs: actionTimeoutMs === undefined ? undefined : Math.max(100, Math.min(30000, actionTimeoutMs)),
+    verificationTimeoutMs: verificationTimeoutMs === undefined ? 3000 : Math.max(100, Math.min(60000, verificationTimeoutMs)) }
+
+}
+

package/src/contracts/selector.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod'
+
+export type UiSelector = {
+  text?: string
+  resource_id?: string
+  accessibility_id?: string
+  contains?: boolean
+}
+
+export const selectorSchema = z.object({
+  text: z.string().min(1).optional(), resource_id: z.string().min(1).optional(),
+  accessibility_id: z.string().min(1).optional(), contains: z.boolean().optional()
+}).strict().refine(value => !!(value.text || value.resource_id || value.accessibility_id), 'Selector requires a target')
+
+export const selectorJson = { type: 'object', additionalProperties: false, properties: {
+  text: { type: 'string', minLength: 1 }, resource_id: { type: 'string', minLength: 1 }, accessibility_id: { type: 'string', minLength: 1 }, contains: { type: 'boolean' }
+}, anyOf: ['text', 'resource_id', 'accessibility_id'].map(key => ({ required: [key] })) }

package/src/contracts/target.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod'
+import { selectorSchema as selector, selectorJson } from './selector.js'
+
+export interface DeviceTarget { platform?: 'android' | 'ios'; deviceId?: string }
+export type ScrollSelector = { text?: string; resourceId?: string; contentDesc?: string; className?: string }
+const pollIntervalMs = z.number().int().min(50).max(1000).optional()
+export const waitForSchema = z.object({
+  condition: z.enum(['exists', 'visible', 'clickable']).optional(),
+  timeoutMs: z.number().int().min(100).max(10000).optional(), pollIntervalMs,
+  match: z.object({ index: z.number().int().nonnegative().optional() }).strict().optional()
+}).strict()
+export const targetFields = { selector: selector.optional(), elementId: z.string().min(1).optional() }
+export const exactlyOneTarget = (value: { selector?: unknown, elementId?: string }) => Number(!!value.selector) + Number(!!value.elementId) === 1
+export const tapElementControlsSchema = z.object({
+  elementId: z.string().min(1).optional(), selector: selector.optional(), waitFor: waitForSchema.optional()
+}).strict().refine(value => Number(!!value.elementId) + Number(!!value.selector) === 1 && (!value.elementId || !value.waitFor))
+
+export const targetJson = { selector: selectorJson, elementId: { type: 'string', minLength: 1 } }
+export const oneTargetJson = [{ required: ['selector'], not: { required: ['elementId'] } }, { required: ['elementId'], not: { required: ['selector'] } }]

package/src/contracts/ui.ts

@@ -0,0 +1,94 @@
+export interface UIElementState {
+  checked?: boolean | null;
+  selected?: boolean | string | { id: string; label?: string } | null;
+  focused?: boolean | null;
+  expanded?: boolean | null;
+  enabled?: boolean | null;
+  text_value?: string | null;
+  value?: number | string | null;
+  raw_value?: number | string | null;
+  value_range?: {
+    min: number;
+    max: number;
+    step?: number | null;
+  } | null;
+  step?: number | null;
+}
+
+export interface SelectorConfidence {
+  score: number;
+  reason: string;
+}
+
+export interface UIResolutionSelector {
+  value: string | null;
+  confidence: SelectorConfidence | null;
+}
+
+export interface UIElementSemanticMetadata {
+  is_clickable: boolean;
+  is_container: boolean;
+  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;
+}
+
+export interface LoadingState {
+  active: boolean;
+  signal: string;
+  source: string;
+}
+
+export interface SnapshotDelta {
+  previous_snapshot_revision: number | null;
+  added_elements: number;
+  removed_elements: number;
+  mutated_elements: number;
+  total_elements: number;
+}
+
+export interface StateDelta {
+  base_snapshot_revision: number | null;
+  snapshot_revision: number;
+  added: UIElement[];
+  removed: Array<{ stable_id?: string; resourceId?: string; contentDescription?: string; text?: string; index: number }>;
+  changed: UIElement[];
+  truncated: boolean;
+  omitted_changes?: number;
+}
+
+export interface UIElement {
+  text: string | null;
+  contentDescription: string | null;
+  type: string;
+  clickable: boolean;
+  enabled: boolean;
+  visible: boolean;
+  bounds: [number, number, number, number];
+  resourceId: string | null;
+  parentId?: number;
+  children?: number[];
+  center?: [number, number];
+  depth?: number;
+  state?: UIElementState | null;
+  stable_id?: string | null;
+  role?: string | null;
+  test_tag?: string | null;
+  selector?: UIResolutionSelector | null;
+  semantic?: UIElementSemanticMetadata | null;
+}
+
+export interface ReadinessSummary {
+  state: 'loading' | 'transitioning' | 'settled' | 'unknown' | 'unresponsive' | 'debugger_paused';
+  scope: 'device_ui';
+  basis: 'observed' | 'heuristic' | 'insufficient';
+  captured_at_ms: number | null;
+  sample_count: number;
+  stable_for_ms: number;
+  snapshot_session_id: string | null;
+  snapshot_revision: number | null;
+  evidence: Array<{ code: string; source: string; captured_at_ms: number | null; snapshot_revision: number | null }>;
+  limitations: string[];
+  capabilities: { loading: boolean; transitioning: boolean; settled: boolean; unresponsive: boolean; debugger_paused: boolean };
+}

package/src/debugger/android.ts

@@ -34,7 +34,8 @@ export class AndroidDebugNative implements DebugNative {
     // `adb jdwp` is a subscription, not a one-shot command. Bound the sample.
     let jdwpOutput: string
     try { jdwpOutput = (await exec(resolveAdbCmd(), ['-s', device, 'jdwp'], { timeout: debuggerRemaining(500), signal: debuggerSignal(), maxBuffer: 1024 * 1024 })).stdout }
-    catch (e: any) {
+    catch (error: unknown) {
+      const e = error as { killed?: boolean; stderr?: string; stdout?: string }
       if (debuggerSignal()?.aborted) throw new DebuggerError('DEBUGGER_CANCELLED')
       debuggerRemaining(1)
       if (!e.killed || e.stderr?.trim()) throw nativeError(e, 'DEVICE_UNAVAILABLE')

package/src/debugger/diagnostics.ts

@@ -0,0 +1,43 @@
+/** Only catalog values cross the debugger error boundary. Never inspect exception text. */
+export const stages = ['prerequisite', 'compilation', 'worker_start', 'ipc', 'target_resolution', 'forwarding', 'attach', 'command', 'transport', 'cleanup', 'unknown'] as const
+export const reasons = ['unavailable', 'unsupported', 'spawn_failed', 'process_exited', 'invalid_message', 'message_limit', 'write_failed', 'connection_refused', 'transport_lost', 'timeout', 'cancelled', 'operation_failed', 'unknown'] as const
+export type DiagnosticStage = typeof stages[number]
+export type DiagnosticReason = typeof reasons[number]
+export interface DebuggerDiagnostic { stage: DiagnosticStage; reason: DiagnosticReason; recovery: string }
+const recovery: Record<DiagnosticStage, string> = {
+  prerequisite: 'Check JDK 17+ availability, including java, javac and jdk.jdi.',
+  compilation: 'Check the JDK compiler and worker source/cache availability.',
+  worker_start: 'Check Java worker launch availability. Inspect session state and cleanup before attaching again.',
+  ipc: 'Inspect session state and cleanup. Detach before attempting a fresh attach.',
+  target_resolution: 'Check the explicit device and running debuggable app/process.',
+  forwarding: 'Check the explicit device and debugger forwarding availability.',
+  attach: 'Check the running debuggable target and whether another debugger is attached. Inspect cleanup before a fresh attach.',
+  command: 'Inspect debugger session state and cleanup before another state-changing command.',
+  transport: 'Inspect session state and cleanup. Detach before attempting a fresh attach; execution state may be unknown.',
+  cleanup: 'Retry detach_debugger and inspect cleanup.remaining_resources. Do not kill the app or ADB server.',
+  unknown: 'Inspect debugger session state and cleanup; the failure cause is unknown.'
+}
+export function diagnostic(stage: DiagnosticStage, reason: DiagnosticReason): DebuggerDiagnostic {
+  const guidance = reason === 'timeout' || reason === 'cancelled'
+    ? 'Execution may be uncertain. Inspect session state and cleanup before another state-changing command.' : recovery[stage]
+  return { stage, reason, recovery: guidance }
+}
+export function parseDiagnostic(value: unknown): DebuggerDiagnostic {
+  if (!value || typeof value !== 'object') throw new Error('INVALID_WORKER_DIAGNOSTIC')
+  const { stage, reason } = value as Record<string, unknown>
+  if (!stages.includes(stage as DiagnosticStage) || !reasons.includes(reason as DiagnosticReason)) throw new Error('INVALID_WORKER_DIAGNOSTIC')
+  return diagnostic(stage as DiagnosticStage, reason as DiagnosticReason)
+}
+export class DebuggerError extends Error {
+  constructor(public code: string, public diagnostic?: DebuggerDiagnostic) { super(code) }
+}
+const validationCodes = new Set(['INVALID_ARGUMENT', 'DEBUGGER_BUSY', 'DEBUGGER_NOT_FOUND', 'DEBUGGER_PAUSED', 'DEBUGGER_NOT_PAUSED', 'DEBUGGER_STALE_REFERENCE'])
+export function classify(error: unknown, stage: DiagnosticStage, fallback: string, reason: DiagnosticReason = 'unknown'): DebuggerError {
+  const existing = error instanceof DebuggerError ? error : new DebuggerError(fallback)
+  if (existing.diagnostic || validationCodes.has(existing.code)) return existing
+  const knownReason = existing.code === 'DEBUGGER_TIMEOUT' ? 'timeout' : existing.code === 'DEBUGGER_CANCELLED' ? 'cancelled' : reason
+  return new DebuggerError(existing.code, diagnostic(stage, knownReason))
+}
+export async function atStage<T>(stage: DiagnosticStage, fallback: string, operation: () => Promise<T>): Promise<T> {
+  try { return await operation() } catch (error) { throw classify(error, stage, fallback) }
+}

package/src/debugger/guard.ts

@@ -1,6 +1,11 @@
 import { AsyncLocalStorage } from 'node:async_hooks'
 import { DebuggerError } from './worker.js'
-let pauseProvider: (device: string) => any = () => null
+interface PauseEvidence {
+  debug_session_id: string
+  captured_at_ms: number
+  target: unknown
+}
+let pauseProvider: (device: string) => PauseEvidence | null = () => null
 export function registerDebuggerPauseProvider(provider: typeof pauseProvider) { pauseProvider = provider }
 const context = new AsyncLocalStorage<{ platform: string; device: string; dispatched: boolean }>()
 export function withDebuggerGuard<T>(platform: string, device: string, operation: () => Promise<T>) {

package/{worker → src/debugger/java}/DebuggerWorker.java

@@ -139,9 +139,15 @@ public final class DebuggerWorker {
     try(Reader reader=new InputStreamReader(System.in,StandardCharsets.UTF_8)){
       StringBuilder line=new StringBuilder();int ch;
       while((ch=reader.read())!=-1){if(ch!='\n'){line.append((char)ch);if(line.length()>MAX_LINE)throw new IOException("IPC_LIMIT");continue;}
-        Object id=null;
-        try{@SuppressWarnings("unchecked") Map<String,Object>a=(Map<String,Object>)new Json(line.toString()).value();id=a.get("id");synchronized(lock){Object result=command(a);send(obj("id",id,"result",result));}}
-        catch(Exception e){String msg=e.getMessage();String code=msg!=null&&msg.matches("(?:DEBUGGER|INVALID|PROCESS|DEVICE)_[A-Z_]+")?msg:e instanceof VMDisconnectedException?"DEBUGGER_DISCONNECTED":"DEBUGGER_WORKER_FAILED";send(obj("id",id,"error",obj("code",code)));}
+        Object id=null;String commandName="";
+        try{@SuppressWarnings("unchecked") Map<String,Object>a=(Map<String,Object>)new Json(line.toString()).value();id=a.get("id");commandName=str(a,"command");synchronized(lock){Object result=command(a);send(obj("id",id,"result",result));}}
+        catch(Exception e){
+          String msg=e.getMessage();
+          String code=msg!=null&&msg.matches("(?:DEBUGGER|INVALID|PROCESS|DEVICE)_[A-Z_]+")?msg:e instanceof VMDisconnectedException?"DEBUGGER_DISCONNECTED":"DEBUGGER_WORKER_FAILED";
+          String stage=commandName.equals("attach")?"attach":e instanceof VMDisconnectedException?"transport":"command";
+          String reason=e instanceof java.net.ConnectException?"connection_refused":e instanceof VMDisconnectedException?"transport_lost":e instanceof java.net.SocketTimeoutException || e instanceof TransportTimeoutException?"timeout":"operation_failed";
+          send(obj("id",id,"error",obj("code",code,"diagnostic",obj("stage",stage,"reason",reason))));
+        }
         line.setLength(0);
       }
     }finally{synchronized(lock){finish("parent_closed");}watchdog.shutdownNow();}

package/src/debugger/protocol.ts

@@ -0,0 +1,37 @@
+import { parseDiagnostic, type DebuggerDiagnostic } from './diagnostics.js'
+/** Worker messages contain private debuggee data; never include them in errors. */
+export interface WorkerEvent extends Record<string, unknown> {
+  event: string
+  reason?: string
+  diagnostic?: DebuggerDiagnostic
+  stop_id?: string
+}
+export type WorkerReply = Record<string, unknown>
+export type WorkerMessage =
+  | { kind: 'event'; value: WorkerEvent }
+  | { kind: 'reply'; id: number; result: WorkerReply; error?: { code?: string; diagnostic?: DebuggerDiagnostic } }
+
+const workerCodes = new Set(['INVALID_ARGUMENT', 'DEBUGGER_BUSY', 'DEBUGGER_NOT_FOUND', 'DEBUGGER_NOT_PAUSED', 'DEBUGGER_STALE_REFERENCE', 'DEBUGGER_DISCONNECTED', 'DEBUGGER_WORKER_FAILED'])
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+export function parseWorkerMessage(value: unknown): WorkerMessage {
+  if (!record(value)) throw new Error('INVALID_WORKER_MESSAGE')
+  if (value.event) {
+    if (typeof value.event !== 'string') throw new Error('INVALID_WORKER_EVENT')
+    for (const field of ['reason', 'stop_id']) {
+      if (value[field] !== undefined && typeof value[field] !== 'string') throw new Error('INVALID_WORKER_EVENT')
+    }
+    const event = { ...value } as WorkerEvent
+    if (value.diagnostic !== undefined) event.diagnostic = parseDiagnostic(value.diagnostic)
+    return { kind: 'event', value: event }
+  }
+  if (typeof value.id !== 'number' || !Number.isSafeInteger(value.id) || value.id < 1) throw new Error('INVALID_WORKER_REPLY')
+  if (value.error) {
+    if (!record(value.error) || (value.error.code !== undefined && typeof value.error.code !== 'string')) throw new Error('INVALID_WORKER_ERROR')
+    if (value.error.code !== undefined && !workerCodes.has(value.error.code as string)) throw new Error('INVALID_WORKER_ERROR')
+    return { kind: 'reply', id: value.id, result: {}, error: { ...(value.error.code === undefined ? {} : { code: value.error.code as string }), ...(value.error.diagnostic === undefined ? {} : { diagnostic: parseDiagnostic(value.error.diagnostic) }) } }
+  }
+  if (!record(value.result)) throw new Error('INVALID_WORKER_RESULT')
+  return { kind: 'reply', id: value.id, result: value.result }
+}