mobile-debug-mcp 0.34.0 → 0.35.0

package/src/server/handlers/input.ts

@@ -0,0 +1,173 @@
+import type { UiSelector as ExpectElementSelectorArg } from '../../contracts/selector.js'
+import { measure } from '../../utils/timing.js'
+import { runWithBudget } from '../../utils/operation-budget.js'
+import { tapElementControlsSchema } from '../schemas/journey-schema.js'
+import { notifyActionStart } from '../../interact/conditional-action.js'
+
+import { ToolsInteract } from '../../interact/index.js'
+import { recordObservationConsumer, recordObservationEvent, withObservationContext } from '../../observe/performance-metrics.js'
+import {
+  buildActionExecutionResult,
+  captureActionFingerprint,
+  getNumberArg,
+  getStringArg,
+  inferGenericFailure,
+  inferScrollFailure,
+  requireNumberArg,
+  requireObjectArg,
+  requireStringArg,
+  ToolCallArgs,
+  wrapResponse
+} from '../common.js'
+import type { PlatformArg, ScrollSelectorArg } from './handler-types.js'
+import { interactionControls, actionHandler } from './action-execution.js'
+
+export async function executeTap(args: ToolCallArgs) {
+  const platform = getStringArg(args, 'platform') as PlatformArg | undefined
+  const x = requireNumberArg(args, 'x')
+  const y = requireNumberArg(args, 'y')
+  const deviceId = getStringArg(args, 'deviceId')
+  const { verificationMode, actionTimeoutMs } = interactionControls(args)
+  const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null
+  notifyActionStart()
+  const res = await measure('dispatch_ms', () => ToolsInteract.tapHandler({ platform, x, y, deviceId, timeoutMs: actionTimeoutMs }))
+  const uiFingerprintAfter = verificationMode === 'full' ? await measure('post_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null
+  const result = buildActionExecutionResult({
+    actionType: 'tap',
+    sourceModule: 'server',
+    selector: { x, y },
+    success: !!res.success,
+    uiFingerprintBefore,
+    uiFingerprintAfter,
+    failure: res.success ? undefined : inferGenericFailure(res.error)
+  })
+  return wrapResponse(result)
+}
+
+export async function executeTapElement(args: ToolCallArgs) {
+  const controls = tapElementControlsSchema.safeParse({ elementId: args.elementId, selector: args.selector, waitFor: args.waitFor })
+  if (!controls.success) throw new Error(`INVALID_ARGUMENT: ${controls.error.message}`)
+  const elementId = controls.data.elementId
+  const selector = controls.data.selector as ExpectElementSelectorArg | undefined
+  const { verificationMode, actionTimeoutMs } = interactionControls(args)
+  let resolvedId = elementId
+  let freshTree: import('../../interact/observation.js').UiTree | undefined
+  if (selector) {
+    const waitFor = controls.data.waitFor
+    const targetStarted = performance.now()
+    const resolutionTimeoutMs = waitFor?.timeoutMs ?? actionTimeoutMs ?? 5000
+    const resolution = (await withObservationContext({ stepId: args._stepId as string | undefined, purpose: 'target' }, () =>
+      measure('target_resolution_ms', () => runWithBudget(resolutionTimeoutMs, () => ToolsInteract.waitForUIHandler({ selector, condition: waitFor?.condition ?? 'clickable', timeout_ms: resolutionTimeoutMs, poll_interval_ms: waitFor?.pollIntervalMs ?? 100, match: waitFor?.match, singleObservation: true, singleAttempt: !waitFor, rejectAmbiguous: !waitFor, resolveTapTarget: true, platform: getStringArg(args, 'platform') as PlatformArg | undefined, deviceId: getStringArg(args, 'deviceId') })))))!
+    recordObservationEvent({ step_id: args._stepId as string | undefined, purpose: 'target', target_resolution_ms: performance.now() - targetStarted, target_resolution_outcome: resolution.status })
+    if (resolution.status !== 'success' || !resolution.element?.elementId) return wrapResponse({ success: false, action_type: 'tap_element', failure_code: resolution.error?.code ?? 'ELEMENT_NOT_FOUND', retryable: true })
+    resolvedId = resolution.element.elementId
+    freshTree = resolution._tree
+  }
+  notifyActionStart()
+  if (freshTree) recordObservationConsumer(freshTree, 'target', args._stepId as string | undefined)
+  const res = await measure('dispatch_ms', () => ToolsInteract.tapElementHandler({ elementId: resolvedId!, freshTree, verificationMode, timeoutMs: actionTimeoutMs, platform: getStringArg(args, 'platform') as PlatformArg | undefined, deviceId: getStringArg(args, 'deviceId') }))
+  return wrapResponse(res)
+}
+
+export async function executeSwipe(args: ToolCallArgs) {
+  const platform = (getStringArg(args, 'platform') as PlatformArg | undefined) ?? 'android'
+  const x1 = requireNumberArg(args, 'x1')
+  const y1 = requireNumberArg(args, 'y1')
+  const x2 = requireNumberArg(args, 'x2')
+  const y2 = requireNumberArg(args, 'y2')
+  const duration = requireNumberArg(args, 'duration')
+  const deviceId = getStringArg(args, 'deviceId')
+  const { verificationMode, actionTimeoutMs } = interactionControls(args)
+  const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null
+  notifyActionStart()
+  const res = await measure('dispatch_ms', () => ToolsInteract.swipeHandler({ platform, x1, y1, x2, y2, duration, deviceId, timeoutMs: actionTimeoutMs }))
+  const uiFingerprintAfter = verificationMode === 'full' ? await measure('post_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null
+  const result = buildActionExecutionResult({
+    actionType: 'swipe',
+    sourceModule: 'server',
+    selector: { x1, y1, x2, y2, duration },
+    success: !!res.success,
+    uiFingerprintBefore,
+    uiFingerprintAfter,
+    failure: res.success ? undefined : inferGenericFailure(res.error)
+  })
+  return wrapResponse(result)
+}
+
+export async function executeScrollToElement(args: ToolCallArgs) {
+  const platform = requireStringArg(args, 'platform') as PlatformArg
+  const selector = requireObjectArg<ScrollSelectorArg>(args, 'selector')
+  const direction = getStringArg(args, 'direction') as 'down' | 'up' | undefined
+  const maxScrolls = getNumberArg(args, 'maxScrolls')
+  const scrollAmount = getNumberArg(args, 'scrollAmount')
+  const deviceId = getStringArg(args, 'deviceId')
+  const { verificationMode } = interactionControls(args)
+  const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null
+  notifyActionStart()
+  const res = await measure('dispatch_ms', () => ToolsInteract.scrollToElementHandler({ platform, selector, direction, maxScrolls, scrollAmount, deviceId }))
+  const uiFingerprintAfter = verificationMode === 'full' ? await measure('post_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null
+  const result = buildActionExecutionResult({
+    actionType: 'scroll_to_element',
+    sourceModule: 'server',
+    selector: selector ?? null,
+    resolved: res?.success && res?.element ? {
+      elementId: null,
+      text: res.element.text ?? null,
+      resource_id: res.element.resourceId ?? null,
+      accessibility_id: (res.element as typeof res.element & { contentDesc?: string }).contentDesc ?? null,
+      class: (res.element as typeof res.element & { className?: string }).className ?? null,
+      bounds: res.element.bounds ?? null,
+      index: null
+    } : null,
+    success: !!res.success,
+    uiFingerprintBefore,
+    uiFingerprintAfter,
+    failure: res.success ? undefined : inferScrollFailure(res.reason)
+  })
+  return wrapResponse(result)
+}
+
+export async function executeTypeText(args: ToolCallArgs) {
+  const text = requireStringArg(args, 'text')
+  const deviceId = getStringArg(args, 'deviceId')
+  const { verificationMode, actionTimeoutMs } = interactionControls(args)
+  const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint('android', deviceId)) : null
+  notifyActionStart()
+  const res = await measure('dispatch_ms', () => ToolsInteract.typeTextHandler({ text, deviceId, timeoutMs: actionTimeoutMs }))
+  const uiFingerprintAfter = verificationMode === 'full' ? await measure('post_observation_ms', () => captureActionFingerprint('android', deviceId)) : null
+  const result = buildActionExecutionResult({
+    actionType: 'type_text',
+    sourceModule: 'server',
+    selector: { text },
+    success: !!res.success,
+    uiFingerprintBefore,
+    uiFingerprintAfter,
+    failure: res.success ? undefined : inferGenericFailure(res.error)
+  })
+  return wrapResponse(result)
+}
+
+export async function executePressBack(args: ToolCallArgs) {
+  const deviceId = getStringArg(args, 'deviceId')
+  const { verificationMode, actionTimeoutMs } = interactionControls(args)
+  const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint('android', deviceId)) : null
+  notifyActionStart()
+  const res = await measure('dispatch_ms', () => ToolsInteract.pressBackHandler({ deviceId, timeoutMs: actionTimeoutMs }))
+  const uiFingerprintAfter = verificationMode === 'full' ? await measure('post_observation_ms', () => captureActionFingerprint('android', deviceId)) : null
+  const result = buildActionExecutionResult({
+    actionType: 'press_back',
+    sourceModule: 'server',
+    selector: { key: 'back' },
+    success: !!res.success,
+    uiFingerprintBefore,
+    uiFingerprintAfter,
+    failure: res.success ? undefined : inferGenericFailure(res.error)
+  })
+  return wrapResponse(result)
+}
+export const handleTap = actionHandler('tap', executeTap)
+export const handleTapElement = actionHandler('tap_element', executeTapElement)
+export const handleSwipe = actionHandler('swipe', executeSwipe)
+export const handleScrollToElement = actionHandler('scroll_to_element', executeScrollToElement)
+export const handleTypeText = actionHandler('type_text', executeTypeText)
+export const handlePressBack = actionHandler('press_back', executePressBack)

package/src/server/handlers/interact.ts

@@ -0,0 +1,135 @@
+import type { UiSelector as ExpectElementSelectorArg } from '../../contracts/selector.js'
+import { markEvidenceVerification } from '../../observe/evidence.js'
+import { withReadyWait } from '../../observe/readiness-service.js'
+
+import { ToolsInteract } from '../../interact/index.js'
+import { recordObservationEvent, withObservationContext } from '../../observe/performance-metrics.js'
+import {
+  getBooleanArg,
+  getNumberArg,
+  getObjectArg,
+  getStringArg,
+  requireNumberArg,
+  requireObjectArg,
+  requireStringArg,
+  ToolCallArgs,
+  wrapResponse
+} from '../common.js'
+import type { PlatformArg, WaitForUiMatchArg, WaitForUiRetryArg } from './handler-types.js'
+
+export async function handleWaitForScreenChange(args: ToolCallArgs) {
+  const platform = getStringArg(args, 'platform') as PlatformArg | undefined
+  const previousFingerprint = requireStringArg(args, 'previousFingerprint')
+  const timeoutMs = getNumberArg(args, 'timeoutMs')
+  const pollIntervalMs = getNumberArg(args, 'pollIntervalMs')
+  const deviceId = getStringArg(args, 'deviceId')
+  const res = await ToolsInteract.waitForScreenChangeHandler({ platform, previousFingerprint, timeoutMs, pollIntervalMs, deviceId })
+  return wrapResponse(res)
+}
+
+export async function handleExpectScreen(args: ToolCallArgs) {
+  const platform = getStringArg(args, 'platform') as PlatformArg | undefined
+  const fingerprint = getStringArg(args, 'fingerprint')
+  const screen = getStringArg(args, 'screen')
+  const deviceId = getStringArg(args, 'deviceId')
+  const res = await ToolsInteract.expectScreenHandler({ platform, fingerprint, screen, deviceId })
+  return wrapResponse(res)
+}
+
+export async function handleExpectElementVisible(args: ToolCallArgs) {
+  const selector = requireObjectArg<ExpectElementSelectorArg>(args, 'selector')
+  const element_id = getStringArg(args, 'element_id')
+  const timeout_ms = getNumberArg(args, 'timeout_ms')
+  const poll_interval_ms = getNumberArg(args, 'poll_interval_ms')
+  const platform = getStringArg(args, 'platform') as PlatformArg | undefined
+  const deviceId = getStringArg(args, 'deviceId')
+  const res = await ToolsInteract.expectElementVisibleHandler({ selector, element_id, timeout_ms, poll_interval_ms, platform, deviceId })
+  return wrapResponse(res)
+}
+
+export async function handleExpectState(args: ToolCallArgs) {
+  const selector = getObjectArg<ExpectElementSelectorArg>(args, 'selector')
+  const element_id = getStringArg(args, 'element_id')
+  const property = requireStringArg(args, 'property')
+  const platform = getStringArg(args, 'platform') as PlatformArg | undefined
+  const deviceId = getStringArg(args, 'deviceId')
+  if (!selector && !element_id) {
+    throw new Error('Missing selector or element_id argument')
+  }
+  if (!Object.prototype.hasOwnProperty.call(args, 'expected')) {
+    throw new Error('Missing expected argument')
+  }
+  const expected = args.expected as boolean | number | string | Record<string, unknown>
+  const res = await ToolsInteract.expectStateHandler({ selector: selector ?? undefined, element_id: element_id ?? undefined, property, expected, platform, deviceId })
+  return wrapResponse(res)
+}
+
+export async function handleAdjustControl(args: ToolCallArgs) {
+  const selector = getObjectArg<ExpectElementSelectorArg>(args, 'selector')
+  const element_id = getStringArg(args, 'element_id')
+  const property = getStringArg(args, 'property') ?? 'value'
+  const targetValue = requireNumberArg(args, 'targetValue')
+  const tolerance = getNumberArg(args, 'tolerance')
+  const maxAttempts = getNumberArg(args, 'maxAttempts')
+  const platform = getStringArg(args, 'platform') as PlatformArg | undefined
+  const deviceId = getStringArg(args, 'deviceId')
+  if ((!selector && !element_id) || (selector && element_id)) {
+    throw new Error('Exactly one of selector or element_id argument is required')
+  }
+  const res = await ToolsInteract.adjustControlHandler({
+    selector: selector ?? undefined,
+    element_id: element_id ?? undefined,
+    property,
+    targetValue,
+    tolerance,
+    maxAttempts,
+    platform,
+    deviceId
+  })
+  markEvidenceVerification()
+  return wrapResponse(res)
+}
+
+export async function handleWaitForUI(args: ToolCallArgs) {
+  if (args.requireReady !== undefined && typeof args.requireReady !== 'boolean') throw new Error('INVALID_ARGUMENT: requireReady must be boolean')
+  const selector = getObjectArg<ExpectElementSelectorArg>(args, 'selector')
+  const condition = (getStringArg(args, 'condition') as 'exists' | 'not_exists' | 'visible' | 'clickable' | undefined) ?? 'exists'
+  const timeout_ms = getNumberArg(args, 'timeout_ms') ?? 60000
+  const poll_interval_ms = getNumberArg(args, 'poll_interval_ms') ?? 300
+  const match = getObjectArg<WaitForUiMatchArg>(args, 'match')
+  const retry = getObjectArg<WaitForUiRetryArg>(args, 'retry')
+  const platform = getStringArg(args, 'platform') as PlatformArg | undefined
+  const deviceId = getStringArg(args, 'deviceId')
+  const execute = (targetPlatform = platform, targetId = deviceId) => ToolsInteract.waitForUIHandler({ selector, condition, timeout_ms, poll_interval_ms, match, retry, platform: targetPlatform, deviceId: targetId })
+  const res = args.requireReady === true ? await withReadyWait({ platform, deviceId }, timeout_ms,
+    device => execute(device.platform as PlatformArg, device.id), (code, elapsed, samples) => ({ status: 'timeout', error: { code, message: 'Readiness wait could not complete' }, metrics: { latency_ms: elapsed, poll_count: samples, attempts: samples ? 1 : 0 }, requested: { selector, condition, match }, observed: { matched_count: 0, condition_satisfied: false, selected_index: null, last_matched_element: null } })) : await execute()
+  return wrapResponse(res)
+}
+
+export async function handleWaitForUIChange(args: ToolCallArgs) {
+  if (args.requireReady !== undefined && typeof args.requireReady !== 'boolean') throw new Error('INVALID_ARGUMENT: requireReady must be boolean')
+  const platform = getStringArg(args, 'platform') as PlatformArg | undefined
+  const deviceId = getStringArg(args, 'deviceId')
+  const timeout_ms = getNumberArg(args, 'timeout_ms') ?? 60000
+  const stability_window_ms = getNumberArg(args, 'stability_window_ms') ?? 300
+  const expected_change = getStringArg(args, 'expected_change') as 'hierarchy_diff' | 'text_change' | 'state_change' | undefined
+  const scope = getStringArg(args, 'scope') as 'screen' | 'subtree' | undefined
+  const target = getStringArg(args, 'target')
+  const execute = (targetPlatform = platform, targetId = deviceId) => ToolsInteract.waitForUIChangeHandler({ platform: targetPlatform, deviceId: targetId, timeout_ms, stability_window_ms, expected_change, scope, target })
+  const res = args.requireReady === true ? await withReadyWait({ platform, deviceId }, timeout_ms,
+    device => execute(device.platform as PlatformArg, device.id), (code, elapsed) => ({ success: false, timeout: true, observed_change: null, elapsed_ms: elapsed, reason: code, error: { code, message: 'Readiness wait could not complete' } })) : await execute()
+  return wrapResponse(res)
+}
+
+export async function handleFindElement(args: ToolCallArgs) {
+  const query = requireStringArg(args, 'query')
+  const exact = getBooleanArg(args, 'exact') ?? false
+  const timeoutMs = getNumberArg(args, 'timeoutMs') ?? 3000
+  const platform = getStringArg(args, 'platform') as PlatformArg | undefined
+  const deviceId = getStringArg(args, 'deviceId')
+  const targetStarted = performance.now()
+  const res = await withObservationContext({ purpose: 'target' }, () => ToolsInteract.findElementHandler({ query, exact, timeoutMs, platform, deviceId }))
+  recordObservationEvent({ target_resolution_ms: performance.now() - targetStarted, target_resolution_outcome: res.found ? 'found' : 'not_found', operation: 'find_element' })
+  return wrapResponse(res)
+}
+

package/src/server/handlers/journey-assertions.ts

@@ -0,0 +1,39 @@
+import type { UiSelector as ExpectElementSelectorArg } from '../../contracts/selector.js'
+
+import { ToolsInteract } from '../../interact/index.js'
+import { ToolsObserve } from '../../observe/index.js'
+
+
+import type { PlatformArg } from './handler-types.js'
+
+export async function expectElementAbsent({ selector, timeoutMs, pollIntervalMs, platform, deviceId }: { selector: ExpectElementSelectorArg, timeoutMs: number, pollIntervalMs: number, platform: PlatformArg, deviceId?: string }) {
+  const deadline = performance.now() + timeoutMs
+  let consecutive = 0
+  let observed: import('../../interact/waits/ui-wait-state.js').UIWaitResult['observed']
+  while (performance.now() < deadline) {
+    const result = await ToolsInteract.waitForUIHandler({ selector, condition: 'not_exists', timeout_ms: 0, singleObservation: true, singleAttempt: true, platform, deviceId })
+    observed = result!.observed
+    consecutive = result!.status === 'success' ? consecutive + 1 : 0
+    if (consecutive === 2 && performance.now() <= deadline) return { success: true, observed }
+    const delay = Math.max(100, pollIntervalMs)
+    if (performance.now() + delay >= deadline) break
+    await new Promise(resolve => setTimeout(resolve, delay))
+  }
+  return { success: false, failure_code: 'ASSERTION_TIMEOUT', observed }
+}
+
+export async function expectFingerprint({ fingerprint, timeoutMs, platform, deviceId }: { fingerprint: string, timeoutMs: number, platform: PlatformArg, deviceId?: string }) {
+  const deadline = performance.now() + timeoutMs
+  let consecutive = 0
+  let observed: string | null = null
+  while (performance.now() < deadline) {
+    const result = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId })
+    observed = result?.fingerprint ?? null
+    consecutive = observed === fingerprint ? consecutive + 1 : 0
+    if (consecutive === 2 && performance.now() <= deadline) return { success: true, observed_fingerprint: observed }
+    if (performance.now() + 100 >= deadline) break
+    await new Promise(resolve => setTimeout(resolve, 100))
+  }
+  return { success: false, failure_code: 'ASSERTION_TIMEOUT', observed_fingerprint: observed }
+}
+

