mobile-debug-mcp 0.33.0 → 0.35.0

package/src/server/handlers/observe.ts

@@ -0,0 +1,116 @@
+
+
+import { ToolsObserve } from '../../observe/index.js'
+import { withObservationContext } from '../../observe/performance-metrics.js'
+import {
+  getBooleanArg,
+  getNumberArg,
+  getStringArg,
+  requireStringArg,
+  ToolCallArgs,
+  wrapResponse
+} from '../common.js'
+import type { PlatformArg, ResponseMode } from './handler-types.js'
+
+export async function handleGetLogs(args: ToolCallArgs) {
+  const platform = requireStringArg(args, 'platform') as PlatformArg
+  const appId = getStringArg(args, 'appId')
+  const deviceId = getStringArg(args, 'deviceId')
+  const pid = getNumberArg(args, 'pid')
+  const tag = getStringArg(args, 'tag')
+  const level = getStringArg(args, 'level')
+  const contains = getStringArg(args, 'contains')
+  const since_seconds = getNumberArg(args, 'since_seconds')
+  const limit = getNumberArg(args, 'limit')
+  const lines = getNumberArg(args, 'lines')
+  const res = await ToolsObserve.getLogsHandler({ platform, appId, deviceId, pid, tag, level, contains, since_seconds, limit, lines })
+  const filtered = !!(pid || tag || level || contains || since_seconds || appId)
+  return {
+    content: [
+      { type: 'text' as const, text: JSON.stringify({ device: res.device, result: { count: res.logCount, filtered, crashLines: (res.crashLines || []), source: res.source, meta: res.meta || {} } }, null, 2) },
+      { type: 'text' as const, text: JSON.stringify({ logs: res.logs }, null, 2) }
+    ]
+  }
+}
+
+export async function handleCaptureScreenshot(args: ToolCallArgs) {
+  const platform = requireStringArg(args, 'platform') as PlatformArg
+  const deviceId = getStringArg(args, 'deviceId')
+  const started = performance.now()
+  const res = await ToolsObserve.captureScreenshotHandler({ platform, deviceId })
+  const screenshotMs = performance.now() - started
+  const mime = res.screenshot_mime || 'image/png'
+  const content: Array<{ type: 'text' | 'image'; text?: string; data?: string; mimeType?: string }> = [
+    { type: 'text', text: JSON.stringify({ device: res.device, result: { resolution: res.resolution, mimeType: mime }, timing: { total_ms: screenshotMs, screenshot_ms: screenshotMs } }, null, 2) },
+    { type: 'image', data: res.screenshot, mimeType: mime }
+  ]
+  if (res.screenshot_fallback) {
+    content.push({ type: 'text', text: JSON.stringify({ note: 'JPEG fallback included for compatibility', mimeType: res.screenshot_fallback_mime || 'image/jpeg' }) })
+    content.push({ type: 'image', data: res.screenshot_fallback, mimeType: res.screenshot_fallback_mime || 'image/jpeg' })
+  }
+  return { content }
+}
+
+export async function handleCaptureDebugSnapshot(args: ToolCallArgs) {
+  const reason = getStringArg(args, 'reason')
+  const includeLogs = getBooleanArg(args, 'includeLogs')
+  const logLines = getNumberArg(args, 'logLines')
+  const platform = getStringArg(args, 'platform') as PlatformArg | undefined
+  const appId = getStringArg(args, 'appId')
+  const deviceId = getStringArg(args, 'deviceId')
+  const sessionId = getStringArg(args, 'sessionId')
+  const includeScreenshot = getBooleanArg(args, 'includeScreenshot')
+  const res = await ToolsObserve.captureDebugSnapshotHandler({ reason, includeLogs, includeScreenshot, logLines, platform, appId, deviceId, sessionId })
+  return wrapResponse(res)
+}
+
+export async function handleGetUITree(args: ToolCallArgs) {
+  const platform = requireStringArg(args, 'platform') as PlatformArg
+  const deviceId = getStringArg(args, 'deviceId')
+  const responseMode = (getStringArg(args, 'responseMode') as ResponseMode | undefined) ?? 'debug'
+  const sinceSnapshotRevision = getNumberArg(args, 'sinceSnapshotRevision')
+  const metricsStepId = process.env.MOBILE_DEBUG_MCP_UI_TREE_METRICS === '1' ? getStringArg(args, '_metricsStepId') : undefined
+  const res = await withObservationContext({ stepId: metricsStepId, purpose: metricsStepId?.includes('post-response') ? 'assertion' : 'debug' }, () =>
+    ToolsObserve.getUITreeHandler({ platform, deviceId, responseMode, sinceSnapshotRevision }))
+  return wrapResponse(res)
+}
+
+export async function handleGetCurrentScreen(args: ToolCallArgs) {
+  const deviceId = getStringArg(args, 'deviceId')
+  const res = await ToolsObserve.getCurrentScreenHandler({ deviceId })
+  return wrapResponse(res)
+}
+
+export async function handleGetScreenFingerprint(args: ToolCallArgs) {
+  const platform = getStringArg(args, 'platform') as PlatformArg | undefined
+  const deviceId = getStringArg(args, 'deviceId')
+  const res = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId })
+  return wrapResponse(res)
+}
+
+export async function handleStartLogStream(args: ToolCallArgs) {
+  const platform = (getStringArg(args, 'platform') as PlatformArg | undefined) ?? 'android'
+  const packageName = requireStringArg(args, 'packageName')
+  const level = (getStringArg(args, 'level') as 'error' | 'warn' | 'info' | 'debug' | undefined) ?? 'error'
+  const sessionId = getStringArg(args, 'sessionId')
+  const deviceId = getStringArg(args, 'deviceId')
+  const res = await ToolsObserve.startLogStreamHandler({ platform, packageName, level, sessionId, deviceId })
+  return wrapResponse(res)
+}
+
+export async function handleReadLogStream(args: ToolCallArgs) {
+  const platform = getStringArg(args, 'platform') as PlatformArg | undefined
+  const sessionId = getStringArg(args, 'sessionId')
+  const limit = getNumberArg(args, 'limit')
+  const since = getStringArg(args, 'since')
+  const res = await ToolsObserve.readLogStreamHandler({ platform, sessionId, limit, since })
+  return wrapResponse(res)
+}
+
+export async function handleStopLogStream(args: ToolCallArgs) {
+  const platform = getStringArg(args, 'platform') as PlatformArg | undefined
+  const sessionId = getStringArg(args, 'sessionId')
+  const res = await ToolsObserve.stopLogStreamHandler({ platform, sessionId })
+  return wrapResponse(res)
+}
+

