@mentra/engine 0.1.0-beta.0

package/src/services/OtaService.ts

@@ -0,0 +1,83 @@
+/**
+ * OTA service — engine-owned. Subscribes to the glasses' OTA BLE events and projects
+ * them into the engine glasses store (otaStatus / otaProgress), so
+ * the OTA read surface works for ANY host — not just the first-party Mentra app, where
+ * these handlers used to live in MantleManager.
+ *
+ * This is the inbound projection half of `engine.ota` (read/observe). The install
+ * ORCHESTRATION (startOtaUpdate/poll/ping) is host-side for now — Phase 2 moves it here
+ * behind `engine.ota.{check,install,retry}` (bootloop-risk; needs on-device verification).
+ *
+ * Started by `engine.start()`. Idempotent.
+ */
+import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
+import type {OtaStatus} from "@mentra/bluetooth-sdk/internal"
+import GlobalEventEmitter from "../utils/GlobalEventEmitter"
+import {useGlassesStore} from "../stores/glasses"
+import {handleOtaClockSkewFromGlasses} from "./glassesClockSync"
+import {
+  legacyOtaProgressFromOtaStatusEvent,
+  normalizeOtaStatusEvent,
+  otaStatusFromNormalized,
+} from "./otaLegacyMapping"
+
+let subs: Array<{remove: () => void}> = []
+
+export function startOtaService(): void {
+  if (subs.length) return
+
+  // MTK firmware update finished (self power-cycle path).
+  subs.push(
+    BluetoothSdk.addListener("mtk_update_complete", (event) => {
+      GlobalEventEmitter.emit("mtk_update_complete", {message: event.message, timestamp: event.timestamp})
+    }),
+  )
+
+  // Glasses acknowledged the install start.
+  subs.push(
+    BluetoothSdk.addListener("ota_start_ack", (event) => {
+      GlobalEventEmitter.emit("ota_start_ack", {timestamp: event.timestamp})
+    }),
+  )
+
+  // Install progress / lifecycle. Updates both the new (otaStatus) and the legacy
+  // (otaProgress) store shapes; auto-fixes clock skew on the relevant failures.
+  subs.push(
+    BluetoothSdk.addListener("ota_status", (event) => {
+      const normalized = normalizeOtaStatusEvent(event as Record<string, unknown>)
+      const status: OtaStatus = otaStatusFromNormalized(normalized)
+      useGlassesStore.getState().setOtaStatus(status)
+      // Emit before legacy progress: setOtaProgress can throw (e.g. JSON.stringify in store);
+      // native logs would still show while RN UI would stay on "Starting update…".
+      GlobalEventEmitter.emit("ota_status", status)
+      try {
+        useGlassesStore.getState().setOtaProgress(legacyOtaProgressFromOtaStatusEvent(normalized))
+      } catch (err) {
+        console.warn("OTA: ota_status legacy otaProgress mapping failed", err)
+      }
+
+      if (status.status === "failed") {
+        const raw = event as Record<string, unknown>
+        const glassesTimeMs = Number(raw.glasses_time_ms ?? raw.glassesTimeMs ?? 0) || undefined
+        const errorCode = normalized.error_message
+        if (
+          errorCode === "clock_skew" ||
+          (errorCode === "ssl_error" && typeof glassesTimeMs === "number" && Number.isFinite(glassesTimeMs))
+        ) {
+          handleOtaClockSkewFromGlasses(errorCode, glassesTimeMs).catch((err: unknown) => {
+            console.warn("OTA: clock skew auto-fix failed", err)
+          })
+        }
+      }
+
+      if (status.status === "complete" || status.status === "failed") {
+        useGlassesStore.getState().setOtaUpdateAvailable(null)
+      }
+    }),
+  )
+}
+
+export function stopOtaService(): void {
+  subs.forEach((s) => s.remove())
+  subs = []
+}

package/src/services/OtaUpdateCheckService.ts