package/src/server/handlers/journey.ts

@@ -0,0 +1,132 @@
+import type { z } from 'zod'
+import { debuggerSessions } from '../../debugger/sessions.js'
+import { systemTraces } from '../../observe/system-trace.js'
+import { currentEvidenceCorrelationId, bindSystemTrace, refreshJourneyEvidence, completeJourneyVerification } from '../../observe/evidence.js'
+import { runWithBudget } from '../../utils/operation-budget.js'
+import { journeySchema } from '../schemas/journey-schema.js'
+import { resolveTargetDevice, withResolvedDevice } from '../../utils/resolve-device.js'
+import { ToolsInteract } from '../../interact/index.js'
+import { ToolsObserve } from '../../observe/index.js'
+import { withObservationContext } from '../../observe/performance-metrics.js'
+import { wrapResponse, type ToolCallArgs } from '../common.js'
+import { payloadOf, type ToolPayload } from './payload.js'
+import { handleStartApp } from './manage.js'
+import { handleTapElement } from './input.js'
+import { expectElementAbsent, expectFingerprint } from './journey-assertions.js'
+
+type Journey = z.infer<typeof journeySchema>
+type Step = Journey['steps'][number]
+type AssertionStep = Extract<Step, { type: 'assert' }>
+interface StepResult {
+  id: string; type: Step['type']; status: string; success: boolean; reason?: string
+  result: ToolPayload | null; timing?: { total_ms: number }
+}
+interface Context {
+  input: Journey; deviceId: string; results: StepResult[]; stoppedAt: string | null; pendingLightStep: number | null
+}
+async function assertStep(step: AssertionStep, platform: Journey['platform'], deviceId: string): Promise<ToolPayload> {
+  const assertion = step.assertion
+  const timeoutMs = step.timeoutMs ?? 5000, pollIntervalMs = step.pollIntervalMs ?? 100
+  if (assertion.kind === 'element_visible') return ToolsInteract.expectElementVisibleHandler({ selector: assertion.selector, timeout_ms: timeoutMs, poll_interval_ms: pollIntervalMs, platform, deviceId })
+  if (assertion.kind === 'element_absent') return expectElementAbsent({ selector: assertion.selector, timeoutMs, pollIntervalMs, platform, deviceId })
+  if (assertion.kind === 'screen_fingerprint') return expectFingerprint({ fingerprint: assertion.fingerprint, timeoutMs, platform, deviceId })
+  if (assertion.kind === 'state_equals') return ToolsInteract.expectStateHandler({ selector: assertion.selector, element_id: assertion.elementId, property: assertion.property, expected: assertion.expected, platform, deviceId, stabilization_window_ms: timeoutMs, poll_interval_ms: pollIntervalMs, exact_budget: true })
+  return { success: false, failure_code: 'INVALID_ASSERTION' }
+}
+async function executeStep(s: Context, step: Step, covered: boolean): Promise<ToolPayload> {
+  const { platform, responseMode, defaults } = s.input, deviceId = s.deviceId
+  try {
+    if (step.type === 'tap') return payloadOf(await handleTapElement({ ...defaults, ...step, platform, deviceId, responseMode, _journey: true, _stepId: step.id, verificationMode: covered ? 'none' : step.verificationMode ?? defaults?.verificationMode ?? 'full' }))
+    if (step.type === 'wait') {
+      const result = (await withObservationContext({ stepId: step.id, purpose: 'target' }, () => ToolsInteract.waitForUIHandler({ selector: step.selector, condition: step.condition ?? 'exists', timeout_ms: step.timeoutMs ?? 5000, poll_interval_ms: step.pollIntervalMs ?? 100, platform, deviceId })))!
+      return { success: result.status === 'success', ...result }
+    }
+    if (step.type === 'assert') return await withObservationContext({ stepId: step.id, purpose: 'assertion' }, () => runWithBudget(step.timeoutMs ?? 5000, () => assertStep(step, platform, deviceId)))
+    if (step.type === 'start_app') return payloadOf(await handleStartApp({ ...defaults, platform, deviceId, appId: step.appId, responseMode, _journey: true, _stepId: step.id, verificationMode: step.verificationMode ?? defaults?.verificationMode ?? 'full' }))
+    return { success: false, failure_code: 'UNSUPPORTED_JOURNEY_STEP' }
+  } catch (error) {
+    return { success: false, failure_code: step.type === 'assert' ? 'ASSERTION_TIMEOUT' : 'STEP_FAILED', error: error instanceof Error ? error.message : String(error) }
+  }
+}
+function lightVerification(s: Context, step: Step, result: ToolPayload, covered: boolean, success: boolean) {
+  if (covered) {
+    result.verification = { mode: 'light', status: success ? 'unavailable' :
+      (['mismatch', 'unavailable'].includes(result.condition?.status ?? '') ? 'not_requested' : 'failed') }
+    if (success) {
+      result.verification_diagnostic = { code: 'VERIFICATION_UNAVAILABLE', retryable: true }
+      s.pendingLightStep = s.results.length
+    }
+  }
+  if (step.type !== 'assert' || s.pendingLightStep === null) return
+  const pending = s.results[s.pendingLightStep].result!
+  if (typeof result.observed?.matched_count === 'number') {
+    pending.verification!.status = 'observed'
+    if (pending.evidence) completeJourneyVerification(pending.evidence.action_id!)
+    delete pending.verification_diagnostic
+    const delta = ToolsObserve.getLatestStateDelta(s.input.platform, s.deviceId)
+    if (delta) { pending.state_delta = delta; pending.state_delta_available = true }
+  }
+  s.pendingLightStep = null
+}
+function compactAssertion(result: ToolPayload, success: boolean) {
+  const errorCode = typeof result.error === 'object' ? result.error?.code : undefined
+  return { success, ...(result.failure_code ? { failure_code: result.failure_code } : {}),
+    ...(errorCode ? { failure_code: errorCode } : {}),
+    ...(result.observed?.matched_count !== undefined ? { matched_count: result.observed.matched_count } : {}),
+    ...(result.observed_fingerprint !== undefined ? { matched: success } : {}),
+    ...(result.actual_state ? { observed: result.actual_state } : {}) }
+}
+function coveredByAssertion(s: Context, step: Step, next?: Step) {
+  const verification = ('verificationMode' in step ? step.verificationMode : undefined) ?? s.input.defaults?.verificationMode ?? 'full'
+  return step.type === 'tap' && s.input.responseMode === 'compact' && verification === 'light' && next?.type === 'assert' && next.assertion.kind === 'element_visible'
+}
+async function runSteps(s: Context) {
+  const { platform, responseMode, steps } = s.input
+  for (let index = 0; index < steps.length; index++) {
+    const step = steps[index]
+    if (platform === 'android' && debuggerSessions.paused(s.deviceId)) {
+      s.results.push({ id: step.id, type: step.type, status: 'failed', success: false, result: { success: false, failure_code: 'DEBUGGER_PAUSED', dispatch_started: false, delivery_status: 'not_delivered' } })
+      s.stoppedAt = step.id
+      break
+    }
+    const covered = coveredByAssertion(s, step, steps[index + 1]), started = performance.now()
+    if (s.stoppedAt) {
+      s.results.push({ id: step.id, type: step.type, status: 'not_run', success: false, reason: 'PREVIOUS_STEP_FAILED', result: null, timing: { total_ms: 0 } })
+      continue
+    }
+    let result = await executeStep(s, step, covered)
+    if (platform === 'android' && debuggerSessions.paused(s.deviceId)) { result.success = false; result.failure_code = 'DEBUGGER_PAUSED'; result.retryable = false }
+    if (step.type === 'assert' && !result?.success && /TIMEOUT/.test(result?.failure_code ?? '')) result.failure_code = 'ASSERTION_TIMEOUT'
+    const success = !!result?.success
+    lightVerification(s, step, result, covered, success)
+    if (responseMode === 'compact' && ['wait', 'assert'].includes(step.type)) result = compactAssertion(result, success)
+    s.results.push({ id: step.id, type: step.type, status: success ? 'passed' : 'failed', success, result, timing: { total_ms: performance.now() - started } })
+    if (!success) s.stoppedAt = step.id
+  }
+}
+async function journeyResponse(s: Context, started: number, finishTrace?: () => Promise<unknown>) {
+  const { platform, captureOnFailure, responseMode } = s.input
+  const failureSnapshot = s.stoppedAt && captureOnFailure && responseMode === 'debug'
+    ? await ToolsObserve.captureDebugSnapshotHandler({ platform, deviceId: s.deviceId, includeScreenshot: false }).catch(() => null) : undefined
+  const timing: Record<string, number> = {}
+  for (const step of s.results) for (const [key, value] of Object.entries(step.result?.timing ?? {})) {
+    if (key !== 'total_ms' && typeof value === 'number') timing[key] = (timing[key] ?? 0) + value
+  }
+  refreshJourneyEvidence(s.results)
+  return wrapResponse({ ...(finishTrace ? { system_trace: await finishTrace() } : {}), success: s.stoppedAt === null, stopped_at_step_id: s.stoppedAt, steps: s.results, ...(failureSnapshot ? { failure_snapshot: failureSnapshot } : {}), timing: responseMode === 'compact' ? { total_ms: performance.now() - started } : { ...timing, total_ms: performance.now() - started } }, responseMode === 'debug')
+}
+export async function handleRunJourney(args: ToolCallArgs) {
+  const parsed = journeySchema.safeParse(args)
+  if (!parsed.success) throw new Error(`INVALID_ARGUMENT: ${parsed.error.message}`)
+  const device = await resolveTargetDevice({ platform: parsed.data.platform, deviceId: parsed.data.deviceId })
+  const finishTrace = parsed.data.systemTraceId ? await systemTraces.link(parsed.data.systemTraceId, device, currentEvidenceCorrelationId()!) : undefined
+  if (parsed.data.systemTraceId) bindSystemTrace(parsed.data.systemTraceId)
+  try {
+    return await withResolvedDevice(device, async () => {
+      const started = performance.now()
+      const state: Context = { input: parsed.data, deviceId: device.id, results: [], stoppedAt: null, pendingLightStep: null }
+      await runSteps(state)
+      return journeyResponse(state, started, finishTrace)
+    })
+  } finally { await finishTrace?.() }
+}

