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

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/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)