@mentra/engine 3.2.0-dev.217 → 3.2.0-dev.221

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentra/engine",
-  "version": "3.2.0-dev.217",
+  "version": "3.2.0-dev.221",
   "description": "Mentra Engine — miniapp registry, WebView bridge, and miniapp store",
   "main": "build/index.js",
   "react-native": "src/index.ts",
@@ -97,12 +97,12 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@mentra/acs-meeting": "3.2.0-dev.217",
-    "@mentra/bluetooth-sdk": "3.2.0-dev.217",
-    "@mentra/cloud-client": "3.2.0-dev.217",
-    "@mentra/cloud-protocol": "3.2.0-dev.217",
-    "@mentra/crust": "3.2.0-dev.217",
-    "@mentra/miniapp": "3.2.0-dev.217",
+    "@mentra/acs-meeting": "3.2.0-dev.221",
+    "@mentra/bluetooth-sdk": "3.2.0-dev.221",
+    "@mentra/cloud-client": "3.2.0-dev.221",
+    "@mentra/cloud-protocol": "3.2.0-dev.221",
+    "@mentra/crust": "3.2.0-dev.221",
+    "@mentra/miniapp": "3.2.0-dev.221",
     "buffer": "^6.0.3",
     "events": "^3.3.0",
     "react-native-marked": "8.1.1",

package/src/generated/releaseMetadata.ts