@@ -0,0 +1,386 @@
+import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
+import type {OtaUpdateInfo} from "@mentra/bluetooth-sdk/internal"
+import {getGlassesSystemTimeMs, isGlassesConnected, useGlassesStore, waitForGlassesState} from "../stores/glasses"
+import {maybeFixGlassesClockFromVersionInfo} from "./glassesClockSync"
+import {getAsgOtaVersionUrl} from "./asgOtaVersionUrl"
+
+export interface VersionInfo {
+  versionCode: number
+  versionName: string
+  downloadUrl: string
+  apkSize: number
+  sha256: string
+  releaseNotes: string
+  isRequired?: boolean
+}
+
+export interface MtkPatch {
+  start_firmware: string
+  end_firmware: string
+  url: string
+}
+
+export interface BesFirmware {
+  version: string
+  url: string
+}
+
+export interface VersionJson {
+  apps?: {
+    [packageName: string]: VersionInfo
+  }
+  mtk_patches?: MtkPatch[]
+  bes_firmware?: BesFirmware
+  versionCode?: number
+  versionName?: string
+  downloadUrl?: string
+  apkSize?: number
+  sha256?: string
+  releaseNotes?: string
+}
+
+export interface OtaCheckResult {
+  hasCheckCompleted: boolean
+  updateAvailable: boolean
+  latestVersionInfo: VersionInfo | null
+  updates: string[]
+  mtkPatch: MtkPatch | null
+  besVersion: string | null
+}
+
+export type OtaCheckSkippedReason = "disconnected" | "missing_build"
+
+export interface OtaCheckCurrentGlassesResult extends OtaCheckResult {
+  updateInfo: OtaUpdateInfo | null
+  isRequired: boolean
+  skippedReason?: OtaCheckSkippedReason
+  manifestUrl?: string
+  buildNumber?: string
+  mtkFirmwareVersion?: string
+  besFirmwareVersion?: string
+}
+
+export interface OtaCheckCurrentGlassesOptions {
+  waitForBuildNumberMs?: number
+  waitForBesVersionMs?: number
+  waitForMtkVersionMs?: number
+  refreshVersionInfo?: boolean
+  fixClockBeforeCheck?: boolean
+}
+
+function emptyCheckResult(skippedReason?: OtaCheckSkippedReason): OtaCheckCurrentGlassesResult {
+  return {
+    hasCheckCompleted: false,
+    updateAvailable: false,
+    latestVersionInfo: null,
+    updates: [],
+    mtkPatch: null,
+    besVersion: null,
+    updateInfo: null,
+    isRequired: true,
+    skippedReason,
+  }
+}
+
+function glassesConnectedNow(): boolean {
+  return isGlassesConnected(useGlassesStore.getState().connection)
+}
+
+export async function fetchVersionInfo(url: string): Promise<VersionJson | null> {
+  try {
+    const response = await fetch(url)
+    if (!response.ok) {
+      console.error("Failed to fetch version info:", response.status)
+      return null
+    }
+    return await response.json()
+  } catch (error) {
+    console.error("OTA: Error fetching version info:", error)
+    return null
+  }
+}
+
+export function checkVersionUpdateAvailable(
+  currentBuildNumber: string | undefined,
+  versionJson: VersionJson | null,
+): boolean {
+  if (!currentBuildNumber || !versionJson) {
+    return false
+  }
+
+  const currentVersion = parseInt(currentBuildNumber, 10)
+  if (isNaN(currentVersion)) {
+    return false
+  }
+
+  let serverVersion: number | undefined
+
+  if (versionJson.apps?.["com.mentra.asg_client"]) {
+    serverVersion = versionJson.apps["com.mentra.asg_client"].versionCode
+  } else if (versionJson.versionCode) {
+    serverVersion = versionJson.versionCode
+  }
+
+  if (!serverVersion || isNaN(serverVersion)) {
+    return false
+  }
+
+  return serverVersion > currentVersion
+}
+
+export function getLatestVersionInfo(versionJson: VersionJson | null): VersionInfo | null {
+  if (!versionJson) {
+    return null
+  }
+
+  if (versionJson.apps?.["com.mentra.asg_client"]) {
+    return versionJson.apps["com.mentra.asg_client"]
+  }
+
+  if (versionJson.versionCode) {
+    return {
+      versionCode: versionJson.versionCode,
+      versionName: versionJson.versionName || "",
+      downloadUrl: versionJson.downloadUrl || "",
+      apkSize: versionJson.apkSize || 0,
+      sha256: versionJson.sha256 || "",
+      releaseNotes: versionJson.releaseNotes || "",
+    }
+  }
+
+  return null
+}
+
+export function findMatchingMtkPatch(
+  patches: MtkPatch[] | undefined,
+  currentVersion: string | undefined,
+): MtkPatch | null {
+  if (!patches || !currentVersion) {
+    return null
+  }
+
+  return (
+    patches.find((patch) => {
+      if (patch.start_firmware === currentVersion) {
+        return true
+      }
+      const serverDate = patch.start_firmware.includes("_")
+        ? patch.start_firmware.split("_").pop()
+        : patch.start_firmware
+      return serverDate === currentVersion
+    }) || null
+  )
+}
+
+export function checkBesUpdate(besFirmware: BesFirmware | undefined, currentVersion: string | undefined): boolean {
+  if (!besFirmware) {
+    return false
+  }
+
+  if (!currentVersion) {
+    console.log(`📱 BES current version unknown - assuming update needed (server: ${besFirmware.version})`)
+    return true
+  }
+  return compareVersions(besFirmware.version, currentVersion) > 0
+}
+
+function compareVersions(version1: string, version2: string): number {
+  if (version1.includes(".") && version2.includes(".")) {
+    const parts1 = version1.split(".")
+    const parts2 = version2.split(".")
+    const maxLen = Math.max(parts1.length, parts2.length)
+
+    for (let i = 0; i < maxLen; i++) {
+      const v1 = i < parts1.length ? parseInt(parts1[i], 10) : 0
+      const v2 = i < parts2.length ? parseInt(parts2[i], 10) : 0
+      if (v1 !== v2) {
+        return v1 - v2
+      }
+    }
+    return 0
+  }
+
+  return version1.localeCompare(version2)
+}
+
+export async function checkForOtaUpdate(
+  otaVersionUrl: string,
+  currentBuildNumber: string,
+  currentMtkVersion?: string,
+  currentBesVersion?: string,
+): Promise<OtaCheckResult> {
+  try {
+    console.log("OTA: Checking for OTA update - URL: " + otaVersionUrl + ", current build: " + currentBuildNumber)
+    const versionJson = await fetchVersionInfo(otaVersionUrl)
+    const latestVersionInfo = getLatestVersionInfo(versionJson)
+
+    const apkUpdateAvailable = checkVersionUpdateAvailable(currentBuildNumber, versionJson)
+    console.log(`OTA: APK update available: ${apkUpdateAvailable} (current: ${currentBuildNumber})`)
+
+    const mtkPatch = findMatchingMtkPatch(versionJson?.mtk_patches, currentMtkVersion)
+    const mtkUpdateAvailable = mtkPatch !== null
+    if (!currentMtkVersion && versionJson?.mtk_patches?.length) {
+      console.log(`OTA: MTK current version unknown - skipping MTK patch check`)
+    }
+    console.log(
+      `OTA: MTK patch available: ${mtkUpdateAvailable ? "yes" : "no"} (current MTK: ${currentMtkVersion || "unknown"})`,
+    )
+
+    const besUpdateAvailable = checkBesUpdate(versionJson?.bes_firmware, currentBesVersion)
+    console.log(`OTA: BES update available: ${besUpdateAvailable} (current BES: ${currentBesVersion || "unknown"})`)
+
+    const updates: string[] = []
+    if (apkUpdateAvailable) updates.push("apk")
+    if (mtkUpdateAvailable) updates.push("mtk")
+    if (besUpdateAvailable) updates.push("bes")
+
+    console.log(`OTA: OTA check result - updates available: ${updates.length > 0}, updates: [${updates.join(", ")}]`)
+
+    return {
+      hasCheckCompleted: true,
+      updateAvailable: updates.length > 0,
+      latestVersionInfo,
+      updates,
+      mtkPatch,
+      besVersion: versionJson?.bes_firmware?.version || null,
+    }
+  } catch (error) {
+    console.error("Error checking for OTA update:", error)
+    return {
+      hasCheckCompleted: false,
+      updateAvailable: false,
+      latestVersionInfo: null,
+      updates: [],
+      mtkPatch: null,
+      besVersion: null,
+    }
+  }
+}
+
+export async function checkCurrentGlassesForUpdate(
+  options: OtaCheckCurrentGlassesOptions = {},
+): Promise<OtaCheckCurrentGlassesResult> {
+  const {
+    waitForBuildNumberMs = 0,
+    waitForBesVersionMs = 5000,
+    waitForMtkVersionMs = 2000,
+    refreshVersionInfo = true,
+    fixClockBeforeCheck = true,
+  } = options
+
+  if (!glassesConnectedNow()) {
+    return emptyCheckResult("disconnected")
+  }
+
+  if (refreshVersionInfo) {
+    void BluetoothSdk.requestVersionInfo().catch((error) => {
+      console.warn("OTA: Failed to request version_info from glasses:", error)
+    })
+  }
+
+  let buildNumber = useGlassesStore.getState().buildNumber
+  if (!buildNumber && waitForBuildNumberMs > 0) {
+    await waitForGlassesState("buildNumber", (value) => !!value, waitForBuildNumberMs)
+    buildNumber = useGlassesStore.getState().buildNumber
+  }
+
+  if (!buildNumber) {
+    return emptyCheckResult("missing_build")
+  }
+
+  if (!glassesConnectedNow()) {
+    return emptyCheckResult("disconnected")
+  }
+
+  let besFirmwareVersion = useGlassesStore.getState().besFirmwareVersion
+  if (!besFirmwareVersion && waitForBesVersionMs > 0) {
+    console.log("OTA: BES version still unknown - waiting up to 5s for it to arrive...")
+    await waitForGlassesState("besFirmwareVersion", (value) => !!value, waitForBesVersionMs)
+    besFirmwareVersion = useGlassesStore.getState().besFirmwareVersion
+    if (besFirmwareVersion) {
+      console.log(`OTA: BES version arrived: ${besFirmwareVersion}`)
+    } else {
+      console.log("OTA: BES version still unknown after extended wait - will assume BES update if published")
+    }
+  }
+
+  if (!glassesConnectedNow()) {
+    return emptyCheckResult("disconnected")
+  }
+
+  let mtkFirmwareVersion = useGlassesStore.getState().mtkFirmwareVersion
+  if (!mtkFirmwareVersion && waitForMtkVersionMs > 0) {
+    await waitForGlassesState("mtkFirmwareVersion", (value) => !!value, waitForMtkVersionMs)
+    mtkFirmwareVersion = useGlassesStore.getState().mtkFirmwareVersion
+  }
+
+  if (!glassesConnectedNow()) {
+    return emptyCheckResult("disconnected")
+  }
+
+  if (fixClockBeforeCheck) {
+    const systemTimeMs = getGlassesSystemTimeMs()
+    await maybeFixGlassesClockFromVersionInfo(systemTimeMs > 0 ? systemTimeMs : undefined).catch((error) => {
+      console.warn("OTA: clock fix attempt failed; continuing OTA check", error)
+    })
+  }
+
+  const manifestUrl = getAsgOtaVersionUrl(useGlassesStore.getState().otaVersionUrl, buildNumber)
+  const result = await checkForOtaUpdate(manifestUrl, buildNumber, mtkFirmwareVersion, besFirmwareVersion)
+
+  if (!result.hasCheckCompleted) {
+    return {
+      ...result,
+      updateInfo: null,
+      isRequired: true,
+      manifestUrl,
+      buildNumber,
+      mtkFirmwareVersion,
+      besFirmwareVersion,
+    }
+  }
+
+  const mtkUpdatedThisSession = useGlassesStore.getState().mtkUpdatedThisSession
+  let filteredUpdates = result.updates
+  if (mtkUpdatedThisSession && filteredUpdates.includes("mtk")) {
+    console.log("OTA: Filtering out MTK - already updated this session (pending reboot)")
+    filteredUpdates = filteredUpdates.filter((update) => update !== "mtk")
+  }
+
+  // Pre-migration parity: an update is only surfaced when the manifest also
+  // carries APK version metadata. A firmware-only manifest (mtk_patches /
+  // bes_firmware with no APK entry) is therefore dropped here — same as the
+  // legacy host check. Loud-log it so the case is visible in the field;
+  // surfacing firmware-only updates is a deliberate behavior change to make
+  // separately, not silently inside the boundary migration.
+  if (filteredUpdates.length > 0 && !result.latestVersionInfo) {
+    console.warn(
+      `OTA: manifest lists updates [${filteredUpdates.join(", ")}] but has no APK version metadata - ` +
+        "reporting no update (legacy behavior)",
+    )
+  }
+  const updateAvailable = filteredUpdates.length > 0 && !!result.latestVersionInfo
+  const updateInfo = updateAvailable
+    ? {
+        available: true,
+        versionCode: result.latestVersionInfo?.versionCode || 0,
+        versionName: result.latestVersionInfo?.versionName || "",
+        updates: filteredUpdates,
+        totalSize: 0,
+      }
+    : null
+
+  useGlassesStore.getState().setOtaUpdateAvailable(updateInfo)
+
+  return {
+    ...result,
+    updateAvailable,
+    updates: filteredUpdates,
+    updateInfo,
+    isRequired: result.latestVersionInfo?.isRequired !== false,
+    manifestUrl,
+    buildNumber,
+    mtkFirmwareVersion,
+    besFirmwareVersion,
+  }
+}

