Shared schemas

type A11yNode = {
  ref: string
  role: RoleOut
  name: string
  label?: string
  text?: string
  value?: string
  placeholder?: string
  testId?: string
  frame: Frame
  enabled: boolean
  selected: boolean
  focused: boolean
  visible: boolean
  checked?: boolean | 'mixed'
  expanded?: boolean
  pressed?: boolean
  level?: integer
  scrollable?: boolean
  hittable?: boolean
  native: NativeInfo
  children?: A11yNode[]
}

type ActionResult = { callId: string; durationMs: number; target?: { node: A11yNode; point: PointOut } }

type AppFormat = 'iosApp' | 'iosAppArchive' | 'apk' | 'expoProject' | 'catalystApp'

type AppFormatOut = 'iosApp' | 'iosAppArchive' | 'apk' | 'expoProject' | 'catalystApp' | …

type AppInfo = {
  bundleId: string
  name?: string
  version?: string
  build?: string
  state: AppStateOut
  pid?: integer
  installedBy: 'troupe' | 'preinstalled' | 'other' | …
}

type AppSource =
  | {
      path: string  // 2–4096 chars
    }
  | {
      url: string  // ≤ 8192 chars; url
      sha256: Sha256Hex
    }
  | { artifactId: ArtifactId }

type AppStateOut = 'notRunning' | 'background' | 'suspended' | 'foreground' | …

type Appearance = 'light' | 'dark'

type AppearanceOut = 'light' | 'dark' | …

type Arch = 'arm64' | 'x86_64'

type ArchOut = 'arm64' | 'x86_64' | …

type ArtifactId = string

type BundleId = string

type ButtonName = 'home' | 'back' | 'appSwitch' | 'power' | 'volumeUp' | 'volumeDown'

type ButtonNameOut = 'home' | 'back' | 'appSwitch' | 'power' | 'volumeUp' | 'volumeDown' | …

type Bytes = integer

type CodecOut = 'h264' | 'jpeg' | …

type ContractInfo = { version: string; majors: integer[] }

type CrashId = string

type CrashSummary = {
  crashId: CrashId
  bundleId?: string
  process: string
  pid?: integer
  at: string
  kind: 'crash' | 'anr' | 'jetsam' | 'watchdog' | 'sceneManifestMissing' | 'other' | …
  signal?: string
  exceptionType?: string
  reason?: string
  report: { status: 'pending' | 'attached' | 'unavailable' | …; file?: FileRef }
}

type Cursor = string

type DeviceId = string

type DeviceSpec = {
  platform: PlatformId
  deviceType?: string  // 1–128 chars
  os?: string  // 1–32 chars
  arch?: Arch
  variant?: string  // 1–64 chars
  locale?: string  // ≤ 35 chars; /^[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*$/
  timeZone?: string  // 1–64 chars
  orientation?: Orientation
  appearance?: Appearance
  labels?: Record<string, string>
}

type DeviceSpecOut = {
  platform: PlatformIdOut
  deviceType?: string
  os?: string
  arch?: ArchOut
  variant?: string
  locale?: string
  timeZone?: string
  orientation?: OrientationOut
  appearance?: AppearanceOut
  labels?: Record<string, string>
}

type DeviceType = {
  platform: PlatformIdOut
  id: string
  name: string
  formFactor: FormFactorOut
  screen: ScreenSize
  minOs?: string
  maxOs?: string
  default: boolean
}

type DoctorCheck = {
  id: 'host.platform' | 'disk.free' | 'ports.range' | 'gui.session' | 'xcode.selected' | 'xcode.license' | 'xcode.firstLaunch' | 'ios.runtimes' | 'ios.runner' | 'ios.deviceHub' | 'ios.home' | 'android.sdk' | 'android.emulator' | 'android.images' | 'android.adb' | 'android.driver' | 'catalyst.toolchain' | …
  platform?: PlatformIdOut
  status: 'pass' | 'warn' | 'fail' | 'skip' | …
  message: string
  error?: { code: string; data: { fix: string } }
}

type DurationMs = integer

type ElementRef = string

type ErrorBody = {
  code: ErrorCodeOut
  message: string
  data: JsonObject
  retryable: boolean
  requestId: string
}

