@mentra/engine 3.2.0-dev.116 → 3.2.0-dev.120

package/build/services/PhoneStreamCoordinator.js

@@ -26,6 +26,18 @@
  * streams. We use a `phone-` prefix so they're trivially distinguishable from
  * cloud-minted IDs in logs and from cloud-SDK app streams that flow through
  * the legacy path.
+ *
+ * BLE link loss is a SUSPENDED state, not a failure:
+ *   The glasses publisher keeps pushing over Wi-Fi when the phone's Bluetooth
+ *   link drops; only our keep-alives stop reaching it. While the store says
+ *   the glasses are disconnected we pause the heartbeat (so we don't count
+ *   misses we caused ourselves), fan out `suspended`, and give the link
+ *   `glassesGraceMs` to come back. On reconnect we resume, heartbeat at once,
+ *   and fan out `resumed` with the SAME streamId — no re-provision. The grace
+ *   ends early when Cloudflare reports the publisher gone for two probes in
+ *   a row (glasses powered off, not a BLE hiccup). If the grace expires the
+ *   stream is torn down with reason `glasses_disconnected`, and the BLE stop
+ *   the glasses never received is sent on the next reconnect.
  */
 import BluetoothSdk from "@mentra/bluetooth-sdk/internal";
 import { isGlassesConnected } from "./GlassesReadiness";
@@ -49,6 +61,23 @@ const DEFAULT_TIMINGS = {
     hlsReadinessInitialDelayMs: 5_000,
     hlsReadinessPollMs: 2_000,
     hlsReadinessMaxAttempts: 30,
+    // How long a stream survives a BLE link drop before we give up on it. Must
+    // stay under the glasses publisher's own 60s no-keep-alive watchdog with
+    // margin for the resume heartbeat's round trip.
+    glassesGraceMs: 45_000,
+    // Consecutive Cloudflare "publisher disconnected" probes while suspended
+    // before we conclude the glasses are off (not just out of BLE range).
+    suspendedPublisherGoneProbes: 2,
+};
+const storeLinkSource = {
+    isConnected: () => isGlassesConnected(useGlassesStore.getState().connection),
+    subscribe: (listener) => useGlassesStore.subscribe((s) => isGlassesConnected(s.connection), listener),
+};
+/** Reasons carried on coordinator-sourced `stream_status` fanouts for link events. */
+export const LINK_STATUS = {
+    suspended: "suspended",
+    resumed: "resumed",
+    reason: "glasses_disconnected",
 };
 // Console-backed minimal logger; replaces pino on the phone.
 const consoleLogger = {
@@ -78,22 +107,22 @@ export class StreamConflictError extends Error {
         this.name = "StreamConflictError";
     }
 }