package/src/server/handlers/payload.ts

@@ -0,0 +1,36 @@
+import type { ActionExecutionResult, DeviceInfo, ActionConditionResult, TimingBreakdown } from '../../types.js'
+import type { ToolCallResult } from '../common.js'
+
+// Internal decoded MCP payloads vary by capability. Keep the fields inspected by
+// orchestration explicit while preserving untouched capability-specific fields.
+export interface ToolPayload {
+  success?: boolean
+  action_id?: string
+  action_type?: string
+  lifecycle_state?: string
+  failure_code?: string
+  retryable?: boolean
+  device?: DeviceInfo
+  target?: ActionExecutionResult['target']
+  ui_fingerprint_before?: string | null
+  error?: string | { code?: string; message?: string }
+  reason?: string
+  details?: { error?: unknown }
+  dispatch_started?: boolean
+  delivery_status?: string
+  state_delta?: unknown
+  state_delta_available?: boolean
+  actual_state?: unknown
+  observed_fingerprint?: string | null
+  status?: string
+  condition?: ActionConditionResult
+  verification?: { mode?: string; status: string }
+  evidence?: { action_id?: string }
+  verification_diagnostic?: { code: string; retryable: boolean }
+  observed?: { matched_count?: number | null }
+  timing?: TimingBreakdown
+}
+export function payloadOf(response: ToolCallResult): ToolPayload {
+  const text = response.content.find(item => item.type === 'text')?.text
+  return text ? JSON.parse(text) as ToolPayload : null as unknown as ToolPayload
+}