type ErrorCodeOut = 'VALIDATION' | 'CONTRACT_UNSUPPORTED' | 'UNAUTHENTICATED' | 'FORBIDDEN' | 'NOT_FOUND' | 'CONFLICT' | 'TIMEOUT' | 'RATE_LIMITED' | 'INTERNAL' | 'CAPABILITY_UNSUPPORTED' | 'CAPACITY_UNAVAILABLE' | 'HOST_LOST' | 'SESSION_NOT_READY' | 'SESSION_ENDED' | 'SESSION_BUSY' | 'DEVICE_SPEC_INVALID' | 'DEVICE_BOOT_FAILED' | 'DEVICE_LOST' | 'DEVICE_DRIVER_FAILED' | 'DEVICE_MEDIA_FAILED' | 'DEVICE_INPUT_UNAVAILABLE' | 'APP_NOT_INSTALLED' | 'APP_NOT_RUNNING' | 'APP_INSTALL_FAILED' | 'APP_LAUNCH_FAILED' | 'APP_CRASHED' | 'LOCATOR_NOT_FOUND' | 'LOCATOR_NOT_ACTIONABLE' | 'LOCATOR_STRICT_VIOLATION' | 'LOCATOR_REF_STALE' | 'SECRET_UNAVAILABLE' | 'JS_RUNTIME_UNAVAILABLE' | 'QUOTA_EXCEEDED' | 'ORG_SUSPENDED' | 'PROJECT_SUSPENDED' | 'SERVICE_SUSPENDED' | 'PROJECT_REQUIRED' | 'PLACEMENT_MISMATCH' | 'ENVIRONMENT_HOST_UNSUPPORTED' | 'ENVIRONMENT_XCODE_MISSING' | 'ENVIRONMENT_XCODE_SETUP_INCOMPLETE' | 'ENVIRONMENT_IOS_RUNTIME_MISSING' | 'ENVIRONMENT_ANDROID_SDK_MISSING' | 'ENVIRONMENT_ANDROID_IMAGE_MISSING' | 'ENVIRONMENT_ADB_UNAVAILABLE' | 'ENVIRONMENT_DRIVER_NOT_INSTALLED' | 'ENVIRONMENT_TOOL_MISSING' | 'ENVIRONMENT_UNVERIFIED' | 'ENVIRONMENT_DEVICE_HUB_ACTIVE' | 'ENVIRONMENT_GUI_SESSION_MISSING' | 'ENVIRONMENT_PORTS_UNAVAILABLE' | 'ENVIRONMENT_RESERVED_RESOURCE' | 'ENVIRONMENT_DISK_LOW' | 'ENVIRONMENT_PLATFORM_DISABLED' | …

type FileId = string

type FileRef = {
  fileId: FileId
  name: string
  contentType: MediaType
  bytes: Bytes
  sha256: string
  expiresAt: string
}

type FormFactorOut = 'phone' | 'tablet' | 'desktop' | 'tv' | 'watch' | 'foldable' | …

type Frame = { x: number; y: number; width: number; height: number }

type HolderKind = 'test-worker' | 'client' | 'mcp' | 'api'

type HolderKindOut = 'test-worker' | 'client' | 'mcp' | 'api' | …

type HostInfo = {
  os: 'darwin' | 'linux' | 'win32' | …
  osVersion: string
  arch: ArchOut
  cpuCount: integer
  memoryBytes: Bytes
  freeDiskBytes: Bytes
  guiSession: boolean
  profile: 'developer' | 'shared' | …
  troupeHome: string
  toolchains: {
    xcode?: { path: string; version: string; build: string }
    androidSdk?: { root: string; emulatorVersion?: string; platformToolsVersion?: string }
  }
  limits: {
    platform: PlatformIdOut
    maxDevices: integer
    memoryBudgetBytes: Bytes
    deviceMemoryBytes?: Bytes
  }[]
}

type InstalledApp = {
  bundleId: string
  name?: string
  version?: string
  build?: string
  format: AppFormatOut
  sha256?: string
  urlSchemes: string[]
  installedAt: string
}

type JsRuntime = {
  state: 'connecting' | 'connected' | 'disconnected' | 'replaced' | …
  bundleId: string
  devServerUrl: string
  deviceName?: string
  title?: string
  multipleDebuggers?: boolean
  connectedAt?: string
  reconnects: integer
}

type JsonObject = Record<string, unknown>

type Label = string

type LeakItem = {
  kind: 'device' | 'avd' | 'process' | 'port' | …
  id: string
  owned: boolean
  action: 'report' | 'remove' | …
}

type Locator = {
  v: 1
  root?: LocatorRoot
  bundleId?: BundleId
  description?: string  // ≤ 200 chars
  steps: [LocatorStep, ...LocatorStep[]]
}

type LocatorOut = {
  v: 1
  root?: LocatorRootOut
  bundleId?: string
  description?: string
  steps: [LocatorStepOut, ...LocatorStepOut[]]
}

type LocatorRoot = 'app' | 'system' | 'all'