package/src/server/handlers/manage.ts

@@ -0,0 +1,141 @@
+import { measure } from '../../utils/timing.js'
+import { notifyActionStart } from '../../interact/conditional-action.js'
+import type {
+  InstallAppResponse,
+  ResetAppDataResponse,
+  TerminateAppResponse
+} from '../../types.js'
+import { AndroidManage, iOSManage, ToolsManage } from '../../manage/index.js'
+import {
+  buildActionExecutionResult,
+  captureActionFingerprint,
+  getNumberArg,
+  getStringArg,
+  inferGenericFailure,
+  requireStringArg,
+  ToolCallArgs,
+  wrapResponse
+} from '../common.js'
+import type { PlatformArg, ProjectTypeArg } from './handler-types.js'
+import { interactionControls, actionHandler } from './action-execution.js'
+
+export async function executeStartApp(args: ToolCallArgs) {
+  const platform = requireStringArg(args, 'platform') as PlatformArg
+  const appId = requireStringArg(args, 'appId')
+  const deviceId = getStringArg(args, 'deviceId')
+  const { verificationMode, actionTimeoutMs } = interactionControls(args)
+  const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null
+  notifyActionStart()
+  const res = await measure('dispatch_ms', () => (platform === 'android' ? new AndroidManage().startApp(appId, deviceId, actionTimeoutMs ?? (verificationMode === 'full' && getStringArg(args, 'responseMode') === undefined && args._journey !== true ? undefined : 10000)) : new iOSManage().startApp(appId, deviceId, verificationMode === 'full')))
+  const uiFingerprintAfter = verificationMode === 'full' ? await measure('post_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null
+  const result = buildActionExecutionResult({
+    actionType: 'start_app',
+    sourceModule: 'server',
+    device: res.device,
+    selector: { appId },
+    success: !!res.appStarted,
+    uiFingerprintBefore,
+    uiFingerprintAfter,
+    failure: res.appStarted ? undefined : inferGenericFailure(res.error),
+    details: {
+      launch_time_ms: res.launchTimeMs,
+      ...(typeof res.output === 'string' ? { output: res.output } : {}),
+      ...(res.device ? { device_id: res.device.id } : {}),
+      ...(typeof res.error === 'string' ? { error: res.error } : {}),
+      ...(res.diagnostics ? { diagnostics: res.diagnostics } : {}),
+      ...(res.observedApp ? { observed_app: res.observedApp } : {})
+    }
+  })
+  return wrapResponse(result)
+}
+
+export async function handleTerminateApp(args: ToolCallArgs) {
+  const platform = requireStringArg(args, 'platform') as PlatformArg
+  const appId = requireStringArg(args, 'appId')
+  const deviceId = getStringArg(args, 'deviceId')
+  const res = await (platform === 'android' ? new AndroidManage().terminateApp(appId, deviceId) : new iOSManage().terminateApp(appId, deviceId))
+  const response: TerminateAppResponse = { device: res.device, appTerminated: res.appTerminated }
+  return wrapResponse(response)
+}
+
+export async function executeRestartApp(args: ToolCallArgs) {
+  const platform = requireStringArg(args, 'platform') as PlatformArg
+  const appId = requireStringArg(args, 'appId')
+  const deviceId = getStringArg(args, 'deviceId')
+  const { verificationMode, actionTimeoutMs } = interactionControls(args)
+  const uiFingerprintBefore = verificationMode === 'full' ? await measure('pre_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null
+  notifyActionStart()
+  const bounded = args._journey === true || verificationMode !== 'full' || args.responseMode !== undefined || actionTimeoutMs !== undefined
+  const res = await measure('dispatch_ms', () => (platform === 'android' ? new AndroidManage().restartApp(appId, deviceId, bounded, actionTimeoutMs ?? 15000) : new iOSManage().restartApp(appId, deviceId, verificationMode === 'full', bounded, actionTimeoutMs ?? 15000)))
+  const uiFingerprintAfter = verificationMode === 'full' ? await measure('post_observation_ms', () => captureActionFingerprint(platform, deviceId)) : null
+  const result = buildActionExecutionResult({
+    actionType: 'restart_app',
+    sourceModule: 'server',
+    device: res.device,
+    selector: { appId },
+    success: !!res.appRestarted,
+    uiFingerprintBefore,
+    uiFingerprintAfter,
+    failure: res.appRestarted ? undefined : inferGenericFailure(res.error),
+    details: {
+      launch_time_ms: res.launchTimeMs,
+      ...(typeof res.output === 'string' ? { output: res.output } : {}),
+      ...(typeof res.terminatedBeforeRestart === 'boolean' ? { terminated_before_restart: res.terminatedBeforeRestart } : {}),
+      ...(typeof res.terminateError === 'string' ? { terminate_error: res.terminateError } : {}),
+      ...(typeof res.error === 'string' ? { error: res.error } : {}),
+      ...(res.diagnostics ? { diagnostics: res.diagnostics } : {}),
+      ...(res.observedApp ? { observed_app: res.observedApp } : {})
+    }
+  })
+  return wrapResponse(result)
+}
+
+export async function handleResetAppData(args: ToolCallArgs) {
+  const platform = requireStringArg(args, 'platform') as PlatformArg
+  const appId = requireStringArg(args, 'appId')
+  const deviceId = getStringArg(args, 'deviceId')
+  const res = await (platform === 'android' ? new AndroidManage().resetAppData(appId, deviceId) : new iOSManage().resetAppData(appId, deviceId))
+  const response: ResetAppDataResponse = { device: res.device, dataCleared: res.dataCleared }
+  return wrapResponse(response)
+}
+
+export async function handleInstallApp(args: ToolCallArgs) {
+  const platform = requireStringArg(args, 'platform') as PlatformArg
+  const projectType = requireStringArg(args, 'projectType') as ProjectTypeArg
+  const appPath = requireStringArg(args, 'appPath')
+  const deviceId = getStringArg(args, 'deviceId')
+  const res = await ToolsManage.installAppHandler({ platform, appPath, deviceId, projectType })
+  const response: InstallAppResponse = {
+    device: res.device,
+    installed: res.installed,
+    output: res.output,
+    error: res.error
+  }
+  return wrapResponse(response)
+}
+
+export async function handleBuildApp(args: ToolCallArgs) {
+  const platform = requireStringArg(args, 'platform') as PlatformArg
+  const projectType = requireStringArg(args, 'projectType') as ProjectTypeArg
+  const projectPath = requireStringArg(args, 'projectPath')
+  const variant = getStringArg(args, 'variant')
+  const res = await ToolsManage.buildAppHandler({ platform, projectPath, variant, projectType })
+  return wrapResponse(res)
+}
+
+export async function handleBuildAndInstall(args: ToolCallArgs) {
+  const platform = requireStringArg(args, 'platform') as PlatformArg
+  const projectType = requireStringArg(args, 'projectType') as ProjectTypeArg
+  const projectPath = requireStringArg(args, 'projectPath')
+  const deviceId = getStringArg(args, 'deviceId')
+  const timeout = getNumberArg(args, 'timeout')
+  const res = await ToolsManage.buildAndInstallHandler({ platform, projectPath, deviceId, timeout, projectType })
+  return {
+    content: [
+      { type: 'text' as const, text: res.ndjson },
+      { type: 'text' as const, text: JSON.stringify(res.result, null, 2) }
+    ]
+  }
+}
+export const handleStartApp = actionHandler('start_app', executeStartApp)
+export const handleRestartApp = actionHandler('restart_app', executeRestartApp)