package/src/server/handlers/tool-handlers.ts

@@ -0,0 +1,159 @@
+import type { DeviceInfo } from '../../types.js'
+import { handleDebugger } from './debugger-handlers.js'
+import { debuggerContracts } from '../schemas/debugger-schema.js'
+import { debuggerSessions } from '../../debugger/sessions.js'
+import { withDebuggerGuard, guardDispatched } from '../../debugger/guard.js'
+import { TraceError } from '../../observe/system-trace.js'
+import { systemTraceTools } from '../schemas/system-trace-schema.js'
+import { withTiming } from '../../utils/timing.js'
+import { readinessSchema, readinessWaitSchema } from '../schemas/readiness-schema.js'
+import { getAppReadiness } from '../../observe/readiness-service.js'
+import { validateExpectedState } from '../schemas/condition-schema.js'
+import { resolveTargetDevice, withResolvedDevice } from '../../utils/resolve-device.js'
+
+import {
+  ToolCallArgs,
+  ToolCallResult,
+  ToolHandler,
+  wrapResponse,
+  wrapToolError
+} from '../common.js'
+import { handleTerminateApp, handleResetAppData, handleInstallApp, handleBuildApp, handleBuildAndInstall, handleStartApp, handleRestartApp } from './manage.js'
+import { handleGetLogs, handleCaptureScreenshot, handleCaptureDebugSnapshot, handleGetUITree, handleGetCurrentScreen, handleGetScreenFingerprint, handleStartLogStream, handleReadLogStream, handleStopLogStream } from './observe.js'
+import { handleWaitForScreenChange, handleExpectScreen, handleExpectElementVisible, handleExpectState, handleAdjustControl, handleWaitForUI, handleWaitForUIChange, handleFindElement } from './interact.js'
+import { handleTap, handleTapElement, handleSwipe, handleScrollToElement, handleTypeText, handlePressBack } from './input.js'
+import { handleRunJourney } from './journey.js'
+import { handleListDevices, handleGetSystemStatus, handleClassifyActionOutcome, handleGetNetworkActivity, handleSystemTrace } from './diagnostic.js'
+import { correlatedHandler } from './action-execution.js'
+
+const systemTraceToolNames = new Set(systemTraceTools.map(tool => tool.name))
+
+export const toolHandlers: Record<string, ToolHandler> = {
+  ...Object.fromEntries(systemTraceTools.map(({ name }) => [name, (args: ToolCallArgs) => handleSystemTrace(name, args)])),
+  get_app_readiness: async args => {
+    const parsed = readinessSchema.safeParse(args)
+    if (!parsed.success) throw new Error('INVALID_ARGUMENT: invalid readiness arguments')
+    return wrapResponse(await getAppReadiness(parsed.data))
+  },
+  wait_for_app_ready: async args => {
+    const parsed = readinessWaitSchema.safeParse(args)
+    if (!parsed.success) throw new Error('INVALID_ARGUMENT: invalid readiness arguments')
+    return wrapResponse(await getAppReadiness(parsed.data, true))
+  },
+  start_app: handleStartApp,
+  terminate_app: handleTerminateApp,
+  restart_app: handleRestartApp,
+  reset_app_data: handleResetAppData,
+  install_app: handleInstallApp,
+  build_app: handleBuildApp,
+  build_and_install: handleBuildAndInstall,
+  get_logs: handleGetLogs,
+  list_devices: handleListDevices,
+  get_system_status: handleGetSystemStatus,
+  capture_screenshot: handleCaptureScreenshot,
+  capture_debug_snapshot: handleCaptureDebugSnapshot,
+  get_ui_tree: handleGetUITree,
+  get_current_screen: handleGetCurrentScreen,
+  get_screen_fingerprint: handleGetScreenFingerprint,
+  wait_for_screen_change: handleWaitForScreenChange,
+  wait_for_ui_change: handleWaitForUIChange,
+  expect_screen: handleExpectScreen,
+  expect_element_visible: handleExpectElementVisible,
+  expect_state: handleExpectState,
+  adjust_control: handleAdjustControl,
+  wait_for_ui: handleWaitForUI,
+  find_element: handleFindElement,
+  tap: handleTap,
+  tap_element: handleTapElement,
+  run_journey: handleRunJourney,
+  swipe: handleSwipe,
+  scroll_to_element: handleScrollToElement,
+  type_text: handleTypeText,
+  press_back: handlePressBack,
+  start_log_stream: handleStartLogStream,
+  read_log_stream: handleReadLogStream,
+  stop_log_stream: handleStopLogStream,
+  classify_action_outcome: handleClassifyActionOutcome,
+  get_network_activity: handleGetNetworkActivity
+}
+
+for (const name of ['capture_screenshot', 'get_ui_tree', 'get_screen_fingerprint', 'capture_debug_snapshot', 'get_logs', 'read_log_stream', 'run_journey', 'adjust_control']) {
+  toolHandlers[name] = correlatedHandler(name, toolHandlers[name], name === 'adjust_control', name === 'run_journey')
+}
+
+async function dispatchGuarded(device: DeviceInfo, args: ToolCallArgs, handler: ToolHandler, addTiming: (response: ToolCallResult) => ToolCallResult) {
+  return withResolvedDevice(device, () => withDebuggerGuard('android', device.id, async () => {
+    const before = debuggerSessions.paused(device.id)
+    if (before) return wrapResponse({ success: false, failure_code: 'DEBUGGER_PAUSED', delivery_status: 'not_delivered', dispatch_started: false, debugger: before })
+    let response: ToolCallResult
+    try { response = await handler(args) } catch (error) {
+      if (!debuggerSessions.paused(device.id)) throw error
+      response = wrapResponse({ success: false })
+    }
+    const pause = debuggerSessions.paused(device.id)
+    if (pause) {
+      const item = response.content.find(item => item.type === 'text')
+      if (item?.text) {
+        const payload = JSON.parse(item.text)
+        Object.assign(payload, { success: false, failure_code: 'DEBUGGER_PAUSED', retryable: false,
+          dispatch_started: guardDispatched(), delivery_status: payload.success ? 'delivered' : guardDispatched() ? 'unknown' : 'not_delivered',
+          verification: { status: 'blocked', reason: 'DEBUGGER_PAUSED' }, debugger: pause })
+        item.text = JSON.stringify(payload)
+      }
+    }
+    return addTiming(response)
+  }))
+}
+
+function attachPausedObservation(name: string, args: ToolCallArgs, response: ToolCallResult) {
+  if (['capture_screenshot', 'get_ui_tree', 'get_screen_fingerprint', 'capture_debug_snapshot', 'get_logs', 'get_current_screen', 'read_log_stream'].includes(name) && args.platform !== 'ios') {
+    const item = response.content.find(item => item.type === 'text')
+    if (item?.text) {
+      try {
+        const payload = JSON.parse(item.text)
+        const device = payload.device ?? payload.evidence?.device
+        const id = device?.id ?? args.deviceId
+        const pause = id && device?.platform !== 'ios' ? debuggerSessions.paused(String(id)) : null
+        if (pause) item.text = JSON.stringify({ ...payload, debugger: pause })
+      } catch { /* Non-JSON observation */ }
+    }
+  }
+}
+
+export async function handleToolCall(name: string, args: ToolCallArgs = {}, signal?: AbortSignal) {
+  if (Object.hasOwn(debuggerContracts, name)) return handleDebugger(name, args, signal)
+  const handler = toolHandlers[name]
+  if (!handler) throw new Error(`Unknown tool: ${name}`)
+
+  const started = performance.now()
+  const measured: Record<string, number> = {}
+  const addTiming = (response: ToolCallResult) => {
+    if (!['start_app', 'restart_app', 'tap', 'tap_element', 'swipe', 'scroll_to_element', 'type_text', 'press_back', 'wait_for_ui', 'get_ui_tree', 'capture_screenshot', 'capture_debug_snapshot'].includes(name)) return response
+    const item = response.content.find(item => item.type === 'text')
+    if (item?.text) {
+      try {
+        const value = JSON.parse(item.text)
+        value.timing = { ...measured, ...value.timing, total_ms: performance.now() - started }
+        item.text = JSON.stringify(value)
+      } catch { /* Non-JSON text responses retain their original content. */ }
+    }
+    return response
+  }
+  return withTiming(measured, async () => {
+    try {
+      if (!systemTraceToolNames.has(name)) validateExpectedState(name, args)
+      const guarded = ['start_app', 'terminate_app', 'restart_app', 'reset_app_data', 'install_app', 'build_and_install', 'tap', 'tap_element', 'swipe', 'scroll_to_element', 'type_text', 'press_back', 'adjust_control', 'run_journey', 'wait_for_ui', 'wait_for_ui_change', 'wait_for_screen_change', 'expect_screen', 'expect_element_visible', 'expect_state'].includes(name)
+      if (guarded && args.platform !== 'ios' && debuggerSessions.hasActiveSessions()) {
+        const device = await resolveTargetDevice({ platform: 'android', deviceId: args.deviceId as string | undefined })
+        return dispatchGuarded(device, args, handler, addTiming)
+      }
+      const response = await handler(args)
+      attachPausedObservation(name, args, response)
+      return addTiming(response)
+    } catch (error) {
+      if (error instanceof TraceError) return { ...wrapResponse({ error: { tool: name, code: error.code, message: error.message } }), isError: true }
+      console.error(`Error executing tool ${name}:`, error)
+      return addTiming(wrapToolError(name, error))
+    }
+  })
+}