@@ -12,9 +12,9 @@ export interface EngineReleaseMetadata {
 export const ENGINE_RELEASE_METADATA: Readonly<EngineReleaseMetadata> = Object.freeze({
   "schemaVersion": 1,
   "familyBaseVersion": "3.2.0",
-  "releaseIdentity": "3.2.0-dev.217",
-  "releaseSetId": "mentra-3.2.0-dev.217",
-  "sourceCommit": "acd4336bcf67c5e2c7ddfa17ea1a2600dc7fb1d9",
-  "otaManifestUrl": "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.217.json",
-  "otaManifestSha256": "4ec6bf57ab08ef2749a58232737dface3b0ddb0d8269b61e134b7cb5986efa4a"
+  "releaseIdentity": "3.2.0-dev.221",
+  "releaseSetId": "mentra-3.2.0-dev.221",
+  "sourceCommit": "3837a3055e7a69e18553ce51c3a97579d2ad3b83",
+  "otaManifestUrl": "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.221.json",
+  "otaManifestSha256": "657e9616ad0c464ee57d827c05b53393e45559992c13b15adbb06e0c903eb870"
 })

package/src/index.ts

@@ -119,7 +119,13 @@ export {
 export type {OtaAutoChainAdvanceResult} from "./services/OtaAutoChain"
 export {
   BES_INSTALL_RESTART_MESSAGE,
+  OTA_ERROR_BES_RESTART_REQUIRED_COPY_KEY,
+  OTA_ERROR_ENGLISH_COPY,
+  OTA_ERROR_GENERIC_COPY_KEY,
+  OTA_ERROR_UNKNOWN_GLASSES_COPY_KEY,
+  OTA_GLASSES_ERROR_COPY_KEYS,
   getOtaErrorMessage,
+  otaErrorCopyKey,
   shouldRequireGlassesRebootForBesFailure,
   shouldShowChangeWifiForOtaDownloadFailure,
 } from "./services/OtaErrorMapping"

package/src/react/MentraLiveOtaFlow.tsx

@@ -14,10 +14,12 @@ import {useMarkdown, type MarkedStyles, type useMarkdownHookOptions} from "react
 import {SafeAreaView} from "react-native-safe-area-context"
 import Svg, {Path, Rect} from "react-native-svg"
 
+import {OTA_ERROR_ENGLISH_COPY} from "../services/OtaErrorMapping"
 import {
   MINIMUM_OTA_BATTERY_LEVEL,
   useMentraLiveOta,
   type MentraLiveOtaController,
+  type MentraLiveOtaError,
   type MentraLiveOtaFlowPage,
 } from "./useMentraLiveOta"
 
@@ -142,6 +144,8 @@ const ENGLISH_COPY: Record<string, string> = {
   "ota:versionChangeFirmwarePassComplete": "Firmware updated",
   "ota:versionChangeFirmwarePassCompleteMessage":
     "Your glasses restarted with new firmware. One more step: they'll now continue to the required version.",
+  "ota:updateFailed": "Update Failed",
+  ...OTA_ERROR_ENGLISH_COPY,
 }
 
 const componentCopyKey = {
@@ -150,8 +154,17 @@ const componentCopyKey = {
   bes: "ota:componentBes",
 } as const
 
+/**
+ * Copy for the failed screen: the translated copy key when the failure maps to one,
+ * otherwise the engine's English message (phone-side watchdog and preflight text).
+ */
+function failureMessage(error: MentraLiveOtaError | null, translate: MentraLiveOtaFlowTranslate): string {
+  if (!error) return translate("ota:errorGeneric")
+  return error.copyKey ? translate(error.copyKey) : error.message
+}
+
 function defaultTranslate(key: string, options?: Record<string, string>): string {
-  let value = ENGLISH_COPY[key] ?? key
+  let value = Object.prototype.hasOwnProperty.call(ENGLISH_COPY, key) ? ENGLISH_COPY[key] : key
   for (const [name, replacement] of Object.entries(options ?? {})) {
     value = value.replaceAll(`{{${name}}}`, replacement)
   }
@@ -559,8 +572,13 @@ function OtaFlowContent({
         }
         colors={colors}
         icon="alert"
-        title="Update Failed">
-        <BodyText colors={colors}>{state.error?.message}</BodyText>
+        title={translate("ota:updateFailed")}>
+        <BodyText colors={colors}>{failureMessage(state.error, translate)}</BodyText>
+        {state.error?.glassesCode ? (
+          <Text style={[styles.errorCode, {color: colors.textDim}]} testID="ota-error-code">
+            {translate("ota:errorCode", {code: state.error.glassesCode})}
+          </Text>
+        ) : null}
       </FlowPage>
     )
   }
@@ -810,6 +828,7 @@ const styles = StyleSheet.create({
   icon: {fontSize: 64, fontWeight: "500", lineHeight: 72, textAlign: "center"},
   title: {fontSize: 20, fontWeight: "600", textAlign: "center"},
   body: {fontSize: 14, lineHeight: 20, maxWidth: 420, textAlign: "center"},
+  errorCode: {fontSize: 12, fontVariant: ["tabular-nums"], lineHeight: 16, opacity: 0.7, textAlign: "center"},
   percent: {fontSize: 30, fontVariant: ["tabular-nums"], fontWeight: "700"},
   progressTrack: {borderRadius: 4, height: 8, maxWidth: 420, overflow: "hidden", width: "100%"},
   progressFill: {borderRadius: 4, height: 8},

package/src/react/useMentraLiveOta.ts

@@ -14,7 +14,9 @@ import {
 } from "../services/OtaAutoChain"
 import {
   BES_INSTALL_RESTART_MESSAGE,
+  OTA_ERROR_BES_RESTART_REQUIRED_COPY_KEY,
   getOtaErrorMessage,
+  otaErrorCopyKey,
   shouldRequireGlassesRebootForBesFailure,
   shouldShowChangeWifiForOtaDownloadFailure,
 } from "../services/OtaErrorMapping"
@@ -54,7 +56,19 @@ export type MentraLiveOtaErrorCode =
 
 export type MentraLiveOtaError = {
   code: MentraLiveOtaErrorCode
+  /** English copy for hosts without localization. */
   message: string
+  /**
+   * Copy key for `message` when the failure maps to known copy, so localized hosts can
+   * translate it. Null for phone-side watchdog and preflight messages, which are English-only.
+   * Optional so host code that builds this type by hand keeps compiling; the hook always sets it.
+   */
+  copyKey?: string | null
+  /**
+   * Raw failure code reported by the glasses (`ota_status.error`), for support. Null when the
+   * failure originated on the phone. Optional for the same source-compatibility reason.
+   */
+  glassesCode?: string | null
 }
 
 export type MentraLiveOtaTransport = "wifi" | "hotspot"
@@ -680,9 +694,16 @@ export function useMentraLiveOta(options: UseMentraLiveOtaOptions = {}): MentraL
         error = {
           code: "check_failed",
           message: "Couldn't check for updates. Please check your connection and try again.",
+          copyKey: "ota:checkFailedMessage",
+          glassesCode: null,
         }
       } else if (screen === "update_info_unavailable") {
-        error = {code: "update_info_unavailable", message: "Update information for this app version is unavailable."}
+        error = {
+          code: "update_info_unavailable",
+          message: "Update information for this app version is unavailable.",
+          copyKey: "ota:updateInfoUnavailableMessage",
+          glassesCode: null,
+        }
       }
       return {
         screen,
@@ -745,16 +766,33 @@ export function useMentraLiveOta(options: UseMentraLiveOtaOptions = {}): MentraL
       installSnapshot.otaProgress,
       installSnapshot.errorMsg,
     )
-    const displayedError = requiresGlassesReboot
-      ? BES_INSTALL_RESTART_MESSAGE
-      : installSnapshot.errorMsg || getOtaErrorMessage(installSnapshot.otaStatus?.error)
+    // The raw code the glasses attached to their failure report, kept for support even when
+    // phone-side copy outranks it. Only a failed ota_status carries a current code.
+    const glassesCode = installSnapshot.otaStatus?.status === "failed" ? installSnapshot.otaStatus.error || null : null
+    // Precedence mirrors the legacy screen: the BES restart instruction, then a phone-side
+    // watchdog/preflight message (English-only, no copy key), then the glasses code mapped to
+    // copy (unknown codes get the generic glasses-error copy rather than the raw code).
+    let displayedError: string
+    let copyKey: string | null
+    if (requiresGlassesReboot) {
+      displayedError = BES_INSTALL_RESTART_MESSAGE
+      copyKey = OTA_ERROR_BES_RESTART_REQUIRED_COPY_KEY
+    } else if (installSnapshot.errorMsg) {
+      displayedError = installSnapshot.errorMsg
+      copyKey = null
+    } else {
+      displayedError = getOtaErrorMessage(glassesCode)
+      copyKey = otaErrorCopyKey(glassesCode)
+    }
     const progressState = progressScreen(installSnapshot)
     const screen = progressState === "complete" && autoChainActive ? "finishing" : progressState
-    const error =
+    const error: MentraLiveOtaError | null =
       screen === "failed"
         ? {
-            code: requiresGlassesReboot ? ("bes_restart_required" as const) : ("install_failed" as const),
+            code: requiresGlassesReboot ? "bes_restart_required" : "install_failed",
             message: displayedError,
+            copyKey,
+            glassesCode,
           }
         : null
     const totalSteps = installSnapshot.otaStatus?.totalSteps ?? null

package/src/services/OtaErrorMapping.ts

@@ -1,7 +1,79 @@
 import type {OtaProgress, OtaStatus} from "../facades/ota"
 
-export const BES_INSTALL_RESTART_MESSAGE =
-  "Restart your glasses to safely exit firmware update mode before trying again"
+/**
+ * Copy keys for OTA failures the glasses report by code (`ota_status.error`), plus the
+ * phone-side BES restart instruction. Hosts translate these keys; the engine's own
+ * English copy for each key lives in `OTA_ERROR_ENGLISH_COPY`.
+ *
+ * The glasses-side producers are `sendProgressToPhone(..., "FAILED", errorCode)` in the
+ * ASG client's OtaHelper (download classification, install failures, and the downgrade
+ * handoff to the recovery worker). Keep this table in sync with those codes; anything
+ * else falls back to `OTA_ERROR_UNKNOWN_GLASSES_COPY_KEY` and the raw code is shown in a
+ * secondary line so support can still identify it.
+ */
+export const OTA_GLASSES_ERROR_COPY_KEYS: Readonly<Record<string, string>> = {
+  no_internet: "ota:errorNoInternet",
+  clock_skew: "ota:errorClockSkew",
+  ssl_error: "ota:errorSslError",
+  download_failed: "ota:errorDownloadFailed",
+  insufficient_storage: "ota:errorInsufficientStorage",
+  firmware_too_large: "ota:errorFirmwareTooLarge",
+  firmware_verify_failed: "ota:errorFirmwareVerifyFailed",
+  apk_verify_failed: "ota:errorApkVerifyFailed",
+  install_failed: "ota:errorInstallFailed",
+  apk_restart_guard_not_persisted: "ota:errorApkRestartGuardNotPersisted",
+  downgrade_handoff_refused: "ota:errorDowngradeHandoffRefused",
+  downgrade_handoff_failed: "ota:errorDowngradeHandoffFailed",
+  downgrade_transaction_stalled: "ota:errorDowngradeTransactionStalled",
+}
+
+export const OTA_ERROR_UNKNOWN_GLASSES_COPY_KEY = "ota:errorGlassesUnknown"
+export const OTA_ERROR_GENERIC_COPY_KEY = "ota:errorGeneric"
+export const OTA_ERROR_BES_RESTART_REQUIRED_COPY_KEY = "ota:errorBesRestartRequired"
+
+/** English copy for every OTA error key above. Mirrored in the Mentra App's `ota` i18n namespace. */
+export const OTA_ERROR_ENGLISH_COPY: Readonly<Record<string, string>> = {
+  "ota:errorNoInternet": "Glasses WiFi has no internet connection",
+  "ota:errorClockSkew": "Glasses clock is wrong — syncing time from your phone, then retrying update check",
+  "ota:errorSslError": "Secure connection failed — try a different WiFi network",
+  "ota:errorDownloadFailed": "Download failed — check glasses WiFi connection",
+  "ota:errorInsufficientStorage": "Not enough storage on your glasses — free up space before trying again",
+  "ota:errorFirmwareTooLarge": "Firmware file is unexpectedly large — please contact support",
+  "ota:errorFirmwareVerifyFailed": "Firmware verification failed — please try again or contact support",
+  "ota:errorApkVerifyFailed": "Update verification failed — please try again or contact support",
+  "ota:errorInstallFailed": "Install failed — please try again",
+  "ota:errorApkRestartGuardNotPersisted":
+    "Your glasses could not save the update before restarting. Restart your glasses and try again.",
+  "ota:errorDowngradeHandoffRefused":
+    "Your glasses could not start the version change. Restart your glasses and try again.",
+  "ota:errorDowngradeHandoffFailed":
+    "The recovery service on your glasses did not respond. Restart your glasses and try again.",
+  "ota:errorDowngradeTransactionStalled":
+    "The version change on your glasses did not finish. Restart your glasses and try again.",
+  "ota:errorGlassesUnknown": "Your glasses reported an unexpected error. Restart your glasses and try again.",
+  "ota:errorGeneric": "Update failed",
+  "ota:errorBesRestartRequired": "Restart your glasses to safely exit firmware update mode before trying again",
+  "ota:errorCode": "Error code: {{code}}",
+}
+
+export const BES_INSTALL_RESTART_MESSAGE = OTA_ERROR_ENGLISH_COPY[OTA_ERROR_BES_RESTART_REQUIRED_COPY_KEY]
+
+/**
+ * Copy key for a glasses-reported failure code. Unknown codes get the generic
+ * glasses-error copy; a missing code gets the plain generic copy.
+ */
+export function otaErrorCopyKey(error?: string | null): string {
+  if (!error) return OTA_ERROR_GENERIC_COPY_KEY
+  // Own-property lookup: a code that happens to name an inherited Object member
+  // ("constructor", "toString", ...) is unknown, not a mapped key.
+  return hasOwn(OTA_GLASSES_ERROR_COPY_KEYS, error)
+    ? OTA_GLASSES_ERROR_COPY_KEYS[error]
+    : OTA_ERROR_UNKNOWN_GLASSES_COPY_KEY
+}
+
+function hasOwn(table: Readonly<Record<string, string>>, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(table, key)
+}
 
 function isDownloadPhaseSnapshot(
   otaStatus: OtaStatus | null | undefined,
@@ -43,29 +115,9 @@ export function shouldShowChangeWifiForOtaDownloadFailure(
   return false
 }
 
-export function getOtaErrorMessage(error?: string): string {
-  switch (error) {
-    case "no_internet":
-      return "Glasses WiFi has no internet connection"
-    case "clock_skew":
-      return "Glasses clock is wrong — syncing time from your phone, then retrying update check"
-    case "ssl_error":
-      return "Secure connection failed — try a different WiFi network"
-    case "download_failed":
-      return "Download failed — check glasses WiFi connection"
-    case "insufficient_storage":
-      return "Not enough storage on your glasses — free up space before trying again"
-    case "firmware_too_large":
-      return "Firmware file is unexpectedly large — please contact support"
-    case "firmware_verify_failed":
-      return "Firmware verification failed — please try again or contact support"
-    case "apk_verify_failed":
-      return "Update verification failed — please try again or contact support"
-    case "install_failed":
-      return "Install failed — please try again"
-    default:
-      return error || "Update failed"
-  }
+/** English message for a glasses-reported failure code. Never echoes the raw code. */
+export function getOtaErrorMessage(error?: string | null): string {
+  return OTA_ERROR_ENGLISH_COPY[otaErrorCopyKey(error)]
 }
 
 /**

package/src/services/OtaInstallCoordinator.ts

@@ -853,7 +853,12 @@ class OtaInstallCoordinator {
       // suppress ota_start and hang the fresh downgrade until the global timeout).
       this.otaStartOwnership?.outcome === "acknowledged" &&
       otaStatus?.stepType === "apk" &&
-      otaStatus.phase === "install"
+      otaStatus.phase === "install" &&
+      // Only a live install arms the latch. A terminal failed status keeps stepType/phase
+      // apk/install and stays in the store, so without this gate every later pass (any
+      // unrelated store change) would re-arm the latch and the non-ownership block below
+      // would release it again, flooding the log with paired enter/release lines.
+      otaStatus.status === "in_progress"
     ) {
       console.log("[OTA_PROGRESS] version-change: apk install started — entering detour wait")
       this.versionChangeInstallStarted = true