type LocatorRootOut = 'app' | 'system' | 'all' | …

type LocatorStep =
  | {
      by: 'role'
      role: Role
      name?: TextMatch
      checked?: boolean | 'mixed'
      disabled?: boolean
      expanded?: boolean
      selected?: boolean
      pressed?: boolean
      level?: integer  // 1–9
      includeHidden?: boolean
    }
  | { by: 'text'; match: TextMatch }
  | { by: 'label'; match: TextMatch }
  | { by: 'placeholder'; match: TextMatch }
  | { by: 'testId'; match: TextMatch }
  | {
      by: 'filter'
      hasText?: TextMatch
      hasNotText?: TextMatch
      has?: Locator
      hasNot?: Locator
      visible?: boolean
    }
  | {
      by: 'nth'
      index: integer  // -10000–10000
    }
  | { by: 'and'; locator: Locator }
  | { by: 'or'; locator: Locator }

type LocatorStepOut =
  | {
      by: 'role'
      role: RoleOut
      name?: TextMatchOut
      checked?: boolean | 'mixed'
      disabled?: boolean
      expanded?: boolean
      selected?: boolean
      pressed?: boolean
      level?: integer
      includeHidden?: boolean
    }
  | { by: 'text'; match: TextMatchOut }
  | { by: 'label'; match: TextMatchOut }
  | { by: 'placeholder'; match: TextMatchOut }
  | { by: 'testId'; match: TextMatchOut }
  | {
      by: 'filter'
      hasText?: TextMatchOut
      hasNotText?: TextMatchOut
      has?: LocatorOut
      hasNot?: LocatorOut
      visible?: boolean
    }
  | { by: 'nth'; index: integer }
  | { by: 'and'; locator: LocatorOut }
  | { by: 'or'; locator: LocatorOut }

type LogEvent =
  | {
      type: 'log'
      seq: Seq
      at: string
      source: LogSourceOut
      level: LogLevelOut
      bundleId?: string
      pid?: integer
      tag?: string
      message: string
    }
  | {
      type: 'gap'
      fromSeq: Seq
      toSeq: Seq
      dropped: integer  // ≥ 0
    }

type LogGap = {
  fromSeq: Seq
  toSeq: Seq
  dropped: integer  // ≥ 0
}

type LogLevel = 'debug' | 'info' | 'notice' | 'warn' | 'error' | 'fault'

type LogLevelOut = 'debug' | 'info' | 'notice' | 'warn' | 'error' | 'fault' | …

type LogLine = {
  seq: Seq
  at: string
  source: LogSourceOut
  level: LogLevelOut
  bundleId?: string
  pid?: integer
  tag?: string
  message: string
}

type LogSource = 'system' | 'app' | 'driver' | 'engine' | 'runtime' | 'js'

type LogSourceOut = 'system' | 'app' | 'driver' | 'engine' | 'runtime' | 'js' | …

type MediaType = string

type NativeInfo = { type: string; bundleId?: string; windowId?: string }

type NonNegativeInt = integer

type Orientation = 'portrait' | 'portraitUpsideDown' | 'landscapeLeft' | 'landscapeRight'

type OrientationOut = 'portrait' | 'portraitUpsideDown' | 'landscapeLeft' | 'landscapeRight' | …

type OsVersion = {
  platform: PlatformIdOut
  version: string
  build?: string
  id: string
  arch: string
  installed: boolean
  default: boolean
  installCommand?: string
}

type Pairing = {
  pairingId: PairingId
  origin: string
  scopes: RuntimeScopeOut[]
  createdAt: string
  expiresAt: string
  lastUsedAt?: string
}

type PairingId = string

type Permission = 'calendar' | 'camera' | 'contacts' | 'location' | 'locationAlways' | 'microphone' | 'motion' | 'notifications' | 'photos' | 'reminders'

type PermissionOut = 'calendar' | 'camera' | 'contacts' | 'location' | 'locationAlways' | 'microphone' | 'motion' | 'notifications' | 'photos' | 'reminders' | …

type PlatformCapabilities = {
  platform: PlatformIdOut
  deviceClass: 'virtual' | 'physical' | …
  os: {
    family: 'ios' | 'android' | 'macos' | …
    source: 'runtime' | 'systemImage' | 'host' | …
    selectable: boolean
  }
  install: { from: AppFormatOut[] }
  apps: {
    launchArgs: boolean
    launchEnv: boolean
    clearData: boolean
    openUrl: boolean
    permissions: PermissionOut[]
  }
  ui: {
    tree: boolean
    locators: ('role' | 'text' | 'label' | 'placeholder' | 'testId' | …)[]
    regex: boolean
    describeAt: boolean
    systemScope: boolean
    testIdAttributes: string[]
  }
  input: {
    touch: boolean
    semantic: boolean
    maxContacts: integer  // ≥ 0
    keyboard: 'none' | 'text' | 'keys' | …
    buttons: ButtonNameOut[]
    rotate: boolean
    hideKeyboard: boolean
  }
  media: { screenshot: boolean; recording: boolean; stream: StreamCapabilities | null }
  logs: { system: boolean; app: boolean; crashes: boolean }
  system: { location: boolean; appearance: boolean; clipboard: boolean; statusBar?: boolean }
}