package/src/server/schemas/condition-schema.ts

@@ -0,0 +1,2 @@
+// Compatibility export for existing server consumers.
+export * from '../../contracts/condition.js'

package/src/server/schemas/debugger-schema.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod'
+const text = z.string().min(1).max(512)
+const integer = z.number().int().safe().positive()
+const timeout = z.number().int().min(100).max(30000)
+const target = { platform: z.literal('android'), deviceId: text, appId: text.regex(/^[A-Za-z][\w]*(?:\.[A-Za-z][\w]*)+$/), processId: integer.optional() }
+const session = { debugSessionId: text }
+const stop = { ...session, stopId: text }
+const specs = {
+  get_debugger_capabilities: { fields: target, command: 'capabilities', description: 'Probe optional Android JDK/JDWP prerequisites and matching running debuggable processes; does not attach.' },
+  attach_debugger: { fields: target, command: 'attach', description: 'Attach an owned Android JDI session. Requires an explicit device and debuggable app; choose processId when ambiguous. Stops suspend all app threads. Auto-detach: 60s paused, 5m idle, 30m total.' },
+  get_debugger_state: { fields: session, command: 'state', description: 'Read debugger state, current stop and breakpoint/cleanup status.' },
+  set_debugger_breakpoint: { fields: { ...session, className: text.regex(/^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/), line: integer }, command: 'set', description: 'Set an exact binary-class and executable-source-line breakpoint; unloaded classes remain pending. No silent line relocation.' },
+  remove_debugger_breakpoint: { fields: { ...session, breakpointId: text }, command: 'remove', description: 'Remove an owned breakpoint; repeated removal succeeds.' },
+  wait_for_debugger_event: { fields: { ...session, afterSequence: z.number().int().safe().min(0).optional() }, command: 'events', description: 'Wait for bounded debugger events after a sequence cursor. Empty timeout does not affect execution; overflow is explicit.' },
+  get_debugger_stack: { fields: { ...stop, threadId: text, offset: z.number().int().min(0).max(999).optional(), limit: z.number().int().min(1).max(100).optional() }, command: 'stack', description: 'Read bounded stack frames for a stopped thread; IDs expire on resume.' },
+  get_debugger_locals: { fields: { ...stop, frameId: text }, command: 'locals', description: 'Read at most 100 shallow locals. Sensitive values returned only on request; strings truncate at 256 characters. No evaluation or field traversal.' },
+  step_debugger: { fields: { ...stop, threadId: text, kind: z.enum(['into', 'over', 'out']) }, command: 'step', description: 'Acknowledge one-shot line stepping and resume. Wait for a subsequent stop event separately.' },
+  resume_debugger: { fields: stop, command: 'resume', description: 'Resume owned debugger suspension and immediately expire stopped references.' },
+  detach_debugger: { fields: session, command: 'detach', description: 'Dispose the owned debugger connection, release owned suspension and remove its exact forward. Idempotent; retries incomplete cleanup.' }
+}
+// Derive JSON schemas and runtime validation from the same small Zod field vocabulary.
+function jsonField(schema: z.ZodType): Record<string, unknown> {
+  if (schema instanceof z.ZodOptional) return jsonField(schema.unwrap() as z.ZodType)
+  if (schema instanceof z.ZodLiteral) return { type: 'string', enum: [schema.value] }
+  if (schema instanceof z.ZodEnum) return { type: 'string', enum: schema.options }
+  if (schema instanceof z.ZodString) {
+    const json = z.toJSONSchema(schema)
+    return { type: 'string', minLength: 1, maxLength: 512, ...(json.pattern ? { pattern: json.pattern } : {}) }
+  }
+  if (schema instanceof z.ZodNumber) return { type: 'integer', minimum: schema.minValue, maximum: schema.maxValue }
+  throw new Error('Unsupported debugger field schema')
+}
+export const debuggerContracts = Object.fromEntries(Object.entries(specs).map(([name, spec]) => [name, {
+  ...spec, schema: z.object({ ...spec.fields, responseMode: z.enum(['compact', 'debug']).default('debug'), timeoutMs: timeout.default(name === 'wait_for_debugger_event' ? 1000 : 10000) }).strict()
+}]))
+export const debuggerTools = Object.entries(debuggerContracts).map(([name, spec]) => ({
+  name, description: spec.description,
+  inputSchema: {
+    type: 'object' as const, additionalProperties: false,
+    required: Object.entries(spec.fields).filter(([, field]) => !field.isOptional()).map(([key]) => key),
+    properties: { responseMode: { type: 'string', enum: ['compact', 'debug'], default: 'debug' }, ...Object.fromEntries(Object.entries(spec.fields).map(([key, field]) => [key, jsonField(field)])), timeoutMs: { type: 'integer', minimum: 100, maximum: 30000, default: name === 'wait_for_debugger_event' ? 1000 : 10000 } }
+  }
+}))