-/**
- * Fail fast if glasses aren't connected — BEFORE provisioning. Without this a
- * managed start would create a provider live input, fail the BLE command, and
- * tear the input down again: a slow, billable no-op with a confusing error.
- */
-function assertGlassesConnected() {
-    if (!isGlassesConnected(useGlassesStore.getState().connection)) {
-        throw new StreamConflictError("GLASSES_NOT_CONNECTED", "Glasses are not connected", "command", "ble");
-    }
-}
 export class PhoneStreamCoordinator {
     current = null;
     lifecycle = null;
     statusSubscriber = null;
     idCounter = 0;
     timings;
+    linkSource;
+    unsubscribeLink = null;
+    suspended = null;
+    /**
+     * A stream was torn down while the BLE link was down, so the glasses never
+     * got `stopStream`. Sent on the next reconnect (if no new stream has claimed
+     * the slot) so a publisher that outlived its input does not keep pushing
+     * until its own watchdog fires.
+     */
+    pendingBleStop = null;
     /**
      * Serializes state transitions (start, stop, teardown). Without it, a
      * second `start*` racing with the first can pass the `this.current === null`
@@ -107,8 +136,23 @@ export class PhoneStreamCoordinator {
     lastFanoutSignature = null;
     /** Send full resolvedConfig only once per stream session. */
     resolvedConfigForwarded = false;
-    constructor(timings = {}) {
+    constructor(timings = {}, deps = {}) {
         this.timings = { ...DEFAULT_TIMINGS, ...timings };
+        this.linkSource = deps.linkSource ?? storeLinkSource;
+    }
+    /**
+     * Fail fast if glasses aren't connected — BEFORE provisioning. Without this a
+     * managed start would create a provider live input, fail the BLE command, and
+     * tear the input down again: a slow, billable no-op with a confusing error.
+     */
+    assertGlassesConnected() {
+        if (!this.linkSource.isConnected()) {
+            throw new StreamConflictError("GLASSES_NOT_CONNECTED", "Glasses are not connected", "command", "ble");
+        }
+    }
+    /** True while the active stream is parked on a dropped BLE link. */
+    isSuspended() {
+        return this.suspended !== null;
     }
     /**
      * Run `work` under the transition lock. Each call awaits the previous
@@ -146,7 +190,11 @@ export class PhoneStreamCoordinator {
     /** Report-safe stream ownership snapshot for incident diagnostics. */
     getDiagnosticSnapshot() {
         if (!this.current)
-            return { active: false };
+            return { active: false, pendingBleStop: this.pendingBleStop?.streamId ?? null };
+        const link = {
+            suspended: this.suspended !== null,
+            ...(this.suspended ? { suspendedForMs: Date.now() - this.suspended.since } : {}),
+        };
         return this.current.kind === "managed"
             ? {
                 active: true,
@@ -155,12 +203,14 @@ export class PhoneStreamCoordinator {
                 subscribers: [...this.current.subscribers].sort(),
                 mode: this.current.mode,
                 playbackReady: this.current.hlsReady,
+                ...link,
             }
             : {
                 active: true,
                 kind: this.current.kind,
                 streamId: this.current.streamId,
                 ownerPackageName: this.current.packageName,
+                ...link,
             };
     }
     async startUnmanaged(packageName, opts) {
@@ -169,7 +219,7 @@ export class PhoneStreamCoordinator {
         if (!opts.streamUrl || typeof opts.streamUrl !== "string") {
             throw new StreamConflictError("STREAM_URL_REQUIRED", "streamUrl is required");
         }
-        assertGlassesConnected();
+        this.assertGlassesConnected();
         return this.runExclusive(async () => {
             if (this.current) {
                 throw new StreamConflictError("STREAM_ALREADY_ACTIVE", `A ${this.current.kind} stream is already active. Stop it before starting a new one.`);
@@ -195,6 +245,7 @@ export class PhoneStreamCoordinator {
                     ...(opts.video !== undefined ? { video: opts.video } : {}),
                     ...(opts.audio !== undefined ? { audio: opts.audio } : {}),
                     ...(opts.authToken ? { authToken: opts.authToken } : {}),
+                    ...(typeof opts.captureAudio === "boolean" ? { captureAudio: opts.captureAudio } : {}),
                 });
                 const result = publisherStartResult(streamId, event);
                 this.startLifecycle(streamId);
@@ -219,7 +270,7 @@ export class PhoneStreamCoordinator {
         // Two-phase: the entry-claim runs under the transition lock; the wait for
         // HLS readiness happens AFTER the lock releases so a long warm-up doesn't
         // block subsequent start/stop transitions on this coordinator.
-        assertGlassesConnected();
+        this.assertGlassesConnected();
         const decision = await this.runExclusive(async () => {
             if (this.current && this.current.kind === "unmanaged") {
                 throw new StreamConflictError("STREAM_ALREADY_ACTIVE", "An unmanaged stream is already active. Stop it before starting a managed stream.");
@@ -279,6 +330,7 @@ export class PhoneStreamCoordinator {
                     // See startUnmanaged: the native bridge rejects explicit `undefined`.
                     ...(opts.video !== undefined ? { video: opts.video } : {}),
                     ...(opts.audio !== undefined ? { audio: opts.audio } : {}),
+                    ...(typeof opts.captureAudio === "boolean" ? { captureAudio: opts.captureAudio } : {}),
                 });
                 entry.publisherStart = publisherStartResult(streamId, event);
                 console.info("[STREAM_STARTUP]", {
@@ -396,13 +448,120 @@ export class PhoneStreamCoordinator {
         this.lifecycle?.handleAck(event.ackId);
     }
     // ===========================================================================
+    // BLE link suspension
+    // ===========================================================================
+    attachLink() {
+        if (this.unsubscribeLink)
+            return;
+        this.unsubscribeLink = this.linkSource.subscribe((connected) => this.handleLinkChange(connected));
+    }
+    detachLinkIfIdle() {
+        if (this.current || this.pendingBleStop || !this.unsubscribeLink)
+            return;
+        this.unsubscribeLink();
+        this.unsubscribeLink = null;
+    }
+    handleLinkChange(connected) {
+        if (connected) {
+            if (this.current && this.suspended) {
+                this.resumeLocked();
+            }
+            else if (!this.current && this.pendingBleStop) {
+                this.flushPendingBleStop();
+            }
+            return;
+        }
+        if (this.current && !this.suspended)
+            this.suspend();
+    }
+    suspend() {
+        const entry = this.current;
+        if (!entry)
+            return;
+        const since = Date.now();
+        // Pause the heartbeat: misses now would be our own fault, not the
+        // publisher's, and counting them would reap a stream that is still live.
+        this.lifecycle?.setActive(false);
+        const graceTimer = setTimeout(() => this.onGraceExpired(entry.streamId), this.timings.glassesGraceMs);
+        this.suspended = { since, graceTimer, publisherGoneProbes: 0 };
+        console.warn("[STREAM] BLE link lost; stream suspended", {
+            streamId: entry.streamId,
+            graceMs: this.timings.glassesGraceMs,
+        });
+        this.fanout({
+            streamId: entry.streamId,
+            source: "coordinator",
+            status: LINK_STATUS.suspended,
+            data: { reason: LINK_STATUS.reason, graceMs: this.timings.glassesGraceMs, since },
+        });
+    }
+    resumeLocked() {
+        const entry = this.current;
+        const suspended = this.suspended;
+        if (!entry || !suspended)
+            return;
+        clearTimeout(suspended.graceTimer);
+        this.suspended = null;
+        const suspendedMs = Date.now() - suspended.since;
+        console.info("[STREAM] BLE link back; stream resumed", { streamId: entry.streamId, suspendedMs });
+        // Resume and heartbeat immediately: the glasses watchdog has been running
+        // the whole time, so the first keep-alive must not wait another interval.
+        this.lifecycle?.setActive(true);
+        this.lifecycle?.tickNow();
+        // A resumed session is a fresh status baseline for subscribers.
+        this.lastFanoutSignature = null;
+        this.fanout({
+            streamId: entry.streamId,
+            source: "coordinator",
+            status: LINK_STATUS.resumed,
+            data: { reason: LINK_STATUS.reason, suspendedMs },
+        });
+    }
+    onGraceExpired(streamId) {
+        if (this.current?.streamId !== streamId || !this.suspended)
+            return;
+        this.failSuspended(streamId, "glasses_disconnected", { publisherGone: false });
+    }
+    /**
+     * End a suspended stream. `publisherGone` distinguishes "glasses are off and
+     * Cloudflare confirms nothing is publishing" from "grace ran out with the
+     * publisher possibly still alive" — miniapps word the two differently.
+     */
+    failSuspended(streamId, reason, detail) {
+        this.fanout({
+            streamId,
+            source: "coordinator",
+            status: "error",
+            data: { reason: LINK_STATUS.reason, teardownReason: reason, ...detail },
+        });
+        void this.runExclusive(async () => {
+            if (this.current?.streamId !== streamId)
+                return;
+            await this.teardownLocked(reason);
+        });
+    }
+    flushPendingBleStop() {
+        const pending = this.pendingBleStop;
+        if (!pending)
+            return;
+        this.pendingBleStop = null;
+        console.info("[STREAM] BLE link back; sending deferred stopStream", pending);
+        void BluetoothSdk.stopStream()
+            .catch((err) => console.warn("[STREAM] deferred stopStream failed:", err))
+            .finally(() => this.detachLinkIfIdle());
+    }
+    // ===========================================================================
     // Internal
     // ===========================================================================
     mintId(prefix) {
         this.idCounter += 1;
         return `phone-${prefix}-${Date.now().toString(36)}-${this.idCounter}`;
     }
+    /** BLE keep-alives. StreamLifecycleController uses BgTimer so they survive MentraOS backgrounding. */
     startLifecycle(streamId) {
+        // A new stream supersedes any deferred stop for the previous one.
+        this.pendingBleStop = null;
+        this.attachLink();
         this.lifecycle?.dispose();
         const ctrl = new StreamLifecycleController({
             logger: consoleLogger,
@@ -475,6 +634,21 @@ export class PhoneStreamCoordinator {
                     status: status.isConnected ? "connected" : "disconnected",
                     data: status,
                 });
+                // While the BLE link is down, Cloudflare is the only witness to the
+                // publisher. Two consecutive "nobody is publishing" probes mean the
+                // glasses are off, not merely out of Bluetooth range — stop waiting.
+                if (this.suspended) {
+                    if (status.isConnected) {
+                        this.suspended.publisherGoneProbes = 0;
+                    }
+                    else {
+                        this.suspended.publisherGoneProbes += 1;
+                        if (this.suspended.publisherGoneProbes >= this.timings.suspendedPublisherGoneProbes) {
+                            this.failSuspended(entry.streamId, "glasses_disconnected_publisher_gone", { publisherGone: true });
+                            keepPolling = false;
+                        }
+                    }
+                }
                 // webrtc mode readiness: first "connected" means WHEP playback is
                 // available (WebRTC playback follows the ingest directly; there is no
                 // manifest to probe).
@@ -652,11 +826,25 @@ export class PhoneStreamCoordinator {
         const sendBleStop = options.sendBleStop !== false;
         this.lastFanoutSignature = null;
         this.resolvedConfigForwarded = false;
+        if (this.suspended) {
+            clearTimeout(this.suspended.graceTimer);
+            this.suspended = null;
+        }
         // Dispose the lifecycle controller immediately so it doesn't fire one
         // more keep-alive against a stream we're tearing down. The transition
         // lock guarantees no new lifecycle is started concurrently.
         this.lifecycle?.dispose();
         this.lifecycle = null;
+        // With the link down a BLE write can only fail (and hold the transition
+        // lock for the native timeout). Defer it to the next reconnect instead.
+        const linkUp = this.linkSource.isConnected();
+        if (sendBleStop && !linkUp) {
+            this.pendingBleStop = { streamId: entry.streamId };
+            console.warn("[STREAM] BLE link down during teardown; stopStream deferred", {
+                streamId: entry.streamId,
+                reason,
+            });
+        }
         if (entry.kind === "managed") {
             if (entry.cloudflareTimer)
                 clearTimeout(entry.cloudflareTimer);
@@ -670,7 +858,7 @@ export class PhoneStreamCoordinator {
             entry.hlsReadyRejecters = [];
         }
         try {
-            if (sendBleStop) {
+            if (sendBleStop && linkUp) {
                 await BluetoothSdk.stopStream();
             }
         }
@@ -684,6 +872,7 @@ export class PhoneStreamCoordinator {
             // serializes us, so this should always be true).
             if (this.current === entry)
                 this.current = null;
+            this.detachLinkIfIdle();
             if (entry.kind === "managed") {
                 // Start remote cleanup only after the publisher has stopped, but do not
                 // hold the local transition lock on an unbounded network request. The