type PlatformId = string

type PlatformIdOut = 'ios-simulator' | 'android-emulator' | 'catalyst' | 'ios-device' | 'android-device' | …

type Point = { x: number; y: number }

type PointOut = { x: number; y: number }

type ReactAtPoint = {
  components: { name: string; source?: { file: string; line: integer; column?: integer } }[]
  note?: string
}

type RecordingId = string

type ReporterEnvelope = { v: 1; runId: RunId; seq: Seq; at: Timestamp; method: ReporterMethod; params: JsonObject }

type ReporterEnvelopeOut = { v: 1; runId: RunId; seq: Seq; at: string; method: ReporterMethodOut; params: JsonObject }

type ReporterMethod = 'onBegin' | 'onTestBegin' | 'onStepBegin' | 'onStepEnd' | 'onStdOut' | 'onStdErr' | 'onError' | 'onTestEnd' | 'onEnd'

type ReporterMethodOut = 'onBegin' | 'onTestBegin' | 'onStepBegin' | 'onStepEnd' | 'onStdOut' | 'onStdErr' | 'onError' | 'onTestEnd' | 'onEnd' | …

type ResolvedDeviceSpec = {
  platform: PlatformIdOut
  deviceType: string
  deviceTypeName: string
  os: string
  osBuild?: string
  arch: ArchOut
  variant?: string
  locale: string
  timeZone: string
  orientation: OrientationOut
  appearance: AppearanceOut
}

type Role = 'alertdialog' | 'alert' | 'application' | 'button' | 'checkbox' | 'combobox' | 'dialog' | 'document' | 'generic' | 'group' | 'heading' | 'img' | 'keyboard' | 'link' | 'list' | 'listitem' | 'menu' | 'menuitem' | 'progressbar' | 'radio' | 'radiogroup' | 'searchbox' | 'slider' | 'spinbutton' | 'status' | 'switch' | 'tab' | 'tablist' | 'text' | 'textbox' | 'toolbar'

type RoleOut = 'alertdialog' | 'alert' | 'application' | 'button' | 'checkbox' | 'combobox' | 'dialog' | 'document' | 'generic' | 'group' | 'heading' | 'img' | 'keyboard' | 'link' | 'list' | 'listitem' | 'menu' | 'menuitem' | 'progressbar' | 'radio' | 'radiogroup' | 'searchbox' | 'slider' | 'spinbutton' | 'status' | 'switch' | 'tab' | 'tablist' | 'text' | 'textbox' | 'toolbar' | …

type RunDetail = RunSummary & { tests: (TestCaseSummary & { results: TestResultSummary[]; outcome?: TestOutcomeOut })[] }

type RunId = string

type RunStats = {
  expected: integer
  unexpected: integer
  flaky: integer
  skipped: integer
  errored: integer
}

type RunStatus = 'queued' | 'running' | 'passed' | 'failed' | 'errored' | 'timedOut' | 'canceled'

type RunStatusOut = 'queued' | 'running' | 'passed' | 'failed' | 'errored' | 'timedOut' | 'canceled' | …

type RunSummary = {
  runId: RunId
  status: RunStatusOut
  title?: string
  origin: 'local' | 'cloud' | …
  startedAt: string
  endedAt?: string
  projects: string[]
  shard?: Shard
  stats: RunStats
}

type RuntimeInstanceId = string

type RuntimeScope = 'runtime:read' | 'runtime:admin' | 'devices:read' | 'devices:acquire' | 'devices:drive' | 'apps:install' | 'apps:debug' | 'logs:read' | 'runs:read' | 'runs:report'

type RuntimeScopeOut = 'runtime:read' | 'runtime:admin' | 'devices:read' | 'devices:acquire' | 'devices:drive' | 'apps:install' | 'apps:debug' | 'logs:read' | 'runs:read' | 'runs:report' | …