package/src/server/{journey-schema.ts → schemas/journey-schema.ts}

@@ -1,20 +1,13 @@
+import { verificationModeSchema, responseModeSchema, verificationModeJson } from '../../contracts/execution-controls.js'
+import { waitForSchema as waitFor, targetFields as target, exactlyOneTarget, targetJson, oneTargetJson } from '../../contracts/target.js'
+export { tapElementControlsSchema } from '../../contracts/target.js'
+import { selectorSchema as selector, selectorJson } from '../../contracts/selector.js'
 import { z } from 'zod'
 import { expectedStateSchema, expectedStateJson } from './condition-schema.js'
 
-const selector = 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')
-const verificationMode = z.enum(['none', 'light', 'full'])
+const verificationMode = verificationModeSchema
 const timeoutMs = z.number().int().min(100).max(60000).optional()
 const pollIntervalMs = z.number().int().min(50).max(1000).optional()
-const waitFor = 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()
-const target = { selector: selector.optional(), elementId: z.string().min(1).optional() }
-const exactlyOneTarget = (value: { selector?: unknown, elementId?: string }) => Number(!!value.selector) + Number(!!value.elementId) === 1
 const assertion = z.union([
   z.object({ kind: z.literal('element_visible'), selector }).strict(),
   z.object({ kind: z.literal('element_absent'), selector }).strict(),
@@ -28,24 +21,17 @@ const step = z.union([
   z.object({ id, type: z.literal('wait'), selector, condition: z.enum(['exists', 'not_exists', 'visible', 'clickable']).optional(), timeoutMs, pollIntervalMs }).strict(),
   z.object({ id, type: z.literal('assert'), assertion, timeoutMs, pollIntervalMs }).strict()
 ])
-export const tapElementControlsSchema = z.object({
-  elementId: z.string().min(1).optional(), selector: selector.optional(), waitFor: waitFor.optional()
-}).strict().refine(value => Number(!!value.elementId) + Number(!!value.selector) === 1 && (!value.elementId || !value.waitFor))
 
 export const journeySchema = z.object({
   platform: z.enum(['android', 'ios']), deviceId: z.string().min(1).optional(),
-  responseMode: z.enum(['compact', 'debug']).default('compact'), captureOnFailure: z.boolean().default(false),
+  systemTraceId: z.string().uuid().optional(),
+  responseMode: responseModeSchema.default('compact'), captureOnFailure: z.boolean().default(false),
   defaults: z.object({ verificationMode: verificationMode.optional(), actionTimeoutMs: z.number().int().finite().optional(), verificationTimeoutMs: z.number().int().finite().optional() }).strict().optional(),
   steps: z.array(step).min(1).max(50)
 }).strict().refine(value => new Set(value.steps.map(step => step.id)).size === value.steps.length, 'Step IDs must be unique')
 
-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] })) }
-const targetJson = { selector: selectorJson, elementId: { type: 'string', minLength: 1 } }
-const oneTargetJson = [{ required: ['selector'], not: { required: ['elementId'] } }, { required: ['elementId'], not: { required: ['selector'] } }]
 const intervalJson = { timeoutMs: { type: 'integer', minimum: 100, maximum: 60000 }, pollIntervalMs: { type: 'integer', minimum: 50, maximum: 1000 } }