package/src/services/PairingIdentity.ts

@@ -0,0 +1,154 @@
+/**
+ * PairingIdentity — the pairing-identity lifecycle, reified. The two-phase
+ * identity rules (see the pending/default group in stores/settings.ts) exist
+ * as a three-state machine over the identity settings keys:
+ *
+ *   none ──markPendingSelection()──▶ pending ──native promotion──▶ paired
+ *                                       ▲                            │
+ *                                       └───────boot demotion────────┘
+ *
+ * - `none`    — no model ever selected: hosts route to model selection.
+ * - `pending` — a model was CHOSEN (the one JS-owned identity write, made at
+ *               scan entry) but pairing never completed: hosts render
+ *               finish-pairing affordances.
+ * - `paired`  — the native layer promoted the identity at pairing success
+ *               (handleDeviceReady) and echoed it down via save_setting:
+ *               hosts render the device card / connect surfaces.
+ *
+ * Projection law, mirroring native currentDefaultDevice() on both platforms:
+ * `paired` requires default_wearable AND device_name; device_address is
+ * optional. Two read-time alignments with the demotion's own write rules:
+ * - The simulated device is its own identity (its name mirrors the model at
+ *   connectSimulated, and the boot demotion never touches it), so a simulated
+ *   default_wearable projects as `paired` even without a device_name echo.
+ * - A non-simulated default_wearable WITHOUT a device_name is the orphan
+ *   population `demoteOrphanedDefaultWearable` repairs into pending_wearable
+ *   at boot; the projection already reads it as `pending` (a fresher
+ *   pending_wearable wins, matching the demotion's latest-selection-wins
+ *   backfill).
+ *
+ * JS-initiated identity writes live here and only here — the scan screen
+ * (markPendingSelection), the device-event router (promotion retires the
+ * pending marker), and the boot demotion (demoteDefaultToPending) invoke
+ * these methods instead of writing the raw keys. The router's generic
+ * save_setting persistence is the inbound native→JS echo leg, not a
+ * JS-initiated write, and stays with the router.
+ */
+import {result as Res, type AsyncResult} from "typesafe-ts"
+
+import {useSettingsStore, SETTINGS} from "../stores/settings"
+import {DeviceTypes} from "../types"
+
+export type IdentitySnapshot =
+  | {kind: "none"}
+  | {kind: "pending"; model: string}
+  | {kind: "paired"; model: string; name: string; address?: string}
+
+// Identity keys hold model/name strings; anything else (legacy null, a stray
+// non-string) reads as absent, matching native currentDefaultDevice()'s
+// blank checks.
+function readIdentityString(key: string): string {
+  const value = useSettingsStore.getState().getSetting(key)
+  return typeof value === "string" ? value : ""
+}
+
+/** Project the identity settings keys into the lifecycle snapshot. */
+export function projectPairingIdentity(): IdentitySnapshot {
+  const model = readIdentityString(SETTINGS.default_wearable.key)
+  const name = readIdentityString(SETTINGS.device_name.key)
+
+  if (model && name) {
+    const address = readIdentityString(SETTINGS.device_address.key)
+    return address ? {kind: "paired", model, name, address} : {kind: "paired", model, name}
+  }
+  if (model && model.includes(DeviceTypes.SIMULATED)) {
+    return {kind: "paired", model, name: model}
+  }
+  const pending = readIdentityString(SETTINGS.pending_wearable.key)
+  if (pending) return {kind: "pending", model: pending}
+  if (model) return {kind: "pending", model}
+  return {kind: "none"}
+}
+
+/**
+ * Subscribe to identity changes, deduped on the projected snapshot (same
+ * style as glasses.onStatus): the settings store updates on many keys; the
+ * callback fires only when the identity snapshot actually changes.
+ */
+export function subscribePairingIdentity(cb: (identity: IdentitySnapshot) => void): () => void {
+  let last = JSON.stringify(projectPairingIdentity())
+  return useSettingsStore.subscribe(() => {
+    const snap = projectPairingIdentity()
+    const key = JSON.stringify(snap)
+    if (key === last) return
+    last = key
+    cb(snap)
+  })
+}
+
+/**
+ * Selection: mark the model the user chose as the PENDING wearable (written
+ * at scan entry). Promotion to `paired` only ever happens natively at pairing
+ * success. The marker persists so an abandoned selection still renders its
+ * finish-pairing card after an app restart.
+ */
+export function markPendingSelection(model: string): AsyncResult<void, Error> {
+  // Guard the public write-path: an empty/whitespace model would persist a
+  // pending identity that renders a blank finish-pairing card.
+  const trimmed = typeof model === "string" ? model.trim() : ""
+  if (!trimmed) {
+    console.warn(`PairingIdentity: ignoring pending selection with empty model (got ${JSON.stringify(model)})`)
+    return Res.try_async(async () => {})
+  }
+  console.log(`PairingIdentity: pending selection -> "${trimmed}"`)
+  const result = useSettingsStore.getState().setSetting(SETTINGS.pending_wearable.key, trimmed)
+  // setSetting resolves to a Result (never rejects); a persist failure would
+  // silently drop the finish-pairing affordance on restart — surface it.
+  void Promise.resolve(result).then((r) => {
+    if (r.is_error()) console.warn("PairingIdentity: pending selection failed to persist:", r.error)
+  })
+  return result
+}
+
+/**
+ * Promotion retires the selection: when the native layer promotes the default
+ * wearable at pairing success and its save_setting echo lands, the pending
+ * marker has served its purpose. Invoked by DeviceEventRouter for every echo;
+ * a no-op for other keys, empty promotions, and an already-clear marker.
+ */
+export async function retirePendingSelectionOnPromotion(echoedKey: string, echoedValue: unknown): Promise<void> {
+  if (echoedKey !== SETTINGS.default_wearable.key || !echoedValue) return
+  const settings = useSettingsStore.getState()
+  const pending = settings.getSetting(SETTINGS.pending_wearable.key)
+  if (pending) {
+    console.log(`PairingIdentity: promotion "${String(echoedValue)}" retires pending "${pending}"`)
+    await settings.setSetting(SETTINGS.pending_wearable.key, "")
+  }
+}
+
+/**
+ * Demotion: turn an orphaned default identity back into a pending selection.
+ * The guards (hydration, the native default-device read, link-layer state)
+ * live with the boot repair in demoteOrphanedDefaultWearable — this is only
+ * the identity write set: backfill the pending marker unless a fresher
+ * selection already holds it (the user's LATEST selection wins), then clear
+ * the promoted identity triplet.
+ */
+export async function demoteDefaultToPending(model: string): Promise<void> {
+  const settings = useSettingsStore.getState()
+  // readIdentityString, not raw getSetting: a truthy non-string legacy value
+  // must read as absent here too, or the orphaned model is never backfilled
+  // while the projection reads the same junk as no pending at all.
+  const fresher = readIdentityString(SETTINGS.pending_wearable.key)
+  console.log(
+    fresher
+      ? `PairingIdentity: demote "${model}" — fresher pending "${fresher}" kept`
+      : `PairingIdentity: demote "${model}" -> pending`,
+  )
+  if (!fresher) {
+    await settings.setSetting(SETTINGS.pending_wearable.key, model)
+  }
+  await settings.setSetting(SETTINGS.default_wearable.key, "")
+  await settings.setSetting(SETTINGS.device_name.key, "")
+  await settings.setSetting(SETTINGS.device_address.key, "")
+}