type RuntimeStatus = {
  instanceId: RuntimeInstanceId
  version: string
  startedAt: string
  sessions: { live: NonNegativeInt; byHolderKind: Record<string, integer> }
  devices: {
    deviceId: DeviceId
    platform: PlatformIdOut
    name: string
    state: string
    sessionId?: SessionId
  }[]
  supervisors: {
    kind: 'driver' | 'engine' | 'emulator' | …
    deviceId: DeviceId
    state: string
    restarts: NonNegativeInt
    lastError?: string
  }[]
  governor: { level: 'normal' | 'warn' | 'critical' | …; availableBytes: Bytes; reserveBytes: Bytes }
  leaks: { unregisteredDevices: NonNegativeInt; strayProcesses: NonNegativeInt }
}

type ScreenSize = { width: number; height: number; scale: number }

type Seq = integer

type Session = {
  sessionId: SessionId
  status: SessionStatusOut
  reason?: SessionReasonOut
  error?: ErrorBody
  statusDetail?: string
  holder: { kind: HolderKindOut; label?: string }
  key?: string
  platform: PlatformIdOut
  spec: DeviceSpecOut
  resolved?: ResolvedDeviceSpec
  screen?: SessionScreen
  deviceId?: DeviceId
  attempt: integer  // ≥ 1
  createdAt: string
  readyAt?: string
  streamReadyAt?: string
  endedAt?: string
  expiresAt?: string
  maxEndsAt?: string
  installed?: InstalledApp[]
}

type SessionCreateHolder = { kind?: HolderKind; label?: Label }

type SessionEvent =
  | {
      seq: Seq
      at: string
      sessionId: SessionId
      type: 'status'
      status: SessionStatusOut
      previous?: SessionStatusOut
      reason?: SessionReasonOut
      error?: ErrorBody
    }
  | {
      seq: Seq
      at: string
      sessionId: SessionId
      type: 'appState'
      bundleId: string
      state: AppStateOut
      pid?: integer
    }
  | { seq: Seq; at: string; sessionId: SessionId; type: 'crash'; crash: CrashSummary }
  | {
      seq: Seq
      at: string
      sessionId: SessionId
      type: 'inputState'
      available: boolean
      reason?: string
    }
  | { seq: Seq; at: string; sessionId: SessionId; type: 'streamReady' }
  | { seq: Seq; at: string; sessionId?: SessionId; type: 'gap'; fromSeq: Seq; toSeq: Seq }

type SessionId = string

type SessionReasonOut = 'released' | 'queue-timeout' | 'app-install-failed' | 'boot-failed' | 'driver-failed' | 'environment' | 'host-lost' | 'start-timeout' | 'idle-timeout' | 'heartbeat-timeout' | 'max-duration' | 'runtime-shutdown' | 'device-lost' | 'host-pressure' | …

type SessionScreen = { width: number; height: number; scale: number; orientation: OrientationOut }

type SessionStatusOut = 'queued' | 'starting' | 'ready' | 'ended' | 'failed' | 'errored' | 'canceled' | …

type Sha256Hex = string

type Shard = { current: integer; total: integer }

type SnapshotId = string

type StreamCap = 'watch' | 'drive'

type StreamCapabilities = {
  codecs: CodecOut[]
  liveSettings: boolean
  keyframesShared: boolean
  touchTimestamps: boolean
}

type Target = { locator: Locator } | { ref: ElementRef; snapshotId?: SnapshotId } | { point: Point }

type TestAnnotation = { type: string; description?: string }

type TestCaseSummary = {
  testId: string
  projectName: string
  title: string
  titlePath: string[]
  location: TestLocation
  tags: string[]
  annotations: TestAnnotation[]
  expectedStatus: TestStatusOut
  retries: integer
  timeoutMs: integer
}

type TestLocation = { file: string; line: integer; column: integer }

type TestOutcomeOut = 'expected' | 'unexpected' | 'flaky' | 'skipped' | …

type TestResultSummary = {
  resultId: string
  status: TestStatusOut
  durationMs: number
  retry: integer
  sessionId?: SessionId
}

type TestStatusOut = 'passed' | 'failed' | 'timedOut' | 'skipped' | 'errored' | 'canceled' | …

type TextMatch =
  | {
      text: string  // ≤ 4096 chars
      exact?: boolean
    }
  | {
      regex: string  // ≤ 1024 chars
      flags?: string  // /^[ims]{0,3}$/
    }

type TextMatchOut = { text: string; exact?: boolean } | { regex: string; flags?: string }

type TimeoutMs = integer

type Timestamp = string

type TraceCapture = {
  screenshots?: 'off' | 'after' | 'beforeAfter'
  a11y?: 'off' | 'onFailure' | 'always'
  video?: boolean
  logs?: boolean
}

type TraceChunkId = string