-const modeJson = { type: 'string', enum: ['none', 'light', 'full'] }
+const modeJson = verificationModeJson
 const objectJson = (properties: Record<string, unknown>, required: string[], extra = {}) => ({ type: 'object', additionalProperties: false, properties, required, ...extra })
 export const journeyStepsJson = {
   type: 'array', minItems: 1, maxItems: 50, items: { oneOf: [

package/src/server/schemas/system-trace-schema.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod'
+const target = { platform: z.enum(['android', 'ios']), deviceId: z.string().min(1).optional() }
+export const traceTargetSchema = z.object(target).strict()
+export const traceStartSchema = z.object({ ...target, durationMs: z.number().int().min(1000).max(120000).default(30000) }).strict()
+export const traceControlSchema = z.object({ traceId: z.string().uuid() }).strict()
+const properties = { platform: { type: 'string', enum: ['android', 'ios'] }, deviceId: { type: 'string', minLength: 1 } }
+export const systemTraceTools = [
+  { name: 'get_system_trace_capabilities', description: 'Probe Android Perfetto prerequisites without recording. Device-wide system tracing is optional; iOS is unsupported.',
+    inputSchema: { type: 'object' as const, additionalProperties: false, required: ['platform'], properties } },
+  { name: 'start_system_trace', description: 'Start bounded Android Perfetto recording, returning an owned trace_id. Run an existing journey with systemTraceId, then stop to retrieve a local artifact or cancel to discard. Device-wide traces may contain sensitive system annotations; no upload.',
+    inputSchema: { type: 'object' as const, additionalProperties: false, required: ['platform'], properties: { ...properties, durationMs: { type: 'integer', minimum: 1000, maximum: 120000, default: 30000 } } } },
+  ...['get_system_trace_status', 'stop_system_trace', 'cancel_system_trace'].map(name => ({ name,
+    description: name === 'get_system_trace_status' ? 'Reconcile an owned trace and retrieve its state; finalise duration-completed capture.' :
+      name === 'stop_system_trace' ? 'Stop owned capture gracefully and retrieve a local Perfetto artifact. Retry after a transfer/cleanup failure.' : 'Stop owned capture and discard partial files. Already completed local artifacts are retained.',
+    inputSchema: { type: 'object' as const, additionalProperties: false, required: ['traceId'], properties: { traceId: { type: 'string', format: 'uuid' } } }
+  }))
+]