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

package/src/services/MentraJSLogPipeline.ts

@@ -73,6 +73,34 @@ export interface ThrottleOptions {
   now?: () => number
 }
 
+/** A per-package override of the shared budget. Both fields are absolute, not multipliers. */
+export interface PackageLogBudget {
+  tokensPerSecond: number
+  bucketCapacity: number
+}
+
+/**
+ * Budgets for miniapps under active diagnosis.
+ *
+ * The default ceiling protects the host from a miniapp that logs in a render loop, and it is the
+ * right default. It is the wrong ceiling for a miniapp someone is actively debugging: a single
+ * instrumented call join emits several hundred lines in its first few seconds, which exhausts the
+ * burst and then drops everything that follows — and the drops land exactly where the interesting
+ * part is. A log with silent holes in the failure window is worse than no log, because it is read
+ * as complete.
+ *
+ * So the ceiling is raised for named packages rather than lowered for everyone. Anything not
+ * listed here keeps the protective default.
+ */
+export const DIAGNOSTIC_LOG_BUDGETS: Readonly<Record<string, PackageLogBudget>> = {
+  // Mentra Call is instrumented end to end — UI, background, and the host call path — so the
+  // whole of a join, a cancel, and a teardown can be read back from one capture.
+  "com.mentra.call": {tokensPerSecond: 200, bucketCapacity: 5_000},
+}
+
+/** Ring-buffer window for a package in {@link DIAGNOSTIC_LOG_BUDGETS}. See `capacityFor`. */
+export const DIAGNOSTIC_RING_CAPACITY = 2_000
+
 interface PackageBucket {
   tokens: number
   lastRefillAtMs: number
@@ -85,6 +113,7 @@ export class MentraJSLogThrottle {
   private readonly bucketCapacity: number
   private readonly now: () => number
   private readonly buckets: Map<string, PackageBucket> = new Map()
+  private readonly budgets: Map<string, PackageLogBudget> = new Map(Object.entries(DIAGNOSTIC_LOG_BUDGETS))
 
   constructor(opts: ThrottleOptions = {}) {
     this.tokensPerSecond = opts.tokensPerSecond ?? 100 / 60
@@ -92,6 +121,29 @@ export class MentraJSLogThrottle {
     this.now = opts.now ?? (() => Date.now())
   }
 
+  /**
+   * Raise (or lower) one package's budget at runtime.
+   *
+   * Exists so a support session can widen the pipe for the miniapp being investigated without a
+   * rebuild, and so tests can exercise a budget without depending on the shipped table.
+   */
+  setPackageBudget(packageName: string, budget: PackageLogBudget | null): void {
+    if (budget) this.budgets.set(packageName, budget)
+    else this.budgets.delete(packageName)
+    // The bucket holds a capacity snapshot, so a stale one would keep enforcing the old ceiling
+    // until it happened to refill. Dropping it re-derives from the new budget on the next line.
+    this.buckets.delete(packageName)
+  }
+
+  private budgetFor(packageName: string): PackageLogBudget {
+    return (
+      this.budgets.get(packageName) ?? {
+        tokensPerSecond: this.tokensPerSecond,
+        bucketCapacity: this.bucketCapacity,
+      }
+    )
+  }
+
   /**
    * Try to consume one token for the named package. Returns either:
    *   - `{allowed: true}` — caller emits the original log line.
@@ -102,17 +154,18 @@ export class MentraJSLogThrottle {
    */
   consume(packageName: string): {allowed: true} | {allowed: false; throttledLine?: string} {
     const at = this.now()
+    const budget = this.budgetFor(packageName)
     let bucket = this.buckets.get(packageName)
     if (!bucket) {
       bucket = {
-        tokens: this.bucketCapacity,
+        tokens: budget.bucketCapacity,
         lastRefillAtMs: at,
         pendingDrops: 0,
       }
       this.buckets.set(packageName, bucket)
     } else {
       const elapsedSec = (at - bucket.lastRefillAtMs) / 1000
-      bucket.tokens = Math.min(this.bucketCapacity, bucket.tokens + elapsedSec * this.tokensPerSecond)
+      bucket.tokens = Math.min(budget.bucketCapacity, bucket.tokens + elapsedSec * budget.tokensPerSecond)
       bucket.lastRefillAtMs = at
     }
     if (bucket.tokens >= 1) {
@@ -146,6 +199,19 @@ export class MentraJSLogRingBuffer {
     this.capacity = capacityPerPackage
   }
 
+  /**
+   * Capacity for a package under diagnosis.
+   *
+   * This buffer is the miniapp's last words in a crash report, and 200 lines of a heavily
+   * instrumented miniapp is a couple of seconds — so the report would arrive holding the
+   * aftermath and none of the cause. A package with a raised log budget needs a window long
+   * enough to contain whatever produced the crash.
+   */
+  private capacityFor(packageName: string): number {
+    const budget = DIAGNOSTIC_LOG_BUDGETS[packageName]
+    return budget ? Math.max(this.capacity, DIAGNOSTIC_RING_CAPACITY) : this.capacity
+  }
+
   push(packageName: string, line: string): void {
     let buf = this.buffers.get(packageName)
     if (!buf) {
@@ -153,7 +219,8 @@ export class MentraJSLogRingBuffer {
       this.buffers.set(packageName, buf)
     }
     buf.push(line)
-    if (buf.length > this.capacity) buf.shift()
+    const capacity = this.capacityFor(packageName)
+    while (buf.length > capacity) buf.shift()
   }
 
   snapshot(packageName: string): string[] {

package/src/services/MentraJSRouter.ts

@@ -379,9 +379,9 @@ export class MentraJSRouter {
    * router gates this to registered packages and keeps LocalMiniappView from
    * reaching into runtime internals.
    */
-  probeForegroundLiveness(packageName: string, reason = "foreground-open"): void {
+  probeForegroundLiveness(packageName: string, reason = "foreground-open", timeoutMs?: number): void {
     if (!this.registered.has(packageName)) return
-    this.runtime.probeForegroundLiveness(packageName, reason)
+    this.runtime.probeForegroundLiveness(packageName, reason, timeoutMs)
   }
 
   // ----------------------------------------------------------------

package/src/services/MicStateCoordinator.ts

@@ -48,6 +48,14 @@ class MicStateCoordinator {
   // Local miniapp requirements (set when miniapps subscribe to audio streams)
   private localWantsPcm = false
   private localWantsLc3 = false
+  /**
+   * A live ACS call taking the wearer's voice off the glasses over BLE LC3.
+   *
+   * Tracked separately from the miniapp requirement because the two have independent lifetimes:
+   * the call miniapp does not subscribe to `audio_chunk`, and a captions miniapp that stops mid-call
+   * must not take the call's microphone with it.
+   */
+  private callWantsPcm = false
   private configuredVad: boolean | undefined
   private configuredLoudnessGate: boolean | undefined
   private readonly miniappVadOverrides = new Map<string, GateOverride>()
@@ -75,6 +83,29 @@ class MicStateCoordinator {
     this.applyUnion()
   }
 
+  /**
+   * Claim or release raw PCM on behalf of an active call.
+   *
+   * Called by AcsMeetingService around a call whose uplink is the glasses microphone over BLE LC3.
+   * Releasing is a claim release, not a mic shutdown: if a captions miniapp still wants PCM the
+   * microphone stays on, which is the whole reason this is a separate flag rather than a setter on
+   * the local requirement.
+   */
+  public setCallRequirement(pcm: boolean): void {
+    if (this.callWantsPcm === pcm) return
+    this.callWantsPcm = pcm
+    console.log(`${LOG_TAG}: call requirement updated — pcm=${pcm}`)
+    this.applyUnion()
+  }
+
+  /**
+   * Whether anything on this device needs a continuous raw-PCM timeline. Also the condition that
+   * forces hardware VAD off: a gate that drops silence turns a call into clipped half-words.
+   */
+  private get wantsRawPcm(): boolean {
+    return this.localWantsPcm || this.callWantsPcm
+  }
+
   /**
    * Apply a miniapp-owned gate override without changing the OS preference.
    * Overrides are lifecycle-scoped and last-live-owner-wins independently for
@@ -159,7 +190,7 @@ class MicStateCoordinator {
     const vadOverride = this.latestOverride(this.miniappVadOverrides)
     const loudnessOverride = this.latestOverride(this.miniappLoudnessGateOverrides)
 
-    if (this.localWantsPcm) {
+    if (this.wantsRawPcm) {
       runtimeSettings.voice_activity_detection_enabled = false
     } else if (vadOverride) {
       runtimeSettings.voice_activity_detection_enabled = vadOverride.enabled
@@ -176,7 +207,7 @@ class MicStateCoordinator {
    * on-device PCM consumers; cloud audio uses LC3 through AudioCloudUplink.
    */
   private applyUnion(): void {
-    const shouldSendPcm = this.localWantsPcm
+    const shouldSendPcm = this.wantsRawPcm
     const shouldSendLc3 = this.localWantsLc3
 
     // console.log(
@@ -225,7 +256,7 @@ class MicStateCoordinator {
 
     // Hardware VAD suppresses silence. Raw-audio consumers need a continuous
     // timeline, so their requirement wins over both OS and miniapp VAD values.
-    if (this.localWantsPcm) patch.voice_activity_detection_enabled = false
+    if (this.wantsRawPcm) patch.voice_activity_detection_enabled = false
     else if (vadOverride) patch.voice_activity_detection_enabled = vadOverride.enabled
     else if (this.configuredVad !== undefined) patch.voice_activity_detection_enabled = this.configuredVad
 
@@ -243,6 +274,7 @@ class MicStateCoordinator {
   public reset(): void {
     this.localWantsPcm = false
     this.localWantsLc3 = false
+    this.callWantsPcm = false
     this.applyUnion()
   }
 

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

package/src/services/PhoneStreamCoordinator.ts

@@ -102,6 +102,14 @@ export interface StartUnmanagedOptions {
   /** Optional Bearer token for WHIP Authorization (custom authenticated endpoints). */
   authToken?: string
   captureAudio?: boolean
+  /**
+   * ICE configuration for the glasses' publisher. SoftAP passes `{stun: ""}`, which puts the
+   * glasses in host-only mode: there is no route from the hotspot to a STUN server, so a
+   * configured one would only add doomed gathering to every call.
+   */
+  ice?: StreamStartRequest["ice"]
+  /** Correlation id echoed by the glasses into their own logs. See softapTrace. */
+  traceId?: string
 }
 
 export interface StartManagedOptions {
@@ -364,6 +372,8 @@ export class PhoneStreamCoordinator {
           ...(opts.audio !== undefined ? {audio: opts.audio} : {}),
           ...(opts.authToken ? {authToken: opts.authToken} : {}),
           ...(typeof opts.captureAudio === "boolean" ? {captureAudio: opts.captureAudio} : {}),
+          ...(opts.ice !== undefined ? {ice: opts.ice} : {}),
+          ...(opts.traceId ? {traceId: opts.traceId} : {}),
         })
         const result = publisherStartResult(streamId, event)
         this.startLifecycle(streamId)